@promptbook/cli 0.114.0-2 → 0.114.0-20

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

@@ -0,0 +1,129 @@
+import { spaceTrim } from 'spacetrim';
+import {
+    describeAgentPlannedMessageSchedule,
+    type AgentPlannedMessageScheduleDescription,
+} from '../../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
+
+/**
+ * Lifecycle events of an agent that are recorded in its goal chat.
+ */
+export type AgentGoalChatLifecycleEvent = 'CREATED' | 'MODIFIED';
+
+/**
+ * Builds the goal-chat note left when an agent is created or its book is modified.
+ *
+ * @param options - Lifecycle event and the agent name shown in the note.
+ * @returns Note content stored as one agent message.
+ */
+export function createAgentGoalChatLifecycleNoteContent(options: {
+    readonly event: AgentGoalChatLifecycleEvent;
+    readonly agentName: string;
+    readonly currentGoal: string | null;
+}): string {
+    const currentGoal = options.currentGoal?.trim() || null;
+    const goalSection = currentGoal
+        ? spaceTrim(
+              (block) => `
+                  My current goal is:
+
+                  ${block(currentGoal)}
+              `,
+          )
+        : 'I currently have no `GOAL` or `GOALS` commitment.';
+
+    if (options.event === 'CREATED') {
+        return spaceTrim(
+            (block) => `
+                🌱 I was created as \`${options.agentName}\`.
+
+                ${block(goalSection)}
+
+                This is my own thread for acting towards that goal. I should work on it now when useful,
+                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.
+            `,
+        );
+    }
+
+    return spaceTrim(
+        (block) => `
+            📝 My book was updated, so \`${options.agentName}\` may work differently from now on.
+
+            ${block(goalSection)}
+
+            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.
+        `,
+    );
+}
+
+/**
+ * Planned-message details shown in one goal-chat note.
+ */
+export type AgentGoalChatPlannedMessageNoteOptions = AgentPlannedMessageScheduleDescription & {
+    readonly timeoutId: string;
+    readonly dueAt: string;
+    readonly message?: string | null;
+};
+
+/**
+ * Builds the goal-chat note left when a planned message is scheduled.
+ *
+ * @param options - Planned-message identity, its whole schedule, and optional payload message.
+ * @returns Note content stored as one agent message.
+ */
+export function createAgentGoalChatPlannedMessageNoteContent(options: AgentGoalChatPlannedMessageNoteOptions): string {
+    return createAgentGoalChatPlannedMessageScheduleNoteContent('⏳ I planned a message that', options);
+}
+
+/**
+ * Builds the goal-chat note left when the schedule of a planned message is changed.
+ *
+ * @param options - Planned-message identity, its new schedule, and optional payload message.
+ * @returns Note content stored as one agent message.
+ */
+export function createAgentGoalChatUpdatedPlannedMessageNoteContent(
+    options: AgentGoalChatPlannedMessageNoteOptions,
+): string {
+    return createAgentGoalChatPlannedMessageScheduleNoteContent('🔁 I changed a planned message, which now', options);
+}
+
+/**
+ * Builds one goal-chat note describing the current schedule of a planned message.
+ *
+ * @param headlinePrefix - Sentence opening telling apart a new plan from a changed one.
+ * @param options - Planned-message identity, its schedule, and optional payload message.
+ * @returns Note content stored as one agent message.
+ *
+ * @private function of `createAgentGoalChatNoteContent`
+ */
+function createAgentGoalChatPlannedMessageScheduleNoteContent(
+    headlinePrefix: string,
+    options: AgentGoalChatPlannedMessageNoteOptions,
+): string {
+    const plannedMessage = options.message?.trim() || '';
+
+    return spaceTrim(
+        (block) => `
+            ${headlinePrefix} ${describeAgentPlannedMessageSchedule(options)}.
+
+            ${plannedMessage ? block(plannedMessage) : ''}
+
+            timeoutId: ${options.timeoutId}
+        `,
+    );
+}
+
+/**
+ * Builds the goal-chat note left when a planned message is cancelled.
+ *
+ * @param options - Planned-message identity.
+ * @returns Note content stored as one agent message.
+ */
+export function createAgentGoalChatCancelledPlannedMessageNoteContent(options: { readonly timeoutId: string }): string {
+    return spaceTrim(`
+        🚫 I cancelled the planned message \`${options.timeoutId}\`, so it will not wake me up anymore.
+    `);
+}

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

