Documentation
¶
Overview ¶
Package toolbuild is the single construction entry point for every LLM-facing tool defined by this repository.
Before this package existed, agent and server each had their own read/write constructor pair (agent.readTool/writeTool and server.roTool/wrTool) and built their parameter schemas with package-local helpers. Adding a recon tool meant copying whichever pair lived nearby, so the two copies slowly drifted. Build is now the one place that turns a Spec into an actool.CoreTool:
- it validates required fields at construction time (name, description, schema, handler, access and permission), so a tool that forgets to declare read-only or its permission policy fails immediately instead of running with fail-closed defaults nobody noticed;
- it keeps the exact semantics of the old constructors: read-only tools are marked concurrency-safe with the allow policy, mutating tools are neither read-only nor concurrency-safe, and the allow policy is permission.Allowed();
- it accepts an optional per-call Timeout that wraps the handler in a context deadline. Current tools pass 0 (no deadline), which preserves the old behavior exactly; the harness still owns the run-level wall-clock budget, so no per-tool budget is invented here.
Build never changes a tool's name, description, schema or return value: it is a constructor, not a schema transformer.
Index ¶
- func Array(items map[string]any, desc string) map[string]any
- func Boolean(desc string) map[string]any
- func Build(s Spec) actool.CoreTool
- func EnumString(desc string, values ...string) map[string]any
- func Integer(desc string) map[string]any
- func Object(props map[string]any, required ...string) map[string]any
- func Read(name, desc string, schema map[string]any, ...) actool.CoreTool
- func String(desc string) map[string]any
- func Write(name, desc string, schema map[string]any, ...) actool.CoreTool
- type Access
- type Permission
- type RunFunc
- type Spec
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
Build validates s and returns the tool. It panics on an invalid spec: tools are registered at process startup, so a panic is the loudest possible failure and happens before any model can see a half-defined tool.
func EnumString ¶
EnumString builds {"type":"string","enum":<values>} plus a description when non-empty. An empty value list panics: an enum with no choices is a bug.
func Read ¶
func Read(name, desc string, schema map[string]any, run func(context.Context, json.RawMessage) (actool.Result, error)) actool.CoreTool
Read is the convenience form for the common read-only, concurrency-safe, allow-without-asking tool. It exists so the vast majority of call sites stay one line; it is a thin declaration over Build, not a second implementation.
func Write ¶
func Write(name, desc string, schema map[string]any, run func(context.Context, json.RawMessage) (actool.Result, error)) actool.CoreTool
Write is the convenience form for the common mutating, allow-without-asking tool (not read-only, not concurrency-safe) — the old writeTool/wrTool behavior.
Types ¶
type Access ¶
type Access int
Access declares whether a tool may mutate state. It is required: Build panics on the zero value so a new tool cannot "forget" to say.
type Permission ¶
type Permission int
Permission is the registration-time permission policy. It is required: Build panics on the zero value. Almost every built-in tool allows without asking; MCP tools ask the user, exactly as before.
const ( PermissionUnset Permission = iota PermissionAllow PermissionAsk )
type RunFunc ¶
type RunFunc func(ctx context.Context, input json.RawMessage, tc *actool.ToolContext) (actool.Result, error)
RunFunc is the handler shape accepted by Build. It receives the harness tool context (some host tools, e.g. MCP/custom commands, need it for output capture and proxy env).
type Spec ¶
type Spec struct {
Name string
Description string
Schema map[string]any
Run RunFunc
Access Access
Permission Permission
// Concurrent marks the tool safe to run alongside other tools. The old
// read-only constructors set it; write tools and host tools did not.
Concurrent bool
// Prompt is an optional extra prompt fragment (actool.Spec.Prompt).
Prompt string
// RawInput marks a tool that parses its own arguments (actool.Spec.RawInput).
RawInput bool
// AskPrompt overrides the confirmation text for PermissionAsk. Empty means
// actool's default "approve <name>?".
AskPrompt string
// Timeout, when >0, wraps Run in a context deadline. 0 = inherit the
// caller's context (the behavior of every tool before this package existed).
Timeout time.Duration
}
Spec describes one tool.
Source Files