@promptbook/cli 0.114.0-2 → 0.114.0-21

package/apps/agents-server/src/utils/getAdminChatTasksResponse/getAdminChatTasks/adminChatTaskSqlQuery.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import type { AdminChatTaskSortField, AdminChatTaskSortOrder, AdminChatTaskView } from '../../chatTasksAdmin';
 import type { ParsedAdminChatTaskQuery } from '../parseAdminChatTaskQuery';
 
@@ -12,7 +13,7 @@ export function createAdminChatTaskBaseQuery(options: {
     userTable: string;
     agentTable: string;
 }): string {
-    return `
+    return spaceTrim(`
         SELECT
             job."id" AS "id",
             'CHAT_COMPLETION'::text AS "kind",
@@ -70,7 +71,7 @@ export function createAdminChatTaskBaseQuery(options: {
         FROM ${options.userChatTimeoutTable} timeout
         LEFT JOIN ${options.userTable} "user" ON "user"."id" = timeout."userId"
         LEFT JOIN ${options.agentTable} agent ON agent."permanentId" = timeout."agentPermanentId"
-    `;
+    `);
 }
 
 /**
@@ -85,19 +86,21 @@ export function createAdminChatTaskListQuery(options: { baseTaskQuery: string; q
     const listQueryParts = createAdminChatTaskListQueryParts(options.query);
 
     return {
-        sql: `
-            WITH tasks AS (
-                ${options.baseTaskQuery}
-            )
-            SELECT
-                task.*,
-                COUNT(*) OVER() AS "totalCount"
-            FROM tasks task
-            ${listQueryParts.whereClause}
-            ORDER BY ${createAdminChatTaskOrderBySql(options.query, 'task')}
-            LIMIT $${listQueryParts.limitPlaceholder}
-            OFFSET $${listQueryParts.offsetPlaceholder}
-        `,
+        sql: spaceTrim(
+            (block) => `
+                WITH tasks AS (
+                    ${block(options.baseTaskQuery)}
+                )
+                SELECT
+                    task.*,
+                    COUNT(*) OVER() AS "totalCount"
+                FROM tasks task
+                ${block(listQueryParts.whereClause)}
+                ORDER BY ${block(createAdminChatTaskOrderBySql(options.query, 'task'))}
+                LIMIT $${listQueryParts.limitPlaceholder}
+                OFFSET $${listQueryParts.offsetPlaceholder}
+            `,
+        ),
         values: listQueryParts.values,
     };
 }
@@ -108,23 +111,25 @@ export function createAdminChatTaskListQuery(options: { baseTaskQuery: string; q
  * @private function of `getAdminChatTasks`
  */
 export function createAdminChatTaskCountersQuery(options: { baseTaskQuery: string }): string {
-    return `
-        WITH tasks AS (
-            ${options.baseTaskQuery}
-        )
-        SELECT
-            COUNT(*) FILTER (WHERE "status" = 'RUNNING') AS "runningCount",
-            COUNT(*) FILTER (WHERE "status" = 'QUEUED') AS "queuedCount",
-            COUNT(*) FILTER (
-                WHERE "status" = 'FAILED'
-                  AND "finishedAt" >= CURRENT_TIMESTAMP - INTERVAL '24 hours'
-            ) AS "failedLast24hCount",
-            CASE
-                WHEN MIN("queuedAt") FILTER (WHERE "status" = 'QUEUED') IS NULL THEN NULL
-                ELSE EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - MIN("queuedAt") FILTER (WHERE "status" = 'QUEUED'))) * 1000
-            END AS "oldestQueuedAgeMs"
-        FROM tasks
-    `;
+    return spaceTrim(
+        (block) => `
+            WITH tasks AS (
+                ${block(options.baseTaskQuery)}
+            )
+            SELECT
+                COUNT(*) FILTER (WHERE "status" = 'RUNNING') AS "runningCount",
+                COUNT(*) FILTER (WHERE "status" = 'QUEUED') AS "queuedCount",
+                COUNT(*) FILTER (
+                    WHERE "status" = 'FAILED'
+                      AND "finishedAt" >= CURRENT_TIMESTAMP - INTERVAL '24 hours'
+                ) AS "failedLast24hCount",
+                CASE
+                    WHEN MIN("queuedAt") FILTER (WHERE "status" = 'QUEUED') IS NULL THEN NULL
+                    ELSE EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - MIN("queuedAt") FILTER (WHERE "status" = 'QUEUED'))) * 1000
+                END AS "oldestQueuedAgeMs"
+            FROM tasks
+        `,
+    );
 }
 
 /**
@@ -265,7 +270,7 @@ function createAdminChatTaskDefaultOrderBySql(view: AdminChatTaskView, alias: st
             return `${createAdminChatTaskTimelineExpressionSql(alias)} DESC NULLS LAST, ${alias}."updatedAt" DESC, ${alias}."createdAt" DESC, ${alias}."id" DESC`;
         case 'active':
         default:
-            return `
+            return spaceTrim(`
                 CASE
                     WHEN ${alias}."status" = 'RUNNING' THEN 0
                     WHEN ${alias}."status" = 'QUEUED' THEN 1
@@ -281,7 +286,7 @@ function createAdminChatTaskDefaultOrderBySql(view: AdminChatTaskView, alias: st
                 END DESC NULLS LAST,
                 ${alias}."updatedAt" DESC,
                 ${alias}."id" DESC
-            `;
+            `);
     }
 }
 
@@ -328,13 +333,13 @@ function createAdminChatTaskCustomOrderBySql(
  * @private function of `getAdminChatTasks`
  */
 function createAdminChatTaskTimelineExpressionSql(alias: string): string {
-    return `
+    return spaceTrim(`
         CASE
             WHEN ${alias}."status" = 'RUNNING' THEN COALESCE(${alias}."startedAt", ${alias}."createdAt")
             WHEN ${alias}."status" = 'QUEUED' THEN ${alias}."createdAt"
             ELSE COALESCE(${alias}."finishedAt", ${alias}."updatedAt", ${alias}."createdAt")
         END
-    `;
+    `);
 }
 
 /**

package/apps/agents-server/src/utils/getAdminChatTasksResponse/getAdminChatTasks/loadAdminChatTaskFallbackData.ts

@@ -1,6 +1,4 @@
-import { $getTableName } from '@/src/database/$getTableName';
-import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
-import type { AgentsServerDatabase } from '@/src/database/schema';
+import { loadAgentNamesByPermanentId, loadUsernamesByUserId } from '../../adminEntityLookups';
 import { provideUserChatJobTable } from '../../userChat/provideUserChatJobTable';
 import type { UserChatJobStatus } from '../../userChat/UserChatJobRecord';
 import { provideUserChatTimeoutTable } from '../../userChatTimeout/userChatTimeoutStore/provideUserChatTimeoutTable';
@@ -54,23 +52,6 @@ export type AdminChatTaskTimeoutRow = {
     status: UserChatJobStatus;
 };
 
-/**
- * Minimal user lookup row needed by the admin task-manager fallback.
- *
- * @private type of `getAdminChatTasks`
- */
-type AdminChatTaskUserLookupRow = Pick<AgentsServerDatabase['public']['Tables']['User']['Row'], 'id' | 'username'>;
-
-/**
- * Minimal agent lookup row needed by the admin task-manager fallback.
- *
- * @private type of `getAdminChatTasks`
- */
-type AdminChatTaskAgentLookupRow = Pick<
-    AgentsServerDatabase['public']['Tables']['Agent']['Row'],
-    'permanentId' | 'agentName'
->;
-
 /**
  * Raw admin task-manager rows and lookup maps loaded through the Supabase-shaped adapters used by SQLite mode.
  *
@@ -95,8 +76,8 @@ export async function loadAdminChatTaskFallbackData(): Promise<AdminChatTaskFall
         ...new Set([...jobRows, ...timeoutRows].map((task) => task.agentPermanentId).filter(Boolean)),
     ];
     const [usernamesById, agentNamesByPermanentId] = await Promise.all([
-        loadAdminChatTaskUsernames(allUserIds),
-        loadAdminChatTaskAgentNames(allAgentPermanentIds),
+        loadUsernamesByUserId(allUserIds),
+        loadAgentNamesByPermanentId(allAgentPermanentIds),
     ]);
 
     return { jobRows, timeoutRows, usernamesById, agentNamesByPermanentId };
@@ -137,58 +118,3 @@ async function loadAdminChatTaskTimeoutRows(): Promise<Array<AdminChatTaskTimeou
 
     return (data || []) as unknown as Array<AdminChatTaskTimeoutRow>;
 }
-
-/**
- * Loads usernames keyed by user id for admin task rendering and search.
- *
- * @private function of `getAdminChatTasks`
- */
-async function loadAdminChatTaskUsernames(userIds: ReadonlyArray<number>): Promise<Map<number, string>> {
-    if (userIds.length === 0) {
-        return new Map();
-    }
-
-    const supabase = $provideSupabaseForServer();
-    const userTable = await $getTableName('User');
-    const { data, error } = await supabase.from(userTable).select('id,username').in('id', [...new Set(userIds)]);
-
-    if (error) {
-        throw new Error(`Failed to load admin task-manager users: ${error.message}`);
-    }
-
-    return new Map(
-        ((data || []) as Array<AdminChatTaskUserLookupRow>).map((userRow) => [userRow.id, userRow.username] as const),
-    );
-}
-
-/**
- * Loads agent names keyed by permanent id for admin task rendering and search.
- *
- * @private function of `getAdminChatTasks`
- */
-async function loadAdminChatTaskAgentNames(
-    agentPermanentIds: ReadonlyArray<string>,
-): Promise<Map<string, string | null>> {
-    if (agentPermanentIds.length === 0) {
-        return new Map();
-    }
-
-    const supabase = $provideSupabaseForServer();
-    const agentTable = await $getTableName('Agent');
-    const { data, error } = await supabase
-        .from(agentTable)
-        .select('permanentId,agentName')
-        .in('permanentId', [...new Set(agentPermanentIds)]);
-
-    if (error) {
-        throw new Error(`Failed to load admin task-manager agents: ${error.message}`);
-    }
-
-    return new Map(
-        ((data || []) as Array<AdminChatTaskAgentLookupRow>)
-            .filter((agentRow): agentRow is AdminChatTaskAgentLookupRow & { permanentId: string } =>
-                Boolean(agentRow.permanentId),
-            )
-            .map((agentRow) => [agentRow.permanentId, agentRow.agentName] as const),
-    );
-}

