replay

package
v0.32.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 9 Imported by: 0

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

View Source
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

func Session(ctx context.Context, sessionID string, opts Options) (Replay, error)

Session reads sessionID's journal and produces a full Replay. Returns an error when the session directory or journal cannot be opened.

func SessionAt

func SessionAt(ctx context.Context, sessionID string, atSeq uint64, opts Options) (Replay, error)

SessionAt is a convenience that wraps Session with a non-zero AtSeq.

func (Replay) ByAgent

func (r Replay) ByAgent(agentID string) []Event

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.

func (Replay) Children

func (r Replay) Children(parentSeq uint64) []Event

Children returns the events whose ParentSeq matches the given seq. Useful when consumers want to walk the DAG node-by-node rather than scanning the flat Events slice.

func (Replay) Roots

func (r Replay) Roots() []Event

Roots returns events with no parent — typically io.session.start, io.input arrivals, and other operator-driven entry points.

type SceneSnap

type SceneSnap struct {
	Handle    scene.SceneHandle `json:"handle"`
	AtSeq     uint64            `json:"at_seq"`
	Content   any               `json:"content"`
	UpdatedAt string            `json:"updated_at,omitempty"`
}

SceneSnap is the rebuilt content of a scene at a specific point in the session's history.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL