@jini-ai/core 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @jini-ai/core
 
+## 0.4.9 — 2026-10-22
+
+- 2026-10-22: Provider registry, ObjectStore contract with object_store registry and deferObjectStore, default-on batch tool eligibility, coverage.
+
+- New `./object-store` (also on the root): the one `ObjectStore` contract (put with atomic `ifAbsent` / get→null / head / delete, optional `publicAccess`), `ObjectStoreProvider.create()` returning `ProviderResult`, and `createObjectStoreRegistry()` (contract `object_store`, default `local`). Absorbs cms `BlobStorePort`, capability-providers `StorageProvider`, devops `ArtifactStorePort` and platform `BlobStorage` as views.
+- New `./provider-registry` (also on the root): `createProviderRegistry<T>()` — keyed register/get/has/list/getDefault, frozen entries, core registrations throw while plugin contributions are recorded in `refusals()` — plus shared `ProviderResult<T>`, `ProviderContext` and `DomainRequirement` types. Frozen contract: `docs/provider-registry.md`. `contribute()` turns a throwing validator or provider/id getter into an `invalid_provider` refusal; every public method and the `providerOk`/`providerRejected`/`providerUnknown` factories take the reserved optional object.
+
+## 0.4.8 — 2026-10-16
+
+- `applyTargetScope`: one optional `site` input on read-only tools; the host resolves the target and a peer handler/principal, writes refuse a foreign target (3786c8f0).
+
 ## 0.4.7 — 2026-10-16
 
 - `requireString`, `requireNumber` and `requireObject` errors list the keys the call actually received and flag unsupported `items[]` batching (a6ac9d7e, c7557838).

package/dist/agent-tools.d.ts

