@portel/photon-core 2.14.0 → 2.16.0

package/src/base.ts

@@ -40,11 +40,13 @@
  */
 
 import { MCPClient, MCPClientFactory, createMCPProxy } from '@portel/mcp';
-import { executionContext } from '@portel/cli';
+import { executionContext, type CallerInfo } from '@portel/cli';
 import { getBroker } from './channels/index.js';
 import { withLock as withLockHelper } from './decorators.js';
 import { MemoryProvider } from './memory.js';
 import { ScheduleProvider } from './schedule.js';
+import * as path from 'path';
+import * as fs from 'fs';
 
 /**
  * Simple base class for creating Photons
@@ -61,6 +63,20 @@ export class Photon {
    */
   _photonName?: string;
 
+  /**
+   * Absolute path to the .photon.ts/.photon.js source file - set by runtime loader
+   * Used for storage() and assets() path resolution
+   * @internal
+   */
+  _photonFilePath?: string;
+
+  /**
+   * Dynamic photon resolver - injected by runtime loader
+   * Used by this.photon.use() for runtime photon access
+   * @internal
+   */
+  _photonResolver?: (name: string, instance?: string) => Promise<any>;
+
   /**
    * Scoped memory provider - lazy-initialized on first access
    * @internal
@@ -79,6 +95,28 @@ export class Photon {
    */
   _sessionId?: string;
 
