@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/internal/concurrency/subagent-credentials.d.ts

@@ -0,0 +1,112 @@
+/**
+ * theokit#148 — the parent's credentials, delivered through the CALL, not through the tool object.
+ *
+ * ## The class of bug this replaces
+ *
+ * Credential inheritance used to ride a property installed on the subagent tool object — first a
+ * unique `Symbol()`, then `Symbol.for` after #143. Both are the same shape of contract: "this
+ * object will reach the dispatcher with an extra property intact". Nothing enforces that, and it
+ * broke twice for two different reasons:
+ *
+ *  - **Module duplication** (#142/#143): `tsup splitting: false` inlined a separate copy of the
+ *    module into each public entry, so the two copies disagreed on a unique `Symbol()` key. Fixed at
+ *    the build level by M78's `splitting: true`, but the fragile contract remained.
+ *  - **Object normalization** (#148): any layer that rebuilds the tool from its known fields drops
+ *    the property. `@theokit/agents`' `toCompiledTool` does exactly that, and had to add an explicit
+ *    `Object.getOwnPropertySymbols` copy loop to compensate — a band-aid the SDK's contract forced
+ *    onto a consumer. A named field would have been dropped by the same four-field rebuild, which is
+ *    why "make it a typed field" alone does not close this.
+ *
+ * ## Why the async scope closes it
+ *
+ * What survives a rebuild is not the object — it is the CALL. A normalizing wrapper builds a new
+ * object but still invokes the original handler, inside the parent run's async context. So
+ * credentials published on that context reach the handler regardless of what the tool object looks
+ * like by then. There is no property left for a layer to drop.
+ *
+ * It also fixes a defect the per-object slot could not: credentials were stored per tool INSTANCE,
+ * so one subagent tool shared by two agents got last-writer-wins. The scope is per run.
+ *
+ * Nothing is exposed to third-party tool code: the store is module-private, credentials never touch
+ * a handler's `ctx`, and `currentInheritedSubAgentCredentials` is `@internal`.
+ *
+ * @internal
+ */
+import type { BuiltinToolName, CompatSource, SettingSource } from "../../types/agent.js";
+import type { ModelSelection } from "../../types/agent-prims.js";
+import type { Plugin } from "../plugins/types.js";
+/**
+ * Credentials a parent agent hands down to its subagent tools so the child inherits the parent's
+ * auth (and, absent an explicit `spec.model`, its model).
+ *
+ * Declared here rather than in `a2a/subagent.ts` so the delivery mechanism owns the payload shape
+ * and the dependency runs one way (`a2a/subagent` -> this module). `a2a/subagent.ts` briefly
+ * re-exported it "for back-compat"; knip proved there was no back-compat surface to preserve — the
+ * type was never in the public barrel nor the exports map — so the re-export was deleted.
+ *
+ * Emitted rather than erased: `a2a/subagent.d.ts` imports it by name, and that entry IS published,
+ * so erasing this declaration ships a `.d.ts` that does not compile. Not being in the exports map
+ * is what keeps it out of the semver contract; erasure is not what does that.
+ */
+export interface InheritedCredentials {
+    readonly apiKey?: string;
+    readonly model?: ModelSelection;
+    /**
+     * The parent's shell-sandbox posture (`local.sandboxOptions.enabled`), handed down so a delegated
+     * child of a sandboxed parent stays sandboxed unless its role explicitly opts out. Without this a
+     * child ran unsandboxed whenever its role omitted `sandbox` — a default-open the sandbox wiring
+     * exists to prevent.
+     */
+    readonly sandbox?: boolean;
+    /**
+     * #55 — the parent's code-registered plugins (e.g. a `PermissionPlugin`) handed down so the child
+     * runs under the SAME policy. Without this, a delegated child's inner tool calls escape the
+     * parent's argument-level permission gate. First-party delegation path only — never exposed to
+     * third-party tool `ctx`.
+     */
+    readonly plugins?: readonly Plugin[];
+    /**
+     * #578 — the parent's RESOLVED `local.settingSources` / `local.compatSources`, handed down so a
+     * delegated child can see the configuration surfaces its parent was declared to read.
+     *
+     * `compatSources` arrived with #524 and neither carrier was updated, so a parent declaring
+     * `compatSources: ["claude-code"]` read `.claude/agents/` and its child did not: a team could
+     * delegate TO a role by name and the child could not resolve the rest of the team.
+     *
+     * ## Why inheriting is safe here, unlike widening
+     *
+     * Every other field on this interface hands DOWN a restriction (the sandbox posture, the
+     * permission plugins) and the danger is a child escaping it. These two are the mirror image: the
+     * child is currently MORE restricted than its parent, so the failure is a missing capability
+     * rather than an open door. Inheritance cannot widen — the child receives what the parent already
+     * resolved, and it runs in the parent's cwd, so it reads no directory the parent could not.
+     *
+     * A role's explicit value still wins; these are the fallback, exactly as `model` and `sandbox` are.
+     */
+    readonly settingSources?: readonly SettingSource[];
+    /** @see {@link InheritedCredentials.settingSources} — carried together, same reasoning. */
+    readonly compatSources?: readonly CompatSource[];
+    /**
+     * #580 — the builtin tools the parent removed from its catalog, handed down so a delegated child
+     * cannot recover one its parent revoked.
+     *
+     * This is the third field here that hands down a RESTRICTION, and it was the one that crossed no
+     * carrier at all: measured, a parent with `withheldBuiltinTools: ["shell"]` produced a child whose
+     * value was `undefined`, so the child got the shell back. Delegation widened authority the operator
+     * had revoked — the inverse of #578 and materially worse, because there the child was merely
+     * over-restricted.
+     *
+     * It bites because of a documented default (`types/agent.ts` § LocalOptions): a `shell` tool is
+     * ALWAYS registered on a local agent, including when `tools: []` is passed. Withholding is the only
+     * mechanism that removes it, so a withholding that does not survive delegation leaves no other way
+     * for a child to be without a shell.
+     *
+     * ## The union rule
+     *
+     * A child's own list is UNIONED with this one, never substituted for it — see
+     * {@link buildChildWithheldBuiltins}. Every other field on this interface lets the role's own value
+     * win, and copying that here would let a child un-withhold what its parent revoked: the bug,
+     * reintroduced by its own fix.
+     */
+    readonly withheldBuiltinTools?: readonly BuiltinToolName[];
+}

