portel-dev/photon

Photon Lifecycle Guide

Photons are single-file TypeScript MCP servers. No compilation — runs directly with tsx.

Quick Start

npm install -g @portel/photon    # Install runtime
photon maker new my-weather      # Create photon
photon beam                      # Launch Beam UI
photon mcp my-weather            # Run as MCP server
photon cli my-weather current --city London  # CLI

Files go in ~/.photon/. See Directory Structure for the full layout. Connect to Claude Desktop:

{ "mcpServers": { "my-weather": { "command": "photon", "args": ["mcp", "my-weather"] } } }

Minimal Photon

import { Photon } from '@portel/photon-core';

/**
 * Weather API
 * @version 1.0.0
 * @dependencies axios@^1.0.0
 * @icon 🌤️
 */
export default class Weather extends Photon {
  constructor(private apiKey: string) { super(); }

  /**
   * Get current weather for a city
   * @param city City name {@example London}
   * @readOnly
   * @title Current Weather
   * @format markdown
   */
  async current({ city }: { city: string }): Promise<string> {
    const res = await fetch(`https://api.weather.com/v1/current?q=${city}&key=${this.apiKey}`);
    if (!res.ok) throw new Error(`API error: ${res.statusText}`);
    const data = await res.json();
    return `**${data.name}** — ${data.temp}°C, ${data.description}`;
  }
}

Core Principles

1. Return values directly — no { success: true, data } wrappers. If it returns, it succeeded.
2. Throw on errors — let the runtime handle them. Don't catch and wrap.
3. Single-word method names — they read as CLI commands: weather current, not weather getCurrentWeather.
4. Constructor = config — constructor params auto-map to env vars: PHOTON_WEATHER_APIKEY.

Class Structure

/**
 * Brief description (becomes photon description)
 *
 * @version 1.0.0
 * @runtime ^1.5.0
 * @dependencies package1, package2@^2.0.0
 * @icon 🔧
 * @tags api, utility
 */
export default class MyTool extends Photon {
  constructor(private apiKey: string) { super(); }

  /**
   * Method description (becomes tool description)
   * @param query Search query {@example "typescript"} {@min 1}
   * @readOnly
   * @title Search Items
   * @format table
   */
  async search({ query }: { query: string }) { ... }
}

MCP Annotations

JSDoc tags map to MCP protocol annotations (spec 2025-11-25):

/**
 * @readOnly        — no side effects, safe to auto-approve
 * @destructive     — requires confirmation
 * @idempotent      — safe to retry
 * @openWorld       — calls external systems
 * @closedWorld     — local data only
 * @title My Tool   — human-readable display name
 * @audience user   — who sees results: user, assistant, or both
 * @priority 0.9    — content importance (0.0–1.0)
 */

UI-only methods: Combine @internal + @audience user for methods the dashboard can call but the LLM never sees:

/**
 * Dashboard-only admin panel data.
 * @internal
 * @audience user
 * @readOnly
 */
async metrics() { return { cpu: 42 }; }

@internal hides from tools/list. @audience user marks results as human-only. The UI still calls via window.photon.callTool('metrics', {}).

Structured Output

Auto-generated from TypeScript return types — no tags needed:

async create(params: { title: string }): Promise<{ id: string; done: boolean }> { ... }

For field descriptions, use an interface with JSDoc:

interface Task {
  /** Unique identifier */
  id: string;
  /** Whether complete */
  done: boolean;
}
async create(params: { title: string }): Promise<Task> { ... }

Output Formats

Use @format to control rendering. Common values:

| Format | Use For | |--------|---------| | table | Array of objects | | list | Styled list with {@title name, @subtitle email} | | checklist | Interactive todo list — {text, done}[] with checkboxes, drag reorder | | article | Magazine-style text flow around images — {text, images?[]} | | markdown | Rich text, diagrams | | slides | Marp-style presentation deck | | chart:bar / chart:line / chart:pie | Data visualization | | json | Raw JSON | | dashboard | Composite panels (auto-detected) |

