@sema-agent/core 2.2.0 → 2.4.0

package/dist/agents/teacher.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { mapNestedSuspend, isDurablePause } from "./suspend-guard.js";
+import { isDefineToolProduct, stampDefineToolBrand } from "../core/tools.js";
 import { delimitUntrusted, inlineUntrusted } from "../core/untrusted-text.js";
 export const TEACHER_PROMPT = `You are an expert advisor to a less-capable "student" agent that got stuck.
 You receive the task and the student's recent failed attempts. Your job is to help the student RECOVER,
@@ -119,29 +120,56 @@ async function runTeacherCore(runner, studentSpec, teacher) {
         errorStreak = sig === lastErrSig ? errorStreak + 1 : 1;
         lastErrSig = sig;
     };
-    const wrap = (t) => ({
-        ...t,
-        execute: async (args, ctx) => {
-            try {
-                const out = await t.execute(args, ctx);
-                const text = typeof out === "string"
-                    ? out
-                    : out && typeof out === "object" && "content" in out
-                        ? String(out.content)
-                        : (JSON.stringify(out) ?? "");
-                logTool(t.name, args, text);
-                errorStreak = 0;
-                lastErrSig = "";
-                return out;
-            }
-            catch (e) {
-                const errText = String(e);
-                logTool(t.name, args, `ERROR: ${errText}`);
-                onToolFail(t.name, errText);
-                throw e;
-            }
-        },
-    });
+    const wrap = (t) => {
+        if (isDefineToolProduct(t)) {
+            const product = t;
+            return stampDefineToolBrand({
+                ...t,
+                execute: async (toolCallId, rawParams, signal, onUpdate) => {
+                    try {
+                        const out = await product.execute(toolCallId, rawParams, signal, onUpdate);
+                        const blocks = out && typeof out === "object" && "content" in out ? out.content : out;
+                        const text = Array.isArray(blocks)
+                            ? blocks.map((b) => (b && typeof b === "object" && "text" in b ? String(b.text) : "")).join("\n")
+                            : String(blocks ?? "");
+                        logTool(t.name, rawParams, text);
+                        errorStreak = 0;
+                        lastErrSig = "";
+                        return out;
+                    }
+                    catch (e) {
+                        const errText = String(e);
+                        logTool(t.name, rawParams, `ERROR: ${errText}`);
+                        onToolFail(t.name, errText);
+                        throw e;
+                    }
+                },
+            });
+        }
+        return {
+            ...t,
+            execute: async (args, ctx) => {
+                try {
+                    const out = await t.execute(args, ctx);
+                    const text = typeof out === "string"
+                        ? out
+                        : out && typeof out === "object" && "content" in out
+                            ? String(out.content)
+                            : (JSON.stringify(out) ?? "");
+                    logTool(t.name, args, text);
+                    errorStreak = 0;
+                    lastErrSig = "";
+                    return out;
+                }
+                catch (e) {
+                    const errText = String(e);
+                    logTool(t.name, args, `ERROR: ${errText}`);
+                    onToolFail(t.name, errText);
+                    throw e;
+                }
+            },
+        };
+    };
     const tools = studentSpec.tools?.map(wrap);
     const helperBase = () => teacher.helperModel
         ? { model: teacher.helperModel }

package/dist/brain/errors.d.ts

@@ -12,4 +12,5 @@ export declare class BrainError extends Error {
 export declare function classifyHttp(status: number): BrainErrorCode;
 export declare function extractErrorCode(errorMessage: string | undefined): BrainErrorCode | undefined;
 export declare function stripErrorCodePrefix(errorMessage: string): string;
+export declare function describeNetworkError(e: unknown): string;
 export {};

package/dist/brain/errors.js

@@ -42,3 +42,17 @@ export function extractErrorCode(errorMessage) {
 export function stripErrorCodePrefix(errorMessage) {
     return errorMessage.replace(CODE_PREFIX_RE, "");
 }
+export function describeNetworkError(e) {
+    const top = e instanceof Error ? e.message : String(e);
+    const parts = [];
+    let cur = e instanceof Error ? e.cause : undefined;
+    for (let depth = 0; depth < 4 && cur !== undefined && cur !== null; depth++) {
+        const code = typeof cur.code === "string" ? cur.code : undefined;
+        const msg = cur instanceof Error ? cur.message : String(cur);
+        const piece = code !== undefined && !msg.includes(code) ? `${code}: ${msg}` : msg;
+        if (piece.length > 0 && piece !== top && !parts.includes(piece))
+            parts.push(piece);
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return parts.length > 0 ? `${top} (${parts.join(" ← ")})` : top;
+}

package/dist/brain/stream-engine.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
-import { BrainError, classifyHttp } from "./errors.js";
+import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
 import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController } from "./timeout.js";
@@ -139,7 +139,7 @@ export function runStreamingBrain(args) {
                     continue;
                 }
                 if (netErr)
-                    throw new BrainError("network", netErr instanceof Error ? netErr.message : String(netErr));
+                    throw new BrainError("network", describeNetworkError(netErr));
                 const detail = r ? await r.text().catch(() => "") : "";
                 const status = r?.status ?? 0;
                 throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}`, status);
