[REA-6855] Serve saved step folders over HTTP

[Dere-Wah]

Why

The step folders are only useful if a caller can read them, and the caller may come for them after the session is over: a session that stopped at its steps has usually closed by the time its last folder is written.

What Changed

Three routes serve the folders by the session's own id:

GET /sessions/{id}/steps                {"steps": [1, 2, 3, 4]}
GET /sessions/{id}/steps/{n}            the step's result.json
GET /sessions/{id}/steps/{n}/{name}     a file result.json lists, with its content type

Only a step whose result.json is written is listed or served, so a reader never sees a step that is half saved. Only a name that result.json lists is served, so neither a file still being written nor a path that leaves the folder is reachable; result.json itself is read through the second route. A session that kept no folder, an id that is not a UUID, and a step that is not complete are all 404. The routes keep answering after the session ends, until each folder ages out.

Both file routes open the file inside the handler: result.json is read there, and other files are streamed from a handle opened there, with Content-Length from it. A folder that ages out between the lookup and the response answers 404 rather than failing in a deferred open, and one that ages out mid-transfer is still read whole from the open handle.

The OpenAPI document gains the three routes and the result.json schema, as additions only. The README now describes steps and step results, and the contract suite locks the surface end to end: a two-step session on a model whose process_output() returns a StepCompleted with an extra file, its step_result_ready facts, every route, the folders after the session ends, and the 404s.

Checked against examples/starter with step results on and steps: 3, with no client: four steps were saved (one reported after the stop), two of them finished after the session was back to ready, the list returned [1, 2, 3, 4], and output.mp4 decoded as an 800×500 H.264 frame at 30 fps.

[github-actions]

[codex-review] - [P2] src/reactor_runtime/http/routes.py: retention cleanup can race FileResponse, producing a 500 instead of 404.

Scope: full (4a3e9e0..d7e5693).

View workflow run.

[Dere-Wah]

• [REA-6855] Serve saved step folders over HTTP #239 👈 (View in Graphite)
• [REA-6855] Save each reported step as a folder of files #238
• [REA-6855] Write one step's output as a single MP4 file #237
• [REA-6855] Read the runtime.step_results block from the manifest #236
• [REA-6854] Close a session when it reaches its steps #235
• [REA-6854] Report each finished step to the runtime with complete_step() #234
• [REA-6854] Apply a session's starting input, sent by a system client #233
• [REA-6854] Read starting_input and steps from the start body #232
• [REA-6854] Deliver commands and reactor events to the model in posted order #231
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[tempusfrangit]

Approved with a nonblocking follow-up on the existing retention/read race: please keep an admitted file stable during delivery, or translate disappearance during response setup into a 404. Add a regression test that forces cleanup between path validation and response setup. The overall route design and contract coverage look sound.

[Dere-Wah]

@tempusfrangit done in 1f3fcad: both routes open the file inside the handler, so a folder reaped after its lookup answers 404 and one reaped mid-transfer is still sent whole. Regression tests delete the folder between validation and response, and during a transfer.

[Dere-Wah]

Merge activity

• Oct 5, 6:07 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Oct 5, 6:33 PM UTC: Graphite rebased this pull request as part of a merge.
• Oct 5, 6:34 PM UTC: @Dere-Wah merged this pull request with Graphite.