create-theokit 1.0.10 → 1.0.11

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: theokit-agents
-description: TheoKit agent/LLM integration — @Agent, @Tool, @Toolbox decorators, streaming, memory
+description: TheoKit agent/LLM integration — two streaming surfaces (decorator vs manual), @Tool, @Toolbox, memory
 user-invocable: false
 paths:
   - "**/*agent*"
@@ -13,31 +13,51 @@ paths:
 
 # TheoKit Agents & Tools
 
-## @Agent Decorator
+## Two Streaming Surfaces — pick one per endpoint
+
+TheoKit ships two ways to create agent endpoints. Use ONE per endpoint, not both.
+
+| Surface | Server | Events | Client | When to use |
+|---------|--------|--------|--------|-------------|
+| **Manual** (recommended for most apps) | `defineAgentEndpoint({ handler: async function* })` | `AgentEvent` (Message, ToolCall, Result, Error) | `useAgentStream()` / `consumeAgentStream()` | Full control over the LLM loop — you write the generator |
+| **Decorator** (`@theokit/agents`) | `@Agent` class → auto-generated route | `AgentStreamEvent` (TextDelta, ToolCall, Done...) | (same client hooks work) | Declarative — framework manages LLM loop via `@MainLoop` |
+
+### Surface 1: Manual (defineAgentEndpoint)
 
 ```typescript
-import { Agent, MainLoop, Hook, Memory, Budget } from '@theokit/agents'
+// server/routes/agents/assistant.ts
+import { defineAgentEndpoint } from 'theokit/server/define'
+import type { AgentEvent } from 'theokit'
+
+export const POST = defineAgentEndpoint({
+  handler: async function* ({ body }): AsyncGenerator<AgentEvent> {
+    // You control the LLM loop
+    yield { type: 'message', content: 'Thinking...' }
+    const result = await callLLM(body.message)
+    yield { type: 'message', content: result }
+  },
+})
+```
+
+### Surface 2: Decorator (@Agent)
+
+```typescript
+// server/agents/assistant.agent.ts
+import { Agent, MainLoop, Tool, Toolbox } from '@theokit/agents'
 
 @Agent({
-  model: 'openai/gpt-4o-mini',     // Required: LLM model
-  systemPrompt: 'You are a helpful task assistant.',
+  model: 'openai/gpt-4o-mini',
+  systemPrompt: 'You are a helpful assistant.',
 })
-@Memory({ provider: 'built-in', scope: 'per-user' })  // Optional
-@Budget({ maxCostUsd: 1.00, window: 'daily' })         // Optional
 export class AssistantAgent {
   @MainLoop({ strategy: 'react', maxIterations: 5 })
   async run() {
-    // Framework handles the LLM loop
-  }
-
-  @Hook('before:llm-call')
-  async onBeforeLLM(ctx) {
-    // Intercept before each LLM call
+    // Framework handles the LLM loop via @theokit/sdk
   }
 }
 ```
 
-Convention: `AssistantAgent` class name maps to `GET/POST /api/agents/assistant`.
+Convention: `AssistantAgent` → `POST /api/agents/assistant`
 
 ## @Tool Decorator
 
