@portel/photon-core 2.22.0 → 2.24.0

package/src/index.ts

@@ -162,6 +162,12 @@ export { DependencyManager } from './dependency-manager.js';
 
 // Schema extraction
 export { SchemaExtractor, detectCapabilities, type PhotonCapability } from './schema-extractor.js';
+export {
+  sanitizeDescription,
+  MAX_DESCRIPTION_LENGTH,
+  type SanitizerWarning,
+  type SanitizeResult,
+} from './description-sanitizer.js';
 
 // Path resolution (Photon-specific paths)
 export {
@@ -172,6 +178,7 @@ export {
   resolvePhotonPath,
   listPhotonFiles,
   listPhotonFilesWithNamespace,
+  listPhotonSourceFiles,
   ensurePhotonDir,
   DEFAULT_PHOTON_DIR,
   type ResolverOptions,
@@ -494,7 +501,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 +606,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,110 @@ 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;
+  }
+}
+
+/**
+ * Photons whose loader pinned a baseDir get deterministic paths regardless
+ * of which process reads them back. When baseDir is missing, getBase()
+ * silently falls back to PHOTON_DIR env or ~/.photon, which means the same
+ * photon can write to <repo>/.data/ from a CLI process and read from
+ * ~/.photon/.data/ from a daemon worker started in a different cwd. We
+ * warn once per photon so this drift is noticeable rather than silent.
+ *
+ * To suppress in test environments where the fallback is intentional, set
+ * PHOTON_MEMORY_NO_BASEDIR_WARN=1.
+ */
+const _baseDirFallbackWarned = new Set<string>();
+function warnIfBaseDirMissing(photonId: string, baseDir?: string): void {
+  if (baseDir) return;
+  if (process.env.PHOTON_MEMORY_NO_BASEDIR_WARN) return;
+  if (_baseDirFallbackWarned.has(photonId)) return;
+  _baseDirFallbackWarned.add(photonId);
+  process.stderr.write(
+    `[photon-core] memory.resolveDir for "${photonId}" got no baseDir — ` +
+      `falling back to PHOTON_DIR env or ~/.photon. If this photon was ` +
+      `loaded with a workingDir, the loader is failing to set ` +
+      `instance._baseDir. Symptom: writes from one process land at the ` +
+      `loader's baseDir but reads from another process land at the env ` +
+      `fallback. See memory-baseDir-resolution-bug for details.\n`
+  );
+}
+
 function resolveDir(
   photonId: string,
   namespace: string,
@@ -223,12 +328,16 @@ function resolveDir(
   sessionId?: string,
   baseDir?: string
 ): string {
+  warnIfBaseDirMissing(photonId, baseDir);
   switch (scope) {
     case 'photon': {
       const newDir = getPhotonMemoryDir(namespace, photonId, baseDir);
       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

@@ -674,6 +674,102 @@ const bulkheadMiddleware = defineMiddleware<{ maxConcurrent: number }>({
   },
 });
 
+// --- mask (phase 85) ---
+// Post-execution redaction pass. Rewrites named fields in the result with
+// a masked placeholder before handoff to the transport layer. Defense
+// against oversharing and accidental PII exposure (OWASP MCP #10).
+// Runs AFTER execution, BEFORE __meta attachment (phase ≥ 85).
+
+function maskValue(value: unknown, keys: string[], placeholder: string): unknown {
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => maskValue(v, keys, placeholder));
+  }
+  if (typeof value === 'object') {
+    const src = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(src)) {
+      if (keys.includes(k)) {
+        out[k] = placeholder;
+      } else {
+        out[k] = maskValue(src[k], keys, placeholder);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+const maskMiddleware = defineMiddleware<{ fields: string[]; placeholder: string }>({
+  name: 'mask',
+  phase: 85,
+  parseShorthand(value: string) {
+    const fields = value
+      .split(/[,\s]+/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return { fields, placeholder: '[REDACTED]' };
+  },
+  parseConfig(raw) {
+    const fields = (raw.fields || '')
+      .split(/[,\s]+/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return { fields, placeholder: raw.placeholder?.trim() || '[REDACTED]' };
+  },
+  create(config, _state) {
+    return async (ctx, next) => {
+      const result = await next();
+      if (config.fields.length === 0) return result;
+      return maskValue(result, config.fields, config.placeholder);
+    };
+  },
+});
+
+// --- maxResponseBytes (phase 88) ---
+// Caps the serialized response size. Hard truncates with a warning marker.
+// Prevents context-window flooding (OWASP MCP #10) — an oversized result
+// is an attack vector on its own even when the data is legitimate.
+// Runs after @mask so the cap applies to the redacted payload.
+
+const maxResponseBytesMiddleware = defineMiddleware<{ limit: number }>({
+  name: 'maxResponseBytes',
+  phase: 88,
+  parseShorthand(value: string) {
+    return { limit: Math.max(1, parseInt(value.trim(), 10) || 0) };
+  },
+  parseConfig(raw) {
+    const v = raw.limit || raw.bytes || raw.max;
+    return { limit: Math.max(1, parseInt(v || '0', 10) || 0) };
+  },
+  create(config, _state) {
+    return async (ctx, next) => {
+      const result = await next();
+      if (!config.limit || config.limit <= 0) return result;
+      let serialized: string;
+      try {
+        serialized = typeof result === 'string' ? result : JSON.stringify(result);
+      } catch {
+        return result; // unserializable → leave untouched
+      }
+      const byteLen = Buffer.byteLength(serialized, 'utf8');
+      if (byteLen <= config.limit) return result;
+      const truncated = serialized.slice(
+        0,
+        Math.max(0, config.limit - 32)
+      );
+      return {
+        truncated: true,
+        reason: 'maxResponseBytes',
+        limit: config.limit,
+        originalBytes: byteLen,
+        tool: `${ctx.photon}.${ctx.tool}`,
+        preview: truncated,
+      };
+    };
+  },
+});
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // GLOBAL BUILT-IN REGISTRY
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -691,6 +787,8 @@ builtinRegistry.register(queuedMiddleware);
 builtinRegistry.register(lockedMiddleware);
 builtinRegistry.register(timeoutMiddleware);
 builtinRegistry.register(retryableMiddleware);
+builtinRegistry.register(maskMiddleware);
+builtinRegistry.register(maxResponseBytesMiddleware);
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // PIPELINE ASSEMBLY

package/src/mixins.ts

@@ -58,6 +58,13 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
      */
     _photonName?: string;
     _photonNamespace?: string;
+    /**
+     * PHOTON_DIR this instance was loaded from - set by runtime loader.
+     * Pinned so memory and other .data/-rooted state resolve to the same
+     * root regardless of which process reads back later.
+     * @internal
+     */
+    _baseDir?: string;
 
     /**
      * Session ID for session-scoped memory - set by runtime
@@ -113,7 +120,12 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
           .replace(/([A-Z])/g, '-$1')
           .toLowerCase()
           .replace(/^-/, '');
-        this._memory = new MemoryProvider(name, this._sessionId, this._photonNamespace);
+        this._memory = new MemoryProvider(
+          name,
+          this._sessionId,
+          this._photonNamespace,
+          this._baseDir
+        );
       }
       return this._memory;
     }
@@ -128,7 +140,7 @@ export function withPhotonCapabilities<T extends Constructor>(Base: T): T {
           .replace(/([A-Z])/g, '-$1')
           .toLowerCase()
           .replace(/^-/, '');
-        this._schedule = new ScheduleProvider(name);
+        this._schedule = new ScheduleProvider(name, this._baseDir);
       }
       return this._schedule;
     }

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.
  *