@promptbook/cli 0.114.0-3 → 0.114.0-5

package/src/commitments/MEMORY/createMemorySystemMessage.ts

@@ -1,27 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import { MemoryToolNames } from './MemoryToolNames';
-
-/**
- * Builds the MEMORY instruction block appended to the system message.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function createMemorySystemMessage(extraInstructions: string): string {
-    return spaceTrim(
-        (block) => `
-            ## Memory
-
-            -   Prefer storing agent-scoped memories; only make them global when the fact should apply across all your agents.
-            -   You can use persistent user memory tools.
-            -   Use \`${MemoryToolNames.retrieve}\` to load relevant memory before answering.
-            -   Use \`${MemoryToolNames.store}\` to save stable user-specific facts that improve future help.
-            -   Use \`${MemoryToolNames.update}\` to refresh an existing memory when the content changes.
-            -   Use \`${
-                MemoryToolNames.delete
-            }\` to delete memories that are no longer accurate (deletions are soft and hidden from future queries).
-            -   Store concise memory items and avoid duplicates.
-            -   Never claim memory was saved or loaded unless the tool confirms it.
-            ${block(extraInstructions)}
-        `,
-    );
-}

package/src/commitments/MEMORY/createMemoryToolFunctions.ts

@@ -1,134 +0,0 @@
-import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import { getMemoryToolRuntimeAdapterOrDisabledResult } from './getMemoryToolRuntimeAdapterOrDisabledResult';
-import { MemoryToolNames } from './MemoryToolNames';
-import type {
-    DeleteMemoryToolArgs,
-    DeleteMemoryToolResult,
-    RetrieveMemoryToolArgs,
-    RetrieveMemoryToolResult,
-    StoreMemoryToolArgs,
-    StoreMemoryToolResult,
-    UpdateMemoryToolArgs,
-    UpdateMemoryToolResult,
-} from './MemoryToolRuntimeAdapter';
-import { parseMemoryToolArgs } from './parseMemoryToolArgs';
-import { resolveMemoryRuntimeContext } from './resolveMemoryRuntimeContext';
-
-/**
- * Gets MEMORY tool function implementations.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function createMemoryToolFunctions(): Record<string_javascript_name, ToolFunction> {
-    return {
-        async [MemoryToolNames.retrieve](args: RetrieveMemoryToolArgs): Promise<string> {
-            const runtimeContext = resolveMemoryRuntimeContext(args);
-            const { adapter, disabledResult } = getMemoryToolRuntimeAdapterOrDisabledResult('retrieve', runtimeContext);
-
-            if (!adapter || disabledResult) {
-                return JSON.stringify(disabledResult);
-            }
-
-            const parsedArgs = parseMemoryToolArgs.retrieve(args);
-
-            try {
-                const memories = await adapter.retrieveMemories(parsedArgs, runtimeContext);
-                const result: RetrieveMemoryToolResult = {
-                    action: 'retrieve',
-                    status: 'ok',
-                    query: parsedArgs.query,
-                    memories,
-                };
-                return JSON.stringify(result);
-            } catch (error) {
-                const result: RetrieveMemoryToolResult = {
-                    action: 'retrieve',
-                    status: 'error',
-                    query: parsedArgs.query,
-                    memories: [],
-                    message: error instanceof Error ? error.message : String(error),
-                };
-                return JSON.stringify(result);
-            }
-        },
-        async [MemoryToolNames.store](args: StoreMemoryToolArgs): Promise<string> {
-            const runtimeContext = resolveMemoryRuntimeContext(args);
-            const { adapter, disabledResult } = getMemoryToolRuntimeAdapterOrDisabledResult('store', runtimeContext);
-
-            if (!adapter || disabledResult) {
-                return JSON.stringify(disabledResult);
-            }
-
-            try {
-                const parsedArgs = parseMemoryToolArgs.store(args);
-                const memory = await adapter.storeMemory(parsedArgs, runtimeContext);
-                const result: StoreMemoryToolResult = {
-                    action: 'store',
-                    status: 'stored',
-                    memory,
-                };
-                return JSON.stringify(result);
-            } catch (error) {
-                const result: StoreMemoryToolResult = {
-                    action: 'store',
-                    status: 'error',
-                    message: error instanceof Error ? error.message : String(error),
-                };
-                return JSON.stringify(result);
-            }
-        },
-        async [MemoryToolNames.update](args: UpdateMemoryToolArgs): Promise<string> {
-            const runtimeContext = resolveMemoryRuntimeContext(args);
-            const { adapter, disabledResult } = getMemoryToolRuntimeAdapterOrDisabledResult('update', runtimeContext);
-
-            if (!adapter || disabledResult) {
-                return JSON.stringify(disabledResult);
-            }
-
-            try {
-                const parsedArgs = parseMemoryToolArgs.update(args);
-                const memory = await adapter.updateMemory(parsedArgs, runtimeContext);
-                const result: UpdateMemoryToolResult = {
-                    action: 'update',
-                    status: 'updated',
-                    memory,
-                };
-                return JSON.stringify(result);
-            } catch (error) {
-                const result: UpdateMemoryToolResult = {
-                    action: 'update',
-                    status: 'error',
-                    message: error instanceof Error ? error.message : String(error),
-                };
-                return JSON.stringify(result);
-            }
-        },
-        async [MemoryToolNames.delete](args: DeleteMemoryToolArgs): Promise<string> {
-            const runtimeContext = resolveMemoryRuntimeContext(args);
-            const { adapter, disabledResult } = getMemoryToolRuntimeAdapterOrDisabledResult('delete', runtimeContext);
-
-            if (!adapter || disabledResult) {
-                return JSON.stringify(disabledResult);
-            }
-
-            try {
-                const parsedArgs = parseMemoryToolArgs.delete(args);
-                const deleted = await adapter.deleteMemory(parsedArgs, runtimeContext);
-                const result: DeleteMemoryToolResult = {
-                    action: 'delete',
-                    status: 'deleted',
-                    memoryId: deleted.id,
-                };
-                return JSON.stringify(result);
-            } catch (error) {
-                const result: DeleteMemoryToolResult = {
-                    action: 'delete',
-                    status: 'error',
-                    message: error instanceof Error ? error.message : String(error),
-                };
-                return JSON.stringify(result);
-            }
-        },
-    };
-}

package/src/commitments/MEMORY/createMemoryTools.ts

@@ -1,115 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
-import { MemoryToolNames } from './MemoryToolNames';
-
-/**
- * Concrete type of tool definitions in `AgentModelRequirements`.
- *
- * @private type of MemoryCommitmentDefinition
- */
-type AgentModelTools = NonNullable<AgentModelRequirements['tools']>;
-
-/**
- * Creates MEMORY tool definitions while preserving already-registered tools.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function createMemoryTools(existingTools: AgentModelRequirements['tools']): AgentModelTools {
-    const tools = [...(existingTools || [])];
-
-    if (!tools.some((tool) => tool.name === MemoryToolNames.retrieve)) {
-        tools.push({
-            name: MemoryToolNames.retrieve,
-            description: spaceTrim(`
-                Retrieve previously stored user memories relevant to the current conversation.
-                Use this before responding when user context can improve the answer.
-            `),
-            parameters: {
-                type: 'object',
-                properties: {
-                    query: {
-                        type: 'string',
-                        description: 'Optional query used to filter relevant memories.',
-                    },
-                    limit: {
-                        type: 'integer',
-                        description: 'Optional maximum number of memories to return (default 5, max 20).',
-                    },
-                },
-            },
-        });
-    }
-
-    if (!tools.some((tool) => tool.name === MemoryToolNames.store)) {
-        tools.push({
-            name: MemoryToolNames.store,
-            description: spaceTrim(`
-                Store a durable user memory that should be remembered in future conversations.
-                Store only stable and useful user-specific facts or preferences.
-            `),
-            parameters: {
-                type: 'object',
-                properties: {
-                    content: {
-                        type: 'string',
-                        description: 'Memory text to store.',
-                    },
-                    isGlobal: {
-                        type: 'boolean',
-                        description: 'Set true to make this memory global across all user agents.',
-                    },
-                },
-                required: ['content'],
-            },
-        });
-    }
-
-    if (!tools.some((tool) => tool.name === MemoryToolNames.update)) {
-        tools.push({
-            name: MemoryToolNames.update,
-            description: spaceTrim(`
-                Update an existing user memory after retrieving it, so the stored fact stays accurate.
-                Always pass the memory id you retrieved along with the new content.
-            `),
-            parameters: {
-                type: 'object',
-                properties: {
-                    memoryId: {
-                        type: 'string',
-                        description: 'Unique identifier of the memory entry to update.',
-                    },
-                    content: {
-                        type: 'string',
-                        description: 'Updated memory text.',
-                    },
-                    isGlobal: {
-                        type: 'boolean',
-                        description: 'Set true to keep the fact global; omit or false to keep it agent-scoped.',
-                    },
-                },
-                required: ['memoryId', 'content'],
-            },
-        });
-    }
-
-    if (!tools.some((tool) => tool.name === MemoryToolNames.delete)) {
-        tools.push({
-            name: MemoryToolNames.delete,
-            description: spaceTrim(`
-                Delete a user memory that is no longer relevant. Deletions are soft so the record is hidden from future queries.
-            `),
-            parameters: {
-                type: 'object',
-                properties: {
-                    memoryId: {
-                        type: 'string',
-                        description: 'Unique identifier of the memory entry to delete.',
-                    },
-                },
-                required: ['memoryId'],
-            },
-        });
-    }
-
-    return tools;
-}

package/src/commitments/MEMORY/getMemoryCommitmentDocumentation.ts

@@ -1,47 +0,0 @@
-import { spaceTrim } from 'spacetrim';
-
-/**
- * Markdown documentation for MEMORY commitment.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function getMemoryCommitmentDocumentation(type: 'MEMORY' | 'MEMORIES'): string {
-    return spaceTrim(`
-        # ${type}
-
-        Enables persistent user memory for the current agent. The memory is stored by the runtime and can be retrieved in future conversations.
-
-        ## Key aspects
-
-        - Both \`MEMORY\` and \`MEMORIES\` work identically.
-        - Stores user-specific details through runtime tools.
-        - Retrieves relevant memories for personalized responses.
-        - Supports optional extra instructions in the commitment content.
-
-        ## Examples
-
-        \`\`\`book
-        Personal Assistant
-
-        PERSONA You are a personal productivity assistant
-        MEMORY Remember user projects and long-term preferences.
-        GOAL Help optimize daily productivity and workflow
-        \`\`\`
-
-        \`\`\`book
-        Learning Companion
-
-        PERSONA You are an educational companion for programming students
-        MEMORY Remember only the student's learning progress and preferred study style.
-        GOAL Provide progressive learning experiences tailored to student's pace
-        \`\`\`
-
-        \`\`\`book
-        Customer Support Agent
-
-        PERSONA You are a customer support representative
-        MEMORY Remember only important support history and communication preferences.
-        GOAL Provide personalized support based on customer history
-        \`\`\`
-    `);
-}

package/src/commitments/MEMORY/getMemoryToolRuntimeAdapterOrDisabledResult.ts

@@ -1,104 +0,0 @@
-import type {
-    DeleteMemoryToolResult,
-    MemoryToolAction,
-    MemoryToolResult,
-    MemoryToolRuntimeAdapter,
-    MemoryToolRuntimeContext,
-    RetrieveMemoryToolResult,
-    StoreMemoryToolResult,
-    UpdateMemoryToolResult,
-} from './MemoryToolRuntimeAdapter';
-import { getMemoryToolRuntimeAdapter } from './setMemoryToolRuntimeAdapter';
-
-/**
- * Builds a disabled memory-tool response payload.
- *
- * @private function of MemoryCommitmentDefinition
- */
-function createDisabledMemoryResult(action: MemoryToolAction, message: string): MemoryToolResult {
-    if (action === 'retrieve') {
-        return {
-            action,
-            status: 'disabled',
-            memories: [],
-            message,
-        };
-    }
-
-    if (action === 'store') {
-        return {
-            action,
-            status: 'disabled',
-            message,
-        };
-    }
-
-    if (action === 'update') {
-        return {
-            action,
-            status: 'disabled',
-            message,
-        };
-    }
-
-    if (action === 'delete') {
-        return {
-            action,
-            status: 'disabled',
-            message,
-        };
-    }
-
-    throw new Error(`Unsupported memory tool action: ${action}`);
-}
-
-/**
- * Return type of MEMORY adapter resolution helper.
- *
- * @private type of MemoryCommitmentDefinition
- */
-type MemoryToolRuntimeAdapterResolution = {
-    adapter: MemoryToolRuntimeAdapter | null;
-    disabledResult:
-        | RetrieveMemoryToolResult
-        | StoreMemoryToolResult
-        | UpdateMemoryToolResult
-        | DeleteMemoryToolResult
-        | null;
-};
-
-/**
- * Gets the runtime adapter and returns a disabled result when unavailable.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function getMemoryToolRuntimeAdapterOrDisabledResult(
-    action: MemoryToolAction,
-    runtimeContext: MemoryToolRuntimeContext,
-): MemoryToolRuntimeAdapterResolution {
-    if (!runtimeContext.enabled || runtimeContext.isTeamConversation || runtimeContext.isPrivateMode) {
-        const message = runtimeContext.isPrivateMode
-            ? 'Memory is disabled because private mode is active.'
-            : runtimeContext.isTeamConversation
-            ? 'Memory is disabled for TEAM conversations.'
-            : 'Memory is disabled for unauthenticated users.';
-
-        return {
-            adapter: null,
-            disabledResult: createDisabledMemoryResult(action, message),
-        };
-    }
-
-    const memoryToolRuntimeAdapter = getMemoryToolRuntimeAdapter();
-    if (!memoryToolRuntimeAdapter) {
-        return {
-            adapter: null,
-            disabledResult: createDisabledMemoryResult(action, 'Memory runtime is not available in this environment.'),
-        };
-    }
-
-    return {
-        adapter: memoryToolRuntimeAdapter,
-        disabledResult: null,
-    };
-}

package/src/commitments/MEMORY/getMemoryToolTitles.ts

@@ -1,16 +0,0 @@
-import type { string_javascript_name } from '../../types/string_person_fullname';
-import { MemoryToolNames } from './MemoryToolNames';
-
-/**
- * Gets human-readable titles for MEMORY tool functions.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function getMemoryToolTitles(): Record<string_javascript_name, string> {
-    return {
-        [MemoryToolNames.retrieve]: 'User memory',
-        [MemoryToolNames.store]: 'Store user memory',
-        [MemoryToolNames.update]: 'Update user memory',
-        [MemoryToolNames.delete]: 'Delete user memory',
-    };
-}

package/src/commitments/MEMORY/parseMemoryToolArgs.ts

@@ -1,126 +0,0 @@
-import type {
-    DeleteMemoryToolArgs,
-    RetrieveMemoryToolArgs,
-    StoreMemoryToolArgs,
-    UpdateMemoryToolArgs,
-} from './MemoryToolRuntimeAdapter';
-
-/**
- * Parsed retrieve memory arguments.
- *
- * @private type of MemoryCommitmentDefinition
- */
-type ParsedRetrieveMemoryArgs = {
-    query?: string;
-    limit?: number;
-};
-
-/**
- * Parsed store memory arguments.
- *
- * @private type of MemoryCommitmentDefinition
- */
-type ParsedStoreMemoryArgs = {
-    content: string;
-    isGlobal: boolean;
-};
-
-/**
- * Parsed update memory arguments.
- *
- * @private type of MemoryCommitmentDefinition
- */
-type ParsedUpdateMemoryArgs = {
-    memoryId: string;
-    content: string;
-    isGlobal?: boolean;
-};
-
-/**
- * Parsed delete memory arguments.
- *
- * @private type of MemoryCommitmentDefinition
- */
-type ParsedDeleteMemoryArgs = {
-    memoryId: string;
-};
-
-/**
- * Parses a memory identifier argument shared across MEMORY tools.
- *
- * @private function of MemoryCommitmentDefinition
- */
-function parseMemoryIdArg(value: unknown): string {
-    const memoryId = typeof value === 'string' ? value.trim() : '';
-    if (!memoryId) {
-        throw new Error('Memory id is required.');
-    }
-
-    return memoryId;
-}
-
-/**
- * Collection of MEMORY tool argument parsers.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export const parseMemoryToolArgs = {
-    /**
-     * Parses retrieve memory arguments.
-     */
-    retrieve(args: RetrieveMemoryToolArgs): ParsedRetrieveMemoryArgs {
-        const query = typeof args.query === 'string' ? args.query.trim() : undefined;
-        const limit =
-            typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.floor(args.limit) : undefined;
-
-        return {
-            query: query && query.length > 0 ? query : undefined,
-            limit: limit && limit > 0 ? Math.min(limit, 20) : undefined,
-        };
-    },
-
-    /**
-     * Parses store memory arguments.
-     */
-    store(args: StoreMemoryToolArgs): ParsedStoreMemoryArgs {
-        const content = typeof args.content === 'string' ? args.content.trim() : '';
-
-        if (!content) {
-            throw new Error('Memory content is required.');
-        }
-
-        return {
-            content,
-            isGlobal: args.isGlobal === true,
-        };
-    },
-
-    /**
-     * Parses update memory arguments.
-     */
-    update(args: UpdateMemoryToolArgs): ParsedUpdateMemoryArgs {
-        const memoryId = parseMemoryIdArg(args.memoryId);
-        const content = typeof args.content === 'string' ? args.content.trim() : '';
-
-        if (!content) {
-            throw new Error('Memory content is required.');
-        }
-
-        const isGlobal = typeof args.isGlobal === 'boolean' ? args.isGlobal : undefined;
-
-        return {
-            memoryId,
-            content,
-            isGlobal,
-        };
-    },
-
-    /**
-     * Parses delete memory arguments.
-     */
-    delete(args: DeleteMemoryToolArgs): ParsedDeleteMemoryArgs {
-        return {
-            memoryId: parseMemoryIdArg(args.memoryId),
-        };
-    },
-};

