runs

package
v0.2.7 Latest Latest
Warning

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

Go to latest
Published: May 27, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package runs provides typed access to daemon-managed Compozy runs while preserving the public run-reader API.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// ErrIncompatibleSchemaVersion reports an event schema the reader cannot decode.
	ErrIncompatibleSchemaVersion = errors.New("runs: incompatible schema version")
	// ErrPartialEventLine reports a truncated final JSON line in events.jsonl.
	ErrPartialEventLine = errors.New("runs: partial final event line")
	// ErrDaemonUnavailable reports that the public reader could not reach a ready daemon.
	ErrDaemonUnavailable = errors.New("runs: daemon unavailable")
)

Functions

func WatchRemote added in v0.2.0

func WatchRemote(ctx context.Context, client RemoteStreamClient, runID string) (<-chan events.Event, <-chan error)

WatchRemote follows one daemon-backed run stream with cursor resume semantics.

func WatchWorkspace

func WatchWorkspace(ctx context.Context, workspaceRoot string) (<-chan RunEvent, <-chan error)

WatchWorkspace emits RunEvent notifications for daemon-managed runs in workspaceRoot.

Example
previous := resolveRunsDaemonReader
resolveRunsDaemonReader = func() (daemonRunReader, error) {
	return &stubDaemonRunReader{
		listSummaries: [][]RunSummary{
			nil,
			{{
				RunID:     "run-created",
				Status:    "running",
				StartedAt: time.Date(2026, 4, 6, 12, 0, 0, 0, time.UTC),
			}},
		},
	}, nil
}
defer func() { resolveRunsDaemonReader = previous }()

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

eventsCh, errsCh := WatchWorkspace(ctx, "/workspace")
event := mustReadExampleRunEvent(eventsCh, errsCh)
fmt.Printf("%s %s %s\n", event.Kind, event.RunID, event.Summary.Status)
Output:
created run-created running

Types

type ListOptions

type ListOptions struct {
	Status []string
	Mode   []string
	Since  time.Time
	Until  time.Time
	Limit  int
}

ListOptions filters the runs returned by List.

type RemoteCursor added in v0.2.0

type RemoteCursor struct {
	Timestamp time.Time
	Sequence  uint64
}

RemoteCursor is the package-local cursor shape used by daemon-backed readers.

type RemoteRunSnapshot added in v0.2.0

type RemoteRunSnapshot struct {
	Status            string
	Incomplete        bool
	IncompleteReasons []string
	NextCursor        *RemoteCursor
}

RemoteRunSnapshot is the minimal snapshot state needed to decide whether a watch should reconnect after EOF.

type RemoteRunStream added in v0.2.0

type RemoteRunStream interface {
	Items() <-chan RemoteRunStreamItem
	Errors() <-chan error
	Close() error
}

RemoteRunStream is the minimal replay-plus-live stream contract required by WatchRemote.

type RemoteRunStreamItem added in v0.2.0

type RemoteRunStreamItem struct {
	Event           *events.Event
	Snapshot        *RemoteRunSnapshot
	HeartbeatCursor *RemoteCursor
	OverflowCursor  *RemoteCursor
}

RemoteRunStreamItem is one parsed stream delivery from a daemon-backed watch.

type RemoteStreamClient added in v0.2.0

type RemoteStreamClient interface {
	GetRunSnapshot(context.Context, string) (RemoteRunSnapshot, error)
	OpenRunStream(context.Context, string, RemoteCursor) (RemoteRunStream, error)
}

RemoteStreamClient is the package-local daemon observation surface.

type Run

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

Run is a handle over one daemon-backed run reader.

func Open

func Open(workspaceRoot, runID string) (*Run, error)

Open loads one run and prepares replay access through the daemon transport.

Example
previous := resolveRunsDaemonReader
resolveRunsDaemonReader = func() (daemonRunReader, error) {
	return &stubDaemonRunReader{
		openSummary: RunSummary{
			RunID:  "run-open",
			Mode:   "exec",
			Status: "completed",
		},
	}, nil
}
defer func() { resolveRunsDaemonReader = previous }()

run, err := Open("/workspace", "run-open")
if err != nil {
	panic(err)
}

summary := run.Summary()
fmt.Printf("%s %s %s\n", summary.RunID, summary.Mode, summary.Status)
Output:
run-open exec completed

func (*Run) Replay

func (r *Run) Replay(fromSeq uint64) iter.Seq2[events.Event, error]

Replay yields all persisted events from fromSeq forward through the daemon-backed event page API.

Example
previous := resolveRunsDaemonReader
resolveRunsDaemonReader = func() (daemonRunReader, error) {
	return &stubDaemonRunReader{
		openSummary: RunSummary{RunID: "run-replay"},
		eventPages: []remoteRunEventPage{{
			Events: []events.Event{
				exampleEvent("run-replay", 1, events.EventKindRunStarted),
				exampleEvent("run-replay", 2, events.EventKindJobCompleted),
				exampleEvent("run-replay", 3, events.EventKindRunCompleted),
			},
		}},
	}, nil
}
defer func() { resolveRunsDaemonReader = previous }()

