opencodekit 0.15.4 → 0.15.6

package/dist/template/.opencode/skill/cloudflare/references/agents-sdk/configuration.md

@@ -0,0 +1,99 @@
+# Configuration
+
+## Wrangler Setup
+
+```toml
+name = "my-agents-app"
+
+[[durable_objects.bindings]]
+name = "MyAgent"
+class_name = "MyAgent"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyAgent"]
+
+[ai]
+binding = "AI"
+```
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {"name": "MyAgent", "class_name": "MyAgent"}
+    ]
+  },
+  "migrations": [
+    {"tag": "v1", "new_sqlite_classes": ["MyAgent"]}
+  ],
+  "ai": {
+    "binding": "AI"
+  }
+}
+```
+
+## Environment Bindings
+
+```typescript
+interface Env {
+  AI?: Ai;                              // Workers AI
+  MyAgent?: DurableObjectNamespace<MyAgent>;
+  DB?: D1Database;                      // D1 database
+  KV?: KVNamespace;                     // KV storage
+  R2?: R2Bucket;                        // R2 bucket
+  OPENAI_API_KEY?: string;              // Secrets
+  QUEUE?: Queue;                        // Queues
+}
+```
+
+## Deployment
+
+```bash
+# Local dev
+npx wrangler dev
+
+# Deploy production
+npx wrangler deploy
+
+# Set secrets
+npx wrangler secret put OPENAI_API_KEY
+```
+
+## Agent Routing
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env) {
+    const id = env.MyAgent.idFromName("user-123");
+    const stub = env.MyAgent.get(id);
+    return stub.fetch(request);
+  }
+}
+```
+
+## Email Routing
+
+Configure email routing in dashboard to deliver emails to agent:
+
+```
+Destination: Workers with Durable Objects
+Worker: my-agents-app
+```
+
+## AI Gateway (Optional)
+
+```typescript
+// Enable caching/routing through AI Gateway
+const response = await this.env.AI.run(
+  "@cf/meta/llama-3.1-8b-instruct",
+  { prompt },
+  {
+    gateway: {
+      id: "my-gateway-id",
+      skipCache: false,
+      cacheTtl: 3600
+    }
+  }
+);
+```

package/dist/template/.opencode/skill/cloudflare/references/agents-sdk/gotchas.md

@@ -0,0 +1,59 @@
+# Gotchas & Best Practices
+
+## State
+DO: `setState()` (auto-syncs), serializable, limit size | DON'T: Mutate directly, large objects (SQL), functions/circular
+```ts
+// ❌ this.state.count++ | ✅ this.setState({...this.state, count: this.state.count + 1})
+```
+
+## SQL
+DO: Parameterized, create in `onStart()`, types | DON'T: Direct interpolation, assume exists
+```ts
+// ❌ this.sql`...WHERE id = '${userId}'` | ✅ this.sql`...WHERE id = ${userId}`
+```
+
+## WebSocket
+DO: `conn.accept()`, errors, cleanup | DON'T: Forget accept (timeout), assume persist, sensitive in state
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) { conn.accept(); conn.setState({userId: "123"}); }
+```
+
+## Scheduling
+1000 tasks/agent, 1min min, persist. Clean old, descriptive names, handle failures
+```ts
+async checkSchedules() { if ((await this.getSchedules()).length > 800) console.warn("Near limit!"); }
+```
+
+## AI
+Optimize: AI Gateway cache, rate limit, stream | Error: try/catch, fallback, quota/timeout
+```ts
+try { return await this.env.AI.run(model, {prompt}); } catch (e) { return {error: "Unavailable"}; }
+```
+
+## Perf
+State: Batch `setState()`, low-freq, SQL for large | Conns: Limit broadcast, selective, backpressure
+
+## Debug
+`npx wrangler dev` (local), `npx wrangler tail` (remote)
+Issues: "Agent not found" (DO binding), State not sync (`setState()`), Timeout (`conn.accept()`), SQL (create in `onStart()`)
+
+## Security
+DO: Validate, sanitize, auth WS, env secrets | DON'T: Trust headers, expose sensitive, unauth
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) {
+  const token = ctx.request.headers.get("Authorization");
+  if (!await this.validateToken(token)) { conn.close(4001, "Unauthorized"); return; }
+  conn.accept();
+}
+```
+
+## Limits
+CPU: 30s/req, Mem: 128MB/inst, Storage: SQL shares DO quota, Conns: no limit (watch mem), Schedules: 1000/agent
+
+## Migration
+`new_sqlite_classes`, test staging, no downgrade w/SQL, careful state
+```toml
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyAgent"]
+```