+  /**
+   * Authenticated caller identity
+   *
+   * Populated from MCP OAuth when `@auth` is enabled on the photon.
+   * Returns the identity of whoever is calling the current method —
+   * human (via social login) or agent (via API key).
+   *
+   * Returns an anonymous caller if no auth token was provided.
+   *
+   * @example
+   * ```typescript
+   * // In a method:
+   * const userId = this.caller.id;     // stable user ID from JWT
+   * const name = this.caller.name;     // display name
+   * const isAnon = this.caller.anonymous; // true if no auth
+   * ```
+   */
+  get caller(): CallerInfo {
+    const store = executionContext.getStore();
+    return store?.caller ?? { id: 'anonymous', anonymous: true };
+  }
+
   /**
    * Scoped key-value storage for photon data
    *
@@ -156,6 +194,103 @@ export class Photon {
     return this._schedule;
   }
 
+  /**
+   * Get an absolute path to a storage directory for this photon's data.
+   *
+   * Uses the symlink/installed path (not resolved) so data stays at the
+   * installed location. Directories are auto-created.
+   *
+   * @param subpath Sub-directory within the photon's data folder (e.g., 'auth', 'media')
+   * @returns Absolute path to the directory
+   *
+   * @example
+   * ```typescript
+   * const authDir = this.storage('auth');
+   * // ~/.photon/portel-dev/whatsapp/auth/
+   *
+   * const mediaDir = this.storage('media/images');
+   * // ~/.photon/portel-dev/whatsapp/media/images/
+   * ```
+   */
+  protected storage(subpath: string): string {
+    if (!this._photonFilePath) {
+      throw new Error(
+        'storage() requires _photonFilePath to be set by the runtime loader. ' +
+        'Ensure this photon is loaded through the standard runtime.'
+      );
+    }
+    const dir = path.dirname(this._photonFilePath);
+    const name = path.basename(this._photonFilePath).replace(/\.photon\.(ts|js)$/, '');
+    const target = path.join(dir, name, subpath);
+    fs.mkdirSync(target, { recursive: true });
+    return target;
+  }
+
+  /**
+   * Get an absolute path to an assets directory for this photon.
+   *
+   * Uses realpathSync to follow symlinks — assets travel with source code,
+   * not the installed location. Useful for marketplace-distributed resources
+   * like HTML templates, images, etc.
+   *
+   * @param subpath Sub-path within the assets folder (e.g., 'templates', 'icons/logo.png')
+   * @returns Absolute path to the asset file or directory
+   *
+   * @example
+   * ```typescript
+   * const templateDir = this.assets('templates');
+   * // /real/path/to/portel-dev/whatsapp/assets/templates/
+   *
+   * const logo = this.assets('icons/logo.png');
+   * // /real/path/to/portel-dev/whatsapp/assets/icons/logo.png
+   * ```
+   */
+  protected assets(subpath: string): string {
+    if (!this._photonFilePath) {
+      throw new Error(
+        'assets() requires _photonFilePath to be set by the runtime loader. ' +
+        'Ensure this photon is loaded through the standard runtime.'
+      );
+    }
+    const realPath = fs.realpathSync(this._photonFilePath);
+    const dir = path.dirname(realPath);
+    const name = path.basename(realPath).replace(/\.photon\.(ts|js)$/, '');
+    return path.join(dir, name, 'assets', subpath);
+  }
+
+  /**
+   * Dynamic photon access
+   *
+   * Provides runtime access to other photons by name, with optional instance selection.
+   * Supports both short names and namespace-qualified names.
+   *
+   * @example
+   * ```typescript
+   * // Get default instance
+   * const wa = await this.photon.use('whatsapp');
+   *
+   * // Get named instance
+   * const personal = await this.photon.use('whatsapp', 'personal');
+   *
+   * // Cross-namespace access
+   * const wa2 = await this.photon.use('portel-dev:whatsapp', 'work');
+   * ```
+   */
+  get photon(): { use: (name: string, instance?: string) => Promise<any> } {
+    const resolver = this._photonResolver;
+    return {
+      use: async (name: string, instance?: string) => {
+        if (!resolver) {
+          throw new Error(
+            'this.photon.use() requires a runtime with photon resolution. ' +
+            'Ensure this photon is loaded through the standard runtime.'
+          );
+        }
+        return resolver(name, instance);
+      },
+    };
+  }
+
   /**
    * Emit an event/progress update
    *
@@ -216,6 +351,45 @@ export class Photon {
       });
     }
   }
+
+  /**
+   * Render a formatted value as an intermediate result
+   *
+   * Sends a value to the client (Beam, CLI, MCP) rendered with the specified
+   * format — the same formats available via `@format` docblock tags. Each call
+   * replaces the previous render in the result panel.
+   *
+   * For custom formats, place an HTML renderer at `assets/formats/<name>.html`.
+   *
+   * @param format The format type (table, qr, chart:bar, dashboard, or custom)
+   * @param value The data to render — same shape as a return value with that @format
+   *
+   * @example
+   * ```typescript
+   * // Show a QR code mid-execution
+   * this.render('qr', { value: 'https://wa.link/...' });
+   *
+   * // Show a status table
+   * this.render('table', [['Step', 'Status'], ['Auth', 'Done']]);
+   *
+   * // Composite dashboard
+   * this.render('dashboard', {
+   *   qr: { format: 'qr', data: 'https://wa.link/...' },
+   *   status: { format: 'text', data: 'Scan the QR code above' }
+   * });
+   * ```
+   */
+  protected render(format: string, value: any): void;
+  protected render(): void;
+  protected render(format?: string, value?: any): void {
+    if (format === undefined) {
+      // Clear the render zone without rendering new content
+      this.emit({ emit: 'render:clear' });
+    } else {
+      this.emit({ emit: 'render', format, value });
+    }
+  }
+
   /**
    * Cross-photon call handler - injected by runtime
    * @internal
@@ -305,16 +479,13 @@ export class Photon {
     ]);
 
     // Get all property names from prototype chain
+    // Use getOwnPropertyDescriptor to avoid triggering getters (which may call storage())
     let current = prototype;
     while (current && current !== Photon.prototype) {
       Object.getOwnPropertyNames(current).forEach((name) => {
-        // Skip private methods (starting with _) and convention methods
-        if (
-          !name.startsWith('_') &&
-          !conventionMethods.has(name) &&
-          typeof (prototype as any)[name] === 'function' &&
-          !methods.includes(name)
-        ) {
+        if (name.startsWith('_') || conventionMethods.has(name) || methods.includes(name)) return;
+        const desc = Object.getOwnPropertyDescriptor(current, name);
+        if (desc && typeof desc.value === 'function') {
           methods.push(name);
         }
       });
@@ -466,4 +637,106 @@ export class Photon {
   ): Promise<T> {
     return withLockHelper(lockName, fn, timeout);
   }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // IDENTITY-AWARE LOCK MANAGEMENT
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /**
+   * Identity-aware lock handler - injected by runtime
+   * @internal
+   */
+  _lockHandler?: {
+    assign(lockName: string, holder: string, timeout?: number): Promise<boolean>;
+    transfer(lockName: string, fromHolder: string, toHolder: string, timeout?: number): Promise<boolean>;
+    release(lockName: string, holder: string): Promise<boolean>;
+    query(lockName: string): Promise<{ holder: string | null; acquiredAt?: number; expiresAt?: number }>;
+  };
+
+  /**
+   * Assign a lock to a specific caller (identity-aware)
+   *
+   * Unlike `withLock` which auto-acquires/releases around a function,
+   * this explicitly assigns a lock to a caller ID. The lock persists
+   * until transferred or released.
+   *
+   * @param lockName Name of the lock
+   * @param callerId Caller ID to assign the lock to
+   * @param timeout Lock timeout in ms (default 30000, auto-extended on transfer)
+   *
+   * @example
+   * ```typescript
+   * // Assign "turn" lock to first player
+   * await this.acquireLock('turn', this.caller.id);
+   * ```
+   */
+  protected async acquireLock(lockName: string, callerId: string, timeout?: number): Promise<boolean> {
+    if (!this._lockHandler) {
+      console.warn(`[photon] acquireLock('${lockName}'): no lock handler configured`);
+      return true;
+    }
+    return this._lockHandler.assign(lockName, callerId, timeout);
+  }
+
+  /**
+   * Transfer a lock from the current holder to another caller
+   *
+   * Only succeeds if `fromCallerId` is the current holder.
+   *
+   * @param lockName Name of the lock
+   * @param toCallerId Caller ID to transfer the lock to
+   * @param fromCallerId Current holder (defaults to this.caller.id)
+   *
+   * @example
+   * ```typescript
+   * // After a chess move, transfer turn to opponent
+   * await this.transferLock('turn', opponentId);
+   * ```
+   */
+  protected async transferLock(lockName: string, toCallerId: string, fromCallerId?: string): Promise<boolean> {
+    if (!this._lockHandler) {
+      console.warn(`[photon] transferLock('${lockName}'): no lock handler configured`);
+      return true;
+    }
+    return this._lockHandler.transfer(lockName, fromCallerId ?? this.caller.id, toCallerId);
+  }
+
+  /**
+   * Release a lock (make the method open to anyone)
+   *
+   * @param lockName Name of the lock
+   * @param callerId Holder to release from (defaults to this.caller.id)
+   *
+   * @example
+   * ```typescript
+   * // Presenter releases navigation control to audience
+   * await this.releaseLock('navigation');
+   * ```
+   */
+  protected async releaseLock(lockName: string, callerId?: string): Promise<boolean> {
+    if (!this._lockHandler) {
+      console.warn(`[photon] releaseLock('${lockName}'): no lock handler configured`);
+      return true;
+    }
+    return this._lockHandler.release(lockName, callerId ?? this.caller.id);
+  }
+
+  /**
+   * Query who holds a specific lock
+   *
+   * @param lockName Name of the lock
+   * @returns Lock holder info, or null holder if unlocked
+   *
+   * @example
+   * ```typescript
+   * const lock = await this.getLock('turn');
+   * if (lock.holder === this.caller.id) { ... }
+   * ```
+   */
+  protected async getLock(lockName: string): Promise<{ holder: string | null; acquiredAt?: number; expiresAt?: number }> {
+    if (!this._lockHandler) {
+      return { holder: null };
+    }
+    return this._lockHandler.query(lockName);
+  }
 }

