tool

type AskUserFunc ¶ added in v0.38.0

type AskUserFunc func(ctx context.Context, sessionID string, questions []question.Question) (question.Reply, error)

AskUserFunc puts a batch of questions in front of the user and blocks until they answer. Implemented by agent.LoopRunner.AskUser and wired in from server.go to avoid the tool→agent import cycle.

type AskUserTool ¶ added in v0.38.0

type AskUserTool struct {
	Ask AskUserFunc
}

AskUserTool puts a small batch of questions to the user and waits for the answers. It is the channel for whatever only the user can tell the agent — a preference, a constraint, a choice with real trade-offs, or a step of something they are meant to play along with (a quiz, a survey, a walk-through). What the agent can find out for itself — from the code, a file, the web, a command — does not belong here. The batch is rendered as paginated screens in one dialog; the answers come back as the tool result and the turn continues. It is a blocking round trip — the turn pauses until the user answers (or the run is cancelled).

A screen can depend on an earlier answer: give a question an id and gate the next one on it with showWhen, so the user only ever sees the branch that applies to them. The result reports both the answers given and which screens were skipped, so the model can see the path the user took.

It is only offered to an interactive session: the tool is registered where a question manager exists and the loop only offers it under permission gating (see LoopRunner.RunLoop). Headless runs and sub-agents never see it.

func (AskUserTool) Description() string

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

func (AskUserTool) ID() string

func (AskUserTool) Parameters() json.RawMessage

type BackgroundTaskFunc ¶ added in v0.51.0

type BackgroundTaskFunc func(ctx context.Context, sessionID, description, prompt string) (BackgroundTaskResult, error)

BackgroundTaskFunc starts the same shape of investigation as a persistent child on the agent board and returns at once, instead of blocking until the child finishes. The child's answer is delivered to the caller by the board's completion report — pushed into the caller's running turn when one is live, or handed over at its next turn start — and can be collected early with `teammate wait`. Implemented by server.spawnBackgroundTask; nil in environments with no board (CLI), where background mode is refused with a note.

type BackgroundTaskResult ¶ added in v0.51.0

type BackgroundTaskResult struct {
	Handle    string
	SessionID string
	URL       string
	Notice    string
	Live      int
}

BackgroundTaskResult is what starting a background task hands back: where the child runs and how the caller will hear about it.

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 BoardFunc ¶ added in v0.51.0

type BoardFunc func(ctx context.Context, sessionID string, req BoardRequest) (BoardResult, error)

BoardFunc carries out one board operation for the calling session. Implemented by the server and wired in from server.go to avoid the tool→server import cycle.

type BoardRequest ¶ added in v0.51.0

type BoardRequest struct {
	// Op is roster. Empty means roster, so a bare call is useful instead of an
	// error.
	Op string
}

BoardRequest is one operation on the project board.

type BoardResult ¶ added in v0.51.0

type BoardResult struct {
	// Roster is every agent on the board; the handles' spawned_by edges make it
	// a tree, which is what the tool prints.
	Roster []board.Handle
	// Notice is the one-line outcome the tool prints.
	Notice string
}

BoardResult is what one board operation produced.

type BoardTool ¶ added in v0.51.0

type BoardTool struct {
	Run BoardFunc
}

BoardTool shows the build agent the tree of agents working in the same project directory: who spawned whom, and what each one is doing.

func (BoardTool) Description() string

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

func (BoardTool) ID() string

func (BoardTool) Parameters() json.RawMessage

type BrowserClickTool ¶ added in v0.52.0

type BrowserClickTool struct{ Disp BrowserDispatcher }

BrowserClickTool clicks a snapshot ref or a CSS selector.

func (BrowserClickTool) Description() string

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

func (BrowserClickTool) ID() string

func (BrowserClickTool) Parameters() json.RawMessage

type BrowserConsoleTool ¶ added in v0.52.0

type BrowserConsoleTool struct{ Disp BrowserDispatcher }

BrowserConsoleTool reads the console output a driven tab captured.

func (BrowserConsoleTool) Description() string

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

func (BrowserConsoleTool) ID() string

func (BrowserConsoleTool) Parameters() json.RawMessage

