opensource/cline
3
0
Fork 0
mirror of https://github.com/cline/cline.git synced 2026-10-24 02:02:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(sdk): document runTurn's teardown rejection and the discarded field

Browse Source 
sdk/AGENTS.md asks for a DOC.md update when exported surfaces or
lifecycle semantics change. DOC.md now states how abort() and
stopSession() differ for queued prompts, that runTurn rejects for a
session whose teardown has started, and what the discarded field on
SessionPendingPromptsEvent and the pending_prompts_discarded telemetry
carry.
This commit is contained in:
Mikołaj Kondratek
2026-10-23 12:17:04 +02:00
parent e89344067c
commit bd71007a3a
1 changed files with 29 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
sdk/DOC.md
+29
View File
@@ -496,3 +496,32 @@ run returns.
No message text leaves the client: `textSignature` and `session.input_sent`'s
`bumpKind` are enums computed locally
(`packages/core/src/services/telemetry/stall-signals.ts`).
## Pending prompts and session teardown
Two host calls end a turn and they differ for prompts queued behind it.
`abort(sessionId)` (the Stop/Cancel button) stops the in-flight turn and
leaves the session alive and `idle`; queued prompts stay in the queue and
drain once the abort settles, and a `delivery: "steer"` prompt sent to the
idle session starts a turn. `stopSession(sessionId)`, `deleteSession(sessionId)`
and `dispose()` tear the session down; nothing can reach it afterwards.
- Once teardown has started, `runTurn` rejects for that session with
`Session <id> is shutting down`, for immediate, `queue` and `steer`
delivery alike. Before this it resolved `undefined`, which is also what an
accepted queued prompt returns, so a caller could not tell that the input
was lost. Hub clients receive the rejection as a failed `session.send_input`
command (and a `run.failed` event for it).
- `SessionPendingPromptsEvent` (`pending_prompts`) has an optional
`discarded: SessionPendingPrompt[]`. It is present on the snapshot that
empties the queue when prompts leave it without being sent: on teardown, when
the user aborts a turn the queue itself started, and when a dequeued prompt
is stopped by teardown before the agent accepted it (that prompt was already
announced by `pending_prompt_submitted`, so the `discarded` entry with the
same `id` is how a client learns it never ran). Snapshots that only reorder
or remove prompts at the user's request carry no `discarded`. The hub
forwards the field unchanged. Hosts that let users recover typed text should
read it from this event; the queue itself is not persisted across teardown.
- `session.pending_prompts_discarded` telemetry (`count`, `reason` of
`session_teardown` or `queue_abort`) is emitted alongside; it never carries
prompt text.