@sema-agent/core 5.2.0 → 5.4.0

package/dist/core/runner/runtask.js

@@ -40,6 +40,7 @@ import { refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.
 import { defaultTaskRegistry } from "../task-registry.js";
 import { discloseDroppedPending, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
+import { workflowSizeGuidelineChangeNotice } from "../../orchestration/workflow-size-guideline.js";
 import { DEFAULT_MAX_TURNS } from "../../config/defaults.js";
 import { structuredFrom, toolOutputFrom } from "./tool-output-projection.js";
 export { DEFAULT_MAX_TURNS };
@@ -51,7 +52,7 @@ function createRunState() {
         budget: { remainingMicroUsd: undefined, maxCostMicroUsd: undefined, overBudget: () => false, streamCancel: false, callOutputChars: 0, lastStreamBudgetCheck: 0, projectedOverBudget: () => false },
         turn: { callStartAt: undefined, firstTokenAt: undefined, turnUsage: undefined, turnUsageMissing: false, turnStopReason: undefined, lastTurnHadToolCalls: false, toolBatch: [] },
         counters: { nudgesSent: 0, nudgeIdx: 0, finalizeInjected: false, walltimeSyncBackstopFired: false, compactionFloor: 0, trimForceBackoff: false, callCutoffs: 0, repetitionCuts: 0, repetitionSpared: 0, repetitionEvents: [], REPETITION_EVENTS_CAP: 0, preemptIgnoredReported: false, wroteThisRun: false, finalVerifyInjections: 0, groundingSignalPreR9: false, groundingSignalPostR9: false, cadenceTurns: 0 },
-        attach: { attachmentsCfg: undefined, agentListingOn: false, skillsListingOn: false, attachState: undefined, dateState: undefined, instrProbe: undefined, instrState: undefined, attachmentsInjected: 0 },
+        attach: { attachmentsCfg: undefined, agentListingOn: false, skillsListingOn: false, attachState: undefined, dateState: undefined, instrProbe: undefined, instrState: undefined, sizeGuidelineState: undefined, attachmentsInjected: 0 },
     };
 }
 const MAX_CONSECUTIVE_COMPACTION_FAILURES = 3;
@@ -314,7 +315,10 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
         }
         let boundaryAttachmentBytes = 0;
         let attachmentsPayload;
-        if ((rs.attach.dateState !== undefined || rs.attach.instrState !== undefined || rs.attach.attachState !== undefined) &&
+        if ((rs.attach.dateState !== undefined ||
+            rs.attach.instrState !== undefined ||
+            rs.attach.sizeGuidelineState !== undefined ||
+            rs.attach.attachState !== undefined) &&
             !boundarySteered &&
             !rs.counters.finalizeInjected &&
             rs.counters.finalVerifyInjections === 0 &&
@@ -457,6 +461,16 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     rs.attach.dateState.announcedDate = today;
                 }
             }
