tools

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 24, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultOutputLimit is the maximum tool output size before truncation (30KB).
	DefaultOutputLimit = 30 * 1024
)

Variables

View Source 
var ErrPlanExitNotWired = errors.New("exit_plan_mode is not wired")

ErrPlanExitNotWired is returned when exit_plan_mode is invoked before the harness wires the exiter callback. Indicates a bootstrapping bug.

Functions

func BuildSkillForkArgs added in v0.1.0 

func BuildSkillForkArgs(result *skill.InvocationResult) (json.RawMessage, error)

func CleanOldOutputs added in v0.0.2 

func CleanOldOutputs()

CleanOldOutputs removes tool output files older than 7 days.

func NewCronTools added in v0.0.2 

func NewCronTools() (*cron.Store, []agentcore.Tool)

NewCronTools creates a cron.Store and the three cron tools that share it.

func NewTaskTools 

func NewTaskTools(store *storage.TaskStore, rt *task.Runtime, hookRunner *hooks.Runner) []agentcore.Tool

NewTaskTools creates the task tools for both planning and background execution. Pass nil for rt if background task tools are not needed.

func SetOutputDir added in v0.1.0 

func SetOutputDir(dir string)

SetOutputDir sets the directory used for large tool output files. Should be called once during bootstrap, before any tools execute.

func WrapWithOutputLimit added in v0.0.2 

func WrapWithOutputLimit(tools []agentcore.Tool) []agentcore.Tool

WrapWithOutputLimit wraps tools in the limitable set with output truncation. Tools not in the set are returned unchanged.

Types

type AllowToolsSetter added in v0.0.4 

type AllowToolsSetter func(tools []string)

AllowToolsSetter grants temporary tool permissions for the active skill. Called with nil/empty to clear grants from the previous skill.

type AllowedPromptArg added in v0.1.3 

type AllowedPromptArg struct {
	Tool   string `json:"tool"`
	Prompt string `json:"prompt"`
}

AllowedPromptArg is a semantic label the model may attach to exit_plan_mode to remind the user about follow-up actions (e.g. {Tool: "Bash", Prompt: "go test"}). These are reference-only — they do NOT auto-allow tool calls. The approval engine surfaces them in the plan-exit prompt preview alongside the plan body.

type AskUserHandler 

type AskUserHandler func(ctx context.Context, questions []Question) (*AskUserResponse, error)

AskUserHandler blocks until the user submits or dismisses the dialog. On dismiss, returns a Response with Cancelled=true (not an error) so partial answers can still reach the model.

type AskUserResponse 

type AskUserResponse struct {
	Answers   map[string][]string // question text → selected labels (or user-typed text)
	Notes     map[string]string   // question text → custom text the user typed
	Cancelled bool                // true if the user dismissed the dialog before submitting
}

AskUserResponse carries the outcome of an ask_user interaction.

Answers is always populated: an empty []string means the question was shown but not answered (only possible when Cancelled is true). Notes carries the raw text the user typed into "Type your own answer" — never echoed in the answer list, surfaced separately so the model sees it as user-authored.

type AskUserTool 

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

AskUserTool lets the model ask the user structured multi-choice questions.

func NewAskUser 

func NewAskUser() *AskUserTool

NewAskUser creates an AskUserTool with no handler. Call SetHandler before use.

func (*AskUserTool) Description 

func (t *AskUserTool) Description() string

func (*AskUserTool) Execute 

func (t *AskUserTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*AskUserTool) Label 

func (t *AskUserTool) Label() string

func (*AskUserTool) Name 

func (t *AskUserTool) Name() string

func (*AskUserTool) PermissionMetadata added in v0.1.3 

func (t *AskUserTool) PermissionMetadata() permission.Metadata

func (*AskUserTool) Schema 

func (t *AskUserTool) Schema() map[string]any

func (*AskUserTool) SetHandler 

