@ixo/oracle-runtime-workers 0.15.0 → 0.17.0

package/src/core/context-budget.ts

@@ -3,8 +3,12 @@
  * (`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%),
- *                            never above what the summarizer may read;
+ *                            (default 60% of the window, whatever its size;
+ *                            never above the request cap nor above what the
+ *                            summarizer reads, which only binds below a
+ *                            ~34k window). The summary is written by the
+ *                            turn's own model (the `summarizer` role), so no
+ *                            second window bounds it;
  *   - `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;
@@ -24,7 +28,7 @@ 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). */
+  /** Fraction of the window at which the history is summarized (default 0.6). */
   summarizeFraction: number;
   /** Fraction of the window above which old tool results are pruned per request (default 0.35). */
   pruneFraction: number;
@@ -47,7 +51,7 @@ export interface ContextKnobs {
 }
 
 export const DEFAULT_CONTEXT_KNOBS: ContextKnobs = {
-  summarizeFraction: 0.5,
+  summarizeFraction: 0.6,
   pruneFraction: 0.35,
   resultCapFraction: 0.12,
   resultCapMaxChars: 200_000,
@@ -66,13 +70,11 @@ export interface ContextBudget {
   requestCapTokens: number;
   outputReserveTokens: number;
   /**
-   * The summarizer's own input limit (what it may read to write the summary):
-   * the smaller of what the main model's request cap and the summarizing
-   * model's own request cap leave, less a margin for the summary prompt.
+   * The summarizer's input limit (what it may read to write the summary):
+   * the main model's request cap less a margin for the summary prompt. The
+   * summarizer is the main model, so its request has the same room.
    */
   summaryInputTokens: number;
-  /** The summarizing model's window, when the host resolved it. */
-  summaryWindowTokens?: number;
   summarizeTriggerMessages?: number;
   keepMessages: number;
 }
@@ -170,34 +172,31 @@ function requestCapFor(
 }
 
 /**
- * The budget for a turn on `resolution.model`. `summarizer` is the window of
- * the model that writes the summary (the `routing` role), resolved the same
- * way: the history it is handed is bounded by its own window too, not only
- * by the main model's. Omitted, the main model's window alone bounds it.
+ * The budget for a turn on `resolution.model`, from that model's window
+ * alone: the summary is written by the same model (the `summarizer` role),
+ * so no other window bounds what it reads.
  */
 export function contextBudgetFor(
   resolution: ContextWindowResolution,
   knobs: ContextKnobs = DEFAULT_CONTEXT_KNOBS,
-  summarizer?: ContextWindowResolution,
 ): ContextBudget {
   const window = resolution.tokens;
   const { requestCapTokens, outputReserveTokens } = requestCapFor(
     window,
     knobs,
   );
-  const summaryRequestCap = summarizer
-    ? Math.min(
-        requestCapTokens,
-        requestCapFor(summarizer.tokens, knobs).requestCapTokens,
-      )
-    : requestCapTokens;
+  // The summarizer keeps only the newest `summaryInputTokens` of what it is
+  // asked to condense (LangChain trims with `strategy: 'last'`; the summary
+  // prompt needs its own room in the request) and drops the rest unread —
+  // the earlier summary first. Summarizing therefore starts no later than
+  // that limit, so the thread's memory is never lost unread. With the
+  // default knobs this only binds below a window of ~34.3k tokens (60% of
+  // the window exceeds 95% less the reply reserve and the prompt margin);
+  // above it the trigger is the plain fraction.
   const summaryInputTokens = Math.max(
     1_000,
-    summaryRequestCap - SUMMARY_PROMPT_MARGIN_TOKENS,
+    requestCapTokens - SUMMARY_PROMPT_MARGIN_TOKENS,
   );
-  // The summarizer keeps only the newest `summaryInputTokens` of what it is
-  // asked to condense and drops the rest unread — the earlier summary first.
-  // Summarizing starts no later than that, so nothing is lost unsummarized.
   const summarizeAtTokens = Math.min(
     Math.floor(window * knobs.summarizeFraction),
     requestCapTokens,
@@ -220,7 +219,6 @@ export function contextBudgetFor(
     requestCapTokens,
     outputReserveTokens,
     summaryInputTokens,
-    ...(summarizer ? { summaryWindowTokens: summarizer.tokens } : {}),
     ...(knobs.summarizeTriggerMessages !== undefined
       ? { summarizeTriggerMessages: knobs.summarizeTriggerMessages }
       : {}),
@@ -284,5 +282,5 @@ export function messageToolCallTokens(
 }
 
 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} summaryInput=${b.summaryInputTokens}${b.summaryWindowTokens !== undefined ? ` (summarizer window ${b.summaryWindowTokens})` : ''}`;
+  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} summaryInput=${b.summaryInputTokens}`;
 }

package/src/core/context-window.ts

@@ -8,22 +8,30 @@
  *
  * 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
+ *   1. a window **learned** from the provider (below);
+ *   2. an operator override for the exact model id (`MODEL_CONTEXT_OVERRIDES`,
+ *      optional — nothing needs one);
+ *   3. 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).
+ *   4. the built-in table (`BUILTIN_CONTEXT_WINDOWS` in `llm.ts`: the
+ *      curated catalog's `contextTokens` plus every other id the runtime
+ *      sends), looked up the same way — so an unreachable catalogue does not
+ *      shrink a known model to the default;
+ *   5. the deployment default (`MODEL_CONTEXT_TOKENS`, 100k unless set), only
+ *      for a model nothing above knows.
  *
- * 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
+ * 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 every other
+ * source 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 { BUILTIN_CONTEXT_WINDOWS } from './llm';
 import { NOOP_LOGGER } from './utils';
 
 export const DEFAULT_CONTEXT_TOKENS = 100_000;
@@ -35,6 +43,7 @@ export type ContextWindowOrigin =
   | 'override'
   | 'learned'
   | 'catalog'
+  | 'builtin'
   | 'default';
 
 export interface ContextWindowResolution {
@@ -42,7 +51,7 @@ export interface ContextWindowResolution {
   model: string;
   tokens: number;
   origin: ContextWindowOrigin;
-  /** The catalog id that answered, when the catalog did. */
+  /** The catalog (or built-in table) id that answered, when one did. */
   catalogId?: string;
 }
 
@@ -61,15 +70,20 @@ export interface ContextWindowResolverOptions {
   config: ContextWindowConfig;
   /** OpenRouter model id → context window (tokens). */
   catalog: () => Promise<ReadonlyMap<string, number>>;
+  /**
+   * Known model id → context window (tokens), consulted after the catalogue
+   * with the same candidate ids. Default {@link BUILTIN_CONTEXT_WINDOWS}.
+   */
+  builtin?: 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).
+ * — optional, 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>,
@@ -212,8 +226,14 @@ export class ContextWindowResolver {
     const base = await this.baseline(model, opts.byoProvider);
     const learned = await this.learned(model);
     if (learned !== undefined && learned < base.tokens) {
+      this.logger.debug?.(
+        `[context] ${model}: window ${learned} (learned; ${base.origin} says ${base.tokens})`,
+      );
       return { ...base, tokens: learned, origin: 'learned' };
     }
+    this.logger.debug?.(
+      `[context] ${model}: window ${base.tokens} (${base.origin}${base.catalogId ? ` ${base.catalogId}` : ''})`,
+    );
     return base;
   }
 
@@ -235,13 +255,20 @@ export class ContextWindowResolver {
         `[context] model catalog unavailable: ${error instanceof Error ? error.message : String(error)}`,
       );
     }
+    const candidates = catalogCandidates(model, byoProvider);
     if (catalog) {
-      for (const candidate of catalogCandidates(model, byoProvider)) {
+      for (const candidate of candidates) {
         const tokens = catalog.get(candidate);
         if (tokens !== undefined && isWindow(tokens))
           return { model, tokens, origin: 'catalog', catalogId: candidate };
       }
     }
+    const builtin = this.options.builtin ?? BUILTIN_CONTEXT_WINDOWS;
+    for (const candidate of candidates) {
+      const tokens = builtin.get(candidate);
+      if (tokens !== undefined && isWindow(tokens))
+        return { model, tokens, origin: 'builtin', catalogId: candidate };
+    }
     return { model, tokens: config.defaultTokens, origin: 'default' };
   }
 

package/src/core/domain-context/document.ts

@@ -0,0 +1,100 @@
+/**
+ * Reading a validated `domain.md` frontmatter: the document index entries and
+ * the brief (the bounded slice of the frontmatter the prompt carries).
+ */
+import type { DomainDocument } from '@ixo/domain.md/workers';
+import { z } from 'zod';
+
+const documentEntry = z.object({
+  id: z.string(),
+  uri: z.string().nullable(),
+  cid: z.string().nullable(),
+  required_for_tasks: z.array(z.string()).optional(),
+  freshness: z
+    .object({
+      last_verified: z.string().nullable(),
+      max_age: z.string().nullable(),
+    })
+    .optional(),
+  role: z.string(),
+  media_type: z.string(),
+  disclosure_pass: z.number(),
+  sensitivity: z.string(),
+  access_policy: z.string(),
+  agent_use: z.object({
+    read: z.boolean(),
+    cite: z.boolean(),
+    summarize: z.boolean(),
+  }),
+});
+export type DomainDocumentEntry = z.infer<typeof documentEntry>;
+
+const entriesSchema = z.object({ entries: z.array(documentEntry) });
+
+/** The document index; empty when the frontmatter carries none (or a malformed one). */
+export function entries(
+  document: DomainDocument | undefined,
+): DomainDocumentEntry[] {
+  const result = entriesSchema.safeParse(document?.frontmatter.documents);
+  return result.success ? result.data.entries : [];
+}
+
+/** `value` as a plain object, or `{}`. */
+export function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? { ...value }
+    : {};
+}
+
+/** A linked document is private unless both its access policy and its sensitivity are `public`. */
+export function isPrivateEntry(entry: DomainDocumentEntry): boolean {
+  return entry.access_policy !== 'public' || entry.sensitivity !== 'public';
+}
+
+/**
+ * The parts of the frontmatter the model needs to orient itself: purpose and
+ * boundary, constitution, sources of truth, default agent mode, controllers,
+ * baseline rights, privacy, the critical don'ts and the document index
+ * (without URIs or CIDs). Serialized once per CID by the resolver.
+ */
+export function briefBody(document: DomainDocument): Record<string, unknown> {
+  const front = document.frontmatter;
+  return {
+    domain: front.domain,
+    constitution: front.constitution,
+    source_of_truth: front.source_of_truth,
+    agent_default_mode: front.agent_default_mode,
+    controllers: record(front.controllers).summary,
+    rights: record(front.rights).agent_baseline,
+    privacy: front.privacy,
+    critical_do_not: front.critical_do_not,
+    documents: entries(document).map((entry) => ({
+      id: entry.id,
+      role: entry.role,
+      disclosure_pass: entry.disclosure_pass,
+      required_for_tasks: entry.required_for_tasks,
+      agent_use: entry.agent_use,
+      access_policy: entry.access_policy,
+      sensitivity: entry.sensitivity,
+    })),
+  };
+}
+
+/**
+ * ISO 8601 durations of days and time parts (`P180D`, `PT12H`, `P1DT2H`) in
+ * milliseconds; `undefined` for any other form (years, months and weeks are
+ * calendar-dependent and refused).
+ */
+export function durationMs(value: string): number | undefined {
+  const match = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/.exec(
+    value,
+  );
+  if (!match) return undefined;
+  const ms =
+    (Number(match[1] ?? 0) * 86_400 +
+      Number(match[2] ?? 0) * 3_600 +
+      Number(match[3] ?? 0) * 60 +
+      Number(match[4] ?? 0)) *
+    1000;
+  return ms > 0 ? ms : undefined;
+}

