@portel/photon 1.19.0 → 1.20.0

package/dist/task-executor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * TaskExecutor — extracted from PhotonServer
+ *
+ * Encapsulates all MCP Tasks protocol handling (spec v2025-11-25):
+ * - Task creation from tool calls (task mode)
+ * - GetTask, ListTasks, CancelTask, GetTaskPayload handlers
+ * - Input resolution via elicitation
+ *
+ * Dependency direction: PhotonServer → TaskExecutor (never the reverse).
+ */
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { LogLevel } from './shared/logger.js';
+/** Minimal interface for executing a tool — avoids importing PhotonLoader */
+export interface ToolExecutor {
+    executeTool(photon: {
+        name: string;
+    }, toolName: string, args: Record<string, unknown>, options: {
+        outputHandler?: (data: any) => void;
+        inputProvider?: (ask: any) => Promise<any>;
+    }): Promise<any>;
+}
+/** Minimal interface for creating an input provider via MCP elicitation */
+export interface InputProviderFactory {
+    createMCPInputProvider(server?: Server): (ask: any) => Promise<any>;
+}
+/** Logger callback matching PhotonServer's log() signature */
+export type TaskLog = (level: LogLevel, message: string, meta?: Record<string, any>) => void;
+export declare class TaskExecutor {
+    private log;
+    private toolExecutor;
+    private inputProviderFactory;
+    constructor(log: TaskLog, toolExecutor: ToolExecutor, inputProviderFactory: InputProviderFactory);
+    /**
+     * Handle task-mode tool call: when request params contain a `task` field,
+     * run the tool asynchronously and return a task reference.
+     *
+     * Returns the MCP response if task mode applies, or null if it doesn't.
+     */
+    handleTaskModeCall(photonName: string, toolName: string, args: Record<string, unknown>, taskField: {
+        ttl?: number;
+    }): {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    };
+    /**
+     * Handle tasks/get — returns wire-format task status.
+     */
+    handleGetTask(taskId: string): any;
+    /**
+     * Handle tasks/list — returns paginated task list.
+     */
+    handleListTasks(cursor?: string): any;
+    /**
+     * Handle tasks/cancel — aborts the task and returns updated status.
+     */
+    handleCancelTask(taskId: string): any;
+    /**
+     * Handle tasks/get_result — blocks until task completes or times out.
+     * Handles input_required states via elicitation.
+     */
+    handleGetTaskPayload(taskId: string, server: Server): Promise<any>;
+    /**
+     * Format a terminal task result for MCP response.
+     */
+    private formatTaskResult;
+}
+//# sourceMappingURL=task-executor.d.ts.map

package/dist/task-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-executor.d.ts","sourceRoot":"","sources":["../src/task-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAaxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,WAAW,CACT,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EACxB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE;QAAE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;QAAC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,GAC3F,OAAO,CAAC,GAAG,CAAC,CAAC;CACjB;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,sBAAsB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACrE;AAED,8DAA8D;AAC9D,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;AAE7F,qBAAa,YAAY;IAErB,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,oBAAoB;gBAFpB,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,YAAY,EAC1B,oBAAoB,EAAE,oBAAoB;IAGpD;;;;;OAKG;IACH,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;IAuBrD;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG;IAMlC;;OAEG;IACH,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG;IAYrC;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG;IAgBrC;;;OAGG;IACG,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAwDxE;;OAEG;IACH,OAAO,CAAC,gBAAgB;CA2BzB"}

package/dist/task-executor.js

