@zds-ai/cli 0.1.8 → 0.1.10

package/dist/agent/message-processor.js

@@ -0,0 +1,225 @@
+import { parseImagesFromMessage, hasImageReferences } from "../utils/image-encoder.js";
+import { Variable } from "./prompt-variables.js";
+/**
+ * Handles message processing, parsing, and transformation for the LLM agent
+ */
+export class MessageProcessor {
+    deps;
+    /** Stores prefill text from hooks */
+    hookPrefillText = null;
+    /**
+     * Creates a new MessageProcessor instance
+     * @param deps - Dependencies required for message processing
+     */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Processes rephrase commands and sets up rephrase state
+     * @param message - The input message to check for rephrase commands
+     * @returns Object containing rephrase information and processed message
+     */
+    async setupRephraseCommand(message) {
+        let isRephraseCommand = false;
+        let isSystemRephrase = false;
+        let messageToSend = message;
+        let messageType = "user";
+        let prefillText;
+        if (message.startsWith("/system rephrase")) {
+            isRephraseCommand = true;
+            isSystemRephrase = true;
+            messageToSend = message.substring(8).trim();
+            messageType = "system";
+            const prefillMatch = message.match(/^\/system rephrase\s+(.+)$/);
+            if (prefillMatch) {
+                prefillText = prefillMatch[1];
+            }
+        }
+        else if (message.startsWith("/rephrase")) {
+            isRephraseCommand = true;
+            messageToSend = message;
+            messageType = "user";
+            const prefillMatch = message.match(/^\/rephrase\s+(.+)$/);
+            if (prefillMatch) {
+                prefillText = prefillMatch[1];
+            }
+        }
+        if (isRephraseCommand) {
+            let lastAssistantIndex = -1;
+            for (let i = this.deps.chatHistory.length - 1; i >= 0; i--) {
+                if (this.deps.chatHistory[i].type === "assistant") {
+                    lastAssistantIndex = i;
+                    break;
+                }
+            }
+            if (lastAssistantIndex === -1) {
+                throw new Error("No previous assistant message to rephrase");
+            }
+            this.deps.setRephraseState(lastAssistantIndex, this.deps.chatHistory.length, -1, messageType, prefillText);
+        }
+        return { isRephraseCommand, messageType, messageToSend, prefillText };
+    }
+    /**
+     * Parses message content and assembles it with variables
+     * @param messageToSend - The message to parse and assemble
+     * @returns Object containing parsed content and assembled message
+     */
+    async parseAndAssembleMessage(messageToSend) {
+        const parsed = hasImageReferences(messageToSend)
+            ? parseImagesFromMessage(messageToSend)
+            : { text: messageToSend, images: [] };
+        Variable.set("USER:PROMPT", parsed.text);
+        const assembledMessage = Variable.renderFull("USER");
+        return { parsed, assembledMessage };
+    }
+    /**
+     * Prepares message content for LLM consumption, handling images and content types
+     * @param messageType - Type of message ("user" or "system")
+     * @param assembledMessage - The assembled message text
+     * @param parsed - Parsed message content including images
+     * @param messageToSend - Original message to send
+     * @param supportsVision - Whether the LLM supports vision/images
+     * @returns Object containing user entry and formatted message content
+     */
+    prepareMessageContent(messageType, assembledMessage, parsed, messageToSend, supportsVision) {
+        let messageContent = assembledMessage;
+        if (messageType === "user" && parsed.images.length > 0 && supportsVision) {
+            messageContent = [
+                { type: "text", text: assembledMessage },
+                ...parsed.images
+            ];
+        }
+        const userEntry = {
+            type: messageType,
+            content: messageContent,
+            originalContent: messageType === "user" ? (parsed.images.length > 0 && supportsVision
+                ? [{ type: "text", text: parsed.text }, ...parsed.images]
+                : parsed.text) : undefined,
+            timestamp: new Date(),
+        };
+        return { userEntry, messageContent };
+    }
+    /**
+     * Parse XML-formatted tool calls from message content (x.ai format)
+     * Converts <xai:function_call> elements to standard LLMToolCall format
+     * @param message - Message object that may contain XML tool calls
+     * @returns Modified message with parsed tool calls
+     */
+    parseXMLToolCalls(message) {
+        if (!message.content || typeof message.content !== 'string') {
+            return message;
+        }
+        const content = message.content;
+        const xmlToolCallRegex = /<xai:function_call\s+name="([^"]+)">([\s\S]*?)<\/xai:function_call>/g;
+        const matches = Array.from(content.matchAll(xmlToolCallRegex));
+        if (matches.length === 0) {
+            return message;
+        }
+        // Parse each XML tool call
+        const toolCalls = [];
+        let cleanedContent = content;
+        for (const match of matches) {
+            const functionName = match[1];
+            const paramsXML = match[2];
+            // Parse parameters
+            const paramRegex = /<parameter\s+name="([^"]+)">([^<]*)<\/parameter>/g;
+            const paramMatches = Array.from(paramsXML.matchAll(paramRegex));
+            const args = {};
+            for (const paramMatch of paramMatches) {
+                args[paramMatch[1]] = paramMatch[2];
+            }
+            // Generate a unique ID for this tool call
+            const toolCallId = `call_xml_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+            toolCalls.push({
+                id: toolCallId,
+                type: "function",
+                function: {
+                    name: functionName,
+                    arguments: JSON.stringify(args)
+                }
+            });
+            // Remove this XML block from content
+            cleanedContent = cleanedContent.replace(match[0], '');
+        }
+        // Trim any extra whitespace
+        cleanedContent = cleanedContent.trim();
+        // Return modified message with tool_calls and cleaned content
+        return {
+            ...message,
+            content: cleanedContent || null,
+            tool_calls: [...(message.tool_calls || []), ...toolCalls]
+        };
+    }
+    /**
+     * Reduces streaming message chunks into a complete message object
+     * @param previous - Previously accumulated message data
+     * @param item - Current streaming chunk to process
+     * @returns Updated accumulated message object
+     */
+    messageReducer(previous, item) {
+        const reduce = (acc, delta) => {
+            // Ensure acc is always an object before spreading (handles null/undefined)
+            acc = { ...(acc || {}) };
+            for (const [key, value] of Object.entries(delta)) {
+                // Skip null values in delta (Venice sends tool_calls: null which breaks Object.entries)
+                if (value === null)
+                    continue;
+                if (acc[key] === undefined || acc[key] === null) {
+                    acc[key] = value;
+                    // Clean up index properties from tool calls
+                    if (Array.isArray(acc[key])) {
+                        for (const arr of acc[key]) {
+                            delete arr.index;
+                        }
+                    }
+                }
+                else if (typeof acc[key] === "string" && typeof value === "string") {
+                    // Don't concatenate certain properties that should remain separate
+                    const nonConcatenableProps = ['id', 'type', 'name'];
+                    if (nonConcatenableProps.includes(key)) {
+                        // For non-concatenable properties, keep the new value
+                        acc[key] = value;
+                    }
+                    else {
+                        // For content, arguments, and other text properties, concatenate
+                        acc[key] += value;
+                    }
+                }
+                else if (Array.isArray(acc[key]) && Array.isArray(value)) {
+                    const accArray = acc[key];
+                    for (let i = 0; i < value.length; i++) {
+                        if (!accArray[i])
+                            accArray[i] = {};
+                        accArray[i] = reduce(accArray[i], value[i]);
+                    }
+                }
+                else if (typeof acc[key] === "object" && typeof value === "object") {
+                    acc[key] = reduce(acc[key], value);
+                }
+            }
+            return acc;
+        };
+        return reduce(previous, item.choices?.[0]?.delta || {});
+    }
+    /**
+     * Gets the current hook prefill text
+     * @returns The prefill text or null if none is set
+     */
+    getHookPrefillText() {
+        return this.hookPrefillText;
+    }
+    /**
+     * Clears the hook prefill text
+     */
+    clearHookPrefillText() {
+        this.hookPrefillText = null;
+    }
+    /**
+     * Sets the hook prefill text
+     * @param text - The prefill text to set
+     */
+    setHookPrefillText(text) {
+        this.hookPrefillText = text;
+    }
+}
+//# sourceMappingURL=message-processor.js.map

package/dist/agent/message-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-processor.js","sourceRoot":"","sources":["../../src/agent/message-processor.ts"],"names":[],"mappings":"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"}

package/dist/agent/prompt-variables.d.ts

@@ -1,16 +1,28 @@
+/**
+ * Variable definition class for prompt template system
+ * Defines structure, behavior, and relationships between variables
+ */
 export declare class VariableDef {
     /**
      * Map of variable names to their definitions
      * Indexed by variable name (e.g., "USER:PRE" -> VariableDef)
      */
     private static definitions;
+    /** Variable name (e.g., "USER:PRE", "SYSTEM") */
     name: string;
+    /** Rendering weight for ordering (lower = earlier) */
     weight: number;
+    /** Environment variable to read value from */
     env_var?: string;
+    /** Whether to render in full template expansion */
     renderFull: boolean;
+    /** Whether variable persists across clearOneShot() calls */
     persists: boolean;
+    /** Template string with %VAR% placeholders and %% for own content */
     template: string;
+    /** Variables referenced in template (%VAR% patterns) */
     adoptedChildren: string[];
+    /** Function to dynamically compute variable value */
     getter?: () => string;
     constructor(config: {
         name: string;
@@ -24,24 +36,56 @@ export declare class VariableDef {
     /**
      * Get or create definition by name
      * Looks in definitions map, then PROMPT_VARS, then creates default
+     *
      * @param name Variable name
      * @returns VariableDef instance
      */
     static getOrCreate(name: string): VariableDef;
     /**
      * Get all variable definitions
+     * Ensures all PROMPT_VARS are loaded into definitions map
+     * Later definitions override earlier ones (YAML overrides hardcoded)
+     *
      * @returns Array of all VariableDef instances
      */
     static getAllDefinitions(): VariableDef[];
+    /**
+     * Check if a variable is intrinsic (hardcoded in TypeScript)
+     *
+     * @param name Variable name
+     * @returns True if defined in INTRINSIC_VARS
+     */
+    static isIntrinsic(name: string): boolean;
+    /**
+     * Check if a variable is explicit (defined in external YAML file)
+     *
+     * @param name Variable name
+     * @returns True if defined in EXTERNAL_VARS
+     */
+    static isExplicit(name: string): boolean;
 }
+/**
+ * Variable instance class for prompt template system
+ * Holds actual values and handles rendering logic
+ *
+ * Supports:
+ * - Hierarchical variable relationships (parent:child)
+ * - Template expansion with %VAR% placeholders
+ * - Dynamic value computation via getters
+ * - Circular dependency detection
+ * - Weight-based ordering
+ */
 export declare class Variable {
     /**
      * Map of variable names to their current values
      * Indexed by variable name (e.g., "USER:PRE" -> Variable)
      */
     private static variables;
+    /** Variable definition (structure and behavior) */
     def: VariableDef;
+    /** Array of string values for this variable */
     values: string[];
+    /** Whether variable has new/changed values since last render */
     isNew: boolean;
     constructor(name: string);
     get name(): string;
@@ -50,88 +94,107 @@ export declare class Variable {
     get renderFull(): boolean;
     get persists(): boolean;
     /**
-     * Set variable value
+     * Set variable value (replaces existing values)
      * Creates variable if it doesn't exist
+     *
      * @param name Variable name
-     * @param value Value to add
+     * @param value Value to set
      */
     static set(name: string, value: string): void;
+    /**
+     * Append value to variable (adds to existing values)
+     * Creates variable if it doesn't exist
+     * Use when building multi-value variables within same execution context
+     *
+     * @param name Variable name
+     * @param value Value to append
+     */
+    static append(name: string, value: string): void;
     /**
      * Get variable by name
+     *
      * @param name Variable name
      * @returns Variable instance or undefined
      */
     static get(name: string): Variable | undefined;
+    /**
+     * Get or create variable by name
+     *
+     * @param name Variable name
+     * @returns Variable instance
+     */
+    static getOrCreate(name: string): Variable;
     /**
      * Get all set variables
+     *
      * @returns Array of all Variable instances
      */
     static getAllVariables(): Variable[];
     /**
      * Clear all one-shot variables
+     * Removes variables where persists=false
      */
     static clearOneShot(): void;
     /**
-     * Find birth child variables of given parent.  Return sorted.
+     * Export persistent variables for saving to context.json
+     * Returns only variables with persists=true
      *
-     * Returns birth children (prefix match) of a parent var, sorted by weight,
-     * where renderFull == true.
+     * @returns Object with variable names as keys and objects containing values and isNew state
+     */
+    static exportPersistentVariables(): Record<string, {
+        values: string[];
+        isNew: boolean;
+    }>;
+    /**
+     * Import persistent variables from saved context.json
+     * Restores variables with their values and isNew state
      *
-     * @param parent: string
-     *   Parent name (e.g., "USER" or "SYSTEM")
+     * @param saved Object with variable names as keys and objects containing values and isNew state
+     */
+    static importPersistentVariables(saved: Record<string, {
+        values: string[];
+        isNew: boolean;
+    }>): void;
+    /**
+     * Find birth child variables of given parent
+     * Returns variables with prefix "parent:" sorted by weight
      *
-     * @returns variables[]
-     *   All variables with prefix "parent:", renderFull=true, sorted by weight
+     * @param parent Parent name (e.g., "USER" or "SYSTEM")
+     * @returns Variables with prefix "parent:", renderFull=true, sorted by weight
      */
     static findBirthChildren(parent: string): Variable[];
     /**
-     * Find all full child variables of given parent.  Return sorted.
-     *
-     * Returns all children of a parent var, sorted by weight,
-     * where renderFull == true.  Includes both birth children
-     * (prefix match "parent:") and adopted children (from template).
+     * Find all child variables of given parent
+     * Returns both birth children (prefix match) and adopted children (template refs)
      *
-     * @param parent: string
-     *   Parent name (e.g., "USER")
-     *
-     * @returns variables[]
-     *   All variables with prefix "parent:", renderFull=true, sorted by weight
+     * @param parent Parent name (e.g., "USER")
+     * @returns All child variables with renderFull=true, sorted by weight
      */
     static findFullChildrenVars(parent: string): Variable[];
     /**
-     * Render a variable fully (recursive)
-     * If variable exists, renders its template (which may reference children)
-     * If variable doesn't exist but children do, renders children and joins
-     * If variable doesn't exist but has a getter, auto-creates it
+     * Render a variable fully with recursive template expansion
+     * Handles variable creation, getter execution, and circular dependency detection
+     *
      * @param name Variable name (e.g., "USER" or "USER:PROMPT")
      * @param renderingStack Set of variables currently being rendered (for cycle detection)
      * @returns Rendered string
      */
     static renderFull(name: string, renderingStack?: Set<string>): string;
     /**
-     * Render full value string using template.
+     * Render variable using its template with placeholder substitution
+     * Handles %VAR% substitution and %% replacement with own values + children
      *
      * @param renderingStack Set of variables currently being rendered (for cycle detection)
-     * @returns string
-     *   Rendered string
+     * @returns Rendered template string
      */
     renderFullTemplate(renderingStack?: Set<string>): string;
     /**
-     * Render full values as a string, from values array.
-     *
-     * If this variable has a getter function, computes the current value
-     * and updates values array only if the value changed (sets isNew flag).
-     *
-     * After rendering, clears the isNew flag since the variable has been consumed.
-     *
-     * ASSUMPTION: Getter functions always return a single string value,
-     * never an array. If this assumption changes, this logic needs revision.
-     *
-     * @param separator: string
-     *   The string to use as a separator.  Defaults to "\n\n".
+     * Render variable values as string with dynamic getter support
+     * Updates values from getter if present and value changed
+     * Clears isNew flag after rendering
      *
-     * @returns string
-     *   values joined as a string (double-nl-separated)
+     * @param separator String to join multiple values (default: "\n")
+     * @returns Joined values string
      */
     renderFullValue(separator?: string): string;
 }