@promptbook/cli 0.114.0-5 → 0.114.0-50

package/apps/agents-server/src/tools/agentGoalChatTimeoutToolFunctions.ts

@@ -0,0 +1,249 @@
+import { spaceTrim } from 'spacetrim';
+import { describeAgentPlannedMessageSchedule } from '../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
+import type { string_javascript_name } from '../../../../src/types/string_person_fullname';
+import type { ToolFunction } from '../../../../src/scripting/javascript/JavascriptExecutionToolsOptions';
+import { createToolExecutionEnvelope } from '../../../../src/commitments/_common/toolExecutionEnvelope';
+import { readToolRuntimeContextFromToolArgs } from '../../../../src/commitments/_common/toolRuntimeContext';
+import { ParseError } from '../../../../src/errors/ParseError';
+import {
+    createAgentGoalChatPlannedMessageActions,
+    type AgentGoalChatPlannedMessageDependencies,
+    type AgentGoalChatPlannedMessageItem,
+    type UpdateAgentGoalChatPlannedMessageResult,
+} from '../utils/agentGoalChat/agentGoalChatPlannedMessageActions';
+import { AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES } from './agentGoalChatTimeoutTools';
+
+/**
+ * Maximum number of planned messages repeated in the assistant-visible list summary.
+ */
+const MAX_ASSISTANT_VISIBLE_PLANNED_MESSAGES = 20;
+
+/**
+ * Raw model-supplied arguments accepted by planned-message tools.
+ */
+type AgentGoalChatTimeoutToolArguments = Record<string, unknown>;
+
+/**
+ * Creates tool functions that schedule and manage future messages in an agent's singleton goal chat.
+ *
+ * @param dependencyOverrides - Optional persistence substitutions used by focused tests.
+ * @returns Script-callable planned-message functions keyed by their model-facing names.
+ */
+export function createAgentGoalChatTimeoutToolFunctions(
+    dependencyOverrides: Partial<AgentGoalChatPlannedMessageDependencies> = {},
+): Record<string_javascript_name, ToolFunction> {
+    const actions = createAgentGoalChatPlannedMessageActions(dependencyOverrides);
+
+    return {
+        async [AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.set](
+            toolArguments: AgentGoalChatTimeoutToolArguments,
+        ): Promise<string> {
+            try {
+                const agentPermanentId = resolveAgentPermanentId(toolArguments);
+                const result = await actions.set({
+                    agentPermanentId,
+                    ...createPlannedMessageScheduleArguments(toolArguments),
+                    message: toolArguments.message,
+                });
+
+                return createToolExecutionEnvelope({
+                    assistantMessage: `Planned message ${JSON.stringify(
+                        result.timeoutId,
+                    )} ${describeAgentPlannedMessageSchedule(result)}.`,
+                    toolResult: result,
+                });
+            } catch (error) {
+                return serializeToolError('set', error);
+            }
+        },
+
+        async [AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.update](
+            toolArguments: AgentGoalChatTimeoutToolArguments,
+        ): Promise<string> {
+            try {
+                const agentPermanentId = resolveAgentPermanentId(toolArguments);
+                const result = await actions.update({
+                    agentPermanentId,
+                    timeoutId: toolArguments.timeoutId,
+                    ...createPlannedMessageScheduleArguments(toolArguments),
+                    ...(toolArguments.message === undefined ? {} : { message: toolArguments.message }),
+                });
+
+                return createToolExecutionEnvelope({
+                    assistantMessage: createUpdatedPlannedMessageAssistantMessage(result),
+                    toolResult: result,
+                });
+            } catch (error) {
+                return serializeToolError('update', error);
+            }
+        },
+
+        async [AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.list](
+            toolArguments: AgentGoalChatTimeoutToolArguments,
+        ): Promise<string> {
+            try {
+                const agentPermanentId = resolveAgentPermanentId(toolArguments);
+                const result = await actions.list({
+                    agentPermanentId,
+                    isIncludingFinished: toolArguments.isIncludingFinished,
+                    limit: toolArguments.limit,
+                });
+
+                return createToolExecutionEnvelope({
+                    assistantMessage: createPlannedMessagesAssistantSummary(result.items),
+                    toolResult: result,
+                });
+            } catch (error) {
+                return serializeToolError('list', error);
+            }
+        },
+
+        async [AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.cancel](
+            toolArguments: AgentGoalChatTimeoutToolArguments,
+        ): Promise<string> {
+            try {
+                const agentPermanentId = resolveAgentPermanentId(toolArguments);
+                const result = await actions.cancel({
+                    agentPermanentId,
+                    timeoutId: toolArguments.timeoutId,
+                });
+
+                return createToolExecutionEnvelope({
+                    assistantMessage:
+                        result.status === 'cancelled'
+                            ? `Cancelled planned message ${JSON.stringify(result.timeoutId)}.`
+                            : 'The planned message was already inactive or was not found.',
+                    toolResult: result,
+                });
+            } catch (error) {
+                return serializeToolError('cancel', error);
+            }
+        },
+    };
+}
+
+/**
+ * Production planned-message functions registered in the Agents Server script runtime.
+ */
+export const AGENT_GOAL_CHAT_TIMEOUT_TOOL_FUNCTIONS = createAgentGoalChatTimeoutToolFunctions();
+
+/**
+ * Resolves the active agent identity from hidden server runtime context.
+ *
+ * @param toolArguments - Raw tool arguments containing the hidden runtime payload.
+ * @returns Permanent id of the agent that owns the singleton goal chat.
+ */
+function resolveAgentPermanentId(toolArguments: AgentGoalChatTimeoutToolArguments): string {
+    const runtimeContext = readToolRuntimeContextFromToolArgs(toolArguments);
+    const candidateAgentIds = [
+        runtimeContext?.chat?.agentId,
+        runtimeContext?.memory?.agentId,
+        runtimeContext?.spawn?.parentAgentId,
+    ];
+
+    for (const candidateAgentId of candidateAgentIds) {
+        if (typeof candidateAgentId === 'string' && candidateAgentId.trim().length > 0) {
+            return candidateAgentId.trim();
+        }
+    }
+
+    throw new ParseError(
+        spaceTrim(`
+            Planned messages are unavailable because the active agent identity is missing.
+
+            **Note:** This tool can only run inside an Agents Server agent invocation.
+        `),
+    );
+}
+
+/**
+ * Builds concise text shown to the model for a planned-message listing.
+ *
+ * @param plannedMessages - Ordered planned-message summaries returned by the shared action.
+ * @returns Assistant-visible listing summary.
+ */
+function createPlannedMessagesAssistantSummary(
+    plannedMessages: ReadonlyArray<AgentGoalChatPlannedMessageItem>,
+): string {
+    if (plannedMessages.length === 0) {
+        return 'There are no matching planned messages.';
+    }
+
+    const visiblePlannedMessages = plannedMessages.slice(0, MAX_ASSISTANT_VISIBLE_PLANNED_MESSAGES);
+    const summaryRows = visiblePlannedMessages.map((plannedMessage, index) => {
+        const message = plannedMessage.message?.trim() || 'Wake up and continue working towards the current goal.';
+        return `${index + 1}. ${plannedMessage.timeoutId} ${describeAgentPlannedMessageSchedule(
+            plannedMessage,
+        )}: ${message}`;
+    });
+    const hiddenPlannedMessageCount = plannedMessages.length - visiblePlannedMessages.length;
+
+    if (hiddenPlannedMessageCount > 0) {
+        summaryRows.push(`...and ${hiddenPlannedMessageCount} more.`);
+    }
+
+    return spaceTrim(
+        (block) => `
+            Found ${plannedMessages.length} planned message${plannedMessages.length === 1 ? '' : 's'}:
+
+            ${block(summaryRows.join('\n'))}
+        `,
+    );
+}
+
+/**
+ * Builds the text shown to the model after one re-planning attempt.
+ *
+ * @param result - Result of the shared re-planning action.
+ * @returns Assistant-visible sentence telling what really happened to the planned message.
+ */
+function createUpdatedPlannedMessageAssistantMessage(result: UpdateAgentGoalChatPlannedMessageResult): string {
+    if (result.status === 'updated') {
+        return `Planned message ${JSON.stringify(result.timeoutId)} now ${describeAgentPlannedMessageSchedule(
+            result,
+        )}.`;
+    }
+
+    if (result.status === 'busy') {
+        return `Planned message ${JSON.stringify(
+            result.timeoutId,
+        )} is waking you right now and was left unchanged, so change it again afterwards.`;
+    }
+
+    return 'The planned message was already inactive or was not found.';
+}
+
+/**
+ * Collects the schedule arguments of one planned-message tool call.
+ *
+ * An argument the model did not pass stays absent, so an update changes only the fields it names.
+ *
+ * @param toolArguments - Raw arguments of the tool call.
+ * @returns Schedule fields passed to the shared planned-message actions.
+ */
+function createPlannedMessageScheduleArguments(
+    toolArguments: AgentGoalChatTimeoutToolArguments,
+): AgentGoalChatTimeoutToolArguments {
+    return {
+        ...(toolArguments.milliseconds === undefined ? {} : { milliseconds: toolArguments.milliseconds }),
+        ...(toolArguments.cronExpression === undefined ? {} : { cronExpression: toolArguments.cronExpression }),
+        ...(toolArguments.startsAt === undefined ? {} : { startsAt: toolArguments.startsAt }),
+        ...(toolArguments.endsAt === undefined ? {} : { endsAt: toolArguments.endsAt }),
+        ...(toolArguments.maxRunCount === undefined ? {} : { maxRunCount: toolArguments.maxRunCount }),
+    };
+}
+
+/**
+ * Serializes one caught tool failure without crashing the surrounding model run.
+ *
+ * @param action - Planned-message action that failed.
+ * @param error - Caught failure.
+ * @returns JSON result readable by the model and persisted tool-call inspector.
+ */
+function serializeToolError(action: 'set' | 'update' | 'list' | 'cancel', error: unknown): string {
+    return JSON.stringify({
+        action,
+        status: 'error',
+        message: error instanceof Error ? error.message : String(error),
+    });
+}

