@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/{errors-BgJH9PHi.d.cts → errors-CLOAyuiv.d.ts}

@@ -1,15 +1,25 @@
-import { Q as RunOperation } from './run-BYSHf58D.cjs';
+import { T as TheokitAgentError, a as ErrorCode, E as ErrorMetadata } from './errors-base-B5g01neU.js';
+import { K as RunOperation } from './run-CTAdRU3U.js';
 
 /**
+ * Owner: `internal/budget/` (4 of 6 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for the Budget enforcement primitive
  * (ADRs D375, D382-D387). The runtime facade lives in `budget.ts`.
  *
  * @public
  */
 /**
- * Scope of a budget — where the charge is attributed. v1 supports
- * `process` (shared global) only; `agent` and `call` reserved for
- * v0.2 multi-tenant scenarios.
+ * Accounting scope for a budget.
+ *
+ * ONLY `"process"` is implemented, and `Budget.create` now REFUSES the other two with
+ * `unimplemented_budget_scope`. It used to accept them: nothing outside the registry read `scope`, so
+ * a caller asking for per-agent accounting silently got process-wide accounting — a cost control
+ * reporting the wrong number, which is worse than the missing feature.
+ *
+ * The union is not narrowed to `"process"` here because that is a breaking change to a published
+ * type and belongs to a major. Widening it back when the scopes are built is non-breaking.
  */
 type BudgetScope = "agent" | "call" | "process";
 /**
@@ -90,13 +100,64 @@ interface BudgetSnapshot {
 }
 
 /**
- * Finite, machine-readable error codes for provider-originated errors
- * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively
- * — adding a new variant is an explicit decision + test coverage.
+ * Errors raised by the Task API (`src/task.ts`).
+ *
+ * One actor, one module: these three are about task identity and task lifecycle, and they change
+ * when the Task surface changes rather than when the agent-run surface does. They extend
+ * `TheokitAgentError` like every other error in this package — the hierarchy is the contract, and
+ * `tests/lint/every-error-is-in-the-hierarchy.test.ts` enforces it wherever the class lives.
+ *
+ * Re-exported from `errors.ts`, so `@theokit/sdk/errors` still names every error in one place.
+ *
+ * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not
+ * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and
+ * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.
+ * `tsc --noEmit` stays clean and the declaration rollup fails with `"X" is not exported by "..."`.
+ * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment
+ * EXPLAINING the trap quoted the tag verbatim and re-armed it.
+ */
+
+/**
+ * Thrown when a user-supplied task ID violates the grammar
+ * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter
+ * prefix (`wf-` / `b-` / `cron-`, EC-5).
+ *
+ * @public
+ */
+declare class InvalidTaskIdError extends TheokitAgentError {
+    readonly name: string;
+    readonly taskId: string;
+    constructor(message: string, taskId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `Task.subscribe(id)` is called for a task that has been
+ * evicted, never submitted, or evicted after retention (D373).
+ *
+ * @public
+ */
+declare class TaskNotFoundError extends TheokitAgentError {
+    readonly name: string;
+    readonly taskId: string;
+    constructor(taskId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
+ * task observability is deferred until Theo PaaS GA.
  *
  * @public
  */
-type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" | "server_error" | "context_too_long" | "content_filtered" | "model_unavailable" | "network" | "quota_exceeded" | "unknown";
+declare class UnsupportedTaskOperationError extends TheokitAgentError {
+    readonly name: string;
+    readonly operation: string;
+    constructor(operation: string, options?: {
+        cause?: unknown;
+    });
+}
+
 /**
  * T1.1 — closed literal union for `AgentRunError.code`. The previous
  * `(string & {})` escape hatch let arbitrary strings slip into the type
@@ -145,52 +206,6 @@ type AgentRunErrorCode = KnownAgentRunErrorCode;
  * @public
  */
 declare function coerceToKnownAgentRunErrorCode(code: string | undefined): KnownAgentRunErrorCode;
-/**
- * Structured context for errors that originated from a provider HTTP
- * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),
- * surface actionable diagnostics (`provider`, `endpoint`), and inspect the
- * raw response body when needed (`raw`, capped at ~2KB by the mapper).
- *
- * @public
- */
-interface ErrorMetadata {
-    /** Provider canonical name (e.g., `"anthropic"`, `"openai"`, `"openrouter"`, `"gemini"`). */
-    provider: string;
-    /** HTTP endpoint that failed (e.g., `"/v1/messages"`, `"/v1/chat/completions"`). */
-    endpoint: string;
-    /** Machine-readable error code (finite enum). */
-    code: ErrorCode;
-    /** HTTP status code if applicable. */
-    statusCode?: number;
-    /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */
-    retryAfter?: number;
-    /** Raw response body for debugging (truncated to ~2KB by the mapper). */
-    raw?: unknown;
-}
-/**
- * Base class for all errors thrown by `@theokit/sdk`.
- *
- * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`
- * are populated for server-originated errors when available. `metadata`
- * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when
- * the error originated from a provider HTTP call.
- *
- * @public
- */
-declare class TheokitAgentError extends Error {
-    readonly name: string;
-    readonly isRetryable: boolean;
-    readonly code?: string;
-    readonly protoErrorCode?: string;
-    readonly metadata?: ErrorMetadata;
-    constructor(message: string, options?: {
-        isRetryable?: boolean;
-        code?: string;
-        protoErrorCode?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
 /**
  * Invalid API key, not logged in, insufficient permissions.
  *
@@ -430,46 +445,6 @@ declare class MemoryAdapterError extends TheokitAgentError {
         metadata?: ErrorMetadata;
     });
 }
-/**
- * Thrown when a user-supplied task ID violates the grammar
- * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter
- * prefix (`wf-` / `b-` / `cron-`, EC-5).
- *
- * @public
- */
-declare class InvalidTaskIdError extends TheokitAgentError {
-    readonly name: string;
-    readonly taskId: string;
-    constructor(message: string, taskId: string, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when `Task.subscribe(id)` is called for a task that has been
- * evicted, never submitted, or evicted after retention (D373).
- *
- * @public
- */
-declare class TaskNotFoundError extends TheokitAgentError {
-    readonly name: string;
-    readonly taskId: string;
-    constructor(taskId: string, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
- * task observability is deferred until Theo PaaS GA.
- *
- * @public
- */
-declare class UnsupportedTaskOperationError extends TheokitAgentError {
-    readonly name: string;
-    readonly operation: string;
-    constructor(operation: string, options?: {
-        cause?: unknown;
-    });
-}
 /**
  * Thrown by `Budget` enforcement (ADR D386) when a `mode: "block"`
  * budget would be exceeded by the upcoming LLM call. The caller catches a
@@ -527,5 +502,68 @@ declare class UnsupportedBudgetOperationError extends TheokitAgentError {
         cause?: unknown;
     });
 }
+/**
+ * Why a structured-output call failed.
+ *
+ * A named union rather than a repeated inline one: the narrow form was written out at the class AND
+ * in `agent-generate.ts`'s local type, so widening it meant finding both. One name, one edit.
+ *
+ * @public
+ */
+type StructuredOutputErrorCode = 
+/** The model did not call the forced output tool. The original meaning, unchanged. */
+"no_tool_call"
+/** The tool was called and its arguments did not parse against the schema. */
+ | "parse_failed"
+/** The agent run errored before there was an answer to structure. */
+ | "upstream_run_failed"
+/** The agent run was cancelled before there was an answer to structure. */
+ | "run_cancelled"
+/** The loop finished with tools only and produced no text to structure. */
+ | "no_text_answer";
+/**
+ * The failure contract shared by `generateObject` and `streamObject`.
+ *
+ * Both entry points run the same rule — up to `maxRetries` attempts; if the model never called the
+ * output tool, fail as `no_tool_call`, naming the underlying run error when there was one; if the
+ * schema never parsed, fail as `parse_failed` — and both declared their own error class for it, with
+ * byte-identical user-facing strings. A change to the taxonomy or the wording had to be made twice,
+ * or the two APIs would start describing the same failure differently.
+ *
+ * It extends `TheokitAgentError` because every typed error the SDK publishes does, and these two did
+ * not: a consumer catching `TheokitAgentError` — the documented way to catch anything this SDK throws
+ * — silently missed both, and neither carried `isRetryable`.
+ *
+ * It lives HERE rather than beside the two entry points because it is an error class and this is the
+ * error module. The first home was `internal/structured-output-helpers.ts`, and rollup-plugin-dts
+ * could not resolve it from there when bundling the root declaration — a failure `tsc --noEmit`
+ * does not see, because it never runs the declaration rollup.
+ *
+ * `isRetryable` is false. Both codes mean the model did not produce the requested shape; the caller's
+ * own `maxRetries` has already been spent by the time either is thrown, so an outer retry loop would
+ * re-run a sequence that already gave up.
+ *
+ * The two public names stay DISTINCT subclasses rather than aliases of this one. Collapsing them
+ * would make `streamObjectError instanceof GenerateObjectError` true, which is a semantic widening
+ * nobody asked for; the duplication being removed is the contract, not the identity.
+ *
+ * @public
+ */
+declare class StructuredOutputError extends TheokitAgentError {
+    readonly name: string;
+    /**
+     * Why the structuring failed.
+     *
+     * Three of these are new, and they name causes the SDK ALREADY distinguished in prose while
+     * reporting all three as `no_tool_call`: an upstream run that errored, a run that was cancelled,
+     * and a tool-only completion with no text to structure. Three tests asserted the byte-identical
+     * oracle for three genuinely different setups — swap any two and all three still passed — because
+     * the only thing that differed was the free-text message.
+     *
+     * `no_tool_call` keeps its original meaning: the model did not call the forced output tool.
+     */
+    readonly code: "no_tool_call" | "parse_failed" | "upstream_run_failed" | "run_cancelled" | "no_text_answer";
+    constructor(code: "no_tool_call" | "parse_failed" | "upstream_run_failed" | "run_cancelled" | "no_text_answer", message: string, cause?: unknown);
+}
 
-export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, type ErrorMetadata as E, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, TheokitAgentError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, type ErrorCode as m, InvalidTaskIdError as n, type MemoryAdapterErrorCode as o, TaskNotFoundError as p, UnsupportedBudgetOperationError as q, UnsupportedRunOperationError as r, UnsupportedTaskOperationError as s, isTransientError as t, CredentialPoolExhaustedError as u, coerceToKnownAgentRunErrorCode as v };
+export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, StructuredOutputError as S, TaskNotFoundError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, InvalidTaskIdError as m, type MemoryAdapterErrorCode as n, UnsupportedBudgetOperationError as o, UnsupportedRunOperationError as p, UnsupportedTaskOperationError as q, isTransientError as r, CredentialPoolExhaustedError as s, type StructuredOutputErrorCode as t, coerceToKnownAgentRunErrorCode as u };

package/dist/{errors-C5fJUqLk.d.ts → errors-DrDEgyz1.d.cts}

@@ -1,15 +1,25 @@
-import { Q as RunOperation } from './run-BYSHf58D.js';
+import { T as TheokitAgentError, a as ErrorCode, E as ErrorMetadata } from './errors-base-B5g01neU.cjs';
+import { K as RunOperation } from './run-CTAdRU3U.cjs';
 
 /**
+ * Owner: `internal/budget/` (4 of 6 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for the Budget enforcement primitive
  * (ADRs D375, D382-D387). The runtime facade lives in `budget.ts`.
  *
  * @public
  */
 /**
- * Scope of a budget — where the charge is attributed. v1 supports
- * `process` (shared global) only; `agent` and `call` reserved for
- * v0.2 multi-tenant scenarios.
+ * Accounting scope for a budget.
+ *
+ * ONLY `"process"` is implemented, and `Budget.create` now REFUSES the other two with
+ * `unimplemented_budget_scope`. It used to accept them: nothing outside the registry read `scope`, so
+ * a caller asking for per-agent accounting silently got process-wide accounting — a cost control
+ * reporting the wrong number, which is worse than the missing feature.
+ *
+ * The union is not narrowed to `"process"` here because that is a breaking change to a published
+ * type and belongs to a major. Widening it back when the scopes are built is non-breaking.
  */
 type BudgetScope = "agent" | "call" | "process";
 /**
@@ -90,13 +100,64 @@ interface BudgetSnapshot {
 }
 
 /**
- * Finite, machine-readable error codes for provider-originated errors
- * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively
- * — adding a new variant is an explicit decision + test coverage.
+ * Errors raised by the Task API (`src/task.ts`).
+ *
+ * One actor, one module: these three are about task identity and task lifecycle, and they change
+ * when the Task surface changes rather than when the agent-run surface does. They extend
+ * `TheokitAgentError` like every other error in this package — the hierarchy is the contract, and
+ * `tests/lint/every-error-is-in-the-hierarchy.test.ts` enforces it wherever the class lives.
+ *
+ * Re-exported from `errors.ts`, so `@theokit/sdk/errors` still names every error in one place.
+ *
+ * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not
+ * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and
+ * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.
+ * `tsc --noEmit` stays clean and the declaration rollup fails with `"X" is not exported by "..."`.
+ * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment
+ * EXPLAINING the trap quoted the tag verbatim and re-armed it.
+ */
+
+/**
+ * Thrown when a user-supplied task ID violates the grammar
+ * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter
+ * prefix (`wf-` / `b-` / `cron-`, EC-5).
+ *
+ * @public
+ */
+declare class InvalidTaskIdError extends TheokitAgentError {
+    readonly name: string;
+    readonly taskId: string;
+    constructor(message: string, taskId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `Task.subscribe(id)` is called for a task that has been
+ * evicted, never submitted, or evicted after retention (D373).
+ *
+ * @public
+ */
+declare class TaskNotFoundError extends TheokitAgentError {
+    readonly name: string;
+    readonly taskId: string;
+    constructor(taskId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
+ * task observability is deferred until Theo PaaS GA.
  *
  * @public
  */
-type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" | "server_error" | "context_too_long" | "content_filtered" | "model_unavailable" | "network" | "quota_exceeded" | "unknown";
+declare class UnsupportedTaskOperationError extends TheokitAgentError {
+    readonly name: string;
+    readonly operation: string;
+    constructor(operation: string, options?: {
+        cause?: unknown;
+    });
+}
+
 /**
  * T1.1 — closed literal union for `AgentRunError.code`. The previous
  * `(string & {})` escape hatch let arbitrary strings slip into the type
@@ -145,52 +206,6 @@ type AgentRunErrorCode = KnownAgentRunErrorCode;
  * @public
  */
 declare function coerceToKnownAgentRunErrorCode(code: string | undefined): KnownAgentRunErrorCode;
-/**
- * Structured context for errors that originated from a provider HTTP
- * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),
- * surface actionable diagnostics (`provider`, `endpoint`), and inspect the
- * raw response body when needed (`raw`, capped at ~2KB by the mapper).
- *
- * @public
- */
-interface ErrorMetadata {
-    /** Provider canonical name (e.g., `"anthropic"`, `"openai"`, `"openrouter"`, `"gemini"`). */
-    provider: string;
-    /** HTTP endpoint that failed (e.g., `"/v1/messages"`, `"/v1/chat/completions"`). */
-    endpoint: string;
-    /** Machine-readable error code (finite enum). */
-    code: ErrorCode;
-    /** HTTP status code if applicable. */
-    statusCode?: number;
-    /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */
-    retryAfter?: number;
-    /** Raw response body for debugging (truncated to ~2KB by the mapper). */
-    raw?: unknown;
-}
-/**
- * Base class for all errors thrown by `@theokit/sdk`.
- *
- * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`
- * are populated for server-originated errors when available. `metadata`
- * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when
- * the error originated from a provider HTTP call.
- *
- * @public
- */
-declare class TheokitAgentError extends Error {
-    readonly name: string;
-    readonly isRetryable: boolean;
-    readonly code?: string;
-    readonly protoErrorCode?: string;
-    readonly metadata?: ErrorMetadata;
-    constructor(message: string, options?: {
-        isRetryable?: boolean;
-        code?: string;
-        protoErrorCode?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
 /**
  * Invalid API key, not logged in, insufficient permissions.
  *
@@ -430,46 +445,6 @@ declare class MemoryAdapterError extends TheokitAgentError {
         metadata?: ErrorMetadata;
     });
 }
-/**
- * Thrown when a user-supplied task ID violates the grammar
- * `^[a-z0-9][a-z0-9_-]*$` (D368) OR starts with a reserved adapter
- * prefix (`wf-` / `b-` / `cron-`, EC-5).
- *
- * @public
- */
-declare class InvalidTaskIdError extends TheokitAgentError {
-    readonly name: string;
-    readonly taskId: string;
-    constructor(message: string, taskId: string, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when `Task.subscribe(id)` is called for a task that has been
- * evicted, never submitted, or evicted after retention (D373).
- *
- * @public
- */
-declare class TaskNotFoundError extends TheokitAgentError {
-    readonly name: string;
-    readonly taskId: string;
-    constructor(taskId: string, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when `CloudAgent` is asked to wrap a task (D370). Cloud
- * task observability is deferred until Theo PaaS GA.
- *
- * @public
- */
-declare class UnsupportedTaskOperationError extends TheokitAgentError {
-    readonly name: string;
-    readonly operation: string;
-    constructor(operation: string, options?: {
-        cause?: unknown;
-    });
-}
 /**
  * Thrown by `Budget` enforcement (ADR D386) when a `mode: "block"`
  * budget would be exceeded by the upcoming LLM call. The caller catches a
@@ -527,5 +502,68 @@ declare class UnsupportedBudgetOperationError extends TheokitAgentError {
         cause?: unknown;
     });
 }
+/**
+ * Why a structured-output call failed.
+ *
+ * A named union rather than a repeated inline one: the narrow form was written out at the class AND
+ * in `agent-generate.ts`'s local type, so widening it meant finding both. One name, one edit.
+ *
+ * @public
+ */
+type StructuredOutputErrorCode = 
+/** The model did not call the forced output tool. The original meaning, unchanged. */
+"no_tool_call"
+/** The tool was called and its arguments did not parse against the schema. */
+ | "parse_failed"
+/** The agent run errored before there was an answer to structure. */
+ | "upstream_run_failed"
+/** The agent run was cancelled before there was an answer to structure. */
+ | "run_cancelled"
+/** The loop finished with tools only and produced no text to structure. */
+ | "no_text_answer";
+/**
+ * The failure contract shared by `generateObject` and `streamObject`.
+ *
+ * Both entry points run the same rule — up to `maxRetries` attempts; if the model never called the
+ * output tool, fail as `no_tool_call`, naming the underlying run error when there was one; if the
+ * schema never parsed, fail as `parse_failed` — and both declared their own error class for it, with
+ * byte-identical user-facing strings. A change to the taxonomy or the wording had to be made twice,
+ * or the two APIs would start describing the same failure differently.
+ *
+ * It extends `TheokitAgentError` because every typed error the SDK publishes does, and these two did
+ * not: a consumer catching `TheokitAgentError` — the documented way to catch anything this SDK throws
+ * — silently missed both, and neither carried `isRetryable`.
+ *
+ * It lives HERE rather than beside the two entry points because it is an error class and this is the
+ * error module. The first home was `internal/structured-output-helpers.ts`, and rollup-plugin-dts
+ * could not resolve it from there when bundling the root declaration — a failure `tsc --noEmit`
+ * does not see, because it never runs the declaration rollup.
+ *
+ * `isRetryable` is false. Both codes mean the model did not produce the requested shape; the caller's
+ * own `maxRetries` has already been spent by the time either is thrown, so an outer retry loop would
+ * re-run a sequence that already gave up.
+ *
+ * The two public names stay DISTINCT subclasses rather than aliases of this one. Collapsing them
+ * would make `streamObjectError instanceof GenerateObjectError` true, which is a semantic widening
+ * nobody asked for; the duplication being removed is the contract, not the identity.
+ *
+ * @public
+ */
+declare class StructuredOutputError extends TheokitAgentError {
+    readonly name: string;
+    /**
+     * Why the structuring failed.
+     *
+     * Three of these are new, and they name causes the SDK ALREADY distinguished in prose while
+     * reporting all three as `no_tool_call`: an upstream run that errored, a run that was cancelled,
+     * and a tool-only completion with no text to structure. Three tests asserted the byte-identical
+     * oracle for three genuinely different setups — swap any two and all three still passed — because
+     * the only thing that differed was the free-text message.
+     *
+     * `no_tool_call` keeps its original meaning: the model did not call the forced output tool.
+     */
+    readonly code: "no_tool_call" | "parse_failed" | "upstream_run_failed" | "run_cancelled" | "no_text_answer";
+    constructor(code: "no_tool_call" | "parse_failed" | "upstream_run_failed" | "run_cancelled" | "no_text_answer", message: string, cause?: unknown);
+}
 
-export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, type ErrorMetadata as E, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, TheokitAgentError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, type ErrorCode as m, InvalidTaskIdError as n, type MemoryAdapterErrorCode as o, TaskNotFoundError as p, UnsupportedBudgetOperationError as q, UnsupportedRunOperationError as r, UnsupportedTaskOperationError as s, isTransientError as t, CredentialPoolExhaustedError as u, coerceToKnownAgentRunErrorCode as v };
+export { AgentDisposedError as A, type BudgetOptions as B, ConfigurationError as C, IntegrationNotConnectedError as I, type KnownAgentRunErrorCode as K, MemoryAdapterError as M, NetworkError as N, RateLimitError as R, StructuredOutputError as S, TaskNotFoundError as T, UnknownAgentError as U, type BudgetHandle as a, type BudgetSnapshot as b, AgentRunError as c, type AgentRunErrorCode as d, AuthenticationError as e, type BudgetExceedEvent as f, BudgetExceededError as g, type BudgetLimit as h, type BudgetMode as i, type BudgetScope as j, type BudgetThresholdEvent as k, type BudgetWindow as l, InvalidTaskIdError as m, type MemoryAdapterErrorCode as n, UnsupportedBudgetOperationError as o, UnsupportedRunOperationError as p, UnsupportedTaskOperationError as q, isTransientError as r, CredentialPoolExhaustedError as s, type StructuredOutputErrorCode as t, coerceToKnownAgentRunErrorCode as u };

package/dist/errors-base-B5g01neU.d.cts

@@ -0,0 +1,75 @@
+/**
+ * The root of the SDK error hierarchy, and the two types it is built from.
+ *
+ * A LEAF module on purpose: every other error in this package extends `TheokitAgentError`, and
+ * `errors.ts` re-exports the ones that live in their own files. If the root lived in that catalogue,
+ * each sibling would import it from a file that imports the sibling — a cycle madge reports and
+ * `tests/architecture/no-cycles-at-all.test.ts` fails on. `types/messages-base.ts` exists for the
+ * same reason, one layer over.
+ *
+ * Re-exported from `errors.ts`, so `@theokit/sdk/errors` is unchanged and consumers keep catching
+ * `TheokitAgentError` from where the README tells them to.
+ *
+ * NOTE ON THE MODULE TAG: this header deliberately carries no internal-visibility tag, and does not
+ * even name one — TypeScript attaches a file-leading docblock to the FIRST declaration below it, and
+ * `stripInternal: true` (tsconfig.base) then deletes that declaration from the emitted `.d.ts`.
+ * `tsc --noEmit` stays clean and the declaration rollup fails with `"X" is not exported by "..."`.
+ * Measured twice on this file on 2026-09-01: once with the tag, and again when the comment
+ * EXPLAINING the trap quoted the tag verbatim and re-armed it.
+ */
+/**
+ * Finite, machine-readable error codes for provider-originated errors
+ * (ADR D66). Consumers can `switch (err.metadata?.code)` exhaustively
+ * — adding a new variant is an explicit decision + test coverage.
+ *
+ * @public
+ */
+type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" | "server_error" | "context_too_long" | "content_filtered" | "model_unavailable" | "network" | "quota_exceeded" | "unknown";
+/**
+ * Structured context for errors that originated from a provider HTTP
+ * call (ADR D65). Lets callers retry with the right backoff (`retryAfter`),
+ * surface actionable diagnostics (`provider`, `endpoint`), and inspect the
+ * raw response body when needed (`raw`, capped at ~2KB by the mapper).
+ *
+ * @public
+ */
+interface ErrorMetadata {
+    /** Provider canonical name (e.g., `"anthropic"`, `"openai"`, `"openrouter"`, `"gemini"`). */
+    provider: string;
+    /** HTTP endpoint that failed (e.g., `"/v1/messages"`, `"/v1/chat/completions"`). */
+    endpoint: string;
+    /** Machine-readable error code (finite enum). */
+    code: ErrorCode;
+    /** HTTP status code if applicable. */
+    statusCode?: number;
+    /** Seconds to wait before retry, per provider's `retry-after` header (numeric form only). */
+    retryAfter?: number;
+    /** Raw response body for debugging (truncated to ~2KB by the mapper). */
+    raw?: unknown;
+}
+/**
+ * Base class for all errors thrown by `@theokit/sdk`.
+ *
+ * Use `isRetryable` to drive retry/backoff logic. `code` and `protoErrorCode`
+ * are populated for server-originated errors when available. `metadata`
+ * (ADR D65) carries structured `{ provider, endpoint, code, ... }` when
+ * the error originated from a provider HTTP call.
+ *
+ * @public
+ */
+declare class TheokitAgentError extends Error {
+    readonly name: string;
+    readonly isRetryable: boolean;
+    readonly code?: string;
+    readonly protoErrorCode?: string;
+    readonly metadata?: ErrorMetadata;
+    constructor(message: string, options?: {
+        isRetryable?: boolean;
+        code?: string;
+        protoErrorCode?: string;
+        cause?: unknown;
+        metadata?: ErrorMetadata;
+    });
+}
+
+export { type ErrorMetadata as E, TheokitAgentError as T, type ErrorCode as a };