@portel/photon-core 1.4.0 → 2.1.0

package/src/schema-extractor.ts

@@ -61,6 +61,12 @@ export class SchemaExtractor {
       // Helper to process a method declaration
       const processMethod = (member: ts.MethodDeclaration) => {
         const methodName = member.name.getText(sourceFile);
+
+        // Skip private methods (prefixed with _)
+        if (methodName.startsWith('_')) {
+          return;
+        }
+
         const jsdoc = this.getJSDocComment(member, sourceFile);
 
         // Check if this is an async generator method (has asterisk token)
@@ -129,17 +135,25 @@ export class SchemaExtractor {
         // Otherwise, it's a regular tool
         else {
           const outputFormat = this.extractFormat(jsdoc);
+          const layoutHints = this.extractLayoutHints(jsdoc);
+          const buttonLabel = this.extractButtonLabel(jsdoc);
+          const icon = this.extractIcon(jsdoc);
           const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
           const isStateful = this.hasStatefulTag(jsdoc);
+          const autorun = this.hasAutorunTag(jsdoc);
 
           tools.push({
             name: methodName,
             description,
             inputSchema,
             ...(outputFormat ? { outputFormat } : {}),
+            ...(layoutHints ? { layoutHints } : {}),
+            ...(buttonLabel ? { buttonLabel } : {}),
+            ...(icon ? { icon } : {}),
             ...(isGenerator ? { isGenerator: true } : {}),
             ...(yields && yields.length > 0 ? { yields } : {}),
             ...(isStateful ? { isStateful: true } : {}),
+            ...(autorun ? { autorun: true } : {}),
           });
         }
       };
@@ -219,6 +233,19 @@ export class SchemaExtractor {
     const properties: Record<string, any> = {};
     const required: string[] = [];
 
+    // Handle union types (e.g., { ip: string } | string)
+    // Extract properties from the first object type member
+    if (ts.isUnionTypeNode(typeNode)) {
+      for (const memberType of typeNode.types) {
+        if (ts.isTypeLiteralNode(memberType)) {
+          // Found an object type in the union, extract its properties
+          return this.buildSchemaFromType(memberType, sourceFile);
+        }
+      }
+      // No object type found in union, return empty
+      return { properties, required };
+    }
+
     // Handle type literal (object type)
     if (ts.isTypeLiteralNode(typeNode)) {
       typeNode.members.forEach((member) => {
@@ -570,6 +597,54 @@ export class SchemaExtractor {
    * Extract parameter descriptions from JSDoc @param tags
    * Also removes constraint tags from descriptions
    */
+  /**
+   * Remove {@example ...} tags that may contain nested braces/brackets (JSON)
+   */
+  private removeExampleTags(text: string): string {
+    let result = text;
+    let searchStart = 0;
+
+    while (true) {
+      const exampleStart = result.indexOf('{@example ', searchStart);
+      if (exampleStart === -1) break;
+
+      const contentStart = exampleStart + '{@example '.length;
+      let braceDepth = 0;
+      let bracketDepth = 0;
+      let i = contentStart;
+      let inString = false;
+
+      while (i < result.length) {
+        const ch = result[i];
+        const prevCh = i > 0 ? result[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) {
+              // Found the closing brace of the {@example} tag
+              result = result.substring(0, exampleStart) + result.substring(i + 1);
+              break;
+            }
+            braceDepth--;
+          }
+        }
+        i++;
+      }
+
+      // Safety: if we didn't find closing brace, move past this tag
+      if (i >= result.length) {
+        searchStart = exampleStart + 1;
+      }
+    }
+
+    return result;
+  }
+
   private extractParamDocs(jsdocContent: string): Map<string, string> {
     const paramDocs = new Map<string, string>();
     const paramRegex = /@param\s+(\w+)\s+(.+)/g;
@@ -577,19 +652,25 @@ export class SchemaExtractor {
     let match;
     while ((match = paramRegex.exec(jsdocContent)) !== null) {
       const [, paramName, description] = match;
-      // Remove all constraint tags from description
-      const cleanDesc = description
+      // Remove {@example} tags first (handles nested braces/brackets)
+      let cleanDesc = this.removeExampleTags(description);
+      // Remove other constraint tags from description
+      cleanDesc = cleanDesc
         .replace(/\{@min\s+[^}]+\}/g, '')
         .replace(/\{@max\s+[^}]+\}/g, '')
         .replace(/\{@pattern\s+[^}]+\}/g, '')
         .replace(/\{@format\s+[^}]+\}/g, '')
+        .replace(/\{@choice\s+[^}]+\}/g, '')
+        .replace(/\{@field\s+[^}]+\}/g, '')
         .replace(/\{@default\s+[^}]+\}/g, '')
         .replace(/\{@unique(?:Items)?\s*\}/g, '')
-        .replace(/\{@example\s+[^}]+\}/g, '')
         .replace(/\{@multipleOf\s+[^}]+\}/g, '')
         .replace(/\{@deprecated(?:\s+[^}]+)?\}/g, '')
         .replace(/\{@readOnly\s*\}/g, '')
         .replace(/\{@writeOnly\s*\}/g, '')