type BrowserContentTool ¶ added in v0.52.0

type BrowserContentTool struct{ Disp BrowserDispatcher }

BrowserContentTool reads the page's visible text.

func (BrowserContentTool) Description() string

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

func (BrowserContentTool) ID() string

func (BrowserContentTool) Parameters() json.RawMessage

type BrowserDispatcher ¶ added in v0.52.0

type BrowserDispatcher = browser.Dispatcher

BrowserDispatcher is the live bridge behind every browser_* tool. A nil dispatcher or an unpaired bridge turns each call into a paired-up refusal rather than an error.

type BrowserKeyTool ¶ added in v0.52.0

type BrowserKeyTool struct{ Disp BrowserDispatcher }

BrowserKeyTool presses a named key.

func (BrowserKeyTool) Description() string

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

func (BrowserKeyTool) ID() string

func (BrowserKeyTool) Parameters() json.RawMessage

type BrowserNavigateTool ¶ added in v0.52.0

type BrowserNavigateTool struct{ Disp BrowserDispatcher }

BrowserNavigateTool moves a granted tab to a URL.

func (BrowserNavigateTool) Description() string

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

func (BrowserNavigateTool) ID() string

func (BrowserNavigateTool) Parameters() json.RawMessage

type BrowserNetworkTool ¶ added in v0.52.0

type BrowserNetworkTool struct{ Disp BrowserDispatcher }

BrowserNetworkTool reads the network traffic a driven tab captured.

func (BrowserNetworkTool) Description() string

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

func (BrowserNetworkTool) ID() string

func (BrowserNetworkTool) Parameters() json.RawMessage

type BrowserScreenshotTool ¶ added in v0.52.0

type BrowserScreenshotTool struct{ Disp BrowserDispatcher }

BrowserScreenshotTool captures a PNG and hands it to the model as an image.

func (BrowserScreenshotTool) Description() string

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

func (BrowserScreenshotTool) ID() string

func (BrowserScreenshotTool) Parameters() json.RawMessage

type BrowserScrollTool ¶ added in v0.52.0

type BrowserScrollTool struct{ Disp BrowserDispatcher }

BrowserScrollTool scrolls a granted tab.

func (BrowserScrollTool) Description() string

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

func (BrowserScrollTool) ID() string

func (BrowserScrollTool) Parameters() json.RawMessage

type BrowserSnapshotTool ¶ added in v0.52.0

type BrowserSnapshotTool struct{ Disp BrowserDispatcher }

BrowserSnapshotTool returns the compact numbered interactive-element view.

func (BrowserSnapshotTool) Description() string

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

func (BrowserSnapshotTool) ID() string

func (BrowserSnapshotTool) Parameters() json.RawMessage

type BrowserStatusTool ¶ added in v0.52.0

type BrowserStatusTool struct{ Disp BrowserDispatcher }

BrowserStatusTool reports the takeover connection. It answers even when the extension is not paired — that is exactly when it is useful.

func (BrowserStatusTool) Description() string

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

func (BrowserStatusTool) ID() string

func (BrowserStatusTool) Parameters() json.RawMessage

type BrowserTypeTool ¶ added in v0.52.0

type BrowserTypeTool struct{ Disp BrowserDispatcher }

BrowserTypeTool fills an input and optionally submits.

func (BrowserTypeTool) Description() string

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

func (BrowserTypeTool) ID() string

func (BrowserTypeTool) Parameters() json.RawMessage

type CheckSyntaxTool ¶ added in v0.25.0

type CheckSyntaxTool struct{}

CheckSyntaxTool parses a file with tree-sitter and reports its syntax errors.

The failure it catches is both common and quiet: a replaced block that drops a brace, an indentation slip in Python, a merge of two fragments that leaves a stray token, a JSON config missing a comma. None of those announce themselves — the file writes fine, and the damage surfaces later, in a build the agent may not run for several turns, by which point it has stacked more edits on a broken parse. (Python's indentation rules are enforced by codemap's own pass: the tree-sitter grammar accepts indentation CPython rejects.)

write and edit call syntaxNote for exactly that reason, which leaves this tool the cases they cannot cover: a file changed by a shell command, a formatter, a patch or a generator, and the confirmation that a fix landed.

