@ixo/oracle-runtime-workers 0.10.0 → 0.11.0

package/README.md

@@ -117,5 +117,8 @@ lifetime are in [operations](docs/operations.md).
 - Open: the memory engine's recall ranking on accounts with a long history;
   the storage cost of task-holding users at scale (R2 page tier, see
   [architecture](docs/architecture.md#storage-cost-planning)).
-- Not ported on purpose: the Slack transport, the commerce lane and Matrix
-  group chats — see [node-parity](docs/node-parity.md#not-ported).
+- Not ported on purpose: the Slack transport and the commerce lane — see
+  [node-parity](docs/node-parity.md#not-ported). Matrix group chats were
+  ported in September 2026 behind `MATRIX_GROUP_ROOMS=gate` (the gate and
+  channel memory run in the gateway; by default the bot stays silent in
+  group rooms, see [operations](docs/operations.md#rooms-group-chats)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {

package/src/core/context-budget.ts

@@ -0,0 +1,201 @@
+/**
+ * Every context-related limit of a turn, derived from the model's window
+ * (`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%);
+ *   - `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;
+ *   - `resultCapChars`     — a tool result larger than this is stored whole
+ *                            and the model sees head + tail + a handle;
+ *   - `requestCapTokens`   — a request that is still larger than this after
+ *                            pruning is refused instead of sent to fail;
+ *   - `outputReserveTokens`— the room left for the reply.
+ *
+ * Token counts are chars/4 estimates (`estimateTokensApprox`), never billing.
+ */
+import type { Logger } from '../plugin-api/types';
+import type { ContextWindowResolution } from './context-window';
+import { estimateTokensApprox } from './manifest';
+import { NOOP_LOGGER } from './utils';
+
+export const CHARS_PER_TOKEN = 4;
+
+export interface ContextKnobs {
+  /** Fraction of the window at which the history is summarized (default 0.5). */
+  summarizeFraction: number;
+  /** Fraction of the window above which old tool results are pruned per request (default 0.35). */
+  pruneFraction: number;
+  /** Fraction of the window one tool result may occupy before it is capped (default 0.12). */
+  resultCapFraction: number;
+  /**
+   * Ceiling on the result cap in chars (default 200,000 ≈ 50k tokens): a
+   * million-token window does not make a half-megabyte tool result a good
+   * idea — the rest stays reachable through `read_result`.
+   */
+  resultCapMaxChars: number;
+  /** Fraction of the window a request may use, output reserve included (default 0.95). */
+  requestFraction: number;
+  /** Tokens reserved for the reply (default 8000). */
+  outputReserveTokens: number;
+  /** Optional message-count trigger for summarization (unset = tokens only). */
+  summarizeTriggerMessages?: number;
+  /** Recent messages kept verbatim by the summarizer (default 10). */
+  keepMessages: number;
+}
+
+export const DEFAULT_CONTEXT_KNOBS: ContextKnobs = {
+  summarizeFraction: 0.5,
+  pruneFraction: 0.35,
+  resultCapFraction: 0.12,
+  resultCapMaxChars: 200_000,
+  requestFraction: 0.95,
+  outputReserveTokens: 8_000,
+  keepMessages: 10,
+};
+
+export interface ContextBudget {
+  model: string;
+  windowTokens: number;
+  origin: ContextWindowResolution['origin'];
+  summarizeAtTokens: number;
+  pruneAtTokens: number;
+  resultCapChars: number;
+  requestCapTokens: number;
+  outputReserveTokens: number;
+  /** The summarizer's own input limit (what it may read to write the summary). */
+  summaryInputTokens: number;
+  summarizeTriggerMessages?: number;
+  keepMessages: number;
+}
+
+/** Parse the `CONTEXT_*` env knobs; anything unusable keeps its default (with a warning). */
+export function contextKnobs(
+  env: Record<string, unknown>,
+  logger: Logger = NOOP_LOGGER,
+): ContextKnobs {
+  const fraction = (key: string, fallback: number): number => {
+    const raw = env[key];
+    if (typeof raw !== 'string' || raw.trim() === '') return fallback;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0 && n <= 1) return n;
+    logger.warn(
+      `[context] ${key}=${raw} is not a fraction in (0, 1]; using ${fallback}`,
+    );
+    return fallback;
+  };
+  const int = (
+    key: string,
+    fallback: number | undefined,
+    min: number,
+  ): number | undefined => {
+    const raw = env[key];
+    if (typeof raw !== 'string' || raw.trim() === '') return fallback;
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= min) return n;
+    logger.warn(
+      `[context] ${key}=${raw} is not an integer ≥ ${min}; using ${fallback ?? 'unset'}`,
+    );
+    return fallback;
+  };
+  const summarizeTriggerMessages = int(
+    'CONTEXT_SUMMARIZE_MESSAGES',
+    undefined,
+    4,
+  );
+  return {
+    summarizeFraction: fraction(
+      'CONTEXT_SUMMARIZE_FRACTION',
+      DEFAULT_CONTEXT_KNOBS.summarizeFraction,
+    ),
+    pruneFraction: fraction(
+      'CONTEXT_PRUNE_FRACTION',
+      DEFAULT_CONTEXT_KNOBS.pruneFraction,
+    ),
+    resultCapFraction: fraction(
+      'CONTEXT_RESULT_CAP_FRACTION',
+      DEFAULT_CONTEXT_KNOBS.resultCapFraction,
+    ),
+    resultCapMaxChars:
+      int(
+        'CONTEXT_RESULT_CAP_MAX_CHARS',
+        DEFAULT_CONTEXT_KNOBS.resultCapMaxChars,
+        4_000,
+      ) ?? DEFAULT_CONTEXT_KNOBS.resultCapMaxChars,
+    requestFraction: fraction(
+      'CONTEXT_REQUEST_FRACTION',
+      DEFAULT_CONTEXT_KNOBS.requestFraction,
+    ),
+    outputReserveTokens:
+      int(
+        'CONTEXT_OUTPUT_RESERVE_TOKENS',
+        DEFAULT_CONTEXT_KNOBS.outputReserveTokens,
+        256,
+      ) ?? DEFAULT_CONTEXT_KNOBS.outputReserveTokens,
+    ...(summarizeTriggerMessages !== undefined
+      ? { summarizeTriggerMessages }
+      : {}),
+    keepMessages:
+      int('CONTEXT_KEEP_MESSAGES', DEFAULT_CONTEXT_KNOBS.keepMessages, 2) ??
+      DEFAULT_CONTEXT_KNOBS.keepMessages,
+  };
+}
+
+/** The budget for a turn on `resolution.model`. */
+export function contextBudgetFor(
+  resolution: ContextWindowResolution,
+  knobs: ContextKnobs = DEFAULT_CONTEXT_KNOBS,
+): ContextBudget {
+  const window = resolution.tokens;
+  // The reply reserve can never eat a small window: cap it at a quarter.
+  const outputReserveTokens = Math.min(
+    knobs.outputReserveTokens,
+    Math.floor(window / 4),
+  );
+  const requestCapTokens = Math.max(
+    1_000,
+    Math.floor(window * knobs.requestFraction) - outputReserveTokens,
+  );
+  const summarizeAtTokens = Math.min(
+    Math.floor(window * knobs.summarizeFraction),
+    requestCapTokens,
+  );
+  const pruneAtTokens = Math.min(
+    Math.floor(window * knobs.pruneFraction),
+    summarizeAtTokens,
+  );
+  return {
+    model: resolution.model,
+    windowTokens: window,
+    origin: resolution.origin,
+    summarizeAtTokens,
+    pruneAtTokens,
+    resultCapChars: Math.min(
+      Math.floor(window * knobs.resultCapFraction) * CHARS_PER_TOKEN,
+      knobs.resultCapMaxChars,
+    ),
+    requestCapTokens,
+    outputReserveTokens,
+    summaryInputTokens: Math.max(1_000, requestCapTokens - 4_000),
+    ...(knobs.summarizeTriggerMessages !== undefined
+      ? { summarizeTriggerMessages: knobs.summarizeTriggerMessages }
+      : {}),
+    keepMessages: knobs.keepMessages,
+  };
+}
+
+/** chars/4 over a message's content, whatever its shape. */
+export function estimateContentTokens(content: unknown): number {
+  if (typeof content === 'string') return estimateTokensApprox(content);
+  if (content == null) return 0;
+  try {
+    return estimateTokensApprox(JSON.stringify(content));
+  } catch {
+    return 0;
+  }
+}
+
+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}`;
+}

package/src/core/context-window.ts

@@ -0,0 +1,289 @@
+/**
+ * The context window of the model a turn runs on — resolved per model, not
+ * configured once for the deployment.
+ *
+ * Every context budget (when to summarize, how large a tool result may be
+ * before it is capped, when a request no longer fits) is a fraction of this
+ * number, so a 1M-context model is treated differently from a 32k one.
+ *
+ * Resolution order, first hit wins:
+ *
+ *   1. an operator override for the exact model id (`MODEL_CONTEXT_OVERRIDES`);
+ *   2. the OpenRouter `/models` listing (the same cached fetch that serves
+ *      the price catalog) — for OpenRouter ids directly, and for BYO
+ *      provider-native ids through the vendor prefix (`gpt-…` → `openai/gpt-…`);
+ *   3. the deployment default (`MODEL_CONTEXT_TOKENS`, 100k unless set).
+ *
+ * On top of that, a window is **learned downwards**: when a provider rejects
+ * a request as too long and names its limit, that smaller number is kept for
+ * the model (persistently, when the host supplies a store) and wins over the
+ * catalog from then on. A provider's error is the one source that is never
+ * wrong about its own limit; nothing is ever learned upwards.
+ *
+ * Modelled on Hermes Agent's `get_model_context_length` chain, trimmed to the
+ * sources this runtime has.
+ */
+import type { Logger } from '../plugin-api/types';
+import { NOOP_LOGGER } from './utils';
+
+export const DEFAULT_CONTEXT_TOKENS = 100_000;
+export const MIN_CONTEXT_TOKENS = 16_000;
+/** Above this a "window" is not a window (a parse slip); ignored. */
+export const MAX_CONTEXT_TOKENS = 20_000_000;
+
+export type ContextWindowOrigin =
+  | 'override'
+  | 'learned'
+  | 'catalog'
+  | 'default';
+
+export interface ContextWindowResolution {
+  /** The id the lookup was made for (as given). */
+  model: string;
+  tokens: number;
+  origin: ContextWindowOrigin;
+  /** The catalog id that answered, when the catalog did. */
+  catalogId?: string;
+}
+
+export interface ContextWindowConfig {
+  defaultTokens: number;
+  overrides: ReadonlyMap<string, number>;
+}
+
+/** Persisted learned limits (the host backs this with Durable Object storage). */
+export interface LearnedWindowStore {
+  get(model: string): Promise<number | undefined>;
+  set(model: string, tokens: number): Promise<void>;
+}
+
+export interface ContextWindowResolverOptions {
+  config: ContextWindowConfig;
+  /** OpenRouter model id → context window (tokens). */
+  catalog: () => Promise<ReadonlyMap<string, number>>;
+  learned?: LearnedWindowStore;
+  logger?: Logger;
+}
+
+/**
+ * `MODEL_CONTEXT_OVERRIDES="openai/gpt-5.6-luna=400000, gpt-5.6-terra=1000000"`
+ * — comma-separated `<model id>=<tokens>`; malformed entries are skipped
+ * with a warning. `MODEL_CONTEXT_TOKENS` is the default for models nothing
+ * else knows (min 16k).
+ */
+export function contextWindowConfig(
+  env: Record<string, unknown>,
+  logger: Logger = NOOP_LOGGER,
+): ContextWindowConfig {
+  const rawDefault = env.MODEL_CONTEXT_TOKENS;
+  const parsedDefault =
+    typeof rawDefault === 'string' && rawDefault.trim() !== ''
+      ? Number(rawDefault)
+      : Number.NaN;
+  const defaultTokens = isWindow(parsedDefault)
+    ? Math.floor(parsedDefault)
+    : DEFAULT_CONTEXT_TOKENS;
+  if (
+    typeof rawDefault === 'string' &&
+    rawDefault.trim() !== '' &&
+    !isWindow(parsedDefault)
+  )
+    logger.warn(
+      `[context] MODEL_CONTEXT_TOKENS=${rawDefault} is not a usable window; using ${DEFAULT_CONTEXT_TOKENS}`,
+    );
+  const overrides = new Map<string, number>();
+  const rawOverrides = env.MODEL_CONTEXT_OVERRIDES;
+  if (typeof rawOverrides === 'string' && rawOverrides.trim() !== '') {
+    for (const entry of rawOverrides.split(',')) {
+      const trimmed = entry.trim();
+      if (!trimmed) continue;
+      const eq = trimmed.lastIndexOf('=');
+      const model = eq > 0 ? trimmed.slice(0, eq).trim() : '';
+      const tokens = eq > 0 ? Number(trimmed.slice(eq + 1).trim()) : Number.NaN;
+      if (!model || !isWindow(tokens)) {
+        logger.warn(
+          `[context] MODEL_CONTEXT_OVERRIDES entry ignored: "${trimmed}"`,
+        );
+        continue;
+      }
+      overrides.set(model, Math.floor(tokens));
+    }
+  }
+  return { defaultTokens, overrides };
+}
+
+function isWindow(n: number): boolean {
+  return (
+    Number.isFinite(n) && n >= MIN_CONTEXT_TOKENS && n <= MAX_CONTEXT_TOKENS
+  );
+}
+
+/**
+ * OpenRouter routing variants (`:nitro`, `:floor`, `:online`, `:free`, …) are
+ * request-time modifiers, not catalog entries: look the base id up.
+ */
+export function stripRoutingVariant(model: string): string {
+  const slash = model.indexOf('/');
+  const colon = model.lastIndexOf(':');
+  return colon > slash ? model.slice(0, colon) : model;
+}
+
+/**
+ * Candidate catalog ids for a model id, in order. A provider-native BYO id
+ * (`gpt-5.6-luna`, `claude-sonnet-5`, `gemini-3.6-flash`, `deepseek-v4-pro`)
+ * is looked up under the vendor prefix OpenRouter lists it with.
+ */
+export function catalogCandidates(
+  model: string,
+  byoProvider?: string,
+): string[] {
+  const base = stripRoutingVariant(model.replace(/^byo:/, ''));
+  if (base.includes('/')) return [base];
+  const vendors: Record<string, string> = {
+    chatgpt: 'openai',
+    openai: 'openai',
+    anthropic: 'anthropic',
+    gemini: 'google',
+    deepseek: 'deepseek',
+  };
+  const byName =
+    base.startsWith('gpt-') || /^o\d/.test(base)
+      ? 'openai'
+      : base.startsWith('claude-')
+        ? 'anthropic'
+        : base.startsWith('gemini-')
+          ? 'google'
+          : base.startsWith('deepseek-')
+            ? 'deepseek'
+            : undefined;
+  const prefixes = new Set<string>();
+  const byProvider = byoProvider ? vendors[byoProvider] : undefined;
+  if (byProvider) prefixes.add(byProvider);
+  if (byName) prefixes.add(byName);
+  return [...prefixes].map((p) => `${p}/${base}`);
+}
+
+const LIMIT_PATTERNS: RegExp[] = [
+  // OpenAI / OpenRouter / most OpenAI-compatible gateways
+  /maximum context length is (\d[\d,]*) tokens/i,
+  /context length of only (\d[\d,]*) tokens/i,
+  /context window of (\d[\d,]*) tokens/i,
+  // Anthropic: "prompt is too long: 213000 tokens > 200000 maximum"
+  /tokens\s*>\s*(\d[\d,]*)\s*maximum/i,
+  // Gemini: "input token count (1200000) exceeds the maximum number of tokens allowed (1048576)"
+  /maximum number of tokens allowed \((\d[\d,]*)\)/i,
+  // Generic "limit: 128000 tokens" / "max_tokens: 128000"
+  /(?:token limit|limit)(?: of| is|:)?\s*(\d[\d,]*)\s*tokens/i,
+];
+
+/** The limit a provider's "too long" error names, in tokens, or `undefined`. */
+export function parseContextLimit(message: string): number | undefined {
+  for (const pattern of LIMIT_PATTERNS) {
+    const match = pattern.exec(message);
+    if (!match?.[1]) continue;
+    const n = Number(match[1].replace(/,/g, ''));
+    if (isWindow(n)) return n;
+  }
+  return undefined;
+}
+
+/** A provider rejected the request because the prompt no longer fits. */
+export function isContextOverflowError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  return /context_length_exceeded|maximum context length|context window|prompt is too long|input tokens exceed|too many tokens|exceeds the maximum number of tokens|request too large for|reduce the length of the messages/i.test(
+    message,
+  );
+}
+
+export class ContextWindowResolver {
+  private readonly logger: Logger;
+
+  /** Learned limits seen this boot (so a persisted read happens once per model). */
+  private readonly learnedCache = new Map<string, number | undefined>();
+
+  constructor(private readonly options: ContextWindowResolverOptions) {
+    this.logger = options.logger ?? NOOP_LOGGER;
+  }
+
+  async resolve(
+    model: string,
+    opts: { byoProvider?: string } = {},
+  ): Promise<ContextWindowResolution> {
+    const base = await this.baseline(model, opts.byoProvider);
+    const learned = await this.learned(model);
+    if (learned !== undefined && learned < base.tokens) {
+      return { ...base, tokens: learned, origin: 'learned' };
+    }
+    return base;
+  }
+
+  private async baseline(
+    model: string,
+    byoProvider?: string,
+  ): Promise<ContextWindowResolution> {
+    const { config } = this.options;
+    const stripped = stripRoutingVariant(model.replace(/^byo:/, ''));
+    const override =
+      config.overrides.get(model) ?? config.overrides.get(stripped);
+    if (override !== undefined)
+      return { model, tokens: override, origin: 'override' };
+    let catalog: ReadonlyMap<string, number> | undefined;
+    try {
+      catalog = await this.options.catalog();
+    } catch (error) {
+      this.logger.warn(
+        `[context] model catalog unavailable: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    if (catalog) {
+      for (const candidate of catalogCandidates(model, byoProvider)) {
+        const tokens = catalog.get(candidate);
+        if (tokens !== undefined && isWindow(tokens))
+          return { model, tokens, origin: 'catalog', catalogId: candidate };
+      }
+    }
+    return { model, tokens: config.defaultTokens, origin: 'default' };
+  }
+
+  private async learned(model: string): Promise<number | undefined> {
+    if (this.learnedCache.has(model)) return this.learnedCache.get(model);
+    let value: number | undefined;
+    try {
+      value = await this.options.learned?.get(model);
+    } catch {
+      value = undefined;
+    }
+    this.learnedCache.set(model, value);
+    return value;
+  }
+
+  /**
+   * A provider said the prompt does not fit: keep the limit it named when it
+   * is smaller than what we believed. Returns the new window, or `undefined`
+   * when the message names nothing usable (the caller then shrinks blind).
+   */
+  async learnFromError(
+    model: string,
+    error: unknown,
+    opts: { byoProvider?: string } = {},
+  ): Promise<number | undefined> {
+    const message =
+      error instanceof Error ? error.message : String(error ?? '');
+    const limit = parseContextLimit(message);
+    if (limit === undefined) return undefined;
+    const current = await this.resolve(model, opts);
+    if (limit >= current.tokens) return undefined;
+    this.learnedCache.set(model, limit);
+    try {
+      await this.options.learned?.set(model, limit);
+    } catch (storeError) {
+      this.logger.warn(
+        `[context] could not persist the learned window for ${model}: ${storeError instanceof Error ? storeError.message : String(storeError)}`,
+      );
+    }
+    this.logger.warn(
+      `[context] ${model}: window lowered ${current.tokens} → ${limit} (from the provider's error)`,
+    );
+    return limit;
+  }
+}

package/src/core/env.ts

@@ -115,6 +115,35 @@ export const baseEnvSchema = z.object({
     .min(1)
     .default(TURN_RECURSION_LIMIT_DEFAULT),
 
+  // --- durable runs (docs/plans/durable-runs.md) ---------------------------
+  // Parsed by `runDurabilityConfig` (src/do/run-store.ts) with defaults:
+  // keep-alive 20 s, segment pack every 2 s / 16 KiB, 4 recovery attempts at
+  // 5/15/30/60 s, `interrupt` as the multitask rule.
+  RUN_KEEPALIVE_MS: z.string().optional(),
+  RUN_SEGMENT_FLUSH_MS: z.string().optional(),
+  RUN_SEGMENT_BYTES: z.string().optional(),
+  RUN_RECOVERY_ATTEMPTS: z.string().optional(),
+  RUN_RECOVERY_DELAYS_MS: z.string().optional(),
+  TURN_MULTITASK_DEFAULT: z.enum(['interrupt', 'enqueue']).optional(),
+
+  // --- context budgets (docs/plans/context-budgets.md) ---------------------
+  // Parsed by `contextWindowConfig` / `contextKnobs` / `resultStoreKnobs`.
+  // The model's context window is resolved per model (override → OpenRouter
+  // catalog → MODEL_CONTEXT_TOKENS default, lowered by provider errors); the
+  // fractions derive every limit from it.
+  MODEL_CONTEXT_TOKENS: z.string().optional(),
+  MODEL_CONTEXT_OVERRIDES: z.string().optional(),
+  CONTEXT_SUMMARIZE_FRACTION: z.string().optional(),
+  CONTEXT_PRUNE_FRACTION: z.string().optional(),
+  CONTEXT_RESULT_CAP_FRACTION: z.string().optional(),
+  CONTEXT_RESULT_CAP_MAX_CHARS: z.string().optional(),
+  CONTEXT_REQUEST_FRACTION: z.string().optional(),
+  CONTEXT_OUTPUT_RESERVE_TOKENS: z.string().optional(),
+  CONTEXT_SUMMARIZE_MESSAGES: z.string().optional(),
+  CONTEXT_KEEP_MESSAGES: z.string().optional(),
+  TOOL_RESULT_TTL_HOURS: z.string().optional(),
+  TOOL_RESULT_R2_MIN_BYTES: z.string().optional(),
+
   // --- misc ---------------------------------------------------------------
   LOG_LEVEL: z.string().default('info'),
   CORS_ORIGIN: z.string().default('*'),

package/src/core/main-agent-types.ts

@@ -1,3 +1,7 @@
+import type { ContextBudget } from './context-budget';
+import type { ContextGuardEvent } from './middlewares/context-guard';
+import type { ResultCapConfig } from './middlewares/result-cap';
+import type { ReadResultOutcome } from '../do/result-store';
 import type { AgentMiddleware } from 'langchain';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { BaseCheckpointSaver } from '@langchain/langgraph';
@@ -75,6 +79,37 @@ export interface MainAgentHooks {
    * producer the core cannot construct).
    */
   middlewares?: AgentMiddleware[];
+  /**
+   * Middlewares applied to the main agent AND to every sub-agent's inner
+   * graph (a sub-agent's own tool calls go through them too): the
+   * write-ahead tool marks of durable runs and the result cap live here.
+   */
+  toolMiddlewares?: AgentMiddleware[];
+  /**
+   * The turn's result cap (result-cap.ts), applied inside every wrapped
+   * tool — plugin, meta and sub-agent inner tools — so a large result is
+   * truncated and saved before it becomes a ToolMessage or an SSE frame.
+   */
+  resultCap?: ResultCapConfig;
+  /**
+   * The provider rejected a request as too long (context-guard.ts): learn
+   * the limit it named. Resolves to the new window when there is one.
+   */
+  onContextOverflow?: (error: unknown) => Promise<number | undefined>;
+  /**
+   * What the context guard did to a request (a prune, an overflow retry, a
+   * refusal): the host keeps per-session counters for diagnostics.
+   */
+  onContextEvent?: (event: ContextGuardEvent) => void;
+  /**
+   * Pages through a tool result the result cap saved whole; when present
+   * the model gets the `read_result` tool.
+   */
+  readResult?: (
+    id: string,
+    offset: number,
+    length: number,
+  ) => Promise<ReadResultOutcome>;
 }
 
 export interface MainAgentArgs {
@@ -100,6 +135,12 @@ export interface MainAgentArgs {
   abortSignal?: AbortSignal;
   /** Provider of a BYO turn (`runtime.context.byo`); absent on platform turns. */
   byoProvider?: string;
+  /**
+   * The turn's context budget (context-budget.ts): drives when the history
+   * is summarized, how large a request may be, and the `read_result` chunk
+   * size. Omitted → the legacy fixed thresholds (tests, stateless builds).
+   */
+  contextBudget?: ContextBudget;
   hooks?: MainAgentHooks;
 }
 
@@ -114,6 +155,11 @@ export interface MainAgentBuildResult {
   systemPrompt: string;
   /** Names of every tool bound to the agent, in binding order. */
   boundToolNames: string[];
+  /**
+   * The effect of every bound tool (`read` may run again on a resumed
+   * turn, `write` never does). Declared by the plugin, else by name.
+   */
+  toolEffects: Map<string, 'read' | 'write'>;
   /**
    * The request's `{ user, session }` channel. Tools already fall back to it,
    * but pass it as `context` in the `invoke` / `stream` config so LangChain