@love-moon/app-sdk 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @love-moon/app-sdk
 
+## 0.4.0
+
+### Patch Changes
+
+- 4ecc359: Publish the chat-web browser runtime and wire it into the CLI and AI SDK for
+  ChatGPT and Gemini web sessions, including provider error handling and local
+  development installation support.
+
+  Ship app SDK realtime history catch-up and the CLI/AI SDK goal-mode and custom
+  command runtime updates included in this release.
+
 ## 0.3.2
 
 ### Changed
@@ -26,10 +37,13 @@
   silent for minutes) can opt out by passing `idleTimeoutMs: 0`:
 
   ```ts
-  for await (const delta of client.tasks.streamReply(taskId, { idleTimeoutMs: 0 })) {
+  for await (const delta of client.tasks.streamReply(taskId, {
+    idleTimeoutMs: 0,
+  })) {
     // never time out — caller is responsible for cancelling via signal
   }
   ```
+
 - **Locked down the public `.d.ts` surface.** Internal transport types —
   `Fetcher`, `FetcherOptions`, `RequestOptions`, `AppWebSocket`,
   `AppWebSocketOptions`, `TasksRestApi` — are now tagged
@@ -89,7 +103,7 @@ Initial implementation, RFC 0027 milestones M0–M3.
   subscribe; yields `text` deltas from `reply_preview` plus a terminal `done`
   on the assistant message (or `error` on `task_status_update=failed`).
 - Unified `ConductorAppError` with named error codes mapped from HTTP status
-  + backend error strings.
+  - backend error strings.
 - Custom fetch / WebSocket / bearerToken providers for SSR + test injection.
 
 ### Added — `/react` (M2)
@@ -106,7 +120,7 @@ Initial implementation, RFC 0027 milestones M0–M3.
 - Optimistic send → server confirm flow with pending-message replacement.
 - Pre-compiled CSS at `@love-moon/app-sdk/react/styles.css`; CSS-variable
   theming via the `theme` prop; mobile/desktop layout via responsive CSS
-  + an explicit `layout` prop override.
+  - an explicit `layout` prop override.
 - jsdom integration tests covering hydration, live events, runtime status,
   interrupt button visibility, and optimistic send.
 

package/dist/react/index.d.ts

@@ -43,6 +43,35 @@ interface SendMessageInput {
     role?: MessageRole;
 }
 
