@portel/photon-core 2.8.0 → 2.8.2

package/src/generator.ts

@@ -1220,72 +1220,3 @@ export async function* wrapAsGenerator<T>(
   return await asyncFn();
 }
 
-// ══════════════════════════════════════════════════════════════════════════════
-// LEGACY COMPATIBILITY - Map old format to new
-// ══════════════════════════════════════════════════════════════════════════════
-
-/**
- * @deprecated Use AskYield instead
- */
-export type PromptYield = AskText | AskPassword;
-
-/**
- * @deprecated Use AskConfirm instead
- */
-export type ConfirmYield = AskConfirm;
-
-/**
- * @deprecated Use AskSelect instead
- */
-export type SelectYield = AskSelect;
-
-/**
- * @deprecated Use EmitProgress instead
- */
-export type ProgressYield = EmitProgress;
-
-/**
- * @deprecated Use EmitStream instead
- */
-export type StreamYield = EmitStream;
-
-/**
- * @deprecated Use EmitLog instead
- */
-export type LogYield = EmitLog;
-
-/**
- * @deprecated Use isAskYield instead
- */
-export const isInputYield = isAskYield;
-
-/**
- * @deprecated Use isEmitYield instead
- */
-export function isProgressYield(y: PhotonYield): y is EmitProgress {
-  return isEmitYield(y) && y.emit === 'progress';
-}
-
-/**
- * @deprecated Use isEmitYield instead
- */
-export function isStreamYield(y: PhotonYield): y is EmitStream {
-  return isEmitYield(y) && y.emit === 'stream';
-}
-
-/**
- * @deprecated Use isEmitYield instead
- */
-export function isLogYield(y: PhotonYield): y is EmitLog {
-  return isEmitYield(y) && y.emit === 'log';
-}
-
-/**
- * @deprecated Use extractAsks instead
- */
-export const extractYields = extractAsks;
-
-/**
- * @deprecated Use ExtractedAsk instead
- */
-export type ExtractedYield = ExtractedAsk;

package/src/index.ts

@@ -249,20 +249,6 @@ export {
   type OutputHandler,
   type GeneratorExecutorConfig,
   type ExtractedAsk,
-
-  // Legacy compatibility
-  isInputYield,
-  isProgressYield,
-  isStreamYield,
-  isLogYield,
-  extractYields,
-  type PromptYield,
-  type ConfirmYield,
-  type SelectYield,
-  type ProgressYield,
-  type StreamYield,
-  type LogYield,
-  type ExtractedYield,
 } from './generator.js';
 
 // Stateful Workflow Execution

package/src/mcp-apps.ts

@@ -39,7 +39,7 @@ export interface McpAppsInitialize {
       width?: number;
       height?: number;
     };
-    // Legacy flat theme tokens (kept for backward compat with Photon apps)
+    // Flat theme tokens for Photon Bridge apps
     theme: Record<string, string>;
     safeAreaInsets?: { top: number; bottom: number; left: number; right: number };
   };
@@ -154,7 +154,6 @@ export function createMcpAppsInitialize(
         width: dimensions.width,
         height: dimensions.height,
       },
-      // Legacy flat theme tokens for backward compat
       theme: themeTokens,
       ...(context.safeAreaInsets ? { safeAreaInsets: context.safeAreaInsets } : {}),
     },
@@ -178,7 +177,7 @@ export function createThemeChangeMessages(theme: 'light' | 'dark'): unknown[] {
         styles: { variables: themeTokens },
       },
     },
