tool

type BashTool ¶

type BashTool struct{}

func (BashTool) Description() string

func (BashTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (BashTool) ID() string

func (BashTool) Parameters() json.RawMessage

type BreakdownInput ¶

type BreakdownInput struct {
	Tasks []struct {
		Title        string `json:"title"`
		Description  string `json:"description"`
		Dependencies []int  `json:"dependencies"`
		Effort       string `json:"effort"`
		Complexity   string `json:"complexity"`
		OrderIndex   int    `json:"orderIndex"`
	} `json:"tasks"`
}

BreakdownInput matches the tool's parameter schema.

type BreakdownTool ¶

type BreakdownTool struct{}

BreakdownTool receives a structured task breakdown from the breakdown agent. The LLM calls this tool with properly formatted JSON (guaranteed valid by the tool-calling system), eliminating free-text JSON parsing issues.

func (t BreakdownTool) Description() string

func (t BreakdownTool) Execute(_ context.Context, args json.RawMessage, _ Context) (Result, error)

func (t BreakdownTool) ID() string

func (t BreakdownTool) Parameters() json.RawMessage

type Context ¶

type Context struct {
	SessionID  session.SessionID
	MessageID  session.MessageID
	Agent      string
	CallID     string
	Ctx        context.Context
	SessionDir string
	Ask        func(req PermissionRequest) error
	Metadata   func(meta MetadataUpdate) error
	// ModelSupportsImages is true when the session's active model accepts image
	// input. Tools may use this to decide whether to return an image (e.g. a
	// rendered PDF page) instead of text.
	ModelSupportsImages bool
	// Model is the model ID the parent session is using. Tools that spawn child
	// sessions (e.g. deep_search) should inherit this so they run on the same model.
	Model string
}

Context is passed to every tool execution.

type DeepSearchFunc ¶ added in v0.8.0

type DeepSearchFunc func(ctx context.Context, query, dir, model string) (string, error)

DeepSearchFunc is a function that runs a child search-agent session and returns the synthesised answer. Implemented by agent.LoopRunner.RunSearchSession and wired in from server.go to avoid the tool→agent import cycle.

type DeepSearchTool ¶ added in v0.8.0

type DeepSearchTool struct {
	Run DeepSearchFunc
}

DeepSearchTool lets any agent delegate a research query to the SearchAgent. It creates an ephemeral child session, runs the full search loop, and returns the synthesised text as the tool result.

func (DeepSearchTool) Description() string

func (t DeepSearchTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (DeepSearchTool) ID() string

func (DeepSearchTool) Parameters() json.RawMessage

type DocxIndexTool ¶ added in v0.13.6

type DocxIndexTool struct {
	Store *docindex.Store
}

DocxIndexTool returns the stored semantic map for a DOCX file — pseudo-page labels — so the agent can decide which pages to read before calling read_docx_page.

func NewDocxIndexTool(store *docindex.Store) DocxIndexTool

func (DocxIndexTool) Description() string

func (t DocxIndexTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (DocxIndexTool) ID() string

func (DocxIndexTool) Parameters() json.RawMessage

type EditTool ¶

type EditTool struct{}

func (EditTool) Description() string

func (EditTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (EditTool) ID() string

func (EditTool) Parameters() json.RawMessage

type FetchPageTool ¶ added in v0.8.0

type FetchPageTool struct {
	Bridge *search.BridgeClient
}

FetchPageTool retrieves the text content of a URL via the Playwright bridge.

func (FetchPageTool) Description() string

func (t FetchPageTool) Execute(ctx context.Context, args json.RawMessage, _ Context) (Result, error)

func (FetchPageTool) ID() string

func (FetchPageTool) Parameters() json.RawMessage

type FileMapTool ¶ added in v0.24.0

type FileMapTool struct{}

FileMapTool returns the structural outline of a single file — every declaration it makes and the line range that declaration occupies — so the agent can read the one region it needs instead of the whole file.

It pairs with the read tool the way pdf_index pairs with read_pdf_page: file_map to decide where to look, read(start_line, end_line) to look. Unlike that pair it consults no index — the outline is parsed from the file on every call, so its ranges always describe the file's current contents.

func (FileMapTool) Description() string

func (FileMapTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (FileMapTool) ID() string

func (FileMapTool) Parameters() json.RawMessage

type GlobTool ¶

type GlobTool struct{}

func (GlobTool) Description() string

func (GlobTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (GlobTool) ID() string

func (GlobTool) Parameters() json.RawMessage

type GrepTool ¶

type GrepTool struct{}

func (GrepTool) Description() string

func (GrepTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (GrepTool) ID() string

func (GrepTool) Parameters() json.RawMessage

type LatexToPdfTool ¶ added in v0.9.1

type LatexToPdfTool struct{}

LatexToPdfTool compiles LaTeX source to PDF using pdflatex. It returns the path to the generated PDF file and, for vision-capable models, renders the first page as a JPEG image.

func (LatexToPdfTool) Description() string

func (LatexToPdfTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (LatexToPdfTool) ID() string

func (LatexToPdfTool) Parameters() json.RawMessage

type MemoryRecallTool ¶ added in v0.2.1

type MemoryRecallTool struct {
	Memory   *memory.Memory
	Registry *provider.Registry
}

MemoryRecallTool lets the LLM query the agentic knowledge graph on demand. Synthesis uses the session's currently selected model: the tool resolves the provider from the model ID via the registry and builds a per-call chat client.

func NewMemoryRecallTool(mem *memory.Memory, registry *provider.Registry) MemoryRecallTool

func (t MemoryRecallTool) Description() string

func (t MemoryRecallTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (t MemoryRecallTool) ID() string

func (t MemoryRecallTool) Parameters() json.RawMessage

type MetadataUpdate ¶

type MetadataUpdate struct {
	Title    string         `json:"title,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

MetadataUpdate updates the running tool call's display metadata.

type PdfIndexTool ¶ added in v0.6.0

type PdfIndexTool struct {
	Store *docindex.Store
}

PdfIndexTool returns the stored semantic map for a PDF — page labels — so the agent can decide which pages to read before calling read_pdf_page.

func NewPdfIndexTool(store *docindex.Store) PdfIndexTool

func (PdfIndexTool) Description() string

func (t PdfIndexTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (PdfIndexTool) ID() string

func (PdfIndexTool) Parameters() json.RawMessage

type PermissionRequest ¶

type PermissionRequest struct {
	ID        session.PermissionID
	SessionID session.SessionID
	Tool      string
	Input     string
}

PermissionRequest is sent when a tool needs user approval.

type ProjectIndexTool ¶ added in v0.7.0

type ProjectIndexTool struct {
	Store *docindex.Store
}

ProjectIndexTool returns a labeled tree of all indexed files in the session directory — text/code files, PDF documents, and DOCX documents alike — so the agent can navigate the project by topic without knowing file paths upfront.

Every file — text, code, PDF, or DOCX — appears as a leaf holding a flat topic-label array. For PDFs and DOCX files a concise subset of labels (capped at 15) is aggregated and de-duplicated across all pages, giving the agent a quick overview of what the document covers without the per-page breakdown. The dedicated pdf_index and docx_index tools provide the full per-page detail when the agent needs to decide which page to read.

func NewProjectIndexTool(store *docindex.Store) ProjectIndexTool

func (ProjectIndexTool) Description() string

func (t ProjectIndexTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (ProjectIndexTool) ID() string

func (ProjectIndexTool) Parameters() json.RawMessage

type ProjectMemoryRecallTool ¶ added in v0.23.0

type ProjectMemoryRecallTool struct {
	Memory   *memory.Memory
	Registry *provider.Registry
}

ProjectMemoryRecallTool queries the agentic knowledge graph across every conversation ever held in this workspace, where memory_recall only sees the current session. Synthesis uses the session's selected model, resolved per call from the registry — same contract as MemoryRecallTool.

func NewProjectMemoryRecallTool(mem *memory.Memory, registry *provider.Registry) ProjectMemoryRecallTool

func (t ProjectMemoryRecallTool) Description() string

func (t ProjectMemoryRecallTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (t ProjectMemoryRecallTool) ID() string

func (t ProjectMemoryRecallTool) Parameters() json.RawMessage

type ReadDocxPageTool ¶ added in v0.13.6

type ReadDocxPageTool struct{}

ReadDocxPageTool extracts the text of a single pseudo-page from a DOCX file for the agent to read. Use docx_index first to identify which pages are relevant, then call this tool to read their content.

func (ReadDocxPageTool) Description() string

func (ReadDocxPageTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (ReadDocxPageTool) ID() string

func (ReadDocxPageTool) Parameters() json.RawMessage

type ReadPdfPageTool ¶ added in v0.6.0

type ReadPdfPageTool struct{}

ReadPdfPageTool extracts the text of a single PDF page for the agent to read.

func (ReadPdfPageTool) Description() string

func (ReadPdfPageTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (ReadPdfPageTool) ID() string

func (ReadPdfPageTool) Parameters() json.RawMessage

type ReadTool ¶

type ReadTool struct{}

func (ReadTool) Description() string

func (ReadTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (ReadTool) ID() string

func (ReadTool) Parameters() json.RawMessage

type Registry ¶

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

Registry holds all registered tools.

func NewRegistry() *Registry

func (r *Registry) ForAgent(toolIDs []string) []ToolDef

func (r *Registry) Get(id string) ToolDef

func (r *Registry) List() []ToolDef

func (r *Registry) Register(t ToolDef)

type Result ¶

type Result struct {
	Title    string         `json:"title"`
	Metadata map[string]any `json:"metadata,omitempty"`
	Output   string         `json:"output"`
	// Image, when non-nil, is an image the tool wants the model to see (e.g. a
	// rendered PDF page). It is delivered to the model alongside Output, in a
	// provider-appropriate way. Only honored for vision-capable models.
	Image *ResultImage `json:"image,omitempty"`
	// Truncated marks that the tool already capped its own Output to a safe size.
	// The agent loop's global truncation backstop leaves such results untouched;
	// results without this flag are capped to MaxToolOutputBytes/MaxToolOutputLines
	// before they enter the model context.
	Truncated bool `json:"truncated,omitempty"`
}

Result is returned from tool execution.

type ResultImage ¶ added in v0.6.0

type ResultImage struct {
	MediaType string `json:"mediaType"`
	Data      string `json:"data"`
}

ResultImage is an image attachment on a tool Result. Data is base64-encoded image bytes; MediaType is e.g. "image/jpeg".

type SubmitDocIndexTool ¶ added in v0.6.0

type SubmitDocIndexTool struct {
	Store *docindex.Store
}

SubmitDocIndexTool allows the index agent to store semantic page labels.

func NewSubmitDocIndexTool(store *docindex.Store) SubmitDocIndexTool

func (SubmitDocIndexTool) Description() string

func (t SubmitDocIndexTool) Execute(_ context.Context, args json.RawMessage, _ Context) (Result, error)

func (SubmitDocIndexTool) ID() string

func (SubmitDocIndexTool) Parameters() json.RawMessage

type TaskFunc ¶ added in v0.21.0

type TaskFunc func(ctx context.Context, description, prompt, dir, model string) (string, error)

TaskFunc runs a read-only sub-agent session for a delegated investigation and returns its final written answer. Implemented by agent.LoopRunner.RunTaskSession and wired in from server.go/cli to avoid the tool→agent import cycle.

type TaskTool ¶ added in v0.21.0

type TaskTool struct {
	Run TaskFunc
}

TaskTool lets a coding/planning agent delegate a focused, self-contained investigation to an autonomous read-only sub-agent. The sub-agent explores the codebase (read/glob/grep/codebase_map) and, if needed, the web (deep_search), then returns a concise written answer as the tool result. It cannot edit files or run shell commands, and it cannot spawn further sub-agents (depth-1).

func (TaskTool) Description() string

func (t TaskTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (TaskTool) ID() string

func (TaskTool) Parameters() json.RawMessage

type ToolDef ¶

type ToolDef interface {
	ID() string
	Description() string
	Parameters() json.RawMessage
	Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)
}

ToolDef is the interface every tool must implement.

type TruncateDirection ¶ added in v0.21.0

type TruncateDirection int

TruncateDirection selects which end of the output to keep when it exceeds the caps. Most tools keep the head — the start of a file or listing is usually the useful part. Shell keeps the tail, because the end of a build/test log is where the error and summary live.

const (
	KeepHead TruncateDirection = iota
	KeepTail
)

type ViewImageTool ¶ added in v0.15.0

type ViewImageTool struct{}

ViewImageTool lets the agent view an image file (PNG, JPEG, GIF, BMP, WebP) on disk. For vision-capable models the decoded image is returned as a ResultImage; otherwise a textual description is returned.

func (ViewImageTool) Description() string

func (ViewImageTool) Execute(_ context.Context, args json.RawMessage, tctx Context) (Result, error)

func (ViewImageTool) ID() string

func (ViewImageTool) Parameters() json.RawMessage

type WebSearchTool ¶ added in v0.8.0

type WebSearchTool struct {
	Bridge *search.BridgeClient
}

WebSearchTool searches the web via the Playwright bridge and returns a markdown list of results.

func (WebSearchTool) Description() string

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

func (WebSearchTool) ID() string

func (WebSearchTool) Parameters() json.RawMessage

type WriteTool ¶

type WriteTool struct{}

func (WriteTool) Description() string

func (WriteTool) Execute(ctx context.Context, args json.RawMessage, tctx Context) (Result, error)

func (WriteTool) ID() string

func (WriteTool) Parameters() json.RawMessage