@sema-agent/core 2.8.0 → 2.10.0

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

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { defineTool } from "../core/tools.js";
 import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
-import { canAccessAgentRecord } from "../core/background-agent-store.js";
+import { canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/background-agent-store.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
@@ -91,8 +91,9 @@ export function createSendMessageTool(opts) {
             }
             const senderId = ctx.taskId ?? opts.owner;
             const [parentTaskId, parentSessionId] = ctx.parentTaskId !== undefined ? [ctx.parentTaskId, ctx.parentSessionId] : [opts.parentTaskId, opts.parentSessionId];
-            const senderIsChild = parentTaskId !== undefined || opts.uplink !== undefined || opts.senderName !== undefined || opts.siblingRetain !== undefined;
-            const senderLabel = opts.senderName ?? (senderIsChild ? senderId ?? "main" : "main");
+            const senderName = ctx.spawnedAgentName ?? opts.senderName;
+            const senderIsChild = parentTaskId !== undefined || opts.uplink !== undefined || senderName !== undefined || opts.siblingRetain !== undefined;
+            const senderLabel = senderName ?? (senderIsChild ? senderId ?? "main" : "main");
             if (senderId !== undefined && isObserverTaskId(senderId)) {
                 return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" }, isError: true };
             }
@@ -102,7 +103,7 @@ 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 = opts.senderName !== undefined ? opts.senderName : senderId;
+                    const fromLabel = senderName ?? senderId;
                     try {
                         opts.uplink({
                             task_id: senderId,
@@ -140,6 +141,9 @@ export function createSendMessageTool(opts) {
                 scope: ctx.principal ?? opts.scope,
                 ...((ctx.sessionId ?? opts.sessionId) !== undefined ? { sessionId: ctx.sessionId ?? opts.sessionId } : {}),
             };
+            const parentAccess = parentTaskId !== undefined
+                ? { ...access, owner: parentTaskId, ...(parentSessionId !== undefined ? { sessionId: parentSessionId } : {}) }
+                : undefined;
             const tier3Revive = async (handle) => {
                 if (opts.agentStore === undefined || opts.mailbox === undefined || opts.reviveSpawn === undefined)
                     return undefined;
@@ -156,10 +160,9 @@ export function createSendMessageTool(opts) {
                 if (!row)
                     return undefined;
                 if (!canAccessAgentRecord(row, access)) {
-                    if (parentTaskId === undefined)
+                    if (parentAccess === undefined)
                         return undefined;
-                    const parentView = { ...access, owner: parentTaskId, ...(parentSessionId !== undefined ? { sessionId: parentSessionId } : {}) };
-                    if (!canAccessAgentRecord(row, parentView))
+                    if (!canAccessAgentRecord(row, parentAccess))
                         return undefined;
                 }
                 if (row.name === undefined || row.agentType === "fork")
@@ -213,15 +216,7 @@ export function createSendMessageTool(opts) {
                     const now = Date.now();
                     const nextSeq = (row.seq ?? 1) + 1;
                     const claimed = { ...row, status: "running", writerId: opts.registry.writerId, writerEpoch: (row.writerEpoch ?? 0) + 1, updatedAt: now, seq: nextSeq };
-                    delete claimed.settledAt;
-                    delete claimed.stoppedBy;
-                    delete claimed.finalOutput;
-                    delete claimed.error;
-                    delete claimed.resultIsPartial;
-                    delete claimed.summary;
-                    delete claimed.recentSteps;
-                    delete claimed.editedFiles;
-                    delete claimed.usage;
+                    clearRevivedRowTerminalPayload(claimed);
                     let won = false;
                     try {
                         won = await opts.agentStore.update(handle, scope, claimed, { rev: row.rev });
@@ -345,12 +340,11 @@ export function createSendMessageTool(opts) {
             };
             let idRow = opts.registry.getAccessibleTask(to, access);
             let resolvedAccess = access;
-            if (!idRow && parentTaskId !== undefined) {
-                const parentView = { ...access, owner: parentTaskId, ...(parentSessionId !== undefined ? { sessionId: parentSessionId } : {}) };
-                const siblingById = opts.registry.getAccessibleTask(to, parentView);
+            if (!idRow && parentAccess !== undefined) {
+                const siblingById = opts.registry.getAccessibleTask(to, parentAccess);
                 if (siblingById) {
                     idRow = siblingById;
-                    resolvedAccess = parentView;
+                    resolvedAccess = parentAccess;
                 }
             }
             if (!idRow && DURABLE_AGENT_HANDLE_RE.test(to)) {
@@ -361,12 +355,13 @@ export function createSendMessageTool(opts) {
             let target = idRow;
             if (!target) {
                 let byName = opts.registry.resolveBackgroundAgentByName(to, access);
-                if (byName.status === "not_found" && parentTaskId !== undefined) {
-                    const parentView = { ...access, owner: parentTaskId, ...(parentSessionId !== undefined ? { sessionId: parentSessionId } : {}) };
-                    const sibling = opts.registry.resolveBackgroundAgentByName(to, parentView);
+                let parentByName;
+                if (byName.status === "not_found" && parentAccess !== undefined) {
+                    const sibling = opts.registry.resolveBackgroundAgentByName(to, parentAccess);
+                    parentByName = sibling;
                     if (sibling.status === "found" || sibling.status === "ambiguous") {
                         byName = sibling;
-                        resolvedAccess = parentView;
+                        resolvedAccess = parentAccess;
                     }
                 }
                 if (byName.status === "ambiguous") {
@@ -381,6 +376,8 @@ export function createSendMessageTool(opts) {
                     if (opts.roster) {
                         try {
                             rosterHit = await opts.roster.resolve(to, access);
+                            if (rosterHit === undefined && parentAccess !== undefined)
+                                rosterHit = await opts.roster.resolve(to, parentAccess);
                         }
                         catch {
                         }
@@ -396,13 +393,17 @@ export function createSendMessageTool(opts) {
                             isError: true,
                         };
                     }
-                    const labels = opts.registry.runningBackgroundAgentLabels(access);
+                    const suggestion = byName.suggestion ?? (parentByName?.status === "not_found" ? parentByName.suggestion : undefined);
+                    const ownLabels = opts.registry.runningBackgroundAgentLabels(access);
+                    const labels = parentAccess !== undefined
+                        ? [...ownLabels, ...opts.registry.runningBackgroundAgentLabels(parentAccess).filter((l) => !ownLabels.includes(l))]
+                        : ownLabels;
                     return {
                         content: `Message not sent: no agent matches "${to}" (unknown id or name, not yours, or expired).` +
-                            (byName.suggestion !== undefined ? ` Did you mean: ${byName.suggestion}?` : "") +
+                            (suggestion !== undefined ? ` Did you mean: ${suggestion}?` : "") +
                             (labels.length > 0 ? ` Running background agents: ${labels.join(", ")}.` : "") +
                             ` Note: a completed foreground agent is not resumable (its transcript is not retained) — spawn with run_in_background to keep an agent addressable, or launch a new agent.`,
-                        details: { error: "not_found", to, ...(byName.suggestion !== undefined ? { suggestion: byName.suggestion } : {}) },
+                        details: { error: "not_found", to, ...(suggestion !== undefined ? { suggestion } : {}) },
                         isError: true,
                     };
                 }
@@ -424,7 +425,7 @@ export function createSendMessageTool(opts) {
                         : message;
                     const teammateXml = frameTeammateMessage({ from: fromLabel, ...(s2Summary !== undefined ? { summary: s2Summary } : {}), text: s2Clipped });
                     const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
-                        task_id: senderId ?? "main",
+                        task_id: senderLabel,
                         task_type: "background_agent",
                         status: "event",
                         summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
@@ -450,6 +451,13 @@ export function createSendMessageTool(opts) {
                         };
                     }
                     const nowRow = opts.registry.getAccessibleTask(targetId, resolvedAccess);
+                    if (nowRow?.status === "parked") {
+                        return {
+                            content: `Message not sent: ${who} is parked on a pending approval — it resumes when the approval is decided, not by message delivery. Send again after it resumes.`,
+                            details: { error: "parked_pending_approval", to },
+                            isError: true,
+                        };
+                    }
                     const stillLive = nowRow !== undefined && (nowRow.status === "running" || nowRow.status === "pending");
                     return stillLive
                         ? {
@@ -524,7 +532,7 @@ export function createSendMessageTool(opts) {
                     ...(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 "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
+                const fromPrefix = parentTaskId !== undefined ? `(message from teammate "${senderName ?? senderId ?? "unknown"}")\n` : "";
                 try {
                     const safeSummary = summary !== undefined ? escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, summary) : undefined;
                     const safeMessage = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, message);

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",
@@ -1201,6 +1236,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     tools: [reportTool],
                     ...(ctx.excludeTools !== undefined ? { excludeTools: [...ctx.excludeTools] } : {}),
                     ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
+                    ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                     ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
                     enableBlockedReport: false,
                     limits: { maxTurns: observerDef.maxTurns ?? 8, timeoutSec: 120 },
@@ -1344,9 +1380,17 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 parentToolCallId: ctx.toolCallId,
                 ...(childAgentName ? { agentName: childAgentName } : {}),
                 ...(agentName !== undefined ? { explicitAgentName: agentName } : {}),
-                ...(ctx.taskId !== undefined ? { parentTaskId: ctx.taskId } : {}),
-                ...(ctx.sessionId !== undefined ? { parentSessionId: ctx.sessionId } : {}),
-                ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}),
+                ...(reviveClaim !== undefined
+                    ? {
+                        ...(reviveClaim.row.parentTaskId !== undefined ? { parentTaskId: reviveClaim.row.parentTaskId } : {}),
+                        ...(reviveClaim.row.parentSessionId !== undefined ? { parentSessionId: reviveClaim.row.parentSessionId } : {}),
+                        ...(reviveClaim.row.rootSessionId !== undefined ? { rootSessionId: reviveClaim.row.rootSessionId } : {}),
+                    }
+                    : {
+                        ...(ctx.taskId !== undefined ? { parentTaskId: ctx.taskId } : {}),
+                        ...(ctx.sessionId !== undefined ? { parentSessionId: ctx.sessionId } : {}),
+                        ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}),
+                    }),
                 ...(ctx.centerArtifactDigest !== undefined ? { parentCenterArtifactDigest: ctx.centerArtifactDigest } : {}),
                 ...(ctx.centerSourceRevision !== undefined ? { parentCenterSourceRevision: ctx.centerSourceRevision } : {}),
                 ...(ctx.onTaskNotification !== undefined ? { parentNotify: ctx.onTaskNotification } : {}),
@@ -1375,6 +1419,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.clientContext !== undefined ? { clientContext: ctx.clientContext } : {}),
                 ...(ctx.excludeTools !== undefined ? { excludeTools: [...ctx.excludeTools] } : {}),
                 ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
+                ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                 ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
                 ...(ctx.additionalDirectories !== undefined ? { additionalDirectories: [...ctx.additionalDirectories] } : {}),
                 ...(ctx.envFacts !== undefined ? { envFacts: { ...ctx.envFacts } } : {}),
@@ -1402,6 +1447,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(plainSpec.clientContext !== undefined ? { clientContext: { ...plainSpec.clientContext } } : {}),
                         ...(plainSpec.excludeTools !== undefined ? { excludeTools: [...plainSpec.excludeTools] } : {}),
                         ...(plainSpec.deferTools !== undefined ? { deferTools: [...plainSpec.deferTools] } : {}),
+                        ...(plainSpec.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...plainSpec.alwaysLoadTools] } : {}),
                     }),
                     internalsSnapshot: { ...childInternals },
                     release: async () => {
@@ -1482,6 +1528,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...(plainSpec.clientContext !== undefined ? { clientContext: { ...plainSpec.clientContext } } : {}),
                             ...(plainSpec.excludeTools !== undefined ? { excludeTools: [...plainSpec.excludeTools] } : {}),
                             ...(plainSpec.deferTools !== undefined ? { deferTools: [...plainSpec.deferTools] } : {}),
+                            ...(plainSpec.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...plainSpec.alwaysLoadTools] } : {}),
                         }),
                         internalsSnapshot: { ...childInternals },
                         release: releaseChild,
@@ -1686,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,
@@ -1696,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();
@@ -1752,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) } : {}),
@@ -1823,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 } : {}),
@@ -2145,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,
@@ -2155,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();
@@ -2388,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),
@@ -2484,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/brain/circuit-breaker.js

