@sema-agent/core 2.9.0 → 2.11.0

package/dist/agents/send-message-tool.js

@@ -8,6 +8,9 @@ import { createSubagentResume } from "./subagent.js";
 export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
 let uplinkSeqGlobal = Date.now();
 const UPLINK_RESULT_MAX = 8000;
+function clipCarrierMessage(text) {
+    return text.length > UPLINK_RESULT_MAX ? `${text.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${text.length} chars total]` : text;
+}
 export const SEND_MESSAGE_SUMMARY_MAX = 200;
 export function clipSendMessageSummary(raw) {
     return raw.length > SEND_MESSAGE_SUMMARY_MAX
@@ -89,6 +92,7 @@ export function createSendMessageTool(opts) {
                     isError: true,
                 };
             }
+            const summary = clipSendMessageSummary(summaryArg);
             const senderId = ctx.taskId ?? opts.owner;
             const [parentTaskId, parentSessionId] = ctx.parentTaskId !== undefined ? [ctx.parentTaskId, ctx.parentSessionId] : [opts.parentTaskId, opts.parentSessionId];
             const senderName = ctx.spawnedAgentName ?? opts.senderName;
@@ -102,14 +106,12 @@ export function createSendMessageTool(opts) {
             }
             if (normalizeAgentName(to) === "main") {
                 if (opts.uplink && senderId !== undefined) {
-                    const uplinkSummaryRaw = typeof a.summary === "string" && a.summary.trim() !== "" ? clipSendMessageSummary(a.summary.trim()) : message.slice(0, 80);
-                    const fromLabel = senderName ?? senderId;
                     try {
                         opts.uplink({
                             task_id: senderId,
                             task_type: "background_agent",
                             status: "event",
-                            summary: `message from ${fromLabel}: ${uplinkSummaryRaw}`,
+                            summary: `message from ${senderLabel}: ${summary}`,
                             result: message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message,
                             seq: ++uplinkSeqGlobal,
                         }, { priority: "next" });
@@ -270,11 +272,9 @@ export function createSendMessageTool(opts) {
                             isError: true,
                         };
                     }
-                    const clipped = message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]` : message;
-                    const t3Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? clipSendMessageSummary(a.summary.trim()) : undefined;
-                    const t3From = senderLabel;
+                    const clipped = clipCarrierMessage(message);
                     try {
-                        await opts.mailbox.append(scope, handle, { from: t3From, content: t3Summary !== undefined ? `[${t3Summary}] ${clipped}` : clipped, sentAt: now });
+                        await opts.mailbox.append(scope, handle, { from: senderLabel, content: `[${summary}] ${clipped}`, sentAt: now });
                     }
                     catch (e) {
                         await rollback();
@@ -418,17 +418,13 @@ export function createSendMessageTool(opts) {
             }
             if (row.status === "running" || row.status === "pending") {
                 return await withTargetLane(targetLaneKey(access.scope, targetId), async () => {
-                    const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? clipSendMessageSummary(a.summary.trim()) : undefined;
-                    const fromLabel = senderLabel;
-                    const s2Clipped = message.length > UPLINK_RESULT_MAX
-                        ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]`
-                        : message;
-                    const teammateXml = frameTeammateMessage({ from: fromLabel, ...(s2Summary !== undefined ? { summary: s2Summary } : {}), text: s2Clipped });
+                    const s2Clipped = clipCarrierMessage(message);
+                    const teammateXml = frameTeammateMessage({ from: senderLabel, summary, text: s2Clipped });
                     const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
                         task_id: senderLabel,
                         task_type: "background_agent",
                         status: "event",
-                        summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
+                        summary: `message from ${senderLabel}: ${summary}`,
                         result: teammateXml,
                         seq: ++uplinkSeqGlobal,
                     }, { priority: "next" });
@@ -440,7 +436,7 @@ export function createSendMessageTool(opts) {
                                 : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll.`;
                         return {
                             content: receiptText,
-                            details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, ...(s2Summary !== undefined ? { summary: s2Summary } : {}) },
+                            details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, summary },
                         };
                     }
                     if (delivered.reason === "no_channel") {
@@ -531,16 +527,15 @@ export function createSendMessageTool(opts) {
                     ...(row.rootSessionId !== undefined ? { rowRootSessionId: row.rootSessionId } : {}),
                     ...(opts.notify ? { currentParentNotify: opts.notify } : {}),
                 });
-                const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? clipSendMessageSummary(a.summary.trim()) : undefined;
-                const fromPrefix = parentTaskId !== undefined ? `(message from teammate "${senderName ?? senderId ?? "unknown"}")\n` : "";
+                const fromPrefix = senderIsChild ? `(message from teammate "${senderLabel}")\n` : "";
                 try {
-                    const safeSummary = summary !== undefined ? escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, summary) : undefined;
+                    const safeSummary = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, summary);
                     const safeMessage = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, message);
-                    const marker = await resume(`${fromPrefix}${safeSummary ? `[${safeSummary}] ${safeMessage}` : safeMessage}`);
+                    const marker = await resume(`${fromPrefix}[${safeSummary}] ${safeMessage}`);
                     return {
                         content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
                             `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,
-                        details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, ...(summary !== undefined ? { summary } : {}) },
+                        details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, summary },
                     };
                 }
                 catch (e) {

package/dist/agents/subagent.js

@@ -17,7 +17,7 @@ import { addWorktree } from "../core/git-worktree-env.js";
 import { shellQuote } from "../tools/fs/search.js";
 import { BG_AGENT_REAP_STOP_ERROR } from "../core/task-registry.js";
 import { extractErrorCode } from "../brain/errors.js";
-import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
+import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX, RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getOrCreateSessionRetainLedger, ensureSessionReapHook, createResumePrompt, } from "./retain-ledger.js";
 import { recordRosterSpawn } from "./roster-store.js";
@@ -227,6 +227,21 @@ function errorKindClause(c) {
 const FAILED_SESSION_RETAIN_TTL_MS = 15 * 60 * 1000;
 const PARTIAL_FINDINGS_MAX_CHARS = 1200;
 const BG_NOTIFY_DRAIN_WINDOW_MS = 2_000;
+function createBgActivityBeat(parentToolCallId, emitTick) {
+    let beats = 0;
+    let starts = 0;
+    return (e) => {
+        if (e.type !== "tool_start" && e.type !== "tool_end")
+            return;
+        if (parentToolCallId === undefined || e.parentToolCallId !== parentToolCallId)
+            return;
+        if (e.type === "tool_start")
+            starts += 1;
+        beats += 1;
+        if (beats === 1 || beats % RUNNING_AGENT_OBSERVE_EVERY_BEATS === 0)
+            emitTick(starts);
+    };
+}
 function markerFragment() {
     return uuidv7().replace(/-/g, "").slice(-12);
 }
@@ -351,6 +366,25 @@ export function createSubagentResume(deps) {
                 }
             }
             reviveStartedAt = Date.now();
