@jini-ai/core 0.4.7 → 0.4.9

package/dist/primitives/paths.js

@@ -1,13 +1,11 @@
-/** Pure lexical normalization of an already absolute path; no cwd, filesystem or symlink access. */
-function normalizeAbsolutePath(value, separator) {
-    const path = separator === '\\' ? value.replace(/\\/g, '/') : value;
-    const drive = separator === '\\' ? /^[A-Za-z]:\//.exec(path)?.[0] : undefined;
-    const unc = separator === '\\' ? /^\/\/[^/]+\/[^/]+(?:\/|$)/.exec(path)?.[0] : undefined;
-    const prefix = drive ?? unc ?? (path.startsWith('/') ? '/' : undefined);
-    if (!prefix)
-        throw new RangeError('pathContains requires resolved absolute paths');
+/** Root of an already `/`-separated Windows path: a drive root (`C:/`) or a UNC share root. */
+function windowsRoot(path) {
+    return /^[A-Za-z]:\//.exec(path)?.[0] ?? /^\/\/[^/]+\/[^/]+(?:\/|$)/.exec(path)?.[0];
+}
+/** Lexically resolve `.` and `..` segments; `..` never climbs above the root. */
+function resolveSegments(rest) {
     const segments = [];
-    for (const segment of path.slice(prefix.length).split('/')) {
+    for (const segment of rest.split('/')) {
         if (!segment || segment === '.')
             continue;
         if (segment === '..')
@@ -15,7 +13,16 @@ function normalizeAbsolutePath(value, separator) {
         else
             segments.push(segment);
     }
-    return prefix.replace(/\/+$/, '') + '/' + segments.join('/');
+    return segments;
+}
+/** Pure lexical normalization of an already absolute path; no cwd, filesystem or symlink access. */
+function normalizeAbsolutePath(value, separator) {
+    const windows = separator === '\\';
+    const path = windows ? value.replace(/\\/g, '/') : value;
+    const prefix = (windows ? windowsRoot(path) : undefined) ?? (path.startsWith('/') ? '/' : undefined);
+    if (!prefix)
+        throw new RangeError('pathContains requires resolved absolute paths');
+    return prefix.replace(/\/+$/, '') + '/' + resolveSegments(path.slice(prefix.length)).join('/');
 }
 /**
  * Check lexical containment using whole directory segments, including equality.

package/dist/primitives/tasks.d.ts

@@ -0,0 +1,10 @@
+/** Append work to a fulfilled serial tail and report failures without rejecting the next tail.
+ * The observer owns failure policy and must not throw. Callers retain the returned tail to drain.
+ * @complexity O(1) scheduling time and space per task, excluding task work.
+ */
+export declare function appendSerialTask({ previous, task, onError }: {
+    previous: Promise<void>;
+    task: () => Promise<unknown>;
+    onError: (error: unknown) => void;
+}, _optional?: Record<string, never>): Promise<void>;
+//# sourceMappingURL=tasks.d.ts.map

package/dist/primitives/tasks.js

@@ -0,0 +1,8 @@
+/** Append work to a fulfilled serial tail and report failures without rejecting the next tail.
+ * The observer owns failure policy and must not throw. Callers retain the returned tail to drain.
+ * @complexity O(1) scheduling time and space per task, excluding task work.
+ */
+export function appendSerialTask({ previous, task, onError }, _optional = {}) {
+    return previous.then(task).then(() => undefined, onError);
+}
+//# sourceMappingURL=tasks.js.map

package/dist/provider-catalog.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Neutral catalog contracts consumed by UI and implemented by host adapters.
+ * Vendor identities, aliases and endpoint defaults belong to integrations.
+ */
+/** UI catalog identity policy. Operations are pure, synchronous and must agree on IDs.
+ * Normalization returns a new map, preserves values, and resolves alias collisions
+ * deterministically. The host keeps one policy for the lifetime of a mounted tab.
+ *
+ * @example
+ * MediaProvidersTab({ port, catalog, catalogPolicy: mediaProviderCatalogPolicy });
+ */
+export interface MediaProviderCatalogPolicy {
+    /** Canonicalize catalog entries, pinned IDs, edits and clears; preserve unknown IDs. */
+    canonicalMediaProviderId(input: {
+        id: string;
+    }, options?: Record<string, never>): string;
+    /** Normalize initial state and daemon replies before reconciliation. Canonical entries win aliases. */
+    normalizeMediaProviderMap<T>(input: {
+        providers: Readonly<Record<string, T>>;
+    }, options?: Record<string, never>): Record<string, T>;
+}
+/**
+ * One selectable provider in the host-supplied catalog.
+ */
+export interface MediaProviderOption {
+    id: string;
+    label: string;
+    /** Prefilled when the operator picks this provider and typed nothing. */
+    defaultBaseUrl?: string;
+    /** Model ids this provider advertises. A host that discovers models at
+     *  runtime can leave this empty. */
+    models?: readonly string[];
+}
+/** Whether a preset appears in the protocol or gateway chip row. */
+export type ProviderPresetKind = 'protocol' | 'gateway';
+/** One host-supplied endpoint preset, parameterized by the consumer's wire protocols. */
+export interface ProviderPreset<Protocol extends string = string> {
+    id: string;
+    title: string;
+    protocol: Protocol;
+    baseUrl: string;
+    /** Ranked suggestions shown in the model field. Never authoritative — a
+     *  host with live model discovery should pass `ExecutionPort.listModels`. */
+    preferredModels: readonly string[];
+    kind?: ProviderPresetKind;
+    /** Fixed-origin gateways resolve their base URL themselves, so the Base URL
+     *  field is hidden rather than shown-and-ignored (origin: `isFixedOriginGateway`). */
+    fixedOrigin?: boolean;
+    /** Some local/self-hosted endpoints need no bearer credential. Defaults to
+     *  `true` — i.e. an API key is required unless a preset opts out. */
+    requiresApiKey?: boolean;
+    /** Optional "Get key" deep link rendered beside the API-key field. */
+    apiKeyConsoleUrl?: string;
+    /**
+     * The literal prefix that positively identifies a pasted key as belonging to THIS provider —
+     * `'AIza'` for Google, `'sk-ant-'` for Anthropic. Omit it for a vendor whose keys carry no
+     * distinguishing prefix (Azure OpenAI's are bare hex) rather than inventing one.
+     *
+     * Read in exactly one direction: to recognise a key as SOMEONE ELSE'S. It is deliberately NOT an
+     * allowlist, and no code may ask "does the selected preset's key match this?" as a validity test.
+     * That is the shape this field replaced, and it shipped a false positive within hours of landing:
+     * a real Google Gemini key in a newer shape than `/^AIza/` was reported to its owner as not
+     * looking like a Google key. Vendors add key formats without telling anyone, so a catalog can
+     * prove a string belongs to vendor X, but never that it belongs to nobody. See
+     * `apiKeyFormatWarning`.
+     *
+     * Data rather than an `if (providerId === …)` chain in the rule, so adding a provider stays a row
+     * in the preset catalog — including for a host that supplies its own `presets` and never touches
+     * this package.
+     */
+    apiKeyPrefix?: string;
+    /** The synthetic "Custom" preset. Exactly one may carry this flag; it is
+     *  never treated as configured-by-preset and never hides the Base URL. */
+    custom?: boolean;
+}
+//# sourceMappingURL=provider-catalog.d.ts.map

package/dist/provider-catalog.js

@@ -0,0 +1,6 @@
+/**
+ * Neutral catalog contracts consumed by UI and implemented by host adapters.
+ * Vendor identities, aliases and endpoint defaults belong to integrations.
+ */
+export {};
+//# sourceMappingURL=provider-catalog.js.map

package/dist/provider-registry.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @file The one keyed provider registry every provider seam shares (FROZEN CONTRACT, 2026-10-21).
+ *
+ * Four registries with four shapes grew independently (media `VendorAdapterRegistry`, visitor-auth,
+ * `OAuthProviderRegistry`, commerce `createPaymentProviderRegistry`). This is the shape new seams use
+ * and the four migrate to; `docs/provider-registry.md` in this package records the contract and the
+ * migration path for each. Other builds depend on the exported names and semantics below: change
+ * them only additively.
+ *
+ * Error policy is split by origin. A core/built-in registration that is malformed or duplicated is a
+ * composition-root programming error, so it THROWS at boot (same class as commerce's registry). A
+ * plugin contribution is third-party input, so a broken or duplicate one is recorded in
+ * `refusals()` and never crashes boot (same policy as `createPluginContributionLoader`).
+ */
+/** Provider ids share the plugin-tool name grammar (agent-plugins lifecycle/tools/manifest.ts). */
+export declare const PROVIDER_ID_PATTERN: RegExp;
+export type ProviderOrigin = 'core' | 'plugin';
+/** One registered provider. Stored frozen; the `provider` value keeps its identity. */
+export interface ProviderDefinition<T> {
+    readonly id: string;
+    readonly provider: T;
+    readonly label?: string;
+}
+export interface RegisteredProvider<T> extends ProviderDefinition<T> {
+    readonly origin: ProviderOrigin;
+    /** Set only for `origin: 'plugin'`. */
+    readonly pluginId?: string;
+}
+export type ProviderRefusalCode = 'invalid_id' | 'invalid_provider' | 'duplicate' | 'contract_mismatch' | 'displaced_by_core';
+export interface ProviderRefusal {
+    readonly code: ProviderRefusalCode;
+    readonly pluginId: string;
+    readonly providerId: string;
+    readonly message: string;
+}
+export interface ProviderRegistry<T> {
+    readonly contract: string;
+    /** Core/built-in registration. @throws {ProviderRegistryError} on a bad id, invalid provider or duplicate. */
+    register(required: {
+        readonly definition: ProviderDefinition<T>;
+    }, _optional?: Record<string, never>): void;
+    /** Plugin registration. Never throws (a throwing validator or provider getter is an `invalid_provider`
+     * refusal); returns false and records a refusal instead. */
+    contribute(required: {
+        readonly definition: ProviderDefinition<T>;
+        readonly pluginId: string;
+        readonly contract?: string;
+    }, _optional?: Record<string, never>): boolean;
+    get(required: {
+        readonly id: string;
+    }, _optional?: Record<string, never>): RegisteredProvider<T> | undefined;
+    has(required: {
+        readonly id: string;
+    }, _optional?: Record<string, never>): boolean;
+    /** Frozen snapshot in registration order. */
+    list(_required?: Record<string, never>, _optional?: Record<string, never>): readonly RegisteredProvider<T>[];
+    /** The configured default provider, if one was named and is registered. */
+    getDefault(_required?: Record<string, never>, _optional?: Record<string, never>): RegisteredProvider<T> | undefined;
+    /** Frozen snapshot of every refused plugin contribution, in refusal order. */
+    refusals(_required?: Record<string, never>, _optional?: Record<string, never>): readonly ProviderRefusal[];
+}
+export declare class ProviderRegistryError extends Error {
+    readonly code: ProviderRefusalCode;
+    constructor(required: {
+        readonly code: ProviderRefusalCode;
+        readonly message: string;
+    });
+}
+/**
+ * Build an independent registry for one provider contract (e.g. `mail`, `dns`, `payments`).
+ * Core always wins an id: a core registration displaces an earlier plugin entry (recording a
+ * `displaced_by_core` refusal) so a plugin loaded first can never turn a later core registration
+ * into a boot crash.
+ * @param required.contract - Contract name used in messages and checked against contributions.
+ * @param optional.defaultProviderId - Validated eagerly; need not be registered yet.
+ * @param optional.validate - Contract-specific shape check; a string is the reason it is invalid.
+ * @param optional.seed - Core definitions registered in order (throwing policy).
+ * @throws {ProviderRegistryError} When the default id or a seed definition is invalid.
+ * @complexity register/contribute/get/has O(1); list/refusals O(n) snapshot.
+ */
+export declare function createProviderRegistry<T>(required: {
+    readonly contract: string;
+}, optional?: {
+    readonly defaultProviderId?: string;
+    readonly validate?: (required: {
+        readonly provider: T;
+    }) => string | undefined;
+    readonly seed?: readonly ProviderDefinition<T>[];
+}): ProviderRegistry<T>;
+export type ProviderMode = 'test' | 'live';
+/** Who a provider call acts for. Credentials are pre-resolved by the host, never carried here. */
+export interface ProviderContext {
+    readonly workspaceId: string;
+    readonly siteId?: string;
+    /** The connected account at the provider (e.g. a Stripe account or a mail domain id). */
+    readonly providerAccountId?: string;
+    readonly mode: ProviderMode;
+}
+/** The provider definitively refused: nothing happened, the caller may correct and retry. */
+export type ProviderRejectedCode = 'invalid_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'rate_limited' | 'quota_exceeded' | 'unsupported' | 'not_configured' | 'provider_error';
+/** The outcome is indeterminate (it may have happened): the caller must reconcile, not blindly retry. */
+export type ProviderUnknownCode = 'timeout' | 'network' | 'provider_unavailable' | 'unexpected_response';
+export interface ProviderError<C extends string> {
+    readonly code: C;
+    /** Caller-safe: no credentials, tokens, or raw provider payloads. */
+    readonly message: string;
+    readonly retryAfterMs?: number;
+}
+export type ProviderResult<T> = {
+    readonly status: 'ok';
+    readonly value: T;
+} | {
+    readonly status: 'rejected';
+    readonly error: ProviderError<ProviderRejectedCode>;
+} | {
+    readonly status: 'unknown';
+    readonly error: ProviderError<ProviderUnknownCode>;
+};
+export declare function providerOk<T>(required: {
+    readonly value: T;
+}, _optional?: Record<string, never>): ProviderResult<T>;
+export declare function providerRejected<T = never>(required: ProviderError<ProviderRejectedCode>, _optional?: Record<string, never>): ProviderResult<T>;
+export declare function providerUnknown<T = never>(required: ProviderError<ProviderUnknownCode>, _optional?: Record<string, never>): ProviderResult<T>;
+export type DomainPurpose = 'mail' | 'site' | 'tls';
+export type DnsRecordType = 'A' | 'AAAA' | 'CNAME' | 'TXT' | 'MX' | 'CAA' | 'NS' | 'SRV';
+export interface DomainRecordRequirement {
+    readonly type: DnsRecordType;
+    /** Fully-qualified record name, e.g. `send.example.com`. */
+    readonly name: string;
+    readonly value: string;
+    readonly ttl?: number;
+    /** MX / SRV priority. */
+    readonly priority?: number;
+    /** Operator-facing explanation, e.g. "DKIM signing key". */
+    readonly note?: string;
+}
+/** What one provider needs from a domain before it can serve `purpose` for it. */
+export interface DomainRequirement {
+    readonly purpose: DomainPurpose;
+    readonly domain: string;
+    readonly providerId: string;
+    readonly records: readonly DomainRecordRequirement[];
+}
+//# sourceMappingURL=provider-registry.d.ts.map

package/dist/provider-registry.js

@@ -0,0 +1,138 @@
+/**
+ * @file The one keyed provider registry every provider seam shares (FROZEN CONTRACT, 2026-10-21).
+ *
+ * Four registries with four shapes grew independently (media `VendorAdapterRegistry`, visitor-auth,
+ * `OAuthProviderRegistry`, commerce `createPaymentProviderRegistry`). This is the shape new seams use
+ * and the four migrate to; `docs/provider-registry.md` in this package records the contract and the
+ * migration path for each. Other builds depend on the exported names and semantics below: change
+ * them only additively.
+ *
+ * Error policy is split by origin. A core/built-in registration that is malformed or duplicated is a
+ * composition-root programming error, so it THROWS at boot (same class as commerce's registry). A
+ * plugin contribution is third-party input, so a broken or duplicate one is recorded in
+ * `refusals()` and never crashes boot (same policy as `createPluginContributionLoader`).
+ */
+/** Provider ids share the plugin-tool name grammar (agent-plugins lifecycle/tools/manifest.ts). */
+export const PROVIDER_ID_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+export class ProviderRegistryError extends Error {
+    code;
+    constructor(required) {
+        super(required.message);
+        this.name = 'ProviderRegistryError';
+        this.code = required.code;
+    }
+}
+/** @returns The first validation fault of a definition, or undefined when it may be registered. */
+function definitionFault(required, optional = {}) {
+    const { contract, definition } = required;
+    if (typeof definition.id !== 'string' || !PROVIDER_ID_PATTERN.test(definition.id)) {
+        return { code: 'invalid_id', message: `${contract} provider id '${String(definition.id)}' must match ${PROVIDER_ID_PATTERN.source}` };
+    }
+    const reason = optional.validate?.({ provider: definition.provider });
+    if (reason !== undefined)
+        return { code: 'invalid_provider', message: `${contract} provider '${definition.id}' is invalid: ${reason}` };
+    return undefined;
+}
+/** The id for a refusal line; a hostile definition whose id cannot even be read is recorded as ''. */
+function safeId(required, _optional = {}) {
+    try {
+        return String(required.definition.id);
+    }
+    catch {
+        return '';
+    }
+}
+function frozenEntry(required, optional = {}) {
+    const { id, provider, label } = required.definition;
+    return Object.freeze({
+        id, provider, origin: required.origin,
+        ...(label === undefined ? {} : { label }),
+        ...(optional.pluginId === undefined ? {} : { pluginId: optional.pluginId }),
+    });
+}
+/**
+ * Build an independent registry for one provider contract (e.g. `mail`, `dns`, `payments`).
+ * Core always wins an id: a core registration displaces an earlier plugin entry (recording a
+ * `displaced_by_core` refusal) so a plugin loaded first can never turn a later core registration
+ * into a boot crash.
+ * @param required.contract - Contract name used in messages and checked against contributions.
+ * @param optional.defaultProviderId - Validated eagerly; need not be registered yet.
+ * @param optional.validate - Contract-specific shape check; a string is the reason it is invalid.
+ * @param optional.seed - Core definitions registered in order (throwing policy).
+ * @throws {ProviderRegistryError} When the default id or a seed definition is invalid.
+ * @complexity register/contribute/get/has O(1); list/refusals O(n) snapshot.
+ */
+export function createProviderRegistry(required, optional = {}) {
+    const { contract } = required;
+    const { defaultProviderId, validate } = optional;
+    if (defaultProviderId !== undefined && !PROVIDER_ID_PATTERN.test(defaultProviderId)) {
+        throw new ProviderRegistryError({ code: 'invalid_id', message: `${contract} default provider id '${defaultProviderId}' must match ${PROVIDER_ID_PATTERN.source}` });
+    }
+    const providers = new Map();
+    const refused = [];
+    const refuse = (input) => {
+        refused.push(Object.freeze({ ...input.fault, pluginId: input.pluginId, providerId: input.providerId }));
+        return false;
+    };
+    const registry = {
+        contract,
+        register({ definition }) {
+            const fault = definitionFault({ contract, definition }, { ...(validate ? { validate } : {}) });
+            if (fault)
+                throw new ProviderRegistryError(fault);
+            const existing = providers.get(definition.id);
+            if (existing?.origin === 'core') {
+                throw new ProviderRegistryError({ code: 'duplicate', message: `${contract} provider '${definition.id}' is already registered` });
+            }
+            if (existing?.pluginId !== undefined) {
+                refuse({ fault: { code: 'displaced_by_core', message: `${contract} provider '${definition.id}' from plugin '${existing.pluginId}' was replaced by the built-in provider` }, pluginId: existing.pluginId, providerId: definition.id });
+                providers.delete(definition.id);
+            }
+            providers.set(definition.id, frozenEntry({ definition, origin: 'core' }));
+        },
+        contribute(input) {
+            // Third-party input: a throwing validator, id or provider getter is refused, never propagated
+            // (core registrations keep the throwing policy above).
+            try {
+                return contributeChecked(input);
+            }
+            catch {
+                return refuse({ fault: { code: 'invalid_provider', message: `${contract} provider from plugin '${input.pluginId}' was not loaded: its definition could not be validated` }, pluginId: input.pluginId, providerId: safeId({ definition: input.definition }) });
+            }
+        },
+        get({ id }) { return providers.get(id); },
+        has({ id }) { return providers.has(id); },
+        list() { return Object.freeze([...providers.values()]); },
+        getDefault() { return defaultProviderId === undefined ? undefined : providers.get(defaultProviderId); },
+        refusals() { return Object.freeze([...refused]); },
+    };
+    function contributeChecked({ definition, pluginId, contract: declared }) {
+        const providerId = String(definition.id);
+        if (declared !== undefined && declared !== contract) {
+            return refuse({ fault: { code: 'contract_mismatch', message: `plugin '${pluginId}' contributed provider '${providerId}' for contract '${declared}', not '${contract}'` }, pluginId, providerId });
+        }
+        const fault = definitionFault({ contract, definition }, { ...(validate ? { validate } : {}) });
+        if (fault)
+            return refuse({ fault, pluginId, providerId });
+        const existing = providers.get(providerId);
+        if (existing) {
+            const owner = existing.pluginId === undefined ? 'the built-in provider' : `plugin '${existing.pluginId}'`;
+            return refuse({ fault: { code: 'duplicate', message: `${contract} provider '${providerId}' from plugin '${pluginId}' was not loaded: already registered by ${owner}` }, pluginId, providerId });
+        }
+        providers.set(providerId, frozenEntry({ definition, origin: 'plugin' }, { pluginId }));
+        return true;
+    }
+    for (const definition of optional.seed ?? [])
+        registry.register({ definition });
+    return registry;
+}
+export function providerOk(required, _optional = {}) {
+    return { status: 'ok', value: required.value };
+}
+export function providerRejected(required, _optional = {}) {
+    return { status: 'rejected', error: { ...required } };
+}
+export function providerUnknown(required, _optional = {}) {
+    return { status: 'unknown', error: { ...required } };
+}
+//# sourceMappingURL=provider-registry.js.map

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

@@ -44,6 +44,10 @@ export interface SecretRedactionPattern {
 }
 /** 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

@@ -139,21 +139,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 +195,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 +267,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