@jini-ai/core 0.6.15-rc.2 → 0.6.16

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @jini-ai/core
 
+## 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
+
+- Export async WebCrypto `canonicalArgumentDigest` from `@jini-ai/core/records`, reusing
+  `canonicalJson` for identical plugin and host SHA-256 hex digests. Canonical JSON now
+  sorts keys recursively by Unicode code point and throws `CanonicalJsonError` for
+  non-JSON values and cycles; undefined object properties remain omitted.
+
+  MCP approval fingerprints reuse the core serializer. Existing ordinary JSON
+  fingerprints retain their bytes; non-JSON schemas now fail instead of colliding
+  with valid JSON, and astral object keys follow the shared code-point ordering.
+
+- Export generic tool-contributor, derived-contributor and paired-registry contracts
+  from the existing contribution-registry owner without coupling core to host surfaces.
+
 ## 0.6.13
 
 ### Patch 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;
@@ -15,11 +17,13 @@ export type ApprovalAnswer = {
     reason: 'declined' | 'expired' | 'abandoned';
 };
 /** 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. */
+ * 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.
+ * @complexity O(1) local time/space plus the injected human transport's wait. */
 export declare function resolveApproval({ signal, askHuman }: {
     signal: AbortSignal;
     askHuman: () => Promise<ApprovalAnswer>;
-}, _optional?: {}): Promise<ApprovalAnswer>;
+}, { onApprovalStateChange }?: Pick<ToolExecutionOptions, 'onApprovalStateChange'>): Promise<ApprovalAnswer>;
 export interface RememberedApprovalPort {
     has(required: {
         ctx: ToolExecutionContext;
@@ -101,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;
@@ -115,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;
@@ -124,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,20 +1,26 @@
 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. */
-export async function resolveApproval({ signal, askHuman }, _optional = {}) {
+ * 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.
+ * @complexity O(1) local time/space plus the injected human transport's wait. */
+export async function resolveApproval({ signal, askHuman }, { onApprovalStateChange } = {}) {
     if (signal.aborted)
         return { confirmed: false, reason: 'abandoned' };
     let abandon;
     const aborted = new Promise(resolve => { abandon = () => resolve({ confirmed: false, reason: 'abandoned' }); });
     signal.addEventListener('abort', abandon, { once: true });
     try {
+        onApprovalStateChange?.({ pending: true });
         const answer = await Promise.race([askHuman(), aborted]);
         return signal.aborted ? { confirmed: false, reason: 'abandoned' } : answer;
     }
     finally {
         signal.removeEventListener('abort', abandon);
+        onApprovalStateChange?.({ pending: false });
     }
 }
 /** The confirmer is always the run's own delegating principal, as a user. */
@@ -38,7 +44,7 @@ export function createApprovalHandler(steps, { remembered } = {}) {
     /** Ask the host transport; record the choice and any reusable grant only on an explicit yes. */
     const askFresh = async ({ prepared, plan }, options = {}) => {
         const { ctx } = prepared;
-        const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) });
+        const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) }, options);
         if (ctx.signal.aborted)
             return abandoned(prepared);
         if (answer.confirmed !== true)
@@ -153,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' };
@@ -192,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 top-level `required` fields {@link batchDescriptorFor} moved into its `items` description.
+ * 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(n) in the items description length; 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,

package/dist/batch-tool-inputs.js

@@ -16,6 +16,22 @@ 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).";
+/** The top-level `required` fields {@link batchDescriptorFor} moved into its `items` description.
+ * 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(n) in the items description length; pure. */
+export function batchItemRequiredFields({ inputSchema }, _optional = {}) {
+    const items = isPlainObject(inputSchema) && isPlainObject(inputSchema.properties) ? inputSchema.properties.items : undefined;
+    const text = isPlainObject(items) && typeof items.description === "string" ? items.description : "";
+    const start = text.indexOf(ITEM_NEEDS);
+    const end = text.indexOf(ITEM_NEEDS_END, start);
+    if (start === -1 || end === -1)
+        return [];
+    return text.slice(start + ITEM_NEEDS.length, end).split(", ");
+}
 /** 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.
@@ -26,7 +42,13 @@ export function batchOutcomeFor({ output }, _options = {}) {
     if (!isPlainObject(output) || output.batch !== true || !Array.isArray(output.results) || output.results.length === 0)
         return undefined;
     const failed = output.results.filter(item => isPlainObject(item) && item.ok === false).length;
-    return failed === 0 ? 'completed' : failed === output.results.length ? 'error' : 'partial_failure';
+    return outcomeFor({ failed, total: output.results.length });
+}
+/** No failure completes the batch, all failing is an error, anything between is partial. */
+function outcomeFor({ failed, total }) {
+    if (failed === 0)
+        return 'completed';
+    return failed === total ? 'error' : 'partial_failure';
 }
 /** A JSON object: not null, not an array. */
 function isPlainObject(value) {
@@ -54,8 +76,9 @@ export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
     }
     const maxItems = tool.maxItems ?? DEFAULT_MAX_BATCH_ITEMS;
     const requiredFields = schema.required ?? [];
