Align Item, event, reasoning and usage serialization

[SaladDay]

Items, events, reasoning and usage now carry the official field presence and sequencing where the pinned types define them. Model output text is never altered and no model-derived defaults or counters are invented. The pinned baseline is unchanged (SDK 3.13.0 / d7c41ef / agents=v1).

Behavior

• Null field presence (S1–S3):

  • item.added/item.done carry output_index: null when there is no index.
  • Message Items always carry phase: null for user messages, the native value or null for assistant messages.
  • function_call_output always carries error (null when none) and output.

  These are applied at rendering. Stored Item payloads keep their previous encoding (Item.MarshalStored), so replayed child Items and creation-retry hashes are unchanged.

• Assistant message framing (S4/S5):

  • item.added is in_progress with content: [], then content_part.added with text "", then deltas, output_text.done, content_part.done and item.done.
  • A message that the native harness delivers complete, such as Claude structured output, uses the same sequence with the exact final text in one delta.
  • Stored Items are unchanged.

• Reasoning (S6): Session and saved Agent responses serialize {effort, summary} with explicit nulls instead of {}. No model default is filled in (official reports model-specific values; that remains a documented difference).

• Session usage (S7): public usage is the sum of root-Turn usage only when every root Turn has ended with recorded usage. Otherwise it is null, including while any root Turn is queued, running or waiting. This follows EVT-13 and the scan-5 ST-03 official samples.

• Core observability is unaffected by S7:

  • Runtime history token points use a separate tenant-scoped query that keeps summing measured usage continuously. This is a documented Core extension.
  • The Core Web dashboard summary total holds each Session's last reported value while public usage is null. The live trend shows those intervals as gaps, never zero, and spreads the rate over the elapsed time once usage is reported again.

• Cancelled Codex Turns (S8):

  • The all-zero usage came from the Codex adapter. It published a zero difference between two unchanged native thread totals as a real measurement.
  • An unchanged total now leaves the Turn's usage unknown (null).

• Client and Core Web: accept the new nulls and still accept older Cores that omit them.

Evidence

• EVT-09, EVT-10 and EVT-13 (campaign scan 2, raw official frames).
• SES-23 and SES-25 (scan 1).
• VA-11.
• ST-03 (scan 5, 3 official samples).
• The live-kit observation EVT-24.

Recorded in history-events-usage.md, execution-tools.md, runtime-history-api.md and operation-evidence.md (register SR, rows 7, 12, 15).

Validation

• Live acceptance: real Core, the daemon and native harnesses on environment: none. Every image, the Claude bridge included, was built from each tree. 5 Turns per phase. All events and reads were validated with the pinned SDK's strict parse.

  Row	Codex + Kimi K3	Claude SDK + Kimi K3	MiniMax Code + M2.7
  S1 output_index: null	FAIL → PASS	FAIL → PASS	FAIL → PASS
  S2 phase present	FAIL → PASS	FAIL → PASS	FAIL → PASS
  S3 error/output present	FAIL → PASS	–	–
  S4 framing	FAIL → PASS	–	FAIL → PASS
  S5 one byte-identical delta	–	FAIL → PASS	–
  S6 reasoning nulls	FAIL → PASS	–	–
  S7 Session usage (null in all 212 samples during Turns, sum after)	FAIL → PASS	PASS → PASS	PASS → PASS
  S8 cancelled Turn usage	FAIL (zeros) → PASS (null)	–	–

  Cleanup and secret scans passed.

• Tests:

  • Contract, store (real PostgreSQL), API, Items, runtime observation and runtime history tests.
  • Codex adapter tests with -race, including a reproduction of the zero-usage cancel.
  • TS client and Core Web tests.
  • The pinned-SDK official client suite.

• Server gate on this head: all make check targets plus Web typecheck, core-doctor, unit tests and build pass. The Playwright browser cases were not run on the server (no Google Chrome; the user approved the skip). make openapi and make sqlc-generate are byte-identical.

• Independent blind review by a fresh Claude Code subagent (the user-approved replacement for GPT-6 Astra). It found no blockers and confirmed in code: stored Item payloads and creation-retry hashes are unchanged; the Claude structured-output path produces exactly one byte-identical delta; S7 counts only root Turns; every public caller uses the public rule; and the telemetry query is tenant-scoped. Its follow-ups are fixed in the last two commits:

  • The Core Web live trend now shows gaps, not zero, while usage is held, and spreads the rate over the elapsed time when usage returns.
  • Stale observability and sqlc docs are corrected.
  • The docs record that a root Turn cancelled while queued keeps public Session usage null, an inference with no official sample.

  These were verified by Web tests and the gate on the final head, without a new review, per the user's rule.

No full protocol compatibility is claimed.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}