@portel/photon-core 2.23.0 → 2.25.0

package/src/base.ts

@@ -48,6 +48,13 @@ import { ScheduleProvider } from './schedule.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import { getPhotonDataDir } from './data-paths.js';
+import type {
+  AskYield,
+  InputProvider,
+  SampleParams,
+  SamplingMessage,
+  SamplingProvider,
+} from './generator.js';
 
 /**
  * Simple base class for creating Photons
@@ -71,6 +78,16 @@ export class Photon {
    */
   _photonNamespace?: string;
 
+  /**
+   * PHOTON_DIR this instance was loaded from - set by runtime loader.
+   * Pinned so .data/ resolves to the same root regardless of which
+   * process (CLI, daemon, worker) reads the photon back later. Without
+   * this pin, MemoryProvider falls back to getDefaultContext().baseDir
+   * and writes/reads can drift between cwd-derived locations.
+   * @internal
+   */
+  _baseDir?: string;
+
   /**
    * Absolute path to the .photon.ts/.photon.js source file - set by runtime loader
    * Used for storage() and assets() path resolution
@@ -78,6 +95,25 @@ export class Photon {
    */
   _photonFilePath?: string;
 
+  /**
+   * Stat snapshot captured when the current photon instance was loaded.
+   * Used by executeTool() to detect out-of-band edits so CLI-direct and
+   * lite-loader callers see new code immediately after a file save.
+   * See `_photonReloader` for the callback invoked on change.
+   * @internal
+   */
+  _photonSourceStat?: { mtimeMs: number; size: number; ino: number };
+
+  /**
+   * Callback the loader registers so executeTool() can trigger a live
+   * reload when `_photonFilePath` has changed since load. The loader is
+   * expected to re-evaluate the file, replace the cached module, and
+   * update `_photonSourceStat` on success. Missing callback means the
+   * gate is a no-op (the original behavior).
+   * @internal
+   */
+  _photonReloader?: () => Promise<void>;
+
   /**
    * Dynamic photon resolver - injected by runtime loader
    * Used by this.photon.use() for runtime photon access
@@ -125,6 +161,127 @@ export class Photon {
     return store?.caller ?? { id: 'anonymous', anonymous: true };
   }
 
+  /**
+   * Ask the caller a yes/no question and await the answer.
+   *
+   * Imperative sugar over the existing `{ ask: 'confirm' }` yield.
+   * Works in any method (generator or plain async), routed through the
+   * runtime's elicitation pipeline — returns `true`/`false` based on the
+   * user's response in whichever surface the client offers (Beam
+   * dialog, Claude confirm prompt, CLI readline, etc.).
+   *
+   * @throws If no client with elicitation capability is connected.
+   *
+   * @example
+   * ```typescript
+   * if (await this.confirm('Delete all records?')) {
+   *   await purge();
+   * }
+   * ```
+   */
+  async confirm(question: string): Promise<boolean> {
+    const provider = this._resolveInputProvider('this.confirm()');
+    const result = await provider({ ask: 'confirm', question, message: question } as AskYield);
+    return Boolean(result);
+  }
+
+  /**
+   * Pose an arbitrary elicitation request and await the answer.
+   *
+   * Accepts any `AskYield` (text, password, select, number, form, etc.)
+   * and returns the client's response. Prefer `this.confirm()` for
+   * yes/no; use `yield { ask: ... }` inside async-generator workflows.
+   * `this.elicit()` is the imperative form for plain async methods
+   * that need a single input without the generator plumbing.
+   *
+   * The name matches MCP spec terminology (`elicitation/create`) to
+   * avoid ambiguity with the legacy `this.ask(type, message, opts)`
+   * factory, which just constructs an `AskYield` object for use with
+   * `yield`.
+   *
+   * @throws If no client with elicitation capability is connected.
+   */
+  async elicit<T = unknown>(params: AskYield): Promise<T> {
+    const provider = this._resolveInputProvider('this.elicit()');
+    return (await provider(params)) as T;
+  }
+
+  /**
+   * Ask the client's LLM to generate text (MCP `sampling/createMessage`).
+   *
+   * The caller's agent model generates the completion — no API key
+   * needed in the photon, and inference cost is borne by whoever is
+   * driving the tool. The client must declare the `sampling`
+   * capability during initialize; otherwise this throws.
+   *
+   * Returns just the generated text for the common case. For
+   * multi-block / image / structured responses, access the underlying
+   * provider via the runtime.
+   *
+   * @example
+   * ```typescript
+   * async summarize(params: { text: string }) {
+   *   return await this.sample({
+   *     prompt: `Summarize this in one sentence:\n\n${params.text}`,
+   *     maxTokens: 128,
+   *   });
+   * }
+   * ```
+   */
+  async sample(params: SampleParams): Promise<string> {
+    const store = executionContext.getStore() as { samplingProvider?: SamplingProvider } | undefined;
+    const provider = store?.samplingProvider;
+    if (!provider) {
+      throw new Error(
+        'this.sample() requires the connected MCP client to declare the ' +
+          '`sampling` capability. None is available in this invocation — ' +
+          "either the client didn't declare sampling during initialize, or " +
+          'this method is being called outside an MCP request context (e.g. ' +
+          'from a scheduled task without a live session).'
+      );
+    }
+    if (!params.prompt && !params.messages?.length) {
+      throw new Error('this.sample() requires either `prompt` or `messages`.');
+    }
+    const messages: SamplingMessage[] =
+      params.messages ??
+      [{ role: 'user', content: { type: 'text', text: params.prompt! } }];
+    const result = await provider({
+      messages,
+      systemPrompt: params.systemPrompt,
+      maxTokens: params.maxTokens ?? 1024,
+      temperature: params.temperature,
+      modelPreferences: params.modelPreferences,
+      stopSequences: params.stopSequences,
+      includeContext: params.includeContext,
+    });
+    const first = Array.isArray(result.content) ? result.content[0] : result.content;
+    if (first && first.type === 'text') return first.text;
+    // Non-text responses (image-only) — return empty string rather than
+    // a JSON-stringified blob so callers can reliably concatenate the
+    // result. Users needing image output should hit the provider directly.
+    return '';
+  }
+
+  /**
+   * Internal: resolve the runtime-supplied input provider, throwing a
+   * clear error if none is attached to the current execution context.
+   * @internal
+   */
+  private _resolveInputProvider(forMethod: string): InputProvider {
+    const store = executionContext.getStore() as { inputProvider?: InputProvider } | undefined;
+    const provider = store?.inputProvider;
+    if (!provider) {
+      throw new Error(
+        `${forMethod} requires a connected MCP client that supports elicitation. ` +
+          'The runtime attaches an input provider for every tool invocation; ' +
+          "this call is running outside that context (e.g. a background task " +
+          'without a session, or a client that declined elicitation).'
+      );
+    }
+    return provider;
+  }
+
   /**
    * Scoped key-value storage for photon data
    *
@@ -153,7 +310,12 @@ export class Photon {
         .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;
   }
@@ -197,11 +359,27 @@ export class Photon {
         .replace(/([A-Z])/g, '-$1')
         .toLowerCase()
         .replace(/^-/, '');
-      this._schedule = new ScheduleProvider(name);
+      this._schedule = new ScheduleProvider(
+        name,
+        this._baseDir,
+        this._scheduleUnscheduleHook
+      );
     }
     return this._schedule;
   }
 
+  /**
+   * Runtime-injected hook that evicts an in-memory cron registration.
+   * The photon runtime (photon-repo loader) attaches a callback that
+   * IPCs the daemon's `unschedule` request; photon-core doesn't know
+   * about the daemon, so the hook is passed through to ScheduleProvider
+   * which calls it after unlinking the disk file. Without the hook,
+   * `this.schedule.cancel()` leaves a ghost registration that keeps
+   * firing until the next daemon restart.
+   * @internal
+   */
+  _scheduleUnscheduleHook?: import('./schedule.js').UnscheduleHook;
+
   /**
    * Get an absolute path to a storage directory for this photon's data.
    *
@@ -624,6 +802,15 @@ export class Photon {
    * Execute a tool method
    */
   async executeTool(toolName: string, parameters: any, options?: { outputHandler?: (data: any) => void }): Promise<any> {
+    // Stat-gate: close the edit→dispatch race on non-daemon paths. The
+    // daemon has its own equivalent at src/daemon/server.ts; this runs
+    // for CLI-direct dispatch and for callers using the lite loader's
+    // programmatic photon() API. If the source file has changed since
+    // the instance was loaded, hand off to the loader-registered
+    // reloader before dispatching so the first call after a save sees
+    // the new code.
+    await this._statGateIfStale();
+
     const method = (this as any)[toolName];
 
     if (!method || typeof method !== 'function') {
@@ -642,6 +829,41 @@ export class Photon {
     });
   }
 
