@witqq/agent-sdk 0.6.1 → 0.7.0

package/dist/chat/state.cjs

@@ -0,0 +1,177 @@
+'use strict';
+
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  /** @internal Marker for cross-bundle identity checks */
+  _agentSDKError = true;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+  }
+  /** Check if an error is an AgentSDKError (works across bundled copies) */
+  static is(error) {
+    return error instanceof Error && "_agentSDKError" in error && error._agentSDKError === true;
+  }
+};
+
+// src/chat/errors.ts
+var ChatError = class extends AgentSDKError {
+  code;
+  retryable;
+  retryAfter;
+  timestamp;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "ChatError";
+    this.code = options.code;
+    this.retryable = options.retryable ?? false;
+    this.retryAfter = options.retryAfter;
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  }
+};
+
+// src/chat/state.ts
+var StateMachine = class {
+  constructor(initial, transitions) {
+    this.initial = initial;
+    this.transitions = transitions;
+    this._current = initial;
+  }
+  _current;
+  /** Current state */
+  get current() {
+    return this._current;
+  }
+  /**
+   * Check whether transitioning to `next` is allowed from current state
+   * @param next - Target state to check
+   * @returns True if transition is allowed
+   */
+  canTransition(next) {
+    const allowed = this.transitions[this._current];
+    return allowed !== void 0 && allowed.includes(next);
+  }
+  /**
+   * Transition to `next` state.
+   * @throws ChatError(INVALID_TRANSITION) if the transition is not allowed
+   */
+  transition(next) {
+    if (!this.canTransition(next)) {
+      throw new ChatError(
+        `Invalid transition: ${this._current} \u2192 ${next}`,
+        { code: "INVALID_TRANSITION" /* INVALID_TRANSITION */ }
+      );
+    }
+    this._current = next;
+  }
+  /** Reset to initial state */
+  reset() {
+    this._current = this.initial;
+  }
+};
+var RUNTIME_TRANSITIONS = {
+  idle: ["streaming", "disposed"],
+  streaming: ["idle", "error", "disposed"],
+  error: ["idle", "disposed"],
+  disposed: []
+};
+var MESSAGE_TRANSITIONS = {
+  pending: ["streaming", "error", "cancelled"],
+  streaming: ["complete", "error", "cancelled"],
+  complete: [],
+  error: [],
+  cancelled: []
+};
+var TOOL_CALL_TRANSITIONS = {
+  pending: ["running", "requires_approval", "error"],
+  running: ["complete", "error"],
+  requires_approval: ["running", "denied", "error"],
+  complete: [],
+  error: [],
+  denied: []
+};
+function createRuntimeStateMachine() {
+  return new StateMachine("idle", RUNTIME_TRANSITIONS);
+}
+function createMessageStateMachine() {
+  return new StateMachine("pending", MESSAGE_TRANSITIONS);
+}
+function createToolCallStateMachine() {
+  return new StateMachine("pending", TOOL_CALL_TRANSITIONS);
+}
+var ChatReentrancyGuard = class {
+  _acquired = false;
+  /** Whether the guard is currently held */
+  get isAcquired() {
+    return this._acquired;
+  }
+  /**
+   * Acquire the guard. Throws if already acquired.
+   * @throws ChatError with code REENTRANCY
+   */
+  acquire() {
+    if (this._acquired) {
+      throw new ChatError(
+        "Concurrent operation detected: a send is already in progress",
+        { code: "REENTRANCY" /* REENTRANCY */ }
+      );
+    }
+    this._acquired = true;
+  }
+  /** Release the guard. Safe to call even if not acquired. */
+  release() {
+    this._acquired = false;
+  }
+};
+var ChatAbortController = class {
+  _controller;
+  _onExternalAbort;
+  _externalSignal;
+  constructor(externalSignal) {
+    this._controller = new AbortController();
+    this._externalSignal = externalSignal;
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        this._controller.abort(externalSignal.reason);
+      } else {
+        this._onExternalAbort = () => {
+          this._controller.abort(externalSignal.reason);
+        };
+        externalSignal.addEventListener("abort", this._onExternalAbort, { once: true });
+      }
+    }
+  }
+  /** The AbortSignal for this controller */
+  get signal() {
+    return this._controller.signal;
+  }
+  /** Whether the operation has been aborted */
+  get isAborted() {
+    return this._controller.signal.aborted;
+  }
+  /**
+   * Abort the operation.
+   * @param reason - Optional abort reason
+   */
+  abort(reason) {
+    this._controller.abort(reason);
+  }
+  /** Clean up external signal listener to prevent memory leaks */
+  dispose() {
+    if (this._onExternalAbort && this._externalSignal) {
+      this._externalSignal.removeEventListener("abort", this._onExternalAbort);
+    }
+  }
+};
+
+exports.ChatAbortController = ChatAbortController;
+exports.ChatReentrancyGuard = ChatReentrancyGuard;
+exports.MESSAGE_TRANSITIONS = MESSAGE_TRANSITIONS;
+exports.RUNTIME_TRANSITIONS = RUNTIME_TRANSITIONS;
+exports.StateMachine = StateMachine;
+exports.TOOL_CALL_TRANSITIONS = TOOL_CALL_TRANSITIONS;
+exports.createMessageStateMachine = createMessageStateMachine;
+exports.createRuntimeStateMachine = createRuntimeStateMachine;
+exports.createToolCallStateMachine = createToolCallStateMachine;
+//# sourceMappingURL=state.cjs.map
+//# sourceMappingURL=state.cjs.map

