Implements archie-core-h019.3 (reviewer isolation) and h019.4 (wiring),
per docs/prds/adversarial-self-review.md.
- internal/domain/workflow: new Reviewer interface and StageReview,
inserted between StageDiffCap and StageOpenPR in the implement
workflow. Fail-closed: a review that didn't run, or a confirmed
error-level finding, parks the task (store.StatusParked) with
findings in Detail; warn/plausible findings never block. Inert
unless Repo.ReviewEnabled.
- internal/worktree: Manager.Snapshot exports HEAD's tracked files into
a fresh directory with no .git, for the reviewer's isolated
workspace. Trees interface gains Snapshot; hybridTrees delegates to
it.
- internal/app/agentworker: subagentReviewer implements Reviewer using
ai-sdk's agent.Subagent (nested, in-process, non-streaming
generation) -- conversation isolation is structural (Subagent.Run
never carries message history), workspace isolation is the snapshot
above. The reviewer's toolset is read-only (read/grep/find) rooted
at the snapshot, never the worker's own toolset, so it cannot reach
the worktreerpc publication grant. Findings are captured via a typed
record_finding tool appending to a slice the stage owns, read even
when Subagent.Run errors (a truncated run's captured findings
survive).
- internal/config: Repo.ReviewEnabled (default false) and
Models["reviewer"] (falls back to Models["builder"], no schema
change).
Judgment calls: Reviewer.Review never returns a Go error -- every
failure folds into ReviewReport per the PRD's fail-closed contract,
which the stage can act on uniformly. A Subagent.Run error with zero
captured findings resolves to ReviewStatusNotRun (park); a
Subagent.Run error with >=1 captured findings resolves to
ReviewStatusCompleted with those findings, since the PRD's own example
("three defects survive a step-limit truncation") requires them to
still be evaluated for blocking rather than discarded.
361 lines
13 KiB
Go
361 lines
13 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"
|
|
"errors"
|
|
"fmt"
|
|
"log/slog"
|
|
"sort"
|
|
"time"
|
|
"unicode/utf8"
|
|
|
|
"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 {
|
|
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
|
|
}
|
|
|
|
// 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 *store.Task
|
|
Repo config.Repo
|
|
Cfg config.Config
|
|
Forge Forger
|
|
Store store.WorkflowStore
|
|
Trees Trees
|
|
Agent agentexec.Runner
|
|
// Reviewer runs the adversarial self-review stage (StageReview). Nil
|
|
// is only safe when Repo.ReviewEnabled is false; StageReview parks
|
|
// rather than silently skipping if it is enabled with no Reviewer
|
|
// wired.
|
|
Reviewer Reviewer
|
|
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. Application
|
|
// composition injects it; nil disables discovery, so StageRepoStages is a
|
|
// no-op. The composition layer provides the implementation rather
|
|
// than importing the generated Yaegi symbol table here, which would create
|
|
// a workflow package 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,
|
|
})
|
|
}
|
|
|
|
// 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, 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 // 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
|
|
|
|
// Definition is the operator-safe snapshot of an executable workflow. It
|
|
// contains only identity and stage order, never executable function values.
|
|
type Definition struct {
|
|
ID string `json:"id"`
|
|
Name string `json:"name"`
|
|
Origin string `json:"origin"`
|
|
Enabled bool `json:"enabled"`
|
|
Stages []string `json:"stages"`
|
|
}
|
|
|
|
// Definitions snapshots a registry deterministically so installed workflows
|
|
// remain visible even when they have not produced persisted run statistics.
|
|
func Definitions(reg Registry) []Definition {
|
|
return DefinitionsWithOrigins(reg, nil)
|
|
}
|
|
|
|
// DefinitionsWithOrigins snapshots a registry with composition-supplied
|
|
// provenance. Entries absent from origins are conservatively labelled
|
|
// "registry", which keeps the helper useful for tests and non-catalog callers.
|
|
func DefinitionsWithOrigins(reg Registry, origins map[string]string) []Definition {
|
|
ids := make([]string, 0, len(reg))
|
|
for id := range reg {
|
|
ids = append(ids, id)
|
|
}
|
|
sort.Strings(ids)
|
|
definitions := make([]Definition, 0, len(ids))
|
|
for _, id := range ids {
|
|
wf := reg[id]
|
|
stages := make([]string, 0, len(wf.Stages))
|
|
for _, stage := range wf.Stages {
|
|
stages = append(stages, stage.Name)
|
|
}
|
|
origin := origins[id]
|
|
if origin == "" {
|
|
origin = "registry"
|
|
}
|
|
definitions = append(definitions, Definition{ID: id, Name: wf.Name, Origin: origin, Enabled: true, Stages: stages})
|
|
}
|
|
return definitions
|
|
}
|
|
|
|
// 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
|
|
}
|
|
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
|
|
}
|
|
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()
|
|
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
|
|
data["interrupted"] = true
|
|
}
|
|
}
|
|
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)
|
|
tc.Emit(events.KindOutcome, t.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
|
|
_ = tc.Store.Update(ctx, t)
|
|
_ = tc.Store.Transition(ctx, t.ID, store.StatusRunning, store.StatusParked, reason)
|
|
tc.Emit(events.KindParked, t.Stage, reason, nil)
|
|
}
|
|
|
|
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:]
|
|
}
|