Files
archie/internal/workflow/workflow.go
T
sam 9d5040fd65 refactor: add internal/eventbus as the broker-neutral messaging contract
dependencies-and-contracts.md rule 1 says domains must not import
internal/infrastructure. internal/daemon and internal/agentexec both did,
and for exactly the thing the doc carves out: "internal/eventbus is an
approved shared application contract ... it MUST remain broker-neutral."

The Publisher/Consumer/Requester interfaces existed but lived inside the
NATS package, so a caller could depend on the behaviour yet still had to
import the implementation to name it. They now live in internal/eventbus,
and nats.Client asserts against eventbus.Bus.

The larger violation was ownership of meaning. The doc says "message schemas
stay with their owning domains; the event bus transports messages, it does
not own their meaning." The bus exported TaskEnvelope and a PublishTask
method, so the transport knew what a unit of work was, and it exported the
archie.agent.* subject helpers, so it also owned the agent protocol.

  - TaskEnvelope, its routing Kind, the label vocabulary and the task
    subjects move to internal/domain/workintake, which encodes and decodes
    its own bytes. This starts internal/domain/ per organisation.md.
  - The agent request/response/system subjects move to internal/agentexec,
    which defines what those messages mean.
  - internal/workflow keeps only the kind-to-registry mapping; the label
    table stays single and lives with the domain that reads forge issues.
  - The bus now carries opaque payloads on plain-string subjects.

Consumers declare the smallest interface they need rather than taking the
whole Bus: daemon.TaskBus is publish-unique/fetch/request, agentexec.
RequestBus is publish-request/reply-inbox, and archie-agent's stageBus is
fetch/respond. None can reach what it does not use.

Two defects this surfaced:

  - archie-agent declared its own JetStream stream with a second copy of the
    name, subjects, retention, dedup window, MaxDeliver and TTLs that
    nats.Connect already sets -- two definitions of one stream, free to
    diverge. Config now takes Subjects and FilterSubject from composition,
    which is what let the agent use the shared client and delete its
    hand-rolled setup.
  - Replying to a request needs core NATS, not the JetStream publish path:
    a reply inbox is ephemeral and belongs to no stream, so a durable
    publish to it fails. The old code hid this by using the raw connection.
    The contract now distinguishes Respond from Publish. The agentexec
    round-trip test caught it after I had made the same mistake in
    archie-agent.

