Captures and files

A runner publishes output files as captures and lets people read file bytes from its environment on demand. Both ride the same outbound topology as everything else: the runner uploads, Nexus stores, clients read from Nexus.

Publish a capture

POST /agent_api/v1/executor/uploads

Executor plane. The runner uploads the bytes, receives an upload public_id, and names it in a committed result as a resource_link:

{
  "claim_token": "…",
  "content": [
    { "type": "text", "text": "Rendered the chart to chart.png." },
    { "type": "resource_link", "uri": "nexus://uploads/<public_id>", "name": "chart.png", "mimeType": "image/png" }
  ]
}

The result binds the capture. A link must name this executor's own capture or one retained by the task's sealed operation observation; anything else is refused (422 unknown_result_upload) with the park standing. A bound image or PDF reaches the model as an attachment when the current model accepts that media type; other links are the client's to show, and the tool's own sentence already names the path.

Read bytes

GET /agent_api/v1/uploads/{public_id}/bytes
GET /agent_api/v1/uploads/{public_id}/thumbnail
GET /agent_api/v1/uploads/{public_id}/preview

Member plane. The creator may read, and so may anyone with access to a readable row that refers to the upload — a conversation input's attachment, a tool result's capture. HTTP Range answers a slice; a strong ETag and If-None-Match answer 304. Thumbnails (256 px) and previews (1600 px) are generated by Nexus and limited to 30 per minute.

Files on the runner, on demand

A person's client can ask a runner for a file that no tool result named — a log, a build artifact — through the runner's files_bytes capability, and for a background process's output through process_log. These are announced without a description or schema, so the model never sees them. The request is an addressed operator call: a one-task standalone run with an explicitly routed tool step, using the ordinary claim, extension, commit and recovery. File bytes are always a capture, with Range for partial reads.

rho's own process reads its local surface directly; for a remote runner it goes through Nexus. rho call_tool, rho fetch, rho ps and rho logs expose these operations, and the browser downloads artifacts through rho, including artifacts on a separate runner.

Attachments to a task

A tool call whose input references uploads — a document the agent is importing into the runner — reads them through the task's attachment door with its claim:

GET /agent_api/v1/executor/inbox/{run_public_id}/{task_key}/attachments/{upload_public_id}

Retention

Captures named by a result live with that result. After the account's retention window prunes a run's execution detail, invocation-owned output files are removed with it; conversation attachments stay with their inputs. See Retention.

The upload resource's field table is in Uploads; the executor upload door and result binding are in the Executor reference.