From 5f3cceb94017ac8a79f90bdf00b46ffae74c4b7f Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 25 Oct 2026 16:45:27 +1100 Subject: [PATCH] feat(modelloop): run a step's tool calls in parallel as each tool's classification allows --- go.mod | 2 +- go.sum | 4 +-- internal/agentexec/modelloop/loop_runner.go | 18 +++++----- internal/agentexec/modelloop/toolset.go | 37 ++++++++++++++++++++- internal/app/archiegateway/chat_runtime.go | 7 ++-- internal/app/archiegateway/curators.go | 2 ++ internal/gateway/interactive_tools.go | 8 +++-- internal/tools/classification.go | 7 ++-- internal/tools/disclosure.go | 2 +- internal/tools/mcp/client.go | 3 ++ internal/tools/provider/mcp/provider.go | 15 ++++++--- 11 files changed, 79 insertions(+), 26 deletions(-) diff --git a/go.mod b/go.mod index ff0dc9398..807c30165 100644 --- a/go.mod +++ b/go.mod @@ -96,7 +96,7 @@ require ( github.com/opencontainers/go-digest v1.0.0 github.com/opencontainers/image-spec v1.1.1 github.com/pressly/goose/v3 v3.29.0 - github.com/samcharles93/ai-sdk v0.3.2 + github.com/samcharles93/ai-sdk v0.4.0 go.lsp.dev/jsonrpc2 v1.0.1 go.lsp.dev/protocol v1.0.1 go.lsp.dev/uri v1.0.1 diff --git a/go.sum b/go.sum index 59a3b7888..1550dd7c1 100644 --- a/go.sum +++ b/go.sum @@ -174,8 +174,8 @@ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo= github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= -github.com/samcharles93/ai-sdk v0.3.2 h1:sWQ+Mbb1fXTRkY13Z+kTidjo20VpfeqrPlQUS3xGXnU= -github.com/samcharles93/ai-sdk v0.3.2/go.mod h1:u4zrQ9/Q58L5mNEut4bNQ1ks+RCKq71LN5EDz2N/0Zk= +github.com/samcharles93/ai-sdk v0.4.0 h1:MU/0MGU7Oq1wPiIDqncv4jDYTTKVsTqoyk0SzRcGw6M= +github.com/samcharles93/ai-sdk v0.4.0/go.mod h1:u4zrQ9/Q58L5mNEut4bNQ1ks+RCKq71LN5EDz2N/0Zk= github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0= github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs= github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0= diff --git a/internal/agentexec/modelloop/loop_runner.go b/internal/agentexec/modelloop/loop_runner.go index f7fb671b2..d0a67b6ce 100644 --- a/internal/agentexec/modelloop/loop_runner.go +++ b/internal/agentexec/modelloop/loop_runner.go @@ -74,14 +74,16 @@ func (r *LoopRunner) Run(ctx context.Context, workspace string, req agentrun.Req } captureTools := captureToolSet(req.CaptureTools, captures) res, err := r.run(ctx, agentloop.Config{ - Runtime: r.runtime, - ModelRef: req.Model, - WorkDir: workspace, - Mission: req.Mission, - ExtraRules: agentexec.ProjectScopedRules(workspace, req.ExtraRules), - Notes: notes, - Gate: toAgentGate(req.Gate), - Preflight: toAgentCommands(req.Preflight), + Runtime: r.runtime, + ModelRef: req.Model, + WorkDir: workspace, + + MaxParallelToolCalls: MaxParallelToolCalls, + Mission: req.Mission, + ExtraRules: agentexec.ProjectScopedRules(workspace, req.ExtraRules), + Notes: notes, + Gate: toAgentGate(req.Gate), + Preflight: toAgentCommands(req.Preflight), Budget: agentloop.Budget{ MaxSteps: req.Budget.MaxSteps, WallClock: req.Budget.WallClock, diff --git a/internal/agentexec/modelloop/toolset.go b/internal/agentexec/modelloop/toolset.go index 38dd3d494..e4b057257 100644 --- a/internal/agentexec/modelloop/toolset.go +++ b/internal/agentexec/modelloop/toolset.go @@ -6,6 +6,7 @@ import ( "errors" "fmt" "os" + "path/filepath" "slices" aicore "github.com/samcharles93/ai-sdk/core" @@ -148,11 +149,45 @@ func BuildToolSetFrom(entries []tools.ToolEntry, opts ToolSetOptions) (aicore.To if err != nil { return nil, fmt.Errorf("tool %s schema: %w", entry.Name, err) } - set[entry.Name] = aicore.NewTool(entry.Name, entry.Description, params, toolExecute(entry, opts)) + tool := aicore.NewTool(entry.Name, entry.Description, params, toolExecute(entry, opts)) + tool.Concurrency = concurrency(entry.Classification) + set[entry.Name] = tool } return set, nil } +// MaxParallelToolCalls bounds how many of one model step's tool calls run at +// once. Each tool's classification decides which calls may overlap. +const MaxParallelToolCalls = 8 + +// concurrency maps a classification to how a call may overlap others. +// Unclassified and approval-gated tools run alone: approvals are asked one +// at a time, and an unknown tool is never assumed safe. +func concurrency(class tools.ToolClassification) func(string) aicore.Concurrency { + switch { + case class.IsApprovalRequired(): + return nil + case class.IsIdempotent(): + return func(input string) aicore.Concurrency { return pathKeyed(input, true) } + case class.IsMutating(): + return func(input string) aicore.Concurrency { return pathKeyed(input, false) } + } + return nil +} + +// pathKeyed orders calls per path argument, so a read and a write of one +// file keep the model's order. A call without a path runs in parallel when +// pathless is set and alone otherwise. +func pathKeyed(input string, pathless bool) aicore.Concurrency { + var args struct { + Path string `json:"path"` + } + if json.Unmarshal([]byte(input), &args) != nil || args.Path == "" { + return aicore.Concurrency{Parallel: pathless} + } + return aicore.Concurrency{Parallel: true, Key: filepath.Clean(args.Path)} +} + func safeToolAvailable(entry tools.ToolEntry) (available bool, err error) { defer func() { if recovered := recover(); recovered != nil { diff --git a/internal/app/archiegateway/chat_runtime.go b/internal/app/archiegateway/chat_runtime.go index f81d57970..8b7dc77a9 100644 --- a/internal/app/archiegateway/chat_runtime.go +++ b/internal/app/archiegateway/chat_runtime.go @@ -141,9 +141,10 @@ func chatGenerateOptions( maxSteps = defaultChatMaxSteps } return core.GenerateOptions{ - Messages: messages, - Tools: toolSet, - MaxSteps: maxSteps, + Messages: messages, + Tools: toolSet, + MaxParallelToolCalls: modelloop.MaxParallelToolCalls, + MaxSteps: maxSteps, }, nil } diff --git a/internal/app/archiegateway/curators.go b/internal/app/archiegateway/curators.go index 76a09885a..ba07317d7 100644 --- a/internal/app/archiegateway/curators.go +++ b/internal/app/archiegateway/curators.go @@ -142,6 +142,8 @@ func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (cu Messages: msgs, Tools: toolSet, MaxSteps: max(req.MaxSteps, 1), + + MaxParallelToolCalls: modelloop.MaxParallelToolCalls, }) r.outcomes.record(req.Model, err) r.usage.record(ctx, usage.SourceCurator, req.Model, res.TotalUsage) diff --git a/internal/gateway/interactive_tools.go b/internal/gateway/interactive_tools.go index 8e174cbd2..6658290f0 100644 --- a/internal/gateway/interactive_tools.go +++ b/internal/gateway/interactive_tools.go @@ -41,7 +41,9 @@ func askQuestionsTool() tools.ToolEntry { Description: "Ask the human several related questions at once, each with choices to pick from or a free-text answer. " + "Prefer it to repeated ask_user calls when you need more than one answer. " + "Blocks until they answer or skip, so ask at most once and only when you cannot proceed without it.", - Classification: tools.ClassIdempotent, + // Mutating: a channel holds one pending reply per chat, so a second + // concurrent question would replace the first. + Classification: tools.ClassMutating, Schema: tools.JSONSchema{ "type": "object", "properties": map[string]any{ @@ -160,7 +162,9 @@ func askUserTool() tools.ToolEntry { Description: "Ask the human a question when their answer changes what you do. " + "Pass options to ask them to choose exactly one; without options it is a free-text question. " + "Blocks until they answer, so ask at most once and only when you cannot proceed without it.", - Classification: tools.ClassIdempotent, + // Mutating: a channel holds one pending reply per chat, so a second + // concurrent question would replace the first. + Classification: tools.ClassMutating, Schema: tools.JSONSchema{ "type": "object", "properties": map[string]any{ diff --git a/internal/tools/classification.go b/internal/tools/classification.go index d70c8cd9e..abf733e43 100644 --- a/internal/tools/classification.go +++ b/internal/tools/classification.go @@ -9,12 +9,13 @@ type ToolClassification int const ( // ClassIdempotent marks a read-only tool. Idempotent tools can be - // safely retried and run in parallel with other idempotent tools. + // safely retried and run in parallel with other calls. ClassIdempotent ToolClassification = 1 << iota // ClassMutating marks a tool that modifies external state (writes files, - // creates resources, sends messages, etc.). Mutating tools require - // serialization, checkpointing, and stricter guardrail monitoring. + // creates resources, sends messages, etc.). A mutating call with a path + // argument runs in order with other calls on that path; any other + // mutating call runs alone. ClassMutating // RequiresApproval marks a tool that needs human approval before each call. diff --git a/internal/tools/disclosure.go b/internal/tools/disclosure.go index 5ba3ed218..ddd96fd81 100644 --- a/internal/tools/disclosure.go +++ b/internal/tools/disclosure.go @@ -203,7 +203,7 @@ func BridgeTools(reg *Registry) []ToolEntry { Toolset: "bridge", Description: "Invoke a tool by name. Use after tool_describe to confirm the schema.", Emoji: "⚡", - Classification: ClassIdempotent, + Classification: ClassMutating, // it can invoke any tool Handler: bridgeCallHandler(reg), Schema: JSONSchema{ "type": "object", diff --git a/internal/tools/mcp/client.go b/internal/tools/mcp/client.go index f486d1d5d..2b8cfb3c7 100644 --- a/internal/tools/mcp/client.go +++ b/internal/tools/mcp/client.go @@ -115,6 +115,9 @@ type ToolSchema struct { Name string `json:"name"` Description string `json:"description,omitempty"` InputSchema tools.JSONSchema `json:"inputSchema"` + Annotations struct { + ReadOnlyHint bool `json:"readOnlyHint"` + } `json:"annotations"` } // ContentBlock is one block of a tools/call result. Per the MCP spec a diff --git a/internal/tools/provider/mcp/provider.go b/internal/tools/provider/mcp/provider.go index 3257f3959..d1882e08e 100644 --- a/internal/tools/provider/mcp/provider.go +++ b/internal/tools/provider/mcp/provider.go @@ -171,12 +171,17 @@ func (p *Provider) Discover(ctx context.Context) ([]tools.ToolEntry, error) { ) } names[publicName] = schema.Name + var class tools.ToolClassification + if schema.Annotations.ReadOnlyHint { + class = tools.ClassIdempotent + } entries = append(entries, tools.ToolEntry{ - Name: publicName, - Toolset: "mcp", - Schema: schema.InputSchema, - Description: schema.Description, - Handler: p.handlerFor(client, schema.Name), + Classification: class, + Name: publicName, + Toolset: "mcp", + Schema: schema.InputSchema, + Description: schema.Description, + Handler: p.handlerFor(client, schema.Name), CheckFn: func() bool { return p.transport.State() == protocol.StateRunning },