@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -28,12 +28,12 @@ export type CoderRunAgentVisual = TerminalAgentAvatarVisual;
  * 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.
+ * commitment wins, then the `META VISUAL` commitment, then the shared default visual.
+ * Character-based visuals such as `AsciiOctopus` paint the terminal grid directly, while pixel-based
+ * visuals are rendered through the shared canvas avatar pipeline into terminal ASCII art, using 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.
+ * The visual is decorative, so any failure returns `null` and the caller renders no header visual at all.
  *
  * @param agentSource Source of the `--agent` book file.
  * @returns ANSI-colored ASCII-art renderer or `null` when the visual cannot be rendered.

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

@@ -1,6 +1,10 @@
+import type { CoderRunControlFeedbackNotice } from '../common/CoderRunControlFeedback';
 import type { CoderRunPauseState } from '../common/waitForPause';
+import type { HarnessSubscriptionUsage } from '../runners/types/HarnessSubscriptionUsage';
 import type { CoderRunConfig, CoderRunPhase, CoderRunProgressSnapshot } from './CoderRunUiState';
 import type { CoderRunAgentVisual } from './buildCoderRunAgentVisual';
+import type { CoderRunOutput } from './output/CoderRunOutput';
+import type { CoderOutputMode } from './output/CoderOutputEvent';
 /**
  * Shared pause-state shape between the renderer and the frame builder.
  */
@@ -9,12 +13,15 @@ export type { CoderRunPauseState };
  * Snapshot consumed by the pure coder-run frame builder.
  */
 export type BuildCoderRunUiFrameOptions = {
+    /**
+     * Number of physical columns currently available in the terminal.
+     */
     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.
+     * ANSI ASCII-art renderer of the `--agent` avatar visual shown above the dashboard boxes.
      */
     readonly agentVisual?: CoderRunAgentVisual;
     /**
@@ -25,6 +32,7 @@ export type BuildCoderRunUiFrameOptions = {
     readonly pauseTargetLabel: string;
     readonly isEndAfterCurrentPromptRequested: boolean;
     readonly config: CoderRunConfig;
+    readonly subscriptionUsage?: HarnessSubscriptionUsage;
     readonly phase: CoderRunPhase;
     readonly currentPromptLabel: string;
     readonly currentScriptPaths?: readonly string[];
@@ -38,8 +46,16 @@ export type BuildCoderRunUiFrameOptions = {
     readonly agentStatusTableRows?: readonly AgentRunStatusTableRow[];
     readonly pendingEnterLabel?: string;
     readonly agentOutputLines: readonly string[];
+    /** Presentation-only state; omitted by dashboards which use the older plain output panel. */
+    readonly output?: CoderRunOutput;
+    readonly outputMode?: CoderOutputMode;
+    readonly outputScrollOffset?: number;
     readonly errors: readonly string[];
     readonly progress: CoderRunProgressSnapshot;
+    /**
+     * Answer of the runner to the control key which was pressed last, shown in the `Controls` box.
+     */
+    readonly controlFeedback?: CoderRunControlFeedbackNotice;
 };
 /**
  * Structured row rendered in the agent-run `Agents` table.

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

@@ -0,0 +1,27 @@
+/**
+ * Builds the terminal output required to replace the previous coder-run frame with the next one.
+ *
+ * The complete update is returned as one string so callers can write it atomically. This prevents
+ * animated visuals from producing a separate terminal write for every changed row, which otherwise
+ * leaves a large rendering backlog in terminal emulators while their window is not focused.
+ *
+ * @private internal utility of coder run UI
+ */
+export type BuildCoderRunUiTerminalFrameUpdateOptions = {
+    /** Frame currently displayed in the terminal, with the cursor on its last row. */
+    readonly previousFrameLines: readonly string[];
+    /** Frame that should replace the currently displayed frame. */
+    readonly nextFrameLines: readonly string[];
+};
+/**
+ * Builds one atomic ANSI update that changes the displayed coder-run terminal frame.
+ *
+ * A change in frame height requires a full rewrite to reserve or clear rows correctly. Frames with
+ * the same height only rewrite contiguous groups of changed rows, returning to the frame bottom
+ * between groups so each group can be assembled into the same output payload safely.
+ *
+ * @returns One terminal output payload, or `undefined` when the frame is already up to date.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function buildCoderRunUiTerminalFrameUpdate(options: BuildCoderRunUiTerminalFrameUpdateOptions): string | undefined;

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

@@ -0,0 +1,5 @@
+/** Keeps controls reachable in short terminals and makes the entire existing dashboard scrollable. */
+export declare function buildCoderRunUiViewport(lines: string[], columns: number, rows: number, scrollOffset: number): {
+    lines: string[];
+    maxScrollOffset: number;
+};

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

