@jini-ai/core 0.6.15 → 0.6.17

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @jini-ai/core
 
+## 0.6.17
+
+### Patch Changes
+
+- Mark required single-call fields in published batched-tool schemas and descriptions while preserving batching and clear missing-input errors.
+
+## 0.6.16
+
+### Patch Changes
+
+- Remove the GitHub Copilot CLI agent: its def, `createCopilotStreamHandler`/`CopilotStreamEvent`,
+  account model discovery and the `@github/copilot-sdk` optional peer, the MCP installer's `copilot`
+  slug, and its icon. A saved `copilot` agent id no longer resolves (`getAgentDef` returns `null`).
+  CopilotKit/AG-UI is unrelated and unchanged.
+
+  Drop peers no runtime entry loads: `express` from core and http-kit (type-only imports; type
+  consumers keep `@types/express`), `vue` from ui-kit, `react-dom` from vibecoding.
+
 ## 0.6.15
 
 ### Minor Changes

package/README.md

@@ -15,8 +15,9 @@ set of tokens, and fails to typecheck if any pack's declared dependency is left
 npm install @jini-ai/core
 ```
 
-The root has no runtime dependencies and never loads settings or Express. `express` is an optional
-peer used only by `@jini-ai/core/settings/express`; install it in hosts mounting those routes.
+The root has no runtime dependencies and never loads settings or Express. The
+`@jini-ai/core/settings/express` adapter uses Express types and the host's injected app; it never
+loads the Express runtime, so this package declares no Express peer.
 
 ## What you get
 

package/dist/approval.d.ts

@@ -1,5 +1,7 @@
 import { type HumanConfirmer } from './registration-kit.js';
 import type { ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolRegistration } from './tool-registry.js';
+/** Maximum human approval wait for one invocation, independent of execution time. */
+export declare const APPROVAL_WAIT_TIMEOUT_MS = 120000;
 /** A host describes the action; core owns the decision lifecycle, never the card format. */
 export interface ApprovalPlan<TDescription> {
     readonly ask: boolean;
@@ -103,6 +105,12 @@ export declare function createApprovalProposalStore<TDescription>({ responseTool
 }, { createId }?: {
     createId?: () => string;
 }): {
+    request: ({ description, signal }: {
+        description: TDescription;
+        signal: AbortSignal;
+    }, { timeoutMs }?: {
+        timeoutMs?: number;
+    }) => Promise<ApprovalAnswer>;
     getSnapshot: (_required?: {}, _optional?: {}) => {
         pending: {
             approvalId: string;
@@ -117,7 +125,10 @@ export declare function createApprovalProposalStore<TDescription>({ responseTool
         description: TDescription;
         execute: () => Promise<unknown>;
         signal: AbortSignal;
-    }, _optional?: {}): {
+    }, { humanOnly, decide }?: {
+        humanOnly?: boolean;
+        decide?: (answer: ApprovalAnswer) => void;
+    }): {
         status: "approval_required";
         approvalId: string;
         description: TDescription;
@@ -126,7 +137,9 @@ export declare function createApprovalProposalStore<TDescription>({ responseTool
     respond({ approvalId, approved }: {
         approvalId: string;
         approved: boolean;
-    }, _optional?: {}): Promise<unknown>;
+    }, { source }?: {
+        source?: "human";
+    }): Promise<unknown>;
 };
 /** Apply a host classification through the same handler owner used by domain plans.
  * A host description's string `rememberKey` opts into reusable grants; descriptions remain opaque.

package/dist/approval.js

@@ -1,6 +1,8 @@
 import { humanConfirmedHandler, requireInputRecord } from './registration-kit.js';
 import { ToolInputError } from './tool-registry.js';
 import { isNonArrayRecord } from './records.js';
+/** Maximum human approval wait for one invocation, independent of execution time. */
+export const APPROVAL_WAIT_TIMEOUT_MS = 120_000;
 /** The decision reducer shared by parked tool calls and the browser's explicit reply transport.
  * An answer never revives an aborted operation. Transport failures propagate without an effect.
  * @param optional.onApprovalStateChange Reports only the human wait, released on every outcome.
@@ -157,33 +159,45 @@ export function createApprovalProposalStore({ responseTool, messages }, { create
     const listeners = new Set();
     const publish = (next) => { snapshot = next; for (const listener of listeners)
         listener(); };
-    const clear = () => {
+    const clear = (answer = { confirmed: false, reason: 'abandoned' }) => {
+        const decide = action?.decide;
         detach?.();
         detach = null;
         action = null;
         publish({ pending: null, error: null });
+        decide?.(answer);
     };
-    return {
+    /** Resolve authority before consuming the single-use action; model input cannot set source. */
+    const actionForReply = ({ approvalId, source }) => {
+        if (!action || action.approvalId !== approvalId)
+            throw new Error(messages.missing);
+        if (action.humanOnly && source !== 'human')
+            throw new Error('This decision requires the app dialog');
+        return action;
+    };
+    const store = {
         getSnapshot: (_required = {}, _optional = {}) => snapshot,
         subscribe: ({ listener }, _optional = {}) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
-        propose({ description, execute, signal }, _optional = {}) {
+        propose({ description, execute, signal }, { humanOnly = false, decide } = {}) {
             if (signal.aborted)
                 throw new Error(messages.closed);
             if (snapshot.pending)
                 throw new Error(messages.pending);
             const frozenDescription = structuredClone(description);
             const approvalId = createId();
-            action = { approvalId, execute, signal };
-            signal.addEventListener('abort', clear, { once: true });
-            detach = () => signal.removeEventListener('abort', clear);
+            action = { approvalId, execute, signal, humanOnly, ...(decide ? { decide } : {}) };
+            const abort = () => clear();
+            signal.addEventListener('abort', abort, { once: true });
+            detach = () => signal.removeEventListener('abort', abort);
             publish({ pending: { approvalId, description: structuredClone(frozenDescription) }, error: null });
             return { status: 'approval_required', approvalId, description: frozenDescription, responseTool };
         },
-        async respond({ approvalId, approved }, _optional = {}) {
-            if (!action || action.approvalId !== approvalId)
-                throw new Error(messages.missing);
-            const prepared = action;
-            clear();
+        async respond({ approvalId, approved }, { source } = {}) {
+            const prepared = actionForReply({ approvalId, source });
+            clear(approved === true ? { confirmed: true } : { confirmed: false, reason: 'declined' });
+            // An awaiting caller owns execution after this decision; do not start a second lifecycle.
+            if (prepared.decide)
+                return { status: approved === true ? 'approved' : 'declined' };
             const answer = await resolveApproval({ signal: prepared.signal, askHuman: async () => approved === true ? { confirmed: true } : { confirmed: false, reason: 'declined' } });
             if (!answer.confirmed)
                 return { status: 'declined' };
@@ -196,6 +210,28 @@ export function createApprovalProposalStore({ responseTool, messages }, { create
             }
         },
     };
+    /** Park a call on this same store without publishing any assistant reply capability. The app
+     * dialog alone may decide it. Expiry/abort consume the proposal before resolving the waiter. */
+    async function request({ description, signal }, { timeoutMs = APPROVAL_WAIT_TIMEOUT_MS } = {}) {
+        const lifetime = new AbortController();
+        const abort = () => lifetime.abort();
+        if (signal.aborted)
+            return { confirmed: false, reason: 'abandoned' };
+        signal.addEventListener('abort', abort, { once: true });
+        let expired = false;
+        const timer = setTimeout(() => { expired = true; lifetime.abort(); }, timeoutMs);
+        try {
+            return await resolveApproval({ signal: lifetime.signal, askHuman: () => new Promise(resolve => {
+                    store.propose({ description, signal: lifetime.signal, execute: async () => undefined }, { humanOnly: true, decide: resolve });
+                }) }).then(answer => expired ? { confirmed: false, reason: 'expired' } : answer);
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            lifetime.abort();
+        }
+    }
+    return { ...store, request };
 }
 /** Apply a host classification through the same handler owner used by domain plans.
  * A host description's string `rememberKey` opts into reusable grants; descriptions remain opaque.

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

@@ -20,6 +20,14 @@ export declare const BATCH_GUIDANCE_MARKER = " Batch: ";
 export declare function withoutBatchGuidance({ description }: {
     description: string;
 }, _optional?: {}): string;
+/** 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.
+ * @returns The moved field names in order; [] for a non-batch schema or a tool that required none.
+ * @complexity O(r) time and space for r required fields; pure. */
+export declare function batchItemRequiredFields({ inputSchema }: {
+    inputSchema: unknown;
+}, _optional?: {}): string[];
 /** Used when a {@link BatchableTool} names no `maxItems`. */
 export declare const DEFAULT_MAX_BATCH_ITEMS = 25;
 /** One item's outcome. `error` is the domain's own message without the appended input schema,
@@ -53,15 +61,16 @@ export declare function batchOutcomeFor({ output }: {
 }, _options?: {}): BatchResult['outcome'] | undefined;
 /**
  * The descriptor a batchable tool publishes: its own schema plus an `items` array, its top-level
- * `required` list moved into the `items` description (a batch call sets those per item or once at
- * the top level through the declared legacy normalization), and batch guidance appended to its description.
+ * `required` list retained as metadata and described on required properties (a batch call sets
+ * those per item or once at the top level through the declared legacy normalization), and batch
+ * guidance appended to its description.
  *
  * @param required.descriptor - The tool's registered descriptor.
  * @param required.tool - Its batch settings.
  * @returns A new descriptor; the input is not mutated.
  * @throws {Error} If the tool publishes no object schema, or already has an `items` property
  * (the batch field would shadow it) — both developer errors caught at composition time.
- * @complexity O(p) in the schema's top-level property count.
+ * @complexity O(p + r) time and space for p top-level properties and r required fields.
  */
 export declare function batchDescriptorFor({ descriptor, tool }: {
     descriptor: ToolRegistration["descriptor"];

package/dist/batch-tool-inputs.js

@@ -16,6 +16,21 @@ export function withoutBatchGuidance({ description }, _optional = {}) {
         return end === -1 ? `${BATCH_GUIDANCE_MARKER}to do several at once,${part}` : part.slice(end + BATCH_GUIDANCE_END.length);
     }).join("");
 }
+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');
+/** 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.
+ * @returns The moved field names in order; [] for a non-batch schema or a tool that required none.
+ * @complexity O(r) time and space for r required fields; pure. */
+export function batchItemRequiredFields({ inputSchema }, _optional = {}) {
+    if (!isPlainObject(inputSchema))
+        return [];
+    const schema = inputSchema;
+    return [...(schema[BATCH_ITEM_REQUIRED_FIELDS] ?? [])];
+}
 /** Used when a {@link BatchableTool} names no `maxItems`. */
 export const DEFAULT_MAX_BATCH_ITEMS = 25;
 /** Classify a batch result, including legacy envelopes, without dropping per-item evidence.
@@ -40,15 +55,16 @@ function isPlainObject(value) {
 }
 /**
  * The descriptor a batchable tool publishes: its own schema plus an `items` array, its top-level
- * `required` list moved into the `items` description (a batch call sets those per item or once at
- * the top level through the declared legacy normalization), and batch guidance appended to its description.
+ * `required` list retained as metadata and described on required properties (a batch call sets
+ * those per item or once at the top level through the declared legacy normalization), and batch
+ * guidance appended to its description.
  *
  * @param required.descriptor - The tool's registered descriptor.
  * @param required.tool - Its batch settings.
  * @returns A new descriptor; the input is not mutated.
  * @throws {Error} If the tool publishes no object schema, or already has an `items` property
  * (the batch field would shadow it) — both developer errors caught at composition time.
- * @complexity O(p) in the schema's top-level property count.
+ * @complexity O(p + r) time and space for p top-level properties and r required fields.
  */
 export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     const schema = descriptor.inputSchema;
@@ -60,9 +76,18 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     }
     const maxItems = tool.maxItems ?? DEFAULT_MAX_BATCH_ITEMS;
     const requiredFields = schema.required ?? [];
+    const requiredNames = new Set(requiredFields);
+    const properties = Object.fromEntries(Object.entries(schema.properties).map(([name, property]) => [
+        name,
+        requiredNames.has(name) && isPlainObject(property)
+            ? { ...property, description: `Required for a single call (or set it in each item). ${property.description ?? ""}` }
+            : property,
+    ]));
     const rest = { ...schema };
     delete rest.required;
-    const needs = requiredFields.length > 0 ? ` Each item needs ${requiredFields.join(", ")} (inside each item).` : "";
+    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 items = {
         type: "array",
         minItems: 1,
@@ -75,8 +100,9 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
         ...descriptor,
         description: `${descriptor.description ?? ""}${BATCH_GUIDANCE_MARKER}to do several at once, pass items: [{...}, ...] (up to ${maxItems}) in ONE call instead of one call per item. ` +
             "Canonical shape: {items:[{...}, ...]} only. Legacy shared top-level fields are normalized into each item; item values win. " +
+            singleNeeds +
             "Returns { batch: true, outcome: completed | partial_failure | error, total, succeeded, failed, results: [{ index, ok, result | error }] }; one item's failure does not stop the others.",
-        inputSchema: { ...rest, properties: { ...schema.properties, items } },
+        inputSchema: { ...rest, [BATCH_ITEM_REQUIRED_FIELDS]: [...requiredFields], properties: { ...properties, items } },
     };
 }
 /** The domain message without `withSchemaOnRejection`'s appended schema: the text before the
@@ -111,6 +137,38 @@ async function normalizeBatchItem({ registration, defaults, shared, item }) {
     const normalized = await normalizeToolInput({ input, registration });
     return { input: normalized.input, notes: [...layers.flatMap(layer => layer.notes), ...normalized.notes] };
 }
+/** Restore the single-call requirement the published batch schema intentionally omits, from the
+ * wrapped tool's own schema. Normalize first so repaired spellings and domain aliases satisfy it.
+ * @throws ToolInputError with every required name/type when any required value is missing.
+ * @complexity O(r) for r required fields, plus the existing normalization; no effects.
+ */
+async function normalizeSingleBatchInput({ input, registration }) {
+    const normalized = await normalizeToolInput({ input, registration });
+    const value = normalized.input;
+    const schema = registration.descriptor.inputSchema;
+    const required = schema.required ?? [];
+    if (!isPlainObject(value) || required.every(name => value[name] !== undefined))
+        return normalized;
+    const missing = required.filter(name => value[name] === undefined);
+    const fields = required.map(name => `${name} (${schemaTypeLabel(schema.properties?.[name])})`);
+    throw new ToolInputError({ message: `${registration.descriptor.id}: missing required inputs: ${missing.join(', ')}. Required inputs: ${fields.join(', ')}.` });
+}
+/** A property's declared JSON type, `a | b` for a type list, `unknown` when undeclared. */
+function schemaTypeLabel(property) {
+    const type = isPlainObject(property) ? property.type : undefined;
+    if (Array.isArray(type))
+        return type.join(' | ');
+    return typeof type === 'string' ? type : 'unknown';
+}
+/** A batch result is one JSON value, so an item's MCP `image` block would reach the model and the
+ * chat as base64 text (a 20-item import batch, 20 previews). Drop images from item envelopes; the
+ * item's text blocks still carry its result. Anything that is not an envelope is returned as is. */
+function withoutItemImages(output) {
+    if (!isPlainObject(output) || !Array.isArray(output.content))
+        return output;
+    const content = output.content.filter((block) => !isPlainObject(block) || block.type !== 'image');
+    return content.length === output.content.length ? output : { ...output, content };
+}
 /** Classify one returned output without dropping error payloads or normalization notes.
  * @complexity O(n) for a nested batch's n results, plus formatting its notes; no effects.
  */
@@ -158,7 +216,7 @@ export function withBatchInput({ registration, tool }, { mode = 'items' } = {})
             // its policy and planner receive the same targets; never execute items to preflight them.
             normalizeInput: async ({ input }) => {
                 if (!Object.hasOwn(input, 'items'))
-                    return normalizeToolInput({ input, registration });
+                    return normalizeSingleBatchInput({ input, registration });
                 const { items: rawItems, ...shared } = input;
                 const items = readItems({ items: rawItems, toolId, maxItems });
                 const normalized = [];
@@ -189,7 +247,7 @@ export function withBatchInput({ registration, tool }, { mode = 'items' } = {})
                 if (!options?.invokeTool)
                     throw new Error(`${toolId}: batch items require the gated ToolExecutor invocation port`);
                 const output = await options.invokeTool({ toolId, input: normalized.input }, { registry: itemRegistry });
-                results.push(batchItemResult({ index, output, notes: normalized.notes }));
+                results.push(batchItemResult({ index, output: withoutItemImages(output), notes: normalized.notes }));
             }
             catch (error) {
                 results.push({ index, ok: false, error: withNormalizationNotes({ output: itemErrorMessage({ error, toolId }), notes }) });
@@ -199,9 +257,9 @@ export function withBatchInput({ registration, tool }, { mode = 'items' } = {})
     };
     return { ...registration, descriptor, handler,
         // Domain normalization belongs to each merged item, not the incomplete shared layer.
-        normalizeInput: async ({ input }, options) => Object.hasOwn(input, 'items') || !registration.normalizeInput
+        normalizeInput: async ({ input }) => Object.hasOwn(input, 'items')
             ? { input, notes: [] }
-            : registration.normalizeInput({ input }, options),
+            : normalizeSingleBatchInput({ input, registration }),
     };
 }
 /**

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
 export * from './surface-exchanges.js';
-export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
+export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolExecutionOptions, ToolApprovalDecision, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
 export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, toolDiscoveryMetadata, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
 export * from './tool-exposure.js';
@@ -30,6 +30,6 @@ export * from "./native-regexp.js";
 export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, type LegacyToolAuthorizeFn, type AuthorizationPort as ToolPermissionAuthorizationPort, type RequireToolPermissionRequired, type RequireToolPermissionOptional, } from "./tool-permissions.js";
 export { evaluateFeatureFlag, type FeatureFlagDecision } from './feature-flags.js';
 export { normalizeToolInput, withNormalizationNotes, ToolInputNormalizationError, type NormalizedToolInput, type ToolInputNormalizer } from './tool-input-normalization.js';
-export { applyBatchInputs, BATCH_GUIDANCE_MARKER, withoutBatchGuidance, batchOutcomeFor, batchDescriptorFor, batchEligibilityFor, defaultBatchableTools, withBatchInput, DEFAULT_MAX_BATCH_ITEMS, type BatchableTool, type BatchEligibility, type BatchOptOut, type BatchResult, type BatchItemResult } from './batch-tool-inputs.js';
+export { applyBatchInputs, BATCH_GUIDANCE_MARKER, withoutBatchGuidance, batchOutcomeFor, batchDescriptorFor, batchItemRequiredFields, batchEligibilityFor, defaultBatchableTools, withBatchInput, DEFAULT_MAX_BATCH_ITEMS, type BatchableTool, type BatchEligibility, type BatchOptOut, type BatchResult, type BatchItemResult } from './batch-tool-inputs.js';
 export type { MediaProviderCatalogPolicy, MediaProviderOption, ProviderPreset, ProviderPresetKind } from './provider-catalog.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -25,5 +25,5 @@ export * from "./native-regexp.js";
 export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, } from "./tool-permissions.js";
 export { evaluateFeatureFlag } from './feature-flags.js';
 export { normalizeToolInput, withNormalizationNotes, ToolInputNormalizationError } from './tool-input-normalization.js';
-export { applyBatchInputs, BATCH_GUIDANCE_MARKER, withoutBatchGuidance, batchOutcomeFor, batchDescriptorFor, batchEligibilityFor, defaultBatchableTools, withBatchInput, DEFAULT_MAX_BATCH_ITEMS } from './batch-tool-inputs.js';
+export { applyBatchInputs, BATCH_GUIDANCE_MARKER, withoutBatchGuidance, batchOutcomeFor, batchDescriptorFor, batchItemRequiredFields, batchEligibilityFor, defaultBatchableTools, withBatchInput, DEFAULT_MAX_BATCH_ITEMS } from './batch-tool-inputs.js';
 //# sourceMappingURL=index.js.map

package/dist/optional-peer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Load a host-selected feature's optional library, synchronously or asynchronously.
+ * Keep the import/require literal in the caller so bundlers and closure guards can see it.
+ * @throws A feature-specific load error with the original resolution/ABI error as `cause`.
+ * @complexity O(1) wrapper work; loading cost belongs to the supplied loader.
+ */
+export declare function loadOptionalPeer<T>({ feature, dependency, load }: {
+    feature: string;
+    dependency: string;
+    load: () => T;
+}, { createError }?: {
+    createError?: (input: {
+        message: string;
+        cause: unknown;
+    }) => Error;
+}): T;
+//# sourceMappingURL=optional-peer.d.ts.map

package/dist/optional-peer.js

@@ -0,0 +1,40 @@
+/**
+ * Load a host-selected feature's optional library, synchronously or asynchronously.
+ * Keep the import/require literal in the caller so bundlers and closure guards can see it.
+ * @throws A feature-specific load error with the original resolution/ABI error as `cause`.
+ * @complexity O(1) wrapper work; loading cost belongs to the supplied loader.
+ */
+export function loadOptionalPeer({ feature, dependency, load }, { createError = ({ message, cause }) => new Error(message, { cause }) } = {}) {
+    const failed = (cause) => {
+        throw createError({ message: optionalPeerLoadMessage({ feature, dependency, cause }), cause });
+    };
+    try {
+        const library = load();
+        // Native import() returns a Promise. Synchronous factories must keep their return contract.
+        if (library instanceof Promise)
+            return library.catch(failed);
+        return library;
+    }
+    catch (cause) {
+        return failed(cause);
+    }
+}
+/** Classify loader failures without echoing paths or other untrusted driver diagnostics.
+ * Resolution of an internal dependency is not evidence the selected peer is absent.
+ * Pure; O(1) branches and O(message length) matching; no errors or side effects. */
+function optionalPeerLoadMessage({ feature, dependency, cause }, _options = {}) {
+    const prefix = `${feature} could not load ${dependency}.`;
+    const { message: detail = '', code } = cause instanceof Error ? cause : {};
+    if (/NODE_MODULE_VERSION|compiled against a different Node\.js version/.test(detail)) {
+        return `${prefix} Its native binary was built for a different Node.js/Electron ABI. Rebuild ${dependency} for the host runtime.`;
+    }
+    if (code === 'ERR_DLOPEN_FAILED') {
+        return `${prefix} Its native binary is incompatible with this runtime or architecture. Rebuild ${dependency} for the host runtime.`;
+    }
+    const missing = code === 'MODULE_NOT_FOUND' || code === 'ERR_MODULE_NOT_FOUND';
+    if (missing && (detail.includes(`Cannot find module '${dependency}'`) || detail.includes(`Cannot find package '${dependency}'`))) {
+        return `${prefix} It is not installed. Install ${dependency} to enable this feature.`;
+    }
+    return `${prefix} Check its installed dependencies and native binaries.`;
+}
+//# sourceMappingURL=optional-peer.js.map

package/dist/tool-registry.d.ts

@@ -160,13 +160,17 @@ export interface ToolExecutionContext {
     readonly input: unknown;
     readonly signal: AbortSignal;
 }
+/** Value-free human-dialog outcomes recorded by the executor; never authorization grants. */
+export type ToolApprovalDecision = 'approved' | 'declined' | 'expired' | 'abandoned';
 /** Optional handler ports supplied by the invoking transport. */
 export interface ToolExecutionOptions {
     readonly emitSurface?: SurfaceEmitter;
     /** Reports the human wait to the executor so concurrent writes can be refused. This is
-     * notification only; it never supplies a confirmation decision or grants authority. */
+     * notification only; it never grants authority or substitutes for the human dialog. */
     readonly onApprovalStateChange?: (required: {
         pending: boolean;
+        /** Bound frontend's human-dialog outcome; observation only, never an authorization grant. */
+        decision?: ToolApprovalDecision;
     }, optional?: Record<string, never>) => void;
     /** Invoke through the same executor, retaining this call's principal, run, cancellation and
      * transport gates. Rejects on denial, failed confirmation, validation or execution failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "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": {
@@ -28,7 +28,8 @@
       "./settings": "universal",
       "./settings/express": "node",
       "./plugin-directory": "universal",
-      "./filesystem": "universal"
+      "./filesystem": "universal",
+      "./optional-peer": "universal"
     },
     "isolation": {
       "entries": {
@@ -161,6 +162,11 @@
       "types": "./dist/filesystem.d.ts",
       "import": "./dist/filesystem.js",
       "default": "./dist/filesystem.js"
+    },
+    "./optional-peer": {
+      "types": "./dist/optional-peer.d.ts",
+      "import": "./dist/optional-peer.js",
+      "default": "./dist/optional-peer.js"
     }
   },
   "files": [
@@ -187,14 +193,6 @@
     "express": "^4.21.0",
     "@types/express": "^4.17.21"
   },
-  "peerDependencies": {
-    "express": "^4.21.0 || ^5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "express": {
-      "optional": true
-    }
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",