The check is deliberately narrow. It shares the parse file_map already relies on, costs single-digit milliseconds, and needs no toolchain, so it works in any project — but it validates grammar only. It is a cheap guard against having broken the file, not a substitute for the compiler.

func (CheckSyntaxTool) Description() string

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

func (CheckSyntaxTool) ID() string

func (CheckSyntaxTool) Parameters() json.RawMessage

type CompactContextTool ¶ added in v0.26.1

type CompactContextTool struct{}

CompactContextTool lets the agent reclaim its own context mid-turn: it drops the earlier steps of the turn in exchange for a summary the agent writes. It is offered to every read-capable agent on every provider. Shedding finished work keeps the model's reasoning focused on what the task still needs and stops that work being re-sent every step; the token saving is largest where the endpoint does not cache a repeated prefix, but the focus it buys helps a long turn anywhere.

The tool itself only validates. The agent loop does the work: seeing this call, it records a watermark at the assistant message that made it, and from the next step onward assembles the request as the summary plus everything after that watermark. Nothing is deleted — the session store keeps every message, so history and the UI are unaffected — only the model-facing slice narrows.

func NewCompactContextTool() CompactContextTool

func (CompactContextTool) Description() string

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

func (CompactContextTool) ID() string

func (CompactContextTool) 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
	// Provider is the provider that serves Model. It rides along with Model so a
	// child session resolves the same provider: a model id can be served by more
	// than one provider (a plan model by both OGX and an OpenAI-compatible
	// endpoint), so the id alone does not identify one.
	Provider string
	// IntentMatcher is true when this turn runs the plan matcher: the steps the
	// agent states with update_intent are matched against the skills and MCP
	// tools it holds, and the result names the ones that fit. A tool that would
	// otherwise enumerate every candidate (the skill listing) uses it to stay
	// quiet instead of spending context on what the matcher already narrowed.
	IntentMatcher bool
	// FileLog is the read-bookmark gate: read records the revision it saw,
	// write and edit refuse a mutation another session made after it, and bash
	// records what a command changed among the files the gate has seen. nil (a
	// bare CLI run, a test, any loop with no database) is a no-op gate, so the
	// tools behave exactly as they did before it existed.
	FileLog *filechange.Log
}

Context is passed to every tool execution.

type DeepSearchFunc ¶ added in v0.8.0

type DeepSearchFunc func(ctx context.Context, query, dir, model, provider 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.Backend
}

