@voltro/ai 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -353,6 +353,10 @@ export declare interface AiServiceImpl {
 export declare const aiSpendUsd: (store: DataStore, opts?: {
     readonly tenantId?: string | null;
     readonly since?: Date;
+    /** Scope the sum to ONE prompt version. This is the "did revision 4 cost
+     *  more than revision 3" query, and it is the reason the digest is on the
+     *  ledger row rather than only on the step row. */
+    readonly promptDigest?: string;
 }) => Effect.Effect<number>;
 
 /** Token tally as returned by `generateText` / `generateObject` / `streamText`. */
@@ -376,6 +380,10 @@ export declare interface AiUsageRecordInput {
      *  models the static table prices at zero. Extract it from the AI-SDK result's
      *  `providerMetadata.gateway.cost` (see `gatewayCostUsd`). */
     readonly actualCostUsd?: number;
+    /** Which prompt VERSION produced this call — `definePrompt(...).render(...)`
+     *  returns one, and `aiStep` passes it through automatically. Stamped onto the
+     *  ledger row so spend can be attributed to a prompt revision. */
+    readonly prompt?: PromptStamp;
     /** Override the timestamp (tests; default `new Date()`). */
     readonly calledAt?: Date;
 }
@@ -406,6 +414,9 @@ export declare interface AnyTool {
     readonly name: string;
     readonly description: string;
     readonly input: Schema.Schema.Any;
+    /** See `ToolDef.inputJsonSchema` — a foreign parameter schema shown to the
+     *  model in place of a rendered `input`. */
+    readonly inputJsonSchema?: Record<string, unknown>;
     readonly output?: Schema.Schema.Any;
     readonly execute?: (input: never) => Effect.Effect<unknown, never, unknown>;
     readonly handler?: ToolHandler<never, unknown>;
@@ -442,6 +453,57 @@ export declare const appendStreamingMessage: (store: DataStore, input: {
  */
 export declare const applyMiddleware: (model: LanguageModelV4, middleware?: AiMiddleware | ReadonlyArray<AiMiddleware>) => LanguageModelV4;
 
+/**
+ * The EXECUTION admission for one descriptor, as data.
+ *
+ * Same shape and same ORDER as `mcpToolDecision` in `mcpTools.ts`, on purpose:
+ * an app tool and an external MCP tool are admitted by two functions that agree
+ * about what a decision is, so one confirm-UI, one inventory type and one
+ * refusal message cover both. The asymmetry between them is only in step 1 —
+ * an app descriptor carries an `exposeAsTool` act, so an absent allowlist is
+ * permissive here and refused there.
+ *
+ * It exists because a SECOND caller appeared. `appTools` used to inline the
+ * three filters, which was fine while it was the only executor; the moment a
+ * transport (the inspect agent-tool surface, reached over MCP) needed the same
+ * verdict, an inlined chain would have become a second policy path — and a
+ * second policy path is how a ceiling gets bypassed. So the verdict is a
+ * function, `appTools` calls it, and the transport calls the same one.
+ *
+ * Order, asserted in the tests:
+ *   1. `passesPolicy` (deny beats allow) on the descriptor NAME,
+ *   2. exposability — an `exposeAsTool` object WITH a description,
+ *   3. the writes gate — a mutation/action needs `includeWrites`,
+ *   4. the CONFIRM gate — `confirm` must be backed by `requiresApproval:`.
+ *
+ * ── Why step 4 exists (`confirm` was reported, not enforced) ─────────────────
+ *
+ * `confirm` shipped as metadata: `synthesizeToolSpecs` reported it, this
+ * function admitted the tool anyway, and the file said out loud that enforcement
+ * was "the agent loop / UI"'s job. That is the shape this repo keeps paying for
+ * — a control that reads as enforcement in every inventory and enforces nothing
+ * in any caller that forgets to look.
+ *
+ * There is now somewhere for it to MEAN something. A descriptor that declares
+ * `requiresApproval:` parks the call as a durable approval in the shared serve
+ * pipeline — the same gate a human's call goes through — so the second human is
+ * the app's own approval queue rather than a prompt in a harness we do not
+ * control. A confirm tool WITH that policy is therefore admitted: executing it
+ * cannot skip the human, because the handler behind it will not run without one.
+ *
+ * A confirm tool WITHOUT it is refused. The alternative is to mount it and hope
+ * the caller asks, and the caller is a model.
+ */
+export declare type AppToolDecision = {
+    readonly admitted: true;
+    readonly spec: SynthesizedTool;
+} | {
+    readonly admitted: false;
+    readonly reason: string;
+};
+
+export declare const appToolDecision: (descriptor: AppToolDescriptor, policy: AppToolPolicy) => AppToolDecision;
+
 /** The descriptor fields tool synthesis reads. */
 export declare interface AppToolDescriptor {
     readonly kind: 'query' | 'mutation' | 'action' | string;
@@ -449,6 +511,15 @@ export declare interface AppToolDescriptor {
     readonly input: Schema.Schema.Any;
     readonly output?: Schema.Schema.Any;
     readonly exposeAsTool?: ExposeAsToolLike;
+    /**
+     * Presence of the descriptor's `requiresApproval:` policy — read as a BOOLEAN
+     * here and nothing more, so `@voltro/ai` needs no `@voltro/protocol` shape for
+     * it (structural, like `exposeAsTool` above).
+     *
+     * It is what turns `confirm` from a report into an enforcement: see
+     * `appToolDecision`.
+     */
+    readonly requiresApproval?: unknown;
 }
 
 /** A descriptor paired with its ctx-bound executor (the real handler). */
@@ -475,9 +546,14 @@ export declare interface AppToolPolicy {
  * The EXECUTABLE toolset for the agent loop. Read tools are always included;
  * WRITE tools only when `policy.includeWrites` is true (writes are opt-in —
  * the safety default). Each tool's handler runs the descriptor's bound
- * `invoke` (the real handler under the caller's subject). Confirm is enforced
- * by the agent loop / UI using `synthesizeToolSpecs` — the pure executable
- * tool can't gate a human prompt.
+ * `invoke` (the real handler under the caller's subject).
+ *
+ * A `confirm` tool is admitted only when the descriptor is APPROVAL-BACKED
+ * (`requiresApproval:`), and then the human step is enforced by the real handler
+ * — the tool call returns the typed `ApprovalRequired` refusal, a human decides
+ * in the app, and the identical call succeeds once. This module still gates no
+ * human prompt of its own, and no longer needs to: it decides which tools can
+ * exist, and the pipeline decides whether the call runs.
  */
 export declare const appTools: (entries: ReadonlyArray<AppToolEntry>, policy?: AppToolPolicy) => ReadonlyArray<AnyTool>;
 
@@ -660,8 +736,9 @@ export declare interface DataCopilotDeps {
  *
  * The two tables (`streamEventsTable`, `streamStateTable`) register into the
  * app's migration set like the agent/usage tables — add them to the database
- * barrel (or they ride along with a `*.agent.tsx` app). Run `gcResumableStreams`
- * periodically to drop finished streams past a retention window.
+ * barrel (or they ride along with a `*.agent.tsx` app). Building this store
+ * BOUNDS them (see `registerStreamLogRetention`); `gcResumableStreams` remains
+ * for a tighter, done-aware collection an app can run on its own schedule.
  */
 export declare const dataStoreResumableStreamStore: (store: DataStore) => ResumableStreamStore;
 
@@ -697,6 +774,14 @@ export declare const DEFAULT_INFERENCE_LEASE_MS: number;
  *  top of it. */
 export declare const DEFAULT_INFERENCE_POLL_MS = 250;
 
+/** Default window on `_voltro_ai_inferences`: 30 days since COMPLETION.
+ *
+ *  Env `VOLTRO_AI_INFERENCES_TTL_HOURS`. Shorter than the usage ledger's year
+ *  because this table stores the PROMPT verbatim (the dispatcher has to, to
+ *  perform the call) — so it is the one AI table where "keep it forever by
+ *  default" is a data-protection decision as well as a size one. */
+export declare const DEFAULT_INFERENCE_RETENTION_HOURS: number;
+
 declare const DEFAULT_INPUT: Schema.Struct<{
     prompt: typeof Schema.String;
 }>;
@@ -704,6 +789,21 @@ declare const DEFAULT_INPUT: Schema.Struct<{
 /** The default judge threshold when a judge is configured without one. */
 export declare const DEFAULT_JUDGE_THRESHOLD = 0.7;
 
+/** Default window on `_voltro_prompts`: a year since last use. Long, because a
+ *  registry row is tiny and its value is answering a question about a run you
+ *  are only now investigating. Env `VOLTRO_AI_PROMPTS_TTL_HOURS`. */
+export declare const DEFAULT_PROMPT_RETENTION_HOURS: number;
+
+/** Default window on the resumable-stream log: 7 days since the row was
+ *  written. Env `VOLTRO_STREAM_LOG_TTL_HOURS`.
+ *
+ *  It is measured in DAYS against a thing whose useful life is MINUTES on
+ *  purpose. A resumable stream exists so a browser that lost its socket can
+ *  reconnect and replay; nothing reads a week-old log. The width is there so the
+ *  bound can never be the reason a reconnect came back short, which makes it a
+ *  bound on the DISK rather than a decision about the feature. */
+export declare const DEFAULT_STREAM_LOG_RETENTION_HOURS: number;
+
 /** Default input schema type when `input` is omitted (`{ prompt: string }`). */
 export declare type DefaultAgentInputSchema = typeof DEFAULT_INPUT;
 
@@ -754,6 +854,17 @@ export declare const defineAgent: <S extends Schema.Schema.Any = DefaultAgentInp
  */
 export declare const defineAgentExecutor: <S extends Schema.Schema.Any = DefaultAgentInputSchema>(descriptor: AgentDescriptor<S>, config: AgentExecutorConfig<AgentInput<S>>) => AgentExecutor<S>;
 
+export declare interface DefinedPrompt extends PromptDefinition {
+    /** Content digest of `template` + `system`. The version. */
+    readonly digest: string;
+    /** Placeholder names found in the template, in first-appearance order. */
+    readonly variables: ReadonlyArray<string>;
+    /** Substitute the variables. Fails when one is missing — a `{{ticket}}` left
+     *  unsubstituted is a prompt that quietly asks the model about the literal
+     *  string `{{ticket}}`, which is worse than an error. */
+    readonly render: (vars?: Record<string, string | number | boolean>) => Effect.Effect<RenderedPrompt, PromptRenderError>;
+}
+
 /**
  * Declare an eval suite. Validated at module load — an empty case list, a
  * duplicate case id, or a nonsensical threshold throws loudly so a broken eval
@@ -773,16 +884,46 @@ export declare interface DefineEvalInput {
     readonly tools?: ReadonlyArray<string>;
 }
 
+/**
+ * Declare a versioned prompt.
+ *
+ * ```ts
+ * 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',
+ * })
+ * ```
+ *
+ * The digest is computed here, from the file — so it exists before any database
+ * does, and a test, a CLI, or an eval can identify a prompt version without a
+ * connection. Registration (`recordPromptVersion`) only adds the human-facing
+ * revision number and the retrievable copy.
+ */
+export declare const definePrompt: (definition: PromptDefinition) => DefinedPrompt;
+
 export declare const defineTool: <A, I, O>(def: {
     readonly name: string;
     readonly description: string;
     readonly input: Schema.Schema<A, I>;
+    readonly inputJsonSchema?: Record<string, unknown>;
     readonly output?: Schema.Schema.Any;
     readonly execute?: (input: A) => Effect.Effect<O, never, unknown>;
     readonly handler?: ToolHandler<A, O>;
     readonly timeoutMs?: number;
 }) => AnyTool;
 
+/**
+ * Describe an external tool to the model.
+ *
+ * The provenance prefix is short on purpose — it is paid per tool, per turn —
+ * but it is not decoration. A model that has been told which text is
+ * third-party has something to weigh an instruction in that text against; a
+ * model handed the same sentence with no attribution has nothing.
+ */
+export declare const describeExternalTool: (namespace: string, tool: McpToolInfo) => string;
+
 /**
  * One dispatch tick. Never throws.
  *
@@ -961,6 +1102,15 @@ export declare type ExposeAsToolLike = boolean | {
 
 export { extractReasoningMiddleware }
 
+/**
+ * Flatten an MCP `content` array into the string the model sees, bounded.
+ *
+ * Non-text content is DESCRIBED, not inlined: a server returning a 6 MB base64
+ * image would otherwise spend a context window (and a lot of money) on
+ * something the text channel cannot use anyway.
+ */
+export declare const flattenMcpContent: (result: Record<string, unknown>, maxBytes: number) => string;
+
 /**
  * Pull the ACTUAL per-call cost (USD) out of an AI-SDK result's provider
  * metadata, when the Vercel AI Gateway reported it. The gateway attaches
@@ -1322,6 +1472,36 @@ export declare const hashToVector: (text: string, dim: number) => number[];
  */
 export declare const historyToModelMessages: (history: ReadonlyArray<AgentMessage>) => ModelMessage[];
 
+/**
+ * MCP over Streamable HTTP.
+ *
+ * SSRF note, stated rather than silently assumed: `url` is app configuration.
+ * Nothing here validates that it points outside your own network, because a
+ * legitimate deployment mounts an MCP server on a private address. If the URL
+ * can ever come from user or model input in your app, gate it there — this
+ * layer treats it as trusted and everything the URL RETURNS as untrusted.
+ */
+export declare const httpMcpTransport: (options: HttpMcpTransportOptions) => McpTransport;
+
+export declare interface HttpMcpTransportOptions {
+    /** The server's Streamable-HTTP endpoint. App configuration — NEVER derived
+     *  from anything a model produced. */
+    readonly url: string;
+    /** Namespace, used only for error attribution. */
+    readonly server: string;
+    /**
+     * Extra request headers — this is where an `Authorization` goes.
+     *
+     * Read it from the environment at the call site (`process.env.GITHUB_MCP_TOKEN`).
+     * The framework ships no credential value for any server, and there is
+     * deliberately no "default token" field here to make that accidental.
+     */
+    readonly headers?: Record<string, string>;
+    readonly bounds?: Partial<McpBounds>;
+    /** Injectable for tests. Defaults to the global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+
 export declare interface InferenceDispatchDeps {
     readonly store: DataStore;
     /**
@@ -1398,12 +1578,31 @@ export declare const isAgentExecutor: (x: unknown) => x is AnyAgentExecutor;
 
 export declare const isEvalDefinition: (value: unknown) => value is EvalDefinition;
 
+/**
+ * Is this external tool a WRITE, for the purpose of the `includeWrites` gate
+ * and the confirm default?
+ *
+ * The default answer is YES for everything. That is not pessimism for its own
+ * sake: the classification exists to decide whether an agent may take an action
+ * with side effects, and the only party who can answer that for an external
+ * server is the app that chose to mount it. So the app answers, with `readOnly`.
+ * `trustToolHints` delegates the answer back to the server, explicitly, in one
+ * place a reviewer can find.
+ */
+export declare const isExternalWrite: (tool: McpToolInfo, namespace: string, policy: McpToolPolicy) => boolean;
+
+/** Is this a rendered prompt or a bare string? The discriminator `aiStep` uses
+ *  so `prompt:` can accept either without a wrapper type at every call site. */
+export declare const isRenderedPrompt: (value: unknown) => value is RenderedPrompt;
+
 /** Whether a stream with this id is currently registered (in flight). */
 export declare const isStreamActive: (streamId: string) => boolean;
 
 /** Is `x` a `defineTool(...)` result? */
 export declare const isTool: (x: unknown) => x is AnyTool;
 
+export declare const isUsableMcpToolName: (name: unknown, maxChars: number) => name is string;
+
 export declare interface JudgeVerdict {
     readonly pass: boolean;
     /** 0..1. Below `judge.threshold` fails the case even when `pass` is true. */
@@ -1437,6 +1636,267 @@ export declare const loggingMiddleware: (opts?: {
     readonly log?: (event: AiCallLog) => void;
 }) => AiMiddleware;
 
+/**
+ * Build ONE external tool. Exported so the gate can be tested at the sharpest
+ * point: hand this a tool the policy denies and it still refuses at call time,
+ * without touching the transport.
+ */
+export declare const makeMcpTool: (server: McpServer, tool: McpToolInfo, policy: McpToolPolicy, bounds: McpBounds) => AnyTool;
+
+export declare const MCP_BOUNDS_DEFAULTS: McpBounds;
+
+/** Identity this client reports in `initialize`. No version literal here — the
+ *  caller passes its own, so a published build reports the lockstep release. */
+export declare const MCP_CLIENT_INFO: {
+    readonly name: string;
+    readonly version: string;
+};
+
+/** The MCP revision this client requests. Mirror of `@voltro/mcp`'s. */
+export declare const MCP_CLIENT_PROTOCOL_VERSION = "2025-06-18";
+
+/**
+ * The ceilings applied to everything an external server sends.
+ *
+ * Resolution order is explicit option → environment variable → default, so an
+ * operator can tighten a deployment without a code change and an app can pin a
+ * value the operator cannot loosen.
+ */
+export declare interface McpBounds {
+    /** How many of a server's tools may be mounted, AFTER the policy gate.
+     *  A server advertising 4 000 tools would otherwise buy the whole context
+     *  window. Env `VOLTRO_MCP_MAX_TOOLS`. */
+    readonly maxTools: number;
+    /** Ceiling on one tool's description — the prompt-injection surface.
+     *  Env `VOLTRO_MCP_MAX_DESCRIPTION_CHARS`. */
+    readonly maxDescriptionChars: number;
+    /** Ceiling on a tool's advertised input JSON Schema, serialized. A schema
+     *  over this is DROPPED rather than truncated — a half-schema would make the
+     *  model call the tool wrongly. Env `VOLTRO_MCP_MAX_SCHEMA_BYTES`. */
+    readonly maxSchemaBytes: number;
+    /** How deep + how wide the input schema may be before it is pruned. Guards
+     *  the recursive sanitizer itself against a schema built to blow the stack. */
+    readonly maxSchemaDepth: number;
+    readonly maxSchemaNodes: number;
+    /** Ceiling on one tool-call RESULT as handed back to the model. Truncated
+     *  with a visible marker. Env `VOLTRO_MCP_MAX_RESULT_BYTES`. */
+    readonly maxResultBytes: number;
+    /** Hard ceiling on any single HTTP/stdio response body, applied while
+     *  reading — an unbounded stream is cancelled, not buffered.
+     *  Env `VOLTRO_MCP_MAX_RESPONSE_BYTES`. */
+    readonly maxResponseBytes: number;
+    /** Per-JSON-RPC-request deadline. Env `VOLTRO_MCP_TIMEOUT_MS`. */
+    readonly requestTimeoutMs: number;
+    /** Ceiling on a tool NAME. Longer names are dropped, not truncated —
+     *  a truncated name would not be the name we allowed. */
+    readonly maxToolNameChars: number;
+}
+
+/**
+ * `tools/call`. Returns the flattened, bounded text the model receives.
+ *
+ * `isError: true` is surfaced as text prefixed with `Error:` rather than as a
+ * failed Effect: a tool that failed IS information the model should get and act
+ * on, and that is exactly how `buildSdkTools` treats an app tool's rejection.
+ */
+export declare const mcpCallTool: (transport: McpTransport, server: string, toolName: string, args: Record<string, unknown>, bounds: McpBounds) => Effect.Effect<string, McpError>;
+
+/**
+ * Typed MCP client failure.
+ *
+ * `transport` — the socket/process/HTTP layer failed or timed out.
+ * `protocol`  — we reached the server and it answered with something that is
+ *               not a usable MCP response (a JSON-RPC error, a malformed body).
+ * `bounds`    — the server answered, and the answer exceeded a stated bound.
+ *               Kept SEPARATE from `protocol` on purpose: "the server is broken"
+ *               and "the server sent 40 MB" are different operational events and
+ *               the second one is the one you want to alert on.
+ * `policy`    — the app's own allow/deny gate refused. Never the server's fault.
+ */
+export declare class McpError extends McpError_base {
+}
+
+declare const McpError_base: Schema.TaggedErrorClass<McpError, "McpError", {
+    readonly _tag: Schema.tag<"McpError">;
+} & {
+    /** The app-chosen namespace of the server, never a server-supplied string. */
+    server: typeof Schema.String;
+    reason: Schema.Literal<["transport", "protocol", "bounds", "policy"]>;
+    message: typeof Schema.String;
+}>;
+
+/** The MCP handshake: `initialize`, then the `notifications/initialized` the
+ *  spec requires before any other request. */
+export declare const mcpInitialize: (transport: McpTransport, server: string, clientInfo?: {
+    readonly name: string;
+    readonly version: string;
+}) => Effect.Effect<{
+    readonly protocolVersion: string;
+    readonly serverName: string;
+}, McpError>;
+
+export declare interface McpJsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id?: string | number | null;
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+
+export declare interface McpJsonRpcResponse {
+    readonly jsonrpc: '2.0';
+    readonly id: string | number | null;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+
+/**
+ * `tools/list`, bounded.
+ *
+ * Everything a server can inflate is capped HERE rather than at the call site:
+ * a tool whose name is unusable or whose schema is oversized is DROPPED (with
+ * its name reported), a description is sanitized + truncated, and the list is
+ * cut to `maxTools` after sorting so the cut is deterministic across calls
+ * rather than "whichever ones the server put first this time".
+ */
+export declare const mcpListTools: (transport: McpTransport, server: string, bounds: McpBounds) => Effect.Effect<{
+    readonly tools: ReadonlyArray<McpToolInfo>;
+    readonly dropped: ReadonlyArray<{
+        readonly name: string;
+        readonly reason: string;
+    }>;
+}, McpError>;
+
+/** An external server, as the app names and reaches it. */
+export declare interface McpServer {
+    /**
+     * The app's own name for this server. Prefixes every tool tag
+     * (`github.create_issue`), so it is what an allow/deny rule matches on.
+     * App-chosen — never the server's self-reported name, which is untrusted.
+     */
+    readonly namespace: string;
+    readonly transport: McpTransport;
+}
+
+export declare type McpToolDecision = {
+    readonly admitted: true;
+    readonly spec: SynthesizedTool;
+} | {
+    readonly admitted: false;
+    readonly reason: string;
+};
+
+/**
+ * THE gate. One pure function, called at mount AND re-called inside every tool
+ * body before a request leaves the process, so a toolset that was tampered with
+ * after construction still cannot reach the server.
+ *
+ * Order matters and is asserted in the tests: default-deny, then the shared
+ * `passesPolicy` (deny beats allow), then the writes gate.
+ */
+export declare const mcpToolDecision: (tool: McpToolInfo, namespace: string, policy: McpToolPolicy) => McpToolDecision;
+
+/** One tool as an external server advertises it, already bounded + sanitized. */
+export declare interface McpToolInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    /**
+     * The server's own hints about the tool. ADVISORY ONLY — see
+     * `mcpTools.ts`; the server is the untrusted party, so its claim that a tool
+     * is read-only cannot be what decides whether the tool is allowed to run.
+     */
+    readonly annotations?: {
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+    };
+}
+
+/**
+ * The mount policy. Extends `AppToolPolicy` rather than paralleling it: an app
+ * that already expresses its agent policy in one shape expresses this one in
+ * the same shape, and the two lists can literally be the same object.
+ */
+export declare interface McpToolPolicy extends AppToolPolicy {
+    /**
+     * Tools the APP declares to be reads (tags, `*` globs, or a RegExp), matched
+     * against the namespaced tag. This is the app's judgement, and it is the only
+     * one that counts by default — see {@link isExternalWrite}.
+     */
+    readonly readOnly?: ReadonlyArray<string> | RegExp;
+    /**
+     * Accept the server's `annotations.readOnlyHint` as evidence a tool is a read.
+     *
+     * Default FALSE, and the default is the security decision. For an app tool the
+     * read/write split comes from the descriptor KIND, which somebody in this
+     * repository wrote. For an external tool it would come from the untrusted
+     * party, who can flip it between two `tools/list` calls — so trusting it would
+     * let a server talk its way past `includeWrites: false`.
+     */
+    readonly trustToolHints?: boolean;
+    /** Ceilings on everything the server sends. See {@link McpBounds}. */
+    readonly bounds?: Partial<McpBounds>;
+}
+
+/** The `Record<string, AnyTool>` an agent loop wants, without the inventory. */
+export declare const mcpTools: (server: McpServer, policy: McpToolPolicy) => Effect.Effect<Record<string, AnyTool>, McpError>;
+
+/** A mounted server's toolset. */
+export declare interface McpToolset {
+    readonly namespace: string;
+    /** Keyed by the namespaced tag — the shape the agent loop consumes. */
+    readonly tools: Record<string, AnyTool>;
+    /** The same inventory type `synthesizeToolSpecs` returns, for a confirm-UI. */
+    readonly specs: ReadonlyArray<SynthesizedTool>;
+    /** Everything the server advertised that did NOT mount, and why. Surfaced
+     *  rather than logged: a tool silently missing from an agent's set is a
+     *  support ticket that starts "the agent just says it can't do that". */
+    readonly dropped: ReadonlyArray<{
+        readonly name: string;
+        readonly reason: string;
+    }>;
+    /** The bounds actually in force (after env + defaults resolved). */
+    readonly bounds: McpBounds;
+    readonly close: () => Effect.Effect<void>;
+}
+
+/**
+ * Connect to an external MCP server, list its tools, and mount the ones this
+ * app's policy admits.
+ *
+ * ```ts
+ * 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.get_*', 'github.search_*'], readOnly: ['github.get_*', 'github.search_*'] },
+ * )
+ * yield* generateObjectWithTools({ prompt, tools: github.tools, schema: Result })
+ * ```
+ */
+export declare const mcpToolset: (server: McpServer, policy: McpToolPolicy) => Effect.Effect<McpToolset, McpError>;
+
+/** `<namespace>.<toolName>` — the tag an allow/deny rule matches. */
+export declare const mcpToolTag: (namespace: string, toolName: string) => string;
+
+/**
+ * One JSON-RPC round trip against an external server. The seam every test uses
+ * — a test supplies an in-memory transport and never opens a socket, which is
+ * what makes the untrusted-input bounds assertable on their own.
+ */
+export declare interface McpTransport {
+    /** Send a request; resolve with its response. */
+    readonly send: (request: McpJsonRpcRequest) => Effect.Effect<McpJsonRpcResponse, McpError>;
+    /** Send a notification (no id, no response expected). */
+    readonly notify: (request: McpJsonRpcRequest) => Effect.Effect<void, McpError>;
+    /** Release the socket / child process. Idempotent. */
+    readonly close: () => Effect.Effect<void>;
+}
+
 /** Token tally, mirroring `GenerateTextResult['usage']`. Only `generateImage`
  *  reports one (the speech + video model specs carry no usage), which is why
  *  it's optional on every media result. */
@@ -1619,6 +2079,16 @@ export declare type OpenAIModel = 'gpt-5.5' | 'gpt-4o' | 'gpt-4o-mini' | (string
  *  cannot be journaled, and its JSON rendering can. */
 export declare const outputJsonSchema: (schema: Schema.Schema.Any, fn: string) => Effect.Effect<Record<string, unknown>, AiError>;
 
+/**
+ * Pull the first JSON-RPC message out of a Streamable-HTTP response body.
+ * A server may answer a POST with `application/json` (one object) or with
+ * `text/event-stream` (SSE frames, the response interleaved with whatever else
+ * the server wants to push). Both are spec-legal; we take the first frame whose
+ * `id` matches and ignore the rest, because a client that keeps reading after
+ * its answer is a client an unbounded server can hold open forever.
+ */
+export declare const parseHttpMcpBody: (body: string, contentType: string, id: string | number | null) => McpJsonRpcResponse | null;
+
 /** Does this tag pass the allow/deny policy? deny wins; allow (when set) gates. */
 export declare const passesPolicy: (tag: string, policy: AppToolPolicy) => boolean;
 
@@ -1638,6 +2108,119 @@ export declare const patchStreamingMessage: (store: DataStore, id: string, parts
  */
 export declare const priceForModel: (model: string) => ModelPrice | undefined;
 
+export declare interface PromptDefinition {
+    /**
+     * Stable identity across revisions. Dotted, like a descriptor tag
+     * (`support.triage`) — the same vocabulary the rest of the framework uses for
+     * "the name of a thing an app owns".
+     */
+    readonly id: string;
+    /**
+     * The template, with `{{name}}` placeholders. A STRING, not a function, and
+     * that is the design: a function has no stable content to hash, so a
+     * function-built prompt could be versioned only by hashing its output — which
+     * would make every distinct customer message a new "version". Compose in the
+     * variables instead.
+     */
+    readonly template: string;
+    /** Optional system message. Part of the digest — changing it IS a new
+     *  version, because it changes the model's behaviour as surely as the
+     *  template does. */
+    readonly system?: string;
+    /** Optional human label for this revision (`'shorter-system'`). Metadata:
+     *  deliberately NOT part of the digest, so relabelling does not fork a
+     *  version. */
+    readonly label?: string;
+}
+
+/** The digest form: a prefix, not the whole hash. This is a correlation handle,
+ *  and a full sha256 in a dashboard cell is a wall of hex nobody reads.
+ *
+ *  Lives here rather than in `inferStep.ts` (where it started) because it is now
+ *  the identity of a versioned artefact, and `inferStep` imports
+ *  `@voltro/workflow` — a prompt registry has no business needing the workflow
+ *  engine to compute a hash. `inferStep` re-exports it. */
+export declare const promptDigest: (prompt: string) => string;
+
+export declare class PromptRenderError extends PromptRenderError_base {
+}
+
+declare const PromptRenderError_base: Schema.TaggedErrorClass<PromptRenderError, "PromptRenderError", {
+    readonly _tag: Schema.tag<"PromptRenderError">;
+} & {
+    promptId: typeof Schema.String;
+    missing: Schema.Array$<typeof Schema.String>;
+    message: typeof Schema.String;
+}>;
+
+export declare const PROMPTS_TABLE = "_voltro_prompts";
+
+/**
+ * One row per (prompt id · content digest) — i.e. one row per VERSION.
+ *
+ * `promptId` + `digest` are `.maxLength(191)` because they carry a composite
+ * UNIQUE: an unbounded text column under a UNIQUE is backed on MariaDB by a
+ * hash long-unique index whose hidden column wedges binlog CDC (see
+ * `@voltro/database`'s maintainer note). 191 is the utf8mb4 index-prefix limit.
+ *
+ * `lastUsedAt` is what the retention sweep prunes on, and the table is
+ * self-healing under it: `recordPromptVersion` re-inserts on the next use, so a
+ * version that ages out is a version nothing has run in a year.
+ */
+export declare const promptsTable: Table<typeof PROMPTS_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
+
+/** A prompt's identity, as it is stamped onto a step row and a usage row. */
+export declare interface PromptStamp {
+    /** The author-chosen stable id, e.g. `support.triage`. */
+    readonly promptId: string;
+    /** Content digest of the template (+ system). CHANGES when the template does
+     *  — that is the version. */
+    readonly digest: string;
+    /** The monotonic revision `recordPromptVersion` assigned, once it has been
+     *  registered. Absent before first registration; the digest is the identity
+     *  either way. */
+    readonly revision?: number;
+    /** Optional human label the author gave this revision. */
+    readonly label?: string;
+}
+
+/** Look one version up by its digest — the reverse of the stamp on a step row
+ *  or a usage row, and therefore the answer to "which prompt produced this
+ *  run". */
+export declare const promptVersionByDigest: (store: DataStore, digest: string) => Effect.Effect<PromptVersionRow | null>;
+
+/**
+ * The version digest of a (template, system) pair.
+ *
+ * LENGTH-PREFIXED, not separator-joined. A separator is only injective when it
+ * cannot occur in the parts, and every printable candidate can occur in prose:
+ * join on a space and template `'a b'` + no system collides with template `'a'`
+ * + system `'b'`, so two genuinely different prompts read as ONE version and the
+ * second one's provenance silently points at the first. A length prefix has no
+ * such case and needs no exotic character.
+ *
+ * (The first version of this used a raw NUL as the separator, which is the
+ * repo-wide rule this file now also demonstrates the reason for: the file
+ * became BINARY to grep, and every text search over it silently returned
+ * nothing — indistinguishable from a clean file.)
+ */
+export declare const promptVersionDigest: (template: string, system: string | undefined) => string;
+
+/** A registered version, as read back. */
+export declare interface PromptVersionRow {
+    readonly promptId: string;
+    readonly digest: string;
+    readonly revision: number;
+    readonly label: string | null;
+    readonly template: string | null;
+    readonly system: string | null;
+    readonly firstSeenAt: Date | null;
+    readonly lastUsedAt: Date | null;
+}
+
+/** Every registered version of one prompt, newest revision first. */
+export declare const promptVersionsFor: (store: DataStore, promptId: string) => Effect.Effect<ReadonlyArray<PromptVersionRow>>;
+
 /**
  * A resolved provider choice — a DISCRIMINATED UNION on `name`. Each provider
  * only carries the fields that apply to it: the mock-only `mockText` / `script`
@@ -1749,6 +2332,10 @@ export declare interface QueuedInference {
     readonly model: string;
     readonly prompt: string;
     readonly system: string | null;
+    /** Prompt provenance carried from the parked run — see the table. */
+    readonly promptId: string | null;
+    readonly promptDigest: string | null;
+    readonly promptRevision: number | null;
     readonly maxTokens: number | null;
     readonly providerOptions: unknown;
     readonly jsonSchema: Record<string, unknown> | null;
@@ -1775,6 +2362,25 @@ export declare interface ReadRecorder<S extends QueryableStore> {
  */
 export declare const recordAiUsage: (store: DataStore, record: AiUsageRecordInput) => Effect.Effect<CostBreakdown>;
 
+/**
+ * Register a prompt version, idempotently, and return it.
+ *
+ * First sight of a `(promptId, digest)` pair inserts it with the next revision
+ * number for that `promptId`; every later sight only touches `lastUsedAt`. The
+ * insert is an `insertIgnore` over the composite UNIQUE, so two replicas
+ * racing the same first sight produce one row.
+ *
+ * The revision NUMBER is read-then-write and therefore not strictly serialised:
+ * two different versions of one prompt first seen in the same millisecond on
+ * two replicas can both land on revision 4. That is accepted deliberately — the
+ * digest is the identity and it is exact; the revision is a label for humans,
+ * and paying for a serialisable counter to make a label prettier is the wrong
+ * trade. Order by `firstSeenAt` when you need the true sequence.
+ */
+export declare const recordPromptVersion: (store: DataStore, prompt: PromptDefinition & {
+    readonly digest?: string;
+}) => Effect.Effect<PromptVersionRow>;
+
 /**
  * Wrap a store so the rows it serves become a dependency set — automatic
  * provenance capture with no runtime edit. Every `query()` records
@@ -1802,6 +2408,16 @@ export declare const redisResumableStreamStore: (redis: ResumableRedis, opts?: {
     readonly ttlSeconds?: number;
 }) => ResumableStreamStore;
 
+/**
+ * Re-list and re-gate a mounted server.
+ *
+ * This is the ONLY way the tool set changes. Nothing reacts to a
+ * `notifications/tools/list_changed`, and that is deliberate: a set that can be
+ * rewritten by the party it protects against is not a set, and the cost of the
+ * alternative is a stale tool until the app decides otherwise.
+ */
+export declare const refreshMcpToolset: (server: McpServer, policy: McpToolPolicy) => Effect.Effect<McpToolset, McpError>;
+
 /**
  * Register (or reuse) the `AbortController` for `streamId`. `streamText` calls
  * this when given a `streamId`; it threads the returned controller's `signal`
@@ -1811,6 +2427,18 @@ export declare const redisResumableStreamStore: (redis: ResumableRedis, opts?: {
  */
 export declare const registerStream: (streamId: string) => AbortController;
 
+/** What `.render(vars)` produces — a stamp plus the text to send. */
+export declare interface RenderedPrompt extends PromptStamp {
+    readonly prompt: string;
+    readonly system?: string;
+    /** The artefact this was rendered from. Carried along so a consumer that
+     *  receives only the rendered value (`aiStep`) can REGISTER the version
+     *  without the app having to remember a separate boot-time call. It is the
+     *  template — code, not data — so carrying it costs nothing a repository
+     *  checkout does not already cost. */
+    readonly definition: PromptDefinition;
+}
+
 /**
  * Gate an AI call against a per-tenant USD budget with an ATOMIC reservation —
  * the cap precedent is billing's `requireEntitlement` / storage's
@@ -1888,6 +2516,9 @@ export declare const resolveEmbeddingModel: (config: EmbeddingProviderConfig) =>
 
 export declare const resolveImageModel: (config: ProviderConfig) => ImageModelV4;
 
+/** Explicit option → env → default, per field. */
+export declare const resolveMcpBounds: (overrides: Partial<McpBounds> | undefined, env?: Record<string, string | undefined>) => McpBounds;
+
 export declare const resolveModel: (config: ProviderConfig, middleware?: AiMiddleware | ReadonlyArray<AiMiddleware>) => LanguageModelV4;
 
 export declare const resolveSpeechModel: (config: ProviderConfig) => SpeechModelV4;
@@ -2076,6 +2707,30 @@ export declare interface RunEvalDeps {
     readonly branchId?: string;
 }
 
+/**
+ * Make one server-supplied string safe to place in a model's context: strip
+ * invisibles, normalise runaway whitespace, and cap the length with a marker
+ * the model can see.
+ *
+ * The cap is the honest part. It does NOT stop a description from CONTAINING
+ * an instruction — nothing does, short of not showing the model the description
+ * at all, which would make the tool unusable. It stops the description from
+ * being a whole second system prompt, and it stops the invisible encodings that
+ * make an injection unreviewable by a human reading the same string.
+ */
+export declare const sanitizeExternalText: (raw: unknown, maxChars: number) => string;
+
+/**
+ * Recursively bound + clean a server's input JSON Schema.
+ *
+ * Depth and node budget are enforced as we walk (a subtree past either is
+ * dropped, not truncated mid-object), and every `description` / `title` string
+ * anywhere in the tree is sanitized — those are model-visible too, and a
+ * per-property description is the least-inspected place to hide an instruction.
+ * Returns `null` when the schema is unusable, in which case the tool is dropped.
+ */
+export declare const sanitizeInputSchema: (schema: unknown, bounds: McpBounds) => Record<string, unknown> | null;
+
 /**
  * Combine assertion failures + the judge verdict into one pass/fail. Pure. A case
  * passes iff no assertion failed AND (no judge, or the judge's score clears the
@@ -2252,6 +2907,31 @@ export { simulateStreamingMiddleware }
  */
 export declare const startResumableProducer: (streamId: string, store: ResumableStreamStore, source: () => Stream.Stream<AgentEvent>) => Effect.Effect<void>;
 
+/**
+ * MCP over stdio — the transport most published servers ship (`npx
+ * some-mcp-server`).
+ *
+ * The child does NOT inherit `process.env`. That is a deliberate difference
+ * from `child_process.spawn`'s default: an MCP server is a program you are
+ * handing your model's tool surface to, and the default should not also hand
+ * it every credential in the process. Spread what it needs explicitly.
+ */
+export declare const stdioMcpTransport: (options: StdioMcpTransportOptions) => McpTransport;
+
+export declare interface StdioMcpTransportOptions {
+    /** Executable to spawn. App configuration, never model output. */
+    readonly command: string;
+    readonly args?: ReadonlyArray<string>;
+    /** Namespace, for error attribution. */
+    readonly server: string;
+    /** Environment for the child. Pass credentials here, from YOUR env — the
+     *  child does NOT inherit the parent environment unless you spread it in,
+     *  so a server cannot read a secret you did not hand it. */
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+    readonly bounds?: Partial<McpBounds>;
+}
+
 export declare const STREAM_EVENTS_TABLE = "_voltro_stream_events";
 
 export declare const STREAM_STATE_TABLE = "_voltro_stream_state";
@@ -2368,6 +3048,16 @@ export declare interface SynthesizedTool {
     readonly write: boolean;
     /** Require human confirmation before this call executes. */
     readonly confirm: boolean;
+    /**
+     * Whether that confirmation is ENFORCED by the app — i.e. the descriptor also
+     * declares `requiresApproval:`, so the real handler parks the call as a
+     * durable approval instead of running it.
+     *
+     * The inventory reports both flags because they answer different questions: a
+     * confirm-UI asks `confirm`, and "why is this tool not executable" is answered
+     * only by the pair.
+     */
+    readonly approvalBacked: boolean;
     readonly maxPerRun?: number;
 }
 
@@ -2375,6 +3065,10 @@ export declare interface SynthesizedTool {
  * The discovery/inventory view: every descriptor that is exposable AND passes
  * the policy, as `SynthesizedTool` metadata (no executable body). Use for the
  * capability surface / a confirm-UI. Sorted by name.
+ *
+ * Deliberately does NOT apply the `includeWrites` gate — that is an EXECUTION
+ * decision (`appToolDecision`), and an inventory that hid write tools would
+ * make a confirm-UI unable to explain why one is missing.
  */
 export declare const synthesizeToolSpecs: (entries: ReadonlyArray<AppToolEntry>, policy?: AppToolPolicy) => ReadonlyArray<SynthesizedTool>;
 
@@ -2409,6 +3103,18 @@ export declare interface ToolDef<A, I, O> {
     readonly name: string;
     readonly description: string;
     readonly input: Schema.Schema<A, I>;
+    /**
+     * A ready-made JSON Schema for the tool's parameters, used INSTEAD of
+     * rendering `input`.
+     *
+     * For a tool whose shape is defined elsewhere — an external MCP server's
+     * `inputSchema` — there is no faithful Effect Schema to render from, and a
+     * lossy re-expression would reject arguments the far side would have
+     * accepted. So the far side's schema is what the model sees, while `input`
+     * stays the decode gate on the way in. Leave unset for a normal tool; a
+     * rendered `input` is strictly better when you own the shape.
+     */
+    readonly inputJsonSchema?: Record<string, unknown>;
     /** Optional result schema. When set, `buildSdkTools` decodes the body's
      *  output through it before handing the value back to the model. */
     readonly output?: Schema.Schema.Any;