@portel/photon-core 2.24.0 → 2.26.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
@@ -154,6 +161,184 @@ 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 '';
+  }
+
+  /**
+   * Workspace roots declared by the connected MCP client (per spec
+   * `roots/list`). Each entry is a `{ uri, name? }` pair; URIs always start
+   * with `file://` per the current spec.
+   *
+   * Empty when:
+   *   - the client did not declare the `roots` capability,
+   *   - the photon is running outside a live MCP session (CLI / unit test),
+   *   - the client returned an empty list.
+   *
+   * The runtime fetches `roots/list` once per session and refreshes on
+   * `notifications/roots/list_changed`, so reads inside a tool call are
+   * synchronous and consistent.
+   *
+   * @example
+   * ```typescript
+   * async listProjectFiles() {
+   *   const roots = this.roots;
+   *   if (roots.length === 0) return [];
+   *   // ...resolve files under each root.uri...
+   * }
+   * ```
+   */
+  get roots(): Array<{ uri: string; name?: string }> {
+    const store = executionContext.getStore() as
+      | { roots?: Array<{ uri: string; name?: string }> }
+      | undefined;
+    return store?.roots ?? [];
+  }
+
+  /**
+   * Notify subscribed MCP clients that the resource at `uri` has changed.
+   * Triggers `notifications/resources/updated` for every client that has
+   * issued `resources/subscribe` against this exact URI.
+   *
+   * Default no-op so calls from CLI execution (no live MCP server) do not
+   * throw. The runtime overrides this with a wired version on every
+   * instance it constructs; that wired version dispatches into the
+   * server's subscription registry.
+   *
+   * Use it from `@stateful` methods or any code path that mutates the
+   * data behind a `@resource <uri-template>` resolver:
+   *
+   * @example
+   * ```typescript
+   * async upsertPerson(params: { slug: string; ... }) {
+   *   this.people[params.slug] = ...;
+   *   this.notifyResourceUpdated(`person://${params.slug}`);
+   * }
+   * ```
+   */
+  notifyResourceUpdated(_uri: string): void {
+    // Runtime injects a wired version on every instance — see
+    // photon/src/loader.ts injectResourceNotifier. This default is for
+    // standalone use (CLI, unit tests) where no MCP server is attached.
+  }
+
+  /**
+   * 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
    *
@@ -231,11 +416,27 @@ export class Photon {
         .replace(/([A-Z])/g, '-$1')
         .toLowerCase()
         .replace(/^-/, '');
-      this._schedule = new ScheduleProvider(name, this._baseDir);
+      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.
    *

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

@@ -33,6 +33,12 @@ function warnHandlePrefixOnce(methodName: string): void {
   );
 }
 
+export interface HttpRoute {
+  method: 'GET' | 'POST';
+  path: string;
+  handler: string;
+}
+
 export interface ExtractedMetadata {
   tools: ExtractedSchema[];
   templates: TemplateInfo[];
@@ -48,8 +54,11 @@ export interface ExtractedMetadata {
    * - 'required': all methods require authenticated caller
    * - 'optional': caller populated if token present, anonymous allowed
    * - string URL: OIDC provider URL (implies required)
+   * - 'cf-access': use Cloudflare Access JWT to identify caller
    */
-  auth?: 'required' | 'optional' | string;
+  auth?: 'required' | 'optional' | 'cf-access' | string;
+  /** HTTP routes declared with @get or @post on individual methods */
+  httpRoutes?: HttpRoute[];
 }
 
 /**
@@ -93,6 +102,9 @@ export class SchemaExtractor {
     // MCP OAuth auth requirement (from @auth tag)
     let auth: 'required' | 'optional' | string | undefined;
 
+    // HTTP routes from @get / @post method-level tags
+    const httpRoutes: HttpRoute[] = [];
+
     try {
       // If source doesn't contain a class declaration, wrap it in one
       let sourceToParse = source;
@@ -156,6 +168,18 @@ export class SchemaExtractor {
           return;
         }
 
+        // @get /path or @post /path — HTTP-only route, not an MCP tool
+        const getMatch = jsdoc.match(/@get\s+(\/\S*)/i);
+        const postMatch = jsdoc.match(/@post\s+(\/\S*)/i);
+        if (getMatch || postMatch) {
+          httpRoutes.push({
+            method: getMatch ? 'GET' : 'POST',
+            path: (getMatch ?? postMatch)![1],
+            handler: methodName,
+          });
+          return;
+        }
+
         // Check if this is an async generator method (has asterisk token)
         const isGenerator = member.asteriskToken !== undefined;
 
@@ -562,6 +586,11 @@ export class SchemaExtractor {
       result.auth = auth;
     }
 
+    // Include HTTP routes if any
+    if (httpRoutes.length > 0) {
+      result.httpRoutes = httpRoutes;
+    }
+
     return result;
   }
 
@@ -1980,17 +2009,24 @@ export class SchemaExtractor {
   }
 
   /**
-   * Check if JSDoc contains @Template tag
+   * Check if a method's JSDoc marks it as an MCP prompt template.
+   * Canonical form: `@prompt`. Legacy form `@Template` still accepted
+   * for backward compatibility with photons authored before the rename.
    */
   private hasTemplateTag(jsdocContent: string): boolean {
-    return /@Template/i.test(jsdocContent);
+    return /@(?:Template|prompt)\b/i.test(jsdocContent);
   }
 
   /**
-   * Check if JSDoc contains @Static tag
+   * Check if a method's JSDoc marks it as a dynamic MCP resource resolver.
+   * Canonical form: `@resource <uri-template>`. Legacy form `@Static`
+   * still accepted. Disambiguation from the class-level static-file form
+   * (`@resource <id> <path>`) is by argument shape: the class-level form
+   * requires `<id>` followed by a path starting with `./` or `/`, which
+   * the URI-template form never matches.
    */
   private hasStaticTag(jsdocContent: string): boolean {
-    return /@Static/i.test(jsdocContent);
+    return /@(?:Static|resource)\b/i.test(jsdocContent);
   }
 
   /**
@@ -2448,11 +2484,12 @@ export class SchemaExtractor {
   }
 
   /**
-   * Extract URI pattern from @Static tag
-   * Example: @Static github://repos/{owner}/{repo}/readme
+   * Extract URI pattern from a method's resource annotation.
+   * Canonical: `@resource github://repos/{owner}/{repo}/readme`
+   * Legacy: `@Static github://repos/{owner}/{repo}/readme`
    */
   private extractStaticURI(jsdocContent: string): string | null {
-    const match = jsdocContent.match(/@Static\s+([\w:\/\{\}\-_.]+)/i);
+    const match = jsdocContent.match(/@(?:Static|resource)\s+([\w:\/\{\}\-_.]+)/i);
     return match ? match[1].trim() : null;
   }
 
@@ -3143,8 +3180,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}`);