@promptbook/openai 0.114.0-0 → 0.114.0-10

package/README.md

@@ -410,8 +410,6 @@ Respond to incoming legal inquiries via email and keep the company website updat
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
 <br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
 <br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
@@ -500,7 +498,7 @@ GOAL Keep the company website updated with the latest legal policies and complia
 
 #### `Use` commitments
 
-Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE EMAIL` lets the agent send emails, `USE BROWSER` lets it access and read web content, `USE SEARCH ENGINE` lets it search the web, and many more.
+Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE CALENDAR` lets the agent work with a calendar, `USE PROJECT` gives it access to a code repository, `USE MCP` connects any external Model Context Protocol server, and many more.
 
 These are what turn a chatbot into a persistent agent that actually does work.
 
@@ -517,9 +515,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 
 </td></tr></table>
 
@@ -540,9 +535,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
@@ -729,7 +721,7 @@ Or you can install them separately:
 
 Promptbook Coder is **not another standalone coding model**. It is an orchestration layer over coding agents such as **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, **Opencode**, **Cline**, and **Gemini CLI**. The difference is that Promptbook Coder adds a repeatable repository workflow on top of them:
 
--   prompt files with explicit statuses like `[ ]`, `[x]`, and `[-]`
+-   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
 -   optional shared repo context loaded from a file such as `AGENTS.md`
 -   automatic `git add`, commit, and push after each successful prompt
@@ -744,11 +736,11 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.promptbook`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
 2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
 3. You replace placeholder `@@@` sections with real coding tasks.
-4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent.
+4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent and immediately marks it as in progress `[^]`, naming the harness, the model and the step which is running.
 5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
 6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
 
-Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority.
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind.
 
 #### Features
 
@@ -820,26 +812,27 @@ ptbk coder verify
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
-| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                                  |
+| `ptbk coder run`                      | Picks the next ready prompt, can run tests before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                             |
 | `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
-| Flag                       | Purpose                                                                                            |
-| -------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--harness <name>`         | Selects the coding harness.                                                                        |
-| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
-| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
-| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |
-| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
-| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
-| `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
-| `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
-| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                     |
-| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                               |
-| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                              |
+| Flag                       | Purpose                                                                                                                                                                                |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>`         | Selects the coding harness.                                                                                                                                                            |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`.                                                                                     |
+| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                                                                                                     |
+| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                       |
+| `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
+| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
+| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                                                                                                                 |
+| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
+| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
+| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |
+| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                   |
+| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                  |
 
 #### Typical usage pattern
 

package/esm/index.es.js

@@ -2,9 +2,6 @@ import { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import CryptoJS from 'crypto-js';
 import colors from 'colors';
 import Bottleneck from 'bottleneck';
-import OpenAI from 'openai';
-import { io } from 'socket.io-client';
-import { fileSearchTool, tool, Agent, webSearchTool, run, setDefaultOpenAIClient, setDefaultOpenAIKey } from '@openai/agents';
 
 // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
 /**
@@ -20,7 +17,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-0';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-10';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2786,28 +2783,28 @@ function serializeError(error) {
  */
 function buildToolInvocationScript(options) {
     const { functionName, functionArgsExpression } = options;
-    return `
-        const args = ${functionArgsExpression};
-        const runtimeContextRaw =
-            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
-
-        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
-        }
+    return spaceTrim$1((block) => `
+            const args = ${block(functionArgsExpression)};
+            const runtimeContextRaw =
+                typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
+
+            if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
+            }
 
-        const toolProgressTokenRaw =
-            typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_PROGRESS_TOKEN_PARAMETER};
+            const toolProgressTokenRaw =
+                typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
+                    ? undefined
+                    : ${TOOL_PROGRESS_TOKEN_PARAMETER};
 
-        if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
-        }
+            if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+                args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
+            }
 
