@maintainer-pro/ai-server 0.1.4 → 0.1.6

package/src/server.mjs

@@ -1,9 +1,9 @@
-#!/usr/bin/env node
 /**
  * Maintainer Pro chat HTTP server.
  * Talks to coding agents through @maintainer-pro/ai-cli.
  *
- * Config from .env (or --env-file). CLI flags override env.
+ * Use `startAiServer(options)` from the bridge (one instance per project).
+ * The CLI (`bin/cli.js`) still runs a single standalone listener.
  */
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
@@ -15,9 +15,10 @@ import {
   createChatHandler,
   createDefaultSystemPrompt,
   createLogger,
-  createMaintainerProStoreFromEnv,
+  createMaintainerProStore,
   parseIgnorePathsEnv,
   resolveIgnorePaths,
+  ensureProjectDataDir,
 } from "@maintainer-pro/ai-cli";
 import { attachChatWebSocket } from "./ws.mjs";
 
@@ -39,8 +40,10 @@ function parseArgs(argv) {
   return out;
 }
 
-function loadEnvFile(file) {
-  if (!file || !fs.existsSync(file)) return;
+export function parseEnvFile(file) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  if (!file || !fs.existsSync(file)) return out;
   const text = fs.readFileSync(file, "utf8");
   for (const raw of text.split(/\r?\n/)) {
     const line = raw.trim();
@@ -55,51 +58,23 @@ function loadEnvFile(file) {
     ) {
       value = value.slice(1, -1);
     }
-    if (process.env[key] === undefined) process.env[key] = value;
+    out[key] = value;
   }
+  return out;
 }
 
