tools

type AskUserOptions ¶

type AskUserOptions struct {
	// Prompter is the consumer's delivery mechanism. Required.
	Prompter Prompter

	// Name overrides the tool's function name. Defaults to "ask_user"
	// when empty.
	Name string

	// Description overrides the tool's description (the prose the
	// model sees in its function-decl list). Empty falls back to a
	// sensible default.
	Description string
}

AskUserOptions configures NewAskUserTool.

type BuiltinTools ¶

type BuiltinTools struct {
	Bash      bool // /bin/sh -c with timeout + denylist + gate
	ReadFile  bool // Read a file with offset/limit
	WriteFile bool // Atomic write/create
	EditFile  bool // Single-occurrence string replacement
	ListDir   bool // Sorted directory listing
	Glob      bool // Walk + filepath.Match by basename
	Grep      bool // Walk + RE2 regex per line
	Todo      bool // In-process plan tracker
}

BuiltinTools toggles core-agent's built-in tool suite. Each enabled flag becomes one entry in the returned Registry's Tools slice.

All defaults are on — every consumer that's writing an agent will almost certainly want read/write/edit/list/bash. The Todo store is always created; the toggle just controls whether the model can drive it via the `todo` tool.

To turn one off:

reg, _ := tools.Build(cfg, gate, tools.BuiltinTools{
    Bash: false,        // disable shell
    ReadFile: true,
    WriteFile: true,
    EditFile: true,
    ListDir: true,
    Todo: true,
})

Or use Default() and override fields directly or via Disable:

b := tools.Default()
b.Disable("bash")               // by canonical name; errors on typos
b.WriteFile = false             // or set the field directly
reg, _ := tools.Build(cfg, gate, b)

func Default() BuiltinTools

func (b *BuiltinTools) Disable(name string) error

type LifecycleEvent ¶

type LifecycleEvent struct {
	State  string
	Detail string
	Time   time.Time
}

LifecycleEvent is the payload delivered to a LifecycleHandler each time the model calls a tool built by NewLifecycleTool. State is the value the model passed (e.g. "thinking", "blocked", "done"); Detail is the optional human-readable context. Time is the moment the handler received the call.

type LifecycleHandler ¶

type LifecycleHandler func(ctx context.Context, ev LifecycleEvent) error

LifecycleHandler receives each lifecycle emit. Returning a non-nil error surfaces the error string back to the model as the tool's response — useful for "this state isn't valid right now" feedback. A nil return acks the call with a generic "ok" so the model can keep working.

type LifecycleOptions ¶

type LifecycleOptions struct {
	// Handler is invoked once per emit. Required.
	Handler LifecycleHandler

	// Name overrides the tool's function name. Defaults to
	// "set_status" when empty.
	Name string

	// Description overrides the tool's description (the prose the
	// model sees in its function-decl list). Empty falls back to a
	// sensible default.
	Description string

	// AllowedStates, when non-empty, restricts the State values the
	// tool will accept. A call with a State outside the set is
	// rejected with an error result returned to the model — the
	// handler is not invoked for the rejected call.
	AllowedStates []string
}

LifecycleOptions configures NewLifecycleTool.

type Prompter ¶

type Prompter interface {
	Prompt(ctx context.Context, question string) (string, error)
}

Prompter delivers a question from the agent to a human (or any external authority) and returns their answer. Implementations decide the channel — stdin, websocket, queue, file watch, etc.

Returning a non-nil error signals "no user available" or transport failure; the agent sees the error string as the tool's response and can adapt (typically by proceeding with its best assumption or reporting the problem) instead of blocking forever.

Prompt should respect ctx cancellation so SIGTERM, deadlines, and agent-driven aborts unblock the tool cleanly.

func RefusePrompter(reason string) Prompter

tools.RefusePrompter("running unattended; proceed with reasonable defaults and explain in your final response")

func StaticPrompter(answer string) Prompter

func StdinPrompter(in io.Reader, out io.Writer) Prompter

type PrompterFunc ¶

type PrompterFunc func(ctx context.Context, question string) (string, error)

PrompterFunc adapts a function to the Prompter interface for one-off uses.

func (f PrompterFunc) Prompt(ctx context.Context, q string) (string, error)

type Registry ¶

type Registry struct {
	Tools []tool.Tool
	Todo  *TodoStore
}

Registry is the assembled built-in tool set returned by Build.

Tools is the slice you pass to agent.WithTools(...). Todo is the underlying store, exposed so hosts can render plan progress (e.g. for a /todo slash command in a TUI).

func Build(cfg *config.Config, gate *permissions.Gate, b BuiltinTools) (*Registry, error)

type TodoItem ¶

type TodoItem struct {
	ID     int    `json:"id"`
	Status string `json:"status"` // "pending" | "in_progress" | "completed"
	Text   string `json:"text"`
}

TodoItem is one entry in the agent's plan.

type TodoStore ¶

type TodoStore struct {
	// contains filtered or unexported fields
}

TodoStore is the in-process backing for the agent's todo list. Ephemeral (one store per core-agent process); persistence across sessions can be added later if a consumer needs it.

func NewTodoStore() *TodoStore

func (s *TodoStore) Items() []TodoItem