@promptbook/cli 0.113.0-0 → 0.113.0-10

package/umd/scripts/find-refactor-candidates/find-refactor-candidates.d.ts

@@ -15,4 +15,11 @@ export type FindRefactorCandidatesOptions = {
      * Aggressiveness level used to score candidate files.
      */
     readonly level?: RefactorCandidateLevel;
+    /**
+     * Maximum number of refactor prompts to create in this run.
+     *
+     * When more candidates are found than this limit, only the most important ones (by severity)
+     * are turned into prompts. When omitted, a prompt is created for every candidate.
+     */
+    readonly limit?: number;
 };

package/umd/scripts/find-refactor-candidates/selectMostImportantRefactorCandidates.d.ts

@@ -0,0 +1,12 @@
+import type { RefactorCandidate } from './RefactorCandidate';
+/**
+ * Keeps at most `limit` refactor candidates, preferring the most important ones.
+ *
+ * When there are more candidates than `limit`, only the highest-severity candidates are kept
+ * (ties broken by relative path for determinism). When `limit` is `undefined` or there are fewer
+ * candidates than the limit, every candidate is returned. The original input order is preserved
+ * among the kept candidates, so `limit` acts purely as a filter and never reorders prompts.
+ *
+ * @private function of findRefactorCandidates
+ */
+export declare function selectMostImportantRefactorCandidates(candidates: ReadonlyArray<RefactorCandidate>, limit: number | undefined): ReadonlyArray<RefactorCandidate>;

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/MultipleAgentAutoPuller.d.ts

@@ -0,0 +1,27 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import type { LocalAgentRunnerProjectSummary } from './LocalAgentRunnerProjectSummary';
+import type { MultiAgentAutoPullResult } from './MultiAgentAutoPullResult';
+import type { MultipleAgentRunUiPresenter } from './MultipleAgentRunUiPresenter';
+/**
+ * Owns periodic auto-pull state for watched local repositories.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class MultipleAgentAutoPuller {
+    private readonly autoPullTimestampsByProjectPath;
+    /**
+     * Pulls latest changes for watched child repositories when their idle auto-pull interval elapsed.
+     */
+    pullIfNeeded(options: {
+        readonly rootPath: string;
+        readonly runOptions: AgentRunOptions;
+        readonly uiPresenter: MultipleAgentRunUiPresenter;
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly ignoredAgentCount: number;
+    }): Promise<MultiAgentAutoPullResult>;
+    /**
+     * Records an auto-pull timestamp observed while a child runner processed one message.
+     */
+    recordAutoPullTimestamp(projectPath: string, autoPullTimestamp: number): void;
+    private pruneTimestampsForCurrentProjects;
+}

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/MultipleAgentGithubSynchronizer.d.ts

@@ -0,0 +1,26 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import type { AgentIgnoreMatcher } from '../agentIgnorePatterns';
+import type { MultipleAgentRunUiPresenter } from './MultipleAgentRunUiPresenter';
+/**
+ * Owns periodic GitHub repository synchronization state for `runMultipleAgentMessages`.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class MultipleAgentGithubSynchronizer {
+    private synchronizationTimestamp;
+    private ignoredRepositoryCount;
+    /**
+     * Number of remote repositories ignored during the last synchronization round.
+     */
+    get ignoredAgentCount(): number;
+    /**
+     * Synchronizes missing local repositories from GitHub when the owner configuration is available.
+     */
+    synchronizeIfNeeded(options: {
+        readonly rootPath: string;
+        readonly runOptions: AgentRunOptions;
+        readonly ignoreMatcher: AgentIgnoreMatcher;
+        readonly uiPresenter: MultipleAgentRunUiPresenter;
+        readonly lastObservedProjectCount: number;
+    }): Promise<void>;
+}

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/MultipleAgentRunUiPresenter.d.ts

