@aleph-alpha/chat-kit 1.11.1 → 1.12.0

package/src/adapters/responses-api.ts

@@ -23,6 +23,7 @@ import { generateId } from '../helpers';
 import type {
   ConversationTree,
   MessageContent,
+  MessageMetadata,
   MessageRole,
   TreeMessage,
 } from '../types';
@@ -213,6 +214,22 @@ export interface ResponseAttachment {
   searchStoreId: string;
 }
 
+/**
+ * Render-side attachment shape produced by `responsesToTree`. Stored under
+ * `metadata.attachments` on the user `TreeMessage` (chat-kit's `BaseMessage`
+ * /`TreeMessage` carry `metadata` as an opaque `Record<string, unknown>`).
+ *
+ * The shape is intentionally minimal — a human-readable `name` plus the
+ * optional ids needed to resolve a public URL for the file. Consumers
+ * using a different attachment shape can either skip this adapter or
+ * project this onto their own type at the read site.
+ */
+export interface ResponseMessageAttachment {
+  name: string;
+  fileId?: string;
+  searchStoreId?: string;
+}
+
 /**
  * One stored response from the OpenAI-style Responses API, as returned by
  * `GET /conversations/:id/responses`. `previous_response_id` chains
@@ -230,7 +247,7 @@ export interface StoredResponse {
   output: ResponseOutput[];
   request_input: Record<string, unknown>[];
   metadata?: Record<string, unknown> & {
-    attachments?: ResponseAttachment[];
+    attachments?: string;
   };
   conversation?: { id: string };
   ancestor_ids?: string[];
@@ -252,11 +269,47 @@ export interface ResponseList {
 // Conversion: StoredResponse[] → ConversationTree
 // ---------------------------------------------------------------------------
 
+/**
+ * Per-node metadata produced by `responsesToTree`. The adapter is the
+ * single point that knows about the Responses-API wire format, so it
+ * stamps the originating `responseId` onto every node it emits. Anything
+ * downstream that reads it (typically a host app linking a tree message
+ * back to its server-side response) does so via this narrower metadata
+ * shape — chat-kit core stays oblivious to the field and treats it as
+ * opaque metadata.
+ */
+export type ResponseTreeMessageMetadata = MessageMetadata & {
+  responseId: string;
+  attachments?: ResponseMessageAttachment[];
+};
+
+/**
+ * Tree node emitted by `responsesToTree`. Structurally a `TreeMessage`,
+ * but with `metadata` narrowed to {@link ResponseTreeMessageMetadata} and
+ * promoted from optional to required: every node carries at least the
+ * originating `responseId`. Assignable to `TreeMessage` so the resulting
+ * tree can be passed directly to `useMessageHandler().setTree(...)`.
+ */
+export type ResponseTreeMessage = Omit<TreeMessage, 'metadata'> & {
+  metadata: ResponseTreeMessageMetadata;
+};
+
+/**
+ * `ConversationTree` returned by `responsesToTree`. Same shape as the
+ * core `ConversationTree`, with every node typed as a
+ * {@link ResponseTreeMessage} so callers can read `metadata.responseId`
+ * without re-narrowing. Structurally assignable to `ConversationTree`.
+ */
+export interface ResponseConversationTree extends ConversationTree {
+  nodes: Record<string, ResponseTreeMessage>;
+}
+
 interface ResponseMessageNode {
   id: string;
   role: MessageRole;
   content: MessageContent[];
   createdAt: Date;
+  metadata: ResponseTreeMessageMetadata;
 }
 
 function extractMessageText(parts: ResponseOutputTextPart[]): string {
@@ -373,6 +426,38 @@ function extractInputText(rawContent: unknown): string {
   return text.trim();
 }
 
+// Parse `resp.metadata.attachments` defensively. The Responses API
+// serialises the value as a JSON-encoded string (transports that persist
+// metadata flatten nested objects, so the array is stringified on the
+// wire). Returns `null` when the payload is missing, empty, or malformed —
+// callers treat that as "no attachments on this response". Malformed
+// payloads are logged via `console.warn` so consumers can spot upstream
+// serialisation issues.
+function parseResponseAttachments(
+  resp: StoredResponse,
+): ResponseAttachment[] | null {
+  const raw = resp.metadata?.attachments;
+  if (!raw) return null;
+
+  let attachments: unknown;
+  try {
+    attachments = JSON.parse(raw);
+  } catch {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[chat-kit] Failed to parse metadata.attachments as JSON; skipping.',
+      raw,
+    );
+    return null;
+  }
+
+  if (!Array.isArray(attachments) || attachments.length === 0) {
+    return null;
+  }
+
+  return attachments as ResponseAttachment[];
+}
+
 // Within a single response, the visible messages chain linearly: every user
 // input is followed by exactly one assistant turn (whose reasoning, tool,
 // and text outputs are merged into one node). Across responses, branching
