@theokit/sdk-tools 0.27.0 → 0.27.2

package/dist/index.d.ts

@@ -34,6 +34,21 @@ interface CreateApplyPatchToolOptions {
     /** Absolute path to the project root. Every hunk path is gated against this boundary. */
     projectRoot: string;
 }
+/**
+ * Build the `apply_patch` tool over Codex's V4A patch grammar — one call that adds, updates, deletes
+ * and moves several files at once.
+ *
+ * Prefer it to a run of {@link createEditFileTool} calls when a change spans files, because the whole
+ * patch is planned before anything is written: every file read, every new content computed and every
+ * path security-checked first, and any failure aborts with zero writes. A sequence of `edit_file`
+ * calls has no such property — the third can fail with the first two already on disk. The price is
+ * that it leaves no backup, where `edit_file` writes a `.bak`.
+ *
+ * Refusals: `parse_error`, `path_traversal`, `forbidden_path` (checked at every path segment here,
+ * not just the first), `not_found`, `patch_failed` (context did not match), `duplicate_target` (two
+ * hunks touching one file, which would silently lose the earlier edit), `file_exists` (Add over an
+ * existing file) and `io_error` for anything the filesystem raises during the write phase.
+ */
 declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;
 
 /**
@@ -114,6 +129,17 @@ interface CreateCurrentTimeToolOptions {
     /** Injectable clock — defaults to `() => new Date()`. Pass a fixed clock for deterministic tests. */
     clock?: () => Date;
 }
+/**
+ * Build the `current_time` tool, so the model reads a clock instead of stating a date from training
+ * data.
+ *
+ * The model may pass an IANA `timezone`; omitted, the answer is UTC. An unknown zone comes back as
+ * `{ ok: false, error: "invalid_timezone" }` — the `RangeError` `Intl` raises is caught, so the
+ * handler never throws at the model.
+ *
+ * Pass `clock` in tests. The default reads the real wall clock, and a test asserting on a formatted
+ * date without injecting one is asserting on the day it was written.
+ */
 declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): CustomTool;
 
 /**
@@ -124,7 +150,7 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
  *
  * Return shape (always a JSON string):
  *   - `{ ok: true, replacements: 1 }` on success
- *   - `{ ok: false, error: 'no_match' | 'not_found' | 'path_traversal' |
+ *   - `{ ok: false, error: 'no_change' | 'no_match' | 'not_found' | 'path_traversal' |
  *        'forbidden_path' }` on refusal
  */
 
@@ -146,6 +172,21 @@ interface CreateEditFileToolOptions {
      *  write go through the backend (surface-agnostic); omitted ⇒ the local `fs` path (byte-identical). */
     filesystem?: FilesystemProvider;
 }
+/**
+ * Build the `edit_file` tool: replace one occurrence of `old_string` with `new_string` in place,
+ * after copying the previous content to `<path>.bak`.
+ *
+ * Three matching attempts run in order and the first hit wins — the exact substring, then the same
+ * text with runs of whitespace collapsed, then a line-based ladder tolerating trailing whitespace and
+ * typographic punctuation. The FIRST exact occurrence is taken with no ambiguity check, so a short
+ * `old_string` appearing twice edits the earlier one silently: include enough surrounding context to
+ * make it unique. Only the ladder refuses an ambiguous target, and it is reached only when the exact
+ * and whitespace-normalised passes have both failed.
+ *
+ * `old_string === new_string` is refused up front as `no_change`; the other refusals are `no_match`,
+ * `not_found`, `forbidden_path` and `path_traversal`. Exactly one occurrence changes per call, so
+ * replacing every occurrence means calling until `no_match`.
+ */
 declare function createEditFileTool(opts: CreateEditFileToolOptions): CustomTool;
 
 /**
@@ -192,13 +233,31 @@ interface CreateGitDiffToolOptions {
     name?: string;
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
     description?: string;
+    /** Absolute path to the project root. `git` runs here and every `path` scope is gated against it. */
     projectRoot: string;
+    /** Wall-clock cap on the local `git` child; the process group is killed on expiry. Default 30_000. */
     timeoutMs?: number;
