Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

10.4 KB
Raw Blame
import type {
  MessageStatus,
  ThreadAssistantMessage,
  ThreadAssistantMessagePart,
  ThreadMessage,
} from '@assistant-ui/core';
import type { ToolResponseRequiredEvent, Turn, TurnInputItem, UserToolResponseEvent } from './server/index.js';

import { ROOT_THREAD_ID } from './constants.js';
import { recordToolApprovalInFold, recordToolResponseInFold, type PeerThreadFoldState } from './foldPeerThreads.js';
import type { ToolResponseMessageCustomMetadata } from './messageCustomMetadata.js';
import type { TurnStreamUpdate } from './turnStreamUpdate.js';

export { ROOT_THREAD_ID } from './constants.js';

export const TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY = 'toolResponseThreadId';

export interface AskUserQuestionInterruptPayload {
  question?: string;
  options?: string[];
}

export type StoredToolResponse = Pick<UserToolResponseEvent, 'content'>;

export type RespondToToolResponseOptions = Pick<UserToolResponseEvent, 'toolCallId' | 'content'>;

type ToolCallPart = Extract<ThreadMessage['content'][number], { type: 'tool-call' }>;

type AssistantToolCallPart = Extract<ThreadAssistantMessagePart, { type: 'tool-call' }>;

export function hasPendingToolResponse(part: Pick<ToolCallPart, 'interrupt' | 'result'>): boolean {
  return part.interrupt != null && part.result === undefined;
}

function isStagedResponseAwaitingSdk(part: ToolCallPart): boolean {
  return part.interrupt != null && part.result !== undefined;
}

export function toolResponseStatus(): MessageStatus {
  return { type: 'requires-action', reason: 'tool-calls' };
}

export function toolResponseMessageCustom(threadId: string): ToolResponseMessageCustomMetadata {
  return {
    [TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]: threadId === ROOT_THREAD_ID ? ROOT_THREAD_ID : threadId,
  };
}

export function getToolResponseThreadId(message: ThreadMessage | undefined): string | undefined {
  if (message?.role !== 'assistant') {
    return undefined;
  }
  const threadId = message.metadata.custom[TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY];
  return typeof threadId === 'string' ? threadId : undefined;
}

export function findResponseRequiredInTurn(turn: Pick<Turn, 'state'>): ToolResponseRequiredEvent | undefined {
  if (turn.state.status !== 'done') {
    return undefined;
  }
  const found = turn.state.requiredActions?.find(action => action.type === 'tool.response_required');
  return found?.type === 'tool.response_required' ? found : undefined;
}

function applyToolResponseToToolCall(part: AssistantToolCallPart, content: string): AssistantToolCallPart {
  return { ...part, result: content };
}

function updateToolResponseInContent(
  content: readonly ThreadAssistantMessagePart[],
  options: RespondToToolResponseOptions,
): { content: readonly ThreadAssistantMessagePart[]; found: boolean } {
  let found = false;
  const newContent = content.map(part => {
    if (part.type !== 'tool-call') {
      return part;
    }

    if (part.toolCallId === options.toolCallId && hasPendingToolResponse(part)) {
      found = true;
      return applyToolResponseToToolCall(part, options.content);
    }

    if (part.messages == null) {
      return part;
    }

    const messages = part.messages.map(message => {
      if (message.role !== 'assistant') {
        return message;
      }
      const nested = updateToolResponseInContent(message.content, options);
      if (!nested.found) {
        return message;
      }
      found = true;
      return { ...message, content: nested.content };
    });
    return { ...part, messages };
  });

  return { content: newContent, found };
}

export function applyToolResponseToMessage(
  message: ThreadAssistantMessage,
  options: RespondToToolResponseOptions,
): ThreadAssistantMessage {
  const { content } = updateToolResponseInContent(message.content, options);
  return { ...message, content: [...content] };
}

function nestedMessagesHavePendingResponses(messages: readonly ThreadMessage[]): boolean {
  for (const message of messages) {
    if (messageHasPendingResponses(message)) {
      return true;
    }
  }
  return false;
}

export function messageHasPendingResponses(message: ThreadMessage | undefined): boolean {
  if (message?.role !== 'assistant') {
    return false;
  }
  for (const part of message.content) {
    if (part.type !== 'tool-call') {
      continue;
    }
    if (hasPendingToolResponse(part)) {
      return true;
    }
    if (part.messages != null && nestedMessagesHavePendingResponses(part.messages)) {
      return true;
    }
  }
  return false;
}

function collectResponseInputsFromMessages(
  messages: readonly ThreadMessage[],
  defaultThreadId: string,
): UserToolResponseEvent[] {
  const events: UserToolResponseEvent[] = [];
  for (const message of messages) {
    events.push(...collectResponseInputs(message, defaultThreadId));
  }
  return events;
}

export function collectResponseInputs(message: ThreadMessage, threadId: string): UserToolResponseEvent[] {
  if (message.role !== 'assistant' || !threadId) {
    return [];
  }
  if (messageHasPendingResponses(message)) {
    return [];
  }

  const scopedThreadId = getToolResponseThreadId(message) ?? threadId;
  const events: UserToolResponseEvent[] = [];

  for (const part of message.content) {
    if (part.type !== 'tool-call') {
      continue;
    }
    if (isStagedResponseAwaitingSdk(part)) {
      events.push({
        type: 'user.tool_response',
        threadId: scopedThreadId,
        toolCallId: part.toolCallId,
        content: String(part.result),
      });
    }
    if (part.messages != null) {
      events.push(...collectResponseInputsFromMessages(part.messages, scopedThreadId));
    }
  }
  return events;
}