package/src/core/domain-context/findings.ts

@@ -0,0 +1,25 @@
+/**
+ * Finding codes are diagnostics that reach the prompt block, the
+ * `router_update` stream and `domain_context_runs`, so every list of them is
+ * bounded where it enters a snapshot: a hostile index can make the validator
+ * report one finding per bad entry, tens of thousands in all.
+ */
+
+/** Most entries one finding list holds, `findings-truncated` included. */
+export const MAX_FINDINGS = 32;
+/** Last entry of a list that was cut to {@link MAX_FINDINGS}. */
+export const FINDINGS_TRUNCATED = 'findings-truncated';
+
+/**
+ * `codes` without duplicates, in first-seen order, at most
+ * {@link MAX_FINDINGS} entries. A cut list (or one that already carried
+ * `findings-truncated`) keeps its first codes and ends with
+ * `findings-truncated`, so a bounded list can be extended and bounded again.
+ */
+export function boundFindings(codes: Iterable<string>): string[] {
+  const unique = new Set(codes);
+  const truncated = unique.delete(FINDINGS_TRUNCATED);
+  const list = [...unique];
+  if (!truncated && list.length <= MAX_FINDINGS) return list;
+  return [...list.slice(0, MAX_FINDINGS - 1), FINDINGS_TRUNCATED];
+}