FetchPageTool retrieves the text content of a URL via the configured search backend.

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(ranges=[{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 MCPToolInfo ¶ added in v0.49.0

type MCPToolInfo interface {
	MCPServer() string
	MCPServerDescription() string
	MCPToolName() string
}

MCPToolInfo is an optional interface implemented by tools adapted from an external MCP server, exposing the owning server's name, handshake summary, and raw tool name so the intent router can group MCP tools by server.

type MemoryMapTool ¶ added in v0.34.0

type MemoryMapTool struct {
	Store *memfile.Store
}

MemoryMapTool is the index over a project's per-turn markdown memory — the memory analogue of codebase_map. At project scope every conversation is collapsed to ONE line carrying its turn count and a sample of topic labels drawn from across its turns; calling again with subdir set to a conversation tag descends into it and lists that conversation's summaries as file lines — file name and topic labels, the way codebase_map lists a folder's files. Scope (project vs a single session) comes from the recall context, never from the model.

func NewMemoryMapTool(store *memfile.Store) MemoryMapTool

func (t MemoryMapTool) Description() string

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

func (t MemoryMapTool) ID() string

func (t MemoryMapTool) Parameters() json.RawMessage

type MemoryRecallTool ¶ added in v0.2.1

type MemoryRecallTool struct {
	Recall  RecallFunc
	Barrier RecallBarrier
}

MemoryRecallTool answers a question from the CURRENT session's persistent memory by delegating to the read-only recall sub-agent, which reads this session's dated markdown turn summaries. Barrier makes it wait for any in-flight background summary write to land before the lookup runs.

func NewMemoryRecallTool(recall RecallFunc, barrier RecallBarrier) 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.

The map shows one level at a time. Every folder at that level is a single line — how many files it holds, the subfolders directly inside it, and a sample of topic labels drawn from across the whole branch — whatever its size, and the files sitting directly at that level are listed with their own labels. The subdir parameter is the only way down: each call re-roots the map at that folder, and a subfolder named on a folder line can be jumped to directly. Output size therefore tracks how wide a level is, never how large the project is beneath it.

Text, code, PDF, and DOCX leaves all carry a flat topic-label array. A text or code file shows every label the index holds for it (the store caps that at MaxLabelsPerPage). For PDFs and DOCX files a subset is aggregated across pages; 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 {
	Recall  RecallFunc
	Barrier RecallBarrier
}

ProjectMemoryRecallTool answers a question from the project's persistent memory — every past conversation in this workspace — by delegating to the read-only recall sub-agent over the dated markdown turn summaries. The per-conversation route is MemoryRecallTool; this one is always project-wide.

func NewProjectMemoryRecallTool(recall RecallFunc, barrier RecallBarrier) 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 QuerySheetTool ¶ added in v0.55.0

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

QuerySheetTool executes a single read-only SQL query against the sheets of one spreadsheet file (CSV, TSV, XLSX or XLSM). The tool is the SQL probe behind the spreadsheet index: the file is profiled once (one sheet = one SQLite table named after the sheet), the DDL runs and the data rows stream from the loader's row source into a per-workbook in-memory database, and the query runs against it.

Everything is read-only and deterministic: the connection carries PRAGMA query_only=ON, the SQL is screened for writes and side-effecting statements, each query gets a 3s context timeout, the result is capped at 200 rows, and loading a workbook is bounded by a per-sheet row cap and a 30s deadline.

func (QuerySheetTool) Description() string

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

func (QuerySheetTool) ID() string

func (QuerySheetTool) 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 RecallBarrier ¶ added in v0.34.0

type RecallBarrier interface {
	Wait(project string)
}

RecallBarrier lets a recall wait for in-flight background turn-summary work to settle before it runs, so it never reads a stale or partial index. memfile.Manager satisfies it; a nil barrier waits for nothing.

type RecallFunc ¶ added in v0.34.0

type RecallFunc func(ctx context.Context, question, scope, targetSessionID, dir, model, provider string) (string, error)

RecallFunc runs the read-only memory recall sub-agent for a question at a given scope and returns its concise written answer. Implemented by agent.LoopRunner.RunMemoryRecallSession and wired in from server.go to avoid the tool→agent import cycle, exactly like TaskFunc.

type RecallScope ¶ added in v0.34.0

type RecallScope struct {
	// Scope is "project" (every summary in the workspace) or "session" (only the
	// target conversation's summaries).
	Scope string
	// SessionID is the conversation to restrict to when Scope is "session".
	SessionID string
	// ProjectID is the resolved workspace key whose summaries are in play.
	ProjectID string
}

RecallScope tells the memory_map tool which turn summaries the current recall is allowed to see. It is carried on the context rather than passed as tool arguments so the model can never widen its own scope or point recall at another conversation — the recall runner sets it from trusted values.

func RecallScopeFromContext(ctx context.Context) (RecallScope, bool)

type Registry ¶

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

Registry holds all registered tools.

A mutex guards the map because MCP server connections are established lazily in a background goroutine (after the HTTP server starts) and register their tools into the same registry the agent loop reads each step via ForAgent/Get. Without the lock that concurrent Register+read is a data race.

func NewRegistry() *Registry

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

func (r *Registry) Generation() uint64

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

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

func (r *Registry) Register(t ToolDef)

func (r *Registry) Remove(ids ...string)

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 either flag are capped to MaxToolOutputBytes/MaxToolOutputLines
	// before they enter the model context.
	Truncated bool `json:"truncated,omitempty"`
	// Uncapped marks that Output is deliberately whole content the backstop must
	// not bound. read and file_map set it: a clipped read is not a cheaper
	// answer, it is a wrong one. Internal to the loop — never sent to the client.
	Uncapped bool `json:"-"`
	// Denied marks that the tool call was rejected by the permission gate and was
	// never executed. The loop uses it to record a ToolDenied status (distinct
	// from ToolCompleted/ToolError) so the UI and DB reflect that the call was
	// blocked rather than run.
	Denied bool `json:"-"`
}

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 ScheduleFunc ¶ added in v0.52.0

type ScheduleFunc func(ctx context.Context, sessionID string, req ScheduleRequest) (ScheduleResult, error)

ScheduleFunc carries out one schedule operation for the calling session — creating, listing or cancelling a one-shot reminder. Implemented by the server and wired in from server.go to avoid the tool→server import cycle.

type ScheduleRequest ¶ added in v0.52.0

type ScheduleRequest struct {
	// Op is create, list or cancel.
	Op string `json:"op"`
	// DelaySeconds is how long from now a create fires. Exactly one of
	// DelaySeconds and FireAt is required on create.
	DelaySeconds int `json:"delaySeconds,omitempty"`
	// FireAt is an absolute RFC3339 time a create fires. Exactly one of
	// DelaySeconds and FireAt is required on create.
	FireAt string `json:"fireAt,omitempty"`
	// Note is what the reminder says when it fires; create requires it.
	Note string `json:"note,omitempty"`
	// ID is the reminder a cancel removes.
	ID string `json:"id,omitempty"`
}

ScheduleRequest is one operation on this session's reminders.

type ScheduleResult ¶ added in v0.52.0

type ScheduleResult struct {
	// ID and FireAt echo the reminder a create or cancel acted on. For a
	// delay-form create the handler fills FireAt as now+DelaySeconds in
	// RFC3339.
	ID     string `json:"id,omitempty"`
	FireAt string `json:"fireAt,omitempty"`
	// Timers are the reminders a list reports.
	Timers []ScheduledTimer `json:"timers,omitempty"`
}

ScheduleResult is what one schedule operation produced.

type ScheduleTool ¶ added in v0.52.0

type ScheduleTool struct{ Run ScheduleFunc }

ScheduleTool sets a one-shot reminder that is delivered back into the session's loop as a system notice when its deadline passes.

func (ScheduleTool) Description() string

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

func (ScheduleTool) ID() string

func (ScheduleTool) Parameters() json.RawMessage

type ScheduledTimer ¶ added in v0.52.0

type ScheduledTimer struct {
	ID     string `json:"id,omitempty"`
	Note   string `json:"note,omitempty"`
	FireAt string `json:"fireAt,omitempty"`
	Status string `json:"status,omitempty"`
}

ScheduledTimer is one pending reminder as a list reports it.

type SheetColumn ¶ added in v0.55.0

type SheetColumn struct {
	Name     string
	Type     string // "integer" | "number" | "date" | "boolean" | "text" | "empty"
	Affinity string // INTEGER | REAL | TEXT
	Min, Max string
	Distinct []string
}

SheetColumn and SheetProfile mirror the sheet-profiling contract of internal/indexer (same field names, same meanings). They are re-declared here because internal/tool cannot import internal/indexer — indexer imports agent, which imports tool — so the entry-point packages (server, cli) that see both convert the profiles across the seam (server.SheetProfilesFromIndexer).

type SheetProfile ¶ added in v0.55.0

type SheetProfile struct {
	Name    string
	Rows    int
	Cols    int
	Headers []string
	Columns []SheetColumn
	SQL     string
	Total   int // decoded cell bytes, when the profiler reports them

	// Tool-side build state, not part of the profiling contract. TotalRows is
	// the profiler's TRUE data-row count (Rows is the sampling-capped count);
	// Table, Loaded and Truncated are set by buildSheetDatabase.
	TotalRows int
	Table     string
	Loaded    int
	Truncated bool
}

SheetProfile is one sheet of one workbook: its shape, the inferred column profiles, and the DDL (a bare CREATE TABLE) that executes as-is into an in-memory SQLite database. The data rows do NOT ride in the SQL — they stream through the SheetRowSource the loader hands back alongside the profiles, so a workbook of any size never materializes in the tool.

type SheetRowSource ¶ added in v0.55.0

type SheetRowSource func(sheet string, feed func(rows []string) error) error

SheetRowSource streams one sheet's data rows (header row excluded) to feed in reading order, one []string per row, each value normalized exactly as the profiler normalized it. A nil source is valid: the workbook loads with schema only. A feed error aborts the load.

type SkillTool ¶ added in v0.27.0

type SkillTool struct {
	Loader *skill.Loader
}

SkillTool loads one skill's instructions into the agent's context.

A skill's instructions can run to thousands of tokens and the prompt is re-sent on every step of every turn, so bodies stay on disk and the agent pulls the one it needs. A session that runs the intent matcher never needs a menu: stating a plan names the skills fitted to its steps, and the listing is refused there so a turn cannot spend context on every skill it will not use. An agent with no matcher (and no <available_skills> block) can still get the menu from a bare call.

func NewSkillTool(l *skill.Loader) SkillTool

func (SkillTool) Description() string

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

func (SkillTool) ID() string

func (SkillTool) Parameters() json.RawMessage

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, provider 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
	// Spawn starts background: true investigations. nil (CLI, tests, embedders
	// without a board) makes background mode refuse with a note; sync runs keep
	// working unchanged.
	Spawn BackgroundTaskFunc
}

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).

