@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/core/capability-router.ts

@@ -0,0 +1,273 @@
+import {
+  AmbiguousDecisionProviderError,
+  CAPABILITY_ROUTER_MODES,
+  CAPABILITY_ROUTE_DECISION_NAME,
+  DecisionProviderUnavailableError,
+  capabilityRouteDecision,
+  decideCapabilityRoute,
+  toRoutableCapabilities,
+  type CapabilityRouterMode,
+  type DecisionEvaluator,
+  type DecisionTraceOptions,
+  type RoutableCapability,
+} from '@ixo/common/ai/decisions';
+import type { Logger } from '../plugin-api/types';
+import { unmetRequirements } from './manifest';
+import type { RegisteredManifest } from './registries';
+
+/**
+ * Predicts, before the first model call of a turn, which on-demand plugin the
+ * user's message needs and preloads that plugin's tools for the turn, so the
+ * model does not spend a round trip on `load_capability`.
+ *
+ * The preload is one-turn state only: it is admitted by the capability gate
+ * and visible as loaded to tool handlers, but never written to the graph's
+ * `loadedPlugins` channel. The router fails open — any evaluation failure
+ * preloads nothing and the turn proceeds exactly as without a router.
+ */
+export interface CapabilityRouterOptions {
+  evaluator: DecisionEvaluator;
+  logger: Logger;
+  /**
+   * Keeps a shadow evaluation alive after the turn has moved on
+   * (`ctx.waitUntil` on Workers). Without it the promise is merely detached.
+   */
+  background?: (work: Promise<unknown>) => void;
+  now?: () => number;
+}
+
+export interface CapabilityRouteTurn {
+  mode: CapabilityRouterMode;
+  /** Every registered manifest; the router picks the routable candidates. */
+  manifests: readonly RegisteredManifest[];
+  /** Plugins the thread has already loaded (the checkpointed channel). */
+  loaded: ReadonlySet<string>;
+  /**
+   * Plugins the user's delegation leaves with nothing to use (all of their
+   * tools admin-plane and not granted): never offered to the router. A
+   * function is called only when the router actually evaluates (not when
+   * it is off, or the message is empty), so the host does not compute the
+   * set for nothing.
+   */
+  hidden?: ReadonlySet<string> | (() => Promise<ReadonlySet<string>>);
+  /**
+   * The user's delegation, as `ctx.ucan.hasCapability`: a plugin whose
+   * `manifest.requires` it does not grant is never offered (the gate would
+   * refuse every one of its tools). Omitted, `requires` is not checked.
+   */
+  hasCapability?: (resource: string, action: string) => boolean;
+  /** The user's message text for this turn. */
+  text: string;
+  requestId: string;
+  /** The turn's abort signal; only an awaited (`on`) evaluation is bound to it. */
+  signal?: AbortSignal;
+  /**
+   * The turn's tracer and trace metadata. The router runs before the graph,
+   * outside any LangChain run, so without these its Decision is not traced.
+   */
+  trace?: DecisionTraceOptions;
+  /**
+   * Shadow mode only: receives what the router would have preloaded once its
+   * evaluation completes, so the host can compare it with what the turn
+   * actually loaded.
+   */
+  onShadowVerdict?: (wouldPreload: readonly string[]) => void;
+}
+
+export type CapabilityRouter = (
+  turn: CapabilityRouteTurn,
+) => Promise<ReadonlySet<string>>;
+
+const NOTHING: ReadonlySet<string> = new Set<string>();
+
+/** Narrows an env value to a router mode; anything else is `off`. */
+export function capabilityRouterMode(value: unknown): CapabilityRouterMode {
+  return CAPABILITY_ROUTER_MODES.find((mode) => mode === value) ?? 'off';
+}
+
+/**
+ * The manifests the router may choose from: effectively on-demand plugins the
+ * thread has not loaded yet. `always` plugins are already bound and `silent`
+ * ones are never surfaced, so predicting them is pointless; a `hidden` one
+ * (no tool the user's delegation reaches), or one whose `requires` the
+ * delegation (`hasCapability`) does not grant, is not even named to the
+ * router.
+ */
+export function routableCandidates(
+  manifests: readonly RegisteredManifest[],
+  loaded: ReadonlySet<string>,
+  hidden: ReadonlySet<string> = NOTHING,
+  hasCapability?: (resource: string, action: string) => boolean,
+): RoutableCapability[] {
+  return toRoutableCapabilities(
+    manifests
+      .filter(
+        ({ pluginName, manifest }) =>
+          (manifest.visibility ?? 'on-demand') === 'on-demand' &&
+          !loaded.has(pluginName) &&
+          !hidden.has(pluginName) &&
+          (hasCapability === undefined ||
+            unmetRequirements(manifest, hasCapability).length === 0),
+      )
+      .map(({ pluginName, manifest }) => ({
+        name: pluginName,
+        title: manifest.title,
+        summary: manifest.summary,
+      })),
+  );
+}
+
+/**
+ * After-turn comparison for shadow mode: which plugins the turn loaded on its
+ * own, and whether that matches what the router would have preloaded.
+ */
+export function shadowAgreement(args: {
+  priorLoaded: ReadonlySet<string>;
+  loadedAfter: ReadonlySet<string>;
+  wouldPreload: readonly string[];
+}): { loadedDuringTurn: string[]; agree: boolean } {
+  const loadedDuringTurn = Array.from(args.loadedAfter).filter(
+    (name) => !args.priorLoaded.has(name),
+  );
+  const predicted = new Set(args.wouldPreload);
+  const agree =
+    predicted.size === loadedDuringTurn.length &&
+    loadedDuringTurn.every((name) => predicted.has(name));
+  return { loadedDuringTurn, agree };
+}
+
+function errorName(error: unknown): string {
+  return error instanceof Error ? error.name : typeof error;
+}
+
+function list(names: readonly string[]): string {
+  return `[${names.join(', ')}]`;
+}
+
+export function createCapabilityRouter(
+  options: CapabilityRouterOptions,
+): CapabilityRouter {
+  const { evaluator, logger } = options;
+  const now = options.now ?? (() => Date.now());
+  const background =
+    options.background ??
+    ((work: Promise<unknown>) => {
+      void work;
+    });
+  // A missing Decision provider is a deployment fact, not a per-turn event:
+  // said once per object, then the router stays quiet.
+  let unavailableWarned = false;
+
+  // An ambiguous multi-provider configuration is a subclass: equally a
+  // deployment fact, but fixed by routing rather than by adding a provider.
+  const unavailable = (
+    error: unknown,
+  ): error is DecisionProviderUnavailableError =>
+    error instanceof DecisionProviderUnavailableError;
+
+  const warnUnavailable = (
+    requestId: string,
+    mode: CapabilityRouterMode,
+    error: DecisionProviderUnavailableError,
+  ) => {
+    if (unavailableWarned) return;
+    unavailableWarned = true;
+    const hint =
+      error instanceof AmbiguousDecisionProviderError
+        ? `route ${CAPABILITY_ROUTE_DECISION_NAME} or set decisionProviderPolicy.defaultProviderId`
+        : 'set DECISION_PROVIDER or CAPABILITY_ROUTER=off';
+    logger.warn(
+      `[capability-router] request=${requestId} mode=${mode} status=fallback reason=${error.name} (${hint})`,
+    );
+  };
+
+  return async (turn) => {
+    if (turn.mode === 'off') return NOTHING;
+    const text = turn.text.trim();
+    if (!text) return NOTHING;
+    let hidden: ReadonlySet<string> | undefined;
+    try {
+      hidden =
+        typeof turn.hidden === 'function' ? await turn.hidden() : turn.hidden;
+    } catch (error) {
+      // Fail open like any other router failure: no preload this turn.
+      logger.warn(
+        `[capability-router] request=${turn.requestId} mode=${turn.mode} status=fallback reason=${errorName(error)} (hidden plugins unavailable)`,
+      );
+      return NOTHING;
+    }
+    const capabilities = routableCandidates(
+      turn.manifests,
+      turn.loaded,
+      hidden,
+      turn.hasCapability,
+    );
+    if (capabilities.length === 0) return NOTHING;
+
+    // The turn is prepared from a checkpoint read without its messages, so
+    // the router sees the current message only; `recentTurns` stays empty.
+    const input = { text, recentTurns: [], capabilities };
+    const { requestId } = turn;
+
+    if (turn.mode === 'shadow') {
+      const started = now();
+      background(
+        evaluator
+          .evaluate(capabilityRouteDecision, input, turn.trace)
+          .then((evaluation) => {
+            const verdict = decideCapabilityRoute(evaluation, capabilities);
+            logger.log(
+              `[capability-router-shadow] request=${requestId} status=ok ` +
+                `needsCapability=${verdict.needsCapability.toFixed(2)} ` +
+                `capability=${verdict.capability ?? '-'} ` +
+                `capabilityConfidence=${verdict.capabilityConfidence?.toFixed(2) ?? '-'} ` +
+                `wouldPreload=${list(verdict.preload)} reason=${verdict.reason} ` +
+                `latencyMs=${now() - started} provider=${evaluation.provider} model=${evaluation.model}`,
+            );
+            turn.onShadowVerdict?.(verdict.preload);
+          })
+          .catch((error: unknown) => {
+            if (unavailable(error)) {
+              warnUnavailable(requestId, 'shadow', error);
+              return;
+            }
+            logger.log(
+              `[capability-router-shadow] request=${requestId} status=failed errorType=${errorName(error)} latencyMs=${now() - started}`,
+            );
+          }),
+      );
+      return NOTHING;
+    }
+
+    try {
+      const evaluation = await evaluator.evaluate(
+        capabilityRouteDecision,
+        input,
+        {
+          ...turn.trace,
+          ...(turn.signal && { signal: turn.signal }),
+        },
+      );
+      const verdict = decideCapabilityRoute(evaluation, capabilities);
+      if (verdict.preload.length === 0) {
+        logger.debug?.(
+          `[capability-router] request=${requestId} mode=on status=none reason=${verdict.reason} candidates=${capabilities.length}`,
+        );
+        return NOTHING;
+      }
+      logger.log(
+        `[capability-router] request=${requestId} preloaded=${list(verdict.preload)} candidates=${capabilities.length}`,
+      );
+      return new Set(verdict.preload);
+    } catch (error) {
+      if (unavailable(error)) {
+        warnUnavailable(requestId, 'on', error);
+      } else {
+        logger.warn(
+          `[capability-router] request=${requestId} mode=on status=fallback reason=${errorName(error)}`,
+        );
+      }
+      return NOTHING;
+    }
+  };
+}