package/apps/agents-server/src/utils/getAdminChatTasksResponse/getAdminChatTasks/mapAdminChatTaskFallbackRows.ts

@@ -1,3 +1,4 @@
+import { isAgentGoalChatId } from '../../agentGoalChat/agentGoalChatIdentity';
 import type { AdminChatTaskRecord } from '../../chatTasksAdmin';
 import { getUserChatJobRunReportFromParameters } from '../../userChat/userChatJobRunReport';
 import { resolveNullableSqlNumber } from './adminChatTaskSqlValues';
@@ -57,6 +58,7 @@ function mapAdminChatTaskJobRow(
         chatId: row.chatId,
         workerId: null,
         queueName: 'user-chat-jobs',
+        isAgentGoalTask: isAgentGoalChatId(row.chatId),
         runReport: getUserChatJobRunReportFromParameters(row.parameters),
     };
 }
@@ -97,5 +99,6 @@ function mapAdminChatTaskTimeoutRow(
         chatId: row.chatId,
         workerId: null,
         queueName: 'user-chat-timeouts',
+        isAgentGoalTask: isAgentGoalChatId(row.chatId),
     };
 }

package/apps/agents-server/src/utils/getAdminChatTasksResponse/getAdminChatTasks/mapAdminChatTaskSqlRows.ts

