@sema-agent/core 7.1.0 → 7.2.0

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

@@ -0,0 +1,184 @@
+import { isPermissionModeClass } from "./cross-session-envelope.js";
+export const CROSS_SESSION_INBOUND_SETTINGS = Object.freeze(["accept", "hold", "refuse"]);
+export function isCrossSessionInboundSetting(value) {
+    return typeof value === "string" && CROSS_SESSION_INBOUND_SETTINGS.includes(value);
+}
+const RANK = { accept: 0, hold: 1, refuse: 2 };
+function readLayer(v) {
+    if (v === undefined || v === null || v === "default")
+        return undefined;
+    return isCrossSessionInboundSetting(v) ? v : "invalid";
+}
+export function resolveCrossSessionInboundSetting(layers) {
+    const invalidLayers = [];
+    let value;
+    let decidedBy;
+    for (const [name, raw] of [
+        ["managed", layers.managed],
+        ["user", layers.user],
+    ]) {
+        const v = readLayer(raw);
+        if (v === "invalid") {
+            invalidLayers.push(name);
+            continue;
+        }
+        if (v !== undefined && value === undefined) {
+            value = v;
+            decidedBy = name;
+        }
+    }
+    for (const raw of layers.repo ?? []) {
+        const v = readLayer(raw);
+        if (v === "invalid") {
+            invalidLayers.push("repo");
+            continue;
+        }
+        if (v === undefined)
+            continue;
+        if (RANK[v] > RANK[value ?? "accept"]) {
+            value = v;
+            decidedBy = "repo";
+        }
+        else if (v !== "accept" && value !== undefined && RANK[v] === RANK[value] && decidedBy !== "managed") {
+            decidedBy = "repo";
+        }
+    }
+    if (invalidLayers.length > 0 && RANK[value ?? "accept"] < RANK.hold) {
+        value = "hold";
+        decidedBy = "invalid";
+    }
+    return { ...(value !== undefined ? { value } : {}), ...(decidedBy !== undefined ? { decidedBy } : {}), invalidLayers };
+}
+export const CROSS_SESSION_HOLD_CAUSES = Object.freeze([
+    "mode-mismatch",
+    "no-mode-asserted",
+    "explicit-setting",
+    "managed-setting",
+    "repo-setting",
+    "invalid-setting",
+    "bypass-default",
+    "mode-unknown",
+    "invalid-mode-attestation",
+]);
+export function describeCrossSessionHoldCause(cause) {
+    switch (cause) {
+        case "mode-mismatch":
+            return "The sending session's permission mode class doesn't match this session's, so it wasn't delivered automatically.";
+        case "no-mode-asserted":
+            return "The sender did not attest its permission mode, and this session bypasses permission prompts.";
+        case "explicit-setting":
+            return 'Your "crossSessionInbound" setting is "hold".';
+        case "managed-setting":
+            return `Your organization's managed settings set "crossSessionInbound" to "hold".`;
+        case "repo-setting":
+            return `This repository's settings set "crossSessionInbound" to "hold" (your own "accept" cannot override a repo tightening).`;
+        case "invalid-setting":
+            return 'A settings file has an unrecognized "crossSessionInbound" value (see the settings warning), so messages are held while it is present.';
+        case "bypass-default":
+            return "This session is not prompting for permissions.";
+        case "mode-unknown":
+            return "This session's permission mode could not be determined.";
+        case "invalid-mode-attestation":
+            return "The sender attested an unrecognized permission mode, so the message is held for your review.";
+        default: {
+            const _exhaustive = cause;
+            void _exhaustive;
+            throw new Error(`unreachable hold cause ${String(cause)}`);
+        }
+    }
+}
+function describeUnknown(value) {
+    try {
+        const text = typeof value === "string" ? JSON.stringify(value) : typeof value === "bigint" ? `${value}n` : typeof value === "object" && value !== null ? JSON.stringify(value) : String(value);
+        return text.length > 80 ? `${text.slice(0, 80)}…` : text;
+    }
+    catch {
+        return `[unrenderable ${typeof value}]`;
+    }
+}
+function holdFor(cause, warning) {
+    return { verdict: "hold", cause, message: describeCrossSessionHoldCause(cause), ...(warning !== undefined ? { warning } : {}) };
+}
+function causeOf(decidedBy) {
+    switch (decidedBy) {
+        case "managed":
+            return "managed-setting";
+        case "repo":
+            return "repo-setting";
+        case "invalid":
+            return "invalid-setting";
+        case "user":
+        case undefined:
+            return "explicit-setting";
+        default: {
+            const _exhaustive = decidedBy;
+            void _exhaustive;
+            throw new Error(`unreachable setting source ${String(decidedBy)}`);
+        }
+    }
+}
+export function judgeCrossSessionInbound(input) {
+    const { setting, selfModeClass, sender } = input;
+    if (setting.value !== undefined) {
+        switch (setting.value) {
+            case "accept":
+                return { verdict: "deliver" };
+            case "refuse":
+                return { verdict: "refuse", cause: "opt-out" };
+            case "hold": {
+                const cause = causeOf(setting.decidedBy);
+                return holdFor(cause, cause === "invalid-setting" ? `unrecognized "crossSessionInbound" value in: ${setting.invalidLayers.join(", ")}` : undefined);
+            }
+            default: {
+                const _exhaustive = setting.value;
+                void _exhaustive;
+                throw new Error(`unreachable setting value ${String(setting.value)}`);
+            }
+        }
+    }
+    if (sender?.selfSent === true)
+        return { verdict: "deliver" };
+    if (selfModeClass === "unknown")
+        return holdFor("mode-unknown");
+    if (sender === undefined)
+        return selfModeClass === "bypass" ? holdFor("bypass-default") : { verdict: "deliver" };
+    if (sender.fromMode !== undefined) {
+        if (!isPermissionModeClass(sender.fromMode)) {
+            return holdFor("invalid-mode-attestation", `sender attested from-mode=${describeUnknown(sender.fromMode)} (expected bypass|prompting)`);
+        }
+        return sender.fromMode === selfModeClass ? { verdict: "deliver" } : holdFor("mode-mismatch");
+    }
+    return selfModeClass === "bypass" ? holdFor("no-mode-asserted") : { verdict: "deliver" };
+}
+export function foldPermissionModeClass(askEffective) {
+    switch (askEffective) {
+        case "auto_allow":
+            return "bypass";
+        case "human_reachable":
+        case "park_only":
+        case "auto_deny":
+            return "prompting";
+        case "unresolved":
+            return "unknown";
+        default: {
+            const _exhaustive = askEffective;
+            void _exhaustive;
+            throw new Error(`unreachable ask effective ${String(askEffective)}`);
+        }
+    }
+}
+export const PEER_SEND_VERDICT_CODES = Object.freeze([
+    "peer_send.stale_socket",
+    "peer_send.socket_busy",
+    "peer_send.too_large",
+    "peer_send.invalid_target",
+    "peer_send.timeout",
+    "peer_send.recipient_refuses",
+    "peer_send.not_reachable",
+    "peer_send.subscription_cap",
+    "peer_send.send_uncertain",
+    "peer_send.other",
+]);
+export function peerSendVerdictSeverity(code) {
+    return code === "peer_send.send_uncertain" || code === "peer_send.recipient_refuses" || code === "peer_send.subscription_cap" ? "degraded" : "error";
+}

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

