Files
archie/internal/domain/workflow/agent.go
T
sam 44237b448b
deploy / plan (push) Successful in 6s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
ci/woodpecker/push/deploy Pipeline was canceled
deploy / gate (push) Canceled after 2m58s
refactor(prompts): every model prompt is a file in internal/prompts
2026-11-11 00:01:43 +11:00

444 lines
16 KiB
Go

package workflow
import (
"context"
"encoding/json"
"fmt"
"maps"
"os"
"path/filepath"
"slices"
"strings"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/agentrun"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/prompts"
"github.com/samcharles93/archie-core/internal/skill"
"github.com/samcharles93/archie-core/internal/taskstate"
)
// AgentStage runs one LLM-driven workflow stage on the agent runtime with its
// own mission, gate and result handler.
type AgentStage struct {
Name string
// Model is the model alias; empty means the default alias.
Model string
ReadOnly bool
// Mission produces the task statement from the current context.
Mission func(*TaskContext) string
// Gate returns the stage's quality gate; nil means ungated (e.g.
// read-only analysis stages).
Gate func(*TaskContext) agentrun.Gate
// ExtraRules is appended to the system prompt.
ExtraRules string
// MaxSteps overrides the configured step budget when > 0 (planner
// stages are cheaper than builder stages).
MaxSteps int
// ProtectGlobs blocks write/edit on matching paths for this stage, in
// addition to the repo's protected suffixes.
ProtectGlobs func(*TaskContext) []string
// CaptureTools adds structured-output tools whose calls are returned
// as data rather than receiving callbacks into daemon state.
CaptureTools func(*TaskContext) []agentrun.CaptureTool
// OnResult consumes a successful (passed) result. A stop on the stage's
// budget closes the run with the partial findings as its outcome before
// OnResult is called; any other parked or idle result parks the
// workflow.
OnResult func(*TaskContext, agentrun.Result) error
// ApproveBudget makes a stop on the step budget ask for approval to
// continue, in the same worktree, instead of parking the run.
ApproveBudget bool
// ReviewResult gates agent output before OnResult forwards it to the
// delivery channels. The daemon calls this hook to review stage output (issue
// comments, PR bodies) before delivery. Return an error to block the
// stage. Nil means pass-through -- no review.
ReviewResult func(*TaskContext, agentrun.Result) error
}
// Stage adapts the AgentStage to the engine.
func (a AgentStage) Stage() Stage {
return Stage{Name: a.Name, Run: func(ctx context.Context, tc *TaskContext) error {
// Lazy-load the skill body from the worktree (dir is set by the
// prepare stage, which runs before any agent stage). If the body
// was already loaded by the daemon, this is a no-op.
if tc.SkillBody == "" && tc.Dir != "" {
tc.SkillBody = loadSkillBody(tc)
}
if tc.Agent == nil {
return fmt.Errorf("no LLM runtime configured (missing [providers] in config?)")
}
modelRef, err := a.resolveModel(tc)
if err != nil {
return err
}
req, buildErr := a.buildRequest(tc, modelRef)
if buildErr != nil {
return buildErr
}
// The agent call is a child of the stage's recorded step: the store
// says what the stage's runtime did, not just what the stage did.
req.History = tc.takeHistory(a.historyKey(tc))
tc.transcript = slices.Clone(req.History)
res, runErr := tc.RunAgentChild(ctx, a.Name, a.Model, modelRef, func() (agentrun.Result, error) {
report := tc.reporter(ctx, a.Name)
persist := report.Transcript
report.Transcript = func(entry agentrun.TranscriptEntry) {
tc.transcript = append(tc.transcript, entry)
persist(entry)
}
return tc.Agent.Run(ctx, tc.Dir, req, report)
})
return a.handleResult(ctx, tc, req, res, runErr, modelRef)
}}
}
// resolveModel resolves this stage's model alias.
func (a AgentStage) resolveModel(tc *TaskContext) (string, error) {
return config.ResolveModel(tc.Cfg.Models, a.Model, config.PurposeAgent)
}
// buildRequest assembles the agentrun.Request for this stage's run.
func (a AgentStage) buildRequest(tc *TaskContext, modelRef string) (agentrun.Request, error) {
budget := agentrun.Budget{
MaxSteps: tc.Cfg.Budgets.MaxSteps,
WallClock: tc.Cfg.Budgets.WallClock.Std(),
}
if a.MaxSteps > 0 {
budget.MaxSteps = a.MaxSteps
}
var gate agentrun.Gate
if a.Gate != nil {
gate = a.Gate(tc)
}
var captureTools []agentrun.CaptureTool
if a.CaptureTools != nil {
captureTools = a.CaptureTools(tc)
}
captureTools, err := tc.appendOutputTools(captureTools)
if err != nil {
return agentrun.Request{}, err
}
protection := agentrun.Protection{Suffixes: append([]string(nil), tc.Repo.Protect...)}
if a.ProtectGlobs != nil {
protection.Globs = a.ProtectGlobs(tc)
}
if a.ReadOnly {
protection = agentrun.Protection{}
}
var preflight []agentrun.Command
for _, argv := range tc.Repo.ResolvedPreflight() {
if len(argv) == 0 {
continue
}
preflight = append(preflight, agentrun.Command{Name: argv[0], Argv: argv})
}
return agentrun.Request{
Version: agentrun.ProtocolVersion,
TaskID: tc.Task.ID,
Attempt: tc.Task.Attempt,
Stage: a.Name,
Workflow: tc.Task.Workflow,
Model: modelRef,
ContextWindow: modelContextBudget(tc.Cfg, modelRef),
Mission: missionWithInputs(tc.Task, missionWithSkill(tc, a.Mission(tc))),
ExtraRules: tc.withInstructions(a.buildExtraRules(tc)),
ReadOnly: a.ReadOnly,
Budget: budget,
Gate: gate,
Preflight: preflight,
Protection: protection,
Notes: tc.Task.Notes,
CaptureTools: captureTools,
}, nil
}
// buildExtraRules prepends memory context, if the daemon wired a memory
// manager, ahead of the stage's own rules.
func (a AgentStage) buildExtraRules(tc *TaskContext) string {
if tc.SystemPrompt == nil {
return a.ExtraRules
}
memCtx := tc.SystemPrompt()
if memCtx == "" {
return a.ExtraRules
}
if a.ExtraRules == "" {
return memCtx
}
return memCtx + "\n\n" + a.ExtraRules
}
// handleResult records guardrail state, validates and persists the agent
// result, then dispatches to ReviewResult/OnResult on success.
func (a AgentStage) handleResult(
ctx context.Context, tc *TaskContext, req agentrun.Request, res agentrun.Result, runErr error, modelRef string,
) error {
a.recordGuardrails(tc, res, runErr)
if runErr != nil && res.Version == 0 {
return fmt.Errorf("agent run: %w", runErr)
}
if validateErr := res.ValidateFor(req); validateErr != nil {
return fmt.Errorf("validate agent result: %w", validateErr)
}
if err := persistAppendedNotes(ctx, tc, res); err != nil {
return err
}
tc.Task.TokensUsed += res.TokensUsed
tc.Task.Iterations += res.Iterations
accumulateUsage(&tc.RunUsage, res.Usage)
if emitErr := tc.EmitDurable(ctx, events.KindAgentFinish, a.Name, res.Summary, agentFinishData(res, modelRef)); emitErr != nil {
return fmt.Errorf("persist agent finish: %w", emitErr)
}
if runErr != nil {
return fmt.Errorf("agent run: %w", runErr)
}
return a.deliverResult(tc, res)
}
// recordGuardrails feeds this run's outcome to the guardrail engine: on
// success it checks no-progress thresholds, on failure it records the
// error pattern.
func (a AgentStage) recordGuardrails(tc *TaskContext, res agentrun.Result, runErr error) {
if tc.Guardrails == nil {
return
}
if runErr == nil && res.Status == agentrun.StatusPassed {
tc.Guardrails.RecordSuccess("agent:" + a.Name)
} else if runErr != nil {
tc.Guardrails.RecordFailure("agent:"+a.Name, runErr)
}
}
// persistAppendedNotes saves any notes the agent appended during the run.
func persistAppendedNotes(ctx context.Context, tc *TaskContext, res agentrun.Result) error {
if len(res.AppendedNotes) == 0 {
return nil
}
for _, note := range res.AppendedNotes {
tc.Task.Notes += "- " + note + "\n"
}
if saveErr := tc.Store.Update(ctx, tc.Task); saveErr != nil {
return fmt.Errorf("persist agent notes: %w", saveErr)
}
return nil
}
// Budget stop reasons, matching the runners' vocabulary: the built-in
// loop's step budget and both runners' wall clock report one of these.
const (
stopBudgetExhausted = "budget_exhausted"
stopTimedOut = "timed_out"
)
// budgetStopped reports whether res is a stage that exhausted its budget:
// the loop's step budget or a runner's wall clock. Such a stop is an
// outcome that carries what the stage found, not a runner error.
func budgetStopped(res agentrun.Result) bool {
return res.StopReason == stopBudgetExhausted || res.StopReason == stopTimedOut
}
// budgetStopOutcome is the outcome a budget-stopped stage closes the run
// with: what stopped it and the partial findings it recorded, in the place
// a completed run's result would occupy. The status stays parked, so the
// outcome is distinguishable from a gate-passed completion.
func budgetStopOutcome(stage string, res agentrun.Result) Outcome {
var b strings.Builder
fmt.Fprintf(&b, "stage %s stopped on its budget (%s)", stage, res.StopReason)
if detail := strings.TrimSpace(res.Detail); detail != "" {
b.WriteString(": " + detail)
} else if summary := strings.TrimSpace(res.Summary); summary != "" {
b.WriteString(": " + summary)
}
if len(res.AppendedNotes) > 0 {
b.WriteString("\n\nPartial findings:")
for _, note := range res.AppendedNotes {
b.WriteString("\n- " + note)
}
}
if len(res.Changes) > 0 {
b.WriteString("\n\nChanged files:")
for _, path := range res.Changes {
b.WriteString("\n- " + path)
}
}
// The store caps a park reason at 4000; the stop and the findings come
// ahead of the changed files, so clipping loses work last.
return Outcome{Status: StatusParked, Detail: clip(b.String(), 4000)}
}
// awaitBudgetApproval waits for a decision on running the stage again. The
// worktree is kept as it stands, the stage's findings and changed files go to
// the next run as task notes, and its conversation is kept for the run to
// continue from. The run loop records where the workflow resumes.
func awaitBudgetApproval(tc *TaskContext, stage, historyKey string, res agentrun.Result) {
note := fmt.Sprintf("Stage %s stopped on its step budget and was approved to continue. The worktree holds its work so far; carry on from it.", stage)
if summary := strings.TrimSpace(res.Summary); summary != "" {
note += " Where it stood: " + summary
}
if len(res.Changes) > 0 {
note += " Files changed so far: " + strings.Join(res.Changes, ", ") + "."
}
tc.Task.Notes += "- " + note + "\n"
tc.Task.RetryMode = string(taskstate.RetryKeepWorktree)
tc.Task.ResumeHistory = mergeHistories(tc.Task.ResumeHistory, stageHistories{historyKey: agentrun.BoundHistory(tc.transcript, agentrun.HistoryBytes(0))})
detail := budgetStopOutcome(stage, res).Detail
tc.Outcome = Outcome{Status: StatusWaitingApproval, Detail: clip(detail+"\n\nApprove to continue with another full step budget, or reject to stop.", 4000)}
}
// deliverResult checks the run passed, then runs ReviewResult and OnResult.
func (a AgentStage) deliverResult(tc *TaskContext, res agentrun.Result) error {
if res.Status != agentrun.StatusPassed {
// A budget stop is an outcome, not a failure: the stage closes the
// run with what it found, without demanding the gate passed.
// ReviewResult and OnResult stay behind the passed check, because
// a budget stop is not a success.
if a.ApproveBudget && res.StopReason == stopBudgetExhausted {
awaitBudgetApproval(tc, a.Name, a.historyKey(tc), res)
return nil
}
if budgetStopped(res) {
tc.Outcome = budgetStopOutcome(a.Name, res)
return nil
}
detail := res.Detail
if detail == "" {
detail = res.Summary
}
// A stage that stops without passing has its notes to show alongside
// the reason.
for _, note := range res.AppendedNotes {
detail += "\n- " + note
}
return fmt.Errorf("agent %s (%s): %s", res.Status, res.StopReason, clip(detail, 2000))
}
if !a.ReadOnly {
// repo.commit clears this when the stage commits changes.
tc.BuildNoChanges = true
}
// Gatekeeping: the daemon reviews agent output before delivery.
if a.ReviewResult != nil {
if err := a.ReviewResult(tc, res); err != nil {
return fmt.Errorf("review: %w", err)
}
}
if err := tc.applyOutputCaptures(res); err != nil {
return err
}
if a.OnResult != nil {
return a.OnResult(tc, res)
}
return nil
}
func modelContextBudget(cfg config.Config, modelRef string) int {
limits := cfg.ModelLimits[modelRef]
if limits.ContextWindow <= limits.MaxOutputTokens {
return 0
}
return limits.ContextWindow - limits.MaxOutputTokens
}
// accumulateUsage adds a single agent run's token breakdown onto a
// workflow-run running total. Extracted so every accumulation site (agent.go
// and implement.go's baseline-fix repair loop) stays in sync.
func accumulateUsage(total *agentrun.Usage, delta agentrun.Usage) {
total.PromptTokens += delta.PromptTokens
total.CompletionTokens += delta.CompletionTokens
total.TotalTokens += delta.TotalTokens
total.CachedTokens += delta.CachedTokens
total.CacheCreationTokens += delta.CacheCreationTokens
}
func agentFinishData(res agentrun.Result, modelRef string) map[string]any {
return map[string]any{
"status": res.Status, "stop_reason": res.StopReason,
"tokens": res.TokensUsed, "iterations": res.Iterations, "model": modelRef,
"prompt_tokens": res.Usage.PromptTokens, "completion_tokens": res.Usage.CompletionTokens,
"cached_tokens": res.Usage.CachedTokens, "cache_creation_tokens": res.Usage.CacheCreationTokens,
}
}
// GateFromRepo converts the repo's configured command lists into an
// agent execution gate.
func GateFromRepo(repo config.Repo, budgets config.Budgets) agentrun.Gate {
cmds := make([]agentrun.Command, 0, len(repo.Gate))
for _, argv := range repo.Gate {
if len(argv) == 0 {
continue
}
cmds = append(cmds, agentrun.Command{Name: argv[0], Argv: argv})
}
return agentrun.Gate{Commands: cmds, MaxConsecutiveFailures: budgets.GateMaxFailures}
}
// missionWithSkill prepends the skill body (loaded from SKILL.md) to the
// stage's mission. When no skill is loaded, the mission is returned unchanged.
func missionWithSkill(tc *TaskContext, mission string) string {
if tc.SkillBody == "" {
return mission
}
return prompts.SkillGuidelines(tc.SkillBody, mission)
}
// loadSkillBody loads the SKILL.md body for the current workflow, matched by
// metadata.archie.workflow.
func loadSkillBody(tc *TaskContext) string {
catalog, _ := skill.Catalog(tc.Dir)
entry := skill.SkillForWorkflow(catalog, tc.Task.Workflow)
if entry == nil {
return ""
}
// Read and parse SKILL.md once to get both body and frontmatter.
skillPath := filepath.Join(tc.Dir, ".agents", "skills", entry.Dir, "SKILL.md")
data, err := os.ReadFile(skillPath)
if err != nil {
return ""
}
fm, body, err := skill.Parse(data)
if err != nil || fm == nil {
return ""
}
body = strings.TrimSpace(body)
return body
}
// stageHistories are the conversations budget-stopped agent steps leave for
// their continuation, by step path, as persisted on the task. Parallel
// branches can stop in the same attempt.
type stageHistories map[string][]agentrun.TranscriptEntry
// historyKey identifies this step's conversation: its path when it runs in a
// workflow, which tells apart the same step in two branches.
func (a AgentStage) historyKey(tc *TaskContext) string {
if tc.stepPath != "" {
return tc.stepPath
}
return a.Name
}
// mergeHistories adds the conversations in more to the persisted ones.
func mergeHistories(persisted json.RawMessage, more stageHistories) json.RawMessage {
merged := stageHistories{}
if len(persisted) > 0 {
// A value this package wrote; one it cannot read is dropped.
_ = json.Unmarshal(persisted, &merged)
}
maps.Copy(merged, more)
// Transcript entries hold strings and numbers, which always marshal.
encoded, _ := json.Marshal(merged)
return encoded
}
// takeHistory hands the step the conversation its earlier run left, once.
func (tc *TaskContext) takeHistory(key string) []agentrun.TranscriptEntry {
entries := tc.resumeHistory[key]
delete(tc.resumeHistory, key)
return entries
}