@jini-ai/core 0.4.1 → 0.4.3

package/dist/surface-exchanges.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Shared surface-exchange ABI. The daemon owns the store and ask/report implementation;
+ * consumers inject those ports without depending on the daemon runtime.
+ */
+import type { SurfaceEmission, SurfaceEmitter } from './tool-registry.js';
+/**
+ * The callback param carrying an exchange id from a rendered surface back to the server.
+ *
+ * Double-underscored to keep it clear of a surface's real fields, and named in one place because
+ * three parties must agree on it: whatever builds the surface, the route that routes on it, and the
+ * handler that opened the exchange.
+ *
+ * This is MCP-UI's carrier specifically, because an mcp-ui surface can only answer by issuing a tool
+ * call, so its correlation has to ride inside that call's params. A channel that can name the
+ * exchange directly should do so — `mcp-ui-tool-calls-route.ts` also accepts a top-level
+ * `exchangeId`, and A2UI/`surface_request` correlate by their own `surfaceId`.
+ */
+export declare const SURFACE_EXCHANGE_ID_PARAM = "__exchangeId";
+/**
+ * The callback param a surface's Cancel action sets, so a dismissal resolves the exchange
+ * immediately instead of stranding the agent until the idle deadline.
+ *
+ * Carried as data rather than as a distinct {@link SurfaceMessage} status: "the human answered, and
+ * the answer was no" is genuinely an answer, and only the tool that built the surface knows what a
+ * dismissal means for its own result.
+ */
+export declare const SURFACE_DISMISSED_PARAM = "__dismissed";
+/**
+ * The callback param carrying free text a human TYPED — into the chat composer — as their answer to
+ * an outstanding surface, rather than clicking the rendered form.
+ *
+ * ## The deadlock this exists to break
+ *
+ * A held-open exchange can only be resolved by a message that names it, and until now every param
+ * shape a surface posts back was one the FORM produced. A human who reads the question, ignores the
+ * dialog and types the answer into the composer therefore resolved nothing: their message was queued
+ * behind the very run it was meant to unblock, and the agent sat parked until the idle deadline
+ * fired minutes later.
+ *
+ * ## Why it is a separate param rather than the tool's own answer fields
+ *
+ * Prose is not a selection. A tool whose answer fields are option VALUES the model itself supplied
+ * (`assistant_ask_choice`'s `choice`/`selections`) would, if prose were poured into them, report to
+ * the model that the administrator picked an option that was never offered. Carrying typed text
+ * under its own name is what forces each tool to decide, explicitly, what a typed answer means for
+ * its own result — and lets a tool that has no safe reading of one simply ignore it.
+ *
+ * ## What it deliberately cannot do
+ *
+ * It cannot confirm anything. `classifyConfirmationAnswer` reads only a literal `decision:
+ * "confirm"`, so a typed answer arriving at a confirmation-shaped exchange fails closed to
+ * `"declined"` with no code change and no exception — which is the correct reading of "the human
+ * wrote a sentence instead of clicking Confirm". Nothing here should ever grow a prose-to-consent
+ * mapping.
+ *
+ * Double-underscored, and named here rather than at a tool, for the same reason as
+ * {@link SURFACE_EXCHANGE_ID_PARAM}: several parties must agree on the spelling.
+ */
+export declare const SURFACE_TYPED_ANSWER_PARAM = "__typedAnswer";
+/**
+ * Which inbound route may answer an exchange. `"mcp-ui"` (the host's default) is a tool-call-shaped answer
+ * posted to the MCP-UI route; `"a2ui"` is a renderer message posted to the A2UI route. A2UI posts
+ * carry no `toolId`, so without this an A2UI message could land in, and cancel, a pending MCP-UI
+ * confirmation of the same principal.
+ */
+export type SurfaceAnswerChannel = string;
+/** Who an exchange belongs to. Checked on every delivery; a mismatch is a rejection, not a warning. */
+export interface SurfaceExchangeBinding {
+    /** The tool that opened it. A message for one tool cannot resolve another's exchange. */
+    readonly toolId: string;
+    /** The principal whose run opened it: one human's answer must not land in another's call. */
+    readonly principalId: string;
+    /** The route allowed to answer it; omission uses the store's injected default channel. */
+    readonly channel?: SurfaceAnswerChannel;
+}
+/**
+ * One inbound message, or the reason there will not be one.
+ *
+ * The non-`received` cases are part of the contract rather than error handling (ADR-055 Decision 6):
+ * blocking moves the timeout story, it does not remove it, and a handler must be able to tell the
+ * model something true about which happened.
+ */
+export type SurfaceMessage = {
+    status: 'received';
+    params: Record<string, unknown>;
+} | {
+    status: 'expired';
+} | {
+    status: 'abandoned';
+};
+/** Why a delivery did not reach an exchange. Reported to the browser, never to the model. */
+export type SurfaceDeliveryRejectionReason = 'unknown-or-closed' | 'binding-mismatch';
+export type DeliverResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: SurfaceDeliveryRejectionReason;
+};
+/** A live, two-way conversation bound to one in-flight tool call. */
+export interface SurfaceExchange {
+    /** Correlation handle embedded in the human's answer carrier; not a secret. */
+    readonly id: string;
+    /**
+     * Sends one message out to the human.
+     *
+     * @throws {Error} If the exchange has already ended — the same posture the daemon's emitter takes,
+     * because a message sent onto a settled call has no way to be answered.
+     */
+    send(args: {
+        emission: SurfaceEmission;
+    }, optional?: Record<string, never>): Promise<void>;
+    /**
+     * Waits for the next inbound message.
+     *
+     * Returns a buffered one immediately if the human answered while the handler was busy. Once the
+     * exchange has ended, returns that terminal status rather than hanging — so a handler looping on
+     * `receive()` terminates instead of waiting out the transport.
+     */
+    receive(_args: Record<string, never>, optional?: Record<string, never>): Promise<SurfaceMessage>;
+    /** Ends the exchange idempotently. Pending receives resolve "abandoned"; an ended exchange is unchanged. */
+    close(_args: Record<string, never>, optional?: Record<string, never>): void;
+    /**
+     * When the exchange expires if nothing more happens, in epoch ms: the earlier of the idle and
+     * lifetime deadlines. Activity moves the idle one, so read it right before rendering a deadline
+     * for the human; a card drawn just before its `send()` shows a deadline a few ms early, never late.
+     */
+    expiresAtMs(): number;
+}
+/** Messaging helpers do not require deadline tracking. Hosts may supply a conversation port
+ * without a deadline; the daemon store always returns the full, dated SurfaceExchange. */
+export type SurfaceExchangeConversation = Omit<SurfaceExchange, 'expiresAtMs'> & Partial<Pick<SurfaceExchange, 'expiresAtMs'>>;
+/**
+ * What a delivery must prove about itself. `principalId` is load-bearing for every channel — one
+ * human's answer must never land in another's call. `toolId` is load-bearing only for a channel
+ * whose correlation carrier is itself a tool call: MCP-UI's surface can only answer by issuing one,
+ * so it always has a real tool name to offer, and the store checks it.
+ *
+ * A channel that correlates directly by its own id — A2UI's `surfaceId`, the run protocol's own
+ * `surface_request`/`surface_response` — has no natural `toolId` to supply; the browser never
+ * learns which tool opened the exchange, only its id. Requiring one anyway would force such a
+ * channel to either lie (send a placeholder that means nothing) or grow a lookup this store does
+ * not expose. So `toolId` is optional here: when a caller supplies it, it must still match exactly
+ * (MCP-UI's behavior is unchanged, byte for byte); when omitted, only `principalId` and the
+ * exchange's own unguessable `randomUUID()` id gate the delivery. That pair is still sufficient —
+ * the id is not enumerable, and `principalId` is a server-verified session identity, never a value
+ * the browser chooses (see `run-ownership.ts`) — so relaxing the caller's OBLIGATION does not
+ * relax the exchange's own binding, which `open()` still records honestly as whatever tool actually
+ * opened it.
+ */
+export interface SurfaceDeliverySpec {
+    exchangeId: string;
+    params: Record<string, unknown>;
+    principalId: string;
+    toolId?: string;
+    channel?: SurfaceAnswerChannel;
+}
+export interface SurfaceExchangeStore {
+    /**
+     * Opens an exchange bound to one in-flight tool call.
+     *
+     * @param args.emit - The call's live {@link SurfaceEmitter}. Required, not optional: an exchange whose
+     * messages cannot reach anybody is a guaranteed deadlock, and taking the emitter here is what makes
+     * that state unrepresentable rather than merely discouraged.
+     */
+    open(args: {
+        binding: SurfaceExchangeBinding;
+        emit: SurfaceEmitter;
+    }, optional?: Record<string, never>): SurfaceExchange;
+    /**
+     * Routes one inbound message to the exchange it names, queueing it if nothing is waiting yet.
+     * See {@link SurfaceDeliverySpec} for why `toolId` is optional rather than part of
+     * {@link SurfaceExchangeBinding} here.
+     */
+    deliver(requiredArgs: Pick<SurfaceDeliverySpec, 'exchangeId' | 'params' | 'principalId'>, optionalArgs?: Pick<SurfaceDeliverySpec, 'toolId' | 'channel'>): DeliverResult;
+    /**
+     * Resolves which open exchange a TYPED answer is for, when the human named none.
+     *
+     * A person typing into the chat composer does not know exchanges exist, so they cannot carry a
+     * {@link SURFACE_EXCHANGE_ID_PARAM} the way a rendered form does. This store is the only thing
+     * that knows what is open, so the correlation is recovered here rather than guessed by a client
+     * scraping an id out of the surface's own (model-influenced) HTML.
+     *
+     * Scoped by `toolId` as well as `principalId` on purpose: it is an OPT-IN, not a broadcast. Only
+     * a tool that has a safe reading of prose should ever be named here, which is what keeps typed
+     * text away from confirmation-shaped exchanges (see {@link SURFACE_TYPED_ANSWER_PARAM}).
+     *
+     * @returns The single matching open exchange's id, or `undefined` when there is none — or more
+     * than one. Ambiguity fails closed: delivering to the wrong one would silently answer a question
+     * the human was not looking at, and report their words as an answer to it.
+     * @complexity O(n) in the number of open exchanges, which is bounded by concurrent agent runs.
+     */
+    findTypedAnswerTarget(args: {
+        principalId: string;
+        toolId: string;
+    }, optional?: Record<string, never>): string | undefined;
+    /** Open, unsettled count — for tests and diagnostics only. */
+    size(): number;
+}
+/** Send a form, handle its answer, report the outcome, and finally close the exchange.
+ * Supply `askThenReport` from `@jini-ai/daemon/surface-exchanges` at the host boundary. */
+export type SurfaceAskThenReport = <Result>(args: {
+    exchange: SurfaceExchangeConversation;
+    confirmationEmission: SurfaceEmission;
+    handle: (answer: SurfaceMessage) => Promise<{
+        result: Result;
+        outcome?: SurfaceEmission;
+    }>;
+}, optional?: Record<string, never>) => Promise<Result>;
+//# sourceMappingURL=surface-exchanges.d.ts.map