package/apps/agents-server/src/tools/agentGoalChatTimeoutTools.ts

@@ -0,0 +1,147 @@
+import type { LlmToolDefinition } from '../../../../src/types/LlmToolDefinition';
+
+/**
+ * Tool names used by the agent-owned planned-message capability.
+ */
+export const AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES = {
+    set: 'set_timeout',
+    update: 'update_timeout',
+    list: 'list_timeouts',
+    cancel: 'cancel_timeout',
+} as const;
+
+/**
+ * Schedule parameters shared by the planning and re-planning tools.
+ *
+ * One planned message follows exactly one recurrence rule, bounded by an optional date window and an
+ * optional total number of runs, so both tools describe the very same fields.
+ */
+const AGENT_GOAL_CHAT_TIMEOUT_SCHEDULE_PARAMETERS = {
+    milliseconds: {
+        type: 'number',
+        description:
+            'Repeat interval in milliseconds between two wake-ups by this planned message (at least 60000). Use either this or `cronExpression`.',
+    },
+    cronExpression: {
+        type: 'string',
+        description:
+            'Five-field cron expression such as `0 9 * * 1-5`, evaluated in the server time zone. Use either this or `milliseconds`.',
+    },
+    maxRunCount: {
+        type: 'number',
+        description:
+            'How many times in total this planned message wakes you, for example 1 for a one-off message. Leave it out to repeat until cancelled.',
+    },
+    startsAt: {
+        type: 'string',
+        description:
+            'ISO date before which the planned message never wakes you, for example `2026-09-01T08:00:00.000Z`.',
+    },
+    endsAt: {
+        type: 'string',
+        description: 'ISO date after which the planned message stops waking you and finishes on its own.',
+    },
+} as const;
+
+/**
+ * Adds the Agents Server planned-message tools while preserving already registered tools.
+ *
+ * Planned messages always belong to the agent's singleton goal chat. This lets an agent plan
+ * follow-up work from any conversation without tying the future wake-up to a human's thread.
+ *
+ * @param existingTools - Tool definitions already available in the current chat runtime.
+ * @returns Tool definitions including planned-message scheduling, listing, and cancellation.
+ */
+export function createAgentGoalChatTimeoutTools(
+    existingTools: ReadonlyArray<LlmToolDefinition> = [],
+): Array<LlmToolDefinition> {
+    const tools = [...existingTools];
+
+    if (!tools.some((tool) => tool.name === AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.set)) {
+        tools.push({
+            name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.set,
+            description:
+                'Plan a message that wakes you in your singleton goal chat, like `setInterval`. Use this for useful autonomous follow-up towards your current goal; the wake-up is not tied to the human conversation where you schedule it, and it keeps repeating until its schedule is over or you cancel it. Do not plan a message that matches one you already planned.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    ...AGENT_GOAL_CHAT_TIMEOUT_SCHEDULE_PARAMETERS,
+                    message: {
+                        type: 'string',
+                        description:
+                            'The concrete future instruction or reminder that will be delivered in your goal chat.',
+                    },
+                },
+                required: ['message'],
+                additionalProperties: false,
+            },
+        });
+    }
+
+    if (!tools.some((tool) => tool.name === AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.update)) {
+        tools.push({
+            name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.update,
+            description:
+                'Change the schedule or the text of one planned goal-chat message without losing its identity. Pass only the fields you want to change; every other field keeps its current value, and `null` removes a bound such as `endsAt`. Prefer this over cancelling and planning the same message again.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    timeoutId: {
+                        type: 'string',
+                        description: 'Identifier returned by `set_timeout` or `list_timeouts`.',
+                    },
+                    ...AGENT_GOAL_CHAT_TIMEOUT_SCHEDULE_PARAMETERS,
+                    message: {
+                        type: 'string',
+                        description: 'New instruction delivered by this planned message in your goal chat.',
+                    },
+                },
+                required: ['timeoutId'],
+                additionalProperties: false,
+            },
+        });
+    }
+
+    if (!tools.some((tool) => tool.name === AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.list)) {
+        tools.push({
+            name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.list,
+            description:
+                'List your planned goal-chat messages, including their identifiers, whole schedules, and next execution times, across every conversation in which you were invoked. Messages which already finished are left out. Keep the listed messages as they are unless they no longer match your goal.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    isIncludingFinished: {
+                        type: 'boolean',
+                        description: 'Set to true only when completed, failed, and cancelled messages are also needed.',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum number of planned messages to return (default 20, maximum 100).',
+                    },
+                },
+                additionalProperties: false,
+            },
+        });
+    }
+
+    if (!tools.some((tool) => tool.name === AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.cancel)) {
+        tools.push({
+            name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.cancel,
+            description:
+                'Stop one planned goal-chat message by its timeout identifier, which also stops all of its remaining repetitions. List planned messages first when the identifier is not known.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    timeoutId: {
+                        type: 'string',
+                        description: 'Identifier returned by `set_timeout` or `list_timeouts`.',
+                    },
+                },
+                required: ['timeoutId'],
+                additionalProperties: false,
+            },
+        });
+    }
+
+    return tools;
+}

