@sema-agent/server 7.137.0 → 7.138.0

package/dist/observability/secret-env-scrub.js

@@ -14,7 +14,7 @@ export const SECRET_ENV_SCRUB_SITES = {
         remedy: null,
     },
     "server.hooks.spawn-env": {
-        note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎组合,名单外一律不交;请求显式给的 `settings.env` 另叠在上面",
+        note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎的 `hostChildEnv` 组合:名单外一律不交,本服务自有凭据任何情况都不交;请求的有效环境层(`settings.env`)作授予叠在上面;请求给工具 shell 的继承词对它不作用",
         remedy: null,
     },
     "server.project-memory.git-subprocess": {

package/dist/parked-decide.d.ts

@@ -16,6 +16,7 @@ import type { RebuiltInheritedGate } from "./boot/parked-revive-gate.js";
 import { type WorkflowRunParkKey, type WorkflowAgentSessionIndex } from "./orchestration/workflow-agent-session-index.js";
 import type { WorkflowParkDecisionStore, WorkflowParkOutcome } from "./orchestration/workflow-park-decision.js";
 import { type HeadRead } from "./session-incarnation.js";
+import type { GateIdentity } from "./checkpoint-identity.js";
 export interface ParkedAgentMatch {
     handle: string;
     row: BackgroundAgentRecord;
@@ -224,6 +225,18 @@ export interface ParkedDecideRequest {
      *  的挂点(调用方自吞错,绝不抛落赎回)。claim 败/判别 miss 恒不触发。 */
     onDecideCommitted?: () => Promise<void>;
 }
+/**
+ * 后台子代赎回腿({@link decideParkedAgent})收的请求 = 两条车道共用的那一份 + 选中这张卡的**门身份片段**。workflow 车道是投递、不收它
+ * (那条车道的回执不带结清证据,身份在那里不适用 —— 不捕获,也就不为它记「缺身份」)。
+ */
+export interface ParkedAgentDecideRequest extends ParkedDecideRequest {
+    /**
+     * 调用方在执行之前从选中的那一行捕获、已过信任边界(`checkpoint-identity.ts` 的 `durableRowIdentity`,face `decision-receipt`;读不出 ⇒ `{}`)。
+     * 本腿的两个结清边界(复活成功 / 不可复活 deny 作废)把它随结清证据上体(`gate-settlement.ts`)。必填:身份只有这一个来源 ——
+     * agent 行上没有这一格,本腿也不另读「当前待决门」(受理之后它可能已是下一张卡);认领到的 token 不是选中的那一张 ⇒ 拒,不替它作证。
+     */
+    readonly selectedGate: GateIdentity;
+}
 export interface ParkedDecideResult {
     status: number;
     body: Record<string, unknown>;
@@ -341,8 +354,8 @@ export declare function planWorkflowParkedDecide(origin: Extract<ParkOrigin, {
  * ([ref] Q2:isError 入参级早退 + throw 两形,已核幂等/双滚=无害 lost)。
  *
  * 200 是**受理**语义(drive 是 core 内 fire-and-forget):失败经行/notification 面 + REOPENED
- * re-park 诚实可见,操作员可再决。
+ * re-park 诚实可见,操作员可再决。200 体 `{ taskId, status: "resuming", decision }` + 结清证据(`gate-settlement.ts` 的边界 ④)。
  */
-export declare function decideParkedAgent(deps: ParkedDecideDeps, req: ParkedDecideRequest, match: ParkedAgentMatch): Promise<ParkedDecideResult>;
+export declare function decideParkedAgent(deps: ParkedDecideDeps, req: ParkedAgentDecideRequest, match: ParkedAgentMatch): Promise<ParkedDecideResult>;
 export {};
 //# sourceMappingURL=parked-decide.d.ts.map

package/dist/parked-decide.js

@@ -7,6 +7,8 @@ import { backgroundScopesForCheckpointScope, decodeCheckpointScope, ownerOfCheck
 import { ASK_USER_QUESTION_TOOL_NAME, isEngineQuestionRow } from "./approval-content-kind.js";
 import { sessionFaceOfHead } from "./session-incarnation.js";
 import { refusalBody, resumeRefusalFacts } from "./http/refusal-body.js";
+import { backgroundAgentNameOf } from "./background-agent-name.js";
+import { buildSettlementEvidence } from "./gate-settlement.js";
 export async function findParkOrigin(sources, cp) {
     if (sources.agentStore !== undefined) {
         let match;
@@ -111,7 +113,7 @@ function mintReviveArgs(row, knownAgentTypes) {
     return {
         prompt: row.description ?? "resume parked agent",
         run_in_background: true,
-        name: row.name,
+        name: backgroundAgentNameOf(row),
         description: row.description ?? "revived agent",
         ...(row.agentType !== undefined && knownAgentTypes.has(row.agentType) ? { subagent_type: row.agentType } : {}),
     };
@@ -232,10 +234,10 @@ function sessionGone(taskId) {
         }),
     };
 }
+function gateMoved(taskId) {
+    return { status: 409, body: refusalBody({ errorCode: "decide.gate_moved", message: "the approval gate moved under this decide (re-parked or already settled) — re-check the pending list", facts: { taskId } }) };
+}
 function revivabilityOf(row, taskId) {
-    if (row.name === undefined) {
-        return { kind: "unrevivable", approveRefusal: { status: 409, body: refusalBody({ errorCode: "decide.row_unrevivable", message: "parked row carries no agent name — the revive path requires a named agent, so this approval cannot be approved; deny it to close the card (the agent then ends as failed)", facts: { taskId } }) } };
-    }
     if (row.rootSessionId === undefined) {
         return { kind: "unrevivable", approveRefusal: { status: 409, body: refusalBody({ errorCode: "decide.row_unrevivable", message: "this agent's row carries no root session anchor — the revive path cannot tell which session this approval belongs to, so it cannot be approved; deny it to close the card (the agent then ends as failed)", facts: { taskId } }) } };
     }
@@ -244,7 +246,7 @@ function revivabilityOf(row, taskId) {
 async function voidUnrevivableCard(deps, req, match) {
     const voided = await deps.checkpointStore.expire(req.token, req.scope);
     if (!voided) {
-        return { status: 409, body: refusalBody({ errorCode: "decide.gate_moved", message: "the approval gate moved under this decide (re-parked or already settled) — re-check the pending list", facts: { taskId: match.handle } }) };
+        return gateMoved(match.handle);
     }
     try {
         await deps.registry.reconcileParkedAgents({ agentStore: deps.agentStore, checkpointStore: deps.checkpointStore }, match.row.scope, Date.now());
@@ -252,7 +254,7 @@ async function voidUnrevivableCard(deps, req, match) {
     catch (e) {
         quiet(deps.warn, "parked_unrevivable_reconcile_failed", { taskId: match.handle, error: e instanceof Error ? e.message : String(e) });
     }
-    return { status: 200, body: { taskId: match.handle, status: "failed", decision: "deny" } };
+    return { status: 200, body: { taskId: match.handle, status: "failed", decision: "deny", ...buildSettlementEvidence({ at: "card_voided", gate: req.selectedGate }) } };
 }
 export async function decideParkedAgent(deps, req, match) {
     const row = match.row;
@@ -282,7 +284,7 @@ export async function decideParkedAgent(deps, req, match) {
                 return { status: 409, body: refusalBody({ errorCode: "decide.claim_lost", message: "the parked agent is already claimed — either a concurrent decide won (re-check the pending list), or a stale claim is pending automatic cleanup (retry after the stale-claim window)", facts: { taskId: match.handle } }) };
             case "binding_broken":
             case "checkpoint_not_pending":
-                return { status: 409, body: refusalBody({ errorCode: "decide.gate_moved", message: "the approval gate moved under this decide (re-parked or already settled) — re-check the pending list", facts: { taskId: match.handle } }) };
+                return gateMoved(match.handle);
             default:
                 return { status: 409, body: refusalBody({ errorCode: "decide.not_parked", message: "the parked agent moved under this decide (stopped or already decided)", facts: { taskId: match.handle } }) };
         }
@@ -306,6 +308,10 @@ export async function decideParkedAgent(deps, req, match) {
             return "retry";
         }
     };
+    if (ticket.token !== req.token) {
+        await rollback("claimed_token_moved");
+        return gateMoved(match.handle);
+    }
     let faceAfter;
     try {
         faceAfter = sessionFaceOfHead(root, await deps.headOf(root));
@@ -408,6 +414,6 @@ export async function decideParkedAgent(deps, req, match) {
             }),
         };
     }
-    return { status: 200, body: { taskId: match.handle, status: "resuming", decision: req.decision } };
+    return { status: 200, body: { taskId: match.handle, status: "resuming", decision: req.decision, ...buildSettlementEvidence({ at: "agent_revived", gate: req.selectedGate }) } };
 }
 //# sourceMappingURL=parked-decide.js.map

package/dist/peer-seat.d.ts

@@ -0,0 +1,150 @@
+import type { A2aServerSpec, McpServerSpec, PeerAnswer, PeerQuestion, PeerSeatTarget } from "@sema-agent/core";
+import { type Logger } from "./observability/logger.js";
+import { type SafeText } from "./trace/exit-seat.js";
+type StdioArm = Extract<McpServerSpec["transport"], {
+    kind: "stdio";
+}>;
+type HttpArm = Extract<McpServerSpec["transport"], {
+    kind: "http";
+}>;
+/** The pieces a declaration's sends carry, as written: header name → value (http MCP, A2A) or variable → value (stdio MCP). */
+export type PeerPieces = Readonly<Record<string, string>>;
+/**
+ * An MCP server declaration before the desk has seen it: the engine's declaration without its credential reference, beside the
+ * pieces. `credentials?: never` sits on each transport arm (where the engine keeps the reference) so that a declaration that already
+ * carries one cannot be passed back in as a draft: `Omit` alone would not refuse it, because excess members are judged only on fresh
+ * object literals. Without `exactOptionalPropertyTypes` an explicit `credentials: undefined` still passes; it carries no reference.
+ */
+export type McpDraftSpec = Omit<McpServerSpec, "transport"> & {
+    transport: (Omit<StdioArm, "credentials"> & {
+        credentials?: never;
+    }) | (Omit<HttpArm, "credentials"> & {
+        credentials?: never;
+    });
+};
+/** An MCP draft: the declaration and the pieces its sends carry (absent or empty ⇒ nothing to register). */
+export interface McpDraft {
+    readonly spec: McpDraftSpec;
+    readonly pieces?: PeerPieces;
+}
+/** An A2A peer declaration before the desk has seen it; the engine keeps an A2A peer's reference at the top level. */
+export type A2aDraftSpec = Omit<A2aServerSpec, "credentials"> & {
+    credentials?: never;
+};
+/** An A2A draft: the declaration and the headers its sends carry (absent or empty ⇒ nothing to register). */
+export interface A2aDraft {
+    readonly spec: A2aDraftSpec;
+    readonly pieces?: PeerPieces;
+}
+export type PeerDraft = McpDraft | A2aDraft;
+/** The reference {@link PeerDesk.declare} mints (the `handle` kind of the reference the engine asks with): opaque, the same for the same
+ *  content within one process. */
+export type PeerHandle = Extract<NonNullable<PeerSeatTarget["credentials"]>, {
+    kind: "handle";
+}>;
+/**
+ * Who a send goes to, as the seat binds an answer to it: the engine's question target without the reference itself and without an
+ * A2A send's `destination` (the engine owns which declared origin a send may reach). An http MCP server = name, url, mount
+ * fingerprint; a stdio one = name, the whole start command (absent `args` ≡ `[]`), fingerprint; an A2A peer = name, url, `cardUrl`.
+ */
+export type PeerBinding = {
+    readonly protocol: "mcp";
+    readonly transport: "http";
+    readonly server: string;
+    readonly url: string;
+    readonly fingerprint?: string;
+} | {
+    readonly protocol: "mcp";
+    readonly transport: "stdio";
+    readonly server: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly fingerprint?: string;
+} | {
+    readonly protocol: "a2a";
+    readonly peer: string;
+    readonly url: string;
+    readonly cardUrl?: string;
+};
+/** Why the seat refused a question. Closed: a new word is a new arm of `answer`'s switch. */
+export type PeerSeatRefusalReason = "handle_not_held" | "binding_mismatch" | "kind_env" | "kind_vault" | "kind_assertion" | "kind_unknown";
+/**
+ * The desk's own failures, each loud:
+ *  · `peer_lease_released` — a released lease was used to declare or to extend (a scope released before its last use);
+ *  · `peer_lease_foreign` — a lease another desk opened was used here (its release would never reach this desk's entries);
+ *  · `peer_lease_scope_unknown` — a lease was asked for with a scope word outside {@link PEER_LEASE_SCOPES};
+ *  · `peer_binding_conflict` — two different contents were minted one id (only a digest collision does that); the entry stands;
+ *  · `peer_seat_refused` — the seat refused a question (the engine reads any throw as the seat not furnishing that send).
+ * No message names a value or an id.
+ */
+export type PeerDeskErrorCode = "peer_lease_released" | "peer_lease_foreign" | "peer_lease_scope_unknown" | "peer_binding_conflict" | "peer_seat_refused";
+export declare class PeerDeskError extends Error {
+    readonly code: PeerDeskErrorCode;
+    constructor(code: PeerDeskErrorCode, message: string);
+}
+/**
+ * Which host scope a lease is opened for: the request funnel of a fresh submission, the funnel of a resumed leg, a probe walk, the
+ * roster (held for the process's life). A closed set, so the desk's own error text can name a scope without echoing caller text.
+ */
+export declare const PEER_LEASE_SCOPES: readonly ["fresh", "resume", "probe", "roster"];
+export type PeerLeaseScope = (typeof PEER_LEASE_SCOPES)[number];
+/** A host holder. `release` is idempotent; `extend` opens a further lease that holds every entry this one holds now. */
+export interface PeerLease {
+    /** A further lease holding what this one holds at this moment; this one released ⇒ throws `peer_lease_released`. */
+    extend(): PeerLease;
+    /** Stop holding. Entries no other holder holds are dropped now. A second call does nothing. */
+    release(): void;
+}
+/** What the engine asks: the pieces for one send. The seat holds nothing itself — an entry's holders are host leases only. */
+export interface PeerDeskSeat {
+    /** The pieces for one send, or a throw (refused: logged as one `peer_seat_refused` row naming protocol, peer and reason only). */
+    answer(question: PeerQuestion): Promise<PeerAnswer>;
+}
+/** Live entries and the host leases holding them, summed across entries — the registry's whole observable state. */
+export interface PeerDeskSize {
+    readonly entries: number;
+    readonly holders: number;
+}
+export interface PeerDesk {
+    readonly seat: PeerDeskSeat;
+    /**
+     * Register a draft's pieces under `lease` and mint the reference the declaration carries to the engine. No pieces ⇒ nothing is
+     * registered and nothing is minted (`undefined`: the declaration goes without a reference). The same content (binding, lane,
+     * pieces by name) mints the same id in one process, so two legs declaring one body share one entry and each holds it.
+     */
+    declare(draft: PeerDraft, lease: PeerLease): PeerHandle | undefined;
+    /** Open a host lease for `scope` (named in the desk's own error text; a word outside the set ⇒ throws `peer_lease_scope_unknown`). */
+    lease(scope: PeerLeaseScope): PeerLease;
+    size(): PeerDeskSize;
+}
+export interface PeerDeskOptions {
+    /** Where refusal rows go (default: a JSON-line logger). */
+    readonly log?: Logger;
+}
+/** The binding of a draft, or of the target the engine asks about; both read the same three rows. */
+export declare function bindingOf(peer: PeerDraft | PeerSeatTarget): PeerBinding;
+export declare function createPeerDesk(opts?: PeerDeskOptions): PeerDesk;
+/**
+ * **The one minting point** every entrance calls — the roster (under the roster lease), the request surface (under the leg's host lease) and
+ * the probe walk: register `draft`'s pieces on `desk` under `lease` and hand back the declaration the engine gets, carrying the minted
+ * reference where the engine keeps it (an MCP server's transport arm, an A2A peer's top level) and no piece value anywhere. A draft with no
+ * pieces registers nothing and goes as drafted (no reference member). Where the reference sits is written here and nowhere else.
+ */
+export declare function mintDeclaration(desk: Pick<PeerDesk, "declare">, draft: McpDraft, lease: PeerLease): McpServerSpec;
+export declare function mintDeclaration(desk: Pick<PeerDesk, "declare">, draft: A2aDraft, lease: PeerLease): A2aServerSpec;
+/**
+ * **The one exit** for an engine judge's sentence about a peer declaration (an MCP server's or an A2A peer's `toolAxes` / `toolFaces` /
+ * `sessionMetaKey` / start bound …) on its way into this server's refusal text or an operator line: the engine words what the declaring side
+ * wrote (a tool name, a key — which a mistake can make a credential), so the sentence leaves through the exit seat's `peer-declaration-sentence`
+ * row (credential shapes become marks, the sentence stays the engine's). The request surface's judges, the replay reread lines and the roster's
+ * skip lines all use this one.
+ */
+export declare function peerSentence(problem: string): SafeText;
+/**
+ * Hold `lease`'s entries for as long as `drive` runs: a further lease is opened before `drive` is called (synchronously, so before
+ * the caller's own scope can release) and released when `drive` settles — resolved, rejected or thrown synchronously. A released
+ * lease rejects with `peer_lease_released` and `drive` is not called.
+ */
+export declare function heldFor<T>(lease: PeerLease, drive: () => Promise<T>): Promise<T>;
+export {};
+//# sourceMappingURL=peer-seat.d.ts.map

package/dist/peer-seat.js

@@ -0,0 +1,239 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { createLogger } from "./observability/logger.js";
+import { seatText } from "./trace/exit-seat.js";
+export class PeerDeskError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "PeerDeskError";
+    }
+}
+export const PEER_LEASE_SCOPES = ["fresh", "resume", "probe", "roster"];
+export function bindingOf(peer) {
+    if ("spec" in peer) {
+        const spec = peer.spec;
+        if (!("transport" in spec))
+            return a2aBinding(spec.name, spec.url, spec.cardUrl);
+        const t = spec.transport;
+        switch (t.kind) {
+            case "http":
+                return httpBinding(spec.name, t.url, spec.fingerprint);
+            case "stdio":
+                return stdioBinding(spec.name, t.command, t.args ?? [], spec.fingerprint);
+            default: {
+                const unknownArm = t;
+                throw new Error(`peer desk: an MCP draft with a transport this desk does not know (${discriminantsOf(unknownArm)})`);
+            }
+        }
+    }
+    switch (peer.protocol) {
+        case "mcp":
+            switch (peer.transport) {
+                case "http":
+                    return httpBinding(peer.server, peer.url, peer.fingerprint);
+                case "stdio":
+                    return stdioBinding(peer.server, peer.command, peer.args, peer.fingerprint);
+                default: {
+                    const unknownArm = peer;
+                    throw new Error(`peer desk: a question about an MCP transport this desk does not know (${discriminantsOf(unknownArm)})`);
+                }
+            }
+        case "a2a":
+            return a2aBinding(peer.peer, peer.url, peer.cardUrl);
+        default: {
+            const unknownArm = peer;
+            throw new Error(`peer desk: a question about a protocol this desk does not know (${discriminantsOf(unknownArm)})`);
+        }
+    }
+}
+function httpBinding(server, url, fingerprint) {
+    return Object.freeze({ protocol: "mcp", transport: "http", server, url, ...(fingerprint !== undefined ? { fingerprint } : {}) });
+}
+function stdioBinding(server, command, args, fingerprint) {
+    return Object.freeze({ protocol: "mcp", transport: "stdio", server, command, args: Object.freeze([...args]), ...(fingerprint !== undefined ? { fingerprint } : {}) });
+}
+function a2aBinding(peer, url, cardUrl) {
+    return Object.freeze({ protocol: "a2a", peer, url, ...(cardUrl !== undefined ? { cardUrl } : {}) });
+}
+function discriminantsOf(value) {
+    if (typeof value !== "object" || value === null)
+        return typeof value;
+    const at = (key) => {
+        const v = Reflect.get(value, key);
+        return typeof v === "string" ? JSON.stringify(v.slice(0, 40)) : typeof v;
+    };
+    return `protocol ${at("protocol")}, transport ${at("transport")}, kind ${at("kind")}`;
+}
+function laneOf(binding) {
+    return binding.protocol === "a2a" ? "a2a" : binding.transport;
+}
+function rowsOf(record) {
+    return Object.entries(record).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+function canonicalOf(binding, lane, pieces) {
+    return JSON.stringify([rowsOf(binding), lane, rowsOf(pieces)]);
+}
+function sameBinding(a, b) {
+    return JSON.stringify(rowsOf(a)) === JSON.stringify(rowsOf(b));
+}
+const ID_KEY = randomBytes(32);
+function mintId(canonical) {
+    return `h1.${createHmac("sha256", ID_KEY).update(canonical).digest("base64url")}`;
+}
+function copyPieces(given) {
+    if (given === undefined)
+        return undefined;
+    const names = Object.keys(given);
+    if (names.length === 0)
+        return undefined;
+    const copy = Object.create(null);
+    for (const name of names)
+        copy[name] = given[name];
+    return Object.freeze(copy);
+}
+export function createPeerDesk(opts = {}) {
+    const log = opts.log ?? createLogger();
+    const table = new Map();
+    const leases = new WeakMap();
+    let lastLeaseId = 0;
+    const entryHeld = (id) => {
+        const entry = table.get(id);
+        if (entry === undefined)
+            throw new Error("peer desk: a live lease holds an entry the table no longer has");
+        return entry;
+    };
+    const dropIfUnheld = (id, entry) => {
+        if (entry.hosts.size === 0)
+            table.delete(id);
+    };
+    const liveState = (lease) => {
+        const state = leases.get(lease);
+        if (state === undefined)
+            throw new PeerDeskError("peer_lease_foreign", "peer desk: a lease another desk opened was used here");
+        const held = state.held;
+        if (held === undefined)
+            throw new PeerDeskError("peer_lease_released", `peer desk: a "${state.scope}" lease was used after it was released`);
+        return { id: state.id, scope: state.scope, held };
+    };
+    const openLease = (scope, holds) => {
+        const state = { id: ++lastLeaseId, scope, held: new Set(holds) };
+        for (const id of holds)
+            entryHeld(id).hosts.add(state.id);
+        const lease = Object.freeze({
+            extend: () => openLease(state.scope, liveState(lease).held),
+            release: () => {
+                const held = state.held;
+                if (held === undefined)
+                    return;
+                state.held = undefined;
+                for (const id of held) {
+                    const entry = entryHeld(id);
+                    entry.hosts.delete(state.id);
+                    dropIfUnheld(id, entry);
+                }
+            },
+        });
+        leases.set(lease, state);
+        return lease;
+    };
+    const refuse = (target, reason) => {
+        const peer = target.protocol === "a2a" ? target.peer : target.server;
+        log.warn("peer_seat_refused", { protocol: target.protocol, peer, reason });
+        throw new PeerDeskError("peer_seat_refused", `peer desk: the seat refused this send (${reason})`);
+    };
+    const carry = (entry) => {
+        switch (entry.lane) {
+            case "http":
+            case "a2a":
+                return { kind: "carry", headers: entry.pieces };
+            case "stdio":
+                return { kind: "carry", env: entry.pieces };
+        }
+    };
+    const seat = Object.freeze({
+        answer: async (question) => {
+            const target = question.peer;
+            const ref = target.credentials;
+            if (ref === undefined)
+                return { kind: "carry" };
+            switch (ref.kind) {
+                case "handle": {
+                    const entry = table.get(ref.id);
+                    if (entry === undefined)
+                        return refuse(target, "handle_not_held");
+                    if (!sameBinding(entry.binding, bindingOf(target)))
+                        return refuse(target, "binding_mismatch");
+                    return carry(entry);
+                }
+                case "env":
+                    return refuse(target, "kind_env");
+                case "vault":
+                    return refuse(target, "kind_vault");
+                case "assertion":
+                    return refuse(target, "kind_assertion");
+                default: {
+                    const unknownKind = ref;
+                    void unknownKind;
+                    return refuse(target, "kind_unknown");
+                }
+            }
+        },
+    });
+    return Object.freeze({
+        seat,
+        declare: (draft, lease) => {
+            const pieces = copyPieces(draft.pieces);
+            const binding = pieces === undefined ? undefined : bindingOf(draft);
+            const holder = liveState(lease);
+            if (pieces === undefined || binding === undefined)
+                return undefined;
+            const lane = laneOf(binding);
+            const canonical = canonicalOf(binding, lane, pieces);
+            const id = mintId(canonical);
+            const known = table.get(id);
+            if (known === undefined) {
+                table.set(id, { binding, lane, pieces, hosts: new Set([holder.id]) });
+            }
+            else if (canonicalOf(known.binding, known.lane, known.pieces) !== canonical) {
+                throw new PeerDeskError("peer_binding_conflict", "peer desk: two different declarations were minted one id; the registered one stands");
+            }
+            else {
+                known.hosts.add(holder.id);
+            }
+            holder.held.add(id);
+            return Object.freeze({ kind: "handle", id });
+        },
+        lease: (scope) => {
+            if (!PEER_LEASE_SCOPES.includes(scope))
+                throw new PeerDeskError("peer_lease_scope_unknown", "peer desk: a lease was asked for with a scope outside the closed set");
+            return openLease(scope, new Set());
+        },
+        size: () => {
+            let holders = 0;
+            for (const entry of table.values())
+                holders += entry.hosts.size;
+            return { entries: table.size, holders };
+        },
+    });
+}
+export function mintDeclaration(desk, draft, lease) {
+    const credentials = desk.declare(draft, lease);
+    const spec = draft.spec;
+    if ("transport" in spec)
+        return credentials === undefined ? spec : { ...spec, transport: { ...spec.transport, credentials } };
+    return credentials === undefined ? spec : { ...spec, credentials };
+}
+export function peerSentence(problem) {
+    return seatText("peer-declaration-sentence", problem);
+}
+export async function heldFor(lease, drive) {
+    const own = lease.extend();
+    try {
+        return await drive();
+    }
+    finally {
+        own.release();
+    }
+}
+//# sourceMappingURL=peer-seat.js.map

package/dist/permission-rule-vocab.d.ts

@@ -1,14 +1,14 @@
 import type { RuleBehavior } from "@sema-agent/core";
 /**
- * `PersistedRuleTool` **不再是闭词表**(core 7.9.0 / [ref]):工具名自 core 的**目录**派生
- * (`pathTarget` 声明 ⇒ 路径文法;`Bash` ⇒ 命令文法),型是 `string`。于是本文件对它的处置从
- * 「转录一份名单」换成「转 core 的**谓词**」——名单在 core 的目录里,抄一份的那天目录加一个带
- * `pathTarget` 的工具,本仓会静默拒收一整类合法行(正是本文件顶注说的那个病)。
+ * 一张审批卡的**一键整工具同意**能落在这只工具名上吗 —— 仅当没有任何规则词替这个名字说话:它自己没有规则文法(`ruleToolGrammarOf` 答 undefined),
+ * 也不在 shell 面上(`COARSE_SHELL_TOOLS`:`Bash` 与 `Monitor`,它们的命令按 `Bash(…)` 规则判)。引擎为卡铸整工具候选恰在这个条件下(没有规则文法、
+ * 也不回答任何规则词的调用);一张 shell 卡上的一键整工具同意 = 对每一个程序的常驻许可,路径 / 名字 / 主机工具的卡各有自己的那一形。
  *
- * 谓词方向仍是 fail-CLOSED:`ruleToolGrammarOf` 认不出的名字**不是**一条可持久化规则的工具位
- * (既非命令文法也非路径文法 ⇒ 这条行永远匹配不上任何调用),两只店与票口一律拒。
+ * 读者:卡素材铸点的派生事实一致性(`tool-approval.ts`:整工具候选的工具过不了 ⇒ 丢整只候选,卡上不渲一格按不动的「不再询问」)。
+ * 卡编辑面不读它:引擎的编辑门对任何整工具规则一律拒(编辑只改命令规则),编辑面的形闭集(`rules-consent.ts`)跟着恒拒 —— 那张闭集里「shell 卡上一键整只 shell」
+ * 的理由就是本谓词的理由,不另写一份判据。方向 fail-closed:答不出 ⇒ 不是。
  */
-export declare function isPersistedRuleTool(name: string): boolean;
+export declare function cardTakesWholeToolConsent(tool: string): boolean;
 /**
  * [ref] —— `RuleBehavior` 每一员在**无同意仪式的直接写口**(`POST /v1/rules`)上的逐员表态。
  *

package/dist/permission-rule-vocab.js

@@ -1,6 +1,6 @@
-import { ruleToolGrammarOf } from "@sema-agent/core";
-export function isPersistedRuleTool(name) {
-    return ruleToolGrammarOf(name) !== undefined;
+import { COARSE_SHELL_TOOLS, ruleToolGrammarOf } from "@sema-agent/core";
+export function cardTakesWholeToolConsent(tool) {
+    return ruleToolGrammarOf(tool) === undefined && !COARSE_SHELL_TOOLS.includes(tool);
 }
 export const DIRECT_RULE_WRITE_ADMITS = {
     allow: false,

package/dist/plain-string-record.d.ts

@@ -22,4 +22,42 @@ export type PlainStringRecordRead = {
  * 数据属性取值,访问器调一次。先判每个成员的值(`__proto__` 名的成员也判:它的值不是串 ⇒ 整只不交,与 7.131.x 同),再剔 `__proto__` 名。调用方的对象不被交出去、也不被改。
  */
 export declare function readPlainStringRecord(v: unknown): PlainStringRecordRead;
+/**
+ * 请求面一份声明里每个键的**去处**(闭集;{@link splitDeclaration} 对它穷尽 `switch`):
+ *  · `engine`   —— 进交给引擎的声明;
+ *  · `seat`     —— 进草稿的件:由部署的对端座在发送时按原字节作答,交给引擎的声明里不带(只有值是「名 → 串」记录的键能标它);
+ *  · `withheld` —— 承载、不发送:声明与件两边都不进(由声明这一格的属主另说一行)。
+ */
+export type DeclarationKeyDisposition = "engine" | "seat" | "withheld";
+/**
+ * 请求形 `R` 的**处置表**:`R` 的每个键(可选键也算)恰一格 —— 写成 `as const satisfies DeclarationDispositionTable<R>` 的对象字面量,于是请求形多一个键而表没写 ⇒ 缺属性编译红,
+ * 表里写一个请求形上没有的词 ⇒ 多余属性编译红(三道编译格的第一道,两向)。只有值是「名 → 串」记录的键可以标 `seat`(别的键标它 ⇒ 编译红)。
+ * 表的书写序就是键闭集的序({@link declarationKeys}):受理门按它判序。
+ */
+export type DeclarationDispositionTable<R> = {
+    readonly [K in keyof Required<R>]: NonNullable<R[K]> extends Readonly<Record<string, string>> ? DeclarationKeyDisposition : Exclude<DeclarationKeyDisposition, "seat">;
+};
+/** 处置表里标 `engine` 的键。 */
+export type EngineKeysOf<T> = {
+    [K in keyof T]: T[K] extends "engine" ? K : never;
+}[keyof T];
+/**
+ * 三道编译格的后两道(引擎一侧)的**缺口**,一个型名、两向;用处写成 `AssertAllKeysHandled<EngineSideGap<…>>`(缺口非空 ⇒ 编译红,点名那个键):
+ * ② 引擎形上没标 `engine` 的键恰是 `Unbound`(引擎形长出一个键而表没跟 ⇒ 缺口里有它);
+ * ③ 标 `engine` 的键与 `Unbound` 都仍在引擎形上(引擎退役一个键、或退役了 `Unbound` 那一位 ⇒ 缺口里有它)。`Unbound` = 引擎形上请求面不写、由宿主铸的位(凭据引用)。
+ * 只证键集,不证值型与运行期转换完备(值型由 {@link splitDeclaration} 的返回型交给声明型去判)。
+ */
+export type EngineSideGap<T, EngineArm, Unbound extends PropertyKey> = Exclude<keyof EngineArm, EngineKeysOf<T> | Unbound> | Exclude<EngineKeysOf<T> | Unbound, keyof EngineArm>;
+/** 一张处置表的键,按表的书写序(冻结;受理门的键闭集与判序读它,不另写第二份清单)。 */
+export declare function declarationKeys<T extends object>(table: T): ReadonlyArray<keyof T & string>;
+/**
+ * 按处置表拆一份请求面声明:标 `engine` 的成员进 `engine`(交给引擎的声明那一部分),标 `seat` 的那一张记录进 `pieces`(空记录 = 没有件,`pieces` 缺席),
+ * 标 `withheld` 的成员两边都不进;值为 `undefined` 的成员按缺席读。
+ * 请求面声明的唯一拆法 —— MCP 两臂(`toMcpDraft`)与 A2A 对端(`toA2aDraft`)同调这一只,所以「哪个键去哪」只有表一处说,代码里没有第二份键名。
+ * 运行期漏臂(响亮):成员不在表里(表的型挡住了写得出的形,只有绕过型的调用方走得到)/ 一份声明有两张标 `seat` 的记录 ⇒ 抛;两句都不带值。
+ */
+export declare function splitDeclaration<R extends object, T extends DeclarationDispositionTable<R>>(declaration: R, table: T): {
+    readonly engine: Pick<R, EngineKeysOf<T> & keyof R>;
+    readonly pieces?: Readonly<Record<string, string>>;
+};
 //# sourceMappingURL=plain-string-record.d.ts.map

package/dist/plain-string-record.js

@@ -29,4 +29,42 @@ export function readPlainStringRecord(v) {
     }
     return { ok: true, record, stripped };
 }
+export function declarationKeys(table) {
+    return Object.freeze(Object.keys(table));
+}
+export function splitDeclaration(declaration, table) {
+    const dispositions = table;
+    const engine = {};
+    let pieces;
+    let seatSeen = false;
+    for (const [key, value] of Object.entries(declaration)) {
+        if (value === undefined)
+            continue;
+        const disposition = Object.hasOwn(dispositions, key) ? dispositions[key] : undefined;
+        switch (disposition) {
+            case "engine":
+                engine[key] = value;
+                break;
+            case "seat": {
+                if (seatSeen)
+                    throw new Error("request declaration: two members are marked as pieces in one disposition table");
+                seatSeen = true;
+                const record = value;
+                if (Object.keys(record).length > 0)
+                    pieces = record;
+                break;
+            }
+            case "withheld":
+                break;
+            case undefined:
+                throw new Error(`request declaration: a member the disposition table does not classify (${JSON.stringify(key.slice(0, 40))})`);
+            default: {
+                const unknownDisposition = disposition;
+                void unknownDisposition;
+                throw new Error("request declaration: a disposition outside the closed set");
+            }
+        }
+    }
+    return { engine: engine, ...(pieces === undefined ? {} : { pieces }) };
+}
 //# sourceMappingURL=plain-string-record.js.map