@theokit/sdk-tools 0.13.0 → 0.14.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
+import { InteractiveProvider } from '@theokit/sdk/interactive';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
 
 /**
@@ -153,6 +154,33 @@ interface CreateGlobToolOptions {
 }
 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).
  *
@@ -1003,4 +1031,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,4 +1,5 @@
 import { CustomTool, ConfigurationError } from '@theokit/sdk';
+import { InteractiveProvider } from '@theokit/sdk/interactive';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
 
 /**
@@ -153,6 +154,33 @@ interface CreateGlobToolOptions {
 }
 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).
  *
@@ -1003,4 +1031,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.js

@@ -6,6 +6,7 @@ import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileS
 import { safeFilenameForId, safePathJoin as safePathJoin$1 } from '@theokit/sdk/path-safety';
 import { replaceFileAtomic } from '@theokit/sdk/persistence';
 import { spawn } from 'child_process';
+import { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
 import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
@@ -689,6 +690,60 @@ function globToRegex(pattern) {
   }
   return new RegExp(`^${regexStr}$`);
 }
+function toErrorJson(err) {
+  if (err instanceof InteractiveUnavailableError) {
+    return JSON.stringify({ ok: false, error: "interactive_unavailable" });
+  }
+  if (err instanceof NoSuchSessionError) {
+    return JSON.stringify({ ok: false, error: "no_such_session" });
+  }
+  throw err;
+}
+function createInteractiveShellTool(opts) {
+  const { interactive } = opts;
+  return Tool.create({
+    name: "interactive_shell",
+    description: "Start an interactive shell session for a command that PROMPTS for input or is a REPL (python, node, `git rebase -i`, a `read` prompt) \u2014 NOT for one-shot commands (use shell_exec). Returns a session_id; drive it with write_stdin, reading the incremental output each step. Returns { ok, session_id, output } or { ok: false, error }.",
+    inputSchema: z.object({
+      command: z.string().min(1).describe("Command to run interactively, e.g. 'python3' or 'bash -i'."),
+      yield_time_ms: z.number().int().positive().optional().describe("How long to wait for startup output before returning (clamped by the backend).")
+    }),
+    handler: async ({ command, yield_time_ms }, ctx) => {
+      try {
+        const backend = await resolveInteractive(interactive, ctx ?? {});
+        const { sessionId, output } = await backend.startInteractive(command, {
+          yieldMs: yield_time_ms
+        });
+        return JSON.stringify({ ok: true, session_id: sessionId, output });
+      } catch (err) {
+        return toErrorJson(err);
+      }
+    }
+  });
+}
+function createWriteStdinTool(opts) {
+  const { interactive } = opts;
+  return Tool.create({
+    name: "write_stdin",
+    description: "Write input to a live interactive session (from interactive_shell) and read the output it produces during the wait window. Include a trailing newline to submit a line. Returns { ok, output, alive } (alive:false means the session exited) or { ok: false, error }.",
+    inputSchema: z.object({
+      session_id: z.string().min(1).describe("The session_id returned by interactive_shell."),
+      input: z.string().describe("Text to write to stdin (add a trailing '\\n' to submit a line)."),
+      yield_time_ms: z.number().int().positive().optional().describe("How long to wait for output before returning (clamped by the backend).")
+    }),
+    handler: async ({ session_id, input, yield_time_ms }, ctx) => {
+      try {
+        const backend = await resolveInteractive(interactive, ctx ?? {});
+        const { output, alive } = await backend.writeStdin(session_id, input, {
+          yieldMs: yield_time_ms
+        });
+        return JSON.stringify({ ok: true, output, alive });
+      } catch (err) {
+        return toErrorJson(err);
+      }
+    }
+  });
+}
 var CatastrophicCommandError = class extends ConfigurationError {
   name = "CatastrophicCommandError";
   constructor(reason) {
@@ -2341,6 +2396,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, 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, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map