package/dist/internal/diagnostics.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The library's single diagnostics channel — silent by default (#147).
+ *
+ * ## The problem
+ *
+ * The SDK wrote diagnostics straight to `process.stderr` from hot paths — 92 sites across 51
+ * files under `internal/`. In a TUI host (Ink, alternate screen), those writes interleave with the
+ * render and **corrupt the frame**. And the host had no way to intercept them: there was no
+ * injectable logger. One consumer went as far as installing `proper-lockfile` just to silence ONE
+ * of them.
+ *
+ * A library cannot assume `stdout`/`stderr` are free sinks. The application owns the terminal, not
+ * the dependency.
+ *
+ * ## The contract
+ *
+ * - **`setDiagnosticsSink(fn)`** hands the messages to the application, which decides where to put
+ *   them (a status line, a file, a panel). It is what was missing for a TUI to coexist with the SDK.
+ * - **With no sink, nothing is emitted.** A library does not own the host's terminal.
+ *
+ * ## Silent by default, and how 36 suites survived the flip
+ *
+ * The default WAS `stderr`, and 36 test files spy on `process.stderr.write` to assert a given
+ * warning is emitted. That contract is real and had to survive; migrating all 36 by hand, across
+ * four different spy styles, is how you weaken 36 suites in one commit.
+ *
+ * So the flip happened at the default, and `vitest.setup.ts` installs a sink that FORWARDS to
+ * `stderr` for the duration of every test. Those assertions still test what they always tested —
+ * "this condition emits a diagnostic" — through the channel a host would use, while production
+ * emits nothing unless asked.
+ *
+ * The cost is stated rather than hidden: no test observes the production default by accident, so
+ * `tests/diagnostics-public-entry.test.ts` pins it explicitly by clearing the sink first.
+ *
+ * ## Coverage is the whole guarantee
+ *
+ * The first sweep migrated the 92 sites under `internal/` and left `src/`'s own modules —
+ * `event-bus.ts`, `batch.ts`, `compaction.ts`, `internal/workflow/step-branch.ts`. A host could
+ * therefore install a sink and still have its frame corrupted by a batch run, which is the reported
+ * defect with a smaller blast radius. Those are routed here too, and
+ * `tests/lint/no-direct-terminal-write.test.ts` is what keeps the next hot path from
+ * reintroducing one. "Mostly interceptable" is not interceptable.
+ *
+ * The remaining direct writers are allowlisted there with a reason, and every one of them is a seam
+ * whose destination the CALLER already chooses (`opts.warn`, `opts.logger`, the Workflow logger).
+ *
+ * ## What this is NOT
+ *
+ * It is not a logger with levels, formatting or multiple destinations. It is the minimum that
+ * resolves the reported blocker; a full logger here would be inventing a requirement nobody asked
+ * for.
+ */
+/** Receives each diagnostic message already formatted, with the trailing `\n`. */
+export type DiagnosticsSink = (message: string) => void;
+/**
+ * Installs (or removes, by passing `undefined`) the diagnostics destination.
+ *
+ * When a sink is present it is the ONLY destination — `stderr` gets no copy. Duplicating
+ * destinations would hand the problem back to the TUI that installed the sink precisely to get the
+ * messages out of the terminal.
+ */
+export declare function setDiagnosticsSink(next: DiagnosticsSink | undefined): void;
+/**
+ * Emits a library diagnostic message.
+ *
+ * Replaces `process.stderr.write` on internal paths. Never throws: a faulty sink must not
+ * must not take down the run it merely observes.
+ */
+export declare function diag(message: string): void;

