@promptbook/cli 0.114.0-1 → 0.114.0-10

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

@@ -0,0 +1,307 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import type { UserChatTimeoutRecord, UserChatTimeoutStatus } from '../userChatTimeout';
+import {
+    cancelScheduledUserChatTimeout,
+    getAgentScopedUserChatTimeout,
+    listAgentUserChatTimeouts,
+    scheduleThreadScopedUserChatTimeout,
+} from '../userChatTimeout';
+import { ensureAgentGoalChat } from './ensureAgentGoalChat';
+
+/**
+ * Default number of rows returned by a planned-message listing.
+ */
+const DEFAULT_LISTED_PLANNED_MESSAGES_LIMIT = 20;
+
+/**
+ * Maximum number of rows returned by one planned-message listing.
+ */
+const MAX_LISTED_PLANNED_MESSAGES_LIMIT = 100;
+
+/**
+ * Timeout states that still represent a future or currently firing goal-chat message.
+ */
+const ACTIVE_PLANNED_MESSAGE_STATUSES: ReadonlyArray<UserChatTimeoutStatus> = ['QUEUED', 'RUNNING'];
+
+/**
+ * Minimal goal-chat identity needed when scheduling a planned message.
+ */
+type AgentGoalChatPlannedMessageTarget = {
+    readonly id: string;
+    readonly userId: number;
+};
+
+/**
+ * Serializable summary of one planned goal-chat message.
+ */
+export type AgentGoalChatPlannedMessageItem = {
+    readonly timeoutId: string;
+    readonly status: UserChatTimeoutStatus;
+    readonly dueAt: string;
+    readonly isPaused: boolean;
+    readonly message: string | null;
+};
+
+/**
+ * Result returned after scheduling one planned goal-chat message.
+ */
+export type SetAgentGoalChatPlannedMessageResult = {
+    readonly action: 'set';
+    readonly status: 'set';
+    readonly timeoutId: string;
+    readonly dueAt: string;
+    readonly message: string | null;
+};
+
+/**
+ * Result returned after listing planned goal-chat messages.
+ */
+export type ListAgentGoalChatPlannedMessagesResult = {
+    readonly action: 'list';
+    readonly status: 'listed';
+    readonly items: ReadonlyArray<AgentGoalChatPlannedMessageItem>;
+    readonly total: number;
+};
+
+/**
+ * Result returned after trying to cancel one planned goal-chat message.
+ */
+export type CancelAgentGoalChatPlannedMessageResult = {
+    readonly action: 'cancel';
+    readonly status: 'cancelled' | 'not_found';
+    readonly timeoutId: string;
+    readonly dueAt?: string;
+};
+
+/**
+ * Shared operations used by both model tools and the coding-agent runtime API.
+ */
+export type AgentGoalChatPlannedMessageActions = {
+    readonly set: (options: {
+        readonly agentPermanentId: string;
+        readonly milliseconds: unknown;
+        readonly message: unknown;
+    }) => Promise<SetAgentGoalChatPlannedMessageResult>;
+    readonly list: (options: {
+        readonly agentPermanentId: string;
+        readonly isIncludingFinished?: unknown;
+        readonly limit?: unknown;
+    }) => Promise<ListAgentGoalChatPlannedMessagesResult>;
+    readonly cancel: (options: {
+        readonly agentPermanentId: string;
+        readonly timeoutId: unknown;
+    }) => Promise<CancelAgentGoalChatPlannedMessageResult>;
+};
+
+/**
+ * Persistence dependencies used by planned-message actions.
+ */
+export type AgentGoalChatPlannedMessageDependencies = {
+    readonly ensureAgentGoalChat: (agentPermanentId: string) => Promise<AgentGoalChatPlannedMessageTarget>;
+    readonly scheduleThreadScopedUserChatTimeout: typeof scheduleThreadScopedUserChatTimeout;
+    readonly listAgentUserChatTimeouts: typeof listAgentUserChatTimeouts;
+    readonly getAgentScopedUserChatTimeout: typeof getAgentScopedUserChatTimeout;
+    readonly cancelScheduledUserChatTimeout: typeof cancelScheduledUserChatTimeout;
+};
+
+/**
+ * Production persistence dependencies for planned-message actions.
+ */
+const AGENT_GOAL_CHAT_PLANNED_MESSAGE_DEPENDENCIES: AgentGoalChatPlannedMessageDependencies = {
+    ensureAgentGoalChat,
+    scheduleThreadScopedUserChatTimeout,
+    listAgentUserChatTimeouts,
+    getAgentScopedUserChatTimeout,
+    cancelScheduledUserChatTimeout,
+};
+
+/**
+ * Creates the shared planned-message operations for one agent's singleton goal chat.
+ *
+ * @param dependencyOverrides - Optional persistence substitutions used by focused tests.
+ * @returns Scheduling, listing, and cancellation operations with normalized serializable results.
+ */
+export function createAgentGoalChatPlannedMessageActions(
+    dependencyOverrides: Partial<AgentGoalChatPlannedMessageDependencies> = {},
+): AgentGoalChatPlannedMessageActions {
+    const dependencies: AgentGoalChatPlannedMessageDependencies = {
+        ...AGENT_GOAL_CHAT_PLANNED_MESSAGE_DEPENDENCIES,
+        ...dependencyOverrides,
+    };
+
+    return {
+        async set(options): Promise<SetAgentGoalChatPlannedMessageResult> {
+            const agentPermanentId = parseRequiredText(options.agentPermanentId, 'agentPermanentId');
+            const milliseconds = parsePositiveMilliseconds(options.milliseconds);
+            const message = parseRequiredText(options.message, 'message');
+            const goalChat = await dependencies.ensureAgentGoalChat(agentPermanentId);
+            const plannedMessage = await dependencies.scheduleThreadScopedUserChatTimeout({
+                userId: goalChat.userId,
+                agentPermanentId,
+                chatId: goalChat.id,
+                durationMs: milliseconds,
+                message,
+            });
+
+            return {
+                action: 'set',
+                status: 'set',
+                timeoutId: plannedMessage.timeoutId,
+                dueAt: plannedMessage.dueAt,
+                message: plannedMessage.message,
+            };
+        },
+
+        async list(options): Promise<ListAgentGoalChatPlannedMessagesResult> {
+            const agentPermanentId = parseRequiredText(options.agentPermanentId, 'agentPermanentId');
+            const isIncludingFinished = options.isIncludingFinished === true;
+            const limit = parseListLimit(options.limit);
+            const plannedMessages = await dependencies.listAgentUserChatTimeouts({
+                agentPermanentId,
+                ...(isIncludingFinished ? {} : { statuses: ACTIVE_PLANNED_MESSAGE_STATUSES }),
+                limit,
+            });
+            const items = [...plannedMessages]
+                .sort((leftMessage, rightMessage) => leftMessage.dueAt.localeCompare(rightMessage.dueAt))
+                .map(createPlannedMessageListItem);
+
+            return {
+                action: 'list',
+                status: 'listed',
+                items,
+                total: items.length,
+            };
+        },
+
+        async cancel(options): Promise<CancelAgentGoalChatPlannedMessageResult> {
+            const agentPermanentId = parseRequiredText(options.agentPermanentId, 'agentPermanentId');
+            const timeoutId = parseRequiredText(options.timeoutId, 'timeoutId');
+            const existingPlannedMessage = await dependencies.getAgentScopedUserChatTimeout({
+                agentPermanentId,
+                timeoutId,
+            });
+
+            if (!isActivePlannedMessage(existingPlannedMessage)) {
+                return {
+                    action: 'cancel',
+                    status: 'not_found',
+                    timeoutId,
+                };
+            }
+
+            const cancelledPlannedMessage = await dependencies.cancelScheduledUserChatTimeout(timeoutId);
+            const isCancelled = Boolean(cancelledPlannedMessage?.cancelRequestedAt);
+
+            return {
+                action: 'cancel',
+                status: isCancelled ? 'cancelled' : 'not_found',
+                timeoutId,
+                ...(cancelledPlannedMessage?.dueAt ? { dueAt: cancelledPlannedMessage.dueAt } : {}),
+            };
+        },
+    };
+}
+
+/**
+ * Production planned-message operations shared by Agents Server execution adapters.
+ */
+export const AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS = createAgentGoalChatPlannedMessageActions();
+
+/**
+ * Parses one positive timeout duration.
+ *
+ * @param rawMilliseconds - Untrusted duration supplied by a model or runtime API.
+ * @returns Positive whole milliseconds.
+ */
+function parsePositiveMilliseconds(rawMilliseconds: unknown): number {
+    const milliseconds = Number(rawMilliseconds);
+
+    if (!Number.isFinite(milliseconds) || milliseconds < 1) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message delay.
+
+                - \`milliseconds\` must be a positive number of at least \`1\`.
+            `),
+        );
+    }
+
+    return Math.floor(milliseconds);
+}
+
+/**
+ * Parses one required non-empty string argument.
+ *
+ * @param rawValue - Untrusted argument value.
+ * @param fieldName - Field name used in a detailed parse error.
+ * @returns Trimmed text.
+ */
+function parseRequiredText(rawValue: unknown, fieldName: 'agentPermanentId' | 'message' | 'timeoutId'): string {
+    if (typeof rawValue !== 'string' || rawValue.trim().length === 0) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message arguments.
+
+                - \`${fieldName}\` must be a non-empty string.
+            `),
+        );
+    }
+
+    return rawValue.trim();
+}
+
+/**
+ * Parses and bounds one requested listing size.
+ *
+ * @param rawLimit - Optional untrusted limit.
+ * @returns Whole limit in the supported range.
+ */
+function parseListLimit(rawLimit: unknown): number {
+    if (rawLimit === undefined || rawLimit === null) {
+        return DEFAULT_LISTED_PLANNED_MESSAGES_LIMIT;
+    }
+
+    const limit = Number(rawLimit);
+    if (!Number.isFinite(limit) || limit < 1 || limit > MAX_LISTED_PLANNED_MESSAGES_LIMIT) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message list limit.
+
+                - \`limit\` must be a positive number no greater than \`${MAX_LISTED_PLANNED_MESSAGES_LIMIT}\`.
+            `),
+        );
+    }
+
+    return Math.floor(limit);
+}
+
+/**
+ * Maps one durable timeout row into the model-facing planned-message shape.
+ *
+ * @param plannedMessage - Stored timeout row.
+ * @returns Serializable planned-message summary.
+ */
+function createPlannedMessageListItem(plannedMessage: UserChatTimeoutRecord): AgentGoalChatPlannedMessageItem {
+    return {
+        timeoutId: plannedMessage.timeoutId,
+        status: plannedMessage.status,
+        dueAt: plannedMessage.dueAt,
+        isPaused: Boolean(plannedMessage.pausedAt),
+        message: plannedMessage.message,
+    };
+}
+
+/**
+ * Determines whether one timeout can still be cancelled.
+ *
+ * @param plannedMessage - Stored timeout or a missing lookup result.
+ * @returns `true` for active messages without an existing cancellation request.
+ */
+function isActivePlannedMessage(plannedMessage: UserChatTimeoutRecord | null): plannedMessage is UserChatTimeoutRecord {
+    return Boolean(
+        plannedMessage &&
+            ACTIVE_PLANNED_MESSAGE_STATUSES.includes(plannedMessage.status) &&
+            !plannedMessage.cancelRequestedAt,
+    );
+}

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

