nexus-ai-pro 2.2.0 → 2.3.0

package/dist/agent/index.d.ts

@@ -1,5 +1,6 @@
 export { AgentLoop, type AgentModelClient as AgentLoopModelClient } from './loop.js';
 export { isToolOutput, tool, ToolExecutor, toolMessageContent, toolOutput } from './tool.js';
-export { limitToolCalls, redactMessages, type RedactOptions, summarizeHistory, type SummarizeOptions, } from './middleware.js';
-export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, createAgent, type CreateAgentOptions, } from './create-agent.js';
+export { limitToolCalls, redactMessages, type RedactOptions, summarizeHistory, type SummarizeOptions, } from './middleware/basic.js';
+export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentMiddlewareContext, type AgentModelCallContext, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, createAgent, type CreateAgentOptions, } from './create-agent.js';
 export type { AgentConfig, AgentResult, AgentStep, ToolExecutionResult } from '../types/agent.js';
+export type { ToolContext } from '../types/messages.js';

package/dist/agent/index.js

@@ -1,4 +1,4 @@
 export { AgentLoop } from './loop.js';
 export { isToolOutput, tool, ToolExecutor, toolMessageContent, toolOutput } from './tool.js';
-export { limitToolCalls, redactMessages, summarizeHistory, } from './middleware.js';
+export { limitToolCalls, redactMessages, summarizeHistory, } from './middleware/basic.js';
 export { agentAsTool, agentInput, createAgent, } from './create-agent.js';

package/dist/agent/middleware/approval.d.ts

@@ -0,0 +1,26 @@
+import type { AgentApproval, AgentMiddleware, AgentMiddlewareContext, AgentToolCall } from '../create-agent.js';
+/** Options for `humanApproval()`. */
+export interface HumanApprovalOptions {
+    /**
+     * Which calls need a person's approval. Defaults to every call whose tool declares nothing, or
+     * declares a capability that does anything but read.
+     */
+    when?: (call: AgentToolCall, context: AgentMiddlewareContext) => boolean;
+    /** The question a person sees. Defaults to naming the tool and its arguments. */
+    reason?: (call: AgentToolCall) => string;
+    /**
+     * Asks out of band instead of suspending the run: posts to a chat and waits for the answer, or
+     * applies a rule of your own. Without it, the run suspends through `interrupt()` until `resume()`
+     * answers, as `interruptOn` does.
+     */
+    approve?: (call: AgentToolCall, context: AgentMiddlewareContext) => AgentApproval | Promise<AgentApproval>;
+}
+/**
+ * Asks a person before a tool call runs, decided per call rather than per tool name.
+ *
+ * `interruptOn` approves every call to a named tool; this approves the calls a rule picks: a refund
+ * over a limit, a write outside a draft folder, anything a tool does that is not a read. An
+ * approver may refuse, or correct the arguments, which the permission policy then decides again.
+ * Put it before `toolRetry()`, so a retried call is not asked about twice.
+ */
+export declare function humanApproval(options?: HumanApprovalOptions): AgentMiddleware;

package/dist/agent/middleware/approval.js

@@ -0,0 +1,23 @@
+import { isSensitiveCapability } from '../capabilities.js';
+export function humanApproval(options = {}) {
+    const when = options.when ??
+        ((call) => call.capabilities === undefined || call.capabilities.some(isSensitiveCapability));
+    const reason = options.reason ?? ((call) => `Run tool "${call.name}" with ${JSON.stringify(call.args)}?`);
+    return {
+        name: 'human-approval',
+        async wrapToolCall(call, next, context) {
+            if (!when(call, context))
+                return next();
+            const answer = options.approve
+                ? await options.approve(call, context)
+                : context.interrupt({ reason: reason(call), payload: call });
+            if (answer === false || (typeof answer === 'object' && !answer.approved)) {
+                const why = typeof answer === 'object' && !answer.approved ? answer.reason : undefined;
+                return { ok: false, error: why ?? 'A person refused this tool call' };
+            }
+            return typeof answer === 'object' && answer.approved && answer.args
+                ? next({ ...call, args: answer.args })
+                : next();
+        },
+    };
+}

