@promptbook/cli 0.114.0-2 → 0.114.0-21

package/src/commitments/USE_SPAWN/resolveSpawnAgentToolForNode.ts

@@ -1,42 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { EnvironmentMismatchError } from '../../errors/EnvironmentMismatchError';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-
-/**
- * Resolves the server-side `spawn_agent` tool for Node.js runtimes.
- *
- * Uses lazy require so core package can load outside Agents Server.
- *
- * @private internal utility for USE SPAWN commitment
- */
-export function resolveSpawnAgentToolForNode(): ToolFunction {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const { spawn_agent } = require('../../../apps/agents-server/src/tools/spawn_agent');
-
-        if (typeof spawn_agent !== 'function') {
-            throw new Error('spawn_agent value is not a function but ' + typeof spawn_agent);
-        }
-
-        return spawn_agent as ToolFunction;
-    } catch (error) {
-        const normalizedError =
-            error instanceof Error
-                ? error
-                : new Error(typeof error === 'string' ? error : JSON.stringify(error ?? 'Unknown error'));
-
-        return async () => {
-            throw new EnvironmentMismatchError(
-                spaceTrim(
-                    (block) => `
-                        \`spawn_agent\` tool is not available in this environment.
-                        This commitment requires Agents Server runtime with agent persistence enabled.
-
-                        ${normalizedError.name}:
-                        ${block(normalizedError.message)}
-                    `,
-                ),
-            );
-        };
-    }
-}

package/src/commitments/USE_SPAWN/spawnAgentViaBrowser.ts

