sideagent 0.0.0-stage → 0.2.0

package/dist/testing/mock-llm.d.ts

@@ -0,0 +1,7 @@
+declare function mockLlmHandler(request: Request): Promise<Response>;
+/** Deterministic bag-of-words embedding: texts that share words get similar vectors. */
+declare function mockEmbed(text: string): number[];
+/** Scripted OpenAI-compatible /embeddings endpoint for tests and demos. */
+declare function mockEmbeddingsHandler(request: Request): Promise<Response>;
+
+export { mockEmbed, mockEmbeddingsHandler, mockLlmHandler };

package/dist/testing/mock-llm.js

@@ -0,0 +1,84 @@
+// src/testing/mock-llm.ts
+function script(messages, forced) {
+  if (forced) return { call: { name: forced, args: {} } };
+  const last = messages[messages.length - 1];
+  if (!last) return { text: "..." };
+  if (last.role === "tool") return { text: `Done. Result: ${String(last.content).slice(0, 120)}` };
+  const text = String(last.content ?? "");
+  const explicit = /CALL (\S+)\s*(\{.*\})?/s.exec(text);
+  if (explicit) return { call: { name: explicit[1], args: explicit[2] ? JSON.parse(explicit[2]) : {} } };
+  if (/\b(policy|refunds?|terms|docs|warranty)\b/i.test(text)) return { call: { name: "search_knowledge", args: { query: text } } };
+  if (/\blist\b/i.test(text)) return { call: { name: "listInvoices", args: {} } };
+  if (/\bcreate\b/i.test(text)) return { call: { name: "createInvoice", args: { body: { customer: "Acme", amount: 100 } } } };
+  if (/\bdelete\b/i.test(text)) return { call: { name: "deleteInvoice", args: { id: "1" } } };
+  return { text: "Hello from the mock model." };
+}
+async function mockLlmHandler(request) {
+  const body = await request.json();
+  const { text, call } = script(body.messages, body.tool_choice?.function?.name);
+  const id = `chatcmpl-mock-${crypto.randomUUID()}`;
+  const base = { id, object: "chat.completion.chunk", created: 0, model: "mock" };
+  if (!body.stream) {
+    return Response.json({
+      id,
+      object: "chat.completion",
+      created: 0,
+      model: "mock",
+      choices: [
+        {
+          index: 0,
+          finish_reason: call ? "tool_calls" : "stop",
+          message: call ? { role: "assistant", content: null, tool_calls: [{ id: "call_1", type: "function", function: { name: call.name, arguments: JSON.stringify(call.args) } }] } : { role: "assistant", content: text }
+        }
+      ]
+    });
+  }
+  const chunks = [{ ...base, choices: [{ index: 0, delta: { role: "assistant", content: "" } }] }];
+  if (call) {
+    chunks.push({
+      ...base,
+      choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: `call_${Math.random().toString(36).slice(2, 8)}`, type: "function", function: { name: call.name, arguments: JSON.stringify(call.args) } }] } }]
+    });
+    chunks.push({ ...base, choices: [{ index: 0, delta: {}, finish_reason: "tool_calls" }] });
+  } else {
+    for (const w of (text ?? "").split(/(?<= )/)) chunks.push({ ...base, choices: [{ index: 0, delta: { content: w } }] });
+    chunks.push({ ...base, choices: [{ index: 0, delta: {}, finish_reason: "stop" }] });
+  }
+  const sse = chunks.map((c) => `data: ${JSON.stringify(c)}
+
+`).join("") + "data: [DONE]\n\n";
+  return new Response(sse, { headers: { "content-type": "text/event-stream" } });
+}
+var DIM = 128;
+function hashToken(t) {
+  let h = 2166136261;
+  for (let i = 0; i < t.length; i++) h = Math.imul(h ^ t.charCodeAt(i), 16777619);
+  return Math.abs(h) % DIM;
+}
+function mockEmbed(text) {
+  const v = new Array(DIM).fill(0);
+  for (const w of text.toLowerCase().match(/[a-z0-9]+/g) ?? []) v[hashToken(w)] += 1;
+  const n = Math.sqrt(v.reduce((a, b) => a + b * b, 0)) || 1;
+  return v.map((x) => x / n);
+}
+async function mockEmbeddingsHandler(request) {
+  const body = await request.json();
+  const inputs = Array.isArray(body.input) ? body.input : [body.input];
+  const toB64 = (v) => {
+    const bytes = new Uint8Array(new Float32Array(v).buffer);
+    let s = "";
+    for (const b of bytes) s += String.fromCharCode(b);
+    return btoa(s);
+  };
+  return Response.json({
+    object: "list",
+    model: "mock-embedding",
+    data: inputs.map((t, index) => ({ object: "embedding", index, embedding: body.encoding_format === "base64" ? toB64(mockEmbed(t)) : mockEmbed(t) })),
+    usage: { prompt_tokens: 0, total_tokens: 0 }
+  });
+}
+export {
+  mockEmbed,
+  mockEmbeddingsHandler,
+  mockLlmHandler
+};

