@promptbook/types 0.114.0-3 → 0.114.0-30

package/README.md

@@ -340,8 +340,6 @@ Respond to incoming legal inquiries via email and keep the company website updat
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
 <br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
 <br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
@@ -430,7 +428,7 @@ GOAL Keep the company website updated with the latest legal policies and complia
 
 #### `Use` commitments
 
-Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE EMAIL` lets the agent send emails, `USE BROWSER` lets it access and read web content, `USE SEARCH ENGINE` lets it search the web, and many more.
+Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE CALENDAR` lets the agent work with a calendar, `USE PROJECT` gives it access to a code repository, `USE MCP` connects any external Model Context Protocol server, and many more.
 
 These are what turn a chatbot into a persistent agent that actually does work.
 
@@ -447,9 +445,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 
 </td></tr></table>
 
@@ -470,9 +465,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
@@ -659,7 +651,7 @@ Or you can install them separately:
 
 Promptbook Coder is **not another standalone coding model**. It is an orchestration layer over coding agents such as **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, **Opencode**, **Cline**, and **Gemini CLI**. The difference is that Promptbook Coder adds a repeatable repository workflow on top of them:
 
--   prompt files with explicit statuses like `[ ]`, `[x]`, and `[-]`
+-   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
 -   optional shared repo context loaded from a file such as `AGENTS.md`
 -   automatic `git add`, commit, and push after each successful prompt
@@ -674,19 +666,19 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.promptbook`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
 2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
 3. You replace placeholder `@@@` sections with real coding tasks.
-4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent.
+4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent and immediately marks it as in progress `[^]`, naming the harness, the model and the step which is running.
 5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
 6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
 
-Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority.
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind, and `--git-changes continue` resumes exactly that prompt with its uncommitted changes still in place.
 
 #### Features
 
--   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
+-   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`, `qwen-code`
 -   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
 -   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
--   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
+-   **Git safety:** clean working tree check by default, or `--git-changes ignore` to keep the changes and `--git-changes continue` to resume an interrupted prompt
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
 -   **Failure logging:** failed runs write a neighboring `.error.log`
@@ -707,7 +699,7 @@ npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gp
 
 npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --git-changes ignore
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -733,7 +725,7 @@ ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh -
 
 ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --git-changes ignore
 
 ptbk coder find-refactor-candidates
 
@@ -759,13 +751,13 @@ ptbk coder verify
 | Flag                       | Purpose                                                                                                                                                                                |
 | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--harness <name>`         | Selects the coding harness.                                                                                                                                                            |
-| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`.                                                                                     |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex`, `gemini` and `qwen-code`, optional for `github-copilot`.                                                                        |
 | `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                                                                                                     |
 | `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                       |
 | `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
 | `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
-| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                                                                                                                 |
+| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                 |
 | `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
 | `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
 | `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |

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

@@ -70,8 +70,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 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 { MarkdownInlineReferenceIcon } 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 { MarkdownInlineReferenceMenuAction } 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';
@@ -159,8 +161,10 @@ export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };

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

@@ -62,8 +62,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 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 { MarkdownInlineReferenceIcon } 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 { MarkdownInlineReferenceMenuAction } 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';
@@ -511,8 +513,10 @@ export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };

package/esm/src/avatars/renderAvatarVisualTerminalText.d.ts