func (t *AskUserTool) SetHandler(h AskUserHandler)

SetHandler installs the UI callback. Calling with nil disables the tool.

type CronCreateTool added in v0.0.2 

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

CronCreateTool creates a scheduled cron job.

func (*CronCreateTool) Description added in v0.0.2 

func (t *CronCreateTool) Description() string

func (*CronCreateTool) Execute added in v0.0.2 

func (t *CronCreateTool) Execute(_ context.Context, args json.RawMessage) (json.RawMessage, error)

func (*CronCreateTool) Label added in v0.0.2 

func (t *CronCreateTool) Label() string

func (*CronCreateTool) Name added in v0.0.2 

func (t *CronCreateTool) Name() string

func (*CronCreateTool) Schema added in v0.0.2 

func (t *CronCreateTool) Schema() map[string]any

Schema exposes cron, prompt, recurring to the LLM. The durable parameter is intentionally omitted from the LLM schema but accepted internally (used by /loop command).

func (*CronCreateTool) Store added in v0.0.2 

func (t *CronCreateTool) Store() *cron.Store

Store returns the underlying cron.Store.

type CronDeleteTool added in v0.0.2 

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

CronDeleteTool deletes a cron job by ID.

func (*CronDeleteTool) Description added in v0.0.2 

func (t *CronDeleteTool) Description() string

func (*CronDeleteTool) Execute added in v0.0.2 

func (t *CronDeleteTool) Execute(_ context.Context, args json.RawMessage) (json.RawMessage, error)

func (*CronDeleteTool) Label added in v0.0.2 

func (t *CronDeleteTool) Label() string

func (*CronDeleteTool) Name added in v0.0.2 

func (t *CronDeleteTool) Name() string

func (*CronDeleteTool) Schema added in v0.0.2 

func (t *CronDeleteTool) Schema() map[string]any

type CronListTool added in v0.0.2 

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

CronListTool lists all cron jobs.

func (*CronListTool) Description added in v0.0.2 

func (t *CronListTool) Description() string

func (*CronListTool) Execute added in v0.0.2 

func (t *CronListTool) Execute(_ context.Context, _ json.RawMessage) (json.RawMessage, error)

func (*CronListTool) Label added in v0.0.2 

func (t *CronListTool) Label() string

func (*CronListTool) Name added in v0.0.2 

func (t *CronListTool) Name() string

func (*CronListTool) Schema added in v0.0.2 

func (t *CronListTool) Schema() map[string]any

type EnterPlanModeTool added in v0.1.0 

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

func NewEnterPlanMode added in v0.0.2 

func NewEnterPlanMode() *EnterPlanModeTool

func (*EnterPlanModeTool) Description added in v0.1.0 

func (t *EnterPlanModeTool) Description() string

func (*EnterPlanModeTool) Execute added in v0.1.0 

func (t *EnterPlanModeTool) Execute(_ context.Context, _ json.RawMessage) (json.RawMessage, error)

func (*EnterPlanModeTool) Label added in v0.1.0 

func (t *EnterPlanModeTool) Label() string

func (*EnterPlanModeTool) Name added in v0.1.0 

func (t *EnterPlanModeTool) Name() string

func (*EnterPlanModeTool) PermissionMetadata added in v0.1.3 

func (t *EnterPlanModeTool) PermissionMetadata() permission.Metadata

func (*EnterPlanModeTool) Schema added in v0.1.0 

func (t *EnterPlanModeTool) Schema() map[string]any

func (*EnterPlanModeTool) SetHandler added in v0.1.3 

func (t *EnterPlanModeTool) SetHandler(fn func() (string, error))

func (*EnterPlanModeTool) SetValidator added in v0.1.0 

func (t *EnterPlanModeTool) SetValidator(fn func() error)

type ExitPlanModeTool added in v0.1.0 

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

func NewExitPlanMode added in v0.0.2 