+  /**
+   * If a reloader is registered and the source file has changed since it
+   * was last loaded, invoke the reloader. Silent on missing file or
+   * reloader failure — dispatch continues on the stale instance rather
+   * than throwing for an observability concern.
+   */
+  private async _statGateIfStale(): Promise<void> {
+    const filePath = this._photonFilePath;
+    const reloader = this._photonReloader;
+    const cached = this._photonSourceStat;
+    if (!filePath || !reloader || !cached) return;
+    let current: { mtimeMs: number; size: number; ino: number } | null = null;
+    try {
+      const s = fs.statSync(filePath);
+      current = { mtimeMs: s.mtimeMs, size: s.size, ino: s.ino };
+    } catch {
+      // Source gone or unreadable — nothing to gate against. Dispatch
+      // will surface the missing-photon error through its own path.
+      return;
+    }
+    if (
+      current.mtimeMs === cached.mtimeMs &&
+      current.size === cached.size &&
+      current.ino === cached.ino
+    ) {
+      return;
+    }
+    try {
+      await reloader();
+    } catch {
+      // Reloader errors are non-fatal — keep running on the stale
+      // instance rather than making dispatch itself fail.
+    }
+  }
+
   /**
    * Invoke the onError observability hook with a bounded timeout. Never
    * suppresses the original error and never throws itself — a throw or

package/src/description-sanitizer.ts

@@ -0,0 +1,102 @@
+/**
+ * Tool-description sanitizer.
+ *
+ * Defends against MCP tool-description poisoning (OWASP MCP #3) by stripping
+ * invisible codepoints and redacting embedded prompt-injection markers from
+ * JSDoc descriptions before they reach the model.
+ *
+ * Called by the schema extractor at parse time; any photon loaded via the
+ * runtime benefits automatically. Intentionally conservative — it only
+ * touches obvious attack patterns. Legitimate documentation does not use
+ * zero-width spaces or contain `[[SYSTEM: ...]]` directives.
+ */
+
+/**
+ * Unicode ranges that are invisible to humans but preserved by LLM tokenizers.
+ * Stripped unconditionally — no legitimate doc string needs them.
+ *
+ *   U+200B ZERO WIDTH SPACE
+ *   U+200C ZERO WIDTH NON-JOINER
+ *   U+200D ZERO WIDTH JOINER
+ *   U+200E LEFT-TO-RIGHT MARK
+ *   U+200F RIGHT-TO-LEFT MARK
+ *   U+202A-E LRE/RLE/PDF/LRO/RLO (bidi override)
+ *   U+2060 WORD JOINER
+ *   U+2066-9 LRI/RLI/FSI/PDI (bidi isolate)
+ *   U+FEFF ZERO WIDTH NO-BREAK SPACE (BOM)
+ */
+const INVISIBLE_CHARS = /[\u200B-\u200F\u202A-\u202E\u2060\u2066-\u2069\uFEFF]/g;
+
+/**
+ * Instruction-bracket patterns commonly used in tool-poisoning payloads.
+ * Each match is replaced with `[REDACTED]` and counted as a warning.
+ */
+const INSTRUCTION_PATTERNS: Array<{ name: string; pattern: RegExp }> = [
+  // Bracketed system directives: [[SYSTEM: ...]], [INST] ... [/INST], <|im_start|>...<|im_end|>
+  { name: 'bracketed-system', pattern: /\[{1,2}\s*SYSTEM\s*:[^\]]*\]{1,2}/gi },
+  { name: 'llama-inst', pattern: /\[\/?INST\]/gi },
+  { name: 'chatml-tag', pattern: /<\|im_(?:start|end|sep)\|>/gi },
+  // Verbatim instruction phrases that only appear in jailbreaks, never in docs.
+  { name: 'ignore-previous', pattern: /\bignore\s+(?:all\s+|the\s+)?(?:previous|prior|above)\s+instructions?\b/gi },
+  { name: 'disregard-previous', pattern: /\bdisregard\s+(?:all\s+|the\s+)?(?:previous|prior|above)\b/gi },
+  { name: 'system-prompt-literal', pattern: /\bSYSTEM[_\s-]?PROMPT\b/g },
+];
+
+/** Max length of a cleaned description. Anything longer is an attack surface. */
+export const MAX_DESCRIPTION_LENGTH = 2000;
+
+export interface SanitizerWarning {
+  /** Label of the rule that fired. */
+  rule: string;
+  /** Short slice of the matched text for forensics (capped at 80 chars). */
+  sample: string;
+}
+
+export interface SanitizeResult {
+  cleaned: string;
+  warnings: SanitizerWarning[];
+  /** Whether the string was truncated because it exceeded MAX_DESCRIPTION_LENGTH. */
+  truncated: boolean;
+}
+
+/**
+ * Strip invisible codepoints, redact instruction markers, and cap length.
+ * Idempotent: sanitize(sanitize(x).cleaned).cleaned === sanitize(x).cleaned
+ * so callers can apply it defensively without risking duplicate `[REDACTED]`
+ * tokens.
+ */
+export function sanitizeDescription(input: string): SanitizeResult {
+  const warnings: SanitizerWarning[] = [];
+
+  // Step 1: strip invisibles. Counts as one warning if any were present.
+  const withoutInvisibles = input.replace(INVISIBLE_CHARS, (match) => {
+    warnings.push({ rule: 'invisible-char', sample: codepointSample(match) });
+    return '';
+  });
+
+  // Step 2: redact each known instruction pattern.
+  let redacted = withoutInvisibles;
+  for (const { name, pattern } of INSTRUCTION_PATTERNS) {
+    redacted = redacted.replace(pattern, (match) => {
+      warnings.push({ rule: name, sample: match.slice(0, 80) });
+      return '[REDACTED]';
+    });
+  }
+
+  // Step 3: cap length. An attacker-friendly 50KB description is itself a
+  // prompt-injection vector via context-window flooding (OWASP MCP #10).
+  let truncated = false;
+  if (redacted.length > MAX_DESCRIPTION_LENGTH) {
+    redacted = redacted.slice(0, MAX_DESCRIPTION_LENGTH) + '…';
+    truncated = true;
+  }
+
+  return { cleaned: redacted, warnings, truncated };
+}
+
+function codepointSample(s: string): string {
+  return Array.from(s)
+    .map((c) => 'U+' + c.codePointAt(0)!.toString(16).toUpperCase().padStart(4, '0'))
+    .join(',')
+    .slice(0, 80);
+}

