You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -22,8 +22,7 @@ The Host emits one ordered `conversationItems` collection. A visual turn has its
22
22
23
23
- A user `message` opens a visual turn and supplies its stable `sourceEntryId`.
24
24
- Assistant content becomes reasoning, response, and tool activities in protocol order. The persisted assistant identity is the session entry ID; a Pi message ID or timestamp is only a live-to-persisted correlation clue and never merges two persisted entries.
25
-
- A tool result updates the activity identified by `toolCallId`; it is not a second visible activity. Assistant takeover relocates all reasoning, response, and embedded tool-call parts as one ownership unit, including the tool location. Once a persisted tool result arrives, delayed live tool events cannot replace its stable content.
26
-
- A complete history replacement finalizes every tool still marked `running` as `cancelled`: FrostPi no longer has live tracking and did not receive a final result. This local status preserves partial output and may be replaced by a later persisted tool result.
25
+
- A tool result updates the activity identified by `toolCallId`; it is not a second visible activity. Assistant takeover relocates all reasoning, response, and embedded tool-call parts as one ownership unit, including the tool location.
27
26
-`compaction`, `branch_summary`, and `custom_message` are independent items at their active-path positions.
28
27
- Compaction never removes or hides earlier active-path items. Nested `retainedTail` values are LLM-context metadata and are not expanded into transcript items.
29
28
- Every `custom_message` with `display: true` renders generic text and image blocks. `display: false` messages and plain `custom` state entries are omitted.
@@ -41,13 +40,21 @@ Incremental ownership is preflighted before branch controls or conversation item
41
40
42
41
Incremental entries are accepted only when the reported leaf connects to the previous active leaf through the returned batch. Branch movement, an incomplete connecting chain, a correlation conflict, or a newly discovered control whose edge belongs before the appended segment requires a complete reload.
43
42
43
+
## Unresolved tool results
44
+
45
+
A tool is `running` only while FrostPi can still receive live execution updates. A persisted assistant `toolCall` records that an invocation exists; it does not prove that the invocation is still running or provide its final outcome.
46
+
47
+
Incremental assistant takeover therefore preserves the existing execution state and partial output for the same `toolCallId` while adopting persisted assistant ownership and placement. Only a matching persisted `toolResult` is authoritative for replacing that state with `complete` or `error`; delayed live tool events cannot replace content already owned by a persisted result.
48
+
49
+
A complete history replacement, `agent_settled`, process stop, or connection failure finalizes every still-running tool as `cancelled`. Here `cancelled` means live tracking ended before FrostPi received a final result. It preserves arguments and partial output, does not synthesize output, error, or end time, and does not alter the containing turn status. Incremental entry reconciliation alone is not a finalization boundary because the current Pi process may still be executing the tool.
50
+
44
51
## Turn lifecycle
45
52
46
53
A persisted user message closes the preceding visual turn and opens a user-anchored turn. Assistant `toolUse` keeps it active; an assistant error keeps an `error-awaiting-continuation` anchor so provider retry or context-overflow compaction continuation remains in that turn. A later success or abort closes it. A replacement, a new user entry, or the refresh after `agent_settled` finalizes an error that received no continuation.
47
54
48
55
Live `message_end(error)` displays the error activity but leaves the turn running until `agent_end` decides whether Pi will retry. `agent_end(willRetry: true)` keeps the running turn and `auto_retry_start` adds a notice; `willRetry: false` commits the pending error. This uses the existing turn statuses and does not persist retry notices.
49
56
50
-
While an agent run is active, queued follow-ups remain outside persisted conversation order. Pi may emit a follow-up user message without another `agent_start`; promotion follows protocol FIFO order and closes the prior visual turn. Abort, process stop, and process failure clear the local queue. `agent_settled`, process stop, and process failure also finalize unresolved running tools as `cancelled`; they do not infer a tool error or alter the turn status.
57
+
While an agent run is active, queued follow-ups remain outside persisted conversation order. Pi may emit a follow-up user message without another `agent_start`; promotion follows protocol FIFO order and closes the prior visual turn. Abort, process stop, and process failure clear the local queue. Tool tracking at these lifecycle boundaries follows [Unresolved tool results](#unresolved-tool-results).
51
58
52
59
Live activity updates replace existing view objects instead of mutating them. This is required for bridge deltas and Webview-owned disclosure state. Documented assistant events provide an ID or timestamp correlation clue; a malformed live assistant without either is omitted until persisted refresh rather than emitted as an uncorrelatable duplicate. Notices emitted during an active turn remain inside its ordered items; idle notices are top-level conversation items.
`failed` ends the current child process but leaves retryable metadata. Queued/starting sessions reject submission and model mutation while retaining session actions; running sessions keep the Composer editable and expose Stop. Prompt RPC success means accepted, not completed; only `agent_settled` returns a running session to ready.
36
36
37
-
`agent_end` closes one model attempt, not necessarily the user turn. With `willRetry: true`, the session remains running and conversation projection keeps the pending assistant error in the same user turn; `auto_retry_start` supplies the transient retry notice. With `willRetry: false`, the pending error may become final. `agent_settled` is the completion boundary: Runtime returns the session to ready, refreshes persisted entries, and may issue the one normal-completion notification. Assistant protocol errors remain errors when no continuation succeeds, while a tool failure remains visible without by itself failing the whole turn.
37
+
`agent_end` closes one model attempt, not necessarily the user turn. With `willRetry: true`, the session remains running and conversation projection keeps the pending assistant error in the same user turn; `auto_retry_start` supplies the transient retry notice. With `willRetry: false`, the pending error may become final. `agent_settled` is the completion boundary: Runtime returns the session to ready, refreshes persisted entries, and may issue the one normal-completion notification. Assistant protocol errors remain errors when no continuation succeeds, while a tool failure remains visible without by itself failing the whole turn. Unresolved tool semantics and finalization boundaries belong to [`conversation-projection.SPEC.md`](../conversation/conversation-projection.SPEC.md#unresolved-tool-results).
38
38
39
39
`abort` stops the current run and keeps the process. A restart cancels pending extension UI, stops the child, and starts Pi with the recorded session file; active streams, tools, and pending requests do not survive. Disruptive explicit restart requires confirmation.
0 commit comments