@sema-agent/core 7.2.0 → 7.3.1

package/dist/agents/peer-directory.js

@@ -0,0 +1,272 @@
+import { lstat } from "node:fs/promises";
+import { isAbsolute, dirname, resolve as resolvePath } from "node:path";
+import { formatPeerNameRef, mintPeerRef, normalizePeerName, parsePeerNameRef, PEER_REF_RE } from "./cross-session-ref.js";
+import { inlineUntrusted } from "../core/untrusted-text.js";
+export const PEER_SESSION_RECORD_SCHEMA_VERSION = 1;
+export const PEER_SESSION_RECORD_MAX_BYTES = 262_144;
+export const SESSION_BOX_PREFIX = "session.";
+const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,80}$/;
+export const PEER_SESSION_ID_GRAMMAR = "^[A-Za-z0-9_-]{1,80}$";
+export function isPeerSessionId(sessionId) {
+    return SESSION_ID_RE.test(sessionId);
+}
+const SESSION_ADDRESS_RE = /^session\.([A-Za-z0-9_-]{1,80})$/i;
+export function peerSessionBoxHandle(sessionId) {
+    if (!SESSION_ID_RE.test(sessionId))
+        throw new Error(`peerSessionBoxHandle: session id ${JSON.stringify(sessionId)} is outside the address grammar ^[A-Za-z0-9_-]{1,80}$`);
+    return `${SESSION_BOX_PREFIX}${sessionId.toLowerCase()}`;
+}
+export function parsePeerSessionAddress(text) {
+    const m = SESSION_ADDRESS_RE.exec(text.trim());
+    return m === null ? undefined : m[1].toLowerCase();
+}
+function optNumber(v) {
+    return v === undefined || (typeof v === "number" && Number.isFinite(v));
+}
+function optString(v) {
+    return v === undefined || typeof v === "string";
+}
+function optStringArray(v) {
+    return v === undefined || (Array.isArray(v) && v.every((x) => typeof x === "string"));
+}
+export function readPeerSessionRecord(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { ok: false, reason: "not_an_object" };
+    const r = raw;
+    if (typeof r["schemaVersion"] !== "number" || !Number.isInteger(r["schemaVersion"]) || r["schemaVersion"] < 1)
+        return { ok: false, reason: "schema_missing" };
+    if (r["schemaVersion"] > PEER_SESSION_RECORD_SCHEMA_VERSION)
+        return { ok: false, reason: "schema_newer" };
+    if (typeof r["sessionId"] !== "string" || !SESSION_ID_RE.test(r["sessionId"]))
+        return { ok: false, reason: "session_id_invalid" };
+    if (typeof r["scope"] !== "string" || r["scope"] === "")
+        return { ok: false, reason: "scope_invalid" };
+    if (typeof r["name"] !== "string" || normalizePeerName(r["name"]) === "")
+        return { ok: false, reason: "name_invalid" };
+    const liveness = r["liveness"];
+    if (liveness !== "live" && liveness !== "dead" && liveness !== "deleted")
+        return { ok: false, reason: "liveness_invalid" };
+    const bad = (field) => ({ ok: false, reason: "field_invalid", field });
+    if (!optNumber(r["startedAt"]) || r["startedAt"] === undefined)
+        return bad("startedAt");
+    if (!optNumber(r["updatedAt"]) || r["updatedAt"] === undefined)
+        return bad("updatedAt");
+    if (!optNumber(r["pid"]))
+        return bad("pid");
+    if (!optNumber(r["procStartMs"]))
+        return bad("procStartMs");
+    if (!optNumber(r["diedAt"]))
+        return bad("diedAt");
+    if (!optNumber(r["peerProtocol"]))
+        return bad("peerProtocol");
+    if (!optString(r["cwd"]))
+        return bad("cwd");
+    if (!optString(r["entrypoint"]))
+        return bad("entrypoint");
+    if (!optString(r["sockPath"]))
+        return bad("sockPath");
+    if (!optStringArray(r["formerNames"]))
+        return bad("formerNames");
+    if (!optStringArray(r["peerFeatures"]))
+        return bad("peerFeatures");
+    const nameSource = r["nameSource"];
+    if (nameSource !== undefined && nameSource !== "auto" && nameSource !== "flag" && nameSource !== "rename")
+        return bad("nameSource");
+    const tempo = r["tempo"];
+    if (tempo !== undefined && tempo !== "active" && tempo !== "idle" && tempo !== "blocked")
+        return bad("tempo");
+    const inboundPosture = r["inboundPosture"];
+    if (inboundPosture !== undefined && inboundPosture !== "available" && inboundPosture !== "unavailable")
+        return bad("inboundPosture");
+    const record = {
+        schemaVersion: r["schemaVersion"],
+        sessionId: r["sessionId"],
+        scope: r["scope"],
+        name: r["name"],
+        ...(nameSource !== undefined ? { nameSource } : {}),
+        ...(r["formerNames"] !== undefined ? { formerNames: [...r["formerNames"]] } : {}),
+        ...(r["pid"] !== undefined ? { pid: r["pid"] } : {}),
+        ...(r["procStartMs"] !== undefined ? { procStartMs: r["procStartMs"] } : {}),
+        ...(r["cwd"] !== undefined ? { cwd: r["cwd"] } : {}),
+        startedAt: r["startedAt"],
+        updatedAt: r["updatedAt"],
+        liveness,
+        ...(r["diedAt"] !== undefined ? { diedAt: r["diedAt"] } : {}),
+        ...(tempo !== undefined ? { tempo } : {}),
+        ...(r["entrypoint"] !== undefined ? { entrypoint: r["entrypoint"] } : {}),
+        ...(r["peerProtocol"] !== undefined ? { peerProtocol: r["peerProtocol"] } : {}),
+        ...(r["peerFeatures"] !== undefined ? { peerFeatures: [...r["peerFeatures"]] } : {}),
+        ...(r["sockPath"] !== undefined ? { sockPath: r["sockPath"] } : {}),
+        ...(inboundPosture !== undefined ? { inboundPosture } : {}),
+    };
+    return { ok: true, record };
+}
+export const defaultPeerLivenessProbe = {
+    processExists(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === "EPERM";
+        }
+    },
+};
+export function isPeerSessionProcessAlive(record, probe = defaultPeerLivenessProbe) {
+    if (record.liveness !== "live")
+        return false;
+    if (record.pid === undefined)
+        return true;
+    if (!probe.processExists(record.pid))
+        return false;
+    if (record.procStartMs !== undefined && probe.processStartMs !== undefined) {
+        const started = probe.processStartMs(record.pid);
+        if (started !== undefined && Math.abs(started - record.procStartMs) > 2_000)
+            return false;
+    }
+    return true;
+}
+export function mintPeerSessionCandidates(records, self) {
+    const entries = records.map((record) => ({ kind: "session", id: record.sessionId.toLowerCase(), record }));
+    const selfEntry = self !== undefined && !records.some((r) => r.sessionId.toLowerCase() === self.sessionId.toLowerCase()) ? { kind: "session", id: self.sessionId.toLowerCase() } : undefined;
+    return mintPeerRef(entries, selfEntry).map((e) => ({ record: e.record, ref: e.ref }));
+}
+function describeCandidate(c) {
+    const state = c.record.liveness === "live" ? "" : c.record.liveness === "dead" ? " (offline)" : " (deleted)";
+    return `${formatPeerNameRef(inlineUntrusted(c.record.name, 64), c.ref)}${state} → ${peerSessionBoxHandle(c.record.sessionId)}`;
+}
+export function resolvePeerSessions(records, to, self) {
+    const candidates = mintPeerSessionCandidates(records, self);
+    const selfId = self?.sessionId.toLowerCase();
+    const settle = (c, rung) => {
+        if (selfId !== undefined && c.record.sessionId.toLowerCase() === selfId)
+            return { status: "self" };
+        if (c.record.liveness === "deleted")
+            return { status: "deleted", candidate: c };
+        return { status: "found", candidate: c, rung };
+    };
+    const address = parsePeerSessionAddress(to);
+    if (address !== undefined) {
+        if (selfId !== undefined && address === selfId)
+            return { status: "self" };
+        const hit = candidates.find((c) => c.record.sessionId.toLowerCase() === address);
+        return hit === undefined ? { status: "not_found" } : settle(hit, "address");
+    }
+    const nameRef = parsePeerNameRef(to);
+    const rawName = nameRef?.name ?? to;
+    const key = normalizePeerName(rawName);
+    if (key === "")
+        return { status: "not_found" };
+    const byName = candidates.filter((c) => normalizePeerName(c.record.name) === key);
+    if (nameRef !== undefined) {
+        const hit = byName.find((c) => c.ref === nameRef.ref) ?? (PEER_REF_RE.test(nameRef.ref) ? candidates.find((c) => c.ref === nameRef.ref && normalizePeerName(c.record.name) === key) : undefined);
+        if (hit === undefined)
+            return { status: "stale_ref", ref: nameRef.ref };
+        return settle(hit, "ref");
+    }
+    if (byName.length === 0)
+        return { status: "not_found" };
+    if (byName.length === 1)
+        return settle(byName[0], "name");
+    const sorted = [...byName].sort((a, b) => (a.record.liveness === b.record.liveness ? b.record.updatedAt - a.record.updatedAt : a.record.liveness === "live" ? -1 : 1));
+    return {
+        status: "ambiguous",
+        candidates: sorted,
+        message: `"${inlineUntrusted(rawName, 64)}" matches ${sorted.length} sessions — re-send with the name and ref of the one you mean: ${sorted.map(describeCandidate).join("; ")}`,
+    };
+}
+export function createInMemoryPeerDirectory() {
+    const rows = new Map();
+    const key = (scope, sessionId) => JSON.stringify([scope, sessionId.toLowerCase()]);
+    return {
+        listPeerSessions(access) {
+            return [...rows.values()].filter((r) => r.scope === access.scope).map((r) => ({ ...r }));
+        },
+        upsert(record) {
+            const read = readPeerSessionRecord(record);
+            if (!read.ok)
+                throw new Error(`InMemoryPeerDirectory.upsert: refused row (${read.reason}${read.field !== undefined ? `: ${read.field}` : ""})`);
+            rows.set(key(record.scope, record.sessionId), read.record);
+        },
+        markDead(scope, sessionId, diedAt = Date.now()) {
+            const r = rows.get(key(scope, sessionId));
+            if (r === undefined || r.liveness !== "live")
+                return false;
+            rows.set(key(scope, sessionId), { ...r, liveness: "dead", diedAt, updatedAt: diedAt });
+            return true;
+        },
+        markDeleted(scope, sessionId, at = Date.now()) {
+            const r = rows.get(key(scope, sessionId));
+            if (r === undefined)
+                return false;
+            rows.set(key(scope, sessionId), { ...r, liveness: "deleted", diedAt: r.diedAt ?? at, updatedAt: at });
+            return true;
+        },
+        restorePeerSession(record) {
+            const k = key(record.scope, record.sessionId);
+            if (rows.has(k))
+                return false;
+            const read = readPeerSessionRecord(record);
+            if (!read.ok)
+                return false;
+            rows.set(k, read.record);
+            return true;
+        },
+        async sweep(scope, boxEmpty) {
+            const swept = [];
+            for (const [k, r] of [...rows.entries()]) {
+                if (r.scope !== scope || r.liveness === "live")
+                    continue;
+                if (await boxEmpty(r.sessionId)) {
+                    if (rows.get(k) !== r)
+                        continue;
+                    rows.delete(k);
+                    swept.push(r.sessionId);
+                }
+            }
+            return swept;
+        },
+    };
+}
+export async function vetPeerRegistryDirectory(dir, opts) {
+    if (!isAbsolute(dir))
+        return { ok: false, code: "not_absolute", path: dir };
+    const uid = opts?.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    const stopAt = opts?.stopAt !== undefined ? resolvePath(opts.stopAt) : undefined;
+    let cursor = resolvePath(dir);
+    for (;;) {
+        let st;
+        try {
+            st = await lstat(cursor);
+        }
+        catch {
+            return { ok: false, code: "missing", path: cursor };
+        }
+        if (st.isSymbolicLink())
+            return { ok: false, code: "symlink", path: cursor };
+        if (!st.isDirectory())
+            return { ok: false, code: "not_directory", path: cursor };
+        const parent = dirname(cursor);
+        const isRoot = parent === cursor || (stopAt !== undefined && cursor === stopAt);
+        if (!isRoot) {
+            if (uid !== undefined && st.uid !== uid)
+                return { ok: false, code: "foreign_owner", path: cursor };
+            if ((st.mode & 0o022) !== 0)
+                return { ok: false, code: "group_or_world_writable", path: cursor };
+        }
+        if (isRoot)
+            return { ok: true };
+        cursor = parent;
+    }
+}
+export function judgePeerRecordFile(stat, selfUid) {
+    if (!stat.isFile)
+        return { ok: false, code: "not_regular" };
+    if (selfUid !== undefined && stat.uid !== undefined && stat.uid !== selfUid)
+        return { ok: false, code: "foreign_owner" };
+    if ((stat.mode & 0o022) !== 0)
+        return { ok: false, code: "group_or_world_writable" };
+    if (stat.size > PEER_SESSION_RECORD_MAX_BYTES)
+        return { ok: false, code: "too_large" };
+    return { ok: true };
+}

