@aleph-alpha/chat-kit 1.11.1 → 1.13.0

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,
   };
 };

package/src/helpers/conversationTree.spec.ts

@@ -7,6 +7,7 @@ import type {
 import {
   addNode,
   createEmptyTree,
+  cutBranchAfter,
   getLinearPath,
   navigate,
   updateNode,
@@ -193,6 +194,35 @@ describe('getLinearPath', () => {
     expect(u1Msg.status).toBe('completed');
     expect(u1Msg.createdAt).toEqual(new Date('2025-01-01'));
   });
+
+  it('forwards node metadata onto the BaseMessage projection', () => {
+    const tree = createEmptyTree();
+    addNode(
+      tree,
+      makeTreeMessage({
+        id: 'u1',
+        content: [text('Hello')],
+        metadata: {
+          attachments: [
+            { name: 'report.pdf', fileId: 'f1', searchStoreId: 's1' },
+          ],
+        },
+      }),
+    );
+
+    const path = getLinearPath(tree);
+    expect(path[0].metadata).toEqual({
+      attachments: [{ name: 'report.pdf', fileId: 'f1', searchStoreId: 's1' }],
+    });
+  });
+
+  it('omits metadata when the node has none', () => {
+    const tree = createEmptyTree();
+    addNode(tree, makeTreeMessage({ id: 'u1', content: [text('Hello')] }));
+
+    const path = getLinearPath(tree);
+    expect('metadata' in path[0]).toBe(false);
+  });
 });
 
 describe('addNode', () => {
@@ -287,6 +317,38 @@ describe('updateNode', () => {
     updateNode(tree, 'nonexistent', { content: [text('x')] });
     expect(Object.keys(tree.nodes).length).toBe(nodeCount);
   });
+
+  it('sets metadata when supplied', () => {
+    const tree = makeBranchingTree();
+    updateNode(tree, 'u1', {
+      metadata: {
+        attachments: [{ name: 'report.pdf', fileId: 'f1' }],
+      },
+    });
+    expect(tree.nodes.u1.metadata).toEqual({
+      attachments: [{ name: 'report.pdf', fileId: 'f1' }],
+    });
+  });
+
+  it('clears metadata when explicitly set to undefined', () => {
+    const tree = makeBranchingTree();
+    tree.nodes.u1.metadata = {
+      attachments: [{ name: 'old.pdf' }],
+    };
+    updateNode(tree, 'u1', { metadata: undefined });
+    expect(tree.nodes.u1.metadata).toBeUndefined();
+  });
+
+  it('leaves metadata untouched when the key is absent from updates', () => {
+    const tree = makeBranchingTree();
+    tree.nodes.u1.metadata = {
+      attachments: [{ name: 'keep.pdf' }],
+    };
+    updateNode(tree, 'u1', { content: [text('Updated')] });
+    expect(tree.nodes.u1.metadata).toEqual({
+      attachments: [{ name: 'keep.pdf' }],
+    });
+  });
 });
 
 describe('updateNodeId', () => {
@@ -385,6 +447,78 @@ describe('navigate', () => {
   });
 });
 