+    /** Cap on captured stdout; excess sets `truncated: true`. Default 5 MB. Local path only. */
     maxStdoutBytes?: number;
     /** Optional injected execution backend (`@theokit/sdk/sandbox`) — when provided, `git diff` runs via
      *  `SandboxBackend.execute` (surface-agnostic); omitted ⇒ the local `git` child process (unchanged). */
     sandbox?: SandboxProvider;
 }
+/**
+ * Build the `git_diff` tool: `git diff --no-color` over the working tree, or the staged changes when
+ * the model passes `cached`.
+ *
+ * Reach for it before a commit or after a run of edits, when the question is what CHANGED rather than
+ * what a file now contains — `read_file` answers the latter and spends a whole file doing it.
+ *
+ * Refusals are `not_a_repo`, `path_traversal`, `timeout` and `git_failed`. The local path kills the
+ * process group at `timeoutMs` and caps captured stdout at `maxStdoutBytes`, flagging
+ * `truncated: true`; neither limit applies on the `sandbox` path, where the backend's own `timeoutMs`
+ * is the only bound and `truncated` always comes back false.
+ *
+ * With `sandbox` set the local `.git` probe is skipped deliberately — the repository lives in the
+ * backend, and a missing one surfaces as git's own "not a git repository".
+ */
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
 /**
@@ -229,8 +288,12 @@ interface CreateGitStatusToolOptions {
      * `SandboxBackend.execute`; omitted ⇒ the local `git` (unchanged).
      *
      * Symmetry with `createGitDiffTool`, flagged by the M76 review: without it `git_diff` would run
-     * confined and `git_status` not, in the same session — and the asymmetry would be invisible until someone
-     * notice that one of the two escapes the sandbox.
+     * confined and `git_status` not, in the same session — and the asymmetry would be invisible until
+     * someone noticed that one of the two escapes the sandbox.
+     *
+     * When set, the repository question is answered by the BACKEND (from git's own stderr), not by a
+     * probe of the host's filesystem. #346 — the host probe used to run first, so a session whose
+     * checkout lives inside the backend got `not_a_repo` for a repository that was there.
      */
     sandbox?: SandboxProvider;
     /**
@@ -250,6 +313,23 @@ interface CreateGitStatusToolOptions {
      */
     includeBranch?: boolean;
 }
+/**
+ * Build the `git_status` tool. Returns `git status --porcelain=v1` output, which is the reason to use
+ * this rather than a `shell_exec` of plain `git status`: the human format is not stable across git
+ * versions and the porcelain one is.
+ *
+ * The output arrives in a field named `diff`, shared with {@link createGitDiffTool} rather than named
+ * after what it holds.
+ *
+ * A missing `.git` is `{ ok: false, error: "not_a_repo" }` rather than an empty string, so the model
+ * cannot read "not a repository" as "nothing changed". The other refusals are `path_traversal`,
+ * `timeout` and `git_failed`.
+ *
+ * With `sandbox` the command itself runs through the injected backend — but the local `.git` probe
+ * runs BEFORE that branch, so a sandboxed status still requires `<projectRoot>/.git` to exist on the
+ * host. {@link createGitDiffTool} skips its equivalent probe when sandboxed. Configure both tools the
+ * same way in one session: one confined and one not is an asymmetry nothing surfaces.
+ */
 declare function createGitStatusTool(opts: CreateGitStatusToolOptions): CustomTool;
 
 /**
@@ -275,6 +355,22 @@ interface CreateGlobToolOptions {
      *  backend (Local/remote), so the tool is surface-agnostic; omitted ⇒ the local `readdir` (unchanged). */
     filesystem?: FilesystemProvider;
 }
