alexion
4def357d09
Imported as a linear vendor commit so forge rebases do not replay the upstream root tree. git-subtree-dir: third_party/pi git-subtree-split: d981de1229ef899957bbe968bc8dcda02a21f477
99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# JSON Event Stream Mode
|
|
|
|
```bash
|
|
pi --mode json "Your prompt"
|
|
```
|
|
|
|
Outputs all session events as JSON lines to stdout. Useful for integrating pi into other tools or custom UIs.
|
|
|
|
## Event Types
|
|
|
|
Wire events use `JsonAgentSessionEvent`. It matches
|
|
[`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts)
|
|
except that streaming message updates omit cumulative snapshots:
|
|
|
|
```typescript
|
|
type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
|
|
|
|
type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
|
|
? WithoutPartial<T> & { id: string; toolName: string }
|
|
: WithoutPartial<T>;
|
|
|
|
type JsonAgentSessionEvent =
|
|
| Exclude<AgentSessionEvent, { type: "message_update" }>
|
|
| {
|
|
type: "message_update";
|
|
usage: Usage;
|
|
assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
|
|
};
|
|
```
|
|
|
|
`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
|
|
|
|
Other base events come from
|
|
[`AgentEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts):
|
|
|
|
```typescript
|
|
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 };
|
|
```
|
|
|
|
## Message Types
|
|
|
|
Base messages from [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts#L134):
|
|
- `UserMessage` (line 134)
|
|
- `AssistantMessage` (line 140)
|
|
- `ToolResultMessage` (line 152)
|
|
|
|
Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts#L29):
|
|
- `BashExecutionMessage` (line 29)
|
|
- `CustomMessage` (line 46)
|
|
- `BranchSummaryMessage` (line 55)
|
|
- `CompactionSummaryMessage` (line 62)
|
|
|
|
## Output Format
|
|
|
|
Each line is a JSON object. The first line is the session header:
|
|
|
|
```json
|
|
{"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
|
|
```
|
|
|
|
Followed by events as they occur:
|
|
|
|
```json
|
|
{"type":"agent_start"}
|
|
{"type":"turn_start"}
|
|
{"type":"message_start","message":{"role":"assistant","content":[],...}}
|
|
{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
|
|
{"type":"message_end","message":{...}}
|
|
{"type":"turn_end","message":{...},"toolResults":[]}
|
|
{"type":"agent_end","messages":[...]}
|
|
```
|
|
|
|
`message_update` records are delta-only. They omit both the cumulative `message` field and
|
|
`assistantMessageEvent.partial` to keep stream size linear. The top-level `usage` field contains
|
|
the latest cumulative provider-reported usage and may remain zero when a provider only reports
|
|
usage at completion. Use `contentIndex` and `delta` to assemble live text, thinking, or tool-call
|
|
arguments if needed. A `toolcall_start` event also includes the constant-sized `id` and `toolName`
|
|
fields. `message_end` contains the final authoritative message.
|
|
|
|
## Example
|
|
|
|
```bash
|
|
pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
|
|
```
|