@jini-ai/core 0.3.0 → 0.4.0

package/dist/redact.js

@@ -1,19 +1,23 @@
 /**
  * @module redact
  *
- * Lexical secret / PII scrubber for telemetry payloads. Verbatim port of
- * OD's `apps/daemon/src/redact.ts` — no product-identity strings or
- * hardcoded env vars in the original, so no genericization was needed.
+ * Lexical secret / PII scrubber for telemetry payloads. Originally a verbatim port of
+ * OD's daemon redactor — no product-identity strings or hardcoded env vars in the original,
+ * so no genericization was needed. The shared kernel now also covers the CLI/provider rule
+ * union and accepts explicit host secrets; the original categories and rationale stay here.
  *
  * Runs before any prompt or assistant text is sent to an external
- * observability sink. The patterns here are intentionally conservative:
+ * observability sink. The default policy is intentionally conservative:
  * each one matches a well-defined token shape with extremely low
  * false-positive rate (API keys have a fixed prefix, JWTs have the
  * "header.payload.signature" triple, credit-card matches go through a Luhn
  * check). What this file does NOT do — and any caller-facing copy must
  * reflect that — is detect names, addresses, business secrets, or anything
  * that requires understanding the meaning of the surrounding text. That's
- * an ML / LLM problem this module doesn't take on.
+ * an ML / LLM problem this module doesn't take on. Callers can explicitly opt
+ * into `policy: 'aggressive'` to also mask bare 20+ character opaque runs;
+ * that CLI-style heuristic trades identifier/path readability for broader masking
+ * and must never be used by diagnostics or secret-scan guards.
  *
  * Output format: every match is replaced by `[REDACTED:<kind>]` so a
  * reviewer reading a trace can see exactly which category fired without
@@ -27,6 +31,27 @@
  * - AWS access key shape: 'AKIA' + 16 uppercase alphanumerics.
  * - Luhn algorithm (credit cards): https://en.wikipedia.org/wiki/Luhn_algorithm
  */
