@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/mailbox-store.d.ts

@@ -18,7 +18,56 @@ export interface MailboxMessage {
      *  ABSENT = a pre-385 or foreign record (same semantics as an absent `hopChain`): the drain treats it
      *  as foreign, never retro-admits it. Validated at `append` ({@link readMailboxPeerMeta}). */
     peerMeta?: MailboxPeerMeta;
+    /** The record's HOLD DECISION ({@link MailboxDecision}): absent = never held. Never appended — it
+     *  starts absent and moves only through {@link MailboxStore.moveDecision}; every lease snapshot
+     *  carries it, so every consumer of the box reads the same decision. */
+    decision?: MailboxDecision;
 }
+/**
+ * A parked record's hold decision — the durable answer about a record a recipient's setting put on
+ * hold, kept ON the record so every consumer of the box (another terminal, another process, the session's
+ * next run) reads the same answer. `held` — waiting for a person; `approved` — a person approved it, not yet
+ * handed over; `delivered` — a consumer holding the lease took the move and handed it over (a later
+ * answer about it learns that instead of claiming a decision); `denied` / `expired` / `refused` /
+ * `dropped` — final: the record is never delivered and only waits for the ack that removes it.
+ */
+export declare const MAILBOX_DECISIONS: readonly ["held", "approved", "delivered", "denied", "expired", "refused", "dropped"];
+export type MailboxDecision = (typeof MAILBOX_DECISIONS)[number];
+/** A stored decision word as a reader takes it: a word this engine does not know (a newer engine's) reads
+ *  as `held` — never delivered on a guess, and left for a person (or that newer engine) to decide. */
+export declare function readStoredMailboxDecision(raw: unknown): MailboxDecision | undefined;
+/** The refusal code of a malformed {@link MailboxStore.moveDecision} call (a word outside the
+ *  closed set, a non-positive seq, or an edge the decision law does not allow). */
+export declare const MAILBOX_INVALID_DECISION_MOVE_CODE = "mailbox.invalid_decision_move";
+export declare function isMailboxDecision(value: unknown): value is MailboxDecision;
+/** Final states: the record is never delivered again, by any consumer. */
+export declare function isMailboxDecisionFinal(state: MailboxDecision | undefined): boolean;
+/** Deliverable states: a consumer holding the lease delivers the record (a setting that now refuses still wins). */
+export declare function isMailboxDecisionDeliverable(state: MailboxDecision | undefined): boolean;
+/**
+ * THE decision law — a decision only moves forward, and every hand-over of a held record is itself a move:
+ * absent → `held`; `held` → `approved` / `delivered` / `denied` / `expired` / `refused`; `approved` →
+ * `delivered` or a final state; `delivered` → `dropped` (the handed-over frame was refused by policy inside a lease-holding pass) only;
+ * a final state never moves.
+ */
+export declare function mailboxDecisionEdgeAllowed(from: MailboxDecision | undefined, to: MailboxDecision): boolean;
+/** What {@link MailboxStore.moveDecision} answers: the move happened, or the record's actual state
+ *  (`unset` = never held, `gone` = no such record any more — acked, reaped or dropped). */
+export type MailboxDecisionOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly current: MailboxDecision | "unset" | "gone";
+};
+/**
+ * THE caller-side reading of {@link MailboxStore.moveDecision}: a fault can arrive AFTER the move
+ * committed (a lock release that failed, a reply lost on the wire), so a call that throws is asked once
+ * more, and a store that already holds `next` answers the first call's success. A second fault throws.
+ * Every engine-side decision move goes through this one function.
+ */
+export declare function moveMailboxDecision(store: Pick<MailboxStore, "moveDecision">, scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
+/** The one validator every backend runs BEFORE touching storage: a malformed call has zero side effects. */
+export declare function assertMailboxDecisionMove(seq: unknown, expect: unknown, next: unknown): void;
 /** design/385 — the typed peer-metadata record on a parked message. ONE optional object, one-time
  *  contract extension; every field optional. Bundled backends persist it verbatim and hand back a
  *  detached copy. */
@@ -132,7 +181,7 @@ export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tomb
  * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
  * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
  */
-export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE;
+export type MailboxStoreErrorCode = typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE | typeof MAILBOX_INVALID_PEER_META_CODE | typeof MAILBOX_CROSS_PROCESS_UNSAFE_CODE | typeof MAILBOX_INVALID_DECISION_MOVE_CODE;
 export declare class MailboxStoreError extends Error {
     readonly code: MailboxStoreErrorCode;
     constructor(code: MailboxStoreErrorCode, message: string);
@@ -241,6 +290,17 @@ export interface MailboxStore {
      * Implementations report `{acked:true}` only when they actually consumed the prefix.
      */
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
+    /**
+     * Move one record's hold decision from `expect` (absent = never held) to `next`, atomically
+     * against every other transition and against `ack` — the compare-and-set every decision about a held
+     * record goes through. NOT fenced by the lease: a person answers from whichever process shows the
+     * record, whether or not it holds the box. A state that is not `expect` answers `{ ok: false, current }`
+     * and changes nothing; a record no longer in the box answers `current: "gone"`. A malformed call (see
+     * {@link assertMailboxDecisionMove}) is refused with {@link MAILBOX_INVALID_DECISION_MOVE_CODE}
+     * before any side effect. The state is durable like the record, and `ack` / `reap` / `drop` remove it
+     * with the record.
+     */
+    moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     /** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
     peekCount(scope: string, handle: string): Promise<number>;
@@ -291,6 +351,7 @@ export declare class InMemoryMailboxStore implements MailboxStore {
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
+    moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/core/mailbox-store.js

@@ -1,4 +1,53 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
+export const MAILBOX_DECISIONS = Object.freeze(["held", "approved", "delivered", "denied", "expired", "refused", "dropped"]);
+export function readStoredMailboxDecision(raw) {
+    if (raw === undefined)
+        return undefined;
+    return isMailboxDecision(raw) ? raw : "held";
+}
+export const MAILBOX_INVALID_DECISION_MOVE_CODE = "mailbox.invalid_decision_move";
+export function isMailboxDecision(value) {
+    return typeof value === "string" && MAILBOX_DECISIONS.includes(value);
+}
+export function isMailboxDecisionFinal(state) {
+    return state === "denied" || state === "expired" || state === "refused" || state === "dropped";
+}
+export function isMailboxDecisionDeliverable(state) {
+    return state === "approved" || state === "delivered";
+}
+export function mailboxDecisionEdgeAllowed(from, to) {
+    if (from === undefined)
+        return to === "held";
+    if (from === "held")
+        return to === "approved" || to === "delivered" || to === "denied" || to === "expired" || to === "refused";
+    if (from === "approved")
+        return to === "delivered" || isMailboxDecisionFinal(to);
+    if (from === "delivered")
+        return to === "dropped";
+    return false;
+}
+export async function moveMailboxDecision(store, scope, handle, seq, expect, next) {
+    try {
+        return await store.moveDecision(scope, handle, seq, expect, next);
+    }
+    catch {
+        const again = await store.moveDecision(scope, handle, seq, expect, next);
+        return !again.ok && again.current === next ? { ok: true } : again;
+    }
+}
+export function assertMailboxDecisionMove(seq, expect, next) {
+    const refuse = (why) => {
+        throw new MailboxStoreError(MAILBOX_INVALID_DECISION_MOVE_CODE, `MailboxStore.moveDecision: ${why}`);
+    };
+    if (typeof seq !== "number" || !Number.isInteger(seq) || seq < 1)
+        refuse(`seq must be a positive integer (got ${String(seq)})`);
+    if (expect !== undefined && !isMailboxDecision(expect))
+        refuse(`expect must be absent or one of ${MAILBOX_DECISIONS.join("|")}`);
+    if (!isMailboxDecision(next))
+        refuse(`next must be one of ${MAILBOX_DECISIONS.join("|")}`);
+    if (!mailboxDecisionEdgeAllowed(expect, next))
+        refuse(`${String(expect ?? "unset")} → ${String(next)} is not a decision move (a decision only moves forward)`);
+}
 export const MAILBOX_PEER_FROM_MODES = Object.freeze(["bypass", "prompting"]);
 export const MAILBOX_PEER_RECORD_KINDS = Object.freeze(["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"]);
 export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"]);
@@ -184,6 +233,16 @@ export class InMemoryMailboxStore {
             b.lease = undefined;
         return { acked: true };
     }
+    async moveDecision(scope, handle, seq, expect, next) {
+        assertMailboxDecisionMove(seq, expect, next);
+        const m = this.boxes.get(this.key(scope, handle))?.messages.find((x) => x.seq === seq);
+        if (m === undefined)
+            return { ok: false, current: "gone" };
+        if (m.decision !== expect)
+            return { ok: false, current: m.decision ?? "unset" };
+        m.decision = next;
+        return { ok: true };
+    }
     async releaseLease(scope, handle, owner) {
         const b = this.boxes.get(this.key(scope, handle));
         if (b?.lease?.owner === owner)

package/dist/core/mcp-name-judge.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One declared server, as far as its names go: `McpServerSpec` fits as it is. `tools` are the server's REMOTE tool names the asker
+ * already knows (a listing, a host's reading of one — never the minted `mcp__…` names); absent means none are known.
+ */
+export interface McpNameSetServer {
+    readonly name: string;
+    readonly tools?: readonly string[];
+}
+/**
+ * One contention: `names` are the two sources, the earlier one first (server names for `server_name`; the remote tool names for
+ * `tool_name`, where `server` says whose); `shared` is the name they mint — the prefix for `server_name`, the wire name for `tool_name`.
+ */
+export type McpNameConflict = {
+    readonly kind: "server_name";
+    readonly names: readonly [string, string];
+    readonly shared: string;
+} | {
+    readonly kind: "tool_name";
+    readonly server: string;
+    readonly names: readonly [string, string];
+    readonly shared: string;
+};
+/** The judge's answer: `ok`, or EVERY contention in the set — server rows first, then tool rows, each in declaration order; never empty. */
+export type McpNameVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly conflicts: readonly [McpNameConflict, ...McpNameConflict[]];
+};
+/** Judge a declared set. Pure: reads nothing but the names it is handed; a malformed set is refused (`config.invalid_argument`), never read as clean. */
+export declare function judgeMcpNames(servers: readonly McpNameSetServer[]): McpNameVerdict;
+/**
+ * The sentence that says why a tool of one server is not mounted under its own name: `heldBy` is the raw name that took the wire
+ * name `minted` first, `tool` the raw name that came after. TWO FACTS, TWO SENTENCES (a fixed label must not head more than one
+ * cause): the same raw name listed again, where namespacing folded nothing, and two different raw names that fold onto one name.
+ * It carries no raw name — the caller's own field says which tool.
+ */
+export declare function mcpToolDropReason(minted: string, heldBy: string, tool: string): string;
+/** One row as a sentence — the one the engine refuses a run with (`server_name`) or discloses a drop with (`tool_name`). Names are quoted single-line and bounded. */
+export declare function describeMcpNameConflict(conflict: McpNameConflict): string;
+/**
+ * The refusal of a declared set whose server names do not each own a namespace domain — thrown by the mount and by the no-run probe,
+ * so one set is refused with one code and one sentence wherever it is asked. It takes the NAMES only (a run's refusal reads no
+ * tool list); the FIRST `server_name` row speaks, naming both raw spellings.
+ */
+export declare function refuseCollidingMcpServerNames(serverNames: readonly string[]): void;

package/dist/core/mcp-name-judge.js

@@ -0,0 +1,61 @@
+import { MCP_NAMESPACE } from "./protocol-table.js";
+import { createToolNameClaims, findNamespacePrefixCollisions } from "./protocol-naming.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+function refuseArgument(problem) {
+    throw Object.assign(new Error(problem), { code: "config.invalid_argument" });
+}
+function readNameSet(servers) {
+    if (!Array.isArray(servers))
+        refuseArgument("judgeMcpNames takes a list of declared servers; what was passed is not a list.");
+    return Array.from(servers, (server, index) => {
+        if (typeof server !== "object" || server === null)
+            refuseArgument(`judgeMcpNames: entry ${index} is not a server declaration (an object with a "name").`);
+        const { name, tools } = server;
+        if (typeof name !== "string")
+            refuseArgument(`judgeMcpNames: entry ${index} has no string "name".`);
+        if (tools === undefined)
+            return { name };
+        const listed = Array.isArray(tools) ? Array.from(tools) : [undefined];
+        if (listed.some((tool) => typeof tool !== "string")) {
+            refuseArgument(`judgeMcpNames: entry ${index} ("${inlineUntrusted(name, 120)}") names its tools as something other than a list of strings.`);
+        }
+        return { name, tools: listed };
+    });
+}
+export function judgeMcpNames(servers) {
+    const set = readNameSet(servers);
+    const conflicts = findNamespacePrefixCollisions(MCP_NAMESPACE, set.map((s) => s.name)).map((c) => ({ kind: "server_name", names: c.peers, shared: c.prefix }));
+    for (const server of set) {
+        const claim = createToolNameClaims(MCP_NAMESPACE, server.name);
+        for (const tool of server.tools ?? []) {
+            const { minted, heldBy } = claim(tool);
+            if (heldBy !== undefined)
+                conflicts.push({ kind: "tool_name", server: server.name, names: [heldBy, tool], shared: minted });
+        }
+    }
+    const [first, ...rest] = conflicts;
+    return first === undefined ? { ok: true } : { ok: false, conflicts: [first, ...rest] };
+}
+export function mcpToolDropReason(minted, heldBy, tool) {
+    return heldBy === tool
+        ? `this server listed this tool name more than once in one listing; the first entry is mounted as "${minted}" and the repeat is dropped (one name cannot denote two tools)`
+        : `name collides with an earlier tool of this server: both mount as "${minted}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`;
+}
+export function describeMcpNameConflict(conflict) {
+    const [a, b] = conflict.names;
+    if (conflict.kind === "tool_name") {
+        return `MCP server "${inlineUntrusted(conflict.server, 120)}", tool "${inlineUntrusted(b, 120)}": ${mcpToolDropReason(conflict.shared, a, b)}`;
+    }
+    return a === b
+        ? `MCP server "${inlineUntrusted(a, 120)}" is declared twice — each server needs its own name (both mount under "${conflict.shared}", so their tools would shadow each other and a refresh of one would unmount the other's).`
+        : `MCP server names "${inlineUntrusted(a, 120)}" and "${inlineUntrusted(b, 120)}" both mount under "${conflict.shared}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine (their tools would shadow each other and a refresh of one would unmount the other's). Rename one.`;
+}
+export function refuseCollidingMcpServerNames(serverNames) {
+    const verdict = judgeMcpNames(serverNames.map((name) => ({ name })));
+    if (verdict.ok)
+        return;
+    const row = verdict.conflicts.find((c) => c.kind === "server_name");
+    if (row === undefined)
+        return;
+    throw Object.assign(new Error(describeMcpNameConflict(row)), { code: "config.mcp_server_name_collision" });
+}

package/dist/core/mcp-probe.d.ts

@@ -93,7 +93,7 @@ export interface McpProbeOptions {
  * FAILURE IS PER SERVER, REFUSAL IS NOT. A server that cannot be dialed, that answers a status, or that
  * outlives `timeoutMs` takes its verdict in its own row and the walk continues. What DOES reject is the
  * declaration set the materialization itself refuses — two names that mount under one namespace prefix
- * are refused before any transport is touched, by that same function, so the probe answers a colliding
+ * are refused before any transport is touched, by the judge the mount asks, so the probe answers a colliding
  * configuration exactly as a task would rather than showing two healthy-looking rows for a pair the
  * engine would never mount.
  *

package/dist/core/mcp-probe.js

@@ -2,8 +2,7 @@ import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { snapshotMcpEntries } from "./locked-config.js";
 import { classifyMcpFailure, livenessOf } from "./mcp-failure.js";
 import { MCP_ENV_MS_MAX, materializeMcpTools } from "./mcp.js";
-import { findNamespacePrefixCollision } from "./protocol-naming.js";
-import { MCP_NAMESPACE } from "./protocol-table.js";
+import { refuseCollidingMcpServerNames } from "./mcp-name-judge.js";
 import { mcpManifestEntries } from "./runner/prepare-wiring-manifest.js";
 const DECLINE_EVERY_ELICITATION = async () => ({ action: "decline" });
 function wholeInRange(name, value, min, max) {
@@ -66,9 +65,7 @@ export async function probeMcpServers(specs, opts = {}) {
     const concurrency = wholeInRange("concurrency", opts.concurrency, 1, Number.MAX_SAFE_INTEGER) ?? 1;
     const onElicit = opts.onElicit ?? DECLINE_EVERY_ELICITATION;
     const signal = opts.signal;
-    if (findNamespacePrefixCollision(MCP_NAMESPACE, declared.map((e) => e.name)) !== undefined) {
-        await materializeMcpTools(declared, opts.principal, onElicit);
-    }
+    refuseCollidingMcpServerNames(declared.map((e) => e.name));
     const statuses = [];
     const servers = new Array(declared.length);
     const teardowns = [];

package/dist/core/mcp.d.ts

@@ -6,6 +6,7 @@ import type { ImageContent, TextContent } from "../internal/llm.js";
 import { type McpImageResizer } from "./image-downsample.js";
 import type { McpServerSpec, OnElicit, ToolEffect } from "./types.js";
 import type { McpRevocationLedger } from "./mcp-server-spec.js";
+import { type HostFloor } from "./host-floor.js";
 import { type ReminderDisclosureCounts } from "./reminder-disclosure.js";
 export { resolveMcpDeclaredResultSize } from "./mcp-tool-meta.js";
 /**
@@ -616,7 +617,7 @@ reminderDisclosure?: {
 }, poolOpts?: {
     pool: McpConnectionPool;
     ownsPool?: boolean;
-}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal): Promise<MaterializedMcp>;
+}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean, signal?: AbortSignal, hostFloor?: HostFloor): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to
@@ -720,6 +721,9 @@ export declare function walkMcpListPages<T>(fetchPage: (cursor: string | undefin
      *  entry before any of that ran — the only admissible definition of a tool, removed on the theory
      *  that a name cannot appear twice, which is a rule the layer below owns and applies differently. */
     fingerprintOf?: (item: T) => string | undefined;
+    /** The header values the walk's requests carried ({@link declaredHeaderValues}): a failed continuation's text is minted without them.
+     *  Absent only for the walker's own unit pins; every production consumer passes it. */
+    declared?: readonly string[];
 }): Promise<{
     items: T[];
     incomplete?: McpListingIncomplete;