package/dist/chat/state.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/chat/errors.ts","../../src/chat/state.ts"],"names":[],"mappings":"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","file":"state.cjs","sourcesContent":["/** Base error class for agent-sdk.\n *\n * Use `AgentSDKError.is(err)` for reliable cross-module `instanceof` checks\n * (works across separately bundled entry points where `instanceof` may fail). */\nexport class AgentSDKError extends Error {\n  /** @internal Marker for cross-bundle identity checks */\n  readonly _agentSDKError = true as const;\n\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"AgentSDKError\";\n  }\n\n  /** Check if an error is an AgentSDKError (works across bundled copies) */\n  static is(error: unknown): error is AgentSDKError {\n    return (\n      error instanceof Error &&\n      \"_agentSDKError\" in error &&\n      (error as AgentSDKError)._agentSDKError === true\n    );\n  }\n}\n\n/** Thrown when agent.run() is called while already running (M8 re-entrancy guard) */\nexport class ReentrancyError extends AgentSDKError {\n  constructor() {\n    super(\"Agent is already running. Await the current run before starting another.\");\n    this.name = \"ReentrancyError\";\n  }\n}\n\n/** Thrown when an operation is attempted on a disposed agent/service */\nexport class DisposedError extends AgentSDKError {\n  constructor(entity: string) {\n    super(`${entity} has been disposed and cannot be used.`);\n    this.name = \"DisposedError\";\n  }\n}\n\n/** Thrown when a backend is not found in the registry */\nexport class BackendNotFoundError extends AgentSDKError {\n  constructor(backend: string) {\n    super(\n      `Unknown backend: \"${backend}\". ` +\n      `Built-in: copilot, claude, vercel-ai. ` +\n      `Custom: use registerBackend() first.`,\n    );\n    this.name = \"BackendNotFoundError\";\n  }\n}\n\n/** Thrown when a backend is already registered */\nexport class BackendAlreadyRegisteredError extends AgentSDKError {\n  constructor(backend: string) {\n    super(`Backend \"${backend}\" is already registered. Use a different name or unregister first.`);\n    this.name = \"BackendAlreadyRegisteredError\";\n  }\n}\n\n/** Thrown when subprocess management fails */\nexport class SubprocessError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"SubprocessError\";\n  }\n}\n\n/** Thrown when a required peer dependency is not installed */\nexport class DependencyError extends AgentSDKError {\n  public readonly packageName: string;\n\n  constructor(packageName: string) {\n    super(`${packageName} is not installed. Install it: npm install ${packageName}`);\n    this.name = \"DependencyError\";\n    this.packageName = packageName;\n  }\n}\n\n/** Thrown when an agent run is aborted */\nexport class AbortError extends AgentSDKError {\n  constructor() {\n    super(\"Agent run was aborted.\");\n    this.name = \"AbortError\";\n  }\n}\n\n/** Thrown when a tool execution fails */\nexport class ToolExecutionError extends AgentSDKError {\n  public readonly toolName: string;\n\n  constructor(toolName: string, message: string, options?: ErrorOptions) {\n    super(`Tool \"${toolName}\" failed: ${message}`, options);\n    this.name = \"ToolExecutionError\";\n    this.toolName = toolName;\n  }\n}\n\n/** Thrown when structured output parsing fails */\nexport class StructuredOutputError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(`Structured output error: ${message}`, options);\n    this.name = \"StructuredOutputError\";\n  }\n}\n","/**\n * @witqq/agent-sdk/chat/errors\n *\n * Flat error taxonomy with ChatErrorCode enum, unified ChatError class,\n * pattern-matching classifier, retry strategies with exponential backoff.\n * Extends the existing AgentSDKError from @witqq/agent-sdk.\n */\n\nimport { AgentSDKError } from \"../errors.js\";\n\n// ─── Error Code Enum ───────────────────────────────────────────\n\n/** Error codes for chat-specific errors — used by classifyError() and ChatError */\nexport enum ChatErrorCode {\n  NETWORK = \"NETWORK\",\n  TIMEOUT = \"TIMEOUT\",\n  AUTH_EXPIRED = \"AUTH_EXPIRED\",\n  AUTH_INVALID = \"AUTH_INVALID\",\n  RATE_LIMIT = \"RATE_LIMIT\",\n  PROVIDER_ERROR = \"PROVIDER_ERROR\",\n  MODEL_NOT_FOUND = \"MODEL_NOT_FOUND\",\n  MODEL_OVERLOADED = \"MODEL_OVERLOADED\",\n  CONTEXT_OVERFLOW = \"CONTEXT_OVERFLOW\",\n  INVALID_INPUT = \"INVALID_INPUT\",\n  INVALID_RESPONSE = \"INVALID_RESPONSE\",\n  PERMISSION_DENIED = \"PERMISSION_DENIED\",\n  BACKEND_NOT_INSTALLED = \"BACKEND_NOT_INSTALLED\",\n  SESSION_NOT_FOUND = \"SESSION_NOT_FOUND\",\n  STORAGE_ERROR = \"STORAGE_ERROR\",\n  SESSION_EXPIRED = \"SESSION_EXPIRED\",\n  DISPOSED = \"DISPOSED\",\n  ABORTED = \"ABORTED\",\n  INVALID_TRANSITION = \"INVALID_TRANSITION\",\n  REENTRANCY = \"REENTRANCY\",\n}\n\n// ─── Error Options ─────────────────────────────────────────────\n\n/** Options for constructing a ChatError */\nexport interface ChatErrorOptions {\n  /** Machine-readable error code */\n  code: ChatErrorCode;\n  /** Whether this error is retryable (default: false) */\n  retryable?: boolean;\n  /** Retry delay hint in milliseconds */\n  retryAfter?: number;\n  /** Original cause, if wrapping another error */\n  cause?: unknown;\n}\n\n/** @deprecated Use ChatErrorOptions */\nexport type ChatSDKErrorOptions = ChatErrorOptions;\n\n// ─── Unified Error Class ───────────────────────────────────────\n\n/** Unified error class for all chat SDK errors */\nexport class ChatError extends AgentSDKError {\n  readonly code: ChatErrorCode;\n  readonly retryable: boolean;\n  readonly retryAfter?: number;\n  readonly timestamp: string;\n\n  constructor(message: string, options: ChatErrorOptions) {\n    super(message, { cause: options.cause });\n    this.name = \"ChatError\";\n    this.code = options.code;\n    this.retryable = options.retryable ?? false;\n    this.retryAfter = options.retryAfter;\n    this.timestamp = new Date().toISOString();\n  }\n}\n\n/** @deprecated Use ChatError */\nexport { ChatError as ChatSDKError };\n\n// ─── Classification ────────────────────────────────────────────\n\n/**\n * Classify an unknown thrown value into a ChatError with the appropriate code.\n * Pattern-matches against common error shapes:\n * - Already a ChatError → returned as-is\n * - Fetch/network errors (ECONNREFUSED, ETIMEDOUT, etc.)\n * - HTTP status codes (401→AUTH_INVALID, 429→RATE_LIMIT, 5xx→PROVIDER_ERROR)\n * - Timeout patterns\n * - Zod validation errors\n * - Context overflow patterns\n * - Unknown → wrapped as ChatError with PROVIDER_ERROR\n *\n * @param error - The thrown value to classify\n * @returns ChatError with appropriate error code and retryable flag\n */\nexport function classifyError(error: unknown): ChatError {\n  if (error instanceof ChatError) {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    const msg = error.message.toLowerCase();\n\n    // Network errors\n    if (isNetworkError(msg)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.NETWORK,\n        retryable: true,\n        cause: error,\n      });\n    }\n\n    // Timeout errors\n    if (isTimeoutPattern(msg)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.TIMEOUT,\n        retryable: true,\n        cause: error,\n      });\n    }\n\n    // Zod validation errors\n    if (isZodError(error)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.INVALID_INPUT,\n        retryable: false,\n        cause: error,\n      });\n    }\n\n    // HTTP status code errors\n    const statusCode = extractStatusCode(error);\n    if (statusCode !== null) {\n      return classifyByStatusCode(statusCode, error);\n    }\n\n    // Context overflow patterns\n    if (isContextOverflow(msg)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.CONTEXT_OVERFLOW,\n        retryable: false,\n        cause: error,\n      });\n    }\n  }\n\n  // Unknown errors\n  const message =\n    error instanceof Error ? error.message : String(error);\n  return new ChatError(message, {\n    code: ChatErrorCode.PROVIDER_ERROR,\n    retryable: false,\n    cause: error,\n  });\n}\n\n// ─── Classification Helpers ────────────────────────────────────\n\nconst NETWORK_PATTERNS = [\n  \"econnrefused\",\n  \"econnreset\",\n  \"enotfound\",\n  \"etimedout\",\n  \"enetunreach\",\n  \"epipe\",\n  \"fetch failed\",\n  \"network error\",\n  \"network request failed\",\n  \"failed to fetch\",\n  \"dns lookup failed\",\n] as const;\n\nfunction isNetworkError(msg: string): boolean {\n  return NETWORK_PATTERNS.some((p) => msg.includes(p));\n}\n\nfunction isTimeoutPattern(msg: string): boolean {\n  return (\n    msg.includes(\"timeout\") ||\n    msg.includes(\"timed out\") ||\n    msg.includes(\"deadline exceeded\") ||\n    msg.includes(\"aborted due to timeout\")\n  );\n}\n\nfunction isZodError(error: Error): boolean {\n  return (\n    error.name === \"ZodError\" ||\n    (\"issues\" in error && Array.isArray((error as unknown as Record<string, unknown>).issues))\n  );\n}\n\nfunction extractStatusCode(error: Error): number | null {\n  const errRecord = error as unknown as Record<string, unknown>;\n  if (typeof errRecord.status === \"number\") return errRecord.status;\n  if (typeof errRecord.statusCode === \"number\") return errRecord.statusCode;\n\n  // Check message for HTTP status codes\n  const match = error.message.match(/\\b(4\\d{2}|5\\d{2})\\b/);\n  return match ? parseInt(match[1], 10) : null;\n}\n\nfunction classifyByStatusCode(status: number, error: Error): ChatError {\n  if (status === 401 || status === 403) {\n    return new ChatError(error.message, {\n      code: ChatErrorCode.AUTH_INVALID,\n      retryable: false,\n      cause: error,\n    });\n  }\n  if (status === 429) {\n    const retryAfterSeconds = extractRetryAfter(error);\n    return new ChatError(error.message, {\n      code: ChatErrorCode.RATE_LIMIT,\n      retryable: true,\n      retryAfter: retryAfterSeconds != null ? retryAfterSeconds * 1000 : undefined,\n      cause: error,\n    });\n  }\n  if (status >= 500) {\n    return new ChatError(error.message, {\n      code: ChatErrorCode.PROVIDER_ERROR,\n      retryable: true,\n      cause: error,\n    });\n  }\n  // 4xx other than auth/rate-limit → invalid input\n  if (status >= 400 && status < 500) {\n    return new ChatError(error.message, {\n      code: ChatErrorCode.INVALID_INPUT,\n      retryable: false,\n      cause: error,\n    });\n  }\n  return new ChatError(error.message, {\n    code: ChatErrorCode.NETWORK,\n    retryable: true,\n    cause: error,\n  });\n}\n\nfunction extractRetryAfter(error: Error): number | undefined {\n  const errRecord = error as unknown as Record<string, unknown>;\n  if (typeof errRecord.retryAfter === \"number\") return errRecord.retryAfter;\n  const match = error.message.match(/retry.after[:\\s]*(\\d+)/i);\n  return match ? parseInt(match[1], 10) : undefined;\n}\n\nfunction isContextOverflow(msg: string): boolean {\n  return (\n    msg.includes(\"context length exceeded\") ||\n    msg.includes(\"maximum context length\") ||\n    msg.includes(\"context window\") ||\n    msg.includes(\"token limit\") ||\n    msg.includes(\"too many tokens\")\n  );\n}\n\n// ─── Retry Strategy ────────────────────────────────────────────\n\n/** Strategy for computing retry delays */\nexport interface RetryStrategy {\n  /** Return delay in ms for the given attempt (0-based), or null to stop */\n  nextDelay(attempt: number, error: ChatError): number | null;\n}\n\n/** Options for ExponentialBackoffStrategy */\nexport interface ExponentialBackoffOptions {\n  /** Base delay in ms (default: 1000) */\n  baseMs?: number;\n  /** Maximum delay in ms (default: 30000) */\n  maxMs?: number;\n  /** Maximum number of attempts (default: 3) */\n  maxAttempts?: number;\n  /** Jitter factor 0–1 (default: 0.1) */\n  jitter?: number;\n}\n\n/** Exponential backoff with optional jitter */\nexport class ExponentialBackoffStrategy implements RetryStrategy {\n  private readonly baseMs: number;\n  private readonly maxMs: number;\n  private readonly maxAttempts: number;\n  private readonly jitter: number;\n\n  constructor(options?: ExponentialBackoffOptions) {\n    this.baseMs = options?.baseMs ?? 1000;\n    this.maxMs = options?.maxMs ?? 30000;\n    this.maxAttempts = options?.maxAttempts ?? 3;\n    this.jitter = Math.max(0, Math.min(1, options?.jitter ?? 0.1));\n  }\n\n  nextDelay(attempt: number, error: ChatError): number | null {\n    if (attempt >= this.maxAttempts) return null;\n    if (!error.retryable) return null;\n\n    // Rate-limit errors with retryAfter (already in ms) take priority\n    if (error.code === ChatErrorCode.RATE_LIMIT && error.retryAfter) {\n      return error.retryAfter;\n    }\n\n    const delay = Math.min(this.baseMs * Math.pow(2, attempt), this.maxMs);\n    const jitterAmount = delay * this.jitter * (Math.random() * 2 - 1);\n    return Math.max(0, Math.round(delay + jitterAmount));\n  }\n}\n\n// ─── Retry Execution ───────────────────────────────────────────\n\n/** Options for withRetry execution */\nexport interface RetryOptions {\n  /** Abort signal to cancel retries */\n  signal?: AbortSignal;\n  /** Called before each retry with the error and delay */\n  onRetry?: (error: ChatError, attempt: number, delayMs: number) => void;\n}\n\n/**\n * Execute an async function with automatic retries using the provided strategy.\n * Respects ChatError.retryable and ChatError.retryAfter.\n * Classifies non-ChatError errors before deciding on retry.\n *\n * @param fn - Async function to execute\n * @param strategy - Retry strategy providing delay calculations\n * @param options - Optional abort signal and retry callback\n * @returns Result of fn on success\n * @throws ChatError when all retries exhausted or error is non-retryable\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  strategy: RetryStrategy,\n  options?: RetryOptions,\n): Promise<T> {\n  let attempt = 0;\n\n  for (;;) {\n    try {\n      return await fn();\n    } catch (raw) {\n      const error = classifyError(raw);\n      const delay = strategy.nextDelay(attempt, error);\n\n      if (delay === null) {\n        throw error;\n      }\n\n      if (options?.signal?.aborted) {\n        throw error;\n      }\n\n      options?.onRetry?.(error, attempt, delay);\n\n      await sleep(delay, options?.signal);\n      attempt++;\n    }\n  }\n}\n\n/**\n * Type guard: check if an error is retryable\n * @param error - The error to check\n * @returns True if error is a retryable ChatError\n */\nexport function isRetryable(error: unknown): boolean {\n  if (error instanceof ChatError) {\n    return error.retryable;\n  }\n  const classified = classifyError(error);\n  return classified.retryable;\n}\n\n// ─── Internal Helpers ──────────────────────────────────────────\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new ChatError(\"Retry aborted\", { code: ChatErrorCode.ABORTED }));\n      return;\n    }\n\n    const timer = setTimeout(resolve, ms);\n\n    signal?.addEventListener(\n      \"abort\",\n      () => {\n        clearTimeout(timer);\n        reject(new ChatError(\"Retry aborted\", { code: ChatErrorCode.ABORTED }));\n      },\n      { once: true },\n    );\n  });\n}\n","/**\n * @witqq/agent-sdk/chat/state\n *\n * Validated state machines for runtime, message, and tool-call lifecycles.\n * Generic StateMachine<S> with declarative transition maps.\n */\n\nimport type { RuntimeStatus, MessageStatus, ToolCallStatus } from \"./core.js\";\nimport { ChatError, ChatErrorCode } from \"./errors.js\";\n\n// ─── Generic State Machine ─────────────────────────────────────\n\n/** Map of allowed transitions: current state → set of valid next states */\nexport type TransitionMap<S extends string> = Readonly<Record<S, readonly S[]>>;\n\n/**\n * Generic validated state machine.\n * Enforces that every transition is declared in the transition map.\n * Throws ChatError(INVALID_TRANSITION) on illegal moves.\n */\nexport class StateMachine<S extends string> {\n  private _current: S;\n\n  constructor(\n    readonly initial: S,\n    readonly transitions: TransitionMap<S>,\n  ) {\n    this._current = initial;\n  }\n\n  /** Current state */\n  get current(): S {\n    return this._current;\n  }\n\n  /**\n   * Check whether transitioning to `next` is allowed from current state\n   * @param next - Target state to check\n   * @returns True if transition is allowed\n   */\n  canTransition(next: S): boolean {\n    const allowed = this.transitions[this._current];\n    return allowed !== undefined && allowed.includes(next);\n  }\n\n  /**\n   * Transition to `next` state.\n   * @throws ChatError(INVALID_TRANSITION) if the transition is not allowed\n   */\n  transition(next: S): void {\n    if (!this.canTransition(next)) {\n      throw new ChatError(\n        `Invalid transition: ${this._current} → ${next}`,\n        { code: ChatErrorCode.INVALID_TRANSITION },\n      );\n    }\n    this._current = next;\n  }\n\n  /** Reset to initial state */\n  reset(): void {\n    this._current = this.initial;\n  }\n}\n\n// ─── Transition Maps ───────────────────────────────────────────\n\n/** Allowed transitions for RuntimeStatus (idle → streaming/disposed, etc.) */\nexport const RUNTIME_TRANSITIONS: TransitionMap<RuntimeStatus> = {\n  idle: [\"streaming\", \"disposed\"],\n  streaming: [\"idle\", \"error\", \"disposed\"],\n  error: [\"idle\", \"disposed\"],\n  disposed: [],\n};\n\n/** Allowed transitions for MessageStatus (pending → streaming → complete, etc.) */\nexport const MESSAGE_TRANSITIONS: TransitionMap<MessageStatus> = {\n  pending: [\"streaming\", \"error\", \"cancelled\"],\n  streaming: [\"complete\", \"error\", \"cancelled\"],\n  complete: [],\n  error: [],\n  cancelled: [],\n};\n\n/** Allowed transitions for ToolCallStatus (pending → running → complete, etc.) */\nexport const TOOL_CALL_TRANSITIONS: TransitionMap<ToolCallStatus> = {\n  pending: [\"running\", \"requires_approval\", \"error\"],\n  running: [\"complete\", \"error\"],\n  requires_approval: [\"running\", \"denied\", \"error\"],\n  complete: [],\n  error: [],\n  denied: [],\n};\n\n// ─── Pre-configured Factories ──────────────────────────────────\n\n/** Create a RuntimeStatus state machine starting at \"idle\" */\nexport function createRuntimeStateMachine(): StateMachine<RuntimeStatus> {\n  return new StateMachine<RuntimeStatus>(\"idle\", RUNTIME_TRANSITIONS);\n}\n\n/** Create a MessageStatus state machine starting at \"pending\" */\nexport function createMessageStateMachine(): StateMachine<MessageStatus> {\n  return new StateMachine<MessageStatus>(\"pending\", MESSAGE_TRANSITIONS);\n}\n\n/** Create a ToolCallStatus state machine starting at \"pending\" */\nexport function createToolCallStateMachine(): StateMachine<ToolCallStatus> {\n  return new StateMachine<ToolCallStatus>(\"pending\", TOOL_CALL_TRANSITIONS);\n}\n\n// ─── Reentrancy Guard ──────────────────────────────────────────\n\n/**\n * Guards against concurrent send() calls in a chat runtime.\n * acquire() before work, release() after (use try/finally).\n * Throws ChatError(REENTRANCY) if already acquired.\n */\nexport class ChatReentrancyGuard {\n  private _acquired = false;\n\n  /** Whether the guard is currently held */\n  get isAcquired(): boolean {\n    return this._acquired;\n  }\n\n  /**\n   * Acquire the guard. Throws if already acquired.\n   * @throws ChatError with code REENTRANCY\n   */\n  acquire(): void {\n    if (this._acquired) {\n      throw new ChatError(\n        \"Concurrent operation detected: a send is already in progress\",\n        { code: ChatErrorCode.REENTRANCY },\n      );\n    }\n    this._acquired = true;\n  }\n\n  /** Release the guard. Safe to call even if not acquired. */\n  release(): void {\n    this._acquired = false;\n  }\n}\n\n// ─── Abort Controller ──────────────────────────────────────────\n\n/**\n * Abort controller with external signal linking.\n * Wraps an AbortController and optionally links an external AbortSignal\n * so aborting either side cancels the operation.\n */\nexport class ChatAbortController {\n  private readonly _controller: AbortController;\n  private readonly _onExternalAbort?: () => void;\n  private readonly _externalSignal?: AbortSignal;\n\n  constructor(externalSignal?: AbortSignal) {\n    this._controller = new AbortController();\n    this._externalSignal = externalSignal;\n\n    if (externalSignal) {\n      // If external signal already aborted, abort immediately\n      if (externalSignal.aborted) {\n        this._controller.abort(externalSignal.reason);\n      } else {\n        // Link: external abort → our controller\n        this._onExternalAbort = () => {\n          this._controller.abort(externalSignal.reason);\n        };\n        externalSignal.addEventListener(\"abort\", this._onExternalAbort, { once: true });\n      }\n    }\n  }\n\n  /** The AbortSignal for this controller */\n  get signal(): AbortSignal {\n    return this._controller.signal;\n  }\n\n  /** Whether the operation has been aborted */\n  get isAborted(): boolean {\n    return this._controller.signal.aborted;\n  }\n\n  /**\n   * Abort the operation.\n   * @param reason - Optional abort reason\n   */\n  abort(reason?: unknown): void {\n    this._controller.abort(reason);\n  }\n\n  /** Clean up external signal listener to prevent memory leaks */\n  dispose(): void {\n    if (this._onExternalAbort && this._externalSignal) {\n      this._externalSignal.removeEventListener(\"abort\", this._onExternalAbort);\n    }\n  }\n}\n"]}

