refactor: centralize error types for consistent definition shapes (#1238)

* refactor: centralize errors with BaseError + errorSource, remove error-classification

- Add BaseError abstract class with errorSource: 'user' | 'client' | 'service'
- All error classes extend BaseError with their source baked in
- Move error classes from 5 scattered files into src/lib/errors/types.ts
- Delete src/lib/errors/config.ts, src/lib/packaging/errors.ts
- Extract Zod formatting helpers into src/lib/errors/zod.ts
- Delete src/cli/telemetry/error-classification.ts entirely
- Extract classifyError into src/cli/telemetry/error.ts
- Classification reads errorSource directly from BaseError instances
- SDK name-based fallback map for AWS exceptions
- Replace is_user_error boolean with error_source enum in telemetry schema
- Preserve PackagingError hierarchy (subclasses extend PackagingError)

* docs: fix BaseError constructor example in AGENTS.md

* fix: align ConflictException SDK mapping to 'user' source

ConflictException/ResourceAlreadyExistsException are user-fixable
conditions (duplicate names, unresolved references), matching the
ConflictError class default.

Author: Hweinstock

AGENTS.md

@@ -148,6 +148,38 @@ See `docs/TESTING.md` for details.
 
 New features must include telemetry instrumentation. See `src/cli/telemetry/README.md` for how to add metrics.
 
+## Error Types
+
+Custom error types are encouraged — each distinct error class appears as its own category in telemetry, giving more
+granular failure data. All errors live in `src/lib/errors/types.ts`.
+
+To add a new error:
+
+1. Define a class in `src/lib/errors/types.ts` extending `BaseError` with a default `errorSource`:
+   - `'user'` — user-fixable (bad input, missing credentials, invalid config)
+   - `'client'` — our bug or unexpected local failure
+   - `'service'` — remote service issue (timeout, connection failure, server error)
+   - `'unknown'` — source cannot be determined
+
+```ts
+export class MyNewError extends BaseError {
+  constructor(message: string, options?: BaseErrorOptions) {
+    super(message, { defaultSource: 'user', ...options });
+  }
+}
+```
+
+Callers can override the source per throw site:
+
+```ts
+throw new MyNewError('not found', { errorSource: 'service', cause: originalErr });
+```
+
+2. Add `'MyNewError'` to the `ErrorName` enum in `src/cli/telemetry/schemas/common-shapes.ts`.
+
+That's it. The telemetry client reads `errorSource` and `name` directly from `BaseError` instances — no classification
+logic to update.
+
 ## Multi-Partition Support (GovCloud, China)
 
 The CLI supports multiple AWS partitions (commercial, GovCloud, China) through a central utility at

src/cli/aws/__tests__/account-extended.test.ts

@@ -1,4 +1,5 @@
-import { AwsCredentialsError, detectAccount, getCredentialProvider, validateAwsCredentials } from '../account.js';
+import { AwsCredentialsError } from '../../../lib/errors/types.js';
+import { detectAccount, getCredentialProvider, validateAwsCredentials } from '../account.js';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const { mockSend } = vi.hoisted(() => ({

src/cli/aws/__tests__/account.test.ts

@@ -1,4 +1,4 @@
-import { AwsCredentialsError } from '../account.js';
+import { AwsCredentialsError } from '../../../lib/errors/types.js';
 import { describe, expect, it } from 'vitest';
 
 describe('AwsCredentialsError', () => {

src/cli/aws/account.ts

@@ -1,3 +1,4 @@
+import { AwsCredentialsError } from '../../lib/errors/types.js';
 import { getAwsLoginGuidance } from '../external-requirements/checks';
 import { GetCallerIdentityCommand, STSClient } from '@aws-sdk/client-sts';
 import { fromEnv, fromNodeProviderChain } from '@aws-sdk/credential-providers';
@@ -13,21 +14,6 @@ export function getCredentialProvider(): AwsCredentialIdentityProvider {
   return hasEnvCreds ? fromEnv() : fromNodeProviderChain();
 }
 
-/**
- * Error thrown when AWS credentials are not configured or invalid.
- * Supports both a short message (for interactive mode) and detailed message (for CLI mode).
- */
-export class AwsCredentialsError extends Error {
-  /** Short message suitable for interactive mode where UI handles recovery */
-  readonly shortMessage: string;
-
-  constructor(shortMessage: string, detailedMessage?: string) {
-    super(detailedMessage ?? shortMessage);
-    this.name = 'AwsCredentialsError';
-    this.shortMessage = shortMessage;
-  }
-}
-
 /**
  * Get AWS account ID using STS GetCallerIdentity with detailed error handling.
  * Throws AwsCredentialsError with helpful messages for common credential issues.

src/cli/commands/import/phase2-import.ts

@@ -1,4 +1,5 @@
-import { PollExhaustedError, PollTimeoutError, isThrottlingError, poll } from '../../../lib/utils/polling';
+import { PollExhaustedError, PollTimeoutError } from '../../../lib/errors/types';
+import { isThrottlingError, poll } from '../../../lib/utils/polling';
 import { getCredentialProvider } from '../../aws/account';
 import type { CfnTemplate } from './template-utils';
 import { buildImportTemplate } from './template-utils';

src/cli/operations/dev/__tests__/invoke-a2a.test.ts

@@ -1,4 +1,4 @@
-import { ServerError } from '../invoke';
+import { ServerError } from '../../../../lib/errors/types';
 import { invokeA2AStreaming } from '../invoke-a2a';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 

src/cli/operations/dev/__tests__/invoke-mcp.test.ts

@@ -1,4 +1,4 @@
-import { ServerError } from '../invoke';
+import { ServerError } from '../../../../lib/errors/types';
 import { callMcpTool, listMcpTools } from '../invoke-mcp';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 

src/cli/operations/dev/index.ts

@@ -11,7 +11,7 @@ export {
 
 export { getDevConfig, getDevSupportedAgents, getAgentPort, loadProjectConfig, type DevConfig } from './config';
 
-export { ConnectionError, ServerError, invokeAgent, invokeAgentStreaming, invokeForProtocol } from './invoke';
+export { invokeAgent, invokeAgentStreaming, invokeForProtocol } from './invoke';
 
 export { invokeA2AStreaming, fetchA2AAgentCard, type A2AAgentCard } from './invoke-a2a';
 

src/cli/operations/dev/invoke-a2a.ts

@@ -1,4 +1,5 @@
-import { ConnectionError, type InvokeStreamingOptions, type SSELogger, ServerError } from './invoke-types';
+import { ConnectionError, ServerError } from '../../../lib/errors/types';
+import { type InvokeStreamingOptions, type SSELogger } from './invoke-types';
 import { isConnectionError, sleep } from './utils';
 import { randomUUID } from 'crypto';
 
@@ -153,7 +154,9 @@ export async function* invokeA2AStreaming(options: InvokeStreamingOptions): Asyn
     }
   }
 
-  const finalError = new ConnectionError(lastError ?? new Error('Failed to connect to A2A server after retries'));
+  const finalError = new ConnectionError(lastError?.message ?? 'Failed to connect to A2A server after retries', {
+    cause: lastError,
+  });
   logger?.log?.('error', `Failed to connect after ${maxRetries} attempts: ${finalError.message}`);
   throw finalError;
 }

src/cli/operations/dev/invoke-agui.ts

@@ -1,6 +1,7 @@
+import { ConnectionError, ServerError } from '../../../lib/errors/types';
 import { parseAguiSSEStream } from '../../aws/agui-parser';
 import { AguiEventType } from '../../aws/agui-types';
-import { ConnectionError, type InvokeStreamingOptions, ServerError } from './invoke-types';
+import { type InvokeStreamingOptions } from './invoke-types';
 import { isConnectionError, sleep } from './utils';
 import { randomUUID } from 'crypto';
 
@@ -147,7 +148,9 @@ export async function* invokeAguiStreaming(options: InvokeStreamingOptions): Asy
     }
   }
 
-  const finalError = new ConnectionError(lastError ?? new Error('Failed to connect to AGUI server after retries'));
+  const finalError = new ConnectionError(lastError?.message ?? 'Failed to connect to AGUI server after retries', {
+    cause: lastError,
+  });
   logger?.log?.('error', `Failed to connect after ${maxRetries} attempts: ${finalError.message}`);
   throw finalError;
 }