okengine 0.18.5 → 0.19.0

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

@@ -0,0 +1,256 @@
+---
+title: "Prompts"
+description: "Versioned prompt artifacts on ai.model — out schemas, via recovery, budgets, timeouts, and fx.ask."
+icon: "FileCode"
+source: "docs/spec/unified-theory.md"
+---
+
+A prompt is a **versioned artifact** minted on a model binding (`smart.prompt(...)`). It names
+the ask, optional `in` / `out` shapes, a recovery chain, and a cost cap — then Flows call it
+with `fx.ask`.
+
+For developers who need typed triage JSON and a fallback model — declare once, ask everywhere.
+
+<Callout title="The one rule">
+  Mint prompts with `model.prompt(name, options)` — there is no top-level `ai.prompt`. Input is
+  JSON-serialized (no `template` / `{{var}}` API). When `out` is set, the reply must match or
+  the ask throws.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Mint a prompt on a model
+
+```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 classifyTicket = smart.prompt("support.classify", {
+  version: 1,
+  budget: { maxCostPerCall: 0.01 },
+  in: z.object({ message: z.string() }),
+  out: z.object({
+    category: z.enum(["billing", "technical", "feature_request"]),
+    urgency: z.enum(["low", "medium", "high"]),
+  }),
+});
+```
+
+</Step>
+
+<Step>
+### Ask from a Flow
+
+```typescript title="src/flows/support/classify.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { classifyTicket } from "@/core/ai";
+
+export const classify = on(
+  http.post(),
+  flow({
+    in: z.object({ message: z.string().min(1) }),
+    do: async ({ message }, fx) => {
+      return await fx.ask(classifyTicket, { message });
+    },
+  }),
+);
+```
+
+Manifest lists `asks: ["support.classify"]`. Pin a version at call time with
+`fx.ask("support.classify@1", input)`.
+
+</Step>
+
+<Step>
+### See structured output
+
+With `out` set, the runtime appends a schema instruction and validates the JSON reply. Invalid
+shape → `AiSchemaValidationError` (`code: "AiSchemaInvalid"`) — **no** automatic correction
+retry.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Minimal", "via", "Budget", "Tools"]}>
+
+<Tab value="Minimal">
+
+Name + optional version — model is the parent binding:
+
+```typescript
+export const summarize = smart.prompt("docs.summarize", { version: 1 });
+
+await fx.ask(summarize, { text: "…" });
+```
+
+</Tab>
+
+<Tab value="via">
+
+Ordered logical model names for recovery. Resolution:
+`ask.via ?? prompt.via ?? [prompt.model]`:
+
+```typescript
+export const triage = smart.prompt("ticket-triage", {
+  version: 1,
+  via: ["smart", "local"],
+  out: z.object({ category: z.string() }),
+});
+
+await fx.ask(triage, input, { via: ["local"] }); // call override
+```
+
+**Consequence:** each via step uses that binding’s own `apiKey` / `baseUrl`.
+
+</Tab>
+
+<Tab value="Budget">
+
+Per-call cost cap — exceeded throws `AiBudgetExceededError`:
+
+```typescript
+smart.prompt("ticket-triage", {
+  budget: { maxCostPerCall: 0.02 },
+});
+```
+
+`maxCostPerRun` on a prompt budget is reserved for multi-step asks; agents use
+`budget.maxCostPerRun` on `ai.agent`.
+
+</Tab>
+
+<Tab value="Tools">
+
+Offer Flows for one ask without declaring an agent:
+
+```typescript
+await fx.ask(
+  triage,
+  { message },
+  {
+    tools: ["docs.search", "tickets.create"],
+    maxSteps: 4,
+  },
+);
+```
+
+Default `maxSteps` is `6`. Tool names also stamp `effects.calls`.
+
+</Tab>
+
+</Tabs>
+
+## Options
+
+| Option    | Type                                  | Default          | Meaning                                                         |
+| --------- | ------------------------------------- | ---------------- | --------------------------------------------------------------- |
+| `version` | `number`                              | —                | Pin with `fx.ask("name@N")`                                     |
+| `evals`   | `string`                              | —                | Path for `oke eval` JSONL                                       |
+| `budget`  | `{ maxCostPerCall?, maxCostPerRun? }` | —                | Cost contracts                                                  |
+| `via`     | `string[]`                            | `[parent model]` | Recovery chain of logical names                                 |
+| `timeout` | `"30s"` \| ms                         | —                | Ask deadline (not a cost budget)                                |
+| `in`      | Schema                                | —                | Declared / Manifest / doctor — **not** runtime-validated on ask |
+| `out`     | Schema                                | —                | Runtime-validated (Zod / JSON Schema / field shorthand)         |
+
+## How input reaches the model
+
+There is **no** template string API. The runtime JSON-stringifies the ask input (redacting
+secrets), and when `out` is set appends:
+
+```text
+Reply with JSON only matching this schema: …
+```
+
+Pass the fields you need as the second argument to `fx.ask` — do not invent `template` /
+`{{message}}` options.
+
+## `fx.ask` options
+
+| Option     | Type      | Default          | Meaning                         |
+| ---------- | --------- | ---------------- | ------------------------------- |
+| `via`      | refs      | prompt chain     | Override recovery for this call |
+| `timeout`  | duration  | prompt `timeout` | Per-call deadline               |
+| `tools`    | Flow refs | —                | Tool loop via `fx.call`         |
+| `maxSteps` | `number`  | `6`              | Cap on tool rounds              |
+
+## Embeds (related)
+
+`ai.embed` is a separate declaration for vector pipelines into `store.index`:
+
+```typescript
+export const kb = ai.embed("kb", {
+  model: "smart",
+  into: "knowledge",
+});
+
+const vector = await fx.embed(smart, "install guide");
+const hits = await fx.search(kb, "how to install", { topK: 5 });
+```
+
+`fx.embed` records `embeds` (not `asks`). Missing `into` or a non-vector index fails at
+runtime with `ai: embed "…" has no into` / vector-index errors.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title='ai: unknown prompt "…"'>
+  The name was never registered with `model.prompt`, or the AI module was not imported before boot.
+</Accordion>
+
+<Accordion title="OKE1005 — UNDECLARED_ASK">
+  Cause: `Flow "{flow}" asks "{resource}" without declaring it.` Use the prompt handle in `do`
+  or list `effects: { asks: ["support.classify"] }`.
+</Accordion>
+
+<Accordion title='ai: schema validation failed for prompt "…"@N'>
+  `AiSchemaValidationError` — the model reply failed `out`. Message includes missing / extra / type
+  issues. There is no retry-with-corrections loop.
+</Accordion>
+
+<Accordion title='ai: prompt "…" exceeded maxCostPerCall'>
+  `AiBudgetExceededError` — raise `budget.maxCostPerCall` or reduce tokens / tool rounds.
+</Accordion>
+
+<Accordion title='ai: all models failed for prompt "…"'>
+  Every entry in the `via` chain failed (network, auth, or provider error). Check each binding’s
+  `apiKey` / `baseUrl` and driver health.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Models](/docs/elements/ai/models) — bindings and providers
+- [Agents](/docs/elements/ai/agents) — multi-step `fx.run`
+- [AI](/docs/elements/ai) — guardrails and PII egress
+- [OpenRouter](/docs/recipes/openrouter) — cloud ask recipe
+
+## Next
+
+<Cards>
+  <Card
+    title="Agents"
+    description="Bounded agents whose tools are Flows."
+    href="/docs/elements/ai/agents"
+  />
+  <Card
+    title="Models"
+    description="Provider registry and drivers."
+    href="/docs/elements/ai/models"
+  />
+  <Card title="AI" description="Element overview." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/elements/channel/email.mdx

