Files
archie/internal/agentexec/inprocess.go
T
sam 529b25eada docs: phase 3a — nilerr review, all 11 sites were false positives (qa4)
97 -> 85. Not one of the eleven nilerr findings was a bug.

I called these "real bug candidates" when I planned the phases. I was
wrong, and the reason is worth recording: every site is the same
deliberate idiom, and a linter cannot see intent.

  - inprocess.go (5) and gateway.go (2) are handlers that report a
    problem as TEXT to their consumer. A tool handler returning a Go
    error aborts the tool call; returning "rejected: ..." lets the model
    read the feedback and retry with valid arguments. A chat handler
    returning a Go error surfaces as a gateway fault instead of a usage
    hint to the human.
  - worker.go carries runErr in the response envelope's Error field.
    Returning it as a Go error too would double-report and abort the
    NATS reply.
  - email.go returns nil when Accept fails because context cancellation
    closed the listener. That is a clean shutdown.
  - codesearch.go skips an unreadable entry and continues the walk. A
    best-effort index must not abort on one bad file.
  - skill.go is documented in the function comment already: a
    non-directory skills path means "no skills", not a fatal error.

Annotated each with //nolint:nilerr and the specific reason rather than
excluding the linter by path, so nilerr stays live everywhere else and
the next reader wondering "why nil here?" gets an answer at the site.

This is the phase I insisted on keeping single-session and out of the
subagent fan-out. A worker told to "fix nilerr" would have converted all
eleven to error returns: malformed tool arguments would hard-fail the
agent loop instead of being correctable, chat typos would read as
gateway faults, and shutdown would log spurious errors. Every test would
still have passed.
2026-07-28 01:39:22 +10:00

255 lines
8.5 KiB
Go

