JSON 事件流模式

pi --mode json "Your prompt"

將所有會話事件輸出為JSON行到stdout。對於將 pi 整合到其他工具或自訂 UI 中非常有用。

連線事件使用JsonAgentSessionEvent。它匹配 AgentSessionEvent 除了串流訊息更新忽略累積快照之外：

type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;

type JsonAgentSessionEvent =
  | Exclude<AgentSessionEvent, { type: "message_update" }>
  | {
      type: "message_update";
      assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
    };

每當發生變化時，queue_update都會發出完整的待處理轉向和後續隊列。 compaction_start和compaction_end涵蓋手動和自動壓實。

其他基礎事件來自 AgentEvent:

type AgentEvent =
  // Agent lifecycle
  | { type: "agent_start" }
  | { type: "agent_end"; messages: AgentMessage[] }
  // Turn lifecycle
  | { type: "turn_start" }
  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
  // Message lifecycle
  | { type: "message_start"; message: AgentMessage }
  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
  | { type: "message_end"; message: AgentMessage }
  // Tool execution
  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };

來自packages/ai/src/types.ts的基本訊息：

• UserMessage（第134行）
• AssistantMessage（第140行）
• ToolResultMessage（第152行）

來自packages/coding-agent/src/core/messages.ts的擴充訊息：

• BashExecutionMessage（第29行）
• CustomMessage（第 46 行）
• BranchSummaryMessage（第 55 行）
• CompactionSummaryMessage（第 62 行）

每行都是一個 JSON 物件。第一行是會話頭：

{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}

接下來是事件發生時的情況：

{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{"role":"assistant","content":[],...}}
{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}

message_update 記錄僅包含增量。他們省略了累積 message 字段和 assistantMessageEvent.partial 保持流大小線性。使用contentIndex和delta 如果需要的話，可以組合即時文字、思考或工具來呼叫參數。 message_end 包含 最終的權威消息。

pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'