+/**
+ * Build the `glob_files` tool: find files by the shape of their name. Use it when you know what the
+ * file is called, `search_text` when you know what is inside it, `read_file` when you know the path.
+ *
+ * The pattern is matched against paths relative to `cwd`, while the paths returned are relative to
+ * `projectRoot` — `{ pattern: "*.ts", cwd: "src" }` matches `index.ts` and returns `src/index.ts`.
+ * Only `*`, `**` and `?` are wildcards; braces and character classes are escaped to literals, so
+ * `*.{ts,js}` matches a file actually named that. Matching is anchored at both ends, which is why a
+ * bare `*.ts` sees only the top level of the search root and a leading `**` is usually what is meant.
+ *
+ * `node_modules`, `.git`, `dist` and `.theo` are skipped by name at any depth and cannot be
+ * re-enabled. Nothing else is filtered: this returns names, so a `.env` file is listed even though
+ * `read_file` would refuse to open it. An unreadable directory is skipped without a word rather than
+ * failing the call, so a permission problem looks like an empty directory. The only refusal is
+ * `path_traversal` on `cwd`; a pattern matching nothing is `{ ok: true, files: [] }`.
+ */
 declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
 
 /**
@@ -356,6 +452,15 @@ declare function isCommandAllowed(command: string, policies: CommandPolicy[]): b
  * its own `{ ok: false, error }` shape.
  */
 type ContextMatchReason = "empty" | "ambiguous" | "not_found";
