@promptbook/cli 0.114.0-2 → 0.114.0-21

package/src/commitments/USE_TIMEOUT/parseTimeoutToolArgs.ts

@@ -1,460 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { PipelineExecutionError } from '../../errors/PipelineExecutionError';
-import type {
-    CancelTimeoutToolArgs,
-    ListTimeoutsToolArgs,
-    SetTimeoutToolArgs,
-    UpdateTimeoutToolArgs,
-} from './TimeoutToolRuntimeAdapter';
-
-/**
- * Default number of rows returned by `list_timeouts`.
- *
- * @private internal USE TIMEOUT constant
- */
-const DEFAULT_LIST_TIMEOUTS_LIMIT = 20;
-
-/**
- * Hard cap for `list_timeouts` page size.
- *
- * @private internal USE TIMEOUT constant
- */
-const MAX_LIST_TIMEOUTS_LIMIT = 100;
-
-/**
- * Parsed arguments for `set_timeout`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-type ParsedSetTimeoutToolArgs = {
-    milliseconds: number;
-    message?: string;
-};
-
-/**
- * Parsed arguments for `cancel_timeout`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-type ParsedCancelTimeoutToolArgs =
-    | {
-          timeoutId: string;
-      }
-    | {
-          allActive: true;
-      };
-
-/**
- * Parsed arguments for `list_timeouts`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-type ParsedListTimeoutsToolArgs = {
-    includeFinished: boolean;
-    limit: number;
-};
-
-/**
- * Parsed patch payload for `update_timeout` single-timeout updates.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-type ParsedUpdateTimeoutToolPatch = {
-    dueAt?: string;
-    extendByMs?: number;
-    recurrenceIntervalMs?: number | null;
-    message?: string | null;
-    parameters?: Record<string, unknown>;
-    paused?: boolean;
-};
-
-/**
- * Parsed arguments for `update_timeout`.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-type ParsedUpdateTimeoutToolArgs =
-    | {
-          timeoutId: string;
-          patch: ParsedUpdateTimeoutToolPatch;
-      }
-    | {
-          allActive: true;
-          paused: boolean;
-      };
-
-/**
- * Parsed timeout target selector shared by timeout tools that can act on either one timeout or all active ones.
- *
- * @private type of UseTimeoutCommitmentDefinition
- */
-type ParsedTimeoutTargetSelection =
-    | {
-          timeoutId: string;
-          allActive: false;
-      }
-    | {
-          allActive: true;
-      };
-
-/**
- * Creates one formatted timeout-argument validation error.
- *
- * @private internal utility of USE TIMEOUT
- */
-function createTimeoutToolArgsError(message: string): PipelineExecutionError {
-    return new PipelineExecutionError(
-        spaceTrim(`
-            ${message}
-        `),
-    );
-}
-
-/**
- * Normalizes one optional timeout id string.
- *
- * @private internal utility of USE TIMEOUT
- */
-function normalizeOptionalTimeoutId(value: unknown): string {
-    return typeof value === 'string' ? value.trim() : '';
-}
-
-/**
- * Parses timeout target selection for tools that accept either `timeoutId` or `allActive: true`.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseTimeoutTargetSelection(
-    args: { timeoutId?: string; allActive?: boolean },
-    options: {
-        bothMessage: string;
-        missingMessage: string;
-    },
-): ParsedTimeoutTargetSelection {
-    const timeoutId = normalizeOptionalTimeoutId(args.timeoutId);
-    const allActive = args.allActive === true;
-
-    if (timeoutId && allActive) {
-        throw createTimeoutToolArgsError(options.bothMessage);
-    }
-
-    if (allActive) {
-        return { allActive: true };
-    }
-
-    if (!timeoutId) {
-        throw createTimeoutToolArgsError(options.missingMessage);
-    }
-
-    return {
-        timeoutId,
-        allActive: false,
-    };
-}
-
-/**
- * Parses one explicit `dueAt` update value.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseOptionalTimeoutDueAt(value: unknown): string | undefined {
-    if (typeof value !== 'string' || value.trim().length === 0) {
-        return undefined;
-    }
-
-    const normalizedDueAt = value.trim();
-    const dueAtTimestamp = Date.parse(normalizedDueAt);
-
-    if (!Number.isFinite(dueAtTimestamp)) {
-        throw createTimeoutToolArgsError('Timeout `dueAt` must be one valid ISO timestamp.');
-    }
-
-    return new Date(dueAtTimestamp).toISOString();
-}
-
-/**
- * Parses one explicit `extendByMs` update value.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseOptionalTimeoutExtendByMs(value: unknown): number | undefined {
-    if (typeof value !== 'number') {
-        return undefined;
-    }
-
-    if (!Number.isFinite(value) || value <= 0) {
-        throw createTimeoutToolArgsError('Timeout `extendByMs` must be a positive number of milliseconds.');
-    }
-
-    return Math.floor(value);
-}
-
-/**
- * Parses one explicit `recurrenceIntervalMs` update value.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseOptionalTimeoutRecurrenceInterval(value: unknown): number | null | undefined {
-    if (value === null) {
-        return null;
-    }
-
-    if (typeof value !== 'number') {
-        return undefined;
-    }
-
-    if (!Number.isFinite(value) || value <= 0) {
-        throw createTimeoutToolArgsError(
-            'Timeout `recurrenceIntervalMs` must be a positive number of milliseconds or `null`.',
-        );
-    }
-
-    return Math.floor(value);
-}
-
-/**
- * Parses one explicit `message` update value.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseOptionalTimeoutMessage(value: unknown): string | null | undefined {
-    if (value === null) {
-        return null;
-    }
-
-    if (typeof value !== 'string') {
-        return undefined;
-    }
-
-    const normalizedMessage = value.trim();
-    return normalizedMessage.length > 0 ? normalizedMessage : null;
-}
-
-/**
- * Parses one explicit `parameters` update value.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseOptionalTimeoutParameters(value: unknown): Record<string, unknown> | undefined {
-    if (value === undefined) {
-        return undefined;
-    }
-
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw createTimeoutToolArgsError('Timeout `parameters` must be one JSON object.');
-    }
-
-    return value as Record<string, unknown>;
-}
-
-/**
- * Parses one explicit `paused` update value.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseOptionalTimeoutPaused(value: unknown): boolean | undefined {
-    return typeof value === 'boolean' ? value : undefined;
-}
-
-/**
- * Parses patch fields for `update_timeout`.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseTimeoutUpdatePatch(args: UpdateTimeoutToolArgs): ParsedUpdateTimeoutToolPatch {
-    const patch: ParsedUpdateTimeoutToolPatch = {};
-    const dueAt = parseOptionalTimeoutDueAt(args.dueAt);
-    const extendByMs = parseOptionalTimeoutExtendByMs(args.extendByMs);
-    const recurrenceIntervalMs = parseOptionalTimeoutRecurrenceInterval(args.recurrenceIntervalMs);
-    const message = parseOptionalTimeoutMessage(args.message);
-    const parameters = parseOptionalTimeoutParameters(args.parameters);
-    const paused = parseOptionalTimeoutPaused(args.paused);
-
-    if (dueAt !== undefined) {
-        patch.dueAt = dueAt;
-    }
-
-    if (extendByMs !== undefined) {
-        patch.extendByMs = extendByMs;
-    }
-
-    if (patch.dueAt !== undefined && patch.extendByMs !== undefined) {
-        throw createTimeoutToolArgsError('Timeout update cannot include both `dueAt` and `extendByMs`.');
-    }
-
-    if (recurrenceIntervalMs !== undefined) {
-        patch.recurrenceIntervalMs = recurrenceIntervalMs;
-    }
-
-    if (message !== undefined) {
-        patch.message = message;
-    }
-
-    if (parameters !== undefined) {
-        patch.parameters = parameters;
-    }
-
-    if (paused !== undefined) {
-        patch.paused = paused;
-    }
-
-    return patch;
-}
-
-/**
- * Determines whether the patch contains fields that are only supported for single-timeout updates.
- *
- * @private internal utility of USE TIMEOUT
- */
-function hasSingleTimeoutOnlyPatchFields(patch: ParsedUpdateTimeoutToolPatch): boolean {
-    return (
-        patch.dueAt !== undefined ||
-        patch.extendByMs !== undefined ||
-        patch.recurrenceIntervalMs !== undefined ||
-        patch.message !== undefined ||
-        patch.parameters !== undefined
-    );
-}
-
-/**
- * Parses bulk timeout update arguments.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseBulkTimeoutUpdateArgs(
-    patch: ParsedUpdateTimeoutToolPatch,
-): Extract<ParsedUpdateTimeoutToolArgs, { allActive: true }> {
-    if (patch.paused === undefined) {
-        throw createTimeoutToolArgsError(
-            'Bulk timeout update with `allActive: true` requires `paused` to be explicitly set.',
-        );
-    }
-
-    if (hasSingleTimeoutOnlyPatchFields(patch)) {
-        throw createTimeoutToolArgsError('Bulk timeout update only supports the `paused` field.');
-    }
-
-    return {
-        allActive: true,
-        paused: patch.paused,
-    };
-}
-
-/**
- * Parses single-timeout update arguments.
- *
- * @private internal utility of USE TIMEOUT
- */
-function parseSingleTimeoutUpdateArgs(
-    timeoutId: string,
-    patch: ParsedUpdateTimeoutToolPatch,
-): Extract<ParsedUpdateTimeoutToolArgs, { timeoutId: string }> {
-    if (!timeoutId) {
-        throw createTimeoutToolArgsError('Timeout `timeoutId` is required for single-timeout updates.');
-    }
-
-    if (Object.keys(patch).length === 0) {
-        throw createTimeoutToolArgsError('Timeout update must include at least one editable field.');
-    }
-
-    return {
-        timeoutId,
-        patch,
-    };
-}
-
-/**
- * Parses and validates `USE TIMEOUT` tool arguments.
- *
- * @private internal utility of USE TIMEOUT
- */
-export const parseTimeoutToolArgs = {
-    /**
-     * Parses `set_timeout` input.
-     */
-    set(args: SetTimeoutToolArgs): ParsedSetTimeoutToolArgs {
-        const parsedMilliseconds = Number(args.milliseconds);
-
-        if (!Number.isFinite(parsedMilliseconds) || parsedMilliseconds <= 0) {
-            throw new PipelineExecutionError(
-                spaceTrim(`
-                    Timeout \`milliseconds\` must be a positive number.
-                `),
-            );
-        }
-
-        const message = typeof args.message === 'string' ? args.message.trim() : '';
-
-        return {
-            milliseconds: Math.floor(parsedMilliseconds),
-            ...(message ? { message } : {}),
-        };
-    },
-
-    /**
-     * Parses `cancel_timeout` input.
-     */
-    cancel(args: CancelTimeoutToolArgs): ParsedCancelTimeoutToolArgs {
-        const target = parseTimeoutTargetSelection(args, {
-            bothMessage: 'Timeout cancellation must target either one `timeoutId` or `allActive: true`, not both.',
-            missingMessage: 'Timeout `timeoutId` is required unless you pass `allActive: true`.',
-        });
-
-        if (target.allActive) {
-            return { allActive: true };
-        }
-
-        return { timeoutId: target.timeoutId };
-    },
-
-    /**
-     * Parses `list_timeouts` input.
-     */
-    list(args: ListTimeoutsToolArgs): ParsedListTimeoutsToolArgs {
-        if (args.includeFinished !== undefined && typeof args.includeFinished !== 'boolean') {
-            throw new PipelineExecutionError(
-                spaceTrim(`
-                    Timeout \`includeFinished\` must be a boolean when provided.
-                `),
-            );
-        }
-
-        const parsedLimit = args.limit === undefined ? DEFAULT_LIST_TIMEOUTS_LIMIT : Math.floor(Number(args.limit));
-
-        if (!Number.isFinite(parsedLimit) || parsedLimit <= 0) {
-            throw new PipelineExecutionError(
-                spaceTrim(`
-                    Timeout \`limit\` must be a positive number.
-                `),
-            );
-        }
-
-        if (parsedLimit > MAX_LIST_TIMEOUTS_LIMIT) {
-            throw new PipelineExecutionError(
-                spaceTrim(`
-                    Timeout \`limit\` must be at most \`${MAX_LIST_TIMEOUTS_LIMIT}\`.
-                `),
-            );
-        }
-
-        return {
-            includeFinished: args.includeFinished === true,
-            limit: parsedLimit,
-        };
-    },
-
-    /**
-     * Parses `update_timeout` input.
-     */
-    update(args: UpdateTimeoutToolArgs): ParsedUpdateTimeoutToolArgs {
-        const target = parseTimeoutTargetSelection(args, {
-            bothMessage: 'Timeout update must target either one `timeoutId` or `allActive: true`, not both.',
-            missingMessage: 'Timeout update requires one `timeoutId` or `allActive: true`.',
-        });
-        const patch = parseTimeoutUpdatePatch(args);
-
-        return target.allActive
-            ? parseBulkTimeoutUpdateArgs(patch)
-            : parseSingleTimeoutUpdateArgs(target.timeoutId, patch);
-    },
-};