package/dist/agents/peer-session-drain.d.ts

@@ -0,0 +1,159 @@
+import { type MailboxCrossProcessVerdict, type MailboxStore } from "../core/mailbox-store.js";
+import type { SystemInjectionPriority, TaskNotificationPayload } from "../core/task-notification.js";
+import { type EngineNotice, type RunnerDeps } from "../core/types.js";
+import { type PermissionModeClass } from "./cross-session-envelope.js";
+import { type CrossSessionInboundSettingLayers } from "./cross-session-judge.js";
+import { type PeerAdmissionConfig } from "./peer-admission.js";
+import { type PeerDirectory } from "./peer-directory.js";
+import { createListAgentsTool } from "./list-agents-tool.js";
+import type { AskEffective } from "../core/wiring-manifest.js";
+import type { SendMessageToolOptions } from "./send-message-tool.js";
+/** design/385 §1.2④ — the drain lease TTL. Same sizing law as the tier-3 revive lease: well under the
+ *  store's stale-row floor, long enough to cover one turn (a longer turn renews on the same owner at
+ *  its next boundary; an expired lease re-serves the batch — at-least-once). */
+export declare const PEER_DRAIN_LEASE_TTL_MS: number;
+/** The lane-mount refusal for a run whose own session id cannot be spelled as a peer address. */
+export declare const PEER_SESSION_ID_UNGRAMMATICAL_CODE = "peer.session_id_ungrammatical";
+/** The lane's mount verdict: the mailbox declaration's verdict, or this leg's own address refusal. */
+export type PeerLaneMountVerdict = MailboxCrossProcessVerdict | {
+    ok: false;
+    code: typeof PEER_SESSION_ID_UNGRAMMATICAL_CODE;
+    reason: string;
+};
+/**
+ * design/385 §1.2⑥ / §5.1 — may the cross-session lane mount on this deployment? `undefined` = no
+ * directory seat (no lane, nothing to say). A directory with no mailbox, or over a mailbox that does not
+ * declare cross-process safety, is REFUSED with a named reason (bad-value loudness: several terminals
+ * sharing one box on luck is exactly what the declaration exists to forbid). With a `sessionId`, the
+ * leg's OWN address is judged too: a host-minted session id outside the peer address grammar has no
+ * session box to drain and no address a peer could send to, so the lane refuses by name — the
+ * alternative was `peerSessionBoxHandle` throwing out of prepare and failing the whole run over an
+ * optional feature.
+ */
+export declare function judgePeerLaneMount(deps: {
+    peerDirectory?: PeerDirectory;
+    mailboxStore?: MailboxStore;
+}, sessionId?: string): PeerLaneMountVerdict | undefined;
+export interface PeerSessionDrainOptions {
+    mailbox: MailboxStore;
+    /** This session (the box owner) and this leg's cycle id (the lease owner). */
+    sessionId: string;
+    runId: string;
+    /** The registry/mailbox scope this run mounts in. */
+    scope: string;
+    /** The run's own notification injector (the task-notification lane; `next` tier). */
+    inject: (notification: TaskNotificationPayload, opts?: {
+        priority?: SystemInjectionPriority;
+    }) => void;
+    /** Deployment tuning of the admission gate (the same seat SendMessage reads). */
+    admission?: Partial<PeerAdmissionConfig>;
+    /** The recipient's self-token set for the hop check, read live (the run's peer identity ref). */
+    ownTokens: () => readonly string[];
+    /** The recipient's `crossSessionInbound` layers, read at every drain. */
+    settingLayers: () => CrossSessionInboundSettingLayers | undefined;
+    /** The recipient's own permission-mode class, read at every drain (the manifest's ask fold). */
+    selfModeClass: () => PermissionModeClass | "unknown";
+    onNotice?: (notice: EngineNotice) => void;
+    onError?: (error: unknown, ctx: {
+        phase: "degraded";
+        sessionId: string;
+        classification: string;
+    }) => void;
+    leaseTtlMs?: number;
+}
+export interface PeerSessionDrain {
+    /** One drain round (serialized: a boundary never overlaps a still-running round). */
+    drain(): Promise<void>;
+    /** Run end: ack the last batch and release the lease so the session's next cycle claims at once. */
+    finish(): Promise<void>;
+}
+export declare function createPeerSessionDrain(opts: PeerSessionDrainOptions): PeerSessionDrain;
+/** The lane's late-bound facts: the ask fold resolves after the manifest derivation, the mount runs
+ *  before it — both read this one cell. */
+export interface PeerLaneRefs {
+    askEffective?: AskEffective;
+}
+/**
+ * The mount verdict + its loud half: `true` = the lane mounts on this leg; `false` = no seat, or the
+ * seat was refused — the refusal is announced ONCE per leg as `config.peer_lane_unmounted` naming the
+ * reason (never mounted on luck, never silently inert).
+ */
+export declare function announcePeerLaneMount(deps: {
+    peerDirectory?: PeerDirectory;
+    mailboxStore?: MailboxStore;
+    onNotice?: (n: EngineNotice) => void;
+}, leg: {
+    sessionId: string;
+    runId: string;
+}): boolean;
+/** The SendMessage seats of the lane (design/385 §2): the directory (address arm + last name rung) and
+ *  this session's identity/attestation, whose mode class folds LIVE off the manifest's ask derivation. */
+export declare function peerLaneSendMessageSeats(args: {
+    peerDirectory: PeerDirectory;
+    sessionId: string;
+    scope: string;
+    name?: string;
+    refs: PeerLaneRefs;
+    listingMounted?: boolean;
+}): Pick<SendMessageToolOptions, "peerDirectory" | "peerSelfSession" | "peerListingMounted">;
+/**
+ * design/385 §5.1 — THE ListAgents mount predicate, single source: the built-in mounts only when the
+ * face does not exclude it and no caller tool owns either spelling (`ListAgents` / `ListPeers`) as its
+ * name OR as an alias. Every reader of "is ListAgents on this roster?" — the mount itself and the
+ * SendMessage face's listing phrase — calls this one predicate, so a face can never name a tool the
+ * roster does not carry (a second, inline copy of the rule drifted on exactly the alias arms).
+ */
+export declare function listAgentsMountable(face: {
+    exclude: readonly string[] | undefined;
+    specTools: ReadonlyArray<{
+        name: string;
+        aliases?: readonly string[];
+    }>;
+}): boolean;
+/** design/385 §5.1 — the ListAgents mount (alias ListPeers): read-only, concurrency-safe, on the peer
+ *  seat's own arm beside SendMessage; a caller-supplied tool of the same name wins (skip, not throw). */
+export declare function mountListAgents(args: {
+    peerDirectory: PeerDirectory;
+    sessionId: string;
+    scope: string;
+    hostTaskId: string;
+    /** The delegated child's trusted parent pair (RunInternals), when this run is a child. */
+    parentTaskId?: string;
+    parentSessionId?: string;
+    registry: ListAgentsToolRegistry;
+    roster?: NonNullable<Parameters<typeof createListAgentsTool>[0]["roster"]>;
+    specTools: ReadonlyArray<{
+        name: string;
+        aliases?: readonly string[];
+    }>;
+    toolEffects: Map<string, "read" | "write" | "idempotent">;
+}): ReturnType<typeof createListAgentsTool> | undefined;
+type ListAgentsToolRegistry = NonNullable<Parameters<typeof createListAgentsTool>[0]["registry"]>;
+/** The harness surface the binding needs (structural — the machine itself never sees the harness). */
+export interface PeerDrainHarness {
+    on(type: "turn_boundary" | "before_agent_start", handler: () => Promise<undefined>): unknown;
+    subscribe(listener: (event: {
+        type: string;
+    }) => void | Promise<void>): unknown;
+}
+/**
+ * Bind the drain to a leg: the run's own injector at the `next` tier, run open (the loop's first
+ * steering drain follows the `before_agent_start` hook) + every turn boundary, and the run-end
+ * ack/release on `agent_end`.
+ */
+export declare function bindPeerSessionDrain(harness: PeerDrainHarness, opts: PeerSessionDrainOptions): PeerSessionDrain;
+/**
+ * The leg-side spelling of {@link bindPeerSessionDrain}: the deployment seats the drain reads
+ * (`mailboxStore` / `peerAdmission` / `crossSessionInbound` / the two sinks) come straight off deps, the
+ * recipient's mode class folds off the lane refs — one binding call per leg, no per-seat plumbing.
+ */
+export declare function bindPeerLaneDrain(harness: PeerDrainHarness, args: {
+    deps: Pick<RunnerDeps, "mailboxStore" | "peerAdmission" | "crossSessionInbound" | "onNotice" | "onError">;
+    sessionId: string;
+    runId: string;
+    scope: string;
+    inject: PeerSessionDrainOptions["inject"];
+    ownTokens: () => readonly string[];
+    refs: PeerLaneRefs;
+}): PeerSessionDrain;
+export {};

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 } : {}),
+    });
+}