func NewExitPlanMode() *ExitPlanModeTool

func (*ExitPlanModeTool) Description added in v0.1.0 

func (t *ExitPlanModeTool) Description() string

func (*ExitPlanModeTool) Execute added in v0.1.0 

func (t *ExitPlanModeTool) Execute(_ context.Context, _ json.RawMessage) (json.RawMessage, error)

func (*ExitPlanModeTool) Label added in v0.1.0 

func (t *ExitPlanModeTool) Label() string

func (*ExitPlanModeTool) Name added in v0.1.0 

func (t *ExitPlanModeTool) Name() string

func (*ExitPlanModeTool) PermissionMetadata added in v0.1.3 

func (t *ExitPlanModeTool) PermissionMetadata() permission.Metadata

func (*ExitPlanModeTool) Schema added in v0.1.0 

func (t *ExitPlanModeTool) Schema() map[string]any

func (*ExitPlanModeTool) SetExiter added in v0.1.3 

func (t *ExitPlanModeTool) SetExiter(fn func() (string, error))

SetExiter wires the plan-mode state transition. Called only after the permission engine has approved the exit (CC-style: ExitPlanMode declares checkPermissions:'ask', so the user has already seen the plan and chosen approve before the tool runs). The callback returns the approved plan content so it can be echoed in the tool result for the model.

func (*ExitPlanModeTool) SetValidator added in v0.1.0 

func (t *ExitPlanModeTool) SetValidator(fn func() error)

type FetchProvider 

type FetchProvider interface {
	Fetch(ctx context.Context, targetURL string) (string, error)
}

FetchProvider performs web page content extraction.

type ForkExecutor added in v0.0.4 

type ForkExecutor func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

ForkExecutor runs a task in a forked subagent context. It matches the SubAgentTool.Execute signature so it can be wired directly.

type InvocationApplier added in v0.1.0 

type InvocationApplier func(result *skill.InvocationResult) error

type JinaFetchProvider 

type JinaFetchProvider struct {
	APIKey  string
	Client  *http.Client
	BaseURL string
}

func (*JinaFetchProvider) Fetch 

func (p *JinaFetchProvider) Fetch(ctx context.Context, targetURL string) (string, error)

type JinaProvider 

type JinaProvider struct {
	APIKey  string
	Client  *http.Client // nil uses default with 30s timeout
	BaseURL string       // default: https://s.jina.ai/
}

JinaProvider implements SearchProvider using the Jina search endpoint. It calls POST https://s.jina.ai/ with X-Respond-With: no-content to return only SERP metadata (title, URL, snippet) without full page content.

func (*JinaProvider) Search 

func (p *JinaProvider) Search(ctx context.Context, query string, maxResults int) ([]SearchResult, error)

type Option 

type Option struct {
	Label       string `json:"label"`
	Description string `json:"description"`
	Preview     string `json:"preview,omitempty"`
}

Option is a selectable choice for a question.

type OutputLimitedTool added in v0.0.2 

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

OutputLimitedTool wraps a Tool and truncates oversized output to disk.

func (*OutputLimitedTool) Description added in v0.0.2 

func (t *OutputLimitedTool) Description() string

func (*OutputLimitedTool) Execute added in v0.0.2 

func (t *OutputLimitedTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*OutputLimitedTool) Label added in v0.0.2 

func (t *OutputLimitedTool) Label() string

Label forwards the optional ToolLabeler interface.

func (*OutputLimitedTool) Name added in v0.0.2 

func (t *OutputLimitedTool) Name() string

func (*OutputLimitedTool) Schema added in v0.0.2 

func (t *OutputLimitedTool) Schema() map[string]any

func (*OutputLimitedTool) Unwrap added in v0.0.3 

func (t *OutputLimitedTool) Unwrap() agentcore.Tool

Unwrap returns the underlying tool, allowing type assertions through the wrapper.

type Question 

