@ixo/oracle-runtime-workers 0.2.0

package/src/core/middlewares/tool-repetition-guard.ts

@@ -0,0 +1,125 @@
+import {
+  AIMessage,
+  type BaseMessage,
+  ToolMessage,
+} from '@langchain/core/messages';
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types';
+import { NOOP_LOGGER } from '../utils';
+
+export interface ToolRepetitionGuardMiddlewareOptions {
+  /**
+   * How many messages back to scan for a prior identical failed call.
+   * Default 20 — enough to catch in-turn loops without trawling whole histories.
+   */
+  lookback?: number;
+  /** Optional logger; defaults to a no-op. */
+  logger?: Logger;
+}
+
+/**
+ * Detects when the agent issues the same `(toolName, args)` pair after that
+ * exact call already failed inside the recent window, and short-circuits
+ * before the tool is invoked again. The short-circuit message quotes the
+ * earlier error and tells the model to change tools/args instead.
+ *
+ * `toolRetryMiddleware` retries inside one call; this guard prevents the
+ * model from making the *next* identical call.
+ */
+export const createToolRepetitionGuardMiddleware = (
+  options: ToolRepetitionGuardMiddlewareOptions = {},
+): AgentMiddleware => {
+  const logger = options.logger ?? NOOP_LOGGER;
+  const lookback = options.lookback ?? 20;
+
+  return createMiddleware({
+    name: 'ToolRepetitionGuardMiddleware',
+    wrapToolCall: async (toolCallRequest, handler) => {
+      const { toolCall, state } = toolCallRequest;
+      const toolName = toolCall.name ?? toolCallRequest.tool?.name;
+      if (!toolName) return handler(toolCallRequest);
+
+      const argsKey = canonicalArgsKey(toolCall.args);
+      const messages = state.messages ?? [];
+      const start = Math.max(0, messages.length - lookback);
+
+      for (let i = messages.length - 1; i >= start; i--) {
+        const msg = messages[i];
+        if (!(msg instanceof ToolMessage)) continue;
+        if (msg.status !== 'error') continue;
+        if (msg.name !== toolName) continue;
+
+        const priorArgs = findToolCallArgsById(messages, msg.tool_call_id);
+        if (priorArgs === undefined) continue;
+        if (canonicalArgsKey(priorArgs) !== argsKey) continue;
+
+        const priorError = toolMessageText(msg);
+        logger.warn(
+          `Repetition guard: short-circuiting duplicate failed call to ${toolName}`,
+          { toolName, priorError },
+        );
+        return new ToolMessage({
+          content: [
+            `You already called \`${toolName}\` with these exact arguments earlier in this turn and it failed with:`,
+            '',
+            priorError,
+            '',
+            'Do NOT repeat the same call. Read the error message, then either:',
+            '- change the arguments to satisfy the constraint the error describes, OR',
+            '- pick a different tool that fits the constraint.',
+          ].join('\n'),
+          tool_call_id: toolCall.id ?? '',
+          name: toolName,
+          status: 'error',
+        });
+      }
+
+      return handler(toolCallRequest);
+    },
+  });
+};
+
+function canonicalArgsKey(args: unknown): string {
+  if (args === null || args === undefined) return 'null';
+  if (typeof args !== 'object') return JSON.stringify(args);
+  if (Array.isArray(args)) {
+    return `[${args.map(canonicalArgsKey).join(',')}]`;
+  }
+  const obj = args as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalArgsKey(obj[k])}`).join(',')}}`;
+}
+
+function toolMessageText(msg: ToolMessage): string {
+  const content = msg.content;
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((block) => {
+        if (typeof block === 'string') return block;
+        if (block && typeof block === 'object' && 'text' in block) {
+          const text = (block as { text?: unknown }).text;
+          return typeof text === 'string' ? text : '';
+        }
+        return '';
+      })
+      .join('\n');
+  }
+  return '';
+}
+
+function findToolCallArgsById(
+  messages: BaseMessage[],
+  callId: string | undefined,
+): unknown {
+  if (!callId) return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (!AIMessage.isInstance(m)) continue;
+    const toolCalls = m.tool_calls;
+    if (!toolCalls) continue;
+    const hit = toolCalls.find((tc) => tc.id === callId);
+    if (hit) return hit.args;
+  }
+  return undefined;
+}

package/src/core/middlewares/tool-validation.ts

