@theokit/sdk-tools 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- 6d65983: `createWebFetchTool` gains a redirect policy + injection seam.
+
+  - **`maxRedirects?: number`** — caps redirect hops (each SSRF-screened). Default 5 (unchanged). Set `0` to BLOCK ALL redirects (strict no-redirect policy for untrusted, model-chosen URLs).
+  - **Distinct `redirect_blocked` error** — a refused redirect now returns `{ ok:false, error:'redirect_blocked' }`, split from `ssrf_blocked` (a blocked private/reserved host). New exported `RedirectBlockedError`; `screenedFetch` throws it on redirect-limit exhaustion (was `SsrfBlockedError("too many redirects")` — a minor, more-precise error refinement).
+  - **Injectable `fetchImpl?` / `lookup?`** — drive the tool's redirect + SSRF paths deterministically in tests with no real network/DNS (the seam `screenedFetch` already had, now on the tool surface).
+
+  Additive + backward-compatible: absent options ⇒ today's behavior; `ssrf_blocked`/`invalid_url`/`timeout`/`too_large` codes + return shape unchanged. Lets a consumer (theocode) replace an app-side SSRF/redirect wrapper with `createWebFetchTool({ maxRedirects: 0 })`.
+
+## 0.5.0
+
+### Minor Changes
+
+- 6dc0e26: Add `withShellExitGuidance` — a guidance wrapper for `shell_exec` soft failures.
+
+  `injectGuidance`/`withDefaultGuidance` inject an actionable `guidance` hint only on `{ ok:false, error }` results (by design). But `shell_exec` returns `{ ok:true, exit_code }` — a non-zero `exit_code` is a SOFT failure (the tool ran, the command failed) that the ok:false-only injector does not cover. `withShellExitGuidance(tool)` wraps `shell_exec` so a `{ ok:true, exit_code≠0 }` result gains a `guidance` hint ("The command exited N. Read the stderr above, fix the cause, then retry."). ADDITIVE, IDEMPOTENT, NEVER-THROW; a no-op for any other tool, for `exit_code 0`, and for non-JSON output. Composes after `withDefaultGuidance` (disjoint domains — no double-injection). Lets consumers drop app-side shell-exit guidance reimplementations.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -721,6 +721,15 @@ var SsrfBlockedError = class extends sdk.ConfigurationError {
     );
   }
 };
+var RedirectBlockedError = class extends sdk.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;
@@ -844,7 +853,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;
@@ -1029,6 +1038,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;
@@ -1747,6 +1778,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 sdk.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 }.",
@@ -1776,7 +1810,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");
@@ -1809,6 +1846,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 });
         }
@@ -1941,6 +1981,7 @@ async function isBinaryFile(absolutePath) {
 
 exports.CatastrophicCommandError = CatastrophicCommandError;
 exports.DEFAULT_TOOL_GUIDANCE = DEFAULT_TOOL_GUIDANCE;
+exports.RedirectBlockedError = RedirectBlockedError;
 exports.SsrfBlockedError = SsrfBlockedError;
 exports.buildEnvContext = buildEnvContext;
 exports.buildRepoMap = buildRepoMap;
@@ -1978,6 +2019,7 @@ exports.todoItemsToPlanNodes = todoItemsToPlanNodes;
 exports.truncateOutput = truncateOutput;
 exports.withDefaultGuidance = withDefaultGuidance;
 exports.withDescription = withDescription;
+exports.withShellExitGuidance = withShellExitGuidance;
 exports.withToolResultGuidance = withToolResultGuidance;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map