Upsert messages in an agent session

Advance the session's inbox cursor past this message_index, in the SAME transaction as this message write. The caller has already put those messages into the conversation it is writing, so consuming them and recording the turn that consumed them commit together or not at all. A message that arrived after the caller read has a higher index and is left for the next turn. A session with no inbox is not an error — nothing is advanced.

The status of the latest agent instance driving a session. The same enum is used for cloud and local instances. Cloud-only values (queued, terminating, rate_limited, skipped) are set by the cloud instance lifecycle (start/terminate/end). Common values (running, needs_attention, completed, failed, terminated) are written by either cloud or local clients. merged is a session-level state applied after a completed authoring task's branch is merged into master (via the branch merge endpoint or the session's auto_merge setting); the underlying cloud instance stays completed. accepted and closed are session-level review outcomes for a finished authoring task, set only through the review endpoint; the underlying cloud instance keeps its own status. accepted records that the user kept the authored test. closed records that the user discarded it; the session's test is left in place unless the caller asked for it to be deleted (delete_test on the review request), no branch is deleted either way, and the session's conversation is retained so the task can be regenerated from it. Both are terminal in the same sense as merged — neither is resumable, and no lifecycle transition leaves them. resuming is a transient, server-set-only state on the session (no instance holds it) — the cloud TAA continuation flow flips a resumable session to resuming while it plans the answer, then to queued when the new instance spawns (or back to a resumable status on re-clarification, or failed on error). It is the concurrency guard, so a second answer to a resuming session is rejected. The session's instance_type field indicates which kind of instance owns the session. Use none in query parameters to match sessions without any status.

The id of the agent session

The id of the workspace

The timestamp of the agent session creation in epoch milliseconds

The id of the user who created the agent session

The timestamp of the agent session last update in epoch milliseconds

The id of the user who last updated the agent session

Whether this agent session is associated with a trial account

The id of the parent agent session

A unique identifier for the request that initiated this agent session. If set, this must be globally unique and requests to create a new agent session with the same initiating_request_id will fail.

Indicates what kind of agent instance is driving a session. cloud means a server-managed cloud instance owns the lifecycle (created via the cloudInstance endpoints). local means a local client (e.g. mabl CLI) is driving the session via updateAgentSession.

The status of the latest agent instance driving a session. The same enum is used for cloud and local instances. Cloud-only values (queued, terminating, rate_limited, skipped) are set by the cloud instance lifecycle (start/terminate/end). Common values (running, needs_attention, completed, failed, terminated) are written by either cloud or local clients. merged is a session-level state applied after a completed authoring task's branch is merged into master (via the branch merge endpoint or the session's auto_merge setting); the underlying cloud instance stays completed. accepted and closed are session-level review outcomes for a finished authoring task, set only through the review endpoint; the underlying cloud instance keeps its own status. accepted records that the user kept the authored test. closed records that the user discarded it; the session's test is left in place unless the caller asked for it to be deleted (delete_test on the review request), no branch is deleted either way, and the session's conversation is retained so the task can be regenerated from it. Both are terminal in the same sense as merged — neither is resumable, and no lifecycle transition leaves them. resuming is a transient, server-set-only state on the session (no instance holds it) — the cloud TAA continuation flow flips a resumable session to resuming while it plans the answer, then to queued when the new instance spawns (or back to a resumable status on re-clarification, or failed on error). It is the concurrency guard, so a second answer to a resuming session is rejected. The session's instance_type field indicates which kind of instance owns the session. Use none in query parameters to match sessions without any status.

The reason for terminating a cloud instance. 'infra_shutdown' covers any shutdown signal from the runtime environment (K8s pod eviction, Cloud Run instance cycling, etc.) — kept generic so it applies regardless of where the agent runs. 'dispatch_failed' means the instance never started — its start message failed to publish, or expired in the queue before any runner claimed it. 'agent_stalled' means the agent was still alive but stopped making progress, so a watchdog hard-killed it. 'agent_error' means the agent threw or exited unexpectedly while its work was still in flight.

The authoring-agent arm assigned to this session at creation time (values: generic or flexible). Records which test-authoring agent variant the runtime should use for the session. Only set for test_authoring sessions; unset for other agent types.