package/src/generator.ts

@@ -730,6 +730,23 @@ export interface EmitQR {
   value: string;
 }
 
+/**
+ * Render emit — sends a formatted intermediate result to the client.
+ * The value is rendered using the same format pipeline as @format return values.
+ * Custom formats are resolved from assets/formats/<name>.html.
+ */
+export interface EmitRender {
+  emit: 'render';
+  /** Format type (table, qr, chart:bar, dashboard, or custom name) */
+  format: string;
+  /** Data to render — same shape as a return value with that @format */
+  value: any;
+}
+
+export interface EmitRenderClear {
+  emit: 'render:clear';
+}
+
 export type EmitYield =
   | EmitStatus
   | EmitProgress
@@ -739,7 +756,9 @@ export type EmitYield =
   | EmitThinking
   | EmitArtifact
   | EmitUI
-  | EmitQR;
+  | EmitQR
+  | EmitRender
+  | EmitRenderClear;
 
 // ══════════════════════════════════════════════════════════════════════════════
 // COMBINED TYPES

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   executionContext,
   runWithContext,
   getContext,
+  type CallerInfo,
 
   // Text Utils
   TextUtils,
@@ -166,12 +167,15 @@ export { SchemaExtractor, detectCapabilities, type PhotonCapability } from './sc
 export {
   resolvePath,
   listFiles,
+  listFilesWithNamespace,
   ensureDir,
   resolvePhotonPath,
   listPhotonFiles,
+  listPhotonFilesWithNamespace,
   ensurePhotonDir,
   DEFAULT_PHOTON_DIR,
   type ResolverOptions,
+  type ListedPhoton,
 } from './path-resolver.js';
 
 // Types