@@ -250,7 +250,7 @@ export function runStreamingBrain(args) {
                         throw e;
                     failure = {
                         kind: "connection",
-                        err: new BrainError("network", `mid-stream read failed: ${e instanceof Error ? e.message : String(e)}`),
+                        err: new BrainError("network", `mid-stream read failed: ${describeNetworkError(e)}`),
                     };
                     break readLoop;
                 }

package/dist/core/context-edit.js

@@ -1,7 +1,8 @@
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
+import { offloadPagebackHint } from "./tool-result-store.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
-const refNote = (ref) => `full text persisted; call ReadToolResult with ref "${ref}" to read it back`;
+const refNote = (ref) => offloadPagebackHint(ref, "cleared");
 const mediaNote = (blocks) => {
     const byType = new Map();
     for (const b of blocks) {

package/dist/core/runner/assemble-result.d.ts

@@ -68,6 +68,7 @@ export interface Stats {
 export interface ResultFlags {
     threw: unknown;
     model?: string;
+    unpricedSpend?: boolean;
     abortedForTimeout: boolean;
     abortedForTurns: boolean;
     abortedLive?: boolean;

package/dist/core/runner/assemble-result.js

@@ -36,14 +36,16 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     const taskId = spec.taskId ?? sessionId;
     const text = final ? assistantText(final) : "";
     stats.totalInputTokens = stats.promptTokens;
-    const compactionMicroUsd = stats.compactionMicroUsd ?? 0;
-    const nestedSubagentMicroUsd = stats.nested?.costMicroUsd ?? 0;
-    stats.costBreakdown = {
-        llmRootMicroUsd: Math.max(0, stats.costMicroUsd - compactionMicroUsd),
-        nestedSubagentMicroUsd,
-        memoryConsolidationMicroUsd: 0,
-        compactionMicroUsd,
-    };
+    if (!flags.unpricedSpend) {
+        const compactionMicroUsd = stats.compactionMicroUsd ?? 0;
+        const nestedSubagentMicroUsd = stats.nested?.costMicroUsd ?? 0;
+        stats.costBreakdown = {
+            llmRootMicroUsd: Math.max(0, stats.costMicroUsd - compactionMicroUsd),
+            nestedSubagentMicroUsd,
+            memoryConsolidationMicroUsd: 0,
+            compactionMicroUsd,
+        };
+    }
     let status;
     const result = text;
     let errorMessage;
@@ -139,5 +141,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     }
     const { compactionMicroUsd: _internalCompaction, ...publicStats } = stats;
     void _internalCompaction;
+    if (flags.unpricedSpend)
+        delete publicStats.costMicroUsd;
     return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, stats: publicStats };
 }

package/dist/core/runner/prepare-task.js

@@ -28,7 +28,7 @@ import { cloneObserverInput, formatHookFeedback, runToolGate } from "../hooks.js
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
-import { defineTool } from "../tools.js";
+import { defineTool, isDefineToolProduct } from "../tools.js";
 import { canonicalToolName } from "../tool-name-aliases.js";
 import { pathToUri } from "../lsp-protocol.js";
 import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, buildToolResultRef, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, isVolatileOffloadStore, OFFLOAD_TOOL_NAME, createReadToolResultTool, withToolResultOffload, } from "../tool-result-store.js";
