diff --git a/docs/prds/deep-research-capability.md b/docs/prds/deep-research-capability.md index f8dec844d..dc6010e96 100644 --- a/docs/prds/deep-research-capability.md +++ b/docs/prds/deep-research-capability.md @@ -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 | diff --git a/internal/app/agentworker/task_execution.go b/internal/app/agentworker/task_execution.go index 373f21d65..6f98fa98d 100644 --- a/internal/app/agentworker/task_execution.go +++ b/internal/app/agentworker/task_execution.go @@ -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 diff --git a/internal/app/agentworker/task_execution_test.go b/internal/app/agentworker/task_execution_test.go index b2c792c6b..7a5f6e42a 100644 --- a/internal/app/agentworker/task_execution_test.go +++ b/internal/app/agentworker/task_execution_test.go @@ -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) { diff --git a/internal/app/archied/reload.go b/internal/app/archied/reload.go index 4ca56d598..377508dcd 100644 --- a/internal/app/archied/reload.go +++ b/internal/app/archied/reload.go @@ -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 diff --git a/internal/config/config.go b/internal/config/config.go index 92dc1504b..983455322 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -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}, } } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 9d59fc9f8..65fee5bcf 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -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 diff --git a/internal/tools/builtin/registry.go b/internal/tools/builtin/registry.go index d1b0cbf64..4932a84bf 100644 --- a/internal/tools/builtin/registry.go +++ b/internal/tools/builtin/registry.go @@ -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 -} diff --git a/internal/tools/builtin/registry_test.go b/internal/tools/builtin/registry_test.go index 1322a94ac..43e0f18a0 100644 --- a/internal/tools/builtin/registry_test.go +++ b/internal/tools/builtin/registry_test.go @@ -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) - } -} diff --git a/internal/tools/classification_test.go b/internal/tools/classification_test.go index 2c267288d..baab1a6b4 100644 --- a/internal/tools/classification_test.go +++ b/internal/tools/classification_test.go @@ -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", diff --git a/internal/tools/dispatch.go b/internal/tools/dispatch.go deleted file mode 100644 index 8f434195d..000000000 --- a/internal/tools/dispatch.go +++ /dev/null @@ -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 -} diff --git a/internal/tools/dispatch_test.go b/internal/tools/dispatch_test.go deleted file mode 100644 index 598668655..000000000 --- a/internal/tools/dispatch_test.go +++ /dev/null @@ -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) - } -} diff --git a/internal/tools/registry.go b/internal/tools/registry.go index 93a66cd4d..707e12ab0 100644 --- a/internal/tools/registry.go +++ b/internal/tools/registry.go @@ -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 -} diff --git a/internal/tools/registry_test.go b/internal/tools/registry_test.go index 6a5fab6db..6030005ba 100644 --- a/internal/tools/registry_test.go +++ b/internal/tools/registry_test.go @@ -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}