@maintainer-pro/ai-server 0.1.1 → 0.1.3

package/README.md

@@ -11,20 +11,21 @@ It is **not** what you ship as the production website. Without this process, `lo
 ## Quick start
 
 ```bash
-npx --yes @maintainer-pro/ai-server
+npx --yes @maintainer-pro/ai-server@latest
 ```
 
 Put a `.env` in the current directory (from the admin setup guide or by hand). CLI flags override env.
 
-Requires **Node.js 22+**, [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) next to this package (for `/ai-ui.iife.js`), and one authenticated coding-agent CLI.
+Requires **Node.js 22+** and one authenticated coding-agent CLI. `npx` also installs [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) so `GET /ai-ui.iife.js` is available.
 
 ## Routes
 
 | Path | Purpose |
 |------|---------|
 | `GET` / `POST /api/chat` | Chat (agent + Maintainer Pro store) |
-| `GET /embed-config.js` | Client keys for the widget (`window.__MAINTAINER_PRO__`) |
-| `GET /ai-ui.iife.js` | Embed widget from `node_modules/@maintainer-pro/ai-ui` (unless a file exists in `AI_SERVER_UI`) |
+| `WS /api/ws` (also `/ws`) | Live AI events (`subscribe`, `chat.run`, `message.created`) |
+| `GET /embed-config.js` | `window.__MAINTAINER_PRO__` — `aiServerUrl`, `apiUrl`, `aiServerWsUrl`, client keys |
+| `GET /ai-ui.iife.js` | Embed widget from `@maintainer-pro/ai-ui` (unless a file exists in `AI_SERVER_UI`) |
 | other paths | Static files from `AI_SERVER_UI` |
 
 A copied `ai-ui.iife.js` in the UI folder is served first and will not update when you `npm update @maintainer-pro/ai-ui`. Prefer the `node_modules` copy, then restart this process.
@@ -41,11 +42,12 @@ A copied `ai-ui.iife.js` in the UI folder is served first and will not update wh
 | `MAINTAINER_PRO_URL` | Admin base URL |
 | `MAINTAINER_PRO_API_KEY` | Server API key |
 | `MAINTAINER_PRO_CLIENT_API_KEY` | Client key (served at `/embed-config.js`) |
+| `AI_SERVER_URL` | Public chat origin (e.g. `http://localhost:3100`). Included in `/embed-config.js` as `aiServerUrl` / `apiUrl`. If unset, derived from the request Host. |
 | `AI_CLI_PROVIDER` | `auto` \| `claude` \| `cursor` \| `antigravity` |
 | `AI_SERVER_PRODUCT_DESCRIPTION` | Optional product text for the agent prompt |
 
 ```bash
-npx --yes @maintainer-pro/ai-server --port 3100 --ui . --workspace .
+npx --yes @maintainer-pro/ai-server@latest --port 3100 --ui . --workspace .
 ```
 
 ## Related packages
