toolroll 0.5.0

package/dist/provider.d.ts

@@ -0,0 +1,279 @@
+/**
+ * The provider registry: every way this plane can spend money on an agent,
+ * in one file (§5's "one door", widened to three harness shapes).
+ *
+ * A provider here is how to SPAWN a harness and how to READ its envelope —
+ * argv dialect, transport, session identity, usage. The briefs, the mailbox
+ * protocol, and every custody proof are provider-neutral and live where
+ * they always did; this module owns only the dialect differences.
+ *
+ * Boundary (the architecture test enforces it): only `invoke.ts` may import
+ * the spawning surface (`adapterFor`); everything else that needs provider
+ * facts uses the non-spending inspection surface (`PROVIDERS`,
+ * `inspectionOf`) — identification must never be a way to start an LLM.
+ *
+ * `openrouter` is deliberately not a fourth transport: it is the codex
+ * harness pointed at OpenRouter through `-c` overrides whose keys and
+ * values are CONSTANTS below — no caller-supplied dotted keys, values
+ * TOML-quoted deterministically, and the API key excluded from every
+ * shell the model itself launches (Codex provider review, Q5).
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+export type ProviderId = "claude" | "codex" | "openrouter" | "gemini";
+export declare const PROVIDER_IDS: readonly ProviderId[];
+export declare function isProviderId(value: string): value is ProviderId;
+/** Which harness runs, on which model. model null = the harness's default. */
+export type AgentSpec = {
+    provider: ProviderId;
+    model: string | null;
+};
+/** 'review' (v29) is the reviewer's artifact-only pass — plan-shaped in
+ * every clamp: read, comment, never build. */
+export type Phase = "plan" | "build" | "repair" | "review";
+/**
+ * Model ids cross providers ("anthropic/claude-sonnet-4.5", "gpt-5-codex",
+ * "opus"). Bounded and printable, never leading-dash (argv safety), and no
+ * TOML-hostile characters — but NOT alphanumeric-only, which would refuse
+ * real ids carrying `/ . : -` (Codex provider review, Q5).
+ */
+export declare const MODEL_ID: RegExp;
+export declare function validModelId(model: string | null): boolean;
+/** The one semantic request every provider renders into its own argv. */
+export type Invocation = {
+    phase: Phase;
+    brief: string;
+    model: string | null;
+    /** Claude's turn bound. Codex has no equivalent — see `clampTimeout`. */
+    maxTurns: number;
+    permissionMode: string;
+    skipPermissions: boolean;
+    /** Resume this session (repair). Meaningless across providers. */
+    resumeSession: string | null;
+    /** Claude's native dollar cap (tournament stage 3b) — the harness stops
+     * itself when spend reaches this. Ignored by providers without one. */
+    maxBudgetUsd?: number;
+    /** A plane-minted session identity, for providers that can START under a
+     * caller-chosen id (gemini `--session-id`). The gateway stamps it
+     * durably BEFORE spawn and requires the envelope's init id to EQUAL it
+     * (Phase 3 A5) — a mismatch is a provider-protocol failure, never a
+     * silent survivor. */
+    startSessionId?: string;
+    /** Sealed reviewer screenshots, attached explicitly by transports without a read tool. */
+    reviewImages?: readonly string[];
+    /** The project's tools for this launch (v80): the provider's own flags
+     * naming exactly those MCP servers and no others. Never rendered for a
+     * review, which keeps its own no-tools isolation. */
+    toolArgv?: readonly string[];
+    /** The agent fence (agent-fence.ts): paths no agent may read or write.
+     * Codex renders it as its own sandbox profile; Claude as deny rules for
+     * its file tools (its shell is fenced by the macOS sandbox around it). */
+    fence?: readonly string[];
+};
+export type ProviderRunner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/** The harness's own account of how a turn ended. */
+export type AgentEnding = {
+    subtype: string | null;
+    turns: number | null;
+};
+/** What every envelope normalizes to, whatever dialect produced it. */
+export type ParsedEnvelope = {
+    sessionId: string | null;
+    /**
+     * A structurally impossible provider envelope. Unlike diagnostic prose,
+     * this is a control signal consumed by the invocation gateway: the
+     * process spent, but its output may not authorize a handoff or resume.
+     */
+    protocolError: string | null;
+    /** The agent's spoken conclusion — diagnostics only, never the handoff. */
+    finalMessage: string | null;
+    /** How the harness said the turn ended (claude: the result's subtype and
+     * turn count) — absent on dialects that carry no such record. */
+    ending?: AgentEnding | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    costUsd: number | null;
+    usageRaw: string | null;
+    /**
+     * Whether the provider was seen to initialize (codex: thread.started;
+     * claude streaming: system/init). null = this transport carries no init
+     * signal (legacy buffered fixtures), so absence proves nothing. A `false`
+     * here on a failed run means the harness never came up — config, auth,
+     * or install — and the turn must not be treated as an agent's attempt
+     * (M5 provider audit).
+     */
+    initObserved: boolean | null;
+    /**
+     * Structural proof the MAIN QUERY consumed the prompt (arc 1 finding 15):
+     * true only when the primary result is a success. null = this transport
+     * carries no such signal, and the gateway falls back to its historical
+     * nothing-to-show rule. Never derived from result PROSE — an error
+     * result's diagnostic text must not read as an agent's attempt.
+     */
+    promptConsumed: boolean | null;
+    /**
+     * The harness's own first error message, bounded (2 KiB UTF-8), kept for
+     * refusal words and evidence — DIAGNOSTICS ONLY, control-normalized and
+     * secret-scanned at render, never classification (Phase 3 B6). null =
+     * the transport carries none or none was seen.
+     */
+    diagnostic: string | null;
+    /**
+     * The structural FAILURE terminal, when the harness emitted a typed one
+     * (codex turn.failed, a gemini error terminal) — retained for the
+     * fallback taxonomy AND to block success ingestion on a failed-but-exit-0
+     * run (fallback chains, C5). null = no structural failure terminal seen.
+     */
+    structuralTerminal: import("./exhaustion.js").StructuralTerminal | null;
+};
+type Adapter = {
+    binary: string;
+    argv(invocation: Invocation): string[];
+    /** Prompt input for transports that use stdin instead of a bounded OS argument. */
+    stdin?(invocation: Invocation): string | undefined;
+    parse(stdout: string): ParsedEnvelope;
+    /** The production transport when no runner was injected. */
+    defaultRunner: ProviderRunner;
+    /** Other providers' keys, stripped from this provider's environment. Its
+     * own key (API-key mode only) stays: the provider needs it, and its
+     * agent's shell inherits the environment. */
+    extraOmitEnv: readonly string[];
+    /** Normalize the phase's bounded interval. For ordinary current profiles
+     * this is the no-progress watchdog; for repair and legacy profiles it is
+     * a hard wall clock. */
+    clampTimeout(phase: Phase, requestedMs: number): number;
+};
+export declare const OPENROUTER_ENV_KEY = "OPENROUTER_API_KEY";
+/**
+ * The held-session argv (Parity II Phase 2): the same family as
+ * claudeArgv MINUS the positional prompt — every turn, the brief
+ * included, rides stdin as stream-json — plus the input format flag.
+ * maxBudgetUsd is the Probe-6 backstop: the CLI's cap is cumulative
+ * across the whole process, so the remaining authorization budget rides
+ * the argv and later turns cannot spend past it.
+ */
+export declare const claudeHeldArgv: (invocation: Omit<Invocation, "brief">) => string[];
+/**
+ * The diagnostic discipline (Phase 3 B6/C6): the harness's own words are
+ * untrusted bytes headed for refusal screens and notifications — controls
+ * and line separators collapse to spaces (the fence's character class),
+ * and a line that trips the secret scanner is REPLACED, never quoted.
+ */
+export declare function safeDiagnostic(text: string): string | null;
+/** EVERY provider credential — what a version/help/which PROBE strips,
+ * since a feature check needs no key at all (Codex gemini verify,
+ * finding 2). Agent spawns keep their own; probes keep none. */
+export declare const ALL_CREDENTIAL_ENV: readonly string[];
+/**
+ * The spawning surface. Imported by invoke.ts and NOWHERE else — the
+ * architecture test reads imports, not string literals, because provider
+ * ids and binary names are legitimately the same words elsewhere.
+ */
+export declare function adapterFor(provider: ProviderId): Adapter;
+/**
+ * The provider audit: what each harness supports, what we actually pass,
+ * and what user-global configuration can leak into an unattended run.
+ * REPORT BEFORE ENFORCEMENT (Codex roadmap review, item 10): none of this
+ * changes an invocation — it states facts an operator reads on `providers`,
+ * so hermetic mode can later be turned on per provider from evidence
+ * instead of hope. `enforced` is a literal false until that day.
+ */
+export type ProviderAudit = {
+    /** How output reaches us — and therefore which signals can exist at all. */
+    transport: "buffered-json" | "streaming-jsonl";
+    /** Whether a later invocation can resume this provider's session. */
+    resume: "native" | "none";
+    /** The event whose absence on a failed run means "never initialized".
+     * CAPABILITY metadata, not a per-run observation (arc 1 finding 16):
+     * whether a given run actually saw it lives in ParsedEnvelope.initObserved. */
+    initSignal: "thread.started" | "system-init" | "init-event" | "none";
+    /** How session identity is established: "announced" = read back from the
+     * harness's own stream; "minted" = the PLANE chooses the id pre-spawn
+     * (gemini --session-id) and the envelope must echo it (Phase 3 A5). */
+    sessionIdentity: "announced" | "minted";
+    /**
+     * Whether exit 0 is believed on its own (Phase 3 A4). "required" =
+     * the transport carries a structural terminal signal and the gateway
+     * accepts a zero exit ONLY with init observed AND promptConsumed true —
+     * a missing, truncated, or error-status terminal is a provider-protocol
+     * failure BEFORE handoff ingestion. "none" = today's exit-code
+     * discipline, byte-identical for tier-1 providers.
+     */
+    terminalContract: "required" | "none";
+    isolation: {
+        /** The harness's hermetic flag, if it has one. We do not pass it. */
+        flag: string | null;
+        /** Whether that flag preserves resume. false = documented conflict. */
+        resumeSafe: boolean | null;
+        enforced: false;
+    };
+    /** User-global surfaces that can reach an invocation today. */
+    configSurface: readonly string[];
+};
+/** Read-only facts about a provider — safe anywhere, spawns nothing. */
+/**
+ * The tournament capability matrix (design v3 finding 14): what each
+ * harness can PROVE about money, stated as data. Eligibility is derived,
+ * never asserted: a provider races only when its own machinery can hold
+ * a dollar cap. Codex and OpenRouter report billable usage only at turn
+ * end (cumulative across resumed sessions), so no mid-run cap exists to
+ * hold — ineligible until their harnesses grow one.
+ */
+export type ProviderMoneyCapabilities = {
+    /** Usage events arrive during the run, not only at the end. */
+    incrementalUsage: boolean;
+    /** The harness's own dollar-cap flag, when one exists. */
+    nativeDollarCapFlag: string | null;
+    usageSemantics: "per-invocation" | "cumulative-session";
+    /** Whether this harness may race in a dollar-capped tournament. */
+    tournamentEligible: boolean;
+    /** Said in words on refusal screens. */
+    whyIneligible: string | null;
+};
+export declare const MONEY_CAPABILITIES: Record<ProviderId, ProviderMoneyCapabilities>;
+/**
+ * The fail-closed budget-flag probe (finding 24's amendment): resolve
+ * the EXACT executable that will spawn, read its version, and prove the
+ * flag exists in that binary's own help — presence is a feature check
+ * and nothing more; pricing and semantics stay pinned in pricing.ts.
+ */
+export declare function probeBudgetCap(provider: ProviderId, runner: (command: string, argv: readonly string[], options: {
+    timeoutMs?: number;
+    omitEnv?: readonly string[];
+}) => Promise<ExecResult>): Promise<{
+    ok: true;
+    executable: string;
+    version: string;
+} | {
+    ok: false;
+    problem: string;
+}>;
+export declare function auditOf(provider: ProviderId): ProviderAudit;
+/**
+ * A spec a person or a config row proposed, validated to a complete pair.
+ * openrouter REQUIRES a model: there is no meaningful harness default
+ * across a 300-model catalog.
+ */
+export declare function validateSpec(spec: AgentSpec): {
+    ok: true;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * Whether this provider reports dollar cost. The routine budget interacts:
+ * a ceiling against an unmeasured provider fails closed by design, so the
+ * approval surfaces refuse the combination outright.
+ */
+export declare function reportsCost(provider: ProviderId): boolean;
+/** The non-spending inspection surface: what `toolroll providers` reports. */
+export type ProviderInspection = {
+    id: ProviderId;
+    binary: string;
+    /** argv of a CHEAP identity probe, or null when none exists without spend. */
+    identityProbe: readonly string[] | null;
+    /** Env var whose PRESENCE matters (never its value). */
+    requiresEnv: string | null;
+    measuresCost: boolean;
+};
+export declare function inspectionOf(provider: ProviderId): ProviderInspection;
+export {};