@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/dist/types/stt/recorder.d.ts

@@ -5,9 +5,26 @@ export interface RecordingHandle {
  * Returns available recording tools in priority order.
  */
 export declare function detectRecordingTools(): string[];
+export interface ResolvedRecorder {
+    tool: "sox" | "ffmpeg" | "arecord" | "powershell";
+    bin: string;
+}
+export declare function detectRecorder(): ResolvedRecorder | null;
+/**
+ * Ensure a recorder is available, downloading the static ffmpeg binary when
+ * nothing is already present. Returns the resolved recorder.
+ */
+export declare function ensureRecorder(onProgress?: (p: {
+    stage: string;
+    percent?: number;
+}) => void, signal?: AbortSignal): Promise<ResolvedRecorder>;
 export declare function startRecording(outputPath: string): Promise<RecordingHandle>;
 /**
  * Verify a recorded audio file is usable.
  * Returns the file size in bytes, or throws.
  */
 export declare function verifyRecordingFile(filePath: string): Promise<number>;
+export interface StreamingRecordingHandle {
+    stop(): Promise<void>;
+}
+export declare function startStreamingRecording(onAudio: (samples: Float32Array) => void): Promise<StreamingRecordingHandle | null>;

package/dist/types/stt/stt-controller.d.ts

@@ -3,9 +3,15 @@ interface ToggleOptions {
     showWarning(msg: string): void;
     showStatus(msg: string): void;
     onStateChange(state: SttState): void;
+    /** Force a redraw after async edits to the composer (live segment/preview inserts). */
+    requestRender?(): void;
 }
+/** The slice of the composer editor the controller drives. */
 interface Editor {
     insertText(text: string): void;
+    setVolatileText(text: string): void;
+    clearVolatileText(): void;
+    commitVolatileText(text: string): void;
 }
 export declare class STTController {
     #private;

package/dist/types/stt/transcriber.d.ts

@@ -4,13 +4,11 @@ export interface TranscribeOptions {
     signal?: AbortSignal;
 }
 /**
- * Find a usable Python command.
- */
-export declare function resolvePython(): string | null;
-/**
- * Transcribe a WAV file using Python openai-whisper.
+ * Transcribe a WAV file using the local ONNX Whisper worker.
  *
- * Reads the WAV via Python's built-in `wave` module (no ffmpeg needed),
- * resamples to 16 kHz mono, and passes the numpy array directly to whisper.
+ * Decodes the WAV to a 16 kHz mono Float32Array in-process (no Python, no
+ * ffmpeg) and routes it to the warm speech worker, which keeps the model loaded
+ * across calls. Honors `options.signal` (abort) and applies an internal timeout
+ * with the same semantics as the previous Python path.
  */
 export declare function transcribe(audioPath: string, options?: TranscribeOptions): Promise<string>;

package/dist/types/stt/wav.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Minimal WAV (RIFF/PCM) decoder producing the Float32Array @ 16 kHz mono that
+ * transformers.js `automatic-speech-recognition` expects. Ports the decode/
+ * mono-mix/resample logic from the retired Python `transcribe.py` (which read
+ * via the stdlib `wave` module) so STT no longer shells out to Python.
+ *
+ * Supported sample formats: PCM uint8 (8-bit), int16 (16-bit), int32 (32-bit),
+ * and IEEE float32 (format tag 3). Any number of channels is mixed down to mono.
+ */
+/** transformers.js Whisper feature extractor operates at 16 kHz. */
+export declare const TARGET_SAMPLE_RATE = 16000;
+/**
+ * Resample via linear interpolation, mirroring the Python `np.interp` over
+ * `linspace(0, n-1, targetLen)` against `arange(n)`.
+ */
+export declare function resampleLinear(input: Float32Array, fromRate: number, toRate: number): Float32Array;
+/**
+ * Decode a WAV byte buffer into a 16 kHz mono Float32Array suitable for the
+ * transformers.js Whisper pipeline.
+ */
+export declare function decodeWavToMono16k(buffer: ArrayBuffer): Float32Array;
+/**
+ * Decode interleaved little-endian signed 16-bit PCM bytes into normalized
+ * [-1, 1] mono float samples. The live recorder streams raw s16le frames from
+ * sox/ffmpeg/arecord stdout (no RIFF container), so this is the hot-path
+ * counterpart to {@link decodeWavToMono16k}. `bytes` MUST be 2-byte aligned;
+ * callers buffer any trailing odd byte across chunk boundaries.
+ */
+export declare function decodePcmS16LE(bytes: Uint8Array): Float32Array;

package/dist/types/system-prompt.d.ts

@@ -78,6 +78,10 @@ export interface BuildSystemPromptOptions {
     mcpDiscoveryServerSummaries?: string[];
     /** Encourage the agent to delegate via tasks unless changes are trivial. */
     eagerTasks?: boolean;
+    /** When true, the Eager Tasks section uses the hard MUST/ONLY wording (`task.eager: always`) rather than the softer `preferred` nudge. */
+    eagerTasksAlways?: boolean;
+    /** Whether `task.batch` is enabled; gates batch-call guidance in the Eager Tasks section. */
+    taskBatch?: boolean;
     /** Rules with alwaysApply=true — their full content is injected into the prompt. */
     alwaysApplyRules?: AlwaysApplyRule[];
     /** Whether secret obfuscation is active. When true, explains the redaction format in the prompt. */

package/dist/types/task/executor.d.ts

@@ -51,6 +51,8 @@ export interface ExecutorOptions {
         content: string;
     };
     description?: string;
+    /** Specialist role/expertise for this spawn; drives the system-prompt preamble, display name, and telemetry identity. */
+    role?: string;
     index: number;
     id: string;
     parentToolCallId?: string;

package/dist/types/task/index.d.ts

@@ -1,7 +1,7 @@
 import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { ToolSession } from "..";
 import type { Theme } from "../modes/theme/theme";
-import { type AgentDefinition, type SingleResult, type TaskToolDetails, type TaskToolSchemaInstance } from "./types";
+import { type AgentDefinition, type SingleResult, type TaskItem, type TaskToolDetails, type TaskToolSchemaInstance } from "./types";
 import "../tools/review";
 import { renderResult, renderCall as renderTaskCall } from "./render";
 export { loadBundledAgents as BUNDLED_AGENTS } from "./agents";
@@ -18,6 +18,14 @@ export declare function isReadOnlyAgent(agent: AgentDefinition): boolean;
  * tell a no-op child from one that burned requests before being cancelled.
  */
 export declare function formatResultOutputFallback(result: Pick<SingleResult, "output" | "stderr" | "requests">): string;
+/**
+ * Advisory — never a rejection — nudging the spawner toward tailored
+ * specialists when it spawns generic role-less workers and still holds spawn
+ * capacity (DepthCapacity: it currently has the `task` tool). Fires when a
+ * generic `task`/`quick_task` spawn carries no `role`, or when one call clones
+ * the same agent ≥2× all without roles. Returns undefined when no nudge applies.
+ */
+export declare function buildSpecializationAdvisory(agentName: string | undefined, items: TaskItem[], depthCapacity: boolean): string | undefined;
 /**
  * Task tool - Delegate tasks to specialized agents.
  *

package/dist/types/task/types.d.ts

@@ -51,9 +51,14 @@ export interface SubagentLifecyclePayload {
      */
     detached?: boolean;
 }
+/** Display cap for a normalized one-line label (roster line, registry `displayName`, prompt field). */
+export declare const ROLE_LABEL_MAX = 80;
+/** Schema bound on the raw `role` input, before it is label-normalized at every use site. */
+export declare const ROLE_INPUT_MAX = 256;
 export declare const taskItemSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
     assignment: z.ZodString;
 }, z.core.$strip>;
 /** Single task item. Fields are optional defensively: args stream in token by token. */
@@ -62,6 +67,8 @@ export interface TaskItem {
     id?: string;
     /** UI label, not seen by the subagent. */
     description?: string;
+    /** Specialist role/expertise this subagent embodies; shapes its system-prompt identity and display name. */
+    role?: string;
     /** The work; required by the schema. */
     assignment?: string;
     /** Run this spawn in an isolated worktree (batch form; flat form carries it top-level). */
@@ -70,6 +77,7 @@ export interface TaskItem {
 export declare const taskSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
     assignment: z.ZodString;
     isolated: z.ZodOptional<z.ZodBoolean>;
     agent: z.ZodString;
@@ -77,12 +85,14 @@ export declare const taskSchema: z.ZodObject<{
 declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
     assignment: z.ZodString;
     isolated: z.ZodOptional<z.ZodBoolean>;
     agent: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
     assignment: z.ZodString;
     agent: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -91,6 +101,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
     tasks: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
         assignment: z.ZodString;
         isolated: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
@@ -100,6 +111,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
     tasks: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
         assignment: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>];
@@ -124,6 +136,8 @@ export interface TaskParams {
     id?: string;
     /** UI label (flat form), not seen by the subagent. */
     description?: string;
+    /** Specialist role/expertise this subagent embodies; shapes its system-prompt identity and display name. */
+    role?: string;
     /** The work (flat form). */
     assignment?: string;
     /** Batch form (`task.batch`): one subagent per item. */
@@ -133,6 +147,28 @@ export interface TaskParams {
     /** Run in an isolated worktree (flat form; per-item in batch form). */
     isolated?: boolean;
 }
+/**
+ * One-line, length-capped label safe for a single roster line, a registry
+ * `displayName`, or a system-prompt field. Collapses every run of whitespace
+ * AND control/format characters — including U+0085 NEL, ESC/ANSI, and the
+ * zero-width separators that `\s` misses — to a single space, then caps length.
+ * So untrusted text (a spawn `role`, a peer activity gist) can neither break the
+ * line, inject prompt structure, nor smuggle terminal escapes. Caps at `max`
+ * characters (clamped to >= 1; default `ROLE_LABEL_MAX`), appending an ellipsis when truncated.
+ */
+export declare function oneLineLabel(text: string, max?: number): string;
+/**
+ * Display name for a spawned subagent: its tailored `role` (label-normalized)
+ * when one is given, else the agent type's name. Empty/whitespace roles fall
+ * back to the agent name.
+ */
+export declare function resolveSubagentDisplayName(role: string | undefined, agentName: string): string;
+/**
+ * Whether an agent at `taskDepth` may still spawn children — i.e. it currently
+ * holds the `task` tool. Mirrors the task-tool availability gate;
+ * `maxRecursionDepth < 0` disables the cap entirely.
+ */
+export declare function canSpawnAtDepth(maxRecursionDepth: number, taskDepth: number): boolean;
 /** A code review finding reported by the reviewer agent */
 export interface ReviewFinding {
     title: string;

package/dist/types/tools/bash.d.ts

@@ -124,7 +124,7 @@ export declare function createShellRenderer<TArgs>(config: ShellRendererConfig<T
     }, uiTheme: Theme, args?: TArgs): Component;
     mergeCallAndResult: boolean;
     inline: boolean;
-    provisionalPendingPreview: boolean;
+    provisionalPendingPreview: string;
 };
 export declare const bashToolRenderer: {
     renderCall(args: BashRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component;
@@ -140,6 +140,6 @@ export declare const bashToolRenderer: {
     }, uiTheme: Theme, args?: BashRenderArgs | undefined): Component;
     mergeCallAndResult: boolean;
     inline: boolean;
-    provisionalPendingPreview: boolean;
+    provisionalPendingPreview: string;
 };
 export {};

package/dist/types/tools/eval-render.d.ts

@@ -48,6 +48,6 @@ export declare const evalToolRenderer: {
     }, uiTheme: Theme, _args?: EvalRenderArgs): Component;
     mergeCallAndResult: boolean;
     inline: boolean;
-    provisionalPendingPreview: boolean;
+    provisionalPendingPreview: string;
 };
 export {};

package/dist/types/tools/index.d.ts

@@ -17,6 +17,7 @@ import type { AgentRegistry } from "../registry/agent-registry";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
 import type { CustomMessage } from "../session/messages";
+import type { UsageStatistics } from "../session/session-entries";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
 import type { AgentOutputManager } from "../task/output-manager";
 import type { DiscoverableTool, DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
@@ -45,6 +46,8 @@ export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
 export * from "./job";
+export * from "./learn";
+export * from "./manage-skill";
 export * from "./memory-edit";
 export * from "./memory-recall";
 export * from "./memory-reflect";
@@ -97,6 +100,13 @@ export interface ToolSession {
     cwd: string;
     /** Whether UI is available */
     hasUI: boolean;
+    /**
+     * Suppress the spawn specialization/coordination advisory appended to `task`
+     * results. Set by internal/programmatic callers (e.g. the commit agent's
+     * file-analysis fan-out) whose results are consumed by code — not by a model
+     * orchestrating further spawns — so the nudge would only be noise.
+     */
+    suppressSpawnAdvisory?: boolean;
     /** Optional fetch implementation injected into the URL read pipeline (tests, proxies). Defaults to global fetch. */
     fetch?: FetchImpl;
     /** Skip Python kernel availability check and warmup */
@@ -211,7 +221,7 @@ export interface ToolSession {
     /** Goal runtime for the active agent session. */
     getGoalRuntime?: () => GoalRuntime | undefined;
     /** Get cumulative session usage statistics (input/output tokens, cost). */
-    getUsageStatistics?: () => import("../session/session-manager").UsageStatistics;
+    getUsageStatistics?: () => UsageStatistics;
     /** Current per-turn token budget {total, spent, hard} for the eval `budget` helper. */
     getTurnBudget?: () => {
         total: number | null;

package/dist/types/tools/irc.d.ts

@@ -47,6 +47,7 @@ interface IrcPeerInfo {
     parentId?: string;
     unread: number;
     lastActivity: number;
+    activity?: string;
 }
 export interface IrcDetails {
     op: "send" | "wait" | "inbox" | "list";

package/dist/types/tools/learn.d.ts

@@ -0,0 +1,51 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { z } from "zod/v4";
+import type { ToolSession } from ".";
+declare const learnSchema: z.ZodObject<{
+    memory: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    skill: z.ZodOptional<z.ZodObject<{
+        action: z.ZodEnum<{
+            create: "create";
+            update: "update";
+        }>;
+        name: z.ZodString;
+        description: z.ZodString;
+        body: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LearnParams = z.infer<typeof learnSchema>;
+/**
+ * Orchestrating "learn" tool: persists a lesson to long-term memory and,
+ * given a `skill` payload, mints/enhances a managed skill via the shared
+ * `writeManagedSkill` primitive. Gated behind `autolearn.enabled` plus a live
+ * memory backend — `hindsight`/`mnemopi` (remote/SQLite) or `local` (the
+ * file-based rollout backend, where lessons append to `learned.md`).
+ */
+export declare class LearnTool implements AgentTool<typeof learnSchema> {
+    private readonly session;
+    readonly name = "learn";
+    readonly approval: (args: unknown) => "read" | "write";
+    readonly label = "Learn";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        memory: z.ZodString;
+        context: z.ZodOptional<z.ZodString>;
+        skill: z.ZodOptional<z.ZodObject<{
+            action: z.ZodEnum<{
+                create: "create";
+                update: "update";
+            }>;
+            name: z.ZodString;
+            description: z.ZodString;
+            body: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode: "essential";
+    readonly summary = "Capture a reusable lesson to memory (and optionally a managed skill)";
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): LearnTool | null;
+    execute(_id: string, params: LearnParams): Promise<AgentToolResult>;
+}
+export {};

package/dist/types/tools/manage-skill.d.ts

@@ -0,0 +1,40 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { z } from "zod/v4";
+import type { ToolSession } from ".";
+declare const manageSkillSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        create: "create";
+        delete: "delete";
+        update: "update";
+    }>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ManageSkillParams = z.infer<typeof manageSkillSchema>;
+/**
+ * Direct create/update/delete of isolated managed skills. Gated behind
+ * `autolearn.enabled`; backend-independent (the skill side is standalone).
+ */
+export declare class ManageSkillTool implements AgentTool<typeof manageSkillSchema> {
+    readonly name = "manage_skill";
+    readonly approval: "write";
+    readonly label = "Manage Skill";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        action: z.ZodEnum<{
+            create: "create";
+            delete: "delete";
+            update: "update";
+        }>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly loadMode: "essential";
+    readonly summary = "Create, update, or delete an isolated managed skill";
+    static createIf(session: ToolSession): ManageSkillTool | null;
+    execute(_id: string, params: ManageSkillParams): Promise<AgentToolResult>;
+}
+export {};

package/dist/types/tools/plan-mode-guard.d.ts

@@ -1,7 +1,17 @@
 import type { ToolSession } from ".";
+/** Strip the hashline `[path#TAG]` wrapper from a write/edit target so the inner
+ *  filesystem path drives both authorization and resolution. Only unwraps inputs
+ *  that match the strict hashline header shape (`[path]` or `[path#XXXX]` with a
+ *  4-hex tag); anything else returns the original string so the downstream
+ *  resolver surfaces the real error. Exported for callers (e.g. `write`) that
+ *  make scheme/bridge-routing decisions before {@link resolvePlanPath} runs. */
+export declare function unwrapHashlineHeaderPath(targetPath: string): string;
 /**
  * Resolve a write/edit target to its absolute filesystem path, honoring the
  * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ * Bracketed hashline headers (`[path#TAG]`) are unwrapped first so the inner
+ * filesystem path drives resolution — keeping the plan-mode guard and the
+ * eventual write in lockstep.
  */
 export declare function resolvePlanPath(session: ToolSession, targetPath: string): string;
 /**

package/dist/types/tools/renderers.d.ts

@@ -22,17 +22,13 @@ export type ToolRenderer = {
     /** Render without background box, inline in the response flow */
     inline?: boolean;
     /**
-     * Collapsed pending preview is provisional — a tail-window or otherwise
-     * re-anchored view the result render replaces wholesale (an edit's
-     * streamed-diff tail, bash/ssh command caps, eval cells whose outputs
-     * interleave under each cell). Its rows must never commit to native
-     * scrollback mid-run; see
-     * `ToolExecutionComponent.isTranscriptBlockCommitStable`. Absent = the
-     * pending preview streams top-anchored append-shaped rows the result
-     * render preserves (task context/assignment, write content), which stay
-     * commit-eligible so a call taller than the viewport scrolls into history
-     * instead of reading as cut off.
+     * Whether pending-call rows are provisional: useful on screen while a tool is
+     * streaming, but not durable transcript history. `true` means every pending
+     * shape is provisional. `"collapsed"` means only the collapsed pending shape
+     * is provisional; expanded rendering is top-anchored/append-shaped enough to
+     * let the transcript commit its settled prefix. Absent = the pending preview
+     * streams rows the result render preserves.
      */
-    provisionalPendingPreview?: boolean;
+    provisionalPendingPreview?: boolean | "collapsed";
 };
 export declare const toolRenderers: Record<string, ToolRenderer>;

package/dist/types/tools/ssh.d.ts

@@ -65,6 +65,6 @@ export declare const sshToolRenderer: {
         renderContext?: SshRenderContext;
     }, uiTheme: Theme, args?: SshRenderArgs): Component;
     mergeCallAndResult: boolean;
-    provisionalPendingPreview: boolean;
+    provisionalPendingPreview: string;
 };
 export {};

package/dist/types/tools/todo.d.ts

@@ -4,7 +4,7 @@ import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
 export interface TodoItem {
     content: string;

package/dist/types/tools/tts.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod/v4";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 type TtsCodec = "mp3" | "wav";
+type TtsBackend = "local" | "xai";
 declare const ttsSchema: z.ZodObject<{
     text: z.ZodString;
     voice_id: z.ZodDefault<z.ZodString>;
@@ -13,6 +14,30 @@ interface TtsToolDetails {
     bytes: number;
     voiceId: string;
     codec: TtsCodec;
+    backend: TtsBackend;
 }
+/**
+ * Pick the synthesis backend. Pure for testability.
+ *
+ * - `xai` / `local` are honored verbatim (the xAI path still surfaces its own
+ *   "no credentials" error when creds are missing).
+ * - `auto` prefers the local on-device backend, except when the caller asked for
+ *   an `.mp3` and xAI credentials exist — only the cloud path can emit MP3, so we
+ *   route there to satisfy the requested container rather than substituting WAV.
+ */
+export declare function resolveTtsBackend(opts: {
+    preference: string;
+    wantsMp3: boolean;
+    hasXaiCreds: boolean;
+}): TtsBackend;
+/**
+ * Resolve the on-disk path for local synthesis. Local output is always WAV (no
+ * MP3 encoder is bundled), so an `.mp3` (or any non-`.wav`) request is rewritten
+ * to a sibling `.wav` and flagged so the tool result can note the substitution.
+ */
+export declare function resolveLocalWavPath(outputPath: string): {
+    wavPath: string;
+    substituted: boolean;
+};
 export declare const ttsTool: CustomTool<typeof ttsSchema, TtsToolDetails>;
 export {};

package/dist/types/tools/write.d.ts

@@ -46,7 +46,7 @@ export declare class WriteTool implements AgentTool<typeof writeSchema, WriteToo
     /** Stream matchers should see the real file content, not its JSON-escaped argument encoding. */
     matcherDigest(args: unknown): string | undefined;
     constructor(session: ToolSession);
-    execute(_toolCallId: string, { path, content }: WriteParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<WriteToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<WriteToolDetails>>;
+    execute(_toolCallId: string, { path: rawPath, content }: WriteParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<WriteToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<WriteToolDetails>>;
 }
 interface WriteRenderArgs {
     path?: string;

package/dist/types/tts/downloader.d.ts

@@ -0,0 +1,20 @@
+export interface TtsDownloadProgress {
+    stage: string;
+    /** Integer 0–100 download percent when known. */
+    percent?: number;
+}
+/**
+ * Whether the selected local TTS model and the side Kokoro runtime are already
+ * present. transformers.js stores `main`-revision files at
+ * `<cacheDir>/<repo>/...`, so any `.onnx` weight under the repo dir means the
+ * model weights can load without a network fetch; the Kokoro package runtime is
+ * version-keyed separately and must also exist before setup can report ready.
+ */
+export declare function isTtsModelCached(modelKey: string): Promise<boolean>;
+/**
+ * Ensure the selected local TTS model is downloaded into the transformers.js
+ * cache (and warm in the worker), streaming integer-percent Hub progress. The
+ * worker resolves the request once every model file is cached. Returns `false`
+ * if the worker is unavailable or the download failed.
+ */
+export declare function downloadTtsModel(modelKey: string, onProgress?: (progress: TtsDownloadProgress) => void, signal?: AbortSignal): Promise<boolean>;

package/dist/types/tts/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./downloader";
+export * from "./models";
+export * from "./runtime";
+export * from "./tts-client";
+export * from "./tts-protocol";
+export * from "./tts-worker";
+export * from "./vocalizer";
+export * from "./wav";

package/dist/types/tts/models.d.ts

@@ -0,0 +1,82 @@
+import type { TinyModelDtype } from "../tiny/dtype";
+/**
+ * Voice exposed by a local TTS model. Kokoro ships a fixed catalog of named
+ * voices; a voice is just a stable id (e.g. `af_heart`) plus a display label.
+ * Selection is purely on-device — generating with a different voice needs no
+ * extra network fetch once the model weights are cached.
+ */
+export interface TtsLocalVoiceSpec {
+    id: string;
+    label: string;
+}
+/**
+ * A local (on-device, ONNX) text-to-speech model the worker can load. `repo` is
+ * the Hugging Face model id loaded through `kokoro-js`
+ * (`KokoroTTS.from_pretrained`), which runs on the same `@huggingface/transformers`
+ * + `onnxruntime` runtime as the rest of the tiny-model stack and bundles the
+ * misaki/espeak phonemizer Kokoro needs. `dtype` is the default ONNX precision
+ * (overridable via `providers.tinyModelDtype`/`PI_TINY_DTYPE`).
+ */
+export interface TtsLocalModelSpec {
+    key: string;
+    repo: string;
+    dtype: TinyModelDtype;
+    /** PCM sample rate the model emits; fallback only — the worker uses the value RawAudio reports. */
+    sampleRate: number;
+    label: string;
+    description: string;
+    /** First entry is the model's default voice. */
+    voices: readonly TtsLocalVoiceSpec[];
+}
+/**
+ * Curated Kokoro-82M voice catalog. Kokoro ships ~28 voices; we surface the
+ * higher-graded ones across American/British × female/male so the picker stays
+ * useful without listing every D/F-grade sample. `af_heart` (grade A) leads and
+ * is the default voice. Grades are Kokoro's own `overallGrade` ratings.
+ */
+export declare const KOKORO_VOICES: readonly TtsLocalVoiceSpec[];
+/** Default voice within the default model — Kokoro's flagship grade-A voice. */
+export declare const DEFAULT_TTS_VOICE = "af_heart";
+/** Default local TTS model used when `tts.localModel` is unset. */
+export declare const DEFAULT_TTS_LOCAL_MODEL_KEY = "kokoro";
+/**
+ * Local TTS model registry. Kokoro-82M is the on-device SoTA tiny TTS (tops the
+ * TTS Arena leaderboard); the `onnx-community` ONNX export runs through
+ * `kokoro-js` on the shared transformers.js/onnxruntime worker. q8 keeps the
+ * weights ~100 MB and CPU inference fast while preserving quality. One model
+ * spans every voice/accent — language selection is a voice choice, not a
+ * separate download.
+ */
+export declare const TTS_LOCAL_MODELS: readonly [{
+    readonly key: "kokoro";
+    readonly repo: "onnx-community/Kokoro-82M-v1.0-ONNX";
+    readonly dtype: "q8";
+    readonly sampleRate: 24000;
+    readonly label: "Kokoro-82M";
+    readonly description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local";
+    readonly voices: readonly TtsLocalVoiceSpec[];
+}];
+export type TtsLocalModelKey = (typeof TTS_LOCAL_MODELS)[number]["key"];
+export declare const TTS_LOCAL_MODEL_VALUES: readonly ["kokoro"];
+export declare const TTS_LOCAL_MODEL_OPTIONS: readonly [{
+    readonly value: "kokoro";
+    readonly label: "Kokoro-82M";
+    readonly description: "Kokoro-82M neural TTS — SoTA on-device quality, multi-voice, fully local";
+}];
+/** Voice options for the `tts.localVoice` setting picker (default model's catalog). */
+export declare const TTS_LOCAL_VOICE_OPTIONS: ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+/** Accepted `tts.localVoice` values (default model's catalog) for schema validation. */
+export declare const TTS_LOCAL_VOICE_VALUES: readonly string[];
+export declare function getTtsLocalModelSpec(key: string): TtsLocalModelSpec | undefined;
+export declare function isTtsLocalModelKey(value: string): value is TtsLocalModelKey;
+/** Resolve a model key (or the default) to its Hugging Face repo id. */
+export declare function resolveTtsRepo(modelKey: string | undefined): string;
+/**
+ * Resolve a requested voice id to a concrete voice the model supports, falling
+ * back to the model's default voice (first entry) when the id is unknown or the
+ * legacy `"default"` sentinel. The returned id is always a valid Kokoro voice.
+ */
+export declare function resolveTtsVoice(modelKey: string | undefined, voice: string | undefined): string;