nexus-ai-pro 1.12.0 → 1.15.0

package/API_STABILITY.md

@@ -328,6 +328,50 @@ 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.
+
+## Evaluation stage (1.15.0)
+
+`nexus-ai-pro/evaluate` is public and follows the 1.x rules, and is not exported from the root.
+`Dataset`, `DatasetExample`, `Experiment`, `ExampleResult`, `MetricSummary`, and the comparison shapes
+are normalized; new optional fields and new bundled evaluators may be added in a minor release.
+
+- A dataset version is derived from example content. The hash itself is an implementation detail, but
+  the guarantee is not: identical examples produce identical versions, and any change produces a
+  different one.
+- `compareExperiments()` is statistical. Its intervals come from a seeded paired bootstrap, so the
+  same inputs give the same verdict; the exact interval bounds may change if the method improves, and
+  a verdict is a judgement about evidence rather than a compatibility guarantee.
+- `evaluate()` reports a target's failure as a failed example and an evaluator's failure as a failed
+  measurement; neither throws.
+- The existing `EvalRunner` and `MediaEvalRunner` keep their APIs unchanged. Rebuilding them on this
+  entry point is a later, internal change.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,104 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-09-21
+
+Evaluation. One entry point for evaluating anything, datasets versioned by their content, experiments
+that can be compared with a verdict rather than a vibe, and the loop from a production failure back to
+a permanent regression test.
+
+### Added
+
+- **`nexus-ai-pro/evaluate`.** `evaluate(target, dataset, evaluators, options)` accepts any target: a
+  completion, an agent, a graph, an image operation, or plain code.
+  - Examples run concurrently, with repetitions for a target that is not deterministic, a timeout per
+    example, and per-metric statistics including a 95% interval.
+  - A target that throws is recorded as a failed example; an evaluator that throws is recorded as a
+    failed measurement. Neither voids the experiment.
+- **Datasets versioned by content.** Change an example and the version changes with it, so two
+  experiments are comparable only when they ran over the same data. `MemoryDatasetStore` and
+  `FileDatasetStore` (one reviewable JSON file per version), plus `splitOf()` for train and test
+  splits.
+- **`datasetFromTraces()`.** Turns recorded runs into examples, each keeping the run it came from, so
+  yesterday's production failure becomes tomorrow's regression test.
+- **Bundled evaluators.** `exactMatch`, `contains`, `mustNotMatch`, `completed`, `underLatency`,
+  `embeddingSimilarity` through any injected embedder, `pairwise` for side-by-side judgements, and
+  `trajectory`, which scores how an answer was reached rather than only what it said. `passRate` and
+  `totalCost` summarize a whole experiment.
+- **`compareExperiments()` with a real verdict.** A paired bootstrap over per-example differences
+  gives each metric a 95% interval; a metric whose interval spans zero is `unchanged` rather than an
+  improvement. The bootstrap is seeded, so a CI gate cannot flip between runs. The report names the
+  examples that moved most, the failures that are new, the ones that were fixed, and any dataset
+  version mismatch. `formatComparison()` prints it for a pull request.
+- **`evaluateOnline()`.** Scores sampled production runs, writes the scores back as trace feedback so
+  alert rules can watch them, and sends uncertain results to people.
+- **`AnnotationQueue`.** Review work with a rubric, claims that expire so nothing is stranded,
+  consensus across several reviewers, and `toExamples()` to turn reviewed items into dataset examples.
+
+## [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 +751,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.12.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.15.0...HEAD
+[1.15.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.14.0...v1.15.0
+[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,249 @@ 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';
+import { evaluate, createDataset, compareExperiments } from 'nexus-ai-pro/evaluate';
+
+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.
+
+## Evaluation
+
+One entry point for evaluating anything: a completion, an agent, a graph, an image operation, or
+plain code. A dataset of examples, a target that turns an example into an output, evaluators that
+score it, and a stored experiment a later run can be compared against.
+
+```ts
+import { evaluate, createDataset, exactMatch, contains, trajectory, passRate } from 'nexus-ai-pro/evaluate';
+
+const dataset = createDataset({
+  name: 'support-questions',
+  examples: [
+    { id: 'refund', inputs: { question: 'how do I get a refund?' }, expected: 'Open the order and choose refund.' },
+    { id: 'hours', inputs: { question: 'when are you open?' }, expected: 'Weekdays, nine to five.' },
+  ],
+});
+
+const experiment = await evaluate(
+  (inputs) => agent.invoke(agentInput(inputs.question)),
+  dataset,
+  [contains(['refund']), trajectory({ expected: ['search_orders'] })],
+  { repetitions: 3, concurrency: 4, summary: [passRate()], store: experiments },
+);
+```
+
+**A dataset is versioned by its content**, so two experiments are comparable only when they really
+ran over the same examples. Change an example and the version changes with it.
+
+**Datasets can come from production.** `datasetFromTraces({ store, query: { status: 'error' } })`
+turns recorded runs into examples, each keeping the run it came from — the request that failed
+yesterday becomes tomorrow's regression test.
+
+**Evaluators are ordinary functions.** Bundled: `exactMatch`, `contains`, `mustNotMatch`, `completed`,
+`underLatency`, `embeddingSimilarity` through any embedder, `pairwise` for side-by-side judgements,
+and `trajectory`, which scores *how* an answer was reached — an agent that gets the right answer by
+calling the refund tool three times is not working. The LLM judge from `nexus-ai-pro/evals/judge`
+plugs in as one more evaluator.
+
+### Was the change real?
+
+```ts
+import { compareExperiments, formatComparison } from 'nexus-ai-pro/evaluate';
+
+const comparison = compareExperiments(baseline, candidate);
+console.log(formatComparison(comparison));
+if (comparison.regressed) process.exit(1);
+```
+
+A mean that moves from 0.81 to 0.83 says nothing on its own; with twenty examples that is noise, and
+shipping on it makes a quality gate a coin toss. The verdict comes from a **paired bootstrap** over
+the per-example differences, which assumes nothing about how the scores are distributed, and the
+pairing removes the variation caused by the examples themselves. A metric whose interval spans zero
+is reported as `unchanged`, not as an improvement. The bootstrap is seeded, so CI gives the same
+verdict twice.
+
+The report names the examples that moved most, the failures that are new, and the ones that were
+fixed. A comparison across different dataset versions says so rather than pretending it is like for
+like.
+
+### The runs you did not think of
+
+```ts
+import { evaluateOnline, AnnotationQueue } from 'nexus-ai-pro/evaluate';
+
+const queue = new AnnotationQueue({
+  rubric: [{ key: 'helpful', prompt: 'Did this answer the question?', type: 'boolean' }],
+  consensus: 2,
+});
+
+await evaluateOnline({
+  store: traceStore,
+  evaluators: [mustNotMatch([/i cannot help/i])],
+  sampleRate: 0.1,
+  reviewQueue: queue,
+  reviewWhen: (scores) => scores.some((score) => score.passed === false),
+});
+```
+
+A dataset tells you whether a change works on the cases you thought of; online evaluation tells you
+how it is doing on the rest. Scores are written back as feedback on the run, so an alert rule can
+watch them, and anything uncertain goes to a person.
+
+**The review queue keeps track of what people owe you.** Claims expire, so a reviewer who closes the
+tab does not strand an item; `consensus` lets two reviewers see the same item when one opinion is not
+enough; and `toExamples()` turns reviewed items into dataset examples, which closes the loop from a
+production failure to a permanent regression test.
+
 ## Provider Batch Tiers
 
 Both OpenAI and Anthropic sell an asynchronous tier at roughly half price, in exchange for a
@@ -1925,6 +2168,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 |
@@ -1938,8 +2182,10 @@ only, so it never appears in an import graph.
 | `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/evaluate` | 33 KB | 5% | 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 +2194,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 +2208,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 +2219,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 };