@promptbook/cli 0.114.0-3 → 0.114.0-31

package/src/book-2.0/book-language-documentation/czechBookLanguageManualDictionary.ts

@@ -47,7 +47,7 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
                 2. **Vrstva chování**:
                 \`RULE\`, \`KNOWLEDGE\`, \`WRITING SAMPLE\`, \`WRITING RULES\`, \`LANGUAGE\`, \`GOAL\` a příbuzné commitmenty.
                 3. **Vrstva schopností**:
-                \`USE*\`, \`MEMORY\` a další nástrojové commitmenty, které agentovi otevírají běhové schopnosti.
+                \`USE*\` a další nástrojové commitmenty, které agentovi otevírají běhové schopnosti.
                 4. **Vrstva skládání**:
                 Dědičnost přes \`FROM\`, znovupoužití přes \`IMPORT\` a delegování přes \`TEAM\`.
             `),
@@ -69,9 +69,9 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
                 4. **Skládání místo jednoho velkého agenta**:
                 Na specializované odpovědnosti použijte \`TEAM\` nebo \`IMPORT\`.
                 Kompromis: režie s koordinací, výrazně lepší modularita a znovupoužitelnost.
-                5. **Řízená paměť**:
-                Pokud používáte \`MEMORY\`, popište, co se pamatovat má a co v žádném případě ne.
-                Kompromis: přísnější návrh pravidel, lepší soukromí i kvalita zapamatovaného.
+                5. **Řízená práce s daty**:
+                Pokud používáte \`USE PRIVACY\`, popište, co smí a co v žádném případě nesmí opustit konverzaci.
+                Kompromis: přísnější návrh pravidel, lepší soukromí i kvalita odpovědí.
             `),
         },
         primitives: {
@@ -102,7 +102,7 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
                 3. **Přidejte oporu ve znalostech**
                 Přidejte commitmenty \`KNOWLEDGE\` (přímý text, nebo lokální či importovatelné zdroje).
                 4. **Přidejte schopnosti**
-                Přidejte jen ty commitmenty \`USE*\` a \`MEMORY\`, které agent opravdu potřebuje.
+                Přidejte jen ty commitmenty \`USE*\`, které agent opravdu potřebuje.
                 5. **Doplňte profilová metadata**
                 Přidejte \`META DESCRIPTION\`, \`META AVATAR\` / \`META VISUAL\` nebo \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, \`META THINKING MESSAGE\` a případná upozornění.
                 6. **Připravte první interakci**
@@ -140,7 +140,12 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
                 \`FROM\` odkazuje na zdroj rodičovského agenta. Při vyhodnocení dědičnosti platí:
 
                 - Obsah rodiče se sloučí do výsledného zdroje.
-                - \`FROM {Void}\` / \`FROM VOID\` znamená výslovné „žádný rodič“.
+                - Když \`FROM\` není uvedeno vůbec, platí to samé jako \`FROM @Adam\`, tedy jádrový agent, ze kterého dědí každý agent.
+                - \`FROM @Null\` / \`FROM {Void}\` / \`FROM VOID\` znamená výslovné „žádný rodič“.
+                - Výslovně zvolený rodič nahradí implicitního Adama; vlastní řetězec \`FROM\` tohoto rodiče se pak zdědí běžným způsobem.
+                - \`@Jmeno\` je pro jednoslovné jméno agenta zkratka zápisu \`{Jmeno}\`.
+                - Když je \`FROM\` uvedeno vícekrát, platí poslední a přepíše všechna předchozí.
+                - Adam je kořenový agent a musí výslovně použít \`FROM @Null\` (\`@Void\` je ekvivalentní). Editor knihy upozorní na jiného Adamova rodiče i na lokální cykly dědičnosti.
                 - Chybějící odkazy se do výsledného zdroje propíší jako poznámky.
             `),
         },
@@ -155,7 +160,7 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
         capabilities: {
             title: 'Commitmenty USE',
             body: spaceTrim(`
-                Commitmenty \`USE*\` zapínají schopnosti (vyhledávání, prohlížeč, napojení na projekt, e-mail, generování obrázků a další).
+                Commitmenty \`USE*\` zapínají schopnosti (napojení na projekt, kalendář, generování obrázků a další).
                 Zpřístupňují běhové nástroje a doplňují pokyny do systémové zprávy.
             `),
         },
@@ -209,16 +214,6 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
                 '`CLOSED` brání tomu, aby se agent upravoval během konverzace.',
             ],
         },
