@portel/photon 1.17.6 → 1.19.0

package/dist/tasks/executor.js

@@ -0,0 +1,180 @@
+/**
+ * MCP Task Executor (spec v2025-11-25)
+ *
+ * Runs tool execution in the background with support for input resumption.
+ * Decoupled from transport — works with both Streamable HTTP and STDIO.
+ */
+import { updateTask, unregisterController, taskEvents } from './store.js';
+import { TERMINAL_STATES } from './types.js';
+/**
+ * Pending input resolvers — when a task enters input_required,
+ * the generator blocks on a promise. resolveTaskInput() resolves it.
+ */
+const pendingInputs = new Map();
+/**
+ * Resolve pending input for a task, resuming generator execution.
+ * Returns true if there was pending input to resolve.
+ */
+export function resolveTaskInput(taskId, value) {
+    const pending = pendingInputs.get(taskId);
+    if (!pending)
+        return false;
+    pendingInputs.delete(taskId);
+    pending.resolve(value);
+    return true;
+}
+/**
+ * Reject pending input (e.g., on cancellation or timeout).
+ */
+export function rejectTaskInput(taskId, reason) {
+    const pending = pendingInputs.get(taskId);
+    if (!pending)
+        return false;
+    pendingInputs.delete(taskId);
+    pending.reject(new Error(reason));
+    return true;
+}
+/**
+ * Check if a task has pending input waiting.
+ */
+export function hasPendingInput(taskId) {
+    return pendingInputs.has(taskId);
+}
+/**
+ * Wait for a task to reach a specific state (or any state change).
+ * Resolves with the updated task when the condition is met.
+ */
+export function waitForStateChange(taskId, predicate, signal) {
+    return new Promise((resolve, reject) => {
+        // Check abort
+        if (signal?.aborted) {
+            reject(new Error('Aborted'));
+            return;
+        }
+        const handler = (changedId, newState, task) => {
+            if (changedId !== taskId)
+                return;
+            if (!predicate || predicate(newState)) {
+                cleanup();
+                resolve(task);
+            }
+        };
+        const onAbort = () => {
+            cleanup();
+            reject(new Error('Aborted'));
+        };
+        const cleanup = () => {
+            taskEvents.removeListener('stateChange', handler);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        taskEvents.on('stateChange', handler);
+        signal?.addEventListener('abort', onAbort);
+    });
+}
+/**
+ * Wait for a task to reach a terminal state or input_required.
+ * Used by tasks/result handler.
+ */
+export function waitForTerminalOrInput(taskId, signal) {
+    return waitForStateChange(taskId, (state) => TERMINAL_STATES.includes(state) || state === 'input_required', signal);
+}
+/**
+ * Run tool execution as a background task.
+ *
+ * Fire-and-forget — caller does not await this.
+ * Updates task state in store as execution progresses.
+ * Generator yields { ask } → task enters input_required, blocks until resolveTaskInput().
+ */
+export function runTaskExecution(taskId, executeFn, options) {
+    const { signal, outputHandler: externalOutputHandler } = options;
+    // inputProvider that blocks on pending input
+    const inputProvider = async (ask) => {
+        // Store the ask payload and transition to input_required
+        updateTask(taskId, {
+            state: 'input_required',
+            statusMessage: ask.message || 'Waiting for user input.',
+            input: ask,
+        });
+        // Block until resolveTaskInput() or rejectTaskInput() is called
+        return new Promise((resolve, reject) => {
+            pendingInputs.set(taskId, { resolve, reject });
+            // If already aborted, reject immediately
+            if (signal.aborted) {
+                pendingInputs.delete(taskId);
+                reject(new Error('Task cancelled'));
+                return;
+            }
+            // Listen for abort to clean up
+            const onAbort = () => {
+                if (pendingInputs.has(taskId)) {
+                    pendingInputs.delete(taskId);
+                    reject(new Error('Task cancelled'));
+                }
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        });
+    };
+    // outputHandler that updates task progress
+    const outputHandler = (data) => {
+        if (data?.emit === 'progress' && typeof data.value === 'number') {
+            updateTask(taskId, {
+                progress: { percent: data.value, message: data.message },
+                statusMessage: data.message || undefined,
+            });
+        }
+        else if (data?.emit === 'status') {
+            updateTask(taskId, {
+                statusMessage: data.message || 'Processing...',
+            });
+        }
+        // Forward to external handler (e.g., SSE broadcast)
+        externalOutputHandler?.(data);
+    };
+    // Run in background
+    void (async () => {
+        try {
+            if (signal.aborted) {
+                updateTask(taskId, { state: 'cancelled', statusMessage: 'Task was cancelled.' });
+                return;
+            }
+            // When input is provided and task resumes, transition back to working
+            const wrappedInputProvider = async (ask) => {
+                const result = await inputProvider(ask);
+                // Resume: transition back to working
+                updateTask(taskId, {
+                    state: 'working',
+                    statusMessage: 'Resuming execution...',
+                    input: undefined,
+                });
+                return result;
+            };
+            const result = await executeFn(wrappedInputProvider, outputHandler);
+            if (!signal.aborted) {
+                updateTask(taskId, {
+                    state: 'completed',
+                    statusMessage: 'Operation completed successfully.',
+                    result,
+                });
+            }
+        }
+        catch (err) {
+            if (signal.aborted) {
+                updateTask(taskId, { state: 'cancelled', statusMessage: 'Task was cancelled.' });
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                updateTask(taskId, {
+                    state: 'failed',
+                    statusMessage: message,
+                    error: message,
+                });
+            }
+        }
+        finally {
+            // Clean up any lingering pending input
+            pendingInputs.delete(taskId);
+            unregisterController(taskId);
+        }
+    })();
+}
+//# sourceMappingURL=executor.js.map

package/dist/tasks/executor.js.map

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

package/dist/tasks/store.d.ts

@@ -1,19 +1,26 @@
 /**
- * MCP Task Store
+ * MCP Task Store (spec v2025-11-25)
  *
  * File-based persistence at ~/.photon/tasks/.
  * Each task is a JSON file: {taskId}.json
- * Consistent with existing photon file-based patterns (audit, runs, state).
+ * EventEmitter for state change notifications.
  */
-import type { Task } from './types.js';
+import { EventEmitter } from 'events';
+import { type Task } from './types.js';
+/** Event emitter for task state changes */
+export declare const taskEvents: EventEmitter<[never]>;
 export declare function registerController(taskId: string, controller: AbortController): void;
 export declare function unregisterController(taskId: string): void;
 export declare function getController(taskId: string): AbortController | undefined;
-export declare function createTask(photon: string, method: string, params?: Record<string, unknown>): Task;
+export declare function createTask(photon: string, method: string, params?: Record<string, unknown>, ttl?: number): Task;
 export declare function getTask(id: string): Task | null;
-export declare function updateTask(id: string, updates: Partial<Pick<Task, 'state' | 'progress' | 'result' | 'error'>>): Task | null;
+export declare function updateTask(id: string, updates: Partial<Pick<Task, 'state' | 'statusMessage' | 'progress' | 'result' | 'error' | 'input'>>): Task | null;
 export declare function listTasks(photon?: string): Task[];
-export declare function cleanExpiredTasks(maxAgeMs: number): number;
+/**
+ * Clean expired tasks — removes terminal tasks past their TTL
+ * and also removes non-terminal tasks that have been alive longer than their TTL
+ */
+export declare function cleanExpiredTasks(): number;
 /** Override tasks dir for testing */
 export declare function _getTasksDir(): string;
 //# sourceMappingURL=store.d.ts.map

package/dist/tasks/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/tasks/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAgBvC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI,CAEpF;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEzE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAcjG;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAS/C;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAC,GACtE,IAAI,GAAG,IAAI,CAMb;AAED,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAejD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAqB1D;AAED,qCAAqC;AACrC,wBAAgB,YAAY,IAAI,MAAM,CAErC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/tasks/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,KAAK,IAAI,EAAuD,MAAM,YAAY,CAAC;AAkB5F,2CAA2C;AAC3C,eAAO,MAAM,UAAU,uBAAqB,CAAC;AAM7C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,GAAG,IAAI,CAEpF;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEzE;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,CAAC,EAAE,MAAM,GACX,IAAI,CAkBN;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAS/C;AAED,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CACd,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,CAClF,GACA,IAAI,GAAG,IAAI,CAcb;AAED,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAejD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CA+B1C;AAED,qCAAqC;AACrC,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/tasks/store.js

@@ -1,16 +1,22 @@
 /**
- * MCP Task Store
+ * MCP Task Store (spec v2025-11-25)
  *
  * File-based persistence at ~/.photon/tasks/.
  * Each task is a JSON file: {taskId}.json
- * Consistent with existing photon file-based patterns (audit, runs, state).
+ * EventEmitter for state change notifications.
  */
 import { mkdirSync, readdirSync, unlinkSync, existsSync } from 'fs';
 import { readJSONSync, writeJSONSync } from '../shared/io.js';
 import { join } from 'path';
-import { homedir } from 'os';
 import { randomUUID } from 'crypto';
-const TASKS_DIR = join(homedir(), '.photon', 'tasks');
+import { EventEmitter } from 'events';
+import { TERMINAL_STATES, DEFAULT_TTL, DEFAULT_POLL_INTERVAL } from './types.js';
+import { getTasksDir, getLegacyTasksDir } from '@portel/photon-core';
+// Tasks are ephemeral/global — use .data/tasks/
+// Check legacy path for existing tasks during migration
+const newDir = getTasksDir();
+const legacyDir = getLegacyTasksDir();
+const TASKS_DIR = existsSync(newDir) ? newDir : existsSync(legacyDir) ? legacyDir : newDir;
 /** Ensure tasks directory exists (idempotent) */
 function ensureDir() {
     mkdirSync(TASKS_DIR, { recursive: true });
@@ -18,6 +24,9 @@ function ensureDir() {
 function taskPath(id) {
     return join(TASKS_DIR, `${id}.json`);
 }
+/** Event emitter for task state changes */
+export const taskEvents = new EventEmitter();
+taskEvents.setMaxListeners(50); // Multiple SSE sessions may listen
 /** Active task AbortControllers for cancellation */
 const activeControllers = new Map();
 export function registerController(taskId, controller) {
@@ -29,7 +38,7 @@ export function unregisterController(taskId) {
 export function getController(taskId) {
     return activeControllers.get(taskId);
 }
-export function createTask(photon, method, params) {
+export function createTask(photon, method, params, ttl) {
     ensureDir();
     const now = new Date().toISOString();
     const task = {
@@ -38,10 +47,14 @@ export function createTask(photon, method, params) {
         method,
         params,
         state: 'working',
+        statusMessage: 'The operation is now in progress.',
+        ttl: ttl ?? DEFAULT_TTL,
+        pollInterval: DEFAULT_POLL_INTERVAL,
         createdAt: now,
         updatedAt: now,
     };
     writeJSONSync(taskPath(task.id), task);
+    taskEvents.emit('stateChange', task.id, task.state, task);
     return task;
 }
 export function getTask(id) {
@@ -60,8 +73,13 @@ export function updateTask(id, updates) {
     const task = getTask(id);
     if (!task)
         return null;
+    const oldState = task.state;
     Object.assign(task, updates, { updatedAt: new Date().toISOString() });
     writeJSONSync(taskPath(id), task);
+    // Emit on any state transition
+    if (updates.state && updates.state !== oldState) {
+        taskEvents.emit('stateChange', id, task.state, task);
+    }
     return task;
 }
 export function listTasks(photon) {
@@ -81,7 +99,11 @@ export function listTasks(photon) {
     }
     return tasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 }
-export function cleanExpiredTasks(maxAgeMs) {
+/**
+ * Clean expired tasks — removes terminal tasks past their TTL
+ * and also removes non-terminal tasks that have been alive longer than their TTL
+ */
+export function cleanExpiredTasks() {
     ensureDir();
     const files = readdirSync(TASKS_DIR).filter((f) => f.endsWith('.json'));
     const now = Date.now();
@@ -89,11 +111,24 @@ export function cleanExpiredTasks(maxAgeMs) {
     for (const file of files) {
         try {
             const task = readJSONSync(join(TASKS_DIR, file));
-            const age = now - new Date(task.updatedAt).getTime();
-            if (age > maxAgeMs &&
-                (task.state === 'completed' || task.state === 'failed' || task.state === 'cancelled')) {
-                unlinkSync(join(TASKS_DIR, file));
-                cleaned++;
+            const age = now - new Date(task.createdAt).getTime();
+            const ttl = task.ttl || DEFAULT_TTL;
+            if (age > ttl) {
+                // Terminal tasks: always clean
+                // Non-terminal tasks past TTL: force-cancel and clean
+                if (TERMINAL_STATES.includes(task.state)) {
+                    unlinkSync(join(TASKS_DIR, file));
+                    cleaned++;
+                }
+                else {
+                    // Force-cancel stale non-terminal tasks
+                    const controller = getController(task.id);
+                    if (controller)
+                        controller.abort();
+                    unregisterController(task.id);
+                    unlinkSync(join(TASKS_DIR, file));
+                    cleaned++;
+                }
             }
         }
         catch {
@@ -106,4 +141,14 @@ export function cleanExpiredTasks(maxAgeMs) {
 export function _getTasksDir() {
     return TASKS_DIR;
 }
+// Startup cleanup
+try {
+    const cleaned = cleanExpiredTasks();
+    if (cleaned > 0) {
+        console.error(`🗑️  Cleaned ${cleaned} expired task(s)`);
+    }
+}
+catch {
+    // Best effort
+}
 //# sourceMappingURL=store.js.map

package/dist/tasks/store.js.map

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

package/dist/tasks/types.d.ts

@@ -1,24 +1,45 @@
 /**
- * MCP Tasks Types
+ * MCP Tasks Types (spec v2025-11-25)
  *
- * Task state machine for async long-running operations (MCP 2025-11-25 spec).
+ * Task state machine for async long-running operations.
  * States: working → completed | failed | cancelled
  *         working → input_required → working (when resuming)
  */
 export type TaskState = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+export declare const TERMINAL_STATES: readonly TaskState[];
+export declare const DEFAULT_TTL: number;
+export declare const DEFAULT_POLL_INTERVAL = 2000;
 export interface Task {
     id: string;
     photon: string;
     method: string;
     params?: Record<string, unknown>;
     state: TaskState;
+    statusMessage?: string;
+    ttl: number;
+    pollInterval: number;
     progress?: {
         percent: number;
         message?: string;
     };
     result?: unknown;
     error?: string;
+    input?: unknown;
     createdAt: string;
     updatedAt: string;
 }
+/** MCP wire format — field names match the spec exactly */
+export interface TaskWire {
+    taskId: string;
+    status: TaskState;
+    statusMessage?: string;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttl: number;
+    pollInterval: number;
+}
+/** Convert internal Task to MCP wire format */
+export declare function toWireFormat(task: Task): TaskWire;
+/** The _meta field for task-related messages */
+export declare function relatedTaskMeta(taskId: string): Record<string, unknown>;
 //# sourceMappingURL=types.d.ts.map

package/dist/tasks/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tasks/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5F,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tasks/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,gBAAgB,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5F,eAAO,MAAM,eAAe,EAAE,SAAS,SAAS,EAAyC,CAAC;AAE1F,eAAO,MAAM,WAAW,QAA0B,CAAC;AACnD,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,EAAE,SAAS,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,+CAA+C;AAC/C,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAUjD;AAED,gDAAgD;AAChD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIvE"}

package/dist/tasks/types.js

@@ -1,9 +1,29 @@
 /**
- * MCP Tasks Types
+ * MCP Tasks Types (spec v2025-11-25)
  *
- * Task state machine for async long-running operations (MCP 2025-11-25 spec).
+ * Task state machine for async long-running operations.
  * States: working → completed | failed | cancelled
  *         working → input_required → working (when resuming)
  */
-export {};
+export const TERMINAL_STATES = ['completed', 'failed', 'cancelled'];
+export const DEFAULT_TTL = 7 * 24 * 60 * 60 * 1000; // 1 week
+export const DEFAULT_POLL_INTERVAL = 2000; // 2 seconds
+/** Convert internal Task to MCP wire format */
+export function toWireFormat(task) {
+    return {
+        taskId: task.id,
+        status: task.state,
+        ...(task.statusMessage && { statusMessage: task.statusMessage }),
+        createdAt: task.createdAt,
+        lastUpdatedAt: task.updatedAt,
+        ttl: task.ttl,
+        pollInterval: task.pollInterval,
+    };
+}
+/** The _meta field for task-related messages */
+export function relatedTaskMeta(taskId) {
+    return {
+        'io.modelcontextprotocol/related-task': { taskId },
+    };
+}
 //# sourceMappingURL=types.js.map

package/dist/tasks/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tasks/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tasks/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,MAAM,eAAe,GAAyB,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;AAE1F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,SAAS;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC,CAAC,YAAY;AA8BvD,+CAA+C;AAC/C,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,MAAM,EAAE,IAAI,CAAC,KAAK;QAClB,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;QAChE,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,SAAS;QAC7B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC;AACJ,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,OAAO;QACL,sCAAsC,EAAE,EAAE,MAAM,EAAE;KACnD,CAAC;AACJ,CAAC"}

package/dist/version-notify.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Version Upgrade Notification
+ *
+ * Checks npm registry for newer versions and displays an unobtrusive notice
+ * with changelog highlights. Non-blocking — spawns a detached child process
+ * on cache miss so CLI startup is never delayed.
+ *
+ * Cache: .data/.version-check.json (24h TTL)
+ * Notice: shown once per new version (tracks notifiedVersion)
+ */
+/**
+ * Spawn a detached background process that fetches the latest version
+ * and changelog, then writes the cache file. The parent process does
+ * not wait for this — CLI exits immediately.
+ */
+export declare function refreshUpdateCache(): void;
+/**
+ * Show update notice to stderr if a newer version is available.
+ *
+ * Returns silently if:
+ * - No cache exists (background refresh hasn't completed yet)
+ * - Current version is up to date
+ * - Already notified for this version
+ * - Running in MCP STDIO mode
+ */
+export declare function showUpdateNotice(): void;
+//# sourceMappingURL=version-notify.d.ts.map

package/dist/version-notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-notify.d.ts","sourceRoot":"","sources":["../src/version-notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA2DH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAwCzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CA6BvC"}

package/dist/version-notify.js

@@ -0,0 +1,142 @@
+/**
+ * Version Upgrade Notification
+ *
+ * Checks npm registry for newer versions and displays an unobtrusive notice
+ * with changelog highlights. Non-blocking — spawns a detached child process
+ * on cache miss so CLI startup is never delayed.
+ *
+ * Cache: .data/.version-check.json (24h TTL)
+ * Notice: shown once per new version (tracks notifiedVersion)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { getDataRoot } from '@portel/photon-core';
+import { PHOTON_VERSION } from './version.js';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+function getCachePath() {
+    return path.join(getDataRoot(), '.version-check.json');
+}
+function readCache() {
+    try {
+        const cachePath = getCachePath();
+        if (!fs.existsSync(cachePath))
+            return null;
+        return JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cache) {
+    try {
+        const cachePath = getCachePath();
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+    }
+    catch {
+        // Best effort
+    }
+}
+function isStale(cache) {
+    const checkedAt = new Date(cache.checkedAt).getTime();
+    return Date.now() - checkedAt > CACHE_TTL_MS;
+}
+/**
+ * Compare two semver strings.
+ * Returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareSemver(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] || 0) > (pb[i] || 0))
+            return 1;
+        if ((pa[i] || 0) < (pb[i] || 0))
+            return -1;
+    }
+    return 0;
+}
+/**
+ * Spawn a detached background process that fetches the latest version
+ * and changelog, then writes the cache file. The parent process does
+ * not wait for this — CLI exits immediately.
+ */
+export function refreshUpdateCache() {
+    const cache = readCache();
+    if (cache && !isStale(cache))
+        return;
+    const cachePath = getCachePath();
+    const script = `
+    const fs = require('fs');
+    const { execSync } = require('child_process');
+
+    let latest = null;
+    try {
+      latest = execSync('npm view @portel/photon version', {
+        encoding: 'utf-8', timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+    } catch { process.exit(0); }
+
+    if (!latest) process.exit(0);
+
+    const existing = (() => {
+      try { return JSON.parse(fs.readFileSync(${JSON.stringify(cachePath)}, 'utf-8')); }
+      catch { return {}; }
+    })();
+    const data = {
+      latest,
+      checkedAt: new Date().toISOString(),
+      notifiedVersion: existing.notifiedVersion || undefined,
+    };
+    try {
+      fs.mkdirSync(require('path').dirname(${JSON.stringify(cachePath)}), { recursive: true });
+      fs.writeFileSync(${JSON.stringify(cachePath)}, JSON.stringify(data, null, 2));
+    } catch {}
+  `;
+    // Spawn detached — parent doesn't wait
+    const child = spawn(process.execPath, ['-e', script], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+}
+/**
+ * Show update notice to stderr if a newer version is available.
+ *
+ * Returns silently if:
+ * - No cache exists (background refresh hasn't completed yet)
+ * - Current version is up to date
+ * - Already notified for this version
+ * - Running in MCP STDIO mode
+ */
+export function showUpdateNotice() {
+    if (process.env.PHOTON_TRANSPORT === 'stdio')
+        return;
+    const cache = readCache();
+    if (!cache)
+        return;
+    if (compareSemver(cache.latest, PHOTON_VERSION) <= 0)
+        return;
+    if (cache.notifiedVersion === cache.latest)
+        return;
+    const current = PHOTON_VERSION;
+    const latest = cache.latest;
+    const lines = [];
+    lines.push(`  Update available: ${current} → ${latest}`);
+    lines.push(`  Update:    photon update`);
+    lines.push(`  What's new: photon changelog`);
+    const width = Math.max(...lines.map((l) => l.length)) + 2;
+    const pad = (s) => s + ' '.repeat(Math.max(0, width - s.length));
+    console.error('');
+    console.error(`╭${'─'.repeat(width)}╮`);
+    for (const line of lines) {
+        console.error(`│${pad(line)}│`);
+    }
+    console.error(`╰${'─'.repeat(width)}╯`);
+    // Mark as notified so we don't show again for this version
+    cache.notifiedVersion = cache.latest;
+    writeCache(cache);
+}
+//# sourceMappingURL=version-notify.js.map

package/dist/version-notify.js.map

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