@@ -0,0 +1,43 @@
+import type { ChatMessage } from '@promptbook-local/types';
+import { $randomBase58 } from '../../../../../src/utils/random/$randomBase58';
+import type { UserChatRecord } from '../userChat/UserChatRecord';
+import { mutateUserChat } from '../userChat/mutateUserChat';
+import { AGENT_GOAL_CHAT_MESSAGE_ID_LENGTH } from './agentGoalChatConstants';
+import { ensureAgentGoalChat } from './ensureAgentGoalChat';
+
+/**
+ * Appends one agent-authored note to the singleton goal chat of an agent.
+ *
+ * Goal chats are written only by the agent and by the server acting on its behalf, so every note is
+ * stored as a completed `AGENT` message.
+ *
+ * @param options - Target agent and note content.
+ * @returns Updated goal-chat record.
+ */
+export async function appendAgentGoalChatNote(options: {
+    readonly agentPermanentId: string;
+    readonly content: string;
+}): Promise<UserChatRecord> {
+    const goalChat = await ensureAgentGoalChat(options.agentPermanentId);
+    const nowIso = new Date().toISOString() as NonNullable<ChatMessage['createdAt']>;
+
+    return mutateUserChat({
+        userId: goalChat.userId,
+        agentPermanentId: goalChat.agentPermanentId,
+        chatId: goalChat.id,
+        mutate: (currentChat) => ({
+            messages: [
+                ...currentChat.messages,
+                {
+                    id: $randomBase58(AGENT_GOAL_CHAT_MESSAGE_ID_LENGTH),
+                    sender: 'AGENT',
+                    content: options.content,
+                    createdAt: nowIso,
+                    isComplete: true,
+                    lifecycleState: 'completed',
+                },
+            ],
+            lastMessageAt: nowIso,
+        }),
+    });
+}

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