-const args = parseArgs(process.argv.slice(2));
-if (args.help) {
-  console.log(`Maintainer Pro AI server
-
-Usage:
-  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).
-
-  --port <n>           Listen port (PORT)
-  --ui <dir>           Static UI folder (AI_SERVER_UI)
-  --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);
+function loadEnvFile(file) {
+  const parsed = parseEnvFile(file);
+  for (const [key, value] of Object.entries(parsed)) {
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
 }
 
-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";
+function pickEnv(env, key, fallback = "") {
+  const raw = env?.[key] ?? process.env[key] ?? fallback;
+  return String(raw ?? "").trim();
 }
 
-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";
@@ -110,19 +85,6 @@ function contentType(file) {
   return "application/octet-stream";
 }
 
-function resolveUiFile(uiDir, pathname) {
-  const rel = decodeURIComponent(pathname === "/" ? "/index.html" : pathname);
-  const file = path.normalize(path.join(uiDir, rel));
-  const root = path.resolve(uiDir);
-  if (!file.startsWith(root)) return null;
-  if (fs.existsSync(file) && fs.statSync(file).isFile()) return file;
-  if (pathname === "/ai-ui.iife.js") {
-    const bundled = findIife();
-    if (bundled) return bundled;
-  }
-  return null;
-}
-
 function tryResolveIife(from) {
   try {
     return createRequire(from).resolve("@maintainer-pro/ai-ui");
@@ -131,7 +93,7 @@ function tryResolveIife(from) {
   }
 }
 
-function findIife() {
+export function findIife() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const cwdPkg = path.join(process.cwd(), "package.json");
   const candidates = [
@@ -144,6 +106,19 @@ function findIife() {
   return candidates.find((file) => file && fs.existsSync(file)) ?? null;
 }
 
+function resolveUiFile(uiDir, pathname) {
+  const rel = decodeURIComponent(pathname === "/" ? "/index.html" : pathname);
+  const file = path.normalize(path.join(uiDir, rel));
+  const root = path.resolve(uiDir);
+  if (!file.startsWith(root)) return null;
+  if (fs.existsSync(file) && fs.statSync(file).isFile()) return file;
+  if (pathname === "/ai-ui.iife.js") {
+    const bundled = findIife();
+    if (bundled) return bundled;
+  }
+  return null;
+}
+
 async function toFetchRequest(req) {
   const host = req.headers.host ?? "localhost";
   const url = `http://${host}${req.url ?? "/"}`;
@@ -179,503 +154,495 @@ function toHttpWsUrl(httpUrl) {
   return u.toString().replace(/\/$/, "");
 }
 
-const port = Number(args.port || process.env.PORT || 3000);
-const workspaceDir = path.resolve(
-  args.workspace || process.env.AI_CLI_WORKSPACE || process.cwd()
-);
-const uiDir = path.resolve(
-  args.ui || process.env.AI_SERVER_UI || process.cwd()
-);
-const corsOrigin =
-  (typeof args.corsOrigin === "string" ? args.corsOrigin : process.env.CORS_ORIGIN) ||
-  "*";
-
-process.env.AI_CLI_WORKSPACE = workspaceDir;
-
-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}).`
-  );
+function parseCorsOrigins(value) {
+  return String(value || "*")
+    .split(/[\s,]+/)
+    .map((item) => item.trim())
+    .filter(Boolean);
 }
 
-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, 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())
+const HELP = `Maintainer Pro AI server
+
+Usage:
+  npx --yes --prefer-online @maintainer-pro/ai-server@latest
+  npx --yes --prefer-online @maintainer-pro/ai-server@latest --port 3000 --ui . --workspace .
+
+Flags override .env. Preferred config is env (from the admin setup guide).
+
+  --port <n>           Listen port (PORT)
+  --ui <dir>           Static UI folder (AI_SERVER_UI)
+  --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
+`;
+
+/**
+ * One chat server for one project folder. Safe to start several in one process.
+ *
+ * @param {object} [options]
+ * @param {number} [options.port]
+ * @param {string} [options.workspaceDir]
+ * @param {string} [options.uiDir]
+ * @param {string|string[]} [options.corsOrigins]
+ * @param {Record<string, string>} [options.env]
+ * @param {import("@maintainer-pro/ai-cli").Logger} [options.logger]
+ * @param {boolean} [options.listen]
+ * @param {string} [options.dataDir]
+ * @param {string} [options.sandboxId]
+ * @param {string} [options.label]
+ */
+export async function startAiServer(options = {}) {
+  const env = options.env && typeof options.env === "object" ? options.env : {};
+  const port = Number(options.port || pickEnv(env, "PORT", "3100") || 3100);
+  const workspaceDir = path.resolve(
+    options.workspaceDir || pickEnv(env, "AI_CLI_WORKSPACE") || process.cwd()
   );
-  // 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
+  const sandboxId =
+    options.sandboxId || pickEnv(env, "MAINTAINER_PRO_SANDBOX_ID") || "";
+  const dataDir = ensureProjectDataDir({
+    workspaceDir,
+    sandboxId,
+    dataDir:
+      options.dataDir || pickEnv(env, "MAINTAINER_PRO_DATA_DIR") || undefined,
+  });
+  const uiDir = path.resolve(
+    options.uiDir || pickEnv(env, "AI_SERVER_UI") || workspaceDir
+  );
+  const corsOrigins = Array.isArray(options.corsOrigins)
+    ? options.corsOrigins.filter(Boolean)
+    : parseCorsOrigins(
+        options.corsOrigins ||
+          pickEnv(env, "CORS_ORIGIN") ||
+          pickEnv(env, "CORS_ORIGINS") ||
+          "*"
       );
-    }
-  } 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 });
+  const logger =
+    options.logger || createLogger(options.label || "ai-server");
+  const shouldListen = options.listen !== false;
+
+  const maintainerProUrl = pickEnv(env, "MAINTAINER_PRO_URL");
+  const maintainerProApiKey = pickEnv(env, "MAINTAINER_PRO_API_KEY");
+  if (!maintainerProUrl || !maintainerProApiKey) {
+    throw new Error(
+      "Set MAINTAINER_PRO_URL and MAINTAINER_PRO_API_KEY for this project (.env)."
+    );
   }
-  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,
+  const runningTurns = new Set();
+  const runningByConversation = new Map();
+  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 = createMaintainerProStore({
+    baseUrl: maintainerProUrl,
+    apiKey: maintainerProApiKey,
+    logger,
+    tempDir: path.join(dataDir, "uploads"),
+    onWorkingTurn: (event) => {
+      void runWorkingTurn(event);
     },
-    "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"
+  const productDescription =
+    pickEnv(env, "AI_SERVER_PRODUCT_DESCRIPTION") ||
+    "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(pickEnv(env, "AI_CLI_IGNORE_PATHS"))
   );
-  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,
-    },
+
+  const handlers = createChatHandler({
+    systemPrompt: createDefaultSystemPrompt({ productDescription, ignorePaths }),
+    workspaceDir,
+    dataDir,
+    sandboxId: sandboxId || undefined,
+    db,
+    logger,
   });
-}
 
-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;
+  function applyCors(req, res) {
+    const requestOrigin = String(req.headers.origin || "").trim();
+    if (corsOrigins.includes("*")) {
+      res.setHeader("Access-Control-Allow-Origin", requestOrigin || "*");
+      return;
     }
-  } 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);
+    if (requestOrigin && corsOrigins.includes(requestOrigin)) {
+      res.setHeader("Access-Control-Allow-Origin", requestOrigin);
+      res.setHeader("Vary", "Origin");
+      return;
     }
-    // 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);
-      });
+    if (corsOrigins[0]) {
+      res.setHeader("Access-Control-Allow-Origin", corsOrigins[0]);
     }
   }
-};
-
-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}`;
+
+  function headerMap(headers) {
+    /** @type {Record<string, string>} */
+    const out = {};
+    if (!headers || typeof headers !== "object") return out;
+    for (const [key, value] of Object.entries(headers)) {
+      if (value == null) continue;
+      out[String(key).toLowerCase()] = Array.isArray(value)
+        ? value.join(", ")
+        : String(value);
+    }
+    return out;
   }
