@promptbook/cli 0.114.0-11 → 0.114.0-13

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves which projects one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a project counts as touched when the
+ * harness named it in a tool invocation — reading, searching, running, or editing files inside
+ * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+ * narration are ignored so a project merely mentioned in the conversation is never reported.
+ *
+ * Every candidate is matched against the projects that really exist, which both filters prompt
+ * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+ *
+ * @param options - Raw runtime log content and the project directory names of the agent.
+ * @returns Touched project names in the canonical spelling, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedProjectNames(options: {
+    readonly logText: string | null | undefined;
+    readonly knownProjectNames: ReadonlyArray<string>;
+}): ReadonlyArray<string>;

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-10`).
+ * It follows semantic versioning (e.g., `0.114.0-12`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.114.0-11",
+    "version": "0.114.0-13",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/book-2.0/agent-source/AgentSourceParseResult.ts

@@ -1,5 +1,6 @@
 import type { ParsedCommitment } from '../../commitments/_base/ParsedCommitment';
 import type { string_agent_name } from '../../types/string_agent_name';
+import type { ParsedUnknownCommitment } from './ParsedUnknownCommitment';
 
 /**
  * Result of parsing agent source for commitments
@@ -22,6 +23,11 @@ export type AgentSourceParseResult = {
      */
     commitments: ParsedCommitment[];
 
+    /**
+     * Uppercase commitment blocks whose types are not registered by Promptbook.
+     */
+    unknownCommitments: ParsedUnknownCommitment[];
+
     /**
      * Lines that are not commitments (for system message)
      */

package/src/book-2.0/agent-source/ParsedUnknownCommitment.ts

@@ -0,0 +1,29 @@
+/**
+ * An uppercase Book commitment block whose keyword is not registered by Promptbook.
+ *
+ * Unknown commitments are retained as system-message context instead of being applied
+ * as executable commitments.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+export type ParsedUnknownCommitment = {
+    /**
+     * Uppercase unknown commitment type, for example `FOO` or `BAR BZZ`.
+     */
+    readonly type: string;
+
+    /**
+     * Original first line, retained for precise editor diagnostics.
+     */
+    readonly originalLine: string;
+
+    /**
+     * Line number in the agent source (1-based).
+     */
+    readonly lineNumber: number;
+
+    /**
+     * Complete unknown commitment block, including its keyword and continuation lines.
+     */
+    readonly source: string;
+};

package/src/book-2.0/agent-source/createAgentModelRequirementsWithCommitments/augmentAgentModelRequirementsFromSource.ts

@@ -46,8 +46,9 @@ export async function augmentAgentModelRequirementsFromSource(
     requirements = await importReferencedFiles(requirements);
     requirements = appendMcpServers(requirements, agentSource);
     requirements = appendNonCommitmentContent(requirements, parseResult);
+    requirements = appendExampleInteractions(requirements, parseResult);
 
-    return appendExampleInteractions(requirements, parseResult);
+    return appendUnknownCommitmentContent(requirements, parseResult);
 }
 
 /**
@@ -188,6 +189,42 @@ function appendNonCommitmentContent(
     return appendSystemMessageSection(requirements, nonCommitmentContent);
 }
 
+/**
+ * Appends unknown commitment blocks as final extra context without applying commitment side effects.
+ *
+ * @param requirements - Current requirements snapshot.
+ * @param parseResult - Parsed source including unknown commitment blocks.
+ * @returns Requirements with unknown commitment context appended at the end of the system message.
+ *
+ * @private internal utility of `augmentAgentModelRequirementsFromSource`
+ */
+function appendUnknownCommitmentContent(
+    requirements: AgentModelRequirements,
+    parseResult: ParsedAgentSourceWithCommitments,
+): AgentModelRequirements {
+    const unknownCommitmentContent = getUnknownCommitmentContent(parseResult);
+    if (!unknownCommitmentContent) {
+        return requirements;
+    }
+
+    return appendSystemMessageSection(requirements, unknownCommitmentContent);
+}
+
+/**
+ * Joins unknown commitment blocks into their final extra-context representation.
+ *
+ * @param parseResult - Parsed source including unknown commitment blocks.
+ * @returns Unknown commitment source blocks in their original order.
+ *
+ * @private internal utility of `appendUnknownCommitmentContent`
+ */
+function getUnknownCommitmentContent(parseResult: ParsedAgentSourceWithCommitments): string {
+    return parseResult.unknownCommitments
+        .map((commitment) => commitment.source)
+        .filter(Boolean)
+        .join('\n\n');
+}
+
 /**
  * Collects plain-text lines that were not parsed as commitments and should still become part of the final system message.
  *

package/src/book-2.0/agent-source/getBookCommitmentLineType.ts

@@ -0,0 +1,36 @@
+/**
+ * Pattern shared by Book parsing and editor highlighting for a commitment-like line.
+ *
+ * A Book commitment keyword consists of one or more all-uppercase words with at least
+ * two characters each. This deliberately mirrors the Book editor syntax rule so an
+ * unknown keyword starts a new source block everywhere it is interpreted.
+ *
+ * @private internal constant of `getBookCommitmentLineType`
+ */
+const BOOK_COMMITMENT_LINE_TYPE_REGEX = /^\s*(?<type>[A-Z][A-Z0-9]+(?:\s+[A-Z][A-Z0-9]+)*)(?=\s|$)/;
+
+/**
+ * Creates the regex used to recognize the uppercase commitment type at the beginning of a Book line.
+ *
+ * A fresh regular expression keeps Monaco tokenizer state isolated from parser calls.
+ *
+ * @returns Regular expression matching one Book commitment-like line.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export function createBookCommitmentLineTypeRegex(): RegExp {
+    return new RegExp(BOOK_COMMITMENT_LINE_TYPE_REGEX.source);
+}
+
+/**
+ * Extracts the uppercase commitment type from a Book line, including types not registered by Promptbook.
+ *
+ * @param line - One raw Book source line.
+ * @returns Matched commitment type or `null` when the line does not begin with commitment syntax.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export function getBookCommitmentLineType(line: string): string | null {
+    const match = BOOK_COMMITMENT_LINE_TYPE_REGEX.exec(line);
+    return match?.groups?.type || null;
+}

package/src/book-2.0/agent-source/parseAgentSourceWithCommitments.ts

@@ -3,7 +3,9 @@ import type { BookCommitment } from '../../commitments/_base/BookCommitment';
 import type { ParsedCommitment } from '../../commitments/_base/ParsedCommitment';
 import { COMMITMENT_REGISTRY } from '../../commitments/index';
 import type { AgentSourceParseResult } from './AgentSourceParseResult';
+import { getBookCommitmentLineType } from './getBookCommitmentLineType';
 import { parseAgentSourcePrelude } from './parseAgentSourcePrelude';
+import type { ParsedUnknownCommitment } from './ParsedUnknownCommitment';
 import type { string_book } from './string_book';
 
 /**
@@ -12,6 +14,39 @@ import type { string_book } from './string_book';
  */
 const HORIZONTAL_LINE_PATTERN = /^[\s]*[-_*][\s]*[-_*][\s]*[-_*][\s]*[-_*]*[\s]*$/;
 
+/**
+ * Registered commitment block currently being collected from Book source.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+type CurrentKnownCommitment = {
+    readonly kind: 'known';
+    readonly type: string;
+    readonly startLineNumber: number;
+    readonly originalStartLine: string;
+    readonly contentLines: string[];
+};
+
+/**
+ * Unknown commitment block currently being collected from Book source.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+type CurrentUnknownCommitment = {
+    readonly kind: 'unknown';
+    readonly type: string;
+    readonly startLineNumber: number;
+    readonly originalStartLine: string;
+    readonly sourceLines: string[];
+};
+
+/**
+ * Commitment-like source block currently being collected.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+type CurrentCommitment = CurrentKnownCommitment | CurrentUnknownCommitment;
+
 /**
  * Parses agent source using the new commitment system with multiline support
  * This function replaces the hardcoded commitment parsing in the original parseAgentSource
@@ -26,6 +61,7 @@ export function parseAgentSourceWithCommitments(agentSource: string_book): Omit<
         return {
             agentName: null,
             commitments: [],
+            unknownCommitments: [],
             nonCommitmentLines: [],
         };
     }
@@ -33,15 +69,11 @@ export function parseAgentSourceWithCommitments(agentSource: string_book): Omit<
     const { lines, agentName, agentNameLineIndex, agentNameLineNumber } = parseAgentSourcePrelude(agentSource);
 
     const commitments: ParsedCommitment[] = [];
+    const unknownCommitments: ParsedUnknownCommitment[] = [];
     const nonCommitmentLines: string[] = agentNameLineIndex >= 0 ? [lines[agentNameLineIndex]!] : [];
 
-    // Parse commitments with multiline support
-    let currentCommitment: {
-        type: string;
-        startLineNumber: number;
-        originalStartLine: string;
-        contentLines: string[];
-    } | null = null;
+    // Parse commitments with multiline support.
+    let currentCommitment: CurrentCommitment | null = null;
 
     // Process lines starting from after the agent name line
     const startIndex = agentNameLineIndex >= 0 ? agentNameLineIndex + 1 : 0;
@@ -58,24 +90,12 @@ export function parseAgentSourceWithCommitments(agentSource: string_book): Omit<
         if (trimmedLine.startsWith('```')) {
             isInsideCodeBlock = !isInsideCodeBlock;
 
