@anvia/cli 1.1.1 → 1.3.0

package/dist/skills/anvia-evals/scripts/check-evals.sh

@@ -0,0 +1,73 @@
+#!/bin/sh
+# Heuristic checks for Anvia eval code in an app directory.
+# Usage: sh scripts/check-evals.sh [--dir <app-root>]
+# Fails with a list of violations; passes silently with "evals OK".
+
+DIR="."
+if [ "$1" = "--dir" ] && [ -n "$2" ]; then
+  DIR="$2"
+fi
+
+ROOTS_FOUND=0
+for root in "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" "$DIR/evals"; do
+  if [ -d "$root" ]; then
+    ROOTS_FOUND=1
+    break
+  fi
+done
+if [ "$ROOTS_FOUND" -eq 0 ]; then
+  echo "ERROR: no src/app/lib/server/evals directory under '$DIR' — nothing was checked."
+  echo "Run from the app root or pass --dir <app-root>."
+  exit 1
+fi
+
+fail=0
+violation() {
+  echo "VIOLATION: $1"
+  fail=1
+}
+warning() {
+  echo "WARNING: $1"
+}
+
+FILES=$(grep -rln --include='*.ts' \
+  -e 'runEvalSuite' -e 'runEvalCli' -e 'llmJudge' -e 'llmScore' -e 'gEval(' \
+  "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" "$DIR/evals" 2>/dev/null | sort -u)
+
+if [ -z "$FILES" ]; then
+  echo "evals OK (no eval code found)"
+  exit 0
+fi
+
+# 1. Eval runs need a stable name (history and expectations key off it).
+if echo "$FILES" | xargs grep -l -e 'runEvalSuite' -e 'runEvalCli' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A6 -e 'runEvalSuite(' -e 'runEvalCli(' 2>/dev/null | grep -q 'name:' || {
+    violation "runEvalSuite/runEvalCli without name (see references/running.md)."
+  }
+fi
+
+# 2. llmScore needs a threshold; llmJudge needs a passes predicate.
+if echo "$FILES" | xargs grep -l 'llmScore(' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A8 'llmScore(' 2>/dev/null | grep -q 'threshold' || {
+    violation "llmScore without threshold (see references/judges.md)."
+  }
+fi
+if echo "$FILES" | xargs grep -l 'llmJudge(' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A8 'llmJudge(' 2>/dev/null | grep -q 'passes' || {
+    violation "llmJudge without passes predicate (see references/judges.md)."
+  }
+fi
+
+# 3. CI runs should fail the build on regression (warning only).
+if echo "$FILES" | xargs grep -l 'runEvalCli' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A20 'runEvalCli(' 2>/dev/null | grep -q 'exitCode' || {
+    warning "runEvalCli without exitCode will not fail CI (see references/running.md)."
+  }
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "evals OK"
+  exit 0
+fi
+echo "See skills/anvia-evals/references/ for fixes."
+exit 1

package/dist/skills/anvia-mcp/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: anvia-mcp
+description: Connect MCP servers to Anvia agents — clients, transports, tool discovery, URL safety, and lifecycle.
+---
+
+# Anvia MCP Skill
+
+Use this skill when the user wants tools from an MCP server: configuring an
+`McpClient`, choosing stdio vs Streamable HTTP, handling version negotiation
+and URL safety, grouping servers, or wiring them into an `Agent`.
+
+## Process
+
+1. Configure clients (`references/clients.md`) — one `McpClient` per server.
+2. Apply the safety rules (`references/safety.md`) — especially for HTTP servers.
+3. Run `scripts/check-mcp.sh` from the app root before claiming done.
+
+## Minimal slice
+
+```ts
+import { Agent } from "@anvia/core/agent";
+import { McpClient } from "@anvia/mcp";
+
+const counterMcp = new McpClient({
+  name: "counter",
+  transport: { type: "stdio", command: "tsx", args: ["./mcp-counter-server.ts"] },
+});
+const counterServer = await counterMcp.connect();
+
+try {
+  const agent = new Agent({
+    id: "agent",
+    model: agentModel,
+    instructions: "Use MCP tools for arithmetic and counter updates.",
+    mcpServers: [counterServer], // the only path for MCP tools — never via skills
+    maxTurns: 3,
+  });
+  for await (const event of agent.stream({ prompt: "Add 8 and 13." })) {
+    if (event.type === "response") console.log("final:", event.text);
+  }
+} finally {
+  await counterMcp.close();
+}
+```
+
+## Output
+
+Prefer stdio for local servers, Streamable HTTP for remote ones. Point to the
+relevant reference file instead of pasting its contents into chat.

