create-theokit 1.4.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/default/agents/chat.ts

@@ -1,29 +1,31 @@
 import { agent } from '@theokit/agents'
+import { defineSkillReadTool } from '@theokit/sdk'
 import { z } from 'zod'
 
-import { BASE_INSTRUCTIONS } from './_lib/instructions.js'
-import { weatherTool } from './_tools/weather.js'
+import { BASE_INSTRUCTIONS } from './prompts/instructions.js'
+import { dailyBriefingSkill } from './skills/daily-briefing.js'
+import { currentTimeTool } from './tools/current-time.js'
+import { weatherTool } from './tools/weather.js'
 
 /**
- * Chat agent — the zero-config `agents/*.ts` convention.
+ * The `chat` agent — served at `POST /api/agents/chat` and bound by `useAgent('chat')`. This file IS the
+ * agent; it composes its neighbours under `agents/`: the persona in `prompts/`, capabilities in `tools/`,
+ * procedures in `skills/`. Those folders are that concern, NOT extra routes — the framework's scanner
+ * 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`. See
+ * `docs/ARCHITECTURE.md`.
  *
- * This one file is auto-served at `POST /api/agents/chat` (dev + build), streaming the
- * ai-sdk `UIMessageStream` that `useAgent('chat')` consumes on the client. No manual route,
- * no manual client wiring. `@theokit/sdk` runs it; conversation turns auto-persist per
- * session (the SDK owns storage).
- *
- * Provider: resolved from the environment — OPENROUTER_API_KEY (preferred — gateway to many
- * models) OR ANTHROPIC_API_KEY / OPENAI_API_KEY. The `model` id is prefixed with the provider
- * namespace so OpenRouter routes it upstream (see https://openrouter.ai/models).
- *
- * The agent is composed from its neighbours (see `docs/ARCHITECTURE.md`): the persona lives in
- * `agents/_lib/instructions.ts` and tools in `agents/_tools/` (both underscore-prefixed so the
- * route scanner skips them). Add a tool with `tool('name')…build()` and chain it via `.tool(...)`;
- * add a skill as `agents/skills/<name>.md`.
+ * `@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).
  */
 export default agent()
   .input(z.object({ message: z.string() }))
   .model('openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS)
   .tool(weatherTool)
+  .tool(currentTimeTool)
+  // `defineSkillReadTool` exposes the skills to the model as an on-demand `skill_read` tool — the model
+  // sees each skill's name + description and loads the full body only when it needs it.
+  .tool(defineSkillReadTool([dailyBriefingSkill]))
   .build()

package/templates/default/agents/prompts/instructions.ts

@@ -0,0 +1,21 @@
+/**
+ * The `chat` agent's system prompt (persona + rules). Lives in `prompts/` — a semantic sub-folder the
+ * framework's agent scanner skips, so it never becomes a route. Grow the persona here instead of inlining
+ * a long string in `index.ts`.
+ */
+export const BASE_INSTRUCTIONS = `You are a helpful assistant living inside a TheoKit app.
+
+## Voice
+- Answer clearly and concisely. Prefer a direct answer over a preamble.
+- If you are unsure, say so rather than inventing an answer.
+
+## Tools — call them, don't guess
+- **Current weather** for a place → call the \`weather\` tool.
+- **Current date / time** (optionally for a timezone) → call the \`current_time\` tool.
+- Never state a time or the weather from memory; always call the tool. If a tool errors, tell the user
+  what failed and what you need (e.g. a valid city or IANA timezone).
+
+## Skills
+- You have a \`skill_read\` tool that lists documented procedures (skills). When a request matches a
+  skill's description — e.g. the user asks for a "briefing" / "morning update" / "what's my day looking
+  like" (the **daily-briefing** skill) — call \`skill_read\` to load its steps, then follow them.`

package/templates/default/agents/skills/daily-briefing.ts

@@ -0,0 +1,31 @@
+import { createSkill } from '@theokit/sdk'
+
+/**
+ * A real, code-defined skill (`createSkill`) — a documented procedure the MODEL can pull in on demand.
+ *
+ * Unlike a loose Markdown note, this is wired into the agent: `agents/chat.ts` passes it to
+ * `defineSkillReadTool([...])`, which gives the model a `skill_read` tool. The model sees the skill's
+ * name + description in every turn (cheap) and calls `skill_read('daily-briefing')` to load the full
+ * `instructions` only when it actually needs them — so long procedures don't bloat every prompt.
+ *
+ * Lives in `agents/skills/` — a semantic folder the route scanner skips, so it never becomes an endpoint.
+ */
+export const dailyBriefingSkill = createSkill({
+  name: 'daily-briefing',
+  description:
+    "Produce a short 'good morning' briefing (today's date, the weather, and a one-line nudge).",
+  instructions: `# Daily briefing
+
+Trigger: the user asks for a "briefing", "morning update", or "what's my day looking like".
+
+Steps:
+1. Ask for (or reuse) the user's city and IANA timezone if you don't already have them.
+2. Call the \`current_time\` tool with their timezone → the local date and time.
+3. Call the \`weather\` tool with their city → the current conditions.
+4. Reply in exactly three lines:
+   - **Today** — weekday + date (from current_time).
+   - **Weather** — conditions + temperature (from weather).
+   - **Nudge** — one short, friendly suggestion based on the weather.
+
+Never invent the time or weather — always call the tools. Keep it to three lines unless asked for more.`,
+})

package/templates/default/agents/tools/current-time.ts

@@ -0,0 +1,35 @@
+import { tool } from 'theokit/server'
+import { z } from 'zod'
+
+/**
+ * A local, deterministic tool — the current date + time, optionally in an IANA timezone. No network,
+ * always works: the counterpart to `weather.ts` (which hits an HTTP API), so the scaffold shows both a
+ * remote-call tool and a pure local one. Imported into `chat.ts` and chained with `.tool(currentTimeTool)`.
+ */
+export const currentTimeTool = tool('current_time')
+  .describe('Get the current date and time, optionally for a specific IANA timezone.')
+  .input(
+    z.object({
+      timezone: z
+        .string()
+        .optional()
+        .describe('IANA timezone, e.g. "Europe/Lisbon" or "America/Sao_Paulo". Defaults to UTC.'),
+    }),
+  )
+  .execute(async ({ timezone }) => {
+    const tz = timezone ?? 'UTC'
+    try {
+      const formatted = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        dateStyle: 'full',
+        timeStyle: 'long',
+      }).format(new Date())
+      return `Current time (${tz}): ${formatted}`
+    } catch {
+      // fail-fast with a clear, actionable message (Rule 8) rather than a cryptic RangeError.
+      throw new Error(
+        `Unknown timezone "${tz}". Use an IANA name like "Europe/Lisbon" or "America/Sao_Paulo".`,
+      )
+    }
+  })
+  .build()

