Skip to main content

Turn Item Types

Types representing items within a turn result.

AnyTurnItem​

Union of all item types:

type AnyTurnItem = MessageItem | ToolCallItem | ToolResultItem;

MessageItem​

Represents a message in the conversation:

interface MessageItem {
  type: 'message';
  role: 'user' | 'assistant';
  id: string;
  text: string;
  timestamp: number;
}

ToolCallItem​

Represents a tool invocation:

interface ToolCallItem {
  type: 'tool_call';
  id: string;
  messageId: string;
  toolId: string;
  toolName: string;
  parameters: Record<string, unknown>;
  timestamp: number;
}

ToolResultItem​

Represents a tool execution result:

interface ToolResultItem {
  type: 'tool_result';
  id: string;
  messageId: string;
  toolId: string;
  toolName: string;
  isError: boolean;
  value: string;
  timestamp: number;
}

TurnResultData​

Serializable turn result data:

interface TurnResultData {
  sessionId: string;
  finalResponse: string;
  items: AnyTurnItem[];
  durationMs: number;
  numTurns: number;
  isError: boolean;
}

JsonResult​

Response from JSON-mode execution:

interface JsonResult {
  session_id: string;
  is_error: boolean;
  duration_ms: number;
  num_turns: number;
  result: string;
}

Usage Examples​

Accessing Items​

const result = await thread.run('Create a file');

// All items in order
for (const item of result.items) {
  console.log(item.type, item.timestamp);
}

// Filter by type
const messages = result.messages;
const toolCalls = result.toolCalls;
const toolResults = result.toolResults;

Correlating Tool Calls and Results​

for (const call of result.toolCalls) {
  const callResult = result.toolResults.find(
    r => r.toolId === call.toolId
  );

  console.log(`${call.toolName}:`, callResult?.isError ? 'FAILED' : 'OK');
}

Serializing Results​

const result = await thread.run('Build feature');

// Convert to plain object
const data = result.toJSON();

// Save to file
fs.writeFileSync('result.json', JSON.stringify(data, null, 2));

// Structure matches TurnResultData
console.log(data.sessionId);
console.log(data.items.length);

Type Narrowing​

for (const item of result.items) {
  switch (item.type) {
    case 'message':
      // item is MessageItem
      console.log(`[${item.role}] ${item.text}`);
      break;

    case 'tool_call':
      // item is ToolCallItem
      console.log(`Call: ${item.toolName}`);
      break;

    case 'tool_result':
      // item is ToolResultItem
      console.log(`Result: ${item.isError ? 'Error' : 'Success'}`);
      break;
  }
}