-        'tool-using-browser-search-agent': {
-            title: 'Agent s nástroji (prohlížeč a vyhledávač)',
-            goal: 'Umožnit rešerši na internetu s jasnou prací se zdroji.',
-            walkthrough: [
-                '`USE SEARCH ENGINE` zpřístupní vyhledávání na webu a volitelné pokyny k němu.',
-                '`USE BROWSER` zapne stahování adres a interaktivní procházení webu.',
-                'Commitmenty `RULE` dělají požadavky na spolehlivost výslovnými a opakovatelnými.',
-                'Tento vzor se hodí pro agenty na aktuální dění a ověřování faktů.',
-            ],
-        },
         'rule-and-knowledge-agent': {
             title: 'Agent s RULE a KNOWLEDGE',
             goal: 'Opřít odpovědi o výslovná omezení a připravené zdroje.',
@@ -229,16 +224,6 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
                 'Tento vzor použijte pro compliance, podporu a interní postupy.',
             ],
         },
-        'memory-agent-with-long-term-memory': {
-            title: 'Agent s dlouhodobou pamětí (MEMORY)',
-            goal: 'Uchovat preference uživatele napříč konverzacemi.',
-            walkthrough: [
-                '`MEMORY` přidá běhové nástroje paměti a příslušné pokyny do systémové zprávy.',
-                'Commitmenty `RULE` zúží, co se smí pamatovat, a snižují tak rizika pro soukromí.',
-                'V Agents Serveru je paměť vedená za běhu a je vázaná na konkrétního uživatele.',
-                'Hodí se pro asistenty, kteří si musí držet kontext v čase.',
-            ],
-        },
         'use-project-integration-agent': {
             title: 'Napojení na projekt (USE PROJECT)',
             goal: 'Pracovat s repozitářem na GitHubu přes připojení projektu.',
@@ -283,7 +268,7 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
         {
             title: 'Neověřitelná tvrzení',
             dont: 'Agent odpovídá na otázky závislé na internetu bez nástrojů nebo bez uvedení zdrojů.',
-            doInstead: 'Přidejte `USE SEARCH ENGINE` / `USE BROWSER` a `RULE` zaměřené na citování.',
+            doInstead: 'Přidejte zdroje `KNOWLEDGE` a `RULE` zaměřené na citování.',
         },
         {
             title: 'Chybějící mantinely',
@@ -295,11 +280,6 @@ export const czechBookLanguageManualDictionary: BookLanguageManualDictionary = {
             dont: 'Dlouhé řetězce `FROM` bez vysvětlení, proč je každý rodič potřeba.',
             doInstead: 'Držte dědičnost mělkou a pro znovupoužití sáhněte po cíleném IMPORT nebo TEAM.',
         },
-        {
-            title: 'Nebezpečné zacházení s pamětí',
-            dont: 'Ukládání každého detailu do paměti bez jakýchkoli hranic.',
-            doInstead: 'Doplňte `MEMORY` výslovnými pravidly, co se smí uchovávat.',
-        },
     ],
     tutorialSections: {
         serverAgentsHint:

package/src/book-2.0/book-language-documentation/englishBookLanguageManualDictionary.ts

@@ -47,7 +47,7 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
                 2. **Behavior layer**:
                 \`RULE\`, \`KNOWLEDGE\`, \`WRITING SAMPLE\`, \`WRITING RULES\`, \`LANGUAGE\`, \`GOAL\`, and related commitments.
                 3. **Capability layer**:
-                \`USE*\`, \`MEMORY\`, and other tooling commitments exposing runtime abilities.
+                \`USE*\` and other tooling commitments exposing runtime abilities.
                 4. **Composition layer**:
                 \`FROM\` inheritance, \`IMPORT\` reuse, and \`TEAM\` delegation.
             `),
@@ -69,8 +69,8 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
                 4. **Composition over monoliths**:
                 Use \`TEAM\`/\`IMPORT\` for specialized responsibilities.
                 Tradeoff: orchestration overhead, stronger modularity and reuse.
-                5. **Controlled memory**:
-                If using \`MEMORY\`, define what must and must not be remembered.
+                5. **Controlled data access**:
+                If using \`USE PRIVACY\`, define what must and must not leave the conversation.
                 Tradeoff: stricter policy design, better privacy and signal quality.
             `),
         },
