@ixo/oracle-runtime-workers 0.18.0 → 0.20.0

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

@@ -191,6 +191,7 @@ import {
   type RunsStatus,
   type ContextStatus,
   type SessionContextStatus,
+  type UserContextPrefetchStatus,
   type RunSummary,
   type TurnIdentity,
   type TurnRequest,
@@ -229,6 +230,14 @@ import {
   type HistoryMessage,
   type IndexableSession,
 } from '../memory/session-history-indexer';
+import {
+  USER_CONTEXT_SLOTS,
+  UserContextFetcher,
+  type UserContextFetchOutcome,
+  type UserContextFetchParams,
+} from '../memory/user-context-fetcher';
+import { createUserContextInvalidationMiddleware } from '../memory/user-context-invalidation';
+import { MEMORY_CAPABILITY } from '../plugins/delegated-capabilities';
 import {
   createSseSubscriberStream,
   runTurnFrames,
@@ -329,7 +338,7 @@ import {
   resolveTurnDelegation,
   WorkersUcanService,
 } from './ucan-service';
-import type { UcanDelegation } from '../plugin-api/types';
+import type { UcanDelegation, UserContextData } from '../plugin-api/types';
 
 /** What one attempt's agent build reads from the request body. */
 type TurnBuildBody = Pick<
@@ -347,6 +356,56 @@ interface TurnBuildRun {
   continuation: string | null;
   /** Domain anchors the run started with (resumed attempts keep them). */
   domainPins?: DomainContextPins;
+  /** A `router.update` step for the run's client while the build waits. */
+  onProgress?: (step: string) => void;
+}
+
+/** Where the user-context prefetch runs: the engine and the `USER_CONTEXT_*` knobs. */
+interface UserContextSettings {
+  engineUrl: string;
+  capMs?: number;
+  cacheTtlMs?: number;
+}
+
+/**
+ * The second half of a first-contact prefetch: waits for the gather (at
+ * most the cap; calling `onSlow` once it has waited past the grace) and
+ * returns the context the thread takes, or `undefined` when there is none
+ * — no answer within the cap, a failure, a skip, or the turn was aborted
+ * (the gather then keeps running in the background).
+ */
+type UserContextSettle = (
+  onSlow: () => void,
+  signal: AbortSignal,
+) => Promise<UserContextData | undefined>;
+
+/** How long a first turn waits on the user-context prefetch before saying so. */
+const USER_CONTEXT_PROGRESS_GRACE_MS = 300;
+const USER_CONTEXT_PROGRESS_STEP = 'Recalling your memories…';
+
+/**
+ * A prefetched context with every slot present, a slot the engine did not
+ * return as an empty section (which renders nothing). The checkpointed
+ * value then marks a landed gather (see `hasUserContext`) even for a user
+ * with no memory yet, so the thread's later turns do not count as first
+ * contact; and the written value is the whole context under a merging
+ * reducer (the `MainAgentGraphState` annotation's) as well as under the
+ * last-value channel the agent declares (`userContextStateMiddleware`).
+ */
+function withEverySlot(context: UserContextData): UserContextData {
+  const out: UserContextData = { ...context };
+  for (const slot of USER_CONTEXT_SLOTS) out[slot] ??= {};
+  return out;
+}
+
+/** A checkpointed `userContext` a gather has written (not the channel's `{}` default). */
+function hasUserContext(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length > 0
+  );
 }
 
 /**
@@ -877,6 +936,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     /** Session-history → memory-engine indexing (built lazily, see `scheduleHistoryIndexing`). */
     private historyIndexer: SessionHistoryIndexer | null = null;
 
+    /** First-turn user-context prefetch (built lazily, see `startUserContextPrefetch`). */
+    private userContextFetcher: UserContextFetcher | null = null;
+
     /**
      * Transcripts captured BEFORE a session is deleted, keyed by session id:
      * the indexer runs after the RPC returned, when the rows are gone.
@@ -1734,7 +1796,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           if (!roomId)
             throw new ChannelError(
               428,
-              'Companion room is not ready',
+              "The user's oracle room is not ready",
               'room_not_ready',
             );
           return (await this.createSession(identity, { roomId, markerTxnId }))
@@ -1753,13 +1815,13 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           )
             throw new ChannelError(
               404,
-              'Companion session not found',
+              'Oracle session not found',
               'session_not_found',
             );
           if (!(await this.roomIsEncrypted(roomId)))
             throw new ChannelError(
               409,
-              'Companion room must be encrypted',
+              "The user's oracle room must be encrypted",
               'room_not_encrypted',
             );
         },
@@ -2352,7 +2414,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         if (next !== null) deadlines.push(Math.max(next, now + 1000));
       }
 
-      // Channel requests: retry the Companion room mirrors that are due, and
+      // Channel requests: retry the user's oracle room mirrors that are due, and
       // prune (bounded) receipts that never started a run and old run
       // tombstones (channels/turns.ts).
       if (this.channelTurns) {
@@ -3026,6 +3088,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           mintInvocation: (target, opts) =>
             ambient.ucan.mintInvocation(userDid, target, opts),
         },
+        // Newly indexed history changes what the prefetch would recall.
+        onIndexed: (roomId) => this.userContextFetcher?.invalidate(roomId),
         speakerLabels: async (roomId) => {
           const prefs = await this.preferences
             ?.get(roomId)
@@ -3058,6 +3122,195 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       );
     }
 
+    /**
+     * The user-context prefetch's settings, or null where it does not run:
+     * switched off (`USER_CONTEXT_PREFETCH=off`) or no memory engine.
+     */
+    private userContextSettings(): UserContextSettings | null {
+      const env = this.core.validatedEnv;
+      if (env['USER_CONTEXT_PREFETCH'] === 'off') return null;
+      const engineUrl = env['MEMORY_ENGINE_URL'];
+      if (typeof engineUrl !== 'string' || engineUrl.length === 0) return null;
+      const capMs = env['USER_CONTEXT_PREFETCH_CAP_MS'];
+      const cacheTtlMs = env['USER_CONTEXT_CACHE_TTL_MS'];
+      return {
+        engineUrl,
+        ...(typeof capMs === 'number' ? { capMs } : {}),
+        ...(typeof cacheTtlMs === 'number' ? { cacheTtlMs } : {}),
+      };
+    }
+
+    /** One fetcher per object: its cache outlives turns, sessions and resets. */
+    private userContextFetcherFor(
+      settings: UserContextSettings,
+    ): UserContextFetcher {
+      this.userContextFetcher ??= new UserContextFetcher(
+        {
+          memoryEngineUrl: settings.engineUrl,
+          oracleDid: this.env.ORACLE_DID,
+          // Looked up per call, not captured: a working-copy reset replaces
+          // the ambient services while a gather may still be running.
+          ucan: {
+            hasSigningKey: () => this.ambient?.ucan.hasSigningKey() ?? false,
+            resolveServiceDid: async (url) =>
+              (await this.ambient?.ucan.resolveServiceDid(url)) ?? null,
+            mintInvocation: async (target, opts) => {
+              const ambient = this.ambient;
+              const userDid = this.userDid;
+              if (!ambient || !userDid)
+                throw new Error('the user object is not booted');
+              return ambient.ucan.mintInvocation(userDid, target, opts);
+            },
+          },
+          logger: console,
+        },
+        {
+          ...(settings.capMs !== undefined
+            ? { blockingCapMs: settings.capMs }
+            : {}),
+          ...(settings.cacheTtlMs !== undefined
+            ? { cacheTtlMs: settings.cacheTtlMs }
+            : {}),
+        },
+      );
+      return this.userContextFetcher;
+    }
+
+    /**
+     * Start a turn's user-context prefetch — stale-while-revalidate, as the
+     * Node AgentBuilder does it. A thread's context is fixed on first
+     * contact: a thread whose checkpoint already holds a gathered context
+     * never waits and never takes a newer answer; it only refreshes the
+     * room's cache in the background (a no-op while the cache is fresh), so
+     * the NEXT session in the room starts from it. First contact — including
+     * a thread whose earlier first turn got nothing (timeout, failure, skip)
+     * — waits for the gather, at most the cap. Returns the step the build
+     * awaits right before the agent is built, or null where this turn
+     * writes no context. Nothing here throws; every gather is handed to
+     * `ctx.waitUntil`, so one that outlives the cap still fills the cache.
+     */
+    private startUserContextPrefetch(input: {
+      sessionId: string;
+      roomId: string | undefined;
+      userDid: string;
+      delegation: UcanDelegation;
+      prior: unknown;
+      client: TurnRequest['client'];
+      roomKind: TurnRequest['roomKind'];
+    }): UserContextSettle | null {
+      // Task runs never get the user's memory (see `scheduleHistoryIndexing`).
+      if (!input.roomId || input.sessionId.startsWith(TASK_SESSION_PREFIX))
+        return null;
+      const settings = this.userContextSettings();
+      const ambient = this.ambient;
+      if (!settings || !ambient) return null;
+      // A group room's reply is posted to every member: one user's memory
+      // must not be (as direct reads are not, see `admissionApplies`).
+      if (input.client === 'matrix' && input.roomKind === 'group') {
+        console.log('[user-context] skipped: group room');
+        return null;
+      }
+      // Without a memory grant the gather could only fail at the mint: skip
+      // it before any request (the engine's did.json included).
+      if (
+        !ambient.ucan.hasCapability(
+          input.delegation,
+          MEMORY_CAPABILITY.resource,
+          MEMORY_CAPABILITY.action,
+        )
+      ) {
+        console.log(
+          `[user-context] skipped: the delegation grants no ${MEMORY_CAPABILITY.resource} ${MEMORY_CAPABILITY.action}`,
+        );
+        return null;
+      }
+      const fetcher = this.userContextFetcherFor(settings);
+      const params: UserContextFetchParams = {
+        roomId: input.roomId,
+        userDid: input.userDid,
+        sessionId: input.sessionId,
+      };
+      const keepGathering = (): void =>
+        this.ctx.waitUntil(
+          fetcher.refresh(params).catch((err: unknown) => {
+            console.warn(
+              `[user-context] background refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }),
+        );
+      if (hasUserContext(input.prior)) {
+        keepGathering();
+        return null;
+      }
+      const pending = fetcher
+        .fetch(params)
+        .catch((err: unknown): UserContextFetchOutcome => {
+          const reason = err instanceof Error ? err.message : String(err);
+          console.warn(`[user-context] failed: ${reason}`);
+          return { kind: 'failed', reason };
+        });
+      // Joins the gather `fetch` started (a no-op on a cache hit).
+      keepGathering();
+      return async (onSlow, signal) => {
+        if (signal.aborted) return undefined;
+        const timer = setTimeout(onSlow, USER_CONTEXT_PROGRESS_GRACE_MS);
+        let onAbort: (() => void) | undefined;
+        const aborted = new Promise<undefined>((resolve) => {
+          onAbort = () => resolve(undefined);
+          signal.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+          const outcome = await Promise.race([pending, aborted]);
+          return outcome?.kind === 'cached' || outcome?.kind === 'fresh'
+            ? withEverySlot(outcome.context)
+            : undefined;
+        } finally {
+          clearTimeout(timer);
+          if (onAbort) signal.removeEventListener('abort', onAbort);
+        }
+      };
+    }
+
+    /** `GET /debug/context` — the prefetch for a session's room, else the user's room. */
+    private async userContextPrefetchStatus(
+      sessionId: string | undefined,
+    ): Promise<UserContextPrefetchStatus> {
+      const userDid = this.userDid;
+      const sessionRoom = sessionId
+        ? (this.sessionRooms.get(sessionId) ??
+          (await this.sessions?.getSession(sessionId))?.roomId)
+        : undefined;
+      const room =
+        sessionRoom ??
+        this.mainRoomId ??
+        (userDid
+          ? (await this.gateway.resolveUserRoom(userDid).catch(() => null))
+              ?.roomId
+          : undefined);
+      const status =
+        room && this.userContextFetcher
+          ? this.userContextFetcher.status(room)
+          : undefined;
+      const last = status?.lastOutcome;
+      return {
+        enabled: this.userContextSettings() !== null,
+        ...(room ? { room } : {}),
+        cached: status?.cached ?? false,
+        ...(status?.ageMs !== undefined ? { ageMs: status.ageMs } : {}),
+        inFlight: status?.inFlight ?? false,
+        ...(last ? { lastOutcome: last.kind } : {}),
+        ...(last?.kind === 'failed' || last?.kind === 'skipped'
+          ? { lastReason: last.reason }
+          : {}),
+        ...(last?.kind === 'fresh'
+          ? { lastMs: last.ms, lastSlots: last.slots }
+          : {}),
+        ...(status?.lastAt !== undefined
+          ? { lastAt: new Date(status.lastAt).toISOString() }
+          : {}),
+      };
+    }
+
     async listMessages(
       identity: TurnIdentity,
       sessionId: string,
@@ -4454,6 +4707,21 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           resumed: !freshInput,
           continuation: freshInput ? null : live.continuation,
           ...(stored.domainPins ? { domainPins: stored.domainPins } : {}),
+          // The Portal shows `router.update` steps (as it shows "Queued…");
+          // chat surfaces have no place for one.
+          ...(req.client === 'portal'
+            ? {
+                onProgress: (step: string) => {
+                  if (live.buffer.isClosed) return;
+                  live.buffer.push('router.update', {
+                    step,
+                    sessionId: req.sessionId,
+                    requestId: req.requestId,
+                    runId: live.runId,
+                  });
+                },
+              }
+            : {}),
         },
       );
       const sessionId = req.sessionId;
@@ -4763,7 +5031,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       outcome: RunOutcome,
     ): Promise<void> {
       // A channel run's reply (or the end of a run without one) is mirrored
-      // into the Companion room in the background: never awaited here, so
+      // into the user's oracle room in the background: never awaited here, so
       // the session's next queued run starts at once. Without the handle (a
       // reset dropped it mid-run) the next poll or alarm mirrors it.
       if (record.client === 'channel') this.channelTurns?.deliverReply();
@@ -4845,6 +5113,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         ...(sessionId
           ? { session: await this.sessionContextStatus(sessionId) }
           : {}),
+        userContext: await this.userContextPrefetchStatus(sessionId),
       };
     }
 
@@ -5345,6 +5614,29 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       }
       if (sessionRoomId) this.sessionRooms.set(req.sessionId, sessionRoomId);
 
+      // The delegation the whole turn reads: the prefetch's memory grant
+      // here, the router's candidates and every capability check of the
+      // build and its tools below.
+      const ucanDelegation = await this.turnDelegation(req.identity);
+      const existing = await saver.getTupleWithoutMessages({
+        configurable: { thread_id: req.sessionId },
+      });
+      const priorState = existing?.checkpoint.channel_values ?? {};
+      // What the memory engine knows about the user, for the prompt's
+      // context block: started now so the round-trip overlaps the rest of
+      // the build, settled right before the agent is built.
+      const settleUserContext = suppliedContextOnly
+        ? null
+        : this.startUserContextPrefetch({
+            sessionId: req.sessionId,
+            roomId: sessionRoomId,
+            userDid: req.identity.userDid,
+            delegation: ucanDelegation,
+            prior: priorState.userContext,
+            client: req.client,
+            roomKind: req.roomKind,
+          });
+
       // A Matrix turn with no usable delegation: ask the web app to open its
       // "authorize for Matrix" modal (throttled per user, best-effort) — the
       // Node AgentBuilder's `maybePromptReauth`.
@@ -5425,10 +5717,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             signal: abortController.signal,
           });
 
-      const existing = await saver.getTupleWithoutMessages({
-        configurable: { thread_id: req.sessionId },
-      });
-      const priorState = existing?.checkpoint.channel_values ?? {};
       // Request metadata (editor room, space, session run, entity) → state,
       // by the Node agent-builder's rules (see turn-metadata.ts).
       const meta = parseTurnMetadata(
@@ -5461,9 +5749,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             client: req.client,
             env: langsmithEnvFromWorkerEnv(this.env),
           });
-      // The delegation the whole turn reads: the router's candidates here,
-      // every capability check of the build and its tools below.
-      const ucanDelegation = await this.turnDelegation(req.identity);
       const preloadedPlugins =
         !suppliedContextOnly && this.capabilityRouter
           ? await this.capabilityRouter({
@@ -5597,6 +5882,17 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // which is a tool result to the main agent. Wrapped tools are capped
       // inside the wrapper (already under the cap by the time it runs).
       const capMiddleware = createResultCapMiddleware(resultCap);
+      // A successful memory write drops the room's prefetched context, so
+      // the next session gathers again (this thread keeps its own).
+      const userContextInvalidation =
+        sessionRoomId && this.userContextSettings()
+          ? createUserContextInvalidationMiddleware({
+              roomId: sessionRoomId,
+              invalidate: (roomId) =>
+                this.userContextFetcher?.invalidate(roomId),
+              logger: console,
+            })
+          : null;
 
       // Chat delivery: a channel or Matrix turn replies as short messages and
       // may hand long content to `create_artifact` (bound only when artefact
@@ -5623,6 +5919,16 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           ]
         : [];
 
+      // The prefetched user context on first contact (bounded by the cap and
+      // the turn's abort); a wait past the grace tells a Portal client what
+      // it waits on.
+      const userContext = settleUserContext
+        ? await settleUserContext(
+            () => run.onProgress?.(USER_CONTEXT_PROGRESS_STEP),
+            abortController.signal,
+          )
+        : undefined;
+
       const built = await createMainAgent({
         executionProfile: req.executionProfile,
         registries: core.registries,
@@ -5660,7 +5966,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             : [],
           // Applied to the main agent AND every sub-agent: a sub-agent's
           // own tool calls are marked and capped too.
-          toolMiddlewares: [marksMiddleware, capMiddleware],
+          toolMiddlewares: [
+            marksMiddleware,
+            capMiddleware,
+            ...(userContextInvalidation ? [userContextInvalidation] : []),
+          ],
           // Budget, scheduling and write claims, innermost around each tool
           // call (main agent and sub-agents alike).
           toolExecution: executionMiddleware,
@@ -5708,6 +6018,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         state: {
           ...(suppliedContextOnly ? {} : priorState),
           userPreferences,
+          ...(userContext ? { userContext } : {}),
           ...metadataBuildState(meta, priorMeta),
           // The client-declared surface: the portal and AG-UI plugins turn
           // these into tools at build time (`getRequestTools` reads
@@ -5791,6 +6102,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         ],
         config: { did: req.identity.userDid },
         client: req.client,
+        // First contact's gathered context is checkpointed with the turn,
+        // every slot present; later turns write nothing and keep it.
+        ...(userContext ? { userContext } : {}),
         ...metadataGraphInput(meta, priorMeta),
         ...surface.input,
       };

package/src/memory/session-history-indexer.ts

@@ -68,6 +68,8 @@ export interface SessionHistoryIndexerDeps {
     ): Promise<string>;
   };
   speakerLabels(roomId: string): Promise<SpeakerLabels>;
+  /** Called after the engine accepted an upload for the room. */
+  onIndexed?(roomId: string): void;
   logger: Logger;
   fetchImpl?: typeof fetch;
   /** Test hooks. */
@@ -316,6 +318,7 @@ export class SessionHistoryIndexer {
           `memory engine rejected the conversation (${res.status}): ${text.slice(0, 200)}`,
         );
       }
+      deps.onIndexed?.(roomId);
     }
 
     const newCount = lastProcessedCount + newMessages.length;