@jini-ai/core 0.6.17 → 0.6.21

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @jini-ai/core
 
+## 0.6.21
+
+- `createPreparedBatchHandler`: prepares a complete direct batch before any effect, reusing the approval handler's input snapshot, cap, duplicate detection and cancellation lifecycle, with no review card.
+
+## 0.6.19
+
+- Preserve detached, frozen batch schema symbol metadata in tool exposure snapshots and single-call required-field guidance in plan-mode descriptions.
+- Redact complete quoted credential keys and values in inspected and JSON diagnostics, including API keys, cookies, tokens and private keys, while preserving diagnostic context.
+- Add universal `formatErrorForLog` diagnostics that retain stacks, codes and structured context, redact secrets and never interrupt recovery for hostile thrown values.
+- Redact default settings-stream exception logs through the shared secret policy.
+
 ## 0.6.17
 
 ### Patch Changes

package/dist/approval.d.ts

@@ -73,6 +73,16 @@ export interface ApprovalSteps<TPrepared, TDescription> {
 export declare function createApprovalHandler<TPrepared, TDescription>(steps: ApprovalSteps<TPrepared, TDescription>, { remembered }?: {
     remembered?: RememberedApprovalPort;
 }): ToolHandler;
+/** Prepare a complete direct batch before effects, reusing the approval owner's input snapshot,
+ * cap, duplicate detection and cancellation lifecycle. No review description or transport exists.
+ * @returns A handler preserving scalar results and ordered batch results.
+ * @throws ToolInputError on cancellation or invalid batches; preparation/effect failures propagate.
+ * @complexity Same bounds as createBatchApprovalHandler: O(input bytes) plus bounded port effects.
+ * @example createPreparedBatchHandler({ prepare, run });
+ */
+export declare function createPreparedBatchHandler<TPrepared>(steps: Pick<ApprovalSteps<TPrepared, undefined>, 'prepare' | 'run'>, options?: {
+    maxItems?: number;
+}): ToolHandler;
 /** Prepare every item before asking once for the complete batch. Reuses the single-call approval
  * lifecycle, including its detached inputs, authenticated confirmer and abort checks.
  * Single inputs preserve their result shape. Batch effects run in order and stop on the first

package/dist/approval.js

@@ -90,6 +90,20 @@ export function createApprovalHandler(steps, { remembered } = {}) {
         },
     });
 }
+/** Prepare a complete direct batch before effects, reusing the approval owner's input snapshot,
+ * cap, duplicate detection and cancellation lifecycle. No review description or transport exists.
+ * @returns A handler preserving scalar results and ordered batch results.
+ * @throws ToolInputError on cancellation or invalid batches; preparation/effect failures propagate.
+ * @complexity Same bounds as createBatchApprovalHandler: O(input bytes) plus bounded port effects.
+ * @example createPreparedBatchHandler({ prepare, run });
+ */
+export function createPreparedBatchHandler(steps, options = {}) {
+    return createBatchApprovalHandler({ steps: { ...steps,
+            describe: () => ({ ask: false, description: undefined }),
+            askHuman: async () => { throw new Error('Direct batches have no approval transport'); },
+            notConfirmed: ({ reason }) => { throw new ToolInputError({ message: `This tool call was ${reason} before the next change. Retry the remaining changes when ready.` }); },
+        }, combineDescriptions: () => undefined }, options);
+}
 /** Prepare every item before asking once for the complete batch. Reuses the single-call approval
  * lifecycle, including its detached inputs, authenticated confirmer and abort checks.
  * Single inputs preserve their result shape. Batch effects run in order and stop on the first
@@ -128,7 +142,7 @@ export function createBatchApprovalHandler({ steps, combineDescriptions }, { max
                 plans.push(await steps.describe(entry, options));
             if (!prepared.batch)
                 return plans[0];
-            return { ask: true, description: combineDescriptions({ descriptions: plans.map(plan => plan.description) }) };
+            return { ask: plans.some(plan => plan.ask), description: combineDescriptions({ descriptions: plans.map(plan => plan.description) }) };
         },
         askHuman: steps.askHuman,
         run: async ({ prepared, confirmer, choice }, options) => {

package/dist/batch-tool-inputs.d.ts

@@ -5,6 +5,8 @@ import { type ToolRegistration } from './tool-registry.js';
  *  smaller window per item that the caller may still raise. */
 export interface BatchableTool {
     readonly toolId: string;
+    /** A domain that owns a combined approval plan receives the whole normalized batch once. */
+    readonly mode?: 'items' | 'plan';
     readonly maxItems?: number;
     readonly itemDefaults?: Readonly<Record<string, unknown>>;
     /** Host-specific result constraints, checked on the normalized item before its handler runs. */

package/dist/batch-tool-inputs.js

@@ -20,6 +20,10 @@ const ITEM_NEEDS = " Each item needs ";
 const ITEM_NEEDS_END = " (inside each item).";
 // Keep discovery requirements through descriptor/schema spreads without adding wire-schema keys.
 const BATCH_ITEM_REQUIRED_FIELDS = Symbol('batchItemRequiredFields');
+/** Shared by item and plan descriptions so neither can make single calls look argument-free. */
+function singleCallGuidance({ fields }, _options = {}) {
+    return fields.length > 0 ? `Single call requires: ${fields.join(', ')}. ` : '';
+}
 /** The original top-level `required` fields retained by {@link batchDescriptorFor} as schema metadata.
  * A batch schema declares no top-level `required`, so a discovery signature built from it alone
  * makes a single call look argument-free and the model sends `{}` — this recovers them.
@@ -87,7 +91,7 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     delete rest.required;
     const needs = requiredFields.length > 0 ? `${ITEM_NEEDS}${requiredFields.join(", ")}${ITEM_NEEDS_END}` : "";
     // Inside the removable guidance so search keeps only the authored description and signature.
-    const singleNeeds = requiredFields.length > 0 ? `Single call requires: ${requiredFields.join(", ")}. ` : "";
+    const singleNeeds = singleCallGuidance({ fields: requiredFields });
     const items = {
         type: "array",
         minItems: 1,
@@ -203,14 +207,14 @@ function summarizeBatchResults({ results }, _options = {}) {
  * @complexity O(n) bounded normalization/target checks for n items, plus the existing
  * per-item executor or combined plan lifecycle. The default cap is 25.
  */
-export function withBatchInput({ registration, tool }, { mode = 'items' } = {}) {
+export function withBatchInput({ registration, tool }, { mode = tool.mode ?? 'items' } = {}) {
     const toolId = registration.descriptor.id;
     const maxItems = tool.maxItems ?? DEFAULT_MAX_BATCH_ITEMS;
     const descriptor = batchDescriptorFor({ descriptor: registration.descriptor, tool });
     if (mode === 'plan')
         return {
             ...registration, descriptor: { ...descriptor,
-                description: `${registration.descriptor.description ?? ''}${BATCH_GUIDANCE_MARKER}up to ${maxItems} inputs are normalized before authorization and passed to the existing combined approval plan.`,
+                description: `${registration.descriptor.description ?? ''}${BATCH_GUIDANCE_MARKER}${singleCallGuidance({ fields: batchItemRequiredFields({ inputSchema: descriptor.inputSchema }) })}up to ${maxItems} inputs are normalized before authorization and passed to the existing combined approval plan.`,
             },
             // The plan owns one confirmation. Normalize every merged item before the outer gate so
             // its policy and planner receive the same targets; never execute items to preflight them.

package/dist/redact.d.ts

@@ -99,6 +99,19 @@ export declare const NON_SECRET_TOKEN_RE: RegExp;
 export declare function redactSecrets({ input }: {
     input: string;
 }, options?: SecretRedactionOptions): string;
+/**
+ * Universal diagnostic text for any thrown value. Keeps native stacks and structured metadata,
+ * then applies the shared credential policy (PII stays readable unless explicitly requested).
+ * Diagnostic getters, serialization and coercion can themselves fail; fixed fallback text keeps
+ * those failures from replacing the original error or interrupting the caller's recovery.
+ * @param required.error - Untrusted thrown value; never mutated.
+ * @param options - Shared redaction options, including caller-owned exact secrets.
+ * @returns Redacted text; never throws, including for circular objects and hostile accessors.
+ * @complexity O(n) serialization in the diagnostic's fields/characters, plus shared redaction passes.
+ */
+export declare function formatErrorForLog(required: {
+    error: unknown;
+}, options?: SecretRedactionOptions): string;
 /**
  * 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

package/dist/redact.js

@@ -165,7 +165,9 @@ const PATTERNS = [
 // non-card numbers (timestamps, IDs, hashes). We isolate the candidate
 // then run a Luhn check before redacting.
 const CARD_CANDIDATE = /\b(?:\d[ -]?){12,18}\d\b/g;
-const API_KEY_HEADER = /(^|[^?&\w-])("?)(x-api-key|api-key|x-goog-api-key)\2(\s*[:=]\s*)("[^"]*"|[^\s,;"'#}]+)/gi;
+// Inspect/JSON credentials can contain spaces and escaped quotes; consume the entire value.
+const QUOTED_SECRET_VALUE = String.raw `"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'`;
+const API_KEY_HEADER = new RegExp(`(^|[^?&\\w-])(["']?)(x-api-key|api-key|x-goog-api-key)\\2(\\s*[:=]\\s*)(${QUOTED_SECRET_VALUE}|[^\\s,;"'#}]+)`, 'gi');
 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
@@ -199,6 +201,9 @@ function isLuhnValid(digits) {
 // 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.
 const SECRET_LABELS = 'authorization|bearer|api[-_]?key|access[-_]?token|refresh[-_]?token|client[-_]?secret|password|secret|cookie';
+// Keep historical URL categories and the bounded sanitizer's vocabulary stable.
+const SERIALIZED_SECRET_LABELS = `${SECRET_LABELS}|x[-_](?:goog[-_])?api[-_]?key|api key|token|set[-_]cookie|private[-_]?key`;
+const EMPTY_QUOTED_ASSIGNMENT_RE = new RegExp(`\\b(?:${SERIALIZED_SECRET_LABELS})\\s*[:=]\\s*$`, 'i');
 export const LABELED_SECRET_RE = new RegExp(`\\b(${SECRET_LABELS})\\b\\s*[:=]\\s*\\S+`, 'gi');
 export const OPAQUE_TOKEN_RE = /[A-Za-z0-9_-]{20,}/g;
 // Pattern parts, only ever used inside the anchored NON_SECRET_TOKEN_RE.
@@ -209,7 +214,9 @@ export const NON_SECRET_TOKEN_RE = new RegExp(`^(?:${CORRELATION_ID}|delegated-t
 // 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);
+// Quoted values end at their matching quote; opaque unquoted values retain punctuation.
+// An ampersand cannot start a value: an empty URL parameter must not eat its neighbor.
+const MASK_AWARE_LABELED_SECRET_RE = new RegExp(`(?<![\\w-])((["']?)(?:${SERIALIZED_SECRET_LABELS})\\2\\s*[:=]\\s*)(?!Bearer\\s+\\[REDACTED:[^\\]]+\\](?:\\s|$))(?!\\[REDACTED:[^\\]]+\\][;&])(${QUOTED_SECRET_VALUE}|(?!&)\\S+)`, 'gi');
 // Provider failures also echo short bearer values. Exclude our own marker on subsequent passes.
 // The leading lookahead only lets the lookbehind run where a value can start (see bearer_token).
 const SHORT_BEARER_RE = /(?=[\w.+/=-])(?<=Bearer\s+)[\w.+/=-]+/gi;
@@ -249,6 +256,59 @@ function isMaskedValue(value) {
 export function redactSecrets({ input }, options = {}) {
     return redactSecretsWithCounts({ input }, options).redacted;
 }
+/**
+ * Universal diagnostic text for any thrown value. Keeps native stacks and structured metadata,
+ * then applies the shared credential policy (PII stays readable unless explicitly requested).
+ * Diagnostic getters, serialization and coercion can themselves fail; fixed fallback text keeps
+ * those failures from replacing the original error or interrupting the caller's recovery.
+ * @param required.error - Untrusted thrown value; never mutated.
+ * @param options - Shared redaction options, including caller-owned exact secrets.
+ * @returns Redacted text; never throws, including for circular objects and hostile accessors.
+ * @complexity O(n) serialization in the diagnostic's fields/characters, plus shared redaction passes.
+ */
+export function formatErrorForLog(required, options = {}) {
+    try {
+        const { error } = required;
+        let text;
+        if (error instanceof Error) {
+            const message = String(error.message);
+            text = String(error.stack ?? `${error.name}: ${message}`);
+            if (!text.includes(message))
+                text += `\n${message}`;
+            const fields = Object.fromEntries(Object.getOwnPropertyNames(error)
+                .filter(key => !['name', 'message', 'stack'].includes(key)).map(key => [key, Reflect.get(error, key)]));
+            if (Object.keys(fields).length)
+                text += `\n${diagnosticJson({ error: fields }, options)}`;
+        }
+        else {
+            text = error !== null && typeof error === 'object' ? diagnosticJson({ error }, options) : String(error);
+        }
+        return redactSecrets({ input: text }, { redactPii: false, ...options });
+    }
+    catch {
+        return '[Unformattable error]';
+    }
+}
+/** JSON preserves structured fields without coercing objects; track cycles and native Error fields.
+ * Property access remains inside formatErrorForLog's recovery boundary. O(n) visited fields. */
+function diagnosticJson({ error }, options = {}) {
+    const seen = new WeakSet();
+    return JSON.stringify(error, (_key, value) => {
+        if (value !== null && typeof value === 'object') {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+            if (value instanceof Error)
+                return Object.fromEntries(Object.getOwnPropertyNames(value).map(key => [key, Reflect.get(value, key)]));
+        }
+        // Scrub string contents before JSON escapes their credential labels. Exact-only is kept
+        // for the final pass so a caller's literal marker is never reprocessed as a supplied secret.
+        if (typeof value === 'string' && options.policy !== 'exact-only') {
+            return redactSecrets({ input: value }, { redactPii: false, ...options });
+        }
+        return typeof value === 'bigint' ? String(value) : value;
+    }) ?? String(error);
+}
 /**
  * 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
@@ -317,7 +377,7 @@ function applyPatterns({ text, marker, patterns }) {
 // and left `hunter2` visible; `api_key` swallowed the whole `api_key=` label), and they split
 // earlier markers (`a` inside `exact_secret`, `email` inside `[REDACTED:email]`).
 const PROTECTED_SPAN_RE = new RegExp([
-    `\\b(?:${SECRET_LABELS})\\b\\s*[:=]`,
+    `(?<![\\w-])["']?(?:${SERIALIZED_SECRET_LABELS})["']?\\s*[:=]`,
     '\\bbearer\\s+',
     URL_SECRET_PARAM_RE.source.slice(0, URL_SECRET_PARAM_RE.source.lastIndexOf('=') + 1),
     URL_CREDENTIALS_RE.source.slice(0, URL_CREDENTIALS_RE.source.indexOf(')') + 1),
@@ -373,14 +433,30 @@ function redactUrlCredentials({ text, marker }) {
         .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')}`);
 }
+/** Mask quoted hints ending in an empty credential assignment before scanning labels. Otherwise
+ * their closing quote is mistaken for a value's opening quote and consumes the next field's key,
+ * leaving that field's secret unrecognized. Only the hint token is replaced; neighboring labels
+ * remain available to the existing matchers, including inspect's unquoted keys.
+ * @complexity O(n) scanning the diagnostic's quoted tokens; no I/O or input mutation.
+ */
+function redactEmptyQuotedAssignments({ text, marker }, _options = {}) {
+    return text.replace(new RegExp(QUOTED_SECRET_VALUE, 'g'), (quoted) => {
+        if (!EMPTY_QUOTED_ASSIGNMENT_RE.test(quoted.slice(1, -1)))
+            return quoted;
+        const quote = quoted.charAt(0);
+        return `${quote}${marker('labeled_secret')}${quote}`;
+    });
+}
 /** 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) => {
+    let out = redactEmptyQuotedAssignments({ text, marker });
+    out = out.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');
-        const redactedValue = value.startsWith('"') ? '"[REDACTED:api_key_header]"' : '[REDACTED:api_key_header]';
+        const valueQuote = /^["']/.test(value) ? value.charAt(0) : '';
+        const redactedValue = `${valueQuote}[REDACTED:api_key_header]${valueQuote}`;
         return `${prefix}${quote}${name}${quote}${separator}${redactedValue}`;
     });
     // The provider rule includes a query fragment in an echoed key; mask that whole value
@@ -392,12 +468,13 @@ function redactKeyedCredentials({ text, marker }) {
     // Sweep other URL parameters before the general labeled rule can consume harmless
     // neighboring parameters (`password=x&page=2` used to lose `&page=2`).
     out = redactUrlSecretParams({ text: out, marker });
-    return out.replace(MASK_AWARE_LABELED_SECRET_RE, (match, _label, value) => {
+    return out.replace(MASK_AWARE_LABELED_SECRET_RE, (match, prefix, _quote, 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')}`;
+        const valueQuote = /^["']/.test(value) ? value.charAt(0) : '';
+        return `${prefix}${valueQuote}${marker('labeled_secret')}${valueQuote}`;
     });
 }
 /** Secret-named URL query/fragment values; values already masked above keep their category. */

package/dist/settings/express/stream.js

@@ -1,3 +1,5 @@
+import { inspect } from 'node:util';
+import { redactSecrets } from '../../redact.js';
 /** Starts after HTTP authorization. All scheduling and storage are injected.
  * Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
  * O(page size) per tick and O(1) connection state; repository effects live behind the feed port.
@@ -149,7 +151,7 @@ function createErrorReporter(optional) {
             if (optional.onError)
                 optional.onError({ operation, error });
             else
-                console.error(`[settings] change feed ${operation} failed`, error);
+                console.error(`[settings] change feed ${operation} failed`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
         }
         catch { /* Diagnostic failures cannot interrupt stream cleanup or retries. */ }
     };

package/dist/surface-exchanges.d.ts

@@ -123,6 +123,7 @@ export interface SurfaceExchange {
      * When the exchange expires if nothing more happens, in epoch ms: the earlier of the idle and
      * lifetime deadlines. Activity moves the idle one, so read it right before rendering a deadline
      * for the human; a card drawn just before its `send()` shows a deadline a few ms early, never late.
+     * Positive infinity denotes a run-lifetime lease; renderers omit a countdown for nonfinite dates.
      */
     expiresAtMs(): number;
 }
@@ -155,6 +156,20 @@ export interface SurfaceDeliverySpec {
     channel?: SurfaceAnswerChannel;
 }
 export interface SurfaceExchangeStore {
+    /** Restore an unanswered call through its original executor, or observe its still-live card.
+     * Streams human-only emissions until the exchange settles. A late answer is delivered once to
+     * the replacement exchange; it is never retained, logged or used as model input. Optional for
+     * compatibility with host-supplied stores that do not support restoration. */
+    restore?(required: {
+        exchangeId: string;
+        principalId: string;
+        emit: SurfaceEmitter;
+    }, optional?: {
+        toolId?: string;
+        channel?: SurfaceAnswerChannel;
+        params?: Record<string, unknown>;
+        signal?: AbortSignal;
+    }): Promise<DeliverResult>;
     /**
      * Opens an exchange bound to one in-flight tool call.
      *

package/dist/tool-exposure.js

@@ -72,14 +72,23 @@ function freezeData(value, seen = new Set()) {
     if (value === null || typeof value !== 'object' || Object.isFrozen(value) || seen.has(value))
         return;
     seen.add(value);
-    for (const child of Object.values(value))
-        freezeData(child, seen);
+    for (const key of Reflect.ownKeys(value))
+        freezeData(Reflect.get(value, key), seen);
     Object.freeze(value);
 }
 /** Clone and measure before publication. Invalid data cannot partially change exposure state. */
 function pinDescriptor(descriptor) {
     try {
         const pinned = structuredClone(descriptor);
+        // structuredClone omits symbol keys. Batch schemas keep discovery requirements there
+        // so providers see a plain wire schema; detach that metadata before freezing it too.
+        if (descriptor.inputSchema !== null && typeof descriptor.inputSchema === 'object') {
+            for (const symbol of Object.getOwnPropertySymbols(descriptor.inputSchema)) {
+                Object.defineProperty(pinned.inputSchema, symbol, {
+                    value: structuredClone(Reflect.get(descriptor.inputSchema, symbol)), enumerable: true,
+                });
+            }
+        }
         const json = JSON.stringify(pinned.inputSchema);
         const bytes = json === undefined ? 0 : new TextEncoder().encode(json).byteLength;
         freezeData(pinned);

package/dist/tool-registry.d.ts

@@ -150,7 +150,20 @@ export interface SurfaceEmission {
  * headless or synthetic execution) omits it, and a handler that finds it absent must fall back to
  * returning its surface rather than parking — see the `@jini-ai/daemon` bridge for the supplying end.
  */
-export type SurfaceEmitter = (emission: SurfaceEmission) => Promise<void>;
+export type SurfaceEmitter = ((emission: SurfaceEmission) => Promise<void>) & {
+    /** Executor-owned lifetime, never supplied by a rendered card. A retry uses the original public
+     * tool input and re-enters the complete authorization/audit stack with a fresh human emitter. */
+    readonly exchangeLifetime?: {
+        readonly signal: AbortSignal;
+        readonly runId: string;
+        readonly toolId: string;
+        readonly principalId: string;
+        readonly retry: (required: {
+            emit: SurfaceEmitter;
+            signal: AbortSignal;
+        }, optional?: Record<string, never>) => Promise<void>;
+    };
+};
 /** What a `ToolHandler` receives — everything it needs and nothing it could use to bypass the gate (no registry access, no other tools' state). */
 export interface ToolExecutionContext {
     /** The id `ToolExecutor` assigned this call — for the handler's own logging/correlation; carries no authority (the gate already ran before the handler is invoked). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.17",
+  "version": "0.6.21",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {