@sema-agent/core 2.9.0 → 2.10.0

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",
@@ -1698,6 +1733,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 +1760,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 +1817,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 +1889,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 } : {}),
@@ -2157,6 +2212,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 +2239,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 +2473,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 +2570,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/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?: {

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

@@ -616,8 +616,37 @@ 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;
+        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 +671,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";
@@ -1852,7 +1876,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 +1885,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             activeTools.delete(name);
                             throw e;
                         }
+                        return listingRideRef.current?.([name]);
                     },
                 };
             };
@@ -3357,7 +3382,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/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/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/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/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.10.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",