メインコンテンツへスキップ

Fundamental Tools (Grida binding)

This document binds the locked fundamental-tool RFC (../agent/tools.md) to Grida's host surfaces. The RFC names the shapes every conforming implementation MUST honor; this page records the identifiers, backends, and shipped deviations as Grida currently implements them.

For canvas-specific tools (scene-graph search, specialized inserts, canvas exec / lint / format, resource lookup), see tools-canvas.md. For image-generation tools, see tools-image.md.

Naming map (RFC → Grida)​

The RFC locks 13 ids (read, write, edit, glob, grep, bash, todo, task, question, web_search, web_fetch, skill, tool_search). Grida currently ships a _file / _files suffix on the fs tools and splits command execution into a start and an interaction tool. The divergence is recorded here, not endorsed — a future RFC item should reconcile (see Adding a new fundamental tool).

RFC idGrida idNotes
readread_fileSame shape; Grida's name is more specific.
writewrite_fileSame full-file upsert shape; creates or overwrites.
editedit_fileSame current-content replacement shape; Grida adds a strict ambiguity rule on multi-match.
globlist_filesGrida binding uses a path-scoped directory-listing shape; VFS hosts should provide it, real-fs hosts may omit it when command/search tools are stronger.
grepgrep_filesSame shape; literal substring search (regex is not shipped).
bashexec_command, write_stdinA command may outlive one call: the first starts it and waits briefly; the second reads, types into, or interrupts it.
todotodo_writeSame shape; replace-all semantics.
tasknot yet shippedSubagent spawn surfaced behind editor flows; expose as task once stable.
questionquestionShipped. Pauses the run on a human (client-resolved survey card); interactive hosts (desktop, serve daemon) answer it, headless hosts return a fixed refusal.
web_searchnot yet shippedHost-bound provider; out of scope for the first cut.
web_fetchnot yet shippedAs above.
skillnot yet shippedDiscovery layer pending.
tool_searchtool_search (proposed)Two-level (literal + semantic) proposed below; not yet implemented.

Backends​

Grida's filesystem tools are storage-agnostic by signature. The same read_file({ path }) call works against any backend; what differs is the adapter under the fs, not the schema the model sees.

Backend categoryWhereUse case
In-process storageapplication memoryTests, scratch documents, ad-hoc agent runs.
Browser storagebrowser originWeb environment (per agent/environments / web).
Host-scoped storagelocal host filesystemOpened Desktop/agent workspaces under the host's containment policy.
Remote storageservice boundaryMulti-tenant cloud product surfaces.

A path can be bound to live state (an editor, a doc model) or pure in-memory storage (notes, scratch). Both shapes share the API.

Per-tool deviations and Grida extensions​

Items where Grida's binding deviates from or extends the RFC shape.

read_file​

Returns the file's current text content. Read is how the agent understands an existing file and obtains exact edit context; it is not an authorization event. The tool exposes no session-local freshness token to the model. Grida bounds model-readable and model-mutable text files at 1 MiB of UTF-8; larger files return too_large. A storage read failure returns io_error, never not_found, so the agent cannot mistake an inaccessible existing file for a safe path to recreate.

edit_file​

Match-and-replace edit. The default write path — cheap, safe, must locate the change.

Each invocation loads current content and finds old_string. Where the storage layer supports an optimistic publication precondition, a detected concurrent change produces stale without clobbering the newer bytes. This narrows the validation-to-publication gap; it is not a claim of cross-process atomicity. A prior read_file is useful but not required: content from a successful write_file is already valid edit context, including after a pause or resumed run.

Matching: literal substring first, then a whitespace-normalized fallback. Ambiguous matches reject unless replace_all: true. The strategy is conservative on purpose: it tolerates whitespace drift, not semantic or broadly fuzzy matches.

write_file​

Full-file upsert. It creates a missing path or replaces all content at an existing path. The model-facing shape has no version argument: choosing this tool is the explicit intent to perform a last-writer-wins wholesale write. Targeted changes belong in edit_file.

Success means the full write has completed before the result returns. Content above the shared 1 MiB text bound is rejected with too_large, so every successful write can still be read and edited after a resumed run.

list_files​

Grida adopts a path-scoped directory-listing shape for the RFC's filesystem-discovery primitive. Despite the current Grida id, this tool is not a whole-workspace inventory.