+        .replace(/\{@label\s+[^}]+\}/g, '')
+        .replace(/\{@placeholder\s+[^}]+\}/g, '')
+        .replace(/\{@hint\s+[^}]+\}/g, '')
         .replace(/\s+/g, ' ')  // Collapse multiple spaces
         .trim();
       paramDocs.set(paramName, cleanDesc);
@@ -636,6 +717,19 @@ export class SchemaExtractor {
         paramConstraints.format = formatMatch[1].trim();
       }
 
+      // Extract {@choice value1,value2,...} - converts to enum in schema
+      const choiceMatch = description.match(/\{@choice\s+([^}]+)\}/);
+      if (choiceMatch) {
+        const choices = choiceMatch[1].split(',').map((c: string) => c.trim());
+        paramConstraints.enum = choices;
+      }
+
+      // Extract {@field type} - hints for UI form rendering
+      const fieldMatch = description.match(/\{@field\s+([a-z]+)\}/);
+      if (fieldMatch) {
+        paramConstraints.field = fieldMatch[1].trim();
+      }
+
       // Extract {@default value} - use lookahead to match until tag-closing }
       const defaultMatch = description.match(/\{@default\s+(.+?)\}(?=\s|$|{@)/);
       if (defaultMatch) {
@@ -702,6 +796,29 @@ export class SchemaExtractor {
         }
       }
 
+      // Extract {@label displayName} - custom label for form fields
+      const labelMatch = description.match(/\{@label\s+([^}]+)\}/);
+      if (labelMatch) {
+        paramConstraints.label = labelMatch[1].trim();
+      }
+
+      // Extract {@placeholder text} - placeholder text for input fields
+      const placeholderMatch = description.match(/\{@placeholder\s+([^}]+)\}/);
+      if (placeholderMatch) {
+        paramConstraints.placeholder = placeholderMatch[1].trim();
+      }
+
+      // Extract {@hint text} - help text shown below/beside the field
+      const hintMatch = description.match(/\{@hint\s+([^}]+)\}/);
+      if (hintMatch) {
+        paramConstraints.hint = hintMatch[1].trim();
+      }
+
+      // Extract {@hidden} - hide field from UI forms (for programmatic use only)
+      if (description.match(/\{@hidden\s*\}/)) {
+        paramConstraints.hidden = true;
+      }
+
       if (Object.keys(paramConstraints).length > 0) {
         constraints.set(paramName, paramConstraints);
       }
@@ -776,6 +893,26 @@ export class SchemaExtractor {
       if (constraints.deprecated !== undefined) {
         s.deprecated = constraints.deprecated === true ? true : constraints.deprecated;
       }
+      // Apply enum from @choice tag (overrides TypeScript-derived enum if present)
+      if (constraints.enum !== undefined && !s.enum) {
+        s.enum = constraints.enum;
+      }
+      // Apply field hint for UI rendering
+      if (constraints.field !== undefined) {
+        s.field = constraints.field;
+      }
+      // Apply custom label for form fields
+      if (constraints.label !== undefined) {
+        s.title = constraints.label;  // JSON Schema uses 'title' for display label
+      }
+      // Apply placeholder for input fields
+      if (constraints.placeholder !== undefined) {
+        s.placeholder = constraints.placeholder;
+      }
+      // Apply hint text for form fields
+      if (constraints.hint !== undefined) {
+        s.hint = constraints.hint;
+      }
 
       // readOnly and writeOnly are mutually exclusive
       // JSDoc takes precedence over TypeScript
@@ -787,6 +924,11 @@ export class SchemaExtractor {
         s.writeOnly = true;
         delete s.readOnly; // Clear readOnly if writeOnly is set
       }
+
+      // Apply hidden flag for UI forms
+      if (constraints.hidden === true) {
+        s.hidden = true;
+      }
     };
 
     // Apply to anyOf schemas or direct schema
