@promptbook/cli 0.113.0-1 → 0.113.0-11

package/src/remote-server/startRemoteServer/registerExecutionRoutes.ts

@@ -4,8 +4,8 @@ import { serializeError } from '../../errors/utils/serializeError';
 import { createPipelineExecutor } from '../../execution/createPipelineExecutor/00-createPipelineExecutor';
 import type { AbstractTask, ExecutionTask } from '../../execution/ExecutionTask';
 import type { chococake } from '../../utils/organization/really_any';
-import type { RemoteServerRuntime } from './RemoteServerRuntime';
 import { getExecutionToolsFromIdentification } from './getExecutionToolsFromIdentification';
+import type { RemoteServerRuntime } from './RemoteServerRuntime';
 
 /**
  * Registers execution task listing, detail, and creation routes.

package/src/remote-server/startRemoteServer/registerServerIndexRoute.ts

@@ -1,9 +1,9 @@
 import { spaceTrim } from 'spacetrim';
 import { CLAIM } from '../../config';
+import type { chococake } from '../../utils/organization/really_any';
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
 import { renderServerIndexHtml } from '../ui/renderServerIndexHtml';
 import type { ServerInfo } from '../ui/types';
-import type { chococake } from '../../utils/organization/really_any';
 import type { RemoteServerRuntime } from './RemoteServerRuntime';
 
 /**

package/src/scrapers/_common/utils/makeKnowledgeSourceHandler.ts

@@ -4,12 +4,7 @@ import { dirname, isAbsolute, join } from 'path';
 import { spaceTrim } from 'spacetrim';
 import type { SetOptional } from 'type-fest';
 import { knowledgeSourceContentToName } from '../../../commands/KNOWLEDGE/utils/knowledgeSourceContentToName';
-import {
-    DEFAULT_DOWNLOAD_CACHE_DIRNAME,
-    DEFAULT_IS_VERBOSE,
-    DEFAULT_MAX_FILE_SIZE,
-    MAX_FILENAME_LENGTH,
-} from '../../../config';
+import { DEFAULT_DOWNLOAD_CACHE_DIRNAME, DEFAULT_IS_VERBOSE, DEFAULT_MAX_FILE_SIZE, MAX_FILENAME_LENGTH } from '../../../config';
 import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
 import { LimitReachedError } from '../../../errors/LimitReachedError';
 import { NotFoundError } from '../../../errors/NotFoundError';

package/src/speech-recognition/OpenAiSpeechRecognition.ts

@@ -1,9 +1,4 @@
-import type {
-    SpeechRecognition,
-    SpeechRecognitionEvent,
-    SpeechRecognitionStartOptions,
-    SpeechRecognitionState,
-} from '../types/SpeechRecognition';
+import type { SpeechRecognition, SpeechRecognitionEvent, SpeechRecognitionStartOptions, SpeechRecognitionState } from '../types/SpeechRecognition';
 
 /**
  * Options for OpenAiSpeechRecognition

package/src/transpilers/_common/prepareSdkTranspilerContext.ts

@@ -6,10 +6,7 @@ import type { string_book } from '../../book-2.0/agent-source/string_book';
 import { getAllCommitmentDefinitions } from '../../commitments/_common/getAllCommitmentDefinitions';
 import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
 import type { BookTranspilerOptions } from './BookTranspilerOptions';
-import {
-    createTranspiledTeamAwareToolFunctions,
-    createTranspiledTeamExportForContext,
-} from './createTranspiledTeamRuntimeSection';
+import { createTranspiledTeamAwareToolFunctions, createTranspiledTeamExportForContext } from './createTranspiledTeamRuntimeSection';
 import type { TranspiledTeamExport } from './TranspiledTeamExport';
 
 /**

package/src/types/Prompt.ts

@@ -2,13 +2,7 @@ import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { FormatCommand } from '../commands/FORMAT/FormatCommand';
 import type { Expectations } from '../pipeline/PipelineJson/Expectations';
 import type { LlmToolDefinition } from './LlmToolDefinition';
-import type {
-    ChatModelRequirements,
-    CompletionModelRequirements,
-    EmbeddingModelRequirements,
-    ImageGenerationModelRequirements,
-    ModelRequirements,
-} from './ModelRequirements';
+import type { ChatModelRequirements, CompletionModelRequirements, EmbeddingModelRequirements, ImageGenerationModelRequirements, ModelRequirements } from './ModelRequirements';
 import type { Parameters } from './Parameters';
 import type { string_postprocessing_function_name } from './string_person_fullname';
 import type { string_pipeline_url_with_task_hash } from './string_pipeline_url';

package/src/types/string_host.ts

@@ -1,12 +1,4 @@
-import type {
-    string_domain_private,
-    string_hostname_private,
-    string_host_private,
-    string_ip_address_private,
-    string_origin_private,
-    string_protocol_private,
-    string_tdl_private,
-} from './string_host_private';
+import type { string_domain_private, string_hostname_private, string_host_private, string_ip_address_private, string_origin_private, string_protocol_private, string_tdl_private } from './string_host_private';
 
 /**
  * Semantic helper

package/src/types/string_pipeline_url.ts

@@ -1,7 +1,4 @@
-import type {
-    string_pipeline_url_private,
-    string_pipeline_url_with_task_hash_private,
-} from './string_pipeline_url_private';
+import type { string_pipeline_url_private, string_pipeline_url_with_task_hash_private } from './string_pipeline_url_private';
 
 /**
  * Semantic helper

package/src/utils/agent-message-runtime/agentMessageRuntimePaths.ts

@@ -0,0 +1,66 @@
+import { basename } from 'path';
+import { resolvePromptbookTemporaryPath } from '../filesystem/promptbookTemporaryPath';
+
+/**
+ * Temporary subdirectory used for agent-message runner shell scripts.
+ *
+ * @private internal constant of agent-message runtime paths
+ */
+export const AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME = 'agent-messages';
+
+/**
+ * File extension used for temporary prompt-runner shell scripts.
+ *
+ * @private internal constant of agent-message runtime paths
+ */
+const AGENT_MESSAGE_SCRIPT_EXTENSION = '.sh';
+
+/**
+ * File extension used for temporary prompt-runner live logs.
+ *
+ * @private internal constant of agent-message runtime paths
+ */
+const AGENT_MESSAGE_RUNTIME_LOG_EXTENSION = '.log.txt';
+
+/**
+ * Builds the temporary shell script path used by one queued agent-message harness run.
+ *
+ * @param projectPath - Local agent project path containing the message queue.
+ * @param sourceFileName - Queued message filename used to name the temporary shell script.
+ * @returns Temporary shell script path.
+ * @private internal utility of agent-message runners
+ */
+export function buildAgentMessageScriptPathFromFileName(projectPath: string, sourceFileName: string): string {
+    const sourceFileBasename = basename(sourceFileName);
+    const scriptFileName = `${sourceFileBasename.replace(/\.[^.]+$/u, '')}${AGENT_MESSAGE_SCRIPT_EXTENSION}`;
+
+    return resolvePromptbookTemporaryPath(projectPath, AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME, scriptFileName);
+}
+
+/**
+ * Builds the live runtime log path used by one queued agent-message harness run.
+ *
+ * @param projectPath - Local agent project path containing the message queue.
+ * @param sourceFileName - Queued message filename used to name the temporary shell script.
+ * @returns Temporary live runtime log path.
+ * @private internal utility of agent-message runners
+ */
+export function buildAgentMessageRuntimeLogPathFromFileName(projectPath: string, sourceFileName: string): string {
+    return buildAgentMessageScriptPathFromFileName(projectPath, sourceFileName).replace(
+        new RegExp(`${escapeRegExp(AGENT_MESSAGE_SCRIPT_EXTENSION)}$`, 'iu'),
+        AGENT_MESSAGE_RUNTIME_LOG_EXTENSION,
+    );
+}
+
+/**
+ * Escapes one literal string for safe `RegExp` construction.
+ *
+ * @param value - Literal string to escape.
+ * @returns Escaped regular-expression fragment.
+ * @private internal utility of agent-message runtime paths
+ */
+function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/utils/agents/resolveAgentAvatarImageUrl.ts

