@prometheus-ai/agent 0.5.4 → 0.5.8

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 "@prometheus-ai/agent-core";
 import type { Component } from "@prometheus-ai/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";
@@ -17,6 +17,9 @@ export interface WriteToolDetails {
     meta?: OutputMeta;
     /** Set when the file was auto-chmod'd because content begins with a `#!` shebang. */
     madeExecutable?: boolean;
+    /** Absolute filesystem path the write resolved to. Used by the renderer to wrap
+     * the (possibly cwd-relative) header path in an OSC 8 `file://` hyperlink. */
+    resolvedPath?: string;
 }
 type WriteParams = WriteToolInput;
 /**
@@ -36,7 +39,6 @@ export declare class WriteTool implements AgentTool<typeof writeSchema, WriteToo
         path: z.ZodString;
         content: z.ZodString;
     }, z.core.$strip>;
-    readonly nonAbortable = true;
     readonly strict = true;
     readonly concurrency = "exclusive";
     readonly loadMode = "discoverable";
@@ -44,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;
@@ -59,6 +61,7 @@ export declare const writeToolRenderer: {
             text?: string;
         }>;
         details?: WriteToolDetails;
+        isError?: boolean;
     }, options: RenderResultOptions, uiTheme: Theme, args?: WriteRenderArgs): Component;
     mergeCallAndResult: boolean;
 };

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

@@ -10,6 +10,14 @@ export interface YieldDetails {
     data: unknown;
     status: "success" | "aborted";
     error?: string;
+    /**
+     * Set when the yield tool exhausted its in-tool schema-retry budget
+     * (MAX_SCHEMA_RETRIES) and accepted the data anyway. Surfaced so the
+     * executor's post-mortem finalizer can honor the override instead of
+     * re-rejecting the same payload with `schema_violation` — keeping the
+     * subagent's acceptance and the parent's view of the result in lockstep.
+     */
+    schemaOverridden?: boolean;
 }
 export declare class YieldTool implements AgentTool<TSchema, YieldDetails> {
     #private;

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`/`PROMETHEUS_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;

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

@@ -0,0 +1,32 @@
+export interface PlayerCommand {
+    cmd: string;
+    args: string[];
+}
+/** Injection seam for {@link playerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface PlayerLookup {
+    which?: (bin: string) => string | null;
+    ffmpeg?: () => string | null;
+}
+/**
+ * Build the ordered list of playback commands to try for `filePath` on the
+ * given platform. Pure + injectable so the selection logic is testable without
+ * spawning anything.
+ *
+ * - darwin: `afplay` (always present on macOS).
+ * - win32: PowerShell `Media.SoundPlayer.PlaySync()` (no extra deps).
+ * - linux/other POSIX: `paplay` (PulseAudio) → `aplay` (ALSA) → the bundled
+ *   static `ffmpeg` (`-f pulse` then `-f alsa`). Empty result means nothing is
+ *   available and the caller should surface an install hint.
+ */
+export declare function playerCommandsFor(platform: NodeJS.Platform, filePath: string, lookup?: PlayerLookup): PlayerCommand[];
+export interface PlayAudioOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Play `filePath` through the speakers, trying each candidate command in order
+ * and returning on the first clean exit. Throws an actionable Error if no
+ * player exists or every candidate fails (with the collected stderr).
+ */
+export declare function playAudioFile(filePath: string, options?: PlayAudioOptions): Promise<void>;
+/** Best-effort temp-file cleanup used by callers after playback. */
+export declare function removeTempFile(filePath: string): Promise<void>;

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

@@ -0,0 +1,6 @@
+export declare const KOKORO_PACKAGE = "kokoro-js";
+export declare const KOKORO_VERSION = "1.2.1";
+export declare const ONNXRUNTIME_NODE_PACKAGE = "onnxruntime-node";
+export declare const ONNXRUNTIME_NODE_VERSION = "1.26.0";
+export declare function getTtsRuntimeDir(): string;
+export declare function isTtsRuntimeCached(): Promise<boolean>;

package/dist/types/tts/streaming-player.d.ts

@@ -0,0 +1,41 @@
+import { type PlayerCommand } from "./player";
+/** Output gain applied while ducked (the user is speaking over the assistant). */
+export declare const DUCK_GAIN = 0.25;
+/** Injection seam for {@link streamingPlayerCommandsFor} — defaults to real PATH/tools lookups. */
+export interface StreamingPlayerLookup {
+    which?: (bin: string) => string | null;
+    ffmpeg?: () => string | null;
+}
+/**
+ * Ordered candidate commands for a persistent raw-PCM player on `platform`: each
+ * reads 32-bit-float little-endian mono PCM at `sampleRate` from stdin (`pipe:0`)
+ * and plays it to the default output device. An empty list means no streaming
+ * backend is available and the caller should fall back to per-file playback.
+ *
+ * - darwin: none; `afplay` is file-only, so macOS uses the interruptible
+ *   per-file fallback.
+ * - linux/other POSIX: `ffmpeg` (`-f pulse` then `-f alsa`) → `paplay`/`aplay`
+ *   raw fallbacks.
+ * - win32: none (PowerShell `SoundPlayer` is file-only).
+ */
+export declare function streamingPlayerCommandsFor(platform: NodeJS.Platform, sampleRate: number, lookup?: StreamingPlayerLookup): PlayerCommand[];
+/**
+ * Single-session gapless player. Lifecycle: {@link start} once, {@link write}
+ * chunks in order, then {@link end} to drain or {@link stop} to abort. Not
+ * reusable after stop/end — create a new instance per utterance.
+ */
+export declare class StreamingAudioPlayer {
+    #private;
+    /** Pick a backend and begin draining. Idempotent; the first call's rate wins. */
+    start(sampleRate: number): void;
+    /** Queue a mono float32 PCM chunk for playback in arrival order. */
+    write(pcm: Float32Array): void;
+    /** Scale subsequent output (1 = normal, <1 = ducked). Applies within {@link LEAD_SECONDS}. */
+    setGain(gain: number): void;
+    /** Close the input; resolves once all queued audio has finished playing. */
+    end(): Promise<void>;
+    /** Stop immediately: kill the player, drop everything still queued. */
+    stop(): void;
+}
+/** Factory the vocalizer calls; a function so tests can stub it without spawning a player. */
+export declare function createStreamingPlayer(): StreamingAudioPlayer;

package/dist/types/tts/tts-client.d.ts

@@ -0,0 +1,93 @@
+import type { Subprocess } from "bun";
+import type { TtsProgressEvent, TtsWorkerInbound, TtsWorkerOutbound } from "./tts-protocol";
+/** Decoded PCM returned by a local synthesis request. */
+export interface TtsAudio {
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * Abstraction over the TTS subprocess. The runtime implementation is a Bun child
+ * process so `onnxruntime-node`'s NAPI finalizer never runs inside the main agent
+ * address space — that destructor segfaults Bun during shutdown (issue #1606).
+ */
+interface WorkerHandle {
+    send(message: TtsWorkerInbound): void;
+    onMessage(handler: (message: TtsWorkerOutbound) => void): () => void;
+    onError(handler: (error: Error) => void): () => void;
+    /** Re-reference the subprocess so a pending request keeps the parent event loop alive. */
+    ref(): void;
+    /** Drop the reference once the worker is idle so it never blocks process exit. */
+    unref(): void;
+    terminate(): Promise<void>;
+}
+export interface TtsSynthesizeOptions {
+    voice?: string;
+    signal?: AbortSignal;
+}
+export interface TtsDownloadOptions {
+    signal?: AbortSignal;
+    onProgress?: (event: TtsProgressEvent) => void;
+}
+export interface TtsStreamOptions {
+    voice?: string;
+    signal?: AbortSignal;
+}
+/** One synthesized sentence of a streaming session, in emission order. */
+export interface TtsAudioChunk {
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * A live streaming-synthesis session. Feed text incrementally with {@link push}
+ * and close the input with {@link end}; `chunks` yields each synthesized
+ * sentence's audio as soon as it is ready, then completes once the worker
+ * finishes draining the closed input.
+ */
+export interface TtsStreamHandle {
+    push(text: string): void;
+    end(): void;
+    chunks: AsyncIterableIterator<TtsAudioChunk>;
+}
+/**
+ * Hidden subcommand on the main CLI that boots the TTS worker in the spawned
+ * subprocess. Kept in sync with the dispatch in `cli.ts` (Main-owned).
+ */
+export declare const TTS_WORKER_ARG = "__prometheus_tts_worker";
+interface SpawnedSubprocess {
+    proc: Subprocess<"ignore", "ignore", "ignore">;
+    inbound: Set<(message: TtsWorkerOutbound) => void>;
+    errors: Set<(error: Error) => void>;
+    /** Flipped to `true` right before the deliberate SIGKILL so `onExit` can tell it apart from a crash. */
+    intentionalExit: {
+        value: boolean;
+    };
+}
+/**
+ * Spawn the TTS worker as a subprocess. Exported for tests and the smoke probe;
+ * production callers go through {@link spawnTtsWorker}.
+ */
+export declare function createTtsSubprocess(): SpawnedSubprocess;
+export declare class TtsClient {
+    #private;
+    constructor(spawnWorker?: () => WorkerHandle);
+    onProgress(listener: (event: TtsProgressEvent) => void): () => void;
+    synthesize(modelKey: string, text: string, options?: TtsSynthesizeOptions): Promise<TtsAudio | null>;
+    /**
+     * Open a streaming-synthesis session. Text is fed incrementally through the
+     * returned handle's `push`/`end`; audio is emitted one synthesized sentence at
+     * a time via `chunks`, so playback can begin before the full text is known.
+     * Returns an inert handle (immediately-ended `chunks`) for unknown models or
+     * an already-aborted signal, and fails the iterator if the worker cannot spawn.
+     */
+    synthesizeStream(modelKey: string, options?: TtsStreamOptions): TtsStreamHandle;
+    downloadModel(modelKey: string, options?: TtsDownloadOptions): Promise<boolean>;
+    terminate(): Promise<void>;
+}
+export declare const ttsClient: TtsClient;
+export declare function shutdownTtsClient(): Promise<void>;
+export declare function smokeTestTtsWorker({ timeoutMs, }?: {
+    timeoutMs?: number;
+}): Promise<void>;
+export {};

package/dist/types/tts/tts-protocol.d.ts

@@ -0,0 +1,95 @@
+import type { TtsLocalModelKey } from "./models";
+export type TtsProgressStatus = "initiate" | "download" | "progress" | "progress_total" | "done" | "ready" | "error";
+export interface TtsProgressFileState {
+    loaded: number;
+    total: number;
+}
+export interface TtsProgressEvent {
+    modelKey: TtsLocalModelKey;
+    status: TtsProgressStatus;
+    name?: string;
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+    files?: Record<string, TtsProgressFileState>;
+    task?: string;
+    model?: string;
+}
+export type TtsWorkerInbound = {
+    type: "ping";
+    id: string;
+} | {
+    type: "synthesize";
+    id: string;
+    modelKey: TtsLocalModelKey;
+    text: string;
+    voice?: string;
+} | {
+    type: "download";
+    id: string;
+    modelKey: TtsLocalModelKey;
+} | {
+    type: "stream-start";
+    id: string;
+    modelKey: TtsLocalModelKey;
+    voice?: string;
+} | {
+    type: "stream-push";
+    id: string;
+    text: string;
+} | {
+    type: "stream-end";
+    id: string;
+} | {
+    type: "stream-cancel";
+    id: string;
+};
+export type TtsWorkerOutbound = {
+    type: "pong";
+    id: string;
+} | {
+    type: "audio";
+    id: string;
+    pcm: Float32Array;
+    sampleRate: number;
+} | {
+    type: "downloaded";
+    id: string;
+} | {
+    type: "error";
+    id: string;
+    error: string;
+} | {
+    type: "progress";
+    id: string;
+    event: TtsProgressEvent;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+} | {
+    type: "audio-chunk";
+    id: string;
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+} | {
+    type: "stream-done";
+    id: string;
+};
+/**
+ * Wire transport between the parent (`TtsClient`) and the local TTS subprocess.
+ * The parent owns the subprocess lifecycle (graceful work, hard SIGKILL on
+ * shutdown); the protocol carries no explicit close handshake — once the parent
+ * decides to terminate, it signals the OS to reap the child so
+ * `onnxruntime-node`'s NAPI finalizer never runs in the main agent address
+ * space (it segfaults Bun on shutdown — issue #1606). See `tts-client.ts` for
+ * the spawn/kill glue.
+ */
+export interface TtsTransport {
+    send(message: TtsWorkerOutbound): void;
+    onMessage(handler: (message: TtsWorkerInbound) => void): () => void;
+}

package/dist/types/tts/tts-worker.d.ts

@@ -0,0 +1,2 @@
+import type { TtsTransport } from "./tts-protocol";
+export declare function startTtsWorker(transport: TtsTransport): void;

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

@@ -0,0 +1,41 @@
+export interface VocalizerPlayer {
+    start(sampleRate: number): void;
+    write(pcm: Float32Array): void;
+    setGain(gain: number): void;
+    end(): Promise<void>;
+    stop(): void;
+}
+export declare class Vocalizer {
+    #private;
+    constructor(createPlayer?: () => VocalizerPlayer);
+    /**
+     * Stream a delta of assistant text into the engine. No-op when vocalization
+     * is disabled. The engine buffers the running text and emits audio for each
+     * complete sentence; the trailing partial is flushed by {@link flush}.
+     */
+    pushDelta(text: string): void;
+    /**
+     * Close the current input stream (call at message/turn end). The engine
+     * flushes its trailing partial as a final chunk; the player keeps draining
+     * queued audio until it completes.
+     */
+    flush(): void;
+    /**
+     * Speak a complete piece of text in one shot (ask questions, yield-mode final
+     * message): stream it in and immediately close the input. No-op when disabled.
+     */
+    speak(text: string): void;
+    /**
+     * Interrupt and drop the current session, killing in-flight playback and
+     * synthesis (new turn / user message / Esc interrupt). Audio stops at once.
+     */
+    clear(): void;
+    /** Lower the volume while the user is speaking (push-to-talk), so speech doesn't drown them out. */
+    duck(): void;
+    /** Restore full volume once the user stops speaking. */
+    unduck(): void;
+    /** Resolve once the playback chain has drained (tests / shutdown). */
+    idle(): Promise<void>;
+}
+/** Process-level vocalizer shared by the event controller and the ask tool. */
+export declare const vocalizer: Vocalizer;

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

@@ -0,0 +1,8 @@
+/**
+ * Assemble a mono PCM16 WAV byte buffer from Float32 PCM samples (the shape
+ * transformers.js `RawAudio` emits: normalized [-1, 1] amplitudes plus a sample
+ * rate). No external encoder is involved — we write a canonical 44-byte RIFF/
+ * WAVE header followed by little-endian signed 16-bit samples. Samples are
+ * clamped before quantization so out-of-range float values do not wrap.
+ */
+export declare function encodeWav(samples: Float32Array, sampleRate: number): Uint8Array;

package/dist/types/tui/code-cell.d.ts

@@ -18,8 +18,6 @@ export interface CodeCellOptions {
      */
     codeTail?: boolean;
     expanded?: boolean;
-    /** Animate the cell border with a sweeping segment while pending/running. */
-    animate?: boolean;
     width: number;
 }
 export declare function renderCodeCell(options: CodeCellOptions, theme: Theme): string[];

package/dist/types/tui/hyperlink.d.ts

@@ -20,20 +20,26 @@ export declare function uriHyperlink(uri: string, displayText: string): string;
  */
 export declare function urlHyperlink(url: string, displayText: string): string;
 /**
- * Wrap `displayText` in an OSC 8 hyperlink pointing at the given absolute file path.
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL,
+ * bypassing terminal capability auto-detection. Used for auth prompts where
+ * an inert "click" label blocks login on terminals whose capabilities are
+ * not advertised. Still returns plain text when the user has explicitly
+ * opted out via `tui.hyperlinks=off`.
+ */
+export declare function urlHyperlinkAlways(url: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at a filesystem path.
  *
  * Returns `displayText` unchanged when hyperlinks are disabled or when
  * the text already contains an OSC 8 sequence (prevents double-wrapping).
+ * Relative paths resolve against the current working directory before URI
+ * encoding so the OSC 8 target is always a valid `file://` URL.
  *
- * The caller is responsible for passing an absolute path. Relative paths
- * produce invalid `file://` URIs and are accepted silently to avoid runtime
- * errors in renderer hot paths.
- *
- * @param absPath - Absolute filesystem path
+ * @param filePath - Filesystem path
  * @param displayText - Text to render as the hyperlink anchor (may contain ANSI codes)
  * @param opts - Optional line/col position appended as `?line=N&col=M` query params
  */
-export declare function fileHyperlink(absPath: string, displayText: string, opts?: {
+export declare function fileHyperlink(filePath: string, displayText: string, opts?: {
     line?: number;
     col?: number;
 }): string;

package/dist/types/tui/output-block.d.ts

@@ -2,7 +2,7 @@
  * Bordered output container with optional header and sections.
  */
 import type { Component } from "@prometheus-ai/tui";
-import type { Theme } from "../modes/theme/theme";
+import type { Theme, ThemeColor } from "../modes/theme/theme";
 import type { State } from "./types";
 export interface OutputBlockOptions {
     header?: string;
@@ -10,12 +10,15 @@ export interface OutputBlockOptions {
     state?: State;
     sections?: Array<{
         label?: string;
-        lines: string[];
+        lines: readonly string[];
+        separator?: boolean;
     }>;
     width: number;
     applyBg?: boolean;
-    /** Animate the border with a sweeping dark segment (pending/running state). */
-    animate?: boolean;
+    contentPaddingLeft?: number;
+    /** Override the state-derived border color. Used for muted "legacy" tool
+     * frames that should not visually compete with framed-output tools. */
+    borderColor?: ThemeColor;
 }
 declare const FRAMED_BLOCK_COMPONENT: unique symbol;
 export type FramedBlockComponent = Component & {
@@ -23,22 +26,6 @@ export type FramedBlockComponent = Component & {
 };
 export declare function markFramedBlockComponent<T extends Component>(component: T): T & FramedBlockComponent;
 export declare function isFramedBlockComponent(component: Component): boolean;
-/**
- * Monotonic frame counter for animated borders, quantized to the TUI's ~16ms
- * render cap so the cache key advances once per ~60fps frame — fine enough for a
- * smooth segment sweep, coarse enough to coalesce multiple render passes that
- * land inside the same frame.
- */
-export declare function borderShimmerTick(): number;
-/**
- * Column of the travelling segment's center on the bottom edge for a box of
- * inner width `W` at time `now`. The segment bounces left → right → left across
- * the bottom border: a triangle wave over one full there-and-back cycle, eased
- * per leg so it slows as it nears each wall before reversing. Position is
- * derived from the wall clock against a fixed cycle, so a resize shifts the
- * center proportionally — no reset.
- */
-export declare function borderSegmentHeadCol(W: number, now: number): number;
 export declare function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[];
 /**
  * Cached wrapper around `renderOutputBlock`.
@@ -49,9 +36,16 @@ export declare function renderOutputBlock(options: OutputBlockOptions, theme: Th
  */
 export declare class CachedOutputBlock {
     #private;
-    /** Render with caching. Returns cached result if options haven't changed. */
-    render(options: OutputBlockOptions, theme: Theme): string[];
+    /** Render with caching. Returns the cached (shared, caller-immutable) lines if options haven't changed. */
+    render(options: OutputBlockOptions, theme: Theme): readonly string[];
     /** Invalidate the cache, forcing a rebuild on next render. */
     invalidate(): void;
 }
+/**
+ * Build a self-framing tool component backed by a cached output block. The
+ * `build` callback returns the block options for a given width; the cache
+ * dedupes re-renders. Pass `borderColor: "borderMuted"` for the dim "legacy"
+ * look that does not compete with the state-colored framed tools.
+ */
+export declare function framedBlock(theme: Theme, build: (width: number) => OutputBlockOptions): Component;
 export {};

package/dist/types/tui/status-line.d.ts

@@ -5,6 +5,9 @@ import type { Theme, ThemeColor } from "../modes/theme/theme";
 import type { ToolUIStatus } from "../tools/render-utils";
 export interface StatusLineOptions {
     icon?: ToolUIStatus;
+    /** Pre-rendered glyph that replaces the status icon (e.g. a magnifier for
+     * search-family tools). Takes precedence over `icon`. */
+    iconOverride?: string;
     spinnerFrame?: number;
     title: string;
     titleColor?: ThemeColor;