toolroll 0.5.0

package/dist/invoke.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The invocation gateway: the only door to any provider binary (§5).
+ *
+ * "Never let an LLM poll" is only enforceable if there is exactly one place
+ * that can start an LLM, and this is it. Every call verifies an open run
+ * record WHOSE RECORDED PROVIDER MATCHES the one about to spawn (a repair
+ * resumed on the wrong harness is a meaningless session id and a silent
+ * fresh spend — refused here, structurally), stamps `provider_started_at`
+ * the instant before the process spawns, and parses usage off the envelope
+ * of EVERY completed process — nonzero exits included, because a failed
+ * turn still spent money and a cost report that skips failures is a
+ * smaller number, not a truer one.
+ *
+ * The architecture test asserts the boundary by imports, not by string
+ * scan: only this module imports the registry's spawning surface
+ * (`adapterFor`), and only builder, planner, reviewer, and scout import
+ * `invokeAgent`.
+ */
+import { type AgentSpec, type Invocation, type ProviderRunner, type AgentEnding } from "./provider.js";
+import { type VersionProbe } from "./attest.js";
+import { startClaudeHeldSession } from "./exec.js";
+import type { Store } from "./store.js";
+import type { RunOptions } from "./exec.js";
+export type { ProviderRunner } from "./provider.js";
+/** The claude binary name — kept for the legacy quota rows and tests that
+ * describe history; new code carries a resolved AgentSpec instead. */
+export declare const PROVIDER_BINARY = "claude";
+export type ProviderUsage = {
+    tokensIn: number | null;
+    tokensOut: number | null;
+    costUsd: number | null;
+};
+export type AgentOutcome = {
+    code: number;
+    stderr: string;
+    timedOut: boolean;
+    notFound: boolean;
+    /** The harness session, for repair-by-resume on the SAME provider. */
+    sessionId: string | null;
+    /** The agent's spoken conclusion — diagnostics, never the handoff. */
+    finalMessage: string | null;
+    /** The harness's own account of the ending, when its dialect has one. */
+    ending?: AgentEnding | null;
+    usage: ProviderUsage;
+    /**
+     * The harness never came up: the provider has an init signal, it was not
+     * seen, and the turn also has nothing to show. Config, auth, or install —
+     * not an agent's attempt, and callers must not treat it as one (M5
+     * provider audit: init failure is retryable infrastructure, and its
+     * distinct reason keeps a broken environment from reading as three
+     * strikes of bad agent work).
+     */
+    initFailed: boolean;
+};
+/**
+ * The value-shaped gateway result (Phase 3 B5): a refusal is a VALUE, so
+ * every caller's try/finally worktree release and disposition run exactly
+ * as they do for any other outcome — nothing here throws for these.
+ *
+ * - `provider-unattested`: the pre-spawn check failed (races past the
+ *   tick's pre-claim skip — an executable swap mid-tick). No process
+ *   started; the refused version is stamped on the run.
+ * - `provider-protocol`: the harness ran and broke its own contract — a
+ *   zero exit without the required terminal proof (A4), or an init
+ *   identity that does not match the minted one (A5). Spend was recorded;
+ *   the handoff must never be ingested.
+ */
+export type InvokeResult = {
+    kind: "ran";
+    outcome: AgentOutcome;
+} | {
+    kind: "refused";
+    reason: "provider-unattested" | "provider-protocol" | "chain-credential" | "chain-custody" | "runner-custody" | "auth-mode" | "route-authority" | "stopped" | "containment";
+    providerVersion: string | null;
+    diagnostic: string | null;
+    /** Bounded agent reply when a spawned turn later failed a protocol
+     * gate. Pre-spawn refusals omit it because no reply can exist. */
+    finalMessage?: string | null;
+};
+/**
+ * Spend money, on the record. Throws — never refuses quietly — when the run
+ * is missing, already finished, or recorded against a different provider:
+ * a caller that reaches for a harness without a matching open run is a
+ * bug, not a case. Attestation and protocol refusals are VALUES (above),
+ * not throws — those are cases, and they must dispose cleanly.
+ */
+export declare function invokeAgent(store: Store, runId: number, spec: AgentSpec, invocation: Omit<Invocation, "model">, options: RunOptions & {
+    runner?: ProviderRunner;
+    clock?: () => Date;
+    versionProbe?: VersionProbe;
+    keyHome?: string;
+    accumulateUsage?: boolean;
+}): Promise<InvokeResult>;
+/**
+ * The HELD invocation gateway (Parity II Phase 2, spec v2 S0b): the only
+ * door to the held-session transport, symmetric with invokeAgent — same
+ * open-run verification, same provider-match rule (claude only in Phase
+ * 2: nothing else can hold), same stamp-before-spawn honesty. It returns
+ * the live handle rather than awaiting session end: ownership of the
+ * hold belongs to the coordinator, never to a promise chain that would
+ * stall the watch.
+ */
+export declare function invokeHeldAgent(store: Store, runId: number, spec: AgentSpec, argv: readonly string[], options: import("./exec.js").RunOptions & {
+    socketPath: string;
+    cookie: string;
+    graceMs?: number;
+    events?: import("./exec.js").HeldSessionEvents;
+    readyTimeoutMs?: number;
+    clock?: () => Date;
+    starter?: typeof startClaudeHeldSession;
+    keyHome?: string;
+}): Promise<import("./exec.js").HeldSessionStart>;