@@ -239,6 +243,8 @@ export {
   type EmitArtifact,
   type EmitUI,
   type EmitQR,
+  type EmitRender,
+  type EmitRenderClear,
 
   // Checkpoint yield type
   type CheckpointYield,

package/src/mixins.ts

@@ -23,7 +23,7 @@
  */
 
 import { MCPClient, MCPClientFactory, createMCPProxy } from '@portel/mcp';
-import { executionContext } from '@portel/cli';
+import { executionContext, type CallerInfo } from '@portel/cli';
 import { getBroker } from './channels/index.js';
 import { MemoryProvider } from './memory.js';
 import { ScheduleProvider } from './schedule.js';
@@ -94,6 +94,14 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
      */
     private _mcpClients: Map<string, MCPClient & Record<string, (params?: any) => Promise<any>>> = new Map();
 
+    /**
+     * Authenticated caller identity from MCP OAuth
+     */
+    get caller(): CallerInfo {
+      const store = executionContext.getStore();
+      return store?.caller ?? { id: 'anonymous', anonymous: true };
+    }
+
     /**
      * Scoped key-value storage for photon data
      */
@@ -124,6 +132,18 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
       return this._schedule;
     }
 
+    /**
+     * Render a formatted value as an intermediate result.
+     * Each call replaces the previous render. Call with no args to clear.
+     */
+    protected render(format?: string, value?: any): void {
+      if (format === undefined) {
+        this.emit({ emit: 'render:clear' });
+      } else {
+        this.emit({ emit: 'render', format, value });
+      }
+    }
+
     /**
      * Emit an event/progress update
      */