@@ -1,5 +1,7 @@
+import type { CoderRunControlFeedbackNotice } from '../common/CoderRunControlFeedback';
 import type { CoderRunPauseState } from '../common/waitForPause';
 import type { CoderRunPhase } from './CoderRunUiState';
+import type { CoderOutputMode } from './output/CoderOutputEvent';
 /**
  * Maximum number of output lines reserved for agent output in the UI.
  */
@@ -50,7 +52,7 @@ export declare function buildTerminalUrlLink(url: string, availableWidth: number
 /**
  * Builds the colored phase badge shown in the session box.
  */
-export declare function buildPausePresentation(phase: CoderRunPhase, pauseState: CoderRunPauseState, pauseTargetLabel: string, statusMessage: string): PausePresentation;
+export declare function buildPausePresentation(phase: CoderRunPhase, pauseState: CoderRunPauseState, pauseTargetLabel: string, statusMessage: string, isBracketed?: boolean): PausePresentation;
 /**
  * Builds the progress bar shown in the session box.
  */
@@ -72,4 +74,16 @@ export declare function buildCoderRunControlPills(options: {
     readonly pendingEnterLabel: string | undefined;
     readonly isEndAfterCurrentPromptRequested: boolean;
     readonly sessionTotal: number;
+    readonly outputMode?: CoderOutputMode;
+}): readonly string[];
+/**
+ * Builds the body of the `Controls` box.
+ *
+ * The pills are always shown, and right after a control key was pressed the answer of the runner to
+ * that key is shown underneath, so no key press ever leaves the frame unchanged.
+ */
+export declare function buildControlsBoxLines(options: {
+    readonly controlPills: readonly string[];
+    readonly controlFeedback: CoderRunControlFeedbackNotice | undefined;
+    readonly bodyWidth?: number;
 }): readonly string[];

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

@@ -0,0 +1,11 @@
+import type { HarnessSubscriptionUsage } from '../runners/types/HarnessSubscriptionUsage';
+import type { SessionRow } from './buildRunUiFrameShared';
+/**
+ * Builds every available subscription-limit row for the terminal Session box.
+ *
+ * The first row carries the `Usage` label and subsequent rows stay aligned beneath it, allowing a harness to report
+ * any number of windows instead of making the dashboard assume a fixed 5-hour/weekly pair.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function buildSubscriptionUsageSessionRows(subscriptionUsage: HarnessSubscriptionUsage | undefined, currentTimeMs?: number): readonly SessionRow[];

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

@@ -28,6 +28,10 @@ export declare function fitPlainText(text: string, width: number): string;
  * @private internal utility of coder run UI
  */
 export declare function visibleLength(text: string): number;
+/** Wraps sanitized display text without splitting surrogate pairs, combining marks or emoji sequences. */
+export declare function wrapTerminalText(text: string, width: number): string[];
+/** Harness control characters may be retained in logs but cannot move the dashboard cursor. */
+export declare function sanitizeTerminalText(text: string): string;
 /**
  * Strips ANSI escape codes from a string.
  *

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

@@ -0,0 +1,20 @@
+/** Display selection belongs only to this dashboard invocation. */
+export type CoderOutputMode = 'normal' | 'raw';
+/** Observable output categories; these never drive runner state. */
+export type CoderOutputKind = 'agent' | 'reasoning' | 'tool' | 'files' | 'check' | 'result' | 'warning' | 'error' | 'status' | 'unknown';
+/** A bounded presentation entry, separate from the original harness chunks and durable trace. */
+export type CoderOutputEvent = {
+    readonly id?: string;
+    readonly kind: CoderOutputKind;
+    readonly title: string;
+    readonly text: string;
+    readonly isDelta?: boolean;
+};
+/** Permissive protocol object: all fields are checked at the presentation boundary. */
+export type CoderOutputRecord = Record<string, unknown>;
+/** Safely reads an object from an unknown protocol field. */
+export declare function outputRecord(value: unknown): CoderOutputRecord;
+/** Safely reads a string without interpreting arbitrary objects as prose. */
+export declare function outputText(value: unknown): string;
+/** Safely reads arrays containing protocol records. */
+export declare function outputRecords(value: unknown): CoderOutputRecord[];

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

@@ -0,0 +1,48 @@
+import type { LiveScriptOutputSource } from '../../common/runGoScript/captureLiveScriptOutput';
+import { type CoderOutputEvent } from './CoderOutputEvent';
+/** Original chunks in arrival order, including stream identity. */
+export type CoderRawOutputChunk = {
+    readonly text: string;
+    readonly source: string;
+};
+/** Bounded, passive projection of existing output. No method calls or controls any harness. */
+export declare class CoderRunOutput {
+    /** Lets the renderer reuse wrapping while only the spinner or elapsed timer changes. */
+    revision: number;
+    private readonly projectedEvents;
+    private readonly pendingOutput;
+    private pendingCharacterCount;
+    private skippedChunkCount;
+    readonly rawChunks: CoderRawOutputChunk[];
+    isHistoryTruncated: boolean;
+    private rawCharacterCount;
+    private sequence;
+    private generation;
+    private streams;
+    /** Makes projection lazy so input keys and process-output callbacks perform no rendering work. */
+    get events(): readonly CoderOutputEvent[];
+    /** Records the original chunk first and queues its independent presentation projection. */
+    append(chunk: string, source: LiveScriptOutputSource, harnessName: string, isCheck: boolean): void;
+    /** Projects a queued chunk, assembling stdout and stderr independently. */
+    private projectChunk;
+    /** Runner logs are already complete messages, unlike shell chunks. */
+    appendRunner(text: string, kind?: 'status' | 'warning' | 'error' | 'check'): void;
+    /** Queues the capture boundary; runner callbacks must never perform projection or wrapping. */
+    flush(): void;
+    /** Final plain lines retain their observed speaker/activity; malformed records remain labeled as data. */
+    private flushStreams;
+    /** Pending JSON is never presented as an agent message. Plain text remains visible before a newline arrives. */
+    getPendingEvents(): CoderOutputEvent[];
+    /** Bounds deferred work too; overload is visible and durable logs remain untouched. */
+    private enqueue;
+    /** Processes bounded display work, never a runner action. */
+    private drain;
+    /** Keeps bounded original chunks separately, never replacing the durable log with normalized text. */
+    private retainRaw;
+    /** Uses the existing shared harness JSON parser; unknown and malformed records stay visible. */
+    private projectLine;
+    /** Groups adjacent lines only within the same observed activity and stream. */
+    private addPlain;
+    /** Updates known message/tool snapshots in place and suppresses duplicate result text. */
+    private add;
+}

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

@@ -0,0 +1,18 @@
+import type { CoderOutputEvent, CoderOutputMode } from './CoderOutputEvent';
+import type { CoderRawOutputChunk } from './CoderRunOutput';
+/** Reads the last rendered scroll extent without doing presentation work on the input-control path. */
+export declare function getCoderOutputScrollMaximum(chunks: readonly CoderRawOutputChunk[], mode: CoderOutputMode, height: number): number;
+/** Builds a fixed-height, wrapped viewport from the selected projection of the same stream. */
+export declare function buildCoderOutputLines(options: {
+    readonly mode: CoderOutputMode;
+    readonly events: readonly CoderOutputEvent[];
+    readonly rawChunks: readonly CoderRawOutputChunk[];
+    readonly width: number;
+    readonly height: number;
+    readonly scrollOffset: number;
+    readonly isHistoryTruncated: boolean;
+    readonly revision?: number;
+}): {
+    lines: string[];
+    maxScrollOffset: number;
+};

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

@@ -0,0 +1,10 @@
+import { type CoderOutputEvent, type CoderOutputRecord } from './CoderOutputEvent';
+/** Per-stream message identity for Claude's indexed content blocks. */
+export type CoderOutputRecordContext = {
+    messageId: string;
+    sequence: number;
+};
+/** Projects known harness envelopes into display events, without making execution decisions. */
+export declare function normalizeCoderOutputRecord(record: CoderOutputRecord, context: CoderOutputRecordContext): CoderOutputEvent[] | undefined;
+/** Displays supplied data as data, never as invented narration. */
+export declare function formatOutputValue(value: unknown): string;

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

@@ -0,0 +1,14 @@
+import type { PromptRunner } from '../runners/types/PromptRunner';
+import type { CoderRunUiState } from './CoderRunUiState';
+/**
+ * Refreshes optional harness subscription usage in the shared coder-run UI state.
+ *
+ * Subscription visibility is an enhancement, not a prerequisite for running prompts. A harness which cannot expose a
+ * snapshot, or whose account endpoint is temporarily unavailable, therefore leaves the existing dashboard unchanged.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function refreshCoderRunUiSubscriptionUsage(options: {
+    readonly runner: PromptRunner;
+    readonly uiState: CoderRunUiState | undefined;
+}): Promise<void>;

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

@@ -34,4 +34,8 @@ export type CoderRunUiHandle = {
 export declare function renderCoderRunUi(startTime: moment.Moment, options?: {
     readonly buildFrameLines?: (options: BuildCoderRunUiFrameOptions) => string[];
     readonly state?: CoderRunUiState;
+    /** Finite jobs cancel their owned activity and finish cleanup instead of exiting directly from a keypress. */
+    readonly onInterrupt?: () => void;
+    /** Jobs without a queue need presentation controls only, independent of global run pause state. */
+    readonly isQueueControlsEnabled?: boolean;
 }): CoderRunUiHandle;

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

