@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/ai.md

@@ -46,9 +46,11 @@ The implementation is the [Vercel AI SDK](https://sdk.vercel.ai) wrapped behind
 - [Providers](/docs/ai/providers) — Anthropic, OpenAI, the Vercel AI Gateway, mock; per-config keys (BYOK), switching at runtime, model-wrapping middleware
 - [Agents](/docs/ai/agents) — `*.agent.tsx` shape, system prompts, tool wiring
 - [Tools](/docs/ai/tools) — `*.tool.tsx` shape, validation, side effects
+- [MCP clients](/docs/ai/mcp-clients) — mount an EXTERNAL MCP server's tools, through the same allow/deny policy, with the untrusted server bounded
 - [Streaming](/docs/ai/streaming) — tokens-over-WebSocket, client hooks, backpressure
 - [RAG](/docs/ai/rag) — pgvector, embedding mixin, hybrid search
 - [Cost tracking](/docs/ai/cost-tracking) — the token `usage` returned on every call
+- [Prompt versioning](/docs/ai/prompt-versioning) — `definePrompt`, a content digest as the version, and which prompt version produced (and cost) a given run
 
 ## Why one surface
 
@@ -982,10 +984,12 @@ authorization path), by construction.
 // Opt a descriptor in (a description is REQUIRED — the model needs it):
 export const listOrders = defineQuery({
   name: 'orders.list', input: ListInput, output: Schema.Array(Order), source: 'orders',
+  guards: [{ scope: 'orders:read' }],     // the tool inherits exactly this check
   exposeAsTool: { description: "List the current tenant's orders." },
 })
 export const createOrder = defineMutation({
   name: 'orders.create', input: CreateInput, output: Order, target: { table: 'orders', op: 'insert' },
+  guards: [{ scope: 'orders:write' }],
   exposeAsTool: { description: 'Create an order.', confirm: true },   // writes confirm by default
 })
 ```
@@ -999,6 +1003,14 @@ const tools = appTools(entries, { allow: ['orders.*'], includeWrites: true })
 const { object } = yield* generateObjectWithTools({ prompt, tools, schema: Result })
 ```
 