For complete format reference with layout hints, containers, and auto-detection rules, see references/output-formats.md.

MCP OAuth & Caller Identity

Use @auth for authenticated photons. Enables this.caller in every method.

/**
 * Multiplayer chess
 * @stateful
 * @auth required
 */
export default class Chess extends Photon {
  players: Record<string, string> = {};

  async join() {
    const slot = !this.players.white ? 'white' : 'black';
    this.players[slot] = this.caller.id;
    if (slot === 'black') {
      await this.acquireLock('turn', this.players.white);
    }
    return { color: slot, name: this.caller.name };
  }

  /** @locked turn */
  async move({ from, to }: { from: string; to: string }) {
    // Only reaches here if this.caller.id holds the 'turn' lock
    const next = this.turn === 'white' ? this.players.black : this.players.white;
    await this.transferLock('turn', next);
    return this.board;
  }
}

this.caller: { id, name, anonymous, scope, claims } — populated from MCP OAuth JWT.

Identity-aware locks:

• this.acquireLock(name, callerId) — assign lock to a caller
• this.transferLock(name, toCallerId) — move lock to another caller
• this.releaseLock(name) — release, open to anyone
• this.getLock(name) — query who holds the lock
• @locked methods auto-check this.caller.id against lock holder

Lifecycle & Hot-Reload

// Lifecycle hooks — receive optional context for hot-reload support
async onInitialize(ctx?: { reason?: string; oldInstance?: any }) {
  if (ctx?.reason === 'hot-reload' && ctx.oldInstance) {
    // Transfer non-serializable resources (sockets, timers, connections)
    this.socket = ctx.oldInstance.socket;
    ctx.oldInstance.socket = null; // prevent old instance from using it
    return;
  }
  // Normal first-time initialization
  this.socket = await createConnection();
}

async onShutdown(ctx?: { reason?: string }) {
  if (ctx?.reason === 'hot-reload') {
    return; // DON'T close resources — new instance will take them
  }
  // Real shutdown: clean up everything
  this.socket?.close();
}

Hot-reload rules:

• onShutdown({ reason: 'hot-reload' }) → skip resource cleanup
• onInitialize({ reason: 'hot-reload', oldInstance }) → transfer resources from old instance
• Normal shutdown/init (no context) → full cleanup/setup
• Backward compatible — photons without context param still work

Events & Channels

// Simple emit (local only — goes to current caller's UI)
this.emit({ status: 'processing', progress: 50 });

// Channel emit (cross-photon pub/sub via daemon broker)
// Framework auto-prefixes with photon name: 'messages' → 'whatsapp:messages'
this.emit({ channel: 'messages', type: 'message', data: msg });

// Subscribe to another photon's events (use the full prefixed name)
const broker = getBroker();
const sub = await broker.subscribe('whatsapp:messages', (msg) => {
  // handle message
});
sub.unsubscribe(); // when done

Channel naming: Emit with simple names (channel: 'messages'). The framework auto-prefixes with the photon name. Channels with a colon are left as-is.

Generator Workflows

// Multi-step with user interaction
async *deploy({ env }: { env: string }) {
  yield { emit: 'status', message: 'Deploying...' };
  const ok = yield { ask: 'confirm', message: `Deploy to ${env}?` };
  if (!ok) return 'Cancelled';
  return 'Done';
}

// Waiting for external async events (WebSocket, library callbacks, etc.)
async *connect() {
  yield { emit: 'status', message: 'Connecting...' };
  let resolve: (v: any) => void;
  const promise = new Promise(r => { resolve = r; });
  this.socket.on('ready', (data) => resolve(data));
  await this.initSocket();
  const event = await promise;  // blocks until external event fires
  yield { emit: 'toast', message: 'Connected!', type: 'success' };
  return event;
}

Scoped Memory

Zero-config persistent storage via this.memory:

