okengine 0.18.5 → 0.19.1

package/site/content/docs/elements/ai/agents.mdx

@@ -0,0 +1,235 @@
+---
+title: "Agents"
+description: "Bounded agents — tools are Flows, maxSteps and budget.maxCostPerRun cap the loop, invoke with fx.run."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+An agent (`ai.agent`) is a **bounded tool-calling loop**. Tools are your app’s Flows (and
+allowlisted MCP refs) — each step goes through `fx.call`. The loop stops at `maxSteps` or
+`budget.maxCostPerRun`.
+
+For developers who need a planner or support assistant without writing a custom tool runtime —
+declare the bag, run with `fx.run`.
+
+<Callout title="The one rule">
+  Pass Flow names (or handles) in `tools`, set `maxSteps` and `budget.maxCostPerRun`, then
+  `fx.run(agent, {message})`. There is no `instructions` / `in` / `out` on `ai.agent` — shape the
+  user message yourself.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare model + agent
+
+```typescript title="src/core/ai.ts"
+import { ai } from "okengine";
+
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export const supportAgent = ai.agent("support.assistant", {
+  model: "smart",
+  tools: ["docs.search", "tickets.create"],
+  maxSteps: 5,
+  budget: { maxCostPerRun: 0.1 },
+});
+```
+
+</Step>
+
+<Step>
+### Run from a Flow
+
+```typescript title="src/flows/support/assist.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { supportAgent } from "@/core/ai";
+import { member } from "@/core/gate";
+
+export const assist = on(
+  http
+    .post({
+      in: z.object({ query: z.string().min(1) }),
+    })
+    .gate(member),
+  flow({
+    do: async ({ query }, fx) => {
+      return await fx.run(supportAgent, {
+        message: `Help the member: ${query}`,
+      });
+    },
+  }),
+);
+```
+
+Runtime records the agent name under `asks`. Prefer declaring `effects: { asks: ["support.assistant"] }`
+when inference does not see `fx.run`.
+
+</Step>
+
+<Step>
+### Bound termination
+
+Default `maxSteps` is **6** when omitted. Hitting the step cap ends the loop; exceeding
+`budget.maxCostPerRun` throws `AiBudgetExceededError`:
+`ai: agent "…" exceeded maxCostPerRun N`.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Flow tools", "MCP tools", "Ask tools", "Budget"]}>
+
+<Tab value="Flow tools">
+
+String names or Flow handles — same capability path as `fx.call`:
+
+```typescript
+import { searchDocs } from "@/flows/docs/search";
+import { createTicket } from "@/flows/tickets/create";
+
+export const supportAgent = ai.agent("support.assistant", {
+  model: smart,
+  tools: [searchDocs, createTicket],
+  maxSteps: 8,
+});
+```
+
+</Tab>
+
+<Tab value="MCP tools">
+
+Outbound MCP refs join the same bag (`mcp:<server>/<tool>`):
+
+```typescript
+const github = ai.mcpServer("github", {
+  url: "https://mcp.example/github",
+  auth: { bearer: vault.secret("GITHUB_MCP_TOKEN") },
+  tools: ["create_issue"],
+});
+
+export const planner = ai.agent("planner", {
+  model: "smart",
+  tools: ["tasks.list", github.tool("create_issue")],
+  maxSteps: 8,
+  budget: { maxCostPerRun: 0.25 },
+});
+```
+
+See [MCP](/docs/elements/ai/mcp).
+
+</Tab>
+
+<Tab value="Ask tools">
+
+One-shot tool loop on `fx.ask` without a named agent:
+
+```typescript
+await fx.ask(triage, input, {
+  tools: ["docs.search"],
+  maxSteps: 3,
+});
+```
+
+</Tab>
+
+<Tab value="Budget">
+
+Run cost is on `budget`, not a top-level `maxCostPerRun` field:
+
+```typescript
+ai.agent("planner", {
+  tools: ["tasks.list", "tasks.create"],
+  budget: { maxCostPerRun: 0.25, maxCostPerCall: 0.05 },
+});
+```
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+| Option     | Type                                  | Default     | Meaning                      |
+| ---------- | ------------------------------------- | ----------- | ---------------------------- |
+| `model`    | `AiModelDecl` \| `string`             | first model | Logical binding for the loop |
+| `tools`    | Flow / MCP refs                       | `[]`        | Callable via `fx.call`       |
+| `maxSteps` | `number`                              | `6`         | Hard cap on tool rounds      |
+| `budget`   | `{ maxCostPerCall?, maxCostPerRun? }` | —           | Cost contracts for the run   |
+
+## `fx.run` input
+
+Pass a string or `{ message: string }` (and any extra fields your tools need in context). The
+agent declaration does **not** take Zod `in` / `out` — validate on the surrounding Flow.
+
+```typescript
+await fx.run(supportAgent, "Summarize open tickets");
+await fx.run(supportAgent, { message: "Summarize open tickets" });
+```
+
+## Agents vs ask-with-tools
+
+| Surface                        | When                                         |
+| ------------------------------ | -------------------------------------------- |
+| `ai.agent` + `fx.run`          | Reusable tool bag, shared step/budget policy |
+| `fx.ask(prompt, …, { tools })` | One prompt, occasional tools                 |
+
+Both default `maxSteps` to `6`. Denied or unknown tools surface as
+`ai: all tool calls denied for prompt "…"` / `ai: model requested unknown tool "…"`.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title='ai: unknown agent "…"'>
+  `fx.run` named an agent that was never declared, or the declaring module was not imported before
+  `oke()`.
+</Accordion>
+
+<Accordion title='ai: agent "…" exceeded maxCostPerRun'>
+  `AiBudgetExceededError` — raise `budget.maxCostPerRun`, lower `maxSteps`, or shrink tools.
+</Accordion>
+
+<Accordion title='ai: model requested unknown tool "…"'>
+  The model emitted a tool name outside the declared `tools` bag. Align names with Flow / MCP refs,
+  or tighten instructions in the user `message`.
+</Accordion>
+
+<Accordion title="OKE1005 on agent runs">
+  Runtime gates `fx.run` as an ask of the agent name. List `effects: { asks: ["support.assistant"] }`
+  when the compiler does not infer `fx.run`.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Prompts](/docs/elements/ai/prompts) — `fx.ask` and ask-time tools
+- [MCP](/docs/elements/ai/mcp) — inbound tools and outbound servers
+- [Flow](/docs/elements/flow) — tools are ordinary Flows
+- [AI](/docs/elements/ai) — guardrails figure and drivers
+
+## Next
+
+<Cards>
+  <Card
+    title="MCP"
+    description="Expose and consume Model Context Protocol tools."
+    href="/docs/elements/ai/mcp"
+  />
+  <Card
+    title="Prompts"
+    description="Versioned fx.ask artifacts."
+    href="/docs/elements/ai/prompts"
+  />
+  <Card title="AI" description="Element overview." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/elements/ai/index.mdx

