@promptbook/cli 0.114.0-13 → 0.114.0-18

package/apps/agents-server/src/utils/cronExpression/resolveNextCronRun.ts

@@ -0,0 +1,100 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import type { ParsedCronExpression } from './CronExpression';
+import { parseCronExpression } from './parseCronExpression';
+
+/**
+ * Maximum number of minutes scanned while finding the next cron run.
+ *
+ * Five years keeps leap-day schedules valid while still rejecting impossible expressions.
+ *
+ * @private constant of `cronExpression`
+ */
+const CRON_EXPRESSION_LOOKAHEAD_MINUTES = 366 * 24 * 60 * 5;
+
+/**
+ * Finds the next local server time matching one cron expression.
+ *
+ * @param cronExpression - Cron expression, validated on the fly.
+ * @param afterDate - Date after which the next run must happen.
+ * @returns Next matching local server time.
+ *
+ * @private function of `cronExpression`
+ */
+export function resolveNextCronRun(cronExpression: string, afterDate = new Date()): Date {
+    return resolveNextCronRunFromParsedExpression(parseCronExpression(cronExpression), afterDate);
+}
+
+/**
+ * Finds the next local server time matching one already parsed cron expression.
+ *
+ * @param parsedCronExpression - Parsed cron expression.
+ * @param afterDate - Date after which the next run must happen.
+ * @returns Next matching local server time.
+ *
+ * @private function of `cronExpression`
+ */
+export function resolveNextCronRunFromParsedExpression(
+    parsedCronExpression: ParsedCronExpression,
+    afterDate: Date,
+): Date {
+    const cursor = new Date(afterDate.getTime());
+    cursor.setSeconds(0, 0);
+    cursor.setMinutes(cursor.getMinutes() + 1);
+
+    for (let index = 0; index < CRON_EXPRESSION_LOOKAHEAD_MINUTES; index++) {
+        if (isCronExpressionDateMatched(parsedCronExpression, cursor)) {
+            return new Date(cursor.getTime());
+        }
+
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+
+    throw new ParseError(
+        spaceTrim(`
+            Cron expression cannot be scheduled.
+
+            **Use a cron expression that matches at least one valid date.**
+        `),
+    );
+}
+
+/**
+ * Tests whether one date matches a parsed cron expression.
+ *
+ * @param parsedCronExpression - Parsed cron expression.
+ * @param date - Candidate local server date.
+ * @returns `true` when the date matches.
+ *
+ * @private function of `resolveNextCronRun`
+ */
+function isCronExpressionDateMatched(parsedCronExpression: ParsedCronExpression, date: Date): boolean {
+    if (!parsedCronExpression.minute.values.has(date.getMinutes())) {
+        return false;
+    }
+
+    if (!parsedCronExpression.hour.values.has(date.getHours())) {
+        return false;
+    }
+
+    if (!parsedCronExpression.month.values.has(date.getMonth() + 1)) {
+        return false;
+    }
+
+    const isDayOfMonthMatched = parsedCronExpression.dayOfMonth.values.has(date.getDate());
+    const isDayOfWeekMatched = parsedCronExpression.dayOfWeek.values.has(date.getDay());
+
+    if (parsedCronExpression.dayOfMonth.isWildcard && parsedCronExpression.dayOfWeek.isWildcard) {
+        return true;
+    }
+
+    if (parsedCronExpression.dayOfMonth.isWildcard) {
+        return isDayOfWeekMatched;
+    }
+
+    if (parsedCronExpression.dayOfWeek.isWildcard) {
+        return isDayOfMonthMatched;
+    }
+
+    return isDayOfMonthMatched || isDayOfWeekMatched;
+}

package/apps/agents-server/src/utils/cronExpression/throwInvalidCronExpressionField.ts

@@ -0,0 +1,20 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+
+/**
+ * Throws a branded validation error for one invalid cron field value.
+ *
+ * @param value - Invalid field value.
+ * @param fieldName - Field name shown in the error message.
+ *
+ * @private function of `cronExpression`
+ */
+export function throwInvalidCronExpressionField(value: string, fieldName: string): never {
+    throw new ParseError(
+        spaceTrim(`
+            Cron field \`${fieldName}\` contains invalid value \`${value}\`.
+
+            **Use numbers, \`*\`, comma lists, ranges, and step values only.**
+        `),
+    );
+}

package/apps/agents-server/src/utils/cronExpression.ts

@@ -0,0 +1,10 @@
+export { CRON_EXPRESSION_FIELD_COUNT } from './cronExpression/CronExpression';
+export { normalizeCronExpression } from './cronExpression/normalizeCronExpression';
+export { normalizeCronExpressionWhitespace } from './cronExpression/normalizeCronExpressionWhitespace';
+export { parseCronExpression } from './cronExpression/parseCronExpression';
+export { resolveNextCronRun, resolveNextCronRunFromParsedExpression } from './cronExpression/resolveNextCronRun';
+export type {
+    CronExpressionField,
+    CronExpressionFieldOptions,
+    ParsedCronExpression,
+} from './cronExpression/CronExpression';

package/apps/agents-server/src/utils/explicitFromCommitment.ts

@@ -0,0 +1,130 @@
+import type { string_book } from '../../../../src/_packages/types.index'; // <- [🚾]
+
+/**
+ * Commitment keyword that declares the parent agent of one book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+const FROM_COMMITMENT_TYPE = 'FROM';
+
+/**
+ * Matches one standalone `FROM` commitment line and captures its inline content.
+ *
+ * The Book parser accepts horizontal whitespace between a commitment keyword and its value, so inheritance resolution
+ * must do the same. Keeping this pattern here makes every server-side consumer agree on which `FROM` lines are real.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+const FROM_COMMITMENT_LINE_PATTERN = new RegExp(`^${FROM_COMMITMENT_TYPE}(?:\\s+(.*))?$`);
+
+/**
+ * One explicit `FROM` commitment written in a book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export type ExplicitFromCommitment = {
+    /**
+     * Zero-based index of the line the commitment was found on, within the scanned lines.
+     */
+    readonly lineIndex: number;
+
+    /**
+     * Trimmed commitment content, empty string for a blank `FROM`.
+     */
+    readonly content: string;
+};
+
+/**
+ * Collects every explicit single-line `FROM` commitment of one book.
+ *
+ * This lightweight parser is intentionally limited to the subset needed by inheritance
+ * resolution so it stays safe to bundle into the Next.js proxy path.
+ *
+ * @param sourceLines - Book source already split into lines.
+ * @returns Found `FROM` commitments in source order, empty when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function collectExplicitFromCommitments(
+    sourceLines: ReadonlyArray<string>,
+): ReadonlyArray<ExplicitFromCommitment> {
+    const explicitFromCommitments: Array<ExplicitFromCommitment> = [];
+    let hasSeenTitle = false;
+    let isInsideCodeBlock = false;
+
+    for (let lineIndex = 0; lineIndex < sourceLines.length; lineIndex++) {
+        const trimmedLine = (sourceLines[lineIndex] || '').trim();
+
+        if (!hasSeenTitle) {
+            if (!trimmedLine) {
+                continue;
+            }
+
+            hasSeenTitle = true;
+            continue;
+        }
+
+        if (trimmedLine.startsWith('```')) {
+            isInsideCodeBlock = !isInsideCodeBlock;
+            continue;
+        }
+
+        if (isInsideCodeBlock) {
+            continue;
+        }
+
+        const fromCommitmentMatch = FROM_COMMITMENT_LINE_PATTERN.exec(trimmedLine);
+        if (fromCommitmentMatch) {
+            explicitFromCommitments.push({
+                lineIndex,
+                content: (fromCommitmentMatch[1] || '').trim(),
+            });
+        }
+    }
+
+    return explicitFromCommitments;
+}
+
+/**
+ * Returns the effective explicit `FROM` commitment of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns The last explicit `FROM` commitment, or `undefined` when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function getEffectiveExplicitFromCommitment(agentSource: string_book): ExplicitFromCommitment | undefined {
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSource.split(/\r?\n/));
+    return explicitFromCommitments[explicitFromCommitments.length - 1];
+}
+
+/**
+ * Returns the effective explicit `FROM` commitment content of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns Trimmed commitment content, empty string for a blank explicit `FROM`, or `undefined` when `FROM` is absent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function getExplicitFromCommitmentContent(agentSource: string_book): string | undefined {
+    return getEffectiveExplicitFromCommitment(agentSource)?.content;
+}
+
+/**
+ * Returns true when one book declares no parent at all and therefore implicitly inherits from `@Adam`.
+ *
+ * Writing no `FROM` commitment is equivalent to writing `FROM @Adam`, so only an explicit
+ * `FROM @Null` / `FROM {Void}` turns the inheritance off.
+ *
+ * @param agentSource - Raw book source.
+ * @returns True when the implicit `@Adam` ancestor applies to this book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export function isImplicitAdamInheritance(agentSource: string_book): boolean {
+    return getExplicitFromCommitmentContent(agentSource) === undefined;
+}

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/localChatRunner/applyLocalAgentPlannedMessageCommands.ts

@@ -10,6 +10,7 @@ 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';
@@ -17,17 +18,23 @@ 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'>;
+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 delay) and the 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 | CancelAgentGoalChatPlannedMessageResult;
+    readonly result:
+        | SetAgentGoalChatPlannedMessageResult
+        | UpdateAgentGoalChatPlannedMessageResult
+        | CancelAgentGoalChatPlannedMessageResult;
 };
 
 /**
@@ -119,7 +126,7 @@ async function applyLocalAgentPlannedMessageCommand(options: {
         if (options.command.action === 'set') {
             const plannedMessage = await options.actions.set({
                 agentPermanentId: options.agentPermanentId,
-                milliseconds: options.command.milliseconds,
+                ...createLocalAgentPlannedMessageScheduleRequest(options.command),
                 message: options.command.message,
             });
 
@@ -133,6 +140,25 @@ async function applyLocalAgentPlannedMessageCommand(options: {
             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,
@@ -158,6 +184,29 @@ async function applyLocalAgentPlannedMessageCommand(options: {
     }
 }
 
+/**
+ * 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.
  *

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

@@ -6,7 +6,10 @@ import {
     type AgentPlannedMessageSnapshot,
     type AgentPlannedMessagesSidecar,
 } from '../../../../../src/book-3.0/AgentPlannedMessagesSidecar';
-import { AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS } from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import {
+    AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS,
+    type AgentGoalChatPlannedMessageItem,
+} from '../agentGoalChat/agentGoalChatPlannedMessageActions';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { LocalAgentFolder } from './ensureLocalAgentFolder';
 import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
@@ -46,21 +49,26 @@ export async function prepareLocalAgentPlannedMessagesSidecar(options: {
 /**
  * Reduces one stored planned message to the fields a coding harness needs.
  *
+ * The whole schedule travels into the sidecar, so the harness can compare a plan with its goal instead
+ * of only seeing when the next wake-up happens.
+ *
  * @param plannedMessage - Planned message returned by the shared planned-message actions.
  * @returns Snapshot written into the sidecar.
  *
  * @private function of `prepareLocalAgentPlannedMessagesSidecar`
  */
