@promptbook/cli 0.114.0-0 → 0.114.0-10

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

@@ -0,0 +1,180 @@
+import { spaceTrim } from 'spacetrim';
+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,
+} 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,
+                    milliseconds: toolArguments.milliseconds,
+                    message: toolArguments.message,
+                });
+
+                return createToolExecutionEnvelope({
+                    assistantMessage: `Planned message ${JSON.stringify(result.timeoutId)} for ${result.dueAt}.`,
+                    toolResult: result,
+                });
+            } catch (error) {
+                return serializeToolError('set', 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} at ${plannedMessage.dueAt}: ${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'))}
+        `,
+    );
+}
+
+/**
+ * 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' | '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,92 @@
+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',
+    list: 'list_timeouts',
+    cancel: 'cancel_timeout',
+} 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 will wake you in your singleton goal chat after a delay. 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.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    milliseconds: {
+                        type: 'number',
+                        description: 'Positive delay in milliseconds before the planned message wakes you.',
+                    },
+                    message: {
+                        type: 'string',
+                        description:
+                            'The concrete future instruction or reminder that will be delivered in your goal chat.',
+                    },
+                },
+                required: ['milliseconds', 'message'],
+                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 and execution times, across every conversation in which you were invoked.',
+            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:
+                'Cancel one planned goal-chat message by its timeout identifier. 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/run_browser.ts

@@ -1,4 +1,4 @@
-import { fetchUrlContent } from '../../../../src/commitments/USE_BROWSER/fetchUrlContent';
+import { fetchUrlContent } from '../../../../src/scrapers/_common/utils/fetchUrlContent';
 import { emitToolCallProgressFromToolArgs } from '../../../../src/commitments/_common/toolRuntimeContext';
 import type { string_date_iso8601 } from '../../../../src/types/typeAliases';
 import type { Page } from 'playwright';

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

@@ -14,7 +14,7 @@ import {
 } from '../utils/useEmailSmtpWalletConstants';
 
 /**
- * Hidden runtime context shape used by USE EMAIL server tool.
+ * Hidden runtime context shape used by the `send_email` server tool.
  */
 type UseEmailRuntimeContext = {
     email?: {
@@ -110,7 +110,7 @@ export async function send_email(args: SendEmailToolArgs): Promise<string> {
 }
 
 /**
- * Builds wallet-required result payload for USE EMAIL.
+ * Builds wallet-required result payload for the `send_email` server tool.
  */
 function createEmailWalletCredentialRequiredResult(
     defaultFromAddress?: string,
@@ -170,7 +170,7 @@ function normalizeSendEmailPayload(args: SendEmailToolArgs, fallbackFromAddress?
     const sender = normalizeNonEmptyString(normalizedMessage?.sender) || fallbackFromAddress;
 
     if (!sender) {
-        throw new Error('Sender email is missing. Configure sender in USE EMAIL or in SMTP credential.');
+        throw new Error('Sender email is missing. Configure the sender in the SMTP credential.');
     }
     if (!recipientsInput || recipientsInput.length === 0) {
         throw new Error('At least one recipient email address is required.');

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