package/src/commitments/USE_TIMEOUT/resolveTimeoutRuntimeContext.ts

@@ -1,36 +0,0 @@
-import type { TODO_any } from '../../utils/organization/TODO_any';
-import { readToolRuntimeContextFromToolArgs } from '../_common/toolRuntimeContext';
-import type { TimeoutToolRuntimeContext } from './TimeoutToolRuntimeAdapter';
-
-/**
- * Resolves timeout runtime context from hidden tool arguments.
- *
- * @private internal utility of USE TIMEOUT
- */
-export function resolveTimeoutRuntimeContext(args: Record<string, TODO_any>): TimeoutToolRuntimeContext {
-    const runtimeContext = readToolRuntimeContextFromToolArgs(args);
-    const chatContext = runtimeContext?.chat;
-
-    return {
-        enabled: Boolean(chatContext?.chatId),
-        chatId: chatContext?.chatId,
-        userId: chatContext?.userId,
-        agentId: chatContext?.agentId,
-        agentName: chatContext?.agentName,
-        promptParameters: normalizePromptParameters(chatContext?.parameters),
-    };
-}
-
-/**
- * Normalizes stored prompt parameters carried by timeout runtime context.
- *
- * @private internal utility of USE TIMEOUT
- */
-function normalizePromptParameters(rawParameters: unknown): Record<string, string> {
-    if (!rawParameters || typeof rawParameters !== 'object' || Array.isArray(rawParameters)) {
-        return {};
-    }
-
-    const normalizedEntries = Object.entries(rawParameters).filter(([, value]) => typeof value === 'string');
-    return Object.fromEntries(normalizedEntries) as Record<string, string>;
-}

