@portel/photon-core 2.11.0 → 2.13.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

@@ -257,7 +257,7 @@ export class SchemaExtractor {
           const openWorldHint = this.extractOpenWorldHint(jsdoc);
           const audience = this.extractAudience(jsdoc);
           const contentPriority = this.extractContentPriority(jsdoc);
-          const outputSchema = this.extractOutputSchema(jsdoc);
+          const outputSchema = this.inferOutputSchemaFromReturnType(member, sourceFile);
 
           // Daemon features
           const webhook = this.extractWebhook(jsdoc, methodName);
@@ -653,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;
@@ -664,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
    */
@@ -793,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);
     };
 
@@ -1859,31 +1900,38 @@ export class SchemaExtractor {
   }
 
   /**
-   * Extract structured output schema from @returns.field {type} tags
-   * @returns.id {string} Task ID
-   * @returns.title {string} Task title
-   * @returns.done {boolean} Completion status
-   * → { type: 'object', properties: { id: { type: 'string', description: 'Task ID' }, ... } }
+   * 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 extractOutputSchema(jsdocContent: string): { type: 'object'; properties: Record<string, any>; required?: string[] } | undefined {
-    const fieldRegex = /@returns\.(\w+)\s+\{(\w+)\}\s*([^\n*]*)/g;
-    const properties: Record<string, any> = {};
-    let match: RegExpExecArray | null;
-    while ((match = fieldRegex.exec(jsdocContent)) !== null) {
-      const [, field, type, desc] = match;
-      const jsonType = type.toLowerCase() === 'boolean' ? 'boolean'
-        : type.toLowerCase() === 'number' || type.toLowerCase() === 'integer' ? 'number'
-        : type.toLowerCase() === 'array' ? 'array'
-        : type.toLowerCase() === 'object' ? 'object'
-        : 'string';
-      properties[field] = { type: jsonType };
-      const trimmedDesc = desc.replace(/\s*\*\s*/g, ' ').trim();
-      if (trimmedDesc) {
-        properties[field].description = trimmedDesc;
-      }
-    }
-    if (Object.keys(properties).length === 0) return undefined;
-    return { type: 'object', properties };
+  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;
   }
 
   /**

package/src/types.ts

@@ -12,7 +12,7 @@
 export type OutputFormat =
   | 'primitive' | 'table' | 'tree' | 'list' | 'none'
   | 'json' | 'markdown' | 'yaml' | 'xml' | 'html' | 'mermaid'
-  | 'card' | 'grid' | 'chips' | 'kv'
+  | 'card' | 'grid' | 'chips' | 'kv' | 'qr'
   | 'chart' | `chart:${string}` | 'metric' | 'gauge' | 'timeline' | 'dashboard' | 'cart'
   | 'panels' | 'tabs' | 'accordion' | 'stack' | 'columns'
   | `code` | `code:${string}`;
@@ -28,6 +28,12 @@ export interface PhotonTool {
   outputFormat?: OutputFormat;
   /** When true, method uses individual params instead of a single params object */
   simpleParams?: boolean;
+  /**
+   * Icon image entries from @icon (file path) or @icons tags.
+   * Raw paths — resolved to data URIs by the runtime.
+   * Maps to MCP Tool.icons[]
+   */
+  iconImages?: Array<{ path: string; sizes?: string; theme?: string }>;
 }
 
 /**