@@ -0,0 +1,66 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import { type CoderRunUiHandle } from '../../../run-codex-prompts/ui/renderCoderRunUi';
+import type { AgentTickUiPresentation } from '../tickAgentMessages';
+import type { LocalAgentRunnerProjectSummary } from './LocalAgentRunnerProjectSummary';
+/**
+ * Owns all rich UI state projection for `runMultipleAgentMessages`.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class MultipleAgentRunUiPresenter {
+    private readonly runOptions;
+    private readonly rootPath;
+    private readonly handle;
+    private constructor();
+    /**
+     * Creates the shared multi-agent rich UI when the terminal supports it.
+     */
+    static create(runOptions: AgentRunOptions, rootPath: string): MultipleAgentRunUiPresenter;
+    /**
+     * Rich terminal UI handle, when the current process can render one.
+     */
+    get uiHandle(): CoderRunUiHandle | undefined;
+    /**
+     * Updates the shared UI while GitHub repository synchronization is running.
+     */
+    updateForGithubSynchronization(lastObservedProjectCount: number): void;
+    /**
+     * Updates the shared UI while watched child repositories are being pulled.
+     */
+    updateForAutoPull(projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>, ignoredAgentCount: number, projectSummariesToPull: ReadonlyArray<LocalAgentRunnerProjectSummary>): void;
+    /**
+     * Updates the shared UI to the idle multi-agent watch state.
+     */
+    updateForWatching(projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>, ignoredAgentCount: number): void;
+    /**
+     * Updates the shared UI while one or more child repositories are answering queued messages.
+     */
+    updateForAnswering(options: {
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly answeringProjectPaths: ReadonlySet<string>;
+        readonly ignoredAgentCount: number;
+        readonly activeMessageCount: number;
+    }): void;
+    /**
+     * Builds the multi-agent presentation passed into one active queued-message tick.
+     */
+    buildTickPresentation(options: {
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly answeringProjectPaths: ReadonlySet<string>;
+        readonly ignoredAgentCount: number;
+    }): AgentTickUiPresentation;
+    private setConfig;
+    private buildScriptPaths;
+    private createQueueProgressSnapshot;
+    private createCompletedQueueProgressSnapshot;
+    private buildStatusLines;
+    private buildStatusTableRows;
+    private formatCurrentAgentMessage;
+    private buildUserMessageLines;
+    private buildMessagePreviewSections;
+    private buildAnsweringAgentMessageLines;
+    private buildAnsweringDetailLines;
+    private buildWatchingDetailLines;
+    private buildAutoPullDetailLines;
+    private formatAgentCount;
+}

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/RunMultipleAgentMessageTaskScheduler.d.ts