package/src/commitments/USE_TIMEOUT/setTimeoutToolRuntimeAdapter.ts

@@ -1,26 +0,0 @@
-import type { TimeoutToolRuntimeAdapter } from './TimeoutToolRuntimeAdapter';
-
-/**
- * Process-wide runtime adapter reference used by `USE TIMEOUT` tools.
- *
- * @private internal singleton of USE TIMEOUT
- */
-let timeoutToolRuntimeAdapter: TimeoutToolRuntimeAdapter | null = null;
-
-/**
- * Sets runtime adapter used by `USE TIMEOUT` tools.
- *
- * @private internal utility of USE TIMEOUT
- */
-export function setTimeoutToolRuntimeAdapter(adapter: TimeoutToolRuntimeAdapter | null): void {
-    timeoutToolRuntimeAdapter = adapter;
-}
-
-/**
- * Gets runtime adapter used by `USE TIMEOUT` tools.
- *
- * @private internal utility of USE TIMEOUT
- */
-export function getTimeoutToolRuntimeAdapter(): TimeoutToolRuntimeAdapter | null {
-    return timeoutToolRuntimeAdapter;
-}

package/src/commitments/WALLET/WALLET.ts

@@ -1,71 +0,0 @@
-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 { createWalletSystemMessage } from './createWalletSystemMessage';
-import { createWalletToolFunctions } from './createWalletToolFunctions';
-import { createWalletTools } from './createWalletTools';
-import { getWalletCommitmentDocumentation } from './getWalletCommitmentDocumentation';
-import { getWalletToolTitles } from './getWalletToolTitles';
-
-export { setWalletToolRuntimeAdapter } from './setWalletToolRuntimeAdapter';
-export type {
-    WalletRecordType,
-    WalletToolRecord,
-    WalletToolRuntimeAdapter,
-    WalletToolRuntimeContext,
-} from './WalletToolRuntimeAdapter';
-
-/**
- * WALLET commitment definition.
- *
- * @private [🪔] Maybe export the commitments through some package
- */
-export class WalletCommitmentDefinition extends BaseCommitmentDefinition<'WALLET' | 'WALLETS'> {
-    public constructor(type: 'WALLET' | 'WALLETS' = 'WALLET') {
-        super(type);
-    }
-
-    override get requiresContent(): boolean {
-        return false;
-    }
-
-    get description(): string {
-        return 'Enable persistent private credential storage (tokens, logins, cookies) scoped per agent or globally.';
-    }
-
-    get icon(): string {
-        return '👛';
-    }
-
-    get documentation(): string {
-        return getWalletCommitmentDocumentation(this.type);
-    }
-
-    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
-        const extraInstructions = formatOptionalInstructionBlock('Wallet instructions', content);
-
-        return this.appendToSystemMessage(
-            {
-                ...requirements,
-                tools: createWalletTools(requirements.tools),
-                _metadata: {
-                    ...requirements._metadata,
-                    useWallet: content || true,
-                },
-            },
-            createWalletSystemMessage(extraInstructions),
-        );
-    }
-
-    getToolTitles(): Record<string_javascript_name, string> {
-        return getWalletToolTitles();
-    }
-
-    getToolFunctions(): Record<string_javascript_name, ToolFunction> {
-        return createWalletToolFunctions();
-    }
-}
-
-// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/WALLET/WalletToolNames.ts

@@ -1,14 +0,0 @@
-import type { string_javascript_name } from '../../types/string_person_fullname';
-
-/**
- * Names of tools used by the WALLET commitment.
- *
- * @private constant of WalletCommitmentDefinition
- */
-export const WalletToolNames = {
-    retrieve: 'retrieve_wallet_records' as string_javascript_name,
-    store: 'store_wallet_record' as string_javascript_name,
-    update: 'update_wallet_record' as string_javascript_name,
-    delete: 'delete_wallet_record' as string_javascript_name,
-    request: 'request_wallet_record' as string_javascript_name,
-} as const;