await this.memory.set('key', value);              // photon scope (default)
const val = await this.memory.get<T>('key');
await this.memory.set('shared', data, 'global');   // cross-photon

Three scopes: photon (private), session (per-user), global (shared). Full API: get, set, delete, has, keys, clear, getAll, update.

Runtime Scheduling

Dynamic task scheduling via this.schedule — complements static @scheduled/@cron tags:

// Create a scheduled task at runtime
await this.schedule.create({
  name: 'nightly-cleanup',
  schedule: '0 0 * * *',       // 5-field cron or @daily, @hourly, @weekly, @monthly
  method: 'purge',
  params: { olderThan: 30 },
});

// Manage tasks
await this.schedule.pause(id);
await this.schedule.resume(id);
await this.schedule.cancel(id);
const tasks = await this.schedule.list('active');

Full API: create, get, getByName, list, update, pause, resume, cancel, cancelByName, cancelAll, has. Tasks persist to disk; the daemon executes them.

Use @scheduled/@cron for fixed schedules known at build time. Use this.schedule for dynamic schedules created at runtime (user-configured intervals, conditional jobs, etc.).

User Settings

Expose configurable options via protected settings. Runtime auto-generates a settings tool and persists to disk:

export default class MyAgent extends Photon {
  protected settings = {
    /** Polling interval in ms */
    pollIntervalMs: 5000,
    /** Max concurrent operations */
    maxConcurrent: 3,
    /** Auto-resume after restart */
    autoResume: true,
  };

  async doWork() {
    const interval = this.settings.pollIntervalMs; // read-only Proxy
  }
}

Users change settings via CLI (photon cli my-agent settings). Values persist to ~/.photon/state/<name>/<instance>-settings.json.

Live Rendering (v1.14+)

this.render(format, value) pushes formatted output that replaces the previous render zone (instead of appending):

export default class Monitor {
  async status() {
    while (true) {
      const metrics = await this.collectMetrics();
      this.render('table', metrics);  // Replaces previous output
      await new Promise(r => setTimeout(r, 5000));
    }
  }
}

Accepts the same format values as @format tags. Call this.render() with no arguments to clear the render zone.

Compile to Binary (v1.13+)

Build standalone executables from any photon — no Node.js required on the target machine:

photon build my-tool                         # Binary for current platform
photon build my-tool -t bun-linux-x64        # Cross-compile for Linux
photon build my-tool --with-app              # Embed Beam UI as a desktop app

Uses Bun's compiler. The binary bundles the photon, its @dependencies, and transitive @photon deps.

Installing Photons

photon add — Install a photon

photon add claw                        # Search all marketplaces by name
photon add my-marketplace/claw         # From a specific marketplace
photon add Arul-/photons/claw          # From a GitHub repo (owner/repo/name)

If a photon has @photon dependencies, they are auto-installed from the same source recursively.

photon beam / photon cli — Run directly from GitHub

photon beam Arul-/photons/claw         # Install + open in Beam
photon cli Arul-/photons/todo add      # Install + run method

Manage marketplaces

photon marketplace add Arul-/photons   # Add a GitHub repo as marketplace source
photon marketplace update              # Refresh all marketplace caches
photon marketplace list                # Show configured marketplaces

Custom UIs

Link HTML files as interactive result renderers:

/** @ui dashboard */
export default class MyApp extends Photon {
  /** @ui dashboard */
  async getData({ range }: { range: string }) { return { metrics: 42 }; }
}

Convention: @ui <id> resolves to <photon>/ui/<id>.html. The id MUST match the HTML filename.

@ui dashboard  → my-app/ui/dashboard.html  ✓
@ui slides     → slides/ui/slides.html     ✓

Text after the id is treated as a description, NOT a file path.

The UI gets a photon-named global proxy: window.myApp.getData(...), window.myApp.onResult(...).

For full MCP Apps guide, see references/mcp-apps.md.

Directory Structure

