@jini-ai/core 0.4.8 → 0.6.10

package/dist/settings/tool-registrations.js

@@ -1,7 +1,8 @@
 import { adaptLegacyAuthorize } from "../tool-permissions.js";
-import { buildSettingsValueWriteHandler } from "./agent-value-write-tools.js";
-import { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
+import { agentWriteRules, buildSettingsValueWriteHandler, toWriteDeps } from "./agent-value-write-tools.js";
+import { findAgentWriteRule } from "./agent-write-denylist.js";
 import { buildDomainRegistrations, indexCatalogById, optionalString, requireInputRecord, requireNoInput, requireString, withSchemaOnRejection } from "../registration-kit.js";
+import { ToolInputError } from "../tool-registry.js";
 import { requireToolPermission } from "../tool-permissions.js";
 import { getSettingsAgentToolCatalog } from "./agent-tools.js";
 import { AGENT_PREFERENCE_WRITE_SCOPE, AGENT_WRITABLE_PREFERENCE_IDS, resolveAgentWritablePreference, } from "./agent-writable-preferences.js";
@@ -42,25 +43,6 @@ async function resolveOwnOrOtherPrincipalRead(routeDeps, required) {
 function layerValueOf(record) {
     return record && record.state === "set" ? record.valueJson : null;
 }
-/**
- * Builds `write-service.ts`'s own five-field dep shape from `RouteDeps`.
- *
- * Deliberately duplicates a host's own HTTP admin layer's equivalent field-mapping helper rather
- * than importing it, for the reason this file's header already gives about
- * `resolveOwnOrOtherPrincipalRead`: this is domain-owned wiring, and importing from a host's HTTP
- * admin layer would invert the ports/adapters direction. It is a field mapping, not logic, so the
- * two copies carry no behavioral drift risk — and `write-service.ts` is the single chokepoint
- * either way, so a divergence here could only produce a missing dependency, which fails loudly.
- */
-function toWriteDeps(routeDeps) {
-    return {
-        repo: routeDeps.settingsRepo,
-        clock: routeDeps.clock,
-        ids: routeDeps.idGen,
-        authorize: routeDeps.authorize,
-        principals: routeDeps.principalRepo,
-    };
-}
 /**
  * Errors a DIFFERENT input would fix, for `withSchemaOnRejection`'s decoration.
  *
@@ -110,6 +92,49 @@ const UNWIRED_SETTINGS_TOOL_IDS = new Set([
     // platform-wide.
     "settings_register_definitions",
 ]);
+/**
+ * One `settings_list_definitions` row. Only aliases need an extra lookup. Their target's
+ * schema/scope and BOTH coordinates' key policies must agree with the write handler;
+ * dangling/tombstoned targets fail closed. O(r) in policy rules plus at most one alias resolution.
+ */
+async function describeDefinitionForAgent(routeDeps, rules, def) {
+    const resolved = def.status === "alias"
+        ? await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { namespace: def.namespace, key: def.key, workspaceId: routeDeps.workspaceId })
+        : def;
+    const coordinates = resolved ? [def, resolved] : [def];
+    const matchesAny = (list) => coordinates.some((coordinate) => !!findAgentWriteRule(list, coordinate));
+    const denied = matchesAny(rules.denied);
+    const confirmationRequired = matchesAny(rules.confirmation);
+    const scopes = resolved?.scopes ?? def.scopes;
+    return { namespace: def.namespace, key: def.key, ownerKind: def.ownerKind, scopes, status: def.status, version: def.version,
+        schema: resolved?.schema ?? def.schema,
+        agentWritable: isAgentWritable({ resolved, denied, confirmationRequired, canConfirm: !!routeDeps.confirmWrite, scopes }),
+        confirmationRequired };
+}
+/** Mirrors the write handler's refusals: live target, not denied, confirmable when protected,
+ * and writable at workspace or user scope. O(1). */
+function isAgentWritable(facts) {
+    if (!facts.resolved || facts.resolved.status === "tombstone" || facts.denied)
+        return false;
+    if (facts.confirmationRequired && !facts.canConfirm)
+        return false;
+    return (facts.scopes & (SCOPE_BIT.workspace | SCOPE_BIT.user)) !== 0;
+}
+/** Every split point of a dotted key that names a live (non-tombstoned) definition.
+ * Leading/trailing dots are never split points. O(k) resolver calls for k dots. */
+async function findDottedKeySplits(routeDeps, dottedKey) {
+    const matches = [];
+    // Reuse the definition resolver, including workspace fencing and aliases; never split on a guess.
+    for (let index = 1; index < dottedKey.length - 1; index++) {
+        if (dottedKey[index] !== ".")
+            continue;
+        const candidate = { namespace: dottedKey.slice(0, index), key: dottedKey.slice(index + 1) };
+        const definition = await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { ...candidate, workspaceId: routeDeps.workspaceId });
+        if (definition && definition.status !== "tombstone")
+            matches.push(candidate);
+    }
+    return matches;
+}
 export function buildSettingsRegistrations(routeDeps) {
     const handlers = {
         settings_set_value: buildSettingsValueWriteHandler(routeDeps, "settings_set_value"),
@@ -122,23 +147,8 @@ export function buildSettingsRegistrations(routeDeps) {
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: null }),
                 routeDeps.settingsRepo.listActiveDefinitions({ workspaceId: routeDeps.workspaceId }),
             ]);
