@promptbook/pdf 0.113.0-9 → 0.114.0-0

package/umd/src/_packages/components.index.d.ts

@@ -69,6 +69,10 @@ import type { ChatParticipant } from '../book-components/Chat/types/ChatParticip
 import type { CitationLabelResolver } from '../book-components/Chat/types/CitationLabelResolver';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
+import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
 import { MicIcon } from '../book-components/icons/MicIcon';
 import { PauseIcon } from '../book-components/icons/PauseIcon';
@@ -154,6 +158,10 @@ export type { ChatParticipant };
 export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
+export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceMenuStatus };
+export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };
 export { PauseIcon };

package/umd/src/_packages/core.index.d.ts

@@ -22,6 +22,8 @@ import { parseParameters } from '../book-2.0/agent-source/parseParameters';
 import { isValidBook } from '../book-2.0/agent-source/string_book';
 import { validateBook } from '../book-2.0/agent-source/string_book';
 import { DEFAULT_BOOK } from '../book-2.0/agent-source/string_book';
+import type { BookLanguageDocumentationAgent } from '../book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown';
+import type { CreateStandaloneBookLanguageMarkdownOptions } from '../book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown';
 import { createStandaloneBookLanguageMarkdown } from '../book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown';
 import { generatePlaceholderAgentProfileImageUrl } from '../book-2.0/utils/generatePlaceholderAgentProfileImageUrl';
 import { Book } from '../book-3.0/Book';
@@ -258,6 +260,8 @@ export { parseParameters };
 export { isValidBook };
 export { validateBook };
 export { DEFAULT_BOOK };
+export type { BookLanguageDocumentationAgent };
+export type { CreateStandaloneBookLanguageMarkdownOptions };
 export { createStandaloneBookLanguageMarkdown };
 export { generatePlaceholderAgentProfileImageUrl };
 export { Book };

package/umd/src/_packages/types.index.d.ts

@@ -5,6 +5,8 @@ import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModel
 import type { AgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
 import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import type { string_book } from '../book-2.0/agent-source/string_book';
+import type { BookLanguageDocumentationAgent } from '../book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown';
+import type { CreateStandaloneBookLanguageMarkdownOptions } from '../book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown';
 import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
 import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
 import type { CliAgentHarness } from '../book-3.0/CliAgent';
@@ -59,6 +61,10 @@ import type { ChatParticipant } from '../book-components/Chat/types/ChatParticip
 import type { CitationLabelResolver } from '../book-components/Chat/types/CitationLabelResolver';
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
+import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
 import type { QrCodeOptions } from '../book-components/Qr/useQrCode';
 import type { AgentCollection } from '../collection/agent-collection/AgentCollection';
@@ -448,6 +454,8 @@ export type { AgentModelRequirements };
 export type { AgentVisibility };
 export type { CreateAgentModelRequirementsOptions };
 export type { string_book };
+export type { BookLanguageDocumentationAgent };
+export type { CreateStandaloneBookLanguageMarkdownOptions };
 export type { BookNodeAgentSource };
 export type { BookNodeAgentSourceOptions };
 export type { CliAgentHarness };
@@ -502,6 +510,10 @@ export type { ChatParticipant };
 export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
+export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceMenuStatus };
+export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };
 export type { AgentCollection };

package/umd/src/book-2.0/agent-source/AgentBasicInformation.d.ts

@@ -81,6 +81,13 @@ export type AgentBasicInformation = {
      * This is the line starting with "INITIAL MESSAGE"
      */
     initialMessage: string | null;
+    /**
+     * Optional custom thinking placeholder variants shown while this agent is composing a reply.
+     *
+     * This is derived from `META THINKING MESSAGE` commitments.
+     * Multiple commitments are preserved as multiple variants.
+     */
+    thinkingMessages?: Array<string>;
     /**
      * Metadata commitments parsed from META lines
      * Each META commitment has the format "META TYPE content"

package/umd/src/book-2.0/agent-source/parseAgentSource/ParsedAgentProfile.d.ts

@@ -4,4 +4,4 @@ import type { AgentBasicInformation } from '../AgentBasicInformation';
  *
  * @private internal utility of `parseAgentSource`
  */
-export type ParsedAgentProfile = Pick<AgentBasicInformation, 'meta' | 'links' | 'capabilities' | 'samples' | 'knowledgeSources'>;
+export type ParsedAgentProfile = Pick<AgentBasicInformation, 'meta' | 'links' | 'capabilities' | 'samples' | 'knowledgeSources' | 'thinkingMessages'>;

package/umd/src/book-2.0/book-language-documentation/BookLanguageDocumentationExample.d.ts

@@ -1,27 +1,19 @@
 /**
  * One end-to-end Book language example used in standalone documentation.
  *
+ * Only the language-neutral Book source lives here. Title, goal, and
+ * walkthrough are translated and therefore kept in
+ * `BookLanguageManualDictionary.exampleTexts`.
+ *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
 export type BookLanguageDocumentationExample = {
     /**
-     * Stable identifier used for markdown anchors.
+     * Stable identifier used for markdown anchors and translation lookup.
      */
     readonly id: string;
-    /**
-     * Human-readable example title.
-     */
-    readonly title: string;
-    /**
-     * Goal of the example in one short sentence.
-     */
-    readonly goal: string;
     /**
      * Full Book source shown to readers.
      */
     readonly source: string;
-    /**
-     * Step-by-step walkthrough of how the source works.
-     */
-    readonly walkthrough: ReadonlyArray<string>;
 };