-            if (currentCommitment) {
-                // If we are inside a commitment, the code block is part of it
-                currentCommitment.contentLines.push(line);
-            } else {
-                // If we are not inside a commitment, the code block is non-commitment
-                nonCommitmentLines.push(line);
-            }
+            appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
             continue;
         }
 
         if (isInsideCodeBlock) {
-            if (currentCommitment) {
-                // If we are inside a commitment and a code block, the line is part of the commitment
-                currentCommitment.contentLines.push(line);
-            } else {
-                // If we are inside a code block but not a commitment, the line is non-commitment
-                nonCommitmentLines.push(line);
-            }
+            appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
             continue;
         }
 
@@ -86,16 +106,7 @@ export function parseAgentSourceWithCommitments(agentSource: string_book): Omit<
             const match = typeRegex.exec(line.trim());
 
             if (match && match.groups?.type) {
-                // Save the previous commitment if it exists
-                if (currentCommitment) {
-                    const fullContent = currentCommitment.contentLines.join('\n');
-                    commitments.push({
-                        type: currentCommitment.type as BookCommitment,
-                        content: spaceTrim(fullContent),
-                        originalLine: currentCommitment.originalStartLine,
-                        lineNumber: currentCommitment.startLineNumber,
-                    });
-                }
+                appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
 
                 // Extract the initial content from the commitment line
                 const fullRegex = definition.createRegex();
@@ -104,6 +115,7 @@ export function parseAgentSourceWithCommitments(agentSource: string_book): Omit<
 
                 // Start a new commitment
                 currentCommitment = {
+                    kind: 'known',
                     type: definition.type,
                     startLineNumber: i + 1,
                     originalStartLine: line,
@@ -114,51 +126,106 @@ export function parseAgentSourceWithCommitments(agentSource: string_book): Omit<
             }
         }
 