package/dist/surface-exchanges.js

@@ -0,0 +1,55 @@
+/**
+ * The callback param carrying an exchange id from a rendered surface back to the server.
+ *
+ * Double-underscored to keep it clear of a surface's real fields, and named in one place because
+ * three parties must agree on it: whatever builds the surface, the route that routes on it, and the
+ * handler that opened the exchange.
+ *
+ * This is MCP-UI's carrier specifically, because an mcp-ui surface can only answer by issuing a tool
+ * call, so its correlation has to ride inside that call's params. A channel that can name the
+ * exchange directly should do so — `mcp-ui-tool-calls-route.ts` also accepts a top-level
+ * `exchangeId`, and A2UI/`surface_request` correlate by their own `surfaceId`.
+ */
+export const SURFACE_EXCHANGE_ID_PARAM = '__exchangeId';
+/**
+ * The callback param a surface's Cancel action sets, so a dismissal resolves the exchange
+ * immediately instead of stranding the agent until the idle deadline.
+ *
+ * Carried as data rather than as a distinct {@link SurfaceMessage} status: "the human answered, and
+ * the answer was no" is genuinely an answer, and only the tool that built the surface knows what a
+ * dismissal means for its own result.
+ */
+export const SURFACE_DISMISSED_PARAM = '__dismissed';
+/**
+ * The callback param carrying free text a human TYPED — into the chat composer — as their answer to
+ * an outstanding surface, rather than clicking the rendered form.
+ *
+ * ## The deadlock this exists to break
+ *
+ * A held-open exchange can only be resolved by a message that names it, and until now every param
+ * shape a surface posts back was one the FORM produced. A human who reads the question, ignores the
+ * dialog and types the answer into the composer therefore resolved nothing: their message was queued
+ * behind the very run it was meant to unblock, and the agent sat parked until the idle deadline
+ * fired minutes later.
+ *
+ * ## Why it is a separate param rather than the tool's own answer fields
+ *
+ * Prose is not a selection. A tool whose answer fields are option VALUES the model itself supplied
+ * (`assistant_ask_choice`'s `choice`/`selections`) would, if prose were poured into them, report to
+ * the model that the administrator picked an option that was never offered. Carrying typed text
+ * under its own name is what forces each tool to decide, explicitly, what a typed answer means for
+ * its own result — and lets a tool that has no safe reading of one simply ignore it.
+ *
+ * ## What it deliberately cannot do
+ *
+ * It cannot confirm anything. `classifyConfirmationAnswer` reads only a literal `decision:
+ * "confirm"`, so a typed answer arriving at a confirmation-shaped exchange fails closed to
+ * `"declined"` with no code change and no exception — which is the correct reading of "the human
+ * wrote a sentence instead of clicking Confirm". Nothing here should ever grow a prose-to-consent
+ * mapping.
+ *
+ * Double-underscored, and named here rather than at a tool, for the same reason as
+ * {@link SURFACE_EXCHANGE_ID_PARAM}: several parties must agree on the spelling.
+ */
+export const SURFACE_TYPED_ANSWER_PARAM = '__typedAnswer';
+//# sourceMappingURL=surface-exchanges.js.map

