@theokit/sdk 1.5.0

package/dist/internal/errors/mappers/ollama.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Ollama-specific HTTP/transport error mapper (T1.1, ADR D185).
+ *
+ * Sits ABOVE the generic OpenAI-compatible mapper for `providerId: "ollama"`.
+ * Returns `undefined` when the error doesn't match an Ollama-specific
+ * pattern — caller (OpenAIClient) then falls back to the generic mapper.
+ *
+ * Surfaces 3 Ollama-specific failure modes with actionable messages
+ * targeted at non-technical users (CLAUDE.md primary persona):
+ *
+ * 1. **Transport-level `ECONNREFUSED` / `ENOTFOUND`** → "Run `ollama serve`"
+ * 2. **HTTP 404 with `not found, try pulling`** → "Run `ollama pull <model>`"
+ * 3. **HTTP 503 with `model is loading`** → retryable (model warming up)
+ *
+ * @internal
+ */
+interface MapOllamaTransportArgs {
+    providerId: string;
+    cause: unknown;
+    endpoint: string;
+}
+interface MapOllamaHttpArgs {
+    providerId: string;
+    status: number;
+    body: unknown;
+    headers: Headers | undefined;
+    endpoint: string;
+}
+/**
+ * Maps fetch-level failures (Node TypeError with `cause.code`). Returns
+ * `undefined` for anything that isn't `ECONNREFUSED` / `ENOTFOUND` so
+ * the caller can re-throw the original error untouched.
+ */
+export declare function mapOllamaTransportError(args: MapOllamaTransportArgs): TheokitAgentError | undefined;
+/**
+ * Maps HTTP-level Ollama failures. Returns `undefined` for status codes
+ * that aren't Ollama-specific so the caller falls back to the generic
+ * OpenAI-compatible mapper.
+ */
+export declare function mapOllamaHttpError(args: MapOllamaHttpArgs): TheokitAgentError | undefined;
+export {};