+**The guards are load-bearing, not incidental.** "The agent can do nothing the
+subject couldn't" is a claim about the descriptor's own access decision — the
+synthesized tool runs the real handler under the calling subject and re-checks
+the same `guards:`. Exposing a procedure whose decision is `openAccess:` gives
+the model an unchecked endpoint, which is the right call for a public price
+lookup and the wrong one for anything reading rows. (A descriptor with *no*
+decision cannot reach this page: the app would not have booted.)
+
 Safety defaults (don't override blindly): **reads are included, writes are
 opt-in** (`includeWrites: true`) and **confirm by default**. Put destructive
 tags on `deny`. `exposeAsTool: true` alone does NOT expose — a tool with no
@@ -1006,6 +1018,60 @@ description is unusable; always use the object form. The annotations also
 surface in the capability manifest, so a coding agent discovers what's
 tool-exposable.
 
+### `confirm` is enforced, not reported
+
+A `confirm` tool is admitted only when its descriptor also declares
+[`requiresApproval`](/docs/data/approvals). Otherwise it is REFUSED — with the
+fix in the reason — because the alternative is to mount it and hope the caller
+asks, and the caller is a model.
+
+```ts
+export const refundOrder = defineMutation({
+  name: 'orders.refund',
+  // …
+  guards: [{ scope: 'orders:refund' }],
+  exposeAsTool: { description: 'Refund an order.' },      // confirm: true by default
+  requiresApproval: { approvers: [{ scope: 'orders:approve' }] },
+})
+```
+
+With that pair, the agent's call parks in your app's own approval queue and comes
+back as a typed `ApprovalRequired` carrying an id; a human decides in your UI;
+the identical call then succeeds exactly once. The human step is enforced by the
+handler, so nothing depends on the agent harness honouring a flag.
+
+The inventory reports both `confirm` and `approvalBacked`, because "why is this
+tool not executable" is answered only by the pair. For an **external** MCP
+server's tools `approvalBacked` is always false: their handler is behind an HTTP
+boundary we do not own, so there is no point at which we could hold the call —
+the human decision for an external write is the declaration-time one (`allow` is
+required, `includeWrites` is opt-in).
+
+### The same toolset, to an EXTERNAL agent
+
+`appTools` is the in-process form: your own agent loop, in your own handler. The
+same descriptors — through the same admission decision (`appToolDecision`, which
+`appTools` itself filters on) — can also be handed to an external MCP peer, so
+Claude Code or Cursor calls your procedures directly:
+
+```ts
+// app.config.ts
+export default {
+  agents: {
+    tools: { allow: ['orders.*'], includeWrites: true },  // the SAME AppToolPolicy
+    mcp: true,                                            // off by default
+  },
+}
+```
+
+Five gates stand in front of it, the app credential the agent acts as is a
+separate header from the operator's inspect token, and an **unbacked** `confirm`
+tool is not mounted there at all (there is no human in that process). A
+`requiresApproval`-backed one IS mounted: the human is not in the transport, they
+are in your approval queue, so nothing there has to trust the client.
+The full list, and what it does not defend against, is on the
+[MCP server](/docs/cli/mcp) page.
+
 The end-user-facing counterpart is **`<AppAgent>`** (from `@voltro/web`) — a
 "do it for me" chat whose ceiling is the logged-in subject's own permissions.
 See [Schema-driven UI → Reactive components](/docs/ui/reactive-components).
@@ -1019,6 +1085,127 @@ See [Schema-driven UI → Reactive components](/docs/ui/reactive-components).
 
 
 
+---
+
+<!-- source: en/ai/mcp-clients.md -->
+## MCP clients
+
+_Mount an external MCP server's tools onto a Voltro agent — through the same allow/deny policy your own `exposeAsTool` descriptors go through, with the untrusted server bounded._
+
+`@voltro/mcp` points **outward**: it exposes your app to a coding agent as an MCP server. `mcpToolset` points **inward** — it connects to somebody else's MCP server (GitHub, Slack, Sentry, a Postgres bridge) and mounts its tools onto a Voltro agent.
+
+The two halves speak the same protocol; only the direction differs.
+
+## Mounting a server
+
+```ts
+import { generateObjectWithTools, httpMcpTransport, mcpToolset } from '@voltro/ai'
+
+const github = yield* mcpToolset(
+  {
+    namespace: 'github',
+    transport: httpMcpTransport({
+      server: 'github',
+      url: process.env.GITHUB_MCP_URL!,
+      headers: { authorization: `Bearer ${process.env.GITHUB_MCP_TOKEN!}` },
+    }),
+  },
+  {
+    allow:    ['github.search_*', 'github.get_*'],
+    readOnly: ['github.search_*', 'github.get_*'],
+  },
+)
+
+const { object } = yield* generateObjectWithTools({
+  prompt,
+  tools:  github.tools,
+  schema: Result,
+})
+```
+
+`github.tools` is a `Record<string, AnyTool>` keyed by the namespaced tag (`github.get_issue`) — the same shape [`appTools`](/docs/ai/tools) produces, so one agent can mix its own tools and an external server's.
+
+For a locally spawned server, use the stdio transport instead:
+
+```ts
+import { stdioMcpTransport } from '@voltro/ai'
+
+const files = yield* mcpToolset(
+  {
+    namespace: 'files',
+    transport: stdioMcpTransport({
+      server:  'files',
+      command: 'npx',
+      args:    ['-y', 'some-mcp-server'],
+      // The child does NOT inherit your process environment. Pass only what it needs.
+      env:     { HOME: process.env.HOME! },
+    }),
+  },
+  { allow: ['files.read_*'], readOnly: ['files.read_*'] },
+)
+```
+
+Credentials always come from your environment or config. The framework ships no default token for any server.
+
+## The policy is the ceiling
+
+An `exposeAsTool` descriptor executes **your** handler under **the caller's** subject, so an agent's ceiling is that subject's permissions by construction. An external MCP server has no such property — it runs elsewhere, with whatever credentials you gave it. So for external tools the policy *is* the ceiling, and it is deliberately stricter:
+
+| | App tools (`appTools`) | External tools (`mcpToolset`) |
+|---|---|---|
+| Default exposure | Only descriptors annotated `exposeAsTool` | **None** — `allow` is required |
+| Allow / deny | `passesPolicy`, deny beats allow | The same function, same globs |
+| Read vs write | The descriptor's `kind` | **The app's `readOnly` list**, not the server's hint |
+| Writes | `includeWrites: true` | `includeWrites: true` |
+| Confirm | On for writes by default | On for writes by default |
+
+Three consequences worth stating outright:
+
+- **Omitting `allow` is refused, not defaulted.** A descriptor got a per-tool decision when somebody wrote `exposeAsTool` on it. Nobody in your repository wrote anything about a server's 94 tools, so naming what you allow is that decision.
+- **A server's `readOnlyHint` does not classify a tool.** The server is the untrusted party and can change the hint between two `tools/list` calls, so believing it would be a way to talk past `includeWrites: false`. Set `trustToolHints: true` if you want to delegate that judgement — explicitly, in one place a reviewer can find.
+- **The gate runs again inside every tool body**, so a tool spliced into the record after mount still cannot reach the server.
+
+`toolset.specs` is a `SynthesizedTool[]` — the same inventory type app tools produce — so one confirm-UI covers both kinds. `toolset.dropped` lists everything the server advertised that did not mount, and why.
+
+## Bounding an untrusted server
+
+A server's tool names, descriptions, schemas and results all reach your model's context. Every one of them is bounded, and every bound is an option with a default and an environment override:
+
+| Bound | Default | Env |
+|---|---|---|
+| `maxTools` | 64 | `VOLTRO_MCP_MAX_TOOLS` |
+| `maxDescriptionChars` | 1024 | `VOLTRO_MCP_MAX_DESCRIPTION_CHARS` |
+| `maxSchemaBytes` | 32 KiB | `VOLTRO_MCP_MAX_SCHEMA_BYTES` |
+| `maxResultBytes` | 256 KiB | `VOLTRO_MCP_MAX_RESULT_BYTES` |
+| `maxResponseBytes` | 4 MiB | `VOLTRO_MCP_MAX_RESPONSE_BYTES` |
+| `requestTimeoutMs` | 30 000 | `VOLTRO_MCP_TIMEOUT_MS` |
+
+```ts
+yield* mcpToolset(server, {
+  allow: ['github.get_*'],
+  bounds: { maxTools: 12, maxResultBytes: 32 * 1024 },
+})
+```
+
+Alongside the numbers:
+
+- **Tool names must be `[A-Za-z0-9_-]`.** Anything else is dropped rather than sanitized — a truncated name would not be the name you allowed.
+- **Descriptions and schemas are stripped of invisible characters** (zero-width spaces, bidi overrides, the Unicode tags block) before they reach the model. Those are how an injection hides from the human reviewing the same string.
+- **Every description carries a provenance prefix** telling the model the text is third-party, not an instruction from your app.
+- **Non-text results are described, not inlined** — a 6 MB base64 image does not buy a context window.
+- **The tool set is snapshotted at mount.** Nothing re-reads `tools/list` on its own; a server that renames or re-describes its tools between calls changes nothing until you call `refreshMcpToolset`.
+
+## What this does not defend against
+
+Stated plainly, because a bound you assume is worse than one you know you lack:
+
+- **Instructions inside a description or a result.** They are bounded, sanitized and labelled, but a model may still choose to obey them. What actually contains the damage is the allowlist above: an injected "now call `admin_delete_all`" reaches a tool that was never mounted.
+- **A server that lies about a tool's effect**, or does something destructive inside a tool you allowed. The ceiling there is the credentials you gave the server — scope them.
+- **Argument exfiltration.** The allowlist bounds *which* tools run, not what the model puts in their arguments. A mounted external tool is a channel out of your process; do not mount one alongside tools that read secrets and expect the two not to meet.
+- **The transport target.** `url` / `command` are treated as app configuration. There is no SSRF guard or binary allowlist, because a legitimate deployment mounts an MCP server on a private address. If either can be influenced by user or model input in your app, gate it there.
+
+
+
 ---
 
 <!-- source: en/ai/streaming.md -->
@@ -1046,6 +1233,10 @@ import { Schema } from 'effect'
 
 export const supportRun = defineStream({
   name:    'support.run',
+  // Every call spends provider tokens, so this is metered work — guard it
+  // rather than declaring it open, and rate-limit it before it faces the
+  // internet (`@voltro/plugin-ratelimit`).
+  guards:  [{ scope: 'support:chat' }],
   input:   Schema.Struct({ message: Schema.String }),
   element: AgentEvent,
 })
@@ -1877,6 +2068,78 @@ Nothing about this needs a third party to operate an inference tier. It needs so
 
 The Flow tab shows the queue: what is waiting and for how long, which calls have been waiting more than two minutes, which claims have a lease their dispatcher will never release, and the dispatcher's own last tick. A run parked on an offloaded call reads `suspended` in the run list with no step row yet, so this is the only view of the wait while it is happening.
 
+## Budget SUSPEND — stop spending without destroying the run
+
+`requireAiBudget` above fails ONE call. That does stop the spend, and it does it
+by killing a durable run that may be nine steps in — the work is lost, and lost
+again on every retry until somebody raises the limit. A ceiling whose only
+expression is destruction gets set high, or turned off. `defineCostBudget` sits
+at the other extreme: it is an observability-grade signal over work that already
+happened, and never blocks anything.
+
+The third answer is the one the workflow engine already knows how to do for a
+human: **suspend**. `aiStep` / `aiObjectStep` take a `budget`:
+
+```ts
+import { aiStep } from '@voltro/ai/workflow'
+
+const summary = yield* aiStep({
+  name: 'summarise-thread',
+  prompt: `Summarise:\n${thread}`,
+  store: ctx.store,
+  tenantId,
+  budget: {
+    limitUsd:    50,
+    estimateUsd: 0.25,
+    onExceeded:  'suspend',
+  },
+})
+```
+
+Over the cap, the run parks on a durable `_voltro_budget_holds` row, frees its
+worker, and resumes when the budget has headroom — then continues from where it
+stopped. Nothing is spent while it is held, and nothing is lost.
+
+**The ordering is the feature.** The gate reads the *reservation counter* before
+the journaled step and before an offloaded call is enqueued — not a sum over
+`_voltro_ai_usage`, which by definition only knows about money already gone. On
+the suspend path no provider is contacted and no queue row exists for a
+dispatcher to pick up. Under the cap, `estimateUsd` is RESERVED atomically before
+the call, which is the difference between a ceiling and a speed bump.
+
+**A release wakes a run; it does not authorise a spend.** Every wake re-reads the
+budget and parks again if it is still over, so an operator lifting the wrong
+hold — or a window rolling over for a tenant that immediately spends again —
+cannot spend through the ceiling. Three things can wake a hold:
+
+- its own durable recheck clock (15 minutes by default, `recheckEveryMs`), so a
+  tumbling window that rolls over on a clock nothing notifies us about is still
+  noticed;
+- `releaseBudgetHolds({ store, budget, tenantId? })`, called from your own code
+  — an admin mutation, or a subscriber on `defineCostBudget`'s `recovered`
+  signal. The framework does not subscribe for you: whether a compute budget
+  recovering should wake AI holds is an app decision, and the recheck clock
+  already guarantees the run is not stranded either way;
+- its total timeout (`holdTimeoutMs`, 7 days), after which the run fails having
+  spent nothing.
+
+`onExceeded: 'fail'` is the default, so an existing `budget` behaves exactly like
+`requireAiBudget`. A compute budget opts in the same way:
+
+```ts
+import { defineCostBudget } from '@voltro/runtime'
+
+export default defineCostBudget({
+  name:       'tenant-recompute-hourly',
+  unit:       'recompute',
+  limit:      100_000,
+  window:     '1h',
+  onExceeded: 'suspend',   // default 'observe' — signal only
+})
+```
+
+Held runs are visible via `pendingBudgetHolds(store)`.
+
 ## Deliberately your call
 
 The toolkit prices + records + gates; a few things stay explicit by design:
@@ -1896,6 +2159,110 @@ For quota tied to billing TIERS (not a raw USD cap), see
 
 
 
+---
+
+<!-- source: en/ai/prompt-versioning.md -->
+## Prompt versioning
+
+_`definePrompt` makes a prompt an identified, versioned artefact — and stamps that identity onto the step row, the spend ledger and a `_voltro_prompts` table, so "which prompt produced this run" is a lookup._
+
+Your schema is versioned. Your rows carry provenance. Your prompts — the part of an AI feature that changes weekly and is edited by whoever is nearest — were code with no identity at all.
+
+`definePrompt` closes that asymmetry. It reuses the digest `aiStep` already recorded on step rows rather than inventing a second identity scheme.
+
+## Declaring a prompt
+
+```ts
+import { definePrompt } from '@voltro/ai'
+
+export const triage = definePrompt({
+  id:       'support.triage',
+  system:   'You triage support tickets. Answer only with the category.',
+  template: 'Ticket:\n{{body}}\n\nCategories: {{categories}}',
+  label:    'v3-shorter-system',
+})
+```
+
+- **`id`** is the stable identity across revisions, dotted like a descriptor tag.
+- **`template`** is a string with `{{name}}` placeholders — not a function. A function has no stable content to hash, so a function-built prompt could only be versioned by hashing its *output*, which would make every distinct customer message a new "version".
+- **`digest`** is computed from the template + system at definition time. It is the version, and it exists before any database does — a test, an eval, or a CLI can identify a prompt version with no connection.
+- **`label`** is metadata and deliberately **not** part of the digest, so renaming a revision does not fork it.
+
+Render it to get the text plus a stamp:
+
+```ts
+const rendered = yield* triage.render({ body: ticket.body, categories: 'hardware, software, billing' })
+// { promptId: 'support.triage', digest: 'sha256:…', prompt: 'Ticket:\n…', system: '…' }
+```
+
+A missing variable **fails** rather than sending the literal `{{body}}` to a model.
+
+## Provenance you get by using the primitive
+
+Pass the rendered prompt straight to `aiStep` — the string form still works, it just carries no stamp:
+
+```ts
+const result = yield* aiStep({
+  name:   'triage-ticket',
+  prompt: rendered,
+  store:  ctx.store,
+  offload: true,
+})
+```
+
+That one call now writes the same `promptId` + digest to three places:
+
+| Where | What it answers |
+|---|---|
+| `_voltro_workflow_run_steps.input` | Which prompt version produced **this run** |
+| `_voltro_ai_usage` | What each prompt version **cost** |
+| `_voltro_prompts` | What the template **was**, at that version |
+
+Nothing has to be remembered at call time, and offloaded calls are covered too — the stamp rides across the suspend on the queue row, so the dispatcher attributes the spend to the same version.
+
+`recordPrompt: 'none'` still records the provenance. That is deliberate: the reason to record nothing about a prompt is that its *text* is sensitive, and an id plus a content digest is neither the text nor derivable from it. Suppressing the identity along with the content would mean the most privacy-conscious setting is also the one where you cannot tell which prompt version ran.
+
+## Reading it back
+
+```ts
+import { aiSpendUsd, promptVersionByDigest, promptVersionsFor } from '@voltro/ai'
+
+// From a run's step row → the artefact.
+const version = yield* promptVersionByDigest(ctx.store, stepInput.promptVersion)
+version?.template   // the template, as it was
+
+// The history of one prompt, newest revision first.
+const history = yield* promptVersionsFor(ctx.store, 'support.triage')
+
+// Did revision 4 cost more than revision 3?
+const spend = yield* aiSpendUsd(ctx.store, { promptDigest: version.digest })
+```
+
+`recordPromptVersion` assigns the human-facing `revision` (1, 2, 3 …) on first sight of a `(promptId, digest)` pair and is idempotent afterwards. Under a two-replica race two different versions can land on the same revision **number** — accepted deliberately: the digest is the exact identity, the revision is a label for humans, and order by `firstSeenAt` when you need the true sequence.
+
+## Retention
+
+`_voltro_prompts` is bounded by the standard retention sweep on `lastUsedAt`, defaulting to **365 days** and tunable with `VOLTRO_AI_PROMPTS_TTL_HOURS`. The table is self-healing under it: a version that ages out is one nothing has run in a year, and the next run re-registers it.
+
+The registration is `framework`-precedence, so an app that registers its own window for the table wins without having to know the framework's exists.
+
+## The table
+
+```text
+_voltro_prompts
+  promptId       stable identity across revisions
+  digest         content digest of template + system — the version
+  revision       human-facing counter within a promptId
+  label          the author's name for this revision
+  template       the TEMPLATE (code) — never a rendered prompt (data)
+  system
+  firstSeenAt / lastUsedAt
+```
+
+Storing the template is safe precisely because it is code — it is in your repository already. The rendered prompt, which may contain a customer's message, is never written here.
+
+
+
 ---
 
 <!-- source: en/ai/data-copilot.md -->
@@ -1929,6 +2296,9 @@ import { Schema } from 'effect'
 
 export const ask = defineAction({
   name: 'copilot.ask',
+  // A model-proposed read, executed as the caller. The grammar bounds WHAT can
+  // be asked; this bounds WHO may ask.
+  guards: [{ scope: 'copilot:ask' }],
   input:  Schema.Struct({ question: Schema.String }),
   output: Schema.Union(
     Schema.Struct({ ok: Schema.Literal(true),  rows:   Schema.Array(Schema.Record({ key: Schema.String, value: Schema.Unknown })) }),