package/umd/src/book-2.0/book-language-documentation/BookLanguageManualDictionary.d.ts

@@ -0,0 +1,195 @@
+import type { string_language } from '../../types/string_token';
+/**
+ * One chapter of the standalone Book language manual.
+ *
+ * The heading anchors are intentionally **not** part of the dictionary, so deep
+ * links stay stable across languages.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualChapter = {
+    /**
+     * Translated chapter heading.
+     */
+    readonly title: string;
+    /**
+     * Translated chapter body as markdown.
+     */
+    readonly body: string;
+};
+/**
+ * Translated prose of one end-to-end example.
+ *
+ * The Book source of an example is language-neutral and therefore stays in
+ * `bookLanguageDocumentationExamples`.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualExampleText = {
+    /**
+     * Translated example heading.
+     */
+    readonly title: string;
+    /**
+     * Translated one-line goal of the example.
+     */
+    readonly goal: string;
+    /**
+     * Translated walkthrough steps explaining the example source.
+     */
+    readonly walkthrough: ReadonlyArray<string>;
+};
+/**
+ * One practical "don't vs do" pitfall item for Book language authoring.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualPitfall = {
+    /**
+     * Short pitfall title.
+     */
+    readonly title: string;
+    /**
+     * Description of what to avoid.
+     */
+    readonly dont: string;
+    /**
+     * Practical corrective action.
+     */
+    readonly doInstead: string;
+};
+/**
+ * Every translatable string of the standalone Book language manual.
+ *
+ * Commitment reference bodies are deliberately excluded, because they are the
+ * canonical English specification maintained next to each commitment in
+ * `src/commitments`.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualDictionary = {
+    /**
+     * Language code this dictionary is written in.
+     */
+    readonly language: string_language;
+    /**
+     * Manual title used as the top-level heading.
+     */
+    readonly title: string;
+    /**
+     * Blockquote lines rendered directly under the manual title.
+     */
+    readonly introLines: ReadonlyArray<string>;
+    /**
+     * Labels of the generated manual metadata bullets.
+     */
+    readonly metadataLabels: {
+        readonly bookLanguageVersion: string;
+        readonly generatedAt: string;
+        readonly commitmentGroups: string;
+        readonly implementedCommitments: string;
+        readonly placeholderCommitments: string;
+    };
+    /**
+     * Heading of the table of contents.
+     */
+    readonly tableOfContentsTitle: string;
+    /**
+     * Chapters rendered in their canonical order.
+     */
+    readonly chapters: {
+        readonly whatIs: BookLanguageManualChapter;
+        readonly mentalModel: BookLanguageManualChapter;
+        readonly howToStructure: BookLanguageManualChapter;
+        readonly primitives: BookLanguageManualChapter;
+        readonly commitmentCatalog: BookLanguageManualChapter;
+        readonly examples: Pick<BookLanguageManualChapter, 'title'>;
+        readonly pitfalls: Pick<BookLanguageManualChapter, 'title'>;
+        readonly tutorial: BookLanguageManualChapter;
+        readonly lowLevelCommitments: BookLanguageManualChapter;
+    };
+    /**
+     * Sub-sections of the "Mental model of an agent" chapter.
+     */
+    readonly mentalModelSections: {
+        readonly detectedIntro: string;
+        readonly detectedProfileLabel: string;
+        readonly detectedBehaviorLabel: string;
+        readonly detectedToolingLabel: string;
+        readonly detectedCompositionLabel: string;
+        readonly meta: BookLanguageManualChapter;
+        readonly inheritance: BookLanguageManualChapter;
+        readonly composition: BookLanguageManualChapter;
+        readonly capabilities: BookLanguageManualChapter;
+    };
+    /**
+     * Sub-sections of the "Primitives and constructs reference" chapter.
+     */
+    readonly primitivesSections: {
+        readonly coreSyntax: BookLanguageManualChapter;
+        readonly references: BookLanguageManualChapter;
+        readonly keywordsTitle: string;
+    };
+    /**
+     * Suffixes distinguishing a server-specific catalog from the portable one.
+     */
+    readonly commitmentCatalogTitleSuffixes: {
+        readonly usedFirst: string;
+        readonly all: string;
+    };
+    /**
+     * Labels used in every commitment catalog entry.
+     */
+    readonly commitmentLabels: {
+        readonly status: string;
+        readonly aliases: string;
+        readonly semantics: string;
+        readonly typeSchema: string;
+        readonly blockSchema: string;
+        readonly lowLevelNotice: string;
+        readonly usage: string;
+        readonly usageOccurrence: string;
+        readonly usageOccurrences: string;
+        readonly statusImplemented: string;
+        readonly statusPlaceholder: string;
+        readonly noAliases: string;
+    };
+    /**
+     * Labels used by end-to-end example sections.
+     */
+    readonly exampleLabels: {
+        readonly commitmentsUsed: string;
+        readonly fullSource: string;
+        readonly goal: string;
+        readonly walkthrough: string;
+        readonly noCommitments: string;
+    };
+    /**
+     * Translated prose of the portable examples, keyed by example id.
+     */
+    readonly exampleTexts: Readonly<Record<string, BookLanguageManualExampleText>>;
+    /**
+     * Labels used by the "Do nots and common pitfalls" chapter.
+     */
+    readonly pitfallLabels: {
+        readonly dont: string;
+        readonly doInstead: string;
+    };
+    /**
+     * Translated pitfall entries.
+     */
+    readonly pitfalls: ReadonlyArray<BookLanguageManualPitfall>;
+    /**
+     * Closing parts of the "Build an agent from scratch" chapter.
+     */
+    readonly tutorialSections: {
+        readonly serverAgentsHint: string;
+        readonly templateIntro: string;
+        readonly checklistTitle: string;
+        readonly checklistBody: string;
+    };
+    /**
+     * Closing "Generated from" block of the manual.
+     */
+    readonly footer: BookLanguageManualChapter;
+};

