@sema-agent/core 7.1.0 → 7.3.0

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

@@ -0,0 +1,245 @@
+import { mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
+import { deliverEngineNotice } from "../core/types.js";
+import { buildCrossSessionEnvelope, CrossSessionCodecError, encodePeerAddress } from "./cross-session-envelope.js";
+import { judgeCrossSessionInbound, resolveCrossSessionInboundSetting } from "./cross-session-judge.js";
+import { judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig } from "./peer-admission.js";
+import { isPeerSessionId, 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";
+export const PEER_DRAIN_LEASE_TTL_MS = 5 * 60_000;
+export const PEER_SESSION_ID_UNGRAMMATICAL_CODE = "peer.session_id_ungrammatical";
+export function judgePeerLaneMount(deps, sessionId) {
+    if (deps.peerDirectory === undefined)
+        return undefined;
+    if (deps.mailboxStore === undefined) {
+        return { ok: false, code: "mailbox.cross_process_unsafe", reason: "RunnerDeps.peerDirectory is wired but RunnerDeps.mailboxStore is not — the cross-session lane parks messages in the recipient's durable session box and has no store to park them in" };
+    }
+    const store = mailboxCrossProcessMountVerdict(deps.mailboxStore);
+    if (!store.ok)
+        return store;
+    if (sessionId !== undefined && !isPeerSessionId(sessionId)) {
+        return {
+            ok: false,
+            code: PEER_SESSION_ID_UNGRAMMATICAL_CODE,
+            reason: `this run's session id ${JSON.stringify(inlineUntrusted(sessionId, 96))} is outside the peer address grammar ${PEER_SESSION_ID_GRAMMAR} — it has no session box to drain and no address a peer could send to (mint session ids the grammar accepts to use the lane)`,
+        };
+    }
+    return { ok: true };
+}
+export function createPeerSessionDrain(opts) {
+    const { mailbox, sessionId, runId, scope } = opts;
+    const boxHandle = peerSessionBoxHandle(sessionId);
+    const drainOwner = `drain:${runId}`;
+    const recipientKey = peerAxisToken(scope, "s", sessionId);
+    const ttl = opts.leaseTtlMs ?? PEER_DRAIN_LEASE_TTL_MS;
+    let settledUpTo;
+    const disclosedHeld = new Set();
+    let inFlight = Promise.resolve();
+    const disclose = (disposition, cause, m, heldNote = "the held-message review face is not mounted in this build") => deliverEngineNotice(opts.onNotice, {
+        code: "peer.inbound_disposition",
+        message: `cross-session message seq ${m.seq} in this session's box was ${disposition === "held" ? `HELD (it stays parked; ${heldNote})` : disposition === "refused" ? "refused by this session's crossSessionInbound setting" : disposition === "notice_unrouted" ? "settled WITHOUT delivery (a notice-kind record; the notice face is not mounted in this build)" : "refused by the inbound admission gate"}: ${cause}`,
+        detail: { disposition, cause, seq: m.seq, box: boxHandle, ...(m.peerMeta?.fromSession !== undefined ? { fromSession: m.peerMeta.fromSession } : {}), sessionId, runId },
+    });
+    const ackSettled = async () => {
+        if (settledUpTo === undefined)
+            return;
+        const upTo = settledUpTo;
+        settledUpTo = undefined;
+        try {
+            await mailbox.ack(scope, boxHandle, drainOwner, upTo);
+        }
+        catch (e) {
+            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-ack" });
+        }
+    };
+    const drainOnce = async () => {
+        let lease;
+        try {
+            lease = await mailbox.claimLease(scope, boxHandle, drainOwner, ttl);
+        }
+        catch (e) {
+            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
+            return;
+        }
+        const previouslySettled = settledUpTo;
+        await ackSettled();
+        if (lease === null)
+            return;
+        let setting;
+        let admissionConfig;
+        let selfModeClass;
+        try {
+            setting = resolveCrossSessionInboundSetting(opts.settingLayers() ?? {});
+            admissionConfig = resolvePeerAdmissionConfig(opts.admission);
+            selfModeClass = opts.selfModeClass();
+        }
+        catch (e) {
+            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-settings" });
+            return;
+        }
+        for (const m of lease.messages) {
+            if (previouslySettled !== undefined && m.seq <= previouslySettled)
+                continue;
+            const meta = m.peerMeta;
+            if (m.hopChain !== undefined) {
+                const verdict = judgePeerAdmission(scope, recipientKey, { senderKey: meta?.senderKey, body: m.content, prospectiveChain: m.hopChain, ownTokens: opts.ownTokens(), seq: m.seq }, admissionConfig, undefined, "drain");
+                if (!verdict.ok) {
+                    if (verdict.reason === "rate_limited") {
+                        if (!disclosedHeld.has(m.seq)) {
+                            disclosedHeld.add(m.seq);
+                            disclose("held", verdict.reason, m, "the inbound admission bucket is empty; it is re-judged at a later boundary once the bucket refills");
+                        }
+                        break;
+                    }
+                    disclose("admission_refused", verdict.reason, m);
+                    settledUpTo = m.seq;
+                    continue;
+                }
+            }
+            if (meta?.kind !== undefined && meta.kind !== "peer_message") {
+                disclose("notice_unrouted", `kind=${meta.kind}`, m);
+                settledUpTo = m.seq;
+                continue;
+            }
+            {
+                const judged = judgeCrossSessionInbound({ setting, selfModeClass, sender: { ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: meta?.fromSession !== undefined && meta.fromSession.toLowerCase() === sessionId.toLowerCase() } });
+                if (judged.verdict === "refuse") {
+                    disclose("refused", judged.cause, m);
+                    settledUpTo = m.seq;
+                    continue;
+                }
+                if (judged.verdict === "hold") {
+                    if (!disclosedHeld.has(m.seq)) {
+                        disclosedHeld.add(m.seq);
+                        disclose("held", `${judged.cause}: ${judged.message}${judged.warning !== undefined ? ` (${judged.warning})` : ""}`, m);
+                    }
+                    break;
+                }
+            }
+            let fields;
+            try {
+                fields = {
+                    from: encodePeerAddress(meta?.fromSession !== undefined ? peerSessionBoxHandle(meta.fromSession) : (m.from ?? "unknown")),
+                    ...(meta?.fromSession !== undefined ? { fromSession: meta.fromSession } : {}),
+                    ...(m.from !== undefined ? { fromName: m.from } : {}),
+                    ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}),
+                    ...(meta?.fromScope !== undefined ? { fromScope: meta.fromScope } : {}),
+                };
+                buildCrossSessionEnvelope(fields, m.content);
+            }
+            catch (e) {
+                disclose("refused", `record fields cannot be rendered canonically (${e instanceof CrossSessionCodecError ? e.code : e instanceof Error ? e.message : String(e)})`, m);
+                settledUpTo = m.seq;
+                continue;
+            }
+            const payload = {
+                task_id: boxHandle,
+                task_type: "background_agent",
+                status: "event",
+                summary: `cross-session message from ${m.from ?? fields.from}`,
+                result: m.content,
+                seq: m.seq,
+                peer: { hopChain: m.hopChain !== undefined ? [...m.hopChain] : [] },
+                crossSessionMessage: { ...fields, body: m.content },
+                _sema_provenance: { kind: "cross_session_message", from: fields.from, taskId: boxHandle, seq: m.seq, ...(meta !== undefined ? { peerMeta: { ...meta } } : {}) },
+            };
+            try {
+                opts.inject(payload, { priority: "next" });
+            }
+            catch (e) {
+                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
+                break;
+            }
+            settledUpTo = m.seq;
+        }
+    };
+    const drain = () => {
+        inFlight = inFlight.then(drainOnce, drainOnce);
+        return inFlight;
+    };
+    const finishOnce = async () => {
+        await ackSettled();
+        try {
+            await mailbox.releaseLease(scope, boxHandle, drainOwner);
+        }
+        catch {
+        }
+    };
+    const finish = () => {
+        inFlight = inFlight.then(finishOnce, finishOnce);
+        return inFlight;
+    };
+    return { drain, finish };
+}
+export function announcePeerLaneMount(deps, leg) {
+    const verdict = judgePeerLaneMount(deps, leg.sessionId);
+    if (verdict === undefined)
+        return false;
+    if (verdict.ok)
+        return true;
+    deliverEngineNotice(deps.onNotice, {
+        code: "config.peer_lane_unmounted",
+        message: `Cross-session lane NOT mounted for this run: ${verdict.reason}. ListAgents is not mounted and peer-session addresses refuse with that reason${verdict.code === PEER_SESSION_ID_UNGRAMMATICAL_CODE ? "." : "; wire a mailbox store that declares crossProcessSafe: true (the bundled FileMailboxStore does)."}`,
+        detail: { reason: verdict.reason, code: verdict.code, mailboxWired: deps.mailboxStore !== undefined, sessionId: leg.sessionId, runId: leg.runId },
+    });
+    return false;
+}
+export function peerLaneSendMessageSeats(args) {
+    return {
+        peerDirectory: args.peerDirectory,
+        ...(args.listingMounted !== undefined ? { peerListingMounted: args.listingMounted } : {}),
+        peerSelfSession: {
+            sessionId: args.sessionId,
+            scope: args.scope,
+            ...(args.name !== undefined ? { name: args.name } : {}),
+            modeClass: () => (args.refs.askEffective !== undefined ? foldPermissionModeClass(args.refs.askEffective) : "unknown"),
+        },
+    };
+}
+export function listAgentsMountable(face) {
+    if ((face.exclude ?? []).includes(LIST_AGENTS_TOOL_NAME))
+        return false;
+    return !face.specTools.some((t) => t.name === LIST_AGENTS_TOOL_NAME || t.name === LIST_AGENTS_TOOL_ALIAS || t.aliases?.includes(LIST_AGENTS_TOOL_NAME) || t.aliases?.includes(LIST_AGENTS_TOOL_ALIAS));
+}
+export function mountListAgents(args) {
+    if (!listAgentsMountable({ exclude: undefined, specTools: args.specTools }))
+        return undefined;
+    args.toolEffects.set(LIST_AGENTS_TOOL_NAME, "read");
+    args.toolEffects.set(LIST_AGENTS_TOOL_ALIAS, "read");
+    return createListAgentsTool({
+        peerDirectory: args.peerDirectory,
+        self: { sessionId: args.sessionId, scope: args.scope },
+        registry: args.registry,
+        access: { owner: args.hostTaskId, scope: args.scope, sessionId: args.sessionId },
+        ...(args.parentTaskId !== undefined ? { parentAccess: { owner: args.parentTaskId, scope: args.scope, ...(args.parentSessionId !== undefined ? { sessionId: args.parentSessionId } : {}) } } : {}),
+        ...(args.roster !== undefined ? { roster: args.roster } : {}),
+    });
+}
+export function bindPeerSessionDrain(harness, opts) {
+    const drain = createPeerSessionDrain(opts);
+    const round = async () => {
+        await drain.drain();
+        return undefined;
+    };
+    harness.on("before_agent_start", round);
+    harness.on("turn_boundary", round);
+    harness.subscribe((event) => (event.type === "agent_end" ? drain.finish().catch(() => undefined) : undefined));
+    return drain;
+}
+export function bindPeerLaneDrain(harness, args) {
+    const { deps } = args;
+    return bindPeerSessionDrain(harness, {
+        mailbox: deps.mailboxStore,
+        sessionId: args.sessionId,
+        runId: args.runId,
+        scope: args.scope,
+        inject: args.inject,
+        ...(deps.peerAdmission !== undefined ? { admission: deps.peerAdmission } : {}),
+        ownTokens: args.ownTokens,
+        settingLayers: () => (typeof deps.crossSessionInbound === "function" ? deps.crossSessionInbound() : deps.crossSessionInbound),
+        selfModeClass: () => (args.refs.askEffective !== undefined ? foldPermissionModeClass(args.refs.askEffective) : "unknown"),
+        ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
+        ...(deps.onError !== undefined ? { onError: deps.onError } : {}),
+    });
+}