package/dist/internal/emit-run-event.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The fail-safe emitter for the `RunEvent` stream — runtime, deliberately NOT in `types/`.
+ *
+ * Eleven modules across `agent-loop/`, `runtime/`, `task/` and `local-agent/` call it; the type it
+ * carries stays in `types/run-events.ts`, which is what `types/` is for. Sibling of
+ * `internal/diagnostics.ts`, which swallows sink failures on the same principle and for the same
+ * reason: observability degrades what you can SEE, never what the agent DOES.
+ *
+ * @internal
+ */
+/**
+ * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
+ * observability can never break the run (fail-safe, mirrors the EventBus EC-2
+ * contract). No-op when the sink is absent.
+ */
+export declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;

package/dist/internal/env.d.ts

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

package/dist/internal/error-mappers/anthropic.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Anthropic HTTP error mapper (ADR D67).
+ *
+ * Translates an Anthropic API error response into a typed
+ * `TheokitAgentError` subclass with full `ErrorMetadata`. Mapping rules:
+ *
+ *   401/403 → `AuthenticationError`  (`code: "auth_failed"`)
+ *   429     → `RateLimitError`        (`code: "rate_limit"`)
+ *   400     → `ConfigurationError`    (`code: "context_too_long"` if body
+ *                                       mentions context length, else
+ *                                       `"invalid_request"`; or
+ *                                       `"content_filtered"` for policy.)
+ *   408     → `NetworkError`          (`code: "timeout"`)
+ *   5xx     → `NetworkError`          (`code: "server_error"` — covers 529
+ *                                       overloaded_error common at peak
+ *                                       at peak)
+ *   other   → `UnknownAgentError`     (`code: "unknown"`)
+ *
+ * Never throws — caller is already in an error path.
+ *
+ * @internal
+ */
+interface MapAnthropicErrorArgs {
+    status: number;
+    body: unknown;
+    headers: Headers | undefined;
+    endpoint: string;
+}
+export declare function mapAnthropicError(args: MapAnthropicErrorArgs): TheokitAgentError;
+export {};

package/dist/internal/error-mappers/bedrock.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AWS Bedrock HTTP error mapper (ADRs D67, D300).
+ *
+ * Bedrock returns either AWS-style `{ message, __type: "ThrottlingException" }`
+ * or sometimes `{ Message }` (capitalized) depending on the model dialect.
+ * We accept both shapes and map to canonical `TheokitAgentError` subclasses.
+ *
+ * @internal
+ */
+export interface MapBedrockErrorArgs {
+    status: number;
+    body: unknown;
+    headers: Headers | undefined;
+    endpoint: string;
+}
+export declare function mapBedrockError(args: MapBedrockErrorArgs): TheokitAgentError;

