create-theokit 1.25.0 → 1.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.25.0",
+  "version": "1.25.1",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "repository": {

package/templates/_bot-preset/agents/publisher.ts

@@ -20,7 +20,7 @@ export const policy = 'public'
 
 export default AgentBuilder.create()
   .input(z.object({ instruction: z.string() }))
-  .model(process.env.LLM_MODEL ?? 'openai/gpt-4o-mini')
+  .model(process.env.LLM_MODEL ?? 'openrouter/openai/gpt-4o-mini')
   .system(
     'You turn research notes into published output. Read notes with read_notes, then publish. ' +
       'Publishing is gated: a human approves it before it happens.',

package/templates/_bot-preset/agents/researcher.ts

@@ -19,7 +19,7 @@ export const policy = 'public'
 
 export default AgentBuilder.create()
   .input(z.object({ topic: z.string() }))
-  .model(process.env.LLM_MODEL ?? 'openai/gpt-4o-mini')
+  .model(process.env.LLM_MODEL ?? 'openrouter/openai/gpt-4o-mini')
   .system(
     'You research a topic and leave notes for the publisher bot. ' +
       'Write what you find with write_note; read what you already know with read_notes. ' +

package/templates/default/.env.example

@@ -2,4 +2,4 @@
 OPENROUTER_API_KEY=sk-or-v1-your-key-here
 
 # Optional: override the model declared in agents/chat.ts
-# LLM_MODEL=openai/gpt-4o-mini
+# LLM_MODEL=openrouter/openai/gpt-4o-mini

package/templates/default/README.md.tmpl

@@ -56,7 +56,7 @@ your environment.
   ```ts
   export default AgentBuilder.create()
     .input(z.object({ message: z.string() }))
-    .model('openai/gpt-4o-mini')
+    .model('openrouter/openai/gpt-4o-mini')
     .system(BASE_INSTRUCTIONS)
     .tool(weatherTool)
     .approval('send_notification', { question: 'Send this notification?' })

package/templates/default/agents/chat.ts

@@ -14,9 +14,17 @@ import { weatherTool } from './tools/weather.js'
  * treats `prompts/ tools/ skills/ lib/ …` as semantic folders, so `agents/tools/weather.ts` never becomes
  * a `/api/agents/tools/weather` endpoint. Add a second agent as another `agents/<name>.ts`.
  *
- * `@theokit/sdk` runs the agent; conversation turns auto-persist per session. Provider is resolved from
- * the environment — OPENROUTER_API_KEY (preferred) OR ANTHROPIC_API_KEY / OPENAI_API_KEY; the model id is
- * provider-prefixed so OpenRouter routes it upstream (https://openrouter.ai/models).
+ * `@theokit/sdk` runs the agent; conversation turns auto-persist per session.
+ *
+ * The FIRST segment of the model id picks the provider, and the key it needs follows from that:
+ * `openrouter/…` needs `OPENROUTER_API_KEY`, `anthropic/…` needs `ANTHROPIC_API_KEY`, `openai/…`
+ * needs `OPENAI_API_KEY`. There is no magic routing — a bare `openai/gpt-4o-mini` goes to OpenAI,
+ * not through a gateway, even with an OpenRouter key present. Reaching OpenAI's catalog THROUGH
+ * OpenRouter means naming the gateway: `openrouter/openai/gpt-4o-mini`, which is what this file
+ * declares, because `.env.example` asks for `OPENROUTER_API_KEY` (one key, many models —
+ * https://openrouter.ai/models).
+ *
+ * Change the id and the key changes with it. Both live in `.env` and here; nothing else to wire.
  */
 /**
  * Who may run this agent, and against which conversation (ADR 0001).
@@ -48,7 +56,7 @@ export default AgentBuilder.create()
   // so setting it changed the model to exactly what it already was (#398, #408). One expression is
   // cheaper than an override path through the framework, and it keeps the value visible in the file
   // that decides it. The literal stays as the fallback: a scaffold has to run with no environment.
-  .model(process.env.LLM_MODEL ?? 'openai/gpt-4o-mini')
+  .model(process.env.LLM_MODEL ?? 'openrouter/openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS)
   .tool(weatherTool)
   .tool(currentTimeTool)

package/templates/default/docs/ARCHITECTURE.md

@@ -59,7 +59,7 @@ An agent that outgrows one file becomes a folder that co-locates its own composi
 ```ts
 export default AgentBuilder.create()
   .input(z.object({ message: z.string() }))
-  .model('openai/gpt-4o-mini')
+  .model('openrouter/openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS) // agents/prompts/instructions.ts
   .tool(weatherTool) // agents/tools/weather.ts
   .tool(currentTimeTool) // agents/tools/current-time.ts

package/templates/default/docs/ENVIRONMENT.md

@@ -8,9 +8,17 @@ Configuration lives in `.env` (copy `.env.example`). Nothing here is committed
 | `ANTHROPIC_API_KEY`  | one of these | Use Anthropic directly instead of OpenRouter.                                 |
 | `OPENAI_API_KEY`     | one of these | Use OpenAI directly.                                                          |
 
-The agent resolves the key from the environment at runtime (OpenRouter preferred). The model id in
-`agents/chat.ts` is provider-prefixed (e.g. `openai/gpt-4o-mini`) so OpenRouter routes it upstream — see
-<https://openrouter.ai/models>.
+The FIRST segment of the model id in `agents/chat.ts` picks the provider, and that decides which key
+is needed. It is not a hint: `openai/gpt-4o-mini` goes to OpenAI and needs `OPENAI_API_KEY`, even
+with an OpenRouter key present. Reaching another vendor's catalog THROUGH OpenRouter means naming
+the gateway first — `openrouter/openai/gpt-4o-mini`, which is what the scaffold declares, matching
+the key above. See <https://openrouter.ai/models> for the ids OpenRouter serves.
+
+| Model id in `agents/chat.ts`    | Key it needs         |
+| ------------------------------- | -------------------- |
+| `openrouter/openai/gpt-4o-mini` | `OPENROUTER_API_KEY` |
+| `anthropic/claude-sonnet-4-6`   | `ANTHROPIC_API_KEY`  |
+| `openai/gpt-4o-mini`            | `OPENAI_API_KEY`     |
 
 ```bash
 cp .env.example .env

package/templates/default/dot-claude/skills/theokit-agents/SKILL.md

@@ -25,7 +25,7 @@ import { z } from 'zod'
 
 export default defineAgent({
   input: z.object({ message: z.string() }),
-  model: 'openai/gpt-4o-mini',
+  model: 'openrouter/openai/gpt-4o-mini',
   system: 'You are a helpful assistant.',
 })
 ```
@@ -33,8 +33,11 @@ export default defineAgent({
 The endpoint streams the ai-sdk `UIMessageStream` that `useAgent` (client hook) consumes.
 `@theokit/sdk` runs the agent; conversation turns auto-persist per session — the SDK owns storage.
 
-**Provider resolution:** `OPENROUTER_API_KEY` (preferred — routes to many models) OR
-`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`. Set one in `.env`.
+**Provider resolution:** the FIRST segment of the model id picks the provider, and that decides
+which key is needed — `openrouter/…` needs `OPENROUTER_API_KEY`, `anthropic/…` needs
+`ANTHROPIC_API_KEY`, `openai/…` needs `OPENAI_API_KEY`. A bare vendor prefix is a selection of that
+vendor, not a hint: reaching OpenAI's catalog through OpenRouter means naming the gateway first
+(`openrouter/openai/gpt-4o-mini`). Set the matching key in `.env`.
 
 ## Advanced Surface — @Agent Decorator (DI / class-based)
 
@@ -46,7 +49,7 @@ When you need dependency injection or composition, build the agent from **capabi
 import { applyCapabilities, AgentConfigCapability, ModelCapability } from '@theokit/agents'
 
 export const assistantAgent = applyCapabilities([
-  new ModelCapability('openai/gpt-4o-mini'),
+  new ModelCapability('openrouter/openai/gpt-4o-mini'),
   new AgentConfigCapability({
     systemPrompt: 'You are a helpful assistant.',
     maxIterations: 5,
@@ -75,7 +78,7 @@ const currentTimeTool = defineAgentTool({
 
 export default defineAgent({
   input: z.object({ message: z.string() }),
-  model: 'openai/gpt-4o-mini',
+  model: 'openrouter/openai/gpt-4o-mini',
   system: 'You are a helpful assistant.',
   tools: [currentTimeTool],
 })

package/templates/default/dot-claude/skills/theokit-gateways/SKILL.md

@@ -26,7 +26,7 @@ returns the `Response` your route must return.
 
 ```typescript
 import { handleChannelWebhook } from 'theokit/server/agent'
-import { telegram } from 'theokit/server/webhook' // also: discord, slack, github, stripe
+import { telegram } from 'theokit/server/webhook' // also: discord, slack, github, stripe, whatsapp
 import { parseInbound } from '@theokit/gateway-telegram'
 
 const response = await handleChannelWebhook(request, new URL(request.url).pathname, {
@@ -42,6 +42,34 @@ const response = await handleChannelWebhook(request, new URL(request.url).pathna
 The path it expects is `POST /api/agents/<name>/channels/<platform>/webhook`; `<name>` and
 `<platform>` arrive in `onMessage` as `agent` and `platform`.
 
+## Platforms that verify the endpoint first (WhatsApp, Instagram, Messenger)
+
+Meta will not deliver anything until it has verified the URL with a `GET` carrying
+`hub.mode=subscribe`, `hub.verify_token` and `hub.challenge`, and it requires the challenge echoed
+back as `text/plain`. Declare a responder per platform and mount the route for `GET` as well as
+`POST`:
+
+```typescript
+import { whatsapp, whatsappSubscribe } from 'theokit/server/webhook'
+
+const response = await handleChannelWebhook(request, new URL(request.url).pathname, {
+  validators: { whatsapp: whatsapp({ appSecret: process.env.META_APP_SECRET! }) },
+  subscribe: { whatsapp: whatsappSubscribe({ verifyToken: process.env.META_VERIFY_TOKEN! }) },
+  onMessage: async ({ payload }) => {
+    /* … */
+  },
+})
+```
+
+`appSecret` is the Meta **app secret**, not the access token — the signature is HMAC-SHA256 of it
+over the raw body. `verifyToken` is the string you typed into the Meta app when registering the URL;
+comparing it is the only thing standing between an arbitrary caller and a subscription. A `GET` for
+a platform with no `subscribe` entry answers `405`, not `404`: the platform is configured, it just
+does not do handshakes.
+
+Developing against any of this needs a public URL. `theo.config.ts` has `allowedHosts` for exactly
+that — see the framework README.
+
 **Give it a `Request` whose body has not been read.** It calls `request.json()` itself, so a wrapper
 that has already parsed the body — `defineRoute` offers a parsed `body` in its handler context —
 leaves nothing for it to read. Mount it where you still hold the original request, or pass a clone.

package/templates/default/package.json.tmpl

@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.56.0",
+    "theokit": "^0.60.0",
     "@theokit/agents": "^10.1.0",
     "@theokit/sdk": "^4.52.1",
     "@theokit/ui": "^1.1.0",