@@ -0,0 +1,14 @@
+import { getCurrentUser } from '../getCurrentUser';
+
+/**
+ * Resolves whether the current request may read the goal chat of an agent.
+ *
+ * Goal chats expose the agent's own planning, so they follow exactly the same rule as the agent
+ * source book page (`/agents/<agentName>/book`): a signed-in user is required. Keeping the rule in
+ * one place makes the two surfaces impossible to drift apart.
+ *
+ * @returns `true` when the current identity may read agent goal chats.
+ */
+export async function canAccessAgentGoalChat(): Promise<boolean> {
+    return Boolean(await getCurrentUser());
+}

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

@@ -0,0 +1,92 @@
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * 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,
+                inspect existing planned messages with \`list_timeouts\`, and use \`set_timeout\` or
+                \`cancel_timeout\` to arrange the next useful wake-up without creating duplicates.
+            `,
+        );
+    }
+
+    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, act on it now when useful,
+            and arrange another goal-chat wake-up with \`set_timeout\` when future follow-up is needed.
+        `,
+    );
+}
+
+/**
+ * Builds the goal-chat note left when a planned message is scheduled.
+ *
+ * @param options - Planned-message identity, 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 message?: string | null;
+}): string {
+    const plannedMessage = options.message?.trim() || '';
+
+    return spaceTrim(
+        (block) => `
+            ⏳ I planned a message that will wake me up at ${options.dueAt}.
+
+            ${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,
+    });
+}