@portel/photon 1.19.0 → 1.20.0

package/dist/capability-negotiator.d.ts

@@ -0,0 +1,67 @@
+/**
+ * CapabilityNegotiator — client capability detection and negotiation
+ *
+ * Encapsulates the logic for detecting what an MCP client supports
+ * (UI rendering, elicitation, etc.) based on the initialize handshake.
+ *
+ * The MCP SDK's Zod schema strips unknown fields like `extensions`
+ * (protocol 2025-11-25+), so we also capture raw capabilities from
+ * the JSON-RPC initialize message before Zod parsing occurs.
+ */
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare class CapabilityNegotiator {
+    /**
+     * Raw client capabilities captured from the initialize request BEFORE Zod parsing.
+     *
+     * The MCP SDK uses Zod to validate incoming requests, which strips unknown fields
+     * from ClientCapabilities. Notably, `extensions` (protocol 2025-11-25+) is not in
+     * the SDK's Zod schema yet, so `getClientCapabilities()` returns an object without
+     * it. Real clients like Claude Desktop and ChatGPT send UI capability under
+     * `extensions`, not `experimental`. We intercept the raw JSON-RPC message to
+     * capture the full capabilities before Zod strips them.
+     *
+     * Key: Server instance → Value: raw capabilities object from initialize request
+     */
+    private rawClientCapabilities;
+    /**
+     * Store raw capabilities for a server instance.
+     * Called from the transport message interceptor.
+     */
+    setRawCapabilities(server: Server, capabilities: Record<string, any>): void;
+    /**
+     * Check if client supports MCP Apps UI (structuredContent + _meta.ui)
+     *
+     * Looks for the "io.modelcontextprotocol/ui" capability in the client's
+     * initialize handshake. Any MCP client that advertises this capability
+     * gets rich UI responses — Claude Desktop, ChatGPT, MCPJam, etc.
+     *
+     * The capability may appear under `experimental` (older SDK types) or
+     * `extensions` (protocol version 2025-11-25+). We check both so it
+     * just works regardless of which field the client uses.
+     *
+     * Beam is special-cased because it's our own SSE transport where the
+     * capability is implicit.
+     */
+    supportsUI(server: Server): boolean;
+    /**
+     * Check if client supports elicitation
+     *
+     * Elicitation is a client capability declared during initialization.
+     * The server can use elicitInput() when the client supports it.
+     */
+    supportsElicitation(server: Server): boolean;
+    /**
+     * Intercept a transport to capture raw client capabilities before Zod strips them.
+     *
+     * The MCP SDK's Zod schema for ClientCapabilities doesn't include `extensions`
+     * (protocol 2025-11-25+), so getClientCapabilities() returns an object without it.
+     * We intercept the transport's onmessage to capture the raw `initialize` request
+     * and store capabilities before Zod parsing occurs.
+     *
+     * @param onMessage Optional additional message interceptor (e.g. for channel permissions)
+     */
+    interceptTransportForRawCapabilities(transport: {
+        onmessage?: (...args: any[]) => void;
+    }, targetServer: Server, onMessage?: (message: any) => void): void;
+}
+//# sourceMappingURL=capability-negotiator.d.ts.map

package/dist/capability-negotiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-negotiator.d.ts","sourceRoot":"","sources":["../src/capability-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAIxE,qBAAa,oBAAoB;IAC/B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB,CAA8C;IAE3E;;;OAGG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAI3E;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAqBnC;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAW5C;;;;;;;;;OASG;IACH,oCAAoC,CAClC,SAAS,EAAE;QAAE,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;KAAE,EACnD,YAAY,EAAE,MAAM,EACpB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GACjC,IAAI;CAcR"}

package/dist/capability-negotiator.js