@@ -0,0 +1,266 @@
+---
+title: "Email"
+description: "Transactional email — channel.email templates, {{field}} catalogs, SMTP/Mailpit, Resend, SNDR, and Taqnyat Mail."
+icon: "Mail"
+source: "docs/spec/unified-theory.md"
+---
+
+Email (`channel.email`) is the default Channel medium. Declare a binder with a From address,
+register templates, put bodies in the catalog, and send with `fx.send`.
+
+For developers who need local catchers and production HTTP MTAs — same `fx.send` path, swap the
+driver.
+
+<Callout title="The one rule">
+  Use `channel.email({ from }).template(name, { schema, locales })` — never
+  `channel.email("name", { subject, body })`. Subject and body live in the catalog.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Declare binder + template
+
+```typescript title="src/core/channel.ts"
+import { channel } from "okengine";
+import { z } from "zod";
+
+const mail = channel.email({ from: "App <noreply@example.com>" });
+
+export const passwordReset = mail.template("auth.resetPassword", {
+  description: "Password reset link",
+  locales: ["en"],
+  schema: z.object({ resetLink: z.string().url() }),
+});
+```
+
+</Step>
+
+<Step>
+### Catalog + send
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+
+oke({
+  name: "app",
+  channel: {
+    catalog: {
+      "auth.resetPassword": {
+        en: {
+          subject: "Reset your password",
+          text: "Open {{resetLink}} to choose a new password.",
+          html: '<p><a href="{{resetLink}}">Reset your password</a></p>',
+        },
+      },
+    },
+  },
+});
+```
+
+```typescript title="src/flows/auth/reset.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { passwordReset } from "@/core/channel";
+
+export const reset = on(
+  http.post().public(),
+  flow({
+    in: z.object({ email: z.string().email() }),
+    do: async ({ email }, fx) => {
+      await fx.send(passwordReset, {
+        to: email,
+        data: { resetLink: `https://example.com/reset?t=${fx.id()}` },
+      });
+      return { ok: true };
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Inspect locally
+
+With Mailpit (`images.channel.email` + `SMTP_URL`), open `MAILPIT_UI_URL`. Manifest lists
+`sends: ["auth.resetPassword"]` on the Flow.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Minimal", "Catalog", "Failover", "Plugin catalog"]}>
+
+<Tab value="Minimal">
+
+No catalog — runtime uses `subject: templateName` and `text: JSON.stringify(data)`:
+
+```typescript
+await fx.send(passwordReset, {
+  to: "alice@example.com",
+  data: { resetLink: "https://example.com/r/1" },
+});
+```
+
+</Tab>
+
+<Tab value="Catalog">
+
+Per-locale `subject` / `text` / `html` with `{{field}}` interpolation from `data`:
+
+```typescript
+catalog: {
+  "auth.resetPassword": {
+    en: { subject: "Reset", text: "{{resetLink}}", html: "<a href=\"{{resetLink}}\">Reset</a>" },
+    ar: { subject: "إعادة التعيين", text: "{{resetLink}}" },
+  },
+}
+```
+
+</Tab>
+
+<Tab value="Failover">
+
+Pin multiple email drivers in `oke({ channel: { drivers } })` or rely on the boot chain, then
+order them per send:
+
+```typescript
+await fx.send(passwordReset, {
+  to: "alice@example.com",
+  data: { resetLink: "…" },
+  via: ["smtp", "resend"],
+});
+```
+
+Receipt status `fallback` means an earlier attempt failed and a later one succeeded.
+
+</Tab>
+
+<Tab value="Plugin catalog">
+
+Official plugins contribute catalogs with `.channelCatalog(…)` (e.g. OTP, magic link). App
+`channel.catalog` merges with plugin contributions at boot.
+
+</Tab>
+
+</Tabs>
+
+## Options Reference
+
+### `channel.email(options?)`
+
+| Option   | Type     | Meaning               |
+| -------- | -------- | --------------------- |
+| `from`   | `string` | Default From / sender |
+| `sender` | `string` | Alias for `from`      |
+
+### `.template(name, options?)`
+
+| Option        | Type       | Meaning                     |
+| ------------- | ---------- | --------------------------- |
+| `description` | `string`   | Console label               |
+| `locales`     | `string[]` | Declared locales            |
+| `schema`      | Schema     | Payload contract for `data` |
+
+Default From when neither binder nor template sets one: `"oke@localhost.test"`.
+
+## Drivers
+
+| Driver id      | Opens at boot | Env / keys                                                                    |
+| -------------- | ------------- | ----------------------------------------------------------------------------- |
+| `smtp`         | yes (default) | `SMTP_URL` or `OKE_CHANNEL_EMAIL_URL`; optional `SMTP_USER` / `SMTP_PASSWORD` |
+| `console`      | yes (test)    | In-process inbox — no network                                                 |
+| `resend`       | yes           | `RESEND_API_KEY`                                                              |
+| `sndr`         | yes           | `SNDR_API_KEY`; optional `SNDR_BASE_URL`                                      |
+| `taqnyat-mail` | yes           | `TAQNYAT_MAIL_TOKEN` + `TAQNYAT_CAMPAIGN`                                     |
+
+```typescript title="oke.config.ts"
+drivers: {
+  channel: {
+    email: { dev: "smtp", test: "console", prod: "resend" },
+  },
+},
+images: {
+  channel: { email: "axllent/mailpit:v1.31.1" },
+},
+```
+
+**Consequence:** `dev` and `prod` both speak SMTP protocol by default — Mailpit locally, your
+relay in production. Swap `prod` to `resend` / `sndr` / `taqnyat-mail` when you want HTTP APIs.
+
+Unknown id → `oke boot: unknown email channel driver "…"`. Missing SMTP URL →
+`oke boot: smtp driver needs SMTP_URL`.
+
+## Locale & consent
+
+Locale chain and suppression run before the driver (see [Overview](/docs/elements/channel) and
+[Receipts](/docs/elements/channel/receipts)). Opted-out or prior hard-bounce addresses never
+reach SMTP / Resend.
+
+Channel catalogs are **not** ICU — do not use `fx.t` for email bodies ([i18n](/docs/reference/i18n)).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="oke boot: smtp driver needs SMTP_URL">
+  Pin Mailpit / set `SMTP_URL=smtp://…`. URL must use the `smtp://` scheme (`oke boot: SMTP_URL must
+  use smtp://`).
+</Accordion>
+
+<Accordion title="oke boot: resend channel needs RESEND_API_KEY">
+  Email driver is `resend` but the key is missing. Export `RESEND_API_KEY` for that env.
+</Accordion>
+
+<Accordion title="oke boot: sndr channel needs SNDR_API_KEY">
+  Same pattern for `sndr` — set `SNDR_API_KEY` (and `SNDR_BASE_URL` if non-default).
+</Accordion>
+
+<Accordion title="oke boot: taqnyat-mail channel needs TAQNYAT_MAIL_TOKEN / TAQNYAT_CAMPAIGN">
+  Taqnyat Email requires both the mail token and a campaign name.
+</Accordion>
+
+<Accordion title="Message in Mailpit has JSON body / template name as subject">
+  No catalog entry for that template + locale. Add `channel.catalog` (or a plugin catalog) with
+  `subject` / `text` / `html`.
+</Accordion>
+
+<Accordion title="suppressed/opted-out or prior-bounce — no provider call">
+  Consent or hard-bounce suppression blocked the send. Check the receipt ledger; see
+  [Receipts](/docs/elements/channel/receipts).
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Channel overview](/docs/elements/channel) — declare → send → drivers
+- [Mailpit](/docs/recipes/mailpit) — local SMTP catcher
+- [Receipts](/docs/elements/channel/receipts) — delivery ledger
+- [Environment variables](/docs/reference/environment-variables) — email boot binder
+- [OTP plugin](/docs/plugins/otp) — `auth-otp-email` catalog
+
+## Next
+
+<Cards>
+  <Card
+    title="SMS"
+    description="SMS templates and provider OTP."
+    href="/docs/elements/channel/sms"
+  />
+  <Card
+    title="Receipts"
+    description="Ledger, outcomes, and suppression."
+    href="/docs/elements/channel/receipts"
+  />
+  <Card
+    title="Channel Overview"
+    description="Physics, fx surface, and driver table."
+    href="/docs/elements/channel"
+  />
+</Cards>