@@ -1,3 +1,4 @@
+import { isAgentGoalChatId } from '../../agentGoalChat/agentGoalChatIdentity';
 import type { AdminChatTaskCounters, AdminChatTaskRecord } from '../../chatTasksAdmin';
 import type { UserChatJobStatus } from '../../userChat/UserChatJobRecord';
 import { getUserChatJobRunReportFromParameters } from '../../userChat/userChatJobRunReport';
@@ -79,6 +80,7 @@ export function mapAdminChatTaskSqlRow(row: AdminChatTaskSqlRow): AdminChatTaskR
         chatId: row.chatId,
         workerId: null,
         queueName: row.queueName,
+        isAgentGoalTask: isAgentGoalChatId(row.chatId),
         runReport: getUserChatJobRunReportFromParameters(row.parameters),
     };
 }

package/apps/agents-server/src/utils/handleChatCompletion/createHandleChatCompletionPromptContext.ts

@@ -1,5 +1,6 @@
 import { createChatHistoryRecorder } from '@/src/utils/chat/createChatHistoryRecorder';
 import { composePromptParametersWithMemoryContext } from '@/src/utils/memoryRuntimeContext';
+import { createAgentGoalChatTimeoutTools } from '@/src/tools/agentGoalChatTimeoutTools';
 import type { ChatMessage, ChatPrompt } from '@promptbook-local/types';
 import { $getCurrentDate } from '@promptbook-local/utils';
 import type { NextRequest } from 'next/server';
