@portel/photon 1.4.1 → 1.5.1

package/dist/photon-cli-runner.js

@@ -6,16 +6,35 @@
  */
 import * as path from 'path';
 import * as fs from 'fs/promises';
-import { SchemaExtractor, setPromptHandler } from '@portel/photon-core';
+import { SchemaExtractor, setPromptHandler, setElicitHandler, elicitReadline, } from '@portel/photon-core';
 import * as readline from 'readline';
 import chalk from 'chalk';
 import { highlight } from 'cli-highlight';
 import { resolvePhotonPath } from './path-resolver.js';
 import { PhotonLoader } from './loader.js';
+import { fileURLToPath } from 'url';
+import { getBundledPhotonPath } from './shared-utils.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// getBundledPhotonPath is imported from shared-utils.js
+/**
+ * Resolve photon path - checks bundled first, then user directory
+ */
+async function resolvePhotonPathWithBundled(name) {
+    // Check bundled photons first
+    const bundledPath = getBundledPhotonPath(name, __dirname);
+    if (bundledPath) {
+        return bundledPath;
+    }
+    // Fall back to user photons
+    return resolvePhotonPath(name);
+}
 import { PhotonDocExtractor } from './photon-doc-extractor.js';
 import { isDaemonRunning, startDaemon } 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';
 /**
  * Extract all public async methods from a photon file
  */
@@ -24,8 +43,8 @@ async function extractMethods(filePath) {
     const extractor = new SchemaExtractor();
     const methods = [];
     // Extract methods using the schema extractor
-    // Also match async generator methods (async *methodName)
-    const methodMatches = source.matchAll(/async\s+\*?\s*(\w+)\s*\(([^)]*)\)/g);
+    // 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];
@@ -52,7 +71,7 @@ async function extractMethods(filePath) {
         const description = descMatch
             ? descMatch[1]
                 .split('\n')
-                .map(line => line.replace(/^\s*\*\s?/, '').trim())
+                .map((line) => line.replace(/^\s*\*\s?/, '').trim())
                 .join(' ')
                 .trim()
             : undefined;
@@ -82,8 +101,8 @@ async function extractMethods(filePath) {
         }
         // Extract format hint from @format tag (structural and content formats)
         let format;
-        // Match structural formats
-        const structuralMatch = jsdoc.match(/@format\s+(primitive|table|tree|list|none)/i);
+        // 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();
         }
@@ -108,8 +127,51 @@ async function extractMethods(filePath) {
         while ((paramMatch = paramRegex.exec(jsdoc)) !== null) {
             const paramName = paramMatch[1];
             const paramDesc = paramMatch[2].trim();
-            // Remove JSDoc constraint tags for display
-            const cleanDesc = paramDesc
+            // 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++;
+                }
+            }
+            // 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, '')
@@ -123,13 +185,19 @@ async function extractMethods(filePath) {
                 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,
             params,
             description,
             ...(format ? { format } : {}),
+            ...(buttonLabel ? { buttonLabel } : {}),
         });
     }
     return methods;
@@ -148,7 +216,7 @@ function extractBaseType(typeStr) {
         return objectMatch[1];
     }
     // Handle unions: boolean | number -> take first primitive type
