@theokit/sdk-tools 0.26.2 → 0.27.0

package/dist/index.d.cts

@@ -130,7 +130,7 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
 
 interface CreateEditFileToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -226,15 +226,15 @@ interface CreateGitStatusToolOptions {
     maxStdoutBytes?: number;
     /**
      * Injected execution backend (`@theokit/sdk/sandbox`) — when present, `git status` runs via
-     * `SandboxBackend.execute`; omitido ⇒ o `git` local (inalterado).
+     * `SandboxBackend.execute`; omitted ⇒ the local `git` (unchanged).
      *
      * Symmetry with `createGitDiffTool`, flagged by the M76 review: without it `git_diff` would run
      * confined and `git_status` not, in the same session — and the asymmetry would be invisible until someone
-     * perceber que uma das duas escapa do sandbox.
+     * notice that one of the two escapes the sandbox.
      */
     sandbox?: SandboxProvider;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"git_status"` (additive).
      *
      * The name is a contract: the approval key, what the model sees and what telemetry records.
      */
@@ -490,7 +490,7 @@ declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
  * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
  * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
  * PowerShell is out of scope. True isolation needs a container.
- * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
+ * reference: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -616,7 +616,7 @@ declare function withShellExitGuidance(tool: CustomTool): CustomTool;
 
 interface CreateListDirToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision key —
      * three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -627,8 +627,8 @@ interface CreateListDirToolOptions {
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
     description?: string;
     /**
-     * M76 — opt-in "lista-em-qualquer-lugar": honra um `path` ABSOLUTO fora de `projectRoot`
-     * (paridade com `createReadFileTool`/`createSearchTextTool`, sandbox read-only do Codex).
+     * M76 — opt-in "list anywhere": honours an ABSOLUTE `path` outside `projectRoot`
+     * (parity with `createReadFileTool`/`createSearchTextTool`, Codex's read-only sandbox).
      *
      * The ANY-segment secret guard still applies, and is not separable: `isForbiddenPath`
      * only blocks the sensitive item when it is the FIRST segment, so a `/home/u/proj/.env/sub`
@@ -720,9 +720,9 @@ interface QuestionToolOptions {
     /**
      * Callback that presents the question to the user and resolves with the answer.
      *
-     * M76 — passou a ser OPCIONAL: o asker preferencial vem do contexto da run
+     * M76 — became OPTIONAL: the preferred asker comes from the run context
      * (`ctx.context.askUser`), because a value pinned here is the "baked into each factory" that the
-     * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
+     * `CustomTool.handler` names as the problem `ctx.context` exists to solve. This field
      * remains as a fallback, for callers building the tool with a fixed asker (backward-compatible).
      */
     askUser?: (question: string, threadId?: string) => Promise<string>;
@@ -735,11 +735,11 @@ interface QuestionToolOptions {
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"question"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"question"` (additive).
      *
      * The consumer needed this: Codex calls the tool `request_user_input`, and without the option it
      * had to rebuild the whole object by hand — the two-cast adapter T3.3
-     * eliminou.
+     * removed.
      */
     name?: string;
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
@@ -945,7 +945,7 @@ declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTo
 
 interface CreateSearchTextToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -985,7 +985,7 @@ declare function createSearchTextTool(opts: CreateSearchTextToolOptions): Custom
 
 interface CreateShellToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -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

@@ -130,7 +130,7 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
 
 interface CreateEditFileToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -226,15 +226,15 @@ interface CreateGitStatusToolOptions {
     maxStdoutBytes?: number;
     /**
      * Injected execution backend (`@theokit/sdk/sandbox`) — when present, `git status` runs via
-     * `SandboxBackend.execute`; omitido ⇒ o `git` local (inalterado).
+     * `SandboxBackend.execute`; omitted ⇒ the local `git` (unchanged).
      *
      * Symmetry with `createGitDiffTool`, flagged by the M76 review: without it `git_diff` would run
      * confined and `git_status` not, in the same session — and the asymmetry would be invisible until someone
-     * perceber que uma das duas escapa do sandbox.
+     * notice that one of the two escapes the sandbox.
      */
     sandbox?: SandboxProvider;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"git_status"` (additive).
      *
      * The name is a contract: the approval key, what the model sees and what telemetry records.
      */
@@ -490,7 +490,7 @@ declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
  * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
  * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
  * PowerShell is out of scope. True isolation needs a container.
- * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
+ * reference: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -616,7 +616,7 @@ declare function withShellExitGuidance(tool: CustomTool): CustomTool;
 
 interface CreateListDirToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision key —
      * three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -627,8 +627,8 @@ interface CreateListDirToolOptions {
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
     description?: string;
     /**
-     * M76 — opt-in "lista-em-qualquer-lugar": honra um `path` ABSOLUTO fora de `projectRoot`
-     * (paridade com `createReadFileTool`/`createSearchTextTool`, sandbox read-only do Codex).
+     * M76 — opt-in "list anywhere": honours an ABSOLUTE `path` outside `projectRoot`
+     * (parity with `createReadFileTool`/`createSearchTextTool`, Codex's read-only sandbox).
      *
      * The ANY-segment secret guard still applies, and is not separable: `isForbiddenPath`
      * only blocks the sensitive item when it is the FIRST segment, so a `/home/u/proj/.env/sub`
@@ -720,9 +720,9 @@ interface QuestionToolOptions {
     /**
      * Callback that presents the question to the user and resolves with the answer.
      *
-     * M76 — passou a ser OPCIONAL: o asker preferencial vem do contexto da run
+     * M76 — became OPTIONAL: the preferred asker comes from the run context
      * (`ctx.context.askUser`), because a value pinned here is the "baked into each factory" that the
-     * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
+     * `CustomTool.handler` names as the problem `ctx.context` exists to solve. This field
      * remains as a fallback, for callers building the tool with a fixed asker (backward-compatible).
      */
     askUser?: (question: string, threadId?: string) => Promise<string>;
@@ -735,11 +735,11 @@ interface QuestionToolOptions {
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"question"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"question"` (additive).
      *
      * The consumer needed this: Codex calls the tool `request_user_input`, and without the option it
      * had to rebuild the whole object by hand — the two-cast adapter T3.3
-     * eliminou.
+     * removed.
      */
     name?: string;
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
@@ -945,7 +945,7 @@ declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTo
 
 interface CreateSearchTextToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -985,7 +985,7 @@ declare function createSearchTextTool(opts: CreateSearchTextToolOptions): Custom
 
 interface CreateShellToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -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';
@@ -791,12 +791,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);
   });
 }
 
@@ -1584,7 +1584,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);
@@ -1597,14 +1597,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 !== "." && isForbiddenPath(relative3)) return refuse("forbidden_path");
   if (!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) {
@@ -1767,10 +1767,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;
@@ -1785,7 +1785,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,
@@ -1822,7 +1822,7 @@ function forbiddenReadError(path, allowAbsolute) {
   if (isForbiddenPath(path)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path });
   }
-  if (allowAbsolute && isAbsolute(path) && ehProibidoEmQualquerProfundidade(path)) {
+  if (allowAbsolute && isAbsolute(path) && isForbiddenAtAnyDepth(path)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path });
   }
   return null;
@@ -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