@portel/photon-core 2.10.1 → 2.12.0

package/src/schedule.ts

@@ -0,0 +1,365 @@
+/**
+ * Runtime Scheduling System
+ *
+ * Programmatic scheduling for photons — create, pause, resume, and cancel
+ * scheduled tasks at runtime. Available as `this.schedule` on Photon.
+ *
+ * Complements static `@scheduled`/`@cron` JSDoc tags with dynamic scheduling.
+ * Schedules persist to disk; the daemon reads and executes them.
+ *
+ * Storage: ~/.photon/schedules/{photonId}/{taskId}.json
+ *
+ * @example
+ * ```typescript
+ * export default class Cleanup extends Photon {
+ *   async setup() {
+ *     await this.schedule.create({
+ *       name: 'nightly-cleanup',
+ *       schedule: '0 0 * * *',
+ *       method: 'purge',
+ *       params: { olderThan: 30 },
+ *     });
+ *   }
+ *
+ *   async purge({ olderThan }: { olderThan: number }) {
+ *     // ... cleanup logic
+ *   }
+ * }
+ * ```
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { randomUUID } from 'crypto';
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'error';
+
+export interface ScheduledTask {
+  /** Unique task ID */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Optional description */
+  description?: string;
+  /** Cron expression (5-field: minute hour day month weekday) */
+  cron: string;
+  /** Method name on this photon to call */
+  method: string;
+  /** Parameters to pass to the method */
+  params: Record<string, any>;
+  /** Execute once then mark completed */
+  fireOnce: boolean;
+  /** Maximum number of executions (0 = unlimited) */
+  maxExecutions: number;
+  /** Current status */
+  status: ScheduleStatus;
+  /** ISO timestamp of creation */
+  createdAt: string;
+  /** ISO timestamp of last execution */
+  lastExecutionAt?: string;
+  /** Total execution count */
+  executionCount: number;
+  /** Error message if status is 'error' */
+  errorMessage?: string;
+  /** Photon that owns this task */
+  photonId: string;
+}
+
+export interface CreateScheduleOptions {
+  /** Human-readable name (must be unique per photon) */
+  name: string;
+  /** Cron expression (5-field) or shorthand: '@hourly', '@daily', '@weekly', '@monthly' */
+  schedule: string;
+  /** Method name on this photon to invoke */
+  method: string;
+  /** Parameters to pass to the method */
+  params?: Record<string, any>;
+  /** Optional description */
+  description?: string;
+  /** Execute once then auto-complete (default: false) */
+  fireOnce?: boolean;
+  /** Maximum executions before auto-complete (0 = unlimited, default: 0) */
+  maxExecutions?: number;
+}
+
+export interface UpdateScheduleOptions {
+  /** New cron schedule */
+  schedule?: string;
+  /** New method name */
+  method?: string;
+  /** New parameters */
+  params?: Record<string, any>;
+  /** New description */
+  description?: string;
+  /** Update fire-once flag */
+  fireOnce?: boolean;
+  /** Update max executions */
+  maxExecutions?: number;
+}
+
+// ── Cron Shorthands ────────────────────────────────────────────────────
+
+const CRON_SHORTHANDS: Record<string, string> = {
+  '@yearly':   '0 0 1 1 *',
+  '@annually': '0 0 1 1 *',
+  '@monthly':  '0 0 1 * *',
+  '@weekly':   '0 0 * * 0',
+  '@daily':    '0 0 * * *',
+  '@midnight': '0 0 * * *',
+  '@hourly':   '0 * * * *',
+};
+
+/**
+ * Resolve cron shorthands and validate basic format.
+ * Returns the resolved 5-field cron expression.
+ */
+function resolveCron(schedule: string): string {
+  const trimmed = schedule.trim();
+
+  // Check shorthands
+  const shorthand = CRON_SHORTHANDS[trimmed.toLowerCase()];
+  if (shorthand) return shorthand;
+
+  // Validate 5-field cron format
+  const fields = trimmed.split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(
+      `Invalid cron expression: '${schedule}'. Expected 5 fields (minute hour day month weekday) or a shorthand (@hourly, @daily, @weekly, @monthly, @yearly).`
+    );
+  }
+
+  return trimmed;
+}
+
+// ── Storage Helpers ────────────────────────────────────────────────────
+
+function getSchedulesDir(): string {
+  return process.env.PHOTON_SCHEDULES_DIR || path.join(os.homedir(), '.photon', 'schedules');
+}
+
+function photonScheduleDir(photonId: string): string {
+  const safeName = photonId.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(getSchedulesDir(), safeName);
+}
+
+function taskPath(photonId: string, taskId: string): string {
+  return path.join(photonScheduleDir(photonId), `${taskId}.json`);
+}
+
+async function ensureDir(dir: string): Promise<void> {
+  try {
+    await fs.mkdir(dir, { recursive: true });
+  } catch (err: any) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+}
+
+// ── Schedule Provider ──────────────────────────────────────────────────
+
+/**
+ * Runtime Schedule Provider
+ *
+ * Provides CRUD operations for scheduled tasks.
+ * Tasks are persisted as JSON files that the daemon watches and executes.
+ */
+export class ScheduleProvider {
+  private _photonId: string;
+
+  constructor(photonId: string) {
+    this._photonId = photonId;
+  }
+
+  /**
+   * Create a new scheduled task
+   *
+   * @example
+   * ```typescript
+   * await this.schedule.create({
+   *   name: 'daily-report',
+   *   schedule: '0 9 * * *',
+   *   method: 'generate',
+   *   params: { format: 'pdf' },
+   * });
+   * ```
+   */
+  async create(options: CreateScheduleOptions): Promise<ScheduledTask> {
+    const cron = resolveCron(options.schedule);
+
+    // Check for duplicate name
+    const existing = await this.getByName(options.name);
+    if (existing) {
+      throw new Error(`Schedule '${options.name}' already exists (id: ${existing.id}). Use update() to modify it.`);
+    }
+
+    const task: ScheduledTask = {
+      id: randomUUID(),
+      name: options.name,
+      description: options.description,
+      cron,
+      method: options.method,
+      params: options.params || {},
+      fireOnce: options.fireOnce ?? false,
+      maxExecutions: options.maxExecutions ?? 0,
+      status: 'active',
+      createdAt: new Date().toISOString(),
+      executionCount: 0,
+      photonId: this._photonId,
+    };
+
+    await this._save(task);
+    return task;
+  }
+
+  /**
+   * Get a scheduled task by ID
+   */
+  async get(taskId: string): Promise<ScheduledTask | null> {
+    try {
+      const content = await fs.readFile(taskPath(this._photonId, taskId), 'utf-8');
+      return JSON.parse(content) as ScheduledTask;
+    } catch (err: any) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+  }
+
+  /**
+   * Get a scheduled task by name
+   */
+  async getByName(name: string): Promise<ScheduledTask | null> {
+    const tasks = await this.list();
+    return tasks.find(t => t.name === name) || null;
+  }
+
+  /**
+   * List all scheduled tasks, optionally filtered by status
+   */
+  async list(status?: ScheduleStatus): Promise<ScheduledTask[]> {
+    const dir = photonScheduleDir(this._photonId);
+    let files: string[];
+    try {
+      files = await fs.readdir(dir);
+    } catch (err: any) {
+      if (err.code === 'ENOENT') return [];
+      throw err;
+    }
+
+    const tasks: ScheduledTask[] = [];
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      try {
+        const content = await fs.readFile(path.join(dir, file), 'utf-8');
+        const task = JSON.parse(content) as ScheduledTask;
+        if (!status || task.status === status) {
+          tasks.push(task);
+        }
+      } catch {
+        // Skip corrupt files
+      }
+    }
+
+    return tasks.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+
+  /**
+   * Update an existing scheduled task
+   */
+  async update(taskId: string, updates: UpdateScheduleOptions): Promise<ScheduledTask> {
+    const task = await this.get(taskId);
+    if (!task) {
+      throw new Error(`Schedule not found: ${taskId}`);
+    }
+
+    if (updates.schedule !== undefined) {
+      task.cron = resolveCron(updates.schedule);
+    }
+    if (updates.method !== undefined) task.method = updates.method;
+    if (updates.params !== undefined) task.params = updates.params;
+    if (updates.description !== undefined) task.description = updates.description;
+    if (updates.fireOnce !== undefined) task.fireOnce = updates.fireOnce;
+    if (updates.maxExecutions !== undefined) task.maxExecutions = updates.maxExecutions;
+
+    await this._save(task);
+    return task;
+  }
+
+  /**
+   * Pause a scheduled task (stops execution until resumed)
+   */
+  async pause(taskId: string): Promise<ScheduledTask> {
+    const task = await this.get(taskId);
+    if (!task) throw new Error(`Schedule not found: ${taskId}`);
+    if (task.status !== 'active') {
+      throw new Error(`Cannot pause task with status '${task.status}'. Only active tasks can be paused.`);
+    }
+    task.status = 'paused';
+    await this._save(task);
+    return task;
+  }
+
+  /**
+   * Resume a paused scheduled task
+   */
+  async resume(taskId: string): Promise<ScheduledTask> {
+    const task = await this.get(taskId);
+    if (!task) throw new Error(`Schedule not found: ${taskId}`);
+    if (task.status !== 'paused') {
+      throw new Error(`Cannot resume task with status '${task.status}'. Only paused tasks can be resumed.`);
+    }
+    task.status = 'active';
+    await this._save(task);
+    return task;
+  }
+
+  /**
+   * Cancel (delete) a scheduled task
+   */
+  async cancel(taskId: string): Promise<boolean> {
+    try {
+      await fs.unlink(taskPath(this._photonId, taskId));
+      return true;
+    } catch (err: any) {
+      if (err.code === 'ENOENT') return false;
+      throw err;
+    }
+  }
+
+  /**
+   * Cancel a scheduled task by name
+   */
+  async cancelByName(name: string): Promise<boolean> {
+    const task = await this.getByName(name);
+    if (!task) return false;
+    return this.cancel(task.id);
+  }
+
+  /**
+   * Check if a schedule with the given name exists
+   */
+  async has(name: string): Promise<boolean> {
+    const task = await this.getByName(name);
+    return task !== null;
+  }
+
+  /**
+   * Cancel all scheduled tasks for this photon
+   */
+  async cancelAll(): Promise<number> {
+    const tasks = await this.list();
+    let count = 0;
+    for (const task of tasks) {
+      if (await this.cancel(task.id)) count++;
+    }
+    return count;
+  }
+
+  /** @internal */
+  private async _save(task: ScheduledTask): Promise<void> {
+    const dir = photonScheduleDir(this._photonId);
+    await ensureDir(dir);
+    await fs.writeFile(taskPath(this._photonId, task.id), JSON.stringify(task, null, 2));
+  }
+}