package/dist/skills/anvia-mcp/references/clients.md

@@ -0,0 +1,73 @@
+# MCP Clients
+
+`@anvia/mcp` owns connections, transports, tool discovery, and cleanup (official
+MCP TypeScript SDK v2 client under the hood). `@anvia/core` keeps only the
+registration contracts the `Agent` consumes. Construction performs no I/O.
+
+## Transports
+
+```ts
+import { McpClient, McpClientGroup } from "@anvia/mcp";
+
+// Local subprocess.
+const filesystem = new McpClient({
+  name: "filesystem",
+  versionNegotiation: { mode: "auto" },
+  transport: {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"],
+  },
+});
+
+// Remote server.
+const github = new McpClient({
+  name: "github",
+  transport: {
+    type: "streamableHttp",
+    url: "https://mcp.example.com/mcp",
+    headers: { authorization: `Bearer ${process.env.MCP_TOKEN}` },
+  },
+  tools: { prefix: "github_" },
+});
+```
+
+- Every client needs a unique `name` — it identifies the server in logs,
+  errors, and the Studio MCP inspector.
+- `tools.prefix` namespaces remote tools (`github_...`) so two servers never
+  collide. Set it whenever more than one server is connected.
+- Read tokens from the environment at the boundary; never commit them.
+- Remote servers that need real OAuth take `authProvider` (an
+  `OAuthClientProvider`) instead of — not alongside — a `headers.authorization`
+  value; the client rejects the combination. `reconnectionOptions` tunes
+  reconnect behavior and `sessionId` resumes a known streamable-HTTP session.
+- Adapters not covered above: pass `transport: { type: "custom", ... }` with
+  your own MCP `Transport` implementation; URL safety and discovery behavior
+  are unchanged.
+
+## Connect and wire
+
+```ts
+const mcp = await McpClientGroup.connect({ clients: [filesystem, github] });
+const agent = new Agent({ id: "assistant", model, mcpServers: mcp.servers });
+
+try {
+  await agent.generate({ prompt: "Find the issue and update it." });
+} finally {
+  await mcp.close();
+}
+```
+
+- `connect()` discovers every tool page once and returns a frozen registration
+  snapshot. A single client also exposes `connect()` returning one server.
+- The Agent only sees `mcpServers`. MCP tools must never be passed via
+  `Agent.skills` — the Agent rejects them there.
+- Always `close()` clients (try/finally). To adopt changed remote tools,
+  reconnect and rebuild the Agent — snapshots do not refresh in place.
+
+## Version negotiation
+
+By default `@anvia/mcp` requires the modern MCP `2026-07-28` protocol and fails
+clearly otherwise. For older servers set `versionNegotiation: { mode: "auto" }`
+(probe modern, fall back to the legacy handshake) or `{ mode: "legacy" }` for a
+known 2025-era server. Prefer `auto` over `legacy` unless the server is pinned.

package/dist/skills/anvia-mcp/references/safety.md

@@ -0,0 +1,25 @@
+# MCP Safety
+
+Streamable HTTP connections enforce Anvia URL safety by default:
+
+- No custom `fetch`. The transport owns its HTTP method, body, abort signal,
+  session, and protocol headers — arbitrary `RequestInit` fields are not exposed.
+- Static headers are explicit transport config. They are sent only to the exact
+  MCP endpoint, never attached to OAuth requests, and endpoint redirects fail
+  instead of forwarding credentials.
+- A static `authorization` header cannot be combined with `authProvider`.
+
+## Private networks
+
+For an intentionally local or private-network server, set
+`ssrfProtection: "disabled"` on that transport. This lifts hostname and DNS
+restrictions for the whole transport — redirects and OAuth discovery included —
+while still requiring HTTP(S). Use it only when the application owns and trusts
+that network boundary, and expect `check-mcp.sh` to flag it for review.
+
+## Instructions are metadata
+
+MCP server instructions remain inspectable metadata; they are not added to Agent
+instructions. If a server's behavior matters, write it into your own
+`instructions` or tool descriptions — never assume the agent has seen the
+server's text.

package/dist/skills/anvia-mcp/scripts/check-mcp.sh

