Harden the thread events API for the transcript writer #208

Closed AtlantisPleb opened this 2d ago 1 comment

Evidence

Shipped in the release at 8c53d09, promoted 2026-08-26.

1 pushes receipt

Outcome

Three small contract improvements found while building the CLI transcript writer (OpenAgentsInc/openagents#23):

POST /api/v3/threads/{id}/events returns 201 {"thread": {...}} — the thread view, not the created event, so a client never learns its event's id or cursor at write time. Return the created event (id and sequence) alongside or instead.
Validation refusals are 422 {"errors": {...}} with no machine code, while thread_terminal is 422 with a top-level "code". Give validation errors a stable machine code too, so clients distinguish retry-safe from drop-only without parsing prose.
There is no batch append; a tool-heavy turn costs one round trip per event and exit flush pays the full ladder. Add a bulk append that preserves order atomically.

Bonus consideration: the route accepts any non-blank event_type with an object payload — the vocabulary is client discipline. Decide whether the server should pin the known types once the vocabulary settles.

AtlantisPleb opened this issue 2d ago
A AtlantisPleb Author 2d ago

Closing as completed. Merged to main and pushed as d0a44b2. POST /api/v3/threads/{id}/events now returns the created event (id — the cursor — schema, event_type, payload, emitted_at, inserted_at) beside the thread; validation refusals carry the stable code event_invalid symmetric with thread_terminal; and the same route accepts {"events": [...]} for all-or-nothing ordered batch append (Threads.record_events/2, cap 100 via config, event_batch_too_large over it, positional errors keyed events[N].field, terminal refusal for the whole batch). Broadcasts fire once per created event in order after commit; a rolled-back batch broadcasts nothing. Verified compatible with the deployed transcript writer (it ignores 2xx bodies and reads only code on 4xx). 65 targeted tests pass post-merge alongside the grants re-mint route. The CLI can adopt batch append for exit-flush latency whenever convenient — no urgency.
AtlantisPleb closed this as completed in d0a44b2 2d ago