@@ -47,7 +47,7 @@ export type ResolveAgentAvatarOptions = {
 export type ResolveAgentAvatarImageUrlOptions = ResolveAgentAvatarOptions;
 
 /**
- * Default built-in avatar visual used when an agent does not define `META IMAGE`.
+ * Default built-in avatar visual used when an agent does not define `META IMAGE`, `META AVATAR`, or `META VISUAL`.
  *
  * @private shared avatar contract
  */
@@ -195,7 +195,7 @@ export function resolveAgentAvatarFallbackUrl(options: ResolveAgentAvatarOptions
 
 /**
  * Resolve the best avatar representation for an agent, preferring explicit `META IMAGE`
- * and otherwise returning the default deterministic canvas visual.
+ * and otherwise returning the selected deterministic canvas visual.
  *
  * @private utility of `<Chat/>`
  */

package/src/utils/agents/terminalAgentAvatarVisual.ts

@@ -0,0 +1,261 @@
+import {
+    createAvatarDefinitionFromAgentBasicInformation,
+    DEFAULT_AVATAR_SIZE,
+} from '../../avatars/avatarRenderingUtils';
+import { resolveAvatarRenderDefinition, type ResolvedAvatarRenderDefinition } from '../../avatars/renderAvatarVisual';
+import {
+    renderAvatarVisualAsciiArt,
+    type CreateCanvasForAsciiArt,
+} from '../../avatars/renderAvatarVisualAsciiArt';
+import type { AvatarDefinition } from '../../avatars/types/AvatarDefinition';
+import type { AvatarVisualId } from '../../avatars/types/AvatarVisualDefinition';
+import { resolveAvatarVisualId } from '../../avatars/visuals/avatarVisualRegistry';
+import type { AgentBasicInformation } from '../../book-2.0/agent-source/AgentBasicInformation';
+import { parseAgentSource } from '../../book-2.0/agent-source/parseAgentSource';
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+import type { AsciiArtColorDepth } from '../ascii-art/convertImageDataToAsciiArt';
+import { DEFAULT_AGENT_AVATAR_VISUAL_ID, resolveAgentAvatarVisualId } from './resolveAgentAvatarImageUrl';
+
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * Output width of the terminal agent avatar visual in character cells.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export const TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS = 48;
+
+/**
+ * Output height of the terminal agent avatar visual in character cells.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export const TERMINAL_AGENT_AVATAR_VISUAL_ROWS = 12;
+
+/**
+ * Refresh cadence used while a terminal agent avatar visual is animated.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export const TERMINAL_AGENT_AVATAR_VISUAL_REFRESH_INTERVAL_MS = 300;
+
+/**
+ * Aspect ratio of the source canvas used for the terminal avatar variant.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+const TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_ASPECT_RATIO = 2;
+
+/**
+ * Source canvas width used before the avatar is converted to ASCII art.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+const TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_WIDTH =
+    DEFAULT_AVATAR_SIZE * TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_ASPECT_RATIO;
+
+/**
+ * Source canvas height used before the avatar is converted to ASCII art.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+const TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_HEIGHT = DEFAULT_AVATAR_SIZE;
+
+/**
+ * Options passed when rendering one animated terminal avatar frame.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export type TerminalAgentAvatarVisualFrameOptions = {
+    /**
+     * Current animation time forwarded to the shared avatar renderer.
+     */
+    readonly animationTimeMs: number;
+};
+
+/**
+ * Runtime renderer for an agent avatar visual shown in a terminal.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export type TerminalAgentAvatarVisual = {
+    /**
+     * 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: TerminalAgentAvatarVisualFrameOptions) => ReadonlyArray<string>;
+};
+
+/**
+ * Options for creating a terminal avatar visual renderer from an agent book source.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export type CreateTerminalAgentAvatarVisualOptions = {
+    /**
+     * Source of the agent book whose metadata controls avatar identity.
+     */
+    readonly agentSource: string_book;
+
+    /**
+     * Built-in avatar visual used when the agent does not declare `META AVATAR` or `META VISUAL`.
+     */
+    readonly defaultAvatarVisualId?: AvatarVisualId;
+
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+
+    /**
+     * Platform-specific canvas factory used to rasterize the visual.
+     */
+    readonly createCanvas: CreateCanvasForAsciiArt;
+};
+
+/**
+ * Stable render inputs derived from an agent source for terminal avatar frames.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+type TerminalAgentAvatarVisualRenderInputs = {
+    /**
+     * Stable identity payload used by the shared avatar renderer.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+
+    /**
+     * Built-in avatar visual selected for terminal rendering.
+     */
+    readonly avatarVisualId: AvatarVisualId;
+
+    /**
+     * Resolved render data reused across animation frames.
+     */
+    readonly resolvedAvatarRenderDefinition: ResolvedAvatarRenderDefinition;
+};
+
+/**
+ * Resolves the built-in avatar visual selected for terminal rendering of one agent source.
+ *
+ * @param agentSource Source of the agent book.
+ * @param defaultAvatarVisualId Built-in fallback used when the source does not declare an avatar visual.
+ * @returns Supported built-in avatar visual id.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export function resolveTerminalAgentAvatarVisualId(
+    agentSource: string_book,
+    defaultAvatarVisualId: AvatarVisualId = DEFAULT_AGENT_AVATAR_VISUAL_ID,
+): AvatarVisualId {
+    const agentBasicInformation = parseAgentSource(agentSource);
+
+    return resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(agentBasicInformation, defaultAvatarVisualId);
+}
+
+/**
+ * Creates an ANSI ASCII-art avatar renderer for terminal UIs.
+ *
+ * The agent's avatar visual is resolved the same way as on the website: `META AVATAR`
+ * / `META VISUAL` wins, then the provided fallback visual, then the shared default visual.
+ * The terminal variant uses a transparent horizontal canvas instead of the website's framed square surface.
+ *
+ * @param options Agent source, canvas factory, and optional terminal color settings.
+ * @returns Runtime terminal avatar visual renderer.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+export function createTerminalAgentAvatarVisual(
+    options: CreateTerminalAgentAvatarVisualOptions,
+): TerminalAgentAvatarVisual {
+    const renderInputs = createTerminalAgentAvatarVisualRenderInputs(
+        options.agentSource,
+        options.defaultAvatarVisualId || DEFAULT_AGENT_AVATAR_VISUAL_ID,
+    );
+
+    return {
+        isAnimated: renderInputs.resolvedAvatarRenderDefinition.avatarVisual.isAnimated,
+        renderFrame({ animationTimeMs }) {
+            return renderTerminalAgentAvatarVisualFrame({
+                ...renderInputs,
+                animationTimeMs,
+                colorDepth: options.colorDepth,
+                createCanvas: options.createCanvas,
+            });
+        },
+    };
+}
+
+/**
+ * Creates stable avatar render inputs from one agent source.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+function createTerminalAgentAvatarVisualRenderInputs(
+    agentSource: string_book,
+    defaultAvatarVisualId: AvatarVisualId,
+): TerminalAgentAvatarVisualRenderInputs {
+    const agentBasicInformation = parseAgentSource(agentSource);
+    const avatarDefinition = createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation);
+    const avatarVisualId = resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(
+        agentBasicInformation,
+        defaultAvatarVisualId,
+    );
+    const resolvedAvatarRenderDefinition = resolveAvatarRenderDefinition({
+        avatarDefinition,
+        visualId: avatarVisualId,
+        surface: 'transparent',
+    });
+
+    return {
+        avatarDefinition,
+        avatarVisualId,
+        resolvedAvatarRenderDefinition,
+    };
+}
+
+/**
+ * Resolves the terminal avatar visual id from already parsed agent information.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+function resolveTerminalAgentAvatarVisualIdFromAgentBasicInformation(
+    agentBasicInformation: AgentBasicInformation,
+    defaultAvatarVisualId: AvatarVisualId,
+): AvatarVisualId {
+    return resolveAgentAvatarVisualId(
+        agentBasicInformation,
+        resolveAvatarVisualId(agentBasicInformation.meta.visual) || defaultAvatarVisualId,
+    );
+}
+
+/**
+ * Renders one terminal avatar frame through the shared avatar-to-ASCII pipeline.
+ *
+ * @private shared helper for terminal avatar rendering
+ */
+function renderTerminalAgentAvatarVisualFrame(
+    options: TerminalAgentAvatarVisualRenderInputs & {
+        readonly animationTimeMs: number;
+        readonly colorDepth?: AsciiArtColorDepth;
+        readonly createCanvas: CreateCanvasForAsciiArt;
+    },
+): ReadonlyArray<string> {
+    return renderAvatarVisualAsciiArt({
+        avatarDefinition: options.avatarDefinition,
+        visualId: options.avatarVisualId,
+        surface: 'transparent',
+        columns: TERMINAL_AGENT_AVATAR_VISUAL_COLUMNS,
+        rows: TERMINAL_AGENT_AVATAR_VISUAL_ROWS,
+        canvasWidth: TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_WIDTH,
+        canvasHeight: TERMINAL_AGENT_AVATAR_VISUAL_CANVAS_HEIGHT,
+        colorDepth: options.colorDepth,
+        timeMs: options.animationTimeMs,
+        createCanvas: options.createCanvas,
+        resolvedAvatarRenderDefinition: options.resolvedAvatarRenderDefinition,
+    });
+}

