@promptbook/cli 0.112.0-46 → 0.112.0-48

package/esm/index.es.js

@@ -2,7 +2,7 @@ import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import * as fs from 'fs';
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'fs';
+import { mkdirSync, writeFileSync, statSync, readFileSync, existsSync } from 'fs';
 import { join, basename, dirname, isAbsolute, relative, extname, resolve } from 'path';
 import { readFile, writeFile, stat, mkdir, access, constants, readdir, watch, unlink, rm, rename, rmdir, appendFile } from 'fs/promises';
 import { forTime, forEver } from 'waitasecond';
@@ -41,7 +41,7 @@ import { EventEmitter } from 'events';
 import { Subject, BehaviorSubject } from 'rxjs';
 import { lookup, extension } from 'mime-types';
 import { parse, unparse } from 'papaparse';
-import { Agent as Agent$1, setDefaultOpenAIClient, setDefaultOpenAIKey, fileSearchTool, tool, run } from '@openai/agents';
+import { Agent as Agent$1, setDefaultOpenAIClient, setDefaultOpenAIKey, fileSearchTool, tool, run, webSearchTool } from '@openai/agents';
 import OpenAI from 'openai';
 
 // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -58,7 +58,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-46';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-48';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -1045,7 +1045,7 @@ const ADMIN_GITHUB_NAME = 'hejny';
  *
  * @public exported from `@promptbook/core`
  */
-const CLAIM = `Turn your company's scattered knowledge into AI ready books`;
+const CLAIM = `Create persistent AI agents that turn your company's scattered knowledge into action`;
 //            <- TODO: [🐊] Pick the best claim
 /**
  * Color of the Promptbook
@@ -1098,7 +1098,7 @@ Color.fromHex('#1D4ED8');
  *
  * @public exported from `@promptbook/core`
  */
-const DEFAULT_BOOK_TITLE = `✨ Untitled Book`;
+const DEFAULT_BOOK_TITLE = `🐙 Untitled agent`;
 /**
  * When the title of task is not provided, the default title is used
  *
@@ -2488,37 +2488,68 @@ function buildMissingEnvVariablesBlock(variables) {
 }
 // Note: [🟡] Code for coder init environment bootstrapping [ensureCoderEnvFile](src/cli/cli-commands/coder/ensureCoderEnvFile.ts) should never be published outside of `@promptbook/cli`
 
+/**
+ * @@@
+ *
+ * @public exported from `@promptbook/utils`
+ */
+function escapeRegExp$1(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  * Relative path to `.gitignore` in the initialized project.
  */
 const GITIGNORE_FILE_PATH = '.gitignore';
 /**
- * `.gitignore` block required by standalone Promptbook coder projects.
+ * Promptbook coder temp directory that should stay out of version control.
+ */
+const CODER_TEMP_GITIGNORE_RULE = '/.tmp';
+/**
+ * Promptbook coder cache directory that should stay out of version control.
+ */
+const CODER_CACHE_GITIGNORE_RULE = '/.promptbook/ptbk-coder';
+/**
+ * Standard header used when appending Promptbook coder rules into `.gitignore`.
  */
-const CODER_GITIGNORE_BLOCK = spaceTrim$1(`
-    # Promptbook Coder
-    /.tmp
-`);
+const CODER_GITIGNORE_HEADER = '# Promptbook Coder';
 /**
- * Ensures `.gitignore` contains the standalone Promptbook coder cache entry.
+ * Ensures `.gitignore` contains the standalone Promptbook coder temp and cache entries.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */
 async function ensureCoderGitignoreFile(projectPath) {
     const gitignorePath = join(projectPath, GITIGNORE_FILE_PATH);
     const currentGitignoreContent = await readTextFileIfExists(gitignorePath);
-    if (currentGitignoreContent !== undefined && hasTmpGitignoreRule(currentGitignoreContent)) {
+    const missingRules = getMissingCoderGitignoreRules(currentGitignoreContent || '');
+    if (currentGitignoreContent !== undefined && missingRules.length === 0) {
         return 'unchanged';
     }
-    const nextGitignoreContent = appendBlock(currentGitignoreContent || '', CODER_GITIGNORE_BLOCK);
+    const nextGitignoreContent = appendBlock(currentGitignoreContent || '', buildCoderGitignoreBlock(missingRules));
     await writeFile(gitignorePath, nextGitignoreContent, 'utf-8');
     return currentGitignoreContent === undefined ? 'created' : 'updated';
 }
 /**
- * Detects whether `.gitignore` already covers the standalone coder temp directory.
+ * Returns the Promptbook coder gitignore rules that still need to be added.
  */
-function hasTmpGitignoreRule(gitignoreContent) {
-    return /(^|[\r\n])\/?\.tmp(?:[\r\n]|$)/u.test(gitignoreContent);
+function getMissingCoderGitignoreRules(gitignoreContent) {
+    const requiredRules = [CODER_TEMP_GITIGNORE_RULE, CODER_CACHE_GITIGNORE_RULE];
+    return requiredRules.filter((rule) => !hasGitignoreRule(gitignoreContent, rule));
+}
+/**
+ * Builds the Promptbook coder `.gitignore` block for the missing rules only.
+ */
+function buildCoderGitignoreBlock(missingRules) {
+    return [CODER_GITIGNORE_HEADER, ...missingRules].join('\n');
+}
+/**
+ * Detects whether `.gitignore` already covers one exact rule.
+ */
+function hasGitignoreRule(gitignoreContent, rule) {
+    const normalizedRulePattern = rule.startsWith('/')
+        ? `/?${escapeRegExp$1(rule.slice(1))}`
+        : escapeRegExp$1(rule);
+    return new RegExp(`(^|[\\r\\n])${normalizedRulePattern}(?:[\\r\\n]|$)`, 'u').test(gitignoreContent);
 }
 // Note: [🟡] Code for coder init gitignore bootstrapping [ensureCoderGitignoreFile](src/cli/cli-commands/coder/ensureCoderGitignoreFile.ts) should never be published outside of `@promptbook/cli`
 
@@ -2655,7 +2686,7 @@ async function parseJsonObjectFile(relativeFilePath, fileContent) {
                 ${typescript.flattenDiagnosticMessageText(parsedFile.error.messageText, '\n')}
             `));
     }
-    if (!isPlainObject(parsedFile.config)) {
+    if (!isPlainObject$1(parsedFile.config)) {
         throw new ParseError(spaceTrim$1(`
                 File \`${relativeFilePath}\` must contain one top-level JSON object.
             `));
@@ -2669,7 +2700,7 @@ function getStringRecordOrDefault(value, relativeFilePath, fieldPath) {
     if (value === undefined) {
         return {};
     }
-    if (!isPlainObject(value)) {
+    if (!isPlainObject$1(value)) {
         throw new ParseError(spaceTrim$1(`
                 File \`${relativeFilePath}\` contains invalid \`${fieldPath}\`.
 
@@ -2714,7 +2745,7 @@ function detectJsonFileFormatting(fileContent) {
 /**
  * Checks whether one parsed JSON value is a plain object.
  */
-function isPlainObject(value) {
+function isPlainObject$1(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 // Note: [🟡] Code for coder init JSON merging [mergeStringRecordJsonFile](src/cli/cli-commands/coder/mergeStringRecordJsonFile.ts) should never be published outside of `@promptbook/cli`
@@ -6194,15 +6225,6 @@ function prompt(strings, ...values) {
 // TODO: [🧠][🈴] Where is the best location for this file
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * @@@
- *
- * @public exported from `@promptbook/utils`
- */
-function escapeRegExp$1(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * HTTP header used by Promptbook clients to advertise their release version.
  *
@@ -23197,6 +23219,7 @@ class TemplateCommitmentDefinition extends BaseCommitmentDefinition {
  * Supported USE types:
  * - USE BROWSER: Enables the agent to use a web browser tool
  * - USE SEARCH ENGINE (future): Enables search engine access
+ * - USE DEEPSEARCH: Enables deeper research-oriented search access
  * - USE FILE SYSTEM (future): Enables file system operations
  * - USE MCP (future): Enables MCP server connections
  *
@@ -23219,7 +23242,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of USE commitments.
      */
     get description() {
-        return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, etc.).';
+        return 'Enable the agent to use specific tools or capabilities (BROWSER, SEARCH ENGINE, DEEPSEARCH, etc.).';
     }
     /**
      * Icon for this commitment.
@@ -23240,6 +23263,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
 
             - **USE BROWSER** - Enables the agent to use a web browser tool to access and retrieve information from the internet
             - **USE SEARCH ENGINE** (future) - Enables search engine access
+            - **USE DEEPSEARCH** - Enables deeper research-oriented search access
             - **USE FILE SYSTEM** (future) - Enables file system operations
             - **USE MCP** (future) - Enables MCP server connections
 
@@ -23294,7 +23318,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
      * Checks if this is a known USE type
      */
     isKnownUseType(useType) {
-        const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'FILE SYSTEM', 'MCP'];
+        const knownTypes = ['BROWSER', 'SEARCH ENGINE', 'DEEPSEARCH', 'FILE SYSTEM', 'MCP'];
         return knownTypes.includes(useType.toUpperCase());
     }
 }
@@ -23307,6 +23331,7 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
  */
 const AGGREGATED_USE_COMMITMENT_TYPES = [
     'USE BROWSER',
+    'USE DEEPSEARCH',
     'USE SEARCH ENGINE',
     'USE TIME',
 ];
@@ -23386,6 +23411,15 @@ function createAggregatedUseCommitmentSystemMessage(type, additionalInstructions
                     - Do not tell the user you cannot search for information, YOU CAN.
                     ${block(formatOptionalInstructionBlock('Search instructions', combinedAdditionalInstructions))}
                 `);
+        case 'USE DEEPSEARCH':
+            return spaceTrim$1((block) => `
+                    Tool:
+                    - You have access to DeepSearch via the tool "deep_search".
+                    - Use it for broader research tasks that need multi-step investigation, comparison, or synthesis across multiple sources.
+                    - Prefer it over quick search when the user asks for a well-grounded brief, report, or deeper investigation.
+                    - Do not pretend you cannot research current information when this tool is available.
+                    ${block(formatOptionalInstructionBlock('DeepSearch instructions', combinedAdditionalInstructions))}
+                `);
     }
 }
 /**
@@ -24935,6 +24969,207 @@ function addConfiguredCalendarIfMissing(configuredCalendars, calendarReference)
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * A search engine implementation that uses the SerpApi to fetch Google search results.
+ *
+ * @private <- TODO: !!!! Export via some package
+ */
+class SerpSearchEngine {
+    get title() {
+        return 'SerpApi Search Engine';
+    }
+    get description() {
+        return 'Search engine that uses SerpApi to fetch Google search results';
+    }
+    checkConfiguration() {
+        if (!process.env.SERP_API_KEY) {
+            throw new Error('SERP_API_KEY is not configured');
+        }
+    }
+    async search(query, options = {}) {
+        const apiKey = process.env.SERP_API_KEY;
+        if (!apiKey) {
+            throw new Error('SERP_API_KEY is not configured');
+        }
+        const url = new URL('https://serpapi.com/search');
+        url.searchParams.set('api_key', apiKey);
+        url.searchParams.set('engine', 'google');
+        url.searchParams.set('q', query);
+        for (const [key, value] of Object.entries(options)) {
+            url.searchParams.set(key, String(value));
+        }
+        const response = await fetch(url.toString());
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`SerpApi failed with status ${response.status}: ${response.statusText}\n${body}`);
+        }
+        const data = (await response.json());
+        return (data.organic_results || []).map((item) => ({
+            title: item.title,
+            url: item.link,
+            snippet: item.snippet || '',
+        }));
+    }
+}
+
+/**
+ * Creates one SERP-backed tool function used as a local fallback for search-like commitments.
+ *
+ * @param toolName - Technical tool name used for validation messages.
+ * @param resultLabel - Human-readable label used in formatted results.
+ * @returns Async tool function compatible with commitment tool registration.
+ *
+ * @private internal helper for search-like commitments
+ */
+function createSerpSearchToolFunction(toolName, resultLabel) {
+    return async (rawArgs) => {
+        const { query, ...searchOptions } = rawArgs;
+        if (typeof query !== 'string' || !query.trim()) {
+            throw new Error(`${toolName} query is required`);
+        }
+        const searchEngine = new SerpSearchEngine();
+        const results = await searchEngine.search(query, searchOptions);
+        return spaceTrim$1((block) => `
+                ${resultLabel} results for "${query}"${Object.keys(searchOptions).length === 0
+            ? ''
+            : ` with options ${JSON.stringify(searchOptions)}`}:
+
+                ${block(results
+            .map((result) => spaceTrim$1(`
+                                - **${result.title}**
+                                  ${result.url}
+                                  ${result.snippet}
+                            `))
+            .join('\n\n'))}
+            `);
+    };
+}
+
+/**
+ * USE DEEPSEARCH commitment definition
+ *
+ * The `USE DEEPSEARCH` commitment indicates that the agent should use a deeper research-oriented
+ * search workflow instead of lightweight web search when it needs fresh information from the internet.
+ *
+ * The content following `USE DEEPSEARCH` is an arbitrary text that the agent should know
+ * (e.g. search scope or research instructions).
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * USE DEEPSEARCH
+ * USE DEEPSEARCH Compare official vendor documentation with independent benchmarks.
+ * ```
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+class UseDeepSearchCommitmentDefinition extends BaseCommitmentDefinition {
+    constructor() {
+        super('USE DEEPSEARCH');
+    }
+    get requiresContent() {
+        return false;
+    }
+    /**
+     * Short one-line description of USE DEEPSEARCH.
+     */
+    get description() {
+        return 'Enable the agent to use DeepSearch for more thorough internet research.';
+    }
+    /**
+     * Icon for this commitment.
+     */
+    get icon() {
+        return '🔬';
+    }
+    /**
+     * Markdown documentation for USE DEEPSEARCH commitment.
+     */
+    get documentation() {
+        return spaceTrim$1(`
+            # USE DEEPSEARCH
+
+            Enables the agent to use DeepSearch for broader, more thorough internet research than lightweight web search.
+
+            ## Key aspects
+
+            - The content following \`USE DEEPSEARCH\` is arbitrary guidance for the research workflow.
+            - In Agents Server, the OpenAI Agents SDK runtime uses a nested deep-research agent for this tool.
+            - Use this for investigations, comparisons, market scans, or other tasks that benefit from deeper synthesis.
+            - Prefer regular \`USE SEARCH ENGINE\` when a quick factual lookup is enough.
+
+            ## Examples
+
+            \`\`\`book
+            Due Diligence Researcher
+
+            GOAL Investigate vendors thoroughly before making recommendations.
+            USE DEEPSEARCH Compare official sources with credible third-party analysis.
+            RULE Cite the strongest supporting sources in the final answer.
+            \`\`\`
+
+            \`\`\`book
+            Market Analyst
+
+            GOAL Build concise but well-grounded research briefs.
+            USE DEEPSEARCH Focus on recent public information and competing viewpoints.
+            CLOSED
+            \`\`\`
+        `);
+    }
+    applyToAgentModelRequirements(requirements, content) {
+        const existingTools = requirements.tools || [];
+        const updatedTools = existingTools.some((tool) => tool.name === 'deep_search')
+            ? existingTools
+            : [
+                ...existingTools,
+                {
+                    name: 'deep_search',
+                    description: spaceTrim$1(`
+                          Research the internet deeply and synthesize a grounded answer.
+                          Use this tool for broader investigations, comparisons, and requests that need more than a quick search.
+                      `),
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'The research question or investigation request.',
+                            },
+                        },
+                        required: ['query'],
+                        additionalProperties: false,
+                    },
+                },
+            ];
+        return appendAggregatedUseCommitmentPlaceholder({
+            ...requirements,
+            tools: updatedTools,
+            _metadata: {
+                ...requirements._metadata,
+                useDeepSearch: content || true,
+            },
+        }, this.type);
+    }
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles() {
+        return {
+            deep_search: 'DeepSearch',
+        };
+    }
+    /**
+     * Gets the local fallback implementation for the `deep_search` tool.
+     */
+    getToolFunctions() {
+        return {
+            deep_search: createSerpSearchToolFunction('deep_search', 'DeepSearch'),
+        };
+    }
+}
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
  * Lightweight email token matcher used for `USE EMAIL` first-line parsing.
  *