@@ -0,0 +1,104 @@
+/**
+ * CapabilityNegotiator — client capability detection and negotiation
+ *
+ * Encapsulates the logic for detecting what an MCP client supports
+ * (UI rendering, elicitation, etc.) based on the initialize handshake.
+ *
+ * The MCP SDK's Zod schema strips unknown fields like `extensions`
+ * (protocol 2025-11-25+), so we also capture raw capabilities from
+ * the JSON-RPC initialize message before Zod parsing occurs.
+ */
+const MCP_UI_CAPABILITY = 'io.modelcontextprotocol/ui';
+export class CapabilityNegotiator {
+    /**
+     * Raw client capabilities captured from the initialize request BEFORE Zod parsing.
+     *
+     * The MCP SDK uses Zod to validate incoming requests, which strips unknown fields
+     * from ClientCapabilities. Notably, `extensions` (protocol 2025-11-25+) is not in
+     * the SDK's Zod schema yet, so `getClientCapabilities()` returns an object without
+     * it. Real clients like Claude Desktop and ChatGPT send UI capability under
+     * `extensions`, not `experimental`. We intercept the raw JSON-RPC message to
+     * capture the full capabilities before Zod strips them.
+     *
+     * Key: Server instance → Value: raw capabilities object from initialize request
+     */
+    rawClientCapabilities = new WeakMap();
+    /**
+     * Store raw capabilities for a server instance.
+     * Called from the transport message interceptor.
+     */
+    setRawCapabilities(server, capabilities) {
+        this.rawClientCapabilities.set(server, capabilities);
+    }
+    /**
+     * Check if client supports MCP Apps UI (structuredContent + _meta.ui)
+     *
+     * Looks for the "io.modelcontextprotocol/ui" capability in the client's
+     * initialize handshake. Any MCP client that advertises this capability
+     * gets rich UI responses — Claude Desktop, ChatGPT, MCPJam, etc.
+     *
+     * The capability may appear under `experimental` (older SDK types) or
+     * `extensions` (protocol version 2025-11-25+). We check both so it
+     * just works regardless of which field the client uses.
+     *
+     * Beam is special-cased because it's our own SSE transport where the
+     * capability is implicit.
+     */
+    supportsUI(server) {
+        // Check SDK-parsed capabilities (works for `experimental` which is in the Zod schema)
+        const capabilities = server.getClientCapabilities();
+        if (capabilities?.experimental?.[MCP_UI_CAPABILITY]) {
+            return true;
+        }
+        // Check raw capabilities captured before Zod parsing (needed for `extensions`
+        // which the SDK's Zod schema strips — Claude Desktop and ChatGPT use this field)
+        const raw = this.rawClientCapabilities.get(server);
+        if (raw?.extensions?.[MCP_UI_CAPABILITY]) {
+            return true;
+        }
+        // Beam is our own transport — UI support is implicit
+        const clientInfo = server.getClientVersion();
+        if (clientInfo?.name === 'beam')
+            return true;
+        return false;
+    }
+    /**
+     * Check if client supports elicitation
+     *
+     * Elicitation is a client capability declared during initialization.
+     * The server can use elicitInput() when the client supports it.
+     */
+    supportsElicitation(server) {
+        const capabilities = server.getClientCapabilities();
+        if (!capabilities) {
+            return false;
+        }
+        // Check for elicitation capability (MCP 2025-06 spec)
+        return !!capabilities.elicitation;
+    }
+    /**
+     * Intercept a transport to capture raw client capabilities before Zod strips them.
+     *
+     * The MCP SDK's Zod schema for ClientCapabilities doesn't include `extensions`
+     * (protocol 2025-11-25+), so getClientCapabilities() returns an object without it.
+     * We intercept the transport's onmessage to capture the raw `initialize` request
+     * and store capabilities before Zod parsing occurs.
+     *
+     * @param onMessage Optional additional message interceptor (e.g. for channel permissions)
+     */
+    interceptTransportForRawCapabilities(transport, targetServer, onMessage) {
+        const origOnMessage = transport.onmessage;
+        transport.onmessage = (message, extra) => {
+            // Capture raw capabilities from initialize request
+            if (message?.method === 'initialize' && message?.params) {
+                if (message.params.capabilities) {
+                    this.rawClientCapabilities.set(targetServer, message.params.capabilities);
+                }
+            }
+            // Call additional interceptor if provided
+            onMessage?.(message);
+            origOnMessage?.(message, extra);
+        };
+    }
+}
+//# sourceMappingURL=capability-negotiator.js.map