@@ -0,0 +1,67 @@
+import type { AgentRunOptions } from '../../AgentRunOptions';
+import type { AgentMessageFailureTracker } from '../AgentMessageFailureTracker';
+import type { LocalAgentRunnerProjectSummary } from './LocalAgentRunnerProjectSummary';
+import type { LocalAgentRunnerWorkItem } from './LocalAgentRunnerWorkItem';
+import type { MultiAgentAutoPullResult } from './MultiAgentAutoPullResult';
+import type { MultipleAgentAutoPuller } from './MultipleAgentAutoPuller';
+import type { MultipleAgentRunUiPresenter } from './MultipleAgentRunUiPresenter';
+/**
+ * Task scheduler dependencies that are stable for one multi-agent watch session.
+ *
+ * @private type of `runMultipleAgentMessages`
+ */
+export type RunMultipleAgentMessageTaskSchedulerOptions = {
+    readonly runOptions: AgentRunOptions;
+    readonly messageFailureTracker: AgentMessageFailureTracker;
+    readonly autoPuller: MultipleAgentAutoPuller;
+    readonly uiPresenter: MultipleAgentRunUiPresenter;
+    readonly watchErrorLogDirectoryPath: string;
+};
+/**
+ * Owns active queued-message task selection, execution, and settling for `runMultipleAgentMessages`.
+ *
+ * @private class of `runMultipleAgentMessages`
+ */
+export declare class RunMultipleAgentMessageTaskScheduler {
+    private readonly options;
+    private readonly activeMessageTasksByKey;
+    private readonly isParallelMessageLimitConfigured;
+    private readonly maxParallelMessageCount;
+    constructor(options: RunMultipleAgentMessageTaskSchedulerOptions);
+    /**
+     * Number of currently running harness tasks.
+     */
+    get activeMessageCount(): number;
+    /**
+     * Selects the next queued messages that can be started without exceeding active harness capacity.
+     */
+    selectQueuedWorkItems(projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>): Array<LocalAgentRunnerWorkItem>;
+    /**
+     * Builds the set of project paths currently represented by active or newly scheduled harness tasks.
+     */
+    createAnsweringProjectPaths(queuedWorkItems: ReadonlyArray<LocalAgentRunnerWorkItem>): Set<string>;
+    /**
+     * Starts selected queued-message harness tasks and records them until they settle.
+     */
+    startQueuedWorkItems(options: {
+        readonly queuedWorkItems: ReadonlyArray<LocalAgentRunnerWorkItem>;
+        readonly projectSummaries: ReadonlyArray<LocalAgentRunnerProjectSummary>;
+        readonly answeringProjectPaths: ReadonlySet<string>;
+        readonly ignoredAgentCount: number;
+        readonly autoPullResult: MultiAgentAutoPullResult;
+    }): void;
+    /**
+     * Waits for either one active task to finish or the next queue polling interval.
+     */
+    waitForNextTurn(queuePollIntervalMs: number): Promise<void>;
+    /**
+     * Preserves previous shutdown behavior by letting active harness tasks finish before returning.
+     */
+    waitForActiveTasksToSettle(): Promise<void>;
+    private startQueuedWorkItem;
+    private runQueuedWorkItem;
+    private selectFirstInactiveQueuedWorkItem;
+    private createTaskKey;
+    private createRunOptionsForQueuedProjectTick;
+    private normalizeMaxParallelMessageCount;
+}

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/formatProjectPath.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Formats one child project path for stable console and UI output.
+ *
+ * @private function of `runMultipleAgentMessages`
+ */
+export declare function formatProjectPath(rootPath: string, projectPath: string): string;

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/loadLocalAgentRunnerProjectSummaries.d.ts

@@ -0,0 +1,11 @@
+import { type AgentIgnoreMatcher } from '../agentIgnorePatterns';
+import type { LocalAgentRunnerProjectSummariesResult } from './LocalAgentRunnerProjectSummary';
+/**
+ * Loads current direct-child repository summaries used by the shared dashboard and queue routing.
+ *
+ * @private function of `runMultipleAgentMessages`
+ */
+export declare function loadLocalAgentRunnerProjectSummaries(rootPath: string, options: {
+    readonly includeMessagePreviews: boolean;
+    readonly ignoreMatcher: AgentIgnoreMatcher;
+}): Promise<LocalAgentRunnerProjectSummariesResult>;

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages/wait.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Waits for the next idle poll interval in multi-agent watch mode.
+ *
+ * @private function of `runMultipleAgentMessages`
+ */
+export declare function wait(delayMs: number): Promise<void>;

package/umd/scripts/run-agent-messages/main/runMultipleAgentMessages.d.ts

@@ -1,4 +1,4 @@
-import { type CoderRunUiHandle } from '../../run-codex-prompts/ui/renderCoderRunUi';
+import type { CoderRunUiHandle } from '../../run-codex-prompts/ui/renderCoderRunUi';
 import type { AgentRunOptions } from '../AgentRunOptions';
 /**
  * Optional integrations for callers that supervise the multi-agent watcher as one service.

package/umd/scripts/run-codex-prompts/common/buildCoderRunProgressSnapshot.d.ts

@@ -24,4 +24,4 @@ export type CoderRunProgressSnapshot = {
  * provided (loaded from the per-config estimate cache stored in the temp folder), the snapshot uses
  * that historical average to project the remaining work instead of waiting for the first completion.
  */
-export declare function buildCoderRunProgressSnapshot(stats: PromptStats, elapsedDuration: moment.Duration, initialDone: number, cachedAveragePromptDurationMs?: number): CoderRunProgressSnapshot;
+export declare function buildCoderRunProgressSnapshot(stats: PromptStats, elapsedDuration: moment.Duration, initialDone: number, cachedAveragePromptDurationMs?: number, runLimit?: number): CoderRunProgressSnapshot;

