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 ¶
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`.
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 ¶
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 (*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 ¶
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 ¶
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 ¶
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).