Also translated the SDK's ErrNoResponders into eventbus.ErrNoResponders, so
the daemon's taskrun retry no longer imports the NATS SDK to name a
transient condition. The SDK is now confined to the nats package, the *rpc
packages (themselves NATS infrastructure), and cmd/*.

The agentexec test fake previously hand-rolled a JetStream consumer; it now
drains the client's own consumer, which is both closer to production and
avoids conflicting consumers on a work-queue stream.

Verified: go build, go vet, gofmt clean; full test suite passes.
2026-07-29 11:40:24 +10:00

275 lines
10 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"
"time"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/skill"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/tools"
)
// Forger is the subset of forge.Forge that workflow stages call mid-run.
// forge.Forge (the daemon's real implementations) and forgerpc.Client
// (archie-agent's NATS-backed proxy) both satisfy it.
type Forger interface {
Comment(ctx context.Context, owner, repo string, number int, body string) (int64, error)
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)
SetStateLabel(ctx context.Context, owner, repo string, number int, label string, knownLabels []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)
}
// 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 *store.Task
Repo config.Repo
Cfg config.Config
Forge Forger
Store store.WorkflowStore
Trees Trees
Agent agentexec.Runner
Bus *events.Bus // nil-safe via Emit
Log *slog.Logger
// CustomStages discovers a repo's per-repo custom stages (Yaegi-
// interpreted from .archie/stages/*.go in the given worktree
// directory), returning them in the order they should run. Wired up
// by the composition root (cmd/archied) -- nil disables discovery, so
// StageRepoStages is a no-op. Kept as an injected function rather
// than a direct import to avoid workflow depending on its own
// generated Yaegi symbol table (an import cycle).
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
// 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
// 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
// Outcome describes where the task ended up; the engine applies it.
Outcome Outcome
// 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
}
// Emit publishes an observability event stamped with the task's
// identity. Safe on a nil bus.
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,
Stage: stage,
Detail: detail,
Data: data,
})
}
// 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 // store.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
}
// 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 *store.Task, reg Registry) Workflow {
if t.Workflow != "" {
if wf, ok := reg[t.Workflow]; ok {
return wf
}
}
if wf, ok := workflowForLabels(reg, t.Labels); 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
log := tc.Log.With("workflow", wf.Name, "repo", tc.Repo.FullName(), "issue", t.IssueNumber)
for _, stage := range wf.Stages {
t.Stage = stage.Name
_ = tc.Store.Update(ctx, t)
log.Info("stage starting", "stage", stage.Name)
tc.Emit(events.KindStageStart, stage.Name, "", nil)
started := time.Now()
err := stage.Run(ctx, tc)
data := map[string]any{"duration_ms": time.Since(started).Milliseconds()}
if err != nil {
data["error"] = err.Error()
}
tc.Emit(events.KindStageFinish, stage.Name, "", data)
if err != nil {
// Daemon shutdown is not a workflow failure. Leave the task running
// so Startup's existing crash recovery requeues it; parking here
// would publish a false failure and require manual intervention.
if ctx.Err() != nil {
log.Info("stage interrupted", "stage", stage.Name, "err", err)
return
}
t.ParkReason = fmt.Sprintf("stage %s: %v", stage.Name, err)
log.Warn("stage failed -- parking", "stage", stage.Name, "err", 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)")
}
func finish(ctx context.Context, tc *TaskContext, log *slog.Logger) {
t := tc.Task
if tc.Outcome.Status == store.StatusParked {
park(ctx, tc, tc.Outcome.Detail)
return
}
_ = tc.Store.Update(ctx, t)
_ = tc.Store.Transition(ctx, t.ID, store.StatusRunning, tc.Outcome.Status, tc.Outcome.Detail)
if t.IsForgeBacked() {
tc.Forge.SetStateLabel(ctx, t.Owner, t.Repo, t.IssueNumber, stateLabelFor(tc.Cfg.Dispatch, tc.Outcome.Status), tc.Cfg.Dispatch.LabelValues())
}
tc.Emit(events.KindOutcome, t.Stage, tc.Outcome.Detail, map[string]any{"status": tc.Outcome.Status})
log.Info("workflow finished", "status", tc.Outcome.Status)
}
// stateLabelFor maps a terminal workflow status to its forge label by
// looking up the configured [dispatch.labels]; empty clears (done states
//
// -- the issue closes or the PR speaks).
func stateLabelFor(d config.Dispatch, status string) string {
switch status {
case store.StatusPROpen:
return d.StateLabel("pr")
case store.StatusWaitingHuman:
return d.StateLabel("waiting")
case store.StatusParked:
return d.StateLabel("parked")
case store.StatusDead:
return d.StateLabel("dead")
default:
return ""
}
}
func park(ctx context.Context, tc *TaskContext, reason string) {
t := tc.Task
t.ParkReason = reason
_ = tc.Store.Update(ctx, t)
_ = tc.Store.Transition(ctx, t.ID, store.StatusRunning, store.StatusParked, reason)
tc.Emit(events.KindParked, t.Stage, reason, nil)
if !t.IsForgeBacked() {
// Chat-sourced tasks have no real forge issue to label or
// comment on; the park reason is visible via /status and the
// task's ParkReason field instead.
return
}
tc.Forge.SetStateLabel(ctx, t.Owner, t.Repo, t.IssueNumber, tc.Cfg.Dispatch.StateLabel("parked"), tc.Cfg.Dispatch.LabelValues())
body := fmt.Sprintf("**archie parked this task.**\n\n```\n%s\n```\n\nThe worktree is kept for inspection.",
clip(reason, 3000))
if _, err := tc.Forge.Comment(ctx, t.Owner, t.Repo, t.IssueNumber, body); err != nil {
tc.Log.Error("failed to post park comment", "err", err)
}
}
func clip(s string, n int) string {
if len(s) <= n {
return s
}
return s[:n] + "\n…(truncated)"
}