+describe('cutBranchAfter', () => {
+  it('removes every descendant of the target node', () => {
+    const tree = makeBranchingTree();
+
+    cutBranchAfter(tree, 'u2');
+
+    expect(tree.nodes.a2).toBeUndefined();
+    expect(tree.nodes.a3).toBeUndefined();
+  });
+
+  it('keeps the target node and clears its children', () => {
+    const tree = makeBranchingTree();
+
+    cutBranchAfter(tree, 'u2');
+
+    expect(tree.nodes.u2).toBeDefined();
+    expect(tree.nodes.u2.childrenIds).toEqual([]);
+    expect(tree.nodes.u2.activeChildIndex).toBe(0);
+  });
+
+  it('makes the target node the leaf of the active path', () => {
+    const tree = makeBranchingTree();
+
+    cutBranchAfter(tree, 'u2');
+
+    const path = getLinearPath(tree);
+    expect(path.map((m) => m.id)).toEqual(['u1', 'a1', 'u2']);
+  });
+
+  it('removes the entire subtree, including grandchildren', () => {
+    const tree = makeBranchingTree();
+
+    cutBranchAfter(tree, 'u1');
+
+    expect(Object.keys(tree.nodes)).toEqual(['u1']);
+    expect(tree.nodes.u1.childrenIds).toEqual([]);
+  });
+
+  it('only cuts descendants — sibling branches are untouched', () => {
+    const tree = makeBranchingTree();
+
+    cutBranchAfter(tree, 'a1');
+
+    expect(tree.nodes.u2).toBeUndefined();
+    expect(tree.nodes.a2).toBeUndefined();
+    expect(tree.nodes.a3).toBeUndefined();
+
+    expect(tree.nodes.a1b).toBeDefined();
+    expect(tree.nodes.u3).toBeDefined();
+    expect(tree.nodes.u1.childrenIds).toEqual(['a1', 'a1b']);
+  });
+
+  it('is a no-op when the node has no children', () => {
+    const tree = makeBranchingTree();
+    const nodeCount = Object.keys(tree.nodes).length;
+
+    cutBranchAfter(tree, 'a2');
+
+    expect(Object.keys(tree.nodes).length).toBe(nodeCount);
+    expect(tree.nodes.a2.childrenIds).toEqual([]);
+  });
+
+  it('is a no-op for a nonexistent id', () => {
+    const tree = makeBranchingTree();
+    const before = Object.keys(tree.nodes).sort();
+
+    cutBranchAfter(tree, 'nonexistent');
+
+    expect(Object.keys(tree.nodes).sort()).toEqual(before);
+  });
+});
+
 describe('integration: full branching scenario', () => {
   it('simulates send → regenerate → navigate workflow', () => {
     const tree = createEmptyTree();

package/src/helpers/conversationTree.ts

@@ -25,6 +25,7 @@ export function getLinearPath(tree: ConversationTree): BaseMessage[] {
       content: node.content,
       createdAt: node.createdAt,
       status: node.status,
+      ...(node.metadata !== undefined ? { metadata: node.metadata } : {}),
     };
 
     if (node.parentId !== null) {
@@ -61,7 +62,9 @@ export function addNode(tree: ConversationTree, node: TreeMessage): void {
 export function updateNode(
   tree: ConversationTree,
   id: string,
-  updates: Partial<Pick<TreeMessage, 'content' | 'status' | 'role'>>,
+  updates: Partial<
+    Pick<TreeMessage, 'content' | 'status' | 'role' | 'metadata'>
+  >,
 ): void {
   const node = tree.nodes[id];
   if (!node) return;
@@ -69,6 +72,9 @@ export function updateNode(
   if (updates.content !== undefined) node.content = updates.content;
   if (updates.status !== undefined) node.status = updates.status;
   if (updates.role !== undefined) node.role = updates.role;
+  // `metadata` is intentionally allowed through with an `undefined` value so
+  // callers can clear it; the call site checks for `'metadata' in updates`.
+  if ('metadata' in updates) node.metadata = updates.metadata;
 }
 
 export function updateNodeId(
@@ -99,6 +105,31 @@ export function updateNodeId(
   if (tree.rootId === oldId) tree.rootId = newId;
 }
 
+/**
+ * Remove every descendant of the node with the given id, keeping the node
+ * itself intact. The node's `childrenIds` is cleared and `activeChildIndex`
+ * is reset to 0, which makes the node the new leaf of its branch.
+ *
+ * Useful when editing a message and discarding the conversation that was
+ * generated after it.
+ */
+export function cutBranchAfter(tree: ConversationTree, id: string): void {
+  const node = tree.nodes[id];
+  if (!node) return;
+
+  const stack: string[] = [...node.childrenIds];
+  while (stack.length > 0) {
+    const currentId = stack.pop() as string;
+    const current = tree.nodes[currentId];
+    if (!current) continue;
+    stack.push(...current.childrenIds);
+    delete tree.nodes[currentId];
+  }
+
+  node.childrenIds = [];
+  node.activeChildIndex = 0;
+}
+
 /**
  * Navigate to a different branch by updating the parent's activeChildIndex
  * to point at the target sibling.

package/src/index.ts

@@ -67,6 +67,7 @@ export {
   CkConversationLayout,
   CkCopyMessageActionButton,
   CkFeedbackButton,
+  CkFeedbackDialog,
   CkFileItemsList,
   CkHistory,
   CkHistoryItem,
@@ -86,6 +87,11 @@ export type {
   CkConversationLayoutProps,
   CkConversationProps,
   CkFeedbackButtonProps,
+  CkFeedbackDialogEmits,
+  CkFeedbackDialogProps,
+  CkFeedbackDialogSubmitPayload,
+  CkFeedbackReason,
+  CkFeedbackSentiment,
   CkFeedbackValue,
   CkFileEntry,
   CkFileItemsListEmits,
@@ -107,6 +113,7 @@ export type {
   ConversationTree,
   MessageContent,
   MessageContentStatus,
+  MessageMetadata,
   MessageReasoningContent,
   MessageRole,
   MessageStatus,

package/src/types.ts

@@ -68,6 +68,19 @@ export type MessageContent =
   | MessageToolContent
   | MessageReasoningContent;
 
+/**
+ * Open-ended metadata bag carried alongside a message. chat-kit is
+ * intentionally agnostic about its contents — adapter authors
+ * (`responsesToTree`, …) and message handlers preserve the value verbatim
+ * through the tree → linear path projection, but never inspect it.
+ *
+ * Consumers attach their own well-known keys (attachments, citations,
+ * ratings, …) and define their own typed projections at the read site
+ * rather than extending this base type. That keeps the handler API stable
+ * even as the shape of what gets stored on a message evolves.
+ */
+export type MessageMetadata = Record<string, unknown>;
+
 export interface BaseMessage {
   id: string;
   role: MessageRole;
@@ -76,6 +89,7 @@ export interface BaseMessage {
   status: MessageStatus;
   siblingIds?: string[];
   siblingIndex?: number;
+  metadata?: MessageMetadata;
 }
 
 export interface TreeMessage {
@@ -87,6 +101,7 @@ export interface TreeMessage {
   content: MessageContent[];
   status: MessageStatus;
   createdAt: Date;
+  metadata?: MessageMetadata;
 }
 
 export interface ConversationTree {