@promptbook/cli 0.112.0-26 → 0.112.0-28

package/esm/index.es.js

@@ -57,7 +57,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-26';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-28';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -21899,6 +21899,147 @@ class UseCommitmentDefinition extends BaseCommitmentDefinition {
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * All `USE` commitment types currently participating in final system-message aggregation.
+ *
+ * @private internal constant for `aggregateUseCommitmentSystemMessages`
+ */
+const AGGREGATED_USE_COMMITMENT_TYPES = ['USE BROWSER', 'USE SEARCH ENGINE', 'USE TIME'];
+/**
+ * Prefix used for temporary in-system-message placeholders that preserve the first-occurrence position of aggregated `USE` sections.
+ *
+ * @private internal constant for `appendAggregatedUseCommitmentPlaceholder`
+ */
+const AGGREGATED_USE_COMMITMENT_PLACEHOLDER_PREFIX = '# AGGREGATED USE COMMITMENT: ';
+/**
+ * Type guard for `USE` commitment types that are aggregated in the final system message.
+ *
+ * @param type - Commitment type to check.
+ * @returns `true` when the commitment participates in `USE` system-message aggregation.
+ * @private internal utility of `aggregateUseCommitmentSystemMessages`
+ */
+function isAggregatedUseCommitmentType(type) {
+    return AGGREGATED_USE_COMMITMENT_TYPES.includes(type);
+}
+/**
+ * Creates the placeholder token used to reserve the first-occurrence position of an aggregated `USE` system-message section.
+ *
+ * @param type - Aggregated `USE` commitment type.
+ * @returns Single-line placeholder comment stored in the interim system message.
+ * @private internal utility of `appendAggregatedUseCommitmentPlaceholder`
+ */
+function getAggregatedUseCommitmentPlaceholder(type) {
+    return `${AGGREGATED_USE_COMMITMENT_PLACEHOLDER_PREFIX}${type}`;
+}
+/**
+ * Combines distinct additional instruction blocks in source order.
+ *
+ * @param additionalInstructions - Deduplicated instruction blocks collected from the agent source.
+ * @returns Combined instruction text ready for `formatOptionalInstructionBlock`.
+ * @private internal utility of `createAggregatedUseCommitmentSystemMessage`
+ */
+function combineAdditionalInstructions(additionalInstructions) {
+    return additionalInstructions.join('\n');
+}
+/**
+ * Creates the final aggregated system-message section for a supported `USE` commitment type.
+ *
+ * @param type - Aggregated `USE` commitment type.
+ * @param additionalInstructions - Distinct additional instructions in source order.
+ * @returns Final system-message block for the commitment type.
+ * @private internal utility of `aggregateUseCommitmentSystemMessages`
+ */
+function createAggregatedUseCommitmentSystemMessage(type, additionalInstructions) {
+    const combinedAdditionalInstructions = combineAdditionalInstructions(additionalInstructions);
+    switch (type) {
+        case 'USE TIME':
+            return spaceTrim$1((block) => `
+                    Time and date context:
+                    - It is ${moment().format('MMMM YYYY')} now.
+                    - If you need more precise current time information, use the tool "get_current_time".
+                    ${block(formatOptionalInstructionBlock('Time instructions', combinedAdditionalInstructions))}
+                `);
+        case 'USE BROWSER':
+            return spaceTrim$1((block) => `
+                    You have access to browser tools to fetch and access content from the internet.
+                    - Use "fetch_url_content" to retrieve content from specific URLs (webpages or documents) using scrapers.
+                    - Use "run_browser" for real interactive browser automation (navigation, clicks, typing, waiting, scrolling).
+                    When you need to know information from a specific website or document, use the fetch_url_content tool.
+                    ${block(formatOptionalInstructionBlock('Browser instructions', combinedAdditionalInstructions))}
+                `);
+        case 'USE SEARCH ENGINE':
+            return spaceTrim$1((block) => `
+                    Tool:
+                    - You have access to the web search engine via the tool "web_search".
+                    - Use it to find up-to-date information or facts that you don't know.
+                    - When you need to know some information from the internet, use the tool provided to you.
+                    - Do not make up information when you can search for it.
+                    - Do not tell the user you cannot search for information, YOU CAN.
+                    ${block(formatOptionalInstructionBlock('Search instructions', combinedAdditionalInstructions))}
+                `);
+    }
+}
+/**
+ * Adds the placeholder for an aggregated `USE` system-message section only once, preserving the section position from the first occurrence.
+ *
+ * @param requirements - Current model requirements.
+ * @param type - Aggregated `USE` commitment type being applied.
+ * @returns Requirements with the placeholder inserted when it was not already present.
+ * @private internal utility of `USE` commitments
+ */
+function appendAggregatedUseCommitmentPlaceholder(requirements, type) {
+    const placeholder = getAggregatedUseCommitmentPlaceholder(type);
+    if (requirements.systemMessage.includes(placeholder)) {
+        return requirements;
+    }
+    const systemMessage = requirements.systemMessage.trim()
+        ? `${requirements.systemMessage}\n\n${placeholder}`
+        : placeholder;
+    return {
+        ...requirements,
+        systemMessage,
+    };
+}
+/**
+ * Replaces temporary `USE` placeholders with one aggregated system-message block per commitment type.
+ *
+ * Distinct additional-instruction blocks are merged in stable source order while the hard-coded section is emitted only once.
+ *
+ * @param requirements - Model requirements produced by commitment-by-commitment application.
+ * @param commitments - Filtered commitments in their original source order.
+ * @returns Requirements with aggregated `USE` system-message sections.
+ * @private internal utility of `createAgentModelRequirementsWithCommitments`
+ */
+function aggregateUseCommitmentSystemMessages(requirements, commitments) {
+    const additionalInstructionsByType = new Map();
+    for (const commitment of commitments) {
+        if (!isAggregatedUseCommitmentType(commitment.type)) {
+            continue;
+        }
+        let additionalInstructions = additionalInstructionsByType.get(commitment.type);
+        if (!additionalInstructions) {
+            additionalInstructions = [];
+            additionalInstructionsByType.set(commitment.type, additionalInstructions);
+        }
+        const normalizedContent = spaceTrim$1(commitment.content);
+        if (normalizedContent && !additionalInstructions.includes(normalizedContent)) {
+            additionalInstructions.push(normalizedContent);
+        }
+    }
+    let systemMessage = requirements.systemMessage;
+    for (const [type, additionalInstructions] of additionalInstructionsByType) {
+        const placeholder = getAggregatedUseCommitmentPlaceholder(type);
+        if (!systemMessage.includes(placeholder)) {
+            continue;
+        }
+        systemMessage = systemMessage.replace(placeholder, createAggregatedUseCommitmentSystemMessage(type, additionalInstructions));
+    }
+    return {
+        ...requirements,
+        systemMessage,
+    };
+}
+
 /**
  * Client-side safe wrapper for fetching URL content
  *
@@ -21949,13 +22090,14 @@ async function fetchUrlContentViaBrowser(url, agentsServerUrl) {
  * 1. One-shot URL fetching: Simple function to fetch and scrape URL content
  * 2. Running browser: For complex tasks like scrolling, clicking, form filling, etc.
  *
- * The content following `USE BROWSER` is ignored (similar to NOTE).
+ * The content following `USE BROWSER` is an arbitrary text that the agent should know
+ * (e.g. browsing scope or preferred sources).
  *
  * Example usage in agent source:
  *
  * ```book
  * USE BROWSER
- * USE BROWSER This will be ignored
+ * USE BROWSER Prefer official documentation and source websites.
  * ```
  *
  * @private [🪔] Maybe export the commitments through some package
@@ -21993,7 +22135,7 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
 
             ## Key aspects
 
-            - The content following \`USE BROWSER\` is ignored (similar to NOTE)
+            - The content following \`USE BROWSER\` is an arbitrary text that the agent should know (e.g. browsing scope or preferred sources).
             - Provides two levels of browser access:
               1. **One-shot URL fetching**: Simple function to fetch and scrape URL content (active)
               2. **Running browser**: For complex tasks like scrolling, clicking, form filling, etc. (runtime-dependent)
@@ -22110,20 +22252,14 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
             });
         }
         const updatedTools = [...existingTools, ...toolsToAdd];
-        // Return requirements with updated tools and metadata
-        return this.appendToSystemMessage({
+        return appendAggregatedUseCommitmentPlaceholder({
             ...requirements,
             tools: updatedTools,
             _metadata: {
                 ...requirements._metadata,
                 useBrowser: true,
             },
-        }, spaceTrim$1(`
-                You have access to browser tools to fetch and access content from the internet.
-                - Use "fetch_url_content" to retrieve content from specific URLs (webpages or documents) using scrapers.
-                - Use "run_browser" for real interactive browser automation (navigation, clicks, typing, waiting, scrolling).
-                When you need to know information from a specific website or document, use the fetch_url_content tool.
-            `));
+        }, this.type);
     }
     /**
      * Gets the browser tool function implementations.
@@ -25910,7 +26046,6 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        const extraInstructions = formatOptionalInstructionBlock('Search instructions', content);
         // Get existing tools array or create new one
         const existingTools = requirements.tools || [];
         // Add 'web_search' to tools if not already present
@@ -25923,7 +26058,6 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
                     description: spaceTrim$1(`
                         Search the internet for information.
                         Use this tool when you need to find up-to-date information or facts that you don't know.
-                        ${!content ? '' : `Search scope / instructions: ${content}`}
                     `),
                     parameters: {
                         type: 'object',
@@ -25961,23 +26095,14 @@ class UseSearchEngineCommitmentDefinition extends BaseCommitmentDefinition {
                     },
                 },
             ];
-        // Return requirements with updated tools and metadata
-        return this.appendToSystemMessage({
+        return appendAggregatedUseCommitmentPlaceholder({
             ...requirements,
             tools: updatedTools,
             _metadata: {
                 ...requirements._metadata,
                 useSearchEngine: content || true,
             },
-        }, spaceTrim$1((block) => `
-                    Tool:
-                    - You have access to the web search engine via the tool "web_search".
-                    - Use it to find up-to-date information or facts that you don't know.
-                    - When you need to know some information from the internet, use the tool provided to you.
-                    - Do not make up information when you can search for it.
-                    - Do not tell the user you cannot search for information, YOU CAN.
-                    ${block(extraInstructions)}
-            `));
+        }, this.type);
     }
     /**
      * Gets human-readable titles for tool functions provided by this commitment.
@@ -27088,7 +27213,6 @@ class UseTimeCommitmentDefinition extends BaseCommitmentDefinition {
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        const extraInstructions = formatOptionalInstructionBlock('Time instructions', content);
         // Get existing tools array or create new one
         const existingTools = requirements.tools || [];
         // Add 'get_current_time' to tools if not already present
@@ -27112,19 +27236,13 @@ class UseTimeCommitmentDefinition extends BaseCommitmentDefinition {
                 },
                 // <- TODO: !!!! define the function in LLM tools
             ];
-        // Return requirements with updated tools and metadata
-        return this.appendToSystemMessage({
+        return appendAggregatedUseCommitmentPlaceholder({
             ...requirements,
             tools: updatedTools,
             _metadata: {
                 ...requirements._metadata,
             },
-        }, spaceTrim$1((block) => `
-                    Time and date context:
-                    - It is ${moment().format('MMMM YYYY')} now.
-                    - If you need more precise current time information, use the tool "get_current_time".
-                    ${block(extraInstructions)}
-                `));
+        }, this.type);
     }
     /**
      * Gets human-readable titles for tool functions provided by this commitment.
@@ -39074,6 +39192,7 @@ async function createAgentModelRequirementsWithCommitments(agentSource, modelNam
             }
         }
     }
+    requirements = aggregateUseCommitmentSystemMessages(requirements, filteredCommitments);
     // Handle IMPORT commitments for generic files
     // Note: This logic could be moved to ImportCommitmentDefinition, but it needs to be asynchronous
     if (requirements.importedFileUrls && requirements.importedFileUrls.length > 0) {
@@ -41434,24 +41553,36 @@ const AGENT_GIT_EMAIL_ENV = 'CODING_AGENT_GIT_EMAIL';
  * Environment variable that configures the signing key used for agent commits.
  */
 const AGENT_GIT_SIGNING_KEY_ENV = 'CODING_AGENT_GIT_SIGNING_KEY';
-let cachedIdentity;
 /**
- * Reads the required agent identity values from the environment and remembers them for the lifetime of the script.
+ * Legacy environment variable that can also provide the signing key used for agent commits.
+ */
+const AGENT_GPG_KEY_ID_ENV = 'CODING_AGENT_GPG_KEY_ID';
+/**
+ * Environment variables accepted for the coding-agent Git signing key.
+ */
+const AGENT_GIT_SIGNING_KEY_ENV_ALIASES = [AGENT_GIT_SIGNING_KEY_ENV, AGENT_GPG_KEY_ID_ENV];
+/**
+ * Reads the optional agent identity values from the environment.
+ *
+ * Falls back to the user's default Git configuration whenever the dedicated coding-agent
+ * identity is only partially configured.
  */
 function getAgentGitIdentity() {
-    if (cachedIdentity) {
-        return cachedIdentity;
+    const name = readOptionalEnvValue(AGENT_GIT_NAME_ENV);
+    const email = readOptionalEnvValue(AGENT_GIT_EMAIL_ENV);
+    const signingKey = readOptionalSigningKeyValue();
+    if (!name || !email || !signingKey) {
+        return undefined;
     }
-    const name = readRequiredEnvValue(AGENT_GIT_NAME_ENV);
-    const email = readRequiredEnvValue(AGENT_GIT_EMAIL_ENV);
-    const signingKey = readRequiredEnvValue(AGENT_GIT_SIGNING_KEY_ENV);
-    cachedIdentity = { name, email, signingKey };
-    return cachedIdentity;
+    return { name, email, signingKey };
 }
 /**
- * Builds the environment overrides that ensure git commits use the agent identity instead of the primary user.
+ * Builds the environment overrides that ensure git commits use the dedicated agent identity instead of the primary user.
  */
 function buildAgentGitEnv(identity = getAgentGitIdentity()) {
+    if (!identity) {
+        return undefined;
+    }
     return {
         GIT_AUTHOR_NAME: identity.name,
         GIT_AUTHOR_EMAIL: identity.email,
@@ -41463,24 +41594,47 @@ function buildAgentGitEnv(identity = getAgentGitIdentity()) {
  * Produces the git commit flag that enforces signing with the configured agent key.
  */
 function buildAgentGitSigningFlag(identity = getAgentGitIdentity()) {
+    if (!identity) {
+        return undefined;
+    }
     return `--gpg-sign="${identity.signingKey}"`;
 }
 /**
- * Reads a required environment variable and fails fast with a helpful message if it is missing.
+ * Prints a one-time style tip when coding-agent commits fall back to the user's default Git configuration.
  */
-function readRequiredEnvValue(name) {
+function printAgentGitIdentityTipIfNeeded() {
+    if (getAgentGitIdentity()) {
+        return;
+    }
+    console.info(colors.cyan(spaceTrim$1(`
+            Tip: \`ptbk coder run\` used your default Git config because the coding-agent identity environment variables are incomplete.
+            For cleaner commit history, set \`CODING_AGENT_GIT_NAME\`, \`CODING_AGENT_GIT_EMAIL\`, and either \`CODING_AGENT_GIT_SIGNING_KEY\` or \`CODING_AGENT_GPG_KEY_ID\`.
+        `)));
+}
+/**
+ * Reads one optional environment variable and trims it when present.
+ */
+function readOptionalEnvValue(name) {
     var _a;
     const value = (_a = process.env[name]) === null || _a === void 0 ? void 0 : _a.trim();
-    if (!value) {
-        throw new Error(`Missing required environment variable ${name}. ` +
-            'Set CODING_AGENT_GIT_NAME, CODING_AGENT_GIT_EMAIL, ' +
-            'and CODING_AGENT_GIT_SIGNING_KEY before running the coding agent.');
+    return value || undefined;
+}
+/**
+ * Reads the first configured signing-key environment variable.
+ */
+function readOptionalSigningKeyValue() {
+    for (const envName of AGENT_GIT_SIGNING_KEY_ENV_ALIASES) {
+        const value = readOptionalEnvValue(envName);
+        if (value) {
+            return value;
+        }
     }
-    return value;
+    return undefined;
 }
 
 /**
- * Commits staged changes with the provided message using the configured agent identity and signing key.
+ * Commits staged changes with the provided message using the dedicated coding-agent identity when configured,
+ * otherwise falls back to the default Git configuration.
  */
 async function commitChanges(message) {
     const commitMessagePath = join(process.cwd(), '.tmp', 'codex-prompts', `COMMIT_MESSAGE_${Date.now()}.txt`);
@@ -41488,12 +41642,13 @@ async function commitChanges(message) {
     await writeFile(commitMessagePath, message, 'utf-8');
     try {
         const agentEnv = buildAgentGitEnv();
+        const signingFlag = buildAgentGitSigningFlag();
         await $execCommand({
             command: 'git add .',
             env: agentEnv,
         });
         await $execCommand({
-            command: `git commit ${buildAgentGitSigningFlag()} --file "${commitMessagePath}"`,
+            command: buildGitCommitCommand(commitMessagePath, signingFlag),
             env: agentEnv,
         });
         await pushCommittedChanges(agentEnv);
@@ -41658,6 +41813,17 @@ async function executeGitPushCommand(command, agentEnv) {
         throw new GitPushFailedError(buildPushFailureMessage(command, error));
     }
 }
+/**
+ * Builds the `git commit` command with an optional signing flag.
+ */
+function buildGitCommitCommand(commitMessagePath, signingFlag) {
+    const commandParts = ['git commit'];
+    if (signingFlag) {
+        commandParts.push(signingFlag);
+    }
+    commandParts.push(`--file "${commitMessagePath}"`);
+    return commandParts.join(' ');
+}
 /**
  * Builds a failure message that includes actionable hints for common push problems.
  */
@@ -43909,15 +44075,25 @@ function buildCodexScript(options) {
     const loginMethodConfig = options.allowCredits ? '' : '  -c forced_login_method=chatgpt \\';
     const modelReasoningEffortConfig = '  -c model_reasoning_effort="xhigh" \\';
     return spaceTrim((block) => `
+
+            if [ -f .env ]; then
+            set -a
+            source .env
+            set +a
+            fi
+
+            unset OPENAI_API_KEY
+            unset OPENAI_BASE_URL
+
             ${options.codexCommand} \\
-              ${loginMethodConfig}
-              ${modelReasoningEffortConfig}
-              --ask-for-approval ${options.askForApproval} \\
-              exec --model ${options.model} \\
-              --local-provider none \\
-              --sandbox ${options.sandbox} \\
-              -C ${projectPath} \\
-              <<'${delimiter}'
+                ${loginMethodConfig}
+                ${modelReasoningEffortConfig}
+                --ask-for-approval ${options.askForApproval} \\
+                exec --model ${options.model} \\
+                --local-provider none \\
+                --sandbox ${options.sandbox} \\
+                -C ${projectPath} \\
+                <<'${delimiter}'
 
             ${block(options.prompt)}
 
@@ -44615,6 +44791,9 @@ async function runCodexPrompts(providedOptions) {
     }
     finally {
         progressDisplay === null || progressDisplay === void 0 ? void 0 : progressDisplay.stop();
+        if (!options.dryRun) {
+            printAgentGitIdentityTipIfNeeded();
+        }
     }
 }
 /**