package/dist/capability-negotiator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-negotiator.js","sourceRoot":"","sources":["../src/capability-negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,iBAAiB,GAAG,4BAA4B,CAAC;AAEvD,MAAM,OAAO,oBAAoB;IAC/B;;;;;;;;;;;OAWG;IACK,qBAAqB,GAAG,IAAI,OAAO,EAA+B,CAAC;IAE3E;;;OAGG;IACH,kBAAkB,CAAC,MAAc,EAAE,YAAiC;QAClE,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,MAAc;QACvB,sFAAsF;QACtF,MAAM,YAAY,GAAG,MAAM,CAAC,qBAAqB,EAAyB,CAAC;QAC3E,IAAI,YAAY,EAAE,YAAY,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,8EAA8E;QAC9E,iFAAiF;QACjF,MAAM,GAAG,GAAG,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,qDAAqD;QACrD,MAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC7C,IAAI,UAAU,EAAE,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAE7C,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,MAAc;QAChC,MAAM,YAAY,GAAG,MAAM,CAAC,qBAAqB,EAAE,CAAC;QAEpD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,sDAAsD;QACtD,OAAO,CAAC,CAAC,YAAY,CAAC,WAAW,CAAC;IACpC,CAAC;IAED;;;;;;;;;OASG;IACH,oCAAoC,CAClC,SAAmD,EACnD,YAAoB,EACpB,SAAkC;QAElC,MAAM,aAAa,GAAG,SAAS,CAAC,SAAS,CAAC;QAC1C,SAAS,CAAC,SAAS,GAAG,CAAC,OAAY,EAAE,KAAW,EAAE,EAAE;YAClD,mDAAmD;YACnD,IAAI,OAAO,EAAE,MAAM,KAAK,YAAY,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;gBACxD,IAAI,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;oBAChC,IAAI,CAAC,qBAAqB,CAAC,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;gBAC5E,CAAC;YACH,CAAC;YACD,0CAA0C;YAC1C,SAAS,EAAE,CAAC,OAAO,CAAC,CAAC;YACrB,aAAa,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC,CAAC;IACJ,CAAC;CACF"}

package/dist/channel-manager.d.ts

