@theokit/sdk-tools 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { CustomTool } from '@theokit/sdk';
+import { CustomTool, ConfigurationError } from '@theokit/sdk';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -18,6 +18,60 @@ interface CreateApplyPatchToolOptions {
 }
 declare function createApplyPatchTool(opts: CreateApplyPatchToolOptions): CustomTool;
 
+/**
+ * Options for {@link createSessionArtifactStore}.
+ *
+ * @public
+ */
+interface SessionArtifactStoreOptions {
+    /** Directory holding one file per artifact (`<dir>/<idStrategy(id)><extension>`). */
+    dir: string;
+    /**
+     * Map an opaque artifact id to a filesystem-safe filename stem.
+     * Default: `safeFilenameForId` (accepts ANY id; deterministically hashes
+     * non-conforming input). The result is additionally passed through
+     * `safePathJoin`, so a traversal id can never escape `dir`.
+     *
+     * NOTE — the default `safeFilenameForId` is CASE-FOLDING: ids differing only
+     * in case (`"Run-1"` vs `"run-1"`) map to the SAME file. If your ids are
+     * case-sensitive (e.g. base64), supply a case-preserving `idStrategy`.
+     */
+    idStrategy?: (id: string) => string;
+    /** File extension (with leading dot). Default `".md"`. */
+    extension?: string;
+}
+/**
+ * A generic, id-keyed, atomic artifact store. Generalizes the per-run
+ * session-summary writer pattern: persist an opaque text artifact under a
+ * stable id, read it back, and enumerate what's stored.
+ *
+ * @public
+ */
+interface SessionArtifactStore {
+    /**
+     * Write (overwrite) the artifact atomically; returns the resolved path.
+     * Content is persisted byte-for-byte. The id is mapped via `idStrategy`
+     * (default case-folding — see {@link SessionArtifactStoreOptions.idStrategy}).
+     */
+    write(id: string, content: string): Promise<string>;
+    /** Read the artifact, or `undefined` if absent/unreadable (never throws). */
+    read(id: string): Promise<string | undefined>;
+    /** Whether an artifact exists for `id` (never throws). */
+    has(id: string): Promise<boolean>;
+    /** The filename stems of all stored artifacts (never throws; `[]` if dir absent). */
+    list(): Promise<string[]>;
+    /** The resolved, traversal-safe path for `id`. */
+    path(id: string): string;
+}
+/**
+ * Create a generic artifact store rooted at `dir`. Composes the shipped
+ * `safeFilenameForId`/`safePathJoin` path guard + the atomic `replaceFileAtomic`
+ * writer — zero new dependencies. Reads never throw; writes fail loud.
+ *
+ * @public
+ */
+declare function createSessionArtifactStore(options: SessionArtifactStoreOptions): SessionArtifactStore;
+
 /**
  * `edit_file` — built-in tool for coding agents.
  *
@@ -88,8 +142,8 @@ declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
  * .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' }`
+ *   - `{ ok: true, files: string[], count }` (an empty match is `ok: true` with `files: []`)
+ *   - `{ ok: false, error: 'path_traversal' }`
  */
 
 interface CreateGlobToolOptions {
@@ -98,6 +152,216 @@ interface CreateGlobToolOptions {
 }
 declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
 
+/**
+ * Composable command-permission policy layer (M3-6).
+ *
+ * A `CommandPolicy` is a pure predicate returning a deny REASON (or `null` to
+ * allow). `denyCatastrophicCommands()` COMPOSES the M3-2 `catastrophicShellReason`
+ * guardrail (it does not duplicate the deny-list). `commandDenialReason` combines
+ * a policy array with deny-wins semantics (the first policy returning a reason
+ * denies); an empty array denies nothing. `isCommandAllowed` is the boolean view.
+ *
+ * Framework-agnostic: a consumer wires it at their permission layer — e.g. inside
+ * an ACP `pre_tool_call` hook — `@theokit/agents` is not required. Inherits the
+ * M3-2 honesty: a heuristic gate, not a sandbox. Design: blueprint m3-command-policy.
+ */
+/**
+ * A pure command-permission predicate: returns a non-empty deny reason, or `null`
+ * to allow. NOTE: return `null` to allow — NOT `""`. An empty string is treated
+ * as a deny with a blank reason (`"" !== null`), which is almost never intended.
+ */
+type CommandPolicy = (command: string) => string | null;
+/** A policy that denies catastrophic commands by composing the M3-2 guardrail. */
+declare function denyCatastrophicCommands(): CommandPolicy;
+/**
+ * The first deny reason across `policies` (deny-wins), or `null` if every policy
+ * allows. An empty `policies` array denies nothing (returns `null`).
+ */
+declare function commandDenialReason(command: string, policies: CommandPolicy[]): string | null;
+/** `true` when no policy denies `command` (an empty policy array allows everything). */
+declare function isCommandAllowed(command: string, policies: CommandPolicy[]): boolean;
+
+/**
+ * SSRF guard for network tools (M3-1).
+ *
+ * `isBlockedIp` is a pure block-list of the canonical private/loopback/link-local/
+ * CGNAT/metadata/reserved ranges (IPv4 + IPv6, with IPv4-mapped unwrap).
+ * `resolveAndScreen` resolves ALL of a host's addresses and rejects if any is
+ * blocked. `screenedFetch` fetches with `redirect:"manual"` and re-screens every
+ * hop. `lookup`/`fetchImpl` are injectable so the DNS + redirect paths are
+ * deterministically testable without real network access.
+ *
+ * Design: blueprint m3-ssrf-guard ADRs D1-D6. Node builtins only (zero new deps).
+ */
+
+/** Thrown when a host/redirect resolves to a blocked (private/reserved) address. */
+declare class SsrfBlockedError extends ConfigurationError {
+    readonly name = "SsrfBlockedError";
+    constructor(host: string, detail?: string);
+}
+/**
+ * True if `ip` is a blocked address (private/loopback/link-local/CGNAT/metadata/
+ * reserved). A non-IP literal returns `true` (fail closed — callers resolve names
+ * to IPs first via {@link resolveAndScreen}).
+ */
+declare function isBlockedIp(ip: string): boolean;
+type LookupFn = (host: string, opts: {
+    all: true;
+}) => Promise<Array<{
+    address: string;
+}>>;
+/** Options for {@link resolveAndScreen}. */
+interface ResolveAndScreenOptions {
+    /** DNS resolver (injectable for tests); defaults to `node:dns/promises` lookup. */
+    lookup?: LookupFn;
+}
+/**
+ * Resolve `host` to ALL its addresses and screen each. Throws {@link SsrfBlockedError}
+ * if any resolved address is blocked (or if `host` is a blocked IP literal, or if
+ * resolution yields no address). Returns the resolved IPs otherwise.
+ */
+declare function resolveAndScreen(rawHost: string, options?: ResolveAndScreenOptions): Promise<string[]>;
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link screenedFetch}. */
+interface ScreenedFetchOptions {
+    /** Fetch implementation (injectable for tests); defaults to global `fetch`. */
+    fetchImpl?: FetchFn;
+    /** DNS resolver (injectable for tests). */
+    lookup?: LookupFn;
+    /** Max redirect hops to follow (default 5). */
+    maxRedirects?: number;
+    /** Skip SSRF screening entirely (opt-out for local-dev tools). Default false. */
+    allowPrivateHosts?: boolean;
+    /** Abort signal forwarded to fetch. */
+    signal?: AbortSignal;
+}
+/**
+ * Fetch `url` with SSRF screening: screens the host (unless `allowPrivateHosts`),
+ * sets `redirect:"manual"`, and re-screens every redirect hop (rejecting a hop to a
+ * blocked host or a non-http(s) target). Throws {@link SsrfBlockedError} on a block
+ * or on exceeding `maxRedirects`.
+ */
+declare function screenedFetch(url: string, options?: ScreenedFetchOptions): Promise<Response>;
+
+/**
+ * Repo-map / env-context builders for orienting an LLM coding agent (M3-3).
+ *
+ * `buildEnvContext(cwd)` renders a short `<env>` block (cwd, platform, node,
+ * is-git, date, project docs, manifests). `buildRepoMap(cwd, opts)` renders a
+ * char-bounded, depth-limited directory tree. Both are node:fs-only and NEVER
+ * throw — a missing/unreadable path yields a best-effort partial string or an
+ * `(unavailable)` marker (distinct from the M3-1/M3-2 guards, which throw).
+ *
+ * Design: blueprint m3-repo-map. Zero new dependencies. A best-effort
+ * orientation aid, not a complete or secure listing (bounded + skips on error).
+ */
+interface RepoMapOptions {
+    /** Max characters of tree output before truncation. Default 8000. */
+    budget?: number;
+    /** Directory/file names to skip (merged with the built-in ignore set). */
+    ignore?: string[];
+    /** Max directory depth to descend. Default 4. */
+    maxDepth?: number;
+}
+/** Render a portable `<env>` orientation block. Never throws. */
+declare function buildEnvContext(cwd: string): string;
+/** Render a char-bounded, depth-limited directory tree. Never throws. */
+declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
+
+/**
+ * Catastrophic-command guardrail for `shell_exec` (M3-2; hardened V3-1).
+ *
+ * `catastrophicShellReason` is a pure, segment-aware deny-list ported from
+ * theocode's security-reviewed `shell-guard.ts` (the proven spec: 42-blocked +
+ * 24-allowed corpus, 0 misses / 0 false-positives). It splits a command on shell
+ * separators (`;`, `&&`, `||`, `|`, `&`, newline), inspects EVERY segment (so a
+ * chained `rm -rf <safe>; rm -rf /` cannot hide), and matches at COMMAND POSITION
+ * (the executable, not an arbitrary substring) so a mention like `echo "rm -rf /"`
+ * is not over-blocked. Returns a human reason for the first catastrophic segment,
+ * else `null`.
+ *
+ * Categories: recursive-force `rm` of an absolute/home/parent path; destructive git
+ * (force-push, `reset --hard`, `clean -fd`); remote-code-execution (curl/wget piped
+ * OR command-substitution `$( )` / `<( )` / eval / source); disk/raw-device wipe
+ * (mkfs, `dd of=/dev/`, `truncate /dev/`, `> /dev/<blockdev>`); recursive chmod/chown
+ * of a root path (SDK extra); fork bomb; `find -delete` / `-exec rm`; secret-file
+ * exfiltration over the network.
+ *
+ * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
+ * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
+ * PowerShell is out of scope. True isolation needs a container.
+ * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
+ */
+
+/** Thrown / reported when a command matches the catastrophic deny-list. */
+declare class CatastrophicCommandError extends ConfigurationError {
+    readonly name = "CatastrophicCommandError";
+    constructor(reason: string);
+}
+/**
+ * Return a human-readable reason when `command` is catastrophic/irreversible, or `null`.
+ * The message is surfaced to the model so it self-corrects.
+ */
+declare function catastrophicShellReason(command: string): string | null;
+
+/**
+ * ACI (Agent-Computer Interface) helpers for tools (M3-5).
+ *
+ * `withDescription(tool, description)` immutably overrides a tool's LLM-facing
+ * description (the wording that drives tool-selection accuracy) — returning a
+ * NEW `CustomTool` and leaving the original untouched. `renderToolList(tools)`
+ * renders a `<tools>` block FROM THE SAME `CustomTool[]` the agent runs, so the
+ * rendered list cannot drift from the real tools (single source of truth).
+ *
+ * Both are pure, zero-dependency, and never throw. The `<tools>` block is a
+ * system-prompt orientation aid — NOT the provider tool-call schema (that stays
+ * each tool's `inputSchema`). Design: blueprint m3-aci-tools.
+ */
+
+/**
+ * Return a new `CustomTool` with `description` replaced. Preserves
+ * name/inputSchema/handler; does NOT mutate the original tool.
+ */
+declare function withDescription(tool: CustomTool, description: string): CustomTool;
+/**
+ * Render a `<tools>` block (name + description per tool) from the agent's actual
+ * `CustomTool[]` — single source of truth, so an overridden/added/removed tool
+ * is reflected automatically. An empty array yields `<tools></tools>`. Never throws.
+ */
+declare function renderToolList(tools: CustomTool[]): string;
+
+/**
+ * Rich-error guidance for tool failures (M3-4).
+ *
+ * `withToolResultGuidance(tool, guidance)` wraps a `CustomTool` so a failing
+ * `{ ok: false, error }` JSON result gains an LLM-actionable `guidance` string
+ * telling the model how to self-correct. The injection is ADDITIVE (only on
+ * `ok:false`), IDEMPOTENT (never overwrites an existing `guidance`), and
+ * NEVER-THROW (a non-JSON / non-object / `ok:true` / unknown-code result is
+ * returned unchanged). Composes over the existing built-in tools (and custom
+ * tools) — no factory edits required.
+ *
+ * Design: blueprint m3-rich-errors. Zero new dependencies (JSON transform).
+ */
+
+/** Maps a tool error code to a short, LLM-actionable self-correction hint. */
+type ToolGuidanceMap = Record<string, string>;
+/** Curated hints for the common cross-tool error codes. Consumers may extend. */
+declare const DEFAULT_TOOL_GUIDANCE: ToolGuidanceMap;
+/**
+ * Pure: parse a tool handler's JSON output and ADD a `guidance` hint when the
+ * result is an `{ ok: false, error }` object whose code has a hint and that does
+ * not already carry guidance. Any other input is returned UNCHANGED (never throws).
+ */
+declare function injectGuidance(handlerOutput: string, guidance: ToolGuidanceMap): string;
+/**
+ * Wrap a `CustomTool` so its failed results gain a `guidance` hint from `guidance`.
+ * Preserves name/description/inputSchema; only the handler output is augmented.
+ */
+declare function withToolResultGuidance(tool: CustomTool, guidance: ToolGuidanceMap): CustomTool;
+/** `withToolResultGuidance` pre-bound to {@link DEFAULT_TOOL_GUIDANCE}. */
+declare function withDefaultGuidance(tool: CustomTool): CustomTool;
+
 /**
  * `list_dir` — built-in tool for coding agents.
  *
@@ -133,7 +397,11 @@ declare function createListDirTool(opts: CreateListDirToolOptions): CustomTool;
  * Return shape (always a JSON string):
  *   - `{ ok: true, mode: string, message: string }`
  *   - `{ ok: false, error: "invalid_action" }`
+ *
+ * Opt-in persistence (M4-4): `createPlanModeTool({ artifactStore })` returns a
+ * variant whose async handler persists the submitted `plan` on `exit`.
  */
