nexus-ai-pro 2.1.0 → 2.3.0

package/dist/agent/create-agent.d.ts

@@ -1,9 +1,11 @@
 import type { OperationLifecycleLike } from '../types/lifecycle.js';
 import { type CompiledGraph } from '../graph/graph.js';
-import type { GraphCheckpointer, NodeContext } from '../types/graph.js';
+import type { GraphCheckpointer, InterruptRequest, NodeContext } from '../types/graph.js';
 import type { CompletionRequest, Message, ToolDefinition } from '../types/messages.js';
 import type { NexusResponse, StreamChunk } from '../types/response.js';
+import type { Principal } from '../types/principal.js';
 import type { Store } from '../types/store.js';
+import type { PermissionPolicyLike } from './permissions.js';
 /**
  * An agent as a graph.
  *
@@ -28,6 +30,10 @@ export interface AgentToolCall {
     name: string;
     /** Arguments, parsed from the model's JSON. */
     args: Record<string, unknown>;
+    /** What the call declares it does, when the tool declares capabilities. */
+    capabilities?: readonly string[];
+    /** Why the permission policy asked for approval, when it did. */
+    permission?: string;
 }
 /** What an approver may answer: allow, refuse with a reason, or allow with corrected arguments. */
 export type AgentApproval = boolean | {
@@ -42,24 +48,58 @@ export interface AgentApprovalPolicy {
     /** The question an operator sees. Defaults to naming the tool and its arguments. */
     reason?: (call: AgentToolCall) => string;
 }
+/** What every middleware hook can read about the step it runs in. */
+export interface AgentMiddlewareContext {
+    /** The agent's state at this step: the whole transcript, tool calls and results included. */
+    state: AgentState;
+    /** Long-term memory, when the agent has a store. */
+    store?: Store;
+    /** The thread the run belongs to. */
+    threadId: string;
+    /** The tenant the run is for, when it has one. */
+    tenantId?: string;
+    /** Who the run is for, when it has a principal: the caller the server authenticated. */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled or the step times out. A hook that waits should stop with it. */
+    signal: AbortSignal;
+    /**
+     * Suspends the run until a person answers, as `interruptOn` does. When the run resumes, the step
+     * runs again and this returns the answer instead of suspending.
+     */
+    interrupt<T = unknown>(request: InterruptRequest): T;
+}
+/** What `wrapModelCall` can read, and how it ends the run without calling the model. */
+export interface AgentModelCallContext extends AgentMiddlewareContext {
+    /**
+     * Ends the run with this answer and `stopReason: 'stopped'`, without another model call. Return
+     * what it returns: `return context.stop('The model call limit was reached.')`.
+     */
+    stop(answer: string): NexusResponse;
+}
 /** Hooks around the agent's model calls and tool calls. Each hook is optional. */
 export interface AgentMiddleware {
     /** Names the middleware in traces and errors. */
     name?: string;
     /** Adjusts the request before it is sent: trim history, add context, swap the model. */
-    beforeModel?(context: {
+    beforeModel?(context: AgentMiddlewareContext & {
         request: CompletionRequest;
-        state: AgentState;
-        store?: Store;
     }): CompletionRequest | void | Promise<CompletionRequest | void>;
     /** Inspects or replaces the response: redact, validate, count. */
-    afterModel?(context: {
+    afterModel?(context: AgentMiddlewareContext & {
         response: NexusResponse;
-        state: AgentState;
-        store?: Store;
     }): NexusResponse | void | Promise<NexusResponse | void>;
-    /** Wraps a tool call, so a policy can log it, time it, or refuse it. */
-    wrapToolCall?(call: AgentToolCall, next: () => Promise<AgentToolResult>): Promise<AgentToolResult> | AgentToolResult;
+    /**
+     * Wraps the model call itself, after every `beforeModel` and before every `afterModel`. `next`
+     * sends a request and may be called again, with the same request or a changed one, to retry or to
+     * fall back to another model. The first middleware is the outermost.
+     */
+    wrapModelCall?(request: CompletionRequest, next: (request: CompletionRequest) => Promise<NexusResponse>, context: AgentModelCallContext): Promise<NexusResponse> | NexusResponse;
+    /**
+     * Wraps a tool call, so a policy can log it, time it, retry it, or refuse it. `next` runs the
+     * rest of the chain and may be called again; given a call, it runs that call's arguments instead,
+     * and the permission policy decides them again first. The first middleware is the outermost.
+     */
+    wrapToolCall?(call: AgentToolCall, next: (call?: AgentToolCall) => Promise<AgentToolResult>, context: AgentMiddlewareContext): Promise<AgentToolResult> | AgentToolResult;
 }
 /** What a tool call produced. */
 export interface AgentToolResult {
@@ -88,6 +128,13 @@ export interface CreateAgentOptions {
     interruptOn?: Record<string, AgentApprovalPolicy | true>;
     /** Hooks around model and tool calls, applied in order. */
     middleware?: AgentMiddleware[];
+    /**
+     * Decides every tool call from the capabilities it declares, before it runs: allow it, deny it,
+     * or interrupt for a person's approval, as `interruptOn` does. A denied call reaches the model as a
+     * failed tool result naming the reason, and never runs. See `permissionPolicy()` in
+     * `nexus-ai-pro/agent/permissions`.
+     */
+    permissions?: PermissionPolicyLike;
     /** Long-term memory, available to tools and middleware as `store`. */
     store?: Store;
     /**
@@ -136,8 +183,11 @@ export type AgentState = {
     /** Why the agent stopped. */
     stopReason?: AgentStopReason;
 };
-/** `completed` when the model answered, `max_iterations` when it ran out of model calls. */
-export type AgentStopReason = 'completed' | 'max_iterations';
+/**
+ * `completed` when the model answered, `max_iterations` when it ran out of model calls, `stopped`
+ * when a middleware ended the run through `context.stop()`.
+ */
+export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped';
 /** An agent: a compiled graph over the agent's channels. */
 export type AgentGraph = CompiledGraph<AgentChannels>;
 /** Wraps a question into the state an agent starts from. */

package/dist/agent/create-agent.js

@@ -1,6 +1,7 @@
 import { appendList, counter, lastValue } from '../graph/channels.js';
 import { createGraph } from '../graph/graph.js';
 import { Command, END, Send } from '../types/graph.js';
+import { capabilitiesOf } from './capabilities.js';
 import { ToolExecutor, toolMessageContent } from './tool.js';
 const agentChannels = () => ({
     messages: appendList(),
@@ -34,24 +35,47 @@ export function createAgent(options) {
             ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
             ...(options.metadata ? { metadata: options.metadata } : {}),
         };
+        const hooks = hookContext(context, state, options.store);
         for (const item of middleware) {
-            request = (await item.beforeModel?.({ request, state, store: options.store })) ?? request;
+            request = (await item.beforeModel?.({ ...hooks, request })) ?? request;
         }
-        let response = options.streamTokens && options.client.stream
-            ? await streamed(options.client.stream(request), (chunk) => context.message(chunk))
-            : await options.client.complete(request);
-        if (!(options.streamTokens && options.client.stream) && response.content) {
+        const streaming = Boolean(options.streamTokens && options.client.stream);
+        const send = (next) => streaming && options.client.stream
+            ? streamed(options.client.stream(next), (chunk) => context.message(chunk))
+            : options.client.complete(next);
+        const stops = new WeakSet();
+        const modelContext = {
+            ...hooks,
+            stop: (answer) => {
+                const stopped = stopResponse(answer, request.model);
+                stops.add(stopped);
+                return stopped;
+            },
+        };
+        const wrapped = middleware.reduceRight((next, item) => {
+            const wrap = item.wrapModelCall?.bind(item);
+            return wrap ? (current) => Promise.resolve(wrap(current, next, modelContext)) : next;
+        }, send);
+        let response = await wrapped(request);
+        const stopped = stops.has(response);
+        if ((!streaming || stopped) && response.content) {
             context.message({ content: response.content });
         }
         for (const item of middleware) {
-            response = (await item.afterModel?.({ response, state, store: options.store })) ?? response;
+            response = (await item.afterModel?.({ ...hooks, response })) ?? response;
         }
         const assistant = {
             role: 'assistant',
             content: response.content,
-            ...(response.toolCalls?.length ? { toolCalls: response.toolCalls } : {}),
+            ...(response.toolCalls?.length && !stopped ? { toolCalls: response.toolCalls } : {}),
         };
-        const calls = response.toolCalls ?? [];
+        const calls = stopped ? [] : (response.toolCalls ?? []);
+        if (stopped) {
+            return new Command({
+                update: { messages: [assistant], iterations: 1, answer: response.content, stopReason: 'stopped' },
+                goto: END,
+            });
+        }
         if (calls.length === 0) {
             return new Command({
                 update: { messages: [assistant], iterations: 1, answer: response.content, stopReason: 'completed' },
@@ -76,27 +100,82 @@ export function createAgent(options) {
             return { messages: [toolMessage(call, { ok: false, error: parsed.error })] };
         }
         let args = parsed.args;
-        const description = { id: call.id, name: call.function.name, args };
+        const definition = executor.get(call.function.name);
+        const capabilities = capabilitiesOf(definition, args);
+        const description = {
+            id: call.id,
+            name: call.function.name,
+            args,
+            ...(capabilities ? { capabilities } : {}),
+        };
+        const refuse = (error) => {
+            context.tool({ phase: 'error', id: call.id, name: description.name, error });
+            return { messages: [toolMessage(call, { ok: false, error })] };
+        };
+        let permission;
+        if (options.permissions) {
+            const verdict = await options.permissions.decide({
+                tool: description.name,
+                args,
+                capabilities,
+                ...(context.principal ? { principal: context.principal } : {}),
+            });
+            if (verdict.decision === 'deny')
+                return refuse(`Permission denied: ${verdict.reason}`);
+            if (verdict.decision === 'ask')
+                permission = verdict.reason;
+        }
         const policy = approvals[description.name];
-        if (policy) {
+        if (policy || permission) {
+            const asked = permission ? { ...description, permission } : description;
             const decision = context.interrupt({
-                reason: (policy === true ? undefined : policy.reason?.(description)) ?? defaultReason(description),
-                payload: description,
+                reason: (policy && policy !== true ? policy.reason?.(asked) : undefined) ??
+                    (permission ? `${defaultReason(asked)} (${permission})` : defaultReason(asked)),
+                payload: asked,
             });
             const verdict = normalizeApproval(decision);
-            if (!verdict.approved) {
-                return {
-                    messages: [toolMessage(call, { ok: false, error: verdict.reason ?? 'A human refused this tool call' })],
-                };
-            }
-            if (verdict.args)
+            if (!verdict.approved)
+                return refuse(verdict.reason ?? 'A human refused this tool call');
+            if (verdict.args) {
                 args = verdict.args;
+                if (options.permissions) {
+                    const recheck = await options.permissions.decide({
+                        tool: description.name,
+                        args,
+                        capabilities: capabilitiesOf(definition, args),
+                    });
+                    if (recheck.decision === 'deny')
+                        return refuse(`Permission denied: ${recheck.reason}`);
+                }
+            }
         }
-        const run = async () => executor.execute(description.name, args);
+        const run = async (current) => {
+            if (options.permissions && current.args !== args) {
+                const recheck = await options.permissions.decide({
+                    tool: description.name,
+                    args: current.args,
+                    capabilities: capabilitiesOf(definition, current.args),
+                });
+                if (recheck.decision === 'deny')
+                    return { ok: false, error: `Permission denied: ${recheck.reason}` };
+            }
+            return executor.execute(description.name, current.args, {
+                toolCallId: call.id,
+                threadId: context.threadId,
+                ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
+                ...(context.principal ? { principal: context.principal } : {}),
+                signal: context.signal,
+                ...(context.store ? { store: context.store } : {}),
+            });
+        };
         context.tool({ phase: 'start', id: call.id, name: description.name, args });
-        const result = await middleware.reduceRight((next, item) => item.wrapToolCall
-            ? () => Promise.resolve(item.wrapToolCall?.({ ...description, args }, next))
-            : next, run)();
+        const hooks = hookContext(context, context.state, options.store);
+        const result = await middleware.reduceRight((next, item) => {
+            const wrap = item.wrapToolCall?.bind(item);
+            return wrap
+                ? (current) => Promise.resolve(wrap(current, (changed) => next(changed ?? current), hooks))
+                : next;
+        }, run)({ ...description, args });
         context.tool(result.ok
             ? { phase: 'result', id: call.id, name: description.name, result: result.result }
             : { phase: 'error', id: call.id, name: description.name, error: result.error ?? 'The tool failed' });
@@ -111,6 +190,12 @@ export function createAgent(options) {
         ...(options.store ? { store: options.store } : {}),
         ...(options.name ? { name: options.name } : {}),
         ...(options.lifecycle ? { lifecycle: options.lifecycle, lifecycleFamily: 'agent' } : {}),
+        tools: executor.list().map((definition) => ({
+            name: definition.name,
+            ...(Array.isArray(definition.capabilities) ? { capabilities: [...definition.capabilities] } : {}),
+            ...(typeof definition.capabilities === 'function' ? { dynamic: true } : {}),
+            approval: approvals[definition.name] ? 'interrupt' : options.permissions ? 'policy' : 'none',
+        })),
     });
 }
 export function agentAsTool(options) {
@@ -165,6 +250,35 @@ function parseArguments(raw) {
         return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }
+function hookContext(context, state, store) {
+    return {
+        state,
+        ...((context.store ?? store) ? { store: context.store ?? store } : {}),
+        threadId: context.threadId,
+        ...(context.tenantId ? { tenantId: context.tenantId } : {}),
+        ...(context.principal ? { principal: context.principal } : {}),
+        signal: context.signal,
+        interrupt: (request) => context.interrupt(request),
+    };
+}
+function stopResponse(answer, model) {
+    return {
+        content: answer,
+        role: 'assistant',
+        finishReason: 'stop',
+        meta: {
+            requestId: '',
+            providerUsed: 'none',
+            modelUsed: model,
+            latencyMs: 0,
+            tokensInput: 0,
+            tokensOutput: 0,
+            tokensSaved: 0,
+            cacheHit: false,
+            guardrailsApplied: ['stopped-by-middleware'],
+        },
+    };
+}
 async function streamed(chunks, onChunk) {
     let content = '';
     const toolCalls = [];

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;