package agentexec
import (
"context"
"encoding/json"
"fmt"
"log/slog"
"maps"
"path/filepath"
"strings"
"github.com/samcharles93/ai-sdk/agentloop"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/ai-sdk/runtime"
"github.com/samcharles93/archie-core/internal/skillscript"
"github.com/samcharles93/archie-core/internal/tools"
)
// Runner executes one autonomous stage against an already prepared workspace.
type Runner interface {
Run(ctx context.Context, workspace string, req Request) (Result, error)
}
type loopFunc func(context.Context, agentloop.Config) (agentloop.Result, error)
// InProcessRunner preserves the current execution behavior behind the v1
// agent protocol. It is replaced by a subprocess or container runner without
// changing workflow orchestration.
type InProcessRunner struct {
runtime *runtime.Runtime
log *slog.Logger
run loopFunc
tools *tools.Registry
}
func NewInProcessRunner(
rt *runtime.Runtime,
log *slog.Logger,
registries ...*tools.Registry,
) *InProcessRunner {
runner := &InProcessRunner{runtime: rt, log: log, run: agentloop.Run}
if len(registries) > 0 {
runner.tools = registries[0]
}
return runner
}
func (r *InProcessRunner) Run(ctx context.Context, workspace string, req Request) (Result, error) {
if err := req.Validate(); err != nil {
return Result{}, err
}
if r.runtime == nil {
return Result{}, fmt.Errorf("agent runtime is not configured")
}
if r.run == nil {
return Result{}, fmt.Errorf("agent loop is not configured")
}
notes := &memoryNotes{initial: req.Notes}
captures := make(map[string][]json.RawMessage)
centralTools, err := BuildToolSet(r.tools)
if err != nil {
return Result{}, fmt.Errorf("build central tool set: %w", err)
}
res, err := r.run(ctx, agentloop.Config{
Runtime: r.runtime,
ModelRef: req.Model,
WorkDir: workspace,
Mission: req.Mission,
ExtraRules: req.ExtraRules,
Notes: notes,
Gate: toAgentGate(req.Gate),
Preflight: toAgentCommands(req.Preflight),
Budget: agentloop.Budget(req.Budget),
ReadOnly: req.ReadOnly,
ProtectPaths: protectionMatcher(req.Protection, req.ReadOnly),
Extra: mergeToolSets(
centralTools,
captureToolSet(req.CaptureTools, captures),
scriptToolSet(workspace),
),
Logger: r.logger(req),
})
result := Result{
Version: ProtocolVersion,
TaskID: req.TaskID,
Attempt: req.Attempt,
Stage: req.Stage,
Status: string(res.Status),
StopReason: res.StopReason,
Changes: res.Changes,
Iterations: res.Iterations,
TokensUsed: res.TokensUsed,
Summary: res.Summary,
Detail: res.Detail,
AppendedNotes: notes.appended,
Captures: captures,
}
// agentloop may return a zero-valued status on early exit (model
// connectivity failure, empty response, etc.). Normalise it to a
// known value so protocol validation always passes.
if result.Status == "" {
result.Status = "blocked"
result.Detail = "agent returned no status (possible model connectivity issue)"
}
if cause := context.Cause(ctx); cause != nil {
return result, cause
}
return result, err
}
func (r *InProcessRunner) logger(req Request) *slog.Logger {
if r.log == nil {
return slog.New(slog.DiscardHandler)
}
return r.log.With("task", req.TaskID, "attempt", req.Attempt, "stage", req.Stage, "model", req.Model)
}
func toAgentGate(g Gate) agentloop.GateConfig {
return agentloop.GateConfig{
Commands: toAgentCommands(g.Commands),
MaxConsecutiveFailures: g.MaxConsecutiveFailures,
}
}
func toAgentCommands(commands []Command) []agentloop.GateCommand {
out := make([]agentloop.GateCommand, 0, len(commands))
for _, command := range commands {
out = append(out, agentloop.GateCommand{
Name: command.Name, Argv: command.Argv, ExpectFailure: command.ExpectFailure,
})
}
return out
}
func protectionMatcher(p Protection, readOnly bool) func(string) bool {
if readOnly || len(p.Suffixes)+len(p.Globs) == 0 {
return nil
}
return func(path string) bool {
for _, suffix := range p.Suffixes {
if strings.HasSuffix(path, suffix) {
return true
}
}
for _, glob := range p.Globs {
matchPath := path
if !strings.ContainsAny(glob, `/\`) {
matchPath = filepath.Base(path)
}
if matched, err := filepath.Match(glob, matchPath); err == nil && matched {
return true
}
}
return false
}
}
func captureToolSet(specs []CaptureTool, captures map[string][]json.RawMessage) core.ToolSet {
tools := make(core.ToolSet, len(specs))
for _, spec := range specs {
tools[spec.Name] = core.NewTool(spec.Name, spec.Description, spec.Parameters,
func(_ context.Context, input string) (string, error) {
if spec.MaxCalls > 0 && len(captures[spec.Name]) >= spec.MaxCalls {
return fmt.Sprintf("%s rejected: maximum call count is %d", spec.Name, spec.MaxCalls), nil
}
value := json.RawMessage(input)
if !json.Valid(value) {
return spec.Name + " rejected: arguments are not valid JSON", nil
}
var object map[string]json.RawMessage
if err := json.Unmarshal(value, &object); err != nil {
return spec.Name + " rejected: arguments must be a JSON object", nil //nolint:nilerr // the agent loop must see malformed tool arguments as feedback it can correct, not as a failed tool call
}
for _, field := range spec.RequiredFields {
if _, ok := object[field]; !ok {
return fmt.Sprintf("%s rejected: %s is required", spec.Name, field), nil
}
}
for _, field := range spec.NonEmptyStrings {
var text string
if raw, ok := object[field]; !ok || json.Unmarshal(raw, &text) != nil || strings.TrimSpace(text) == "" {
return fmt.Sprintf("%s rejected: %s must be a non-empty string", spec.Name, field), nil //nolint:nilerr // same: a rejection message lets the model retry with a valid argument
}
}
for _, field := range spec.BooleanFields {
var value bool
if raw, ok := object[field]; !ok || json.Unmarshal(raw, &value) != nil {
return fmt.Sprintf("%s rejected: %s must be a boolean", spec.Name, field), nil //nolint:nilerr // same: a rejection message lets the model retry with a valid argument
}
}
captures[spec.Name] = append(captures[spec.Name], append(json.RawMessage(nil), value...))
return spec.Name + " recorded", nil
})
}
return tools
}
// scriptToolSet exposes run_go_script: interpreting a Yaegi Go script
// bundled with a skill (.agents/skills/<skill>/scripts/*.go) or living
// anywhere else in the workspace, and returning what it printed. This is
// how an agent following a skill's instructions ("run scripts/gitleaks.go
// to scan for secrets") actually executes a .go helper without a Go
// toolchain in the sandbox.
func scriptToolSet(workspace string) core.ToolSet {
const params = `{"type":"object","properties":{"path":{"type":"string","description":"Path to the .go script, relative to the workspace root."}},"required":["path"]}`
return core.ToolSet{
"run_go_script": core.NewTool(
"run_go_script",
"Run a Yaegi-interpreted Go script (e.g. a skill's bundled scripts/*.go helper) and return everything it printed.",
json.RawMessage(params),
func(_ context.Context, input string) (string, error) {
var args struct {
Path string `json:"path"`
}
if err := json.Unmarshal([]byte(input), &args); err != nil || strings.TrimSpace(args.Path) == "" {
return "run_go_script rejected: arguments must be a JSON object with a non-empty path field", nil //nolint:nilerr // same: a rejection message lets the model retry with a valid path
}
full := filepath.Join(workspace, args.Path)
if rel, err := filepath.Rel(workspace, full); err != nil || strings.HasPrefix(rel, "..") {
return "run_go_script rejected: path escapes the workspace", nil //nolint:nilerr // same: a rejection message lets the model retry with a valid path
}
out, err := skillscript.Run(full)
if err != nil {
return fmt.Sprintf("run_go_script failed: %v\n%s", err, out), nil
}
return out, nil
},
),
}
}
// mergeToolSets combines tool sets into one; later sets win on name
// collisions.
func mergeToolSets(sets ...core.ToolSet) core.ToolSet {
merged := core.ToolSet{}
for _, set := range sets {
maps.Copy(merged, set)
}
return merged
}
type memoryNotes struct {
initial string
appended []string
}
func (n *memoryNotes) Load(context.Context) (string, error) { return n.initial, nil }
func (n *memoryNotes) Append(_ context.Context, entry string) error {
n.appended = append(n.appended, entry)
return nil
}