package/dist/workers-ai/index.d.ts

@@ -0,0 +1,56 @@
+import { BaseChatModel, BaseChatModelCallOptions, BindToolsInput } from '@langchain/core/language_models/chat_models';
+import { BaseLanguageModelInput } from '@langchain/core/language_models/base';
+import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
+import { AIMessageChunk, BaseMessage } from '@langchain/core/messages';
+import { ChatResult, ChatGenerationChunk } from '@langchain/core/outputs';
+import { Runnable } from '@langchain/core/runnables';
+
+/**
+ * The part of the Workers AI binding (`env.AI`) used here. Structural on purpose:
+ * no dependency on @cloudflare/workers-types.
+ */
+interface WorkersAiBinding {
+    run(model: string, input: unknown): Promise<unknown>;
+}
+interface WorkersAiChatOptions {
+    temperature?: number;
+    maxTokens?: number;
+    /** Ask the binding for a stream. Falls back to one chunk when it returns a plain object. Default true. */
+    streaming?: boolean;
+}
+interface WorkersAiCallOptions extends BaseChatModelCallOptions {
+    tools?: unknown[];
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+interface Parsed {
+    text: string;
+    toolCalls: ToolCall[];
+}
+/** Reads every response shape the binding is known to return. Throws on anything else. */
+declare function parseWorkersAiResponse(res: unknown): Parsed;
+declare class ChatWorkersAI extends BaseChatModel<WorkersAiCallOptions> {
+    private readonly ai;
+    private readonly modelName;
+    private readonly opts;
+    constructor(ai: WorkersAiBinding, modelName: string, opts?: WorkersAiChatOptions);
+    _llmType(): string;
+    bindTools(tools: BindToolsInput[], kwargs?: Partial<WorkersAiCallOptions>): Runnable<BaseLanguageModelInput, AIMessageChunk, WorkersAiCallOptions>;
+    private input;
+    private run;
+    _generate(messages: BaseMessage[], options: this["ParsedCallOptions"]): Promise<ChatResult>;
+    _streamResponseChunks(messages: BaseMessage[], options: this["ParsedCallOptions"], runManager?: CallbackManagerForLLMRun): AsyncGenerator<ChatGenerationChunk>;
+    private emit;
+}
+/** A LangChain chat model backed by the Workers AI binding. Pass it to createAgent as `model`. */
+declare function workersAiChatModel(ai: WorkersAiBinding, model: string, opts?: WorkersAiChatOptions): BaseChatModel;
+/** Embeddings backed by the Workers AI binding. Pass them to createAgent as `embeddings`. */
+declare function workersAiEmbeddings(ai: WorkersAiBinding, model: string): {
+    embedDocuments: (texts: string[]) => Promise<number[][]>;
+    embedQuery(text: string): Promise<number[]>;
+};
+
+export { ChatWorkersAI, type WorkersAiBinding, type WorkersAiChatOptions, parseWorkersAiResponse, workersAiChatModel, workersAiEmbeddings };

package/dist/workers-ai/index.js

@@ -0,0 +1,241 @@
+// src/workers-ai/index.ts
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { AIMessage, AIMessageChunk } from "@langchain/core/messages";
+import { ChatGenerationChunk } from "@langchain/core/outputs";
+import { convertToOpenAITool } from "@langchain/core/utils/function_calling";
+var isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function textOf(content) {
+  if (typeof content === "string") return content;
+  return content.map((p) => p.type === "text" && typeof p.text === "string" ? p.text : "").join("");
+}
+function toWire(messages) {
+  return messages.map((m) => {
+    const type = m.getType();
+    const content = textOf(m.content);
+    if (type === "system") return { role: "system", content };
+    if (type === "human") return { role: "user", content };
+    if (type === "tool") return { role: "tool", tool_call_id: m.tool_call_id, content };
+    const calls = m.tool_calls ?? [];
+    return {
+      role: "assistant",
+      content,
+      ...calls.length ? { tool_calls: calls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: JSON.stringify(c.args ?? {}) } })) } : {}
+    };
+  });
+}
+function parseArgs(raw) {
+  if (raw == null || raw === "") return {};
+  if (isObj(raw)) return raw;
+  if (typeof raw === "string") {
+    let v;
+    try {
+      v = JSON.parse(raw);
+    } catch {
+      throw new Error("Workers AI returned a tool call with malformed arguments");
+    }
+    if (isObj(v)) return v;
+  }
+  throw new Error("Workers AI returned a tool call with malformed arguments");
+}
+var newId = () => `call_${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`;
+function parseWorkersAiResponse(res) {
+  const r = isObj(res) && isObj(res.result) && !("response" in res) && !("choices" in res) && !("output" in res) ? res.result : res;
+  if (typeof r === "string") return { text: r, toolCalls: [] };
+  if (!isObj(r)) throw new Error("Workers AI returned an unrecognized response");
+  let text = "";
+  const toolCalls = [];
+  let known = false;
+  if (Array.isArray(r.output)) {
+    known = true;
+    for (const item of r.output) {
+      if (!isObj(item)) continue;
+      if (item.type === "function_call") {
+        toolCalls.push({ id: String(item.call_id ?? item.id ?? newId()), name: String(item.name), args: parseArgs(item.arguments) });
+      } else if (item.type === "message" || item.type === void 0 && Array.isArray(item.content)) {
+        for (const part of Array.isArray(item.content) ? item.content : []) {
+          if (isObj(part) && (part.type === "output_text" || part.type === "text") && typeof part.text === "string") text += part.text;
+        }
+      }
+    }
+  }
+  const msg = Array.isArray(r.choices) && isObj(r.choices[0]) ? r.choices[0].message : void 0;
+  if (isObj(msg)) {
+    known = true;
+    if (typeof msg.content === "string") text += msg.content;
+    for (const c of Array.isArray(msg.tool_calls) ? msg.tool_calls : []) {
+      const fn = isObj(c) ? c.function ?? c : void 0;
+      if (!isObj(fn) || typeof fn.name !== "string") throw new Error("Workers AI returned a malformed tool call");
+      toolCalls.push({ id: String(c.id ?? newId()), name: fn.name, args: parseArgs(fn.arguments) });
+    }
+  }
+  if (typeof r.response === "string") {
+    known = true;
+    text += r.response;
+  } else if (r.response === null) known = true;
+  if (Array.isArray(r.tool_calls)) {
+    known = true;
+    for (const c of r.tool_calls) {
+      const fn = isObj(c) ? c.function ?? c : void 0;
+      if (!isObj(fn) || typeof fn.name !== "string") throw new Error("Workers AI returned a malformed tool call");
+      toolCalls.push({ id: String(c.id ?? newId()), name: fn.name, args: parseArgs(fn.arguments) });
+    }
+  }
+  if (!known) throw new Error("Workers AI returned an unrecognized response");
+  return { text, toolCalls };
+}
+async function* sseEvents(stream) {
+  const dec = new TextDecoder();
+  let buf = "";
+  const source = Symbol.asyncIterator in stream ? stream : readerIterable(stream);
+  function* drain(final) {
+    const lines = buf.split("\n");
+    buf = final ? "" : lines.pop() ?? "";
+    for (const line of lines) {
+      const l = line.trim();
+      if (!l.startsWith("data:")) continue;
+      const data = l.slice(5).trim();
+      if (!data || data === "[DONE]") continue;
+      try {
+        yield JSON.parse(data);
+      } catch {
+        throw new Error("Workers AI returned a malformed stream event");
+      }
+    }
+  }
+  for await (const chunk of source) {
+    buf += typeof chunk === "string" ? chunk : dec.decode(chunk, { stream: true });
+    yield* drain(false);
+  }
+  yield* drain(true);
+}
+async function* readerIterable(stream) {
+  const reader = stream.getReader();
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+var isStream = (v) => !!v && typeof v === "object" && (typeof v.getReader === "function" || Symbol.asyncIterator in v);
+var ChatWorkersAI = class extends BaseChatModel {
+  constructor(ai, modelName, opts = {}) {
+    super({});
+    this.ai = ai;
+    this.modelName = modelName;
+    this.opts = opts;
+  }
+  ai;
+  modelName;
+  opts;
+  _llmType() {
+    return "workers-ai";
+  }
+  bindTools(tools, kwargs) {
+    return this.withConfig({ ...kwargs, tools: tools.map((t) => convertToOpenAITool(t)) });
+  }
+  input(messages, options, stream) {
+    return {
+      messages: toWire(messages),
+      ...options.tools?.length ? { tools: options.tools } : {},
+      ...this.opts.temperature !== void 0 ? { temperature: this.opts.temperature } : {},
+      ...this.opts.maxTokens !== void 0 ? { max_tokens: this.opts.maxTokens } : {},
+      ...stream ? { stream: true } : {}
+    };
+  }
+  async run(input, signal) {
+    signal?.throwIfAborted();
+    return this.ai.run(this.modelName, input);
+  }
+  async _generate(messages, options) {
+    const { text, toolCalls } = parseWorkersAiResponse(await this.run(this.input(messages, options, false), options.signal));
+    const message = new AIMessage({ content: text, tool_calls: toolCalls.map((c) => ({ type: "tool_call", ...c })) });
+    return { generations: [{ text, message }] };
+  }
+  async *_streamResponseChunks(messages, options, runManager) {
+    const res = this.opts.streaming === false ? void 0 : await this.run(this.input(messages, options, true), options.signal);
+    if (!isStream(res)) {
+      const full = res === void 0 ? parseWorkersAiResponse(await this.run(this.input(messages, options, false), options.signal)) : parseWorkersAiResponse(res);
+      yield* this.emit(full, runManager);
+      return;
+    }
+    const partial = /* @__PURE__ */ new Map();
+    const whole = [];
+    for await (const ev of sseEvents(res)) {
+      options.signal?.throwIfAborted();
+      if (!isObj(ev)) continue;
+      let delta = "";
+      if (typeof ev.response === "string") delta = ev.response;
+      const choice = Array.isArray(ev.choices) && isObj(ev.choices[0]) ? ev.choices[0] : void 0;
+      if (choice) {
+        const d = isObj(choice.delta) ? choice.delta : isObj(choice.message) ? choice.message : {};
+        if (typeof d.content === "string") delta += d.content;
+        for (const tc of Array.isArray(d.tool_calls) ? d.tool_calls : []) {
+          const i = typeof tc.index === "number" ? tc.index : partial.size;
+          const cur = partial.get(i) ?? { name: "", args: "" };
+          if (tc.id) cur.id = String(tc.id);
+          if (tc.function?.name) cur.name += tc.function.name;
+          if (typeof tc.function?.arguments === "string") cur.args += tc.function.arguments;
+          partial.set(i, cur);
+        }
+      }
+      if (ev.type === "response.output_text.delta" && typeof ev.delta === "string") delta += ev.delta;
+      if (ev.type === "response.output_item.done" && isObj(ev.item) && ev.item.type === "function_call") {
+        whole.push({ id: String(ev.item.call_id ?? ev.item.id ?? newId()), name: String(ev.item.name), args: parseArgs(ev.item.arguments) });
+      }
+      if (Array.isArray(ev.tool_calls)) whole.push(...parseWorkersAiResponse({ tool_calls: ev.tool_calls }).toolCalls);
+      if (delta) yield* this.emit({ text: delta, toolCalls: [] }, runManager);
+    }
+    const toolCalls = [...whole];
+    for (const p of partial.values()) {
+      if (!p.name) throw new Error("Workers AI returned a malformed tool call");
+      toolCalls.push({ id: p.id ?? newId(), name: p.name, args: parseArgs(p.args) });
+    }
+    if (toolCalls.length) yield* this.emit({ text: "", toolCalls }, runManager);
+  }
+  async *emit({ text, toolCalls }, runManager) {
+    const chunk = new ChatGenerationChunk({
+      text,
+      message: new AIMessageChunk({
+        content: text,
+        tool_call_chunks: toolCalls.map((c, index) => ({ type: "tool_call_chunk", index, id: c.id, name: c.name, args: JSON.stringify(c.args) }))
+      })
+    });
+    yield chunk;
+    await runManager?.handleLLMNewToken(text, void 0, void 0, void 0, void 0, { chunk });
+  }
+};
+function workersAiChatModel(ai, model, opts) {
+  return new ChatWorkersAI(ai, model, opts);
+}
+var EMBED_BATCH = 100;
+function workersAiEmbeddings(ai, model) {
+  async function embedDocuments(texts) {
+    const out = [];
+    for (let i = 0; i < texts.length; i += EMBED_BATCH) {
+      const batch = texts.slice(i, i + EMBED_BATCH);
+      const res = await ai.run(model, { text: batch });
+      const data = res?.data ?? res?.result?.data;
+      if (!Array.isArray(data) || data.length !== batch.length || !data.every((v) => Array.isArray(v))) {
+        throw new Error("Workers AI returned an unrecognized embeddings response");
+      }
+      out.push(...data);
+    }
+    return out;
+  }
+  return {
+    embedDocuments,
+    async embedQuery(text) {
+      return (await embedDocuments([text]))[0];
+    }
+  };
+}
+export {
+  ChatWorkersAI,
+  parseWorkersAiResponse,
+  workersAiChatModel,
+  workersAiEmbeddings
+};

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "sideagent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "workerd": "./dist/server/index.js",
+      "worker": "./dist/server/index.js",
+      "browser": "./dist/server/browser.js",
+      "import": "./dist/server/index.js"
+    },
+    "./workers-ai": {
+      "types": "./dist/workers-ai/index.d.ts",
+      "workerd": "./dist/workers-ai/index.js",
+      "worker": "./dist/workers-ai/index.js",
+      "import": "./dist/workers-ai/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/mock-llm.d.ts",
+      "import": "./dist/testing/mock-llm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "!skills/**/evals"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "demo:api": "tsx demo/server.ts",
+    "demo": "tsx demo/server.ts & vite demo",
+    "eval:skill": "cd skills/sideagent && claude plugin eval . --scaffold --allow-tools Write Edit --trust-plugin --no-publish"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "^0.15.31",
+    "@langchain/core": "^1.0.0",
+    "@langchain/langgraph": "^1.5.2",
+    "@langchain/openai": "^1.7.0",
+    "@radix-ui/react-icons": "^1.3.2",
+    "@scalar/openapi-parser": "^0.29.16",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.14.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "hono": "^4.9.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.0.0",
+    "vitest": "^3.2.0"
+  },
+  "packageManager": "pnpm@10.30.2"
+}