@@ -102,7 +102,7 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
                 3. **Add grounding**
                 Add \`KNOWLEDGE\` commitments (inline text or local/importable sources).
                 4. **Add capabilities**
-                Add only necessary \`USE*\` and/or \`MEMORY\` commitments.
+                Add only necessary \`USE*\` commitments.
                 5. **Set profile metadata**
                 Add \`META DESCRIPTION\`, \`META AVATAR\` / \`META VISUAL\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, \`META THINKING MESSAGE\`, and disclaimers if needed.
                 6. **Add first interaction**
@@ -140,7 +140,12 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
                 \`FROM\` points to a parent agent source. During inheritance resolution:
 
                 - Parent corpus is merged into effective source.
-                - \`FROM {Void}\` / \`FROM VOID\` means explicit "no parent".
+                - Writing no \`FROM\` at all is the same as writing \`FROM @Adam\`, the core agent every agent inherits from.
+                - \`FROM @Null\` / \`FROM {Void}\` / \`FROM VOID\` means explicit "no parent".
+                - An explicit parent replaces the implicit Adam parent; the selected parent's own \`FROM\` chain is then inherited normally.
+                - \`@Name\` is shorthand for \`{Name}\` when the agent name is one word.
+                - When \`FROM\` is written more than once, the last one wins and overrides every earlier one.
+                - Adam is the root agent and must explicitly use \`FROM @Null\` (\`@Void\` is equivalent). The Book editor warns about a different Adam parent and local inheritance cycles.
                 - Missing references are surfaced as notes in resolved source.
             `),
         },
@@ -155,7 +160,7 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
         capabilities: {
             title: 'USE commitments',
             body: spaceTrim(`
-                \`USE*\` commitments enable capabilities (search, browser, project integration, email, image generation, etc.).
+                \`USE*\` commitments enable capabilities (project integration, calendar, image generation, etc.).
                 They expose runtime tools and system-message guidance used during execution.
             `),
         },
@@ -209,16 +214,6 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
                 '`CLOSED` prevents conversational self-modification.',
             ],
         },
-        'tool-using-browser-search-agent': {
-            title: 'Tool-using agent (Browser + Search engine)',
-            goal: 'Enable internet research with clear sourcing behavior.',
-            walkthrough: [
-                '`USE SEARCH ENGINE` provides web search tooling and optional search instructions.',
-                '`USE BROWSER` enables URL fetching and interactive browsing tools.',
-                '`RULE` commitments make reliability behavior explicit and repeatable.',
-                'This pattern is ideal for current-events and fact-checking agents.',
-            ],
-        },
         'rule-and-knowledge-agent': {
             title: 'Agent with RULE and KNOWLEDGE',
             goal: 'Ground responses in explicit constraints and curated sources.',
@@ -229,16 +224,6 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
                 'Use this pattern for compliance, support, and internal procedures.',
             ],
         },