@@ -27322,49 +27557,6 @@ function addConfiguredProjectIfMissing(configuredProjects, repositoryReference)
 }
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * A search engine implementation that uses the SerpApi to fetch Google search results.
- *
- * @private <- TODO: !!!! Export via some package
- */
-class SerpSearchEngine {
-    get title() {
-        return 'SerpApi Search Engine';
-    }
-    get description() {
-        return 'Search engine that uses SerpApi to fetch Google search results';
-    }
-    checkConfiguration() {
-        if (!process.env.SERP_API_KEY) {
-            throw new Error('SERP_API_KEY is not configured');
-        }
-    }
-    async search(query, options = {}) {
-        const apiKey = process.env.SERP_API_KEY;
-        if (!apiKey) {
-            throw new Error('SERP_API_KEY is not configured');
-        }
-        const url = new URL('https://serpapi.com/search');
-        url.searchParams.set('api_key', apiKey);
-        url.searchParams.set('engine', 'google');
-        url.searchParams.set('q', query);
-        for (const [key, value] of Object.entries(options)) {
-            url.searchParams.set(key, String(value));
-        }
-        const response = await fetch(url.toString());
-        if (!response.ok) {
-            const body = await response.text();
-            throw new Error(`SerpApi failed with status ${response.status}: ${response.statusText}\n${body}`);
-        }
-        const data = (await response.json());
-        return (data.organic_results || []).map((item) => ({
-            title: item.title,
-            url: item.link,
-            snippet: item.snippet || '',
-        }));
-    }
-}
-
 /**
  * USE SEARCH ENGINE commitment definition
  *
@@ -27508,26 +27700,7 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
      */
     getToolFunctions() {
         return {
-            async web_search(args) {
-                console.log('!!!! [Tool] web_search called', { args });
-                const { query, ...options } = args;
-                if (!query) {
-                    throw new Error('Search query is required');
-                }
-                const searchEngine = new SerpSearchEngine();
-                const results = await searchEngine.search(query, options);
-                return spaceTrim$1((block) => `
-                        Search results for "${query}"${Object.keys(options).length === 0 ? '' : ` with options ${JSON.stringify(options)}`}:
-
-                        ${block(results
-                    .map((result) => spaceTrim$1(`
-                                            - **${result.title}**
-                                              ${result.url}
-                                              ${result.snippet}
-                                        `))
-                    .join('\n\n'))}
-                    `);
-            },
+            web_search: createSerpSearchToolFunction('web_search', 'Search'),
         };
     }
 }
