@truefoundry/trueforge-assistant-ui-runtime 0.0.0 → 0.2.0-rc.0

package/src/modelMessageContent.ts

@@ -0,0 +1,149 @@
+import type { ThreadAssistantMessagePart } from '@assistant-ui/core';
+import type { PendingResponseRef } from './foldPeerThreads.js';
+import { extractImagePartsFromModelMessage } from './modelMessageImageContent.js';
+import type { ModelMessageEvent } from './server/index.js';
+
+export type AssistantContentPart = ThreadAssistantMessagePart;
+
+export interface ToolCallContext {
+  toolResults?: ReadonlyMap<string, string>;
+  pendingApprovals?: ReadonlyMap<string, { id: string }>;
+  approvalDecisions?: ReadonlyMap<string, { id: string; approved: boolean; reason?: string }>;
+  pendingResponses?: ReadonlyMap<string, PendingResponseRef>;
+}
+
+export type SdkToolCall = NonNullable<ModelMessageEvent['toolCalls']>[number];
+
+type ToolCallPart = Extract<AssistantContentPart, { type: 'tool-call' }>;
+type ToolCallArgValue = ToolCallPart['args'][string];
+
+function isToolCallArgValue(value: unknown): value is ToolCallArgValue {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return true;
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value);
+  }
+  if (Array.isArray(value)) {
+    return value.every(isToolCallArgValue);
+  }
+  if (value != null && typeof value === 'object') {
+    return Object.keys(value).every(key => isToolCallArgValue(Reflect.get(value, key)));
+  }
+  return false;
+}
+
+function parseToolArgs(argsText: string): ToolCallPart['args'] {
+  if (!argsText) {
+    return {};
+  }
+  try {
+    const parsed: unknown = JSON.parse(argsText);
+    if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      const entries: [string, ToolCallArgValue][] = [];
+      for (const key of Object.keys(parsed)) {
+        const value: unknown = Reflect.get(parsed, key);
+        if (isToolCallArgValue(value)) {
+          entries.push([key, value]);
+        }
+      }
+      return Object.fromEntries(entries);
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+function toolCallToPart(toolCall: SdkToolCall, context?: ToolCallContext): ToolCallPart {
+  const argsText = toolCall.function.arguments;
+  const toolResult = context?.toolResults?.get(toolCall.id);
+  const pendingResponse = context?.pendingResponses?.get(toolCall.id);
+  const pendingApproval = context?.pendingApprovals?.get(toolCall.id);
+  const approvalDecision = context?.approvalDecisions?.get(toolCall.id);
+
+  let interrupt: ToolCallPart['interrupt'];
+  if (pendingResponse != null && toolResult === undefined) {
+    interrupt = {
+      type: 'human',
+      payload: {
+        ...(pendingResponse.question != null ? { question: pendingResponse.question } : {}),
+        ...(pendingResponse.options != null ? { options: pendingResponse.options } : {}),
+      },
+    };
+  }
+
+  let approval: ToolCallPart['approval'];
+  if (approvalDecision != null) {
+    approval = {
+      id: approvalDecision.id,
+      approved: approvalDecision.approved,
+      ...(approvalDecision.reason != null ? { reason: approvalDecision.reason } : {}),
+    };
+  } else if (pendingApproval != null) {
+    approval = { id: pendingApproval.id };
+  }
+
+  let result: ToolCallPart['result'];
+  let isError = false;
+  if (toolResult !== undefined) {
+    result = toolResult;
+  } else if (approvalDecision?.approved === false) {
+    result = {
+      error:
+        approvalDecision.reason == null || approvalDecision.reason.length === 0
+          ? 'Tool approval denied'
+          : approvalDecision.reason,
+    };
+    isError = true;
+  }
+
+  return {
+    type: 'tool-call',
+    toolCallId: toolCall.id,
+    toolName: toolCall.function.name,
+    argsText,
+    args: parseToolArgs(argsText),
+    ...(result !== undefined ? { result } : {}),
+    ...(isError ? { isError: true } : {}),
+    ...(approval != null ? { approval } : {}),
+    ...(interrupt != null ? { interrupt } : {}),
+  };
+}
+
+function extractText(message: ModelMessageEvent): string {
+  const { content, refusal } = message;
+  if (content == null) {
+    return refusal ?? '';
+  }
+  if (typeof content === 'string') {
+    return content;
+  }
+  return content
+    .map(part => {
+      if (part.type === 'text') {
+        return part.text;
+      }
+      if (part.type === 'refusal') {
+        return part.refusal;
+      }
+      return '';
+    })
+    .join('');
+}
+
+export function buildAssistantContent(message: ModelMessageEvent, context?: ToolCallContext): AssistantContentPart[] {
+  const parts: AssistantContentPart[] = [];
+  if (message.reasoningContent) {
+    parts.push({ type: 'reasoning', text: message.reasoningContent });
+  }
+  const text = extractText(message);
+  if (text) {
+    parts.push({ type: 'text', text });
+  }
+  parts.push(...extractImagePartsFromModelMessage(message));
+  for (const toolCall of message.toolCalls ?? []) {
+    parts.push(toolCallToPart(toolCall, context));
+  }
+  return parts;
+}

package/src/modelMessageImageContent.ts

@@ -0,0 +1,154 @@
+import type { CompleteAttachment } from '@assistant-ui/core';
+import {
+  isEventDelta,
+  mergeEventDelta,
+  type ModelMessageDeltaEvent,
+  type ModelMessageEvent,
+  type TurnEvent,
+  type TurnStreamingEvent,
+} from './server/index.js';
+
+import type { AssistantContentPart } from './modelMessageContent.js';
+
+export interface ImageUrlContentPart {
+  type: 'image_url';
+  image_url: { url: string };
+}
+
+type ModelMessageContentPart =
+  { type: 'text'; text: string } | { type: 'refusal'; refusal: string } | ImageUrlContentPart;
+
+type ContentBlockDelta = NonNullable<ModelMessageDeltaEvent['contentBlocks']>[number];
+
+function parseDataUriMime(data: string): string {
+  if (!data.startsWith('data:')) {
+    return 'image/png';
+  }
+  const match = /^data:([^;,]+)/.exec(data);
+  return match?.[1] ?? 'image/png';
+}
+
+function imageFilenameFromUrl(url: string, index: number): string {
+  const mimeType = parseDataUriMime(url);
+  const ext = mimeType.split('/')[1] ?? 'png';
+  return `image-${String(index + 1)}.${ext}`;
+}
+
+export function isImageUrlContentPart(part: unknown): part is ImageUrlContentPart {
+  if (!isUnknownRecord(part) || part['type'] !== 'image_url' || !isUnknownRecord(part['image_url'])) {
+    return false;
+  }
+  return typeof part['image_url']['url'] === 'string';
+}
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeModelMessageContent(message: ModelMessageEvent): ModelMessageContentPart[] {
+  const { content } = message;
+  if (content == null) {
+    return [];
+  }
+  if (typeof content === 'string') {
+    return content.length > 0 ? [{ type: 'text', text: content }] : [];
+  }
+  return content;
+}
+
+function mergeContentBlockDeltas(message: ModelMessageEvent, blocks: readonly ContentBlockDelta[]): void {
+  const content = normalizeModelMessageContent(message);
+  message.content = content;
+
+  for (const block of blocks) {
+    const index = block.index;
+    while (content.length <= index) {
+      content.push({ type: 'text', text: '' });
+    }
+
+    const delta = block.delta;
+    if (delta.type === 'text') {
+      const existing = content[index];
+      if (existing?.type === 'text') {
+        existing.text += delta.text ?? '';
+      } else {
+        content[index] = { type: 'text', text: delta.text ?? '' };
+      }
+      continue;
+    }
+
+    const chunk = delta.image_url?.url ?? '';
+    const existing = content[index];
+    if (isImageUrlContentPart(existing)) {
+      existing.image_url.url += chunk;
+    } else {
+      content[index] = { type: 'image_url', image_url: { url: chunk } };
+    }
+  }
+}
+
+export function mergeStreamEventDelta(base: TurnEvent, delta: TurnStreamingEvent): void {
+  if (!isEventDelta(delta)) {
+    return;
+  }
+
+  mergeEventDelta(base, delta);
+
+  if (base.type !== 'model.message') {
+    return;
+  }
+
+  const blocks = delta.contentBlocks ?? delta.content_blocks;
+  if (blocks == null || blocks.length === 0) {
+    return;
+  }
+
+  mergeContentBlockDeltas(base, blocks);
+}
+
+export function imageUrlToAttachment(url: string, attachmentId: string): CompleteAttachment {
+  const mimeType = parseDataUriMime(url);
+  return {
+    id: attachmentId,
+    type: 'image',
+    name: imageFilenameFromUrl(url, 0),
+    contentType: mimeType,
+    status: { type: 'complete' },
+    content: [{ type: 'image', image: url, filename: imageFilenameFromUrl(url, 0) }],
+  };
+}
+
+export function imagePartToAssistantImage(url: string, index: number): AssistantContentPart {
+  return {
+    type: 'image',
+    image: url,
+    filename: imageFilenameFromUrl(url, index),
+  };
+}
+
+export function extractImagePartsFromModelMessage(message: ModelMessageEvent): AssistantContentPart[] {
+  const parts: AssistantContentPart[] = [];
+  let imageIndex = 0;
+
+  for (const part of normalizeModelMessageContent(message)) {
+    if (!isImageUrlContentPart(part)) {
+      continue;
+    }
+    const url = part.image_url.url.trim();
+    if (url.length === 0) {
+      continue;
+    }
+    parts.push(imagePartToAssistantImage(url, imageIndex));
+    imageIndex += 1;
+  }
+
+  return parts;
+}
+
+export function extractImageUrlFromUserContentItem(part: unknown): string | undefined {
+  if (isImageUrlContentPart(part)) {
+    const url = part.image_url.url.trim();
+    return url.length > 0 ? url : undefined;
+  }
+  return undefined;
+}

package/src/requiredActionInputs.ts

@@ -0,0 +1,38 @@
+import type { ThreadMessage } from '@assistant-ui/core';
+import type { TurnInputItem, UserToolApprovalEvent, UserToolResponseEvent } from './server/index.js';
+
+import { ROOT_THREAD_ID } from './constants.js';
+import { collectApprovalInputs, messageHasPendingApprovals } from './toolApproval.js';
+import { collectResponseInputs, messageHasPendingResponses } from './toolResponse.js';
+
+export type RequiredActionInput = Extract<TurnInputItem, UserToolApprovalEvent | UserToolResponseEvent>;
+
+export function messageHasPendingRequiredActions(message: ThreadMessage | undefined): boolean {
+  return messageHasPendingApprovals(message) || messageHasPendingResponses(message);
+}
+
+export function collectRequiredActionInputs(
+  message: ThreadMessage,
+  defaultThreadId: string = ROOT_THREAD_ID,
+): RequiredActionInput[] {
+  if (messageHasPendingRequiredActions(message)) {
+    return [];
+  }
+  return [...collectApprovalInputs(message, defaultThreadId), ...collectResponseInputs(message, defaultThreadId)];
+}
+
+export function isRequiredActionInput(item: TurnInputItem): item is RequiredActionInput {
+  return item.type === 'user.tool_approval' || item.type === 'user.tool_response';
+}
+
+export function findPausedAssistantMessage(
+  messages: readonly ThreadMessage[],
+): Extract<ThreadMessage, { role: 'assistant' }> | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const candidate = messages[i];
+    if (candidate?.role === 'assistant' && candidate.status.type === 'requires-action') {
+      return candidate;
+    }
+  }
+  return undefined;
+}