package/dist/template/.opencode/skill/cloudflare/references/agents-sdk/patterns.md

@@ -0,0 +1,89 @@
+# Patterns & Use Cases
+
+## Chat
+
+```ts
+export class ChatAgent extends Agent<Env, ChatState> {
+  initialState = {messages: [], participants: []};
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept();
+    const userId = ctx.request.headers.get("X-User-ID");
+    conn.setState({userId});
+    this.setState({...this.state, participants: [...this.state.participants, userId]});
+    conn.send(JSON.stringify({type: "history", messages: this.state.messages}));
+  }
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    if (m.type === "chat")
+      this.setState({...this.state, messages: [...this.state.messages, {userId: conn.state.userId, text: m.text, timestamp: Date.now()}]});
+  }
+}
+```
+
+## AI w/Tools
+
+```ts
+import {tool} from "ai"; import {z} from "zod";
+const weatherTool = tool({description: "Get weather", inputSchema: z.object({city: z.string()}), execute: async ({city}) => `Weather: ${city} Sunny 72°F`});
+export class AIAgent extends Agent<Env> {
+  tools = {getWeather: weatherTool};
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    conn.send(JSON.stringify({response: await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: m.prompt, tools: this.tools})}));
+  }
+}
+```
+
+## Streaming
+
+```ts
+import {OpenAI} from "openai";
+export class StreamingAgent extends Agent<Env> {
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    const stream = await new OpenAI({apiKey: this.env.OPENAI_API_KEY}).chat.completions.create({model: "gpt-4", messages: [{role: "user", content: m.prompt}], stream: true});
+    for await (const chunk of stream) { const c = chunk.choices[0]?.delta?.content || ""; if (c) conn.send(JSON.stringify({type: "chunk", content: c})); }
+    conn.send(JSON.stringify({type: "done"}));
+  }
+}
+```
+
+## Cron/Scheduled
+
+```ts
+export class TaskAgent extends Agent<Env> {
+  onStart() { this.schedule("0 0 * * *", "dailyCleanup", {}); this.schedule("0 * * * *", "syncData", {}); }
+  async dailyCleanup() { this.sql`DELETE FROM logs WHERE created_at < ${Date.now() - 86400000}`; }
+  async syncData() { const data = await (await fetch(this.env.API_URL)).json(); this.sql`INSERT INTO cache (data,updated_at) VALUES (${JSON.stringify(data)},${Date.now()})`; }
+}
+```
+
+## Email+AI
+
+```ts
+export class EmailAgent extends Agent<Env> {
+  async onEmail(email: AgentEmail) {
+    const [text, from, subject] = [await email.text(), email.from, email.headers.get("subject")];
+    this.sql`INSERT INTO emails (from_addr,subject,body,received_at) VALUES (${from},${subject},${text},${Date.now()})`;
+    const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: `Summarize: ${text}`});
+    this.setState({...this.state, lastEmail: {from, subject, summary: r}});
+    this.connections.forEach(c => c.send(JSON.stringify({type: "new_email", from, subject})));
+  }
+}
+```
+
+## Game
+
+```ts
+export class GameAgent extends Agent<Env, GameState> {
+  initialState = {players: [], score: 0, round: 1};
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept(); const playerId = ctx.request.headers.get("X-Player-ID"); conn.setState({playerId});
+    this.setState({...this.state, players: [...this.state.players, {id: playerId, score: 0}]});
+  }
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string);
+    if (m.type === "move") this.setState({...this.state, players: this.state.players.map(p => p.id === conn.state.playerId ? {...p, score: p.score + m.points} : p)});
+  }
+}
+```