Plan item 4 of docs/prds/execution-tree-state-machine.md (archie-core-1216), plus the callee half of CancelExecution that plan item 5 deferred until the tree could decide it. Every agent call a stage makes records itself: AgentStage's bridge, the baseline-fix auto-fix run, the adversarial reviewer and a workflow.call each start a child StepExecution of kind agent or call under the stage's own step -- TaskContext.StepID, which the engine sets before the stage body starts and clears when it returns -- and finish it with the call's own outcome and the tokens it accounted. A child's recording write failure parks the execution the same way a stage's does: an agent call that ran unrecorded is the invisibility the step table exists to end. A stage invoked outside the engine's recorded run -- the stage unit tests -- records no child and runs unchanged. The call step is what makes the callee half of the PRD's Cancellation section decidable, and this lands it: a call step closes when its callee ends, so an open call step is a callee the caller waits on (wait:true) and a closed one is a wait:false callee that runs on. CancelExecution reads the open call steps before its sweep closes them and cancels each named callee through its own CancelExecution in the caller's write's aftermath -- the callee's own steps, its own events, its own move to the same destination, and the callee's own wait:true callees beyond it, the depth the enqueue enforces bounding the recursion. A callee that cannot be cancelled is reported and the caller's own record stands. StartStep refuses a call step whose callee is not this run's own (the callee's call_parent_task_id must name the recording execution): a compromised container could otherwise record a step naming a foreign execution and cancel it. StartStepRequest gains called_execution_id (field 6; non-breaking, the column and its named consumer already exist) and StepStart carries it. PRD decisions recorded here: - The reviewer records as one agent child named "review": the Reviewer contract runs one subagent per review, the PRD model's review:1/review:2 are illustrative of depth-1 children. A completed report closes it succeeded, a not-run review failed with the skip reason; the contract carries no usage, so tokens are 0. - A failed-callee call step closes as failed with the callee's detail when the wait ends otherwise; the single open case is the caller itself being cancelled, whose CancelExecution already swept this step -- a late write must not pretend the wait is still the caller's business. - A call step's callee is cancelled to the same destination the caller's action named (parked stays parked, closed_wont_do ends the whole chain), and a callee that cannot be cancelled is reported while the caller's own record stands either way. - The agent child's detail is the result summary on success and the error's text on failure, with the call's own TokensUsed -- the PRD's only usage field, untracked per call for the reviewer contract.
339 lines
12 KiB
Go
339 lines
12 KiB
Go
package workflow
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"os"
|
|
"path/filepath"
|
|
"strings"
|
|
|
|
"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"
|
|
)
|
|
|
|
// AgentStage is the reusable bridge from a workflow stage to an
|
|
// agentloop run. Every LLM-driven stage in any workflow (implement's
|
|
// planner/builder, tdd's test-writer/fixer, feasibility's analyst)
|
|
// is an AgentStage with a different mission, gate, and result handler --
|
|
// never a new engine.
|
|
type AgentStage struct {
|
|
Name string
|
|
// Role selects the model via cfg.Models[Role]; falls back to
|
|
// cfg.Models["builder"].
|
|
Role 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) agentexec.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 --
|
|
// an environmental constraint, not a prompt rule (TDD's fix stage
|
|
// protects the committed repro tests; every builder stage protects
|
|
// the repo's generated files). The returned globs are combined
|
|
// with the repo's configured 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) []agentexec.CaptureTool
|
|
// OnResult consumes a successful (passed) result. Parked and idle
|
|
// results park the workflow before OnResult is called.
|
|
OnResult func(*TaskContext, agentexec.Result) error
|
|
// ReviewResult gates agent output before OnResult forwards it to
|
|
// human channels. The daemon calls this hook to review stage output
|
|
// (issue comments, PR bodies) before human delivery. Return an
|
|
// error to block the stage. Nil means pass-through -- no review.
|
|
// PRD §1: daemon reviews agent responses before forwarding.
|
|
ReviewResult func(*TaskContext, agentexec.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 := a.buildRequest(tc, modelRef)
|
|
// 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.
|
|
res, runErr := tc.RunAgentChild(ctx, a.Name, func() (agentexec.Result, error) {
|
|
return tc.Agent.Run(ctx, tc.Dir, req, tc.toolCallReporter(a.Name))
|
|
})
|
|
return a.handleResult(ctx, tc, req, res, runErr, modelRef)
|
|
}}
|
|
}
|
|
|
|
// resolveModel picks the model reference for this stage's Role, falling
|
|
// back to "builder".
|
|
func (a AgentStage) resolveModel(tc *TaskContext) (string, error) {
|
|
modelRef := tc.Cfg.Models[a.Role]
|
|
if modelRef == "" {
|
|
modelRef = tc.Cfg.Models["builder"]
|
|
}
|
|
if modelRef == "" {
|
|
return "", fmt.Errorf("no model configured for role %q (set [models] in config)", a.Role)
|
|
}
|
|
return modelRef, nil
|
|
}
|
|
|
|
// buildRequest assembles the agentexec.Request for this stage's run.
|
|
func (a AgentStage) buildRequest(tc *TaskContext, modelRef string) agentexec.Request {
|
|
budget := agentexec.Budget{
|
|
MaxSteps: tc.Cfg.Budgets.MaxSteps,
|
|
WallClock: tc.Cfg.Budgets.WallClock.Std(),
|
|
}
|
|
if a.MaxSteps > 0 {
|
|
budget.MaxSteps = a.MaxSteps
|
|
}
|
|
|
|
var gate agentexec.Gate
|
|
if a.Gate != nil {
|
|
gate = a.Gate(tc)
|
|
}
|
|
var captureTools []agentexec.CaptureTool
|
|
if a.CaptureTools != nil {
|
|
captureTools = a.CaptureTools(tc)
|
|
}
|
|
|
|
protection := agentexec.Protection{Suffixes: append([]string(nil), tc.Repo.Protect...)}
|
|
if a.ProtectGlobs != nil {
|
|
protection.Globs = a.ProtectGlobs(tc)
|
|
}
|
|
if a.ReadOnly {
|
|
protection = agentexec.Protection{}
|
|
}
|
|
|
|
var preflight []agentexec.Command
|
|
for _, argv := range tc.Repo.ResolvedPreflight() {
|
|
if len(argv) == 0 {
|
|
continue
|
|
}
|
|
preflight = append(preflight, agentexec.Command{Name: argv[0], Argv: argv})
|
|
}
|
|
|
|
return agentexec.Request{
|
|
Version: agentexec.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: a.buildExtraRules(tc),
|
|
ReadOnly: a.ReadOnly,
|
|
Budget: budget,
|
|
Gate: gate,
|
|
Preflight: preflight,
|
|
Protection: protection,
|
|
Notes: tc.Task.Notes,
|
|
CaptureTools: captureTools,
|
|
Plugins: pluginSpecs(tc.SkillPlugins),
|
|
}
|
|
}
|
|
|
|
// 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 agentexec.Request, res agentexec.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 agentexec.Result, runErr error) {
|
|
if tc.Guardrails == nil {
|
|
return
|
|
}
|
|
if runErr == nil && res.Status == agentexec.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 agentexec.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
|
|
}
|
|
|
|
// deliverResult checks the run passed, then runs ReviewResult and OnResult.
|
|
func (a AgentStage) deliverResult(tc *TaskContext, res agentexec.Result) error {
|
|
if res.Status != agentexec.StatusPassed {
|
|
detail := res.Detail
|
|
if detail == "" {
|
|
detail = res.Summary
|
|
}
|
|
return fmt.Errorf("agent %s (%s): %s", res.Status, res.StopReason, clip(detail, 2000))
|
|
}
|
|
// Gatekeeping: the daemon reviews agent output before human delivery.
|
|
if a.ReviewResult != nil {
|
|
if err := a.ReviewResult(tc, res); err != nil {
|
|
return fmt.Errorf("review: %w", 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 *agentexec.Usage, delta agentexec.Usage) {
|
|
total.PromptTokens += delta.PromptTokens
|
|
total.CompletionTokens += delta.CompletionTokens
|
|
total.TotalTokens += delta.TotalTokens
|
|
total.CachedTokens += delta.CachedTokens
|
|
total.CacheCreationTokens += delta.CacheCreationTokens
|
|
}
|
|
|
|
func agentFinishData(res agentexec.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) agentexec.Gate {
|
|
cmds := make([]agentexec.Command, 0, len(repo.Gate))
|
|
for _, argv := range repo.Gate {
|
|
if len(argv) == 0 {
|
|
continue
|
|
}
|
|
cmds = append(cmds, agentexec.Command{Name: argv[0], Argv: argv})
|
|
}
|
|
return agentexec.Gate{Commands: cmds, MaxConsecutiveFailures: budgets.GateMaxFailures}
|
|
}
|
|
|
|
// pluginSpecs converts skill.Plugin to agentexec.PluginSpec for transport.
|
|
func pluginSpecs(plugins []skill.Plugin) []agentexec.PluginSpec {
|
|
if len(plugins) == 0 {
|
|
return nil
|
|
}
|
|
out := make([]agentexec.PluginSpec, len(plugins))
|
|
for i, p := range plugins {
|
|
out[i] = agentexec.PluginSpec{Name: p.Name, Src: p.Src}
|
|
}
|
|
return out
|
|
}
|
|
|
|
// 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 "Follow these project-specific guidelines:\n\n" + tc.SkillBody + "\n\n---\n\n" + mission
|
|
}
|
|
|
|
// loadSkillBody loads the SKILL.md body and plugins for the current
|
|
// workflow from the worktree's .agents/skills/ directory. Skills declare
|
|
// their workflow in metadata.archie.workflow -- no hardcoded mapping.
|
|
// When metadata.archie.plugins is non-empty, only the listed plugin files
|
|
// are loaded in declared order; otherwise all *.go files are globbed.
|
|
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)
|
|
if body != "" && tc.SkillPlugins == nil {
|
|
var pluginNames []string
|
|
if fm.Metadata.Archie != nil {
|
|
pluginNames = fm.Metadata.Archie.Plugins
|
|
}
|
|
plugins, _ := skill.LoadPlugins(tc.Dir, entry.Dir, pluginNames)
|
|
tc.SkillPlugins = plugins
|
|
}
|
|
return body
|
|
}
|