@sema-agent/core 1.452.0 → 2.0.1

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

@@ -0,0 +1,469 @@
+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 { 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";
+export const SEND_MESSAGE_TOOL_NAME = "SendMessage";
+let uplinkSeqGlobal = Date.now();
+const UPLINK_RESULT_MAX = 8000;
+const REVIVE_LEASE_TTL_MS = 5 * 60_000;
+export function createSendMessageTool(opts) {
+    const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    return defineTool({
+        name: SEND_MESSAGE_TOOL_NAME,
+        contract: { contractId: "core.send_message@1", implementationRevision: "1" },
+        executionMode: "parallel",
+        description: `Send a follow-up message to a previously spawned background agent. ` +
+            `'to' is the agent's name (set at spawn via Agent({name})) or its task_id (a…). A RUNNING agent receives the ` +
+            `message at its next turn (queued — never interrupts its current work); a FINISHED agent resumes as a new ` +
+            `background run with its full prior conversation preserved, so don't re-explain what it already knows. Names ` +
+            `keep working after an agent completes; when a newer agent took the name, the newest wins — use the task_id to ` +
+            `address an older one. You will be notified automatically when it completes — prefer ending your turn; do not ` +
+            `poll. ` +
+            (tier3Capable
+                ? `Continuing a finished agent works for NAMED agents (revived from their durable record, even across restarts) and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
+                : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
+                    `retained (or has expired) you get an honest error and should launch a new agent with the needed context instead.`),
+        parameters: Type.Object({
+            to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
+            message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
+            summary: Type.Optional(Type.String({ maxLength: 200, description: "A short (3-5 word) description of the follow-up." })),
+        }),
+        execute: async (args, ctx) => {
+            const a = args;
+            const to = String(a.to ?? "").trim();
+            const message = String(a.message ?? "").trim();
+            if (!to)
+                return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" }, isError: true };
+            if (!message)
+                return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" }, isError: true };
+            const senderId = ctx.taskId ?? opts.owner;
+            if (senderId !== undefined && isObserverTaskId(senderId)) {
+                return { content: OBSERVER_SENDMESSAGE_SENDER_REFUSAL, details: { error: "observer_sender" }, isError: true };
+            }
+            if (isObserverTaskId(to)) {
+                return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to }, isError: true };
+            }
+            if (normalizeAgentName(to) === "main") {
+                if (opts.uplink && senderId !== undefined) {
+                    const uplinkSummaryRaw = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : message.slice(0, 80);
+                    const fromLabel = opts.senderName !== undefined ? opts.senderName : senderId;
+                    try {
+                        opts.uplink({
+                            task_id: senderId,
+                            task_type: "background_agent",
+                            status: "event",
+                            summary: `message from ${fromLabel}: ${uplinkSummaryRaw}`,
+                            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" });
+                    }
+                    catch (e) {
+                        return { content: `Message not sent: the parent's notification lane rejected it (${e instanceof Error ? e.message : String(e)}).`, details: { error: "uplink_failed", to }, isError: true };
+                    }
+                    return {
+                        content: `Message sent to main — it will reach the spawning conversation at its next turn boundary. Continue with your task; do not wait for a reply.`,
+                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
+                    };
+                }
+                return {
+                    content: `Message not sent: "main" (the spawning conversation) is not a deliverable target here. ` +
+                        `Your completion is reported to it automatically — finish your task and your final report will be relayed.`,
+                    details: { error: "main_not_deliverable", to },
+                    isError: true,
+                };
+            }
+            const access = {
+                owner: ctx.taskId ?? opts.owner,
+                scope: ctx.principal ?? opts.scope,
+                ...((ctx.sessionId ?? opts.sessionId) !== undefined ? { sessionId: ctx.sessionId ?? opts.sessionId } : {}),
+            };
+            const tier3Revive = async (handle) => {
+                if (opts.agentStore === undefined || opts.mailbox === undefined || opts.reviveSpawn === undefined)
+                    return undefined;
+                const scope = access.scope;
+                if (scope === undefined)
+                    return undefined;
+                let row;
+                try {
+                    row = await opts.agentStore.get(handle, scope);
+                }
+                catch {
+                    return undefined;
+                }
+                if (!row)
+                    return undefined;
+                if (!canAccessAgentRecord(row, access)) {
+                    if (ctx.parentTaskId === undefined)
+                        return undefined;
+                    const parentView = { ...access, owner: ctx.parentTaskId, ...(ctx.parentSessionId !== undefined ? { sessionId: ctx.parentSessionId } : {}) };
+                    if (!canAccessAgentRecord(row, parentView))
+                        return undefined;
+                }
+                if (row.name === undefined || row.agentType === "fork")
+                    return undefined;
+                const whoT3 = handle === to ? `agent ${handle}` : `agent "${to}" (${handle})`;
+                if (row.status === "killed") {
+                    return {
+                        content: `Message not sent: ${whoT3} was stopped${row.stoppedBy !== undefined ? ` (by ${row.stoppedBy})` : ""} — a stopped agent is not revived. Launch a new agent with the needed context instead.`,
+                        details: { error: "killed", to, ...(row.stoppedBy !== undefined ? { stoppedBy: row.stoppedBy } : {}) },
+                        isError: true,
+                    };
+                }
+                if (row.status === "parked") {
+                    return {
+                        content: `Message not sent: ${whoT3} is parked on a pending approval — it resumes when the approval is decided (durable approval inbox), not by message delivery. Send again after it resumes.`,
+                        details: { error: "parked_pending_approval", to },
+                        isError: true,
+                    };
+                }
+                if (row.status === "running") {
+                    if (row.writerId === opts.registry.writerId) {
+                        return {
+                            content: `Message not sent: ${whoT3} is currently running in this process but its mid-run delivery channel is not reachable from here. Wait for its completion notification, then send again to continue it.`,
+                            details: { error: "still_running", to },
+                            isError: true,
+                        };
+                    }
+                    if (Date.now() - row.updatedAt > 10 * DURABLE_AGENT_HEARTBEAT_MS) {
+                        return {
+                            content: `Message not sent: ${whoT3} last ran on another host that has stopped renewing its record (no heartbeat). Its row will be settled by the stale-row sweep — send again after that to revive it.`,
+                            details: { error: "host_gone", to },
+                            isError: true,
+                        };
+                    }
+                    return {
+                        content: `Message not sent: ${whoT3} is running on another host — this process has no delivery channel to it. Wait for its completion notification, then send again to continue it.`,
+                        details: { error: "running_elsewhere", to },
+                        isError: true,
+                    };
+                }
+                if (row.sessionId === undefined)
+                    return undefined;
+                if (!opts.registry.beginDurableClaim(handle)) {
+                    return {
+                        content: `Message not sent: ${whoT3} is being revived or recycled right now — send again in a moment.`,
+                        details: { error: "claim_contended", to },
+                        isError: true,
+                    };
+                }
+                try {
+                    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;
+                    let won = false;
+                    try {
+                        won = await opts.agentStore.update(handle, scope, claimed, { rev: row.rev });
+                    }
+                    catch {
+                        won = false;
+                    }
+                    if (!won) {
+                        let fresh = null;
+                        try {
+                            fresh = await opts.agentStore.get(handle, scope);
+                        }
+                        catch {
+                        }
+                        if (fresh?.status === "running") {
+                            return {
+                                content: `Message not sent: ${whoT3} was just revived by another delivery — it is running now. Send again to reach the running agent.`,
+                                details: { error: "claim_lost", to },
+                                isError: true,
+                            };
+                        }
+                        return {
+                            content: `Message not sent: ${whoT3}'s durable record changed underneath this delivery — send again.`,
+                            details: { error: "claim_lost", to },
+                            isError: true,
+                        };
+                    }
+                    const claimedRev = row.rev + 1;
+                    const rollback = async () => {
+                        try {
+                            await opts.agentStore.update(handle, scope, { ...row, updatedAt: Date.now() }, { rev: claimedRev });
+                        }
+                        catch {
+                        }
+                    };
+                    try {
+                        await opts.runner.sessions.acquire(row.sessionId, { requireExisting: true });
+                    }
+                    catch (e) {
+                        await rollback();
+                        if (e?.code === "not_found") {
+                            return {
+                                content: `Message not sent: ${whoT3}'s transcript session no longer exists (evicted or reaped) — it cannot be revived. Launch a new agent with the needed context instead.`,
+                                details: { error: "resume.session_not_found", to },
+                                isError: true,
+                            };
+                        }
+                        return {
+                            content: `Message not sent: ${whoT3}'s transcript store did not answer (${e instanceof Error ? e.message : String(e)}) — nothing was parked; send again.`,
+                            details: { error: "session_store_unavailable", to },
+                            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() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+                    const t3From = opts.senderName ?? senderId;
+                    try {
+                        await opts.mailbox.append(scope, handle, { ...(t3From !== undefined ? { from: t3From } : {}), content: t3Summary !== undefined ? `[${t3Summary}] ${clipped}` : clipped, sentAt: now });
+                    }
+                    catch (e) {
+                        await rollback();
+                        return {
+                            content: `Message not sent: the durable mailbox refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked and the agent was not revived.`,
+                            details: { error: "mailbox_failed", to },
+                            isError: true,
+                        };
+                    }
+                    const leaseOwner = `${opts.registry.writerId}:${ctx.toolCallId}`;
+                    let lease = null;
+                    try {
+                        lease = await opts.mailbox.claimLease(scope, handle, leaseOwner, REVIVE_LEASE_TTL_MS);
+                    }
+                    catch {
+                        lease = null;
+                    }
+                    if (lease === null) {
+                        await rollback();
+                        return {
+                            content: `Message not sent now: ${whoT3}'s mailbox is leased by another in-flight revival. Your message is queued and will be delivered with the next successful revival — do not resend the same content.`,
+                            details: { error: "mailbox_leased", to },
+                        };
+                    }
+                    const revivePrompt = lease.messages.map((m) => `<teammate-message teammate_id="${m.from ?? "main"}">\n${m.content}\n</teammate-message>`).join("\n");
+                    let spawned;
+                    try {
+                        spawned = await opts.reviveSpawn({ row: claimed, rev: claimedRev, prompt: revivePrompt });
+                    }
+                    catch (e) {
+                        spawned = { isError: true, content: e instanceof Error ? e.message : String(e), details: { error: "revive_failed" } };
+                    }
+                    if (spawned.isError === true) {
+                        try {
+                            await opts.mailbox.releaseLease(scope, handle, leaseOwner);
+                        }
+                        catch {
+                        }
+                        await rollback();
+                        const code = spawned.details?.error;
+                        return {
+                            content: `Message not sent: ${whoT3} could not be revived — ${spawned.content}\nYour message remains queued and will be delivered if a later revival succeeds; do not resend the same content.`,
+                            details: { error: code ?? "revive_failed", to },
+                        };
+                    }
+                    try {
+                        await opts.mailbox.ack(scope, handle, leaseOwner, lease.maxSeq);
+                    }
+                    catch {
+                    }
+                    const priorCount = lease.messages.length - 1;
+                    return {
+                        content: `Message sent — ${whoT3} was revived in the background with its prior context intact${priorCount > 0 ? ` (${priorCount} earlier pending message(s) delivered with it)` : ""}. ` +
+                            `You will be notified automatically when it completes. Continue with other work — do not poll.`,
+                        details: { type: "send-message", status: "revived", to, task_id: handle, seq: nextSeq, ...(priorCount > 0 ? { priorMessages: priorCount } : {}) },
+                    };
+                }
+                finally {
+                    opts.registry.endDurableClaim(handle);
+                }
+            };
+            let idRow = opts.registry.getAccessibleTask(to, access);
+            let resolvedAccess = access;
+            if (!idRow && ctx.parentTaskId !== undefined) {
+                const parentView = { ...access, owner: ctx.parentTaskId, ...(ctx.parentSessionId !== undefined ? { sessionId: ctx.parentSessionId } : {}) };
+                const siblingById = opts.registry.getAccessibleTask(to, parentView);
+                if (siblingById) {
+                    idRow = siblingById;
+                    resolvedAccess = parentView;
+                }
+            }
+            if (!idRow && DURABLE_AGENT_HANDLE_RE.test(to)) {
+                const revived = await tier3Revive(to);
+                if (revived !== undefined)
+                    return revived;
+            }
+            let target = idRow;
+            if (!target) {
+                let byName = opts.registry.resolveBackgroundAgentByName(to, access);
+                if (byName.status === "not_found" && ctx.parentTaskId !== undefined) {
+                    const parentView = { ...access, owner: ctx.parentTaskId, ...(ctx.parentSessionId !== undefined ? { sessionId: ctx.parentSessionId } : {}) };
+                    const sibling = opts.registry.resolveBackgroundAgentByName(to, parentView);
+                    if (sibling.status === "found" || sibling.status === "ambiguous") {
+                        byName = sibling;
+                        resolvedAccess = parentView;
+                    }
+                }
+                if (byName.status === "ambiguous") {
+                    return { content: `Message not sent: ${byName.message}`, details: { error: "ambiguous", to }, isError: true };
+                }
+                if (byName.status === "found") {
+                    const h = byName.handle;
+                    target = { task_id: h.id, type: h.type, status: h.status, ...(h.toolUseId !== undefined ? { toolUseId: h.toolUseId } : {}), ...(h.sessionScoped ? { sessionScoped: true } : {}), ...(h.description !== undefined ? { description: h.description } : {}), ...(h.name !== undefined ? { name: h.name } : {}), ...(h.agentType !== undefined ? { agentType: h.agentType } : {}), ...(h.owner !== undefined ? { owner: h.owner } : {}), ...(h.scope !== undefined ? { scope: h.scope } : {}), ...(h.parentTaskId !== undefined ? { parentTaskId: h.parentTaskId } : {}), ...(h.parentSessionId !== undefined ? { parentSessionId: h.parentSessionId } : {}), ...(h.rootSessionId !== undefined ? { rootSessionId: h.rootSessionId } : {}) };
+                }
+                else {
+                    let rosterHit;
+                    if (opts.roster) {
+                        try {
+                            rosterHit = await opts.roster.resolve(to, access);
+                        }
+                        catch {
+                        }
+                    }
+                    if (rosterHit !== undefined) {
+                        const revived = await tier3Revive(rosterHit.agentId);
+                        if (revived !== undefined)
+                            return revived;
+                        return {
+                            content: `Message not sent: "${to}" is on the durable roster (agent ${rosterHit.agentId}) but not reachable in this run — its session belongs to an earlier process. ` +
+                                `Launch a new agent with the needed context instead.`,
+                            details: { error: "roster_only", to, agentId: rosterHit.agentId },
+                            isError: true,
+                        };
+                    }
+                    const labels = opts.registry.runningBackgroundAgentLabels(access);
+                    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}?` : "") +
+                            (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 } : {}) },
+                        isError: true,
+                    };
+                }
+            }
+            const row = target;
+            if (row === undefined)
+                return { content: `Message not sent: no agent named "${to}" is reachable.`, details: { error: "not_found", to }, isError: true };
+            const targetId = row.task_id;
+            const who = targetId === to ? `agent ${targetId}` : `agent "${to}" (${targetId})`;
+            if (row.type !== "background_agent") {
+                return { content: `Message not sent: ${targetId} is a ${row.type} task, not a background agent.`, details: { error: "wrong_type", to }, isError: true };
+            }
+            if (row.status === "running" || row.status === "pending") {
+                const s2Summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+                const fromLabel = opts.senderName ?? senderId ?? "main";
+                const teammateXml = `<teammate-message teammate_id="${fromLabel}"${s2Summary !== undefined ? ` summary=${JSON.stringify(s2Summary)}` : ""}>\n${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[message truncated: ${message.length} chars total]` : message}\n</teammate-message>`;
+                const delivered = await opts.registry.deliverToRunningAgent(targetId, resolvedAccess, {
+                    task_id: senderId ?? "main",
+                    task_type: "background_agent",
+                    status: "event",
+                    summary: `message from ${fromLabel}${s2Summary !== undefined ? `: ${s2Summary}` : ""}`,
+                    result: teammateXml,
+                    seq: ++uplinkSeqGlobal,
+                }, { priority: "next" });
+                if (delivered.ok) {
+                    const receiptText = delivered.disposition === "parked"
+                        ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
+                        : delivered.disposition === "pending"
+                            ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered.`
+                            : `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 } : {}) },
+                    };
+                }
+                if (delivered.reason === "no_channel") {
+                    return {
+                        content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it.`,
+                        details: { error: "still_running", to },
+                        isError: true,
+                    };
+                }
+                return {
+                    content: `Message not sent: ${who} just finished (delivery raced its completion). Send again to continue it from its transcript.`,
+                    details: { error: "settle_race", to },
+                    isError: true,
+                };
+            }
+            if (row.status === "killed") {
+                const by = opts.registry.getStopAttribution(targetId);
+                return {
+                    content: `Message not sent: ${who} was stopped${by ? ` (by ${by})` : ""} — a stopped agent is not resumable. Launch a new agent with the needed context instead.`,
+                    details: { error: "killed", to, ...(by !== undefined ? { stoppedBy: by } : {}) },
+                    isError: true,
+                };
+            }
+            const runLedger = ctx.subagentRetain ?? opts.retain;
+            const smLedgerSessionId = ctx.sessionId ?? opts.sessionId;
+            const sessionLedger = smLedgerSessionId !== undefined ? getSessionRetainLedger(smLedgerSessionId) : undefined;
+            const knows = (l) => l !== undefined && row.toolUseId !== undefined && (l.get(row.toolUseId) !== undefined || l.wasEvicted(row.toolUseId));
+            const siblingLedger = opts.siblingRetain;
+            const liveRetainEntry = row.toolUseId !== undefined ? (sessionLedger?.get(row.toolUseId) ?? runLedger?.get(row.toolUseId) ?? siblingLedger?.get(row.toolUseId)) : undefined;
+            if (liveRetainEntry === undefined) {
+                const revived = await tier3Revive(targetId);
+                if (revived !== undefined)
+                    return revived;
+            }
+            const ledger = (knows(sessionLedger) ? sessionLedger : undefined) ?? (knows(runLedger) ? runLedger : undefined) ?? (knows(siblingLedger) ? siblingLedger : undefined) ?? runLedger ?? sessionLedger ?? siblingLedger;
+            if (!ledger || row.toolUseId === undefined) {
+                return {
+                    content: `Message not sent: ${who}'s session was not retained (this run did not enable retainSubagentSessions), so it cannot be continued — relaunch a new agent with the needed context instead.`,
+                    details: { error: "not_retained", to },
+                    isError: true,
+                };
+            }
+            const resume = createSubagentResume({
+                ledger,
+                parentToolCallId: row.toolUseId,
+                runner: opts.runner,
+                ...(opts.notify ? { notify: opts.notify } : {}),
+                ...(opts.sink ? { sink: opts.sink } : {}),
+                registry: opts.registry,
+                taskId: targetId,
+                taskAccess: resolvedAccess,
+                ...((ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent) ? { bgSink: ctx.onBackgroundChildEvent ?? opts.onBackgroundChildEvent } : {}),
+                sessionScoped: row.sessionScoped === true,
+                ...(row.description !== undefined ? { rowDescription: row.description } : {}),
+                ...(row.name !== undefined ? { rowName: row.name } : {}),
+                ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
+                ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
+                ...(row.scope !== undefined ? { rowScope: row.scope } : {}),
+                ...(row.parentTaskId !== undefined ? { rowParentTaskId: row.parentTaskId } : {}),
+                ...(row.parentSessionId !== undefined ? { rowParentSessionId: row.parentSessionId } : {}),
+                ...(row.rootSessionId !== undefined ? { rowRootSessionId: row.rootSessionId } : {}),
+                ...(opts.notify ? { currentParentNotify: opts.notify } : {}),
+            });
+            const summary = typeof a.summary === "string" && a.summary.trim() !== "" ? a.summary.trim().slice(0, 200) : undefined;
+            const fromPrefix = ctx.parentTaskId !== undefined ? `(message from teammate "${opts.senderName ?? senderId ?? "unknown"}")\n` : "";
+            try {
+                const marker = await resume(`${fromPrefix}${summary ? `[${summary}] ${message}` : message}`);
+                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 } : {}) },
+                };
+            }
+            catch (e) {
+                const code = e?.code;
+                const text = code === "resume.retain_off"
+                    ? `${who}'s session was not retained (retainSubagentSessions is off) — relaunch a new agent instead.`
+                    : code === "resume.evicted"
+                        ? `${who}'s retained session was evicted (retain TTL / capacity / parent run ended) — relaunch a new agent instead.`
+                        : code === "resume.session_not_found"
+                            ? `${who}'s session no longer exists — relaunch a new agent instead.`
+                            : code === "resume.cap"
+                                ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
+                                : code === "steering.still_running"
+                                    ? `${who} (or a prior follow-up to it) is still running — wait for its completion notification.`
+                                    : code === "resume.row_gone"
+                                        ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
+                                        : `${e instanceof Error ? e.message : String(e)}`;
+                return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
+            }
+        },
+    });
+}

