create-theokit 0.1.0-alpha.12 → 0.1.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/api-only/README.md.tmpl

@@ -0,0 +1,78 @@
+# {{name}}
+
+TheoKit API-only project. Backend routes with Zod validation + typed responses — no frontend bundle, no React.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 1. Set your provider key if you wire an agent route later
+echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
+
+# 2. Boot the dev server
+npx theokit dev
+
+# 3. Probe the health route
+curl http://localhost:3000/api/health
+```
+
+You should see `{"status":"ok"}`. The server is now serving the routes under `server/routes/`.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** (this one) — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Route discovery** — every `server/routes/*.ts` becomes a wired endpoint.
+
+## Project structure
+
+```
+server/
+├── routes/
+│   ├── health.ts     GET  /api/health  — returns {status:"ok"}
+│   └── users.ts      CRUD /api/users   — Zod-validated body
+theo.config.ts        Framework config
+.env                  Secrets — never committed (.gitignore)
+```
+
+## Sample requests
+
+```bash
+# Health check
+curl http://localhost:3000/api/health
+
+# Create a user (POST with JSON body)
+curl -X POST http://localhost:3000/api/users \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice","email":"alice@example.com"}'
+
+# List users
+curl http://localhost:3000/api/users
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + structured logs |
+| `npx theokit build` | Production build → `.theo/` |
+| `npx theokit start` | Serve the production build |
+| `npx theokit routes` | List all routes detected |
+| `npm run typecheck` | TypeScript strict check (no emit) |
+
+## Add a new route
+
+Drop a `.ts` file in `server/routes/`. Use `defineRoute` from `theokit/server` for Zod-validated handlers, or export `GET`/`POST` directly.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/api-only/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.14",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -18,5 +18,10 @@
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/api-only/server/routes/webhooks/echo.ts

@@ -0,0 +1,34 @@
+import { defineWebhook } from 'theokit/server'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { z } from 'zod'
+
+/**
+ * Echo webhook — demonstrates `defineWebhook` HMAC-SHA256 pattern
+ * without depending on an external provider (Stripe, GitHub, etc.).
+ *
+ * Self-test:
+ *   SECRET=$(openssl rand -base64 32)
+ *   echo -n '{"message":"hi"}' | openssl dgst -sha256 -hmac "$SECRET"
+ *   curl -X POST localhost:3000/api/webhooks/echo \
+ *     -H "x-echo-signature: <hex from above>" \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"message":"hi"}'
+ */
+const ECHO_SECRET = process.env.ECHO_WEBHOOK_SECRET ?? ''
+
+export const POST = defineWebhook({
+  verify: ({ rawBody, headers }) => {
+    if (ECHO_SECRET === '') return false
+    const sig = headers.get('x-echo-signature') ?? ''
+    const expected = createHmac('sha256', ECHO_SECRET).update(rawBody).digest('hex')
+    try {
+      return timingSafeEqual(Buffer.from(sig, 'utf-8'), Buffer.from(expected, 'utf-8'))
+    } catch {
+      return false
+    }
+  },
+  inputSchema: z.object({ message: z.string() }),
+  handler: async ({ input }) => {
+    return Response.json({ echoed: input.message, timestamp: new Date().toISOString() })
+  },
+})

package/templates/dashboard/README.md.tmpl

