@theokit/sdk-tools 0.26.3 → 0.27.0

package/dist/index.d.cts

@@ -1173,6 +1173,60 @@ declare function truncateOutput(output: string, opts?: TruncationOptions): Trunc
 
 declare function createUpdatePlanTool(): CustomTool;
 
+/**
+ * `view_image` — let the agent LOOK at an image in the project.
+ *
+ * ## Why this is a built-in
+ *
+ * It was the one tool a consumer had to write from scratch (89 LOC), and its shape — a `handler`
+ * returning a structured result plus `toModelOutput` shaping it into an `ImageBlock` — is the
+ * canonical multimodal shape the SDK already defines (SE17). Every product that wants an agent to look at a
+ * screenshot rewrites the same base64 + media-type + confinement logic.
+ *
+ * The confinement is the part that is easy to get wrong, and the reason this belongs in a reviewed
+ * built-in rather than in each product: **an image reader that honours any path is a file
+ * exfiltration primitive with a friendly name.** `/etc/passwd` renamed to `.png` is not a
+ * hypothetical — it is one prompt away.
+ *
+ * ## The two channels
+ *
+ * This built-in uses the SE17 split. The handler returns the envelope as a JSON **string** — which
+ * is what `Tool.create` types it to return — and `toModelOutput` turns that string into an
+ * `ImageBlock` for the model, while `defineTool` routes the full value to `onToolEnd` through a
+ * resolver under `TOOL_SPLIT_RESOLVER`.
+ *
+ * So `tool.handler(...)` yields image blocks on success and the JSON string on failure: the factory
+ * has already applied the shaping. There is no `tool.toModelOutput` left to call, and returning the
+ * envelope unshaped would send the model a base64 blob as TEXT — something it cannot look at, which
+ * is the failure this tool exists to avoid.
+ *
+ * ## Result shape (the APP channel)
+ *
+ *   - `{ ok: true, path, media_type, bytes, data }`
+ *   - `{ ok: false, error: "path_traversal" | "not_found" | "unsupported_image_type" | "image_too_large", … }`
+ */
+
+/**
+ * Default ceiling: 5 MB on disk.
+ *
+ * Base64 inflates by 4/3 and the result lands directly in the model's context. A 20 MB screenshot is
+ * not a slow request — it is a failed turn, and an expensive one.
+ */
+declare const DEFAULT_MAX_IMAGE_BYTES: number;
+interface CreateViewImageToolOptions {
+    /** Root the tool reads from. Every path is resolved inside it. */
+    projectRoot: string;
+    /** Name exposed to the model. Omitted ⇒ `view_image`. The name is a contract: it is the approval
+     *  key, what the model sees, and what telemetry records. */
+    name?: string;
+    /** Description exposed to the model. Omitted ⇒ the literal below. */
+    description?: string;
+    /** Ceiling in bytes, measured on disk. Omitted ⇒ {@link DEFAULT_MAX_IMAGE_BYTES}. */
+    maxBytes?: number;
+}
+/** Read an image from the project so the model can look at it. */
+declare function createViewImageTool(options: CreateViewImageToolOptions): CustomTool;
+
 /**
  * `web_fetch` — built-in tool for coding agents.
  *
@@ -1351,4 +1405,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, 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 TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, 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 CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_IMAGE_BYTES, 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 TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, 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

@@ -1173,6 +1173,60 @@ declare function truncateOutput(output: string, opts?: TruncationOptions): Trunc
 
 declare function createUpdatePlanTool(): CustomTool;
 
+/**
+ * `view_image` — let the agent LOOK at an image in the project.
+ *
+ * ## Why this is a built-in
+ *
+ * It was the one tool a consumer had to write from scratch (89 LOC), and its shape — a `handler`
+ * returning a structured result plus `toModelOutput` shaping it into an `ImageBlock` — is the
+ * canonical multimodal shape the SDK already defines (SE17). Every product that wants an agent to look at a
+ * screenshot rewrites the same base64 + media-type + confinement logic.
+ *
+ * The confinement is the part that is easy to get wrong, and the reason this belongs in a reviewed
+ * built-in rather than in each product: **an image reader that honours any path is a file
+ * exfiltration primitive with a friendly name.** `/etc/passwd` renamed to `.png` is not a
+ * hypothetical — it is one prompt away.
+ *
+ * ## The two channels
+ *
+ * This built-in uses the SE17 split. The handler returns the envelope as a JSON **string** — which
+ * is what `Tool.create` types it to return — and `toModelOutput` turns that string into an
+ * `ImageBlock` for the model, while `defineTool` routes the full value to `onToolEnd` through a
+ * resolver under `TOOL_SPLIT_RESOLVER`.
+ *
+ * So `tool.handler(...)` yields image blocks on success and the JSON string on failure: the factory
+ * has already applied the shaping. There is no `tool.toModelOutput` left to call, and returning the
+ * envelope unshaped would send the model a base64 blob as TEXT — something it cannot look at, which
+ * is the failure this tool exists to avoid.
+ *
+ * ## Result shape (the APP channel)
+ *
+ *   - `{ ok: true, path, media_type, bytes, data }`
+ *   - `{ ok: false, error: "path_traversal" | "not_found" | "unsupported_image_type" | "image_too_large", … }`
+ */
+
+/**
+ * Default ceiling: 5 MB on disk.
+ *
+ * Base64 inflates by 4/3 and the result lands directly in the model's context. A 20 MB screenshot is
+ * not a slow request — it is a failed turn, and an expensive one.
+ */
+declare const DEFAULT_MAX_IMAGE_BYTES: number;
+interface CreateViewImageToolOptions {
+    /** Root the tool reads from. Every path is resolved inside it. */
+    projectRoot: string;
+    /** Name exposed to the model. Omitted ⇒ `view_image`. The name is a contract: it is the approval
+     *  key, what the model sees, and what telemetry records. */
+    name?: string;
+    /** Description exposed to the model. Omitted ⇒ the literal below. */
+    description?: string;
+    /** Ceiling in bytes, measured on disk. Omitted ⇒ {@link DEFAULT_MAX_IMAGE_BYTES}. */
+    maxBytes?: number;
+}
+/** Read an image from the project so the model can look at it. */
+declare function createViewImageTool(options: CreateViewImageToolOptions): CustomTool;
+
 /**
  * `web_fetch` — built-in tool for coding agents.
  *
@@ -1351,4 +1405,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, 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 TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, 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 CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGitStatusToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_IMAGE_BYTES, 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 TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, 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

@@ -1,5 +1,5 @@
 import { rm, mkdir, writeFile, readFile, readdir, open, stat, copyFile } from 'fs/promises';
-import { dirname, relative, join, isAbsolute } from 'path';
+import { dirname, relative, join, isAbsolute, extname } from 'path';
 import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
 import { safePathJoin, assertNoSymlinkEscape, PathTraversalError, ForbiddenPathError, isForbiddenPath, safeFilenameForId } from '@theokit/sdk/path-safety';
@@ -2625,6 +2625,86 @@ function createUpdatePlanTool() {
     }
   });
 }
+var MEDIA_TYPES = /* @__PURE__ */ new Map([
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"]
+]);
+var DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+var json = (result) => JSON.stringify(result);
+function createViewImageTool(options) {
+  const { projectRoot } = options;
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_IMAGE_BYTES;
+  return Tool.create({
+    name: options.name ?? "view_image",
+    description: options.description ?? "Read an image file from the project and show it to the model. Supports png, jpeg, gif and webp.",
+    inputSchema: z.object({
+      path: z.string().describe("Path to the image, relative to the project root.")
+    }),
+    handler: (input) => {
+      const refused = checkPathScope(input.path, projectRoot);
+      if (refused !== null) return refused;
+      if (isForbiddenAtAnyDepth(input.path)) {
+        return json({ ok: false, error: "path_traversal", path: input.path });
+      }
+      const mediaType = MEDIA_TYPES.get(extname(input.path).toLowerCase());
+      if (mediaType === void 0) {
+        return json({
+          ok: false,
+          error: "unsupported_image_type",
+          path: input.path,
+          supported: [...MEDIA_TYPES.keys()]
+        });
+      }
+      const absolute = safePathJoin(projectRoot, input.path);
+      let bytes;
+      try {
+        bytes = statSync(absolute).size;
+      } catch {
+        return json({ ok: false, error: "not_found", path: input.path });
+      }
+      if (bytes > maxBytes) {
+        return json({
+          ok: false,
+          error: "image_too_large",
+          path: input.path,
+          bytes,
+          limit_bytes: maxBytes
+        });
+      }
+      return json({
+        ok: true,
+        path: input.path,
+        media_type: mediaType,
+        bytes,
+        data: readFileSync(absolute).toString("base64")
+      });
+    },
+    /**
+     * Turn a successful read into an image block.
+     *
+     * A failed read stays TEXT on purpose: the model needs to read "not_found" and try another path,
+     * and an error is not something to look at.
+     */
+    toModelOutput: (output) => {
+      let result;
+      try {
+        result = JSON.parse(output);
+      } catch {
+        return output;
+      }
+      if (result.ok !== true) return output;
+      return [
+        {
+          type: "image",
+          source: { type: "base64", media_type: result.media_type, data: result.data }
+        }
+      ];
+    }
+  });
+}
 var DEFAULT_TIMEOUT_MS4 = 3e4;
 var MAX_BODY_BYTES = 1 * 1024 * 1024;
 function createWebFetchTool(opts) {
@@ -2766,8 +2846,8 @@ function createBraveWebSearchAdapter(opts = {}) {
       headers: { "X-Subscription-Token": apiKey, Accept: "application/json" }
     });
     if (!res.ok) throw new Error(`brave_search_failed: HTTP ${res.status}`);
-    const json = await res.json();
-    const results = json?.web?.results ?? [];
+    const json2 = await res.json();
+    const results = json2?.web?.results ?? [];
     return results.map((r) => ({
       title: String(r?.title ?? ""),
       url: String(r?.url ?? ""),
@@ -2927,6 +3007,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, ContextMatchError, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, 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