@sema-agent/core/dist/agents/peer-session-drain.js

Stateless, task-oriented AI agent core

import { mailboxCrossProcessMountVerdict } 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";
import { isGateMintedRecord, principalInboxConsumerOf } from "./org-delivery-gate.js";
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 { 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";
import { peerHeldQueueFor } from "./peer-held-queue.js";
import { peerIdleMachineFor } from "./peer-idle.js";
import { describePeerIdleSubscription, isPeerDeliveryReceiptState, isPeerIdleNoticeKind, peerIdleNoticeLabel, renderCrossSessionDeliveryNotice, renderCrossSessionDroppedNotice, renderCrossSessionIdleNotice, resolveCrossSessionDialogExpiry } from "./peer-notices.js";
import { routePeerDeliveryReceipt, routePeerDroppedReceipt, routePeerIdleNotice } from "./peer-notice-route.js";
import { thrownText } from "../core/thrown-value.js";
export const PEER_DRAIN_LEASE_TTL_MS = 5 * 60_000;
export const PEER_SESSION_ID_UNGRAMMATICAL_CODE = "peer.session_id_ungrammatical";
export const PRINCIPAL_INBOX_UNMINTED_CAUSE = "not_minted_by_delivery_gate";
export function terminalsDrainPrincipalInbox(deps) {
    return principalInboxConsumerOf(deps).kind === "terminals";
}
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 judgeSessionBoxDrain(deps, leg) {
    const mailbox = deps.mailboxStore;
    if (mailbox === undefined || leg.isDelegatedChild)
        return undefined;
    if (!mailboxCrossProcessMountVerdict(mailbox).ok || !isPeerSessionId(leg.sessionId))
        return undefined;
    return {
        mailbox,
        scope: leg.scope,
        handle: peerSessionBoxHandle(leg.sessionId),
        sessionId: leg.sessionId,
        ...(deps.sessionBoxEngineFrames === true ? { engineFrames: true } : {}),
        onError: (e) => deps.onError?.(e, { phase: "degraded", sessionId: leg.sessionId, classification: "session-box-park" }),
    };
}
export const PEER_RESUPPLY_CAP = 1;
export function createPeerSessionDrain(opts) {
    const { mailbox, sessionId, runId, scope } = opts;
    const storedSessionAddress = (fromSession) => fromSession !== undefined && isPeerSessionId(fromSession) ? peerSessionBoxHandle(fromSession) : undefined;
    const drainOwner = `drain:${runId}`;
    const recipientKey = peerAxisToken(scope, "s", sessionId);
    const ttl = opts.leaseTtlMs ?? PEER_DRAIN_LEASE_TTL_MS;
    const TERMINAL_DISPOSITIONS = new Set(["committed", "resupply_exhausted", "terminal"]);
    const isTerminalDisposition = (d) => d !== undefined && TERMINAL_DISPOSITIONS.has(d.kind);
    const clockOpt = opts.clock !== undefined ? { clock: opts.clock } : {};
    const mintLane = (kind) => {
        const boxHandle = kind === "session" ? peerSessionBoxHandle(sessionId) : PRINCIPAL_INBOX_HANDLE;
        return {
            kind,
            boxHandle,
            label: kind === "session" ? "this session's box" : "this principal's inbox",
            ledger: new Map(),
            ackedUpTo: undefined,
            disclosedHeld: new Set(),
            held: peerHeldQueueFor(scope, sessionId, kind === "session" ? clockOpt : { ...clockOpt, box: boxHandle }),
        };
    };
    const lanes = opts.principalInbox === true ? [mintLane("session"), mintLane("principal")] : [mintLane("session")];
    const sessionLane = lanes[0];
    const boxHandle = sessionLane.boxHandle;
    const seam = opts.settlement ?? createFrameSettlement();
    let inFlight = Promise.resolve();
    let noticeRound = 0;
    let currentRound;
    const idleMachine = peerIdleMachineFor(scope, sessionId, clockOpt);
    const disclose = (lane, disposition, cause, m, heldNote) => deliverEngineNotice(opts.onNotice, {
        code: "peer.inbound_disposition",
        message: `cross-session message seq ${m.seq} in ${lane.label} was ${disposition === "held"
            ? `HELD${heldNote !== undefined ? ` (${heldNote})` : lane.kind === "session" ? " (it entered this session's held queue and STAYS IN THE BOX \u2014 the box is that queue's durable seat, so it is not acked until it settles; it is re-judged at every boundary, released or refused with a receipt to the sender, and expires with a receipt under dialogExpiry)" : " (it entered this session's held queue for the principal inbox and STAYS IN THE BOX until it settles; it is re-judged at every boundary. The sender is another principal: no receipt reaches it from here \u2014 the delivery gate's receipt is its record)"}`
            : disposition === "refused"
                ? "refused by this session's crossSessionInbound setting"
                : disposition === "resupply_exhausted"
                    ? "settled WITHOUT being read: its frame was summarized away by a compaction, re-supplied once, and summarized away again \u2014 the engine has stopped handing it over. The sender was not told; reply-worthy content is GONE from this session's context"
                    : disposition === "notice_unrouted"
                        ? "settled WITHOUT delivery (a notice-kind record the notice face cannot render)"
                        : disposition === "notice_user_only"
                            ? "surfaced to the user only (a notice whose sender this session's parity would hold; the model did not read it)"
                            : "refused by the inbound admission gate"}: ${cause}`,
        detail: { disposition, cause, seq: m.seq, box: lane.boxHandle, ...(m.peerMeta?.fromSession !== undefined ? { fromSession: m.peerMeta.fromSession } : {}), sessionId, runId },
    });
    const readFacts = () => {
        const layers = opts.settingLayers() ?? {};
        return { setting: resolveCrossSessionInboundSetting(layers), principalSetting: resolveCrossSessionInboundSetting(principalInboundLayers(layers)), selfModeClass: opts.selfModeClass() };
    };
    const judgeMeta = (facts, meta) => meta?.fromScope !== undefined
        ? judgeCrossSessionInbound({ setting: facts.principalSetting, selfModeClass: facts.selfModeClass, sender: { fromScope: meta.fromScope } })
        : judgeCrossSessionInbound({ setting: facts.setting, selfModeClass: facts.selfModeClass, sender: { ...(meta?.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: meta?.fromSession !== undefined && meta.fromSession.toLowerCase() === sessionId.toLowerCase() } });
    const route = () => ({
        mailbox,
        scope,
        self: { sessionId, ...(opts.selfName?.() !== undefined ? { name: opts.selfName() } : {}), modeClass: opts.selfModeClass },
        ...(opts.onError !== undefined ? { onError: opts.onError } : {}),
    });
    const buildPeerMessagePayload = (lane, m) => {
        const { boxHandle } = lane;
        const meta = m.peerMeta;
        const fields = {
            from: encodePeerAddress(storedSessionAddress(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);
        return {
            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 } } : {}) },
        };
    };
    const buildNoticePayload = (m, kind, text) => ({
        task_id: boxHandle,
        task_type: "background_agent",
        status: "event",
        summary: kind === "delivery_notice" ? "cross-session delivery notice" : "cross-session idle notice",
        result: text,
        seq: m.seq,
        crossSessionNotice: { kind, text },
        _sema_provenance: { kind: "cross_session_notice", from: encodePeerAddress(storedSessionAddress(m.peerMeta?.fromSession) ?? (m.from ?? "unknown")), taskId: boxHandle, seq: m.seq, ...(m.peerMeta !== undefined ? { peerMeta: { ...m.peerMeta } } : {}) },
    });
    const receiptAddress = (lane, entry) => (lane.kind === "session" ? entry.peerMeta?.fromSession : undefined);
    const receipt = (lane) => (entry, state) => {
        const to = receiptAddress(lane, entry);
        if (to === undefined)
            return;
        if (state === "dropped")
            void routePeerDroppedReceipt(route(), to, entry.seq);
        else
            void routePeerDeliveryReceipt(route(), to, state, entry.seq);
    };
    const heldSink = (lane, live) => ({
        judge: (entry) => judgeMeta(readFacts(), entry.peerMeta),
        ...(live
            ? {
                inject: (entry) => {
                    if (currentRound === undefined)
                        return "deferred";
                    const payload = buildPeerMessagePayload(lane, entry);
                    if (currentRound.deliver(payload, "next") === "deferred")
                        return "deferred";
                    noteDelivered(lane, entry.seq, 1, payload, currentRound.carrier);
                    return undefined;
                },
            }
            : {}),
        receipt: receipt(lane),
        onHeld: (entry, count, cause, reannounce) => {
            if (!reannounce && lane.disclosedHeld.has(entry.seq))
                return;
            lane.disclosedHeld.add(entry.seq);
            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")
                lane.ledger.set(entry.seq, { kind: "terminal", why: `held_${settlement}` });
            const replyTo = receiptAddress(lane, entry);
            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"}.`,
                detail: { settlement, reason, seq: entry.seq, box: lane.boxHandle, ...(entry.peerMeta?.fromSession !== undefined ? { fromSession: entry.peerMeta.fromSession } : {}), heldCount: count, sessionId, runId },
            });
        },
    });
    let dialogExpiryMs = resolveCrossSessionDialogExpiry(undefined).ms;
    let dialogExpiryAnnounced = false;
    const bindHeld = (lane, live) => {
        try {
            const resolved = resolveCrossSessionDialogExpiry(opts.dialogExpiry?.());
            dialogExpiryMs = resolved.ms;
            if (resolved.invalid && !dialogExpiryAnnounced) {
                dialogExpiryAnnounced = true;
                opts.onError?.(new Error(`crossSessionDialogExpiry holds a value outside its vocabulary (60s|5m|10m|never); the default ${resolved.value} is in force for held cross-session messages`), { phase: "degraded", sessionId, classification: "peer-dialog-expiry" });
            }
        }
        catch (e) {
            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-dialog-expiry" });
        }
        lane.held.configure({ sink: heldSink(lane, live), dialogExpiryMs });
    };
    for (const lane of lanes)
        bindHeld(lane, true);
    idleMachine.target.configure({
        notify: (sub, notice) => void routePeerIdleNotice(route(), sub.requester, notice),
        judge: (sub) => judgeMeta(readFacts(), { ...(sub.fromMode !== undefined ? { fromMode: sub.fromMode } : {}), ...(sub.selfSent ? { fromSession: sessionId } : {}) }),
        heldCount: () => lanes.reduce((n, lane) => n + lane.held.size(), 0),
        ...(opts.lastTurnText !== undefined ? { lastTurnText: opts.lastTurnText } : {}),
    });
    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) => {
        lane.held.reconcile(new Set(lease.messages.map((m) => m.seq)));
        let queued;
        for (const [seq, d] of lane.ledger) {
            if (d.kind !== "held")
                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);
        }
    };
    const wantsCompactionEffects = () => {
        for (const lane of lanes)
            for (const d of lane.ledger.values())
                if (d.kind === "delivered" || d.kind === "committed")
                    return true;
        return false;
    };
    const noteDelivered = (lane, seq, attempt, payload, carrier) => {
        const own = taskNotificationDedupKey(payload);
        const key = carrier === undefined ? own : `${carrier}|${own}`;
        lane.ledger.set(seq, { kind: "delivered", attempt, key, payload });
        currentRound?.tally(lane, attempt);
        if (carrier === undefined && payload._sema_provenance?.peerMeta?.fromScope !== undefined) {
            try {
                opts.markExternalContent?.(`a letter from another principal (cross-principal message seq ${seq} in ${lane.boxHandle}) was delivered into this session`);
            }
            catch (e) {
                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-external-mark" });
            }
        }
        seam.awaiting.set(key, carrier === undefined ? { carrier: own } : { carrier, frameText: renderTaskNotificationXml(payload) });
    };
    const deriveAckPrefix = (lane, messages) => {
        let prefix;
        for (const m of messages) {
            if (lane.ackedUpTo !== undefined && m.seq <= lane.ackedUpTo)
                continue;
            if (!isTerminalDisposition(lane.ledger.get(m.seq)))
                break;
            prefix = m.seq;
        }
        return prefix;
    };
    const settleLocally = () => {
        const landed = seam.compactions.splice(0);
        for (const lane of lanes)
            settleLaneLocally(lane, landed);
    };
    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) {
                if (d.kind !== "delivered")
                    continue;
                if (seam.hostWithheld.delete(d.key)) {
                    ledger.set(seq, { kind: "terminal", why: "host_withheld" });
                    hostWithheldSeqs.push(seq);
                    continue;
                }
                if (seam.withheld.delete(d.key)) {
                    if (d.attempt > 1)
                        ledger.set(seq, { kind: "invalidated", attempt: d.attempt - 1, payload: d.payload });
                    else
                        ledger.delete(seq);
                    continue;
                }
                const entryId = seam.receipts.get(d.key);
                if (entryId === undefined)
                    continue;
                seam.receipts.delete(d.key);
                ledger.set(seq, { kind: "committed", attempt: d.attempt, key: d.key, entryId, payload: d.payload });
            }
        }
        if (hostWithheldSeqs.length > 0) {
            opts.onError?.(new Error(`${hostWithheldSeqs.length} cross-session message frame(s) (seq ${hostWithheldSeqs.join(", ")}) could not be found in this session's ReadInbox result as a postToolUse hook rewrote it (removed, truncated or reshaped beyond whitespace) — settled as the host's decision: they leave ${boxHandle} and are not handed over again`), { phase: "degraded", sessionId, classification: "peer-inbox-host-withheld" });
        }
        for (const effect of landed) {
            for (const [seq, d] of ledger) {
                if (d.kind !== "committed")
                    continue;
                if (effect.summarizedEntryIds === "unknown" || effect.summarizedEntryIds.has(d.entryId)) {
                    ledger.set(seq, { kind: "invalidated", attempt: d.attempt, payload: d.payload });
                }
            }
        }
        for (const [seq, d] of ledger) {
            if (d.kind === "invalidated" && d.attempt > PEER_RESUPPLY_CAP) {
                const meta = d.payload._sema_provenance?.peerMeta;
                disclose(lane, "resupply_exhausted", `attempt ${d.attempt} of ${PEER_RESUPPLY_CAP + 1} was summarized away too`, { seq, ...(meta !== undefined ? { peerMeta: meta } : {}) });
                ledger.set(seq, { kind: "resupply_exhausted" });
            }
        }
    };
    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 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);
                }
                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" });
                }
            }
            catch (e) {
                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-ack" });
            }
        }
    };
    const settleNoticeRecord = (facts, m, meta) => {
        const notice = meta.notice;
        const kind = meta.kind;
        const stateFits = notice !== undefined && (kind === "idle_notice" ? isPeerIdleNoticeKind(notice.state) : isPeerDeliveryReceiptState(notice.state));
        if (!stateFits) {
            disclose(sessionLane, "notice_unrouted", `kind=${kind}${notice === undefined ? " without a typed notice" : ` with state=${inlineUntrusted(notice.state, 32)}`}`, m);
            currentRound.dispose(sessionLane, m.seq, `notice_unrouted:${kind}`);
            return;
        }
        let text;
        if (kind === "idle_notice") {
            const idleKind = notice.state;
            const from = meta.fromSession;
            const selfAuthored = from !== undefined && from.toLowerCase() === sessionId.toLowerCase();
            const settled = from !== undefined && !selfAuthored ? idleMachine.requester.settle(from, idleKind) : { cleared: 0 };
            const label = (notice.target !== undefined ? peerIdleNoticeLabel(notice.target) : undefined) ?? settled.label ?? peerIdleNoticeLabel(m.from ?? storedSessionAddress(from) ?? "") ?? "(unnamed session)";
            text = renderCrossSessionIdleNotice({ kind: idleKind, label, ...(notice.finishedAt !== undefined ? { finishedAt: notice.finishedAt } : {}), ...(notice.detail !== undefined ? { detail: peerIdleNoticeLabel(notice.detail) ?? "" } : {}) });
        }
        else {
            const state = notice.state;
            const recipients = [notice.recipient ?? m.from ?? ""];
            text = state === "dropped" ? renderCrossSessionDroppedNotice(1, recipients, [notice.dropReason]) : renderCrossSessionDeliveryNotice(state, 1, recipients);
        }
        const judged = judgeMeta(facts, meta);
        if (judged.verdict === "refuse") {
            disclose(sessionLane, "refused", `${judged.cause} (a ${kind})`, m);
        }
        else if (judged.verdict === "hold") {
            disclose(sessionLane, "notice_user_only", `${judged.cause}: ${text}`, m);
        }
        else {
            currentRound.batch.push({ lane: sessionLane, payload: buildNoticePayload(m, kind, text), priority: "next", urgent: false, seq: m.seq, attempt: 1 });
            return;
        }
        currentRound.dispose(sessionLane, m.seq, judged.verdict === "refuse" ? "refused" : "notice_user_only");
    };
    const settleSubscription = (facts, m, meta) => {
        const requester = meta.fromSession;
        if (requester === undefined) {
            disclose(sessionLane, "notice_unrouted", "kind=idle_subscription without a reply address (fromSession)", m);
            currentRound.dispose(sessionLane, m.seq, "subscription_unaddressed");
            return;
        }
        const sub = { requester, ...(m.from !== undefined ? { requesterName: m.from } : {}), ...(meta.fromMode !== undefined ? { fromMode: meta.fromMode } : {}), selfSent: requester.toLowerCase() === sessionId.toLowerCase(), requestedAt: m.sentAt };
        const announce = (outcome, live) => deliverEngineNotice(opts.onNotice, {
            code: "peer.idle_subscription",
            message: outcome === "recorded" || outcome === "refreshed" ? `${describePeerIdleSubscription(encodePeerAddress(peerSessionBoxHandle(requester)))} (${outcome}; ${live} live)` : `A peer session at ${encodePeerAddress(peerSessionBoxHandle(requester))} asked to be told when this session is next idle and was answered "unavailable": ${outcome === "full" ? "this session's subscription table is full" : `this session's crossSessionInbound setting is "refuse"`}.`,
            detail: { outcome, fromSession: requester, live, seq: m.seq, box: boxHandle, sessionId, runId },
        });
        if (facts.setting.value === "refuse") {
            void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
            announce("refused", idleMachine.target.size());
            currentRound.dispose(sessionLane, m.seq, "subscription_refused");
            return;
        }
        const outcome = idleMachine.target.subscribe(sub);
        if (outcome === "full")
            void routePeerIdleNotice(route(), requester, { kind: "unavailable" });
        announce(outcome, idleMachine.target.size());
        currentRound.dispose(sessionLane, m.seq, `subscription_${outcome}`);
    };
    const countWaiting = (lane, lease) => {
        if (lease === null)
            return { pending: 0, urgent: 0 };
        const waiting = lease.messages.filter((m) => {
            if (lane.ackedUpTo !== undefined && m.seq <= lane.ackedUpTo)
                return false;
            const d = lane.ledger.get(m.seq);
            return d === undefined || d.kind === "invalidated";
        });
        return { pending: waiting.length, urgent: waiting.filter((m) => m.peerMeta?.urgent === true).length };
    };
    let warmedUp = opts.warmup === undefined;
    class DrainRound {
        limit;
        out;
        carrier;
        charBudget;
        injected = 0;
        tallies = new Map();
        tally(lane, attempt) {
            const t = this.tallies.get(lane) ?? { fresh: 0, resupplied: 0 };
            if (attempt > 1)
                t.resupplied += 1;
            else
                t.fresh += 1;
            this.tallies.set(lane, t);
        }
        deliveredIn(lane) {
            return this.tallies.get(lane) ?? { fresh: 0, resupplied: 0 };
        }
        dispose(lane, seq, why) {
            lane.ledger.set(seq, { kind: "terminal", why });
        }
        batch = [];
        chars = 0;
        constructor(limit, out, carrier, charBudget) {
            this.limit = limit;
            this.out = out;
            this.carrier = carrier;
            this.charBudget = charBudget;
        }
        get spent() {
            return this.injected + this.batch.length >= this.limit;
        }
        deliver(payload, priority) {
            if (this.spent)
                return "deferred";
            if (this.out !== undefined) {
                if (this.charBudget !== undefined) {
                    const size = renderTaskNotificationXml(payload).length;
                    if (this.out.length > 0 && this.chars + size > this.charBudget)
                        return "deferred";
                    this.chars += size;
                }
                this.out.push(payload);
            }
            else
                opts.inject(payload, { priority });
            this.injected += 1;
            return undefined;
        }
    }
    const drainRound = async (round, pass) => {
        if (!warmedUp) {
            warmedUp = true;
            try {
                await opts.warmup();
            }
            catch {
            }
        }
        const claims = [];
        for (const lane of lanes) {
            try {
                claims.push({ lane, lease: await mailbox.claimLease(scope, lane.boxHandle, drainOwner, ttl) });
            }
            catch (e) {
                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
            }
        }
        if (claims.length === 0)
            return { pending: 0, urgent: 0 };
        const waitingAcross = () => claims.reduce((sum, { lane, lease }) => {
            const c = countWaiting(lane, lease);
            return { pending: sum.pending + c.pending, urgent: sum.urgent + c.urgent };
        }, { pending: 0, urgent: 0 });
        if (pass.settle)
            settleLocally();
        if (pass.settle)
            for (const { lane, lease } of claims)
                if (lease !== null)
                    await ackSettledPrefix(lane, lease);
        if (!pass.deliver)
            return waitingAcross();
        let facts;
        let admissionConfig;
        try {
            facts = readFacts();
            admissionConfig = resolvePeerLaneConfig(opts.lane, opts.onNotice);
        }
        catch (e) {
            opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-settings" });
            return { pending: 0, urgent: 0 };
        }
        currentRound = round;
        try {
            idleMachine.target.sweep();
            const leased = claims.filter((c) => c.lease !== null);
            if (leased.length === 0)
                return { pending: 0, urgent: 0 };
            for (const { lane, lease } of leased) {
                bindHeld(lane, true);
                reconcileHeld(lane, lease);
                lane.held.rejudge();
            }
            try {
                for (const { lane, lease } of leased) {
                    const { ledger, disclosedHeld, held, boxHandle } = lane;
                    const ackedUpTo = lane.ackedUpTo;
                    for (const m of lease.messages) {
                        const prior = ledger.get(m.seq);
                        if (prior === undefined || prior.kind !== "invalidated")
                            continue;
                        if (round.spent)
                            break;
                        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;
                        if (ledger.has(m.seq))
                            continue;
                        if (round.spent)
                            break;
                        const meta = m.peerMeta;
                        if (lane.kind === "principal" && !isGateMintedRecord(meta)) {
                            disclose(lane, "admission_refused", PRINCIPAL_INBOX_UNMINTED_CAUSE, m);
                            round.dispose(lane, m.seq, `admission_refused:${PRINCIPAL_INBOX_UNMINTED_CAUSE}`);
                            continue;
                        }
                        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(lane, "held", verdict.reason, m, "it stays in the box; the inbound admission bucket is empty and it is re-judged at a later boundary once the bucket refills");
                                    }
                                    break;
                                }
                                disclose(lane, "admission_refused", verdict.reason, m);
                                round.dispose(lane, m.seq, `admission_refused:${verdict.reason}`);
                                continue;
                            }
                        }
                        if (meta?.kind === "idle_subscription") {
                            settleSubscription(facts, m, meta);
                            continue;
                        }
                        if (meta?.kind === "idle_notice" || meta?.kind === "delivery_notice") {
                            settleNoticeRecord(facts, m, meta);
                            continue;
                        }
                        if (meta?.kind === "engine_frame") {
                            const decoded = decodeEngineFrame(m.content);
                            if (!decoded.ok && decoded.reason === "newer") {
                                opts.onError?.(new Error(`engine_frame record seq ${m.seq} in ${boxHandle} carries codec version ${decoded.codecVersion}; this engine reads up to ${ENGINE_FRAME_CODEC_VERSION} — the box stops at that record until an engine that reads it drains the session`), { phase: "degraded", sessionId, classification: "peer-box-engine-frame" });
                                break;
                            }
                            if (!decoded.ok) {
                                disclose(lane, "notice_unrouted", `kind=engine_frame (${decoded.detail})`, m);
                                round.dispose(lane, m.seq, `engine_frame_malformed:${decoded.detail}`);
                                continue;
                            }
                            round.batch.push({ lane, payload: decoded.payload, priority: decoded.priority, urgent: false, seq: m.seq, attempt: 1 });
                            continue;
                        }
                        const sameTree = meta?.fromRoot !== undefined && meta.fromRoot.toLowerCase() === sessionId.toLowerCase();
                        if (!sameTree) {
                            const judged = judgeMeta(facts, meta);
                            if (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 (!ledger.has(m.seq))
                                    ledger.set(m.seq, { kind: "held" });
                                continue;
                            }
                        }
                        let payload;
                        try {
                            payload = buildPeerMessagePayload(lane, m);
                        }
                        catch (e) {
                            disclose(lane, "refused", `record fields cannot be rendered canonically (${e instanceof CrossSessionCodecError ? e.code : thrownText(e)})`, m);
                            round.dispose(lane, m.seq, "uncanonical_fields");
                            continue;
                        }
                        round.batch.push({ lane, payload, priority: "next", urgent: meta?.urgent === true, seq: m.seq, attempt: 1 });
                    }
                }
            }
            finally {
                const ordered = round.batch.splice(0).sort((a, b) => Number(b.urgent) - Number(a.urgent));
                for (const item of ordered) {
                    try {
                        if (round.deliver(item.payload, item.priority) === "deferred")
                            continue;
                    }
                    catch (e) {
                        opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
                        break;
                    }
                    noteDelivered(item.lane, item.seq, item.attempt, item.payload, round.carrier);
                }
            }
            for (const { lane, lease } of leased) {
                const counts = countWaiting(lane, lease);
                if (counts.pending === 0 || round.out !== undefined)
                    continue;
                const { boxHandle } = lane;
                const delivered = round.deliveredIn(lane);
                noticeRound += 1;
                try {
                    opts.inject({
                        task_id: `inbox:${boxHandle}`,
                        task_type: "background_agent",
                        status: "event",
                        seq: noticeRound,
                        summary: `inbox notice: ${counts.pending} cross-session message(s) waiting`,
                        inboxNotice: { pending: counts.pending, delivered: delivered.fresh, ...(delivered.resupplied > 0 ? { resupplied: delivered.resupplied } : {}), ...(counts.urgent > 0 ? { urgent: counts.urgent } : {}), box: boxHandle },
                        _sema_provenance: { kind: "inbox_notice", from: boxHandle, taskId: `inbox:${boxHandle}`, seq: noticeRound },
                    }, { priority: "next" });
                }
                catch (e) {
                    opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-inject" });
                }
            }
            return waitingAcross();
        }
        finally {
            currentRound = undefined;
        }
    };
    const boundPass = (pass) => async () => {
        await drainRound(new DrainRound(resolvePeerLaneConfig(opts.lane, opts.onNotice).maxMessagesPerRound, undefined), pass);
    };
    const serialize = (once) => {
        inFlight = inFlight.then(once, once);
        return inFlight;
    };
    const drain = () => serialize(boundPass({ settle: true, deliver: true }));
    const boundaryRound = (o) => serialize(boundPass({ settle: true, deliver: o.continues }));
    const pull = (limit, toolCallId, charBudget) => {
        const out = [];
        const bound = limit !== undefined && Number.isInteger(limit) && limit > 0 ? limit : resolvePeerLaneConfig(opts.lane, opts.onNotice).maxMessagesPerRound;
        let counts = { pending: 0, urgent: 0 };
        const once = async () => {
            counts = await drainRound(new DrainRound(bound, out, toolCallId !== undefined ? toolResultReceiptKey(toolCallId) : undefined, charBudget), { settle: false, deliver: true });
        };
        const settled = inFlight.then(once, once);
        inFlight = settled;
        return settled.then(() => ({ delivered: out, pending: counts.pending, urgent: counts.urgent }));
    };
    const finishOnce = async () => {
        const claimed = [];
        for (const lane of lanes) {
            try {
                claimed.push({ lane, lease: await mailbox.claimLease(scope, lane.boxHandle, drainOwner, ttl) });
            }
            catch (e) {
                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
            }
        }
        if (claimed.length > 0) {
            try {
                settleLocally();
                for (const { lane, lease } of claimed)
                    if (lease !== null)
                        await ackSettledPrefix(lane, lease);
            }
            catch (e) {
                opts.onError?.(e, { phase: "degraded", sessionId, classification: "peer-box-claim" });
            }
        }
        for (const lane of lanes) {
            lane.held.detachLeg();
            try {
                await mailbox.releaseLease(scope, lane.boxHandle, drainOwner);
            }
            catch {
            }
        }
    };
    const finish = () => {
        inFlight = inFlight.then(finishOnce, finishOnce);
        return inFlight;
    };
    return {
        drain,
        boundaryRound,
        pull,
        isBoxBacked: (payload) => {
            const p = payload;
            if (p === null || typeof p !== "object" || typeof p.task_id !== "string" || typeof p.status !== "string")
                return false;
            const key = taskNotificationDedupKey(p);
            for (const lane of lanes)
                for (const d of lane.ledger.values())
                    if (d.kind === "delivered" && d.key === key)
                        return true;
            return false;
        },
        finish,
        wantsCompactionEffects,
        busy: () => idleMachine.target.busy(),
        idle: (finishedAt) => idleMachine.target.idle(finishedAt),
        held: sessionLane.held,
        ...(lanes[1] !== undefined ? { principalHeld: lanes[1].held } : {}),
        idleMachine,
    };
}
function peerModeClassOf(refs) {
    return refs.askEffective !== undefined ? foldPermissionModeClass(refs.permissionMode?.(), refs.askEffective) : "unknown";
}
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: () => peerModeClassOf(args.refs),
        },
    };
}
export function listAgentsMountable(face) {
    return face.leaves({ name: LIST_AGENTS_TOOL_NAME, aliases: [LIST_AGENTS_TOOL_ALIAS] }) && listAgentsNameFree(face.specTools);
}
function listAgentsNameFree(specTools) {
    return !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 (!listAgentsNameFree(args.specTools))
        return undefined;
    args.toolEffects.set(LIST_AGENTS_TOOL_NAME, "read");
    args.toolEffects.set(LIST_AGENTS_TOOL_ALIAS, "read");
    return createListAgentsTool({
        ...(args.peerDirectory !== undefined ? { peerDirectory: args.peerDirectory } : {}),
        ...(args.freshWindowMs !== undefined ? { freshWindowMs: args.freshWindowMs } : {}),
        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 } : {}),
        ...(args.continuationTier !== undefined ? { continuationTier: args.continuationTier } : {}),
        ...(args.readSeats ?? {}),
    });
}
export function bindPeerSessionDrain(harness, opts) {
    const drain = createPeerSessionDrain(opts);
    const round = async () => {
        await drain.drain();
        return undefined;
    };
    harness.on("before_agent_start", async () => {
        drain.busy();
        return round();
    });
    harness.subscribe((event) => {
        if (event.type === "agent_end")
            return drain.finish().catch(() => undefined);
        if (event.type === "settled") {
            const nothingQueued = (event.nextTurnCount ?? 0) === 0 && event.undrainedSteerCount === undefined && event.undrainedFollowUpCount === undefined;
            let parked = false;
            try {
                parked = opts.parked?.() ?? false;
            }
            catch {
                parked = true;
            }
            if (nothingQueued && !parked)
                drain.idle(Date.now());
        }
        return undefined;
    });
    return drain;
}
export function bindPeerLaneDrain(harness, args) {
    const { deps } = args;
    let rowName;
    const lookupRowName = async () => {
        if (deps.peerDirectory === undefined)
            return;
        try {
            const rows = await deps.peerDirectory.listPeerSessions({ scope: args.scope });
            rowName = rows.find((r) => r.sessionId.toLowerCase() === args.sessionId.toLowerCase())?.name;
        }
        catch {
            rowName = undefined;
        }
    };
    const drain = bindPeerSessionDrain(harness, {
        mailbox: deps.mailboxStore,
        sessionId: args.sessionId,
        runId: args.runId,
        scope: args.scope,
        ...(terminalsDrainPrincipalInbox(deps) ? { principalInbox: true } : {}),
        inject: args.inject,
        ...(deps.peerLane !== undefined ? { lane: deps.peerLane } : {}),
        ownTokens: args.ownTokens,
        settingLayers: () => (typeof deps.crossSessionInbound === "function" ? deps.crossSessionInbound() : deps.crossSessionInbound),
        selfModeClass: () => peerModeClassOf(args.refs),
        dialogExpiry: () => (typeof deps.crossSessionDialogExpiry === "function" ? deps.crossSessionDialogExpiry() : deps.crossSessionDialogExpiry),
        selfName: () => rowName ?? args.selfName?.(),
        warmup: lookupRowName,
        ...(args.settlement !== undefined ? { settlement: args.settlement } : {}),
        ...(args.parked !== undefined ? { parked: args.parked } : {}),
        ...(args.lastTurnText !== undefined ? { lastTurnText: args.lastTurnText } : {}),
        ...(args.markExternalContent !== undefined ? { markExternalContent: args.markExternalContent } : {}),
        ...(deps.onNotice !== undefined ? { onNotice: deps.onNotice } : {}),
        ...(deps.onError !== undefined ? { onError: deps.onError } : {}),
    });
    args.refs.pull = (limit, toolCallId, charBudget) => drain.pull(limit, toolCallId, charBudget);
    args.refs.boundaryRound = (o) => drain.boundaryRound(o);
    args.refs.isBoxBacked = (payload) => drain.isBoxBacked(payload);
    if (args.settlement !== undefined)
        args.settlement.wantsEffects = () => drain.wantsCompactionEffects();
    return drain;
}