@portel/photon-core 2.6.1 → 2.8.0

package/src/class-detection.ts

@@ -51,41 +51,73 @@ export function hasAsyncMethods(ClassConstructor: new (...args: unknown[]) => un
   return false;
 }
 
+/**
+ * Check if a class has any public methods (instance or static)
+ */
+export function hasMethods(ClassConstructor: new (...args: unknown[]) => unknown): boolean {
+  const prototype = ClassConstructor.prototype;
+  for (const key of Object.getOwnPropertyNames(prototype)) {
+    if (key === 'constructor') continue;
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+    if (descriptor && typeof descriptor.value === 'function') {
+      return true;
+    }
+  }
+
+  for (const key of Object.getOwnPropertyNames(ClassConstructor)) {
+    if (['length', 'name', 'prototype'].includes(key)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(ClassConstructor, key);
+    if (descriptor && typeof descriptor.value === 'function') {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * Find a single Photon class in a module
  *
  * Priority: default export first, then named exports.
- * Returns the first class with async methods, or null.
+ * Default exports are trusted unconditionally — the file is named .photon.ts,
+ * so the user's intent is clear. For named exports, async methods are used
+ * as a heuristic to distinguish photon classes from helper classes.
  */
 export function findPhotonClass(module: Record<string, unknown>): (new (...args: unknown[]) => unknown) | null {
-  // Try default export first
+  // Default export = the user's photon class. Trust it.
   if (module.default && isClass(module.default)) {
-    if (hasAsyncMethods(module.default)) {
-      return module.default;
-    }
+    return module.default;
   }
 
-  // Try named exports
+  // Named exports: prefer classes with async methods (likely the photon),
+  // but fall back to any class with public methods if none are async
+  let fallback: (new (...args: unknown[]) => unknown) | null = null;
+
   for (const exportedItem of Object.values(module)) {
-    if (isClass(exportedItem) && hasAsyncMethods(exportedItem)) {
-      return exportedItem;
+    if (isClass(exportedItem)) {
+      if (hasAsyncMethods(exportedItem)) {
+        return exportedItem;
+      }
+      if (!fallback && hasMethods(exportedItem)) {
+        fallback = exportedItem;
+      }
     }
   }
 
-  return null;
+  return fallback;
 }
 
 /**
  * Find all Photon classes in a module
  *
- * Returns every exported class that has async methods.
+ * Returns every exported class that has methods.
  * Used by NCP which may load multiple classes from one file.
  */
 export function findPhotonClasses(module: Record<string, unknown>): Array<new (...args: unknown[]) => unknown> {
   const classes: Array<new (...args: unknown[]) => unknown> = [];
 
   for (const exportedItem of Object.values(module)) {
-    if (isClass(exportedItem) && hasAsyncMethods(exportedItem)) {
+    if (isClass(exportedItem) && hasMethods(exportedItem)) {
       classes.push(exportedItem);
     }
   }

package/src/index.ts

@@ -365,6 +365,7 @@ export {
 // Shared Photon class detection for loaders
 export {
   isClass,
+  hasMethods,
   hasAsyncMethods,
   findPhotonClass,
   findPhotonClasses,
@@ -434,6 +435,24 @@ export {
   assertArray,
 } from './validation.js';
 
+// ===== EXECUTION AUDIT TRAIL =====
+// Zero-effort execution recording for debugging and observability
+export {
+  AuditTrail,
+  getAuditTrail,
+  setAuditTrail,
+  generateExecutionId,
+  type ExecutionRecord,
+  type AuditQueryOptions,
+} from './audit.js';
+
+// ===== SCOPED MEMORY =====
+// Framework-level key-value storage (this.memory on PhotonMCP)
+export {
+  MemoryProvider,
+  type MemoryScope,
+} from './memory.js';
+
 // ===== ASSET DISCOVERY =====
 // Discover UI, prompt, and resource assets from Photon files
 export {

package/src/memory.ts

@@ -0,0 +1,241 @@
+/**
+ * Scoped Memory System
+ *
+ * Framework-level key-value storage for photons that eliminates
+ * boilerplate file I/O. Available as `this.memory` on PhotonMCP.
+ *
+ * Three scopes:
+ * | Scope    | Meaning                          | Storage                           |
+ * |----------|----------------------------------|-----------------------------------|
+ * | photon   | Private to this photon (default)  | ~/.photon/data/{photonId}/        |
+ * | session  | Per-user session (Beam sessions)  | ~/.photon/sessions/{sessionId}/   |
+ * | global   | Shared across all photons         | ~/.photon/data/_global/           |
+ *
+ * @example
+ * ```typescript
+ * export default class TodoList extends PhotonMCP {
+ *   async add({ text }: { text: string }) {
+ *     const items = await this.memory.get<Task[]>('items') ?? [];
+ *     items.push({ id: crypto.randomUUID(), text });
+ *     await this.memory.set('items', items);
+ *     return items;
+ *   }
+ * }
+ * ```
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+export type MemoryScope = 'photon' | 'session' | 'global';
+
+/**
+ * Get the base data directory
+ */
+function getDataDir(): string {
+  return process.env.PHOTON_DATA_DIR || path.join(os.homedir(), '.photon', 'data');
+}
+
+/**
+ * Get the sessions directory
+ */
+function getSessionsDir(): string {
+  return process.env.PHOTON_SESSIONS_DIR || path.join(os.homedir(), '.photon', 'sessions');
+}
+
+/**
+ * Resolve storage directory for a given scope
+ */
+function resolveDir(photonId: string, scope: MemoryScope, sessionId?: string): string {
+  const safeName = photonId.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+  switch (scope) {
+    case 'photon':
+      return path.join(getDataDir(), safeName);
+    case 'session':
+      if (!sessionId) {
+        throw new Error('Session ID required for session-scoped memory. Set via memory.sessionId.');
+      }
+      const safeSession = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_');
+      return path.join(getSessionsDir(), safeSession, safeName);
+    case 'global':
+      return path.join(getDataDir(), '_global');
+    default:
+      throw new Error(`Unknown memory scope: ${scope}`);
+  }
+}
+
+/**
+ * Get the file path for a key within a directory
+ */
+function keyPath(dir: string, key: string): string {
+  const safeKey = key.replace(/[^a-zA-Z0-9_.-]/g, '_');
+  return path.join(dir, `${safeKey}.json`);
+}
+
+/**
+ * Scoped Memory Provider
+ *
+ * Provides key-value storage with automatic JSON serialization.
+ * Each key is stored as a separate file for atomic operations.
+ */
+export class MemoryProvider {
+  private _photonId: string;
+  private _sessionId?: string;
+
+  constructor(photonId: string, sessionId?: string) {
+    this._photonId = photonId;
+    this._sessionId = sessionId;
+  }
+
+  /**
+   * Current session ID (can be updated by the runtime)
+   */
+  get sessionId(): string | undefined {
+    return this._sessionId;
+  }
+
+  set sessionId(id: string | undefined) {
+    this._sessionId = id;
+  }
+
+  /**
+   * Get a value from memory
+   *
+   * @param key The key to retrieve
+   * @param scope Storage scope (default: 'photon')
+   * @returns The stored value, or null if not found
+   */
+  async get<T = any>(key: string, scope: MemoryScope = 'photon'): Promise<T | null> {
+    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const filePath = keyPath(dir, key);
+
+    try {
+      if (!fs.existsSync(filePath)) return null;
+      const content = fs.readFileSync(filePath, 'utf-8');
+      return JSON.parse(content) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Set a value in memory
+   *
+   * @param key The key to store
+   * @param value The value (must be JSON-serializable)
+   * @param scope Storage scope (default: 'photon')
+   */
+  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 });
+    }
+
+    const filePath = keyPath(dir, key);
+    fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
+  }
+
+  /**
+   * Delete a key from memory
+   *
+   * @param key The key to delete
+   * @param scope Storage scope (default: 'photon')
+   * @returns true if the key existed and was deleted
+   */
+  async delete(key: string, scope: MemoryScope = 'photon'): Promise<boolean> {
+    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    const filePath = keyPath(dir, key);
+
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Check if a key exists in memory
+   *
+   * @param key The key to check
+   * @param scope Storage scope (default: 'photon')
+   */
+  async has(key: string, scope: MemoryScope = 'photon'): Promise<boolean> {
+    const dir = resolveDir(this._photonId, scope, this._sessionId);
+    return fs.existsSync(keyPath(dir, key));
+  }
+
+  /**
+   * List all keys in memory for a scope
+   *
+   * @param scope Storage scope (default: 'photon')
+   */
+  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)
+        .filter(f => f.endsWith('.json'))
+        .map(f => f.slice(0, -5)); // Remove .json extension
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Clear all keys in a scope
+   *
+   * @param scope Storage scope (default: 'photon')
+   */
+  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));
+      }
+    }
+  }
+
+  /**
+   * Get all key-value pairs in a scope
+   *
+   * @param scope Storage scope (default: 'photon')
+   */
+  async getAll<T = any>(scope: MemoryScope = 'photon'): Promise<Record<string, T>> {
+    const allKeys = await this.keys(scope);
+    const result: Record<string, T> = {};
+
+    for (const key of allKeys) {
+      const value = await this.get<T>(key, scope);
+      if (value !== null) {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Update a value atomically (read-modify-write)
+   *
+   * @param key The key to update
+   * @param updater Function that receives current value and returns new value
+   * @param scope Storage scope (default: 'photon')
+   */
+  async update<T = any>(
+    key: string,
+    updater: (current: T | null) => T,
+    scope: MemoryScope = 'photon'
+  ): Promise<T> {
+    const current = await this.get<T>(key, scope);
+    const updated = updater(current);
+    await this.set(key, updated, scope);
+    return updated;
+  }
+}

package/src/schema-extractor.ts

@@ -109,14 +109,11 @@ export class SchemaExtractor {
         // Check if this is an async generator method (has asterisk token)
         const isGenerator = member.asteriskToken !== undefined;
 
-        // Extract parameter type information
-        // Extract parameter type (may be undefined for no-arg methods)
-        const paramsType = this.getFirstParameterType(member, sourceFile);
-
-        // Build schema from TypeScript type (empty for no-arg methods)
-        const { properties, required } = paramsType
-          ? this.buildSchemaFromType(paramsType, sourceFile)
-          : { properties: {}, required: [] };
+        // Extract parameter schema from method signature
+        // Supports both patterns:
+        //   add(item: string)              → { item: { type: "string" } }
+        //   add(params: { item: string })  → { item: { type: "string" } }
+        const { properties, required, simpleParams } = this.extractMethodParams(member, sourceFile);
 
         // Extract descriptions from JSDoc
         const paramDocs = this.extractParamDocs(jsdoc);
@@ -178,6 +175,7 @@ export class SchemaExtractor {
           const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
           const isStateful = this.hasStatefulTag(jsdoc);
           const autorun = this.hasAutorunTag(jsdoc);
+          const isAsync = this.hasAsyncTag(jsdoc);
 
           // Daemon features
           const webhook = this.extractWebhook(jsdoc, methodName);
@@ -199,7 +197,9 @@ export class SchemaExtractor {
             ...(yields && yields.length > 0 ? { yields } : {}),
             ...(isStateful ? { isStateful: true } : {}),
             ...(autorun ? { autorun: true } : {}),
+            ...(isAsync ? { isAsync: true } : {}),
             ...(isStaticMethod ? { isStatic: true } : {}),
+            ...(simpleParams ? { simpleParams: true } : {}),
             // Daemon features
             ...(webhook !== undefined ? { webhook } : {}),
             ...(scheduled ? { scheduled } : {}),
@@ -213,10 +213,15 @@ export class SchemaExtractor {
         // Look for class declarations
         if (ts.isClassDeclaration(node)) {
           node.members.forEach((member) => {
-            // Look for async methods (including async generators with *)
-            if (ts.isMethodDeclaration(member) &&
-                member.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)) {
-              processMethod(member);
+            // Process all public methods (sync or async)
+            // Skip private/protected — only public methods become tools
+            if (ts.isMethodDeclaration(member)) {
+              const isPrivate = member.modifiers?.some(
+                m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword
+              );
+              if (!isPrivate) {
+                processMethod(member);
+              }
             }
           });
         }
@@ -280,6 +285,61 @@ export class SchemaExtractor {
     return firstParam.type;
   }
 
+  /**
+   * Extract method parameters into JSON schema properties.
+   *
+   * Handles two patterns:
+   *   1. Object param: add(params: { item: string }) → extracts inner properties
+   *   2. Simple params: add(item: string) or add(a: number, b: number) → each param becomes a property
+   */
+  private extractMethodParams(method: ts.MethodDeclaration, sourceFile: ts.SourceFile): { properties: Record<string, any>, required: string[], simpleParams?: boolean } {
+    if (method.parameters.length === 0) {
+      return { properties: {}, required: [] };
+    }
+
+    const firstParam = method.parameters[0];
+    const firstType = firstParam.type;
+
+    // Pattern 1: Single object param — add(params: { item: string })
+    // Unwrap the object type's properties directly
+    if (firstType && method.parameters.length === 1) {
+      // Direct type literal: { item: string }
+      if (ts.isTypeLiteralNode(firstType)) {
+        return this.buildSchemaFromType(firstType, sourceFile);
+      }
+      // Union containing object literal: { item: string } | string
+      if (ts.isUnionTypeNode(firstType)) {
+        for (const memberType of firstType.types) {
+          if (ts.isTypeLiteralNode(memberType)) {
+            return this.buildSchemaFromType(memberType, sourceFile);
+          }
+        }
+      }
+    }
+
+    // Pattern 2: Simple typed params — add(item: string) or add(a: number, b: number)
+    // Flag as simpleParams so the runtime destructures the params object into individual args
+    const properties: Record<string, any> = {};
+    const required: string[] = [];
+
+    for (const param of method.parameters) {
+      const paramName = param.name.getText(sourceFile);
+      const isOptional = param.questionToken !== undefined || param.initializer !== undefined;
+
+      if (!isOptional) {
+        required.push(paramName);
+      }
+
+      if (param.type) {
+        properties[paramName] = this.typeNodeToSchema(param.type, sourceFile);
+      } else {
+        properties[paramName] = { type: 'string' };
+      }
+    }
+
+    return { properties, required, simpleParams: true };
+  }
+
   /**
    * Build JSON schema from TypeScript type node
    * Extracts: type, optional, readonly
@@ -657,7 +717,7 @@ export class SchemaExtractor {
    */
   private extractDescription(jsdocContent: string): string {
     // Split by @param to get only the description part (also stop at other @tags)
-    const beforeTags = jsdocContent.split(/@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|webhook|cron|scheduled|locked|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
+    const beforeTags = jsdocContent.split(/@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility)\b/)[0];
 
     // Remove leading * from each line and trim
     const lines = beforeTags
@@ -1076,6 +1136,14 @@ export class SchemaExtractor {
     return /@autorun/i.test(jsdocContent);
   }
 
+  /**
+   * Check if JSDoc contains @async tag
+   * Indicates this method runs in background — returns execution ID immediately
+   */
+  private hasAsyncTag(jsdocContent: string): boolean {
+    return /@async\b/i.test(jsdocContent);
+  }
+
   // ═══════════════════════════════════════════════════════════════════════════════
   // DAEMON FEATURE EXTRACTION
   // ═══════════════════════════════════════════════════════════════════════════════
@@ -1473,6 +1541,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);
 
     // Build lookup maps
     const mcpMap = new Map(mcpDeps.map(d => [d.name, d]));
@@ -1507,6 +1576,15 @@ export class SchemaExtractor {
         };
       }
 
+      // Non-primitive with default on @stateful class → persisted state
+      if (isStateful && param.hasDefault) {
+        return {
+          param,
+          injectionType: 'state' as const,
+          stateKey: param.name,
+        };
+      }
+
       // Non-primitive without declaration - treat as env var (will likely fail at runtime)
       const envVarName = this.toEnvVarName(mcpName, param.name);
       return {

package/src/types.ts

@@ -63,6 +63,8 @@ export interface ExtractedSchema {
   isStateful?: boolean;
   /** True if this method should auto-execute when selected (idempotent, no required params) */
   autorun?: boolean;
+  /** True if this method runs in background — returns execution ID immediately */
+  isAsync?: boolean;
   /** True if this is a static method (class-level, no instance needed) */
   isStatic?: boolean;
 
@@ -110,7 +112,7 @@ export interface ConstructorParam {
 /**
  * Injection type for constructor parameters
  */
-export type InjectionType = 'env' | 'mcp' | 'photon';
+export type InjectionType = 'env' | 'mcp' | 'photon' | 'state';
 
 /**
  * Resolved injection info for a constructor parameter
@@ -124,6 +126,8 @@ export interface ResolvedInjection {
   photonDependency?: PhotonDependency;
   /** For 'env' - the environment variable name */
   envVarName?: string;
+  /** For 'state' - the key name in the persisted snapshot JSON */
+  stateKey?: string;
 }
 
 /**