package/dist/chat/state.d.cts

@@ -0,0 +1,92 @@
+import { MessageStatus, RuntimeStatus, ToolCallStatus } from './core.cjs';
+import '../types-CqvUAYxt.cjs';
+import 'zod';
+
+/**
+ * @witqq/agent-sdk/chat/state
+ *
+ * Validated state machines for runtime, message, and tool-call lifecycles.
+ * Generic StateMachine<S> with declarative transition maps.
+ */
+
+/** Map of allowed transitions: current state → set of valid next states */
+type TransitionMap<S extends string> = Readonly<Record<S, readonly S[]>>;
+/**
+ * Generic validated state machine.
+ * Enforces that every transition is declared in the transition map.
+ * Throws ChatError(INVALID_TRANSITION) on illegal moves.
+ */
+declare class StateMachine<S extends string> {
+    readonly initial: S;
+    readonly transitions: TransitionMap<S>;
+    private _current;
+    constructor(initial: S, transitions: TransitionMap<S>);
+    /** Current state */
+    get current(): S;
+    /**
+     * Check whether transitioning to `next` is allowed from current state
+     * @param next - Target state to check
+     * @returns True if transition is allowed
+     */
+    canTransition(next: S): boolean;
+    /**
+     * Transition to `next` state.
+     * @throws ChatError(INVALID_TRANSITION) if the transition is not allowed
+     */
+    transition(next: S): void;
+    /** Reset to initial state */
+    reset(): void;
+}
+/** Allowed transitions for RuntimeStatus (idle → streaming/disposed, etc.) */
+declare const RUNTIME_TRANSITIONS: TransitionMap<RuntimeStatus>;
+/** Allowed transitions for MessageStatus (pending → streaming → complete, etc.) */
+declare const MESSAGE_TRANSITIONS: TransitionMap<MessageStatus>;
+/** Allowed transitions for ToolCallStatus (pending → running → complete, etc.) */
+declare const TOOL_CALL_TRANSITIONS: TransitionMap<ToolCallStatus>;
+/** Create a RuntimeStatus state machine starting at "idle" */
+declare function createRuntimeStateMachine(): StateMachine<RuntimeStatus>;
+/** Create a MessageStatus state machine starting at "pending" */
+declare function createMessageStateMachine(): StateMachine<MessageStatus>;
+/** Create a ToolCallStatus state machine starting at "pending" */
+declare function createToolCallStateMachine(): StateMachine<ToolCallStatus>;
+/**
+ * Guards against concurrent send() calls in a chat runtime.
+ * acquire() before work, release() after (use try/finally).
+ * Throws ChatError(REENTRANCY) if already acquired.
+ */
+declare class ChatReentrancyGuard {
+    private _acquired;
+    /** Whether the guard is currently held */
+    get isAcquired(): boolean;
+    /**
+     * Acquire the guard. Throws if already acquired.
+     * @throws ChatError with code REENTRANCY
+     */
+    acquire(): void;
+    /** Release the guard. Safe to call even if not acquired. */
+    release(): void;
+}
+/**
+ * Abort controller with external signal linking.
+ * Wraps an AbortController and optionally links an external AbortSignal
+ * so aborting either side cancels the operation.
+ */
+declare class ChatAbortController {
+    private readonly _controller;
+    private readonly _onExternalAbort?;
+    private readonly _externalSignal?;
+    constructor(externalSignal?: AbortSignal);
+    /** The AbortSignal for this controller */
+    get signal(): AbortSignal;
+    /** Whether the operation has been aborted */
+    get isAborted(): boolean;
+    /**
+     * Abort the operation.
+     * @param reason - Optional abort reason
+     */
+    abort(reason?: unknown): void;
+    /** Clean up external signal listener to prevent memory leaks */
+    dispose(): void;
+}
+
+export { ChatAbortController, ChatReentrancyGuard, MESSAGE_TRANSITIONS, RUNTIME_TRANSITIONS, StateMachine, TOOL_CALL_TRANSITIONS, type TransitionMap, createMessageStateMachine, createRuntimeStateMachine, createToolCallStateMachine };