-  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");
-  if (req.method === "OPTIONS") {
-    res.statusCode = 204;
-    res.end();
-    return;
+  function resolvePublicUrl(reqOrHeaders) {
+    const headers = headerMap(
+      reqOrHeaders?.headers && typeof reqOrHeaders.headers === "object"
+        ? reqOrHeaders.headers
+        : reqOrHeaders
+    );
+    const fromEnv = (
+      pickEnv(env, "AI_SERVER_URL") ||
+      pickEnv(env, "AI_SERVER_BASE_URL")
+    ).replace(/\/$/, "");
+    if (fromEnv) return fromEnv;
+    const host = headers.host?.trim();
+    if (host) {
+      const xfProto = String(headers["x-forwarded-proto"] ?? "")
+        .split(",")[0]
+        ?.trim();
+      const proto = xfProto || "http";
+      return `${proto}://${host}`;
+    }
+    return `http://localhost:${port}`;
   }
-  if (pathname === "/embed-config.js") {
-    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 ??
-        "",
+
+  function corsHeadersFor(headers) {
+    /** @type {Record<string, string>} */
+    const out = {
+      "access-control-allow-headers": "content-type, authorization",
+      "access-control-allow-methods": "GET,POST,OPTIONS",
     };
-    logger.debug({ aiServerUrl }, "embed-config");
-    res.setHeader("Content-Type", "text/javascript; charset=utf-8");
-    res.end(`window.__MAINTAINER_PRO__=${JSON.stringify(payload)};`);
-    return;
+    const requestOrigin = String(headerMap(headers).origin || "").trim();
+    if (corsOrigins.includes("*")) {
+      out["access-control-allow-origin"] = requestOrigin || "*";
+      return out;
+    }
+    if (requestOrigin && corsOrigins.includes(requestOrigin)) {
+      out["access-control-allow-origin"] = requestOrigin;
+      out.vary = "Origin";
+      return out;
+    }
+    if (corsOrigins[0]) out["access-control-allow-origin"] = corsOrigins[0];
+    return out;
   }
-  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(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
-          );
+
+  /**
+   * Handle an HTTP request in-process (no loopback to this server).
+   * @param {{ method?: string, url?: string, headers?: Record<string, unknown>, body?: Buffer | Uint8Array | string }} input
+   */
+  async function handleHttp(input = {}) {
+    const method = String(input.method || "GET").toUpperCase();
+    const url = String(input.url || "/");
+    const headers = headerMap(input.headers);
+    const body = Buffer.isBuffer(input.body)
+      ? input.body
+      : typeof input.body === "string" && input.body
+        ? Buffer.from(input.body)
+        : input.body instanceof Uint8Array
+          ? Buffer.from(input.body)
+          : Buffer.alloc(0);
+    const pathname = url.split("?")[0] || "/";
+    const outHeaders = corsHeadersFor(headers);
+    logger.debug({ method, pathname }, "http");
+
+    if (method === "OPTIONS") {
+      return { status: 204, headers: outHeaders, body: Buffer.alloc(0) };
+    }
+    if (pathname === "/health") {
+      outHeaders["content-type"] = "application/json; charset=utf-8";
+      return {
+        status: 200,
+        headers: outHeaders,
+        body: Buffer.from(JSON.stringify({ ok: true, workspace: workspaceDir })),
+      };
+    }
+    if (pathname === "/embed-config.js") {
+      const aiServerUrl = resolvePublicUrl({ headers });
+      const payload = {
+        aiServerUrl,
+        apiUrl: `${aiServerUrl}/api/chat`,
+        aiServerWsUrl: `${toHttpWsUrl(aiServerUrl)}/api/ws`,
+        debug: true,
+        logLevel: "debug",
+        maintainerProUrl: maintainerProUrl,
+        maintainerProApiKey:
+          pickEnv(env, "MAINTAINER_PRO_CLIENT_API_KEY") ||
+          pickEnv(env, "NEXT_PUBLIC_MAINTAINER_PRO_CLIENT_API_KEY"),
+      };
+      logger.debug({ aiServerUrl }, "embed-config");
+      outHeaders["content-type"] = "text/javascript; charset=utf-8";
+      return {
+        status: 200,
+        headers: outHeaders,
+        body: Buffer.from(`window.__MAINTAINER_PRO__=${JSON.stringify(payload)};`),
+      };
+    }
+    if (pathname === "/api/chat") {
+      logger.info({ method }, "http /api/chat");
+      const handler = method === "GET" ? handlers.GET : handlers.POST;
+      const host = headers.host || `127.0.0.1:${port}`;
+      const hdrs = new Headers();
+      for (const [key, value] of Object.entries(headers)) {
+        hdrs.set(key, value);
+      }
+      /** @type {RequestInit} */
+      const init = { method, headers: hdrs };
+      if (method !== "GET" && method !== "HEAD" && body.length) {
+        init.body = body;
+        init.duplex = "half";
+      }
+      const request = new Request(`http://${host}${url}`, init);
+      const response = await handler(request);
+      if (method === "POST") {
+        const clone = response.clone();
+        const text = await clone.text();
+        let data = {};
+        try {
+          data = text ? JSON.parse(text) : {};
+        } catch {
+          data = {};
         }
-        return response;
-      })
-      .then((response) => send(res, response))
-      .catch((err) => {
-        logger.error({ err }, "chat handler failed");
-        res.statusCode = 500;
-        res.end("Chat handler failed");
+        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
+        );
+      }
+      const buf = Buffer.from(await response.arrayBuffer());
+      response.headers.forEach((value, key) => {
+        if (key.toLowerCase() === "transfer-encoding") return;
+        outHeaders[key] = value;
       });
-    return;
-  }
-  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"
-      );
+      return { status: response.status, headers: outHeaders, body: buf };
     }
