@portel/photon 1.23.1 → 1.25.0

package/dist/telemetry/context.d.ts

@@ -16,6 +16,15 @@ export interface RequestContext {
     parentTraceparent?: string;
     /** Authenticated caller when available. */
     caller?: CallerInfo;
+    /**
+     * Originating CLI invocation directory, propagated end-to-end across
+     * worker thread and cross-photon-call boundaries. Lets photons resolve
+     * defaults relative to where the user ran the command, not the daemon's
+     * cwd. `process.cwd()` inside a worker is the daemon process's cwd, which
+     * is rarely what the photon author wants. Photons read this back via
+     * `this.callerCwd`.
+     */
+    cwd?: string;
     /** Wall-clock start of the tool call. */
     startedAt: number;
 }

package/dist/telemetry/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/telemetry/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/telemetry/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D"}

package/dist/telemetry/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/telemetry/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAgBrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,MAAM,UAAU,qBAAqB,CAAI,GAAmB,EAAE,EAAW;IACvE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/telemetry/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAyBrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,MAAM,UAAU,qBAAqB,CAAI,GAAmB,EAAE,EAAW;IACvE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon",
-  "version": "1.23.1",
+  "version": "1.25.0",
   "description": "You focus on the business logic. We'll enable the rest. Build MCP servers and CLI tools in a single TypeScript file.",
   "type": "module",
   "main": "dist/index.js",
@@ -113,7 +113,7 @@
     "@modelcontextprotocol/ext-apps": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@portel/cli": "^1.1.0",
-    "@portel/photon-core": "^2.24.0",
+    "@portel/photon-core": "^2.25.0",
     "boxen": "^8.0.1",
     "chalk": "^5.4.1",
     "chart.js": "^4.5.1",
@@ -141,7 +141,7 @@
     "@codemirror/theme-one-dark": "^6.1.3",
     "@codemirror/view": "^6.39.12",
     "@playwright/test": "^1.58.0",
-    "@release-it/conventional-changelog": "^10.0.1",
+    "@release-it/conventional-changelog": "^11.0.0",
     "@types/inquirer": "^9.0.9",
     "@types/node": "^22.10.2",
     "@types/qrcode": "^1.5.6",
@@ -157,7 +157,7 @@
     "openapi-types": "^12.1.3",
     "playwright": "^1.57.0",
     "prettier": "^3.8.0",
-    "release-it": "^19.0.6",
+    "release-it": "^20.0.0",
     "tsx": "^4.20.6",
     "typescript": "^5.7.3"
   },

package/templates/cloudflare/worker.ts.template

@@ -11,13 +11,6 @@ interface Env {
   [key: string]: string | undefined;
 }
 
-type SSESession = {
-  writer: WritableStreamDefaultWriter<Uint8Array>;
-  encoder: TextEncoder;
-};
-
-const sessions = new Map<string, SSESession>();
-
 // Tool definitions extracted at build time
 // @ts-ignore - Will be replaced during build
 const TOOL_DEFINITIONS: any[] = __TOOL_DEFINITIONS__;
@@ -67,11 +60,19 @@ async function handleMCPRequest(request: any, env: Env): Promise<any> {
           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 isString = typeof result === 'string';
+        const text = isString ? result : JSON.stringify(result, null, 2);
+        const isObject = result !== null && typeof result === 'object';
         return {
           jsonrpc: '2.0',
           id,
           result: {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            content: [{ type: 'text', text }],
+            ...(isObject && { structuredContent: result }),
           },
         };
       } catch (error: any) {
@@ -100,66 +101,34 @@ async function handleMCPRequest(request: any, env: Env): Promise<any> {
 }
 
 // SSE stream handler
-async function handleSSE(request: Request, env: Env): Promise<Response> {
-  const sessionId = crypto.randomUUID();
-  const encoder = new TextEncoder();
-
-  const { readable, writable } = new TransformStream();
-  const writer = writable.getWriter();
-
-  sessions.set(sessionId, { writer, encoder });
-
-  // Send session ID
-  await writer.write(encoder.encode(`event: session\ndata: ${JSON.stringify({ sessionId })}\n\n`));
-
-  // Keep-alive
-  const interval = setInterval(async () => {
-    try {
-      await writer.write(encoder.encode(`: keepalive\n\n`));
-    } catch {
-      clearInterval(interval);
-    }
-  }, 30000);
-
-  // Cleanup on close
-  request.signal.addEventListener('abort', () => {
-    clearInterval(interval);
-    sessions.delete(sessionId);
-    writer.close().catch(() => {});
-  });
-
-  return new Response(readable, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-      'Access-Control-Allow-Origin': '*',
-    },
-  });
-}
-
-// Message handler for SSE
-async function handleMessage(request: Request, env: Env): Promise<Response> {
-  const url = new URL(request.url);
-  const sessionId = url.searchParams.get('sessionId');
-
-  if (!sessionId || !sessions.has(sessionId)) {
-    return new Response('Invalid session', { status: 400 });
+/**
+ * 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> {
+  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)}` } },
+      { status: 400, headers: CORS_HEADERS }
+    );
   }
-
-  const session = sessions.get(sessionId)!;
-  const body = await request.json();
-  const response = await handleMCPRequest(body, env);
-
-  // Send response via SSE
-  const data = `event: message\ndata: ${JSON.stringify(response)}\n\n`;
-  await session.writer.write(session.encoder.encode(data));
-
-  return new Response('OK', {
-    headers: { 'Access-Control-Allow-Origin': '*' },
-  });
+  const result = await handleMCPRequest(body, env);
+  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',
+};
+
 // Playground HTML
 function getPlaygroundHTML(): string {
   return `<!DOCTYPE html>
@@ -324,25 +293,35 @@ export default {
     if (url.pathname === '/' && request.method === 'GET') {
       return Response.json({
         name: PHOTON_NAME,
-        transport: 'sse',
+        transport: 'streamable-http',
         runtime: 'cloudflare-workers',
         endpoints: {
-          sse: '/mcp',
-          messages: '/mcp/messages',
+          mcp: '/mcp',
           ...(DEV_MODE ? { playground: '/playground' } : {}),
         },
         tools: TOOL_DEFINITIONS.length,
       });
     }
 
-    // SSE endpoint
+    // 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') {
-      return handleSSE(request, env);
+      // 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,
+        },
+      });
     }
-
-    // Message endpoint
-    if (url.pathname === '/mcp/messages' && request.method === 'POST') {
-      return handleMessage(request, env);
+    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

package/templates/cloudflare/wrangler.toml.template

@@ -1,6 +1,11 @@
 name = "__PHOTON_NAME__"
 main = "src/worker.ts"
-compatibility_date = "2024-01-01"
+# 2024-09-23+ enables the Node.js-style module resolution path so packages
+# that ship distinct browser/node entries (e.g. linkedom inside
+# @extractus/article-extractor) resolve to the Node build instead of a
+# browser build that references `window`.
+compatibility_date = "2024-09-23"
+compatibility_flags = ["nodejs_compat"]
 
 # Uncomment to add environment variables
 # [vars]