package/dist/text/escape.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file The one HTML/XML text escaper. A leaf module with NO imports, on purpose: the old copies
+ * lived inside `render.ts`, `form-render.ts` and `static-render.ts` and were duplicated rather than
+ * shared because importing them would have closed a runtime import cycle. A module that imports
+ * nothing can be imported from anywhere.
+ *
+ * `&` is replaced first: it is the escape character for every entity after it, so replacing any
+ * other character first would double-escape the `&` that replacement introduced. The apostrophe
+ * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
+ */
+/** Escapes `& < > " '` for HTML text or a quoted attribute value. @complexity O(text length). */
+export declare function escapeHtml({ text }: {
+    text: string;
+}, _optional?: {}): string;
+/** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
+ *  @complexity O(text length). */
+export declare function escapeXml({ text }: {
+    text: string;
+}, _optional?: {}): string;
+//# sourceMappingURL=escape.d.ts.map

package/dist/text/escape.js

@@ -0,0 +1,23 @@
+/**
+ * @file The one HTML/XML text escaper. A leaf module with NO imports, on purpose: the old copies
+ * lived inside `render.ts`, `form-render.ts` and `static-render.ts` and were duplicated rather than
+ * shared because importing them would have closed a runtime import cycle. A module that imports
+ * nothing can be imported from anywhere.
+ *
+ * `&` is replaced first: it is the escape character for every entity after it, so replacing any
+ * other character first would double-escape the `&` that replacement introduced. The apostrophe
+ * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
+ */
+const HTML_ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+const XML_ENTITIES = { ...HTML_ENTITIES, "'": "&apos;" };
+const SPECIAL = /[&<>"']/g;
+/** Escapes `& < > " '` for HTML text or a quoted attribute value. @complexity O(text length). */
+export function escapeHtml({ text }, _optional = {}) {
+    return text.replace(SPECIAL, (char) => HTML_ENTITIES[char] ?? char);
+}
+/** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
+ *  @complexity O(text length). */
+export function escapeXml({ text }, _optional = {}) {
+    return text.replace(SPECIAL, (char) => XML_ENTITIES[char] ?? char);
+}
+//# sourceMappingURL=escape.js.map

package/dist/text/index.d.ts

@@ -1,3 +1,4 @@
 export { sanitizeUntrustedText, stripControlSequences } from './sanitize-untrusted-text.js';
 export type { SanitizeTextOptions } from './sanitize-untrusted-text.js';
+export { escapeHtml, escapeXml } from "./escape.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/text/index.js

@@ -1,2 +1,3 @@
 export { sanitizeUntrustedText, stripControlSequences } from './sanitize-untrusted-text.js';
+export { escapeHtml, escapeXml } from "./escape.js";
 //# sourceMappingURL=index.js.map

package/dist/tool-metadata.d.ts

@@ -0,0 +1,71 @@
+/** Domain registrations own these declarations; projections never infer risk or authorization. */
+export interface ToolApprovalMetadata {
+    readonly class: 'read' | 'edit' | 'trash' | 'delete' | 'restore-over-existing' | 'publish' | 'replace-secret' | 'escalation';
+    readonly confirmation: 'direct' | 'policy' | 'plan';
+    readonly input?: 'human-form';
+    /** Host-owned input classification rule, separate from the declared side effects. */
+    readonly rule?: string;
+}
+export interface ToolMetadata<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
+    readonly search?: {
+        readonly keywords?: string;
+        readonly queries?: readonly string[];
+    };
+    readonly approval?: A;
+    readonly mcpUi?: {
+        readonly redeemable?: boolean;
+        readonly exchangeOnly?: boolean;
+        readonly secretField?: {
+            readonly secret: true;
+        };
+    };
+}
+export type ToolMetadataById<A extends ToolApprovalMetadata = ToolApprovalMetadata> = Readonly<Record<string, ToolMetadata<A>>>;
+/** Own-property lookup: inherited object keys can never declare a tool's approval or callback access. */
+export declare function toolMetadataFor({ toolId, metadata }: {
+    toolId: string;
+    metadata: ToolMetadataById | undefined;
+}, _optional?: Record<string, never>): ToolMetadata | undefined;
+/**
+ * Bind host-owned metadata to registrations returned by a reusable domain package. Existing
+ * catalog metadata wins; handlers, authorization and independently validated risk are preserved.
+ * @returns New registrations for declared ids; undeclared registrations retain their identity.
+ * @complexity O(t) time and space in registrations.
+ * @example withToolMetadata({ registrations, metadata: notesMetadata });
+ */
+export declare function withToolMetadata({ registrations, metadata }: {
+    registrations: readonly import('./tool-registry.js').ToolRegistration[];
+    metadata: ToolMetadataById;
+}, _optional?: Record<string, never>): import('./tool-registry.js').ToolRegistration[];
+/** Immutable domain declarations projected for discovery and human callback gates. */
+export interface ToolMetadataProjections<A extends ToolApprovalMetadata = ToolApprovalMetadata> {
+    readonly byId: ToolMetadataById<A>;
+    readonly keywords: Readonly<Record<string, string>>;
+    readonly queries: Readonly<Record<string, readonly string[]>>;
+    readonly approvals: Readonly<Record<string, A>>;
+    readonly policyConfirmationIds: ReadonlySet<string>;
+    readonly secretFormIds: ReadonlySet<string>;
+    readonly secretForms: Readonly<Record<string, {
+        readonly secretField: {
+            readonly secret: true;
+        };
+    }>>;
+    readonly redeemableIds: ReadonlySet<string>;
+    readonly exchangeOnlyIds: ReadonlySet<string>;
+}
+/**
+ * Generate projections from the same metadata domain registration consumes. Duplicate ownership
+ * fails before any projection is returned. No handler, risk classification or permission is inferred.
+ * @param required.domains Domain names and their independently authored declarations.
+ * @returns Fresh maps and sets; inputs are never mutated.
+ * @throws Error naming both domains claiming the same id.
+ * @complexity O(t) time and space in declared tools, performed at composition time.
+ * @example projectToolMetadata({ domains: [{ domain: 'notes', tools: notesMetadata }] });
+ */
+export declare function projectToolMetadata<A extends ToolApprovalMetadata>({ domains }: {
+    domains: readonly {
+        readonly domain: string;
+        readonly tools: ToolMetadataById<A>;
+    }[];
+}, _optional?: Record<string, never>): ToolMetadataProjections<A>;
+//# sourceMappingURL=tool-metadata.d.ts.map

