@theokit/sdk 4.24.0 → 4.26.0

package/dist/errors.d.ts

@@ -1,424 +1,3 @@
-import type { RunOperation } from "./types/run.js";
-/**
- * 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
- */
-export type ErrorCode = "rate_limit" | "auth_failed" | "invalid_request" | "timeout" | "server_error" | "context_too_long" | "content_filtered" | "model_unavailable" | "network" | "quota_exceeded" | "unknown";
-/**
- * Codes used by {@link AgentRunError} (Production-Readiness #3, ADR D311).
- *
- * Superset of {@link ErrorCode} extended with codes that do NOT originate
- * from a provider HTTP response:
- *
- * - `quota_exceeded` — billing limit hit (provider 402 or signalled error)
- * - `tool_runtime_error` — custom tool handler threw inside dispatch
- * - `aborted` — caller's `AbortSignal` fired (Phase 4)
- * - `invalid_model` — model id rejected by provider (400 "model not found")
- * - `safety_blocked` — provider safety filter blocked req or resp
- * - `provider_unreachable` — DNS/TCP/timeout/5xx at transport boundary
- *
- * The `& {}` tail keeps the literal-union ergonomics (autocomplete) while
- * accepting any string for forward compatibility with constructor calls
- * that pass arbitrary code values (legacy callers).
- *
- * @public
- */
-/**
- * T1.1 — closed literal union for `AgentRunError.code`. The previous
- * `(string & {})` escape hatch let arbitrary strings slip into the type
- * surface and defeated exhaustive `switch (code)` discrimination. This is
- * the canonical closed form. `AgentRunErrorCode` is re-aliased below for
- * source-level back-compat.
- *
- * Adding a new code: append the literal here AND audit every `switch (err.code)`
- * in callers. Type-checker enforces the audit via the `default: assertNever(code)`
- * convention.
- *
- * @public
- */
-export type KnownAgentRunErrorCode = ErrorCode | "quota_exceeded" | "tool_runtime_error" | "aborted" | "invalid_model" | "safety_blocked" | "provider_unreachable";
-/**
- * Back-compat alias of {@link KnownAgentRunErrorCode}. Pre-T1.1 callers that
- * imported `AgentRunErrorCode` keep working; new code SHOULD prefer
- * `KnownAgentRunErrorCode` to make the closed-union intent explicit.
- *
- * @public
- */
-export type AgentRunErrorCode = 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
- */
-export 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
- */
-export 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.
- *
- * @public
- */
-export declare class AuthenticationError extends TheokitAgentError {
-    readonly name: string;
-    constructor(message: string, options?: {
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Too many requests or usage limits exceeded.
- *
- * @public
- */
-export declare class RateLimitError extends TheokitAgentError {
-    readonly name: string;
-    constructor(message: string, options?: {
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Invalid model, bad request parameters, malformed options.
- *
- * @public
- */
-export declare class ConfigurationError extends TheokitAgentError {
-    readonly name: string;
-    constructor(message: string, options?: {
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Thrown when creating a cloud agent for a repo whose SCM provider is not
- * connected. Use `helpUrl` to point the user at the right reconnect flow.
- *
- * @public
- */
-export declare class IntegrationNotConnectedError extends ConfigurationError {
-    readonly name: string;
-    readonly provider: string;
-    readonly helpUrl: string;
-    constructor(message: string, options: {
-        provider: string;
-        helpUrl: string;
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Service unavailable, timeout, transport-level failure.
- *
- * @public
- */
-export declare class NetworkError extends TheokitAgentError {
-    readonly name: string;
-    constructor(message: string, options?: {
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Catch-all for unclassified server or runtime errors.
- *
- * @public
- */
-export declare class UnknownAgentError extends TheokitAgentError {
-    readonly name: string;
-    constructor(message: string, options?: {
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Thrown by `Agent.prompt` (and helpers that go through `run.wait()`) when
- * the option `{ throwOnError: true }` is set and the run terminates with
- * `status: 'error'`. Carries the structured `RunResult.error` fields so
- * callers can `catch` once and branch on `code` / `provider` instead of
- * unwrapping the run.
- *
- * Extends {@link TheokitAgentError} per ADR D65 — no new hierarchy.
- *
- * @example
- *   try {
- *     await Agent.prompt(msg, { apiKey, model, throwOnError: true });
- *   } catch (err) {
- *     if (err instanceof AgentRunError && err.code === 'auth_failed') {
- *       // bad key
- *     }
- *   }
- *
- * @public
- */
-export declare class AgentRunError extends TheokitAgentError {
-    readonly name: string;
-    readonly provider?: string;
-    readonly raw?: string;
-    /** Provider's request id (`x-request-id` / `request-id` header). Useful for support tickets. */
-    readonly requestId?: string;
-    /** SDK conversation id this error was raised inside. */
-    readonly conversationId?: string;
-    constructor(message: string, options: {
-        code: AgentRunErrorCode;
-        provider?: string;
-        raw?: string;
-        requestId?: string;
-        conversationId?: string;
-        retriable?: boolean;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-    /**
-     * Production-Readiness #3 (ADR D311): alias for `isRetryable` exposed as
-     * `retriable` to match the handoff contract. Future v2 will deprecate
-     * `isRetryable` in favor of this.
-     */
-    get retriable(): boolean;
-    /**
-     * D312: provider's `Retry-After` header in **milliseconds**. Mappers store
-     * the header value (seconds) in `metadata.retryAfter`; this getter
-     * multiplies by 1000 so the result composes with `Date.now()`/`setTimeout`.
-     *
-     * Returns `undefined` when no hint was provided. `0` is a legitimate value
-     * — use `=== undefined` check rather than truthy check.
-     */
-    get retryAfterMs(): number | undefined;
-    /**
-     * D313 + T1.5: alias for `metadata.raw`. Provider response body for
-     * debugging. T1.5 wraps the value in `redactSecrets` at the getter
-     * boundary so secret-shaped substrings (`sk-...`, Bearer JWTs, etc.) are
-     * stripped before reaching the caller. Available but NEVER serialized
-     * into `.message` (anti-leak invariant).
-     */
-    get providerError(): unknown;
-    /**
-     * T1.5 — sanitized JSON form. `metadata.raw` is OMITTED by default; opt
-     * in via `THEOKIT_DEBUG_RAW_ERRORS=1` to surface the (redacted) raw
-     * payload for diagnostics. Every other field stays accessible.
-     *
-     * The single env-var gate is read each call so operators can toggle at
-     * runtime without restarting the process.
-     */
-    toJSON(): Record<string, unknown>;
-}
-/**
- * Is this error transient (worth retrying)?
- *
- * Returns the SDK's own retryability verdict: every {@link TheokitAgentError}
- * subclass computes `isRetryable` at construction (rate-limit / network /
- * credential-pool-exhausted are retryable; auth / configuration / unsupported
- * are not), so this predicate is a single source of truth rather than a
- * re-derivation. Non-SDK errors return `false` conservatively — wrap a foreign
- * error in the appropriate SDK error first if you want it considered transient.
- * It never inspects `err.message`.
- *
- * @example
- *   try {
- *     await agent.send(message, { throwOnError: true });
- *   } catch (err) {
- *     if (isTransientError(err)) return retryWithBackoff();
- *     throw err;
- *   }
- *
- * @public
- */
-export declare function isTransientError(err: unknown): boolean;
-/**
- * Thrown when a {@link Run} or agent operation is not available on the current
- * runtime. Check first with `run.supports(operation)`.
- *
- * Extends {@link TheokitAgentError} (so error-catching code that branches on
- * `instanceof TheokitAgentError` continues to work) but is never retryable —
- * an unsupported operation will not become supported on retry.
- *
- * @public
- */
-export declare class UnsupportedRunOperationError extends TheokitAgentError {
-    readonly name: string;
-    readonly operation: RunOperation;
-    constructor(message: string, operation: RunOperation, options?: {
-        code?: string;
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when every credential in a per-provider pool is in cooldown
- * and no healthy key is available (ADR D133). The caller's
- * {@link import("./internal/llm/fallback-client.js").FallbackLlmClient}
- * catches this and tries the next provider in the fallback chain.
- *
- * `metadata.nextRetryAt` (epoch ms) tells callers when the soonest
- * pool entry resumes — useful for manual retry scheduling.
- *
- * @public
- */
-export declare class CredentialPoolExhaustedError extends TheokitAgentError {
-    readonly name: string;
-    readonly provider: string;
-    readonly nextRetryAt: number | undefined;
-    constructor(message: string, options: {
-        provider: string;
-        nextRetryAt?: number;
-        code?: string;
-        cause?: unknown;
-        metadata?: ErrorMetadata;
-    });
-}
-/**
- * Finite error codes specific to memory adapter operations (ADR D141).
- *
- * @public
- */
-export type MemoryAdapterErrorCode = "auth_failed" | "rate_limited" | "not_found" | "network" | "invalid_input" | "unknown";
-/**
- * Error raised by `@theokit-memory-*` adapters. Carries `adapterId`
- * so callers can branch on which provider failed (ADR D141).
- *
- * @public
- */
-export declare class MemoryAdapterError extends TheokitAgentError {
-    readonly name: string;
-    readonly adapterId: string;
-    constructor(message: string, options: {
-        adapterId: string;
-        code: MemoryAdapterErrorCode;
-        cause?: unknown;
-        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
- */
-export 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
- */
-export 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
- */
-export 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. Caller pega
- * tipado para retry-after-window-reset or surface to the user.
- *
- * @public
- */
-export declare class BudgetExceededError extends TheokitAgentError {
-    readonly name: string;
-    readonly budgetName: string;
-    readonly window: import("./types/budget.js").BudgetWindow;
-    readonly spentUsd: number;
-    readonly limitUsd: number;
-    readonly mode: import("./types/budget.js").BudgetMode;
-    constructor(args: {
-        budgetName: string;
-        window: import("./types/budget.js").BudgetWindow;
-        spentUsd: number;
-        limitUsd: number;
-        mode: import("./types/budget.js").BudgetMode;
-        cause?: unknown;
-    });
-}
-/**
- * Thrown when `CloudAgent.send({ budget })` is invoked (D388). Cloud
- * budget surface waits for Theo PaaS GA.
- *
- * @public
- */
-/**
- * T1.6 — Thrown when a consumer calls `agent.send()` or any method
- * on an agent that has already been `dispose()`d. Pre-T1.6 this was
- * a generic `new Error("Agent has been disposed")` — consumers
- * couldn't catch it without string-matching the message.
- *
- * @public
- */
-export declare class AgentDisposedError extends TheokitAgentError {
-    readonly name: string;
-    readonly agentId: string;
-    constructor(agentId: string);
-}
-export declare class UnsupportedBudgetOperationError extends TheokitAgentError {
-    readonly name: string;
-    readonly operation: string;
-    constructor(operation: string, options?: {
-        cause?: unknown;
-    });
-}
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, g as BudgetExceededError, C as ConfigurationError, u as CredentialPoolExhaustedError, m as ErrorCode, E as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, K as KnownAgentRunErrorCode, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, T as TheokitAgentError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-DHZtSNnj.js';
+import './run-OJbGyweZ.js';
+import 'zod';