cassette

package
v0.10.13 Latest Latest
Warning

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

Go to latest
Published: May 7, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package cassette records and replays versioned direct-PTY evidence.

Index

Constants

View Source
const (
	Version = 1

	ManifestFile      = "manifest.json"
	InputFile         = "input.jsonl"
	OutputRawFile     = "output.raw"
	OutputEventsFile  = "output.jsonl"
	FramesFile        = "frames.jsonl"
	ServiceEventsFile = "service-events.jsonl"
	FinalFile         = "final.json"
	QuotaFile         = "quota.json"
	DiscoveryFile     = "discovery.json"
	ScrubReportFile   = "scrub-report.json"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Clock

type Clock interface {
	Now() time.Time
	Since(time.Time) time.Duration
}

type Command

type Command struct {
	Argv           []string `json:"argv,omitempty"`
	WorkdirPolicy  string   `json:"workdir_policy"`
	EnvAllowlist   []string `json:"env_allowlist,omitempty"`
	TimeoutMS      int64    `json:"timeout_ms,omitempty"`
	PermissionMode string   `json:"permission_mode,omitempty"`
}

type ContentDigest

type ContentDigest struct {
	SHA256 string `json:"sha256"`
}

type DiscoveryRecord

type DiscoveryRecord struct {
	Source            string         `json:"source"`
	Status            string         `json:"status"`
	Models            []string       `json:"models,omitempty"`
	ReasoningLevels   []string       `json:"reasoning_levels,omitempty"`
	CapturedAt        string         `json:"captured_at,omitempty"`
	FreshnessWindow   string         `json:"freshness_window,omitempty"`
	StalenessBehavior string         `json:"staleness_behavior,omitempty"`
	Metadata          map[string]any `json:"metadata,omitempty"`
}

DiscoveryRecord stores harness capability evidence captured from a live PTY or a documented CLI surface and replayed by tests without credentials.

type Emulator

type Emulator struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type Event

type Event struct {
	Seq     uint64
	TMS     int64
	Kind    EventKind
	Input   *InputRecord
	Output  *OutputRecord
	Frame   *FrameRecord
	Service *ServiceEventRecord
	Final   *FinalRecord
}

type EventKind

type EventKind string
const (
	EventInput        EventKind = "input"
	EventOutput       EventKind = "output"
	EventFrame        EventKind = "frame"
	EventServiceEvent EventKind = "service-event"
	EventFinal        EventKind = "final"
)

type FinalRecord

type FinalRecord struct {
	Timed
	Exit           *session.ExitStatus `json:"exit,omitempty"`
	DurationMS     int64               `json:"duration_ms"`
	Metadata       map[string]any      `json:"metadata,omitempty"`
	Usage          map[string]any      `json:"usage,omitempty"`
	CostUSD        float64             `json:"cost_usd,omitempty"`
	RoutingActual  string              `json:"routing_actual,omitempty"`
	SessionLogPath string              `json:"session_log_path,omitempty"`
	FinalText      string              `json:"final_text,omitempty"`
}

type FrameRecord

type FrameRecord struct {
	Timed
	Size         terminal.Size     `json:"size"`
	Text         []string          `json:"text"`
	Cells        [][]terminal.Cell `json:"cells,omitempty"`
	Cursor       terminal.Cursor   `json:"cursor"`
	Title        string            `json:"title,omitempty"`
	RawStart     int64             `json:"raw_start"`
	RawEnd       int64             `json:"raw_end"`
	ParserOffset int64             `json:"parser_offset"`
}

type Harness

type Harness struct {
	Name                string         `json:"name"`
	BinaryPathDigestSHA string         `json:"binary_path_digest_sha256,omitempty"`
	BinaryVersion       string         `json:"binary_version,omitempty"`
	Capability          map[string]any `json:"capability,omitempty"`
	AccountClass        string         `json:"account_class,omitempty"`
	CapturedAt          string         `json:"captured_at,omitempty"`
	FreshnessWindow     string         `json:"freshness_window,omitempty"`
}

type InputRecord

type InputRecord struct {
	Timed
	Kind   session.EventKind `json:"kind"`
	Bytes  []byte            `json:"bytes,omitempty"`
	Key    session.Key       `json:"key,omitempty"`
	Size   *session.Size     `json:"size,omitempty"`
	Signal string            `json:"signal,omitempty"`
}

type Manifest

type Manifest struct {
	Version          int            `json:"version"`
	ID               string         `json:"id"`
	ContentDigest    ContentDigest  `json:"content_digest"`
	Harness          Harness        `json:"harness"`
	Command          Command        `json:"command"`
	Terminal         Terminal       `json:"terminal"`
	Timing           Timing         `json:"timing"`
	Provenance       Provenance     `json:"provenance"`
	RequiredFeatures []string       `json:"required_features,omitempty"`
	Optional         map[string]any `json:"optional,omitempty"`
}

type OpenOption

type OpenOption func(*openConfig)

func WithExpectedBinding

func WithExpectedBinding(id, sha256 string) OpenOption

func WithRequiredEmulator

func WithRequiredEmulator(emulator Emulator) OpenOption

type OutputRecord

type OutputRecord struct {
	Timed
	Offset int64  `json:"offset"`
	Length int64  `json:"length"`
	SHA256 string `json:"sha256,omitempty"`
}

type Provenance

type Provenance struct {
	GitSHA          string `json:"git_sha,omitempty"`
	ContractVersion string `json:"contract_version,omitempty"`
	OS              string `json:"os"`
	Arch            string `json:"arch"`
	RecordedAt      string `json:"recorded_at"`
	RecorderVersion string `json:"recorder_version"`
}

type QuotaRecord

type QuotaRecord struct {
	Source            string           `json:"source"`
	Status            string           `json:"status"`
	CapturedAt        string           `json:"captured_at,omitempty"`
	FreshnessWindow   string           `json:"freshness_window,omitempty"`
	StalenessBehavior string           `json:"staleness_behavior,omitempty"`
	AccountClass      string           `json:"account_class,omitempty"`
	Windows           []map[string]any `json:"windows,omitempty"`
	Metadata          map[string]any   `json:"metadata,omitempty"`
}

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

func Open

func Open(dir string, opts ...OpenOption) (*Reader, error)

func (*Reader) Discovery

func (r *Reader) Discovery() *DiscoveryRecord

func (*Reader) Events

func (r *Reader) Events() ([]Event, error)

func (*Reader) Final

func (r *Reader) Final() FinalRecord

func (*Reader) Frames

func (r *Reader) Frames() []FrameRecord

func (*Reader) Inputs

func (r *Reader) Inputs() []InputRecord

func (*Reader) Manifest

func (r *Reader) Manifest() Manifest

func (*Reader) OutputBytes

func (r *Reader) OutputBytes(rec OutputRecord) ([]byte, error)

func (*Reader) OutputChunks

func (r *Reader) OutputChunks() []OutputRecord

func (*Reader) Quota

func (r *Reader) Quota() *QuotaRecord

func (*Reader) RawOutput

func (r *Reader) RawOutput() []byte

func (*Reader) Replay

func (r *Reader) Replay(ctx context.Context, opts ReplayOptions, sink func(Event) error) error

func (*Reader) ScrubReport

func (r *Reader) ScrubReport() ScrubReport

func (*Reader) ServiceEvents

func (r *Reader) ServiceEvents() []ServiceEventRecord

type RecordLock

type RecordLock struct {
	// contains filtered or unexported fields
}

func AcquireRecordLock

func AcquireRecordLock(root, account string) (*RecordLock, error)

func (*RecordLock) Release

func (l *RecordLock) Release() error

type Recorder

type Recorder struct {
	// contains filtered or unexported fields
}

func Create

func Create(dir string, manifest Manifest, opts ...RecorderOption) (*Recorder, error)

func (*Recorder) Close

func (r *Recorder) Close() error

func (*Recorder) Manifest

func (r *Recorder) Manifest() Manifest

func (*Recorder) RecordFinal

func (r *Recorder) RecordFinal(final FinalRecord) error

func (*Recorder) RecordFrame

func (r *Recorder) RecordFrame(frame terminal.Frame) (FrameRecord, error)

func (*Recorder) RecordInput

func (r *Recorder) RecordInput(kind session.EventKind, b []byte, key session.Key, size *session.Size, signal string) (InputRecord, error)

func (*Recorder) RecordOutput

func (r *Recorder) RecordOutput(chunk session.OutputChunk) (OutputRecord, error)

func (*Recorder) RecordServiceEvent

func (r *Recorder) RecordServiceEvent(payload any) (ServiceEventRecord, error)

func (*Recorder) RecordSessionEvent

func (r *Recorder) RecordSessionEvent(ev session.Event) error

func (*Recorder) WriteDiscovery

func (r *Recorder) WriteDiscovery(discovery DiscoveryRecord) error

func (*Recorder) WriteQuota

func (r *Recorder) WriteQuota(quota QuotaRecord) error

func (*Recorder) WriteScrubReport

func (r *Recorder) WriteScrubReport(report ScrubReport) error

type RecorderOption

type RecorderOption func(*recorderConfig)

func WithClock

func WithClock(clock Clock) RecorderOption

type ReplayMode

type ReplayMode string
const (
	ReplayRealtime  ReplayMode = "realtime"
	ReplayScaled    ReplayMode = "scaled"
	ReplayCollapsed ReplayMode = "collapsed"
)

type ReplayOptions

type ReplayOptions struct {
	Mode    ReplayMode
	Scale   float64
	Sleeper Sleeper
}

type ScrubReport

type ScrubReport struct {
	Status                 string         `json:"status"`
	Rules                  []string       `json:"rules"`
	HitCounts              map[string]int `json:"hit_counts"`
	EnvAllowlist           []string       `json:"env_allowlist,omitempty"`
	IntentionallyPreserved []string       `json:"intentionally_preserved,omitempty"`
}

type Scrubber

type Scrubber struct {
	Home                   string
	Worktree               string
	EnvAllowlist           []string
	AccountIdentifiers     []string
	IntentionallyPreserved []string
	// contains filtered or unexported fields
}

func NewScrubber

func NewScrubber(cfg Scrubber) *Scrubber

func (*Scrubber) NormalizeVolatile

func (s *Scrubber) NormalizeVolatile(input string) string

func (*Scrubber) ScrubEnv

func (s *Scrubber) ScrubEnv(env map[string]string) (map[string]string, ScrubReport)

func (*Scrubber) ScrubString

func (s *Scrubber) ScrubString(input string) (string, ScrubReport)

type ServiceEventRecord

type ServiceEventRecord struct {
	Timed
	Payload json.RawMessage `json:"payload"`
}

type Sleeper

type Sleeper interface {
	Sleep(context.Context, time.Duration) error
}

type Terminal

type Terminal struct {
	InitialRows int            `json:"initial_rows"`
	InitialCols int            `json:"initial_cols"`
	Locale      string         `json:"locale,omitempty"`
	Term        string         `json:"term,omitempty"`
	PTYMode     map[string]any `json:"pty_mode,omitempty"`
	Emulator    Emulator       `json:"emulator"`
}

type Timed

type Timed struct {
	Seq uint64 `json:"seq"`
	TMS int64  `json:"t_ms"`
}

type Timing

type Timing struct {
	ResolutionMS  int64      `json:"resolution_ms"`
	ClockPolicy   string     `json:"clock_policy"`
	ReplayDefault ReplayMode `json:"replay_default"`
}

Jump to

Keyboard shortcuts

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