package/dist/tool-metadata.js

@@ -0,0 +1,56 @@
+/** Own-property lookup: inherited object keys can never declare a tool's approval or callback access. */
+export function toolMetadataFor({ toolId, metadata }, _optional = {}) {
+    return metadata && Object.hasOwn(metadata, toolId) ? metadata[toolId] : undefined;
+}
+/**
+ * Bind host-owned metadata to registrations returned by a reusable domain package. Existing
+ * catalog metadata wins; handlers, authorization and independently validated risk are preserved.
+ * @returns New registrations for declared ids; undeclared registrations retain their identity.
+ * @complexity O(t) time and space in registrations.
+ * @example withToolMetadata({ registrations, metadata: notesMetadata });
+ */
+export function withToolMetadata({ registrations, metadata }, _optional = {}) {
+    return registrations.map(registration => {
+        const declared = toolMetadataFor({ toolId: registration.descriptor.id, metadata });
+        if (!declared || registration.descriptor.metadata)
+            return registration;
+        return { ...registration, descriptor: { ...registration.descriptor, metadata: declared } };
+    });
+}
+/**
+ * Generate projections from the same metadata domain registration consumes. Duplicate ownership
+ * fails before any projection is returned. No handler, risk classification or permission is inferred.
+ * @param required.domains Domain names and their independently authored declarations.
+ * @returns Fresh maps and sets; inputs are never mutated.
+ * @throws Error naming both domains claiming the same id.
+ * @complexity O(t) time and space in declared tools, performed at composition time.
+ * @example projectToolMetadata({ domains: [{ domain: 'notes', tools: notesMetadata }] });
+ */
+export function projectToolMetadata({ domains }, _optional = {}) {
+    const byId = Object.create(null);
+    const owners = new Map();
+    for (const { domain, tools } of domains) {
+        for (const [id, metadata] of Object.entries(tools)) {
+            const owner = owners.get(id);
+            if (owner !== undefined)
+                throw new Error(`tool-metadata: '${id}' is declared by both ${owner} and ${domain}`);
+            owners.set(id, domain);
+            byId[id] = metadata;
+        }
+    }
+    const entries = Object.entries(byId);
+    const approvals = Object.fromEntries(entries.filter(([, metadata]) => metadata.approval !== undefined).map(([id, metadata]) => [id, metadata.approval]));
+    const policyConfirmationIds = new Set(Object.entries(approvals).filter(([, policy]) => policy.confirmation === 'policy' || policy.confirmation === 'plan' || !!policy.rule).map(([id]) => id));
+    const secretEntries = entries.filter(([, metadata]) => metadata.mcpUi?.secretField?.secret === true);
+    const secretFormIds = new Set(secretEntries.map(([id]) => id));
+    return {
+        byId,
+        keywords: Object.fromEntries(entries.filter(([, metadata]) => metadata.search?.keywords !== undefined).map(([id, metadata]) => [id, metadata.search.keywords])),
+        queries: Object.fromEntries(entries.filter(([, metadata]) => metadata.search?.queries !== undefined).map(([id, metadata]) => [id, metadata.search.queries])),
+        approvals, policyConfirmationIds, secretFormIds,
+        secretForms: Object.fromEntries(secretEntries.map(([id, metadata]) => [id, { secretField: metadata.mcpUi.secretField }])),
+        redeemableIds: new Set([...policyConfirmationIds, ...secretFormIds, ...entries.filter(([, metadata]) => metadata.mcpUi?.redeemable === true).map(([id]) => id)]),
+        exchangeOnlyIds: new Set([...policyConfirmationIds, ...secretFormIds, ...entries.filter(([, metadata]) => metadata.mcpUi?.exchangeOnly === true).map(([id]) => id)]),
+    };
+}
+//# sourceMappingURL=tool-metadata.js.map

