@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -44,7 +44,7 @@ export const DEFAULT_BOOK = padBook(
         spaceTrim(`
             AI Avatar
 
-            PERSONA A friendly AI assistant that helps you with your tasks
+            GOAL Help users with their tasks as a friendly AI assistant.
         `),
     ),
 );

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

@@ -80,6 +80,7 @@ const BEHAVIOR_COMMITMENT_TYPES = new Set([
     'LANGUAGES',
     'WRITING SAMPLE',
     'WRITING RULES',
+    'WRITING RULE',
     'SCENARIO',
     'SCENARIOS',
     'MESSAGE',
@@ -280,9 +281,7 @@ export function createStandaloneBookLanguageMarkdown(
             ${block(dictionary.tutorialSections.checklistBody)}
 
             ${block(
-                isLowLevelCommitmentsIncluded
-                    ? renderLowLevelCommitmentsChapter(lowLevelCommitments, dictionary)
-                    : '',
+                isLowLevelCommitmentsIncluded ? renderLowLevelCommitmentsChapter(lowLevelCommitments, dictionary) : '',
             )}
 
             ---
@@ -596,7 +595,9 @@ function renderExampleSection(
             **${dictionary.exampleLabels.goal}:** ${exampleText.goal}
 
             **${dictionary.exampleLabels.commitmentsUsed}:** ${renderCommitmentSectionLinks(
-            parseAgentSourceWithCommitments(example.source as string_book).commitments.map((commitment) => commitment.type),
+            parseAgentSourceWithCommitments(example.source as string_book).commitments.map(
+                (commitment) => commitment.type,
+            ),
             commitmentSectionAnchorByType,
         )}
 

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

@@ -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.
             `),
         },

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

@@ -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.
             `),
         },

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

@@ -5,7 +5,7 @@
  * @param language - Optional info-string language label.
  * @returns Fenced code block.
  *
- * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
  */
 export function getSafeCodeBlock(content: string, language = 'markdown'): string {
     const maxBacktickCount = Math.max(0, ...(content.match(/`+/g) || []).map((match) => match.length));

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.
  *

package/src/book-3.0/AgentPlannedMessagesSidecar.ts

@@ -0,0 +1,284 @@
+import { join } from 'path';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from './agentFolderPaths';
+import { createAgentMessageSidecarBaseName } from './createAgentMessageSidecarBaseName';
+
+// Note: [💞] This file defines the shared planned-message sidecar convention rather than one standalone entity.
+
+/**
+ * Relative directory holding the planned-message sidecar of each queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'planned');
+
+/**
+ * Command actions an agent can request from its planned-message sidecar.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'update', 'cancel'] as const;
+
+/**
+ * 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 function createAgentPlannedMessagesSidecarPath(messageFileName: string): string {
+    return join(AGENT_PLANNED_MESSAGES_DIRECTORY_PATH, `${createAgentMessageSidecarBaseName(messageFileName)}.json`);
+}
+
+/**
+ * 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 function createAgentPlannedMessagesSidecarContent(sidecar: AgentPlannedMessagesSidecar): string {
+    return `${JSON.stringify(sidecar, null, 2)}\n`;
+}
+
+/**
+ * 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 function parseAgentPlannedMessagesSidecar(sidecarContent: string): AgentPlannedMessagesSidecar | null {
+    let parsedSidecar: unknown;
+
+    try {
+        parsedSidecar = JSON.parse(sidecarContent);
+    } catch {
+        return null;
+    }
+
+    if (!parsedSidecar || typeof parsedSidecar !== 'object' || Array.isArray(parsedSidecar)) {
+        return null;
+    }
+
+    const sidecar = parsedSidecar as Partial<AgentPlannedMessagesSidecar>;
+
+    if (sidecar.version !== 1 || typeof sidecar.agentPermanentId !== 'string') {
+        return null;
+    }
+
+    return {
+        version: 1,
+        agentPermanentId: sidecar.agentPermanentId,
+        currentPlannedMessages: normalizeAgentPlannedMessageSnapshots(sidecar.currentPlannedMessages),
+        commands: normalizeAgentPlannedMessageCommands(sidecar.commands),
+    };
+}
+
+/**
+ * Keeps only the commands whose action is understood by the planned-message actions.
+ *
+ * @param rawCommands - Untrusted `commands` value read from one sidecar.
+ * @returns Commands that can be dispatched, in their original order.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessageCommands(rawCommands: unknown): Array<AgentPlannedMessageCommand> {
+    if (!Array.isArray(rawCommands)) {
+        return [];
+    }
+
+    return rawCommands.filter(isAgentPlannedMessageCommand);
+}
+
+/**
+ * Checks whether one untrusted sidecar entry names a supported planned-message action.
+ *
+ * @param value - Untrusted command entry.
+ * @returns `true` when the entry can be dispatched.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function isAgentPlannedMessageCommand(value: unknown): value is AgentPlannedMessageCommand {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+
+    const action = (value as AgentPlannedMessageCommand).action;
+
+    return (
+        typeof action === 'string' &&
+        AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS.includes(action as AgentPlannedMessageCommandAction)
+    );
+}
+
+/**
+ * Keeps only the already planned messages that can be shown to the agent.
+ *
+ * @param rawSnapshots - Untrusted `currentPlannedMessages` value read from one sidecar.
+ * @returns Planned-message snapshots with the fields required for display and cancellation.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessageSnapshots(rawSnapshots: unknown): Array<AgentPlannedMessageSnapshot> {
+    if (!Array.isArray(rawSnapshots)) {
+        return [];
+    }
+
+    return rawSnapshots.filter(isAgentPlannedMessageSnapshot).map(createNormalizedAgentPlannedMessageSnapshot);
+}
+
+/**
+ * Normalizes the optional fields of one already planned message.
+ *
+ * @param snapshot - Planned-message entry with the required identity fields.
+ * @returns Snapshot with a usable schedule and message.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function createNormalizedAgentPlannedMessageSnapshot(
+    snapshot: AgentPlannedMessageSnapshot,
+): AgentPlannedMessageSnapshot {
+    return {
+        timeoutId: snapshot.timeoutId,
+        dueAt: snapshot.dueAt,
+        message: typeof snapshot.message === 'string' ? snapshot.message : null,
+        intervalMs: normalizeAgentPlannedMessagePositiveCount(snapshot.intervalMs),
+        cronExpression: typeof snapshot.cronExpression === 'string' ? snapshot.cronExpression : null,
+        startsAt: typeof snapshot.startsAt === 'string' ? snapshot.startsAt : null,
+        endsAt: typeof snapshot.endsAt === 'string' ? snapshot.endsAt : null,
+        maxRunCount: normalizeAgentPlannedMessagePositiveCount(snapshot.maxRunCount),
+        runCount: normalizeAgentPlannedMessagePositiveCount(snapshot.runCount) || 0,
+    };
+}
+
+/**
+ * Normalizes one optional positive whole number of a planned-message snapshot.
+ *
+ * @param value - Untrusted interval, run count, or run-count limit.
+ * @returns Whole positive number, or `null` when the value cannot be used.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessagePositiveCount(value: unknown): number | null {
+    const numericValue = Number(value);
+
+    return Number.isFinite(numericValue) && numericValue > 0 ? Math.floor(numericValue) : null;
+}
+
+/**
+ * Checks whether one untrusted sidecar entry describes an already planned message.
+ *
+ * @param value - Untrusted planned-message entry.
+ * @returns `true` when the entry can be shown and cancelled.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function isAgentPlannedMessageSnapshot(value: unknown): value is AgentPlannedMessageSnapshot {
+    return Boolean(
+        value &&
+            typeof value === 'object' &&
+            typeof (value as AgentPlannedMessageSnapshot).timeoutId === 'string' &&
+            typeof (value as AgentPlannedMessageSnapshot).dueAt === 'string',
+    );
+}