Module tasks 

Running a task.

POST /v1/responses is the core of the protocol: one unit of work, run on a named harness, returned as a Response object. The surface is shaped like a responses API rather than a chat-completions one, which is why it lives here and not in the OpenAI handler beside it.

Three requirements shape this module more than the happy path does.

Reserved fields are ignored, not rejected. tools and include are reserved by the specification, and a client that sends them for wire compatibility with another API must still be served. But ignoring has to be observable: dropping a field silently is indistinguishable from acting on it, so what was dropped comes back in metadata.ignored_fields — and only what this request actually carried, never a catalogue of what the server would drop.

Usage is honest or absent. null when the runner accounted for nothing. A fabricated zero is worse than an honest absence, because a client cannot tell it from a free task.

A terminal state never changes. Reading a task back must return the same status it finished with.

Structs

ContentPart

One part of a message.

CreateResponse

What a client sends to run a task.

Outcome

A finished task plus what the stream needs to describe it.

OutputItem

One item of a task’s output.

Prepared

Everything a task needs once the harness and session are settled.

Response

A task, in whatever state it reached.

ResponseStore

Responses this server has run and retained, and the sessions they belong to.

Usage

Token accounting, when the runner reported any.

Functions

cancel

Handle POST /v1/responses/{response_id}/cancel.

completed_response

Wrap finished text as the terminal response object.

create

Handle POST /v1/responses.

get

Handle GET /v1/responses/{response_id}.

is_session_id

Whether id has exactly the shape [id_with] mints for a session: the prefix, then a UUID in its simple form, 32 lowercase hex digits.

pending_response

The response object for a task that has not produced anything yet.

prepare

Resolve the harness, model and session for a task without running it.

run

Run one task to a terminal state.