@@ -16,7 +16,7 @@ export type AgentToolSideEffect = "none" | "mutates-durable-state" | "deletes-du
 export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
 /** Structural catalog contract. Domains may require inputSchema or tighten their own metadata. */
 export interface AgentToolDefinition {
-    readonly metadata?: import('./tool-metadata.js').ToolMetadata;
+    readonly metadata?: import('./tool-metadata-types.js').ToolMetadata;
     name: string;
     description: string;
     sideEffects: AgentToolSideEffect;

package/dist/approval.d.ts

@@ -69,6 +69,21 @@ export interface ApprovalSteps<TPrepared, TDescription> {
 export declare function createApprovalHandler<TPrepared, TDescription>(steps: ApprovalSteps<TPrepared, TDescription>, { remembered }?: {
     remembered?: RememberedApprovalPort;
 }): 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
+ * failure; earlier effects are not rolled back. No remembered approval is accepted for a batch.
+ * @throws ToolInputError for malformed, duplicate or over-cap batches, before preparation/effects.
+ * @complexity O(s + n p log p) local time and O(s) snapshot space for s input/description bytes,
+ * p top-level fields per item and n items (default cap 25), plus the injected preparation/effects. */
+export declare function createBatchApprovalHandler<TPrepared, TDescription>({ steps, combineDescriptions }: {
+    steps: ApprovalSteps<TPrepared, TDescription>;
+    combineDescriptions(input: {
+        descriptions: readonly TDescription[];
+    }): TDescription;
+}, { maxItems }?: {
+    maxItems?: number;
+}): ToolHandler;
 /** Page-local proposal transport for a browser that must return before its explicit reply arrives.
  * It carries no principal or tool authorization: the host's execute port must re-check access.
  * The private action is independent of the rendered snapshot; replies consume it before awaiting

package/dist/approval.js

@@ -1,4 +1,5 @@
-import { humanConfirmedHandler } from './registration-kit.js';
+import { humanConfirmedHandler, requireInputRecord } from './registration-kit.js';
+import { ToolInputError } from './tool-registry.js';
 /** 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 = {}) {
@@ -15,6 +16,8 @@ export async function resolveApproval({ signal, askHuman }, _optional = {}) {
         signal.removeEventListener('abort', abandon);
     }
 }
+/** The confirmer is always the run's own delegating principal, as a user. */
+const confirmerOf = (ctx) => ({ id: ctx.principal.id, kind: 'user' });
 /** Extend the branded human-confirm owner with descriptions and optional remembered grants.
  * Inputs and actor identity are detached before any asynchronous port runs. No input field can
  * approve an action; only the host transport or the bound grant store can answer. Abort checks
@@ -27,6 +30,24 @@ export async function resolveApproval({ signal, askHuman }, _optional = {}) {
  * @example createApprovalHandler({ prepare, describe, askHuman, run, notConfirmed });
  */
 export function createApprovalHandler(steps, { remembered } = {}) {
+    const confirmed = () => ({ confirmed: true });
+    const abandoned = (prepared) => ({ confirmed: false, result: steps.notConfirmed({ reason: 'abandoned', prepared: prepared.value }) });
+    /** A remembered grant applies only when the plan offers a key and the host bound a store. */
+    const grantSlot = (plan) => plan.rememberKey !== undefined && remembered ? { store: remembered, key: plan.rememberKey } : undefined;
+    /** 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) });
+        if (ctx.signal.aborted)
+            return abandoned(prepared);
+        if (answer.confirmed !== true)
+            return { confirmed: false, result: steps.notConfirmed({ reason: answer.reason, prepared: prepared.value }) };
+        prepared.choice = answer.choice;
+        const slot = grantSlot(plan);
+        if (slot)
+            await slot.store.grant({ ctx, key: slot.key, confirmer: confirmerOf(ctx) });
+        return ctx.signal.aborted ? abandoned(prepared) : confirmed();
+    };
     return humanConfirmedHandler({
         prepare: async ({ ctx }, options = {}) => {
             const snapshot = { ...ctx, input: structuredClone(ctx.input), principal: { ...ctx.principal }, run: { ...ctx.run } };
@@ -39,38 +60,82 @@ export function createApprovalHandler(steps, { remembered } = {}) {
             return { ctx: snapshot, value, plan };
         },
         askHuman: async ({ prepared }, options = {}) => {
-            const { ctx, plan, value } = prepared;
-            const abandoned = () => ({ confirmed: false, result: steps.notConfirmed({ reason: 'abandoned', prepared: value }) });
+            const { ctx, plan } = prepared;
             if (ctx.signal.aborted || !plan)
-                return abandoned();
+                return abandoned(prepared);
             if (!plan.ask)
-                return { confirmed: true };
-            if (plan.rememberKey !== undefined && remembered) {
-                const approved = await remembered.has({ ctx, key: plan.rememberKey });
+                return confirmed();
+            const slot = grantSlot(plan);
+            if (slot) {
+                const approved = await slot.store.has({ ctx, key: slot.key });
                 if (ctx.signal.aborted)
-                    return abandoned();
+                    return abandoned(prepared);
                 if (approved)
-                    return { confirmed: true };
-            }
-            const answer = await resolveApproval({ signal: ctx.signal, askHuman: () => steps.askHuman({ ctx, description: plan.description }, options) });
-            if (ctx.signal.aborted)
-                return abandoned();
-            if (answer.confirmed !== true)
-                return { confirmed: false, result: steps.notConfirmed({ reason: answer.reason, prepared: value }) };
-            prepared.choice = answer.choice;
-            if (plan.rememberKey !== undefined && remembered) {
-                await remembered.grant({ ctx, key: plan.rememberKey, confirmer: { id: ctx.principal.id, kind: 'user' } });
+                    return confirmed();
             }
-            if (ctx.signal.aborted)
-                return abandoned();
-            return { confirmed: true };
+            return askFresh({ prepared, plan }, options);
         },
         run: ({ prepared }, options = {}) => {
             const { ctx, value, choice } = prepared;
             if (ctx.signal.aborted)
                 return Promise.resolve(steps.notConfirmed({ reason: 'abandoned', prepared: value }));
-            return steps.run({ ctx, prepared: value, confirmer: { id: ctx.principal.id, kind: 'user' }, choice }, options);
+            return steps.run({ ctx, prepared: value, confirmer: confirmerOf(ctx), choice }, 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
+ * failure; earlier effects are not rolled back. No remembered approval is accepted for a batch.
+ * @throws ToolInputError for malformed, duplicate or over-cap batches, before preparation/effects.
+ * @complexity O(s + n p log p) local time and O(s) snapshot space for s input/description bytes,
+ * p top-level fields per item and n items (default cap 25), plus the injected preparation/effects. */
+export function createBatchApprovalHandler({ steps, combineDescriptions }, { maxItems = 25 } = {}) {
+    return createApprovalHandler({
+        prepare: async ({ ctx }, options) => {
+            const input = requireInputRecord({ input: ctx.input });
+            if (!Object.hasOwn(input, 'items'))
+                return { batch: false, entries: [{ ctx, prepared: await steps.prepare({ ctx }, options) }] };
+            const { items, ...defaults } = input;
+            if (!Array.isArray(items) || items.length < 1 || items.length > maxItems) {
+                throw new ToolInputError({ message: `items must contain between 1 and ${maxItems} inputs.` });
+            }
+            const contexts = items.map(item => {
+                const fields = requireInputRecord({ input: item });
+                if (Object.hasOwn(fields, 'items'))
+                    throw new ToolInputError({ message: 'Nested items batches are not supported.' });
+                return { ...ctx, input: { ...defaults, ...fields } };
+            });
+            // These boundary inputs are records; sorting their keys also catches reordered scalar ids.
+            const keys = contexts.map(({ input }) => JSON.stringify(Object.entries(input).sort(([a], [b]) => a.localeCompare(b))));
+            if (new Set(keys).size !== keys.length)
+                throw new ToolInputError({ message: 'Duplicate batch inputs are not allowed.' });
+            const entries = [];
+            for (const itemCtx of contexts)
+                entries.push({ ctx: itemCtx, prepared: await steps.prepare({ ctx: itemCtx }, options) });
+            return { batch: true, entries };
+        },
+        describe: async ({ prepared }, options) => {
+            const plans = [];
+            for (const entry of prepared.entries)
+                plans.push(await steps.describe(entry, options));
+            if (!prepared.batch)
+                return plans[0];
+            return { ask: true, description: combineDescriptions({ descriptions: plans.map(plan => plan.description) }) };
+        },
+        askHuman: steps.askHuman,
+        run: async ({ prepared, confirmer, choice }, options) => {
+            if (!prepared.batch)
+                return steps.run({ ...prepared.entries[0], confirmer, choice }, options);
+            const results = [];
+            for (const entry of prepared.entries) {
+                if (entry.ctx.signal.aborted)
+                    return steps.notConfirmed({ reason: 'abandoned' });
+                results.push(await steps.run({ ...entry, confirmer, choice }, options));
+            }
+            return { batch: true, total: results.length, results };
         },
+        notConfirmed: ({ reason, prepared }) => steps.notConfirmed({ reason, prepared: prepared?.batch ? undefined : prepared?.entries[0]?.prepared }),
     });
 }
 /** Page-local proposal transport for a browser that must return before its explicit reply arrives.

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

@@ -0,0 +1,147 @@
+/** Shared sequential batching. Each merged item re-enters the invoking executor's gates. */
+import { type ToolRegistration } from './tool-registry.js';
+/** One tool that accepts `items`. `itemDefaults` sit under the caller's own fields: a batch that
+ *  returns every item's full body could overflow one tool result, so a reader can default to a
+ *  smaller window per item that the caller may still raise. */
+export interface BatchableTool {
+    readonly toolId: string;
+    readonly maxItems?: number;
+    readonly itemDefaults?: Readonly<Record<string, unknown>>;
+    /** Host-specific result constraints, checked on the normalized item before its handler runs. */
+    readonly validateItem?: (required: {
+        input: unknown;
+    }) => void;
+}
+/** Where every batch descriptor's appended guidance starts. */
+export declare const BATCH_GUIDANCE_MARKER = " Batch: ";
+/** A description without {@link batchDescriptorFor}'s appended guidance, wherever it sits (a merged
+ * description may carry several), e.g. for a search index: the same boilerplate on most tools would
+ * otherwise dilute relevance. Other text is kept. @complexity O(n) in the description length. */
+export declare function withoutBatchGuidance({ description }: {
+    description: string;
+}, _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,
+ *  which the tool already publishes and which would otherwise repeat once per failed item. */
+export type BatchItemResult = {
+    readonly index: number;
+    readonly ok: true;
+    readonly result: unknown;
+} | {
+    readonly index: number;
+    readonly ok: false;
+    readonly error: string;
+    readonly result?: unknown;
+};
+/** What a batch call returns. A failed item never stops the ones after it. */
+export interface BatchResult {
+    readonly batch: true;
+    readonly outcome: 'completed' | 'partial_failure' | 'error';
+    readonly isError?: true;
+    readonly total: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly results: readonly BatchItemResult[];
+}
+/** Classify a batch result, including legacy envelopes, without dropping per-item evidence.
+ * @returns Undefined for non-batches; error when every item failed, partial_failure for a mix.
+ * @complexity O(n) in per-item results; no effects.
+ */
+export declare function batchOutcomeFor({ output }: {
+    output: unknown;
+}, _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.
+ *
+ * @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.
+ */
+export declare function batchDescriptorFor({ descriptor, tool }: {
+    descriptor: ToolRegistration["descriptor"];
+    tool: BatchableTool;
+}, _optional?: Record<string, never>): ToolRegistration["descriptor"];
+/**
+ * Wraps one registration so it also accepts `items`. Single calls retain their handler.
+ * Ordinary merged items re-enter the executor; plan batches normalize all items at the outer
+ * gate and retain their combined approval handler.
+ *
+ * @param required.registration - The registration to extend (already approval-wrapped).
+ * @param required.tool - Its batch settings.
+ * @param optional.mode - `plan` normalizes every merged item before policy, leaving the
+ * existing handler to prepare and confirm the combined plan once; `items` gates each item.
+ * @returns The registration with {@link batchDescriptorFor}'s descriptor and a batch-aware handler.
+ * @throws {Error} At composition time, per {@link batchDescriptorFor}. The returned handler throws
+ * {@link ToolInputError} for a malformed `items`, and `AbortError` if the call is cancelled between
+ * items; an item's own failure is reported in its result instead.
+ * @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 declare function withBatchInput({ registration, tool }: {
+    registration: ToolRegistration;
+    tool: BatchableTool;
+}, { mode }?: {
+    mode?: 'items' | 'plan';
+}): ToolRegistration;
+/**
+ * Applies {@link withBatchInput} to every listed tool present in `registrations`; every other
+ * registration is returned as the same object. A listed id that is not registered is skipped (a
+ * domain may be absent in a narrower composition, e.g. a test building one domain).
+ *
+ * @param required.registrations - The assembled registration list.
+ * @param optional.tools - Explicit host-owned batchable tool list.
+ * @returns A new list in the same order.
+ * @complexity O(r + b) for r registrations and b batchable tools.
+ */
+export declare function applyBatchInputs({ registrations }: {
+    registrations: readonly ToolRegistration[];
+}, { tools }?: {
+    tools?: readonly BatchableTool[];
+}): ToolRegistration[];
+/** A tool a host keeps single-call by default, with the one-line reason a reviewer reads. */
+export interface BatchOptOut {
+    readonly toolId: string;
+    readonly reason: string;
+}
+/** Why a registration is, or is not, batched by default. */
+export type BatchEligibility = 'batchable' | 'opted-out' | 'takes-items' | 'no-object-schema' | 'list-read';
+/**
+ * The default-on batch rule: every read-by-id and mutating tool takes `items` unless its host
+ * opts it out. Structural exclusions need no host entry: a tool with no object schema cannot take
+ * `items`, one that already has an `items` field would be shadowed by it, and a read-only tool with
+ * no required input (a list or search) has no per-item target to batch.
+ *
+ * @param required.registration - The registration to classify.
+ * @param optional.optOut - Host-owned tool ids kept single-call.
+ * @returns The first matching reason, or `batchable`.
+ * @complexity O(1) plus the schema's top-level `required` list; no effects.
+ */
+export declare function batchEligibilityFor({ registration }: {
+    registration: ToolRegistration;
+}, { optOut }?: {
+    optOut?: ReadonlySet<string>;
+}): BatchEligibility;
+/**
+ * Every registration {@link batchEligibilityFor} classifies as batchable, as {@link BatchableTool}
+ * entries. A host's per-tool `settings` (a raised `maxItems`, item defaults, item validation) are
+ * merged over the default entry; a settings entry never makes an ineligible tool batchable.
+ *
+ * @param required.registrations - The assembled registration list.
+ * @param optional.optOut - Host-owned tools kept single-call, each with its reason.
+ * @param optional.settings - Host-owned per-tool batch settings.
+ * @returns The batchable tools, in registration order.
+ * @complexity O(r + o + s) for r registrations, o opt-outs and s settings entries.
+ */
+export declare function defaultBatchableTools({ registrations }: {
+    registrations: readonly ToolRegistration[];
+}, { optOut, settings }?: {
+    optOut?: readonly BatchOptOut[];
+    settings?: readonly BatchableTool[];
+}): BatchableTool[];
+//# sourceMappingURL=batch-tool-inputs.d.ts.map

package/dist/batch-tool-inputs.js

@@ -0,0 +1,257 @@
+/** Shared sequential batching. Each merged item re-enters the invoking executor's gates. */
+import { createToolRegistry, isReadOnlyTool } from './tool-registry.js';
+import { ToolInputError } from './tool-input-errors.js';
+import { canonicalizeToolInputKeys, normalizeToolInput, withNormalizationNotes } from './tool-input-normalization.js';
+/** Where every batch descriptor's appended guidance starts. */
+export const BATCH_GUIDANCE_MARKER = " Batch: ";
+const BATCH_GUIDANCE_END = "one item's failure does not stop the others.";
+/** A description without {@link batchDescriptorFor}'s appended guidance, wherever it sits (a merged
+ * description may carry several), e.g. for a search index: the same boilerplate on most tools would
+ * otherwise dilute relevance. Other text is kept. @complexity O(n) in the description length. */
+export function withoutBatchGuidance({ description }, _optional = {}) {
+    return description.split(`${BATCH_GUIDANCE_MARKER}to do several at once,`).map((part, index) => {
+        if (index === 0)
+            return part;
+        const end = part.indexOf(BATCH_GUIDANCE_END);
+        return end === -1 ? `${BATCH_GUIDANCE_MARKER}to do several at once,${part}` : part.slice(end + BATCH_GUIDANCE_END.length);
+    }).join("");
+}
+/** 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.
+ * @returns Undefined for non-batches; error when every item failed, partial_failure for a mix.
+ * @complexity O(n) in per-item results; no effects.
+ */
+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';
+}
+/** A JSON object: not null, not an array. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(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.
+ *
+ * @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.
+ */
+export function batchDescriptorFor({ descriptor, tool }, _optional = {}) {
+    const schema = descriptor.inputSchema;
+    if (!isPlainObject(schema) || !isPlainObject(schema.properties)) {
+        throw new Error(`batch-tool-inputs.ts: '${descriptor.id}' publishes no object inputSchema, so it cannot take items`);
+    }
+    if (Object.hasOwn(schema.properties, "items")) {
+        throw new Error(`batch-tool-inputs.ts: '${descriptor.id}' already has an 'items' input, so the batch field would shadow it`);
+    }
+    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 items = {
+        type: "array",
+        minItems: 1,
+        maxItems,
+        description: `Batch: up to ${maxItems} inputs run in ONE call, in order. Each item takes the same fields as a single call; ` +
+            `Canonical shape: {items:[{...}, ...]} only. Legacy shared top-level fields are normalized into each item before execution; an item's own value wins.${needs}`,
+        items: { type: "object", description: "One item: the same fields as a single call of this tool." },
+    };
+    return {
+        ...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. " +
+            "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 } },
+    };
+}
+/** The domain message without `withSchemaOnRejection`'s appended schema: the text before the
+ * first schema marker, or the whole message when no schema was appended. */
+function itemErrorMessage({ error, toolId }) {
+    const message = error instanceof Error ? error.message : String(error);
+    const schemaAt = message.indexOf(` Schema for '${toolId}': `);
+    return schemaAt === -1 ? message : message.slice(0, schemaAt);
+}
+/** Validates the batch half of an input and returns its items, or throws a caller-actionable error. */
+function readItems({ items, toolId, maxItems }) {
+    if (!Array.isArray(items) || items.length === 0) {
+        throw new ToolInputError({ message: `${toolId}: 'items' must be a non-empty array of inputs` });
+    }
+    if (items.length > maxItems) {
+        throw new ToolInputError({ message: `${toolId}: 'items' has ${items.length} entries; the most one call takes is ${maxItems}. Split them into several calls.` });
+    }
+    const bad = items.findIndex((item) => !isPlainObject(item));
+    if (bad !== -1)
+        throw new ToolInputError({ message: `${toolId}: items[${bad}] must be an object of this tool's input fields` });
+    return items;
+}
+/** Defaults < shared fields < item, after resolving spellings independently in each layer.
+ * Domain aliases, scalar conversion and closed-schema rejection run on the final merged input.
+ * @throws ToolInputError on a collision within any layer or invalid final input.
+ * @complexity Three bounded schema walks plus the registered normalizer's cost.
+ */
+async function normalizeBatchItem({ registration, defaults, shared, item }) {
+    const schema = registration.descriptor.inputSchema;
+    const layers = [defaults ?? {}, shared, item].map(input => canonicalizeToolInputKeys({ input, schema }));
+    const input = { ...layers[0].input, ...layers[1].input, ...layers[2].input };
+    const normalized = await normalizeToolInput({ input, registration });
+    return { input: normalized.input, notes: [...layers.flatMap(layer => layer.notes), ...normalized.notes] };
+}
+/** 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.
+ */
+function batchItemResult({ index, output, notes }, _options = {}) {
+    const outcome = batchOutcomeFor({ output });
+    if (isPlainObject(output) && (output.isError === true || outcome === 'error' || outcome === 'partial_failure')) {
+        return { index, ok: false, error: typeof output.error === 'string' ? output.error : 'item returned an error', result: output };
+    }
+    return { index, ok: true, result: withNormalizationNotes({ output, notes }) };
+}
+/** Summarize all item outcomes, retaining their order and evidence.
+ * @complexity O(n) time and space for n results; no effects.
+ */
+function summarizeBatchResults({ results }, _options = {}) {
+    const succeeded = results.filter((result) => result.ok).length;
+    const outcome = succeeded === results.length ? 'completed' : succeeded === 0 ? 'error' : 'partial_failure';
+    return { batch: true, outcome, ...(succeeded === 0 ? { isError: true } : {}), total: results.length, succeeded, failed: results.length - succeeded, results };
+}
+/**
+ * Wraps one registration so it also accepts `items`. Single calls retain their handler.
+ * Ordinary merged items re-enter the executor; plan batches normalize all items at the outer
+ * gate and retain their combined approval handler.
+ *
+ * @param required.registration - The registration to extend (already approval-wrapped).
+ * @param required.tool - Its batch settings.
+ * @param optional.mode - `plan` normalizes every merged item before policy, leaving the
+ * existing handler to prepare and confirm the combined plan once; `items` gates each item.
+ * @returns The registration with {@link batchDescriptorFor}'s descriptor and a batch-aware handler.
+ * @throws {Error} At composition time, per {@link batchDescriptorFor}. The returned handler throws
+ * {@link ToolInputError} for a malformed `items`, and `AbortError` if the call is cancelled between
+ * items; an item's own failure is reported in its result instead.
+ * @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' } = {}) {
+    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.`,
+            },
+            // 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.
+            normalizeInput: async ({ input }) => {
+                if (!Object.hasOwn(input, 'items'))
+                    return normalizeToolInput({ input, registration });
+                const { items: rawItems, ...shared } = input;
+                const items = readItems({ items: rawItems, toolId, maxItems });
+                const normalized = [];
+                for (const item of items) {
+                    const result = await normalizeBatchItem({ registration, defaults: tool.itemDefaults, shared, item });
+                    tool.validateItem?.({ input: result.input });
+                    normalized.push(result);
+                }
+                return { input: { items: normalized.map(item => item.input) }, notes: normalized.flatMap(item => item.notes) };
+            },
+        };
+    const original = registration.handler;
+    const itemRegistry = createToolRegistry({});
+    itemRegistry.register(registration);
+    const handler = async (ctx, options) => {
+        if (!isPlainObject(ctx.input) || !Object.hasOwn(ctx.input, "items"))
+            return original(ctx, options);
+        const { items: rawItems, ...shared } = ctx.input;
+        const items = readItems({ items: rawItems, toolId, maxItems });
+        const results = [];
+        for (const [index, item] of items.entries()) {
+            ctx.signal.throwIfAborted();
+            let notes = [];
+            try {
+                const normalized = await normalizeBatchItem({ registration, defaults: tool.itemDefaults, shared, item });
+                notes = normalized.notes;
+                tool.validateItem?.({ input: normalized.input });
+                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 }));
+            }
+            catch (error) {
+                results.push({ index, ok: false, error: withNormalizationNotes({ output: itemErrorMessage({ error, toolId }), notes }) });
+            }
+        }
+        return summarizeBatchResults({ results });
+    };
+    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
+            ? { input, notes: [] }
+            : registration.normalizeInput({ input }, options),
+    };
+}
+/**
+ * Applies {@link withBatchInput} to every listed tool present in `registrations`; every other
+ * registration is returned as the same object. A listed id that is not registered is skipped (a
+ * domain may be absent in a narrower composition, e.g. a test building one domain).
+ *
+ * @param required.registrations - The assembled registration list.
+ * @param optional.tools - Explicit host-owned batchable tool list.
+ * @returns A new list in the same order.
+ * @complexity O(r + b) for r registrations and b batchable tools.
+ */
+export function applyBatchInputs({ registrations }, { tools = [] } = {}) {
+    const byId = new Map(tools.map((tool) => [tool.toolId, tool]));
+    return registrations.map((registration) => {
+        const tool = byId.get(registration.descriptor.id);
+        return tool ? withBatchInput({ registration, tool }) : registration;
+    });
+}
+/**
+ * The default-on batch rule: every read-by-id and mutating tool takes `items` unless its host
+ * opts it out. Structural exclusions need no host entry: a tool with no object schema cannot take
+ * `items`, one that already has an `items` field would be shadowed by it, and a read-only tool with
+ * no required input (a list or search) has no per-item target to batch.
+ *
+ * @param required.registration - The registration to classify.
+ * @param optional.optOut - Host-owned tool ids kept single-call.
+ * @returns The first matching reason, or `batchable`.
+ * @complexity O(1) plus the schema's top-level `required` list; no effects.
+ */
+export function batchEligibilityFor({ registration }, { optOut = new Set() } = {}) {
+    const schema = registration.descriptor.inputSchema;
+    if (optOut.has(registration.descriptor.id))
+        return 'opted-out';
+    if (!isPlainObject(schema) || !isPlainObject(schema.properties))
+        return 'no-object-schema';
+    if (Object.hasOwn(schema.properties, 'items'))
+        return 'takes-items';
+    const hasRequired = Array.isArray(schema.required) && schema.required.length > 0;
+    return hasRequired || !isReadOnlyTool({ descriptor: registration.descriptor }) ? 'batchable' : 'list-read';
+}
+/**
+ * Every registration {@link batchEligibilityFor} classifies as batchable, as {@link BatchableTool}
+ * entries. A host's per-tool `settings` (a raised `maxItems`, item defaults, item validation) are
+ * merged over the default entry; a settings entry never makes an ineligible tool batchable.
+ *
+ * @param required.registrations - The assembled registration list.
+ * @param optional.optOut - Host-owned tools kept single-call, each with its reason.
+ * @param optional.settings - Host-owned per-tool batch settings.
+ * @returns The batchable tools, in registration order.
+ * @complexity O(r + o + s) for r registrations, o opt-outs and s settings entries.
+ */
+export function defaultBatchableTools({ registrations }, { optOut = [], settings = [] } = {}) {
+    const optedOut = new Set(optOut.map((entry) => entry.toolId));
+    const settingsById = new Map(settings.map((tool) => [tool.toolId, tool]));
+    return registrations
+        .filter((registration) => batchEligibilityFor({ registration }, { optOut: optedOut }) === 'batchable')
+        .map((registration) => settingsById.get(registration.descriptor.id) ?? { toolId: registration.descriptor.id });
+}
+//# sourceMappingURL=batch-tool-inputs.js.map

package/dist/feature-flags.d.ts

@@ -0,0 +1,21 @@
+/** A boolean rollout decision with its winning layer; feature flags never grant permissions. */
+export interface FeatureFlagDecision {
+    enabled: boolean;
+    source: 'environment' | 'runtime' | 'workspace' | 'default';
+}
+/** Evaluate one flag. Environment is the deployment override; runtime precedes persisted workspace.
+ * An explicitly malformed layer disables the feature instead of falling through to an enabling layer.
+ * @param requiredArgs - Flag key for a stable caller contract (the host owns lookup).
+ * @param optionalArgs - Layer values, with absent layers represented by undefined. Defaults off.
+ * @returns The winning decision and source, with no I/O or mutation.
+ * @complexity O(1) time and space.
+ */
+export declare function evaluateFeatureFlag(_requiredArgs: {
+    key: string;
+}, { environment, runtime, workspace, defaultEnabled }?: {
+    environment?: unknown;
+    runtime?: unknown;
+    workspace?: unknown;
+    defaultEnabled?: boolean;
+}): FeatureFlagDecision;
+//# sourceMappingURL=feature-flags.d.ts.map

package/dist/feature-flags.js

@@ -0,0 +1,17 @@
+/** Evaluate one flag. Environment is the deployment override; runtime precedes persisted workspace.
+ * An explicitly malformed layer disables the feature instead of falling through to an enabling layer.
+ * @param requiredArgs - Flag key for a stable caller contract (the host owns lookup).
+ * @param optionalArgs - Layer values, with absent layers represented by undefined. Defaults off.
+ * @returns The winning decision and source, with no I/O or mutation.
+ * @complexity O(1) time and space.
+ */
+export function evaluateFeatureFlag(_requiredArgs, { environment, runtime, workspace, defaultEnabled = false } = {}) {
+    if (environment !== undefined)
+        return { enabled: environment === 'true' || environment === '1', source: 'environment' };
+    if (runtime !== undefined)
+        return { enabled: runtime === true, source: 'runtime' };
+    if (workspace !== undefined)
+        return { enabled: workspace === true, source: 'workspace' };
+    return { enabled: defaultEnabled === true, source: 'default' };
+}
+//# sourceMappingURL=feature-flags.js.map

package/dist/fetch/index.d.ts

@@ -1,5 +1,6 @@
 /** Framework-neutral query contracts and cache; hosts supply transport callbacks and environment ports. */
 export { DEFAULT_STALE_TIME, IDLE_RETENTION, FetchQueryCache, toQueryError } from './cache.js';
 export type { QueryCacheSchedulerPort, FetchQueryEnvironmentPort, FetchQueryCacheOptions, QueryState, QueryObserver, CacheEntry } from './cache.js';
-export type { QueryKey, QueryStatus, QueryResult, FetchQueryOptions, MutationStatus, MutationResult, FetchMutationOptions, CachedLoaderOptions, CachedLoader, FetchQueryAdapter } from './types.js';
+export type { QueryKey, QueryStatus, QueryResult, FetchQueryOptions, MutationStatus, MutationResult, FetchMutationOptions, CachedLoaderOptions, CachedLoaderDefaults, CachedLoader, FetchQueryAdapter } from './types.js';
+export { missingCachedLoaderFetchError, withCachedLoaderFetch } from './loader-read.js';
 //# sourceMappingURL=index.d.ts.map