Documentation
¶
Overview ¶
Package runs provides typed access to daemon-managed Compozy runs while preserving the public run-reader API.
Index ¶
- Variables
- func WatchRemote(ctx context.Context, client RemoteStreamClient, runID string) (<-chan events.Event, <-chan error)
- func WatchWorkspace(ctx context.Context, workspaceRoot string) (<-chan RunEvent, <-chan error)
- type ListOptions
- type RemoteCursor
- type RemoteRunSnapshot
- type RemoteRunStream
- type RemoteRunStreamItem
- type RemoteStreamClient
- type Run
- type RunEvent
- type RunEventKind
- type RunSummary
- type SchemaVersionError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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 = 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 ¶
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 ¶
ListOptions filters the runs returned by List.
type RemoteCursor ¶ added in v0.2.0
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 ¶
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 ¶
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) Tail ¶
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.