@theokit/sdk-tools 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -361,6 +361,14 @@ declare function injectGuidance(handlerOutput: string, guidance: ToolGuidanceMap
 declare function withToolResultGuidance(tool: CustomTool, guidance: ToolGuidanceMap): CustomTool;
 /** `withToolResultGuidance` pre-bound to {@link DEFAULT_TOOL_GUIDANCE}. */
 declare function withDefaultGuidance(tool: CustomTool): CustomTool;
+/**
+ * Wrap `shell_exec` so a SOFT failure — `{ ok: true, exit_code != 0 }` (the TOOL ran, the COMMAND
+ * failed) — gains a `guidance` hint. This is the one case {@link injectGuidance} does not cover (it
+ * is `ok:false`-only by design). ADDITIVE, IDEMPOTENT, NEVER-THROW; a no-op for any other tool, for
+ * `exit_code 0`, and for non-JSON output. Compose AFTER {@link withDefaultGuidance} (the two domains —
+ * `ok:false` vs `ok:true` soft-fail — are disjoint, so there is no double-injection).
+ */
+declare function withShellExitGuidance(tool: CustomTool): CustomTool;
 
 /**
  * `list_dir` — built-in tool for coding agents.
@@ -785,4 +793,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-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 };
+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, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -361,6 +361,14 @@ declare function injectGuidance(handlerOutput: string, guidance: ToolGuidanceMap
 declare function withToolResultGuidance(tool: CustomTool, guidance: ToolGuidanceMap): CustomTool;
 /** `withToolResultGuidance` pre-bound to {@link DEFAULT_TOOL_GUIDANCE}. */
 declare function withDefaultGuidance(tool: CustomTool): CustomTool;
+/**
+ * Wrap `shell_exec` so a SOFT failure — `{ ok: true, exit_code != 0 }` (the TOOL ran, the COMMAND
+ * failed) — gains a `guidance` hint. This is the one case {@link injectGuidance} does not cover (it
+ * is `ok:false`-only by design). ADDITIVE, IDEMPOTENT, NEVER-THROW; a no-op for any other tool, for
+ * `exit_code 0`, and for non-JSON output. Compose AFTER {@link withDefaultGuidance} (the two domains —
+ * `ok:false` vs `ok:true` soft-fail — are disjoint, so there is no double-injection).
+ */
+declare function withShellExitGuidance(tool: CustomTool): CustomTool;
 
 /**
  * `list_dir` — built-in tool for coding agents.
@@ -785,4 +793,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-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 };
+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, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -1027,6 +1027,28 @@ function withToolResultGuidance(tool, guidance) {
 function withDefaultGuidance(tool) {
   return withToolResultGuidance(tool, DEFAULT_TOOL_GUIDANCE);
 }
+function withShellExitGuidance(tool) {
+  if (tool.name !== "shell_exec") return tool;
+  return {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: async (input) => {
+      const out = await tool.handler(input);
+      let parsed;
+      try {
+        parsed = JSON.parse(out);
+      } catch {
+        return out;
+      }
+      if (isRecord(parsed) && parsed.ok === true && typeof parsed.exit_code === "number" && parsed.exit_code !== 0 && !("guidance" in parsed)) {
+        const guidance = `The command exited ${parsed.exit_code}. Read the stderr above, fix the cause, then retry.`;
+        return JSON.stringify({ ...parsed, guidance });
+      }
+      return out;
+    }
+  };
+}
 var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES } = opts;
@@ -1937,6 +1959,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, SsrfBlockedError, 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 };
+export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, SsrfBlockedError, 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, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map