@eir-labs/coltrane 0.24.30 → 0.24.32

package/dist/src/runtime.d.ts

@@ -10,10 +10,20 @@ import { type GigConformanceResult } from "./gig_conformance.js";
 import { type Ledger, type GigUsage } from "./ledger.js";
 import { type PlacementResolver } from "./placement.js";
 import type { Depth } from "./pricing.js";
+import type { Effort } from "./genome_schema.js";
 import type { SkillRecord, EvalRecord } from "./loader.js";
 export interface AgentInvocationContext {
     agent: Agent;
     phase: string;
+    /**
+     * The ROLE of the chair this invocation seats (Chair.role) — the seat's name within its phase.
+     * Threaded so buildPrompt can name the seat, and so two chairs seating the SAME agent in one
+     * phase do NOT receive byte-identical prompts: the division of labour a standard declares between
+     * them has to reach the model, not live only in the role names. Absent for a hand-built ctx (the
+     * text-seal literals and other tests that construct a context directly) — buildPrompt renders the
+     * seat only when a role is present, so those prompts stay valid and unchanged.
+     */
+    role?: string | undefined;
     gig_id?: string | undefined;
     /**
      * THE INSTITUTION'S DATA, delivered to the player it was supplied for: slot name → value, taken
@@ -39,6 +49,8 @@ export interface AgentInvocationContext {
     onEvent?: (ev: AgentStreamEvent) => void;
     signal?: AbortSignal | undefined;
     depth?: Depth | undefined;
+    effort?: Effort | undefined;
+    max_context_tokens?: number | undefined;
     realization?: Realization | undefined;
     venue?: Venue | undefined;
     substrateMcpConfigs?: Readonly<Record<string, unknown>> | undefined;
@@ -48,6 +60,16 @@ export interface AgentInvocationContext {
     } | undefined;
     turn_budget?: number | undefined;
     turn_reserve?: number | undefined;
+    resume?: boolean | undefined;
+    resume_keep_prompt?: boolean | undefined;
+    prime?: {
+        area: string;
+    } | undefined;
+    fork?: {
+        primer_session_id: string;
+        stale_paths: readonly string[];
+        frontier?: string;
+    } | undefined;
 }
 export interface AgentStreamEvent {
     type: string;
@@ -72,6 +94,15 @@ export type GigProgressEvent = {
     /** types actually SEALED */
     output_types: string[];
     duration_ms: number;
+    /**
+     * #seat-metrics — the ms from chair start to the FIRST write the chair's child emitted (a
+     * tool_use whose tool is Write/Edit/MultiEdit/NotebookEdit), and the context the seat carried
+     * then (input + cache_read + cache_creation of the last assistant usage BEFORE that write).
+     * A chair that never wrote records BOTH as null — present, never absent, never a stand-in 0,
+     * so "wrote at t=0" and "never wrote / never measured" cannot collide.
+     */
+    first_write_ms: number | null;
+    context_tokens_at_first_write: number | null;
     /** #243 — types the chair's output_contract PROMISED. Equal to output_types when the
      *  chair delivered everything; the difference is what `missing_output_types` names. */
     promised_output_types?: string[];
@@ -80,6 +111,37 @@ export type GigProgressEvent = {
     /** #240 — `*_sha` fields the engine could not tie to any consumed input or the gig
      *  payload. Sealed as "" rather than guessed; listed here so the gap is visible. */
     unresolved_sha_fields?: string[];
+    /** #seat-effort (O5) — the reasoning effort the seat actually ran at, as resolved by the
+     *  runtime (dispatch ▷ agent ▷ tier ▷ medium). Present for a model chair; absent for a skill
+     *  chair, which runs no model at an effort. */
+    effort?: Effort;
+    /** contract-chair-session-continuity-v1 (O4) — the seat's `claude` session id (the uuid
+     *  derived from (gig_id, role)) and whether THIS invocation RESUMED it (an amend round) rather
+     *  than opening it. Present for a model chair; absent for a skill chair, which runs no session. */
+    session_id?: string;
+    resumed?: boolean;
+    /** contract-amend-resume-prompt-v1 (F1) — set when this seat's amend RESUME found no session
+     *  and fell back COLD (a fresh --session-id spawn with the full prompt). The fallback never
+     *  fails the chair, but it is never silent either: this records that a resume was ATTEMPTED and
+     *  did not happen, rather than `resumed: true` claiming a continuation that never occurred.
+     *  Absent when no fallback fired. */
+    resume_fallback?: boolean;
+    /** contract-seat-primer-v1 (O3) — a forked chair records the primer it warm-started from: the
+     *  seat-primer record's id, the primer seat's own session_id, and the commit it sealed at.
+     *  Present only when the fork actually resumed the primer (absent on a cold fallback). */
+    forked_from?: {
+        id: string;
+        session_id: string;
+        commit: string;
+    };
+    /** contract-seat-primer-v1 (O4) — the primer files whose working-tree blob differs from the
+     *  blob recorded at priming (empty when none changed). Named in the fork's prompt too. Present
+     *  on a successful fork. */
+    primer_stale_paths?: string[];
+    /** contract-seat-primer-v1 (F1/F2) — the fork could not warm-start (no primer for this
+     *  agent+area → "primer_missing", or the primer's session could not be resumed → a reason
+     *  naming that session). The chair ran COLD and did not fail; this records why, never silently. */
+    fork_fallback?: string;
 } | {
     type: "chair_failed";
     phase: string;
@@ -172,25 +234,25 @@ export interface RunDeps {
     skill_dirs?: ReadonlyMap<string, string> | undefined;
     evals?: ReadonlyMap<string, EvalRecord> | undefined;
     /**
-     * Optional cost-budget input. When omitted (default), no budget enforcement
-     * runs — preserving v0 back-compat. When present, the runtime tracks
-     * per-gig BudgetState matching budget-state.json schema: balance =
-     * opening - spent + credit.
+     * Optional cost-budget input, in US DOLLARS ({ max_usd }). When omitted (default), or when
+     * present without a `max_usd`, no dollar enforcement runs — preserving v0 back-compat.
      *
-     * The cycle is RESERVE → SETTLE (#232). At chair-prep the runtime computes
-     * cost-of-append (base + k*size(input)) and compares it against
-     * `balance - reserved`; short → BudgetExhausted. Passing chairs RESERVE the
-     * cost. `spent` moves only when a chair's invocation SUCCEEDS, which is what
-     * the contract always claimed and what the code did not do: prep runs
-     * eagerly for the whole ready batch, so a batch member tripping the gate
-     * used to leave every earlier member of that batch charged for work no
-     * invoker ever started.
+     * When a ceiling is set the runtime tracks per-gig settled spend (the invokers' own
+     * `result`-event USD) and, at each dispatch-batch boundary (O2), refuses to start the NEXT
+     * batch once settled spend reaches `max_usd` — the batch already running is never interrupted.
+     * There is no pre-invocation reservation and no append-unit proxy: payload size does not gate.
      *
-     * The final BudgetState is returned in GigResult.budget_state, and is also
-     * attached to a BudgetExhausted / mid-gig error so a FAILED gig can still
-     * report what it cost.
+     * The final BudgetState is returned in GigResult.budget_state, and is also attached to a
+     * BudgetExhausted / mid-gig error so a FAILED gig can still report what it cost.
      */
     budget?: BudgetInput | undefined;
+    /**
+     * O6 — the gig reserve POOL, in turns, decoupled from any money budget. When set it opens the
+     * pool and OVERRIDES `Standard.reserve_pool` deterministically (no max, no sum). Absent → the
+     * standard default, then 0 (no pool). A turn pool in play yields a BudgetState even with no
+     * dollar ceiling: its pool fields are filled, its dollar fields omitted.
+     */
+    turn_pool?: number | undefined;
     onProgress?: ((ev: GigProgressEvent) => void) | undefined;
     gig_id?: string | undefined;
     /**
@@ -220,6 +282,20 @@ export interface RunDeps {
      * the thing that actually spends. Absent = each agent's own `depth_profile` stands.
      */
     depth?: Depth | undefined;
+    /**
+     * #seat-effort — the reasoning effort this gig was dispatched at, threaded to the resolver so
+     * dispatch effort wins over the agent's declared effort and the tier default (resolveEffort).
+     * Absent = no dispatch effort, so the agent's own `effort` or its tier default stands. Sibling of
+     * `depth`; the dispatch door threads it beside `depth` (src/server.ts).
+     */
+    effort?: Effort | undefined;
+    /**
+     * contract-seat-context-ceiling-v1 (O2) — the per-round context ceiling this gig was dispatched at,
+     * threaded to the resolver so a dispatch ceiling wins over the agent's declared `max_context_tokens`
+     * (resolveMaxContextTokens). Absent = no dispatch ceiling, so the agent's own field — or NONE — stands.
+     * Sibling of `effort`; the dispatch door threads it beside `effort` (src/server.ts).
+     */
+    max_context_tokens?: number | undefined;
     /**
      * Set by `runChart` (src/chart.ts) when this gig is a movement of an arrangement. Absent = a
      * plain single-standard run, byte-identical to every run before charts existed.
@@ -376,49 +452,41 @@ export interface RunDeps {
      * the room declines to populate (an empty read-only workspace) and no git credential is minted.
      */
     repoUrl?: string | undefined;
+    /**
+     * The directory whose git objects the SEAL stamps law and change addresses from (records-by-address,
+     * contract-records-by-address-v1). When a sealed `red-spec` record carries `laws` or a `change-set`
+     * record carries `changes`, the seal replaces those entries with ones the engine stamps from git in
+     * THIS directory — `blob_sha`/`tests` for a law, `blob_sha`/`patch_sha256`/`bytes` for a change —
+     * via `stampLawAddresses`/`stampChangeAddresses`. Stamping NEVER reads `process.cwd()`: a record
+     * carrying `laws`/`changes` sealed with no `tree_root` refuses with `tree_root_unknown`. Absent AND
+     * the sealed records carry only `diffs` (the pre-migration shape) = no stamping, byte-identical to
+     * before this field existed. Every door that runs a gig names the tree it stamps from; it is never
+     * an ambient host path.
+     */
+    tree_root?: string | undefined;
 }
 /**
- * Per-gig cost-budget input. Honors budget-state.json schema (PR #56). Only
- * `opening` is required for v0 enforcement; the rest are recomputed.
- *
- * COST FORMULA (v0, tunable):
- *   cost = base_cost + k * size_bytes(input)
- *   defaults: base_cost = 1, k = 0.1
+ * Per-gig cost-budget input. A budget is US DOLLARS (operator decision 2026-09-16): the
+ * single field is `max_usd`, the per-gig dollar ceiling.
  *
- * Where size_bytes(input) = JSON.stringify(canonical context).length.
+ * ENFORCEMENT (O2). The ceiling is checked against SETTLED spend — the invokers' own
+ * `result`-event `total_cost_usd`, reconciled at each dispatch-batch boundary — never a
+ * pre-invocation estimate. A batch already running is allowed to finish; the NEXT batch does
+ * not start once settled spend reaches `max_usd`. There is no append-unit proxy and no
+ * per-chair reservation: payload size does not decide whether a chair runs (I8/O3).
  *
- * WHAT THIS IS AND IS NOT (#233). `opening`/`spent`/`balance` are SYNTHETIC APPEND UNITS —
- * see `BudgetState.unit`. They are not dollars and were never converted to dollars; an
- * `opening: 1000` that reads like a dollar figure to an operator is a coincidence of scale.
- * The real, settled figure is `BudgetState.settled_usd`, reconciled from the model's own
- * `result` events at each batch boundary. Two honest limits on the synthetic gate:
+ * The retired append-unit knobs (`opening`, `base_cost`, `k`) and the retired `pool` field are
+ * gone. The reserve pool now opens from `RunDeps.turn_pool` (else `Standard.reserve_pool`),
+ * needs no money budget, and is orthogonal to the dollar ledger — a draw moves
+ * `BudgetState.pool_remaining` only, never `spent_usd`.
  *
- *   1. It is a proxy for prompt size, not a price. It has no model tier, no output side, no
- *      skills/charter/schema bytes — only the agent slug, phase, consumed input CONTENT and
- *      the gig payload. It is a rate limiter on context growth, nothing more.
- *   2. A USD figure cannot gate a chair before that chair runs, because `prepareChair` runs
- *      for the WHOLE ready batch before any invocation — a chair cannot see its batch
- *      siblings' settled cost. So reconciliation happens at BATCH BOUNDARIES, and any dollar
- *      bound built on it would be a cap plus one batch of slack, never a hard stop. No such
- *      bound is wired: there is no per-chair dollar estimator, and inventing one would be
- *      guessing. `settled_usd` reports; it does not enforce.
+ * `max_usd` is optional at the type level so a drain with no ceiling can pass `{}` ("no
+ * enforcement"); every door that accepts a budget validates it (a positive finite number)
+ * before anything runs.
  */
 export interface BudgetInput {
-    opening: number;
-    /** base cost per agent invocation, in append units. Default 1. */
-    base_cost?: number;
-    /** per-byte multiplier on consumed-input size, in append units. Default 0.1. */
-    k?: number;
-    /**
-     * #turn-budget — the gig-level reserve POOL, in turns: a shared quantity a budget-exhausted chair
-     * draws from, capped per chair by its own `turn_reserve`. This dispatch-payload value is the
-     * PRIMARY source and OVERRIDES `Standard.reserve_pool` deterministically when both are present
-     * (no max, no sum). Orthogonal to `opening`/`base_cost`/`k` — those are append-units, this is
-     * turns, and a draw moves `pool_remaining` only, never `spent`/`balance`. Absent → the standard
-     * default, then 0 (no pool). Distinct from 0 only in that 0 could equally be an authored empty
-     * pool; either way a chair reaching for a reserve finds nothing and is recorded as starved.
-     */
-    pool?: number;
+    /** The per-gig ceiling, in US dollars. Absent → no dollar enforcement. */
+    max_usd?: number;
 }
 /**
  * #turn-budget — one attributable draw against the gig reserve pool. `denied` marks a chair that
@@ -434,54 +502,48 @@ export interface ReserveDraw {
     denied?: boolean;
 }
 /**
- * Per-gig budget snapshot. Mirrors fields of domain_types/budget-state.json
- * (PR #56) that are runtime-tractable in v0. balance = opening - spent + credit.
+ * Per-gig budget snapshot. Present whenever a dollar ceiling OR a turn pool is in play (O6):
+ * the POOL fields (`pool_remaining`, `draws`) are filled regardless of money, and the DOLLAR
+ * fields (`max_usd`, `spent_usd`, `unit: "usd"`) only when a ceiling is set.
  *
- * The `agent_state` mirrors the budget-state.json enum:
- *   active           — currently spending, balance > cost-of-next-append
- *   yielding         — below cost-of-next-append, paused (used when partial)
- *   depleted         — balance <= 0 OR < cost-of-next-append, hard stop
+ * The `agent_state` enum:
+ *   active           — running normally
+ *   yielding         — a seated chair is currently drawing its reserve (D1)
+ *   depleted         — a drawing chair spent its reserve+pool without landing, OR the dollar
+ *                      ceiling stopped the next batch
  *   awaiting_grade   — work shipped, external grader contacted (v0 unused)
- *   settled          — cycle closed, closing populated (v0 set on success)
+ *   settled          — cycle closed on success
  */
 export interface BudgetState {
-    opening: number;
-    /** Cost of chairs that ACTUALLY RAN AND SUCCEEDED. Reserved-but-unsettled cost is not here. */
-    spent: number;
-    credit: number;
-    balance: number;
     agent_state: "active" | "yielding" | "depleted" | "awaiting_grade" | "settled";
     /** Slug of the agent whose invocation tripped depletion. null when solvent. */
     depleted_agent: string | null;
-    /** Wall-clock when balance first crossed below cost-of-next-append. null while solvent. */
+    /** Wall-clock when the gig crossed into depletion. null while solvent. */
     depleted_at: string | null;
-    base_cost: number;
-    k: number;
     /**
-     * #233 — the denomination of opening/spent/balance/base_cost/k, stated rather than assumed.
-     * These are a synthetic proxy for consumed context bytes. They are NOT dollars, and nothing
-     * converts between the two. Read `settled_usd` for money.
+     * The dollar ceiling this gig runs under, echoed onto the snapshot. Present ONLY when a
+     * ceiling is set (a turn-pool-only gig omits it).
      */
-    unit: "append-units";
+    max_usd?: number;
     /**
-     * #233 — REAL settled model spend for this gig so far, in USD, reconciled from the invokers'
-     * own `result` events at each dispatch-batch boundary. This is the number `src/ledger.ts`
-     * calls settled spend; the budget gate above never used it, even though it was live and
-     * in-scope. Reporting only — see the BudgetInput docstring for why it cannot gate.
-     * 0 when no invoker reported cost (stubbed invokers, skill-only gigs).
+     * REAL settled model spend for this gig so far, in USD, reconciled from the invokers' own
+     * `result` events at each dispatch-batch boundary. This is what the ceiling is enforced
+     * against (O2). Present ONLY under a ceiling; 0 when no invoker reported cost.
      */
-    settled_usd: number;
+    spent_usd?: number;
+    /** The denomination of the dollar fields, stated rather than assumed. Present ONLY under a ceiling. */
+    unit?: "usd";
     /**
-     * #turn-budget — turns remaining in the gig reserve pool (Item 2). Seeded from the dispatch
-     * `pool` (else `Standard.reserve_pool`, else 0), drawn down as chairs cross into reserve, never
-     * negative and never re-increased in v0 (strict draw-down, no preemption). Orthogonal to the
-     * append-unit ledger above: a draw moves ONLY this number.
+     * Turns remaining in the gig reserve pool. Seeded from `RunDeps.turn_pool` (else
+     * `Standard.reserve_pool`, else 0), drawn down as chairs cross into reserve, never negative and
+     * never re-increased in v0 (strict draw-down). Orthogonal to the dollar ledger: a draw moves
+     * ONLY this number, never `spent_usd`.
      */
     pool_remaining: number;
     /**
-     * #turn-budget — the attributable draw ledger (Item 2). One record per chair that reached for a
-     * reserve, granted or denied, so a post-run reader can see who drew, how much, and what the pool
-     * had left — and so a starved chair is visible rather than a silent no-op.
+     * The attributable draw ledger. One record per chair that reached for a reserve, granted or
+     * denied, so a post-run reader can see who drew, how much, and what the pool had left — and so
+     * a starved chair is visible rather than a silent no-op.
      */
     draws: ReserveDraw[];
 }
@@ -728,39 +790,72 @@ export declare class GigAborted extends Error {
 /** The human-readable cause behind an AbortSignal, whatever shape the aborter used. */
 export declare function abortReasonText(signal: AbortSignal): string;
 /**
- * Raised when a gig's budget cannot cover the next agent's cost-of-append.
- * Carries the agent_slug, the available balance, and the required cost so
- * the caller can render the exact reason. The in-memory BudgetState is
- * also attached for downstream telemetry.
+ * Raised when a gig's SETTLED dollar spend reaches its `max_usd` ceiling and the next batch may
+ * not start (O2/O5). Denominated in dollars: `spent_usd`, `max_usd`, `unit: "usd"`, and a message
+ * that names the amounts with `$` and `usd` — never append-units. The in-memory BudgetState is
+ * attached so a caller can render the full snapshot.
  */
 export declare class BudgetExhausted extends Error {
     readonly agent_slug: string;
-    readonly balance: number;
-    readonly cost: number;
+    readonly spent_usd: number;
+    readonly max_usd: number;
+    readonly unit: "usd";
     readonly state: BudgetState;
-    constructor(agent_slug: string, balance: number, cost: number, state: BudgetState);
+    constructor(agent_slug: string, spent_usd: number, max_usd: number, state: BudgetState);
 }
 /**
- * Cost-of-append for an agent invocation, in synthetic append units (see BudgetState.unit).
- * Deterministic function of the input context size — same input → same cost. Keeps cost
- * calculation inside the runtime (not the invoker) so budget enforcement cannot be spoofed by
- * a misbehaving invoker.
- *
- * #233 — this used to serialize `input_ids`: the UUIDs of the upstream outputs a chair
- * consumes, not their data. An upstream output contributed exactly 36 bytes whether it was a
- * one-line signal or a 40-page draft, so the proxy was not even monotonic in the thing that
- * drives real cost. It now measures the CONTENT the invoker actually receives.
- *
- * Still excluded, honestly: resolved skills, the agent charter, type schemas, model tier,
- * max_tool_calls, and the entire output side. This is a rate limiter on consumed context, not
- * a price. Money is `BudgetState.settled_usd`.
+ * Raised when a gig under a dollar ceiling cannot VERIFY its spend (F3): a settled invocation
+ * reported usage but no `total_cost_usd`, so the runtime cannot know whether the next batch is
+ * affordable. Fail-closed — no further batch starts. `reason` is the typed `budget_unverifiable`,
+ * and the message names the chairs whose dollar spend is unknown.
  */
-export declare function computeAppendCost(ctx: {
-    agent: Agent;
-    phase: string;
-    inputs: readonly OutputRecord[];
-    gig_input: Record<string, unknown>;
-}, base_cost: number, k: number): number;
+export declare class BudgetUnverifiable extends Error {
+    readonly reason = "budget_unverifiable";
+    readonly chairs: readonly string[];
+    readonly state: BudgetState;
+    constructor(chairs: readonly string[], state: BudgetState);
+}
+/**
+ * The model that DID a chair's work: the model that WROTE the most output tokens across the chair's
+ * `modelUsage` breakdown — NOT whichever key the CLI listed first. Claude Code spends a small
+ * background call on a fast model before the real work, and that model is listed FIRST while writing
+ * almost nothing, so a first-key stamp names a model that did none of the chair's work. Output
+ * tokens are the honest signal of which model produced the answer. Ties break on the model id
+ * (lexicographic ascending), so the stamp is deterministic regardless of the breakdown's key order.
+ * An empty map (a transport that reported no per-model breakdown) yields undefined — nothing to
+ * stamp, exactly as before.
+ */
+export declare function workingModel(outputByModel: ReadonlyMap<string, number>): string | undefined;
+type LawAddress = {
+    path: string;
+    commit: string;
+    blob_sha?: string;
+    tests?: string[];
+};
+type ChangeAddress = {
+    path: string;
+    base: string;
+    blob_sha?: string;
+    patch_sha256?: string;
+    bytes?: number;
+};
+/**
+ * Stamp each law's `blob_sha` (`git rev-parse <commit>:<path>`) and `tests` (the it/test titles in
+ * that blob, in file order) from a supplied `{path, commit}`, reading git in `tree_root`.
+ * REFUSALS: no `tree_root` → `tree_root_unknown` (never a `process.cwd()` fallback); an address that
+ * does not resolve (unknown commit, or a path absent at that commit) → `law_record_unresolvable`
+ * naming `path@commit`; a seat-supplied `blob_sha`/`tests` that disagrees with git → `law_bytes_mismatch`
+ * naming the path and field.
+ */
+export declare function stampLawAddresses(laws: readonly LawAddress[], tree_root: string | undefined): Array<Required<LawAddress>>;
+/**
+ * Stamp each change's `blob_sha` (`git hash-object` of the file in `tree_root`, or the literal
+ * `"deleted"` when the file is absent from the tree), `patch_sha256` (sha256 of `git diff <base> --
+ * <path>` in `tree_root`) and `bytes` (that diff's length) from a supplied `{path, base}`.
+ * REFUSALS: no `tree_root` → `tree_root_unknown`; a seat-supplied `blob_sha`/`patch_sha256`/`bytes`
+ * that disagrees with git → `law_bytes_mismatch` naming the path and field.
+ */
+export declare function stampChangeAddresses(changes: readonly ChangeAddress[], tree_root: string | undefined): Array<Required<ChangeAddress>>;
 /**
  * The structural identity of a pipeline: the standard's phase graph plus each bound agent's
  * type surface. Deterministic across machines for a given structure.
@@ -776,3 +871,4 @@ export declare function genomeHash(standard: Standard): string;
  *  this record satisfy this declared type" differently is the #263 defect wearing a new hat. */
 export declare function outputSatisfiesType(output: OutputRecord, declared: string): boolean;
 export declare function runGig(standard: Standard, gigInput: Record<string, unknown>, deps: RunDeps): Promise<GigResult>;
+export {};