recoder-a2a-sdk 1.0.0

package/dist/error-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/error-mapping.ts","../../../shared/src/a2a/schemas/task-envelope.ts","../../../shared/src/a2a/schemas/audit-event.ts","../../../shared/src/a2a/schemas/error-taxonomy.ts"],"sourcesContent":["/**\n * @module error-mapping\n *\n * Error mapping helpers for connector adapters.\n *\n * Each connector may report errors in its own format (HTTP status codes,\n * vendor-specific error objects, raw exceptions). This module provides\n * functions that normalize those heterogeneous error shapes into canonical\n * `A2AError` instances using the error taxonomy from\n * `@recoder/shared/a2a/schemas`.\n *\n * Adapter authors should call these mappers at the boundary where connector\n * errors are caught, so that all upstream logic can operate on a uniform\n * error type.\n *\n * @example\n * ```ts\n * import { mapCodexError, mapClaudeError, mapHttpError } from '@recoder/a2a-sdk/error-mapping';\n *\n * const a2aError = mapCodexError({ type: 'timeout', message: 'Codex timed out' });\n * const httpError = mapHttpError(503, 'Service Unavailable');\n * ```\n */\n\nimport {\n  type A2AError,\n  type A2AErrorCode,\n  A2AErrorCodeEnum,\n  buildA2AError,\n} from '@recoder/shared/a2a/schemas';\n\nimport type { ConnectorPlatform } from './state-mapping';\n\n// ---------------------------------------------------------------------------\n// Codex error mapping\n// ---------------------------------------------------------------------------\n\n/**\n * Shape of an error object emitted by the Codex adapter.\n * This is a normalized representation -- the actual wire format may vary,\n * and adapter code should transform the raw error into this shape before\n * calling `mapCodexError`.\n */\nexport interface CodexErrorInput {\n  /** Codex-specific error type string. */\n  type:\n    | 'timeout'\n    | 'rate_limit'\n    | 'quota_exceeded'\n    | 'auth_error'\n    | 'connection_error'\n    | 'invalid_request'\n    | 'execution_error'\n    | 'model_error'\n    | 'internal_error'\n    | 'cancelled'\n    | string;\n  /** Human-readable error message from Codex. */\n  message: string;\n  /** Optional HTTP status code (if the error originated from an HTTP call). */\n  statusCode?: number;\n  /** Optional raw details from the Codex API response. */\n  details?: Record<string, unknown>;\n  /** Optional trace ID for correlation. */\n  traceId?: string;\n}\n\n/**\n * Map from Codex error type strings to canonical A2A error codes.\n */\nconst CODEX_ERROR_MAP: Readonly<Record<string, A2AErrorCode>> = {\n  timeout: A2AErrorCodeEnum.ConnectorTimeout,\n  rate_limit: A2AErrorCodeEnum.RateLimitExceeded,\n  quota_exceeded: A2AErrorCodeEnum.QuotaExceeded,\n  auth_error: A2AErrorCodeEnum.AuthenticationFailed,\n  connection_error: A2AErrorCodeEnum.NetworkError,\n  invalid_request: A2AErrorCodeEnum.InvalidPayload,\n  execution_error: A2AErrorCodeEnum.TaskExecutionFailed,\n  model_error: A2AErrorCodeEnum.ConnectorError,\n  internal_error: A2AErrorCodeEnum.InternalError,\n  cancelled: A2AErrorCodeEnum.TaskCancelled,\n};\n\n/**\n * Map a Codex adapter error to a canonical `A2AError`.\n *\n * @param input - The normalized Codex error.\n * @returns A canonical `A2AError`.\n */\nexport function mapCodexError(input: CodexErrorInput): A2AError {\n  const code = CODEX_ERROR_MAP[input.type] ?? A2AErrorCodeEnum.ConnectorError;\n  return buildA2AError({\n    code,\n    message: input.message,\n    details: {\n      ...input.details,\n      connector_platform: 'codex' as const,\n      original_error_type: input.type,\n      ...(input.statusCode !== undefined ? { status_code: input.statusCode } : {}),\n    },\n    trace_id: input.traceId,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Claude Code error mapping\n// ---------------------------------------------------------------------------\n\n/**\n * Shape of an error object emitted by the Claude Code adapter.\n */\nexport interface ClaudeErrorInput {\n  /** Claude-specific error type string. */\n  type:\n    | 'overloaded'\n    | 'rate_limit'\n    | 'authentication_error'\n    | 'permission_error'\n    | 'invalid_request'\n    | 'api_error'\n    | 'timeout'\n    | 'connection_error'\n    | 'tool_execution_error'\n    | 'context_length_exceeded'\n    | 'cancelled'\n    | 'aborted'\n    | string;\n  /** Human-readable error message from Claude. */\n  message: string;\n  /** Optional HTTP status code. */\n  statusCode?: number;\n  /** Optional raw details from the Claude API response. */\n  details?: Record<string, unknown>;\n  /** Optional trace ID for correlation. */\n  traceId?: string;\n}\n\n/**\n * Map from Claude Code error type strings to canonical A2A error codes.\n */\nconst CLAUDE_ERROR_MAP: Readonly<Record<string, A2AErrorCode>> = {\n  overloaded: A2AErrorCodeEnum.ConnectorUnavailable,\n  rate_limit: A2AErrorCodeEnum.RateLimitExceeded,\n  authentication_error: A2AErrorCodeEnum.AuthenticationFailed,\n  permission_error: A2AErrorCodeEnum.AuthorizationDenied,\n  invalid_request: A2AErrorCodeEnum.InvalidPayload,\n  api_error: A2AErrorCodeEnum.ConnectorError,\n  timeout: A2AErrorCodeEnum.ConnectorTimeout,\n  connection_error: A2AErrorCodeEnum.NetworkError,\n  tool_execution_error: A2AErrorCodeEnum.TaskExecutionFailed,\n  context_length_exceeded: A2AErrorCodeEnum.QuotaExceeded,\n  cancelled: A2AErrorCodeEnum.TaskCancelled,\n  aborted: A2AErrorCodeEnum.TaskCancelled,\n};\n\n/**\n * Map a Claude Code adapter error to a canonical `A2AError`.\n *\n * @param input - The normalized Claude Code error.\n * @returns A canonical `A2AError`.\n */\nexport function mapClaudeError(input: ClaudeErrorInput): A2AError {\n  const code = CLAUDE_ERROR_MAP[input.type] ?? A2AErrorCodeEnum.ConnectorError;\n  return buildA2AError({\n    code,\n    message: input.message,\n    details: {\n      ...input.details,\n      connector_platform: 'claude_code' as const,\n      original_error_type: input.type,\n      ...(input.statusCode !== undefined ? { status_code: input.statusCode } : {}),\n    },\n    trace_id: input.traceId,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// HTTP error mapping\n// ---------------------------------------------------------------------------\n\n/**\n * Map from common HTTP status codes to canonical A2A error codes.\n */\nconst HTTP_STATUS_MAP: Readonly<Record<number, A2AErrorCode>> = {\n  400: A2AErrorCodeEnum.InvalidPayload,\n  401: A2AErrorCodeEnum.AuthenticationFailed,\n  403: A2AErrorCodeEnum.AuthorizationDenied,\n  404: A2AErrorCodeEnum.ConnectorNotFound,\n  408: A2AErrorCodeEnum.ConnectorTimeout,\n  409: A2AErrorCodeEnum.InvalidStateTransition,\n  422: A2AErrorCodeEnum.InvalidEnvelope,\n  429: A2AErrorCodeEnum.RateLimitExceeded,\n  500: A2AErrorCodeEnum.InternalError,\n  502: A2AErrorCodeEnum.NetworkError,\n  503: A2AErrorCodeEnum.ConnectorUnavailable,\n  504: A2AErrorCodeEnum.ConnectorTimeout,\n};\n\n/**\n * Map an HTTP status code and message to a canonical `A2AError`.\n *\n * Useful for connector adapters that communicate with external services\n * over HTTP/REST and need to normalize HTTP error responses.\n *\n * @param statusCode - The HTTP response status code.\n * @param message - Human-readable error message (e.g. from the response body).\n * @param options - Optional trace ID and additional details.\n * @returns A canonical `A2AError`.\n */\nexport function mapHttpError(\n  statusCode: number,\n  message: string,\n  options?: {\n    traceId?: string;\n    details?: Record<string, unknown>;\n    platform?: ConnectorPlatform;\n  },\n): A2AError {\n  const code = HTTP_STATUS_MAP[statusCode] ?? A2AErrorCodeEnum.UnexpectedStatus;\n  return buildA2AError({\n    code,\n    message,\n    details: {\n      ...options?.details,\n      http_status: statusCode,\n      ...(options?.platform ? { connector_platform: options.platform } : {}),\n    },\n    trace_id: options?.traceId,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Generic connector error mapping\n// ---------------------------------------------------------------------------\n\n/**\n * Generic connector error input that works with any platform.\n */\nexport interface ConnectorErrorInput {\n  /** The connector platform. */\n  platform: ConnectorPlatform;\n  /** Connector-specific error type string. */\n  type: string;\n  /** Human-readable error message. */\n  message: string;\n  /** Optional HTTP status code. */\n  statusCode?: number;\n  /** Optional raw details. */\n  details?: Record<string, unknown>;\n  /** Optional trace ID. */\n  traceId?: string;\n}\n\n/**\n * Map a generic connector error to a canonical `A2AError`, dispatching\n * to the appropriate platform-specific mapper.\n *\n * @param input - The connector error input.\n * @returns A canonical `A2AError`.\n */\nexport function mapConnectorError(input: ConnectorErrorInput): A2AError {\n  switch (input.platform) {\n    case 'codex':\n      return mapCodexError(input);\n    case 'claude_code':\n      return mapClaudeError(input);\n    default:\n      // Fallback: use the HTTP mapper if we have a status code, otherwise generic\n      if (input.statusCode !== undefined) {\n        return mapHttpError(input.statusCode, input.message, {\n          traceId: input.traceId,\n          details: { ...input.details, original_error_type: input.type },\n          platform: input.platform,\n        });\n      }\n      return buildA2AError({\n        code: A2AErrorCodeEnum.ConnectorError,\n        message: input.message,\n        details: {\n          ...input.details,\n          connector_platform: input.platform,\n          original_error_type: input.type,\n        },\n        trace_id: input.traceId,\n      });\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Exception wrapping\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a caught JavaScript Error (or unknown) into a canonical `A2AError`.\n *\n * This is a last-resort mapper for unstructured exceptions that escape\n * the connector adapter. Prefer using the typed mappers above whenever\n * possible.\n *\n * @param err - The caught error.\n * @param options - Optional context: platform, trace ID.\n * @returns A canonical `A2AError`.\n */\nexport function wrapUnknownError(\n  err: unknown,\n  options?: {\n    platform?: ConnectorPlatform;\n    traceId?: string;\n  },\n): A2AError {\n  const message =\n    err instanceof Error ? err.message : typeof err === 'string' ? err : 'Unknown error';\n\n  const details: Record<string, unknown> = {};\n  if (options?.platform) {\n    details.connector_platform = options.platform;\n  }\n  if (err instanceof Error) {\n    details.error_name = err.name;\n    if (err.stack) {\n      details.stack_preview = err.stack.split('\\n').slice(0, 3).join('\\n');\n    }\n  }\n\n  return buildA2AError({\n    code: A2AErrorCodeEnum.InternalError,\n    message,\n    details,\n    trace_id: options?.traceId,\n  });\n}\n","/**\n * @module task-envelope\n *\n * Canonical TaskEnvelope schema for the Recoder A2A control plane.\n *\n * A TaskEnvelope is the top-level wrapper that carries a task through the\n * entire lifecycle -- from submission by a requester agent, through execution\n * by an assignee agent, to terminal completion/failure/cancellation.\n *\n * Every envelope is scoped to a workspace + thread and carries an\n * OpenTelemetry-compatible trace_id so that downstream consumers (audit,\n * observability, billing) can correlate events end-to-end.\n *\n * Consumed by: codex adapter, claude adapter, control-plane orchestrator,\n * audit-log service, billing metering.\n *\n * @example\n * ```ts\n * import type { TaskEnvelope } from '@recoder/shared/a2a/schemas';\n *\n * const envelope: TaskEnvelope = {\n *   envelope_version: TASK_ENVELOPE_VERSION,\n *   id: 'task_01HXYZ',\n *   workspace_id: 'ws_abc',\n *   thread_id: 'thr_def',\n *   trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',\n *   state: TaskStateEnum.Submitted,\n *   connector: { platform: 'codex', protocol: 'jsonrpc', connector_id: 'codex-v1' },\n *   requester: { agent_id: 'agent-pm', platform: 'recoder_pm' },\n *   assignee:  { agent_id: 'agent-codex', platform: 'codex' },\n *   payload: { kind: 'text', text: 'Implement the auth flow' },\n *   created_at: '2026-02-24T10:00:00.000Z',\n *   updated_at: '2026-02-24T10:00:00.000Z',\n * };\n * ```\n */\n\nimport type { RecoderAgentPlatform, RecoderPayload } from '../types';\nimport type { A2AProtocolKind, TaskState as ControlPlaneTaskState } from '../control-plane';\n\n// ---------------------------------------------------------------------------\n// Version\n// ---------------------------------------------------------------------------\n\n/** Current version of the TaskEnvelope schema. */\nexport const TASK_ENVELOPE_VERSION = '1.0.0' as const;\n\n// ---------------------------------------------------------------------------\n// Task State\n// ---------------------------------------------------------------------------\n\n/**\n * Re-export the canonical task state type from the control plane.\n * This ensures a single source of truth for the state union.\n */\nexport type TaskState = ControlPlaneTaskState;\n\n/**\n * Named-access enum for task state values.\n *\n * Lifecycle:\n * ```\n * submitted -> working -> completed\n *                |     -> failed\n *                |     -> cancelled\n *                +---> input-required -> working (loop)\n * ```\n *\n * These values are identical to the `TaskState` union from the control plane,\n * but exposed as a const object for ergonomic named access:\n * ```ts\n * if (envelope.state === TaskStateEnum.Completed) { ... }\n * ```\n */\nexport const TaskStateEnum = {\n  /** Task has been created and is awaiting execution. */\n  Submitted: 'submitted' as const satisfies TaskState,\n  /** Task is actively being processed by the assignee agent. */\n  Working: 'working' as const satisfies TaskState,\n  /** The assignee needs additional input before it can continue. */\n  InputRequired: 'input-required' as const satisfies TaskState,\n  /** Task finished successfully. */\n  Completed: 'completed' as const satisfies TaskState,\n  /** Task terminated with an error. */\n  Failed: 'failed' as const satisfies TaskState,\n  /** Task was explicitly cancelled by a requester or operator. */\n  Cancelled: 'cancelled' as const satisfies TaskState,\n} as const;\n\n/** Ordered list of all task states (useful for validation). */\nexport const TASK_STATES: readonly TaskState[] = [\n  TaskStateEnum.Submitted,\n  TaskStateEnum.Working,\n  TaskStateEnum.InputRequired,\n  TaskStateEnum.Completed,\n  TaskStateEnum.Failed,\n  TaskStateEnum.Cancelled,\n] as const;\n\n/** Set of terminal states -- once a task reaches one of these it cannot transition further. */\nexport const TERMINAL_TASK_STATES: ReadonlySet<TaskState> = new Set<TaskState>([\n  TaskStateEnum.Completed,\n  TaskStateEnum.Failed,\n  TaskStateEnum.Cancelled,\n]);\n\n/**\n * Returns true when the given state is a terminal state.\n *\n * @param state - The task state to check.\n */\nexport function isTerminalState(state: TaskState): boolean {\n  return TERMINAL_TASK_STATES.has(state);\n}\n\n// ---------------------------------------------------------------------------\n// Task State Transition\n// ---------------------------------------------------------------------------\n\n/**\n * A record of a state transition that occurred during the task lifecycle.\n * Stored in `TaskEnvelope.history` to provide a full audit trail of state\n * changes without requiring a separate event query.\n */\nexport interface TaskStateTransition {\n  /** The state the task moved from. */\n  from: TaskState;\n  /** The state the task moved to. */\n  to: TaskState;\n  /** ISO-8601 timestamp of the transition. */\n  transitioned_at: string;\n  /** Optional human/agent-readable reason for the transition. */\n  reason?: string;\n  /** ID of the actor (agent or user) that triggered the transition. */\n  triggered_by?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Connector Info\n// ---------------------------------------------------------------------------\n\n/**\n * Describes which connector/adapter is responsible for executing the task.\n * This links the task to the UACB connector layer (codex adapter, claude\n * adapter, etc.).\n */\nexport interface TaskConnectorInfo {\n  /** The agent platform this connector targets. */\n  platform: RecoderAgentPlatform;\n  /** The wire protocol used by this connector. */\n  protocol: A2AProtocolKind;\n  /** Unique identifier of the connector instance. */\n  connector_id: string;\n  /** Optional human-readable name for the connector. */\n  name?: string;\n  /** Connector-specific metadata (e.g. endpoint URL, model name). */\n  metadata?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Agent Reference\n// ---------------------------------------------------------------------------\n\n/**\n * A lightweight reference to an agent involved in the task.\n * Unlike the full `RecoderAgentIdentity`, this is a minimal pointer suitable\n * for embedding inside envelopes without duplicating the full agent card.\n */\nexport interface TaskAgentRef {\n  /** The agent's unique identifier in the registry. */\n  agent_id: string;\n  /** The platform the agent belongs to. */\n  platform: RecoderAgentPlatform;\n  /** Optional human-readable display name. */\n  name?: string;\n  /** Optional instance identifier when multiple instances of the same agent exist. */\n  instance_id?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Task Result\n// ---------------------------------------------------------------------------\n\n/**\n * The result of a completed (or failed) task.\n * Only present when the task reaches a terminal state.\n */\nexport interface TaskResult {\n  /** Plain text summary of the result. */\n  text?: string;\n  /** Structured data returned by the connector. */\n  data?: Record<string, unknown>;\n  /** Artifacts produced during execution (patches, files, reports). */\n  artifacts?: TaskArtifact[];\n}\n\n/**\n * An artifact produced by a task execution.\n */\nexport interface TaskArtifact {\n  /** A unique key for this artifact within the task. */\n  key: string;\n  /** The type of artifact. */\n  artifact_type: 'patch' | 'file' | 'plan' | 'report' | 'log' | 'custom';\n  /** MIME type of the content. */\n  mime_type: string;\n  /** The artifact content (inline). */\n  content: string;\n  /** Optional file path when the artifact represents a file. */\n  path?: string;\n  /** Optional metadata about the artifact. */\n  metadata?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Policy Snapshot\n// ---------------------------------------------------------------------------\n\n/**\n * A snapshot of the policy decision that was made when the task was submitted.\n * Embedded inside the envelope so that downstream consumers can see what was\n * approved (or denied) without querying the policy plane separately.\n */\nexport interface TaskPolicySnapshot {\n  /** The policy action that was checked (e.g. 'file:write', 'bash:exec'). */\n  action: string;\n  /** Whether the action was approved. */\n  approved: boolean;\n  /** The rule that was applied ('auto', 'prompt', 'deny'). */\n  rule: string;\n  /** Human-readable reason for the decision. */\n  reason: string;\n  /** ISO-8601 timestamp of the policy check. */\n  checked_at: string;\n}\n\n// ---------------------------------------------------------------------------\n// Error Info\n// ---------------------------------------------------------------------------\n\n/**\n * Structured error information attached to a failed task.\n * Uses the canonical error taxonomy defined in `./error-taxonomy.ts`.\n */\nexport interface TaskErrorInfo {\n  /** Machine-readable error code from the taxonomy. */\n  code: string;\n  /** Error category from the taxonomy. */\n  category: string;\n  /** Human-readable error message. */\n  message: string;\n  /** Error severity. */\n  severity: 'low' | 'medium' | 'high' | 'critical';\n  /** Whether the operation can be retried. */\n  retryable: boolean;\n  /** Additional details about the error. */\n  details?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// TaskEnvelope\n// ---------------------------------------------------------------------------\n\n/**\n * The canonical TaskEnvelope -- the top-level schema that wraps every task\n * flowing through the Recoder A2A control plane.\n *\n * Design principles:\n * 1. **Self-describing**: Carries its own version so consumers can handle\n *    schema evolution.\n * 2. **Trace-aware**: Every envelope has a `trace_id` for distributed tracing.\n * 3. **Workspace-scoped**: `workspace_id` + `thread_id` place the task in\n *    the correct organizational context.\n * 4. **Connector-linked**: The `connector` field ties the task to the adapter\n *    that will execute it.\n * 5. **Audit-ready**: `history` and `policy` fields embed enough information\n *    for offline audit without extra lookups.\n */\nexport interface TaskEnvelope {\n  // -- identity ---------------------------------------------------------------\n\n  /** Schema version of this envelope (semver). */\n  envelope_version: string;\n\n  /** Unique task identifier. */\n  id: string;\n\n  // -- scoping ----------------------------------------------------------------\n\n  /**\n   * The workspace this task belongs to.\n   * Maps to the organizational unit (team, project, org) in the Recoder\n   * platform.\n   */\n  workspace_id: string;\n\n  /**\n   * The thread (conversation) this task is part of.\n   * Multiple tasks can belong to the same thread.\n   */\n  thread_id: string;\n\n  /**\n   * Distributed tracing identifier (W3C Trace Context compatible).\n   * All events, audit entries, and side effects produced by this task\n   * should carry this trace_id.\n   */\n  trace_id: string;\n\n  /**\n   * Optional parent span/message ID for nested traces.\n   */\n  parent_id?: string;\n\n  // -- lifecycle --------------------------------------------------------------\n\n  /** Current state of the task. */\n  state: TaskState;\n\n  /** Ordered history of state transitions. */\n  history?: TaskStateTransition[];\n\n  // -- participants -----------------------------------------------------------\n\n  /** The agent or user that requested this task. */\n  requester: TaskAgentRef;\n\n  /** The agent assigned to execute this task. */\n  assignee: TaskAgentRef;\n\n  // -- connector --------------------------------------------------------------\n\n  /** Information about the connector/adapter that handles execution. */\n  connector: TaskConnectorInfo;\n\n  // -- payload ----------------------------------------------------------------\n\n  /**\n   * The task prompt or input payload.\n   * Uses the existing `RecoderPayload` discriminated union so that tasks\n   * can carry text, JSON, commands, or artifact payloads.\n   */\n  payload: RecoderPayload | RecoderPayload[];\n\n  // -- result -----------------------------------------------------------------\n\n  /** The task result, populated when the task reaches a terminal state. */\n  result?: TaskResult;\n\n  /** Error information, populated when state is 'failed'. */\n  error?: TaskErrorInfo;\n\n  // -- policy -----------------------------------------------------------------\n\n  /** Snapshot of policy decisions made for this task. */\n  policy?: TaskPolicySnapshot[];\n\n  // -- timestamps -------------------------------------------------------------\n\n  /** ISO-8601 timestamp of task creation. */\n  created_at: string;\n\n  /** ISO-8601 timestamp of last update. */\n  updated_at: string;\n\n  // -- cost & usage tracking --------------------------------------------------\n\n  /**\n   * Total tokens consumed by this task (prompt + completion).\n   * Populated when the task reaches the `completed` state.\n   */\n  tokensUsed?: number;\n\n  /**\n   * Estimated cost in USD for this task execution.\n   * Populated when the task reaches the `completed` state.\n   */\n  estimatedCostUsd?: number;\n\n  /**\n   * Number of times this task has been retried (re-created after failure).\n   * Starts at 0 and increments each time a retry is attempted.\n   */\n  retryCount?: number;\n\n  // -- extensibility ----------------------------------------------------------\n\n  /** Arbitrary metadata for connector-specific or consumer-specific data. */\n  metadata?: Record<string, unknown>;\n\n  /**\n   * Tags for categorization and filtering.\n   * Examples: ['priority:high', 'team:backend', 'sprint:42']\n   */\n  tags?: string[];\n}\n\n// ---------------------------------------------------------------------------\n// Factory helper\n// ---------------------------------------------------------------------------\n\n/**\n * Input for creating a new TaskEnvelope.\n * Fields that can be auto-populated (timestamps, version, initial state) are\n * optional.\n */\nexport interface CreateTaskEnvelopeInput {\n  id: string;\n  workspace_id: string;\n  thread_id: string;\n  trace_id: string;\n  parent_id?: string;\n  requester: TaskAgentRef;\n  assignee: TaskAgentRef;\n  connector: TaskConnectorInfo;\n  payload: RecoderPayload | RecoderPayload[];\n  metadata?: Record<string, unknown>;\n  tags?: string[];\n  /** Override the initial state (defaults to 'submitted'). */\n  initial_state?: TaskState;\n  /** Override the creation timestamp (defaults to now). */\n  now?: string;\n}\n\n/**\n * Create a new `TaskEnvelope` in the `submitted` state with sensible\n * defaults for version, timestamps, and empty history.\n *\n * @param input - The required fields for envelope creation.\n * @returns A fully populated `TaskEnvelope`.\n */\nexport function createTaskEnvelope(input: CreateTaskEnvelopeInput): TaskEnvelope {\n  const now = input.now ?? new Date().toISOString();\n  return {\n    envelope_version: TASK_ENVELOPE_VERSION,\n    id: input.id,\n    workspace_id: input.workspace_id,\n    thread_id: input.thread_id,\n    trace_id: input.trace_id,\n    parent_id: input.parent_id,\n    state: input.initial_state ?? TaskStateEnum.Submitted,\n    history: [],\n    requester: input.requester,\n    assignee: input.assignee,\n    connector: input.connector,\n    payload: input.payload,\n    created_at: now,\n    updated_at: now,\n    metadata: input.metadata,\n    tags: input.tags,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// State transition helper\n// ---------------------------------------------------------------------------\n\n/**\n * Allowed state transitions. Maps each state to the set of states it can\n * move to. Any transition not in this map is invalid.\n */\nexport const ALLOWED_STATE_TRANSITIONS: Readonly<Record<TaskState, readonly TaskState[]>> = {\n  [TaskStateEnum.Submitted]: [TaskStateEnum.Working, TaskStateEnum.Cancelled, TaskStateEnum.Failed],\n  [TaskStateEnum.Working]: [\n    TaskStateEnum.Completed,\n    TaskStateEnum.Failed,\n    TaskStateEnum.Cancelled,\n    TaskStateEnum.InputRequired,\n  ],\n  [TaskStateEnum.InputRequired]: [TaskStateEnum.Working, TaskStateEnum.Cancelled, TaskStateEnum.Failed],\n  [TaskStateEnum.Completed]: [],\n  [TaskStateEnum.Failed]: [],\n  [TaskStateEnum.Cancelled]: [],\n};\n\n/**\n * Check whether a state transition is valid according to the lifecycle rules.\n *\n * @param from - The current state.\n * @param to - The desired next state.\n * @returns `true` if the transition is allowed.\n */\nexport function isValidTransition(from: TaskState, to: TaskState): boolean {\n  return (ALLOWED_STATE_TRANSITIONS[from] ?? []).includes(to);\n}\n\n/**\n * Apply a state transition to an envelope, returning a new envelope with\n * the updated state and an appended history entry. Throws if the transition\n * is not allowed.\n *\n * @param envelope - The current envelope.\n * @param to - The target state.\n * @param options - Optional reason and actor for the transition.\n * @returns A new `TaskEnvelope` with the transition applied.\n */\nexport function transitionTaskEnvelope(\n  envelope: TaskEnvelope,\n  to: TaskState,\n  options?: { reason?: string; triggered_by?: string; now?: string }\n): TaskEnvelope {\n  if (!isValidTransition(envelope.state, to)) {\n    throw new Error(\n      `Invalid task state transition: ${envelope.state} -> ${to} (task ${envelope.id})`\n    );\n  }\n\n  const now = options?.now ?? new Date().toISOString();\n  const transition: TaskStateTransition = {\n    from: envelope.state,\n    to,\n    transitioned_at: now,\n    reason: options?.reason,\n    triggered_by: options?.triggered_by,\n  };\n\n  return {\n    ...envelope,\n    state: to,\n    updated_at: now,\n    history: [...(envelope.history ?? []), transition],\n  };\n}\n","/**\n * @module audit-event\n *\n * Canonical AuditEvent schema for the Recoder A2A control plane.\n *\n * An AuditEvent is an immutable record of something that happened within the\n * system. Events are produced by connectors, the policy plane, the task\n * orchestrator, and the collaboration service. They feed into the audit-log\n * service and downstream analytics/compliance pipelines.\n *\n * Every event carries a `trace_id` that links it to the originating\n * `TaskEnvelope`, enabling full causal reconstruction of any workflow.\n *\n * Consumed by: audit-log service, analytics pipeline, compliance dashboards,\n * billing metering, alerting/monitoring.\n *\n * @example\n * ```ts\n * import type { AuditEvent } from '@recoder/shared/a2a/schemas';\n * import { AuditEventTypeEnum, AuditActorKindEnum } from '@recoder/shared/a2a/schemas';\n *\n * const event: AuditEvent = {\n *   schema_version: AUDIT_EVENT_VERSION,\n *   id: 'evt_01HXYZ',\n *   event_type: AuditEventTypeEnum.TaskSubmitted,\n *   actor: {\n *     kind: AuditActorKindEnum.Agent,\n *     id: 'agent-pm',\n *     platform: 'recoder_pm',\n *   },\n *   target: {\n *     kind: 'task',\n *     id: 'task_01HXYZ',\n *   },\n *   trace_id: '4bf92f3577b34da6a3ce929d0e0e4736',\n *   workspace_id: 'ws_abc',\n *   thread_id: 'thr_def',\n *   timestamp: '2026-02-24T10:00:00.000Z',\n * };\n * ```\n */\n\nimport type { RecoderAgentPlatform } from '../types';\n\n// ---------------------------------------------------------------------------\n// Version\n// ---------------------------------------------------------------------------\n\n/** Current version of the AuditEvent schema. */\nexport const AUDIT_EVENT_VERSION = '1.0.0' as const;\n\n// ---------------------------------------------------------------------------\n// Event types\n// ---------------------------------------------------------------------------\n\n/**\n * Canonical audit event types covering the full lifecycle of tasks,\n * policy decisions, connector activity, collaboration actions, and\n * system-level events.\n */\nexport const AuditEventTypeEnum = {\n  // -- task lifecycle ---------------------------------------------------------\n  /** A new task was submitted. */\n  TaskSubmitted: 'task.submitted',\n  /** Task execution started. */\n  TaskStarted: 'task.started',\n  /** Task made progress (intermediate update). */\n  TaskProgress: 'task.progress',\n  /** Assignee agent needs additional input. */\n  TaskInputRequired: 'task.input_required',\n  /** Task completed successfully. */\n  TaskCompleted: 'task.completed',\n  /** Task failed with an error. */\n  TaskFailed: 'task.failed',\n  /** Task was cancelled. */\n  TaskCancelled: 'task.cancelled',\n\n  // -- policy decisions -------------------------------------------------------\n  /** A policy check was performed. */\n  PolicyChecked: 'policy.checked',\n  /** A policy action was approved (auto or prompt). */\n  PolicyApproved: 'policy.approved',\n  /** A policy action was denied. */\n  PolicyDenied: 'policy.denied',\n\n  // -- connector events -------------------------------------------------------\n  /** A connector was attached to an agent. */\n  ConnectorAttached: 'connector.attached',\n  /** A connector was detached from an agent. */\n  ConnectorDetached: 'connector.detached',\n  /** A connector emitted a diagnostic or health event. */\n  ConnectorHealth: 'connector.health',\n  /** A connector encountered an error. */\n  ConnectorError: 'connector.error',\n\n  // -- agent registry ---------------------------------------------------------\n  /** An agent was registered. */\n  AgentRegistered: 'agent.registered',\n  /** An agent was unregistered. */\n  AgentUnregistered: 'agent.unregistered',\n  /** An agent's capabilities were updated. */\n  AgentUpdated: 'agent.updated',\n\n  // -- collaboration ----------------------------------------------------------\n  /** A collaboration channel was created. */\n  ChannelCreated: 'collaboration.channel_created',\n  /** A collaboration thread was created. */\n  ThreadCreated: 'collaboration.thread_created',\n  /** A message was sent in a collaboration thread. */\n  MessageSent: 'collaboration.message_sent',\n\n  // -- system -----------------------------------------------------------------\n  /** A system-level configuration change. */\n  SystemConfig: 'system.config',\n  /** A system-level error or warning. */\n  SystemError: 'system.error',\n} as const;\n\n/** Union of all valid audit event type string values. */\nexport type AuditEventType = (typeof AuditEventTypeEnum)[keyof typeof AuditEventTypeEnum];\n\n/** Ordered list of all event types (useful for validation / UI dropdowns). */\nexport const AUDIT_EVENT_TYPES: readonly AuditEventType[] = Object.values(AuditEventTypeEnum);\n\n// ---------------------------------------------------------------------------\n// Actor\n// ---------------------------------------------------------------------------\n\n/**\n * The kinds of actors that can produce audit events.\n */\nexport const AuditActorKindEnum = {\n  /** An AI agent. */\n  Agent: 'agent',\n  /** A human user. */\n  User: 'user',\n  /** An internal system service (e.g. policy engine, scheduler). */\n  System: 'system',\n  /** A connector/adapter. */\n  Connector: 'connector',\n} as const;\n\n/** Union of all valid actor kind string values. */\nexport type AuditActorKind = (typeof AuditActorKindEnum)[keyof typeof AuditActorKindEnum];\n\n/**\n * Identifies who (or what) caused the audit event.\n */\nexport interface AuditActor {\n  /** The kind of actor. */\n  kind: AuditActorKind;\n\n  /** Unique identifier of the actor. */\n  id: string;\n\n  /** Optional human-readable display name. */\n  name?: string;\n\n  /** Platform the actor belongs to (for agents/connectors). */\n  platform?: RecoderAgentPlatform;\n\n  /** Additional actor metadata. */\n  metadata?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Target\n// ---------------------------------------------------------------------------\n\n/**\n * The kinds of resources that can be the target of an audit event.\n */\nexport const AuditTargetKindEnum = {\n  Task: 'task',\n  Agent: 'agent',\n  Connector: 'connector',\n  Channel: 'channel',\n  Thread: 'thread',\n  Message: 'message',\n  Policy: 'policy',\n  Workspace: 'workspace',\n  System: 'system',\n} as const;\n\n/** Union of all valid target kind string values. */\nexport type AuditTargetKind = (typeof AuditTargetKindEnum)[keyof typeof AuditTargetKindEnum];\n\n/**\n * Identifies the resource that was affected by the audit event.\n */\nexport interface AuditTarget {\n  /** The kind of resource. */\n  kind: AuditTargetKind;\n\n  /** Unique identifier of the target resource. */\n  id: string;\n\n  /** Optional human-readable display name. */\n  name?: string;\n\n  /** Additional target metadata. */\n  metadata?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Policy Context\n// ---------------------------------------------------------------------------\n\n/**\n * When an audit event is related to a policy decision, this carries the\n * full context of what was checked and what the outcome was.\n */\nexport interface AuditPolicyContext {\n  /** The policy action that was evaluated (e.g. 'file:write', 'bash:exec'). */\n  action: string;\n\n  /** The rule that was applied ('auto', 'prompt', 'deny'). */\n  rule: string;\n\n  /** Whether the action was approved. */\n  approved: boolean;\n\n  /** Human-readable reason for the decision. */\n  reason: string;\n\n  /** The agent ID the policy was checked against. */\n  agent_id: string;\n\n  /** Additional policy evaluation details. */\n  details?: Record<string, unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Severity\n// ---------------------------------------------------------------------------\n\n/**\n * Severity levels for audit events, following standard log severity.\n */\nexport const AuditSeverityEnum = {\n  /** Informational -- normal operation. */\n  Info: 'info',\n  /** Warning -- something unexpected but not an error. */\n  Warning: 'warning',\n  /** Error -- an operation failed. */\n  Error: 'error',\n  /** Critical -- a severe failure requiring immediate attention. */\n  Critical: 'critical',\n} as const;\n\n/** Union of all valid severity string values. */\nexport type AuditSeverity = (typeof AuditSeverityEnum)[keyof typeof AuditSeverityEnum];\n\n// ---------------------------------------------------------------------------\n// AuditEvent\n// ---------------------------------------------------------------------------\n\n/**\n * The canonical AuditEvent -- an immutable record of an action or state\n * change within the Recoder A2A system.\n *\n * Design principles:\n * 1. **Immutable**: Once created, an audit event is never modified.\n * 2. **Trace-linked**: `trace_id` connects every event to its causal chain.\n * 3. **Self-describing**: Carries its own schema version for evolution.\n * 4. **Workspace-scoped**: `workspace_id` enables multi-tenant audit queries.\n * 5. **Actor-target model**: Every event answers \"who did what to whom\".\n * 6. **Policy-aware**: When a policy was involved, the full decision context\n *    is embedded directly in the event.\n */\nexport interface AuditEvent {\n  // -- identity ---------------------------------------------------------------\n\n  /** Schema version of this audit event (semver). */\n  schema_version: string;\n\n  /** Unique event identifier. */\n  id: string;\n\n  // -- classification ---------------------------------------------------------\n\n  /** The type of event (from the canonical event type enum). */\n  event_type: AuditEventType;\n\n  /** Severity of the event. Defaults to 'info' if not set. */\n  severity?: AuditSeverity;\n\n  // -- participants -----------------------------------------------------------\n\n  /** The actor that caused this event. */\n  actor: AuditActor;\n\n  /** The resource that was affected by this event. */\n  target: AuditTarget;\n\n  // -- tracing ----------------------------------------------------------------\n\n  /**\n   * Distributed tracing identifier (W3C Trace Context compatible).\n   * Links this event to the originating TaskEnvelope and all related events.\n   */\n  trace_id: string;\n\n  /**\n   * Optional parent event or span ID for nested event hierarchies.\n   */\n  parent_event_id?: string;\n\n  // -- scoping ----------------------------------------------------------------\n\n  /**\n   * The workspace this event belongs to.\n   */\n  workspace_id: string;\n\n  /**\n   * The thread (conversation) this event is associated with, if any.\n   */\n  thread_id?: string;\n\n  /**\n   * The task this event is associated with, if any.\n   */\n  task_id?: string;\n\n  // -- timing -----------------------------------------------------------------\n\n  /** ISO-8601 timestamp of when the event occurred. */\n  timestamp: string;\n\n  /**\n   * Duration in milliseconds, if the event represents a timed operation\n   * (e.g. task execution, policy check).\n   */\n  duration_ms?: number;\n\n  // -- policy -----------------------------------------------------------------\n\n  /**\n   * Policy context, present when the event involves a policy decision.\n   */\n  policy?: AuditPolicyContext;\n\n  // -- extensibility ----------------------------------------------------------\n\n  /** Arbitrary metadata for event-specific details. */\n  metadata?: Record<string, unknown>;\n\n  /**\n   * Tags for categorization and filtering.\n   * Examples: ['connector:codex', 'severity:high', 'team:backend']\n   */\n  tags?: string[];\n}\n\n// ---------------------------------------------------------------------------\n// Factory helper\n// ---------------------------------------------------------------------------\n\n/**\n * Input for creating a new AuditEvent.\n * Fields that can be auto-populated (schema_version, timestamp) are optional.\n */\nexport interface CreateAuditEventInput {\n  id: string;\n  event_type: AuditEventType;\n  actor: AuditActor;\n  target: AuditTarget;\n  trace_id: string;\n  workspace_id: string;\n  thread_id?: string;\n  task_id?: string;\n  parent_event_id?: string;\n  severity?: AuditSeverity;\n  policy?: AuditPolicyContext;\n  metadata?: Record<string, unknown>;\n  tags?: string[];\n  duration_ms?: number;\n  /** Override the timestamp (defaults to now). */\n  now?: string;\n}\n\n/**\n * Create a new `AuditEvent` with sensible defaults for version and timestamp.\n *\n * @param input - The required fields for event creation.\n * @returns A fully populated `AuditEvent`.\n */\nexport function createAuditEvent(input: CreateAuditEventInput): AuditEvent {\n  return {\n    schema_version: AUDIT_EVENT_VERSION,\n    id: input.id,\n    event_type: input.event_type,\n    severity: input.severity,\n    actor: input.actor,\n    target: input.target,\n    trace_id: input.trace_id,\n    parent_event_id: input.parent_event_id,\n    workspace_id: input.workspace_id,\n    thread_id: input.thread_id,\n    task_id: input.task_id,\n    timestamp: input.now ?? new Date().toISOString(),\n    duration_ms: input.duration_ms,\n    policy: input.policy,\n    metadata: input.metadata,\n    tags: input.tags,\n  };\n}\n","/**\n * @module error-taxonomy\n *\n * Canonical error taxonomy for the Recoder A2A system.\n *\n * This module defines a deterministic set of error categories, codes, and\n * severity levels that every connector, service, and adapter in the system\n * must use when reporting errors. Having a single taxonomy ensures that:\n *\n * 1. Error codes are unique and greppable across the entire codebase.\n * 2. Consumers (UI, alerting, billing) can switch on `category` + `code`\n *    without brittle string matching.\n * 3. Retry logic can be driven by the `retryable` flag.\n * 4. Severity-based routing (PagerDuty, Slack, silent log) is consistent.\n *\n * Consumed by: all connectors, control-plane orchestrator, error-contract\n * module, UI error renderers.\n *\n * @example\n * ```ts\n * import {\n *   A2AErrorCategoryEnum,\n *   A2AErrorCodeEnum,\n *   buildA2AError,\n * } from '@recoder/shared/a2a/schemas';\n *\n * const error = buildA2AError({\n *   code: A2AErrorCodeEnum.ConnectorTimeout,\n *   message: 'Codex adapter timed out after 30s',\n * });\n * // => { code: 'CONNECTOR_TIMEOUT', category: 'connector', severity: 'high', ... }\n * ```\n */\n\n// ---------------------------------------------------------------------------\n// Error severity\n// ---------------------------------------------------------------------------\n\n/**\n * Severity levels for A2A errors, mirroring the audit severity for\n * consistency.\n */\nexport const A2AErrorSeverityEnum = {\n  /** Low impact -- informational or gracefully handled. */\n  Low: 'low',\n  /** Medium impact -- degraded functionality but system continues. */\n  Medium: 'medium',\n  /** High impact -- a key operation failed and needs attention. */\n  High: 'high',\n  /** Critical -- system stability at risk, immediate action required. */\n  Critical: 'critical',\n} as const;\n\n/** Union of all valid error severity string values. */\nexport type A2AErrorSeverity = (typeof A2AErrorSeverityEnum)[keyof typeof A2AErrorSeverityEnum];\n\n// ---------------------------------------------------------------------------\n// Error categories\n// ---------------------------------------------------------------------------\n\n/**\n * Top-level error categories. Every error code belongs to exactly one\n * category.\n */\nexport const A2AErrorCategoryEnum = {\n  /** Errors in the envelope or message format (validation, parsing). */\n  Envelope: 'envelope',\n  /** Errors in the connector/adapter layer. */\n  Connector: 'connector',\n  /** Errors in the policy/approval plane. */\n  Policy: 'policy',\n  /** Errors in the task orchestration layer. */\n  Task: 'task',\n  /** Errors in the agent registry. */\n  Registry: 'registry',\n  /** Errors in the collaboration service. */\n  Collaboration: 'collaboration',\n  /** Transport/network-level errors. */\n  Transport: 'transport',\n  /** Authentication and authorization errors. */\n  Auth: 'auth',\n  /** Rate-limiting and quota errors. */\n  RateLimit: 'rate_limit',\n  /** Internal / unexpected errors. */\n  Internal: 'internal',\n} as const;\n\n/** Union of all valid error category string values. */\nexport type A2AErrorCategory = (typeof A2AErrorCategoryEnum)[keyof typeof A2AErrorCategoryEnum];\n\n// ---------------------------------------------------------------------------\n// Error codes\n// ---------------------------------------------------------------------------\n\n/**\n * Exhaustive list of machine-readable error codes.\n * Convention: UPPER_SNAKE_CASE, prefixed implicitly by category context.\n */\nexport const A2AErrorCodeEnum = {\n  // -- envelope ---------------------------------------------------------------\n  /** The envelope failed structural validation. */\n  InvalidEnvelope: 'INVALID_ENVELOPE',\n  /** The envelope version is unsupported. */\n  UnsupportedEnvelopeVersion: 'UNSUPPORTED_ENVELOPE_VERSION',\n  /** A required field is missing from the envelope. */\n  MissingEnvelopeField: 'MISSING_ENVELOPE_FIELD',\n  /** The payload kind is unknown or malformed. */\n  InvalidPayload: 'INVALID_PAYLOAD',\n  /** Compatibility alias used by older gateway/workspace routes. */\n  InvalidParams: 'INVALID_ENVELOPE',\n\n  // -- connector --------------------------------------------------------------\n  /** No connector is attached for the target agent. */\n  ConnectorNotFound: 'CONNECTOR_NOT_FOUND',\n  /** The connector timed out during task execution. */\n  ConnectorTimeout: 'CONNECTOR_TIMEOUT',\n  /** The connector returned an unexpected error. */\n  ConnectorError: 'CONNECTOR_ERROR',\n  /** The connector is temporarily unavailable. */\n  ConnectorUnavailable: 'CONNECTOR_UNAVAILABLE',\n  /** Protocol mismatch between connector and remote agent. */\n  ProtocolMismatch: 'PROTOCOL_MISMATCH',\n\n  // -- policy -----------------------------------------------------------------\n  /** The policy plane denied the requested action. */\n  PolicyDenied: 'POLICY_DENIED',\n  /** No prompt handler is configured for the policy rule. */\n  PolicyHandlerMissing: 'POLICY_HANDLER_MISSING',\n  /** The policy evaluation timed out. */\n  PolicyTimeout: 'POLICY_TIMEOUT',\n\n  // -- task -------------------------------------------------------------------\n  /** The task was not found. */\n  TaskNotFound: 'TASK_NOT_FOUND',\n  /** An invalid state transition was attempted. */\n  InvalidStateTransition: 'INVALID_STATE_TRANSITION',\n  /** The task has already reached a terminal state. */\n  TaskAlreadyTerminal: 'TASK_ALREADY_TERMINAL',\n  /** The task failed during execution. */\n  TaskExecutionFailed: 'TASK_EXECUTION_FAILED',\n  /** The task was cancelled. */\n  TaskCancelled: 'TASK_CANCELLED',\n\n  // -- registry ---------------------------------------------------------------\n  /** The agent was not found in the registry. */\n  AgentNotFound: 'AGENT_NOT_FOUND',\n  /** The agent is already registered. */\n  AgentAlreadyRegistered: 'AGENT_ALREADY_REGISTERED',\n  /** The agent does not have the requested capability. */\n  CapabilityNotFound: 'CAPABILITY_NOT_FOUND',\n\n  // -- collaboration ----------------------------------------------------------\n  /** The channel was not found. */\n  ChannelNotFound: 'CHANNEL_NOT_FOUND',\n  /** The thread was not found. */\n  ThreadNotFound: 'THREAD_NOT_FOUND',\n  /** The message was not found. */\n  MessageNotFound: 'MESSAGE_NOT_FOUND',\n  /** The sender is not a member of the target channel. */\n  NotChannelMember: 'NOT_CHANNEL_MEMBER',\n\n  // -- transport --------------------------------------------------------------\n  /** A network request failed. */\n  NetworkError: 'NETWORK_ERROR',\n  /** The remote endpoint returned an unexpected status. */\n  UnexpectedStatus: 'UNEXPECTED_STATUS',\n  /** The request or response body could not be parsed. */\n  SerializationError: 'SERIALIZATION_ERROR',\n\n  // -- auth -------------------------------------------------------------------\n  /** Authentication failed (invalid or missing credentials). */\n  AuthenticationFailed: 'AUTHENTICATION_FAILED',\n  /** The caller is not authorized for the requested operation. */\n  AuthorizationDenied: 'AUTHORIZATION_DENIED',\n  /** The access token has expired. */\n  TokenExpired: 'TOKEN_EXPIRED',\n\n  // -- rate limit -------------------------------------------------------------\n  /** The caller has exceeded the rate limit. */\n  RateLimitExceeded: 'RATE_LIMIT_EXCEEDED',\n  /** The caller has exceeded their usage quota. */\n  QuotaExceeded: 'QUOTA_EXCEEDED',\n\n  // -- internal ---------------------------------------------------------------\n  /** An unexpected internal error occurred. */\n  InternalError: 'INTERNAL_ERROR',\n  /** A configuration error was detected. */\n  ConfigurationError: 'CONFIGURATION_ERROR',\n} as const;\n\n/** Union of all valid error code string values. */\nexport type A2AErrorCode = (typeof A2AErrorCodeEnum)[keyof typeof A2AErrorCodeEnum];\n\n// ---------------------------------------------------------------------------\n// Error code metadata\n// ---------------------------------------------------------------------------\n\n/**\n * Metadata associated with each error code, providing default severity,\n * category, retryable flag, and a human-readable description.\n */\nexport interface A2AErrorCodeMeta {\n  /** The error code. */\n  code: A2AErrorCode;\n  /** The category this code belongs to. */\n  category: A2AErrorCategory;\n  /** Default severity for this error. */\n  severity: A2AErrorSeverity;\n  /** Whether operations that hit this error can be retried. */\n  retryable: boolean;\n  /** Short human-readable description. */\n  description: string;\n}\n\n/**\n * Registry mapping every error code to its metadata.\n * This is the single source of truth for error classification.\n */\nexport const A2A_ERROR_CODE_REGISTRY: Readonly<Record<A2AErrorCode, A2AErrorCodeMeta>> = {\n  // envelope\n  [A2AErrorCodeEnum.InvalidEnvelope]: {\n    code: A2AErrorCodeEnum.InvalidEnvelope,\n    category: A2AErrorCategoryEnum.Envelope,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The envelope failed structural validation.',\n  },\n  [A2AErrorCodeEnum.UnsupportedEnvelopeVersion]: {\n    code: A2AErrorCodeEnum.UnsupportedEnvelopeVersion,\n    category: A2AErrorCategoryEnum.Envelope,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The envelope version is not supported by this service.',\n  },\n  [A2AErrorCodeEnum.MissingEnvelopeField]: {\n    code: A2AErrorCodeEnum.MissingEnvelopeField,\n    category: A2AErrorCategoryEnum.Envelope,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'A required field is missing from the envelope.',\n  },\n  [A2AErrorCodeEnum.InvalidPayload]: {\n    code: A2AErrorCodeEnum.InvalidPayload,\n    category: A2AErrorCategoryEnum.Envelope,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The payload kind is unknown or malformed.',\n  },\n\n  // connector\n  [A2AErrorCodeEnum.ConnectorNotFound]: {\n    code: A2AErrorCodeEnum.ConnectorNotFound,\n    category: A2AErrorCategoryEnum.Connector,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: false,\n    description: 'No connector is attached for the target agent.',\n  },\n  [A2AErrorCodeEnum.ConnectorTimeout]: {\n    code: A2AErrorCodeEnum.ConnectorTimeout,\n    category: A2AErrorCategoryEnum.Connector,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: true,\n    description: 'The connector timed out during task execution.',\n  },\n  [A2AErrorCodeEnum.ConnectorError]: {\n    code: A2AErrorCodeEnum.ConnectorError,\n    category: A2AErrorCategoryEnum.Connector,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: true,\n    description: 'The connector returned an unexpected error.',\n  },\n  [A2AErrorCodeEnum.ConnectorUnavailable]: {\n    code: A2AErrorCodeEnum.ConnectorUnavailable,\n    category: A2AErrorCategoryEnum.Connector,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: true,\n    description: 'The connector is temporarily unavailable.',\n  },\n  [A2AErrorCodeEnum.ProtocolMismatch]: {\n    code: A2AErrorCodeEnum.ProtocolMismatch,\n    category: A2AErrorCategoryEnum.Connector,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: false,\n    description: 'Protocol mismatch between connector and remote agent.',\n  },\n\n  // policy\n  [A2AErrorCodeEnum.PolicyDenied]: {\n    code: A2AErrorCodeEnum.PolicyDenied,\n    category: A2AErrorCategoryEnum.Policy,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The policy plane denied the requested action.',\n  },\n  [A2AErrorCodeEnum.PolicyHandlerMissing]: {\n    code: A2AErrorCodeEnum.PolicyHandlerMissing,\n    category: A2AErrorCategoryEnum.Policy,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'No prompt handler is configured for the policy rule.',\n  },\n  [A2AErrorCodeEnum.PolicyTimeout]: {\n    code: A2AErrorCodeEnum.PolicyTimeout,\n    category: A2AErrorCategoryEnum.Policy,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: true,\n    description: 'The policy evaluation timed out.',\n  },\n\n  // task\n  [A2AErrorCodeEnum.TaskNotFound]: {\n    code: A2AErrorCodeEnum.TaskNotFound,\n    category: A2AErrorCategoryEnum.Task,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The task was not found.',\n  },\n  [A2AErrorCodeEnum.InvalidStateTransition]: {\n    code: A2AErrorCodeEnum.InvalidStateTransition,\n    category: A2AErrorCategoryEnum.Task,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'An invalid state transition was attempted.',\n  },\n  [A2AErrorCodeEnum.TaskAlreadyTerminal]: {\n    code: A2AErrorCodeEnum.TaskAlreadyTerminal,\n    category: A2AErrorCategoryEnum.Task,\n    severity: A2AErrorSeverityEnum.Low,\n    retryable: false,\n    description: 'The task has already reached a terminal state.',\n  },\n  [A2AErrorCodeEnum.TaskExecutionFailed]: {\n    code: A2AErrorCodeEnum.TaskExecutionFailed,\n    category: A2AErrorCategoryEnum.Task,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: true,\n    description: 'The task failed during execution.',\n  },\n  [A2AErrorCodeEnum.TaskCancelled]: {\n    code: A2AErrorCodeEnum.TaskCancelled,\n    category: A2AErrorCategoryEnum.Task,\n    severity: A2AErrorSeverityEnum.Low,\n    retryable: false,\n    description: 'The task was cancelled.',\n  },\n\n  // registry\n  [A2AErrorCodeEnum.AgentNotFound]: {\n    code: A2AErrorCodeEnum.AgentNotFound,\n    category: A2AErrorCategoryEnum.Registry,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The agent was not found in the registry.',\n  },\n  [A2AErrorCodeEnum.AgentAlreadyRegistered]: {\n    code: A2AErrorCodeEnum.AgentAlreadyRegistered,\n    category: A2AErrorCategoryEnum.Registry,\n    severity: A2AErrorSeverityEnum.Low,\n    retryable: false,\n    description: 'The agent is already registered.',\n  },\n  [A2AErrorCodeEnum.CapabilityNotFound]: {\n    code: A2AErrorCodeEnum.CapabilityNotFound,\n    category: A2AErrorCategoryEnum.Registry,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The agent does not have the requested capability.',\n  },\n\n  // collaboration\n  [A2AErrorCodeEnum.ChannelNotFound]: {\n    code: A2AErrorCodeEnum.ChannelNotFound,\n    category: A2AErrorCategoryEnum.Collaboration,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The channel was not found.',\n  },\n  [A2AErrorCodeEnum.ThreadNotFound]: {\n    code: A2AErrorCodeEnum.ThreadNotFound,\n    category: A2AErrorCategoryEnum.Collaboration,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The thread was not found.',\n  },\n  [A2AErrorCodeEnum.MessageNotFound]: {\n    code: A2AErrorCodeEnum.MessageNotFound,\n    category: A2AErrorCategoryEnum.Collaboration,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The message was not found.',\n  },\n  [A2AErrorCodeEnum.NotChannelMember]: {\n    code: A2AErrorCodeEnum.NotChannelMember,\n    category: A2AErrorCategoryEnum.Collaboration,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The sender is not a member of the target channel.',\n  },\n\n  // transport\n  [A2AErrorCodeEnum.NetworkError]: {\n    code: A2AErrorCodeEnum.NetworkError,\n    category: A2AErrorCategoryEnum.Transport,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: true,\n    description: 'A network request failed.',\n  },\n  [A2AErrorCodeEnum.UnexpectedStatus]: {\n    code: A2AErrorCodeEnum.UnexpectedStatus,\n    category: A2AErrorCategoryEnum.Transport,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: true,\n    description: 'The remote endpoint returned an unexpected status.',\n  },\n  [A2AErrorCodeEnum.SerializationError]: {\n    code: A2AErrorCodeEnum.SerializationError,\n    category: A2AErrorCategoryEnum.Transport,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The request or response body could not be parsed.',\n  },\n\n  // auth\n  [A2AErrorCodeEnum.AuthenticationFailed]: {\n    code: A2AErrorCodeEnum.AuthenticationFailed,\n    category: A2AErrorCategoryEnum.Auth,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: false,\n    description: 'Authentication failed (invalid or missing credentials).',\n  },\n  [A2AErrorCodeEnum.AuthorizationDenied]: {\n    code: A2AErrorCodeEnum.AuthorizationDenied,\n    category: A2AErrorCategoryEnum.Auth,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The caller is not authorized for the requested operation.',\n  },\n  [A2AErrorCodeEnum.TokenExpired]: {\n    code: A2AErrorCodeEnum.TokenExpired,\n    category: A2AErrorCategoryEnum.Auth,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: true,\n    description: 'The access token has expired.',\n  },\n\n  // rate limit\n  [A2AErrorCodeEnum.RateLimitExceeded]: {\n    code: A2AErrorCodeEnum.RateLimitExceeded,\n    category: A2AErrorCategoryEnum.RateLimit,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: true,\n    description: 'The caller has exceeded the rate limit.',\n  },\n  [A2AErrorCodeEnum.QuotaExceeded]: {\n    code: A2AErrorCodeEnum.QuotaExceeded,\n    category: A2AErrorCategoryEnum.RateLimit,\n    severity: A2AErrorSeverityEnum.Medium,\n    retryable: false,\n    description: 'The caller has exceeded their usage quota.',\n  },\n\n  // internal\n  [A2AErrorCodeEnum.InternalError]: {\n    code: A2AErrorCodeEnum.InternalError,\n    category: A2AErrorCategoryEnum.Internal,\n    severity: A2AErrorSeverityEnum.Critical,\n    retryable: false,\n    description: 'An unexpected internal error occurred.',\n  },\n  [A2AErrorCodeEnum.ConfigurationError]: {\n    code: A2AErrorCodeEnum.ConfigurationError,\n    category: A2AErrorCategoryEnum.Internal,\n    severity: A2AErrorSeverityEnum.High,\n    retryable: false,\n    description: 'A configuration error was detected.',\n  },\n};\n\n// ---------------------------------------------------------------------------\n// Structured error type\n// ---------------------------------------------------------------------------\n\n/**\n * A structured A2A error that can be embedded in `TaskEnvelope.error`,\n * returned from connectors, or included in API error responses.\n */\nexport interface A2AError {\n  /** Machine-readable error code from the taxonomy. */\n  code: A2AErrorCode;\n  /** Error category. */\n  category: A2AErrorCategory;\n  /** Human-readable error message. */\n  message: string;\n  /** Error severity. */\n  severity: A2AErrorSeverity;\n  /** Whether the operation can be retried. */\n  retryable: boolean;\n  /** Additional details about the error. */\n  details?: Record<string, unknown>;\n  /** ISO-8601 timestamp of when the error occurred. */\n  timestamp?: string;\n  /** Trace ID for correlation. */\n  trace_id?: string;\n}\n\n// ---------------------------------------------------------------------------\n// Factory helper\n// ---------------------------------------------------------------------------\n\n/**\n * Build a structured `A2AError` from a code and message.\n * Category, severity, and retryable flag are automatically looked up from\n * the error code registry.\n *\n * @param input - The error code, message, and optional overrides.\n * @returns A fully populated `A2AError`.\n */\nexport function buildA2AError(input: {\n  code: A2AErrorCode;\n  message: string;\n  details?: Record<string, unknown>;\n  trace_id?: string;\n  /** Override the default severity from the registry. */\n  severity?: A2AErrorSeverity;\n  /** Override the default retryable flag from the registry. */\n  retryable?: boolean;\n  /** Override the timestamp (defaults to now). */\n  now?: string;\n}): A2AError {\n  const meta = A2A_ERROR_CODE_REGISTRY[input.code];\n  return {\n    code: input.code,\n    category: meta.category,\n    message: input.message,\n    severity: input.severity ?? meta.severity,\n    retryable: input.retryable ?? meta.retryable,\n    details: input.details,\n    timestamp: input.now ?? new Date().toISOString(),\n    trace_id: input.trace_id,\n  };\n}\n\n/**\n * Look up the metadata for an error code.\n *\n * @param code - The error code to look up.\n * @returns The error code metadata, or `undefined` if the code is not in the registry.\n */\nexport function getErrorCodeMeta(code: string): A2AErrorCodeMeta | undefined {\n  return A2A_ERROR_CODE_REGISTRY[code as A2AErrorCode];\n}\n\n/**\n * Check whether a given string is a valid A2A error code.\n *\n * @param code - The string to check.\n */\nexport function isA2AErrorCode(code: string): code is A2AErrorCode {\n  return code in A2A_ERROR_CODE_REGISTRY;\n}\n\n// ---------------------------------------------------------------------------\n// Error class\n// ---------------------------------------------------------------------------\n\n/**\n * A throwable Error subclass that carries the full structured A2A error.\n * Useful in control-plane code where you need to throw and catch typed errors.\n */\nexport class A2AStructuredError extends Error {\n  /** The structured error payload. */\n  readonly a2aError: A2AError;\n\n  constructor(a2aError: A2AError) {\n    super(`[${a2aError.code}] ${a2aError.message}`);\n    this.name = 'A2AStructuredError';\n    this.a2aError = a2aError;\n    Object.setPrototypeOf(this, A2AStructuredError.prototype);\n  }\n\n  /** Convenience getter for the error code. */\n  get code(): A2AErrorCode {\n    return this.a2aError.code;\n  }\n\n  /** Convenience getter for the error category. */\n  get category(): A2AErrorCategory {\n    return this.a2aError.category;\n  }\n\n  /** Convenience getter for the severity. */\n  get severity(): A2AErrorSeverity {\n    return this.a2aError.severity;\n  }\n\n  /** Whether this error is retryable. */\n  get retryable(): boolean {\n    return this.a2aError.retryable;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/error-mapping.mjs