+        if (foundNewCommitment) {
+            continue;
+        }
+
+        const unknownCommitmentType = getBookCommitmentLineType(line);
+        if (unknownCommitmentType) {
+            appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
+            currentCommitment = {
+                kind: 'unknown',
+                type: unknownCommitmentType,
+                startLineNumber: i + 1,
+                originalStartLine: line,
+                sourceLines: [line],
+            };
+            continue;
+        }
+
         // Check if this is a horizontal line (ends any current commitment)
         const isHorizontalLine = HORIZONTAL_LINE_PATTERN.test(line);
         if (isHorizontalLine) {
-            // Save the current commitment if it exists
-            if (currentCommitment) {
-                const fullContent = currentCommitment.contentLines.join('\n');
-                commitments.push({
-                    type: currentCommitment.type as BookCommitment,
-                    content: spaceTrim(fullContent),
-                    originalLine: currentCommitment.originalStartLine,
-                    lineNumber: currentCommitment.startLineNumber,
-                });
-                currentCommitment = null;
-            }
+            appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
+            currentCommitment = null;
             // Add horizontal line to non-commitment lines
             nonCommitmentLines.push(line);
             continue;
         }
 
-        if (!foundNewCommitment) {
-            if (currentCommitment) {
-                // This line belongs to the current commitment
-                currentCommitment.contentLines.push(line);
-            } else {
-                // This line is not part of any commitment
-                nonCommitmentLines.push(line);
-            }
-        }
+        appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
     }
 
-    // Don't forget to save the last commitment if it exists
-    if (currentCommitment) {
-        const fullContent = currentCommitment.contentLines.join('\n');
-        commitments.push({
-            type: currentCommitment.type as BookCommitment,
-            content: spaceTrim(fullContent) as BookCommitment,
-            originalLine: currentCommitment.originalStartLine,
-            lineNumber: currentCommitment.startLineNumber,
-        });
-    }
+    appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
 
     return {
         agentName,
         agentNameLineNumber,
         commitments,
+        unknownCommitments,
         nonCommitmentLines,
     };
 }