list_files({
path?: string, // defaults to "/"
offset?: number,
limit?: number,
}) -> {
path: string,
folders: string[],
files: string[],
truncated: boolean,
next_offset?: number,
}

Contract:

  • path is rooted in the agent workspace or virtual filesystem. It must not be a general host-absolute path.
  • The result lists only the direct children of path, grouped into folders and files.
  • The result is sorted, paginated, and explicit about truncation.
  • list_files discovers names only. It does not return file content or provide textual edit context.
  • For filename-pattern search, use a separate glob / find-path tool rather than overloading this directory-listing result.

Implementation guidance:

  • VFS / OPFS / memory backends: provide list_files. A virtual filesystem may not have a shell, find, tree, or rg, so the structured directory-listing tool is the portable way for the agent to discover reachable paths.
  • Real filesystem backends: treat this tool as optional. A shell-capable real-fs agent often gets better behavior from explicit commands (rg --files, find, ls, tree) because those tools follow mature ignore rules, stream large output, and make scope visible in the command. A flat "all known files" tool can degrade agent quality by confusing the model into trusting an incomplete or stale index as ground truth.
  • Do not hide truncation. If a backend is indexed, capped, or ignore-filtered, the tool result must say so in-band.

grep_files​

Literal substring search across every known file. Returns one entry per matching line with a 1-indexed line number and the full line text. Mirrors grep -n -F (case-sensitive, fixed-string by default; pass case_sensitive: false for -i). A result may provide enough text for a unique edit, but the agent should read the file when it needs broader context.

Roadmap:

  • Level 1 (shipped): literal substring search. Cheap, deterministic, works offline.
  • Level 2 (future): semantic / RAG search. Higher cost; will ship as a separate tool name (e.g. semantic_search) so the model picks the cost tier explicitly.

todo_write​

Plan and track work. Pass the complete list of todos every call — the prior list is replaced wholesale.

{
"todos": [
{
"content": "Add a star",
"activeForm": "Adding a star",
"status": "in_progress"
}
]
}
  • Exactly one in_progress at a time. Enforced socially by the prompt; the visible list makes drift obvious.
  • No batched updates. The model should update as it works.
  • Replace-all. No per-item ops; the whole list is the input.

