@jini-ai/core 0.4.8 → 0.6.10

package/dist/records.d.ts

@@ -21,4 +21,28 @@ export declare function isNonArrayRecord(required: {
 }, _optional?: Record<string, never>): required is {
     value: Record<string, unknown>;
 };
+/** Strict equality over the supplied own, enumerable string fields; omitted fields are unconstrained.
+ * Memory adapters keep their scope and identity fields in this selector, including on deletes.
+ * @complexity O(k) time and space for k selector fields.
+ */
+export declare function matchesRecordFields<Row extends object>({ record, fields }: {
+    record: Row;
+    fields: Partial<Row>;
+}, _optional?: Record<string, never>): boolean;
+/** Replace the first matching record in place, or append; preserves order and reference semantics.
+ * @complexity O(nk) time and O(k) space for n records and k identity fields.
+ */
+export declare function upsertRecord<Row extends object>({ records, record, identity }: {
+    records: Row[];
+    record: Row;
+    identity: Partial<Row>;
+}, _optional?: Record<string, never>): void;
+/** Remove a keyed record only when its additional scope fields match.
+ * @complexity O(k) time and space for k selector fields, plus the map lookup.
+ */
+export declare function deleteMapRecord<Key, Row extends object>({ records, key, fields }: {
+    records: Map<Key, Row>;
+    key: Key;
+    fields: Partial<Row>;
+}, _optional?: Record<string, never>): void;
 //# sourceMappingURL=records.d.ts.map

package/dist/records.js