@@ -42,20 +42,23 @@ export function createCircuitBreakerBrain(inner, opts = {}) {
     const tryPass = (key) => {
         const s = snap(key);
         if (s.phase === "closed")
-            return true;
+            return { pass: true };
         if (s.phase === "open") {
-            if (s.openedAt !== undefined && now() - s.openedAt >= cooldownMs) {
+            if (s.openedAt === undefined)
+                return { pass: false };
+            const elapsed = now() - s.openedAt;
+            if (elapsed >= cooldownMs) {
                 setState(key, s.phase, { ...s, phase: "half-open", halfOpenInFlight: 1 });
-                return true;
+                return { pass: true };
             }
-            return false;
+            return { pass: false, retryInMs: cooldownMs - elapsed };
         }
         const inFlight = s.halfOpenInFlight ?? 0;
         if (inFlight < halfOpenProbes) {
             state.set(key, { ...s, halfOpenInFlight: inFlight + 1 });
-            return true;
+            return { pass: true };
         }
-        return false;
+        return { pass: false };
     };
     const record = (key, failedCode, viaProbe = true) => {
         const s = snap(key);
@@ -81,8 +84,15 @@ export function createCircuitBreakerBrain(inner, opts = {}) {
         const key = keyOf(model);
         void (async () => {
             const bypass = options?.resilience?.bypassBreaker === true;
-            if (!bypass && !tryPass(key)) {
-                emitBrainStatus({ phase: "circuit_open", detail: "repeated errors, pausing briefly" });
+            const decision = bypass ? { pass: true } : tryPass(key);
+            if (!decision.pass) {
+                emitBrainStatus({
+                    phase: "circuit_open",
+                    detail: "repeated errors, pausing briefly",
+                    ...(decision.retryInMs !== undefined
+                        ? { retryInMs: decision.retryInMs, retryInSec: Math.ceil(decision.retryInMs / 1000) }
+                        : {}),
+                });
                 out.push({ type: "error", reason: "error", error: errorAssistantMessage(model, "network", `${CIRCUIT_OPEN_MARKER}${key}`) });
                 return;
             }

package/dist/brain/retry.d.ts

@@ -1,2 +1,3 @@
 export declare function parseRetryAfter(res: Response | undefined): number | undefined;
+export declare function parseRateLimitReset(res: Response | undefined): number | undefined;
 export declare function retryBackoffMs(baseDelayMs: number, attempt: number, res?: Response, rand?: () => number): number;

package/dist/brain/retry.js

@@ -1,5 +1,7 @@
-const MAX_BACKOFF_MS = 30_000;
-const MAX_RETRY_AFTER_MS = 120_000;
+const MAX_BACKOFF_MS = 32_000;
+const JITTER_FRACTION = 0.25;
+const MAX_HEADER_WAIT_MS = 60_000;
+const RATE_LIMIT_STATUS = 429;
 export function parseRetryAfter(res) {
     const h = res?.headers?.get?.("retry-after");
     if (!h)
@@ -12,11 +14,31 @@ export function parseRetryAfter(res) {
         return Math.max(0, date - Date.now());
     return undefined;
 }
+export function parseRateLimitReset(res) {
+    const h = res?.headers?.get?.("anthropic-ratelimit-unified-reset");
+    if (!h)
+        return undefined;
+    const epochSecs = Number(h);
+    if (!Number.isFinite(epochSecs))
+        return undefined;
+    const ms = Math.round(epochSecs * 1000 - Date.now());
+    return ms > 0 ? ms : undefined;
+}
+function providerWaitHintMs(res) {
+    const hints = [];
+    const retryAfter = parseRetryAfter(res);
+    if (retryAfter !== undefined)
+        hints.push(Math.min(MAX_HEADER_WAIT_MS, retryAfter));
+    if (res?.status === RATE_LIMIT_STATUS) {
+        const reset = parseRateLimitReset(res);
+        if (reset !== undefined)
+            hints.push(Math.min(MAX_HEADER_WAIT_MS, reset));
+    }
+    return hints.length === 0 ? undefined : Math.max(...hints);
+}
 export function retryBackoffMs(baseDelayMs, attempt, res, rand = Math.random) {
     const exp = Math.min(MAX_BACKOFF_MS, baseDelayMs * 2 ** attempt);
-    const jittered = rand() * exp;
-    const retryAfter = parseRetryAfter(res);
-    if (retryAfter === undefined)
-        return jittered;
-    return Math.max(Math.min(MAX_RETRY_AFTER_MS, retryAfter), jittered);
+    const computed = Math.round(exp + rand() * JITTER_FRACTION * exp);
+    const hint = providerWaitHintMs(res);
+    return hint === undefined ? computed : Math.max(hint, computed);
 }

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

@@ -4,6 +4,7 @@ export interface StreamEngineConfig extends BrainTimeoutConfig {
     maxRetries?: number;
     retryDelayMs?: number;
 }
+export declare function resolveMaxRetries(configured: number | undefined): number;
 export interface SSERequest {
     url: string;
     headers: Record<string, string>;

package/dist/brain/stream-engine.js

@@ -4,6 +4,22 @@ import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController } from "./timeout.js";
 import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
+const DEFAULT_MAX_RETRIES = 10;
+const MAX_RETRIES_ENV_CEILING = 15;
+const MAX_RETRIES_ENV = "SEMA_MAX_RETRIES";
+export function resolveMaxRetries(configured) {
+    if (configured !== undefined)
+        return configured;
+    const raw = process.env[MAX_RETRIES_ENV];
+    if (raw !== undefined && raw.trim() !== "") {
+        const parsed = Number(raw);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return Math.min(Math.floor(parsed), MAX_RETRIES_ENV_CEILING);
+    }
+    return DEFAULT_MAX_RETRIES;
+}
+const RETRY_STATUS_SLICE_MS = 30_000;
+const THINKING_RETRY_BUDGET = 2;
 const EMPTY_USAGE = {
     input: 0,
     output: 0,
@@ -43,25 +59,54 @@ function sleep(ms, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
+async function sleepAnnouncingRetry(totalMs, signal, frame) {
+    let remaining = Math.max(0, totalMs);
+    for (;;) {
+        if (signal?.aborted)
+            return;
+        emitBrainStatus(frame(remaining));
+        if (remaining <= 0)
+            return;
+        const slice = Math.min(remaining, RETRY_STATUS_SLICE_MS);
+        await sleep(slice, signal);
+        remaining -= slice;
+        if (remaining <= 0)
+            return;
+    }
+}
 export function runStreamingBrain(args) {
     const { model, doFetch, signal, config, httpLabel, buildRequest, makeParser, callDeadlineMs, stallTimeouts } = args;
     const out = createAssistantMessageEventStream();
     let cleanup;
+    let announcedRetry = false;
+    let terminalRetryPhase = "recovered";
+    let terminalRetryDetail = "recovered after retrying";
     void run()
         .catch((err) => {
         const aborted = signal?.aborted === true || isAbortError(err);
+        terminalRetryPhase = "gave_up";
+        terminalRetryDetail = aborted ? "cancelled while retrying" : "retries exhausted";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = err instanceof Error ? err.message : String(err);
         errorMsg.usageMissing = true;
         out.push({ type: "error", reason: aborted ? "aborted" : "error", error: errorMsg });
     })
-        .finally(() => cleanup?.());
+        .finally(() => {
+        cleanup?.();
+        if (!announcedRetry)
+            return;
+        try {
+            emitBrainStatus({ phase: terminalRetryPhase, detail: terminalRetryDetail });
+        }
+        catch {
+        }
+    });
     return out;
     async function run() {
         const req = buildRequest();
-        const maxRetries = config.maxRetries ?? 2;
-        const baseDelay = config.retryDelayMs ?? 400;
+        const maxRetries = resolveMaxRetries(config.maxRetries);
+        const baseDelay = config.retryDelayMs ?? 500;
         const firstTokenTimeoutMs = config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs;
         const idleTimeoutMs = config.idleTimeoutMs ?? stallTimeouts?.idleMs;
         const connectTimeoutMs = config.connectTimeoutMs ?? stallTimeouts?.connectMs;
@@ -126,16 +171,19 @@ export function runStreamingBrain(args) {
                     }
                     const statusPhase = r?.status === 429 ? "rate_limited" : netErr !== undefined ? "reconnecting" : "retrying";
                     emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
-                    emitBrainStatus({
+                    announcedRetry = true;
+                    await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
                         phase: statusPhase,
                         detail: statusPhase === "rate_limited"
                             ? "rate limited, backing off"
                             : statusPhase === "reconnecting"
                                 ? "connection lost, reconnecting"
                                 : "transient error, retrying",
-                        retryInSec: Math.ceil(delayMs / 1000),
-                    });
-                    await sleep(delayMs, signal);
+                        retryInSec: Math.ceil(remainingMs / 1000),
+                        retryInMs: remainingMs,
+                        attempt: attempt + 1,
+                        maxRetries,
+                    }));
                     continue;
                 }
                 if (netErr)
@@ -311,14 +359,21 @@ export function runStreamingBrain(args) {
             cleanup?.();
             cleanup = undefined;
             if (snap.hasOnlyThinking) {
-                if (thinkingRetries >= 2)
+                if (thinkingRetries >= THINKING_RETRY_BUDGET)
                     throw failure.err;
                 thinkingRetries++;
                 parser.sealForRetry();
                 const delayMs = 100 * thinkingRetries;
                 emitBrainTelemetry({ kind: "retry", attempt: thinkingRetries, phase: "midstream" });
-                emitBrainStatus({ phase: "reconnecting", detail: "connection lost, reconnecting", retryInSec: Math.ceil(delayMs / 1000) });
-                await sleep(delayMs, signal);
+                announcedRetry = true;
+                await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
+                    phase: "reconnecting",
+                    detail: "connection lost, reconnecting",
+                    retryInSec: Math.ceil(remainingMs / 1000),
+                    retryInMs: remainingMs,
+                    attempt: thinkingRetries,
+                    maxRetries: THINKING_RETRY_BUDGET,
+                }));
                 continue;
             }
             if (attempt >= maxRetries)
@@ -326,8 +381,15 @@ export function runStreamingBrain(args) {
             const delayMs = retryBackoffMs(baseDelay, attempt);
             attempt++;
             emitBrainTelemetry({ kind: "retry", attempt, phase: "midstream" });
-            emitBrainStatus({ phase: "reconnecting", detail: "connection lost, reconnecting", retryInSec: Math.ceil(delayMs / 1000) });
-            await sleep(delayMs, signal);
+            announcedRetry = true;
+            await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
+                phase: "reconnecting",
+                detail: "connection lost, reconnecting",
+                retryInSec: Math.ceil(remainingMs / 1000),
+                retryInMs: remainingMs,
+                attempt,
+                maxRetries,
+            }));
         }
     }
 }

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;