@@ -0,0 +1,83 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import { type AgentMiddleware, createMiddleware, ToolMessage } from 'langchain';
+import type { Logger } from '../../plugin-api/types';
+import { NOOP_LOGGER } from '../utils';
+
+export interface ToolValidationMiddlewareOptions {
+  /**
+   * Tool names whose dangling `ToolMessage` outputs should be stripped before
+   * the next model call. These are typically sub-agent tools whose responses
+   * are summarised by their parent agent rather than being interpreted by the
+   * model directly.
+   */
+  skipToolNames?: string[];
+  /** Optional logger; defaults to a no-op. */
+  logger?: Logger;
+}
+
+/**
+ * Catches tool validation errors (Zod / schema mismatches) and turns them
+ * into a `ToolMessage` describing the failure, so the model can recover
+ * instead of the graph crashing.
+ *
+ * Also strips `ToolMessage`s for tools listed in `skipToolNames` from the
+ * state before the next model call.
+ */
+export const createToolValidationMiddleware = (
+  options: ToolValidationMiddlewareOptions = {},
+): AgentMiddleware => {
+  const logger = options.logger ?? NOOP_LOGGER;
+  const skipToolNames = new Set(options.skipToolNames ?? []);
+
+  return createMiddleware({
+    name: 'ToolValidationMiddleware',
+    wrapToolCall: async (toolCallRequest, handler) => {
+      const { toolCall } = toolCallRequest;
+      try {
+        return await handler(toolCallRequest);
+      } catch (error: unknown) {
+        const errorMessage = error instanceof Error ? error.message : '';
+        const isSchemaError =
+          errorMessage.includes('did not match expected schema') ||
+          errorMessage.includes('Received tool input did not match') ||
+          errorMessage.includes('schema') ||
+          (error instanceof Error && error.name === 'ZodError');
+
+        if (!isSchemaError) throw error;
+
+        const toolName = toolCall.name ?? toolCallRequest.tool?.name ?? '';
+        logger.warn(`Tool validation error for ${toolName}: ${errorMessage}`, {
+          toolName,
+          toolArgs: toolCall.args,
+          error: errorMessage,
+        });
+
+        return new ToolMessage({
+          content: `Error: The tool "${toolName}" was called with invalid parameters. ${errorMessage}. Please check the tool's required parameters and try again with the correct format.`,
+          tool_call_id: toolCall.id ?? '',
+          name: toolName,
+        });
+      }
+    },
+    beforeModel(state) {
+      if (skipToolNames.size === 0) return state;
+
+      const toolMessage = state.messages.find(
+        (message: BaseMessage) => message.type === 'tool',
+      );
+
+      if (toolMessage?.name && skipToolNames.has(toolMessage.name)) {
+        logger.log(
+          `Tool validation middleware: ${toolMessage.name} is a skip-listed tool, removing tool messages before next model call`,
+        );
+        return {
+          ...state,
+          messages: state.messages.filter(
+            (message: BaseMessage) => message.type !== 'tool',
+          ),
+        };
+      }
+      return state;
+    },
+  });
+};

package/src/core/middlewares/work-status.ts

@@ -0,0 +1,57 @@
+/**
+ * Drives the per-turn `work_status` liveness card from inside the graph —
+ * the port of the Node runtime's `WorkStatusMiddleware`: one `Step n ·
+ * Thinking…` per model call and one `Step n · <Tool name>…` per tool call,
+ * read off the run context's `session.requestId`. A pure side effect: it
+ * returns the handler's result verbatim and never throws on its own.
+ *
+ * Turns that were not registered with the producer (HTTP turns, task runs)
+ * are no-ops, so the middleware is safe to install unconditionally.
+ */
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+import {
+  humanizeToolLabel,
+  type WorkStatusProducer,
+} from '../../matrix/work-status';
+
+const THINKING_LABEL = 'Thinking…';
+
+export interface WorkStatusMiddlewareOptions {
+  producer: Pick<WorkStatusProducer, 'step'>;
+}
+
+function readRequestId(context: unknown): string | undefined {
+  if (typeof context !== 'object' || context === null) return undefined;
+  if (!('session' in context)) return undefined;
+  const session: unknown = context.session;
+  if (typeof session !== 'object' || session === null) return undefined;
+  if (!('requestId' in session)) return undefined;
+  const requestId: unknown = session.requestId;
+  return typeof requestId === 'string' && requestId.length > 0
+    ? requestId
+    : undefined;
+}
+
+export function createWorkStatusMiddleware(
+  options: WorkStatusMiddlewareOptions,
+): AgentMiddleware {
+  const { producer } = options;
+  return createMiddleware({
+    name: 'WorkStatusMiddleware',
+    wrapModelCall: (request, handler) => {
+      const requestId = readRequestId(request.runtime?.context);
+      if (requestId) producer.step(requestId, THINKING_LABEL);
+      return handler(request);
+    },
+    wrapToolCall: (toolCallRequest, handler) => {
+      const requestId = readRequestId(toolCallRequest.runtime?.context);
+      if (requestId) {
+        producer.step(
+          requestId,
+          humanizeToolLabel(toolCallRequest.toolCall.name),
+        );
+      }
+      return handler(toolCallRequest);
+    },
+  });
+}