-function createLocalAgentPlannedMessageSnapshot(plannedMessage: {
-    readonly timeoutId: string;
-    readonly dueAt: string;
-    readonly message: string | null;
-    readonly intervalMs: number | null;
-}): AgentPlannedMessageSnapshot {
+function createLocalAgentPlannedMessageSnapshot(
+    plannedMessage: AgentGoalChatPlannedMessageItem,
+): AgentPlannedMessageSnapshot {
     return {
         timeoutId: plannedMessage.timeoutId,
         dueAt: plannedMessage.dueAt,
         message: plannedMessage.message,
         intervalMs: plannedMessage.intervalMs,
+        cronExpression: plannedMessage.cronExpression,
+        startsAt: plannedMessage.startsAt,
+        endsAt: plannedMessage.endsAt,
+        maxRunCount: plannedMessage.maxRunCount,
+        runCount: plannedMessage.runCount,
     };
 }

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

@@ -8,6 +8,8 @@ import {
     parseAgentMessageRunReport,
     type AgentMessageRunReport,
 } from '../../../../../src/book-3.0/AgentMessageRunReport';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../../../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
 import { createAnsweredMessageChipToolCalls } from '../chatMessageChips/createAnsweredMessageChipToolCalls';
 import { createUserChatJobFailureDetails } from '../userChat/createUserChatJobFailureDetails';
 import { claimNextQueuedUserChatJob } from '../userChat/claimNextQueuedUserChatJob';
@@ -294,6 +296,8 @@ async function synchronizeLocalUserChatJob(
                 job,
                 appliedPlannedMessageCommands,
                 touchedProjectNames: runReport?.touchedProjectNames || [],
+                projectChanges: runReport?.projectChanges || [],
+                touchedExternalSources: runReport?.touchedExternalSources || [],
             });
             const toolCalls = [...teamToolCalls, ...chipToolCalls];
             await persistUserChatJobTerminalState({
@@ -538,12 +542,16 @@ async function createAnsweredMessageChipToolCallsIfPossible(options: {
     readonly job: UserChatJobRecord;
     readonly appliedPlannedMessageCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
     readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly projectChanges: ReadonlyArray<AgentMessageProjectChange>;
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
 }): Promise<ReadonlyArray<ToolCall>> {
     try {
         return await createAnsweredMessageChipToolCalls({
             agentPermanentId: options.job.agentPermanentId,
             appliedPlannedMessageCommands: options.appliedPlannedMessageCommands,
             touchedProjectNames: options.touchedProjectNames,
+            projectChanges: options.projectChanges,
+            touchedExternalSources: options.touchedExternalSources,
         });
     } catch (error) {
         console.warn('[local-chat-runner] message_chips_build_failed', {

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingAgentBooks.ts

@@ -8,7 +8,7 @@ import { spaceTrim } from 'spacetrim';
 export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     Book expert
 
-    PERSONA You are expert in book language
+    GOAL Help users work with Book language.
     RULE You can work with the book language and write, modify, or consult the agents based on the book language.
 
     KNOWLEDGE https://live.ptbk.io/api/docs/book-language.md?language=en
@@ -20,9 +20,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     \`\`\`book
     Paul Smith & Associés
 
-    PERSONA You are a company lawyer.
-    Your job is to provide legal advice and support to the company and its employees.
-    You are knowledgeable, professional, and detail-oriented.
+    GOAL Provide knowledgeable, professional, and detail-oriented legal advice and support to the company and its employees.
     \`\`\`
 
     RULE You are writing a book in the language the user will ask you.
@@ -36,9 +34,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     \`\`\`book
     Mario Ferrari
 
-    PERSONA You are an Italian teacher.
-    You teach the Italian language.
-    You are knowledgeable, professional and detail-oriented.
+    GOAL Teach Italian as a knowledgeable, professional, and detail-oriented teacher.
     RULE Do not chat about anything other than Italian. You can speak Italian or discuss Italian grammar in English.
     LANGUAGES Italian, English
     \`\`\`
@@ -51,9 +47,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     \`\`\`book
     Mario Ferrari
 
-    PERSONA Jste učitel italštiny.
-    Učíte italský jazyk.
-    Jste znalý, profesionální a dbáte na detaily.
+    GOAL Učte italštinu jako znalý, profesionální učitel, který dbá na detaily.
     RULE Nepovídejte si o ničem jiném než o italštině. Můžete mluvit italsky nebo diskutovat o italské gramatice v angličtině.
     LANGUAGES Italština, čeština, angličtina
     \`\`\`
@@ -69,6 +63,6 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
 export const MAN_GO_REPLY_REVIEWER_BOOK = spaceTrim(`
     Kontrolor odpovědí
 
-    PERSONA Jste přísný kontrolor odpovědí zákaznické podpory. Porovnáváte návrh odpovědi s definicí agenta (book) - tonalita, délka, jazyk, zakázaná témata a dodržení instrukcí.
+    GOAL Přísně kontrolujte návrhy odpovědí zákaznické podpory proti definici agenta (book): tonalitu, délku, jazyk, zakázaná témata a dodržení instrukcí.
     RULE Odpovídáte výhradně požadovaným JSON polem v jednom \`json\` bloku, nic jiného.
 `);

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime.ts

@@ -65,7 +65,7 @@ export type EvaluateManGoAgentReplyInput = {
 const MAN_GO_TEST_FALLBACK_BOOK = spaceTrim(`
     Agent
 
-    PERSONA Jste užitečný asistent.
+    GOAL Pomáhejte uživatelům jako užitečný asistent.
     RULE Odpovídejte stručně a prakticky.
     CLOSED
 `);
@@ -127,7 +127,7 @@ function createBookPrompt(input: GenerateManGoBookInput): string {
         Requirements:
         - Use the provided name as the agent title.
         - Write natural-language commitments in Czech unless the brief clearly asks for another language.
-        - Include a useful PERSONA, GOAL, and practical RULE commitments derived from the description.
+        - Include a clear GOAL and practical RULE commitments derived from the description.
         - Keep commitment keywords in English.
         - Use Book-language commitments such as WRITING SAMPLE, WRITING RULES, MESSAGE SUFFIX, and NOTE when they fit the agent.
         - Do not use Markdown headings such as \`##\` as a substitute for Book-language commitments.

package/apps/agents-server/src/utils/managementApi/managementApiSchemas.ts

@@ -332,7 +332,7 @@ export const MANAGEMENT_API_EXAMPLES = {
         },
         source: spaceTrim(`
             Support Concierge
-            PERSONA You triage support tickets.
+            GOAL Triage support tickets.
             RULE Escalate billing issues.
         `),
         profile: {
@@ -346,7 +346,7 @@ export const MANAGEMENT_API_EXAMPLES = {
     createAgentRequest: {
         source: spaceTrim(`
             Support Concierge
-            PERSONA You triage support tickets.
+            GOAL Triage support tickets.
             RULE Escalate billing issues.
         `),
         folderId: 12,

package/apps/agents-server/src/utils/plannedMessageManager/cancelManagedPlannedMessage.ts

@@ -0,0 +1,35 @@
+import { AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS } from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import { getUserChatTimeoutById } from '../userChatTimeout';
+
+/**
+ * Outcome of cancelling one planned message from the admin manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelManagedPlannedMessageResult = 'cancelled' | 'not_found';
+
+/**
+ * Cancels one planned message of any agent, so it never wakes that agent again.
+ *
+ * The cancelled planned message is kept and keeps being listed as cancelled, because the manager is
+ * also the place where an administrator asks what a planned message did before it stopped.
+ *
+ * @param timeoutId - Id of the planned message being cancelled.
+ * @returns Whether the planned message was cancelled.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function cancelManagedPlannedMessage(timeoutId: string): Promise<CancelManagedPlannedMessageResult> {
+    const existingPlannedMessage = await getUserChatTimeoutById(timeoutId);
+
+    if (!existingPlannedMessage) {
+        return 'not_found';
+    }
+
+    const cancelResult = await AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS.cancel({
+        agentPermanentId: existingPlannedMessage.agentPermanentId,
+        timeoutId,
+    });
+
+    return cancelResult.status === 'cancelled' ? 'cancelled' : 'not_found';
+}