@@ -0,0 +1,182 @@
+/**
+ * TaskExecutor — extracted from PhotonServer
+ *
+ * Encapsulates all MCP Tasks protocol handling (spec v2025-11-25):
+ * - Task creation from tool calls (task mode)
+ * - GetTask, ListTasks, CancelTask, GetTaskPayload handlers
+ * - Input resolution via elicitation
+ *
+ * Dependency direction: PhotonServer → TaskExecutor (never the reverse).
+ */
+import { createTask, getTask, updateTask, listTasks, registerController, getController, unregisterController, } from './tasks/store.js';
+import { toWireFormat, relatedTaskMeta, TERMINAL_STATES } from './tasks/types.js';
+import { runTaskExecution, resolveTaskInput, waitForTerminalOrInput } from './tasks/executor.js';
+export class TaskExecutor {
+    log;
+    toolExecutor;
+    inputProviderFactory;
+    constructor(log, toolExecutor, inputProviderFactory) {
+        this.log = log;
+        this.toolExecutor = toolExecutor;
+        this.inputProviderFactory = inputProviderFactory;
+    }
+    /**
+     * Handle task-mode tool call: when request params contain a `task` field,
+     * run the tool asynchronously and return a task reference.
+     *
+     * Returns the MCP response if task mode applies, or null if it doesn't.
+     */
+    handleTaskModeCall(photonName, toolName, args, taskField) {
+        const ttl = typeof taskField.ttl === 'number' ? taskField.ttl : undefined;
+        this.log('info', 'Starting background task', { photon: photonName, tool: toolName });
+        const task = createTask(photonName, toolName, args, ttl);
+        const controller = new AbortController();
+        registerController(task.id, controller);
+        const executeFn = async (taskInputProvider, outputHandler) => {
+            return this.toolExecutor.executeTool({ name: photonName }, toolName, args, {
+                outputHandler,
+                inputProvider: taskInputProvider,
+            });
+        };
+        runTaskExecution(task.id, executeFn, {
+            signal: controller.signal,
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ task: toWireFormat(task) }, null, 2) }],
+        };
+    }
+    /**
+     * Handle tasks/get — returns wire-format task status.
+     */
+    handleGetTask(taskId) {
+        const task = getTask(taskId);
+        if (!task)
+            throw new Error(`Task not found: ${taskId}`);
+        return toWireFormat(task);
+    }
+    /**
+     * Handle tasks/list — returns paginated task list.
+     */
+    handleListTasks(cursor) {
+        const allTasks = listTasks();
+        const offset = cursor ? parseInt(cursor, 10) || 0 : 0;
+        const pageSize = 50;
+        const page = allTasks.slice(offset, offset + pageSize);
+        const nextCursor = offset + pageSize < allTasks.length ? String(offset + pageSize) : undefined;
+        return {
+            tasks: page.map(toWireFormat),
+            ...(nextCursor && { nextCursor }),
+        };
+    }
+    /**
+     * Handle tasks/cancel — aborts the task and returns updated status.
+     */
+    handleCancelTask(taskId) {
+        const task = getTask(taskId);
+        if (!task)
+            throw new Error(`Task not found: ${taskId}`);
+        if (TERMINAL_STATES.includes(task.state)) {
+            throw new Error(`Cannot cancel task in terminal state: ${task.state}`);
+        }
+        const controller = getController(taskId);
+        if (controller)
+            controller.abort();
+        const updated = updateTask(taskId, {
+            state: 'cancelled',
+            statusMessage: 'The task was cancelled by request.',
+        });
+        unregisterController(taskId);
+        return toWireFormat(updated);
+    }
+    /**
+     * Handle tasks/get_result — blocks until task completes or times out.
+     * Handles input_required states via elicitation.
+     */
+    async handleGetTaskPayload(taskId, server) {
+        const task = getTask(taskId);
+        if (!task)
+            throw new Error(`Task not found: ${taskId}`);
+        // Already terminal — return immediately
+        if (TERMINAL_STATES.includes(task.state)) {
+            return this.formatTaskResult(task, taskId);
+        }
+        // If input_required, try to get input via elicitation
+        if (task.state === 'input_required' && task.input) {
+            const inputProvider = this.inputProviderFactory.createMCPInputProvider(server);
+            try {
+                const value = await inputProvider(task.input);
+                resolveTaskInput(taskId, value);
+            }
+            catch {
+                resolveTaskInput(taskId, null);
+            }
+        }
+        // Block until terminal (max 5 min per call)
+        try {
+            const abortController = new AbortController();
+            const timeout = setTimeout(() => abortController.abort(), 300000);
+            try {
+                while (true) {
+                    const current = await waitForTerminalOrInput(taskId, abortController.signal);
+                    if (TERMINAL_STATES.includes(current.state)) {
+                        return this.formatTaskResult(current, taskId);
+                    }
+                    if (current.state === 'input_required' && current.input) {
+                        const inputProvider = this.inputProviderFactory.createMCPInputProvider(server);
+                        try {
+                            const value = await inputProvider(current.input);
+                            resolveTaskInput(taskId, value);
+                        }
+                        catch {
+                            resolveTaskInput(taskId, null);
+                        }
+                    }
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch {
+            const current = getTask(taskId);
+            if (current && TERMINAL_STATES.includes(current.state)) {
+                return this.formatTaskResult(current, taskId);
+            }
+            return {
+                content: [{ type: 'text', text: `Task ${taskId} is still running.` }],
+                isError: false,
+                _meta: relatedTaskMeta(taskId),
+            };
+        }
+    }
+    /**
+     * Format a terminal task result for MCP response.
+     */
+    formatTaskResult(task, taskId) {
+        if (task.state === 'failed') {
+            return {
+                content: [{ type: 'text', text: task.error || 'Task failed' }],
+                isError: true,
+                _meta: relatedTaskMeta(taskId),
+            };
+        }
+        if (task.state === 'cancelled') {
+            return {
+                content: [{ type: 'text', text: 'Task was cancelled.' }],
+                isError: false,
+                _meta: relatedTaskMeta(taskId),
+            };
+        }
+        // Completed
+        if (task.result && typeof task.result === 'object' && 'content' in task.result) {
+            return { ...task.result, _meta: relatedTaskMeta(taskId) };
+        }
+        const text = typeof task.result === 'string' ? task.result : JSON.stringify(task.result ?? null);
+        return {
+            content: [{ type: 'text', text }],
+            isError: false,
+            _meta: relatedTaskMeta(taskId),
+        };
+    }
+}
+//# sourceMappingURL=task-executor.js.map

package/dist/task-executor.js.map

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

package/dist/types/photon-instance.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Runtime-injected properties on photon instances.
+ *
+ * The loader dynamically attaches channel infrastructure, event dispatch,
+ * and reactive-collection wiring onto plain class instances. This interface
+ * captures those shapes so call-sites can avoid `as any`.
+ */
+export interface EventListenerEntry {
+    event: string;
+    fn: (data: unknown) => void;
+    filter?: EventFilter;
+}
+export interface EventFilter {
+    group?: string;
+    chatId?: string;
+    trigger?: string;
+    fromMe?: boolean;
+}
+export interface ChannelMessage {
+    content?: string;
+    fromMe?: boolean;
+    [key: string]: unknown;
+}
+export interface ChannelFunction {
+    (content: string, meta?: Record<string, string>): void;
+    respond: (requestId: string, behavior: 'allow' | 'deny') => void;
+    onPermission: (handler: (request: unknown) => void) => void;
+    _dispatchPermission: (request: unknown) => Promise<unknown> | void;
+    [key: string]: unknown;
+}
+export interface PhotonInstance {
+    channel?: ChannelFunction;
+    _dispatch?: (chatId: string, message: ChannelMessage, groupName?: string) => void;
+    _eventListeners?: EventListenerEntry[];
+    _matchesFilter?: (filter: EventFilter | undefined, chatId: string, message: ChannelMessage, groupName?: string) => boolean;
+    on?: (event: string, handler: (data: unknown) => void, filter?: EventFilter) => void;
+    off?: (event: string, handler: (data: unknown) => void) => void;
+    [key: string]: unknown;
+}
+export interface ReactiveCollectionLike {
+    _propertyName?: string;
+    _emitter?: (event: string, data: unknown) => void;
+    [key: string]: unknown;
+}
+export interface DaemonEventEnvelope {
+    channel: string;
+    event: string;
+    data: Record<string, unknown>;
+}
+//# sourceMappingURL=photon-instance.d.ts.map

package/dist/types/photon-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-instance.d.ts","sourceRoot":"","sources":["../../src/types/photon-instance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,MAAM,WAAW,eAAe;IAC9B,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACvD,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,KAAK,IAAI,CAAC;IACjE,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAC;IAC5D,mBAAmB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IACnE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAClF,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,EACvB,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC;IACb,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;IACrF,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAC;IAChE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B"}

package/dist/types/photon-instance.js

@@ -0,0 +1,9 @@
+/**
+ * Runtime-injected properties on photon instances.
+ *
+ * The loader dynamically attaches channel infrastructure, event dispatch,
+ * and reactive-collection wiring onto plain class instances. This interface
+ * captures those shapes so call-sites can avoid `as any`.
+ */
+export {};
+//# sourceMappingURL=photon-instance.js.map

package/dist/types/photon-instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-instance.js","sourceRoot":"","sources":["../../src/types/photon-instance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/types/server-types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Server-specific type helpers to replace `as any` casts in server.ts.
+ *
+ * These interfaces extend the published photon-core types with properties
+ * that exist at runtime but are not part of the public API surface.
+ */
+import type { PhotonClassExtended } from '@portel/photon-core';
+/**
+ * Extended photon class with runtime-only metadata properties.
+ * These are set by the loader but not declared on PhotonClassExtended.
+ */
+export interface PhotonClassWithMeta extends PhotonClassExtended {
+    /** Photon icon emoji or name (from @icon class-level tag) */
+    icon?: string;
+    /** Whether the photon is stateful (from @stateful class-level tag) */
+    stateful?: boolean;
+    /** Convenience flag: true when settingsSchema.hasSettings is true */
+    hasSettings?: boolean;
+    /** Internal tool schema map used for diagnostics */
+    _toolSchemas?: Record<string, unknown>;
+}
+/**
+ * MCP tool definition returned by handleListTools.
+ * Matches the MCP protocol Tool shape.
+ */
+export interface MCPToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    icons?: Array<{
+        src: string;
+        mimeType?: string;
+        sizes?: string;
+        theme?: string;
+    }>;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * MCP text content block with optional annotations.
+ */
+export interface MCPTextContent {
+    type: 'text';
+    text: string;
+    annotations?: Record<string, unknown>;
+}
+/**
+ * MCP tool call response.
+ */
+export interface MCPToolResponse {
+    content: MCPTextContent[];
+    isError: boolean;
+    structuredContent?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+    /** Extension field for format-aware clients */
+    'x-output-format'?: string;
+    /** Allow additional MCP extension properties */
+    [key: string]: unknown;
+}
+//# sourceMappingURL=server-types.d.ts.map

package/dist/types/server-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.d.ts","sourceRoot":"","sources":["../../src/types/server-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/types/server-types.js

@@ -0,0 +1,8 @@
+/**
+ * Server-specific type helpers to replace `as any` casts in server.ts.
+ *
+ * These interfaces extend the published photon-core types with properties
+ * that exist at runtime but are not part of the public API surface.
+ */
+export {};
+//# sourceMappingURL=server-types.js.map

package/dist/types/server-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.js","sourceRoot":"","sources":["../../src/types/server-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portel/photon",
-  "version": "1.19.0",
+  "version": "1.20.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",
@@ -68,7 +68,7 @@
     "test:client-adaptive": "npx tsx tests/client-adaptive.test.ts",
     "test:load": "npm run build && node --expose-gc --max-old-space-size=4096 node_modules/.bin/tsx tests/load-test.ts",
     "test:sqlite": "npm run build && npx tsx tests/sqlite.test.ts",
-    "test:github": "npm run build && npx tsx tests/github-issues.test.ts",
+    "test:github": "npm run build && npx tsx tests/github-issues.integration.ts",
     "test:beam": "npm run build && npx tsx tests/beam/rendering.test.ts",
     "test:beam:regressions": "npm run build && npx tsx tests/beam/beam-integration-regressions.test.ts",
     "test:e2e": "npm run build && npx playwright test",