-    res.statusCode = 404;
-    res.end("Not found");
-    return;
+    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"
+        );
+      }
+      outHeaders["content-type"] = "text/plain; charset=utf-8";
+      return { status: 404, headers: outHeaders, body: Buffer.from("Not found") };
+    }
+    outHeaders["content-type"] = contentType(file);
+    return { status: 200, headers: outHeaders, body: fs.readFileSync(file) };
   }
-  res.setHeader("Content-Type", contentType(file));
-  fs.createReadStream(file).pipe(res);
-});
-
-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"
+
+  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())
     );
-    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)"
+    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
         );
-        return { conversationId, accepted: false, busy: true };
       }
+    } else {
+      rows = rows.filter((row) => row.queueStatus !== "queued");
     }
-    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 (
+    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 });
     }
-    const assistantMessageId =
-      typeof msg.assistantMessageId === "string" && msg.assistantMessageId
-        ? msg.assistantMessageId
-        : randomUUID();
-    if (userMessageId) runningTurns.add(userMessageId);
-    if (conversationId && userMessageId) {
-      runningByConversation.set(conversationId, userMessageId);
+    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,
+        attachmentCount: Array.isArray(body.attachments)
+          ? body.attachments.length
+          : 0,
+        workspaceDir,
+      },
+      "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, workspaceDir },
+        "ai turn"
+      );
       hub.publish(conversationId, {
         type: "chat.turn",
         conversationId,
         userMessageId,
       });
+      const assistantMessageId = randomUUID();
       const result = await runChatPost({
         conversationId,
         messages,
-        userMessage,
-        skipPersistUser: msg.skipPersistUser !== false,
+        userMessage: content,
+        skipPersistUser: true,
         userMessageId,
         assistantMessageId,
-        senderType: typeof msg.senderType === "string" ? msg.senderType : undefined,
-        senderName: typeof msg.senderName === "string" ? msg.senderName : undefined,
+        senderType: event.message.senderType === "client" ? "client" : undefined,
+        senderName: event.message.senderName ?? undefined,
       });
       publishChatResult(conversationId, result, assistantMessageId, userMessageId);
       if (!result.ok) {
-        throw new Error(result.data?.error ?? `chat failed (${result.status})`);
-      }
-      if (
+        logger.warn({ status: result.status }, "ai turn failed");
+      } else if (
         result.data?.nextQueued &&
         typeof result.data.nextQueued.id === "string"
       ) {
         nextQueued = result.data.nextQueued;
       }