package/templates/default/agents/{_tools → tools}/weather.ts

@@ -5,8 +5,8 @@ import { z } from 'zod'
  * An example agent tool — current weather for a place, via the keyless open-meteo API.
  *
  * A tool is PURE metadata + a handler: it describes a capability and runs local/HTTP work; it NEVER calls
- * an LLM (the agent decides when to invoke it). Lives in `agents/_tools/` (underscore-prefixed) so the
- * route scanner skips it — it is imported into `agents/chat.ts` and chained with `.tool(weatherTool)`.
+ * an LLM (the agent decides when to invoke it). Lives in `tools/` — a semantic sub-folder the agent
+ * scanner skips — and is imported into `chat.ts` and chained with `.tool(weatherTool)`.
  *
  * Add your own the same way: `tool('name').describe(...).input(z.object({...})).execute(async (input) => …).build()`.
  */

package/templates/default/docs/ARCHITECTURE.md

@@ -1,20 +1,22 @@
 # Architecture
 
-How this TheoKit app is organized. The layout puts the **agent at the center** and keeps a clean split
-between the agent, the backend, the frontend, and cross-layer code.
+How this TheoKit app is organized. The layout puts the **agent at the center**: the agent file and the
+folders it composes (prompts, tools, skills) live together under `agents/`, with clean names — the
+"file = identity" convention agent frameworks like [Eve](https://eve.dev) use.
 
 ## Project structure
 
 ```
 .
-├── agents/                 # The agent lives here (auto-served at POST /api/agents/<name>)
-│   ├── chat.ts             #   the agent — composed from its neighbours below
-│   ├── _lib/               #   internal helpers (underscore = NOT a route)
-│   │   └── instructions.ts #     the system prompt / persona
-│   ├── _tools/             #   tools the agent can call (underscore = NOT a route)
-│   │   └── weather.ts      #     example: tool('weather')…build()
-│   └── skills/             #   Markdown procedures the agent (and you) can follow
-│       └── getting-started.md
+├── agents/                 # The agent, and what composes it
+│   ├── chat.ts             #   the agent → POST /api/agents/chat, useAgent('chat')
+│   ├── prompts/            #   system prompts / personas
+│   │   └── instructions.ts
+│   ├── tools/              #   tools the agent can call
+│   │   ├── weather.ts      #     remote — current weather via open-meteo (HTTP)
+│   │   └── current-time.ts #     local — date/time in an IANA timezone (no network)
+│   └── skills/             #   procedures the model loads on demand (createSkill)
+│       └── daily-briefing.ts    #   a real skill: time → weather → a one-line nudge
 ├── app/                    # Frontend (web surface). tui → tui/, desktop → frontend/
 ├── server/                 # Backend routes / actions (POST/GET handlers, jobs)
 ├── shared/                 # Code imported by more than one layer
@@ -24,13 +26,14 @@ between the agent, the backend, the frontend, and cross-layer code.
 └── theo.config.ts          # App config (name, dirs, plugins)
 ```
 
-## Why `_lib/` and `_tools/` have an underscore
+## Clean names, no phantom routes
 
-The framework turns **every `.ts` under `agents/` into a `POST /api/agents/<name>` endpoint** (that is the
-zero-config convention that lets `useAgent('chat')` bind with no manual wiring). Files that are *not*
-agents — the persona, the tools — would otherwise become phantom endpoints, so they live in
-underscore-prefixed folders, which the route scanner skips (the same convention Next.js uses for private
-folders). `skills/` needs no underscore because Markdown is never scanned.
+An agent is a file: `agents/<name>.ts` → `POST /api/agents/<name>`. But the framework's scanner is
+**folder-semantic** — the conventional sub-folders under `agents/` (`prompts/`, `tools/`, `skills/`,
+`lib/`, `hooks/`, `channels/`, `connections/`, `subagents/`, `schedules/`) are **that concern, not routes**.
+So the names stay clean (`tools/`, not `_tools/`) and `agents/tools/weather.ts` never becomes a phantom
+`/api/agents/tools/weather` endpoint. Markdown (`skills/*.md`) is never scanned either way. The
+prompts/tools/skills are **shared** across every agent in `agents/`.
 
 ## Composition
 
@@ -40,13 +43,18 @@ folders). `skills/` needs no underscore because Markdown is never scanned.
 export default agent()
   .input(z.object({ message: z.string() }))
   .model('openai/gpt-4o-mini')