package/dist/tool-permissions.d.ts

@@ -0,0 +1,76 @@
+/** Shared permission checking preserves the command/tool denial contract without loading a domain. */
+export interface AuthorizationRequired {
+    principalId: string;
+    permission: string;
+    workspaceId: string;
+}
+export interface AuthorizationOptional {
+    entityType?: string | undefined;
+    entityId?: string | undefined;
+}
+export type AuthorizationPort = (required: AuthorizationRequired, optional?: AuthorizationOptional) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export type LegacyToolAuthorizeFn = (required: AuthorizationRequired & AuthorizationOptional) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+/** Permission denial shared with the CMS command compatibility export.
+ * Keeps the original class name, message and permission/reason fields; no domain imports.
+ * @example new ForbiddenError({ message: "denied", permission: "settings.read", reason: "no_grant" }, {});
+ */
+export declare class ForbiddenError extends Error {
+    readonly permission: string;
+    readonly reason: string;
+    constructor({ message, permission, reason }: {
+        message: string;
+        permission: string;
+        reason: string;
+    }, _optional?: Record<string, never>);
+}
+export interface RequireToolPermissionRequired {
+    authorize: AuthorizationPort;
+    workspaceId: string;
+    principalId: string;
+    permission: string;
+}
+export interface RequireToolPermissionOptional {
+    entityType?: string | undefined;
+    entityId?: string | undefined;
+}
+/**
+ * Runs the identical inline `authorize()` check the corresponding admin HTTP route performs, for a
+ * tool whose own domain function carries no `authorize()` call to inherit.
+ *
+ * This is NOT a second evaluator alongside another check — that is exactly the single-evaluator
+ * rule's concern. For each tool that
+ * calls it, this IS the only gate that tool's execution ever reaches, reached by an identical path
+ * to the one a human clicking the same admin route reaches. Domains split cleanly on which kind
+ * they are: content-types/Forms/Identity mutations and every Widgets write-service call self-enforce
+ * inside the domain function and must NOT call this; Comments/Members/Newsletter/Media/Menus/
+ * Database/Recovery gate in the route instead, so their handlers call this in the route's place.
+ * Which kind a given tool is stays documented next to that tool's handler, not here.
+ *
+ * Throws `core/commands`'s `ForbiddenError` — the same class `executeCommand` itself throws — so a
+ * tool caller and a route caller see the identical error shape for an identical denial. Throw
+ * rather than a 403 body because the caller here is `ToolExecutor`, which reads a thrown error as a
+ * failed execution and has no response to write to.
+ *
+ * The defining command module re-exports this class: its barrel also exports mutation appliers
+ * that name content features. Pulling that barrel into shared permission wiring would couple
+ * every tool domain to those features; kernel ownership preserves the identical denial class
+ * without that dependency closure.
+ *
+ * @param required - The `authorize()` evaluator and the workspace the run is scoped to.
+ * @param optional - Entity scope for who is asking, for what permission, optionally against which entity.
+ * @throws {ForbiddenError} If `authorize()` denies.
+ * @complexity O(1) beyond the injected `authorize()` call.
+ * @overallScore 100
+ */
+export declare function requireToolPermission(required: RequireToolPermissionRequired, optional?: RequireToolPermissionOptional): Promise<void>;
+/** Adapt an existing evaluator without losing entity scope. @complexity O(1) plus evaluation. */
+export declare function adaptLegacyAuthorize(required: {
+    authorize: LegacyToolAuthorizeFn;
+}, _optional?: Record<string, never>): AuthorizationPort;
+//# sourceMappingURL=tool-permissions.d.ts.map