+
 type Mode = "normal" | "plan";
 interface PlanModeTool {
     name: string;
@@ -145,7 +413,36 @@ interface PlanModeTool {
     /** Expose current mode for testing. */
     currentMode: () => Mode;
 }
+/**
+ * Plan-mode tool with opt-in artifact persistence (M4-4). Same surface as
+ * {@link PlanModeTool} but the handler is ASYNC (it may write to the store) and
+ * accepts an optional `plan` to persist on `exit`.
+ *
+ * @public
+ */
+interface PlanModeToolWithStore {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: {
+        action: string;
+        plan?: string;
+    }) => Promise<string>;
+    currentMode: () => Mode;
+}
+/**
+ * Options for the persistence-enabled {@link createPlanModeTool} overload.
+ *
+ * @public
+ */
+interface PlanModeToolOptions {
+    /** Store the submitted `plan` is persisted to on `exit`. */
+    artifactStore: SessionArtifactStore;
+    /** Artifact id under which the plan is stored. Default `"plan"`. */
+    artifactId?: string;
+}
 declare function createPlanModeTool(): PlanModeTool;
+declare function createPlanModeTool(options: PlanModeToolOptions): PlanModeToolWithStore;
 
 /**
  * `question` — interactive tool that asks the user a question and waits for a response.
@@ -289,6 +586,13 @@ interface CreateShellToolOptions {
     projectRoot: string;
     /** Default timeout in ms. Capped at 300s. */
     defaultTimeoutMs?: number;