@@ -0,0 +1,76 @@
+# {{name}}
+
+TheoKit dashboard project. Build the app your agent lives in — with nested layouts and a sidebar wired from day one.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 1. Set your provider key (OpenRouter recommended — one key, any model)
+echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
+
+# 2. Boot the dev server
+npx theokit dev
+```
+
+Open the printed URL. The default surface is a dashboard shell with sidebar nav + content area, ready to host your agent panels.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** (this one) — nested layouts + sidebar nav.
+- **api-only** — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Tailwind + `@usetheo/ui` styling** auto-configured for the TheoUI surface.
+
+## Project structure
+
+```
+app/                  Frontend (file-based routing with nested layouts)
+├── layout.tsx        root wrapper — TheoUI provider + theme
+├── page.tsx          /              — dashboard home
+├── dashboard/
+│   ├── layout.tsx    /dashboard/*   — sidebar shell
+│   └── page.tsx      /dashboard     — primary panel
+server/               Backend (explicit routes)
+├── routes/
+│   └── health.ts     GET /api/health
+theo.config.ts        Framework config
+tailwind.config.ts    Tailwind theme tokens
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + devtools overlay |
+| `npx theokit build` | Production build → `.theo/` |
+| `npx theokit start` | Serve the production build |
+| `npx theokit check` | Lint for upgrade-readiness |
+| `npx theokit routes` | List all routes + actions detected |
+| `npm run typecheck` | TypeScript strict check (no emit) |
+
+## Add a new panel
+
+```bash
+mkdir -p app/dashboard/billing
+cat > app/dashboard/billing/page.tsx <<'EOF'
+export default function BillingPage() {
+  return <h2>Billing</h2>
+}
+EOF
+```
+
+The route appears at `/dashboard/billing` after HMR.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/dashboard/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.14",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -18,5 +18,10 @@
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/dashboard/server/crons/cleanup-conversations.ts

@@ -0,0 +1,51 @@
+import { defineCron } from 'theokit/server/cron'
+import { readdir, stat, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+/**
+ * Daily GC of stale conversation transcripts.
+ *
+ * The `@usetheo/sdk` Agent persists chat history under
+ * `.theokit/agents/<agentId>/messages.jsonl`. With no TTL the directory
+ * grows unbounded — production foot-gun. This cron removes any agent
+ * directory whose `messages.jsonl` hasn't been touched in 30 days.
+ */
+const MAX_AGE_DAYS = 30
+const AGENTS_DIR = '.theokit/agents'
+
+export default defineCron({
+  name: 'cleanup-conversations',
+  schedule: '0 4 * * *', // Daily 04:00 UTC
+  handler: async ({ log }) => {
+    const root = resolve(process.cwd(), AGENTS_DIR)
+    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
+    let removed = 0
+    let kept = 0
+    let entries: Awaited<ReturnType<typeof readdir>>
+    try {
+      entries = await readdir(root, { withFileTypes: true })
+    } catch {
+      log.info({ msg: 'No agents dir yet — first run', dir: root })
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const agentDir = join(root, entry.name)
+      const messagesFile = join(agentDir, 'messages.jsonl')
+      try {
+        const s = await stat(messagesFile)
+        if (s.mtimeMs < cutoff) {
+          await rm(agentDir, { recursive: true, force: true })
+          removed++
+        } else {
+          kept++
+        }
+      } catch {
+        // messages.jsonl missing → orphan dir, remove
+        await rm(agentDir, { recursive: true, force: true }).catch(() => {})
+        removed++
+      }
+    }
+    log.info({ msg: 'cleanup-conversations complete', removed, kept, maxAgeDays: MAX_AGE_DAYS })
+  },
+})

package/templates/default/README.md.tmpl

@@ -2,6 +2,8 @@
 
 TheoKit project. Build the app your agent lives in — routing, auth, real-time, deploy — wired.
 
