nexus-ai-pro 1.12.0 → 1.14.0

package/API_STABILITY.md

@@ -328,6 +328,33 @@ Also since 1.12.0, all additive:
 - A subgraph node's thread id is `<parent thread>:<task id>`, which equals the previous
   `<parent thread>:<node>` for any node not reached through `Send`.
 
+## Agent, store, MCP, and tracing stages (1.14.0)
+
+The `nexus-ai-pro/agent`, `nexus-ai-pro/store`, `nexus-ai-pro/store/redis`, and `nexus-ai-pro/mcp`
+subpaths are public and follow the 1.x rules. None is exported from the root import.
+
+- `createAgent()` returns a compiled graph, so the graph guarantees above apply to an agent: a
+  superstep is atomic with respect to checkpointing, a finished task is never re-run by a resume, and
+  an approval survives a restart. The agent's state channels (`messages`, `iterations`, `answer`,
+  `stopReason`) are a normalized shape; what a model decides to put in them is not.
+- `Store` is the contract; `MemoryStore` and `RedisStore` implement it. Ranking from a semantic search
+  depends on the embedding function a caller injects and is not a guarantee. `MemoryStore` is
+  process-local and bounded, and drops the least recently written item past `maxItems`.
+- The MCP subpath implements a subset of the Model Context Protocol: initialize, tools, resources, and
+  prompts, over stdio and HTTP. Protocol versions and server behaviour are upstream contracts outside
+  this policy. Server-initiated streaming, sampling, and roots are not implemented; new methods may be
+  added in a minor release.
+- `nexus-ai-pro/tracing` is public: `Tracer`, the `TraceStore` contract, `MemoryTraceStore`,
+  `JsonlTraceStore`, `traceGraph()`, `traceModelClient()`, `compareTraces()`, and `AlertEvaluator`.
+  The `Run`, `RunTree`, and `RunQuery` shapes are normalized; what a model puts in a run's inputs and
+  outputs is not. New `RunKind` values and query fields may be added in a minor release. Sampling is
+  probabilistic by definition, so which traces are kept is not a guarantee, but the tail rules are:
+  an error, a run past `keepSlowerThanMs`, or one past `keepCostlierThan` is always kept.
+- `agentAsTool()` and the bundled middleware (`summarizeHistory`, `redactMessages`, `limitToolCalls`)
+  are public and additive.
+- `AgentLoop`, `tool()`, and `ToolExecutor` keep their behaviour and are re-exported from
+  `nexus-ai-pro/agent` as well as the root.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,70 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.14.0] - 2026-09-20
+
+The memory, agent, and MCP work planned for 1.13.0 ships here together with tracing, so no 1.13.0 was
+published.
+
+Memory, agents, MCP, and traces. An agent is now a graph rather than a loop, so it inherits
+approvals, parallel tool calls, and durability. A store gives it memory that outlives a thread, MCP
+connects it to tools this package does not have to ship, and every run can be recorded as a tree you
+can search, compare, and alert on.
+
+### Added
+
+- **`nexus-ai-pro/agent` and `createAgent()`.** Returns a compiled graph, so an agent gets
+  checkpoints, resume, forks, events, and a diagram from the graph runtime rather than from code
+  written twice.
+  - Tool calls run as parallel tasks, bounded by `toolConcurrency`.
+  - `interruptOn` makes a tool wait for a human. The approval is a checkpoint, so it can arrive days
+    later from another process, and it can approve, refuse with a reason the model sees, or approve
+    with corrected arguments.
+  - Middleware wraps the model call (`beforeModel`, `afterModel`) and each tool call
+    (`wrapToolCall`).
+  - `stopReason` distinguishes a finished answer from one that ran out of iterations, and malformed
+    tool arguments never reach a tool.
+  - `AgentLoop` is unchanged, for the case that wants none of this.
+- **`nexus-ai-pro/store`, long-term memory.** Namespaced tuples, `put`/`get`/`delete`/`search`/
+  `listNamespaces`, TTLs, and field filters.
+  - Semantic search ranks by any embedding function you inject, so the store never imports the
+    embeddings runtime; without an index, a query matches text.
+  - `MemoryStore` is bounded, like the graph's memory checkpointer. `RedisStore`
+    (`nexus-ai-pro/store/redis`) shares memory across processes through a client-like interface.
+  - `compile({ store })` hands it to every node as `context.store`.
+- **`nexus-ai-pro/tracing`, run trees you can query.** Metrics say how it is going; a trace says what
+  happened.
+  - Every family has a run kind: model, tool, graph, node, agent, retriever, embedding, image, voice,
+    realtime, operation. A run carries inputs, outputs, timing, tokens, cost, tags, and errors.
+  - `traceGraph()` turns the graph's own event stream into a run tree, so nothing inside the graph
+    knows about tracing and an untraced run pays nothing. `traceModelClient()` nests each model call
+    inside the node that made it, with its tokens and cost.
+  - Tail sampling keeps every error, slow run, and expensive run whatever the head rate is, because
+    the decision is made when a trace finishes.
+  - Redaction runs before storage: hidden fields are never written, and a `redact` hook gets the last
+    word.
+  - `MemoryTraceStore` is bounded; `JsonlTraceStore` appends to a file that survives a restart and can
+    be read back, pruned, and rotated.
+  - Queries filter by kind, status, name, model, tags, metadata, latency, cost, time, and feedback.
+    `tree()` assembles a trace, `formatTree()` prints it, and `compareTraces()` reports what changed
+    between two runs of the same shape.
+  - `recordFeedback()` attaches scores from people or from evaluators.
+  - `AlertEvaluator` runs rules over stored runs — error rate, latency percentiles, cost, count — and
+    every alert carries the runs that tripped it. `createWebhookNotifier()` posts them.
+- **Bundled agent middleware.** `summarizeHistory` keeps a long transcript from growing without
+  bound, `redactMessages` keeps secrets out of provider requests and responses, and `limitToolCalls`
+  caps how often a tool may run.
+- **`agentAsTool()`.** Gives one agent to another as a tool, so a supervisor can delegate while
+  keeping control. Each agent keeps its own memory, approvals, and thread.
+
+- **`nexus-ai-pro/mcp`, both directions of the Model Context Protocol.** Implemented directly, with
+  no protocol SDK dependency.
+  - `McpClient` lists and calls tools, reads resources and prompts, and `toNexusTools()` turns a
+    server's tools into tools an agent can call, with optional name prefixes.
+  - `McpServer` exposes this application's tools and resources to other assistants.
+  - Stdio and HTTP transports are included, and the transport is an interface, so a client and a
+    server can be wired together in memory for a test.
+
 ## [1.12.0] - 2026-09-20
 
 Graph control and introspection. A node can route itself, a run can pause at breakpoints and be