+/**
+ * Custom content renderer. Receives the full `Message` so the renderer can
+ * branch on `role` / `metadata` / `attachments` if it wants to. Return any
+ * ReactNode; the SDK still wraps it in `<div class="conductor-bubble">` and
+ * applies role-based alignment / pending styling.
+ *
+ * Returning `null` (or `undefined`) renders an empty bubble — equivalent to
+ * a message with empty content. If you want to suppress the bubble entirely,
+ * filter the message upstream (e.g. via your own MessageList).
+ */
+type RenderMessageContent = (message: Message) => ReactNode;
+interface MessageListProps {
+    labels: ChatViewLabels;
+    /**
+     * Optional override for how each message's content is rendered inside its
+     * bubble. Defaults to plain text (`message.content`). Pass e.g. a
+     * `react-markdown` renderer here to enable markdown formatting:
+     *
+     *   <MessageList
+     *     labels={...}
+     *     renderMessageContent={(m) => (
+     *       <ReactMarkdown remarkPlugins={[remarkGfm]}>{m.content}</ReactMarkdown>
+     *     )}
+     *   />
+     */
+    renderMessageContent?: RenderMessageContent;
+}
+declare function MessageList({ labels, renderMessageContent }: MessageListProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Runtime status pushed by the daemon while a task is in progress.
  * Mirrors `task_runtime_status` envelope on /ws/app.
@@ -169,6 +198,25 @@ interface ChatViewProps {
      * "via <self>" self-reference loop.
      */
     showAppOriginChip?: boolean;
+    /**
+     * Override how each message's content is rendered inside its bubble.
+     * Defaults to plain text. Common use: wire in a markdown renderer.
+     *
+     *   import ReactMarkdown from 'react-markdown';
+     *   import remarkGfm from 'remark-gfm';
+     *
+     *   <ChatView
+     *     taskId={taskId}
+     *     adapter={adapter}
+     *     renderMessageContent={(m) => (
+     *       <ReactMarkdown remarkPlugins={[remarkGfm]}>{m.content}</ReactMarkdown>
+     *     )}
+     *   />
+     *
+     * The SDK still owns the bubble container (role-based alignment, pending
+     * state, data attributes). Only the content inside is replaced.
+     */
+    renderMessageContent?: RenderMessageContent;
     onError?: (error: unknown) => void;
     /** Extra className applied to the root container. */
     className?: string;
@@ -196,11 +244,6 @@ interface ChatViewTheme {
 }
 declare function ChatView(props: ChatViewProps): react_jsx_runtime.JSX.Element;
 
-interface MessageListProps {
-    labels: ChatViewLabels;
-}
-declare function MessageList({ labels }: MessageListProps): react_jsx_runtime.JSX.Element;
-
 interface MessageInputProps {
     labels: ChatViewLabels;
     /** Disable the send button (useful while a turn is in progress). */
@@ -361,4 +404,4 @@ type ConductorErrorCode = 'unauthorized' | 'forbidden' | 'token_revoked' | 'inva
 /** Helper: type-guard for callers that don't want `instanceof`. */
 declare function isConductorAppError(error: unknown): error is ConductorAppError;
 
-export { type Attachment, type ChatAdapter, type ChatEvent, ChatProvider, type ChatState, ChatView, type ChatViewLabels, type ChatViewProps, type ChatViewTheme, ConductorAppError, type Message, MessageInput, MessageList, type MessageRole, type RestAdapterOptions, type RuntimeState, type RuntimeStatus, RuntimeStatusBar, type SendMessageInput, type Task, type TaskStatus, createRestAdapter, isConductorAppError, useChat };
+export { type Attachment, type ChatAdapter, type ChatEvent, ChatProvider, type ChatState, ChatView, type ChatViewLabels, type ChatViewProps, type ChatViewTheme, ConductorAppError, type Message, MessageInput, MessageList, type MessageListProps, type MessageRole, type RenderMessageContent, type RestAdapterOptions, type RuntimeState, type RuntimeStatus, RuntimeStatusBar, type SendMessageInput, type Task, type TaskStatus, createRestAdapter, isConductorAppError, useChat };

package/dist/react/index.js

@@ -152,6 +152,51 @@ function ChatProvider(props) {
     const activeAdapter = adapterRef.current;
     let cancelled = false;
     const abort = new AbortController();
+    let catchUpTimer = null;
+    let catchUpInFlight = false;
+    let needAnotherCatchUp = false;
+    let catchUpAbort = null;
+    let prevReplyInProgress;
+    let prevConnectionState;
+    const runCatchUp = async () => {
+      if (cancelled) return;
+      catchUpInFlight = true;
+      catchUpAbort = new AbortController();
+      try {
+        const page = await activeAdapter.fetchHistory(taskId, {
+          limit: 20,
+          signal: catchUpAbort.signal
+        });
+        if (cancelled) return;
+        for (const m of page.messages) {
+          if (!m.id) continue;
+          dispatch({ type: "APPEND_MESSAGE", message: m });
+        }
+      } catch (err) {
+        const name = err?.name;
+        const code = err?.code;
+        if (name === "AbortError" || code === "stream_aborted") return;
+        console.warn("[app-sdk] history catch-up failed", err);
+      } finally {
+        catchUpInFlight = false;
+        if (needAnotherCatchUp && !cancelled) {
+          needAnotherCatchUp = false;
+          void runCatchUp();
+        }
+      }
+    };
+    const scheduleCatchUp = (delayMs) => {
+      if (cancelled) return;
+      if (catchUpInFlight) {
+        needAnotherCatchUp = true;
+        return;
+      }
+      if (catchUpTimer) clearTimeout(catchUpTimer);
+      catchUpTimer = setTimeout(() => {
+        catchUpTimer = null;
+        void runCatchUp();
+      }, delayMs);
+    };
     dispatch({ type: "LOADING_HISTORY", loading: true });
     activeAdapter.fetchHistory(taskId, { signal: abort.signal }).then((page) => {
       if (cancelled) return;
@@ -180,11 +225,18 @@ function ChatProvider(props) {
         case "message_updated":
           dispatch({ type: "UPDATE_MESSAGE", message: event.message });
           break;
-        case "runtime_status":
+        case "runtime_status": {
           dispatch({ type: "SET_RUNTIME", status: event.status });
+          const now = event.status.replyInProgress;
+          if (prevReplyInProgress === true && now === false) {
+            scheduleCatchUp(500);
+          }
+          prevReplyInProgress = now;
           break;
+        }
         case "task_finished":
           dispatch({ type: "TASK_FINISHED" });
+          scheduleCatchUp(500);
           break;
         case "task_failed": {
           const taskErr = {
@@ -194,17 +246,28 @@ function ChatProvider(props) {
           if (event.error.details !== void 0) taskErr.details = event.error.details;
           if (event.error.cause !== void 0) taskErr.cause = event.error.cause;
           dispatch({ type: "TASK_FAILED", error: taskErr });
+          scheduleCatchUp(500);
           break;
         }
-        case "connection_state":
+        case "connection_state": {
           dispatch({ type: "SET_CONNECTION", state: event.state });
+          if (event.state === "connected" && prevConnectionState === "reconnecting") {
+            scheduleCatchUp(0);
+          }
+          prevConnectionState = event.state;
           break;
+        }
       }
     });
     return () => {
       cancelled = true;
       abort.abort();
       sub.unsubscribe();
+      if (catchUpTimer) {
+        clearTimeout(catchUpTimer);
+        catchUpTimer = null;
+      }
+      catchUpAbort?.abort();
     };
   }, [taskId]);
   const value = useMemo(() => {
@@ -299,7 +362,7 @@ function extractError(err) {
 // src/react/components/MessageList.tsx
 import { useEffect as useEffect2, useLayoutEffect, useRef as useRef2 } from "react";
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
-function MessageList({ labels }) {
+function MessageList({ labels, renderMessageContent }) {
   const { state, loadEarlier } = useChat();
   const containerRef = useRef2(null);
   const lastMessageCountRef = useRef2(state.messages.length);
@@ -335,13 +398,14 @@ function MessageList({ labels }) {
     state.messages.map((m) => {
       const isUser = m.role === "user" || m.role === "sdk";
       const isPending = m.id.startsWith("pending:");
+      const content = renderMessageContent ? renderMessageContent(m) : m.content;
       return /* @__PURE__ */ jsx2(
         "div",
         {
           className: "conductor-message " + (isUser ? "conductor-message--user" : "conductor-message--assistant") + (isPending ? " conductor-message--pending" : ""),
           "data-role": m.role,
           "data-message-id": m.id,
-          children: /* @__PURE__ */ jsx2("div", { className: "conductor-bubble", children: m.content })
+          children: /* @__PURE__ */ jsx2("div", { className: "conductor-bubble", children: content })
         },
         m.id
       );
@@ -487,7 +551,13 @@ function ChatView(props) {
       style: themeStyle,
       children: /* @__PURE__ */ jsxs4(ChatProvider, { taskId: props.taskId, adapter: props.adapter, onError: props.onError, children: [
         /* @__PURE__ */ jsx5(RuntimeStatusBar, { labels }),
-        /* @__PURE__ */ jsx5(MessageList, { labels }),
+        /* @__PURE__ */ jsx5(
+          MessageList,
+          {
+            labels,
+            renderMessageContent: props.renderMessageContent
+          }
+        ),
         /* @__PURE__ */ jsx5(MessageInput, { labels, disabled: props.readOnly })
       ] })
     }

package/dist/server/index.d.ts

@@ -329,10 +329,28 @@ declare class TasksApi {
      *
      * The first call lazily opens a /ws/app connection; subsequent calls share
      * the same connection.
+     *
+     * History catch-up (enabled by default): when a terminal event arrives
+     * (`task_finished`, `task_failed`, `runtime_status` flipping
+     * `replyInProgress` true→false, or `connection_state` recovering from
+     * `reconnecting → connected`), the wrapper pulls a window of recent
+     * history via REST and injects any missing entries as synthetic
+     * `message_appended` events. This compensates for Conductor deployments
+     * where the realtime broadcast doesn't always reach the WS connection
+     * (multi-instance fan-out without a backplane, idempotent commit retries
+     * that bypass projection, momentary WS drops). Disable with
+     * `disableHistoryCatchUp: true` for callers that prefer the raw stream.
      */
     subscribe(taskId: string, opts?: {
         signal?: AbortSignal;
         bufferCap?: number;
+        /**
+         * Disable the post-terminal history catch-up. Default: catch-up
+         * enabled. Set to `true` to receive only events that traveled the
+         * realtime path (no synthetic `message_appended` injected from
+         * REST).
+         */
+        disableHistoryCatchUp?: boolean;
     }): AsyncIterable<ChatEvent>;
     /**
      * Higher-level convenience: yield only AI reply deltas. Internally consumes

package/dist/server/index.js

@@ -1151,6 +1151,8 @@ function streamReplyForTask(socket, taskId, opts) {
 }
 
 // src/server/client.ts
+var CATCH_UP_DELAY_MS = 500;
+var CATCH_UP_LIMIT = 20;
 var AppClient = class {
   projects;
   tasks;
@@ -1252,6 +1254,17 @@ var TasksApi = class {
    *
    * The first call lazily opens a /ws/app connection; subsequent calls share
    * the same connection.
+   *
+   * History catch-up (enabled by default): when a terminal event arrives
+   * (`task_finished`, `task_failed`, `runtime_status` flipping
+   * `replyInProgress` true→false, or `connection_state` recovering from
+   * `reconnecting → connected`), the wrapper pulls a window of recent
+   * history via REST and injects any missing entries as synthetic
+   * `message_appended` events. This compensates for Conductor deployments
+   * where the realtime broadcast doesn't always reach the WS connection
+   * (multi-instance fan-out without a backplane, idempotent commit retries
+   * that bypass projection, momentary WS drops). Disable with
+   * `disableHistoryCatchUp: true` for callers that prefer the raw stream.
    */
   subscribe(taskId, opts) {
     if (!taskId) {
@@ -1262,37 +1275,185 @@ var TasksApi = class {
     }
     this.assertOpen();
     const socket = this.getSocket();
+    const rest = this.rest;
     const inner = subscribeToTask(socket, taskId, opts);
+    const catchUpEnabled = opts?.disableHistoryCatchUp !== true;
     return {
+      // Each `for await` consumer gets its own iterator with its own queue,
+      // pump task, knownIds set, and catch-up state. Multiple concurrent
+      // iterations over the same returned AsyncIterable do not share state
+      // beyond the underlying socket (which is shared by design).
       [Symbol.asyncIterator]() {
         const innerIter = inner[Symbol.asyncIterator]();
-        const connectPromise = socket.connect().then(
-          () => null,
-          (err) => err
-        );
-        let connectChecked = false;
-        return {
-          async next() {
-            if (!connectChecked) {
-              connectChecked = true;
+        const queue = [];
+        let pendingResolve = null;
+        let upstreamDone = false;
+        let consumerReturned = false;
+        const knownIds = /* @__PURE__ */ new Set();
+        let prevReplyInProgress;
+        let prevConnectionState;
+        let catchUpInFlight = 0;
+        let needAnotherCatchUp = false;
+        let activeCatchUpAbort = null;
+        const wakePending = (r) => {
+          const resolver = pendingResolve;
+          pendingResolve = null;
+          resolver?.(r);
+        };
+        const drain = () => {
+          if (!pendingResolve) return;
+          if (queue.length > 0) {
+            wakePending({ value: queue.shift(), done: false });
+            return;
+          }
+          if (upstreamDone && catchUpInFlight === 0) {
+            wakePending({ value: void 0, done: true });
+          }
+        };
+        const enqueue = (ev) => {
+          if (consumerReturned) return;
+          queue.push(ev);
+          drain();
+        };
+        const triggerCatchUp = (delayMs) => {
+          if (consumerReturned || !catchUpEnabled) return;
+          if (catchUpInFlight > 0) {
+            needAnotherCatchUp = true;
+            return;
+          }
+          catchUpInFlight += 1;
+          const abort = new AbortController();
+          activeCatchUpAbort = abort;
+          void (async () => {
+            try {
+              if (delayMs > 0) {
+                await new Promise((r) => setTimeout(r, delayMs));
+              }
+              if (consumerReturned || abort.signal.aborted) return;
+              const page = await rest.history(
+                taskId,
+                { limit: CATCH_UP_LIMIT },
+                { signal: abort.signal }
+              );
+              if (consumerReturned || abort.signal.aborted) return;
+              for (const m of page.messages) {
+                if (!m.id) continue;
+                if (knownIds.has(m.id)) continue;
+                knownIds.add(m.id);
+                enqueue({ type: "message_appended", message: m });
+              }
+            } catch (err) {
+              const name = err?.name;
+              const code = err?.code;
+              if (name === "AbortError" || code === "stream_aborted") return;
+              console.warn("[app-sdk] subscribe history catch-up failed", err);
+            } finally {
+              if (activeCatchUpAbort === abort) {
+                activeCatchUpAbort = null;
+              }
+              catchUpInFlight -= 1;
+              if (needAnotherCatchUp && !consumerReturned) {
+                needAnotherCatchUp = false;
+                triggerCatchUp(0);
+              }
+              drain();
+            }
+          })();
+        };
+        let pumpStarted = false;
+        const startPump = () => {
+          if (pumpStarted) return;
+          pumpStarted = true;
+          const connectPromise = socket.connect().then(
+            () => null,
+            (err) => err
+          );
+          void (async () => {
+            try {
               const err = await connectPromise;
               if (err) {
                 try {
                   await innerIter.return?.();
                 } catch {
                 }
-                const event = {
+                enqueue({
                   type: "task_failed",
                   taskId,
                   error: errorToChatError(err, "subscribe_failed")
-                };
-                return { value: event, done: false };
+                });
+                upstreamDone = true;
+                drain();
+                return;
+              }
+              while (!consumerReturned) {
+                const r = await innerIter.next();
+                if (r.done) {
+                  upstreamDone = true;
+                  drain();
+                  return;
+                }
+                const ev = r.value;
+                if (catchUpEnabled) {
+                  if (ev.type === "message_appended") {
+                    if (ev.message.id) knownIds.add(ev.message.id);
+                  } else if (ev.type === "task_finished" || ev.type === "task_failed") {
+                    triggerCatchUp(CATCH_UP_DELAY_MS);
+                  } else if (ev.type === "runtime_status") {
+                    const now = ev.status.replyInProgress;
+                    if (prevReplyInProgress === true && now === false) {
+                      triggerCatchUp(CATCH_UP_DELAY_MS);
+                    }
+                    prevReplyInProgress = now;
+                  } else if (ev.type === "connection_state") {
+                    if (ev.state === "connected" && prevConnectionState === "reconnecting") {
+                      triggerCatchUp(0);
+                    }
+                    prevConnectionState = ev.state;
+                  }
+                }
+                enqueue(ev);
+              }
+            } catch (err) {
+              if (!consumerReturned) {
+                enqueue({
+                  type: "task_failed",
+                  taskId,
+                  error: errorToChatError(err, "subscribe_failed")
+                });
+                upstreamDone = true;
+                drain();
               }
             }
-            return innerIter.next();
+          })();
+        };
+        return {
+          async next() {
+            if (consumerReturned) {
+              return { value: void 0, done: true };
+            }
+            startPump();
+            if (queue.length > 0) {
+              return { value: queue.shift(), done: false };
+            }
+            if (upstreamDone && catchUpInFlight === 0) {
+              return { value: void 0, done: true };
+            }
+            return new Promise((resolve) => {
+              pendingResolve = resolve;
+            });
           },
           async return() {
-            return await innerIter.return?.() ?? { value: void 0, done: true };
+            consumerReturned = true;
+            activeCatchUpAbort?.abort();
+            activeCatchUpAbort = null;
+            try {
+              await innerIter.return?.();
+            } catch {
+            }
+            if (pendingResolve) {
+              wakePending({ value: void 0, done: true });
+            }
+            return { value: void 0, done: true };
           }
         };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@love-moon/app-sdk",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Conductor App SDK: third-party backend SDK + React chat widget for embedding Conductor AI tools",
   "repository": {
     "type": "git",
@@ -60,8 +60,12 @@
     "react-dom": ">=18.0.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "react-dom": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.10.2",