-        return await ${functionName}(args);
-    `;
+            return await ${functionName}(args);
+        `);
 }
 
 /**
@@ -4820,6 +4817,39 @@ class OpenAiCompatibleNonChatPromptCaller {
     }
 }
 
+/**
+ * Creates a loader which imports one module on the first call and reuses the very same module afterwards
+ *
+ * Note: [🐌] Heavy third-party dependencies are imported lazily to keep the startup of the Promptbook CLI fast.
+ *       A statically imported dependency is loaded every single time the bundle is loaded, even when the running
+ *       command never touches it. A lazily imported dependency is loaded only when the feature is really used.
+ *
+ * @example
+ * const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+ * const { JSDOM } = await loadJsdomModule();
+ *
+ * @private internal utility of Promptbook
+ */
+function createLazyModuleLoader(importModule) {
+    let importedModulePromise = null;
+    return function loadModule() {
+        if (importedModulePromise === null) {
+            importedModulePromise = importModule();
+        }
+        return importedModulePromise;
+    };
+}
+// Note: [🐌] Do not convert the lazy `import(...)` calls back to static `import` statements, it would bring back the
+//       slow startup of the `ptbk` CLI utility
+
+/**
+ * Loads the OpenAI SDK (`openai`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `OpenAiCompatibleRequestManager`
+ */
+const loadOpenAiModule = createLazyModuleLoader(() => import('openai'));
 /**
  * Manages OpenAI-compatible client creation plus shared retry and rate-limit behavior.
  *
@@ -4846,6 +4876,7 @@ class OpenAiCompatibleRequestManager {
                 timeout: API_REQUEST_TIMEOUT,
                 maxRetries: CONNECTION_RETRIES_LIMIT,
             };
+            const { default: OpenAI } = await loadOpenAiModule();
             this.client = new OpenAI(enhancedOptions);
         }
         return this.client;
@@ -7445,6 +7476,14 @@ function isValidUrl(url) {
     }
 }
 
+/**
+ * Loads the Socket.io client (`socket.io-client`) on demand
+ *
+ * Note: [🐌] Loaded lazily to keep the startup of the `ptbk` CLI utility fast
+ *
+ * @private internal utility of `createRemoteClient`
+ */
+const loadSocketIoClientModule = createLazyModuleLoader(() => import('socket.io-client'));
 /**
  * Creates a connection to the remote proxy server.
  *
@@ -7473,6 +7512,7 @@ async function createRemoteClient(options) {
 
                     `));
     }
+    const { io } = await loadSocketIoClientModule();
     return new Promise((resolve, reject) => {
         const socket = io(remoteServerUrl, {
             retries: CONNECTION_RETRIES_LIMIT,
@@ -8126,12 +8166,22 @@ class OpenAiAgentKitExecutionToolsOutputTypeMapper {
     }
 }
 
+/**
+ * Loads the OpenAI AgentKit SDK (`@openai/agents`) on demand
+ *
+ * Note: [🐌] The AgentKit SDK is one of the heaviest dependencies of Promptbook, loading it eagerly would slow down
+ *       every single run of the `ptbk` CLI utility even when no AgentKit agent is used
+ *
+ * @private internal utility of `@promptbook/openai`
+ */
+const loadOpenAiAgentsModule = createLazyModuleLoader(() => import('@openai/agents'));
+
 /**
  * Constant for 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.
+ * Tool name used by the DeepSearch capability.
  */
 const DEEP_SEARCH_TOOL_NAME = 'deep_search';
 /**
@@ -8179,8 +8229,9 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
     /**
      * Builds the tool list for AgentKit, including hosted file search when applicable.
      */
-    buildAgentKitTools(options) {
+    async buildAgentKitTools(options) {
         const { tools, vectorStoreId } = options;
+        const { fileSearchTool, tool: agentKitTool } = await loadOpenAiAgentsModule();
         const agentKitTools = [];
         if (vectorStoreId) {
             agentKitTools.push(fileSearchTool(vectorStoreId));
@@ -8191,11 +8242,11 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
         let scriptTools = null;
         for (const toolDefinition of tools) {
             if (this.isDeepSearchToolDefinition(toolDefinition)) {
-                agentKitTools.push(this.createDeepSearchAgentKitTool(toolDefinition));
+                agentKitTools.push(await this.createDeepSearchAgentKitTool(toolDefinition));
                 continue;
             }
             scriptTools !== null && scriptTools !== void 0 ? scriptTools : (scriptTools = this.resolveScriptTools());
-            agentKitTools.push(tool({
+            agentKitTools.push(agentKitTool({
                 name: toolDefinition.name,
                 description: toolDefinition.description,
                 parameters: this.normalizeAgentKitToolParameters(toolDefinition.parameters),
@@ -8400,10 +8451,11 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
         };
     }
     /**
-     * Creates the native Agent SDK tool used for `USE DEEPSEARCH`.
+     * Creates the native Agent SDK tool used for the DeepSearch capability.
      */
-    createDeepSearchAgentKitTool(toolDefinition) {
-        const deepSearchAgent = new Agent({
+    async createDeepSearchAgentKitTool(toolDefinition) {
+        const { Agent: AgentFromKit, webSearchTool } = await loadOpenAiAgentsModule();
+        const deepSearchAgent = new AgentFromKit({
             name: 'DeepSearch',
             model: DEFAULT_DEEP_SEARCH_MODEL_NAME,
             instructions: this.createDeepSearchAgentInstructions(toolDefinition.description),
@@ -8616,8 +8668,9 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                 vectorStoreId,
             });
         }
-        const agentKitTools = this.buildAgentKitTools({ tools, vectorStoreId });
-        const openAiAgentKitAgent = new Agent({
+        const { Agent: AgentFromKit } = await loadOpenAiAgentsModule();
+        const agentKitTools = await this.buildAgentKitTools({ tools, vectorStoreId });
+        const openAiAgentKitAgent = new AgentFromKit({
             name,
             model: this.agentKitModelName,
             instructions: instructions || 'You are a helpful assistant.',
@@ -8662,6 +8715,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             agentName: agentForRun.name,
             input: inputItems,
         };
+        const { run } = await loadOpenAiAgentsModule();
         const streamResult = await run(agentForRun, inputItems, {
             stream: true,
             maxTurns: 200,
@@ -8804,6 +8858,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * Ensures the AgentKit SDK is wired to the OpenAI client and API key.
      */
     async ensureAgentKitDefaults() {
+        const { setDefaultOpenAIClient, setDefaultOpenAIKey } = await loadOpenAiAgentsModule();
         const client = await this.getClient();
         setDefaultOpenAIClient(client);
         const apiKey = this.agentKitOptions.apiKey;