@popcomputer/structured-chat 0.2.0-rc.0 → 0.2.0

package/dist/integrations/assistant-ui.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentType, type FC } from "react";
+import type { StructuredChatDebugSnapshot } from "../core/debug.js";
 import type { ViewData, ViewDefinitionContract } from "../core/view.js";
 import { type StructuredChatSessionReference, type StructuredChatAssistantMessage } from "../core/protocol.js";
 /** Runtime status supplied by assistant-ui to a data-part renderer. */
@@ -52,6 +53,12 @@ export type AssistantChatFetch = (input: string, init: RequestInit) => Promise<R
 export interface AssistantChatModelAdapterOptions {
     readonly endpoint: string;
     readonly fetch?: AssistantChatFetch;
+    /**
+     * Select the explicit debug response contract and receive its safe state
+     * projection after every successful turn. Observer failures are ignored so
+     * they cannot change the outcome of an already-persisted chat turn.
+     */
+    readonly onDebugSnapshot?: (snapshot: StructuredChatDebugSnapshot) => void | Promise<void>;
 }
 /** Minimum assistant message shape consumed by the browser adapter. */
 export interface AssistantChatThreadMessage {
@@ -88,8 +95,8 @@ export interface AssistantChatModelAdapter {
 /**
  * Adapt assistant-ui to one server-owned structured chat endpoint.
  *
- * Only the latest text and opaque prior revision cross the browser boundary.
- * Tools, instructions, history, answer state, and stage position stay server
- * owned.
+ * By default, only the latest text and opaque prior revision cross the browser
+ * boundary. Supplying `onDebugSnapshot` explicitly selects the separate debug
+ * response contract and receives its safe answer-and-stage projection.
  */
 export declare const makeAssistantChatModelAdapter: (options: AssistantChatModelAdapterOptions) => AssistantChatModelAdapter;

package/dist/integrations/assistant-ui.js

@@ -39,6 +39,15 @@ export const makeAssistantView = (view, config) => {
 };
 /** assistant-ui metadata key carrying the latest opaque session reference. */
 export const assistantChatSessionMetadataKey = "popcomputerStructuredChatSession";
+const notifyDebugSnapshot = (callback, snapshot) => {
+    try {
+        const notified = callback(snapshot);
+        void Promise.resolve(notified).catch(() => undefined);
+    }
+    catch {
+        // Debug observers are deliberately isolated from the persisted turn.
+    }
+};
 const readMessageText = (message) => message.content
     .flatMap((part) => part.type === "text" && "text" in part ? [part.text] : [])
     .join("\n")
@@ -72,13 +81,14 @@ const readTurnRequest = (messages) => {
 /**
  * Adapt assistant-ui to one server-owned structured chat endpoint.
  *
- * Only the latest text and opaque prior revision cross the browser boundary.
- * Tools, instructions, history, answer state, and stage position stay server
- * owned.
+ * By default, only the latest text and opaque prior revision cross the browser
+ * boundary. Supplying `onDebugSnapshot` explicitly selects the separate debug
+ * response contract and receives its safe answer-and-stage projection.
  */
 export const makeAssistantChatModelAdapter = (options) => {
     const fetch_ = options.fetch ??
         ((input, init) => globalThis.fetch(input, init));
+    const onDebugSnapshot = options.onDebugSnapshot;
     return {
         run: async ({ messages, abortSignal }) => {
             const request = readTurnRequest(messages);
@@ -102,17 +112,30 @@ export const makeAssistantChatModelAdapter = (options) => {
             catch {
                 throw new Error("Structured chat returned an invalid response");
             }
-            const decoded = Schema.decodeUnknownExit(StructuredChatTurnResponseSchema)(body, { onExcessProperty: "error" });
-            if (Exit.isFailure(decoded)) {
-                throw new Error("Structured chat returned an invalid response");
+            let value;
+            if (onDebugSnapshot === undefined) {
+                const decoded = Schema.decodeUnknownExit(StructuredChatTurnResponseSchema)(body, { onExcessProperty: "error" });
+                if (Exit.isFailure(decoded)) {
+                    throw new Error("Structured chat returned an invalid response");
+                }
+                value = decoded.value;
+            }
+            else {
+                const { StructuredChatDebugTurnResponseSchema } = await import("../core/debug-protocol.js");
+                const decoded = Schema.decodeUnknownExit(StructuredChatDebugTurnResponseSchema)(body, { onExcessProperty: "error" });
+                if (Exit.isFailure(decoded)) {
+                    throw new Error("Structured chat returned an invalid response");
+                }
+                notifyDebugSnapshot(onDebugSnapshot, decoded.value.debug);
+                value = decoded.value;
             }
             return {
-                content: decoded.value.message.content,
+                content: value.message.content,
                 metadata: {
-                    custom: decoded.value.session === undefined
+                    custom: value.session === undefined
                         ? {}
                         : {
-                            [assistantChatSessionMetadataKey]: decoded.value.session,
+                            [assistantChatSessionMetadataKey]: value.session,
                         },
                 },
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcomputer/structured-chat",
-  "version": "0.2.0-rc.0",
+  "version": "0.2.0",
   "description": "Schema-defined structured chats with typed tools, stages, and UI views",
   "type": "module",
   "packageManager": "bun@1.3.1",
@@ -23,6 +23,10 @@
     "./assistant-ui": {
       "types": "./dist/integrations/assistant-ui.d.ts",
       "import": "./dist/integrations/assistant-ui.js"
+    },
+    "./assistant-ui/debug": {
+      "types": "./dist/integrations/assistant-ui-debug.d.ts",
+      "import": "./dist/integrations/assistant-ui-debug.js"
     }
   },
   "files": [