@theokit/sdk 1.5.0

package/dist/tools/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in tools for `@theokit/sdk` agents (`@theokit/sdk/tools`).
+ *
+ * Each factory returns a `CustomTool` ready to drop into `Agent.create`
+ * or `createAgentFactory({ tools: [...] })`. All five share three
+ * design rules:
+ *
+ *   1. **Project-scoped**. Every factory takes `{ projectRoot }` and
+ *      gates every I/O call against that boundary via the SDK's
+ *      `safePathJoin` + `assertNoSymlinkEscape` primitives.
+ *
+ *   2. **Sensitive files refused**. `.env*` (except `.env.example`),
+ *      `.git/`, `node_modules/`, `.theo/`, and lock files are blocked
+ *      via `isForbiddenPath`.
+ *
+ *   3. **JSON returns, never throws on user mistakes**. Handlers return
+ *      `{ ok: true, ... }` or `{ ok: false, error: '...' }`. Real
+ *      exceptions are reserved for SDK-side bugs (input parse errors,
+ *      unexpected fs failures).
+ *
+ * Consumers: TheoKit Studio (the embedded coding agent), `cli-bot`
+ * (the SDK's reference example), and any future coding-agent built on
+ * `@theokit/sdk`.
+ */
+export { type CreateGitDiffToolOptions, createGitDiffTool } from "./git-diff.js";
+export { type CreateListDirToolOptions, createListDirTool } from "./list-dir.js";
+export { type CreateReadFileToolOptions, createReadFileTool } from "./read-file.js";
+export { type CreateRunVitestToolOptions, createRunVitestTool, type VitestSummary, } from "./run-vitest.js";
+export { type CreateSearchTextToolOptions, createSearchTextTool } from "./search-text.js";

package/dist/tools/list-dir.d.cts

@@ -0,0 +1,26 @@
+/**
+ * `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' }`
+ */
+import type { CustomTool } from "../types/agent.js";
+export 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;
+}
+export declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;

package/dist/tools/list-dir.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `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' }`
+ */
+import type { CustomTool } from "../types/agent.js";
+export 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;
+}
+export declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;

package/dist/tools/read-file.d.cts

@@ -0,0 +1,31 @@
+/**
+ * `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).
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateReadFileToolOptions {
+    /** Absolute path to the project root. Every read is gated against this boundary. */
+    projectRoot: string;
+}
+export declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;

package/dist/tools/read-file.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `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).
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateReadFileToolOptions {
+    /** Absolute path to the project root. Every read is gated against this boundary. */
+    projectRoot: string;
+}
+export declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;

package/dist/tools/run-vitest.d.cts

@@ -0,0 +1,46 @@
+/**
+ * `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.
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateRunVitestToolOptions {
+    projectRoot: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+export interface VitestSummary {
+    numTotalTests?: number;
+    numPassedTests?: number;
+    numFailedTests?: number;
+    success?: boolean;
+}
+export declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTool;
+/**
+ * Find the LAST line in `stdout` that parses as a JSON object. Vitest
+ * prepends node deprecation warnings to its JSON reporter output — if
+ * we naively `JSON.parse(stdout)` we get a SyntaxError. Workaround: walk
+ * lines bottom-up and return the first one that parses.
+ *
+ * Exported for direct unit testing without spawning vitest.
+ */
+export declare function extractTrailingJson(stdout: string): unknown;

package/dist/tools/run-vitest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `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.
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateRunVitestToolOptions {
+    projectRoot: string;
+    timeoutMs?: number;
+    maxStdoutBytes?: number;
+}
+export interface VitestSummary {
+    numTotalTests?: number;
+    numPassedTests?: number;
+    numFailedTests?: number;
+    success?: boolean;
+}
+export declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTool;
+/**
+ * Find the LAST line in `stdout` that parses as a JSON object. Vitest
+ * prepends node deprecation warnings to its JSON reporter output — if
+ * we naively `JSON.parse(stdout)` we get a SyntaxError. Workaround: walk
+ * lines bottom-up and return the first one that parses.
+ *
+ * Exported for direct unit testing without spawning vitest.
+ */
+export declare function extractTrailingJson(stdout: string): unknown;

package/dist/tools/search-text.d.cts

@@ -0,0 +1,32 @@
+/**
+ * `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.
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateSearchTextToolOptions {
+    projectRoot: string;
+    /** Cap on total matches returned. Default 100. */
+    maxMatches?: number;
+    /** Skip files larger than this (bytes). Default 1 MB. */
+    maxFileSize?: number;
+}
+export declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;

package/dist/tools/search-text.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `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.
+ */
+import type { CustomTool } from "../types/agent.js";
+export interface CreateSearchTextToolOptions {
+    projectRoot: string;
+    /** Cap on total matches returned. Default 100. */
+    maxMatches?: number;
+    /** Skip files larger than this (bytes). Default 1 MB. */
+    maxFileSize?: number;
+}
+export declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;