@@ -0,0 +1,167 @@
+import { serializeError, spaceTrim } from '@promptbook-local/utils';
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { resolveCurrentOrInternalServerOrigin } from '../resolveCurrentOrInternalServerOrigin';
+import { appendQueuedUserChatTurn } from '../userChat/appendQueuedUserChatTurn';
+import { getUserChatJobByClientMessageId } from '../userChat/getUserChatJobByClientMessageId';
+import { triggerUserChatJobWorker } from '../userChat/triggerUserChatJobWorker';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import { ensureAgentGoalChat } from './ensureAgentGoalChat';
+
+/**
+ * Prefix used for deterministic lifecycle-triggered goal-chat job ids.
+ */
+const AGENT_GOAL_CHAT_LIFECYCLE_CLIENT_MESSAGE_ID_PREFIX = 'goal-lifecycle:';
+
+/**
+ * Lifecycle context persisted with an autonomous goal-chat turn.
+ */
+export type AgentGoalChatTurnTrigger = 'CREATED' | 'MODIFIED';
+
+/**
+ * Input needed to enqueue one agent-owned goal-chat turn.
+ */
+export type EnqueueAgentGoalChatTurnOptions = {
+    readonly agentPermanentId: string;
+    readonly content: string;
+    readonly sourceFingerprint: string;
+    readonly trigger: AgentGoalChatTurnTrigger;
+};
+
+/**
+ * Dependencies used to persist and trigger an autonomous goal-chat turn.
+ */
+type AgentGoalChatTurnEnqueuerDependencies = {
+    readonly ensureAgentGoalChat: typeof ensureAgentGoalChat;
+    readonly appendQueuedUserChatTurn: typeof appendQueuedUserChatTurn;
+    readonly getUserChatJobByClientMessageId: typeof getUserChatJobByClientMessageId;
+    readonly resolveCurrentOrInternalServerOrigin: typeof resolveCurrentOrInternalServerOrigin;
+    readonly triggerUserChatJobWorker: typeof triggerUserChatJobWorker;
+};
+
+/**
+ * Production dependencies for autonomous goal-chat turns.
+ */
+const AGENT_GOAL_CHAT_TURN_ENQUEUER_DEPENDENCIES: AgentGoalChatTurnEnqueuerDependencies = {
+    ensureAgentGoalChat,
+    appendQueuedUserChatTurn,
+    getUserChatJobByClientMessageId,
+    resolveCurrentOrInternalServerOrigin,
+    triggerUserChatJobWorker,
+};
+
+/**
+ * Creates an idempotent enqueuer for server-triggered turns in an agent's singleton goal chat.
+ *
+ * @param dependencyOverrides - Optional dependency substitutions used by focused tests.
+ * @returns Function that resolves the singleton chat, appends a durable turn, and wakes its worker.
+ */
+export function createAgentGoalChatTurnEnqueuer(
+    dependencyOverrides: Partial<AgentGoalChatTurnEnqueuerDependencies> = {},
+): (options: EnqueueAgentGoalChatTurnOptions) => Promise<UserChatJobRecord> {
+    const dependencies: AgentGoalChatTurnEnqueuerDependencies = {
+        ...AGENT_GOAL_CHAT_TURN_ENQUEUER_DEPENDENCIES,
+        ...dependencyOverrides,
+    };
+
+    return async (options: EnqueueAgentGoalChatTurnOptions): Promise<UserChatJobRecord> => {
+        const goalChat = await dependencies.ensureAgentGoalChat(options.agentPermanentId);
+        const clientMessageId = createAgentGoalChatLifecycleClientMessageId(options.sourceFingerprint);
+        const existingJob = await dependencies.getUserChatJobByClientMessageId({
+            userId: goalChat.userId,
+            agentPermanentId: options.agentPermanentId,
+            chatId: goalChat.id,
+            clientMessageId,
+        });
+
+        if (existingJob) {
+            return existingJob;
+        }
+
+        let job: UserChatJobRecord;
+
+        try {
+            const queuedTurn = await dependencies.appendQueuedUserChatTurn({
+                userId: goalChat.userId,
+                agentPermanentId: options.agentPermanentId,
+                chatId: goalChat.id,
+                clientMessageId,
+                messageContent: options.content,
+                messageSender: 'AGENT',
+                parameters: {
+                    agentGoalChatTrigger: options.trigger,
+                    agentGoalChatSourceFingerprint: options.sourceFingerprint,
+                },
+            });
+            job = queuedTurn.job;
+        } catch (error) {
+            if (!isDuplicateUserChatJobError(error)) {
+                throw error;
+            }
+
+            const racedJob = await dependencies.getUserChatJobByClientMessageId({
+                userId: goalChat.userId,
+                agentPermanentId: options.agentPermanentId,
+                chatId: goalChat.id,
+                clientMessageId,
+            });
+
+            if (!racedJob) {
+                throw new DatabaseError(
+                    spaceTrim(`
+                        Goal-chat turn \`${clientMessageId}\` was reported as duplicated but could not be loaded.
+
+                        - Agent: \`${options.agentPermanentId}\`
+                        - Goal chat: \`${goalChat.id}\`
+                    `),
+                );
+            }
+
+            job = racedJob;
+        }
+
+        try {
+            await dependencies.triggerUserChatJobWorker({
+                origin: await dependencies.resolveCurrentOrInternalServerOrigin(),
+                preferredJobId: job.id,
+            });
+        } catch (error) {
+            // Note: The durable job remains queued and will be picked up by the regular worker tick
+            console.error('[agent-goal-chat]', 'turn_trigger_failed', {
+                agentPermanentId: options.agentPermanentId,
+                chatId: goalChat.id,
+                jobId: job.id,
+                error: serializeError(error as Error),
+            });
+        }
+
+        return job;
+    };
+}
+
+/**
+ * Production enqueuer for lifecycle-triggered goal-chat turns.
+ */
+export const enqueueAgentGoalChatTurn = createAgentGoalChatTurnEnqueuer();
+
+/**
+ * Creates a stable client message id for one source version.
+ *
+ * The trigger reason is deliberately excluded: creating an agent and immediately saving the same
+ * source must not run the same goal review twice.
+ *
+ * @param sourceFingerprint - Hash of the agent source that caused the turn.
+ * @returns Durable job idempotency key.
+ */
+export function createAgentGoalChatLifecycleClientMessageId(sourceFingerprint: string): string {
+    return `${AGENT_GOAL_CHAT_LIFECYCLE_CLIENT_MESSAGE_ID_PREFIX}${sourceFingerprint}`;
+}
+
+/**
+ * Detects the durable-job unique-constraint error used for idempotent enqueue recovery.
+ *
+ * @param error - Caught append failure.
+ * @returns `true` when another request already created the same job.
+ */
+function isDuplicateUserChatJobError(error: unknown): boolean {
+    return error instanceof Error && error.name === 'UserChatJobDuplicateError';
+}

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