package/dist/internal/error-mappers/default-retriable.d.ts

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

package/dist/internal/error-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/error-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/error-mappers/shared.d.ts

@@ -0,0 +1,23 @@
+/**
+import type { ErrorCode } from "../../errors.js";
+ * 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 declare function httpStatusToErrorCode(status: number): HttpStatusErrorCode;
+/**
+ * Reads an error body that may arrive already parsed, as a JSON string, or as neither.
+ *
+ * This is TRANSPORT knowledge, not vendor knowledge: it describes how `fetch` surfaces a body, which
+ * is the same whichever provider sent it. It lived twice, character-for-character, in bedrock.ts and
+ * vertex.ts — identical once the return type name was substituted. They had not drifted, so the cost
+ * was only latent: a fix to one would have missed the other silently.
+ *
+ * Unparseable input yields `{}` rather than throwing, because a mapper's job is to classify a
+ * failure that already happened; failing to read the body is not a second failure to report.
+ */
+export declare function parseErrorBody<T>(body: unknown): T;

package/dist/internal/error-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/assert.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SE41 — `assertEval(run, thresholds)`: the CI gate for evals.
+ *
+ * A pure function over a completed {@link EvalRun}. It reads only
+ * `run.aggregate`, collects EVERY unmet threshold (not just the first), and
+ * throws {@link EvalThresholdError} carrying the full failure list. Passing
+ * silently returns `void` — drop it straight into a Vitest `it(...)` or a
+ * standalone eval script whose non-zero exit fails the CI job.
+ *
+ * @public
+ */
+import { TheokitAgentError } from "../../errors.js";
+import type { EvalRun, EvalThresholdFailure, EvalThresholds } from "../../types/eval.js";
+/** Thrown by {@link assertEval} when a run misses one or more thresholds. */
+export declare class EvalThresholdError extends TheokitAgentError {
+    readonly name = "EvalThresholdError";
+    /** The eval's name (`EvalRun.name`). */
+    readonly evalName: string;
+    /** Every unmet threshold, in check order. */
+    readonly failures: readonly EvalThresholdFailure[];
+    constructor(evalName: string, failures: readonly EvalThresholdFailure[]);
+}
+/**
+ * Assert a run meets every set threshold. Throws {@link EvalThresholdError}
+ * with the complete list of failures when it does not; returns `void` on pass.
+ */
+export declare function assertEval(run: EvalRun, thresholds: EvalThresholds): void;

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

@@ -0,0 +1,28 @@
+/**
+ * M6-4 — capture an agent's code change as a gradeable artifact.
+ *
+ * After an agent mutates a provisioned repo, `captureArtifact` records the
+ * working-tree `git diff` and validates it is coherent with the tree via a
+ * reverse `git apply --check` (no re-clone needed). The resulting
+ * `{ diff, applies }` becomes `EvalRowResult.artifact`, the input the Phase 5
+ * verify-gate grades. Every command rides {@link SandboxBackend.execute}
+ * (ADR D2 — portable across Local/Docker/E2B).
+ *
+ * reference: knowledge-base/references/theocode-eval/lib/swebench-batch.ts:154
+ * (build prediction from captured diff), :157 (reverse apply-check on the
+ * mutated tree).
+ *
+ * Re-exported from `@theokit/sdk/eval` for consumers composing a code-eval
+ * harness.
+ *
+ * @public
+ */
+import type { SandboxBackend } from "../../sandbox/types.js";
+/**
+ * Capture the working-tree diff of `repoDir` and check it reverse-applies.
+ * An empty diff (clean tree) returns `{ diff: "", applies: false }`.
+ */
+export declare function captureArtifact(sandbox: SandboxBackend, repoDir: string): Promise<{
+    diff: string;
+    applies: boolean;
+}>;

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,17 @@
+import { TheokitAgentError } from "../../errors-base.js";
+/**
+ * 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 TheokitAgentError {
+    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/eval/trials.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SE41 — trial expansion + collapse for `EvalOptions.trials`.
+ *
+ * Strategy: EXPAND each dataset entry into `trials` tagged copies, run them
+ * through the existing execution paths untouched, then COLLAPSE the resulting
+ * per-trial rows back into one row per original entry. Per-scorer score is the
+ * mean over the trials — an errored trial contributes 0 (a reliability signal),
+ * so the denominator is always `trials`, not the count of successful trials.
+ *
+ * @internal
+ */
+/** Reserved metadata key: the original dataset-row index a trial belongs to. */
+export declare const TRIAL_INDEX_KEY = "__evalRowIndex";
+/** Reserved metadata key: the 0-based trial number within a row. */
+export declare const TRIAL_NUM_KEY = "__evalTrial";
+/** Repeat each entry `trials` times, tagging each copy with its origin + trial number. */
+export declare function expandForTrials(entries: ReadonlyArray<DatasetEntry>, trials: number): DatasetEntry[];
+/** Group per-trial rows by their original entry index and collapse each group. */
+export declare function collapseTrials(rows: ReadonlyArray<EvalRowResult>, trials: number): EvalRowResult[];