package/dist/chat/state.d.ts

@@ -0,0 +1,92 @@
+import { MessageStatus, RuntimeStatus, ToolCallStatus } from './core.js';
+import '../types-CqvUAYxt.js';
+import 'zod';
+
+/**
+ * @witqq/agent-sdk/chat/state
+ *
+ * Validated state machines for runtime, message, and tool-call lifecycles.
+ * Generic StateMachine<S> with declarative transition maps.
+ */
+
+/** Map of allowed transitions: current state → set of valid next states */
+type TransitionMap<S extends string> = Readonly<Record<S, readonly S[]>>;
+/**
+ * Generic validated state machine.
+ * Enforces that every transition is declared in the transition map.
+ * Throws ChatError(INVALID_TRANSITION) on illegal moves.
+ */
+declare class StateMachine<S extends string> {
+    readonly initial: S;
+    readonly transitions: TransitionMap<S>;
+    private _current;
+    constructor(initial: S, transitions: TransitionMap<S>);
+    /** Current state */
+    get current(): S;
+    /**
+     * Check whether transitioning to `next` is allowed from current state
+     * @param next - Target state to check
+     * @returns True if transition is allowed
+     */
+    canTransition(next: S): boolean;
+    /**
+     * Transition to `next` state.
+     * @throws ChatError(INVALID_TRANSITION) if the transition is not allowed
+     */
+    transition(next: S): void;
+    /** Reset to initial state */
+    reset(): void;
+}
+/** Allowed transitions for RuntimeStatus (idle → streaming/disposed, etc.) */
+declare const RUNTIME_TRANSITIONS: TransitionMap<RuntimeStatus>;
+/** Allowed transitions for MessageStatus (pending → streaming → complete, etc.) */
+declare const MESSAGE_TRANSITIONS: TransitionMap<MessageStatus>;
+/** Allowed transitions for ToolCallStatus (pending → running → complete, etc.) */
+declare const TOOL_CALL_TRANSITIONS: TransitionMap<ToolCallStatus>;
+/** Create a RuntimeStatus state machine starting at "idle" */
+declare function createRuntimeStateMachine(): StateMachine<RuntimeStatus>;
+/** Create a MessageStatus state machine starting at "pending" */
+declare function createMessageStateMachine(): StateMachine<MessageStatus>;
+/** Create a ToolCallStatus state machine starting at "pending" */
+declare function createToolCallStateMachine(): StateMachine<ToolCallStatus>;
+/**
+ * Guards against concurrent send() calls in a chat runtime.
+ * acquire() before work, release() after (use try/finally).
+ * Throws ChatError(REENTRANCY) if already acquired.
+ */
+declare class ChatReentrancyGuard {
+    private _acquired;
+    /** Whether the guard is currently held */
+    get isAcquired(): boolean;
+    /**
+     * Acquire the guard. Throws if already acquired.
+     * @throws ChatError with code REENTRANCY
+     */
+    acquire(): void;
+    /** Release the guard. Safe to call even if not acquired. */
+    release(): void;
+}
+/**
+ * Abort controller with external signal linking.
+ * Wraps an AbortController and optionally links an external AbortSignal
+ * so aborting either side cancels the operation.
+ */
+declare class ChatAbortController {
+    private readonly _controller;
+    private readonly _onExternalAbort?;
+    private readonly _externalSignal?;
+    constructor(externalSignal?: AbortSignal);
+    /** The AbortSignal for this controller */
+    get signal(): AbortSignal;
+    /** Whether the operation has been aborted */
+    get isAborted(): boolean;
+    /**
+     * Abort the operation.
+     * @param reason - Optional abort reason
+     */
+    abort(reason?: unknown): void;
+    /** Clean up external signal listener to prevent memory leaks */
+    dispose(): void;
+}
+
+export { ChatAbortController, ChatReentrancyGuard, MESSAGE_TRANSITIONS, RUNTIME_TRANSITIONS, StateMachine, TOOL_CALL_TRANSITIONS, type TransitionMap, createMessageStateMachine, createRuntimeStateMachine, createToolCallStateMachine };

