sideagent 0.1.0 → 0.3.0

package/README.md

@@ -6,6 +6,8 @@ Embed a chat agent in your app. You give it an OpenAPI spec and an OpenAI-compat
 npm i sideagent
 ```
 
+Docs: https://egig.github.io/sideagent/
+
 ## Server (`sideagent/server`)
 
 ```ts
@@ -43,6 +45,16 @@ import { AgentChat } from "sideagent";
 />
 ```
 
+### sideagent Cloud
+
+With an agent hosted on sideagent Cloud, pass its publishable key instead of `endpoint`. The key names the agent and its host, so the chat derives the URL (`https://<host>/v1/agents/<agentId>`) and sends the key in the `x-sideagent-key` header on every request. The key is public: it is safe in the browser and proves nothing on its own.
+
+```tsx
+<AgentChat publishableKey="pk_live_…" />
+```
+
+Pass `endpoint` as well to send the requests somewhere else, such as a proxy in front of sideagent Cloud. A malformed key, or neither prop, throws during render. `parsePublishableKey` and `publishableEndpoint` are exported from `sideagent/keys`.
+
 ### Docked sidebar
 
 Wrap your app in `AgentProvider` to dock the chat on the right, side by side with the app instead of over it. It takes the same props as `AgentChat`. The user drags the panel's left edge (or uses the arrow keys on it) to resize; the width is remembered. Outside `AgentProvider`, sidebar mode overlays the page.
@@ -96,7 +108,7 @@ Neutral by default (grayscale, host font, 10px radius). `theme="auto"` follows t
 
 ## Results and icons
 