@@ -0,0 +1,122 @@
+/**
+ * ChannelManager — encapsulates channel/pub-sub logic extracted from PhotonServer.
+ *
+ * Handles:
+ *  - Channel capability declaration for MCP server init
+ *  - Channel notification methods (per-target)
+ *  - Permission request/response flow
+ *  - Publishing channel events to daemon
+ *  - Subscribing to daemon channels and forwarding messages to MCP clients
+ *  - Cleanup of daemon subscriptions
+ */
+export type ChannelPermissionRequest = {
+    request_id: string;
+    tool_name: string;
+    description: string;
+    input_preview: string;
+};
+export type ChannelPermissionResponse = {
+    request_id: string;
+    behavior: 'allow' | 'deny';
+};
+/** Channel-specific options extracted from PhotonServerOptions */
+export interface ChannelOptions {
+    channelMode?: boolean;
+    channelName?: string;
+    channelTargets?: string[];
+    channelInstructions?: string;
+}
+/**
+ * Callback interface for sending notifications back to MCP clients.
+ * PhotonServer implements this so ChannelManager stays decoupled.
+ */
+export interface ChannelNotificationSink {
+    /** Send a notification to the primary (STDIO) server */
+    sendNotification(notification: {
+        method: string;
+        params: any;
+    }): Promise<void>;
+    /** Send a notification to all SSE sessions */
+    sendNotificationToAllSessions(notification: {
+        method: string;
+        params: any;
+    }): Promise<void>;
+    /** Get the photon instance for permission dispatch */
+    getPhotonInstance(): any;
+}
+export declare class ChannelManager {
+    private channelUnsubscribers;
+    private daemonName;
+    private options;
+    private workingDir?;
+    private sink;
+    private log;
+    constructor(opts: {
+        channelOptions: ChannelOptions;
+        workingDir?: string;
+        sink: ChannelNotificationSink;
+        log: (level: string, message: string, data?: Record<string, unknown>) => void;
+    });
+    /** Whether channel mode is active */
+    get isChannelMode(): boolean;
+    /** The current daemon name (set after daemon startup) */
+    get currentDaemonName(): string | null;
+    /** Set the daemon name (called after daemon startup in PhotonServer) */
+    setDaemonName(name: string | null): void;
+    /**
+     * Returns the server name to use.
+     * In channel mode, uses the channel name; otherwise defaults to 'photon-mcp'.
+     */
+    getServerName(): string;
+    /**
+     * Returns extra capabilities to merge into the MCP Server capabilities object.
+     * Produces the experimental channel entries for each declared target.
+     */
+    getExtraCapabilities(): Record<string, any>;
+    /**
+     * Returns extra server constructor options (e.g. instructions) for channel mode.
+     */
+    getExtraServerOptions(): Record<string, any>;
+    /**
+     * Get the notification methods for all declared channel targets.
+     * Each target (e.g. 'claude') maps to `notifications/{target}/channel`.
+     */
+    private getChannelNotificationMethods;
+    /**
+     * Handle a permission request from the client (e.g. Claude Code asking "Allow tool X?").
+     * Forwards to the photon instance via channel._dispatchPermission().
+     */
+    handlePermissionRequest(params: any): void;
+    /**
+     * Send a permission response back to the client.
+     * Called by the photon instance (via this.channel.respond) when the user approves/denies.
+     */
+    respondToPermission(response: ChannelPermissionResponse): void;
+    /**
+     * Publish a channel event to the daemon for cross-process pub/sub.
+     * Called from output handlers whenever an emit has a `channel` field.
+     */
+    publishIfChannel(emit: any): void;
+    /**
+     * Subscribe to daemon channels for cross-process notifications.
+     * In channel mode, handleChannelMessage intercepts 'channel-push' events
+     * and translates them to notifications/claude/channel for the connected client.
+     */
+    subscribeToChannels(): Promise<void>;
+    /**
+     * Handle incoming channel messages and forward as MCP notifications.
+     * Routes channel-permission-response and channel-push messages,
+     * and forwards everything else as standard MCP notifications with _photon data.
+     */
+    private handleChannelMessage;
+    /**
+     * Check if an incoming message is a channel permission request and handle it.
+     * Returns true if it was handled (caller should not process further).
+     */
+    interceptPermissionRequest(message: any): boolean;
+    /**
+     * Unsubscribe from all daemon channels. Called during server shutdown.
+     */
+    cleanup(): void;
+}
+//# sourceMappingURL=channel-manager.d.ts.map

package/dist/channel-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-manager.d.ts","sourceRoot":"","sources":["../src/channel-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,MAAM,wBAAwB,GAAG;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;CAC5B,CAAC;AAEF,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,gBAAgB,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,8CAA8C;IAC9C,6BAA6B,CAAC,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,sDAAsD;IACtD,iBAAiB,IAAI,GAAG,CAAC;CAC1B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,oBAAoB,CAAyB;IACrD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,GAAG,CAA2E;gBAE1E,IAAI,EAAE;QAChB,cAAc,EAAE,cAAc,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,uBAAuB,CAAC;QAC9B,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KAC/E;IAOD,qCAAqC;IACrC,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,yDAAyD;IACzD,IAAI,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAErC;IAED,wEAAwE;IACxE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAQxC;;;OAGG;IACH,aAAa,IAAI,MAAM;IAMvB;;;OAGG;IACH,oBAAoB,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAY3C;;OAEG;IACH,qBAAqB,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAS5C;;;OAGG;IACH,OAAO,CAAC,6BAA6B;IASrC;;;OAGG;IACH,uBAAuB,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI;IAe1C;;;OAGG;IACH,mBAAmB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAuB9D;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI;IAWjC;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB1C;;;;OAIG;YACW,oBAAoB;IA0ElC;;;OAGG;IACH,0BAA0B,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO;IAYjD;;OAEG;IACH,OAAO,IAAI,IAAI;CAUhB"}

package/dist/channel-manager.js