-    const { required: _required, ...rest } = schema;
-    const needs = requiredFields.length > 0 ? ` Each item needs ${requiredFields.join(", ")} (inside each item).` : "";
+    const rest = { ...schema };
+    delete rest.required;
+    const needs = requiredFields.length > 0 ? `${ITEM_NEEDS}${requiredFields.join(", ")}${ITEM_NEEDS_END}` : "";
     const items = {
         type: "array",
         minItems: 1,
@@ -104,6 +127,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.
  */
@@ -119,7 +174,7 @@ function batchItemResult({ index, output, notes }, _options = {}) {
  */
 function summarizeBatchResults({ results }, _options = {}) {
     const succeeded = results.filter((result) => result.ok).length;
-    const outcome = succeeded === results.length ? 'completed' : succeeded === 0 ? 'error' : 'partial_failure';
+    const outcome = outcomeFor({ failed: results.length - succeeded, total: results.length });
     return { batch: true, outcome, ...(succeeded === 0 ? { isError: true } : {}), total: results.length, succeeded, failed: results.length - succeeded, results };
 }
 /**
@@ -151,7 +206,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 = [];
@@ -182,7 +237,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 }) });
@@ -192,9 +247,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/contribution-registry.d.ts

@@ -1,3 +1,26 @@
+import type { DerivedRiskByToolId } from './registration-kit.js';
+import type { ToolRegistration } from './tool-registry.js';
+/** A domain owns its builder and risk classification; the host binds dependencies and surfaces. */
+export interface ToolContributor<TDeps, TSurfaces> {
+    readonly domain: string;
+    readonly build: (deps: TDeps, surfaces: TSurfaces) => ToolRegistration[];
+    readonly risk: DerivedRiskByToolId;
+}
+/** Post-processing sees the domain registrations; ordering and collision checks belong to the host. */
+export interface DerivedToolContributor<TDeps, TSurfaces> {
+    readonly domain: string;
+    readonly derive: (input: {
+        readonly registrations: readonly ToolRegistration[];
+        readonly routeDeps: TDeps;
+        readonly surfaces: TSurfaces;
+    }) => ToolRegistration[];
+    readonly risk: DerivedRiskByToolId;
+}
+/** The two ordered registries belong to one composition root, never shared across workspaces. */
+export interface ToolContributions<TDeps, TSurfaces> {
+    readonly contributors: ContributionRegistry<ToolContributor<TDeps, TSurfaces>>;
+    readonly derivedContributors: ContributionRegistry<DerivedToolContributor<TDeps, TSurfaces>>;
+}
 /** Replace-by-key registry for host-owned contributions; no singleton or execution surface. */
 export interface ContributionRegistry<TContribution> {
     register(required: {

package/dist/fetch/cache.d.ts

@@ -110,6 +110,7 @@ export declare class FetchQueryCache {
     invalidate({ prefix }: {
         prefix: QueryKey;
     }): void;
+    private reloadInvalidated;
     onFocus(): void;
     /** Execute a read/write once connectivity returns; failures are not retried.
      * @param required.run Operation to invoke online.

package/dist/fetch/cache.js

@@ -16,7 +16,9 @@ const browserScheduler = {
 // Normalize unknown promise rejections once so consumers receive Error without repeating
 // the same narrowing boilerplate at every read and write call site.
 export function toQueryError(value) {
-    return value instanceof Error ? value : new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
+    if (value instanceof Error)
+        return value;
+    return new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
 }
 /** One provider-owned cache. Requests are shared by structural primitive keys.
  * Failed reads retain earlier data; replacement writes supersede older requests.
@@ -162,12 +164,17 @@ export class FetchQueryCache {
             const pendingRead = entry.pendingRead;
             entry.pending = undefined;
             entry.pendingRead = undefined;
-            if (entry.observers.size)
-                this.refresh(entry);
-            // An awaiting loader still needs an answer even if no observer is mounted.
-            else if (pendingRead)
-                void this.load({ entry, ...pendingRead });
+            this.reloadInvalidated(entry, pendingRead);
+        }
+    }
+    reloadInvalidated(entry, pendingRead) {
+        if (entry.observers.size) {
+            this.refresh(entry);
+            return;
         }
+        // An awaiting loader still needs an answer even if no observer is mounted.
+        if (pendingRead)
+            void this.load({ entry, ...pendingRead });
     }
     onFocus() {
         for (const entry of this.entries.values()) {
@@ -249,7 +256,8 @@ export class FetchQueryCache {
     }
     scheduleEviction(entry) {
         this.cancelEviction(entry);
-        if (this.disposed || entry.listeners.size || entry.observers.size || entry.pending || !Number.isFinite(entry.retention))
+        const inUse = entry.listeners.size > 0 || entry.observers.size > 0 || Boolean(entry.pending);
+        if (this.disposed || inUse || !Number.isFinite(entry.retention))
             return;
         entry.eviction = this.scheduler.schedule({ callback: () => this.entries.delete(JSON.stringify(entry.key)), delayMs: entry.retention });
     }

package/dist/index.d.ts

@@ -11,13 +11,14 @@ 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';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
-export * from './contribution-registry.js';
+export { createContributionRegistry } from './contribution-registry.js';
+export type { ContributionRegistry, ToolContributor, DerivedToolContributor, ToolContributions } from './contribution-registry.js';
 export * from './provider-registry.js';
 export * from './object-store.js';
 export * from './naming.js';
@@ -29,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

@@ -14,7 +14,7 @@ export * from './tool-tokens.js';
 export * from './tool-exposure.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
-export * from './contribution-registry.js';
+export { createContributionRegistry } from './contribution-registry.js';
 export * from './provider-registry.js';
 export * from './object-store.js';
 export * from './naming.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/origin-validation.js

@@ -134,7 +134,13 @@ function parseDottedQuad(host) {
 }
 /** RFC 1918 (10/8, 172.16/12, 192.168/16) or link-local (169.254/16), from the first two octets. */
 function isPrivateIpv4Prefix([a, b]) {
-    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    if (a === 10)
+        return true;
+    if (a === 172)
+        return b >= 16 && b <= 31;
+    if (a === 192)
+        return b === 168;
+    return a === 169 && b === 254;
 }
 /** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16).
  * Implements the dev-browser LAN allow-list, not SSRF blocking. Use @jini-ai/platform/net
@@ -152,17 +158,12 @@ export function isIpLiteralHostname({ hostname }) {
         return true;
     return parseDottedQuad(host) !== undefined;
 }
+const LOOPBACK_OR_UNSPECIFIED_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0', '::']);
 /** Whether `hostname` is loopback, unspecified, or a private-LAN address.
  * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
 export function isLoopbackOrPrivateLanHost({ hostname }) {
     const host = String(hostname || '').toLowerCase();
-    return (host === 'localhost' ||
-        host === '127.0.0.1' ||
-        host === '::1' ||
-        host === '[::1]' ||
-        host === '0.0.0.0' ||
-        host === '::' ||
-        isPrivateIpv4({ hostname: host }));
+    return LOOPBACK_OR_UNSPECIFIED_HOSTS.has(host) || isPrivateIpv4({ hostname: host });
 }
 /** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
 export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowedOrigins }) {

package/dist/primitives/index.d.ts

@@ -8,4 +8,5 @@ export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
 export * from './tasks.js';
+export { trimChars, trimCharsEnd, trimCharsStart } from './trim-chars.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.js

@@ -7,4 +7,5 @@ export * from './logger.js';
 export * from './result.js';
 export * from './paths.js';
 export * from './tasks.js';
+export { trimChars, trimCharsEnd, trimCharsStart } from './trim-chars.js';
 //# sourceMappingURL=index.js.map

package/dist/primitives/paths.js

@@ -1,3 +1,4 @@
+import { trimCharsEnd } from './trim-chars.js';
 /** 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];
@@ -22,7 +23,7 @@ function normalizeAbsolutePath(value, separator) {
     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('/');
+    return trimCharsEnd({ text: prefix, chars: '/' }) + '/' + resolveSegments(path.slice(prefix.length)).join('/');
 }
 /**
  * Check lexical containment using whole directory segments, including equality.