@portel/photon 1.25.0 → 1.26.1

package/templates/cloudflare/worker.ts.template

@@ -1,37 +1,547 @@
 /**
  * Photon MCP Worker for Cloudflare
  * Auto-generated - do not edit directly
+ *
+ * Architecture: each photon (the host plus any `@photons` siblings) lives
+ * in its own Durable Object class so `this.memory`, `this.emit`,
+ * `this.schedule`, and `this.call` work identically to the local daemon.
+ * One DO per `instanceName` per photon — see docs/internals/CF-DURABLE-OBJECTS.md.
  */
 
-// @ts-ignore - Will be replaced during build
-import PhotonClass from './photon';
+import { DurableObject } from 'cloudflare:workers';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { CronExpressionParser } from 'cron-parser';
+__PHOTON_IMPORTS__
 
 interface Env {
-  // Add your environment variables here
-  [key: string]: string | undefined;
+  PHOTON: DurableObjectNamespace;
+  [key: string]: any;
 }
 
-// Tool definitions extracted at build time
-// @ts-ignore - Will be replaced during build
-const TOOL_DEFINITIONS: any[] = __TOOL_DEFINITIONS__;
-const PHOTON_NAME = '__PHOTON_NAME__';
 const DEV_MODE = __DEV_MODE__;
+const HOST_PHOTON_NAME = '__HOST_PHOTON_NAME__';
+
+/**
+ * Photon name → Worker env binding name. Generated at deploy time from the
+ * host photon's source plus every `@photons` sibling. `this.call('foo.bar')`
+ * uses this to find the right DO namespace.
+ */
+const PHOTON_BINDINGS: Record<string, string> = __PHOTON_BINDINGS_MAP__;
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Mcp-Session-Id, X-Photon-Instance',
+};
 
-// Instantiate photon
-let photonInstance: InstanceType<typeof PhotonClass> | null = null;
+// ════════════════════════════════════════════════════════════════════════════
+// Memory proxy — ctx.storage backing for this.memory
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Build a `MemoryBackend`-shaped accessor over `ctx.storage`. Mirrors the
+ * `this.memory` API the local runtime exposes. Per-namespace keys are
+ * encoded as `${namespace}:${key}` so one DO storage table holds multiple
+ * namespaces while preserving the boundary the runtime relies on. The DO
+ * input gate already serializes calls per-DO, so `update` is just
+ * read-modify-write — no extra locking needed.
+ */
+function createMemoryProxy(ctx: DurableObjectState) {
+  const ns = (key: string, namespace = 'default') => `${namespace}:${key}`;
+  return {
+    async get(key: string, opts?: { namespace?: string }) {
+      const v = await ctx.storage.get(ns(key, opts?.namespace));
+      return v === undefined ? null : v;
+    },
+    async set(key: string, value: unknown, opts?: { namespace?: string }) {
+      await ctx.storage.put(ns(key, opts?.namespace), value);
+    },
+    async delete(key: string, opts?: { namespace?: string }) {
+      return ctx.storage.delete(ns(key, opts?.namespace));
+    },
+    async has(key: string, opts?: { namespace?: string }) {
+      const v = await ctx.storage.get(ns(key, opts?.namespace));
+      return v !== undefined;
+    },
+    async keys(opts?: { namespace?: string }) {
+      const prefix = `${opts?.namespace ?? 'default'}:`;
+      const map = await ctx.storage.list({ prefix });
+      return Array.from(map.keys()).map((k) => k.slice(prefix.length));
+    },
+    async list(opts?: { namespace?: string; prefix?: string }) {
+      const namespacePrefix = `${opts?.namespace ?? 'default'}:`;
+      const prefix = namespacePrefix + (opts?.prefix ?? '');
+      const map = await ctx.storage.list({ prefix });
+      return Array.from(map.entries()).map(([k, v]) => ({
+        key: k.slice(namespacePrefix.length),
+        value: v,
+      }));
+    },
+    async clear(opts?: { namespace?: string }) {
+      const prefix = `${opts?.namespace ?? 'default'}:`;
+      const map = await ctx.storage.list({ prefix });
+      if (map.size > 0) {
+        await ctx.storage.delete(Array.from(map.keys()));
+      }
+    },
+    async update(
+      key: string,
+      updater: (current: any) => any,
+      opts?: { namespace?: string }
+    ): Promise<any> {
+      const fullKey = ns(key, opts?.namespace);
+      const current = (await ctx.storage.get(fullKey)) ?? null;
+      const next = await updater(current);
+      await ctx.storage.put(fullKey, next);
+      return next;
+    },
+  };
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Schedule provider — DO alarm multiplexer
+// ════════════════════════════════════════════════════════════════════════════
+
+const SCHEDULE_PREFIX = '__sched__:';
+
+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 * * * *',
+};
 
