@theokit/sdk-tools 0.26.2 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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
+
+- 8790f70: Refuse a `workspace:` range before it can reach npm.
+
+  Five of this repo's twelve publishable packages declare internal dependencies as `workspace:^`, which
+  is correct on disk and becomes an unrecoverable defect if the publish goes out through a tool that
+  does not rewrite it: `pnpm` resolves the protocol while packing, `npm` ships the manifest verbatim.
+  A version published that way fails to install for everyone and cannot be corrected — only
+  deprecated.
+
+  Every publishable package now runs the guard in `prepublishOnly`, so it fires whichever way the
+  publish is invoked, and `pnpm release` runs it once across the repo before `changeset publish`.
+
+  Note for anyone reading a published manifest: the `prepublishOnly` entry points at a path inside
+  this repository. It never runs for a consumer — the hook only fires when the package itself is
+  published — and guarding the entry point that a hand-run `npm publish` actually uses was worth the
+  cosmetic wart of shipping the line.
+
 ## 0.26.2
 
 ### Patch Changes

package/dist/index.cjs

@@ -793,12 +793,12 @@ function checkPathScope(path, projectRoot) {
     throw err;
   }
 }
-var SEGMENTOS_SENSIVEIS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
-function ehProibidoEmQualquerProfundidade(path) {
+var SENSITIVE_SEGMENTS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function isForbiddenAtAnyDepth(path) {
   const segs = path.replace(/\\/g, "/").split("/").filter(Boolean);
   return segs.some((s) => {
     if (s === ".env.example") return false;
-    return SEGMENTOS_SENSIVEIS.has(s) || /^\.env\./.test(s);
+    return SENSITIVE_SEGMENTS.has(s) || /^\.env\./.test(s);
   });
 }
 
@@ -1586,7 +1586,7 @@ function createListDirTool(opts) {
     }),
     handler: async ({ path }, ctx) => {
       const relative3 = path === "" || path === "." ? "." : path;
-      const verdict = decidirEscopo(relative3, path, opts.allowAbsolute === true);
+      const verdict = decideScope(relative3, path, opts.allowAbsolute === true);
       if (verdict.error !== void 0) return verdict.error;
       if (verdict.absoluteRoot !== void 0) {
         return listViaLocalFs(verdict.absoluteRoot, ".", path, max);
@@ -1599,14 +1599,14 @@ function createListDirTool(opts) {
     }
   });
 }
-function decidirEscopo(relative3, original, allowAbsolute) {
+function decideScope(relative3, original, allowAbsolute) {
   const refuse = (error) => ({
     error: JSON.stringify({ ok: false, error, path: original })
   });
   if (relative3 !== "." && pathSafety.isForbiddenPath(relative3)) return refuse("forbidden_path");
   if (!path.isAbsolute(relative3)) return {};
   if (!allowAbsolute) return refuse("path_traversal");
-  if (ehProibidoEmQualquerProfundidade(relative3)) return refuse("forbidden_path");
+  if (isForbiddenAtAnyDepth(relative3)) return refuse("forbidden_path");
   return { absoluteRoot: relative3 };
 }
 async function listViaLocalFs(projectRoot, relative3, originalPath, max) {
@@ -1769,10 +1769,10 @@ function createPlanModeTool(options) {
 }
 
 // src/question.ts
-function askerDoContexto(context) {
+function askerFromContext(context) {
   if (typeof context !== "object" || context === null) return void 0;
-  const candidato = context.askUser;
-  return typeof candidato === "function" ? candidato : void 0;
+  const candidate = context.askUser;
+  return typeof candidate === "function" ? candidate : void 0;
 }
 function createQuestionTool(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e5;
@@ -1787,7 +1787,7 @@ function createQuestionTool(opts) {
       required: ["question"]
     },
     handler: async (input, ctx) => {
-      const askUser = askerDoContexto(ctx?.context) ?? opts.askUser;
+      const askUser = askerFromContext(ctx?.context) ?? opts.askUser;
       if (askUser === void 0) {
         return JSON.stringify({
           ok: false,
@@ -1824,7 +1824,7 @@ function forbiddenReadError(path$1, allowAbsolute) {
   if (pathSafety.isForbiddenPath(path$1)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path: path$1 });
   }
-  if (allowAbsolute && path.isAbsolute(path$1) && ehProibidoEmQualquerProfundidade(path$1)) {
+  if (allowAbsolute && path.isAbsolute(path$1) && isForbiddenAtAnyDepth(path$1)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path: path$1 });
   }
   return null;
@@ -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;