package/umd/src/book-2.0/book-language-documentation/bookLanguageDocumentationExamples.d.ts

@@ -3,7 +3,8 @@ import type { BookLanguageDocumentationExample } from './BookLanguageDocumentati
  * End-to-end examples used by the standalone Book language documentation.
  *
  * These are intentionally compact but complete, so they can be copy-pasted and
- * used as practical starting points.
+ * used as practical starting points. Their prose lives in the manual
+ * dictionaries, keyed by the `id` of each example.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */

package/umd/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.d.ts

@@ -1,4 +1,46 @@
+import type { string_book } from '../agent-source/string_book';
 import type { string_markdown } from '../../types/string_markdown';
+import type { string_language } from '../../types/string_token';
+/**
+ * Agent source incorporated into a server-specific Book language manual.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type BookLanguageDocumentationAgent = {
+    /**
+     * Human-readable title shown above the baked example.
+     */
+    readonly agentName: string;
+    /**
+     * Current Book source used both as an example and to detect used commitments.
+     */
+    readonly agentSource: string_book;
+};
+/**
+ * Optional context used to tailor a standalone Book language manual.
+ *
+ * An empty `agents` array deliberately has the same effect as omitting this
+ * option, which keeps the non-customized manual portable between servers.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type CreateStandaloneBookLanguageMarkdownOptions = {
+    /**
+     * Server agents whose sources should be baked into examples and usage priority.
+     */
+    readonly agents?: ReadonlyArray<BookLanguageDocumentationAgent>;
+    /**
+     * Language the manual should be written in, English is used as the fallback.
+     */
+    readonly language?: string_language;
+    /**
+     * Whether the closing chapter with low-level commitments should be generated.
+     *
+     * Low-level commitments are intended for advanced use only, so they are
+     * omitted unless they are explicitly requested.
+     */
+    readonly isLowLevelCommitmentsIncluded?: boolean;
+};
 /**
  * Creates one standalone markdown guide for Book language (Book 2.0 / agent language).
  *
@@ -11,4 +53,4 @@ import type { string_markdown } from '../../types/string_markdown';
  *
  * @public exported from `@promptbook/core`
  */
