@sema-agent/core 7.55.0 → 7.57.0

package/dist/agents/peer-session-drain.js

@@ -1,4 +1,4 @@
-import { mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
+import { isMailboxDecisionFinal, mailboxCrossProcessMountVerdict, moveMailboxDecision } from "../core/mailbox-store.js";
 import { decodeEngineFrame, ENGINE_FRAME_CODEC_VERSION, renderTaskNotificationXml, taskNotificationDedupKey } from "../core/task-notification.js";
 import { createFrameSettlement, toolResultReceiptKey } from "../core/frame-settlement.js";
 import { PRINCIPAL_INBOX_HANDLE } from "./cross-session-ref.js";
@@ -7,7 +7,7 @@ import { deliverEngineNotice } from "../core/types.js";
 import { buildCrossSessionEnvelope, CrossSessionCodecError, encodePeerAddress } from "./cross-session-envelope.js";
 import { judgeCrossSessionInbound, principalInboundLayers, resolveCrossSessionInboundSetting } from "./cross-session-judge.js";
 import { judgePeerAdmission, peerAxisToken, resolvePeerLaneConfig } from "./peer-admission.js";
-import { isPeerSessionId, PEER_SESSION_ID_GRAMMAR, peerSessionBoxHandle } from "./peer-directory.js";
+import { isPeerSessionId, listPeerDirectory, PEER_SESSION_ID_GRAMMAR, peerSessionBoxHandle } from "./peer-directory.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { createListAgentsTool, LIST_AGENTS_TOOL_ALIAS, LIST_AGENTS_TOOL_NAME } from "./list-agents-tool.js";
 import { foldPermissionModeClass } from "./cross-session-judge.js";
@@ -161,7 +161,7 @@ export function createPeerSessionDrain(opts) {
         ...(live
             ? {
                 inject: (entry) => {
-                    if (currentRound === undefined)
+                    if (currentRound === undefined || !currentRound.holds(lane))
                         return "deferred";
                     const payload = buildPeerMessagePayload(lane, entry);
                     if (currentRound.deliver(payload, "next") === "deferred")
@@ -169,9 +169,13 @@ export function createPeerSessionDrain(opts) {
                     noteDelivered(lane, entry.seq, 1, payload, currentRound.carrier);
                     return undefined;
                 },
+                canInject: () => currentRound !== undefined && currentRound.holds(lane) && !currentRound.spent,
             }
             : {}),
         receipt: receipt(lane),
+        tellsSender: (entry) => receiptAddress(lane, entry) !== undefined,
+        decide: (entry, expect, next) => moveMailboxDecision(mailbox, scope, lane.boxHandle, entry.seq, expect, next),
+        onFault: (entry, e) => opts.onError?.(e, { phase: "degraded", sessionId, classification: `peer-decision-move:${entry.box}#${entry.seq}` }),
         onHeld: (entry, count, cause, reannounce) => {
             if (!reannounce && lane.disclosedHeld.has(entry.seq))
                 return;
@@ -179,12 +183,13 @@ export function createPeerSessionDrain(opts) {
             disclose(lane, "held", cause, entry, reannounce ? `still held; its cause moved to ${cause} (${count} held)` : undefined);
         },
         onSettled: (entry, settlement, reason, count) => {
-            if (entry.box === lane.boxHandle && settlement !== "delivered")
+            if (entry.box === lane.boxHandle && settlement !== "delivered" && settlement !== "retired")
                 lane.ledger.set(entry.seq, { kind: "terminal", why: `held_${settlement}` });
             const replyTo = receiptAddress(lane, entry);
+            const told = reason !== "decided_elsewhere" && settlement !== "retired" && replyTo !== undefined;
             deliverEngineNotice(opts.onNotice, {
                 code: "peer.held_settled",
-                message: `held cross-session message seq ${entry.seq} left this session's held queue: ${settlement} (${reason}); ${count} still held${settlement === "expired" && reason === "evicted" ? " — the held queue was full, so the oldest entry was expired to make room" : ""}. The sender ${replyTo !== undefined ? "was sent a receipt" : "has no reply address and was not told"}.`,
+                message: `held cross-session message seq ${entry.seq} left this session's held queue: ${settlement} (${reason}); ${count} still held${settlement === "expired" && reason === "evicted" ? " — the held queue was full, so the oldest entry was expired to make room" : ""}${settlement === "retired" ? (reason === "superseded" ? " — its record is no longer in the box (another consumer settled it); nothing was decided here" : " — no decision was taken: it stays held in the box, and the next drain presents it again") : ""}${reason === "decided_elsewhere" ? " — another consumer of the box decided it first" : ""}. The sender ${told ? "was sent a receipt" : replyTo !== undefined ? "was not sent a receipt from here" : "has no reply address and was not told"}.`,
                 detail: { settlement, reason, seq: entry.seq, box: lane.boxHandle, ...(entry.peerMeta?.fromSession !== undefined ? { fromSession: entry.peerMeta.fromSession } : {}), heldCount: count, sessionId, runId },
             });
         },
@@ -216,28 +221,29 @@ export function createPeerSessionDrain(opts) {
     idleMachine.requester.configure({
         expired: (o) => void routePeerIdleNotice(route(), sessionId, { kind: "expired", label: o.label }),
     });
-    const adoptHeldDecisions = (lane) => {
-        const decided = lane.held.decisions();
-        if (decided.size === 0)
-            return;
-        for (const [seq, settlement] of decided) {
-            if (lane.ackedUpTo !== undefined && seq <= lane.ackedUpTo)
-                continue;
-            const mine = lane.ledger.get(seq);
-            if (mine !== undefined && mine.kind !== "held")
-                continue;
-            lane.ledger.set(seq, { kind: "terminal", why: `held_${settlement}` });
+    const reconcileHeld = (lane, lease) => {
+        const live = lease.messages.filter((m) => lane.ackedUpTo === undefined || m.seq > lane.ackedUpTo);
+        lane.held.reconcile(new Map(live.map((m) => [m.seq, m.decision])));
+        adoptFinalDecisions(lane, lease);
+        for (const m of live) {
+            const d = lane.ledger.get(m.seq);
+            if (lane.held.has(m.seq)) {
+                if (d === undefined)
+                    lane.ledger.set(m.seq, { kind: "held" });
+            }
+            else if (d?.kind === "held")
+                lane.ledger.delete(m.seq);
         }
     };
-    const reconcileHeld = (lane, lease) => {
-        lane.held.reconcile(new Set(lease.messages.map((m) => m.seq)));
-        let queued;
-        for (const [seq, d] of lane.ledger) {
-            if (d.kind !== "held")
+    const adoptFinalDecisions = (lane, lease) => {
+        for (const m of lease.messages) {
+            if (lane.ackedUpTo !== undefined && m.seq <= lane.ackedUpTo)
                 continue;
-            queued ??= new Set(lane.held.list().filter((e) => e.box === lane.boxHandle).map((e) => e.seq));
-            if (!queued.has(seq))
-                lane.ledger.delete(seq);
+            if (!isMailboxDecisionFinal(m.decision))
+                continue;
+            const d = lane.ledger.get(m.seq);
+            if (d === undefined || d.kind === "held" || d.kind === "invalidated")
+                lane.ledger.set(m.seq, { kind: "terminal", why: `held_${m.decision}` });
         }
     };
     const wantsCompactionEffects = () => {
@@ -280,7 +286,6 @@ export function createPeerSessionDrain(opts) {
     };
     const settleLaneLocally = (lane, landed) => {
         const { ledger, boxHandle } = lane;
-        adoptHeldDecisions(lane);
         const hostWithheldSeqs = [];
         if (seam.receipts.size > 0 || seam.withheld.size > 0 || seam.hostWithheld.size > 0) {
             for (const [seq, d] of ledger) {
@@ -326,26 +331,17 @@ export function createPeerSessionDrain(opts) {
         }
     };
     const ackSettledPrefix = async (lane, lease) => {
-        const { held, ledger, boxHandle } = lane;
-        const decided = held.decisions();
-        if (decided.size > 0) {
-            const live = new Set(lease.messages.map((m) => m.seq));
-            held.forgetDecisions([...decided.keys()].filter((seq) => !live.has(seq)));
-        }
+        const { ledger, boxHandle } = lane;
+        adoptFinalDecisions(lane, lease);
         const prefix = deriveAckPrefix(lane, lease.messages);
         if (prefix !== undefined && (lane.ackedUpTo === undefined || prefix > lane.ackedUpTo)) {
             try {
                 const result = await mailbox.ack(scope, boxHandle, drainOwner, prefix);
                 if (result.acked) {
                     lane.ackedUpTo = prefix;
-                    const gone = [];
-                    for (const seq of [...ledger.keys()]) {
-                        if (seq > prefix)
-                            continue;
-                        gone.push(seq);
-                        ledger.delete(seq);
-                    }
-                    held.forgetDecisions(gone);
+                    for (const seq of [...ledger.keys()])
+                        if (seq <= prefix)
+                            ledger.delete(seq);
                 }
                 else {
                     opts.onError?.(new Error(`the ${lane.kind === "session" ? "session box" : "principal inbox"} ${boxHandle} refused this leg's ack up to seq ${prefix}: the drain lease is no longer held by ${drainOwner} (it expired and another cycle claimed it). The records stay parked and the lease holder re-serves them.`), { phase: "degraded", sessionId, classification: "peer-box-ack" });
@@ -451,6 +447,13 @@ export function createPeerSessionDrain(opts) {
             lane.ledger.set(seq, { kind: "terminal", why });
         }
         batch = [];
+        leasedLanes = new Set();
+        lease(lanes) {
+            this.leasedLanes = new Set(lanes);
+        }
+        holds(lane) {
+            return this.leasedLanes.has(lane);
+        }
         chars = 0;
         constructor(limit, out, carrier, charBudget) {
             this.limit = limit;
@@ -527,15 +530,17 @@ export function createPeerSessionDrain(opts) {
             const leased = claims.filter((c) => c.lease !== null);
             if (leased.length === 0)
                 return { pending: 0, urgent: 0 };
+            round.lease(leased.map((c) => c.lane));
             for (const { lane, lease } of leased) {
                 bindHeld(lane, true);
                 reconcileHeld(lane, lease);
-                lane.held.rejudge();
+                await lane.held.rejudge();
             }
             try {
                 for (const { lane, lease } of leased) {
                     const { ledger, disclosedHeld, held, boxHandle } = lane;
                     const ackedUpTo = lane.ackedUpTo;
+                    let adoptedThisPass = false;
                     for (const m of lease.messages) {
                         const prior = ledger.get(m.seq);
                         if (prior === undefined || prior.kind !== "invalidated")
@@ -545,7 +550,6 @@ export function createPeerSessionDrain(opts) {
                         const attempt = prior.attempt + 1;
                         round.batch.push({ lane, payload: { ...prior.payload, attempt, resupplied: true }, priority: "next", urgent: false, seq: m.seq, attempt });
                     }
-                    adoptHeldDecisions(lane);
                     for (const m of lease.messages) {
                         if (ackedUpTo !== undefined && m.seq <= ackedUpTo)
                             continue;
@@ -597,15 +601,29 @@ export function createPeerSessionDrain(opts) {
                             continue;
                         }
                         const sameTree = meta?.fromRoot !== undefined && meta.fromRoot.toLowerCase() === sessionId.toLowerCase();
+                        const known = m.decision;
                         if (!sameTree) {
                             const judged = judgeMeta(facts, meta);
-                            if (judged.verdict === "refuse") {
+                            const shown = known === "held" || known === "approved";
+                            if (!shown && judged.verdict === "refuse") {
                                 disclose(lane, "refused", judged.cause, m);
                                 round.dispose(lane, m.seq, `refused:${judged.cause}`);
                                 continue;
                             }
-                            if (judged.verdict === "hold") {
-                                held.hold({ seq: m.seq, box: boxHandle, content: m.content, ...(m.from !== undefined ? { from: m.from } : {}), sentAt: m.sentAt, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}), ...(meta !== undefined ? { peerMeta: { ...meta } } : {}), cause: judged.cause });
+                            if (shown || (judged.verdict === "hold" && known !== "delivered")) {
+                                const outcome = await held.hold({ seq: m.seq, box: boxHandle, content: m.content, ...(m.from !== undefined ? { from: m.from } : {}), sentAt: m.sentAt, ...(m.hopChain !== undefined ? { hopChain: [...m.hopChain] } : {}), ...(meta !== undefined ? { peerMeta: { ...meta } } : {}), cause: judged.verdict === "hold" ? judged.cause : "explicit-setting" }, shown ? known : undefined);
+                                if (outcome === "gone" || outcome === "fault")
+                                    continue;
+                                if (outcome !== "held" && outcome !== "adopted" && outcome !== "uncarded") {
+                                    round.dispose(lane, m.seq, `held_${outcome}`);
+                                    continue;
+                                }
+                                if (shown && outcome === "adopted")
+                                    adoptedThisPass = true;
+                                if (outcome === "uncarded" && !disclosedHeld.has(m.seq)) {
+                                    disclosedHeld.add(m.seq);
+                                    disclose(lane, "held", judged.verdict === "hold" ? judged.cause : "explicit-setting", m, "it is held in the box, but this session's held queue is full; it is shown when a card frees");
+                                }
                                 if (!ledger.has(m.seq))
                                     ledger.set(m.seq, { kind: "held" });
                                 continue;
@@ -622,6 +640,8 @@ export function createPeerSessionDrain(opts) {
                         }
                         round.batch.push({ lane, payload, priority: "next", urgent: meta?.urgent === true, seq: m.seq, attempt: 1 });
                     }
+                    if (adoptedThisPass)
+                        await held.rejudge();
                 }
             }
             finally {
@@ -830,7 +850,7 @@ export function bindPeerLaneDrain(harness, args) {
         if (deps.peerDirectory === undefined)
             return;
         try {
-            const rows = await deps.peerDirectory.listPeerSessions({ scope: args.scope });
+            const rows = await listPeerDirectory(deps.peerDirectory, { scope: args.scope });
             rowName = rows.find((r) => r.sessionId.toLowerCase() === args.sessionId.toLowerCase())?.name;
         }
         catch {

package/dist/agents/repair-loop.js

@@ -48,7 +48,7 @@ export async function runRepairLoop(runner, implSpec, config) {
         const oracle = { tier: "none", passed: false, flaky: false, retries: 0 };
         return {
             taskId: implSpec.taskId ?? "",
-            result: `oracle isolation check failed: ${reason}`,
+            result: `oracle isolation check failed: ${reason}`, resultEntryIds: [],
             terminal: { kind: "failed", code: "oracle.unprotected", message: `oracle isolation check failed: ${reason}` },
             sessionId: "",
             stats: { tokens: 0, turns: 0, costMicroUsd: 0 },
@@ -160,7 +160,7 @@ export async function runRepairLoop(runner, implSpec, config) {
     };
     const exhaustedBeforeDispatch = (message, errorCode) => ({
         taskId: implSpec.taskId ?? "",
-        result: message ?? `repair loop: attempt budget already spent (attemptCount ${bundle.attemptCount} >= maxAttempts ${maxAttempts}) — no attempt dispatched`,
+        result: message ?? `repair loop: attempt budget already spent (attemptCount ${bundle.attemptCount} >= maxAttempts ${maxAttempts}) — no attempt dispatched`, resultEntryIds: [],
         terminal: { kind: "failed", code: errorCode ?? "repair.attempts_exhausted", message: message ?? `repair loop: attempt budget already spent (attemptCount ${bundle.attemptCount} >= maxAttempts ${maxAttempts}) — no attempt dispatched` },
         sessionId: implSpec.sessionId ?? "",
         stats: { tokens: 0, turns: 0, costMicroUsd: 0 },

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

@@ -1,12 +1,12 @@
 import { Type } from "typebox";
 import { isNotificationInjectionOutcome } from "../core/task-notification.js";
 import { defineTool } from "../core/tools.js";
-import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
+import { normalizeAgentName, chosenAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
 import { announceTranscriptIntegrityGapOnce, canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/background-agent-store.js";
 import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE, mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
 import { peerSendVerdictSeverity } from "./cross-session-judge.js";
-import { parsePeerSessionAddress, peerSessionBoxHandle, peerSessionLane, resolvePeerSessions } from "./peer-directory.js";
+import { listPeerDirectory, parsePeerSessionAddress, peerSessionBoxHandle, peerSessionLane, resolvePeerSessions } from "./peer-directory.js";
 import { peerIdleMachineFor } from "./peer-idle.js";
 import { PEER_IDLE_OUTSTANDING_CAP, PEER_IDLE_SUBSCRIPTION_TTL_MS, peerIdleNoticeLabel } from "./peer-notices.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
@@ -263,7 +263,7 @@ export function createSendMessageTool(opts) {
             let ownRowName;
             const resolvePeerTarget = async () => {
                 try {
-                    const rows = await opts.peerDirectory.listPeerSessions({ scope: peerScope ?? "" });
+                    const rows = await listPeerDirectory(opts.peerDirectory, { scope: peerScope ?? "" });
                     if (peerSelfSessionId !== undefined)
                         ownRowName = rows.find((r) => r.sessionId.toLowerCase() === peerSelfSessionId.toLowerCase())?.name;
                     return resolvePeerSessions(rows, to, peerSelfSessionId !== undefined ? { sessionId: peerSelfSessionId } : undefined);
@@ -349,7 +349,7 @@ export function createSendMessageTool(opts) {
                 const doorbell = opts.peerChannel !== undefined && record.sockPath !== undefined && record.liveness === "live" && (seq !== undefined || subscriptionSeq !== undefined) ? await opts.peerChannel.nudge(record.sockPath).catch(() => false) : undefined;
                 let rowRestored = "present";
                 try {
-                    const rowsNow = await opts.peerDirectory.listPeerSessions({ scope: peerScope });
+                    const rowsNow = await listPeerDirectory(opts.peerDirectory, { scope: peerScope });
                     const nowRow = rowsNow.find((r) => r.sessionId.toLowerCase() === record.sessionId.toLowerCase());
                     if (nowRow?.liveness === "deleted")
                         rowRestored = "deleted_meanwhile";
@@ -906,7 +906,7 @@ export function createSendMessageTool(opts) {
                             (suggestion !== undefined ? ` Did you mean: ${suggestion}?` : "") +
                             (labels.length > 0 ? ` Running background agents: ${labels.join(", ")}.` : "") +
                             ` Reachable from here: ${reachable.join("; ").slice(0, 300)}.` +
-                            ` 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.`,
+                            ` Note: a completed foreground agent is not addressable (nothing retains its transcript) — name an agent or run it in the background to keep it addressable (a named agent always runs in the background), or launch a new agent.`,
                         details: { error: "not_found", to, ...(suggestion !== undefined ? { suggestion } : {}) },
                         isError: true,
                     };
@@ -1041,6 +1041,7 @@ export function createSendMessageTool(opts) {
                 if (!l3Verdict.ok)
                     return admissionRefusal(l3Verdict.reason, who);
                 assertParentSpecSeatCurrent(ctx.parentSpecSeat);
+                const chosenRowName = chosenAgentName(targetId, row.name);
                 const resume = createSubagentResume({
                     ledger,
                     parentToolCallId: resumeToolUseId,
@@ -1055,7 +1056,7 @@ export function createSendMessageTool(opts) {
                     ...((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 } : {}),
+                    ...(chosenRowName !== undefined ? { rowName: chosenRowName } : {}),
                     ...(row.agentType !== undefined ? { rowAgentType: row.agentType } : {}),
                     ...(row.owner !== undefined ? { rowOwner: row.owner } : {}),
                     ...(row.scope !== undefined ? { rowScope: row.scope } : {}),

package/dist/agents/subagent.d.ts

@@ -168,9 +168,6 @@ export interface SubagentWorktreeIsolation {
     /** CC "auto-cleaned if unchanged": remove the worktree when clean, keep it when the child made changes. */
     finish(worktreeDir: string): Promise<"pruned" | "kept">;
 }
-/** Is `result` one of the delegation tool's refusals before any child ran ({@link notStartedResult})? The brand only: the identity
- *  of its `details` object, never what the result says. */
-export declare function isNotStartedDelegationResult(result: unknown): boolean;
 /**
  * Build the {@link SubagentWorktreeIsolation} helper over a base env + repo root. Called by `prepare-task`
  * (closure over the run's ExecutionEnv/taskRootPath — trusted, mirrors the scheduler/fork mounts). The
@@ -672,10 +669,15 @@ export interface SubagentToolOptions {
     allowTools?: string[];
     /** Tool-level denylist (design/38 1A), used when no `agent` is selected: the denied half of the child's own selector layer (a deny wins). */
     denyTools?: string[];
-    /** System prompt / persona for the child. Default (since 1.259.0): the LEAN
+    /** System prompt / persona for the child, by TEXT — the child's own role-base statement, written on its task seat (an
+     *  agent definition's `systemPrompt` wins over it). Default (since 1.259.0): the LEAN
      *  {@link SUBAGENT_PROMPT} (agent persona + return contract), NOT the full default constitution role
      *  base — pass `DEFAULT_SYSTEM_PROMPT` here explicitly to restore the pre-1.259 behavior. */
     systemPrompt?: string;
+    /** The child's role base by WORD (`TaskSpec.promptRole`'s closed set: `"code"` gives the children the catalog's coding
+     *  base): the same seat as {@link systemPrompt} (text beside it replaces the base this word selects) — so a role
+     *  preset never overtakes it. Outside the closed set ⇒ refused when the tool is built (`config.prompt_selector_invalid`). */
+    promptRole?: import("../prompt-assembly/catalog/schema.js").HostRole;
     /** Tool name exposed to the parent. Default "Agent". */
     name?: string;
     /** What the child is for (shown to the parent in the tool description). */