package/src/utils/ascii-art/$detectTerminalAnsiColorDepth.ts

@@ -0,0 +1,45 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+
+/**
+ * Detects the ANSI color depth supported by the current terminal.
+ *
+ * Prefers 24-bit true color when the environment advertises it (modern terminals such as
+ * Windows Terminal, ConEmu, VS Code, mintty, iTerm2, and WezTerm) and falls back to the
+ * portable 256-color palette otherwise.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it reads the process environment
+ *
+ * @returns Color depth usable by `convertImageDataToAsciiArt`
+ *
+ * @private within the repository
+ */
+export function $detectTerminalAnsiColorDepth(): AsciiArtColorDepth {
+    if (typeof process === 'undefined' || !process.env) {
+        return 'ANSI_256';
+    }
+
+    const colorTerm = (process.env.COLORTERM || '').toLowerCase();
+    if (colorTerm.includes('truecolor') || colorTerm.includes('24bit')) {
+        return 'TRUE_COLOR';
+    }
+
+    if (process.env.WT_SESSION !== undefined) {
+        return 'TRUE_COLOR'; // <- Note: Windows Terminal always supports true color but does not set COLORTERM
+    }
+
+    if (process.env.ConEmuANSI === 'ON') {
+        return 'TRUE_COLOR';
+    }
+
+    const termProgram = process.env.TERM_PROGRAM || '';
+    if (['vscode', 'iTerm.app', 'WezTerm', 'ghostty', 'Hyper'].includes(termProgram)) {
+        return 'TRUE_COLOR';
+    }
+
+    const term = (process.env.TERM || '').toLowerCase();
+    if (term.includes('truecolor') || term.includes('24bit') || term.includes('direct')) {
+        return 'TRUE_COLOR';
+    }
+
+    return 'ANSI_256';
+}