-export declare function createStandaloneBookLanguageMarkdown(): string_markdown;
+export declare function createStandaloneBookLanguageMarkdown(options?: CreateStandaloneBookLanguageMarkdownOptions): string_markdown;

package/umd/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.test.d.ts

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

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

@@ -0,0 +1,10 @@
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+/**
+ * Czech translation of the standalone Book language manual.
+ *
+ * Commitment keywords are intentionally kept in English, because they are part
+ * of the Book language syntax and must be written exactly as-is.
+ *
+ * @private internal constant of `createStandaloneBookLanguageMarkdown`
+ */
+export declare const czechBookLanguageManualDictionary: BookLanguageManualDictionary;

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

@@ -0,0 +1,10 @@
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+/**
+ * Canonical English wording of the standalone Book language manual.
+ *
+ * Every other language pack is a translation of this dictionary and is resolved
+ * through `getBookLanguageManualDictionary`.
+ *
+ * @private internal constant of `createStandaloneBookLanguageMarkdown`
+ */
+export declare const englishBookLanguageManualDictionary: BookLanguageManualDictionary;

package/umd/src/book-2.0/book-language-documentation/getBookLanguageManualCommitmentGroups.d.ts

@@ -0,0 +1,33 @@
+import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
+/**
+ * One grouped commitment definition as returned by the runtime registry.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualCommitmentGroup = ReturnType<typeof getGroupedCommitmentDefinitions>[number];
+/**
+ * Commitment groups of the manual, split by how prominently they are documented.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualCommitmentGroups = {
+    /**
+     * Commitments documented in the main catalog.
+     */
+    readonly documented: ReadonlyArray<BookLanguageManualCommitmentGroup>;
+    /**
+     * Low-level and unfinished commitments documented in their own closing chapter.
+     */
+    readonly lowLevel: ReadonlyArray<BookLanguageManualCommitmentGroup>;
+};
+/**
+ * Splits the commitment registry into the groups documented by the manual.
+ *
+ * Deprecated commitments are intentionally left out completely, so that the
+ * manual never teaches a keyword that should no longer be written into a book.
+ *
+ * @returns Commitment groups for the main catalog and for the low-level chapter.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function getBookLanguageManualCommitmentGroups(): BookLanguageManualCommitmentGroups;

package/umd/src/book-2.0/book-language-documentation/getBookLanguageManualDictionary.d.ts

@@ -0,0 +1,15 @@
+import type { string_language } from '../../types/string_token';
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+/**
+ * Resolves the manual dictionary for one requested language.
+ *
+ * Unknown and region-qualified codes (for example `cs-CZ`) fall back to the
+ * closest available pack and finally to English, so an export never fails
+ * because of an unsupported language.
+ *
+ * @param language - Requested language code.
+ * @returns Manual dictionary for the requested language or the English fallback.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function getBookLanguageManualDictionary(language: string_language | null | undefined): BookLanguageManualDictionary;

package/umd/src/book-2.0/book-language-documentation/getSafeCodeBlock.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Creates a safe markdown fenced code block even when content contains backticks.
+ *
+ * @param content - Raw code content.
+ * @param language - Optional info-string language label.
+ * @returns Fenced code block.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function getSafeCodeBlock(content: string, language?: string): string;

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

@@ -0,0 +1,30 @@
+import type { BookLanguageManualDictionary } from './BookLanguageManualDictionary';
+import type { BookLanguageManualCommitmentGroup } from './getBookLanguageManualCommitmentGroups';
+/**
+ * Options for rendering one commitment section of the generated catalog.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type RenderCommitmentCatalogSectionOptions = {
+    /**
+     * Grouped commitment definition with aliases.
+     */
+    readonly groupedCommitment: BookLanguageManualCommitmentGroup;
+    /**
+     * Number of uses across the selected server agents.
+     */
+    readonly usageCount: number;
+    /**
+     * Translated labels of the manual.
+     */
+    readonly dictionary: BookLanguageManualDictionary;
+};
+/**
+ * Renders one commitment section in the generated catalog.
+ *
+ * @param options - Commitment group, usage statistics, and translated labels.
+ * @returns Markdown section for a single commitment.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function renderCommitmentCatalogSection(options: RenderCommitmentCatalogSectionOptions): string;

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

@@ -35,9 +35,10 @@ type GroupedCommitmentDocumentationSource = {
  * surfaces present them as one conceptual switch instead of two isolated pages.
  *
  * @param group - Grouped commitment metadata.
+ * @param headingLevelShift - How many levels the entry is nested by its host document.
  * @returns Markdown body for the docs page/catalog entry.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
-export declare function renderGroupedCommitmentDocumentationMarkdown(group: GroupedCommitmentDocumentationSource): string;
+export declare function renderGroupedCommitmentDocumentationMarkdown(group: GroupedCommitmentDocumentationSource, headingLevelShift?: number): string;
 export {};

package/umd/src/book-2.0/book-language-documentation/toStableAnchorId.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a heading label into a stable markdown anchor id.
+ *
+ * Anchors are generated from language-neutral identifiers, so deep links into
+ * the manual keep working in every translation.
+ *
+ * @param value - Raw heading/identifier text.
+ * @returns Stable lowercase anchor id.
+ *
+ * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ */
+export declare function toStableAnchorId(value: string): string;