-Tool results render as readable views: arrays of objects become tables (up to 50 rows and 8 columns, numbers right-aligned, dates and booleans formatted), objects become labelled fields, errors and rejections get their own state. Raw JSON stays under "Details". Everything is plain text, never HTML. Override per operation:
+Tool results render as readable views: arrays of objects become tables (up to 50 rows and 8 columns, numbers right-aligned, dates and booleans formatted), objects become labelled fields, errors and rejections get their own state. Raw JSON stays under "Details". Tool results are plain text, never HTML. Assistant replies render as Markdown (GFM); raw HTML is dropped. Override per operation:
 
 ```tsx
 <AgentChat resultRenderers={{ listInvoices: ({ result }) => <MyInvoiceTable rows={result as any[]} /> }} />
@@ -130,3 +142,45 @@ createAgent({
 The agent gets a `search_knowledge` tool; answers show a "Sources" card (links only for your configured URLs). Passages reach the model as labelled untrusted data and never reach the browser. URLs come only from config, must be public http(s) (private ranges need `allowPrivateNetworks`, metadata addresses never), follow only same-host redirects, and are capped by `maxSourceBytes`. URL sources refresh in the background after `ttlMs` (default 1h) or on `agent.knowledge.refresh()`. A source that fails to load is skipped with a warning and shown in `doctor()`.
 
 With the default in-memory store, every start re-embeds all sources (embedding cost). Use a persistent `vectorStore` for large knowledge.
+
+## Cloudflare Workers
+
+`sideagent/server` runs on Workers. Use `nodejs_compat` (or just `nodejs_als`) in `wrangler.jsonc`. LangGraph's approval pause (`interrupt()`) needs `AsyncLocalStorage`, and the Workers build of LangGraph does not register it. sideagent registers it for you when the runtime has it. Without the flag, reads work and the first approval fails (startup logs a warning).
+
+```jsonc
+{ "compatibility_date": "2025-09-01", "compatibility_flags": ["nodejs_compat"] }
+```
+
+**Export conditions.** `sideagent/server` resolves to the real build under `workerd` and `worker`, listed before `browser` (which stays a throwing stub for real browser bundles). Wrangler (esbuild) and `@cloudflare/vite-plugin` need no alias. Both also set `browser`, so the order in `exports` matters.
+
+**Workers AI as the LLM.** `env.AI` is a binding, not an HTTP endpoint, so use the adapter from `sideagent/workers-ai` instead of `llm`:
+
+```ts
+import { createAgent } from "sideagent/server";
+import { workersAiChatModel, workersAiEmbeddings } from "sideagent/workers-ai";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    agent ??= await createAgent({
+      spec, baseUrl: env.API_URL, allow: ["listInvoices", "createInvoice"],
+      allowedOrigins: ["https://app.example.com"], approvalSecret: env.APPROVAL_SECRET,
+      getAuth,
+      model: workersAiChatModel(env.AI, "@cf/openai/gpt-oss-120b"),
+      knowledge: { sources }, // optional
+      embeddings: workersAiEmbeddings(env.AI, "@cf/baai/bge-m3"), // replaces knowledge.embeddings
+    });
+    return agent.handler(request);
+  },
+};
+let agent: Awaited<ReturnType<typeof createAgent>> | undefined;
+```
+
+`model` and `llm` are mutually exclusive; so are the `embeddings` option and `knowledge.embeddings`. `model` can be any LangChain chat model that supports `bindTools()`. `doctor()` checks an injected model with one `invoke`, not an HTTP call. The adapter takes the binding structurally (no `@cloudflare/workers-types` needed) and reads gpt-oss Responses-style output, chat-style `choices[0].message` and `{ response }`.
+
+A custom `checkpointer` (D1, Durable Object storage) is a `BaseCheckpointSaver` with four methods: `getTuple`, `list`, `put`, `putWrites`. sideagent also calls `deleteThread` when a user deletes a thread.
+
+## For AI agents
+
+- Skill: `npx skills add egig/sideagent`, then ask your coding agent to "add an AI assistant to this app". See [Quickstart](https://egig.github.io/sideagent/quickstart).
+- [`AGENTS.md`](AGENTS.md): commands, layout and rules for coding agents working on this repo.
+- [`llms.txt`](https://egig.github.io/sideagent/llms.txt) and [`llms-full.txt`](https://egig.github.io/sideagent/llms-full.txt): the docs in LLM-friendly form.

package/dist/index.js

@@ -25,6 +25,8 @@ import {
   ViewVerticalIcon
 } from "@radix-ui/react-icons";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import Markdown from "react-markdown";
+import remarkGfm from "remark-gfm";
 
 // src/client/hooks.ts
 function safely(fn) {
@@ -166,6 +168,18 @@ var CSS = `
 .sa-msg{max-width:90%;white-space:pre-wrap;word-break:break-word}
 .sa-user{align-self:flex-end;background:var(--sa-surface);padding:7px 12px;border-radius:calc(var(--sa-radius) + 4px)}
 .sa-assistant{align-self:flex-start}
+.sa-md{white-space:normal;min-width:0}
+.sa-md>:first-child{margin-top:0}.sa-md>:last-child{margin-bottom:0}
+.sa-md :is(p,ul,ol,pre,table,blockquote){margin:0 0 .6em}
+.sa-md :is(ul,ol){padding-left:1.4em}
+.sa-md :is(h1,h2,h3,h4){font-size:1em;font-weight:600;margin:.8em 0 .3em}
+.sa-md a{color:inherit;text-decoration:underline}
+.sa-md code{font-family:ui-monospace,monospace;font-size:.9em;background:var(--sa-surface);padding:1px 4px;border-radius:4px}
+.sa-md pre{background:var(--sa-surface);padding:8px 10px;border-radius:calc(var(--sa-radius) - 2px);overflow-x:auto}
+.sa-md pre code{background:none;padding:0}
+.sa-md blockquote{border-left:3px solid var(--sa-border);padding-left:10px;color:var(--sa-muted);margin-left:0}
+.sa-md table{border-collapse:collapse;display:block;overflow-x:auto}
+.sa-md :is(th,td){border:1px solid var(--sa-border);padding:3px 8px;text-align:left}
 .sa-icon-btn{display:inline-grid;place-items:center;min-width:28px;padding:4px}
 .sa-icon-btn svg{width:15px;height:15px}
 .sa-tool{align-self:stretch;border:1px solid var(--sa-border);border-radius:var(--sa-radius);padding:8px 10px;font-size:13px;min-width:0}