function contentHasPendingResponses(content: readonly ThreadAssistantMessagePart[]): boolean {
  return messageHasPendingResponses({
    id: 'pending-check',
    role: 'assistant',
    content,
    status: { type: 'complete', reason: 'stop' },
    createdAt: new Date(),
    metadata: {
      unstable_state: null,
      unstable_annotations: [],
      unstable_data: [],
      steps: [],
      custom: {},
    },
  });
}

export function resolveToolResponseUpdate(update: TurnStreamUpdate): TurnStreamUpdate {
  if (
    contentHasPendingResponses(update.content) ||
    update.status?.type !== 'requires-action' ||
    update.status.reason !== 'tool-calls'
  ) {
    return update;
  }

  return { content: update.content };
}

function walkAssistantToolCallParts(
  content: readonly ThreadAssistantMessagePart[],
  visit: (part: AssistantToolCallPart) => void,
): void {
  for (const part of content) {
    if (part.type !== 'tool-call') {
      continue;
    }
    visit(part);
    if (part.messages == null) {
      continue;
    }
    for (const message of part.messages) {
      if (message.role === 'assistant') {
        walkAssistantToolCallParts(message.content, visit);
      }
    }
  }
}

function collectStagedResponsesFromContent(content: readonly ThreadAssistantMessagePart[]): Map<string, string> {
  const staged = new Map<string, string>();
  walkAssistantToolCallParts(content, part => {
    if (isStagedResponseAwaitingSdk(part)) {
      staged.set(part.toolCallId, String(part.result));
    }
  });
  return staged;
}

function applyStagedResponsesToContentMap(
  content: readonly ThreadAssistantMessagePart[],
  staged: ReadonlyMap<string, string>,
): ThreadAssistantMessagePart[] {
  return content.map(part => {
    if (part.type !== 'tool-call') {
      return part;
    }

    const contentValue = staged.get(part.toolCallId);
    let nextPart: AssistantToolCallPart = part;
    if (contentValue != null && hasPendingToolResponse(part)) {
      nextPart = applyToolResponseToToolCall(part, contentValue);
    }

    if (nextPart.messages == null) {
      return nextPart;
    }

    return {
      ...nextPart,
      messages: nextPart.messages.map(message => {
        if (message.role !== 'assistant') {
          return message;
        }
        return {
          ...message,
          content: applyStagedResponsesToContentMap(message.content, staged),
        };
      }),
    };
  });
}

export function mergeStagedResponsesIntoContent(
  incoming: readonly ThreadAssistantMessagePart[],
  existing: readonly ThreadAssistantMessagePart[],
): ThreadAssistantMessagePart[] {
  const staged = collectStagedResponsesFromContent(existing);
  if (staged.size === 0) {
    return [...incoming];
  }
  return applyStagedResponsesToContentMap(incoming, staged);
}

export function extractToolResponsesFromTurnInput(input: Turn['input'] | undefined): UserToolResponseEvent[] {
  const events: UserToolResponseEvent[] = [];
  for (const item of input ?? []) {
    if (item.type === 'user.tool_response') {
      events.push(item);
    }
  }
  return events;
}

export function applyUserToolResponsesToFold(fold: PeerThreadFoldState, inputs: readonly TurnInputItem[]): void {
  for (const item of inputs) {
    if (item.type === 'user.tool_response') {
      recordToolResponseInFold(fold, {
        toolCallId: item.toolCallId,
        content: item.content,
      });
    } else if (item.type === 'user.tool_approval') {
      recordToolApprovalInFold(fold, {
        toolCallId: item.toolCallId,
        approved: item.approval.status === 'allow',
        ...(item.approval.status === 'deny' && item.approval.reason != null ? { reason: item.approval.reason } : {}),
      });
    }
  }
}

export function collectSubsequentToolResponses(
  turns: readonly Pick<Turn, 'input'>[],
  fromIndex: number,
): Map<string, StoredToolResponse> {
  const responses = new Map<string, StoredToolResponse>();

  for (let index = fromIndex + 1; index < turns.length; index++) {
    const input = turns[index]?.input ?? [];
    if (input.some(item => item.type === 'user.message')) {
      break;
    }

    for (const event of extractToolResponsesFromTurnInput(input)) {
      responses.set(event.toolCallId, { content: event.content });
    }
  }

  return responses;
}

export function collectToolResponsesFromTurnInput(input: Turn['input'] | undefined): Map<string, StoredToolResponse> {
  const responses = new Map<string, StoredToolResponse>();
  for (const event of extractToolResponsesFromTurnInput(input)) {
    responses.set(event.toolCallId, { content: event.content });
  }
  return responses;
}

export function applyStagedResponsesToContent(
  content: readonly ThreadAssistantMessagePart[],
  responses: ReadonlyMap<string, StoredToolResponse>,
): ThreadAssistantMessagePart[] {
  const staged = new Map([...responses.entries()].map(([toolCallId, value]) => [toolCallId, value.content]));
  return applyStagedResponsesToContentMap(content, staged);
}