package/src/generator.ts

@@ -921,6 +921,99 @@ export type InputProvider = (ask: AskYield) => Promise<any>;
  */
 export type OutputHandler = (emit: EmitYield) => void | Promise<void>;
 
+// ══════════════════════════════════════════════════════════════════════════════
+// SAMPLING - Photon-to-client LLM requests (MCP sampling/createMessage)
+// ══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * A message in an MCP sampling conversation.
+ *
+ * Mirrors `SamplingMessage` in the MCP spec: `role` plus either text or
+ * image content. Most photon callers only need `{ role: 'user', content:
+ * { type: 'text', text: '...' } }` — use the `prompt` shortcut on
+ * `SampleParams` to build that automatically.
+ */
+export interface SamplingMessage {
+  role: 'user' | 'assistant';
+  content:
+    | { type: 'text'; text: string }
+    | { type: 'image'; data: string; mimeType: string };
+}
+
+/**
+ * Preferences passed to the client's sampling LLM (MCP modelPreferences).
+ * All fields are advisory — the client picks the final model.
+ */
+export interface ModelPreferences {
+  /** Hints at desired models, in priority order (e.g. `[{name:'claude-3-5-sonnet'}]`) */
+  hints?: Array<{ name: string }>;
+  /** 0-1 weight favoring cheaper models */
+  costPriority?: number;
+  /** 0-1 weight favoring faster responses */
+  speedPriority?: number;
+  /** 0-1 weight favoring stronger models */
+  intelligencePriority?: number;
+}
+
+/**
+ * Parameters for `this.sample()`.
+ *
+ * Pick ONE of `prompt` or `messages`. `prompt` is the ergonomic path:
+ * it becomes a single user-role text message. `messages` gives full
+ * control over multi-turn conversations or image content.
+ */
+export interface SampleParams {
+  /** Convenience: wraps the string as a single user message */
+  prompt?: string;
+  /** Full message array (alternative to `prompt`) */
+  messages?: SamplingMessage[];
+  /** Optional system prompt */
+  systemPrompt?: string;
+  /**
+   * Max tokens the client should generate. MCP spec requires this field;
+   * defaults to 1024 when omitted. Keep modest — sampling is not free.
+   */
+  maxTokens?: number;
+  temperature?: number;
+  modelPreferences?: ModelPreferences;
+  stopSequences?: string[];
+  /** Whether the client should include this or other servers' context */
+  includeContext?: 'none' | 'thisServer' | 'allServers';
+}
+
+/**
+ * Result of a sampling request (a `CreateMessageResult` from MCP).
+ * The `content` union accommodates both single-block responses (the
+ * common case) and multi-block responses from tool-capable sampling.
+ */
+export interface SamplingResult {
+  role: 'assistant';
+  content:
+    | { type: 'text'; text: string }
+    | { type: 'image'; data: string; mimeType: string }
+    | Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }>;
+  model: string;
+  stopReason?: string;
+}
+
+/**
+ * Runtime hook that forwards a sampling request to the MCP client.
+ *
+ * Runtimes implement this by calling the client's
+ * `sampling/createMessage`. When the client doesn't declare the
+ * `sampling` capability, the runtime should throw or omit the provider
+ * entirely — `this.sample()` surfaces a clear error in that case.
+ */
+export type SamplingProvider = (params: {
+  messages: SamplingMessage[];
+  systemPrompt?: string;
+  maxTokens: number;
+  temperature?: number;
+  modelPreferences?: ModelPreferences;
+  stopSequences?: string[];
+  includeContext?: 'none' | 'thisServer' | 'allServers';
+}) => Promise<SamplingResult>;
+
 /**
  * Configuration for generator execution
  */

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 {
@@ -259,6 +265,12 @@ export {
   type OutputHandler,
   type GeneratorExecutorConfig,
   type ExtractedAsk,
+  // Sampling (MCP createMessage) — powers this.sample()
+  type SampleParams,
+  type SamplingMessage,
+  type SamplingResult,
+  type SamplingProvider,
+  type ModelPreferences,
 } from './generator.js';
 
 // Stateful Workflow Execution

package/src/memory.ts

@@ -294,6 +294,33 @@ function findAndMigrateStrandedMemory(
   }
 }
 
+/**
+ * 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,
@@ -301,6 +328,7 @@ function resolveDir(
   sessionId?: string,
   baseDir?: string
 ): string {
+  warnIfBaseDirMissing(photonId, baseDir);
   switch (scope) {
     case 'photon': {
       const newDir = getPhotonMemoryDir(namespace, photonId, baseDir);

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