@@ -64,12 +65,12 @@ export async function createHandleChatCompletionPromptContext(options: {
         projectRepositories: runtime.projectRepositories,
         projectGithubToken: runtime.projectGithubToken,
         emailSmtpCredential: runtime.emailSmtpCredential,
-        emailFromAddress: runtime.useEmailConfiguration.senderEmail,
         calendarGoogleAccessToken: runtime.calendarGoogleAccessToken,
         calendarConnections: runtime.calendarConnections,
         localServerUrl: runtime.localServerUrl,
         teamInternalAccessToken: resolveTeamInternalAgentAccessToken(),
     });
+    const runtimeTools = createAgentGoalChatTimeoutTools(parsedRequest.runtimeTools || []);
     const prompt: ChatPrompt = {
         title,
         content: lastMessage.content,
@@ -80,7 +81,7 @@ export async function createHandleChatCompletionPromptContext(options: {
         },
         parameters: promptParameters,
         thread,
-        ...(parsedRequest.runtimeTools ? { tools: parsedRequest.runtimeTools } : {}),
+        tools: runtimeTools,
     };
 
     return {

package/apps/agents-server/src/utils/handleChatCompletion/resolveHandleChatCompletionRuntime.ts

@@ -5,7 +5,6 @@ import type { string_book, TODO_any } from '@promptbook-local/types';
 import { createInlineKnowledgeSourceUploader } from '@/src/utils/knowledge/createInlineKnowledgeSourceUploader';
 import { resolveCurrentUserMemoryIdentity } from '@/src/utils/userMemory';
 import { extractUseCalendarConnectionsFromAgentSource } from '@/src/utils/calendars/extractUseCalendarConnectionsFromAgentSource';
-import { extractUseEmailConfigurationFromAgentSource } from '@/src/utils/emails/extractUseEmailConfigurationFromAgentSource';
 import { extractProjectRepositoriesFromAgentSource } from '@/src/utils/projects/extractProjectRepositoriesFromAgentSource';
 import { resolveUseEmailSmtpCredential } from '@/src/utils/resolveUseEmailSmtpCredential';
 import { resolveUseCalendarGoogleToken } from '@/src/utils/resolveUseCalendarGoogleToken';
@@ -43,7 +42,6 @@ export type HandleChatCompletionRuntime = {
     agentHash: string;
     projectRepositories: ReturnType<typeof extractProjectRepositoriesFromAgentSource>;
     calendarConnections: ReturnType<typeof extractUseCalendarConnectionsFromAgentSource>;
-    useEmailConfiguration: ReturnType<typeof extractUseEmailConfigurationFromAgentSource>;
     currentUserIdentity: Awaited<ReturnType<typeof resolveCurrentUserMemoryIdentity>>;
     projectGithubToken: Awaited<ReturnType<typeof resolveUseProjectGithubToken>>;
     calendarGoogleAccessToken: Awaited<ReturnType<typeof resolveUseCalendarGoogleToken>>;
@@ -95,7 +93,6 @@ export async function resolveHandleChatCompletionRuntime(options: {
     const unresolvedAgentSource = resolvedAgentContext.unresolvedAgentSource;
     const projectRepositories = extractProjectRepositoriesFromAgentSource(agentSource);
     const calendarConnections = extractUseCalendarConnectionsFromAgentSource(agentSource);
-    const useEmailConfiguration = extractUseEmailConfigurationFromAgentSource(agentSource);
     const messageSuffix = resolveMessageSuffixFromAgentSource(agentSource);
     const { agentSourceWithContext, hasDynamicContext } = appendSystemMessagesToAgentSource(agentSource, messages);
     agentSource = agentSourceWithContext;
@@ -121,7 +118,6 @@ export async function resolveHandleChatCompletionRuntime(options: {
             currentUserIdentity,
             agentId,
             calendarConnections,
-            useEmailConfiguration,
         });
     const agent = await createHandleChatCompletionAgent({
         agentName,
@@ -145,7 +141,6 @@ export async function resolveHandleChatCompletionRuntime(options: {
         agentHash,
         projectRepositories,
         calendarConnections,
-        useEmailConfiguration,
         currentUserIdentity,
         projectGithubToken,
         calendarGoogleAccessToken,
@@ -213,7 +208,6 @@ async function resolveHandleChatCompletionCredentials(options: {
     currentUserIdentity: Awaited<ReturnType<typeof resolveCurrentUserMemoryIdentity>>;
     agentId: string;
     calendarConnections: ReturnType<typeof extractUseCalendarConnectionsFromAgentSource>;
-    useEmailConfiguration: ReturnType<typeof extractUseEmailConfigurationFromAgentSource>;
 }): Promise<{
     projectGithubToken: Awaited<ReturnType<typeof resolveUseProjectGithubToken>>;
     calendarGoogleAccessToken: Awaited<ReturnType<typeof resolveUseCalendarGoogleToken>>;
@@ -231,12 +225,10 @@ async function resolveHandleChatCompletionCredentials(options: {
                   agentPermanentId: options.agentId,
               })
             : Promise.resolve(undefined),
-        options.useEmailConfiguration.isEnabled
-            ? resolveUseEmailSmtpCredential({
-                  userId,
-                  agentPermanentId: options.agentId,
-              })
-            : Promise.resolve(undefined),
+        resolveUseEmailSmtpCredential({
+            userId,
+            agentPermanentId: options.agentId,
+        }),
     ]);
 
     return {

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

@@ -0,0 +1,261 @@
+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,
+    type UpdateAgentGoalChatPlannedMessageResult,
+} 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' | 'update' | 'cancel'
+>;
+
+/**
+ * One planned-message command that was applied together with its result.
+ *
+ * The command carries what the agent asked for (for example the requested schedule) 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
+        | UpdateAgentGoalChatPlannedMessageResult
+        | 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,
+                ...createLocalAgentPlannedMessageScheduleRequest(options.command),
+                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;
+        }
+
+        if (options.command.action === 'update') {
+            const updatedPlannedMessage = await options.actions.update({
+                agentPermanentId: options.agentPermanentId,
+                timeoutId: options.command.timeoutId,
+                ...createLocalAgentPlannedMessageScheduleRequest(options.command),
+                ...(options.command.message === undefined ? {} : { message: options.command.message }),
+            });
+
+            console.info('[local-chat-runner]', 'planned_message_update', {
+                chatId: options.job.chatId,
+                jobId: options.job.id,
+                timeoutId: updatedPlannedMessage.timeoutId,
+                status: updatedPlannedMessage.status,
+                dueAt: updatedPlannedMessage.dueAt,
+            });
+
+            return updatedPlannedMessage.status === 'updated' ? updatedPlannedMessage : null;
+        }
+
+        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;
+    }
+}
+
+/**
+ * Collects the schedule fields of one sidecar command.
+ *
+ * A field the harness did not write stays absent, which is what tells "keep this part of the schedule"
+ * apart from "remove this bound".
+ *
+ * @param command - Planned-message command written by the coding harness.
+ * @returns Schedule fields passed to the shared planned-message actions.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function createLocalAgentPlannedMessageScheduleRequest(command: AgentPlannedMessageCommand): {
+    readonly [FieldName: string]: unknown;
+} {
+    return {
+        ...(command.milliseconds === undefined ? {} : { milliseconds: command.milliseconds }),
+        ...(command.cronExpression === undefined ? {} : { cronExpression: command.cronExpression }),
+        ...(command.startsAt === undefined ? {} : { startsAt: command.startsAt }),
+        ...(command.endsAt === undefined ? {} : { endsAt: command.endsAt }),
+        ...(command.maxRunCount === undefined ? {} : { maxRunCount: command.maxRunCount }),
+    };
+}
+
+/**
+ * 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'),
+    );
+}