package/src/core/domain-context/index.ts

@@ -0,0 +1,28 @@
+export type {
+  DocumentRequest,
+  DomainAnchor,
+  DomainCapsuleInspection,
+  DomainContextOptions,
+  DomainContextPins,
+  DomainContextProvenance,
+  DomainDocumentRead,
+  DomainSnapshot,
+  DomainTransport,
+} from './types';
+export {
+  ANCHOR_LOOKUP_TIMEOUT_MS,
+  DEFAULT_ANCHOR_TTL_MS,
+  DomainContextResolver,
+  PINNED_ANCHOR_SOURCE,
+} from './resolver';
+export { createDomainTransport, DOCUMENT_READ_TIMEOUT_MS } from './transport';
+export {
+  DEFAULT_PASS1,
+  DOCUMENT_PAGE_CHARS,
+  DOMAIN_CONTEXT_CLOSE,
+  DOMAIN_CONTEXT_OPEN,
+  DOMAIN_CONTEXT_PRECEDENCE,
+  prepareDomainContext,
+  provenance,
+  RESOLUTION_TIMEOUT_MS,
+} from './turn-context';

package/src/core/domain-context/integrity.ts

@@ -0,0 +1,60 @@
+/**
+ * Byte-level checks every domain document passes before anything reads it:
+ * the anchor's CID must name the exact bytes, and the bytes must be strict
+ * UTF-8 without a byte-order mark.
+ */
+import { CID } from 'multiformats/cid';
+import { sha256 } from 'multiformats/hashes/sha2';
+
+/** multicodec `raw`. */
+const RAW_CODEC = 0x55;
+/** multihash `sha2-256`. */
+const SHA2_256 = 0x12;
+
+/** Index (`domain.md`) and capsule manifest bound. */
+export const INDEX_MAX_BYTES = 1024 * 1024;
+/** Linked document bound. */
+export const LINKED_DOCUMENT_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Throws unless `cid` is a CIDv1 over the raw codec with a sha2-256 digest of
+ * exactly `bytes`. Any other CID shape is refused rather than interpreted.
+ */
+export async function verifyBytes(
+  bytes: Uint8Array,
+  cid: string,
+): Promise<void> {
+  let expected: CID;
+  try {
+    expected = CID.parse(cid);
+  } catch {
+    throw new Error('invalid-cid');
+  }
+  if (
+    expected.version !== 1 ||
+    expected.code !== RAW_CODEC ||
+    expected.multihash.code !== SHA2_256
+  )
+    throw new Error('unsupported-cid-codec');
+  const digest = await sha256.digest(bytes);
+  if (!CID.createV1(RAW_CODEC, digest).equals(expected))
+    throw new Error('cid-mismatch');
+}
+
+/** CIDv1 (raw, sha2-256) of `bytes`, as its default base32 string. */
+export async function cidOf(bytes: Uint8Array): Promise<string> {
+  return CID.createV1(RAW_CODEC, await sha256.digest(bytes)).toString();
+}
+
+/** Strict UTF-8 decode; a byte-order mark or any invalid sequence is refused. */
+export function decode(bytes: Uint8Array): string {
+  if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+    throw new Error('utf8-bom');
+  try {
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(
+      bytes,
+    );
+  } catch {
+    throw new Error('invalid-utf8');
+  }
+}

