@promptbook/cli 0.114.0-3 → 0.114.0-30

package/apps/agents-server/src/middleware/createMiddlewareRequestContext/loadRegisteredServers.ts

@@ -1,4 +1,6 @@
+import { isAgentsServerSqliteMode } from '../../database/agentsServerDatabaseMode';
 import {
+    listEnvironmentRegisteredServers,
     listRegisteredServersUsingServiceRole,
     type ServerRecord,
 } from '../../utils/serverRegistry';
@@ -12,6 +14,12 @@ import {
  */
 export async function loadRegisteredServers(): Promise<Array<ServerRecord>> {
     try {
+        if (isAgentsServerSqliteMode()) {
+            // Note: Edge middleware cannot open the standalone SQLite registry. `SERVERS`
+            //       supplies the domain list required for its host-routing decisions.
+            return listEnvironmentRegisteredServers();
+        }
+
         return await listRegisteredServersUsingServiceRole();
     } catch (error) {
         console.error('Error loading server registry in middleware:', error);

package/apps/agents-server/src/tools/$provideOpenAiAgentKitExecutionToolsForServer.ts

@@ -1,21 +1,7 @@
 'use server';
 
-import {
-    setMemoryToolRuntimeAdapter,
-    type MemoryToolRecord,
-    type MemoryToolRuntimeContext,
-} from '../../../../src/commitments/MEMORY/MEMORY';
 import { OpenAiAgentKitExecutionTools } from '../../../../src/llm-providers/openai/OpenAiAgentKitExecutionTools';
 import { JavascriptExecutionTools } from '../../../../src/scripting/javascript/JavascriptExecutionTools';
-import { configureTimeoutToolRuntimeAdapterForServer } from './configureTimeoutToolRuntimeAdapterForServer';
-import {
-    createUserMemory,
-    deleteUserMemory,
-    findUserMemoryRecordById,
-    listUserMemories,
-    type UserMemoryRecord,
-    updateUserMemory,
-} from '../utils/userMemory';
 import { getAllToolFunctionsForServer } from './getAllToolFunctionsForServer';
 
 /**
@@ -25,187 +11,10 @@ import { getAllToolFunctionsForServer } from './getAllToolFunctionsForServer';
  */
 let llmExecutionTools: null | OpenAiAgentKitExecutionTools = null;
 
-/**
- * Converts user memory rows to tool records.
- */
-function mapUserMemoryRecordToToolRecord(record: UserMemoryRecord): MemoryToolRecord {
-    return {
-        id: record.id.toString(),
-        content: record.content,
-        isGlobal: record.isGlobal,
-        createdAt: record.createdAt,
-        updatedAt: record.updatedAt,
-    };
-}
-
-/**
- * Creates a memory runtime adapter backed by Agents Server database.
- */
-function createMemoryRuntimeAdapter() {
-    const parseMemoryId = (value: unknown): number => {
-        const parsed = Number.parseInt(String(value ?? ''), 10);
-        if (!Number.isFinite(parsed) || parsed <= 0) {
-            throw new Error('Memory id is required.');
-        }
-        return parsed;
-    };
-
-    const normalizeContent = (value: unknown): string => {
-        const content = typeof value === 'string' ? value.trim() : '';
-        if (!content) {
-            throw new Error('Memory content is required.');
-        }
-        return content;
-    };
-
-    const ensureAgentPermanentId = (
-        runtimeContext: MemoryToolRuntimeContext,
-        fallback?: string | null,
-    ): string => {
-        if (runtimeContext.agentId) {
-            return runtimeContext.agentId;
-        }
-
-        if (fallback) {
-            return fallback;
-        }
-
-        throw new Error('Memory is unavailable because agent context is missing.');
-    };
-
-    return {
-        async retrieveMemories(
-            args: { query?: string; limit?: number },
-            runtimeContext: MemoryToolRuntimeContext,
-        ): Promise<MemoryToolRecord[]> {
-            if (!runtimeContext.userId) {
-                return [];
-            }
-
-            const records = await listUserMemories({
-                userId: runtimeContext.userId,
-                agentPermanentId: runtimeContext.agentId,
-                includeGlobal: true,
-                search: args.query,
-                limit: args.limit ?? 5,
-            });
-
-            return records.map(mapUserMemoryRecordToToolRecord);
-        },
-        async storeMemory(
-            args: { content: string; isGlobal: boolean },
-            runtimeContext: MemoryToolRuntimeContext,
-        ): Promise<MemoryToolRecord> {
-            if (!runtimeContext.userId) {
-                throw new Error('Memory is unavailable because user is not authenticated.');
-            }
-
-            const content = normalizeContent(args.content);
-            const isGlobal = args.isGlobal === true;
-            const agentPermanentId = isGlobal ? null : ensureAgentPermanentId(runtimeContext);
-
-            const record = await createUserMemory({
-                userId: runtimeContext.userId,
-                content,
-                isGlobal,
-                agentPermanentId,
-            });
-
-            return mapUserMemoryRecordToToolRecord(record);
-        },
-        async updateMemory(
-            args: { memoryId: unknown; content: unknown; isGlobal?: unknown },
-            runtimeContext: MemoryToolRuntimeContext,
-        ): Promise<MemoryToolRecord> {
-            if (!runtimeContext.userId) {
-                throw new Error('Memory is unavailable because user is not authenticated.');
-            }
-
-            const memoryId = parseMemoryId(args.memoryId);
-            const content = normalizeContent(args.content);
-
-            const existingMemory = await findUserMemoryRecordById({
-                userId: runtimeContext.userId,
-                memoryId,
-            });
-
-            if (!existingMemory) {
-                throw new Error('Memory not found.');
-            }
-
-            if (
-                !existingMemory.isGlobal &&
-                existingMemory.agentPermanentId &&
-                runtimeContext.agentId !== existingMemory.agentPermanentId
-            ) {
-                throw new Error('Memory belongs to another agent.');
-            }
-
-            const requestedGlobal = typeof args.isGlobal === 'boolean' ? args.isGlobal : undefined;
-            const finalIsGlobal = requestedGlobal ?? existingMemory.isGlobal;
-
-            let agentPermanentId: string | null = null;
-            if (!finalIsGlobal) {
-                agentPermanentId = ensureAgentPermanentId(runtimeContext, existingMemory.agentPermanentId);
-            }
-
-            const record = await updateUserMemory({
-                userId: runtimeContext.userId,
-                memoryId,
-                content,
-                isGlobal: finalIsGlobal,
-                agentPermanentId,
-            });
-
-            return mapUserMemoryRecordToToolRecord(record);
-        },
-        async deleteMemory(
-            args: { memoryId: unknown },
-            runtimeContext: MemoryToolRuntimeContext,
-        ): Promise<{ id?: string }> {
-            if (!runtimeContext.userId) {
-                throw new Error('Memory is unavailable because user is not authenticated.');
-            }
-
-            const memoryId = parseMemoryId(args.memoryId);
-            const existingMemory = await findUserMemoryRecordById({
-                userId: runtimeContext.userId,
-                memoryId,
-            });
-
-            if (!existingMemory) {
-                throw new Error('Memory not found.');
-            }
-
-            if (
-                !existingMemory.isGlobal &&
-                existingMemory.agentPermanentId &&
-                runtimeContext.agentId !== existingMemory.agentPermanentId
-            ) {
-                throw new Error('Memory belongs to another agent.');
-            }
-
-            const deleted = await deleteUserMemory({
-                userId: runtimeContext.userId,
-                memoryId,
-            });
-
-            if (!deleted) {
-                throw new Error('Memory not found.');
-            }
-
-            return { id: memoryId.toString() };
-        },
-    };
-}
-
 /**
  * Provides a cached OpenAiAgentKitExecutionTools instance for the Agents Server.
  */
 export async function $provideOpenAiAgentKitExecutionToolsForServer(): Promise<OpenAiAgentKitExecutionTools> {
-    setMemoryToolRuntimeAdapter(createMemoryRuntimeAdapter());
-    configureTimeoutToolRuntimeAdapterForServer();
-
     const isVerbose = true; // <- TODO: [🤰] Pass
 
     if (llmExecutionTools !== null) {

package/apps/agents-server/src/tools/$provideOpenAiAssistantExecutionToolsForServer.ts

@@ -2,7 +2,6 @@
 
 import { OpenAiAssistantExecutionTools } from '@promptbook-local/openai';
 import { JavascriptExecutionTools } from '../../../../src/scripting/javascript/JavascriptExecutionTools';
-import { configureTimeoutToolRuntimeAdapterForServer } from './configureTimeoutToolRuntimeAdapterForServer';
 import { getAllToolFunctionsForServer } from './getAllToolFunctionsForServer';
 
 /**
@@ -16,8 +15,6 @@ let llmExecutionTools: null | OpenAiAssistantExecutionTools = null;
  * [🐱‍🚀]
  */
 export async function $provideOpenAiAssistantExecutionToolsForServer(): Promise<OpenAiAssistantExecutionTools> {
-    configureTimeoutToolRuntimeAdapterForServer();
-
     // TODO: [🐱‍🚀] [🌕] DRY
     const isVerbose = true; // <- TODO: [🐱‍🚀] Pass
 

package/apps/agents-server/src/tools/$provideServer.ts

@@ -3,7 +3,8 @@ import { headers } from 'next/headers';
 import { cache } from 'react';
 import { isAgentsServerSqliteMode } from '../database/agentsServerDatabaseMode';
 import { resolveInternalServerOrigin } from '../utils/resolveInternalServerOrigin';
-import { createServerPublicUrl, listRegisteredServersUsingServiceRole } from '../utils/serverRegistry';
+import { createServerPublicUrl } from '../utils/serverRegistry';
+import { listRegisteredServersUsingServiceRole } from '../utils/serverRegistryNode';
 import { resolveServerSelection } from '../utils/serverSelection';
 import { getServerContextOverride } from './serverContextOverride';
 

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