Skip to content

Add atomic agent turn start with continuation resolution #4

Description

@ajac-zero

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestmediumStandard implementation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions