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.

ALX Protocol uses two distinct event systems that serve different purposes. Run events report real-time execution progress as a solve runs — step by step, in order, as work happens. Session timeline events are the historical record of what happened across all runs in a session, written after the fact and queryable by clients inspecting session history. Both use closed vocabularies enforced by wire-level guarantees.

​
The difference between run events and session timeline events

DimensionRun eventsSession timeline events
When emittedDuring live execution, in real timeAfter execution, as historical record
GranularityFine-grained step progressCoarser execution milestones
Vocabulary typeRunEventType (closed)SessionTimelineEventType (closed)
Wire guaranteeWG-04WG-03
TimestampsISO-8601 stringsEpoch milliseconds
Queryable after run?Not guaranteedYes, via session timeline endpoint

​
Wire-level guarantees

GuaranteeRule
WG-03Session timeline events MUST use the closed SessionTimelineEventType vocabulary
WG-04Run events MUST use the closed RunEventType vocabulary

​
Types

​
RunEventType

The closed vocabulary of run event types. Implementations MUST NOT emit types outside this list (WG-04).
TypeMeaning
run.startedExecution of the run has begun
step.startedA plan step has begun execution
step.completedA plan step completed successfully
step.failedA plan step failed
step.skippedA plan step was intentionally skipped
artifact.createdAn artifact was produced during execution
approval.requiredExecution is paused waiting for human approval
run.completedThe run finished successfully (ok: true, WG-10)
run.failedThe run finished with an error (ok: false, WG-09)

​
RunEvent

A single event emitted during live execution of a solve run.
​
type
RunEventType
required
The event type. Must be one of the values in the RunEventType closed vocabulary above.
​
payload
object
Type-specific event payload. Shape varies by type. For example, step.completed may carry { stepId, durationMs } while artifact.created carries { artifactId }. Clients MUST tolerate unknown payload fields (WG-07).

​
RunState

Represents the current state of an in-progress or completed run. Carries accumulated context as the run progresses through steps.
RunState is a protocol-level shape. Do not confuse it with SessionStatus, which tracks lifecycle state across all runs in a session.

​
SessionTimelineEventType

The closed vocabulary of session timeline event types. Implementations MUST NOT emit types outside this list (WG-03).
TypeMeaning
executionA full solve run was recorded in the session
stepA single step within a run was recorded
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

​
SessionTimelineEvent

A single entry in a session’s historical timeline.
​
type
SessionTimelineEventType
required
The event type. Must be one of the values in the SessionTimelineEventType closed vocabulary above.
​
artifactId
string
ID of the artifact associated with this event. May be omitted for events that do not involve an artifact (e.g. reset).
​
stepId
string
ID of the step associated with this event. Present for step events; omitted for execution, reset, and fork events.
​
success
boolean
Whether the event represents a successful outcome.
​
timestamp
number
required
Epoch milliseconds when the event occurred. Session timeline timestamps always use epoch milliseconds — not ISO-8601 strings (see PROTOCOL-SPEC §5).
​
metadata
object
Arbitrary key-value metadata specific to the event type. For example, an execution event may include { improvement: 0.24 } and a step event may include { reason: "execute plan" }.

​
Extension rule

New event types MAY be added in minor releases only when existing clients can ignore them without breaking correctness. This applies to both RunEventType and SessionTimelineEventType. Your client MUST be written to tolerate unknown event types gracefully. Do not error or abort a run event stream when you encounter an unrecognized type — log and skip it. 
function handleRunEvent(event: RunEvent) {
  switch (event.type) {
    case "run.started":
      // handle
      break;
    case "step.completed":
      // handle
      break;
    // ... other known types
    default:
      // Unknown type added in a minor release — ignore safely
      console.debug(`Unrecognized run event type: ${event.type}`);
  }
}
Do not hard-fail on unknown event types. ALX Protocol reserves the right to add new types in minor releases. Clients that throw on unknown types will break when the server is upgraded.

​
JSON examples

​
RunEvent

{
  "type": "step.completed",
  "payload": {
    "stepId": "step_2",
    "label": "execute plan",
    "durationMs": 342,
    "success": true
  }
}

{
  "type": "run.failed",
  "payload": {
    "error": {
      "code": "LOW_CONFIDENCE",
      "message": "Selection confidence 0.22 is below minimum 0.35."
    }
  }
}

​
SessionTimelineEvent

{
  "type": "step",
  "artifactId": "artifact_42",
  "stepId": "step_2",
  "success": true,
  "timestamp": 1775131200000,
  "metadata": {
    "reason": "execute plan"
  }
}

{
  "type": "execution",
  "artifactId": "artifact_42",
  "success": true,
  "timestamp": 1775131199000,
  "metadata": {
    "improvement": 0.24
  }
}