rony-llm-agent/pkg/tools/README.md

# pkg/tools

> Tools system (function calling) with JSON Schema, sandbox, and permissions.

## Responsibility

Allow the LLM to invoke functions defined in Go, with schema validation and sandboxing.

## Public API

```go
type Tool struct {
    Name        string
    Description string
    InputSchema json.RawMessage  // JSON Schema draft-07+
    Handler     Handler          // func(ctx, args json.RawMessage) (Result, error)
    Permission  Permission       // Allow | Ask | Deny
    Examples    []Example        // few-shot for the LLM
}

type Registry interface {
    Register(tool Tool) error
    Get(name string) (Tool, bool)
    List() []Tool
    Filter(policy Policy) []Tool
}

type Call struct {
    ID        string
    Name      string
    Arguments json.RawMessage
    Thought   string           // optional: chain-of-thought from the LLM
}

type Result struct {
    Content   string
    IsError   bool
    Metadata  map[string]string
    Artifacts []Artifact
}

type Permission int

const (
    Allow Permission = iota
    Ask
    Deny
)
```

## Integrated sandbox

`pkg/tools` uses `os.Root` (Go 1.24+) for filesystem sandbox:

```go
sandbox := tools.NewSandbox("./workspace")
sandbox.Register(myReadTool)  // can only read inside the workspace
```

See [pkg/tools/sandbox/](sandbox/) for details.

## Generic tools included

- `http_fetch` — GET URL with HTML→markdown
- `json_parse` — Parse arbitrary JSON
- `datetime_now` — Current timestamp

Product-specific tools (e.g., `read_file`, `bash` for software dev) are defined by each consumer in their own `internal/tools/`.

## See also

- [pkg/agent](../agent/README.md) — Executes tool calls
- [pkg/llm](../llm/README.md) — Tools are sent to the LLM