@@ -50,56 +70,63 @@ export class TaskTools {
   @Tool({
     name: 'list_tasks',
     description: 'List all tasks, optionally filtered by status',
-    input: z.object({
-      done: z.boolean().optional(),
-    }),
+    input: z.object({ done: z.boolean().optional() }),
   })
   async listTasks({ done }: { done?: boolean }) {
-    const all = db.select().from(tasks).all()
-    return done !== undefined ? all.filter(t => t.done === done) : all
-  }
-
-  @Tool({
-    name: 'create_task',
-    description: 'Create a new task with a title',
-    input: z.object({
-      title: z.string().min(1),
-    }),
-  })
-  async createTask({ title }: { title: string }) {
-    return db.insert(tasks).values({ title }).returning().get()
+    return db.select().from(tasks).all()
   }
 }
 ```
 
-## Frontend — useAgentStream
+## Client — useAgentStream (React hook)
+
+Works with BOTH surfaces. Transport: `fetch` POST + `ReadableStream` (SSE).
 
 ```typescript
 import { useAgentStream } from 'theokit/client'
 
 function ChatUI() {
-  const { status, events, send } = useAgentStream('/api/agents/assistant')
+  const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
 
   return (
     <div>
-      {events.map(e => <p key={e.id}>{e.content}</p>)}
+      {status === 'streaming' && <p>Thinking...</p>}
+      {events.map(e => (
+        <div key={e.id}>
+          {e.type === 'message' && <p>{e.content}</p>}
+          {e.type === 'tool_call' && <p>Using tool: {e.name}</p>}
+        </div>
+      ))}
       <button onClick={() => send({ message: 'Hello' })}>Send</button>
     </div>
   )
 }
 ```
 
+### Non-React: consumeAgentStream
+
+```typescript
+import { consumeAgentStream } from 'theokit/client'
+
+const stream = consumeAgentStream('/api/agents/assistant', { body: { message: 'Hi' } })
+for await (const event of stream) {
+  console.log(event.type, event.content)
+}
+```
+
 ## Rules
 
 - Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
 - Tool `input` uses Zod schema — same pattern as defineRoute
 - `@UseGuards()` works on agents (shared with HTTP pipeline)
-- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings, not enforced at runtime)
+- `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings)
 - Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch
+- Pick ONE surface per endpoint — don't mix defineAgentEndpoint with @Agent for the same route
 
 ## Anti-patterns
 
-- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent + @Tool
+- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use @Agent or defineAgentEndpoint
 - NEVER reimplement tool calling loop — the SDK handles it
-- NEVER store conversations manually — use @Memory
+- NEVER store conversations manually — use @Memory (decorator) or SDK persistence
 - NEVER infer tool capability from method name — always provide explicit `name` + `description`
+- NEVER mix both surfaces for the same endpoint — pick manual OR decorator

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

@@ -43,18 +43,21 @@ import { createAppClient } from 'theokit/client'
 
 const client = createAppClient()
 
-// Proxy pattern — method names match route structure
 const tasks = await client.tasks.GET()
 const task = await client.tasks[':id'].GET({ params: { id: 1 } })
 const created = await client.tasks.POST({ body: { title: 'New' } })
 ```
 
-## Agent Streaming (useAgentStream)
+## Agent Streaming
+
+Three client APIs, all from `theokit/client`:
+
+### useAgentStream (React hook — most common)
 
 ```typescript
 import { useAgentStream } from 'theokit/client'
 
-function ChatComponent() {
+function ChatUI() {
   const { status, events, send, reset } = useAgentStream('/api/agents/assistant')
 
   return (
@@ -66,12 +69,34 @@ function ChatComponent() {
           {event.type === 'tool_call' && <p>Using tool: {event.name}</p>}
         </div>
       ))}
-      <input onSubmit={e => send({ message: e.target.value })} />
+      <button onClick={() => send({ message: 'Hello' })}>Send</button>
     </div>
   )
 }
 ```
 
+### consumeAgentStream (non-React, async iterable)
+
+```typescript
+import { consumeAgentStream } from 'theokit/client'
+
+const stream = consumeAgentStream('/api/agents/assistant', {
+  body: { message: 'Hello' },
+})
+for await (const event of stream) {
+  console.log(event.type, event.content)
+}
+```
+
+### parseSSEChunk (low-level SSE parser)
+
+```typescript
+import { parseSSEChunk } from 'theokit/client'
+
+// Parse a single SSE line into an AgentEvent (or null)
+const event = parseSSEChunk('data: {"type":"message","content":"Hello"}')
+```
+
 ## Path Aliases
 
 ```typescript
@@ -83,7 +108,7 @@ Configured in `tsconfig.json` — works in both server and app code.
 
 ## Anti-patterns
 
-- NEVER use `fetch('/api/...')` directly — use `theoFetch` for type safety
+- NEVER use raw `fetch('/api/...')` — use `theoFetch` for type safety
 - NEVER create pages outside `app/` — they won't be discovered by the router
 - NEVER import server code directly in `app/` — use theoFetch or server actions
 - NEVER use `useEffect` + `fetch` for data loading — use theoFetch or useAgentStream