@@ -0,0 +1,52 @@
+/** CC `aa` / `bmn`: a ref is 6..12 hex characters — the shortest prefix of `sha256(kind:id)` that is
+ *  unique against its sorted neighbours in the LISTING that minted it. */
+export declare const PEER_REF_MIN = 6;
+export declare const PEER_REF_MAX = 12;
+/** CC `Mz`. */
+export declare const PEER_REF_RE: RegExp;
+export interface PeerRefEntry {
+    /** The identity kind (`session`, `agent`, …): part of the hash input so two kinds with the same id
+     *  never share a ref. */
+    kind: string;
+    /** The durable id (a `session.<id>` box handle, an a* agent handle, …). */
+    id: string;
+}
+/**
+ * CC `K8` transcribed on sha256: mint the ref of EVERY entry of one listing. Refs are minted by the
+ * listing side and are valid only against that listing (a ref the model did not just read from a
+ * listing or a disambiguation error will not resolve). The optional `self` entry joins the
+ * disambiguation set (so no ref collides with the caller's own identity) but is not returned.
+ * The hash choice is local to this engine: a ref never crosses a process boundary, so the value
+ * domain (`[0-9a-f]{6,12}`) is what interoperates, not the digest.
+ */
+export declare function mintPeerRef<T extends PeerRefEntry>(entries: readonly T[], self?: PeerRefEntry): Array<T & {
+    ref: string;
+}>;
+/** CC `qN` — the display token. */
+export declare function formatPeerNameRef(name: string, ref: string): string;
+/** CC `V8`/`DO` — split a `name [ref]` token; `undefined` when no ref suffix is present. */
+export declare function parsePeerNameRef(text: string): {
+    name: string;
+    ref: string;
+} | undefined;
+/**
+ * CC `dr` — the MATCHING key of a peer/session name: NFKC → strip control/format code points → trim →
+ * lower-case → collapse whitespace runs to `-`. Every terminal resolves and compares names on this
+ * key (a display name is never the key).
+ */
+export declare function normalizePeerName(name: string): string;
+/** The box-address prefixes of design/385 (`session.<id>` per-session box, `principal.<…>` the
+ *  cross-principal inbox family). Reserved: a NAME may never spell an address. */
+export declare const PEER_ADDRESS_PREFIXES: readonly string[];
+/**
+ * design/385 §2.2 namespace protection (CC `qd` in spirit): a candidate spawn/session name is refused
+ * when its normalized key would shadow an explicit address — a reserved box prefix, a transport
+ * scheme (`uds:` / `bridge:` / `did:`), a socket path, an `@`-bearing team form, or the `*`
+ * broadcast token. Returns the reason, or `undefined` when the name is admissible. Registration-side
+ * check (loud refusal at write time); the resolution ladder ranks explicit addresses first regardless.
+ *
+ * The socket-path arm is judged on the RAW name AND on its normalized key (CC `QHe` runs its
+ * classifier over both): a name that is a socket path in either spelling is refused, since the
+ * resolution ladder would read the raw spelling as an address.
+ */
+export declare function reservedPeerNameReason(name: string): "empty" | "address_prefix" | "transport_scheme" | "socket_path" | "at_sign" | "wildcard" | undefined;

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

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+export const PEER_REF_MIN = 6;
+export const PEER_REF_MAX = 12;
+export const PEER_REF_RE = /^[0-9a-f]{6,12}$/;
+function refHash(e) {
+    return createHash("sha256").update(`${e.kind}:${e.id}`).digest("hex");
+}
+function commonPrefixLen(a, b) {
+    let n = 0;
+    while (n < a.length && n < b.length && a[n] === b[n])
+        n++;
+    return n;
+}
+export function mintPeerRef(entries, self) {
+    const hashes = entries.map(refHash);
+    const universe = [...new Set([...hashes, ...(self !== undefined ? [refHash(self)] : [])])].sort();
+    const lengths = new Map();
+    for (let i = 0; i < universe.length; i++) {
+        const h = universe[i];
+        const shared = Math.max(i > 0 ? commonPrefixLen(h, universe[i - 1]) : 0, i + 1 < universe.length ? commonPrefixLen(h, universe[i + 1]) : 0);
+        lengths.set(h, Math.min(h.length, Math.max(PEER_REF_MIN, shared + 1)));
+    }
+    return entries.map((e, i) => {
+        const h = hashes[i];
+        return { ...e, ref: h.slice(0, Math.min(lengths.get(h), PEER_REF_MAX)) };
+    });
+}
+export function formatPeerNameRef(name, ref) {
+    return `${name} [${ref}]`;
+}
+export function parsePeerNameRef(text) {
+    const m = /^(.*\S)\s*\[([0-9a-f]{6,12})\]$/.exec(text.trim());
+    return m === null ? undefined : { name: m[1], ref: m[2] };
+}
+export function normalizePeerName(name) {
+    return name
+        .normalize("NFKC")
+        .replace(/[\p{Cc}\p{Cf}]/gu, "")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "-");
+}
+export const PEER_ADDRESS_PREFIXES = Object.freeze(["session.", "principal."]);
+const SOCKET_PATH_RE = /^\/\S*\.sock/;
+const NAMED_PIPE_RE = /^[\\/]{2}[.?][\\/]pipe[\\/]/i;
+function isSocketPathSpelling(text) {
+    return SOCKET_PATH_RE.test(text) || NAMED_PIPE_RE.test(text);
+}
+export function reservedPeerNameReason(name) {
+    const key = normalizePeerName(name);
+    if (key === "")
+        return "empty";
+    if (key === "*")
+        return "wildcard";
+    if (key.includes("@"))
+        return "at_sign";
+    if (PEER_ADDRESS_PREFIXES.some((p) => key.startsWith(p)))
+        return "address_prefix";
+    if (/^(?:uds|bridge|did):/.test(key))
+        return "transport_scheme";
+    if (isSocketPathSpelling(name) || isSocketPathSpelling(key))
+        return "socket_path";
+    return undefined;
+}

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

