@linxiraos/zeta 1.0.4 → 1.0.6

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

@@ -0,0 +1,39 @@
+/**
+ * Result submission tool for subagent output.
+ *
+ * Subagents can call this tool incrementally or terminally depending on `type`.
+ */
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@linxiraos/pi-agent-core";
+import type { TSchema } from "@linxiraos/pi-ai/types";
+import type { ToolSession } from "./index.js";
+export interface YieldDetails {
+    /** Successful result payload, or omitted when `useLastTurn` requests last-turn extraction. */
+    data?: unknown;
+    status: "success" | "aborted";
+    error?: string;
+    /** Optional result section/classification supplied by the yield caller. */
+    type?: string | string[];
+    /** True when the caller intentionally omitted success data so the executor uses the last assistant turn. */
+    useLastTurn?: boolean;
+    /**
+     * 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;
+    readonly name = "yield";
+    readonly approval: "read";
+    readonly label = "Submit Result";
+    readonly description: string;
+    readonly parameters: TSchema;
+    strict: boolean;
+    readonly intent: "omit";
+    lenientArgValidation: boolean;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: unknown, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<YieldDetails>, _context?: AgentToolContext): Promise<AgentToolResult<YieldDetails>>;
+}

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,10 @@
+export * from "./downloader.js";
+export * from "./models.js";
+export * from "./runtime.js";
+export * from "./speakable.js";
+export * from "./speech-enhancer.js";
+export * from "./tts-client.js";
+export * from "./tts-protocol.js";
+export * from "./tts-worker.js";
+export * from "./vocalizer.js";
+export * from "./wav.js";

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

@@ -0,0 +1,82 @@
+import type { TinyModelDtype } from "../tiny/dtype.js";
+/**
+ * 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;

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

@@ -0,0 +1,47 @@
+/**
+ * Streaming markdown → speakable-segment transform for assistant speech.
+ *
+ * Sits between the assistant's raw streaming text deltas and the TTS engine,
+ * deciding both *what* is worth speaking and *when* a piece of text is ready
+ * to synthesize. Three passes:
+ *
+ * 1. Block pass (per character, stateful): drops fenced code blocks and table
+ *    rows, strips heading/bullet/blockquote markers (numbered-list markers are
+ *    spoken as "1, …"), and turns newlines into hard segment breaks.
+ * 2. Segmentation (stateful): emits a segment the moment a sentence boundary
+ *    appears — no next-sentence confirmation, which is what made the previous
+ *    engine-side splitter stall a full sentence behind generation. The first
+ *    segment cuts early at a clause boundary for fast time-to-first-audio, and
+ *    over-long unpunctuated runs are force-split so no segment exceeds the
+ *    synthesizer's input budget.
+ * 3. Inline normalization (per segment): markdown links speak their label,
+ *    bare URLs speak their host, inline-code ticks and emphasis markers are
+ *    stripped, multi-directory file paths collapse to their basename, HTML
+ *    tags are dropped, and whitespace is collapsed. Segments with no letters
+ *    or digits left are not spoken at all.
+ *
+ * Pure and synchronous — the vocalizer owns timers (idle flush) and the
+ * session lifecycle, so this class stays trivially unit-testable.
+ */
+/**
+ * One per utterance. Feed raw assistant deltas through {@link push}; each call
+ * returns the segments that became ready to speak. {@link flush} drains the
+ * remainder at message end; {@link flushIdle} drains it when generation stalls
+ * mid-sentence so speech doesn't sit on buffered text through a tool call.
+ */
+export declare class SpeakableStream {
+    #private;
+    /** Consume a raw delta; returns segments now ready to speak, in order. */
+    push(delta: string): string[];
+    /** Message end: drain everything left, including a trailing partial sentence. */
+    flush(): string[];
+    /**
+     * Generation stalled (tool call, thinking block): speak what we have rather
+     * than sit silent on buffered text. Keeps block state so the stream resumes
+     * afterwards, and refuses stubby mid-sentence fragments — the buffer must be
+     * a complete thought (trailing sentence punctuation) or at least
+     * {@link MIN_SEGMENT} long, so a stall right after "The" stays silent
+     * instead of turning into choppy one-word speech.
+     */
+    flushIdle(): string[];
+}

package/dist/types/tts/speech-enhancer.d.ts

@@ -0,0 +1,46 @@
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { Settings } from "../config/settings.js";
+/** Session-scoped dependencies; mirrors the auto-thinking classifier's deps. */
+export interface SpeechEnhancerDeps {
+    settings: Settings;
+    registry: ModelRegistry;
+    sessionId: string;
+    metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
+}
+/**
+ * Rewrites one markdown block into spoken prose via the tiny/smol role.
+ * Constructed per session by the event controller and handed to the vocalizer.
+ */
+export declare class SpeechEnhancer {
+    #private;
+    constructor(deps: SpeechEnhancerDeps);
+    /**
+     * Rewrite `block` for speech. Returns the spoken text (empty string when
+     * the model judged the block unspeakable — pure code/markup), or null when
+     * the rewrite failed, timed out, or no model/key resolved; the caller then
+     * falls back to mechanical normalization.
+     */
+    rewrite(block: string, signal?: AbortSignal): Promise<string | null>;
+}
+/**
+ * Fence-aware paragraph accumulator over raw streaming deltas. One instance
+ * per utterance.
+ */
+export declare class BlockAccumulator {
+    #private;
+    /** Feed a delta; returns the blocks it completed, in order. */
+    push(delta: string): string[];
+    /**
+     * Message end: drain everything. An unterminated code fence is dropped from
+     * its opening line onward (a truncated block is never worth speaking); the
+     * prose before it still comes out.
+     */
+    flush(): string | null;
+    /**
+     * Generation stalled: drain the pending partial block — unless we are
+     * inside a code fence, where the only thing buffered is code and speaking
+     * or rewriting half a fence would re-introduce vocalized code. Fence state
+     * is preserved so the eventual closing fence still matches.
+     */
+    flushPartial(): string | null;
+}

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

@@ -0,0 +1,21 @@
+/** Output gain applied while the user speaks over assistant audio. */
+export declare const DUCK_GAIN = 0.25;
+/**
+ * One native gapless playback session. Call {@link start}, enqueue mono `f32`
+ * chunks with {@link write}, then {@link end} to drain or {@link stop} to abort.
+ */
+export declare class StreamingAudioPlayer {
+    #private;
+    /** Opens the default speaker at the stream's logical sample rate. */
+    start(sampleRate?: number): void;
+    /** Queues one mono `f32` PCM chunk without copying it in TypeScript. */
+    write(pcm: Float32Array): void;
+    /** Applies gain at render time, including to samples already queued natively. */
+    setGain(gain: number): void;
+    /** Closes input and resolves after every queued sample reaches the speaker. */
+    end(): Promise<void>;
+    /** Stops immediately and discards queued audio. Safe to call repeatedly. */
+    stop(): void;
+}
+/** Creates the single-use player used by the speech vocalizer. */
+export declare function createStreamingPlayer(): StreamingAudioPlayer;

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

@@ -0,0 +1,69 @@
+import { type RefCountedWorkerHandle, type SpawnedSubprocess } from "../subprocess/worker-client.js";
+import type { TtsProgressEvent, TtsWorkerInbound, TtsWorkerOutbound } from "./tts-protocol.js";
+/** Decoded PCM returned by a local synthesis request. */
+export interface TtsAudio {
+    pcm: Float32Array;
+    sampleRate: number;
+}
+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 segment of a streaming session, in emission order. */
+export interface TtsAudioChunk {
+    index: number;
+    text: string;
+    pcm: Float32Array;
+    sampleRate: number;
+}
+/**
+ * A live streaming-synthesis session. Feed complete speakable segments with
+ * {@link push} (the worker synthesizes each push as-is) and close the input
+ * with {@link end}; `chunks` yields each segment'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 = "__omp_worker_tts";
+/**
+ * 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<TtsWorkerOutbound>;
+export declare class TtsClient {
+    #private;
+    constructor(spawnWorker?: () => RefCountedWorkerHandle<TtsWorkerInbound, TtsWorkerOutbound>);
+    onProgress(listener: (event: TtsProgressEvent) => void): () => void;
+    synthesize(modelKey: string, text: string, options?: TtsSynthesizeOptions): Promise<TtsAudio | null>;
+    /**
+     * Open a streaming-synthesis session. Complete speakable segments are fed
+     * through the returned handle's `push`/`end`; audio is emitted one segment
+     * 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>;

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

@@ -0,0 +1,102 @@
+import type { TtsLocalModelKey } from "./models.js";
+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;
+    /**
+     * Send and resolve once the message has drained into the IPC channel.
+     * Streaming synthesis awaits this per audio chunk: ONNX inference blocks
+     * the worker's event loop for seconds at a time, so fire-and-forget sends
+     * queue unflushed until the session ends and arrive as one burst.
+     */
+    sendAndFlush(message: TtsWorkerOutbound): Promise<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.js";
+export declare function startTtsWorker(transport: TtsTransport): void;

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

@@ -0,0 +1,59 @@
+import { type SpeechEnhancer } from "./speech-enhancer.js";
+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);
+    /** Wire (or drop) the per-session enhanced-rewrite service. */
+    setEnhancer(enhancer: SpeechEnhancer | null): void;
+    /**
+     * Suppress new vocalization until the returned idempotent release function runs.
+     * Existing synthesis and playback stop immediately; nested scopes release independently.
+     */
+    suspend(): () => void;
+    /**
+     * Stream a delta of assistant text into the pipeline. No-op when
+     * vocalization is disabled. The synthesis session (worker, player) is only
+     * opened once the first speakable segment exists, so a reply that
+     * normalizes to silence (pure code, tables, URLs) costs nothing. The
+     * trailing partial is flushed by {@link flush} or the idle timer. The
+     * pipeline (enhanced vs mechanical) is latched per utterance.
+     */
+    pushDelta(text: string): void;
+    /**
+     * Close the current input stream (call at message/turn end). Drains the
+     * trailing partial as final segments; in enhanced mode the session ends
+     * only after the last in-flight rewrite has pushed, while the next
+     * utterance may already be streaming.
+     */
+    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 every utterance, killing in-flight playback, synthesis,
+     * and rewrites (new turn / user message / Esc interrupt). Audio stops at once.
+     */
+    clear(): void;
+    /**
+     * True while any utterance is still audible or synthesizing — a live
+     * player, an unfinished stream handle, or an in-flight rewrite is enough.
+     * Callers (Esc handler) treat this as the "silence me" signal.
+     */
+    isSpeaking(): boolean;
+    /** 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

@@ -0,0 +1,47 @@
+import { type Theme } from "../modes/theme/theme.js";
+export interface CodeCellOptions {
+    code: string;
+    language?: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    codeMaxLines?: number;
+    /**
+     * Show the LAST `codeMaxLines` rows (the live streaming edge) instead of the
+     * first, with a "… N earlier lines" marker on top. Lets a pending preview
+     * follow code as it is written while staying bounded. Ignored when `expanded`.
+     */
+    codeTail?: boolean;
+    expanded?: boolean;
+    /**
+     * Prefix the header with the cell's language icon (resolved through the
+     * active symbol preset: nerd-font devicon, unicode emoji, or ascii
+     * shorthand). Opt-in so only the eval kernel renderer labels each cell;
+     * read/write/browser code cells stay icon-free.
+     */
+    showLanguage?: boolean;
+    width: number;
+    codeStartLine?: number;
+    codeLineNumbers?: Array<number | null>;
+}
+export declare function renderCodeCell(options: CodeCellOptions, theme: Theme): string[];
+export interface MarkdownCellOptions {
+    content: string;
+    index?: number;
+    total?: number;
+    title?: string;
+    status?: "pending" | "running" | "warning" | "complete" | "error";
+    spinnerFrame?: number;
+    duration?: number;
+    output?: string;
+    outputMaxLines?: number;
+    contentMaxLines?: number;
+    expanded?: boolean;
+    width: number;
+}
+export declare function renderMarkdownCell(options: MarkdownCellOptions, theme: Theme): string[];