@@ -54,4 +56,3 @@ npx --yes @maintainer-pro/ai-server --port 3100 --ui . --workspace .
 |---------|------|
 | [`@maintainer-pro/ai-cli`](https://www.npmjs.com/package/@maintainer-pro/ai-cli) | Talks to coding agents |
 | [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) | Embed widget (`/ai-ui.iife.js`) |
-| [`@maintainer-pro/setup`](https://www.npmjs.com/package/@maintainer-pro/setup) | Download the sandbox setup guide |

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 /**
- *   npx --yes @maintainer-pro/ai-server
+ *   npx --yes @maintainer-pro/ai-server@latest
  */
 import "../src/server.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maintainer-pro/ai-server",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Node HTTP server for Maintainer Pro chat. Uses @maintainer-pro/ai-cli to talk to coding agents.",
   "keywords": [
     "maintainer-pro",
@@ -26,7 +26,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@maintainer-pro/ai-cli": "^0.1.2"
+    "@maintainer-pro/ai-cli": "^0.1.5",
+    "@maintainer-pro/ai-ui": "^0.2.3",
+    "ws": "^8.21.3"
   },
   "engines": {
     "node": ">=22"

package/src/server.mjs

@@ -5,21 +5,21 @@
  *
  * Config from .env (or --env-file). CLI flags override env.
  */
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   createChatHandler,
   createDefaultSystemPrompt,
+  createLogger,
   createMaintainerProStoreFromEnv,
+  parseIgnorePathsEnv,
+  resolveIgnorePaths,
 } from "@maintainer-pro/ai-cli";
-
-const log = (msg) => console.log(`[ai-server] ${msg}`);
-const fail = (msg) => {
-  console.error(`[ai-server] ${msg}`);
-  process.exit(1);
-};
+import { attachChatWebSocket } from "./ws.mjs";
 
 function parseArgs(argv) {
   /** @type {Record<string, string | boolean>} */
@@ -59,12 +59,13 @@ function loadEnvFile(file) {
   }
 }
 
-function printHelp() {
+const args = parseArgs(process.argv.slice(2));
+if (args.help) {
   console.log(`Maintainer Pro AI server
 
 Usage:
-  npx @maintainer-pro/ai-server
-  npx @maintainer-pro/ai-server --port 3000 --ui . --workspace .
+  npx @maintainer-pro/ai-server@latest
+  npx @maintainer-pro/ai-server@latest --port 3000 --ui . --workspace .
 
 Flags override .env. Preferred config is env (from the admin setup guide).
 
@@ -73,9 +74,32 @@ Flags override .env. Preferred config is env (from the admin setup guide).
   --workspace <dir>    Agent edit root (AI_CLI_WORKSPACE)
   --env-file <path>    Env file (default: ./.env)
   --cors-origin <url>  CORS origin (CORS_ORIGIN)
+
+Logging (env):
+  LOG_LEVEL=info|debug|warn|error|silent
+  AI_LOG_LEVEL=…                           alias for LOG_LEVEL
+  NODE_ENV=development                     defaults to debug logs (auto if unset)
+  LOG_PRETTY=0                             disable pretty TTY output
 `);
+  process.exit(0);
+}
+
+const envFile = path.resolve(
+  typeof args.envFile === "string" ? args.envFile : path.join(process.cwd(), ".env")
+);
+loadEnvFile(envFile);
+
+// Local sidecar defaults to development (debug logs) unless explicitly set.
+if (!process.env.NODE_ENV?.trim()) {
+  process.env.NODE_ENV = "development";
 }
 
+const logger = createLogger("ai-server");
+const fail = (msg) => {
+  logger.fatal(msg);
+  process.exit(1);
+};
+
 function contentType(file) {
   if (file.endsWith(".html")) return "text/html; charset=utf-8";
   if (file.endsWith(".js")) return "text/javascript; charset=utf-8";
@@ -99,14 +123,25 @@ function resolveUiFile(uiDir, pathname) {
   return null;
 }
 
+function tryResolveIife(from) {
+  try {
+    return createRequire(from).resolve("@maintainer-pro/ai-ui");
+  } catch {
+    return null;
+  }
+}
+
 function findIife() {
   const here = path.dirname(fileURLToPath(import.meta.url));
+  const cwdPkg = path.join(process.cwd(), "package.json");
   const candidates = [
+    tryResolveIife(import.meta.url),
+    fs.existsSync(cwdPkg) ? tryResolveIife(cwdPkg) : null,
     path.resolve(process.cwd(), "node_modules/@maintainer-pro/ai-ui/dist/ai-ui.iife.js"),
     path.resolve(here, "../../ai-ui/dist/ai-ui.iife.js"),
     path.resolve(here, "../../../node_modules/@maintainer-pro/ai-ui/dist/ai-ui.iife.js"),
   ];
-  return candidates.find((file) => fs.existsSync(file)) ?? null;
+  return candidates.find((file) => file && fs.existsSync(file)) ?? null;
 }
 
 async function toFetchRequest(req) {
@@ -138,17 +173,12 @@ async function send(res, response) {
   res.end(Buffer.from(await response.arrayBuffer()));
 }
 
-const args = parseArgs(process.argv.slice(2));
-if (args.help) {
-  printHelp();
-  process.exit(0);
+function toHttpWsUrl(httpUrl) {
+  const u = new URL(httpUrl);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  return u.toString().replace(/\/$/, "");
 }
 
-const envFile = path.resolve(
-  typeof args.envFile === "string" ? args.envFile : path.join(process.cwd(), ".env")
-);
-loadEnvFile(envFile);
-
 const port = Number(args.port || process.env.PORT || 3000);
 const workspaceDir = path.resolve(
   args.workspace || process.env.AI_CLI_WORKSPACE || process.cwd()
@@ -162,7 +192,22 @@ const corsOrigin =
 
 process.env.AI_CLI_WORKSPACE = workspaceDir;
 
-const db = createMaintainerProStoreFromEnv();
+const runningTurns = new Set();
+/** One active AI turn per conversation — prevents raced double promotes. */
+const runningByConversation = new Map();
+/** Turns that arrived while the conversation was busy — run after unlock. */
+const deferredTurns = new Map();
+/** @type {{ publish: (conversationId: string, payload: Record<string, unknown>) => void; close: () => void }} */
+let hub = { publish() {}, close() {} };
+/** @type {(event: { conversationId: string; message: { id?: string; content?: string; senderType?: string | null; senderName?: string | null } }) => Promise<void>} */
+let runWorkingTurn = async () => {};
+
+const db = createMaintainerProStoreFromEnv({
+  logger,
+  onWorkingTurn: (event) => {
+    void runWorkingTurn(event);
+  },
+});
 if (!db) {
   fail(
     `Set MAINTAINER_PRO_URL and MAINTAINER_PRO_API_KEY (env file: ${envFile}).`
@@ -173,14 +218,255 @@ const productDescription =
   process.env.AI_SERVER_PRODUCT_DESCRIPTION?.trim() ||
   "This product uses Maintainer Pro. When the user asks for a change, edit source files in the workspace using the coding agent CLI. Do not invent JSON tool calls.";
 
+const ignorePaths = resolveIgnorePaths(
+  parseIgnorePathsEnv(process.env.AI_CLI_IGNORE_PATHS)
+);
+
 const handlers = createChatHandler({
-  systemPrompt: createDefaultSystemPrompt({ productDescription }),
+  systemPrompt: createDefaultSystemPrompt({ productDescription, ignorePaths }),
   workspaceDir,
   db,
+  logger,
 });
 
+async function historyForTurn(conversationId, userMessage, userMessageId) {
+  const history = db.listMessages ? await db.listMessages(conversationId) : [];
+  let rows = history.filter(
+    (row) =>
+      (row.role === "user" || row.role === "assistant") &&
+      row.provider !== "working" &&
+      Boolean(row.content?.trim())
+  );
+  // Exclude later queued user turns so the model answers the current working
+  // message, not messages still waiting behind it.
+  if (userMessageId) {
+    const end = rows.findIndex((row) => row.id === userMessageId);
+    if (end >= 0) {
+      rows = rows.slice(0, end + 1);
+    } else {
+      rows = rows.filter(
+        (row) =>
+          row.queueStatus !== "queued" ||
+          row.content === userMessage
+      );
+    }
+  } else {
+    rows = rows.filter((row) => row.queueStatus !== "queued");
+  }
+  const messages = rows.map((row) => ({ role: row.role, content: row.content }));
+  if (
+    userMessage &&
+    !messages.some(
+      (row) => row.role === "user" && row.content === userMessage
+    )
+  ) {
+    messages.push({ role: "user", content: userMessage });
+  }
+  return messages;
+}
+
+async function runChatPost(body) {
+  logger.debug(
+    {
+      conversationId: body.conversationId,
+      skipPersistUser: body.skipPersistUser,
+      userMessageId: body.userMessageId,
+      messageCount: Array.isArray(body.messages) ? body.messages.length : 0,
+    },
+    "runChatPost"
+  );
+  const response = await handlers.POST(
+    new Request("http://127.0.0.1/api/chat", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    })
+  );
+  const text = await response.text();
+  let data = {};
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { error: text || "invalid chat response" };
+  }
+  logger.debug(
+    { conversationId: body.conversationId, ok: response.ok, status: response.status },
+    "runChatPost done"
+  );
+  return { ok: response.ok, status: response.status, data };
+}
+
+function publishChatResult(conversationId, result, fallbackMessageId, parentMessageId) {
+  if (!conversationId) return;
+  if (!result.ok) {
+    logger.debug({ conversationId, status: result.status }, "publish chat.run.failed");
+    hub.publish(conversationId, {
+      type: "chat.run.failed",
+      conversationId,
+      error: result.data?.error ?? `chat failed (${result.status})`,
+      userMessageId: parentMessageId,
+    });
+    return;
+  }
+  const reply = typeof result.data?.text === "string" ? result.data.text : "";
+  if (!reply) {
+    logger.debug({ conversationId }, "skip publish (empty reply)");
+    return;
+  }
+  const messageId =
+    typeof result.data?.messageId === "string"
+      ? result.data.messageId
+      : fallbackMessageId;
+  logger.debug(
+    { conversationId, messageId, provider: result.data?.provider, chars: reply.length },
+    "publish message.created"
+  );
+  hub.publish(conversationId, {
+    type: "message.created",
+    conversationId,
+    message: {
+      id: messageId,
+      role: "assistant",
+      content: reply,
+      senderType: "ai",
+      senderName: "AI",
+      provider: result.data?.provider ?? null,
+      parentMessageId: parentMessageId ?? null,
+    },
+  });
+}
+
+runWorkingTurn = async (event) => {
+  const userMessageId = event.message.id;
+  const content = event.message.content ?? "";
+  const conversationId = event.conversationId;
+  if (!userMessageId || !content.trim()) {
+    logger.debug({ event }, "skip working turn (empty)");
+    return;
+  }
+  if (runningTurns.has(userMessageId)) {
+    logger.debug({ userMessageId }, "skip working turn (already running)");
+    return;
+  }
+  const busy = runningByConversation.get(conversationId);
+  if (busy && busy !== userMessageId) {
+    deferredTurns.set(conversationId, event);
+    logger.info(
+      { conversationId, busy, userMessageId },
+      "defer working turn (conversation busy)"
+    );
+    return;
+  }
+  runningTurns.add(userMessageId);
+  runningByConversation.set(conversationId, userMessageId);
+  let nextQueued = null;
+  try {
+    const messages = await historyForTurn(conversationId, content, userMessageId);
+    if (!messages.length) {
+      messages.push({ role: "user", content });
+    }
+    logger.info(
+      {
+        conversationId,
+        userMessageId,
+        historyLength: messages.length,
+      },
+      "ai turn"
+    );
+    hub.publish(conversationId, {
+      type: "chat.turn",
+      conversationId,
+      userMessageId,
+    });
+    const assistantMessageId = randomUUID();
+    const result = await runChatPost({
+      conversationId,
+      messages,
+      userMessage: content,
+      skipPersistUser: true,
+      userMessageId,
+      assistantMessageId,
+      senderType: event.message.senderType === "client" ? "client" : undefined,
+      senderName: event.message.senderName ?? undefined,
+    });
+    publishChatResult(conversationId, result, assistantMessageId, userMessageId);
+    if (!result.ok) {
+      logger.warn({ status: result.status }, "ai turn failed");
+    } else if (
+      result.data?.nextQueued &&
+      typeof result.data.nextQueued.id === "string"
+    ) {
+      nextQueued = result.data.nextQueued;
+    }
+  } catch (err) {
+    logger.error({ err }, "ai turn failed");
+    hub.publish(conversationId, {
+      type: "chat.run.failed",
+      conversationId,
+      error: err instanceof Error ? err.message : String(err),
+      userMessageId,
+    });
+  } finally {
+    runningTurns.delete(userMessageId);
+    if (runningByConversation.get(conversationId) === userMessageId) {
+      runningByConversation.delete(conversationId);
+    }
+    // Prefer explicit next from complete-turn; else a deferred becameWorking event.
+    const deferred = deferredTurns.get(conversationId);
+    if (deferred) deferredTurns.delete(conversationId);
+    const followUp =
+      nextQueued?.id && nextQueued.content?.trim()
+        ? {
+            conversationId,
+            message: {
+              id: nextQueued.id,
+              content: nextQueued.content,
+              senderType: "client",
+            },
+          }
+        : deferred && deferred.message?.id !== userMessageId
+          ? deferred
+          : null;
+    if (followUp) {
+      logger.info(
+        {
+          conversationId,
+          from: userMessageId,
+          next: followUp.message.id,
+          via: nextQueued?.id ? "nextQueued" : "deferred",
+        },
+        "chain next queued turn"
+      );
+      queueMicrotask(() => {
+        void runWorkingTurn(followUp);
+      });
+    }
+  }
+};
+
+function resolveAiServerUrl(req) {
+  const fromEnv = (
+    process.env.AI_SERVER_URL ||
+    process.env.AI_SERVER_BASE_URL ||
+    ""
+  )
+    .trim()
+    .replace(/\/$/, "");
+  if (fromEnv) return fromEnv;
+  const host = req.headers.host?.trim();
+  if (host) {
+    const xfProto = String(req.headers["x-forwarded-proto"] ?? "")
+      .split(",")[0]
+      ?.trim();
+    const proto = xfProto || "http";
+    return `${proto}://${host}`;
+  }
+  return `http://localhost:${port}`;
+}
+
 const server = http.createServer((req, res) => {
   const pathname = (req.url ?? "/").split("?")[0];
+  logger.debug({ method: req.method, pathname }, "http");
   res.setHeader("Access-Control-Allow-Origin", corsOrigin);
   res.setHeader("Access-Control-Allow-Headers", "content-type, authorization");
   res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
@@ -190,24 +476,61 @@ const server = http.createServer((req, res) => {
     return;
   }
   if (pathname === "/embed-config.js") {
-    const payload = {
+    const aiServerUrl = resolveAiServerUrl(req);
+      const payload = {
+      aiServerUrl,
+      apiUrl: `${aiServerUrl}/api/chat`,
+      aiServerWsUrl: `${toHttpWsUrl(aiServerUrl)}/api/ws`,
+      debug: true,
+      logLevel: "debug",
       maintainerProUrl: process.env.MAINTAINER_PRO_URL ?? "",
       maintainerProApiKey:
         process.env.MAINTAINER_PRO_CLIENT_API_KEY ??
         process.env.NEXT_PUBLIC_MAINTAINER_PRO_CLIENT_API_KEY ??
         "",
     };
+    logger.debug({ aiServerUrl }, "embed-config");
     res.setHeader("Content-Type", "text/javascript; charset=utf-8");
     res.end(`window.__MAINTAINER_PRO__=${JSON.stringify(payload)};`);
     return;
   }
   if (pathname === "/api/chat") {
+    logger.info({ method: req.method }, "http /api/chat");
     const handler = req.method === "GET" ? handlers.GET : handlers.POST;
     void toFetchRequest(req)
-      .then((request) => handler(request))
+      .then(async (request) => {
+        const response = await handler(request);
+        if (req.method === "POST") {
+          const clone = response.clone();
+          const text = await clone.text();
+          let data = {};
+          try {
+            data = text ? JSON.parse(text) : {};
+          } catch {
+            data = {};
+          }
+          const conversationId =
+            typeof data.conversationId === "string" ? data.conversationId : "";
+          const parentMessageId =
+            typeof data.parentMessageId === "string"
+              ? data.parentMessageId
+              : undefined;
+          publishChatResult(
+            conversationId,
+            {
+              ok: response.ok,
+              status: response.status,
+              data,
+            },
+            undefined,
+            parentMessageId
+          );
+        }
+        return response;
+      })
       .then((response) => send(res, response))
       .catch((err) => {
-        console.error(err);
+        logger.error({ err }, "chat handler failed");
         res.statusCode = 500;
         res.end("Chat handler failed");
       });
@@ -215,6 +538,11 @@ const server = http.createServer((req, res) => {
   }
   const file = resolveUiFile(uiDir, pathname);
   if (!file) {
+    if (pathname === "/ai-ui.iife.js") {
+      logger.warn(
+        "GET /ai-ui.iife.js 404 — @maintainer-pro/ai-ui is not installed next to ai-server"
+      );
+    }
     res.statusCode = 404;
     res.end("Not found");
     return;
@@ -223,8 +551,265 @@ const server = http.createServer((req, res) => {
   fs.createReadStream(file).pipe(res);
 });
 
-server.listen(port, () => {
-  log(`chat → http://localhost:${port}/api/chat`);
-  log(`ui   → http://localhost:${port}/`);
-  log(`workspace ${workspaceDir}`);
+hub = attachChatWebSocket(server, {
+  logger,
+  onChatRun: async (msg) => {
+    const conversationId =
+      typeof msg.conversationId === "string" ? msg.conversationId : "";
+    const userMessage =
+      typeof msg.userMessage === "string"
+        ? msg.userMessage
+        : typeof msg.content === "string"
+          ? msg.content
+          : "";
+    const userMessageId =
+      typeof msg.userMessageId === "string" ? msg.userMessageId : undefined;
+    logger.info(
+      {
+        conversationId,
+        userMessageId,
+        chars: userMessage.length,
+        hasMessages: Array.isArray(msg.messages),
+        messageCount: Array.isArray(msg.messages) ? msg.messages.length : 0,
+        skipPersistUser: msg.skipPersistUser,
+      },
+      "ws chat.run"
+    );
+    if (userMessageId && runningTurns.has(userMessageId)) {
+      logger.debug({ userMessageId }, "ws chat.run duplicate");
+      return { conversationId, accepted: true, duplicate: true };
+    }
+    if (conversationId) {
+      const busy = runningByConversation.get(conversationId);
+      if (busy && busy !== userMessageId) {
+        if (userMessageId && userMessage.trim()) {
+          deferredTurns.set(conversationId, {
+            conversationId,
+            message: {
+              id: userMessageId,
+              content: userMessage,
+              senderType:
+                typeof msg.senderType === "string" ? msg.senderType : "client",
+              senderName:
+                typeof msg.senderName === "string" ? msg.senderName : null,
+            },
+          });
+          logger.info(
+            { conversationId, busy, userMessageId },
+            "ws chat.run deferred (conversation busy)"
+          );
+          return { conversationId, accepted: true, deferred: true };
+        }
+        logger.warn(
+          { conversationId, busy, userMessageId },
+          "ws chat.run skipped (conversation busy)"
+        );
+        return { conversationId, accepted: false, busy: true };
+      }
+    }
+    let messages = Array.isArray(msg.messages)
+      ? msg.messages.filter(
+          (row) =>
+            row &&
+            (row.role === "user" || row.role === "assistant") &&
+            typeof row.content === "string"
+        )
+      : [];
+    if (!messages.length && conversationId) {
+      messages = await historyForTurn(conversationId, userMessage, userMessageId);
+      logger.info(
+        { conversationId, history: messages.length },
+        "ws chat.run loaded history"
+      );
+    } else if (
+      userMessage &&
+      !messages.some((row) => row.role === "user" && row.content === userMessage)
+    ) {
+      messages.push({ role: "user", content: userMessage });
+    }
+    const assistantMessageId =
+      typeof msg.assistantMessageId === "string" && msg.assistantMessageId
+        ? msg.assistantMessageId
+        : randomUUID();
+    if (userMessageId) runningTurns.add(userMessageId);
+    if (conversationId && userMessageId) {
+      runningByConversation.set(conversationId, userMessageId);
+    }
+    let nextQueued = null;
+    try {
+      hub.publish(conversationId, {
+        type: "chat.turn",
+        conversationId,
+        userMessageId,
+      });
+      const result = await runChatPost({
+        conversationId,
+        messages,
+        userMessage,
+        skipPersistUser: msg.skipPersistUser !== false,
+        userMessageId,
+        assistantMessageId,
+        senderType: typeof msg.senderType === "string" ? msg.senderType : undefined,
+        senderName: typeof msg.senderName === "string" ? msg.senderName : undefined,
+      });
+      publishChatResult(conversationId, result, assistantMessageId, userMessageId);
+      if (!result.ok) {
+        throw new Error(result.data?.error ?? `chat failed (${result.status})`);
+      }
+      if (
+        result.data?.nextQueued &&
+        typeof result.data.nextQueued.id === "string"
+      ) {
+        nextQueued = result.data.nextQueued;
+      }
+      return { conversationId, ...result.data };
+    } finally {
+      if (userMessageId) runningTurns.delete(userMessageId);
+      if (
+        conversationId &&
+        userMessageId &&
+        runningByConversation.get(conversationId) === userMessageId
+      ) {
+        runningByConversation.delete(conversationId);
+      }
+      const deferred = deferredTurns.get(conversationId);
+      if (deferred) deferredTurns.delete(conversationId);
+      const followUp =
+        nextQueued?.id && String(nextQueued.content ?? "").trim()
+          ? {
+              conversationId,
+              message: {
+                id: nextQueued.id,
+                content: nextQueued.content,
+                senderType: "client",
+              },
+            }
+          : deferred && deferred.message?.id !== userMessageId
+            ? deferred
+            : null;
+      if (followUp) {
+        logger.info(
+          {
+            conversationId,
+            from: userMessageId,
+            next: followUp.message.id,
+            via: nextQueued?.id ? "nextQueued" : "deferred",
+          },
+          "chain next queued turn"
+        );
+        queueMicrotask(() => {
+          void runWorkingTurn(followUp);
+        });
+      }
+    }
+  },
 });
+
+async function start() {
+  if (db.ready) {
+    try {
+      const info = await db.ready;
+      logger.info(
+        {
+          conversations: info.conversations,
+          messages: info.messages,
+        },
+        "cache ready"
+      );
+    } catch (err) {
+      logger.warn({ err }, "cache hydrate failed");
+    }
+  }
+
+  const recoverMs = Math.max(
+    5_000,
+    Number(process.env.AI_QUEUE_RECOVER_MS || 20_000) || 20_000
+  );
+  let recoverInFlight = false;
+  const sweepStuckQueues = async (reason) => {
+    if (recoverInFlight || !db.recoverQueue || !db.listConversations) return;
+    recoverInFlight = true;
+    try {
+      const convs = await db.listConversations();
+      for (const conv of convs) {
+        if (runningByConversation.has(conv.id)) continue;
+        const msgs = conv.messages ?? [];
+        const hasWorking = msgs.some(
+          (m) =>
+            m.role === "user" &&
+            m.queueStatus === "working" &&
+            m.senderType !== "developer"
+        );
+        const hasQueued = msgs.some(
+          (m) =>
+            m.role === "user" &&
+            m.queueStatus === "queued" &&
+            m.senderType !== "developer"
+        );
+        if (!hasWorking && !hasQueued) continue;
+        const result = await db.recoverQueue(conv.id);
+        if (result && result.action && result.action !== "noop") {
+          logger.info(
+            {
+              reason,
+              conversationId: conv.id,
+              action: result.action,
+              workingId: result.workingId,
+              promotedId: result.promotedId,
+            },
+            "queue recover"
+          );
+        }
+      }
+    } catch (err) {
+      logger.warn({ err, reason }, "queue recover sweep failed");
+    } finally {
+      recoverInFlight = false;
+    }
+  };
+
+  void sweepStuckQueues("startup");
+  const recoverTimer = setInterval(() => {
+    void sweepStuckQueues("interval");
+  }, recoverMs);
+  if (typeof recoverTimer.unref === "function") recoverTimer.unref();
+
+  server.listen(port, () => {
+    const base =
+      (process.env.AI_SERVER_URL || process.env.AI_SERVER_BASE_URL || "")
+        .trim()
+        .replace(/\/$/, "") || `http://localhost:${port}`;
+    logger.info(`chat → ${base}/api/chat`);
+    logger.info(`ws   → ${toHttpWsUrl(base)}/api/ws`);
+    logger.info(`ui   → ${base}/`);
+    logger.info(`embed-config → ${base}/embed-config.js`);
+    const widget = findIife();
+    if (widget) {
+      logger.info(`widget → ${base}/ai-ui.iife.js`);
+      logger.debug({ widget }, "widget file");
+    } else {
+      logger.warn(
+        "GET /ai-ui.iife.js will 404 — @maintainer-pro/ai-ui is not installed next to ai-server"
+      );
+    }
+    logger.info(`workspace ${workspaceDir}`);
+    logger.info(
+      {
+        logLevel: logger.level,
+        nodeEnv: process.env.NODE_ENV,
+        queueRecoverMs: recoverMs,
+      },
+      "logger ready"
+    );
+  });
+}
+
+void start();
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    db.stop?.();
+    hub.close();
+    process.exit(0);
+  });
+}

package/src/ws.mjs

@@ -0,0 +1,243 @@
+import { WebSocketServer } from "ws";
+
+function rawToText(raw) {
+  if (typeof raw === "string") return raw;
+  if (Buffer.isBuffer(raw)) return raw.toString("utf8");
+  if (ArrayBuffer.isView(raw)) {
+    return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString(
+      "utf8"
+    );
+  }
+  return String(raw ?? "");
+}
+
+function parseJson(raw) {
+  try {
+    const data = JSON.parse(rawToText(raw).trim());
+    if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function sendJson(socket, payload, debug) {
+  if (socket.readyState !== socket.OPEN) {
+    debug?.(
+      { type: payload?.type, readyState: socket.readyState },
+      "ws outbound skipped (not open)"
+    );
+    return;
+  }
+  try {
+    socket.send(JSON.stringify(payload));
+  } catch (err) {
+    debug?.(
+      { type: payload?.type, err: err instanceof Error ? err.message : String(err) },
+      "ws outbound failed"
+    );
+  }
+}
+
+/**
+ * Accepts browser / bridge WebSockets on /api/ws (and /ws).
+ * Clients subscribe to a conversation and receive AI turn events.
+ */
+export function attachChatWebSocket(server, opts) {
+  const logger = opts.logger;
+  const log =
+    opts.log ??
+    ((msg) => {
+      if (logger) logger.info(msg);
+      else console.log(`[ai-server] ${msg}`);
+    });
+  const debug = (obj, msg) => {
+    if (logger?.debug) logger.debug(obj, msg);
+  };
+  const info = (obj, msg) => {
+    if (logger?.info) logger.info(obj, msg);
+    else debug(obj, msg);
+  };
+  const onChatRun = opts.onChatRun;
+  const wss = new WebSocketServer({ noServer: true });
+  /** @type {Map<string, Set<import("ws").WebSocket>>} */
+  const channels = new Map();
+  /** @type {WeakMap<import("ws").WebSocket, Set<string>>} */
+  const socketChannels = new WeakMap();
+
+  const subscribe = (socket, conversationId) => {
+    const id = String(conversationId ?? "").trim();
+    if (!id) return;
+    let set = channels.get(id);
+    if (!set) {
+      set = new Set();
+      channels.set(id, set);
+    }
+    set.add(socket);
+    const owned = socketChannels.get(socket) ?? new Set();
+    owned.add(id);
+    socketChannels.set(socket, owned);
+    debug({ conversationId: id, subscribers: set.size }, "ws subscribe");
+  };
+
+  const unsubscribeAll = (socket) => {
+    const owned = socketChannels.get(socket);
+    if (!owned) return;
+    for (const id of owned) {
+      const set = channels.get(id);
+      if (!set) continue;
+      set.delete(socket);
+      if (set.size === 0) channels.delete(id);
+    }
+    socketChannels.delete(socket);
+  };
+
+  const publish = (conversationId, payload) => {
+    const id = String(conversationId ?? "").trim();
+    if (!id) return;
+    const set = channels.get(id);
+    if (!set?.size) {
+      debug({ conversationId: id, type: payload?.type }, "ws publish (no subscribers)");
+      return;
+    }
+    debug(
+      { conversationId: id, type: payload?.type, subscribers: set.size },
+      "ws publish"
+    );
+    for (const socket of [...set]) {
+      sendJson(socket, payload, debug);
+    }
+  };
+
+  wss.on("connection", (socket) => {
+    debug({ clients: wss.clients.size }, "ws connection open");
+    sendJson(socket, { type: "hello", role: "ai_server" }, debug);
+    socket.on("message", (raw) => {
+      void (async () => {
+        const text = rawToText(raw);
+        const msg = parseJson(raw);
+        if (!msg) {
+          log(`ws inbound unparsed (${text.slice(0, 200)})`);
+          return;
+        }
+        const type = typeof msg.type === "string" ? msg.type : "";
+        if (type && type !== "ping") {
+          info(
+            {
+              type,
+              conversationId: msg.conversationId,
+              userMessageId: msg.userMessageId,
+              requestId: msg.requestId,
+              bytes: text.length,
+            },
+            "ws inbound"
+          );
+        }
+        if (type === "ping") {
+          sendJson(socket, { type: "pong" }, debug);
+          return;
+        }
+        if (type === "subscribe") {
+          const ids = [];
+          if (typeof msg.conversationId === "string") {
+            ids.push(msg.conversationId);
+          }
+          if (Array.isArray(msg.channels)) {
+            for (const channel of msg.channels) {
+              if (typeof channel !== "string") continue;
+              ids.push(
+                channel.startsWith("conversation:")
+                  ? channel.slice("conversation:".length)
+                  : channel
+              );
+            }
+          }
+          debug({ channels: ids }, "ws subscribe request");
+          for (const id of ids.slice(0, 50)) subscribe(socket, id);
+          return;
+        }
+        if (type === "chat.run" && onChatRun) {
+          const requestId =
+            typeof msg.requestId === "string" ? msg.requestId : undefined;
+          debug(
+            {
+              requestId,
+              conversationId: msg.conversationId,
+              userMessageId: msg.userMessageId,
+            },
+            "ws chat.run"
+          );
+          try {
+            const result = await onChatRun(msg);
+            info(
+              {
+                requestId,
+                conversationId: msg.conversationId,
+                duplicate: result?.duplicate === true,
+                ok: result?.ok !== false,
+              },
+              "ws chat.run done"
+            );
+            sendJson(
+              socket,
+              {
+                type: "chat.accepted",
+                requestId,
+                ok: true,
+                ...result,
+              },
+              debug
+            );
+          } catch (err) {
+            log(
+              `ws chat.run failed: ${err instanceof Error ? err.message : err}`
+            );
+            sendJson(
+              socket,
+              {
+                type: "chat.error",
+                requestId,
+                error: err instanceof Error ? err.message : "chat.run failed",
+              },
+              debug
+            );
+          }
+          return;
+        }
+        info({ type: type || "(missing)" }, "ws inbound ignored (unknown type)");
+      })().catch((err) => {
+        log(`ws handler failed: ${err instanceof Error ? err.message : err}`);
+      });
+    });
+    socket.on("close", () => {
+      debug({}, "ws connection close");
+      unsubscribeAll(socket);
+    });
+  });
+
+  server.on("upgrade", (req, socket, head) => {
+    const pathname = (req.url ?? "/").split("?")[0];
+    if (pathname !== "/api/ws" && pathname !== "/ws") {
+      socket.destroy();
+      return;
+    }
+    debug({ pathname }, "ws upgrade");
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit("connection", ws, req);
+    });
+  });
+
+  return {
+    publish,
+    close() {
+      for (const socket of wss.clients) {
+        try {
+          socket.close();
+        } catch {
+          /* ignore */
+        }
+      }
+      wss.close();
+    },
+  };
+}