package/umd/scripts/run-codex-prompts/common/cliProgressDisplay.d.ts

@@ -5,6 +5,7 @@ import type { PromptStats } from '../prompts/types/PromptStats';
  */
 export declare class CliProgressDisplay {
     private readonly minimumPriority;
+    private readonly runLimit?;
     private stats;
     /**
      * Initial number of completed prompts when the session started.
@@ -19,7 +20,7 @@ export declare class CliProgressDisplay {
     /**
      * Creates a new display that uses the provided start time when computing estimates.
      */
-    constructor(startTime: moment.Moment, minimumPriority: number);
+    constructor(startTime: moment.Moment, minimumPriority: number, runLimit?: number | undefined);
     /**
      * Sets the cached average prompt duration (in milliseconds) loaded from the temp-folder estimate cache.
      *

package/umd/scripts/run-codex-prompts/common/resolveCoderAgent.d.ts

@@ -0,0 +1,20 @@
+import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
+/**
+ * Agent data resolved from the optional `--agent` book file.
+ */
+export type ResolvedCoderAgent = {
+    /**
+     * Raw source of the agent `.book` file.
+     */
+    readonly agentSource: string_book;
+    /**
+     * Compiled system message injected into each coding prompt.
+     */
+    readonly systemMessage: string;
+};
+/**
+ * Reads an optional agent `.book` file and compiles its system message for injection into coder prompts.
+ *
+ * Returns `undefined` when no agent path is provided.
+ */
+export declare function resolveCoderAgent(agentPath: string | undefined, currentWorkingDirectory: string): Promise<ResolvedCoderAgent | undefined>;

package/umd/scripts/run-codex-prompts/runners/claude-code/ClaudeCodeRunner.d.ts

@@ -16,4 +16,8 @@ export declare class ClaudeCodeRunner implements PromptRunner {
      * Runs the prompt using Claude Code and parses usage output.
      */
     runPrompt(options: PromptRunOptions): Promise<PromptRunResult>;
+    /**
+     * Runs one Claude Code CLI process and returns its raw output.
+     */
+    private runClaudeCodeOnce;
 }

package/umd/scripts/run-codex-prompts/runners/claude-code/ClaudeCodeSessionResurrection.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Number of milliseconds added after Claude's reported reset timestamp before retrying.
+ */
+export declare const CLAUDE_CODE_SESSION_LIMIT_RESET_BUFFER_MS: number;
+/**
+ * Fallback delay used when Claude reports a session limit without a machine-readable reset timestamp.
+ */
+export declare const DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS: number;
+/**
+ * Session-limit detection details needed to resume a Claude Code run.
+ */
+export type ClaudeCodeSessionLimit = {
+    readonly sessionId: string;
+    readonly resetDate?: Date;
+    readonly rateLimitType?: string;
+    readonly summary: string;
+};
+/**
+ * Extracts a Claude Code session-limit failure from a thrown runner error.
+ */
+export declare function extractClaudeCodeSessionLimitFromError(error: unknown): ClaudeCodeSessionLimit | undefined;
+/**
+ * Extracts a Claude Code session-limit failure from raw stream-json output.
+ */
+export declare function extractClaudeCodeSessionLimitFromOutput(output: string): ClaudeCodeSessionLimit | undefined;
+/**
+ * Computes how long to wait before trying to resume the Claude Code session.
+ */
+export declare function getClaudeCodeSessionLimitDelayMs(sessionLimit: ClaudeCodeSessionLimit, nowMs?: number): number;
+/**
+ * Builds the follow-up prompt sent into a resumed Claude Code session after its limit resets.
+ */
+export declare function buildClaudeCodeSessionResurrectionPrompt(originalPrompt: string, sessionId: string): string;
+/**
+ * Builds a compact one-line label for logs and terminal UI messages.
+ */
+export declare function formatClaudeCodeSessionLimitForDisplay(sessionLimit: ClaudeCodeSessionLimit): string;

package/umd/scripts/run-codex-prompts/runners/claude-code/parseClaudeCodeOutputEvents.d.ts

@@ -0,0 +1,47 @@
+/**
+ * One parsed JSON event emitted by the Claude Code `--output-format stream-json` mode.
+ */
+export type ClaudeCodeOutputEvent = {
+    readonly type?: string;
+    readonly subtype?: string;
+    readonly is_error?: boolean;
+    readonly api_error_status?: number;
+    readonly result?: string;
+    readonly session_id?: string;
+    readonly error?: string;
+    readonly rate_limit_info?: {
+        readonly status?: string;
+        readonly resetsAt?: number;
+        readonly rateLimitType?: string;
+    };
+    readonly usage?: {
+        readonly input_tokens?: number;
+        readonly cache_creation_input_tokens?: number;
+        readonly cache_read_input_tokens?: number;
+        readonly output_tokens?: number;
+        readonly server_tool_use?: {
+            readonly web_search_requests?: number;
+            readonly web_fetch_requests?: number;
+        };
+        readonly service_tier?: string;
+        readonly cache_creation?: {
+            readonly ephemeral_1h_input_tokens?: number;
+            readonly ephemeral_5m_input_tokens?: number;
+        };
+    };
+    readonly total_cost_usd?: number;
+    readonly message?: {
+        readonly content?: ReadonlyArray<{
+            readonly type?: string;
+            readonly text?: string;
+        }>;
+    };
+};
+/**
+ * Parses all JSON lines from Claude Code output while ignoring shell prefixes and stack traces.
+ */
+export declare function parseClaudeCodeOutputEvents(output: string): readonly ClaudeCodeOutputEvent[];
+/**
+ * Finds the final Claude Code result event in a stream-json output blob.
+ */
+export declare function findClaudeCodeResultEvent(output: string): ClaudeCodeOutputEvent | undefined;

package/umd/scripts/run-codex-prompts/ui/CoderRunUiState.d.ts

@@ -2,8 +2,9 @@
 import { EventEmitter } from 'events';
 import moment from 'moment';
 import { type CoderRunProgressSnapshot } from '../common/buildCoderRunProgressSnapshot';
-import type { AgentRunMessagePreviewSection, AgentRunStatusTableRow } from './buildCoderRunUiFrame';
 import type { PromptStats } from '../prompts/types/PromptStats';
+import type { CoderRunAgentVisual } from './buildCoderRunAgentVisual';
+import type { AgentRunMessagePreviewSection, AgentRunStatusTableRow } from './buildCoderRunUiFrame';
 /**
  * Execution phase of the coder run process.
  *
@@ -23,6 +24,7 @@ export type CoderRunConfig = {
     readonly context?: string;
     readonly serverUrl?: string;
     readonly priority: number;
+    readonly limit?: number;
     readonly testCommand?: string;
 };
 /**
@@ -41,6 +43,7 @@ export type { CoderRunProgressSnapshot };
  */
 export declare class CoderRunUiState extends EventEmitter {
     config: CoderRunConfig;
+    agentVisual: CoderRunAgentVisual | undefined;
     currentPromptLabel: string;
     currentScriptPaths: string[];
     currentAttempt: number;
@@ -72,6 +75,10 @@ export declare class CoderRunUiState extends EventEmitter {
      * Replaces the configuration shown in the UI header.
      */
     setConfig(config: CoderRunConfig): void;
+    /**
+     * Replaces the ASCII-art agent visual renderer shown instead of the default brand banner.
+     */
+    setAgentVisual(agentVisual: CoderRunAgentVisual | undefined): void;
     /**
      * Feeds new prompt statistics from the main loop so the progress bar updates.
      */

package/umd/scripts/run-codex-prompts/ui/buildCoderRunAgentVisual.d.ts

@@ -0,0 +1,54 @@
+import type { string_book } from '../../../src/book-2.0/agent-source/string_book';
+/**
+ * Output width of the coder-run agent visual in terminal character cells.
+ *
+ * @private internal constant of coder run UI
+ */
+export declare const CODER_RUN_AGENT_VISUAL_COLUMNS = 48;
+/**
+ * Output height of the coder-run agent visual in terminal character cells.
+ *
+ * @private internal constant of coder run UI
+ */
+export declare const CODER_RUN_AGENT_VISUAL_ROWS = 12;
+/**
+ * Options passed by the terminal UI when rendering one animated agent visual frame.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunAgentVisualFrameOptions = {
+    /**
+     * Current animation time forwarded to the shared avatar renderer.
+     */
+    readonly animationTimeMs: number;
+};
+/**
+ * Runtime renderer for the `--agent` avatar visual shown in the coder-run terminal UI.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunAgentVisual = {
+    /**
+     * Whether the selected built-in visual changes over time.
+     */
+    readonly isAnimated: boolean;
+    /**
+     * Renders one ANSI ASCII-art frame for the current terminal timestamp.
+     */
+    readonly renderFrame: (options: CoderRunAgentVisualFrameOptions) => ReadonlyArray<string>;
+};
+/**
+ * Builds the ANSI ASCII-art visual of the `--agent` book shown above the coder-run dashboard.
+ *
+ * The agent's avatar visual is resolved the same way as on the website - the `META AVATAR`
+ * commitment wins, then the `META VISUAL` commitment, then the shared default visual - and is
+ * rendered dynamically through the shared canvas avatar pipeline into terminal ASCII art.
+ * The terminal variant uses a transparent horizontal canvas instead of the website's framed 1:1 surface.
+ *
+ * The visual is decorative, so any failure (for example when the optional `@napi-rs/canvas`
+ * module is not installed) returns `null` and the caller keeps the default brand banner.
+ *
+ * @param agentSource Source of the `--agent` book file.
+ * @returns ANSI-colored ASCII-art renderer or `null` when the visual cannot be rendered.
+ */
+export declare function buildCoderRunAgentVisual(agentSource: string_book): Promise<CoderRunAgentVisual | null>;

package/umd/scripts/run-codex-prompts/ui/buildCoderRunUiFrame.d.ts

@@ -1,5 +1,6 @@
 import type { CoderRunPauseState } from '../common/waitForPause';
 import type { CoderRunConfig, CoderRunPhase, CoderRunProgressSnapshot } from './CoderRunUiState';
+import type { CoderRunAgentVisual } from './buildCoderRunAgentVisual';
 /**
  * Shared pause-state shape between the renderer and the frame builder.
  */
@@ -10,7 +11,16 @@ export type { CoderRunPauseState };
 export type BuildCoderRunUiFrameOptions = {
     readonly terminalWidth: number;
     readonly animationFrame: number;
+    readonly animationTimeMs: number;
     readonly spinner: string;
+    /**
+     * ANSI ASCII-art renderer of the `--agent` avatar visual shown instead of the default brand banner.
+     */
+    readonly agentVisual?: CoderRunAgentVisual;
+    /**
+     * Optional static ANSI ASCII-art lines of the `--agent` avatar visual.
+     */
+    readonly agentVisualLines?: readonly string[];
     readonly pauseState: CoderRunPauseState;
     readonly pauseTargetLabel: string;
     readonly config: CoderRunConfig;

package/umd/scripts/run-codex-prompts/ui/coderRunUiRefresh.d.ts

@@ -11,7 +11,7 @@ export declare const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = 300;
  *
  * @private internal utility of coder run UI
  */
-export declare function isCoderRunUiAutoRefreshing(phase: CoderRunPhase, pauseState: CoderRunPauseState): boolean;
+export declare function isCoderRunUiAutoRefreshing(phase: CoderRunPhase, pauseState: CoderRunPauseState, isAgentVisualAnimated?: boolean): boolean;
 /**
  * Returns the automatic refresh interval for the current UI state.
  *
@@ -20,4 +20,4 @@ export declare function isCoderRunUiAutoRefreshing(phase: CoderRunPhase, pauseSt
  *
  * @private internal utility of coder run UI
  */
-export declare function getCoderRunUiAutoRefreshInterval(phase: CoderRunPhase, pauseState: CoderRunPauseState): number | undefined;
+export declare function getCoderRunUiAutoRefreshInterval(phase: CoderRunPhase, pauseState: CoderRunPauseState, isAgentVisualAnimated?: boolean): number | undefined;

package/umd/src/_packages/types.index.d.ts

@@ -20,8 +20,8 @@ import type { AvatarProfileFromSourceProps } from '../book-components/AvatarProf
 import type { BookEditorUploadProgressCallback } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorUploadOptions } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorProps } from '../book-components/BookEditor/BookEditor';