package/dist/tool-permissions.js

@@ -0,0 +1,57 @@
+/** Permission denial shared with the CMS command compatibility export.
+ * Keeps the original class name, message and permission/reason fields; no domain imports.
+ * @example new ForbiddenError({ message: "denied", permission: "settings.read", reason: "no_grant" }, {});
+ */
+export class ForbiddenError extends Error {
+    permission;
+    reason;
+    constructor({ message, permission, reason }, _optional = {}) {
+        super(message);
+        this.permission = permission;
+        this.reason = reason;
+    }
+}
+/**
+ * Runs the identical inline `authorize()` check the corresponding admin HTTP route performs, for a
+ * tool whose own domain function carries no `authorize()` call to inherit.
+ *
+ * This is NOT a second evaluator alongside another check — that is exactly the single-evaluator
+ * rule's concern. For each tool that
+ * calls it, this IS the only gate that tool's execution ever reaches, reached by an identical path
+ * to the one a human clicking the same admin route reaches. Domains split cleanly on which kind
+ * they are: content-types/Forms/Identity mutations and every Widgets write-service call self-enforce
+ * inside the domain function and must NOT call this; Comments/Members/Newsletter/Media/Menus/
+ * Database/Recovery gate in the route instead, so their handlers call this in the route's place.
+ * Which kind a given tool is stays documented next to that tool's handler, not here.
+ *
+ * Throws `core/commands`'s `ForbiddenError` — the same class `executeCommand` itself throws — so a
+ * tool caller and a route caller see the identical error shape for an identical denial. Throw
+ * rather than a 403 body because the caller here is `ToolExecutor`, which reads a thrown error as a
+ * failed execution and has no response to write to.
+ *
+ * The defining command module re-exports this class: its barrel also exports mutation appliers
+ * that name content features. Pulling that barrel into shared permission wiring would couple
+ * every tool domain to those features; kernel ownership preserves the identical denial class
+ * without that dependency closure.
+ *
+ * @param required - The `authorize()` evaluator and the workspace the run is scoped to.
+ * @param optional - Entity scope for who is asking, for what permission, optionally against which entity.
+ * @throws {ForbiddenError} If `authorize()` denies.
+ * @complexity O(1) beyond the injected `authorize()` call.
+ * @overallScore 100
+ */
+export async function requireToolPermission(required, optional = {}) {
+    const result = await required.authorize({
+        principalId: required.principalId, permission: required.permission, workspaceId: required.workspaceId,
+    }, optional);
+    if (!result.allowed)
+        throw new ForbiddenError({
+            message: `principal '${required.principalId}' is not authorized for '${required.permission}' (${result.reason})`,
+            permission: required.permission, reason: result.reason,
+        });
+}
+/** Adapt an existing evaluator without losing entity scope. @complexity O(1) plus evaluation. */
+export function adaptLegacyAuthorize(required, _optional = {}) {
+    return (request, optional = {}) => required.authorize({ ...request, ...optional });
+}
+//# sourceMappingURL=tool-permissions.js.map

