@portel/photon 1.28.2 → 1.31.0

package/dist/runtime/cf-local.js

@@ -0,0 +1,406 @@
+/**
+ * Local Cloudflare runtime adapter for the new `Cloudflare` injection
+ * surface. Backs `private cf: Cloudflare` constructor params (and the
+ * forgiving auto-inject path for plain classes that reference
+ * `this.cf.*`) with a miniflare sandbox when a photon runs outside a
+ * deployed Worker.
+ *
+ * Auto-naming rule (single source of truth — `bindingNameFor`):
+ *   cf.kv()        → <photon>_kv
+ *   cf.kv('x')     → <photon>_x_kv
+ *   cf.ai          → AI         (shared, single per Worker)
+ *   cf.images      → IMAGES     (shared)
+ *   cf.browser     → BROWSER    (shared)
+ *
+ * Photons no longer pick global binding names. The framework derives
+ * them from the photon name plus an optional qualifier so per-photon
+ * resources never collide.
+ *
+ * Boot is keyed off the `cf-usage-scanner` output: every literal
+ * qualifier the photon uses is configured in miniflare up front, so
+ * the first call to a binding doesn't pay a reconfigure cost. Dynamic
+ * qualifiers (`cf.kv(this.tenantId)`) only get the default binding
+ * unless the author lists overrides in `protected cfBindings`.
+ *
+ * Storage persists under `<baseDir>/.data/cf-sandbox/<photon>/` so
+ * state survives process restarts and matches the Phase A2 layout.
+ */
+import * as path from 'path';
+import { bindingNameFor, } from '@portel/photon-core';
+import { expandScopedBindingNames } from '../cf-usage-scanner.js';
+/**
+ * Merge two CfBindingsConfig blobs. Used by the deploy pipeline to
+ * stack a per-photon override JSON on top of in-source declarations.
+ * Boolean shared flags are last-write-wins; per-binding records merge
+ * key-by-key.
+ */
+export function mergeBindings(base, override) {
+    const merged = { ...(base ?? {}) };
+    if (!override)
+        return merged;
+    for (const cat of ['kv', 'r2', 'queue', 'vectorize']) {
+        const ov = override[cat];
+        if (ov) {
+            merged[cat] = { ...(merged[cat] ?? {}), ...ov };
+        }
+    }
+    if (override.d1) {
+        merged.d1 = { ...(merged.d1 ?? {}), ...override.d1 };
+    }
+    for (const cat of ['ai', 'images', 'browser']) {
+        if (typeof override[cat] === 'boolean')
+            merged[cat] = override[cat];
+    }
+    return merged;
+}
+const SCOPED = ['kv', 'r2', 'd1', 'queue', 'vectorize'];
+const SHARED_BINDING_NAMES = {
+    ai: 'AI',
+    images: 'IMAGES',
+    browser: 'BROWSER',
+};
+export class CFLocalRuntime {
+    mfPromise = null;
+    photonName;
+    baseDir;
+    usage;
+    overrides;
+    /**
+     * Legacy mode means the photon was constructed via the Phase-A2
+     * positional `(name, cfBindings, baseDir)` form. In that mode the
+     * `qualifier` arg passed to `cf.kv(...)` etc. is treated as a
+     * literal binding name (not run through `bindingNameFor`), and
+     * miniflare seeds the names declared in `overrides.<category>`.
+     * The new options-form constructor flips this to false and the
+     * auto-naming convention takes over.
+     */
+    legacyMode;
+    legacyBooleanFlags;
+    constructor(optsOrName, legacyBindings, legacyBaseDir) {
+        if (typeof optsOrName === 'string') {
+            this.photonName = optsOrName;
+            this.baseDir = legacyBaseDir ?? '';
+            this.usage = null;
+            this.overrides = legacyBindings ?? {};
+            this.legacyMode = true;
+            this.legacyBooleanFlags = {
+                ai: legacyBindings?.ai === true,
+                images: legacyBindings?.images === true,
+                browser: legacyBindings?.browser === true,
+            };
+        }
+        else {
+            this.photonName = optsOrName.photonName;
+            this.baseDir = optsOrName.baseDir;
+            this.usage = optsOrName.usage ?? null;
+            this.overrides = optsOrName.overrides ?? {};
+            this.legacyMode = false;
+            this.legacyBooleanFlags = { ai: false, images: false, browser: false };
+        }
+    }
+    /** Legacy alias retained for callers that built against the Phase-A2 API. */
+    getBindings() {
+        return this.overrides;
+    }
+    /** Inspector for tools/CLI: lists every binding miniflare seeded. */
+    getSeededBindings() {
+        const out = {};
+        if (this.legacyMode) {
+            // Legacy: seed exactly what `cfBindings` declared, no auto-naming.
+            for (const cat of SCOPED) {
+                const declared = this.overrides[cat];
+                if (!declared) {
+                    out[cat] = [];
+                    continue;
+                }
+                out[cat] = Object.keys(declared);
+            }
+            return out;
+        }
+        if (!this.usage) {
+            for (const cat of SCOPED)
+                out[cat] = [bindingNameFor(this.photonName, cat)];
+            return out;
+        }
+        return expandScopedBindingNames(this.photonName, this.usage);
+    }
+    /**
+     * Resolve the miniflare binding name for a `cf.<cat>(qualifier?)`
+     * call. In auto-naming mode runs through `bindingNameFor`; in
+     * legacy mode treats the arg as a literal binding name (matching
+     * the Phase-A2 `cf.kv(name)` semantics).
+     */
+    resolveBindingName(category, qualifier) {
+        if (this.legacyMode) {
+            // Legacy callers pass the binding name directly. Empty / missing
+            // is invalid in this mode (the old API required a name).
+            if (!qualifier) {
+                throw new Error(`cf.${category}() in legacy mode requires the binding name as an argument ` +
+                    `(e.g. cf.${category}('cache')). Migrate to the new options-object ` +
+                    `constructor to use auto-naming.`);
+            }
+            return qualifier;
+        }
+        return bindingNameFor(this.photonName, category, qualifier);
+    }
+    async dispose() {
+        if (this.mfPromise) {
+            const mf = await this.mfPromise;
+            await mf.dispose();
+            this.mfPromise = null;
+        }
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Cloudflare interface — scoped categories with auto-naming
+    // ────────────────────────────────────────────────────────────────
+    kv(qualifier) {
+        return this.scopedBinding('kv', qualifier, ['get', 'put', 'delete', 'list']);
+    }
+    r2(qualifier) {
+        return this.scopedBinding('r2', qualifier, [
+            'head',
+            'get',
+            'put',
+            'delete',
+            'list',
+        ]);
+    }
+    d1(qualifier) {
+        const name = this.resolveBindingName('d1', qualifier);
+        const get = this.getMiniflare.bind(this);
+        return {
+            prepare: (query) => makeD1PreparedStatement(get, name, query, []),
+            batch: async (statements) => {
+                const mf = await get();
+                const db = (await mf.getD1Database(name));
+                const real = await Promise.all(statements.map(async (s) => {
+                    const candidate = s._materialize;
+                    return candidate ? candidate() : s;
+                }));
+                return db.batch(real);
+            },
+            exec: async (query) => {
+                const mf = await get();
+                const db = (await mf.getD1Database(name));
+                return db.exec(query);
+            },
+            dump: async () => {
+                const mf = await get();
+                const db = (await mf.getD1Database(name));
+                return db.dump();
+            },
+        };
+    }
+    queue(qualifier) {
+        return this.scopedBinding('queue', qualifier, ['send', 'sendBatch']);
+    }
+    vectorize(qualifier) {
+        return this.envBindingProxy(this.resolveBindingName('vectorize', qualifier), [
+            'insert',
+            'upsert',
+            'query',
+            'getByIds',
+            'deleteByIds',
+        ]);
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Cloudflare interface — shared categories (single per Worker)
+    // ────────────────────────────────────────────────────────────────
+    get ai() {
+        const enabled = this.usage?.shared.ai === true || this.legacyBooleanFlags.ai;
+        if (!enabled) {
+            return throwingShared('ai', 'reference this.cf.ai (or cf.ai) somewhere in the photon to enable');
+        }
+        return this.envBindingProxy(SHARED_BINDING_NAMES.ai, ['run']);
+    }
+    get images() {
+        const enabled = this.usage?.shared.images === true || this.legacyBooleanFlags.images;
+        if (!enabled) {
+            return throwingShared('images', 'reference this.cf.images (or cf.images) somewhere in the photon to enable');
+        }
+        return this.envBindingProxy(SHARED_BINDING_NAMES.images, [
+            'info',
+            'input',
+        ]);
+    }
+    get browser() {
+        return throwingShared('browser', 'browser rendering requires a Chromium dep and is deferred until a photon dogfoods it');
+    }
+    fetch(_input, _init) {
+        return Promise.reject(new Error('cf.fetch() — not yet supported on the local sandbox. Service-binding ' +
+            'fetch lands with the deploy adapter; until then, use plain `fetch()` ' +
+            'or wire the photon up to a deployed Worker.'));
+    }
+    // ────────────────────────────────────────────────────────────────
+    // Internals
+    // ────────────────────────────────────────────────────────────────
+    /** Lazily boot a Miniflare instance scoped to this photon. */
+    getMiniflare() {
+        if (!this.mfPromise) {
+            this.mfPromise = (async () => {
+                const { Miniflare } = await import('miniflare');
+                const sandbox = path.join(this.baseDir, '.data', 'cf-sandbox', this.photonName);
+                const seeded = this.getSeededBindings();
+                const options = {
+                    modules: true,
+                    script: 'export default { async fetch() { return new Response("noop"); } };',
+                };
+                if (seeded.kv.length > 0) {
+                    options.kvNamespaces = seeded.kv;
+                    options.kvPersist = path.join(sandbox, 'kv');
+                }
+                if (seeded.r2.length > 0) {
+                    options.r2Buckets = seeded.r2;
+                    options.r2Persist = path.join(sandbox, 'r2');
+                }
+                if (seeded.d1.length > 0) {
+                    options.d1Databases = seeded.d1;
+                    options.d1Persist = path.join(sandbox, 'd1');
+                }
+                if (seeded.queue.length > 0) {
+                    const producers = {};
+                    for (const bindingName of seeded.queue) {
+                        // Local sandbox: queue name == binding name. Overrides only
+                        // come into play at deploy time.
+                        producers[bindingName] = { queueName: bindingName };
+                    }
+                    options.queueProducers = producers;
+                }
+                if (seeded.vectorize.length > 0) {
+                    const indices = {};
+                    for (const bindingName of seeded.vectorize) {
+                        indices[bindingName] = { indexName: bindingName };
+                    }
+                    options.vectorize = indices;
+                }
+                if (this.usage?.shared.ai) {
+                    options.ai = { binding: SHARED_BINDING_NAMES.ai };
+                }
+                if (this.usage?.shared.images) {
+                    options.images = { binding: SHARED_BINDING_NAMES.images };
+                }
+                // browser intentionally omitted — see `get browser` deferral.
+                return new Miniflare(options);
+            })();
+        }
+        return this.mfPromise;
+    }
+    /**
+     * Build a thin proxy whose methods defer to a binding fetched via
+     * `mf.getKVNamespace(name)` / `mf.getR2Bucket(name)` / etc on first
+     * invocation. Avoids paying the boot cost on cold paths.
+     */
+    scopedBinding(category, qualifier, methods) {
+        const name = this.resolveBindingName(category, qualifier);
+        const dynamicCategory = this.usage?.dynamicQualifiers.has(category);
+        const knownNames = new Set(this.getSeededBindings()[category]);
+        if (!knownNames.has(name) && !dynamicCategory) {
+            throw new Error(`cf.${category}(${qualifier ? JSON.stringify(qualifier) : ''}) on ` +
+                `${this.photonName} resolves to binding "${name}", which the runtime ` +
+                `did not seed. Either reference this binding with a literal qualifier ` +
+                `somewhere in your photon source (the boot scanner only sees literals), ` +
+                `or add a "${category}" override to \`protected cfBindings\`.`);
+        }
+        const get = this.getMiniflare.bind(this);
+        const out = {};
+        for (const method of methods) {
+            out[method] = async (...args) => {
+                const mf = await get();
+                const binding = await getMiniflareBinding(mf, category, name);
+                const fn = binding[method];
+                if (typeof fn !== 'function') {
+                    throw new Error(`Miniflare binding "${name}" has no method "${method}" (category=${category}).`);
+                }
+                return fn.apply(binding, args);
+            };
+        }
+        return out;
+    }
+    /**
+     * Pull a binding off the miniflare-built env (for AI, Vectorize,
+     * Images — categories that surface as env props rather than via a
+     * dedicated `mf.getXxx(name)` accessor).
+     */
+    envBindingProxy(bindingName, methods) {
+        const get = this.getMiniflare.bind(this);
+        const out = {};
+        for (const method of methods) {
+            out[method] = async (...args) => {
+                const mf = await get();
+                const env = await mf.getBindings();
+                const binding = env[bindingName];
+                if (!binding) {
+                    throw new Error(`Miniflare has no binding named '${bindingName}' (photon=${this.photonName}).`);
+                }
+                return binding[method].apply(binding, args);
+            };
+        }
+        return out;
+    }
+}
+async function getMiniflareBinding(mf, category, name) {
+    // Each miniflare accessor is typed for its specific binding; the
+    // `as never` cast keeps the dispatcher concise without giving up
+    // the runtime guarantee that `name` is one of the configured
+    // bindings (the dispatcher gate above ensures this).
+    switch (category) {
+        case 'kv':
+            return mf.getKVNamespace(name);
+        case 'r2':
+            return mf.getR2Bucket(name);
+        case 'd1':
+            return mf.getD1Database(name);
+        case 'queue':
+            return mf.getQueueProducer(name);
+        case 'vectorize': {
+            const env = await mf.getBindings();
+            return env[name];
+        }
+    }
+}
+function throwingShared(category, hint) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Proxy(Object.create(null), {
+        get(_target, prop) {
+            throw new Error(`cf.${category}.${String(prop)} — ${hint}.`);
+        },
+    });
+}
+/**
+ * Build a chainable D1 prepared-statement proxy that mirrors
+ * `D1PreparedStatement.bind(...).first/all/run/raw()` semantics. We
+ * accumulate the bind list on the proxy and materialize the real
+ * statement only when a terminal method runs.
+ */
+function makeD1PreparedStatement(get, dbName, query, bound) {
+    const materialize = async () => {
+        const mf = await get();
+        const db = (await mf.getD1Database(dbName));
+        const stmt = db.prepare(query);
+        if (bound.length > 0)
+            return stmt.bind(...bound);
+        return stmt;
+    };
+    const proxy = {
+        bind: (...values) => makeD1PreparedStatement(get, dbName, query, [...bound, ...values]),
+        first: async (colName) => {
+            const real = (await materialize());
+            return real.first(colName);
+        },
+        run: async () => {
+            const real = (await materialize());
+            return real.run();
+        },
+        all: async () => {
+            const real = (await materialize());
+            return real.all();
+        },
+        raw: async () => {
+            const real = (await materialize());
+            return real.raw();
+        },
+        _materialize: materialize,
+    };
+    return proxy;
+}
+//# sourceMappingURL=cf-local.js.map

package/dist/runtime/cf-local.js.map

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

package/dist/server.d.ts

@@ -62,6 +62,14 @@ export interface PhotonServerOptions {
     };
     /** Embedded @ui HTML templates: photonName → { assetId → html content } */
     embeddedUITemplates?: Record<string, Record<string, string>>;
+    /**
+     * Embedded asset tree for `<photon>/<name>/assets/**` (v1.29 Track E).
+     * Shape: photonName → { relativePath → utf-8 content }. Consumed by the
+     * directory-style serving path so SPA chunks (sibling JS/CSS next to a
+     * declared @ui index.html) resolve in standalone binaries without a
+     * filesystem lookup.
+     */
+    embeddedAssetTree?: Record<string, Record<string, string>>;
     /** Channel mode — declares channel capabilities for target clients */
     channelMode?: boolean;
     /** Channel name — becomes the MCP server name and <channel source="name"> */
@@ -91,6 +99,26 @@ export declare class PhotonServer {
     private daemonInstanceName?;
     /** Tracked instance names per SSE session for daemon drift recovery */
     private sseInstanceNames;
+    /**
+     * Track C closure: per-claim instance pool. Populated lazily on first
+     * request from a new authenticated caller when the photon declares
+     * `@stateful` + `@auth`. Without this, every authenticated caller
+     * shares `this.mcp.instance` — meaning two users on the standalone
+     * HTTP server race on the same `this.tasks` / `this.memory`.
+     *
+     * Daemon path doesn't need this — it has its own per-instance loader
+     * (`session-manager.ts`). Cloudflare doesn't need it either — the
+     * outer Worker selects a DO per claim before the request arrives.
+     * This pool is the standalone HTTP server's equivalent.
+     */
+    private instancePool;
+    /**
+     * True iff the loaded photon declares both `@stateful` and `@auth` —
+     * the only shape that actually wants per-caller state isolation. For
+     * everything else, instance routing is a no-op and `this.mcp` is used
+     * directly.
+     */
+    private requiresInstanceRouting;
     /** Whether client capabilities have been logged (one-time on first tools/list) */
     private clientCapabilitiesLogged;
     /** Client capability detection and negotiation */
@@ -98,9 +126,60 @@ export declare class PhotonServer {
     /** Write queue for serialized STDIO notifications (prevents interleaving from concurrent generators) */
     private _notifyQueue;
     /** Compatibility alias for tests that seed raw capabilities directly on PhotonServer */
-    rawClientCapabilities: WeakMap<Server, Record<string, any>>;
+    rawClientCapabilities: WeakMap<Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>, Record<string, any>>;
     /** Resource listing, reading, and asset serving */
     private resourceServer;
+    /**
+     * Server-wide registry of `resources/subscribe` state. The STDIO server
+     * registers one persistent sink; each SSE session registers a per-session
+     * sink at connect and clears its subscriptions at close.
+     */
+    private subscriptions;
+    /** Stable sink for the STDIO server, registered once on first subscribe. */
+    private stdioSink?;
+    /**
+     * Per-server roots cache. Populated on `oninitialized` if the client
+     * declared the `roots` capability, refreshed on
+     * `notifications/roots/list_changed`. Read at tool-call time and threaded
+     * into ALS so `this.roots` resolves synchronously inside photon code.
+     *
+     * WeakMap-keyed so dead session servers stop holding cache entries
+     * automatically when SSE sessions disconnect.
+     */
+    private rootsByServer;
     private currentStatus;
     private logger;
     /** Get the loaded photon (available after start()) */
@@ -163,6 +242,22 @@ export declare class PhotonServer {
      */
     private resolveChoiceFromFields;
     private handleListTools;
+    /**
+     * Resolve which photon instance handles this call. For `@stateful` +
+     * `@auth` photons we pull claims from the request's `authInfo.extra`
+     * (populated by `BeamCompatTransport` from the HTTP headers), look up
+     * the binding rule from the `@auth` directive, and lazy-load a fresh
+     * photon instance keyed by that claim value. Subsequent calls from
+     * the same caller reuse the cached instance so `this.memory` /
+     * `this.tasks` persist across requests within their per-user scope.
+     *
+     * Returns `this.mcp` (the shared singleton) when the photon doesn't
+     * declare per-caller routing, when claims are missing, or when the
+     * binding rule yields no instance name. The fallback is intentional:
+     * unauthenticated requests still execute, they just share the default
+     * instance — same as a v1.28 photon would.
+     */
+    private resolveInstanceMcp;
     private handleCallTool;
     private handleListPrompts;
     private handleGetPrompt;
@@ -170,6 +265,19 @@ export declare class PhotonServer {
      * Set up MCP protocol handlers (STDIO transport)
      */
     private setupHandlers;
+    /**
+     * Wire up `roots/list` discovery + `notifications/roots/list_changed`
+     * refresh for one Server instance. Called once for the STDIO server and
+     * once per SSE session.
+     *
+     * Eager fetch on initialize keeps `this.roots` synchronous inside photon
+     * code — clients that don't declare the capability skip the fetch
+     * entirely. The cache is server-scoped (per-session for SSE) so two
+     * clients with different working directories don't see each other's
+     * roots.
+     */
+    private setupRootsForServer;
+    private refreshRootsCache;
     /**
      * Format tool result as text
      */
@@ -217,9 +325,16 @@ export declare class PhotonServer {
      */
     start(): Promise<void>;
     /**
-     * Start server with stdio transport
+     * Start server with stdio transport.
+     * @param webPort - when set, start a companion HTTP server on this port
+     *                  to serve @get/@post web routes for stateful photons.
      */
     private startStdio;
+    /**
+     * Dispatch an incoming HTTP request to the photon's @get/@post web routes.
+     * Used by the companion HTTP server that runs alongside STDIO stateful photons.
+     */
+    private handleWebRoute;
     /**
      * Start server with SSE transport (HTTP)
      */

package/dist/server.d.ts.map

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