type Question struct {
	Question    string   `json:"question"`
	Header      string   `json:"header"`
	Options     []Option `json:"options"`
	MultiSelect bool     `json:"multiSelect,omitempty"`
	// Custom controls whether the host renders a built-in "Type your own
	// answer" entry below the listed options. Nil = default true.
	Custom *bool `json:"custom,omitempty"`
}

Question is a single multi-choice question.

func (Question) AllowsCustom added in v0.1.3 

func (q Question) AllowsCustom() bool

AllowsCustom reports whether the host should render a built-in "Type your own answer" entry for this question.

type SearchProvider 

type SearchProvider interface {
	Search(ctx context.Context, query string, maxResults int) ([]SearchResult, error)
}

SearchProvider performs web searches.

type SearchResult 

type SearchResult struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"content"`
}

SearchResult represents a single web search result.

type SendToSubAgentTool added in v0.1.3 

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

SendToSubAgentTool queues a user-style message to a background sub-agent's next turn. The sub-agent's loop drains it through GetSteeringMessages, so the message becomes visible at the next steering tick (turn boundary or post-tool) rather than waiting for the agent to decide to stop.

This is the parent→child runtime communication path. A sub-agent CANNOT use this tool — when team support lands it will get its own peer-messaging tool, and send_to_subagent stays strictly parent→child to keep the channels distinct. tool_filter.go enforces the exclusion.

Terminal tasks are NOT auto-resumed. CC resumes from on-disk transcripts; that's a stage 6 capability. Today we report the failure verbatim so the model can tell the user the message was not delivered.

func NewSendToSubAgentTool added in v0.1.3 

func NewSendToSubAgentTool(rt *task.Runtime) *SendToSubAgentTool

NewSendToSubAgentTool constructs the tool. nil rt is a programmer error — the tool is meaningless without a runtime to look tasks up in.

func (*SendToSubAgentTool) Description added in v0.1.3 

func (t *SendToSubAgentTool) Description() string

func (*SendToSubAgentTool) Execute added in v0.1.3 

func (t *SendToSubAgentTool) Execute(_ context.Context, args json.RawMessage) (json.RawMessage, error)

func (*SendToSubAgentTool) Label added in v0.1.3 

func (t *SendToSubAgentTool) Label() string

func (*SendToSubAgentTool) Name added in v0.1.3 

func (t *SendToSubAgentTool) Name() string

func (*SendToSubAgentTool) Schema added in v0.1.3 

func (t *SendToSubAgentTool) Schema() map[string]any

type SkillExecutionResult added in v0.1.0 

type SkillExecutionResult struct {
	PromptText string
	Forked     bool
	ForkOutput json.RawMessage
}

func ExecuteSkillInvocation added in v0.1.0 

func ExecuteSkillInvocation(ctx context.Context, result *skill.InvocationResult, apply InvocationApplier, fork ForkExecutor) (*SkillExecutionResult, error)

type SkillTool added in v0.0.4 

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

SkillTool lets the LLM invoke skills by name. It loads the skill file, strips frontmatter, expands $ARGUMENTS placeholders, and returns the formatted content as a tool result. Skills with context: fork are delegated to a subagent via the ForkExecutor.

func NewSkillTool added in v0.0.4 

func NewSkillTool(catalog *skill.Catalog, sessionID string) *SkillTool

NewSkillTool creates a SkillTool with the given initial skill list.

func (*SkillTool) Description added in v0.0.4 

func (t *SkillTool) Description() string

func (*SkillTool) Execute added in v0.0.4 

func (t *SkillTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*SkillTool) Label added in v0.0.4 

func (t *SkillTool) Label() string

func (*SkillTool) Name added in v0.0.4 

func (t *SkillTool) Name() string

func (*SkillTool) Schema added in v0.0.4 

func (t *SkillTool) Schema() map[string]any

func (*SkillTool) SetAllowToolsSetter added in v0.0.4 

func (t *SkillTool) SetAllowToolsSetter(fn AllowToolsSetter)

SetAllowToolsSetter sets the function used to grant temporary tool permissions.

func (*SkillTool) SetCatalog added in v0.1.0 

func (t *SkillTool) SetCatalog(catalog *skill.Catalog)

SetCatalog replaces the active skill catalog (called on /reload).

func (*SkillTool) SetForkExecutor added in v0.0.4 

func (t *SkillTool) SetForkExecutor(fn ForkExecutor)

SetForkExecutor sets the function used to run context: fork skills in a subagent.

func (*SkillTool) SetInvocationApplier added in v0.1.0 

func (t *SkillTool) SetInvocationApplier(fn InvocationApplier)

type TaskCreateTool 

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

TaskCreateTool creates new tasks.

func (*TaskCreateTool) ConcurrencySafe added in v0.1.1 

func (t *TaskCreateTool) ConcurrencySafe(_ json.RawMessage) bool

func (*TaskCreateTool) Description 

func (t *TaskCreateTool) Description() string

func (*TaskCreateTool) Execute 

func (t *TaskCreateTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*TaskCreateTool) Label 

func (t *TaskCreateTool) Label() string

func (*TaskCreateTool) Name 

func (t *TaskCreateTool) Name() string

func (*TaskCreateTool) Schema 

func (t *TaskCreateTool) Schema() map[string]any

func (*TaskCreateTool) SetNotifyFn 

func (t *TaskCreateTool) SetNotifyFn(fn storage.TaskNotifyFn)

SetNotifyFn registers the TUI notification callback (delegates to store).

func (*TaskCreateTool) Store 

func (t *TaskCreateTool) Store() *storage.TaskStore

Store returns the underlying TaskStore.

type TaskGetTool 

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

TaskGetTool retrieves a single task by ID.

func (*TaskGetTool) ConcurrencySafe added in v0.1.1 

func (t *TaskGetTool) ConcurrencySafe(_ json.RawMessage) bool

func (*TaskGetTool) Description 

func (t *TaskGetTool) Description() string

func (*TaskGetTool) Execute 

func (t *TaskGetTool) Execute(_ context.Context, args json.RawMessage) (json.RawMessage, error)

func (*TaskGetTool) Label 

func (t *TaskGetTool) Label() string

func (*TaskGetTool) Name 

func (t *TaskGetTool) Name() string

func (*TaskGetTool) PermissionMetadata added in v0.1.3 

func (t *TaskGetTool) PermissionMetadata() permission.Metadata

func (*TaskGetTool) ReadOnly added in v0.1.1 

func (t *TaskGetTool) ReadOnly(_ json.RawMessage) bool

func (*TaskGetTool) Schema 

func (t *TaskGetTool) Schema() map[string]any

type TaskListTool 

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

TaskListTool lists all tasks.

func (*TaskListTool) ConcurrencySafe added in v0.1.1 

func (t *TaskListTool) ConcurrencySafe(_ json.RawMessage) bool

func (*TaskListTool) Description 

func (t *TaskListTool) Description() string

func (*TaskListTool) Execute 

func (t *TaskListTool) Execute(_ context.Context, _ json.RawMessage) (json.RawMessage, error)

func (*TaskListTool) Label 

func (t *TaskListTool) Label() string

func (*TaskListTool) Name 

func (t *TaskListTool) Name() string

func (*TaskListTool) PermissionMetadata added in v0.1.3 

func (t *TaskListTool) PermissionMetadata() permission.Metadata

func (*TaskListTool) ReadOnly added in v0.1.1 

func (t *TaskListTool) ReadOnly(_ json.RawMessage) bool

func (*TaskListTool) Schema 

func (t *TaskListTool) Schema() map[string]any

type TaskOutputTool added in v0.1.0 

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

TaskOutputTool lets the model query or wait for background task output.

func (*TaskOutputTool) Description added in v0.1.0 

func (t *TaskOutputTool) Description() string

func (*TaskOutputTool) Execute added in v0.1.0 

func (t *TaskOutputTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*TaskOutputTool) Label added in v0.1.0 

func (t *TaskOutputTool) Label() string

func (*TaskOutputTool) Name added in v0.1.0 

func (t *TaskOutputTool) Name() string

func (*TaskOutputTool) Schema added in v0.1.0 

func (t *TaskOutputTool) Schema() map[string]any

type TaskStopTool added in v0.1.0 

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

TaskStopTool lets the model terminate a background task.

func (*TaskStopTool) Description added in v0.1.0 

func (t *TaskStopTool) Description() string

func (*TaskStopTool) Execute added in v0.1.0 

func (t *TaskStopTool) Execute(_ context.Context, args json.RawMessage) (json.RawMessage, error)

func (*TaskStopTool) Label added in v0.1.0 

func (t *TaskStopTool) Label() string

func (*TaskStopTool) Name added in v0.1.0 

func (t *TaskStopTool) Name() string

func (*TaskStopTool) Schema added in v0.1.0 

func (t *TaskStopTool) Schema() map[string]any

type TaskUpdateTool 

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

TaskUpdateTool modifies an existing task.

func (*TaskUpdateTool) ConcurrencySafe added in v0.1.1 

func (t *TaskUpdateTool) ConcurrencySafe(_ json.RawMessage) bool

func (*TaskUpdateTool) Description 

func (t *TaskUpdateTool) Description() string

func (*TaskUpdateTool) Execute 

func (t *TaskUpdateTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*TaskUpdateTool) Label 

func (t *TaskUpdateTool) Label() string

func (*TaskUpdateTool) Name 

func (t *TaskUpdateTool) Name() string

func (*TaskUpdateTool) Schema 

func (t *TaskUpdateTool) Schema() map[string]any

type TavilyFetchProvider 

type TavilyFetchProvider struct {
	APIKey string
	Client *http.Client
}

func (*TavilyFetchProvider) Fetch 

func (p *TavilyFetchProvider) Fetch(ctx context.Context, targetURL string) (string, error)

type TavilyProvider 

type TavilyProvider struct {
	APIKey string
	Client *http.Client // nil uses default with 30s timeout
}

TavilyProvider implements SearchProvider using the Tavily API.

func (*TavilyProvider) Search 

func (p *TavilyProvider) Search(ctx context.Context, query string, maxResults int) ([]SearchResult, error)

type WebFetchTool 

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

WebFetchTool fetches web content and returns markdown.

func NewWebFetch 

func NewWebFetch(providerName, apiKey string) *WebFetchTool

NewWebFetch creates a WebFetchTool for the configured provider. Supported providers: tavily, jina.

func (*WebFetchTool) Description 

func (t *WebFetchTool) Description() string

func (*WebFetchTool) Execute 

func (t *WebFetchTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*WebFetchTool) Label 

func (t *WebFetchTool) Label() string

func (*WebFetchTool) Name 

func (t *WebFetchTool) Name() string

func (*WebFetchTool) Schema 

func (t *WebFetchTool) Schema() map[string]any

type WebSearchTool 

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

WebSearchTool provides web search capability.

func NewWebSearch 

func NewWebSearch(providerName, apiKey string) *WebSearchTool

NewWebSearch creates a WebSearchTool for the configured provider. Supported providers: tavily, jina.

func (*WebSearchTool) Description 

func (t *WebSearchTool) Description() string

func (*WebSearchTool) Execute 

func (t *WebSearchTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*WebSearchTool) Label 

func (t *WebSearchTool) Label() string

func (*WebSearchTool) Name 

func (t *WebSearchTool) Name() string

func (*WebSearchTool) Schema 

func (t *WebSearchTool) Schema() map[string]any

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.