@@ -0,0 +1,66 @@
+import type { UserChatRecord } from '../userChat/UserChatRecord';
+import { USER_CHAT_SOURCES } from '../userChat/UserChatSource';
+import { createUserChat } from '../userChat/createUserChat';
+import { getUserChat } from '../userChat/getUserChat';
+import { AGENT_GOAL_CHAT_TITLE } from './agentGoalChatConstants';
+import { buildAgentGoalChatId } from './agentGoalChatIdentity';
+import { resolveAgentGoalChatOwnerUserId } from './resolveAgentGoalChatOwnerUserId';
+
+/**
+ * Loads the singleton goal chat of one agent, creating it on first use.
+ *
+ * The chat id is derived from the agent permanent id, so concurrent callers converge on the very
+ * same row and an agent can never end up with two goal chats.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the goal chat.
+ * @returns Persisted goal-chat record.
+ */
+export async function ensureAgentGoalChat(agentPermanentId: string): Promise<UserChatRecord> {
+    const chatId = buildAgentGoalChatId(agentPermanentId);
+    const existingGoalChat = await loadAgentGoalChat(agentPermanentId, chatId);
+
+    if (existingGoalChat) {
+        return existingGoalChat;
+    }
+
+    try {
+        return await createUserChat({
+            chatId,
+            userId: await resolveAgentGoalChatOwnerUserId(agentPermanentId),
+            agentPermanentId,
+            source: USER_CHAT_SOURCES.AGENT_GOAL,
+            title: AGENT_GOAL_CHAT_TITLE,
+        });
+    } catch (error) {
+        // Note: Another request may have created the very same singleton row in the meantime
+        const racedGoalChat = await loadAgentGoalChat(agentPermanentId, chatId);
+
+        if (racedGoalChat) {
+            return racedGoalChat;
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Loads the stored goal chat of one agent by its deterministic id.
+ *
+ * The stored owner is deliberately not part of the lookup: agent ownership can change after the
+ * goal chat was created, while the goal chat itself must stay the very same singleton row.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the goal chat.
+ * @param chatId - Deterministic goal-chat id.
+ * @returns Stored goal chat, or `null` when it does not exist yet.
+ *
+ * @private function of `ensureAgentGoalChat`
+ */
+async function loadAgentGoalChat(agentPermanentId: string, chatId: string): Promise<UserChatRecord | null> {
+    return getUserChat({
+        // Note: The access decision belongs to the callers of `ensureAgentGoalChat`
+        userId: 0,
+        viewerCanAccessAgentGoalChat: true,
+        agentPermanentId,
+        chatId,
+    });
+}

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

@@ -0,0 +1,40 @@
+import { serializeError } from '@promptbook-local/utils';
+import type { UserChatSummarySeed } from '../userChat/createUserChatSummary';
+import { createUserChatSummarySeedFromChatRecord } from '../userChat/listUserChats';
+import { ensureAgentGoalChat } from './ensureAgentGoalChat';
+import { isAgentGoalChatId } from './agentGoalChatIdentity';
+
+/**
+ * Puts the singleton goal chat of one agent on top of the chat-history list.
+ *
+ * The goal chat is not owned by the viewer and is therefore not part of the normal chat listing
+ * query, so it is resolved separately and pinned in front of every other chat.
+ *
+ * @param options - Loaded chat seeds together with the agent and the viewer's access decision.
+ * @returns Chat seeds, with the goal chat first whenever the viewer may read it.
+ */
+export async function prependAgentGoalChatSummarySeed(options: {
+    readonly chatSummarySeeds: ReadonlyArray<UserChatSummarySeed>;
+    readonly agentPermanentId: string;
+    readonly isAgentGoalChatVisible: boolean;
+}): Promise<Array<UserChatSummarySeed>> {
+    const otherChatSummarySeeds = options.chatSummarySeeds.filter(
+        (chatSummarySeed) => !isAgentGoalChatId(chatSummarySeed.id),
+    );
+
+    if (!options.isAgentGoalChatVisible) {
+        return otherChatSummarySeeds;
+    }
+
+    try {
+        const goalChat = await ensureAgentGoalChat(options.agentPermanentId);
+        return [createUserChatSummarySeedFromChatRecord(goalChat), ...otherChatSummarySeeds];
+    } catch (error) {
+        // Note: A missing goal chat must never break the chat list of the agent
+        console.error('[agent-goal-chat]', 'list_seed_failed', {
+            agentPermanentId: options.agentPermanentId,
+            error: serializeError(error as Error),
+        });
+        return otherChatSummarySeeds;
+    }
+}

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

@@ -0,0 +1,53 @@
+import { computeHash, serializeError } from '@promptbook-local/utils';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { appendAgentGoalChatNote } from './appendAgentGoalChatNote';
+import {
+    createAgentGoalChatLifecycleNoteContent,
+    type AgentGoalChatLifecycleEvent,
+} from './createAgentGoalChatNoteContent';
+import { enqueueAgentGoalChatTurn } from './enqueueAgentGoalChatTurn';
+import { resolveEffectiveAgentGoal } from './resolveEffectiveAgentGoal';
+
+/**
+ * Leaves the goal-chat note that records one agent lifecycle event.
+ *
+ * Writing the note is best-effort on purpose: creating or saving an agent must never fail because
+ * its goal chat could not be updated.
+ *
+ * @param options - Lifecycle event together with the affected agent.
+ */
+export async function recordAgentGoalChatLifecycleNote(options: {
+    readonly event: AgentGoalChatLifecycleEvent;
+    readonly agentPermanentId: string;
+    readonly agentName: string;
+    readonly agentSource: string_book;
+}): Promise<void> {
+    try {
+        const currentGoal = resolveEffectiveAgentGoal(options.agentSource);
+        const content = createAgentGoalChatLifecycleNoteContent({
+            event: options.event,
+            agentName: options.agentName,
+            currentGoal,
+        });
+
+        if (currentGoal) {
+            await enqueueAgentGoalChatTurn({
+                agentPermanentId: options.agentPermanentId,
+                content,
+                sourceFingerprint: computeHash(options.agentSource),
+                trigger: options.event,
+            });
+        } else {
+            await appendAgentGoalChatNote({
+                agentPermanentId: options.agentPermanentId,
+                content,
+            });
+        }
+    } catch (error) {
+        console.error('[agent-goal-chat]', 'lifecycle_note_failed', {
+            event: options.event,
+            agentPermanentId: options.agentPermanentId,
+            error: serializeError(error as Error),
+        });
+    }
+}

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

@@ -0,0 +1,104 @@
+import { spaceTrim } from 'spacetrim';
+import { DatabaseError } from '../../../../../src/errors/DatabaseError';
+import { $getTableName } from '../../database/$getTableName';
+import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
+
+/**
+ * Resolves the database user the singleton goal chat of one agent is stored under.
+ *
+ * The goal chat conceptually belongs to the agent, not to any human, but `UserChat.userId` is a
+ * non-null foreign key. The agent owner is therefore used, with the same fallback ordering the
+ * ownership migration uses when an agent has no owner assigned yet.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the goal chat.
+ * @returns Database user id used as the goal-chat owner.
+ */
+export async function resolveAgentGoalChatOwnerUserId(agentPermanentId: string): Promise<number> {
+    const agentOwnerUserId = await loadAgentOwnerUserId(agentPermanentId);
+
+    if (typeof agentOwnerUserId === 'number') {
+        return agentOwnerUserId;
+    }
+
+    return loadFallbackOwnerUserId(agentPermanentId);
+}
+
+/**
+ * Loads the owner of one agent row.
+ *
+ * @param agentPermanentId - Permanent id of the agent.
+ * @returns Owning user id, or `null` when the agent has no owner assigned.
+ *
+ * @private function of `resolveAgentGoalChatOwnerUserId`
+ */
+async function loadAgentOwnerUserId(agentPermanentId: string): Promise<number | null> {
+    const supabase = $provideSupabaseForServer();
+    const agentTableName = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(agentTableName)
+        .select('userId')
+        .eq('permanentId', agentPermanentId)
+        .maybeSingle();
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to load the owner of agent \`${agentPermanentId}\` for its goal chat.
+
+                **Cause:** \`${error.message}\`
+            `),
+        );
+    }
+
+    const userId = (data as { userId?: unknown } | null)?.userId;
+    return typeof userId === 'number' ? userId : null;
+}
+
+/**
+ * Loads the fallback goal-chat owner used when an agent has no owner assigned.
+ *
+ * Mirrors the `fallbackUser` ordering of the ownership migration so unowned agents keep a stable,
+ * predictable goal-chat owner.
+ *
+ * @param agentPermanentId - Permanent id of the agent, used only for error reporting.
+ * @returns Database user id of the fallback owner.
+ *
+ * @private function of `resolveAgentGoalChatOwnerUserId`
+ */
+async function loadFallbackOwnerUserId(agentPermanentId: string): Promise<number> {
+    const supabase = $provideSupabaseForServer();
+    const userTableName = await $getTableName('User');
+    const { data, error } = await supabase
+        .from(userTableName)
+        .select('id')
+        .order('isAdmin', { ascending: false })
+        .order('createdAt', { ascending: true })
+        .order('id', { ascending: true })
+        .limit(1)
+        .maybeSingle();
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to resolve the fallback goal-chat owner for agent \`${agentPermanentId}\`.
+
+                **Cause:** \`${error.message}\`
+            `),
+        );
+    }
+
+    const fallbackUserId = (data as { id?: unknown } | null)?.id;
+
+    if (typeof fallbackUserId !== 'number') {
+        throw new DatabaseError(
+            spaceTrim(`
+                Agent \`${agentPermanentId}\` has no owner and this server has no user to fall back to,
+                so its goal chat cannot be stored.
+
+                **Note:** Every goal chat is persisted as one \`UserChat\` row, which requires a \`userId\`.
+            `),
+        );
+    }
+
+    return fallbackUserId;
+}

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