-            const deniedRules = [...AGENT_WRITE_DENIED_SETTINGS, ...(routeDeps.extraDeniedSettings ?? [])];
-            const confirmationRules = [...(routeDeps.confirmationSettings ?? AGENT_WRITE_CONFIRMATION_SETTINGS), ...(routeDeps.extraConfirmationSettings ?? [])];
-            // Only aliases need an extra lookup. Their target's schema/scope and BOTH coordinates'
-            // key policies must agree with the write handler; dangling/tombstoned targets fail closed.
-            const data = (await Promise.all([...platformDefs, ...siteDefs].map(async (def) => {
-                const resolved = def.status === "alias"
-                    ? await resolveDefinitionRaw({ repo: routeDeps.settingsRepo }, { namespace: def.namespace, key: def.key, workspaceId: routeDeps.workspaceId })
-                    : def;
-                const coordinates = resolved ? [def, resolved] : [def];
-                const denied = coordinates.some((coordinate) => !!findAgentWriteRule(deniedRules, coordinate));
-                const confirmationRequired = coordinates.some((coordinate) => !!findAgentWriteRule(confirmationRules, coordinate));
-                const scopes = resolved?.scopes ?? def.scopes;
-                return { namespace: def.namespace, key: def.key, ownerKind: def.ownerKind, scopes, status: def.status, version: def.version,
-                    schema: resolved?.schema ?? def.schema,
-                    agentWritable: !!resolved && resolved.status !== "tombstone" && !denied && (!confirmationRequired || !!routeDeps.confirmWrite) && (scopes & (SCOPE_BIT.workspace | SCOPE_BIT.user)) !== 0,
-                    confirmationRequired };
-            })))
+            const rules = agentWriteRules(routeDeps);
+            const data = (await Promise.all([...platformDefs, ...siteDefs].map((def) => describeDefinitionForAgent(routeDeps, rules, def))))
                 .sort((a, b) => a.namespace.localeCompare(b.namespace) || a.key.localeCompare(b.key));
             return { data };
         },
@@ -245,6 +255,21 @@ export function buildSettingsRegistrations(routeDeps) {
             return { setting: settingId, value: stored, scope: AGENT_PREFERENCE_WRITE_SCOPE, revisionSeq };
         },
     };
-    return buildDomainRegistrations({ domain: "settings", catalogModule: "settings/agent-tools.ts", catalog: CATALOG_BY_ID, handlers, derivedRisk: settingsDerivedRisk }, { unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS });
+    return buildDomainRegistrations({ domain: "settings", catalogModule: "settings/agent-tools.ts", catalog: CATALOG_BY_ID, handlers, derivedRisk: settingsDerivedRisk,
+        inputNormalizers: { settings_set_value: async ({ input }) => {
+                if (input.namespace !== undefined || typeof input.key !== "string" || !input.key.includes("."))
+                    return { input, notes: [] };
+                if (input.key.length > 512)
+                    throw new ToolInputError({ message: "settings_set_value: dotted key is too long. Send namespace and key separately." });
+                await routeDeps.settingsReady;
+                await routeDeps.settingsUiTabsReady;
+                const matches = await findDottedKeySplits(routeDeps, input.key);
+                if (matches.length !== 1)
+                    throw new ToolInputError({ message: matches.length
+                            ? `settings_set_value: dotted key is ambiguous (${matches.map(match => `namespace=${match.namespace}, key=${match.key}`).join("; ")}). Send namespace and key explicitly.`
+                            : "settings_set_value: no registered namespace/key pair matches this dotted key. Call settings_list_definitions to see valid keys; send namespace and key explicitly." });
+                return { input: { ...input, ...matches[0] }, notes: ["dotted key→namespace + key"] };
+            } },
+    }, { unwiredToolIds: UNWIRED_SETTINGS_TOOL_IDS });
 }
 //# sourceMappingURL=tool-registrations.js.map