Synchronous is the default and the old behaviour: the call blocks until the child answers. With background mode (Spawn wired) the child keeps running after this call returns and reports through the board's completion pipeline, so the caller's turn is not parked behind a minutes-long investigation.

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 TeammateFunc ¶ added in v0.51.0

type TeammateFunc func(ctx context.Context, sessionID string, req TeammateRequest) (TeammateResult, error)

TeammateFunc carries out one teammate operation for the calling session. Implemented by the server and wired in from server.go to avoid the tool→server import cycle.

type TeammateReport ¶ added in v0.51.0

type TeammateReport struct {
	Handle    string
	Status    string
	SessionID string
	// Text is the teammate's last message: what it was asked for, its result,
	// or the question it stopped on.
	Text string
}

TeammateReport is one teammate's final status and the message it left.

type TeammateRequest ¶ added in v0.51.0

type TeammateRequest struct {
	// Op is spawn, wait, stop or status.
	Op string
	// Name is the slug a spawn asks for. A name already on the roster, or a
	// reserved one (user, system, board), is refused rather than renamed.
	Name   string
	Prompt string
	// Handles is who a wait is watching; empty means every teammate this
	// session spawned.
	Handles []string
	// Handle is the single teammate stop and status act on.
	Handle string
	// Timeout bounds a wait, in seconds.
	Timeout int
}

