@theokit/sdk-tools 0.27.6 → 0.29.0

package/dist/index.d.cts

@@ -2,6 +2,8 @@ import { CustomTool, ConfigurationError } from '@theokit/sdk';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
 import { SandboxProvider } from '@theokit/sdk/sandbox';
 import { InteractiveProvider } from '@theokit/sdk/interactive';
+import { W as WebSearchCallback } from './web-search-CE82zZVl.cjs';
+export { C as CreateWebSearchToolOptions, a as WebSearchResult, c as createWebSearchTool } from './web-search-CE82zZVl.cjs';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -1279,6 +1281,113 @@ interface CreateShellToolOptions {
  */
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 
+/**
+ * `text_to_speech` — turns text into an audio file inside the project root.
+ *
+ * The audio comes from a `synthesize` callback the consumer injects (the `web_search` pattern): the
+ * tool holds no key and opens no socket. The clip is written to `outputDir` below `projectRoot`
+ * under the same confinement `view_image` and `read_file` carry, and the model receives the
+ * relative path, the mime type and the byte count, never the audio itself: a model cannot listen
+ * to it, and a base64 clip at the default ceiling would be about 13 MB of context text.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, path, mime_type, bytes }`
+ *   - `{ ok: false, error }` with `error` one of `path_traversal`, `text_too_large`,
+ *     `synthesis_failed`, `unsupported_audio_type`, `empty_audio`, `audio_too_large`, `write_failed`
+ *
+ * Nothing is written on any failure, and a refused path or an oversize text never reaches the
+ * provider.
+ *
+ * Limits, accepted and stated: the confinement is checked before the write and again after the
+ * output directory is created, but a symlink swapped in by another process between that check and
+ * the rename is not caught (the same-user race the sibling tools leave open). A clip is written with
+ * mode 0o600. A chosen `filename`, or a default stem two texts happen to share (32 bits of the
+ * text's sha256), replaces the existing file of that name. `synthesis_failed` carries the provider's
+ * own message on purpose: the provider is the consumer's code, and its words are what the model
+ * needs to explain the failure; `write_failed` carries only the errno code, since a file-system
+ * message names the host's absolute paths.
+ */
+
+/** Default ceiling on the text sent to the provider, in UTF-16 code units. A default, not a measured limit. */
+declare const DEFAULT_MAX_TEXT_CHARS = 4096;
+/** Default ceiling on the clip written to disk: 10 MiB, by analogy with `DEFAULT_MAX_IMAGE_BYTES`. */
+declare const DEFAULT_MAX_AUDIO_BYTES: number;
+/** What the provider returns: the encoded clip and its mime type. */
+interface SynthesizedAudio {
+    audio: Uint8Array;
+    mimeType: string;
+}
+/**
+ * The speech provider {@link createTextToSpeechTool} calls.
+ *
+ * Reject the promise to signal a failed synthesis: the tool turns a rejection into
+ * `{ ok: false, error: "synthesis_failed", message }` and never lets it escape into the agent turn.
+ */
+type TextToSpeechCallback = (text: string) => Promise<SynthesizedAudio>;
+/** Options for {@link createTextToSpeechTool}. `synthesize` and `projectRoot` are required. */
+interface CreateTextToSpeechToolOptions {
+    /** Speech provider callback — the consumer injects the implementation. */
+    synthesize: TextToSpeechCallback;
+    /** Root the tool writes under. Every path is resolved inside it. */
+    projectRoot: string;
+    /** Directory for the clips, relative to `projectRoot`. Omitted ⇒ `audio`. Created when absent. */
+    outputDir?: string;
+    /** Name exposed to the model. Omitted ⇒ `text_to_speech`. The name is a contract: the approval
+     *  key, what the model sees and what telemetry records. */
+    name?: string;
+    /** Description exposed to the model. Omitted ⇒ the literal below. */
+    description?: string;
+    /** Longest text sent to the provider. Omitted ⇒ {@link DEFAULT_MAX_TEXT_CHARS}. */
+    maxTextChars?: number;
+    /** Largest clip written. Omitted ⇒ {@link DEFAULT_MAX_AUDIO_BYTES}. A clip of exactly this size fits. */
+    maxAudioBytes?: number;
+}
+type TextToSpeechFailure = {
+    ok: false;
+    error: "path_traversal";
+    path: string;
+} | {
+    ok: false;
+    error: "text_too_large";
+    chars: number;
+    max_chars: number;
+} | {
+    ok: false;
+    error: "synthesis_failed";
+    message: string;
+} | {
+    ok: false;
+    error: "unsupported_audio_type";
+    mime_type: string;
+} | {
+    ok: false;
+    error: "empty_audio";
+} | {
+    ok: false;
+    error: "audio_too_large";
+    bytes: number;
+    max_bytes: number;
+} | {
+    ok: false;
+    error: "write_failed";
+    message: string;
+};
+/** The tool's result, before it is serialised to the JSON string the handler returns. */
+type TextToSpeechResult = {
+    ok: true;
+    path: string;
+    mime_type: string;
+    bytes: number;
+} | TextToSpeechFailure;
+/**
+ * Build the `text_to_speech` tool over a caller-supplied provider.
+ *
+ * Order of checks: the text length, then the path (stem and output directory), then the provider,
+ * then the mime table, the empty and size checks, then the write. A refused path or an oversize
+ * text never reaches the provider, and no failure leaves a file behind.
+ */
+declare function createTextToSpeechTool(opts: CreateTextToSpeechToolOptions): CustomTool;
+
 /**
  * `todolist` — in-session task tracking for multi-step work.
  *
@@ -1607,64 +1716,6 @@ interface CreateWebFetchToolOptions {
  */
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
-/**
- * `web_search` — built-in tool for coding agents.
- *
- * Accepts a search callback via DIP (consumer provides the search
- * provider). The tool itself is provider-agnostic.
- *
- * Return shape (always a JSON string):
- *   - `{ ok: true, results: Array<{ title, url, snippet }> }`
- *   - `{ ok: false, error: 'search_failed' | 'no_provider' }`
- */
-
-interface WebSearchResult {
-    title: string;
-    url: string;
-    snippet: string;
-}
-/**
- * The search provider {@link createWebSearchTool} calls.
- *
- * `maxResults` is what the caller asked for, not a limit you must enforce — the tool slices the array
- * itself — but returning far more than asked wastes the round trip that produced them.
- *
- * Reject the promise to signal a failed search: the tool turns a rejection into
- * `{ ok: false, error: "search_failed" }` and never lets it escape into the agent turn. Resolving
- * with `[]` says something different — that the search ran and found nothing.
- */
-type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
-/**
- * Options for {@link createWebSearchTool}. `search` is required: the tool ships no provider of its
- * own, and the two adapters in this package — {@link createBraveWebSearchAdapter} and
- * {@link createGenericHttpSearchAdapter} — exist to fill it.
- */
-interface CreateWebSearchToolOptions {
-    /** M76 — name exposed to the model. Omitted => today's literal (additive). The name is a contract:
-     *  the approval key, what the model sees and what telemetry records. */
-    name?: string;
-    /** M76 — description exposed to the model. Omitted => today's literal (additive). */
-    description?: string;
-    /** Search provider callback — consumer injects the implementation. */
-    search: WebSearchCallback;
-    /** Default max results if not specified by the LLM. */
-    defaultMaxResults?: number;
-}
-/**
- * Build the `web_search` tool over a caller-supplied provider.
- *
- * The tool holds no API key and talks to no service; everything network-facing lives in the `search`
- * callback, which is why one tool serves Brave, a self-hosted endpoint, or a fixture in a test. Use
- * it to find pages and `web_fetch` to read one — results carry a snippet, not a body.
- *
- * The model's `max_results` (1..20) wins over `defaultMaxResults`, and the list is sliced to it even
- * when the provider returns more. A rejecting provider yields `{ ok: false, error: "search_failed" }`
- * with its message attached; a provider resolving `[]` yields `{ ok: true, results: [] }`. The two
- * are different signals, so an adapter that swallows its own failures — as
- * {@link createGenericHttpSearchAdapter} deliberately does — reports the first as the second.
- */
-declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
-
 /**
  * Brave Search adapter for `createWebSearchTool` (M3-7).
  *
@@ -1805,4 +1856,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 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 };
+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 CreateTextToSpeechToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, 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 SynthesizedAudio, type TextToSpeechCallback, type TextToSpeechResult, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, WebSearchCallback, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTextToSpeechTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, 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

@@ -2,6 +2,8 @@ import { CustomTool, ConfigurationError } from '@theokit/sdk';
 import { FilesystemProvider } from '@theokit/sdk/filesystem';
 import { SandboxProvider } from '@theokit/sdk/sandbox';
 import { InteractiveProvider } from '@theokit/sdk/interactive';
+import { W as WebSearchCallback } from './web-search-CE82zZVl.js';
+export { C as CreateWebSearchToolOptions, a as WebSearchResult, c as createWebSearchTool } from './web-search-CE82zZVl.js';
 
 /**
  * `apply_patch` — built-in tool for coding agents.
@@ -1279,6 +1281,113 @@ interface CreateShellToolOptions {
  */
 declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
 
+/**
+ * `text_to_speech` — turns text into an audio file inside the project root.
+ *
+ * The audio comes from a `synthesize` callback the consumer injects (the `web_search` pattern): the
+ * tool holds no key and opens no socket. The clip is written to `outputDir` below `projectRoot`
+ * under the same confinement `view_image` and `read_file` carry, and the model receives the
+ * relative path, the mime type and the byte count, never the audio itself: a model cannot listen
+ * to it, and a base64 clip at the default ceiling would be about 13 MB of context text.
+ *
+ * Return shape (always a JSON string):
+ *   - `{ ok: true, path, mime_type, bytes }`
+ *   - `{ ok: false, error }` with `error` one of `path_traversal`, `text_too_large`,
+ *     `synthesis_failed`, `unsupported_audio_type`, `empty_audio`, `audio_too_large`, `write_failed`
+ *
+ * Nothing is written on any failure, and a refused path or an oversize text never reaches the
+ * provider.
+ *
+ * Limits, accepted and stated: the confinement is checked before the write and again after the
+ * output directory is created, but a symlink swapped in by another process between that check and
+ * the rename is not caught (the same-user race the sibling tools leave open). A clip is written with
+ * mode 0o600. A chosen `filename`, or a default stem two texts happen to share (32 bits of the
+ * text's sha256), replaces the existing file of that name. `synthesis_failed` carries the provider's
+ * own message on purpose: the provider is the consumer's code, and its words are what the model
+ * needs to explain the failure; `write_failed` carries only the errno code, since a file-system
+ * message names the host's absolute paths.
+ */
+
+/** Default ceiling on the text sent to the provider, in UTF-16 code units. A default, not a measured limit. */
+declare const DEFAULT_MAX_TEXT_CHARS = 4096;
+/** Default ceiling on the clip written to disk: 10 MiB, by analogy with `DEFAULT_MAX_IMAGE_BYTES`. */
+declare const DEFAULT_MAX_AUDIO_BYTES: number;
+/** What the provider returns: the encoded clip and its mime type. */
+interface SynthesizedAudio {
+    audio: Uint8Array;
+    mimeType: string;
+}
+/**
+ * The speech provider {@link createTextToSpeechTool} calls.
+ *
+ * Reject the promise to signal a failed synthesis: the tool turns a rejection into
+ * `{ ok: false, error: "synthesis_failed", message }` and never lets it escape into the agent turn.
+ */
+type TextToSpeechCallback = (text: string) => Promise<SynthesizedAudio>;
+/** Options for {@link createTextToSpeechTool}. `synthesize` and `projectRoot` are required. */
+interface CreateTextToSpeechToolOptions {
+    /** Speech provider callback — the consumer injects the implementation. */
+    synthesize: TextToSpeechCallback;
+    /** Root the tool writes under. Every path is resolved inside it. */
+    projectRoot: string;
+    /** Directory for the clips, relative to `projectRoot`. Omitted ⇒ `audio`. Created when absent. */
+    outputDir?: string;
+    /** Name exposed to the model. Omitted ⇒ `text_to_speech`. The name is a contract: the approval
+     *  key, what the model sees and what telemetry records. */
+    name?: string;
+    /** Description exposed to the model. Omitted ⇒ the literal below. */
+    description?: string;
+    /** Longest text sent to the provider. Omitted ⇒ {@link DEFAULT_MAX_TEXT_CHARS}. */
+    maxTextChars?: number;
+    /** Largest clip written. Omitted ⇒ {@link DEFAULT_MAX_AUDIO_BYTES}. A clip of exactly this size fits. */
+    maxAudioBytes?: number;
+}
+type TextToSpeechFailure = {
+    ok: false;
+    error: "path_traversal";
+    path: string;
+} | {
+    ok: false;
+    error: "text_too_large";
+    chars: number;
+    max_chars: number;
+} | {
+    ok: false;
+    error: "synthesis_failed";
+    message: string;
+} | {
+    ok: false;
+    error: "unsupported_audio_type";
+    mime_type: string;
+} | {
+    ok: false;
+    error: "empty_audio";
+} | {
+    ok: false;
+    error: "audio_too_large";
+    bytes: number;
+    max_bytes: number;
+} | {
+    ok: false;
+    error: "write_failed";
+    message: string;
+};
+/** The tool's result, before it is serialised to the JSON string the handler returns. */
+type TextToSpeechResult = {
+    ok: true;
+    path: string;
+    mime_type: string;
+    bytes: number;
+} | TextToSpeechFailure;
+/**
+ * Build the `text_to_speech` tool over a caller-supplied provider.
+ *
+ * Order of checks: the text length, then the path (stem and output directory), then the provider,
+ * then the mime table, the empty and size checks, then the write. A refused path or an oversize
+ * text never reaches the provider, and no failure leaves a file behind.
+ */
+declare function createTextToSpeechTool(opts: CreateTextToSpeechToolOptions): CustomTool;
+
 /**
  * `todolist` — in-session task tracking for multi-step work.
  *
@@ -1607,64 +1716,6 @@ interface CreateWebFetchToolOptions {
  */
 declare function createWebFetchTool(opts?: CreateWebFetchToolOptions): CustomTool;
 
-/**
- * `web_search` — built-in tool for coding agents.
- *
- * Accepts a search callback via DIP (consumer provides the search
- * provider). The tool itself is provider-agnostic.
- *
- * Return shape (always a JSON string):
- *   - `{ ok: true, results: Array<{ title, url, snippet }> }`
- *   - `{ ok: false, error: 'search_failed' | 'no_provider' }`
- */
-
-interface WebSearchResult {
-    title: string;
-    url: string;
-    snippet: string;
-}
-/**
- * The search provider {@link createWebSearchTool} calls.
- *
- * `maxResults` is what the caller asked for, not a limit you must enforce — the tool slices the array
- * itself — but returning far more than asked wastes the round trip that produced them.
- *
- * Reject the promise to signal a failed search: the tool turns a rejection into
- * `{ ok: false, error: "search_failed" }` and never lets it escape into the agent turn. Resolving
- * with `[]` says something different — that the search ran and found nothing.
- */
-type WebSearchCallback = (query: string, maxResults: number) => Promise<WebSearchResult[]>;
-/**
- * Options for {@link createWebSearchTool}. `search` is required: the tool ships no provider of its
- * own, and the two adapters in this package — {@link createBraveWebSearchAdapter} and
- * {@link createGenericHttpSearchAdapter} — exist to fill it.
- */
-interface CreateWebSearchToolOptions {
-    /** M76 — name exposed to the model. Omitted => today's literal (additive). The name is a contract:
-     *  the approval key, what the model sees and what telemetry records. */
-    name?: string;
-    /** M76 — description exposed to the model. Omitted => today's literal (additive). */
-    description?: string;
-    /** Search provider callback — consumer injects the implementation. */
-    search: WebSearchCallback;
-    /** Default max results if not specified by the LLM. */
-    defaultMaxResults?: number;
-}
-/**
- * Build the `web_search` tool over a caller-supplied provider.
- *
- * The tool holds no API key and talks to no service; everything network-facing lives in the `search`
- * callback, which is why one tool serves Brave, a self-hosted endpoint, or a fixture in a test. Use
- * it to find pages and `web_fetch` to read one — results carry a snippet, not a body.
- *
- * The model's `max_results` (1..20) wins over `defaultMaxResults`, and the list is sliced to it even
- * when the provider returns more. A rejecting provider yields `{ ok: false, error: "search_failed" }`
- * with its message attached; a provider resolving `[]` yields `{ ok: true, results: [] }`. The two
- * are different signals, so an adapter that swallows its own failures — as
- * {@link createGenericHttpSearchAdapter} deliberately does — reports the first as the second.
- */
-declare function createWebSearchTool(opts: CreateWebSearchToolOptions): CustomTool;
-
 /**
  * Brave Search adapter for `createWebSearchTool` (M3-7).
  *
@@ -1805,4 +1856,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 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 };
+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 CreateTextToSpeechToolOptions, type CreateViewImageToolOptions, type CreateWebFetchToolOptions, type CreateWriteFileToolOptions, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, 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 SynthesizedAudio, type TextToSpeechCallback, type TextToSpeechResult, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationMode, type TruncationOptions, type TruncationResult, type VitestSummary, WebSearchCallback, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTextToSpeechTool, createTodolistTool, createUpdatePlanTool, createViewImageTool, createWebFetchTool, 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 } from 'fs/promises';
-import { dirname, relative, join, isAbsolute, extname } from 'path';
+import { rm, mkdir, writeFile, readFile, readdir, open, stat, rename } from 'fs/promises';
+import { dirname, relative, join, isAbsolute, posix, extname, basename } from 'path';
 import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
 import { safePathJoin, assertNoSymlinkEscape, PathTraversalError, ForbiddenPathError, isForbiddenPath, safeFilenameForId } from '@theokit/sdk/path-safety';
@@ -11,7 +11,7 @@ import { spawn } from 'child_process';
 import { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
-import { randomUUID } from 'crypto';
+import { randomUUID, createHash, randomBytes } from 'crypto';
 
 // src/apply-patch.ts
 
@@ -2459,6 +2459,123 @@ function formatResult(result, timeoutMs) {
     exit_code: result.exitCode
   });
 }
+var AUDIO_EXTENSIONS = /* @__PURE__ */ new Map([
+  ["audio/mpeg", "mp3"],
+  ["audio/wav", "wav"],
+  ["audio/x-wav", "wav"],
+  ["audio/ogg", "ogg"],
+  ["audio/opus", "opus"],
+  ["audio/flac", "flac"],
+  ["audio/aac", "aac"],
+  ["audio/webm", "webm"]
+]);
+var DEFAULT_MAX_TEXT_CHARS = 4096;
+var DEFAULT_MAX_AUDIO_BYTES = 10 * 1024 * 1024;
+var STEM_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+var json = (result) => JSON.stringify(result);
+var errorMessage = (err) => err instanceof Error ? err.message : String(err);
+var errorCode = (err) => err.code ?? "unknown";
+function requirePositiveInteger(name, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(
+      `createTextToSpeechTool: ${name} must be a positive integer, got ${value}`
+    );
+  }
+  return value;
+}
+function defaultStem(text) {
+  return `speech-${createHash("sha256").update(text).digest("hex").slice(0, 8)}`;
+}
+function refusePath(relativeStem, stem, projectRoot) {
+  if (!STEM_PATTERN.test(stem) || isForbiddenAtAnyDepth(relativeStem)) {
+    return json({ ok: false, error: "path_traversal", path: relativeStem });
+  }
+  return checkPathScope(relativeStem, projectRoot);
+}
+async function synthesizeSafely(synthesize, text) {
+  try {
+    const value = await synthesize(text);
+    if (!(value?.audio instanceof Uint8Array) || typeof value.mimeType !== "string") {
+      return { ok: false, error: "synthesis_failed", message: "provider returned no audio" };
+    }
+    return { audio: value.audio, mimeType: value.mimeType };
+  } catch (err) {
+    return { ok: false, error: "synthesis_failed", message: errorMessage(err) };
+  }
+}
+function checkAudio({ audio, mimeType }, maxAudioBytes) {
+  const extension = AUDIO_EXTENSIONS.get(mimeType);
+  if (extension === void 0)
+    return { ok: false, error: "unsupported_audio_type", mime_type: mimeType };
+  if (audio.length === 0) return { ok: false, error: "empty_audio" };
+  if (audio.length > maxAudioBytes) {
+    return { ok: false, error: "audio_too_large", bytes: audio.length, max_bytes: maxAudioBytes };
+  }
+  return { extension };
+}
+async function writeAtomic(target, audio) {
+  const temp = `${dirname(target)}/.${basename(target)}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(temp, audio, { flag: "wx", mode: 384 });
+    await rename(temp, target);
+  } catch (err) {
+    await rm(temp, { force: true });
+    throw err;
+  }
+}
+async function saveClip(projectRoot, outputDir, relativePath2, { audio, mimeType }) {
+  const target = safePathJoin(projectRoot, relativePath2);
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    const refused = checkPathScope(outputDir, projectRoot);
+    if (refused !== null) return refused;
+    await writeAtomic(target, audio);
+    return json({ ok: true, path: relativePath2, mime_type: mimeType, bytes: audio.length });
+  } catch (err) {
+    return json({ ok: false, error: "write_failed", message: errorCode(err) });
+  }
+}
+function createTextToSpeechTool(opts) {
+  const { synthesize, projectRoot } = opts;
+  const outputDir = posix.normalize((opts.outputDir ?? "audio").replace(/\\/g, "/"));
+  const maxTextChars = requirePositiveInteger(
+    "maxTextChars",
+    opts.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS
+  );
+  const maxAudioBytes = requirePositiveInteger(
+    "maxAudioBytes",
+    opts.maxAudioBytes ?? DEFAULT_MAX_AUDIO_BYTES
+  );
+  return Tool.create({
+    name: opts.name ?? "text_to_speech",
+    description: opts.description ?? "Turn text into spoken audio and save it as a file in the project. Use when the user asks for speech, a voice reply or an audio clip. Returns { ok, path, mime_type, bytes } with the path relative to the project root, or { ok: false, error }. The speech provider is injected by the consumer.",
+    inputSchema: z.object({
+      text: z.string().min(1).describe("The text to speak."),
+      filename: z.string().optional().describe(
+        "File name without extension (letters, digits, '.', '_', '-'). Default: derived from the text."
+      )
+    }),
+    handler: async ({ text, filename }) => {
+      if (text.length > maxTextChars) {
+        return json({
+          ok: false,
+          error: "text_too_large",
+          chars: text.length,
+          max_chars: maxTextChars
+        });
+      }
+      const stem = filename ?? defaultStem(text);
+      const refused = refusePath(posix.join(outputDir, stem), stem, projectRoot);
+      if (refused !== null) return refused;
+      const synthesized = await synthesizeSafely(synthesize, text);
+      if ("ok" in synthesized) return json(synthesized);
+      const checked = checkAudio(synthesized, maxAudioBytes);
+      if ("ok" in checked) return json(checked);
+      const relativePath2 = posix.join(outputDir, `${stem}.${checked.extension}`);
+      return saveClip(projectRoot, outputDir, relativePath2, synthesized);
+    }
+  });
+}
 
 // src/todo-plan-nodes.ts
 function todoItemsToPlanNodes(items) {
@@ -2661,7 +2778,7 @@ var MEDIA_TYPES = /* @__PURE__ */ new Map([
   [".webp", "image/webp"]
 ]);
 var DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
-var json = (result) => JSON.stringify(result);
+var json2 = (result) => JSON.stringify(result);
 function createViewImageTool(options) {
   const { projectRoot } = options;
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_IMAGE_BYTES;
@@ -2675,11 +2792,11 @@ function createViewImageTool(options) {
       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 });
+        return json2({ ok: false, error: "path_traversal", path: input.path });
       }
       const mediaType = MEDIA_TYPES.get(extname(input.path).toLowerCase());
       if (mediaType === void 0) {
-        return json({
+        return json2({
           ok: false,
           error: "unsupported_image_type",
           path: input.path,
@@ -2688,8 +2805,8 @@ function createViewImageTool(options) {
       }
       const absolute = safePathJoin(projectRoot, input.path);
       const outcome = readWithinBudget(absolute, maxBytes);
-      if (!outcome.ok) return json(failureFor(outcome, input.path, maxBytes));
-      return json({
+      if (!outcome.ok) return json2(failureFor(outcome, input.path, maxBytes));
+      return json2({
         ok: true,
         path: input.path,
         media_type: mediaType,
@@ -2886,8 +3003,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 json2 = await res.json();
-    const results = json2?.web?.results ?? [];
+    const json3 = await res.json();
+    const results = json3?.web?.results ?? [];
     return results.map((r) => ({
       title: String(r?.title ?? ""),
       url: String(r?.url ?? ""),
@@ -3047,6 +3164,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-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 };
+export { CatastrophicCommandError, ContextMatchError, DEFAULT_MAX_AUDIO_BYTES, DEFAULT_MAX_IMAGE_BYTES, DEFAULT_MAX_TEXT_CHARS, 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, createTextToSpeechTool, 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