feat: close Gap 1 — per-task agent (multi-stage batch execution)

HandleMessage now supports two modes:
- Single-stage (Request only): backward compatible, no Workflow set
- Per-task batch (Workflow + Stages): runs all stages sequentially,
  accumulates tokens/iterations/notes, sets TaskCompleted on success

New fields:
- AgentRequestMessage.Stages []Request — batch of agent stages
- AgentResponseEnvelope.TaskCompleted bool — true when batch done

RunnerFactory injection for testability — HandleMessage accepts a
factory function. DefaultRunnerFactory creates InProcessRunner.
Tests use mockRunner.

runStages() executes each stage, stops on first failure, aggregates
results. Combined summary uses "[stage] summary" format.
This commit is contained in:
sam committed 2026-07-22 03:20:37 +10:00
1 parent e8ffa20b33
commit ce9ce050ed
4 files changed
+169 -57

No files matched your search

+1 -1
View File
@@ -155,7 +155,7 @@ func handle(ctx context.Context, msg jetstream.Msg, nc *nats.Conn, log *slog.Log
"reply_to", replyTo,
)
resp, err := agentexec.HandleMessage(ctx, req, log)
resp, err := agentexec.HandleMessage(ctx, req, log, agentexec.DefaultRunnerFactory)
if err != nil {
return fmt.Errorf("handle: %w", err)
}
+8 -10
View File
@@ -14,10 +14,8 @@ import (
)
// AgentRequestMessage is the NATS payload for an agent stage execution request.
// The Workflow field tells the agent which workflow to run (implement, tdd,
// feasibility, bootstrap) — the agent may execute multiple stages for one task.
// Channel selects the response routing: "response" (default, daemon-reviewed
// then forwarded to humans) or "system" (internal, never forwarded). PRD §2.
// When Workflow is set and Stages is populated, the agent runs all stages as a
// per-task batch rather than a single stage. PRD §1.
type AgentRequestMessage struct {
TaskID int64 `json:"task_id"`
Attempt int `json:"attempt"`
@@ -26,17 +24,17 @@ type AgentRequestMessage struct {
Channel string `json:"channel,omitempty"` // "response" (default) or "system"
Workspace string `json:"workspace"`
Request Request `json:"request"`
Stages []Request `json:"stages,omitempty"` // batch: all agent stages for this task
Providers map[string]Provider `json:"providers,omitempty"`
}
// AgentResponseEnvelope is the response payload published to the reply inbox.
// Channel distinguishes agent output for humans ("response") from internal
// messages the daemon never forwards ("system"). PRD §2.
type AgentResponseEnvelope struct {
Version int `json:"version"`
Result Result `json:"result"`
Error string `json:"error,omitempty"`
Channel string `json:"channel,omitempty"` // "response" (default) or "system"
Version int `json:"version"`
Result Result `json:"result"`
Error string `json:"error,omitempty"`
Channel string `json:"channel,omitempty"` // "response" (default) or "system"
TaskCompleted bool `json:"task_completed,omitempty"` // true when all stages finished (per-task mode)
}
const defaultAgentTimeout = 30 * time.Minute
+83 -32
View File
@@ -15,53 +15,104 @@ import (
arnats "github.com/samcharles93/archie-core/internal/nats"
)
// ── helpers ──────────────────────────────────────────────────────────
type mockRunner struct{}
func (m *mockRunner) Run(_ context.Context, _ string, req Request) (Result, error) {
return Result{
Version: ProtocolVersion,
TaskID: req.TaskID,
Attempt: req.Attempt,
Stage: req.Stage,
Status: StatusPassed,
Summary: "mock:" + req.Mission,
TokensUsed: 10,
Iterations: 1,
}, nil
}
var mockFactory = func(providers map[string]Provider, log *slog.Logger) Runner {
return &mockRunner{}
}
// ── regression: Gap 1 — per-task agent ──────────────────────────────
func TestHandleMessageReadsWorkflowField(t *testing.T) {
// Gap 1: archie-agent is per-stage, not per-task.
// PRD section 1: the agent runs full multi-stage workflows, not
// individual stages. When HandleMessage receives a message with
// Workflow set, its behaviour must differ from a single-stage
// execution. Currently HandleMessage ignores the Workflow field.
msg := AgentRequestMessage{
// PRD section 1: when the daemon sends a task-level message with
// Workflow="implement" and Stages populated, the agent must run all
// stages as a batch. Single-stage mode (Request only) is the
// backward-compatible fallback.
ws := t.TempDir()
providers := map[string]Provider{"test": {Class: "openai", APIKeyEnv: "FAKE"}}
// Single-stage mode: uses Request, no Workflow, no Stages.
singleMsg := AgentRequestMessage{
TaskID: 1,
Attempt: 1,
Stage: "plan",
Workspace: t.TempDir(),
Workspace: ws,
Request: Request{
Version: ProtocolVersion,
TaskID: 1,
Attempt: 1,
Stage: "plan",
Model: "test/model",
Mission: "test",
Budget: Budget{MaxSteps: 1, MaxTokens: 10},
Version: ProtocolVersion, TaskID: 1, Attempt: 1,
Stage: "plan", Model: "test/model", Mission: "single",
Budget: Budget{MaxSteps: 1, MaxTokens: 10},
},
Providers: map[string]Provider{"test": {Class: "openai", APIKeyEnv: "FAKE"}},
Providers: providers,
}
// With Workflow empty: single-stage mode (current behaviour).
withoutWorkflow, err := HandleMessage(context.Background(), msg, slog.New(slog.DiscardHandler))
mockFactory := func(providers map[string]Provider, log *slog.Logger) Runner {
return &mockRunner{}
}
singleResp, err := HandleMessage(context.Background(), singleMsg, slog.New(slog.DiscardHandler), mockFactory)
if err != nil {
t.Fatal(err)
}
if singleResp.TaskCompleted {
t.Error("single-stage mode set TaskCompleted=true — should be false")
}
// With Workflow set: should trigger per-task mode.
msg.Workflow = "implement"
withWorkflow, err := HandleMessage(context.Background(), msg, slog.New(slog.DiscardHandler))
// Per-task mode: Workflow set, Stages populated with two stages.
multiMsg := AgentRequestMessage{
TaskID: 2,
Attempt: 1,
Stage: "plan",
Workflow: "implement",
Workspace: ws,
Request: Request{
Version: ProtocolVersion, TaskID: 2, Attempt: 1,
Stage: "plan", Model: "test/model", Mission: "multi-1",
Budget: Budget{MaxSteps: 1, MaxTokens: 10},
},
Stages: []Request{
{
Version: ProtocolVersion, TaskID: 2, Attempt: 1,
Stage: "plan", Model: "test/model", Mission: "multi-plan",
Budget: Budget{MaxSteps: 1, MaxTokens: 10},
},
{
Version: ProtocolVersion, TaskID: 2, Attempt: 1,
Stage: "build", Model: "test/model", Mission: "multi-build",
Budget: Budget{MaxSteps: 1, MaxTokens: 10},
},
},
Providers: providers,
}
multiResp, err := HandleMessage(context.Background(), multiMsg, slog.New(slog.DiscardHandler), mockFactory)
if err != nil {
t.Fatal(err)
}
// The responses MUST differ when Workflow is set — the agent must
// process the full workflow, not just one stage. Currently both
// paths are identical (Workflow is ignored).
if withoutWorkflow.Result.Status == withWorkflow.Result.Status &&
withoutWorkflow.Result.Summary == withWorkflow.Result.Summary {
t.Error("Gap 1: HandleMessage ignores the Workflow field. " +
"With and without Workflow produce identical results. " +
"The agent must run the full multi-stage workflow when Workflow is set, " +
"not just a single stage. See PRD section 1.")
if !multiResp.TaskCompleted {
t.Error("Gap 1: per-task mode did not set TaskCompleted=true. " +
"The agent must signal task completion when all stages in a " +
"workflow batch have been processed.")
}
// Batch results must aggregate from both stages.
if multiResp.Result.TokensUsed == singleResp.Result.TokensUsed &&
multiResp.Result.Iterations == singleResp.Result.Iterations {
t.Error("Gap 1: per-task mode produced same token/iteration counts " +
"as single-stage mode. Multi-stage batch must accumulate " +
"results from all stages. See PRD section 1.")
}
}
@@ -93,7 +144,7 @@ func TestHandleMessageRoutesSystemMessagesSeparately(t *testing.T) {
}
// Normal stage request — should route to response channel.
resp, err := HandleMessage(context.Background(), msg, slog.New(slog.DiscardHandler))
resp, err := HandleMessage(context.Background(), msg, slog.New(slog.DiscardHandler), mockFactory)
if err != nil {
t.Fatal(err)
}
@@ -105,7 +156,7 @@ func TestHandleMessageRoutesSystemMessagesSeparately(t *testing.T) {
// system channel. Currently HandleMessage always returns "response".
// The daemon sets Channel on the request to indicate message type.
msg.Channel = "system"
sysResp, err := HandleMessage(context.Background(), msg, slog.New(slog.DiscardHandler))
sysResp, err := HandleMessage(context.Background(), msg, slog.New(slog.DiscardHandler), mockFactory)
if err != nil {
t.Fatal(err)
}
+77 -14
View File
@@ -7,15 +7,20 @@ import (
"fmt"
"io"
"log/slog"
"strings"
)
const maxProtocolBytes = 8 << 20
// ServeOne decodes and executes exactly one invocation. Stdout contains only
// the response envelope; callers should direct the supplied logger to stderr.
// DefaultRunnerFactory creates an InProcessRunner backed by the ai-sdk runtime.
func DefaultRunnerFactory(providers map[string]Provider, log *slog.Logger) Runner {
return NewInProcessRunner(NewRuntime(providers), log)
}
// ServeOne decodes and executes exactly one invocation.
func ServeOne(ctx context.Context, in io.Reader, out io.Writer, log *slog.Logger) error {
return serveOne(ctx, in, out, func(invocation Invocation) Runner {
return NewInProcessRunner(NewRuntime(invocation.Providers), log)
return DefaultRunnerFactory(invocation.Providers, log)
})
}
@@ -45,24 +50,31 @@ func serveOne(ctx context.Context, in io.Reader, out io.Writer, newRunner func(I
// ReplyFunc sends a response back to the daemon.
type ReplyFunc func(data []byte) error
// HandleMessage processes one AgentRequestMessage by running the appropriate
// workflow stage. It exists so the agent's message processing is testable
// independently of NATS transport.
//
// Gap 1: currently runs ONE stage. Must be changed to run the full multi-stage
// workflow named in msg.Workflow.
func HandleMessage(ctx context.Context, msg AgentRequestMessage, log *slog.Logger) (*AgentResponseEnvelope, error) {
llm := NewRuntime(msg.Providers)
if llm == nil {
// RunnerFactory creates a Runner from provider config. In production this
// calls NewRuntime + NewInProcessRunner; tests inject a mock.
type RunnerFactory func(Providers map[string]Provider, log *slog.Logger) Runner
// HandleMessage processes one AgentRequestMessage. When msg.Stages is
// populated and msg.Workflow is set, it runs all stages as a per-task
// batch. Otherwise it falls back to single-stage execution.
func HandleMessage(ctx context.Context, msg AgentRequestMessage, log *slog.Logger, newRunner RunnerFactory) (*AgentResponseEnvelope, error) {
runner := newRunner(msg.Providers, log)
if runner == nil {
return nil, fmt.Errorf("no providers configured in request")
}
runner := NewInProcessRunner(llm, log)
result, runErr := runner.Run(ctx, msg.Workspace, msg.Request)
channel := msg.Channel
if channel == "" {
channel = "response"
}
// Per-task mode: run all stages for this workflow as a batch.
if msg.Workflow != "" && len(msg.Stages) > 0 {
return runStages(ctx, runner, msg, channel, log)
}
// Single-stage mode (backward compatible).
result, runErr := runner.Run(ctx, msg.Workspace, msg.Request)
resp := &AgentResponseEnvelope{
Version: msg.Request.Version,
Result: result,
@@ -74,6 +86,57 @@ func HandleMessage(ctx context.Context, msg AgentRequestMessage, log *slog.Logge
return resp, nil
}
// runStages executes every stage in msg.Stages sequentially, accumulating
// tokens, iterations, and notes. The first failure stops the batch and
// returns immediately. On success, TaskCompleted is set.
func runStages(ctx context.Context, runner Runner, msg AgentRequestMessage, channel string, log *slog.Logger) (*AgentResponseEnvelope, error) {
var (
totalTokens int
totalIter int
lastResult Result
combinedNotes []string
combinedDetail []string
)
for i, stage := range msg.Stages {
log.Info("running stage", "stage", stage.Stage, "batch", fmt.Sprintf("%d/%d", i+1, len(msg.Stages)))
result, runErr := runner.Run(ctx, msg.Workspace, stage)
if runErr != nil {
resp := &AgentResponseEnvelope{
Version: stage.Version,
Result: result,
Error: runErr.Error(),
Channel: channel,
}
return resp, nil
}
totalTokens += result.TokensUsed
totalIter += result.Iterations
combinedNotes = append(combinedNotes, result.AppendedNotes...)
if result.Summary != "" {
combinedDetail = append(combinedDetail, fmt.Sprintf("[%s] %s", stage.Stage, result.Summary))
}
lastResult = result
if result.Status != StatusPassed {
break
}
}
lastResult.TokensUsed = totalTokens
lastResult.Iterations = totalIter
lastResult.AppendedNotes = combinedNotes
if len(combinedDetail) > 0 {
lastResult.Summary = strings.Join(combinedDetail, "\n")
}
return &AgentResponseEnvelope{
Version: lastResult.Version,
Result: lastResult,
Channel: channel,
TaskCompleted: lastResult.Status == StatusPassed,
}, nil
}
func decodeOne(r io.Reader, value any) error {
data, err := io.ReadAll(io.LimitReader(r, maxProtocolBytes+1))
if err != nil {