package/src/commitments/MEMORY/resolveMemoryRuntimeContext.ts

@@ -1,23 +0,0 @@
-import type { TODO_any } from '../../utils/organization/TODO_any';
-import { readToolRuntimeContextFromToolArgs } from '../_common/toolRuntimeContext';
-import type { MemoryToolRuntimeContext } from './MemoryToolRuntimeAdapter';
-
-/**
- * Resolves runtime context from hidden tool arguments.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function resolveMemoryRuntimeContext(args: Record<string, TODO_any>): MemoryToolRuntimeContext {
-    const runtimeContext = readToolRuntimeContextFromToolArgs(args);
-    const memoryContext = runtimeContext?.memory;
-
-    return {
-        enabled: memoryContext?.enabled === true,
-        userId: memoryContext?.userId,
-        username: memoryContext?.username,
-        agentId: memoryContext?.agentId,
-        agentName: memoryContext?.agentName,
-        isTeamConversation: memoryContext?.isTeamConversation === true,
-        isPrivateMode: memoryContext?.isPrivateMode === true,
-    };
-}

package/src/commitments/MEMORY/setMemoryToolRuntimeAdapter.ts

@@ -1,26 +0,0 @@
-import type { MemoryToolRuntimeAdapter } from './MemoryToolRuntimeAdapter';
-
-/**
- * Runtime adapter used by MEMORY tool functions.
- *
- * @private function of MemoryCommitmentDefinition
- */
-let memoryToolRuntimeAdapter: MemoryToolRuntimeAdapter | null = null;
-
-/**
- * Sets runtime adapter used by MEMORY commitment tools.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function setMemoryToolRuntimeAdapter(adapter: MemoryToolRuntimeAdapter | null): void {
-    memoryToolRuntimeAdapter = adapter;
-}
-
-/**
- * Gets runtime adapter used by MEMORY commitment tools.
- *
- * @private function of MemoryCommitmentDefinition
- */
-export function getMemoryToolRuntimeAdapter(): MemoryToolRuntimeAdapter | null {
-    return memoryToolRuntimeAdapter;
-}