Documentation
¶
Overview ¶
Package replay is the read-only walker over a session's durable journal. Given a session ID and the engine's session root directory, it reconstructs every event the session dispatched and rebuilds scene state at any seq. Replay does not re-run agents or tools — reconstruction is deterministic from the journals.
Use cases:
- Debugging: a user reports an issue with a session; replay reconstructs the event sequence so an operator can read what happened.
- Audit: walk the causation DAG to verify what a session did.
- Time-travel: reconstruct scene state at an earlier point.
- Branch and fork: replay to a point, then continue from there with a new agent message (the engine's existing rewind primitive consumes the DAG produced here).
Index ¶
Constants ¶
const ScenePluginID = "nexus.scene"
ScenePluginID is the plugin ID whose data dir holds the scene patch journal. Hard-coded because the replay primitive does not have access to the live plugin registry.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
Seq uint64 `json:"seq"`
ParentSeq uint64 `json:"parent_seq,omitempty"`
ParentID string `json:"parent_id,omitempty"`
EventID string `json:"event_id,omitempty"`
Type string `json:"type"`
AgentID string `json:"agent_id,omitempty"`
Depth int `json:"depth,omitempty"`
Vetoed bool `json:"vetoed,omitempty"`
Payload any `json:"payload,omitempty"`
}
Event is one node in the reconstructed causation DAG. Mirrors the journal Envelope with the fields callers walk explicitly.
type Options ¶
type Options struct {
// SessionsRoot is the engine's session root (typically ~/.nexus/sessions).
SessionsRoot string
// AtSeq limits reconstruction to events with Seq <= AtSeq. Zero means
// "to the end of the journal".
AtSeq uint64
// IncludeVetoed controls whether vetoed before:* envelopes appear in
// the returned Events slice. Defaults to true; set false for clean
// audit reports.
IncludeVetoed bool
}
Options configure a replay walk.
type Replay ¶
type Replay struct {
SessionID string `json:"session_id"`
Events []Event `json:"events"`
Scenes []SceneSnap `json:"scenes"`
LastSeq uint64 `json:"last_seq"`
}
Replay is the materialized reconstruction returned to callers.
func Session ¶
Session reads sessionID's journal and produces a full Replay. Returns an error when the session directory or journal cannot be opened.
func (Replay) ByAgent ¶
ByAgent returns events whose AgentID matches. Sub-agent invocations carry their own AgentID per the causation contract, so this is the easiest way to scope a replay to a single specialist's work.