nexus-ai-pro 1.11.0 → 1.14.0

package/API_STABILITY.md

@@ -313,6 +313,48 @@ Also since 1.11.0, all additive:
 - `context.taskId` and `context.attempt` are new. Step events carry `tasks` and `attempts` when there
   is something to report.
 
+Also since 1.12.0, all additive:
+
+- `Command` (with `Command.PARENT`) may be returned from a node; `NodeResult` names what a node may
+  return. `goto` routes are added to the node's outgoing edges, and a paused checkpoint records them in
+  the optional `gotos` field.
+- `interruptBefore` and `interruptAfter` on compile and run options; a paused checkpoint and result
+  carry `breakpoint`, and step events may have type `breakpoint`.
+- `NodeOptions.defer`, `GraphRunOptions.onEvent` with the `GraphEvent` union, and `context.emit()`.
+  New `GraphEvent` variants may be added in a minor release.
+- `updateState()`, `fork()`, and `describe()` on a compiled graph, and the `nexus-ai-pro/graph/visualize`
+  subpath. The exact Mermaid text `toMermaid()` produces is not a guarantee — diagram layout may
+  improve in a minor release — but `GraphDescription` is a normalized shape.
+- 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,109 @@ 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
+edited or forked, every task and custom event can be watched as it happens, and a graph can draw
+itself.
+
+### Added
+
+- **`Command`.** A node returns `new Command({ update, goto })` to write state and choose its
+  successors in one step, instead of splitting the decision into a separate router. `goto` takes node
+  names or `Send`s. A route chosen by a task that finished before its step paused is kept on the
+  checkpoint, so it is still followed when the step resumes.
+- **`Command.PARENT`.** A node inside a subgraph hands control back to the graph that contains it. The
+  subgraph's own writes and the update it addressed to the parent are reduced separately, in order,
+  so neither overwrites the other.
+- **Breakpoints.** `interruptBefore` and `interruptAfter`, per compile or per run, pause a run at
+  chosen nodes with status `interrupted` and a `breakpoint` describing where. `continue()` carries on,
+  and does not pause again at the breakpoint it resumes from.
+- **Deferred nodes.** `addNode(name, fn, { defer: true })` holds a node until every other pending task
+  has finished, so an aggregator after branches of different lengths runs once.
+- **`updateState()`.** Merges a correction into a thread's latest checkpoint in place, keeping any
+  pending question; with `asNode`, applies it as that node's output and continues along its edges.
+- **`fork()`.** Copies a thread's history up to a step into a new thread, leaving the original
+  untouched and runnable, and records `metadata.forkedFrom`.
+- **`onEvent` and `context.emit()`.** A run can observe each task starting, retrying, and finishing
+  with its update, every checkpoint written, and custom events a node emits, such as model tokens. A
+  listener that throws never fails the run.
+- **`describe()` and `nexus-ai-pro/graph/visualize`.** `describe()` returns a graph's nodes, edges, and
+  run-time routes as plain JSON, including subgraphs. `toMermaid()` draws it, with optional
+  highlighting of where a thread is; `toGraphJSON()` returns the data. The visualizer imports no
+  runtime code.
+
+### Fixed
+
+- **Parallel copies of a subgraph node no longer share a thread.** `asNode()` keyed the subgraph's
+  thread by node name, so two `Send` copies of one subgraph node in the same step wrote to the same
+  thread. It is now keyed by task; a plain node's task id is its name, so existing threads are
+  unaffected.
+
 ## [1.11.0] - 2026-09-18
 
 Parallel graphs. A fan-out that looks parallel now runs in parallel, a graph can fan out over data it