-function getPhoton(env: Env): InstanceType<typeof PhotonClass> {
-  if (!photonInstance) {
-    // Pass env vars as constructor params if needed
-    photonInstance = new PhotonClass();
+function resolveCron(schedule: string): string {
+  const trimmed = schedule.trim();
+  const shorthand = CRON_SHORTHANDS[trimmed.toLowerCase()];
+  if (shorthand) return shorthand;
+  if (trimmed.split(/\s+/).length !== 5) {
+    throw new Error(
+      `Invalid cron expression: '${schedule}'. Expected 5 fields or a shorthand (@hourly, @daily, @weekly, @monthly, @yearly).`
+    );
   }
-  return photonInstance;
+  return trimmed;
+}
+
+function nextFireMs(cron: string, from: Date = new Date()): number {
+  return CronExpressionParser.parse(cron, { currentDate: from }).next().getTime();
+}
+
+interface ScheduledTask {
+  id: string;
+  name: string;
+  description?: string;
+  cron: string;
+  method: string;
+  params: Record<string, unknown>;
+  fireOnce: boolean;
+  maxExecutions: number;
+  status: 'active' | 'paused' | 'completed' | 'error';
+  createdAt: string;
+  lastExecutionAt?: string;
+  executionCount: number;
+  errorMessage?: string;
+  photonId: string;
+}
+
+async function listSchedules(ctx: DurableObjectState): Promise<ScheduledTask[]> {
+  const map = await ctx.storage.list<ScheduledTask>({ prefix: SCHEDULE_PREFIX });
+  return Array.from(map.values());
+}
+
+async function rescheduleAlarm(ctx: DurableObjectState): Promise<void> {
+  const tasks = await listSchedules(ctx);
+  let earliest = Infinity;
+  const now = Date.now();
+  for (const task of tasks) {
+    if (task.status !== 'active') continue;
+    const fromTs = Math.max(
+      task.lastExecutionAt ? Date.parse(task.lastExecutionAt) : 0,
+      now - 1000
+    );
+    const t = nextFireMs(task.cron, new Date(fromTs));
+    if (t < earliest) earliest = t;
+  }
+  if (earliest === Infinity) {
+    await ctx.storage.deleteAlarm();
+  } else {
+    await ctx.storage.setAlarm(earliest);
+  }
+}
+
+function createScheduleProvider(ctx: DurableObjectState, photonId: string) {
+  return {
+    async create(opts: {
+      name: string;
+      schedule: string;
+      method: string;
+      params?: Record<string, unknown>;
+      description?: string;
+      fireOnce?: boolean;
+      maxExecutions?: number;
+    }): Promise<ScheduledTask> {
+      const cron = resolveCron(opts.schedule);
+      const all = await listSchedules(ctx);
+      if (all.find((t) => t.name === opts.name)) {
+        throw new Error(`Schedule '${opts.name}' already exists. Use update() to modify it.`);
+      }
+      const task: ScheduledTask = {
+        id: crypto.randomUUID(),
+        name: opts.name,
+        description: opts.description,
+        cron,
+        method: opts.method,
+        params: opts.params ?? {},
+        fireOnce: opts.fireOnce ?? false,
+        maxExecutions: opts.maxExecutions ?? 0,
+        status: 'active',
+        createdAt: new Date().toISOString(),
+        executionCount: 0,
+        photonId,
+      };
+      await ctx.storage.put(SCHEDULE_PREFIX + task.id, task);
+      await rescheduleAlarm(ctx);
+      return task;
+    },
+    async get(id: string): Promise<ScheduledTask | null> {
+      return (await ctx.storage.get<ScheduledTask>(SCHEDULE_PREFIX + id)) ?? null;
+    },
+    async getByName(name: string): Promise<ScheduledTask | null> {
+      const all = await listSchedules(ctx);
+      return all.find((t) => t.name === name) ?? null;
+    },
+    async list(status?: ScheduledTask['status']): Promise<ScheduledTask[]> {
+      const all = await listSchedules(ctx);
+      return status ? all.filter((t) => t.status === status) : all;
+    },
+    async cancel(id: string): Promise<boolean> {
+      const ok = await ctx.storage.delete(SCHEDULE_PREFIX + id);
+      if (ok) await rescheduleAlarm(ctx);
+      return ok;
+    },
+    async update(
+      id: string,
+      updates: Partial<
+        Pick<ScheduledTask, 'method' | 'params' | 'description' | 'fireOnce' | 'maxExecutions'>
+      > & { schedule?: string }
+    ): Promise<ScheduledTask> {
+      const cur = await ctx.storage.get<ScheduledTask>(SCHEDULE_PREFIX + id);
+      if (!cur) throw new Error(`Schedule ${id} not found`);
+      const next: ScheduledTask = {
+        ...cur,
+        ...updates,
+        cron: updates.schedule ? resolveCron(updates.schedule) : cur.cron,
+      };
+      await ctx.storage.put(SCHEDULE_PREFIX + id, next);
+      await rescheduleAlarm(ctx);
+      return next;
+    },
+  };
 }
 
-// MCP JSON-RPC handler
-async function handleMCPRequest(request: any, env: Env): Promise<any> {
+// ════════════════════════════════════════════════════════════════════════════
+// Cross-photon call — env.PHOTON_<NAME> stub routing
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * `this.call('sibling.method', params, {instance?})` — hops to a sibling
+ * photon's DO via the env binding generated at deploy time. The sibling DO
+ * exposes an internal /__call endpoint that dispatches the request to the
+ * named method (with the same simpleParams spreading rule the public MCP
+ * surface uses) and returns the result inline.
+ */
+function createCallProvider(env: Env, callerName: string) {
+  return async (
+    target: string,
+    params: Record<string, unknown> = {},
+    options?: { instance?: string }
+  ): Promise<unknown> => {
+    const dotIndex = target.indexOf('.');
+    if (dotIndex === -1) {
+      throw new Error(
+        `Invalid call target: '${target}'. Expected format: 'photonName.methodName'.`
+      );
+    }
+    const photonName = target.slice(0, dotIndex);
+    const methodName = target.slice(dotIndex + 1);
+    if (photonName === callerName) {
+      throw new Error(
+        `this.call('${target}') points at the caller's own photon. Call the method directly via this.${methodName}(...) instead.`
+      );
+    }
+    const bindingName = PHOTON_BINDINGS[photonName];
+    if (!bindingName) {
+      throw new Error(
+        `Unknown photon '${photonName}' in this.call('${target}'). Add it to the host photon's @photons docblock so it gets bundled.`
+      );
+    }
+    const ns = env[bindingName] as DurableObjectNamespace | undefined;
+    if (!ns) {
+      throw new Error(
+        `Worker is missing binding '${bindingName}'. The deploy adapter should have generated it; rerun \`photon host deploy cf\`.`
+      );
+    }
+    const stub = ns.get(ns.idFromName(options?.instance ?? 'default'));
+    const res = await stub.fetch('http://photon.internal/__call', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ method: methodName, args: params }),
+    });
+    const payload = (await res.json()) as { ok: boolean; result?: unknown; error?: string };
+    if (!payload.ok) {
+      throw new Error(payload.error ?? `Cross-photon call to ${target} failed`);
+    }
+    return payload.result;
+  };
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Capability shim — wires this.* on the photon instance
+// ════════════════════════════════════════════════════════════════════════════
+
+function withCfCapabilities(
+  instance: any,
+  ctx: DurableObjectState,
+  env: Env,
+  photonName: string
+): any {
+  Object.defineProperty(instance, 'memory', {
+    value: createMemoryProxy(ctx),
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
+  Object.defineProperty(instance, 'emit', {
+    value: (event: { channel?: string; [k: string]: unknown }) => {
+      const channel = (event && typeof event === 'object' && event.channel) || 'default';
+      const payload = JSON.stringify(event);
+      for (const ws of ctx.getWebSockets(channel)) {
+        try {
+          ws.send(payload);
+        } catch {
+          // Socket closing; webSocketClose hook will reap.
+        }
+      }
+    },
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
+  Object.defineProperty(instance, 'schedule', {
+    value: createScheduleProvider(ctx, photonName),
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
+  Object.defineProperty(instance, 'call', {
+    value: createCallProvider(env, photonName),
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
+  Object.defineProperty(instance, 'callerCwd', {
+    get() {
+      return undefined;
+    },
+    enumerable: false,
+    configurable: false,
+  });
+
+  // Worker env exposed to the photon for direct binding access — Workers AI
+  // (`env.AI.run('@cf/...', ...)`), KV, R2, queues, secrets. Photons that
+  // want to stay CF-portable should branch on `(this as any).env?.AI` and
+  // fall back to a non-CF path on the local daemon (where `env` is
+  // undefined). Non-enumerable so it doesn't leak into JSON output.
+  Object.defineProperty(instance, 'env', {
+    value: env,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
+  // Human/LLM-in-the-loop primitives. Each one wraps an MCP server-initiated
+  // request (sampling/createMessage, elicitation/create), pushed over the
+  // active tool call's SSE response stream and awaited on a Promise keyed by
+  // request id. The pending map and the SSE writer live on the per-request
+  // AsyncLocalStorage context so concurrent tool calls don't collide.
+  Object.defineProperty(instance, 'sample', {
+    value: cfSample,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+  Object.defineProperty(instance, 'confirm', {
+    value: cfConfirm,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+  Object.defineProperty(instance, 'elicit', {
+    value: cfElicit,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+
+  return instance;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Server-initiated MCP requests — sample / confirm / elicit
+// ════════════════════════════════════════════════════════════════════════════
+
+interface PendingRequest {
+  resolve: (value: any) => void;
+  reject: (error: Error) => void;
+}
+
+interface RequestContext {
+  /** Push one JSON-RPC message to the client over the active SSE response. */
+  send: (msg: unknown) => Promise<void>;
+  /** Shared pending map; the DO's POST /mcp handler resolves entries here. */
+  pendingRequests: Map<string, PendingRequest>;
+}
+
+/**
+ * Per-tool-call context. Set when the DO begins streaming a tool call
+ * response and read by `this.sample` / `this.confirm` / `this.elicit` to
+ * find the right SSE writer + pending map. AsyncLocalStorage propagates
+ * the context across awaits so a tool that calls `await this.sample()`
+ * deep in its async tree still hits the right context.
+ */
+const requestContext = new AsyncLocalStorage<RequestContext>();
+
+function requireRequestContext(which: string): RequestContext {
+  const ctx = requestContext.getStore();
+  if (!ctx) {
+    throw new Error(
+      `this.${which}() requires the calling client to use SSE (Accept: text/event-stream). ` +
+        `Stateless JSON requests can't carry server-initiated MCP messages back to the client. ` +
+        `If you control the client, set the Accept header. If not, the photon should not call ` +
+        `this.${which}() in tools invoked by JSON-only callers.`
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Send a server-initiated JSON-RPC request to the client over the active
+ * SSE stream and await the matching response. The DO's POST /mcp handler
+ * resolves the pending Promise when the client posts back a response with
+ * the same id.
+ */
+async function sendServerRequest(method: string, params: unknown, which: string): Promise<unknown> {
+  const ctx = requireRequestContext(which);
+  const id = crypto.randomUUID();
+  const promise = new Promise<unknown>((resolve, reject) => {
+    ctx.pendingRequests.set(id, { resolve, reject });
+  });
+  await ctx.send({ jsonrpc: '2.0', id, method, params });
+  return promise;
+}
+
+async function cfSample(params: {
+  prompt?: string;
+  messages?: Array<{ role: string; content: { type: string; text?: string } }>;
+  maxTokens?: number;
+  systemPrompt?: string;
+  temperature?: number;
+}): Promise<string> {
+  if (!params.prompt && !params.messages?.length) {
+    throw new Error('this.sample() requires either `prompt` or `messages`.');
+  }
+  const messages =
+    params.messages ??
+    [{ role: 'user' as const, content: { type: 'text' as const, text: params.prompt! } }];
+  const result = (await sendServerRequest(
+    'sampling/createMessage',
+    {
+      messages,
+      maxTokens: params.maxTokens ?? 1024,
+      ...(params.systemPrompt ? { systemPrompt: params.systemPrompt } : {}),
+      ...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
+    },
+    'sample'
+  )) as { content?: { type?: string; text?: string } } | string | undefined;
+  if (typeof result === 'string') return result;
+  if (result?.content?.type === 'text' && typeof result.content.text === 'string') {
+    return result.content.text;
+  }
+  return JSON.stringify(result);
+}
+
+async function cfElicit<T = unknown>(params: {
+  message?: string;
+  question?: string;
+  requestedSchema?: unknown;
+  [k: string]: unknown;
+}): Promise<T> {
+  const message = params.message ?? params.question ?? 'Input requested';
+  const result = await sendServerRequest(
+    'elicitation/create',
+    {
+      message,
+      ...(params.requestedSchema ? { requestedSchema: params.requestedSchema } : {}),
+    },
+    'elicit'
+  );
+  // Per MCP elicitation spec the response carries `content` with the user's
+  // answer. Some clients return the answer at the top level for simple
+  // schemas; accept either shape so photon code stays compact.
+  const obj = result as { content?: T } | T;
+  return ((obj as { content?: T })?.content ?? (obj as T));
+}
+
+async function cfConfirm(question: string): Promise<boolean> {
+  const result = await cfElicit<{ confirmed?: boolean } | boolean>({
+    message: question,
+    requestedSchema: {
+      type: 'object',
+      properties: {
+        confirmed: {
+          type: 'boolean',
+          title: 'Confirm',
+          description: question,
+        },
+      },
+      required: ['confirmed'],
+    },
+  });
+  if (typeof result === 'boolean') return result;
+  return Boolean(result?.confirmed);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Tool dispatch
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert the JSON-RPC `arguments` object into the positional-call arg list
+ * the photon method expects. Mirrors the local loader's logic so a photon
+ * behaves identically whether it runs on the daemon or as a Cloudflare Worker.
+ */
+function spreadArgs(toolDef: any, args: Record<string, unknown>): unknown[] {
+  if (toolDef?.simpleParams && args && typeof args === 'object') {
+    const paramNames = Object.keys(toolDef.inputSchema?.properties || {});
+    return paramNames.map((name) => args[name]);
+  }
+  return [args];
+}
+
+async function handleMCPRequest(
+  request: any,
+  photon: any,
+  photonName: string,
+  toolDefinitions: any[]
+): Promise<any> {
   const { method, params, id } = request;
-  const photon = getPhoton(env);
 
   switch (method) {
     case 'initialize':
@@ -41,7 +551,7 @@ async function handleMCPRequest(request: any, env: Env): Promise<any> {
         result: {
           protocolVersion: '2024-11-05',
           capabilities: { tools: {} },
-          serverInfo: { name: PHOTON_NAME, version: '1.0.0' },
+          serverInfo: { name: photonName, version: '1.0.0' },
         },
       };
 
@@ -49,21 +559,19 @@ async function handleMCPRequest(request: any, env: Env): Promise<any> {
       return {
         jsonrpc: '2.0',
         id,
-        result: { tools: TOOL_DEFINITIONS },
+        result: { tools: toolDefinitions },
       };
 
     case 'tools/call': {
       const { name, arguments: args } = params;
       try {
-        const method = (photon as any)[name];
-        if (typeof method !== 'function') {
+        const fn = (photon as any)[name];
+        if (typeof fn !== 'function') {
           throw new Error(`Unknown tool: ${name}`);
         }
-        const result = await method.call(photon, args || {});
-        // String returns (e.g. markdown from `read`) flow through as-is so
-        // clients receive renderable text. Other shapes are JSON-stringified
-        // for legibility. Structured shapes are also surfaced via
-        // `structuredContent` per MCP — clients that prefer JSON pick it up.
+        const toolDef = toolDefinitions.find((t: any) => t.name === name);
+        const callArgs = spreadArgs(toolDef, args || {});
+        const result = await fn.call(photon, ...callArgs);
         const isString = typeof result === 'string';
         const text = isString ? result : JSON.stringify(result, null, 2);
         const isObject = result !== null && typeof result === 'object';
@@ -100,43 +608,414 @@ async function handleMCPRequest(request: any, env: Env): Promise<any> {
   }
 }
 
-// SSE stream handler
-/**
- * Stateless MCP Streamable HTTP handler.
- *
- * Each POST /mcp is a complete JSON-RPC exchange: body in, result out, no
- * session state carried across requests. This matches the MCP Streamable
- * HTTP spec's single-endpoint pattern and stays within the Cloudflare
- * Workers free tier (no Durable Objects needed for session storage).
- */
-async function handleStreamableMCP(request: Request, env: Env): Promise<Response> {
+async function handleStreamableMCP(
+  request: Request,
+  photon: any,
+  photonName: string,
+  toolDefinitions: any[]
+): Promise<Response> {
   let body: unknown;
   try {
     body = await request.json();
   } catch (error: any) {
     return Response.json(
-      { jsonrpc: '2.0', id: null, error: { code: -32700, message: `Parse error: ${error?.message ?? String(error)}` } },
+      {
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: `Parse error: ${error?.message ?? String(error)}` },
+      },
       { status: 400, headers: CORS_HEADERS }
     );
   }
-  const result = await handleMCPRequest(body, env);
+  const result = await handleMCPRequest(body, photon, photonName, toolDefinitions);
   return Response.json(result, { headers: CORS_HEADERS });
 }
 
-const CORS_HEADERS = {
-  'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Mcp-Session-Id',
+// ════════════════════════════════════════════════════════════════════════════
+// BasePhotonDO — shared logic for every per-photon DO class
+// ════════════════════════════════════════════════════════════════════════════
+
+abstract class BasePhotonDO extends DurableObject<Env> {
+  protected abstract readonly photonName: string;
+  protected abstract readonly toolDefinitions: any[];
+  protected readonly httpRoutes: { method: string; path: string; handler: string }[] = [];
+  protected abstract createPhoton(): any;
+
+  protected photon: any;
+  protected instanceName: string;
+
+  /**
+   * In-flight server-initiated MCP requests, keyed by request id. The active
+   * tool call's `this.sample` / `this.confirm` / `this.elicit` add entries
+   * here; the POST /mcp handler resolves them when the client sends the
+   * response. Lives on the DO instance so it persists across the multiple
+   * fetch handlers (one for the original tool call, one per client response).
+   */
+  protected pendingRequests = new Map<string, PendingRequest>();
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.instanceName = ctx.id.name ?? 'default';
+    this.photon = withCfCapabilities(this.createPhoton(), ctx, env, this.photonName);
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+
+    // Internal cross-photon call — invoked by sibling DOs via this.call.
+    // Not exposed externally (outer Worker doesn't route to this path).
+    if (url.pathname === '/__call' && request.method === 'POST') {
+      try {
+        const { method, args } = (await request.json()) as {
+          method: string;
+          args: Record<string, unknown>;
+        };
+        const fn = (this.photon as any)[method];
+        if (typeof fn !== 'function') {
+          return Response.json({ ok: false, error: `Unknown method: ${method}` });
+        }
+        const toolDef = this.toolDefinitions.find((t: any) => t.name === method);
+        const callArgs = spreadArgs(toolDef, args || {});
+        const result = await fn.call(this.photon, ...callArgs);
+        return Response.json({ ok: true, result });
+      } catch (error: any) {
+        return Response.json({ ok: false, error: error?.message ?? String(error) });
+      }
+    }
+
+    // Hibernatable WebSocket upgrade for emit subscribers, tagged by channel.
+    if (url.pathname === '/events' && request.headers.get('Upgrade') === 'websocket') {
+      const channel = url.searchParams.get('channel') ?? 'default';
+      const pair = new WebSocketPair();
+      const client = pair[0];
+      const server = pair[1];
+      this.ctx.acceptWebSocket(server, [channel]);
+      return new Response(null, { status: 101, webSocket: client });
+    }
+
+    // MCP Streamable HTTP. Three flavors of POST /mcp body:
+    //  - JSON-RPC request (has `method`): tools/call, initialize, etc.
+    //    Tool calls may produce server-initiated requests during execution
+    //    (sample/confirm/elicit), so when the client signals SSE support
+    //    (`Accept: text/event-stream`) we stream the response. Plain JSON
+    //    is the default for clients that don't.
+    //  - JSON-RPC response (has `result` or `error`, no `method`): the
+    //    client answering a server-initiated request. We resolve the
+    //    matching pending entry and ack with 204.
+    if (url.pathname === '/mcp' && request.method === 'POST') {
+      return this._handleMcpPost(request);
+    }
+    if (url.pathname === '/mcp' && request.method === 'GET') {
+      return new Response(': streamable-http\n\n', {
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          ...CORS_HEADERS,
+        },
+      });
+    }
+    if (url.pathname === '/mcp' && request.method === 'DELETE') {
+      return new Response(null, { status: 204, headers: CORS_HEADERS });
+    }
+
+    // Info endpoint
+    if (url.pathname === '/' && request.method === 'GET') {
+      return Response.json(
+        {
+          name: this.photonName,
+          instance: this.instanceName,
+          transport: 'streamable-http',
+          runtime: 'cloudflare-workers',
+          endpoints: {
+            mcp: '/mcp',
+            events: '/events?channel=<name>',
+            ...(DEV_MODE ? { playground: '/playground' } : {}),
+          },
+          tools: this.toolDefinitions.length,
+        },
+        { headers: CORS_HEADERS }
+      );
+    }
+
+    // Dev-only endpoints
+    if (DEV_MODE) {
+      if (url.pathname === '/playground') {
+        return new Response(getPlaygroundHTML(this.photonName, this.toolDefinitions), {
+          headers: { 'Content-Type': 'text/html' },
+        });
+      }
+      if (url.pathname === '/api/tools') {
+        return Response.json({ tools: this.toolDefinitions }, { headers: CORS_HEADERS });
+      }
+      if (url.pathname === '/api/call' && request.method === 'POST') {
+        const { tool, args } = (await request.json()) as { tool: string; args: any };
+        try {
+          const fn = (this.photon as any)[tool];
+          if (typeof fn !== 'function') {
+            throw new Error(`Unknown tool: ${tool}`);
+          }
+          const toolDef = this.toolDefinitions.find((t: any) => t.name === tool);
+          const callArgs = spreadArgs(toolDef, args || {});
+          const result = await fn.call(this.photon, ...callArgs);
+          return Response.json({ success: true, data: result }, { headers: CORS_HEADERS });
+        } catch (error: any) {
+          return Response.json(
+            { success: false, error: error.message },
+            { status: 500, headers: CORS_HEADERS }
+          );
+        }
+      }
+    }
+
+    // @get / @post HTTP routes — dispatch to photon method, bypass MCP
+    const httpRoute = this.httpRoutes.find(
+      (r) => r.method === request.method && r.path === url.pathname
+    );
+    if (httpRoute) {
+      const fn = (this.photon as any)[httpRoute.handler];
+      if (typeof fn === 'function') {
+        try {
+          const response = await fn.call(this.photon, request);
+          if (response instanceof Response) return response;
+          return Response.json(response, { headers: CORS_HEADERS });
+        } catch (error: any) {
+          return new Response(error?.message ?? 'Internal Server Error', { status: 500 });
+        }
+      }
+    }
+
+    return new Response('Not Found', { status: 404, headers: CORS_HEADERS });
+  }
+
+  /**
+   * Handle a single POST /mcp body. Distinguishes JSON-RPC requests from
+   * JSON-RPC responses to server-initiated requests, and chooses between a
+   * plain JSON or SSE-streamed reply for tool calls based on the client's
+   * Accept header.
+   */
+  private async _handleMcpPost(request: Request): Promise<Response> {
+    let body: any;
+    try {
+      body = await request.json();
+    } catch (err: any) {
+      return Response.json(
+        {
+          jsonrpc: '2.0',
+          id: null,
+          error: { code: -32700, message: `Parse error: ${err?.message ?? String(err)}` },
+        },
+        { status: 400, headers: CORS_HEADERS }
+      );
+    }
+
+    // JSON-RPC RESPONSE coming back to a server-initiated request: route to
+    // the pending Promise, ack with 204. Distinguished by the absence of
+    // `method` plus a known id in the pending map.
+    if (
+      body &&
+      typeof body === 'object' &&
+      body.method === undefined &&
+      body.id !== undefined &&
+      typeof body.id === 'string' &&
+      this.pendingRequests.has(body.id)
+    ) {
+      const pending = this.pendingRequests.get(body.id)!;
+      this.pendingRequests.delete(body.id);
+      if (body.error) {
+        pending.reject(new Error(body.error.message ?? 'Server-initiated request rejected'));
+      } else {
+        pending.resolve(body.result);
+      }
+      return new Response(null, { status: 204, headers: CORS_HEADERS });
+    }
+
+    // Tool calls from clients that signal SSE support get a streamed
+    // response so this.sample / this.confirm / this.elicit can push
+    // server-initiated requests inline. All other JSON-RPC methods (and
+    // tool calls from JSON-only clients) use the plain JSON path.
+    const accept = request.headers.get('Accept') ?? '';
+    const wantsSse = accept.includes('text/event-stream');
+    if (body?.method === 'tools/call' && wantsSse) {
+      return this._streamToolCall(body);
+    }
+
+    const result = await handleMCPRequest(body, this.photon, this.photonName, this.toolDefinitions);
+    return Response.json(result, { headers: CORS_HEADERS });
+  }
+
+  /**
+   * SSE-stream a tool call response. Sets up the per-request context so
+   * `this.sample` / `this.confirm` / `this.elicit` can push server-initiated
+   * MCP requests over the same stream and await the client's responses
+   * (which arrive as separate POST /mcp requests routed by `_handleMcpPost`).
+   */
+  private _streamToolCall(rpcRequest: any): Response {
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const encoder = new TextEncoder();
+    const send = async (msg: unknown): Promise<void> => {
+      await writer.write(encoder.encode(`data: ${JSON.stringify(msg)}\n\n`));
+    };
+
+    const ctx: RequestContext = {
+      send,
+      pendingRequests: this.pendingRequests,
+    };
+
+    // Fire-and-forget: the response stream stays open as long as the writer
+    // is open, which keeps the DO active until the tool finishes and we
+    // close the writer in `finally`.
+    requestContext
+      .run(ctx, async () => {
+        try {
+          const result = await handleMCPRequest(
+            rpcRequest,
+            this.photon,
+            this.photonName,
+            this.toolDefinitions
+          );
+          await send(result);
+        } catch (err: any) {
+          await send({
+            jsonrpc: '2.0',
+            id: rpcRequest?.id ?? null,
+            error: { code: -32603, message: err?.message ?? String(err) },
+          });
+        }
+      })
+      .finally(() => {
+        writer.close().catch(() => {
+          // Stream already torn down on the client side; nothing to do.
+        });
+      });
+
+    return new Response(readable, {
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        ...CORS_HEADERS,
+      },
+    });
+  }
+
+  async webSocketMessage(_ws: WebSocket, _msg: string | ArrayBuffer): Promise<void> {
+    // Subscribers don't send messages in v1; ignore.
+  }
+
+  async webSocketClose(_ws: WebSocket, _code: number, _reason: string): Promise<void> {
+    // No-op — ctx.getWebSockets() prunes closed sockets.
+  }
+
+  /**
+   * Alarm fired by the DO scheduler. Walk every persisted schedule, dispatch
+   * those that are due, advance bookkeeping, and reschedule the next alarm.
+   * Per-task errors move that task to status='error' without blocking others.
+   */
+  async alarm(): Promise<void> {
+    const tasks = await listSchedules(this.ctx);
+    const now = Date.now();
+    for (const task of tasks) {
+      if (task.status !== 'active') continue;
+      const fromTs = task.lastExecutionAt
+        ? Date.parse(task.lastExecutionAt)
+        : Date.parse(task.createdAt);
+      const due = nextFireMs(task.cron, new Date(fromTs));
+      if (due > now + 1000) continue;
+      try {
+        const fn = (this.photon as any)[task.method];
+        if (typeof fn !== 'function') {
+          throw new Error(`Scheduled method '${task.method}' not found on photon`);
+        }
+        const toolDef = this.toolDefinitions.find((t: any) => t.name === task.method);
+        const callArgs = spreadArgs(toolDef, task.params || {});
+        await fn.call(this.photon, ...callArgs);
+        task.lastExecutionAt = new Date(now).toISOString();
+        task.executionCount += 1;
+        if (
+          task.fireOnce ||
+          (task.maxExecutions > 0 && task.executionCount >= task.maxExecutions)
+        ) {
+          task.status = 'completed';
+        }
+      } catch (err) {
+        task.errorMessage = err instanceof Error ? err.message : String(err);
+        task.status = 'error';
+      }
+      await this.ctx.storage.put(SCHEDULE_PREFIX + task.id, task);
+    }
+    await rescheduleAlarm(this.ctx);
+  }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Generated DO classes — one per photon (host + every @photons sibling)
+// ════════════════════════════════════════════════════════════════════════════
+
+__PHOTON_DO_CLASSES__
+
+// ════════════════════════════════════════════════════════════════════════════
+// Outer Worker — routes every external request to the host photon DO
+// ════════════════════════════════════════════════════════════════════════════
+
+const CF_ACCESS_ENABLED = __CF_ACCESS_ENABLED__;
+
+/**
+ * Pick the photon instance name from (in priority order):
+ *   1. CF Access JWT email — when @auth cf-access is set on the photon
+ *   2. ?instance=<name> query param
+ *   3. X-Photon-Instance header
+ *   4. 'default' singleton
+ *
+ * CF Access verifies the JWT at the edge before the request reaches this
+ * Worker, so we trust the claim without re-verifying the signature here.
+ */
+function extractInstance(request: Request): string {
+  if (CF_ACCESS_ENABLED) {
+    const jwt = request.headers.get('Cf-Access-Jwt-Assertion');
+    if (jwt) {
+      try {
+        const payload = JSON.parse(atob(jwt.split('.')[1]));
+        if (payload?.email) return payload.email as string;
+      } catch {
+        // malformed JWT — fall through to default resolution
+      }
+    }
+  }
+  const url = new URL(request.url);
+  return (
+    url.searchParams.get('instance') ?? request.headers.get('X-Photon-Instance') ?? 'default'
+  );
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method === 'OPTIONS') {
+      return new Response(null, {
+        headers: {
+          'Access-Control-Allow-Origin': '*',
+          'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+          'Access-Control-Allow-Headers':
+            'Content-Type, Mcp-Session-Id, X-Photon-Instance, Upgrade',
+        },
+      });
+    }
+    const instance = extractInstance(request);
+    const id = env.__HOST_BINDING__.idFromName(instance);
+    return env.__HOST_BINDING__.get(id).fetch(request);
+  },
 };
 
-// Playground HTML
-function getPlaygroundHTML(): string {
+// ════════════════════════════════════════════════════════════════════════════
+// Dev playground UI
+// ════════════════════════════════════════════════════════════════════════════
+
+function getPlaygroundHTML(photonName: string, toolDefinitions: any[]): string {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${PHOTON_NAME} - Playground</title>
+  <title>${photonName} - Playground</title>
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     :root { --bg: #0a0a0f; --card: #12121a; --border: #1e1e2e; --text: #e4e4e7; --muted: #71717a; --accent: #6366f1; --green: #22c55e; }
@@ -168,7 +1047,7 @@ function getPlaygroundHTML(): string {
 </head>
 <body>
   <div class="header">
-    <h1>${PHOTON_NAME}</h1>
+    <h1>${photonName}</h1>
     <span class="badge">Cloudflare Workers</span>
   </div>
   <div class="container">
@@ -188,7 +1067,7 @@ function getPlaygroundHTML(): string {
     </div>
   </div>
   <script>
-    const tools = ${JSON.stringify(TOOL_DEFINITIONS)};
+    const tools = ${JSON.stringify(toolDefinitions)};
     let selectedTool = null;
 
     function renderTools() {
@@ -272,89 +1151,3 @@ function getPlaygroundHTML(): string {
 </body>
 </html>`;
 }
-
-// Main fetch handler
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const url = new URL(request.url);
-
-    // CORS preflight
-    if (request.method === 'OPTIONS') {
-      return new Response(null, {
-        headers: {
-          'Access-Control-Allow-Origin': '*',
-          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-          'Access-Control-Allow-Headers': 'Content-Type',
-        },
-      });
-    }
-
-    // Info endpoint
-    if (url.pathname === '/' && request.method === 'GET') {
-      return Response.json({
-        name: PHOTON_NAME,
-        transport: 'streamable-http',
-        runtime: 'cloudflare-workers',
-        endpoints: {
-          mcp: '/mcp',
-          ...(DEV_MODE ? { playground: '/playground' } : {}),
-        },
-        tools: TOOL_DEFINITIONS.length,
-      });
-    }
-
-    // MCP Streamable HTTP: one endpoint, stateless per request.
-    if (url.pathname === '/mcp' && request.method === 'POST') {
-      return handleStreamableMCP(request, env);
-    }
-    if (url.pathname === '/mcp' && request.method === 'GET') {
-      // Spec-compliant no-op: clients that open an SSE stream for server
-      // notifications get a valid empty stream. We do not push anything
-      // server-initiated from a stateless Worker.
-      return new Response(': streamable-http\n\n', {
-        headers: {
-          'Content-Type': 'text/event-stream',
-          'Cache-Control': 'no-cache',
-          ...CORS_HEADERS,
-        },
-      });
-    }
-    if (url.pathname === '/mcp' && request.method === 'DELETE') {
-      // Session termination: stateless, nothing to clean up.
-      return new Response(null, { status: 204, headers: CORS_HEADERS });
-    }
-
-    // Dev-only endpoints
-    if (DEV_MODE) {
-      // Playground
-      if (url.pathname === '/playground') {
-        return new Response(getPlaygroundHTML(), {
-          headers: { 'Content-Type': 'text/html' },
-        });
-      }
-
-      // API: List tools
-      if (url.pathname === '/api/tools') {
-        return Response.json({ tools: TOOL_DEFINITIONS });
-      }
-
-      // API: Call tool
-      if (url.pathname === '/api/call' && request.method === 'POST') {
-        const { tool, args } = await request.json();
-        const photon = getPhoton(env);
-        try {
-          const method = (photon as any)[tool];
-          if (typeof method !== 'function') {
-            throw new Error(`Unknown tool: ${tool}`);
-          }
-          const result = await method.call(photon, args || {});
-          return Response.json({ success: true, data: result });
-        } catch (error: any) {
-          return Response.json({ success: false, error: error.message }, { status: 500 });
-        }
-      }
-    }
-
-    return new Response('Not Found', { status: 404 });
-  },
-};