@@ -18,4 +18,29 @@ export function isRecord(required, _optional = {}) {
 export function isNonArrayRecord(required, _optional = {}) {
     return isRecord(required) && !Array.isArray(required.value);
 }
+/** Strict equality over the supplied own, enumerable string fields; omitted fields are unconstrained.
+ * Memory adapters keep their scope and identity fields in this selector, including on deletes.
+ * @complexity O(k) time and space for k selector fields.
+ */
+export function matchesRecordFields({ record, fields }, _optional = {}) {
+    return Object.keys(fields).every(key => record[key] === fields[key]);
+}
+/** Replace the first matching record in place, or append; preserves order and reference semantics.
+ * @complexity O(nk) time and O(k) space for n records and k identity fields.
+ */
+export function upsertRecord({ records, record, identity }, _optional = {}) {
+    const index = records.findIndex(candidate => matchesRecordFields({ record: candidate, fields: identity }));
+    if (index === -1)
+        records.push(record);
+    else
+        records[index] = record;
+}
+/** Remove a keyed record only when its additional scope fields match.
+ * @complexity O(k) time and space for k selector fields, plus the map lookup.
+ */
+export function deleteMapRecord({ records, key, fields }, _optional = {}) {
+    const record = records.get(key);
+    if (record && matchesRecordFields({ record, fields }))
+        records.delete(key);
+}
 //# sourceMappingURL=records.js.map

package/dist/redact.d.ts

@@ -38,12 +38,44 @@ export interface SecretShapePattern {
 }
 export declare const PEM_PATTERN_NAME = "PEM private key block";
 export declare const SECRET_SHAPE_PATTERNS: readonly SecretShapePattern[];
+/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
+export declare const AGENT_FAILURE_SECRET_SHAPE_RE: RegExp;
+/**
+ * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
+ * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
+ * a match). `secrets` is the owner's explicit example: whatever a site or app tree names its
+ * credentials folder (`sites/**\/secrets/`, `apps/admin/**\/secrets/`, or anywhere else), it never
+ * becomes reachable through this domain. A denied segment is refused by the guarded reader
+ * AND skipped entirely by the `fs_list_files` walk — its contents are never even enumerated,
+ * not merely refused once named. Besides `secrets`, the set names the
+ * well-known credential-store directories a home-directory `custom` root can expose: `.aws`
+ * (`credentials`), `.docker` (`config.json` with registry auth), `.kube` (`config`), and
+ * `gcloud`/`gh` for `.config/gcloud/application_default_credentials.json` and
+ * `.config/gh/hosts.yml`. Denied by SEGMENT rather than by leaf filename on purpose: `config`,
+ * `config.json`, and `hosts.yml` are generic names that appear harmlessly elsewhere, so denying the
+ * directory is the narrower of the two mistakes.
+ *
+ * A host's install-wide site-key directory (2026-09-24) needs the same protection; the host appends it.
+ * Production stores it beside individual site folders on a durable volume; local/dev stores
+ * it below the home directory, reachable through an operator-set `custom` root. Its key backs
+ * site-key administration, webhook/newsletter signing secrets, and permission checks, so the
+ * agent must never read it from disk. Denying the whole directory segment, rather than only
+ * a generated key filename, also prevents `fs_list_files` from enumerating its contents — the
+ * same "never even advertise it" property `secrets` gets above.
+ */
+export declare const CREDENTIAL_FILE_DENY_SEGMENTS: readonly string[];
+export declare const LOCAL_OWNER_PROXY_MARKER_PREFIXES: readonly string[];
+export declare const LOCAL_OWNER_PROXY_MARKER_HEADERS: readonly string[];
 export interface SecretRedactionPattern {
     name: string;
     regex: RegExp;
 }
 /** Optional caller-owned secrets and named lexical rules, without ambient credential lookup. */
 export interface SecretRedactionOptions {
+    /** Diagnostic text can retain addresses/numbers while using the same credential rules. Default true. */
+    redactPii?: boolean;
+    /** Exact trusted registration IDs; credential patterns always take precedence. */
+    diagnosticToolIds?: readonly string[];
     /** Conservative by default; aggressive also masks bare 20+ character opaque runs. */
     policy?: 'conservative' | 'aggressive';
     exactSecrets?: ReadonlyArray<string | undefined | null>;

package/dist/redact.js

@@ -52,6 +52,40 @@ export const SECRET_SHAPE_PATTERNS = [
     { name: "Fastmail app password (fm2_)", pattern: /(?<![A-Za-z0-9+/=])fm2_[A-Za-z0-9+/=]{20,}/ },
     { name: PEM_PATTERN_NAME, pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
 ];
+/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
+export const AGENT_FAILURE_SECRET_SHAPE_RE = /\b(?:AIza[\w-]+|AQ\.[\w.\/-]+|sk-[\w.-]+|gh[pousr]_[\w]+|github_pat_[\w]+|ya29\.[\w.-]+|eyJ[\w-]+\.[\w-]+(?:\.[\w-]+)?)/g;
+/**
+ * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
+ * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
+ * a match). `secrets` is the owner's explicit example: whatever a site or app tree names its
+ * credentials folder (`sites/**\/secrets/`, `apps/admin/**\/secrets/`, or anywhere else), it never
+ * becomes reachable through this domain. A denied segment is refused by the guarded reader
+ * AND skipped entirely by the `fs_list_files` walk — its contents are never even enumerated,
+ * not merely refused once named. Besides `secrets`, the set names the
+ * well-known credential-store directories a home-directory `custom` root can expose: `.aws`
+ * (`credentials`), `.docker` (`config.json` with registry auth), `.kube` (`config`), and
+ * `gcloud`/`gh` for `.config/gcloud/application_default_credentials.json` and
+ * `.config/gh/hosts.yml`. Denied by SEGMENT rather than by leaf filename on purpose: `config`,
+ * `config.json`, and `hosts.yml` are generic names that appear harmlessly elsewhere, so denying the
+ * directory is the narrower of the two mistakes.
+ *
+ * A host's install-wide site-key directory (2026-09-24) needs the same protection; the host appends it.
+ * Production stores it beside individual site folders on a durable volume; local/dev stores
+ * it below the home directory, reachable through an operator-set `custom` root. Its key backs
+ * site-key administration, webhook/newsletter signing secrets, and permission checks, so the
+ * agent must never read it from disk. Denying the whole directory segment, rather than only
+ * a generated key filename, also prevents `fs_list_files` from enumerating its contents — the
+ * same "never even advertise it" property `secrets` gets above.
+ */
+// Generic credential-store segments only. A host adds its own product-specific key directory
+// (e.g. its install-wide site-key folder) when it builds its deny-list; core stays product-neutral.
+export const CREDENTIAL_FILE_DENY_SEGMENTS = ["secrets", ".aws", ".docker", ".kube", "gcloud", "gh"];
+// A local tunnel has a loopback socket and may rewrite Host; refuse marker presence, even empty.
+export const LOCAL_OWNER_PROXY_MARKER_PREFIXES = ["x-forwarded-", "x-envoy-", "x-ms-"];
+export const LOCAL_OWNER_PROXY_MARKER_HEADERS = [
+    "forwarded", "x-real-ip", "via", "cf-connecting-ip", "true-client-ip", "x-original-host",
+    "x-client-ip", "x-cluster-client-ip", "fastly-client-ip", "tailscale-user-login", "x-original-forwarded-for",
+];
 // Order matters: list specific rules before more general ones. Langfuse
 // keys (`sk-lf-...`) would otherwise be eaten by the generic `sk-...`
 // rule and labeled as a generic OpenAI-style key.
@@ -139,21 +173,17 @@ function isLuhnValid(digits) {
     }
     return sum % 10 === 0;
 }
-function redactApiKeyHeaderValue(prefix, quote, name, separator, value) {
-    const redactedValue = value.startsWith('"') ? '"[REDACTED:api_key_header]"' : '[REDACTED:api_key_header]';
-    return `${prefix}${quote}${name}${quote}${separator}${redactedValue}`;
-}
 // A labeled credential has its value masked even when too short to have a vendor token shape.
 // Bare long opaque runs are opt-in CLI heuristics: UUIDs, hashes, model IDs and path segments
 // share that alphabet, so the default telemetry policy must leave them readable. Whole
-// correlation IDs and the delegated-tool route stay readable even in aggressive mode;
+// correlation IDs, UPPER_SNAKE diagnostic codes and the delegated-tool route stay readable even in aggressive mode;
 // appending secret characters defeats that exception. The host's ERR-XXXX-XXXX-XXXX-XXXX
 // correlation ID uses uppercase hex and is meant to reach the model and be quoted to an
 // operator; delegated-tool-calls is the route segment named in delegated tool failures.
 // Matching the ENTIRE run keeps a secret glued onto either spelling redactable.
 export const LABELED_SECRET_RE = /\b(authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie)\b\s*[:=]\s*\S+/gi;
 export const OPAQUE_TOKEN_RE = /[A-Za-z0-9_-]{20,}/g;
-export const NON_SECRET_TOKEN_RE = /^(?:ERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}|delegated-tool-calls)$/;
+export const NON_SECRET_TOKEN_RE = /^(?:ERR-[0-9A-F]{4}(?:-[0-9A-F]{4}){3}|delegated-tool-calls|[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)$/;
 // Runtime markers must survive a second pass; the bounded sanitizer deliberately retains
 // its historical lowercase marker contract and uses the unmodified lexical vocabulary.
 // Reject a masked header/query value before matching, so a following field's credential
@@ -199,39 +229,71 @@ export function redactSecretsWithCounts({ input }, options = {}) {
     const counts = {};
     if (!input)
         return { redacted: input, counts };
-    let out = input;
     const marker = (name) => {
         counts[name] = (counts[name] ?? 0) + 1;
         return `[REDACTED:${name}]`;
     };
-    const applyPattern = ({ name, regex }) => {
+    let out = redactExactSecrets({ text: input, marker, secrets: options.exactSecrets ?? [] });
+    out = redactUrlCredentials({ text: out, marker });
+    out = applyPatterns({ text: out, marker, patterns: credentialPatterns(options.extraPatterns ?? []) });
+    out = redactKeyedCredentials({ text: out, marker });
+    if (options.policy === 'aggressive') {
+        const trustedIds = new Set(options.diagnosticToolIds);
+        out = out.replace(/[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g, token => trustedIds.has(token) ? token
+            : token.replace(OPAQUE_TOKEN_RE, match => NON_SECRET_TOKEN_RE.test(match) ? match : marker('opaque_token')));
+    }
+    if (options.redactPii !== false)
+        out = redactPii({ text: out, marker });
+    return { redacted: out, counts };
+}
+// PII rules run last (after credential and opt-in opaque rules) and only when PII redaction is on;
+// splitting once keeps each list in PATTERNS order.
+const PII_PATTERN_NAMES = ['email', 'ipv4', 'phone'];
+const NON_PII_PATTERNS = PATTERNS.filter((pattern) => !PII_PATTERN_NAMES.includes(pattern.name));
+const PII_PATTERNS = PATTERNS.filter((pattern) => PII_PATTERN_NAMES.includes(pattern.name));
+/** Built-in credential rules, then the static-scan shapes (labeled `credential`), then the caller's extra rules. */
+function credentialPatterns(extraPatterns) {
+    return [
+        ...NON_PII_PATTERNS,
+        ...SECRET_SHAPE_PATTERNS.map((shape) => ({ name: 'credential', regex: shape.pattern })),
+        ...extraPatterns,
+    ];
+}
+function applyPatterns({ text, marker, patterns }) {
+    let out = text;
+    for (const { name, regex } of patterns) {
         // Clone host/global regexes so lastIndex state never leaks across requests. Named extra
         // patterns use the same global replacement contract as the built-in vocabulary.
         const flags = regex.flags.includes('g') ? regex.flags : `${regex.flags}g`;
         out = out.replace(new RegExp(regex.source, flags), () => marker(name));
-    };
-    const secrets = [...new Set((options.exactSecrets ?? []).filter((secret) => typeof secret === 'string' && secret.length > 0))].sort((a, b) => b.length - a.length);
-    for (const secret of secrets) {
+    }
+    return out;
+}
+/** Masks caller-supplied secrets verbatim, longest first, ignoring empty and non-string entries. */
+function redactExactSecrets({ text, marker, secrets }) {
+    const usable = [...new Set(secrets.filter((secret) => typeof secret === 'string' && secret.length > 0))].sort((a, b) => b.length - a.length);
+    let out = text;
+    for (const secret of usable) {
         const escaped = secret.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         out = out.replace(new RegExp(escaped, 'g'), () => marker('exact_secret'));
     }
-    out = out.replace(URL_CREDENTIALS_RE, (match, scheme, userinfo) => isMaskedValue(userinfo) ? match : `${scheme}${marker('url_credentials')}@`);
-    out = out.replace(SIGNED_QUERY_RE, (match, prefix, value) => isMaskedValue(value) ? match : `${prefix}${marker('signed_query')}`);
-    const piiNames = new Set(['email', 'ipv4', 'phone']);
-    for (const pattern of PATTERNS) {
-        if (!piiNames.has(pattern.name))
-            applyPattern(pattern);
-    }
-    for (const shape of SECRET_SHAPE_PATTERNS)
-        applyPattern({ name: 'credential', regex: shape.pattern });
-    for (const pattern of options.extraPatterns ?? [])
-        applyPattern(pattern);
-    out = out.replace(API_KEY_HEADER, (_match, prefix, quote, name, separator, value) => {
+    return out;
+}
+/** URL userinfo and signed query values: credentials recognized by their URL context. */
+function redactUrlCredentials({ text, marker }) {
+    return text
+        .replace(URL_CREDENTIALS_RE, (match, scheme, userinfo) => isMaskedValue(userinfo) ? match : `${scheme}${marker('url_credentials')}@`)
+        .replace(SIGNED_QUERY_RE, (match, prefix, value) => isMaskedValue(value) ? match : `${prefix}${marker('signed_query')}`);
+}
+/** Values named by a header, query parameter, bearer prefix or credential label. */
+function redactKeyedCredentials({ text, marker }) {
+    let out = text.replace(API_KEY_HEADER, (_match, prefix, quote, name, separator, value) => {
         // Already masked values are not new credentials and should not inflate the audit count.
         if (isMaskedValue(value))
             return `${prefix}${quote}${name}${quote}${separator}${value}`;
         marker('api_key_header');
-        return redactApiKeyHeaderValue(prefix, quote, name, separator, value);
+        const redactedValue = value.startsWith('"') ? '"[REDACTED:api_key_header]"' : '[REDACTED:api_key_header]';
+        return `${prefix}${quote}${name}${quote}${separator}${redactedValue}`;
     });
     // The provider rule includes a query fragment in an echoed key; mask that whole value
     // before the narrower core query rule can split it and leave a credential suffix behind.
@@ -239,24 +301,19 @@ export function redactSecretsWithCounts({ input }, options = {}) {
     out = out.replace(API_KEY_QUERY, (match, prefix) => isMaskedValue(match.slice(prefix.length)) ? match : `${prefix}${marker('api_key_query')}`);
     out = out.replace(SHORT_BEARER_RE, () => marker('bearer_token'));
     out = out.replace(PROVIDER_API_KEY_HEADER, (match, name, value) => isMaskedValue(value) ? match : `${name}: ${marker('api_key_header')}`);
-    out = out.replace(MASK_AWARE_LABELED_SECRET_RE, (match, _label, value) => {
+    return out.replace(MASK_AWARE_LABELED_SECRET_RE, (match, _label, value) => {
         // Replace only the captured value, retaining labels even when no whitespace separates
         // them. Glued credential suffixes fail the complete-marker check and remain maskable.
         if (isMaskedValue(value))
             return match;
         return `${match.slice(0, -value.length)}${marker('labeled_secret')}`;
     });
-    if (options.policy === 'aggressive') {
-        out = out.replace(OPAQUE_TOKEN_RE, (match) => NON_SECRET_TOKEN_RE.test(match) ? match : marker('opaque_token'));
-    }
-    for (const pattern of PATTERNS) {
-        if (piiNames.has(pattern.name))
-            applyPattern(pattern);
-    }
-    out = out.replace(CARD_CANDIDATE, (match) => {
+}
+/** Email/IPv4/phone rules, then Luhn-checked card candidates. */
+function redactPii({ text, marker }) {
+    return applyPatterns({ text, marker, patterns: PII_PATTERNS }).replace(CARD_CANDIDATE, (match) => {
         const digits = match.replace(/\D/g, '');
         return isLuhnValid(digits) ? marker('credit_card') : match;
     });
-    return { redacted: out, counts };
 }
 //# sourceMappingURL=redact.js.map

package/dist/registration-kit.d.ts

@@ -140,14 +140,16 @@ export declare function requireInputRecord(required: {
     input: unknown;
 }, _optional?: Record<string, never>): Record<string, unknown>;
 /**
- * Reads a required non-empty string, with received-key hints when the field is missing.
- * @throws {ToolInputError} If the field is missing, empty, or not a string.
+ * Reads a required string, non-empty by default; allowEmpty supports literal text deletion.
+ * @throws {ToolInputError} If the field is missing, not a string, or empty without allowEmpty.
  * @complexity O(k) for k input keys on a missing-field rejection; otherwise O(1).
  */
 export declare function requireString(required: {
     input: Record<string, unknown>;
     key: string;
-}, _optional?: Record<string, never>): string;
+}, { allowEmpty }?: {
+    allowEmpty?: boolean;
+}): string;
 export declare function requireNumber(requiredArgs: {
     input: Record<string, unknown>;
     key: string;
@@ -261,7 +263,7 @@ export declare function decorateWithSchema(params: {
 }): Error;
 /**
  * Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
- * `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
+ * authorization permission is missing, whose `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
  * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
  * its handler does not ask for.
  *
@@ -327,6 +329,7 @@ export declare function buildDomainRegistrations(spec: {
     catalogModule: string;
     catalog: ReadonlyMap<string, AgentToolDefinition>;
     handlers: Record<string, ToolHandler>;
+    inputNormalizers?: Readonly<Record<string, import('./tool-input-normalization.js').ToolInputNormalizer>>;
     derivedRisk: DerivedRiskByToolId;
     /** Host vocabulary and reviewed action policy; risk remains independently checked above. */
     metadata?: import('./tool-metadata.js').ToolMetadataById;

package/dist/registration-kit.js

@@ -124,43 +124,37 @@ function missingFieldHint(required, _optional = {}) {
     }
     return hint;
 }
+/** The refusal for a required field: the expected kind, plus received-key hints only when the key is absent. */
+function requiredFieldError(required, _optional = {}) {
+    const { input, key, kind } = required;
+    const hint = input[key] === undefined ? missingFieldHint({ input }) : "";
+    return new ToolInputError({ message: `'${key}' (${kind}) is required${hint}` });
+}
 /**
- * Reads a required non-empty string, with received-key hints when the field is missing.
- * @throws {ToolInputError} If the field is missing, empty, or not a string.
+ * Reads a required string, non-empty by default; allowEmpty supports literal text deletion.
+ * @throws {ToolInputError} If the field is missing, not a string, or empty without allowEmpty.
  * @complexity O(k) for k input keys on a missing-field rejection; otherwise O(1).
  */
-export function requireString(required, _optional = {}) {
+export function requireString(required, { allowEmpty = false } = {}) {
     const { input, key } = required;
     const value = input[key];
-    if (typeof value !== "string" || value.length === 0) {
-        let message = `'${key}' (non-empty string) is required`;
-        if (value === undefined)
-            message += missingFieldHint({ input });
-        throw new ToolInputError({ message });
-    }
+    if (typeof value !== "string" || (!allowEmpty && value.length === 0))
+        throw requiredFieldError({ input, key, kind: allowEmpty ? "string" : "non-empty string" });
     return value;
 }
 export function requireNumber(requiredArgs, optionalArgs = {}) {
     const { input, key } = requiredArgs;
     const value = input[key];
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        let message = `'${key}' (number) is required`;
-        if (value === undefined)
-            message += missingFieldHint({ input });
-        throw new ToolInputError({ message });
-    }
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw requiredFieldError({ input, key, kind: "number" });
     return value;
 }
 export function requireObject(requiredArgs, optionalArgs = {}) {
     const { input, key } = requiredArgs;
     const value = input[key];
     const candidate = { value };
-    if (!isRecord(candidate) || Array.isArray(candidate.value)) {
-        let message = `'${key}' (object) is required`;
-        if (value === undefined)
-            message += missingFieldHint({ input });
-        throw new ToolInputError({ message });
-    }
+    if (!isRecord(candidate) || Array.isArray(candidate.value))
+        throw requiredFieldError({ input, key, kind: "object" });
     return candidate.value;
 }
 export function optionalString(required, _optional = {}) {
@@ -319,7 +313,7 @@ export function decorateWithSchema(params) {
 // ---------------------------------------------------------------------------
 /**
  * Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
- * `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
+ * authorization permission is missing, whose `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
  * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
  * its handler does not ask for.
  *
@@ -339,17 +333,34 @@ export function decorateWithSchema(params) {
  */
 export function assertToolIsWirable(params, optional = {}) {
     const { toolId, catalogEntry } = params;
-    const derived = params.derivedRisk.get(toolId);
+    if (!hasDeclaredPermission({ catalogEntry })) {
+        throw new Error(`tool-registrations: '${toolId}' must declare an authorization permission before wiring`);
+    }
+    assertRiskIsCorroborated({ toolId, catalogEntry, derivedRisk: params.derivedRisk });
+    if (needsHumanConfirmer({ catalogEntry }) && !isHumanConfirmedHandler({ handler: optional.handler })) {
+        throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which needs a human confirmer — build its handler with humanConfirmedHandler so a human answers through the host's confirmation transport (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
+    }
+}
+/** A non-blank string permission; a malformed catalog (no authorization object) counts as none. */
+function hasDeclaredPermission({ catalogEntry }) {
+    const permission = catalogEntry.authorization?.permission;
+    return typeof permission === "string" && permission.trim().length > 0;
+}
+/** Refuses an unclassified tool, then a declaration the wiring layer's own classification contradicts. */
+function assertRiskIsCorroborated({ toolId, catalogEntry, derivedRisk }) {
+    const derived = derivedRisk.get(toolId);
     if (!derived) {
         throw new Error(`tool-registrations: '${toolId}' has no entry in DERIVED_RISK_BY_TOOL_ID — classify what its handler actually does before wiring it (unknown operations are refused, never assumed safe)`);
     }
     if (derived !== catalogEntry.sideEffects) {
         throw new Error(`tool-registrations: '${toolId}' declares sideEffects '${catalogEntry.sideEffects}' but this layer derives '${derived}' from what its handler calls — reconcile the two rather than trusting the declaration`);
     }
-    const needsHuman = catalogEntry.actorClassRule && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule);
-    if (needsHuman && !(optional.handler && HUMAN_CONFIRMED_HANDLERS.has(optional.handler))) {
-        throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which needs a human confirmer — build its handler with humanConfirmedHandler so a human answers through the host's confirmation transport (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
-    }
+}
+function needsHumanConfirmer({ catalogEntry }) {
+    return catalogEntry.actorClassRule !== undefined && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule);
+}
+function isHumanConfirmedHandler({ handler }) {
+    return handler !== undefined && HUMAN_CONFIRMED_HANDLERS.has(handler);
 }
 /**
  * Turns one domain's handler map into `ToolRegistration`s, applying every build-time gate the
@@ -388,48 +399,56 @@ export function assertToolIsWirable(params, optional = {}) {
  * @overallScore 100
  */
 export function buildDomainRegistrations(spec, optional = {}) {
-    const registrations = [];
-    for (const [id, handler] of Object.entries(spec.handlers)) {
-        const catalogEntry = spec.catalog.get(id);
-        if (!catalogEntry) {
-            throw new Error(`tool-registrations: ${spec.domain} catalog has no entry named '${id}' — ${spec.catalogModule} drifted`);
-        }
-        assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk }, { handler });
-        if (!catalogEntry.inputSchema) {
-            throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
-        }
-        const metadata = catalogEntry.metadata ?? toolMetadataFor({ toolId: id, metadata: spec.metadata });
-        registrations.push({
-            descriptor: {
-                id,
-                description: catalogEntry.description,
-                inputSchema: catalogEntry.inputSchema,
-                ...(metadata ? { metadata } : {}),
-                // The ONE place a domain's declared risk becomes the descriptor flag every read-only gate
-                // reads (`@jini-ai/core`'s `isReadOnlyTool`). Placed here rather than in each domain's
-                // `tool-registrations.ts` for the same reason the drift tripwire is: twelve copies of this
-                // line is twelve chances for one to say something different. Change what counts as
-                // read-only and every domain follows.
-                //
-                // Safe to derive from the declaration only because `assertToolIsWirable` has ALREADY run
-                // two lines above and refused any tool whose declared `sideEffects` disagrees with the
-                // wiring layer's own `DERIVED_RISK_BY_TOOL_ID` classification — so by this point the
-                // declaration has been independently corroborated, and a catalog entry cannot make itself
-                // read-only by editing one word.
-                readOnly: catalogEntry.sideEffects === "none",
-            },
-            handler,
-            policy: { authorize: () => "allow" },
-        });
+    const registrations = Object.entries(spec.handlers).map(([id, handler]) => registrationFor({ spec, id, handler }));
+    assertEveryEntryIsWiredOrDeclared({ spec }, optional);
+    return registrations;
+}
+/** One wired tool: every build-time gate first, then the descriptor/handler/policy triple. */
+function registrationFor({ spec, id, handler }) {
+    const catalogEntry = spec.catalog.get(id);
+    if (!catalogEntry) {
+        throw new Error(`tool-registrations: ${spec.domain} catalog has no entry named '${id}' — ${spec.catalogModule} drifted`);
+    }
+    assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk }, { handler });
+    if (!catalogEntry.inputSchema) {
+        throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
     }
+    const metadata = catalogEntry.metadata ?? toolMetadataFor({ toolId: id, metadata: spec.metadata });
+    const normalizeInput = spec.inputNormalizers?.[id];
+    return {
+        descriptor: {
+            id,
+            description: catalogEntry.description,
+            inputSchema: catalogEntry.inputSchema,
+            ...(metadata ? { metadata } : {}),
+            // The ONE place a domain's declared risk becomes the descriptor flag every read-only gate
+            // reads (`@jini-ai/core`'s `isReadOnlyTool`). Placed here rather than in each domain's
+            // `tool-registrations.ts` for the same reason the drift tripwire is: twelve copies of this
+            // line is twelve chances for one to say something different. Change what counts as
+            // read-only and every domain follows.
+            //
+            // Safe to derive from the declaration only because `assertToolIsWirable` has ALREADY run
+            // two lines above and refused any tool whose declared `sideEffects` disagrees with the
+            // wiring layer's own `DERIVED_RISK_BY_TOOL_ID` classification — so by this point the
+            // declaration has been independently corroborated, and a catalog entry cannot make itself
+            // read-only by editing one word.
+            readOnly: catalogEntry.sideEffects === "none",
+            sideEffects: catalogEntry.sideEffects,
+        },
+        handler,
+        ...(normalizeInput ? { normalizeInput } : {}),
+        policy: { authorize: () => "allow" },
+    };
+}
+/** The tripwire: a catalog entry is either wired or recorded as deliberately unwired, never silently neither. */
+function assertEveryEntryIsWiredOrDeclared({ spec }, { unwiredToolIds } = {}) {
     for (const id of spec.catalog.keys()) {
         if (id in spec.handlers)
             continue;
-        if (optional.unwiredToolIds?.has(id))
+        if (unwiredToolIds?.has(id))
             continue;
         throw new Error(`tool-registrations: ${spec.domain} catalog entry '${id}' is neither wired nor declared unwired — wire a handler for it, or add it to that domain's unwired set with the reason recorded next to it`);
     }
-    return registrations;
 }
 /**
  * Folds every domain's risk slice into the one map the assistant-level

package/dist/settings/agent-value-write-tools.d.ts

@@ -1,6 +1,8 @@
 import { type ToolExecutionContext, type ToolHandler } from "../tool-registry.js";
 import type { JsonValue } from "../primitives/index.js";
+import { type AgentSettingWriteRule } from "./agent-write-denylist.js";
 import type { SettingsToolDeps } from "./tool-registrations.js";
+import { type SettingsWriteServiceDeps } from "./write-service.js";
 export type SettingsValueWriteToolId = "settings_set_value" | "settings_clear_value";
 /** Host-only port. This request is never an agent input and only the host's authenticated
  * human transport or a persisted human identity grant may answer it. Model input never authorizes it. */
@@ -14,6 +16,23 @@ export interface SettingsWriteConfirmation {
     value?: JsonValue;
     reason: string;
 }
+/** The effective agent-write key policy: package denials plus host extensions (never agent input),
+ * and the host's confirmation policy (replacing the package defaults) plus host extensions. O(r). */
+export declare function agentWriteRules(deps: SettingsToolDeps): {
+    denied: AgentSettingWriteRule[];
+    confirmation: AgentSettingWriteRule[];
+};
+/**
+ * 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 `tool-registrations.ts`'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.
+ */
+export declare function toWriteDeps(routeDeps: SettingsToolDeps): SettingsWriteServiceDeps;
 /** Builds one value-write handler. Effects: authorize -> raw read -> optional human card ->
  * service write -> result. The service rechecks authorization and performs its normal transaction.
  * @complexity O(value size + rule count) plus bounded repository calls and a human wait.