@theokit/sdk-tools 0.5.0 → 0.7.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
@@ -323,12 +332,26 @@ declare function catastrophicShellReason(command: string): string | null;
  * name/inputSchema/handler; does NOT mutate the original tool.
  */
 declare function withDescription(tool: CustomTool, description: string): CustomTool;
+/** Render mode for {@link renderToolList}. Local — the published `renderToolList`
+ *  signature inlines this union into its `.d.ts`, so consumers pass the literal
+ *  ("summary" | "names" | "full") without needing the named type exported. */
+type ToolListMode = "full" | "summary" | "names";
 /**
- * Render a `<tools>` block (name + description per tool) from the agent's actual
- * `CustomTool[]` — single source of truth, so an overridden/added/removed tool
- * is reflected automatically. An empty array yields `<tools></tools>`. Never throws.
+ * Render the agent's actual `CustomTool[]` — single source of truth, so an
+ * overridden/added/removed tool is reflected automatically. Never throws.
+ *
+ * Modes (`options.mode`, default `"full"`):
+ * - `"full"`: a `<tools>` XML block (name + description per tool, XML-escaped).
+ *   An empty array yields `<tools></tools>`.
+ * - `"summary"`: markdown `- name: <first sentence>` per tool (NOT XML-escaped).
+ * - `"names"`: markdown `- name` per tool (NOT XML-escaped).
+ *
+ * Markdown modes on an empty array yield `""`. A non-object `options` arg (e.g. a
+ * map index from `tools.map(renderToolList)`) has no `.mode` → falls back to `"full"`.
  */
-declare function renderToolList(tools: CustomTool[]): string;
+declare function renderToolList(tools: CustomTool[], options?: {
+    mode?: ToolListMode;
+}): string;
 
 /**
  * Rich-error guidance for tool failures (M3-4).
@@ -707,7 +730,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 {
@@ -719,6 +742,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;
 
@@ -793,4 +826,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, withShellExitGuidance, 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
@@ -323,12 +332,26 @@ declare function catastrophicShellReason(command: string): string | null;
  * name/inputSchema/handler; does NOT mutate the original tool.
  */
 declare function withDescription(tool: CustomTool, description: string): CustomTool;
+/** Render mode for {@link renderToolList}. Local — the published `renderToolList`
+ *  signature inlines this union into its `.d.ts`, so consumers pass the literal
+ *  ("summary" | "names" | "full") without needing the named type exported. */
+type ToolListMode = "full" | "summary" | "names";
 /**
- * Render a `<tools>` block (name + description per tool) from the agent's actual
- * `CustomTool[]` — single source of truth, so an overridden/added/removed tool
- * is reflected automatically. An empty array yields `<tools></tools>`. Never throws.
+ * Render the agent's actual `CustomTool[]` — single source of truth, so an
+ * overridden/added/removed tool is reflected automatically. Never throws.
+ *
+ * Modes (`options.mode`, default `"full"`):
+ * - `"full"`: a `<tools>` XML block (name + description per tool, XML-escaped).
+ *   An empty array yields `<tools></tools>`.
+ * - `"summary"`: markdown `- name: <first sentence>` per tool (NOT XML-escaped).
+ * - `"names"`: markdown `- name` per tool (NOT XML-escaped).
+ *
+ * Markdown modes on an empty array yield `""`. A non-object `options` arg (e.g. a
+ * map index from `tools.map(renderToolList)`) has no `.mode` → falls back to `"full"`.
  */
-declare function renderToolList(tools: CustomTool[]): string;
+declare function renderToolList(tools: CustomTool[], options?: {
+    mode?: ToolListMode;
+}): string;
 
 /**
  * Rich-error guidance for tool failures (M3-4).
@@ -707,7 +730,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 {
@@ -719,6 +742,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;
 
@@ -793,4 +826,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, withShellExitGuidance, 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;
@@ -970,7 +979,18 @@ function withDescription(tool, description) {
 function esc(s) {
   return String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
-function renderToolList(tools) {
+function firstSentence(d) {
+  const m = d.trim().match(/\.\s+(?=[A-Z(]|$)/);
+  return m?.index == null ? d.trim() : d.trim().slice(0, m.index + 1);
+}
+function renderToolList(tools, options) {
+  const mode = options?.mode ?? "full";
+  if (mode === "summary") {
+    return tools.map((t) => `- ${t.name}: ${firstSentence(t.description)}`).join("\n");
+  }
+  if (mode === "names") {
+    return tools.map((t) => `- ${t.name}`).join("\n");
+  }
   if (tools.length === 0) return "<tools></tools>";
   const lines = ["<tools>"];
   for (const t of tools) {
@@ -1767,6 +1787,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 }.",
@@ -1796,7 +1819,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");
@@ -1829,6 +1855,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 });
         }
@@ -1959,6 +1988,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, withShellExitGuidance, 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