@@ -0,0 +1,29 @@
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { parseAgentSourceWithCommitments } from '../../../../../src/book-2.0/agent-source/parseAgentSourceWithCommitments';
+
+/**
+ * Resolves the effective non-empty `GOAL` or `GOALS` commitment from one agent source.
+ *
+ * Goal commitments overwrite each other in source order, so the last non-empty declaration is
+ * the same goal that reaches the agent model requirements.
+ *
+ * @param agentSource - Current persisted agent source.
+ * @returns Effective goal text, or `null` when no goal is defined.
+ */
+export function resolveEffectiveAgentGoal(agentSource: string_book): string | null {
+    const commitments = parseAgentSourceWithCommitments(agentSource).commitments;
+
+    for (let index = commitments.length - 1; index >= 0; index--) {
+        const commitment = commitments[index]!;
+        if (commitment.type !== 'GOAL' && commitment.type !== 'GOALS') {
+            continue;
+        }
+
+        const goal = commitment.content.trim();
+        if (goal) {
+            return goal;
+        }
+    }
+
+    return null;
+}

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

@@ -0,0 +1,85 @@
+import { debounce } from '@promptbook-local/utils';
+import type { ProvidedServer } from '@/src/tools/$provideServer';
+import { runWithServerContextOverride } from '@/src/tools/serverContextOverride';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { recordAgentGoalChatLifecycleNote } from './recordAgentGoalChatLifecycleNote';
+
+/**
+ * Delay after the final persisted book update before the goal chat receives one modification note.
+ */
+export const AGENT_GOAL_CHAT_MODIFIED_NOTE_DEBOUNCE_DELAY_MS = 60_000;
+
+/**
+ * Agent identity used to write one delayed book-modification note.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+type AgentGoalChatModifiedNote = {
+    readonly agentPermanentId: string;
+    readonly agentName: string;
+    readonly agentSource: string_book;
+    readonly server: ProvidedServer;
+};
+
+/**
+ * Runs delayed work under the server that owned the source update.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+type RunWithServerContext = (
+    server: ProvidedServer,
+    callback: () => Promise<void>,
+) => Promise<void>;
+
+/**
+ * Creates an independent one-minute debounce for each agent's goal-chat modification note.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+export function createAgentGoalChatModifiedNoteScheduler(options?: {
+    readonly recordAgentGoalChatLifecycleNote?: typeof recordAgentGoalChatLifecycleNote;
+    readonly runWithServerContextOverride?: RunWithServerContext;
+}): (agentGoalChatModifiedNote: AgentGoalChatModifiedNote) => void {
+    const debouncedNoteRecordersByServerAndAgent = new Map<
+        string,
+        ((agentGoalChatModifiedNote: AgentGoalChatModifiedNote) => void) & { cancel: () => void }
+    >();
+    const recordLifecycleNote = options?.recordAgentGoalChatLifecycleNote || recordAgentGoalChatLifecycleNote;
+    const runWithServerContext = options?.runWithServerContextOverride || runWithServerContextOverride;
+
+    return (agentGoalChatModifiedNote: AgentGoalChatModifiedNote) => {
+        const agentGoalChatModifiedNoteKey = createAgentGoalChatModifiedNoteKey(agentGoalChatModifiedNote);
+        let debouncedNoteRecorder = debouncedNoteRecordersByServerAndAgent.get(agentGoalChatModifiedNoteKey);
+
+        if (!debouncedNoteRecorder) {
+            debouncedNoteRecorder = debounce((latestAgentGoalChatModifiedNote: AgentGoalChatModifiedNote) => {
+                debouncedNoteRecordersByServerAndAgent.delete(agentGoalChatModifiedNoteKey);
+                void runWithServerContext(latestAgentGoalChatModifiedNote.server, () =>
+                    recordLifecycleNote({
+                        event: 'MODIFIED',
+                        agentPermanentId: latestAgentGoalChatModifiedNote.agentPermanentId,
+                        agentName: latestAgentGoalChatModifiedNote.agentName,
+                        agentSource: latestAgentGoalChatModifiedNote.agentSource,
+                    }),
+                );
+            }, AGENT_GOAL_CHAT_MODIFIED_NOTE_DEBOUNCE_DELAY_MS);
+            debouncedNoteRecordersByServerAndAgent.set(agentGoalChatModifiedNoteKey, debouncedNoteRecorder);
+        }
+
+        debouncedNoteRecorder(agentGoalChatModifiedNote);
+    };
+}
+
+/**
+ * Schedules one best-effort goal-chat note after the latest book update of each agent.
+ */
+export const scheduleAgentGoalChatModifiedNote = createAgentGoalChatModifiedNoteScheduler();
+
+/**
+ * Creates the per-server, per-agent key used to keep independent note debounces separate.
+ *
+ * @private function of scheduleAgentGoalChatModifiedNote
+ */
+function createAgentGoalChatModifiedNoteKey(agentGoalChatModifiedNote: AgentGoalChatModifiedNote): string {
+    return JSON.stringify([agentGoalChatModifiedNote.server.tablePrefix, agentGoalChatModifiedNote.agentPermanentId]);
+}