+// Named once and reused (by SECRET_SHAPE_PATTERNS here and by the guard's ALLOWLIST) rather than repeated
+// as a literal in multiple places.
+export const PEM_PATTERN_NAME = "PEM private key block";
+// Share data between static scans and runtime redactors without importing a CLI entry point:
+// top-level argv/path handling in a scanner can crash a daemon that imports it. Keeping the
+// vocabulary dependency-free also avoids making core redaction depend on feature code.
+// Match each vendor's actual alphabet. Fixed-length patterns need lookaround boundaries so a
+// credential-shaped substring of a longer inert value is not mistaken for a complete secret.
+export const SECRET_SHAPE_PATTERNS = [
+    { name: "Google API key (AIza)", pattern: /(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{35}(?![A-Za-z0-9_-])/ },
+    { name: "Anthropic API key (sk-ant-)", pattern: /(?<![A-Za-z0-9_-])sk-ant-[A-Za-z0-9_-]{90,}/ },
+    { name: "generic sk- secret key (OpenAI-shaped)", pattern: /(?<![A-Za-z0-9_-])sk-[A-Za-z0-9]{40,}/ },
+    { name: "GitHub personal access token (classic, ghp_)", pattern: /(?<!\w)ghp_\w{36}(?!\w)/ },
+    { name: "GitHub OAuth token (gho_)", pattern: /(?<!\w)gho_\w{36}(?!\w)/ },
+    { name: "GitHub fine-grained PAT", pattern: /(?<!\w)github_pat_\w{80,}/ },
+    { name: "npm access token", pattern: /(?<!\w)npm_\w{36}(?!\w)/ },
+    { name: "Slack token", pattern: /(?<![A-Za-z0-9-])xox[baprs]-[A-Za-z0-9-]{12,}/ },
+    { name: "AWS access key ID", pattern: /(?<![0-9A-Z])AKIA[0-9A-Z]{16}(?![0-9A-Z])/ },
+    { 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-----/ },
+];
 // 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.
@@ -40,7 +65,7 @@ const PATTERNS = [
     // covers most "sk-..." secrets a user might paste into a prompt.
     { name: 'sk_key', regex: /\bsk-(?:proj-|live-|test-|ant-)?[A-Za-z0-9_-]{20,}\b/g },
     // GitHub personal / OAuth / server / user-server / refresh tokens.
-    { name: 'github_token', regex: /\bgh[opsur]_[A-Za-z0-9]{36,251}\b/g },
+    { name: 'github_token', regex: /\bgh[opsur]_[A-Za-z0-9]{36,}\b/g },
     // GitHub legacy 40-hex personal access tokens that ship with no prefix
     // are indistinguishable from a sha1 hash, so we don't try to match them
     // here — false positives would be brutal in commit logs / artifact slugs.
@@ -92,7 +117,7 @@ const API_KEY_HEADER = /(^|[^?&\w-])("?)(x-api-key|api-key|x-goog-api-key)\2(\s*
 const API_KEY_QUERY = /([?&](?:key|api_key|api-key)=)[^&#\s,;"']+/gi;
 // The length guard and the per-digit `d < 0 || d > 9` guard from the origin
 // were both dropped here (a documented deviation from the otherwise-verbatim
-// port — see source-map.md): `isLuhnValid` is private with exactly one call
+// port — see archived provenance ledger): `isLuhnValid` is private with exactly one call
 // site (the `CARD_CANDIDATE.replace` callbacks below), and `CARD_CANDIDATE`'s
 // own regex (`\b(?:\d[ -]?){12,18}\d\b`) already guarantees any string
 // reaching here is 13-19 characters, and the preceding `match.replace(/\D/g,
@@ -117,74 +142,120 @@ 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;
+// 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)$/;
+// 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
+// remains available to the global scan rather than being consumed beside the marker.
+const MASK_AWARE_LABELED_SECRET_RE = new RegExp(LABELED_SECRET_RE.source.replace(/\\S\+$/, "(?!Bearer\\s+\\[REDACTED:[^\\]]+\\](?:\\s|$))(?!\\[REDACTED:[^\\]]+\\][;&])(\\S+)"), LABELED_SECRET_RE.flags);
+// Provider failures also echo short bearer values. Exclude our own marker on subsequent passes.
+const SHORT_BEARER_RE = /(?<=Bearer\s+)[A-Za-z0-9_\-.+/=]+/gi;
+const PROVIDER_API_KEY_HEADER = /(x-api-key|api-key|x-goog-api-key)\s*[:=]\s*([^\s,;"']+)/gi;
+const PROVIDER_API_KEY_QUERY = /([?&]key=)([^&\s]+)/gi;
+// URL userinfo and signed query values have explicit credential context; unlike opaque runs,
+// they are safe to recognize in the conservative policy. Keep scheme/host and query names
+// readable for debugging without exposing credentials that authorize access to the resource.
+const URL_CREDENTIALS_RE = /(\b[a-z][a-z0-9+.-]*:\/\/)([^/\s?#@]+)@/gi;
+const SIGNED_QUERY_RE = /([?&](?:signature|sig|x-amz-signature|x-goog-signature|access_token|refresh_token)=)([^&#\s,;"']+)/gi;
+// Only an entire marker is already masked. A secret glued onto marker-like text still needs
+// masking; a substring check would preserve credential suffixes in echoed header/query values.
+function isMaskedValue(value) {
+    return /^["']?\[REDACTED:[^\]]+\]["']?$/.test(value);
+}
 /**
  * Returns `input` with every recognised secret / PII pattern replaced by a
  * `[REDACTED:<kind>]` marker. Idempotent — re-running on already redacted
- * text only matches new tokens.
+ * text only matches new tokens. Defaults to conservative; `{ policy: 'aggressive' }`
+ * additionally masks bare 20+ character opaque runs. Exact secrets and extra patterns
+ * are honored under either policy.
  *
  * Empty / non-string input passes through unchanged so the caller can use
  * this as a no-op on optional fields.
  */
-export function redactSecrets(input) {
-    if (!input)
-        return input;
-    let out = input;
-    for (const { name, regex } of PATTERNS) {
-        out = out.replace(regex, `[REDACTED:${name}]`);
-    }
-    out = out
-        .replace(API_KEY_HEADER, (_match, prefix, quote, name, separator, value) => redactApiKeyHeaderValue(prefix, quote, name, separator, value))
-        .replace(API_KEY_QUERY, '$1[REDACTED:api_key_query]');
-    out = out.replace(CARD_CANDIDATE, (match) => {
-        const digits = match.replace(/\D/g, '');
-        return isLuhnValid(digits) ? '[REDACTED:credit_card]' : match;
-    });
-    return out;
+export function redactSecrets({ input }, options = {}) {
+    return redactSecretsWithCounts({ input }, options).redacted;
 }
 /**
  * Same as {@link redactSecrets} but also returns per-category counts so the
  * caller can attach an audit summary to the trace metadata ('we stripped 2
  * keys + 1 email before send').
+ *
+ * Exact secrets run first, longest first: lexical rules or a shorter supplied secret must not
+ * split a known credential and leave a suffix behind. Opt-in aggressive opaque rules precede
+ * PII rules for the same reason (a numeric token can also contain phone/card candidates).
  */
-export function redactSecretsWithCounts(input) {
+export function redactSecretsWithCounts({ input }, options = {}) {
     const counts = {};
     if (!input)
         return { redacted: input, counts };
     let out = input;
-    for (const { name, regex } of PATTERNS) {
-        let matched = 0;
-        out = out.replace(regex, () => {
-            matched += 1;
-            return `[REDACTED:${name}]`;
-        });
-        if (matched > 0)
-            counts[name] = matched;
+    const marker = (name) => {
+        counts[name] = (counts[name] ?? 0) + 1;
+        return `[REDACTED:${name}]`;
+    };
+    const applyPattern = ({ name, regex }) => {
+        // 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) {
+        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);
     }
-    let apiKeyHeaderCount = 0;
+    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) => {
-        apiKeyHeaderCount += 1;
+        // 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);
     });
-    if (apiKeyHeaderCount > 0)
-        counts.api_key_header = apiKeyHeaderCount;
-    let apiKeyQueryCount = 0;
-    out = out.replace(API_KEY_QUERY, (_match, prefix) => {
-        apiKeyQueryCount += 1;
-        return `${prefix}[REDACTED:api_key_query]`;
+    // 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.
+    out = out.replace(PROVIDER_API_KEY_QUERY, (match, prefix, value) => isMaskedValue(value) ? match : `${prefix}${marker('api_key_query')}`);
+    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) => {
+        // 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 (apiKeyQueryCount > 0)
-        counts.api_key_query = apiKeyQueryCount;
-    let cardCount = 0;
+    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) => {
         const digits = match.replace(/\D/g, '');
-        if (isLuhnValid(digits)) {
-            cardCount += 1;
-            return '[REDACTED:credit_card]';
-        }
-        return match;
+        return isLuhnValid(digits) ? marker('credit_card') : match;
     });
-    if (cardCount > 0)
-        counts.credit_card = cardCount;
     return { redacted: out, counts };
 }
 //# sourceMappingURL=redact.js.map

package/dist/registration-kit.d.ts

@@ -0,0 +1,323 @@
+/**
+ * @file The cross-domain half of the agent-tool wiring split: everything a domain's own
+ * `tool-registrations.ts` needs that is NOT specific to that domain.
+ *
+ * Why this file exists at all. Every domain's wiring repeats the same five moves — index its
+ * catalog by id, read a handful of fields off `ctx.input`, run the tool's permission check,
+ * decorate a shape rejection with the published schema, and then loop the handler map into
+ * `ToolRegistration`s behind a build-time risk/schema gate. Those five moves were previously copied
+ * per domain inside one shared `assistant/tool-registrations.ts`, which is exactly why that file
+ * grew past 2000 lines and why three independent domain slices could not be developed in parallel
+ * without colliding on it. Each domain now owns a `tool-registrations.ts` next to its own code and
+ * imports the shared moves from here; `assistant/tool-registrations.ts` is reduced to the
+ * aggregator that assembles them.
+ *
+ * The membership test for anything in this file is "would a fourth, not-yet-written domain need
+ * it?". Domain-shaped things deliberately stay out: each domain's model-facing `to*View`
+ * projections, its dependency-bag builder, its own `DERIVED_RISK_BY_TOOL_ID` slice (a claim about
+ * that domain's handlers, so it is maintained where those handlers live), and its unwired-tool set.
+ *
+ * What is deliberately NOT abstracted here is the authorization DECISION. The host's permission helper
+ * performs a check a caller asks for; it never decides that a check is needed. The "one
+ * evaluator" rule is a per-tool fact — some domains self-enforce inside their service function and
+ * must NOT be double-checked here, others have no service-layer gate at all and must be checked at
+ * the handler — and that judgement stays recorded in the domain file next to the handler it
+ * describes, where a reviewer reading the handler can see it.
+ */
+import { type ToolExecutionOptions, type ToolHandler, type ToolRegistration } from "./tool-registry.js";
+import type { Result } from "./primitives/index.js";
+import type { AgentToolSideEffect, AgentToolDefinition } from "./agent-tools.js";
+/**
+ * Catalog entries use the kernel's AgentToolDefinition. The distinct deletion classification
+ * and its rationale live beside that contract in agent-tools.ts: every wiring gate compares
+ * classifications for equality, so deleting durable state cannot pass as a milder edit.
+ *
+ * This remains a structural minimum. A domain may tighten its own catalog, for example by
+ * requiring inputSchema for every wired entry or declaring authorization.orPermission for
+ * real OR gates. Neither requires importing another domain or loosening its own contract.
+ *
+ * A domain's independent classification of what its own handlers actually do, keyed by tool id.
+ *
+ * The point of the type is the point of the pattern: a tool's risk must not be self-declared. A
+ * catalog entry that quietly downgraded itself to `sideEffects:'none'` would otherwise become
+ * "safe" by editing one word in a file that carries no knowledge of which domain function runs.
+ * Each domain's `tool-registrations.ts` maintains its slice next to the handlers it describes, and
+ * {@link assertToolIsWirable} refuses to build when the two disagree. An id absent from the map
+ * cannot be wired at all, so the conservative default is "refuse", not "assume safe".
+ */
+export type DerivedRiskByToolId = ReadonlyMap<string, AgentToolSideEffect>;
+/**
+ * Audit provenance stamped onto every revision row a tool handler writes.
+ *
+ * A constant, not `ctx.principal`'s own kind, and that is the point: `ctx.principal.id` is the
+ * HUMAN admin's principal id — the host's proxy reads it from the browser session and stamps it
+ * into the run's `contextRef`, and the daemon hands it back to the handler. So a content-type change made by the assistant and one the same person made by clicking
+ * through the admin UI record an identical `actorId`. What distinguishes them is the path, and
+ * reaching a `tool-registrations.ts` handler IS the agent path — those handlers are only ever
+ * invoked by `@jini-ai/daemon`'s `ToolExecutor` during a run. `'agent'` is therefore a fact about
+ * the call site, not a default.
+ */
+export declare const AGENT_TOOL_PRINCIPAL_KIND: "agent";
+/**
+ * Actor-class rules that need a human confirmer.
+ *
+ * `confirmer-must-equal-own-delegatedBy` means "a human must confirm this, and the confirmer must
+ * be the principal who delegated". The kit never delivers that through `descriptor.requiresConfirmation`:
+ * without a host `ExecutionDelegate`, that flag parks the execution on a promise only
+ * `resumeConfirmation` can settle, and nothing would call it (unbounded, too, because
+ * `descriptor.timeoutMs`'s timer is armed only AFTER the confirmation await).
+ *
+ * So a tool carrying this rule is wirable only when its handler was built with
+ * {@link humanConfirmedHandler}, which asks the human through the host's own confirmation transport
+ * and runs the action only on an explicit yes. Any other handler fails the build.
+ */
+export declare const ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT: Set<string>;
+/**
+ * The human who confirmed, as {@link humanConfirmedHandler} hands it to `run`: always the run's own
+ * delegating principal (`ctx.principal.id`, see {@link AGENT_TOOL_PRINCIPAL_KIND}), always
+ * `kind: "user"`. The only thing a `run` step may pass to a confirm step as its confirmer.
+ */
+export interface HumanConfirmer {
+    readonly id: string;
+    readonly kind: "user";
+}
+/** What the host's transport reports back. Only exactly `confirmed: true` counts as a yes. */
+export type HumanConfirmationAnswer = {
+    confirmed: true;
+} | {
+    confirmed: false;
+    result: unknown;
+};
+/**
+ * Builds the one kind of handler a `confirmer-must-equal-own-delegatedBy` tool may be wired with
+ * (see {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}).
+ *
+ * The order is fixed here, not left to each domain: `prepare` (validate, pre-authorize, derive what
+ * the human will see) → `askHuman` (the host's transport, e.g. an MCP-UI dialog) → `run`, only when
+ * the answer is exactly `{ confirmed: true }`. The decision never comes from `ctx.input`, so nothing
+ * the model sends can stand in for the human. `run` gets the confirmer as the delegating human.
+ *
+ * @param steps.prepare - Reads input and derives what the human is asked about. May throw.
+ * @param steps.askHuman - Asks the human through the host's transport. Throws when no human can be
+ *   asked; a no-answer returns `{ confirmed: false, result }` and `result` is the tool's result.
+ * @param steps.run - Performs the action on a yes.
+ * Each step receives the invoking transport's execution options as its second argument so
+ * the confirmation dialog can be emitted before awaiting the human's answer.
+ * @returns A handler {@link assertToolIsWirable} accepts for a tool carrying the rule.
+ * @complexity O(1) plus the three steps.
+ */
+export declare function humanConfirmedHandler<TPrepared>(steps: {
+    prepare: (required: {
+        ctx: Parameters<ToolHandler>[0];
+    }, optional?: ToolExecutionOptions) => Promise<TPrepared>;
+    askHuman: (required: {
+        ctx: Parameters<ToolHandler>[0];
+        prepared: TPrepared;
+    }, optional?: ToolExecutionOptions) => Promise<HumanConfirmationAnswer>;
+    run: (required: {
+        ctx: Parameters<ToolHandler>[0];
+        prepared: TPrepared;
+        confirmer: HumanConfirmer;
+    }, optional?: ToolExecutionOptions) => Promise<unknown>;
+}, _optional?: Record<string, never>): ToolHandler;
+/**
+ * Indexes a domain catalog by tool id — the single lookup used for descriptors, risk metadata, and
+ * schema-bearing error messages.
+ *
+ * @param required.catalog - The domain's own `agent-tools.ts` catalog array.
+ * @returns The catalog keyed by `name`.
+ * @complexity O(n) once at module load, O(1) per subsequent lookup.
+ * @overallScore 100
+ */
+export declare function indexCatalogById<T extends {
+    name: string;
+}>(required: {
+    catalog: readonly T[];
+}, _optional?: Record<string, never>): ReadonlyMap<string, T>;
+export declare function isRecord(required: {
+    value: unknown;
+}, _optional?: Record<string, never>): required is {
+    value: Record<string, unknown>;
+};
+/** Narrows `ctx.input` to a record, refusing anything else. The first line of most handlers. */
+export declare function requireInputRecord(required: {
+    input: unknown;
+}, _optional?: Record<string, never>): Record<string, unknown>;
+export declare function requireString(required: {
+    input: Record<string, unknown>;
+    key: string;
+}, _optional?: Record<string, never>): string;
+export declare function requireNumber(requiredArgs: {
+    input: Record<string, unknown>;
+    key: string;
+}, optionalArgs?: Record<string, never>): number;
+export declare function requireObject(requiredArgs: {
+    input: Record<string, unknown>;
+    key: string;
+}, optionalArgs?: Record<string, never>): Record<string, unknown>;
+export declare function optionalString(required: {
+    input: Record<string, unknown>;
+    key: string;
+}, _optional?: Record<string, never>): string | undefined;
+export declare function optionalNumber(requiredArgs: {
+    input: Record<string, unknown>;
+    key: string;
+}, optionalArgs?: Record<string, never>): number | undefined;
+export declare function optionalBoolean(requiredArgs: {
+    input: Record<string, unknown>;
+    key: string;
+}, optionalArgs?: Record<string, never>): boolean | undefined;
+/**
+ * The reader for a parameterless tool: `ctx.input` may be omitted entirely or passed as `{}`,
+ * nothing else. Refusing a populated object is deliberate — silently ignoring keys would teach a
+ * model that a filter it invented was applied.
+ */
+export declare function requireNoInput(required: {
+    input: unknown;
+}, _optional?: Record<string, never>): void;
+/**
+ * Wraps a `Result<T, Error>`-returning domain call as a value: `ToolExecutor` treats a thrown error
+ * as a `'failed'` execution, so an `{ok:false}` becomes a throw rather than a silently-swallowed
+ * value.
+ */
+export declare function fromResult<T>(requiredArgs: {
+    fn: () => Promise<Result<T>>;
+}, optionalArgs?: Record<string, never>): Promise<T>;
+/**
+ * Re-throws a rejection with the tool's published `inputSchema` appended, so a model can correct
+ * its call in a single turn instead of guessing the rest of the shape from one field's complaint.
+ *
+ * `isShapeRejection` is the domain's own decision and has no default: only errors a DIFFERENT input
+ * would fix are decorated. A `ForbiddenError` or a slug conflict is not a shape problem, and
+ * appending a schema to one would be noise the model must read past — worse, it would imply the
+ * call is retryable when it is not.
+ *
+ * @param spec.toolId - The tool whose schema is published with the failure.
+ * @param spec.catalog - The domain catalog, consulted for that schema.
+ * @param spec.isShapeRejection - Predicate selecting the errors worth decorating.
+ * @param spec.fn - The domain call.
+ * @throws The original error unchanged when it is not a shape rejection, or a decorated `Error`
+ * when it is. A tool whose catalog entry publishes no schema still gets the retry-is-futile note.
+ * @complexity O(1) beyond the wrapped call, plus the schema's own serialization on the failure path.
+ * @overallScore 100
+ */
+export declare function withSchemaOnRejection<T>(spec: {
+    toolId: string;
+    catalog: ReadonlyMap<string, AgentToolDefinition>;
+    isShapeRejection: (required: {
+        error: unknown;
+    }) => boolean;
+    fn: () => Promise<T>;
+}, _optional?: Record<string, never>): Promise<T>;
+/**
+ * The synchronous half of {@link withSchemaOnRejection}, for a domain that validates BEFORE the
+ * call rather than inside it (content-types parses `fields` at a boundary parser, so its rejection
+ * never reaches a `try` around a domain call).
+ *
+ * @returns The `Error` to throw — returned rather than thrown so the caller's own `throw` keeps
+ * TypeScript's control-flow narrowing at the call site.
+ * @complexity O(s) in the serialized schema size, on the failure path only.
+ * @overallScore 100
+ */
+export declare function decorateWithSchema(params: {
+    toolId: string;
+    catalog: ReadonlyMap<string, AgentToolDefinition>;
+    message: string;
+}): 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,
+ * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
+ * its handler does not ask for.
+ *
+ * Throws rather than warning, and at registration time rather than call time: a metadata
+ * inconsistency is a developer error that should stop the daemon booting, not a runtime condition
+ * to degrade around.
+ *
+ * @param params.toolId - The wired tool id.
+ * @param params.catalogEntry - Its `agent-tools.ts` entry, the declared side of the comparison.
+ * @param params.derivedRisk - The wiring layer's independent classification, the derived side.
+ * @param params.handler - The handler being wired; checked only for a tool carrying a rule in
+ *   {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
+ * @throws {Error} If the tool is unclassified, misclassified, or needs a human confirmer its handler
+ *   does not ask for.
+ * @complexity O(1) — two map/set lookups.
+ * @overallScore 100
+ */
+export declare function assertToolIsWirable(params: {
+    toolId: string;
+    catalogEntry: AgentToolDefinition;
+    derivedRisk: DerivedRiskByToolId;
+}, optional?: {
+    handler?: ToolHandler;
+}): void;
+/**
+ * Turns one domain's handler map into `ToolRegistration`s, applying every build-time gate the
+ * wiring layer owes each tool, and tripwiring on any catalog entry that is neither wired nor
+ * explicitly declared unwired.
+ *
+ * The tripwire is the reason this is one shared function rather than a loop each domain copies.
+ * "Add a catalog entry, forget to wire it" is the failure this layer is meant to make impossible,
+ * and a per-domain copy of the check is a per-domain opportunity to get it subtly wrong — one of
+ * the copies this replaced omitted the schema assertion, another omitted the unwired-set escape
+ * hatch. Silence is never the outcome: an unwired entry either appears in `unwiredToolIds` with a
+ * recorded reason next to it, or the build fails.
+ *
+ * `policy.authorize` is a pass-through `'allow'` for every registration, and that is by design
+ * rather than an omission: each tool's permission is evaluated exactly once — inside its domain
+ * function for the self-enforcing domains, or by the handler's own host permission helper
+ * call for the domains whose gate lives in the route. A check here would be a SECOND evaluator of
+ * the same rule, and a `ToolPolicy`-only check would be bypassable by any future non-tool caller of
+ * the same domain function, which is precisely why the chokepoint owns the gate.
+ *
+ * `descriptor.requiresConfirmation` is deliberately never set — a tool that needs a human confirm
+ * asks inside its own {@link humanConfirmedHandler}; see
+ * {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
+ *
+ * @param spec.domain - Human-readable domain name, used only in failure messages.
+ * @param spec.catalogModule - Path of the catalog file, named in the drift message so the failure
+ * points at the file to edit.
+ * @param spec.catalog - That domain's catalog indexed by id (see {@link indexCatalogById}).
+ * @param spec.handlers - Tool id to handler. Registration order follows this map's key order.
+ * @param spec.derivedRisk - The domain's own risk classification (see {@link DerivedRiskByToolId}).
+ * @param optional.unwiredToolIds - Catalog ids deliberately not wired. Omit when the domain wires its
+ * entire catalog, which makes ANY unwired entry a build failure.
+ * @throws {Error} On catalog drift, an unclassified/misclassified tool, a wired tool publishing no
+ * `inputSchema`, or a catalog entry that is neither wired nor declared unwired.
+ * @complexity O(h + c) in the handler and catalog counts.
+ * @overallScore 100
+ */
+export declare function buildDomainRegistrations(spec: {
+    domain: string;
+    catalogModule: string;
+    catalog: ReadonlyMap<string, AgentToolDefinition>;
+    handlers: Record<string, ToolHandler>;
+    derivedRisk: DerivedRiskByToolId;
+}, optional?: {
+    unwiredToolIds?: ReadonlySet<string>;
+}): ToolRegistration[];
+/**
+ * Folds every domain's risk slice into the one map the assistant-level
+ * `assertRiskMetadataIsWirable(toolId, catalogEntry)` consults, refusing any id two domains both
+ * claim.
+ *
+ * That refusal is the structural answer to the failure this restructure was prompted by: three
+ * domain slices were developed in parallel, each checking its new ids only against the ids that
+ * existed before it started, so a name two of them both picked would have been discovered at
+ * runtime as a silently double-registered tool. A cross-domain id collision now fails the build.
+ * The one real collision in the current catalogs — `backup_create_restore_point`, declared by both
+ * Database and Recovery — passes because Recovery declares it unwired and therefore contributes no
+ * risk entry for it, which is exactly the resolution this check is meant to force.
+ *
+ * @param slices - Each domain's name (for the failure message) and its own risk map.
+ * @throws {Error} If two domains classify the same tool id.
+ * @complexity O(t) in the total classified-tool count.
+ * @overallScore 100
+ */
+export declare function mergeDerivedRiskMaps(requiredArgs: {
+    slices: readonly {
+        domain: string;
+        risk: DerivedRiskByToolId;
+    }[];
+}, optionalArgs?: Record<string, never>): DerivedRiskByToolId;
+//# sourceMappingURL=registration-kit.d.ts.map