@theokit/sdk-tools 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -199,6 +199,15 @@ declare class SsrfBlockedError extends ConfigurationError {
     readonly name = "SsrfBlockedError";
     constructor(host: string, detail?: string);
 }
+/**
+ * Thrown when a request is refused by the REDIRECT policy (the `maxRedirects` hop limit was
+ * exceeded) — a distinct event from {@link SsrfBlockedError} (a blocked host). With `maxRedirects: 0`
+ * this fires on the first 3xx (block-all-redirects). Carries `code: "redirect_blocked"`.
+ */
+declare class RedirectBlockedError extends ConfigurationError {
+    readonly name = "RedirectBlockedError";
+    constructor(url: 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
@@ -361,6 +370,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.
@@ -699,7 +716,7 @@ declare function truncateOutput(output: string, opts?: TruncationOptions): Trunc
  * Return shape (always a JSON string):
  *   - `{ ok: true, content, status_code, content_type }`
  *   - `{ ok: false, error: 'invalid_url' | 'fetch_failed' |
- *        'timeout' | 'too_large' }`
+ *        'timeout' | 'too_large' | 'ssrf_blocked' | 'redirect_blocked' }`
  */
 
 interface CreateWebFetchToolOptions {
@@ -711,6 +728,16 @@ interface CreateWebFetchToolOptions {
      * trusted local-dev tooling.
      */
     allowPrivateHosts?: boolean;
+    /**
+     * Max redirect hops to follow (each SSRF-screened). Default 5. Set `0` to BLOCK ALL
+     * redirects — a 3xx then returns `{ ok: false, error: "redirect_blocked" }` (a strict
+     * no-redirect policy for untrusted, model-chosen URLs).
+     */
+    maxRedirects?: number;
+    /** Fetch implementation (injectable for tests — drive paths with no real network). */
+    fetchImpl?: ScreenedFetchOptions["fetchImpl"];
+    /** DNS resolver (injectable for tests — drive the SSRF path with no real DNS). */
+    lookup?: ScreenedFetchOptions["lookup"];
 }
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
@@ -785,4 +812,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, 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, 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

@@ -199,6 +199,15 @@ declare class SsrfBlockedError extends ConfigurationError {
     readonly name = "SsrfBlockedError";
     constructor(host: string, detail?: string);
 }
+/**
+ * Thrown when a request is refused by the REDIRECT policy (the `maxRedirects` hop limit was
+ * exceeded) — a distinct event from {@link SsrfBlockedError} (a blocked host). With `maxRedirects: 0`
+ * this fires on the first 3xx (block-all-redirects). Carries `code: "redirect_blocked"`.
+ */
+declare class RedirectBlockedError extends ConfigurationError {
+    readonly name = "RedirectBlockedError";
+    constructor(url: 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
@@ -361,6 +370,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.
@@ -699,7 +716,7 @@ declare function truncateOutput(output: string, opts?: TruncationOptions): Trunc
  * Return shape (always a JSON string):
  *   - `{ ok: true, content, status_code, content_type }`
  *   - `{ ok: false, error: 'invalid_url' | 'fetch_failed' |
- *        'timeout' | 'too_large' }`
+ *        'timeout' | 'too_large' | 'ssrf_blocked' | 'redirect_blocked' }`
  */
 
 interface CreateWebFetchToolOptions {
@@ -711,6 +728,16 @@ interface CreateWebFetchToolOptions {
      * trusted local-dev tooling.
      */
     allowPrivateHosts?: boolean;
+    /**
+     * Max redirect hops to follow (each SSRF-screened). Default 5. Set `0` to BLOCK ALL
+     * redirects — a 3xx then returns `{ ok: false, error: "redirect_blocked" }` (a strict
+     * no-redirect policy for untrusted, model-chosen URLs).
+     */
+    maxRedirects?: number;
+    /** Fetch implementation (injectable for tests — drive paths with no real network). */
+    fetchImpl?: ScreenedFetchOptions["fetchImpl"];
+    /** DNS resolver (injectable for tests — drive the SSRF path with no real DNS). */
+    lookup?: ScreenedFetchOptions["lookup"];
 }
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
@@ -785,4 +812,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, 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, 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

@@ -719,6 +719,15 @@ var SsrfBlockedError = class extends ConfigurationError {
     );
   }
 };
+var RedirectBlockedError = class extends ConfigurationError {
+  name = "RedirectBlockedError";
+  constructor(url, detail) {
+    super(
+      `Blocked redirect for "${url}"${detail ? ` (${detail})` : ""}: redirect-hop limit exceeded (redirect policy).`,
+      { code: "redirect_blocked" }
+    );
+  }
+};
 function v4ToInt(ip) {
   const parts = ip.split(".");
   return (Number(parts[0]) << 24 | Number(parts[1]) << 16 | Number(parts[2]) << 8 | Number(parts[3])) >>> 0;
@@ -842,7 +851,7 @@ async function screenedFetch(url, options = {}) {
     if (next === void 0) return res;
     current = next;
   }
-  throw new SsrfBlockedError(url, "too many redirects");
+  throw new RedirectBlockedError(url, "too many redirects");
 }
 var DEFAULT_BUDGET = 8e3;
 var DEFAULT_MAX_DEPTH = 4;
@@ -1027,6 +1036,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;
@@ -1745,6 +1776,9 @@ var MAX_BODY_BYTES = 1 * 1024 * 1024;
 function createWebFetchTool(opts) {
   const defaultTimeoutMs = opts?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS4;
   const allowPrivateHosts = opts?.allowPrivateHosts ?? false;
+  const maxRedirects = opts?.maxRedirects;
+  const fetchImpl = opts?.fetchImpl;
+  const lookup = opts?.lookup;
   return defineTool({
     name: "web_fetch",
     description: "Fetch the contents of a URL via HTTP/HTTPS. Use only for URLs the user provided or that you are confident help with the task; never invent or guess URLs. Rejects non-http(s) URLs and is SSRF-guarded by default (private/loopback/link-local/cloud-metadata hosts are refused with an ssrf_blocked error). The response body is capped at 1 MB. Returns { ok, content, status_code, content_type } or { ok: false, error }.",
@@ -1774,7 +1808,10 @@ function createWebFetchTool(opts) {
       try {
         const response = await screenedFetch(url, {
           signal: controller.signal,
-          allowPrivateHosts
+          allowPrivateHosts,
+          ...maxRedirects !== void 0 ? { maxRedirects } : {},
+          ...fetchImpl ? { fetchImpl } : {},
+          ...lookup ? { lookup } : {}
         });
         clearTimeout(timer);
         const contentLength = response.headers.get("content-length");
@@ -1807,6 +1844,9 @@ function createWebFetchTool(opts) {
         });
       } catch (err) {
         clearTimeout(timer);
+        if (err instanceof RedirectBlockedError) {
+          return JSON.stringify({ ok: false, error: "redirect_blocked", url, reason: err.message });
+        }
         if (err instanceof SsrfBlockedError) {
           return JSON.stringify({ ok: false, error: "ssrf_blocked", url, reason: err.message });
         }
@@ -1937,6 +1977,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, RedirectBlockedError, 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