@portel/photon-core 2.21.0 → 2.23.0

package/src/base.ts

@@ -636,11 +636,45 @@ export class Photon {
         return result;
       } catch (error: any) {
         console.error(`Tool execution failed: ${toolName} - ${error.message}`);
+        await this._invokeErrorHook(error, { tool: toolName, params: parameters });
         throw error;
       }
     });
   }
 
+  /**
+   * Invoke the onError observability hook with a bounded timeout. Never
+   * suppresses the original error and never throws itself — a throw or
+   * timeout inside the hook is logged and swallowed so observability code
+   * can never cascade into the request path.
+   */
+  private async _invokeErrorHook(
+    error: unknown,
+    ctx: { tool: string; params: any }
+  ): Promise<void> {
+    const hook = (this as any).onError;
+    if (typeof hook !== 'function') return;
+    const TIMEOUT_MS = 5000;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        Promise.resolve(hook.call(this, error, ctx)),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(
+            () => reject(new Error(`onError hook exceeded ${TIMEOUT_MS}ms`)),
+            TIMEOUT_MS
+          );
+        }),
+      ]);
+    } catch (hookError: any) {
+      console.error(
+        `onError hook failed for ${ctx.tool}: ${hookError?.message ?? String(hookError)}`
+      );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
   /**
    * Optional lifecycle hooks
    */
@@ -654,6 +688,15 @@ export class Photon {
    * During hot-reload, receives context so you can skip resource cleanup.
    */
   async onShutdown?(ctx?: { reason?: string }): Promise<void>;
+  /**
+   * Called when any tool method throws. Observability only — the hook
+   * cannot suppress or transform the error. A throw or timeout inside
+   * the hook is logged and swallowed. Default timeout is 5s.
+   *
+   * Use it for centralized logging, metrics, or error reporting instead
+   * of wrapping every method in try/catch.
+   */
+  async onError?(error: unknown, ctx: { tool: string; params: any }): Promise<void>;
 
   /**
    * Get an MCP client for calling external MCP servers

package/src/bases-registry.ts

@@ -0,0 +1,141 @@
+/**
+ * Bases Registry
+ *
+ * Tracks every PHOTON_DIR the daemon has served. The daemon upserts an
+ * entry on every photon invocation and, on startup, scans each surviving
+ * base for long-lived per-photon state (schedules, etc.) that must be
+ * reinstated across restarts.
+ *
+ * The registry itself is daemon infrastructure and lives at the global
+ * path `~/.photon/.data/.bases.json`. The data it points at is NOT — each
+ * listed base owns its own data under `{base}/.data/`.
+ *
+ * See docs/internals/PHOTON-DIR-AND-NAMESPACE.md §8.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { getBasesRegistryPath } from './data-paths.js';
+
+export interface BaseRegistryEntry {
+  /** Absolute, resolved path to the PHOTON_DIR. */
+  path: string;
+  /** ISO-8601 timestamp of first record. */
+  firstSeen: string;
+  /** ISO-8601 timestamp of most recent invocation. */
+  lastSeen: string;
+}
+
+export interface BasesRegistry {
+  bases: BaseRegistryEntry[];
+}
+
+const EMPTY_REGISTRY: BasesRegistry = { bases: [] };
+
+function normalizeBase(basePath: string): string {
+  return path.resolve(basePath);
+}
+
+/**
+ * Read the registry from disk. Returns an empty registry if the file is
+ * missing or malformed. Never throws for absent data.
+ */
+export function readBasesRegistry(): BasesRegistry {
+  const file = getBasesRegistryPath();
+  let raw: string;
+  try {
+    raw = fs.readFileSync(file, 'utf-8');
+  } catch {
+    return { bases: [] };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.bases)) return { bases: [] };
+    // Trust the shape but filter out entries that are obviously broken.
+    const bases = parsed.bases.filter(
+      (b: any) =>
+        b &&
+        typeof b.path === 'string' &&
+        typeof b.firstSeen === 'string' &&
+        typeof b.lastSeen === 'string'
+    );
+    return { bases };
+  } catch {
+    return { bases: [] };
+  }
+}
+
+/**
+ * Write the registry to disk atomically. Creates the parent directory if
+ * needed. Uses a temp-file + rename pattern so readers never observe a
+ * half-written file.
+ */
+export function writeBasesRegistry(registry: BasesRegistry): void {
+  const file = getBasesRegistryPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(registry, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Upsert a base with a fresh `lastSeen`. Sets `firstSeen` on new entries.
+ * Safe to call on every photon invocation — cost is one JSON round-trip
+ * per call.
+ */
+export function touchBase(basePath: string, now: Date = new Date()): void {
+  const normalized = normalizeBase(basePath);
+  const iso = now.toISOString();
+  const registry = readBasesRegistry();
+  const existing = registry.bases.find((b) => b.path === normalized);
+  if (existing) {
+    existing.lastSeen = iso;
+  } else {
+    registry.bases.push({ path: normalized, firstSeen: iso, lastSeen: iso });
+  }
+  writeBasesRegistry(registry);
+}
+
+/**
+ * Return registry entries whose path still exists on disk as a directory.
+ * Entries whose path cannot be confirmed (permission errors, unmounted
+ * drives, transient failures) are KEPT — we only filter on confirmed
+ * absence, so a momentarily-unreachable path does not get silently
+ * dropped.
+ */
+export function listActiveBases(): BaseRegistryEntry[] {
+  const registry = readBasesRegistry();
+  return registry.bases.filter((b) => {
+    try {
+      return fs.statSync(b.path).isDirectory();
+    } catch (err: any) {
+      // Only treat "does not exist" as inactive. Other errors keep the entry.
+      return err?.code !== 'ENOENT';
+    }
+  });
+}
+
+/**
+ * Remove entries whose path is confirmed absent on disk (ENOENT only).
+ * Writes the pruned registry back. Returns the list of entries that were
+ * removed so callers can log them.
+ */
+export function pruneBasesRegistry(): BaseRegistryEntry[] {
+  const registry = readBasesRegistry();
+  const removed: BaseRegistryEntry[] = [];
+  const kept: BaseRegistryEntry[] = [];
+  for (const b of registry.bases) {
+    let confirmedAbsent = false;
+    try {
+      fs.statSync(b.path);
+    } catch (err: any) {
+      if (err?.code === 'ENOENT') confirmedAbsent = true;
+    }
+    if (confirmedAbsent) removed.push(b);
+    else kept.push(b);
+  }
+  if (removed.length > 0) {
+    writeBasesRegistry({ bases: kept });
+  }
+  return removed;
+}

package/src/data-paths.ts

@@ -31,10 +31,16 @@ import * as path from 'path';
 import * as os from 'os';
 import { execSync } from 'child_process';
 
-const DEFAULT_BASE = path.join(os.homedir(), '.photon');
+/**
+ * Default PHOTON_DIR when none is explicitly resolved: the user's home
+ * `.photon` directory. Single source of truth — path-resolver.ts and
+ * photon/src/context.ts re-export this so there is exactly one constant
+ * for the concept.
+ */
+export const DEFAULT_PHOTON_DIR = path.join(os.homedir(), '.photon');
 
 function getBase(baseDir?: string): string {
-  return baseDir || process.env.PHOTON_DIR || DEFAULT_BASE;
+  return baseDir || process.env.PHOTON_DIR || DEFAULT_PHOTON_DIR;
 }
 
 // ── Root ─────────────────────────────────────────────────────────────────────
@@ -142,17 +148,33 @@ export function getDaemonSocketPath(): string {
   if (process.platform === 'win32') {
     return '\\\\.\\pipe\\photon-daemon';
   }
-  return path.join(DEFAULT_BASE, '.data', 'daemon.sock');
+  return path.join(DEFAULT_PHOTON_DIR, '.data', 'daemon.sock');
 }
 
 /** Daemon PID file: always ~/.photon/.data/daemon.pid */
 export function getDaemonPidPath(): string {
-  return path.join(DEFAULT_BASE, '.data', 'daemon.pid');
+  return path.join(DEFAULT_PHOTON_DIR, '.data', 'daemon.pid');
 }
 
 /** Daemon log file: always ~/.photon/.data/daemon.log */
 export function getDaemonLogPath(): string {
-  return path.join(DEFAULT_BASE, '.data', 'daemon.log');
+  return path.join(DEFAULT_PHOTON_DIR, '.data', 'daemon.log');
+}
+
+/**
+ * Bases registry: always ~/.photon/.data/.bases.json (global, one per user).
+ *
+ * The daemon maintains this file to track every PHOTON_DIR it has served.
+ * On startup it reads the registry and scans each base for schedules and
+ * other long-lived per-photon state that must survive daemon restarts.
+ *
+ * The `PHOTON_BASES_REGISTRY` env var exists as a test-only override;
+ * production always uses the fixed global path.
+ *
+ * See docs/internals/PHOTON-DIR-AND-NAMESPACE.md §8.
+ */
+export function getBasesRegistryPath(): string {
+  return process.env.PHOTON_BASES_REGISTRY ?? path.join(DEFAULT_PHOTON_DIR, '.data', '.bases.json');
 }
 
 // ── Namespace Detection ──────────────────────────────────────────────────────
@@ -165,6 +187,11 @@ export function getDaemonLogPath(): string {
  *   git@github.com:portel-dev/photons.git     → 'portel-dev'
  *   https://github.com/arul-kumar/my-photons  → 'arul-kumar'
  *   (no git remote)                           → ''
+ *
+ * @deprecated Under Option B the namespace is a pure function of the
+ *   photon file's position relative to PHOTON_DIR; git state must never
+ *   influence data paths. Scheduled for removal in the next minor release.
+ *   See docs/internals/PHOTON-DIR-AND-NAMESPACE.md §3.
  */
 export function detectNamespace(dir: string): string {
   try {
@@ -228,62 +255,29 @@ export function getLegacySessionMemoryDir(sessionId: string, photonName: string,
   return path.join(getBase(baseDir), 'sessions', safeSession, safeName);
 }
 
-/** Old runs dir: ~/.photon/runs/ */
-export function getLegacyRunsDir(): string {
-  return path.join(DEFAULT_BASE, 'runs');
-}
-
-/** Old logs dir: ~/.photon/logs/{photonId}/ */
-export function getLegacyLogsDir(photonName: string): string {
-  return path.join(DEFAULT_BASE, 'logs', photonName);
-}
-
-/** Old tasks dir: ~/.photon/tasks/ */
-export function getLegacyTasksDir(): string {
-  return path.join(DEFAULT_BASE, 'tasks');
-}
-
-/** Old audit path: ~/.photon/audit.jsonl */
-export function getLegacyAuditPath(): string {
-  return path.join(DEFAULT_BASE, 'audit.jsonl');
-}
-
-/** Old metadata path: {baseDir}/.metadata.json */
-export function getLegacyMetadataPath(baseDir?: string): string {
-  return path.join(getBase(baseDir), '.metadata.json');
-}
-
-/** Old daemon socket: ~/.photon/daemon.sock */
-export function getLegacyDaemonSocketPath(): string {
-  if (process.platform === 'win32') {
-    return '\\\\.\\pipe\\photon-daemon';
-  }
-  return path.join(DEFAULT_BASE, 'daemon.sock');
-}
-
-/** Old daemon PID: ~/.photon/daemon.pid */
-export function getLegacyDaemonPidPath(): string {
-  return path.join(DEFAULT_BASE, 'daemon.pid');
+/** Old runs dir: {baseDir}/runs/ */
+export function getLegacyRunsDir(baseDir?: string): string {
+  return path.join(getBase(baseDir), 'runs');
 }
 
-/** Old daemon log: ~/.photon/daemon.log */
-export function getLegacyDaemonLogPath(): string {
-  return path.join(DEFAULT_BASE, 'daemon.log');
+/** Old logs dir: {baseDir}/logs/{photonId}/ */
+export function getLegacyLogsDir(photonName: string, baseDir?: string): string {
+  return path.join(getBase(baseDir), 'logs', photonName);
 }
 
-/** Old cache dir: {baseDir}/.cache/ or {baseDir}/cache/ */
-export function getLegacyCacheDir(baseDir?: string): string {
-  return path.join(getBase(baseDir), '.cache');
+/** Old tasks dir: {baseDir}/tasks/ */
+export function getLegacyTasksDir(baseDir?: string): string {
+  return path.join(getBase(baseDir), 'tasks');
 }
 
 /** Old schedules dir: ~/.photon/schedules/{photonName}/ */
 export function getLegacySchedulesDir(photonName: string): string {
   const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
-  return path.join(DEFAULT_BASE, 'schedules', safeName);
+  return path.join(DEFAULT_PHOTON_DIR, 'schedules', safeName);
 }
 
 /** Old per-photon config: ~/.photon/{photonName}/config.json */
 export function getLegacyPhotonConfigPath(photonName: string): string {
   const safeName = photonName.replace(/[^a-zA-Z0-9_-]/g, '_');
-  return path.join(DEFAULT_BASE, safeName, 'config.json');
+  return path.join(DEFAULT_PHOTON_DIR, safeName, 'config.json');
 }

package/src/index.ts

@@ -172,6 +172,7 @@ export {
   resolvePhotonPath,
   listPhotonFiles,
   listPhotonFilesWithNamespace,
+  listPhotonSourceFiles,
   ensurePhotonDir,
   DEFAULT_PHOTON_DIR,
   type ResolverOptions,
@@ -494,7 +495,14 @@ export {
 
 // ===== PHOTON LOADER LITE =====
 // Direct TypeScript API for loading .photon.ts files with full enhancements
-export { photon, clearPhotonCache, type PhotonOptions, type PhotonEvent } from './photon-loader-lite.js';
+export {
+  photon,
+  clearPhotonCache,
+  disposePhoton,
+  disposeAllPhotons,
+  type PhotonOptions,
+  type PhotonEvent,
+} from './photon-loader-lite.js';
 
 // ===== FILE WATCHING =====
 // Reusable photon file watcher with symlink resolution, debouncing, rename handling
@@ -592,3 +600,8 @@ export {
 // ===== DATA PATHS =====
 // Central data path resolver — single source of truth for all runtime data locations
 export * from './data-paths.js';
+
+// ===== BASES REGISTRY =====
+// Daemon-owned registry of every PHOTON_DIR served. Used to discover schedules
+// and other per-base data on daemon startup. See data-paths getBasesRegistryPath.
+export * from './bases-registry.js';

package/src/memory.ts

@@ -27,6 +27,7 @@ import {
   getLegacyMemoryDir,
   getLegacyGlobalMemoryDir,
   getLegacySessionMemoryDir,
+  getDataRoot,
 } from './data-paths.js';
 
 export type MemoryScope = 'photon' | 'session' | 'global';
@@ -216,6 +217,83 @@ export class FileMemoryBackend implements MemoryBackend {
 // SCOPE RESOLUTION
 // ════════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Compatibility shim — one-release migration only.
+ *
+ * Under docs/internals/PHOTON-DIR-AND-NAMESPACE.md the namespace comes
+ * purely from directory position and never changes silently. But installs
+ * that ran with the old git-remote-based namespace detection may have data
+ * sitting under a stale namespace bucket. On first read, if the canonical
+ * dir is empty but exactly one sibling namespace contains this photon's
+ * memory, migrate it atomically to the canonical location.
+ *
+ * Multiple matches → ambiguous; warn to stderr so the user can consolidate
+ * manually rather than proceeding with empty memory.
+ *
+ * @deprecated Remove this helper and its caller one release after the
+ *   PHOTON_DIR-and-namespace change ships.
+ */
+function findAndMigrateStrandedMemory(
+  photonId: string,
+  canonicalDir: string,
+  baseDir?: string
+): string | null {
+  const dataRoot = getDataRoot(baseDir);
+  let entries: string[];
+  try {
+    entries = fsSync.readdirSync(dataRoot);
+  } catch {
+    return null;
+  }
+
+  const matches: string[] = [];
+  for (const entry of entries) {
+    // Skip non-namespace buckets. `_global`, `_sessions`, `.cache`, `tasks`
+    // live at the same level but are reserved names.
+    if (entry.startsWith('_') || entry.startsWith('.') || entry === 'tasks') continue;
+    const candidate = path.join(dataRoot, entry, photonId, 'memory');
+    try {
+      const stat = fsSync.statSync(candidate);
+      if (stat.isDirectory()) {
+        // Only count non-empty dirs as real data.
+        if (fsSync.readdirSync(candidate).length > 0) matches.push(candidate);
+      }
+    } catch {
+      // Not a match, continue.
+    }
+  }
+
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    process.stderr.write(
+      `[photon] warning: photon '${photonId}' has memory data stranded under multiple namespaces:\n` +
+        matches.map((m) => `  - ${m}`).join('\n') +
+        `\n  Canonical path is ${canonicalDir}.\n` +
+        `  Move the correct one into the canonical path and delete the others to consolidate.\n`
+    );
+    return null;
+  }
+
+  const stranded = matches[0];
+  try {
+    fsSync.mkdirSync(path.dirname(canonicalDir), { recursive: true });
+    fsSync.renameSync(stranded, canonicalDir);
+    // Clean up now-empty parent if it has no siblings.
+    try {
+      const strandedParent = path.dirname(stranded);
+      if (fsSync.readdirSync(strandedParent).length === 0) fsSync.rmdirSync(strandedParent);
+      const strandedNs = path.dirname(strandedParent);
+      if (fsSync.readdirSync(strandedNs).length === 0) fsSync.rmdirSync(strandedNs);
+    } catch {
+      // Non-fatal: leave parent dirs if cleanup fails.
+    }
+    return canonicalDir;
+  } catch {
+    // Cross-device rename or permission issue — fall back to reading in place.
+    return stranded;
+  }
+}
+
 function resolveDir(
   photonId: string,
   namespace: string,
@@ -229,6 +307,9 @@ function resolveDir(
       if (!fsSync.existsSync(newDir)) {
         const legacyDir = getLegacyMemoryDir(photonId, baseDir);
         if (fsSync.existsSync(legacyDir)) return legacyDir;
+        // Last resort: data stranded under a different namespace bucket.
+        const recovered = findAndMigrateStrandedMemory(photonId, newDir, baseDir);
+        if (recovered) return recovered;
       }
       return newDir;
     }

package/src/middleware.ts

@@ -626,6 +626,54 @@ const retryableMiddleware = defineMiddleware<{ count: number; delay: number }>({
   },
 });
 
+// --- bulkhead (phase 15) ---
+// Caps concurrent in-flight executions per photon:instance:tool. Unlike
+// @throttled (which rate-limits over a time window), bulkhead protects
+// downstream resources from being overwhelmed by concurrent load.
+// Fast-fails when the cap is hit — callers should back off or queue.
+
+interface BulkheadStateEntry {
+  inFlight: number;
+}
+
+const bulkheadMiddleware = defineMiddleware<{ maxConcurrent: number }>({
+  name: 'bulkhead',
+  phase: 15,
+  parseShorthand(value: string) {
+    return { maxConcurrent: Math.max(1, parseInt(value.trim(), 10) || 1) };
+  },
+  parseConfig(raw) {
+    return {
+      maxConcurrent: Math.max(1, parseInt(raw.maxConcurrent || raw.max || '1', 10)),
+    };
+  },
+  create(config, state) {
+    return async (ctx, next) => {
+      const key = `${ctx.photon}:${ctx.instance}:${ctx.tool}`;
+      let entry = state.get<BulkheadStateEntry>(key);
+      if (!entry) {
+        entry = { inFlight: 0 };
+        state.set(key, entry);
+      }
+
+      if (entry.inFlight >= config.maxConcurrent) {
+        const error = new Error(
+          `Bulkhead full: ${ctx.photon}.${ctx.tool} has ${entry.inFlight} concurrent executions (cap: ${config.maxConcurrent})`
+        );
+        error.name = 'PhotonBulkheadFullError';
+        throw error;
+      }
+
+      entry.inFlight++;
+      try {
+        return await next();
+      } finally {
+        entry.inFlight = Math.max(0, entry.inFlight - 1);
+      }
+    };
+  },
+});
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // GLOBAL BUILT-IN REGISTRY
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -634,6 +682,7 @@ export const builtinRegistry = new MiddlewareRegistry();
 builtinRegistry.register(fallbackMiddleware);
 builtinRegistry.register(loggedMiddleware);
 builtinRegistry.register(circuitBreakerMiddleware);
+builtinRegistry.register(bulkheadMiddleware);
 builtinRegistry.register(throttledMiddleware);
 builtinRegistry.register(debouncedMiddleware);
 builtinRegistry.register(cachedMiddleware);

package/src/path-resolver.ts

@@ -18,7 +18,10 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 
-export const DEFAULT_PHOTON_DIR = path.join(os.homedir(), '.photon');
+import { DEFAULT_PHOTON_DIR } from './data-paths.js';
+// Re-exported so existing `import { DEFAULT_PHOTON_DIR } from '@portel/photon-core'`
+// callers keep working. One canonical definition lives in data-paths.ts.
+export { DEFAULT_PHOTON_DIR };
 
 /**
  * Expand tilde (~) to user's home directory
@@ -53,6 +56,28 @@ const SKIP_DIRS = new Set([
   'node_modules', 'marketplace', 'photons', 'templates',
 ]);
 
+/**
+ * List photon source file names in a directory. Returns just filenames
+ * (not full paths) so callers can choose to either join with the dir
+ * or operate on the basename directly. Missing/unreadable dirs return [].
+ *
+ * Replaces scattered `readdirSync(dir).filter(f => f.endsWith('.photon.ts'))`
+ * expressions so the default extension list stays consistent.
+ */
+export function listPhotonSourceFiles(
+  dir: string,
+  options?: { extensions?: string[] },
+): string[] {
+  const extensions = options?.extensions ?? defaultOptions.extensions;
+  try {
+    return fsSync
+      .readdirSync(dir)
+      .filter((f) => extensions.some((ext) => f.endsWith(ext)));
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Resolve a file path from name.
  *