@theokit/sdk-tools 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
+import { SandboxProvider } from '@theokit/sdk/sandbox';
+import { InteractiveProvider } from '@theokit/sdk/interactive';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -88,6 +90,9 @@ declare function createSessionArtifactStore(options: SessionArtifactStoreOptions
 interface CreateEditFileToolOptions {
     /** Absolute path to the project root. Every edit is gated against this boundary. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the read + `.bak` backup +
+     *  write go through the backend (surface-agnostic); omitted ⇒ the local `fs` path (byte-identical). */
+    filesystem?: FilesystemProvider;
 }
 declare function createEditFileTool(opts: CreateEditFileToolOptions): CustomTool;
 
@@ -133,6 +138,9 @@ interface CreateGitDiffToolOptions {
     projectRoot: string;
     timeoutMs?: number;
     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;
 }
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
@@ -150,9 +158,39 @@ declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 interface CreateGlobToolOptions {
     /** Absolute path to the project root. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the walk reads through the
+     *  backend (Local/remote), so the tool is surface-agnostic; omitted ⇒ the local `readdir` (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
 
+/**
+ * `interactive_shell` + `write_stdin` — built-in tools for driving an interactive
+ * session (a REPL, `git rebase -i`, any command that PROMPTS for stdin).
+ *
+ * Surface-agnostic by construction: both tools depend on an INJECTED
+ * `InteractiveProvider` (`@theokit/sdk/interactive`) exactly as `read_file`
+ * depends on `FilesystemProvider`. The HOST supplies the backend — a local
+ * `@theokit/sdk-pty` (terminal), a container/E2B backend (cluster/web), or a
+ * Tauri backend (desktop) — so the SAME tool runs on every theokit surface with
+ * NO native dependency here. When no backend is injected (or it cannot allocate
+ * a session) the tool returns `{ ok: false, error: 'interactive_unavailable' }`
+ * and the agent falls back to non-interactive exec.
+ *
+ * Return shapes (always a JSON string):
+ *   interactive_shell → `{ ok: true, session_id, output }` | `{ ok: false, error }`
+ *   write_stdin       → `{ ok: true, output, alive }`       | `{ ok: false, error }`
+ */
+
+interface CreateInteractiveShellToolOptions {
+    /** The interactive backend, or a per-request resolver of one (injected — never a direct native dep). */
+    interactive: InteractiveProvider<unknown>;
+}
+/** Start an interactive session; returns a `session_id` to drive with `write_stdin`. */
+declare function createInteractiveShellTool(opts: CreateInteractiveShellToolOptions): CustomTool;
+/** Write to a live interactive session's stdin and read the output it produces. */
+declare function createWriteStdinTool(opts: CreateInteractiveShellToolOptions): CustomTool;
+
 /**
  * Composable command-permission policy layer (M3-6).
  *
@@ -706,6 +744,9 @@ interface CreateSearchTextToolOptions {
     maxMatches?: number;
     /** Skip files larger than this (bytes). Default 1 MB. */
     maxFileSize?: number;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the recursive walk reads
+     *  through the backend (surface-agnostic); omitted ⇒ the local `readdir`/`readFile` walk (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 
@@ -732,6 +773,14 @@ interface CreateShellToolOptions {
      * guardrail, not a sandbox.
      */
     allowCatastrophic?: boolean;
+    /**
+     * Optional injected execution backend (`@theokit/sdk/sandbox`) — a backend or a per-request resolver.
+     * When provided, the command runs via `SandboxBackend.execute` (Local/Docker/E2B) so the tool is
+     * surface-agnostic (a cluster/desktop host runs it in the sandbox, not the local host); omitted ⇒ the
+     * local `/bin/sh -c` child process (byte-identical to before). The catastrophic-command guard runs
+     * before either path.
+     */
+    sandbox?: SandboxProvider;
 }
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 
@@ -1003,4 +1052,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, 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 TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, 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 TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
+import { SandboxProvider } from '@theokit/sdk/sandbox';
+import { InteractiveProvider } from '@theokit/sdk/interactive';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -88,6 +90,9 @@ declare function createSessionArtifactStore(options: SessionArtifactStoreOptions
 interface CreateEditFileToolOptions {
     /** Absolute path to the project root. Every edit is gated against this boundary. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the read + `.bak` backup +
+     *  write go through the backend (surface-agnostic); omitted ⇒ the local `fs` path (byte-identical). */
+    filesystem?: FilesystemProvider;
 }
 declare function createEditFileTool(opts: CreateEditFileToolOptions): CustomTool;
 
@@ -133,6 +138,9 @@ interface CreateGitDiffToolOptions {
     projectRoot: string;
     timeoutMs?: number;
     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;
 }
 declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 
@@ -150,9 +158,39 @@ declare function createGitDiffTool(opts: CreateGitDiffToolOptions): CustomTool;
 interface CreateGlobToolOptions {
     /** Absolute path to the project root. */
     projectRoot: string;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the walk reads through the
+     *  backend (Local/remote), so the tool is surface-agnostic; omitted ⇒ the local `readdir` (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createGlobTool(opts: CreateGlobToolOptions): CustomTool;
 
+/**
+ * `interactive_shell` + `write_stdin` — built-in tools for driving an interactive
+ * session (a REPL, `git rebase -i`, any command that PROMPTS for stdin).
+ *
+ * Surface-agnostic by construction: both tools depend on an INJECTED
+ * `InteractiveProvider` (`@theokit/sdk/interactive`) exactly as `read_file`
+ * depends on `FilesystemProvider`. The HOST supplies the backend — a local
+ * `@theokit/sdk-pty` (terminal), a container/E2B backend (cluster/web), or a
+ * Tauri backend (desktop) — so the SAME tool runs on every theokit surface with
+ * NO native dependency here. When no backend is injected (or it cannot allocate
+ * a session) the tool returns `{ ok: false, error: 'interactive_unavailable' }`
+ * and the agent falls back to non-interactive exec.
+ *
+ * Return shapes (always a JSON string):
+ *   interactive_shell → `{ ok: true, session_id, output }` | `{ ok: false, error }`
+ *   write_stdin       → `{ ok: true, output, alive }`       | `{ ok: false, error }`
+ */
+
+interface CreateInteractiveShellToolOptions {
+    /** The interactive backend, or a per-request resolver of one (injected — never a direct native dep). */
+    interactive: InteractiveProvider<unknown>;
+}
+/** Start an interactive session; returns a `session_id` to drive with `write_stdin`. */
+declare function createInteractiveShellTool(opts: CreateInteractiveShellToolOptions): CustomTool;
+/** Write to a live interactive session's stdin and read the output it produces. */
+declare function createWriteStdinTool(opts: CreateInteractiveShellToolOptions): CustomTool;
+
 /**
  * Composable command-permission policy layer (M3-6).
  *
@@ -706,6 +744,9 @@ interface CreateSearchTextToolOptions {
     maxMatches?: number;
     /** Skip files larger than this (bytes). Default 1 MB. */
     maxFileSize?: number;
+    /** Optional injected filesystem (`@theokit/sdk/filesystem`) — when provided, the recursive walk reads
+     *  through the backend (surface-agnostic); omitted ⇒ the local `readdir`/`readFile` walk (unchanged). */
+    filesystem?: FilesystemProvider;
 }
 declare function createSearchTextTool(opts: CreateSearchTextToolOptions): CustomTool;
 
@@ -732,6 +773,14 @@ interface CreateShellToolOptions {
      * guardrail, not a sandbox.
      */
     allowCatastrophic?: boolean;
+    /**
+     * Optional injected execution backend (`@theokit/sdk/sandbox`) — a backend or a per-request resolver.
+     * When provided, the command runs via `SandboxBackend.execute` (Local/Docker/E2B) so the tool is
+     * surface-agnostic (a cluster/desktop host runs it in the sandbox, not the local host); omitted ⇒ the
+     * local `/bin/sh -c` child process (byte-identical to before). The catastrophic-command guard runs
+     * before either path.
+     */
+    sandbox?: SandboxProvider;
 }
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 
@@ -1003,4 +1052,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, 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 TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, 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 TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };