@ixo/oracle-runtime-workers 0.15.0 → 0.17.0

package/src/do/user-oracle-do.ts

@@ -4,6 +4,7 @@ import {
   ChannelError,
   channelRequestHash,
   channelOrigin,
+  delegationRequiredError,
   requireChannelDelegation,
   type ChannelTurnInput,
   type ChannelTurnOutcome,
@@ -68,10 +69,10 @@ import {
   langsmithEnvFromWorkerEnv,
   llmEnvFromWorkerEnv,
   resolveLangsmithTracing,
+  streamLivenessFromEnv,
   type LangsmithTracingDecision,
   type OpenRouterLlmAdapter,
   DEFAULT_MODEL_ID,
-  OPENROUTER_MODEL_MAP,
 } from '../core/llm';
 import { renderTurnTimeNote } from '../core/prompt-composer';
 import { TURN_TIME_NOTE_KWARG, withTurnTimeNote } from '../core/turn-time-note';
@@ -96,7 +97,7 @@ import type { BaseChatModel } from '@langchain/core/language_models/chat_models'
 import type { AmbientServices, LlmAdapter } from '../core/runtime-context';
 import { chatGptBackendFromEnv } from '../llm/byo-client';
 import { createByoLlmAdapter } from '../llm/byo-adapter';
-import { byoModelForRole, isByoModelId } from '../llm/byo-catalog';
+import { isByoModelId } from '../llm/byo-catalog';
 import { handleByoRequest } from '../llm/byo-routes';
 import {
   WorkersByoService,
@@ -191,6 +192,7 @@ import {
   type TurnIdentity,
   type TurnRequest,
   type TurnResult,
+  type DomainContextRouterUpdate,
   type MemorySchemaDebug,
   TURN_INTERRUPTED_MARKER,
   type JsonString,
@@ -274,6 +276,14 @@ import {
 } from '../core/middlewares/context-guard';
 import { fetchOpenRouterContextLengths } from '../core/openrouter-pricing';
 import { ResultStore, resultStoreKnobs } from './result-store';
+import {
+  DomainContextResolver,
+  type DomainContextOptions,
+  type DomainContextPins,
+  type DomainContextProvenance,
+} from '../core/domain-context';
+import { DomainContextStore } from './domain-context-store';
+import { EVENT_NAMES } from '../core/runtime-context';
 import { artifactStorageConfig } from '../artifacts/config';
 import {
   ArtifactStore,
@@ -311,7 +321,11 @@ import type {
   FeedbackSettlement,
   FeedbackTarget,
 } from '../feedback/contract';
-import { resolveTurnDelegation, WorkersUcanService } from './ucan-service';
+import {
+  readDelegation,
+  resolveTurnDelegation,
+  WorkersUcanService,
+} from './ucan-service';
 import type { UcanDelegation } from '../plugin-api/types';
 
 /** What one attempt's agent build reads from the request body. */
@@ -328,6 +342,8 @@ interface TurnBuildRun {
   resumed: boolean;
   /** The reply text the user already received (resumed attempts). */
   continuation: string | null;
+  /** Domain anchors the run started with (resumed attempts keep them). */
+  domainPins?: DomainContextPins;
 }
 
 /**
@@ -531,6 +547,11 @@ export interface OracleWorkerHooks {
 export interface UserOracleDOOptions {
   core: (env: OracleWorkerEnv) => RuntimeCore;
   hooks?: OracleWorkerHooks;
+  /**
+   * Observe-only domain context (docs/configuration.md). Absent or `off`:
+   * no lookups, no prompt block, no tools.
+   */
+  domainContext?: DomainContextOptions;
 }
 
 interface StoredDelegation {
@@ -540,6 +561,17 @@ interface StoredDelegation {
   at: number;
 }
 
+/** The user's delegation as the object holds it in memory. */
+interface CachedDelegation {
+  raw: string;
+  /**
+   * Unix seconds: the delegation's effective expiry. Taken from where the
+   * delegation arrived (the shell's validation, the deposit record) or read
+   * off the token itself; absent only when the token cannot be parsed.
+   */
+  expiration?: number;
+}
+
 interface FlushResult {
   uploaded: boolean;
   /** Raw file size (skips) or bytes sent upstream (uploads). */
@@ -603,7 +635,11 @@ function lastAiText(messages: BaseMessage[]): string {
 }
 
 /** Id of the final assistant message (what `POST /messages` reports as `message.id`). */
-/** `turn_runs.usage` for `/debug/runs`; a row written before the column existed, or an unreadable one, is null. */
+/**
+ * `turn_runs.usage` for `/debug/runs`; a row written before the column
+ * existed, or an unreadable one, is null. A `limits.tokens` a row from an
+ * older runtime still carries is ignored: tokens are no longer limited.
+ */
 function parseUsage(raw: string | null): TurnUsage | null {
   if (!raw) return null;
   try {
@@ -626,7 +662,6 @@ function parseUsage(raw: string | null): TurnUsage | null {
       toolAttempts: num('toolAttempts'),
       elapsedMs: num('elapsedMs'),
       limits: {
-        tokens: limit('tokens'),
         tools: limit('tools'),
         durationMs: limit('durationMs'),
       },
@@ -637,7 +672,6 @@ function parseUsage(raw: string | null): TurnUsage | null {
       usage.modelCalls === undefined ||
       usage.toolAttempts === undefined ||
       usage.elapsedMs === undefined ||
-      usage.limits.tokens === undefined ||
       usage.limits.tools === undefined ||
       usage.limits.durationMs === undefined
     )
@@ -649,7 +683,6 @@ function parseUsage(raw: string | null): TurnUsage | null {
       toolAttempts: usage.toolAttempts,
       elapsedMs: usage.elapsedMs,
       limits: {
-        tokens: usage.limits.tokens,
         tools: usage.limits.tools,
         durationMs: usage.limits.durationMs,
       },
@@ -725,6 +758,13 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
      * bounded lanes. Lives as long as the object.
      */
     private readonly toolScheduler = new ToolScheduler();
+    /**
+     * Domain-context anchors and documents, cached for every session of this
+     * object; `refresh_domain_context` invalidates entries here.
+     */
+    private readonly domainResolver = new DomainContextResolver();
+    /** Per-turn domain-context provenance (`domain_context_runs`). */
+    private domainContextStore: DomainContextStore | null = null;
     private runs: RunCoordinator | null = null;
     private readonly runConfig: RunDurabilityConfig = runDurabilityConfig(
       this.env,
@@ -761,7 +801,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
      * events of one request (a soft then a hard prune) never race.
      */
     private contextStatsWrites: Promise<void> = Promise.resolve();
-    private readonly delegations = new Map<string, { raw: string }>();
+    private readonly delegations = new Map<string, CachedDelegation>();
     /** Epoch-ms until which a room-state delegation lookup is not retried. */
     private delegationMissUntil = 0;
     private dirty = false;
@@ -977,9 +1017,18 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           this.delegations.get(identity.userDid)?.raw ??
           (await this.ctx.storage.get<StoredDelegation>(META_DELEGATION))?.raw;
         delegationReplaced = known !== identity.ucanDelegation;
-        this.delegations.set(identity.userDid, {
-          raw: identity.ucanDelegation,
-        });
+        const cached = this.delegations.get(identity.userDid);
+        if (
+          cached?.raw !== identity.ucanDelegation ||
+          typeof cached.expiration !== 'number'
+        )
+          this.delegations.set(
+            identity.userDid,
+            await this.delegationRecord(
+              identity.ucanDelegation,
+              identity.ucanDelegationExpiration,
+            ),
+          );
         // Remember a new one for turns that arrive without the header.
         if (delegationReplaced)
           await this.ctx.storage.put(META_DELEGATION, {
@@ -1125,7 +1174,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const cached =
         await this.ctx.storage.get<StoredDelegation>(META_DELEGATION);
       if (live(cached)) {
-        this.delegations.set(userDid, { raw: cached.raw });
+        this.delegations.set(
+          userDid,
+          await this.delegationRecord(cached.raw, cached.expiration),
+        );
         return;
       }
       if (Date.now() < this.delegationMissUntil) return;
@@ -1156,7 +1208,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             }
           : null;
         if (live(deposited)) {
-          this.delegations.set(userDid, { raw: deposited.raw });
+          this.delegations.set(
+            userDid,
+            await this.delegationRecord(deposited.raw, deposited.expiration),
+          );
           await this.ctx.storage.put(META_DELEGATION, deposited);
           console.log(
             `[user-do] delegation for ${userDid} loaded from the deposited room state (header-less turn)`,
@@ -1171,6 +1226,31 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.delegationMissUntil = Date.now() + DELEGATION_MISS_TTL_MS;
     }
 
+    /**
+     * The in-memory record of a delegation: the expiry where it arrived
+     * stated one (the shell validated the token and read it off the chain),
+     * else the token's own effective expiry along its proof chain. A token
+     * that cannot be parsed keeps no expiry; channel turns refuse it.
+     */
+    private async delegationRecord(
+      raw: string,
+      expiration: number | undefined,
+    ): Promise<CachedDelegation> {
+      if (typeof expiration === 'number' && Number.isFinite(expiration))
+        return { raw, expiration };
+      try {
+        const grant = await readDelegation(raw);
+        return typeof grant.expiration === 'number'
+          ? { raw, expiration: grant.expiration }
+          : { raw };
+      } catch (err) {
+        console.warn(
+          `[user-do] could not read the expiry of a delegation: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return { raw };
+      }
+    }
+
     private async boot(userDid: string): Promise<void> {
       const stored = await this.ctx.storage.get<string>(META_USER_DID);
       if (stored && stored !== userDid)
@@ -1585,6 +1665,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       });
       await this.resultStore.setup();
       this.attachmentTextCache = new AttachmentTextCacheStore(liveDb, console);
+      // Constructing it touches no SQL. Only an observe turn records (and so
+      // creates `domain_context_runs`); a session delete never creates it but
+      // still removes rows an earlier observe deployment left behind.
+      this.domainContextStore = new DomainContextStore(liveDb, console);
       // The store exists whenever the bucket is bound, so artefacts made
       // earlier stay readable, revocable and deleted with their session after
       // the public origin is removed; only new ones need it.
@@ -1616,7 +1700,12 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.channelTurns = new ChannelTurns(liveDb, {
         createSession: async (identity, markerTxnId) => {
           const room = await this.gateway.resolveUserRoom(identity.userDid);
-          if (!room) throw new ChannelError(409, 'Companion room is not ready');
+          if (!room)
+            throw new ChannelError(
+              428,
+              'Companion room is not ready',
+              'room_not_ready',
+            );
           return (
             await this.createSession(identity, {
               roomId: room.roomId,
@@ -1633,7 +1722,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             !room ||
             session.roomId !== room.roomId
           )
-            throw new ChannelError(404, 'Companion session not found');
+            throw new ChannelError(
+              404,
+              'Companion session not found',
+              'session_not_found',
+            );
           const encryption = await this.gateway.getRoomStateEvent(
             room.roomId,
             'm.room.encryption',
@@ -1645,11 +1738,17 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             !('algorithm' in parsed) ||
             parsed.algorithm !== 'm.megolm.v1.aes-sha2'
           )
-            throw new ChannelError(409, 'Companion room must be encrypted');
+            throw new ChannelError(
+              409,
+              'Companion room must be encrypted',
+              'room_not_encrypted',
+            );
         },
+        // Checked again as the run starts: admission may have waited.
         requireDelegation: async (identity) =>
           requireChannelDelegation(
-            !!this.delegations.get(identity.userDid)?.raw,
+            this.delegations.get(identity.userDid),
+            Math.floor(Date.now() / 1000),
           ),
         getRun: (runId) => this.runStore!.get(runId),
         getPlan: (runId) => this.runStore!.getPlan(runId),
@@ -1823,6 +1922,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.resultStore = null;
       this.artifacts = null;
       this.attachmentTextCache = null;
+      this.domainContextStore = null;
       // Its store is bound to the database just dropped: a caller that sees
       // no scheduler boots again instead of reading a closed connection.
       this.taskScheduler = null;
@@ -2558,16 +2658,52 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           throw new ChannelError(
             403,
             'Channel grants cannot become tool authority',
+            'channel_grant_not_tool_authority',
           );
         // The shell (the only caller) checked the binding just before.
-        await this.ready(identity);
+        // The delegation is checked BEFORE the object boots: a cold boot
+        // loads the owner copy under it, and a user without a usable one
+        // must get `delegation_required`, not a boot failure. Hydration
+        // reads the cached copy, then the deposited room state (throttled
+        // after a miss); an in-memory one that no longer passes is
+        // re-read too, in case a newer deposit did not reach this object.
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        try {
+          requireChannelDelegation(
+            this.delegations.get(identity.userDid),
+            nowSeconds,
+          );
+        } catch {
+          await this.hydrateDelegation(identity.userDid);
+          requireChannelDelegation(
+            this.delegations.get(identity.userDid),
+            nowSeconds,
+          );
+        }
+        try {
+          await this.ready(identity);
+        } catch (error) {
+          // A delegation that lacks the file-storage grant over
+          // `/.oracles` cannot load the owner copy: the user must
+          // authorize again, exactly as without a delegation. (Boot throws
+          // the failure as its RPC envelope, so it is parsed, not matched
+          // by class.)
+          if (parseOwnerCopyFailure(error)?.code === 'NO_VFS_DELEGATION')
+            throw delegationRequiredError();
+          throw error;
+        }
         return {
           ok: true,
           result: await this.channelTurns!.submit(identity, input, requestHash),
         };
       } catch (error) {
         if (error instanceof ChannelError)
-          return { ok: false, status: error.status, message: error.message };
+          return {
+            ok: false,
+            status: error.status,
+            code: error.code,
+            message: error.message,
+          };
         throw error;
       }
     }
@@ -2653,6 +2789,13 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
               `[user-do] could not delete the artefacts of ${sessionId}; their links expire on schedule: ${err instanceof Error ? err.message : String(err)}`,
             );
           });
+        await this.domainContextStore
+          ?.deleteForSession(sessionId)
+          .catch((err: unknown) => {
+            console.warn(
+              `[domain-context] could not delete the provenance of ${sessionId}: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          });
         await this.ctx.storage.delete(contextStatsKey(sessionId));
         await this.feedbackMarkers!.forgetSession(sessionId);
         this.markDirty();
@@ -2891,7 +3034,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       raw: string,
       expiration?: number,
     ): Promise<void> {
-      this.delegations.set(userDid, { raw });
+      this.delegations.set(
+        userDid,
+        await this.delegationRecord(raw, expiration),
+      );
       this.delegationMissUntil = 0;
       await this.ctx.storage.put(META_DELEGATION, {
         raw,
@@ -3001,12 +3147,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         await this.ctx.storage.get<StoredDelegation>(META_DELEGATION);
       const inMemory = this.delegations.get(userDid);
       if (inMemory) {
+        const expiration = inMemory.expiration ?? stored?.expiration;
         return {
           present: true,
           source: 'memory',
-          ...(typeof stored?.expiration === 'number'
-            ? { expiration: stored.expiration }
-            : {}),
+          ...(typeof expiration === 'number' ? { expiration } : {}),
         };
       }
       if (stored?.raw) {
@@ -4076,7 +4221,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         if (live.attemptSource !== 'begin')
           await assertChannelAttemptAllowed(req.identity, this.env);
         requireChannelDelegation(
-          !!this.delegations.get(req.identity.userDid)?.raw,
+          this.delegations.get(req.identity.userDid),
+          Math.floor(Date.now() / 1000),
         );
       }
       // An attempt that starts from `admitting` never reached the agent (the
@@ -4173,6 +4319,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         toolOutputCapChars,
         delivery,
         usage,
+        domainContext,
       } = await this.prepareTurn(
         req,
         {
@@ -4188,9 +4335,28 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           abortController: live.abort,
           resumed: !freshInput,
           continuation: freshInput ? null : live.continuation,
+          ...(stored.domainPins ? { domainPins: stored.domainPins } : {}),
         },
       );
       const sessionId = req.sessionId;
+      // The anchors this run read are pinned on its row, so a resumed
+      // attempt reads the same document revisions.
+      if (
+        domainContext &&
+        JSON.stringify(domainContext.pins) !==
+          JSON.stringify(stored.domainPins ?? {})
+      ) {
+        stored.domainPins = domainContext.pins;
+        const request = JSON.stringify(stored);
+        try {
+          await this.runStore!.update(live.runId, { request });
+          live.record.request = request;
+        } catch (error) {
+          console.warn(
+            `[domain-context] could not pin the anchors of run ${live.runId}: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
       const sink = {
         emit: (eventName: string, payload: Record<string, unknown>) => {
           if (live.buffer.isClosed) return;
@@ -4203,6 +4369,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // (the turn's deadline timer among them) run however the attempt ends.
       try {
         this.events.register(sessionId, sink);
+        if (domainContext)
+          await this.reportDomainContext(req, domainContext.provenance);
         if (byoNotice)
           sink.emit('error', {
             ...byoNotice,
@@ -4531,15 +4699,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const window = await this.contextWindows.resolve(modelId, {
         ...(byoProvider ? { byoProvider } : {}),
       });
-      const budget = contextBudgetFor(
-        window,
-        contextKnobs(this.env, console),
-        await this.contextWindows.resolve(
-          llm && isProviderAdapter(llm)
-            ? llm.modelForRole('routing')
-            : OPENROUTER_MODEL_MAP.routing,
-        ),
-      );
+      const budget = contextBudgetFor(window, contextKnobs(this.env, console));
       const stats = (await this.resultStore?.stats()) ?? {
         rows: 0,
         sqliteBytes: 0,
@@ -4897,27 +5057,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       };
     }
 
-    /**
-     * The model that summarises the turn's history (the `routing` role): its
-     * window bounds what the summariser is handed.
-     */
-    private summaryModelId(
-      platform: LlmAdapter,
-      byoTurn: ByoTurnState | null,
-    ): string {
-      if (byoTurn)
-        return (
-          byoModelForRole(
-            byoTurn.credential.provider,
-            'routing',
-            byoTurn.mainModelId,
-          ) ?? OPENROUTER_MODEL_MAP.routing
-        );
-      return isProviderAdapter(platform)
-        ? platform.modelForRole('routing')
-        : OPENROUTER_MODEL_MAP.routing;
-    }
-
     /**
      * Build one attempt's agent and input (`buildTurn`). A build that fails
      * part-way leaves nothing behind: the cleanups it registered run (the
@@ -5029,6 +5168,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
                 credential: byoTurn.credential,
                 mainModelId: byoTurn.mainModelId,
                 chatGptBackend: byoTurn.chatGptBackend,
+                streamLiveness: streamLivenessFromEnv(core.validatedEnv, 'byo'),
               },
               console,
             ),
@@ -5047,13 +5187,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const windowResolution = await this.contextWindows.resolve(mainModelId, {
         ...(byoTurn ? { byoProvider: byoTurn.provider } : {}),
       });
+      // The summary is written by the main model too (the `summarizer`
+      // role), so the main model's window is the only one that counts.
       const contextBudget = contextBudgetFor(
         windowResolution,
         contextKnobs(this.env, console),
-        await this.contextWindows.resolve(
-          this.summaryModelId(baseAmbient.llm, byoTurn),
-          byoTurn ? { byoProvider: byoTurn.provider } : {},
-        ),
       );
       if (
         req.client === 'matrix' &&
@@ -5283,8 +5421,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         continuation: run.continuation,
         logger: console,
       });
-      // The turn's budget (turn-budget.ts): model calls are charged by the
-      // metered adapter every model of this turn comes from, tool calls by
+      // The turn's budget (turn-budget.ts): model tokens are accounted (for
+      // the usage line below, never limited) by the metered adapter every
+      // model of this turn comes from, tool calls are charged by
       // the execution middleware below, and the deadline aborts the run
       // with the limit as the reason (the stream reports it as a terminal
       // error, not as a user abort).
@@ -5294,6 +5433,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         budget,
         outputReserveTokens: contextBudget.outputReserveTokens,
         signal: abortController.signal,
+        logger: console,
       });
       const deadline = setTimeout(() => {
         if (abortController.signal.aborted) return;
@@ -5310,6 +5450,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       }, turnLimits.durationMs);
       turnDisposables.add(async () => {
         clearTimeout(deadline);
+        // Heartbeats of model calls that never reported an end.
+        meteredLlm.dispose();
         const usage = budget.snapshot();
         console.log(
           `[harness] turn ${req.requestId} usage: ~${usage.tokens} tokens (${usage.reportedTokens} reported over ${usage.modelCalls} model calls), ${usage.toolAttempts} tool attempts, ${usage.elapsedMs} ms`,
@@ -5379,6 +5521,18 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         contextBudget,
         turnBudget: budget,
         delivery,
+        // Observe-only domain context, on the object's shared resolver (the
+        // one `refresh_domain_context` invalidates); a resumed run reads the
+        // anchors it pinned.
+        ...(opts.domainContext
+          ? {
+              domainContext: opts.domainContext,
+              domainResolver: this.domainResolver,
+              onDomainProvenance: (provenance: DomainContextProvenance[]) =>
+                void this.reportDomainContext(req, provenance),
+              ...(run.domainPins ? { domainPins: run.domainPins } : {}),
+            }
+          : {}),
         ambient: {
           ...ambient,
           llm: meteredLlm,
@@ -5547,9 +5701,32 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         /** The budget's usage so far (JSON), stored with the run's end. */
         usage: (): string => JSON.stringify(budget.snapshot()),
         delivery,
+        domainContext: built.domainContext,
       };
     }
 
+    /**
+     * A turn's domain-context provenance: a `router_update` frame for the
+     * client and the session's sockets, and a `domain_context_runs` row.
+     * Diagnostics only — nothing here can fail the turn.
+     */
+    private async reportDomainContext(
+      req: TurnRequest,
+      provenance: DomainContextProvenance[],
+    ): Promise<void> {
+      const update: DomainContextRouterUpdate = {
+        sessionId: req.sessionId,
+        requestId: req.requestId,
+        domainContext: provenance,
+      };
+      this.events.emit(EVENT_NAMES.router, { ...update });
+      await this.domainContextStore?.record(
+        req.sessionId,
+        req.requestId,
+        provenance,
+      );
+    }
+
     /**
      * Node parity (`MessagesService.sendMessage`): every HTTP/SSE turn is
      * replayed into the user's oracle room as a thread under the session's

package/src/index.ts

@@ -39,6 +39,7 @@ import { artifactSweepIntervalMs } from './artifacts/config';
 import { sweepExpiredArtifacts } from './artifacts/sweep';
 import { feedbackConfigFromEnv } from './feedback/config';
 import { LinearFeedbackSink } from './feedback/linear-sink';
+import type { DomainContextOptions } from './core/domain-context';
 
 export * from './plugin-api';
 export * from './plugins';
@@ -56,6 +57,14 @@ export {
   createUserOracleDO,
   type OracleWorkerHooks,
 } from './do/user-oracle-do';
+export type {
+  DocumentRequest,
+  DomainCapsuleInspection,
+  DomainContextOptions,
+  DomainContextPins,
+  DomainContextProvenance,
+  DomainDocumentRead,
+} from './core/domain-context';
 export { createShell, type ListModelsOptions } from './shell/app';
 export { authenticate } from './shell/auth';
 export {
@@ -265,6 +274,12 @@ export interface CreateOracleWorkerOptions {
    * user object's ambient services.
    */
   hooks?: OracleWorkerHooks;
+  /**
+   * Observe-only domain context: the oracle's and the selected subject's
+   * anchored domain documents, verified by CID and handed to the model as
+   * retrieved data. Default off. See docs/configuration.md.
+   */
+  domainContext?: DomainContextOptions;
 }
 
 export interface OracleWorker {
@@ -341,6 +356,7 @@ export function createOracleWorker(
   const UserOracleDO = createUserOracleDO({
     core: coreFor,
     ...(opts.hooks ? { hooks: opts.hooks } : {}),
+    ...(opts.domainContext ? { domainContext: opts.domainContext } : {}),
   });
 
   return {

package/src/llm/byo-adapter.ts

@@ -28,6 +28,7 @@ import {
   ByoModelFallbackChatModel,
   ByoModelFallbackState,
 } from './byo-model-fallback';
+import type { StreamLivenessSettings } from './stream-liveness';
 
 export interface ByoTurnResolution {
   credential: ByoCredential;
@@ -35,6 +36,8 @@ export interface ByoTurnResolution {
   mainModelId: string;
   /** ChatGPT lane only: backend/proxy the requests go to. */
   chatGptBackend?: ChatGptBackendConfig;
+  /** The BYO lane's liveness budgets (`streamLivenessFromEnv(env, 'byo')`). */
+  streamLiveness?: StreamLivenessSettings;
 }
 
 export function createByoLlmAdapter(
@@ -68,6 +71,9 @@ export function createByoLlmAdapter(
           modelId,
           role,
           chatGptBackend: turn.chatGptBackend,
+          ...(turn.streamLiveness
+            ? { streamLiveness: turn.streamLiveness }
+            : {}),
           params: rest,
           logger,
         }),