Use it when the work is non-trivial (multiple edits, exploration, anything you'd break into steps). Skip it for one-shot edits.

exec_command and write_stdin​

Grida's binding of the RFC's bash, split in two because a command can outlive the call that started it: a development server, a watcher, a long build, or an interactive program.

exec_command({
cmd: string, // command line, run as `<shell> -c cmd`
workdir?: string, // absolute; defaults to the selected directory's root
tty?: boolean, // pseudo-terminal; otherwise pipes with stdin closed
yield_time_ms?: number, // wait before returning; default 10000, 250–30000
max_output_tokens?: number, // output budget; default 10000, host-capped
// plus the host's approval fields where grants are scoped per directory
})

write_stdin({
session_id: number, // from an earlier result
chars?: string, // empty polls; "\u0003" interrupts
yield_time_ms?: number, // writes: default 250, at most 30000; polls: 5000–300000
max_output_tokens?: number,
})

Both return text:

Wall time: 1.2345 seconds
Process exited with code 0 (or: Process running with session ID 3)
Original token count: 12 (only when the output was shortened)
Output:
<output>

The contract:

  • The shell is named, not chosen by the model. It is the user's own POSIX shell when that is a known one at an absolute path, otherwise /bin/sh, and never a login or interactive shell. The call carries no environment, stdin, or shell selection.
  • A call waits for its whole yield. It returns at the end of its wait or when the command ends, never at the first output, so one call sees everything that arrived in that time.
  • A command that ends within its wait has no session. Its exit is reported once and nothing is retained.
  • A still-running command belongs to the conversation, not to the call or the turn. Ending, cancelling or pausing a turn, waiting for an approval, and resuming elsewhere leave it running; a later turn reaches it by its session ID. An explicit stop, revocation of its directory, deleting the conversation, eviction, and host shutdown end it, and the host's own exit ends it too.
  • Session IDs are per conversation, increasing, and never reused. The end of a session is reported once; after that its ID is unknown.
  • Pipes accept only an interrupt. A terminal session receives the characters as typed, including the interrupt character.
  • Output keeps its start and end. Over budget, the middle is replaced with a counted truncation marker; bytes the host could not retain are counted where they were dropped. An end by signal or stop is reported as such, never as an exit code.
  • Approval belongs to the start. Input to an approved session needs no approval of its own and reaches only the conversation's own sessions. A pre-execution policy check therefore sees the command line, not later input; a policy that must see every command refuses interactive shells.
  • Recovery is honest. A start or input whose result the host cannot account for after an interruption is uncertain; an empty poll may be repeated.
  • Bounded. A conversation keeps a bounded number of sessions. Starting another evicts the least recently used one, never one of the most recently used or one in use, ended ones first; if none qualifies, the start is refused.

Security expectation: command execution must run under a real sandbox boundary. Every command runs under execution confinement with its own authority set; see execution authority.

view_image (Grida extension)​

Grida's binding of the RFC visual perception contract — the visual twin of read_file. read_file returns text and stays text-only; view_image returns a raster image the model sees as pixels.

view_image({ path }) →
| { ok: true, mime, width?, height?, bytes, data /* base64 */ }
| { ok: false, reason: "not_found" | "unsupported_type" | "too_large", message }

Binding facts as Grida currently ships them:

  • v1 = raster bitmaps (png / jpeg / webp / gif), identified by magic bytes (never the extension). Rendering non-bitmap sources (svg / text / code → pixels) is the planned next step under this same tool name; the contract is shaped to absorb it without a rename.
  • Result-to-image lowering uses Strategy 1 (vision / lowering): the tool result carries the base64 payload and the tool declares a model-output lowering to a media block, so the perception reproduces from the persisted result on every rebuild — no bespoke replay path.
  • Retention. A stale view_image result drops its payload (lowering degrades to a naming descriptor); the bytes stay durable and the model re-views by calling the tool again. Pasted inline images are NOT auto-evicted (no re-view reference) — see vision / retention.
  • Capability. Needs only fs.read over the path — the same read scope as read_file; view_image joins the registry only when the host wires a byte source. Grida's workspace agent passes its filesystem (it exposes a raw-bytes read), so the tool sees workspace images by path.
  • Known v1 gap. A binary image is not yet surfaced by list_files (the text-hydrate skips it), so the agent perceives images the user names by path; autonomous discovery is a tracked follow-up.

It lives alongside the other fundamentals (the perception module is a sibling of the fs tools, not part of tools-image.md, which is image generation — a different verb).

tool_search (proposed)​

As the toolkit grows — fs + todos + canvas (15+) + future env tools

  • user-installed MCP servers — the model can't reasonably hold every tool's full schema in its working context. The RFC names a two-level (literal + semantic) discovery shape; Grida's binding will mirror it.
LevelSearch typeCostWhen
Level 1Text / token matchZeroDefault. Substring + ranked keyword match on tool name + description.
Level 2Semantic / embeddingCheap, non-zeroOptional fallback when text match is empty.

The model picks the level via a hint (mode: "literal" | "semantic"), default literal. Level 2 is invoked only on miss, keeping the typical path zero-cost.

tool_search({
query: "send slack message", // free-text intent
// or
select: ["read_file", "edit_file"], // exact tool names
max_results?: 5,
})
→ {
tools: [
{ name: "slack_post_message", description: "...", schema: {...} },
...
]
}

Status: proposed. The four shipped fundamentals plus the canvas tools are enough that we haven't felt the pinch. When the form-builder agent surface or the first MCP integration lands, this becomes the next thing to ship.

What lives where​

  • crates/grida-agent/src/file_tools.rs — filesystem fundamentals (source)
  • tool_search — not yet created; see proposal above
  • Document-specific tools belong to their editor implementations. See tools-canvas.md for the canvas capability catalog.

Adding a new fundamental tool​

Bar: would every agent want this, regardless of env? If yes, it's fundamental. Examples that pass the bar: filesystem, planning, tool discovery, time/clock, env metadata. Examples that fail: anything canvas-specific, anything network-bound (those are MCP or per-env).

Process:

  1. Confirm the RFC carries the shape — if not, propose it to ../agent/tools.md first.
  2. Implement it in the native agent (crates/grida-agent) with its own module, tool schema, and pure-logic tests.
  3. Add a row to the naming map above and a per-tool section below it.
  4. If it's vfs-only (only needed because we lack command execution), mark it so — the host can then drop it when command execution is available.

See also​