-import type { UploadItem } from '../book-components/BookEditor/useBookEditorMonacoUploads';
-import type { UploadStats } from '../book-components/BookEditor/useBookEditorMonacoUploads';
+import type { UploadItem } from '../book-components/BookEditor/useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
+import type { UploadStats } from '../book-components/BookEditor/useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
 import type { AgentChatProps } from '../book-components/Chat/AgentChat/AgentChatProps';
 import type { AgentChipData } from '../book-components/Chat/AgentChip/AgentChip';
 import type { AgentChipProps } from '../book-components/Chat/AgentChip/AgentChip';

package/umd/src/avatars/renderAvatarVisualAsciiArt.d.ts

@@ -0,0 +1,98 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId } from './types/AvatarVisualDefinition';
+/**
+ * Default output width of the ASCII avatar in terminal character cells.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_AVATAR_ASCII_ART_COLUMNS = 32;
+/**
+ * Factory creating a drawable canvas of the requested pixel size.
+ *
+ * In browsers this is typically `document.createElement('canvas')` (with width/height set),
+ * in Node.js an adapter around `createCanvas` of `@napi-rs/canvas` or a compatible library.
+ *
+ * @private within the repository
+ */
+export type CreateCanvasForAsciiArt = (width: number, height: number) => HTMLCanvasElement;
+/**
+ * Options for `renderAvatarVisualAsciiArt`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualAsciiArtOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Surface used to composite the avatar before ASCII conversion.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+    /**
+     * Output width in terminal character cells.
+     *
+     * @default `DEFAULT_AVATAR_ASCII_ART_COLUMNS`
+     */
+    readonly columns?: number;
+    /**
+     * Output height in terminal character cells.
+     *
+     * @default `columns / 2` so the square avatar stays visually square in a common terminal font
+     */
+    readonly rows?: number;
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+    /**
+     * Animation timestamp for animated visuals.
+     *
+     * @default `STATIC_AVATAR_ASCII_ART_FRAME_TIME_MS`
+     */
+    readonly timeMs?: number;
+    /**
+     * Source canvas width in CSS pixels before ASCII conversion.
+     *
+     * @default `DEFAULT_AVATAR_SIZE`
+     */
+    readonly canvasWidth?: number;
+    /**
+     * Source canvas height in CSS pixels before ASCII conversion.
+     *
+     * @default `DEFAULT_AVATAR_SIZE`
+     */
+    readonly canvasHeight?: number;
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+    /**
+     * Platform-specific canvas factory used to rasterize the visual.
+     */
+    readonly createCanvas: CreateCanvasForAsciiArt;
+};
+/**
+ * Renders one built-in avatar visual into ANSI-colored ASCII art for terminal display.
+ *
+ * This is the universal bridge between the canvas avatar visuals shown on the website and
+ * text-based terminal UIs: the visual is rasterized through the exact same `renderAvatarVisual`
+ * pipeline the web uses, then the resulting pixels are converted into colored half-block
+ * characters by `convertImageDataToAsciiArt`.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and the platform canvas factory.
+ * @returns One ANSI-colored string per output row.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualAsciiArt(options: RenderAvatarVisualAsciiArtOptions): ReadonlyArray<string>;

package/umd/src/avatars/visuals/octopus3dAvatarVisualShared.d.ts

@@ -1,5 +1,5 @@
 import type { AvatarPalette } from '../types/AvatarVisualDefinition';
-import { type Point3D, type ProjectedPoint } from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
 /**
  * Eye-style knobs shared by the proper-3D octopus visuals.
  *

package/umd/src/book-components/BookEditor/BookEditorMonacoUploadPanel.d.ts

@@ -1,4 +1,4 @@
-import type { UploadItem, UploadStats } from './useBookEditorMonacoUploads';
+import type { UploadItem, UploadStats } from './useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
 /**
  * Props for book editor monaco upload panel.
  */