run, err := Open("/workspace", "run-replay")
if err != nil {
	panic(err)
}

for event, replayErr := range run.Replay(2) {
	if replayErr != nil {
		panic(replayErr)
	}
	fmt.Printf("%d %s\n", event.Seq, event.Kind)
}
Output:
2 job.completed
3 run.completed

func (*Run) Summary

func (r *Run) Summary() RunSummary

Summary returns the loaded run metadata.

func (*Run) Tail

func (r *Run) Tail(ctx context.Context, fromSeq uint64) (<-chan events.Event, <-chan error)

Tail replays historical events from fromSeq and then follows the daemon stream for new events until ctx is canceled.

Example
previous := resolveRunsDaemonReader
resolveRunsDaemonReader = func() (daemonRunReader, error) {
	now := time.Date(2026, 4, 6, 12, 0, 0, 0, time.UTC)
	return &stubDaemonRunReader{
		openSummary: RunSummary{RunID: "run-tail"},
		snapshot: RemoteRunSnapshot{
			Status:     publicRunStatusRunning,
			NextCursor: remoteCursor(now, 1),
		},
		eventPages: []remoteRunEventPage{{
			Events: []events.Event{
				exampleEvent("run-tail", 1, events.EventKindRunStarted),
			},
			NextCursor: remoteCursor(now, 1),
		}},
		streams: []RemoteRunStream{
			newBufferedRemoteRunStream(
				RemoteRunStreamItem{Event: &events.Event{
					SchemaVersion: events.SchemaVersion,
					RunID:         "run-tail",
					Seq:           2,
					Timestamp:     now.Add(time.Second),
					Kind:          events.EventKindRunCompleted,
				}},
			),
		},
	}, nil
}
defer func() { resolveRunsDaemonReader = previous }()

run, err := Open("/workspace", "run-tail")
if err != nil {
	panic(err)
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

eventsCh, errsCh := run.Tail(ctx, 2)
event := mustReadExampleTailEvent(eventsCh, errsCh)
fmt.Printf("%d %s\n", event.Seq, event.Kind)
Output:
2 run.completed

type RunEvent

type RunEvent struct {
	Kind    RunEventKind
	RunID   string
	Summary *RunSummary
}

RunEvent reports workspace-level run lifecycle changes.

type RunEventKind

type RunEventKind string

RunEventKind identifies the type of workspace run event.

const (
	// RunEventCreated reports a newly observed run.
	RunEventCreated RunEventKind = "created"
	// RunEventStatusChanged reports a run whose status changed.
	RunEventStatusChanged RunEventKind = "status_changed"
	// RunEventRemoved reports a removed run directory.
	RunEventRemoved RunEventKind = "removed"
)

type RunSummary

type RunSummary struct {
	RunID         string
	ParentRunID   string
	Status        string
	Mode          string
	IDE           string
	Model         string
	WorkspaceRoot string
	StartedAt     time.Time
	EndedAt       *time.Time
	ArtifactsDir  string
}

RunSummary is the public metadata view for one persisted run.

func List

func List(workspaceRoot string, opts ListOptions) ([]RunSummary, error)

List enumerates daemon-managed runs for the supplied workspace root.

Example
previous := resolveRunsDaemonReader
resolveRunsDaemonReader = func() (daemonRunReader, error) {
	return &stubDaemonRunReader{
		listSummaries: [][]RunSummary{{
			{
				RunID:     "run-early",
				Status:    "failed",
				StartedAt: time.Date(2026, 4, 6, 12, 0, 0, 0, time.UTC),
			},
			{
				RunID:     "run-late",
				Status:    "completed",
				StartedAt: time.Date(2026, 4, 6, 13, 0, 0, 0, time.UTC),
			},
		}},
	}, nil
}
defer func() { resolveRunsDaemonReader = previous }()

summaries, err := List("/workspace", ListOptions{})
if err != nil {
	panic(err)
}
for index := range summaries {
	fmt.Printf("%s %s\n", summaries[index].RunID, summaries[index].Status)
}
Output:
run-late completed
run-early failed

type SchemaVersionError

type SchemaVersionError struct {
	Version string
}

SchemaVersionError reports an unsupported event schema version.

func (*SchemaVersionError) Error

func (e *SchemaVersionError) Error() string

Error implements the error interface.

func (*SchemaVersionError) Unwrap

func (e *SchemaVersionError) Unwrap() error

Unwrap exposes the sentinel error for errors.Is checks.

Directories

Path Synopsis
Package layout exports the compatibility on-disk layout for one persisted Compozy run.
Package layout exports the compatibility on-disk layout for one persisted Compozy run.

Jump to

Keyboard shortcuts

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