Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xandrlabs.ai/llms.txt

Use this file to discover all available pages before exploring further.

Sessions in ALX Protocol group related solve runs under a shared context. You can inspect a session’s current state, page through its run history, or list all sessions for a user. All session types are canonical wire shapes exported from @alx/protocol and carry the same compatibility guarantees as solve types.

​
Nullability rules

Two distinct concepts govern optional fields in session responses:
  • null — the field is known and intentionally empty. The server evaluated the field and determined it has no value.
  • Omitted — the field is optional and was not provided. New clients SHOULD treat omitted optional fields as unavailable rather than invalid.
Never treat null and omission as interchangeable when writing protocol-compliant consumers.

​
Types

​
SessionSummary

Aggregate statistics for a session computed across all runs.
​
runCount
number
Total number of runs recorded in this session.
​
successCount
number
Number of runs that completed with ok: true.
​
avgImprovement
number
Average improvement score across all successful runs.
​
lastArtifactId
string
ID of the artifact most recently produced or selected in this session.
​
updatedAt
string
ISO-8601 timestamp of the most recent update to the session. Present in SessionStatusEnvelope.summary; may be omitted in SessionTimelineEnvelope.summary.

​
SessionStatus

The lifecycle state of a session. Returned in SessionStatusEnvelope.status. Valid values: "active" | "completed" | "failed" | "paused" | "abandoned"

​
SessionTimeline

An ordered array of SessionTimelineEvent objects representing the historical record of events in a session. Returned in SessionTimelineEnvelope.timeline. Events are ordered chronologically by timestamp (epoch milliseconds). The closed vocabulary of event types is: execution, step, fallback, error, reset, fork. See SessionTimelineEventType vocabulary.

​
SessionList

An array of session summary objects. Returned in SessionListEnvelope.sessions. Each entry contains at least a session ID and summary statistics.

​
SessionStatusEnvelope

The complete response shape for a session status request. All fields listed are canonical wire fields.
​
ok
boolean
required
true if the request succeeded.
​
correlationId
string
required
Opaque request identifier for tracing.
​
protocol
object
required
Protocol negotiation envelope with protocol_version and optional capabilities.
​
sessionId
string
Opaque identifier for the session. Treat as a string; do not parse its structure.
​
userId
string
Identifier of the user who owns the session.
​
intent
object
The intent that initiated the session. Contains verb, target, and domain.
​
status
SessionStatus
Current lifecycle state of the session. See SessionStatus above.
​
progress
object
Step-level progress counters. Contains:
  • done (number) — steps completed
  • failed (number) — steps that failed
  • pending (number) — steps not yet started
​
nextStep
object | null
The next pending step, or null if the session has no pending steps. Contains id and status.
​
summary
SessionSummary
Aggregate run statistics for the session.
​
error
object | null
null on success. On failure, a ProtocolError object.

​
SessionTimelineEnvelope

The complete response shape for a session timeline request.
​
ok
boolean
required
true if the request succeeded.
​
correlationId
string
required
Opaque request identifier for tracing.
​
protocol
object
required
Protocol negotiation envelope.
​
sessionId
string
Opaque session identifier.
​
userId
string
Identifier of the user who owns the session.
​
timeline
SessionTimeline
Ordered array of SessionTimelineEvent objects. See SessionTimeline.
​
summary
object
Aggregate session statistics. Equivalent to SessionSummary but updatedAt may be omitted.
​
error
object | null
null on success. On failure, a ProtocolError object.

​
SessionListEnvelope

​
ok
boolean
required
true if the request succeeded.
​
correlationId
string
required
Opaque request identifier for tracing.
​
protocol
object
required
Protocol negotiation envelope.
​
sessions
array
Array of session objects. Each entry includes at minimum a session ID and summary statistics.
​
error
object | null
null on success. On failure, a ProtocolError object.

​
SessionTimelineEventType vocabulary

Session timeline events use a closed vocabulary. Implementations MUST NOT emit types outside this list (WG-03).
TypeMeaning
executionA full solve run completed within the session
stepA single plan step executed within a run
fallbackA fallback artifact or strategy was used
errorAn error occurred during the run or step
resetThe session state was reset
forkThe session branched into a new sub-context
New types MAY be added in minor releases only when existing clients can safely ignore them.

​
JSON examples

​
Session status response

{
  "ok": true,
  "correlationId": "req_456",
  "protocol": {
    "protocol_version": "1.1",
    "capabilities": ["sessions"]
  },
  "sessionId": "session_abc123",
  "userId": "user_123",
  "intent": {
    "verb": "deploy",
    "target": "api",
    "domain": "engineering"
  },
  "status": "active",
  "progress": {
    "done": 2,
    "failed": 0,
    "pending": 0
  },
  "nextStep": {
    "id": "step_3",
    "status": "pending"
  },
  "summary": {
    "runCount": 4,
    "successCount": 3,
    "avgImprovement": 0.17,
    "lastArtifactId": "artifact_42",
    "updatedAt": "2026-04-02T12:00:00.000Z"
  },
  "error": null
}

​
Session timeline response

{
  "ok": true,
  "correlationId": "req_789",
  "protocol": {
    "protocol_version": "1.1",
    "capabilities": ["sessions"]
  },
  "sessionId": "session_abc123",
  "userId": "user_123",
  "timeline": [
    {
      "type": "execution",
      "artifactId": "artifact_42",
      "success": true,
      "timestamp": 1775131199000,
      "metadata": {
        "improvement": 0.24
      }
    },
    {
      "type": "step",
      "artifactId": "artifact_42",
      "stepId": "step_2",
      "success": true,
      "timestamp": 1775131200000,
      "metadata": {
        "reason": "execute plan"
      }
    }
  ],
  "summary": {
    "runCount": 4,
    "successCount": 3,
    "avgImprovement": 0.17,
    "lastArtifactId": "artifact_42"
  },
  "error": null
}