+            if (rs.attach.sizeGuidelineState !== undefined && rs.turn.lastTurnHadToolCalls) {
+                const guideline = rs.attach.sizeGuidelineState.current();
+                if (guideline !== rs.attach.sizeGuidelineState.announcedGuideline) {
+                    due.splice(due.length > 0 && due[0].source === "date_change" ? 1 : 0, 0, {
+                        source: "workflow_size_guideline_change",
+                        body: workflowSizeGuidelineChangeNotice(guideline),
+                    });
+                    rs.attach.sizeGuidelineState.announcedGuideline = guideline;
+                }
+            }
             if (rs.attach.instrState !== undefined && rs.attach.instrProbe !== undefined && rs.turn.lastTurnHadToolCalls) {
                 let probed = null;
                 try {
@@ -1770,6 +1784,10 @@ export class Runner {
             rs.attach.instrProbe !== undefined && prepared.instructionSources !== undefined && prepared.instructionSources.length > 0
                 ? { lastAnnouncedHash: new Map(prepared.instructionSources.map((s) => [s.path, s.contentHash])) }
                 : undefined;
+        rs.attach.sizeGuidelineState =
+            prepared.workflowSizeGuideline !== undefined
+                ? { announcedGuideline: prepared.workflowSizeGuideline.legGuideline, current: prepared.workflowSizeGuideline.current }
+                : undefined;
         rs.counters.cadenceTurns = 0;
         rs.turn.lastTurnHadToolCalls = false;
         if (rs.attach.attachState !== undefined && rs.attach.attachmentsCfg?.backgroundTasks === true) {
@@ -2620,6 +2638,7 @@ export class Runner {
         catch (err) {
             if (errorCodeOf(err) === "resume.tool_unavailable") {
                 await settleTeardownLeg(() => prepared.mcp.dispose(), "mcp.dispose (tool_unavailable leg)", (e) => this.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+                await settleTeardownLeg(() => prepared.a2a?.dispose(), "a2a.dispose (tool_unavailable leg)", (e) => this.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
                 await settleTeardownLeg(() => (prepared.ownedEnv && hasDestroy(prepared.ownedEnv) ? prepared.ownedEnv.destroy() : undefined), "ownedEnv.destroy (tool_unavailable leg)", (e) => this.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
                 throw err;
             }
@@ -2640,6 +2659,9 @@ export class Runner {
             unsubBoundary();
             unsub();
         }
+        if (threw === undefined && prepared.brainCallGuardrailRef.timedOut !== undefined) {
+            threw = prepared.brainCallGuardrailRef.timedOut;
+        }
         const suspended = prepared.suspendRef.token !== undefined && prepared.suspendRef.gate !== undefined;
         const reviewPaused = prepared.reviewRef.token !== undefined && prepared.reviewRef.gate !== undefined;
         const durablyPaused = suspended || reviewPaused;
@@ -3198,12 +3220,12 @@ export class Runner {
         if (outcome.gate === "policy_ask") {
             const boundTo = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.toolCallId : undefined;
             if (outcome.boundCallId !== boundTo) {
-                throw new CheckpointError("checkpoint.invalid_outcome", `resume boundCallId "${outcome.boundCallId}" does not match the checkpoint's pending tool call "${boundTo ?? "(none)"}" — the decision-action binding (design/80 D-1) failed; refusing to apply a decision bound to a different action`);
+                throw new CheckpointError("checkpoint.invalid_outcome", `resume boundCallId "${outcome.boundCallId}" does not match the checkpoint's pending tool call "${boundTo ?? "(none)"}" — the decision-action binding (design/80 D-1) failed; refusing to apply a decision bound to a different action`, { field: "boundCallId" });
             }
             const boundHash = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.boundInputHash : undefined;
             if (boundHash !== undefined) {
                 if (outcome.boundInputHash !== boundHash) {
-                    throw new CheckpointError("checkpoint.invalid_outcome", "resume boundInputHash does not match the checkpoint's pending tool call input — the decision-action input binding (design/80 D-1 §2) failed; refusing to apply an approval bound to a different input (TOCTOU re-mint guard)");
+                    throw new CheckpointError("checkpoint.invalid_outcome", "resume boundInputHash does not match the checkpoint's pending tool call input — the decision-action input binding (design/80 D-1 §2) failed; refusing to apply an approval bound to a different input (TOCTOU re-mint guard)", { field: "boundInputHash" });
                 }
             }
             else if (checkpointVersionOf(cp) >= BINDING_CHECKPOINT_VERSION) {
@@ -3520,6 +3542,14 @@ export class Runner {
         catch (err) {
             this.deps.onError?.(err, { phase: "mcp", sessionId: prepared.sessionId });
         }
+        if (prepared.a2a !== undefined) {
+            try {
+                await prepared.a2a.dispose();
+            }
+            catch (err) {
+                this.deps.onError?.(err, { phase: "a2a", sessionId: prepared.sessionId });
+            }
+        }
         return comp;
     }
     async teardownOwnedEnv(prepared) {

package/dist/core/runner/tool-disclosure.d.ts

@@ -14,7 +14,7 @@ export declare function deferHint(description: string, max?: number): string;
 export declare function safeName(name: string): string;
 export declare function classifyDeferred(opts: {
     specs: ReadonlyArray<ToolSpec>;
-    mcpToolNames: ReadonlyArray<string>;
+    protocolToolNames: ReadonlyArray<string>;
     fullTools: ReadonlyArray<ToolFingerprintInput>;
     deferMode?: "auto";
     model: Model;

package/dist/core/runner/tool-disclosure.js

@@ -35,7 +35,7 @@ export function classifyDeferred(opts) {
         if (s.defer === true && !pinned.has(s.name))
             deferred.add(s.name);
     }
-    for (const name of opts.mcpToolNames)
+    for (const name of opts.protocolToolNames)
         if (!pinned.has(name))
             deferred.add(name);
     for (const name of opts.deferNames ?? [])

package/dist/core/runner/turn-attachments.d.ts

@@ -15,7 +15,7 @@ export declare const TOOL_SEARCH_REMINDER_CONFIG: {
 export declare const CHANGED_FILES_MAX = 20;
 export declare const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export declare const ATTACHMENT_BYTE_CAP: number;
-export type AttachmentSource = "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
+export type AttachmentSource = "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
 export interface AgentListingEntry {
     name: string;
     description: string;
@@ -31,7 +31,6 @@ export interface TurnAttachment {
     body: string;
 }
 export interface ListProjection {
-    statusCounts: Record<string, number>;
     items: Array<{
         content: string;
         status: string;

package/dist/core/runner/turn-attachments.js

@@ -47,12 +47,7 @@ export function reduceToolEnd(state, details) {
                 : [];
         });
         const allDone = shaped.length > 0 && shaped.every((t) => t.status === "completed");
-        state.todo = allDone
-            ? { statusCounts: {}, items: [] }
-            : {
-                statusCounts: countStatuses(shaped),
-                items: shaped.slice(0, PROJECTION_ITEMS_MAX),
-            };
+        state.todo = allDone ? { items: [] } : { items: shaped.slice(0, PROJECTION_ITEMS_MAX) };
     }
     else if (d.type === "task") {
         const map = state.taskItems ?? (state.taskItems = new Map());
@@ -120,12 +115,6 @@ export function rebaseCadenceWindows(state, clock) {
     state.toolSearchLastUseTurn = clock;
     state.lastToolSearchReminderTurn = clock;
 }
-function countStatuses(items) {
-    const counts = {};
-    for (const t of items)
-        counts[t.status] = (counts[t.status] ?? 0) + 1;
-    return counts;
-}
 const EMPTY = Object.freeze([]);
 export function collectDueAttachments(state, inp) {
     let out;

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

@@ -0,0 +1,5 @@
+import { type BackgroundAgentStore } from "../background-agent-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare const BACKGROUND_AGENT_CONTRACT_SCOPE = "tenant-A";
+export declare function backgroundAgentStoreContract(mk: () => BackgroundAgentStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function backgroundAgentStoreScopesContract(mk: () => BackgroundAgentStore, runAssertion?: ContractAssertionRunner): Promise<void>;

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

@@ -0,0 +1,213 @@
+import { strict as assert } from "node:assert";
+import { STALE_RUNNING_REAP_ATTRIBUTION, } from "../background-agent-store.js";
+import { beginContract } from "./contract-harness.js";
+export const BACKGROUND_AGENT_CONTRACT_SCOPE = "tenant-A";
+function record(over = {}) {
+    return {
+        handle: "a0000000000000001",
+        scope: BACKGROUND_AGENT_CONTRACT_SCOPE,
+        owner: "task-1",
+        sessionScoped: false,
+        parentSessionId: "sess-1",
+        writerId: "writer-1",
+        spawnedAt: 1_000,
+        updatedAt: 1_000,
+        status: "running",
+        rev: 0,
+        ...over,
+    };
+}
+async function withStores(mk, fn) {
+    const live = [];
+    const make = () => {
+        const s = mk();
+        live.push(s);
+        return s;
+    };
+    try {
+        await fn(make);
+    }
+    finally {
+        for (const s of live.splice(0))
+            s.close?.();
+    }
+}
+async function held(store, handle, scope = BACKGROUND_AGENT_CONTRACT_SCOPE) {
+    const row = await store.get(handle, scope);
+    assert.notEqual(row, null, `row ${handle} should exist in scope ${scope}`);
+    return row;
+}
+export async function backgroundAgentStoreContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = BACKGROUND_AGENT_CONTRACT_SCOPE;
+    run("put is create-once and scope-partitioned; get round-trips the row and is null cross-scope", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", finalOutput: "result-text" }));
+        await assert.rejects(store.put(record({ handle: "a1" })), (e) => e.code === "agent_record.already_exists", "a second put under the same (handle, scope) must throw the typed already_exists error");
+        await store.put(record({ handle: "a1", scope: "tenant-B" }));
+        const row = await held(store, "a1");
+        assert.equal(row.finalOutput, "result-text");
+        assert.equal(row.owner, "task-1");
+        assert.equal(await store.get("a1", "tenant-C"), null, "an unrelated scope must not see the row");
+        assert.equal(await store.get("a-missing", S), null);
+    });
+    run("put refuses a scopeless row (a row with no tenant partition would be world-readable)", async (make) => {
+        const store = make();
+        await assert.rejects(store.put(record({ scope: "" })), "an empty scope must be refused loudly, not stored");
+    });
+    run("get returns DETACHED copies: mutating a read never reaches the stored row", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", usage: { totalTokens: 5 } }));
+        const first = await held(store, "a1");
+        first.status = "failed";
+        first.usage.totalTokens = 999;
+        const second = await held(store, "a1");
+        assert.equal(second.status, "running");
+        assert.equal(second.usage?.totalTokens, 5);
+    });
+    run("update is a rev-CAS: stale rev loses, wrong scope loses, the winner bumps rev by EXACTLY 1", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1" }));
+        const row = await held(store, "a1");
+        assert.equal(await store.update("a1", "tenant-B", { ...row, status: "completed" }, { rev: row.rev }), false, "wrong scope");
+        assert.equal(await store.update("a1", S, { ...row, status: "completed" }, { rev: row.rev + 5 }), false, "rev ahead");
+        assert.equal(await store.update("a-missing", S, { ...row, status: "completed" }, { rev: row.rev }), false, "missing row");
+        assert.equal(await store.update("a1", S, { ...row, status: "completed" }, { rev: row.rev }), true);
+        const after = await held(store, "a1");
+        assert.equal(after.status, "completed");
+        assert.equal(after.rev, row.rev + 1);
+        assert.equal(await store.update("a1", S, { ...row, status: "failed" }, { rev: row.rev }), false);
+        assert.equal((await held(store, "a1")).status, "completed");
+    });
+    run("update keeps the KEY authoritative: a payload naming another handle/scope cannot repartition the row", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1" }));
+        const row = await held(store, "a1");
+        assert.equal(await store.update("a1", S, { ...row, handle: "a-other", scope: "tenant-B", status: "failed" }, { rev: row.rev }), true);
+        const after = await held(store, "a1");
+        assert.equal(after.handle, "a1", "the key's handle wins over the payload's");
+        assert.equal(after.scope, S, "scope is the partition key and an update must never rewrite it");
+        assert.equal(await store.get("a-other", "tenant-B"), null, "no second row may appear");
+    });
+    run("updateIf keeps the rev guard AND adds the field guards (status / checkpoint token / claim id)", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "parked", parkedCheckpointToken: "cp-1" }));
+        const row = await held(store, "a1");
+        assert.equal(await store.updateIf("a1", S, { ...row, status: "running" }, { rev: row.rev + 3 }), false, "stale rev");
+        assert.equal(await store.updateIf("a1", S, { ...row, status: "running" }, { rev: row.rev, status: "running" }), false, "status mismatch");
+        assert.equal(await store.updateIf("a1", S, { ...row, status: "running" }, { rev: row.rev, status: "parked", parkedCheckpointToken: "cp-OTHER" }), false, "checkpoint token mismatch");
+        assert.equal(await store.updateIf("a1", S, { ...row, status: "running" }, { rev: row.rev, parkedCheckpointToken: null }), false, "null must mean 'this field is absent', and it is present");
+        assert.equal(await store.updateIf("a1", S, { ...row, status: "running" }, { rev: row.rev, parkClaimId: "claim-1" }), false, "claim id expected but absent");
+        const next = { ...row, status: "running", parkClaimId: "claim-1" };
+        assert.equal(await store.updateIf("a1", S, next, { rev: row.rev, status: "parked", parkedCheckpointToken: "cp-1", parkClaimId: null }), true, "matching guards (incl. null-as-absent on the claim id) must win");
+        const after = await held(store, "a1");
+        assert.equal(after.status, "running");
+        assert.equal(after.parkClaimId, "claim-1");
+        assert.equal(after.rev, row.rev + 1);
+    });
+    run("listBySession anchors on (sessionScoped ? owner : parentSessionId) OR rootSessionId, newest-first", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", spawnedAt: 1_000, finalOutput: "SECRET", summary: "s", error: "e", recentSteps: [] }));
+        await store.put(record({ handle: "a2", owner: "sess-1", sessionScoped: true, parentSessionId: undefined, spawnedAt: 2_000 }));
+        await store.put(record({ handle: "a3", parentSessionId: "sess-mid", rootSessionId: "sess-1", spawnedAt: 3_000 }));
+        await store.put(record({ handle: "a4", parentSessionId: "sess-other", spawnedAt: 4_000 }));
+        const rows = await store.listBySession(S, "sess-1");
+        assert.deepEqual(rows.map((r) => r.handle), ["a3", "a2", "a1"], "newest-first by spawnedAt");
+        for (const row of rows) {
+            for (const field of ["finalOutput", "summary", "error", "recentSteps", "editedFiles"]) {
+                assert.equal(Object.hasOwn(row, field), false, `list projections must not carry ${field}`);
+            }
+        }
+        assert.deepEqual((await store.listBySession(S, "sess-1", { limit: 2 })).map((r) => r.handle), ["a3", "a2"], "limit keeps the NEWEST n");
+        assert.deepEqual(await store.listBySession("tenant-B", "sess-1"), [], "another tenant sees nothing");
+        assert.deepEqual((await store.listBySession(S, "sess-mid")).map((r) => r.handle), ["a3"], "the intermediate anchor still lists its direct child");
+    });
+    run("listBySession/listByScope filter one status; listByScope enumerates the whole tenant", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "running", spawnedAt: 1_000 }));
+        await store.put(record({ handle: "a2", status: "completed", spawnedAt: 2_000 }));
+        await store.put(record({ handle: "a3", status: "completed", parentSessionId: "sess-other", spawnedAt: 3_000 }));
+        await store.put(record({ handle: "a4", status: "completed", scope: "tenant-B", spawnedAt: 4_000 }));
+        assert.deepEqual((await store.listByScope(S)).map((r) => r.handle), ["a3", "a2", "a1"], "scope-wide, newest-first");
+        assert.deepEqual((await store.listByScope(S, { status: "completed" })).map((r) => r.handle), ["a3", "a2"]);
+        assert.deepEqual((await store.listByScope(S, { status: "completed", limit: 1 })).map((r) => r.handle), ["a3"]);
+        assert.deepEqual((await store.listBySession(S, "sess-1", { status: "completed" })).map((r) => r.handle), ["a2"]);
+        assert.deepEqual((await store.listByScope("tenant-B")).map((r) => r.handle), ["a4"], "tenants are separate ledgers");
+    });
+    run("delete is row-precise and CONDITIONAL when a rev is supplied (a concurrent revival must win)", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "completed" }));
+        await store.put(record({ handle: "a2", status: "completed" }));
+        const row = await held(store, "a1");
+        assert.equal(await store.delete("a1", S, { rev: row.rev + 1 }), false, "a stale rev must not delete");
+        assert.notEqual(await store.get("a1", S), null);
+        assert.equal(await store.delete("a1", "tenant-B"), false, "cross-scope delete is a miss");
+        assert.equal(await store.delete("a1", S, { rev: row.rev }), true);
+        assert.equal(await store.get("a1", S), null);
+        assert.equal(await store.delete("a1", S), false, "deleting a gone row reports false, not true");
+        assert.equal(await store.delete("a2", S), true, "an unconditional delete still works");
+    });
+    run("reap with NO policy is a no-op (retention is always explicit)", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "completed", settledAt: 1_000 }));
+        assert.equal(await store.reap(S, 100_000), 0);
+        assert.equal(await store.reap(S, 100_000, {}), 0);
+        assert.notEqual(await store.get("a1", S), null);
+    });
+    run("reap deletes terminal rows by age and by keep-bound; running and parked rows survive BOTH", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "completed", spawnedAt: 1_000, settledAt: 1_000 }));
+        await store.put(record({ handle: "a2", status: "running", spawnedAt: 1_000, updatedAt: 1_000 }));
+        await store.put(record({ handle: "a3", status: "parked", spawnedAt: 1_000, updatedAt: 1_000, parkedCheckpointToken: "cp-1" }));
+        assert.equal(await store.reap(S, 100_000, { maxAgeMs: 10 }), 1, "only the terminal row ages out");
+        assert.equal(await store.get("a1", S), null);
+        assert.equal((await held(store, "a2")).status, "running");
+        assert.equal((await held(store, "a3")).status, "parked");
+        for (const i of [1, 2, 3])
+            await store.put(record({ handle: `b${i}`, status: "completed", spawnedAt: 1_000 + i, settledAt: 2_000 + i }));
+        assert.equal(await store.reap(S, 100_000, { keep: 2 }), 1);
+        assert.deepEqual((await store.listByScope(S, { status: "completed" })).map((r) => r.handle), ["b3", "b2"]);
+        assert.notEqual(await store.get("a2", S), null);
+        assert.notEqual(await store.get("a3", S), null);
+    });
+    run("reap's stale-running arm flips to a terminal `failed` WITH the shared attribution, and never overwrites real failure text", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "running", updatedAt: 1_000 }));
+        await store.put(record({ handle: "a2", status: "running", updatedAt: 1_000, error: "the child reported a real failure" }));
+        assert.equal(await store.reap(S, 100_000, { staleRunningMaxAgeMs: 50_000 }), 2);
+        const flipped = await held(store, "a1");
+        assert.equal(flipped.status, "failed", "an interrupted host's row settles as a terminal, not a perpetual running");
+        assert.equal(flipped.stoppedBy, "system");
+        assert.equal(flipped.settledAt, 100_000);
+        assert.equal(flipped.updatedAt, 100_000);
+        assert.equal(flipped.error, STALE_RUNNING_REAP_ATTRIBUTION);
+        assert.equal(flipped.summary, STALE_RUNNING_REAP_ATTRIBUTION);
+        assert.equal((await held(store, "a2")).error, "the child reported a real failure");
+        await store.put(record({ handle: "a3", status: "running", updatedAt: 99_000 }));
+        assert.equal(await store.reap(S, 100_000, { staleRunningMaxAgeMs: 50_000 }), 0);
+        assert.equal((await held(store, "a3")).status, "running");
+    });
+    run("reap counts each ROW once even when the same sweep flips it AND removes it", async (make) => {
+        const store = make();
+        await store.put(record({ handle: "a1", status: "running", spawnedAt: 1_000, updatedAt: 1_000 }));
+        assert.equal(await store.reap(S, 100_000, { staleRunningMaxAgeMs: 50_000, keep: 0 }), 1, "one row changed, so the count is 1");
+        assert.equal(await store.get("a1", S), null, "and it really is gone (flipped, then trimmed)");
+    });
+    await settle();
+}
+export async function backgroundAgentStoreScopesContract(mk, runAssertion) {
+    const { run: runRaw, settle } = beginContract(runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    run("listScopes enumerates the scopes that currently HOLD rows, deduplicated and sorted", async (make) => {
+        const store = make();
+        assert.equal(typeof store.listScopes, "function", "this layer is only for backends that implement listScopes");
+        await store.put(record({ handle: "a1", scope: "tenant-B" }));
+        await store.put(record({ handle: "a2", scope: "tenant-A" }));
+        await store.put(record({ handle: "a3", scope: "tenant-A" }));
+        assert.deepEqual(await store.listScopes(), ["tenant-A", "tenant-B"], "deduplicated and sorted — a retention loop drives itself off this");
+        await store.delete("a1", "tenant-B");
+        assert.deepEqual(await store.listScopes(), ["tenant-A"]);
+    });
+    await settle();
+}

package/dist/core/task-registry-agent.d.ts

@@ -1,5 +1,5 @@
 import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
-import { type StopSource, type TaskAccess, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
+import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import { type ToolResultStore } from "./tool-result-store.js";
 export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
 export declare function durableAgentWriteLane(handle: BackgroundAgentTaskHandle, patch: Partial<BackgroundAgentRecord>, clear?: readonly (keyof BackgroundAgentRecord)[]): void;
@@ -126,6 +126,19 @@ export declare function notFoundRunningAgentsTail(footer: {
     named: string[];
     background: string[];
 }): string;
+export interface AgentPollDetailsInput {
+    taskId: string;
+    status: UnifiedTaskOutput["status"];
+    retrievalStatus: TaskRetrievalStatus;
+    seq?: number;
+    stoppedBy?: StopSource;
+    error?: string;
+    errorCode?: string;
+    errorRetryable?: boolean;
+    resultIsPartial?: boolean;
+    completionId?: string;
+}
+export declare function buildAgentPollDetails(input: AgentPollDetailsInput): UnifiedTaskOutput;
 export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): UnifiedTaskResult;
 export declare function spillClippedAgentResult(handle: BackgroundAgentTaskHandle, full: string, clipped: string, store: ToolResultStore | undefined, sessionId: string | undefined): Promise<string>;
 export declare function pollBackgroundAgentLane(handle: BackgroundAgentTaskHandle, deadline?: number, signal?: AbortSignal, oneShot?: boolean, store?: ToolResultStore, sessionId?: string): Promise<UnifiedTaskResult>;

package/dist/core/task-registry-agent.js

@@ -1008,7 +1008,7 @@ export function notFoundRunningAgentsTail(footer) {
     return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
         (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
 }
-function buildAgentPollDetails(input) {
+export function buildAgentPollDetails(input) {
     const failed = input.status === "failed";
     return {
         task_id: input.taskId,
@@ -1016,7 +1016,7 @@ function buildAgentPollDetails(input) {
         status: input.status,
         retrieval_status: input.retrievalStatus,
         ...(input.seq !== undefined ? { seq: input.seq } : {}),
-        ...(input.status === "killed" && input.stoppedBy !== undefined ? { stoppedBy: input.stoppedBy } : {}),
+        ...(input.stoppedBy !== undefined ? { stoppedBy: input.stoppedBy } : {}),
         ...(failed && input.error !== undefined ? { error: delimitUntrusted("agent error", boundedRedactedSummary(input.error, 300)) } : {}),
         ...(failed && input.errorCode !== undefined ? { errorCode: input.errorCode } : {}),
         ...(failed && input.errorRetryable !== undefined ? { retryable: input.errorRetryable } : {}),

package/dist/core/types.d.ts

@@ -197,6 +197,19 @@ export interface McpServerSpec {
         irreversibility?: "always" | "never";
     }>;
 }
+export interface A2aServerSpec {
+    name: string;
+    url: string;
+    cardUrl?: string;
+    headers?: Record<string, string>;
+    principalHeader?: string;
+    allowSkills?: string[];
+    toolAxes?: Record<string, {
+        effect?: ToolEffect;
+        egress?: boolean;
+        irreversibility?: "always" | "never";
+    }>;
+}
 export interface McpElicitRequest {
     server: string;
     message: string;
@@ -296,6 +309,7 @@ export interface TaskSpec {
     enableFork?: boolean;
     shellGate?: "off" | "always" | "classify";
     mcp?: McpServerSpec[];
+    a2a?: A2aServerSpec[];
     skills?: SkillSpec[];
     backgroundScope?: "task" | "session";
     envFacts?: {
@@ -319,6 +333,7 @@ export interface TaskSpec {
         };
         callCapByDeadline?: false;
         gracefulFinalize?: false;
+        brainCallGuardrailMs?: import("../brain/timeout.js").BrainCallGuardrailKnob;
     };
     configOverrides?: ReadonlyArray<import("../config/catalog.js").ConfigOverrideDeclaration>;
     forwardSubagentEvents?: boolean;
@@ -562,7 +577,7 @@ export type TaskEvent = ({
     reason?: string;
 } & TaskEventIdentity) | ({
     type: "steering_injected";
-    source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
+    source: "deadline_nudge" | "finalize" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools";
     preview: string;
 } & TaskEventIdentity) | ({
     type: "diagnostics";
@@ -740,6 +755,7 @@ export interface RunnerDeps {
     builtinWorkflows?: boolean;
     onWorkflowAgentSpawn?: (handle: import("../orchestration/workflow.js").WorkflowAgentHandle) => void;
     maxSuspends?: number;
+    brainCallGuardrailMs?: import("../brain/timeout.js").BrainCallGuardrailKnob;
     now?: () => number;
     memoryBackend?: import("./memory-engine/types.js").MemoryBackend;
     memoryEngineDir?: string;
@@ -772,7 +788,7 @@ export interface RunnerDeps {
     hooks?: import("./hooks.js").Hooks;
     allowImageUrl?: (url: string) => boolean;
     onError?: (err: unknown, context: {
-        phase: "compaction" | "prompt-cache" | "prompt-constitution" | "degraded" | "config" | "memory" | "mcp" | "interrupt-reconcile" | "suggestions" | "rewind" | "hook";
+        phase: "compaction" | "prompt-cache" | "prompt-constitution" | "degraded" | "config" | "memory" | "mcp" | "a2a" | "interrupt-reconcile" | "suggestions" | "rewind" | "hook";
         sessionId: string;
         classification?: string;
     }) => void;

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -19,7 +19,6 @@ export declare function decideSpoolReclaim(args: {
     reclaim: false;
 } | {
     reclaim: true;
-    live: boolean;
     skippedBytes: number;
 };
 export declare function openSpoolPair(base: string): {

package/dist/engine/execution-env/node-execution-env.js

@@ -8,7 +8,7 @@ import { createInterface } from "node:readline";
 import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
 import { killProcessTree, shutdownDebug } from "./kill-tree.js";
 import { scrubSecretEnv } from "../../core/secret-env.js";
-import { RollingTailBuffer, markLiveSpoolRotations, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
+import { RollingTailBuffer, markTruncated, newStreamCursorState, sliceStreamIncrement, } from "../../core/exec-output-tail.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import { SchedulerError } from "../../core/scheduler.js";
 const MAX_TIMER_TIMEOUT_MS = 2_147_000_000;
@@ -216,18 +216,14 @@ const EXEC_SPOOL_HARD_CAP_BYTES = 16 * 1024 * 1024;
 export function decideSpoolReclaim(args) {
     const rotate = args.rotateBytes ?? EXEC_SPOOL_ROTATE_BYTES;
     const hardCap = args.hardCapBytes ?? EXEC_SPOOL_HARD_CAP_BYTES;
-    if (args.cursor < rotate)
+    if (args.writerLive)
         return { reclaim: false };
-    if (args.size === args.cursor) {
-        if (!args.writerLive)
-            return { reclaim: true, live: false, skippedBytes: 0 };
-        if (args.size >= hardCap)
-            return { reclaim: true, live: true, skippedBytes: 0 };
+    if (args.cursor < rotate)
         return { reclaim: false };
-    }
-    if (args.size > args.cursor && args.size >= hardCap) {
-        return { reclaim: true, live: args.writerLive, skippedBytes: args.size - args.cursor };
-    }
+    if (args.size === args.cursor)
+        return { reclaim: true, skippedBytes: 0 };
+    if (args.size > args.cursor && args.size >= hardCap)
+        return { reclaim: true, skippedBytes: args.size - args.cursor };
     return { reclaim: false };
 }
 const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
@@ -330,8 +326,6 @@ export class NodeExecutionEnv {
             const adoptOnTimeoutRef = {};
             const pumpSpoolRef = {};
             const drainSpoolRef = {};
-            const liveRotations = { out: 0, err: 0 };
-            const liveRotationsTotal = () => liveRotations.out + liveRotations.err;
             const writerLive = () => !settled && child !== undefined && child.exitCode === null && child.signalCode === null;
             const armForceSettle = (result) => {
                 if (forceSettleRef.current || settled)
@@ -351,7 +345,7 @@ export class NodeExecutionEnv {
                 drainSpoolRef.current?.();
                 const so = stdoutTail.result();
                 const se = stderrTail.result();
-                return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markLiveSpoolRotations(markTruncated(se.text, se.droppedBytes), liveRotationsTotal()) };
+                return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes) };
             };
             const onAbort = () => {
                 abortKillInFlight = true;
@@ -545,8 +539,6 @@ export class NodeExecutionEnv {
                         return;
                     if (d.skippedBytes > 0)
                         lane.tail.recordSkippedBytes(d.skippedBytes);
-                    if (d.live)
-                        liveRotations[lane.cursor]++;
                     truncateSync(lane.path, 0);
                     spoolCursor[lane.cursor] = 0;
                 }
@@ -583,9 +575,7 @@ export class NodeExecutionEnv {
                 if (settled || !child)
                     return false;
                 pumpSpoolRef.current?.();
-                const shellId = this.adoptRunningChild(child, stdoutTail.result(), stderrTail.result(), execSpoolRef.current !== undefined
-                    ? { spool: execSpoolRef.current, cursors: { out: spoolCursor.out, err: spoolCursor.err }, liveRotations: liveRotationsTotal() }
-                    : undefined);
+                const shellId = this.adoptRunningChild(child, stdoutTail.result(), stderrTail.result(), execSpoolRef.current !== undefined ? { spool: execSpoolRef.current, cursors: { out: spoolCursor.out, err: spoolCursor.err } } : undefined);
                 if (shellId === undefined)
                     return false;
                 if (spoolPumpRef.current)
@@ -678,12 +668,12 @@ export class NodeExecutionEnv {
                     const signum = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
                     settle(ok({
                         stdout: markTruncated(so.text, so.droppedBytes),
-                        stderr: markLiveSpoolRotations(`${markTruncated(se.text, se.droppedBytes)}${se.text.endsWith("\n") || se.text === "" ? "" : "\n"}[process terminated by ${signal}]`, liveRotationsTotal()),
+                        stderr: `${markTruncated(se.text, se.droppedBytes)}${se.text.endsWith("\n") || se.text === "" ? "" : "\n"}[process terminated by ${signal}]`,
                         exitCode: 128 + (signum[signal] ?? 9),
                     }));
                     return;
                 }
-                settle(ok({ stdout: markTruncated(so.text, so.droppedBytes), stderr: markLiveSpoolRotations(markTruncated(se.text, se.droppedBytes), liveRotationsTotal()), exitCode: code ?? 0 }));
+                settle(ok({ stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes), exitCode: code ?? 0 }));
             };
             child.on("close", (code, signal) => settleFromTermination(code, signal));
             child.on("exit", (code, signal) => {
@@ -1051,7 +1041,6 @@ export class NodeExecutionEnv {
             ...(handover !== undefined
                 ? { spool: { outPath: handover.spool.outPath, errPath: handover.spool.errPath, fileCursor: { ...handover.cursors }, ephemeral: true } }
                 : {}),
-            ...(handover !== undefined && (handover.liveRotations ?? 0) > 0 ? { liveRotations: handover.liveRotations } : {}),
         };
         const seedOut = Buffer.from(stdoutSoFar.text, "utf8");
         const seedErr = Buffer.from(stderrSoFar.text, "utf8");
@@ -1241,14 +1230,9 @@ export class NodeExecutionEnv {
         const out = sliceStreamIncrement(entry.stdout, terminal);
         const er = sliceStreamIncrement(entry.stderr, terminal);
         const droppedBeforeCursor = out.droppedBeforeCursor + er.droppedBeforeCursor;
-        let stderrInc = er.inc;
-        if (terminal && (entry.liveRotations ?? 0) > 0 && entry.liveRotationsDisclosed !== true) {
-            entry.liveRotationsDisclosed = true;
-            stderrInc = markLiveSpoolRotations(er.inc, entry.liveRotations ?? 0);
-        }
         return ok({
             stdout: out.inc,
-            stderr: stderrInc,
+            stderr: er.inc,
             status: entry.status,
             ...(entry.exitCode !== undefined ? { exitCode: entry.exitCode } : {}),
             ...(droppedBeforeCursor > 0 ? { truncated: true, bytesDroppedBeforeCursor: droppedBeforeCursor } : {}),
@@ -1320,8 +1304,6 @@ export class NodeExecutionEnv {
                             stream.tail.recordSkippedBytes(d.skippedBytes);
                             stream.totalBytes += d.skippedBytes;
                         }
-                        if (d.live)
-                            entry.liveRotations = (entry.liveRotations ?? 0) + 1;
                         truncateSync(path, 0);
                         spool.fileCursor[lane] = 0;
                     }