@theokit/sdk-tools 0.26.3 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.27.0
+
+### Minor Changes
+
+- c18c655: `createViewImageTool` reaches consumers.
+
+  The tool was committed on 2026-08-14, three days after `0.26.3` went to the registry, and no version
+  was cut — so the published `0.26.3` and the source at `0.26.3` were different packages. Anyone
+  resolving the range got a build without the image tool, and `@theokit/agents` could not forward what
+  its dependency did not ship.
+
+  The measurable cost: TheoCode wrote `packages/agent/src/tools/view-image.ts` by hand — the only local
+  tool in a ten-tool registry where the other nine are framework built-ins.
+
+  Note for consumers migrating off a hand-rolled equivalent: this `toModelOutput` returns the image
+  block ALONE on success, and leaves a failure as text so the model can read the reason and retry.
+  An implementation that also emitted a leading text line will change what the model receives.
+
 ## 0.26.3
 
 ### Patch Changes

package/dist/index.cjs

@@ -2627,6 +2627,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 sdk.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: zod.z.object({
+      path: zod.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(path.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 = pathSafety.safePathJoin(projectRoot, input.path);
+      let bytes;
+      try {
+        bytes = fs.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: fs.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) {
@@ -2768,8 +2848,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 ?? ""),
@@ -2931,6 +3011,7 @@ async function isBinaryFile(absolutePath) {
 
 exports.CatastrophicCommandError = CatastrophicCommandError;
 exports.ContextMatchError = ContextMatchError;
+exports.DEFAULT_MAX_IMAGE_BYTES = DEFAULT_MAX_IMAGE_BYTES;
 exports.DEFAULT_TOOL_GUIDANCE = DEFAULT_TOOL_GUIDANCE;
 exports.ReadTracker = ReadTracker;
 exports.ReasoningTools = ReasoningTools;
@@ -2959,6 +3040,7 @@ exports.createSessionArtifactStore = createSessionArtifactStore;
 exports.createShellTool = createShellTool;
 exports.createTodolistTool = createTodolistTool;
 exports.createUpdatePlanTool = createUpdatePlanTool;
+exports.createViewImageTool = createViewImageTool;
 exports.createWebFetchTool = createWebFetchTool;
 exports.createWebSearchTool = createWebSearchTool;
 exports.createWriteFileTool = createWriteFileTool;