@portel/photon-core 2.23.0 → 2.25.0

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/photon-loader-lite.ts

@@ -269,6 +269,44 @@ async function loadPhotonInternal(
     // docs/internals/PHOTON-DIR-AND-NAMESPACE.md §3.
     instance._photonName = photonName;
     instance._photonNamespace = options.namespace ?? deriveNamespace(absolutePath, options.baseDir);
+    instance._baseDir = options.baseDir;
+    instance._photonFilePath = absolutePath;
+    // Stat-gate baseline. When executeTool() sees the source file has
+    // changed, it fires _photonReloader (registered just below) to swap
+    // in the fresh compile before dispatching.
+    try {
+      const s = fsSync.statSync(absolutePath);
+      instance._photonSourceStat = { mtimeMs: s.mtimeMs, size: s.size, ino: s.ino };
+    } catch {
+      // No stat — skip baselining so the gate is a no-op.
+    }
+    instance._photonReloader = async () => {
+      // Invalidate the cache entry, then re-run the whole load pipeline
+      // and copy public surface from the fresh instance onto the existing
+      // one. Callers already holding a reference to the proxy see new
+      // method behavior on the very next dispatch.
+      instanceCache.delete(cacheKey);
+      const fresh = (await photon(absolutePath, options)) as Record<string, any>;
+      // Refresh stat baseline on success so we don't re-trigger.
+      try {
+        const s = fsSync.statSync(absolutePath);
+        instance._photonSourceStat = { mtimeMs: s.mtimeMs, size: s.size, ino: s.ino };
+      } catch {
+        // ignore — next call will re-evaluate
+      }
+      // Rewire every own property from the fresh instance onto the
+      // live one. Prototype-level methods are re-looked-up through the
+      // instance's class on each dispatch via the proxy's method lookup,
+      // so they pick up the new code automatically. Own-property state
+      // (collections, explicit fields) gets refreshed here.
+      for (const key of Object.keys(fresh)) {
+        try {
+          (instance as Record<string, any>)[key] = fresh[key];
+        } catch {
+          // Read-only own property — skip; the proxy path will handle it.
+        }
+      }
+    };
     if (options.instanceName) {
       instance.instanceName = options.instanceName;
     }

package/src/schedule.ts

@@ -139,9 +139,9 @@ function resolveCron(schedule: string): string {
 
 // ── Storage Helpers ────────────────────────────────────────────────────
 
-function photonScheduleDir(photonId: string, namespace?: string): string {
+function photonScheduleDir(photonId: string, namespace?: string, baseDir?: string): string {
   const ns = namespace || 'local';
-  const newDir = getPhotonSchedulesDir(ns, photonId);
+  const newDir = getPhotonSchedulesDir(ns, photonId, baseDir);
   if (!fsSync.existsSync(newDir)) {
     const legacyDir = getLegacySchedulesDir(photonId);
     if (fsSync.existsSync(legacyDir)) return legacyDir;
@@ -149,8 +149,8 @@ function photonScheduleDir(photonId: string, namespace?: string): string {
   return newDir;
 }
 
-function taskPath(photonId: string, taskId: string): string {
-  return path.join(photonScheduleDir(photonId), `${taskId}.json`);
+function taskPath(photonId: string, taskId: string, baseDir?: string): string {
+  return path.join(photonScheduleDir(photonId, undefined, baseDir), `${taskId}.json`);
 }
 
 async function ensureDir(dir: string): Promise<void> {
@@ -163,6 +163,20 @@ async function ensureDir(dir: string): Promise<void> {
 
 // ── Schedule Provider ──────────────────────────────────────────────────
 
+/**
+ * Callback the runtime injects so `this.schedule.cancel()` (and
+ * transitively `cancelByName`, `cancelAll`) can evict the in-memory
+ * cron registration on top of unlinking the disk file. Without this,
+ * the daemon keeps firing the cancelled schedule until its next
+ * restart / first fire (where the phantom-prune check at fire time
+ * catches it as a backstop) — doubled executions in the window.
+ *
+ * The parameter is the namespaced job id the daemon uses:
+ * `${photonId}:sched:${taskId}`. Return value mirrors the daemon's
+ * `unscheduleJob` boolean (true if something was evicted).
+ */
+export type UnscheduleHook = (namespacedJobId: string) => Promise<boolean> | boolean;
+
 /**
  * Runtime Schedule Provider
  *
@@ -171,9 +185,30 @@ async function ensureDir(dir: string): Promise<void> {
  */
 export class ScheduleProvider {
   private _photonId: string;
+  private _baseDir?: string;
+  private _unscheduleHook?: UnscheduleHook;
 
-  constructor(photonId: string) {
+  /**
+   * @param photonId Photon identifier used as the bucket under .data/
+   * @param baseDir PHOTON_DIR the photon was loaded from. Pinned so
+   *   schedule files stay under this base regardless of which process
+   *   reads back later — mirrors the fix applied to MemoryProvider.
+   *   Without it, photonScheduleDir falls through to PHOTON_DIR env or
+   *   ~/.photon and schedule files drift across daemon restarts.
+   * @param unscheduleHook Runtime-injected callback that evicts the
+   *   in-memory cron registration after a disk cancel. Optional — when
+   *   absent, `cancel()` still unlinks the file and the daemon's
+   *   fire-time phantom prune is the fallback.
+   */
+  constructor(photonId: string, baseDir?: string, unscheduleHook?: UnscheduleHook) {
     this._photonId = photonId;
+    this._baseDir = baseDir;
+    this._unscheduleHook = unscheduleHook;
+  }
+
+  /** Shape the daemon keys cron jobs under — see schedule-loader.ts. */
+  private _jobId(taskId: string): string {
+    return `${this._photonId}:sched:${taskId}`;
   }
 
   /**
@@ -222,7 +257,10 @@ export class ScheduleProvider {
    */
   async get(taskId: string): Promise<ScheduledTask | null> {
     try {
-      const content = await fs.readFile(taskPath(this._photonId, taskId), 'utf-8');
+      const content = await fs.readFile(
+        taskPath(this._photonId, taskId, this._baseDir),
+        'utf-8'
+      );
       return JSON.parse(content) as ScheduledTask;
     } catch (err: any) {
       if (err.code === 'ENOENT') return null;
@@ -242,7 +280,7 @@ export class ScheduleProvider {
    * List all scheduled tasks, optionally filtered by status
    */
   async list(status?: ScheduleStatus): Promise<ScheduledTask[]> {
-    const dir = photonScheduleDir(this._photonId);
+    const dir = photonScheduleDir(this._photonId, undefined, this._baseDir);
     let files: string[];
     try {
       files = await fs.readdir(dir);
@@ -319,16 +357,59 @@ export class ScheduleProvider {
   }
 
   /**
-   * Cancel (delete) a scheduled task
+   * Cancel (delete) a scheduled task.
+   *
+   * Two steps:
+   *   1. Unlink the disk file so daemon restarts don't re-register.
+   *   2. Notify the running daemon via `unscheduleHook` so the
+   *      in-memory cron registration is evicted immediately.
+   *
+   * Without step 2, a cancel followed by a re-enable under the same
+   * name produced two in-memory registrations — the old one (never
+   * evicted) and the new one — both firing on schedule until the
+   * next daemon restart. The hook closes that window.
    */
   async cancel(taskId: string): Promise<boolean> {
+    let removed = false;
     try {
-      await fs.unlink(taskPath(this._photonId, taskId));
-      return true;
+      await fs.unlink(taskPath(this._photonId, taskId, this._baseDir));
+      removed = true;
     } catch (err: any) {
-      if (err.code === 'ENOENT') return false;
-      throw err;
+      if (err.code !== 'ENOENT') throw err;
     }
+
+    // Always call the hook — even when the file was already gone the
+    // in-memory registration might still be alive (ghost schedule from
+    // a prior session). The daemon's unschedule is idempotent, so an
+    // extra call when no registration exists is harmless.
+    //
+    // Eviction is best-effort. If the daemon is unreachable we log
+    // loudly and rely on the fire-time phantom-prune (daemon checks
+    // sourceFile before running) to catch the ghost on its next
+    // scheduled tick. For low-frequency schedules that tick may be
+    // hours away, so a silent swallow would let `cancel()` return
+    // truthy while duplicate runs continue; logging gives operators
+    // a chance to see and retry.
+    if (this._unscheduleHook) {
+      const jobId = this._jobId(taskId);
+      try {
+        const acknowledged = await this._unscheduleHook(jobId);
+        if (!acknowledged) {
+          console.warn(
+            `[schedule] cancel(${taskId}): daemon did not acknowledge unschedule for ${jobId}. ` +
+              `The disk file was removed; the ghost cron registration will be pruned at next fire.`
+          );
+        }
+      } catch (err) {
+        console.warn(
+          `[schedule] cancel(${taskId}): unschedule hook threw for ${jobId} — ` +
+            `relying on fire-time phantom-prune as fallback.`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+
+    return removed;
   }
 
   /**
@@ -362,8 +443,11 @@ export class ScheduleProvider {
 
   /** @internal */
   private async _save(task: ScheduledTask): Promise<void> {
-    const dir = photonScheduleDir(this._photonId);
+    const dir = photonScheduleDir(this._photonId, undefined, this._baseDir);
     await ensureDir(dir);
-    await fs.writeFile(taskPath(this._photonId, task.id), JSON.stringify(task, null, 2));
+    await fs.writeFile(
+      taskPath(this._photonId, task.id, this._baseDir),
+      JSON.stringify(task, null, 2)
+    );
   }
 }

package/src/schema-extractor.ts

@@ -13,6 +13,10 @@ import * as ts from 'typescript';
 import { ExtractedSchema, ConstructorParam, TemplateInfo, StaticInfo, OutputFormat, YieldInfo, MCPDependency, PhotonDependency, CLIDependency, ResolvedInjection, PhotonAssets, UIAsset, PromptAsset, ResourceAsset, ConfigSchema, ConfigParam, SettingsSchema, SettingsProperty, NotificationSubscription } from './types.js';
 import { parseDuration, parseRate } from './utils/duration.js';
 import { builtinRegistry, type MiddlewareDeclaration } from './middleware.js';
+import { sanitizeDescription } from './description-sanitizer.js';
+
+// Warn once per unique (method, rule) pair so poisoned photons don't spam.
+const sanitizeWarnings = new Set<string>();
 
 // Track which `handle*` method names have already emitted a deprecation
 // warning this process so large photons don't spam the console.
@@ -396,6 +400,33 @@ export class SchemaExtractor {
 
         const properties: SettingsProperty[] = [];
 
+        // Inline-JSDoc helper: pull the description from a /** ... */ comment
+        // that immediately precedes a property assignment inside the object
+        // literal. Class-level @property tags still win when both are
+        // present (so existing photons aren't disrupted).
+        const sourceText = sourceFile.text;
+        const inlineDescriptionFor = (prop: ts.Node): string | undefined => {
+          const ranges = ts.getLeadingCommentRanges(sourceText, prop.pos);
+          if (!ranges || ranges.length === 0) return undefined;
+          // Use the last comment block before the property (closest to it).
+          const block = ranges[ranges.length - 1];
+          if (
+            sourceText[block.pos] !== '/' ||
+            sourceText[block.pos + 1] !== '*' ||
+            sourceText[block.pos + 2] !== '*'
+          ) {
+            return undefined;
+          }
+          const raw = sourceText.slice(block.pos + 3, block.end - 2);
+          // Strip leading "*" markers, trim, collapse whitespace.
+          return raw
+            .split('\n')
+            .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+            .filter(Boolean)
+            .join(' ')
+            .trim();
+        };
+
         for (const prop of member.initializer.properties) {
           if (!ts.isPropertyAssignment(prop)) continue;
           const propName = prop.name.getText(sourceFile);
@@ -452,7 +483,7 @@ export class SchemaExtractor {
           properties.push({
             name: propName,
             type,
-            description: propertyDocs.get(propName),
+            description: propertyDocs.get(propName) ?? inlineDescriptionFor(prop),
             default: defaultValue,
             required,
           });
@@ -996,10 +1027,36 @@ export class SchemaExtractor {
         true
       );
 
+      // Per-parameter JSDoc: prefer an inline /** ... */ block immediately
+      // before the parameter (the natural way authors write it), fall back
+      // to a constructor-level @param tag.
+      const sourceText = sourceFile.text;
+      const inlineDescriptionFor = (param: ts.Node): string | undefined => {
+        const ranges = ts.getLeadingCommentRanges(sourceText, param.pos);
+        if (!ranges || ranges.length === 0) return undefined;
+        const block = ranges[ranges.length - 1];
+        if (
+          sourceText[block.pos] !== '/' ||
+          sourceText[block.pos + 1] !== '*' ||
+          sourceText[block.pos + 2] !== '*'
+        ) {
+          return undefined;
+        }
+        const raw = sourceText.slice(block.pos + 3, block.end - 2);
+        return raw
+          .split('\n')
+          .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+          .filter(Boolean)
+          .join(' ')
+          .trim();
+      };
+
       const visit = (node: ts.Node) => {
         if (ts.isClassDeclaration(node)) {
           node.members.forEach((member) => {
             if (ts.isConstructorDeclaration(member)) {
+              const ctorJsdoc = this.getJSDocComment(member as any, sourceFile);
+              const ctorParamDocs = this.extractParamDocs(ctorJsdoc);
               member.parameters.forEach((param) => {
                 if (param.name && ts.isIdentifier(param.name)) {
                   const name = param.name.getText(sourceFile);
@@ -1019,6 +1076,7 @@ export class SchemaExtractor {
                     hasDefault,
                     defaultValue,
                     isPrimitive: this.isPrimitiveType(type),
+                    description: inlineDescriptionFor(param) ?? ctorParamDocs.get(name),
                   });
                 }
               });
@@ -1264,6 +1322,29 @@ export class SchemaExtractor {
       declarations.push({ name: 'locked', config: { name: lockName }, phase: def?.phase ?? 60 });
     }
 
+    // @mask <field1,field2,...> — redact named fields from the response.
+    // Accepts comma- or whitespace-separated field names.
+    const maskMatch = jsdocContent.match(/@mask\s+([^\n@]+)/i);
+    if (maskMatch) {
+      const def = builtinRegistry.get('mask');
+      const rawValue = maskMatch[1].trim();
+      const config = def?.parseShorthand
+        ? def.parseShorthand(rawValue)
+        : { fields: rawValue.split(/[,\s]+/).filter(Boolean), placeholder: '[REDACTED]' };
+      declarations.push({ name: 'mask', config, phase: def?.phase ?? 85 });
+    }
+
+    // @maxResponseBytes <N> — cap serialized response size.
+    const maxBytesMatch = jsdocContent.match(/@maxResponseBytes\s+(\d+)/i);
+    if (maxBytesMatch) {
+      const def = builtinRegistry.get('maxResponseBytes');
+      const rawValue = maxBytesMatch[1];
+      const config = def?.parseShorthand
+        ? def.parseShorthand(rawValue)
+        : { limit: parseInt(rawValue, 10) || 0 };
+      declarations.push({ name: 'maxResponseBytes', config, phase: def?.phase ?? 88 });
+    }
+
     // 2. Extract @use declarations
     const useDecls = this.extractUseDeclarations(jsdocContent);
     for (const { name, rawConfig } of useDecls) {
@@ -1291,7 +1372,7 @@ export class SchemaExtractor {
   private extractDescription(jsdocContent: string): string {
     // Split by @tags that appear at start of a JSDoc line (after optional * prefix)
     // This avoids matching @tag references inline in description text
-    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility|auth)\b/)[0];
+    const beforeTags = jsdocContent.split(/(?:^|\n)\s*\*?\s*@(?:param|example|returns?|throws?|see|since|deprecated|version|author|license|ui|icon|format|stateful|autorun|async|webhook|cron|scheduled|locked|fallback|logged|circuitBreaker|cached|timeout|retryable|throttled|debounced|queued|validate|use|Template|Static|mcp|photon|cli|tags|dependencies|csp|visibility|auth|mask|maxResponseBytes)\b/)[0];
 
     // Remove leading * from each line and trim
     const lines = beforeTags
@@ -1328,8 +1409,26 @@ export class SchemaExtractor {
 
     const description = parts.join('');
 
-    // Clean up multiple spaces
-    return description.replace(/\s+/g, ' ').trim() || 'No description';
+    // Clean up multiple spaces, then defend against tool-description poisoning.
+    const collapsed = description.replace(/\s+/g, ' ').trim() || 'No description';
+    const { cleaned, warnings, truncated } = sanitizeDescription(collapsed);
+    if (warnings.length > 0 || truncated) {
+      for (const w of warnings) {
+        const key = `${w.rule}|${w.sample}`;
+        if (sanitizeWarnings.has(key)) continue;
+        sanitizeWarnings.add(key);
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[photon] description sanitizer: redacted ${w.rule} (sample: "${w.sample}")`
+        );
+      }
+      if (truncated && !sanitizeWarnings.has('truncated')) {
+        sanitizeWarnings.add('truncated');
+        // eslint-disable-next-line no-console
+        console.warn('[photon] description sanitizer: truncated oversized description');
+      }
+    }
+    return cleaned;
   }
 
   /**
@@ -2412,6 +2511,11 @@ export class SchemaExtractor {
       return format as OutputFormat;
     }
 
+    // Match declarative UI formats (A2UI v0.9 rides on AG-UI)
+    if (format === 'a2ui') {
+      return 'a2ui' as OutputFormat;
+    }
+
     return undefined;
   }
 
@@ -3025,25 +3129,54 @@ export class SchemaExtractor {
  */
 export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'instanceMeta' | 'allInstances' | 'caller';
 
+/**
+ * Match a `this`-like base in source code. Covers:
+ *   this            — literal
+ *   (this as any)   — TS `as` cast (the most common workaround when
+ *                     TypeScript can't see a runtime-injected method)
+ *   (this as SomeClass), (this as unknown as T)
+ *   (<any>this), (<T>this) — older angle-bracket cast syntax
+ *
+ * Not covered: aliasing (`const self = this`), destructuring
+ * (`const { call } = this`), or bracket access (`this['call']`).
+ * Those require dataflow analysis which a regex can't do; the loader
+ * compensates by always-injecting the cheap convenience methods whose
+ * gating would otherwise silently fail for those patterns.
+ */
+// The `(this as <T>)` alternative allows one level of nested parens inside
+// the type annotation so function-type syntax like `(k: string) => void`
+// doesn't truncate the match. Without the `(?:[^()]|\([^()]*\))+` fallback,
+// `(this as unknown as { memory: { set: (k: string) => Promise<void> } })`
+// would terminate at the first inner `)` and the trailing `.memory` access
+// would never be seen — silently disabling this.memory injection for any
+// plain class that uses a complex TS type cast to reach memory.
+const THIS_BASE =
+  String.raw`(?:\bthis\b|\(\s*<[^>]+>\s*this\s*\)|\(\s*this\s+as\s+(?:[^()]|\([^()]*\))+\))`;
+
+function memberAccess(name: string, trailing: '\\(' | '\\b'): RegExp {
+  return new RegExp(`${THIS_BASE}\\s*\\.\\s*${name}\\s*${trailing}`);
+}
+
 /**
  * Detect capabilities used by a Photon from its source code.
  *
  * Scans for `this.emit(`, `this.memory`, `this.call(`, etc. patterns
- * and returns the set of capabilities that the runtime should inject.
+ * (including typed-access workarounds like `(this as any).call(`) and
+ * returns the set of capabilities that the runtime should inject.
  *
  * This enables plain classes (no extends Photon) to use all framework
  * features — the loader detects usage and injects automatically.
  */
 export function detectCapabilities(source: string): Set<PhotonCapability> {
   const caps = new Set<PhotonCapability>();
-  if (/this\.emit\s*\(/.test(source)) caps.add('emit');
-  if (/this\.render\s*\(/.test(source)) caps.add('emit'); // render() needs emit injection
-  if (/this\.memory\b/.test(source)) caps.add('memory');
-  if (/this\.call\s*\(/.test(source)) caps.add('call');
-  if (/this\.mcp\s*\(/.test(source)) caps.add('mcp');
-  if (/this\.withLock\s*\(/.test(source)) caps.add('lock');
-  if (/this\.instanceMeta\b/.test(source)) caps.add('instanceMeta');
-  if (/this\.allInstances\s*\(/.test(source)) caps.add('allInstances');
-  if (/this\.caller\b/.test(source)) caps.add('caller');
+  if (memberAccess('emit', '\\(').test(source)) caps.add('emit');
+  if (memberAccess('render', '\\(').test(source)) caps.add('emit'); // render() needs emit injection
+  if (memberAccess('memory', '\\b').test(source)) caps.add('memory');
+  if (memberAccess('call', '\\(').test(source)) caps.add('call');
+  if (memberAccess('mcp', '\\(').test(source)) caps.add('mcp');
+  if (memberAccess('withLock', '\\(').test(source)) caps.add('lock');
+  if (memberAccess('instanceMeta', '\\b').test(source)) caps.add('instanceMeta');
+  if (memberAccess('allInstances', '\\(').test(source)) caps.add('allInstances');
+  if (memberAccess('caller', '\\b').test(source)) caps.add('caller');
   return caps;
 }

package/src/types.ts

@@ -9,6 +9,7 @@
  * - Visualization: chart, chart:<type>, metric, gauge, timeline, dashboard, cart
  * - Content: json, markdown, yaml, xml, html, mermaid, code, code:<lang>, slides
  * - Container: panels, tabs, accordion, stack, columns
+ * - Declarative: a2ui (A2UI v0.9 JSONL — emits createSurface/updateComponents/updateDataModel)
  */
 export type OutputFormat =
   | 'primitive' | 'table' | 'tree' | 'list' | 'none'
@@ -16,6 +17,7 @@ export type OutputFormat =
   | 'card' | 'grid' | 'chips' | 'kv' | 'qr'
   | 'chart' | `chart:${string}` | 'metric' | 'gauge' | 'timeline' | 'dashboard' | 'cart'
   | 'panels' | 'tabs' | 'accordion' | 'stack' | 'columns'
+  | 'a2ui'
   | `code` | `code:${string}`;
 
 export interface PhotonTool {
@@ -299,6 +301,13 @@ export interface ConstructorParam {
   defaultValue?: any;
   /** True if type is string, number, or boolean (inject from env var) */
   isPrimitive: boolean;
+  /**
+   * Per-parameter JSDoc description, taken from an inline `/** ... *\/`
+   * comment immediately before the parameter, or from a constructor-level
+   * `@param <name>` tag when the inline form is absent. Used by the Beam
+   * Setup form for field help text.
+   */
+  description?: string;
 }
 
 /**