+> 📚 **Full docs:** https://docs.theokit.dev
+
 ## Quick start
 
 ```bash

package/templates/default/package.json.tmpl

@@ -10,7 +10,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.14",
     "@usetheo/sdk": "^1.2.0",
     "@usetheo/ui": "^0.12.0-next.0",
     "lucide-react": "^0.469.0",
@@ -25,5 +25,10 @@
     "@types/react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/default/server/crons/cleanup-conversations.ts

@@ -0,0 +1,51 @@
+import { defineCron } from 'theokit/server/cron'
+import { readdir, stat, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+/**
+ * Daily GC of stale conversation transcripts.
+ *
+ * The `@usetheo/sdk` Agent persists chat history under
+ * `.theokit/agents/<agentId>/messages.jsonl`. With no TTL the directory
+ * grows unbounded — production foot-gun. This cron removes any agent
+ * directory whose `messages.jsonl` hasn't been touched in 30 days.
+ */
+const MAX_AGE_DAYS = 30
+const AGENTS_DIR = '.theokit/agents'
+
+export default defineCron({
+  name: 'cleanup-conversations',
+  schedule: '0 4 * * *', // Daily 04:00 UTC
+  handler: async ({ log }) => {
+    const root = resolve(process.cwd(), AGENTS_DIR)
+    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
+    let removed = 0
+    let kept = 0
+    let entries: Awaited<ReturnType<typeof readdir>>
+    try {
+      entries = await readdir(root, { withFileTypes: true })
+    } catch {
+      log.info({ msg: 'No agents dir yet — first run', dir: root })
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const agentDir = join(root, entry.name)
+      const messagesFile = join(agentDir, 'messages.jsonl')
+      try {
+        const s = await stat(messagesFile)
+        if (s.mtimeMs < cutoff) {
+          await rm(agentDir, { recursive: true, force: true })
+          removed++
+        } else {
+          kept++
+        }
+      } catch {
+        // messages.jsonl missing → orphan dir, remove
+        await rm(agentDir, { recursive: true, force: true }).catch(() => {})
+        removed++
+      }
+    }
+    log.info({ msg: 'cleanup-conversations complete', removed, kept, maxAgeDays: MAX_AGE_DAYS })
+  },
+})

package/templates/postgres/README.md.tmpl

@@ -0,0 +1,83 @@
+# {{name}}
+
+TheoKit project with Postgres + Drizzle ORM wired. Schema-first, migration-aware, typed end-to-end.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 0. Provision Postgres
+#    Option A — local docker (one-liner):
+docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
+#    Option B — hosted: neon.tech, supabase.com, fly.io
+
+# 1. Set env
+cat > .env <<'EOF'
+DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
+OPENROUTER_API_KEY=sk-or-v1-...
+EOF
+
+# 2. Generate + apply migrations
+pnpm db:generate
+pnpm db:migrate
+
+# 3. Boot the dev server
+npx theokit dev
+```
+
+Open the printed URL. The default surface includes a sample users API backed by Postgres.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** — server routes without React.
+- **postgres** (this one) — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. `DATABASE_URL` must be set before `pnpm db:migrate`.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Drizzle schema** under `db/schema.ts` drives migrations + typed query builder.
+
+## Project structure
+
+```
+app/                  Frontend
+├── page.tsx          /              — sample UI
+server/
+├── routes/
+│   ├── health.ts     GET  /api/health
+│   └── users.ts      CRUD /api/users  — backed by db.users
+db/
+├── schema.ts         Drizzle schema (tables + relations)
+├── client.ts         Drizzle client (used by routes)
+└── migrations/       Generated SQL files (committed)
+drizzle.config.ts     Drizzle CLI config
+theo.config.ts        Framework config
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR |
+| `npx theokit build` | Production build |
+| `npx theokit start` | Serve production build |
+| `pnpm db:generate` | Generate SQL migration from `db/schema.ts` |
+| `pnpm db:migrate` | Apply pending migrations to `DATABASE_URL` |
+| `pnpm db:studio` | Open Drizzle Studio UI |
+| `npm run typecheck` | TypeScript strict check |
+
+## Troubleshooting
+
+- **`pnpm db:migrate` fails with "ECONNREFUSED"** → check `DATABASE_URL` host:port + Postgres is running (`docker ps` or hosted dashboard).
+- **`relation "users" does not exist`** → you forgot `pnpm db:migrate`. Run it.
+- **Schema change not reflected** → `pnpm db:generate` first, then `pnpm db:migrate`.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/postgres/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.14",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "drizzle-orm": "^0.45.0",
@@ -26,5 +26,10 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "drizzle-kit": "^0.31.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/postgres/server/jobs/log-message.ts

@@ -0,0 +1,27 @@
+import { defineJob } from 'theokit/server/jobs'
+import { z } from 'zod'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { resolve, dirname } from 'node:path'
+
+/**
+ * Background job demonstrating `defineJob` + `ctx.queue.enqueue` pattern.
+ *
+ * Triggered from `server/routes/users.ts` POST handler via:
+ *   await ctx.queue.enqueue('log-message', { userId, message })
+ *
+ * Per ADR-0003 (transactional outbox), enqueue is deferred until the
+ * route handler commits successfully — handler throws → 0 jobs dispatched.
+ */
+export default defineJob({
+  name: 'log-message',
+  input: z.object({ userId: z.string(), message: z.string() }),
+  handler: async ({ input, log }) => {
+    // v1.1 EC-9: anchor path to process.cwd() — handler CWD may differ from
+    // project root when running via external job runner.
+    const auditPath = resolve(process.cwd(), '.theo/audit.log')
+    await mkdir(dirname(auditPath), { recursive: true })
+    const line = `${new Date().toISOString()} user=${input.userId} msg=${input.message}\n`
+    await appendFile(auditPath, line)
+    log.info({ msg: 'audit logged', userId: input.userId, path: auditPath })
+  },
+})

package/templates/saas/README.md.tmpl

@@ -0,0 +1,103 @@
+# {{name}}
+
+TheoKit SaaS template — auth, sessions, billing-ready, and an agent route. The full stack for shipping an account-aware product on day one.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 0. Provision Postgres (sessions + users)
+docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
+# Or use a hosted Postgres (neon.tech / supabase.com)
+
+# 1. Set env (generate a strong session secret)
+cat > .env <<EOF
+DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
+SESSION_SECRET=$(openssl rand -base64 32)
+OPENROUTER_API_KEY=sk-or-v1-...
+EOF
+
+# 2. Migrate the schema
+pnpm db:generate
+pnpm db:migrate
+
+# 3. Boot the dev server
+npx theokit dev
+```
+
+## Sample auth flow
+
+```bash
+# Register
+curl -X POST http://localhost:3000/api/register \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"alice@example.com","password":"strong-passphrase"}'
+
+# Login (saves session cookie)
+curl -X POST http://localhost:3000/api/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"alice@example.com","password":"strong-passphrase"}' \
+  -c cookies.txt
+
+# Authenticated request
+curl http://localhost:3000/api/me -b cookies.txt
+```
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** (this one) — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. `SESSION_SECRET`, `DATABASE_URL`, `OPENROUTER_API_KEY` all required.
+- **Encrypted sessions** (AES-256-GCM) via `SESSION_SECRET`.
+- **`.theo/` build output cleanup** on every `theokit build`.
+
+## Project structure
+
+```
+app/                  Frontend
+├── page.tsx          /            — landing
+server/
+├── routes/
+│   ├── login.ts      POST /api/login    — sets session cookie
+│   ├── logout.ts     POST /api/logout   — clears session
+│   ├── me.ts         GET  /api/me       — requireAuth() guarded
+│   └── agent.ts      POST /api/agent    — agent SSE, requireAuth()
+db/
+├── schema.ts         users + sessions tables (Drizzle)
+└── migrations/       generated SQL (committed)
+drizzle.config.ts     Drizzle config
+theo.config.ts        Framework config
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + auth |
+| `npx theokit build` | Production build |
+| `npx theokit start` | Serve production build |
+| `pnpm db:generate` | Generate SQL migration |
+| `pnpm db:migrate` | Apply migrations |
+| `npm run typecheck` | TypeScript strict check |
+
+## Adding billing
+
+Stripe is the canonical path — add `STRIPE_SECRET_KEY` to `.env`, mount `server/routes/billing/webhook.ts` via `defineWebhook`, and wire plan checks into `requireAuth()`.
+
+## Troubleshooting
+
+- **`SESSION_SECRET must be at least 32 bytes`** → regenerate with `openssl rand -base64 32`.
+- **`relation "users" does not exist`** → run `pnpm db:migrate` first.
+- **`401 Unauthorized` on `/api/me`** → login first; cookie must be sent (`-b cookies.txt`).
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/saas/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.12",
+    "theokit": "^0.1.0-alpha.14",
     "@usetheo/ui": "^0.12.0-next.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -28,5 +28,10 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "drizzle-kit": "^0.31.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/saas/server/routes/agent.ts

@@ -1,10 +1,20 @@
 import { defineAgentEndpoint, requireAuth, type AgentEvent } from 'theokit/server'
+import { trackAgentRun } from 'theokit/server/cost'
 import type { RequestContext } from '../context.js'
 
 /**
  * Protected agent endpoint. `requireAuth` fires BEFORE the stream starts;
  * unauthorized requests get 401 immediately — no SSE bytes leak.
  *
+ * Observability: wraps the run with `trackAgentRun` to surface per-user
+ * cost + token usage to the configured `UsageStorageAdapter` (configure via
+ * `theo.config.ts > cost.storage`). Also feeds the devtools `Agents` tab
+ * (when running in dev).
+ *
+ * NOTE: `costUsd: 0` is a v1 stub. Pricing table integration is a
+ * `@usetheo/sdk` follow-up (R0.5.11). Devtools tab renders "$0.0000" —
+ * indicates "cost tracking not yet calibrated for this model".
+ *
  * Replace the mock generator with your LLM provider call.
  */
 export const POST = defineAgentEndpoint<{ message: string }, RequestContext>({
@@ -12,10 +22,28 @@ export const POST = defineAgentEndpoint<{ message: string }, RequestContext>({
     requireAuth(ctx.session)
     const body = (await request.json()) as { message?: string }
     const msg = body.message ?? ''
-    yield {
-      type: 'message',
-      content: `Hello ${ctx.session.email}, you said: "${msg}"`,
+    try {
+      yield {
+        type: 'message',
+        content: `Hello ${ctx.session.email}, you said: "${msg}"`,
+      }
+      yield { type: 'message', content: '(Replace this mock with your LLM.)' }
+    } finally {
+      // Always emit observability — even on stream error / abort.
+      // `storage` resolved from theo.config.ts > cost.storage (undefined =
+      // no-op; configure to enable persistence + devtools tab visibility).
+      // To enable persistent cost tracking: wire `cost: { storage }` into
+      // `theo.config.ts` and forward via context. Demo passes `undefined`
+      // (no-op storage; still fires devtools dispatcher in dev mode).
+      await trackAgentRun(
+        {
+          userId: ctx.session.email,
+          model: 'mock/echo',
+          tokens: { input: msg.length, output: 0 }, // crude — real impl uses tokenizer
+          costUsd: 0, // v1 stub
+        },
+        { storage: undefined },
+      )
     }
-    yield { type: 'message', content: '(Replace this mock with your LLM.)' }
   },
 })

package/templates/saas/server/routes/billing/stripe-webhook.ts

@@ -0,0 +1,49 @@
+import { defineWebhook } from 'theokit/server'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { z } from 'zod'
+
+/**
+ * Stripe webhook receiver.
+ *
+ * Verifies `Stripe-Signature` header per Stripe's documented HMAC-SHA256
+ * scheme (https://stripe.com/docs/webhooks/signatures). Real impl would
+ * handle `checkout.session.completed`, `invoice.paid`, etc.
+ *
+ * Setup:
+ *   1. Create webhook endpoint in Stripe Dashboard pointing to /api/billing/stripe-webhook
+ *   2. Copy signing secret → `.env` STRIPE_WEBHOOK_SECRET
+ *   3. Test locally: `stripe listen --forward-to localhost:3000/api/billing/stripe-webhook`
+ */
+const STRIPE_SECRET = process.env.STRIPE_WEBHOOK_SECRET ?? ''
+
+export const POST = defineWebhook({
+  verify: ({ rawBody, headers }) => {
+    if (STRIPE_SECRET === '') return false
+    const sigHeader = headers.get('stripe-signature') ?? ''
+    // Stripe format: `t=<unix-ts>,v1=<hash>` (potentially also v0)
+    const parts: Record<string, string> = {}
+    for (const pair of sigHeader.split(',')) {
+      const [k, v] = pair.split('=')
+      if (k && v) parts[k.trim()] = v.trim()
+    }
+    const t = parts['t']
+    const v1 = parts['v1']
+    if (!t || !v1) return false
+    const signedPayload = `${t}.${rawBody}`
+    const expected = createHmac('sha256', STRIPE_SECRET).update(signedPayload).digest('hex')
+    try {
+      return timingSafeEqual(Buffer.from(v1, 'utf-8'), Buffer.from(expected, 'utf-8'))
+    } catch {
+      return false
+    }
+  },
+  inputSchema: z.object({ type: z.string(), data: z.unknown() }),
+  handler: async ({ input, log }) => {
+    log.info({ msg: 'stripe webhook received', type: input.type })
+    // TODO: dispatch by input.type:
+    //   - 'checkout.session.completed' → activate subscription
+    //   - 'invoice.paid' → extend access
+    //   - 'invoice.payment_failed' → notify user + retry plan
+    return Response.json({ received: true })
+  },
+})