@portel/photon 1.23.1 → 1.24.0

package/README.md

@@ -280,6 +280,9 @@ Things you don't build because Photon handles them:
 | **Cross-photon calls** | `this.call()` invokes another photon's methods |
 | **Real-time events** | `this.emit()` fires named events to the browser UI with zero wiring |
 | **Live rendering** | `this.render()` pushes formatted output to CLI and Beam in real time |
+| **Delegated LLM** | `this.sample()` asks the driving agent's model to generate text — no API key, agent pays |
+| **Inline confirm / input** | `this.confirm()` and `this.elicit()` route through the client's native UI (Beam dialog, Claude prompt) |
+| **Scoped remote access** | `photon claim` generates a short-lived code to scope a remote MCP session to one directory |
 | **Standalone binaries** | `photon build` compiles any photon to a single executable via Bun |
 | **Dependency management** | `@dependencies` auto-installs npm packages on first run |
 
@@ -327,6 +330,69 @@ The same pattern applies beyond games: approval workflows where a human reviews
 
 ---
 
+## MCP Primitives on `this`
+
+The MCP protocol's user-facing primitives are surfaced as plain methods
+on every photon instance — no decorators, no capability flags, no SDK
+imports. The runtime routes each call through whichever surface the
+request arrived on (Beam, Claude Desktop, Cursor, CLI).
+
+```typescript
+export default class Editor {
+  async summarize(params: { text: string }) {
+    // Ask the driving agent's LLM. No API key. Agent pays.
+    return await this.sample({
+      prompt: `Summarize in one sentence:\n\n${params.text}`,
+      maxTokens: 128,
+    });
+  }
+
+  async deploy() {
+    if (!(await this.confirm('Ship to production?'))) return;
+    const env = await this.elicit<string>({
+      ask: 'select',
+      message: 'Which environment?',
+      options: ['staging', 'prod'],
+    });
+    await this.run(env);
+  }
+}
+```
+
+| Primitive | What it does |
+|---|---|
+| `await this.sample({ prompt })` | Delegates LLM generation to the caller's model via MCP sampling |
+| `await this.confirm(question)` | Yes/no prompt — returns `boolean` |
+| `await this.elicit(params)` | Arbitrary input (text, select, form, file, etc.) |
+| `this.status(msg)` / `this.progress(v)` | Live feedback during long work |
+
+Full reference: [`docs/reference/MCP-PRIMITIVES.md`](docs/reference/MCP-PRIMITIVES.md).
+
+---
+
+## Remote Access: Claim Codes
+
+By default every installed photon is visible to every connected MCP
+client. When you want to pair a *remote* agent with a *subset* of your
+photons — your phone driving Beam, a teammate reviewing one project,
+a CI agent scoped to a single directory — generate a claim code:
+
+```bash
+$ photon claim --scope /workspace/proj --ttl 4h --label "phone"
+✓ Claim code: R3K-9QZ
+  Scope:      /workspace/proj
+  Expires in: 4h
+```
+
+The remote client presents the code as the `Mcp-Claim-Code` header on
+its MCP session. `tools/list` then only exposes photons whose source
+lives under that directory. Sessions without a code keep full access —
+the feature is strictly opt-in.
+
+Full reference: [`docs/reference/CLAIM-CODES.md`](docs/reference/CLAIM-CODES.md).
+
+---
+
 ## Marketplace
 
 32 photons ready to install: databases, APIs, developer tools, and more.

package/dist/auto-ui/streamable-http-transport.d.ts.map

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

package/dist/auto-ui/streamable-http-transport.js