@@ -29173,6 +29346,7 @@ const COMMITMENT_REGISTRY = [
     new ClosedCommitmentDefinition(),
     new TeamCommitmentDefinition(),
     new UseBrowserCommitmentDefinition(),
+    new UseDeepSearchCommitmentDefinition(),
     new UseSearchEngineCommitmentDefinition(),
     new UseSpawnCommitmentDefinition(),
     new UseTimeoutCommitmentDefinition(),
@@ -42226,6 +42400,11 @@ const SIMPLE_CAPABILITY_BY_COMMITMENT_TYPE = {
         label: 'Internet',
         iconName: 'Search',
     },
+    'USE DEEPSEARCH': {
+        type: 'search-engine',
+        label: 'DeepSearch',
+        iconName: 'Search',
+    },
     'USE TIME': {
         type: 'time',
         label: 'Time',
@@ -43289,6 +43468,246 @@ const EMOJIS_OF_SINGLE_PICTOGRAM = new Set(Array.from(EMOJIS).filter((emoji) =>
 // TODO: Mirror from Collboard or some common package
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
+/**
+ * Default file globs scanned for emoji tags.
+ */
+const DEFAULT_INCLUDE_GLOBS = ['**/*.{ts,tsx,js,jsx,json,md,txt}'];
+/**
+ * Default ignored paths while scanning the repository.
+ */
+const DEFAULT_IGNORE_GLOBS = ['**/node_modules/**', '**/.git/**', '**/.promptbook/ptbk-coder/**'];
+/**
+ * Directory used for Promptbook coder runtime caches.
+ */
+const PTBK_CODER_CACHE_DIRECTORY_PATH = '.promptbook/ptbk-coder';
+/**
+ * Relative cache file path storing per-file emoji-tag scan results.
+ */
+const EMOJI_TAG_SCAN_CACHE_FILE_PATH = `${PTBK_CODER_CACHE_DIRECTORY_PATH}/emoji-tag-scan-cache.json`;
+/**
+ * Current schema version of the persisted emoji-tag scan cache.
+ */
+const EMOJI_TAG_SCAN_CACHE_VERSION = 1;
+/**
+ * Scans repository files for bracketed emoji tags while reusing per-file cache entries for unchanged files.
+ */
+async function scanEmojiTagUsage(options) {
+    var _a, _b, _c, _d;
+    const rootDir = (_a = options.rootDir) !== null && _a !== void 0 ? _a : process.cwd();
+    const includeGlobs = (_b = options.includeGlobs) !== null && _b !== void 0 ? _b : DEFAULT_INCLUDE_GLOBS;
+    const ignoreGlobs = (_c = options.ignoreGlobs) !== null && _c !== void 0 ? _c : DEFAULT_IGNORE_GLOBS;
+    const tagPrefix = (_d = options.tagPrefix) !== null && _d !== void 0 ? _d : '';
+    const filesToScan = await findFilesToScan(rootDir, includeGlobs, ignoreGlobs);
+    const matcher = buildEmojiTagMatcher(options.candidateEmojis, tagPrefix);
+    const usedEmojis = new Set();
+    const existingCache = await readEmojiTagScanCache(rootDir);
+    const nextCacheFiles = { ...existingCache.files };
+    let isCacheDirty = false;
+    let scannedFileCount = 0;
+    let reusedFileCount = 0;
+    for (const filePath of filesToScan) {
+        try {
+            const fileStats = statSync(filePath);
+            const cacheKey = toCacheKey(rootDir, filePath);
+            const cachedFile = nextCacheFiles[cacheKey];
+            const cachedEmojis = getCachedFileEmojis(cachedFile, fileStats.mtimeMs, fileStats.size, tagPrefix);
+            if (cachedEmojis) {
+                reusedFileCount += 1;
+                addEmojis(usedEmojis, cachedEmojis);
+                continue;
+            }
+            const fileContent = readFileSync(filePath, 'utf-8'); /* Note: sync file reads are fine for local tooling. */
+            const scannedEmojis = scanFileForEmojiTags(fileContent, matcher);
+            addEmojis(usedEmojis, scannedEmojis);
+            nextCacheFiles[cacheKey] = updateCachedFile(cachedFile, fileStats.mtimeMs, fileStats.size, tagPrefix, scannedEmojis);
+            scannedFileCount += 1;
+            isCacheDirty = true;
+        }
+        catch (error) {
+            if (options.onFileError) {
+                options.onFileError(normalizeError(error), filePath);
+                continue;
+            }
+            throw error;
+        }
+    }
+    if (isCacheDirty) {
+        await writeEmojiTagScanCache(rootDir, {
+            version: EMOJI_TAG_SCAN_CACHE_VERSION,
+            files: nextCacheFiles,
+        });
+    }
+    return {
+        usedEmojis,
+        scannedFileCount,
+        reusedFileCount,
+    };
+}
+/**
+ * Resolves files to scan for matching emoji tags.
+ */
+async function findFilesToScan(rootDir, includeGlobs, ignoreGlobs) {
+    const files = new Set();
+    for (const pattern of includeGlobs) {
+        const matches = await glob(pattern, {
+            cwd: rootDir,
+            ignore: Array.from(new Set([...ignoreGlobs, ...DEFAULT_IGNORE_GLOBS])),
+            nodir: true,
+            absolute: true,
+        });
+        for (const match of matches) {
+            files.add(match);
+        }
+    }
+    return Array.from(files);
+}
+/**
+ * Builds a regex that matches one exact bracketed emoji-tag form.
+ */
+function buildEmojiTagMatcher(candidateEmojis, tagPrefix) {
+    const escapedEmojiAlternatives = Array.from(candidateEmojis)
+        .sort((leftEmoji, rightEmoji) => rightEmoji.length - leftEmoji.length)
+        .map((emoji) => escapeRegExp$1(emoji))
+        .join('|');
+    if (escapedEmojiAlternatives === '') {
+        return /$^/u;
+    }
+    return new RegExp(`\\[${escapeRegExp$1(tagPrefix)}(?<emoji>${escapedEmojiAlternatives})\\]`, 'gu');
+}
+/**
+ * Extracts matching emojis from one file content.
+ */
+function scanFileForEmojiTags(fileContent, matcher) {
+    var _a;
+    matcher.lastIndex = 0;
+    const matchedEmojis = new Set();
+    for (const match of fileContent.matchAll(matcher)) {
+        const emoji = (_a = match.groups) === null || _a === void 0 ? void 0 : _a.emoji;
+        if (emoji) {
+            matchedEmojis.add(emoji);
+        }
+    }
+    return Array.from(matchedEmojis);
+}
+/**
+ * Returns cached emojis when the file metadata still matches the stored cache entry.
+ */
+function getCachedFileEmojis(cachedFile, mtimeMs, size, tagPrefix) {
+    if (!cachedFile || cachedFile.mtimeMs !== mtimeMs || cachedFile.size !== size) {
+        return undefined;
+    }
+    const cachedEmojis = cachedFile.tagsByPrefix[tagPrefix];
+    return Array.isArray(cachedEmojis) ? cachedEmojis : undefined;
+}
+/**
+ * Stores the latest scan result for one file while preserving other prefix caches when the file revision is unchanged.
+ */
+function updateCachedFile(cachedFile, mtimeMs, size, tagPrefix, emojis) {
+    const isSameFileRevision = (cachedFile === null || cachedFile === void 0 ? void 0 : cachedFile.mtimeMs) === mtimeMs && cachedFile.size === size;
+    return {
+        mtimeMs,
+        size,
+        tagsByPrefix: {
+            ...(isSameFileRevision ? cachedFile.tagsByPrefix : {}),
+            [tagPrefix]: [...emojis],
+        },
+    };
+}
+/**
+ * Loads the persisted emoji-tag scan cache and falls back to an empty cache when it is missing or invalid.
+ */
+async function readEmojiTagScanCache(rootDir) {
+    try {
+        const cacheContent = await readFile(join(rootDir, EMOJI_TAG_SCAN_CACHE_FILE_PATH), 'utf-8');
+        return normalizeEmojiTagScanCache(JSON.parse(cacheContent));
+    }
+    catch (_a) {
+        return createEmptyEmojiTagScanCache();
+    }
+}
+/**
+ * Persists the updated emoji-tag scan cache as a best-effort optimization.
+ */
+async function writeEmojiTagScanCache(rootDir, cache) {
+    try {
+        await mkdir(join(rootDir, PTBK_CODER_CACHE_DIRECTORY_PATH), { recursive: true });
+        await writeFile(join(rootDir, EMOJI_TAG_SCAN_CACHE_FILE_PATH), `${JSON.stringify(cache, null, 2)}\n`, 'utf-8');
+    }
+    catch (_a) {
+        // Note: Cache writes are only an optimization; scanning still succeeds when the cache cannot be written.
+    }
+}
+/**
+ * Normalizes one parsed cache payload into the current typed cache shape.
+ */
+function normalizeEmojiTagScanCache(value) {
+    if (!isPlainObject(value) || value.version !== EMOJI_TAG_SCAN_CACHE_VERSION || !isPlainObject(value.files)) {
+        return createEmptyEmojiTagScanCache();
+    }
+    const files = {};
+    for (const [filePath, cachedValue] of Object.entries(value.files)) {
+        if (!isPlainObject(cachedValue)) {
+            continue;
+        }
+        const { mtimeMs, size, tagsByPrefix } = cachedValue;
+        if (typeof mtimeMs !== 'number' || typeof size !== 'number' || !isPlainObject(tagsByPrefix)) {
+            continue;
+        }
+        const normalizedTagsByPrefix = {};
+        for (const [tagPrefix, cachedEmojis] of Object.entries(tagsByPrefix)) {
+            if (!Array.isArray(cachedEmojis)) {
+                continue;
+            }
+            normalizedTagsByPrefix[tagPrefix] = cachedEmojis.filter((emoji) => typeof emoji === 'string');
+        }
+        files[filePath] = {
+            mtimeMs,
+            size,
+            tagsByPrefix: normalizedTagsByPrefix,
+        };
+    }
+    return {
+        version: EMOJI_TAG_SCAN_CACHE_VERSION,
+        files,
+    };
+}
+/**
+ * Creates an empty cache payload for emoji-tag scans.
+ */
+function createEmptyEmojiTagScanCache() {
+    return {
+        version: EMOJI_TAG_SCAN_CACHE_VERSION,
+        files: {},
+    };
+}
+/**
+ * Converts an absolute file path into a stable cache key relative to the scanned root.
+ */
+function toCacheKey(rootDir, filePath) {
+    return relative(rootDir, filePath).replace(/\\/gu, '/');
+}
+/**
+ * Adds multiple emojis into one target set.
+ */
+function addEmojis(target, emojis) {
+    for (const emoji of emojis) {
+        target.add(emoji);
+    }
+}
+/**
+ * Checks whether one unknown JSON value is a plain object.
+ */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Normalizes thrown values into proper `Error` objects for optional callbacks.
+ */
+function normalizeError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+// Note: [?] Code in this file should never be published in any package
+
 // find-fresh-emoji-tags.ts
 // Note: When run as a standalone script, call the exported function
 if (require.main === module) {
@@ -43318,29 +43737,16 @@ function initializeFindFreshEmojiTagRun() {
 async function findFreshEmojiTag() {
     initializeFindFreshEmojiTagRun();
     console.info(`🤪  Find fresh emoji tag`);
-    const allFiles = await glob('**/*.{ts,tsx,js,jsx,json,md,txt}', {
-        ignore: '**/node_modules/**', // <- TODO: [🚰] Ignore also hidden folders like *(`.promptbook`, `.next`, `.git`,...)*
-    });
     const allEmojis = EMOJIS_OF_SINGLE_PICTOGRAM;
-    // const allEmojis = new Set<string_char_emoji>(['🧎' as string_char_emoji, '🥎' as string_char_emoji]);
-    const usedEmojis = new Set();
-    for (const file of allFiles) {
-        try {
-            const content = readFileSync(file, 'utf-8'); /* <- Note: Its OK to use sync in tooling for scripts */
-            for (const emoji of allEmojis) {
-                const tag = `[${emoji}]`;
-                if (content.includes(tag)) {
-                    usedEmojis.add(emoji);
-                }
-            }
-        }
-        catch (error) {
-            console.error(colors.red('Error in checking file file /' + file));
+    const { usedEmojis } = await scanEmojiTagUsage({
+        candidateEmojis: allEmojis,
+        tagPrefix: '',
+        onFileError: (error, filePath) => {
+            console.error(colors.red('Error in checking file /' + filePath));
             console.error(error);
-        }
-    }
-    //console.info({ usedEmojis });
-    const freshEmojis = difference(allEmojis, usedEmojis);
+        },
+    });
+    const freshEmojis = new Set(Array.from(allEmojis).filter((emoji) => !usedEmojis.has(emoji)));
     console.info(colors.green(`Avialable fresh tags:`));
     const randomEmojis = [...$shuffleItems(...Array.from(freshEmojis))].splice(0, 10);
     // const randomEmojis = freshEmojis;
@@ -43948,9 +44354,14 @@ async function getFreshPromptEmojiTags(options) {
     const includeGlobs = (_b = options.includeGlobs) !== null && _b !== void 0 ? _b : ['**/*.{ts,tsx,js,jsx,json,md,txt}'];
     const ignoreGlobs = (_c = options.ignoreGlobs) !== null && _c !== void 0 ? _c : ['**/node_modules/**'];
     const tagPrefix = (_d = options.tagPrefix) !== null && _d !== void 0 ? _d : PROMPT_EMOJI_TAG_PREFIX;
-    const filesToScan = await findFilesToScan(rootDir, includeGlobs, ignoreGlobs);
-    const usedEmojis = collectUsedPromptEmojis(filesToScan, tagPrefix);
-    const freshEmojis = difference(EMOJIS_OF_SINGLE_PICTOGRAM, usedEmojis);
+    const { usedEmojis } = await scanEmojiTagUsage({
+        rootDir,
+        includeGlobs,
+        ignoreGlobs,
+        tagPrefix,
+        candidateEmojis: EMOJIS_OF_SINGLE_PICTOGRAM,
+    });
+    const freshEmojis = new Set(Array.from(EMOJIS_OF_SINGLE_PICTOGRAM).filter((emoji) => !usedEmojis.has(emoji)));
     const shuffledEmojis = $shuffleItems(...Array.from(freshEmojis));
     const selectedEmojis = shuffledEmojis.slice(0, count);
     if (selectedEmojis.length < count) {
@@ -43962,40 +44373,6 @@ async function getFreshPromptEmojiTags(options) {
         tagPrefix,
     };
 }
-/**
- * Resolves files to scan for existing prompt emoji tags.
- */
-async function findFilesToScan(rootDir, includeGlobs, ignoreGlobs) {
-    const files = new Set();
-    for (const pattern of includeGlobs) {
-        const matches = await glob(pattern, {
-            cwd: rootDir,
-            ignore: ignoreGlobs,
-            nodir: true,
-            absolute: true,
-        });
-        for (const match of matches) {
-            files.add(match);
-        }
-    }
-    return Array.from(files);
-}
-/**
- * Collects emojis already used with the configured prompt prefix.
- */
-function collectUsedPromptEmojis(filePaths, tagPrefix) {
-    const usedEmojis = new Set();
-    for (const file of filePaths) {
-        const content = readFileSync(file, 'utf-8'); /* Note: sync read is fine for script tooling. */
-        for (const emoji of EMOJIS_OF_SINGLE_PICTOGRAM) {
-            const tag = formatPromptEmojiTag(emoji, tagPrefix);
-            if (content.includes(tag)) {
-                usedEmojis.add(emoji);
-            }
-        }
-    }
-    return usedEmojis;
-}
 // Note: [?] Code in this file should never be published in any package
 
 var promptEmojiTags = /*#__PURE__*/Object.freeze({
@@ -45024,6 +45401,27 @@ async function waitForEnter(prompt) {
  * Current pause state.
  */
 let pauseState = 'RUNNING';
+/**
+ * Stores one new pause state in the shared runner controller.
+ */
+function setPauseState(nextPauseState) {
+    pauseState = nextPauseState;
+}
+/**
+ * Applies the same three-state toggle used by the `P` hotkey.
+ */
+function togglePauseState() {
+    if (pauseState === 'RUNNING') {
+        setPauseState('PAUSING');
+        return 'REQUESTED_PAUSE';
+    }
+    if (pauseState === 'PAUSING') {
+        setPauseState('RUNNING');
+        return 'CANCELLED_PAUSE';
+    }
+    setPauseState('RUNNING');
+    return 'RESUMED';
+}
 /**
  * Listens for the "p" key to pause and resume.
  */
@@ -45038,19 +45436,13 @@ function listenForPause() {
             process.exit();
         }
         if (key.name === 'p') {
-            if (pauseState === 'RUNNING') {
-                pauseState = 'PAUSING';
+            const toggleResult = togglePauseState();
+            if (toggleResult === 'REQUESTED_PAUSE') {
                 // Note: Using console.log here which adds a new line.
                 // This is intentional to prevent the message from being overwritten.
                 console.log(colors.bgWhite('Pausing...'));
             }
-            else if (pauseState === 'PAUSED') {
-                pauseState = 'RUNNING';
-                // The checkPause loop will terminate.
-            }
-            else if (pauseState === 'PAUSING') {
-                // If user presses 'p' again while pausing, cancel the pause.
-                pauseState = 'RUNNING';
+            else if (toggleResult === 'CANCELLED_PAUSE') {
                 console.log(colors.green('Pause cancelled. Resuming...'));
             }
         }
@@ -45066,12 +45458,12 @@ function listenForPause() {
 async function checkPause(options) {
     var _a, _b;
     if (pauseState === 'PAUSING') {
-        pauseState = 'PAUSED';
+        setPauseState('PAUSED');
         if (!(options === null || options === void 0 ? void 0 : options.silent)) {
             console.log(colors.bgWhite.black('Paused') + colors.gray(' (Press "p" to resume)'));
         }
         (_a = options === null || options === void 0 ? void 0 : options.onPaused) === null || _a === void 0 ? void 0 : _a.call(options);
-        while (pauseState === 'PAUSED') {
+        while (getPauseState() === 'PAUSED') {
             await new Promise((resolve) => setTimeout(resolve, 100));
         }
         (_b = options === null || options === void 0 ? void 0 : options.onResumed) === null || _b === void 0 ? void 0 : _b.call(options);
@@ -45086,20 +45478,6 @@ async function checkPause(options) {
 function getPauseState() {
     return pauseState;
 }
-/**
- * Requests a pause from an external controller (e.g. the Ink UI).
- */
-function requestPause() {
-    if (pauseState === 'RUNNING') {
-        pauseState = 'PAUSING';
-    }
-}
-/**
- * Resumes execution from an external controller after a pause.
- */
-function requestResume() {
-    pauseState = 'RUNNING';
-}
 
 /**
  * Environment variable that configures the name used for agent commits.
@@ -48739,49 +49117,215 @@ function buildPromptTestScriptPath(scriptPath) {
     return `${scriptPath}.test.sh`;
 }
 
+/**
+ * Centers an ANSI-colored line within the available frame width.
+ *
+ * @private internal utility of coder run UI
+ */
+function centerAnsiText(text, width) {
+    const paddingWidth = Math.max(0, Math.floor((width - visibleLength(text)) / 2));
+    return `${' '.repeat(paddingWidth)}${text}`;
+}
+/**
+ * Pads or truncates a possibly ANSI-colored line to the target visible width.
+ *
+ * @private internal utility of coder run UI
+ */
+function padAnsiText(text, width) {
+    const fittedText = fitAnsiText(text, width);
+    return fittedText + ' '.repeat(Math.max(0, width - visibleLength(fittedText)));
+}
+/**
+ * Truncates a possibly ANSI-colored line to the target visible width.
+ *
+ * @private internal utility of coder run UI
+ */
+function fitAnsiText(text, width) {
+    if (visibleLength(text) <= width) {
+        return text;
+    }
+    return fitPlainText(stripAnsi(text), width);
+}
+/**
+ * Truncates a plain-text line to the target width with an ellipsis.
+ *
+ * @private internal utility of coder run UI
+ */
+function fitPlainText(text, width) {
+    if (text.length <= width) {
+        return text;
+    }
+    if (width <= 3) {
+        return '.'.repeat(width);
+    }
+    return `${text.slice(0, width - 3)}...`;
+}
+/**
+ * Measures visible string width by stripping ANSI escape codes.
+ *
+ * @private internal utility of coder run UI
+ */
+function visibleLength(text) {
+    return stripAnsi(text).length;
+}
+/**
+ * Strips ANSI escape codes from a string.
+ *
+ * @private internal utility of coder run UI
+ */
+function stripAnsi(text) {
+    // eslint-disable-next-line no-control-regex
+    return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+/**
+ * Fixed left-side head used across all octopus frames.
+ */
+const OCTOPUS_HEAD_LINES = [
+    colors.magenta.bold('      .-""""-.'),
+    colors.magenta.bold("    .'  .-.  '."),
+    `${colors.magenta.bold('   /   (')}${colors.yellow.bold('o o')}${colors.magenta.bold(')   \\')}`,
+    colors.magenta.bold('  |      ^      |'),
+    colors.magenta.bold('  |   \\___/     |'),
+    colors.magenta.bold('   \\___________/'),
+];
+/**
+ * Gap between the head silhouette and the animated tentacles.
+ */
+const OCTOPUS_HEAD_TO_TENTACLE_GAP = '   ';
+/**
+ * Animated right-side tentacle poses.
+ */
+const OCTOPUS_TENTACLE_FRAMES = [
+    [
+        `                 ${colors.green.bold('ptbk.io')}`,
+        colors.cyan('          __      __'),
+        colors.cyan('   _/\\/\\/  \\_/\\/  \\_/\\_'),
+        colors.cyan('_/\\/  _   /\\/  _  /\\/\\__'),
+        colors.cyan('\\__/ /_/\\/  \\_/ \\_/  \\_/'),
+        colors.cyan('   /_/   \\__/   \\__/  /'),
+    ],
+    [
+        `                 ${colors.green.bold('ptbk.io')}`,
+        colors.cyan('          __      __'),
+        colors.cyan('   _/\\/  \\_/\\/\\_  \\_/\\_'),
+        colors.cyan('_/\\/  _  /\\/  _ \\/\\/  \\__'),
+        colors.cyan('\\__/ /_/\\/  \\_/  \\_ /\\_/'),
+        colors.cyan('     /_/  \\__/   \\__/  /'),
+    ],
+    [
+        `                 ${colors.green.bold('ptbk.io')}`,
+        colors.cyan('          __      __'),
+        colors.cyan('   _/\\/\\/  \\_/\\_  \\_/\\_'),
+        colors.cyan('_/\\/  _   /\\/  _  /\\/  \\_'),
+        colors.cyan('\\__/ /_/\\/  \\_/ \\_/  _/'),
+        colors.cyan('   /_/    \\__/    \\__/'),
+    ],
+    [
+        `                 ${colors.green.bold('ptbk.io')}`,
+        colors.cyan('          __      __'),
+        colors.cyan('   _/\\/  \\_/\\/  \\_/\\/\\_'),
+        colors.cyan('_/\\/  _  /\\/  _  /\\/\\  \\'),
+        colors.cyan('\\__/ /_/\\/  \\_/ \\_  \\_/'),
+        colors.cyan('    /_/   \\__/   \\__\\_/'),
+    ],
+];
+/**
+ * Builds the horizontal octopus illustration shown above the coder-run dashboard.
+ *
+ * @private internal utility of coder run UI
+ */
+function buildCoderRunOctopusVisual(options) {
+    const tentacleFrame = OCTOPUS_TENTACLE_FRAMES[((options.animationFrame % OCTOPUS_TENTACLE_FRAMES.length) + OCTOPUS_TENTACLE_FRAMES.length) %
+        OCTOPUS_TENTACLE_FRAMES.length];
+    const visualLines = OCTOPUS_HEAD_LINES.map((headLine, lineIndex) => `${headLine}${OCTOPUS_HEAD_TO_TENTACLE_GAP}${tentacleFrame[lineIndex]}`);
+    const visualWidth = visualLines.reduce((maxWidth, line) => Math.max(maxWidth, visibleLength(line)), 0);
+    visualLines.map((line) => centerAnsiText(padAnsiText(line, visualWidth), options.totalWidth));
+    /*
+    Note: Octopus art should look better, now using just text
+    https://www.google.com/search?sca_esv=52e84acb78c558cc&sxsrf=ANbL-n7DVKf71T1HSPRpM-2skfMss0jh7w:1776693767588&udm=2&fbs=ADc_l-ZseckkBJUFopaGDNYa-HGjo4_b6b_a7pIHTL5Y9QnExg6xJqXbG7aOLcH8CWqOtkzCrjxXWZVmrIhYPvZzFDVUIb7oTJfuJ6idsCc5GA1j5KGoi2q3sW0uDBWWfYgbuxGWTQPZMetvj33BdP833wZm47mxW-6rC3bTQWluwJdOsgloPieyQvTfF2uNgIZ_K0KZ-WzpL1An8GuRrKqHdvl8T306FA&q=octopus&sa=X&ved=2ahUKEwil7ZCHzPyTAxUghP0HHY-_Js8QtKgLegQIOhAB&biw=1745&bih=903&dpr=1.1#sv=CAMSVhoyKhBlLVl1bHNmeVhneml6a1dNMg5ZdWxzZnlYZ3ppemtXTToOTVJvdXhTdk5STkZ4d00gBCocCgZtb3NhaWMSEGUtWXVsc2Z5WGd6aXprV00YADABGAcg46LBxA9KCBABGAEgASgB
+    https://www.mrgoodfish.com/wp-content/uploads/2022/09/Eledone_moschata__.png
+    https://fish-commercial-names.ec.europa.eu/fish-names/jakarta.faces.resource/pictograms/octopus_vulgaris.jpg.xhtml?ln=images
+    https://www.asciiart.eu/image-to-ascii
+    */
+    // Note: Created by https://patorjk.com/software/taag/#p=display&f=ANSI+Compact&t=ptbk.io&x=none&v=4&h=4&w=80&we=false
+    return _spaceTrim(`                        
+                                   
+        ▄▄▄▄ ▄▄▄▄▄▄ ▄▄▄▄  ▄▄ ▄▄   ▄▄  ▄▄▄  
+        ██▄█▀  ██   ██▄██ ██▄█▀   ██ ██▀██ 
+        ██     ██   ██▄█▀ ██ ██ ▄ ██ ▀███▀ 
+                                            
+    `)
+        .split('\n')
+        .map((line) => centerAnsiText(line, options.totalWidth));
+}
+
+/**
+ * Refresh cadence used only while the rich coder UI needs animated updates.
+ *
+ * @private internal constant of coder run UI
+ */
+const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = 300;
+/**
+ * Phases that still benefit from automatic refreshes because the frame can change
+ * over time even without new runner output.
+ *
+ * @private internal constant of coder run UI
+ */
+const AUTO_REFRESH_PHASES = ['initializing', 'loading', 'running', 'verifying'];
+/**
+ * Returns whether the rich coder UI should keep animating on its own.
+ *
+ * @private internal utility of coder run UI
+ */
+function isCoderRunUiAutoRefreshing(phase, pauseState) {
+    // `PAUSING` still means the current task is winding down, so keep active
+    // animations/timers running until the runner reaches the fully paused state.
+    if (pauseState === 'PAUSED') {
+        return false;
+    }
+    return AUTO_REFRESH_PHASES.includes(phase);
+}
+/**
+ * Returns the automatic refresh interval for the current UI state.
+ *
+ * Waiting, paused, and completed states return `undefined` so the rich UI stays
+ * perfectly still until actual state changes arrive.
+ *
+ * @private internal utility of coder run UI
+ */
+function getCoderRunUiAutoRefreshInterval(phase, pauseState) {
+    return isCoderRunUiAutoRefreshing(phase, pauseState) ? ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS : undefined;
+}
+
 /**
  * Maximum number of output lines reserved for agent output in the UI.
  */
 const MAX_VISIBLE_OUTPUT_LINES = 8;
+/**
+ * Minimum width used for the rich coder-run frame.
+ */
+const MIN_FRAME_WIDTH = 56;
+/**
+ * Maximum width used for the rich coder-run frame.
+ */
+const MAX_FRAME_WIDTH = 96;
+/**
+ * Visible width reserved for aligned labels in the session box.
+ */
+const SESSION_LABEL_WIDTH = 8;
 /**
  * Builds the complete boxed terminal frame for the rich `ptbk coder run` UI.
  */
 function buildCoderRunUiFrame(options) {
-    const totalWidth = Math.max(56, Math.min(options.terminalWidth, 96));
+    const totalWidth = Math.max(MIN_FRAME_WIDTH, Math.min(options.terminalWidth, MAX_FRAME_WIDTH));
     const isPromptActive = options.phase === 'running' || options.phase === 'verifying' || options.phase === 'loading';
     const promptStatusPrefix = isPromptActive ? `${colors.yellow(`${options.spinner} `)}` : '';
-    const sessionScopeLine = options.progress.sessionTotal > 0
-        ? `Working on ${options.progress.currentPromptIndex}/${options.progress.sessionTotal} prompts with Priority ≥${options.config.priority}`
-        : `No runnable prompts with Priority ≥${options.config.priority}`;
-    const sessionCountLine = `Done ${options.progress.sessionDone}/${options.progress.sessionTotal} this run  ·  Repo total ${options.progress.totalPrompts}`;
-    const sessionQueueParts = [];
-    if (options.progress.skippedPrompts > 0) {
-        sessionQueueParts.push(`Skipping ${formatPromptCount(options.progress.skippedPrompts)} with Priority <${options.config.priority}`);
-    }
-    if (options.progress.toBeWrittenPrompts > 0) {
-        sessionQueueParts.push(`Write first ${formatPromptCount(options.progress.toBeWrittenPrompts)}`);
-    }
-    const sessionLines = [
-        `${buildPhaseBadge(options.phase, options.pauseState)} ${fitPlainText(options.statusMessage, totalWidth - 18)}`,
-        sessionScopeLine,
-        sessionCountLine,
-        ...(sessionQueueParts.length > 0 ? [sessionQueueParts.join('  ·  ')] : []),
-        `Elapsed ${options.progress.elapsedText}  ·  Est. total ${options.progress.estimatedTotalText}  ·  Est. done ${options.progress.estimatedLabel}`,
-        buildProgressBar(options.progress.percentage, totalWidth - 6, `${options.progress.percentage}% complete (${options.progress.sessionDone}/${options.progress.sessionTotal} done)`),
-    ];
-    const metadataParts = [options.config.agentName || 'No agent selected'];
-    if (options.config.modelName) {
-        metadataParts.push(options.config.modelName);
-    }
-    if (options.config.thinkingLevel) {
-        metadataParts.push(`thinking ${options.config.thinkingLevel}`);
-    }
-    const runnerDetails = [
-        [`${colors.bgCyan.black(' PTBK ')}`, colors.bgBlue.white(' CODER '), colors.bold.white(' Promptbook Coder')]
-            .join(''),
-        metadataParts.join('  ·  '),
-        buildConfigSummaryLine(options.config),
-    ];
+    const octopusAnimationFrame = isCoderRunUiAutoRefreshing(options.phase, options.pauseState)
+        ? options.animationFrame
+        : 0;
+    const pausePresentation = buildPausePresentation(options.phase, options.pauseState, options.statusMessage);
+    const sessionLines = buildSessionLines(options, totalWidth, pausePresentation);
     const currentTaskLines = options.currentPromptLabel
         ? [
             `${promptStatusPrefix}${colors.bold.white(fitPlainText(options.currentPromptLabel, totalWidth - 8))}`,
@@ -48790,9 +49334,10 @@ function buildCoderRunUiFrame(options) {
         ]
         : [options.statusMessage, ...options.detailLines.map((detailLine) => `• ${detailLine}`)];
     const visibleOutputLines = buildVisibleOutputLines(options.agentOutputLines);
-    const controls = buildControlPills(options.pauseState, options.pendingEnterLabel).join('  ');
+    const controls = buildControlPills(pausePresentation.pauseControl, options.pendingEnterLabel).join('  ');
     const frame = [
-        ...renderBox('Brand', runnerDetails, totalWidth, colors.cyan.bold),
+        ...buildCoderRunOctopusVisual({ totalWidth, animationFrame: octopusAnimationFrame }),
+        '',
         ...renderBox('Session', sessionLines, totalWidth, colors.yellow.bold),
         ...renderBox(options.currentPromptLabel ? 'Current task' : 'Queue', currentTaskLines, totalWidth, colors.magenta.bold),
         ...renderBox('Live output', visibleOutputLines, totalWidth, colors.green.bold),
@@ -48803,13 +49348,67 @@ function buildCoderRunUiFrame(options) {
     frame.push(...renderBox('Controls', [controls], totalWidth, colors.white.bold));
     return frame;
 }
+/**
+ * Builds the structured session lines that combine state, runner, queue, and timing metadata.
+ */
+function buildSessionLines(options, totalWidth, pausePresentation) {
+    const bodyWidth = Math.max(10, totalWidth - 4);
+    return buildSessionRows(options, bodyWidth, pausePresentation).map((sessionRow) => buildLabeledSessionLine(sessionRow.label, sessionRow.value, bodyWidth));
+}
+/**
+ * Builds the session rows so the renderer can keep one consistent structure without duplicating labels.
+ */
+function buildSessionRows(options, bodyWidth, pausePresentation) {
+    const runnerParts = [options.config.agentName || 'No agent selected'];
+    if (options.config.modelName) {
+        runnerParts.push(options.config.modelName);
+    }
+    if (options.config.thinkingLevel) {
+        runnerParts.push(`thinking ${options.config.thinkingLevel}`);
+    }
+    const configurationRows = [
+        ...buildOptionalSessionRow('Context', options.config.context),
+        ...buildOptionalSessionRow('Test', options.config.testCommand),
+    ];
+    return [
+        {
+            label: 'State',
+            value: `${pausePresentation.badge} ${pausePresentation.stateMessage}`,
+        },
+        {
+            label: 'Runner',
+            value: runnerParts.join('  ·  '),
+        },
+        ...configurationRows,
+        {
+            label: 'This run',
+            value: buildThisRunSummary(options.progress),
+        },
+        {
+            label: 'Backlog',
+            value: buildBacklogSummary(options.progress),
+        },
+        {
+            label: 'Scope',
+            value: buildScopeSummary(options.progress, options.config),
+        },
+        {
+            label: 'Timing',
+            value: buildTimingSummary(options.progress),
+        },
+        {
+            label: 'Progress',
+            value: buildProgressBar(options.progress.percentage, bodyWidth - SESSION_LABEL_WIDTH - 1, `${options.progress.percentage}% complete (${options.progress.sessionDone}/${options.progress.sessionTotal} done)`),
+        },
+    ];
+}
 /**
  * Builds the fixed-height live output section so streaming updates do not keep resizing the frame.
  */
 function buildVisibleOutputLines(agentOutputLines) {
     const visibleOutputLines = agentOutputLines.length > 0
         ? agentOutputLines.slice(-MAX_VISIBLE_OUTPUT_LINES).map((line) => `› ${stripAnsi(line)}`)
-        : ['No live agent output yet.'];
+        : [colors.gray('No live agent output yet.')];
     while (visibleOutputLines.length < MAX_VISIBLE_OUTPUT_LINES) {
         visibleOutputLines.push('');
     }
@@ -48832,25 +49431,84 @@ function renderBox(title, lines, totalWidth, colorizeTitle) {
     return [topBorder, ...body, bottomBorder];
 }
 /**
- * Builds the compact config summary line shown in the branding box.
+ * Builds one aligned labeled line inside the session box.
  */
-function buildConfigSummaryLine(config) {
-    const parts = [`Priority ≥${config.priority}`];
-    if (config.context) {
-        parts.unshift(`Context ${config.context}`);
+function buildLabeledSessionLine(label, value, bodyWidth) {
+    const formattedLabel = colors.gray(label.padEnd(SESSION_LABEL_WIDTH));
+    return `${formattedLabel} ${fitAnsiText(value, bodyWidth - SESSION_LABEL_WIDTH - 1)}`;
+}
+/**
+ * Builds zero or one structured session row for optional metadata.
+ */
+function buildOptionalSessionRow(label, value) {
+    if (!value) {
+        return [];
     }
-    if (config.testCommand) {
-        parts.push(`Test ${config.testCommand}`);
+    return [{ label, value }];
+}
+/**
+ * Builds the active-session summary shown in the session box.
+ */
+function buildThisRunSummary(progress) {
+    if (progress.sessionTotal === 0) {
+        return 'No runnable prompts in current scope';
+    }
+    return `Task ${progress.currentPromptIndex}/${progress.sessionTotal}  ·  ${progress.sessionDone} done  ·  ${progress.sessionRemaining} left`;
+}
+/**
+ * Builds the backlog/filter summary shown in the session box.
+ */
+function buildBacklogSummary(progress) {
+    const parts = [`Repo ${progress.totalPrompts} total`];
+    if (progress.skippedPrompts > 0) {
+        parts.push(`${formatPromptCount(progress.skippedPrompts)} below priority`);
+    }
+    return parts.join('  ·  ');
+}
+/**
+ * Builds the priority/write-order summary shown in the session box.
+ */
+function buildScopeSummary(progress, config) {
+    const parts = [`Priority ≥${config.priority}`];
+    if (progress.toBeWrittenPrompts > 0) {
+        parts.push(`Write ${formatPromptCount(progress.toBeWrittenPrompts)} first`);
     }
     return parts.join('  ·  ');
 }
+/**
+ * Builds the elapsed/estimate summary shown in the session box.
+ */
+function buildTimingSummary(progress) {
+    return `Elapsed ${progress.elapsedText}  ·  Total ${progress.estimatedTotalText}  ·  ETA ${progress.estimatedLabel}`;
+}
 /**
  * Builds the colored phase badge shown in the session box.
  */
-function buildPhaseBadge(phase, pauseState) {
-    if (pauseState !== 'RUNNING' || phase === 'paused') {
-        return colors.bgYellow.black(' PAUSED ');
+function buildPausePresentation(phase, pauseState, statusMessage) {
+    if (pauseState === 'PAUSING') {
+        return {
+            badge: colors.bgYellow.black(' PAUSING '),
+            stateMessage: 'Pausing before the next task',
+            pauseControl: colors.bgMagenta.white(' P ') + colors.white(' Cancel pause'),
+        };
+    }
+    if (pauseState === 'PAUSED') {
+        return {
+            badge: colors.bgWhite.black(' PAUSED '),
+            stateMessage: 'Paused until resumed',
+            pauseControl: colors.bgGreen.black(' P ') + colors.white(' Resume'),
+        };
     }
+    return {
+        badge: buildRunningPhaseBadge(phase),
+        stateMessage: statusMessage,
+        pauseControl: colors.bgYellow.black(' P ') + colors.white(' Pause'),
+    };
+}
+/**
+ * Builds the active phase badge shown in the session box while the runner is not paused.
+ */
+function buildRunningPhaseBadge(phase) {
     switch (phase) {
         case 'loading':
         case 'initializing':
@@ -48865,6 +49523,8 @@ function buildPhaseBadge(phase, pauseState) {
             return colors.bgGreen.black(' DONE ');
         case 'error':
             return colors.bgRed.white(' ERROR ');
+        case 'paused':
+            return colors.bgWhite.black(' READY ');
         default:
             return colors.bgWhite.black(' READY ');
     }
@@ -48877,7 +49537,7 @@ function buildProgressBar(percentage, availableWidth, label) {
     const barWidth = Math.max(10, availableWidth - percentageLabel.length - 1);
     const filledWidth = Math.round((percentage / 100) * barWidth);
     const emptyWidth = Math.max(0, barWidth - filledWidth);
-    return `${colors.green('█'.repeat(filledWidth))}${colors.gray('░'.repeat(emptyWidth))} ${percentageLabel}`;
+    return `${colors.green('█'.repeat(filledWidth))}${colors.blue('░'.repeat(emptyWidth))} ${percentageLabel}`;
 }
 /**
  * Formats a prompt count with singular/plural wording.
@@ -48888,58 +49548,15 @@ function formatPromptCount(count) {
 /**
  * Builds the control pills shown in the footer box.
  */
-function buildControlPills(pauseState, pendingEnterLabel) {
+function buildControlPills(pauseControl, pendingEnterLabel) {
     const pills = [];
     if (pendingEnterLabel) {
         pills.push(colors.bgWhite.black(' ENTER ') + colors.white(` ${pendingEnterLabel}`));
     }
-    pills.push(pauseState === 'RUNNING'
-        ? colors.bgYellow.black(' P ') + colors.white(' Pause')
-        : colors.bgYellow.black(' P ') + colors.white(' Resume'));
+    pills.push(pauseControl);
     pills.push(colors.bgRed.white(' CTRL+C ') + colors.white(' Exit'));
     return pills;
 }
-/**
- * Pads or truncates a possibly ANSI-colored line to the target visible width.
- */
-function padAnsiText(text, width) {
-    const fittedText = fitAnsiText(text, width);
-    return fittedText + ' '.repeat(Math.max(0, width - visibleLength(fittedText)));
-}
-/**
- * Truncates a possibly ANSI-colored line to the target visible width.
- */
-function fitAnsiText(text, width) {
-    if (visibleLength(text) <= width) {
-        return text;
-    }
-    return fitPlainText(stripAnsi(text), width);
-}
-/**
- * Truncates a plain-text line to the target width with an ellipsis.
- */
-function fitPlainText(text, width) {
-    if (text.length <= width) {
-        return text;
-    }
-    if (width <= 3) {
-        return '.'.repeat(width);
-    }
-    return `${text.slice(0, width - 3)}...`;
-}
-/**
- * Measures visible string width by stripping ANSI escape codes.
- */
-function visibleLength(text) {
-    return stripAnsi(text).length;
-}
-/**
- * Strips ANSI escape codes from a string.
- */
-function stripAnsi(text) {
-    // eslint-disable-next-line no-control-regex
-    return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
-}
 
 /**
  * Maximum number of agent output lines kept in the scrolling output area.
@@ -48968,7 +49585,9 @@ class CoderRunUiState extends EventEmitter {
         this.statusMessage = 'Initializing...';
         this.errors = [];
         this.stats = { done: 0, forAgent: 0, belowMinimumPriority: 0, toBeWritten: 0 };
-        this.timer = new CoderRunTimer(startTime, true);
+        // Match the plain CLI progress header and count active run time from startup.
+        // Explicit waits/pauses are excluded later through `pauseTimer()` / `resumeTimer()`.
+        this.timer = new CoderRunTimer(startTime);
     }
     /**
      * Pauses the elapsed timer (e.g. while waiting for user input or paused state).
@@ -49080,34 +49699,6 @@ class CoderRunUiState extends EventEmitter {
     }
 }
 
-/**
- * Refresh cadence used only while the rich coder UI needs animated updates.
- *
- * @private internal constant of coder run UI
- */
-const ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS = 1000;
-/**
- * Phases that still benefit from automatic refreshes because the frame can change
- * over time even without new runner output.
- *
- * @private internal constant of coder run UI
- */
-const AUTO_REFRESH_PHASES = ['initializing', 'loading', 'running', 'verifying'];
-/**
- * Returns the automatic refresh interval for the current UI state.
- *
- * Waiting, paused, and completed states return `undefined` so the rich UI stays
- * perfectly still until actual state changes arrive.
- *
- * @private internal utility of coder run UI
- */
-function getCoderRunUiAutoRefreshInterval(phase, pauseState) {
-    if (pauseState !== 'RUNNING') {
-        return undefined;
-    }
-    return AUTO_REFRESH_PHASES.includes(phase) ? ACTIVE_CODER_RUN_UI_REFRESH_INTERVAL_MS : undefined;
-}
-
 /**
  * Spinner animation frames.
  *
@@ -49286,6 +49877,7 @@ function renderCoderRunUi(startTime) {
     function buildFrameLines() {
         return buildCoderRunUiFrame({
             terminalWidth: getTerminalWidth(),
+            animationFrame: spinnerFrame,
             spinner: SPINNER_FRAMES[spinnerFrame],
             pauseState: getPauseState(),
             config: state.config,
@@ -49333,12 +49925,7 @@ function renderCoderRunUi(startTime) {
             process.exit(0);
         }
         if (key.name === 'p') {
-            if (getPauseState() === 'RUNNING') {
-                requestPause();
-            }
-            else {
-                requestResume();
-            }
+            togglePauseState();
             scheduleRender();
             return;
         }
@@ -49474,6 +50061,23 @@ async function runCodexPrompts(providedOptions) {
     const isRichUiEnabled = !options.dryRun && !options.noUi && Boolean(process.stdout.isTTY);
     const progressDisplay = options.dryRun || options.noUi || isRichUiEnabled ? undefined : new CliProgressDisplay(runStartDate, options.priority);
     const uiHandle = isRichUiEnabled ? renderCoderRunUi(runStartDate) : undefined;
+    const waitForRequestedPause = async () => {
+        await checkPause({
+            silent: isRichUiEnabled,
+            onPaused: () => {
+                progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.pauseTimer();
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('paused');
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Paused');
+            },
+            onResumed: () => {
+                progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.resumeTimer();
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
+                uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Resuming...');
+            },
+        });
+    };
     // When the Ink UI is active it handles keyboard input itself, so skip the raw stdin listener.
     if (!isRichUiEnabled) {
         listenForPause();
@@ -49590,19 +50194,7 @@ async function runCodexPrompts(providedOptions) {
         let hasShownUpcomingTasks = false;
         let hasWaitedForStart = false;
         while (just(true)) {
-            await checkPause({
-                silent: isRichUiEnabled,
-                onPaused: () => {
-                    progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.pauseTimer();
-                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.pauseTimer();
-                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('paused');
-                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Paused');
-                },
-                onResumed: () => {
-                    progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.resumeTimer();
-                    uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.resumeTimer();
-                },
-            });
+            await waitForRequestedPause();
             if (isRichUiEnabled) {
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('loading');
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setStatusMessage('Loading prompts...');
@@ -49670,6 +50262,7 @@ async function runCodexPrompts(providedOptions) {
             const commitMessage = buildCommitMessage(nextPrompt.file, nextPrompt.section);
             const codexPrompt = appendCoderContext(buildCodexPrompt(nextPrompt.file, nextPrompt.section), resolvedCoderContext);
             const scriptPath = buildScriptPath(nextPrompt.file, nextPrompt.section);
+            await waitForRequestedPause();
             if (isRichUiEnabled) {
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCurrentPrompt(promptLabel);
                 uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setPhase('running');
@@ -51380,6 +51973,14 @@ function promptbookifyAiText(text) {
  * Constant for default agent kit model name.
  */
 const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.4-mini';
+/**
+ * Default model used for nested DeepSearch tool invocations.
+ */
+const DEFAULT_DEEP_SEARCH_MODEL_NAME = 'o4-mini-deep-research';
+/**
+ * Tool name used by the Book commitment-backed DeepSearch capability.
+ */
+const DEEP_SEARCH_TOOL_NAME = 'deep_search';
 /**
  * Creates one structured log entry for streamed tool-call updates.
  *
@@ -51422,6 +52023,98 @@ function resolveFinalToolCallState(options) {
     }
     return 'COMPLETE';
 }
+/**
+ * Returns true when one tool definition represents the dedicated DeepSearch capability.
+ *
+ * @param toolDefinition - Tool definition from compiled model requirements.
+ * @returns `true` when the tool should be backed by a nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function isDeepSearchToolDefinition(toolDefinition) {
+    return toolDefinition.name === DEEP_SEARCH_TOOL_NAME;
+}
+/**
+ * Normalizes Promptbook JSON-schema tool parameters for AgentKit function tools.
+ *
+ * @param parameters - Promptbook tool parameters.
+ * @returns AgentKit-compatible JSON schema or `undefined`.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function normalizeAgentKitToolParameters(parameters) {
+    var _a, _b;
+    if (!parameters) {
+        return undefined;
+    }
+    return {
+        ...parameters,
+        additionalProperties: (_a = parameters.additionalProperties) !== null && _a !== void 0 ? _a : false,
+        required: (_b = parameters.required) !== null && _b !== void 0 ? _b : [],
+    };
+}
+/**
+ * Creates instructions for the nested DeepSearch specialist agent.
+ *
+ * @param toolDescription - Model-facing description from the original tool definition.
+ * @returns System instructions for the nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function createDeepSearchAgentInstructions(toolDescription) {
+    const normalizedDescription = toolDescription.trim();
+    return spaceTrim$1((block) => `
+            You are a DeepSearch specialist working as a tool for another agent.
+            Perform thorough, source-grounded public-web research based on the provided request.
+            Use web search to gather current information, compare relevant viewpoints, and synthesize a concise research brief.
+            Do not ask follow-up questions. If the request is not specific enough, state the assumptions you had to make.
+            Include citations in the research brief whenever sources were used.
+            ${block(normalizedDescription ? `Tool guidance:\n${normalizedDescription}` : '')}
+        `);
+}
+/**
+ * Builds the nested DeepSearch prompt from structured tool arguments.
+ *
+ * @param rawInput - Parsed function-tool arguments provided by the outer agent.
+ * @returns Prompt text passed to the nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function buildDeepSearchToolInput(rawInput) {
+    const input = rawInput && typeof rawInput === 'object' ? rawInput : {};
+    const query = typeof input.query === 'string' ? input.query.trim() : '';
+    const additionalHints = Object.entries(input)
+        .filter(([key, value]) => key !== 'query' && value !== undefined && value !== null && String(value).trim() !== '')
+        .map(([key, value]) => `- ${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    return spaceTrim$1((block) => `
+            Research request:
+            ${query || JSON.stringify(input)}
+            ${block(additionalHints.length > 0 ? `Execution hints:\n${additionalHints.join('\n')}` : '')}
+        `);
+}
+/**
+ * Creates the native Agent SDK tool used for `USE DEEPSEARCH`.
+ *
+ * @param toolDefinition - Promptbook tool definition for `deep_search`.
+ * @returns AgentKit tool backed by a nested deep-research agent.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function createDeepSearchAgentKitTool(toolDefinition) {
+    const deepSearchAgent = new Agent$1({
+        name: 'DeepSearch',
+        model: DEFAULT_DEEP_SEARCH_MODEL_NAME,
+        instructions: createDeepSearchAgentInstructions(toolDefinition.description),
+        tools: [webSearchTool({ searchContextSize: 'high' })],
+    });
+    return deepSearchAgent.asTool({
+        toolName: toolDefinition.name,
+        toolDescription: toolDefinition.description,
+        parameters: normalizeAgentKitToolParameters(toolDefinition.parameters),
+        inputBuilder: ({ params }) => buildDeepSearchToolInput(params),
+        customOutputExtractor: (result) => { var _a; return typeof result.finalOutput === 'string' ? result.finalOutput : JSON.stringify((_a = result.finalOutput) !== null && _a !== void 0 ? _a : ''); },
+    });
+}
 /**
  * Constant for default JSON schema name.
  */
@@ -51762,25 +52455,23 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * Builds the tool list for AgentKit, including hosted file search when applicable.
      */
     buildAgentKitTools(options) {
-        var _a;
         const { tools, vectorStoreId } = options;
         const agentKitTools = [];
         if (vectorStoreId) {
             agentKitTools.push(fileSearchTool(vectorStoreId));
         }
         if (tools && tools.length > 0) {
-            const scriptTools = this.resolveScriptTools();
+            let scriptTools = null;
             for (const toolDefinition of tools) {
+                if (isDeepSearchToolDefinition(toolDefinition)) {
+                    agentKitTools.push(createDeepSearchAgentKitTool(toolDefinition));
+                    continue;
+                }
+                scriptTools !== null && scriptTools !== void 0 ? scriptTools : (scriptTools = this.resolveScriptTools());
                 agentKitTools.push(tool({
                     name: toolDefinition.name,
                     description: toolDefinition.description,
-                    parameters: toolDefinition.parameters
-                        ? {
-                            ...toolDefinition.parameters,
-                            additionalProperties: false,
-                            required: (_a = toolDefinition.parameters.required) !== null && _a !== void 0 ? _a : [],
-                        }
-                        : undefined,
+                    parameters: normalizeAgentKitToolParameters(toolDefinition.parameters),
                     strict: false,
                     execute: async (input, runContext, details) => {
                         var _a, _b, _c, _d;
@@ -53734,9 +54425,10 @@ function formatMetaLine(label, value) {
  * Build a minimal agent source snapshot for remote agents.
  */
 function buildRemoteAgentSource(profile, meta) {
+    const isMetaImageExplicit = profile.isMetaImageExplicit !== false;
     const metaLines = [
         formatMetaLine('FULLNAME', meta === null || meta === void 0 ? void 0 : meta.fullname),
-        formatMetaLine('IMAGE', meta === null || meta === void 0 ? void 0 : meta.image),
+        formatMetaLine('IMAGE', isMetaImageExplicit ? meta === null || meta === void 0 ? void 0 : meta.image : undefined),
         formatMetaLine('DESCRIPTION', meta === null || meta === void 0 ? void 0 : meta.description),
         formatMetaLine('COLOR', meta === null || meta === void 0 ? void 0 : meta.color),
         formatMetaLine('FONT', meta === null || meta === void 0 ? void 0 : meta.font),
@@ -53835,6 +54527,8 @@ class RemoteAgent extends Agent {
         remoteAgent._isVoiceCallingEnabled = profile.isVoiceCallingEnabled === true; // [✨✷] Store voice calling status
         remoteAgent._isVoiceTtsSttEnabled = profile.isVoiceTtsSttEnabled !== false;
         remoteAgent.knowledgeSources = profile.knowledgeSources || [];
+        remoteAgent.isMetaImageExplicit = profile.isMetaImageExplicit !== false;
+        remoteAgent.avatarVisualId = profile.avatarVisualId;
         return remoteAgent;
     }
     /**
@@ -53850,6 +54544,8 @@ class RemoteAgent extends Agent {
         this.toolTitles = {};
         this._isVoiceCallingEnabled = false; // [✨✷] Track voice calling status
         this._isVoiceTtsSttEnabled = true;
+        this.isMetaImageExplicit = true;
+        this.avatarVisualId = undefined;
         this.knowledgeSources = [];
         this.agentUrl = options.agentUrl;
     }