package/umd/src/book-3.0/AgentMessageRunReport.d.ts

@@ -0,0 +1,78 @@
+import type { Usage } from '../execution/Usage';
+import type { CodexLoginMethod } from './codexLoginMethod';
+/**
+ * File suffix appended to one answered message book to store its run report sidecar.
+ *
+ * For example `messages/finished/2026-07-16-thread.book` is reported in
+ * `messages/finished/2026-07-16-thread.book.report.json`.
+ *
+ * @private internal constant of the agent folder convention
+ */
+export declare const AGENT_MESSAGE_RUN_REPORT_FILE_SUFFIX = ".report.json";
+/**
+ * Report describing how one queued agent message was answered by a CLI harness runner.
+ *
+ * The agent runner writes it next to the answered message book so consumers
+ * (for example the Agents Server task details) can show which runner, authentication
+ * method and usage one answer cost without re-parsing the runner output.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent folder convention
+ */
+export type AgentMessageRunReport = {
+    /**
+     * Report schema version for forward compatibility.
+     */
+    readonly version: 1;
+    /**
+     * Name of the harness runner which answered the message, for example `codex` or `claude-code`.
+     */
+    readonly runnerName: string;
+    /**
+     * Model identifier used by the runner, when known.
+     */
+    readonly modelName?: string;
+    /**
+     * Authentication method the runner used, when it can be determined.
+     *
+     * Currently only the OpenAI Codex runner reports this (its ChatGPT account vs. `OPENAI_API_KEY`);
+     * other runners leave it `undefined`.
+     */
+    readonly loginMethod?: CodexLoginMethod;
+    /**
+     * Usage statistics of the run (price, token counts, duration).
+     */
+    readonly usage: Usage;
+};
+/**
+ * Builds the run-report sidecar path for one message book path.
+ *
+ * Works for absolute and relative paths because the suffix is simply appended.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function buildAgentMessageRunReportPath(messageFilePath: string): string;
+/**
+ * Serializes one run report into the stable JSON format persisted next to the answered message book.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function serializeAgentMessageRunReport(report: AgentMessageRunReport): string;
+/**
+ * Validates one already-parsed JSON value as a run report.
+ *
+ * @returns The typed report, or `null` when the value does not match the expected shape,
+ * so consumers can silently skip malformed or foreign sidecar files.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function normalizeAgentMessageRunReport(value: unknown): AgentMessageRunReport | null;
+/**
+ * Parses one run-report sidecar file content.
+ *
+ * @returns The typed report, or `null` when the content is not valid JSON or does not match the expected shape.
+ *
+ * @private internal utility of the agent folder convention
+ */
+export declare function parseAgentMessageRunReport(reportFileContent: string): AgentMessageRunReport | null;

package/umd/src/book-3.0/AgentMessageRunReport.test.d.ts

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

package/umd/src/book-3.0/agentFolderPaths.d.ts

@@ -28,3 +28,12 @@ export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
  * @public exported from `@promptbook/node`
  */
 export declare const AGENT_FAILED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to the agent-owned projects root used by the agent folder convention.
+ *
+ * Each direct child directory is one project — an isolated folder the agent fully controls
+ * (files, scripts, optionally its own git repository).
+ *
+ * @private internal constant of the agent folder convention, used by agent runners and the Agents Server
+ */
+export declare const AGENT_PROJECTS_DIRECTORY_PATH = "projects";