package/dist/chat/state.js

@@ -0,0 +1,167 @@
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  /** @internal Marker for cross-bundle identity checks */
+  _agentSDKError = true;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+  }
+  /** Check if an error is an AgentSDKError (works across bundled copies) */
+  static is(error) {
+    return error instanceof Error && "_agentSDKError" in error && error._agentSDKError === true;
+  }
+};
+
+// src/chat/errors.ts
+var ChatError = class extends AgentSDKError {
+  code;
+  retryable;
+  retryAfter;
+  timestamp;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = "ChatError";
+    this.code = options.code;
+    this.retryable = options.retryable ?? false;
+    this.retryAfter = options.retryAfter;
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  }
+};
+
+// src/chat/state.ts
+var StateMachine = class {
+  constructor(initial, transitions) {
+    this.initial = initial;
+    this.transitions = transitions;
+    this._current = initial;
+  }
+  _current;
+  /** Current state */
+  get current() {
+    return this._current;
+  }
+  /**
+   * Check whether transitioning to `next` is allowed from current state
+   * @param next - Target state to check
+   * @returns True if transition is allowed
+   */
+  canTransition(next) {
+    const allowed = this.transitions[this._current];
+    return allowed !== void 0 && allowed.includes(next);
+  }
+  /**
+   * Transition to `next` state.
+   * @throws ChatError(INVALID_TRANSITION) if the transition is not allowed
+   */
+  transition(next) {
+    if (!this.canTransition(next)) {
+      throw new ChatError(
+        `Invalid transition: ${this._current} \u2192 ${next}`,
+        { code: "INVALID_TRANSITION" /* INVALID_TRANSITION */ }
+      );
+    }
+    this._current = next;
+  }
+  /** Reset to initial state */
+  reset() {
+    this._current = this.initial;
+  }
+};
+var RUNTIME_TRANSITIONS = {
+  idle: ["streaming", "disposed"],
+  streaming: ["idle", "error", "disposed"],
+  error: ["idle", "disposed"],
+  disposed: []
+};
+var MESSAGE_TRANSITIONS = {
+  pending: ["streaming", "error", "cancelled"],
+  streaming: ["complete", "error", "cancelled"],
+  complete: [],
+  error: [],
+  cancelled: []
+};
+var TOOL_CALL_TRANSITIONS = {
+  pending: ["running", "requires_approval", "error"],
+  running: ["complete", "error"],
+  requires_approval: ["running", "denied", "error"],
+  complete: [],
+  error: [],
+  denied: []
+};
+function createRuntimeStateMachine() {
+  return new StateMachine("idle", RUNTIME_TRANSITIONS);
+}
+function createMessageStateMachine() {
+  return new StateMachine("pending", MESSAGE_TRANSITIONS);
+}
+function createToolCallStateMachine() {
+  return new StateMachine("pending", TOOL_CALL_TRANSITIONS);
+}
+var ChatReentrancyGuard = class {
+  _acquired = false;
+  /** Whether the guard is currently held */
+  get isAcquired() {
+    return this._acquired;
+  }
+  /**
+   * Acquire the guard. Throws if already acquired.
+   * @throws ChatError with code REENTRANCY
+   */
+  acquire() {
+    if (this._acquired) {
+      throw new ChatError(
+        "Concurrent operation detected: a send is already in progress",
+        { code: "REENTRANCY" /* REENTRANCY */ }
+      );
+    }
+    this._acquired = true;
+  }
+  /** Release the guard. Safe to call even if not acquired. */
+  release() {
+    this._acquired = false;
+  }
+};
+var ChatAbortController = class {
+  _controller;
+  _onExternalAbort;
+  _externalSignal;
+  constructor(externalSignal) {
+    this._controller = new AbortController();
+    this._externalSignal = externalSignal;
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        this._controller.abort(externalSignal.reason);
+      } else {
+        this._onExternalAbort = () => {
+          this._controller.abort(externalSignal.reason);
+        };
+        externalSignal.addEventListener("abort", this._onExternalAbort, { once: true });
+      }
+    }
+  }
+  /** The AbortSignal for this controller */
+  get signal() {
+    return this._controller.signal;
+  }
+  /** Whether the operation has been aborted */
+  get isAborted() {
+    return this._controller.signal.aborted;
+  }
+  /**
+   * Abort the operation.
+   * @param reason - Optional abort reason
+   */
+  abort(reason) {
+    this._controller.abort(reason);
+  }
+  /** Clean up external signal listener to prevent memory leaks */
+  dispose() {
+    if (this._onExternalAbort && this._externalSignal) {
+      this._externalSignal.removeEventListener("abort", this._onExternalAbort);
+    }
+  }
+};
+
+export { ChatAbortController, ChatReentrancyGuard, MESSAGE_TRANSITIONS, RUNTIME_TRANSITIONS, StateMachine, TOOL_CALL_TRANSITIONS, createMessageStateMachine, createRuntimeStateMachine, createToolCallStateMachine };
+//# sourceMappingURL=state.js.map
+//# sourceMappingURL=state.js.map