+            const reviveActivityBeat = createBgActivityBeat(deps.parentToolCallId, (toolStarts) => {
+                if (reviveEmit === undefined)
+                    return;
+                const currentAction = resumeStepRecorder.currentAction();
+                const currentTool = resumeStepRecorder.currentActionStructured();
+                reviveEmit({
+                    kind: "tick",
+                    taskId: deps.taskId,
+                    sessionScoped: deps.sessionScoped === true,
+                    ...(deps.rowAgentType !== undefined ? { agentType: deps.rowAgentType } : {}),
+                    transcriptId: entry.childSessionId,
+                    sessionId: entry.childSessionId,
+                    ...(deps.parentToolCallId !== undefined ? { parentToolCallId: deps.parentToolCallId } : {}),
+                    progressTaskId: entry.childSessionId,
+                    ...(currentAction !== undefined ? { currentAction } : {}),
+                    ...(currentTool !== undefined ? { currentTool } : {}),
+                    usage: { toolUses: toolStarts },
+                });
+            });
             stream = childRunner.runTaskStream(resumeSpec, undefined, {
                 ...entry.internalsSnapshot,
                 ...(true
@@ -362,6 +396,7 @@ export function createSubagentResume(deps) {
                             }
                             catch {
                             }
+                            reviveActivityBeat(e);
                             if (reviveEmit !== undefined && e.type === "task_progress") {
                                 reviveEmit({
                                     kind: "tick",
@@ -1337,8 +1372,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const editedFiles = stepRecorder.editedFiles();
                 return { ...(recentSteps ? { recentSteps } : {}), ...(editedFiles ? { editedFiles } : {}) };
             };
+            const treeScope = reviveClaim?.row.scope ?? ctx.principal ?? opts.background?.scope;
             const childInternals = {
                 ...(inheritedManifestScope ? { inheritedManifestScope } : {}),
+                ...(treeScope !== undefined ? { registryScope: treeScope } : {}),
                 ...(ctx.inheritedGateForChildren ? { inheritedGate: ctx.inheritedGateForChildren() } : {}),
                 ...(childDefaultPersona !== undefined ? { defaultSystemPrompt: childDefaultPersona } : {}),
                 isDelegatedChild: true,
@@ -1597,7 +1634,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                     const shortDesc = `fork: ${(typeof a.description === "string" && a.description.trim() ? a.description.trim() : prompt).slice(0, 180)}`;
                     const bgOwner = sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
-                    const bgScope = ctx.principal ?? bg.scope;
+                    const bgScope = treeScope;
                     let taskId;
                     try {
                         taskId = bg.registry.registerBackgroundAgent({
@@ -1698,6 +1735,23 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const s2ForkNotifyReady = (inject) => {
                         bg.registry.attachAgentNotify(taskId, inject);
                     };
+                    const bgForkActivityBeat = createBgActivityBeat(ctx.toolCallId, (toolStarts) => {
+                        const currentAction = stepRecorder.currentAction();
+                        const currentTool = stepRecorder.currentActionStructured();
+                        sinkEmit({
+                            kind: "tick",
+                            taskId,
+                            sessionScoped: sessionScopedBg === true,
+                            transcriptId: forkedId,
+                            sessionId: forkedId,
+                            parentToolCallId: ctx.toolCallId,
+                            progressTaskId: forkedId,
+                            agentType: spawnAgentType,
+                            ...(currentAction !== undefined ? { currentAction } : {}),
+                            ...(currentTool !== undefined ? { currentTool } : {}),
+                            usage: { toolUses: toolStarts },
+                        });
+                    });
                     const bgForkInternals = bgSink
                         ? {
                             ...forkInternals,
@@ -1708,6 +1762,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 }
                                 catch {
                                 }
+                                bgForkActivityBeat(e);
                                 if (e.type === "task_progress") {
                                     const currentAction = stepRecorder.currentAction();
                                     const currentTool = stepRecorder.currentActionStructured();
@@ -1764,6 +1819,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
                             : undefined;
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
+                            cycle: 0,
                             status: okBg ? "completed" : reapedBg ? "killed" : "failed",
                             ...resultSettleFields(child.result),
                             ...(!okBg ? { error: reapedBg ? (collateralBg ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
@@ -1835,6 +1891,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const errCodeForkReject = killed ? undefined : extractErrorCode(msgFork);
                         const errClassForkReject = killed ? undefined : classifySubagentError({ status: "failed", errorMessage: msgFork });
                         const settledBg = bg.registry.settleBackgroundAgent(taskId, {
+                            cycle: 0,
                             status: killed ? "killed" : "failed",
                             error: killed ? BG_AGENT_REAP_STOP_ERROR : msgFork,
                             ...(errCodeForkReject !== undefined ? { errorCode: errCodeForkReject } : {}),
@@ -1982,7 +2039,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 const shortDesc = reviveRow?.description ?? String(a.description ?? "sub-agent").slice(0, 200);
                 const bgOwner = reviveRow !== undefined ? reviveRow.owner : sessionScopedBg ? ctx.sessionId : ctx.taskId ?? bg.owner;
-                const bgScope = reviveRow !== undefined ? reviveRow.scope : ctx.principal ?? bg.scope;
+                const bgScope = treeScope;
                 let taskId;
                 try {
                     taskId = bg.registry.registerBackgroundAgent(reviveRow !== undefined
@@ -2157,6 +2214,23 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         bg.registry.finalizeParkedResume(taskId);
                     reviveAttachedResolve?.();
                 };
+                const bgActivityBeat = createBgActivityBeat(ctx.toolCallId, (toolStarts) => {
+                    const currentAction = stepRecorder.currentAction();
+                    const currentTool = stepRecorder.currentActionStructured();
+                    sinkEmit({
+                        kind: "tick",
+                        taskId,
+                        sessionScoped: sessionScopedBg === true,
+                        transcriptId: bgChildSessionId,
+                        sessionId: bgChildSessionId,
+                        parentToolCallId: ctx.toolCallId,
+                        progressTaskId: bgChildSessionId,
+                        agentType: spawnAgentType,
+                        ...(currentAction !== undefined ? { currentAction } : {}),
+                        ...(currentTool !== undefined ? { currentTool } : {}),
+                        usage: { toolUses: toolStarts },
+                    });
+                });
                 const bgInternals = bgSink
                     ? {
                         ...childInternals,
@@ -2167,6 +2241,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             }
                             catch {
                             }
+                            bgActivityBeat(e);
                             if (e.type === "task_progress") {
                                 const currentAction = stepRecorder.currentAction();
                                 const currentTool = stepRecorder.currentActionStructured();
@@ -2400,6 +2475,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ? classifySubagentError({ status: "failed", ...(child.errorCode !== undefined ? { errorCode: child.errorCode } : {}), ...(child.errorMessage !== undefined ? { errorMessage: child.errorMessage } : {}) })
                         : undefined;
                     const settled = bg.registry.settleBackgroundAgent(taskId, {
+                        cycle: 0,
                         status: ok ? "completed" : reaped ? "killed" : "failed",
                         seq: seqAtSettle ?? 1,
                         ...resultSettleFields(child.result),
@@ -2496,6 +2572,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const errCodeBgReject = killed ? undefined : extractErrorCode(msg);
                     const errClassBgReject = killed ? undefined : classifySubagentError({ status: "failed", errorMessage: msg });
                     const settled = bg.registry.settleBackgroundAgent(taskId, {
+                        cycle: 0,
                         status: killed ? "killed" : "failed",
                         error: msg,
                         seq: seqAtSettle ?? 1,

package/dist/config/defaults.d.ts

@@ -4,3 +4,4 @@ export declare const SESSION_BG_DEFAULT_TIMEOUT_SEC: number;
 export declare const RETAIN_DEFAULT_TTL_MS: number;
 export declare const RETAIN_DEFAULT_MAX = 16;
 export declare const SESSION_DEFAULT_TTL_DAYS = 7;
+export declare const RUNNING_AGENT_OBSERVE_EVERY_BEATS = 4;

package/dist/config/defaults.js

@@ -4,3 +4,4 @@ export const SESSION_BG_DEFAULT_TIMEOUT_SEC = 30 * 60;
 export const RETAIN_DEFAULT_TTL_MS = 30 * 60 * 1000;
 export const RETAIN_DEFAULT_MAX = 16;
 export const SESSION_DEFAULT_TTL_DAYS = 7;
+export const RUNNING_AGENT_OBSERVE_EVERY_BEATS = 4;

package/dist/core/consolidate-scope.js

@@ -23,8 +23,10 @@ export async function consolidateScope(scope, deps, opts = {}) {
             "(getConsolidationCursor/setConsolidationCursor) — skipped (no-op), NOT degraded to a full re-consolidation"));
         return undefined;
     }
-    if (!supportsConsolidation(store) || typeof store.listStructuredNotes !== "function") {
-        onWarn?.(new Error("consolidateScope: store is not id-addressable / has no manifest — skipped (no-op)"));
+    if (!supportsConsolidation(store) ||
+        typeof store.listStructuredNotes !== "function" ||
+        typeof store.getByIds !== "function") {
+        onWarn?.(new Error("consolidateScope: store is not id-addressable / has no manifest read pair — skipped (no-op)"));
         return undefined;
     }
     const release = deps.acquire ? await deps.acquire(scope) : () => { };

package/dist/core/context-edit.js

@@ -76,29 +76,28 @@ export function clearStaleToolResults(messages, opts) {
     }
     const keep = opts.keepRecentToolResults ?? 3;
     const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
-    const toolResultIdx = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName ?? "") ? [i] : []);
-    const clearable = toolResultIdx.slice(0, Math.max(0, toolResultIdx.length - keep));
+    const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
+    const clearable = toolResultCandidates.slice(0, Math.max(0, toolResultCandidates.length - keep));
     if (clearable.length === 0) {
         return messages;
     }
     const out = messages.slice();
     let current = total;
-    for (const idx of clearable) {
+    for (const { idx, target } of clearable) {
         if (current <= opts.budgetTokens) {
             break;
         }
-        const before = estimateTokens(out[idx], cpt);
-        const msg = out[idx];
-        const rawContent = Array.isArray(msg.content) ? msg.content : [];
+        const before = estimateTokens(target, cpt);
+        const rawContent = Array.isArray(target.content) ? target.content : [];
         let ref;
         if (opts.offload) {
             const fullText = rawContent
                 .filter((c) => c?.type === "text" && typeof c.text === "string")
                 .map((c) => c.text)
                 .join("\n");
-            if (msg.toolCallId && fullText.trim().length > 0) {
+            if (target.toolCallId && fullText.trim().length > 0) {
                 try {
-                    ref = refNote(opts.offload.persist(msg.toolCallId, fullText));
+                    ref = refNote(opts.offload.persist(target.toolCallId, fullText));
                 }
                 catch {
                     ref = undefined;
@@ -107,10 +106,7 @@ export function clearStaleToolResults(messages, opts) {
         }
         const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
         const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined]);
-        const cleared = {
-            ...out[idx],
-            content: [{ type: "text", text: marker }],
-        };
+        const cleared = { ...target, content: [{ type: "text", text: marker }] };
         out[idx] = cleared;
         current -= idx > anchorIdx ? before - estimateTokens(cleared, cpt) : 0;
     }

package/dist/core/memory.d.ts

@@ -47,8 +47,10 @@ export interface MemoryNoteHeader {
 export interface MemoryNoteRecord extends MemoryNoteHeader {
     text: string;
 }
-export declare function supportsConsolidation(store: MemoryStore): boolean;
-export declare function supportsPeriodicConsolidation(store: MemoryStore): boolean;
+export type ConsolidationCapableStore = MemoryStore & Required<Pick<MemoryStore, "searchScored" | "update" | "delete">>;
+export declare function supportsConsolidation(store: MemoryStore): store is ConsolidationCapableStore;
+export type PeriodicConsolidationCapableStore = MemoryStore & Required<Pick<MemoryStore, "getConsolidationCursor" | "setConsolidationCursor">>;
+export declare function supportsPeriodicConsolidation(store: MemoryStore): store is PeriodicConsolidationCapableStore;
 export declare const CALLER_AUTHORED_TYPES: ReadonlySet<string>;
 export declare const DEFAULT_CALLER_AUTHORED_TYPE: MemoryNoteType;
 export type UtilityGate = (stats: unknown) => boolean;

package/dist/core/message-utils.d.ts

@@ -1,3 +1,4 @@
 import type { AgentMessage } from "../internal/harness-types.js";
+import type { ToolResultMessage } from "../internal/llm.js";
 export declare function messageRole(m: AgentMessage): string | undefined;
-export declare function isToolResult(m: AgentMessage): boolean;
+export declare function isToolResult(m: AgentMessage): m is ToolResultMessage;

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

@@ -69,6 +69,7 @@ export interface ResultFlags {
     threw: unknown;
     model?: string;
     unpricedSpend?: boolean;
+    rewindNotes?: TaskResult["rewindNotes"];
     abortedForTimeout: boolean;
     abortedForTurns: boolean;
     abortedLive?: boolean;

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

@@ -143,5 +143,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     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 };
+    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), stats: publicStats };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -17,7 +17,7 @@ import { type CwdRef } from "../../tools/fs/index.js";
 import type { Runner } from "./runtask.js";
 import { type CheckpointGate, type CheckpointState, type CheckpointToken, type ResourceLedger, type ResourceLimitReason } from "../checkpoint-store.js";
 import type { AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
-import type { RunnerDeps, TaskEvent, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
+import type { RunnerDeps, TaskEvent, TaskResult, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
 import type { RepairBundle } from "../../agents/repair-loop.js";
 export declare const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
 export declare function checkpointScopeOf(spec: {
@@ -48,6 +48,7 @@ export interface Prepared {
         tasks: number;
         costMicroUsd: number;
     };
+    rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
     cwdRef?: CwdRef;
     worktreeSessionRef?: {
         current?: {
@@ -307,6 +308,7 @@ export interface RunInternals {
     parentTaskId?: string;
     parentSessionId?: string;
     rootSessionId?: string;
+    registryScope?: string;
     parentCenterArtifactDigest?: string;
     parentCenterSourceRevision?: string;
     promptProfile?: "simple" | "classic";

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

@@ -409,7 +409,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }));
         }
     }
-    const taskScope = spec.principal ?? "default";
+    const taskScope = internals?.registryScope ?? spec.principal ?? "default";
     defaultTaskRegistry.maybeGc();
     const forgetOnThrow = () => forgetQuietly(sessions, sessionId);
     const extraBodyCollisions = reservedCollisions(model.extraBody, reservedFor(model.api));
@@ -616,8 +616,42 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             catch {
             }
         }
-        let rewindTarget = spec.resumeAt !== undefined ? (spec.rewindFiles ? spec.resumeAt : undefined) : spec.rewindFilesTo;
+        const rewindNotes = [];
+        const rewindCaptureRequested = spec.rewindFiles === true;
+        if (spec.resumeAt !== undefined && spec.rewindFilesTo !== undefined) {
+            const e = new Error(`rewind-files: resumeAt ("${spec.resumeAt}") and rewindFilesTo ("${spec.rewindFilesTo}") were both set — resumeAt already anchors the file restore when rewindFiles is true, so a separate rewindFilesTo target is a conflicting request. Drop one of the two.`);
+            e.code = "rewind.conflicting_targets";
+            throw e;
+        }
+        let rewindTarget = spec.resumeAt !== undefined ? (rewindCaptureRequested ? spec.resumeAt : undefined) : spec.rewindFilesTo;
         const rewindBefore = rewindTarget !== undefined && spec.resumeAt !== undefined && spec.resumeAtMode === "before";
+        if (spec.resumeAt !== undefined && !rewindCaptureRequested) {
+            rewindNotes.push({
+                code: "conversation_only",
+                message: `the conversation was branched at entry "${spec.resumeAt}" but the working tree was NOT rewound — this task set resumeAt without rewindFiles, so files remain at their current state`,
+            });
+        }
+        if (!deps.fileSnapshotStore) {
+            if (rewindTarget !== undefined) {
+                const e = new Error(`rewind-files: restoring the working tree to entry "${rewindTarget}" requires a snapshot backend, but this deployment wired no RunnerDeps.fileSnapshotStore — no snapshot was ever captured, so the files were NOT rewound`);
+                e.code = "rewind.store_unconfigured";
+                throw e;
+            }
+            if (rewindCaptureRequested) {
+                rewindNotes.push({
+                    code: "snapshot_store_unconfigured",
+                    message: "rewindFiles was requested but no RunnerDeps.fileSnapshotStore is wired — no working-tree snapshot was captured for this turn, so it cannot be rewound to later",
+                });
+            }
+        }
+        else if (!handsEnabled) {
+            if (rewindTarget !== undefined || rewindCaptureRequested) {
+                rewindNotes.push({
+                    code: "files_env_unsupported",
+                    message: "the file side of rewind was inert: this deployment mounts no filesystem-capable ExecutionEnv, so no working-tree snapshot was captured or restored",
+                });
+            }
+        }
         if (rewindTarget !== undefined && deps.fileSnapshotStore && handsEnabled) {
             if (rewindBefore) {
                 let anchor;
@@ -642,18 +676,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             const restoreSignal = spec.signal ? AbortSignal.any([abortController.signal, spec.signal]) : abortController.signal;
             const restored = await deps.fileSnapshotStore.restore(sessionId, rewindTarget, executionEnv, restoreRoot, restoreSignal);
             if (!restored.ok) {
-                if (restored.error.code === "not_found" && rewindBefore) {
-                    const e = new Error(`rewind-files: the resolved "before" snapshot anchor "${rewindTarget}" disappeared before restore — files were NOT rewound`);
+                if (restored.error.code === "not_found") {
+                    const e = new Error(rewindBefore
+                        ? `rewind-files: the resolved "before" snapshot anchor "${rewindTarget}" disappeared before restore — files were NOT rewound`
+                        : `rewind-files: no file snapshot exists for entry "${rewindTarget}" on session "${sessionId}" — the working tree was NOT rewound (only a COMPLETED turn that ran with rewindFiles is snapshotted, and snapshots are keyed by that turn's END leaf; earlier turns that ran without rewindFiles, mid-turn entries, and reaped snapshots have none)`);
                     e.code = "rewind_snapshot.unresolvable";
                     throw e;
                 }
-                if (restored.error.code === "not_found") {
-                    try {
-                        deps.onError?.(new Error(`rewind-files: no snapshot for entry "${rewindTarget}" — files left unchanged`), { phase: "rewind", sessionId });
-                    }
-                    catch {
-                    }
-                }
                 else {
                     const e = new Error(`rewind-files restore failed (${restored.error.code}): ${restored.error.message}`);
                     e.code = "rewind.restore_failed";
@@ -1809,15 +1838,6 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
         const activeTools = new Set();
         const fpRef = {};
-        if (rebuildHarnessToolsRef.current === undefined) {
-            rebuildHarnessToolsRef.current = async () => {
-                const list = [...tools];
-                await harnessRef.current.setTools(list, list.map((t) => t.name));
-                if (fpRef.current)
-                    fpRef.current.tools = toolsToFingerprintInputs(list);
-                turnSnapshotRef.current?.refreshTools(toolsToFingerprintInputs(list));
-            };
-        }
         const turnSnapshotRef = {};
         let harnessTools = tools;
         const failedMcpServers = mcp.statuses
@@ -1852,7 +1872,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(executionMode !== undefined ? { executionMode } : {}),
                     activate: async () => {
                         if (activeTools.has(name))
-                            return;
+                            return undefined;
                         activeTools.add(name);
                         try {
                             await rematerialize(activeTools);
@@ -1861,6 +1881,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             activeTools.delete(name);
                             throw e;
                         }
+                        return listingRideRef.current?.([name]);
                     },
                 };
             };
@@ -1883,7 +1904,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (deferred.has(n))
                         activeTools.add(n);
             }
-            offloadReachableToolsRef.current = () => {
+            const callableToolNames = () => {
                 const s = new Set(tools.map((t) => t.name));
                 for (const n of deferred)
                     if (!activeTools.has(n))
@@ -1891,6 +1912,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 s.add(TOOL_SEARCH_NAME);
                 return s;
             };
+            offloadReachableToolsRef.current = callableToolNames;
             let toolSearch;
             const buildToolList = (active) => {
                 const list = tools.map((t) => (deferred.has(t.name) && !active.has(t.name) ? placeholders.get(t.name) : t));
@@ -1932,11 +1954,20 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 active: activeTools,
                 rematerialize,
                 listingRide: (newly) => listingRideRef.current?.(newly),
-                mountedNames: () => new Set(buildToolList(activeTools).map((t) => t.name).filter((n) => !registry.has(n) || activeTools.has(n))),
+                mountedNames: callableToolNames,
                 directCallEnabled: spec.deferSelfResolve !== false,
             });
             harnessTools = buildToolList(activeTools);
         }
+        else {
+            rebuildHarnessToolsRef.current = async () => {
+                const list = [...tools];
+                await harnessRef.current.setTools(list, list.map((t) => t.name));
+                if (fpRef.current)
+                    fpRef.current.tools = toolsToFingerprintInputs(list);
+                turnSnapshotRef.current?.refreshTools(toolsToFingerprintInputs(list));
+            };
+        }
         if (spec.agents !== undefined && spec.agents.length > 0) {
             const known = new Set(tools.flatMap((t) => [canonicalToolName(t.name), ...(t.aliases ?? []).map((a) => canonicalToolName(a))]));
             for (const def of spec.agents) {
@@ -3357,7 +3388,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -2764,6 +2764,7 @@ export class Runner {
                 threw,
                 model: prepared.model.id,
                 unpricedSpend: rs.telemetry.unpricedSpend,
+                rewindNotes: prepared.rewindNotes,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,
                 abortedLive,
@@ -3045,10 +3046,19 @@ export class Runner {
             if (!leafId)
                 return;
             const root = prepared.taskRootPath;
-            const refusedAt = this.snapshotTooLargeRoots.get(root);
-            if (refusedAt !== undefined) {
-                if (Date.now() - refusedAt < SNAPSHOT_TOO_LARGE_TTL_MS)
+            const refusal = this.snapshotTooLargeRoots.get(root);
+            if (refusal !== undefined) {
+                if (Date.now() - refusal.refusedAt < SNAPSHOT_TOO_LARGE_TTL_MS) {
+                    if (!refusal.skipAnnounced) {
+                        refusal.skipAnnounced = true;
+                        try {
+                            this.deps.onError?.(new Error(`rewind-files snapshot skipped for this working-tree root: a too_large refusal is still inside its ${SNAPSHOT_TOO_LARGE_TTL_MS / 60_000}-minute cooldown (re-probed at ${new Date(refusal.refusedAt + SNAPSHOT_TOO_LARGE_TTL_MS).toISOString()}) — turns completed during the cooldown capture no snapshot and cannot be rewound to. Announced once per cooldown window.`), { phase: "rewind", sessionId: prepared.sessionId, classification: "too_large" });
+                        }
+                        catch {
+                        }
+                    }
                     return;
+                }
                 this.snapshotTooLargeRoots.delete(root);
             }
             const ac = new AbortController();
@@ -3071,11 +3081,14 @@ export class Runner {
             }
             if (!r.ok) {
                 const tooLarge = r.error.code === "too_large";
+                const refusedAt = Date.now();
                 if (tooLarge)
-                    this.snapshotTooLargeRoots.set(root, Date.now());
+                    this.snapshotTooLargeRoots.set(root, { refusedAt, skipAnnounced: false });
                 try {
                     this.deps.onError?.(new Error(`rewind-files snapshot failed (${r.error.code}): ${r.error.message}` +
-                        (tooLarge ? " — skipping further snapshots for this root (this process); raise the store's snapshotBounds or shrink the tree to re-enable rewind" : "")), { phase: "rewind", sessionId: prepared.sessionId, ...(tooLarge ? { classification: "too_large" } : {}) });
+                        (tooLarge
+                            ? ` — skipping further snapshots for this root (this process) during a ${SNAPSHOT_TOO_LARGE_TTL_MS / 60_000}-minute cooldown, until ${new Date(refusedAt + SNAPSHOT_TOO_LARGE_TTL_MS).toISOString()}, when the tree is re-probed automatically. Raise the store's snapshotBounds to accept a tree this size; shrinking the tree also re-enables rewind, but only at that re-probe — not immediately`
+                            : "")), { phase: "rewind", sessionId: prepared.sessionId, ...(tooLarge ? { classification: "too_large" } : {}) });
                 }
                 catch {
                 }

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

@@ -31,7 +31,7 @@ export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, too
 export interface PlaceholderDirectCall {
     resolveReal: () => PlaceholderDirectTarget | undefined;
     executionMode?: ToolExecutionMode;
-    activate: () => Promise<void>;
+    activate: () => Promise<string | undefined>;
 }
 export interface PlaceholderDirectTarget {
     parameters: TSchema;

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

@@ -79,8 +79,11 @@ export function createPlaceholderTool(info, direct) {
             execute: async (toolCallId, params, signal, onUpdate) => {
                 const real = direct.resolveReal();
                 if (real !== undefined && Value.Check(real.parameters, params)) {
-                    await direct.activate();
-                    return real.invoke(toolCallId, params, signal, onUpdate);
+                    const ride = await direct.activate();
+                    const result = await real.invoke(toolCallId, params, signal, onUpdate);
+                    if (ride === undefined || ride === "")
+                        return result;
+                    return { ...result, content: [...result.content, { type: "text", text: ride }] };
                 }
                 return teachingRejection();
             },
@@ -168,15 +171,27 @@ export function resolveToolSearch(args, registry) {
 }
 export function extractDiscoveredToolNames(messages, registry) {
     const names = new Set();
+    const pendingDirect = new Map();
     for (const m of messages) {
+        if (m.role === "toolResult") {
+            const name = pendingDirect.get(m.toolCallId);
+            if (name !== undefined && m.isError !== true)
+                names.add(name);
+            continue;
+        }
         if (m.role !== "assistant")
             continue;
         for (const part of m.content) {
-            if (part.type === "toolCall" && part.name === TOOL_SEARCH_NAME) {
+            if (part.type !== "toolCall")
+                continue;
+            if (part.name === TOOL_SEARCH_NAME) {
                 for (const n of resolveToolSearch(part.arguments, registry)) {
                     names.add(n);
                 }
             }
+            else if (registry.has(part.name)) {
+                pendingDirect.set(part.id, part.name);
+            }
         }
     }
     return [...names];

package/dist/core/session-store.d.ts

@@ -12,6 +12,7 @@ export interface TtlSessionStoreOptions {
 export declare class TtlSessionStore implements SessionStore {
     private repo;
     private entries;
+    private owners;
     private pending;
     private pinned;
     private defaultTtlMs;
@@ -31,6 +32,8 @@ export declare class TtlSessionStore implements SessionStore {
     forget(sessionId: string): void;
     pin(sessionId: string): void;
     unpin(sessionId: string): void;
+    ownerOf(sessionId: string): Promise<string | null | undefined>;
+    register(sessionId: string, owner: string | null): Promise<void>;
     sweep(now?: number): void;
     get size(): number;
     dispose(): void;

package/dist/core/session-store.js

@@ -6,6 +6,7 @@ export { SESSION_DEFAULT_TTL_DAYS };
 export class TtlSessionStore {
     repo;
     entries = new Map();
+    owners = new Map();
     pending = new Map();
     pinned = new Set();
     defaultTtlMs;
@@ -132,6 +133,7 @@ export class TtlSessionStore {
         this.entries.delete(sessionId);
         if (this.evictPolicy === "delete") {
             await this.repo.delete(await e.session.getMetadata());
+            this.owners.delete(sessionId);
         }
     }
     forget(sessionId) {
@@ -143,6 +145,13 @@ export class TtlSessionStore {
     unpin(sessionId) {
         this.pinned.delete(sessionId);
     }
+    async ownerOf(sessionId) {
+        return this.owners.has(sessionId) ? this.owners.get(sessionId) : undefined;
+    }
+    async register(sessionId, owner) {
+        if (!this.owners.has(sessionId))
+            this.owners.set(sessionId, owner);
+    }
     sweep(now = Date.now()) {
         for (const [id, e] of this.entries) {
             if (this.pinned.has(id)) {
@@ -152,6 +161,7 @@ export class TtlSessionStore {
                 this.entries.delete(id);
                 if (this.evictPolicy === "delete") {
                     void this.repo.delete({ id, createdAt: "" });
+                    this.owners.delete(id);
                 }
             }
         }

package/dist/core/session.d.ts

@@ -31,6 +31,8 @@ export interface SessionStore {
     noteTaskRun?(sessionId: string, taskId: string): void | Promise<void>;
     list?(): Promise<SessionStoreSummary[]>;
     fork?(sourceId: string, owner?: string | null): Promise<string | null>;
+    ownerOf?(sessionId: string): Promise<string | null | undefined>;
+    register?(sessionId: string, owner: string | null): Promise<void>;
     readonly size: number;
     dispose(): void | Promise<void>;
 }

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

@@ -652,6 +652,9 @@ export function settleBackgroundAgentLane(core, id, outcome) {
     const handle = core.handles.get(id);
     if (!handle || handle.type !== "background_agent")
         return undefined;
+    if (outcome.cycle === undefined && (handle.reviveCycle ?? 0) !== 0) {
+        throw new Error(`settleBackgroundAgent("${id}"): the row has been revived (cycle ${handle.reviveCycle}) — pass the cycle this settle speaks for, or use settleRevivedAgent`);
+    }
     if ((outcome.cycle ?? 0) !== (handle.reviveCycle ?? 0))
         return undefined;
     if (handle.status !== "running") {

package/dist/core/tool-result-budget.js

@@ -21,6 +21,8 @@ function isOffloadedPreview(content) {
     return first?.type === "text" && typeof first.text === "string" && first.text.startsWith(PERSISTED_OUTPUT_PREFIX);
 }
 function replaceTextBlock(m, text) {
+    if (!isToolResult(m))
+        return m;
     const images = m.content.filter((b) => b.type !== "text");
     return { ...m, content: [{ type: "text", text }, ...images] };
 }

package/dist/core/types.d.ts

@@ -390,6 +390,10 @@ export interface TaskResult {
         atTurn: number;
     };
     structuredOutput?: unknown;
+    rewindNotes?: Array<{
+        code: "conversation_only" | "files_env_unsupported" | "snapshot_store_unconfigured";
+        message: string;
+    }>;
     stats: {
         turns: number;
         tokens: number;

package/dist/engine/session/session.js

@@ -34,8 +34,9 @@ export function buildSessionContext(pathEntries, opts) {
         }
     }
     const messages = [];
+    const isAssistantMessage = (m) => m.role === "assistant";
     const stripAssistantUsage = (message) => {
-        if (message.role !== "assistant") {
+        if (!isAssistantMessage(message)) {
             return message;
         }
         return {

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { createSkillsFromDirectory, type SkillsDirectoryOptions, type SkillsDire
 export { REPORT_FINDINGS_TOOL_NAME, type ReportedFinding } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
 export type { WorkerErrorClass } from "./core/tool-errors.js";
-export { createWebFetchTool, webFetchToolSpec, htmlToText, type WebFetchConfig, createWebSearchTool, type WebSearchConfig, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
+export { createWebFetchTool, webFetchToolSpec, htmlToText, type WebFetchConfig, createWebSearchTool, type WebSearchConfig, createSearxngSearchBackend, probeSearchBackend, type SearxngBackendOptions, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
 export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata, type TaskListItem, type TaskListStore } from "./tools/task-list.js";
 export { assembleCodeTools, type CodeToolsConfig, CODE_ROLE } from "./scenarios/full-body.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { SKILL_TOOL_NAME } from "./core/runner/synthetic-tools.js";
 export { createSkillsFromDirectory, } from "./core/skills-directory.js";
 export { REPORT_FINDINGS_TOOL_NAME } from "./core/runner/synthetic-tools.js";
 export { formatToolError, formatZodValidationError, formatValidationPath, truncateError, errorClassOf } from "./core/tool-errors.js";
-export { createWebFetchTool, webFetchToolSpec, htmlToText, createWebSearchTool, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
+export { createWebFetchTool, webFetchToolSpec, htmlToText, createWebSearchTool, createSearxngSearchBackend, probeSearchBackend, createWebFetchSummarizer, WEBFETCH_SUMMARY_MAX_CONTENT, WEBFETCH_SUMMARY_GUIDELINES, } from "./tools/web.js";
 export { createTodoWriteTool } from "./tools/todo.js";
 export { createTaskListTools, createMemoryTaskListStore, assertJsonMetadata } from "./tools/task-list.js";
 export { assembleCodeTools, CODE_ROLE } from "./scenarios/full-body.js";

package/dist/orchestration/workflow.js

@@ -9,6 +9,7 @@ import { combinePolicies, createAllowDenyPolicy } from "../core/tool-policy.js";
 import { callKeyOrdinal, oversizeJournalResult, journalOversizeTombstone, JOURNAL_OVERSIZE_ERROR_CODE, MAX_JOURNAL_RESULT_BYTES } from "../core/workflow-journal-store.js";
 import { isWorkflowRunActive, closeWorkflowChannel, markWorkflowActive, publishWorkflowEvent } from "./workflow-observe.js";
 import { isDurablePause, mapNestedSuspend } from "../agents/suspend-guard.js";
+import { RUNNING_AGENT_OBSERVE_EVERY_BEATS } from "../config/defaults.js";
 import { boundInputHashOf } from "../core/canonical-json.js";
 import { boundedRedactedSummary } from "../core/untrusted-egress.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
@@ -20,7 +21,6 @@ const MAX_TRANSCRIPT_CHARS = 4000;
 const WORKFLOW_RESULT_MAX = 4000;
 const WORKFLOW_RESULT_FULL_MAX = 200_000;
 const MAX_ACTIVITY = 30;
-const RUNNING_AGENT_PERSIST_EVERY_BEATS = 4;
 function workflowModelLabel(spec) {
     const model = spec.model;
     if (model === undefined)
@@ -453,16 +453,17 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
     };
     const waIdOf = (callKey) => `wa${createHash("sha256").update(`${runId}:${callKey}`).digest("hex").slice(0, 16)}`;
     const bceLive = new Map();
-    const bceSpawn = (callKey, label, agentType, replayed) => {
+    const bceSpawn = (callKey, label, agentType, replayed, sessionId) => {
         if (!bceSink)
             return;
         const id = waIdOf(callKey);
-        bceLive.set(id, { callKey, label, ...(agentType !== undefined ? { agentType } : {}) });
+        bceLive.set(id, { callKey, label, ...(agentType !== undefined ? { agentType } : {}), ...(sessionId !== undefined ? { sessionId } : {}) });
         bceEmit({
             kind: "spawn",
             taskId: id,
             sessionScoped: false,
             owner: runId,
+            ...(sessionId !== undefined ? { sessionId, transcriptId: sessionId } : {}),
             ...(scope !== undefined ? { scope } : {}),
             description: replayed ? `${label} (replayed)` : label,
             agentType: agentType ?? "workflow-agent",
@@ -474,6 +475,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             startedAt: Date.now(),
         });
     };
+    const bceBindSession = (callKey, sessionId) => {
+        const row = bceLive.get(waIdOf(callKey));
+        if (row !== undefined)
+            row.sessionId = sessionId;
+    };
     const bceTick = (callKey, e) => {
         if (!bceSink)
             return;
@@ -489,6 +495,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             workflowRunId: runId,
             ...(scope !== undefined ? { scope } : {}),
             ...(row.agentType !== undefined ? { agentType: row.agentType } : { agentType: "workflow-agent" }),
+            ...(row.sessionId !== undefined ? { sessionId: row.sessionId, transcriptId: row.sessionId } : {}),
             name: e.name ?? row.label,
             progressTaskId: e.taskId,
             ...(e.parentTaskId !== undefined ? { progressParentTaskId: e.parentTaskId } : {}),
@@ -635,7 +642,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 rec.toolCalls = (rec.toolCalls ?? 0) + 1;
             rec.activity = tail;
             beatCount += 1;
-            if (beatCount === 1 || beatCount % RUNNING_AGENT_PERSIST_EVERY_BEATS === 0) {
+            if (beatCount === 1 || beatCount % RUNNING_AGENT_OBSERVE_EVERY_BEATS === 0) {
                 void persist("update");
             }
         };
@@ -768,7 +775,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         agentPhaseOf.set(replayRec, phaseInstance);
                     emit({ type: "agent_start", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), callKey, prompt, ...(model !== undefined ? { model } : {}), replayed: true, ts: at });
                     emit({ type: "agent_end", runId, label, phase, ...(groupId !== undefined ? { groupId } : {}), status: replayRec.status, output: cachedOutput, ...(rs.toolCalls !== undefined ? { toolCalls: rs.toolCalls } : {}), replayed: true, ts: at });
-                    bceSpawn(callKey, label, agentOpts.agentType, true);
+                    bceSpawn(callKey, label, agentOpts.agentType, true, r.sessionId || undefined);
                     bceTerminal(callKey, replayRec.status === "completed" ? "completed" : "failed", cachedOutput, r.sessionId || undefined, replayRec.stats);
                     accumulateStats(r, false);
                     void persist("update");
@@ -810,7 +817,8 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 if (finalized)
                     throw new Error("workflow run already finalized — ctx.agent cannot spawn after the run ended");
                 rec.startedAt = now();
-                bceSpawn(callKey, label, agentOpts.agentType, false);
+                const bornChildSessionId = resolveChildSessionIdAtSpawn(spec);
+                bceSpawn(callKey, label, agentOpts.agentType, false, bornChildSessionId);
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
                 const framedSpec = withWorkflowChildPersona(typedSpec, agentOpts.schema ?? typedSpec.outputSchema);
@@ -852,10 +860,11 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     const onCallerAbort = () => attemptCtl.abort(new Error("workflow aborted"));
                     effectiveSignal?.addEventListener("abort", onCallerAbort, { once: true });
                     armWatchdog();
-                    const attemptSessionId = resolveChildSessionIdAtSpawn(runSpec);
+                    const attemptSessionId = attempts === 1 ? bornChildSessionId : resolveChildSessionIdAtSpawn(runSpec);
                     const attemptSpec = attemptSessionId !== undefined ? { ...runSpec, sessionId: attemptSessionId, signal: attemptCtl.signal } : { ...runSpec, signal: attemptCtl.signal };
                     if (attemptSessionId !== undefined && !finalized) {
                         rec.sessionId = attemptSessionId;
+                        bceBindSession(callKey, attemptSessionId);
                         void persist("update");
                     }
                     const attemptInternals = {
@@ -1143,9 +1152,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 throw new Error(finalized ? "workflow run already finalized — ctx.agentStream cannot spawn after the run ended" : "workflow aborted");
             }
             rec.startedAt = now();
-            bceSpawn(callKey, label, agentOpts.agentType, false);
+            const childSessionId = resolveChildSessionIdAtSpawn(spec);
+            bceSpawn(callKey, label, agentOpts.agentType, false, childSessionId);
             let stream;
-            let childSessionId;
             try {
                 const typedSpec0 = applyWorkflowAgentType(spec, agentOpts.agentType, agentRegistry);
                 const typedSpec = typedSpec0.model === undefined && inheritedModelSnap !== undefined ? { ...typedSpec0, model: inheritedModelSnap } : typedSpec0;
@@ -1154,7 +1163,6 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const baseRunSpec = agentOpts.schema
                     ? { ...framedSpec, ...authInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
                     : { ...framedSpec, ...authInherit, signal: effectiveSignal };
-                childSessionId = resolveChildSessionIdAtSpawn(baseRunSpec);
                 const runSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
                 const enrichedForwardS = opts.onForwardEvent !== undefined
                     ? (e) => {

package/dist/tools/fs/fs-write.js

@@ -152,6 +152,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                 return errorResult(`Error (Edit): "${path}" has a truncated UTF-16 body; repair/convert it with bash first.`);
             const original = decoded.text;
             const entry = state.get(r.key);
+            const readWasTruncated = entry?.truncated === true;
             const stale = checkStale(entry, sha256(original));
             if (stale)
                 return errorResult(violationText("Edit", stale));
@@ -180,7 +181,7 @@ export function createEditFileTool(env, state, rootCanonical, cwdRef, additional
                         oldS = resolvedEsc;
                     }
                 }
-                const match = checkEditMatch(working, oldS, e.replace_all === true, entry.truncated);
+                const match = checkEditMatch(working, oldS, e.replace_all === true, readWasTruncated);
                 if (match) {
                     const escNote = match.code === "ambiguous_edit" && escapeMatchWasAttempted(e.old_string) && !working.includes(oldS) ? ESCAPE_MATCH_MISS_NOTE : "";
                     return errorResult(batch ? `Error (Edit): ${where}${match.message}${escNote} (no changes written — the batch is atomic).` : `${violationText("Edit", match)}${escNote}`);

package/dist/tools/fs/safety.d.ts

@@ -58,7 +58,7 @@ export declare const OVERSIZE_READ_ESCAPE_HINT = "(This file is over the Read to
 export declare const PARTIAL_VIEW_READ_ESCAPE_HINT = "(Your last Read of this file returned only a PARTIAL view \u2014 the output token cap paginated it, so a default Read will keep returning the same page. Re-read it with explicit offset/limit (start from the page marker's next-page hint) until you have seen the part you are about to change; an explicit slice that fits satisfies the read-first rule. Or inspect/transform it with bash (e.g. `sed -n`, `grep`) instead.)";
 export declare const WRITE_ENCODING_DEADLOCK_ESCAPE_HINT = "(If the Read tool refuses this file (binary/unknown encoding), overwrite or convert it with bash instead \u2014 e.g. `rm` + rewrite, or `iconv`.)";
 export declare function checkNoChange(oldString: string, newString: string): FsViolation | undefined;
-export declare function checkStale(entry: ReadEntry, currentHash: string): FsViolation | undefined;
+export declare function checkStale(entry: ReadEntry | undefined, currentHash: string): FsViolation | undefined;
 export declare function countOccurrences(haystack: string, needle: string): number;
 export declare function similarNameSuggestion(siblingNames: readonly string[], missingName: string): string | undefined;
 export declare function normalizeQuotes(s: string): string;

package/dist/tools/fs/safety.js

@@ -276,7 +276,7 @@ export function checkNoChange(oldString, newString) {
     return undefined;
 }
 export function checkStale(entry, currentHash) {
-    if (entry.hash !== currentHash) {
+    if (entry === undefined || entry.hash !== currentHash) {
         return { code: "stale", message: "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it." };
     }
     return undefined;

package/dist/tools/web.d.ts

@@ -29,3 +29,18 @@ export interface WebSearchConfig {
 }
 export declare function clipCodePoints(s: string, max: number): string;
 export declare function createWebSearchTool(config: WebSearchConfig): ToolSpec;
+export interface SearxngBackendOptions {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    extraParams?: Record<string, string>;
+}
+export declare function createSearxngSearchBackend(baseUrl: string, options?: SearxngBackendOptions): WebSearchConfig["search"];
+export declare function probeSearchBackend(search: WebSearchConfig["search"], options?: {
+    timeoutMs?: number;
+}): Promise<{
+    ok: true;
+    results: number;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/tools/web.js

@@ -798,3 +798,45 @@ export function createWebSearchTool(config) {
         },
     };
 }
+export function createSearxngSearchBackend(baseUrl, options = {}) {
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const base = baseUrl.replace(/\/+$/, "");
+    return async (query, signal, opts) => {
+        const q = opts?.allowedDomains && opts.allowedDomains.length > 0
+            ? `${opts.allowedDomains.map((d) => `site:${d}`).join(" OR ")} ${query}`
+            : query;
+        const url = new URL(`${base}/search`);
+        url.searchParams.set("q", q);
+        url.searchParams.set("format", "json");
+        for (const [k, v] of Object.entries(options.extraParams ?? {}))
+            url.searchParams.set(k, v);
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const res = await doFetch(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, headers: { accept: "application/json" } });
+        if (!res.ok)
+            throw new Error(`SearXNG ${res.status} ${res.statusText} from ${base}/search`);
+        const body = (await res.json());
+        if (!Array.isArray(body.results))
+            throw new Error(`SearXNG returned no results array from ${base}/search — is format=json enabled on this instance?`);
+        return body.results
+            .filter((r) => typeof r.url === "string" && r.url !== "")
+            .map((r) => ({
+            title: typeof r.title === "string" && r.title !== "" ? r.title : r.url,
+            url: r.url,
+            snippet: typeof r.content === "string" ? r.content : "",
+        }));
+    };
+}
+export async function probeSearchBackend(search, options) {
+    const budget = options?.timeoutMs ?? 15_000;
+    try {
+        const results = await Promise.race([
+            search("connectivity probe", AbortSignal.timeout(budget)),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`probe timed out after ${budget}ms`)), budget)),
+        ]);
+        return { ok: true, results: results.length };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",