upstream/K-Dense-AI-scientific-agent-skills/catalogue/skills/pi-agent/references/json.md

@@ -2,9 +2,9 @@
 title: "JSON Event Stream Mode"
 task: ""
 lineage_type: import
-upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/9c9bd2e9/skills/pi-agent/references/json.md
-upstream_sha: 9c9bd2e9
-imported_at: 2026-06-27
+upstream_source: https://github.com/K-Dense-AI/scientific-agent-skills/blob/b2a92ba0/skills/pi-agent/references/json.md
+upstream_sha: b2a92ba0
+imported_at: 2026-08-14
 prompt_class: unknown
 upstream_changes: accepted
 author: upstream
@@ -23,17 +23,33 @@ pi --mode json "Your prompt"
 
 ## Event Types
 
-`AgentSessionEvent` includes base agent events plus queue, compaction, and retry events:
+Wire events use `JsonAgentSessionEvent`, which matches `AgentSessionEvent` except that streaming message updates omit cumulative snapshots:
 
-- `agent_start`, `agent_end`
-- `turn_start`, `turn_end`
-- `message_start`, `message_update`, `message_end`
-- `tool_execution_start`, `tool_execution_update`, `tool_execution_end`
-- `queue_update`
-- `compaction_start`, `compaction_end`
-- `auto_retry_start`, `auto_retry_end`
+```typescript
+type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
 
-`queue_update` emits full pending steering and follow-up queues. Compaction events cover manual and automatic compaction.
+type JsonAgentSessionEvent =
+  | Exclude<AgentSessionEvent, { type: "message_update" }>
+  | { type: "message_update"; usage: Usage; assistantMessageEvent: WithoutPartial<AssistantMessageEvent> };
+```
+
+`AgentSessionEvent` is `AgentEvent` plus session-level events:
+
+- `queue_update` — `{ steering: readonly string[], followUp: readonly string[] }`, emitted whenever either queue changes
+- `compaction_start` — `{ reason: "manual" | "threshold" | "overflow" }`
+- `compaction_end` — `{ reason, result: CompactionResult | undefined, aborted, willRetry, errorMessage? }`
+- `auto_retry_start` — `{ attempt, maxAttempts, delayMs, errorMessage }`
+- `auto_retry_end` — `{ success, attempt, finalError? }`
+- `summarization_retry_scheduled` — `{ attempt, maxAttempts, delayMs, errorMessage }`
+- `summarization_retry_attempt_start` — `{ source: "branchSummary" }` or `{ source: "compaction", reason }`
+- `summarization_retry_finished`
+
+Base `AgentEvent` types:
+
+- `agent_start`, `agent_end` (`messages`)
+- `turn_start`, `turn_end` (`message`, `toolResults`)
+- `message_start` (`message`), `message_update` (`usage`, `assistantMessageEvent`), `message_end` (`message`)
+- `tool_execution_start` (`toolCallId`, `toolName`, `args`), `tool_execution_update` (+ `partialResult`), `tool_execution_end` (`result`, `isError`)
 
 ## Output Format
 
@@ -43,15 +59,20 @@ First line is the session header:
 {"type":"session","version":3,"id":"uuid","timestamp":"...","cwd":"/path"}
 ```
 
-Subsequent lines are events:
+Then events as they occur:
 
 ```json
 {"type":"agent_start"}
 {"type":"turn_start"}
-{"type":"message_update","message":{},"assistantMessageEvent":{"type":"text_delta","delta":"Hello"}}
+{"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 carries the latest cumulative provider-reported usage and may stay zero when a provider only reports usage at completion. Assemble live text, thinking, or tool-call arguments from `contentIndex` and `delta`; `message_end` holds the final authoritative message.
+
 ## Example
 
 ```bash