@portel/photon-core 1.3.0 → 1.4.0

package/dist/types.d.ts

@@ -48,6 +48,8 @@ export interface ExtractedSchema {
     isGenerator?: boolean;
     /** Yield information for generator methods (used by REST APIs) */
     yields?: YieldInfo[];
+    /** True if this is a stateful workflow (supports checkpoint/resume) */
+    isStateful?: boolean;
 }
 export interface PhotonMCPClass {
     name: string;
@@ -61,6 +63,25 @@ export interface ConstructorParam {
     isOptional: boolean;
     hasDefault: boolean;
     defaultValue?: any;
+    /** True if type is string, number, or boolean (inject from env var) */
+    isPrimitive: boolean;
+}
+/**
+ * Injection type for constructor parameters
+ */
+export type InjectionType = 'env' | 'mcp' | 'photon';
+/**
+ * Resolved injection info for a constructor parameter
+ */
+export interface ResolvedInjection {
+    param: ConstructorParam;
+    injectionType: InjectionType;
+    /** For 'mcp' - the MCP dependency info */
+    mcpDependency?: MCPDependency;
+    /** For 'photon' - the Photon dependency info */
+    photonDependency?: PhotonDependency;
+    /** For 'env' - the environment variable name */
+    envVarName?: string;
 }
 /**
  * MCP Dependency declaration from @mcp tag
@@ -95,6 +116,118 @@ export interface MCPDependency {
     /** Environment variables to pass (from @env tags) */
     env?: Record<string, string>;
 }