@@ -435,10 +435,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
         ? new ScopedToolResultStore(rawOffloadStore, taskScope)
         : rawOffloadStore;
+    const offloadReachableToolsRef = {};
     const maybeOffload = (tool, perTool) => {
         if (!offloadStore || perTool?.offload === false)
             return tool;
-        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId);
+        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId, () => offloadReachableToolsRef.current?.());
     };
     const firstPartyOffload = (tool) => {
         const policy = firstPartyOffloadPolicy(tool.name);
@@ -796,10 +797,15 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             requestStopAfterTurn,
             ...(spec.enablePlanMode === true ? { enterPlanMode } : {}),
         });
-        const tools = (spec.tools ?? []).map((t) => maybeOffload(defineTool({
-            ...t,
-            execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
-        }), t));
+        const tools = (spec.tools ?? []).map((t) => {
+            if (isDefineToolProduct(t)) {
+                return maybeOffload(t, t);
+            }
+            return maybeOffload(defineTool({
+                ...t,
+                execute: (args, ctx) => t.execute(args, enrichSpecToolCtx(ctx)),
+            }), t);
+        });
         const blockedRef = {};
         if (spec.enableBlockedReport !== false) {
             tools.push(createReportBlockedTool(blockedRef));
@@ -1118,6 +1124,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         phase: "config",
                         sessionId,
                     });
+                    emitTrace(deps.tracer, () => ({
+                        kind: "config.additional_directory_skipped",
+                        version: 1,
+                        taskId: hostTaskId,
+                        entry: dir,
+                        reason: `${c.error.code}: ${c.error.message}`,
+                        ts: Date.now(),
+                    }));
                 }
             }
             if (spec.envFacts?.scratchpadDir) {
@@ -1217,7 +1231,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         if (backgroundTaskToolsActive || workflowToolsActive) {
             toolEffects.set("TaskOutput", "read");
             toolEffects.set("TaskStop", "write");
-            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
             if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
                 const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
                 const reviveSpawn = delegationForRevive !== undefined && deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined
@@ -1250,6 +1264,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(internals?.parentNotify !== undefined ? { uplink: internals.parentNotify } : {}),
                     ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
                     ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
+                    ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+                    ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
                     ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
                     ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
@@ -1277,6 +1293,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { onTaskNotification: internals.onTaskNotification } : {}),
                 ...(handsCwdRef !== undefined ? { cwdRef: handsCwdRef } : {}),
+                ...(offloadStore !== undefined ? { toolResultStore: offloadStore } : {}),
             })));
         }
         if (handsCwdRef !== undefined) {
@@ -1808,6 +1825,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (deferred.has(n))
                         activeTools.add(n);
             }
