@theokit/sdk-tools 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,430 @@
+import { CustomTool } from '@theokit/sdk';
+
+/**
+ * `apply_patch` — built-in tool for coding agents.
+ *
+ * Parses a unified diff string and applies it to the project files.
+ * Creates `.bak` backups before modifying each file.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, files_patched: string[] }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' |
+ *        'forbidden_path' | 'patch_failed' }`
+ */
+
+interface CreateApplyPatchToolOptions {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+}
+declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;
+
+/**
+ * `edit_file` — built-in tool for coding agents.
+ *
+ * Replaces a string in a project-relative file. Tries exact match first,
+ * then whitespace-normalized match. Creates a `.bak` backup before editing.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, replacements: 1 }` on success
+ *   - `{ ok: false, error: 'no_match' | 'not_found' | 'path_traversal' |
+ *        'forbidden_path' }` on refusal
+ */
+
+interface CreateEditFileToolOptions {
+    /** Absolute path to the project root. Every edit is gated against this boundary. */
+    projectRoot: string;
+}
+declare function createEditFileTool(opts: CreateEditFileToolOptions): CustomTool;
+
+/**
+ * `formatter` — output formatting utilities for tool results.
+ *
+ * Wraps code, diffs, file lists, errors, and truncated output references.
+ */
+/**
+ * Wrap code in a fenced code block with language tag.
+ */
+declare function formatCode(language: string, code: string): string;
+/**
+ * Format a unified diff with +/- prefixes preserved.
+ */
+declare function formatDiff(diff: string): string;
+/**
+ * Format a list of file paths as a bulleted markdown list.
+ */
+declare function formatFileList(files: string[]): string;
+/**
+ * Format an error message as a markdown block.
+ */
+declare function formatError(message: string, code?: string): string;
+
+/**
+ * `git_diff` — built-in tool for coding agents.
+ *
+ * Returns the unified diff of the working tree (or staged changes when
+ * `cached=true`). Implemented as a thin `git diff` subprocess wrapper
+ * with a couple of hard limits:
+ *
+ *   - 30s wall clock timeout (kills the process group on expiry)
+ *   - 5 MB stdout cap (truncate + flag `truncated=true`)
+ *   - Path scope validated through `safePathJoin` + `assertNoSymlinkEscape`
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, diff: string, truncated?: boolean }`
+ *   - `{ ok: false, error: 'not_a_repo' | 'path_traversal' | 'timeout' }`
+ */
+
+interface CreateGitDiffToolOptions {
+    projectRoot: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
+
+/**
+ * `glob_files` — built-in tool for coding agents.
+ *
+ * Lists project files matching a glob pattern. Excludes node_modules,
+ * .git, and dist by default. Returns relative paths.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, files: string[] }`
+ *   - `{ ok: false, error: 'path_traversal' | 'no_matches' }`
+ */
+
+interface CreateGlobToolOptions {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+}
+declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
+
+/**
+ * `list_dir` — built-in tool for coding agents.
+ *
+ * Returns the direct entries of a project-relative directory. Hardened
+ * against the same four bug families as `read_file` plus the
+ * **EC-6 unbounded output** failure mode: in a project with 10k files,
+ * a naive listing returns a 5 MB JSON payload that freezes the browser
+ * and (more importantly) blows past the LLM context window.
+ *
+ * Defaults:
+ *   - `max = 500` entries (override via factory option `{ max }`)
+ *   - Result includes `{ truncated: boolean, totalCount: number }` so the
+ *     agent can decide whether to drill deeper or call `search_text` instead
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, entries: Array<{ name, type }>, truncated, totalCount }`
+ *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' | 'not_found' }`
+ */
+
+interface CreateListDirToolOptions {
+    /** Absolute path to the project root. Every listing is gated against this boundary. */
+    projectRoot: string;
+    /** Maximum number of entries returned per call. Default 500. */
+    max?: number;
+}
+declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
+
+/**
+ * `plan_mode` — tool for toggling between normal and planning mode.
+ *
+ * In plan mode, the agent focuses on outlining steps rather than executing them.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, mode: string, message: string }`
+ *   - `{ ok: false, error: "invalid_action" }`
+ */
+type Mode = "normal" | "plan";
+interface PlanModeTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: {
+        action: string;
+    }) => string;
+    /** Expose current mode for testing. */
+    currentMode: () => Mode;
+}
+declare function createPlanModeTool(): PlanModeTool;
+
+/**
+ * `question` — interactive tool that asks the user a question and waits for a response.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, answer: string }`
+ *   - `{ ok: false, error: "timeout" }`
+ */
+interface QuestionToolOptions {
+    /** Callback that presents a question to the user and resolves with their answer. */
+    askUser: (question: string) => Promise<string>;
+    /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+}
+interface QuestionTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: {
+        question: string;
+    }) => Promise<string>;
+}
+declare function createQuestionTool(opts: QuestionToolOptions): QuestionTool;
+
+/**
+ * `read_file` — built-in tool for coding agents.
+ *
+ * Reads a project-relative file as UTF-8 and returns its contents.
+ * Hardened against the four bug families a coding agent normally hits:
+ *
+ *   1. **Path traversal** — `safePathJoin` rejects literal `..`,
+ *      normalised escape, absolute segments, null-byte injection.
+ *   2. **Symlink escape** — `assertNoSymlinkEscape` follows the full
+ *      chain (and any intermediate symlinks; defence-in-depth fix v1.x).
+ *   3. **Sensitive files** — `isForbiddenPath` blocks `.env*` (except
+ *      `.env.example`), `.git/`, `node_modules/`, `.theo/`, lock files.
+ *   4. **Binary files** — null-byte check on the first 8 KB. PNG/JPEG/
+ *      compiled binaries return a structured `binary_file` error
+ *      instead of garbled UTF-8 (EC-5 from the TheoKit Studio review).
+ *
+ * Return shape (always a JSON string the LLM consumes):
+ *   - `{ ok: true, content: string }` on success
+ *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' |
+ *        'binary_file' | 'not_found' | 'too_large' }` on refusal
+ *
+ * The handler intentionally never throws on a "user mistake"
+ * (traversal / forbidden / not found). Throwing reserved for SDK-side
+ * mistakes that should crash the agent loop (input parse errors).
+ */
+
+interface CreateReadFileToolOptions {
+    /** Absolute path to the project root. Every read is gated against this boundary. */
+    projectRoot: string;
+}
+declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
+
+/**
+ * `run_vitest` — built-in tool for coding agents.
+ *
+ * Runs vitest against an optional file/pattern scope and returns the
+ * parsed JSON report. Hardened against the same subprocess failure
+ * modes as `git_diff`:
+ *
+ *   - 120s wall clock timeout (vitest can be slow on first run)
+ *   - Process group kill on timeout (EC-7 — defeats vitest workers as
+ *     grandchildren of the spawned shell)
+ *   - **EC-12**: vitest stdout may contain deprecation warnings BEFORE
+ *     the JSON payload. The parser scans line-by-line and extracts the
+ *     LAST valid JSON object, not the first.
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, summary: { numTotalTests, numPassedTests, numFailedTests, success } }`
+ *   - `{ 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.
+ */
+
+interface CreateRunVitestToolOptions {
+    projectRoot: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+interface VitestSummary {
+    numTotalTests?: number;
+    numPassedTests?: number;
+    numFailedTests?: number;
+    success?: boolean;
+}
+declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTool;
+
+/**
+ * `search_text` — built-in tool for coding agents.
+ *
+ * Literal text search across the project tree (recursive). Sensible
+ * defaults:
+ *
+ *   - Skips forbidden directories (`.env`, `.git/`, `node_modules/`,
+ *     `.theo/`) so the agent never wastes context on dependency soup
+ *     or VCS internals.
+ *   - Skips files larger than `maxFileSize` (default 1 MB) and binary
+ *     files (null-byte detection on first 8 KB) so a megabyte of
+ *     minified JS never blows up the result.
+ *   - Caps total matches at `maxMatches` (default 100) — the agent
+ *     should refine the query if it gets close to the cap.
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, matches: Array<{ file, line, preview }>, truncated, totalMatches }`
+ *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' | 'not_found' }`
+ *
+ * Implementation note: this is a plain JS recursive walk. For very
+ * large repos a future iteration can shell out to `rg` (ripgrep) when
+ * present, but the JS path stays as the dependency-free fallback.
+ */
+
+interface CreateSearchTextToolOptions {
+    projectRoot: string;
+    /** Cap on total matches returned. Default 100. */
+    maxMatches?: number;
+    /** Skip files larger than this (bytes). Default 1 MB. */
+    maxFileSize?: number;
+}
+declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
+
+/**
+ * `shell_exec` — built-in tool for coding agents.
+ *
+ * Executes a shell command via `/bin/sh -c` with a configurable timeout
+ * and output size cap.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, stdout, stderr, exit_code }`
+ *   - `{ ok: false, error: 'timeout' | 'exec_failed' }`
+ */
+
+interface CreateShellToolOptions {
+    /** Absolute path to the project root. Commands execute in this cwd. */
+    projectRoot: string;
+    /** Default timeout in ms. Capped at 300s. */
+    defaultTimeoutMs?: number;
+}
+declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
+
+/**
+ * `todolist` — in-session task tracking for multi-step work.
+ *
+ * The agent uses this to plan complex tasks and track progress.
+ * Inspired by OpenCode's todo.ts and Claude Code's TodoWrite.
+ *
+ * Actions:
+ *   - add(title)         → add a new todo item
+ *   - complete(id)       → mark an item done
+ *   - remove(id)         → remove an item
+ *   - list()             → show all items with status
+ *   - clear_completed()  → remove all done items
+ */
+interface TodoItem {
+    id: string;
+    title: string;
+    status: "pending" | "in_progress" | "done";
+    createdAt: number;
+    completedAt?: number;
+}
+interface TodolistTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: TodoInput) => string;
+    /** Expose items for testing. */
+    getItems: () => TodoItem[];
+}
+type TodoInput = {
+    action: "add";
+    title: string;
+} | {
+    action: "complete";
+    id: string;
+} | {
+    action: "in_progress";
+    id: string;
+} | {
+    action: "remove";
+    id: string;
+} | {
+    action: "list";
+} | {
+    action: "clear_completed";
+};
+declare function createTodolistTool(): TodolistTool;
+
+/**
+ * `truncateOutput` — utility for truncating large tool output.
+ *
+ * When output exceeds `maxBytes`, writes the full content to a temp file
+ * and returns a truncated version with a reference to the full output.
+ *
+ * Return shape:
+ *   - `{ content: string, truncated: false }`
+ *   - `{ content: string, truncated: true, overflowPath: string }`
+ */
+interface TruncationOptions {
+    /** Maximum output size in bytes before truncation. Default: 30_000. */
+    maxBytes?: number;
+    /** Directory for overflow files. Default: ".theocode/tool-output". */
+    outputDir?: string;
+}
+interface TruncationResult {
+    /** The (possibly truncated) content. */
+    content: string;
+    /** Whether the output was truncated. */
+    truncated: boolean;
+    /** Path to the full output file, present only when truncated. */
+    overflowPath?: string;
+}
+declare function truncateOutput(output: string, opts?: TruncationOptions): TruncationResult;
+
+/**
+ * `web_fetch` — built-in tool for coding agents.
+ *
+ * Fetches a URL via native `fetch()`. Rejects non-http(s) protocols.
+ * Size-capped at 1 MB response body.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, content, status_code, content_type }`
+ *   - `{ ok: false, error: 'invalid_url' | 'fetch_failed' |
+ *        'timeout' | 'too_large' }`
+ */
+
+interface CreateWebFetchToolOptions {
+    /** Default timeout in ms. */
+    defaultTimeoutMs?: number;
+}
+declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
+
+/**
+ * `web_search` — built-in tool for coding agents.
+ *
+ * Accepts a search callback via DIP (consumer provides the search
+ * provider). The tool itself is provider-agnostic.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, results: Array<{ title, url, snippet }> }`
+ *   - `{ ok: false, error: 'search_failed' | 'no_provider' }`
+ */
+
+interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
+interface CreateWebSearchToolOptions {
+    /** Search provider callback — consumer injects the implementation. */
+    search: WebSearchCallback;
+    /** Default max results if not specified by the LLM. */
+    defaultMaxResults?: number;
+}
+declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
+
+/**
+ * `write_file` — built-in tool for coding agents.
+ *
+ * Writes UTF-8 content to a project-relative path. Creates parent
+ * directories recursively. Refuses binary-file overwrites, path
+ * traversal, and sensitive paths.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, path, bytes }` on success
+ *   - `{ ok: false, error: 'path_traversal' | 'forbidden_path' |
+ *        'binary_file' }` on refusal
+ */
+
+interface CreateWriteFileToolOptions {
+    /** Absolute path to the project root. Every write is gated against this boundary. */
+    projectRoot: string;
+}
+declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
+
+export { type CreateApplyPatchToolOptions, type CreateEditFileToolOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, type PlanModeTool, type QuestionTool, type QuestionToolOptions, type TodoItem, type TodolistTool, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, createApplyPatchTool, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, formatCode, formatDiff, formatError, formatFileList, truncateOutput };