@spec cancel(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentSession.t()} | {:error, ArchAstro.Error.reason()}

Cancel an agent session

Requests cancellation of an active agent session. The session status is set to "cancelled" and any in-progress agent turn is interrupted as soon as the platform can safely stop it.

If the session is already in a terminal state ("completed", "failed", or "cancelled"), the call succeeds and returns the session unchanged — it is safe to call this endpoint more than once.

Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.

The agent session after the cancellation request is applied.

@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1AgentSessions.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentSession.t()} | {:error, ArchAstro.Error.reason()}

Create an agent session

Creates a new agent session and enqueues it for execution. The session begins in "pending" status and transitions to "running" once the platform picks it up. Subscribe to the session stream endpoint to receive real-time status updates.

You must supply the ID of an agent that the authenticated app owns and a plain-text instructions string describing the task. All other parameters are optional and default to the agent's configured limits when omitted.

Set start_idle to true to create the session without running an opening turn — it begins in "waiting" status and runs its first turn only once you post a message (see the message endpoint). Use this when you want the first message to drive the session instead of the instructions alone.

Requires an app-scoped API key. Returns HTTP 201 on success.

The newly created agent session.

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete an agent session

Permanently deletes an agent session and its associated data. This action is irreversible — the session record, its trajectory, and all inbox messages are removed.

To stop a running session without deleting it, use the cancel endpoint instead. The session must be in a terminal state ("completed", "failed", or "cancelled") before it can be deleted; attempting to delete an active session returns 422.

Requires an app-scoped API key. Returns HTTP 204 with no body on success.

Empty body. HTTP 204 indicates the session was permanently deleted.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentSession.t()} | {:error, ArchAstro.Error.reason()}

Retrieve an agent session

Returns the agent session identified by agent_session. Use this endpoint to poll session status or to inspect the final result after execution completes.

For real-time updates without polling, subscribe to the session stream endpoint instead, which delivers server-sent events whenever the session state changes.

Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.

The requested agent session.

@spec list(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1AgentSessions.Params.t()
) ::
  {:ok, ArchAstro.Types.AgentSessionListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List agent sessions

Returns a flat list of agent sessions visible to the authenticated app, ordered by creation time descending. Use the agent, status, and routine_run filters to narrow results.

All filters are optional and can be combined. The status and routine_run parameters each accept multiple values; pass the parameter more than once or as a comma-separated array to match any of the supplied values.

Requires an app-scoped API key. Results are limited to sessions that belong to agents owned by the authenticated app.

A list of agent sessions matching the supplied filters.

@spec message(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentSessionsAgentSessionMessage.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentSession.t()} | {:error, ArchAstro.Error.reason()}

Send a message to an agent session

Appends a message to the inbox of the specified agent session. The agent reads inbox messages at the start of each turn; sending a message to a "waiting" session signals it to resume execution.

Use role to identify the sender type. The default role is "user". Arbitrary key-value metadata may be attached to the message for tracking or display purposes.

Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.

The agent session with the new message appended to its inbox.

@spec stream(ArchAstro.Client.t(), String.t()) ::
  ArchAstro.SSE.Stream.t(
    ArchAstro.Types.Operations.GetApiV1AgentSessionsAgentSessionStream.StreamEvent.t()
  )

Stream agent session status

Opens a Server-Sent Events connection that emits a session_update event whenever the agent session's status changes, replaying the current status on connect and closing on a terminal status (completed, failed, cancelled).

Server-Sent Events stream

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1AgentSessionsAgentSession.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentSession.t()} | {:error, ArchAstro.Error.reason()}

Update an agent session

Updates the mutable fields of an agent session. Currently only metadata can be changed; supply any key-value pairs you want to store alongside the session. Omitting metadata leaves it unchanged.

This endpoint may be called while the session is in any status, including while it is actively running.

Requires an app-scoped API key. The session must belong to an agent owned by the authenticated app.

The agent session with the updated fields applied.