@@ -38,6 +38,7 @@ import { createTask, getTask, updateTask, listTasks, registerController, unregis
 import { toWireFormat, relatedTaskMeta, TERMINAL_STATES } from '../tasks/types.js';
 import { runTaskExecution, resolveTaskInput, waitForTerminalOrInput } from '../tasks/executor.js';
 import { generateAgentCard } from '../a2a/card-generator.js';
+import { isPathInScope } from '../daemon/claims.js';
 // ════════════════════════════════════════════════════════════════════════════════
 // JWT HELPERS
 // ════════════════════════════════════════════════════════════════════════════════
@@ -73,6 +74,71 @@ function decodeJWTCaller(authHeader) {
 // ════════════════════════════════════════════════════════════════════════════════
 const sessions = new Map();
 const pendingElicitations = new Map();
+const pendingServerRequests = new Map();
+let nextServerRequestId = 1;
+/**
+ * Send a JSON-RPC request to a Beam session over its SSE stream and
+ * await the reply. Backs photon-facing providers (sampling, future
+ * roots/list) that route through the human at the browser.
+ *
+ * 30-min timeout accommodates the sampling-modal's serial queue:
+ * a queued request can sit behind an open modal for the user's full
+ * read+reply time, so 5 min would let entries expire off-screen.
+ */
+function requestSession(sessionId, method, params, timeoutMs = 30 * 60_000) {
+    return new Promise((resolve, reject) => {
+        const session = sessions.get(sessionId);
+        if (!session || !session.sseResponse || session.sseResponse.writableEnded) {
+            reject(new Error(`requestSession: session ${sessionId} has no live SSE stream — the ` +
+                `browser must be connected for server→client requests to work.`));
+            return;
+        }
+        const id = `srv-${nextServerRequestId++}`;
+        const timer = setTimeout(() => {
+            pendingServerRequests.delete(id);
+            reject(new Error(`requestSession: ${method} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        pendingServerRequests.set(id, { resolve, reject, sessionId, timer });
+        const payload = `data: ${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n\n`;
+        try {
+            session.sseResponse.write(payload);
+        }
+        catch (err) {
+            clearTimeout(timer);
+            pendingServerRequests.delete(id);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+/**
+ * Build a sampling provider for a specific Beam session — the
+ * person at the browser plays the role of the LLM. The provider
+ * returns a `CreateMessageResult` shape with `model: 'human@beam'`
+ * so the photon can tell (via the returned model field) that the
+ * response came from a person rather than a real model.
+ */
+function makeHumanSamplingProvider(sessionId) {
+    return async (params) => {
+        const result = (await requestSession(sessionId, 'sampling/createMessage', params));
+        // Defensive normalisation: some clients return just a string;
+        // wrap it in the canonical CreateMessageResult shape so photon-core
+        // can index into content[0].text without extra checks.
+        if (typeof result === 'string') {
+            return {
+                role: 'assistant',
+                content: { type: 'text', text: result },
+                model: 'human@beam',
+                stopReason: 'endTurn',
+            };
+        }
+        return {
+            role: result?.role ?? 'assistant',
+            content: result?.content ?? { type: 'text', text: '' },
+            model: result?.model ?? 'human@beam',
+            stopReason: result?.stopReason ?? 'endTurn',
+        };
+    };
+}
 const APPROVALS_DIR = join(homedir(), '.photon', 'state');
 // Simple async mutex for file operations
 function createMutex() {
@@ -451,6 +517,19 @@ function buildToolResult(result, methodInfo) {
     }
     return toolResult;
 }
+/**
+ * Is the given task visible to this session under its claim scope?
+ * Out-of-scope tasks AND tasks whose photon has been removed are
+ * both hidden, so a stale task can't leak info to a scoped caller.
+ */
+function isTaskInScope(task, scopeDir, photons) {
+    if (!scopeDir)
+        return true;
+    const info = photons.find((p) => p.name === task.photon);
+    if (!info)
+        return false;
+    return isPathInScope(info.path, scopeDir);
+}
 const handlers = {
     // ─────────────────────────────────────────────────────────────────────────────
     // Lifecycle
@@ -777,8 +856,16 @@ const handlers = {
     // ─────────────────────────────────────────────────────────────────────────────
     'tools/list': async (req, session, ctx) => {
         const tools = [];
+        // Claim-code scoping: when the session presented a valid claim on
+        // initialize, only photons whose source file lives under that
+        // directory are visible. Unscoped sessions keep the prior behavior
+        // (every configured photon is listed).
+        const scopeDir = session.claimScopeDir;
+        const visiblePhotons = scopeDir
+            ? ctx.photons.filter((p) => isPathInScope(p.path, scopeDir))
+            : ctx.photons;
         // Add configured photon methods as tools
-        for (const photon of ctx.photons) {
+        for (const photon of visiblePhotons) {
             if (!photon.configured || !photon.methods)
                 continue;
             for (const method of photon.methods) {
@@ -826,7 +913,7 @@ const handlers = {
             }
         }
         // Add runtime-injected instance tools for stateful photons
-        for (const photon of ctx.photons) {
+        for (const photon of visiblePhotons) {
             if (!photon.configured || !photon.stateful)
                 continue;
             tools.push({
@@ -1136,6 +1223,13 @@ const handlers = {
     },
     'tools/call': async (req, session, ctx) => {
         const { name, arguments: args } = req.params;
+        // MCP spec: if the caller supplied `_meta.progressToken`, every
+        // notifications/progress we emit for this request MUST echo that
+        // token so the client can correlate progress events with the
+        // specific in-flight request. Falling back to a synthetic token
+        // stranded progress notifications — clients filtered them out
+        // because no listener was registered for the synthetic key.
+        const clientProgressToken = req.params?._meta?.progressToken;
         // Handle beam system tools
         if (name === 'beam/configure') {
             return handleBeamConfigure(req, ctx, args || {});
@@ -1189,6 +1283,30 @@ const handlers = {
         const methodName = name.slice(slashIndex + 1);
         // Per-photon auth check: if this photon requires auth but caller is anonymous, reject
         const targetPhoton = ctx.photons.find((p) => p.name === serverName);
+        // Claim-code scope enforcement: filtering tools/list alone is not a
+        // gate — a caller that knows a tool name (cached from before the
+        // claim was scoped, or inferred) could still invoke it via
+        // tools/call. Every call therefore re-checks scope against the
+        // session's `claimScopeDir`. Unscoped sessions bypass this check.
+        if (session.claimScopeDir) {
+            if (!targetPhoton || !isPathInScope(targetPhoton.path, session.claimScopeDir)) {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    result: {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Tool ${name} is not available in the current claim scope. ` +
+                                    `The claim code presented on this session only grants access to photons ` +
+                                    `under ${session.claimScopeDir}.`,
+                            },
+                        ],
+                        isError: true,
+                    },
+                };
+            }
+        }
         if (targetPhoton?.configured && targetPhoton.auth === 'required') {
             if (!ctx.caller || ctx.caller.anonymous) {
                 return {
@@ -1504,12 +1622,17 @@ const handlers = {
             const task = createTask(photonName, methodName, args, ttl);
             const controller = new AbortController();
             registerController(task.id, controller);
-            // Build execution function that the executor will run
+            // Build execution function that the executor will run.
+            // Same human-sampling provider shape as the sync path — scoped
+            // to the session that kicked off the task so the modal appears
+            // in the right browser tab.
             const executeFn = async (inputProvider, outputHandler) => {
                 if (ctx.loader) {
+                    const samplingProvider = makeHumanSamplingProvider(session.id);
                     return ctx.loader.executeTool(mcp, methodName, args || {}, {
                         outputHandler,
                         inputProvider,
+                        samplingProvider,
                         caller: ctx.caller,
                     });
                 }
@@ -1550,6 +1673,12 @@ const handlers = {
             const outputHandler = (yieldValue) => {
                 if (!ctx.broadcast)
                     return;
+                // Echo the caller's progressToken when supplied so the client
+                // can route notifications back to the originating panel. Fall
+                // back to the synthetic `progress_<photon>_<method>` only when
+                // the caller didn't send one (e.g. server-initiated task
+                // progress with no user request to correlate against).
+                const progressToken = clientProgressToken ?? `progress_${photonName}_${methodName}`;
                 // Forward progress events as MCP notifications
                 if (yieldValue?.emit === 'progress') {
                     const rawValue = typeof yieldValue.value === 'number' ? yieldValue.value : 0;
@@ -1558,7 +1687,7 @@ const handlers = {
                         jsonrpc: '2.0',
                         method: 'notifications/progress',
                         params: {
-                            progressToken: `progress_${photonName}_${methodName}`,
+                            progressToken,
                             progress,
                             total: 100,
                             message: yieldValue.message || null,
@@ -1572,7 +1701,7 @@ const handlers = {
                         jsonrpc: '2.0',
                         method: 'notifications/progress',
                         params: {
-                            progressToken: `progress_${photonName}_${methodName}`,
+                            progressToken,
                             progress: 0,
                             total: 100,
                             message: yieldValue.message || '',
@@ -1747,13 +1876,23 @@ const handlers = {
                 });
             };
             // Use loader.executeTool if available (sets up execution context for this.emit())
-            // Fall back to direct method call for backward compatibility
+            // Fall back to direct method call for backward compatibility.
+            //
+            // Build a samplingProvider that forwards `sampling/createMessage`
+            // to the Beam session driving this call. The browser's request
+            // handler (src/auto-ui/frontend/components/sampling-modal.ts)
+            // pops a modal, the human types a response, and that text flows
+            // back as the photon's `this.sample()` return value. Declaring
+            // `sampling: {}` on the client without this provider would let
+            // the photon hang — the earlier codex P1 finding.
             let result;
             const startTime = Date.now();
             if (ctx.loader) {
+                const samplingProvider = makeHumanSamplingProvider(session.id);
                 result = await ctx.loader.executeTool(mcp, methodName, args || {}, {
                     outputHandler,
                     inputProvider,
+                    samplingProvider,
                     caller: ctx.caller,
                 });
             }
@@ -2086,6 +2225,24 @@ const handlers = {
                 error: { code: -32602, message: 'Missing required params: photon, method' },
             };
         }
+        // Claim-code scope enforcement on the async task API. tools/call
+        // has the same gate at the sync path; without this, a scoped
+        // client could bypass scope by starting work via tasks/create.
+        if (session.claimScopeDir) {
+            const targetInfo = ctx.photons.find((p) => p.name === photonName);
+            if (!targetInfo || !isPathInScope(targetInfo.path, session.claimScopeDir)) {
+                return {
+                    jsonrpc: '2.0',
+                    id: req.id,
+                    error: {
+                        code: -32602,
+                        message: `Photon ${photonName} is not available in the current claim scope. ` +
+                            `The claim code presented on this session only grants access to photons ` +
+                            `under ${session.claimScopeDir}.`,
+                    },
+                };
+            }
+        }
         const mcp = ctx.photonMCPs.get(photonName);
         if (!mcp?.instance) {
             return {
@@ -2121,7 +2278,7 @@ const handlers = {
             result: { task: toWireFormat(task) },
         };
     },
-    'tasks/get': async (req, _session, _ctx) => {
+    'tasks/get': async (req, session, ctx) => {
         const { taskId } = req.params;
         if (!taskId) {
             return {
@@ -2131,7 +2288,11 @@ const handlers = {
             };
         }
         const task = getTask(taskId);
-        if (!task) {
+        // Scope-gated: a scoped session sees "not found" whether the task
+        // is truly absent or simply out of scope. Collapsing both cases
+        // into the same response avoids leaking existence to callers
+        // that shouldn't see this photon.
+        if (!task || !isTaskInScope(task, session.claimScopeDir, ctx.photons)) {
             return {
                 jsonrpc: '2.0',
                 id: req.id,
@@ -2140,9 +2301,14 @@ const handlers = {
         }
         return { jsonrpc: '2.0', id: req.id, result: toWireFormat(task) };
     },
-    'tasks/list': async (req, _session, _ctx) => {
+    'tasks/list': async (req, session, ctx) => {
         const { cursor } = (req.params || {});
-        const allTasks = listTasks();
+        let allTasks = listTasks();
+        // Filter scoped sessions before paginating so the cursor indexes
+        // align with what the caller actually sees.
+        if (session.claimScopeDir) {
+            allTasks = allTasks.filter((t) => isTaskInScope(t, session.claimScopeDir, ctx.photons));
+        }
         // Simple pagination: cursor is the offset index
         const offset = cursor ? parseInt(cursor, 10) || 0 : 0;
         const pageSize = 50;
@@ -2157,7 +2323,7 @@ const handlers = {
             },
         };
     },
-    'tasks/cancel': async (req, _session, _ctx) => {
+    'tasks/cancel': async (req, session, ctx) => {
         const { taskId } = req.params;
         if (!taskId) {
             return {
@@ -2167,7 +2333,7 @@ const handlers = {
             };
         }
         const task = getTask(taskId);
-        if (!task) {
+        if (!task || !isTaskInScope(task, session.claimScopeDir, ctx.photons)) {
             return {
                 jsonrpc: '2.0',
                 id: req.id,
@@ -2201,7 +2367,7 @@ const handlers = {
             };
         }
         const task = getTask(taskId);
-        if (!task) {
+        if (!task || !isTaskInScope(task, session.claimScopeDir, ctx.photons)) {
             return {
                 jsonrpc: '2.0',
                 id: req.id,
@@ -3308,7 +3474,7 @@ export async function handleStreamableHTTP(req, res, options) {
     // CORS headers
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Mcp-Session-Id, Authorization');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Mcp-Session-Id, Mcp-Claim-Code, Authorization');
     res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
     // Handle preflight
     if (req.method === 'OPTIONS') {
@@ -3348,6 +3514,39 @@ export async function handleStreamableHTTP(req, res, options) {
         sessionId = url.searchParams.get('sessionId') || undefined;
     }
     const session = getOrCreateSession(sessionId);
+    // Claim-code scoping: if the client presents `Mcp-Claim-Code` (header
+    // or query param for SSE), validate it on EVERY request and stamp
+    // the allowed scopeDir onto the session. Re-validating per request
+    // (rather than once at session init) means revoke + TTL expiry take
+    // effect immediately on the next call — otherwise a scoped session
+    // keeps its access after `photon claim revoke` or TTL, which would
+    // defeat the point of short-lived codes.
+    //
+    // Absent or invalid codes leave the session unscoped (full access) —
+    // claims are strictly additive, never a gate on unclaimed sessions.
+    // See `src/daemon/claims.ts` for the store and the scoping contract.
+    {
+        const rawCode = req.headers['mcp-claim-code'] ||
+            url.searchParams.get('claim') ||
+            undefined;
+        if (rawCode) {
+            try {
+                const { validateClaimSync } = await import('../daemon/claims.js');
+                const result = validateClaimSync(rawCode);
+                session.claimScopeDir = result.ok ? result.claim.scopeDir : undefined;
+            }
+            catch {
+                // Claim store unreadable — fall through to unscoped access so
+                // we don't hard-break when `.data/claims.json` is missing.
+                session.claimScopeDir = undefined;
+            }
+        }
+        else if (session.claimScopeDir) {
+            // Session was previously scoped but the client stopped sending
+            // the code. Treat the missing header as revocation.
+            session.claimScopeDir = undefined;
+        }
+    }
     // GET - Open SSE stream for server notifications
     if (req.method === 'GET') {
         const accept = req.headers.accept || '';
@@ -3369,13 +3568,15 @@ export async function handleStreamableHTTP(req, res, options) {
         res.socket?.setKeepAlive(true, 60000);
         // Store SSE response for server-initiated messages
         session.sseResponse = res;
-        // Keep connection alive with SSE data events (every 15s for better reliability)
+        // Keep connection alive with SSE comments (every 15s). Comments are
+        // silently dropped by all spec-compliant parsers including the MCP
+        // SDK's EventSourceParserStream, so they don't clutter JSON-RPC
+        // message routing. Prevents intermediary proxies (nginx) from closing
+        // idle connections.
         const keepAlive = setInterval(() => {
-            // Check if response is still writable before sending keepalive
             if (!res.writableEnded && !res.destroyed) {
                 try {
-                    // Send as data event so client onmessage handler fires and updates lastMessageTime
-                    res.write('data: {"type":"keepalive"}\n\n');
+                    res.write(': keepalive\n\n');
                 }
                 catch (err) {
                     // If write fails, connection is dead - clean up
@@ -3391,6 +3592,21 @@ export async function handleStreamableHTTP(req, res, options) {
         const cleanup = () => {
             clearInterval(keepAlive);
             session.sseResponse = undefined;
+            // Reject any server→client requests still waiting on this
+            // session. Without this, a disconnect during `sampling/createMessage`
+            // leaves the pending entry alive until the 5-minute timeout,
+            // and because Beam's sampling-modal serializes via a single
+            // inFlight promise, the queue wedges for every later request
+            // in that tab. Each pending entry carries the originating
+            // sessionId so we can target precisely this session's work.
+            for (const [id, pending] of pendingServerRequests) {
+                if (pending.sessionId !== session.id)
+                    continue;
+                if (pending.timer)
+                    clearTimeout(pending.timer);
+                pendingServerRequests.delete(id);
+                pending.reject(new Error(`requestSession: session ${session.id} disconnected before response`));
+            }
             // Clean up subscriptions when client disconnects
             if (options.subscriptionManager) {
                 options.subscriptionManager.onClientDisconnect(session.id);
@@ -3444,6 +3660,34 @@ export async function handleStreamableHTTP(req, res, options) {
         // Process requests
         const responses = [];
         for (const request of requests) {
+            // Response to a server→client request: no method, has id, has
+            // either result or error. Route to the pending-request map so
+            // the samplingProvider / future server-initiated primitives see
+            // the browser's reply. These never produce an outgoing response.
+            //
+            // SECURITY: the reply's session MUST match the session that
+            // originated the server→client request. Ids are globally
+            // monotonic (`srv-1`, `srv-2`, ...), so without a session cross
+            // check, session A could POST a reply carrying session B's id
+            // and inject a fabricated sampling result into B's photon.
+            // Drop mismatched replies silently — the original timeout on
+            // the pending entry stays the only way to fail legitimately.
+            if (!request.method && request.id !== undefined) {
+                const msg = request;
+                const pending = pendingServerRequests.get(msg.id);
+                if (pending && pending.sessionId === session.id) {
+                    if (pending.timer)
+                        clearTimeout(pending.timer);
+                    pendingServerRequests.delete(msg.id);
+                    if (msg.error) {
+                        pending.reject(new Error(msg.error.message || 'server→client request failed'));
+                    }
+                    else {
+                        pending.resolve(msg.result);
+                    }
+                }
+                continue;
+            }
             const handler = handlers[request.method];
             if (!handler) {
                 if (request.id !== undefined) {