@@ -0,0 +1,80 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId, AvatarVisualTerminalTextGrid } from './types/AvatarVisualDefinition';
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Surface used to derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextGrid(options: RenderAvatarVisualTerminalTextOptions): AvatarVisualTerminalTextGrid | null;
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextLines(options: RenderAvatarVisualTerminalTextLinesOptions): ReadonlyArray<string> | null;

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -72,6 +72,52 @@ export type AvatarVisualRenderContext = {
  * @private shared contract for the avatar rendering system
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -84,6 +130,14 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 /**
  * Props of the shared `<Avatar/>` component.

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

@@ -31,13 +31,13 @@ export type BookParameter = {
 };
 /**
  * Capability of the agent
- * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+ * This is parsed from commitments like USE CALENDAR, USE PROJECT, KNOWLEDGE, etc.
  */
 export type AgentCapability = {
     /**
      * The type of the capability
      */
-    type: 'browser' | 'search-engine' | 'knowledge' | 'timeout' | 'time' | 'user-location' | 'inheritance' | 'import' | 'image-generator' | 'team' | 'email' | 'popup' | 'privacy' | 'project' | 'calendar' | 'wallet';
+    type: 'knowledge' | 'user-location' | 'inheritance' | 'import' | 'image-generator' | 'team' | 'popup' | 'privacy' | 'project' | 'calendar';
     /**
      * The label to display for this capability
      */
@@ -122,7 +122,7 @@ export type AgentBasicInformation = {
     parameters: Array<BookParameter>;
     /**
      * Capabilities of the agent
-     * This is parsed from commitments like USE BROWSER, USE SEARCH ENGINE, KNOWLEDGE, etc.
+     * This is parsed from commitments like USE CALENDAR, USE PROJECT, KNOWLEDGE, etc.
      */
     capabilities: Array<AgentCapability>;
     /**

package/esm/src/book-2.0/agent-source/AgentSourceParseResult.d.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
  *
@@ -18,6 +19,10 @@ export type AgentSourceParseResult = {
      * All parsed commitments
      */
     commitments: ParsedCommitment[];
+    /**
+     * Uppercase commitment blocks whose types are not registered by Promptbook.
+     */
+    unknownCommitments: ParsedUnknownCommitment[];
     /**
      * Lines that are not commitments (for system message)
      */

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

@@ -0,0 +1,26 @@
+/**
+ * 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/esm/src/book-2.0/agent-source/getBookCommitmentLineType.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function createBookCommitmentLineTypeRegex(): RegExp;
+/**
+ * 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 declare function getBookCommitmentLineType(line: string): string | null;

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

@@ -1,4 +1,6 @@
 import type { Usage } from '../execution/Usage';
+import type { AgentMessageProjectChange } from '../utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
 import type { CodexLoginMethod } from './codexLoginMethod';
 /**
  * File suffix appended to one answered message book to store its run report sidecar.
@@ -9,6 +11,23 @@ import type { CodexLoginMethod } from './codexLoginMethod';
  * @private internal constant of the agent folder convention
  */
 export declare 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.
  *
@@ -44,6 +63,33 @@ 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>;
 };
 /**
  * Builds the run-report sidecar path for one message book path.

package/esm/src/book-3.0/AgentPlannedMessagesSidecar.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Relative directory holding the planned-message sidecar of each queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Command actions an agent can request from its planned-message sidecar.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS: readonly ["set", "update", "cancel"];
+/**
+ * One planned-message command action.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageCommandAction = (typeof AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS)[number];
+/**
+ * One planned message that is already waiting to wake the agent.
+ *
+ * A planned message can repeat like `setInterval`, run a bounded number of times, or wake the agent
+ * only once, so the whole schedule is what the agent compares with its goal, while `dueAt` only says
+ * when the nearest wake-up happens.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageSnapshot = {
+    readonly timeoutId: string;
+    readonly dueAt: string;
+    readonly message: string | null;
+    /**
+     * Repeat interval in milliseconds, or `null` for a planned message that does not repeat at a fixed
+     * interval.
+     */
+    readonly intervalMs: number | null;
+    /**
+     * Five-field cron expression driving the repetitions, or `null` when the planned message does not
+     * follow a cron.
+     */
+    readonly cronExpression: string | null;
+    /**
+     * Moment before which the planned message never wakes the agent, or `null` when it has no starting
+     * date.
+     */
+    readonly startsAt: string | null;
+    /**
+     * Moment after which the planned message never wakes the agent again, or `null` when it has no
+     * ending date.
+     */
+    readonly endsAt: string | null;
+    /**
+     * Total number of wake-ups the planned message performs, or `null` when it repeats until it is
+     * cancelled.
+     */
+    readonly maxRunCount: number | null;
+    /**
+     * Number of times the planned message already woke the agent.
+     */
+    readonly runCount: number;
+};
+/**
+ * One command written by the coding harness into its planned-message sidecar.
+ *
+ * The payload stays untyped on purpose: it is untrusted harness output and is validated by the very
+ * same shared planned-message actions that back the model tools and the internal runtime API.
+ *
+ * For a `set` command, `milliseconds` is the repeat interval of the planned message, not a one-shot
+ * delay, and `cronExpression`, `startsAt`, `endsAt`, and `maxRunCount` bound how it repeats. An
+ * `update` command changes the very same fields of the planned message named by `timeoutId`, where a
+ * field that is left out stays as it is and an explicit `null` removes the bound.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageCommand = {
+    readonly action: AgentPlannedMessageCommandAction;
+    readonly milliseconds?: unknown;
+    readonly cronExpression?: unknown;
+    readonly startsAt?: unknown;
+    readonly endsAt?: unknown;
+    readonly maxRunCount?: unknown;
+    readonly message?: unknown;
+    readonly timeoutId?: unknown;
+};
+/**
+ * Planned-message sidecar prepared for one queued message.
+ *
+ * `currentPlannedMessages` is written by the Agents Server and is read-only for the agent, while
+ * `commands` is the only channel through which a coding harness can plan or cancel a wake-up.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessagesSidecar = {
+    readonly version: 1;
+    readonly agentPermanentId: string;
+    readonly currentPlannedMessages: ReadonlyArray<AgentPlannedMessageSnapshot>;
+    readonly commands: ReadonlyArray<AgentPlannedMessageCommand>;
+};
+/**
+ * Creates the relative planned-message sidecar path of one queued message.
+ *
+ * @param messageFileName - File name of the queued `.book` message.
+ * @returns Relative path of the sidecar inside the agent folder.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentPlannedMessagesSidecarPath(messageFileName: string): string;
+/**
+ * Serializes one planned-message sidecar into its stored representation.
+ *
+ * @param sidecar - Sidecar prepared for one queued message.
+ * @returns Pretty-printed JSON the coding harness can edit by hand.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentPlannedMessagesSidecarContent(sidecar: AgentPlannedMessagesSidecar): string;
+/**
+ * Parses one untrusted planned-message sidecar written back by a coding harness.
+ *
+ * A malformed sidecar never fails the already answered chat, so this returns `null` instead of throwing.
+ *
+ * @param sidecarContent - Raw file content read from the agent folder.
+ * @returns Normalized sidecar, or `null` when it cannot be used.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function parseAgentPlannedMessagesSidecar(sidecarContent: string): AgentPlannedMessagesSidecar | null;