@@ -0,0 +1,37 @@
+import type { PromptRunner } from '../runners/types/PromptRunner';
+import type { CoderRunUiState } from './CoderRunUiState';
+/**
+ * How often the harness subscription usage is re-read while `ptbk coder` is running.
+ *
+ * @private internal constant of coder run UI
+ */
+export declare const CODER_RUN_SUBSCRIPTION_USAGE_REFRESH_INTERVAL_MS: number;
+/**
+ * Stops the periodic subscription-usage refresh of one coder run.
+ *
+ * @private internal type of coder run UI
+ */
+export type CoderRunUiSubscriptionUsageRefreshHandle = {
+    /**
+     * Ends the refresh, after which the dashboard keeps the last read values.
+     */
+    stop(): void;
+};
+/**
+ * Keeps the harness subscription usage of the coder-run dashboard current for the whole run.
+ *
+ * A single coding prompt can take hours, so reading the usage once per prompt leaves the dashboard showing values
+ * which are long out of date. Reading it on its own clock instead means the percentages and reset countdowns always
+ * describe the present moment, no matter how long the current prompt runs.
+ *
+ * Refreshes never overlap: a read which is still in flight when the next tick arrives simply skips that tick, so a
+ * slow or hanging harness cannot pile up requests. The whole refresh is optional dashboard information, so a harness
+ * without subscription limits and a run without a dashboard start no timer at all.
+ *
+ * @private internal utility of coder run UI
+ */
+export declare function startCoderRunUiSubscriptionUsageRefresh(options: {
+    readonly runner: PromptRunner;
+    readonly uiState: CoderRunUiState | undefined;
+    readonly refreshIntervalMs?: number;
+}): CoderRunUiSubscriptionUsageRefreshHandle;

