Problem
An external agent runtime currently needs separate continuation lookup, turn creation, user-item append, and replay calls. Those calls leave races around ownership, predecessor validity, concurrent continuations, and conversation edits.
Proposed change
Add an agent-facing atomic start operation, for example POST /v1/agent-turns, that in one transaction:
- authenticates the tenant, owner, and agent deployment
- resolves an optional
previous_response_id
- returns the same not-found result for absent and wrong-owner predecessors
- verifies the predecessor is terminal and continuable
- enforces a linear/head continuation policy for the initial version
- creates a conversation when no predecessor is supplied
- creates a pending turn
- appends the ordered user input items
- reserves the runtime-supplied
response_id
- records and validates an idempotency request digest
- returns the conversation ID, turn ID, predecessor sequence boundary, and current input boundary
An exact retry must return the original result. Reusing the key with different input must return a typed conflict. An unknown HTTP outcome must be reconcilable by the same idempotency key or response ID.
Acceptance criteria
- Start is one database transaction.
- Concurrent starts from the same linear head produce one winner and one typed conflict.
- No model execution is required before the operation commits.
- Existing-conversation and new-conversation paths are covered.
- Exact retry, altered retry, wrong owner, wrong agent, missing predecessor, non-terminal predecessor, and concurrent continuation are tested.
- The wire contract and failure codes are documented.
Integration context
This is the durable admission boundary needed by Bonsai before it exposes a new Open Responses resp_* ID.
Problem
An external agent runtime currently needs separate continuation lookup, turn creation, user-item append, and replay calls. Those calls leave races around ownership, predecessor validity, concurrent continuations, and conversation edits.
Proposed change
Add an agent-facing atomic start operation, for example
POST /v1/agent-turns, that in one transaction:previous_response_idresponse_idAn exact retry must return the original result. Reusing the key with different input must return a typed conflict. An unknown HTTP outcome must be reconcilable by the same idempotency key or response ID.
Acceptance criteria
Integration context
This is the durable admission boundary needed by Bonsai before it exposes a new Open Responses
resp_*ID.