worktrace

package
v0.0.0-...-86254be Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package worktrace exposes the `workTrace` DSL/SDK builtin -- the history-over-gRPC contract a remote client (the memql-cockpit CLI) calls to fetch a run's full execution timeline (issue memql-cockpit#142; re-keyed onto the work journal by the work spine's epic A1).

Why this exists: the trace assembler (#589) reconstructs a run's timeline from the append-only graph event stream, but it was only reachable in-process. This integration is the remote half: it wraps NewTraceReader behind an @sdk builtin so the cockpit can call it through the typed Go SDK like any other engine query -- no bespoke wire wrapper, no raw DSL string.

The assembler it wraps used to live in component/harness and moved here with the harness retirement, re-pointed from v1:harness:plan/step/ observation to the work journal's v1:work:run/step/observation. The SHAPE of what it returns is unchanged, so the cockpit's decoder still reads it -- only the arg name moved, planId to runId.

DSL surface (dsl/memory/builtins.memql -> builtin workTrace):

workTrace(runId: "v1:work:run:...")

Returns a SINGLE synthetic node whose JSON payload carries:

{
  "runId":     "<the requested run id>",
  "timeline":  "<tr.Render() -- the human-readable timeline>",
  "complete":  <bool -- tr.IsComplete(), the run reached a terminal status>,
  "stepCount": <int -- len(tr.Steps)>
}

OWNER-SCOPING IS UPSTREAM, AND THE READER IS DELIBERATELY NOT SCOPED. v1:work:run and v1:work:step declare the composite owner tier, but the reader goes to raw SQL by run id -- because a TRACE with holes does not read as "rows were withheld", it reads as "this never happened", which is a worse failure than disclosure for an audit surface. The same reasoning is recorded per-query in reader.go under the staged-data ruling. We resolve the calling actor here and log it for the audit trail; narrowing the read itself is an owner decision that belongs with the surface that exposes traces to more than their own owner.

Index

Constants

View Source
const (
	// RunStatusRunning is a run in flight.
	RunStatusRunning = "running"
	// RunStatusSucceeded is the run's successful terminal status. The
	// harness plan spelled this `done`; ComputeMetrics keys Success on it.
	RunStatusSucceeded = "succeeded"
	// RunStatusFailed is a run that ended on a step failure.
	RunStatusFailed = "failed"
	// RunStatusCancelled is a run stopped by a person or by context cancel.
	RunStatusCancelled = "cancelled"
)

status.go names the run and step statuses the timeline reads, so the assembler and the metrics do not compare against bare literals.

These are the WORK JOURNAL's vocabulary (dsl/work/concepts.memql), not the harness one this package's assembler came from. The mapping is why the port needed reading rather than renaming:

harness plan  open / running / done / failed  ->  run  running / succeeded / failed / cancelled
harness step  pending / ready / running / done / failed / blocked
                                              ->  step pending / ready / running / waiting /
                                                       done / failed / skipped / cancelled

`done` and `failed` survived on the step, which is what let the metrics rollup port unchanged; `succeeded` is the run's terminal, where the harness plan said `done`.

View Source
const (
	// StepStatusPending is a step not yet reached.
	StepStatusPending = "pending"
	// StepStatusReady is a step whose dependencies are met.
	StepStatusReady = "ready"
	// StepStatusRunning is the INTENT version, written before the body runs.
	// ReplaySequence keys on it: the order steps first reached running IS
	// the dispatch order a replay reproduces.
	StepStatusRunning = "running"
	// StepStatusDone is the receipt of a step that succeeded.
	StepStatusDone = "done"
	// StepStatusFailed is the receipt of a step that failed.
	StepStatusFailed = "failed"
	// StepStatusSkipped is a step whose condition decided it would not run.
	// It has no intent version, because nothing was intended.
	StepStatusSkipped = "skipped"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type EventKind

type EventKind string

EventKind classifies a timeline entry by which concept produced it.

const (
	// EventKindRun is a v1:work:run version transition (create / start /
	// complete / fail / cancel).
	EventKindRun EventKind = "run"
	// EventKindStep is a v1:work:step version transition (running ->
	// done / failed / skipped).
	EventKindStep EventKind = "step"
	// EventKindObservation is a v1:work:observation (tool_result / error /
	// note / decision).
	EventKindObservation EventKind = "observation"
)

type Integration

type Integration struct {
	Logger *slog.Logger
	// contains filtered or unexported fields
}

Integration holds the state the workTrace handler needs: a lazily-resolved bun handle (the trace reader reads via bun). It is constructed by the plug-in factory and populated via SetDBGetter at registration time, mirroring integrations/harnessrecall.

func New

func New(logger *slog.Logger) *Integration

New constructs a workTrace integration.

func (*Integration) Capabilities

func (i *Integration) Capabilities() []memql.IntegrationCapability

Capabilities lists the DSL-callable functions. One capability: trace.

func (*Integration) IntegrationName

func (i *Integration) IntegrationName() string

IntegrationName implements memql.IntegrationProvider.

func (*Integration) SetDBGetter

func (i *Integration) SetDBGetter(f func() *bun.DB)

SetDBGetter injects the lazy bun handle getter. The trace assembler (NewTraceReader) takes exactly this shape, so we hand it straight through -- no adapter.

type RunMetrics

type RunMetrics struct {
	// RunID is the run these metrics describe.
	RunID string
	// FinalStatus is the run's terminal (or current) status.
	FinalStatus string
	// Success is true iff the run reached status=succeeded.
	Success bool
	// StepCount is the number of distinct steps the run introduced.
	StepCount int
	// StepsCompleted is how many steps reached done.
	StepsCompleted int
	// StepsFailed is how many steps reached failed.
	StepsFailed int
	// ToolCalls is the cumulative tool-call count summed from observation
	// data (tool_result observations and any explicit toolCalls counters).
	ToolCalls int
	// TokenCost is the cumulative token cost summed from observation data
	// (any "tokens" / "tokenCost" counter carried on a tool_result).
	TokenCost int
	// WallClock is the elapsed time from the first to the last timeline
	// event -- the run's observed duration.
	WallClock time.Duration
	// ObservationCount is the total observations recorded for the run.
	ObservationCount int
	// ErrorCount is the number of error-kind observations.
	ErrorCount int
}

RunMetrics is the per-plan rollup the eval harness scores and the cockpit surfaces. Every field is derived from the Trace.

func ComputeMetrics

func ComputeMetrics(t Trace) RunMetrics

ComputeMetrics derives RunMetrics from a Trace. It is the single source of the success / step-count / tool-call / token-cost / wall-clock numbers the eval scaffold reports, computed purely from the event stream.

type StepTimeline

type StepTimeline struct {
	StepID       string
	Title        string
	FinalStatus  string
	Transitions  []TraceEvent
	Observations []TraceEvent
}

StepTimeline is the per-step slice of a run's timeline: the step's own transitions and the observations recorded against it, already ordered.

type Trace

type Trace struct {
	// RunID is the run this trace reconstructs.
	RunID string
	// Goal is the run's goal (from the latest plan version), for headers.
	Goal string
	// FinalStatus is the run's latest status.
	FinalStatus string
	// Events is the full ordered timeline (ascending by createdAt, then a
	// stable tiebreak so equal-timestamp events render deterministically).
	Events []TraceEvent
	// Steps is the per-step rollup keyed by step id, in first-seen order.
	Steps []StepTimeline
}

Trace is a run's fully reconstructed timeline plus a small rollup.

func AssembleTrace

func AssembleTrace(runID string, events []TraceEvent) Trace

AssembleTrace folds a flat, unordered set of timeline events (one per graph node version) into an ordered Trace. This is the pure core of the trace assembler: the bun reader hands it every plan/step/observation version for a plan, and this orders + rolls them up. No DB, no clock -- just sorting and grouping, so it unit-tests with hand-built events.

Ordering: ascending createdAt is the primary key (the event stream's natural order). Ties break by kind (plan < step < observation, so a step's create sorts before its first observation when both land in the same instant), then by NodeID, then by Mutation -- giving a stable, reproducible order even when timestamps collide (common in fast tests and same-tick reconciles).

func (Trace) IsComplete

func (t Trace) IsComplete() bool

IsComplete reports whether the run reached a terminal status, so callers know the trace is final rather than a snapshot of an in-flight run.

`abandoned` counts: the run's node stopped heartbeating and the sweep closed it (epic A2 writes it). A trace of an abandoned run is as final as one of a failed run -- nothing more is coming -- and reading it as in-flight would leave a caller waiting forever.

func (Trace) Render

func (t Trace) Render() string

Render returns a human-readable rendering of the run timeline: a header (run id / goal / final status), then each event in createdAt order with its actor + mutation + content. This is the canonical text projection the cockpit CLI prints.

func (Trace) ReplaySequence

func (t Trace) ReplaySequence() []string

ReplaySequence is the ordered list of step ids in the order the run dispatched them (the order each step first transitioned to running). It is the canonical "what the run did" fingerprint that replay reproduces.

type TraceEvent

type TraceEvent struct {
	// At is the node version's createdAt -- the sole ordering key.
	At time.Time
	// Kind is which concept produced this entry.
	Kind EventKind
	// NodeID is the graph node id (plan id / step id / observation id).
	NodeID string
	// StepID is the owning step for an observation, or the step's own id for
	// a step transition. Empty for plan transitions.
	StepID string
	// Status is the step/plan status at this version (e.g. "running",
	// "done"). Empty for observations.
	Status string
	// ObservationKind is the observation kind (tool_result / error / note /
	// decision). Empty for plan/step transitions.
	ObservationKind string
	// Mutation is the mutation that named this transition (e.g.
	// "updateWorkStep"). The audit trail's verb, when the row carries one.
	Mutation string
	// Actor is createdBy -- who produced this version.
	Actor string
	// Content is the observation's embedding text, or a step/plan title/goal
	// for transitions. Free-form, render-only.
	Content string
	// ToolName is the tool that produced a tool_result observation, when the
	// observation data carries one. Empty otherwise.
	ToolName string
	// Data is the observation's structured per-kind data (named `data`, not
	// `payload`, per the #582 concept gotcha). Nil for transitions.
	Data map[string]any
}

TraceEvent is one entry on a run's reconstructed timeline. Every entry derives from exactly one graph node version, so the timeline is a faithful projection of the event stream -- nothing is synthesized.

type TraceReader

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

TraceReader assembles a run's full timeline from the graph. It is the reusable, importable surface the cockpit CLI (and eval) call.

func NewTraceReader

func NewTraceReader(db func() *bun.DB) *TraceReader

NewTraceReader builds a trace reader over a lazily-resolved bun handle (same shape as NewBunStepReader so app wiring is symmetric).

func (*TraceReader) Trace

func (r *TraceReader) Trace(ctx context.Context, runID string) (Trace, error)

Trace reconstructs the full ordered timeline for runID: every run + step version transition and every observation, ordered by createdAt. Returns an empty (non-error) trace when the run does not exist.

Jump to

Keyboard shortcuts

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