@jini-ai/core 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @jini-ai/core
 
+## 0.4.2 — pending release
+
+- Own generic settings at `./settings` and its optional Express adapter at `./settings/express`; keep both out of the root runtime closure. Move the existing permission helper into core, preserving the CMS command denial class through re-export.
+
+- Own the shared surface-exchange interfaces and reserved parameter constants, formerly declared in daemon. Add the `SurfaceAskThenReport` port so UI can consume the existing daemon lifecycle without depending on its runtime.
+
+## 0.4.1 — 2026-10-05
+
+- New `readToolLimit({ input, max, fallback }, { key })`: an absent limit is `fallback`, one above `max` is capped at `max`, and a non-integer or one below 1 throws `ToolInputError` ("'limit' must be an integer between 1 and <max>").
+- New `optionalOneOf({ input, key, values })`: a value outside `values` throws `ToolInputError` ("'<key>' must be one of: ..."). Both are additive.
+
 ## 0.4.0 — 2026-10-02
 
 ### BREAKING

package/README.md

@@ -15,7 +15,8 @@ set of tokens, and fails to typecheck if any pack's declared dependency is left
 npm install @jini-ai/core
 ```
 
-No peer dependencies — this package is pure TypeScript with no runtime dependencies at all.
+The root has no runtime dependencies and never loads settings or Express. `express` is an optional
+peer used only by `@jini-ai/core/settings/express`; install it in hosts mounting those routes.
 
 ## What you get
 
@@ -239,3 +240,19 @@ Node or reading a working directory. Equality counts as contained. Directory
 prefix siblings and traversal escapes are rejected; a legal `..name` segment is
 allowed. Windows hosts pass `{ caseSensitive: false, separator: "\\\\" }`; POSIX hosts
 retain the default slash separator so backslashes in directory names remain literal.
+
+## Generic settings
+
+`@jini-ai/core/settings` owns scoped definitions, defaults, values, revisions, change feeds,
+boot-time definition registration, dictionaries and agent tools. Hosts inject settings storage,
+active-principal lookup, authorization, clocks and IDs; no CMS or database adapter is required.
+The keys, scopes, permissions and tool IDs are unchanged by the relocation.
+
+`@jini-ai/core/settings/express` exports `registerSettingsRoutes`, HTTP policy contracts and
+`createCmsSettingsService` / `createCmsSettingsChangeFeed` (factory names retained for compatibility).
+Hosts provide route paths, readiness, principal resolution, scheduler, service and feed ports.
+Registration returns a disposer that closes active feeds. The universal settings entry never
+loads this adapter; neither entry is re-exported by the kernel root.
+
+The former `@jini-ai/cms/settings` and `@jini-ai/cms/settings/express` entries re-export these
+owners for one release. New consumers should import the core subpaths directly.

package/dist/agent-tools.d.ts

@@ -16,6 +16,7 @@ export type AgentToolSideEffect = "none" | "mutates-durable-state" | "deletes-du
 export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
 /** Structural catalog contract. Domains may require inputSchema or tighten their own metadata. */
 export interface AgentToolDefinition {
+    readonly metadata?: import('./tool-metadata.js').ToolMetadata;
     name: string;
     description: string;
     sideEffects: AgentToolSideEffect;

package/dist/approval.d.ts

@@ -0,0 +1,134 @@
+import { type HumanConfirmer } from './registration-kit.js';
+import type { ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolRegistration } from './tool-registry.js';
+/** A host describes the action; core owns the decision lifecycle, never the card format. */
+export interface ApprovalPlan<TDescription> {
+    readonly ask: boolean;
+    readonly description: TDescription;
+    /** Only reusable escalation grants receive a key. Irreversible actions omit it. */
+    readonly rememberKey?: string;
+}
+export type ApprovalAnswer = {
+    confirmed: true;
+    choice?: string;
+} | {
+    confirmed: false;
+    reason: 'declined' | 'expired' | 'abandoned';
+};
+/** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
+ * An answer never revives an aborted operation. Transport failures propagate without an effect. */
+export declare function resolveApproval({ signal, askHuman }: {
+    signal: AbortSignal;
+    askHuman: () => Promise<ApprovalAnswer>;
+}, _optional?: {}): Promise<ApprovalAnswer>;
+export interface RememberedApprovalPort {
+    has(required: {
+        ctx: ToolExecutionContext;
+        key: string;
+    }): Promise<boolean>;
+    grant(required: {
+        ctx: ToolExecutionContext;
+        key: string;
+        confirmer: HumanConfirmer;
+    }): Promise<void>;
+}
+export interface ApprovalSteps<TPrepared, TDescription> {
+    prepare(required: {
+        ctx: ToolExecutionContext;
+    }, optional: ToolExecutionOptions): Promise<TPrepared>;
+    describe(required: {
+        ctx: ToolExecutionContext;
+        prepared: TPrepared;
+    }, optional: ToolExecutionOptions): Promise<ApprovalPlan<TDescription>> | ApprovalPlan<TDescription>;
+    askHuman(required: {
+        ctx: ToolExecutionContext;
+        description: TDescription;
+    }, optional: ToolExecutionOptions): Promise<ApprovalAnswer>;
+    run(required: {
+        ctx: ToolExecutionContext;
+        prepared: TPrepared;
+        confirmer: HumanConfirmer;
+        choice?: string | undefined;
+    }, optional: ToolExecutionOptions): Promise<unknown>;
+    /** Abort may happen before preparation; the lifecycle forwards that missing value explicitly. */
+    notConfirmed(required: {
+        reason: 'declined' | 'expired' | 'abandoned';
+        prepared?: TPrepared | undefined;
+    }): unknown;
+}
+/** Extend the branded human-confirm owner with descriptions and optional remembered grants.
+ * Inputs and actor identity are detached before any asynchronous port runs. No input field can
+ * approve an action; only the host transport or the bound grant store can answer. Abort checks
+ * bracket preparation, storage and the human wait, so a completed run never performs an effect.
+ * @param steps Domain preparation/effects and the host's description/transport ports.
+ * @param optional.remembered A persisted escalation store; omission requires a fresh decision.
+ * @returns A handler accepted by the registration kit's human-only actor rule.
+ * @throws Port failures propagate; a failed store cannot silently authorize an action.
+ * @complexity O(input size) for the snapshot plus bounded port calls and the human wait.
+ * @example createApprovalHandler({ prepare, describe, askHuman, run, notConfirmed });
+ */
+export declare function createApprovalHandler<TPrepared, TDescription>(steps: ApprovalSteps<TPrepared, TDescription>, { remembered }?: {
+    remembered?: RememberedApprovalPort;
+}): ToolHandler;
+/** Page-local proposal transport for a browser that must return before its explicit reply arrives.
+ * It carries no principal or tool authorization: the host's execute port must re-check access.
+ * The private action is independent of the rendered snapshot; replies consume it before awaiting
+ * so double clicks/replayed replies cannot execute twice. Abort clears the proposal and listener.
+ * @returns An observable transport for an app dialog and its authenticated reply entry point.
+ * @complexity O(description size) to detach the proposal; O(listeners) to publish a change.
+ */
+export declare function createApprovalProposalStore<TDescription>({ responseTool, messages }: {
+    responseTool: string;
+    messages: {
+        closed: string;
+        pending: string;
+        missing: string;
+    };
+}, { createId }?: {
+    createId?: () => string;
+}): {
+    getSnapshot: (_required?: {}, _optional?: {}) => {
+        pending: {
+            approvalId: string;
+            description: TDescription;
+        } | null;
+        error: string | null;
+    };
+    subscribe: ({ listener }: {
+        listener: () => void;
+    }, _optional?: {}) => () => void;
+    propose({ description, execute, signal }: {
+        description: TDescription;
+        execute: () => Promise<unknown>;
+        signal: AbortSignal;
+    }, _optional?: {}): {
+        status: "approval_required";
+        approvalId: string;
+        description: TDescription;
+        responseTool: string;
+    };
+    respond({ approvalId, approved }: {
+        approvalId: string;
+        approved: boolean;
+    }, _optional?: {}): Promise<unknown>;
+};
+/** Apply a host classification through the same handler owner used by domain plans.
+ * @returns The registration with one approval handler; authorization policy is preserved.
+ */
+export declare function applyApprovalPolicy<TDescription>({ registration, classify, asks, describe, askHuman, notConfirmed }: {
+    registration: ToolRegistration;
+    classify(required: {
+        input: unknown;
+    }): string;
+    asks(required: {
+        class: string;
+    }): boolean;
+    describe(required: {
+        ctx: ToolExecutionContext;
+        class: string;
+    }): Promise<TDescription>;
+    askHuman: ApprovalSteps<string, TDescription>['askHuman'];
+    notConfirmed: ApprovalSteps<string, TDescription>['notConfirmed'];
+}, optional?: {
+    remembered?: RememberedApprovalPort;
+}): ToolRegistration;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -0,0 +1,141 @@
+import { humanConfirmedHandler } from './registration-kit.js';
+/** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
+ * An answer never revives an aborted operation. Transport failures propagate without an effect. */
+export async function resolveApproval({ signal, askHuman }, _optional = {}) {
+    if (signal.aborted)
+        return { confirmed: false, reason: 'abandoned' };
+    let abandon;
+    const aborted = new Promise(resolve => { abandon = () => resolve({ confirmed: false, reason: 'abandoned' }); });
+    signal.addEventListener('abort', abandon, { once: true });
+    try {
+        const answer = await Promise.race([askHuman(), aborted]);
+        return signal.aborted ? { confirmed: false, reason: 'abandoned' } : answer;
+    }
+    finally {
+        signal.removeEventListener('abort', abandon);
+    }
+}
+/** Extend the branded human-confirm owner with descriptions and optional remembered grants.
+ * Inputs and actor identity are detached before any asynchronous port runs. No input field can
+ * approve an action; only the host transport or the bound grant store can answer. Abort checks
+ * bracket preparation, storage and the human wait, so a completed run never performs an effect.
+ * @param steps Domain preparation/effects and the host's description/transport ports.
+ * @param optional.remembered A persisted escalation store; omission requires a fresh decision.
+ * @returns A handler accepted by the registration kit's human-only actor rule.
+ * @throws Port failures propagate; a failed store cannot silently authorize an action.
+ * @complexity O(input size) for the snapshot plus bounded port calls and the human wait.
+ * @example createApprovalHandler({ prepare, describe, askHuman, run, notConfirmed });
+ */
+export function createApprovalHandler(steps, { remembered } = {}) {
+    return humanConfirmedHandler({
+        prepare: async ({ ctx }, options = {}) => {
+            const snapshot = { ...ctx, input: structuredClone(ctx.input), principal: { ...ctx.principal }, run: { ...ctx.run } };
+            if (snapshot.signal.aborted)
+                return { ctx: snapshot };
+            const value = await steps.prepare({ ctx: snapshot }, options);
+            if (snapshot.signal.aborted)
+                return { ctx: snapshot, value };
+            const plan = await steps.describe({ ctx: snapshot, prepared: value }, options);
+            return { ctx: snapshot, value, plan };
+        },
+        askHuman: async ({ prepared }, options = {}) => {
+            const { ctx, plan, value } = prepared;
+            const abandoned = () => ({ confirmed: false, result: steps.notConfirmed({ reason: 'abandoned', prepared: value }) });
+            if (ctx.signal.aborted || !plan)
+                return abandoned();
+            if (!plan.ask)
+                return { confirmed: true };
+            if (plan.rememberKey !== undefined && remembered) {
+                const approved = await remembered.has({ ctx, key: plan.rememberKey });
+                if (ctx.signal.aborted)
+                    return abandoned();
+                if (approved)
+                    return { confirmed: true };
+            }
+            const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) });
+            if (ctx.signal.aborted)
+                return abandoned();
+            if (answer.confirmed !== true)
+                return { confirmed: false, result: steps.notConfirmed({ reason: answer.reason, prepared: value }) };
+            prepared.choice = answer.choice;
+            if (plan.rememberKey !== undefined && remembered) {
+                await remembered.grant({ ctx, key: plan.rememberKey, confirmer: { id: ctx.principal.id, kind: 'user' } });
+            }
+            if (ctx.signal.aborted)
+                return abandoned();
+            return { confirmed: true };
+        },
+        run: ({ prepared }, options = {}) => {
+            const { ctx, value, choice } = prepared;
+            if (ctx.signal.aborted)
+                return Promise.resolve(steps.notConfirmed({ reason: 'abandoned', prepared: value }));
+            return steps.run({ ctx, prepared: value, confirmer: { id: ctx.principal.id, kind: 'user' }, choice }, options);
+        },
+    });
+}
+/** Page-local proposal transport for a browser that must return before its explicit reply arrives.
+ * It carries no principal or tool authorization: the host's execute port must re-check access.
+ * The private action is independent of the rendered snapshot; replies consume it before awaiting
+ * so double clicks/replayed replies cannot execute twice. Abort clears the proposal and listener.
+ * @returns An observable transport for an app dialog and its authenticated reply entry point.
+ * @complexity O(description size) to detach the proposal; O(listeners) to publish a change.
+ */
+export function createApprovalProposalStore({ responseTool, messages }, { createId = () => crypto.randomUUID() } = {}) {
+    let snapshot = { pending: null, error: null };
+    let action = null;
+    let detach = null;
+    const listeners = new Set();
+    const publish = (next) => { snapshot = next; for (const listener of listeners)
+        listener(); };
+    const clear = () => {
+        detach?.();
+        detach = null;
+        action = null;
+        publish({ pending: null, error: null });
+    };
+    return {
+        getSnapshot: (_required = {}, _optional = {}) => snapshot,
+        subscribe: ({ listener }, _optional = {}) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        propose({ description, execute, signal }, _optional = {}) {
+            if (signal.aborted)
+                throw new Error(messages.closed);
+            if (snapshot.pending)
+                throw new Error(messages.pending);
+            const frozenDescription = structuredClone(description);
+            const approvalId = createId();
+            action = { approvalId, execute, signal };
+            signal.addEventListener('abort', clear, { once: true });
+            detach = () => signal.removeEventListener('abort', clear);
+            publish({ pending: { approvalId, description: structuredClone(frozenDescription) }, error: null });
+            return { status: 'approval_required', approvalId, description: frozenDescription, responseTool };
+        },
+        async respond({ approvalId, approved }, _optional = {}) {
+            if (!action || action.approvalId !== approvalId)
+                throw new Error(messages.missing);
+            const prepared = action;
+            clear();
+            const answer = await resolveApproval({ signal: prepared.signal, askHuman: async () => approved === true ? { confirmed: true } : { confirmed: false, reason: 'declined' } });
+            if (!answer.confirmed)
+                return { status: 'declined' };
+            try {
+                return await prepared.execute();
+            }
+            catch (error) {
+                publish({ ...snapshot, error: error instanceof Error ? error.message : String(error) });
+                throw error;
+            }
+        },
+    };
+}
+/** Apply a host classification through the same handler owner used by domain plans.
+ * @returns The registration with one approval handler; authorization policy is preserved.
+ */
+export function applyApprovalPolicy({ registration, classify, asks, describe, askHuman, notConfirmed }, optional = {}) {
+    return { ...registration, handler: createApprovalHandler({
+            prepare: async ({ ctx }) => classify({ input: ctx.input }),
+            describe: async ({ ctx, prepared }) => ({ ask: asks({ class: prepared }), description: await describe({ ctx, class: prepared }) }),
+            askHuman, notConfirmed,
+            run: ({ ctx }, options) => registration.handler(ctx, options),
+        }, optional) };
+}
+//# sourceMappingURL=approval.js.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './token.js';
+export * from './tool-metadata.js';
 export * from './pack.js';
 export * from './bindings.js';
 export type { Daemon, DaemonConfig, DaemonOptions } from './daemon.js';
@@ -9,6 +10,7 @@ export * from './redact.js';
 export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
+export * from './surface-exchanges.js';
 export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
 export { createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
@@ -18,4 +20,7 @@ export * from './contribution-registry.js';
 export * from './naming.js';
 export type { AgentToolSideEffect, AgentToolActorClassRule, AgentToolDefinition } from './agent-tools.js';
 export * from "./registration-kit.js";
+export * from "./approval.js";
+export * from "./native-regexp.js";
+export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, type LegacyToolAuthorizeFn, type AuthorizationPort as ToolPermissionAuthorizationPort, type RequireToolPermissionRequired, type RequireToolPermissionOptional, } from "./tool-permissions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './token.js';
+export * from './tool-metadata.js';
 export * from './pack.js';
 export * from './bindings.js';
 export { createDaemon } from './daemon.js';
@@ -7,6 +8,7 @@ export * from './redact.js';
 export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
+export * from './surface-exchanges.js';
 export { createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
 export * from './gated-mutations.js';
@@ -14,4 +16,7 @@ export * from './model-facing-tool-errors.js';
 export * from './contribution-registry.js';
 export * from './naming.js';
 export * from "./registration-kit.js";
+export * from "./approval.js";
+export * from "./native-regexp.js";
+export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, } from "./tool-permissions.js";
 //# sourceMappingURL=index.js.map

package/dist/model-facing-tool-errors.d.ts

@@ -3,35 +3,187 @@
  * Rule evaluation is O(r); container wrapping O(n), with no I/O or reporting dependencies.
  */
 import { type ToolHandler, type ToolRegistration } from "./tool-registry.js";
+/**
+ * One entry in a domain's allowlist: an error class, and the stable code prefix its message is
+ * published to the model under.
+ *
+ * The code is prepended before a `: ` separator (`MEMBERS_NOT_FOUND: member 'x' was not found`) so
+ * a model — and a test — can match on a stable token without parsing prose, mirroring the prefix
+ * convention `features/widgets/tool-registrations.ts` already shipped.
+ *
+ * `guidance`, when present, is appended after the message. Use it only for a failure where the
+ * caller's next action is not obvious from the message alone (a version conflict that needs a
+ * re-read, say); a not-found needs no coaching.
+ */
 export interface ModelFacingErrorRule {
+    /** The class to match with `instanceof`. Declared to accept any constructor shape so a domain can
+     *  list an error class whose constructor takes extra fields. */
     readonly error: abstract new (...args: never[]) => Error;
+    /** The stable code published before `: `. Conventionally `<DOMAIN>_<REASON>`, SCREAMING_SNAKE. */
     readonly code: string;
+    /** Published INSTEAD of the error's own message. Set it for a class whose KIND is the actionable
+     *  reason a caller needs but whose TEXT is not safe to publish — one that wraps another
+     *  component's error (a sealer's, a driver's, a keyring's), which can carry plaintext, an internal
+     *  address, an env var name or an absolute path. Omit it to publish the class's own message
+     *  verbatim, which is only correct when every construction site builds that message from fixed
+     *  text and the caller's own input.
+     *
+     *  The same field, for the same reason, as {@link CallerSafeErrorRule.message} — these two
+     *  allowlists are the RETURNED-result and THROWN-rejection halves of one policy, and a class whose
+     *  kind is safe to name on one half is safe to name on the other. They drifted until 2026-09-18:
+     *  `features/custom-credentials` listed `CustomCredentialSecretStoreUnconfiguredError` with a fixed
+     *  message in its `CallerSafeErrorRule` allowlist, but could not list it here at all, because the
+     *  only thing this shape could publish was the very text that had to stay in. A missing site root
+     *  key — the one operator-fixable failure in that domain — therefore reached the model as a bare
+     *  `INTERNAL_ERROR` on every credential-using tool. */
     readonly message?: string;
+    /** Optional recovery guidance appended after the message. */
     readonly guidance?: string;
 }
+/**
+ * The code every domain publishes an authorization refusal under, parameterized by domain prefix.
+ *
+ * Exists because `ForbiddenError` is the ONE class in this ladder that no domain declares: the kit's
+ * `requireToolPermission` throws it on every domain's behalf. Deriving the rule here rather than
+ * retyping `{ error: ForbiddenError, code: "X_FORBIDDEN" }` in six files means a later decision to
+ * reconcile this code with the HTTP arm's own `FORBIDDEN` is a one-line change here, not a sweep.
+ *
+ * NOTE (2026-09-16): the model-facing and HTTP arms disagree on this code today — the HTTP mappers
+ * return `FORBIDDEN` while the model-facing arm returns `<DOMAIN>_FORBIDDEN`. That drift predates
+ * this file (see `features/widgets/tool-registrations.ts`'s `toModelFacingWidgetsError` doc, which
+ * documented it for Widgets) and is owned elsewhere. This helper deliberately matches the SHIPPED
+ * model-facing convention rather than inventing a third spelling.
+ *
+ * The refusal message `requireToolPermission` builds names the principal, the permission, and the
+ * `authorize()` reason — no data, no internals. Surfacing it tells a model whether to stop asking
+ * or to ask a human for access; redacting it tells it only that something broke.
+ *
+ * @param required.domainPrefix - The domain's SCREAMING_SNAKE prefix, e.g. `MEMBERS`.
+ * @param required.error - The consumer's permission-error class; core has no CMS dependency.
+ * @returns The rule to place in that domain's allowlist.
+ * @complexity O(1).
+ */
 export declare function forbiddenRule(required: {
     domainPrefix: string;
     error: ModelFacingErrorRule["error"];
 }): ModelFacingErrorRule;
+/**
+ * Re-classifies one rejection against a domain's allowlist, so a listed domain error reaches the
+ * model as a `ToolInputError` carrying its real message instead of a redacted `INTERNAL_ERROR`.
+ *
+ * Rules are evaluated IN ORDER and the first `instanceof` match wins, so a domain listing both a
+ * subclass and its superclass must place the subclass first — the same ordering discipline any
+ * hand-written `instanceof` ladder carries, made explicit here because an array hides it less than
+ * a chain of `if`s does.
+ *
+ * A matched rule publishes the error's own message, or {@link ModelFacingErrorRule.message} instead
+ * when the rule sets one — see that field for which classes need it and why.
+ *
+ * An already-`ToolInputError` rejection is returned untouched: it is already correctly classified,
+ * and re-wrapping it would double a code prefix that a `withSchemaOnRejection` wrap may have
+ * already attached.
+ *
+ * @param required.err - The rejection, of unknown type — anything a handler can throw.
+ * @param required.rules - The domain's allowlist. Anything unmatched is returned UNCHANGED and stays
+ * redacted; see this file's header for why that default is the security-relevant half.
+ * @returns The value to re-throw: a `ToolInputError` for a matched rule, otherwise `err` itself.
+ * @complexity O(r) in the rule count, on the failure path only.
+ */
 export declare function reclassifyToolError(required: {
     err: unknown;
     rules: readonly ModelFacingErrorRule[];
 }): unknown;
+/**
+ * Wraps EVERY handler in a domain's map with {@link reclassifyToolError}, returning a new map.
+ *
+ * Wrapping the whole map once — rather than reclassifying at each call site — is the point. This
+ * codebase's dominant defect is a correct primitive with an unwired call site, and a per-call-site
+ * reshape is exactly that defect waiting to happen: `features/post/tool-registrations.ts` had a
+ * correct `toModelFacingUpdateError` wired into ONE of its handlers while its siblings kept
+ * throwing the same class straight through to the redactor. A map-level wrap cannot have a missed
+ * arm, because it has no arms.
+ *
+ * The wrap is transparent on the success path: the handler's own return value is passed through
+ * untouched, and only the `catch` does work.
+ *
+ * @param required.handlers - The domain's handler map, keyed by tool id.
+ * @param rules - The domain's allowlist, applied identically to every handler.
+ * @returns A new map with the same keys; the input map is not mutated.
+ * @complexity O(h) handlers wrapped once at build time; O(r) per failed call, none per successful one.
+ */
 export declare function withModelFacingErrors(required: {
     handlers: Readonly<Record<string, ToolHandler>>;
     rules: readonly ModelFacingErrorRule[];
 }): Record<string, ToolHandler>;
+/**
+ * Wraps EVERY registration's handler in a domain's `ToolRegistration[]` with
+ * {@link reclassifyToolError}, returning a new array. The `ToolRegistration[]`-shaped sibling of
+ * {@link withModelFacingErrors} — for the registry-converted domains whose `build*Registrations`
+ * returns an array of `{descriptor, handler, policy}` (see `assistant/tool-contribution-registry.ts`'s
+ * `ToolContributor.build`) rather than a `Record<toolId, handler>`. `features/entries`,
+ * `features/content-types`, `features/navigation` and `features/workspace` are re-exported Jini
+ * builders of exactly this shape — see each one's `contribute*Tools`.
+ *
+ * Same transparency guarantee as {@link withModelFacingErrors}: only the `catch` arm does work, and
+ * every other field of each registration (`descriptor`, `policy`) passes through unchanged.
+ *
+ * @param required.registrations - The domain's registrations, in whatever order `build*Registrations`
+ * returned them.
+ * @param rules - The domain's allowlist, applied identically to every registration.
+ * @returns A new array with the same length and order; the input array is not mutated.
+ * @complexity O(n) registrations wrapped once at build time; O(r) per failed call, none per successful one.
+ */
 export declare function withModelFacingRegistrationErrors(required: {
     registrations: readonly ToolRegistration[];
     rules: readonly ModelFacingErrorRule[];
 }): ToolRegistration[];
+/**
+ * One entry in a structured-result allowlist — see {@link callerSafeErrorMessage}.
+ *
+ * No `code`: a structured result already carries its own `reason` discriminant, and its message is
+ * often rendered to a human as-is, so no prefix is added.
+ */
 export interface CallerSafeErrorRule {
+    /** The class to match with `instanceof`. Same constructor shape as {@link ModelFacingErrorRule.error}. */
     readonly error: abstract new (...args: never[]) => Error;
+    /** Published INSTEAD of the error's own message. Set it for a class whose KIND is safe and worth
+     *  naming but whose message is not — one that embeds another error's text. Omit it to publish the
+     *  class's own message verbatim, which is only correct when every construction site builds that
+     *  message from fixed text and the caller's own input. */
     readonly message?: string;
 }
+/**
+ * The message a RETURNED failure result may carry for `err`: a listed class's message (or its fixed
+ * replacement), otherwise `fallback`.
+ *
+ * Unknown means redacted. An error class added tomorrow, a raw driver error, or a non-`Error` throw
+ * all get `fallback`, never their own text. Rules are evaluated in order; the first `instanceof`
+ * match wins.
+ *
+ * @param required.err - The caught value, of unknown type.
+ * @param required.rules - The allowlist.
+ * @param required.fallback - Fixed text for everything unlisted. Must not be built from `err`.
+ * @returns The message to publish.
+ * @complexity O(r) in the rule count.
+ */
 export declare function callerSafeErrorMessage(required: {
     err: unknown;
     rules: readonly CallerSafeErrorRule[];
     fallback: string;
 }): string;
+/**
+ * What a server-side log line may say about an error whose message is NOT known to be safe: its class
+ * name, a constant-token `code`, and the same for its direct `cause`. Never the message, which can
+ * quote a secret — `JSON.parse` quotes its input, and a sealer is handed plaintext.
+ *
+ * Use it wherever the raw message could carry a credential. Where a class's message is designed for
+ * logs (`EgressRefusedError.message`), log that instead.
+ *
+ * @param required.err - The caught value.
+ * @returns e.g. `SqliteError(SQLITE_BUSY)`, or `TypeError cause=Error(ECONNREFUSED)`.
+ * @complexity O(1).
+ */
+export declare function describeErrorForLog(required: {
+    err: unknown;
+}, _optional?: Record<string, never>): string;
 //# sourceMappingURL=model-facing-tool-errors.d.ts.map