package/dist/tool-registry.d.ts

@@ -4,7 +4,7 @@
  * `{descriptor, handler, policy}` triples; the registry's *public* surface
  * (this file's `ToolRegistry` interface, and everything re-exported from
  * this package's root `index.ts`) exposes only `ToolDescriptor`s —
- * `register`/`has`/`list`. It never exposes a way to retrieve a `handler`
+ * `register`/`has`/`list`. Revocable host scopes add replacement without retrieval. It never exposes a way to retrieve a `handler`
  * or `policy` back out.
  *
  * That's the load-bearing invariant this task is named after: "handlers
@@ -26,6 +26,7 @@
  * `archived provenance ledger` for the 2026-07-29 hardening note.
  */
 import type { Principal } from './principal.js';
+import type { ToolMetadata } from './tool-metadata.js';
 /** A structural run reference — anything with a stable `id` satisfies this (e.g. `@jini-ai/protocol`'s `RunStatus`). No import needed to satisfy it; see the module doc. */
 export interface RunRef {
     readonly id: string;
@@ -35,6 +36,8 @@ export interface RunRef {
  * handler or policy — those are only reachable via {@link authorizeToolInvocation}.
  */
 export interface ToolDescriptor {
+    /** Domain-owned discovery and approval metadata; grants no execution authority. */
+    readonly metadata?: ToolMetadata;
     readonly id: string;
     readonly description?: string;
     /**
@@ -196,6 +199,21 @@ export interface ToolRegistry {
     /** Descriptors only, in registration order. Never the underlying handlers/policies. */
     list(_required: Record<string, never>): readonly ToolDescriptor[];
 }
+/** A host can invalidate its disposable discovery snapshot without exposing handlers. */
+export declare function toolRegistryRevision(required: {
+    registry: object;
+}, _optional?: Record<string, never>): number | undefined;
+/** Revocable registration scope on the SAME registry the executor owns. Collision validation
+ * completes before mutation, so a failed replacement cannot lose the working generation.
+ * Only this closure may remove its own registrations; native and other scopes remain protected.
+ * Already-authorized closures are revoked too: confirmation can await a human across disable. */
+export declare function createToolRegistrationScope(required: {
+    registry: ToolRegistry;
+}, _optional?: Record<string, never>): {
+    replace({ registrations: next }: {
+        registrations: readonly ToolRegistration[];
+    }, _optional?: Record<string, never>): void;
+};
 /**
  * Creates an empty, append-only `ToolRegistry`.
  *