+/**
+ * Photon Dependency declaration from @photon tag
+ * Format: @photon <name> <source>
+ *
+ * Source formats (following marketplace conventions):
+ * - Marketplace: rss-feed (from configured marketplace)
+ * - GitHub shorthand: portel-dev/photons/rss-feed
+ * - npm package: npm:@portel/rss-feed-photon
+ * - Local path: ./my-local-photon.photon.ts
+ *
+ * Example:
+ * ```typescript
+ * /**
+ *  * @photon rssFeed rss-feed
+ *  * @photon custom ./my-photon.photon.ts
+ *  *\/
+ * export default class MyWorkflow {
+ *   constructor(private rssFeed: any) {}
+ *
+ *   async run() {
+ *     const items = await this.rssFeed.read({ url: '...' });
+ *   }
+ * }
+ * ```
+ */
+export interface PhotonDependency {
+    /** Local name to use for accessing this Photon (e.g., 'rssFeed') */
+    name: string;
+    /** Source identifier (marketplace name, GitHub shorthand, npm package, or path) */
+    source: string;
+    /** Resolved source type */
+    sourceType: 'marketplace' | 'github' | 'npm' | 'local';
+}
+/**
+ * UI Asset - HTML/React UI for MCP Apps
+ *
+ * Declared via @ui annotation:
+ * ```
+ * /** @ui preferences-form ./ui/preferences.html *\/
+ * ```
+ *
+ * Referenced in tools via @ui JSDoc or EmitUI yield
+ */
+export interface UIAsset {
+    /** Asset identifier (e.g., 'preferences-form') */
+    id: string;
+    /** Relative path from asset folder (e.g., './ui/preferences.html') */
+    path: string;
+    /** Resolved absolute path (set by loader) */
+    resolvedPath?: string;
+    /** MIME type (detected from extension) */
+    mimeType?: string;
+    /** Tool this UI is linked to (from method @ui annotation) */
+    linkedTool?: string;
+}
+/**
+ * Prompt Asset - Static MCP Prompt template
+ *
+ * Declared via @prompt annotation:
+ * ```
+ * /** @prompt system ./prompts/system.md *\/
+ * ```
+ */
+export interface PromptAsset {
+    /** Asset identifier (e.g., 'system') */
+    id: string;
+    /** Relative path from asset folder */
+    path: string;
+    /** Resolved absolute path (set by loader) */
+    resolvedPath?: string;
+    /** Prompt description (from file frontmatter or annotation) */
+    description?: string;
+    /** Prompt arguments schema (from file frontmatter) */
+    arguments?: Record<string, {
+        type: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+/**
+ * Resource Asset - Static MCP Resource
+ *
+ * Declared via @resource annotation:
+ * ```
+ * /** @resource config ./resources/config.json *\/
+ * ```
+ */
+export interface ResourceAsset {
+    /** Asset identifier (e.g., 'config') */
+    id: string;
+    /** Relative path from asset folder */
+    path: string;
+    /** Resolved absolute path (set by loader) */
+    resolvedPath?: string;
+    /** MIME type (detected from extension) */
+    mimeType?: string;
+    /** Resource description */
+    description?: string;
+}
+/**
+ * All assets extracted from a Photon
+ */
+export interface PhotonAssets {
+    /** UI assets for MCP Apps */
+    ui: UIAsset[];
+    /** Static prompt templates */
+    prompts: PromptAsset[];
+    /** Static resources */
+    resources: ResourceAsset[];
+    /** Asset folder path (e.g., './my-photon/') */
+    assetFolder?: string;
+}
 /**
  * Template type - for text generation with variable substitution
  * Maps to MCP Prompts, HTTP template endpoints, CLI help generators, etc.
@@ -167,5 +300,132 @@ export interface StaticInfo {
 export interface PhotonMCPClassExtended extends PhotonMCPClass {
     templates: TemplateInfo[];
     statics: StaticInfo[];
+    /** Assets from the Photon's asset folder (UI, prompts, resources) */
+    assets?: PhotonAssets;
+}
+/**
+ * State log entry types for JSONL persistence
+ */
+export type StateLogType = 'start' | 'emit' | 'checkpoint' | 'ask' | 'answer' | 'return' | 'error';
+/**
+ * Base state log entry
+ */
+interface StateLogBase {
+    /** Entry type */
+    t: StateLogType;
+    /** Timestamp (Unix ms) */
+    ts: number;
+}
+/**
+ * Workflow start entry
+ */
+export interface StateLogStart extends StateLogBase {
+    t: 'start';
+    /** Tool/method name being executed */
+    tool: string;
+    /** Input parameters */
+    params: Record<string, any>;
+}
+/**
+ * Emit entry (status, progress, etc.)
+ */
+export interface StateLogEmit extends StateLogBase {
+    t: 'emit';
+    /** Emit type (status, progress, stream, log, etc.) */
+    emit: string;
+    /** Emit message */
+    message?: string;
+    /** Additional emit data */
+    data?: any;
+}
+/**
+ * Checkpoint entry - marks safe resume point with state snapshot
+ */
+export interface StateLogCheckpoint extends StateLogBase {
+    t: 'checkpoint';
+    /** Checkpoint ID (auto-generated or explicit) */
+    id: string;
+    /** Accumulated state at this point */
+    state: Record<string, any>;
+}
+/**
+ * Ask entry - input request
+ */
+export interface StateLogAsk extends StateLogBase {
+    t: 'ask';
+    /** Ask ID */
+    id: string;
+    /** Ask type (text, confirm, select, etc.) */
+    ask: string;
+    /** Ask message */
+    message: string;
+}
+/**
+ * Answer entry - input response
+ */
+export interface StateLogAnswer extends StateLogBase {
+    t: 'answer';
+    /** Ask ID this answers */
+    id: string;
+    /** User's response value */
+    value: any;
+}
+/**
+ * Return entry - workflow completion
+ */
+export interface StateLogReturn extends StateLogBase {
+    t: 'return';
+    /** Final return value */
+    value: any;
+}
+/**
+ * Error entry - workflow failed
+ */
+export interface StateLogError extends StateLogBase {
+    t: 'error';
+    /** Error message */
+    message: string;
+    /** Error stack trace */
+    stack?: string;
+}
+/**
+ * Union of all state log entry types
+ */
+export type StateLogEntry = StateLogStart | StateLogEmit | StateLogCheckpoint | StateLogAsk | StateLogAnswer | StateLogReturn | StateLogError;
+/**
+ * Workflow run status
+ */
+export type WorkflowStatus = 'running' | 'waiting' | 'completed' | 'failed' | 'paused';
+/**
+ * Workflow run metadata
+ */
+export interface WorkflowRun {
+    /** Unique run ID */
+    runId: string;
+    /** Photon name */
+    photon: string;
+    /** Tool/method name */
+    tool: string;
+    /** Input parameters */
+    params: Record<string, any>;
+    /** Current status */
+    status: WorkflowStatus;
+    /** Start timestamp */
+    startedAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Completion timestamp (if completed/failed) */
+    completedAt?: number;
+    /** Final result (if completed) */
+    result?: any;
+    /** Error message (if failed) */
+    error?: string;
+    /** Last checkpoint state */
+    lastCheckpoint?: {
+        id: string;
+        state: Record<string, any>;
+        ts: number;
+    };
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmHH;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAY,EAAE,CAAC,GAAe,CAAC;AAErE;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,GAAa,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+PH;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAY,EAAE,CAAC,GAAe,CAAC;AAErE;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,GAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Core library for parsing, loading, and managing .photon.ts files - runtime-agnostic foundation for building custom Photon runtimes",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -8,7 +8,9 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [

package/src/generator.ts

@@ -279,6 +279,174 @@ export interface AskDate extends AskBase {
   default?: string;
 }
 
+/**
+ * JSON Schema property definition for form fields
+ */
+export interface FormSchemaProperty {
+  type: 'string' | 'number' | 'integer' | 'boolean';
+  title?: string;
+  description?: string;
+  default?: any;
+  // String constraints
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: 'email' | 'uri' | 'date' | 'date-time';
+  // Number constraints
+  minimum?: number;
+  maximum?: number;
+  // Enum (single select)
+  enum?: string[];
+  // Enum with titles (single select)
+  oneOf?: Array<{ const: string; title: string }>;
+}
+
+/**
+ * JSON Schema for array (multi-select)
+ */
+export interface FormSchemaArrayProperty {
+  type: 'array';
+  title?: string;
+  description?: string;
+  minItems?: number;
+  maxItems?: number;
+  items: {
+    type?: 'string';
+    enum?: string[];
+    anyOf?: Array<{ const: string; title: string }>;
+  };
+  default?: string[];
+}
+
+/**
+ * Full form schema (flat object only per MCP spec)
+ */
+export interface FormSchema {
+  type: 'object';
+  properties: Record<string, FormSchemaProperty | FormSchemaArrayProperty>;
+  required?: string[];
+}
+
+/**
+ * Form-based input - multi-field structured data with JSON Schema
+ *
+ * Aligned with MCP elicitation spec (form mode).
+ * Schema is limited to flat objects with primitive properties.
+ *
+ * @example
+ * // Simple form
+ * const contact = yield {
+ *   ask: 'form',
+ *   id: 'contact',
+ *   message: 'Enter your contact details',
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       name: { type: 'string', title: 'Full Name' },
+ *       email: { type: 'string', format: 'email', title: 'Email' },
+ *       subscribe: { type: 'boolean', title: 'Subscribe to newsletter', default: true }
+ *     },
+ *     required: ['name', 'email']
+ *   }
+ * };
+ *
+ * @example
+ * // With enum selection
+ * const preferences = yield {
+ *   ask: 'form',
+ *   id: 'prefs',
+ *   message: 'Configure your preferences',
+ *   schema: {
+ *     type: 'object',
+ *     properties: {
+ *       theme: {
+ *         type: 'string',
+ *         title: 'Theme',
+ *         oneOf: [
+ *           { const: 'light', title: 'Light Mode' },
+ *           { const: 'dark', title: 'Dark Mode' },
+ *           { const: 'auto', title: 'System Default' }
+ *         ],
+ *         default: 'auto'
+ *       },
+ *       notifications: {
+ *         type: 'array',
+ *         title: 'Notification Types',
+ *         items: {
+ *           anyOf: [
+ *             { const: 'email', title: 'Email' },
+ *             { const: 'push', title: 'Push' },
+ *             { const: 'sms', title: 'SMS' }
+ *           ]
+ *         },
+ *         default: ['email']
+ *       }
+ *     }
+ *   }
+ * };
+ */
+export interface AskForm extends AskBase {
+  ask: 'form';
+  /** JSON Schema defining the form fields */
+  schema: FormSchema;
+}
+
+/**
+ * URL-based input - opens browser for OAuth or credential collection
+ *
+ * Aligned with MCP elicitation spec (url mode).
+ * User is redirected to a URL for authentication, then returns.
+ *
+ * Security: URL opens in secure browser context (not embedded webview).
+ * The URL should NOT contain sensitive data.
+ *
+ * @example
+ * // OAuth flow
+ * const auth = yield {
+ *   ask: 'url',
+ *   id: 'github_auth',
+ *   message: 'Authenticate with GitHub to continue',
+ *   url: 'https://github.com/login/oauth/authorize?client_id=...'
+ * };
+ *
+ * @example
+ * // API key collection via secure form
+ * const result = yield {
+ *   ask: 'url',
+ *   id: 'api_key',
+ *   message: 'Enter your API key securely',
+ *   url: 'https://myservice.com/collect-api-key?callback=...'
+ * };
+ */
+export interface AskUrl extends AskBase {
+  ask: 'url';
+  /** URL to open in browser */
+  url: string;
+  /**
+   * Unique ID for this elicitation (for async completion).
+   * If not provided, one will be generated.
+   */
+  elicitationId?: string;
+}
+
+/**
+ * Elicitation response action (MCP-aligned)
+ */
+export type ElicitAction = 'accept' | 'decline' | 'cancel';
+
+/**
+ * Result from a form or url elicitation (MCP-aligned)
+ *
+ * Different from the simpler ElicitResult in elicit.ts which is for
+ * native OS dialogs. This follows the MCP elicitation protocol.
+ */
+export interface FormElicitResult<T = any> {
+  /** User's action */
+  action: ElicitAction;
+  /** Form content (only present when action is 'accept' and mode is 'form') */
+  content?: T;
+}
+
 /**
  * Union of all ask (input) yield types
  */
@@ -289,7 +457,9 @@ export type AskYield =
   | AskSelect
   | AskNumber
   | AskFile
-  | AskDate;
+  | AskDate
+  | AskForm
+  | AskUrl;
 
 // ══════════════════════════════════════════════════════════════════════════════
 // EMIT YIELDS - Output to user (fire and forget)
@@ -443,6 +613,52 @@ export interface EmitArtifact {
   mimeType?: string;
 }
 
+/**
+ * UI render - display a UI asset from the Photon's asset folder
+ *
+ * For MCP Apps (SEP-1865) - renders interactive UI templates
+ * The runtime will resolve the asset path and serve the UI appropriately.
+ *
+ * @example
+ * // Show a form UI after a tool runs
+ * yield {
+ *   emit: 'ui',
+ *   id: 'preferences',
+ *   title: 'Configure Preferences',
+ *   data: { currentTheme: 'dark', volume: 80 }
+ * };
+ *
+ * @example
+ * // Show inline HTML content
+ * yield {
+ *   emit: 'ui',
+ *   inline: '<div class="result"><h2>Success!</h2></div>',
+ *   mimeType: 'text/html'
+ * };
+ */
+export interface EmitUI {
+  emit: 'ui';
+  /**
+   * UI asset ID (references @ui annotation in Photon)
+   * Must match an @ui declared asset: @ui preferences ./ui/preferences.html
+   */
+  id?: string;
+  /** Title for the UI panel/dialog */
+  title?: string;
+  /** Data to pass to the UI template (available as window.__photon_data__) */
+  data?: Record<string, any>;
+  /** Inline HTML/JSX content (alternative to id) */
+  inline?: string;
+  /** MIME type for inline content */
+  mimeType?: 'text/html' | 'text/jsx' | 'application/json';
+  /** Display mode */
+  mode?: 'panel' | 'dialog' | 'fullscreen' | 'inline';
+  /** Width hint (CSS value or number in px) */
+  width?: string | number;
+  /** Height hint (CSS value or number in px) */
+  height?: string | number;
+}
+
 /**
  * Union of all emit (output) yield types
  */
@@ -453,17 +669,49 @@ export type EmitYield =
   | EmitLog
   | EmitToast
   | EmitThinking
-  | EmitArtifact;
+  | EmitArtifact
+  | EmitUI;
 
 // ══════════════════════════════════════════════════════════════════════════════
 // COMBINED TYPES
 // ══════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Checkpoint yield - marks a safe resume point for stateful workflows
+ *
+ * Place checkpoints AFTER side effects to ensure idempotency on resume.
+ *
+ * @example
+ * // After a side effect, checkpoint to preserve state
+ * const posted = await this.slack.post_message({ ... });
+ * yield { checkpoint: true, state: { step: 1, messageTs: posted.ts } };
+ */
+export interface CheckpointYield {
+  /** Marker for checkpoint yield */
+  checkpoint: true;
+  /** State snapshot to preserve (accumulated data at this point) */
+  state: Record<string, any>;
+  /** Optional checkpoint ID (auto-generated if not provided) */
+  id?: string;
+}
+
+/**
+ * Type guard for checkpoint yields
+ */
+export function isCheckpointYield(y: any): y is CheckpointYield {
+  return y && 'checkpoint' in y && y.checkpoint === true;
+}
+
 /**
  * All possible yield types from a photon generator
  */
 export type PhotonYield = AskYield | EmitYield;
 
+/**
+ * Extended yield type including checkpoint (for stateful workflows)
+ */
+export type StatefulYield = PhotonYield | CheckpointYield;
+
 // ══════════════════════════════════════════════════════════════════════════════
 // TYPE GUARDS - Check what kind of yield we have
 // ══════════════════════════════════════════════════════════════════════════════
@@ -805,6 +1053,26 @@ function getMockValue(ask: AskYield): any {
       return null;
     case 'date':
       return (ask as AskDate).default || new Date().toISOString();
+    case 'form':
+      // Return object with defaults from schema
+      const form = ask as AskForm;
+      const result: Record<string, any> = {};
+      for (const [key, prop] of Object.entries(form.schema.properties)) {
+        if ('default' in prop && prop.default !== undefined) {
+          result[key] = prop.default;
+        } else if (prop.type === 'string') {
+          result[key] = '';
+        } else if (prop.type === 'number' || prop.type === 'integer') {
+          result[key] = 0;
+        } else if (prop.type === 'boolean') {
+          result[key] = false;
+        } else if (prop.type === 'array') {
+          result[key] = [];
+        }
+      }
+      return { action: 'accept', content: result };
+    case 'url':
+      return { action: 'accept' };
     default:
       return null;
   }