@@ -614,7 +717,9 @@ 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.11.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
 [1.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.8.0...v1.9.0

package/README.md

@@ -1,8 +1,12 @@
 # nexus-ai-pro
 
-The Universal AI Pipeline for Node.js: one typed API for routing, guardrails, caching, context-window management, tools, RAG, evals, jobs, and provider failover.
+The typed AI framework for TypeScript. One API for provider routing and failover, agent graphs that
+run branches in parallel and survive a restart, durable background operations, guardrails, cost
+control, images, voice, and evals.
 
-Use the whole pipeline for production AI features, or turn pieces off when you only need a thin provider wrapper.
+Import the whole runtime, or one piece: every capability has its own entry point with a size budget
+CI enforces, and the table below publishes what each one costs. A graph-only application loads 60 KB
+and installs no third-party package at all.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
@@ -533,6 +537,98 @@ await graph.history(threadId);      // newest first
 graph.resumeFrom(threadId, 3);      // rewind and run forward
 ```
 
+**Route from inside a node.** When a node already knows where to go — an agent that just picked a
+tool, a triage step that classified a ticket — return a `Command` instead of splitting the decision
+into a separate router:
+
+```ts
+import { Command } from 'nexus-ai-pro/graph';
+
+.addNode('triage', (ctx) =>
+  new Command({ update: { label: classify(ctx.state) }, goto: isUrgent(ctx.state) ? 'page-oncall' : 'queue' }),
+  { ends: ['page-oncall', 'queue'] },
+)
+```
+
+`goto` takes node names or `Send`s, and `ends` keeps compile-time checks and diagrams exact. A node
+inside a subgraph can return `new Command({ graph: Command.PARENT, goto: 'human' })` to hand control
+back to the graph that contains it — how a nested agent escalates.
+
+**Aggregate after branches of different lengths.** `{ defer: true }` holds a node until every other
+pending task has finished, so an aggregator after a two-step branch and a one-step branch runs once,
+after both, rather than once per arrival.
+
+**Pause for inspection.** Breakpoints stop a run before or after chosen nodes, checkpointed, without
+changing the nodes themselves:
+
+```ts
+const graph = builder.compile({ interruptBefore: ['publish'] });
+const paused = await graph.invoke(input, { threadId });   // status: 'interrupted', breakpoint: { when: 'before', ... }
+await graph.updateState(threadId, { draft: fixedDraft }); // correct something first, if needed
+for await (const _ of graph.continue(threadId)) {}         // then carry on
+```
+
+Set them per compile or per run; a run's list replaces the compiled one.
+
+**Edit state, or fork a thread.** `updateState(threadId, update)` merges a correction into the latest
+checkpoint through the channel reducers, leaving any pending question in place.
+`updateState(threadId, update, { asNode: 'research' })` applies it as if that node had produced it,
+so the next step follows that node's edges. `fork(threadId, { step })` copies the history up to a step
+into a new thread and leaves the original untouched, so two answers to the same question can be run
+side by side.
+
+**Watch it run.** `onEvent` receives every task starting, retrying, and finishing with its update,
+every checkpoint written, and whatever a node passes to `context.emit()` — model tokens as they
+stream, a status line, an intermediate result:
+
+```ts
+.addNode('write', async (ctx) => {
+  for await (const token of streamAnswer(ctx.state)) ctx.emit({ token });
+  return { answer };
+})
+
+await graph.invoke(input, {
+  onEvent: (event) => event.type === 'custom' && process.stdout.write((event.data as { token: string }).token),
+});
+```
+
+A listener that throws never fails the run it is watching.
+
+**See the shape.** `graph.describe()` returns nodes, edges, and which routes are decided at run
+time, as plain JSON. `toMermaid()` from `nexus-ai-pro/graph/visualize` draws it — solid arrows are
+always taken, dotted ones are chosen at run time, and subgraphs are drawn inside the node that runs
+them:
+
+```ts
+import { toMermaid } from 'nexus-ai-pro/graph/visualize';
+
+console.log(toMermaid(graph, { highlight: checkpoint.next }));
+```
+
+This diagram is that function's actual output for a research-and-review graph:
+
+```mermaid
+flowchart TD
+  __start__([start])
+  __end__([end])
+  n_plan["plan"]
+  n_research["research<br/><small>retries</small>"]
+  n_summarize["summarize<br/><small>deferred</small>"]
+  n_review["review"]
+  n_publish["publish"]
+  __start__ --> n_plan
+  n_summarize --> n_review
+  n_publish --> __end__
+  n_plan -.-> n_research
+  n_research -.-> n_summarize
+  n_review -.-> n_publish
+  n_review -.-> n_plan
+```
+
+The visualizer is its own subpath and imports no runtime code, so drawing a graph costs nothing to an
+application that only runs one. No image renderer is bundled; any Mermaid renderer turns the output
+into PNG or SVG.
+
 **Durable by construction.** The default checkpointer is in-process, holding up to 1,000 threads;
 pass `checkpointer: false` to turn checkpointing off. Point it at the operation store
 that already backs durable operations and a thread survives a restart — a different worker resumes
@@ -559,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
@@ -1829,21 +2080,23 @@ 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 |
+| `nexus-ai-pro/graph` | 60 KB | 10% | none |
 | `nexus-ai-pro/providers/ollama` | 58 KB | 9% | none |
 | `nexus-ai-pro/batch/openai` | 52 KB | 8% | none |
 | `nexus-ai-pro/batch/anthropic` | 52 KB | 8% | none |
 | `nexus-ai-pro/operations` | 49 KB | 8% | none |
 | `nexus-ai-pro/batch/mock` | 47 KB | 8% | none |
 | `nexus-ai-pro/providers/cohere` | 46 KB | 8% | none |
-| `nexus-ai-pro/graph` | 46 KB | 8% | none |
 | `nexus-ai-pro/realtime/openai-webrtc` | 46 KB | 8% | none |
 | `nexus-ai-pro/security` | 40 KB | 7% | +3.4 MB |
 | `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 |
@@ -1852,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 |
@@ -1865,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 |
@@ -1874,6 +2129,8 @@ only, so it never appears in an import graph.
 | `nexus-ai-pro/realtime/openai-server` | 8 KB | 1% | none |
 | `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 };