package/apps/agents-server/src/tools/createServerChatRuntimeTools.ts

@@ -0,0 +1,20 @@
+import type { ChatMessage, LlmToolDefinition } from '@promptbook-local/types';
+import { createAgentGoalChatTimeoutTools } from './agentGoalChatTimeoutTools';
+import { createAgentProgressTools } from './createAgentProgressTools';
+import { createChatAttachmentTools } from './createChatAttachmentTools';
+
+/**
+ * Composes the runtime-only tools shared by Agents Server web chat execution paths.
+ *
+ * @param attachments - Files attached to the current chat turn.
+ * @param existingTools - Additional request-scoped tools to preserve.
+ * @returns Deduplicated server runtime tool definitions.
+ */
+export function createServerChatRuntimeTools(
+    attachments: ChatMessage['attachments'] = [],
+    existingTools: ReadonlyArray<LlmToolDefinition> = [],
+): Array<LlmToolDefinition> {
+    return createAgentProgressTools(
+        createAgentGoalChatTimeoutTools(createChatAttachmentTools(existingTools, attachments || [])),
+    );
+}

package/apps/agents-server/src/tools/getAllToolFunctionsForServer.ts

@@ -6,6 +6,7 @@ import {
 import type { ToolFunction } from '../../../../src/scripting/javascript/JavascriptExecutionToolsOptions';
 import { getAllCommitmentsToolFunctionsForNode } from '../../../../src/commitments/_common/getAllCommitmentsToolFunctionsForNode';
 import { agent_progress } from './agent_progress';
+import { AGENT_GOAL_CHAT_TIMEOUT_TOOL_FUNCTIONS } from './agentGoalChatTimeoutToolFunctions';
 import { createChatAttachmentToolFunctions } from './createChatAttachmentToolFunctions';
 
 /**
@@ -13,6 +14,7 @@ import { createChatAttachmentToolFunctions } from './createChatAttachmentToolFun
  */
 const SERVER_TOOL_FUNCTIONS: CommitmentToolFunctions = {
     ...createChatAttachmentToolFunctions(),
+    ...AGENT_GOAL_CHAT_TIMEOUT_TOOL_FUNCTIONS,
     agent_progress,
 };
 

package/apps/agents-server/src/tools/mapRegisteredServerContexts.ts

@@ -1,10 +1,10 @@
 import {
     createServerPublicUrl,
-    listRegisteredServersUsingServiceRole,
     normalizeServerDomain,
     resolveRegisteredServerByHost,
     type ServerRecord,
 } from '../utils/serverRegistry';
+import { listRegisteredServersUsingServiceRole } from '../utils/serverRegistryNode';
 import type { ProvidedServer } from './$provideServer';
 import { runWithServerContextOverride } from './serverContextOverride';
 

package/apps/agents-server/src/types/swagger-ui-dist.d.ts

@@ -0,0 +1,5 @@
+declare module 'swagger-ui-dist/swagger-ui-bundle.js' {
+    import { SwaggerUIBundle } from 'swagger-ui-dist';
+
+    export default SwaggerUIBundle;
+}

package/apps/agents-server/src/utils/adminEntityLookups/loadAgentNamesByPermanentId.ts

@@ -0,0 +1,45 @@
+import { $getTableName } from '@/src/database/$getTableName';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import type { AgentsServerDatabase } from '@/src/database/schema';
+
+/**
+ * Minimal agent lookup row needed to name the agent behind one admin row.
+ *
+ * @private type of `loadAgentNamesByPermanentId`
+ */
+type AgentNameLookupRow = Pick<AgentsServerDatabase['public']['Tables']['Agent']['Row'], 'permanentId' | 'agentName'>;
+
+/**
+ * Loads agent names keyed by permanent id, for admin listings that only store the permanent id.
+ *
+ * @param agentPermanentIds - Permanent ids of the agents to name, duplicates allowed.
+ * @returns Agent names keyed by permanent id, empty when nothing was asked for.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function loadAgentNamesByPermanentId(
+    agentPermanentIds: ReadonlyArray<string>,
+): Promise<Map<string, string | null>> {
+    const uniqueAgentPermanentIds = [...new Set(agentPermanentIds)].filter(Boolean);
+
+    if (uniqueAgentPermanentIds.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', uniqueAgentPermanentIds);
+
+    if (error) {
+        throw new Error(`Failed to load admin listing agents: ${error.message}`);
+    }
+
+    return new Map(
+        ((data || []) as Array<AgentNameLookupRow>)
+            .filter((agentRow): agentRow is AgentNameLookupRow & { permanentId: string } => Boolean(agentRow.permanentId))
+            .map((agentRow) => [agentRow.permanentId, agentRow.agentName] as const),
+    );
+}

package/apps/agents-server/src/utils/adminEntityLookups/loadUsernamesByUserId.ts

@@ -0,0 +1,36 @@
+import { $getTableName } from '@/src/database/$getTableName';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import type { AgentsServerDatabase } from '@/src/database/schema';
+
+/**
+ * Minimal user lookup row needed to name the owner of one admin row.
+ *
+ * @private type of `loadUsernamesByUserId`
+ */
+type UsernameLookupRow = Pick<AgentsServerDatabase['public']['Tables']['User']['Row'], 'id' | 'username'>;
+
+/**
+ * Loads usernames keyed by user id, for admin listings that only store the owning user id.
+ *
+ * @param userIds - Ids of the users to name, duplicates allowed.
+ * @returns Usernames keyed by user id, empty when nothing was asked for.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function loadUsernamesByUserId(userIds: ReadonlyArray<number>): Promise<Map<number, string>> {
+    const uniqueUserIds = [...new Set(userIds)];
+
+    if (uniqueUserIds.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', uniqueUserIds);
+
+    if (error) {
+        throw new Error(`Failed to load admin listing users: ${error.message}`);
+    }
+
+    return new Map(((data || []) as Array<UsernameLookupRow>).map((userRow) => [userRow.id, userRow.username] as const));
+}

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

@@ -0,0 +1,2 @@
+export { loadAgentNamesByPermanentId } from './adminEntityLookups/loadAgentNamesByPermanentId';
+export { loadUsernamesByUserId } from './adminEntityLookups/loadUsernamesByUserId';

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

@@ -0,0 +1,14 @@
+/**
+ * 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;
+
+/**
+ * Internal endpoint used by managed coding agents to plan goal-chat messages.
+ */
+export const AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH = '/api/internal/agent-goal-chat-planned-messages';

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);
+}