@@ -0,0 +1,16 @@
+import {
+  mapClaudeError,
+  mapCodexError,
+  mapConnectorError,
+  mapHttpError,
+  wrapUnknownError
+} from "./chunk-AGD6G5N6.mjs";
+import "./chunk-WLNW7Y2H.mjs";
+export {
+  mapClaudeError,
+  mapCodexError,
+  mapConnectorError,
+  mapHttpError,
+  wrapUnknownError
+};
+//# sourceMappingURL=error-mapping.mjs.map

package/dist/error-mapping.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,7 @@
+export { A2AError, A2AErrorCategory, A2AErrorCategoryEnum, A2AErrorCode, A2AErrorCodeEnum, A2AErrorCodeMeta, A2AErrorSeverity, A2AErrorSeverityEnum, A2AStructuredError, A2A_ERROR_CODE_REGISTRY, ALLOWED_STATE_TRANSITIONS, AUDIT_EVENT_TYPES, AUDIT_EVENT_VERSION, AuditActor, AuditActorKind, AuditActorKindEnum, AuditEvent, AuditEventType, AuditEventTypeEnum, AuditPolicyContext, AuditSeverity, AuditSeverityEnum, AuditTarget, AuditTargetKind, AuditTargetKindEnum, CreateAuditEventInput, CreateTaskEnvelopeInput, TASK_ENVELOPE_VERSION, TASK_STATES, TERMINAL_TASK_STATES, TaskAgentRef, TaskArtifact, TaskConnectorInfo, TaskEnvelope, TaskErrorInfo, TaskPolicySnapshot, TaskResult, TaskState, TaskStateEnum, TaskStateTransition, buildA2AError, createAuditEvent, createTaskEnvelope, getErrorCodeMeta, isA2AErrorCode, isTerminalState, isValidTransition, transitionTaskEnvelope } from '@recoder/shared/a2a/schemas';
+export { ClaudeNativeState, CodexNativeState, ConnectorPlatform, canonicalToClaudeState, canonicalToCodexState, canonicalToConnectorState, checkConnectorTransition, isConnectorTerminalState, mapClaudeState, mapClaudeStateStrict, mapCodexState, mapCodexStateStrict, mapConnectorState, mapConnectorStateStrict } from './state-mapping.mjs';
+export { ClaudeErrorInput, CodexErrorInput, ConnectorErrorInput, mapClaudeError, mapCodexError, mapConnectorError, mapHttpError, wrapUnknownError } from './error-mapping.mjs';
+export { ClaudeEnvelopeOptions, CodexEnvelopeOptions, ConnectorEnvelopeInput, a2aErrorToTaskErrorInfo, buildClaudeEnvelope, buildCodexEnvelope, cancelEnvelope, completeEnvelope, failEnvelope, startEnvelope } from './envelope-builders.mjs';
+export { AuditEventBase, ConnectorAuditEventInput, PolicyAuditEventInput, TaskAuditEventInput, emitAuditForTransition, emitConnectorAttached, emitConnectorError, emitConnectorHealth, emitPolicyApproved, emitPolicyChecked, emitPolicyDenied, emitTaskCancelled, emitTaskCompleted, emitTaskFailed, emitTaskInputRequired, emitTaskProgress, emitTaskStarted, emitTaskSubmitted } from './audit-helpers.mjs';
+export { ValidationIssue, ValidationResult, assertAuditEvent, assertTaskEnvelope, isValidA2AError, isValidAuditEvent, isValidTaskEnvelope, validateA2AError, validateAuditEvent, validateTaskEnvelope } from './validation.mjs';
+import '@recoder/shared/a2a';

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { A2AError, A2AErrorCategory, A2AErrorCategoryEnum, A2AErrorCode, A2AErrorCodeEnum, A2AErrorCodeMeta, A2AErrorSeverity, A2AErrorSeverityEnum, A2AStructuredError, A2A_ERROR_CODE_REGISTRY, ALLOWED_STATE_TRANSITIONS, AUDIT_EVENT_TYPES, AUDIT_EVENT_VERSION, AuditActor, AuditActorKind, AuditActorKindEnum, AuditEvent, AuditEventType, AuditEventTypeEnum, AuditPolicyContext, AuditSeverity, AuditSeverityEnum, AuditTarget, AuditTargetKind, AuditTargetKindEnum, CreateAuditEventInput, CreateTaskEnvelopeInput, TASK_ENVELOPE_VERSION, TASK_STATES, TERMINAL_TASK_STATES, TaskAgentRef, TaskArtifact, TaskConnectorInfo, TaskEnvelope, TaskErrorInfo, TaskPolicySnapshot, TaskResult, TaskState, TaskStateEnum, TaskStateTransition, buildA2AError, createAuditEvent, createTaskEnvelope, getErrorCodeMeta, isA2AErrorCode, isTerminalState, isValidTransition, transitionTaskEnvelope } from '@recoder/shared/a2a/schemas';
+export { ClaudeNativeState, CodexNativeState, ConnectorPlatform, canonicalToClaudeState, canonicalToCodexState, canonicalToConnectorState, checkConnectorTransition, isConnectorTerminalState, mapClaudeState, mapClaudeStateStrict, mapCodexState, mapCodexStateStrict, mapConnectorState, mapConnectorStateStrict } from './state-mapping.js';
+export { ClaudeErrorInput, CodexErrorInput, ConnectorErrorInput, mapClaudeError, mapCodexError, mapConnectorError, mapHttpError, wrapUnknownError } from './error-mapping.js';
+export { ClaudeEnvelopeOptions, CodexEnvelopeOptions, ConnectorEnvelopeInput, a2aErrorToTaskErrorInfo, buildClaudeEnvelope, buildCodexEnvelope, cancelEnvelope, completeEnvelope, failEnvelope, startEnvelope } from './envelope-builders.js';
+export { AuditEventBase, ConnectorAuditEventInput, PolicyAuditEventInput, TaskAuditEventInput, emitAuditForTransition, emitConnectorAttached, emitConnectorError, emitConnectorHealth, emitPolicyApproved, emitPolicyChecked, emitPolicyDenied, emitTaskCancelled, emitTaskCompleted, emitTaskFailed, emitTaskInputRequired, emitTaskProgress, emitTaskStarted, emitTaskSubmitted } from './audit-helpers.js';
+export { ValidationIssue, ValidationResult, assertAuditEvent, assertTaskEnvelope, isValidA2AError, isValidAuditEvent, isValidTaskEnvelope, validateA2AError, validateAuditEvent, validateTaskEnvelope } from './validation.js';
+import '@recoder/shared/a2a';