package/dist/agent/{middleware.d.ts → middleware/basic.d.ts}

@@ -1,5 +1,5 @@
-import type { Message } from '../types/messages.js';
-import type { AgentMiddleware } from './create-agent.js';
+import type { Message } from '../../types/messages.js';
+import type { AgentMiddleware } from '../create-agent.js';
 /**
  * Middleware that ships with the agent.
  *
@@ -40,9 +40,10 @@ export interface RedactOptions {
  */
 export declare function redactMessages(options: RedactOptions): AgentMiddleware;
 /**
- * Caps how often a tool may be called in one run.
+ * Caps how often a tool may be called in one run: one turn, from a user message to the answer.
  *
  * A model that loops on the same call otherwise burns the iteration budget, and with an expensive
- * tool it burns money too.
+ * tool it burns money too. Calls are counted from the transcript, so the count survives a restart
+ * and a resumed approval, and two threads never share one.
  */
 export declare function limitToolCalls(limits: Record<string, number>): AgentMiddleware;

package/dist/agent/{middleware.js → middleware/basic.js}

@@ -1,3 +1,4 @@
+import { callPosition } from './shared.js';
 export function summarizeHistory(options) {
     const keepLast = options.keepLast ?? 6;
     const triggerAfter = options.triggerAfter ?? 20;
@@ -40,18 +41,15 @@ export function redactMessages(options) {
     };
 }
 export function limitToolCalls(limits) {
-    const counts = new Map();
     return {
         name: 'limit-tool-calls',
-        async wrapToolCall(call, next) {
+        async wrapToolCall(call, next, context) {
             const limit = limits[call.name];
             if (limit === undefined)
                 return next();
-            const used = counts.get(call.name) ?? 0;
-            if (used >= limit) {
+            if (callPosition(context.state.messages, call) > limit) {
                 return { ok: false, error: `Tool "${call.name}" has already run ${limit} times in this run` };
             }
-            counts.set(call.name, used + 1);
             return next();
         },
     };

package/dist/agent/middleware/context-editor.d.ts

@@ -0,0 +1,52 @@
+import type { CompletionRequest } from '../../types/messages.js';
+import type { AgentMiddleware } from '../create-agent.js';
+/** One cleared result, for a custom placeholder. */
+export interface ClearedToolResult {
+    /** The tool whose result was cleared. */
+    tool: string;
+    /** How long the result was, in characters. */
+    length: number;
+}
+/** What one edit did, for logs and for measuring what it saves. */
+export interface ContextEdit {
+    /** Tool results cleared. */
+    cleared: number;
+    /** The request's estimated tokens before. */
+    tokensBefore: number;
+    /** And after. */
+    tokensAfter: number;
+}
+/** Options for `contextEditor()`. */
+export interface ContextEditorOptions {
+    /** Editing starts once the request's estimated tokens pass this. Defaults to 30,000. */
+    triggerTokens?: number;
+    /** The most recent tool results, kept whole. Defaults to 3. */
+    keepToolResults?: number;
+    /**
+     * Results are cleared this many at a time, so the edited prefix stays the same for several calls
+     * and a provider's prompt cache keeps working between edits. Defaults to 5.
+     */
+    batch?: number;
+    /** Tools whose results are never cleared. */
+    exclude?: readonly string[];
+    /** Also empties the arguments of each call whose result is cleared, for tools that take large inputs. */
+    clearArguments?: boolean;
+    /** What a cleared result says instead. Defaults to a line naming the tool and how to get it back. */
+    placeholder?: string | ((cleared: ClearedToolResult) => string);
+    /** Estimates a request's tokens. Defaults to about four characters a token. */
+    estimateTokens?: (request: CompletionRequest) => number;
+    /** Called after each edit. */
+    onEdit?: (edit: ContextEdit) => void;
+}
+/**
+ * Clears old tool results from what the model is sent, once the request grows past a threshold.
+ *
+ * Tool output is most of a long agent's context, and the model rarely needs a result from twenty
+ * steps ago verbatim. Every result but the most recent few is replaced by a short placeholder, in
+ * batches, so the edited prefix stays the same between edits and a provider's prompt cache keeps
+ * working. Only the request changes: the transcript in state keeps every result, and checkpoints,
+ * events, and a later summary still see them.
+ */
+export declare function contextEditor(options?: ContextEditorOptions): AgentMiddleware;
+/** About four characters a token, over the messages, the tool calls, and the tool schemas. */
+export declare function estimateRequestTokens(request: CompletionRequest): number;

package/dist/agent/middleware/context-editor.js

@@ -0,0 +1,66 @@
+import { textOf } from './shared.js';
+export function contextEditor(options = {}) {
+    const triggerTokens = options.triggerTokens ?? 30_000;
+    const keep = Math.max(0, options.keepToolResults ?? 3);
+    const batch = Math.max(1, options.batch ?? 5);
+    const exclude = new Set(options.exclude ?? []);
+    const estimate = options.estimateTokens ?? estimateRequestTokens;
+    const placeholder = (cleared) => typeof options.placeholder === 'function'
+        ? options.placeholder(cleared)
+        : (options.placeholder ??
+            `[Cleared to save context: the result of ${cleared.tool}, ${cleared.length} characters. Call the tool again if you need it.]`);
+    return {
+        name: 'context-editor',
+        beforeModel({ request }) {
+            const tokensBefore = estimate(request);
+            if (tokensBefore <= triggerTokens)
+                return;
+            const names = new Map();
+            for (const message of request.messages) {
+                for (const call of message.toolCalls ?? [])
+                    names.set(call.id, call.function.name);
+            }
+            const results = request.messages.flatMap((message, index) => (message.role === 'tool' ? [index] : []));
+            const eligible = Math.max(0, results.length - keep);
+            const count = eligible < batch ? eligible : eligible - (eligible % batch);
+            const clearable = new Set(results.slice(0, count).filter((index) => {
+                const id = request.messages[index]?.toolCallId;
+                return !exclude.has(names.get(id ?? '') ?? '');
+            }));
+            if (clearable.size === 0)
+                return;
+            const clearedIds = new Set();
+            const messages = request.messages.map((message, index) => {
+                if (!clearable.has(index))
+                    return message;
+                const text = textOf(message.content);
+                const tool = names.get(message.toolCallId ?? '') ?? 'a tool';
+                clearedIds.add(message.toolCallId ?? '');
+                return { ...message, content: placeholder({ tool, length: text.length }) };
+            });
+            const edited = options.clearArguments
+                ? messages.map((message) => message.toolCalls?.some((call) => clearedIds.has(call.id))
+                    ? {
+                        ...message,
+                        toolCalls: message.toolCalls.map((call) => clearedIds.has(call.id) ? { ...call, function: { ...call.function, arguments: '{}' } } : call),
+                    }
+                    : message)
+                : messages;
+            const next = { ...request, messages: edited };
+            options.onEdit?.({ cleared: clearable.size, tokensBefore, tokensAfter: estimate(next) });
+            return next;
+        },
+    };
+}
+export function estimateRequestTokens(request) {
+    let characters = 0;
+    for (const message of request.messages) {
+        characters += textOf(message.content).length + 4;
+        for (const call of message.toolCalls ?? [])
+            characters += call.function.name.length + call.function.arguments.length;
+    }
+    for (const tool of request.tools ?? []) {
+        characters += tool.name.length + tool.description.length + JSON.stringify(tool.parameters ?? {}).length;
+    }
+    return Math.ceil(characters / 4);
+}

package/dist/agent/middleware/filesystem.d.ts

@@ -0,0 +1,44 @@
+import type { AgentMiddleware } from '../create-agent.js';
+import type { Sandbox } from '../sandbox.js';
+/** Where `filesystemContext()` reads and writes: a `Sandbox`, or anything with the same file methods. */
+export type FilesystemContextSource = Pick<Sandbox, 'readFile'> & Partial<Pick<Sandbox, 'writeFile' | 'listFiles'>>;
+/** Where large tool results go instead of the transcript. */
+export interface ContextOffloadOptions {
+    /** Results longer than this, in characters, are offloaded. Defaults to 20,000. */
+    overChars?: number;
+    /** The directory they are written to, inside the source. Defaults to `.context`. */
+    directory?: string;
+    /** How much of a result stays in the transcript as a preview, in characters. Defaults to 1,000. */
+    previewChars?: number;
+    /** Tools whose results are never offloaded. Defaults to `read_file`, so reading one back cannot loop. */
+    exclude?: readonly string[];
+}
+/** Options for `filesystemContext()`. */
+export interface FilesystemContextOptions {
+    /** Where files are read from and offloaded to. */
+    source: FilesystemContextSource;
+    /**
+     * Files whose contents the model sees on every call, after the system prompt: project
+     * instructions such as `AGENTS.md`, conventions, a glossary. A missing file is skipped.
+     */
+    include?: readonly string[];
+    /** Lists a directory after the files, so the model knows what exists without a tool call. Needs `listFiles`. */
+    listing?: {
+        directory?: string;
+        maxEntries?: number;
+    };
+    /** The most characters of included files, together. Defaults to 32,000; the rest is cut. */
+    maxChars?: number;
+    /** Writes large tool results to a file and leaves a preview and the path. Needs `writeFile`. */
+    offload?: ContextOffloadOptions | boolean;
+}
+/**
+ * The filesystem as the agent's context: files in, large results out.
+ *
+ * Instruction files reach the model on every call without a tool call, read once per run and placed
+ * right after the system prompt, so the prefix a provider caches stays the same. A tool result too
+ * large for the context is written to a file instead, and the model reads a preview and a path it can
+ * open with `read_file` when it needs the rest: the transcript stays small however much a tool
+ * returns, and nothing is lost.
+ */
+export declare function filesystemContext(options: FilesystemContextOptions): AgentMiddleware;

package/dist/agent/middleware/filesystem.js

@@ -0,0 +1,83 @@
+export function filesystemContext(options) {
+    const maxChars = options.maxChars ?? 32_000;
+    const offload = options.offload === true
+        ? {}
+        : options.offload === false || options.offload === undefined
+            ? undefined
+            : options.offload;
+    if (offload && !options.source.writeFile) {
+        throw new TypeError('filesystemContext() offloading needs a source with writeFile()');
+    }
+    const loaded = new Map();
+    const load = async () => {
+        const sections = [];
+        let budget = maxChars;
+        for (const file of options.include ?? []) {
+            if (budget <= 0)
+                break;
+            let text;
+            try {
+                text = await options.source.readFile(file);
+            }
+            catch {
+                continue;
+            }
+            const cut = text.length > budget ? `${text.slice(0, budget)}\n[cut: ${text.length - budget} more characters]` : text;
+            budget -= text.length;
+            sections.push(`<file path="${file}">\n${cut}\n</file>`);
+        }
+        if (options.listing && options.source.listFiles) {
+            try {
+                const entries = await options.source.listFiles(options.listing.directory ?? '.');
+                const max = options.listing.maxEntries ?? 200;
+                const shown = entries.slice(0, max).join('\n');
+                sections.push(`<listing directory="${options.listing.directory ?? '.'}">\n${shown}${entries.length > max ? `\n[${entries.length - max} more]` : ''}\n</listing>`);
+            }
+            catch {
+            }
+        }
+        return sections.length ? `Files from the workspace:\n\n${sections.join('\n\n')}` : undefined;
+    };
+    return {
+        name: 'filesystem-context',
+        async beforeModel({ request, state, threadId }) {
+            if (!options.include?.length && !options.listing)
+                return;
+            const turn = state.messages.filter((message) => message.role === 'user').length;
+            const key = `${threadId}:${turn}`;
+            let pending = loaded.get(key);
+            if (!pending) {
+                pending = load();
+                loaded.set(key, pending);
+                if (loaded.size > 256)
+                    loaded.delete(loaded.keys().next().value);
+            }
+            const text = await pending;
+            if (!text)
+                return;
+            const systemCount = request.messages.findIndex((message) => message.role !== 'system');
+            const at = systemCount === -1 ? request.messages.length : systemCount;
+            const context = { role: 'system', content: text };
+            return { ...request, messages: [...request.messages.slice(0, at), context, ...request.messages.slice(at)] };
+        },
+        async wrapToolCall(call, next) {
+            const result = await next();
+            if (!offload || !result.ok || (offload.exclude ?? ['read_file']).includes(call.name))
+                return result;
+            const value = result.result;
+            if (value?.type === 'tool_output')
+                return result;
+            const text = typeof value === 'string' ? value : JSON.stringify(value);
+            if (text === undefined || text.length <= (offload.overChars ?? 20_000))
+                return result;
+            const directory = (offload.directory ?? '.context').replace(/\/+$/, '');
+            const file = `${directory}/${`${call.name}-${call.id}`.replace(/[^A-Za-z0-9._-]/g, '_')}.txt`;
+            await options.source.writeFile?.(file, text);
+            const preview = text.slice(0, offload.previewChars ?? 1_000);
+            return {
+                ok: true,
+                result: `${preview}\n\n[This result is ${text.length} characters; the first ${preview.length} are above. The whole result is in ${file}: read it with read_file when you need the rest.]`,
+            };
+        },
+    };
+}

package/dist/agent/middleware/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Middleware for `createAgent()`, each its own import: retries, fallbacks, model choice, tool
+ * selection, context editing, personal data, approvals, limits, and the filesystem as context.
+ *
+ * Each is ordinary `AgentMiddleware` built on the same hooks an application's own middleware uses,
+ * so any of them can be read, copied, and changed. None adds a dependency, and a bundler keeps only
+ * the ones imported.
+ */
+export { limitToolCalls, redactMessages, type RedactOptions, summarizeHistory, type SummarizeOptions, } from './basic.js';
+export { type ClearedToolResult, type ContextEdit, contextEditor, type ContextEditorOptions, estimateRequestTokens, } from './context-editor.js';
+export { type ContextOffloadOptions, filesystemContext, type FilesystemContextOptions, type FilesystemContextSource, } from './filesystem.js';
+export { humanApproval, type HumanApprovalOptions } from './approval.js';
+export { modelCallLimit, ModelCallLimitError, type ModelCallLimitOptions } from './limits.js';
+export { type DynamicModelContext, dynamicModel, modelFallback, type ModelFallbackEvent, type ModelFallbackOptions, type ModelFallbackTarget, } from './models.js';
+export { PiiBlockedError, type PiiFinding, type PiiKind, piiMiddleware, type PiiMiddlewareOptions, type PiiStrategy, type PiiWhere, } from './pii.js';
+export { modelRetry, type ModelRetryOptions, type RetryEvent, toolRetry, type ToolRetryOptions } from './retry.js';
+export type { RetryBackoff } from './shared.js';
+export { type ToolSelection, type ToolSelectionContext, toolSelector, type ToolSelectorOptions, } from './tool-selector.js';
+export type { AgentMiddleware, AgentMiddlewareContext, AgentModelCallContext, AgentToolCall, AgentToolResult, } from '../create-agent.js';

package/dist/agent/middleware/index.js

@@ -0,0 +1,9 @@
+export { limitToolCalls, redactMessages, summarizeHistory, } from './basic.js';
+export { contextEditor, estimateRequestTokens, } from './context-editor.js';
+export { filesystemContext, } from './filesystem.js';
+export { humanApproval } from './approval.js';
+export { modelCallLimit, ModelCallLimitError } from './limits.js';
+export { dynamicModel, modelFallback, } from './models.js';
+export { PiiBlockedError, piiMiddleware, } from './pii.js';
+export { modelRetry, toolRetry } from './retry.js';
+export { toolSelector, } from './tool-selector.js';

package/dist/agent/middleware/limits.d.ts

@@ -0,0 +1,42 @@
+import type { AgentMiddleware } from '../create-agent.js';
+/** Options for `modelCallLimit()`. Set `run`, `thread`, or both. */
+export interface ModelCallLimitOptions {
+    /** Model calls in one run: from a user message to the answer, a resumed approval included. */
+    run?: number;
+    /**
+     * Model calls over a thread's whole life, every run on it included. Counted in the agent's store
+     * when it has one, so every process shares the count and it survives a restart; otherwise in this
+     * process. A budget, not a lock: two runs on one thread at the same moment may each pass it once.
+     */
+    thread?: number;
+    /**
+     * What happens at a limit: `end` answers with `message` and stops with `stopReason: 'stopped'`,
+     * without calling the model; `error` fails the run with a `ModelCallLimitError`. Defaults to `end`.
+     */
+    onLimit?: 'end' | 'error';
+    /** The answer a run ends with under `end`. Defaults to a sentence naming the limit. */
+    message?: string;
+}
+/** Thrown by `modelCallLimit()` under `onLimit: 'error'`. */
+export declare class ModelCallLimitError extends Error {
+    /** Which limit was reached. */
+    readonly scope: 'run' | 'thread';
+    /** The limit. */
+    readonly limit: number;
+    /** Always `MODEL_CALL_LIMIT`. */
+    readonly code = "MODEL_CALL_LIMIT";
+    constructor(
+    /** Which limit was reached. */
+    scope: 'run' | 'thread', 
+    /** The limit. */
+    limit: number);
+}
+/**
+ * Caps the model calls of a run, of a thread, or both.
+ *
+ * `maxIterations` stops one run that keeps calling tools; this is a budget an application sets per
+ * run and per conversation, so a thread a user keeps coming back to cannot spend without bound. The
+ * run count is read from the transcript, so it survives a restart. A run that reaches a limit ends
+ * with an answer rather than an error, unless you ask for one.
+ */
+export declare function modelCallLimit(options: ModelCallLimitOptions): AgentMiddleware;

package/dist/agent/middleware/limits.js

@@ -0,0 +1,52 @@
+import { modelCallsInTurn } from './shared.js';
+export class ModelCallLimitError extends Error {
+    scope;
+    limit;
+    code = 'MODEL_CALL_LIMIT';
+    constructor(scope, limit) {
+        super(`The agent reached its limit of ${limit} model calls per ${scope}`);
+        this.scope = scope;
+        this.limit = limit;
+        this.name = 'ModelCallLimitError';
+    }
+}
+const NAMESPACE = ['nexus', 'agent', 'model-calls'];
+export function modelCallLimit(options) {
+    if (options.run === undefined && options.thread === undefined) {
+        throw new RangeError('modelCallLimit() needs a run limit, a thread limit, or both');
+    }
+    const local = new Map();
+    return {
+        name: 'model-call-limit',
+        async wrapModelCall(request, next, context) {
+            let reached;
+            if (options.run !== undefined && modelCallsInTurn(context.state.messages) >= options.run) {
+                reached = ['run', options.run];
+            }
+            let used = 0;
+            if (!reached && options.thread !== undefined) {
+                used = context.store
+                    ? ((await context.store.get(NAMESPACE, context.threadId))?.value ?? 0)
+                    : (local.get(context.threadId) ?? 0);
+                if (used >= options.thread)
+                    reached = ['thread', options.thread];
+            }
+            if (reached) {
+                const [scope, limit] = reached;
+                if (options.onLimit === 'error')
+                    throw new ModelCallLimitError(scope, limit);
+                return context.stop(options.message ?? `I stopped here: this ${scope} reached its limit of ${limit} model calls.`);
+            }
+            if (options.thread !== undefined) {
+                if (context.store)
+                    await context.store.put(NAMESPACE, context.threadId, used + 1);
+                else {
+                    local.set(context.threadId, used + 1);
+                    if (local.size > 10_000)
+                        local.delete(local.keys().next().value);
+                }
+            }
+            return next(request);
+        },
+    };
+}

package/dist/agent/middleware/models.d.ts

@@ -0,0 +1,48 @@
+import type { CompletionRequest } from '../../types/messages.js';
+import type { AgentMiddleware, AgentMiddlewareContext, AgentModelClient } from '../create-agent.js';
+/** A model to fall back to: a model name for the agent's own client, or another client. */
+export type ModelFallbackTarget = string | {
+    client: AgentModelClient;
+    model?: string;
+};
+/** One fallback about to happen. */
+export interface ModelFallbackEvent {
+    /** The model that failed. */
+    from: string;
+    /** The model tried next. */
+    to: string;
+    /** What the failed call threw. */
+    error: unknown;
+}
+/** Options for `modelFallback()`. */
+export interface ModelFallbackOptions {
+    /** Whether an error moves on to the next model. Defaults to every error but a cancellation. */
+    fallbackOn?: (error: unknown, model: string) => boolean;
+    /** Called before each fallback, for logs and metrics. */
+    onFallback?: (event: ModelFallbackEvent) => void;
+}
+/**
+ * Tries other models, in order, when the model call fails.
+ *
+ * The client's router already falls back between providers for one request; this is the fallback
+ * it cannot make: to a client of a different kind, or once the client's own routes are exhausted. A
+ * target with its own client is called through `complete()`, never streamed, and middleware after
+ * this one does not wrap it.
+ */
+export declare function modelFallback(models: readonly ModelFallbackTarget[], options?: ModelFallbackOptions): AgentMiddleware;
+/** What `dynamicModel()` decides from: the step's context and the request about to be sent. */
+export type DynamicModelContext = AgentMiddlewareContext & {
+    request: CompletionRequest;
+};
+/**
+ * Chooses the model for each call from the run so far.
+ *
+ * A cheap model for the first steps and a stronger one once the task proves hard, a model with a
+ * longer context once the transcript grows, or a tenant's own model. Returning nothing keeps the
+ * model the request already names.
+ *
+ * ```ts
+ * dynamicModel(({ state }) => (state.iterations >= 4 ? 'gpt-5' : 'gpt-5-mini'))
+ * ```
+ */
+export declare function dynamicModel(select: (context: DynamicModelContext) => string | undefined | Promise<string | undefined>): AgentMiddleware;

package/dist/agent/middleware/models.js

@@ -0,0 +1,44 @@
+import { isCancellation } from './shared.js';
+export function modelFallback(models, options = {}) {
+    if (models.length === 0)
+        throw new RangeError('modelFallback() needs at least one model to fall back to');
+    return {
+        name: 'model-fallback',
+        async wrapModelCall(request, next, context) {
+            try {
+                return await next(request);
+            }
+            catch (first) {
+                let error = first;
+                let from = request.model;
+                for (const target of models) {
+                    if (isCancellation(error, context.signal) || !(options.fallbackOn?.(error, from) ?? true))
+                        throw error;
+                    const model = typeof target === 'string' ? target : (target.model ?? request.model);
+                    options.onFallback?.({ from, to: model, error });
+                    try {
+                        return typeof target === 'string'
+                            ? await next({ ...request, model })
+                            : await target.client.complete({ ...request, model });
+                    }
+                    catch (failure) {
+                        error = failure;
+                        from = model;
+                    }
+                }
+                throw error;
+            }
+        },
+    };
+}
+export function dynamicModel(select) {
+    return {
+        name: 'dynamic-model',
+        async beforeModel(context) {
+            const model = await select(context);
+            if (!model || model === context.request.model)
+                return;
+            return { ...context.request, model };
+        },
+    };
+}

package/dist/agent/middleware/pii.d.ts

@@ -0,0 +1,67 @@
+import type { AgentMiddleware } from '../create-agent.js';
+/** The personal data and secrets `piiMiddleware()` finds on its own. */
+export type PiiKind = 'email' | 'credit-card' | 'ssn' | 'phone' | 'iban' | 'ip-address' | 'secret';
+/**
+ * What happens to a match: `redact` replaces it with its kind, `mask` keeps its last four
+ * characters, `hash` replaces it with a stable token so two values stay distinguishable, and `block`
+ * refuses the whole message.
+ */
+export type PiiStrategy = 'redact' | 'mask' | 'hash' | 'block';
+/** Where a match was found. */
+export type PiiWhere = 'input' | 'output' | 'tool';
+/** One match, as `onDetect` sees it: never the value itself. */
+export interface PiiFinding {
+    /** Its kind: a built-in kind or a name from `patterns`. */
+    kind: string;
+    /** Where it was found. */
+    where: PiiWhere;
+    /** What was done with it. */
+    strategy: PiiStrategy;
+}
+/** Options for `piiMiddleware()`. */
+export interface PiiMiddlewareOptions {
+    /** The built-in kinds to find. Defaults to all of them. */
+    kinds?: readonly PiiKind[];
+    /** Kinds of your own, by name: `{ 'employee-id': /\bEMP-\d{6}\b/ }`. */
+    patterns?: Readonly<Record<string, RegExp>>;
+    /**
+     * What happens to a match, for every kind or per kind: `'mask'`, or
+     * `{ email: 'hash', 'credit-card': 'block' }`. Kinds not named are redacted.
+     */
+    strategy?: PiiStrategy | Readonly<Record<string, PiiStrategy>>;
+    /**
+     * Where to look. `input` is every message sent to the model but the system prompt; `output` is
+     * the model's answer; `toolResults` cleans a result before it enters the transcript, so it is never
+     * checkpointed either. Defaults to input and tool results.
+     */
+    apply?: {
+        input?: boolean;
+        output?: boolean;
+        toolResults?: boolean;
+    };
+    /** Called for each match, for an audit trail. */
+    onDetect?: (finding: PiiFinding) => void;
+}
+/** Thrown when a match under the `block` strategy is found in the model's input or output. */
+export declare class PiiBlockedError extends Error {
+    /** The kind that was found. */
+    readonly kind: string;
+    /** Where it was found. */
+    readonly where: PiiWhere;
+    /** Always `PII_BLOCKED`. */
+    readonly code = "PII_BLOCKED";
+    constructor(
+    /** The kind that was found. */
+    kind: string, 
+    /** Where it was found. */
+    where: PiiWhere);
+}
+/**
+ * Keeps personal data and secrets away from the model, the transcript, or both.
+ *
+ * Finds emails, card numbers (checked with Luhn), US social security numbers, phone numbers, IBANs
+ * (checked with their checksum), IP addresses, and common API keys and private keys, plus any kinds
+ * of your own; and redacts, masks, hashes, or blocks each. The validated kinds keep false positives
+ * low: an order number is not a card number unless its checksum says so.
+ */
+export declare function piiMiddleware(options?: PiiMiddlewareOptions): AgentMiddleware;