package/src/core/domain-context/lru.ts

@@ -0,0 +1,63 @@
+/**
+ * A small least-recently-used map bounded by entry count and by a total
+ * weight (bytes, characters). `Map` keeps insertion order, so re-inserting on
+ * every hit makes the first key the least recently used one.
+ */
+export class LruMap<K, V> {
+  private readonly entries = new Map<K, { value: V; weight: number }>();
+  private totalWeight = 0;
+
+  constructor(
+    private readonly limits: {
+      maxEntries: number;
+      maxWeight?: number;
+      weigh?: (value: V) => number;
+    },
+  ) {}
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  get weight(): number {
+    return this.totalWeight;
+  }
+
+  has(key: K): boolean {
+    return this.entries.has(key);
+  }
+
+  get(key: K): V | undefined {
+    const entry = this.entries.get(key);
+    if (!entry) return undefined;
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+
+  /** Stores `value` unless it alone exceeds the weight bound; evicts the least recently used entries to fit. */
+  set(key: K, value: V): void {
+    const weight = this.limits.weigh?.(value) ?? 0;
+    const maxWeight = this.limits.maxWeight ?? Infinity;
+    this.delete(key);
+    if (weight > maxWeight) return;
+    while (
+      this.entries.size > 0 &&
+      (this.entries.size >= this.limits.maxEntries ||
+        this.totalWeight + weight > maxWeight)
+    ) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) break;
+      this.delete(oldest.value);
+    }
+    this.entries.set(key, { value, weight });
+    this.totalWeight += weight;
+  }
+
+  delete(key: K): void {
+    const entry = this.entries.get(key);
+    if (!entry) return;
+    this.entries.delete(key);
+    this.totalWeight -= entry.weight;
+  }
+}