package/dist/internal/global-singleton.d.ts

@@ -0,0 +1,16 @@
+/**
+ * One singleton per realm, keyed by `Symbol.for`.
+ *
+ * It exists because a package can be loaded more than once in the same process (two copies in
+ * `node_modules`, ESM and CJS side by side, a monorepo with distinct versions) — and then a module-level
+ * `const x = new Map()` produces TWO caches that cannot see each other. `Symbol.for` uses the global
+ * symbol registry, which belongs to the realm and not the module, so every copy converges on one instance.
+ *
+ * It WAS copied verbatim into `providers/discovery.ts` and `providers/catalog-loader.ts`; both now
+ * import it, as does `providers/registry.ts`. That was duplicated KNOWLEDGE rather than a
+ * coincidence of shape — the copies had to agree on the mechanism, and one fixed without the other
+ * reproduced exactly the bug this function exists to avoid. The paragraph is kept in the past tense
+ * because it is the REASON the helper exists, not a defect report: the previous wording described
+ * the duplication as live, long after it was removed.
+ */
+export declare function globalSingleton<T>(key: string, create: () => T): T;

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,48 @@
+import { TheokitAgentError } from "../../errors.js";
+/** 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. When absent, it DERIVES from {@link agentModel} — and only falls back to the literal
+     * `"openai/gpt-4o-mini"` when neither is provided.
+     *
+     * M80 — the fixed default was provider-blind: it only resolves on OpenRouter. With an Anthropic key it gives
+     * 404, with an OAuth bearer it gives 401, and in both the goal burned 3 whole turns before failing with
+     * a misleading reason. The agent-builder already worked around this by deriving on its own; the knowledge
+     * belongs here.
+     */
+    judgeModel?: string;
+    /**
+     * M80 — the DRIVEN agent's model. It is the basis of the derivation: a judge running on the same model as the
+     * chat works wherever chat works.
+     */
+    agentModel?: string;
+    /** Override env. Default `process.env.OPENROUTER_API_KEY` (EC-A). */
+    apiKey?: string;
+}
+/**
+ * M80 — the judge's credential or model does not work: 401/404.
+ *
+ * Fails FAST by design. `rules/error-handling.md` § 2 separates recoverable from unrecoverable, and a
+ * nonexistent model does not start existing on retry — folding that into `{parseFailed: true}` made the loop
+ * try three times and report "failed" on a consecutive-failure limit, hiding that the cause was the
+ * credential. A slow, opaque failure traded for a fast, clear one.
+ *
+ * PARSE failures and network errors stay folded: they are recoverable, and the loop already decides on
+ * in a row.
+ */
+export declare class JudgeCredentialError extends TheokitAgentError {
+    readonly httpStatus: number;
+    readonly judgeModel: string;
+    readonly name = "JudgeCredentialError";
+    constructor(httpStatus: number, judgeModel: string, cause: unknown);
+}
+/** 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/llm/abort-error.d.ts

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