Merge branch 'crew/cluster1' into crew-integration

This commit is contained in:
sam committed 2026-09-15 10:33:15 +10:00
commit 49da68fb25
13 files changed
+63 -1747

No files matched your search

+1 -1
View File
@@ -20,7 +20,7 @@ Every claim in this document is mapped to what exists in the tree today.
| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go:112` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |
| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |
| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: "orchestration across missions lives with the caller". No caller does this yet |
| Parallel-safe tool execution | **Implemented, no production caller** | `internal/tools/dispatch.go` `ExecutionClass` (`ExecParallelSafe` auto-derived from `ClassIdempotent`; `ClassRead` does not exist). `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry` have **zero non-test callers**; live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |
| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |
| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go:44`); no **aggregate** turn cap by design (`toolset.go:62`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |
| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go:199`) |
| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go:247` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |
@@ -11,6 +11,7 @@ import (
"strconv"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/workflow"
"github.com/samcharles93/archie-core/internal/domain/workflow/skillbuild"
"github.com/samcharles93/archie-core/internal/domain/workflow/wfeval"
@@ -138,6 +139,22 @@ func newTaskRunner(providers map[string]agentexec.Provider, log *slog.Logger) ag
return agentexec.NewLoopRunner(agentexec.NewRuntime(providers), log)
}
// applyToolLimits wires the task's carried tool policy into a *LoopRunner's
// result cap/spill, so a worker-executed stage enforces the same limits the
// daemon's own chat path applies (config.Config.Tools.Policy, carried
// non-secret via TaskConfig.ToolPolicy). A runner that isn't a *LoopRunner
// (e.g. a test fake) is left untouched.
func applyToolLimits(agent agentexec.Runner, policy config.ToolPolicy) {
runner, ok := agent.(*agentexec.LoopRunner)
if !ok {
return
}
runner.Limits = agentexec.ToolLimits{
MaxResultChars: policy.MaxResultChars,
SpillDir: policy.SpillDir,
}
}
// routeTask applies the request-carried routing bindings and selects the
// workflow for a task. The daemon's package-level SetKindWorkflows state
// never crosses the process boundary, so runTask installs the resolved
@@ -191,6 +208,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen
if agent == nil {
return nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID)
}
applyToolLimits(agent, req.Cfg.ToolPolicy)
agent = persistentRunner{Runner: agent, enabled: req.Repo.PersistentStorage}
// A workflow run in this process publishes to an in-process *events.Bus
@@ -195,6 +195,29 @@ func TestHybridTreesPushSurfacesOwnershipReconciliationFailure(t *testing.T) {
}
}
// TestApplyToolLimitsWiresConfiguredPolicyIntoLoopRunner guards against
// regressing archie-core's tool-result cap and spill dir back to inert
// zero values on the worker path (agentexec-1 / tools-core-11): a
// *LoopRunner built for a task must carry the daemon's configured
// ToolPolicy, not the zero value NewLoopRunner leaves it at.
func TestApplyToolLimitsWiresConfiguredPolicyIntoLoopRunner(t *testing.T) {
runner := agentexec.NewLoopRunner(agentexec.NewRuntime(nil), slog.New(slog.DiscardHandler))
policy := config.ToolPolicy{MaxResultChars: 12345, SpillDir: "/var/tmp/archie-spill"}
applyToolLimits(runner, policy)
want := agentexec.ToolLimits{MaxResultChars: 12345, SpillDir: "/var/tmp/archie-spill"}
if runner.Limits != want {
t.Fatalf("runner.Limits = %+v, want %+v", runner.Limits, want)
}
}
// TestApplyToolLimitsIgnoresNonLoopRunner confirms a test-fake runner (which
// is not a *agentexec.LoopRunner) is left untouched rather than panicking.
func TestApplyToolLimitsIgnoresNonLoopRunner(t *testing.T) {
applyToolLimits(panicRunner{t}, config.ToolPolicy{MaxResultChars: 1})
}
type panicRunner struct{ t *testing.T }
func (r panicRunner) Run(context.Context, string, agentexec.Request, agentexec.ToolCallReporter) (agentexec.Result, error) {
+7
View File
@@ -173,6 +173,10 @@ var reloadableFields = map[string]bool{
// [agent] is a decode-only compatibility shim; changes have no runtime
// consumer and therefore require neither reload nor restart.
"LegacyAgent": true,
// Tools.Policy (MaxResultChars/SpillDir) is carried into TaskConfig by
// ForTask (config.go) and applied fresh per dispatch via
// agentworker.applyToolLimits. See reloadableSubFields["Tools"].
"ToolPolicy": true,
}
// reloadableSubFields are sub-fields of structs that are otherwise
@@ -188,6 +192,9 @@ var reloadableFields = map[string]bool{
var reloadableSubFields = map[string]map[string]bool{
"Containers": {"LegacyEnabled": true, "VolumeTTL": true},
"Forge": {"Host": true},
// Policy is carried into TaskConfig by ForTask (config.go); MCPServers,
// WebFetch and Minimax are not and stay requires-restart.
"Tools": {"Policy": true},
}
// changedNonReloadableFields compares old and new and returns the
+3
View File
@@ -590,6 +590,7 @@ type TaskConfig struct {
DiffCapLines int `json:"diff_cap_lines"`
Notify Notify `json:"notify"`
Forge TaskForge `json:"forge"`
ToolPolicy ToolPolicy `json:"tool_policy"`
}
// TaskForge is the non-secret forge configuration needed by workflow stages.
@@ -610,6 +611,7 @@ func (c Config) ForTask() TaskConfig {
DiffCapLines: c.DiffCapLines,
Notify: c.Notify,
Forge: TaskForge{Host: c.Forge.Host},
ToolPolicy: c.Tools.Policy,
}
}
@@ -628,6 +630,7 @@ func (tc TaskConfig) ToConfig() Config {
DiffCapLines: tc.DiffCapLines,
Notify: tc.Notify,
Forge: Forge{Host: tc.Forge.Host},
Tools: ToolsConfig{Policy: tc.ToolPolicy},
}
}
+8 -2
View File
@@ -20,9 +20,13 @@ func TestTaskConfigToConfigRoundTrip(t *testing.T) {
Dispatch: Dispatch{Trigger: "label", AckReaction: "eyes", Labels: map[string]string{"working": "bot:working"}},
Notify: Notify{Webhook: "https://notify.example.test/hook"},
Forge: Forge{Type: "github", Host: "https://forge.example.test", Token: SecretRef{Engine: "env", Key: "TOP_SECRET"}},
Tools: ToolsConfig{Policy: ToolPolicy{MaxResultChars: 50_000, SpillDir: "/var/tmp/archie-spill"}},
}
got := cfg.ForTask().ToConfig()
if got.Tools.Policy != cfg.Tools.Policy {
t.Fatalf("Tools.Policy = %#v, want %#v", got.Tools.Policy, cfg.Tools.Policy)
}
if !reflect.DeepEqual(got.Models, cfg.Models) {
t.Fatalf("Models = %#v, want %#v", got.Models, cfg.Models)
}
@@ -110,7 +114,8 @@ func TestConfigForTaskJSONRoundTrip(t *testing.T) {
Providers: map[string]Provider{
"secret": {APIKeyEnv: "TOP_SECRET_PROVIDER_TOKEN"},
},
NATS: NATSConfig{TokenEnv: "TOP_SECRET_NATS_TOKEN"},
NATS: NATSConfig{TokenEnv: "TOP_SECRET_NATS_TOKEN"},
Tools: ToolsConfig{Policy: ToolPolicy{MaxResultChars: 50_000, SpillDir: "/var/tmp/archie-spill"}},
}
want := TaskConfig{
@@ -122,6 +127,7 @@ func TestConfigForTaskJSONRoundTrip(t *testing.T) {
DiffCapLines: cfg.DiffCapLines,
Notify: cfg.Notify,
Forge: TaskForge{Host: cfg.Forge.Host},
ToolPolicy: cfg.Tools.Policy,
}
got := cfg.ForTask()
if !reflect.DeepEqual(got, want) {
@@ -148,7 +154,7 @@ func TestConfigForTaskJSONRoundTrip(t *testing.T) {
if err != nil {
t.Fatal(err)
}
assertJSONKeys(t, data, "bot_user", "bot_email", "models", "budgets", "dispatch", "diff_cap_lines", "notify", "forge")
assertJSONKeys(t, data, "bot_user", "bot_email", "models", "budgets", "dispatch", "diff_cap_lines", "notify", "forge", "tool_policy")
var forgePayload map[string]json.RawMessage
var payload map[string]json.RawMessage
+3 -111
View File
@@ -16,7 +16,6 @@ import (
"encoding/json"
"errors"
"fmt"
"strings"
"sync"
"time"
)
@@ -68,10 +67,9 @@ type Tool struct {
// Registry holds all registered tools and provides thread-safe access.
type Registry struct {
mu sync.RWMutex
tools map[string]Tool
order []string // insertion order for deterministic iteration
pluginToolExecutor PluginToolExecutor
mu sync.RWMutex
tools map[string]Tool
order []string // insertion order for deterministic iteration
}
// NewRegistry creates an empty tool registry.
@@ -191,109 +189,3 @@ func (r *Registry) Count() int {
return len(r.tools)
}
// PluginToolDef describes a tool provided by a plugin.
type PluginToolDef struct {
Name string
Description string
InputSchema string // JSON Schema as string
}
// PluginToolExecutor is called by the registry when a plugin tool is executed.
type PluginToolExecutor func(ctx context.Context, pluginName, toolName string, args json.RawMessage) (Result, error)
// SetPluginToolExecutor sets the executor for plugin tools. The executor is
// called whenever a plugin-registered tool is invoked by the agent.
func (r *Registry) SetPluginToolExecutor(executor PluginToolExecutor) {
r.mu.Lock()
defer r.mu.Unlock()
r.pluginToolExecutor = executor
}
// pluginToolSep joins a plugin name and its tool name into the registry's
// public tool identifier. It must satisfy the function-name pattern that
// OpenAI-compatible providers enforce (^[a-zA-Z0-9_-]+$), so it cannot be ".".
const pluginToolSep = "__"
// sanitizePluginToolName maps an arbitrary name to the ^[a-zA-Z0-9_-]+$
// character set that OpenAI-compatible providers require for function names,
// replacing any other character with '_'. This is applied centrally to every
// plugin tool so plugin authors can return natural names (the MCP spec, for
// one, places no character constraints on tool names) without each plugin
// re-implementing provider name rules.
func sanitizePluginToolName(s string) string {
var b strings.Builder
b.Grow(len(s))
for _, r := range s {
switch {
case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_', r == '-':
b.WriteRune(r)
default:
b.WriteByte('_')
}
}
if b.Len() == 0 {
return "tool"
}
return b.String()
}
// RegisterPluginTool registers a tool from a plugin in the registry.
//
// The public, LLM-facing name is the plugin name and tool name, sanitised to the
// provider-safe character set and joined with pluginToolSep. Sanitising here -
// once, for every plugin - means plugin authors can return whatever names their
// upstream uses. Execution routes back to the plugin with its ORIGINAL, unmodified
// tool name (captured in the closure below), so the plugin never sees the
// sanitised form and needs no name translation of its own.
//
// Returns an error if the resulting name is already registered.
func (r *Registry) RegisterPluginTool(pluginName string, def PluginToolDef) error {
toolName := sanitizePluginToolName(pluginName) + pluginToolSep + sanitizePluginToolName(def.Name)
reg := r // capture for closure
tool := Tool{
Schema: Schema{
Name: toolName,
Description: "[" + pluginName + "] " + def.Description,
},
Execute: func(ctx context.Context, params json.RawMessage, ui UIBridge) (Result, error) {
reg.mu.RLock()
exec := reg.pluginToolExecutor
reg.mu.RUnlock()
if exec == nil {
return Result{IsError: true, Content: "plugin executor not available"}, nil
}
return exec(ctx, pluginName, def.Name, params)
},
Source: "plugin:" + pluginName,
}
if def.InputSchema != "" {
tool.Schema.Parameters = json.RawMessage(def.InputSchema)
}
return r.Replace(tool)
}
// UnregisterPluginTools removes all tools belonging to a plugin.
// Plugin tools are identified by the sanitised "pluginName__" prefix in their
// names (see RegisterPluginTool).
func (r *Registry) UnregisterPluginTools(pluginName string) {
prefix := sanitizePluginToolName(pluginName) + pluginToolSep
r.mu.Lock()
defer r.mu.Unlock()
for name := range r.tools {
if strings.HasPrefix(name, prefix) {
delete(r.tools, name)
r.order = removeFromOrder(r.order, name)
}
}
}
func removeFromOrder(order []string, name string) []string {
for i, n := range order {
if n == name {
return append(order[:i], order[i+1:]...)
}
}
return order
}
-36
View File
@@ -3,7 +3,6 @@ package builtin_test
import (
"context"
"encoding/json"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/tools/builtin"
@@ -152,38 +151,3 @@ func TestRegistry_Validation(t *testing.T) {
t.Fatal("expected error for nil executor")
}
}
// TestRegistry_PluginToolSanitizesName verifies that the registry (not each
// plugin) makes plugin tool names safe for OpenAI-compatible providers, while
// routing execution back to the plugin with its ORIGINAL, unmodified names.
func TestRegistry_PluginToolSanitizesName(t *testing.T) {
r := builtin.NewRegistry()
var gotPlugin, gotTool string
r.SetPluginToolExecutor(func(_ context.Context, pluginName, toolName string, _ json.RawMessage) (builtin.Result, error) {
gotPlugin, gotTool = pluginName, toolName
return builtin.Result{Content: "ok"}, nil
})
// A plugin returns a natural name containing a '.' - invalid for the provider.
if err := r.RegisterPluginTool("mcp-plugin", builtin.PluginToolDef{Name: "spawn.list_issues"}); err != nil {
t.Fatal(err)
}
// The public, LLM-facing name is sanitised.
const want = "mcp-plugin__spawn_list_issues"
tool, ok := r.Get(want)
if !ok {
t.Fatalf("expected registered tool %q; got names %v", want, r.Names())
}
if strings.ContainsRune(tool.Schema.Name, '.') {
t.Fatalf("registered name %q still contains '.'", tool.Schema.Name)
}
// Execution routes back to the plugin with the ORIGINAL plugin and tool names.
if _, err := tool.Execute(context.Background(), nil, nil); err != nil {
t.Fatal(err)
}
if gotPlugin != "mcp-plugin" || gotTool != "spawn.list_issues" {
t.Fatalf("executor received %q/%q, want mcp-plugin/spawn.list_issues", gotPlugin, gotTool)
}
}
-31
View File
@@ -114,37 +114,6 @@ func TestToolClassificationString(t *testing.T) {
}
}
func TestClassifyEntry(t *testing.T) {
t.Run("idempotent tools are parallel-safe", func(t *testing.T) {
e := ToolEntry{
Name: "reader",
Handler: noopHandler,
Classification: ClassIdempotent,
}
if got := ClassifyEntry(e); got != ExecParallelSafe {
t.Errorf("expected parallel-safe, got %v", got)
}
})
t.Run("mutating tools are never-parallel", func(t *testing.T) {
e := ToolEntry{
Name: "writer",
Handler: noopHandler,
Classification: ClassMutating,
}
if got := ClassifyEntry(e); got != ExecNeverParallel {
t.Errorf("expected never-parallel, got %v", got)
}
})
t.Run("unclassified tools default to never-parallel", func(t *testing.T) {
e := ToolEntry{Name: "unknown", Handler: noopHandler}
if got := ClassifyEntry(e); got != ExecNeverParallel {
t.Errorf("expected never-parallel, got %v", got)
}
})
}
func TestClassificationJSONRoundTrip(t *testing.T) {
e := ToolEntry{
Name: "classified",
-404
View File
@@ -1,404 +0,0 @@
package tools
import (
"context"
"fmt"
"sync"
"time"
)
// ExecutionClass defines how a tool interacts with the dispatch gating engine.
type ExecutionClass int
const (
// ExecNeverParallel marks tools that must run alone -- typically state
// mutators where concurrent execution could cause corruption.
ExecNeverParallel ExecutionClass = iota
// ExecParallelSafe marks tools that can run concurrently with any
// other tool. Read-only tools (idempotent classification) are
// automatically promoted to this class.
ExecParallelSafe
// ExecPathScoped marks tools that can run in parallel with tools
// targeting different paths/scopes, but must serialize with tools
// targeting the same path.
ExecPathScoped
)
// String returns a human-readable representation of the execution class.
func (c ExecutionClass) String() string {
switch c {
case ExecNeverParallel:
return "never-parallel"
case ExecParallelSafe:
return "parallel-safe"
case ExecPathScoped:
return "path-scoped"
default:
return "unknown"
}
}
// ClassifyEntry derives the [ExecutionClass] from a [ToolEntry]'s
// classification flags. Idempotent tools are parallel-safe. Mutating
// tools are never-parallel unless explicitly marked otherwise.
// Unclassified tools default to never-parallel (conservative).
func ClassifyEntry(e ToolEntry) ExecutionClass {
if e.Classification.IsIdempotent() {
return ExecParallelSafe
}
if e.Classification.IsMutating() {
return ExecNeverParallel
}
// Conservative default: treat unclassified tools as never-parallel.
return ExecNeverParallel
}
// ---------------------------------------------------------------------------
// Dispatch types
// ---------------------------------------------------------------------------
// DispatchResult holds the outcome of a single tool invocation.
type DispatchResult struct {
// ToolName is the name of the tool that was invoked.
ToolName string
// Output is the value returned by the tool's Handler. nil when
// IsError is true.
Output any
// Preview is a truncated version of the output suitable for
// inclusion in the conversation context. It is at most 500 chars.
Preview string
// Error is the error returned by the handler or dispatch layer.
Error error
// Duration is the wall-clock time spent executing the tool
// (handler execution only; does not include spill time).
Duration time.Duration
}
// IsError reports whether the result represents a failed invocation.
func (r DispatchResult) IsError() bool { return r.Error != nil }
// previewChars is the maximum length of a result preview.
const previewChars = 500
// truncatePreview returns a short summary of the output suitable for
// the conversation context.
func truncatePreview(output any) string {
if output == nil {
return ""
}
s := fmt.Sprint(output)
if len(s) <= previewChars {
return s
}
return s[:previewChars] + "... [truncated]"
}
// ---------------------------------------------------------------------------
// Tool invocation
// ---------------------------------------------------------------------------
// ToolCall represents a single pending tool invocation.
type ToolCall struct {
// Entry is the tool to invoke. Handler must be non-nil.
Entry ToolEntry
// Input is the deserialized JSON input to pass to the handler.
Input map[string]any
// PathScope is an optional key used by ExecPathScoped gating.
// Tools with the same non-empty PathScope are serialized.
PathScope string
}
// invokeTool executes a single tool and returns a [DispatchResult].
//
// Tools that require human approval are refused. The dispatch path has no
// ApprovalRequester — it is used by the agent execution loop, which runs
// without a human in the loop. The chat path gates approval through
// BuildToolSetFrom → toolExecute, which has the approver wired.
func invokeTool(ctx context.Context, call ToolCall) DispatchResult {
start := time.Now()
result := DispatchResult{ToolName: call.Entry.Name}
if call.Entry.Classification.IsApprovalRequired() {
result.Error = fmt.Errorf("tool %s: requires human approval and cannot be invoked through the agent dispatch path", call.Entry.Name)
return result
}
output, err := call.Entry.Handler(ctx, call.Input)
result.Duration = time.Since(start)
if err != nil {
result.Error = err
return result
}
result.Output = output
result.Preview = truncatePreview(output)
return result
}
// ---------------------------------------------------------------------------
// 17.5 -- Sequential dispatch
// ---------------------------------------------------------------------------
// DispatchSequential invokes tools one at a time, capturing per-result
// previews and classifying errors. Each result includes a truncated
// preview for inclusion in the conversation context.
//
// spillDir controls displacement of individual oversized results. Aggregate
// output volume never stops dispatch.
//
// If guardrail is non-nil, failures are recorded and the dispatch may
// abort early on a hard-stop decision.
func DispatchSequential(
ctx context.Context,
calls []ToolCall,
spillDir string,
guardrail *GuardrailEngine,
) []DispatchResult {
results := make([]DispatchResult, 0, len(calls))
for _, call := range calls {
// Check for hard-stop before dispatching.
if guardrail != nil && guardrail.HardStopped() {
results = append(results, DispatchResult{
ToolName: call.Entry.Name,
Error: fmt.Errorf("guardrail hard-stop active"),
})
break
}
result := dispatchOne(ctx, call, spillDir, guardrail)
results = append(results, result)
// Abort on hard-stop.
if guardrail != nil && guardrail.HardStopped() {
break
}
}
return results
}
// ---------------------------------------------------------------------------
// 17.6 -- Concurrent dispatch
// ---------------------------------------------------------------------------
// gatedGroup holds a set of calls that must run sequentially within the
// group but can run concurrently with other groups.
type gatedGroup struct {
calls []ToolCall
class ExecutionClass
scope string // non-empty only for ExecPathScoped
}
// DispatchConcurrent invokes tools concurrently where safe, applying
// execution gating:
//
// - ExecNeverParallel: runs alone, blocking all other execution.
// - ExecParallelSafe: runs concurrently with any other tool.
// - ExecPathScoped: same-path tools serialize, different paths run
// in parallel.
//
// Results are returned in the same order as calls.
func DispatchConcurrent(
ctx context.Context,
calls []ToolCall,
spillDir string,
guardrail *GuardrailEngine,
) []DispatchResult {
if len(calls) == 0 {
return nil
}
// Classify each call and build gating groups.
groups := buildGatingGroups(calls)
// Execute groups: never-parallel groups block all concurrency.
// Others run in parallel within their group, sequentially between groups.
results := make([]DispatchResult, len(calls))
resultIdx := 0
for _, group := range groups {
if group.class == ExecNeverParallel || len(group.calls) == 1 {
// Run sequentially.
for _, call := range group.calls {
results[resultIdx] = dispatchOne(ctx, call, spillDir, guardrail)
resultIdx++
}
} else {
// Run in parallel within group.
res := dispatchParallel(ctx, group.calls, spillDir, guardrail)
for _, r := range res {
results[resultIdx] = r
resultIdx++
}
}
}
return results
}
// buildGatingGroups partitions calls into groups based on their execution
// class. Never-parallel calls get isolated groups. Path-scoped calls share
// a group if they have the same path; otherwise they get separate groups.
// Parallel-safe calls all share one group.
//
// Groups are tracked by index (not pointer) to avoid the value-copy bug
// where appending to a map-stored pointer was invisible to the slice copy.
func buildGatingGroups(calls []ToolCall) []gatedGroup {
if len(calls) == 0 {
return nil
}
var groups []gatedGroup
// Track path-scoped groups by scope key to index in the groups slice.
pathScopedIdx := make(map[string]int)
for _, call := range calls {
class := ClassifyEntry(call.Entry)
switch class {
case ExecNeverParallel:
// Isolate: one group per never-parallel call.
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecNeverParallel,
})
case ExecPathScoped:
scope := call.PathScope
if scope == "" {
// No scope specified -- treat as never-parallel.
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecNeverParallel,
})
continue
}
if idx, ok := pathScopedIdx[scope]; ok {
// Update existing group in-place through the index.
groups[idx].calls = append(groups[idx].calls, call)
} else {
idx := len(groups)
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecPathScoped,
scope: scope,
})
pathScopedIdx[scope] = idx
}
case ExecParallelSafe:
// Batch all parallel-safe calls into one group.
if idx, ok := firstParallelSafeIdx(groups); ok {
groups[idx].calls = append(groups[idx].calls, call)
} else {
groups = append(groups, gatedGroup{
calls: []ToolCall{call},
class: ExecParallelSafe,
})
}
}
}
return groups
}
// firstParallelSafeIdx returns the index of the first parallel-safe group
// in the slice. Used by buildGatingGroups to batch parallel-safe calls.
func firstParallelSafeIdx(groups []gatedGroup) (int, bool) {
for i := range groups {
if groups[i].class == ExecParallelSafe {
return i, true
}
}
return 0, false
}
// dispatchOne runs a single call with guardrail and per-tool limit checks.
//
// Callers that do not own the batch cannot use this: it caps
// DispatchResult.Preview, whereas a caller handing the result straight to a
// model has to cap the payload it actually sends. [CapPayload] is the shared
// rule between the two; this sequence is specific to batch dispatch.
func dispatchOne(
ctx context.Context,
call ToolCall,
spillDir string,
guardrail *GuardrailEngine,
) DispatchResult {
if guardrail != nil && guardrail.HardStopped() {
return DispatchResult{
ToolName: call.Entry.Name,
Error: fmt.Errorf("guardrail hard-stop active"),
}
}
result := invokeTool(ctx, call)
// Enforce per-tool result size limit (17.4).
enforcePerToolLimit(&result, call.Entry, spillDir)
// Track guardrail.
if guardrail != nil {
if result.IsError() {
_ = guardrail.RecordFailure(call.Entry.Name, result.Error)
} else {
_ = guardrail.RecordSuccess(call.Entry.Name)
}
}
return result
}
// enforcePerToolLimit replaces the preview when the result exceeds the tool's
// MaxResultSizeChars, spilling to disk when a directory is configured and
// truncating inline otherwise. [CapPayload] owns that rule; this only decides
// whether it applies.
//
// Returns whether the result was capped.
func enforcePerToolLimit(result *DispatchResult, entry ToolEntry, spillDir string) bool {
if result.IsError() || entry.MaxResultSizeChars <= 0 || result.Output == nil {
return false
}
fullOutput := fmt.Sprint(result.Output)
capped := CapPayload(entry.Name, fullOutput, entry.MaxResultSizeChars, spillDir)
if capped == fullOutput {
return false
}
result.Preview = capped
return true
}
// dispatchParallel runs multiple calls concurrently and returns results
// in the same order.
func dispatchParallel(
ctx context.Context,
calls []ToolCall,
spillDir string,
guardrail *GuardrailEngine,
) []DispatchResult {
results := make([]DispatchResult, len(calls))
var wg sync.WaitGroup
wg.Add(len(calls))
for i, call := range calls {
go func(idx int, c ToolCall) {
defer wg.Done()
results[idx] = dispatchOne(ctx, c, spillDir, guardrail)
}(i, call)
}
wg.Wait()
return results
}
-645
View File
@@ -1,645 +0,0 @@
package tools
import (
"context"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"sync/atomic"
"testing"
"time"
)
// maxTruncationNotice bounds the explanatory notice CapPayload appends when it
// truncates inline. Tests assert the capped payload plus this allowance, so a
// notice that grew without bound would fail rather than quietly eat context.
const maxTruncationNotice = 128
func TestExecutionClassString(t *testing.T) {
tests := []struct {
c ExecutionClass
want string
}{
{ExecNeverParallel, "never-parallel"},
{ExecParallelSafe, "parallel-safe"},
{ExecPathScoped, "path-scoped"},
{ExecutionClass(99), "unknown"},
}
for _, tt := range tests {
if got := tt.c.String(); got != tt.want {
t.Errorf("String() = %q, want %q", got, tt.want)
}
}
}
func TestTruncatePreview(t *testing.T) {
t.Run("nil output", func(t *testing.T) {
if got := truncatePreview(nil); got != "" {
t.Errorf("expected empty string, got %q", got)
}
})
t.Run("short output passthrough", func(t *testing.T) {
s := "short result"
if got := truncatePreview(s); got != s {
t.Errorf("expected %q, got %q", s, got)
}
})
t.Run("long output truncated", func(t *testing.T) {
long := strings.Repeat("x", previewChars+100)
got := truncatePreview(long)
if len(got) > previewChars+len("... [truncated]") {
t.Errorf("preview too long: %d chars", len(got))
}
if !strings.HasSuffix(got, "... [truncated]") {
t.Error("truncated preview should end with '... [truncated]'")
}
})
}
func TestDispatchResultIsError(t *testing.T) {
r := DispatchResult{}
if r.IsError() {
t.Error("zero result should not be an error")
}
r.Error = errors.New("fail")
if !r.IsError() {
t.Error("result with error should be an error")
}
}
func TestInvokeTool(t *testing.T) {
e := ToolEntry{
Name: "echo",
Handler: echoHandler,
}
result := invokeTool(context.Background(), ToolCall{
Entry: e,
Input: map[string]any{"msg": "hello"},
})
if result.IsError() {
t.Fatalf("unexpected error: %v", result.Error)
}
if result.ToolName != "echo" {
t.Errorf("ToolName = %q, want 'echo'", result.ToolName)
}
if result.Duration <= 0 {
t.Error("duration should be non-zero")
}
if result.Preview == "" {
t.Error("preview should not be empty")
}
}
func TestInvokeToolError(t *testing.T) {
e := ToolEntry{
Name: "failing",
Handler: func(_ context.Context, _ map[string]any) (any, error) {
return nil, errors.New("simulated failure")
},
}
result := invokeTool(context.Background(), ToolCall{Entry: e})
if !result.IsError() {
t.Error("expected error")
}
if result.Preview != "" {
t.Errorf("preview should be empty on error, got %q", result.Preview)
}
}
// --- Sequential dispatch ---
func TestDispatchSequentialEmpty(t *testing.T) {
results := DispatchSequential(context.Background(), nil, "", nil)
if len(results) != 0 {
t.Errorf("expected 0 results, got %d", len(results))
}
}
func TestDispatchSequentialBasic(t *testing.T) {
e := ToolEntry{
Name: "echo",
Handler: echoHandler,
}
calls := []ToolCall{
{Entry: e, Input: map[string]any{"msg": "first"}},
{Entry: e, Input: map[string]any{"msg": "second"}},
}
results := DispatchSequential(context.Background(), calls, "", nil)
if len(results) != 2 {
t.Fatalf("expected 2 results, got %d", len(results))
}
for i, r := range results {
if r.IsError() {
t.Errorf("result %d error: %v", i, r.Error)
}
if r.Preview == "" {
t.Errorf("result %d has empty preview", i)
}
}
}
func TestDispatchSequentialOutputVolumeDoesNotStop(t *testing.T) {
e := ToolEntry{
Name: "big-echo",
Handler: echoHandler,
}
calls := []ToolCall{
{Entry: e, Input: map[string]any{"msg": strings.Repeat("x", 100)}},
{Entry: e, Input: map[string]any{"msg": strings.Repeat("y", 100)}},
}
spillDir := "" // Aggregate output volume never stops dispatch.
results := DispatchSequential(context.Background(), calls, spillDir, nil)
if len(results) != 2 {
t.Fatalf("expected 2 results, got %d", len(results))
}
for i, result := range results {
if result.IsError() {
t.Errorf("result %d failed after accumulated output: %v", i, result.Error)
}
}
}
func TestDispatchSequentialGuardrailHardStop(t *testing.T) {
// First failure warns; second warn hard-stops.
config := ToolCallGuardrailConfig{
ExactFailureWarnAfter: 1,
HardStopAfterWarnRepeat: 2,
}
g := NewGuardrailEngine(config)
e := ToolEntry{
Name: "failing",
Handler: func(_ context.Context, _ map[string]any) (any, error) {
return nil, errors.New("boom")
},
}
calls := []ToolCall{
{Entry: e}, {Entry: e}, {Entry: e},
}
results := DispatchSequential(context.Background(), calls, "", g)
// First call: warn, second call: hard-stop → abort.
// Should stop before completing all 3.
if len(results) < 2 {
t.Fatalf("expected at least 2 results, got %d", len(results))
}
}
// --- Concurrent dispatch ---
func TestDispatchConcurrentEmpty(t *testing.T) {
results := DispatchConcurrent(context.Background(), nil, "", nil)
if len(results) != 0 {
t.Errorf("expected 0 results, got %d", len(results))
}
}
func TestDispatchConcurrentParallel(t *testing.T) {
var order []string
var counter atomic.Int32
makeTool := func(name string) ToolEntry {
return ToolEntry{
Name: name,
Handler: noopHandler,
Classification: ClassIdempotent, // parallel-safe
}
}
calls := []ToolCall{
{Entry: makeTool("a")},
{Entry: makeTool("b")},
{Entry: makeTool("c")},
{Entry: makeTool("d")},
}
results := DispatchConcurrent(context.Background(), calls, "", nil)
if len(results) != 4 {
t.Fatalf("expected 4 results, got %d", len(results))
}
for _, r := range results {
if r.IsError() {
t.Errorf("unexpected error for %s: %v", r.ToolName, r.Error)
}
}
// Sanity: all tools ran.
if counter.Load() < 0 {
t.Error("counter should not be negative")
}
_ = order
}
func TestDispatchConcurrentNeverParallelIsolated(t *testing.T) {
// Mutating tools should run sequentially (never-parallel).
var running atomic.Int32
var maxConcurrent atomic.Int32
makeMutating := func(name string) ToolEntry {
return ToolEntry{
Name: name,
Classification: ClassMutating,
Handler: func(_ context.Context, _ map[string]any) (any, error) {
n := running.Add(1)
if n > maxConcurrent.Load() {
maxConcurrent.Store(n)
}
time.Sleep(10 * time.Millisecond)
running.Add(-1)
return nil, nil
},
}
}
calls := []ToolCall{
{Entry: makeMutating("m1")},
{Entry: makeMutating("m2")},
}
results := DispatchConcurrent(context.Background(), calls, "", nil)
if len(results) != 2 {
t.Fatalf("expected 2 results, got %d", len(results))
}
// Mutating tools are never-parallel → each in its own group → serial.
// Maximum concurrent should be 1.
if maxConcurrent.Load() > 1 {
t.Errorf("mutating tools should be serial; max concurrent was %d", maxConcurrent.Load())
}
}
func TestDispatchConcurrentPathScoped(t *testing.T) {
// Path-scoped tools with the same path serialize; different paths parallelize.
var running atomic.Int32
var maxConcurrent atomic.Int32
makePathScoped := func(name, _ string) ToolEntry {
return ToolEntry{
Name: name,
Classification: ClassIdempotent, // idempotent but we override via PathScope
Handler: func(_ context.Context, _ map[string]any) (any, error) {
n := running.Add(1)
if n > maxConcurrent.Load() {
maxConcurrent.Store(n)
}
time.Sleep(10 * time.Millisecond)
running.Add(-1)
return nil, nil
},
}
}
calls := []ToolCall{
{Entry: makePathScoped("a", "path-1")},
{Entry: makePathScoped("b", "path-2")}, // Different path → can run concurrently with "a".
}
results := DispatchConcurrent(context.Background(), calls, "", nil)
if len(results) != 2 {
t.Fatalf("expected 2 results, got %d", len(results))
}
// Both are idempotent, so they're parallel-safe (ExecParallelSafe), not path-scoped.
// ClassifyEntry maps idempotent → ExecParallelSafe regardless of PathScope.
// PathScope only matters when the tool is classified as ExecPathScoped,
// which currently requires explicit classification that doesn't exist yet.
// So they run in parallel.
if maxConcurrent.Load() < 1 {
t.Error("tools should have run")
}
}
// --- buildGatingGroups ---
func TestBuildGatingGroupsEmpty(t *testing.T) {
groups := buildGatingGroups(nil)
if len(groups) != 0 {
t.Errorf("expected 0 groups, got %d", len(groups))
}
}
func TestBuildGatingGroupsIsolatesNeverParallel(t *testing.T) {
e := ToolEntry{
Name: "mutator",
Handler: noopHandler,
Classification: ClassMutating,
}
calls := []ToolCall{
{Entry: e},
{Entry: e},
{Entry: e},
}
groups := buildGatingGroups(calls)
// Each should be in its own group.
if len(groups) != 3 {
t.Errorf("expected 3 isolated groups, got %d", len(groups))
}
for _, g := range groups {
if g.class != ExecNeverParallel {
t.Errorf("expected never-parallel group, got %v", g.class)
}
if len(g.calls) != 1 {
t.Errorf("expected 1 call per group, got %d", len(g.calls))
}
}
}
func TestBuildGatingGroupsBatchesParallelSafe(t *testing.T) {
e := ToolEntry{
Name: "reader",
Handler: noopHandler,
Classification: ClassIdempotent,
}
calls := []ToolCall{
{Entry: e}, {Entry: e}, {Entry: e},
}
groups := buildGatingGroups(calls)
// All parallel-safe → one group.
if len(groups) != 1 {
t.Errorf("expected 1 group, got %d", len(groups))
}
if groups[0].class != ExecParallelSafe {
t.Errorf("expected parallel-safe group, got %v", groups[0].class)
}
if len(groups[0].calls) != 3 {
t.Errorf("expected 3 calls in group, got %d", len(groups[0].calls))
}
}
func TestDispatchSequentialErrorCapture(t *testing.T) {
e := ToolEntry{
Name: "failing",
Handler: func(_ context.Context, _ map[string]any) (any, error) {
return nil, fmt.Errorf("something went wrong")
},
}
results := DispatchSequential(context.Background(), []ToolCall{{Entry: e}}, "", nil)
if len(results) != 1 {
t.Fatalf("expected 1 result, got %d", len(results))
}
if !results[0].IsError() {
t.Error("expected error result")
}
if results[0].Error.Error() != "something went wrong" {
t.Errorf("error = %v, want 'something went wrong'", results[0].Error)
}
}
func TestDispatchPerToolResultSizeLimit(t *testing.T) {
// 17.4 -- Per-tool max_result_size_chars enforcement.
dir := t.TempDir()
spillDir := dir
e := ToolEntry{
Name: "big-output",
Handler: echoHandler,
MaxResultSizeChars: 50,
}
results := DispatchSequential(context.Background(), []ToolCall{
{Entry: e, Input: map[string]any{"msg": strings.Repeat("x", 200)}},
}, spillDir, nil)
if len(results) != 1 {
t.Fatalf("expected 1 result, got %d", len(results))
}
if !results[0].IsError() && !strings.Contains(results[0].Preview, "spilled") &&
!strings.Contains(results[0].Preview, "truncated") {
t.Errorf("expected spill or truncation marker, got: %s", results[0].Preview)
}
}
func TestDispatchPerToolLimitNoSpillDir(t *testing.T) {
e := ToolEntry{
Name: "big-output",
Handler: echoHandler,
MaxResultSizeChars: 50,
}
results := DispatchSequential(context.Background(), []ToolCall{
{Entry: e, Input: map[string]any{"msg": strings.Repeat("x", 200)}},
}, "", nil)
if len(results) != 1 {
t.Fatalf("expected 1 result, got %d", len(results))
}
if !strings.Contains(results[0].Preview, "truncated") {
t.Errorf("expected truncation marker, got: %s", results[0].Preview)
}
}
// --- Regression tests for adversarial review findings ---
func TestBuildGatingGroupsSameScopePathScoped(t *testing.T) {
// Regression for: value-copy bug in buildGatingGroups silently dropped
// path-scoped calls with the same scope.
//
// Two calls with the same PathScope must end up in the same gatedGroup.
// Before fix: the second call was silently dropped because a value copy
// of the group was stored in the slice, while the map-stored pointer
// was appended to but invisible to the slice.
makePathScoped := func(name, _ string) ToolEntry {
return ToolEntry{
Name: name,
Handler: noopHandler,
Classification: ClassMutating, // ClassifyEntry → ExecNeverParallel, but we
}
}
// We need a classification that routes to ExecPathScoped. Since
// ClassifyEntry doesn't produce ExecPathScoped from any existing flag,
// test buildGatingGroups directly with a manually-constructed ToolCall.
calls := []ToolCall{
{Entry: makePathScoped("a", "/tmp"), PathScope: "/tmp"},
{Entry: makePathScoped("b", "/tmp"), PathScope: "/tmp"},
{Entry: makePathScoped("c", "/var"), PathScope: "/var"},
}
// Override ClassifyEntry for this test: force ExecPathScoped.
// We do this by testing buildGatingGroups with calls that have
// entries we know will route correctly. Since no existing flag
// routes to ExecPathScoped, we test the group-building logic
// indirectly through a helper that uses the same index-based
// pattern as the fix.
// Direct test: verify buildGatingGroups with ExecNeverParallel
// (mutating tools route here) — each call gets its own group.
groups := buildGatingGroups(calls)
neverParallelCount := 0
for _, g := range groups {
if g.class == ExecNeverParallel {
neverParallelCount += len(g.calls)
}
}
if neverParallelCount != 3 {
t.Errorf("expected 3 never-parallel calls, got %d", neverParallelCount)
}
}
func TestBuildGatingGroupsIndexTracking(t *testing.T) {
// Regression for: index-based tracking ensures same-scope calls
// are grouped together (not silently dropped via value-copy bug).
//
// We test the firstParallelSafeIdx helper directly.
groups := []gatedGroup{
{class: ExecNeverParallel, calls: []ToolCall{{}}},
{class: ExecParallelSafe, calls: []ToolCall{{}}},
{class: ExecNeverParallel, calls: []ToolCall{{}}},
}
idx, ok := firstParallelSafeIdx(groups)
if !ok {
t.Fatal("expected to find a parallel-safe group")
}
if idx != 1 {
t.Errorf("expected index 1, got %d", idx)
}
// No parallel-safe group.
groups2 := []gatedGroup{
{class: ExecNeverParallel, calls: []ToolCall{{}}},
}
_, ok = firstParallelSafeIdx(groups2)
if ok {
t.Error("expected false when no parallel-safe group exists")
}
}
func TestDispatchPerToolLimitSpillFailureFallback(t *testing.T) {
// Regression: when per-tool MaxResultSizeChars is set but the configured
// spill directory is unwritable, inline truncation
// must still be applied.
//
// Before fix: the "spill failed" path had no fallback; the per-tool
// limit was silently bypassed, leaving the full 500-char preview.
// Create a regular file and use a sub-path as the spill directory.
// Even root cannot write a file when a path component is a regular
// file, making this test reliable regardless of privileges.
f, err := os.CreateTemp(t.TempDir(), "archie-test-spill-blocker")
if err != nil {
t.Fatal(err)
}
f.Close()
defer os.Remove(f.Name())
spillDir := filepath.Join(f.Name(), "sub")
e := ToolEntry{
Name: "big-output",
Handler: echoHandler,
MaxResultSizeChars: 30,
}
results := DispatchSequential(context.Background(), []ToolCall{
{Entry: e, Input: map[string]any{"msg": strings.Repeat("x", 500)}},
}, spillDir, nil)
if len(results) != 1 {
t.Fatalf("expected 1 result, got %d", len(results))
}
// Should be truncated to MaxResultSizeChars even though spill failed.
if !strings.Contains(results[0].Preview, "truncated") {
t.Errorf("expected inline truncation fallback, got: %s", results[0].Preview)
}
// The payload is cut to the limit; the notice explaining the cut is the
// only thing allowed past it.
maxPreview := e.MaxResultSizeChars + maxTruncationNotice
if len(results[0].Preview) > maxPreview {
t.Errorf("preview too long (%d chars), expected at most %d", len(results[0].Preview), maxPreview)
}
}
func TestDispatchSequentialOutputVolumeNeverStopsCalls(t *testing.T) {
e := ToolEntry{
Name: "echo",
Handler: echoHandler,
}
spillDir := ""
calls := []ToolCall{
{Entry: e, Input: map[string]any{"msg": "short"}},
{Entry: e, Input: map[string]any{"msg": "also-short"}},
{Entry: e, Input: map[string]any{"msg": "never-runs"}},
}
results := DispatchSequential(context.Background(), calls, spillDir, nil)
if len(results) != len(calls) {
t.Errorf("output accumulation stopped dispatch: got %d results, want %d", len(results), len(calls))
}
for i, result := range results {
if result.Error != nil {
t.Errorf("result %d failed after accumulated output: %v", i, result.Error)
}
}
}
func TestDispatchPerToolLimitWithoutSpillTruncates(t *testing.T) {
// A per-tool limit without a spill directory must truncate explicitly.
e := ToolEntry{
Name: "verbose",
Handler: echoHandler,
MaxResultSizeChars: 40,
}
results := DispatchSequential(context.Background(), []ToolCall{
{Entry: e, Input: map[string]any{"msg": strings.Repeat("y", 300)}},
}, "", nil)
if len(results) != 1 {
t.Fatalf("expected 1 result, got %d", len(results))
}
if !strings.Contains(results[0].Preview, "truncated") {
t.Errorf("expected truncation without spill directory, got: %s", results[0].Preview)
}
}
func TestDispatchPerToolLimitWithinLimit(t *testing.T) {
// Sanity: output within per-tool limit passes through unchanged.
e := ToolEntry{
Name: "concise",
Handler: echoHandler,
MaxResultSizeChars: 500,
}
results := DispatchSequential(context.Background(), []ToolCall{
{Entry: e, Input: map[string]any{"msg": "short"}},
}, "", nil)
if len(results) != 1 {
t.Fatalf("expected 1 result, got %d", len(results))
}
if strings.Contains(results[0].Preview, "truncated") || strings.Contains(results[0].Preview, "spilled") {
t.Errorf("expected clean pass-through, got: %s", results[0].Preview)
}
}
-335
View File
@@ -3,12 +3,6 @@ package tools
import (
"errors"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"path"
"strconv"
"sync"
)
@@ -16,15 +10,6 @@ import (
// same name has already been registered.
var ErrDuplicateTool = errors.New("duplicate tool name")
// defaultRegistry is the package-level singleton.
var defaultRegistry = NewRegistry()
// DefaultRegistry returns the package-level singleton registry. Most
// callers should use this rather than creating their own.
func DefaultRegistry() *Registry {
return defaultRegistry
}
// Registry is a thread-safe tool registry. It maps tool names to
// [ToolEntry] values and supports lookup by toolset and availability.
type Registry struct {
@@ -149,323 +134,3 @@ func (r *Registry) Available() []ToolEntry {
}
return out
}
// Discover scans a directory of Go source files for Register calls
// that pass a [ToolEntry] composite literal. It uses [go/parser] and
// [go/ast] to statically analyse source files without executing them.
//
// Discover returns the number of Register calls found. Function fields
// (Handler, CheckFn, DynamicSchemaOverrides) cannot be resolved from
// static source analysis and remain nil. Entries that fail
// [ToolEntry.Validate] -- typically because Handler is nil -- are
// counted but not registered.
//
// Parse errors in individual files do not stop the scan; they are
// accumulated and returned as a joined error alongside the count of
// Register calls found in successfully-parsed files.
func (r *Registry) Discover(fsys fs.FS, dir string) (int, error) {
entries, err := fs.Glob(fsys, path.Join(dir, "*.go"))
if err != nil {
return 0, err
}
count := 0
var errs []error
for _, filePath := range entries {
src, err := fs.ReadFile(fsys, filePath)
if err != nil {
errs = append(errs, fmt.Errorf("read %s: %w", filePath, err))
continue
}
fset := token.NewFileSet()
f, err := parser.ParseFile(fset, filePath, src, parser.ParseComments)
if err != nil {
errs = append(errs, fmt.Errorf("parse %s: %w", filePath, err))
continue
}
count += countRegisterCalls(f)
for _, entry := range extractToolEntries(f) {
// Best-effort registration: only entries that pass
// Validate (have Name + Handler) are registered.
_ = r.Register(entry)
}
}
return count, errors.Join(errs...)
}
// countRegisterCalls counts the number of Register method calls in a Go AST.
func countRegisterCalls(f *ast.File) int {
count := 0
ast.Inspect(f, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok {
return true
}
if isRegisterCall(call) {
count++
}
return true
})
return count
}
// extractToolEntries walks the AST and extracts [ToolEntry] composite
// literals from Register calls.
func extractToolEntries(f *ast.File) []ToolEntry {
var entries []ToolEntry
ast.Inspect(f, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok {
return true
}
if !isRegisterCall(call) {
return true
}
if len(call.Args) == 0 {
return true
}
comp, ok := call.Args[0].(*ast.CompositeLit)
if !ok {
return true
}
entries = append(entries, toolEntryFromCompositeLit(comp))
return true
})
return entries
}
// isRegisterCall reports whether call is a .Register(...) method call on
// a *Registry receiver. It accepts common patterns:
//
// - DefaultRegistry().Register(...)
// - tools.DefaultRegistry().Register(...)
// - r.Register(...) where r is a known registry variable
func isRegisterCall(call *ast.CallExpr) bool {
sel, ok := call.Fun.(*ast.SelectorExpr)
if !ok {
return false
}
if sel.Sel.Name != "Register" {
return false
}
// The receiver must be a call to DefaultRegistry, with or without
// a package qualifier (e.g. DefaultRegistry() or tools.DefaultRegistry()).
rcv, ok := sel.X.(*ast.CallExpr)
if !ok {
return false
}
return callsDefaultRegistry(rcv)
}
// callsDefaultRegistry reports whether call is a DefaultRegistry()
// invocation, with or without a package qualifier.
func callsDefaultRegistry(call *ast.CallExpr) bool {
switch fn := call.Fun.(type) {
case *ast.Ident:
return fn.Name == "DefaultRegistry"
case *ast.SelectorExpr:
// pkg.DefaultRegistry()
return fn.Sel.Name == "DefaultRegistry"
default:
return false
}
}
// toolEntryFromCompositeLit extracts a [ToolEntry] from an AST composite
// literal. Only basic literal values (strings, bools, ints) are extracted;
// function references are ignored.
func toolEntryFromCompositeLit(lit *ast.CompositeLit) ToolEntry {
var e ToolEntry
for _, elt := range lit.Elts {
kv, ok := elt.(*ast.KeyValueExpr)
if !ok {
continue
}
key, ok := kv.Key.(*ast.Ident)
if !ok {
continue
}
switch key.Name {
case "Name":
e.Name = stringLit(kv.Value)
case "Toolset":
e.Toolset = stringLit(kv.Value)
case "Description":
e.Description = stringLit(kv.Value)
case "Emoji":
e.Emoji = stringLit(kv.Value)
case "IsAsync":
e.IsAsync = boolLit(kv.Value)
case "MaxResultSizeChars":
e.MaxResultSizeChars = intLit(kv.Value)
case "RequiresEnv":
e.RequiresEnv = stringSliceLit(kv.Value)
case "Schema":
e.Schema = schemaLit(kv.Value)
}
}
return e
}
// --- AST value extractors ---
func stringLit(expr ast.Expr) string {
lit, ok := expr.(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
return ""
}
// strconv.Unquote handles double-quoted, backtick-delimited (raw),
// and interpreted string literals with escape sequences.
s, err := strconv.Unquote(lit.Value)
if err != nil {
return ""
}
return s
}
func boolLit(expr ast.Expr) bool {
ident, ok := expr.(*ast.Ident)
return ok && ident.Name == "true"
}
func intLit(expr ast.Expr) int {
// Handle negative literals: the AST represents -5 as
// UnaryExpr{Op: token.SUB, X: BasicLit{Kind: INT, Value: "5"}}.
if un, ok := expr.(*ast.UnaryExpr); ok && un.Op == token.SUB {
lit, ok := un.X.(*ast.BasicLit)
if !ok || lit.Kind != token.INT {
return 0
}
v, err := strconv.ParseInt(lit.Value, 0, 0)
if err != nil {
return 0
}
return -int(v)
}
lit, ok := expr.(*ast.BasicLit)
if !ok || lit.Kind != token.INT {
return 0
}
// base=0 auto-detects decimal, hex (0x), octal (0o), binary (0b).
v, err := strconv.ParseInt(lit.Value, 0, 0)
if err != nil {
return 0
}
return int(v)
}
func stringSliceLit(expr ast.Expr) []string {
comp, ok := expr.(*ast.CompositeLit)
if !ok {
return nil
}
out := make([]string, 0, len(comp.Elts))
for _, elt := range comp.Elts {
if s := stringLit(elt); s != "" || isStringLit(elt) {
out = append(out, s)
}
}
return out
}
// isStringLit reports whether expr is a string literal (including empty).
func isStringLit(expr ast.Expr) bool {
lit, ok := expr.(*ast.BasicLit)
return ok && lit.Kind == token.STRING
}
func schemaLit(expr ast.Expr) JSONSchema {
comp, ok := expr.(*ast.CompositeLit)
if !ok {
return nil
}
s := make(JSONSchema)
for _, elt := range comp.Elts {
kv, ok := elt.(*ast.KeyValueExpr)
if !ok {
continue
}
key := schemaKey(kv.Key)
if key == "" {
continue
}
if v := schemaValue(kv.Value); v != nil {
s[key] = v
}
}
if len(s) == 0 {
return nil
}
return s
}
// schemaKey extracts a key string from a schema literal key expression.
// Handles string literals and identifier names (e.g. Type: "object").
func schemaKey(expr ast.Expr) string {
if s := stringLit(expr); s != "" {
return s
}
if ident, ok := expr.(*ast.Ident); ok {
return ident.Name
}
return ""
}
// schemaValue extracts a value from a schema literal, handling strings,
// ints, bools, nested maps, and arrays of strings.
func schemaValue(expr ast.Expr) any {
switch v := expr.(type) {
case *ast.BasicLit:
switch v.Kind {
case token.STRING:
return stringLit(v)
case token.INT:
return intLit(v)
default:
return nil
}
case *ast.Ident:
if v.Name == "true" {
return true
}
if v.Name == "false" {
return false
}
return nil
case *ast.CompositeLit:
// Check if it's a slice/array (no key-value pairs) or a map.
if isArrayLit(v) {
return schemaArrayLit(v)
}
return schemaLit(v)
default:
return nil
}
}
// isArrayLit reports whether a composite literal looks like a slice/array
// (elements without keys) rather than a map.
func isArrayLit(lit *ast.CompositeLit) bool {
if len(lit.Elts) == 0 {
return false
}
_, ok := lit.Elts[0].(*ast.KeyValueExpr)
return !ok
}
// schemaArrayLit extracts a []any from an array composite literal.
func schemaArrayLit(lit *ast.CompositeLit) []any {
var out []any
for _, elt := range lit.Elts {
if v := schemaValue(elt); v != nil {
out = append(out, v)
}
}
return out
}
-182
View File
@@ -4,7 +4,6 @@ import (
"errors"
"slices"
"testing"
"testing/fstest"
)
func TestRegistryRegister(t *testing.T) {
@@ -191,116 +190,6 @@ func TestRegistryAvailable(t *testing.T) {
})
}
func TestRegistryDiscover(t *testing.T) {
t.Run("no go files", func(t *testing.T) {
r := NewRegistry()
fsys := fstest.MapFS{}
n, err := r.Discover(fsys, ".")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if n != 0 {
t.Errorf("expected 0 discovered, got %d", n)
}
})
t.Run("go file with Register call", func(t *testing.T) {
r := NewRegistry()
fsys := fstest.MapFS{
"mytool.go": &fstest.MapFile{
Data: []byte(`package tools
import "github.com/samcharles93/archie-core/internal/tools"
func init() {
tools.DefaultRegistry().Register(tools.ToolEntry{
Name: "discovered_hello",
Description: "A discovered tool",
})
}
`),
},
}
// Discover finds and counts Register calls. The entry is not
// actually registered because Handler (a function field) cannot
// be resolved from source via static AST analysis.
n, err := r.Discover(fsys, ".")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if n != 1 {
t.Errorf("expected 1 discovered, got %d", n)
}
})
t.Run("go file without Register call", func(t *testing.T) {
r := NewRegistry()
fsys := fstest.MapFS{
"plain.go": &fstest.MapFile{
Data: []byte(`package tools
func PlainFunction() string {
return "hello"
}
`),
},
}
n, err := r.Discover(fsys, ".")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if n != 0 {
t.Errorf("expected 0 discovered, got %d", n)
}
})
t.Run("syntax error in go file", func(t *testing.T) {
r := NewRegistry()
fsys := fstest.MapFS{
"broken.go": &fstest.MapFile{
Data: []byte(`package tools
func broken( {`),
},
}
_, err := r.Discover(fsys, ".")
if err == nil {
t.Error("expected error for broken Go file")
}
})
t.Run("multiple Register calls in one file", func(t *testing.T) {
r := NewRegistry()
fsys := fstest.MapFS{
"tools.go": &fstest.MapFile{
Data: []byte(`package tools
func init() {
DefaultRegistry().Register(ToolEntry{Name: "tool-a", Description: "First tool"})
DefaultRegistry().Register(ToolEntry{Name: "tool-b", Description: "Second tool"})
}
`),
},
}
n, err := r.Discover(fsys, ".")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if n != 2 {
t.Errorf("expected 2 discovered, got %d", n)
}
})
}
func TestRegistrySingleton(t *testing.T) {
// DefaultRegistry returns the same instance.
d1 := DefaultRegistry()
d2 := DefaultRegistry()
if d1 != d2 {
t.Error("DefaultRegistry should be a singleton")
}
}
// toolNames extracts names from a slice of ToolEntry.
func toolNames(entries []ToolEntry) []string {
names := make([]string, len(entries))
@@ -375,79 +264,8 @@ func TestRegistryRegisterDefensiveCopy(t *testing.T) {
}
}
func TestRegistryDiscoverContinuesOnError(t *testing.T) {
// Regression: Discover aborted on first parse error, losing prior
// registrations. After fix, it continues to remaining files.
r := NewRegistry()
fsys := fstest.MapFS{
"good.go": &fstest.MapFile{
Data: []byte(`package tools
func init() {
DefaultRegistry().Register(ToolEntry{Name: "good-tool", Description: "Valid"})
}
`),
},
"broken.go": &fstest.MapFile{
Data: []byte(`package tools
func broken( {`),
},
"another.go": &fstest.MapFile{
Data: []byte(`package tools
func init() {
DefaultRegistry().Register(ToolEntry{Name: "another-tool", Description: "Also valid"})
}
`),
},
}
n, err := r.Discover(fsys, ".")
// Should report the parse error.
if err == nil {
t.Error("expected error for broken.go")
}
// Should still count Register calls from good files.
if n != 2 {
t.Errorf("expected 2 discovered (good.go + another.go), got %d", n)
}
}
func TestRegistryDiscoverNonRegistryRegisterIgnored(t *testing.T) {
// Regression: isRegisterCall matched ANY .Register() method.
// After fix, only DefaultRegistry().Register() or bare identifiers
// are matched.
r := NewRegistry()
fsys := fstest.MapFS{
"not_a_tool.go": &fstest.MapFile{
Data: []byte(`package tools
type Other struct{}
func (o *Other) Register(name string) {}
func init() {
var o Other
o.Register("not-a-tool")
DefaultRegistry().Register(ToolEntry{Name: "real-tool", Description: "A real tool"})
}
`),
},
}
n, err := r.Discover(fsys, ".")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// Only the DefaultRegistry().Register() call should be counted.
if n != 1 {
t.Errorf("expected 1 (only DefaultRegistry call), got %d", n)
}
}
// Ensure registry implements basic sanity at the package level.
func TestRegistryPackageLevelHelpers(t *testing.T) {
// Reset state by creating a fresh registry.
// The package-level helpers work against DefaultRegistry.
t.Run("Register and All via package helpers", func(t *testing.T) {
r := NewRegistry()
e := ToolEntry{Name: "pkg_helper", Handler: noopHandler}