feat(agent): add per-tool execution config (#31)

Author: lucasnevespereira

README.md

@@ -110,6 +110,10 @@ context:
 tools:
   - file_list
   - file_read
+tool_config:
+  file_read:
+    timeout: 5s
+    result_cap: 8000
 ```
 
 If `provider` is omitted, Vikusha infers Anthropic for models beginning with `claude`; otherwise it uses OpenAI-compatible chat completions. The default env vars are `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `GROQ_API_KEY`, depending on the provider.

core/agent/agent.go

@@ -23,6 +23,7 @@ type Agent struct {
 	systemPrompt  string
 	provider      llm.Provider
 	tools         *tool.Registry
+	toolConfig    map[string]ToolConfig
 	memory        memory.Memory
 	toolResultCap int
 	historyBudget int
@@ -49,12 +50,18 @@ type Options struct {
 	SystemPrompt       string
 	Provider           llm.Provider
 	Tools              *tool.Registry
+	ToolConfig         map[string]ToolConfig
 	Memory             memory.Memory
 	ToolResultCap      int
 	HistoryTokenBudget int
 	Logger             TurnLogger
 }
 
+type ToolConfig struct {
+	Timeout   time.Duration
+	ResultCap int
+}
+
 type TurnLogger interface {
 	LogTurn(ctx context.Context, event TurnEvent)
 }
@@ -101,6 +108,7 @@ func New(opts Options) (*Agent, error) {
 		systemPrompt:  opts.SystemPrompt,
 		provider:      opts.Provider,
 		tools:         opts.Tools,
+		toolConfig:    cloneToolConfig(opts.ToolConfig),
 		memory:        opts.Memory,
 		toolResultCap: opts.ToolResultCap,
 		historyBudget: opts.HistoryTokenBudget,
@@ -111,6 +119,17 @@ func New(opts Options) (*Agent, error) {
 	}, nil
 }
 
+func cloneToolConfig(in map[string]ToolConfig) map[string]ToolConfig {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make(map[string]ToolConfig, len(in))
+	for name, cfg := range in {
+		out[name] = cfg
+	}
+	return out
+}
+
 func (a *Agent) Name() string { return a.name }
 
 func (a *Agent) Cancel(userID string) bool {

core/agent/agent_test.go

@@ -125,6 +125,96 @@ func TestCapToolResultTruncatesLongOutput(t *testing.T) {
 	}
 }
 
+type outputTool struct {
+	name   string
+	output string
+}
+
+func (t outputTool) Name() string { return t.name }
+
+func (t outputTool) Description() string { return "output" }
+
+func (t outputTool) Schema() json.RawMessage { return json.RawMessage(`{"type":"object"}`) }
+
+func (t outputTool) Run(ctx context.Context, input json.RawMessage) (string, error) {
+	return t.output, nil
+}
+
+func TestRunToolUsesPerToolResultCap(t *testing.T) {
+	reg := tool.NewRegistry()
+	reg.Register(outputTool{name: "long", output: "hello world"})
+	a, err := New(Options{
+		Name:          "test",
+		Model:         "test-model",
+		Provider:      staticProvider{},
+		Tools:         reg,
+		ToolResultCap: 100,
+		ToolConfig: map[string]ToolConfig{
+			"long": {ResultCap: 5},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	result, truncated := a.runTool(context.Background(), llm.Block{
+		Type:      llm.BlockToolUse,
+		ToolUseID: "tool-1",
+		ToolName:  "long",
+	})
+	if !truncated {
+		t.Fatal("runTool did not report truncation")
+	}
+	if !strings.HasPrefix(result.Text, "hello\n\n") {
+		t.Fatalf("tool result = %q, want hello prefix", result.Text)
+	}
+}
+
+type blockingTool struct{}
+
+func (blockingTool) Name() string { return "slow" }
+
+func (blockingTool) Description() string { return "slow" }
+
+func (blockingTool) Schema() json.RawMessage { return json.RawMessage(`{"type":"object"}`) }
+
+func (blockingTool) Run(ctx context.Context, input json.RawMessage) (string, error) {
+	<-ctx.Done()
+	return "", ctx.Err()
+}
+
+func TestRunToolUsesPerToolTimeout(t *testing.T) {
+	reg := tool.NewRegistry()
+	reg.Register(blockingTool{})
+	a, err := New(Options{
+		Name:     "test",
+		Model:    "test-model",
+		Provider: staticProvider{},
+		Tools:    reg,
+		ToolConfig: map[string]ToolConfig{
+			"slow": {Timeout: time.Millisecond},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	result, truncated := a.runTool(context.Background(), llm.Block{
+		Type:      llm.BlockToolUse,
+		ToolUseID: "tool-1",
+		ToolName:  "slow",
+	})
+	if truncated {
+		t.Fatal("timeout result should not be marked truncated")
+	}
+	if !result.ToolError {
+		t.Fatal("timeout result should be marked as tool error")
+	}
+	if !strings.Contains(result.Text, context.DeadlineExceeded.Error()) {
+		t.Fatalf("timeout result = %q, want deadline exceeded", result.Text)
+	}
+}
+
 type recordingLogger struct {
 	events []TurnEvent
 }

core/agent/loop.go

@@ -193,19 +193,43 @@ func (a *Agent) runTool(ctx context.Context, call llm.Block) (out llm.Block, tru
 	if !ok {
 		return errResult(call.ToolUseID, fmt.Sprintf("tool not found: %s", call.ToolName)), false
 	}
+	cfg := a.configForTool(call.ToolName)
+	if cfg.Timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, cfg.Timeout)
+		defer cancel()
+	}
 	output, err := t.Run(ctx, call.ToolInput)
 	if err != nil {
 		return errResult(call.ToolUseID, err.Error()), false
 	}
-	text, truncated := a.capToolResult(output)
+	text, truncated := capToolResult(output, a.resultCapForTool(cfg))
 	return llm.Block{Type: llm.BlockToolResult, ToolUseID: call.ToolUseID, Text: text}, truncated
 }
 
 func (a *Agent) capToolResult(output string) (string, bool) {
-	if a.toolResultCap <= 0 || len(output) <= a.toolResultCap {
+	return capToolResult(output, a.toolResultCap)
+}
+
+func (a *Agent) configForTool(name string) ToolConfig {
+	if a.toolConfig == nil {
+		return ToolConfig{}
+	}
+	return a.toolConfig[name]
+}
+
+func (a *Agent) resultCapForTool(cfg ToolConfig) int {
+	if cfg.ResultCap > 0 {
+		return cfg.ResultCap
+	}
+	return a.toolResultCap
+}
+
+func capToolResult(output string, cap int) (string, bool) {
+	if cap <= 0 || len(output) <= cap {
 		return output, false
 	}
-	return output[:a.toolResultCap] + fmt.Sprintf("\n\n[tool result truncated: %d bytes omitted]", len(output)-a.toolResultCap), true
+	return output[:cap] + fmt.Sprintf("\n\n[tool result truncated: %d bytes omitted]", len(output)-cap), true
 }
 
 func splitBlocks(blocks []llm.Block) (string, []llm.Block) {

core/character/character.go

@@ -5,18 +5,20 @@ import (
 	"fmt"
 	"os"
 	"strings"
+	"time"
 
 	"gopkg.in/yaml.v3"
 )
 
 type Character struct {
-	Name         string         `yaml:"name"`
-	Model        string         `yaml:"model"`
-	SystemPrompt string         `yaml:"system_prompt"`
-	Provider     ProviderConfig `yaml:"provider"`
-	Memory       MemoryConfig   `yaml:"memory"`
-	Context      ContextConfig  `yaml:"context"`
-	Tools        []string       `yaml:"tools"`
+	Name         string                `yaml:"name"`
+	Model        string                `yaml:"model"`
+	SystemPrompt string                `yaml:"system_prompt"`
+	Provider     ProviderConfig        `yaml:"provider"`
+	Memory       MemoryConfig          `yaml:"memory"`
+	Context      ContextConfig         `yaml:"context"`
+	Tools        []string              `yaml:"tools"`
+	ToolConfig   map[string]ToolConfig `yaml:"tool_config"`
 }
 
 type ProviderConfig struct {
@@ -34,6 +36,11 @@ type ContextConfig struct {
 	HistoryTokenBudget int `yaml:"history_token_budget"`
 }
 
+type ToolConfig struct {
+	Timeout   string `yaml:"timeout"`
+	ResultCap int    `yaml:"result_cap"`
+}
+
 func Load(path string) (*Character, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -72,6 +79,20 @@ func (c Character) Validate() []string {
 	if c.Context.HistoryTokenBudget < 0 {
 		errs = append(errs, "context.history_token_budget cannot be negative")
 	}
+	for name, cfg := range c.ToolConfig {
+		toolName := strings.TrimSpace(name)
+		if toolName == "" {
+			errs = append(errs, "tool_config cannot contain empty tool names")
+		}
+		if strings.TrimSpace(cfg.Timeout) != "" {
+			if _, err := time.ParseDuration(cfg.Timeout); err != nil {
+				errs = append(errs, fmt.Sprintf("tool_config.%s.timeout is invalid: %v", toolName, err))
+			}
+		}
+		if cfg.ResultCap < 0 {
+			errs = append(errs, fmt.Sprintf("tool_config.%s.result_cap cannot be negative", toolName))
+		}
+	}
 	for _, t := range c.Tools {
 		if strings.TrimSpace(t) == "" {
 			errs = append(errs, "tools cannot contain empty names")

core/character/character_test.go

@@ -138,6 +138,56 @@ context:
 	}
 }
 
+func TestLoadToolConfig(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "character.yaml")
+	if err := os.WriteFile(path, []byte(`
+name: Helper
+model: gpt-4o-mini
+system_prompt: Be useful.
+tools:
+  - file_read
+tool_config:
+  file_read:
+    timeout: 5s
+    result_cap: 8000
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	c, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg := c.ToolConfig["file_read"]
+	if cfg.Timeout != "5s" {
+		t.Fatalf("timeout = %q, want 5s", cfg.Timeout)
+	}
+	if cfg.ResultCap != 8000 {
+		t.Fatalf("result_cap = %d, want 8000", cfg.ResultCap)
+	}
+}
+
+func TestToolConfigValidation(t *testing.T) {
+	c := Character{
+		Name:         "Tools",
+		Model:        "gpt-4o-mini",
+		SystemPrompt: "Be useful.",
+		ToolConfig: map[string]ToolConfig{
+			"file_read": {Timeout: "soon", ResultCap: -1},
+		},
+	}
+	errs := c.Validate()
+	if len(errs) != 2 {
+		t.Fatalf("Validate() = %#v, want two errors", errs)
+	}
+	got := strings.Join(errs, "\n")
+	for _, want := range []string{"tool_config.file_read.timeout", "tool_config.file_read.result_cap"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("Validate() = %#v, want %q", errs, want)
+		}
+	}
+}
+
 func TestContextValidation(t *testing.T) {
 	c := Character{
 		Name:         "Context",

docs/CHARACTER.md

@@ -50,6 +50,11 @@ context:
 tools:
   - file_list
   - file_read
+
+tool_config:
+  file_read:
+    timeout: 5s
+    result_cap: 8000
 ```
 
 ## Fields
@@ -68,6 +73,8 @@ tools:
 
 `tools` is optional. The implemented built-in tools today are `file_list` and `file_read`.
 
+`tool_config` is optional. It configures enabled tools by name. `timeout` uses Go duration strings such as `5s`, `500ms`, or `1m`. `result_cap` limits how many bytes from that tool result are returned to the model before truncation.
+
 ## Validation
 
 `vikusha chat character.yaml` validates on startup:

docs/ROADMAP.md

@@ -73,7 +73,7 @@ A single agent you can talk to from the terminal, backed by a core harness that
 - [x] Tool interface with a stable JSON schema so definitions cache cleanly.
 - [x] Built-in: `file_read`, `file_list`.
 - [ ] Built-in: `bash`, `file_edit`, `web_search`, `web_fetch`.
-- [ ] Per-tool timeout and result-cap overrides via character YAML.
+- [x] Per-tool timeout and result-cap overrides via character YAML.
 - [ ] Danger detection on bash and file writes, with an approval flow.
 
 ### Character