@@ -1,50 +0,0 @@
-/**
- * Browser-safe wrapper for spawning one persisted Agents Server agent.
- *
- * This function proxies requests to the Agents Server `/api/spawn-agent` endpoint.
- *
- * @param args Tool payload forwarded to server-side `spawn_agent` tool.
- * @param agentsServerUrl Optional explicit agents server base URL.
- * @returns JSON string with structured spawn result.
- *
- * @private internal utility for USE SPAWN commitment
- */
-export async function spawnAgentViaBrowser(args: Record<string, unknown>, agentsServerUrl?: string): Promise<string> {
-    try {
-        const baseUrl = agentsServerUrl || (typeof window !== 'undefined' ? window.location.origin : '');
-
-        if (!baseUrl) {
-            throw new Error('Agents server URL is required in non-browser environments');
-        }
-
-        const apiUrl = new URL('/api/spawn-agent', baseUrl);
-
-        const response = await fetch(apiUrl.toString(), {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify(args),
-        });
-
-        const payload = (await response.json().catch(() => ({}))) as {
-            success?: boolean;
-            result?: unknown;
-            error?: unknown;
-        };
-
-        if (payload.result !== undefined) {
-            return typeof payload.result === 'string' ? payload.result : JSON.stringify(payload.result);
-        }
-
-        if (!response.ok || payload.success === false) {
-            throw new Error(
-                `Failed to spawn agent: ${typeof payload.error === 'string' ? payload.error : response.statusText}`,
-            );
-        }
-        return JSON.stringify(payload);
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Error spawning agent via browser: ${errorMessage}`);
-    }
-}

package/src/commitments/USE_TIME/USE_TIME.ts

@@ -1,177 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import type { TODO_any } from '../../utils/organization/TODO_any';
-import { appendAggregatedUseCommitmentPlaceholder } from '../USE/aggregateUseCommitmentSystemMessages';
-import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-
-/**
- * USE TIME commitment definition
- *
- * The `USE TIME` commitment indicates that the agent should be able to determine the current date and time.
- *
- * Example usage in agent source:
- *
- * ```book
- * USE TIME
- * USE TIME Prefer the user's local timezone.
- * ```
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseTimeCommitmentDefinition extends BaseCommitmentDefinition<'USE TIME'> {
-    public constructor() {
-        super('USE TIME', ['CURRENT TIME', 'TIME', 'DATE']);
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of USE TIME.
-     */
-    public get description(): string {
-        return 'Enable the agent to determine the current date and time.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '🕒';
-    }
-
-    /**
-     * Markdown documentation for USE TIME commitment.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE TIME
-
-            Enables the agent to determine the current date and time.
-
-            ## Key aspects
-
-            - This tool won't receive any input.
-            - It outputs the current date and time as an ISO 8601 string.
-            - Allows the agent to answer questions about the current time or date.
-            - The content following \`USE TIME\` is an arbitrary text that the agent should know (e.g. timezone preference).
-
-            ## Examples
-
-            \`\`\`book
-            Time-aware Assistant
-
-            PERSONA You are a helpful assistant who knows the current time.
-            USE TIME
-            \`\`\`
-
-            \`\`\`book
-            Travel Assistant
-
-            PERSONA You help travelers with planning.
-            USE TIME Prefer the user's local timezone.
-            \`\`\`
-        `);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        // Additional instructions are aggregated later in the final USE system-message pass.
-        void content;
-
-        // Get existing tools array or create new one
-        const existingTools = requirements.tools || [];
-
-        // Add 'get_current_time' to tools if not already present
-        const updatedTools = existingTools.some((tool) => tool.name === 'get_current_time')
-            ? existingTools
-            : [
-                  ...existingTools,
-                  {
-                      name: 'get_current_time',
-                      description: 'Get the current date and time in ISO 8601 format.',
-                      parameters: {
-                          type: 'object',
-                          properties: {
-                              timezone: {
-                                  type: 'string',
-                                  description:
-                                      'Optional timezone name (e.g. "Europe/Prague", "UTC", "America/New_York").',
-                              },
-                          },
-                          required: [],
-                      },
-                  } as TODO_any, // <- TODO: !!!! Remove any
-                  // <- TODO: !!!! define the function in LLM tools
-              ];
-
-        return appendAggregatedUseCommitmentPlaceholder(
-            {
-                ...requirements,
-                tools: updatedTools,
-                _metadata: {
-                    ...requirements._metadata,
-                },
-            },
-            this.type,
-        );
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            get_current_time: 'Get current time',
-        };
-    }
-
-    /**
-     * Gets the `get_current_time` tool function implementation.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return {
-            async get_current_time(args: { timezone?: string }): Promise<string> {
-                console.log('!!!! [Tool] get_current_time called', { args });
-
-                const { timezone } = args;
-
-                if (!timezone) {
-                    return new Date().toISOString();
-                }
-
-                try {
-                    // Note: Returning ISO 8601 string but in the requested timezone
-                    const formatter = new Intl.DateTimeFormat('en-CA', {
-                        timeZone: timezone,
-                        year: 'numeric',
-                        month: '2-digit',
-                        day: '2-digit',
-                        hour: '2-digit',
-                        minute: '2-digit',
-                        second: '2-digit',
-                        hour12: false,
-                        timeZoneName: 'shortOffset',
-                    });
-
-                    const parts = formatter.formatToParts(new Date());
-                    const part = (type: string) => parts.find((p) => p.type === type)?.value;
-
-                    // en-CA format is YYYY-MM-DD
-                    const isoString = `${part('year')}-${part('month')}-${part('day')}T${part('hour')}:${part(
-                        'minute',
-                    )}:${part('second')}${part('timeZoneName')?.replace('GMT', '')}`;
-
-                    return isoString;
-                } catch (error) {
-                    // Fallback to UTC if timezone is invalid
-                    return new Date().toISOString();
-                }
-            },
-        };
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_TIMEOUT/TimeoutToolNames.ts

@@ -1,13 +0,0 @@
-import type { string_javascript_name } from '../../types/string_person_fullname';
-
-/**
- * Tool names provided by the `USE TIMEOUT` commitment.
- *
- * @private internal USE TIMEOUT constant
- */
-export const TimeoutToolNames = {
-    set: 'set_timeout' as string_javascript_name,
-    cancel: 'cancel_timeout' as string_javascript_name,
-    list: 'list_timeouts' as string_javascript_name,
-    update: 'update_timeout' as string_javascript_name,
-} as const;

package/src/commitments/USE_TIMEOUT/TimeoutToolRuntimeAdapter.ts