-  .system(BASE_INSTRUCTIONS)   // agents/_lib/instructions.ts
-  .tool(weatherTool)           // agents/_tools/weather.ts
+  .system(BASE_INSTRUCTIONS)   // agents/prompts/instructions.ts
+  .tool(weatherTool)           // agents/tools/weather.ts
+  .tool(currentTimeTool)       // agents/tools/current-time.ts
+  .tool(defineSkillReadTool([dailyBriefingSkill]))  // agents/skills/daily-briefing.ts
   .build()
 ```
 
-Grow the agent by editing its neighbours, not by inflating `chat.ts`: persona → `_lib/instructions.ts`,
-a new capability → `_tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure → `skills/<name>.md`.
+Grow the agent by editing its neighbours, not by inflating `chat.ts`: persona → `prompts/instructions.ts`,
+a new capability → `tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure → a
+`createSkill(...)` in `skills/<name>.ts` (add it to the `defineSkillReadTool([...])` list). A **skill** is
+loaded by the model on demand via the `skill_read` tool, so long procedures don't bloat every prompt. Add a
+**second agent** as another `agents/<name>.ts`.
 
 ## Surfaces
 

package/templates/default/docs/CUSTOMIZATION.md

@@ -5,18 +5,18 @@ Common changes, and where they go. See [ARCHITECTURE](./ARCHITECTURE.md) for the
 | I want to… | Edit |
 |------------|------|
 | Change the model | `agents/chat.ts` (`.model(...)`) + the label in `shared/agent.ts` |
-| Change the persona / rules | `agents/_lib/instructions.ts` |
-| Add a tool (an action the agent can take) | new `agents/_tools/<name>.ts`, then `.tool(<name>Tool)` in `agents/chat.ts` |
-| Add a skill (a documented procedure) | new `agents/skills/<name>.md` |
-| Change the greeting / app name | `shared/agent.ts` |
+| Change the persona / rules | `agents/prompts/instructions.ts` |
+| Add a tool (an action the agent can take) | new `agents/tools/<name>.ts`, then `.tool(<name>Tool)` in `agents/chat.ts` |
+| Add a skill (a procedure the model loads on demand) | `createSkill(...)` in `agents/skills/<name>.ts`, then add it to `defineSkillReadTool([...])` in `agents/chat.ts` |
 | Add a second agent | new `agents/<name>.ts` → auto-served at `/api/agents/<name>`, bind with `useAgent('<name>')` |
+| Change the greeting / app name | `shared/agent.ts` |
 | Add a backend route | `server/routes/<name>.ts` |
 | Change the provider key | `.env` — `OPENROUTER_API_KEY` (or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`). See [ENVIRONMENT](./ENVIRONMENT.md) |
 
 ## Adding a tool
 
 ```ts
-// agents/_tools/echo.ts
+// agents/tools/echo.ts
 import { tool } from 'theokit/server'
 import { z } from 'zod'
 
@@ -29,7 +29,7 @@ export const echoTool = tool('echo')
 
 ```ts
 // agents/chat.ts