package/dist/agents/send-message-tool.d.ts

@@ -3,6 +3,8 @@ import type { Runner } from "../core/runner/runtask.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { type ToolCtxEnricher } from "../core/tools.js";
 import { type TaskAccess } from "../core/task-registry.js";
+import type { PermissionModeClass } from "./cross-session-envelope.js";
+import { type PeerDirectory } from "./peer-directory.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 import { type PeerAdmissionConfig, type PeerInboundChainRef, type PeerSelfRef } from "./peer-admission.js";
@@ -44,6 +46,19 @@ export interface SendMessageToolOptions {
      *  this run's process exits when the turn ends, so no completion notification can ever land — checked
      *  AHEAD of {@link notificationWired}, since no amount of wiring makes a later turn exist. */
     oneShot?: boolean;
+    /**
+     * Whether a RETRIEVAL tool (`TaskOutput`) is mounted beside this tool on the same face. Every
+     * degraded completion promise on this face (the one-shot and silent arms of the description and
+     * the receipt/refusal texts) tells the model how to collect a continued agent's result; naming
+     * `TaskOutput(task_id, block: true)` as an imperative is only true where that tool exists. Since
+     * design/385 §1.5 this tool also mounts on the delegated-child arm WITHOUT the background door
+     * TaskOutput/TaskStop keep, so the two can no longer be assumed to travel together. Three states:
+     * `true` — the advice names TaskOutput plainly; `false` — this face has no retrieval tool, and the
+     * advice says the result cannot be collected by this run instead of naming a tool the model cannot
+     * call (an unknown-tool error on a one-shot run is the turn where the result is lost); absent — the
+     * mount did not say, and the advice is hedged ("where that tool is mounted").
+     */
+    retrievalToolMounted?: boolean;
     /** Steer-handle sink: the revived run re-emits a FRESH handle (design/122 risk-table contract). */
     sink?: (handle: SubagentSteerHandle) => void;
     /**
@@ -151,6 +166,35 @@ export interface SendMessageToolOptions {
      * per-call honest refusal is the only loudness (unchanged behavior).
      */
     onTranscriptIntegrityGap?: (handle: string, scope: string | undefined) => void;
+    /**
+     * design/385 §2 — the peer-session DIRECTORY ({@link import("../core/types.js").RunnerDeps.peerDirectory}):
+     * opens the cross-session lane's two rungs on this face — the explicit `session.<id>` address arm
+     * (ranked beside the precise a* id) and the LAST name rung (`name [ref]` over the directory's full
+     * set, after every agent rung missed). Needs {@link mailbox} beside it AND that store's
+     * `crossProcessSafe: true` declaration: with the directory wired but either missing, the lane stays
+     * closed and every peer-addressed send refuses with the named reason (never a silent fall-through to
+     * "no agent matches"). Absent ⇒ byte-identical pre-385 behavior.
+     */
+    peerDirectory?: PeerDirectory;
+    /**
+     * design/385 — THIS session's own identity on the cross-session lane: its session id (the sender's
+     * `from-session` / reply address, and the self-target guard), the scope its directory rows live in,
+     * its display name (the `from-name` attestation), and the live fold of its own permission-mode class
+     * ({@link import("./cross-session-judge.js").foldPermissionModeClass} over the wiring manifest's
+     * `ask.effective`) — read at SEND time, attested on the parked record's typed `peerMeta.fromMode`.
+     * The Runner mount fills it; a direct mount without it sends with no session attestation (the
+     * recipient then judges it as "no class asserted").
+     */
+    peerSelfSession?: {
+        sessionId: string;
+        scope?: string;
+        name?: string;
+        modeClass?: () => PermissionModeClass | "unknown";
+    };
+    /** design/385 §5.1 — is `ListAgents` mounted beside this tool? Drives the "list them with ListAgents"
+     *  phrase (a face never names a tool the roster does not carry — an `excludeTools` may drop one of the
+     *  pair). Absent = unknown ⇒ the phrase is hedged. */
+    peerListingMounted?: boolean;
 }
 /** RB-382 — max chars of the `summary` arg (the short recap label, distinct from `message`'s much
  *  larger {@link UPLINK_RESULT_MAX}) before ITS OWN truncation. Exported for direct unit-testing only

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

@@ -3,9 +3,12 @@ import { defineTool } from "../core/tools.js";
 import { normalizeAgentName, 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 } from "../core/mailbox-store.js";
+import { MAILBOX_TOMBSTONED_RECIPIENT_CODE, mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
+import { peerSendVerdictSeverity } from "./cross-session-judge.js";
+import { parsePeerSessionAddress, peerSessionBoxHandle, resolvePeerSessions } from "./peer-directory.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
+import { neutralizePeerBody } from "./cross-session-envelope.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig, PEER_MESSAGE_NOTICE, } from "./peer-admission.js";
@@ -24,10 +27,11 @@ export function clipSendMessageSummary(raw) {
 const TEAMMATE_MESSAGE_TAG = "teammate-message";
 function frameTeammateMessage(args) {
     const summaryAttr = args.summary !== undefined ? ` summary="${escapeAttributeValue(args.summary)}"` : "";
-    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, args.text);
+    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, neutralizePeerBody(args.text));
     return `<${TEAMMATE_MESSAGE_TAG} teammate_id="${escapeAttributeValue(args.from)}"${summaryAttr}>\n${body}\n</${TEAMMATE_MESSAGE_TAG}>`;
 }
 const REVIVE_LEASE_TTL_MS = 5 * 60_000;
+const PEER_REFUSAL_TEXT_MAX = 1200;
 const sendMessageTargetLanes = new Map();
 function withTargetLane(key, fn) {
     const prev = sendMessageTargetLanes.get(key) ?? Promise.resolve();
@@ -46,21 +50,44 @@ function targetLaneKey(scope, targetId) {
 const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    const peerLane = (() => {
+        if (opts.peerDirectory === undefined)
+            return { active: false };
+        if (opts.mailbox === undefined)
+            return { active: false, reason: "a peer-session directory is wired but no mailbox store is (the lane parks messages in the recipient's durable session box)" };
+        const verdict = mailboxCrossProcessMountVerdict(opts.mailbox);
+        return verdict.ok ? { active: true } : { active: false, reason: verdict.reason };
+    })();
+    const retrievalMounted = opts.retrievalToolMounted;
+    const retrievalHedge = retrievalMounted === undefined ? " (where that tool is mounted)" : "";
+    const RETRIEVE_NOW = retrievalMounted === false
+        ? "its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not wait for it, and say so in your answer if the result matters"
+        : `retrieve its result NOW with TaskOutput(task_id, block: true)${retrievalHedge} rather than ending your turn`;
+    const RETRIEVE_LATER = retrievalMounted === false
+        ? "its result cannot be collected by this run (no TaskOutput is mounted beside this tool)"
+        : "retrieve its status and result with TaskOutput(task_id) where mounted";
+    const WAIT_NOW = retrievalMounted === false
+        ? "do not wait for it — this face has no TaskOutput to block on, and"
+        : `wait for it NOW with TaskOutput(task_id, block: true)${retrievalHedge} —`;
+    const CHECK_LATER = retrievalMounted === false
+        ? "its completion cannot be checked from this face (no TaskOutput is mounted beside this tool)"
+        : "check for its completion with TaskOutput(task_id) where mounted";
+    const capitalize = (text) => `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
     const completionMode = opts.oneShot === true ? "one_shot" : (opts.notificationWired ?? opts.notify !== undefined) ? "notified" : "silent";
     const notifyWired = completionMode === "notified";
     const NO_COMPLETION_NOTICE = completionMode === "one_shot"
-        ? "this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so retrieve its result NOW with TaskOutput(task_id, block: true) rather than ending your turn"
-        : "its completion is NOT announced on this mount — retrieve its status and result with TaskOutput(task_id) where mounted";
+        ? `this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so ${RETRIEVE_NOW}`
+        : `its completion is NOT announced on this mount — ${RETRIEVE_LATER}`;
     const AWAIT_COMPLETION = notifyWired
         ? "Wait for its completion notification"
         : completionMode === "one_shot"
-            ? "Wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
-            : "Check for its completion with TaskOutput(task_id) where mounted";
+            ? `${capitalize(WAIT_NOW)} this one-shot submission ends with this turn`
+            : capitalize(CHECK_LATER);
     const awaitCompletion = notifyWired
         ? "wait for its completion notification"
         : completionMode === "one_shot"
-            ? "wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
-            : "check for its completion with TaskOutput(task_id) where mounted";
+            ? `${WAIT_NOW} this one-shot submission ends with this turn`
+            : CHECK_LATER;
     const sendMessagePins = new Map();
     const pinGuard = (targetId, targetName, rung, to) => {
         if (rung === "other")
@@ -104,12 +131,19 @@ export function createSendMessageTool(opts) {
             (notifyWired
                 ? `You will be notified automatically when it completes — prefer ending your turn; do not poll. `
                 : completionMode === "one_shot"
-                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one — wait actively with TaskOutput(task_id, block: true) when you need a continued agent's result. `
-                    : `A finished agent is NOT announced on this mount — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes. `) +
+                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one${retrievalMounted === false
+                        ? "; a continued agent's result cannot be collected by this run (no TaskOutput is mounted beside this tool) — say so if the result matters"
+                        : ` — wait actively with TaskOutput(task_id, block: true)${retrievalHedge} when you need a continued agent's result`}. `
+                    : `A finished agent is NOT announced on this mount${retrievalMounted === false
+                        ? ", and its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not end your turn to wait for a notification that never comes"
+                        : " — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes"}. `) +
             (tier3Capable
                 ? `Continuing a finished agent works for agents with a durable record — by name or task_id, 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 is no longer held) you get an honest error and should launch a new agent with the needed context instead.`),
+                    `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`) +
+            (peerLane.active
+                ? ` Peer SESSIONS — other sessions of this engine for the same user${opts.peerListingMounted === false ? "" : opts.peerListingMounted === true ? " (list them with ListAgents)" : " (list them with ListAgents where that tool is mounted)"} — are addressed by name, by \`name [ref]\` when a name is ambiguous, or by their \`session.<id>\` address. A message to a peer is parked durably in its session box and read at its next turn boundary (an offline peer reads it when it next runs); the receipt confirms the box accepted it, not that the peer acted on it.`
+                : ""),
         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." }),
@@ -159,9 +193,9 @@ export function createSendMessageTool(opts) {
                 return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to }, isError: true };
             }
             const admissionConfig = resolvePeerAdmissionConfig(opts.admission);
-            const guardScope = ctx.principal ?? opts.scope;
+            const guardScope = ctx.principal ?? opts.scope ?? opts.peerSelfSession?.scope;
             const selfRef = ctx.peerSelfRef ?? opts.peerSelf;
-            const directMountSessionId = ctx.sessionId ?? opts.sessionId;
+            const directMountSessionId = ctx.sessionId ?? opts.sessionId ?? opts.peerSelfSession?.sessionId;
             const directMountTaskId = ctx.taskId ?? opts.owner;
             const senderKey = selfRef?.current.key ??
                 (directMountSessionId !== undefined
@@ -183,6 +217,125 @@ export function createSendMessageTool(opts) {
                             : `this message's forwarding chain is too long (runaway relay) — stop relaying it; act on it or drop it.`;
                 return { content: `Message not sent: ${text}`, details: { error: reason, code: reason, to }, isError: true };
             };
+            const peerRefusal = (code, text, extra) => {
+                const verdict = { ok: false, code, severity: peerSendVerdictSeverity(code), message: text };
+                return { content: `Message not sent: ${text.slice(0, PEER_REFUSAL_TEXT_MAX)}`, details: { error: code, code, to, verdict, ...extra }, isError: true };
+            };
+            const peerSelfSessionId = opts.peerSelfSession?.sessionId ?? directMountSessionId;
+            const peerScope = guardScope ?? opts.peerSelfSession?.scope;
+            let ownRowName;
+            const resolvePeerTarget = async () => {
+                try {
+                    const rows = await opts.peerDirectory.listPeerSessions({ scope: peerScope ?? "" });
+                    if (peerSelfSessionId !== undefined)
+                        ownRowName = rows.find((r) => r.sessionId.toLowerCase() === peerSelfSessionId.toLowerCase())?.name;
+                    return resolvePeerSessions(rows, to, peerSelfSessionId !== undefined ? { sessionId: peerSelfSessionId } : undefined);
+                }
+                catch (e) {
+                    return { status: "directory_fault", message: e instanceof Error ? e.message : String(e) };
+                }
+            };
+            const deliverToPeerSession = async (c) => {
+                const record = c.record;
+                const handle = peerSessionBoxHandle(record.sessionId);
+                const peerLabel = `peer session "${inlineUntrusted(record.name, 64)}" (${handle})`;
+                if (peerScope === undefined)
+                    return peerRefusal("peer_send.other", `this mount has no scope axis, so ${peerLabel}'s box cannot be addressed.`);
+                if (record.inboundPosture === "unavailable") {
+                    return peerRefusal("peer_send.recipient_refuses", `${peerLabel} advertises that it does not accept cross-session messages (its crossSessionInbound is "refuse"). Nothing was parked.`);
+                }
+                const recipientKey = peerAxisToken(peerScope, "s", record.sessionId);
+                const storedContent = `[${summary}] ${clipCarrierMessage(message)}`;
+                const sendVerdict = judgePeerAdmission(peerScope, recipientKey, { senderKey, body: storedContent, prospectiveChain, ownTokens: [recipientKey] }, admissionConfig, undefined, "send");
+                if (!sendVerdict.ok)
+                    return admissionRefusal(sendVerdict.reason, peerLabel);
+                let boxFull = false;
+                try {
+                    boxFull = (await opts.mailbox.peekCount(peerScope, handle)) >= admissionConfig.maxQueuedPeerMessages;
+                }
+                catch {
+                }
+                if (boxFull) {
+                    return { content: `Message not sent: ${inlineUntrusted(peerLabel, 200)}'s session box is at its queued-message limit (${admissionConfig.maxQueuedPeerMessages.toFixed(0)}) — the message was NOT queued; it drains the box at its next turn. Resend later. ${DEDUP_RETRY_NOTE.slice(0, 200)}`, details: { error: "queue_full", code: "queue_full", to }, isError: true };
+                }
+                const modeClass = opts.peerSelfSession?.modeClass?.();
+                const peerMeta = {
+                    ...(peerSelfSessionId !== undefined ? { fromSession: peerSelfSessionId } : {}),
+                    ...(modeClass === "bypass" || modeClass === "prompting" ? { fromMode: modeClass } : {}),
+                    ...(senderKey !== undefined ? { senderKey } : {}),
+                    kind: "peer_message",
+                };
+                const now = Date.now();
+                let seq;
+                try {
+                    seq = await opts.mailbox.append(peerScope, handle, { from: ownRowName ?? opts.peerSelfSession?.name ?? senderLabel, content: storedContent, sentAt: now, hopChain: prospectiveChain, peerMeta });
+                }
+                catch (e) {
+                    if (e?.code === MAILBOX_TOMBSTONED_RECIPIENT_CODE) {
+                        return peerRefusal("peer_send.invalid_target", `${peerLabel} is being deleted — its box no longer accepts messages. Nothing was parked; do not retry.`);
+                    }
+                    return peerRefusal("peer_send.other", `the session box refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked. ${DEDUP_RETRY_NOTE}`);
+                }
+                let rowRestored = "present";
+                try {
+                    const rowsNow = await opts.peerDirectory.listPeerSessions({ scope: peerScope });
+                    const nowRow = rowsNow.find((r) => r.sessionId.toLowerCase() === record.sessionId.toLowerCase());
+                    if (nowRow?.liveness === "deleted")
+                        rowRestored = "deleted_meanwhile";
+                    else if (nowRow === undefined) {
+                        rowRestored = opts.peerDirectory.restorePeerSession !== undefined && (await opts.peerDirectory.restorePeerSession(record)) ? "restored" : "unrestorable";
+                    }
+                }
+                catch {
+                }
+                const rowNote = rowRestored === "unrestorable"
+                    ? " Note: the peer's directory row disappeared while this message was being parked and this directory cannot restore it — the message is safe in the box (it drains by session id), but the name may not resolve until that session next registers; its session.<id> address still does."
+                    : rowRestored === "deleted_meanwhile"
+                        ? " Note: that session was DELETED while this message was being parked — its box is being retired and this message will not be read; do not resend to it."
+                        : "";
+                const offline = record.liveness !== "live";
+                const verdict = { ok: true, disposition: offline ? "parked_offline" : "queued", via: "store" };
+                return {
+                    content: offline
+                        ? `Message parked for ${peerLabel}: that session is offline, so the message was parked durably in its session box (seq ${seq}) and will be delivered when it next runs — subject to the deployment's mailbox retirement policy, which does not notify you. Continue with your task; do not resend the same content.${rowNote}`
+                        : `Message queued for ${peerLabel} (seq ${seq}): it is parked durably in that session's box and will be read at its next turn boundary. This receipt confirms acceptance into the box, not the peer's judgment of the message. Continue with your task; do not resend the same content.${rowNote}`,
+                    details: { type: "send-message", status: offline ? "peer_parked_offline" : "peer_queued", to, address: handle, seq, verdict, ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}) },
+                };
+            };
+            const settlePeerResolution = async (r) => {
+                switch (r.status) {
+                    case "directory_fault":
+                        return peerRefusal("peer_send.other", `the peer-session directory could not be read (${r.message}) — nothing was sent.`);
+                    case "not_found":
+                        return undefined;
+                    case "self":
+                        return peerRefusal("peer_send.invalid_target", `"${inlineUntrusted(to, 120)}" is this session — a session cannot send a cross-session message to itself.`);
+                    case "deleted":
+                        return peerRefusal("peer_send.invalid_target", `peer session "${inlineUntrusted(r.candidate.record.name, 64)}" was deleted — its address no longer accepts messages. Nothing was parked.`);
+                    case "stale_ref":
+                        return peerRefusal("peer_send.invalid_target", `the ref [${r.ref}] no longer resolves (the peer set changed since you listed it) — re-run ListAgents and re-send with a current ref.`);
+                    case "ambiguous":
+                        return { content: `Message not sent: ${inlineUntrusted(r.message, 1000)}`, details: { error: "ambiguous", to, candidates: r.candidates.map((c) => ({ name: c.record.name, ref: c.ref, address: peerSessionBoxHandle(c.record.sessionId), liveness: c.record.liveness })) }, isError: true };
+                    case "found": {
+                        const guard = pinGuard(peerSessionBoxHandle(r.candidate.record.sessionId), r.candidate.record.name, r.rung === "name" ? "name" : "ref", to);
+                        if (guard !== undefined)
+                            return guard;
+                        return await withTargetLane(targetLaneKey(peerScope, peerSessionBoxHandle(r.candidate.record.sessionId)), () => deliverToPeerSession(r.candidate));
+                    }
+                    default: {
+                        const _exhaustive = r;
+                        void _exhaustive;
+                        return undefined;
+                    }
+                }
+            };
+            if (parsePeerSessionAddress(to) !== undefined) {
+                if (!peerLane.active) {
+                    return peerRefusal("peer_send.invalid_target", peerLane.reason !== undefined ? `cross-session addressing is unavailable on this mount — ${peerLane.reason}. Nothing was sent.` : `cross-session addressing is not mounted here (no peer-session directory), so "${inlineUntrusted(to, 120)}" cannot be delivered.`);
+                }
+                const settled = await settlePeerResolution(await resolvePeerTarget());
+                return settled ?? peerRefusal("peer_send.invalid_target", `no session is registered at "${inlineUntrusted(to, 120)}" — nothing was parked (a message is only ever parked for a session that exists or existed).`);
+            }
             if (normalizeAgentName(to) === "main") {
                 if (opts.uplink && senderId !== undefined) {
                     const uplinkIdentity = opts.uplinkRecipient?.current;
@@ -191,15 +344,19 @@ export function createSendMessageTool(opts) {
                         if (!verdict.ok)
                             return admissionRefusal(verdict.reason, "main");
                     }
+                    const uplinkBody = 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;
+                    const uplinkSeq = ++uplinkSeqGlobal;
                     try {
                         opts.uplink({
                             task_id: senderId,
                             task_type: "background_agent",
                             status: "event",
                             summary: `message from ${senderLabel}: ${summary}`,
-                            result: `${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message}\n\n${PEER_MESSAGE_NOTICE}`,
-                            seq: ++uplinkSeqGlobal,
+                            result: `${uplinkBody}\n\n${PEER_MESSAGE_NOTICE}`,
+                            seq: uplinkSeq,
                             peer: { hopChain: prospectiveChain },
+                            agentMessage: { from: senderLabel, body: uplinkBody },
+                            _sema_provenance: { kind: "agent_message", from: senderLabel, taskId: senderId, seq: uplinkSeq },
                         }, { priority: "next" });
                     }
                     catch (e) {
@@ -207,7 +364,7 @@ export function createSendMessageTool(opts) {
                     }
                     return {
                         content: `Message sent to main — queued for the spawning conversation at its next turn boundary. If that conversation finishes before reading it, the message may not survive. Continue with your task; do not wait for a reply.`,
-                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
+                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeq },
                     };
                 }
                 if (!senderIsChild) {
@@ -594,6 +751,14 @@ export function createSendMessageTool(opts) {
                     const labels = parentAccess !== undefined
                         ? [...ownLabels, ...opts.registry.runningBackgroundAgentLabels(parentAccess).filter((l) => !ownLabels.includes(l))]
                         : ownLabels;
+                    if (peerLane.active) {
+                        const settled = await settlePeerResolution(await resolvePeerTarget());
+                        if (settled !== undefined)
+                            return settled;
+                    }
+                    else if (peerLane.reason !== undefined) {
+                        return peerRefusal("peer_send.other", `no agent matches "${inlineUntrusted(to, 120)}", and the cross-session lane that could reach a peer session by that name is unavailable on this mount — ${peerLane.reason}.`);
+                    }
                     if (DURABLE_AGENT_HANDLE_RE.test(to)) {
                         return {
                             content: `Message not sent: no transcript found for agent ${to} — launch a new agent with the needed context instead.`,

package/dist/agents/subagent-steps.d.ts

@@ -41,6 +41,17 @@ export interface SubagentEditedFile {
 }
 /** Keep the last N tool steps (CC's tail is ~this deep; older steps are rarely load-bearing for resume). */
 export declare const STEP_CAP = 10;
+/** Hard-bound a line to `max` UTF-16 units — a pure prefix, no marker appended. When the cut would split a
+ *  redaction marker, it moves back to the marker's start (the bound holds, and the output never shows a
+ *  marker fragment); when it would split a surrogate pair, it moves back one unit (never a lone surrogate). */
+export declare function cutAt(line: string, max: number): string;
+/**
+ * Redact, THEN bound — the order every display cut in this module (and the runner's `steering_injected`
+ * previews) uses. Exported so a preview minted elsewhere gets the same marker-aware cut rather than a
+ * raw `slice` that can leave a half marker at the bound. Keeps newlines: a multi-line body is the
+ * caller's shape; only the bound and the redaction are this function's.
+ */
+export declare function redactThenCut(s: string, max: number): string;
 /** The tool's primary argument as a single short line (best-effort; unknown shapes → a compact JSON head). */
 export declare function extractTarget(args: unknown): string;
 /**