@@ -402,12 +416,15 @@ function ToolCard(props) {
     ] })
   ] });
 }
+var mdComponents = {
+  a: ({ node: _n, ...p }) => /* @__PURE__ */ jsx2("a", { ...p, target: "_blank", rel: "noopener noreferrer nofollow" })
+};
 var UserMessage = () => /* @__PURE__ */ jsx2(MessagePrimitive.Root, { className: "sa-msg sa-user", children: /* @__PURE__ */ jsx2(MessagePrimitive.Parts, { components: { Text } }) });
 var AssistantMessage = () => /* @__PURE__ */ jsx2(MessagePrimitive.Root, { style: { display: "contents" }, children: /* @__PURE__ */ jsx2(
   MessagePrimitive.Parts,
   {
     components: {
-      Text: ({ text }) => text ? /* @__PURE__ */ jsx2("div", { className: "sa-msg sa-assistant", children: text }) : null,
+      Text: ({ text }) => text ? /* @__PURE__ */ jsx2("div", { className: "sa-msg sa-assistant sa-md", children: /* @__PURE__ */ jsx2(Markdown, { remarkPlugins: [remarkGfm], components: mdComponents, children: text }) }) : null,
       tools: { Fallback: ToolCard }
     }
   }

package/dist/server/index.d.ts

@@ -2,16 +2,17 @@ import { ThreadMeta } from '../protocol.js';
 export { AgentEvent, ChatRequest } from '../protocol.js';
 import { z } from 'zod';
 import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 
 declare const configSchema: z.ZodObject<{
     spec: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
     baseUrl: z.ZodString;
-    llm: z.ZodObject<{
+    llm: z.ZodOptional<z.ZodObject<{
         baseUrl: z.ZodString;
         apiKey: z.ZodString;
         model: z.ZodString;
         temperature: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>;
+    }, z.core.$strip>>;
     allow: z.ZodArray<z.ZodString>;
     allowedOrigins: z.ZodArray<z.ZodString>;
     anonymous: z.ZodOptional<z.ZodBoolean>;
@@ -28,11 +29,11 @@ declare const configSchema: z.ZodObject<{
             url: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>]>>>;
-        embeddings: z.ZodObject<{
+        embeddings: z.ZodOptional<z.ZodObject<{
             model: z.ZodString;
             baseUrl: z.ZodOptional<z.ZodString>;
             apiKey: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
+        }, z.core.$strip>>;
         topK: z.ZodDefault<z.ZodNumber>;
         ttlMs: z.ZodDefault<z.ZodNumber>;
         maxSourceBytes: z.ZodDefault<z.ZodNumber>;
@@ -51,7 +52,10 @@ declare const configSchema: z.ZodObject<{
 type AgentConfigInput = z.input<typeof configSchema>;
 type AgentConfig = z.output<typeof configSchema>;
 /** Validates config; also requires getAuth or anonymous:true (checked by caller with the function in hand). */
-declare function parseConfig(input: unknown, hasGetAuth: boolean): AgentConfig;
+declare function parseConfig(input: unknown, hasGetAuth: boolean, injected?: {
+    model?: boolean;
+    embeddings?: boolean;
+}): AgentConfig;
 
 interface UrlGuardOptions {
     /** Pinned origin from config. Requests may only go here. */
@@ -187,7 +191,16 @@ interface AuthResult {
     /** Headers forwarded to your API (e.g. Authorization, Cookie). Never shown to the LLM. */
     headers?: Record<string, string>;
 }
+/** Same shape as LangChain's Embeddings, minimal so any adapter fits. */
+interface EmbeddingsLike {
+    embedDocuments(texts: string[]): Promise<number[][]>;
+    embedQuery(text: string): Promise<number[]>;
+}
 interface CreateAgentOptions extends AgentConfigInput {
+    /** Your own chat model (e.g. workersAiChatModel from sideagent/workers-ai). Use instead of `llm`, never with it. It must support bindTools(). */
+    model?: BaseChatModel;
+    /** Your own embeddings, used instead of knowledge.embeddings. */
+    embeddings?: EmbeddingsLike;
     getAuth?: (request: Request) => AuthResult | Promise<AuthResult>;
     /** Throw to reject a turn (rate limiting, quota). */
     beforeTurn?: (ctx: {
@@ -244,4 +257,4 @@ declare function honoHandler(agent: Agent): (c: {
 /** Express (use express.json() before it): `app.post("/agent", expressHandler(agent))` and `app.options("/agent", expressHandler(agent))` */
 declare function expressHandler(agent: Agent): (req: any, res: any) => Promise<any>;
 
-export { type Agent, type AgentConfig, type AgentConfigInput, type AuditEvent, type AuthResult, type CreateAgentOptions, type DoctorReport, KnowledgeBase, type KnowledgeSourceInput, MemoryThreadStore, MemoryVectorStore, type ThreadStore, type VectorStore, assertAllowedUrl, chunkText, configSchema, createAgent, expressHandler, honoHandler, htmlToText, nextRoute, parseConfig };
+export { type Agent, type AgentConfig, type AgentConfigInput, type AuditEvent, type AuthResult, type CreateAgentOptions, type DoctorReport, type EmbeddingsLike, KnowledgeBase, type KnowledgeSourceInput, MemoryThreadStore, MemoryVectorStore, type ThreadStore, type VectorStore, assertAllowedUrl, chunkText, configSchema, createAgent, expressHandler, honoHandler, htmlToText, nextRoute, parseConfig };

package/dist/server/index.js

@@ -6,8 +6,8 @@ var knowledgeSchema = z.object({
   sources: z.array(z.object({ id: z.string().min(1).max(64), title: z.string().min(1).max(200), content: z.string() })).default([]),
   /** Pages the server fetches itself (never model-chosen). Public hosts only unless allowPrivateNetworks. */
   urls: z.array(z.union([url, z.object({ url, title: z.string().max(200).optional() })])).default([]),
-  /** OpenAI-compatible /embeddings endpoint. baseUrl and apiKey default to the llm ones. */
-  embeddings: z.object({ model: z.string().min(1), baseUrl: url.optional(), apiKey: z.string().min(1).optional() }),
+  /** OpenAI-compatible /embeddings endpoint. baseUrl and apiKey default to the llm ones. Omit when you pass the `embeddings` option to createAgent. */
+  embeddings: z.object({ model: z.string().min(1), baseUrl: url.optional(), apiKey: z.string().min(1).optional() }).optional(),
   topK: z.number().int().min(1).max(12).default(4),
   ttlMs: z.number().int().positive().default(36e5),
   maxSourceBytes: z.number().int().positive().default(2e5),
@@ -17,12 +17,13 @@ var knowledgeSchema = z.object({
 var configSchema = z.object({
   spec: z.union([z.string(), z.record(z.string(), z.unknown())]),
   baseUrl: url,
+  /** OpenAI-compatible endpoint. Give either this or the `model` option of createAgent, never both. */
   llm: z.object({
     baseUrl: url,
     apiKey: z.string().min(1, "llm.apiKey is empty; read it from an env var on the server"),
     model: z.string().min(1),
     temperature: z.number().min(0).max(2).optional()
-  }),
+  }).optional(),
   allow: z.array(z.string()).min(1, "allow is empty; list operationIds, tags or globs to expose"),
   allowedOrigins: z.array(z.string().url()).min(1, "allowedOrigins is required"),
   anonymous: z.boolean().optional(),
@@ -47,7 +48,7 @@ var configSchema = z.object({
     maxTools: 40
   })
 }).strict();
-function parseConfig(input, hasGetAuth) {
+function parseConfig(input, hasGetAuth, injected = {}) {
   const result = configSchema.safeParse(input);
   if (!result.success) {
     const lines = result.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`);
@@ -57,6 +58,18 @@ ${lines.join("\n")}`);
   if (!hasGetAuth && !result.data.anonymous) {
     throw new Error("Invalid agent config:\n  - getAuth: provide getAuth(request) or set anonymous: true explicitly");
   }
+  const { llm, knowledge } = result.data;
+  const fail = (msg) => {
+    throw new Error(`Invalid agent config:
+  - ${msg}`);
+  };
+  if (llm && injected.model) fail("llm and model are mutually exclusive: pass llm for an OpenAI-compatible endpoint, or model for your own chat model");
+  if (!llm && !injected.model) fail("no model: pass llm ({ baseUrl, apiKey, model }) or model (a LangChain BaseChatModel)");
+  if (knowledge?.embeddings && injected.embeddings) fail("knowledge.embeddings and the embeddings option are mutually exclusive");
+  if (knowledge && !knowledge.embeddings && !injected.embeddings) fail("knowledge needs knowledge.embeddings (HTTP endpoint) or the embeddings option");
+  if (knowledge?.embeddings && !llm && !(knowledge.embeddings.baseUrl && knowledge.embeddings.apiKey)) {
+    fail("knowledge.embeddings needs baseUrl and apiKey when llm is not set");
+  }
   return result.data;
 }
 
@@ -112,7 +125,7 @@ function assertPublicUrl(url2, allowPrivateNetworks) {
 // src/server/create-agent.ts
 import { HumanMessage } from "@langchain/core/messages";
 import { Command as Command2 } from "@langchain/langgraph";
-import { OpenAIEmbeddings } from "@langchain/openai";
+import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai";
 import { z as z2 } from "zod";
 
 // src/server/approval.ts
@@ -152,7 +165,6 @@ async function verifyApproval(secret, token, claims) {
 
 // src/server/graph.ts
 import { SystemMessage, ToolMessage } from "@langchain/core/messages";
-import { ChatOpenAI } from "@langchain/openai";
 import {
   Command,
   END,
@@ -195,8 +207,8 @@ async function readCapped(res, max) {
   let size = 0;
   let truncated = false;
   for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
+    const { done: done2, value } = await reader.read();
+    if (done2) break;
     size += value.byteLength;
     if (size > max) {
       truncated = true;
@@ -606,7 +618,7 @@ function redact(value) {
 
 // src/server/graph.ts
 var APPROVAL_TTL_MS = 10 * 6e4;
-function buildGraph({ config, ops, secret, checkpointer, onAudit, knowledge }) {
+function buildGraph({ config, ops, secret, checkpointer, onAudit, knowledge, model: baseModel, bindOptions }) {
   const byName = new Map(ops.map((o) => [o.operationId, o]));
   const toolDefs = ops.map((o) => ({
     type: "function",
@@ -623,13 +635,8 @@ function buildGraph({ config, ops, secret, checkpointer, onAudit, knowledge }) {
       }
     });
   }
-  const model = new ChatOpenAI({
-    model: config.llm.model,
-    apiKey: config.llm.apiKey,
-    temperature: config.llm.temperature,
-    streaming: true,
-    configuration: { baseURL: config.llm.baseUrl }
-  }).bindTools(toolDefs, { parallel_tool_calls: false });
+  if (!baseModel.bindTools) throw new Error("The chat model does not support bindTools(), which sideagent needs for tool calling.");
+  const model = baseModel.bindTools(toolDefs, bindOptions);
   const audit = (e) => {
     try {
       void Promise.resolve(onAudit?.({ ...e, args: redact(e.args) })).catch(() => {
@@ -768,6 +775,31 @@ function buildGraph({ config, ops, secret, checkpointer, onAudit, knowledge }) {
   return new StateGraph(MessagesAnnotation).addNode("agent", agentNode).addNode("tools", toolsNode).addEdge(START, "agent").addConditionalEdges("agent", route, ["tools", END]).addEdge("tools", "agent").compile({ checkpointer: checkpointer ?? new MemorySaver() });
 }
 
+// src/server/als.ts
+import { AsyncLocalStorageProviderSingleton } from "@langchain/core/singletons";
+var done;
+function ensureAsyncLocalStorage() {
+  done ??= (async () => {
+    const spec = "node:async_hooks";
+    let ALS = globalThis.AsyncLocalStorage;
+    if (!ALS) {
+      try {
+        ALS = (await import(
+          /* @vite-ignore */
+          spec
+        )).AsyncLocalStorage;
+      } catch {
+        console.warn(
+          '[sideagent] AsyncLocalStorage is unavailable, so approval pauses will fail. On Cloudflare Workers add "nodejs_compat" (or "nodejs_als") to compatibility_flags.'
+        );
+        return;
+      }
+    }
+    AsyncLocalStorageProviderSingleton.initializeGlobalInstance(new ALS());
+  })();
+  return done;
+}
+
 // src/server/history.ts
 function textOf(content) {
   if (typeof content === "string") return content;
@@ -844,13 +876,15 @@ var chatBody = z2.union([
   })
 ]);
 var enc2 = encodeURIComponent;
+var PING_TOOL = { type: "function", function: { name: "ping", description: "ping", parameters: { type: "object", properties: {} } } };
 var MAX_BODY = 256 * 1024;
 function json(status, body, extra = {}) {
   return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", ...extra } });
 }
 async function createAgent(options) {
-  const { getAuth, beforeTurn, onAudit, checkpointer, threadStore: givenStore, vectorStore, ...data } = options;
-  const config = parseConfig(data, !!getAuth);
+  const { getAuth, beforeTurn, onAudit, checkpointer, threadStore: givenStore, vectorStore, model: givenModel, embeddings: givenEmbeddings, ...data } = options;
+  await ensureAsyncLocalStorage();
+  const config = parseConfig(data, !!getAuth, { model: !!givenModel, embeddings: !!givenEmbeddings });
   const ops = await loadOperations(config.spec, config.allow, config.limits.maxTools);
   const secret = config.approvalSecret ?? crypto.randomUUID() + crypto.randomUUID();
   if (!config.approvalSecret) {
@@ -869,7 +903,7 @@ async function createAgent(options) {
       throw new Error(`An allowlisted operation is named "${SEARCH_TOOL}", which is reserved for knowledge search`);
     }
     const k = config.knowledge;
-    const embedder = new OpenAIEmbeddings({
+    const embedder = givenEmbeddings ?? new OpenAIEmbeddings({
       model: k.embeddings.model,
       apiKey: k.embeddings.apiKey ?? config.llm.apiKey,
       configuration: { baseURL: k.embeddings.baseUrl ?? config.llm.baseUrl }
@@ -884,7 +918,9 @@ async function createAgent(options) {
     const timedOut = await Promise.race([loading.then(() => false), new Promise((r) => setTimeout(() => r(true), 6e4))]);
     if (timedOut) console.warn("[sideagent] knowledge is still loading after 60s; search results may be incomplete until it finishes.");
   }
-  const graph = buildGraph({ config, ops, secret, checkpointer, onAudit, knowledge });
+  const llm = config.llm;
+  const model = givenModel ?? new ChatOpenAI({ model: llm.model, apiKey: llm.apiKey, temperature: llm.temperature, streaming: true, configuration: { baseURL: llm.baseUrl } });
+  const graph = buildGraph({ config, ops, secret, checkpointer, onAudit, knowledge, model, bindOptions: givenModel ? void 0 : { parallel_tool_calls: false } });
   const active = /* @__PURE__ */ new Map();
   async function handler(request) {
     const origin = request.headers.get("origin");
@@ -1016,31 +1052,42 @@ async function createAgent(options) {
       headers: { ...cors, "content-type": "text/event-stream", "cache-control": "no-store" }
     });
   }
-  async function doctor() {
-    const checks = [];
-    checks.push({ name: "spec", ok: true, detail: `${ops.length} operation(s) exposed` });
-    if (secret === config.approvalSecret) checks.push({ name: "approvalSecret", ok: true, detail: "set" });
-    else checks.push({ name: "approvalSecret", ok: false, detail: "not set; random per instance" });
+  async function checkInjectedModel(m) {
+    try {
+      if (!m.bindTools) return { name: "llm tool calling", ok: false, detail: "model has no bindTools()" };
+      const reply = await m.bindTools([PING_TOOL]).invoke("Call the ping tool.");
+      const called = (reply.tool_calls?.length ?? 0) > 0;
+      return { name: "llm tool calling", ok: called, detail: called ? "supported" : "model did not return a tool call" };
+    } catch (e) {
+      return { name: "llm", ok: false, detail: e.message };
+    }
+  }
+  async function checkHttpLlm(cfg) {
     try {
-      const res = await fetch(`${config.llm.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+      const res = await fetch(`${cfg.baseUrl.replace(/\/$/, "")}/chat/completions`, {
         method: "POST",
-        headers: { "content-type": "application/json", authorization: `Bearer ${config.llm.apiKey}` },
+        headers: { "content-type": "application/json", authorization: `Bearer ${cfg.apiKey}` },
         body: JSON.stringify({
-          model: config.llm.model,
+          model: cfg.model,
           messages: [{ role: "user", content: "Call the ping tool." }],
-          tools: [{ type: "function", function: { name: "ping", description: "ping", parameters: { type: "object", properties: {} } } }],
+          tools: [PING_TOOL],
           tool_choice: { type: "function", function: { name: "ping" } }
         })
       });
-      if (!res.ok) checks.push({ name: "llm", ok: false, detail: `HTTP ${res.status}` });
-      else {
-        const j = await res.json();
-        const called = j?.choices?.[0]?.message?.tool_calls?.length > 0;
-        checks.push({ name: "llm tool calling", ok: called, detail: called ? "supported" : "model did not return a tool call" });
-      }
+      if (!res.ok) return { name: "llm", ok: false, detail: `HTTP ${res.status}` };
+      const j = await res.json();
+      const called = j?.choices?.[0]?.message?.tool_calls?.length > 0;
+      return { name: "llm tool calling", ok: called, detail: called ? "supported" : "model did not return a tool call" };
     } catch (e) {
-      checks.push({ name: "llm", ok: false, detail: e.message });
+      return { name: "llm", ok: false, detail: e.message };
     }
+  }
+  async function doctor() {
+    const checks = [];
+    checks.push({ name: "spec", ok: true, detail: `${ops.length} operation(s) exposed` });
+    if (secret === config.approvalSecret) checks.push({ name: "approvalSecret", ok: true, detail: "set" });
+    else checks.push({ name: "approvalSecret", ok: false, detail: "not set; random per instance" });
+    checks.push(await (givenModel ? checkInjectedModel(givenModel) : checkHttpLlm(config.llm)));
     if (knowledge) {
       const st = knowledge.status();
       const bad = st.filter((x) => x.error);
@@ -1090,8 +1137,8 @@ function expressHandler(agent) {
     if (!r.body) return res.end();
     const reader = r.body.getReader();
     for (; ; ) {
-      const { done, value } = await reader.read();
-      if (done) break;
+      const { done: done2, value } = await reader.read();
+      if (done2) break;
       res.write(value);
     }
     res.end();

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,6 @@
 {
   "name": "sideagent",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -10,27 +10,44 @@
     },
     "./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"
     },
+    "./keys": {
+      "types": "./dist/keys.d.ts",
+      "import": "./dist/keys.js"
+    },
     "./testing": {
       "types": "./dist/testing/mock-llm.d.ts",
       "import": "./dist/testing/mock-llm.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "!skills/**/evals"
   ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
+    "format": "prettier --write src demo",
+    "format:check": "prettier --check src demo",
     "demo:api": "tsx demo/server.ts",
-    "demo": "tsx demo/server.ts & vite demo"
+    "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",
@@ -39,6 +56,8 @@
     "@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": {
@@ -56,6 +75,7 @@
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^5.0.0",
     "hono": "^4.9.0",
+    "prettier": "^3.9.10",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.5.0",

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"`. For an agent hosted on sideagent Cloud, pass `publishableKey="pk_live_…"` instead of `endpoint`.
+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.