@@ -1,255 +0,0 @@
-import type { TODO_any } from '../../utils/organization/TODO_any';
-
-/**
- * Tool arguments for scheduling one timeout.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type SetTimeoutToolArgs = {
-    milliseconds?: number;
-    message?: string;
-    [key: string]: TODO_any;
-};
-
-/**
- * Tool arguments for cancelling one timeout.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type CancelTimeoutToolArgs = {
-    timeoutId?: string;
-    allActive?: boolean;
-    [key: string]: TODO_any;
-};
-
-/**
- * Tool arguments for updating one timeout or pausing/resuming all active queued timeouts.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type UpdateTimeoutToolArgs = {
-    timeoutId?: string;
-    allActive?: boolean;
-    dueAt?: string;
-    extendByMs?: number;
-    recurrenceIntervalMs?: number | null;
-    message?: string | null;
-    parameters?: Record<string, unknown>;
-    paused?: boolean;
-    [key: string]: TODO_any;
-};
-
-/**
- * Tool arguments for listing scoped timeouts.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type ListTimeoutsToolArgs = {
-    includeFinished?: boolean;
-    limit?: number;
-    [key: string]: TODO_any;
-};
-
-/**
- * Runtime context available to `USE TIMEOUT` tools.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type TimeoutToolRuntimeContext = {
-    readonly enabled: boolean;
-    readonly chatId?: string;
-    readonly userId?: number;
-    readonly agentId?: string;
-    readonly agentName?: string;
-    readonly promptParameters: Record<string, string>;
-};
-
-/**
- * Lifecycle status exposed by `list_timeouts`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type TimeoutToolListItemStatus = 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
-
-/**
- * One timeout row exposed by `list_timeouts`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type TimeoutToolListItem = {
-    timeoutId: string;
-    chatId: string;
-    status: TimeoutToolListItemStatus;
-    dueAt: string;
-    paused: boolean;
-    message?: string | null;
-    recurrenceIntervalMs?: number | null;
-};
-
-/**
- * Result payload returned by `set_timeout`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type SetTimeoutToolResult = {
-    action: 'set';
-    status: 'set' | 'disabled' | 'error';
-    timeoutId?: string;
-    dueAt?: string;
-    message?: string;
-};
-
-/**
- * Result payload returned by `cancel_timeout`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type CancelTimeoutToolResult = {
-    action: 'cancel';
-    status: 'cancelled' | 'cancelled_all' | 'not_found' | 'disabled' | 'error';
-    timeoutId?: string;
-    dueAt?: string;
-    cancelledCount?: number;
-    cancelledTimeoutIds?: Array<string>;
-    hasMore?: boolean;
-    message?: string;
-};
-
-/**
- * Result payload returned by `update_timeout`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type UpdateTimeoutToolResult = {
-    action: 'update';
-    status: 'updated' | 'updated_all' | 'not_found' | 'conflict' | 'disabled' | 'error';
-    timeoutId?: string;
-    dueAt?: string;
-    paused?: boolean;
-    recurrenceIntervalMs?: number | null;
-    updatedCount?: number;
-    matchedCount?: number;
-    updatedTimeoutIds?: Array<string>;
-    hasMore?: boolean;
-    message?: string;
-};
-
-/**
- * Result payload returned by `list_timeouts`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type ListTimeoutsToolResult = {
-    action: 'list';
-    status: 'listed' | 'disabled' | 'error';
-    items?: Array<TimeoutToolListItem>;
-    total?: number;
-    message?: string;
-};
-
-/**
- * Union of all `USE TIMEOUT` tool actions.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type TimeoutToolAction =
-    | SetTimeoutToolResult['action']
-    | CancelTimeoutToolResult['action']
-    | ListTimeoutsToolResult['action']
-    | UpdateTimeoutToolResult['action'];
-
-/**
- * Union of all `USE TIMEOUT` tool results.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type TimeoutToolResult =
-    | SetTimeoutToolResult
-    | CancelTimeoutToolResult
-    | ListTimeoutsToolResult
-    | UpdateTimeoutToolResult;
-
-/**
- * Runtime adapter used by `USE TIMEOUT` tools.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-export type TimeoutToolRuntimeAdapter = {
-    scheduleTimeout(
-        args: {
-            milliseconds: number;
-            message?: string;
-        },
-        runtimeContext: TimeoutToolRuntimeContext,
-    ): Promise<{
-        timeoutId: string;
-        dueAt: string;
-    }>;
-    cancelTimeout(
-        args:
-            | {
-                  timeoutId: string;
-              }
-            | {
-                  allActive: true;
-              },
-        runtimeContext: TimeoutToolRuntimeContext,
-    ): Promise<{
-        status: 'cancelled' | 'cancelled_all' | 'not_found';
-        timeoutId?: string;
-        dueAt?: string;
-        cancelledCount?: number;
-        cancelledTimeoutIds?: Array<string>;
-        hasMore?: boolean;
-    }>;
-    listTimeouts(
-        args: {
-            includeFinished: boolean;
-            limit: number;
-        },
-        runtimeContext: TimeoutToolRuntimeContext,
-    ): Promise<{
-        items: Array<TimeoutToolListItem>;
-        total: number;
-    }>;
-    updateTimeout(
-        args:
-            | {
-                  timeoutId: string;
-                  patch: {
-                      dueAt?: string;
-                      extendByMs?: number;
-                      recurrenceIntervalMs?: number | null;
-                      message?: string | null;
-                      parameters?: Record<string, unknown>;
-                      paused?: boolean;
-                  };
-              }
-            | {
-                  allActive: true;
-                  paused: boolean;
-              },
-        runtimeContext: TimeoutToolRuntimeContext,
-    ): Promise<
-        | {
-              status: 'updated';
-              timeout: TimeoutToolListItem;
-          }
-        | {
-              status: 'not_found';
-              timeoutId: string;
-          }
-        | {
-              status: 'conflict';
-              timeoutId: string;
-              reason: 'finished' | 'running';
-          }
-        | {
-              status: 'updated_all';
-              updatedCount: number;
-              matchedCount: number;
-              updatedTimeoutIds: Array<string>;
-              hasMore?: boolean;
-          }
-    >;
-};

package/src/commitments/USE_TIMEOUT/USE_TIMEOUT.ts

@@ -1,117 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
-import { formatOptionalInstructionBlock } from '../_base/formatOptionalInstructionBlock';
-import { createTimeoutSystemMessage } from './createTimeoutSystemMessage';
-import { createTimeoutToolFunctions } from './createTimeoutToolFunctions';
-import { createTimeoutTools } from './createTimeoutTools';
-import { TimeoutToolNames } from './TimeoutToolNames';
-
-export { setTimeoutToolRuntimeAdapter } from './setTimeoutToolRuntimeAdapter';
-export type {
-    CancelTimeoutToolResult,
-    ListTimeoutsToolResult,
-    SetTimeoutToolResult,
-    TimeoutToolListItem,
-    TimeoutToolRuntimeAdapter,
-    TimeoutToolRuntimeContext,
-    UpdateTimeoutToolResult,
-} from './TimeoutToolRuntimeAdapter';
-
-/**
- * `USE TIMEOUT` commitment definition.
- *
- * The `USE TIMEOUT` commitment enables timeout wake-ups and scoped timeout management.
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition<'USE TIMEOUT'> {
-    public constructor() {
-        super('USE TIMEOUT');
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    /**
-     * Short one-line description of `USE TIMEOUT`.
-     */
-    get description(): string {
-        return 'Enable timeout wake-ups plus scoped timeout listing, updates, and cancellation across chats.';
-    }
-
-    /**
-     * Icon for this commitment.
-     */
-    get icon(): string {
-        return '⏱️';
-    }
-
-    /**
-     * Markdown documentation for `USE TIMEOUT`.
-     */
-    get documentation(): string {
-        return spaceTrim(`
-            # USE TIMEOUT
-
-            Enables timeout wake-ups and timeout management for the same user+agent scope.
-
-            ## Key aspects
-
-            - The agent uses \`set_timeout\` to schedule a future wake-up in the same chat thread.
-            - The tool returns immediately while the timeout is stored and executed by the runtime later.
-            - The wake-up arrives as a new user-like timeout message in the same conversation.
-            - The agent can inspect known timeout details via \`list_timeouts\`.
-            - The agent can cancel one timeout by \`timeoutId\` or cancel all active timeouts via \`cancel_timeout\`.
-            - The agent can pause/resume and edit timeout details via \`update_timeout\`.
-            - Commitment content is treated as optional timeout policy instructions.
-
-            ## Examples
-
-            \`\`\`book
-            Follow-up Agent
-            USE TIMEOUT Remind yourself only when follow-up work is explicitly requested.
-            \`\`\`
-        `);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        const extraInstructions = formatOptionalInstructionBlock('Timeout instructions', content);
-
-        return this.appendToSystemMessage(
-            {
-                ...requirements,
-                tools: createTimeoutTools(requirements.tools || []),
-                _metadata: {
-                    ...requirements._metadata,
-                    useTimeout: content || true,
-                },
-            },
-            createTimeoutSystemMessage(extraInstructions),
-        );
-    }
-
-    /**
-     * Gets human-readable titles for tool functions provided by this commitment.
-     */
-    getToolTitles(): Record<string_javascript_name, string> {
-        return {
-            [TimeoutToolNames.set]: 'Set timer',
-            [TimeoutToolNames.cancel]: 'Cancel timer',
-            [TimeoutToolNames.list]: 'List timers',
-            [TimeoutToolNames.update]: 'Update timer',
-        };
-    }
-
-    /**
-     * Gets `USE TIMEOUT` tool function implementations.
-     */
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return createTimeoutToolFunctions();
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/USE_TIMEOUT/createTimeoutSystemMessage.ts

@@ -1,22 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-
-/**
- * Creates system-message instructions for `USE TIMEOUT`.
- *
- * @private internal utility of USE TIMEOUT
- */
-export function createTimeoutSystemMessage(extraInstructions: string): string {
-    return spaceTrim(
-        (block) => `
-            ## Timeout scheduling
-
-            -   Use \`set_timeout\` to wake this same chat thread in the future.
-            -   Use \`list_timeouts\` to review timeout ids/details across all chats for the same user+agent scope.
-            -   \`cancel_timeout\` accepts either one timeout id or \`allActive: true\` to cancel all active timeouts in this same user+agent scope.
-            -   Use \`update_timeout\` to pause/resume, edit next run, edit recurrence, or update timeout payload details.
-            -   When one timeout elapses, you will receive a new user-like message that explicitly says it is a timeout wake-up and includes the \`timeoutId\`.
-            -   Do not claim a timer was set or cancelled unless the tool confirms it.
-            ${block(extraInstructions)}
-        `,
-    );
-}