package/umd/scripts/utils/emojiTags/scanEmojiTagUsage.d.ts

@@ -3,6 +3,8 @@ import type { string_char_emoji } from '../../../src/types/typeAliasEmoji';
  * Options controlling one repository emoji-tag scan.
  */
 export type EmojiTagScanOptions = {
+    /** False keeps a scan read-only while still reusing any existing cache. */
+    readonly isCacheWriteEnabled?: boolean;
     /**
      * Candidate emojis that may appear inside bracketed tags.
      */

package/umd/scripts/utils/emojiTags/validSinglePictogramEmojis.d.ts

@@ -0,0 +1,17 @@
+import type { string_char_emoji } from '../../../src/types/typeAliasEmoji';
+/**
+ * Valid single-pictogram emojis that `ptbk` can use in generated tags.
+ *
+ * The shared emoji catalogue also contains legacy symbols for other presentation
+ * purposes. Restricting generated tags to Unicode emoji-presentation pictograms
+ * prevents those symbols from being emitted as prompt identifiers.
+ *
+ * @private internal utility of generated `ptbk` emoji tags
+ */
+export declare const VALID_SINGLE_PICTOGRAM_EMOJIS: ReadonlySet<string_char_emoji>;
+/**
+ * Determines whether one catalogue entry is a valid single-pictogram emoji for a generated tag.
+ *
+ * @private internal utility of generated `ptbk` emoji tags
+ */
+export declare function isValidSinglePictogramEmoji(emoji: string_char_emoji): boolean;

package/umd/scripts/utils/prompts/isPromptDocumentationFile.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reserves the prompts README for documentation, regardless of its contents or filename case.
+ * Other Markdown filenames remain valid PRDs, including names which contain the word "readme".
+ */
+export declare function isPromptDocumentationFile(filePath: string): boolean;

package/umd/scripts/utils/prompts/promptEmojiTags.d.ts

@@ -7,6 +7,8 @@ export declare const PROMPT_EMOJI_TAG_PREFIX = "\u2728";
  * Options for selecting fresh prompt emoji tags.
  */
 export type PromptEmojiTagOptions = {
+    /** Read-only authoring previews can disable the scan cache's filesystem writes. */
+    readonly isCacheWriteEnabled?: boolean;
     /**
      * Number of unique emojis to reserve.
      */

package/umd/scripts/verify-prompts/verify-prompts.d.ts

@@ -1,3 +1,4 @@
+import type { WorkspaceRepositoryContext } from '../../src/cli/cli-commands/common/workspaceRepository';
 import type { CoderGitSyncOptions } from '../run-codex-prompts/git/coderGitSync';
 import type { PromptFile } from '../run-codex-prompts/prompts/types/PromptFile';
 import type { VerifyPromptsOrder } from './VerifyPromptsOrder';
@@ -5,6 +6,8 @@ import type { VerifyPromptsOrder } from './VerifyPromptsOrder';
  * Options supported by the prompt verification helper.
  */
 export type VerifyPromptsOptions = {
+    /** Resolved project and repository supplied by the workspace preflight. */
+    readonly workspace?: WorkspaceRepositoryContext;
     /**
      * Order in which the prompt files are processed.
      */

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

@@ -70,8 +70,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
 import { MicIcon } from '../book-components/icons/MicIcon';
@@ -159,8 +161,10 @@ export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };

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

@@ -62,8 +62,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
 import type { QrCodeOptions } from '../book-components/Qr/useQrCode';
@@ -511,8 +513,10 @@ export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };

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

@@ -0,0 +1,80 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId, AvatarVisualTerminalTextGrid } from './types/AvatarVisualDefinition';
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * 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 derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextGrid(options: RenderAvatarVisualTerminalTextOptions): AvatarVisualTerminalTextGrid | null;
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextLines(options: RenderAvatarVisualTerminalTextLinesOptions): ReadonlyArray<string> | null;

