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

package/dist/types/tools/browser/tab-supervisor.d.ts

@@ -1,5 +1,6 @@
 import type { ToolSession } from "../../sdk";
-import { type BrowserHandle, type BrowserKindTag } from "./registry";
+import { CmuxTab } from "./cmux/cmux-tab";
+import { type BrowserHandle, type BrowserKindTag, type CmuxBrowserHandle, type PuppeteerBrowserHandle } from "./registry";
 import type { ReadyInfo, RunResultOk, Transferable, WorkerInbound, WorkerInitPayload, WorkerOutbound } from "./tab-protocol";
 interface WorkerHandle {
     send(msg: WorkerInbound, transferList?: Transferable[]): void;
@@ -16,17 +17,27 @@ export interface PendingRun {
     signal?: AbortSignal;
     toolCalls: Map<string, AbortController>;
 }
-export interface TabSession {
+interface TabSessionBase<TBrowser extends BrowserHandle = BrowserHandle> {
     name: string;
-    browser: BrowserHandle;
+    browser: TBrowser;
     targetId: string;
-    worker: WorkerHandle;
     state: "alive" | "dead";
     info: ReadyInfo;
     pending: Map<string, PendingRun>;
     dialogPolicy?: DialogPolicy;
     kindTag: BrowserKindTag;
 }
+export interface WorkerTabSession extends TabSessionBase<PuppeteerBrowserHandle> {
+    backend: "worker";
+    worker: WorkerHandle;
+}
+export interface CmuxTabSession extends TabSessionBase<CmuxBrowserHandle> {
+    backend: "cmux";
+    cmuxTab: CmuxTab;
+    cmuxOwnsSurface: boolean;
+    cmuxAttachedSurface?: string;
+}
+export type TabSession = WorkerTabSession | CmuxTabSession;
 export interface AcquireTabOptions {
     url?: string;
     waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
@@ -39,6 +50,7 @@ export interface AcquireTabOptions {
     signal?: AbortSignal;
     timeoutMs: number;
     dialogs?: DialogPolicy;
+    cmuxSurface?: string;
 }
 export interface AcquireTabResult {
     tab: TabSession;

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

@@ -1,9 +1,11 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from "../sdk";
 import { type BrowserKindTag } from "./browser/registry";
 import type { Observation, ScreenshotResult } from "./browser/tab-protocol";
 import type { OutputMeta } from "./output-meta";
+export { cmuxSnapshotToObservation, mapWaitUntil, resolveCmuxKind, serializeEval } from "./browser/cmux/rpc";
+export { CmuxSocketClient } from "./browser/cmux/socket-client";
 export { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./browser/readable";
 export type { Observation, ObservationEntry } from "./browser/tab-protocol";
 declare const browserSchema: z.ZodObject<{

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

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from ".";
 import type { OutputMeta } from "./output-meta";
 export interface CheckpointState {

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

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, RenderResultOptions, ToolApprovalDecision } from "@oh-my-pi/pi-agent-core";
 import { type Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { type DapBreakpointRecord, type DapContinueOutcome, type DapDataBreakpointInfoResponse, type DapDataBreakpointRecord, type DapDisassembledInstruction, type DapEvaluateResponse, type DapFunctionBreakpointRecord, type DapInstructionBreakpointRecord, type DapModule, type DapScope, type DapSessionSummary, type DapSource, type DapStackFrame, type DapThread, type DapVariable } from "../dap";
 import type { Theme } from "../modes/theme/theme";
 import type { ToolSession } from ".";

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/eval.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { EvalToolDetails } from "../eval/types";
 import type { ToolSession } from ".";
 export { EVAL_DEFAULT_PREVIEW_LINES, evalToolRenderer } from "./eval-render";

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

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { type TruncationResult } from "../session/streaming-output";

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

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolApprovalDecision } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Settings } from "../config/settings";
 import * as git from "../utils/git";
 import type { ToolSession } from ".";

package/dist/types/tools/image-gen.d.ts

@@ -1,5 +1,5 @@
 import { type Model } from "@oh-my-pi/pi-ai";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";

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

@@ -1,6 +1,6 @@
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
 import type { AgentTelemetryConfig, AgentTool } from "@oh-my-pi/pi-agent-core";
-import type { FetchImpl, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { FetchImpl, Model, ToolChoice } from "@oh-my-pi/pi-ai";
 import type { AsyncJobManager } from "../async/job-manager";
 import type { Rule } from "../capability/rule";
 import type { PromptTemplate } from "../config/prompt-templates";
@@ -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 */
@@ -173,6 +183,8 @@ export interface ToolSession {
     getModelString?: () => string | undefined;
     /** Get the current session model string, regardless of how it was chosen */
     getActiveModelString?: () => string | undefined;
+    /** Get the current session model object (provider/api capabilities), regardless of how it was chosen. */
+    getActiveModel?: () => Model | undefined;
     /** Auth storage for passing to subagents (avoids re-discovery) */
     authStorage?: import("../session/auth-storage").AuthStorage;
     /** Model registry for passing to subagents (avoids re-discovery) */
@@ -209,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/inspect-image.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { completeSimple } from "@oh-my-pi/pi-ai";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from "./index";
 declare const inspectImageSchema: z.ZodObject<{
     path: z.ZodString;

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

@@ -10,7 +10,7 @@
  */
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { type Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type IrcDeliveryReceipt, type IrcMessage } from "../irc/bus";
@@ -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/job.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import type { ToolSession } from "./index";

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/memory-edit.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from ".";
 declare const memoryEditSchema: z.ZodObject<{
     op: z.ZodEnum<{

package/dist/types/tools/memory-recall.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from ".";
 declare const memoryRecallSchema: z.ZodObject<{
     query: z.ZodString;

package/dist/types/tools/memory-reflect.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from ".";
 declare const memoryReflectSchema: z.ZodObject<{
     query: z.ZodString;

package/dist/types/tools/memory-retain.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from ".";
 declare const memoryRetainSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{

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/read.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+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";

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

@@ -1,5 +1,5 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { ToolSession } from "./index";
 declare const renderMermaidSchema: z.ZodObject<{
     mermaid: z.ZodString;

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/resolve.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import type { ToolSession } from ".";

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

@@ -6,7 +6,7 @@
  * Reviewers finish via `yield` tool with SubmitReviewDetails schema.
  */
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { Theme, ThemeColor } from "../modes/theme/theme";
 import type { ReviewFinding } from "../task/types";
 export type FindingPriority = "P0" | "P1" | "P2" | "P3";

package/dist/types/tools/search-tool-bm25.d.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { type DiscoverableTool } from "../tool-discovery/tool-index";

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

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { type TruncationResult } from "../session/streaming-output";

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

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { SSHHost } from "../capability/ssh";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
@@ -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

@@ -1,10 +1,10 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+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 * as z from "zod/v4";
+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

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type FileDiagnosticsResult } from "../lsp";
 import { type Theme } from "../modes/theme/theme";
@@ -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";