TeammateRequest is one operation on a spawned teammate.

type TeammateResult ¶ added in v0.51.0

type TeammateResult struct {
	Handle    string
	SessionID string
	URL       string
	// Notice is the one-line outcome the tool prints.
	Notice string
	// Reports are the teammates a wait or status watched, with their result.
	Reports []TeammateReport
	// Roster is the board's current view of the caller's teammates.
	Roster []board.Handle
	// Live is the number of agents still working after the operation, so the
	// blast radius of a spawn is visible in the transcript.
	Live int
}

TeammateResult is what one teammate operation produced.

type TeammateTool ¶ added in v0.51.0

type TeammateTool struct {
	Run TeammateFunc
}

TeammateTool spawns and supervises the agents that work alongside the build agent in the same project directory.

func (TeammateTool) Description() string

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

func (TeammateTool) ID() string

func (TeammateTool) 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.

func NewBrowserTools(disp BrowserDispatcher) []ToolDef

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 UpdateIntentTool ¶ added in v0.49.0

type UpdateIntentTool struct{}

UpdateIntentTool lets the agent say where the turn is heading, ahead of doing the work. The transcript is retrospective — a tool row appears only once the work is done — so without this the user can only infer the agent's direction from a pile of finished actions. The plan is replaced whole on every call (last write wins), so it always describes what remains as the agent understands it now.

The tool itself only validates. The agent loop does the work: seeing this call, it writes the plan onto the session row and announces it, and the session header renders it as a pill.

func NewUpdateIntentTool() UpdateIntentTool

func (UpdateIntentTool) Description() string

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

func (UpdateIntentTool) ID() string

func (UpdateIntentTool) Parameters() json.RawMessage

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.Backend
}

WebSearchTool searches the web via the configured search backend 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