@promptbook/cli 0.114.0-0 → 0.114.0-10

package/src/commitments/MEMORY/MemoryToolRuntimeAdapter.ts

@@ -1,180 +0,0 @@
-import type { TODO_any } from '../../utils/organization/TODO_any';
-
-/**
- * Tool arguments for retrieving memory.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type RetrieveMemoryToolArgs = {
-    query?: string;
-    limit?: number;
-    [key: string]: TODO_any;
-};
-
-/**
- * Tool arguments for storing memory.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type StoreMemoryToolArgs = {
-    content?: string;
-    isGlobal?: boolean;
-    [key: string]: TODO_any;
-};
-
-/**
- * Tool arguments for updating memory.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type UpdateMemoryToolArgs = {
-    memoryId?: string;
-    content?: string;
-    isGlobal?: boolean;
-    [key: string]: TODO_any;
-};
-
-/**
- * Tool arguments for deleting memory.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type DeleteMemoryToolArgs = {
-    memoryId?: string;
-    [key: string]: TODO_any;
-};
-
-/**
- * Memory record returned by runtime adapters.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type MemoryToolRecord = {
-    id?: string;
-    content: string;
-    isGlobal: boolean;
-    createdAt?: string;
-    updatedAt?: string;
-};
-
-/**
- * Runtime context for MEMORY tools resolved from hidden tool arguments.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type MemoryToolRuntimeContext = {
-    readonly enabled: boolean;
-    readonly userId?: number;
-    readonly username?: string;
-    readonly agentId?: string;
-    readonly agentName?: string;
-    readonly isTeamConversation: boolean;
-    readonly isPrivateMode: boolean;
-};
-
-/**
- * Result payload returned by retrieve memory tool.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type RetrieveMemoryToolResult = {
-    action: 'retrieve';
-    status: 'ok' | 'disabled' | 'error';
-    query?: string;
-    memories: MemoryToolRecord[];
-    message?: string;
-};
-
-/**
- * Result payload returned by store memory tool.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type StoreMemoryToolResult = {
-    action: 'store';
-    status: 'stored' | 'disabled' | 'error';
-    memory?: MemoryToolRecord;
-    message?: string;
-};
-
-/**
- * Result payload returned by update memory tool.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type UpdateMemoryToolResult = {
-    action: 'update';
-    status: 'updated' | 'disabled' | 'error';
-    memory?: MemoryToolRecord;
-    message?: string;
-};
-
-/**
- * Result payload returned by delete memory tool.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type DeleteMemoryToolResult = {
-    action: 'delete';
-    status: 'deleted' | 'disabled' | 'error';
-    memoryId?: string;
-    message?: string;
-};
-
-/**
- * Union of all MEMORY tool actions.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type MemoryToolAction =
-    | RetrieveMemoryToolResult['action']
-    | StoreMemoryToolResult['action']
-    | UpdateMemoryToolResult['action']
-    | DeleteMemoryToolResult['action'];
-
-/**
- * Union of all MEMORY tool result payloads.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type MemoryToolResult =
-    | RetrieveMemoryToolResult
-    | StoreMemoryToolResult
-    | UpdateMemoryToolResult
-    | DeleteMemoryToolResult;
-
-/**
- * Runtime adapter interface used by MEMORY tools.
- *
- * @private type of MemoryCommitmentDefinition
- */
-export type MemoryToolRuntimeAdapter = {
-    retrieveMemories(
-        args: {
-            query?: string;
-            limit?: number;
-        },
-        runtimeContext: MemoryToolRuntimeContext,
-    ): Promise<MemoryToolRecord[]>;
-    storeMemory(
-        args: {
-            content: string;
-            isGlobal: boolean;
-        },
-        runtimeContext: MemoryToolRuntimeContext,
-    ): Promise<MemoryToolRecord>;
-    updateMemory(
-        args: {
-            memoryId: string;
-            content: string;
-            isGlobal?: boolean;
-        },
-        runtimeContext: MemoryToolRuntimeContext,
-    ): Promise<MemoryToolRecord>;
-    deleteMemory(
-        args: {
-            memoryId: string;
-        },
-        runtimeContext: MemoryToolRuntimeContext,
-    ): Promise<{ id?: string }>;
-};

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',
-    };
-}