package/src/core/context-budget.ts

@@ -3,7 +3,8 @@
  * (`context-window.ts`) so that they scale with the model:
  *
  *   - `summarizeAtTokens`  — the history is condensed once it is this large
- *                            (default half the window; Hermes fires at 50%);
+ *                            (default half the window; Hermes fires at 50%),
+ *                            never above what the summarizer may read;
  *   - `pruneAtTokens`      — above this, old tool results are demoted to
  *                            one-liners in the request (no model call, no
  *                            state change) before the model sees them;
@@ -64,8 +65,14 @@ export interface ContextBudget {
   resultCapChars: number;
   requestCapTokens: number;
   outputReserveTokens: number;
-  /** The summarizer's own input limit (what it may read to write the summary). */
+  /**
+   * The summarizer's own input limit (what it may read to write the summary):
+   * the smaller of what the main model's request cap and the summarizing
+   * model's own request cap leave, less a margin for the summary prompt.
+   */
   summaryInputTokens: number;
+  /** The summarizing model's window, when the host resolved it. */
+  summaryWindowTokens?: number;
   summarizeTriggerMessages?: number;
   keepMessages: number;
 }
@@ -142,12 +149,14 @@ export function contextKnobs(
   };
 }
 
-/** The budget for a turn on `resolution.model`. */
-export function contextBudgetFor(
-  resolution: ContextWindowResolution,
-  knobs: ContextKnobs = DEFAULT_CONTEXT_KNOBS,
-): ContextBudget {
-  const window = resolution.tokens;
+/** Tokens the summary prompt and its framing need on top of the history it reads. */
+const SUMMARY_PROMPT_MARGIN_TOKENS = 4_000;
+
+/** What a request to a model with `window` may hold, the reply reserve left out. */
+function requestCapFor(
+  window: number,
+  knobs: ContextKnobs,
+): { requestCapTokens: number; outputReserveTokens: number } {
   // The reply reserve can never eat a small window: cap it at a quarter.
   const outputReserveTokens = Math.min(
     knobs.outputReserveTokens,
@@ -157,9 +166,42 @@ export function contextBudgetFor(
     1_000,
     Math.floor(window * knobs.requestFraction) - outputReserveTokens,
   );
+  return { requestCapTokens, outputReserveTokens };
+}
+
+/**
+ * The budget for a turn on `resolution.model`. `summarizer` is the window of
+ * the model that writes the summary (the `routing` role), resolved the same
+ * way: the history it is handed is bounded by its own window too, not only
+ * by the main model's. Omitted, the main model's window alone bounds it.
+ */
+export function contextBudgetFor(
+  resolution: ContextWindowResolution,
+  knobs: ContextKnobs = DEFAULT_CONTEXT_KNOBS,
+  summarizer?: ContextWindowResolution,
+): ContextBudget {
+  const window = resolution.tokens;
+  const { requestCapTokens, outputReserveTokens } = requestCapFor(
+    window,
+    knobs,
+  );
+  const summaryRequestCap = summarizer
+    ? Math.min(
+        requestCapTokens,
+        requestCapFor(summarizer.tokens, knobs).requestCapTokens,
+      )
+    : requestCapTokens;
+  const summaryInputTokens = Math.max(
+    1_000,
+    summaryRequestCap - SUMMARY_PROMPT_MARGIN_TOKENS,
+  );
+  // The summarizer keeps only the newest `summaryInputTokens` of what it is
+  // asked to condense and drops the rest unread — the earlier summary first.
+  // Summarizing starts no later than that, so nothing is lost unsummarized.
   const summarizeAtTokens = Math.min(
     Math.floor(window * knobs.summarizeFraction),
     requestCapTokens,
+    summaryInputTokens,
   );
   const pruneAtTokens = Math.min(
     Math.floor(window * knobs.pruneFraction),
@@ -177,7 +219,8 @@ export function contextBudgetFor(
     ),
     requestCapTokens,
     outputReserveTokens,
-    summaryInputTokens: Math.max(1_000, requestCapTokens - 4_000),
+    summaryInputTokens,
+    ...(summarizer ? { summaryWindowTokens: summarizer.tokens } : {}),
     ...(knobs.summarizeTriggerMessages !== undefined
       ? { summarizeTriggerMessages: knobs.summarizeTriggerMessages }
       : {}),
@@ -196,6 +239,50 @@ export function estimateContentTokens(content: unknown): number {
   }
 }
 
+/**
+ * Per-message memo of the chars/4 estimates: every model step of a turn
+ * re-estimates the whole history (the context guard, the turn budget, the
+ * summarizer's trigger), and the history is the same message objects from
+ * step to step. An entry is reused only while the message still holds the
+ * same `content` / `tool_calls` values it was computed from.
+ */
+interface MessageEstimate {
+  content: unknown;
+  contentTokens: number;
+  toolCalls?: { value: unknown; tokens: number };
+}
+
+const messageEstimates = new WeakMap<object, MessageEstimate>();
+
+function estimateOf(message: { content: unknown }): MessageEstimate {
+  const cached = messageEstimates.get(message);
+  if (cached && cached.content === message.content) return cached;
+  const fresh: MessageEstimate = {
+    content: message.content,
+    contentTokens: estimateContentTokens(message.content),
+  };
+  messageEstimates.set(message, fresh);
+  return fresh;
+}
+
+/** `estimateContentTokens(message.content)`, memoised per message. */
+export function messageContentTokens(message: { content: unknown }): number {
+  return estimateOf(message).contentTokens;
+}
+
+/** `estimateContentTokens(toolCalls)` for `message`'s tool calls, memoised per message. */
+export function messageToolCallTokens(
+  message: { content: unknown },
+  toolCalls: unknown,
+): number {
+  const entry = estimateOf(message);
+  if (entry.toolCalls && entry.toolCalls.value === toolCalls)
+    return entry.toolCalls.tokens;
+  const tokens = estimateContentTokens(toolCalls);
+  entry.toolCalls = { value: toolCalls, tokens };
+  return tokens;
+}
+
 export function describeBudget(b: ContextBudget): string {
-  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens}`;
+  return `model=${b.model} window=${b.windowTokens} (${b.origin}) summarizeAt=${b.summarizeAtTokens} pruneAt=${b.pruneAtTokens} resultCap=${b.resultCapChars}c requestCap=${b.requestCapTokens} reserve=${b.outputReserveTokens} summaryInput=${b.summaryInputTokens}${b.summaryWindowTokens !== undefined ? ` (summarizer window ${b.summaryWindowTokens})` : ''}`;
 }

package/src/core/env.ts

@@ -1,7 +1,17 @@
+import {
+  capabilityRouterEnvShape,
+  decisionProviderEnvShape,
+} from '@ixo/common/ai/decisions';
 import { z } from 'zod';
 import type { OraclePlugin } from '../plugin-api/oracle-plugin';
 import type { Logger } from '../plugin-api/types';
 import { NOOP_LOGGER } from './utils';
+import { FEEDBACK_ENV_PREFIX } from '../feedback/contract';
+import {
+  isSecureUrl,
+  MAX_ARTIFACT_SWEEP_INTERVAL_HOURS,
+  MAX_ARTIFACT_TTL_DAYS,
+} from '../artifacts/config';
 
 /**
  * Tier-0 (core) environment for the Workers runtime. Mirrors
@@ -29,6 +39,11 @@ import { NOOP_LOGGER } from './utils';
  */
 export const TURN_RECURSION_LIMIT_DEFAULT = 600;
 
+/** An https URL, or http on localhost / 127.0.0.1 (local harness). */
+const secureUrlSchema = z.string().refine((raw) => isSecureUrl(raw), {
+  message: 'must be an https URL (http only on localhost)',
+});
+
 export const baseEnvSchema = z.object({
   // --- identity -----------------------------------------------------------
   ORACLE_NAME: z.string().min(1),
@@ -50,6 +65,13 @@ export const baseEnvSchema = z.object({
    * declares. Default 15 minutes.
    */
   UCAN_AUTH_MAX_TTL_SECONDS: z.coerce.number().int().positive().default(900),
+  /**
+   * `true` lets a bare `x-ucan-delegation` (no invocation) authenticate a
+   * request — the legacy fallback, for clients that do not send a UCAN
+   * invocation yet. Off by default: a delegation travels on as proof in
+   * downstream invocations, so it must not also be a login credential.
+   */
+  UCAN_ALLOW_BARE_DELEGATION_AUTH: z.enum(['true', 'false']).optional(),
 
   // --- matrix -------------------------------------------------------------
   MATRIX_BASE_URL: z.string().min(1),
@@ -114,6 +136,45 @@ export const baseEnvSchema = z.object({
     .int()
     .min(1)
     .default(TURN_RECURSION_LIMIT_DEFAULT),
+  /**
+   * The turn budget (docs/plans/workers-harness-hardening.md): cumulative
+   * model tokens across the main agent, sub-agents and helper models; tool
+   * attempts; and the wall-clock deadline. Exhaustion ends the turn and keeps
+   * the work done so far. Parsed by `turnLimitsFromEnv`.
+   */
+  TURN_MAX_TOKENS: z.coerce.number().int().positive().default(500_000),
+  TURN_MAX_TOOL_CALLS: z.coerce.number().int().positive().default(120),
+  TURN_TIMEOUT_MS: z.coerce.number().int().positive().default(600_000),
+  /**
+   * The repetition guard's per-turn caps on identical successful calls
+   * (same tool, same arguments): a write, and a read or `repeatable` tool.
+   * Parsed by `repetitionCapsFromEnv`.
+   */
+  TURN_MAX_IDENTICAL_WRITES: z.coerce.number().int().positive().default(1),
+  TURN_MAX_IDENTICAL_READS: z.coerce.number().int().positive().default(5),
+  /**
+   * Time limit per plugin `getRequestAdmission` handler (ms). A handler that
+   * has not answered by then counts as `pass` and the turn goes on to the
+   * next handler or the agent. See docs/architecture/request-admission.md.
+   */
+  REQUEST_ADMISSION_TIMEOUT_MS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(2_000),
+
+  // --- decisions ----------------------------------------------------------
+  // Bounded semantic Decision provider (`DECISION_PROVIDER`, `DECISION_MODEL`,
+  // Cloudflare credentials), shared with the Node runtime and optional so
+  // oracles without Decisions keep their behaviour. `openrouter-jev` reuses
+  // `OPEN_ROUTER_API_KEY` (required above). On Workers `cloudflare-jev`
+  // prefers the `AI` binding over the account credentials, which are only
+  // needed when the binding is not declared.
+  ...decisionProviderEnvShape,
+  // `CAPABILITY_ROUTER` (`off` | `shadow` | `on`, default `off`): the first
+  // runtime consumer of Decisions. It predicts the on-demand plugin a message
+  // needs and preloads it for the turn; it needs a `DECISION_PROVIDER`.
+  ...capabilityRouterEnvShape,
 
   // --- durable runs (docs/plans/durable-runs.md) ---------------------------
   // Parsed by `runDurabilityConfig` (src/do/run-store.ts) with defaults:
@@ -144,9 +205,49 @@ export const baseEnvSchema = z.object({
   TOOL_RESULT_TTL_HOURS: z.string().optional(),
   TOOL_RESULT_R2_MIN_BYTES: z.string().optional(),
 
+  // --- chat delivery (docs/chat-delivery.md) -------------------------------
+  /**
+   * `true` gives Matrix room turns the chat style (several short messages,
+   * long content as artefacts); unset keeps `OracleConfig.delivery.matrixChat`,
+   * which defaults to one message per reply.
+   */
+  MATRIX_CHAT_DELIVERY: z.enum(['true', 'false']).optional(),
+  /**
+   * Artefact links (the bucket is a binding, `ARTIFACT_BUCKET`): the oracle's
+   * public origin, an optional shared viewer page, and the link lifetime in
+   * days. Links carry the decryption key, so both URLs must be https (http
+   * only on localhost).
+   */
+  ORACLE_PUBLIC_URL: secureUrlSchema.optional(),
+  ARTIFACT_VIEWER_URL: secureUrlSchema.optional(),
+  ARTIFACT_LINK_TTL_DAYS: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_ARTIFACT_TTL_DAYS)
+    .optional(),
+  /**
+   * Hours between the cron's sweeps of expired share copies in the bucket
+   * (unset = 24). Only runs where `ARTIFACT_BUCKET` is bound and a cron
+   * trigger is declared.
+   */
+  ARTIFACT_SWEEP_INTERVAL_HOURS: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_ARTIFACT_SWEEP_INTERVAL_HOURS)
+    .optional(),
+
   // --- misc ---------------------------------------------------------------
   LOG_LEVEL: z.string().default('info'),
   CORS_ORIGIN: z.string().default('*'),
+  /**
+   * Comma-separated DIDs allowed onto the gateway-wide operator routes
+   * (`/debug/matrix/*`). Unset: any authenticated caller (with
+   * `ORACLE_DEBUG_ROUTES=true`). A list with an entry that is not a DID
+   * admits nobody.
+   */
+  ORACLE_OPERATOR_DIDS: z.string().optional(),
 });
 
 export type BaseEnv = z.infer<typeof baseEnvSchema>;
@@ -207,8 +308,18 @@ export function composeEnvSchema(
     if (!plugin.configSchema) continue;
     const shape = plugin.configSchema.shape as Record<string, unknown>;
     for (const key of Object.keys(shape)) {
+      // Runtime-only secrets (the feedback sink's Linear key and pseudonym
+      // secret) must never reach a plugin's `ctx.config`.
+      if (key.startsWith(FEEDBACK_ENV_PREFIX))
+        throw new Error(
+          `Plugin '${plugin.name}' declares env key '${key}': the '${FEEDBACK_ENV_PREFIX}' prefix is reserved for the runtime`,
+        );
       const previous = pluginOwnership.get(key);
       if (previous !== undefined && previous !== plugin.name) {
+        // Plugins that declare the very same schema object share the key on
+        // purpose (the wallet-signing chain ids): nothing is replaced, and
+        // the first declarer stays its owner.
+        if (merged.shape[key] === shape[key]) continue;
         logger.warn(
           `[boot] env key '${key}' is defined by both '${previous}' and '${plugin.name}'; '${plugin.name}' wins.`,
         );

package/src/core/execution-profile.ts

@@ -0,0 +1,17 @@
+export const TASK_EXECUTION_PROFILES = ['supplied-context-markdown'] as const;
+
+export type TaskExecutionProfile = (typeof TASK_EXECUTION_PROFILES)[number];
+
+export function isTaskExecutionProfile(
+  value: unknown,
+): value is TaskExecutionProfile {
+  return (TASK_EXECUTION_PROFILES as readonly unknown[]).includes(value);
+}
+
+export function taskExecutionProfile(
+  value: unknown,
+): TaskExecutionProfile | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (isTaskExecutionProfile(value)) return value;
+  throw new Error('Unsupported task execution profile');
+}