@ixo/oracle-runtime-workers 0.10.0 → 0.11.0

package/src/core/main-agent.ts

@@ -14,6 +14,9 @@ import type {
 import type { MainAgentArgs, MainAgentBuildResult } from './main-agent-types';
 import { renderTier1, type Tier1Entry } from './manifest';
 import { buildMetaTools } from './meta-tools';
+import { buildReadResultTool } from './read-result-tool';
+import { describeBudget } from './context-budget';
+import { createContextGuardMiddleware } from './middlewares/context-guard';
 import {
   createByoHistorySanitizerMiddleware,
   createCapabilityGateMiddleware,
@@ -52,6 +55,7 @@ import {
   type RuntimeStateInput,
 } from './runtime-context';
 import { MainAgentGraphState } from './state';
+import { toolEffectOf } from './middlewares/tool-marks';
 import { collectSubAgentsWithFallback } from './sub-agent-fallback';
 import { computeSubAgentToolName } from './subagent-as-tool';
 import { wrapPluginTool } from './wrap-plugin-tool';
@@ -119,6 +123,7 @@ export async function createMainAgent(
     checkpointer,
     abortSignal,
     byoProvider,
+    contextBudget,
     hooks,
   } = args;
 
@@ -227,12 +232,31 @@ export async function createMainAgent(
   const silentTools = selectByVisibility(allTools, manifestViz, 'silent');
 
   // ── 4. Wrap tools (meta + plugin) so handlers receive a RuntimeContext ──
-  const metaTools = buildMetaTools({
-    manifestRegistry: registries.manifests,
-    toolRegistry: registries.tools,
-  });
+  const metaTools = [
+    ...buildMetaTools({
+      manifestRegistry: registries.manifests,
+      toolRegistry: registries.tools,
+    }),
+    // Pages through tool results the result cap saved whole (result-cap.ts);
+    // its chunks stay well under the cap so a page is never capped itself.
+    ...(hooks?.readResult
+      ? [
+          buildReadResultTool({
+            read: hooks.readResult,
+            maxChars: Math.min(
+              16_000,
+              Math.max(
+                512,
+                Math.floor((contextBudget?.resultCapChars ?? 32_000) / 2),
+              ),
+            ),
+          }),
+        ]
+      : []),
+  ];
 
   const fallbackContext = runConfig.context;
+  const resultCap = hooks?.resultCap;
   const wrap = (entry: CollectedTool) =>
     wrapPluginTool(entry.tool, {
       ambient,
@@ -240,6 +264,7 @@ export async function createMainAgent(
       pluginTitle: titleByPlugin.get(entry.pluginName),
       sharedFactory,
       fallbackContext,
+      ...(resultCap ? { resultCap } : {}),
     });
 
   // ── 5. Sub-agents — bind all at compile time; gating happens at runtime ─
@@ -256,8 +281,21 @@ export async function createMainAgent(
     sharedFactory,
     fallbackContext,
     subAgents: subAgentEntries,
+    ...(hooks?.toolMiddlewares
+      ? { extraMiddleware: hooks.toolMiddlewares }
+      : {}),
+    ...(resultCap ? { resultCap } : {}),
   });
 
+  // Effect of every tool the model can call (durable runs: what may run
+  // again after a reset). Meta-tools only touch graph state; a sub-agent
+  // is opaque, hence a write.
+  const toolEffects = new Map<string, 'read' | 'write'>();
+  for (const t of metaTools) toolEffects.set(t.name, 'read');
+  for (const { tool } of allTools)
+    toolEffects.set(tool.name, toolEffectOf(tool));
+  for (const t of subAgentTools) toolEffects.set(t.name, 'write');
+
   ambient.logger.debug?.(
     `[main-agent] binding summary (all bound; gated at runtime): ` +
       `eager=${eagerTools.length} onDemand=${onDemandTools.length} silent=${silentTools.length} ` +
@@ -271,6 +309,7 @@ export async function createMainAgent(
         state: wrapState,
         sharedFactory,
         fallbackContext,
+        ...(resultCap ? { resultCap } : {}),
       }),
     ),
     ...eagerTools.map(wrap),
@@ -312,8 +351,12 @@ export async function createMainAgent(
   const resolveModel = hooks?.resolveModel ?? ambient.llm.get.bind(ambient.llm);
 
   const middleware = [
-    // Outermost: a turn that died between a tool call and its result (abort,
-    // object reset) must not poison every later model request on the thread.
+    // Outermost of all: the durable-run tool marks (write-ahead record per
+    // tool call, resume policy, continuation note) must see every call
+    // before validation and retries do.
+    ...(hooks?.toolMiddlewares ?? []),
+    // A turn that died between a tool call and its result (abort, object
+    // reset) must not poison every later model request on the thread.
     createDanglingToolCallRepairMiddleware({ logger: ambient.logger }),
     // Then, as on Node: rewrite cross-provider reasoning residue before the
     // summarizer condenses (a well-formed) history.
@@ -322,10 +365,26 @@ export async function createMainAgent(
     // Without this, thread state — reloaded, re-serialized, and re-uploaded to
     // the owner store on every turn — grows without bound.
     // The summarizer's own model call is internal: it must never stream its
-    // tokens into the user's reply (belt: no streaming here; braces: the SSE
-    // stream drops `lc_source: 'summarization'` events).
+    // tokens into the user's reply. That is guaranteed by the SSE producer,
+    // which drops every model event tagged `lc_source: 'summarization'`
+    // (the middleware tags its call). The model itself keeps whatever
+    // transport its provider needs — forcing it non-streaming broke the
+    // ChatGPT backend, which accepts streamed requests only.
     createSummarizationMiddleware({
-      model: resolveModel('routing', { disableStreaming: true }),
+      model: resolveModel('routing'),
+      logger: ambient.logger,
+      // Window-derived thresholds when the host resolved a budget: summarize
+      // at a fraction of the model's window (tokens only, unless the
+      // operator asked for a message trigger), the summarizer reading at
+      // most what fits the window.
+      ...(contextBudget
+        ? {
+            triggerTokens: contextBudget.summarizeAtTokens,
+            triggerMessages: contextBudget.summarizeTriggerMessages ?? null,
+            keepMessages: contextBudget.keepMessages,
+            summaryInputTokens: contextBudget.summaryInputTokens,
+          }
+        : {}),
     }),
     createCapabilityGateMiddleware({
       pluginByToolName,
@@ -385,7 +444,24 @@ export async function createMainAgent(
       : []),
     ...pluginMiddlewares,
     ...(hooks?.middlewares ?? []),
+    // Innermost: sees the request exactly as it goes to the provider. Prunes
+    // old tool results under pressure, refuses what cannot fit, and learns
+    // the window from a provider overflow (context-guard.ts).
+    ...(contextBudget
+      ? [
+          createContextGuardMiddleware({
+            budget: contextBudget,
+            ...(hooks?.onContextOverflow
+              ? { onOverflow: hooks.onContextOverflow }
+              : {}),
+            ...(hooks?.onContextEvent ? { onEvent: hooks.onContextEvent } : {}),
+            logger: ambient.logger,
+          }),
+        ]
+      : []),
   ];
+  if (contextBudget)
+    ambient.logger.log(`[context] ${describeBudget(contextBudget)}`);
 
   // ── 7. Prompt composition ───────────────────────────────────────────────
   const eagerEntries: Tier1Entry[] = manifestEntries.filter(
@@ -435,6 +511,7 @@ export async function createMainAgent(
     agent,
     systemPrompt,
     boundToolNames: tools.map((t) => t.name),
+    toolEffects,
     context: runConfig.context,
   };
 }

package/src/core/middlewares/context-guard.ts

@@ -0,0 +1,270 @@
+/**
+ * Keeps every model request inside the model's window.
+ *
+ * Three layers, all on the request only (graph state and the transcript are
+ * never rewritten here):
+ *
+ *   1. **Pressure pruning.** Above `pruneAtTokens` (35% of the window), tool
+ *      results outside the kept tail are demoted to one-line placeholders
+ *      (a capped result keeps its `read_result` handle) and results whose
+ *      text is identical to a later one are replaced by a back-reference.
+ *      No model call, no storage — Hermes' deterministic passes.
+ *   2. **The hard cap.** A request still above `requestCapTokens` after a
+ *      harder prune is refused with a clear error instead of being sent to
+ *      fail at the provider.
+ *   3. **Overflow recovery.** When the provider rejects the request anyway,
+ *      the limit it names is learned (the window is lowered for good), the
+ *      request is pruned hard, and it is retried once.
+ *
+ * Token counts are chars/4 estimates; the thresholds leave the slack for it.
+ */
+import {
+  AIMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
+import { convertToOpenAITool } from '@langchain/core/utils/function_calling';
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types';
+import { estimateContentTokens, type ContextBudget } from '../context-budget';
+import { isContextOverflowError } from '../context-window';
+import { NOOP_LOGGER } from '../utils';
+import { cappedMetaOf } from './result-cap';
+
+export class ContextOverflowError extends Error {
+  readonly retryable = false;
+
+  constructor(
+    message: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = 'ContextOverflowError';
+  }
+}
+
+/**
+ * What the guard did to a request, for the host's per-session counters
+ * (`GET /debug/context?session=`): the stage that pruned and how much it
+ * saved, a provider overflow that was retried, or a request it refused.
+ */
+export type ContextGuardEvent =
+  | {
+      kind: 'prune';
+      stage: 'soft' | 'hard' | 'overflow';
+      pruned: number;
+      beforeTokens: number;
+      afterTokens: number;
+    }
+  | { kind: 'overflow-retry'; learnedWindow?: number }
+  | { kind: 'refused'; tokens: number };
+
+export interface ContextGuardOptions {
+  budget: ContextBudget;
+  /**
+   * A provider rejected the request as too long: learn from it. Returns the
+   * new window (tokens) when the error named one.
+   */
+  onOverflow?: (error: unknown) => Promise<number | undefined>;
+  /** Observes every prune, overflow retry and refusal (never throws into the turn). */
+  onEvent?: (event: ContextGuardEvent) => void;
+  logger?: Logger;
+}
+
+export interface PruneOptions {
+  /** Messages at the end that are never touched. */
+  keepTail: number;
+  /** Tool results shorter than this are left alone. */
+  demoteMinChars: number;
+}
+
+export const PRUNE_SOFT: PruneOptions = { keepTail: 10, demoteMinChars: 600 };
+export const PRUNE_HARD: PruneOptions = { keepTail: 4, demoteMinChars: 200 };
+
+function textOf(content: unknown): string {
+  if (typeof content === 'string') return content;
+  try {
+    return JSON.stringify(content) ?? '';
+  } catch {
+    return '';
+  }
+}
+
+function placeholder(
+  message: ToolMessage,
+  text: string,
+  reason: 'pruned' | 'duplicate',
+): ToolMessage {
+  const name = message.name ?? 'tool';
+  const meta = cappedMetaOf(message);
+  const body =
+    reason === 'duplicate'
+      ? `[${name} result: identical to a later ${name} result, omitted]`
+      : `[${name} result (${text.length} characters) pruned from context${meta?.id ? `; the full result is saved as ${meta.id} — read_result({ id: "${meta.id}" }) reads it` : ''}]`;
+  return new ToolMessage({
+    ...(message.id ? { id: message.id } : {}),
+    tool_call_id: message.tool_call_id,
+    name,
+    status: message.status,
+    content: body,
+    additional_kwargs: { ...message.additional_kwargs, pruned: reason },
+  });
+}
+
+/**
+ * Old tool results → one-liners; duplicates → back-references. The last
+ * `keepTail` messages are returned as they are. Pure: new message objects
+ * with the same ids, the input untouched.
+ */
+export function pruneToolResults(
+  messages: BaseMessage[],
+  options: PruneOptions,
+): { messages: BaseMessage[]; pruned: number } {
+  const cutoff = Math.max(0, messages.length - options.keepTail);
+  const out = [...messages];
+  let pruned = 0;
+  // Duplicates: keep the LAST full copy anywhere; earlier identical results
+  // (outside the tail) point at it.
+  const seenLater = new Set<string>();
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const m = messages[i]!;
+    if (!ToolMessage.isInstance(m)) continue;
+    const text = textOf(m.content);
+    if (i >= cutoff) {
+      if (text.length >= 40) seenLater.add(text);
+      continue;
+    }
+    if (text.length >= 40 && seenLater.has(text)) {
+      out[i] = placeholder(m, text, 'duplicate');
+      pruned += 1;
+      continue;
+    }
+    if (text.length >= 40) seenLater.add(text);
+    if (text.length > options.demoteMinChars) {
+      out[i] = placeholder(m, text, 'pruned');
+      pruned += 1;
+    }
+  }
+  return { messages: out, pruned };
+}
+
+/** chars/4 over the request: system prompt, tool schemas, messages. */
+export function estimateRequestTokens(input: {
+  systemTokens: number;
+  schemaTokens: number;
+  messages: BaseMessage[];
+}): number {
+  let tokens = input.systemTokens + input.schemaTokens;
+  for (const m of input.messages) {
+    tokens += estimateContentTokens(m.content) + 4;
+    if (AIMessage.isInstance(m) && m.tool_calls?.length)
+      tokens += estimateContentTokens(m.tool_calls);
+  }
+  return tokens;
+}
+
+export function createContextGuardMiddleware(
+  options: ContextGuardOptions,
+): AgentMiddleware {
+  const logger = options.logger ?? NOOP_LOGGER;
+  const { budget } = options;
+  const emit = (event: ContextGuardEvent): void => {
+    try {
+      options.onEvent?.(event);
+    } catch (err) {
+      logger.warn(
+        `[context] onEvent failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+  const schemaTokensCache = new WeakMap<object, number>();
+  const schemaTokensOf = (tools: unknown[]): number => {
+    let total = 0;
+    for (const entry of tools) {
+      if (!entry || typeof entry !== 'object') continue;
+      let n = schemaTokensCache.get(entry);
+      if (n === undefined) {
+        try {
+          n = estimateContentTokens(
+            'schema' in entry ? convertToOpenAITool(entry as never) : entry,
+          );
+        } catch {
+          n = 0;
+        }
+        schemaTokensCache.set(entry, n);
+      }
+      total += n;
+    }
+    return total;
+  };
+  return createMiddleware({
+    name: 'ContextGuardMiddleware',
+    wrapModelCall: async (request, handler) => {
+      const systemTokens = estimateContentTokens(
+        request.systemMessage?.content ?? '',
+      );
+      const schemaTokens = schemaTokensOf(request.tools ?? []);
+      const size = (messages: BaseMessage[]) =>
+        estimateRequestTokens({ systemTokens, schemaTokens, messages });
+      let messages = request.messages;
+      let tokens = size(messages);
+      const shrink = (
+        opts: PruneOptions,
+        stage: 'soft' | 'hard' | 'overflow',
+        why: string,
+      ): void => {
+        const before = tokens;
+        const result = pruneToolResults(messages, opts);
+        messages = result.messages;
+        tokens = size(messages);
+        if (result.pruned > 0) {
+          logger.log(
+            `[context] ${why}: pruned ${result.pruned} tool result(s), ~${before} → ~${tokens} tokens (window ${budget.windowTokens})`,
+          );
+          emit({
+            kind: 'prune',
+            stage,
+            pruned: result.pruned,
+            beforeTokens: before,
+            afterTokens: tokens,
+          });
+        }
+      };
+      if (tokens > budget.pruneAtTokens)
+        shrink(PRUNE_SOFT, 'soft', 'over the prune threshold');
+      if (tokens > budget.requestCapTokens)
+        shrink(PRUNE_HARD, 'hard', 'over the request cap');
+      if (tokens > budget.requestCapTokens) {
+        emit({ kind: 'refused', tokens });
+        throw new ContextOverflowError(
+          `The conversation no longer fits the model's context window (about ${tokens} of ${budget.windowTokens} tokens even after trimming old tool results). Start a new session or ask for a shorter answer.`,
+        );
+      }
+      try {
+        return await handler({ ...request, messages });
+      } catch (error) {
+        if (!isContextOverflowError(error)) throw error;
+        const learned = await options
+          .onOverflow?.(error)
+          .catch(() => undefined);
+        logger.warn(
+          `[context] provider rejected the request as too long (${learned ? `window now ${learned}` : 'no limit named'}); retrying once with a hard prune`,
+        );
+        emit({
+          kind: 'overflow-retry',
+          ...(learned !== undefined ? { learnedWindow: learned } : {}),
+        });
+        shrink(PRUNE_HARD, 'overflow', 'after the provider overflow');
+        try {
+          return await handler({ ...request, messages });
+        } catch (retryError) {
+          if (!isContextOverflowError(retryError)) throw retryError;
+          throw new ContextOverflowError(
+            "The conversation no longer fits the model's context window, even after trimming. Start a new session.",
+            retryError,
+          );
+        }
+      }
+    },
+  });
+}

package/src/core/middlewares/result-cap.ts

@@ -0,0 +1,180 @@
+/**
+ * Tool results larger than the turn's cap never reach the model whole.
+ *
+ * The cap is a fraction of the model's context window (`context-budget.ts`),
+ * so it scales with the model. Above it the result is stored whole (the
+ * result store: SQLite under ~1 MB, R2 beyond) and the model receives the
+ * first 40% and last 60% of the visible budget with a footer naming the
+ * handle, so `read_result` can page through the rest when needed. Nothing
+ * is decided per tool: every large result is both truncated and preserved.
+ *
+ * Applied to the main agent and every sub-agent (via `toolMiddlewares`), so
+ * a sub-agent's own tool calls are capped too — and the sub-agent's reply,
+ * which is a tool result to the main agent, is capped in turn.
+ */
+import { ToolMessage } from '@langchain/core/messages';
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types';
+import type { StoredResultRef } from '../../do/result-store';
+import { NOOP_LOGGER } from '../utils';
+
+export interface ResultCapStore {
+  put(input: {
+    sessionId: string;
+    toolName: string;
+    content: string;
+  }): Promise<StoredResultRef | undefined>;
+}
+
+export interface ResultCapOptions {
+  /** Visible characters a result may have before it is capped. */
+  capChars: number;
+  sessionId: string;
+  store?: ResultCapStore;
+  /** Share of the visible budget given to the head (default 0.4, Hermes' split). */
+  headRatio?: number;
+  /** Tools whose results are never capped (`read_result` pages by design). */
+  exempt?: ReadonlySet<string>;
+  logger?: Logger;
+}
+
+/** The same configuration, as the tool wrapper takes it (see `wrapPluginTool`). */
+export type ResultCapConfig = ResultCapOptions;
+
+/**
+ * Cap one result's text: store it whole (when a store is bound) and return
+ * the head + tail + footer the model sees, or the text unchanged when it
+ * fits. Used at the tool boundary (`wrapPluginTool`, so the SSE frame, the
+ * model and the transcript all carry the capped text) and by the
+ * middleware below for tools that bypass the wrapper (sub-agents).
+ */
+export async function capToolResult(
+  text: string,
+  toolName: string,
+  options: ResultCapOptions,
+): Promise<{ text: string; meta?: CappedResultMeta }> {
+  if (text.length <= options.capChars) return { text };
+  if (options.exempt?.has(toolName)) return { text };
+  const logger = options.logger ?? NOOP_LOGGER;
+  let ref: StoredResultRef | undefined;
+  try {
+    ref = await options.store?.put({
+      sessionId: options.sessionId,
+      toolName,
+      content: text,
+    });
+  } catch (error) {
+    logger.warn(
+      `[result-cap] ${toolName}: could not save the full result: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const meta: CappedResultMeta = {
+    ...(ref ? { id: ref.id } : {}),
+    size: text.length,
+    shown: Math.max(200, options.capChars - 400),
+  };
+  logger.log(
+    `[result-cap] ${toolName}: ${text.length} chars > cap ${options.capChars}; ${ref ? `saved as ${ref.id.slice(0, 12)}… (${ref.tier})` : 'not saved'}`,
+  );
+  return {
+    text: truncateHeadTail(
+      text,
+      options.capChars,
+      meta,
+      options.headRatio ?? 0.4,
+    ),
+    meta,
+  };
+}
+
+/** Marker kept in `additional_kwargs` so later passes know the result was capped. */
+export interface CappedResultMeta {
+  id?: string;
+  size: number;
+  shown: number;
+}
+
+export const CAPPED_META_KEY = 'capped';
+
+export function capFooter(
+  meta: CappedResultMeta,
+  head: number,
+  tail: number,
+): string {
+  const where = meta.id
+    ? `The full result is saved as ${meta.id}: call read_result({ id: "${meta.id}", offset: 0 }) and follow \`next\` to read it in chunks.`
+    : 'The full result could not be saved.';
+  return `\n\n[Result truncated: showing the first ${head} and last ${tail} of ${meta.size} characters. ${where}]`;
+}
+
+/** Split a visible budget into head and tail lengths. */
+export function headTailSplit(
+  budget: number,
+  headRatio = 0.4,
+): { head: number; tail: number } {
+  const head = Math.max(0, Math.floor(budget * headRatio));
+  return { head, tail: Math.max(0, budget - head) };
+}
+
+export function truncateHeadTail(
+  text: string,
+  capChars: number,
+  meta: CappedResultMeta,
+  headRatio = 0.4,
+): string {
+  // Leave room for the footer inside the cap.
+  const budget = Math.max(200, capChars - 400);
+  const { head, tail } = headTailSplit(budget, headRatio);
+  return `${text.slice(0, head)}\n\n… [${text.length - head - tail} characters omitted] …\n\n${text.slice(text.length - tail)}${capFooter(meta, head, tail)}`;
+}
+
+function contentToText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  try {
+    return JSON.stringify(content) ?? '';
+  } catch {
+    return String(content);
+  }
+}
+
+export function createResultCapMiddleware(
+  options: ResultCapOptions,
+): AgentMiddleware {
+  return createMiddleware({
+    name: 'ResultCapMiddleware',
+    wrapToolCall: async (request, handler) => {
+      const output = await handler(request);
+      if (!ToolMessage.isInstance(output)) return output;
+      const toolName = output.name ?? request.toolCall.name;
+      const capped = await capToolResult(
+        contentToText(output.content),
+        toolName,
+        options,
+      );
+      if (!capped.meta) return output;
+      return new ToolMessage({
+        ...(output.id ? { id: output.id } : {}),
+        tool_call_id: output.tool_call_id,
+        name: toolName,
+        status: output.status,
+        content: capped.text,
+        additional_kwargs: {
+          ...output.additional_kwargs,
+          [CAPPED_META_KEY]: capped.meta,
+        },
+      });
+    },
+  });
+}
+
+/** The cap marker of a tool message, if it was capped. */
+export function cappedMetaOf(message: {
+  additional_kwargs?: Record<string, unknown>;
+}): CappedResultMeta | undefined {
+  const raw = message.additional_kwargs?.[CAPPED_META_KEY];
+  if (!raw || typeof raw !== 'object') return undefined;
+  const meta = raw as Partial<CappedResultMeta>;
+  return typeof meta.size === 'number'
+    ? { ...meta, size: meta.size, shown: meta.shown ?? 0 }
+    : undefined;
+}