package/dist/internal/errors/mappers/openai-compatible.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAI-compatible HTTP error mapper (ADR D67).
+ *
+ * Translates OpenAI-shaped API error responses (covers OpenAI, OpenRouter,
+ * DeepSeek, Together, Mistral, Voyage, DeepInfra, etc.) into typed
+ * `TheokitAgentError` subclasses with full `ErrorMetadata`.
+ *
+ * Body inspection: looks at `body.error.code` / `body.error.type` to detect
+ * `context_too_long`, `content_filtered`, `model_unavailable` semantics.
+ * Falls back to status-based mapping when body doesn't expose `.error`
+ * (e.g., HTML server error page, DeepInfra's `{message: "..."}` shape).
+ *
+ * Never throws — caller is already in an error path.
+ *
+ * @internal
+ */
+interface MapOpenAiErrorArgs {
+    providerId: string;
+    status: number;
+    body: unknown;
+    headers: Headers | undefined;
+    endpoint: string;
+}
+export declare function mapOpenAICompatibleError(args: MapOpenAiErrorArgs): TheokitAgentError;
+export {};

package/dist/internal/errors/mappers/shared.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Helpers shared between provider HTTP error mappers (ADR D67).
+ *
+ * Extracted to dedupe identical logic in `anthropic.ts` and
+ * `openai-compatible.ts` — retry-after parsing, raw-body truncation,
+ * and metadata assembly are dialect-agnostic.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/errors/mappers/vertex.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GCP Vertex AI HTTP error mapper (ADRs D67, D300).
+ *
+ * Vertex returns `{ error: { code, status, message, details } }` (Google
+ * AIP-193 standard error shape).
+ *
+ * @internal
+ */
+export interface MapVertexErrorArgs {
+    status: number;
+    body: unknown;
+    headers: Headers | undefined;
+    endpoint: string;
+}
+export declare function mapVertexError(args: MapVertexErrorArgs): TheokitAgentError;

package/dist/internal/eval/aggregate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * D211 — compute `EvalAggregate` from a list of `EvalRowResult`.
+ *
+ * Pure functions; no IO. p50/p95 computed via sort+index (O(n log n) is
+ * fine for v1; eval datasets are bounded by D210 streaming-deferral).
+ *
+ * @internal
+ */
+export declare function computeAggregate(rows: ReadonlyArray<EvalRowResult>): EvalAggregate;

package/dist/internal/eval/dataset-iter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * D210 — normalize `Dataset` (array OR factory-of-iterable) into a
+ * concrete `AsyncIterable<DatasetEntry>`. Then the runner materializes
+ * the list (v1 doesn't stream the aggregate).
+ *
+ * @internal
+ */
+export declare function normalizeDataset(d: Dataset): AsyncGenerator<DatasetEntry, void, void>;
+export declare function materializeDataset(d: Dataset): Promise<DatasetEntry[]>;

package/dist/internal/eval/runner.d.ts

@@ -0,0 +1,9 @@
+/**
+ * D204 — Eval execution engine. Orchestrates dataset materialization,
+ * `Agent.batch` fanout, scorer application, aggregate computation, and
+ * single-flight lifecycle.
+ *
+ * @internal
+ */
+import type { EvalOptions, EvalRun, EvalRunOptions } from "../../types/eval.js";
+export declare function runEval(options: EvalOptions, runOpts: EvalRunOptions | undefined): Promise<EvalRun>;

package/dist/internal/eval/single-flight.d.ts

@@ -0,0 +1,16 @@
+/**
+ * D213 — single-flight guard for `Eval.run`. Module-level `Set<string>`
+ * tracks running names; `acquire` throws on collision; `release` is
+ * idempotent.
+ *
+ * @internal
+ */
+export declare class EvalAlreadyRunningError extends Error {
+    readonly name = "EvalAlreadyRunningError";
+    readonly evalName: string;
+    constructor(evalName: string);
+}
+export declare function acquireSingleFlight(name: string): void;
+export declare function releaseSingleFlight(name: string): void;
+/** Test-only — clears the running set. NOT exported via barrel. */
+export declare function __resetSingleFlightForTests(): void;

package/dist/internal/eval/telemetry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * D206 — minimal OTel piggyback for `Eval.run`. Emits a parent `eval.run`
+ * span when available; child `agent.send` spans (existing per D34) nest
+ * correctly when OTel context is active.
+ *
+ * @internal
+ */
+export interface EvalTelemetryHandle {
+    setAttribute(key: string, value: string | number | boolean): void;
+    end(): void;
+}
+/**
+ * Start an `eval.run` span. Returns a handle whose `end()` MUST be called
+ * in `finally`. When OTel is unavailable, returns a no-op.
+ */
+export declare function startEvalRunSpan(attrs: {
+    name: string;
+    id: string;
+    rows: number;
+    concurrency: number;
+}): EvalTelemetryHandle;
+/** Test-only — clears the tracer cache so a re-load happens. */
+export declare function __resetEvalOtelCacheForTests(): void;

package/dist/internal/fixture-mode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fixture-mode detection.
+ *
+ * When `THEOKIT_API_BASE_URL` is NOT set and the API key matches the
+ * `theo_test_*` pattern, the SDK runs in fixture mode — it returns
+ * deterministic, baked-in responses that match the golden fixtures under
+ * `tests/golden/`. This is documented behavior and part of the contract
+ * (analogous to Stripe's test keys), NOT a test-side mock.
+ *
+ * When `THEOKIT_API_BASE_URL` is set (e.g. pointing at a test HTTP server
+ * or a real Theo PaaS instance), the SDK always performs real HTTP
+ * requests — fixture mode is short-circuited.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/handoff/dispatcher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Handoff dispatch orchestration.
+ *
+ * Pragmatic v1: when a handoff fires, the sender calls `receiver.send()`
+ * with the (optionally filtered) history. The receiver's reply is returned
+ * to the sender, which captures it as the answer to the user's question.
+ *
+ * NOTE: this is NOT pure peer-to-peer (the sender stays on the call stack
+ * until the receiver returns). Pure intercept-and-swap requires deeper
+ * agent-loop refactor; deferred to v2. v1 still validates the user-facing
+ * value: "agent A reasoned about routing, agent B answered."
+ *
+ * @internal
+ */
+import type { HandoffDescriptor, HandoffHistory, HandoffResult } from "../../types/handoff.js";
+import { type HandoffChainState } from "./registry.js";
+export declare function dispatchHandoff(args: {
+    descriptor: HandoffDescriptor;
+    senderAgentId: string;
+    chainState: HandoffChainState;
+    rawInputJson: unknown;
+    /** The conversation so far (history wrapper). v1: just the LAST user message. */
+    history: HandoffHistory;
+    /** Override the message text sent to the receiver. Used by `Agent.handoffTo` imperative. */
+    messageOverride?: string;
+}): Promise<{
+    reply: string;
+    result: HandoffResult;
+}>;

package/dist/internal/handoff/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handoff registry — pure state container per `Agent` instance.
+ *
+ * Holds the active dispatch chain (for depth + pair tracking) across the
+ * lifetime of a single `agent.send()` call. Cleared between calls.
+ *
+ * @internal
+ */
+export interface HandoffChainState {
+    /** Ordered chain of agentIds traversed so far (oldest first). */
+    readonly chain: string[];
+    /** Set of "<sender>-><receiver>" keys for pair-level loop detection (D221). */
+    readonly seenPairs: Set<string>;
+    /** Caller-supplied max depth (D218). */
+    readonly maxDepth: number;
+}
+export declare function createChainState(rootAgentId: string, maxDepth: number): HandoffChainState;
+/**
+ * Record a handoff hop. Throws on depth-exceed (D218) or pair-loop (D221).
+ * Mutates the state in place.
+ */
+export declare function recordHop(state: HandoffChainState, senderAgentId: string, receiverAgentId: string): void;
+export declare function currentDepth(state: HandoffChainState): number;

package/dist/internal/handoff/telemetry.d.ts

@@ -0,0 +1,18 @@
+/**
+ * D220 — Lazy-loaded OTel `handoff.transfer` span emitter.
+ *
+ * @internal
+ */
+export interface HandoffSpanHandle {
+    setAttribute(key: string, value: string | number | boolean): void;
+    end(): void;
+}
+export declare function startHandoffSpan(attrs: {
+    from: string;
+    to: string;
+    reason: string;
+    depth: number;
+    toolName: string;
+}): HandoffSpanHandle;
+/** Test-only — reset cached OTel handle. */
+export declare function __resetHandoffOtelCacheForTests(): void;

package/dist/internal/handoff/tool-injector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Convert `handoffs[]` entries into synthetic `transfer_to_<receiver>` tools
+ * for injection into the agent's tool registry at construction time.
+ *
+ * The synthesized tool's handler calls `dispatchHandoff` internally and
+ * returns the receiver's reply as `tool_result`. v1 trade-off documented
+ * in dispatcher.ts.
+ *
+ * @internal
+ */
+import type { CustomTool, SDKAgent } from "../../types/agent.js";
+import { type HandoffDescriptor } from "../../types/handoff.js";
+interface NormalizedHandoff {
+    descriptor: HandoffDescriptor;
+}
+/**
+ * Normalize each `handoffs[]` entry to a `HandoffDescriptor`. Raw `SDKAgent`
+ * instances are auto-wrapped with default options. Validates:
+ *   - EC-6: no self-reference (would cause infinite recursion).
+ *   - D215: resolved tool names must be unique.
+ */
+export declare function normalizeHandoffs(parentAgentId: string, entries: ReadonlyArray<SDKAgent | HandoffDescriptor>): NormalizedHandoff[];
+/**
+ * Build a `CustomTool` for one handoff descriptor. The handler dispatches
+ * the handoff using a fresh chain state per `send()`-level invocation.
+ *
+ * NOTE: this v1 builds a NEW chain state per tool invocation. Pure
+ * cross-tool depth tracking within one send() requires per-Agent context
+ * — deferred. The single-flight pair guard catches direct ping-pong even
+ * without cross-invocation chain (since each call wraps the same depth
+ * counter from 1).
+ */
+export declare function buildHandoffTool(parentAgentId: string, descriptor: HandoffDescriptor, maxHandoffDepth: number): CustomTool;
+export {};

package/dist/internal/http.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/ids.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/judge/judge-call.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Judge call primitive (T2.2, ADRs D119-D121).
+ *
+ * Instantiates a short-lived auxiliary agent that evaluates whether a
+ * goal is satisfied. The auxiliary judge runs with `tools: []` and a
+ * cheap model (default `openai/gpt-4o-mini`) — see ADR D119. The judge
+ * model needs only API access; we read `OPENROUTER_API_KEY` directly
+ * from the environment (EC-A — single source of truth) and let the
+ * caller override via {@link JudgeOptions.apiKey} for Anthropic or
+ * direct-OpenAI environments.
+ *
+ * NOTE: judge aux agents created from inside a `forkAgent` context will
+ * inherit the parent fork's whitelist via AsyncLocalStorage (EC-J).
+ * `tools: []` keeps this benign today; future callers that add tools to
+ * a judge should be aware.
+ *
+ * @internal
+ */
+/** Inputs to the judge — pure data. */
+export interface JudgeContext {
+    goal: string;
+    lastResponse: string;
+    subgoals?: string[];
+}
+/** Caller-supplied tuning knobs for the judge call. */
+export interface JudgeOptions {
+    /** Judge model identifier. Default `"openai/gpt-4o-mini"` (ADR D119). */
+    judgeModel?: string;
+    /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
+    apiKey?: string;
+}
+/** Dependencies injected so `judge-call.ts` stays free of `Agent` import. */
+export interface JudgeDeps {
+    create: (options: AgentOptions) => Promise<SDKAgent>;
+}

package/dist/internal/judge/parse-verdict.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure verdict parser (T2.1, ADRs D120-D121).
+ *
+ * Strict prefix matching against `DONE:`, `CONTINUE:`, `SKIPPED:`. Reason
+ * is the suffix, trimmed. Anything else is fail-safe: verdict = `continue`,
+ * `parseFailed: true` — caller's max-consecutive-failure cap stops the
+ * loop after N flakes.
+ *
+ * @internal
+ */
+export declare function parseVerdict(text: string): JudgeResult;

package/dist/internal/judge/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Public types for the judge subsystem (T2.1, ADR D120).
+ *
+ * @internal
+ */
+/** Outcome of {@link parseVerdict} / {@link judgeCallImpl}. */
+export interface JudgeResult {
+    verdict: Verdict;
+    reason: string;
+    /**
+     * `true` when the underlying text did not start with one of the three
+     * canonical prefixes. The verdict is set to `"continue"` (fail-safe,
+     * ADR D121) to avoid stopping prematurely; callers track consecutive
+     * failures and bail via `maxConsecutiveJudgeFailures`.
+     */
+    parseFailed: boolean;
+}

package/dist/internal/llm/anthropic-shared.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared helpers for Anthropic Messages wire format across direct API
+ * (anthropic.ts), Vertex (vertex-anthropic.ts), and Bedrock (bedrock-anthropic.ts)
+ * clients. Extracted to remove cross-module clones flagged by jscpd.
+ *
+ * @internal
+ */
+import type { LlmMessage, LlmRequest, LlmStopReason, LlmToolCallPart } from "./types.js";
+export interface AnthropicResponseLike {
+    content?: Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "tool_use";
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }>;
+    stop_reason?: string | null;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+export declare function extractAnthropicText(response: AnthropicResponseLike): string;
+export declare function extractAnthropicToolCalls(response: AnthropicResponseLike): LlmToolCallPart[];
+export declare function mapAnthropicStopReason(reason: string | null): LlmStopReason;
+/**
+ * Convert an SDK `LlmMessage` to the Anthropic Messages wire shape.
+ * Identical across the three Anthropic-compatible clients (D289/D292).
+ */
+export declare function toAnthropicWireMessage(message: LlmMessage): Record<string, unknown>;
+/**
+ * Build the common body shape for Anthropic Messages requests. Caller
+ * is responsible for adding wire-specific fields (`anthropic_version`,
+ * `model`, `stream`, etc.).
+ */
+/**
+ * Issue a POST to an Anthropic-compatible Messages endpoint with the
+ * standard auth + content-type headers. Caller maps non-2xx via its own
+ * dialect-specific error mapper.
+ */
+export declare function postAnthropicRequest(args: {
+    fetchImpl: typeof fetch;
+    url: string;
+    token: string;
+    body: Record<string, unknown>;
+    signal: AbortSignal;
+}): Promise<Response>;
+/**
+ * Map non-2xx response to a typed error via the dialect mapper; consume
+ * 2xx body into the Anthropic-shape result. Shared by Bedrock + Vertex
+ * Anthropic clients to remove the ~15-line clone (jscpd).
+ */
+export declare function handleAnthropicResponse(args: {
+    response: Response;
+    endpoint: string;
+    errorMapper: (info: {
+        status: number;
+        body: unknown;
+        headers: Headers;
+        endpoint: string;
+    }) => Error;
+}): Promise<{
+    text: string;
+    toolCalls: LlmToolCallPart[];
+    stopReason: LlmStopReason;
+    inputTokens?: number;
+    outputTokens?: number;
+}>;
+export declare function consumeAnthropicResponse(response: Response): Promise<{
+    text: string;
+    toolCalls: LlmToolCallPart[];
+    stopReason: LlmStopReason;
+    inputTokens?: number;
+    outputTokens?: number;
+}>;
+export declare function parseHttpErrorBody(response: Response): Promise<unknown>;
+export declare function buildAnthropicCommonBody(request: LlmRequest): {
+    max_tokens: number;
+    messages: Array<Record<string, unknown>>;
+    system?: string;
+    temperature?: number;
+    tools?: Array<{
+        name: string;
+        description: string;
+        input_schema: unknown;
+    }>;
+};

package/dist/internal/llm/anthropic.d.ts

@@ -0,0 +1,9 @@
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export declare class AnthropicClient implements LlmClient {
+    private readonly options;
+    readonly name = "anthropic";
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: AnthropicClientOptions);
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/bedrock-anthropic.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AWS Bedrock client for Anthropic Messages (Adoption Roadmap #8; ADRs
+ * D286-D302).
+ *
+ * v1: non-streaming only (`POST /model/{id}/invoke`). D302 defers
+ * `/invoke-with-response-stream` (AWS Event Stream binary format) to v1.x.
+ *
+ * Body massage (D289):
+ *  - inject `anthropic_version: "bedrock-2023-05-31"`
+ *  - strip `model` from body (goes in URL)
+ *  - strip `stream` from body (D302 — non-streaming only in v1)
+ *
+ * Uses native `fetch` only — no `@aws-sdk/client-bedrock-runtime`.
+ *
+ * @internal
+ */
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export interface BedrockAnthropicClientOptions {
+    /**
+     * AWS Bearer token. When non-empty, used as-is. When empty/undefined,
+     * resolved lazily per request via `resolveBedrockToken(region)` (D287).
+     */
+    apiKey?: string;
+    /** Override the resolved baseUrl (rarely needed; defaults derive from model id). */
+    baseUrl?: string;
+    /** Injected fetch impl for tests. */
+    fetch?: typeof fetch;
+}
+export declare class BedrockAnthropicClient implements LlmClient {
+    private readonly options;
+    readonly name = "bedrock";
+    private readonly fetchImpl;
+    constructor(options: BedrockAnthropicClientOptions);
+    private resolveTokenOrThrow;
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/bedrock-token-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bedrock Bearer token resolution + cache (ADRs D287, D295).
+ *
+ * Two paths:
+ *   1. Explicit env (`AWS_BEARER_TOKEN_BEDROCK`) wins; no refresh.
+ *   2. Optional peer dep `@aws/bedrock-token-generator` (D287) auto-generates
+ *      short-term tokens from the standard AWS credential chain
+ *      (`@aws-sdk/credential-providers`). Cached for 1.5h.
+ *
+ * `resolveBedrockToken` returns `undefined` only when BOTH paths produce no
+ * token. Caller (router) is responsible for throwing a helpful error
+ * (D279/EC-6) — this module is auth-resolution only.
+ *
+ * @internal
+ */
+export declare function resolveBedrockToken(region: string): Promise<string | undefined>;
+/** Test seam — clear cache between tests. */
+export declare function __resetBedrockTokenCache(): void;

package/dist/internal/llm/credential-pool-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-fork credential-pool inheritance via `AsyncLocalStorage` (ADR D131).
+ *
+ * Mirrors the whitelist context pattern from D111
+ * (`runtime/async-local-storage.ts`). Forked sub-agents inherit the
+ * parent's pool *by reference* so concurrent rotations all observe
+ * the same cooldown state — the desired behavior per Hermes parity.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/llm/credential-pool-types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Types for the credential pool subsystem (ADRs D123-D133).
+ *
+ * Pool a developer's multiple API keys for the SAME provider so the SDK
+ * can rotate transparently on HTTP 429/402/401 instead of jumping
+ * straight to a different provider via `FallbackLlmClient`.
+ *
+ * @internal
+ */
+/** Health flag tracked per credential. */
+export type CredentialStatus = "ok" | "exhausted";
+/**
+ * Provenance of a credential — where it came from when seeded.
+ * Free-form string; conventional prefixes:
+ *
+ * - `env:<VAR_NAME>` — auto-discovered from environment variable
+ * - `manual` — added via explicit `apiKeys` config
+ * - `explicit-apikey` — wrapped from `AgentOptions.apiKey` single-key path (D132)
+ */
+export type CredentialSource = string;
+/** Default cooldown when no specific code matches. */
+export declare const DEFAULT_COOLDOWN_MS: number;

package/dist/internal/llm/credential-pool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * In-memory credential pool with strategy-based rotation (ADRs D123-D133).
+ *
+ * Pure logic. No I/O — persistence lives in `internal/persistence/
+ * credential-pool-store.ts`. The pool is the single source of truth for
+ * rotation state within a process; if it diverges from disk (e.g.,
+ * process killed mid-rotation per EC-I), the next save heals the
+ * inconsistency — at the cost of one extra HTTP 429 per crash.
+ *
+ * Thread safety: the pool uses an in-process async-aware mutex
+ * (`cwd-mutex` D9 keyed by `credential-pool:${provider}`). Cross-process
+ * safety happens at the persistence layer via `withFileLock` (D61).
+ * Two Node processes sharing the same file may double-pick momentarily
+ * (worst case = 1 extra 429 per race) — acceptable per ADR D128.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/llm/fallback-client.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/llm/fault-injection.d.ts

@@ -0,0 +1,50 @@
+/**
+ * D14 — Fault injection via `THEOKIT_TEST_RESPONSE_OVERRIDE` env var.
+ *
+ * Decorator pattern (D127 inspired): wraps any `LlmClient` and short-circuits
+ * the network call when:
+ *
+ *   1. `process.env.NODE_ENV === "test"` (fail-safe gate — prevents production
+ *      footgun), AND
+ *   2. `process.env.THEOKIT_TEST_RESPONSE_OVERRIDE` is a non-empty JSON string
+ *      shaped as `{ "status": number, "body": object | string }`.
+ *
+ * On any other condition (different NODE_ENV, missing env, malformed JSON),
+ * the wrapper delegates to the real client — graceful degradation.
+ *
+ * Use cases (FAANG-grade chaos testing):
+ *
+ *   - `{"status":429,"body":{"error":{"code":"rate_limit_exceeded"}}}` →
+ *     deterministic RateLimitError without burning real quota
+ *   - `{"status":500,"body":{"error":{"code":"internal_error"}}}` →
+ *     deterministic NetworkError for retry/circuit-breaker tests
+ *   - `{"status":200,"body":{"choices":[{"message":{"content":"fake"}}]}}` →
+ *     deterministic happy-path text for snapshot tests
+ *
+ * Compatible with the dogfood-stranger chaos phases (12-15). Replaces the
+ * flaky "50 parallel requests to force 429" anti-pattern.
+ *
+ * Wire format mirrors OpenAI Chat Completions (universal — same shape every
+ * provider returns). Error mapping reuses `mapOpenAICompatibleError` so the
+ * injected errors are byte-equal to what the real provider would raise.
+ *
+ * @internal
+ */
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+/**
+ * Wrap an `LlmClient` with the fault-injection decorator. Returns the
+ * original client unchanged when the activation gate is not satisfied
+ * (cheap noop — no allocation in the hot path of production runtime).
+ */
+export declare function maybeWrapWithFaultInjection(client: LlmClient): LlmClient;
+export declare class FaultInjectingLlmClient implements LlmClient {
+    readonly name: string;
+    /**
+     * Inner (real) client. Exposed so layered transport assertions (router
+     * pool-wiring tests, telemetry inspectors) can walk one level deep —
+     * same pattern PoolAwareLlmClient uses for its inner transport.
+     */
+    readonly inner: LlmClient;
+    constructor(inner: LlmClient);
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/finish.d.ts

@@ -0,0 +1 @@
+export {};