package/umd/src/avatars/renderAvatarVisualTerminalText.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -72,6 +72,52 @@ export type AvatarVisualRenderContext = {
  * @private shared contract for the avatar rendering system
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -84,6 +130,14 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 /**
  * Props of the shared `<Avatar/>` component.

package/umd/src/book-2.0/agent-source/AgentReferenceResolutionIssue.d.ts

@@ -0,0 +1,45 @@
+import type { BookCommitment } from '../../commitments/_base/BookCommitment';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+/**
+ * Structured issue captured when compact agent reference resolution fails.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceResolutionIssue = {
+    /**
+     * Commitment where the unresolved token appeared.
+     */
+    readonly commitmentType: BookCommitment;
+    /**
+     * Original token text (for example `{Unknown Agent}` or `@UnknownAgent`).
+     */
+    readonly token: string;
+    /**
+     * Normalized token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Human-readable explanation of why the token could not be resolved.
+     */
+    readonly message: string;
+};
+/**
+ * Extension implemented by resolvers that can expose accumulated resolution issues.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type IssueTrackingAgentReferenceResolver = AgentReferenceResolver & {
+    /**
+     * Returns tracked issues and clears the internal queue.
+     */
+    consumeResolutionIssues(): Array<AgentReferenceResolutionIssue>;
+};
+/**
+ * Drains unresolved compact-reference issues from a resolver when supported.
+ *
+ * @param resolver - Resolver instance that may implement issue tracking.
+ * @returns Collected issues or an empty list.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function consumeAgentReferenceResolutionIssues(resolver?: AgentReferenceResolver): Array<AgentReferenceResolutionIssue>;