@ixo/oracle-runtime-workers 0.2.0

package/src/core/template.ts

@@ -0,0 +1,245 @@
+/**
+ * A minimal Mustache renderer covering exactly what the system-prompt
+ * template uses — replaces the `mustache` package the Node runtime pulled in
+ * through `@langchain/core`'s `PromptTemplate` (`templateFormat: 'mustache'`).
+ *
+ * Supported syntax (Mustache spec semantics for each):
+ *   - `{{name}}` and `{{{name}}}` — interpolation. Both are unescaped, which
+ *     is also how LangChain configures Mustache (`mustache.escape = identity`).
+ *   - `{{#name}} … {{/name}}` — section, rendered once when the value is
+ *     truthy (a non-empty string, `true`, a non-zero number, a non-empty
+ *     array, or an object). Not iterated: the prompt has no list slots.
+ *   - `{{^name}} … {{/name}}` — inverted section.
+ *   - `{{! comment }}` — dropped.
+ *   - Standalone tag lines: a section/inverted/close/comment tag that is the
+ *     only non-whitespace on its line is removed together with that line's
+ *     newline, exactly as the spec requires. Interpolation tags are never
+ *     standalone.
+ *
+ * Unsupported on purpose: partials, dotted names, set-delimiters, and
+ * iteration. Values are looked up on the flat `values` record only.
+ */
+
+export type TemplateValues = Record<string, unknown>;
+
+type Node =
+  | { kind: 'text'; text: string }
+  | { kind: 'var'; name: string }
+  | { kind: 'section'; name: string; inverted: boolean; children: Node[] };
+
+interface Token {
+  kind: 'text' | 'var' | 'open' | 'open-inverted' | 'close' | 'comment';
+  value: string;
+  /** Standalone-line detection needs to know where the tag sat in the source. */
+  start: number;
+  end: number;
+}
+
+const TAG_RE =
+  /\{\{\{\s*([^{}]+?)\s*\}\}\}|\{\{\s*([#^/!])?\s*([^{}]*?)\s*\}\}/g;
+
+function tokenize(template: string): Token[] {
+  const tokens: Token[] = [];
+  let last = 0;
+  for (const match of template.matchAll(TAG_RE)) {
+    const start = match.index ?? 0;
+    const end = start + match[0].length;
+    if (start > last) {
+      tokens.push({
+        kind: 'text',
+        value: template.slice(last, start),
+        start: last,
+        end: start,
+      });
+    }
+    const triple = match[1];
+    if (triple !== undefined) {
+      tokens.push({ kind: 'var', value: triple, start, end });
+    } else {
+      const sigil = match[2];
+      const name = match[3] ?? '';
+      const kind: Token['kind'] =
+        sigil === '#'
+          ? 'open'
+          : sigil === '^'
+            ? 'open-inverted'
+            : sigil === '/'
+              ? 'close'
+              : sigil === '!'
+                ? 'comment'
+                : 'var';
+      tokens.push({ kind, value: name, start, end });
+    }
+    last = end;
+  }
+  if (last < template.length) {
+    tokens.push({
+      kind: 'text',
+      value: template.slice(last),
+      start: last,
+      end: template.length,
+    });
+  }
+  return stripStandaloneLines(tokens);
+}
+
+/**
+ * Remove the surrounding whitespace + newline of every tag that stands alone
+ * on its line. Operates on the adjacent text tokens so the parse tree never
+ * sees the dead whitespace.
+ */
+function stripStandaloneLines(tokens: Token[]): Token[] {
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i]!;
+    if (
+      tok.kind !== 'open' &&
+      tok.kind !== 'open-inverted' &&
+      tok.kind !== 'close' &&
+      tok.kind !== 'comment'
+    ) {
+      continue;
+    }
+    const prev = tokens[i - 1];
+    const next = tokens[i + 1];
+
+    // Text before the tag on the same line must be whitespace-only (or the
+    // tag must start the template / follow another tag's stripped line).
+    let prevOk: boolean;
+    let prevCut = 0;
+    if (prev === undefined) {
+      prevOk = true;
+    } else if (prev.kind !== 'text') {
+      prevOk = false;
+    } else {
+      const nl = prev.value.lastIndexOf('\n');
+      const tail = prev.value.slice(nl + 1);
+      prevOk = /^[ \t]*$/.test(tail);
+      prevCut = tail.length;
+    }
+    if (!prevOk) continue;
+
+    // Text after the tag up to and including the newline must be whitespace.
+    let nextOk: boolean;
+    let nextCut = 0;
+    if (next === undefined) {
+      nextOk = true;
+    } else if (next.kind !== 'text') {
+      nextOk = false;
+    } else {
+      const m = /^[ \t]*(\r?\n|$)/.exec(next.value);
+      nextOk = m !== null;
+      nextCut = m ? m[0].length : 0;
+    }
+    if (!nextOk) continue;
+
+    if (prev && prev.kind === 'text' && prevCut > 0) {
+      prev.value = prev.value.slice(0, prev.value.length - prevCut);
+    }
+    if (next && next.kind === 'text' && nextCut > 0) {
+      next.value = next.value.slice(nextCut);
+    }
+  }
+  return tokens.filter((t) => !(t.kind === 'text' && t.value.length === 0));
+}
+
+function parse(tokens: Token[]): Node[] {
+  const root: Node[] = [];
+  const stack: Array<{ name: string; children: Node[] }> = [];
+  let current = root;
+
+  for (const tok of tokens) {
+    switch (tok.kind) {
+      case 'text':
+        current.push({ kind: 'text', text: tok.value });
+        break;
+      case 'var':
+        current.push({ kind: 'var', name: tok.value });
+        break;
+      case 'comment':
+        break;
+      case 'open':
+      case 'open-inverted': {
+        const node: Node = {
+          kind: 'section',
+          name: tok.value,
+          inverted: tok.kind === 'open-inverted',
+          children: [],
+        };
+        current.push(node);
+        stack.push({ name: tok.value, children: current });
+        current = node.children;
+        break;
+      }
+      case 'close': {
+        const open = stack.pop();
+        if (!open || open.name !== tok.value) {
+          throw new Error(
+            `template: unbalanced section — closing "${tok.value}" ${
+              open ? `while "${open.name}" is open` : 'with no open section'
+            }`,
+          );
+        }
+        current = open.children;
+        break;
+      }
+    }
+  }
+  if (stack.length > 0) {
+    throw new Error(
+      `template: section "${stack[stack.length - 1]!.name}" was never closed`,
+    );
+  }
+  return root;
+}
+
+function isTruthy(value: unknown): boolean {
+  if (value === null || value === undefined || value === false) return false;
+  if (typeof value === 'string') return value.length > 0;
+  if (typeof value === 'number') return value !== 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+function stringify(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  return typeof value === 'string' ? value : String(value);
+}
+
+function render(nodes: Node[], values: TemplateValues): string {
+  let out = '';
+  for (const node of nodes) {
+    switch (node.kind) {
+      case 'text':
+        out += node.text;
+        break;
+      case 'var':
+        out += stringify(values[node.name]);
+        break;
+      case 'section': {
+        const truthy = isTruthy(values[node.name]);
+        if (truthy !== node.inverted) out += render(node.children, values);
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/** A parsed template that can be rendered repeatedly. */
+export interface CompiledTemplate {
+  render(values: TemplateValues): string;
+}
+
+/** Parse once, render many. Throws on unbalanced sections. */
+export function compileTemplate(template: string): CompiledTemplate {
+  const nodes = parse(tokenize(template));
+  return { render: (values) => render(nodes, values) };
+}
+
+/** One-shot convenience for `compileTemplate(template).render(values)`. */
+export function renderTemplate(
+  template: string,
+  values: TemplateValues,
+): string {
+  return compileTemplate(template).render(values);
+}

package/src/core/utils.ts

@@ -0,0 +1,246 @@
+import { z } from 'zod';
+import type { Logger } from '../plugin-api/types';
+
+// ── Logger defaults ─────────────────────────────────────────────────────────
+
+/** A logger that discards everything. The default wherever none is supplied. */
+export const NOOP_LOGGER: Logger = Object.freeze({
+  log: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+  debug: () => undefined,
+  verbose: () => undefined,
+});
+
+/**
+ * A `console`-backed logger whose `child()` prefixes every record with the
+ * bound context (`[plugin=weather]`). Suitable for Workers, where `console`
+ * output is what `wrangler tail` and the dashboard show.
+ */
+export function createConsoleLogger(
+  bindings: Record<string, unknown> = {},
+): Logger {
+  const prefix = Object.entries(bindings)
+    .map(([k, v]) => `${k}=${String(v)}`)
+    .join(' ');
+  const tag = prefix.length > 0 ? `[${prefix}]` : '';
+  const emit =
+    (fn: (...args: unknown[]) => void) =>
+    (message: unknown, ...optional: unknown[]): void => {
+      if (tag) fn(tag, message, ...optional);
+      else fn(message, ...optional);
+    };
+  return {
+    log: emit(console.log),
+    warn: emit(console.warn),
+    error: emit(console.error),
+    debug: emit(console.debug),
+    verbose: emit(console.debug),
+    child: (more) => createConsoleLogger({ ...bindings, ...more }),
+  };
+}
+
+// ── Tool lock ───────────────────────────────────────────────────────────────
+
+/**
+ * Locks live per isolate. Keys are `${sessionId}:${toolName}` by convention,
+ * so users sharing an isolate never contend — a lock only ever guards the
+ * same session re-entering the same stateful tool.
+ */
+const activeLocks = new Set<string>();
+
+/**
+ * Acquire an exclusive lock for the given key. Throws immediately if the key
+ * is already locked (another invocation is in flight). Returns a release
+ * function — always call it in a `finally` block.
+ *
+ * @example
+ * const release = acquireToolLock(`${ctx.session.id}:my_tool`);
+ * try {
+ *   // ... tool body
+ * } finally {
+ *   release();
+ * }
+ */
+export function acquireToolLock(key: string): () => void {
+  if (activeLocks.has(key)) {
+    throw new Error(
+      `A call to this tool is already in progress for this session. Wait for it to complete before calling again.`,
+    );
+  }
+  activeLocks.add(key);
+  return () => activeLocks.delete(key);
+}
+
+// ── Bounded maps ────────────────────────────────────────────────────────────
+
+/**
+ * Insert into a Map used as an LRU: the key moves to the back of the
+ * insertion order, and the oldest entries are evicted once `maxEntries` is
+ * exceeded. For isolate-lifetime caches keyed by unbounded request-derived
+ * ids (threads, rooms, events), the cap is what keeps them from growing for
+ * as long as the isolate lives.
+ */
+export function lruInsert<V>(
+  map: Map<string, V>,
+  key: string,
+  value: V,
+  maxEntries: number,
+): void {
+  map.delete(key);
+  map.set(key, value);
+  while (map.size > maxEntries) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
+/**
+ * Drop expired entries from a TTL map. The runtime's small lookup caches
+ * check expiry lazily on read, which leaves entries for keys that are never
+ * read again resident forever; calling this on each write keeps such maps
+ * bounded by their active key set without a background timer.
+ */
+export function sweepExpired<V extends { expiresAt: number }>(
+  map: Map<string, V>,
+  now: number = Date.now(),
+): void {
+  for (const [key, entry] of map) {
+    if (entry.expiresAt <= now) map.delete(key);
+  }
+}
+
+// ── Client-declared tool schemas ────────────────────────────────────────────
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * `#` and `#/$defs/*` / `#/definitions/*` are the only refs `z.fromJSONSchema`
+ * knows how to resolve — everything else it rejects outright.
+ */
+function isResolvableByZod(ref: string): boolean {
+  return ref === '#' || /^#\/(?:\$defs|definitions)\//.test(ref);
+}
+
+/** Decode the `~1` / `~0` escapes defined by RFC 6901. */
+function decodeSegment(segment: string): string {
+  return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+function resolvePointer(root: JsonRecord, ref: string): unknown {
+  const segments = ref.slice(1).split('/').filter(Boolean).map(decodeSegment);
+  let node: unknown = root;
+  for (const segment of segments) {
+    if (Array.isArray(node)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index)) return undefined;
+      node = node[index];
+    } else if (isRecord(node)) {
+      node = node[segment];
+    } else {
+      return undefined;
+    }
+    if (node === undefined) return undefined;
+  }
+  return node;
+}
+
+/**
+ * Ceiling on how many pointers a single schema may expand. Inlining duplicates
+ * subtrees, so a schema built from many cross-referencing pointers can grow
+ * super-linearly; past this point the remaining refs are dropped rather than
+ * expanded. Far above what a real tool schema needs.
+ */
+const MAX_EXPANSIONS = 1_000;
+
+interface InlineState {
+  /** Pointers currently being expanded — guards self-referential targets. */
+  active: Set<string>;
+  expansions: number;
+}
+
+function inline(node: unknown, root: JsonRecord, state: InlineState): unknown {
+  if (Array.isArray(node)) {
+    return node.map((item) => inline(item, root, state));
+  }
+  if (!isRecord(node)) return node;
+
+  const inlinedSiblings: JsonRecord = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (key === '$ref') continue;
+    inlinedSiblings[key] = inline(value, root, state);
+  }
+
+  const ref = node.$ref;
+  if (typeof ref !== 'string') {
+    if ('$ref' in node) inlinedSiblings.$ref = ref;
+    return inlinedSiblings;
+  }
+  // Leave refs zod handles itself, and external refs (it raises its own,
+  // clearer error for those).
+  if (isResolvableByZod(ref) || !ref.startsWith('#')) {
+    inlinedSiblings.$ref = ref;
+    return inlinedSiblings;
+  }
+  // A pointer whose target contains the pointer would expand forever. Drop the
+  // constraint — an unconstrained value still validates.
+  if (state.active.has(ref)) return inlinedSiblings;
+  if (state.expansions >= MAX_EXPANSIONS) return inlinedSiblings;
+
+  const target = resolvePointer(root, ref);
+  if (!isRecord(target)) return inlinedSiblings;
+
+  state.expansions += 1;
+  state.active.add(ref);
+  const expanded = inline(target, root, state);
+  state.active.delete(ref);
+
+  return isRecord(expanded)
+    ? { ...expanded, ...inlinedSiblings }
+    : inlinedSiblings;
+}
+
+/**
+ * Replace every local JSON-pointer `$ref` with the subschema it points at.
+ *
+ * `zod-to-json-schema` defaults to `$refStrategy: "root"`, so a subschema that
+ * appears more than once in a tool's schema is emitted once and every later
+ * occurrence becomes a pointer back into the document
+ * (`#/properties/ops/items/anyOf/2/properties/questionId`). Those pointers are
+ * valid JSON Schema but unresolvable by `z.fromJSONSchema`, so inline them
+ * before conversion.
+ */
+export function inlineLocalJsonPointerRefs(schema: JsonRecord): JsonRecord {
+  const inlined = inline(schema, schema, { active: new Set(), expansions: 0 });
+  return isRecord(inlined) ? inlined : schema;
+}
+
+/**
+ * Convert a client-declared JSON Schema (browser tool / AG-UI action) into a
+ * Zod schema.
+ *
+ * Returns `null` when the schema cannot be converted. Callers must skip that
+ * tool: these hooks run inside `collectRequest`, where one malformed client
+ * schema must not be allowed to take the request down with it.
+ */
+export function clientSchemaToZod(
+  schema: JsonRecord,
+  toolName: string,
+  logger: Logger = NOOP_LOGGER,
+): z.ZodType | null {
+  try {
+    return z.fromJSONSchema(inlineLocalJsonPointerRefs(schema));
+  } catch (error) {
+    logger.error(
+      `Skipping client-declared tool "${toolName}": its JSON Schema could not be converted to Zod — ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    return null;
+  }
+}

package/src/core/wrap-plugin-tool.ts

@@ -0,0 +1,100 @@
+import { tool } from '@langchain/core/tools';
+import type { StructuredTool } from 'langchain';
+import type {
+  PluginTool,
+  RuntimeContext,
+  SharedAccessors,
+} from '../plugin-api/types';
+import {
+  buildRuntimeContext,
+  type AmbientServices,
+  type RunConfig,
+  type RunConfigContext,
+  type RuntimeStateInput,
+} from './runtime-context';
+
+/**
+ * What `wrapPluginTool` needs at each call: the captured ambient bag, the
+ * current graph state, and the plugin title used for the description prefix.
+ */
+export interface WrapPluginToolOptions {
+  ambient: AmbientServices;
+  /** Snapshot of the graph state for the in-flight build. */
+  state: RuntimeStateInput;
+  /** Plugin manifest title used to auto-prefix the description. */
+  pluginTitle?: string;
+  /**
+   * Builds the `ctx.shared` accessor bag for each call. The main-agent build
+   * wires the shared-state registry here; ad-hoc callers may omit it.
+   */
+  sharedFactory?: (ctx: RuntimeContext) => SharedAccessors;
+  /**
+   * The request's user/session, used when the invocation config carries no
+   * `context` channel. The agent is built per request, so the build-time
+   * context IS this request's; a caller that also passes `context` to
+   * `invoke`/`stream` (the Node runtime does) overrides it.
+   */
+  fallbackContext?: RunConfigContext;
+}
+
+/**
+ * Resolve the `RunConfig` a tool call sees: LangChain's `ToolRuntime` when
+ * it carries a usable `context`, else the build-time fallback.
+ */
+export function resolveRunConfig(
+  runConfig: unknown,
+  fallbackContext: RunConfigContext | undefined,
+): RunConfig {
+  const raw = (runConfig ?? {}) as Partial<RunConfig>;
+  const ctx = raw.context;
+  const usable = Boolean(ctx && ctx.user && ctx.session);
+  const context = usable ? ctx : fallbackContext;
+  if (!context) {
+    throw new Error(
+      'wrapPluginTool: no run context — pass `context: { user, session }` in the invoke config or supply `fallbackContext`.',
+    );
+  }
+  return { ...raw, context };
+}
+
+/**
+ * Bridge a `PluginTool` (handler signature `(args, ctx: RuntimeContext)`)
+ * into LangChain's `tool()` calling convention `(args, runConfig)`.
+ *
+ * Per-call, the wrapper synthesises a fresh `RuntimeContext` via
+ * `buildRuntimeContext` so handlers see the same shape regardless of where
+ * the call originates.
+ *
+ * The agent-facing description is auto-prefixed with the plugin's
+ * `manifest.title` so the agent always knows which plugin a tool belongs to.
+ */
+export function wrapPluginTool(
+  pluginTool: PluginTool,
+  options: WrapPluginToolOptions,
+): StructuredTool {
+  const { ambient, state, pluginTitle, sharedFactory, fallbackContext } =
+    options;
+  const description = pluginTitle
+    ? `[${pluginTitle}] ${pluginTool.description}`
+    : pluginTool.description;
+
+  return tool(
+    async (args, runConfig) => {
+      // LangChain passes the `ToolRuntime` as `runConfig`; its `context`
+      // channel carries user/session when the caller supplied one at
+      // invocation, otherwise the build-time request context applies.
+      const ctx = buildRuntimeContext(
+        resolveRunConfig(runConfig, fallbackContext),
+        ambient,
+        state,
+        sharedFactory,
+      );
+      return pluginTool.handler(args, ctx);
+    },
+    {
+      name: pluginTool.name,
+      description,
+      schema: pluginTool.schema,
+    },
+  );
+}