@sema-agent/core 7.54.1 → 7.56.0

package/dist/agents/cc-uds-peer-channel.js

@@ -0,0 +1,457 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer, Socket } from "node:net";
+import { chmod, lstat, mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve as resolvePath } from "node:path";
+import { CrossSessionCodecError, decodeCcPeerFrame } from "./cross-session-envelope.js";
+import { peerSendVerdictSeverity } from "./cross-session-judge.js";
+import { peerAxisToken, peerWireHopToken, resolvePeerLaneConfig } from "./peer-admission.js";
+import { judgePeerRecordFile, peerSessionBoxHandle, vetPeerRegistryDirectory } from "./peer-directory.js";
+import { defaultCcProcessProbe } from "./cc-peer-directory.js";
+import { CC_PEER_FIRST_LINE_DEADLINE_MS, CC_PEER_KEY_FILE_MAX_BYTES, CC_PEER_KEY_FILE_RE, CC_PEER_LINE_MAX_CHARS, CC_PEER_SEND_TIMEOUT_MS, CC_PEER_SOCKET_PATH_MAX_BYTES, CC_PEER_TOKEN_RE, ccPeerAddress, ccPeerKeyFileName, ccPeerSocketDigest, ccRegistrationRow, encodeCcAuthLine, encodeCcNudgeLine, encodeCcUserLine, parseCcPeerLine, } from "./cc-peer-wire.js";
+export class CcPeerChannelError extends Error {
+    code;
+    path;
+    constructor(code, message, path) {
+        super(message);
+        this.name = "CcPeerChannelError";
+        this.code = code;
+        if (path !== undefined)
+            this.path = path;
+    }
+}
+const LISTENING_SLOTS = new Set();
+const NUDGE_TIMEOUT_MS = 1_000;
+const STALE_PROBE_MS = 250;
+function errCode(e) {
+    const c = e?.code;
+    return typeof c === "string" ? c : undefined;
+}
+async function writeFileAtomic0600(path, text) {
+    const tmp = `${path}.tmp.${randomBytes(6).toString("hex")}`;
+    try {
+        await writeFile(tmp, text, { mode: 0o600, flag: "wx" });
+        await rename(tmp, path);
+    }
+    catch (e) {
+        await unlink(tmp).catch(() => undefined);
+        throw e;
+    }
+}
+function probeSocket(path, ms) {
+    return new Promise((resolve) => {
+        const s = new Socket();
+        const done = (answer) => {
+            s.destroy();
+            resolve(answer);
+        };
+        s.setTimeout(ms, () => done("unknown"));
+        s.once("connect", () => done("live"));
+        s.once("error", (e) => done(errCode(e) === "ECONNREFUSED" ? "stale" : "unknown"));
+        s.connect({ path });
+    });
+}
+export function createCcUdsPeerChannel(opts) {
+    const platform = opts.platform ?? process.platform;
+    const pid = opts.pid ?? process.pid;
+    const probe = opts.probe ?? defaultCcProcessProbe;
+    const now = opts.now ?? Date.now;
+    const uid = opts.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    const vetOpts = { ...(uid !== undefined ? { uid } : {}), platform };
+    let listening;
+    const ensureVettedDir = async (dir) => {
+        try {
+            await lstat(dir);
+        }
+        catch (e) {
+            if (errCode(e) !== "ENOENT")
+                throw e;
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+        }
+        const verdict = await vetPeerRegistryDirectory(dir, vetOpts);
+        if (!verdict.ok)
+            throw new CcPeerChannelError(verdict.code, `the directory ${verdict.path} is not one this engine can trust (${verdict.code}) — the socket lane was not opened`, verdict.path);
+    };
+    const vetPeerSocket = async (address) => {
+        if (platform === "win32")
+            return { ok: false, code: "peer_send.not_reachable", text: "the reference agent's socket lane is not available on this platform" };
+        if (!isAbsolute(address) || Buffer.byteLength(address) > CC_PEER_SOCKET_PATH_MAX_BYTES)
+            return { ok: false, code: "peer_send.invalid_target", text: `${JSON.stringify(address.slice(0, 120))} is not a usable local socket address` };
+        const verdict = await vetPeerRegistryDirectory(dirname(address), vetOpts);
+        if (!verdict.ok)
+            return { ok: false, code: "peer_send.invalid_target", text: `the peer's socket directory is not one this engine trusts (${verdict.code}: ${verdict.path})` };
+        let st;
+        try {
+            st = await lstat(address);
+        }
+        catch {
+            return { ok: false, code: "peer_send.not_reachable", text: "no socket exists at that address (the session is gone)" };
+        }
+        if (st.isSymbolicLink())
+            return { ok: false, code: "peer_send.invalid_target", text: "the peer's socket address is a link" };
+        if (!st.isSocket())
+            return { ok: false, code: "peer_send.invalid_target", text: "the peer's address is not a socket" };
+        return { ok: true };
+    };
+    const readPeerToken = async (address) => {
+        const digest = ccPeerSocketDigest(address);
+        let names;
+        try {
+            names = await readdir(opts.registryDir);
+        }
+        catch {
+            return undefined;
+        }
+        const candidates = names
+            .map((n) => ({ n, m: CC_PEER_KEY_FILE_RE.exec(n) }))
+            .filter((c) => c.m !== null && c.m[2] === digest)
+            .map((c) => ({ file: c.n, pid: Number.parseInt(c.m[1], 10) }))
+            .sort((a, b) => Number(probe.processExists(b.pid)) - Number(probe.processExists(a.pid)));
+        for (const c of candidates) {
+            const path = join(opts.registryDir, c.file);
+            try {
+                const st = await lstat(path);
+                if (!judgePeerRecordFile({ uid: st.uid, mode: st.mode, isFile: st.isFile(), size: st.size }, uid, platform).ok || st.size > CC_PEER_KEY_FILE_MAX_BYTES)
+                    continue;
+                const parsed = JSON.parse(await readFile(path, "utf8"));
+                const token = parsed !== null && typeof parsed === "object" ? parsed["peerToken"] : undefined;
+                if (typeof token === "string" && CC_PEER_TOKEN_RE.test(token))
+                    return token;
+            }
+            catch {
+            }
+        }
+        return undefined;
+    };
+    const send = (address, payload, timeoutMs) => new Promise((resolve) => {
+        const sock = new Socket();
+        let written = false;
+        let settled = false;
+        const settle = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            sock.destroy();
+            resolve(v);
+        };
+        sock.setTimeout(timeoutMs, () => settle(written ? { ok: false, code: "peer_send.send_uncertain", text: "the frame was written but the connection did not close in time — it may have arrived" } : { ok: false, code: "peer_send.timeout", text: `the peer did not accept the connection within ${timeoutMs} ms` }));
+        sock.once("error", (e) => {
+            const c = errCode(e);
+            if (written)
+                return settle({ ok: false, code: "peer_send.send_uncertain", text: `the frame was written, then the connection failed (${c ?? "error"}) — it may have arrived` });
+            if (c === "ENOENT")
+                return settle({ ok: false, code: "peer_send.not_reachable", text: "no socket exists at that address (the session is gone)" });
+            if (c === "ECONNREFUSED")
+                return settle({ ok: false, code: "peer_send.stale_socket", text: "the socket file is there but nothing is listening on it (the session ended)" });
+            if (c === "EAGAIN" || c === "EBUSY")
+                return settle({ ok: false, code: "peer_send.socket_busy", text: "the peer's socket is momentarily busy — retry shortly" });
+            return settle({ ok: false, code: "peer_send.other", text: `the connection failed (${c ?? "error"})` });
+        });
+        sock.once("connect", () => {
+            sock.write(payload, () => {
+                written = true;
+                sock.end();
+            });
+        });
+        sock.once("close", (hadError) => {
+            if (!hadError)
+                settle(written ? { ok: true } : { ok: false, code: "peer_send.send_uncertain", text: "the connection closed before the frame was confirmed written" });
+        });
+        sock.connect({ path: address });
+    });
+    const prepareSocketPath = async (socketPath) => {
+        await ensureVettedDir(dirname(socketPath));
+        await ensureVettedDir(opts.registryDir);
+        let existing;
+        try {
+            existing = await lstat(socketPath);
+        }
+        catch (e) {
+            if (errCode(e) !== "ENOENT")
+                throw e;
+        }
+        if (existing === undefined)
+            return;
+        const inUse = (why) => new CcPeerChannelError("address_in_use", `${socketPath} is in use (${why}) — the socket lane was not opened`, socketPath);
+        if (!existing.isSocket())
+            throw inUse("it is not a socket");
+        if (uid !== undefined && existing.uid !== uid)
+            throw inUse("another user's socket");
+        const state = await probeSocket(socketPath, STALE_PROBE_MS);
+        if (state !== "stale")
+            throw inUse(state === "live" ? "a process listens there" : "it could not be proven stale");
+        const again = await lstat(socketPath).catch(() => undefined);
+        if (again === undefined)
+            return;
+        if (again.ino !== existing.ino || again.dev !== existing.dev)
+            throw inUse("it changed while it was probed");
+        await unlink(socketPath);
+    };
+    const refusal = (code, text) => ({ ok: false, code, severity: peerSendVerdictSeverity(code), message: text });
+    return {
+        async listen(self) {
+            if (platform === "win32")
+                throw new CcPeerChannelError("unsupported_platform", "the reference agent's socket lane (its named-pipe arm) is not implemented on this platform — the socket lane was not opened");
+            if (listening !== undefined)
+                throw new CcPeerChannelError("already_listening", `this channel already listens at ${listening.address}`);
+            const socketPath = opts.socketPath;
+            if (!isAbsolute(socketPath) || Buffer.byteLength(socketPath) > CC_PEER_SOCKET_PATH_MAX_BYTES) {
+                throw new CcPeerChannelError("socket_path_too_long", `the socket path must be absolute and at most ${CC_PEER_SOCKET_PATH_MAX_BYTES} bytes (got ${Buffer.byteLength(socketPath)})`, socketPath);
+            }
+            const box = peerSessionBoxHandle(self.sessionId);
+            const laneConfig = resolvePeerLaneConfig(opts.lane);
+            const slot = `${pid}\u0000${resolvePath(opts.registryDir)}`;
+            if (LISTENING_SLOTS.has(slot))
+                throw new CcPeerChannelError("already_listening", `this process already listens through ${opts.registryDir} (its key file and registry row are named by the pid)`);
+            LISTENING_SLOTS.add(slot);
+            const release = (e) => {
+                LISTENING_SLOTS.delete(slot);
+                throw e;
+            };
+            await prepareSocketPath(socketPath).catch(release);
+            const token = randomBytes(16).toString("hex");
+            const tokenBytes = Buffer.from(token, "utf8");
+            const tokenMatches = (t) => {
+                if (t === undefined)
+                    return false;
+                const b = Buffer.from(t, "utf8");
+                return b.length === tokenBytes.length && timingSafeEqual(b, tokenBytes);
+            };
+            const emit = (event) => {
+                try {
+                    self.onEvent?.(event);
+                }
+                catch {
+                }
+            };
+            const drop = (reason, detail) => emit({ kind: "dropped", reason, ...(detail !== undefined ? { detail } : {}) });
+            let chain = Promise.resolve();
+            let pending = 0;
+            const enqueue = (work) => {
+                if (pending >= laneConfig.maxQueuedPeerMessages)
+                    return drop("box_full", `${pending} frames already waiting for the box`);
+                pending++;
+                chain = chain
+                    .then(work)
+                    .catch((e) => drop("append_failed", e instanceof Error ? e.message.slice(0, 200) : "error"))
+                    .then(() => {
+                    pending--;
+                });
+            };
+            const appendUser = async (line) => {
+                if (line.toSession !== undefined && line.toSession !== self.sessionId)
+                    return drop("session_mismatch");
+                if (line.attachments)
+                    return drop("unhandled_frame", "file_attachments");
+                let queued = 0;
+                try {
+                    queued = await opts.mailbox.peekCount(self.scope, box);
+                }
+                catch {
+                }
+                if (queued >= laneConfig.maxQueuedPeerMessages)
+                    return drop("box_full", `${queued} queued`);
+                const decoded = decodeCcPeerFrame(line.content);
+                const fields = decoded.ok ? decoded.fields : {};
+                const body = decoded.ok ? decoded.body : line.content;
+                const peerMeta = {
+                    ...(fields.fromSession !== undefined ? { fromSession: fields.fromSession, senderKey: peerAxisToken(self.scope, "s", fields.fromSession) } : {}),
+                    ...(fields.fromMode !== undefined ? { fromMode: fields.fromMode } : {}),
+                    kind: "peer_message",
+                };
+                const from = fields.fromName ?? line.from;
+                const seq = await opts.mailbox.append(self.scope, box, { ...(from !== undefined ? { from } : {}), content: body, sentAt: now(), hopChain: fields.hopChain !== undefined ? [...fields.hopChain] : [], peerMeta });
+                emit({ kind: "appended", seq });
+            };
+            const connections = new Set();
+            const deadlineMs = opts.firstLineDeadlineMs ?? CC_PEER_FIRST_LINE_DEADLINE_MS;
+            const server = createServer({ allowHalfOpen: true }, (sock) => {
+                connections.add(sock);
+                sock.setEncoding("utf8");
+                let timer = setTimeout(() => {
+                    timer = undefined;
+                    drop("first_line_deadline");
+                    sock.destroy();
+                }, deadlineMs);
+                timer.unref();
+                const clear = () => {
+                    if (timer !== undefined)
+                        clearTimeout(timer);
+                    timer = undefined;
+                };
+                let authed = false;
+                let buf = "";
+                const handle = (raw) => {
+                    if (raw.trim() === "") {
+                        if (authed)
+                            return true;
+                        drop("unauthenticated", "a blank line");
+                        return false;
+                    }
+                    const line = parseCcPeerLine(raw);
+                    if (!authed) {
+                        if (line.kind !== "auth") {
+                            drop("unauthenticated", line.kind === "malformed" ? line.why : `a '${line.kind}' line`);
+                            return false;
+                        }
+                        if (!tokenMatches(line.token)) {
+                            drop("bad_token");
+                            return false;
+                        }
+                        authed = true;
+                        return true;
+                    }
+                    switch (line.kind) {
+                        case "auth":
+                            return true;
+                        case "malformed":
+                            drop("malformed_line", line.why);
+                            return true;
+                        case "unhandled":
+                            drop("unhandled_frame", line.action !== undefined ? `${line.type}:${line.action}` : line.type);
+                            return true;
+                        case "nudge":
+                            enqueue(async () => {
+                                emit({ kind: "nudged" });
+                                try {
+                                    self.onNudge?.();
+                                }
+                                catch {
+                                }
+                            });
+                            return true;
+                        case "user":
+                            enqueue(() => appendUser(line));
+                            return true;
+                    }
+                };
+                sock.on("data", (chunk) => {
+                    buf += chunk;
+                    if (buf.length > CC_PEER_LINE_MAX_CHARS) {
+                        drop("line_too_long");
+                        buf = "";
+                        sock.destroy();
+                        return;
+                    }
+                    for (let nl = buf.indexOf("\n"); nl !== -1; nl = buf.indexOf("\n")) {
+                        const raw = buf.slice(0, nl);
+                        buf = buf.slice(nl + 1);
+                        clear();
+                        if (!handle(raw)) {
+                            buf = "";
+                            sock.destroy();
+                            return;
+                        }
+                    }
+                });
+                sock.on("end", () => {
+                    if (buf.trim() !== "" && !sock.destroyed) {
+                        clear();
+                        handle(buf);
+                    }
+                    buf = "";
+                    sock.end();
+                });
+                sock.on("error", () => undefined);
+                sock.on("close", () => {
+                    clear();
+                    connections.delete(sock);
+                });
+            });
+            server.on("error", () => undefined);
+            await new Promise((resolve, reject) => {
+                const onError = (e) => reject(errCode(e) === "EADDRINUSE" ? new CcPeerChannelError("address_in_use", `another process listens at ${socketPath}`, socketPath) : e);
+                server.once("error", onError);
+                server.listen(socketPath, () => {
+                    server.removeListener("error", onError);
+                    resolve();
+                });
+            }).catch(release);
+            server.unref();
+            const keyPath = join(opts.registryDir, ccPeerKeyFileName(pid, socketPath));
+            const rowPath = join(opts.registryDir, `${pid}.json`);
+            let closed = false;
+            const close = async () => {
+                if (closed)
+                    return;
+                closed = true;
+                listening = undefined;
+                LISTENING_SLOTS.delete(slot);
+                for (const s of connections)
+                    s.destroy();
+                connections.clear();
+                await new Promise((resolve) => server.close(() => resolve()));
+                await unlink(socketPath).catch(() => undefined);
+                await unlink(keyPath).catch(() => undefined);
+                await unlink(rowPath).catch(() => undefined);
+                await chain.catch(() => undefined);
+            };
+            try {
+                await chmod(socketPath, 0o600);
+                const procStart = await probe.processStartToken(pid);
+                await writeFileAtomic0600(keyPath, JSON.stringify({ peerToken: token, ...(procStart !== undefined ? { procStart } : {}) }));
+                const at = now();
+                const reg = opts.registration ?? {};
+                await writeFileAtomic0600(rowPath, JSON.stringify(ccRegistrationRow({
+                    pid,
+                    sessionId: self.sessionId,
+                    socketPath,
+                    startedAt: reg.startedAt ?? at,
+                    updatedAt: at,
+                    ...(reg.cwd !== undefined ? { cwd: reg.cwd } : {}),
+                    ...(reg.name !== undefined ? { name: reg.name } : {}),
+                    ...(reg.entrypoint !== undefined ? { entrypoint: reg.entrypoint } : {}),
+                    ...(procStart !== undefined ? { procStart } : {}),
+                    ...(typeof opts.mailbox.identity === "string" && opts.mailbox.identity !== "" ? { storeIdentity: opts.mailbox.identity } : {}),
+                })));
+            }
+            catch (e) {
+                await close();
+                throw new CcPeerChannelError("publish_failed", `the socket was bound but its key file or registry row could not be published (${errCode(e) ?? (e instanceof Error ? e.message : "error")}) — no peer could authenticate or find it, so the socket lane was closed`, opts.registryDir);
+            }
+            listening = { address: socketPath, sessionId: self.sessionId };
+            return { address: socketPath, close };
+        },
+        async dial(address, message) {
+            const vetted = await vetPeerSocket(address);
+            if (!vetted.ok)
+                return refusal(vetted.code, vetted.text);
+            let line;
+            try {
+                const from = listening !== undefined && message.fromSession === listening.sessionId ? ccPeerAddress(listening.address) : undefined;
+                line = encodeCcUserLine({
+                    fields: {
+                        ...(from !== undefined ? { from } : {}),
+                        ...(message.fromSession !== undefined ? { fromSession: message.fromSession } : {}),
+                        hopChain: message.hopChain.map(peerWireHopToken),
+                        ...(message.fromName !== undefined ? { fromName: message.fromName } : {}),
+                        ...(message.fromMode !== undefined ? { fromMode: message.fromMode } : {}),
+                    },
+                    body: message.body,
+                    ...(from !== undefined ? { from } : {}),
+                });
+            }
+            catch (e) {
+                if (e instanceof CrossSessionCodecError)
+                    return refusal("peer_send.other", `the frame could not be spelled (${e.code})`);
+                throw e;
+            }
+            if (encodeCcAuthLine("0".repeat(32)).length + line.length > CC_PEER_LINE_MAX_CHARS)
+                return refusal("peer_send.too_large", `the frame is ${line.length} characters; the peer's line wall is ${CC_PEER_LINE_MAX_CHARS}`);
+            const token = await readPeerToken(address);
+            const sent = await send(address, `${token !== undefined ? encodeCcAuthLine(token) : ""}${line}`, opts.sendTimeoutMs ?? CC_PEER_SEND_TIMEOUT_MS);
+            return sent.ok ? { ok: true, disposition: "delivered", via: "uds" } : refusal(sent.code, sent.text);
+        },
+        async nudge(address) {
+            try {
+                if (!(await vetPeerSocket(address)).ok)
+                    return false;
+                const token = await readPeerToken(address);
+                const sent = await send(address, `${token !== undefined ? encodeCcAuthLine(token) : ""}${encodeCcNudgeLine()}`, opts.nudgeTimeoutMs ?? NUDGE_TIMEOUT_MS);
+                return sent.ok;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/agents/child-model-seat.d.ts

@@ -18,17 +18,6 @@ export declare function deploymentStatesSubagentModel(roles: ModelRoles | undefi
  * already reflects when the parent ran on it).
  */
 export declare function deploymentSubagentThinking(roles: ModelRoles | undefined): ThinkingLevel | undefined;
-/**
- * Did the deployment STATE a system prompt for its subagents — and which? The `systemPrompt` member of an
- * object-form `roles.subagent` entry; a string ref, a `Model` object or an entry without the member states
- * none. The third axis, read off the SAME seat as {@link deploymentSubagentThinking}. It has no parent rung:
- * a child never inherits its PARENT's system prompt, only the deployment's statement for subagents. Which
- * station needs to read it: one whose default persona is written onto the spec itself (the workflow lane
- * frames an empty `systemPrompt` with the workflow-subagent persona, so the preset must be written first, as
- * a custom persona to that frame); the delegation station's default rides the trusted internals channel
- * below the role chain, so prepare reads the preset there without this helper.
- */
-export declare function deploymentSubagentSystemPrompt(roles: ModelRoles | undefined): string | undefined;
 /**
  * The child run's THINKING seat — {@link childModelSeat}'s sister, the same rung order on the other axis
  * (#651): an EXPLICIT level for this spawn wins (the agent definition's `thinking`; a fork's explicit is the

package/dist/agents/child-model-seat.js

@@ -23,9 +23,6 @@ export function deploymentStatesSubagentModel(roles) {
 export function deploymentSubagentThinking(roles) {
     return subagentRolePresets(roles)?.thinking;
 }
-export function deploymentSubagentSystemPrompt(roles) {
-    return subagentRolePresets(roles)?.systemPrompt;
-}
 function subagentRolePresets(roles) {
     const s = roles?.subagent;
     if (s == null || typeof s === "string")

package/dist/agents/cross-session-envelope.d.ts

@@ -128,12 +128,15 @@ export interface CcPeerFrameFields {
     hopChain?: string[];
     fromName?: string;
     fromMode?: PermissionModeClass;
+    /** The sending plugin's display name (CC 2.1.296 sixth attribute, (cli296.js:237185) "from-plugin", after `from-mode`; canonicalized like
+     *  `from-name`). Display only — the reference attributes a plugin's message by it, no judgment reads it. */
+    fromPlugin?: string;
 }
 /** CC `ygt` — the carry window: keep the newest 32. */
 export declare function clampHopChain(chain: readonly string[]): string[];
 /**
  * Serialize the CC wire envelope (what goes into a UDS user frame's `message.content`). Attribute
- * order `from` → `from-session` → `hop-chain` → `from-name` → `from-mode`. Unlike CC's own
+ * order `from` → `from-session` → `hop-chain` → `from-name` → `from-mode` → `from-plugin`. Unlike CC's own
  * constructor, which silently DROPS an ill-formed `from-session`/`hop-chain`, this throws on them: the
  * values are ours, and a producer bug must not become an attribute-less frame on the wire.
  * @throws CrossSessionCodecError

package/dist/agents/cross-session-envelope.js

@@ -170,6 +170,11 @@ export function encodeCcPeerFrame(fields, body) {
         assert(isPermissionModeClass(fields.fromMode), "cross_session.invalid_from_mode", `"from-mode" must be one of ${PERMISSION_MODE_CLASSES.join("|")}`);
         attrs.push(`from-mode="${fields.fromMode}"`);
     }
+    if (fields.fromPlugin !== undefined) {
+        const plugin = typeof fields.fromPlugin === "string" ? canonicalPeerDisplayName(fields.fromPlugin) : "";
+        if (plugin !== "")
+            attrs.push(`from-plugin="${plugin}"`);
+    }
     const header = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
     return `<${CROSS_SESSION_MESSAGE_TAG}${header}>\n${escapeEnvelopeTag(CROSS_SESSION_MESSAGE_TAG, body)}\n</${CROSS_SESSION_MESSAGE_TAG}>`;
 }
@@ -179,12 +184,13 @@ const CC_WIRE_RE = new RegExp(`^<${CROSS_SESSION_MESSAGE_TAG}` +
     `(?: hop-chain="(${HOP_CHAIN_RE.source.slice(1, -1)})")?` +
     `(?: from-name="([^"<>\\n\\r]+)")?` +
     `(?: from-mode="(bypass|prompting)")?` +
+    `(?: from-plugin="([^"<>\\n\\r]+)")?` +
     `>\\n([\\s\\S]*)\\n</${CROSS_SESSION_MESSAGE_TAG}>$`);
 export function decodeCcPeerFrame(text) {
     const m = CC_WIRE_RE.exec(text);
     if (m === null)
         return { ok: false, reason: "not_an_envelope" };
-    const [, from, fromSession, hopChain, fromName, fromMode, body] = m;
+    const [, from, fromSession, hopChain, fromName, fromMode, fromPlugin, body] = m;
     if (from !== undefined && !isCanonicalPeerAddress(from))
         return { ok: false, reason: "roundtrip_mismatch" };
     const fields = {
@@ -193,6 +199,7 @@ export function decodeCcPeerFrame(text) {
         ...(hopChain !== undefined ? { hopChain: hopChain.split(",") } : {}),
         ...(fromName !== undefined ? { fromName } : {}),
         ...(fromMode !== undefined ? { fromMode: fromMode } : {}),
+        ...(fromPlugin !== undefined ? { fromPlugin } : {}),
     };
     if (encodeCcPeerFrame(fields, body) !== text)
         return { ok: false, reason: "roundtrip_mismatch" };

package/dist/agents/cross-session-judge.d.ts

@@ -62,7 +62,7 @@ export declare function resolveCrossSessionInboundSetting(layers: CrossSessionIn
  */
 export declare function principalInboundLayers(layers: CrossSessionInboundSettingLayers): CrossSessionInboundSettingLayers;
 /**
- * Why a message was held. The first eight are CC 2.1.250's closed set (`sne`), reachable exactly
+ * Why a message was held. The first eight are the reference's closed set, reachable exactly
  * where CC reaches them. `invalid-mode-attestation` is a sema-only arm: CC's envelope parser drops a
  * non-vocabulary `from-mode` before any judgment (the state is unreachable there); sema receives the
  * attestation as a TYPED store/wire field, where a garbage value is a producer bug that must hold
@@ -73,7 +73,7 @@ export declare function principalInboundLayers(layers: CrossSessionInboundSettin
  */
 export type CrossSessionHoldCause = "mode-mismatch" | "no-mode-asserted" | "explicit-setting" | "managed-setting" | "repo-setting" | "invalid-setting" | "bypass-default" | "mode-unknown" | "invalid-mode-attestation" | "cross-principal-default";
 export declare const CROSS_SESSION_HOLD_CAUSES: readonly CrossSessionHoldCause[];
-/** CC `sne` verbatim for the eight CC causes; the sema arm has its own sentence. */
+/** The reference's wording for the eight inherited causes; the sema arm has its own sentence. */
 export declare function describeCrossSessionHoldCause(cause: CrossSessionHoldCause): string;
 export type CrossSessionInboundVerdict = {
     verdict: "deliver";

package/dist/agents/list-agents-tool.d.ts

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import type { TaskAccess } from "../core/task-registry.js";
 import { type RosterEntry } from "./roster-store.js";
-import { type PeerDirectory, type PeerPresence, type PeerSessionRecord } from "./peer-directory.js";
+import { type PeerDirectory, type PeerPresence, type PeerSessionRecord, type PeerSessionWhere } from "./peer-directory.js";
 import type { SubagentTranscriptTier } from "../core/wiring-manifest.js";
 import { formatAgo, type AgentState, type AgentStateSource } from "../core/agent-state.js";
 import type { CheckpointSeat } from "../core/checkpoint-seat.js";
@@ -89,6 +89,8 @@ export interface ListAgentsRow {
     cwd?: string;
     /** Peer rows: the session's self-reported presence, when it reported any. */
     presence?: PeerPresence;
+    /** Peer rows: where the session runs, as the directory's row says it ({@link PeerSessionWhere}). */
+    where?: PeerSessionWhere;
     /** What SendMessage accepts: on both AGENT lanes the registry `task_id` VERBATIM (no prefixing or
      *  re-minting), never the child's session id — a different domain, tabled in INTEGRATION-CORE §1.6a.
      *  Peer rows carry the `session.<id>` box handle instead. */

package/dist/agents/list-agents-tool.js

@@ -3,9 +3,9 @@ import { defineTool } from "../core/tools.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { formatPeerNameRef } from "./cross-session-ref.js";
 import { entryAccessible } from "./roster-store.js";
-import { mintPeerSessionCandidates, PEER_PRESENCE_MAX_CHARS, peerSessionBoxHandle } from "./peer-directory.js";
+import { listPeerDirectory, mintPeerSessionCandidates, PEER_PRESENCE_MAX_CHARS, PEER_SESSION_WHERE_LABELS, peerSessionBoxHandle } from "./peer-directory.js";
 import { PEER_LANE_DEFAULTS } from "./peer-admission.js";
-import { toolFace } from "../core/tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
 import { thrownText } from "../core/thrown-value.js";
 import { assertNoRetiredKeys } from "../core/retired-keys.js";
 import { agentActivityClause, agentApprovalClause, formatAgo, readAgentState } from "../core/agent-state.js";
@@ -45,8 +45,7 @@ const PEER_ROW_STATE = {
 function peerRowState(r) {
     if (r.liveness === "dead")
         return "offline";
-    const tempo = r.tempo;
-    return tempo !== undefined && Object.hasOwn(PEER_ROW_STATE, tempo) ? PEER_ROW_STATE[tempo] : "unknown";
+    return r.tempo !== undefined ? PEER_ROW_STATE[r.tempo] : "unknown";
 }
 function renderPresence(p) {
     const parts = [...(p.agent !== undefined ? [`agent=${inlineUntrusted(p.agent, PEER_PRESENCE_MAX_CHARS)}`] : []), ...(p.intent !== undefined ? [`intent=${inlineUntrusted(p.intent, PEER_PRESENCE_MAX_CHARS)}`] : [])];
@@ -62,10 +61,11 @@ export function createListAgentsTool(opts) {
     return defineTool({
         name: LIST_AGENTS_TOOL_NAME,
         ...toolFace("list-agents"),
+        ruleFace: mountRuleFace("list-agents"),
         isConcurrencySafe: () => true,
         description: `List the agents${peers ? " and peer sessions" : ""} you can message with SendMessage. ` +
             (peers
-                ? `Peer sessions are other sessions of this engine running for the same user, shown as \`name [ref] · state · active <N> ago · <directory> · self: agent=…, intent=…\`; send to one with its name (or \`name [ref]\` ` +
+                ? `Peer sessions are other sessions of this engine running for the same user, shown as \`name [ref] · state · active <N> ago · <directory> · self: agent=…, intent=… · peer session <where>\` (where it runs: ${Object.values(PEER_SESSION_WHERE_LABELS).join(", or ")}); send to one with its name (or \`name [ref]\` ` +
                     `when a name is ambiguous, or its \`session.<id>\` address). By default only FRESH peers are listed (working now, or active within the last ${formatAgo(windowMs)}); ` +
                     `pass includeAll: true to also list stale and offline ones. A peer that is offline or unlisted still accepts messages — they are parked ` +
                     `durably in its session box and delivered when it next runs. `
@@ -83,7 +83,7 @@ export function createListAgentsTool(opts) {
             let directoryFault;
             if (opts.peerDirectory !== undefined) {
                 try {
-                    peerRows = await opts.peerDirectory.listPeerSessions({ scope: opts.self.scope });
+                    peerRows = await listPeerDirectory(opts.peerDirectory, { scope: opts.self.scope });
                 }
                 catch (e) {
                     directoryFault = thrownText(e);
@@ -107,6 +107,7 @@ export function createListAgentsTool(opts) {
                     ...(r.liveness === "live" ? { lastActiveAt: r.updatedAt } : r.diedAt !== undefined ? { offlineAt: r.diedAt } : {}),
                     ...(r.cwd !== undefined ? { cwd: cwdTail(r.cwd) } : {}),
                     ...(presence.agent !== undefined || presence.intent !== undefined ? { presence } : {}),
+                    where: r.where,
                 });
             }
             let registryCapped = false;
@@ -171,13 +172,13 @@ export function createListAgentsTool(opts) {
                 const age = r.kind !== "peer_session" ? undefined : r.lastActiveAt !== undefined ? `active ${formatAgo(now - r.lastActiveAt)} ago` : r.offlineAt !== undefined ? `offline ${formatAgo(now - r.offlineAt)} ago` : "offline";
                 const activity = r.agentState !== undefined ? agentActivityClause(r.agentState) : undefined;
                 const approval = r.agentState?.approval !== undefined ? agentApprovalClause(r.agentState.approval, r.agentState.readAt) : undefined;
-                const cols = [label, r.state, age, activity, approval, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? "peer session" : r.kind === "roster" ? rosterLabel : "agent", r.address];
+                const cols = [label, r.state, age, activity, approval, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? `peer session ${PEER_SESSION_WHERE_LABELS[r.where]}` : r.kind === "roster" ? rosterLabel : "agent", r.address];
                 return cols.filter((c) => c !== undefined).join("  ·  ");
             });
             const finishedCount = rows.filter((r) => r.state === "finished").length;
             const header = rows.length === 0 ? "No agents or peer sessions are listed right now." : `${rows.length} listed:`;
             const finishedNote = finishedCount > 0 ? `\n(${finishedCount} finished agent(s): continuable by SendMessage only ${finishedReach} — otherwise SendMessage answers with an honest refusal)` : "";
-            const fault = (directoryFault !== undefined ? `\n(peer-session directory unreadable: ${inlineUntrusted(directoryFault, 200)} — peer rows may be missing)` : "") +
+            const fault = (directoryFault !== undefined ? `\n(peer-session directory unreadable: ${inlineUntrusted(directoryFault, 200)} — no peer row is listed until its host fixes it)` : "") +
                 (registryCapped ? "\n(the live task list is at its 500-row window: older background agents may be missing from this listing — address them by task_id)" : "");
             let content = `${header}${lines.length > 0 ? `\n${lines.join("\n")}` : ""}${finishedNote}${fault}`;
             if (content.length > LIST_AGENTS_MAX_RESULT_CHARS)