package/dist/agents/subagent.d.ts

@@ -1,9 +1,14 @@
-import { Type } from "typebox";
 import type { Runner } from "../core/runner/runtask.js";
-import type { AgentDefinition, Model, ModelRef, TaskSpec, ToolSpec } from "../core/types.js";
+import type { AgentDefinition, Model, ModelRef, ToolSpec } from "../core/types.js";
 import { type ExecutionEnv } from "../internal/harness.js";
 import type { RunInternals } from "../core/runner/prepare-task.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
+import { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
+export { FORK_DEFAULT_MAX_TURNS, SESSION_BG_DEFAULT_TIMEOUT_SEC, RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX };
+import { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger, type SubagentRetainEntry } from "./retain-ledger.js";
+export { SubagentRetainLedger, getSessionRetainLedger, releaseSessionRetainLedger, type SubagentRetainEntry };
+export { AGENT_TRANSCRIPT_TOOL_NAME, createAgentTranscriptTool, type AgentTranscriptToolOptions } from "./agent-transcript-tool.js";
+export { SEND_MESSAGE_TOOL_NAME, createSendMessageTool, type SendMessageToolOptions } from "./send-message-tool.js";
 export type { SubagentStep, SubagentEditedFile } from "./subagent-steps.js";
 export declare function notifyResultField(result: string | undefined): string | undefined;
 export declare function inheritedManifestScopeFor(snapshot: readonly unknown[] | undefined): RunInternals["inheritedManifestScope"];
@@ -23,7 +28,6 @@ export interface SubagentToolStats {
 }
 export declare const FORK_SUBAGENT_TYPE = "fork";
 export declare const GENERAL_PURPOSE_SUBAGENT_TYPE = "general-purpose";
-export declare const FORK_DEFAULT_MAX_TURNS = 200;
 export declare function forkGovernanceDenial(enableFork: boolean | undefined, allowFork: boolean | undefined): "task" | "principal" | undefined;
 export interface SubagentWorktreeIsolation {
     mint(childId: string): Promise<{
@@ -32,7 +36,7 @@ export interface SubagentWorktreeIsolation {
     finish(worktreeDir: string): Promise<"pruned" | "kept">;
 }
 export declare function createSubagentWorktreeHelper(baseEnv: ExecutionEnv, repoRoot: string): SubagentWorktreeIsolation;
-export declare const SESSION_BG_DEFAULT_TIMEOUT_SEC: number;
+export declare const REPORT_FIELD_MAX = 300;
 export type SubagentErrorKind = "rate_limit" | "overloaded" | "timeout" | "network" | "logic";
 export declare function classifySubagentError(child: {
     status: string;
@@ -50,60 +54,31 @@ export interface SubagentSteerHandle {
     childSessionId?: string;
     resume?: (content: string) => Promise<string>;
 }
-export declare const SUBAGENT_RESUME_CAP = 8;
-export declare const RETAIN_DEFAULT_TTL_MS: number;
-export declare const RETAIN_DEFAULT_MAX = 16;
-export interface SubagentRetainEntry {
-    childSessionId: string;
-    runner?: Runner;
-    agentName?: string;
-    ttlMs?: number;
-    specSnapshot: Readonly<TaskSpec>;
-    internalsSnapshot: RunInternals;
-    running: boolean;
-    settled: boolean;
-    settledAt: number;
-    resumeCount: number;
-    cycleSeq: number;
-    deferredNotify?: {
-        seq?: number;
-        cancel: () => void;
-        flush: () => void;
-    };
-    activeAbort?: AbortController;
-    release: () => Promise<void>;
-}
-export declare class SubagentRetainLedger {
-    readonly ttlMs: number;
-    readonly max: number;
-    private entries;
-    private evictedIds;
-    private ttlTimers;
-    private isDisposed;
-    constructor(config: true | {
-        ttlMs?: number;
-        max?: number;
-    });
-    private static readonly TOMBSTONES_MAX;
-    private tombstone;
-    private effectiveTtlMs;
-    get disposed(): boolean;
-    get size(): number;
-    get(parentToolCallId: string): SubagentRetainEntry | undefined;
-    wasEvicted(parentToolCallId: string): boolean;
-    sweepExpired(now?: number): void;
-    register(parentToolCallId: string, entry: Omit<SubagentRetainEntry, "running" | "settled" | "settledAt" | "resumeCount" | "cycleSeq" | "activeAbort" | "deferredNotify">): SubagentRetainEntry | undefined;
-    markSettled(parentToolCallId: string): void;
-    private armTtlTimer;
-    private clearTtlTimer;
-    private flushDeferredNotify;
-    abandon(parentToolCallId: string): void;
-    evict(parentToolCallId: string): Promise<void>;
-    disposeAll(): Promise<void>;
-}
-export declare function getSessionRetainLedger(sessionId: string): SubagentRetainLedger | undefined;
-export declare function releaseSessionRetainLedger(sessionId: string): Promise<void>;
-export declare function makeResumePrompt(marker: string, content: string): string;
+export declare function createSubagentResume(deps: {
+    ledger: SubagentRetainLedger | undefined;
+    parentToolCallId: string;
+    runner: Runner;
+    notify?: (n: TaskNotificationPayload, opts?: {
+        priority?: "now" | "next" | "later";
+    }) => void;
+    sink?: (handle: SubagentSteerHandle) => void;
+    registry?: import("../core/task-registry.js").TaskRegistry;
+    currentParentNotify?: (n: TaskNotificationPayload, opts?: {
+        priority?: "now" | "next" | "later";
+    }) => void;
+    taskId?: string;
+    taskAccess?: import("../core/task-registry.js").TaskAccess;
+    bgSink?: (event: import("../core/types.js").BackgroundChildEvent) => void;
+    sessionScoped?: boolean;
+    rowDescription?: string;
+    rowName?: string;
+    rowAgentType?: string;
+    rowOwner?: string;
+    rowScope?: string;
+    rowParentTaskId?: string;
+    rowParentSessionId?: string;
+    rowRootSessionId?: string;
+}): (content: string) => Promise<string>;
 export interface SubagentToolOptions {
     runner: Runner;
     background?: {
@@ -163,53 +138,3 @@ export declare function agentWhenToUseText(def: {
     whenToUse?: string;
     whenToUseLean?: string;
 }, lean?: boolean): string | undefined;
-export declare const SEND_MESSAGE_TOOL_NAME = "SendMessage";
-export interface SendMessageToolOptions {
-    runner: Runner;
-    registry: import("../core/task-registry.js").TaskRegistry;
-    retain?: SubagentRetainLedger;
-    owner?: string;
-    scope?: string;
-    sessionId?: string;
-    notify?: (n: TaskNotificationPayload, opts?: {
-        priority?: "now" | "next" | "later";
-    }) => void;
-    sink?: (handle: SubagentSteerHandle) => void;
-    uplink?: (n: TaskNotificationPayload, opts?: {
-        priority?: "now" | "next" | "later";
-    }) => void;
-    senderName?: string;
-    roster?: import("./roster-store.js").RosterStore;
-    siblingRetain?: SubagentRetainLedger;
-    onBackgroundChildEvent?: (event: import("../core/types.js").BackgroundChildEvent) => void;
-    agentStore?: import("../core/background-agent-store.js").BackgroundAgentStore;
-    mailbox?: import("../core/mailbox-store.js").MailboxStore;
-    reviveSpawn?: (req: {
-        row: import("../core/background-agent-store.js").BackgroundAgentRecord;
-        rev: number;
-        prompt: string;
-    }) => Promise<{
-        isError?: boolean;
-        content: string;
-        details?: unknown;
-    }>;
-}
-export declare function recordRosterSpawn(roster: import("./roster-store.js").RosterStore | undefined, entry: import("./roster-store.js").RosterEntry): void;
-export declare function createSendMessageTool(opts: SendMessageToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
-    to: Type.TString;
-    message: Type.TString;
-    summary: Type.TOptional<Type.TString>;
-}>, unknown>;
-export declare const AGENT_TRANSCRIPT_TOOL_NAME = "AgentTranscript";
-export interface AgentTranscriptToolOptions {
-    runner: Runner;
-    registry: import("../core/task-registry.js").TaskRegistry;
-    agentStore?: import("../core/background-agent-store.js").BackgroundAgentStore;
-    owner?: string;
-    scope?: string;
-    sessionId?: string;
-}
-export declare function createAgentTranscriptTool(opts: AgentTranscriptToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
-    id: Type.TString;
-    lastN: Type.TOptional<Type.TInteger>;
-}>, unknown>;