@promptbook/cli 0.112.0-123 → 0.112.0-125

package/apps/agents-server/src/utils/userChat/userChatProgressCard.ts

@@ -0,0 +1,288 @@
+import type { ChatMessage, ToolCall } from '@promptbook-local/types';
+import { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../../../../../src/types/ToolCall';
+
+/**
+ * Prefix used by automatic durable chat progress items.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+const AUTOMATIC_PROGRESS_ITEM_ID_PREFIX = 'user-chat-job-progress-';
+
+/**
+ * Shared title for progress cards owned by the durable chat runner.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+const AUTOMATIC_PROGRESS_TITLE = 'Agent Progress';
+
+/**
+ * Tool names that are already represented by the progress card itself.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+const HIDDEN_PROGRESS_TOOL_NAMES = new Set(['agent_progress']);
+
+/**
+ * Options for building an automatic running progress card.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+type CreateRunningUserChatProgressCardOptions = {
+    readonly currentProgressCard?: ChatMessage['progressCard'];
+    readonly content: string;
+    readonly toolCalls?: ReadonlyArray<ToolCall>;
+    readonly updatedAt: NonNullable<ChatMessage['progressCard']>['updatedAt'];
+};
+
+/**
+ * Creates the initial real progress payload shown before an agent runner starts.
+ *
+ * @param updatedAt - Timestamp used for the progress-card update marker.
+ * @returns Structured progress card for a queued assistant placeholder.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+export function createQueuedUserChatProgressCard(
+    updatedAt: NonNullable<ChatMessage['progressCard']>['updatedAt'],
+): NonNullable<ChatMessage['progressCard']> {
+    return {
+        title: AUTOMATIC_PROGRESS_TITLE,
+        now: 'Your message is queued for the agent runner.',
+        next: 'The runner will prepare the agent context and start generating the response.',
+        items: [
+            {
+                id: `${AUTOMATIC_PROGRESS_ITEM_ID_PREFIX}queued`,
+                text: 'Request added to the chat queue',
+                status: 'completed',
+            },
+            {
+                id: `${AUTOMATIC_PROGRESS_ITEM_ID_PREFIX}waiting-for-runner`,
+                text: 'Waiting for an available agent runner',
+                status: 'pending',
+            },
+        ],
+        updatedAt,
+        isVisible: true,
+    };
+}
+
+/**
+ * Creates or refreshes the automatic progress card for a running durable chat job.
+ *
+ * A model-authored `agent_progress` card is preserved once it takes over, so the
+ * durable runner does not overwrite more specific progress supplied by the agent.
+ *
+ * @param options - Current message state and streamed runtime details.
+ * @returns Progress card that should be stored on the assistant message.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+export function createRunningUserChatProgressCard(
+    options: CreateRunningUserChatProgressCardOptions,
+): NonNullable<ChatMessage['progressCard']> {
+    if (shouldPreserveModelProgressCard(options.currentProgressCard)) {
+        return options.currentProgressCard;
+    }
+
+    const visibleToolCalls = (options.toolCalls || []).filter((toolCall) => !HIDDEN_PROGRESS_TOOL_NAMES.has(toolCall.name));
+    const hasVisibleToolCalls = visibleToolCalls.length > 0;
+    const hasStartedWriting = options.content.trim().length > 0;
+
+    return {
+        title: AUTOMATIC_PROGRESS_TITLE,
+        now: resolveRunningProgressNowText({
+            hasStartedWriting,
+            visibleToolCalls,
+        }),
+        next: hasVisibleToolCalls
+            ? 'Tool results will be incorporated into the final response.'
+            : 'The final answer will replace this progress view when generation finishes.',
+        items: [
+            {
+                id: `${AUTOMATIC_PROGRESS_ITEM_ID_PREFIX}queued`,
+                text: 'Request added to the chat queue',
+                status: 'completed',
+            },
+            {
+                id: `${AUTOMATIC_PROGRESS_ITEM_ID_PREFIX}runtime-prepared`,
+                text: 'Agent context and runtime tools prepared',
+                status: 'completed',
+            },
+            {
+                id: `${AUTOMATIC_PROGRESS_ITEM_ID_PREFIX}generating-response`,
+                text: hasStartedWriting ? 'Response text has started streaming' : 'Generating the assistant response',
+                status: hasStartedWriting ? 'completed' : 'pending',
+            },
+            ...visibleToolCalls.map(createToolCallProgressItem),
+        ],
+        updatedAt: options.updatedAt,
+        isVisible: true,
+    };
+}
+
+/**
+ * Returns true when the existing progress card should be treated as model-authored.
+ *
+ * @param progressCard - Existing progress-card payload on the assistant message.
+ * @returns Whether automatic runner progress should leave the card untouched.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function shouldPreserveModelProgressCard(
+    progressCard: ChatMessage['progressCard'],
+): progressCard is NonNullable<ChatMessage['progressCard']> {
+    if (!progressCard || progressCard.isVisible === false) {
+        return false;
+    }
+
+    if (progressCard.title !== AUTOMATIC_PROGRESS_TITLE) {
+        return true;
+    }
+
+    return (progressCard.items || []).some((item) => !item.id.startsWith(AUTOMATIC_PROGRESS_ITEM_ID_PREFIX));
+}
+
+/**
+ * Resolves the current-work copy for a running progress card.
+ *
+ * @param options - Running output and tool-call state.
+ * @returns Concise progress-card text.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function resolveRunningProgressNowText(options: {
+    readonly hasStartedWriting: boolean;
+    readonly visibleToolCalls: ReadonlyArray<ToolCall>;
+}): string {
+    if (options.visibleToolCalls.length > 0) {
+        return `Using ${formatToolCallList(options.visibleToolCalls)}.`;
+    }
+
+    if (options.hasStartedWriting) {
+        return 'The agent has started writing the response.';
+    }
+
+    return 'The agent runtime is prepared and the model is generating the response.';
+}
+
+/**
+ * Creates one checklist item from an observed tool-call snapshot.
+ *
+ * @param toolCall - Tool call observed while the model is running.
+ * @param index - Position of the tool call in the current snapshot.
+ * @returns Progress item for the tool action.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function createToolCallProgressItem(toolCall: ToolCall, index: number): NonNullable<ChatMessage['progressCard']>['items'][number] {
+    return {
+        id: `${AUTOMATIC_PROGRESS_ITEM_ID_PREFIX}tool-${resolveToolCallProgressId(toolCall, index)}`,
+        text: resolveToolCallProgressText(toolCall),
+        status: isToolCallComplete(toolCall) ? 'completed' : 'pending',
+    };
+}
+
+/**
+ * Creates a stable progress item id from one tool-call snapshot.
+ *
+ * @param toolCall - Tool call observed while the model is running.
+ * @param index - Position of the tool call in the current snapshot.
+ * @returns Stable id suffix for the rendered progress item.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function resolveToolCallProgressId(toolCall: ToolCall, index: number): string {
+    const rawId = toolCall.idempotencyKey || `${toolCall.name}-${index}`;
+    return rawId
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+}
+
+/**
+ * Resolves user-facing progress text for one tool-call snapshot.
+ *
+ * @param toolCall - Tool call observed while the model is running.
+ * @returns Concise description of the action or result.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function resolveToolCallProgressText(toolCall: ToolCall): string {
+    const toolTitle = formatToolName(toolCall.name);
+    const latestLog = [...(toolCall.logs || [])].reverse().find((log) => log.title || log.message);
+
+    if (toolCall.name === ASSISTANT_PREPARATION_TOOL_CALL_NAME) {
+        return 'Preparing assistant runtime';
+    }
+
+    if (Array.isArray(toolCall.errors) && toolCall.errors.length > 0) {
+        return `${toolTitle} reported an error`;
+    }
+
+    if (isToolCallComplete(toolCall)) {
+        return `${toolTitle} completed`;
+    }
+
+    if (latestLog) {
+        const logText = latestLog.title || latestLog.message;
+        return `${toolTitle}: ${logText}`;
+    }
+
+    return `${toolTitle} is running`;
+}
+
+/**
+ * Formats a short comma-separated list of active tools.
+ *
+ * @param toolCalls - Visible tool calls in the current stream snapshot.
+ * @returns Human-readable tool list.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function formatToolCallList(toolCalls: ReadonlyArray<ToolCall>): string {
+    const uniqueToolNames = [...new Set(toolCalls.map((toolCall) => formatToolName(toolCall.name)))];
+
+    if (uniqueToolNames.length === 1) {
+        return uniqueToolNames[0]!;
+    }
+
+    const finalToolName = uniqueToolNames[uniqueToolNames.length - 1]!;
+    return `${uniqueToolNames.slice(0, -1).join(', ')} and ${finalToolName}`;
+}
+
+/**
+ * Converts one technical tool name into compact user-facing copy.
+ *
+ * @param toolName - Tool function name.
+ * @returns Human-readable tool name.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function formatToolName(toolName: string): string {
+    return toolName
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/^\w/, (character) => character.toUpperCase());
+}
+
+/**
+ * Infers whether a tool-call snapshot has reached a terminal successful state.
+ *
+ * @param toolCall - Tool call observed while the model is running.
+ * @returns Whether the tool call has a completed result.
+ *
+ * @private internal helper for Agents Server durable chat progress
+ */
+function isToolCallComplete(toolCall: ToolCall): boolean {
+    if (toolCall.state === 'COMPLETE') {
+        return true;
+    }
+
+    if (toolCall.state === 'ERROR' || toolCall.state === 'PARTIAL' || toolCall.state === 'PENDING') {
+        return false;
+    }
+
+    return toolCall.result !== undefined && toolCall.result !== '';
+}

package/esm/index.es.js

@@ -1,7 +1,7 @@
 import colors from 'colors';
 import commander, { Option } from 'commander';
 import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
-import { writeFile, stat, mkdir, readFile, rm, cp, lstat, symlink, readdir, unlink, appendFile, rename, access, constants, watch, rmdir } from 'fs/promises';
+import { writeFile, stat, mkdir, readFile, rm, cp, lstat, symlink, readdir, unlink, appendFile, rename, copyFile, access, constants, watch, rmdir } from 'fs/promises';
 import { join, resolve, dirname, relative, basename, delimiter, isAbsolute, extname } from 'path';
 import { spawn } from 'child_process';
 import { createHash, randomBytes } from 'crypto';
@@ -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-123';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-125';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2176,7 +2176,7 @@ function getDefaultBookLanguageManualContent() {
  */
 async function ensureCoderMarkdownFile(projectPath, relativeFilePath, fileContent) {
     const absoluteFilePath = join(projectPath, relativeFilePath);
-    if (await isExistingFile$2(absoluteFilePath)) {
+    if (await isExistingFile$3(absoluteFilePath)) {
         return 'unchanged';
     }
     await writeFile(absoluteFilePath, `${fileContent}\n`, 'utf-8');
@@ -2185,7 +2185,7 @@ async function ensureCoderMarkdownFile(projectPath, relativeFilePath, fileConten
 /**
  * Checks whether a path exists and is a file.
  */
-async function isExistingFile$2(path) {
+async function isExistingFile$3(path) {
     try {
         return (await stat(path)).isFile();
     }
@@ -38757,7 +38757,7 @@ async function ensureDefaultCoderPromptTemplateFiles(projectPath) {
     const ensuredTemplateFiles = [];
     for (const definition of DEFAULT_CODER_PROJECT_PROMPT_TEMPLATE_DEFINITIONS) {
         const absoluteTemplatePath = join(projectPath, definition.relativeFilePath);
-        if (await isExistingFile$1(absoluteTemplatePath)) {
+        if (await isExistingFile$2(absoluteTemplatePath)) {
             ensuredTemplateFiles.push({
                 id: definition.id,
                 relativeFilePath: definition.relativeFilePath,
@@ -38871,7 +38871,7 @@ function isNodeJsErrorWithCode(error, code) {
 /**
  * Checks whether a path exists and is a file.
  */
-async function isExistingFile$1(path) {
+async function isExistingFile$2(path) {
     try {
         return (await stat(path)).isFile();
     }
@@ -39144,6 +39144,70 @@ function formatInlineCodeList(values) {
 // Note: [🟡] Code for coder AGENT_CODING file boilerplate [agentCodingFile](src/cli/cli-commands/coder/agentCodingFile.ts) should never be published outside of `@promptbook/cli`
 // Note: [💞] Ignore a discrepancy between file name and exported helper names
 
+/**
+ * Relative directory path for agents initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+const CODER_AGENTS_DIRECTORY_PATH = 'agents';
+/**
+ * Relative file path to the default developer agent initialized by `ptbk coder init`.
+ *
+ * @private internal utility of `coder init` command
+ */
+const CODER_DEVELOPER_AGENT_FILE_PATH = 'agents/developer.book';
+/**
+ * Source file path of the bundled developer agent inside the Promptbook repository.
+ *
+ * @private internal utility of `coder init` command
+ */
+const DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH = 'agents/default/developer.book';
+/**
+ * Ensures the default developer agent exists in the initialized project.
+ *
+ * @private function of `initializeCoderProjectConfiguration`
+ */
+async function ensureCoderDeveloperAgentFile(projectPath) {
+    const absoluteFilePath = join(projectPath, CODER_DEVELOPER_AGENT_FILE_PATH);
+    if (await isExistingFile$1(absoluteFilePath)) {
+        return 'unchanged';
+    }
+    await copyFile(await resolveDefaultCoderDeveloperAgentFilePath(), absoluteFilePath);
+    return 'created';
+}
+/**
+ * Resolves the bundled developer agent from a source checkout or generated CLI package.
+ */
+async function resolveDefaultCoderDeveloperAgentFilePath() {
+    const candidates = [
+        join(__dirname, '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
+        join(__dirname, '..', '..', '..', '..', DEFAULT_CODER_DEVELOPER_AGENT_SOURCE_FILE_PATH),
+    ];
+    for (const candidate of candidates) {
+        if (await isExistingFile$1(candidate)) {
+            return candidate;
+        }
+    }
+    throw new NotAllowed(spaceTrim$1(`
+            Cannot find the bundled Promptbook developer agent.
+
+            Checked:
+            ${candidates.map((candidate) => `- \`${candidate}\``).join('\n')}
+        `));
+}
+/**
+ * Checks whether a path exists and is a file.
+ */
+async function isExistingFile$1(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (_a) {
+        return false;
+    }
+}
+// Note: [🟡] Code for coder init developer agent bootstrapping [ensureCoderDeveloperAgentFile](src/cli/cli-commands/coder/ensureCoderDeveloperAgentFile.ts) should never be published outside of `@promptbook/cli`
+
 /**
  * Fallback `.env` content used when no required variables need to be appended.
  */
@@ -39220,7 +39284,7 @@ async function ensureCoderGitignoreFile(projectPath) {
  */
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
-    'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --no-wait',
+    'coder:run': 'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md --no-wait',
     // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 };
@@ -39466,6 +39530,8 @@ async function initializeCoderProjectConfiguration(projectPath) {
     const promptsDoneDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_DONE_DIRECTORY_PATH);
     const promptsTemplatesDirectoryStatus = await ensureDirectory(projectPath, PROMPTS_TEMPLATES_DIRECTORY_PATH);
     const promptTemplateFileStatuses = await ensureDefaultCoderPromptTemplateFiles(projectPath);
+    const agentsDirectoryStatus = await ensureDirectory(projectPath, CODER_AGENTS_DIRECTORY_PATH);
+    const developerAgentFileStatus = await ensureCoderDeveloperAgentFile(projectPath);
     const agentsFileStatus = await ensureCoderMarkdownFile(projectPath, AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent());
     const agentCodingFileStatus = await ensureCoderMarkdownFile(projectPath, AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent({
         packageJsonScripts: getDefaultCoderPackageJsonScripts(),
@@ -39479,6 +39545,8 @@ async function initializeCoderProjectConfiguration(projectPath) {
         promptsDoneDirectoryStatus,
         promptsTemplatesDirectoryStatus,
         promptTemplateFileStatuses,
+        agentsDirectoryStatus,
+        developerAgentFileStatus,
         agentsFileStatus,
         agentCodingFileStatus,
         envFileStatus,
@@ -39503,6 +39571,8 @@ function printInitializationSummary(summary) {
     for (const templateFileStatus of summary.promptTemplateFileStatuses) {
         printInitializationStatusLine(formatDisplayPath(templateFileStatus.relativeFilePath), templateFileStatus.status);
     }
+    printInitializationStatusLine('agents/', summary.agentsDirectoryStatus);
+    printInitializationStatusLine(CODER_DEVELOPER_AGENT_FILE_PATH, summary.developerAgentFileStatus);
     printInitializationStatusLine(AGENTS_FILE_PATH, summary.agentsFileStatus);
     printInitializationStatusLine(AGENT_CODING_FILE_PATH, summary.agentCodingFileStatus);
     printInitializationStatusLine('.env', summary.envFileStatus);
@@ -39559,6 +39629,7 @@ function $initializeCoderInitCommand(program) {
             - prompts/
             - prompts/done/
             ${listDefaultCoderProjectPromptTemplateDisplayPaths()}
+            - ${CODER_DEVELOPER_AGENT_FILE_PATH}
             - ${AGENTS_FILE_PATH}
             - ${AGENT_CODING_FILE_PATH}
             - .gitignore