package/src/schema-extractor.ts

@@ -243,11 +243,22 @@ export class SchemaExtractor {
           const layoutHints = this.extractLayoutHints(jsdoc);
           const buttonLabel = this.extractButtonLabel(jsdoc);
           const icon = this.extractIcon(jsdoc);
+          const iconImages = this.extractIconImages(jsdoc);
           const yields = isGenerator ? this.extractYieldsFromJSDoc(jsdoc) : undefined;
           const isStateful = this.hasStatefulTag(jsdoc);
           const autorun = this.hasAutorunTag(jsdoc);
           const isAsync = this.hasAsyncTag(jsdoc);
 
+          // MCP standard annotations
+          const title = this.extractTitle(jsdoc);
+          const readOnlyHint = this.hasReadOnlyHint(jsdoc);
+          const destructiveHint = this.hasDestructiveHint(jsdoc);
+          const idempotentHint = this.hasIdempotentHint(jsdoc);
+          const openWorldHint = this.extractOpenWorldHint(jsdoc);
+          const audience = this.extractAudience(jsdoc);
+          const contentPriority = this.extractContentPriority(jsdoc);
+          const outputSchema = this.inferOutputSchemaFromReturnType(member, sourceFile);
+
           // Daemon features
           const webhook = this.extractWebhook(jsdoc, methodName);
           const scheduled = this.extractScheduled(jsdoc, methodName);
@@ -294,6 +305,7 @@ export class SchemaExtractor {
             ...(layoutHints ? { layoutHints } : {}),
             ...(buttonLabel ? { buttonLabel } : {}),
             ...(icon ? { icon } : {}),
+            ...(iconImages ? { iconImages } : {}),
             ...(isGenerator ? { isGenerator: true } : {}),
             ...(yields && yields.length > 0 ? { yields } : {}),
             ...(isStateful ? { isStateful: true } : {}),
@@ -319,6 +331,15 @@ export class SchemaExtractor {
             ...(deprecated !== undefined ? { deprecated } : {}),
             // Unified middleware declarations (new — runtime uses this)
             ...(middleware.length > 0 ? { middleware } : {}),
+            // MCP standard annotations
+            ...(title ? { title } : {}),
+            ...(readOnlyHint ? { readOnlyHint: true } : {}),
+            ...(destructiveHint ? { destructiveHint: true } : {}),
+            ...(idempotentHint ? { idempotentHint: true } : {}),
+            ...(openWorldHint !== undefined ? { openWorldHint } : {}),
+            ...(audience ? { audience } : {}),
+            ...(contentPriority !== undefined ? { contentPriority } : {}),
+            ...(outputSchema ? { outputSchema } : {}),
             // Event emission (for @stateful classes)
             ...emitsEventData,
           });
@@ -632,6 +653,12 @@ export class SchemaExtractor {
             properties[propName] = { type: 'object' };
           }
 
+          // Extract JSDoc description from property (e.g., /** Task ID */ id: string)
+          const jsDocComment = this.getPropertyJsDoc(member, sourceFile);
+          if (jsDocComment) {
+            properties[propName].description = jsDocComment;
+          }
+
           // Add readonly from TypeScript (JSDoc can override)
           if (isReadonly) {
             properties[propName]._tsReadOnly = true;
@@ -643,6 +670,32 @@ export class SchemaExtractor {
     return { properties, required };
   }
 
+  /**
+   * Extract JSDoc description from a property signature.
+   * Handles both /** comment * / style and // comment style.
+   */
+  private getPropertyJsDoc(member: ts.PropertySignature, sourceFile: ts.SourceFile): string | undefined {
+    // Check for JSDoc comments attached to the node
+    const jsDocNodes = (member as any).jsDoc;
+    if (jsDocNodes && jsDocNodes.length > 0) {
+      const comment = jsDocNodes[0].comment;
+      if (typeof comment === 'string') return comment.trim();
+    }
+
+    // Fallback: look for leading comment in source text
+    const fullText = sourceFile.getFullText();
+    const start = member.getFullStart();
+    const leading = fullText.substring(start, member.getStart(sourceFile)).trim();
+
+    // Match /** ... */ or /* ... */
+    const blockMatch = leading.match(/\/\*\*?\s*([\s\S]*?)\s*\*\//);
+    if (blockMatch) {
+      return blockMatch[1].replace(/\s*\*\s*/g, ' ').trim();
+    }
+
+    return undefined;
+  }
+
   /**
    * Convert TypeScript type node to JSON schema
    */
@@ -772,6 +825,15 @@ export class SchemaExtractor {
         return;
       }
 
+      // Also resolve interface declarations → synthesize a TypeLiteral
+      if (ts.isInterfaceDeclaration(node) && node.name.text === typeName) {
+        // Create a synthetic TypeLiteralNode from interface members
+        resolved = ts.factory.createTypeLiteralNode(
+          node.members.filter(ts.isPropertySignature) as ts.PropertySignature[]
+        );
+        return;
+      }
+
       ts.forEachChild(node, visit);
     };
 
@@ -1756,6 +1818,122 @@ export class SchemaExtractor {
     return /@async\b/i.test(jsdocContent);
   }
 
+  /**
+   * Extract @title tag value (human-readable display name)
+   * Example: @title Create New Task
+   */
+  private extractTitle(jsdocContent: string): string | undefined {
+    const match = jsdocContent.match(/@title\s+(.+?)(?:\n|\s*\*\/|\s*\*\s*@)/s);
+    if (match) {
+      return match[1].replace(/\s*\*\s*/g, ' ').trim();
+    }
+    return undefined;
+  }
+
+  /**
+   * Check if JSDoc contains method-level @readOnly tag (NOT param-level {@readOnly})
+   * Method-level: indicates tool has no side effects (MCP readOnlyHint)
+   * Param-level: {@readOnly} inside @param — different regex, no conflict
+   */
+  private hasReadOnlyHint(jsdocContent: string): boolean {
+    // Match @readOnly that is NOT inside curly braces (param-level uses {@readOnly})
+    // Look for @readOnly at start of line (after * ) or start of JSDoc
+    return /(?:^|\n)\s*\*?\s*@readOnly\b/m.test(jsdocContent);
+  }
+
+  /**
+   * Check if JSDoc contains @destructive tag
+   * Indicates tool performs destructive operations requiring confirmation
+   */
+  private hasDestructiveHint(jsdocContent: string): boolean {
+    return /@destructive\b/i.test(jsdocContent);
+  }
+
+  /**
+   * Check if JSDoc contains @idempotent tag
+   * Indicates tool is safe to retry — multiple calls produce same effect
+   */
+  private hasIdempotentHint(jsdocContent: string): boolean {
+    return /@idempotent\b/i.test(jsdocContent);
+  }
+
+  /**
+   * Extract open/closed world hint from @openWorld or @closedWorld tags
+   * @openWorld → true (tool interacts with external systems)
+   * @closedWorld → false (tool operates only on local data)
+   * Returns undefined if neither tag present
+   */
+  private extractOpenWorldHint(jsdocContent: string): boolean | undefined {
+    if (/@openWorld\b/i.test(jsdocContent)) return true;
+    if (/@closedWorld\b/i.test(jsdocContent)) return false;
+    return undefined;
+  }
+
+  /**
+   * Extract @audience tag value
+   * @audience user → ['user']
+   * @audience assistant → ['assistant']
+   * @audience user assistant → ['user', 'assistant']
+   */
+  private extractAudience(jsdocContent: string): ('user' | 'assistant')[] | undefined {
+    const match = jsdocContent.match(/@audience\s+([\w\s]+?)(?:\n|\s*\*\/|\s*\*\s*@)/);
+    if (match) {
+      const values = match[1].trim().split(/\s+/) as ('user' | 'assistant')[];
+      const valid = values.filter(v => v === 'user' || v === 'assistant');
+      return valid.length > 0 ? valid : undefined;
+    }
+    return undefined;
+  }
+
+  /**
+   * Extract @priority tag value (content importance 0.0-1.0)
+   */
+  private extractContentPriority(jsdocContent: string): number | undefined {
+    const match = jsdocContent.match(/@priority\s+([\d.]+)/);
+    if (match) {
+      const value = parseFloat(match[1]);
+      if (!isNaN(value) && value >= 0 && value <= 1) {
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Infer output schema from TypeScript return type annotation.
+   * Unwraps Promise<T> and converts T to JSON Schema.
+   * Property descriptions come from JSDoc on the type/interface properties.
+   * Only produces a schema for object return types (not primitives/arrays).
+   */
+  private inferOutputSchemaFromReturnType(method: ts.MethodDeclaration, sourceFile: ts.SourceFile): { type: 'object'; properties: Record<string, any>; required?: string[] } | undefined {
+    const returnType = method.type;
+    if (!returnType) return undefined;
+
+    // Unwrap Promise<T> → T
+    let innerType: ts.TypeNode = returnType;
+    if (ts.isTypeReferenceNode(returnType)) {
+      const typeName = returnType.typeName.getText(sourceFile);
+      if (typeName === 'Promise' && returnType.typeArguments?.length) {
+        innerType = returnType.typeArguments[0];
+      }
+    }
+
+    // Convert to JSON Schema
+    const schema = this.typeNodeToSchema(innerType, sourceFile);
+
+    // Only produce outputSchema for object types with properties
+    if (schema.type === 'object' && schema.properties && Object.keys(schema.properties).length > 0) {
+      const result: { type: 'object'; properties: Record<string, any>; required?: string[] } = {
+        type: 'object',
+        properties: schema.properties,
+      };
+      if (schema.required?.length) result.required = schema.required;
+      return result;
+    }
+
+    return undefined;
+  }
+
   /**
    * Extract notification subscriptions from @notify-on tag
    * Specifies which event types this photon is interested in
@@ -2111,7 +2289,7 @@ export class SchemaExtractor {
     }
 
     // Match visualization formats
-    if (['metric', 'gauge', 'timeline', 'dashboard', 'cart'].includes(format)) {
+    if (['metric', 'gauge', 'timeline', 'dashboard', 'cart', 'qr'].includes(format)) {
       return format as OutputFormat;
     }
 
@@ -2177,11 +2355,50 @@ export class SchemaExtractor {
     const withoutLayoutHints = jsdocContent.replace(/\{[^}]+\}/g, '');
     const iconMatch = withoutLayoutHints.match(/@icon\s+([^\s@*,]+)/i);
     if (iconMatch) {
-      return iconMatch[1].trim();
+      const value = iconMatch[1].trim();
+      // If it looks like a file path, don't return as emoji icon
+      if (value.startsWith('./') || value.startsWith('../') || /\.(png|jpg|jpeg|gif|svg|webp|ico)$/i.test(value)) {
+        return undefined;
+      }
+      return value;
     }
     return undefined;
   }
 
+  /**
+   * Extract icon image entries from @icon (file path) and @icons tags
+   * @icon ./icons/calc.png          → [{ path: './icons/calc.png' }]
+   * @icon ./icons/calc.svg          → [{ path: './icons/calc.svg' }]
+   * @icons ./icons/calc-48.png 48x48       → [{ path: '...', sizes: '48x48' }]
+   * @icons ./icons/calc-dark.svg dark      → [{ path: '...', theme: 'dark' }]
+   * @icons ./icons/calc-96.png 96x96 dark  → [{ path: '...', sizes: '96x96', theme: 'dark' }]
+   */
+  private extractIconImages(jsdocContent: string): Array<{ path: string; sizes?: string; theme?: string }> | undefined {
+    const images: Array<{ path: string; sizes?: string; theme?: string }> = [];
+
+    // Check if @icon value is a file path
+    const withoutLayoutHints = jsdocContent.replace(/\{[^}]+\}/g, '');
+    const iconMatch = withoutLayoutHints.match(/@icon\s+([^\s@*,]+)/i);
+    if (iconMatch) {
+      const value = iconMatch[1].trim();
+      if (value.startsWith('./') || value.startsWith('../') || /\.(png|jpg|jpeg|gif|svg|webp|ico)$/i.test(value)) {
+        images.push({ path: value });
+      }
+    }
+
+    // Extract @icons entries (can have multiple)
+    const iconsRegex = /@icons\s+([^\s@*,]+)(?:\s+(\d+x\d+))?(?:\s+(light|dark))?/gi;
+    let match: RegExpExecArray | null;
+    while ((match = iconsRegex.exec(jsdocContent)) !== null) {
+      const entry: { path: string; sizes?: string; theme?: string } = { path: match[1].trim() };
+      if (match[2]) entry.sizes = match[2];
+      if (match[3]) entry.theme = match[3] as 'light' | 'dark';
+      images.push(entry);
+    }
+
+    return images.length > 0 ? images : undefined;
+  }
+
   /**
    * Extract MIME type from @mimeType tag
    * Example: @mimeType text/markdown