@@ -44,6 +44,19 @@ export interface SendMessageToolOptions {
      *  this run's process exits when the turn ends, so no completion notification can ever land — checked
      *  AHEAD of {@link notificationWired}, since no amount of wiring makes a later turn exist. */
     oneShot?: boolean;
+    /**
+     * Whether a RETRIEVAL tool (`TaskOutput`) is mounted beside this tool on the same face. Every
+     * degraded completion promise on this face (the one-shot and silent arms of the description and
+     * the receipt/refusal texts) tells the model how to collect a continued agent's result; naming
+     * `TaskOutput(task_id, block: true)` as an imperative is only true where that tool exists. Since
+     * design/385 §1.5 this tool also mounts on the delegated-child arm WITHOUT the background door
+     * TaskOutput/TaskStop keep, so the two can no longer be assumed to travel together. Three states:
+     * `true` — the advice names TaskOutput plainly; `false` — this face has no retrieval tool, and the
+     * advice says the result cannot be collected by this run instead of naming a tool the model cannot
+     * call (an unknown-tool error on a one-shot run is the turn where the result is lost); absent — the
+     * mount did not say, and the advice is hedged ("where that tool is mounted").
+     */
+    retrievalToolMounted?: boolean;
     /** Steer-handle sink: the revived run re-emits a FRESH handle (design/122 risk-table contract). */
     sink?: (handle: SubagentSteerHandle) => void;
     /**

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

@@ -6,6 +6,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../core/mailbox-store.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
+import { neutralizePeerBody } from "./cross-session-envelope.js";
 import { SUBAGENT_RESUME_CAP, SubagentRetainLedger, getSessionRetainLedger } from "./retain-ledger.js";
 import { createSubagentResume } from "./subagent.js";
 import { appendHopToken, judgePeerAdmission, peerAxisToken, resolvePeerAdmissionConfig, PEER_MESSAGE_NOTICE, } from "./peer-admission.js";
@@ -24,7 +25,7 @@ export function clipSendMessageSummary(raw) {
 const TEAMMATE_MESSAGE_TAG = "teammate-message";
 function frameTeammateMessage(args) {
     const summaryAttr = args.summary !== undefined ? ` summary="${escapeAttributeValue(args.summary)}"` : "";
-    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, args.text);
+    const body = escapeEnvelopeTag(TEAMMATE_MESSAGE_TAG, neutralizePeerBody(args.text));
     return `<${TEAMMATE_MESSAGE_TAG} teammate_id="${escapeAttributeValue(args.from)}"${summaryAttr}>\n${body}\n</${TEAMMATE_MESSAGE_TAG}>`;
 }
 const REVIVE_LEASE_TTL_MS = 5 * 60_000;
@@ -46,21 +47,36 @@ function targetLaneKey(scope, targetId) {
 const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    const retrievalMounted = opts.retrievalToolMounted;
+    const retrievalHedge = retrievalMounted === undefined ? " (where that tool is mounted)" : "";
+    const RETRIEVE_NOW = retrievalMounted === false
+        ? "its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not wait for it, and say so in your answer if the result matters"
+        : `retrieve its result NOW with TaskOutput(task_id, block: true)${retrievalHedge} rather than ending your turn`;
+    const RETRIEVE_LATER = retrievalMounted === false
+        ? "its result cannot be collected by this run (no TaskOutput is mounted beside this tool)"
+        : "retrieve its status and result with TaskOutput(task_id) where mounted";
+    const WAIT_NOW = retrievalMounted === false
+        ? "do not wait for it — this face has no TaskOutput to block on, and"
+        : `wait for it NOW with TaskOutput(task_id, block: true)${retrievalHedge} —`;
+    const CHECK_LATER = retrievalMounted === false
+        ? "its completion cannot be checked from this face (no TaskOutput is mounted beside this tool)"
+        : "check for its completion with TaskOutput(task_id) where mounted";
+    const capitalize = (text) => `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
     const completionMode = opts.oneShot === true ? "one_shot" : (opts.notificationWired ?? opts.notify !== undefined) ? "notified" : "silent";
     const notifyWired = completionMode === "notified";
     const NO_COMPLETION_NOTICE = completionMode === "one_shot"
-        ? "this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so retrieve its result NOW with TaskOutput(task_id, block: true) rather than ending your turn"
-        : "its completion is NOT announced on this mount — retrieve its status and result with TaskOutput(task_id) where mounted";
+        ? `this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so ${RETRIEVE_NOW}`
+        : `its completion is NOT announced on this mount — ${RETRIEVE_LATER}`;
     const AWAIT_COMPLETION = notifyWired
         ? "Wait for its completion notification"
         : completionMode === "one_shot"
-            ? "Wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
-            : "Check for its completion with TaskOutput(task_id) where mounted";
+            ? `${capitalize(WAIT_NOW)} this one-shot submission ends with this turn`
+            : capitalize(CHECK_LATER);
     const awaitCompletion = notifyWired
         ? "wait for its completion notification"
         : completionMode === "one_shot"
-            ? "wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
-            : "check for its completion with TaskOutput(task_id) where mounted";
+            ? `${WAIT_NOW} this one-shot submission ends with this turn`
+            : CHECK_LATER;
     const sendMessagePins = new Map();
     const pinGuard = (targetId, targetName, rung, to) => {
         if (rung === "other")
@@ -104,8 +120,12 @@ export function createSendMessageTool(opts) {
             (notifyWired
                 ? `You will be notified automatically when it completes — prefer ending your turn; do not poll. `
                 : completionMode === "one_shot"
-                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one — wait actively with TaskOutput(task_id, block: true) when you need a continued agent's result. `
-                    : `A finished agent is NOT announced on this mount — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes. `) +
+                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one${retrievalMounted === false
+                        ? "; a continued agent's result cannot be collected by this run (no TaskOutput is mounted beside this tool) — say so if the result matters"
+                        : ` — wait actively with TaskOutput(task_id, block: true)${retrievalHedge} when you need a continued agent's result`}. `
+                    : `A finished agent is NOT announced on this mount${retrievalMounted === false
+                        ? ", and its result cannot be collected by this run (no TaskOutput is mounted beside this tool) — do not end your turn to wait for a notification that never comes"
+                        : " — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes"}. `) +
             (tier3Capable
                 ? `Continuing a finished agent works for agents with a durable record — by name or task_id, even across restarts — and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
                 : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
@@ -191,15 +211,19 @@ export function createSendMessageTool(opts) {
                         if (!verdict.ok)
                             return admissionRefusal(verdict.reason, "main");
                     }
+                    const uplinkBody = message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message;
+                    const uplinkSeq = ++uplinkSeqGlobal;
                     try {
                         opts.uplink({
                             task_id: senderId,
                             task_type: "background_agent",
                             status: "event",
                             summary: `message from ${senderLabel}: ${summary}`,
-                            result: `${message.length > UPLINK_RESULT_MAX ? `${message.slice(0, UPLINK_RESULT_MAX)}\n[uplink truncated: ${message.length} chars total — read the agent's transcript for the rest]` : message}\n\n${PEER_MESSAGE_NOTICE}`,
-                            seq: ++uplinkSeqGlobal,
+                            result: `${uplinkBody}\n\n${PEER_MESSAGE_NOTICE}`,
+                            seq: uplinkSeq,
                             peer: { hopChain: prospectiveChain },
+                            agentMessage: { from: senderLabel, body: uplinkBody },
+                            _sema_provenance: { kind: "agent_message", from: senderLabel, taskId: senderId, seq: uplinkSeq },
                         }, { priority: "next" });
                     }
                     catch (e) {
@@ -207,7 +231,7 @@ export function createSendMessageTool(opts) {
                     }
                     return {
                         content: `Message sent to main — queued for the spawning conversation at its next turn boundary. If that conversation finishes before reading it, the message may not survive. Continue with your task; do not wait for a reply.`,
-                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeqGlobal },
+                        details: { type: "send-message", status: "uplinked", to: "main", seq: uplinkSeq },
                     };
                 }
                 if (!senderIsChild) {