@promptbook/cli 0.114.0-5 → 0.114.0-7

package/apps/agents-server/src/database/migratePrefix.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import type { Client } from 'pg';
 import { importRuntimeModule } from './importRuntimeModule';
 import type { DatabaseMigrationAppliedBy, DatabaseMigrationLogger } from './runDatabaseMigrations';
@@ -219,42 +220,42 @@ export async function migratePrefix(options: MigratePrefixOptions): Promise<numb
  * @private function of runDatabaseMigrations
  */
 async function ensureMigrationsTableSchema(options: EnsureMigrationsTableSchemaOptions): Promise<void> {
-    await options.client.query(`
+    await options.client.query(spaceTrim(`
         CREATE TABLE IF NOT EXISTS ${options.migrationsTableIdentifier} (
             "filename" TEXT PRIMARY KEY,
             "appliedAt" TIMESTAMP WITH TIME ZONE DEFAULT now(),
             "appliedBy" TEXT NOT NULL DEFAULT '${options.manualAppliedByDefault}'
         );
-    `);
+    `));
 
-    await options.client.query(`
+    await options.client.query(spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ADD COLUMN IF NOT EXISTS "appliedBy" TEXT;
-    `);
+    `));
 
     await options.client.query(
-        `
+        spaceTrim(`
         UPDATE ${options.migrationsTableIdentifier}
         SET "appliedBy" = $1
         WHERE "appliedBy" IS NULL;
-        `,
+        `),
         [options.manualAppliedByDefault],
     );
 
-    await options.client.query(`
+    await options.client.query(spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ALTER COLUMN "appliedBy" SET DEFAULT '${options.manualAppliedByDefault}';
-    `);
+    `));
 
