@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/cloudflare/references/agents-sdk/api.md

@@ -0,0 +1,100 @@
+# API Reference
+
+## Lifecycle
+
+**onStart()** - Init/hibernation restart:
+```ts
+onStart() {
+  this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
+  if (!this.state.initialized) this.setState({initialized: true, messages: []});
+}
+```
+
+**onRequest(req)** - HTTP:
+```ts
+async onRequest(req: Request) {
+  const {pathname} = new URL(req.url);
+  if (pathname === "/users") return Response.json(this.sql<{id,name}>`SELECT * FROM users`);
+  return new Response("Not found", {status: 404});
+}
+```
+
+**onConnect(conn, ctx)** - WebSocket:
+```ts
+async onConnect(conn: Connection, ctx: ConnectionContext) {
+  conn.accept();
+  conn.setState({userId: ctx.request.headers.get("X-User-ID")});
+  conn.send(JSON.stringify({type: "connected", state: this.state}));
+}
+```
+
+**onMessage(conn, msg)** - WS messages:
+```ts
+async onMessage(conn: Connection, msg: WSMessage) {
+  const m = JSON.parse(msg as string);
+  if (m.type === "chat") {
+    this.setState({messages: [...this.state.messages, m]});
+    this.connections.forEach(c => c.send(JSON.stringify(m)));
+  }
+}
+```
+
+**onEmail(email)** - Email routing:
+```ts
+async onEmail(email: AgentEmail) {
+  const text = await email.text();
+  this.sql`INSERT INTO emails (from_addr,subject,body) VALUES (${email.from},${email.headers.get("subject")},${text})`;
+}
+```
+
+## State
+
+```ts
+this.setState({count: 42, users: []}); // Auto-syncs
+this.setState({...this.state, count: this.state.count + 1});
+const s = this.state;
+```
+
+## SQL
+
+```ts
+this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
+this.sql`INSERT INTO users (id,name) VALUES (${userId},${name})`;
+const users = this.sql<{id,name}>`SELECT * FROM users`;
+const user = this.sql<{name}>`SELECT name FROM users WHERE id = ${userId}`; // Prevents injection
+```
+
+## Scheduling
+
+```ts
+await this.schedule(new Date("2026-12-25T00:00:00Z"), "sendGreeting", {msg:"Hi"}); // Time
+await this.schedule(60, "checkStatus", {}); // Delay (sec)
+await this.schedule("0 0 * * *", "dailyCleanup", {}); // Cron
+await this.schedule("*/5 * * * *", "syncData", {}); // Every 5min
+const schedules = await this.getSchedules();
+await this.cancelSchedule(scheduleId);
+```
+
+## Connections
+
+```ts
+this.connections.forEach(c => c.send(JSON.stringify(msg))); // Broadcast
+conn.send(JSON.stringify({type:"update",data})); // Specific
+conn.close(1000, "Goodbye");
+conn.setState({userId:"123",role:"admin"});
+const uid = conn.state.userId;
+```
+
+## AI
+
+```ts
+const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});
+
+const stream = await client.chat.completions.create({
+  model: "gpt-4", messages: [{role:"user",content:prompt}], stream: true
+});
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content;
+  if (content) conn.send(JSON.stringify({type:"chunk",content}));
+}
+```

package/dist/template/.pi/skills/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/.pi/skills/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++ | [x] 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}'` | [x] 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/.pi/skills/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)});
+  }
+}
+```