@portel/photon 1.7.0 → 1.8.1

package/dist/photon-cli-runner.js

@@ -30,177 +30,52 @@ async function resolvePhotonPathWithBundled(name) {
     return resolvePhotonPath(name);
 }
 import { PhotonDocExtractor } from './photon-doc-extractor.js';
-import { isDaemonRunning, startDaemon } from './daemon/manager.js';
+import { isGlobalDaemonRunning, startGlobalDaemon } from './daemon/manager.js';
 import { sendCommand, pingDaemon } from './daemon/client.js';
 import { formatOutput as baseFormatOutput, renderNone, formatKey, } from './cli-formatter.js';
-import { getErrorMessage } from './shared/error-handler.js';
-import { logger } from './shared/logger.js';
+import { getErrorMessage, exitWithError, ExitCode } from './shared/error-handler.js';
 /**
  * Extract all public async methods from a photon file
  */
 async function extractMethods(filePath) {
     const source = await fs.readFile(filePath, 'utf-8');
     const extractor = new SchemaExtractor();
-    const methods = [];
-    // Extract methods using the schema extractor
-    // Also match async generator methods (async *methodName) and static methods
-    const methodMatches = source.matchAll(/(?:static\s+)?async\s+\*?\s*(\w+)\s*\(([^)]*)\)/g);
-    for (const match of methodMatches) {
-        const methodName = match[1];
-        const methodParams = match[2];
-        // Skip private methods and lifecycle hooks
-        if (methodName.startsWith('_') ||
-            methodName === 'onInitialize' ||
-            methodName === 'onShutdown') {
-            continue;
-        }
-        // Extract method signature
-        const methodIndex = match.index;
-        const precedingContent = source.substring(0, methodIndex);
-        // Find JSDoc comment
-        const lastJSDocStart = precedingContent.lastIndexOf('/**');
-        if (lastJSDocStart === -1)
-            continue;
-        const jsdocSection = precedingContent.substring(lastJSDocStart);
-        const jsdocMatch = jsdocSection.match(/\/\*\*([\s\S]*?)\*\/\s*$/);
-        if (!jsdocMatch)
-            continue;
-        const jsdoc = jsdocMatch[1];
-        // Extract description
-        const descMatch = jsdoc.match(/^\s*\*\s*(.+?)(?=\n\s*\*\s*@|\n\s*$)/s);
-        const description = descMatch
-            ? descMatch[1]
-                .split('\n')
-                .map((line) => line.replace(/^\s*\*\s?/, '').trim())
-                .join(' ')
-                .trim()
-            : undefined;
-        // Parse TypeScript parameter types and optionality from method signature
-        const tsParamTypes = new Map();
-        const tsParamOptional = new Map();
-        if (methodParams.trim()) {
-            // Extract: params?: { mute?: boolean } | boolean
-            const paramTypeMatch = methodParams.match(/(\w+)(\??):\s*(.+)/);
-            if (paramTypeMatch) {
-                const tsParamName = paramTypeMatch[1];
-                const isParamOptional = paramTypeMatch[2] === '?';
-                const paramType = paramTypeMatch[3].trim();
-                // Extract base type (handle unions like "{ mute?: boolean } | boolean")
-                const baseType = extractBaseType(paramType);
-                // Store type for both the TS param name and any inner property names
-                tsParamTypes.set(tsParamName, baseType);
-                tsParamOptional.set(tsParamName, isParamOptional);
-                // Also extract inner object properties: { mute?: boolean }
-                const innerProps = extractObjectProperties(paramType);
-                for (const [propName, propInfo] of innerProps) {
-                    tsParamTypes.set(propName, propInfo.type);
-                    // If the parent param is optional, inner properties are also optional
-                    tsParamOptional.set(propName, isParamOptional || propInfo.optional);
-                }
-            }
-        }
-        // Extract format hint from @format tag (structural and content formats)
-        let format;
-        // Match structural formats (including card, tabs, accordion)
-        const structuralMatch = jsdoc.match(/@format\s+(primitive|table|tree|list|card|tabs|accordion|none)/i);
-        if (structuralMatch) {
-            format = structuralMatch[1].toLowerCase();
-        }
-        // Match content formats
-        else {
-            const contentMatch = jsdoc.match(/@format\s+(json|markdown|yaml|xml|html)/i);
-            if (contentMatch) {
-                format = contentMatch[1].toLowerCase();
-            }
-            else {
-                // Match code format (with optional language)
-                const codeMatch = jsdoc.match(/@format\s+code(?::(\w+))?/i);
-                if (codeMatch) {
-                    format = codeMatch[1] ? `code:${codeMatch[1]}` : 'code';
-                }
-            }
-        }
-        // Extract parameters
+    const metadata = extractor.extractAllFromSource(source);
+    return metadata.tools.map((tool) => {
         const params = [];
-        const paramRegex = /@param\s+(\w+)\s+(.+?)(?=\n\s*\*\s*@|\n\s*\*\/|\n\s*$)/gs;
-        let paramMatch;
-        while ((paramMatch = paramRegex.exec(jsdoc)) !== null) {
-            const paramName = paramMatch[1];
-            const paramDesc = paramMatch[2].trim();
-            // Extract custom label from {@label displayName} tag
-            const labelMatch = paramDesc.match(/\{@label\s+([^}]+)\}/);
-            const customLabel = labelMatch ? labelMatch[1].trim() : undefined;
-            // Extract {@example ...} - handle nested braces/brackets for JSON
-            let example;
-            const exampleStart = paramDesc.indexOf('{@example ');
-            if (exampleStart !== -1) {
-                const contentStart = exampleStart + '{@example '.length;
-                let braceDepth = 0;
-                let bracketDepth = 0;
-                let i = contentStart;
-                let inString = false;
-                while (i < paramDesc.length) {
-                    const ch = paramDesc[i];
-                    const prevCh = i > 0 ? paramDesc[i - 1] : '';
-                    if (ch === '"' && prevCh !== '\\') {
-                        inString = !inString;
-                    }
-                    else if (!inString) {
-                        if (ch === '{')
-                            braceDepth++;
-                        else if (ch === '[')
-                            bracketDepth++;
-                        else if (ch === ']')
-                            bracketDepth--;
-                        else if (ch === '}') {
-                            if (braceDepth === 0 && bracketDepth === 0) {
-                                example = paramDesc.substring(contentStart, i).trim();
-                                break;
-                            }
-                            braceDepth--;
-                        }
-                    }
-                    i++;
+        const schema = tool.inputSchema;
+        if (schema?.properties) {
+            for (const [name, prop] of Object.entries(schema.properties)) {
+                // Resolve type from anyOf/oneOf union schemas (e.g. number | string)
+                let type = prop.type;
+                if (!type && (prop.anyOf || prop.oneOf)) {
+                    const variants = (prop.anyOf || prop.oneOf);
+                    type = variants
+                        .map((v) => v.type)
+                        .filter(Boolean)
+                        .join(' | ');
                 }
+                params.push({
+                    name,
+                    type: type || 'any',
+                    optional: !schema.required?.includes(name),
+                    description: prop.description,
+                    ...(prop.title ? { label: prop.title } : {}),
+                    ...(prop.examples?.[0] !== undefined ? { example: String(prop.examples[0]) } : {}),
+                    ...(prop.enum ? { enum: prop.enum.map(String) } : {}),
+                });
             }
-            // Remove {@example ...} tag (handles nested braces/brackets)
-            let cleanedParamDesc = paramDesc;
-            if (exampleStart !== -1 && example) {
-                // Remove the full {@example ...} tag we extracted
-                const tagEnd = exampleStart + '{@example '.length + example.length + 1; // +1 for closing }
-                cleanedParamDesc = paramDesc.substring(0, exampleStart) + paramDesc.substring(tagEnd);
-            }
-            // Remove remaining JSDoc constraint tags for display
-            const cleanDesc = cleanedParamDesc
-                .replace(/\{@\w+[^}]*\}/g, '')
-                .replace(/\(optional\)/gi, '')
-                .replace(/\(default:.*?\)/gi, '')
-                .trim();
-            // Check optional from TypeScript signature first, fallback to JSDoc
-            const tsOptional = tsParamOptional.get(paramName);
-            const jsdocOptional = /\(optional\)/i.test(paramDesc) || /\(default:/i.test(paramDesc);
-            const optional = tsOptional !== undefined ? tsOptional : jsdocOptional;
-            params.push({
-                name: paramName,
-                type: tsParamTypes.get(paramName) || 'any',
-                optional,
-                description: cleanDesc,
-                ...(customLabel ? { label: customLabel } : {}),
-                ...(example ? { example } : {}),
-            });
         }
-        // Extract button label from @returns {@label ...} tag
-        const returnsMatch = jsdoc.match(/@returns?\s+.*?\{@label\s+([^}]+)\}/i);
-        const buttonLabel = returnsMatch ? returnsMatch[1].trim() : undefined;
-        methods.push({
-            name: methodName,
+        return {
+            name: tool.name,
             params,
-            description,
-            ...(format ? { format } : {}),
-            ...(buttonLabel ? { buttonLabel } : {}),
-        });
-    }
-    return methods;
+            description: tool.description !== 'No description' ? tool.description : undefined,
+            ...(tool.outputFormat ? { format: tool.outputFormat } : {}),
+            ...(tool.buttonLabel ? { buttonLabel: tool.buttonLabel } : {}),
+            ...(tool.scheduled ? { scheduled: tool.scheduled } : {}),
+            ...(tool.webhook !== undefined ? { webhook: true } : {}),
+        };
+    });
 }
 /**
  * Extract base type from TypeScript type annotation
@@ -252,6 +127,45 @@ function extractObjectProperties(typeStr) {
  */
 function formatOutput(result, formatHint) {
     let hint = formatHint;
+    // Handle _photonType structured data (e.g., table, collection)
+    if (result && typeof result === 'object' && result._photonType) {
+        // If the object has toJSON(), call it to get the plain data (e.g., Table instances have private fields)
+        const data = typeof result.toJSON === 'function' ? result.toJSON() : result;
+        const photonType = data._photonType;
+        if (photonType === 'table' && data.rows && Array.isArray(data.rows)) {
+            // Convert structured table to array of objects for renderTable
+            const columns = data.columns || [];
+            const rows = data.rows.map((row) => {
+                if (Array.isArray(row)) {
+                    // Row is an array of values, map to column names
+                    const obj = {};
+                    columns.forEach((col, i) => {
+                        const key = typeof col === 'string' ? col : col.label || col.field || `col${i}`;
+                        obj[key] = row[i] ?? '';
+                    });
+                    return obj;
+                }
+                // Row is already an object, extract display values using column fields
+                if (columns.length > 0) {
+                    const obj = {};
+                    for (const col of columns) {
+                        const field = typeof col === 'string' ? col : col.field || col.key;
+                        const label = typeof col === 'string' ? col : col.label || col.field || col.key;
+                        if (field) {
+                            obj[label] = row[field] ?? '';
+                        }
+                    }
+                    return obj;
+                }
+                return row;
+            });
+            baseFormatOutput(rows, 'table');
+            return true;
+        }
+        // For other _photonType values, strip the marker and render normally
+        const { _photonType, ...rest } = data;
+        return formatOutput(rest, formatHint);
+    }
     // Handle error responses
     if (result && typeof result === 'object' && result.success === false) {
         const errorMsg = result.error || result.message || 'Unknown error';
@@ -371,7 +285,18 @@ function parseCliArgs(args, params) {
     let positionalIndex = 0;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        if (arg.startsWith('--')) {
+        if (arg.startsWith('--no-') && !arg.includes('=')) {
+            // --no-<param> negation syntax for boolean params (e.g., --no-enabled → enabled=false)
+            const key = arg.substring(5);
+            if (paramTypes.has(key)) {
+                result[key] = false;
+            }
+            else {
+                // Unknown param, store as-is (will be caught by validation later)
+                result[key] = false;
+            }
+        }
+        else if (arg.startsWith('--')) {
             // Named argument: --key value or --key=value
             const eqIndex = arg.indexOf('=');
             if (eqIndex !== -1) {
@@ -384,13 +309,17 @@ function parseCliArgs(args, params) {
             else {
                 // --key value format (next arg is the value)
                 const key = arg.substring(2);
-                i++;
-                if (i < args.length) {
-                    const expectedType = paramTypes.get(key) || 'any';
+                const expectedType = paramTypes.get(key) || 'any';
+                // For boolean params, treat bare --flag as true (no value consumed)
+                if (expectedType === 'boolean' && (i + 1 >= args.length || args[i + 1].startsWith('--'))) {
+                    result[key] = true;
+                }
+                else if (i + 1 < args.length) {
+                    i++;
                     result[key] = coerceValue(args[i], expectedType);
                 }
                 else {
-                    // Boolean flag
+                    // No value and not boolean - treat as boolean flag
                     result[key] = true;
                 }
             }
@@ -412,7 +341,7 @@ function parseCliArgs(args, params) {
 function coerceValue(value, expectedType) {
     // Preserve strings starting with + or - for relative adjustments
     // Must check BEFORE JSON.parse because JSON.parse("-3") returns -3 (number)
-    if (expectedType === 'number' && (value.startsWith('+') || value.startsWith('-'))) {
+    if (expectedType.includes('number') && (value.startsWith('+') || value.startsWith('-'))) {
         return value;
     }
     // Try to parse as JSON first (handles objects, arrays, true/false)
@@ -987,9 +916,57 @@ function formatLabel(name) {
 /**
  * Print help for a specific method
  */
+function printParamHelp(param) {
+    const displayLabel = param.label || formatLabel(param.name);
+    // Build type hint suffix
+    let typeHint = '';
+    if (param.enum && param.enum.length > 0) {
+        typeHint = ` [values: ${param.enum.join(', ')}]`;
+    }
+    else if (param.type === 'boolean') {
+        typeHint = ' [--no-' + param.name + ' to disable]';
+    }
+    else if (param.type === 'array') {
+        typeHint = ` (JSON array, e.g., '["a","b"]')`;
+    }
+    else if (param.type === 'object') {
+        typeHint = ` (JSON object, e.g., '{"key":"value"}')`;
+    }
+    console.log(`    --${param.name} (${displayLabel})${typeHint}`);
+    if (param.description) {
+        console.log(`        ${param.description}`);
+    }
+    // Show example for complex types (JSON)
+    if (param.example) {
+        console.log(`        Example: ${param.example}`);
+    }
+}
 function printMethodHelp(photonName, method) {
+    // Truncate description at sentence boundary if too long, or clean up mid-sentence truncation
+    let description = method.description || 'No description';
+    if (description.length > 200) {
+        const sentenceEnd = description.substring(0, 200).lastIndexOf('.');
+        if (sentenceEnd > 80) {
+            description = description.substring(0, sentenceEnd + 1);
+        }
+        else {
+            description = description.substring(0, 197) + '...';
+        }
+    }
+    else if (description.length > 0 && !/[.!?]$/.test(description.trim())) {
+        // Description appears truncated mid-sentence (no terminal punctuation)
+        // Truncate at the last complete sentence if possible
+        const lastSentence = description.lastIndexOf('.');
+        if (lastSentence > 40) {
+            description = description.substring(0, lastSentence + 1);
+        }
+        else {
+            // No good sentence boundary — add ellipsis to signal truncation
+            description = description.trim() + '...';
+        }
+    }
     console.log(`\nNAME:`);
-    console.log(`    ${method.name} - ${method.description || 'No description'}\n`);
+    console.log(`    ${method.name} - ${description}\n`);
     console.log(`USAGE:`);
     const requiredParams = method.params.filter((p) => !p.optional);
     const optionalParams = method.params.filter((p) => p.optional);
@@ -1005,32 +982,14 @@ function printMethodHelp(photonName, method) {
         if (requiredParams.length > 0) {
             console.log(`REQUIRED:`);
             for (const param of requiredParams) {
-                // Show custom label or formatted name
-                const displayLabel = param.label || formatLabel(param.name);
-                console.log(`    --${param.name} (${displayLabel})`);
-                if (param.description) {
-                    console.log(`        ${param.description}`);
-                }
-                // Show example for complex types (JSON)
-                if (param.example) {
-                    console.log(`        Example: ${param.example}`);
-                }
+                printParamHelp(param);
             }
             console.log('');
         }
         if (optionalParams.length > 0) {
             console.log(`OPTIONS:`);
             for (const param of optionalParams) {
-                // Show custom label or formatted name
-                const displayLabel = param.label || formatLabel(param.name);
-                console.log(`    --${param.name} (${displayLabel})`);
-                if (param.description) {
-                    console.log(`        ${param.description}`);
-                }
-                // Show example for complex types (JSON)
-                if (param.example) {
-                    console.log(`        Example: ${param.example}`);
-                }
+                printParamHelp(param);
             }
             console.log('');
         }
@@ -1054,12 +1013,28 @@ export async function listMethods(photonName) {
     try {
         const resolvedPath = await resolvePhotonPathWithBundled(photonName);
         if (!resolvedPath) {
-            logger.error(`Photon '${photonName}' not found`);
-            console.error(`\nMake sure the photon is installed in ~/.photon/`);
-            console.error(`If '${photonName}' is a command, run 'photon --help' for available commands.`);
-            process.exit(1);
+            exitWithError(`Photon '${photonName}' not found`, {
+                exitCode: ExitCode.NOT_FOUND,
+                searchedIn: '~/.photon/',
+                suggestion: `Install it with: photon add ${photonName}\nIf '${photonName}' is a command, run 'photon --help' for available commands`,
+            });
         }
-        const methods = await extractMethods(resolvedPath);
+        const allMethods = await extractMethods(resolvedPath);
+        // Filter out internal methods: scheduled*, handle*, reportError
+        const methods = allMethods.filter((m) => {
+            if (m.scheduled)
+                return false;
+            if (m.webhook)
+                return false;
+            if (m.name.startsWith('scheduled'))
+                return false;
+            if (m.name.startsWith('handle'))
+                return false;
+            if (m.name === 'reportError')
+                return false;
+            return true;
+        });
+        const hiddenCount = allMethods.length - methods.length;
         // Print usage
         console.log(`\nUSAGE:`);
         console.log(`    photon cli ${photonName} <command> [options]\n`);
@@ -1067,11 +1042,32 @@ export async function listMethods(photonName) {
         console.log(`COMMANDS:`);
         // Find longest method name for alignment
         const maxLength = Math.max(...methods.map((m) => m.name.length));
+        const maxDescLength = 60;
         for (const method of methods) {
             const padding = ' '.repeat(maxLength - method.name.length + 4);
-            const description = method.description || 'No description';
+            let description = method.description || 'No description';
+            // Truncate long descriptions in listing, keeping first sentence
+            if (description.length > maxDescLength) {
+                const sentenceEnd = description.substring(0, maxDescLength).lastIndexOf('.');
+                if (sentenceEnd > 20) {
+                    description = description.substring(0, sentenceEnd + 1);
+                }
+                else {
+                    description = description.substring(0, maxDescLength - 3) + '...';
+                }
+            }
+            // Show param signature for methods with no description
+            if (!method.description && method.params.length > 0) {
+                const sig = method.params
+                    .map((p) => (p.optional ? `${p.name}?` : p.name) + `: ${p.type}`)
+                    .join(', ');
+                description = `(${sig})`;
+            }
             console.log(`    ${method.name}${padding}${description}`);
         }
+        if (hiddenCount > 0) {
+            console.log(`\n    (${hiddenCount} internal/scheduled methods hidden)`);
+        }
         // Print footer
         console.log(`\nFor detailed parameter information, run:`);
         console.log(`    photon cli ${photonName} <command> --help\n`);
@@ -1094,8 +1090,9 @@ export async function listMethods(photonName) {
         }
     }
     catch (error) {
-        logger.error(`Error: ${getErrorMessage(error)}`);
-        process.exit(1);
+        exitWithError(`Cannot list methods for ${photonName}: ${getErrorMessage(error)}`, {
+            suggestion: `Verify the photon file is valid: ~/.photon/${photonName}.photon.ts`,
+        });
     }
 }
 /**
@@ -1122,10 +1119,11 @@ export async function runMethod(photonName, methodName, args) {
         // Resolve photon path
         const resolvedPath = await resolvePhotonPathWithBundled(photonName);
         if (!resolvedPath) {
-            logger.error(`Photon '${photonName}' not found`);
-            console.error(`\nMake sure the photon is installed in ~/.photon/`);
-            console.error(`If '${photonName}' is a command, run 'photon --help' for available commands.`);
-            process.exit(1);
+            exitWithError(`Photon '${photonName}' not found`, {
+                exitCode: ExitCode.NOT_FOUND,
+                searchedIn: '~/.photon/',
+                suggestion: `Install it with: photon add ${photonName}\nIf '${photonName}' is a command, run 'photon --help' for available commands`,
+            });
         }
         // Extract MCP name from filename
         const mcpName = path.basename(resolvedPath).replace(/\.photon\.(ts|js)$/, '');
@@ -1138,10 +1136,11 @@ export async function runMethod(photonName, methodName, args) {
         }
         const method = methods.find((m) => m.name === methodName);
         if (!method) {
-            logger.error(`Method '${methodName}' not found in ${photonName}`);
-            console.error(`\nAvailable methods: ${methods.map((m) => m.name).join(', ')}`);
-            console.error(`\nRun 'photon cli ${photonName}' to see all methods`);
-            process.exit(1);
+            const available = methods.map((m) => m.name).join(', ');
+            exitWithError(`Method '${methodName}' not found in ${photonName}`, {
+                exitCode: ExitCode.NOT_FOUND,
+                suggestion: `Available methods: ${available}\nRun 'photon cli ${photonName}' to see details`,
+            });
         }
         // Check for --help flag in args (e.g., photon cli test-cli-calc add --help)
         if (args.includes('--help') || args.includes('-h')) {
@@ -1168,11 +1167,47 @@ export async function runMethod(photonName, methodName, args) {
             }
         }
         if (missing.length > 0) {
-            logger.error(`Missing required parameters: ${missing.join(', ')}`);
-            console.error(`\nUsage: photon cli ${photonName} ${methodName} ${method.params
+            const usage = method.params
                 .map((p) => (p.optional ? `[--${p.name}]` : `--${p.name} <value>`))
-                .join(' ')}`);
-            process.exit(1);
+                .join(' ');
+            const details = missing
+                .map((name) => {
+                const p = method.params.find((mp) => mp.name === name);
+                return `  --${name} (${p?.type || 'string'})${p?.description ? ': ' + p.description : ''}`;
+            })
+                .join('\n');
+            exitWithError(`Missing required parameters: ${missing.join(', ')}`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                suggestion: `Usage: photon cli ${photonName} ${methodName} ${usage}\n\nRequired:\n${details}`,
+            });
+        }
+        // Validate parameter types and enum values
+        const validationErrors = [];
+        for (const param of method.params) {
+            if (!(param.name in parsedArgs))
+                continue;
+            const value = parsedArgs[param.name];
+            // Validate number types
+            if (param.type === 'number' && typeof value !== 'number') {
+                // coerceToType returns the original string if NaN, so check for non-number
+                if (typeof value === 'string' && !(value.startsWith('+') || value.startsWith('-'))) {
+                    validationErrors.push(`  --${param.name}: expected a number, got '${value}'`);
+                }
+            }
+            // Validate enum values
+            if (param.enum && param.enum.length > 0) {
+                const strValue = String(value).toLowerCase();
+                const validValues = param.enum.map((v) => v.toLowerCase());
+                if (!validValues.includes(strValue)) {
+                    validationErrors.push(`  --${param.name}: invalid value '${value}' (must be one of: ${param.enum.join(', ')})`);
+                }
+            }
+        }
+        if (validationErrors.length > 0) {
+            exitWithError(`Invalid parameter values`, {
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                suggestion: validationErrors.join('\n'),
+            });
         }
         // Check if photon is stateful
         const extractor = new PhotonDocExtractor(resolvedPath);
@@ -1181,8 +1216,8 @@ export async function runMethod(photonName, methodName, args) {
         if (metadata.stateful) {
             // STATEFUL PATH: Use daemon
             // Check if daemon is running
-            if (!isDaemonRunning(photonName)) {
-                await startDaemon(photonName, resolvedPath, true); // quiet mode
+            if (!isGlobalDaemonRunning()) {
+                await startGlobalDaemon(true);
                 // Wait for daemon to be ready
                 let ready = false;
                 for (let i = 0; i < 10; i++) {
@@ -1193,12 +1228,19 @@ export async function runMethod(photonName, methodName, args) {
                     }
                 }
                 if (!ready) {
-                    logger.error(`Failed to start daemon for ${photonName}`);
-                    process.exit(1);
+                    exitWithError(`Failed to start daemon for ${photonName}`, {
+                        suggestion: `Check logs: cat ~/.photon/daemons/${photonName}/daemon.log\nOr try: photon daemon restart ${photonName}`,
+                    });
                 }
             }
-            // Send command to daemon
-            result = await sendCommand(photonName, methodName, parsedArgs);
+            // Read session-scoped instance set by `photon use` (scoped to this terminal)
+            const { CLISessionStore } = await import('./context-store.js');
+            const sessionInstance = new CLISessionStore().getCurrentInstance(photonName);
+            const sessionId = `cli-${photonName}`;
+            const sendOpts = { photonPath: resolvedPath, sessionId };
+            await sendCommand(photonName, '_use', { name: sessionInstance }, sendOpts);
+            // Send the actual command
+            result = await sendCommand(photonName, methodName, parsedArgs, sendOpts);
         }
         else {
             // STATELESS PATH: Direct execution
@@ -1244,15 +1286,13 @@ export async function runMethod(photonName, methodName, args) {
     catch (error) {
         // Check for custom user-facing message from photon
         // Photons can throw: throw Object.assign(new Error('internal'), { userMessage: 'friendly msg', hint: 'try this' })
-        const userMessage = (error && typeof error === 'object' && 'userMessage' in error && error.userMessage) ||
+        const userMessage = (error && typeof error === 'object' && 'userMessage' in error && String(error.userMessage)) ||
             getErrorMessage(error) ||
             'Unknown error occurred';
-        const hint = error && typeof error === 'object' && 'hint' in error ? error.hint : undefined;
-        logger.error(`${userMessage}`);
-        if (hint) {
-            console.error(`💡 ${hint}`);
-        }
-        process.exit(1);
+        const hint = error && typeof error === 'object' && 'hint' in error ? String(error.hint) : undefined;
+        exitWithError(String(userMessage), {
+            suggestion: hint ? String(hint) : undefined,
+        });
     }
 }
 /**