@ixo/oracle-runtime-workers 0.16.0 → 0.17.0

package/src/core/registries.ts

@@ -327,22 +327,33 @@ function withoutShadowingRequestTools(
  * tools), or one an earlier request-time entry of the same turn already
  * claimed, is dropped with one warning naming the plugin. Sub-agents are
  * compared by the tool name they are bound under. Boot-time entries pass
- * through untouched; their collisions are a boot error
- * (`assertNoCollisions`).
+ * through untouched (their collisions are a boot error, `assertNoCollisions`)
+ * unless they take one of `runtimeNames`: tools the runtime binds only on
+ * some turns (so no boot check can see them), which win over a plugin tool
+ * of either origin.
  */
 export function dropShadowingRequestEntries(opts: {
   tools: readonly RegisteredTool[];
   requestSubAgents: readonly RegisteredSubAgent[];
   reservedNames: Iterable<string>;
+  /** Names the runtime binds this turn; reserved against boot-time tools too. */
+  runtimeNames?: Iterable<string>;
   logger: { warn(message: string): void };
 }): { tools: RegisteredTool[]; requestSubAgents: RegisteredSubAgent[] } {
-  const taken = new Set(opts.reservedNames);
+  const runtime = new Set(opts.runtimeNames);
+  const taken = new Set([...opts.reservedNames, ...runtime]);
   const drop = (pluginName: string, name: string, kind: string): void =>
     opts.logger.warn(
       `${LOG_PREFIX} plugin "${pluginName}" request-time ${kind} "${name}" dropped: the name is already taken this turn`,
     );
   const tools: RegisteredTool[] = [];
   for (const entry of opts.tools) {
+    if (entry.origin === 'boot' && runtime.has(entry.tool.name)) {
+      opts.logger.warn(
+        `${LOG_PREFIX} plugin "${entry.pluginName}" tool "${entry.tool.name}" dropped for this turn: the runtime binds a tool of that name`,
+      );
+      continue;
+    }
     if (entry.origin === 'request') {
       if (taken.has(entry.tool.name)) {
         drop(entry.pluginName, entry.tool.name, 'tool');

package/src/core/state.ts

@@ -69,7 +69,8 @@ export const MainAgentGraphState = Annotation.Root({
     default: () => undefined,
     reducer: (_, curr) => curr,
   }),
-  currentEntityDid: Annotation<string | undefined>({
+  /** Subject entity (request `metadata.currentEntityDid`); `null` once a request cleared it. */
+  currentEntityDid: Annotation<string | null | undefined>({
     default: () => undefined,
     reducer: (_, curr) => curr,
   }),

package/src/core/sub-agent-fallback.ts

@@ -55,6 +55,11 @@ export interface CollectSubAgentsInput {
    * in name collisions.
    */
   passthroughTools?: StructuredTool[];
+  /**
+   * Runtime context appended to every sub-agent's system prompt (the turn's
+   * domain-context block), so a sub-agent works from what the main agent saw.
+   */
+  contextPrompt?: string;
   /** Middlewares every sub-agent's inner graph gets in addition to its own. */
   extraMiddleware?: AgentMiddleware[];
   /**
@@ -170,6 +175,7 @@ export async function collectSubAgentsWithFallback(
     fallbackContext,
     toAgentSpec,
     passthroughTools,
+    contextPrompt,
     subAgents,
     extraMiddleware,
     resultCap,
@@ -197,9 +203,15 @@ export async function collectSubAgentsWithFallback(
               resultCap,
               dispatchMiddleware,
             );
-        const withPassthrough: AgentSpec = passthroughTools?.length
-          ? { ...spec, passthroughTools }
+        const withContext: AgentSpec = contextPrompt
+          ? {
+              ...spec,
+              systemPrompt: `${spec.systemPrompt}\n\n${contextPrompt}`,
+            }
           : spec;
+        const withPassthrough: AgentSpec = passthroughTools?.length
+          ? { ...withContext, passthroughTools }
+          : withContext;
         return createSubagentAsTool(
           withPassthrough,
           withPassthrough.forwardTools

package/src/core/turn-budget.ts

@@ -1,13 +1,8 @@
 /**
  * One turn's resource budget, shared by the main agent, every sub-agent it
  * dispatches and the helper models (summarizer, attachment extraction) the
- * turn's LLM adapter hands out. Three limits:
+ * turn's LLM adapter hands out. Two limits:
  *
- *   - `tokens`     — cumulative model tokens. A call reserves an estimate
- *                    (chars/4 of what it sends plus the output reserve) before
- *                    it starts and settles to the provider's reported usage
- *                    when the call ends, so the counter is an estimate only
- *                    while a call is in flight.
  *   - `tools`      — tool attempts, counting a sub-agent dispatch and each
  *                    retry of a read.
  *   - `durationMs` — wall clock since the budget was created (the turn's
@@ -16,6 +11,17 @@
  * Exhaustion is terminal for the turn: `HarnessLimitError` is not retryable
  * and the work already done (checkpoints, tool results) is kept.
  *
+ * Model tokens are accounted, never limited: a call reserves an estimate
+ * (chars/4 of what it sends plus the output reserve) before it starts and
+ * settles to the provider's reported usage when the call ends, so the
+ * counter is an estimate only while a call is in flight. The count is
+ * reported for observability (the host logs it at the end of the turn and
+ * keeps it with the run) and never fails a turn, however large it gets:
+ * every call re-sends the whole history, so a turn on a long thread
+ * legitimately sums to many times the context window. A turn is bounded
+ * by its tool attempts and its deadline, and each request by the context
+ * budget (`context-budget.ts`).
+ *
  * Token counts are estimates reconciled against provider usage, never a
  * billing figure; `TURN_RECURSION_LIMIT` stays the separate guard against a
  * runaway graph.
@@ -25,7 +31,7 @@ export class HarnessLimitError extends Error {
 
   constructor(
     readonly kind: 'budget_exhausted',
-    readonly limit: 'tokens' | 'tools' | 'time',
+    readonly limit: 'tools' | 'time',
     message: string,
   ) {
     super(message);
@@ -33,13 +39,9 @@ export class HarnessLimitError extends Error {
   }
 }
 
-const LIMITS: ReadonlySet<string> = new Set(['tokens', 'tools', 'time']);
-
 function limitOf(error: Error): HarnessLimitError['limit'] | undefined {
   const value: unknown = Reflect.get(error, 'limit');
-  return value === 'tokens' || value === 'tools' || value === 'time'
-    ? value
-    : undefined;
+  return value === 'tools' || value === 'time' ? value : undefined;
 }
 
 /**
@@ -54,7 +56,7 @@ export function harnessLimitOf(error: unknown): HarnessLimitError | undefined {
   for (let depth = 0; depth < 32 && current instanceof Error; depth += 1) {
     if (current instanceof HarnessLimitError) return current;
     const limit = limitOf(current);
-    if (current.name === 'HarnessLimitError' && limit && LIMITS.has(limit))
+    if (current.name === 'HarnessLimitError' && limit)
       return new HarnessLimitError('budget_exhausted', limit, current.message);
     current = current.cause;
   }
@@ -67,8 +69,6 @@ export function isHarnessLimitError(error: unknown): boolean {
 }
 
 export interface TurnLimits {
-  /** Cumulative model tokens (estimated input + reserved output, settled to usage). */
-  tokens: number;
   /** Tool attempts, sub-agent dispatches included. */
   tools: number;
   /** Wall-clock deadline for the turn. */
@@ -76,14 +76,12 @@ export interface TurnLimits {
 }
 
 export const DEFAULT_TURN_LIMITS: TurnLimits = {
-  tokens: 500_000,
   tools: 120,
   durationMs: 600_000,
 };
 
 /** Parse the `TURN_*` env knobs; anything unusable keeps its default. */
 export function turnLimitsFromEnv(env: {
-  TURN_MAX_TOKENS?: number | string;
   TURN_MAX_TOOL_CALLS?: number | string;
   TURN_TIMEOUT_MS?: number | string;
 }): TurnLimits {
@@ -93,7 +91,6 @@ export function turnLimitsFromEnv(env: {
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
   };
   return {
-    tokens: positive(env.TURN_MAX_TOKENS, DEFAULT_TURN_LIMITS.tokens),
     tools: positive(env.TURN_MAX_TOOL_CALLS, DEFAULT_TURN_LIMITS.tools),
     durationMs: positive(env.TURN_TIMEOUT_MS, DEFAULT_TURN_LIMITS.durationMs),
   };
@@ -134,6 +131,8 @@ export class TurnBudget {
   /**
    * Reserve a model call before it starts. Returns the reservation so the
    * caller can settle it against the provider's usage once the call ends.
+   * Only an aborted turn or a passed deadline refuses the call: the token
+   * count itself is never a reason to.
    */
   reserveModel(
     estimatedInputTokens: number,
@@ -141,14 +140,12 @@ export class TurnBudget {
     signal?: AbortSignal,
   ): number {
     this.check(signal);
-    // A NaN would poison the counter for the rest of the turn (every later
-    // comparison with the limit is false): an unusable number counts as 0.
+    // A NaN would poison the reported count for the rest of the turn: an
+    // unusable number counts as 0.
     const usable = (n: number): number =>
       Number.isFinite(n) ? Math.max(0, n) : 0;
     const reservation =
       usable(estimatedInputTokens) + usable(outputReserveTokens);
-    if (this.tokens + reservation > this.limits.tokens)
-      this.fail('tokens', 'token');
     this.tokens += reservation;
     this.modelCalls += 1;
     return reservation;

package/src/do/contracts.ts

@@ -21,6 +21,7 @@ import type {
   FeedbackSettlement,
   FeedbackTarget,
 } from '../feedback/contract';
+import type { DomainContextProvenance } from '../core/domain-context';
 /**
  * Cross-object contracts for the Workers runtime.
  *
@@ -227,10 +228,18 @@ export interface OracleWorkerEnv {
   /** Display markup for `GET /models` prices (default 1.6). */
   MODEL_PRICE_MARKUP?: string;
   MAIN_REASONING_EFFORT?: string;
+  /**
+   * Model-call liveness (docs/configuration.md): ms to response headers
+   * (default 120000), ms of silence between body bytes on the platform lane
+   * (90000) and on BYO lanes (300000), retries before the first byte (1).
+   */
+  LLM_HEADERS_TIMEOUT_MS?: string;
+  LLM_STREAM_IDLE_TIMEOUT_MS?: string;
+  LLM_BYO_STREAM_IDLE_TIMEOUT_MS?: string;
+  LLM_STREAM_RETRIES?: string;
   /** LangGraph steps one turn may take before `GraphRecursionError` (default 600; Node hard-codes 200). */
   TURN_RECURSION_LIMIT?: string;
-  /** Turn budget: cumulative model tokens (default 500000), tool attempts (120), deadline in ms (600000). */
-  TURN_MAX_TOKENS?: string;
+  /** Turn budget: tool attempts (default 120) and deadline in ms (600000). */
   TURN_MAX_TOOL_CALLS?: string;
   TURN_TIMEOUT_MS?: string;
   /** Repetition guard: identical successful writes (default 1) and reads (5) per turn. */
@@ -441,6 +450,18 @@ export interface ContextStatus {
   session?: SessionContextStatus | null;
 }
 
+/**
+ * The `router_update` frame (`router.update` on the SSE stream) that reports
+ * a turn's domain context: one entry per domain the turn looked up (the
+ * oracle's, then the subject's), with CIDs, status and findings. Other
+ * `router_update` frames (a queued run, plugin steps) carry other fields.
+ */
+export interface DomainContextRouterUpdate {
+  sessionId: string;
+  requestId: string;
+  domainContext: DomainContextProvenance[];
+}
+
 export interface RunSummary {
   runId: string;
   sessionId: string;

package/src/do/domain-context-store.ts

@@ -0,0 +1,123 @@
+/**
+ * Per-turn domain-context provenance, kept in the user's own SQLite file
+ * (`domain_context_runs`): which domain documents a turn was given, by CID,
+ * with their status and findings. Bodies, credentials and reasoning are
+ * never stored. A deleted session takes its rows with it
+ * (`deleteForSession`). Diagnostics only: a failed write is logged with
+ * `[domain-context]` and never fails the turn. The table is created by the
+ * first recorded turn, so an oracle without domain context never has it.
+ */
+import type { DoSqliteDatabase } from '../sqlite/database';
+import type { Logger } from '../plugin-api/types';
+import type { DomainContextProvenance } from '../core/domain-context';
+
+export interface DomainContextRunRow {
+  requestId: string;
+  sessionId: string;
+  provenance: DomainContextProvenance[];
+  createdAt: number;
+}
+
+export class DomainContextStore {
+  private setupPromise: Promise<void> | undefined;
+
+  constructor(
+    private readonly db: Pick<DoSqliteDatabase, 'run' | 'exec'>,
+    private readonly log: Pick<Logger, 'warn'>,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private setup(): Promise<void> {
+    this.setupPromise ??= this.createTables().catch((error: unknown) => {
+      this.setupPromise = undefined;
+      throw error;
+    });
+    return this.setupPromise;
+  }
+
+  private async createTables(): Promise<void> {
+    await this.db.run(
+      `CREATE TABLE IF NOT EXISTS domain_context_runs (
+         request_id TEXT NOT NULL,
+         session_id TEXT NOT NULL,
+         provenance TEXT NOT NULL,
+         created_at INTEGER NOT NULL,
+         PRIMARY KEY (session_id, request_id)
+       )`,
+    );
+  }
+
+  /** Record a turn's provenance; a resumed attempt of the same request replaces it. */
+  async record(
+    sessionId: string,
+    requestId: string,
+    provenance: DomainContextProvenance[],
+  ): Promise<void> {
+    try {
+      await this.setup();
+      await this.db.run(
+        `INSERT OR REPLACE INTO domain_context_runs
+           (request_id, session_id, provenance, created_at) VALUES (?, ?, ?, ?)`,
+        [requestId, sessionId, JSON.stringify(provenance), this.now()],
+      );
+    } catch (error) {
+      this.log.warn(
+        `[domain-context] could not record the provenance of ${requestId}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /** A session's rows, oldest first (diagnostics and tests). */
+  async listForSession(sessionId: string): Promise<DomainContextRunRow[]> {
+    await this.setup();
+    const rows = await this.db.exec<{
+      request_id: string;
+      session_id: string;
+      provenance: string;
+      created_at: number;
+    }>(
+      `SELECT request_id, session_id, provenance, created_at
+       FROM domain_context_runs WHERE session_id = ?
+       ORDER BY created_at, rowid`,
+      [sessionId],
+    );
+    return rows.map((row) => ({
+      requestId: row.request_id,
+      sessionId: row.session_id,
+      provenance: parseProvenance(row.provenance),
+      createdAt: row.created_at,
+    }));
+  }
+
+  /**
+   * Delete a session's rows. Never creates the table: a database that has
+   * never recorded a domain-context turn has nothing to delete.
+   */
+  async deleteForSession(sessionId: string): Promise<void> {
+    if (!(await this.tableExists())) return;
+    await this.db.run(`DELETE FROM domain_context_runs WHERE session_id = ?`, [
+      sessionId,
+    ]);
+  }
+
+  private async tableExists(): Promise<boolean> {
+    const rows = await this.db.exec<{ name: string }>(
+      `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'domain_context_runs'`,
+    );
+    return rows.length > 0;
+  }
+}
+
+function parseProvenance(json: string): DomainContextProvenance[] {
+  const parsed: unknown = JSON.parse(json);
+  return Array.isArray(parsed) ? parsed.filter(isProvenance) : [];
+}
+
+function isProvenance(value: unknown): value is DomainContextProvenance {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'did') === 'string' &&
+    typeof Reflect.get(value, 'status') === 'string'
+  );
+}

package/src/do/run-request.ts

@@ -10,6 +10,7 @@ import type { RunSummary, TurnRequest } from './contracts';
 import type { RunRecord } from './run-store';
 import type { TurnBody } from './turn-body';
 import type { RequestDisposition } from '../plugin-api/request-admission';
+import type { DomainContextPins } from '../core/domain-context';
 
 /** The client-declared surface of a turn, as the body carries it. */
 export type ClientSurfaceBody = Pick<TurnBody, 'tools' | 'agActions'>;
@@ -21,6 +22,11 @@ export interface StoredRunRequest extends ClientSurfaceBody {
   };
   timezone?: string;
   stream?: boolean;
+  /**
+   * Domain-context anchors the run's first attempt read, by DID: a resumed
+   * attempt reads the same revisions instead of whatever is anchored now.
+   */
+  domainPins?: DomainContextPins;
 }
 
 export function storedRunRequest(

package/src/do/sse-stream.ts

@@ -306,7 +306,7 @@ export async function runTurnFrames(
     ...(input.runId ? { runId: input.runId } : {}),
   });
 
-  // The turn hit its budget (tokens, tool attempts, deadline): the abort
+  // The turn hit its budget (tool attempts, deadline): the abort
   // was the harness's, not the user's, so the client gets a terminal
   // `error` naming the limit before `done` — not a silent "aborted".
   const limitFailure = (limit: HarnessLimitError) => {

package/src/do/transcript.ts

@@ -50,6 +50,13 @@ export interface MessageDto {
   reasoning?: string;
   isComplete?: boolean;
   isReasoning?: boolean;
+  /**
+   * When the message was first saved, ISO 8601: the saver's
+   * `additional_kwargs.timestamp`, which is also the listing's order key. The
+   * turn's admission time for the user's message; for a reply, the time its
+   * step was first checkpointed. Later saves never move it.
+   */
+  createdAt?: string;
   attachment?: AttachmentMeta;
   attachments?: AttachmentMeta[];
   metadata?: { 'org.ixo.qi.origin': ChannelOrigin };
@@ -203,6 +210,8 @@ export async function transformTranscript(
         }
       }
       if (reasoning) dto.reasoning = reasoning;
+      if (typeof kw.timestamp === 'string' && kw.timestamp.length > 0)
+        dto.createdAt = kw.timestamp;
       if (attachment) dto.attachment = attachment;
       if (attachments?.length) dto.attachments = attachments;
       if (message.type === 'human') {

package/src/do/turn-body.ts

@@ -38,7 +38,8 @@ export interface TurnBody {
     editorRoomId?: string;
     spaceId?: string;
     sessionRunId?: string;
-    currentEntityDid?: string;
+    /** `null` clears the selected subject; omitted keeps it. */
+    currentEntityDid?: string | null;
   };
   tools?: Array<{
     name: string;

package/src/do/turn-metadata.ts

@@ -3,7 +3,8 @@
  *
  *  - `editorRoomId` / `spaceId` / `currentEntityDid` update the thread's
  *    checkpointed value when the request carries them, otherwise the prior
- *    value stands;
+ *    value stands; an explicit `currentEntityDid: null` clears the selected
+ *    subject (omitting it keeps the prior one);
  *  - `sessionRunId` follows the room: a request that names the editor room
  *    also defines its session run, and "no run" must not fall back to one
  *    remembered from an earlier flow — so it is written whenever
@@ -13,7 +14,8 @@
  *    pass the capability gate without an explicit `load_capability` step.
  *
  * Metadata crosses the Durable Object boundary as a JSON string; only string
- * values are honoured, anything else is ignored.
+ * values are honoured (and `null` for `currentEntityDid`), anything else is
+ * ignored.
  */
 
 export const EDITOR_PLUGIN_NAME = 'editor';
@@ -22,7 +24,8 @@ export interface TurnMetadata {
   editorRoomId?: string;
   spaceId?: string;
   sessionRunId?: string;
-  currentEntityDid?: string;
+  /** `null`: the request cleared the selected subject. */
+  currentEntityDid?: string | null;
 }
 
 const KEYS = [
@@ -48,6 +51,7 @@ export function parseTurnMetadata(json: string | undefined): TurnMetadata {
     const value = record[key];
     if (typeof value === 'string' && value.length > 0) out[key] = value;
   }
+  if (record.currentEntityDid === null) out.currentEntityDid = null;
   return out;
 }
 
@@ -101,7 +105,7 @@ export function metadataBuildState(
   editorRoomId?: string;
   sessionRunId?: string;
   spaceId?: string;
-  currentEntityDid?: string;
+  currentEntityDid?: string | null;
   loadedPlugins: string[];
 } {
   const loaded = prior.loadedPlugins ?? [];
@@ -110,7 +114,10 @@ export function metadataBuildState(
     sessionRunId:
       meta.editorRoomId !== undefined ? meta.sessionRunId : prior.sessionRunId,
     spaceId: meta.spaceId ?? prior.spaceId,
-    currentEntityDid: meta.currentEntityDid ?? prior.currentEntityDid,
+    currentEntityDid:
+      meta.currentEntityDid !== undefined
+        ? meta.currentEntityDid
+        : prior.currentEntityDid,
     loadedPlugins: editorContextActive(meta, prior)
       ? Array.from(new Set([...loaded, EDITOR_PLUGIN_NAME]))
       : loaded,
@@ -125,7 +132,7 @@ export function metadataGraphInput(
   editorRoomId?: string;
   sessionRunId?: string;
   spaceId?: string;
-  currentEntityDid?: string;
+  currentEntityDid?: string | null;
   loadedPlugins?: string[];
 } {
   return {