Photon separates source/assets from runtime data under ~/.photon/:

~/.photon/
├── <name>.photon.ts        # Source (or symlink)
├── <name>/                 # Assets (@ui templates, images)
├── state/<name>/           # Runtime: this.memory, settings (automatic)
├── data/<name>/            # Runtime: photon-written files (manual)
├── cache/                  # Runtime: compiled .mjs cache
└── logs/<name>/            # Runtime: execution logs

Key rule: Photons that write runtime files (auth tokens, downloaded media, databases) MUST use ~/.photon/data/<name>/, never ~/.photon/<name>/. The asset folder is watched for hot-reload — writing there causes reload loops.

// Correct: runtime data goes in data/<name>/
const dataDir = path.join(os.homedir(), '.photon', 'data', 'my-app');

// Wrong: asset folder triggers hot-reload!
const dataDir = path.join(os.homedir(), '.photon', 'my-app', 'downloads');

For the full convention, see Directory Structure.

Validating Photon UIs — Promise Checking

Every @ui photon makes implicit promises through its backend methods. The UI must deliver on them.

The Principle

A photon's backend methods are its capabilities. The UI is the interface to those capabilities. If a method exists but the UI has no way to trigger it, that's a broken promise.

Three signal levels:

| Signal | Meaning | |--------|---------| | @ui <id> on a method | This method's result is rendered by the UI — the UI MUST handle it | | @audience user | Result is for the human, not the LLM — the UI SHOULD surface it | | Public method (no @internal) | Capability exists — the UI or CLI should make it accessible |

If a method is public but the UI doesn't use it, either:

• Add a UI control for it, or
• Mark it @internal to be honest about what's exposed

Promise Documentation

Every @ui photon should have a ## UI Promises section in its class docblock:

/**
 * Slides — AI-Native Presentation Tool
 *
 * ## UI Promises
 *
 * - Filmstrip with thumbnails for slide navigation
 * - Drag-and-drop to reorder slides
 * - Theme selector (default, gaia, uncover)
 * - Fullscreen presentation with scaled slides
 * - Markdown editor with live preview
 * - Speaker notes editor
 * - Deck picker to switch or create presentations
 */

These are the acceptance criteria. Each line is a testable claim. Validation means checking every claim is true.

Gap Detection

To validate, compare two lists:

1. Backend capabilities — all public methods in the .photon.ts, especially those tagged @ui or @audience user
2. UI consumption — all method calls in the HTML template (e.g., window["slides"].move(...))

Any method in list 1 but not in list 2 is a gap. Any promise in the docblock that has no corresponding UI control is a broken promise.

Two Layers of Quality

| Layer | What it catches | What it misses | |-------|----------------|----------------| | Cosmetic (screenshot review) | Broken layout, contrast, overflow, clipping | Missing features, interaction bugs | | Functional (promise check) | Missing features, unconsumed methods, state gaps | Subtle visual bugs |

Both layers are needed. A UI can look perfect while missing half its features.

References

| Topic | When to Read | |-------|-------------| | Directory Structure | Need the ~/.photon/ layout rules for assets vs runtime data | | Docblock Tags | Need the complete tag reference (class, method, inline, daemon, MCP) | | Output Formats | Need layout hints, chart mapping, containers, or auto-detection rules | | Dependency Injection | Using @mcp, @photon, or this.call() for cross-photon communication | | Daemon Features | Setting up webhooks, cron jobs, or distributed locks | | User Settings | protected settings, persistence, auto-resume patterns | | MCP Apps | Building custom HTML UIs with the photon bridge | | Visualization | Generating Mermaid diagrams from photons | | Mermaid Syntax | Flowchart shapes, arrows, subgraphs | | Photon Patterns | Common emit/ask/yield patterns, path resolution (this.callerCwd), Mermaid equivalents | | Examples | Complete Photon-to-Mermaid conversion examples | | Validation | Promise checking, gap detection, UI testing checklist |