Reference

sessions

Device acquisition: a session holds one device until it is released or expires. Index · shared schemas · errors.

sessions.create

Acquire a device matching a spec. It returns at once: ready for a warm local device, otherwise starting or queued. Requested installs run inside starting, outside test timeouts. install additionally requires apps:install.

Input:

{
  spec: DeviceSpec
  holder?: SessionCreateHolder
  key?: string  // 1–128 chars
  install?: AppSource[]  // ≤ 5 items
  idleTimeoutMs?: DurationMs
  maxDurationMs?: DurationMs
  fresh?: boolean
}

Output:

Session

Errors: U, E, CAPACITY_UNAVAILABLE, QUOTA_EXCEEDED, DEVICE_SPEC_INVALID, CAPABILITY_UNSUPPORTED, CONFLICT, ORG_SUSPENDED, PROJECT_SUSPENDED, SERVICE_SUSPENDED, PROJECT_REQUIRED.

Named types: AppSource, DeviceSpec, DurationMs, Session, SessionCreateHolder.

sessions.get

Read one session

Input:

{ sessionId: SessionId }

Output:

Session

Errors: U, NOT_FOUND.

Named types: Session, SessionId.

sessions.list

List the caller's visible sessions

Input:

{
  status?: 'live' | 'terminal' | 'all'  // default 'live'
  holderKind?: HolderKind
  limit?: integer  // default 50; 1–100
  cursor?: Cursor
}

Output:

{ sessions: Session[]; nextCursor?: string }

Errors: U.

Named types: Cursor, HolderKind, Session.

sessions.wait

Wait until ready (or terminal) or until timeoutMs. until: 'stream' is done once the session's stream can be opened (streamReadyAt set), at ready or before it, or once it is terminal. A timeout is a normal result, never an error.

Input:

{
  sessionId: SessionId
  until?: 'ready' | 'stream' | 'terminal'  // default 'ready'
  timeoutMs?: TimeoutMs  // default 30000
}

Output:

{ done: boolean; session: Session }

Errors: U, NOT_FOUND.

Named types: Session, SessionId, TimeoutMs.

sessions.heartbeat

Extend liveness. Required for test-worker; a keepalive for other holders.

Input:

{ sessionId: SessionId }

Output:

{ expiresAt: string; maxEndsAt?: string }

Errors: U, NOT_FOUND, SESSION_ENDED, SESSION_BUSY.

Named types: SessionId.

sessions.release

End a session: canceled before ready, ended(released) after. The device returns warm, or is recycled when healthy is false. Releasing an ended session returns it unchanged.

Input:

{
  sessionId: SessionId
  healthy?: boolean  // default true
  reason?: Label
}

Output:

Session

Errors: U, NOT_FOUND, SESSION_BUSY.

Named types: Label, Session, SessionId.

sessions.events

A session's events: status, app state, crashes, input state and stream readiness

Input:

{ sessionId?: SessionId; since?: Seq }

Output: an event iterator (text/event-stream on REST), each event:

SessionEvent

Errors: U, NOT_FOUND.

Named types: Seq, SessionEvent, SessionId.