package/dist/chat/state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts","../../src/chat/errors.ts","../../src/chat/state.ts"],"names":[],"mappings":"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","file":"state.js","sourcesContent":["/** Base error class for agent-sdk.\n *\n * Use `AgentSDKError.is(err)` for reliable cross-module `instanceof` checks\n * (works across separately bundled entry points where `instanceof` may fail). */\nexport class AgentSDKError extends Error {\n  /** @internal Marker for cross-bundle identity checks */\n  readonly _agentSDKError = true as const;\n\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"AgentSDKError\";\n  }\n\n  /** Check if an error is an AgentSDKError (works across bundled copies) */\n  static is(error: unknown): error is AgentSDKError {\n    return (\n      error instanceof Error &&\n      \"_agentSDKError\" in error &&\n      (error as AgentSDKError)._agentSDKError === true\n    );\n  }\n}\n\n/** Thrown when agent.run() is called while already running (M8 re-entrancy guard) */\nexport class ReentrancyError extends AgentSDKError {\n  constructor() {\n    super(\"Agent is already running. Await the current run before starting another.\");\n    this.name = \"ReentrancyError\";\n  }\n}\n\n/** Thrown when an operation is attempted on a disposed agent/service */\nexport class DisposedError extends AgentSDKError {\n  constructor(entity: string) {\n    super(`${entity} has been disposed and cannot be used.`);\n    this.name = \"DisposedError\";\n  }\n}\n\n/** Thrown when a backend is not found in the registry */\nexport class BackendNotFoundError extends AgentSDKError {\n  constructor(backend: string) {\n    super(\n      `Unknown backend: \"${backend}\". ` +\n      `Built-in: copilot, claude, vercel-ai. ` +\n      `Custom: use registerBackend() first.`,\n    );\n    this.name = \"BackendNotFoundError\";\n  }\n}\n\n/** Thrown when a backend is already registered */\nexport class BackendAlreadyRegisteredError extends AgentSDKError {\n  constructor(backend: string) {\n    super(`Backend \"${backend}\" is already registered. Use a different name or unregister first.`);\n    this.name = \"BackendAlreadyRegisteredError\";\n  }\n}\n\n/** Thrown when subprocess management fails */\nexport class SubprocessError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"SubprocessError\";\n  }\n}\n\n/** Thrown when a required peer dependency is not installed */\nexport class DependencyError extends AgentSDKError {\n  public readonly packageName: string;\n\n  constructor(packageName: string) {\n    super(`${packageName} is not installed. Install it: npm install ${packageName}`);\n    this.name = \"DependencyError\";\n    this.packageName = packageName;\n  }\n}\n\n/** Thrown when an agent run is aborted */\nexport class AbortError extends AgentSDKError {\n  constructor() {\n    super(\"Agent run was aborted.\");\n    this.name = \"AbortError\";\n  }\n}\n\n/** Thrown when a tool execution fails */\nexport class ToolExecutionError extends AgentSDKError {\n  public readonly toolName: string;\n\n  constructor(toolName: string, message: string, options?: ErrorOptions) {\n    super(`Tool \"${toolName}\" failed: ${message}`, options);\n    this.name = \"ToolExecutionError\";\n    this.toolName = toolName;\n  }\n}\n\n/** Thrown when structured output parsing fails */\nexport class StructuredOutputError extends AgentSDKError {\n  constructor(message: string, options?: ErrorOptions) {\n    super(`Structured output error: ${message}`, options);\n    this.name = \"StructuredOutputError\";\n  }\n}\n","/**\n * @witqq/agent-sdk/chat/errors\n *\n * Flat error taxonomy with ChatErrorCode enum, unified ChatError class,\n * pattern-matching classifier, retry strategies with exponential backoff.\n * Extends the existing AgentSDKError from @witqq/agent-sdk.\n */\n\nimport { AgentSDKError } from \"../errors.js\";\n\n// ─── Error Code Enum ───────────────────────────────────────────\n\n/** Error codes for chat-specific errors — used by classifyError() and ChatError */\nexport enum ChatErrorCode {\n  NETWORK = \"NETWORK\",\n  TIMEOUT = \"TIMEOUT\",\n  AUTH_EXPIRED = \"AUTH_EXPIRED\",\n  AUTH_INVALID = \"AUTH_INVALID\",\n  RATE_LIMIT = \"RATE_LIMIT\",\n  PROVIDER_ERROR = \"PROVIDER_ERROR\",\n  MODEL_NOT_FOUND = \"MODEL_NOT_FOUND\",\n  MODEL_OVERLOADED = \"MODEL_OVERLOADED\",\n  CONTEXT_OVERFLOW = \"CONTEXT_OVERFLOW\",\n  INVALID_INPUT = \"INVALID_INPUT\",\n  INVALID_RESPONSE = \"INVALID_RESPONSE\",\n  PERMISSION_DENIED = \"PERMISSION_DENIED\",\n  BACKEND_NOT_INSTALLED = \"BACKEND_NOT_INSTALLED\",\n  SESSION_NOT_FOUND = \"SESSION_NOT_FOUND\",\n  STORAGE_ERROR = \"STORAGE_ERROR\",\n  SESSION_EXPIRED = \"SESSION_EXPIRED\",\n  DISPOSED = \"DISPOSED\",\n  ABORTED = \"ABORTED\",\n  INVALID_TRANSITION = \"INVALID_TRANSITION\",\n  REENTRANCY = \"REENTRANCY\",\n}\n\n// ─── Error Options ─────────────────────────────────────────────\n\n/** Options for constructing a ChatError */\nexport interface ChatErrorOptions {\n  /** Machine-readable error code */\n  code: ChatErrorCode;\n  /** Whether this error is retryable (default: false) */\n  retryable?: boolean;\n  /** Retry delay hint in milliseconds */\n  retryAfter?: number;\n  /** Original cause, if wrapping another error */\n  cause?: unknown;\n}\n\n/** @deprecated Use ChatErrorOptions */\nexport type ChatSDKErrorOptions = ChatErrorOptions;\n\n// ─── Unified Error Class ───────────────────────────────────────\n\n/** Unified error class for all chat SDK errors */\nexport class ChatError extends AgentSDKError {\n  readonly code: ChatErrorCode;\n  readonly retryable: boolean;\n  readonly retryAfter?: number;\n  readonly timestamp: string;\n\n  constructor(message: string, options: ChatErrorOptions) {\n    super(message, { cause: options.cause });\n    this.name = \"ChatError\";\n    this.code = options.code;\n    this.retryable = options.retryable ?? false;\n    this.retryAfter = options.retryAfter;\n    this.timestamp = new Date().toISOString();\n  }\n}\n\n/** @deprecated Use ChatError */\nexport { ChatError as ChatSDKError };\n\n// ─── Classification ────────────────────────────────────────────\n\n/**\n * Classify an unknown thrown value into a ChatError with the appropriate code.\n * Pattern-matches against common error shapes:\n * - Already a ChatError → returned as-is\n * - Fetch/network errors (ECONNREFUSED, ETIMEDOUT, etc.)\n * - HTTP status codes (401→AUTH_INVALID, 429→RATE_LIMIT, 5xx→PROVIDER_ERROR)\n * - Timeout patterns\n * - Zod validation errors\n * - Context overflow patterns\n * - Unknown → wrapped as ChatError with PROVIDER_ERROR\n *\n * @param error - The thrown value to classify\n * @returns ChatError with appropriate error code and retryable flag\n */\nexport function classifyError(error: unknown): ChatError {\n  if (error instanceof ChatError) {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    const msg = error.message.toLowerCase();\n\n    // Network errors\n    if (isNetworkError(msg)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.NETWORK,\n        retryable: true,\n        cause: error,\n      });\n    }\n\n    // Timeout errors\n    if (isTimeoutPattern(msg)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.TIMEOUT,\n        retryable: true,\n        cause: error,\n      });\n    }\n\n    // Zod validation errors\n    if (isZodError(error)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.INVALID_INPUT,\n        retryable: false,\n        cause: error,\n      });\n    }\n\n    // HTTP status code errors\n    const statusCode = extractStatusCode(error);\n    if (statusCode !== null) {\n      return classifyByStatusCode(statusCode, error);\n    }\n\n    // Context overflow patterns\n    if (isContextOverflow(msg)) {\n      return new ChatError(error.message, {\n        code: ChatErrorCode.CONTEXT_OVERFLOW,\n        retryable: false,\n        cause: error,\n      });\n    }\n  }\n\n  // Unknown errors\n  const message =\n    error instanceof Error ? error.message : String(error);\n  return new ChatError(message, {\n    code: ChatErrorCode.PROVIDER_ERROR,\n    retryable: false,\n    cause: error,\n  });\n}\n\n// ─── Classification Helpers ────────────────────────────────────\n\nconst NETWORK_PATTERNS = [\n  \"econnrefused\",\n  \"econnreset\",\n  \"enotfound\",\n  \"etimedout\",\n  \"enetunreach\",\n  \"epipe\",\n  \"fetch failed\",\n  \"network error\",\n  \"network request failed\",\n  \"failed to fetch\",\n  \"dns lookup failed\",\n] as const;\n\nfunction isNetworkError(msg: string): boolean {\n  return NETWORK_PATTERNS.some((p) => msg.includes(p));\n}\n\nfunction isTimeoutPattern(msg: string): boolean {\n  return (\n    msg.includes(\"timeout\") ||\n    msg.includes(\"timed out\") ||\n    msg.includes(\"deadline exceeded\") ||\n    msg.includes(\"aborted due to timeout\")\n  );\n}\n\nfunction isZodError(error: Error): boolean {\n  return (\n    error.name === \"ZodError\" ||\n    (\"issues\" in error && Array.isArray((error as unknown as Record<string, unknown>).issues))\n  );\n}\n\nfunction extractStatusCode(error: Error): number | null {\n  const errRecord = error as unknown as Record<string, unknown>;\n  if (typeof errRecord.status === \"number\") return errRecord.status;\n  if (typeof errRecord.statusCode === \"number\") return errRecord.statusCode;\n\n  // Check message for HTTP status codes\n  const match = error.message.match(/\\b(4\\d{2}|5\\d{2})\\b/);\n  return match ? parseInt(match[1], 10) : null;\n}\n\nfunction classifyByStatusCode(status: number, error: Error): ChatError {\n  if (status === 401 || status === 403) {\n    return new ChatError(error.message, {\n      code: ChatErrorCode.AUTH_INVALID,\n      retryable: false,\n      cause: error,\n    });\n  }\n  if (status === 429) {\n    const retryAfterSeconds = extractRetryAfter(error);\n    return new ChatError(error.message, {\n      code: ChatErrorCode.RATE_LIMIT,\n      retryable: true,\n      retryAfter: retryAfterSeconds != null ? retryAfterSeconds * 1000 : undefined,\n      cause: error,\n    });\n  }\n  if (status >= 500) {\n    return new ChatError(error.message, {\n      code: ChatErrorCode.PROVIDER_ERROR,\n      retryable: true,\n      cause: error,\n    });\n  }\n  // 4xx other than auth/rate-limit → invalid input\n  if (status >= 400 && status < 500) {\n    return new ChatError(error.message, {\n      code: ChatErrorCode.INVALID_INPUT,\n      retryable: false,\n      cause: error,\n    });\n  }\n  return new ChatError(error.message, {\n    code: ChatErrorCode.NETWORK,\n    retryable: true,\n    cause: error,\n  });\n}\n\nfunction extractRetryAfter(error: Error): number | undefined {\n  const errRecord = error as unknown as Record<string, unknown>;\n  if (typeof errRecord.retryAfter === \"number\") return errRecord.retryAfter;\n  const match = error.message.match(/retry.after[:\\s]*(\\d+)/i);\n  return match ? parseInt(match[1], 10) : undefined;\n}\n\nfunction isContextOverflow(msg: string): boolean {\n  return (\n    msg.includes(\"context length exceeded\") ||\n    msg.includes(\"maximum context length\") ||\n    msg.includes(\"context window\") ||\n    msg.includes(\"token limit\") ||\n    msg.includes(\"too many tokens\")\n  );\n}\n\n// ─── Retry Strategy ────────────────────────────────────────────\n\n/** Strategy for computing retry delays */\nexport interface RetryStrategy {\n  /** Return delay in ms for the given attempt (0-based), or null to stop */\n  nextDelay(attempt: number, error: ChatError): number | null;\n}\n\n/** Options for ExponentialBackoffStrategy */\nexport interface ExponentialBackoffOptions {\n  /** Base delay in ms (default: 1000) */\n  baseMs?: number;\n  /** Maximum delay in ms (default: 30000) */\n  maxMs?: number;\n  /** Maximum number of attempts (default: 3) */\n  maxAttempts?: number;\n  /** Jitter factor 0–1 (default: 0.1) */\n  jitter?: number;\n}\n\n/** Exponential backoff with optional jitter */\nexport class ExponentialBackoffStrategy implements RetryStrategy {\n  private readonly baseMs: number;\n  private readonly maxMs: number;\n  private readonly maxAttempts: number;\n  private readonly jitter: number;\n\n  constructor(options?: ExponentialBackoffOptions) {\n    this.baseMs = options?.baseMs ?? 1000;\n    this.maxMs = options?.maxMs ?? 30000;\n    this.maxAttempts = options?.maxAttempts ?? 3;\n    this.jitter = Math.max(0, Math.min(1, options?.jitter ?? 0.1));\n  }\n\n  nextDelay(attempt: number, error: ChatError): number | null {\n    if (attempt >= this.maxAttempts) return null;\n    if (!error.retryable) return null;\n\n    // Rate-limit errors with retryAfter (already in ms) take priority\n    if (error.code === ChatErrorCode.RATE_LIMIT && error.retryAfter) {\n      return error.retryAfter;\n    }\n\n    const delay = Math.min(this.baseMs * Math.pow(2, attempt), this.maxMs);\n    const jitterAmount = delay * this.jitter * (Math.random() * 2 - 1);\n    return Math.max(0, Math.round(delay + jitterAmount));\n  }\n}\n\n// ─── Retry Execution ───────────────────────────────────────────\n\n/** Options for withRetry execution */\nexport interface RetryOptions {\n  /** Abort signal to cancel retries */\n  signal?: AbortSignal;\n  /** Called before each retry with the error and delay */\n  onRetry?: (error: ChatError, attempt: number, delayMs: number) => void;\n}\n\n/**\n * Execute an async function with automatic retries using the provided strategy.\n * Respects ChatError.retryable and ChatError.retryAfter.\n * Classifies non-ChatError errors before deciding on retry.\n *\n * @param fn - Async function to execute\n * @param strategy - Retry strategy providing delay calculations\n * @param options - Optional abort signal and retry callback\n * @returns Result of fn on success\n * @throws ChatError when all retries exhausted or error is non-retryable\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  strategy: RetryStrategy,\n  options?: RetryOptions,\n): Promise<T> {\n  let attempt = 0;\n\n  for (;;) {\n    try {\n      return await fn();\n    } catch (raw) {\n      const error = classifyError(raw);\n      const delay = strategy.nextDelay(attempt, error);\n\n      if (delay === null) {\n        throw error;\n      }\n\n      if (options?.signal?.aborted) {\n        throw error;\n      }\n\n      options?.onRetry?.(error, attempt, delay);\n\n      await sleep(delay, options?.signal);\n      attempt++;\n    }\n  }\n}\n\n/**\n * Type guard: check if an error is retryable\n * @param error - The error to check\n * @returns True if error is a retryable ChatError\n */\nexport function isRetryable(error: unknown): boolean {\n  if (error instanceof ChatError) {\n    return error.retryable;\n  }\n  const classified = classifyError(error);\n  return classified.retryable;\n}\n\n// ─── Internal Helpers ──────────────────────────────────────────\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new ChatError(\"Retry aborted\", { code: ChatErrorCode.ABORTED }));\n      return;\n    }\n\n    const timer = setTimeout(resolve, ms);\n\n    signal?.addEventListener(\n      \"abort\",\n      () => {\n        clearTimeout(timer);\n        reject(new ChatError(\"Retry aborted\", { code: ChatErrorCode.ABORTED }));\n      },\n      { once: true },\n    );\n  });\n}\n","/**\n * @witqq/agent-sdk/chat/state\n *\n * Validated state machines for runtime, message, and tool-call lifecycles.\n * Generic StateMachine<S> with declarative transition maps.\n */\n\nimport type { RuntimeStatus, MessageStatus, ToolCallStatus } from \"./core.js\";\nimport { ChatError, ChatErrorCode } from \"./errors.js\";\n\n// ─── Generic State Machine ─────────────────────────────────────\n\n/** Map of allowed transitions: current state → set of valid next states */\nexport type TransitionMap<S extends string> = Readonly<Record<S, readonly S[]>>;\n\n/**\n * Generic validated state machine.\n * Enforces that every transition is declared in the transition map.\n * Throws ChatError(INVALID_TRANSITION) on illegal moves.\n */\nexport class StateMachine<S extends string> {\n  private _current: S;\n\n  constructor(\n    readonly initial: S,\n    readonly transitions: TransitionMap<S>,\n  ) {\n    this._current = initial;\n  }\n\n  /** Current state */\n  get current(): S {\n    return this._current;\n  }\n\n  /**\n   * Check whether transitioning to `next` is allowed from current state\n   * @param next - Target state to check\n   * @returns True if transition is allowed\n   */\n  canTransition(next: S): boolean {\n    const allowed = this.transitions[this._current];\n    return allowed !== undefined && allowed.includes(next);\n  }\n\n  /**\n   * Transition to `next` state.\n   * @throws ChatError(INVALID_TRANSITION) if the transition is not allowed\n   */\n  transition(next: S): void {\n    if (!this.canTransition(next)) {\n      throw new ChatError(\n        `Invalid transition: ${this._current} → ${next}`,\n        { code: ChatErrorCode.INVALID_TRANSITION },\n      );\n    }\n    this._current = next;\n  }\n\n  /** Reset to initial state */\n  reset(): void {\n    this._current = this.initial;\n  }\n}\n\n// ─── Transition Maps ───────────────────────────────────────────\n\n/** Allowed transitions for RuntimeStatus (idle → streaming/disposed, etc.) */\nexport const RUNTIME_TRANSITIONS: TransitionMap<RuntimeStatus> = {\n  idle: [\"streaming\", \"disposed\"],\n  streaming: [\"idle\", \"error\", \"disposed\"],\n  error: [\"idle\", \"disposed\"],\n  disposed: [],\n};\n\n/** Allowed transitions for MessageStatus (pending → streaming → complete, etc.) */\nexport const MESSAGE_TRANSITIONS: TransitionMap<MessageStatus> = {\n  pending: [\"streaming\", \"error\", \"cancelled\"],\n  streaming: [\"complete\", \"error\", \"cancelled\"],\n  complete: [],\n  error: [],\n  cancelled: [],\n};\n\n/** Allowed transitions for ToolCallStatus (pending → running → complete, etc.) */\nexport const TOOL_CALL_TRANSITIONS: TransitionMap<ToolCallStatus> = {\n  pending: [\"running\", \"requires_approval\", \"error\"],\n  running: [\"complete\", \"error\"],\n  requires_approval: [\"running\", \"denied\", \"error\"],\n  complete: [],\n  error: [],\n  denied: [],\n};\n\n// ─── Pre-configured Factories ──────────────────────────────────\n\n/** Create a RuntimeStatus state machine starting at \"idle\" */\nexport function createRuntimeStateMachine(): StateMachine<RuntimeStatus> {\n  return new StateMachine<RuntimeStatus>(\"idle\", RUNTIME_TRANSITIONS);\n}\n\n/** Create a MessageStatus state machine starting at \"pending\" */\nexport function createMessageStateMachine(): StateMachine<MessageStatus> {\n  return new StateMachine<MessageStatus>(\"pending\", MESSAGE_TRANSITIONS);\n}\n\n/** Create a ToolCallStatus state machine starting at \"pending\" */\nexport function createToolCallStateMachine(): StateMachine<ToolCallStatus> {\n  return new StateMachine<ToolCallStatus>(\"pending\", TOOL_CALL_TRANSITIONS);\n}\n\n// ─── Reentrancy Guard ──────────────────────────────────────────\n\n/**\n * Guards against concurrent send() calls in a chat runtime.\n * acquire() before work, release() after (use try/finally).\n * Throws ChatError(REENTRANCY) if already acquired.\n */\nexport class ChatReentrancyGuard {\n  private _acquired = false;\n\n  /** Whether the guard is currently held */\n  get isAcquired(): boolean {\n    return this._acquired;\n  }\n\n  /**\n   * Acquire the guard. Throws if already acquired.\n   * @throws ChatError with code REENTRANCY\n   */\n  acquire(): void {\n    if (this._acquired) {\n      throw new ChatError(\n        \"Concurrent operation detected: a send is already in progress\",\n        { code: ChatErrorCode.REENTRANCY },\n      );\n    }\n    this._acquired = true;\n  }\n\n  /** Release the guard. Safe to call even if not acquired. */\n  release(): void {\n    this._acquired = false;\n  }\n}\n\n// ─── Abort Controller ──────────────────────────────────────────\n\n/**\n * Abort controller with external signal linking.\n * Wraps an AbortController and optionally links an external AbortSignal\n * so aborting either side cancels the operation.\n */\nexport class ChatAbortController {\n  private readonly _controller: AbortController;\n  private readonly _onExternalAbort?: () => void;\n  private readonly _externalSignal?: AbortSignal;\n\n  constructor(externalSignal?: AbortSignal) {\n    this._controller = new AbortController();\n    this._externalSignal = externalSignal;\n\n    if (externalSignal) {\n      // If external signal already aborted, abort immediately\n      if (externalSignal.aborted) {\n        this._controller.abort(externalSignal.reason);\n      } else {\n        // Link: external abort → our controller\n        this._onExternalAbort = () => {\n          this._controller.abort(externalSignal.reason);\n        };\n        externalSignal.addEventListener(\"abort\", this._onExternalAbort, { once: true });\n      }\n    }\n  }\n\n  /** The AbortSignal for this controller */\n  get signal(): AbortSignal {\n    return this._controller.signal;\n  }\n\n  /** Whether the operation has been aborted */\n  get isAborted(): boolean {\n    return this._controller.signal.aborted;\n  }\n\n  /**\n   * Abort the operation.\n   * @param reason - Optional abort reason\n   */\n  abort(reason?: unknown): void {\n    this._controller.abort(reason);\n  }\n\n  /** Clean up external signal listener to prevent memory leaks */\n  dispose(): void {\n    if (this._onExternalAbort && this._externalSignal) {\n      this._externalSignal.removeEventListener(\"abort\", this._onExternalAbort);\n    }\n  }\n}\n"]}