Files
archie/internal/domain/workflow/workflow.go
T
sam 3c32b63066 feat(workflow): declared workflow outputs for wait:true callers
A workflow declares named, typed outputs beside its inputs
(task.WorkflowInterface.Outputs). A run writes each one once through a
capture tool named after the output, or from a deterministic Go stage via
TaskContext.WriteOutput; the finish write persists them on tasks.outputs
before the outcome transition. A wait:true caller receives its successful
callee's outputs through WorkflowCallStatus and publishes one as its own
through a call step's outputs assignment.

Build authority: docs/prds/workflow-call-outputs.md.

- save time: WorkflowInterface.Validate checks output names and types;
  checkCallOutputs checks a call's assignment against both declarations
  and refuses outputs over a wait:false call.
- run time: undeclared, mistyped and required-but-missing values park the
  run; published callee values are re-checked against the caller's type.
- storage/wire: tasks.outputs (goose 0024), reset by each claim so the set
  is attempt-scoped; an encoded set past the structured-payload bound is
  refused, not clipped. Task.outputs_json and
  WorkflowCallStatusResponse.outputs_json carry it; task.Caller keeps its
  two methods.
- examples: firewall-contain calls firewall-investigate and publishes its
  summary as its own output.
2026-10-02 02:09:03 +10:00

633 lines
27 KiB
Go