-    // MCP Apps Extension (legacy name for backward compat)
+    // MCP Apps Extension (older spec draft name, still used by some clients)
     {
       jsonrpc: '2.0',
       method: 'ui/notifications/context',

package/src/memory.ts

@@ -24,7 +24,7 @@
  * ```
  */
 
-import * as fs from 'fs';
+import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 
@@ -74,6 +74,18 @@ function keyPath(dir: string, key: string): string {
   return path.join(dir, `${safeKey}.json`);
 }
 
+/**
+ * Check if a path exists (async)
+ */
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Scoped Memory Provider
  *
@@ -112,11 +124,11 @@ export class MemoryProvider {
     const filePath = keyPath(dir, key);
 
     try {
-      if (!fs.existsSync(filePath)) return null;
-      const content = fs.readFileSync(filePath, 'utf-8');
+      const content = await fs.readFile(filePath, 'utf-8');
       return JSON.parse(content) as T;
-    } catch {
-      return null;
+    } catch (error: any) {
+      if (error.code === 'ENOENT') return null;
+      throw error;
     }
   }
 
@@ -130,12 +142,12 @@ export class MemoryProvider {
   async set<T = any>(key: string, value: T, scope: MemoryScope = 'photon'): Promise<void> {
     const dir = resolveDir(this._photonId, scope, this._sessionId);
 
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
+    if (!await pathExists(dir)) {
+      await fs.mkdir(dir, { recursive: true });
     }
 
     const filePath = keyPath(dir, key);
-    fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+    await fs.writeFile(filePath, JSON.stringify(value, null, 2));
   }
 
   /**
@@ -149,11 +161,13 @@ export class MemoryProvider {
     const dir = resolveDir(this._photonId, scope, this._sessionId);
     const filePath = keyPath(dir, key);
 
-    if (fs.existsSync(filePath)) {
-      fs.unlinkSync(filePath);
+    try {
+      await fs.unlink(filePath);
       return true;
+    } catch (error: any) {
+      if (error.code === 'ENOENT') return false;
+      throw error;
     }
-    return false;
   }
 
   /**
@@ -164,7 +178,7 @@ export class MemoryProvider {
    */
   async has(key: string, scope: MemoryScope = 'photon'): Promise<boolean> {
     const dir = resolveDir(this._photonId, scope, this._sessionId);
-    return fs.existsSync(keyPath(dir, key));
+    return pathExists(keyPath(dir, key));
   }
 
   /**
@@ -175,14 +189,14 @@ export class MemoryProvider {
   async keys(scope: MemoryScope = 'photon'): Promise<string[]> {
     const dir = resolveDir(this._photonId, scope, this._sessionId);
 
-    if (!fs.existsSync(dir)) return [];
-
     try {
-      return fs.readdirSync(dir)
+      const files = await fs.readdir(dir);
+      return files
         .filter(f => f.endsWith('.json'))
-        .map(f => f.slice(0, -5)); // Remove .json extension
-    } catch {
-      return [];
+        .map(f => f.slice(0, -5));
+    } catch (error: any) {
+      if (error.code === 'ENOENT') return [];
+      throw error;
     }
   }
 
@@ -194,11 +208,13 @@ export class MemoryProvider {
   async clear(scope: MemoryScope = 'photon'): Promise<void> {
     const dir = resolveDir(this._photonId, scope, this._sessionId);
 
-    if (fs.existsSync(dir)) {
-      const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-      for (const file of files) {
-        fs.unlinkSync(path.join(dir, file));
-      }
+    try {
+      const files = await fs.readdir(dir);
+      const jsonFiles = files.filter(f => f.endsWith('.json'));
+      await Promise.all(jsonFiles.map(file => fs.unlink(path.join(dir, file))));
+    } catch (error: any) {
+      if (error.code === 'ENOENT') return;
+      throw error;
     }
   }
 
@@ -222,7 +238,10 @@ export class MemoryProvider {
   }
 
   /**
-   * Update a value atomically (read-modify-write)
+   * Update a value with read-modify-write
+   *
+   * Note: Not truly atomic under concurrent access. For concurrent
+   * writes, use distributed locking via `withLock()`.
    *
    * @param key The key to update
    * @param updater Function that receives current value and returns new value

package/src/rendering/layout-selector.ts

@@ -15,9 +15,9 @@ export type LayoutType =
   | 'tree'      // Nested object as collapsible tree
   | 'kv'        // Flat object as key-value table
   | 'chips'     // Array of strings as chips/tags
-  | 'table'     // Legacy: grid table (backward compat)
-  | 'markdown'  // Legacy: markdown rendering
-  | 'mermaid'   // Legacy: mermaid diagrams
+  | 'table'     // Grid table display
+  | 'markdown'  // Markdown rendering
+  | 'mermaid'   // Mermaid diagrams
   | 'code'      // Code block with syntax highlighting
   | 'json'      // Raw JSON display
   | 'html';     // Raw HTML (for custom UIs)
@@ -230,7 +230,7 @@ export function parseLayoutHints(hintsString: string): LayoutHints {
     // Match @key value or @key value:renderer
     const match = part.match(/@(\w+)\s+([^:]+)(?::(\w+))?/);
     if (match) {
-      const [, key, value, renderer] = match;
+      const [, key, value] = match;
       const cleanValue = value.trim();
 
       switch (key) {
@@ -368,7 +368,7 @@ function parseLayoutHints(hintsString) {
   for (const part of parts) {
     const match = part.match(/@(\\w+)\\s+([^:]+)(?::(\\w+))?/);
     if (match) {
-      const [, key, value, renderer] = match;
+      const [, key, value] = match;
       const cleanValue = value.trim();
       switch (key) {
         case 'title': hints.title = cleanValue; break;

package/src/schema-extractor.ts

@@ -1258,6 +1258,21 @@ export class SchemaExtractor {
       return subtype ? `code:${subtype}` as OutputFormat : 'code';
     }
 
+    // Match chart format (with optional chart type: bar, pie, line, donut, area)
+    if (format === 'chart') {
+      return subtype ? `chart:${subtype}` as OutputFormat : 'chart';
+    }
+
+    // Match visualization formats
+    if (['metric', 'gauge', 'timeline', 'dashboard', 'cart'].includes(format)) {
+      return format as OutputFormat;
+    }
+
+    // Match container formats
+    if (['panels', 'tabs', 'accordion', 'stack', 'columns'].includes(format)) {
+      return format as OutputFormat;
+    }
+
     return undefined;
   }
 
@@ -1541,7 +1556,7 @@ export class SchemaExtractor {
     const params = this.extractConstructorParams(source);
     const mcpDeps = this.extractMCPDependencies(source);
     const photonDeps = this.extractPhotonDependencies(source);
-    const isStateful = /@stateful\s+true/.test(source);
+    const isStateful = /@stateful\b/.test(source);
 
     // Build lookup maps
     const mcpMap = new Map(mcpDeps.map(d => [d.name, d]));

package/src/stateful.ts

@@ -130,11 +130,9 @@ export function isCheckpointYield(y: StatefulYield): y is CheckpointYield {
  * State log writer for a single workflow run
  */
 export class StateLog {
-  private runId: string;
   private logPath: string;
 
   constructor(runId: string, runsDir?: string) {
-    this.runId = runId;
     this.logPath = path.join(runsDir || RUNS_DIR, `${runId}.jsonl`);
   }
 
@@ -156,8 +154,8 @@ export class StateLog {
   /**
    * Write start entry
    */
-  async writeStart(tool: string, params: Record<string, any>): Promise<void> {
-    await this.append({ t: 'start', tool, params } as StateLogStart);
+  async writeStart(tool: string, params: Record<string, any>, photon?: string): Promise<void> {
+    await this.append({ t: 'start', tool, params, ...(photon ? { photon } : {}) } as StateLogStart);
   }
 
   /**
@@ -225,7 +223,26 @@ export class StateLog {
    * Stream entries from the log (memory efficient for large logs)
    */
   async *stream(): AsyncGenerator<StateLogEntry> {
-    const fileStream = createReadStream(this.logPath);
+    let fileStream;
+    try {
+      fileStream = createReadStream(this.logPath);
+    } catch (error: any) {
+      if (error.code === 'ENOENT') return;
+      throw error;
+    }
+
+    // Handle ENOENT that surfaces as a stream error
+    const streamReady = new Promise<void>((resolve, reject) => {
+      fileStream.once('ready', resolve);
+      fileStream.once('error', (err: any) => {
+        if (err.code === 'ENOENT') resolve();
+        else reject(err);
+      });
+    });
+    await streamReady;
+
+    if (fileStream.destroyed) return;
+
     const rl = createInterface({ input: fileStream });
 
     for await (const line of rl) {
@@ -418,7 +435,7 @@ export async function executeStatefulGenerator<T>(
 
   // Write start entry (only if not resuming)
   if (!resumed) {
-    await log.writeStart(config.tool, config.params);
+    await log.writeStart(config.tool, config.params, config.photon);
   }
 
   try {
@@ -512,7 +529,7 @@ export async function executeStatefulGenerator<T>(
         result = await generator.next(input);
       } else if (isEmitYield(yielded as PhotonYield)) {
         const emitYield = yielded as EmitYield;
-        await log.writeEmit(emitYield.emit, (emitYield as any).message, emitYield);
+        await log.writeEmit(emitYield.emit, 'message' in emitYield ? (emitYield as { message?: string }).message : undefined, emitYield);
 
         if (config.outputHandler) {
           await config.outputHandler(emitYield);
@@ -520,8 +537,7 @@ export async function executeStatefulGenerator<T>(
 
         result = await generator.next();
       } else {
-        // Unknown yield, skip
-        result = await generator.next();
+        throw new Error(`Unknown yield type: ${JSON.stringify(yielded)}`);
       }
     }
 
@@ -603,7 +619,7 @@ export async function getRunInfo(runId: string, runsDir?: string): Promise<Workf
 
   return {
     runId,
-    photon: '', // Would need to be stored in start entry
+    photon: (firstEntry as StateLogStart).photon || state.tool.split('.')[0] || 'unknown',
     tool: state.tool,
     params: state.params,
     status,
@@ -834,7 +850,7 @@ export async function maybeStatefulExecute<T>(
     await log.init();
 
     // Write start entry
-    await log.writeStart(config.tool, config.params);
+    await log.writeStart(config.tool, config.params, config.photon);
 
     // Replay buffered events to log
     for (const event of bufferedEvents) {
@@ -906,8 +922,7 @@ export async function maybeStatefulExecute<T>(
 
         result = await generator.next();
       } else {
-        // Unknown yield, skip
-        result = await generator.next();
+        throw new Error(`Unknown yield type: ${JSON.stringify(yielded)}`);
       }
     }
 

package/src/types.ts

@@ -4,13 +4,17 @@
 
 /**
  * Output format types
- * - Structural: primitive, table, tree, list, none
- * - Content: json, markdown, yaml, xml, html, code, code:<lang>
+ * - Structural: primitive, table, tree, list, none, card, grid, chips, kv
+ * - Content: json, markdown, yaml, xml, html, mermaid, code, code:<lang>
+ * - Visualization: chart, chart:<type>, metric, gauge, timeline, dashboard, cart
+ * - Container: panels, tabs, accordion, stack, columns
  */
 export type OutputFormat =
   | 'primitive' | 'table' | 'tree' | 'list' | 'none'
   | 'json' | 'markdown' | 'yaml' | 'xml' | 'html' | 'mermaid'
-  | 'card' | 'grid' | 'chips' | 'kv' | 'tabs' | 'accordion'
+  | 'card' | 'grid' | 'chips' | 'kv'
+  | 'chart' | `chart:${string}` | 'metric' | 'gauge' | 'timeline' | 'dashboard' | 'cart'
+  | 'panels' | 'tabs' | 'accordion' | 'stack' | 'columns'
   | `code` | `code:${string}`;
 
 export interface PhotonTool {
@@ -409,6 +413,8 @@ export interface StateLogStart extends StateLogBase {
   tool: string;
   /** Input parameters */
   params: Record<string, any>;
+  /** Photon name that started this run */
+  photon?: string;
 }
 
 /**