package/src/sandboxDownload.ts

@@ -0,0 +1,33 @@
+/**
+ * Request shape for {@link AgentChatServer.downloadSandboxFile}.
+ * Turn-scoped hosts resolve the sandbox from `turnId` and may omit `sandboxId`;
+ * hosts that address sandboxes directly still receive `sandboxId` when known.
+ */
+export interface SandboxDownloadRequest {
+  sessionId: string;
+  turnId: string;
+  path: string;
+  sandboxId?: string;
+}
+
+/**
+ * Builds the host download request. Requires a saved session and a turn scope;
+ * does not require `sandboxId` (it may be missing after resume when
+ * `sandbox.created` fell outside the loaded history window).
+ */
+export function buildSandboxDownloadRequest(args: {
+  sessionId: string | undefined;
+  turnId: string;
+  path: string;
+  sandboxId?: string;
+}): SandboxDownloadRequest {
+  if (args.sessionId == null) {
+    throw new Error('This session has not been saved yet, so its files cannot be downloaded.');
+  }
+  return {
+    sessionId: args.sessionId,
+    turnId: args.turnId,
+    path: args.path,
+    ...(args.sandboxId != null ? { sandboxId: args.sandboxId } : {}),
+  };
+}

package/src/server/eventUtils.ts

@@ -0,0 +1,125 @@
+/**
+ * Local implementations of streaming delta helpers.
+ * Formerly imported from trueforge-gateway-sdk/agents.
+ */
+
+import type {
+  DeltaEvents,
+  ModelMessageDeltaEvent,
+  ModelMessageEvent,
+  ToolCall,
+  ToolInfo,
+  TurnEvent,
+  TurnStreamingEvent,
+} from './events.js';
+
+/** True for `.delta` streaming events. */
+export function isEventDelta(event: TurnStreamingEvent): event is DeltaEvents {
+  return typeof event.type === 'string' && event.type.endsWith('.delta');
+}
+
+/**
+ * Merge `delta` into `base` in place (same `id` required).
+ * Currently handles `model.message.delta` → `model.message`.
+ */
+export function mergeEventDelta(base: TurnEvent, delta: DeltaEvents): void {
+  if (base.id !== delta.id) {
+    throw new Error(`Cannot merge delta into a different event: base id "${base.id}" != delta id "${delta.id}".`);
+  }
+  if (base.type === 'model.message') {
+    mergeModelMessageDelta(base, delta);
+  }
+}
+
+function asToolInfo(value: unknown): ToolInfo | undefined {
+  if (value == null || typeof value !== 'object') {
+    return undefined;
+  }
+  const type: unknown = Reflect.get(value, 'type');
+  if (typeof type !== 'string') {
+    return undefined;
+  }
+  const name: unknown = Reflect.get(value, 'name');
+  if (type === 'trueforge-system') {
+    return typeof name === 'string' ? { type, name } : undefined;
+  }
+  if (type === 'mcp') {
+    const serverId: unknown = Reflect.get(value, 'serverId');
+    const serverName: unknown = Reflect.get(value, 'serverName');
+    return typeof serverId === 'string' && typeof serverName === 'string' && typeof name === 'string'
+      ? { type, serverId, serverName, name }
+      : undefined;
+  }
+  return typeof name === 'string' ? { type, name } : { type };
+}
+
+function mergeModelMessageDelta(base: ModelMessageEvent, delta: ModelMessageDeltaEvent): void {
+  if (delta.content) {
+    if (base.content === undefined || base.content === null || typeof base.content === 'string') {
+      base.content = (base.content ?? '') + delta.content;
+    } else {
+      const last = base.content[base.content.length - 1];
+      if (last?.type === 'text') {
+        last.text += delta.content;
+      } else {
+        base.content.push({ type: 'text', text: delta.content });
+      }
+    }
+  }
+
+  if (delta.refusal) {
+    base.refusal = (base.refusal ?? '') + delta.refusal;
+  }
+
+  if (delta.toolCalls) {
+    base.toolCalls ??= [];
+    for (const d of delta.toolCalls) {
+      let tc: ToolCall | undefined = base.toolCalls[d.index];
+      if (tc === undefined) {
+        const toolInfo = asToolInfo(d.toolInfo);
+        tc = {
+          id: d.id ?? '',
+          type: d.type ?? 'function',
+          function: {
+            name: d.function?.name ?? '',
+            arguments: '',
+          },
+          ...(toolInfo != null ? { toolInfo } : {}),
+        };
+        base.toolCalls[d.index] = tc;
+      }
+      if (d.id) {
+        tc.id = d.id;
+      }
+      if (d.type) {
+        tc.type = d.type;
+      }
+      if (d.function?.name) {
+        tc.function.name = d.function.name;
+      }
+      if (d.function?.arguments) {
+        tc.function.arguments += d.function.arguments;
+      }
+      const toolInfo = asToolInfo(d.toolInfo);
+      if (toolInfo != null) {
+        tc.toolInfo = toolInfo;
+      }
+      if (d.providerSpecificFields) {
+        tc.providerSpecificFields = {
+          ...(tc.providerSpecificFields ?? {}),
+          ...d.providerSpecificFields,
+        };
+      }
+    }
+  }
+
+  if (delta.finishReason) {
+    base.finishReason = delta.finishReason;
+  }
+  if (delta.reasoningContent) {
+    base.reasoningContent = (base.reasoningContent ?? '') + delta.reasoningContent;
+  }
+  if (delta.usage) {
+    base.usage = delta.usage;
+  }
+}