@portel/photon-core 2.24.0 → 2.25.0

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

@@ -265,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/schedule.ts

@@ -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
  *
@@ -172,6 +186,7 @@ async function ensureDir(dir: string): Promise<void> {
 export class ScheduleProvider {
   private _photonId: string;
   private _baseDir?: string;
+  private _unscheduleHook?: UnscheduleHook;
 
   /**
    * @param photonId Photon identifier used as the bucket under .data/
@@ -180,10 +195,20 @@ export class ScheduleProvider {
    *   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) {
+  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}`;
   }
 
   /**
@@ -332,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, this._baseDir));
-      return true;
+      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;
   }
 
   /**

package/src/schema-extractor.ts

@@ -3143,8 +3143,15 @@ export type PhotonCapability = 'emit' | 'memory' | 'call' | 'mcp' | 'lock' | 'in
  * 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+[^)]+\))`;
+  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}`);