package/skills/sideagent/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: sideagent
+description: Add an AI agent, chat assistant or copilot to an existing app or SaaS that has an HTTP API, using the sideagent library. Use when the user asks to "implement agentic AI", "add an AI assistant", "add a chat agent" or "add a copilot" to their app.
+---
+
+# Add an agent to an app with sideagent
+
+sideagent turns an OpenAPI spec plus an OpenAI-compatible LLM into a secure agent endpoint (`sideagent/server`) and a React chat UI (`sideagent`). Full docs: https://egig.github.io/sideagent/llms-full.txt
+
+## Steps
+
+Do them in order. Do not skip the review in step 7.
+
+1. **Detect the stack.** Find the server framework (Next.js App Router, Hono, Express), the frontend (React?) and the OpenAPI spec. No spec: generate one from the existing routes, or ask the user where it is. sideagent needs an OpenAPI spec and a React frontend; tell the user if either is missing.
+2. **Install.** `npm i sideagent` (use the project's package manager).
+3. **Fix the spec.** For each operation the agent may use:
+   - Unique `operationId`, a clear `summary`, typed parameters.
+   - `x-agent` hints where useful: `{ approval, description, invalidates: ["tag"], responseFields: ["id"] }`. `approval` is the string `"required"` or `"auto"` (never a boolean). Non-GET defaults to `"required"`; leave that default. `"auto"` is rejected for DELETE. Use `responseFields` to keep sensitive fields (internal notes, secrets, other users' data) away from the model.
+4. **Add the server route** at `/agent`:
+   ```ts
+   import { createAgent, nextRoute /* or honoHandler, expressHandler */ } from "sideagent/server";
+
+   const agent = await createAgent({
+     spec,                                   // URL, object or JSON string
+     baseUrl: process.env.API_BASE_URL!,     // pinned; the spec's `servers` is ignored
+     llm: { baseUrl: process.env.LLM_BASE_URL ?? "https://api.openai.com/v1", apiKey: process.env.LLM_API_KEY!, model: process.env.LLM_MODEL ?? "gpt-4o-mini" },
+     allow: ["listInvoices"],                // default-deny; start read-only
+     allowedOrigins: [process.env.APP_ORIGIN!],
+     approvalSecret: process.env.APPROVAL_SECRET, // 16+ chars; required on serverless / multi-instance
+     getAuth: async (req) => {
+       const session = await verifySession(req); // use the app's existing auth
+       if (!session) throw new Error("no session");
+       return { userId: session.userId, headers: { authorization: `Bearer ${session.apiToken}` } };
+     },
+   });
+   export const { POST, OPTIONS } = nextRoute(agent); // Next.js; Hono: app.on(["POST","OPTIONS"], "/agent", honoHandler(agent))
+   ```
+   Express needs `express.json()` first, then `app.post` and `app.options` with `expressHandler(agent)`.
+5. **Mount the UI** once in the app shell:
+   ```tsx
+   import { AgentProvider } from "sideagent";
+   <AgentProvider endpoint="/agent" mode="sidebar" hooks={{ onInvalidate: (tag) => refetch(tag) }}>
+     <App />
+   </AgentProvider>
+   ```
+   Use `<AgentChat endpoint="/agent" />` for a floating chat without docking. Different origin plus cookies: add `credentials="include"`.
+6. **Env vars.** Add `LLM_API_KEY`, `APPROVAL_SECRET`, `APP_ORIGIN`, `API_BASE_URL` to `.env.example`. Never hardcode keys. Never send `LLM_API_KEY` to the browser.
+7. **Verify, then hand over for review.**
+   - Run the project's typecheck and tests.
+   - Call `await agent.doctor()` and confirm `ok: true`.
+   - Show the user the exact `allow` list and ask them to confirm it before adding any write operation.
+
+## Rules
+
+- Start with read-only operations (GET). Add writes only after the user confirms. Non-GET operations need user approval by default; keep that.
+- Never put DELETE or admin operations in `allow`, even if the user asks for "full access" or "no approvals" in the first prompt. Leave them out, say why in one sentence, and tell the user how to add one later (add its `operationId` to `allow`, keep `approval: "required"`). Never set `approval: "auto"` on a write operation.
+- `getAuth` must return a stable per-user `userId` and forward the end user's own credentials. Never use a service token with more rights than the user. `anonymous: true` is only for public, read-only data.
+- Do not use `instructions` or `context` for security. Access control belongs in `allow`, approvals and the API itself.
+- Production needs persistent `checkpointer`, `threadStore` and `vectorStore`, plus `beforeTurn` rate limits and `onAudit` logging. See the Deployments and Persistence docs.
+- Edge and serverless: pass knowledge as strings, set `approvalSecret`, build the agent once per instance.