-    const unionTypes = typeStr.split('|').map(t => t.trim());
+    const unionTypes = typeStr.split('|').map((t) => t.trim());
     for (const type of unionTypes) {
         if (/^(boolean|number|string)/.test(type)) {
             return type;
@@ -206,7 +274,10 @@ function formatOutput(result, formatHint) {
             hint = inlineMarkdownFormat;
         }
         if (markdownText) {
-            const primaryBlock = buildMarkdownBlockFromPrepared(markdownText, { hint, inlineFormat: inlineMarkdownFormat });
+            const primaryBlock = buildMarkdownBlockFromPrepared(markdownText, {
+                hint,
+                inlineFormat: inlineMarkdownFormat,
+            });
             if (primaryBlock) {
                 const metadata = extractMetadataFields(result);
                 renderMarkdownBlocks([primaryBlock], { additionalMetadata: metadata });
@@ -218,10 +289,10 @@ function formatOutput(result, formatHint) {
             dataToFormat = result.data;
         }
         else {
-            const otherFields = Object.keys(result).filter(k => k !== 'success' && k !== 'message' && k !== 'error');
+            const otherFields = Object.keys(result).filter((k) => k !== 'success' && k !== 'message' && k !== 'error');
             if (otherFields.length > 0) {
                 dataToFormat = {};
-                otherFields.forEach(k => dataToFormat[k] = result[k]);
+                otherFields.forEach((k) => (dataToFormat[k] = result[k]));
             }
             else {
                 if (!result.message) {
@@ -238,7 +309,10 @@ function formatOutput(result, formatHint) {
                 }
                 dataToFormat = inline.text;
             }
-            const markdownBlock = buildMarkdownBlockFromPrepared(dataToFormat, { hint, inlineFormat: inline?.format });
+            const markdownBlock = buildMarkdownBlockFromPrepared(dataToFormat, {
+                hint,
+                inlineFormat: inline?.format,
+            });
             if (markdownBlock) {
                 renderMarkdownBlocks([markdownBlock]);
                 return true;
@@ -264,7 +338,10 @@ function formatOutput(result, formatHint) {
                 }
                 payload = inline.text;
             }
-            const standaloneBlock = buildMarkdownBlockFromPrepared(payload, { hint, inlineFormat: inline?.format });
+            const standaloneBlock = buildMarkdownBlockFromPrepared(payload, {
+                hint,
+                inlineFormat: inline?.format,
+            });
             if (standaloneBlock) {
                 renderMarkdownBlocks([standaloneBlock]);
                 return true;
@@ -289,7 +366,7 @@ function formatOutput(result, formatHint) {
 function parseCliArgs(args, params) {
     const result = {};
     // Create a map of param names to types for quick lookup
-    const paramTypes = new Map(params.map(p => [p.name, p.type]));
+    const paramTypes = new Map(params.map((p) => [p.name, p.type]));
     // Handle both positional and --flag style arguments
     let positionalIndex = 0;
     for (let i = 0; i < args.length; i++) {
@@ -400,7 +477,7 @@ function looksLikeMarkdown(value) {
         /^```/m,
         /(?:^|\n)(?:-{3,}|_{3,}|\*{3,})(?:\n|$)/m,
     ];
-    if (blockPatterns.some(pattern => pattern.test(trimmed))) {
+    if (blockPatterns.some((pattern) => pattern.test(trimmed))) {
         return true;
     }
     if (/\[.+?\]\(.+?\)/.test(trimmed)) {
@@ -437,7 +514,9 @@ function renderMarkdownNicely(content) {
         return `\u0000CODE${codeBlocks.length - 1}\u0000`;
     });
     // Wrap text paragraphs
-    rendered = rendered.split('\n').map(line => {
+    rendered = rendered
+        .split('\n')
+        .map((line) => {
         // Skip headers, placeholders, empty lines, lists, quotes
         if (line.startsWith('#') ||
             line.includes('\u0000CODE') ||
@@ -447,7 +526,8 @@ function renderMarkdownNicely(content) {
         }
         // Wrap plain text line
         return wrapToWidth(line, termWidth).join('\n');
-    }).join('\n');
+    })
+        .join('\n');
     // Restore code blocks and highlight
     rendered = rendered.replace(/\u0000CODE(\d+)\u0000/g, (_m, index) => {
         const block = codeBlocks[parseInt(index)];
@@ -478,7 +558,10 @@ function renderMarkdownNicely(content) {
     rendered = rendered.replace(/\*(.+?)\*/g, (_m, text) => chalk.italic(text));
     rendered = rendered.replace(/_(.+?)_/g, (_m, text) => chalk.italic(text));
     rendered = rendered.replace(/`([^`]+)`/g, (_m, code) => chalk.cyan(code));
-    rendered = rendered.split('\n').map(line => line.trimEnd()).join('\n');
+    rendered = rendered
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .join('\n');
     rendered = rendered.replace(/\n{3,}/g, '\n\n');
     console.log(rendered.trim());
 }
@@ -506,12 +589,10 @@ function convertFrontMatterToMarkdown(markdown) {
     return { markdown: prefix + text, metadata, hadFrontMatter };
 }
 function frontMatterToTable(parsed) {
-    const rows = Object.entries(parsed).map(([key, value]) => `| ${escapePipes(key)} | ${escapePipes(value)} |`).join('\n');
-    return [
-        '| Field | Value |',
-        '| --- | --- |',
-        rows,
-    ].join('\n');
+    const rows = Object.entries(parsed)
+        .map(([key, value]) => `| ${escapePipes(key)} | ${escapePipes(value)} |`)
+        .join('\n');
+    return ['| Field | Value |', '| --- | --- |', rows].join('\n');
 }
 function escapePipes(text) {
     return text.replace(/\|/g, '\\|');
@@ -822,7 +903,7 @@ function renderMarkdownTableBlock(block) {
     const rows = lines
         .slice(2)
         .map(parseMarkdownTableRow)
-        .filter(row => row.length === header.length);
+        .filter((row) => row.length === header.length);
     if (!rows.length) {
         return block;
     }
@@ -834,18 +915,18 @@ function parseMarkdownTableRow(line) {
         .replace(/^\|/, '')
         .replace(/\|$/, '')
         .split('|')
-        .map(cell => cell.trim());
+        .map((cell) => cell.trim());
 }
 function renderGenericTable(headers, rows) {
     if (!headers.length) {
-        return rows.map(row => row.join(' | ')).join('\n');
+        return rows.map((row) => row.join(' | ')).join('\n');
     }
     const termWidth = process.stdout.columns || 80;
     const columns = headers.length;
     const baseOverhead = 2 * columns + (columns - 1) + 2; // padding + connectors + borders
     const maxAvailable = Math.max(columns, termWidth - baseOverhead);
-    const colWidths = headers.map(header => Math.max(visibleLength(header), 3));
-    rows.forEach(row => {
+    const colWidths = headers.map((header) => Math.max(visibleLength(header), 3));
+    rows.forEach((row) => {
         row.forEach((cell, idx) => {
             const width = visibleLength(cell ?? '');
             if (width > (colWidths[idx] || 0)) {
@@ -865,13 +946,13 @@ function renderGenericTable(headers, rows) {
         }
         colWidths[maxIdx]--;
     }
-    const wrappedRows = [headers, ...rows].map(row => row.map((cell, idx) => wrapToWidth(cell ?? '', colWidths[idx] || 1)));
-    const horizontal = colWidths.map(width => '─'.repeat(width + 2));
+    const wrappedRows = [headers, ...rows].map((row) => row.map((cell, idx) => wrapToWidth(cell ?? '', colWidths[idx] || 1)));
+    const horizontal = colWidths.map((width) => '─'.repeat(width + 2));
     const top = `┌${horizontal.join('┬')}┐`;
     const mid = `├${horizontal.join('┼')}┤`;
     const bottom = `└${horizontal.join('┴')}┘`;
     const formatWrappedRow = (wrappedCells) => {
-        const maxLines = Math.max(...wrappedCells.map(cell => cell.length));
+        const maxLines = Math.max(...wrappedCells.map((cell) => cell.length));
         const lines = [];
         for (let lineIdx = 0; lineIdx < maxLines; lineIdx++) {
             const parts = wrappedCells.map((cellLines, idx) => {
@@ -893,6 +974,16 @@ function renderGenericTable(headers, rows) {
     });
     return output.join('\n');
 }
+/**
+ * Format camelCase/PascalCase to "Title Case With Spaces"
+ */
+function formatLabel(name) {
+    return name
+        .replace(/([A-Z])/g, ' $1') // Add space before capitals
+        .replace(/([a-zA-Z])(\d)/g, '$1 $2') // Add space before numbers
+        .replace(/^./, (str) => str.toUpperCase()) // Capitalize first letter
+        .trim();
+}
 /**
  * Print help for a specific method
  */
@@ -900,11 +991,11 @@ function printMethodHelp(photonName, method) {
     console.log(`\nNAME:`);
     console.log(`    ${method.name} - ${method.description || 'No description'}\n`);
     console.log(`USAGE:`);
-    const requiredParams = method.params.filter(p => !p.optional);
-    const optionalParams = method.params.filter(p => p.optional);
+    const requiredParams = method.params.filter((p) => !p.optional);
+    const optionalParams = method.params.filter((p) => p.optional);
     let usage = `    photon cli ${photonName} ${method.name}`;
     if (requiredParams.length > 0) {
-        usage += ' ' + requiredParams.map(p => `--${p.name} <value>`).join(' ');
+        usage += ' ' + requiredParams.map((p) => `--${p.name} <value>`).join(' ');
     }
     if (optionalParams.length > 0) {
         usage += ' [options]';
@@ -914,20 +1005,32 @@ function printMethodHelp(photonName, method) {
         if (requiredParams.length > 0) {
             console.log(`REQUIRED:`);
             for (const param of requiredParams) {
-                console.log(`    --${param.name}`);
+                // 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}`);
+                }
             }
             console.log('');
         }
         if (optionalParams.length > 0) {
             console.log(`OPTIONS:`);
             for (const param of optionalParams) {
-                console.log(`    --${param.name}`);
+                // 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}`);
+                }
             }
             console.log('');
         }
@@ -937,7 +1040,7 @@ function printMethodHelp(photonName, method) {
     }
     console.log(`EXAMPLE:`);
     if (requiredParams.length > 0) {
-        const exampleParams = requiredParams.map(p => `--${p.name} <value>`).join(' ');
+        const exampleParams = requiredParams.map((p) => `--${p.name} <value>`).join(' ');
         console.log(`    photon cli ${photonName} ${method.name} ${exampleParams}\n`);
     }
     else {
@@ -949,9 +1052,9 @@ function printMethodHelp(photonName, method) {
  */
 export async function listMethods(photonName) {
     try {
-        const resolvedPath = await resolvePhotonPath(photonName);
+        const resolvedPath = await resolvePhotonPathWithBundled(photonName);
         if (!resolvedPath) {
-            console.error(`❌ Photon '${photonName}' not found`);
+            logger.error(`Photon '${photonName}' not found`);
             console.error(`\nMake sure the photon is installed in ~/.photon/`);
             process.exit(1);
         }
@@ -962,7 +1065,7 @@ export async function listMethods(photonName) {
         // Print commands
         console.log(`COMMANDS:`);
         // Find longest method name for alignment
-        const maxLength = Math.max(...methods.map(m => m.name.length));
+        const maxLength = Math.max(...methods.map((m) => m.name.length));
         for (const method of methods) {
             const padding = ' '.repeat(maxLength - method.name.length + 4);
             const description = method.description || 'No description';
@@ -977,9 +1080,9 @@ export async function listMethods(photonName) {
             // Show first 3 methods as examples
             const exampleMethods = methods.slice(0, 3);
             for (const method of exampleMethods) {
-                const requiredParams = method.params.filter(p => !p.optional);
+                const requiredParams = method.params.filter((p) => !p.optional);
                 if (requiredParams.length > 0) {
-                    const paramStr = requiredParams.map(p => `--${p.name} <value>`).join(' ');
+                    const paramStr = requiredParams.map((p) => `--${p.name} <value>`).join(' ');
                     console.log(`    photon cli ${photonName} ${method.name} ${paramStr}`);
                 }
                 else {
@@ -990,7 +1093,7 @@ export async function listMethods(photonName) {
         }
     }
     catch (error) {
-        console.error(`❌ Error: ${error.message}`);
+        logger.error(`Error: ${getErrorMessage(error)}`);
         process.exit(1);
     }
 }
@@ -1005,20 +1108,20 @@ export async function runMethod(photonName, methodName, args) {
                 input: process.stdin,
                 output: process.stdout,
             });
-            const prompt = defaultValue
-                ? `${message} [${defaultValue}]: `
-                : `${message}: `;
+            const prompt = defaultValue ? `${message} [${defaultValue}]: ` : `${message}: `;
             rl.question(prompt, (answer) => {
                 rl.close();
                 resolve(answer || defaultValue || null);
             });
         });
     });
+    // Set up readline elicit handler for CLI (confirm, select, etc.)
+    setElicitHandler(elicitReadline);
     try {
         // Resolve photon path
-        const resolvedPath = await resolvePhotonPath(photonName);
+        const resolvedPath = await resolvePhotonPathWithBundled(photonName);
         if (!resolvedPath) {
-            console.error(`❌ Photon '${photonName}' not found`);
+            logger.error(`Photon '${photonName}' not found`);
             console.error(`\nMake sure the photon is installed in ~/.photon/`);
             process.exit(1);
         }
@@ -1031,10 +1134,10 @@ export async function runMethod(photonName, methodName, args) {
             await listMethods(photonName);
             return;
         }
-        const method = methods.find(m => m.name === methodName);
+        const method = methods.find((m) => m.name === methodName);
         if (!method) {
-            console.error(`❌ Method '${methodName}' not found in ${photonName}`);
-            console.error(`\nAvailable methods: ${methods.map(m => m.name).join(', ')}`);
+            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);
         }
@@ -1045,7 +1148,14 @@ export async function runMethod(photonName, methodName, args) {
         }
         // Check for --json flag
         const jsonOutput = args.includes('--json');
-        const filteredArgs = args.filter(arg => arg !== '--json');
+        // Check for --resume <runId> flag
+        let resumeRunId;
+        const resumeIndex = args.indexOf('--resume');
+        if (resumeIndex !== -1 && args[resumeIndex + 1]) {
+            resumeRunId = args[resumeIndex + 1];
+        }
+        // Filter out special flags before parsing method args
+        const filteredArgs = args.filter((arg, i) => arg !== '--json' && arg !== '--resume' && (resumeIndex === -1 || i !== resumeIndex + 1));
         // Parse arguments
         const parsedArgs = parseCliArgs(filteredArgs, method.params);
         // Validate required parameters
@@ -1056,8 +1166,10 @@ export async function runMethod(photonName, methodName, args) {
             }
         }
         if (missing.length > 0) {
-            console.error(`❌ Missing required parameters: ${missing.join(', ')}`);
-            console.error(`\nUsage: photon cli ${photonName} ${methodName} ${method.params.map(p => p.optional ? `[--${p.name}]` : `--${p.name} <value>`).join(' ')}`);
+            logger.error(`Missing required parameters: ${missing.join(', ')}`);
+            console.error(`\nUsage: photon cli ${photonName} ${methodName} ${method.params
+                .map((p) => (p.optional ? `[--${p.name}]` : `--${p.name} <value>`))
+                .join(' ')}`);
             process.exit(1);
         }
         // Check if photon is stateful
@@ -1072,14 +1184,14 @@ export async function runMethod(photonName, methodName, args) {
                 // Wait for daemon to be ready
                 let ready = false;
                 for (let i = 0; i < 10; i++) {
-                    await new Promise(resolve => setTimeout(resolve, 500));
+                    await new Promise((resolve) => setTimeout(resolve, 500));
                     if (await pingDaemon(photonName)) {
                         ready = true;
                         break;
                     }
                 }
                 if (!ready) {
-                    console.error(`❌ Failed to start daemon for ${photonName}`);
+                    logger.error(`Failed to start daemon for ${photonName}`);
                     process.exit(1);
                 }
             }
@@ -1090,40 +1202,53 @@ export async function runMethod(photonName, methodName, args) {
             // STATELESS PATH: Direct execution
             const loader = new PhotonLoader(false); // verbose=false for CLI mode
             const photonInstance = await loader.loadFile(resolvedPath);
-            // Call the method
-            result = await loader.executeTool(photonInstance, methodName, parsedArgs);
+            // Print resume message before execution
+            if (resumeRunId) {
+                console.log(`Resuming workflow ${resumeRunId}...`);
+            }
+            // Call the method (with optional resume)
+            result = await loader.executeTool(photonInstance, methodName, parsedArgs, { resumeRunId });
         }
+        // Check if this was a stateful workflow execution
+        const isStateful = result && typeof result === 'object' && result._stateful === true;
+        const actualResult = isStateful ? result.result : result;
         // Display result
         if (jsonOutput) {
-            const jsonStr = JSON.stringify(result, null, 2);
+            // For JSON output, include workflow metadata if stateful
+            const outputData = isStateful ? { ...result, result: actualResult } : actualResult;
+            const jsonStr = JSON.stringify(outputData, null, 2);
             baseFormatOutput(jsonStr, 'json');
             // Check for errors in JSON output too
-            if (result && typeof result === 'object' && result.success === false) {
+            if (actualResult && typeof actualResult === 'object' && actualResult.success === false) {
                 process.exit(1);
             }
         }
         else {
-            const formatHint = method.format || (looksLikeMarkdown(result) ? 'markdown' : undefined);
-            const success = formatOutput(result, formatHint);
+            const formatHint = method.format || (looksLikeMarkdown(actualResult) ? 'markdown' : undefined);
+            const success = formatOutput(actualResult, formatHint);
             if (!success) {
                 process.exit(1);
             }
+            // Show run ID for stateful workflows
+            if (isStateful && result.runId) {
+                console.log('');
+                if (result.resumed && result.resumedFromStep !== undefined) {
+                    console.log(`Resumed from step ${result.resumedFromStep}, completed ${result.checkpointsCompleted} checkpoints`);
+                }
+                console.log(`Run ID: ${result.runId}`);
+            }
         }
     }
     catch (error) {
-        // User-friendly error messages without stack traces
-        const errorMsg = error.message || 'Unknown error occurred';
-        // Provide helpful context based on error type
-        if (errorMsg.includes('timeout')) {
-            console.log('❌ Request timed out. The TV may be unreachable or the operation took too long.');
-            console.log('💡 Check that your TV is on and connected to the network.');
-        }
-        else if (errorMsg.includes('Connection error') || errorMsg.includes('Connection closed')) {
-            console.log('❌ Failed to communicate with the TV.');
-            console.log('💡 Try reconnecting with: photon cli lg-remote connect --ip <tv-ip>');
-        }
-        else {
-            console.log(`❌ ${errorMsg}`);
+        // 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) ||
+            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);
     }