-      return { conversationId, ...result.data };
+    } 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 {
-      if (userMessageId) runningTurns.delete(userMessageId);
-      if (
-        conversationId &&
-        userMessageId &&
-        runningByConversation.get(conversationId) === userMessageId
-      ) {
+      runningTurns.delete(userMessageId);
+      if (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()
+        nextQueued?.id && nextQueued.content?.trim()
           ? {
               conversationId,
               message: {
@@ -702,18 +669,195 @@ hub = attachChatWebSocket(server, {
         });
       }
     }
-  },
-});
+  };
+
+  const server = http.createServer((req, res) => {
+    void (async () => {
+      const chunks = [];
+      for await (const chunk of req) chunks.push(chunk);
+      const result = await handleHttp({
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        body: Buffer.concat(chunks),
+      });
+      res.statusCode = result.status;
+      for (const [key, value] of Object.entries(result.headers || {})) {
+        res.setHeader(key, value);
+      }
+      res.end(result.body);
+    })().catch((err) => {
+      logger.error({ err }, "http failed");
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.end("Internal error");
+      }
+    });
+  });
+
+  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,
-        },
+        { conversations: info.conversations, messages: info.messages, workspaceDir },
         "cache ready"
       );
     } catch (err) {
@@ -723,7 +867,7 @@ async function start() {
 
   const recoverMs = Math.max(
     5_000,
-    Number(process.env.AI_QUEUE_RECOVER_MS || 20_000) || 20_000
+    Number(pickEnv(env, "AI_QUEUE_RECOVER_MS", "20000") || 20_000) || 20_000
   );
   let recoverInFlight = false;
   const sweepStuckQueues = async (reason) => {
@@ -774,11 +918,46 @@ async function start() {
   }, recoverMs);
   if (typeof recoverTimer.unref === "function") recoverTimer.unref();
 
-  server.listen(port, () => {
+  const close = () =>
+    new Promise((resolve) => {
+      clearInterval(recoverTimer);
+      try {
+        db.stop?.();
+      } catch {
+        /* ignore */
+      }
+      try {
+        hub.close();
+      } catch {
+        /* ignore */
+      }
+      server.close(() => resolve());
+      setTimeout(resolve, 2000);
+    });
+
+  if (shouldListen) {
+    try {
+      await new Promise((resolve, reject) => {
+        const onError = (err) => {
+          server.off("listening", onListen);
+          reject(err);
+        };
+        const onListen = () => {
+          server.off("error", onError);
+          resolve();
+        };
+        server.once("error", onError);
+        server.listen(port, onListen);
+      });
+    } catch (err) {
+      await close();
+      throw err;
+    }
     const base =
-      (process.env.AI_SERVER_URL || process.env.AI_SERVER_BASE_URL || "")
-        .trim()
-        .replace(/\/$/, "") || `http://localhost:${port}`;
+      (pickEnv(env, "AI_SERVER_URL") || pickEnv(env, "AI_SERVER_BASE_URL")).replace(
+        /\/$/,
+        ""
+      ) || `http://localhost:${port}`;
     logger.info(`chat → ${base}/api/chat`);
     logger.info(`ws   → ${toHttpWsUrl(base)}/api/ws`);
     logger.info(`ui   → ${base}/`);
@@ -793,23 +972,40 @@ async function start() {
       );
     }
     logger.info(`workspace ${workspaceDir}`);
-    logger.info(
-      {
-        logLevel: logger.level,
-        nodeEnv: process.env.NODE_ENV,
-        queueRecoverMs: recoverMs,
-      },
-      "logger ready"
-    );
-  });
-}
+  }
 
-void start();
+  return {
+    port,
+    workspaceDir,
+    server,
+    close,
+    runChat: runChatPost,
+    handleHttp,
+  };
+}
 
-for (const signal of ["SIGINT", "SIGTERM"]) {
-  process.on(signal, () => {
-    db.stop?.();
-    hub.close();
-    process.exit(0);
+export async function runCli(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    console.log(HELP);
+    return;
+  }
+  const envFile = path.resolve(
+    typeof args.envFile === "string" ? args.envFile : path.join(process.cwd(), ".env")
+  );
+  loadEnvFile(envFile);
+  if (!process.env.NODE_ENV?.trim()) {
+    process.env.NODE_ENV = "development";
+  }
+  const instance = await startAiServer({
+    port: Number(args.port || process.env.PORT || 3000),
+    workspaceDir: args.workspace || process.env.AI_CLI_WORKSPACE || process.cwd(),
+    uiDir: args.ui || process.env.AI_SERVER_UI || process.cwd(),
+    corsOrigins: args.corsOrigin || undefined,
   });
+  const shutdown = () => {
+    void instance.close().finally(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
 }