refactor: centralize error types for consistent definition shapes

[Hweinstock]

Description

Problem

Error definitions are scattered across 5+ files with no consistent structure. The telemetry error classification relied on error being defined a specific way, but this wasn't always true. Adding a new error required updating multiple files and remembering to register it in classification sets.

Solution

• All error classes now live in src/lib/errors/types.ts
• Every error carries its source ('user' | 'client' | 'service' | 'unknown') as a constructor parameter with a sensible default. Callers can override per throw site.
• The telemetry client reads errorSource and name directly from BaseError instances.
• A small name-based map in src/cli/telemetry/error.ts handles AWS SDK exceptions that bubble up untyped.
• Each error class has its own entry in ErrorName.

Adding a new error (2 steps)

1. Define class in src/lib/errors/types.ts extending BaseError
2. Add its name to ErrorName enum in src/cli/telemetry/schemas/common-shapes.ts

(added to AGENTS.md)

Related Issue

N/A — internal cleanup

Documentation PR

N/A

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe): Error architecture refactoring + telemetry classification simplification

Testing

How have you tested the change?

• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Package Tarball

aws-agentcore-0.13.1.tgz

How to install

npm install https://github.com/aws/agentcore-cli/releases/download/pr-1238-tarball/aws-agentcore-0.13.1.tgz

[agentcore-cli-automation]

Thanks for the cleanup — switching from string matching to instanceof against real classes is a nicer model. However, this PR drops a large number of error categories that are actively thrown in the codebase, which will noticeably degrade telemetry signal in production. Flagging two issues that I think need to be addressed before merging; details inline.

Separately (non-blocking, your call): there's now a semantic inconsistency where AgentAlreadyExistsError is a user error but ConflictError (e.g., "endpoint already exists" thrown from RuntimeEndpointPrimitive) is not, even though they describe the same kind of situation. Worth aligning.

[Hweinstock]

Based on feedback, there is some inconsistency across the codebase for how errors are defined. Going to attempt to centralize this.

[agentcore-cli-automation]

Nice cleanup overall — the BaseError + errorSource model is much clearer than the previous string-name table, and consolidating into one file and one ErrorName enum will make this easier to maintain. Three things I think need to change before merging; details inline.

(The two earlier review comments on error-classification.ts were against a previous version of the PR and have been substantially addressed by the rewrite — most of the missing classes are now in ErrorName, and an SDK fallback map is back in error.ts.)