+    /**
+     * Opt out of the catastrophic-command guardrail. Default `false` (the
+     * guardrail screens every command before spawn). Set `true` only when the
+     * agent legitimately needs destructive power flows — it is a heuristic
+     * guardrail, not a sandbox.
+     */
+    allowCatastrophic?: boolean;
 }
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 
@@ -339,6 +643,27 @@ type TodoInput = {
 };
 declare function createTodolistTool(): TodolistTool;
 
+/**
+ * A flat plan-render node — the stable shape a UI/plan layer consumes. Mirrors
+ * the `TodoItem` status union; `label` is the item title.
+ *
+ * @public
+ */
+interface PlanNode {
+    id: string;
+    label: string;
+    status: "pending" | "in_progress" | "done";
+}
+/**
+ * Convert structured todo items (from a `todolist` tool result's `items`, M4-5)
+ * into versioned `PlanNode`s for rendering. Pure: projects EXACTLY
+ * `{ id, label, status }` (timestamps are intentionally dropped), preserving
+ * input order. Replaces consumer-side hand-rolled mappers.
+ *
+ * @public
+ */
+declare function todoItemsToPlanNodes(items: readonly TodoItem[]): PlanNode[];
+
 /**
  * `truncateOutput` — utility for truncating large tool output.
  *
@@ -380,6 +705,12 @@ declare function truncateOutput(output: string, opts?: TruncationOptions): Trunc
 interface CreateWebFetchToolOptions {
     /** Default timeout in ms. */
     defaultTimeoutMs?: number;