@@ -380,21 +465,41 @@ function extractInputText(rawContent: unknown): string {
 // same parent and form sibling subtrees.
 function responseToMessageNodes(resp: StoredResponse): ResponseMessageNode[] {
   const nodes: ResponseMessageNode[] = [];
+  // Attachments are stored at the response level but logically belong to
+  // the user turn that started the response. We bind them to the first
+  // user `request_input` (mirroring the existing wire convention).
+  const responseAttachments = parseResponseAttachments(resp);
+  let userNodesPushed = 0;
   if (resp.request_input) {
     for (const [idx, input] of resp.request_input.entries()) {
       const role = (input as { role?: string }).role;
       const rawContent = (input as { content?: unknown }).content;
       const text = extractInputText(rawContent);
-      if (role === 'user' && text) {
-        nodes.push({
-          id: `user-${resp.id}-${idx}`,
-          role: 'user',
-          content: [textPart(text)],
-          createdAt: new Date(resp.created_at * 1000),
-        });
+      const userContent = text || responseAttachments?.length;
+      if (role !== 'user' || !userContent) continue;
+
+      const metadata: ResponseTreeMessageMetadata = { responseId: resp.id };
+      if (responseAttachments && userNodesPushed === 0) {
+        metadata.attachments = responseAttachments.map(
+          (a): ResponseMessageAttachment => ({
+            name: a.fileName,
+            fileId: a.fileId,
+            searchStoreId: a.searchStoreId,
+          }),
+        );
       }
+
+      nodes.push({
+        id: `user-${resp.id}-${idx}`,
+        role: 'user',
+        content: [textPart(text)],
+        createdAt: new Date(resp.created_at * 1000),
+        metadata,
+      });
+      userNodesPushed += 1;
     }
   }
+
   const assistantParts = toAssistantParts(resp);
   if (assistantParts.length > 0) {
     nodes.push({
@@ -402,6 +507,7 @@ function responseToMessageNodes(resp: StoredResponse): ResponseMessageNode[] {
       role: 'assistant',
       content: assistantParts,
       createdAt: new Date((resp.completed_at ?? resp.created_at) * 1000),
+      metadata: { responseId: resp.id },
     });
   }
   return nodes;
@@ -417,15 +523,19 @@ function responseToMessageNodes(resp: StoredResponse): ResponseMessageNode[] {
  * last message immediately. Sibling responses (same `previous_response_id`)
  * surface as branches; the latest one wins as the active branch.
  *
- * Pair with `useMessageHandler().setTree(responsesToTree(responses))` when
- * you want to hydrate a handler.
+ * Every emitted node carries `metadata.responseId` pointing back to the
+ * originating `StoredResponse.id` (see {@link ResponseTreeMessage}). The
+ * return type is assignable to `ConversationTree`, so you can pipe it
+ * straight into `useMessageHandler().setTree(...)`.
  */
-export function responsesToTree(responses: StoredResponse[]): ConversationTree {
+export function responsesToTree(
+  responses: StoredResponse[],
+): ResponseConversationTree {
   if (responses.length === 0) {
     return { nodes: {}, rootId: null };
   }
 
-  const treeNodes: Record<string, TreeMessage> = {};
+  const treeNodes: Record<string, ResponseTreeMessage> = {};
   // For each response, the id of its last visible message — that's the
   // attachment point for any future child response that chains onto it.
   // Empty responses fall back to their parent's attachment point so the
@@ -443,6 +553,7 @@ export function responsesToTree(responses: StoredResponse[]): ConversationTree {
       content: node.content,
       status: 'completed',
       createdAt: node.createdAt,
+      metadata: node.metadata,
     };
     if (parentId !== null) {
       const parent = treeNodes[parentId];

package/src/handlers/useMessageHandler.spec.ts

@@ -118,6 +118,34 @@ describe('useMessageHandler', () => {
       handler.setCurrentUserMessage('   ');
       expect(() => handler.commitUserMessage()).toThrow('No message');
     });
+
+    it('attaches metadata when supplied and exposes it on the message', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      const msg = handler.commitUserMessage({
+        metadata: {
+          attachments: [
+            { name: 'report.pdf', fileId: 'f1', searchStoreId: 's1' },
+          ],
+        },
+      });
+
+      expect(msg.metadata).toEqual({
+        attachments: [
+          { name: 'report.pdf', fileId: 'f1', searchStoreId: 's1' },
+        ],
+      });
+      expect(handler.messages.value[0].metadata).toEqual(msg.metadata);
+    });
+
+    it('omits metadata on the returned message when none is supplied', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      const msg = handler.commitUserMessage();
+
+      expect('metadata' in msg).toBe(false);
+      expect('metadata' in handler.messages.value[0]).toBe(false);
+    });
   });
 
   describe('updateMessage', () => {
@@ -232,6 +260,61 @@ describe('useMessageHandler', () => {
       expect(getText(handler.messages.value[1].content)).toBe('Regenerated');
     });
 
+    it('preserves existing metadata when the update omits it', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      const msg = handler.commitUserMessage({
+        metadata: { attachments: [{ name: 'report.pdf' }] },
+      });
+
+      handler.updateMessage({
+        id: msg.id,
+        content: [text('Edited')],
+        role: 'user',
+        status: 'completed',
+      });
+
+      expect(handler.getMessageById(msg.id)?.metadata).toEqual({
+        attachments: [{ name: 'report.pdf' }],
+      });
+    });
+
+    it('overwrites metadata when explicitly supplied on update', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      const msg = handler.commitUserMessage({
+        metadata: { attachments: [{ name: 'old.pdf' }] },
+      });
+
+      handler.updateMessage({
+        id: msg.id,
+        content: [text('Hello')],
+        role: 'user',
+        status: 'completed',
+        metadata: { attachments: [{ name: 'new.pdf' }] },
+      });
+
+      expect(handler.getMessageById(msg.id)?.metadata).toEqual({
+        attachments: [{ name: 'new.pdf' }],
+      });
+    });
+
+    it('upserts a new message with metadata when supplied', () => {
+      const handler = useMessageHandler();
+      handler.updateMessage({
+        id: 'u-new',
+        content: [text('Hello')],
+        role: 'user',
+        status: 'completed',
+        metadata: { attachments: [{ name: 'fresh.pdf' }] },
+      });
+
+      const stored = handler.getMessageById('u-new');
+      expect(stored?.metadata).toEqual({
+        attachments: [{ name: 'fresh.pdf' }],
+      });
+    });
+
     it('does not truncate when updating the last message', () => {
       const handler = useMessageHandler();
       handler.setTree(
@@ -551,6 +634,137 @@ describe('useMessageHandler', () => {
     });
   });
 
+  describe('cutBranchAfter', () => {
+    it('removes every message that comes after the target on the active path', () => {
+      const handler = useMessageHandler();
+      handler.setTree(
+        makeTree(
+          {
+            u1: makeTreeMessage({ id: 'u1', content: [text('Hello')] }),
+            a1: makeTreeMessage({
+              id: 'a1',
+              parentId: 'u1',
+              role: 'assistant',
+              content: [text('Hi')],
+            }),
+            u2: makeTreeMessage({
+              id: 'u2',
+              parentId: 'a1',
+              content: [text('Follow-up')],
+            }),
+            a2: makeTreeMessage({
+              id: 'a2',
+              parentId: 'u2',
+              role: 'assistant',
+              content: [text('Answer')],
+            }),
+          },
+          'u1',
+        ),
+      );
+
+      handler.cutBranchAfter('u2');
+
+      expect(handler.messages.value.map((m) => m.id)).toEqual([
+        'u1',
+        'a1',
+        'u2',
+      ]);
+      expect(handler.getMessageById('a2')).toBeUndefined();
+    });
+
+    it('keeps the target message and makes it the new leaf', () => {
+      const handler = useMessageHandler();
+      handler.setTree(
+        makeTree(
+          {
+            u1: makeTreeMessage({ id: 'u1', content: [text('Hello')] }),
+            a1: makeTreeMessage({
+              id: 'a1',
+              parentId: 'u1',
+              role: 'assistant',
+              content: [text('Hi')],
+            }),
+            u2: makeTreeMessage({
+              id: 'u2',
+              parentId: 'a1',
+              content: [text('Follow-up')],
+            }),
+          },
+          'u1',
+        ),
+      );
+
+      handler.cutBranchAfter('a1');
+
+      expect(handler.getMessageById('a1')).toBeDefined();
+      expect(handler.currentLeafId.value).toBe('a1');
+    });
+
+    it('drops sibling branches that share the cut ancestor', () => {
+      const handler = useMessageHandler();
+      handler.setTree(
+        makeTree(
+          {
+            u1: makeTreeMessage({ id: 'u1', content: [text('Hello')] }),
+            a1: makeTreeMessage({
+              id: 'a1',
+              parentId: 'u1',
+              role: 'assistant',
+              content: [text('Hi')],
+            }),
+            a2: makeTreeMessage({
+              id: 'a2',
+              parentId: 'u1',
+              role: 'assistant',
+              content: [text('Hey')],
+            }),
+            u2: makeTreeMessage({
+              id: 'u2',
+              parentId: 'a2',
+              content: [text('Follow-up')],
+            }),
+          },
+          'u1',
+        ),
+      );
+
+      handler.cutBranchAfter('u1');
+
+      expect(handler.getMessageById('a1')).toBeUndefined();
+      expect(handler.getMessageById('a2')).toBeUndefined();
+      expect(handler.getMessageById('u2')).toBeUndefined();
+      expect(handler.messages.value.map((m) => m.id)).toEqual(['u1']);
+    });
+
+    it('is a no-op when the target has no descendants', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      const msg = handler.commitUserMessage();
+
+      handler.cutBranchAfter(msg.id);
+
+      expect(handler.messages.value).toHaveLength(1);
+      expect(handler.messages.value[0].id).toBe(msg.id);
+    });
+
+    it('is a no-op for a nonexistent id', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      handler.commitUserMessage();
+      handler.updateMessage({
+        id: 'a1',
+        content: [text('Reply')],
+        role: 'assistant',
+        status: 'completed',
+      });
+
+      handler.cutBranchAfter('nonexistent');
+
+      expect(handler.messages.value).toHaveLength(2);
+    });
+  });
+
   describe('currentLeafId', () => {
     it('is null when there are no messages', () => {
       const handler = useMessageHandler();

package/src/handlers/useMessageHandler.ts

@@ -2,6 +2,7 @@ import {
   generateId,
   addNode as treeAddNode,
   createEmptyTree,
+  cutBranchAfter as treeCutBranchAfter,
   getLinearPath,
   navigate as treeNavigate,
   updateNode,
@@ -11,6 +12,7 @@ import type {
   BaseMessage,
   ConversationTree,
   MessageContent,
+  MessageMetadata,
   MessageRole,
   MessageStatus,
   TreeMessage,
@@ -36,7 +38,9 @@ export const useMessageHandler = () => {
     currentUserMessage.value = '';
   }
 
-  function commitUserMessage(): BaseMessage {
+  function commitUserMessage(opts?: {
+    metadata?: MessageMetadata;
+  }): BaseMessage {
     const id = generateId();
     const text = currentUserMessage.value.trim();
     if (!text) throw new Error('No message');
@@ -54,18 +58,21 @@ export const useMessageHandler = () => {
       content,
       status: 'completed',
       createdAt: new Date(),
+      ...(opts?.metadata !== undefined ? { metadata: opts.metadata } : {}),
     };
 
     treeAddNode(tree, node);
     clearCurrentUserMessage();
 
-    return {
+    const base: BaseMessage = {
       id: node.id,
       role: node.role,
       content: node.content,
       createdAt: node.createdAt,
       status: node.status,
     };
+    if (node.metadata !== undefined) base.metadata = node.metadata;
+    return base;
   }
 
   function updateMessage(message: {
@@ -73,6 +80,7 @@ export const useMessageHandler = () => {
     content: MessageContent[];
     role: MessageRole;
     status: MessageStatus;
+    metadata?: MessageMetadata;
   }) {
     const existing = tree.nodes[message.id];
 
@@ -81,6 +89,9 @@ export const useMessageHandler = () => {
         content: message.content,
         role: message.role,
         status: message.status,
+        ...(message.metadata !== undefined
+          ? { metadata: message.metadata }
+          : {}),
       });
     } else {
       const node: TreeMessage = {
@@ -92,6 +103,9 @@ export const useMessageHandler = () => {
         content: message.content,
         status: message.status,
         createdAt: new Date(),
+        ...(message.metadata !== undefined
+          ? { metadata: message.metadata }
+          : {}),
       };
       treeAddNode(tree, node);
     }
@@ -100,13 +114,15 @@ export const useMessageHandler = () => {
   function getMessageById(id: string): BaseMessage | undefined {
     const node = tree.nodes[id];
     if (!node) return undefined;
-    return {
+    const base: BaseMessage = {
       id: node.id,
       role: node.role,
       content: node.content,
       createdAt: node.createdAt,
       status: node.status,
+      ...(node.metadata !== undefined ? { metadata: node.metadata } : {}),
     };
+    return base;
   }
 
   function updateMessageId(oldId: string, newId: string) {
@@ -135,6 +151,14 @@ export const useMessageHandler = () => {
     treeNavigate(tree, targetId);
   }
 
+  /**
+   * Drop every message that comes after `messageId` on every branch beneath
+   * it. The target message is kept and becomes the new leaf of its branch.
+   */
+  function cutBranchAfter(messageId: string) {
+    treeCutBranchAfter(tree, messageId);
+  }
+
   return {
     messages: messages as Ref<BaseMessage[]>,
     currentUserMessage: readonly(currentUserMessage),
@@ -148,5 +172,6 @@ export const useMessageHandler = () => {
     clearMessages,
     setTree,
     navigate,
+    cutBranchAfter,
   };
 };