@@ -0,0 +1,73 @@
+#!/bin/sh
+# Heuristic checks for Anvia MCP code in an app directory.
+# Usage: sh scripts/check-mcp.sh [--dir <app-root>]
+# Fails with a list of violations; passes silently with "mcp OK".
+
+DIR="."
+if [ "$1" = "--dir" ] && [ -n "$2" ]; then
+  DIR="$2"
+fi
+
+ROOTS_FOUND=0
+for root in "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server"; do
+  if [ -d "$root" ]; then
+    ROOTS_FOUND=1
+    break
+  fi
+done
+if [ "$ROOTS_FOUND" -eq 0 ]; then
+  echo "ERROR: no src/app/lib/server directory under '$DIR' — nothing was checked."
+  echo "Run from the app root or pass --dir <app-root>."
+  exit 1
+fi
+
+fail=0
+violation() {
+  echo "VIOLATION: $1"
+  fail=1
+}
+warning() {
+  echo "WARNING: $1"
+}
+
+FILES=$(grep -rln --include='*.ts' \
+  -e 'new McpClient(' -e 'McpClientGroup' -e 'mcpServers' \
+  "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" 2>/dev/null | sort -u)
+
+if [ -z "$FILES" ]; then
+  echo "mcp OK (no MCP code found)"
+  exit 0
+fi
+
+# 1. Every client needs a unique name.
+if echo "$FILES" | xargs grep -l 'new McpClient(' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A5 'new McpClient(' 2>/dev/null | grep -q 'name:' || {
+    violation "new McpClient without name (see references/clients.md)."
+  }
+fi
+
+# 2. Remote transports need an explicit URL.
+if echo "$FILES" | xargs grep -l 'streamableHttp' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A6 'streamableHttp' 2>/dev/null | grep -q 'url:' || {
+    violation "streamableHttp transport without url (see references/clients.md)."
+  }
+fi
+
+# 3. Disabled SSRF protection must be intentional (warning only).
+if echo "$FILES" | xargs grep -l 'ssrfProtection.*disabled' 2>/dev/null | grep -q .; then
+  warning "ssrfProtection disabled — confirm the app owns that network boundary (see references/safety.md)."
+fi
+
+# 4. Connected clients should be closed (warning only).
+if echo "$FILES" | xargs grep -l -e '\.connect(' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -e '\.close(' 2>/dev/null | grep -q '.close(' || {
+    warning "MCP connect without close — leak risk, use try/finally (see references/clients.md)."
+  }
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "mcp OK"
+  exit 0
+fi
+echo "See skills/anvia-mcp/references/ for fixes."
+exit 1

package/dist/skills/anvia-pipeline/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: anvia-pipeline
+description: Build deterministic multi-step work with Anvia Pipelines — steps, composition, parallel branches, batch runs, agent and extractor stages.
+---
+
+# Anvia Pipeline Skill
+
+Use this skill when the work is a fixed sequence of steps, not a model-driven
+loop: transforms, parsing, scoring, fan-out/fan-in, batch runs, or pipelines
+with one bounded agent or extractor stage inside.
+
+## Pipeline vs agent
+
+- Reach for `Pipeline` when you can name the steps upfront. Reach for `Agent`
+  (see the `anvia-agent` skill) when the model must decide what to do next.
+- The common failure is an agent with rising `maxTurns` doing a fixed sequence
+  — rewrite that as a pipeline with one `.agent()` stage instead.
+
+## Process
+
+1. Model the flow as stages (`references/steps-compose.md`) — step, compose,
+   parallel, batch.
+2. Add model stages only where judgment is needed (`references/agents-extract.md`).
+3. Run `scripts/check-pipeline.sh` from the app root before claiming done.
+
+## Minimal slice
+
+```ts
+import { Pipeline } from "@anvia/core/pipeline";
+import { z } from "zod";
+
+const normalizeIncident = new Pipeline({ id: "normalize-incident", inputSchema: z.string() })
+  .step({ id: "trim", run: ({ input }) => input.trim() })
+  .step({ id: "collapse-whitespace", run: ({ input }) => input.replace(/\s+/g, " ") })
+  .step({
+    id: "summarize",
+    run: ({ input }) => ({
+      normalized: input,
+      wordCount: input.split(" ").length,
+      priority: input.toLowerCase().includes("outage") ? "high" : "normal",
+    }),
+  });
+
+const result = await normalizeIncident.run({ input: "  Checkout outage reported.  " });
+console.log(result.output);
+```
+
+## Output
+
+Keep stages small, named, and typed — each stage's output is the next stage's
+input. Point to the relevant reference file instead of pasting its contents
+into chat.

package/dist/skills/anvia-pipeline/references/agents-extract.md

