@sema-agent/core 7.6.3 → 7.8.0

package/dist/core/shared-memory/tools.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { errorResult } from "../tools.js";
 import { CONNECTING_MESSAGE, GENERIC_FAILURE_MESSAGE, NO_STORES_MESSAGE, SHARED_STORE_FRAME, UNAVAILABLE_MESSAGE, datePrefixOf, echoUntrusted, foldReaderError, listPrefixArgument, normalizeEntries, normalizeMemoryPath, normalizeReadValue, normalizeSnapshot, pageDocuments, relativePathRefusal, sanitizeSharedContent, validateDocumentPath, validatePathPrefix, } from "./normalize.js";
 import { SHARED_MEMORY_LIST_PAGE_SIZE, SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_READ_TOOL_NAME, } from "./types.js";
+import { toolFace } from "../tool-catalog-entries.js";
 const LIST_HINT = "List shared memory stores and their documents — check here before telling the user you do not have something.";
 const LIST_DESCRIPTION = [
     LIST_HINT,
@@ -125,11 +126,9 @@ export function createSharedMemoryTools(opts) {
     };
     const listTool = {
         name: SHARED_MEMORY_LIST_TOOL_NAME,
+        ...toolFace("memory-list"),
         description: LIST_DESCRIPTION,
-        effect: "read",
         defer: true,
-        offload: false,
-        contract: { contractId: "core.memory_list@1", implementationRevision: "1" },
         parameters: Type.Object({
             store: Type.Optional(Type.String({
                 description: "Id of the connected memory store to list. Omit to list the memory stores connected to this session (id, description, and writable or read-only).",
@@ -258,11 +257,9 @@ export function createSharedMemoryTools(opts) {
     };
     const readTool = {
         name: SHARED_MEMORY_READ_TOOL_NAME,
+        ...toolFace("memory-read"),
         description: READ_DESCRIPTION,
-        effect: "read",
         defer: true,
-        offload: false,
-        contract: { contractId: "core.memory_read@1", implementationRevision: "1" },
         parameters: Type.Object({
             store: Type.String({
                 description: `Id of the connected memory store to read from (call ${SHARED_MEMORY_LIST_TOOL_NAME} with no arguments to see the connected stores).`,

package/dist/core/store-contracts/checkpoint-store-contract.d.ts

@@ -1,4 +1,5 @@
 import { type Checkpoint, type CheckpointStore, type ResumeOutcome } from "../checkpoint-store.js";
+import type { GateOutcome } from "../gate-outcome.js";
 import { type CheckpointFields } from "../pause-registry.js";
 import { type ContractAssertionRunner } from "./contract-harness.js";
 /**
@@ -23,6 +24,9 @@ export declare function createCheckpointFixture(over?: Partial<CheckpointFields>
 export declare const ALLOW: Extract<ResumeOutcome, {
     gate: "policy_ask";
 }>;
+export declare const EXECUTED_ALLOW: GateOutcome;
+export declare const EXECUTED_ALLOW_REORDERED: GateOutcome;
+export declare const VETOED_BY_POLICY: GateOutcome;
 /**
  * The full cross-backend contract for {@link CheckpointStore} — the SAME assertions for every
  * backend. Entries are a 1:1 port of the vitest originals (assertion semantics unchanged).

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -1,4 +1,5 @@
 import { strict as assert } from "node:assert";
+import { executionVerdict } from "../checkpoint-execution-record.js";
 import { MAX_PENDING_STEER_ENTRIES, mintCheckpointToken, readPendingSteerQueue, } from "../checkpoint-store.js";
 import { checkpointFrom } from "../pause-registry.js";
 import { beginContract } from "./contract-harness.js";
@@ -36,6 +37,10 @@ export const ALLOW = {
     boundInputHash: "h0",
     hostDecision: { decidedBy: "person" },
 };
+const SETTLED = { kind: "human_allowed", who: { party: "person" }, when: 1_700_000_000_500 };
+export const EXECUTED_ALLOW = Object.freeze({ disposition: Object.freeze({ kind: "allowed" }), settlement: Object.freeze({ ...SETTLED, who: Object.freeze({ ...SETTLED.who }) }), origin: "policy" });
+export const EXECUTED_ALLOW_REORDERED = Object.freeze({ origin: "policy", settlement: Object.freeze({ when: 1_700_000_000_500, who: Object.freeze({ party: "person" }), kind: "human_allowed" }), disposition: Object.freeze({ kind: "allowed" }) });
+export const VETOED_BY_POLICY = Object.freeze({ disposition: Object.freeze({ kind: "denied", deniedBy: "policy" }), settlement: Object.freeze({ ...SETTLED, who: Object.freeze({ ...SETTLED.who }) }), origin: "policy" });
 export async function checkpointStoreContract(make, runAssertion) {
     const { run, settle } = beginContract(runAssertion);
     run("kit prerequisites: reopen/setPendingSteer/listByScope are implemented (REQUIRED by this kit)", async () => {
@@ -43,6 +48,86 @@ export async function checkpointStoreContract(make, runAssertion) {
         const missing = ["reopen", "setPendingSteer", "listByScope"].filter((m) => typeof probe[m] !== "function");
         assert.equal(missing.length, 0, `backend does not implement ${missing.join(", ")} — required for the CheckpointStore contract kit`);
     });
+    run("execution declaration: the backend declares execution.outcome === true (a REQUIRED member of the contract)", async () => {
+        const probe = make();
+        assert.equal(probe.execution?.outcome, true, "backend does not declare `execution = { outcome: true }` — the run refuses the store at its first read");
+        assert.equal(typeof probe.recordExecutionOutcome, "function", "backend does not implement recordExecutionOutcome — required by the CheckpointStore contract");
+    });
+    run("recordExecutionOutcome on a resolved row → `recorded`; the record and its stamp ride the row, the decision winner is untouched, executionVerdict reads executed", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        assert.equal(executionVerdict((await store.get(cp.token))).kind, "unknown");
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        const before = (await store.get(cp.token));
+        assert.equal(executionVerdict(before).kind, "unknown", "a resolved row with no record reads UNKNOWN — never allowed by default");
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, VETOED_BY_POLICY), "recorded");
+        const after = (await store.get(cp.token));
+        assert.deepEqual(after.executionOutcome, VETOED_BY_POLICY);
+        assert.equal(typeof after.executionAtMs, "number");
+        assert.equal(Number.isFinite(after.executionAtMs), true);
+        assert.deepEqual(executionVerdict(after), { kind: "executed", gate: VETOED_BY_POLICY });
+        assert.deepEqual(after.resolvedOutcome, before.resolvedOutcome);
+        assert.equal(after.status, "resolved");
+        assert.equal(after.rev, before.rev);
+    });
+    run("recordExecutionOutcome is idempotent on the SAME record (structural, key-order-blind) → `already_recorded`; a DIFFERENT record throws checkpoint.execution_outcome_conflict and the row is byte-identical", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, EXECUTED_ALLOW), "recorded");
+        const filed = (await store.get(cp.token));
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, EXECUTED_ALLOW), "already_recorded");
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, EXECUTED_ALLOW_REORDERED), "already_recorded", "equality is over the record's JSON — key order and freezing are not part of the value");
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, structuredClone(EXECUTED_ALLOW)), "already_recorded", "an unfrozen structural twin is the same record");
+        await assert.rejects(store.recordExecutionOutcome(cp.token, cp.scope, VETOED_BY_POLICY), (e) => e.code === "checkpoint.execution_outcome_conflict");
+        const still = (await store.get(cp.token));
+        assert.deepEqual(still.executionOutcome, filed.executionOutcome);
+        assert.equal(still.executionAtMs, filed.executionAtMs, "a conflict writes nothing — not even a fresh stamp");
+    });
+    run("recordExecutionOutcome answers `not_resolved` for a pending and for an expired row, `absent` for a missing row and for a wrong-scope row; none of them write", async () => {
+        const store = make();
+        const pending = createCheckpointFixture();
+        await store.put(pending.token, pending);
+        assert.equal(await store.recordExecutionOutcome(pending.token, pending.scope, EXECUTED_ALLOW), "not_resolved");
+        assert.equal((await store.get(pending.token)).executionOutcome, undefined);
+        assert.equal(await store.recordExecutionOutcome(pending.token, "tenant-b", EXECUTED_ALLOW), "absent", "a wrong-scope row reads exactly like a missing one (the isolation rule)");
+        assert.equal(await store.recordExecutionOutcome(mintCheckpointToken(), pending.scope, EXECUTED_ALLOW), "absent");
+        const expired = createCheckpointFixture();
+        await store.put(expired.token, expired);
+        assert.equal(await store.expire(expired.token, expired.scope), true);
+        assert.equal(await store.recordExecutionOutcome(expired.token, expired.scope, EXECUTED_ALLOW), "not_resolved");
+        assert.equal((await store.get(expired.token)).executionOutcome, undefined);
+    });
+    run("reopen is refused on a row that carries an execution record (a settled action is not re-openable); the same row reopens before the record lands", async () => {
+        const store = make();
+        const cp = createCheckpointFixture();
+        await store.put(cp.token, cp);
+        await store.resolve(cp.token, cp.scope, ALLOW);
+        assert.equal(await store.reopen(cp.token, cp.scope, "env_failed"), true);
+        assert.equal(await store.resolve(cp.token, cp.scope, ALLOW, { rev: 2 }), true);
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, EXECUTED_ALLOW), "recorded");
+        assert.equal(await store.reopen(cp.token, cp.scope, "env_failed"), false);
+        assert.equal(await store.reopen(cp.token, cp.scope, "tool_unavailable"), false, "no reason reopens a recorded row");
+        const got = (await store.get(cp.token));
+        assert.equal(got.status, "resolved");
+        assert.equal(got.rev, 3, "a refused reopen bumps nothing");
+        assert.equal(got.reopenReason, undefined);
+        assert.deepEqual(got.executionOutcome, EXECUTED_ALLOW);
+    });
+    run("a row filed WITH an execution record (a restored resolved row) keeps it authoritative: get() returns it, reopen is refused, a different record conflicts, the same one is already_recorded", async () => {
+        const store = make();
+        const cp = createCheckpointFixture({ status: "resolved", rev: 1, executionOutcome: EXECUTED_ALLOW, executionAtMs: 1_700_000_001_000 });
+        await store.put(cp.token, cp);
+        const back = (await store.get(cp.token));
+        assert.deepEqual(back.executionOutcome, EXECUTED_ALLOW);
+        assert.equal(back.executionAtMs, 1_700_000_001_000);
+        assert.equal(await store.reopen(cp.token, cp.scope, "env_failed"), false, "a restored recorded row is as settled as a live one");
+        await assert.rejects(store.recordExecutionOutcome(cp.token, cp.scope, VETOED_BY_POLICY), (e) => e.code === "checkpoint.execution_outcome_conflict");
+        assert.equal(await store.recordExecutionOutcome(cp.token, cp.scope, EXECUTED_ALLOW), "already_recorded");
+        assert.equal((await store.get(cp.token)).status, "resolved");
+    });
     run("put create-once → already_exists", async () => {
         const store = make();
         const cp = createCheckpointFixture();
@@ -216,6 +301,29 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
+    run("design/388 B18 × B6 identity + face group: a row's seven optional members (capabilityId/contractId/shapeDigest/implementationRevision/rosterDigest + family/pathTarget) survive the round-trip verbatim; an absent group stays absent", async () => {
+        const store = make();
+        const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
+        const group = {
+            capabilityId: "caller::Write@acme.write@2",
+            contractId: "acme.write@2",
+            shapeDigest: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+            implementationRevision: "r7",
+            rosterDigest: "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
+            family: "file-write",
+            pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
+        };
+        Object.assign(carried.pendingAction, group);
+        const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-bare" });
+        for (const cp of [carried, bare])
+            await store.put(cp.token, cp);
+        const back = (await store.get(carried.token)).pendingAction;
+        for (const [k, v] of Object.entries(group))
+            assert.deepEqual(back[k], v, `the row's ${k} must survive the round-trip verbatim (a whitelisting serializer that drops it makes every resume-edit recheck judge by the catalog's slot for the NAME)`);
+        const bareBack = (await store.get(bare.token)).pendingAction;
+        for (const k of Object.keys(group))
+            assert.equal(k in bareBack, false, `an absent ${k} must stay OMITTED (a pre-388 row reads name-only, never a partial face)`);
+    });
     run("#457 previewWithheld three-form matrix: a row's spelling survives + projects; absent stays absent; an out-of-contract spelling reads as absent", async () => {
         const store = make();
         const oversize = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-oversize" });

package/dist/core/task-event.d.ts

@@ -885,6 +885,16 @@ export type TaskEvent = ({
      */
     type: "wiring_manifest";
     manifest: import("./wiring-manifest.js").WiringManifest;
+} & TaskEventIdentity) | ({
+    /**
+     * design/388 §2.5 — a RUN-TIME change to this leg's mounted tool set (today: the RefreshMcpTools
+     * seam re-inserting a server's tools in place). Carries the WHOLE post-change roster (positions
+     * come from it; a consumer replaces its copy) plus a summary usable only when the consumer holds
+     * `fromDigest` — otherwise it adopts the snapshot and records a skew (never rejects). The prepared
+     * roster itself rides `wiring_manifest.manifest.tools`; this frame never precedes that one.
+     */
+    type: "tool_roster_delta";
+    delta: import("./tool-roster.js").ToolRosterDelta;
 } & TaskEventIdentity) | {
     type: "done";
     result: TaskResult;

package/dist/core/task-registry.js

@@ -9,8 +9,9 @@ import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-re
 import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
 import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
-import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
+import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
 import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
+import { toolFace } from "./tool-catalog-entries.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 const BLOCK_DEFAULT_TIMEOUT_MS = 30_000;
 const BLOCK_MAX_TIMEOUT_MS = 600_000;
@@ -1234,10 +1235,9 @@ export function createTaskOutputTool(opts) {
     const caps = { ...REGISTRY_TASK_TOOL_CAPS, notification: opts.notificationWired !== false };
     return defineTool({
         name: TASK_OUTPUT_TOOL_NAME,
-        contract: TASK_OUTPUT_CONTRACT,
+        ...toolFace("task-output"),
         description: composeTaskOutputDescription(caps),
         parameters: composeTaskOutputParams(caps),
-        effect: "read",
         execute: async (rawArgs, ctx) => {
             const args = rawArgs;
             const id = resolveTaskIdArg(args.task_id);
@@ -1283,10 +1283,9 @@ export function createTaskOutputTool(opts) {
 export function createTaskStopTool(opts) {
     return defineTool({
         name: TASK_STOP_TOOL_NAME,
-        contract: TASK_STOP_CONTRACT,
+        ...toolFace("task-stop"),
         description: composeTaskStopDescription(REGISTRY_TASK_TOOL_CAPS),
         parameters: TASK_STOP_PARAMS,
-        effect: "write",
         execute: async (rawArgs, ctx) => {
             const args = rawArgs;
             const id = resolveTaskIdArg(args.task_id, args.shell_id);

package/dist/core/task-spec.d.ts

@@ -387,6 +387,14 @@ export interface TaskSpec {
      * owns that risk, same trust level as assembling `spec.tools` itself.
      */
     excludeTools?: string[];
+    /**
+     * design/388 §2.2 ⑥ — unmount the WHOLE tool face: the leg mounts nothing (no hands, no
+     * scaffolds, no MCP or skill tools; the effect roster reads `entries: []` and the model request
+     * carries `tools: []`). The utility-task shape a shell used to express with a hand-kept exclusion
+     * list. Not spelled `excludeTools: ["*"]` on purpose — `"*"` is a legal caller tool name (only `__`
+     * is reserved). `excludeTools` beside it is redundant, not an error.
+     */
+    excludeAllTools?: true;
     /**
      * Per-request DEFERRED disclosure for ALREADY-MOUNTED tools (built-ins
      * included — `ToolSpec.defer` only covers caller specs): wire names listed here ship as

package/dist/core/tool-catalog-entries.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The STATIC TOOL CATALOG (design/388 §2.1 "静态目录"): one row per built-in / synthetic tool DEFINITION
+ * core owns — its wire name, the conditions core (or a host scenario factory) mounts it under, the
+ * `details.type` cards it mints, and its declared FACE (family / axes / contract / path target / rule
+ * vocabulary / render hints / policy bits).
+ *
+ * SINGLE SOURCE, TWO READERS. Each definition module spreads its row's `face` into the `ToolSpec` it
+ * hands `defineTool` (`...TOOL_FACES.read`), so the face a tool declares at mount time IS the face
+ * listed here — there is no second declaration to drift. The effect roster (tool-roster.ts) reads every
+ * axis off the MOUNTED INSTANCE; the static catalog (`describeToolCatalog()`) reads this table without
+ * an env or a deps object. The conformance gate (test/tool-catalog-conformance.test.ts) proves the two
+ * agree for every definition it can instantiate; the catalog completeness gate
+ * (scripts/verify-tool-catalog.mjs) proves every `defineTool` site in src/ that mints a core-owned name
+ * has a row here that declares a `family` — a missing declaration is a RED gate naming the file, never a
+ * silent `"other"`.
+ *
+ * LEAF MODULE by design: it imports vocabulary types and one leaf constant module only. Every definition
+ * module and every policy module that derives a name set from the catalog imports THIS file, so a
+ * dependency from here back into a tool module would be a load-order cycle with a `const` table in it.
+ *
+ * Keyed by DEFINITION identity (`id`), not by name — the full and the read-only shell both answer to
+ * `Bash`; a catalog predicate counts a name as a member when ANY row under that name matches.
+ */
+import type { ToolCatalogEntry, ToolFaceDeclaration } from "./tool-face.js";
+/** The full shell's contract id — declared here (the leaf) and re-exported by fs-bash.ts. */
+export declare const FULL_SHELL_CONTRACT_ID = "core.bash@1";
+export declare const READONLY_SHELL_CONTRACT_ID = "core.bash_readonly@1";
+/** Wire-name constants for definitions that had none (design/388 A-21: literals become references). */
+export declare const TASK_CREATE_TOOL_NAME = "TaskCreate";
+export declare const TASK_GET_TOOL_NAME = "TaskGet";
+export declare const TASK_UPDATE_TOOL_NAME = "TaskUpdate";
+export declare const TASK_LIST_TOOL_NAME = "TaskList";
+export declare const TODO_WRITE_TOOL_NAME = "TodoWrite";
+export declare const REFRESH_MCP_TOOLS_TOOL_NAME = "RefreshMcpTools";
+/**
+ * Every row. Order is documentation order (hands → delegation → scaffolds → memory → scheduler → host
+ * scenarios); nothing reads the order.
+ */
+export declare const TOOL_CATALOG_ENTRIES: readonly ToolCatalogEntry[];
+/**
+ * `details.type` cards the ENGINE mints outside any tool definition — the protocol channels' result
+ * cards and the fs boundary refusals (minted by the shared safety module on behalf of every fs tool).
+ */
+export declare const ENGINE_CARDS: Readonly<Record<string, string>>;
+/** The declared face of one definition, by definition id — what a definition module spreads into its spec. */
+export declare function toolFace(id: string): ToolFaceDeclaration;
+/** Definition-id → face, for the modules that spread one (`...TOOL_FACES.read`). Frozen: a face is data. */
+export declare const TOOL_FACES: Readonly<Record<string, ToolFaceDeclaration>>;

package/dist/core/tool-catalog-entries.js

@@ -0,0 +1,174 @@
+import { TASK_OUTPUT_CONTRACT, TASK_STOP_CONTRACT } from "./task-tool-shape.js";
+export const FULL_SHELL_CONTRACT_ID = "core.bash@1";
+export const READONLY_SHELL_CONTRACT_ID = "core.bash_readonly@1";
+export const TASK_CREATE_TOOL_NAME = "TaskCreate";
+export const TASK_GET_TOOL_NAME = "TaskGet";
+export const TASK_UPDATE_TOOL_NAME = "TaskUpdate";
+export const TASK_LIST_TOOL_NAME = "TaskList";
+export const TODO_WRITE_TOOL_NAME = "TodoWrite";
+export const REFRESH_MCP_TOOLS_TOOL_NAME = "RefreshMcpTools";
+const SHELL_RULE_FACE = { primaryParams: ["command"], params: ["command", "timeout", "description", "run_in_background"] };
+const c = (contractId, implementationRevision = "1") => ({ contractId, implementationRevision });
+export const TOOL_CATALOG_ENTRIES = [
+    {
+        id: "read", name: "Read", source: "builtin", definedIn: "src/tools/fs/fs-read.ts", mountedBy: ["hands"],
+        cards: ["text", "notebook", "file_unchanged", "image", "document"],
+        face: {
+            family: "file-read", effect: "read", contract: c("core.read@1"),
+            pathTarget: { param: "file_path", aliases: ["path"], access: "read" },
+            ruleFace: { params: ["file_path", "path", "offset", "limit", "pages"] },
+            renderHints: { summaryParams: ["file_path"] },
+            offload: false, compactable: true, budgetExempt: true,
+        },
+    },
+    {
+        id: "edit", name: "Edit", source: "builtin", definedIn: "src/tools/fs/fs-write.ts", mountedBy: ["hands"],
+        cards: ["edit"],
+        face: {
+            family: "file-write", effect: "write", contract: c("core.edit@1"),
+            pathTarget: { param: "file_path", aliases: ["path"], access: "edit", skillScopeEligible: true },
+            ruleFace: { params: ["file_path", "path", "old_string", "new_string", "replace_all"] },
+            renderHints: { summaryParams: ["file_path"], approvalCard: "file-edit" },
+            compactable: true,
+        },
+    },
+    {
+        id: "write", name: "Write", source: "builtin", definedIn: "src/tools/fs/fs-write.ts", mountedBy: ["hands"],
+        cards: ["create", "update"],
+        face: {
+            family: "file-write", effect: "write", contract: c("core.write@1"),
+            pathTarget: { param: "file_path", aliases: ["path"], access: "create", skillScopeEligible: true },
+            ruleFace: { params: ["file_path", "path", "content"] },
+            renderHints: { summaryParams: ["file_path"], approvalCard: "file-write" },
+            offload: false, compactable: true,
+        },
+    },
+    {
+        id: "notebook-edit", name: "NotebookEdit", source: "builtin", definedIn: "src/tools/fs/fs-write.ts", mountedBy: ["hands"],
+        cards: ["notebook-edit"],
+        face: {
+            family: "file-write", effect: "write", contract: c("core.notebook_edit@1"),
+            pathTarget: { param: "notebook_path", aliases: ["path"], access: "edit" },
+            ruleFace: { params: ["notebook_path", "path", "cell_id", "cell_type", "edit_mode", "new_source"] },
+            renderHints: { userFacingName: "Edit Notebook", summaryParams: ["notebook_path"], approvalCard: "notebook-edit" },
+        },
+    },
+    {
+        id: "bash", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
+        cards: ["bash", "bash_invalid_timeout"],
+        face: {
+            family: "shell", effect: "write", contentOrigin: "execution", contract: c(FULL_SHELL_CONTRACT_ID),
+            ruleFace: SHELL_RULE_FACE,
+            renderHints: { summaryParams: ["command"], approvalCard: "shell" },
+            offloadThresholdChars: 30_000, compactable: true,
+        },
+    },
+    {
+        id: "bash-readonly", name: "Bash", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"],
+        cards: ["bash", "readonly_out_of_root", "bash_invalid_timeout"],
+        face: {
+            family: "shell", effect: "read", contract: c(READONLY_SHELL_CONTRACT_ID),
+            ruleFace: SHELL_RULE_FACE,
+            renderHints: { summaryParams: ["command"], approvalCard: "shell" },
+            offloadThresholdChars: 30_000, compactable: true,
+        },
+    },
+    {
+        id: "grep", name: "Grep", source: "builtin", definedIn: "src/tools/fs/fs-search-tools.ts", mountedBy: ["hands"],
+        cards: ["grep"],
+        face: {
+            family: "search", effect: "read", contract: c("core.grep@1"),
+            pathTarget: { param: "path", access: "read" },
+            ruleFace: { params: ["pattern", "path", "glob", "type", "output_mode", "head_limit", "offset", "multiline", "context", "ignore_case", "-i", "-n", "-o", "-A", "-B", "-C"] },
+            renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
+            offloadThresholdChars: 20_000, compactable: true,
+        },
+    },
+    {
+        id: "glob", name: "Glob", source: "builtin", definedIn: "src/tools/fs/fs-search-tools.ts", mountedBy: ["hands"],
+        cards: ["glob"],
+        face: {
+            family: "search", effect: "read", contract: c("core.glob@1"),
+            pathTarget: { param: "path", access: "read" },
+            ruleFace: { params: ["pattern", "path", "max_results"] },
+            renderHints: { userFacingName: "Search", summaryParams: ["pattern", "path"] },
+            compactable: true,
+        },
+    },
+    { id: "repo-map", name: "RepoMap", source: "builtin", definedIn: "src/tools/fs/repo-map.ts", mountedBy: ["hands"], cards: ["repo-map"], face: { family: "search", effect: "read", contract: c("core.repo_map@1") } },
+    { id: "lsp", name: "LSP", source: "builtin", definedIn: "src/core/lsp.ts", mountedBy: ["optional"], cards: [], face: { family: "search", effect: "read", contract: c("core.lsp@1") } },
+    { id: "enter-worktree", name: "EnterWorktree", source: "builtin", definedIn: "src/tools/worktree.ts", mountedBy: ["hands"], cards: ["worktree"], face: { family: "other", effect: "write", contract: c("core.enter_worktree@1") } },
+    { id: "exit-worktree", name: "ExitWorktree", source: "builtin", definedIn: "src/tools/worktree.ts", mountedBy: ["hands"], cards: ["worktree"], face: { family: "other", effect: "write", contract: c("core.exit_worktree@1") } },
+    { id: "task-output-hands", name: "TaskOutput", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"], cards: [], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
+    { id: "task-stop-hands", name: "TaskStop", source: "builtin", definedIn: "src/tools/fs/fs-bash.ts", mountedBy: ["hands"], cards: [], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
+    { id: "task-output", name: "TaskOutput", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-output"], face: { family: "delegate", effect: "read", contract: TASK_OUTPUT_CONTRACT } },
+    { id: "task-stop", name: "TaskStop", source: "builtin", definedIn: "src/core/task-registry.ts", mountedBy: ["delegation"], cards: ["task-stop"], face: { family: "delegate", effect: "write", contract: TASK_STOP_CONTRACT } },
+    { id: "monitor", name: "Monitor", source: "builtin", definedIn: "src/tools/monitor.ts", mountedBy: ["backgroundTasks"], cards: ["monitor-start"], face: { family: "other", effect: "write", contract: c("core.monitor@1"), offloadThresholdChars: 10_000 } },
+    { id: "send-message", name: "SendMessage", source: "builtin", definedIn: "src/agents/send-message-tool.ts", mountedBy: ["delegation", "hostInternals", "peerLane"], cards: ["send-message"], face: { family: "protocol", effect: "write", contract: c("core.send_message@1") } },
+    { id: "agent-transcript", name: "AgentTranscript", source: "builtin", definedIn: "src/agents/agent-transcript-tool.ts", mountedBy: ["delegation"], cards: ["agent-transcript"], face: { family: "delegate", effect: "read", contract: c("core.agent_transcript@1") } },
+    { id: "list-agents", name: "ListAgents", source: "builtin", definedIn: "src/agents/list-agents-tool.ts", mountedBy: ["peerLane"], cards: ["list-agents"], face: { family: "protocol", effect: "read", aliases: ["ListPeers"], contract: c("core.list_agents@1") } },
+    { id: "workflow", name: "Workflow", source: "builtin", definedIn: "src/orchestration/run-workflow-tool.ts", mountedBy: ["workflow"], cards: ["workflow-run"], face: { family: "delegate", effect: "write", contract: c("core.workflow@1") } },
+    { id: "report-blocked", name: "ReportBlocked", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.report_blocked@1") } },
+    { id: "report-findings", name: "ReportFindings", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["always"], cards: ["report-findings"], face: { family: "scaffold", effect: "read", contract: c("core.report_findings@1") } },
+    { id: "structured-output", name: "StructuredOutput", source: "synthetic", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.structured_output@1") } },
+    { id: "skill", name: "Skill", source: "builtin", definedIn: "src/core/runner/synthetic-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.skill@1") } },
+    { id: "read-tool-result", name: "ReadToolResult", source: "builtin", definedIn: "src/core/tool-result-store.ts", mountedBy: ["optional"], cards: [], face: { family: "scaffold", effect: "read", contract: c("core.read_tool_result@1"), budgetExempt: true } },
+    { id: "tool-search", name: "ToolSearch", source: "builtin", definedIn: "src/core/runner/tool-disclosure.ts", mountedBy: ["optional"], cards: ["tool-search"], face: { family: "scaffold", effect: "read", contract: c("core.tool_search@1") } },
+    { id: "ask-user-question", name: "AskUserQuestion", source: "builtin", definedIn: "src/core/ask-question.ts", mountedBy: ["optional"], cards: ["ask-question"], face: { family: "other", effect: "read", contract: c("core.ask_user_question@1"), renderHints: { approvalCard: "question" } } },
+    { id: "exit-plan-mode", name: "ExitPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["exit-plan-mode"], face: { family: "plan", effect: "read", contract: c("core.exit_plan_mode@1"), renderHints: { userFacingName: "", approvalCard: "plan" } } },
+    { id: "enter-plan-mode", name: "EnterPlanMode", source: "builtin", definedIn: "src/core/present-plan-tool.ts", mountedBy: ["optional"], cards: ["enter-plan-mode"], face: { family: "plan", effect: "read", contract: c("core.enter_plan_mode@1") } },
+    { id: "refresh-mcp-tools", name: REFRESH_MCP_TOOLS_TOOL_NAME, source: "builtin", definedIn: "src/core/runner/prepare-protocol-tools.ts", mountedBy: ["optional"], cards: [], face: { family: "protocol", effect: "read" } },
+    { id: "memory-search", name: "memory_search", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_search@1", "6"), offload: false } },
+    { id: "memory-get", name: "memory_get", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_get@1", "6"), offload: false } },
+    { id: "memory-index", name: "memory_index", source: "builtin", definedIn: "src/core/memory-engine/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contentOrigin: "local", contract: c("core.memory_index@1"), offload: false } },
+    { id: "memory-list", name: "memory_list", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contract: c("core.memory_list@1"), offload: false } },
+    { id: "memory-read", name: "memory_read", source: "builtin", definedIn: "src/core/shared-memory/tools.ts", mountedBy: ["memory"], cards: [], face: { family: "memory", effect: "read", contract: c("core.memory_read@1"), offload: false } },
+    { id: "cron-create", name: "CronCreate", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-create"], face: { family: "other", effect: "write", contract: c("core.cron_create@1") } },
+    { id: "cron-delete", name: "CronDelete", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-delete"], face: { family: "other", effect: "idempotent", contract: c("core.cron_delete@1") } },
+    { id: "cron-list", name: "CronList", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["cron-list"], face: { family: "other", effect: "read", contract: c("core.cron_list@1") } },
+    { id: "schedule-wakeup", name: "ScheduleWakeup", source: "builtin", definedIn: "src/tools/scheduler-tools.ts", mountedBy: ["scheduler"], cards: ["schedule-wakeup"], face: { family: "other", effect: "write", contract: c("core.schedule_wakeup@1") } },
+    {
+        id: "web-fetch", name: "WebFetch", source: "builtin", definedIn: "src/tools/web.ts", mountedBy: ["scenario"], cards: ["web-fetch"],
+        face: { family: "web", effect: "read", contentOrigin: "external", contract: c("core.web_fetch@1"), ruleFace: { primaryParams: ["url"] }, renderHints: { summaryParams: ["url"], approvalCard: "fetch" }, compactable: true },
+    },
+    {
+        id: "web-search", name: "WebSearch", source: "builtin", definedIn: "src/tools/web.ts", mountedBy: ["scenario"], cards: ["web-search"],
+        face: { family: "web", effect: "read", contentOrigin: "external", contract: c("core.web_search@1"), ruleFace: { primaryParams: ["query"] }, renderHints: { summaryParams: ["query"] }, compactable: true },
+    },
+    { id: "todo-write", name: TODO_WRITE_TOOL_NAME, source: "builtin", definedIn: "src/tools/todo.ts", mountedBy: ["scenario"], cards: ["todo"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.todo_write@1") } },
+    { id: "task-create", name: TASK_CREATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "write", contract: c("core.task_create@1") } },
+    { id: "task-get", name: TASK_GET_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_get@1") } },
+    { id: "task-update", name: TASK_UPDATE_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task"], modelGate: "task-scaffold", face: { family: "plan", effect: "idempotent", contract: c("core.task_update@1") } },
+    { id: "task-list", name: TASK_LIST_TOOL_NAME, source: "builtin", definedIn: "src/tools/task-list.ts", mountedBy: ["scenario"], cards: ["task-list"], modelGate: "task-scaffold", face: { family: "plan", effect: "read", contract: c("core.task_list@1") } },
+    { id: "agent", name: "Agent", source: "builtin", definedIn: "src/agents/subagent.ts", mountedBy: ["scenario"], cards: ["agent", "fork"], face: { family: "delegate", contentOrigin: "local", contract: c("core.agent@1") } },
+    { id: "observer-report", name: "ObserverReport", source: "builtin", definedIn: "src/agents/observer.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "write", contract: c("core.observer_report@1") } },
+    { id: "declare-done", name: "DeclareDone", source: "builtin", definedIn: "src/orchestration/goal.ts", mountedBy: ["scenario"], cards: [], face: { family: "scaffold", effect: "read" } },
+];
+export const ENGINE_CARDS = Object.freeze({
+    mcp: "src/core/mcp.ts",
+    a2a: "src/core/a2a.ts",
+    path_not_in_root: "src/tools/fs/safety.ts",
+    read_path_denied: "src/tools/fs/safety.ts",
+});
+const byId = new Map();
+for (const e of TOOL_CATALOG_ENTRIES) {
+    if (byId.has(e.id))
+        throw new Error(`tool catalog: duplicate definition id ${JSON.stringify(e.id)}`);
+    byId.set(e.id, e);
+}
+export function toolFace(id) {
+    const e = byId.get(id);
+    if (e === undefined)
+        throw new Error(`tool catalog: no definition ${JSON.stringify(id)}`);
+    return structuredClone(e.face);
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const k of Object.keys(value))
+            deepFreeze(value[k]);
+    }
+    return value;
+}
+deepFreeze(TOOL_CATALOG_ENTRIES);
+export const TOOL_FACES = Object.freeze(Object.fromEntries(TOOL_CATALOG_ENTRIES.map((e) => [e.id, e.face])));

package/dist/core/tool-conformance.d.ts

@@ -0,0 +1,22 @@
+import type { ToolMountTag } from "./tool-face.js";
+export interface ToolConformanceVector {
+    id: string;
+    /** The mount conditions the vector activates. */
+    active: readonly ToolMountTag[];
+    /** Predicted names the vector cannot mount, each with the seat it lacks. */
+    absent: ReadonlyArray<{
+        name: string;
+        why: string;
+    }>;
+    /** Mounted names no tag spells, each with the seat that mounts them. */
+    extra: ReadonlyArray<{
+        name: string;
+        why: string;
+    }>;
+    /** The vector's expected core-mounted name set: predict(active) − absent + extra. */
+    expected: readonly string[];
+}
+/** The matrix. Vector ids are stable (a host's own conformance test keys on them). */
+export declare const TOOL_CONFORMANCE_VECTORS: readonly ToolConformanceVector[];
+/** The matrix as a host reads it (a frozen copy). */
+export declare function describeToolConformanceVectors(): readonly ToolConformanceVector[];

package/dist/core/tool-conformance.js

@@ -0,0 +1,37 @@
+import { predictMountedToolNames } from "./tool-registry.js";
+const vector = (id, active, absent = [], extra = []) => {
+    const predicted = new Set(predictMountedToolNames(new Set(active)));
+    for (const a of absent)
+        predicted.delete(a.name);
+    for (const e of extra)
+        predicted.add(e.name);
+    return { id, active, absent, extra, expected: [...predicted].sort() };
+};
+const OFFLOAD_READER = { name: "ReadToolResult", why: "the offload store is wired by default (the deployment threshold), an `optional` seat every vector carries" };
+export const TOOL_CONFORMANCE_VECTORS = [
+    vector("bare", ["always"], [], [OFFLOAD_READER]),
+    vector("hands-full", ["always", "hands", "backgroundTasks", "delegation"], [
+        { name: "SendMessage", why: "needs the runner self seat (a direct prepare has none)" },
+        { name: "AgentTranscript", why: "needs the runner self seat (a direct prepare has none)" },
+    ], [OFFLOAD_READER]),
+    vector("hands-readonly", ["always", "hands"], [
+        { name: "Edit", why: "the read-only band mounts the read half only" },
+        { name: "Write", why: "the read-only band mounts the read half only" },
+        { name: "NotebookEdit", why: "the read-only band mounts the read half only" },
+        { name: "TaskOutput", why: "the background-shell pair mounts on the full shell only" },
+        { name: "TaskStop", why: "the background-shell pair mounts on the full shell only" },
+        { name: "EnterWorktree", why: "the worktree pair needs the tracked cwd the full shell owns" },
+        { name: "ExitWorktree", why: "the worktree pair needs the tracked cwd the full shell owns" },
+    ], [OFFLOAD_READER]),
+    vector("plan-mode", ["always", "optional"], [
+        { name: "LSP", why: "needs a wired LSP manager" },
+        { name: "Skill", why: "needs a skills listing" },
+        { name: "StructuredOutput", why: "needs an output schema" },
+        { name: "ToolSearch", why: "needs a deferred tool" },
+        { name: "RefreshMcpTools", why: "needs a declared MCP server" },
+        { name: "EnterPlanMode", why: "needs a checkpoint store beside plan mode" },
+    ]),
+];
+export function describeToolConformanceVectors() {
+    return TOOL_CONFORMANCE_VECTORS;
+}