@@ -139,9 +159,15 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
       }
 
       if (data && typeof data.channel === 'string') {
+        // Auto-prefix channel with photon name if not already namespaced
+        const channel = data.channel.includes(':')
+          ? data.channel
+          : this._photonName
+            ? `${this._photonName}:${data.channel}`
+            : data.channel;
         const broker = getBroker();
         broker.publish({
-          channel: data.channel,
+          channel,
           event: data.event || 'message',
           data: data.data !== undefined ? data.data : data,
           timestamp: Date.now(),

package/src/path-resolver.ts

@@ -3,6 +3,14 @@
  *
  * Generic path resolution utilities used by photon, lumina, ncp.
  * Configurable file extensions and default directories.
+ *
+ * Supports namespace-based directory structure:
+ *   ~/.photon/
+ *     portel-dev/          ← namespace (marketplace author)
+ *       whatsapp.photon.ts
+ *     local/               ← implicit namespace for user-created photons
+ *       todo.photon.ts
+ *     legacy.photon.ts     ← flat files (pre-migration, still supported)
  */
 
 import * as fs from 'fs/promises';
@@ -37,9 +45,17 @@ const defaultOptions: Required<ResolverOptions> = {
   defaultDir: DEFAULT_PHOTON_DIR,
 };
 
+/** Directories to skip when scanning for namespace subdirectories */
+const SKIP_DIRS = new Set([
+  'state', 'context', 'env', '.cache', '.config',
+  'node_modules', 'marketplace', 'photons', 'templates',
+]);
+
 /**
- * Resolve a file path from name
- * Looks in the specified working directory, or uses absolute path if provided
+ * Resolve a file path from name.
+ *
+ * Supports namespace-qualified names: 'namespace:photonName'
+ * For unqualified names, searches flat files first, then namespace subdirectories.
  */
 export async function resolvePath(
   name: string,
@@ -59,66 +75,172 @@ export async function resolvePath(
     }
   }
 
+  // Parse namespace:name format
+  const colonIndex = name.indexOf(':');
+  let namespace: string | undefined;
+  let photonName: string;
+  if (colonIndex !== -1) {
+    namespace = name.slice(0, colonIndex);
+    photonName = name.slice(colonIndex + 1);
+  } else {
+    photonName = name;
+  }
+
   // Remove extension if provided (match any configured extension)
-  let basename = name;
+  let basename = photonName;
   for (const ext of opts.extensions) {
-    if (name.endsWith(ext)) {
-      basename = name.slice(0, -ext.length);
+    if (photonName.endsWith(ext)) {
+      basename = photonName.slice(0, -ext.length);
       break;
     }
   }
 
-  // Try each extension
+  // If namespace is specified, search only that namespace directory
+  if (namespace) {
+    for (const ext of opts.extensions) {
+      const filePath = path.join(dir, namespace, `${basename}${ext}`);
+      try {
+        await fs.access(filePath);
+        return filePath;
+      } catch {
+        // Continue
+      }
+    }
+    return null;
+  }
+
+  // Unqualified name: search flat files first (backward compat)
   for (const ext of opts.extensions) {
     const filePath = path.join(dir, `${basename}${ext}`);
     try {
       await fs.access(filePath);
       return filePath;
     } catch {
-      // Continue to next extension
+      // Continue
+    }
+  }
+
+  // Then search namespace subdirectories (one level deep)
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+        continue;
+      }
+      for (const ext of opts.extensions) {
+        const filePath = path.join(dir, entry.name, `${basename}${ext}`);
+        try {
+          await fs.access(filePath);
+          return filePath;
+        } catch {
+          // Continue
+        }
+      }
     }
+  } catch {
+    // dir doesn't exist
   }
 
-  // Not found
   return null;
 }
 
 /**
- * List all matching files in a directory
+ * Result from listing files, including namespace information.
+ */
+export interface ListedPhoton {
+  /** Short name (e.g., 'whatsapp') */
+  name: string;
+  /** Namespace (e.g., 'portel-dev') or empty string for flat/root-level files */
+  namespace: string;
+  /** Qualified name (e.g., 'portel-dev:whatsapp' or 'whatsapp' for flat) */
+  qualifiedName: string;
+  /** Full absolute path to the file */
+  filePath: string;
+}
+
+/**
+ * List all matching files in a directory.
+ *
+ * Scans both flat files (backward compat) and namespace subdirectories.
+ * Returns short names for backward compatibility.
  */
 export async function listFiles(
   workingDir?: string,
   options?: ResolverOptions
 ): Promise<string[]> {
+  const listed = await listFilesWithNamespace(workingDir, options);
+  return listed.map((l) => l.name).sort();
+}
+
+/**
+ * List all matching files with full namespace metadata.
+ *
+ * Scans flat files at the root level and one level of namespace subdirectories.
+ */
+export async function listFilesWithNamespace(
+  workingDir?: string,
+  options?: ResolverOptions
+): Promise<ListedPhoton[]> {
   const opts = { ...defaultOptions, ...options };
   const dir = expandTilde(workingDir || opts.defaultDir);
+  const results: ListedPhoton[] = [];
 
   try {
-    // Ensure directory exists
     await fs.mkdir(dir, { recursive: true });
-
     const entries = await fs.readdir(dir, { withFileTypes: true });
-    const files: string[] = [];
 
+    // Scan flat files at root level (backward compat / pre-migration)
     for (const entry of entries) {
-      // Include both regular files and symlinks
       if (entry.isFile() || entry.isSymbolicLink()) {
-        // Check if file matches any extension
         for (const ext of opts.extensions) {
           if (entry.name.endsWith(ext)) {
-            // Remove extension for display
             const name = entry.name.slice(0, -ext.length);
-            files.push(name);
+            results.push({
+              name,
+              namespace: '',
+              qualifiedName: name,
+              filePath: path.join(dir, entry.name),
+            });
             break;
           }
         }
       }
     }
 
-    return files.sort();
+    // Scan namespace subdirectories (one level deep)
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+        continue;
+      }
+
+      const nsDir = path.join(dir, entry.name);
+      try {
+        const nsEntries = await fs.readdir(nsDir, { withFileTypes: true });
+        for (const nsEntry of nsEntries) {
+          if (nsEntry.isFile() || nsEntry.isSymbolicLink()) {
+            for (const ext of opts.extensions) {
+              if (nsEntry.name.endsWith(ext)) {
+                const name = nsEntry.name.slice(0, -ext.length);
+                results.push({
+                  name,
+                  namespace: entry.name,
+                  qualifiedName: `${entry.name}:${name}`,
+                  filePath: path.join(nsDir, nsEntry.name),
+                });
+                break;
+              }
+            }
+          }
+        }
+      } catch {
+        // Namespace dir unreadable, skip
+      }
+    }
   } catch {
-    return [];
+    // Root dir doesn't exist
   }
+
+  return results;
 }
 
 /**
@@ -132,4 +254,5 @@ export async function ensureDir(dir?: string): Promise<void> {
 // Convenience aliases for photon-specific usage
 export const resolvePhotonPath = resolvePath;
 export const listPhotonFiles = listFiles;
+export const listPhotonFilesWithNamespace = listFilesWithNamespace;
 export const ensurePhotonDir = ensureDir;