@ixo/oracle-runtime-workers 0.12.0 → 0.15.0

package/src/core/tool-access.ts

@@ -0,0 +1,189 @@
+import { toolPlaneRequirement } from '../plugin-api/tool-plane';
+import type {
+  Logger,
+  PluginContext,
+  PluginManifest,
+  PluginTool,
+} from '../plugin-api/types';
+import type { CapabilityRequirement } from './manifest';
+import type {
+  RegisteredSubAgent,
+  SubAgentRegistry,
+  ToolRegistry,
+} from './registries';
+import { computeSubAgentToolName } from './subagent-as-tool';
+import { NOOP_LOGGER } from './utils';
+
+/** `ctx.ucan.hasCapability` bound to the turn's delegation. */
+export type HasCapability = (resource: string, action: string) => boolean;
+
+/**
+ * Tool-level counterpart of the manifest's `unmetRequirements`: the
+ * capability `tool`'s plane requires that the delegation does not grant
+ * (empty for an orchestration tool, or an admin tool it reaches).
+ */
+export function unmetToolRequirements(
+  pluginName: string,
+  tool: Pick<PluginTool, 'name' | 'plane'>,
+  has: HasCapability,
+): CapabilityRequirement[] {
+  const required = toolPlaneRequirement(pluginName, tool);
+  return required && !has(required.resource, required.action) ? [required] : [];
+}
+
+/** What the turn's delegation leaves of the collected tools and sub-agents. */
+export interface TurnToolAccess<
+  T extends { pluginName: string; tool: PluginTool },
+> {
+  /** The collected plugin tools the delegation reaches, in collection order. */
+  tools: T[];
+  /**
+   * The sub-agents still exposed, each with its `tools` resolved and cut to
+   * the ones the delegation reaches and its `forwardTools` cut to match. A
+   * sub-agent that had tools and is left with none is not exposed; one
+   * declared without tools (routing only) is.
+   */
+  subAgents: RegisteredSubAgent[];
+  /**
+   * Main-agent tool names the turn withholds: inaccessible admin tools and
+   * the `call_*` tool of a sub-agent that is not exposed. Never bound; the
+   * capability gate refuses a call naming one.
+   */
+  withheldToolNames: ReadonlySet<string>;
+  /**
+   * Plugins that contributed tools or sub-agents of which none is left.
+   * Treated like a plugin whose `requires` are unmet (left out of the
+   * prompt, refused by `load_capability`, never preloaded) except that they
+   * are hidden outright: `list_capabilities` does not list them.
+   */
+  hiddenPlugins: ReadonlySet<string>;
+}
+
+/**
+ * Apply the tool planes to one turn's collection. The single rule every
+ * surface reads: binding, sub-agents, the Tier-1 prompt, the meta-tools,
+ * the capability gate and the router's candidates.
+ *
+ * A sub-agent whose `tools` factory throws is dropped and logged, as its
+ * conversion failure always was (`collectSubAgentsWithFallback`).
+ */
+export function resolveTurnToolAccess<
+  T extends { pluginName: string; tool: PluginTool },
+>(input: {
+  tools: readonly T[];
+  subAgents: readonly RegisteredSubAgent[];
+  buildCtx: PluginContext;
+  has: HasCapability;
+  logger: Logger;
+}): TurnToolAccess<T> {
+  const { buildCtx, has, logger } = input;
+  const reaches = (pluginName: string, tool: PluginTool): boolean =>
+    unmetToolRequirements(pluginName, tool, has).length === 0;
+
+  const contributing = new Set<string>();
+  const usable = new Set<string>();
+  const withheldToolNames = new Set<string>();
+
+  const tools: T[] = [];
+  for (const entry of input.tools) {
+    contributing.add(entry.pluginName);
+    if (reaches(entry.pluginName, entry.tool)) {
+      tools.push(entry);
+      usable.add(entry.pluginName);
+    } else {
+      withheldToolNames.add(entry.tool.name);
+    }
+  }
+
+  const subAgents: RegisteredSubAgent[] = [];
+  for (const { pluginName, subAgent } of input.subAgents) {
+    let declared: PluginTool[];
+    try {
+      declared = Array.isArray(subAgent.tools)
+        ? subAgent.tools
+        : subAgent.tools(buildCtx);
+    } catch (err) {
+      logger.error(
+        `[main-agent] sub-agent init failed for plugin "${pluginName}"; skipping: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      continue;
+    }
+    contributing.add(pluginName);
+    const reached = declared.filter((tool) => reaches(pluginName, tool));
+    if (declared.length > 0 && reached.length === 0) {
+      withheldToolNames.add(computeSubAgentToolName(subAgent.name));
+      continue;
+    }
+    const reachedNames = new Set(reached.map((tool) => tool.name));
+    const withheldInner = new Set(
+      declared
+        .filter((tool) => !reachedNames.has(tool.name))
+        .map((tool) => tool.name),
+    );
+    subAgents.push({
+      pluginName,
+      subAgent: {
+        ...subAgent,
+        tools: reached,
+        ...(Array.isArray(subAgent.forwardTools)
+          ? {
+              forwardTools: subAgent.forwardTools.filter(
+                (name) => !withheldInner.has(name),
+              ),
+            }
+          : {}),
+      },
+    });
+    usable.add(pluginName);
+  }
+
+  const hiddenPlugins = new Set(
+    [...contributing].filter((pluginName) => !usable.has(pluginName)),
+  );
+  return { tools, subAgents, withheldToolNames, hiddenPlugins };
+}
+
+/**
+ * `hiddenPlugins` from the boot-time contributions alone, for the
+ * capability router, which predicts before the turn's request-time tools are
+ * collected. A plugin whose request-time tools would make it usable may be
+ * left out here (the router does not offer it; `load_capability` still
+ * can); one whose request-time tools are all withheld may be offered, and
+ * the turn's build voids that preload (`createMainAgent`).
+ */
+export async function bootHiddenPlugins(input: {
+  registries: { tools: ToolRegistry; subAgents: SubAgentRegistry };
+  buildCtx: PluginContext;
+  has: HasCapability;
+}): Promise<ReadonlySet<string>> {
+  const { registries, buildCtx, has } = input;
+  return resolveTurnToolAccess({
+    tools: await registries.tools.collectBoot(buildCtx),
+    subAgents: registries.subAgents.collectBoot(buildCtx),
+    buildCtx,
+    has,
+    // A failing sub-agent is reported by the turn's build, once.
+    logger: NOOP_LOGGER,
+  }).hiddenPlugins;
+}
+
+/**
+ * The manifest as this turn may show it: `examples` naming a withheld tool
+ * removed, so neither the Tier-1 prompt nor `load_capability` teaches the
+ * model a tool it cannot see. Same reference when nothing is removed.
+ */
+export function withoutWithheldExamples(
+  manifest: PluginManifest,
+  withheldToolNames: ReadonlySet<string>,
+): PluginManifest {
+  const examples = manifest.examples;
+  if (!examples || withheldToolNames.size === 0) return manifest;
+  const kept = examples.filter(
+    (example) => !withheldToolNames.has(example.tool),
+  );
+  return kept.length === examples.length
+    ? manifest
+    : { ...manifest, examples: kept };
+}

package/src/core/tool-scheduler.ts

@@ -0,0 +1,125 @@
+/**
+ * Bounded tool concurrency for one user object, shared by every session and
+ * every turn that object runs:
+ *
+ *   - writes run one at a time (a mutation never races another mutation of
+ *     the same user's data, even from two simultaneous sessions);
+ *   - reads run up to `maxReads` at a time;
+ *   - sub-agent dispatches run up to `maxSubagents` at a time, in their own
+ *     lane so a child waiting for one of the parent's slots can never
+ *     deadlock the parent.
+ *
+ * A wait is cancelled by the turn's abort signal: the waiter leaves the
+ * queue and the signal's reason is thrown, so an aborted turn never holds a
+ * slot it will not use.
+ */
+export type ToolLane = 'read' | 'write' | 'subagent';
+
+class Lane {
+  private active = 0;
+  private readonly waiting: Array<{
+    resolve: () => void;
+    reject: (reason: unknown) => void;
+    signal?: AbortSignal;
+    onAbort?: () => void;
+  }> = [];
+
+  constructor(private readonly capacity: number) {}
+
+  acquire(signal?: AbortSignal): Promise<void> {
+    if (signal?.aborted) return Promise.reject(abortReason(signal));
+    if (this.active < this.capacity) {
+      this.active += 1;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve, reject) => {
+      const waiter: (typeof this.waiting)[number] = { resolve, reject, signal };
+      if (signal) {
+        waiter.onAbort = () => {
+          const index = this.waiting.indexOf(waiter);
+          if (index !== -1) this.waiting.splice(index, 1);
+          reject(abortReason(signal));
+        };
+        signal.addEventListener('abort', waiter.onAbort, { once: true });
+      }
+      this.waiting.push(waiter);
+    });
+  }
+
+  release(): void {
+    const next = this.waiting.shift();
+    if (!next) {
+      this.active -= 1;
+      return;
+    }
+    // The slot passes straight to the next waiter (`active` is unchanged).
+    if (next.signal && next.onAbort)
+      next.signal.removeEventListener('abort', next.onAbort);
+    next.resolve();
+  }
+
+  get inFlight(): number {
+    return this.active;
+  }
+
+  get queued(): number {
+    return this.waiting.length;
+  }
+}
+
+/** The signal's reason as an Error (an aborter may pass any value). */
+function abortReason(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  if (reason instanceof Error) return reason;
+  const error = new Error(
+    reason === undefined
+      ? 'The turn was aborted while waiting for a tool slot.'
+      : String(reason),
+  );
+  error.name = 'AbortError';
+  return error;
+}
+
+export interface ToolSchedulerOptions {
+  maxReads?: number;
+  maxSubagents?: number;
+}
+
+export class ToolScheduler {
+  private readonly lanes: Record<ToolLane, Lane>;
+
+  constructor(options: ToolSchedulerOptions = {}) {
+    this.lanes = {
+      write: new Lane(1),
+      read: new Lane(options.maxReads ?? 4),
+      subagent: new Lane(options.maxSubagents ?? 4),
+    };
+  }
+
+  async run<T>(
+    lane: ToolLane,
+    signal: AbortSignal | undefined,
+    action: () => Promise<T>,
+  ): Promise<T> {
+    const slot = this.lanes[lane];
+    await slot.acquire(signal);
+    try {
+      return await action();
+    } finally {
+      slot.release();
+    }
+  }
+
+  /** Occupancy per lane (diagnostics). */
+  snapshot(): Record<ToolLane, { inFlight: number; queued: number }> {
+    const entry = (lane: Lane) => ({
+      inFlight: lane.inFlight,
+      queued: lane.queued,
+    });
+    return {
+      read: entry(this.lanes.read),
+      write: entry(this.lanes.write),
+      subagent: entry(this.lanes.subagent),
+    };
+  }
+}

package/src/core/turn-budget.ts

@@ -0,0 +1,205 @@
+/**
+ * One turn's resource budget, shared by the main agent, every sub-agent it
+ * dispatches and the helper models (summarizer, attachment extraction) the
+ * turn's LLM adapter hands out. Three limits:
+ *
+ *   - `tokens`     — cumulative model tokens. A call reserves an estimate
+ *                    (chars/4 of what it sends plus the output reserve) before
+ *                    it starts and settles to the provider's reported usage
+ *                    when the call ends, so the counter is an estimate only
+ *                    while a call is in flight.
+ *   - `tools`      — tool attempts, counting a sub-agent dispatch and each
+ *                    retry of a read.
+ *   - `durationMs` — wall clock since the budget was created (the turn's
+ *                    deadline; the host aborts the run when it passes).
+ *
+ * Exhaustion is terminal for the turn: `HarnessLimitError` is not retryable
+ * and the work already done (checkpoints, tool results) is kept.
+ *
+ * Token counts are estimates reconciled against provider usage, never a
+ * billing figure; `TURN_RECURSION_LIMIT` stays the separate guard against a
+ * runaway graph.
+ */
+export class HarnessLimitError extends Error {
+  readonly retryable = false;
+
+  constructor(
+    readonly kind: 'budget_exhausted',
+    readonly limit: 'tokens' | 'tools' | 'time',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'HarnessLimitError';
+  }
+}
+
+const LIMITS: ReadonlySet<string> = new Set(['tokens', 'tools', 'time']);
+
+function limitOf(error: Error): HarnessLimitError['limit'] | undefined {
+  const value: unknown = Reflect.get(error, 'limit');
+  return value === 'tokens' || value === 'tools' || value === 'time'
+    ? value
+    : undefined;
+}
+
+/**
+ * The `HarnessLimitError` behind `error`, if there is one. LangChain wraps an
+ * error thrown from a middleware in a `MiddlewareError` — same name and
+ * message, the original as `cause`, once per middleware layer — so the
+ * original (with `kind` and `limit`) is found by walking the causes. A copy
+ * of the class from another bundle is recognized by name and fields.
+ */
+export function harnessLimitOf(error: unknown): HarnessLimitError | undefined {
+  let current: unknown = error;
+  for (let depth = 0; depth < 32 && current instanceof Error; depth += 1) {
+    if (current instanceof HarnessLimitError) return current;
+    const limit = limitOf(current);
+    if (current.name === 'HarnessLimitError' && limit && LIMITS.has(limit))
+      return new HarnessLimitError('budget_exhausted', limit, current.message);
+    current = current.cause;
+  }
+  return undefined;
+}
+
+/** `true` when `error` is, or wraps, a turn-budget exhaustion. */
+export function isHarnessLimitError(error: unknown): boolean {
+  return harnessLimitOf(error) !== undefined;
+}
+
+export interface TurnLimits {
+  /** Cumulative model tokens (estimated input + reserved output, settled to usage). */
+  tokens: number;
+  /** Tool attempts, sub-agent dispatches included. */
+  tools: number;
+  /** Wall-clock deadline for the turn. */
+  durationMs: number;
+}
+
+export const DEFAULT_TURN_LIMITS: TurnLimits = {
+  tokens: 500_000,
+  tools: 120,
+  durationMs: 600_000,
+};
+
+/** Parse the `TURN_*` env knobs; anything unusable keeps its default. */
+export function turnLimitsFromEnv(env: {
+  TURN_MAX_TOKENS?: number | string;
+  TURN_MAX_TOOL_CALLS?: number | string;
+  TURN_TIMEOUT_MS?: number | string;
+}): TurnLimits {
+  const positive = (raw: number | string | undefined, fallback: number) => {
+    if (raw === undefined || raw === '') return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+  };
+  return {
+    tokens: positive(env.TURN_MAX_TOKENS, DEFAULT_TURN_LIMITS.tokens),
+    tools: positive(env.TURN_MAX_TOOL_CALLS, DEFAULT_TURN_LIMITS.tools),
+    durationMs: positive(env.TURN_TIMEOUT_MS, DEFAULT_TURN_LIMITS.durationMs),
+  };
+}
+
+export interface TurnUsage {
+  /** Tokens counted so far: settled usage plus in-flight reservations. */
+  tokens: number;
+  /** Tokens the provider reported (the settled part of `tokens`). */
+  reportedTokens: number;
+  modelCalls: number;
+  toolAttempts: number;
+  elapsedMs: number;
+  limits: TurnLimits;
+}
+
+export class TurnBudget {
+  private tokens = 0;
+  private reportedTokens = 0;
+  private modelCalls = 0;
+  private tools = 0;
+  private readonly startedAt: number;
+
+  constructor(
+    readonly limits: TurnLimits = DEFAULT_TURN_LIMITS,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.startedAt = now();
+  }
+
+  /** Throws when the turn was aborted or its deadline passed. */
+  check(signal?: AbortSignal): void {
+    if (signal?.aborted) throw signal.reason ?? abortError();
+    if (this.now() - this.startedAt >= this.limits.durationMs)
+      this.fail('time', 'time');
+  }
+
+  /**
+   * Reserve a model call before it starts. Returns the reservation so the
+   * caller can settle it against the provider's usage once the call ends.
+   */
+  reserveModel(
+    estimatedInputTokens: number,
+    outputReserveTokens: number,
+    signal?: AbortSignal,
+  ): number {
+    this.check(signal);
+    // A NaN would poison the counter for the rest of the turn (every later
+    // comparison with the limit is false): an unusable number counts as 0.
+    const usable = (n: number): number =>
+      Number.isFinite(n) ? Math.max(0, n) : 0;
+    const reservation =
+      usable(estimatedInputTokens) + usable(outputReserveTokens);
+    if (this.tokens + reservation > this.limits.tokens)
+      this.fail('tokens', 'token');
+    this.tokens += reservation;
+    this.modelCalls += 1;
+    return reservation;
+  }
+
+  /** Replace a reservation with what the provider reported. */
+  settleModel(reservation: number, reportedTotalTokens: number): void {
+    if (!Number.isFinite(reportedTotalTokens) || reportedTotalTokens < 0)
+      return;
+    this.tokens += reportedTotalTokens - reservation;
+    this.reportedTokens += reportedTotalTokens;
+  }
+
+  /**
+   * Take a reservation back: the call is known to have cost nothing the turn
+   * should carry (the caller decides which failures qualify). Still counted
+   * as a model call.
+   */
+  releaseModel(reservation: number): void {
+    if (!Number.isFinite(reservation) || reservation <= 0) return;
+    this.tokens = Math.max(0, this.tokens - reservation);
+  }
+
+  reserveTool(signal?: AbortSignal): void {
+    this.check(signal);
+    if (this.tools >= this.limits.tools) this.fail('tools', 'tool-call');
+    this.tools += 1;
+  }
+
+  snapshot(): TurnUsage {
+    return {
+      tokens: this.tokens,
+      reportedTokens: this.reportedTokens,
+      modelCalls: this.modelCalls,
+      toolAttempts: this.tools,
+      elapsedMs: this.now() - this.startedAt,
+      limits: this.limits,
+    };
+  }
+
+  private fail(limit: HarnessLimitError['limit'], label: string): never {
+    throw new HarnessLimitError(
+      'budget_exhausted',
+      limit,
+      `The turn reached its ${label} limit. Completed work is preserved; no further work was started.`,
+    );
+  }
+}
+
+function abortError(): Error {
+  const error = new Error('The turn was aborted.');
+  error.name = 'AbortError';
+  return error;
+}

package/src/core/turn-time-note.ts

@@ -0,0 +1,43 @@
+/**
+ * The exact time of a turn rides on the message the user sent, not in the
+ * system prompt: the system prompt then stays identical from turn to turn
+ * (the provider's prompt cache keeps the whole history), and the model still
+ * sees when every message was sent.
+ *
+ * The note is stored as part of the message the model reads, and recorded
+ * verbatim in the message's `additional_kwargs` so everything a person reads
+ * (the transcript, a mirror) can take it off again without guessing.
+ */
+import type { MessageContent } from '@langchain/core/messages';
+
+/** `additional_kwargs` key holding the exact note a message was sent with. */
+export const TURN_TIME_NOTE_KWARG = 'turn_time_note';
+
+const SEPARATOR = '\n\n';
+
+/** The content the model reads: the note first, then what the user sent. */
+export function withTurnTimeNote(
+  content: MessageContent,
+  note: string,
+): MessageContent {
+  if (typeof content === 'string') return `${note}${SEPARATOR}${content}`;
+  return [{ type: 'text', text: note }, ...content];
+}
+
+/**
+ * The content the user sent. `note` is the value recorded under
+ * `TURN_TIME_NOTE_KWARG`; content that does not start with exactly that
+ * note (an older message, a message edited since) is returned unchanged.
+ */
+export function stripTurnTimeNote(
+  content: MessageContent,
+  note: unknown,
+): MessageContent {
+  if (typeof note !== 'string' || note.length === 0) return content;
+  if (typeof content === 'string') {
+    const lead = `${note}${SEPARATOR}`;
+    return content.startsWith(lead) ? content.slice(lead.length) : content;
+  }
+  const [first, ...rest] = content;
+  return first?.type === 'text' && first.text === note ? rest : content;
+}