@portel/photon-core 2.22.0 → 2.24.0

package/src/schema-extractor.ts

@@ -13,6 +13,25 @@ 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.
+const handlePrefixWarned = new Set<string>();
+
+function warnHandlePrefixOnce(methodName: string): void {
+  if (handlePrefixWarned.has(methodName)) return;
+  handlePrefixWarned.add(methodName);
+  // eslint-disable-next-line no-console
+  console.error(
+    `[photon] deprecation: method "${methodName}" is being auto-registered as a ` +
+      `webhook via the legacy handle* prefix. Add an explicit "@webhook" JSDoc ` +
+      `tag; the prefix convention will be removed in the next minor release.`,
+  );
+}
 
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
@@ -381,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);
@@ -437,7 +483,7 @@ export class SchemaExtractor {
           properties.push({
             name: propName,
             type,
-            description: propertyDocs.get(propName),
+            description: propertyDocs.get(propName) ?? inlineDescriptionFor(prop),
             default: defaultValue,
             required,
           });
@@ -981,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);
@@ -1004,6 +1076,7 @@ export class SchemaExtractor {
                     hasDefault,
                     defaultValue,
                     isPrimitive: this.isPrimitiveType(type),
+                    description: inlineDescriptionFor(param) ?? ctorParamDocs.get(name),
                   });
                 }
               });
@@ -1249,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) {
@@ -1276,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
@@ -1313,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;
   }
 
   /**
@@ -2048,10 +2162,15 @@ export class SchemaExtractor {
   // ═══════════════════════════════════════════════════════════════════════════════
 
   /**
-   * Extract webhook configuration from @webhook tag or handle* prefix
+   * Extract webhook configuration from @webhook tag or handle* prefix.
    * - @webhook → use method name as path
    * - @webhook stripe → custom path "stripe"
-   * - handle* prefix → auto-detected as webhook
+   * - handle* prefix → auto-detected as webhook (DEPRECATED)
+   *
+   * The handle* prefix is a legacy convention being removed. It still
+   * works for one release but emits a one-time stderr warning per
+   * method so users can migrate to the explicit @webhook tag before
+   * the convention is dropped.
    */
   private extractWebhook(jsdocContent: string, methodName: string): boolean | string | undefined {
     // Check for @webhook tag with optional path
@@ -2063,8 +2182,9 @@ export class SchemaExtractor {
       return path || true;
     }
 
-    // Check for handle* prefix (convention)
+    // Check for handle* prefix (legacy convention — deprecated).
     if (methodName.startsWith('handle')) {
+      warnHandlePrefixOnce(methodName);
       return true;
     }
 
@@ -2391,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;
   }
 
@@ -3004,25 +3129,47 @@ 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.
+ */
+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/stateful.ts

@@ -87,10 +87,21 @@ import {
 // ══════════════════════════════════════════════════════════════════════════════
 
 /**
- * Default runs directory (legacy: ~/.photon/runs)
- * @deprecated Use getPhotonRunsDir(namespace, photonName) from data-paths.ts
+ * Resolve the default runs directory at call time so a long-lived daemon
+ * that serves multiple PHOTON_DIRs picks up each base's runs. Previously
+ * a module-level const frozen at import time.
+ * @deprecated Use getPhotonRunsDir(namespace, photonName, baseDir) for per-photon runs.
  */
-export const RUNS_DIR = getLegacyRunsDir();
+function defaultRunsDir(): string {
+  return getLegacyRunsDir();
+}
+
+/**
+ * Back-compat export. Resolved at import time — kept for consumers that
+ * read `RUNS_DIR` as a constant. New code should call getPhotonRunsDir().
+ * @deprecated Use getPhotonRunsDir(namespace, photonName, baseDir).
+ */
+export const RUNS_DIR = defaultRunsDir();
 
 // ══════════════════════════════════════════════════════════════════════════════
 // CHECKPOINT YIELD TYPE
@@ -136,7 +147,9 @@ export class StateLog {
   private logPath: string;
 
   constructor(runId: string, runsDir?: string) {
-    this.logPath = path.join(runsDir || RUNS_DIR, `${runId}.jsonl`);
+    // Resolve runs dir at call time so the current PHOTON_DIR is honored
+    // even when a long-lived process has served earlier bases.
+    this.logPath = path.join(runsDir || defaultRunsDir(), `${runId}.jsonl`);
   }
 
   /**
@@ -573,7 +586,7 @@ export async function executeStatefulGenerator<T>(
  * List all workflow runs
  */
 export async function listRuns(runsDir?: string): Promise<WorkflowRun[]> {
-  const dir = runsDir || RUNS_DIR;
+  const dir = runsDir || defaultRunsDir();
   const runs: WorkflowRun[] = [];
 
   try {
@@ -639,7 +652,7 @@ export async function getRunInfo(runId: string, runsDir?: string): Promise<Workf
  * Delete a workflow run
  */
 export async function deleteRun(runId: string, runsDir?: string): Promise<void> {
-  const logPath = path.join(runsDir || RUNS_DIR, `${runId}.jsonl`);
+  const logPath = path.join(runsDir || defaultRunsDir(), `${runId}.jsonl`);
   await fs.unlink(logPath);
 }
 

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;
 }
 
 /**