package/dist/settings/write-service.d.ts

@@ -110,8 +110,21 @@ export interface SetValueRequired {
         requiredPermissionOverride?: string | undefined;
     };
 }
-/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export declare function set(required: SetValueRequired): Promise<{
+/** Optional concurrency guard shared by `set` and `clear`. */
+export interface SettingsValueWriteOptions {
+    /** Compare the addressed layer's stored seq, including cleared rows; 0 means no stored row.
+     * Omission preserves unconditional writes. Defaults, inherited values and definition revisions
+     * do not count. A mismatch throws SettingsRevisionConflictError and rolls back the write.
+     */
+    readonly expectedRevisionSeq?: number | undefined;
+}
+/**
+ * Authorize -> validate -> value + revision in one transaction. An optional expectedRevisionSeq
+ * refuses a stale scoped value and rolls back its revision; omission keeps unconditional writes.
+ * @example await set({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function set(required: SetValueRequired, optional?: SettingsValueWriteOptions): Promise<{
     value: JsonValue;
     revisionSeq: number;
 }>;
@@ -135,8 +148,14 @@ export interface ClearValueRequired {
         authWorkspaceId?: UUID | undefined;
     };
 }
-/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export declare function clear(required: ClearValueRequired): Promise<{
+/**
+ * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
+ * the same semantics as `set`. With skipTransaction, the enclosing caller must propagate errors
+ * so its transaction rolls back the appended revision on conflict.
+ * @example await clear({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function clear(required: ClearValueRequired, optional?: SettingsValueWriteOptions): Promise<{
     revisionSeq: number;
 }>;
 export interface ResetNamespaceRequired {
@@ -239,6 +258,25 @@ export declare function retypeDefinition(required: RetypeDefinitionRequired): Pr
     settingId: string;
     version: number;
 }>;
+/** Add source-declared scopes to a core definition without moving or rewriting existing values.
+ * Boot uses this when a workspace preference gains a personal override. Scope removal is a
+ * separate migration decision: this operation only adds bits and preserves definition identity.
+ * @throws DefinitionInvalidError for operator-owned definitions or invalid scope bits.
+ * @complexity O(1), one definition transaction and cache invalidation.
+ * @example await extendDefinitionScopes({ deps, input: { namespace, key, workspaceId: null,
+ *   scopes: SCOPE_BIT.user, callerPrincipalId, authWorkspaceId } });
+ */
+export declare function extendDefinitionScopes({ deps, input }: {
+    deps: SettingsWriteServiceDeps;
+    input: {
+        namespace: string;
+        key: string;
+        workspaceId: UUID | null;
+        scopes: number;
+        callerPrincipalId: UUID;
+        authWorkspaceId: UUID;
+    };
+}, _options?: {}): Promise<void>;
 export interface ReconcileDefinitionDefaultRequired {
     deps: SettingsWriteServiceDeps;
     input: {

package/dist/settings/write-service.js

@@ -1,5 +1,5 @@
 import { nowIso as kernelNowIso } from "../primitives/index.js";
-import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, ValueValidationFailedError, } from "./errors.js";
+import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, SettingsRevisionConflictError, ValueValidationFailedError, } from "./errors.js";
 import { invalidateDefinitionNamespaceCache, resolveDefinitionRaw, validateDefinitionInput, validateValueAgainstSchema, } from "./settings.js";
 import { SCOPE_BIT } from "./types.js";
 /**
@@ -148,8 +148,33 @@ async function assertTargetPrincipalInWorkspace(deps, input) {
         throw new PrincipalNotFoundError(`principal '${input.principalId}' was not found in workspace '${input.workspaceId}'`, input.principalId, input.workspaceId);
     }
 }
-/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export async function set(required) {
+/**
+ * Check the addressed value after appendRevision has taken the ledger lock. On Postgres, a read
+ * before that lock can see the same old seq in two READ COMMITTED transactions and lose an update.
+ * The caller's enclosing transaction rolls the appended revision back on conflict.
+ * @complexity At most one scoped value read; no reads when the option is omitted.
+ */
+async function assertExpectedRevision(required, optional = {}) {
+    if (optional.expectedRevisionSeq === undefined)
+        return;
+    const { repo, settingId, input } = required;
+    const current = input.scope === "global"
+        ? await repo.getGlobalValue(settingId)
+        : input.scope === "workspace"
+            ? await repo.getWorkspaceValue({ workspaceId: input.workspaceId, settingId })
+            : await repo.getUserValue({ workspaceId: input.workspaceId, principalId: input.principalId ?? input.callerPrincipalId, settingId });
+    const actualRevisionSeq = current?.seq ?? 0;
+    if (actualRevisionSeq !== optional.expectedRevisionSeq) {
+        throw new SettingsRevisionConflictError({ expectedRevisionSeq: optional.expectedRevisionSeq, actualRevisionSeq });
+    }
+}
+/**
+ * Authorize -> validate -> value + revision in one transaction. An optional expectedRevisionSeq
+ * refuses a stale scoped value and rolls back its revision; omission keeps unconditional writes.
+ * @example await set({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function set(required, optional = {}) {
     const { deps, input } = required;
     const permission = input.requiredPermissionOverride ??
         deriveRequiredPermission({
@@ -190,6 +215,7 @@ export async function set(required) {
             changeSetId: null,
             createdAt: now,
         });
+        await assertExpectedRevision({ repo: deps.repo, settingId: definition.settingId, input }, optional);
         const base = {
             settingId: definition.settingId,
             scope: input.scope,
@@ -222,8 +248,14 @@ export async function set(required) {
     });
     return result;
 }
-/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export async function clear(required) {
+/**
+ * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
+ * the same semantics as `set`. With skipTransaction, the enclosing caller must propagate errors
+ * so its transaction rolls back the appended revision on conflict.
+ * @example await clear({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function clear(required, optional = {}) {
     const { deps, input } = required;
     if (!input.skipAuthorize) {
         const permission = deriveRequiredPermission({
@@ -262,6 +294,7 @@ export async function clear(required) {
             changeSetId: null,
             createdAt: now,
         });
+        await assertExpectedRevision({ repo: deps.repo, settingId: definition.settingId, input }, optional);
         const base = {
             settingId: definition.settingId,
             scope: input.scope,
@@ -416,6 +449,11 @@ export async function renameDefinition(required) {
     const { deps, input } = required;
     await authorizeDefinitionsManage(deps, input.callerPrincipalId, input.authWorkspaceId);
     const current = await resolveActiveDefinitionOrThrow(deps, input, "rename");
+    // A dispatched `rename` item that omits its target arrives here as `""` (see definitions-dispatch);
+    // without this guard the definition was silently moved to the empty name `.`.
+    if (!input.newNamespace || !input.newKey) {
+        throw new DefinitionInvalidError("rename requires a non-empty newNamespace and newKey");
+    }
     if (input.namespace === input.newNamespace && input.key === input.newKey) {
         throw new DefinitionInvalidError("rename requires newNamespace/newKey to differ from the current name");
     }
@@ -564,6 +602,35 @@ export async function retypeDefinition(required) {
     invalidateDefinitionNamespaceCache(deps.repo, input.namespace);
     return result;
 }
+/** Add source-declared scopes to a core definition without moving or rewriting existing values.
+ * Boot uses this when a workspace preference gains a personal override. Scope removal is a
+ * separate migration decision: this operation only adds bits and preserves definition identity.
+ * @throws DefinitionInvalidError for operator-owned definitions or invalid scope bits.
+ * @complexity O(1), one definition transaction and cache invalidation.
+ * @example await extendDefinitionScopes({ deps, input: { namespace, key, workspaceId: null,
+ *   scopes: SCOPE_BIT.user, callerPrincipalId, authWorkspaceId } });
+ */
+export async function extendDefinitionScopes({ deps, input }, _options = {}) {
+    await authorizeDefinitionsManage(deps, input.callerPrincipalId, input.authWorkspaceId);
+    const current = await resolveActiveDefinitionOrThrow(deps, input, "extend the scopes of");
+    const validBits = SCOPE_BIT.global | SCOPE_BIT.workspace | SCOPE_BIT.user;
+    if (current.ownerKind !== "core" || !Number.isInteger(input.scopes) || input.scopes <= 0 || input.scopes > validBits) {
+        throw new DefinitionInvalidError("Only core definitions can gain valid source-declared scope bits");
+    }
+    const scopes = current.scopes | input.scopes;
+    if (scopes === current.scopes)
+        return;
+    await deps.repo.transaction(async () => {
+        const now = kernelNowIso({ clock: deps.clock });
+        await deps.repo.saveDefinition({ ...current, scopes, updatedAt: now });
+        // Re-registration of metadata, not a value/schema change; retain the existing revision vocabulary.
+        await deps.repo.appendRevision({ entityKind: "definition", settingId: current.settingId,
+            scope: null, workspaceId: current.workspaceId, principalId: null, op: "register",
+            beforeJson: { scopes: current.scopes }, afterJson: { scopes }, defVersion: current.version,
+            actor: input.callerPrincipalId, originPluginId: null, changeSetId: null, createdAt: now });
+    });
+    invalidateDefinitionNamespaceCache(deps.repo, input.namespace);
+}
 /**
  * Reconciles a stored `default_json` that has drifted from the default its
  * source declares. Idempotent and a no-op when they already agree.

package/dist/target-scope.d.ts

@@ -21,6 +21,8 @@ export type TargetResolution = 'current' | {
  * @param required.isCurrentTarget - Check whether an unscoped tool names the current target.
  * @param optional - Target input name, schema description, refusal text and a narrowing scope predicate.
  * @returns A new array in the same order, preserving tools that already own the target input.
+ * Unscoped targets are also checked by normalizeInput, before policy or approval planning;
+ * the handler retains its check for direct handler callers.
  * @throws ToolInputError from a wrapped handler for a non-string target or a refused foreign target.
  * Host port errors propagate unchanged from the wrapped handler.
  * @complexity O(n) over registrations, plus copying supported schemas' top-level properties.

package/dist/target-scope.js

@@ -1,5 +1,6 @@
 import { isNonArrayRecord } from './records.js';
-import { isReadOnlyTool, ToolInputError } from './tool-registry.js';
+import { isReadOnlyTool } from './tool-registry.js';
+import { ToolInputError } from './tool-input-errors.js';
 /** Narrow the shared record predicate to ordinary or null-prototype objects, excluding instances. */
 function isPlainObject(value) {
     if (!isNonArrayRecord({ value }))
@@ -25,6 +26,8 @@ function withTargetParam(schema, param, description) {
  * @param required.isCurrentTarget - Check whether an unscoped tool names the current target.
  * @param optional - Target input name, schema description, refusal text and a narrowing scope predicate.
  * @returns A new array in the same order, preserving tools that already own the target input.
+ * Unscoped targets are also checked by normalizeInput, before policy or approval planning;
+ * the handler retains its check for direct handler callers.
  * @throws ToolInputError from a wrapped handler for a non-string target or a refused foreign target.
  * Host port errors propagate unchanged from the wrapped handler.
  * @complexity O(n) over registrations, plus copying supported schemas' top-level properties.
@@ -39,10 +42,23 @@ export function applyTargetScope(required, optional = {}) {
         if (isNonArrayRecord(properties) && Object.hasOwn(properties.value, param))
             return registration;
         const scoped = isReadOnlyTool({ descriptor }) && (optional.scoped?.({ registration }) ?? true);
-        const inputSchema = scoped ? withTargetParam(descriptor.inputSchema, param, describeParam) : descriptor.inputSchema;
+        const inputSchema = withTargetParam(descriptor.inputSchema, param, describeParam);
         return {
             ...registration,
             descriptor: inputSchema === descriptor.inputSchema ? descriptor : { ...descriptor, inputSchema },
+            normalizeInput: async ({ input }, options) => {
+                const normalized = registration.normalizeInput ? await registration.normalizeInput({ input }, options) : { input, notes: [] };
+                // Target refusal precedes policy and confirmation, including each merged plan item.
+                // Keep the key intact: downstream gates must authorize exactly this target.
+                if (!scoped && isPlainObject(normalized.input) && Object.hasOwn(normalized.input, param)) {
+                    const target = normalized.input[param];
+                    if (typeof target !== 'string')
+                        throw new ToolInputError({ message: `${param} must be a string` });
+                    if (!await required.isCurrentTarget({ target }))
+                        throw new ToolInputError({ message: refuseMessage });
+                }
+                return normalized;
+            },
             handler: async (ctx, options) => {
                 if (!isPlainObject(ctx.input) || !Object.hasOwn(ctx.input, param))
                     return registration.handler(ctx, options);

package/dist/text/escape.js

@@ -13,11 +13,11 @@ const XML_ENTITIES = { ...HTML_ENTITIES, "'": "'" };
 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);
+    return text.replace(SPECIAL, (char) => HTML_ENTITIES[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);
+    return text.replace(SPECIAL, (char) => XML_ENTITIES[char]);
 }
 //# sourceMappingURL=escape.js.map

package/dist/text/sanitize-untrusted-text.d.ts

@@ -8,6 +8,9 @@ export declare function stripControlSequences({ text }: {
     text: string;
 }): string;
 export interface SanitizeTextOptions {
+    /** Exact IDs from trusted registration metadata, never inferred from error text or arguments.
+     * Credential rules still run first; prefixes and glued suffixes are never exempted. */
+    diagnosticToolIds?: readonly string[];
     /** Maximum output length; longer input is truncated with a trailing marker. Defaults to 500. */
     maxLength?: number;
 }
@@ -15,6 +18,8 @@ export interface SanitizeTextOptions {
  * Strip terminal control sequences, redact anything that looks like a secret, and cap the
  * length of `text` — the one function every boundary that surfaces daemon/network-derived text
  * to stderr/stdout should route through first.
+ * Trusted diagnosticToolIds exempt complete IDs (including dots) only, after credential masking.
+ * @complexity O(n + t) local time/space for n text bytes and t trusted ID bytes.
  */
 export declare function sanitizeUntrustedText({ text }: {
     text: string;

package/dist/text/sanitize-untrusted-text.js

@@ -1,4 +1,4 @@
-import { LABELED_SECRET_RE, OPAQUE_TOKEN_RE, NON_SECRET_TOKEN_RE } from "../redact.js";
+import { redactSecrets, LABELED_SECRET_RE, OPAQUE_TOKEN_RE, NON_SECRET_TOKEN_RE } from "../redact.js";
 /**
  * @module redact
  *
@@ -39,6 +39,38 @@ function isOtherControlCode(code) {
         return true; // C1 controls
     return false;
 }
+/** True when position `j` starts an OSC terminator: BEL, or ST (`ESC \\`). */
+function isOscTerminatorAt(text, j) {
+    const code = text.charCodeAt(j);
+    return code === BEL || (code === ESC && text.charCodeAt(j + 1) === BACKSLASH);
+}
+/** Index of a CSI's final byte at or after `from`, or `text.length` when the CSI is truncated. */
+function csiEnd(text, from) {
+    let j = from;
+    while (j < text.length && !isCsiFinalByte(text.charCodeAt(j)))
+        j++;
+    return j;
+}
+/** Index of the last code unit of an OSC body starting at `from`: the BEL, the `\\` of ST, or the
+ * final code unit when the OSC is never terminated. */
+function oscEnd(text, from) {
+    let j = from;
+    while (j < text.length && !isOscTerminatorAt(text, j))
+        j++;
+    // charCodeAt past the end is NaN, so a truncated OSC never matches BEL here.
+    if (text.charCodeAt(j) === BEL)
+        return j;
+    return Math.min(j + 1, text.length - 1);
+}
+/** Index of the last code unit consumed by the escape sequence whose ESC sits at `start`. */
+function escapeSequenceEnd(text, start) {
+    const next = text.charCodeAt(start + 1);
+    if (next === CSI_OPEN)
+        return csiEnd(text, start + 2);
+    if (next === OSC_OPEN)
+        return oscEnd(text, start + 2);
+    return start; // bare ESC (or an unrecognized ESC-prefixed byte): drop just the ESC byte
+}
 /**
  * Strip ANSI/terminal escape sequences (CSI `ESC [ ... final-byte`, OSC `ESC ] ... BEL-or-ST`,
  * and bare ESC-prefixed bytes) plus other C0/C1 control characters from `text`. Written as an
@@ -50,53 +82,41 @@ export function stripControlSequences({ text }) {
     for (let i = 0; i < text.length; i++) {
         const code = text.charCodeAt(i);
         if (code === ESC) {
-            const next = text.charCodeAt(i + 1);
-            if (next === CSI_OPEN) {
-                let j = i + 2;
-                while (j < text.length && !isCsiFinalByte(text.charCodeAt(j)))
-                    j++;
-                i = j; // land on the final byte; the outer loop's i++ steps past it
-                continue;
-            }
-            if (next === OSC_OPEN) {
-                let j = i + 2;
-                while (j < text.length &&
-                    text.charCodeAt(j) !== BEL &&
-                    !(text.charCodeAt(j) === ESC && text.charCodeAt(j + 1) === BACKSLASH)) {
-                    j++;
-                }
-                if (j < text.length && text.charCodeAt(j) === BEL)
-                    i = j;
-                else
-                    i = Math.min(j + 1, text.length - 1);
-                continue;
-            }
-            continue; // bare ESC (or an unrecognized ESC-prefixed byte): drop just the ESC byte
-        }
-        if (isOtherControlCode(code))
+            i = escapeSequenceEnd(text, i); // land on the last consumed byte; the loop's i++ steps past it
             continue;
-        out += text[i];
+        }
+        if (!isOtherControlCode(code))
+            out += text[i];
     }
     return out;
 }
-// A labeled credential (`Authorization: ...`, `api-key=...`) has everything after the label
-// redacted. A bare run of 20+ base64url/hex-alphabet characters is treated as a possible
-// opaque token/secret and redacted outright, even with no label.
-/** Redact labeled credentials and long opaque-token-looking substrings from `text`. */
-function redactSecretLike({ text }) {
-    return text
-        .replace(LABELED_SECRET_RE, (match) => match.replace(/\S+$/, '[redacted]'))
-        .replace(OPAQUE_TOKEN_RE, (match) => (NON_SECRET_TOKEN_RE.test(match) ? match : '[redacted]'));
+/** Exact diagnostic vocabulary only: unknown spellings and glued suffixes remain opaque. */
+const DIAGNOSTIC_TOKENS = new Set([
+    'additionalProperties', 'additionalItems', 'unevaluatedProperties', 'unevaluatedItems',
+    'dependentRequired', 'dependentSchemas', 'exclusiveMinimum', 'exclusiveMaximum',
+    'minContains', 'maxContains', 'patternProperties', 'propertyNames', 'prefixItems',
+    'contentEncoding', 'contentMediaType', 'contentSchema',
+]);
+/** Mask credentials before preserving complete trusted IDs and UPPER_SNAKE diagnostics; redact opaque spans elsewhere. */
+function redactSecretLike({ text, diagnosticToolIds }) {
+    return redactSecrets({ input: text }, { redactPii: false })
+        .replace(LABELED_SECRET_RE, match => match.replace(/([:=]\s*)\S+$/, '$1[redacted]'))
+        .replace(/\[REDACTED:[^\]\r\n]+\]/g, '[redacted]')
+        // Trust whole dotted IDs so their components cannot become a general redaction bypass.
+        .replace(/[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g, token => diagnosticToolIds.has(token) ? token
+        : token.replace(OPAQUE_TOKEN_RE, match => NON_SECRET_TOKEN_RE.test(match) || DIAGNOSTIC_TOKENS.has(match) ? match : '[redacted]'));
 }
 /**
  * Strip terminal control sequences, redact anything that looks like a secret, and cap the
  * length of `text` — the one function every boundary that surfaces daemon/network-derived text
  * to stderr/stdout should route through first.
+ * Trusted diagnosticToolIds exempt complete IDs (including dots) only, after credential masking.
+ * @complexity O(n + t) local time/space for n text bytes and t trusted ID bytes.
  */
 export function sanitizeUntrustedText({ text }, options = {}) {
     const requestedLength = options.maxLength ?? DEFAULT_MAX_EXCERPT_LENGTH;
     const maxLength = Number.isFinite(requestedLength) ? Math.max(0, Math.floor(requestedLength)) : DEFAULT_MAX_EXCERPT_LENGTH;
-    const sanitized = redactSecretLike({ text: stripControlSequences({ text }) });
+    const sanitized = redactSecretLike({ text: stripControlSequences({ text }), diagnosticToolIds: new Set(options.diagnosticToolIds) });
     if (sanitized.length <= maxLength)
         return sanitized;
     // The marker is part of the output budget, including when the budget cannot fit the full marker.

package/dist/tool-exposure.d.ts

@@ -0,0 +1,79 @@
+/** Descriptor-only projections. Execution and current authorization remain with ToolExecutor. */
+import type { ToolDescriptor, ToolRegistry } from './tool-registry.js';
+export interface ToolNameMap {
+    wireNameFor(required: {
+        toolId: string;
+    }, optional?: Record<string, never>): string | undefined;
+    toolIdFor(required: {
+        wireName: string;
+    }, optional?: Record<string, never>): string | undefined;
+}
+/**
+ * Build a deterministic, collision-checked mapping to conservative 64-character wire names.
+ * @param required - Registry IDs; duplicates share one mapping.
+ * @param optional - Names already occupied by transport-owned tools.
+ * @returns Read-only forward/reverse lookups, with no descriptors or execution authority.
+ * @complexity O(n log n + l + c) time, O(n + l) space for n IDs, l characters and c collision probes.
+ */
+export declare function createToolNameMap({ toolIds }: {
+    toolIds: readonly string[];
+}, { reservedNames }?: {
+    reservedNames?: readonly string[];
+}): ToolNameMap;
+export interface ExposedToolDescriptor {
+    readonly wireName: string;
+    readonly descriptor: ToolDescriptor;
+}
+export interface ToolExposureSnapshot {
+    readonly revision: number;
+    readonly tools: readonly ExposedToolDescriptor[];
+    /** UTF-8 bytes of JSON-serialized input schemas, excluding absent schemas. */
+    readonly schemaBytes: number;
+}
+export interface ToolExposureSkipped {
+    readonly toolId: string;
+    readonly reason: 'not-found' | 'tool-limit' | 'schema-byte-limit';
+}
+export interface ToolExposurePromotion {
+    readonly snapshot: ToolExposureSnapshot;
+    readonly added: readonly string[];
+    readonly skipped: readonly ToolExposureSkipped[];
+}
+export interface ToolExposure {
+    /** Synchronous and idempotent; successful promotions are never evicted within this scope. */
+    promote(required: {
+        toolIds: readonly string[];
+    }, optional?: Record<string, never>): ToolExposurePromotion;
+    getSnapshot(required: Record<string, never>, optional?: Record<string, never>): ToolExposureSnapshot;
+    /** Resolves published names only. Callers must still invoke the authoritative executor. */
+    resolveToolId(required: {
+        wireName: string;
+    }, optional?: Record<string, never>): string | undefined;
+}
+export declare class ToolExposureError extends Error {
+    readonly code: 'invalid-limit' | 'invalid-descriptor';
+    constructor({ code }: {
+        code: 'invalid-limit' | 'invalid-descriptor';
+    }, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Create one run's bounded, append-only descriptor exposure over the existing registry.
+ * @param required - Descriptor source; a filtered registry view may enforce host visibility.
+ * @param optional - Count/schema-byte budgets and transport-owned reserved wire names.
+ * @returns Immutable snapshots and promotion deltas; no handlers, policies or execution path.
+ * @throws ToolExposureError for invalid limits or non-cloneable/non-serializable descriptors.
+ * @complexity Promotion O(r log r + s + b + c) time and O(r + s + b) space for r registry IDs,
+ * s exposed entries, b promoted descriptor bytes and c name collision probes. No I/O.
+ * @remarks Scope mutation is synchronous, so concurrent promise continuations cannot lose updates.
+ * Definitions stay pinned until this object is released; execution must recheck current registry policy.
+ */
+export declare function createToolExposure({ registry }: {
+    registry: Pick<ToolRegistry, 'list'>;
+}, { maxTools, maxSchemaBytes, reservedNames }?: {
+    maxTools?: number;
+    maxSchemaBytes?: number;
+    reservedNames?: readonly string[];
+}): ToolExposure;
+//# sourceMappingURL=tool-exposure.d.ts.map