+            offloadReachableToolsRef.current = () => {
+                const s = new Set(tools.map((t) => t.name));
+                for (const n of deferred)
+                    if (!activeTools.has(n))
+                        s.delete(n);
+                s.add(TOOL_SEARCH_NAME);
+                return s;
+            };
             let toolSearch;
             const buildToolList = (active) => {
                 const list = tools.map((t) => (deferred.has(t.name) && !active.has(t.name) ? placeholders.get(t.name) : t));

package/dist/core/runner/runtask.js

@@ -45,7 +45,7 @@ import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
 export { DEFAULT_MAX_TURNS };
 function createRunState() {
     return {
-        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, tracer: undefined, taskId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
+        telemetry: { cacheFamily: "input-excludes-cached", pricing: { inputPer1M: 0, outputPer1M: 0 }, pricingConfigured: true, unpricedSpend: false, tracer: undefined, taskId: "", taskStart: 0, taskStartMonotonic: 0, cacheBreakReported: false },
         degrade: { degradeToModel: undefined, degraded: undefined, outputErrorStreak: 0, outputInvalid: false, recordDegraded: () => { } },
         limits: { turnsExceeded: false, budgetHit: undefined, outputRetryCap: 0, effectiveMaxTurns: undefined },
         budget: { remainingMicroUsd: undefined, maxCostMicroUsd: undefined, overBudget: () => false, streamCancel: false, callOutputChars: 0, lastStreamBudgetCheck: 0, projectedOverBudget: () => false },
@@ -788,6 +788,8 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             const u = m.usage;
             stats.tokens += u.totalTokens || 0;
             const { totalInputTokens: turnInput, costMicroUsd: turnCostMicroUsd } = usageCostMicroUsd(rs.telemetry.cacheFamily, u, rs.telemetry.pricing);
+            if (!rs.telemetry.pricingConfigured)
+                rs.telemetry.unpricedSpend = true;
             stats.promptTokens += turnInput;
             stats.cachedTokens += u.cacheRead || 0;
             stats.cacheWriteTokens += u.cacheWrite || 0;
@@ -826,7 +828,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 latencyMs: rs.turn.callStartAt !== undefined ? callEndAt - rs.turn.callStartAt : 0,
                 firstTokenMs: rs.turn.callStartAt !== undefined && rs.turn.firstTokenAt !== undefined ? rs.turn.firstTokenAt - rs.turn.callStartAt : undefined,
                 ...(callIssuedAt !== undefined ? { callStartedAt: callIssuedAt } : {}),
-                costMicroUsd: turnCostMicroUsd,
+                ...(rs.telemetry.pricingConfigured ? { costMicroUsd: turnCostMicroUsd } : {}),
                 ...(capLast !== undefined ? { callCap: capLast.cap, capThinkingSkipped: capLast.thinkingSkipped } : {}),
                 ...(m.role === "assistant" && typeof m.stopReason === "string"
                     ? { stopReason: m.stopReason }
@@ -1628,6 +1630,7 @@ export class Runner {
         const rs = createRunState();
         rs.telemetry.cacheFamily = cacheFamilyOf(prepared.model);
         rs.telemetry.pricing = this.deps.pricing?.[prepared.model.id] ?? modelCostToPricing(prepared.model.cost);
+        rs.telemetry.pricingConfigured = this.deps.pricing?.[prepared.model.id] !== undefined || prepared.model.cost !== undefined;
         if (spec.degrade) {
             try {
                 rs.degrade.degradeToModel = resolveModel(spec.degrade.to, this.deps.models);
@@ -1669,11 +1672,17 @@ export class Runner {
             }
             if (m) {
                 rs.telemetry.pricing = this.deps.pricing?.[m.id] ?? modelCostToPricing(m.cost);
+                rs.telemetry.pricingConfigured = this.deps.pricing?.[m.id] !== undefined || m.cost !== undefined;
                 rs.telemetry.cacheFamily = cacheFamilyOf(m);
             }
             else {
-                if (this.deps.pricing?.[info.to])
+                if (this.deps.pricing?.[info.to]) {
                     rs.telemetry.pricing = this.deps.pricing[info.to];
+                    rs.telemetry.pricingConfigured = true;
+                }
+                else {
+                    rs.telemetry.pricingConfigured = false;
+                }
                 rs.telemetry.cacheFamily = "input-excludes-cached";
             }
             rs.degrade.degraded = info;
@@ -2076,6 +2085,9 @@ export class Runner {
                 return;
             const fam = cacheFamilyOf(m);
             const price = this.deps.pricing?.[m.id] ?? modelCostToPricing(m.cost);
+            const priced = this.deps.pricing?.[m.id] !== undefined || m.cost !== undefined;
+            if (!priced)
+                rs.telemetry.unpricedSpend = true;
             const { totalInputTokens, costMicroUsd } = usageCostMicroUsd(fam, u, price);
             stats.tokens += u.totalTokens || 0;
             stats.promptTokens += totalInputTokens;
@@ -2088,7 +2100,7 @@ export class Runner {
                 kind: "brain.call", version: 1, taskId: rs.telemetry.taskId, model: m.id, provider: m.provider,
                 promptTokens: totalInputTokens, completionTokens: u.output || 0,
                 cacheRead: u.cacheRead || 0, cacheWrite: u.cacheWrite || 0,
-                latencyMs: 0, costMicroUsd, ...(typeof msg?.stopReason === "string" ? { stopReason: msg.stopReason } : {}), ts: Date.now(),
+                latencyMs: 0, ...(priced ? { costMicroUsd } : {}), ...(typeof msg?.stopReason === "string" ? { stopReason: msg.stopReason } : {}), ts: Date.now(),
             }));
         };
         const compactionBrain = {
@@ -2717,6 +2729,7 @@ export class Runner {
             const result = assembleResult(spec, prepared.sessionId, final, stats, {
                 threw,
                 model: prepared.model.id,
+                unpricedSpend: rs.telemetry.unpricedSpend,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,
                 abortedLive,
@@ -2835,7 +2848,7 @@ export class Runner {
                 errorCode: result.errorCode,
                 turns: stats.turns,
                 tokens: stats.tokens,
-                costMicroUsd: stats.costMicroUsd,
+                ...(rs.telemetry.unpricedSpend ? {} : { costMicroUsd: stats.costMicroUsd }),
                 durationMs: Date.now() - rs.telemetry.taskStart,
                 ...(prepared.outputRef.set ? { hasStructuredOutput: true } : {}),
                 ...(stats.mechanisms !== undefined

package/dist/core/runner/tool-output-projection.js

@@ -57,10 +57,11 @@ export const toolOutputFrom = (result) => {
     return { output: raw, truncated: true, totalChars };
 };
 const CC_DETAIL_TYPES = new Set([
-    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "text", "grep", "glob", "mcp",
+    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "file_unchanged", "worktree", "text", "grep", "glob", "mcp",
     "agent", "task", "task-list", "task-output", "memory-saved", "workflow-run",
     "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
     "task-stop", "tool-search", "memory-recall", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
+    "monitor-start", "path_not_in_root",
 ]);
 export const structuredFrom = (result) => {
     const details = result !== null && typeof result === "object" ? result.details : undefined;

package/dist/core/store-contracts/checkpoint-store-contract.d.ts

@@ -0,0 +1,37 @@
+import { type Checkpoint, type CheckpointStore, type ResumeOutcome } from "../checkpoint-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function createCheckpointFixture(over?: Partial<Checkpoint>): Checkpoint;
+export declare const ALLOW: Extract<ResumeOutcome, {
+    gate: "policy_ask";
+}>;
+export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function checkpointListByScopeSummaries(store: CheckpointStore): Promise<import("../checkpoint-store.js").CheckpointSummary[]>;
+export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
+    token: string;
+    sessionId: string;
+    scope: string;
+    gateKind: string;
+    severity: number;
+    deadline: number;
+    createdAt: number;
+    sourceTaskId: string;
+    principal: string;
+    toolCallId: string;
+    toolName: string;
+    toolInput: string;
+    spentMicroUsd?: undefined;
+} | {
+    token: string;
+    sessionId: string;
+    scope: string;
+    gateKind: string;
+    spentMicroUsd: number;
+    createdAt: number;
+    severity?: undefined;
+    deadline?: undefined;
+    sourceTaskId?: undefined;
+    principal?: undefined;
+    toolCallId?: undefined;
+    toolName?: undefined;
+    toolInput?: undefined;
+})[];

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -0,0 +1,195 @@
+import { strict as assert } from "node:assert";
+import { mintCheckpointToken, } from "../checkpoint-store.js";
+import { beginContract } from "./contract-harness.js";
+export function createCheckpointFixture(over = {}) {
+    const token = over.token ?? mintCheckpointToken();
+    return {
+        token,
+        scope: "tenant-a",
+        sessionId: "sess-1",
+        leafId: "leaf-1",
+        gate: { kind: "human", reason: "approve", toolName: "Write" },
+        pendingAction: {
+            kind: "tool_approval",
+            toolCallId: "call-3",
+            toolName: "Write",
+            args: { path: "/x", content: "y" },
+            boundInputHash: "h0",
+            batchToolCallIds: ["call-3"],
+            completedCallIds: [],
+        },
+        state: {
+            activeTools: [],
+            nestedStats: { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0 },
+        },
+        status: "pending",
+        createdAt: 1_700_000_000_000,
+        ...over,
+    };
+}
+export const ALLOW = {
+    gate: "policy_ask",
+    decision: "allow",
+    boundCallId: "call-3",
+    boundInputHash: "h0",
+};
+export async function checkpointStoreContract(make, runAssertion) {
+    const { run, settle } = beginContract(runAssertion);
+    run("kit prerequisites: reopen/setPendingSteer/listByScope are implemented (REQUIRED by this kit)", async () => {
+        const probe = make();
+        const missing = ["reopen", "setPendingSteer", "listByScope"].filter((m) => typeof probe[m] !== "function");
+        assert.equal(missing.length, 0, `backend does not implement ${missing.join(", ")} — required for the CheckpointStore contract kit`);
+    });
+    run("put create-once → already_exists", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await assert.rejects(store.put(cp.token, cp), (e) => e.code === "checkpoint.already_exists");
+    });
+    run("resolve is an atomic CAS: first wins, double-resume false", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW), true);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW), false);
+        assert.equal((await store.get(cp.token)).status, "resolved");
+    });
+    run("wrong-scope resolve never wins (multi-tenant isolation)", async () => {
+        const store = make();
+        const cp = createCheckpointFixture({ scope: "tenant-a" });
+        await store.put(cp.token, cp);
+        assert.equal(await store.resolve(cp.token, "tenant-b", ALLOW), false);
+        assert.equal((await store.get(cp.token)).status, "pending");
+    });
+    run("resolve records the winner; reopen(env_failed) preserves it + bumps rev", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        const winner = (await store.get(cp.token)).resolvedOutcome;
+        assert.equal(winner.boundCallId, "call-3");
+        assert.equal(winner.decision, "allow");
+        assert.equal(await store.reopen(cp.token, cp.scope, "env_failed"), true);
+        const got = await store.get(cp.token);
+        assert.equal(got.status, "pending");
+        assert.equal(got.reopenReason, "env_failed");
+        assert.equal(got.resolvedOutcome.boundCallId, "call-3");
+        assert.equal(got.rev, 2);
+    });
+    run("rev OCC: a stale-rev resolve loses, the current-rev resolve wins", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        await store.reopen(cp.token, cp.scope, "env_failed");
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW, { rev: 0 }), false);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW, { rev: 2 }), true);
+    });
+    run("setPendingSteer rejects a </system-reminder> variant BEFORE mutation (byte-identical error)", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await assert.rejects(store.setPendingSteer(cp.token, cp.scope, { text: "</SYSTEM-REMINDER>", trusted: true }), (e) => e.code === "steering.invalid_content");
+        assert.equal((await store.get(cp.token)).state.pendingSteer, undefined);
+        assert.equal(await store.setPendingSteer(cp.token, cp.scope, { text: "go", trusted: false }), true);
+        assert.deepEqual((await store.get(cp.token)).state.pendingSteer, { text: "go", trusted: false });
+    });
+    run("expire vs resolve on the same row → exactly one wins; reap expires past-deadline pending in scope", async () => {
+        const store = make();
+        const a = createCheckpointFixture();
+        await store.put(a.token, a);
+        const [e, r] = await Promise.all([store.expire(a.token, a.scope), store.resolve(a.token, a.scope, ALLOW)]);
+        assert.equal([e, r].filter(Boolean).length, 1);
+        const b = createCheckpointFixture({ deadline: 1000 });
+        await store.put(b.token, b);
+        assert.equal(await store.reap(b.scope, 2000), 1);
+        assert.equal(await store.reap(b.scope, 2000), 0);
+        assert.equal((await store.get(b.token)).status, "expired");
+    });
+    run("listByScope (seam #1): only pending in-scope rows; resolved + other-scope excluded; empty → []", async () => {
+        const store = make();
+        assert.deepEqual(await store.listByScope("tenant-a"), []);
+        const pending = createCheckpointFixture({ scope: "tenant-a", sessionId: "p" });
+        const resolved = createCheckpointFixture({ scope: "tenant-a", sessionId: "r" });
+        const other = createCheckpointFixture({ scope: "tenant-b", sessionId: "o" });
+        for (const cp of [pending, resolved, other])
+            await store.put(cp.token, cp);
+        await store.resolve(resolved.token, resolved.scope, ALLOW);
+        const list = await store.listByScope("tenant-a");
+        assert.equal(list.length, 1);
+        assert.equal(list[0].sessionId, "p");
+        assert.equal(list[0].token, pending.token);
+        assert.equal((await store.get(pending.token)).status, "pending");
+    });
+    await settle();
+}
+const sortByToken = (a, b) => a.token.localeCompare(b.token);
+export async function checkpointListByScopeSummaries(store) {
+    if (typeof store.listByScope !== "function") {
+        throw new Error("backend does not implement listByScope — required for checkpointListByScopeSummaries");
+    }
+    const escalation = createCheckpointFixture({
+        token: "tok-escalation",
+        scope: "tenant-a",
+        sessionId: "needs-approval",
+        deadline: 1_999_999_999_999,
+        createdAt: 1_700_000_000_000,
+        sourceTaskId: "needs-approval",
+        principal: "alice@corp",
+        gate: {
+            kind: "human",
+            reason: "approve",
+            toolName: "open_pr",
+            riskDescriptor: { severity: 5, axes: { egress: true, irreversible: true }, toolName: "open_pr" },
+        },
+        pendingAction: {
+            kind: "tool_approval",
+            toolCallId: "call-pr",
+            toolName: "open_pr",
+            args: { repo: "x" },
+            boundInputHash: "h0",
+            batchToolCallIds: ["call-pr"],
+            completedCallIds: [],
+        },
+    });
+    const resource = createCheckpointFixture({
+        token: "tok-resource",
+        scope: "tenant-a",
+        sessionId: "out-of-budget",
+        createdAt: 1_700_000_000_001,
+        gate: { kind: "resource_limit", reason: "budget" },
+        pendingAction: { kind: "resource_limit", reason: "budget" },
+        resourceLedger: { totalBudgetMicroUsd: 10_000_000, spentMicroUsd: 4_200_000, spentTokens: 9, spentTurns: 3, sliceCount: 2 },
+    });
+    const resolved = createCheckpointFixture({ token: "tok-resolved", scope: "tenant-a", sessionId: "done" });
+    const other = createCheckpointFixture({ token: "tok-other", scope: "tenant-b", sessionId: "x" });
+    const fixture = [escalation, resource, resolved, other];
+    for (const cp of fixture)
+        await store.put(cp.token, cp);
+    await store.resolve(resolved.token, resolved.scope, ALLOW);
+    return (await store.listByScope("tenant-a")).sort(sortByToken);
+}
+export const EXPECTED_LISTBYSCOPE_SUMMARIES = [
+    {
+        token: "tok-escalation",
+        sessionId: "needs-approval",
+        scope: "tenant-a",
+        gateKind: "human",
+        severity: 5,
+        deadline: 1_999_999_999_999,
+        createdAt: 1_700_000_000_000,
+        sourceTaskId: "needs-approval",
+        principal: "alice@corp",
+        toolCallId: "call-pr",
+        toolName: "open_pr",
+        toolInput: '{"repo":"x"}',
+    },
+    {
+        token: "tok-resource",
+        sessionId: "out-of-budget",
+        scope: "tenant-a",
+        gateKind: "resource_limit",
+        spentMicroUsd: 4_200_000,
+        createdAt: 1_700_000_000_001,
+    },
+];

package/dist/core/store-contracts/contract-harness.d.ts

@@ -0,0 +1,6 @@
+export type ContractAssertionRunner = (name: string, fn: () => Promise<void>) => void | Promise<void>;
+export declare function defaultSequentialRunner(_name: string, fn: () => Promise<void>): Promise<void>;
+export declare function beginContract(runAssertion?: ContractAssertionRunner): {
+    run: (name: string, fn: () => Promise<void>) => void;
+    settle: () => Promise<void>;
+};