+/**
+ * Thrown by {@link replaceUnique} when the replacement cannot be made safely. `reason` names the
+ * case: `empty` (no target given), `ambiguous` (the target matched in more than one place, so nothing
+ * was replaced), `not_found` (no rung of the ladder matched).
+ *
+ * `ambiguous` is the one worth handling apart from the others. It says the caller's target text is
+ * too short, not that the file lacks it, so the remedy is more surrounding context rather than a
+ * different search.
+ */
 declare class ContextMatchError extends Error {
     readonly reason: ContextMatchReason;
     constructor(reason: ContextMatchReason, message: string);
@@ -457,6 +562,11 @@ interface RepoMapOptions {
     /** Max directory depth to descend. Default 4. */
     maxDepth?: number;
 }
+/**
+ * Options for {@link buildEnvContext}. Both fields exist to make the block deterministic under test:
+ * `now` fixes the date line, `gitHeadPath` points the branch lookup at a fixture instead of
+ * `<cwd>/.git/HEAD`. Neither changes what the block contains.
+ */
 interface EnvContextOptions {
     /** Injectable clock for the date line (deterministic tests). Default `new Date()`. */
     now?: Date;
@@ -647,6 +757,22 @@ interface CreateListDirToolOptions {
      */
     filesystem?: FilesystemProvider;
 }
+/**
+ * Build the `list_dir` tool: the direct entries of one directory as `{ name, type }`. Never
+ * recursive — use `glob_files` to search a tree.
+ *
+ * The result always carries `truncated` and `totalCount`, so an agent that hits the `max` cap
+ * (default 500) can tell a large directory from a complete listing and switch to `glob_files` or
+ * `search_text`. There is no offset input, so paging past the cap is not possible; `totalCount`
+ * counts everything the directory holds, including what was cut.
+ *
+ * `path` is project-relative and `"."` means the root. Refusals are `forbidden_path`,
+ * `path_traversal` and `not_found`, the last of which also covers a path that exists but is a file.
+ *
+ * On a `filesystem` backend each entry costs a `stat` to learn its type, and an entry whose `stat`
+ * fails is reported as a file rather than dropped — so `type` is best-effort there and exact on the
+ * local path.
+ */
 declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
 
 /**
@@ -663,6 +789,13 @@ declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
  */
 
 type Mode = "normal" | "plan";
+/**
+ * The `plan_mode` tool object returned by the no-argument {@link createPlanModeTool}. Its `handler`
+ * is synchronous, where {@link PlanModeToolWithStore}'s returns a promise — so the two are not
+ * interchangeable at a call site that does not await.
+ *
+ * `currentMode` is a test seam; the mode also comes back in every result.
+ */
 interface PlanModeTool {
     name: string;
     description: string;
@@ -706,6 +839,20 @@ interface PlanModeToolOptions {
     /** Artifact id under which the plan is stored. Default `"plan"`. */
     artifactId?: string;
 }
+/**
+ * Build the `plan_mode` tool, which flips a flag and returns instruction text telling the model to
+ * outline before it edits. It enforces nothing — no other tool consults the mode, so a model that
+ * ignores the instructions is not stopped, and the mode lives in this object rather than in the
+ * session.
+ *
+ * With no argument it returns a {@link PlanModeTool} whose handler is synchronous. With options it
+ * returns a {@link PlanModeToolWithStore} whose handler is async and accepts a `plan` string,
+ * persisted to `artifactStore` under `artifactId` (default `"plan"`) when the model exits plan mode.
+ * An empty or absent `plan` is not written, and `persisted` in the result says which happened.
+ *
+ * `name` and `description` are read on the options overload only. The no-argument form always
+ * publishes `plan_mode` with the built-in description, since it takes nothing to override it with.
+ */
 declare function createPlanModeTool(): PlanModeTool;
 declare function createPlanModeTool(options: PlanModeToolOptions): PlanModeToolWithStore;
 
@@ -714,7 +861,9 @@ declare function createPlanModeTool(options: PlanModeToolOptions): PlanModeToolW
  *
  * Return shape (always a JSON string):
  *   - `{ ok: true, answer: string }`
- *   - `{ ok: false, error: "timeout" }`
+ *   - `{ ok: false, error: "timeout" }` — nobody answered within `timeoutMs`
+ *   - `{ ok: false, error: "no_asker" }` — neither `ctx.context.askUser` nor the factory's `askUser`
+ *     was available, so there was nobody to ask
  */
 interface QuestionToolOptions {
     /**
@@ -770,6 +919,23 @@ interface QuestionTool {
         threadId?: string;
     }) => Promise<string>;
 }
+/**
+ * Build the `question` tool: the agent stops, asks the user something, and the turn waits for the
+ * answer.
+ *
+ * The asker is resolved per call — run context first (`ctx.context.askUser`), then the factory's
+ * `askUser` — so one tool object shared across sessions can still reach the right user. With neither,
+ * the call returns `{ ok: false, error: "no_asker" }` at once rather than hanging until the timeout;
+ * that error means the host is mis-wired, not that the user declined.
+ *
+ * After `timeoutMs` (default 5 minutes) the result is `{ ok: false, error: "timeout" }` and
+ * `onAbandon` fires. Supply `onAbandon` whenever your asker holds a slot per thread: the promise the
+ * tool stopped awaiting is still pending on your side, so without the callback the UI keeps rendering
+ * a prompt nobody is waiting on and rejects every later question as already pending.
+ *
+ * Anything else the asker rejects with propagates out of the handler — only its own timeout is
+ * converted.
+ */
 declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
 
 /**
@@ -851,6 +1017,26 @@ interface CreateReadFileToolOptions {
      */
     allowAbsolute?: boolean;
 }
+/**
+ * Build the `read_file` tool.
+ *
+ * Success is `{ ok: true, content, size }`. Every refusal is a `{ ok: false, error }` value rather
+ * than a throw, so the model can correct itself: `not_found`, `forbidden_path` (the sensitive-file
+ * blocklist), `path_traversal` (escapes `projectRoot`, or the backend refused it), `binary_file` (a
+ * null byte in the first 8 KB) and `too_large` (over 5 MB — a fixed ceiling, not an option).
+ *
+ * `offset`/`limit` page by line and `lineNumbers` renders a `cat -n` view (`<n>\t<line>`). Both are
+ * applied after the whole file has been read, so they bound what the model sees, not what is read
+ * from disk; the 5 MB cap is what bounds the read.
+ *
+ * `allowAbsolute` widens the boundary to the entire filesystem for absolute paths, leaving only the
+ * any-depth secret guard in front of it. It is for a trusted local agent; on a shared or
+ * multi-tenant host pass `filesystem` instead and let the backend own the boundary.
+ *
+ * Pass one {@link ReadTracker} here and the same instance to {@link createWriteFileTool} to enable
+ * read-before-write: this tool records the mtime it saw, and the write tool then refuses to
+ * overwrite a file that was never read or has changed since.
+ */
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
 /**
@@ -895,10 +1081,12 @@ declare class ReasoningTools {
  *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' | 'timeout' |
  *        'no_vitest' | 'unparseable_output' }`
  *
- * Implementation note: invokes vitest via `npx --no-install vitest`. The
- * `--no-install` avoids the agent triggering a multi-megabyte download
- * mid-turn if vitest is missing — the tool fails cleanly with
- * `no_vitest` instead.
+ * Implementation note: invokes vitest via `npx --no-install vitest`. The `--no-install` avoids the
+ * agent triggering a multi-megabyte download mid-turn when vitest is missing. That case surfaces as
+ * `no_vitest` (#347), recognised from npm's own complaint on stderr — `npx` itself starts, so the
+ * spawn succeeds and only the text distinguishes a missing package from a run that produced no
+ * parseable JSON. A spawn failure (`npx` not on PATH) is `no_vitest` too. If npm ever rewords its
+ * message the case falls back to `unparseable_output`, with the real reason in the payload.
  */
 
 interface CreateRunVitestToolOptions {
@@ -911,12 +1099,30 @@ interface CreateRunVitestToolOptions {
     timeoutMs?: number;
     maxStdoutBytes?: number;
 }
+/**
+ * The fields lifted from vitest's JSON report. All optional, because the object is the report's own
+ * top level passed through unvalidated — a vitest version that renames a field yields `undefined`
+ * here rather than an error, so treat a missing `success` as unknown, never as failed.
+ */
 interface VitestSummary {
     numTotalTests?: number;
     numPassedTests?: number;
     numFailedTests?: number;
     success?: boolean;
 }
+/**
+ * Build the `run_vitest` tool: run the project's suite and return the counts rather than the log.
+ *
+ * A FAILING suite is `{ ok: true, summary }` with `success: false`. `ok` reports only that vitest
+ * ran; an agent that branches on `ok` reads a red suite as a green one. And the summary carries
+ * counts alone — which test failed, and why, is not in the result, so chasing a failure means falling
+ * back to `shell_exec`.
+ *
+ * Runs `npx --no-install vitest run --reporter=json`, so a project without vitest installed fails
+ * instead of downloading it mid-turn. That failure arrives as `no_vitest` (#347), as does `npx` not
+ * being on PATH. The remaining refusals are `path_traversal`, `forbidden_path` and `timeout`
+ * (default 120s, process group killed).
+ */
 declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTool;
 
 /**
@@ -970,6 +1176,29 @@ interface CreateSearchTextToolOptions {
      *  sandbox). Forbidden dirs are still skipped. Default `false` ⇒ absolute scope rejected (unchanged). */
     allowAbsolute?: boolean;
 }
+/**
+ * Build the `search_text` tool: scan file CONTENTS across the tree. Use it when you know what the
+ * code says, and `glob_files` when you know what the file is called.
+ *
+ * `regex` is fixed at construction, not chosen per call — it changes both the input schema and the
+ * description the model sees, so one instance is either literal-substring or regex, never both.
+ * Literal matching is case-sensitive and there is no case-insensitive mode. In regex mode the pattern
+ * is compiled with no flags (an inline `(?i)` is a syntax error, not a modifier) and an invalid
+ * pattern returns `{ ok: false, error: "invalid_regex" }` before any file is opened.
+ *
+ * Matches carry `{ file, line, preview }` with `line` 1-based and `preview` cut at 200 characters.
+ * The walk stops at the first match past `maxMatches` (default 100), so on a truncated run
+ * `totalMatches` is `maxMatches + 1` — it counts what was scanned, not how many matches exist. Files
+ * over `maxFileSize` (default 1 MB), files with a null byte in their first 8 KB, and anything
+ * unreadable are skipped in silence.
+ *
+ * `allowAbsolute` honours an absolute `path` scope. Be aware that the sensitive-path filter applied
+ * during the walk inspects only the first segment of each entry's path relative to `projectRoot`,
+ * plus its basename. Under an absolute scope every entry's relative path begins with `..`, so a
+ * nested `.env` is neither skipped nor refused and its matching lines are returned.
+ * {@link createReadFileTool} and {@link createListDirTool} carry an any-depth guard for exactly this
+ * case; this tool does not.
+ */
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 
 /**
@@ -1015,6 +1244,28 @@ interface CreateShellToolOptions {
      */
     sandbox?: SandboxProvider;
 }
+/**
+ * Build the `shell_exec` tool: run a command through `/bin/sh -c` with `projectRoot` as the working
+ * directory.
+ *
+ * Reserve it for what has no dedicated tool — tests, git, package managers, build steps. Reading,
+ * writing, editing and searching files each have a path-checked tool in this package, and routing
+ * them through a shell gives up every one of those checks.
+ *
+ * The model's `timeout_ms` and `defaultTimeoutMs` (30s) are both clamped to a 5-minute ceiling that
+ * is not configurable. On expiry the process group is killed and the result is
+ * `{ ok: false, error: "timeout" }`. stdout and stderr are capped at 5 MB each and cut silently at
+ * the cap — there is no truncation flag, so a command producing more looks like one that produced
+ * exactly 5 MB.
+ *
+ * A non-zero exit is `{ ok: true, ..., exit_code }`, not an error: `ok` reports that the command ran,
+ * `exit_code` reports whether it worked.
+ *
+ * The catastrophic-command screen runs before either execution path and refuses on a heuristic match
+ * over the command string. It is a guardrail, not a sandbox, and `allowCatastrophic: true` removes it
+ * outright. For real confinement pass `sandbox`, which routes execution through the backend — the
+ * 5 MB output caps belong to the local path and do not apply there.
+ */
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 
 /**
@@ -1042,6 +1293,13 @@ interface TodoItem {
     createdAt: number;
     completedAt?: number;
 }
+/**
+ * The `todolist` tool object. It is hand-built rather than produced by `Tool.create`, so
+ * `inputSchema` is a plain JSON Schema value and `handler` is synchronous.
+ *
+ * `getItems` is a test seam onto the same session state the handler mutates, reachable without going
+ * through an action.
+ */
 interface TodolistTool {
     name: string;
     description: string;
@@ -1073,6 +1331,19 @@ type TodoInput = {
 } | {
     action: "clear_completed";
 };
+/**
+ * Build the `todolist` tool: an in-memory checklist the agent keeps across the turns of one session.
+ *
+ * State lives in the closure. It is never written anywhere and dies with the process, so this is a
+ * working memo for the model, not a task store. One tool object can serve many sessions — lists are
+ * keyed by `ctx.threadId`, and every call arriving without one shares a single default list, which
+ * means a multi-session host that forgets to thread the id merges all its users' tasks together.
+ *
+ * Ids are `todo-1`, `todo-2`, … per session and are never reused, so a removed item's id stays gone.
+ * Each successful action returns the whole list twice: `items` structured for a UI, `items_summary`
+ * formatted for the model. Failures are `missing_title`, `missing_id`, `not_found` and
+ * `invalid_action`.
+ */
 declare function createTodolistTool(): TodolistTool;
 
 /**
@@ -1129,6 +1400,10 @@ declare function todoItemsToPlanNodes(items: readonly TodoItem[]): PlanNode[];
  */
 /** How the middle is dropped when output exceeds the budget. */
 type TruncationMode = "head" | "head-tail";
+/**
+ * Options for {@link truncateOutput}. Every field has a default, so `truncateOutput(text)` is a
+ * complete call.
+ */
 interface TruncationOptions {
     /** Maximum output size in bytes before truncation. Default: 30_000. */
     maxBytes?: number;
@@ -1141,6 +1416,13 @@ interface TruncationOptions {
      */
     mode?: TruncationMode;
 }
+/**
+ * What {@link truncateOutput} returns.
+ *
+ * `truncated` is the field to branch on. On the false branch `content` is the input unchanged and
+ * `overflowPath` is absent; reading `overflowPath` without checking `truncated` first is how a
+ * consumer ends up joining `undefined` into a path.
+ */
 interface TruncationResult {
     /** The (possibly truncated) content. */
     content: string;
@@ -1155,6 +1437,29 @@ interface TruncationResult {
     /** Path to the full output file, present only when truncated. */
     overflowPath?: string;
 }
+/**
+ * Bound a block of tool output to `maxBytes`, spilling the full text to a file when it does not fit.
+ *
+ * Nothing is written and nothing is copied when the output already fits — the comparison is
+ * `originalBytes <= maxBytes`, so a payload exactly at the limit passes through untouched. Above the
+ * limit the WHOLE original is written under `outputDir` (created recursively) and the returned
+ * `content` is the cut text plus a trailer naming that file. The trailer is appended after the cut,
+ * so the returned string is longer than `maxBytes`: the budget bounds what is copied out of the
+ * input, not what comes back.
+ *
+ * Choose the mode by where the information sits. `"head"` keeps the opening, which suits a document
+ * or a listing. `"head-tail"` splits the budget between the start and the end, which is what command
+ * output needs — the exit status, the failing assertion and the summary all live in the last lines,
+ * and `"head"` discards exactly those.
+ *
+ * The head is cut on a UTF-8 code-point boundary and never ends in a replacement character. The tail
+ * of `"head-tail"` starts mid-buffer, so it can open with one U+FFFD where a multi-byte character was
+ * split; the omitted-byte count in the separator is computed from `maxBytes` and is approximate for
+ * the same reason.
+ *
+ * Touches the filesystem on the truncating path — a `mkdirSync`/`writeFileSync` failure propagates
+ * rather than degrading to an untruncated return.
+ */
 declare function truncateOutput(output: string, opts?: TruncationOptions): TruncationResult;
 
 /**
@@ -1213,6 +1518,11 @@ declare function createUpdatePlanTool(): CustomTool;
  * not a slow request — it is a failed turn, and an expensive one.
  */
 declare const DEFAULT_MAX_IMAGE_BYTES: number;
+/**
+ * Options for {@link createViewImageTool}. `maxBytes` is measured on disk, before base64 inflates the
+ * payload by roughly a third on its way into the model's context — so the real context cost of a file
+ * at the limit is about 6.7 MB of text, not 5 MB.
+ */
 interface CreateViewImageToolOptions {
     /** Root the tool reads from. Every path is resolved inside it. */
     projectRoot: string;
@@ -1264,6 +1574,26 @@ interface CreateWebFetchToolOptions {
     /** DNS resolver (injectable for tests — drive the SSRF path with no real DNS). */
     lookup?: ScreenedFetchOptions["lookup"];
 }
+/**
+ * Build the `web_fetch` tool: retrieve one URL over HTTP or HTTPS and hand the model the body as
+ * text. Every option is optional — `createWebFetchTool()` gives an SSRF-guarded fetch with a
+ * 30-second timeout.
+ *
+ * The body is decoded as UTF-8 whatever the content type says, so a PDF or an image comes back as
+ * mojibake rather than an error: check `content_type` before trusting `content`. The 1 MB body cap is
+ * fixed rather than an option, and is enforced twice — against `content-length` when the server sends
+ * one, then against the bytes actually downloaded.
+ *
+ * The SSRF guard screens the resolved ADDRESS rather than the hostname, and screens every redirect
+ * hop again. `maxRedirects: 0` refuses any 3xx outright with `redirect_blocked`, which is the strict
+ * setting for a URL the model chose itself. `allowPrivateHosts: true` disables the guard entirely,
+ * and with a model-supplied URL that is enough to reach a cloud metadata endpoint — it is for local
+ * development against your own services, not for production.
+ *
+ * Refusals: `invalid_url` (unparseable, or a scheme other than http/https), `ssrf_blocked`,
+ * `redirect_blocked`, `too_large`, `timeout`, `fetch_failed`. A 4xx or 5xx is NOT a refusal — it
+ * returns `ok: true` with the body and `status_code`, so check the status.
+ */
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
 /**
@@ -1282,7 +1612,22 @@ interface WebSearchResult {
     url: string;
     snippet: string;
 }
+/**
+ * The search provider {@link createWebSearchTool} calls.
+ *
+ * `maxResults` is what the caller asked for, not a limit you must enforce — the tool slices the array
+ * itself — but returning far more than asked wastes the round trip that produced them.
+ *
+ * Reject the promise to signal a failed search: the tool turns a rejection into
+ * `{ ok: false, error: "search_failed" }` and never lets it escape into the agent turn. Resolving
+ * with `[]` says something different — that the search ran and found nothing.
+ */
 type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
+/**
+ * Options for {@link createWebSearchTool}. `search` is required: the tool ships no provider of its
+ * own, and the two adapters in this package — {@link createBraveWebSearchAdapter} and
+ * {@link createGenericHttpSearchAdapter} — exist to fill it.
+ */
 interface CreateWebSearchToolOptions {
     /** M76 — name exposed to the model. Omitted => today's literal (additive). The name is a contract:
      *  the approval key, what the model sees and what telemetry records. */
@@ -1294,6 +1639,19 @@ interface CreateWebSearchToolOptions {
     /** Default max results if not specified by the LLM. */
     defaultMaxResults?: number;
 }
+/**
+ * Build the `web_search` tool over a caller-supplied provider.
+ *
+ * The tool holds no API key and talks to no service; everything network-facing lives in the `search`
+ * callback, which is why one tool serves Brave, a self-hosted endpoint, or a fixture in a test. Use
+ * it to find pages and `web_fetch` to read one — results carry a snippet, not a body.
+ *
+ * The model's `max_results` (1..20) wins over `defaultMaxResults`, and the list is sliced to it even
+ * when the provider returns more. A rejecting provider yields `{ ok: false, error: "search_failed" }`
+ * with its message attached; a provider resolving `[]` yields `{ ok: true, results: [] }`. The two
+ * are different signals, so an adapter that swallows its own failures — as
+ * {@link createGenericHttpSearchAdapter} deliberately does — reports the first as the second.
+ */
 declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
 
 /**
@@ -1309,6 +1667,11 @@ declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTo
  */
 
 type FetchLike$1 = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Options for {@link createBraveWebSearchAdapter}. `apiKey` falls back to `BRAVE_API_KEY` and
+ * `endpoint` to Brave's public search URL, both read once at construction, so a process that exports
+ * the env var can call the factory with no arguments.
+ */
 interface CreateBraveWebSearchAdapterOptions {
     /** Brave API key. Defaults to `process.env.BRAVE_API_KEY`. */
     apiKey?: string;
@@ -1345,6 +1708,12 @@ declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterO
  */
 
 type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Options for {@link createGenericHttpSearchAdapter}. Unlike the Brave adapter, an absent `apiKey` or
+ * `endpoint` is not an error — the callback is still built and simply returns no results — so if you
+ * need to know whether search is actually configured, check both here rather than waiting for an
+ * empty result set to tell you.
+ */
 interface CreateGenericHttpSearchAdapterOptions {
     /** Bearer token. Defaults to `process.env.THEOKIT_SEARCH_API_KEY`. */
     apiKey?: string;
@@ -1377,6 +1746,10 @@ type WriteToolContext = {
     signal?: AbortSignal;
     context?: unknown;
 };
+/**
+ * Options for {@link createWriteFileTool}. `requireReadBeforeWrite` and `readTracker` are a pair —
+ * the flag without the tracker is refused at construction rather than quietly disabling the guard.
+ */
 interface CreateWriteFileToolOptions {
     /** M76 — name exposed to the model. Omitted => today's literal (additive). The name is a contract:
      *  the approval key, what the model sees and what telemetry records. */
@@ -1403,6 +1776,22 @@ interface CreateWriteFileToolOptions {
     /** SE32 — the per-run tracker populated by the paired `read_file` tool. */
     readTracker?: ReadTracker;
 }
+/**
+ * Build the `write_file` tool. It OVERWRITES: reach for {@link createEditFileTool} when the file
+ * exists and only part of it changes.
+ *
+ * Parent directories are created recursively. Refusals arrive as `{ ok: false, error }`:
+ * `forbidden_path`, `path_traversal`, `binary_file`, plus `read_required` / `stale_file` when
+ * read-before-write is on, plus `read_only` / `write_failed` on the backend path.
+ *
+ * The `binary_file` probe (a null byte in the first 8 KB of the file being replaced) runs on the
+ * local path only. A `filesystem` backend has no equivalent, so overwriting a binary file through a
+ * backend is not refused.
+ *
+ * Throws at construction — not at call time — when `requireReadBeforeWrite` is set without a
+ * `readTracker`. A guard that silently does nothing is worse than no guard, and construction is the
+ * only place the pairing can be checked.
+ */
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
 export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };