@sema-agent/core 3.0.0 → 5.0.0

package/dist/brain/anthropic.js

@@ -1,7 +1,8 @@
 import {} from "../internal/llm.js";
 import { BrainError } from "./errors.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
-import { createRepetitionPoll, createWalltimeGate } from "./stream-shared.js";
+import { createRepetitionPoll, createWalltimeGate, parseStreamedToolArgs } from "./stream-shared.js";
+import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { ANTHROPIC_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
@@ -201,23 +202,11 @@ function closeToolUseBlock(acc) {
         return acc.closedTc;
     if (!acc.toolName)
         return undefined;
-    let args;
-    if (acc.toolJson) {
-        try {
-            const parsed = JSON.parse(acc.toolJson);
-            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
-                return undefined;
-            args = parsed;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    else {
-        args = {};
-    }
+    const args = parseStreamedToolArgs(acc.toolJson);
+    if (args === undefined)
+        return undefined;
     if (!acc.toolId)
-        acc.toolId = `toolu_${Math.random().toString(36).slice(2)}`;
+        acc.toolId = mintFallbackToolCallId("toolu_");
     acc.closedTc = { type: "toolCall", id: acc.toolId, name: acc.toolName, arguments: args };
     return acc.closedTc;
 }
@@ -339,6 +328,8 @@ export function createAnthropicBrain(config = {}) {
                 let stopReason = null;
                 let stopDetails;
                 let nextContentIndex = 0;
+                let malformedFrames = 0;
+                let malformedSample;
                 let degenerate = false;
                 let degenTextBlock;
                 const rep = createRepetitionPoll();
@@ -512,6 +503,8 @@ export function createAnthropicBrain(config = {}) {
                             evt = JSON.parse(data);
                         }
                         catch {
+                            malformedFrames++;
+                            malformedSample ??= data.slice(0, 160);
                             return;
                         }
                         handleEvent(evt);
@@ -563,6 +556,12 @@ export function createAnthropicBrain(config = {}) {
                                 text: `\n[note: ${malformed.length} tool call(s) were truncated (stop_reason="${stopReason ?? "?"}") and dropped — re-issue them next turn: ${malformed.join("; ")}]`,
                             });
                         }
+                        if (malformedFrames > 0) {
+                            finalContent.push({
+                                type: "text",
+                                text: `\n[note: ${malformedFrames} provider stream frame(s) were not valid JSON and were dropped — the streamed output may be missing content (first sample: ${JSON.stringify(malformedSample)})]`,
+                            });
+                        }
                         const truncatedEmpty = stopReason === "max_tokens" && noUsableContent && !toolError;
                         const dynamicCut = truncatedEmpty && options?.maxTokensDynamic === true;
                         const staticReasoningCut = truncatedEmpty && !dynamicCut && reasoningSeen && options?.staticReasoningCutDowngrade === true;
@@ -586,7 +585,7 @@ export function createAnthropicBrain(config = {}) {
                                                         ? `[length_empty] response truncated at max_tokens with no answer text (${maxTokensNote}) — the model emitted reasoning although no thinking was requested (a budget-ignoring gateway?) and it consumed the entire output budget; raise max_tokens`
                                                         : `[length_empty] response truncated at max_tokens with no answer text (${maxTokensNote}); raise max_tokens`
                                                 : emptyNoFinish
-                                                    ? `[stream_torn] model stream ended with no content and no stop_reason — the response was lost (a torn stream or an in-band provider error frame)`
+                                                    ? `[stream_torn] model stream ended with no content and no stop_reason — the response was lost (a torn stream or an in-band provider error frame)${malformedFrames > 0 ? ` — ${malformedFrames} unparseable data frame(s) were dropped on this stream (first sample: ${JSON.stringify(malformedSample)})` : ""}`
                                                     : undefined));
                         const errored = walltime.cut ||
                             degenerate ||
@@ -595,9 +594,13 @@ export function createAnthropicBrain(config = {}) {
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut && !staticReasoningCut);
-                        const errorKind = !walltime.cut && !degenerate && !safetyCut && toolError === undefined && truncatedEmpty && !dynamicCut && !staticReasoningCut
-                            ? "length_empty"
-                            : undefined;
+                        const errorKind = walltime.cut
+                            ? "walltime_cutoff"
+                            : degenerate
+                                ? "degenerate"
+                                : !safetyCut && toolError === undefined && truncatedEmpty && !dynamicCut && !staticReasoningCut
+                                    ? "length_empty"
+                                    : undefined;
                         const finalMessage = {
                             ...partial,
                             content: finalContent.length > 0 ? finalContent : [{ type: "text", text: "" }],

package/dist/brain/openai.js

@@ -1,7 +1,8 @@
 import {} from "../internal/llm.js";
 import { repairTextToolCalls } from "./tool-call-repair.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
-import { createRepetitionPoll, createWalltimeGate } from "./stream-shared.js";
+import { createRepetitionPoll, createWalltimeGate, parseStreamedToolArgs } from "./stream-shared.js";
+import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { OPENAI_RESERVED, applyExtraBody, stripAuthHeaders } from "./request-params.js";
@@ -12,23 +13,11 @@ function closeToolCallAccum(acc) {
         return acc.closedTc;
     if (!acc.name)
         return undefined;
-    let args;
-    if (acc.args) {
-        try {
-            const parsed = JSON.parse(acc.args);
-            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
-                return undefined;
-            args = parsed;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    else {
-        args = {};
-    }
+    const args = parseStreamedToolArgs(acc.args);
+    if (args === undefined)
+        return undefined;
     if (!acc.id)
-        acc.id = `call_${Math.random().toString(36).slice(2)}`;
+        acc.id = mintFallbackToolCallId("call_");
     acc.closedTc = { type: "toolCall", id: acc.id, name: acc.name, arguments: args };
     return acc.closedTc;
 }
@@ -356,6 +345,8 @@ export function createOpenAIBrain(config = {}) {
                 const toolAccum = new Map();
                 let finishReason = null;
                 let usageRaw;
+                let malformedFrames = 0;
+                let malformedSample;
                 const thinkingBlock = { type: "thinking", thinking: "" };
                 const textBlock = { type: "text", text: "" };
                 const pushReasoningDelta = (delta) => {
@@ -438,6 +429,8 @@ export function createOpenAIBrain(config = {}) {
                             chunk = JSON.parse(data);
                         }
                         catch {
+                            malformedFrames++;
+                            malformedSample ??= data.slice(0, 160);
                             return;
                         }
                         if (chunk.usage)
@@ -535,6 +528,12 @@ export function createOpenAIBrain(config = {}) {
                                 text: `\n[note: ${malformed.length} tool call(s) were truncated (finish_reason="${finishReason ?? "?"}") and dropped — re-issue them next turn: ${malformed.join("; ")}]`,
                             });
                         }
+                        if (malformedFrames > 0) {
+                            finalContent.push({
+                                type: "text",
+                                text: `\n[note: ${malformedFrames} provider stream frame(s) were not valid JSON and were dropped — the streamed output may be missing content (first sample: ${JSON.stringify(malformedSample)})]`,
+                            });
+                        }
                         const truncatedEmpty = finishReason === "length" && noUsableContent && !toolError;
                         const dynamicCut = truncatedEmpty && options?.maxTokensDynamic === true;
                         const safetyCut = finishReason === "content_filter";
@@ -557,7 +556,7 @@ export function createOpenAIBrain(config = {}) {
                                                     ? `[length_empty] response truncated at max_tokens (finish_reason="length", ${maxTokensNote}) with no answer text — the model spent the whole budget on reasoning (${accumReasoning.length} reasoning chars). Raise max_tokens, or disable thinking for this task.`
                                                     : `[length_empty] response truncated at max_tokens (finish_reason="length", ${maxTokensNote}) with no answer text — raise max_tokens`
                                                 : emptyNoFinish
-                                                    ? `[stream_torn] model stream ended with no content and no finish_reason — the response was lost (a torn stream or an in-band provider error frame)`
+                                                    ? `[stream_torn] model stream ended with no content and no finish_reason — the response was lost (a torn stream or an in-band provider error frame)${malformedFrames > 0 ? ` — ${malformedFrames} unparseable data frame(s) were dropped on this stream (first sample: ${JSON.stringify(malformedSample)})` : ""}`
                                                     : undefined));
                         const errored = walltime.cut ||
                             degenerate ||
@@ -566,9 +565,13 @@ export function createOpenAIBrain(config = {}) {
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut);
-                        const errorKind = !walltime.cut && !degenerate && !safetyCut && !refused && toolError === undefined && truncatedEmpty && !dynamicCut
-                            ? "length_empty"
-                            : undefined;
+                        const errorKind = walltime.cut
+                            ? "walltime_cutoff"
+                            : degenerate
+                                ? "degenerate"
+                                : !safetyCut && !refused && toolError === undefined && truncatedEmpty && !dynamicCut
+                                    ? "length_empty"
+                                    : undefined;
                         const finalMessage = {
                             ...partial,
                             content: finalContent.length > 0 ? finalContent : [{ type: "text", text: "" }],

package/dist/brain/stream-engine.js

@@ -8,7 +8,7 @@ const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
 const MAX_RETRIES_ENV = "SEMA_MAX_RETRIES";
 export function resolveMaxRetries(configured) {
-    if (configured !== undefined)
+    if (configured !== undefined && Number.isFinite(configured))
         return configured;
     const raw = process.env[MAX_RETRIES_ENV];
     if (raw !== undefined && raw.trim() !== "") {
@@ -88,10 +88,13 @@ export function runStreamingBrain(args) {
         .catch((err) => {
         const aborted = signal?.aborted === true || isAbortError(err);
         terminalRetryPhase = "gave_up";
-        terminalRetryDetail = aborted ? "cancelled while retrying" : isWalltimeCutoff(err) ? "wall-clock deadline reached while retrying" : "retries exhausted";
+        const walltimeCut = isWalltimeCutoff(err);
+        terminalRetryDetail = aborted ? "cancelled while retrying" : walltimeCut ? "wall-clock deadline reached while retrying" : "retries exhausted";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = err instanceof Error ? err.message : String(err);
+        if (walltimeCut)
+            errorMsg.errorKind = "walltime_cutoff";
         errorMsg.usageMissing = true;
         out.push({ type: "error", reason: aborted ? "aborted" : "error", error: errorMsg });
     })

package/dist/brain/stream-shared.d.ts

@@ -1,4 +1,5 @@
 import { type RepetitionEvent } from "./repetition.js";
+export declare function parseStreamedToolArgs(json: string): Record<string, unknown> | undefined;
 export interface RepetitionPoll {
     poll(text: string): boolean;
     readonly cut: RepetitionEvent | undefined;

package/dist/brain/stream-shared.js

@@ -1,4 +1,18 @@
 import { inspectDegenerate } from "./repetition.js";
+export function parseStreamedToolArgs(json) {
+    if (!json)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}
 export function createRepetitionPoll() {
     let repCut;
     const repSpared = new Map();

package/dist/brain/terminal-cause.d.ts

@@ -0,0 +1,4 @@
+import type { AssistantMessage } from "../internal/llm.js";
+export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind" | "errorMessage">;
+export declare function isDegenerateCutMessage(message: TerminalCauseCarrier): boolean;
+export declare function isWalltimeCutMessage(message: TerminalCauseCarrier): boolean;

package/dist/brain/terminal-cause.js

@@ -0,0 +1,12 @@
+import { DEGENERATE_MESSAGE } from "./repetition.js";
+import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
+export function isDegenerateCutMessage(message) {
+    if (message.errorKind === "degenerate")
+        return true;
+    return message.errorMessage === DEGENERATE_MESSAGE;
+}
+export function isWalltimeCutMessage(message) {
+    if (message.errorKind === "walltime_cutoff")
+        return true;
+    return message.errorMessage === WALLTIME_CUTOFF_MESSAGE;
+}

package/dist/brain/tool-call-id.d.ts

@@ -0,0 +1 @@
+export declare function mintFallbackToolCallId(prefix: string): string;

package/dist/brain/tool-call-id.js

@@ -0,0 +1,3 @@
+export function mintFallbackToolCallId(prefix) {
+    return `${prefix}${Math.random().toString(36).slice(2)}`;
+}

package/dist/brain/tool-call-repair.js

@@ -1,3 +1,4 @@
+import { mintFallbackToolCallId } from "./tool-call-id.js";
 const TAG_RE = /<(tool_call|function_call|tool_calls|function_calls)>\s*([\s\S]*?)\s*<\/\1>/gi;
 const FENCE_RE = /```(?:json|tool_call|tool|function)?\s*([\s\S]*?)```/gi;
 function asRecord(v) {
@@ -41,7 +42,7 @@ function extractCall(obj, toolNames, framed) {
     }
     return {
         type: "toolCall",
-        id: `repair_${name}_${Math.random().toString(36).slice(2, 8)}`,
+        id: mintFallbackToolCallId(`repair_${name}_`),
         name,
         arguments: args,
     };

package/dist/core/arg-summary.d.ts

@@ -1,2 +1,22 @@
-export declare function scrubSecrets(s: string): string;
+export type RedactionConfidence = "high" | "medium" | "low";
+export interface RedactionFinding {
+    kind: string;
+    span: readonly [number, number];
+    confidence: RedactionConfidence;
+    marker: string;
+}
+export interface RedactionReport {
+    findings: RedactionFinding[];
+    preexistingMarkers?: number;
+}
+export interface RedactionPass {
+    kind: string;
+    confidence: RedactionConfidence;
+    marker: string;
+    re: RegExp;
+    replace: string | ((match: string, ...groups: string[]) => string);
+}
+export declare function runRedactionPasses(input: string, passes: readonly RedactionPass[], report?: RedactionReport): string;
+export declare const SECRET_PASSES: readonly RedactionPass[];
+export declare function scrubSecrets(s: string, report?: RedactionReport): string;
 export declare function primaryActivityArg(args: unknown): string | undefined;

package/dist/core/arg-summary.js

@@ -1,24 +1,71 @@
 const ACTIVITY_ARG_MAX = 80;
 const SENSITIVE_KEY = /token|secret|key|password|passwd|credential|auth/i;
-const SECRET_PATTERNS = [
-    { re: /(?<![A-Za-z0-9])(?:sk|pk|rk|gh[opsur])[-_][A-Za-z0-9_-]{8,}/g, replace: "[redacted]" },
-    { re: /(?<![A-Za-z0-9])AIza[A-Za-z0-9_-]{20,}/g, replace: "[redacted]" },
-    { re: /(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{10,}/g, replace: "[redacted]" },
-    { re: /(?<![A-Za-z0-9])AKIA[0-9A-Z]{12,}/g, replace: "[redacted]" },
-    { re: /(?<![A-Za-z0-9])hf_[A-Za-z0-9]{20,}/g, replace: "[redacted]" },
-    { re: /(?<![A-Za-z0-9])eyJ[A-Za-z0-9._-]{20,}/g, replace: "[redacted]" },
-    { re: /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?(?:-----END[ A-Z]*PRIVATE KEY-----|$)/g, replace: "[redacted]" },
-    { re: /(?<![A-Za-z0-9])Bearer\s+[A-Za-z0-9._~+/-]{8,}=*/gi, replace: "[redacted]" },
+function mapBackOnePass(edits, pos) {
+    let delta = 0;
+    for (const e of edits) {
+        const outStart = e.at + delta;
+        if (pos < outStart)
+            return pos - delta;
+        const outEnd = outStart + e.insertedLen;
+        if (pos < outEnd)
+            return e.at;
+        delta += e.insertedLen - e.removedLen;
+    }
+    return pos - delta;
+}
+const PREEXISTING_MARKER_RE = /\[redacted(?:-[a-z]+)?\]/g;
+export function runRedactionPasses(input, passes, report) {
+    if (report !== undefined && report.preexistingMarkers === undefined) {
+        report.preexistingMarkers = input.match(PREEXISTING_MARKER_RE)?.length ?? 0;
+    }
+    const batches = [];
+    let cur = input;
+    for (const pass of passes) {
+        const edits = [];
+        cur = cur.replace(pass.re, (...args) => {
+            const match = args[0];
+            const offset = args[args.length - 2];
+            const groups = args.slice(1, -2);
+            const inserted = typeof pass.replace === "string"
+                ? pass.replace.replace(/\$(\d)/g, (_m, d) => groups[Number(d) - 1] ?? "")
+                : pass.replace(match, ...groups);
+            if (inserted !== match) {
+                if (report !== undefined) {
+                    let s0 = offset;
+                    let e0 = offset + match.length;
+                    for (let i = batches.length - 1; i >= 0; i--) {
+                        s0 = mapBackOnePass(batches[i], s0);
+                        e0 = mapBackOnePass(batches[i], e0);
+                    }
+                    report.findings.push({ kind: pass.kind, confidence: pass.confidence, span: [s0, e0], marker: pass.marker });
+                }
+                edits.push({ at: offset, removedLen: match.length, insertedLen: inserted.length });
+            }
+            return inserted;
+        });
+        batches.push(edits);
+    }
+    return cur;
+}
+export const SECRET_PASSES = [
+    { kind: "prefixed-token", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])(?:sk|pk|rk|gh[opsur])[-_][A-Za-z0-9_-]{8,}/g, replace: "[redacted]" },
+    { kind: "prefixed-token", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])AIza[A-Za-z0-9_-]{20,}/g, replace: "[redacted]" },
+    { kind: "prefixed-token", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{10,}/g, replace: "[redacted]" },
+    { kind: "prefixed-token", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])AKIA[0-9A-Z]{12,}/g, replace: "[redacted]" },
+    { kind: "prefixed-token", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])hf_[A-Za-z0-9]{20,}/g, replace: "[redacted]" },
+    { kind: "jwt", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])eyJ[A-Za-z0-9._-]{20,}/g, replace: "[redacted]" },
+    { kind: "private-key-block", confidence: "high", marker: "[redacted]", re: /-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?(?:-----END[ A-Z]*PRIVATE KEY-----|$)/g, replace: "[redacted]" },
+    { kind: "bearer-token", confidence: "high", marker: "[redacted]", re: /(?<![A-Za-z0-9])Bearer\s+[A-Za-z0-9._~+/-]{8,}=*/gi, replace: "[redacted]" },
     {
+        kind: "keyword-value",
+        confidence: "medium",
+        marker: "[redacted]",
         re: /(?<![A-Za-z0-9])((?:token|secret|key|password|passwd|credential|authorization)["']?\s*[=:]\s*["']?)[^\s"';|&]{4,}/gi,
         replace: "$1[redacted]",
     },
 ];
-export function scrubSecrets(s) {
-    let out = s;
-    for (const { re, replace } of SECRET_PATTERNS)
-        out = out.replace(re, replace);
-    return out;
+export function scrubSecrets(s, report) {
+    return runRedactionPasses(s, SECRET_PASSES, report);
 }
 function truncCodePoints(s) {
     const cp = Array.from(s);

package/dist/core/auto-compaction.d.ts

@@ -23,6 +23,7 @@ export interface CompactionWindowSafetyInfo {
 export declare const STALE_ANCHOR_STRUCTURAL_MARGIN = 2;
 export declare function sanitizeCompactionSettings(settings: CompactionSettings, contextWindow: number | undefined): CompactionSettings;
 export interface MaybeCompactOptions {
+    onNotifyError?: (failure: import("./safe-notify.js").SafeNotifyFailure) => void;
     session: Session;
     epochDeclaredSections?: import("../prompt-assembly/epoch.js").EpochDeclaredSections;
     centerAdoption?: {

package/dist/core/auto-compaction.js

@@ -5,6 +5,7 @@ import { selectCompactionEpoch } from "../prompt-assembly/epoch.js";
 import { SEMA_DEFAULT_PACK } from "../prompt-assembly/packs/sema-default.js";
 import { brainToRuntime } from "./runtime.js";
 import { defuseFenceMarkers, sanitizeUntrustedText } from "./untrusted-text.js";
+import { createSafeNotifier } from "./safe-notify.js";
 export const DEFAULT_COMPACTION_INSTRUCTIONS = "Preserve verbatim every code, identifier, name, number, file path, error message, credential " +
     "reference, and explicit user instruction or decision mentioned anywhere in the conversation. " +
     "When in doubt, keep the specific detail rather than generalizing it.";
@@ -96,6 +97,7 @@ export async function maybeCompact(opts) {
         return { contextUsage, compacted: false, noop: true };
     }
     const trigger = opts.trigger ?? "auto";
+    const notifier = createSafeNotifier(opts.onNotifyError !== undefined ? { onError: opts.onNotifyError } : undefined);
     let hookInstructions;
     if (opts.preCompact) {
         let pre;
@@ -183,11 +185,7 @@ export async function maybeCompact(opts) {
         }
         const contentTokens = dry !== undefined ? Math.ceil((dry.conversationChars + (prep.value.previousSummary?.length ?? 0)) / cpt) : 0;
         const observeWindowSafety = (info) => {
-            try {
-                opts.onWindowSafety?.(info);
-            }
-            catch {
-            }
+            notifier.notify(() => opts.onWindowSafety?.(info), "compaction.onWindowSafety");
         };
         if (wantsWindowSafety && dry !== undefined) {
             const tolerance = settings.clampTolerance ?? DEFAULT_CLAMP_TOLERANCE;
@@ -498,27 +496,20 @@ export async function maybeCompact(opts) {
     }
     catch {
     }
-    try {
-        opts.onCompaction?.({
-            messagesCompacted: prep.value.messagesToSummarize.length,
-            freedTokens,
-            tokensBefore: summaryTokensBefore,
-            reused,
-        });
-    }
-    catch {
-    }
+    const messagesCompacted = prep.value.messagesToSummarize.length;
+    notifier.notify(() => opts.onCompaction?.({
+        messagesCompacted,
+        freedTokens,
+        tokensBefore: summaryTokensBefore,
+        reused,
+    }), "compaction.onCompaction");
     if (opts.postCompact) {
-        try {
-            await opts.postCompact({
-                trigger,
-                summary,
-                tokensBefore: summaryTokensBefore,
-                ...(postTriggerTokens !== undefined ? { tokensAfter: postTriggerTokens } : {}),
-            });
-        }
-        catch {
-        }
+        await notifier.notifyAsync(() => opts.postCompact?.({
+            trigger,
+            summary,
+            tokensBefore: summaryTokensBefore,
+            ...(postTriggerTokens !== undefined ? { tokensAfter: postTriggerTokens } : {}),
+        }), "compaction.postCompact");
     }
     const endAt = Date.now();
     return {

package/dist/core/background-agent-store.d.ts

@@ -73,18 +73,24 @@ export declare function canAccessAgentRecord(record: Pick<BackgroundAgentRecord,
     sessionId?: string;
 }): boolean;
 export declare const STALE_RUNNING_REAP_ATTRIBUTION = "the host process was interrupted while this agent was running \u2014 its in-process state was lost. Check its worktree / output file for partial work before assuming the task landed (stale running row reaped).";
+export interface BackgroundAgentUpdateIfExpect {
+    rev: number;
+    status?: BackgroundAgentRecord["status"];
+    parkedCheckpointToken?: string | null;
+    parkClaimId?: string | null;
+}
+export interface BackgroundAgentReapOptions {
+    maxAgeMs?: number;
+    keep?: number;
+    staleRunningMaxAgeMs?: number;
+}
 export interface BackgroundAgentStore {
     put(record: BackgroundAgentRecord): Promise<void>;
     get(handle: string, scope: string): Promise<BackgroundAgentRecord | null>;
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
     }): Promise<boolean>;
-    updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
-        rev: number;
-        status?: BackgroundAgentRecord["status"];
-        parkedCheckpointToken?: string | null;
-        parkClaimId?: string | null;
-    }): Promise<boolean>;
+    updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: BackgroundAgentUpdateIfExpect): Promise<boolean>;
     listBySession(scope: string, sessionId: string, opts?: {
         status?: BackgroundAgentRecord["status"];
         limit?: number;
@@ -97,11 +103,7 @@ export interface BackgroundAgentStore {
         rev: number;
     }): Promise<boolean>;
     listScopes?(): Promise<string[]>;
-    reap(scope: string, now: number, opts?: {
-        maxAgeMs?: number;
-        keep?: number;
-        staleRunningMaxAgeMs?: number;
-    }): Promise<number>;
+    reap(scope: string, now: number, opts?: BackgroundAgentReapOptions): Promise<number>;
 }
 export declare function reconcileParkedAgents(stores: {
     agentStore: BackgroundAgentStore;
@@ -114,6 +116,13 @@ export declare function reconcileParkedAgents(stores: {
     failed: number;
     rolledBack: number;
 }>;
+export interface BackgroundAgentQuery {
+    scope: string;
+    sessionId?: string;
+    status?: BackgroundAgentRecord["status"];
+    limit?: number;
+}
+export declare function queryBackgroundAgents(rows: Iterable<BackgroundAgentRecord>, query: BackgroundAgentQuery): BackgroundAgentRowSummary[];
 export declare class InMemoryBackgroundAgentStore implements BackgroundAgentStore {
     private rows;
     private key;
@@ -122,12 +131,7 @@ export declare class InMemoryBackgroundAgentStore implements BackgroundAgentStor
     update(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
         rev: number;
     }): Promise<boolean>;
-    updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: {
-        rev: number;
-        status?: BackgroundAgentRecord["status"];
-        parkedCheckpointToken?: string | null;
-        parkClaimId?: string | null;
-    }): Promise<boolean>;
+    updateIf(handle: string, scope: string, record: BackgroundAgentRecord, expect: BackgroundAgentUpdateIfExpect): Promise<boolean>;
     listBySession(scope: string, sessionId: string, opts?: {
         status?: BackgroundAgentRecord["status"];
         limit?: number;
@@ -140,9 +144,5 @@ export declare class InMemoryBackgroundAgentStore implements BackgroundAgentStor
         rev: number;
     }): Promise<boolean>;
     listScopes(): Promise<string[]>;
-    reap(scope: string, now: number, opts?: {
-        maxAgeMs?: number;
-        keep?: number;
-        staleRunningMaxAgeMs?: number;
-    }): Promise<number>;
+    reap(scope: string, now: number, opts?: BackgroundAgentReapOptions): Promise<number>;
 }

package/dist/core/background-agent-store.js

@@ -173,6 +173,23 @@ function toSummary(r) {
         ...(r.usage !== undefined ? { usage: structuredClone(r.usage) } : {}),
     };
 }
+export function queryBackgroundAgents(rows, query) {
+    const out = [];
+    for (const r of rows) {
+        if (r.scope !== query.scope)
+            continue;
+        if (query.sessionId !== undefined) {
+            const anchor = r.sessionScoped ? r.owner : r.parentSessionId;
+            if (anchor !== query.sessionId && r.rootSessionId !== query.sessionId)
+                continue;
+        }
+        if (query.status !== undefined && r.status !== query.status)
+            continue;
+        out.push(toSummary(r));
+    }
+    out.sort((a, b) => b.spawnedAt - a.spawnedAt);
+    return query.limit !== undefined ? out.slice(0, Math.max(0, query.limit)) : out;
+}
 export class InMemoryBackgroundAgentStore {
     rows = new Map();
     key(handle, scope) {
@@ -220,31 +237,10 @@ export class InMemoryBackgroundAgentStore {
         return this.update(handle, scope, record, { rev: expect.rev });
     }
     async listBySession(scope, sessionId, opts) {
-        const out = [];
-        for (const r of this.rows.values()) {
-            if (r.scope !== scope)
-                continue;
-            const anchor = r.sessionScoped ? r.owner : r.parentSessionId;
-            if (anchor !== sessionId && r.rootSessionId !== sessionId)
-                continue;
-            if (opts?.status !== undefined && r.status !== opts.status)
-                continue;
-            out.push(toSummary(r));
-        }
-        out.sort((a, b) => b.spawnedAt - a.spawnedAt);
-        return opts?.limit !== undefined ? out.slice(0, Math.max(0, opts.limit)) : out;
+        return queryBackgroundAgents(this.rows.values(), { scope, sessionId, status: opts?.status, limit: opts?.limit });
     }
     async listByScope(scope, opts) {
-        const out = [];
-        for (const r of this.rows.values()) {
-            if (r.scope !== scope)
-                continue;
-            if (opts?.status !== undefined && r.status !== opts.status)
-                continue;
-            out.push(toSummary(r));
-        }
-        out.sort((a, b) => b.spawnedAt - a.spawnedAt);
-        return opts?.limit !== undefined ? out.slice(0, Math.max(0, opts.limit)) : out;
+        return queryBackgroundAgents(this.rows.values(), { scope, status: opts?.status, limit: opts?.limit });
     }
     async delete(handle, scope, expect) {
         const k = this.key(handle, scope);