-    await options.client.query(`
+    await options.client.query(spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ALTER COLUMN "appliedBy" SET NOT NULL;
-    `);
+    `));
 
-    await options.client.query(`
+    await options.client.query(spaceTrim(`
         ALTER TABLE ${options.migrationsTableIdentifier}
         ENABLE ROW LEVEL SECURITY;
-    `);
+    `));
 }
 
 /**

package/apps/agents-server/src/database/migrations/2026-08-0100-agent-goal-chat-source.sql

@@ -0,0 +1,10 @@
+ALTER TABLE "prefix_UserChat"
+DROP CONSTRAINT IF EXISTS "prefix_UserChat_source_check";
+
+ALTER TABLE "prefix_UserChat"
+ADD CONSTRAINT "prefix_UserChat_source_check"
+CHECK ("source" IN ('WEB_UI', 'OPENAI_API', 'TEAM_MEMBER', 'EMAIL', 'AGENT_GOAL'));
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChat_agentPermanentId_goalSource_idx"
+    ON "prefix_UserChat" ("agentPermanentId")
+    WHERE "source" = 'AGENT_GOAL';

package/apps/agents-server/src/generated/reservedPaths.ts

@@ -1,43 +1,43 @@
 /**
- * Reserved paths that should not be treated as agent names.
- * This file is auto-generated by scripts/generate-reserved-paths.js
- *
- * ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
- *
- * @see /apps/agents-server/src/app - source directory for routes
- * @see /apps/agents-server/public - source directory for static files
- * @see /apps/agents-server/src/middleware.ts - where this is used
- */
-export const RESERVED_PATHS: readonly string[] = [
-    "_data",
-    "_next",
-    "admin",
-    "agents",
-    "api",
-    "dashboard",
-    "docs",
-    "embed",
-    "experiments",
-    "favicon.ico",
-    "fonts",
-    "humans.txt",
-    "logo-blue-white-256.png",
-    "manifest.webmanifest",
-    "openapi.json",
-    "promptbook-logo-blue.png",
-    "promptbook-logo-white.png",
-    "recycle-bin",
-    "restricted",
-    "robots.txt",
-    "s3",
-    "search",
-    "security.txt",
-    "sitemap.xml",
-    "sounds",
-    "story",
-    "superadmin",
-    "sw.js",
-    "swagger",
-    "system",
-    "test"
-] as const;
+     * Reserved paths that should not be treated as agent names.
+     * This file is auto-generated by scripts/generate-reserved-paths.js
+     *
+     * ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
+     *
+     * @see /apps/agents-server/src/app - source directory for routes
+     * @see /apps/agents-server/public - source directory for static files
+     * @see /apps/agents-server/src/middleware.ts - where this is used
+     */
+    export const RESERVED_PATHS: readonly string[] = [
+        "_data",
+        "_next",
+        "admin",
+        "agents",
+        "api",
+        "dashboard",
+        "docs",
+        "embed",
+        "experiments",
+        "favicon.ico",
+        "fonts",
+        "humans.txt",
+        "logo-blue-white-256.png",
+        "manifest.webmanifest",
+        "openapi.json",
+        "promptbook-logo-blue.png",
+        "promptbook-logo-white.png",
+        "recycle-bin",
+        "restricted",
+        "robots.txt",
+        "s3",
+        "search",
+        "security.txt",
+        "sitemap.xml",
+        "sounds",
+        "story",
+        "superadmin",
+        "sw.js",
+        "swagger",
+        "system",
+        "test"
+    ] as const;

package/apps/agents-server/src/languages/ServerTranslationKeys.ts

@@ -14,7 +14,15 @@ export const SERVER_TRANSLATION_KEYS = [
     'common.chat',
     'chat.answerDurationLabel',
     'common.book',
-    'common.timeouts',
+    'common.goalChat',
+    'goalChat.noticeTitle',
+    'goalChat.noticeDescription',
+    'goalChat.plannedMessagesTitle',
+    'goalChat.plannedMessagesEmptyLabel',
+    'goalChat.plannedMessagesLoadErrorLabel',
+    'goalChat.plannedMessageDefaultLabel',
+    'goalChat.plannedMessageCancelLabel',
+    'goalChat.plannedMessageCancellingLabel',
     'common.projects',
     'common.more',
     'chatEnterBehavior.sectionEyebrow',

package/apps/agents-server/src/languages/translations/czech.yaml

@@ -8,7 +8,15 @@ common.profile: Profil
 common.chat: Chat
 chat.answerDurationLabel: 'Odpověď za {duration}'
 common.book: Book
-common.timeouts: Časovače
+common.goalChat: Cíl
+goalChat.noticeTitle: Toto je cílový chat agenta
+goalChat.noticeDescription: Agent si sem píše sám a plánuje práci ke svému cíli, proto je toto vlákno pro lidi jen ke čtení.
+goalChat.plannedMessagesTitle: Naplánované zprávy
+goalChat.plannedMessagesEmptyLabel: Žádné naplánované zprávy. Agent se probudí, až mu někdo napíše.
+goalChat.plannedMessagesLoadErrorLabel: Naplánované zprávy se nepodařilo načíst.
+goalChat.plannedMessageDefaultLabel: Naplánované probuzení
+goalChat.plannedMessageCancelLabel: Zrušit
+goalChat.plannedMessageCancellingLabel: Ruším
 common.projects: Projekty
 common.more: Více
 chatEnterBehavior.sectionEyebrow: Klávesové zkratky

package/apps/agents-server/src/languages/translations/english.yaml

@@ -8,7 +8,15 @@ common.profile: Profile
 common.chat: Chat
 chat.answerDurationLabel: '{duration} to answer'
 common.book: Book
-common.timeouts: Timeouts
+common.goalChat: Goal
+goalChat.noticeTitle: This is the agent's goal chat
+goalChat.noticeDescription: The agent writes here on its own to plan work towards its goal, so this thread is read-only for people.
+goalChat.plannedMessagesTitle: Planned messages
+goalChat.plannedMessagesEmptyLabel: No planned messages. The agent will wake up only when someone writes to it.
+goalChat.plannedMessagesLoadErrorLabel: Failed to load planned messages.
+goalChat.plannedMessageDefaultLabel: Planned wake-up
+goalChat.plannedMessageCancelLabel: Cancel
+goalChat.plannedMessageCancellingLabel: Cancelling
 common.projects: Projects
 common.more: More
 chatEnterBehavior.sectionEyebrow: Keybindings

package/apps/agents-server/src/message-providers/email/stalwart/parseInboundStalwartEmail.ts

@@ -14,6 +14,21 @@ export type ParsedInboundStalwartEmail = {
     readonly queueId: string | null;
 };
 
+/**
+ * Rebuilds one RFC 5322 header line from a Stalwart header tuple.
+ *
+ * Stalwart reports every header exactly as it stood on the wire, so its value already carries the
+ * space after the colon and its own terminating line break, while folded values keep their inner
+ * line breaks. Emitting such a value verbatim would write `Name:  value` with a doubled space and,
+ * once the tuples are joined with another line break, an empty line after every header - which ends
+ * the header block right after the first one and turns all remaining headers into message body.
+ */
+function createInboundStalwartHeaderLine([name, value]: readonly [string, string]): string {
+    const headerValue = value.replace(/[\r\n]+$/, '');
+    const separator = /^[ \t]/.test(headerValue) ? '' : ' ';
+    return `${name}:${separator}${headerValue}`;
+}
+
 /**
  * Reconstructs an RFC 5322 message from Stalwart's DATA-stage MTA hook payload.
  */
@@ -38,7 +53,7 @@ export async function parseInboundStalwartEmail(
         .map((recipient) => recipient.address.trim())
         .filter(Boolean);
 
-    if (!headers || typeof contents !== 'string' || envelopeRecipients.length === 0) {
+    if (!headers?.length || typeof contents !== 'string' || envelopeRecipients.length === 0) {
         throw new ParseError(
             spaceTrim(`
                 Stalwart sent an incomplete DATA-stage MTA hook payload.
@@ -49,7 +64,7 @@ export async function parseInboundStalwartEmail(
     }
 
     const rawEmail = `${[...(payload.message?.serverHeaders || []), ...headers]
-        .map(([name, value]) => `${name}: ${value}`)
+        .map(createInboundStalwartHeaderLine)
         .join('\r\n')}\r\n\r\n${contents}`;
 
     let email: InboundEmail;

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

@@ -0,0 +1,9 @@
+/**
+ * Title stored on every agent goal chat.
+ */
+export const AGENT_GOAL_CHAT_TITLE = 'Goal';
+
+/**
+ * Length of generated goal-chat message ids.
+ */
+export const AGENT_GOAL_CHAT_MESSAGE_ID_LENGTH = 14;

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

@@ -0,0 +1,28 @@
+/**
+ * Prefix of every goal-chat id.
+ *
+ * Goal-chat ids are derived deterministically from the agent permanent id so that exactly one
+ * goal chat can ever exist per agent, and so that any layer holding only a `chatId`
+ * (SQL task queries, admin task rows, UI rows) can recognize a goal chat without extra lookups.
+ */
+export const AGENT_GOAL_CHAT_ID_PREFIX = 'goal-';
+
+/**
+ * Builds the deterministic singleton goal-chat id of one agent.
+ *
+ * @param agentPermanentId - Permanent id of the agent owning the goal chat.
+ * @returns Stable goal-chat id.
+ */
+export function buildAgentGoalChatId(agentPermanentId: string): string {
+    return `${AGENT_GOAL_CHAT_ID_PREFIX}${agentPermanentId}`;
+}
+
+/**
+ * Returns `true` when one chat id belongs to an agent goal chat.
+ *
+ * @param chatId - Chat id to inspect.
+ * @returns `true` for goal chats.
+ */
+export function isAgentGoalChatId(chatId: string | null | undefined): boolean {
+    return typeof chatId === 'string' && chatId.startsWith(AGENT_GOAL_CHAT_ID_PREFIX);
+}

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,69 @@
+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;
+}): string {
+    if (options.event === 'CREATED') {
+        return spaceTrim(`
+            🌱 I was created as \`${options.agentName}\`.
+
+            From now on I keep my own plans towards my goal in this thread.
+        `);
+    }
+
+    return spaceTrim(`
+        📝 My book was updated, so \`${options.agentName}\` may work differently from now on.
+
+        I should re-check my plans towards my goal against the new book.
+    `);
+}
+
+/**
+ * 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/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,36 @@
+import { serializeError } from '@promptbook-local/utils';
+import { appendAgentGoalChatNote } from './appendAgentGoalChatNote';
+import {
+    createAgentGoalChatLifecycleNoteContent,
+    type AgentGoalChatLifecycleEvent,
+} from './createAgentGoalChatNoteContent';
+
+/**
+ * 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;
+}): Promise<void> {
+    try {
+        await appendAgentGoalChatNote({
+            agentPermanentId: options.agentPermanentId,
+            content: createAgentGoalChatLifecycleNoteContent({
+                event: options.event,
+                agentName: options.agentName,
+            }),
+        });
+    } 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;
+}