-        'memory-agent-with-long-term-memory': {
-            title: 'MEMORY agent with long-term memory',
-            goal: 'Persist user preferences across conversations.',
-            walkthrough: [
-                '`MEMORY` adds runtime memory tools and memory-specific system guidance.',
-                '`RULE` commitments narrow what should be remembered to reduce privacy risks.',
-                'In Agents Server, memory is runtime-backed and user-scoped.',
-                'Use this for assistants that must preserve context over time.',
-            ],
-        },
         'use-project-integration-agent': {
             title: 'USE PROJECT external integration',
             goal: 'Work with a GitHub repository through a connected project integration.',
@@ -283,7 +268,7 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
         {
             title: 'Unverifiable claims',
             dont: 'The agent answers internet-dependent questions without tools or without citing sources.',
-            doInstead: 'Add `USE SEARCH ENGINE` / `USE BROWSER` and a citation-oriented `RULE`.',
+            doInstead: 'Add `KNOWLEDGE` sources and a citation-oriented `RULE`.',
         },
         {
             title: 'Missing guardrails',
@@ -295,11 +280,6 @@ export const englishBookLanguageManualDictionary: BookLanguageManualDictionary =
             dont: 'Using deep `FROM` chains without documenting why each parent is needed.',
             doInstead: 'Keep inheritance shallow and use focused IMPORT/TEAM composition for reuse.',
         },
-        {
-            title: 'Unsafe memory usage',
-            dont: 'Storing every detail in memory without boundaries.',
-            doInstead: 'Pair `MEMORY` with explicit rules about what is allowed to persist.',
-        },
     ],
     tutorialSections: {
         serverAgentsHint:

package/src/book-2.0/book-language-documentation/renderCommitmentCatalogSection.ts

@@ -53,10 +53,7 @@ export function renderCommitmentCatalogSection(options: RenderCommitmentCatalogS
             ${aliasesMarkdown}
 
             ${block(
-                renderGroupedCommitmentDocumentationMarkdown(
-                    groupedCommitment,
-                    COMMITMENT_CATALOG_HEADING_LEVEL_SHIFT,
-                ),
+                renderGroupedCommitmentDocumentationMarkdown(groupedCommitment, COMMITMENT_CATALOG_HEADING_LEVEL_SHIFT),
             )}
         `,
     );

package/src/book-2.0/book-language-documentation/renderGroupedCommitmentDocumentationMarkdown.ts

@@ -196,10 +196,7 @@ export function renderGroupedCommitmentDocumentationMarkdown(
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
-function renderFocusedCommitmentExamples(
-    documentation: string,
-    group: GroupedCommitmentDocumentationSource,
-): string {
+function renderFocusedCommitmentExamples(documentation: string, group: GroupedCommitmentDocumentationSource): string {
     return documentation.replace(BOOK_CODE_BLOCK_PATTERN, (codeBlock, _fence, source: string) => {
         const focusedSource = createFocusedCommitmentExampleSource(source, group);
         return focusedSource ? getSafeCodeBlock(focusedSource, 'book') : codeBlock;
@@ -223,12 +220,7 @@ function createFocusedCommitmentExampleSource(
     const commitmentTypes = new Set([group.primary.type, ...group.aliases]);
     const isOpenClosedCommitmentFamily =
         commitmentTypes.has(OPEN_COMMITMENT_TYPE) && commitmentTypes.has(CLOSED_COMMITMENT_TYPE);
-    const allowedCommitmentTypes = new Set([
-        group.primary.type,
-        ...group.aliases,
-        'GOAL',
-        CLOSED_COMMITMENT_TYPE,
-    ]);
+    const allowedCommitmentTypes = new Set([group.primary.type, ...group.aliases, 'GOAL', CLOSED_COMMITMENT_TYPE]);
     const canonicalTypeByCommitmentType = createCanonicalCommitmentTypeByCommitmentType(
         group,
         isOpenClosedCommitmentFamily,
@@ -384,9 +376,7 @@ function finalizeFocusedCommitmentExampleSource(
         normalizedFocusedCommitments.push(CLOSED_COMMITMENT_TYPE);
     }
 
-    return [agentName, ...normalizedFocusedCommitments]
-        .filter((line): line is string => Boolean(line))
-        .join('\n\n');
+    return [agentName, ...normalizedFocusedCommitments].filter((line): line is string => Boolean(line)).join('\n\n');
 }
 
 /**
@@ -427,10 +417,7 @@ function createCanonicalCommitmentTypeByCommitmentType(
     canonicalTypeByCommitmentType.set(group.primary.type, group.primary.type);
 
     for (const alias of group.aliases) {
-        canonicalTypeByCommitmentType.set(
-            alias,
-            isOpenClosedCommitmentFamily ? alias : group.primary.type,
-        );
+        canonicalTypeByCommitmentType.set(alias, isOpenClosedCommitmentFamily ? alias : group.primary.type);
     }
 
     return canonicalTypeByCommitmentType;

package/src/book-3.0/AgentMessageRunReport.ts

@@ -1,6 +1,10 @@
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 import type { Usage } from '../execution/Usage';
+import type { AgentMessageProjectChange } from '../utils/agent-message-runtime/AgentMessageProjectChange';
+import { normalizeAgentMessageProjectChange } from '../utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+import { normalizeAgentMessageTouchedExternalSource } from '../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
 import type { CodexLoginMethod } from './codexLoginMethod';
 
 /**
@@ -13,6 +17,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 +75,37 @@ 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>;
+
+    /**
+     * Sources outside the agent — integrations, websites and web searches — the harness reached
+     * while answering the message.
+     *
+     * Reported from the same live runtime log as `touchedProjectNames`, so this is the only trace
+     * of what one answer touched beyond the agent itself.
+     */
+    readonly touchedExternalSources?: ReadonlyArray<AgentMessageTouchedExternalSource>;
+
+    /**
+     * Changes the harness made to the agent projects while answering the message.
+     *
+     * Every agent project is a git repository and the runner commits each answer into it, so one
+     * entry describes exactly what one message did to one project — including the diff of the
+     * commit it created.
+     */
+    readonly projectChanges?: ReadonlyArray<AgentMessageProjectChange>;
 };
 
 /**
@@ -110,9 +164,90 @@ 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;
+    }
+
+    if (
+        report.touchedExternalSources !== undefined &&
+        !isSerializedTouchedExternalSourceList(report.touchedExternalSources)
+    ) {
+        return null;
+    }
+
+    if (report.projectChanges !== undefined && !isSerializedProjectChangeList(report.projectChanges)) {
+        return null;
+    }
+
     return report as AgentMessageRunReport;
 }
 
+/**
+ * Checks that one value structurally matches a list of project changes.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedProjectChangeList(value: unknown): value is ReadonlyArray<AgentMessageProjectChange> {
+    return (
+        Array.isArray(value) &&
+        value.every((projectChange) => normalizeAgentMessageProjectChange(projectChange) !== null)
+    );
+}
+
+/**
+ * Checks that one value structurally matches a list of touched external sources.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedTouchedExternalSourceList(
+    value: unknown,
+): value is ReadonlyArray<AgentMessageTouchedExternalSource> {
+    return (
+        Array.isArray(value) &&
+        value.every((externalSource) => normalizeAgentMessageTouchedExternalSource(externalSource) !== null)
+    );
+}
+
+/**
+ * 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.
  *