@@ -828,6 +970,14 @@ export class SchemaExtractor {
     return /@stateful/i.test(jsdocContent);
   }
 
+  /**
+   * Check if JSDoc contains @autorun tag
+   * Indicates this method should auto-execute when selected (idempotent, no required params)
+   */
+  private hasAutorunTag(jsdocContent: string): boolean {
+    return /@autorun/i.test(jsdocContent);
+  }
+
   /**
    * Extract URI pattern from @Static tag
    * Example: @Static github://repos/{owner}/{repo}/readme
@@ -839,29 +989,92 @@ export class SchemaExtractor {
 
   /**
    * Extract format hint from @format tag
+   * Supports nested syntax: @format list {@title name, @subtitle email}
    * Example: @format table
    * Example: @format json
    * Example: @format code:typescript
+   * Example: @format list {@title name, @subtitle email, @style inset}
    */
   private extractFormat(jsdocContent: string): OutputFormat | undefined {
+    // Match format with optional nested hints: @format list {...}
+    // The nested hints are extracted separately by extractLayoutHints
+    const formatMatch = jsdocContent.match(/@format\s+(\w+)(?::(\w+))?/i);
+    if (!formatMatch) return undefined;
+
+    const format = formatMatch[1].toLowerCase();
+    const subtype = formatMatch[2];
+
     // Match structural formats
-    const structuralMatch = jsdocContent.match(/@format\s+(primitive|table|tree|list|none)/i);
-    if (structuralMatch) {
-      return structuralMatch[1].toLowerCase() as OutputFormat;
+    if (['primitive', 'table', 'tree', 'list', 'none', 'card', 'grid', 'chips', 'kv'].includes(format)) {
+      return format as OutputFormat;
     }
 
     // Match content formats
-    const contentMatch = jsdocContent.match(/@format\s+(json|markdown|yaml|xml|html)/i);
-    if (contentMatch) {
-      return contentMatch[1].toLowerCase() as OutputFormat;
+    if (['json', 'markdown', 'yaml', 'xml', 'html', 'mermaid'].includes(format)) {
+      return format as OutputFormat;
     }
 
     // Match code format (with optional language)
-    const codeMatch = jsdocContent.match(/@format\s+code(?::(\w+))?/i);
-    if (codeMatch) {
-      return codeMatch[1] ? `code:${codeMatch[1]}` as OutputFormat : 'code';
+    if (format === 'code') {
+      return subtype ? `code:${subtype}` as OutputFormat : 'code';
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Extract layout hints from nested @format syntax
+   * Example: @format list {@title name, @subtitle email, @icon avatar, @style inset}
+   * Returns: { title: 'name', subtitle: 'email', icon: 'avatar', style: 'inset' }
+   */
+  private extractLayoutHints(jsdocContent: string): Record<string, string> | undefined {
+    // Match @format TYPE {hints}
+    const match = jsdocContent.match(/@format\s+\w+(?::\w+)?\s*\{([^}]+)\}/i);
+    if (!match) return undefined;
+
+    const hintsString = match[1];
+    const hints: Record<string, string> = {};
+
+    // Parse comma-separated hints: @title name, @subtitle email:link
+    const parts = hintsString.split(',').map(s => s.trim());
+
+    for (const part of parts) {
+      // Match @key value or @key value:renderer
+      const hintMatch = part.match(/@(\w+)\s+([^\s,]+(?:\s+[^\s@,][^\s,]*)*)/);
+      if (hintMatch) {
+        const [, key, value] = hintMatch;
+        hints[key.toLowerCase()] = value.trim();
+      }
+    }
+
+    return Object.keys(hints).length > 0 ? hints : undefined;
+  }
+
+  /**
+   * Extract button label from @returns {@label} tag
+   * Example: @returns {@label Calculate Sum} The result
+   * Example: @returns {@label Run Query}
+   */
+  private extractButtonLabel(jsdocContent: string): string | undefined {
+    // Look for {@label ...} in @returns tag
+    const returnsMatch = jsdocContent.match(/@returns?\s+.*?\{@label\s+([^}]+)\}/i);
+    if (returnsMatch) {
+      return returnsMatch[1].trim();
     }
+    return undefined;
+  }
 
+  /**
+   * Extract icon from @icon tag
+   * Example: @icon calculator
+   * Example: @icon 🧮
+   * Example: @icon mdi:calculator
+   */
+  private extractIcon(jsdocContent: string): string | undefined {
+    const iconMatch = jsdocContent.match(/@icon\s+([^\s@*]+)/i);
+    if (iconMatch) {
+      return iconMatch[1].trim();
+    }
     return undefined;
   }
 

package/src/stateful.ts

@@ -56,6 +56,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { createReadStream } from 'fs';
 import { createInterface } from 'readline';
+import { executionContext } from '@portel/cli';
 import type {
   StateLogEntry,
   StateLogStart,
@@ -641,6 +642,306 @@ export async function cleanupRuns(maxAgeMs: number, runsDir?: string): Promise<n
   return deleted;
 }
 
+// ══════════════════════════════════════════════════════════════════════════════
+// IMPLICIT STATEFUL EXECUTOR - Auto-detect checkpoint usage
+// ══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Configuration for maybeStatefulExecute
+ */
+export interface MaybeStatefulConfig {
+  /** Photon name */
+  photon: string;
+  /** Tool name being executed */
+  tool: string;
+  /** Input parameters */
+  params: Record<string, any>;
+  /** Input provider for ask yields */
+  inputProvider: InputProvider;
+  /** Output handler for emit yields */
+  outputHandler?: OutputHandler;
+  /** Runs directory (defaults to ~/.photon/runs) */
+  runsDir?: string;
+  /** Existing run ID to resume (if set, forces stateful mode) */
+  resumeRunId?: string;
+}
+
+/**
+ * Result of maybe-stateful execution
+ */
+export interface MaybeStatefulResult<T> {
+  /** Final result (if completed) */
+  result?: T;
+  /** Error message (if failed) */
+  error?: string;
+  /** Run ID (only if stateful - checkpoint was yielded) */
+  runId?: string;
+  /** Was this a stateful workflow? */
+  isStateful: boolean;
+  /** Was this resumed from a previous run? */
+  resumed: boolean;
+  /** Step number resumed from (if resumed) */
+  resumedFromStep?: number;
+  /** Total checkpoints completed */
+  checkpointsCompleted: number;
+  /** Final status */
+  status: WorkflowStatus;
+}
+
+/**
+ * Buffered event from early execution (before stateful mode detected)
+ */
+interface BufferedEvent {
+  type: 'emit' | 'ask' | 'answer';
+  data: any;
+}
+
+/**
+ * Execute a generator with implicit checkpoint detection
+ *
+ * - If the generator yields checkpoint, automatically becomes stateful (JSONL persistence)
+ * - If no checkpoint, runs as ephemeral (no persistence overhead)
+ * - Seamlessly handles resume if runId is provided
+ *
+ * @example
+ * const result = await maybeStatefulExecute(
+ *   () => myPhoton.myMethod(params),
+ *   {
+ *     photon: 'my-photon',
+ *     tool: 'myMethod',
+ *     params,
+ *     inputProvider: cliInputProvider
+ *   }
+ * );
+ *
+ * if (result.isStateful) {
+ *   console.log(`Run ID: ${result.runId}`);
+ * }
+ */
+export async function maybeStatefulExecute<T>(
+  generatorFn: () => AsyncGenerator<StatefulYield, T, any> | Promise<T>,
+  config: MaybeStatefulConfig
+): Promise<MaybeStatefulResult<T>> {
+  return executionContext.run({ outputHandler: config.outputHandler }, async () => {
+    // If resuming, use stateful executor directly
+    if (config.resumeRunId) {
+    // Get resume state to find step number
+    const resumeState = await parseResumeState(config.resumeRunId, config.runsDir);
+
+    // Validate run exists
+    if (!resumeState) {
+      return {
+        error: `Run not found: ${config.resumeRunId}`,
+        isStateful: false,
+        resumed: false,
+        checkpointsCompleted: 0,
+        status: 'failed',
+      };
+    }
+
+    // Check if already completed
+    if (resumeState.isComplete) {
+      return {
+        result: resumeState.result,
+        error: resumeState.error,
+        runId: config.resumeRunId,
+        isStateful: true,
+        resumed: true,
+        resumedFromStep: resumeState.lastCheckpoint?.state?.step as number | undefined,
+        checkpointsCompleted: resumeState.entries.filter(e => e.t === 'checkpoint').length,
+        status: resumeState.error ? 'failed' : 'completed',
+      };
+    }
+
+    const resumedFromStep = resumeState.lastCheckpoint?.state?.step as number | undefined;
+
+    // Count existing checkpoints
+    const existingCheckpoints = resumeState.entries.filter(e => e.t === 'checkpoint').length;
+
+    const statefulResult = await executeStatefulGenerator<T>(
+      generatorFn as () => AsyncGenerator<StatefulYield, T, any>,
+      {
+        runId: config.resumeRunId,
+        runsDir: config.runsDir,
+        photon: config.photon,
+        tool: config.tool,
+        params: config.params,
+        inputProvider: config.inputProvider,
+        outputHandler: config.outputHandler,
+        resume: true,
+      }
+    );
+
+    // Count total checkpoints after execution
+    const finalState = await parseResumeState(config.resumeRunId, config.runsDir);
+    const totalCheckpoints = finalState?.entries.filter(e => e.t === 'checkpoint').length || existingCheckpoints;
+
+    return {
+      result: statefulResult.result,
+      error: statefulResult.error,
+      runId: statefulResult.runId,
+      isStateful: true,
+      resumed: statefulResult.resumed,
+      resumedFromStep,
+      checkpointsCompleted: totalCheckpoints,
+      status: statefulResult.status,
+    };
+  }
+
+  // Call the function
+  const maybeGenerator = generatorFn();
+
+  // Handle non-generator functions (regular async methods)
+  if (!isAsyncGenerator(maybeGenerator)) {
+    try {
+      const finalValue = await maybeGenerator;
+      return {
+        result: finalValue,
+        isStateful: false,
+        resumed: false,
+        checkpointsCompleted: 0,
+        status: 'completed',
+      };
+    } catch (error: any) {
+      return {
+        error: error.message,
+        isStateful: false,
+        resumed: false,
+        checkpointsCompleted: 0,
+        status: 'failed',
+      };
+    }
+  }
+
+  // It's a generator - execute with checkpoint detection
+  const generator = maybeGenerator;
+  const bufferedEvents: BufferedEvent[] = [];
+  let isStateful = false;
+  let runId: string | undefined;
+  let log: StateLog | undefined;
+  let checkpointIndex = 0;
+  let askIndex = 0;
+
+  /**
+   * Initialize stateful mode on first checkpoint
+   */
+  async function initStateful(): Promise<void> {
+    if (isStateful) return;
+
+    isStateful = true;
+    runId = generateRunId();
+    log = new StateLog(runId, config.runsDir);
+    await log.init();
+
+    // Write start entry
+    await log.writeStart(config.tool, config.params);
+
+    // Replay buffered events to log
+    for (const event of bufferedEvents) {
+      if (event.type === 'emit') {
+        const emit = event.data as EmitYield;
+        await log.writeEmit(emit.emit, (emit as any).message, emit);
+      } else if (event.type === 'ask') {
+        const { id, ask, message } = event.data;
+        await log.writeAsk(id, ask, message);
+      } else if (event.type === 'answer') {
+        const { id, value } = event.data;
+        await log.writeAnswer(id, value);
+      }
+    }
+    bufferedEvents.length = 0; // Clear buffer
+  }
+
+  try {
+    let result = await generator.next();
+
+    while (!result.done) {
+      const yielded = result.value;
+
+      if (isCheckpointYield(yielded)) {
+        // First checkpoint triggers stateful mode
+        await initStateful();
+
+        const cpId = yielded.id || `cp_${checkpointIndex++}`;
+        await log!.writeCheckpoint(cpId, yielded.state);
+
+        // Continue with the state
+        result = await generator.next(yielded.state);
+      } else if (isAskYield(yielded as PhotonYield)) {
+        const askYield = yielded as AskYield;
+        const askId = askYield.id || `ask_${askIndex++}`;
+
+        // Buffer or log ask
+        if (isStateful) {
+          await log!.writeAsk(askId, askYield.ask, askYield.message);
+        } else {
+          bufferedEvents.push({ type: 'ask', data: { id: askId, ask: askYield.ask, message: askYield.message } });
+        }
+
+        // Get input
+        const input = await config.inputProvider(askYield);
+
+        // Buffer or log answer
+        if (isStateful) {
+          await log!.writeAnswer(askId, input);
+        } else {
+          bufferedEvents.push({ type: 'answer', data: { id: askId, value: input } });
+        }
+
+        result = await generator.next(input);
+      } else if (isEmitYield(yielded as PhotonYield)) {
+        const emitYield = yielded as EmitYield;
+
+        // Buffer or log emit
+        if (isStateful) {
+          await log!.writeEmit(emitYield.emit, (emitYield as any).message, emitYield);
+        } else {
+          bufferedEvents.push({ type: 'emit', data: emitYield });
+        }
+
+        // Call output handler
+        if (config.outputHandler) {
+          await config.outputHandler(emitYield);
+        }
+
+        result = await generator.next();
+      } else {
+        // Unknown yield, skip
+        result = await generator.next();
+      }
+    }
+
+    // Write return entry if stateful
+    if (isStateful && log) {
+      await log.writeReturn(result.value);
+    }
+
+    return {
+      result: result.value,
+      runId,
+      isStateful,
+      resumed: false,
+      checkpointsCompleted: checkpointIndex,
+      status: 'completed',
+    };
+  } catch (error: any) {
+    // Write error entry if stateful
+    if (isStateful && log) {
+      await log.writeError(error.message, error.stack);
+    }
+
+    return {
+      error: error.message,
+      runId,
+      isStateful,
+      resumed: false,
+      checkpointsCompleted: checkpointIndex,
+      status: 'failed',
+    };
+  }
+  });
+}
+
 // ══════════════════════════════════════════════════════════════════════════════
 // EXPORTS
 // ══════════════════════════════════════════════════════════════════════════════

package/src/types.ts

@@ -9,7 +9,8 @@
  */
 export type OutputFormat =
   | 'primitive' | 'table' | 'tree' | 'list' | 'none'
-  | 'json' | 'markdown' | 'yaml' | 'xml' | 'html'
+  | 'json' | 'markdown' | 'yaml' | 'xml' | 'html' | 'mermaid'
+  | 'card' | 'grid' | 'chips' | 'kv' | 'tabs' | 'accordion'
   | `code` | `code:${string}`;
 
 export interface PhotonTool {
@@ -48,12 +49,20 @@ export interface ExtractedSchema {
     required?: string[];
   };
   outputFormat?: OutputFormat;
+  /** Layout hints from nested @format syntax: @format list {@title name, @subtitle email} */
+  layoutHints?: Record<string, string>;
+  /** Custom button label from @returns {@label} tag */
+  buttonLabel?: string;
+  /** Icon from @icon tag (emoji or icon name) */
+  icon?: string;
   /** True if this method is an async generator (uses yield for prompts) */
   isGenerator?: boolean;
   /** Yield information for generator methods (used by REST APIs) */
   yields?: YieldInfo[];
   /** True if this is a stateful workflow (supports checkpoint/resume) */
   isStateful?: boolean;
+  /** True if this method should auto-execute when selected (idempotent, no required params) */
+  autorun?: boolean;
 }
 
 export interface PhotonMCPClass {