@promptbook/cli 0.114.0-12 → 0.114.0-13

package/apps/agents-server/src/utils/agentGoalChat/agentGoalChatPlannedMessageActions.ts

@@ -24,6 +24,14 @@ const MAX_LISTED_PLANNED_MESSAGES_LIMIT = 100;
  */
 const ACTIVE_PLANNED_MESSAGE_STATUSES: ReadonlyArray<UserChatTimeoutStatus> = ['QUEUED', 'RUNNING'];
 
+/**
+ * Shortest repeat interval one agent may plan for itself.
+ *
+ * Planned messages repeat like `setInterval`, so an interval below one minute would turn the goal
+ * chat into an unattended self-invocation loop instead of a plan.
+ */
+const MINIMUM_PLANNED_MESSAGE_INTERVAL_MS = 60_000;
+
 /**
  * Minimal goal-chat identity needed when scheduling a planned message.
  */
@@ -41,6 +49,11 @@ export type AgentGoalChatPlannedMessageItem = {
     readonly dueAt: string;
     readonly isPaused: boolean;
     readonly message: string | null;
+
+    /**
+     * Repeat interval in milliseconds, or `null` for a planned message that wakes the agent only once.
+     */
+    readonly intervalMs: number | null;
 };
 
 /**
@@ -52,6 +65,11 @@ export type SetAgentGoalChatPlannedMessageResult = {
     readonly timeoutId: string;
     readonly dueAt: string;
     readonly message: string | null;
+
+    /**
+     * Repeat interval in milliseconds of the scheduled planned message.
+     */
+    readonly intervalMs: number | null;
 };
 
 /**
@@ -76,8 +94,14 @@ export type CancelAgentGoalChatPlannedMessageResult = {
 
 /**
  * Shared operations used by both model tools and the coding-agent runtime API.
+ *
+ * Planned messages behave like `setInterval`: `set` starts a repeating wake-up and only `cancel`
+ * stops it, so an agent that is happy with its plan does not have to do anything.
  */
 export type AgentGoalChatPlannedMessageActions = {
+    /**
+     * Starts one repeating planned message, where `milliseconds` is its repeat interval.
+     */
     readonly set: (options: {
         readonly agentPermanentId: string;
         readonly milliseconds: unknown;
@@ -133,14 +157,16 @@ export function createAgentGoalChatPlannedMessageActions(
     return {
         async set(options): Promise<SetAgentGoalChatPlannedMessageResult> {
             const agentPermanentId = parseRequiredText(options.agentPermanentId, 'agentPermanentId');
-            const milliseconds = parsePositiveMilliseconds(options.milliseconds);
+            const intervalMs = parsePlannedMessageIntervalMs(options.milliseconds);
             const message = parseRequiredText(options.message, 'message');
             const goalChat = await dependencies.ensureAgentGoalChat(agentPermanentId);
+            // Note: A planned message repeats like `setInterval`, so the requested delay is also its interval
             const plannedMessage = await dependencies.scheduleThreadScopedUserChatTimeout({
                 userId: goalChat.userId,
                 agentPermanentId,
                 chatId: goalChat.id,
-                durationMs: milliseconds,
+                durationMs: intervalMs,
+                recurrenceIntervalMs: intervalMs,
                 message,
             });
 
@@ -150,6 +176,7 @@ export function createAgentGoalChatPlannedMessageActions(
                 timeoutId: plannedMessage.timeoutId,
                 dueAt: plannedMessage.dueAt,
                 message: plannedMessage.message,
+                intervalMs: plannedMessage.recurrenceIntervalMs,
             };
         },
 
@@ -209,20 +236,21 @@ export function createAgentGoalChatPlannedMessageActions(
 export const AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS = createAgentGoalChatPlannedMessageActions();
 
 /**
- * Parses one positive timeout duration.
+ * Parses one planned-message repeat interval.
  *
- * @param rawMilliseconds - Untrusted duration supplied by a model or runtime API.
- * @returns Positive whole milliseconds.
+ * @param rawMilliseconds - Untrusted interval supplied by a model or runtime API.
+ * @returns Repeat interval in whole milliseconds.
  */
-function parsePositiveMilliseconds(rawMilliseconds: unknown): number {
+function parsePlannedMessageIntervalMs(rawMilliseconds: unknown): number {
     const milliseconds = Number(rawMilliseconds);
 
-    if (!Number.isFinite(milliseconds) || milliseconds < 1) {
+    if (!Number.isFinite(milliseconds) || milliseconds < MINIMUM_PLANNED_MESSAGE_INTERVAL_MS) {
         throw new ParseError(
             spaceTrim(`
-                Invalid planned-message delay.
+                Invalid planned-message interval.
 
-                - \`milliseconds\` must be a positive number of at least \`1\`.
+                - A planned message **repeats** at this interval until it is cancelled.
+                - \`milliseconds\` must be a number of at least \`${MINIMUM_PLANNED_MESSAGE_INTERVAL_MS}\`.
             `),
         );
     }
@@ -289,6 +317,7 @@ function createPlannedMessageListItem(plannedMessage: UserChatTimeoutRecord): Ag
         dueAt: plannedMessage.dueAt,
         isPaused: Boolean(plannedMessage.pausedAt),
         message: plannedMessage.message,
+        intervalMs: plannedMessage.recurrenceIntervalMs,
     };
 }
 

package/apps/agents-server/src/utils/agentGoalChat/createAgentGoalChatNoteContent.ts

@@ -1,4 +1,5 @@
 import { spaceTrim } from 'spacetrim';
+import { formatTimeoutDurationHuman } from '../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
 
 /**
  * Lifecycle events of an agent that are recorded in its goal chat.
@@ -35,8 +36,8 @@ export function createAgentGoalChatLifecycleNoteContent(options: {
                 ${block(goalSection)}
 
                 This is my own thread for acting towards that goal. I should work on it now when useful,
-                inspect existing planned messages with \`list_timeouts\`, and use \`set_timeout\` or
-                \`cancel_timeout\` to arrange the next useful wake-up without creating duplicates.
+                review the planned messages I already have, and plan a repeating wake-up with the
+                planned-message capability of my invocation when my goal needs one that is not planned yet.
             `,
         );
     }
@@ -47,8 +48,10 @@ export function createAgentGoalChatLifecycleNoteContent(options: {
 
             ${block(goalSection)}
 
-            I should re-check my work and planned messages against this new goal, act on it now when useful,
-            and arrange another goal-chat wake-up with \`set_timeout\` when future follow-up is needed.
+            I should re-check my work and planned messages against this new goal and act on it now when useful.
+            My planned messages keep repeating on their own, so I keep the ones that still match this goal,
+            and cancel and re-plan only the ones that do not — announcing a wake-up without planning it
+            changes nothing.
         `,
     );
 }
@@ -56,19 +59,25 @@ export function createAgentGoalChatLifecycleNoteContent(options: {
 /**
  * Builds the goal-chat note left when a planned message is scheduled.
  *
- * @param options - Planned-message identity, due time, and optional payload message.
+ * @param options - Planned-message identity, repeat interval, due time, and optional payload message.
  * @returns Note content stored as one agent message.
  */
 export function createAgentGoalChatPlannedMessageNoteContent(options: {
     readonly timeoutId: string;
     readonly dueAt: string;
+    readonly intervalMs?: number | null;
     readonly message?: string | null;
 }): string {
     const plannedMessage = options.message?.trim() || '';
+    const headline = options.intervalMs
+        ? `⏳ I planned a message that will wake me up every ${formatTimeoutDurationHuman(
+              options.intervalMs,
+          )}, for the first time at ${options.dueAt}.`
+        : `⏳ I planned a message that will wake me up at ${options.dueAt}.`;
 
     return spaceTrim(
         (block) => `
-            ⏳ I planned a message that will wake me up at ${options.dueAt}.
+            ${headline}
 
             ${plannedMessage ? block(plannedMessage) : ''}
 

package/apps/agents-server/src/utils/agentProjects/listAgentProjectNames.ts

@@ -0,0 +1,35 @@
+import { readdir } from 'fs/promises';
+import { resolveAgentProjectsRootPath } from './agentProjectsPaths';
+import { isMissingPathError } from './isMissingPathError';
+
+/**
+ * Lists the directory names of all projects of one agent.
+ *
+ * This is the cheap half of `listAgentProjects` — it reads the `projects/` folder itself and never walks
+ * the project trees, so it can answer "did the set of projects change?" without measuring every project.
+ *
+ * A missing projects folder is reported as an empty list — the folder is created lazily
+ * when the agent (or the runner) first needs it.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns Project directory names ordered by name.
+ */
+export async function listAgentProjectNames(agentPermanentId: string): Promise<ReadonlyArray<string>> {
+    const projectsRootPath = resolveAgentProjectsRootPath(agentPermanentId);
+
+    let projectsRootEntries;
+    try {
+        projectsRootEntries = await readdir(projectsRootPath, { withFileTypes: true });
+    } catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+
+        throw error;
+    }
+
+    return projectsRootEntries
+        .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
+        .map((projectDirectoryEntry) => projectDirectoryEntry.name)
+        .sort((firstProjectName, secondProjectName) => firstProjectName.localeCompare(secondProjectName));
+}

package/apps/agents-server/src/utils/agentProjects/listAgentProjects.ts

@@ -1,7 +1,6 @@
-import { readdir } from 'fs/promises';
 import type { AgentProjectInfo } from './AgentProjectInfo';
 import { resolveAgentProjectsRootPath } from './agentProjectsPaths';
-import { isMissingPathError } from './isMissingPathError';
+import { listAgentProjectNames } from './listAgentProjectNames';
 import { createAgentProjectInfo } from './resolveAgentProjectInfo';
 
 /**
@@ -15,27 +14,11 @@ import { createAgentProjectInfo } from './resolveAgentProjectInfo';
  */
 export async function listAgentProjects(agentPermanentId: string): Promise<ReadonlyArray<AgentProjectInfo>> {
     const projectsRootPath = resolveAgentProjectsRootPath(agentPermanentId);
+    const projectNames = await listAgentProjectNames(agentPermanentId);
 
-    let projectsRootEntries;
-    try {
-        projectsRootEntries = await readdir(projectsRootPath, { withFileTypes: true });
-    } catch (error) {
-        if (isMissingPathError(error)) {
-            return [];
-        }
-
-        throw error;
-    }
-
-    const projects = await Promise.all(
-        projectsRootEntries
-            .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
-            .map((projectDirectoryEntry): Promise<AgentProjectInfo> =>
-                createAgentProjectInfo(projectsRootPath, projectDirectoryEntry.name),
-            ),
-    );
-
-    return projects.sort((firstProject, secondProject) =>
-        firstProject.projectName.localeCompare(secondProject.projectName),
+    return await Promise.all(
+        projectNames.map(
+            (projectName): Promise<AgentProjectInfo> => createAgentProjectInfo(projectsRootPath, projectName),
+        ),
     );
 }

package/apps/agents-server/src/utils/agentProjects/resolveAgentChatProjectReferences.ts

@@ -0,0 +1,25 @@
+import { resolveAgentProjectsAccess, type AgentProjectsAccessResolution } from './agentProjectAccess';
+import type { AgentProjectReferenceInfo } from './AgentProjectReferenceInfo';
+import { listAgentProjectChatReferences } from './listAgentProjectChatReferences';
+
+/**
+ * Resolves the compact project references one chat surface may render as project chips.
+ *
+ * Every surface showing a chat — the agent profile, the chat page, and the action refreshing an open
+ * chat — gates the projects behind the same overview permission, so the decision lives here only.
+ *
+ * @param options - Owning agent and its already resolved project access, when the caller has it.
+ * @returns Display-only project references safe to send to the browser.
+ */
+export async function resolveAgentChatProjectReferences(options: {
+    readonly agentPermanentId: string;
+    readonly projectsAccess?: AgentProjectsAccessResolution;
+}): Promise<ReadonlyArray<AgentProjectReferenceInfo>> {
+    const projectsAccess = options.projectsAccess || (await resolveAgentProjectsAccess(options.agentPermanentId));
+
+    if (!projectsAccess.isProjectOverviewVisible) {
+        return [];
+    }
+
+    return await listAgentProjectChatReferences(options.agentPermanentId);
+}

package/apps/agents-server/src/utils/chatMessageChips/createAnsweredMessageChipToolCalls.ts

@@ -0,0 +1,37 @@
+import type { ToolCall } from '@promptbook-local/types';
+import type { AppliedAgentPlannedMessageCommand } from '../localChatRunner/applyLocalAgentPlannedMessageCommands';
+import { createPlannedMessageChipToolCalls } from './createPlannedMessageChipToolCalls';
+import { createTouchedProjectChipToolCalls } from './createTouchedProjectChipToolCalls';
+
+/**
+ * Creates every extra chip shown below one answered chat message.
+ *
+ * This is the single place deciding what an answer shows besides its text: the wake-ups it
+ * planned and the projects it worked with. The chips travel as tool calls of the assistant
+ * message, so they are visible in every chat view — including external chats such as email,
+ * whose outbound reply is rendered from the message text alone and therefore stays unchanged.
+ *
+ * @param options - Owning agent plus what the answered message planned and touched.
+ * @returns Tool calls rendered as chips below the answer, in a stable order.
+ */
+export async function createAnsweredMessageChipToolCalls(options: {
+    readonly agentPermanentId: string;
+    readonly appliedPlannedMessageCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly createdAt?: NonNullable<ToolCall['createdAt']>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    const createdAt = options.createdAt || (new Date().toISOString() as NonNullable<ToolCall['createdAt']>);
+    const projectChipToolCalls = await createTouchedProjectChipToolCalls({
+        agentPermanentId: options.agentPermanentId,
+        touchedProjectNames: options.touchedProjectNames,
+        createdAt,
+    });
+
+    return [
+        ...projectChipToolCalls,
+        ...createPlannedMessageChipToolCalls({
+            appliedCommands: options.appliedPlannedMessageCommands,
+            createdAt,
+        }),
+    ];
+}

package/apps/agents-server/src/utils/chatMessageChips/createPlannedMessageChipToolCalls.ts

@@ -0,0 +1,39 @@
+import type { ToolCall } from '@promptbook-local/types';
+import {
+    CANCEL_TIMEOUT_TOOL_CALL_NAME,
+    SET_TIMEOUT_TOOL_CALL_NAME,
+} from '../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+import type { AppliedAgentPlannedMessageCommand } from '../localChatRunner/applyLocalAgentPlannedMessageCommands';
+
+/**
+ * Prefix of the idempotency keys identifying planned-message chips.
+ */
+const PLANNED_MESSAGE_CHIP_IDEMPOTENCY_PREFIX = 'planned-message';
+
+/**
+ * Creates the timeout chips of the message that planned or cancelled a wake-up.
+ *
+ * The chat already renders `set_timeout` and `cancel_timeout` tool calls as timeout chips with a
+ * detail popup, so one planned message becomes exactly one such tool call instead of a second
+ * timeout presentation.
+ *
+ * @param options - Planned-message commands applied for one answered message.
+ * @returns Timeout tool calls shown as chips below the answer.
+ */
+export function createPlannedMessageChipToolCalls(options: {
+    readonly appliedCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): ReadonlyArray<ToolCall> {
+    return options.appliedCommands.map(({ command, result }) => ({
+        name: result.action === 'set' ? SET_TIMEOUT_TOOL_CALL_NAME : CANCEL_TIMEOUT_TOOL_CALL_NAME,
+        arguments: {
+            ...(command.milliseconds === undefined ? {} : { milliseconds: command.milliseconds }),
+            ...(command.message === undefined ? {} : { message: command.message }),
+            ...(command.timeoutId === undefined ? {} : { timeoutId: command.timeoutId }),
+        },
+        result,
+        state: 'COMPLETE',
+        idempotencyKey: `${PLANNED_MESSAGE_CHIP_IDEMPOTENCY_PREFIX}-${result.action}-${result.timeoutId}`,
+        createdAt: options.createdAt,
+    }));
+}

package/apps/agents-server/src/utils/chatMessageChips/createTouchedProjectChipToolCalls.ts

@@ -0,0 +1,75 @@
+import type { ToolCall } from '@promptbook-local/types';
+import { AGENT_PROJECT_TOOL_CALL_NAME } from '../../../../../src/book-components/Chat/utils/agentProjectToolCall';
+import { buildAgentProjectProfileHref } from '../agentProjects/agentProjectHrefs';
+import { isSafeAgentProjectPathSegment } from '../agentProjects/agentProjectsPaths';
+import { resolveAgentProjectInfo } from '../agentProjects/resolveAgentProjectInfo';
+
+/**
+ * Prefix of the idempotency keys identifying touched-project chips.
+ */
+const TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX = 'agent-project';
+
+/**
+ * Creates the project chips of one answered message.
+ *
+ * A project is reported by the runner once the answering harness viewed or edited any of its
+ * files, and it is resolved here so the chip carries the same human-readable project name and
+ * link as every other project surface. Projects that no longer exist are skipped.
+ *
+ * @param options - Owning agent and the project directory names its answer touched.
+ * @returns Project tool calls shown as chips below the answer.
+ */
+export async function createTouchedProjectChipToolCalls(options: {
+    readonly agentPermanentId: string;
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    const projectChipToolCalls = await Promise.all(
+        options.touchedProjectNames
+            .filter((touchedProjectName) => isSafeAgentProjectPathSegment(touchedProjectName))
+            .map((touchedProjectName) =>
+                createTouchedProjectChipToolCall({
+                    agentPermanentId: options.agentPermanentId,
+                    projectName: touchedProjectName,
+                    createdAt: options.createdAt,
+                }),
+            ),
+    );
+
+    return projectChipToolCalls.filter((projectChipToolCall): projectChipToolCall is ToolCall =>
+        Boolean(projectChipToolCall),
+    );
+}
+
+/**
+ * Creates the chip of one touched project.
+ *
+ * @param options - Owning agent and one touched project directory name.
+ * @returns Project tool call, or `null` when the project no longer exists.
+ *
+ * @private function of `createTouchedProjectChipToolCalls`
+ */
+async function createTouchedProjectChipToolCall(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): Promise<ToolCall | null> {
+    const project = await resolveAgentProjectInfo(options.agentPermanentId, options.projectName);
+
+    if (!project) {
+        return null;
+    }
+
+    return {
+        name: AGENT_PROJECT_TOOL_CALL_NAME,
+        arguments: { projectName: project.projectName },
+        result: {
+            projectName: project.projectName,
+            displayName: project.displayName,
+            projectHref: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
+        },
+        state: 'COMPLETE',
+        idempotencyKey: `${TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX}-${project.projectName.toLowerCase()}`,
+        createdAt: options.createdAt,
+    };
+}

package/apps/agents-server/src/utils/localChatRunner/applyLocalAgentPlannedMessageCommands.ts

@@ -0,0 +1,212 @@
+import { readFile, rm } from 'fs/promises';
+import { join } from 'path';
+import { serializeError } from '@promptbook-local/utils';
+import {
+    createAgentPlannedMessagesSidecarPath,
+    parseAgentPlannedMessagesSidecar,
+    type AgentPlannedMessageCommand,
+} from '../../../../../src/book-3.0/AgentPlannedMessagesSidecar';
+import {
+    AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS,
+    type CancelAgentGoalChatPlannedMessageResult,
+    type SetAgentGoalChatPlannedMessageResult,
+} from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * Planned-message operations used while applying one sidecar.
+ */
+export type LocalAgentPlannedMessageActions = Pick<typeof AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS, 'set' | 'cancel'>;
+
+/**
+ * One planned-message command that was applied together with its result.
+ *
+ * The command carries what the agent asked for (for example the requested delay) and the result
+ * carries what really happened, so the chat can show the wake-up below the message that planned it.
+ */
+export type AppliedAgentPlannedMessageCommand = {
+    readonly command: AgentPlannedMessageCommand;
+    readonly result: SetAgentGoalChatPlannedMessageResult | CancelAgentGoalChatPlannedMessageResult;
+};
+
+/**
+ * Applies every planned-message command a coding harness wrote while answering one message.
+ *
+ * The sidecar is consumed exactly once: it is removed afterwards so a replayed worker tick can never
+ * schedule the very same wake-up twice.
+ *
+ * @param options - Answered job, its agent folder path, and the local runner metadata of the message.
+ * @returns Planned-message commands that were applied successfully, in sidecar order.
+ */
+export async function applyLocalAgentPlannedMessageCommands(options: {
+    readonly job: Pick<UserChatJobRecord, 'id' | 'chatId' | 'agentPermanentId'>;
+    readonly agentDirectoryPath: string;
+    readonly metadata: LocalUserChatJobMetadata;
+    readonly actions?: LocalAgentPlannedMessageActions;
+}): Promise<ReadonlyArray<AppliedAgentPlannedMessageCommand>> {
+    const sidecarPath = resolveLocalAgentPlannedMessagesSidecarPath(options.agentDirectoryPath, options.metadata);
+    const sidecarContent = await readOptionalTextFile(sidecarPath);
+
+    await removeLocalAgentPlannedMessagesSidecar(options.agentDirectoryPath, options.metadata);
+
+    if (sidecarContent === null) {
+        return [];
+    }
+
+    const sidecar = parseAgentPlannedMessagesSidecar(sidecarContent);
+
+    if (!sidecar) {
+        console.warn('[local-chat-runner] planned_messages_sidecar_unreadable', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+        });
+        return [];
+    }
+
+    const actions = options.actions || AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS;
+    const appliedCommands: Array<AppliedAgentPlannedMessageCommand> = [];
+
+    for (const command of sidecar.commands) {
+        const result = await applyLocalAgentPlannedMessageCommand({
+            command,
+            actions,
+            agentPermanentId: options.job.agentPermanentId,
+            job: options.job,
+        });
+
+        if (result) {
+            appliedCommands.push({ command, result });
+        }
+    }
+
+    return appliedCommands;
+}
+
+/**
+ * Removes the planned-message sidecar of one queued message.
+ *
+ * @param agentDirectoryPath - Absolute path of the local agent folder.
+ * @param metadata - Local runner metadata of the queued message.
+ */
+export async function removeLocalAgentPlannedMessagesSidecar(
+    agentDirectoryPath: string,
+    metadata: LocalUserChatJobMetadata,
+): Promise<void> {
+    await rm(resolveLocalAgentPlannedMessagesSidecarPath(agentDirectoryPath, metadata), { force: true }).catch(
+        () => undefined,
+    );
+}
+
+/**
+ * Dispatches one planned-message command through the shared planned-message actions.
+ *
+ * One rejected command never blocks the remaining ones, because the agent already answered and the
+ * harness owns this sidecar.
+ *
+ * @param options - Command, actions, and the agent whose goal chat owns the planned message.
+ * @returns Result of the applied command, or `null` when it was rejected.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+async function applyLocalAgentPlannedMessageCommand(options: {
+    readonly command: AgentPlannedMessageCommand;
+    readonly actions: LocalAgentPlannedMessageActions;
+    readonly agentPermanentId: string;
+    readonly job: Pick<UserChatJobRecord, 'id' | 'chatId'>;
+}): Promise<AppliedAgentPlannedMessageCommand['result'] | null> {
+    try {
+        if (options.command.action === 'set') {
+            const plannedMessage = await options.actions.set({
+                agentPermanentId: options.agentPermanentId,
+                milliseconds: options.command.milliseconds,
+                message: options.command.message,
+            });
+
+            console.info('[local-chat-runner]', 'planned_message_set', {
+                chatId: options.job.chatId,
+                jobId: options.job.id,
+                timeoutId: plannedMessage.timeoutId,
+                dueAt: plannedMessage.dueAt,
+            });
+
+            return plannedMessage;
+        }
+
+        const cancelledPlannedMessage = await options.actions.cancel({
+            agentPermanentId: options.agentPermanentId,
+            timeoutId: options.command.timeoutId,
+        });
+
+        console.info('[local-chat-runner]', 'planned_message_cancel', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            timeoutId: cancelledPlannedMessage.timeoutId,
+            status: cancelledPlannedMessage.status,
+        });
+
+        return cancelledPlannedMessage.status === 'cancelled' ? cancelledPlannedMessage : null;
+    } catch (error) {
+        console.error('[local-chat-runner]', 'planned_message_command_failed', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            action: options.command.action,
+            error: serializeError(error as Error),
+        });
+
+        return null;
+    }
+}
+
+/**
+ * Resolves the absolute planned-message sidecar path of one queued message.
+ *
+ * @param agentDirectoryPath - Absolute path of the local agent folder.
+ * @param metadata - Local runner metadata of the queued message.
+ * @returns Absolute sidecar path.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function resolveLocalAgentPlannedMessagesSidecarPath(
+    agentDirectoryPath: string,
+    metadata: LocalUserChatJobMetadata,
+): string {
+    return join(agentDirectoryPath, createAgentPlannedMessagesSidecarPath(metadata.fileName));
+}
+
+/**
+ * Reads one text file and treats a missing planned-message sidecar as absent.
+ *
+ * @param path - Absolute sidecar path.
+ * @returns File content, or `null` when the sidecar does not exist.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+async function readOptionalTextFile(path: string): Promise<string | null> {
+    try {
+        return await readFile(path, 'utf-8');
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Returns true when one filesystem error indicates a missing path.
+ *
+ * @param error - Caught filesystem failure.
+ * @returns `true` for missing-path errors.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function isFileNotFoundError(error: unknown): boolean {
+    return Boolean(
+        error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            ((error as { code?: string }).code === 'ENOENT' || (error as { code?: string }).code === 'ENOTDIR'),
+    );
+}