@aleph-alpha/chat-kit 1.3.1 → 1.5.0

package/src/adapters/responses-api.ts

@@ -0,0 +1,444 @@
+/**
+ * Adapter: OpenAI-style **Responses API** → chat-kit `ConversationTree`.
+ *
+ * chat-kit's domain model (`TreeMessage`, `MessageContent`) is intentionally
+ * format-agnostic. This module is the bridge that turns a stored Responses-
+ * API timeline (`GET /conversations/{id}/responses`) into a `ConversationTree`
+ * the message handler can render. Apps that use a different transcript shape
+ * — or none at all — can build their own adapter or feed the handler via
+ * `setTree(tree)` directly.
+ *
+ * The wire-level types that describe the Responses-API payload (`StoredResponse`,
+ * `ResponseOutput*`, `ResponseAttachment`, `ResponseList`, …) live alongside the
+ * conversion function so the entire Responses-API surface is encapsulated here.
+ *
+ * Public surface:
+ *  - `responsesToTree(responses)` — pure function, the entry point.
+ *  - All Responses-API wire types (re-exported via the adapter subpath).
+ *
+ * Available via `@aleph-alpha/chat-kit/adapters/responses-api` and
+ * `@aleph-alpha/chat-kit/adapters`.
+ */
+import { generateId } from '../helpers';
+import type {
+  ConversationTree,
+  MessageContent,
+  MessageRole,
+  TreeMessage,
+} from '../types';
+
+// ---------------------------------------------------------------------------
+// Wire-level Responses-API types
+// ---------------------------------------------------------------------------
+
+/**
+ * Annotation attached to a Responses-API content part (citations, file
+ * references, etc.). chat-kit does not render annotations itself; the shape
+ * is kept open so consumers can downcast to a more specific schema.
+ */
+export interface ResponseAnnotation {
+  type: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Plain text fragment inside a `ResponseOutputMessage`. Streamed by the
+ * Responses API as `output_text` (or the historical `text` alias).
+ */
+export interface ResponseOutputTextPart {
+  type: 'output_text' | 'text';
+  text: string;
+  annotations?: ResponseAnnotation[];
+}
+
+/**
+ * One reasoning fragment inside a `ResponseOutputReasoning`. The Responses
+ * API streams chain-of-thought under `reasoning_text`; the body is exposed
+ * for consumers that want to render it (chat-kit itself only surfaces a
+ * "thinking" indicator).
+ */
+export interface ResponseReasoningTextPart {
+  type: 'reasoning_text';
+  text: string;
+  annotations?: ResponseAnnotation[];
+}
+
+/**
+ * Forward-compatible catch-all for content parts whose `type` chat-kit does
+ * not yet model (e.g. refusals, future part kinds). Consumers narrow on
+ * `type` themselves when they need richer handling.
+ */
+export interface ResponseUnknownContentPart {
+  type: string;
+  text?: string;
+  annotations?: ResponseAnnotation[];
+  [key: string]: unknown;
+}
+
+/**
+ * Discriminated union of content parts that can appear inside a Responses-
+ * API output item. `ResponseOutputTextPart` and `ResponseReasoningTextPart`
+ * cover the rendered shapes; the catch-all keeps the union open.
+ */
+export type OutputContentPart =
+  | ResponseOutputTextPart
+  | ResponseReasoningTextPart
+  | ResponseUnknownContentPart;
+
+/**
+ * Visible message produced by a Responses-API turn (assistant reply or
+ * echoed user input). Carries the renderable text content; `responsesToTree`
+ * extracts text from `content` to build the chat tree.
+ */
+export interface ResponseOutputMessage {
+  type: 'message';
+  id: string;
+  status: string;
+  role: 'assistant' | 'user';
+  content: string | OutputContentPart[];
+}
+
+/**
+ * Chain-of-thought trail produced by the assistant during a turn. Surfaced
+ * in chat-kit only as a "thinking" indicator; consumers may render the
+ * underlying `reasoning_text` parts directly when desired.
+ */
+export interface ResponseOutputReasoning {
+  type: 'reasoning';
+  id: string;
+  status: string;
+  role?: 'assistant' | null;
+  content: OutputContentPart[];
+}
+
+/**
+ * Single tool entry returned inside `mcp_list_tools` (and similar tool-
+ * discovery outputs). Schema fields are passed through verbatim because
+ * chat-kit does not model JSON Schema itself.
+ */
+export interface ResponseToolDescriptor {
+  name: string;
+  description?: string;
+  annotations?: Record<string, unknown>;
+  input_schema?: unknown;
+}
+
+/**
+ * Wire-level Responses-API output kinds that represent tool activity rather
+ * than visible content. The list enumerates the values chat-kit recognises
+ * today; extend it as new tool kinds are introduced upstream.
+ */
+export type ResponseOutputToolType =
+  | 'mcp_list_tools'
+  | 'mcp_call'
+  | 'tool_call'
+  | 'function_call'
+  | 'web_search_call'
+  | 'file_search_call'
+  | 'code_interpreter_call'
+  | 'image_generation_call'
+  | 'local_shell_call';
+
+/**
+ * Tool-related output produced during a Responses-API turn. Covers tool
+ * discovery (`mcp_list_tools`), invocation (`mcp_call`, `function_call`,
+ * etc.) and the various built-in tool kinds. Common fields are typed; the
+ * rest is passed through so consumers can read kind-specific data without
+ * redefining the shape.
+ */
+export interface ResponseOutputTool {
+  type: ResponseOutputToolType;
+  id: string;
+  status?: string;
+  /** `mcp_list_tools` / `mcp_call`: server identifier. */
+  server_label?: string;
+  /** `mcp_list_tools`: catalog of tools exposed by the server. */
+  tools?: ResponseToolDescriptor[];
+  /** `function_call` / `mcp_call`: invoked tool name. */
+  name?: string;
+  /** `function_call` / `mcp_call`: serialized JSON arguments. */
+  arguments?: string;
+  /** `function_call` / `tool_call`: correlation id for a paired result. */
+  call_id?: string;
+  /** Tool result payload (shape depends on the tool kind). */
+  output?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * One output item produced by a Responses-API response, discriminated by
+ * `type`. Modelled in the same spirit as `MessageContent`: visible
+ * `'message'`, optional `'reasoning'` trail, and `tool` activity.
+ */
+export type ResponseOutput =
+  | ResponseOutputMessage
+  | ResponseOutputReasoning
+  | ResponseOutputTool;
+
+/**
+ * Attachment metadata stored under `metadata.attachments` on a Responses-API
+ * response. chat-kit does not render attachments itself; this type exists so
+ * consumers can read them off `StoredResponse.metadata` without redeclaring
+ * the shape.
+ */
+export interface ResponseAttachment {
+  fileId: string;
+  fileName: string;
+  searchStoreId: string;
+}
+
+/**
+ * One stored response from the OpenAI-style Responses API, as returned by
+ * `GET /conversations/:id/responses`. `previous_response_id` chains
+ * responses into a tree; `responsesToTree` walks that chain to produce a
+ * `ConversationTree`.
+ */
+export interface StoredResponse {
+  id: string;
+  object: 'response';
+  created_at: number;
+  completed_at: number;
+  status: string;
+  model: string;
+  previous_response_id?: string | null;
+  output: ResponseOutput[];
+  request_input: Record<string, unknown>[];
+  metadata?: Record<string, unknown> & {
+    attachments?: ResponseAttachment[];
+  };
+  conversation?: { id: string };
+  ancestor_ids?: string[];
+  depth?: number;
+}
+
+/**
+ * Raw envelope returned by the Responses list endpoint. The endpoint is not
+ * paginated, so chat-kit unwraps `data` and exposes `StoredResponse[]` to
+ * callers; this type is kept exported for users implementing or mocking the
+ * `HttpClient`.
+ */
+export interface ResponseList {
+  object: 'list';
+  data: StoredResponse[];
+}
+
+// ---------------------------------------------------------------------------
+// Conversion: StoredResponse[] → ConversationTree
+// ---------------------------------------------------------------------------
+
+interface ResponseMessageNode {
+  id: string;
+  role: MessageRole;
+  content: MessageContent[];
+  createdAt: Date;
+}
+
+function extractMessageText(content: ResponseOutputMessage['content']): string {
+  if (typeof content === 'string') return content.trim();
+  return extractTextFromParts(content);
+}
+
+function extractTextFromParts(parts: OutputContentPart[]): string {
+  let text = '';
+  for (const part of parts) {
+    if (part.type === 'output_text' || part.type === 'text') {
+      text += part.text ?? '';
+    }
+  }
+  return text.trim();
+}
+
+function extractReasoningText(parts: OutputContentPart[]): string {
+  let text = '';
+  for (const part of parts) {
+    if (part.type === 'reasoning_text') {
+      text += part.text ?? '';
+    }
+  }
+  return text.trim();
+}
+
+function textPart(text: string, id?: string): MessageContent {
+  return { type: 'text', id: id ?? generateId(), text, status: 'completed' };
+}
+
+// Build the `content` array for one assistant turn from a Responses-API
+// record. Reasoning trails, tool invocations, and visible text all belong to
+// the same turn and are kept in their original wire order so the UI can
+// render them inline with the streaming flow.
+function toAssistantParts(resp: StoredResponse): MessageContent[] {
+  const parts: MessageContent[] = [];
+  for (const out of resp.output ?? []) {
+    switch (out.type) {
+      case 'reasoning': {
+        const text = extractReasoningText(out.content);
+        parts.push({
+          type: 'reasoning',
+          id: out.id,
+          ...(text ? { text } : {}),
+          status: 'completed',
+        });
+        break;
+      }
+      case 'message': {
+        if (out.role !== 'assistant') break;
+        const text = extractMessageText(out.content);
+        if (!text) break;
+        parts.push(textPart(text, out.id || undefined));
+        break;
+      }
+      // Actual tool invocations surface as tool parts. `mcp_list_tools` is
+      // informational discovery (the server advertising tools) rather than
+      // a call the assistant made, so it is intentionally skipped.
+      case 'mcp_call':
+      case 'function_call':
+      case 'tool_call': {
+        parts.push({
+          type: 'tool',
+          id: out.id,
+          name: out.name ?? out.type,
+        });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return parts;
+}
+
+// The id used for the assistant `TreeMessage` of a response. Prefer the id
+// of the first visible message output (matches the wire id seen during
+// streaming); fall back to a deterministic `assistant-${resp.id}` so
+// reasoning- or tool-only turns still get a stable node id.
+function getAssistantNodeId(resp: StoredResponse): string {
+  for (const out of resp.output ?? []) {
+    if (out.type === 'message' && out.role === 'assistant' && out.id) {
+      return out.id;
+    }
+  }
+  return `assistant-${resp.id}`;
+}
+
+// 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
+// is encoded by `previous_response_id` so several responses can share the
+// same parent and form sibling subtrees.
+function extractInputText(rawContent: unknown): string {
+  if (typeof rawContent === 'string') return rawContent.trim();
+  if (Array.isArray(rawContent)) {
+    return extractTextFromParts(rawContent as OutputContentPart[]);
+  }
+  return '';
+}
+
+function responseToMessageNodes(resp: StoredResponse): ResponseMessageNode[] {
+  const nodes: ResponseMessageNode[] = [];
+  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 assistantParts = toAssistantParts(resp);
+  if (assistantParts.length > 0) {
+    nodes.push({
+      id: getAssistantNodeId(resp),
+      role: 'assistant',
+      content: assistantParts,
+      createdAt: new Date((resp.completed_at ?? resp.created_at) * 1000),
+    });
+  }
+  return nodes;
+}
+
+/**
+ * Convert an OpenAI Responses API list (already ordered by `created_at`
+ * ascending) into a chat-kit `ConversationTree`.
+ *
+ * The caller guarantees ordering, which lets us build the tree in a single
+ * pass: each response's `previous_response_id` always points to a response
+ * we have already processed, so we can wire its messages onto the parent's
+ * 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.
+ */
+export function responsesToTree(responses: StoredResponse[]): ConversationTree {
+  if (responses.length === 0) {
+    return { nodes: {}, rootId: null };
+  }
+
+  const treeNodes: Record<string, TreeMessage> = {};
+  // 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
+  // chain stays connected.
+  const tailMessageByResponse = new Map<string, string | null>();
+  let rootMessageId: string | null = null;
+
+  function appendNode(node: ResponseMessageNode, parentId: string | null) {
+    treeNodes[node.id] = {
+      id: node.id,
+      parentId,
+      childrenIds: [],
+      activeChildIndex: 0,
+      role: node.role,
+      content: node.content,
+      status: 'completed',
+      createdAt: node.createdAt,
+    };
+    if (parentId !== null) {
+      const parent = treeNodes[parentId];
+      if (parent) {
+        parent.childrenIds.push(node.id);
+        // Latest insertion wins as the active branch — within a single
+        // response there's only one push, so this is a no-op there; for
+        // sibling branches it surfaces the most recent one by default.
+        parent.activeChildIndex = parent.childrenIds.length - 1;
+      }
+    }
+  }
+
+  for (const resp of responses) {
+    const parentResponseId =
+      resp.previous_response_id &&
+      tailMessageByResponse.has(resp.previous_response_id)
+        ? resp.previous_response_id
+        : null;
+    let chainParent =
+      parentResponseId !== null
+        ? (tailMessageByResponse.get(parentResponseId) ?? null)
+        : null;
+
+    const messageNodes = responseToMessageNodes(resp);
+    let firstId: string | null = null;
+    for (const node of messageNodes) {
+      appendNode(node, chainParent);
+      if (firstId === null) firstId = node.id;
+      chainParent = node.id;
+    }
+
+    if (rootMessageId === null && firstId !== null) {
+      rootMessageId = firstId;
+    }
+
+    // Track the attachment point for descendants. If the response had no
+    // visible messages, pass through the parent's tail so children of this
+    // response still land in the right place.
+    tailMessageByResponse.set(resp.id, chainParent);
+  }
+
+  return { nodes: treeNodes, rootId: rootMessageId };
+}