@@ -653,7 +717,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.12.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.14.0...HEAD
+[1.14.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.12.0...v1.14.0
 [1.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.11.0...v1.12.0
 [1.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.10.0...v1.11.0
 [1.10.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.9.0...v1.10.0

package/README.md

@@ -655,6 +655,161 @@ private to the subgraph.
 
 The graph is not in the root import. It costs nothing to a user who does not build graphs.
 
+## Agents
+
+An agent is a graph, so everything above applies to it: checkpoints, human approval, parallel work,
+forks, events, and a diagram.
+
+```ts
+import { createAgent, agentInput, tool } from 'nexus-ai-pro/agent';
+
+const agent = createAgent({
+  client: ai,                      // anything with complete(); NexusAI qualifies
+  systemPrompt: 'You are a support engineer.',
+  tools: [refundTool, emailTool],
+  interruptOn: { send_email: true }, // this one waits for a human
+  store,                             // long-term memory, below
+  checkpointer,                      // survives a restart
+});
+
+const run = await agent.invoke(agentInput('Refund order 1182 and tell the customer'), { threadId });
+run.state.answer;      // the final text
+run.state.stopReason;  // 'completed' | 'max_iterations'
+```
+
+**Tool calls run in parallel.** Each call the model requests becomes its own task, bounded by
+`toolConcurrency`, so three lookups take as long as the slowest one.
+
+**Approval is an interrupt, not a callback.** A tool listed in `interruptOn` pauses the run and
+checkpoints it. The answer can approve, refuse with a reason the model sees, or approve with
+corrected arguments:
+
+```ts
+if (run.status === 'awaiting_input') {
+  await agent.resumeWith(threadId, { approved: true, args: { to: 'billing@example.com' } });
+}
+```
+
+Because it is a checkpoint, the approval can arrive days later, from another process.
+
+**Middleware** wraps the parts worth controlling: `beforeModel` adjusts the request, `afterModel`
+inspects or replaces the response, and `wrapToolCall` surrounds each tool call for logging, timing,
+or policy. `AgentLoop` remains for the simple case that needs none of this.
+
+## Long-term Memory
+
+A checkpoint remembers one conversation. A store remembers across them:
+
+```ts
+import { MemoryStore } from 'nexus-ai-pro/store';
+
+const store = new MemoryStore({ index: { embed, fields: ['text'] } });   // embed is yours
+await store.put(['tenant-7', 'users', 'alice'], 'tone', { text: 'prefers brief answers' });
+
+// In any node or tool, in any thread, later:
+const memories = await context.store.search(['tenant-7', 'users', 'alice'], { query: 'how do they like answers?' });
+```
+
+Namespaces are tuples, so `['tenant-7', 'users', 'alice']` is both a place to put something and a
+prefix to search. Items can expire with `ttlMs`, be filtered by field, and be ranked semantically by
+any embedding function you inject — the store never imports the embeddings runtime, and without an
+index a query falls back to matching text. `RedisStore` from `nexus-ai-pro/store/redis` carries the
+same contract across processes through a client-like interface, so no Redis package is a dependency
+here.
+
+## MCP
+
+The Model Context Protocol, both directions, implemented directly rather than through an SDK:
+
+```ts
+import { McpClient, createStdioTransport } from 'nexus-ai-pro/mcp';
+import { Tracer, MemoryTraceStore } from 'nexus-ai-pro/tracing';
+
+const client = new McpClient(createStdioTransport({ command: 'npx', args: ['-y', 'some-mcp-server'] }));
+const agent = createAgent({ client: ai, tools: await client.toNexusTools({ prefix: 'files' }) });
+```
+
+That is how this package reaches a broad tool ecosystem without maintaining a catalogue of
+integrations: anything exposed over MCP becomes tools an agent can call. The server direction lends
+your tools out the same way, so a tool written once with `tool()` serves an agent here and an editor
+elsewhere:
+
+```ts
+import { McpServer, createStdioServerTransport } from 'nexus-ai-pro/mcp';
+
+await new McpServer({ name: 'my-app', tools: [refundTool] }).connect(createStdioServerTransport());
+```
+
+Stdio and HTTP transports are included, and the transport is an interface, so a test can wire a
+client to a server in memory.
+
+## Traces
+
+Metrics say how it is going. A trace says what happened: the run tree of one request, with its
+inputs, outputs, tokens, cost, and errors, stored where you can search it.
+
+```ts
+import { Tracer, MemoryTraceStore, traceGraph, traceModelClient } from 'nexus-ai-pro/tracing';
+
+const tracer = new Tracer({
+  store: new MemoryTraceStore(),               // or JsonlTraceStore({ file })
+  sampling: { rate: 0.05, keepErrors: true },  // 5% of traces, plus every failure
+  redaction: { hideFields: ['apiKey', 'user.email'] },
+});
+
+const tracing = traceGraph(tracer, { name: 'support-agent', kind: 'agent' });
+const agent = createAgent({ client: traceModelClient(ai, tracer, { parent: () => tracing.runFor('model') }) });
+
+const run = await agent.invoke(agentInput(question), { threadId, ...tracing.runOptions });
+await tracing.finish(run);
+```
+
+**Nothing inside the graph knows about tracing.** The graph already reports every task starting,
+retrying, and finishing; a trace is that stream written down as a tree. An application that does not
+trace creates no context, allocates nothing, and does no per-call work.
+
+**Tail sampling keeps what matters.** A 5% rate still records every error, every run slower than a
+threshold, and every run more expensive than one, because the decision is made when the trace
+finishes rather than when it starts.
+
+**Redaction happens before storage**, so a field you hide is never written, and a `redact` hook gets
+the last word on every run.
+
+**Then ask questions of it:**
+
+```ts
+const failures = await store.query({ status: 'error', kind: 'model', since: yesterday, minLatencyMs: 2000 });
+const tree = await store.tree(failures[0].traceId);
+console.log(formatTree(tree));
+
+await tracer.recordFeedback(runId, { key: 'thumbs', score: 0, source: 'user' });
+```
+
+`compareTraces(a, b)` lays two runs of the same shape side by side and reports what changed — the
+step that got slower, the tool that stopped being called, the output that differs — which is how
+"it worked yesterday" becomes an answerable question.
+
+**Alerts** run the same queries on a timer, and carry the runs that tripped them:
+
+```ts
+import { AlertEvaluator, createWebhookNotifier } from 'nexus-ai-pro/tracing';
+
+const alerts = new AlertEvaluator(
+  store,
+  [
+    { name: 'error rate', metric: 'errorRate', threshold: 0.05, minRuns: 20 },
+    { name: 'p95 latency', metric: 'latencyP95', threshold: 8000 },
+    { name: 'hourly spend', metric: 'cost', threshold: 25, windowMs: 3_600_000 },
+  ],
+  { notifier: createWebhookNotifier({ url: process.env.ALERT_WEBHOOK! }) },
+);
+
+setInterval(() => void alerts.evaluate(), 60_000);
+```
+
+An alert names the rule, the measured value, and three runs that contributed, so the next step is
+reading them rather than starting an investigation.
+
 ## Provider Batch Tiers
 
 Both OpenAI and Anthropic sell an asynchronous tier at roughly half price, in exchange for a
@@ -1925,6 +2080,7 @@ only, so it never appears in an import graph.
 | `nexus-ai-pro/providers/llamacpp` | 77 KB | 13% | none |
 | `nexus-ai-pro/providers/lmstudio` | 77 KB | 13% | none |
 | `nexus-ai-pro/providers/openai` | 77 KB | 13% | none |
+| `nexus-ai-pro/agent` | 76 KB | 12% | none |
 | `nexus-ai-pro/providers/anthropic` | 70 KB | 11% | none |
 | `nexus-ai-pro/providers/google` | 66 KB | 11% | none |
 | `nexus-ai-pro/images` | 65 KB | 11% | none |
@@ -1940,6 +2096,7 @@ only, so it never appears in an import graph.
 | `nexus-ai-pro/models` | 35 KB | 6% | none |
 | `nexus-ai-pro/images/inputs` | 31 KB | 5% | none |
 | `nexus-ai-pro/realtime/openai-websocket` | 29 KB | 5% | none |
+| `nexus-ai-pro/tracing` | 26 KB | 4% | none |
 | `nexus-ai-pro/evals` | 23 KB | 4% | none |
 | `nexus-ai-pro/images/transform` | 22 KB | 4% | none |
 | `nexus-ai-pro/images/stores` | 22 KB | 4% | none |
@@ -1948,6 +2105,7 @@ only, so it never appears in an import graph.
 | `nexus-ai-pro/images/openai` | 19 KB | 3% | none |
 | `nexus-ai-pro/realtime/mock` | 19 KB | 3% | none |
 | `nexus-ai-pro/voice` | 18 KB | 3% | none |
+| `nexus-ai-pro/mcp` | 18 KB | 3% | none |
 | `nexus-ai-pro/images/comfyui` | 17 KB | 3% | none |
 | `nexus-ai-pro/embeddings/adapters` | 17 KB | 3% | none |
 | `nexus-ai-pro/realtime/conversation` | 16 KB | 3% | none |
@@ -1961,6 +2119,7 @@ only, so it never appears in an import graph.
 | `nexus-ai-pro/images/mock` | 12 KB | 2% | none |
 | `nexus-ai-pro/optimizer` | 11 KB | 2% | none |
 | `nexus-ai-pro/voice/session` | 11 KB | 2% | none |
+| `nexus-ai-pro/store/redis` | 11 KB | 2% | none |
 | `nexus-ai-pro/providers` | 10 KB | 2% | none |
 | `nexus-ai-pro/providers/base` | 10 KB | 2% | none |
 | `nexus-ai-pro/embeddings/models` | 10 KB | 2% | none |
@@ -1971,6 +2130,7 @@ only, so it never appears in an import graph.
 | `nexus-ai-pro/capabilities` | 8 KB | 1% | none |
 | `nexus-ai-pro/telephony/realtime-bridge` | 7 KB | 1% | none |
 | `nexus-ai-pro/graph/visualize` | 6 KB | 1.0% | none |
+| `nexus-ai-pro/store` | 6 KB | 1.0% | none |
 | `nexus-ai-pro/providers/errors` | 5 KB | 0.8% | none |
 | `nexus-ai-pro/embeddings/mock` | 5 KB | 0.8% | none |
 | `nexus-ai-pro/cache/semantic-cache` | 5 KB | 0.8% | none |

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

@@ -0,0 +1,119 @@
+import { type CompiledGraph } from '../graph/graph.js';
+import type { GraphCheckpointer, NodeContext } from '../types/graph.js';
+import type { CompletionRequest, Message, ToolDefinition } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+import type { Store } from '../types/store.js';
+/**
+ * An agent as a graph.
+ *
+ * `AgentLoop` is a `while` loop: it cannot be paused, resumed after a restart, inspected halfway, or
+ * made to run two tool calls at once, because a loop has nowhere to keep that state. The same agent
+ * expressed as a graph inherits all of it — checkpoints, human approval through `interrupt()`,
+ * parallel tool tasks through `Send`, forks, events, and a Mermaid diagram — without this module
+ * implementing any of them. `AgentLoop` stays for the simple case that wants none of that.
+ */
+/** The model call an agent makes. Injected, so this module needs no provider runtime. */
+export interface AgentModelClient {
+    complete(request: CompletionRequest): Promise<NexusResponse>;
+}
+export interface AgentToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+/** What an approver may answer: allow, refuse with a reason, or allow with corrected arguments. */
+export type AgentApproval = boolean | {
+    approved: true;
+    args?: Record<string, unknown>;
+} | {
+    approved: false;
+    reason?: string;
+};
+export interface AgentApprovalPolicy {
+    /** The question an operator sees. Defaults to naming the tool and its arguments. */
+    reason?: (call: AgentToolCall) => string;
+}
+export interface AgentMiddleware {
+    name?: string;
+    /** Adjusts the request before it is sent: trim history, add context, swap the model. */
+    beforeModel?(context: {
+        request: CompletionRequest;
+        state: AgentState;
+        store?: Store;
+    }): CompletionRequest | void | Promise<CompletionRequest | void>;
+    /** Inspects or replaces the response: redact, validate, count. */
+    afterModel?(context: {
+        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;
+}
+export interface AgentToolResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface CreateAgentOptions {
+    client: AgentModelClient;
+    model?: string;
+    tools?: ToolDefinition[];
+    systemPrompt?: string;
+    /** Model calls before the agent stops with `stopReason: 'max_iterations'`. Defaults to 8. */
+    maxIterations?: number;
+    /** Tool calls run at once. Defaults to 8; `1` runs them one at a time. */
+    toolConcurrency?: number;
+    /** Tools that need human approval before they run, keyed by tool name. */
+    interruptOn?: Record<string, AgentApprovalPolicy | true>;
+    middleware?: AgentMiddleware[];
+    /** Long-term memory, available to tools and middleware as `store`. */
+    store?: Store;
+    checkpointer?: GraphCheckpointer | false;
+    name?: string;
+    temperature?: number;
+    maxTokens?: number;
+    responseFormat?: CompletionRequest['responseFormat'];
+    metadata?: Record<string, unknown>;
+}
+declare const agentChannels: () => {
+    messages: import("../types/graph.js").Channel<Message[]>;
+    iterations: import("../types/graph.js").Channel<number>;
+    answer: import("../types/graph.js").Channel<string>;
+    stopReason: import("../types/graph.js").Channel<AgentStopReason | undefined>;
+};
+export type AgentChannels = ReturnType<typeof agentChannels>;
+export type AgentState = {
+    messages: Message[];
+    iterations: number;
+    answer: string;
+    stopReason?: AgentStopReason;
+};
+export type AgentStopReason = 'completed' | 'max_iterations';
+export type AgentGraph = CompiledGraph<AgentChannels>;
+/** Wraps a question into the state an agent starts from. */
+export declare function agentInput(goal: string): {
+    messages: Message[];
+};
+/**
+ * Builds an agent and returns it as a compiled graph.
+ *
+ * Run it like any graph: `agent.invoke(agentInput('...'), { threadId })`. The result's `answer` is
+ * the final text, and `stopReason` says whether the agent finished or ran out of iterations.
+ */
+export declare function createAgent(options: CreateAgentOptions): AgentGraph;
+/**
+ * Turns an agent into a tool another agent can call.
+ *
+ * The simplest multi-agent shape: a supervisor keeps control and delegates, rather than handing over
+ * the conversation. The specialist runs as its own graph, with its own memory and approvals, and
+ * returns its answer as the tool result.
+ */
+export declare function agentAsTool(options: {
+    agent: AgentGraph;
+    name: string;
+    description: string;
+    /** Threads the specialist's runs, so its work is resumable too. Defaults to a fresh thread. */
+    threadId?: (goal: string) => string;
+}): ToolDefinition;
+export type { NodeContext };

package/dist/agent/create-agent.js

@@ -0,0 +1,176 @@
+import { appendList, counter, lastValue } from '../graph/channels.js';
+import { createGraph } from '../graph/graph.js';
+import { Command, END, Send } from '../types/graph.js';
+import { ToolExecutor } from './tool.js';
+const agentChannels = () => ({
+    messages: appendList(),
+    iterations: counter(),
+    answer: lastValue(''),
+    stopReason: lastValue(undefined),
+});
+/** Wraps a question into the state an agent starts from. */
+export function agentInput(goal) {
+    return { messages: [{ role: 'user', content: goal }] };
+}
+/**
+ * Builds an agent and returns it as a compiled graph.
+ *
+ * Run it like any graph: `agent.invoke(agentInput('...'), { threadId })`. The result's `answer` is
+ * the final text, and `stopReason` says whether the agent finished or ran out of iterations.
+ */
+export function createAgent(options) {
+    if (typeof options.client?.complete !== 'function') {
+        throw new TypeError('createAgent needs a client with a complete() method');
+    }
+    const maxIterations = Math.max(1, options.maxIterations ?? 8);
+    const executor = new ToolExecutor(options.tools ?? []);
+    const middleware = options.middleware ?? [];
+    const approvals = options.interruptOn ?? {};
+    const graph = createGraph({ channels: agentChannels() })
+        .addNode('model', async (context) => {
+        const state = context.state;
+        let request = {
+            model: options.model ?? 'auto',
+            messages: [
+                ...(options.systemPrompt ? [{ role: 'system', content: options.systemPrompt }] : []),
+                ...state.messages,
+            ],
+            ...(options.tools?.length ? { tools: executor.list() } : {}),
+            ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+            ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
+            ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+        };
+        for (const item of middleware) {
+            request = (await item.beforeModel?.({ request, state, store: options.store })) ?? request;
+        }
+        let response = await options.client.complete(request);
+        for (const item of middleware) {
+            response = (await item.afterModel?.({ response, state, store: options.store })) ?? response;
+        }
+        const assistant = {
+            role: 'assistant',
+            content: response.content,
+            ...(response.toolCalls?.length ? { toolCalls: response.toolCalls } : {}),
+        };
+        const calls = response.toolCalls ?? [];
+        if (calls.length === 0) {
+            return new Command({
+                update: { messages: [assistant], iterations: 1, answer: response.content, stopReason: 'completed' },
+                goto: END,
+            });
+        }
+        if (state.iterations + 1 >= maxIterations) {
+            // The model still wants tools but has used its budget; say so rather than pretending the
+            // last message is an answer.
+            return new Command({
+                update: { messages: [assistant], iterations: 1, answer: response.content, stopReason: 'max_iterations' },
+                goto: END,
+            });
+        }
+        return new Command({
+            update: { messages: [assistant], iterations: 1 },
+            goto: calls.map((call) => new Send('tools', call)),
+        });
+    }, { ends: ['tools', END] })
+        .addNode('tools', async (context) => {
+        const call = context.input;
+        const parsed = parseArguments(call.function.arguments);
+        if (!parsed.ok) {
+            return { messages: [toolMessage(call, { ok: false, error: parsed.error })] };
+        }
+        let args = parsed.args;
+        const description = { id: call.id, name: call.function.name, args };
+        const policy = approvals[description.name];
+        if (policy) {
+            const decision = context.interrupt({
+                reason: (policy === true ? undefined : policy.reason?.(description)) ?? defaultReason(description),
+                payload: description,
+            });
+            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)
+                args = verdict.args;
+        }
+        const run = async () => executor.execute(description.name, args);
+        const result = await middleware.reduceRight((next, item) => item.wrapToolCall
+            ? () => Promise.resolve(item.wrapToolCall?.({ ...description, args }, next))
+            : next, run)();
+        return { messages: [toolMessage(call, result)] };
+    }, { ends: ['model'] })
+        .setEntry('model')
+        .addEdge('tools', 'model');
+    return graph.compile({
+        // Each iteration is two supersteps, plus the entry and a margin for a paused approval.
+        maxSteps: maxIterations * 2 + 4,
+        maxConcurrency: options.toolConcurrency ?? 8,
+        ...(options.checkpointer === undefined ? {} : { checkpointer: options.checkpointer }),
+        ...(options.store ? { store: options.store } : {}),
+        ...(options.name ? { name: options.name } : {}),
+    });
+}
+/**
+ * Turns an agent into a tool another agent can call.
+ *
+ * The simplest multi-agent shape: a supervisor keeps control and delegates, rather than handing over
+ * the conversation. The specialist runs as its own graph, with its own memory and approvals, and
+ * returns its answer as the tool result.
+ */
+export function agentAsTool(options) {
+    return {
+        name: options.name,
+        description: options.description,
+        parameters: {
+            type: 'object',
+            properties: { goal: { type: 'string', description: 'What this agent should do' } },
+            required: ['goal'],
+        },
+        execute: async (args) => {
+            const goal = String(args.goal ?? '');
+            const result = await options.agent.invoke(agentInput(goal), {
+                ...(options.threadId ? { threadId: options.threadId(goal) } : {}),
+            });
+            if (result.status === 'awaiting_input') {
+                return `The ${options.name} agent is waiting for a human: ${result.interrupt?.reason ?? 'approval needed'}`;
+            }
+            return result.state.answer;
+        },
+    };
+}
+/** Turns a tool result into the message the model reads next. */
+function toolMessage(call, result) {
+    return {
+        role: 'tool',
+        toolCallId: call.id,
+        content: JSON.stringify(result.ok ? (result.result ?? null) : { error: result.error }),
+    };
+}
+function defaultReason(call) {
+    return `Run tool "${call.name}" with ${JSON.stringify(call.args)}?`;
+}
+function normalizeApproval(decision) {
+    if (typeof decision === 'boolean')
+        return { approved: decision };
+    return decision.approved
+        ? { approved: true, ...(decision.args ? { args: decision.args } : {}) }
+        : { approved: false, ...(decision.reason ? { reason: decision.reason } : {}) };
+}
+/** Arguments the model did not actually send must never reach a tool. */
+function parseArguments(raw) {
+    if (!raw?.trim())
+        return { ok: true, args: {} };
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed))
+            return { ok: true, args: parsed };
+        return { ok: false, error: 'Tool arguments must be a JSON object; the tool was not run' };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
+    }
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,5 @@
+export { AgentLoop, type AgentModelClient as AgentLoopModelClient } from './loop.js';
+export { tool, ToolExecutor } 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 type { AgentConfig, AgentResult, AgentStep, ToolExecutionResult } from '../types/agent.js';

package/dist/agent/index.js

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

package/dist/agent/middleware.d.ts

@@ -0,0 +1,46 @@
+import type { Message } from '../types/messages.js';
+import type { AgentMiddleware } from './create-agent.js';
+/**
+ * Middleware that ships with the agent.
+ *
+ * Each is small on purpose: the seam matters more than the set, and an application's real policy is
+ * usually its own. These cover the three every long-running agent needs — a transcript that does not
+ * grow forever, secrets that never reach a provider, and a cap on tool use.
+ */
+export interface SummarizeOptions {
+    /** Messages kept verbatim at the end of the transcript. Defaults to 6. */
+    keepLast?: number;
+    /** Summarizing starts once the transcript passes this many messages. Defaults to 20. */
+    triggerAfter?: number;
+    /** Turns the older messages into one summary. Usually a cheap model. */
+    summarize: (messages: Message[]) => Promise<string> | string;
+}
+/**
+ * Replaces the older half of a long transcript with a summary.
+ *
+ * An agent that runs for hours otherwise re-sends its whole history on every call, which costs more
+ * each turn and eventually exceeds the context window.
+ */
+export declare function summarizeHistory(options: SummarizeOptions): AgentMiddleware;
+export interface RedactOptions {
+    /** Patterns replaced before a message reaches the provider. */
+    patterns: readonly RegExp[];
+    replacement?: string;
+    /** Also redact what the model sends back, for anything written to logs or state. */
+    redactOutput?: boolean;
+}
+/**
+ * Redacts matching text from requests, and optionally from responses.
+ *
+ * For an agent whose transcript may contain a key, an account number, or anything else that should
+ * not leave the process. The full security pipeline is in `nexus-ai-pro/security`; this is the small
+ * version that needs no configuration.
+ */
+export declare function redactMessages(options: RedactOptions): AgentMiddleware;
+/**
+ * Caps how often a tool may be called in one run.
+ *
+ * A model that loops on the same call otherwise burns the iteration budget, and with an expensive
+ * tool it burns money too.
+ */
+export declare function limitToolCalls(limits: Record<string, number>): AgentMiddleware;