-import { echoTool } from './_tools/echo.js'
+import { echoTool } from './tools/echo.js'
 // …
   .tool(weatherTool)
   .tool(echoTool)   // chain as many as you need

package/templates/default/package.json.tmpl

@@ -15,9 +15,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.30.3",
+    "theokit": "^0.31.0",
     "@theokit/agents": "^0.35.2",
-    "@theokit/sdk": "^2.13.0",
+    "@theokit/sdk": "^2.25.0",
     "@theokit/ui": "^1.0.0",
     "@usetheo/ui": "^0.14.0",
     "ai": "^7.0.0",

package/templates/default/agents/_lib/instructions.ts

@@ -1,15 +0,0 @@
-/**
- * The agent's base system prompt.
- *
- * Kept in `agents/_lib/` (an underscore-prefixed folder) so the framework's `agents/*` route scanner
- * skips it — only real agents like `agents/chat.ts` become `POST /api/agents/<name>` endpoints. Import
- * this into an agent's `.system(...)`; grow it here (persona, guardrails, tool guidance) instead of
- * inlining a long string in the agent file.
- */
-import { AGENT } from '../../shared/agent.js'
-
-export const BASE_INSTRUCTIONS = `You are ${AGENT.name}, a helpful assistant living inside a TheoKit app.
-
-- Answer clearly and concisely.
-- When the user asks about current weather, call the \`weather\` tool instead of guessing.
-- If you are unsure, say so rather than inventing an answer.`

package/templates/default/agents/skills/getting-started.md

@@ -1,20 +0,0 @@
-# Getting started
-
-A **skill** is a Markdown file that documents a repeatable task for your agent — a recipe it (and you) can
-follow. Skills live in `agents/skills/` and are plain `.md`, so the route scanner ignores them; reference
-them from your instructions or load them into a prompt as your app grows.
-
-This example just documents the scaffold itself:
-
-## Answer a question
-
-1. Read the user's message.
-2. If it needs live weather, call the `weather` tool (see `agents/_tools/weather.ts`).
-3. Otherwise answer directly, concisely.
-
-## Add a capability
-
-- **A tool** (an action the agent can take) → `agents/_tools/<name>.ts`, then `.tool(<name>Tool)` in
-  `agents/chat.ts`.
-- **A skill** (a documented procedure) → a new `agents/skills/<name>.md` like this one.
-- **The persona / rules** → edit `agents/_lib/instructions.ts`.