// Package workflow is archied's extensible pipeline engine. A Workflow
// is an ordered list of stages over a shared TaskContext; stages are
// either deterministic steps (git, gate, PR, comments) or agent stages
// (agentloop runs). New workflows compose from the shared step library --
// adding one must never require reimplementing the engine or the steps.
package workflow
import (
"context"
"fmt"
"log/slog"
"regexp"
"strings"
"time"
"unicode/utf8"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/skill"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/tools"
)
// Forger is the subset of forge.Forge that workflow stages call mid-run.
// Production reaches it through forgerpc.Client, which proxies each call to the
// daemon over NATS -- the worker holds no forge credentials, so the daemon stays
// the only caller of forge.Forge. Test fakes implement it directly.
type Forger interface {
CloseIssue(ctx context.Context, owner, repo string, number int, comment string) error
CreatePR(ctx context.Context, owner, repo, title, head, base, body string) (int, error)
LinkBranch(ctx context.Context, owner, repo string, issueNumber int, branch string) error
// CreateReviewComments posts line-anchored review comments on an open pull
// request. The whole set travels in one call because Gitea's only inline
// shape is a single submitted review holding many comments, and because
// one call cannot half-succeed against a rate limit.
//
// reviewedHeadSHA is the revision those line numbers were measured on. The
// implementation reads the pull request's head itself -- the worker holds no
// forge credentials -- and posts only while that head is still this
// revision, because a line number means nothing against a revision it was
// not measured on. Empty means "not measured": the comments post without
// the check rather than being dropped.
CreateReviewComments(ctx context.Context, owner, repo string, number int, reviewedHeadSHA string, comments []ReviewComment) error
// Comment posts a plain, non-anchored PR comment and returns its ID.
// The remediate workflow's round-cap stage uses this to tell an
// operator why it stopped remediating, and a whole-review reply (no
// single inline comment to thread onto) falls back to it.
Comment(ctx context.Context, owner, repo string, number int, body string) (int64, error)
// ReplyToReview posts a threaded reply to one review comment. The
// remediate workflow calls it once per remediation run, summarising
// what changed (docs/prds/pr-review-remediation.md decision 4).
ReplyToReview(ctx context.Context, owner, repo string, number int, commentID int64, body string) error
}
// ReviewComment is one line-anchored comment to post on an open pull
// request: the repo-relative path, the line in the reviewed revision, and
// the rendered body -- which may carry a fenced suggestion block. It names
// nothing forge-specific, so both the pr-review pipeline (prreview_stages.go)
// and the remediate workflow's callers can hand it to Forger unchanged.
type ReviewComment struct {
Path string
Line int
Body string
}
// Trees is the subset of *worktree.Manager that workflow stages call
// mid-run. *worktree.Manager (the daemon's real manager, holding the push
// token) and a hybrid RPC-backed implementation (archie-agent proxies
// Prepare/Push, runs the rest locally) both satisfy it.
type Trees interface {
Prepare(ctx context.Context, owner, repo, base string, issue int, title, body, labels string) (dir, branch string, err error)
CommitAll(ctx context.Context, dir, message string) (bool, error)
Push(ctx context.Context, dir, branch string) error
Diff(ctx context.Context, dir, base string) (string, error)
ChangedFiles(ctx context.Context, dir, base string) ([]string, error)
ChangedLines(ctx context.Context, dir, base string) (int, error)
// Snapshot exports HEAD's tracked files into destDir with no .git
// directory -- no commit history, branch name, or reflog. Used to
// build the adversarial reviewer's isolated workspace (see
// docs/prds/adversarial-self-review.md).
Snapshot(ctx context.Context, dir, destDir string) error
}
// TaskContext carries everything a stage may need. Stages communicate
// forward by mutating Task (persisted after every stage) and the
// scratch fields below.
type TaskContext struct {
Task *Task
Repo config.Repo
Cfg config.Config
Forge Forger
Store Store
Trees Trees
Agent agentexec.Runner
// Calls starts workflow.call callees and reads them back while a
// wait:true caller waits. Nil is only safe for a workflow with no
// workflow.call step: such a step in a runner with no capability
// fails the run with a named error (docs/prds/workflow-calls.md).
Calls task.Caller
// PRSource fetches a pull request under review and its head snapshot for
// the pr-review workflow (see prreview_stages.go). Nil is only safe for a
// workflow that never runs pr-review's stages: they fail the run with a
// named error rather than silently skipping, the same rule Reviewer and
// Calls follow.
PRSource PRSource
// prReview is the pr-review workflow's cross-stage scratch state (see
// prreview_stages.go). It is unexported, following the pattern set by
// the feasibility workflow's decision field: pipeline-private state has
// no business being read or set outside its own stages.
prReview *prReviewState
Bus *events.Bus // nil-safe via Emit
Log *slog.Logger
// CustomStages is retained for source compatibility only. Repository Go
// stages are no longer executed; StageRepoStages rejects their presence.
CustomStages func(dir string) ([]Stage, error)
// SkillBody is the Markdown body of the loaded SKILL.md for this
// workflow's matching skill, injected into agent context. Empty
// when no skill is found (backward compatible).
SkillBody string
// SkillPlugins holds the bundled Yaegi plugins loaded from the
// skill's plugins/ directory. Populated by loadSkillBody alongside
// SkillBody. Nil when no skill is loaded or the skill has no plugins.
SkillPlugins []skill.Plugin
// Dir/Branch are set by the prepare step.
Dir string
Branch string
// Stage is the name of the stage currently running, kept here (not
// persisted on Task -- docs/prds/execution-tree-state-machine.md drops
// tasks.stage in favour of the durable StepExecution record StartStep
// writes) purely so park/finish can tag the event they emit with it.
Stage string
// StepID is the StepExecution the engine recorded for the stage whose
// body is running: every agent call the stage makes records itself as
// this step's child. Zero outside a stage body, which is how the stage
// unit tests run their bodies.
StepID int64
// BuildSummary is the builder agent's finish summary -- the PR body.
BuildSummary string
// BuildNoChanges is set when the builder returned StatusPassed but
// made no file changes -- the fix already exists or the issue is a
// no-op. StageCommitPush closes the issue instead of erroring.
BuildNoChanges bool
// BaselineFixed is set when StageBaselineGate committed a real fix for
// a pre-existing gate failure. It gates whether the build stage is
// allowed to set BuildNoChanges: a baseline-fix commit is a real,
// gate-verified change sitting in the worktree, so even if the actual
// task needed no further work, StageCommitPush must still push and
// open a PR rather than discarding it as "no changes required".
BaselineFixed bool
// ReproProof is the captured failing-test output from a TDD repro
// stage, posted on the PR as evidence the bug was reproduced.
ReproProof string
// decision is the feasibility assess stage's verdict.
decision *decision
// reviewUnit is the remediate workflow's decoded Task.ReviewPayload,
// stashed by its build stage so the commit-push and reply stages that
// follow don't each re-decode the same JSON.
reviewUnit ReviewUnit
// Outcome describes where the task ended up; the engine applies it.
Outcome Outcome
// runInterface is the declaration the run's compiled workflow carries
// (Workflow.Interface, set by Run), so the declared-outputs pieces
// (outputs.go) read one source: the engine's own compile of the pinned
// YAML. A stage body invoked outside Run falls back to parsing the
// pinned YAML once, memoized here.
runInterface task.WorkflowInterface
runInterfaceSet bool
ifaceParsed *task.WorkflowInterface
// SystemPrompt, when non-nil, returns additional context to inject
// before the agent's mission in every agent stage request. Wired by
// the composition root (cmd/archied) from the MemoryManager.
SystemPrompt func() string
// Guardrails is the per-task guardrail engine reference. When non-nil,
// agent stages record tool successes and failures for guardrail
// enforcement. Wired by the composition root from the daemon.
Guardrails *tools.GuardrailEngine
// RunUsage accumulates every agent run's token breakdown (prompt,
// completion, cached) for this workflow execution. It is presentation
// scratch, not persisted -- Task.TokensUsed remains the durable,
// authoritative total. It exists so PR bodies can show how much of the
// reported prompt-token sum was cache hits (billed at a steep discount)
// rather than fresh, full-price tokens; see formatTokenUsage.
RunUsage agentexec.Usage
}
// Emit publishes an observability event stamped with the task's
// identity and the attempt that produced it. Safe on a nil bus.
//
// The attempt comes from the task record this context runs against, so a
// reader can attribute the event to one run without segmenting the task's
// stream by stage order. It is never guessed: a producer with no attempt
// (the deliberately task-agnostic daemon events) leaves it zero, which reads
// as unattributed rather than as a first run.
func (tc *TaskContext) Emit(kind, stage, detail string, data map[string]any) {
if tc.Bus == nil {
return
}
tc.Bus.Publish(events.Event{
Kind: kind,
TaskID: tc.Task.ID,
Repo: tc.Task.Owner + "/" + tc.Task.Repo,
Issue: tc.Task.IssueNumber,
Workflow: tc.Task.Workflow,
Attempt: tc.Task.Attempt,
Stage: stage,
Detail: detail,
Data: data,
})
}
// EmitDurable persists evaluation-critical telemetry before publishing it to
// the lossy live bus. The assigned ID tells the daemon sink to broadcast
// without inserting a duplicate row.
func (tc *TaskContext) EmitDurable(ctx context.Context, kind, stage, detail string, data map[string]any) error {
if tc.Store == nil {
tc.Emit(kind, stage, detail, data)
return nil
}
event := events.Event{
At: time.Now().UTC(), Kind: kind, TaskID: tc.Task.ID, Repo: tc.Task.Owner + "/" + tc.Task.Repo,
Issue: tc.Task.IssueNumber, Workflow: tc.Task.Workflow, Attempt: tc.Task.Attempt,
Stage: stage, Detail: detail, Data: data,
}
id, err := tc.Store.InsertEvent(ctx, event)
if err != nil {
return err
}
event.ID = id
if tc.Bus != nil {
tc.Bus.Publish(event)
}
return nil
}
// toolCallReporter builds the agentexec.ToolCallReporter an agent stage
// passes to tc.Agent.Run, so every completed tool call during that run
// surfaces as a tool_call event on the task timeline (archie-core-467's
// task-transcript counterpart -- the interactive chat gateway has its own,
// separate ToolCallEvent). Safe to call on a nil Bus: Emit no-ops.
func (tc *TaskContext) toolCallReporter(stage string) agentexec.ToolCallReporter {
return func(report agentexec.ToolCallReport) {
tc.Emit(events.KindToolCall, stage, report.Detail, map[string]any{
"tool": report.Tool,
"failed": report.Failed,
})
}
}
// Outcome is a stage's terminal decision for the whole workflow. Stages
// that don't end the workflow leave it zero.
type Outcome struct {
Status string // Status* value; empty = continue to next stage
Detail string // park reason / close rationale / PR body context
}
// Stage is one named step. Returning an error parks the task with the
// error text; setting ctx.Outcome ends the workflow with that status.
type Stage struct {
Name string
Run func(ctx context.Context, tc *TaskContext) error
}
// Workflow is a named, ordered stage list.
type Workflow struct {
Name string
Stages []Stage
// Interface declares this workflow's inputs, repository mode and agent
// profile to whatever starts it -- a binding's CheckWorkflow reads it the
// same way it reads a YAML-defined workflow's WorkflowInterface. Zero
// value (no declared inputs) is the default every builtin had before
// pr-review's triggers needed one; ShippedDefinitions only emits an
// inputs: block when this is non-empty, so every other builtin's
// generated YAML is byte-identical to before.
Interface task.WorkflowInterface
}
// Registry maps workflow names to definitions.
type Registry map[string]Workflow
// Route picks the workflow for a task. A pre-assigned workflow wins
// (the waiting_human → approved handoff requeues under "implement");
// otherwise labels decide, then the default.
func Route(t *Task, reg Registry) Workflow {
if t.Workflow != "" {
if wf, ok := reg[t.Workflow]; ok {
return wf
}
return Workflow{Name: "none", Stages: []Stage{{
Name: "fail",
Run: func(context.Context, *TaskContext) error {
return fmt.Errorf("requested workflow %q is unavailable", t.Workflow)
},
}}}
}
if wf, ok := workflowForLabels(reg, t.Labels); ok {
return wf
}
// No explicit workflow, no label match: a labelled task already has a
// free, reliable signal and never reaches here. Everything else --
// overwhelmingly chat-spawned tasks, which rarely carry labels -- gets
// classified by triage instead of defaulting straight to the heaviest
// workflow. See docs/prds/dynamic-workflow-triage.md.
if wf, ok := reg["triage"]; ok {
return wf
}
if wf, ok := reg["implement"]; ok {
return wf
}
if wf, ok := reg["default"]; ok {
return wf
}
// Registry always ships a default; this is a config error backstop.
return Workflow{Name: "none", Stages: []Stage{{
Name: "fail",
Run: func(context.Context, *TaskContext) error {
return fmt.Errorf("no workflow registered for task")
},
}}}
}
// Run executes the workflow: stages in order, task persisted after each,
// errors park the task with a comment on the issue -- never silently.
func Run(ctx context.Context, wf Workflow, tc *TaskContext) {
t := tc.Task
t.Workflow = wf.Name
// The run's declared interface (outputs.go) is the compiled definition's
// own, so every write/publish/finish check judges the YAML the task row
// pinned.
tc.runInterface, tc.runInterfaceSet = wf.Interface, true
log := tc.Log.With("workflow", wf.Name, "repo", tc.Repo.FullName(), "issue", t.IssueNumber)
for _, stage := range wf.Stages {
tc.Stage = stage.Name
if err := tc.Store.Update(ctx, t); err != nil {
park(ctx, tc, fmt.Sprintf("persist task before stage %s: %v", stage.Name, err))
return
}
// Every stage is a StepExecution (docs/prds/execution-tree-state-machine.md):
// the store records pending -> running and writes the stage_start event
// in the same transaction, and refuses a start the state machine
// forbids. A failed recording write parks the execution -- the step
// does not run unrecorded, because a stage whose record never landed
// would park on a reason no dashboard can trace to a step row.
stepID, startEvent, err := tc.Store.StartStep(ctx, StepStart{
ExecutionID: t.ID, Attempt: t.Attempt, Kind: task.StepKindStage, Name: stage.Name,
})
if err != nil {
park(ctx, tc, fmt.Sprintf("stage %s could not be recorded: %v", stage.Name, err))
return
}
publishEvent(tc, startEvent)
// The stage's own step is the parent of every agent or call step the
// stage body records; zero it when the body returns, so a caller that
// outlives the stage cannot parent to a step that has finished.
tc.StepID = stepID
defer func() { tc.StepID = 0 }()
// The stage is bound onto the task logger for exactly the stage's own
// execution and removed afterwards, so every line a stage's code writes
// is selectable by stage (internal/logging.Query.Stage). It is restored
// rather than left in place because a line written outside any stage is
// not attributable to one. Agent and tool output is logged by the runtime
// that produced it, which never sees this logger, so it carries no stage:
// the stage filter narrows the log, it does not cover it.
previousLog := tc.Log
stageLog := previousLog.With("stage", stage.Name)
tc.Log = stageLog
stageLog.Info("stage starting")
err = stage.Run(ctx, tc)
tc.Log = previousLog
// Daemon shutdown is not a workflow failure. The step records the
// table's interrupted outcome -- the process knows the step it is
// giving up -- and returns without parking: Startup's existing crash
// recovery requeues the execution, and the next attempt starts fresh
// steps. A recording failure on this path is logged and left to the
// same recovery: the process is on its way out either way.
if ctx.Err() != nil && err != nil {
finishCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
finishEvent, recordErr := tc.Store.FinishStep(finishCtx, StepFinish{
StepID: stepID, ExecutionID: t.ID,
From: taskstate.StepRunning, To: taskstate.StepInterrupted, Detail: err.Error(),
})
cancel()
if recordErr != nil {
stageLog.Warn("interrupted step finish could not be recorded", "stage", stage.Name, "err", recordErr)
} else {
publishEvent(tc, finishEvent)
}
stageLog.Info("stage interrupted", "err", err)
return
}
finishTo := taskstate.StepSucceeded
finishDetail := ""
if err != nil {
finishTo = taskstate.StepFailed
finishDetail = err.Error()
}
// The outcome event is the store's own stage_finish row, written in the
// FinishStep transaction -- not a second copy emitted beside it. A
// failed recording write parks the execution, like a failed start.
finishEvent, recordErr := tc.Store.FinishStep(ctx, StepFinish{
StepID: stepID, ExecutionID: t.ID,
From: taskstate.StepRunning, To: finishTo, Detail: finishDetail,
})
if recordErr != nil {
stageLog.Error("stage finish could not be recorded", "stage", stage.Name, "err", recordErr)
park(ctx, tc, fmt.Sprintf("stage %s could not be recorded: %v", stage.Name, recordErr))
return
}
publishEvent(tc, finishEvent)
if err != nil {
// Parking here publishes the failure; the store has already
// recorded the step that produced it.
t.ParkReason = fmt.Sprintf("stage %s: %v", stage.Name, err)
park(ctx, tc, t.ParkReason)
return
}
if tc.Outcome.Status != "" {
finish(ctx, tc, log)
return
}
}
// A workflow must end with an explicit outcome; not doing so is a
// definition bug, which still must not vanish silently.
park(ctx, tc, "workflow ended without an outcome (definition bug)")
}
// publishEvent puts an already-persisted event on the run's bus after its
// write committed: the assigned ID is what the daemon's event sink reads to
// skip the second insert, the same convention EmitDurable established.
func publishEvent(tc *TaskContext, e events.Event) {
if tc.Bus == nil || e.ID == 0 {
return
}
tc.Bus.Publish(e)
}
func finish(ctx context.Context, tc *TaskContext, log *slog.Logger) {
t := tc.Task
if tc.Outcome.Status == StatusParked {
park(ctx, tc, tc.Outcome.Detail)
return
}
// The attempt's declared outputs are validated before the outcome
// transition: an undeclared, mistyped or required-but-missing value
// parks the run here, so no caller observes a terminal state that
// breaks the workflow's own promise
// (docs/prds/workflow-call-outputs.md, "Failure rules").
if err := tc.validateFinishOutputs(); err != nil {
park(ctx, tc, err.Error())
return
}
if err := tc.Store.Update(ctx, t); err != nil {
park(ctx, tc, fmt.Sprintf("persist workflow outcome: %v", err))
return
}
if err := tc.Store.Transition(ctx, t.ID, StatusRunning, tc.Outcome.Status, tc.Outcome.Detail); err != nil {
log.Error("workflow outcome transition failed", "err", err)
return
}
tc.Emit(events.KindOutcome, tc.Stage, tc.Outcome.Detail, map[string]any{"status": tc.Outcome.Status})
log.Info("workflow finished", "status", tc.Outcome.Status)
}
func park(ctx context.Context, tc *TaskContext, reason string) {
t := tc.Task
t.ParkReason = reason
if err := tc.Store.Update(ctx, t); err != nil {
tc.Log.Error("task fields could not be persisted while parking", "err", err)
}
if err := tc.Store.Transition(ctx, t.ID, StatusRunning, StatusParked, reason); err != nil {
tc.Log.Error("task park transition failed", "err", err)
return
}
tc.Emit(events.KindParked, tc.Stage, reason, nil)
// The run's own log is the surface an operator downloads to answer "why did
// this park?", and the event above lands on the timeline, which the log
// never carries. This is the one place a park's reason is final, so it is
// the one place that records it -- the stage names itself in the reason.
tc.Log.Error("task parked", "stage", tc.Stage, "reason", reason)
}
func clip(s string, n int) string {
if len(s) <= n {
return s
}
return s[:n] + "\n…(truncated)"
}
// clipTail keeps the last n bytes of s, breaking on a rune boundary so a
// multi-byte character straddling the cut point isn't split into invalid
// UTF-8 -- this return value can be persisted (e.g. into a task's park
// reason), not just logged, so mangled bytes would survive past this call.
//
// Head-clipping (clip, above) is right when the useful part comes first,
// such as a compiler error. It is wrong for command output where the
// explanation is at the end, such as a test runner's "--- FAIL" block after
// pages of "ok" lines -- clip would keep exactly the part that doesn't say
// why it failed.
func clipTail(s string, n int) string {
if len(s) <= n {
return s
}
cut := len(s) - n
for cut < len(s) && !utf8.RuneStart(s[cut]) {
cut++
}
return "…(truncated)\n" + s[cut:]
}
// formatTokenUsage renders a token total for a human, breaking out how much
// was a cache hit (billed at a steep discount) versus fresh, full-price
// tokens. Without this, a heavily-cached run's raw prompt-token sum reads as
// roughly 10x its actual bill.
//
// It falls back to the plain total when no usage breakdown is available
// (usage is the zero value -- e.g. a workflow that never ran an agent stage,
// or an older code path that hasn't been wired to populate RunUsage), so
// callers never need to special-case an empty Usage themselves.
func formatTokenUsage(total int, usage agentexec.Usage) string {
if usage.PromptTokens == 0 && usage.CompletionTokens == 0 && usage.CachedTokens == 0 {
return fmt.Sprintf("%d tokens", total)
}
fresh := max(usage.PromptTokens-usage.CachedTokens+usage.CompletionTokens, 0)
return fmt.Sprintf("%d tokens (%d fresh + %d cached)", total, fresh, usage.CachedTokens)
}
// extractFailingGateOutput trims a gate command's combined output down to
// the lines relevant to diagnosing a failure, dropping "ok" lines for
// packages that already pass. `go test ./...` output interleaves one
// "ok \t<pkg>\t<time>" line per passing package with the failing packages'
// "--- FAIL:"/"FAIL\t<pkg>" blocks; in a large repo the passing-package
// lines dominate the byte count and get squeezed out by clip's size bound,
// pushing the actual failure detail out of the mission prompt on later
// retries.
//
// It only trims when the output actually looks like recognized `go test`
// failure output (at least one "--- FAIL:" or "FAIL\t" marker survives the
// filter); otherwise it returns s unchanged, so a non-Go gate command or an
// unexpected output shape degrades to the previous full-output behaviour
// instead of silently dropping real failure information.
func extractFailingGateOutput(s string) string {
lines := strings.Split(s, "\n")
kept := make([]string, 0, len(lines))
sawFailureMarker := false
for _, line := range lines {
if goTestOKLine.MatchString(line) {
continue
}
kept = append(kept, line)
if strings.HasPrefix(line, "--- FAIL:") || strings.HasPrefix(line, "FAIL\t") || strings.HasPrefix(line, "FAIL ") {
sawFailureMarker = true
}
}
if !sawFailureMarker {
return s
}
return strings.Join(kept, "\n")
}
// goTestOKLine matches a `go test` passing-package summary line, e.g.
// "ok \tgithub.com/example/pkg\t0.004s".
var goTestOKLine = regexp.MustCompile(`^ok\s+\S+`)
// RunAgentChild records one agent call as a child StepExecution of the stage
// this run is executing (docs/prds/execution-tree-state-machine.md, "Model"):
// kind agent, parented to the stage's own step, which the store derives depth
// from, and finished with the call's own outcome and the tokens it
// accounted. A child's recording write failure is the same park a stage's
// is: an agent call that ran unrecorded is the invisibility the step table
// exists to end. A stage invoked outside the engine's recorded run -- which
// is how the stage unit tests run -- records no child and runs its work
// unchanged.
func (tc *TaskContext) RunAgentChild(ctx context.Context, name string, run func() (agentexec.Result, error)) (agentexec.Result, error) {
stepID, _, err := tc.startChildStep(ctx, task.StepKindAgent, name)
if err != nil {
return agentexec.Result{}, err
}
res, runErr := run()
to, detail := taskstate.StepSucceeded, res.Summary
if runErr != nil {
to, detail = taskstate.StepFailed, runErr.Error()
}
if ferr := tc.finishChildStep(ctx, stepID, to, detail, int64(res.TokensUsed)); ferr != nil {
return res, ferr
}
return res, runErr
}
// startChildStep records one agent or call step under the stage step this
// run is executing. A run with no recorded stage step records nothing and
// reports step id 0 without an error, which is how the stage unit tests keep
// running their bodies exactly as they did before the record existed.
func (tc *TaskContext) startChildStep(ctx context.Context, kind, name string) (int64, events.Event, error) {
if tc.Store == nil || tc.StepID == 0 {
return 0, events.Event{}, nil
}
stepID, event, err := tc.Store.StartStep(ctx, task.StepStart{
ExecutionID: tc.Task.ID, Attempt: tc.Task.Attempt, ParentID: tc.StepID, Kind: kind, Name: name,
})
if err != nil {
return 0, events.Event{}, err
}
publishEvent(tc, event)
return stepID, event, nil
}
// finishChildStep closes a child step and publishes the transition's
// persisted event, the same post-commit convention the stage steps use.
func (tc *TaskContext) finishChildStep(ctx context.Context, stepID int64, to taskstate.StepStatus, detail string, tokensUsed int64) error {
if stepID == 0 {
return nil
}
event, err := tc.Store.FinishStep(ctx, task.StepFinish{
StepID: stepID, ExecutionID: tc.Task.ID,
From: taskstate.StepRunning, To: to, Detail: detail, TokensUsed: tokensUsed,
})
if err != nil {
return err
}
publishEvent(tc, event)
return nil
}