@sema-agent/core 7.7.0 → 7.8.0

package/dist/core/tool-roster.js

@@ -0,0 +1,497 @@
+import { createHash } from "node:crypto";
+import { Type } from "typebox";
+import { getToolContract } from "../prompt-assembly/tool-catalog.js";
+import { protocolOf } from "./protocol-table.js";
+import { RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_APPROVAL_CARDS, TOOL_FAMILIES, TOOL_KEYS_MAX, TOOL_KEY_MAX_CHARS, TOOL_MOUNT_TAGS, } from "./tool-face.js";
+function lit(values) {
+    return Type.Union(values.map((v) => Type.Literal(v)));
+}
+const Name = Type.String({ minLength: 1, maxLength: 128 });
+const Short = Type.String({ maxLength: 64 });
+const Key = Type.String({ maxLength: TOOL_KEY_MAX_CHARS });
+const Digest16 = Type.String({ minLength: 16, maxLength: 16 });
+export const ROSTER_SOURCES = ["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"];
+export const ToolRosterRenderHints = Type.Object({
+    userFacingName: Type.Optional(Type.String({ maxLength: RENDER_HINT_MAX_CHARS })),
+    activity: Type.Optional(Type.String({ maxLength: RENDER_HINT_ACTIVITY_MAX_CHARS })),
+    summaryParams: Type.Optional(Type.Array(Key, { maxItems: RENDER_HINT_MAX_LIST })),
+    resultCards: Type.Optional(Type.Array(Key, { maxItems: RENDER_HINT_MAX_LIST })),
+    approvalCard: Type.Optional(lit(TOOL_APPROVAL_CARDS)),
+}, { additionalProperties: false });
+export const ToolRosterEntry = Type.Object({
+    name: Name,
+    aliases: Type.Array(Name, { uniqueItems: true }),
+    source: lit(ROSTER_SOURCES),
+    origin: Type.Optional(Type.Object({ peer: Name, declaredBy: Type.Optional(lit(["center", "file", "request"])) }, { additionalProperties: false })),
+    contract: Type.Object({ contractId: Short, implementationRevision: Short }, { additionalProperties: false }),
+    shapeDigest: Digest16,
+    wireSchemaDigest: Digest16,
+    cardId: Type.String({ maxLength: 160 }),
+    capabilityId: Digest16,
+    inputKeys: Type.Array(Type.Object({ name: Key, type: lit(["string", "number", "integer", "boolean", "object", "array", "null", "mixed"]) }, { additionalProperties: false }), { maxItems: TOOL_KEYS_MAX }),
+    effect: lit(["read", "write", "idempotent"]),
+    effectProvenance: lit(["declared", "caller", "synthetic", "default"]),
+    offload: Type.Boolean(),
+    offloadThresholdChars: Type.Optional(Type.Integer({ minimum: 0 })),
+    compactable: Type.Boolean(),
+    budgetExempt: Type.Boolean(),
+    egress: Type.Boolean(),
+    egressProvenance: lit(["declared", "caller", "default"]),
+    irreversibility: Type.Optional(lit(["never", "maybe", "always"])),
+    reversibilityProbe: Type.Boolean(),
+    contentOrigin: lit(["local", "execution", "external"]),
+    contentOriginProvenance: lit(["declared", "server", "exempted", "default"]),
+    family: lit(TOOL_FAMILIES),
+    pathTarget: Type.Optional(Type.Object({ param: Key, aliases: Type.Array(Key), access: lit(["read", "create", "edit"]), skillScopeEligible: Type.Boolean() }, { additionalProperties: false })),
+    ruleFace: Type.Object({ primaryParams: Type.Array(Key), params: Type.Array(Key) }, { additionalProperties: false }),
+    approvalPreview: Type.Boolean(),
+    validateInput: Type.Boolean(),
+    deferred: Type.Boolean(),
+    alwaysLoad: Type.Boolean(),
+    modelGate: Type.Optional(Short),
+    renderHints: Type.Optional(ToolRosterRenderHints),
+    mountedBy: lit(TOOL_MOUNT_TAGS),
+}, { additionalProperties: false });
+export const ToolRoster = Type.Object({
+    schemaVersion: Type.Literal(1),
+    count: Type.Integer({ minimum: 0 }),
+    entries: Type.Array(ToolRosterEntry, { maxItems: 2048 }),
+    digest: Digest16,
+}, { additionalProperties: false });
+export const ToolRosterDelta = Type.Object({
+    fromDigest: Digest16,
+    roster: ToolRoster,
+    summary: Type.Object({ added: Type.Array(Name), removed: Type.Array(Name), changed: Type.Array(Name) }, { additionalProperties: false }),
+}, { additionalProperties: false });
+export function rosterEntryNamed(roster, toolName) {
+    return roster.entries.find((r) => r.name === toolName) ?? roster.entries.find((r) => r.aliases.includes(toolName));
+}
+export function toolCallFaceOf(roster, toolName) {
+    if (roster === undefined)
+        return undefined;
+    const e = rosterEntryNamed(roster, toolName);
+    if (e === undefined)
+        return undefined;
+    return {
+        family: e.family,
+        ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}),
+        capabilityId: e.capabilityId,
+        contractId: e.contract.contractId,
+        shapeDigest: e.shapeDigest,
+        implementationRevision: e.contract.implementationRevision,
+    };
+}
+export function parkedToolIdentity(roster, toolName) {
+    if (roster === undefined)
+        return {};
+    const e = rosterEntryNamed(roster, toolName);
+    if (e === undefined)
+        return {};
+    return { capabilityId: e.capabilityId, contractId: e.contract.contractId, shapeDigest: e.shapeDigest, implementationRevision: e.contract.implementationRevision, rosterDigest: roster.digest };
+}
+export function parkedToolFace(roster, toolName) {
+    if (roster === undefined)
+        return {};
+    const e = rosterEntryNamed(roster, toolName);
+    if (e === undefined)
+        return {};
+    return { family: e.family, ...(e.pathTarget !== undefined ? { pathTarget: e.pathTarget } : {}) };
+}
+export function parkedCallFaceOf(pending) {
+    if (pending.family === undefined || pending.capabilityId === undefined || pending.contractId === undefined || pending.shapeDigest === undefined || pending.implementationRevision === undefined)
+        return undefined;
+    return {
+        family: pending.family,
+        ...(pending.pathTarget !== undefined ? { pathTarget: pending.pathTarget } : {}),
+        capabilityId: pending.capabilityId,
+        contractId: pending.contractId,
+        shapeDigest: pending.shapeDigest,
+        implementationRevision: pending.implementationRevision,
+    };
+}
+export function callFaceSeat(face) {
+    return face !== undefined ? { face } : {};
+}
+export function toolIdentityOf(entry) {
+    return { capabilityId: entry.capabilityId, contractId: entry.contract.contractId, shapeDigest: entry.shapeDigest, implementationRevision: entry.contract.implementationRevision };
+}
+function canonical(node) {
+    if (Array.isArray(node))
+        return `[${node.map(canonical).join(",")}]`;
+    if (node === null || typeof node !== "object")
+        return JSON.stringify(node) ?? "null";
+    const keys = Object.keys(node).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(node[k])}`).join(",")}}`;
+}
+function sha16(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+export function mintCapabilityId(t) {
+    return sha16(canonical({ source: t.source, peer: t.peer, name: t.name, contractId: t.contractId }));
+}
+export function rosterDigestOf(entries) {
+    return sha16(canonical(entries));
+}
+const SCALAR_TYPES = new Set(["string", "number", "integer", "boolean"]);
+function schemaTypeOf(node) {
+    if (node === null || typeof node !== "object")
+        return { type: "mixed", scalar: false };
+    const s = node;
+    const branches = s["anyOf"] ?? s["oneOf"];
+    if (Array.isArray(branches) && branches.length > 0) {
+        const parts = branches.map(schemaTypeOf);
+        const scalar = parts.every((p) => p.scalar);
+        const first = parts[0].type;
+        return parts.every((p) => p.type === first) ? { type: first, scalar } : { type: "mixed", scalar };
+    }
+    if (s["const"] !== undefined) {
+        const t = typeof s["const"];
+        return t === "string" || t === "number" || t === "boolean" ? { type: t, scalar: true } : { type: "mixed", scalar: false };
+    }
+    const en = s["enum"];
+    if (Array.isArray(en) && en.length > 0) {
+        const kinds = new Set(en.map((v) => typeof v));
+        if (kinds.size === 1) {
+            const t = [...kinds][0];
+            if (t === "string" || t === "number" || t === "boolean")
+                return { type: t, scalar: true };
+        }
+        return { type: "mixed", scalar: [...kinds].every((k) => k === "string" || k === "number" || k === "boolean") };
+    }
+    const t = s["type"];
+    if (typeof t === "string") {
+        if (SCALAR_TYPES.has(t))
+            return { type: t, scalar: true };
+        if (t === "object" || t === "array" || t === "null")
+            return { type: t, scalar: false };
+    }
+    if (Array.isArray(t))
+        return { type: "mixed", scalar: t.every((x) => typeof x === "string" && SCALAR_TYPES.has(x)) };
+    if (s["properties"] !== undefined)
+        return { type: "object", scalar: false };
+    if (s["items"] !== undefined)
+        return { type: "array", scalar: false };
+    return { type: "mixed", scalar: false };
+}
+export function inputKeysOf(schema) {
+    const keys = [];
+    const scalar = new Set();
+    const props = schema?.properties;
+    if (props !== null && typeof props === "object" && !Array.isArray(props)) {
+        for (const [name, sub] of Object.entries(props)) {
+            const t = schemaTypeOf(sub);
+            keys.push({ name, type: t.type });
+            if (t.scalar)
+                scalar.add(name);
+        }
+    }
+    return { keys, scalar };
+}
+export function schemaKeyBoundProblem(schema) {
+    const props = schema?.properties;
+    if (props === null || typeof props !== "object" || Array.isArray(props))
+        return undefined;
+    const names = Object.keys(props);
+    if (names.length > TOOL_KEYS_MAX)
+        return `the schema declares ${names.length} top-level properties; a roster row carries at most ${TOOL_KEYS_MAX}`;
+    const long = names.find((n) => n.length > TOOL_KEY_MAX_CHARS);
+    if (long !== undefined)
+        return `the schema property ${JSON.stringify(long.slice(0, 40) + "…")} is ${long.length} characters; a roster key is at most ${TOOL_KEY_MAX_CHARS}`;
+    return undefined;
+}
+export function ruleFaceOfInstance(schema, declared, pathTarget) {
+    const { scalar } = inputKeysOf(schema);
+    const derived = new Set(scalar);
+    if (pathTarget !== undefined) {
+        derived.add(pathTarget.param);
+        for (const a of pathTarget.aliases ?? [])
+            derived.add(a);
+    }
+    const primary = declared?.primaryParams !== undefined ? [...declared.primaryParams] : pathTarget !== undefined ? [pathTarget.param, ...(pathTarget.aliases ?? [])] : [];
+    for (const p of primary)
+        derived.add(p);
+    const params = declared?.params !== undefined ? declared.params.filter((p) => derived.has(p)) : [...derived];
+    const ordered = [...new Set([...params, ...primary.filter((p) => params.includes(p) || declared?.params === undefined)])];
+    return { primaryParams: primary, params: ordered };
+}
+function capRenderHints(h) {
+    const out = {};
+    if (typeof h.userFacingName === "string")
+        out.userFacingName = h.userFacingName;
+    if (typeof h.activity === "string")
+        out.activity = h.activity;
+    if (Array.isArray(h.summaryParams))
+        out.summaryParams = h.summaryParams.filter((s) => typeof s === "string");
+    if (Array.isArray(h.resultCards))
+        out.resultCards = h.resultCards.filter((s) => typeof s === "string");
+    if (typeof h.approvalCard === "string" && TOOL_APPROVAL_CARDS.includes(h.approvalCard))
+        out.approvalCard = h.approvalCard;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+export const faceOf = (t) => t;
+function configError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export class RosterBuilder {
+    #tools = [];
+    #engineLane = [];
+    #meta = new WeakMap();
+    #effects;
+    constructor(effects) {
+        this.#effects = effects;
+    }
+    get tools() {
+        return this.#tools;
+    }
+    get length() {
+        return this.#tools.length;
+    }
+    metaOf(tool) {
+        return this.#meta.get(tool);
+    }
+    mount(tool, meta) {
+        this.#admit(tool, meta);
+        this.#tools.push(tool);
+    }
+    mountEngineLane(tool, meta) {
+        this.#admit(tool, meta);
+        this.#engineLane.push(tool);
+    }
+    #admit(tool, meta) {
+        if ((meta.source === "mcp" || meta.source === "a2a" || meta.source === "external") !== (meta.origin !== undefined)) {
+            throw configError("config.tool_roster_origin", `tool ${JSON.stringify(tool.name)}: a ${meta.source} mount ${meta.origin === undefined ? "requires" : "must not carry"} an origin`);
+        }
+        if (!TOOL_MOUNT_TAGS.includes(meta.mountedBy))
+            throw configError("config.tool_roster_mount_tag", `tool ${JSON.stringify(tool.name)}: mount tag ${JSON.stringify(meta.mountedBy)} is outside the closed set`);
+        this.#meta.set(tool, meta);
+        const eff = faceOf(tool).effect;
+        if (eff !== undefined && !(meta.mountedBy === "scenario" && this.#effects.has(tool.name)))
+            this.#effects.set(tool.name, eff);
+    }
+    mountAll(tools, meta) {
+        for (const t of tools)
+            this.mount(t, meta);
+    }
+    unmountWhere(pred) {
+        const removed = [];
+        for (let i = this.#tools.length - 1; i >= 0; i--) {
+            const t = this.#tools[i];
+            if (pred(t, i)) {
+                this.#tools.splice(i, 1);
+                removed.unshift(t);
+            }
+        }
+        return removed;
+    }
+    replaceAt(index, tool) {
+        const prior = this.#tools[index];
+        if (prior === undefined)
+            throw new Error(`roster: no tool at index ${index}`);
+        const meta = this.#meta.get(prior);
+        this.#tools[index] = tool;
+        if (meta !== undefined)
+            this.#meta.set(tool, meta);
+    }
+    replaceDomain(prefix, fresh, meta) {
+        let anchor = -1;
+        for (let i = this.#tools.length - 1; i >= 0; i--) {
+            if (this.#tools[i].name.startsWith(prefix)) {
+                anchor = i;
+                this.#tools.splice(i, 1);
+            }
+        }
+        for (const t of fresh) {
+            this.#meta.set(t, meta);
+            const eff = faceOf(t).effect;
+            if (eff !== undefined)
+                this.#effects.set(t.name, eff);
+        }
+        if (anchor >= 0)
+            this.#tools.splice(anchor, 0, ...fresh);
+        else
+            this.#tools.push(...fresh);
+        return { anchor };
+    }
+    snapshot(facts) {
+        const all = [...this.#tools, ...this.#engineLane];
+        const winner = new Map();
+        for (const t of all)
+            winner.set(t.name, t);
+        const entries = [];
+        const emitted = new Set();
+        for (const t of all) {
+            if (emitted.has(t.name))
+                continue;
+            emitted.add(t.name);
+            const survivor = winner.get(t.name);
+            const meta = this.#meta.get(survivor) ?? { source: "caller", mountedBy: "scenario" };
+            entries.push(mintRosterEntry(survivor, meta, facts));
+        }
+        return { schemaVersion: 1, count: entries.length, entries, digest: rosterDigestOf(entries) };
+    }
+}
+export function callerMountSource(tool) {
+    return getToolContract(tool, "caller").origin === "core" ? "builtin" : "caller";
+}
+export function mintRosterEntry(tool, meta, facts) {
+    const face = faceOf(tool);
+    const fallbackOrigin = meta.source === "builtin" ? "core" : meta.source === "synthetic" ? "synthetic" : meta.source === "mcp" || meta.source === "a2a" ? meta.source : "caller";
+    const d = getToolContract(tool, fallbackOrigin);
+    const peer = meta.origin?.peer ?? null;
+    const protocolTool = peer !== null ? protocolOf(tool.name)?.parse(tool.name)?.tool ?? tool.name : tool.name;
+    const cardId = meta.source === "builtin" || meta.source === "synthetic"
+        ? `builtin:${tool.name}`
+        : meta.source === "mcp" || meta.source === "a2a"
+            ? `${meta.source}:${peer}/${protocolTool}`
+            : `${meta.source === "external" ? "external" : "caller"}:${d.contractId}`;
+    const { keys: inputKeys } = inputKeysOf(tool.parameters);
+    const declaredEffect = face.effect;
+    const foldedEffect = facts.effects.get(tool.name);
+    const effect = declaredEffect ?? foldedEffect ?? "write";
+    const effectProvenance = declaredEffect !== undefined ? (meta.source === "synthetic" ? "synthetic" : "declared") : foldedEffect !== undefined && (meta.source === "mcp" || meta.source === "a2a") ? "caller" : "default";
+    const egress = face.egress === true || facts.egress.has(tool.name);
+    const egressProvenance = face.egress === true ? "declared" : egress ? "caller" : "default";
+    const irreversibility = face.irreversibility ?? facts.irreversibilityTier.get(tool.name);
+    const reversibilityProbe = face.reversibilityProbe !== undefined || facts.reversibilityProbes.has(tool.name);
+    const contentOrigin = face.contentOrigin ?? (facts.trustedTools.has(tool.name) ? "local" : "external");
+    const contentOriginProvenance = face.contentOrigin !== undefined ? (meta.source === "mcp" || meta.source === "a2a" ? "server" : "declared") : facts.trustedTools.has(tool.name) ? "exempted" : "default";
+    const pathTarget = face.pathTarget;
+    const rf = ruleFaceOfInstance(tool.parameters, face.ruleFace, pathTarget);
+    const hints = face.renderHints !== undefined ? capRenderHints(face.renderHints) : undefined;
+    return {
+        name: tool.name,
+        aliases: [...new Set(tool.aliases ?? [])],
+        source: meta.source,
+        ...(meta.origin !== undefined ? { origin: { peer: meta.origin.peer, ...(meta.origin.declaredBy !== undefined ? { declaredBy: meta.origin.declaredBy } : {}) } } : {}),
+        contract: { contractId: d.contractId.slice(0, 64), implementationRevision: d.implementationRevision.slice(0, 64) },
+        shapeDigest: d.shapeDigest,
+        wireSchemaDigest: d.wireSchemaDigest,
+        cardId: cardId.slice(0, 160),
+        capabilityId: mintCapabilityId({ source: meta.source, peer, name: tool.name, contractId: d.contractId }),
+        inputKeys,
+        effect,
+        effectProvenance,
+        offload: face.offload !== false,
+        ...(typeof face.offloadThresholdChars === "number" && Number.isFinite(face.offloadThresholdChars) && face.offloadThresholdChars >= 0 ? { offloadThresholdChars: Math.floor(face.offloadThresholdChars) } : {}),
+        compactable: face.compactable === true,
+        budgetExempt: face.budgetExempt === true,
+        egress,
+        egressProvenance,
+        ...(irreversibility !== undefined ? { irreversibility } : {}),
+        reversibilityProbe,
+        contentOrigin,
+        contentOriginProvenance,
+        family: face.family !== undefined && TOOL_FAMILIES.includes(face.family) ? face.family : "other",
+        ...(pathTarget !== undefined
+            ? { pathTarget: { param: pathTarget.param, aliases: [...(pathTarget.aliases ?? [])], access: pathTarget.access, skillScopeEligible: pathTarget.skillScopeEligible === true } }
+            : {}),
+        ruleFace: rf,
+        approvalPreview: typeof tool.approvalPreview === "function",
+        validateInput: typeof tool.validateInput === "function",
+        deferred: facts.deferred.has(tool.name),
+        alwaysLoad: face.alwaysLoad === true || face.mcpAlwaysLoad === true,
+        ...(typeof face.modelGate === "string" ? { modelGate: face.modelGate.slice(0, 64) } : {}),
+        ...(hints !== undefined ? { renderHints: hints } : {}),
+        mountedBy: meta.mountedBy,
+    };
+}
+export class ToolRosterDeltaSeat {
+    #current;
+    #snapshot;
+    #pending = [];
+    #sink;
+    arm(current, snapshot) {
+        this.#current = current;
+        this.#snapshot = snapshot;
+    }
+    get current() {
+        return this.#current;
+    }
+    republish() {
+        if (this.#current === undefined || this.#snapshot === undefined)
+            return undefined;
+        const next = this.#snapshot();
+        const delta = diffToolRoster(this.#current, next);
+        this.#current = next;
+        if (this.#sink !== undefined)
+            this.#sink(delta);
+        else {
+            this.#pending.push(delta);
+            if (this.#pending.length > 64)
+                this.#pending.shift();
+        }
+        return delta;
+    }
+    subscribe(sink) {
+        this.#sink = sink;
+        const pending = this.#pending;
+        this.#pending = [];
+        for (const d of pending)
+            sink(d);
+    }
+    drain() {
+        const pending = this.#pending;
+        this.#pending = [];
+        return pending;
+    }
+}
+export function ruleFacesFromRoster(roster) {
+    const byName = new Map(roster.entries.map((e) => [e.name, e]));
+    for (const e of roster.entries)
+        for (const a of e.aliases)
+            if (!byName.has(a))
+                byName.set(a, e);
+    return (toolName) => {
+        const e = byName.get(toolName);
+        if (e === undefined)
+            return undefined;
+        const params = new Set(e.ruleFace.params);
+        return {
+            primaryParams: e.ruleFace.primaryParams,
+            params: e.ruleFace.params,
+            nonScalar: e.inputKeys.filter((k) => !params.has(k.name) && (k.type === "object" || k.type === "array")).map((k) => k.name),
+            pathTargeting: e.pathTarget !== undefined,
+        };
+    };
+}
+export function diffToolRoster(prev, next) {
+    const before = new Map(prev.entries.map((e) => [e.name, canonical(e)]));
+    const after = new Map(next.entries.map((e) => [e.name, canonical(e)]));
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [name, row] of after) {
+        const old = before.get(name);
+        if (old === undefined)
+            added.push(name);
+        else if (old !== row)
+            changed.push(name);
+    }
+    for (const name of before.keys())
+        if (!after.has(name))
+            removed.push(name);
+    return { fromDigest: prev.digest, roster: next, summary: { added, removed, changed } };
+}
+export function judgeParkedToolIdentity(pending, row) {
+    const carried = pending.capabilityId !== undefined || pending.contractId !== undefined || pending.shapeDigest !== undefined || pending.implementationRevision !== undefined;
+    if (row === undefined)
+        return "absent";
+    if (!carried)
+        return "name_only";
+    const id = toolIdentityOf(row);
+    return pending.capabilityId === id.capabilityId && pending.contractId === id.contractId && pending.shapeDigest === id.shapeDigest && pending.implementationRevision === id.implementationRevision ? "match" : "mismatch";
+}
+export function offendingResultCard(hints, cardId, engineCards) {
+    for (const c of hints?.resultCards ?? []) {
+        if (typeof c !== "string")
+            continue;
+        if (c.startsWith(`${cardId}/`))
+            continue;
+        if (c.startsWith("builtin:") || engineCards.has(c) || !c.includes("/"))
+            return c;
+        return c;
+    }
+    return undefined;
+}

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

@@ -14,6 +14,7 @@ import type { AgentDefinition } from "./agent-definition.js";
 import type { TaskEvent } from "./task-event.js";
 import type { TaskSpec } from "./task-spec.js";
 import type { BackgroundChildEvent } from "./delegation-frames.js";
+import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /**
  * Side-effect class of a tool. Used by wake/resume reconciliation: when a call was interrupted
  * before its result was recorded, the outcome is unknown, so core must decide whether re-doing it
@@ -403,9 +404,10 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * (`config.tool_model_gate_unknown_class`). Restore channels: explicit composition (no tag),
      * {@link TaskSpec.restoreGatedTools}, env `SEMA_TOOL_MODEL_GATE=off`,
      * `RunnerDeps.toolModelGate: false`; {@link TaskSpec.excludeTools} always wins regardless.
-     * The materialized `AgentTool` face does NOT carry this field (`defineTool` is a whitelist
-     * constructor) — the decision completes on the ToolSpec face inside `prepareConfigDoors`,
-     * before any conversion.
+     * The gate DECISION completes on the ToolSpec face inside `prepareConfigDoors`, before any
+     * conversion; `defineTool` then forwards the class onto the materialized face (design/388: the
+     * effect roster reports `modelGate` on a row that survived the gate, so an operator can read which
+     * class a mounted scaffold belongs to — the forwarded value is a read face, never a second gate).
      */
     modelGate?: string;
     /**
@@ -421,6 +423,55 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
         /** Declared behavior revision — bump when execute-visible behavior changes. */
         implementationRevision: string;
     };
+    /**
+     * design/388 §2.2 ① — the DISPLAY / DISPATCH family of this tool (closed set {@link TOOL_FAMILIES}).
+     * Input to grouping, card pre-selection and the rule editor's completion — never an authorization
+     * source: no gate reads it. Absent on a caller/MCP tool ⇒ the roster reports `"other"`; every
+     * built-in definition in the static catalog declares one (the catalog completeness gate reds a
+     * missing declaration rather than defaulting it).
+     */
+    family?: ToolFamily;
+    /**
+     * design/388 §2.2 ② — the parameter that names this tool's filesystem TARGET and how it is touched.
+     * Present ⇔ the tool can be confirmed BY PATH: write confinement (`allowDirs`, the fs-write gate,
+     * the sensitive-path guard, frozen-path denies), edited-file tracking and the transcript-directory
+     * gate all read it off the call's face instead of a name table. ABSENT ⇒ the tool is handled as a
+     * write whose target cannot be confirmed (fail-closed under every path-confining face) — exactly how
+     * a tool outside the retired name tables was handled. `param` outranks `aliases` (NotebookEdit's
+     * `notebook_path` beats a decoy `file_path`). `skillScopeEligible` is a SEPARATE grant: only a tool
+     * that sets it enters the active-skill `allowPaths` face (Write/Edit do; NotebookEdit deliberately
+     * does not; a caller tool that merely takes a built-in's NAME inherits nothing).
+     */
+    pathTarget?: ToolPathTarget;
+    /**
+     * design/388 §2.2 ③ — the parameter vocabulary a permission rule (`Tool(param:pattern)`) may name.
+     * DERIVED from the schema when absent (the scalar top-level parameters plus the path target's
+     * aliases; object/array parameters never enter — a rule on them can never match). A declaration can
+     * only NARROW the derived set. A tool whose `prepareArguments` renames keys must declare its face
+     * explicitly (the schema keys are not what a call carries).
+     */
+    ruleFace?: ToolRuleFace;
+    /**
+     * design/388 §2.2 ④ — declarative render hints for a shell that has no local implementation of
+     * this tool (an MCP / caller / external tool). Every string is UNTRUSTED display input: the
+     * roster caps lengths, the shell strips control and bidi characters. `approvalCard` is a
+     * pre-filter, never a compatibility proof — the shell validates the call's args against its own
+     * card schema before mounting a specialised card. `resultCards` may only name this tool's own
+     * `cardId` namespace; a declaration naming an engine card (`builtin:*`, `mcp`) is refused at prepare.
+     */
+    renderHints?: ToolRenderHints;
+    /**
+     * design/388 §2.2 ⑤ — this tool's results are CLEARABLE by the context-edit micro-compaction
+     * (the CC `microCompact` whitelist, previously the name table `COMPACTABLE_TOOLS`). Default
+     * false: an undeclared tool's results survive to the harder defenses.
+     */
+    compactable?: true;
+    /**
+     * design/388 §2.2 ⑤ — this tool's results are EXEMPT from the per-batch aggregate result budget
+     * because they are self-bounded (Read pages at its own cap; the offload reader pages small
+     * slices). Default false: every undeclared tool counts against the budget.
+     */
+    budgetExempt?: true;
     /**
      * Execute the tool. Return a string (becomes text content) or a structured result.
      * Throw to signal failure (the loop encodes it as an error tool result).

package/dist/core/tools.js

@@ -54,6 +54,13 @@ export function defineTool(spec, options) {
         ...(spec.defer !== undefined ? { defer: spec.defer } : {}),
         ...(spec.alwaysLoad !== undefined ? { alwaysLoad: spec.alwaysLoad } : {}),
         ...(spec.prepareArguments ? { prepareArguments: spec.prepareArguments } : {}),
+        ...(spec.family !== undefined ? { family: spec.family } : {}),
+        ...(spec.pathTarget !== undefined ? { pathTarget: spec.pathTarget } : {}),
+        ...(spec.ruleFace !== undefined ? { ruleFace: spec.ruleFace } : {}),
+        ...(spec.renderHints !== undefined ? { renderHints: spec.renderHints } : {}),
+        ...(spec.compactable === true ? { compactable: true } : {}),
+        ...(spec.budgetExempt === true ? { budgetExempt: true } : {}),
+        ...(spec.modelGate !== undefined ? { modelGate: spec.modelGate } : {}),
         ...(spec.approvalPreview ? { approvalPreview: spec.approvalPreview } : {}),
         ...(spec.validateInput ? { validateInput: spec.validateInput } : {}),
         execute: async (toolCallId, rawParams, signal) => {

package/dist/core/wiring-manifest.d.ts

@@ -262,6 +262,17 @@ export interface WiringManifest {
      * assembly, and legs of one assembly must fingerprint alike whether or not a server was up.
      */
     mcp?: readonly WiringManifestMcpEntry[];
+    /**
+     * design/388 §2.5 — EFFECTIVE half only, and ALWAYS present on an engine-minted effective manifest:
+     * the leg's TOOL ROSTER — one row per mounted instance in wire order, every declared axis, the
+     * engine-minted identity (`capabilityId`), the schema-derived `inputKeys` / rule vocabulary and the
+     * roster `digest`. The static half has no roster to report (it mounts nothing). NOT part of
+     * {@link configFingerprint}: a roster is per-leg by construction (a child leg mounts a different set
+     * under the same assembly), so hashing it would break the cross-leg equality the fingerprint
+     * advertises — the roster carries its own digest for that. A run-time change to the set arrives as a
+     * `tool_roster_delta` event, never as a re-emitted manifest.
+     */
+    tools?: import("./tool-roster.js").ToolRoster;
     /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
      *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
      *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
@@ -333,6 +344,8 @@ export interface WiringFacts {
     /** Effective half only — see {@link WiringManifest.mcp}; the static half materializes nothing.
      *  Copied entry-wise onto the manifest (the caller's array is never aliased). */
     mcp?: readonly WiringManifestMcpEntry[];
+    /** Effective half only — the leg's minted tool roster (see {@link WiringManifest.tools}). */
+    tools?: import("./tool-roster.js").ToolRoster;
 }
 /** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
  *  single-source shapes, no parallel hand-copied interface). */

package/dist/core/wiring-manifest.js

@@ -127,9 +127,10 @@ export function deriveWiringManifest(facts) {
         ...(facts.half === "effective" && facts.modelGate !== undefined ? { modelGate: { class: facts.modelGate.class, removed: [...facts.modelGate.removed], restore: facts.modelGate.restore } } : {}),
         ...(facts.half === "effective" && facts.autoMode !== undefined ? { autoMode: readAutoModeFact(facts.autoMode) } : {}),
         ...(facts.half === "effective" && facts.mcp !== undefined ? { mcp: facts.mcp.map((e) => ({ ...e })) } : {}),
+        ...(facts.half === "effective" && facts.tools !== undefined ? { tools: facts.tools } : {}),
     };
     if (facts.half === "effective") {
-        const { leg: _leg, mcp: _mcp, ...assembly } = manifest;
+        const { leg: _leg, mcp: _mcp, tools: _tools, ...assembly } = manifest;
         const { provenance: _askSeat, ...askForHash } = assembly.ask;
         const { provenance: _questionSeat, ...questionForHash } = assembly.question;
         manifest.configFingerprint = createHash("sha256")

package/dist/core/write-protect.d.ts

@@ -1,3 +1,4 @@
+import { type ToolCallLike } from "./tool-registry.js";
 /**
  * How one table row matches the judged path:
  *  · `"basename"`     — the target's last segment equals the row name (CC `DANGEROUS_FILES` form);
@@ -81,4 +82,4 @@ export declare function compileWriteProtection(entries?: readonly WriteProtected
  */
 export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[], opts?: {
     dataRoot?: string;
-}): ((toolName: string, args: unknown) => WriteProtectedHit | null) | undefined;
+}): ((toolName: string, args: unknown, face?: ToolCallLike["face"]) => WriteProtectedHit | null) | undefined;

package/dist/core/write-protect.js

@@ -1,5 +1,5 @@
 import { isWinFormPath, writeTargetPath, isUncPath } from "../tools/fs/safety.js";
-import { PATH_CONFINABLE_WRITE_TOOLS } from "./runner/session-rule-policy.js";
+import { isProtectedWrite } from "./tool-registry.js";
 import { dataRootSpellings } from "./sensitive-path-policy.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
@@ -213,10 +213,11 @@ export function createWriteProtectionCheck(entries, opts) {
     const matcher = compileWriteProtection(entries, opts);
     if (matcher === undefined)
         return undefined;
-    return (toolName, args) => {
-        if (!PATH_CONFINABLE_WRITE_TOOLS.has(toolName))
+    return (toolName, args, face) => {
+        const call = { toolName, args, ...(face !== undefined ? { face } : {}) };
+        if (!isProtectedWrite(call))
             return null;
-        const path = writeTargetPath(toolName, args);
+        const path = writeTargetPath(call);
         if (typeof path !== "string" || path.length === 0)
             return null;
         return matcher.matchPath(path);