@maintainer-pro/ai-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,8 +1,10 @@
 # @maintainer-pro/ai-cli
 
-Server SDK for Maintainer Pro. It talks to coding agents — Cursor (`agent`), Claude (`claude`), or Antigravity (`agy`) — and exposes chat HTTP handlers for your Node app.
+Server SDK for Maintainer Pro. It talks to coding agents — Cursor (`agent`), Claude (`claude`), or Antigravity (`agy`) — and exposes chat HTTP handlers.
 
-Use this package when you already have a server (Next, Express, Fastify). To get a port with no custom `server.mjs`, use [`@maintainer-pro/ai-server`](https://www.npmjs.com/package/@maintainer-pro/ai-server).
+**Local development:** prefer [`@maintainer-pro/ai-server`](https://www.npmjs.com/package/@maintainer-pro/ai-server) as a sidecar (a separate Node chat server beside the host app). Do not add chat routes to the host.
+
+**Production:** use this SDK on a machine that can run a coding-agent CLI, or pass a custom `AiProvider`. HTTP model backends are out of scope for the default providers. The embed widget (`ai-ui.iife.js`) must be served as a static file in production — `localhost` sidecar URLs will not load.
 
 ## Install
 
@@ -10,7 +12,7 @@ Use this package when you already have a server (Next, Express, Fastify). To get
 npm install @maintainer-pro/ai-cli
 ```
 
-Requires **Node.js 22+** and one authenticated coding-agent CLI on the machine that runs chat.
+Requires **Node.js 22+** and one authenticated coding-agent CLI on the machine that runs chat (unless you supply `providers`).
 
 ## Quick start
 
@@ -38,7 +40,7 @@ export const GET = handlers.GET;
 export const POST = handlers.POST;
 ```
 
-Chat history is stored in Maintainer Pro admin. Do not put API keys in the browser bundle — serve the client key from `/embed-config.js` (or Next `/api/embed-config`).
+Chat history is stored in Maintainer Pro admin. Do not put API keys in the browser — serve the client key from `/embed-config.js`.
 
 ## Environment
 
@@ -54,8 +56,8 @@ Chat history is stored in Maintainer Pro admin. Do not put API keys in the brows
 
 | Package | Role |
 |---------|------|
-| [`@maintainer-pro/ai-server`](https://www.npmjs.com/package/@maintainer-pro/ai-server) | `npx` Node server that uses this SDK |
-| [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) | React chat UI and embed script |
+| [`@maintainer-pro/ai-server`](https://www.npmjs.com/package/@maintainer-pro/ai-server) | Local Node chat server (sidecar) that uses this SDK |
+| [`@maintainer-pro/ai-ui`](https://www.npmjs.com/package/@maintainer-pro/ai-ui) | Embed widget (`ai-ui.iife.js`) — sidecar in dev, static file in prod |
 | [`@maintainer-pro/setup`](https://www.npmjs.com/package/@maintainer-pro/setup) | Download the sandbox setup guide |
 
 Optional SQL persistence lives on `@maintainer-pro/ai-cli/db` (install `better-sqlite3`, `postgres`, or `mysql2`).

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  WORKING_PROVIDER: () => WORKING_PROVIDER,
   buildClaudeUserPrompt: () => buildClaudeUserPrompt,
   buildConversationPrompt: () => buildConversationPrompt,
   buildCursorPrompt: () => buildCursorPrompt,
@@ -592,7 +593,9 @@ async function buildPriorConversationsContext(db, options) {
   ).slice(0, maxConversations) : ranked;
   const blocks = selected.map((c) => {
     const slice = c.messages.length > maxMessages ? c.messages.slice(-maxMessages) : c.messages;
-    const lines = slice.filter((m) => m.role === "user" || m.role === "assistant").map(
+    const lines = slice.filter(
+      (m) => (m.role === "user" || m.role === "assistant") && m.provider !== "working" && Boolean(m.content?.trim())
+    ).map(
       (m) => `${m.role === "user" ? "Human" : "Assistant"}: ${truncate(m.content)}`
     );
     const when = c.updatedAt ? ` (updated ${c.updatedAt.slice(0, 10)})` : "";
@@ -625,6 +628,18 @@ function createToolValidator(schemas) {
 }
 
 // src/http/handler.ts
+var WORKING_PROVIDER = "working";
+async function setWorkingMessage(db, conversationId) {
+  await db.ensureConversation(conversationId);
+  await db.clearWorkingMessages?.(conversationId);
+  await db.saveMessage({
+    conversationId,
+    role: "assistant",
+    content: "",
+    provider: WORKING_PROVIDER,
+    senderType: "ai"
+  });
+}
 var SHARED_CONVERSATION_ID = "shared";
 var conversationTurnSeq = /* @__PURE__ */ new Map();
 function beginConversationTurn(conversationId) {
@@ -697,6 +712,8 @@ function createChatHandler(options) {
       }
     },
     async POST(request) {
+      let trackedConversationId;
+      let trackedTurn = 0;
       try {
         const body = await request.json();
         const conversationId = await resolveSharedConversationId(
@@ -704,21 +721,16 @@ function createChatHandler(options) {
           options,
           body.conversationId
         );
-        if (body.type === "status") {
-          const content = body.content?.trim();
-          if (!conversationId || !content) {
+        trackedConversationId = conversationId;
+        if (body.type === "working-clear") {
+          if (!conversationId) {
             return Response.json(
-              { error: "conversationId and content are required" },
+              { error: "conversationId is required" },
               { status: 400 }
             );
           }
-          if (options.db) {
-            await options.db.ensureConversation(conversationId);
-            await options.db.saveMessage({
-              conversationId,
-              role: "assistant",
-              content
-            });
+          if (options.db?.clearWorkingMessages) {
+            await options.db.clearWorkingMessages(conversationId);
           }
           return Response.json({ ok: true, conversationId });
         }
@@ -766,7 +778,8 @@ function createChatHandler(options) {
           );
           persistAttachmentPaths = attachmentPaths;
         }
-        const turn = beginConversationTurn(conversationId);
+        const turn = beginConversationTurn(conversationId ?? SHARED_CONVERSATION_ID);
+        trackedTurn = turn;
         const signal = request.signal;
         if (options.db && conversationId) {
           const latest = messages[messages.length - 1];
@@ -782,13 +795,26 @@ function createChatHandler(options) {
               senderName: body.senderName?.trim() || void 0
             });
           }
+          await setWorkingMessage(options.db, conversationId);
         }
         const latestUser = [...messages].reverse().find((m) => m.role === "user");
         const priorConversationsContext = options.db ? await buildPriorConversationsContext(options.db, {
           excludeConversationId: conversationId,
           currentRequest: latestUser?.content ?? ""
         }) : "";
-        if (signal.aborted || !isActiveConversationTurn(conversationId, turn)) {
+        if (!isActiveConversationTurn(
+          conversationId ?? SHARED_CONVERSATION_ID,
+          turn
+        )) {
+          return Response.json({
+            superseded: true,
+            conversationId: conversationId ?? null
+          });
+        }
+        if (signal.aborted) {
+          if (options.db?.clearWorkingMessages && conversationId) {
+            await options.db.clearWorkingMessages(conversationId);
+          }
           return Response.json({
             superseded: true,
             conversationId: conversationId ?? null
@@ -799,7 +825,10 @@ function createChatHandler(options) {
           attachmentPaths,
           priorConversationsContext: priorConversationsContext || void 0
         });
-        if (!isActiveConversationTurn(conversationId, turn)) {
+        if (!isActiveConversationTurn(
+          conversationId ?? SHARED_CONVERSATION_ID,
+          turn
+        )) {
           return Response.json({
             superseded: true,
             conversationId: conversationId ?? null
@@ -811,6 +840,7 @@ function createChatHandler(options) {
         }
         if (options.db && conversationId) {
           await options.db.ensureConversation(conversationId);
+          await options.db.clearWorkingMessages?.(conversationId);
           await options.db.saveMessage({
             conversationId,
             role: "assistant",
@@ -834,6 +864,11 @@ function createChatHandler(options) {
         });
       } catch (err) {
         console.error("Chat API error:", err);
+        if (trackedConversationId && options.db?.clearWorkingMessages && isActiveConversationTurn(trackedConversationId, trackedTurn)) {
+          await options.db.clearWorkingMessages(trackedConversationId).catch(
+            () => void 0
+          );
+        }
         return Response.json(
           {
             error: "Sorry about that \u2014 I couldn't finish this right now. Happy to jump on a quick call if you'd like help \u2014 just let us know when works."
@@ -903,6 +938,16 @@ function createLocalDirectoryStore(baseDir) {
       await writeConversation(filePath, existing);
       return message;
     },
+    async clearWorkingMessages(conversationId) {
+      const filePath = fileFor(conversationId);
+      const existing = await readConversation(filePath);
+      if (!existing) return;
+      const next = existing.messages.filter((m) => m.provider !== "working");
+      if (next.length === existing.messages.length) return;
+      existing.messages = next;
+      existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await writeConversation(filePath, existing);
+    },
     async listMessages(conversationId) {
       const existing = await readConversation(fileFor(conversationId));
       return existing?.messages ?? [];
@@ -1009,6 +1054,15 @@ function createMaintainerProStore(options) {
       );
       return data.message;
     },
+    async clearWorkingMessages(conversationId) {
+      await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/conversations/${encodeURIComponent(conversationId)}/messages?provider=working`,
+        { method: "DELETE" },
+        fetchImpl
+      );
+    },
     async listMessages(conversationId) {
       const data = await mpFetch(
         baseUrl,
@@ -1090,6 +1144,7 @@ function createMaintainerProStoreFromEnv() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  WORKING_PROVIDER,
   buildClaudeUserPrompt,
   buildConversationPrompt,
   buildCursorPrompt,

package/dist/index.d.cts

@@ -111,6 +111,8 @@ declare function createToolValidator(schemas: ToolSchemaMap): (toolCall: ToolCal
     error: string;
 };
 
+/** Stored on assistant rows while a single in-flight AI turn is running. */
+declare const WORKING_PROVIDER = "working";
 /** Minimal persistence contract (file store, SQL, or Maintainer Pro). */
 interface ChatStoreLike {
     ensureConversation(id: string): Promise<void>;
@@ -133,6 +135,8 @@ interface ChatStoreLike {
         senderType?: "client" | "developer" | "ai" | null;
         senderName?: string | null;
     }>>;
+    /** Remove in-progress working placeholders (at most one per conversation). */
+    clearWorkingMessages?(conversationId: string): Promise<void>;
     /** All conversations under the store (for prior-chat context). */
     listConversations?(): Promise<Array<{
         id: string;
@@ -141,6 +145,7 @@ interface ChatStoreLike {
             role: string;
             content: string;
             createdAt?: string | Date;
+            provider?: string | null;
         }>;
     }>>;
     saveToolEvents?(conversationId: string, events: Array<{
@@ -236,4 +241,4 @@ interface PriorConversationOptions {
  */
 declare function buildPriorConversationsContext(db: ChatStoreLike, options: PriorConversationOptions): Promise<string>;
 
-export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };
+export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, WORKING_PROVIDER, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };

package/dist/index.d.ts

@@ -111,6 +111,8 @@ declare function createToolValidator(schemas: ToolSchemaMap): (toolCall: ToolCal
     error: string;
 };
 
+/** Stored on assistant rows while a single in-flight AI turn is running. */
+declare const WORKING_PROVIDER = "working";
 /** Minimal persistence contract (file store, SQL, or Maintainer Pro). */
 interface ChatStoreLike {
     ensureConversation(id: string): Promise<void>;
@@ -133,6 +135,8 @@ interface ChatStoreLike {
         senderType?: "client" | "developer" | "ai" | null;
         senderName?: string | null;
     }>>;
+    /** Remove in-progress working placeholders (at most one per conversation). */
+    clearWorkingMessages?(conversationId: string): Promise<void>;
     /** All conversations under the store (for prior-chat context). */
     listConversations?(): Promise<Array<{
         id: string;
@@ -141,6 +145,7 @@ interface ChatStoreLike {
             role: string;
             content: string;
             createdAt?: string | Date;
+            provider?: string | null;
         }>;
     }>>;
     saveToolEvents?(conversationId: string, events: Array<{
@@ -236,4 +241,4 @@ interface PriorConversationOptions {
  */
 declare function buildPriorConversationsContext(db: ChatStoreLike, options: PriorConversationOptions): Promise<string>;
 
-export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };
+export { type AiCliProviderId, type AiProvider, type AiResponse, type CallAiOptions, type ChatAttachment, type ChatHandlerOptions, type ChatHandlers, type ChatMessage, type ChatSenderType, type ChatStoreLike, type ChatUser, type ClientContext, type LocalStoredMessage, type MaintainerProStoreOptions, type PriorConversationOptions, type ProviderPreference, type ToolCall, type ToolSchemaMap, WORKING_PROVIDER, buildClaudeUserPrompt, buildConversationPrompt, buildCursorPrompt, buildPriorConversationsContext, callAi, commandExists, createAntigravityProvider, createBuiltinProviders, createChatHandler, createClaudeProvider, createCursorProvider, createDefaultSystemPrompt, createLocalDirectoryStore, createMaintainerProStore, createMaintainerProStoreFromEnv, createToolValidator, formatClientContext, getProviderPreference, parseAiResponse, providerLabel, resolveCliBinary, resolveProvider, saveChatAttachments, toNextRoute };

package/dist/index.js

@@ -533,7 +533,9 @@ async function buildPriorConversationsContext(db, options) {
   ).slice(0, maxConversations) : ranked;
   const blocks = selected.map((c) => {
     const slice = c.messages.length > maxMessages ? c.messages.slice(-maxMessages) : c.messages;
-    const lines = slice.filter((m) => m.role === "user" || m.role === "assistant").map(
+    const lines = slice.filter(
+      (m) => (m.role === "user" || m.role === "assistant") && m.provider !== "working" && Boolean(m.content?.trim())
+    ).map(
       (m) => `${m.role === "user" ? "Human" : "Assistant"}: ${truncate(m.content)}`
     );
     const when = c.updatedAt ? ` (updated ${c.updatedAt.slice(0, 10)})` : "";
@@ -566,6 +568,18 @@ function createToolValidator(schemas) {
 }
 
 // src/http/handler.ts
+var WORKING_PROVIDER = "working";
+async function setWorkingMessage(db, conversationId) {
+  await db.ensureConversation(conversationId);
+  await db.clearWorkingMessages?.(conversationId);
+  await db.saveMessage({
+    conversationId,
+    role: "assistant",
+    content: "",
+    provider: WORKING_PROVIDER,
+    senderType: "ai"
+  });
+}
 var SHARED_CONVERSATION_ID = "shared";
 var conversationTurnSeq = /* @__PURE__ */ new Map();
 function beginConversationTurn(conversationId) {
@@ -638,6 +652,8 @@ function createChatHandler(options) {
       }
     },
     async POST(request) {
+      let trackedConversationId;
+      let trackedTurn = 0;
       try {
         const body = await request.json();
         const conversationId = await resolveSharedConversationId(
@@ -645,21 +661,16 @@ function createChatHandler(options) {
           options,
           body.conversationId
         );
-        if (body.type === "status") {
-          const content = body.content?.trim();
-          if (!conversationId || !content) {
+        trackedConversationId = conversationId;
+        if (body.type === "working-clear") {
+          if (!conversationId) {
             return Response.json(
-              { error: "conversationId and content are required" },
+              { error: "conversationId is required" },
               { status: 400 }
             );
           }
-          if (options.db) {
-            await options.db.ensureConversation(conversationId);
-            await options.db.saveMessage({
-              conversationId,
-              role: "assistant",
-              content
-            });
+          if (options.db?.clearWorkingMessages) {
+            await options.db.clearWorkingMessages(conversationId);
           }
           return Response.json({ ok: true, conversationId });
         }
@@ -707,7 +718,8 @@ function createChatHandler(options) {
           );
           persistAttachmentPaths = attachmentPaths;
         }
-        const turn = beginConversationTurn(conversationId);
+        const turn = beginConversationTurn(conversationId ?? SHARED_CONVERSATION_ID);
+        trackedTurn = turn;
         const signal = request.signal;
         if (options.db && conversationId) {
           const latest = messages[messages.length - 1];
@@ -723,13 +735,26 @@ function createChatHandler(options) {
               senderName: body.senderName?.trim() || void 0
             });
           }
+          await setWorkingMessage(options.db, conversationId);
         }
         const latestUser = [...messages].reverse().find((m) => m.role === "user");
         const priorConversationsContext = options.db ? await buildPriorConversationsContext(options.db, {
           excludeConversationId: conversationId,
           currentRequest: latestUser?.content ?? ""
         }) : "";
-        if (signal.aborted || !isActiveConversationTurn(conversationId, turn)) {
+        if (!isActiveConversationTurn(
+          conversationId ?? SHARED_CONVERSATION_ID,
+          turn
+        )) {
+          return Response.json({
+            superseded: true,
+            conversationId: conversationId ?? null
+          });
+        }
+        if (signal.aborted) {
+          if (options.db?.clearWorkingMessages && conversationId) {
+            await options.db.clearWorkingMessages(conversationId);
+          }
           return Response.json({
             superseded: true,
             conversationId: conversationId ?? null
@@ -740,7 +765,10 @@ function createChatHandler(options) {
           attachmentPaths,
           priorConversationsContext: priorConversationsContext || void 0
         });
-        if (!isActiveConversationTurn(conversationId, turn)) {
+        if (!isActiveConversationTurn(
+          conversationId ?? SHARED_CONVERSATION_ID,
+          turn
+        )) {
           return Response.json({
             superseded: true,
             conversationId: conversationId ?? null
@@ -752,6 +780,7 @@ function createChatHandler(options) {
         }
         if (options.db && conversationId) {
           await options.db.ensureConversation(conversationId);
+          await options.db.clearWorkingMessages?.(conversationId);
           await options.db.saveMessage({
             conversationId,
             role: "assistant",
@@ -775,6 +804,11 @@ function createChatHandler(options) {
         });
       } catch (err) {
         console.error("Chat API error:", err);
+        if (trackedConversationId && options.db?.clearWorkingMessages && isActiveConversationTurn(trackedConversationId, trackedTurn)) {
+          await options.db.clearWorkingMessages(trackedConversationId).catch(
+            () => void 0
+          );
+        }
         return Response.json(
           {
             error: "Sorry about that \u2014 I couldn't finish this right now. Happy to jump on a quick call if you'd like help \u2014 just let us know when works."
@@ -844,6 +878,16 @@ function createLocalDirectoryStore(baseDir) {
       await writeConversation(filePath, existing);
       return message;
     },
+    async clearWorkingMessages(conversationId) {
+      const filePath = fileFor(conversationId);
+      const existing = await readConversation(filePath);
+      if (!existing) return;
+      const next = existing.messages.filter((m) => m.provider !== "working");
+      if (next.length === existing.messages.length) return;
+      existing.messages = next;
+      existing.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await writeConversation(filePath, existing);
+    },
     async listMessages(conversationId) {
       const existing = await readConversation(fileFor(conversationId));
       return existing?.messages ?? [];
@@ -950,6 +994,15 @@ function createMaintainerProStore(options) {
       );
       return data.message;
     },
+    async clearWorkingMessages(conversationId) {
+      await mpFetch(
+        baseUrl,
+        apiKey,
+        `/api/v1/store/conversations/${encodeURIComponent(conversationId)}/messages?provider=working`,
+        { method: "DELETE" },
+        fetchImpl
+      );
+    },
     async listMessages(conversationId) {
       const data = await mpFetch(
         baseUrl,
@@ -1030,6 +1083,7 @@ function createMaintainerProStoreFromEnv() {
   return createMaintainerProStore({ baseUrl, apiKey });
 }
 export {
+  WORKING_PROVIDER,
   buildClaudeUserPrompt,
   buildConversationPrompt,
   buildCursorPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maintainer-pro/ai-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Maintainer Pro server SDK: Claude/Cursor CLI, chat HTTP handlers, and optional SQL persistence",
   "keywords": [
     "maintainer-pro",