indusagi-coding-agent 0.1.23 → 0.1.25

package/dist/modes/shared.d.ts

@@ -0,0 +1,386 @@
+/**
+ * Shared Utilities for All Execution Modes
+ *
+ * This module provides common utilities, validators, and formatters used across all three
+ * execution modes (interactive, print, RPC).
+ *
+ * Purpose:
+ * --------
+ * - Centralize common functionality to avoid duplication
+ * - Ensure consistent behavior across modes
+ * - Provide standard data transformation and validation
+ *
+ * Usage by Modes:
+ * ---------------
+ * INTERACTIVE MODE:
+ *   - Uses formatDuration for displaying execution times
+ *   - Uses validatePrompt for user input validation
+ *   - Uses extractSessionId for session switching
+ *
+ * PRINT MODE:
+ *   - Uses createOutputFormatter to format results as JSON/text
+ *   - Uses escapeJsonString for JSON output
+ *   - Uses formatErrorMessage for error reporting
+ *
+ * RPC MODE:
+ *   - Uses parseSessionPath for session resolution
+ *   - Uses validatePrompt for incoming RPC requests
+ *   - Uses escapeJsonString for JSON-RPC responses
+ *
+ * Architecture:
+ * -------------
+ * This module acts as a utility facade, providing a single source of truth for:
+ * 1. Data transformation (format functions)
+ * 2. Input validation (validate functions)
+ * 3. Error handling (error formatting)
+ * 4. Conversion utilities (token counts, durations)
+ *
+ * All functions are pure (no side effects) and stateless for maximum reusability.
+ */
+/**
+ * Output format type for print mode
+ * - 'json': Machine-readable JSON lines format
+ * - 'text': Human-readable plain text format
+ * - 'compact': Minimal output (status only)
+ */
+export type OutputFormat = 'json' | 'text' | 'compact';
+/**
+ * Validation result with error details
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Output formatter interface used by all modes
+ */
+export interface OutputFormatter {
+    format(data: unknown): string;
+    formatError(error: Error): string;
+    getContentType(): string;
+}
+/**
+ * Create an output formatter for a specific format type
+ *
+ * Factory function that returns a formatter implementing the OutputFormatter interface.
+ * Each formatter knows how to convert data to its target output format.
+ *
+ * Formats:
+ * - 'json': Outputs JSON lines (each event as a JSON object)
+ * - 'text': Outputs human-readable text with formatting
+ * - 'compact': Outputs minimal status information
+ *
+ * Usage:
+ * ------
+ * PRINT MODE:
+ *   const formatter = createOutputFormatter('json');
+ *   console.log(formatter.format(agentResponse));
+ *   console.error(formatter.formatError(error));
+ *
+ * @param format - Output format type ('json' | 'text' | 'compact')
+ * @returns OutputFormatter instance for the specified format
+ *
+ * @example
+ * // JSON output for event streaming
+ * const jsonFormatter = createOutputFormatter('json');
+ * process.stdout.write(jsonFormatter.format(event));
+ *
+ * @example
+ * // Text output for human readers
+ * const textFormatter = createOutputFormatter('text');
+ * process.stdout.write(textFormatter.format(response));
+ *
+ * @throws Error if format is not recognized
+ */
+export declare function createOutputFormatter(format: OutputFormat): OutputFormatter;
+/**
+ * Parse and validate a session path/ID
+ *
+ * Extracts and validates session identifiers. Supports multiple formats:
+ * - UUID: "550e8400-e29b-41d4-a716-446655440000"
+ * - Filename: "session-123.jsonl"
+ * - Path: "/home/user/.indusagi/sessions/session-123.jsonl"
+ *
+ * Returns parsed session ID or throws ValidationError if invalid.
+ *
+ * Usage:
+ * ------
+ * RPC MODE:
+ *   const sessionId = parseSessionPath(request.params.sessionId);
+ *   const session = sessionManager.load(sessionId);
+ *
+ * INTERACTIVE MODE:
+ *   const sessionId = parseSessionPath(userInput);
+ *   // Used in session switching command
+ *
+ * @param path - Session ID, filename, or filesystem path
+ * @returns Normalized session UUID
+ *
+ * @example
+ * parseSessionPath('550e8400-e29b-41d4-a716-446655440000')
+ * // Returns: '550e8400-e29b-41d4-a716-446655440000'
+ *
+ * @example
+ * parseSessionPath('session-123.jsonl')
+ * // Returns: 'session-123' (extracts ID from filename)
+ *
+ * @throws Error if path is empty or invalid format
+ */
+export declare function parseSessionPath(path: string): string;
+/**
+ * Validate user input/prompt
+ *
+ * Checks if a prompt is valid for sending to the agent.
+ *
+ * Validation rules:
+ * - Non-empty (after trimming whitespace)
+ * - No longer than 100,000 characters (prevents DOS)
+ * - Must be a string
+ *
+ * Returns ValidationResult with detailed error information if invalid.
+ *
+ * Usage:
+ * ------
+ * INTERACTIVE MODE:
+ *   const result = validatePrompt(userInput);
+ *   if (!result.valid) {
+ *     showError(result.error);
+ *     return;
+ *   }
+ *   session.prompt(userInput);
+ *
+ * RPC MODE:
+ *   const result = validatePrompt(request.message);
+ *   if (!result.valid) {
+ *     return rpcError(-32602, result.error);
+ *   }
+ *
+ * @param prompt - User input to validate
+ * @returns ValidationResult with valid flag and optional error message
+ *
+ * @example
+ * validatePrompt('What does this code do?')
+ * // Returns: { valid: true }
+ *
+ * @example
+ * validatePrompt('  ')
+ * // Returns: { valid: false, error: 'Prompt cannot be empty' }
+ *
+ * @example
+ * validatePrompt('x'.repeat(100001))
+ * // Returns: { valid: false, error: 'Prompt exceeds maximum length (100000)' }
+ */
+export declare function validatePrompt(prompt: unknown): ValidationResult;
+/**
+ * Format milliseconds to human-readable duration string
+ *
+ * Converts milliseconds into a readable format like "1h 23m 45s 123ms".
+ * Omits zero values and units for brevity.
+ *
+ * Examples:
+ * - 1000 ms → "1s"
+ * - 61000 ms → "1m 1s"
+ * - 3661000 ms → "1h 1m 1s"
+ *
+ * Usage:
+ * ------
+ * INTERACTIVE MODE:
+ *   const elapsed = Date.now() - startTime;
+ *   footer.text = `Completed in ${formatDuration(elapsed)}`;
+ *
+ * PRINT MODE:
+ *   console.log(`"elapsed_time": "${formatDuration(duration)}"`);
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string
+ *
+ * @example
+ * formatDuration(1234567)  // "20m 34s 567ms"
+ *
+ * @example
+ * formatDuration(5000)     // "5s"
+ *
+ * @example
+ * formatDuration(0)        // "0ms"
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format token count with usage estimates
+ *
+ * Converts a token count into a readable format with estimates of cost/usage:
+ * - Shows raw token count
+ * - Estimates word count (roughly 0.75 words per token)
+ * - Estimates cost at $0.002 per 1000 tokens (GPT-4 average)
+ *
+ * Useful for displaying resource usage in logs and UI.
+ *
+ * Usage:
+ * ------
+ * PRINT MODE:
+ *   const formatted = formatTokens(response.usage.total_tokens);
+ *   console.log(`Tokens: ${formatted}`);
+ *
+ * INTERACTIVE MODE:
+ *   footer.text = `Tokens: ${formatTokens(totalTokens)}`;
+ *
+ * @param tokens - Number of tokens used
+ * @returns Formatted string with tokens, word estimate, and cost estimate
+ *
+ * @example
+ * formatTokens(1500)
+ * // Returns: "1,500 tokens (~1,125 words, ~$0.003 cost)"
+ *
+ * @example
+ * formatTokens(0)
+ * // Returns: "0 tokens"
+ */
+export declare function formatTokens(tokens: number): string;
+/**
+ * Extract session ID from user input
+ *
+ * Parses user input to extract a session ID. Handles multiple formats:
+ * - Direct UUID
+ * - Filenames with session ID
+ * - Prefixes like "session:uuid"
+ *
+ * Returns null if no valid session ID found.
+ *
+ * Usage:
+ * ------
+ * INTERACTIVE MODE:
+ *   // User types: "/switch 550e8400-e29b-41d4-a716-446655440000"
+ *   const sessionId = extractSessionId(userInput);
+ *   if (sessionId) interactiveMode.switchSession(sessionId);
+ *
+ * @param input - User input string
+ * @returns Session ID if found, null otherwise
+ *
+ * @example
+ * extractSessionId('session:550e8400-e29b-41d4-a716-446655440000')
+ * // Returns: '550e8400-e29b-41d4-a716-446655440000'
+ *
+ * @example
+ * extractSessionId('/switch my-session-123')
+ * // Returns: 'my-session-123'
+ *
+ * @example
+ * extractSessionId('invalid input')
+ * // Returns: null
+ */
+export declare function extractSessionId(input: string): string | null;
+/**
+ * Escape string for safe JSON output
+ *
+ * Properly escapes special characters for JSON strings:
+ * - Quotes: " → \"
+ * - Backslashes: \ → \\
+ * - Newlines: \n, \r, \t etc
+ * - Control characters
+ *
+ * Usage:
+ * ------
+ * PRINT MODE:
+ *   const jsonLine = `{"message": "${escapeJsonString(message)}"}`;
+ *   console.log(jsonLine);
+ *
+ * RPC MODE:
+ *   const response = {
+ *     message: escapeJsonString(plainText)
+ *   };
+ *   sendJsonRpc(response);
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for JSON output
+ *
+ * @example
+ * escapeJsonString('Hello "World"\n')
+ * // Returns: 'Hello \"World\"\\n'
+ *
+ * @example
+ * escapeJsonString('Path: C:\\Users\\test')
+ * // Returns: 'Path: C:\\\\Users\\\\test'
+ */
+export declare function escapeJsonString(str: string): string;
+/**
+ * Format error message for display
+ *
+ * Converts an Error object into a formatted error message suitable for:
+ * - Terminal display (interactive mode)
+ * - Log output (print mode)
+ * - JSON responses (RPC mode)
+ *
+ * Includes error message, type, and optional stack trace (if DEBUG enabled).
+ *
+ * Usage:
+ * ------
+ * INTERACTIVE MODE:
+ *   try {
+ *     await session.prompt(input);
+ *   } catch (error) {
+ *     displayError(formatErrorMessage(error));
+ *   }
+ *
+ * PRINT MODE:
+ *   process.stderr.write(formatErrorMessage(error));
+ *   process.exit(1);
+ *
+ * RPC MODE:
+ *   catch (error) {
+ *     response.error = formatErrorMessage(error);
+ *   }
+ *
+ * @param error - Error object or string
+ * @returns Formatted error message string
+ *
+ * @example
+ * const error = new Error('Invalid session');
+ * formatErrorMessage(error)
+ * // Returns: 'Error: Invalid session'
+ *
+ * @example
+ * formatErrorMessage('Something went wrong')
+ * // Returns: 'Something went wrong'
+ */
+export declare function formatErrorMessage(error: unknown): string;
+/**
+ * Determine if session should be auto-saved
+ *
+ * Checks configuration and state to determine whether to automatically persist
+ * the session to disk.
+ *
+ * Auto-save is enabled when:
+ * - config.autoSave is true
+ * - Session has been modified (dirty flag)
+ * - Minimum time interval has passed since last save
+ *
+ * Usage:
+ * ------
+ * INTERACTIVE MODE:
+ *   if (shouldAutoSave(config)) {
+ *     await sessionManager.save(session);
+ *   }
+ *
+ * @param config - Configuration object with autoSave setting
+ * @returns Boolean indicating if session should be auto-saved
+ *
+ * @example
+ * const config = { autoSave: true, autoSaveInterval: 30000 };
+ * if (shouldAutoSave(config)) {
+ *   sessionManager.save(currentSession);
+ * }
+ */
+export declare function shouldAutoSave(config: any): boolean;
+declare const _default: {
+    createOutputFormatter: typeof createOutputFormatter;
+    parseSessionPath: typeof parseSessionPath;
+    validatePrompt: typeof validatePrompt;
+    formatDuration: typeof formatDuration;
+    formatTokens: typeof formatTokens;
+    extractSessionId: typeof extractSessionId;
+    escapeJsonString: typeof escapeJsonString;
+    formatErrorMessage: typeof formatErrorMessage;
+    shouldAutoSave: typeof shouldAutoSave;
+};
+export default _default;
+//# sourceMappingURL=shared.d.ts.map

package/dist/modes/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/modes/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IAClC,cAAc,IAAI,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAW3E;AAmED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CA2BhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAsBjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAczD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAInD;;;;;;;;;;;;AAED,wBAUE"}