package/dist/types/tui/file-list.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Render file listings with optional icons and metadata.
+ */
+import type { Theme } from "../modes/theme/theme.js";
+export interface FileEntry {
+    path: string;
+    /** Absolute filesystem path. When provided together with {@link FileListOptions.hyperlinkFn}, the
+     * rendered path text is wrapped in an OSC 8 hyperlink. */
+    absPath?: string;
+    isDirectory?: boolean;
+    meta?: string;
+}
+export interface FileListOptions {
+    files: FileEntry[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    showIcons?: boolean;
+    /** When provided, called with the entry's absolute path and the ANSI-styled display string to
+     * optionally wrap the path in an OSC 8 hyperlink. Only invoked when {@link FileEntry.absPath} is set. */
+    hyperlinkFn?: (absPath: string, displayText: string) => string;
+}
+export declare function renderFileList(options: FileListOptions, theme: Theme): string[];

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

@@ -0,0 +1,61 @@
+/**
+ * Returns true when OSC 8 hyperlinks should be emitted.
+ *
+ * Respects `tui.hyperlinks` setting:
+ * - `"off"`: never
+ * - `"auto"`: when `process.stdout.isTTY`, `NO_COLOR` is unset, and the detected terminal reports hyperlink support
+ * - `"always"`: unconditionally (useful for viewers that support OSC 8 without advertising it)
+ * Before settings initialization, returns false so early render paths stay plain text.
+ */
+export declare function isHyperlinkEnabled(): boolean;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at `uri`.
+ *
+ * Returns `displayText` unchanged when hyperlinks are disabled, `uri` contains
+ * terminal control bytes, or `displayText` already contains an OSC 8 sequence.
+ */
+export declare function uriHyperlink(uri: string, displayText: string): string;
+/**
+ * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL.
+ * `www.example.com` inputs are linked as `https://www.example.com`.
+ */
+export declare function urlHyperlink(url: string, displayText: string): string;
+/**
+ * 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 before settings initialization or
+ * 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.
+ *
+ * @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(filePath: string, displayText: string, opts?: {
+    line?: number;
+    col?: number;
+}): string;
+/**
+ * Synchronously resolve a filesystem-backed internal URL (e.g. `local://foo.md`,
+ * `memory://root/notes.md`) to its absolute filesystem path. Returns `undefined`
+ * for inputs that aren't fs-backed, aren't resolvable in the current session
+ * registry, or fail to parse.
+ *
+ * Used by renderers to wrap fs-backed internal URLs in OSC 8 hyperlinks even
+ * when the resolved path isn't yet available from tool result details (e.g.
+ * during the call/streaming phase before a result lands).
+ *
+ * Async-resolved schemes (`artifact://`, `agent://`, `skill://`, `rule://`,
+ * `omp://`) are not handled here — those rely on `details.resolvedPath` set
+ * by the read tool's router resolution.
+ */
+export declare function tryResolveInternalUrlSync(input: string): string | undefined;