+
+/**
+ * Stores the current known or unknown commitment in its appropriate parsed collection.
+ *
+ * @param currentCommitment - Commitment-like block collected so far.
+ * @param commitments - Parsed registered commitments to append to.
+ * @param unknownCommitments - Parsed unregistered commitments to append to.
+ *
+ * @private internal utility of `parseAgentSourceWithCommitments`
+ */
+function appendCurrentCommitment(
+    currentCommitment: CurrentCommitment | null,
+    commitments: ParsedCommitment[],
+    unknownCommitments: ParsedUnknownCommitment[],
+): void {
+    if (!currentCommitment) {
+        return;
+    }
+
+    if (currentCommitment.kind === 'unknown') {
+        unknownCommitments.push({
+            type: currentCommitment.type,
+            originalLine: currentCommitment.originalStartLine,
+            lineNumber: currentCommitment.startLineNumber,
+            source: spaceTrim(currentCommitment.sourceLines.join('\n')),
+        });
+        return;
+    }
+
+    commitments.push({
+        type: currentCommitment.type as BookCommitment,
+        content: spaceTrim(currentCommitment.contentLines.join('\n')),
+        originalLine: currentCommitment.originalStartLine,
+        lineNumber: currentCommitment.startLineNumber,
+    });
+}
+
+/**
+ * Adds one source line to the active commitment-like block, or to plain source content when none is active.
+ *
+ * @param currentCommitment - Commitment-like block currently being collected.
+ * @param line - Source line to append.
+ * @param nonCommitmentLines - Plain source lines to append to when no block is active.
+ *
+ * @private internal utility of `parseAgentSourceWithCommitments`
+ */
+function appendLineToCurrentCommitmentOrNonCommitmentLines(
+    currentCommitment: CurrentCommitment | null,
+    line: string,
+    nonCommitmentLines: string[],
+): void {
+    if (!currentCommitment) {
+        nonCommitmentLines.push(line);
+        return;
+    }
+
+    if (currentCommitment.kind === 'unknown') {
+        currentCommitment.sourceLines.push(line);
+        return;
+    }
+
+    currentCommitment.contentLines.push(line);
+}

package/src/book-3.0/AgentMessageRunReport.ts

@@ -13,6 +13,25 @@ import type { CodexLoginMethod } from './codexLoginMethod';
  */
 export const AGENT_MESSAGE_RUN_REPORT_FILE_SUFFIX = '.report.json';
 
+/**
+ * Exact wall-clock interval during which one harness processed an agent message.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent folder convention
+ */
+export type AgentMessageRunExecutionTiming = {
+    /**
+     * ISO 8601 timestamp captured immediately before the harness begins the message.
+     */
+    readonly startedAt: string;
+
+    /**
+     * ISO 8601 timestamp captured when the harness finishes the message.
+     */
+    readonly finishedAt: string;
+};
+
 /**
  * Report describing how one queued agent message was answered by a CLI harness runner.
  *
@@ -52,6 +71,19 @@ export type AgentMessageRunReport = {
      * Usage statistics of the run (price, token counts, duration).
      */
     readonly usage: Usage;
+
+    /**
+     * Measured wall-clock timing of the actual harness execution, excluding time spent waiting in the queue.
+     */
+    readonly executionTiming?: AgentMessageRunExecutionTiming;
+
+    /**
+     * Directory names of the agent projects the harness worked with while answering the message.
+     *
+     * Reported by the runner from its live runtime log, which is deleted once the message is
+     * answered, so this is the only trace of the projects one answer viewed or edited.
+     */
+    readonly touchedProjectNames?: ReadonlyArray<string>;
 };
 
 /**
@@ -110,9 +142,53 @@ export function normalizeAgentMessageRunReport(value: unknown): AgentMessageRunR
         return null;
     }
 
+    if (report.executionTiming !== undefined && !isSerializedAgentMessageRunExecutionTiming(report.executionTiming)) {
+        return null;
+    }
+
+    if (report.touchedProjectNames !== undefined && !isSerializedProjectNameList(report.touchedProjectNames)) {
+        return null;
+    }
+
     return report as AgentMessageRunReport;
 }
 
+/**
+ * Checks that one value structurally matches a list of project directory names.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedProjectNameList(value: unknown): value is ReadonlyArray<string> {
+    return Array.isArray(value) && value.every((projectName) => typeof projectName === 'string');
+}
+
+/**
+ * Checks that one value contains a valid, non-negative agent-message execution interval.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedAgentMessageRunExecutionTiming(value: unknown): value is AgentMessageRunExecutionTiming {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+
+    const executionTiming = value as Record<string, unknown>;
+    if (!isSerializedIsoTimestamp(executionTiming.startedAt) || !isSerializedIsoTimestamp(executionTiming.finishedAt)) {
+        return false;
+    }
+
+    return Date.parse(executionTiming.finishedAt) >= Date.parse(executionTiming.startedAt);
+}
+
+/**
+ * Checks that one JSON value is a parseable ISO timestamp.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedIsoTimestamp(value: unknown): value is string {
+    return typeof value === 'string' && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+
 /**
  * Parses one run-report sidecar file content.
  *