+    /**
+     * Opt out of the SSRF guard (default `false`). When `true`, requests to
+     * private/loopback/link-local/metadata addresses are NOT blocked — use only for
+     * trusted local-dev tooling.
+     */
+    allowPrivateHosts?: boolean;
 }
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
@@ -408,6 +739,33 @@ interface CreateWebSearchToolOptions {
 }
 declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
 
+/**
+ * Brave Search adapter for `createWebSearchTool` (M3-7).
+ *
+ * `createBraveWebSearchAdapter()` returns a `WebSearchCallback` that queries the
+ * Brave Search API using an env-driven key (`BRAVE_API_KEY`). It plugs into the
+ * provider-agnostic `createWebSearchTool` via its callback seam — the tool is NOT
+ * modified. The `fetch` impl is injectable (default `globalThis.fetch`) so the
+ * adapter is offline-testable; a plain fetch (not `screenedFetch`) is used because
+ * the endpoint host is fixed (no SSRF surface) and `screenedFetch` cannot carry
+ * the required auth header. Zero new dependencies. Design: blueprint m3-websearch-adapter.
+ */
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface CreateBraveWebSearchAdapterOptions {
+    /** Brave API key. Defaults to `process.env.BRAVE_API_KEY`. */
+    apiKey?: string;
+    /** Injectable fetch (default `globalThis.fetch`) — set in tests for offline runs. */
+    fetchImpl?: FetchLike;
+    /** Override the Brave endpoint (self-host / test). */
+    endpoint?: string;
+}
+/**
+ * Build a `WebSearchCallback` backed by the Brave Search API. Throws a typed
+ * `ConfigurationError` ("no_api_key") at creation when no key is available.
+ */
+declare function createBraveWebSearchAdapter(opts?: CreateBraveWebSearchAdapterOptions): WebSearchCallback;
+
 /**
  * `write_file` — built-in tool for coding agents.
  *
@@ -427,4 +785,4 @@ interface CreateWriteFileToolOptions {
 }
 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 };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withToolResultGuidance };