@@ -0,0 +1,266 @@
+/**
+ * ChannelManager — encapsulates channel/pub-sub logic extracted from PhotonServer.
+ *
+ * Handles:
+ *  - Channel capability declaration for MCP server init
+ *  - Channel notification methods (per-target)
+ *  - Permission request/response flow
+ *  - Publishing channel events to daemon
+ *  - Subscribing to daemon channels and forwarding messages to MCP clients
+ *  - Cleanup of daemon subscriptions
+ */
+import { subscribeChannel, publishToChannel } from './daemon/client.js';
+import { getErrorMessage } from './shared/error-handler.js';
+export class ChannelManager {
+    channelUnsubscribers = [];
+    daemonName = null;
+    options;
+    workingDir;
+    sink;
+    log;
+    constructor(opts) {
+        this.options = opts.channelOptions;
+        this.workingDir = opts.workingDir;
+        this.sink = opts.sink;
+        this.log = opts.log;
+    }
+    /** Whether channel mode is active */
+    get isChannelMode() {
+        return !!this.options.channelMode;
+    }
+    /** The current daemon name (set after daemon startup) */
+    get currentDaemonName() {
+        return this.daemonName;
+    }
+    /** Set the daemon name (called after daemon startup in PhotonServer) */
+    setDaemonName(name) {
+        this.daemonName = name;
+    }
+    // ---------------------------------------------------------------------------
+    // MCP Server Init Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns the server name to use.
+     * In channel mode, uses the channel name; otherwise defaults to 'photon-mcp'.
+     */
+    getServerName() {
+        return this.options.channelMode && this.options.channelName
+            ? this.options.channelName
+            : 'photon-mcp';
+    }
+    /**
+     * Returns extra capabilities to merge into the MCP Server capabilities object.
+     * Produces the experimental channel entries for each declared target.
+     */
+    getExtraCapabilities() {
+        if (!this.options.channelMode || !this.options.channelTargets?.length)
+            return {};
+        return {
+            experimental: Object.fromEntries(this.options.channelTargets.flatMap((t) => [
+                [`${t}/channel`, {}],
+                [`${t}/channel/permission`, {}],
+            ])),
+        };
+    }
+    /**
+     * Returns extra server constructor options (e.g. instructions) for channel mode.
+     */
+    getExtraServerOptions() {
+        if (!this.options.channelMode || !this.options.channelInstructions)
+            return {};
+        return { instructions: this.options.channelInstructions };
+    }
+    // ---------------------------------------------------------------------------
+    // Notification Methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Get the notification methods for all declared channel targets.
+     * Each target (e.g. 'claude') maps to `notifications/{target}/channel`.
+     */
+    getChannelNotificationMethods() {
+        const targets = this.options.channelTargets || [];
+        return targets.map((t) => `notifications/${t}/channel`);
+    }
+    // ---------------------------------------------------------------------------
+    // Permission Flow
+    // ---------------------------------------------------------------------------
+    /**
+     * Handle a permission request from the client (e.g. Claude Code asking "Allow tool X?").
+     * Forwards to the photon instance via channel._dispatchPermission().
+     */
+    handlePermissionRequest(params) {
+        if (!params?.request_id || !params?.tool_name)
+            return;
+        const request = {
+            request_id: params.request_id,
+            tool_name: params.tool_name,
+            description: params.description || '',
+            input_preview: params.input_preview || '',
+        };
+        this.log('info', `Permission request: ${request.tool_name} (${request.request_id})`);
+        const instance = this.sink.getPhotonInstance();
+        if (instance?.channel?._dispatchPermission) {
+            instance.channel._dispatchPermission(request);
+        }
+    }
+    /**
+     * Send a permission response back to the client.
+     * Called by the photon instance (via this.channel.respond) when the user approves/denies.
+     */
+    respondToPermission(response) {
+        const targets = this.options.channelTargets || [];
+        for (const target of targets) {
+            const notification = {
+                method: `notifications/${target}/channel/permission`,
+                params: {
+                    request_id: response.request_id,
+                    behavior: response.behavior,
+                },
+            };
+            this.sink.sendNotification(notification).catch((e) => {
+                this.log('debug', 'Permission response failed', { error: getErrorMessage(e) });
+            });
+            this.sink.sendNotificationToAllSessions(notification).catch((e) => {
+                this.log('debug', `Failed to send permission to SSE sessions: ${getErrorMessage(e)}`);
+            });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Publishing
+    // ---------------------------------------------------------------------------
+    /**
+     * Publish a channel event to the daemon for cross-process pub/sub.
+     * Called from output handlers whenever an emit has a `channel` field.
+     */
+    publishIfChannel(emit) {
+        if (!this.daemonName || !emit?.channel)
+            return;
+        publishToChannel(this.daemonName, emit.channel, emit, this.workingDir).catch((e) => {
+            this.log('debug', `Failed to publish channel event to daemon: ${e?.message || e}`);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Subscribing & Message Handling
+    // ---------------------------------------------------------------------------
+    /**
+     * Subscribe to daemon channels for cross-process notifications.
+     * In channel mode, handleChannelMessage intercepts 'channel-push' events
+     * and translates them to notifications/claude/channel for the connected client.
+     */
+    async subscribeToChannels() {
+        if (!this.daemonName)
+            return;
+        try {
+            const unsubscribe = await subscribeChannel(this.daemonName, `${this.daemonName}:*`, (message) => {
+                void this.handleChannelMessage(message);
+            }, { workingDir: this.workingDir });
+            this.channelUnsubscribers.push(unsubscribe);
+            this.log('info', `Subscribed to daemon channel: ${this.daemonName}:*`);
+        }
+        catch (error) {
+            this.log('warn', `Failed to subscribe to daemon: ${getErrorMessage(error)}`);
+        }
+    }
+    /**
+     * Handle incoming channel messages and forward as MCP notifications.
+     * Routes channel-permission-response and channel-push messages,
+     * and forwards everything else as standard MCP notifications with _photon data.
+     */
+    async handleChannelMessage(message) {
+        if (!message || typeof message !== 'object')
+            return;
+        const msg = message;
+        if (process.env.PHOTON_DEBUG_EVENTS === '1') {
+            console.error(`[PHOTON-SERVER] Received daemon message on ${String(msg.channel)}: event=${String(msg.event)}`);
+        }
+        // Channel permission responses — photon called this.channel.respond()
+        if (this.options.channelMode && String(msg.channel).endsWith(':channel-permission-response')) {
+            const data = msg.data;
+            if (data?.request_id && data?.behavior) {
+                this.respondToPermission({
+                    request_id: data.request_id,
+                    behavior: data.behavior,
+                });
+            }
+            return;
+        }
+        // Channel events — translate to client-specific channel notifications.
+        if (this.options.channelMode && String(msg.channel).endsWith(':channel-push')) {
+            const pushData = msg.data;
+            const methods = this.getChannelNotificationMethods();
+            if (methods.length === 0)
+                return;
+            const content = typeof pushData?.content === 'string' ? pushData.content : '';
+            const meta = pushData?.meta || {};
+            try {
+                for (const method of methods) {
+                    const notification = { method, params: { content, meta } };
+                    await this.sink.sendNotification(notification);
+                    await this.sink.sendNotificationToAllSessions(notification);
+                }
+            }
+            catch (e) {
+                this.log('debug', 'Channel notification failed', { error: getErrorMessage(e) });
+            }
+            return;
+        }
+        // Standard notification with embedded photon data
+        const payload = {
+            method: 'ui/notifications/host-context-changed',
+            params: {
+                _photon: {
+                    photon: this.daemonName,
+                    channel: msg.channel,
+                    event: msg.event,
+                    data: msg.data,
+                },
+            },
+        };
+        try {
+            if (process.env.PHOTON_DEBUG_EVENTS === '1') {
+                console.error(`[PHOTON-SERVER] Sending notification to MCP clients...`);
+            }
+            await this.sink.sendNotification(payload);
+            if (process.env.PHOTON_DEBUG_EVENTS === '1') {
+                console.error(`[PHOTON-SERVER] Notification sent successfully`);
+            }
+        }
+        catch (e) {
+            console.error(`[PHOTON-SERVER-ERROR] Notification send failed: ${getErrorMessage(e)}`);
+            this.log('debug', 'Notification send failed', { error: getErrorMessage(e) });
+        }
+        // Also send to SSE sessions
+        await this.sink.sendNotificationToAllSessions(payload).catch((e) => {
+            this.log('debug', 'Session notification failed', { error: getErrorMessage(e) });
+        });
+    }
+    /**
+     * Check if an incoming message is a channel permission request and handle it.
+     * Returns true if it was handled (caller should not process further).
+     */
+    interceptPermissionRequest(message) {
+        if (this.options.channelMode && message?.method?.endsWith('/channel/permission_request')) {
+            this.handlePermissionRequest(message.params);
+            return true;
+        }
+        return false;
+    }
+    // ---------------------------------------------------------------------------
+    // Cleanup
+    // ---------------------------------------------------------------------------
+    /**
+     * Unsubscribe from all daemon channels. Called during server shutdown.
+     */
+    cleanup() {
+        for (const unsubscribe of this.channelUnsubscribers) {
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.channelUnsubscribers = [];
+    }
+}
+//# sourceMappingURL=channel-manager.js.map

package/dist/channel-manager.js.map

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

package/dist/cli/commands/package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/package.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+LzC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAunB9D"}
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/package.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+LzC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8oB9D"}

package/dist/cli/commands/package.js

@@ -485,7 +485,7 @@ export function registerPackageCommands(program) {
                         tableData.push({
                             name: mcpName,
                             local: info.local || '-',
-                            remote: info.remote || 'local only',
+                            remote: info.remote || 'local editable copy',
                             status: STATUS.UNKNOWN,
                         });
                     }
@@ -645,8 +645,9 @@ export function registerPackageCommands(program) {
     program
         .command('fork')
         .argument('<name>', 'Photon name to fork/own')
-        .description('Take ownership of an installed photon (removes marketplace tracking)')
-        .action(async (name, _options, command) => {
+        .option('--as <newName>', 'New local photon name (required when forking an already-local photon)')
+        .description('Create a local editable copy or take ownership of a tracked photon')
+        .action(async (name, options, command) => {
         try {
             const { printSuccess, printError } = await import('../../cli-formatter.js');
             const workingDir = getDefaultContext().baseDir;
@@ -662,7 +663,7 @@ export function registerPackageCommands(program) {
                 }
             }
             choices.push('Create new GitHub repository');
-            choices.push('Local only (remove marketplace tracking)');
+            choices.push('Local editable copy');
             const rl = createReadline();
             console.error(`\nWhere do you want to fork ${name}?\n`);
             choices.forEach((c, i) => console.error(`  [${i + 1}] ${c}`));
@@ -676,7 +677,7 @@ export function registerPackageCommands(program) {
                 printError('Invalid choice');
                 process.exit(1);
             }
-            let forkOptions;
+            let forkOptions = {};
             if (choiceIdx < targets.length) {
                 // Push to existing marketplace repo
                 forkOptions = { targetRepo: targets[choiceIdx].repo };
@@ -694,8 +695,25 @@ export function registerPackageCommands(program) {
                 }
                 forkOptions = { createRepo: repoName.trim() };
             }
-            // else: local only, no options
-            const result = await manager.forkPhoton(name, workingDir, forkOptions);
+            if (options.as?.trim()) {
+                forkOptions.newName = options.as.trim();
+            }
+            let result = await manager.forkPhoton(name, workingDir, forkOptions);
+            if (!result.success && result.requiresName && !forkOptions.newName) {
+                const rl3 = createReadline();
+                const suggested = result.suggestedName ? ` [${result.suggestedName}]` : '';
+                const newName = await new Promise((resolve) => {
+                    rl3.question(`New local photon name${suggested}: `, resolve);
+                });
+                rl3.close();
+                const resolvedName = newName.trim() || result.suggestedName;
+                if (!resolvedName) {
+                    printError('A new local name is required');
+                    process.exit(1);
+                }
+                forkOptions.newName = resolvedName;
+                result = await manager.forkPhoton(name, workingDir, forkOptions);
+            }
             if (result.success) {
                 printSuccess(result.message);
             }