@@ -0,0 +1,342 @@
+---
+title: "Overview"
+description: "Machine intelligence — bind models, ask versioned prompts, run bounded agents, embed into store.index, and connect MCP."
+icon: "Sparkles"
+source: "docs/spec/unified-theory.md"
+---
+
+AI is how your backend **calls a model as a declared effect**. Ticket triage, a weekly
+summary, a planner that tools your own Flows — each ask is a named prompt or agent with
+budgets, not an SDK call buried in `do`.
+
+For developers wiring OpenRouter or any OpenAI-compatible `/v1` endpoint — bind a model,
+mint a prompt, ask through `fx`.
+
+<Callout title="The one rule">
+  Declare `ai.model` → `model.prompt` (or `ai.agent` / `ai.embed`), then call through `fx.ask` /
+  `fx.run` / `fx.embed`. There is no top-level `ai.prompt`. Budgets and `maxSteps` are contracts;
+  PII to a third-party model needs explicit `allowPii`.
+</Callout>
+
+<AiBlocks />
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Bind a model and mint a prompt
+
+```typescript title="src/core/ai.ts"
+import { ai } from "okengine";
+import { z } from "zod";
+
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export const triage = smart.prompt("ticket-triage", {
+  version: 1,
+  budget: { maxCostPerCall: 0.02 },
+  out: z.object({
+    category: z.enum(["billing", "technical", "other"]),
+    urgency: z.enum(["low", "medium", "high"]),
+  }),
+});
+```
+
+Import this module before `oke()` so registries adopt the decls.
+
+</Step>
+
+<Step>
+### Ask from a Flow
+
+```typescript title="src/flows/support/triage.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { triage } from "@/core/ai";
+
+export const classify = on(
+  http.post({
+    in: z.object({ message: z.string().min(1) }),
+  }),
+  flow({
+    do: async ({ message }, fx) => {
+      return await fx.ask(triage, { message });
+    },
+  }),
+);
+```
+
+The compiler stamps `asks: ["ticket-triage"]` on the Flow’s effects.
+
+</Step>
+
+<Step>
+### Call the endpoint
+
+```bash
+curl -X POST http://localhost:6530/support/triage \
+  -H "accept: application/json" \
+  -H "content-type: application/json" \
+  -d '{"message":"Invoice double-charged last week"}'
+```
+
+With `out` set, the model must return JSON matching the schema or the ask throws
+`AiSchemaValidationError`.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+From a bare ask to fallback models, tools on ask, and a bounded agent:
+
+<Tabs items={["Minimal", "via", "Tools", "Agent"]}>
+
+<Tab value="Minimal">
+
+Prompt handle + input — model comes from the parent `ai.model`:
+
+```typescript
+const result = await fx.ask(triage, { message: "Cannot reset password" });
+```
+
+</Tab>
+
+<Tab value="via">
+
+Ordered recovery across logical bindings. Each name opens its **own** client — keys and
+`baseUrl` never mix:
+
+```typescript
+export const triage = smart.prompt("ticket-triage", {
+  version: 1,
+  via: ["smart", "local"],
+  out: z.object({ category: z.string() }),
+});
+```
+
+Override per call with `fx.ask(triage, input, { via: ["local"] })`.
+
+</Tab>
+
+<Tab value="Tools">
+
+Offer Flows as tools on a single ask. Each invocation goes through `fx.call`
+(default `maxSteps: 6`):
+
+```typescript
+await fx.ask(
+  triage,
+  { message },
+  {
+    tools: [searchDocs, createTicket],
+    maxSteps: 4,
+  },
+);
+```
+
+**Consequence:** undeclared tools fail capability checks the same way as `fx.call`.
+
+</Tab>
+
+<Tab value="Agent">
+
+Multi-step loop with a declared tool bag and run budget:
+
+```typescript
+export const supportAgent = ai.agent("support.assistant", {
+  model: "smart",
+  tools: ["docs.search", "tickets.create"],
+  maxSteps: 5,
+  budget: { maxCostPerRun: 0.1 },
+});
+
+// In a Flow:
+return await fx.run(supportAgent, { message: "Help with billing" });
+```
+
+</Tab>
+
+</Tabs>
+
+## Declaration Reference
+
+| Declaration    | Signature                      | Purpose                                       |
+| -------------- | ------------------------------ | --------------------------------------------- |
+| `ai.model`     | `ai.model(name, options?)`     | Logical binding (provider / wire model / key) |
+| `model.prompt` | `model.prompt(name, options?)` | Versioned prompt on that binding              |
+| `ai.agent`     | `ai.agent(name, options?)`     | Bounded tool-calling agent                    |
+| `ai.embed`     | `ai.embed(name, options?)`     | Embedding pipeline into `store.index`         |
+| `ai.mcpServer` | `ai.mcpServer(name, options)`  | Outbound MCP client (allowlisted tools)       |
+
+There is **no** `ai.prompt(...)` — mint prompts only via `model.prompt`.
+
+## `fx` surface
+
+| Method                           | Capability          | Meaning                                          |
+| -------------------------------- | ------------------- | ------------------------------------------------ |
+| `fx.ask(prompt, input?, opts?)`  | `asks`              | Complete a versioned prompt (optional tool loop) |
+| `fx.run(agent, input?)`          | `asks` (agent name) | Run a declared agent                             |
+| `fx.stream(model, opts?)`        | `asks`              | Token stream from a model binding                |
+| `fx.embed(model, text)`          | `embeds`            | Return a vector (does not write an index)        |
+| `fx.search(embed, query, opts?)` | `reads`             | Similarity search over an embed / index          |
+
+### `fx.ask` options
+
+| Option     | Type          | Default                  | Meaning                        |
+| ---------- | ------------- | ------------------------ | ------------------------------ |
+| `via`      | refs          | prompt `via` / `[model]` | Recovery chain for this call   |
+| `timeout`  | `"30s"` \| ms | prompt `timeout`         | Per-call deadline              |
+| `tools`    | Flow refs     | —                        | Offered as tools via `fx.call` |
+| `maxSteps` | `number`      | `6`                      | Cap on tool rounds             |
+
+Undeclared ask → **OKE1005** `UNDECLARED_ASK`. Undeclared embed → **OKE1009**.
+
+## Guardrails
+
+Budgets, version pins, step limits, and PII egress are contracts — not guidelines:
+
+<AiGuardrails />
+
+### PII egress
+
+Sending a `.pii()` field to a **third-party** provider fails the build unless the Flow
+declares `allowPii: true` (or `pii: "allow"`). `mock`, `local`, and `openai-compatible` are
+not third-party egress.
+
+<AiPiiEgress />
+
+```typescript
+flow({
+  allowPii: true,
+  do: async (input, fx) => fx.ask(triage, { email: input.email }),
+});
+```
+
+## Per-environment drivers
+
+`AiDriverId`: `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex`.
+
+Boot implements `mock`, `anthropic`, and `openai-compatible`. `bedrock` / `vertex` are
+reserved and throw until implemented. Dev/test fall back to **`mock`** when unset — **prod
+must declare** `drivers.ai`.
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    ai: {
+      dev: "openai-compatible",
+      test: "mock",
+      prod: "openai-compatible",
+    },
+  },
+});
+```
+
+| Driver              | Runs as             | Best for                                       |
+| ------------------- | ------------------- | ---------------------------------------------- |
+| `mock`              | In-process stub     | Tests, CI, no network                          |
+| `openai-compatible` | OpenAI HTTP API     | OpenRouter, cloud registries, any `/v1` server |
+| `anthropic`         | Native Messages API | Production Claude + reliable tools             |
+
+Env knobs: `OKE_AI_DRIVER`, `OKE_AI_URL` / `OPENAI_BASE_URL`, provider API keys.
+Compose does not pin inference — BYO URL + keys, or [OpenRouter](/docs/recipes/openrouter).
+
+## The Capabilities of AI
+
+<Cards>
+  <Card
+    title="Models"
+    description="Verified providers, limited-compatibility caveats, cloud and BYO bindings."
+    href="/docs/elements/ai/models"
+  />
+  <Card
+    title="Prompts"
+    description="Versioned artifacts, via chains, budgets, out-schema validation."
+    href="/docs/elements/ai/prompts"
+  />
+  <Card
+    title="Agents"
+    description="Tool bags are Flows — maxSteps and maxCostPerRun bound the loop."
+    href="/docs/elements/ai/agents"
+  />
+  <Card
+    title="Model Context Protocol"
+    description="Expose Flows as MCP tools; consume external servers via ai.mcpServer."
+    href="/docs/elements/ai/mcp"
+  />
+</Cards>
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title='ai: unknown prompt "…"'>
+  `fx.ask` named a prompt that was never minted with `model.prompt`, or the declaring module was not
+  imported before `oke()`.
+</Accordion>
+
+<Accordion title="OKE1005 — UNDECLARED_ASK">
+  Cause: `Flow "{flow}" asks "{resource}" without declaring it.` Touch the prompt handle
+  inside `do` (inference) or list `effects: { asks: ["ticket-triage"] }`.
+</Accordion>
+
+<Accordion title="AiSchemaValidationError / AiSchemaInvalid">
+  Cause: `ai: schema validation failed for prompt "…"@N: …` The model reply did not match `out`. Fix
+  the schema, the input, or the model — there is no automatic “schema correction” retry.
+</Accordion>
+
+<Accordion title="AiBudgetExceededError">
+  Cause: `ai: prompt "…" exceeded maxCostPerCall N` or `ai: agent "…" exceeded maxCostPerRun N`.
+  Raise the budget or shrink the work.
+</Accordion>
+
+<Accordion title="build failed: … without allowPii">
+  Cause: `build failed: flow "…" sends pii field(s) […] to a third-party model without allowPii`.
+  Set `allowPii: true` on the Flow, or keep the ask on `mock` / `local` / `openai-compatible`.
+</Accordion>
+
+<Accordion title="oke boot: unknown AI driver / reserved">
+  Prod must pin a real `drivers.ai` id. `bedrock` and `vertex` throw `oke boot: AI driver "…" is
+  reserved but not implemented yet`.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Models](/docs/elements/ai/models) — provider registry and `baseUrl` rules
+- [Prompts](/docs/elements/ai/prompts) — `via`, budgets, versions, evals
+- [Agents](/docs/elements/ai/agents) — `fx.run`, tools, `maxSteps`
+- [MCP](/docs/elements/ai/mcp) — inbound `mcp.tool` and outbound `ai.mcpServer`
+- [OpenRouter](/docs/recipes/openrouter) — zero-Docker cloud path
+- [fx](/docs/reference/fx) — `fx.ask` / `fx.run` / `fx.embed`
+- [Errors](/docs/reference/errors) — OKE1005 · OKE1009
+
+## Next
+
+<Cards>
+  <Card
+    title="Models"
+    description="Bind providers and wire model ids."
+    href="/docs/elements/ai/models"
+  />
+  <Card
+    title="Channel Element"
+    description="Reach humans with email, SMS, WhatsApp, and push."
+    href="/docs/elements/channel"
+  />
+  <Card
+    title="The Model"
+    description="Eight elements overview."
+    href="/docs/understand/the-architecture"
+  />
+</Cards>