package/src/core/openrouter-pricing.ts

@@ -0,0 +1,124 @@
+/**
+ * Live OpenRouter list prices for the model catalog — the Workers port of the
+ * Node runtime's `llm/openrouter-pricing.ts`.
+ *
+ * Fetched from OpenRouter's public models API and cached per isolate for an
+ * hour. The catalog carries baseline prices so `GET /models` always answers;
+ * this module upgrades them to live numbers when the call succeeds and
+ * silently keeps serving the last good map (or nothing, so the baseline
+ * applies) when it doesn't. Prices returned here are RAW provider list
+ * prices; the markup is applied by `buildModelListing`.
+ *
+ * Per isolate rather than per process: a cold isolate pays one ~100 ms fetch
+ * on its first `/models`, then serves from memory until evicted.
+ */
+import { z } from 'zod';
+import type { ModelPrice } from './llm';
+
+export const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
+export const OPENROUTER_PRICE_CACHE_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * OpenRouter returns `pricing.prompt` / `pricing.completion` as strings in USD
+ * **per token** (e.g. `"0.0000002"`). Only those two fields are read, so a
+ * schema change upstream can't break the listing.
+ */
+const openRouterModelsSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.string(),
+      pricing: z
+        .object({
+          prompt: z.string().optional(),
+          completion: z.string().optional(),
+        })
+        .optional(),
+    }),
+  ),
+});
+
+interface PriceCache {
+  fetchedAt: number;
+  prices: Map<string, ModelPrice>;
+}
+
+let cache: PriceCache | null = null;
+
+/** Convert an OpenRouter `$/token` string to `$/million tokens`, or `null`. */
+function perMillion(pricePerToken: string | undefined): number | null {
+  if (pricePerToken == null) return null;
+  const perToken = Number(pricePerToken);
+  if (!Number.isFinite(perToken)) return null;
+  return perToken * 1_000_000;
+}
+
+function parsePrices(
+  data: z.infer<typeof openRouterModelsSchema>['data'],
+): Map<string, ModelPrice> {
+  const out = new Map<string, ModelPrice>();
+  for (const model of data) {
+    const inputPerMillion = perMillion(model.pricing?.prompt);
+    const outputPerMillion = perMillion(model.pricing?.completion);
+    if (inputPerMillion == null || outputPerMillion == null) continue;
+    out.set(model.id, { inputPerMillion, outputPerMillion });
+  }
+  return out;
+}
+
+export interface FetchOpenRouterPricesOptions {
+  /** Sent as a bearer when present (higher rate limits); the endpoint is public. */
+  apiKey?: string;
+  /** Test seam / custom transport. Defaults to the global `fetch`. */
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+  now?: () => number;
+  logger?: { warn: (message: string) => void };
+}
+
+/**
+ * Live OpenRouter prices keyed by model id ($/million tokens). Cached for an
+ * hour. Never throws: on any failure it returns the last cached map, or an
+ * empty map (so the caller falls back to the catalog's baseline prices).
+ */
+export async function fetchOpenRouterPrices(
+  opts: FetchOpenRouterPricesOptions = {},
+): Promise<ReadonlyMap<string, ModelPrice>> {
+  const now = opts.now ?? Date.now;
+  if (cache && now() - cache.fetchedAt < OPENROUTER_PRICE_CACHE_TTL_MS) {
+    return cache.prices;
+  }
+  // The global `fetch` must be called as a function of the global scope on
+  // workerd ("Illegal invocation" when handed around as a bare reference).
+  const fetchImpl =
+    opts.fetch ?? ((input: string, init?: RequestInit) => fetch(input, init));
+  const logger = opts.logger ?? console;
+  try {
+    const response = await fetchImpl(OPENROUTER_MODELS_URL, {
+      headers: opts.apiKey ? { Authorization: `Bearer ${opts.apiKey}` } : {},
+    });
+    if (!response.ok) {
+      throw new Error(`OpenRouter /models returned HTTP ${response.status}`);
+    }
+    const parsed = openRouterModelsSchema.safeParse(await response.json());
+    if (!parsed.success) {
+      throw new Error(`Unexpected /models payload: ${parsed.error.message}`);
+    }
+    const prices = parsePrices(parsed.data.data);
+    if (prices.size === 0) {
+      throw new Error('OpenRouter /models returned no usable pricing');
+    }
+    cache = { fetchedAt: now(), prices };
+    return prices;
+  } catch (error) {
+    logger.warn(
+      `[models] live OpenRouter pricing unavailable — serving baseline prices: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    return cache?.prices ?? new Map<string, ModelPrice>();
+  }
+}
+
+/** Test seam: clear the in-memory price cache between cases. */
+export function resetOpenRouterPriceCache(): void {
+  cache = null;
+}

package/src/core/plugin-loader.ts

@@ -0,0 +1,192 @@
+import type { OraclePlugin, PluginEnv } from '../plugin-api/oracle-plugin';
+import type { Logger } from '../plugin-api/types';
+import { NOOP_LOGGER } from './utils';
+
+/**
+ * Per-feature toggle:
+ *  - `true`   — explicit opt-in. If the plugin has an `autoDetect` and it
+ *               fails, boot fails.
+ *  - `false`  — explicit opt-out.
+ *  - `'auto'` — include only if the plugin's `autoDetect` returns true (or
+ *               the plugin has no `autoDetect`, in which case it loads).
+ */
+export type FeatureToggle = boolean | 'auto';
+
+export type ExclusionCause =
+  | 'feature_false'
+  | 'auto_detect_missing'
+  | 'cascaded';
+
+export interface ExcludedPlugin {
+  plugin: string;
+  reason: string;
+  cause: ExclusionCause;
+}
+
+export interface SoftDepGap {
+  plugin: string;
+  missing: string;
+}
+
+export interface ResolvePluginsInput {
+  features?: Partial<Record<string, FeatureToggle>>;
+  /** Plugins subject to feature toggles + `autoDetect`. */
+  bundled: OraclePlugin[];
+  /** Plugins that always load (no toggle, no auto-detect). */
+  userPlugins?: OraclePlugin[];
+  /**
+   * The Worker `env` bindings object handed to each plugin's `autoDetect`.
+   * Required on Workers — there is no `process.env` to fall back to.
+   */
+  env: PluginEnv;
+  logger?: Logger;
+}
+
+export interface ResolvePluginsResult {
+  loaded: OraclePlugin[];
+  excluded: ExcludedPlugin[];
+  softDepGaps: SoftDepGap[];
+}
+
+/**
+ * Resolve the final plugin list for boot.
+ *
+ *   1. Apply feature toggles + each plugin's `autoDetect` to the bundled list.
+ *   2. Combine with always-loaded user plugins.
+ *   3. Cascade hard-dep removals (transitive — fixed-point).
+ *   4. Topologically sort by `dependsOn`.
+ *   5. Log soft-dep gaps.
+ */
+export function resolvePlugins(
+  input: ResolvePluginsInput,
+): ResolvePluginsResult {
+  const env = input.env;
+  const logger = input.logger ?? NOOP_LOGGER;
+  const features = input.features ?? {};
+
+  const excluded: ExcludedPlugin[] = [];
+  const survivors: OraclePlugin[] = [];
+
+  for (const plugin of input.bundled) {
+    const toggle = features[plugin.name];
+
+    if (toggle === false) {
+      excluded.push({
+        plugin: plugin.name,
+        reason: 'feature flag set to false',
+        cause: 'feature_false',
+      });
+      continue;
+    }
+
+    const detectOk = plugin.autoDetect ? plugin.autoDetect(env) : true;
+    const hint = plugin.autoDetectHint ?? 'auto-detect predicate';
+
+    if (toggle === true && !detectOk) {
+      throw new Error(
+        `boot.plugin.env_missing: plugin '${plugin.name}' enabled via features but precondition failed (${hint}). ` +
+          `Set the required env or disable: features: { ${plugin.name}: false }`,
+      );
+    }
+
+    if (!detectOk) {
+      excluded.push({
+        plugin: plugin.name,
+        reason: `auto-detect precondition not met (${hint})`,
+        cause: 'auto_detect_missing',
+      });
+      continue;
+    }
+
+    survivors.push(plugin);
+  }
+
+  const allLoaded = [...survivors, ...(input.userPlugins ?? [])];
+
+  // Transitive cascade — fixed-point. A plugin cascades off if any of its
+  // hard deps is excluded for any reason (explicit false, auto-detect, or
+  // a previous cascade).
+  const kept = new Map(allLoaded.map((p) => [p.name, p]));
+  const excludedNames = new Set(excluded.map((e) => e.plugin));
+
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const plugin of [...kept.values()]) {
+      for (const dep of plugin.dependsOn ?? []) {
+        if (kept.has(dep)) continue;
+        if (!excludedNames.has(dep)) continue;
+        const reason = `cascaded off via ${dep}`;
+        excluded.push({ plugin: plugin.name, reason, cause: 'cascaded' });
+        excludedNames.add(plugin.name);
+        kept.delete(plugin.name);
+        logger.warn(
+          `[boot] plugin '${plugin.name}' ${reason} (event: boot.plugin.cascaded_off)`,
+        );
+        changed = true;
+        break;
+      }
+    }
+  }
+
+  const ordered = topoSort([...kept.values()]);
+  const finalNames = new Set(ordered.map((p) => p.name));
+
+  const softDepGaps: SoftDepGap[] = [];
+  for (const plugin of ordered) {
+    for (const soft of plugin.softDependsOn ?? []) {
+      if (finalNames.has(soft)) continue;
+      softDepGaps.push({ plugin: plugin.name, missing: soft });
+      logger.log(
+        `[boot] plugin '${plugin.name}' soft-depends on '${soft}', which is not loaded (event: boot.plugin.soft_dep_missing)`,
+      );
+    }
+  }
+
+  return { loaded: ordered, excluded, softDepGaps };
+}
+
+/**
+ * Topologically sort plugins by `dependsOn`. Throws on unmet hard deps
+ * (`boot.plugin.dep_missing`) or cycles (`boot.plugin.cycle`, with the
+ * cycle path included in the message).
+ */
+export function topoSort(plugins: OraclePlugin[]): OraclePlugin[] {
+  const byName = new Map(plugins.map((p) => [p.name, p]));
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const ordered: OraclePlugin[] = [];
+
+  const visit = (
+    name: string,
+    requiredBy: string | null,
+    path: string[],
+  ): void => {
+    if (visited.has(name)) return;
+    if (visiting.has(name)) {
+      const cycle = [...path.slice(path.indexOf(name)), name].join(' -> ');
+      throw new Error(
+        `boot.plugin.cycle: dependency cycle detected: ${cycle}. ` +
+          `Break the cycle by removing one of the dependsOn links.`,
+      );
+    }
+    const plugin = byName.get(name);
+    if (!plugin) {
+      throw new Error(
+        `boot.plugin.dep_missing: plugin '${requiredBy}' requires '${name}', which is not loaded. ` +
+          `Add '${name}' to features, or remove '${requiredBy}'.`,
+      );
+    }
+
+    visiting.add(name);
+    for (const dep of plugin.dependsOn ?? []) {
+      visit(dep, name, [...path, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+    ordered.push(plugin);
+  };
+
+  for (const p of plugins) visit(p.name, null, []);
+  return ordered;
+}

package/src/core/plugins/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Example plugins that prove the Workers plugin API end-to-end. Neither is
+ * loaded unless a host passes it to `createRuntimeCore({ plugins })`.
+ */
+export * from './weather';
+export * from './skills';

package/src/core/plugins/skills/index.ts

@@ -0,0 +1,8 @@
+export { SkillsPlugin, type SkillsPluginOptions } from './skills.plugin';
+export {
+  createDefaultSkillsUcanBuilder,
+  createSkillsTools,
+  type MergedSkill,
+  type SkillsToolsOptions,
+  type SkillsUcanBuilder,
+} from './skills-tools';