@@ -0,0 +1,62 @@
+# Agent and Extractor Stages
+
+## Agent stages
+
+Embed one bounded agent where a step needs judgment. The stage maps pipeline
+input to an agent request explicitly, and `suspension` is required:
+
+```ts
+const executiveUpdate = new Pipeline({ id: "executive-update", inputSchema: z.array(z.string()) })
+  .step({
+    id: "format-notes",
+    run: ({ input }) => input.map((note) => `- ${note}`).join("\n"),
+  })
+  .agent({
+    id: "analyze",
+    agent: analyst,
+    suspension: "reject",
+    request: ({ input }) => ({
+      prompt: `Prepare an executive update from these notes:\n\n${input}`,
+    }),
+  });
+```
+
+- Keep the agent's instructions narrow (one task, facts-only, visible final
+  text) — the pipeline already handles orchestration, so the agent must not
+  coordinate.
+- Prefer approval-free agents inside pipelines. A tool approval inside an agent
+  stage suspends the run (`PipelineAgentSuspensionError`); if you need
+  approvals, surface them at the pipeline boundary instead of burying them
+  mid-flow.
+
+## Extractor stages
+
+Extractor stages turn unstructured text into schema-validated objects. Reach
+for them when a step's job is "pull fields out of this text" rather than
+open-ended judgment; the schema is the contract downstream steps program
+against:
+
+```ts
+const ticketed = pipeline.extract({
+  id: "extract-ticket",
+  text: ({ input }) => input.body,
+  model,
+  outputSchema: z.object({ title: z.string(), priority: z.enum(["low", "high"]) }),
+  instructions: "Extract the support ticket fields.",
+});
+```
+
+`text` maps the previous stage's output to the source text; `model`,
+`instructions`, `retries`, `temperature`, `maxTokens`, and `providerOptions`
+behave like the single extraction call. The cookbook's extractor-pipeline
+example shows a full flow.
+
+## Observing runs
+
+`run` / `runBatch` accept an `observer` (`stage_started` / `stage_completed` /
+`stage_failed`), plus `abortSignal`, `metadata`, `runId`, and
+`failOnObserverError`; `graph()` prints the stage graph. Pipelines also carry
+`observability` options from construction, and Studio replays run history stage
+by stage (see the `anvia-studio` skill). When a pipeline misbehaves, replay the
+failing run in Studio before changing stages — most pipeline bugs are wrong
+intermediate outputs, visible at the stage boundary.

package/dist/skills/anvia-pipeline/references/steps-compose.md

@@ -0,0 +1,63 @@
+# Steps and Composition
+
+Pipelines come from `@anvia/core/pipeline`. The constructor takes an `id` and a
+zod `inputSchema` — inputs are parsed at the boundary, and a non-zod schema
+throws. Every stage takes an `id`:
+
+```ts
+const ticketSummary = new Pipeline({ id: "ticket-summary", inputSchema: z.string() })
+  .compose({ id: "parse", pipeline: parseTicket })
+  .compose({ id: "score", pipeline: scoreTicket });
+
+const { output: summary } = await ticketSummary.run({ input: rawTicket });
+```
+
+## Stage kinds
+
+- `.step({ id, run })` — a pure function of `{ input }`. `run` may be async.
+  Prefer many small named steps over one big closure.
+- `.compose({ id, pipeline })` — nest a whole pipeline as a stage. Build
+  parse/score/format sub-pipelines independently, then compose them.
+- `.parallel({ id, branches })` — fan out over named sub-pipelines, then merge:
+
+```ts
+const triage = new Pipeline({ id: "triage", inputSchema: z.string() })
+  .parallel({
+    id: "signals",
+    branches: { classification: classifyText, signals: extractSignals, priority: estimatePriority },
+  })
+  .step({
+    id: "merge",
+    run: ({ input: { classification, signals, priority } }) => ({
+      ...classification,
+      ...signals,
+      ...priority,
+    }),
+  });
+```
+
+Branch outputs arrive keyed by branch name — destructure them in the merge step.
+Keep branches independent; a branch that needs another branch's output belongs
+downstream, not in the same fan-out.
+
+## Batch runs
+
+```ts
+const batch = await normalizeIncident.runBatch({
+  inputs: ["Payment latency for EU customers.", "Search outage for the admin dashboard."],
+  concurrency: 2,
+});
+```
+
+`runBatch` maps the same pipeline over inputs with bounded concurrency. Use it
+instead of hand-rolled `Promise.all` loops — backpressure and error
+aggregation come free.
+
+## Rules
+
+- Every pipeline and stage needs an `id`. Ids show up in traces, logs, and
+  Studio replay — `step-1`, `step-2` waste that surface.
+- Type the seams: `inputSchema` on the pipeline, object outputs from steps. An
+  untyped middle step turns every downstream stage into guesswork.
+- Deterministic stages first, model stages last and few (see
+  `references/agents-extract.md`).

