Skip to content

Commit dc635b8

Browse files
byapparovclaude
andcommitted
feat(run): emit a user_message NDJSON event
`aictrl run --format json` never emitted user messages, so the stream could not reconstruct what the model was asked. Emit each primary-session user message once, with its messageID, agent, model, full parts as stored (synthetic flags and -f file parts included) and a sequenceNum on the per-session counter shared with text/reasoning/tool_use. The bus has no "user message complete" event: updateMessage publishes the info, then updatePart publishes each part. A small collector in run.user-message.ts treats the message as complete at the first primary-session event that is not about it (the loop's busy status, the assistant message, an error or idle), so user_message always precedes the assistant events it triggers. Child-session user messages are not emitted, matching text. This covers the prompt, the --command expansion, and the user messages the loop stores itself (compaction request, compaction continue, subtask summary). The StructuredOutput corrective reminder is never stored, so it has no user_message; structured_output_rejected already reports it. Additive: schemaVersion stays "1". Part of #223. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_015nwvfUHdM3bgMgD9Zpz7Mj
1 parent adf968f commit dc635b8

6 files changed

Lines changed: 402 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
## Unreleased
44

5+
### Features
6+
7+
- **`user_message` NDJSON event** — `aictrl run --format json` now emits each primary-session user message once, with its `messageID`, `agent`, `model`, full `parts` as stored (including `synthetic` flags and `-f` file parts) and a `sequenceNum` on the per-session counter shared with `text`, `reasoning` and `tool_use`. It covers the prompt, the `--command` expansion and the user messages the loop creates (the compaction request, the compaction "continue" message and the subtask summary request), and always comes before the assistant events it triggers. Parts are not truncated, so consumers must accept large lines. The StructuredOutput corrective reminder is not stored, so it has no `user_message`. Subagent user messages are not emitted. The event is additive; `schemaVersion` stays `"1"`. (part of #223)
8+
59
### Fixes
610

711
- **Messages written in the same millisecond keep their order** — Reading a session's messages now breaks `time_created` ties by message ID. Before, messages written in the same millisecond came back oldest first. A compaction writes its request, its summary and the continue message in quick succession, so the prompt loop could miss the finished summary and compact again, sending an extra model request. (#200)

‎EVENTS.md‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,37 @@ Emitted when a primary-session model attempt fails with a retryable error and th
220220

221221
**Retry delays.** No single wait between attempts exceeds 5 minutes, whatever the status code or headers. Each retry waits for the provider's `Retry-After` / `retry-after-ms` when it asks for a positive wait, or else for exponential backoff of 2 s, 4 s, 8 s and 16 s, then 30 s for each later attempt. A retryable error whose provider asks for a wait longer than 5 minutes is not retried: a 429 fails as a provider usage limit (see `session_error`), and any other status (for example a 503 or 529 "overloaded" with `retry-after: 18000`) fails with that provider error, so `session_error.reason` is classified from its status as usual (`provider` for a 5xx). Neither emits a `retry` event. With at most 10 retries, the waits total at most 50 minutes when every response asks for 5 minutes, and 3.5 minutes (210 s) when no response gives a retry hint.
222222

223+
### `user_message`
224+
225+
Emitted once for each primary-session user message, after all of its parts are stored. This covers the prompt (with its `-f` file parts and any agent or subtask parts), the `--command` expansion, and the user messages the session loop creates itself: the compaction request, the compaction "continue" message and the message that asks the model to summarize a subtask's output.
226+
227+
```json
228+
{
229+
"type": "user_message",
230+
"messageID": "msg_01abc...",
231+
"agent": "build",
232+
"model": { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" },
233+
"parts": [
234+
{
235+
"id": "prt_01abc...",
236+
"messageID": "msg_01abc...",
237+
"sessionID": "session_01abc...",
238+
"type": "text",
239+
"text": "Fix the failing test"
240+
}
241+
],
242+
"sequenceNum": 1
243+
}
244+
```
245+
246+
- `messageID` (string, **required**) — stable user-message identity. Assistant messages it triggers carry it as their `parentID`.
247+
- `agent` (string, **required**) — the agent the message was sent to.
248+
- `model` (object, **required**) — `{ providerID, modelID }` the message was sent with.
249+
- `parts` (array, **required**) — the message's parts exactly as stored, in the order they were written. Parts the CLI derived from the input have `synthetic: true`; for example, the text a `-f` file or MCP resource expands to, or the compaction "continue" text. A compaction request has a single `compaction` part. Parts are not truncated: a `file` part can carry a `data:` URL, so consumers must accept arbitrarily large lines, as for `reasoning`.
250+
- `sequenceNum` (number, **required**) — the same per-session counter as `text`, `reasoning` and `tool_use`. A `user_message` is emitted before any event of the assistant turn it triggers, so its `sequenceNum` is lower than theirs.
251+
252+
The StructuredOutput corrective reminder is not a stored user message. It is added to the next model request only, so it emits no `user_message`; `structured_output_rejected` reports each corrective turn instead. Child-session (subagent) user messages are not emitted, matching `text`.
253+
223254
### `message_complete`
224255

225256
Emitted when a primary-session assistant message finishes (one per LLM turn). Child-session assistant messages are
@@ -314,7 +345,7 @@ Emitted when a text block from the assistant is complete.
314345
}
315346
```
316347

317-
- `sequenceNum` (number, **required**) — monotonic per-session counter shared across `text`, `reasoning`, and `tool_use` events. Use it to render a correctly-ordered trace without relying on timestamp ties. Subagent sessions have their own independent counters keyed on `part.sessionID`. Note: in JSON mode only `tool_use` events are emitted for subagent sessions, so subagent counters increment only on tool_use.
348+
- `sequenceNum` (number, **required**) — monotonic per-session counter shared across `user_message`, `text`, `reasoning`, and `tool_use` events. Use it to render a correctly-ordered trace without relying on timestamp ties. Subagent sessions have their own independent counters keyed on `part.sessionID`. Note: in JSON mode only `tool_use` events are emitted for subagent sessions, so subagent counters increment only on tool_use.
318349

319350
### `reasoning`
320351

@@ -331,7 +362,7 @@ Emitted when extended thinking content is complete (requires `--thinking` flag).
331362
}
332363
```
333364

334-
- `sequenceNum` (number, **required**) — monotonic per-session counter shared across `text`, `reasoning`, and `tool_use` events. Use it to render a correctly-ordered trace without relying on timestamp ties. Subagent sessions have their own independent counters keyed on `part.sessionID`. Note: in JSON mode only `tool_use` events are emitted for subagent sessions, so subagent counters increment only on tool_use.
365+
- `sequenceNum` (number, **required**) — monotonic per-session counter shared across `user_message`, `text`, `reasoning`, and `tool_use` events. Use it to render a correctly-ordered trace without relying on timestamp ties. Subagent sessions have their own independent counters keyed on `part.sessionID`. Note: in JSON mode only `tool_use` events are emitted for subagent sessions, so subagent counters increment only on tool_use.
335366
- One event is emitted per complete reasoning block. `part.text` has no size cap; consumers must accept arbitrarily large strings.
336367

337368
## Tool Events
@@ -356,7 +387,7 @@ Emitted when a tool call completes (success or error). This includes tools execu
356387
}
357388
```
358389

359-
- `sequenceNum` (number, **required**) — monotonic per-session counter shared across `text`, `reasoning`, and `tool_use` events. Use it to render a correctly-ordered trace without relying on timestamp ties. Subagent sessions have their own independent counters keyed on `part.sessionID`. Note: in JSON mode only `tool_use` events are emitted for subagent sessions, so subagent counters increment only on tool_use.
390+
- `sequenceNum` (number, **required**) — monotonic per-session counter shared across `user_message`, `text`, `reasoning`, and `tool_use` events. Use it to render a correctly-ordered trace without relying on timestamp ties. Subagent sessions have their own independent counters keyed on `part.sessionID`. Note: in JSON mode only `tool_use` events are emitted for subagent sessions, so subagent counters increment only on tool_use.
360391

361392
`state.status` is `"completed"` or `"error"`. On error, `state.error` contains the error message.
362393

‎packages/cli/src/cli/cmd/run.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import { UI } from "../ui"
77
import { cmd } from "./cmd"
88
import { classifySessionError, SCHEMA_VERSION } from "./run.errors"
99
import { terminal } from "./run.terminal"
10+
import { userMessages } from "./run.user-message"
1011
import { buildToolCatalogItems } from "./tool-catalog"
1112
import { withTimeout } from "../../util/timeout"
1213
import { Flag } from "../../flag/flag"
@@ -645,6 +646,7 @@ export const RunCommand = cmd({
645646
const toggles = new Map<string, boolean>()
646647

647648
eventsLoop: for await (const event of events.stream) {
649+
users.observe(event)
648650
if (
649651
schema &&
650652
event.type === "session.structured_output_rejected" &&
@@ -928,6 +930,7 @@ export const RunCommand = cmd({
928930
})
929931
}
930932
}
933+
users.flush()
931934
}
932935

933936
// Validate agent if specified
@@ -960,6 +963,7 @@ export const RunCommand = cmd({
960963
await fail("Session not found", "INVOCATION_SESSION_CREATE_FAILED")
961964
}
962965
invocation.link(sessionID)
966+
const users = userMessages({ sessionID, emit, nextSeq: () => nextSeq(sessionID) })
963967

964968
emit("session_start", {
965969
schemaVersion: SCHEMA_VERSION,
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
import type { MessageV2 } from "../../session/message-v2"
2+
3+
type Emit = (type: string, data: Record<string, unknown>) => unknown
4+
5+
type BusEvent = { type: string; properties?: any }
6+
7+
type UserMessage = { info: MessageV2.User; parts: MessageV2.Part[] }
8+
9+
/** The session a bus event is about, or undefined for events that name no session. */
10+
function eventSessionID(event: BusEvent) {
11+
const properties = event.properties ?? {}
12+
return properties.sessionID ?? properties.info?.sessionID ?? properties.part?.sessionID
13+
}
14+
15+
function eventMessageID(event: BusEvent) {
16+
if (event.type === "message.updated") return event.properties.info.id
17+
if (event.type === "message.part.updated") return event.properties.part.messageID
18+
}
19+
20+
function upsertPart(parts: MessageV2.Part[], part: MessageV2.Part) {
21+
if (!parts.some((existing) => existing.id === part.id)) return [...parts, part]
22+
return parts.map((existing) => (existing.id === part.id ? part : existing))
23+
}
24+
25+
/**
26+
* Emits each primary-session user message once, as `user_message`.
27+
*
28+
* `Session.updateMessage` publishes the message info and `Session.updatePart`
29+
* then publishes each part; the bus has no "user message complete" event. The
30+
* message is complete when the session moves on: the first primary-session
31+
* event that is not about this message (the loop's `busy` status, the assistant
32+
* message it triggers, an error, or `idle`). Every assistant event follows one
33+
* of those, so a `user_message` always precedes the assistant events it causes.
34+
* Child-session user messages are not emitted, matching `text`.
35+
*/
36+
export function userMessages(input: { sessionID: string; emit: Emit; nextSeq: () => number }) {
37+
const emitted = new Set<string>()
38+
let pending: UserMessage | undefined
39+
40+
function flush() {
41+
if (!pending) return
42+
const { info, parts } = pending
43+
pending = undefined
44+
emitted.add(info.id)
45+
input.emit("user_message", {
46+
messageID: info.id,
47+
agent: info.agent,
48+
model: info.model,
49+
parts,
50+
sequenceNum: input.nextSeq(),
51+
})
52+
}
53+
54+
function isNewUserMessage(event: BusEvent) {
55+
if (event.type !== "message.updated") return false
56+
const info = event.properties.info
57+
return info.role === "user" && info.sessionID === input.sessionID && !emitted.has(info.id)
58+
}
59+
60+
function collect(event: BusEvent) {
61+
if (!pending) return
62+
if (event.type === "message.updated") pending.info = event.properties.info
63+
if (event.type === "message.part.updated") pending.parts = upsertPart(pending.parts, event.properties.part)
64+
}
65+
66+
return {
67+
observe(event: BusEvent) {
68+
if (pending && eventMessageID(event) === pending.info.id) return collect(event)
69+
if (eventSessionID(event) === input.sessionID) flush()
70+
if (isNewUserMessage(event)) pending = { info: event.properties.info, parts: [] }
71+
},
72+
/** Emits a message still pending when the event stream ends. */
73+
flush,
74+
}
75+
}

‎packages/cli/test/cli/run-output-schema.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -495,6 +495,7 @@ test("plain run pins unchanged event types and ordering", async () => {
495495
"invocation_start",
496496
"session_start",
497497
"tool_catalog",
498+
"user_message",
498499
"step_start",
499500
"text",
500501
"step_finish",

0 commit comments

Comments
 (0)