package/dist/skills/anvia-pipeline/scripts/check-pipeline.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+# Heuristic checks for Anvia Pipeline code in an app directory.
+# Usage: sh scripts/check-pipeline.sh [--dir <app-root>]
+# Fails with a list of violations; passes silently with "pipeline OK".
+
+DIR="."
+if [ "$1" = "--dir" ] && [ -n "$2" ]; then
+  DIR="$2"
+fi
+
+ROOTS_FOUND=0
+for root in "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server"; do
+  if [ -d "$root" ]; then
+    ROOTS_FOUND=1
+    break
+  fi
+done
+if [ "$ROOTS_FOUND" -eq 0 ]; then
+  echo "ERROR: no src/app/lib/server directory under '$DIR' — nothing was checked."
+  echo "Run from the app root or pass --dir <app-root>."
+  exit 1
+fi
+
+fail=0
+violation() {
+  echo "VIOLATION: $1"
+  fail=1
+}
+warning() {
+  echo "WARNING: $1"
+}
+
+FILES=$(grep -rln --include='*.ts' \
+  -e 'new Pipeline(' \
+  "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" 2>/dev/null | sort -u)
+
+if [ -z "$FILES" ]; then
+  echo "pipeline OK (no Pipeline code found)"
+  exit 0
+fi
+
+# 1. Pipelines need an id and a zod inputSchema (constructor throws without a schema).
+if echo "$FILES" | xargs grep -h -A4 'new Pipeline(' 2>/dev/null | grep -q 'new Pipeline('; then
+  echo "$FILES" | xargs grep -h -A4 'new Pipeline(' 2>/dev/null | grep -q 'id:' || {
+    violation "new Pipeline without id (see references/steps-compose.md)."
+  }
+  echo "$FILES" | xargs grep -h -A4 'new Pipeline(' 2>/dev/null | grep -q 'inputSchema' || {
+    violation "new Pipeline without inputSchema (see references/steps-compose.md)."
+  }
+fi
+
+# 2. Agent stages require an explicit suspension policy.
+if echo "$FILES" | xargs grep -l '\.agent(' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A6 '\.agent(' 2>/dev/null | grep -q 'suspension' || {
+    violation "pipeline .agent stage without suspension (see references/agents-extract.md)."
+  }
+fi
+
+# 3. A pipeline with no stages runs nothing (warning only).
+if echo "$FILES" | xargs grep -L -e '\.step(' -e '\.compose(' -e '\.agent(' -e '\.parallel(' -e '\.extract(' 2>/dev/null | grep -q .; then
+  warning "Pipeline file defines no stages — check for an unfinished pipeline (see references/steps-compose.md)."
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "pipeline OK"
+  exit 0
+fi
+echo "See skills/anvia-pipeline/references/ for fixes."
+exit 1

package/dist/skills/anvia-rag/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: anvia-rag
+description: Build retrieval and RAG with Anvia — chunking, embeddings, vector stores, knowledge graphs, filters, and search tools.
+---
+
+# Anvia RAG Skill
+
+Use this skill when the user wants retrieval over their own data: chunking
+documents, embedding them, picking a vector store, filtering results, or
+exposing retrieval to an agent as a search tool.
+
+## Process
+
+1. Chunk and embed the corpus (`references/pipeline.md`).
+2. Pick the store (`references/stores.md`) — `InMemoryVectorStore` first, a
+   client store when data must persist. For connection questions, add a graph
+   (`references/graph-rag.md`).
+3. Expose retrieval to the agent (`references/rag-tool.md`, `references/graph-rag.md`) — search tool or
+   `VectorContext`, not raw vectors in the prompt.
+4. Run `scripts/check-rag.sh` from the app root before claiming done.
+
+## Minimal slice
+
+```ts
+import { embedDocuments } from "@anvia/core/embeddings";
+import { InMemoryVectorStore, retrieveDocuments } from "@anvia/core/vector-store";
+import { loadTransformersEmbeddingModel } from "@anvia/transformers";
+
+const embeddingModel = await loadTransformersEmbeddingModel({ modelId: "Xenova/all-MiniLM-L6-v2" });
+const { documents: embedded } = await embedDocuments({
+  model: embeddingModel,
+  documents: notes,
+  id: (note) => note.id,
+  content: (note) => `${note.title}\n${note.body}`,
+  metadata: (note) => ({ topic: note.topic }),
+});
+
+const store = InMemoryVectorStore.fromDocuments({ documents: embedded });
+const results = await retrieveDocuments({
+  store,
+  model: embeddingModel,
+  query: "market risk",
+  topK: 1,
+});
+```
+
+## Output
+
+Keep the pipeline explicit: load → chunk → embed → upsert → retrieve. Point to
+the relevant reference file instead of pasting its contents into chat.