@ixo/oracle-runtime-workers 0.38.0 → 0.40.1

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

@@ -1,3 +1,14 @@
+import { taskCardSummary } from '../plugins/tasks/tasks-tools';
+import {
+  ActionInteractionError,
+  type CheckClaimDispatch,
+  type CheckDispatch,
+} from '@ixo/action-interactions';
+import {
+  ActionInteractionStore,
+  interactionOutcome,
+  type InteractionCommand,
+} from '../action-interactions/store';
 import {
   CHANNEL_DELIVERY_NOTICE_KWARG,
   channelDeliveryNote,
@@ -186,9 +197,15 @@ import {
   DEFAULT_MODEL_ID,
 } from '../core/llm';
 import { renderTurnTimeNote } from '../core/prompt-composer';
+import type { RegisteredManifest } from '../core/registries';
+import {
+  TURN_GUIDE_NOTE_KWARG,
+  USAGE_CARRIED_KWARG,
+} from '../core/operating-guides';
 import { TURN_TIME_NOTE_KWARG, withTurnTimeNote } from '../core/turn-time-note';
 import {
   capabilityRouterMode,
+  preloadThreshold,
   createCapabilityRouter,
   shadowAgreement,
   type CapabilityRouter,
@@ -203,7 +220,6 @@ import type {
   RequestAdmissionResult,
   RequestDisposition,
 } from '../plugin-api/request-admission';
-import { bootHiddenPlugins } from '../core/tool-access';
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { AmbientServices, LlmAdapter } from '../core/runtime-context';
 import { chatGptBackendFromEnv } from '../llm/byo-client';
@@ -220,6 +236,8 @@ import { parseJwk } from '../secrets/jwe';
 import { WorkersSecretsService } from '../secrets/secrets-service';
 import { createSecretsAdapter } from './secrets-adapter';
 import {
+  EDITOR_PLUGIN_NAME,
+  editorContextActive,
   metadataBuildState,
   metadataGraphInput,
   parseTurnMetadata,
@@ -348,6 +366,7 @@ import {
   pageOfMessages,
   SessionHistoryIndexer,
   type HistoryEntry,
+  conversationReader,
   type HistoryMessage,
   type HistoryPage,
   type IndexableSession,
@@ -455,6 +474,7 @@ import {
   contentToText,
   isSummarizationMessage,
   pageThreadTranscript,
+  recentTurnTexts,
   TranscriptCursorError,
   transformTranscript,
   type TranscriptPageOptions,
@@ -571,6 +591,15 @@ type UserContextSettle = (
   signal: AbortSignal,
 ) => Promise<UserContextData | undefined>;
 
+/**
+ * What the capability router sees of the thread: enough to route a follow-up
+ * (two exchanges, each turn cut short), read from a bounded number of rows so
+ * a long thread costs nothing extra.
+ */
+const ROUTER_RECENT_TURNS = 4;
+const ROUTER_RECENT_TURN_CHARS = 300;
+const ROUTER_RECENT_ROWS = 12;
+
 /** 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…';
@@ -717,6 +746,11 @@ const META_LEGACY_CLEARED = 'meta:legacyCleared';
  */
 const META_LEGACY_UNUSABLE = 'meta:legacyUnusable';
 const META_USER_DID = 'meta:userDid';
+/**
+ * Set when an evicted object keeps an alarm only for action-card draft
+ * retention; a boot clears it. The alarm then prunes on the bare object.
+ */
+const META_RETENTION_WAKE = 'meta:interactionRetentionWake';
 
 /** KV key of a session's context-guard counters (`GET /debug/context?session=`). */
 const contextStatsKey = (sessionId: string): string => `ctxstats:${sessionId}`;
@@ -1672,6 +1706,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         throw new Error(`Object bound to ${stored}, not ${userDid}`);
       if (!stored) await this.ctx.storage.put(META_USER_DID, userDid);
       this.userDid = userDid;
+      await this.ctx.storage.delete(META_RETENTION_WAKE);
 
       const env = this.env;
       // The gateway lazily starts on first use; make sure it is up before the
@@ -2751,6 +2786,21 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // exists once the object booted).
       const keepAliveAt = this.runs?.keepAliveDeadline(wakeAt) ?? null;
       const recoveryAt = this.runs?.nextRecoveryAt() ?? null;
+      // An evicted object (no working copy, no housekeeping deadline) with
+      // no socket is only woken for action-card draft retention: prune on
+      // the bare object instead of importing the owner copy, and re-arm.
+      if (
+        !this.db &&
+        nextPingAt === null &&
+        keepAliveAt === null &&
+        recoveryAt === null &&
+        (await this.ctx.storage.get<boolean>(META_RETENTION_WAKE)) === true
+      ) {
+        const next = await this.bareInteractionRetention();
+        if (next !== null) await this.requestAlarm(next);
+        else await this.ctx.storage.delete(META_RETENTION_WAKE);
+        return;
+      }
       if (this.runs && recoveryAt !== null && recoveryAt <= wakeAt + 1000) {
         // A store error here must not reject the alarm: the tick below (or
         // the re-arm) still has to run.
@@ -2966,6 +3016,22 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         }
       }
 
+      // Action-card drafts past retention: one bounded batch per tick, so a
+      // user who stopped preparing cards still loses expired draft values.
+      // Its follow-up is no reason to keep an idle copy either.
+      if (this.userDid) {
+        try {
+          await new ActionInteractionStore(this.ctx.storage, {
+            oracleDid: this.env.ORACLE_DID,
+            userDid: this.userDid,
+          }).prune();
+        } catch (err) {
+          console.warn(
+            `[action-interactions] retention tick failed for ${this.userDid}: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+
       // Idle housekeeping: a user silent for five days loses the cached
       // pages — their file is safe upstream, and we stop paying to store a
       // copy. Never evict while tasks are scheduled: their runs ARE
@@ -2997,12 +3063,22 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         });
         if (outcome === 'evicted') {
           await this.ctx.storage.delete(META_HOUSEKEEPING_AT);
+          // Action-card drafts outlive the working copy: their retention
+          // still needs a wake (handled on the bare object, see alarm()).
+          const retentionAt = await this.interactionRetentionAt();
           // An attached (idle) socket still needs its heartbeat rounds.
-          if (nextPingAt !== null) await this.requestAlarm(nextPingAt);
+          if (nextPingAt !== null)
+            await this.requestAlarm(
+              Math.min(nextPingAt, retentionAt ?? Infinity),
+            );
           // A request that waited on the wipe has booted the object afresh
           // and armed its own deadlines (a task Start's run): keep them.
-          else if (this.initPromise === null)
-            await this.ctx.storage.deleteAlarm();
+          else if (this.initPromise === null) {
+            if (retentionAt !== null) {
+              await this.ctx.storage.put(META_RETENTION_WAKE, true);
+              await this.requestAlarm(retentionAt);
+            } else await this.ctx.storage.deleteAlarm();
+          }
           return;
         }
         if (outcome === 'not-current') {
@@ -3178,6 +3254,162 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
 
     // ── RPC surface (contracts.ts UserOracleObject) ───────────────────────
 
+    private async interactionStore(
+      identity: TurnIdentity,
+      sessionId: string,
+      options: { recordAccess?: boolean } = {},
+    ) {
+      await this.ready(identity, options);
+      if (
+        this.userDid !== identity.userDid ||
+        !(await this.sessions?.getSession(sessionId))
+      )
+        throw new ActionInteractionError(404, 'not_found', 'Session not found');
+      return new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid: identity.userDid,
+      });
+    }
+
+    async readActionInteractionTask(
+      identity: TurnIdentity,
+      sessionId: string,
+      taskId: string,
+    ) {
+      return interactionOutcome(async () => {
+        // The task scheduler needs a booted object, but an open task card polls every 15 s:
+        // the poll is not activity, so it never keeps an idle object from being evicted.
+        await this.interactionStore(identity, sessionId, {
+          recordAccess: false,
+        });
+        const task = await this.taskScheduler?.surface.get(taskId);
+        if (!task)
+          throw new ActionInteractionError(404, 'not_found', 'Task not found');
+        return JSON.stringify({ task: taskCardSummary(task) });
+      });
+    }
+
+    /**
+     * The draft store without a boot: the object is addressed by the
+     * caller's DID, and the stored binding is checked against it.
+     */
+    private async bareInteractionStore(identity: TurnIdentity) {
+      const bound =
+        this.userDid ?? (await this.ctx.storage.get<string>(META_USER_DID));
+      if (bound && bound !== identity.userDid)
+        throw new ActionInteractionError(404, 'not_found', 'Owner not found');
+      return new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid: identity.userDid,
+      });
+    }
+
+    async checkDispatch(identity: TurnIdentity, input: CheckDispatch) {
+      return interactionOutcome(async () => {
+        // Runs before every bid, claim-block and approval effect: no boot, as in checkClaimDispatch.
+        const store = await this.bareInteractionStore(identity);
+        return JSON.stringify(await store.checkDispatch(input));
+      });
+    }
+
+    async checkClaimDispatch(
+      identity: TurnIdentity,
+      input: CheckClaimDispatch,
+    ) {
+      return interactionOutcome(async () => {
+        // Every Portal claim calls this, Companion user or not, so it must
+        // not boot the object (gateway, signer, SQLite, owner-copy import):
+        // it only reads and writes a few keys. The object is addressed by
+        // the caller's DID; the stored binding is checked without a boot.
+        const store = await this.bareInteractionStore(identity);
+        return JSON.stringify(await store.checkClaimDispatch(input));
+      });
+    }
+
+    /** When stored action-card drafts next need retention, if any are kept. */
+    private async interactionRetentionAt(): Promise<number | null> {
+      const userDid =
+        this.userDid ?? (await this.ctx.storage.get<string>(META_USER_DID));
+      if (!userDid) return null;
+      return new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid,
+      })
+        .nextRetentionAt()
+        .catch(() => null);
+    }
+
+    /** One retention pass on an un-booted object; returns the next due time. */
+    private async bareInteractionRetention(): Promise<number | null> {
+      const userDid = await this.ctx.storage.get<string>(META_USER_DID);
+      if (!userDid) return null;
+      const store = new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid,
+      });
+      try {
+        await store.prune();
+      } catch (err) {
+        console.warn(
+          `[action-interactions] retention on an evicted object failed for ${userDid}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return Date.now() + 60 * 60 * 1000;
+      }
+      const next = await store.nextRetentionAt().catch(() => null);
+      // A backlog larger than one pass resumes a minute later.
+      return next === null ? null : Math.max(next, Date.now() + 60_000);
+    }
+
+    /** Drafts of a deleted chat, in bounded batches. */
+    private async forgetInteractions(userDid: string, sessionId: string) {
+      const store = new ActionInteractionStore(this.ctx.storage, {
+        oracleDid: this.env.ORACLE_DID,
+        userDid,
+      });
+      while ((await store.forgetSession(sessionId)) > 0);
+    }
+
+    async actionInteraction(
+      identity: TurnIdentity,
+      command: InteractionCommand,
+    ) {
+      return interactionOutcome(async () => {
+        const store = await this.interactionStore(
+          identity,
+          command.input.sessionId,
+        );
+        if (
+          command.kind === 'prepare' &&
+          command.input.owner.kind === 'task' &&
+          !(await this.taskScheduler?.surface.get(command.input.owner.taskId))
+        )
+          throw new ActionInteractionError(404, 'not_found', 'Task not found');
+        return JSON.stringify(await store.command(command));
+      });
+    }
+
+    async readActionInteraction(
+      identity: TurnIdentity,
+      sessionId: string,
+      id?: string,
+      references = false,
+    ) {
+      return interactionOutcome(async () => {
+        // Card polls never boot the object or count as activity: they read a
+        // few keys, so an open card neither imports an evicted owner copy nor
+        // keeps an idle object alive. A deleted chat's drafts are deleted
+        // with it, so no session lookup is needed to hide them.
+        const store = await this.bareInteractionStore(identity);
+        return JSON.stringify(
+          await (id
+            ? store.read(id, sessionId)
+            : references
+              ? store.listReferences(sessionId)
+              : store.list(sessionId)),
+        );
+      });
+    }
+
     async createSession(
       identity: TurnIdentity,
       o: { roomId?: string; sessionId?: string; markerTxnId?: string } = {},
@@ -4094,6 +4326,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           });
         await this.ctx.storage.delete(contextStatsKey(sessionId));
         await this.feedbackMarkers!.forgetSession(sessionId);
+        // The chat's action-card drafts go with it; a dispatched claim keeps
+        // only the tombstones that stop a duplicate.
+        await this.forgetInteractions(identity.userDid, sessionId).catch(
+          (err: unknown) => {
+            console.warn(
+              `[action-interactions] could not delete the drafts of ${sessionId}; retention removes them later: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          },
+        );
         this.markDirty();
       }
       // A channel binding that pointed at the session opens a new one on
@@ -4787,7 +5028,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             !isAttachmentViewMessage(m) &&
             !isDeliveryNoticeMessage(m),
         )
-        .map((m) => ({ type: m.type, content: visibleText(m) }));
+        .map(conversationReader());
     }
 
     /**
@@ -4810,6 +5051,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       }
       const pageRows = Math.max(1, limit);
       const entries: HistoryEntry[] = [];
+      const read = conversationReader();
       for (;;) {
         const rows = await saver.listThreadMessageRows(sessionId, {
           direction: 'newer',
@@ -4826,7 +5068,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           )
             continue;
           entries.push({
-            message: { type: m.type, content: visibleText(m) },
+            message: read(m),
             cursor: row.messageId,
           });
         }
@@ -5021,6 +5263,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       prior: unknown;
       client: TurnRequest['client'];
       roomKind: TurnRequest['roomKind'];
+      /** The provider's cache has expired, so the prompt may change. */
+      coldTurn: boolean;
     }): UserContextSettle | null {
       // A first contact that fetches nothing still prints the one
       // first-contact line (see the settle step below), with its reason, so
@@ -5075,9 +5319,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         // room answer — but only one already in the cache: an upload that
         // just invalidated the room must not make the next message wait for
         // a gather. On a miss the thread keeps its context and the
-        // (single-flight) refresh warms the cache for a later turn.
+        // (single-flight) refresh warms the cache for a later turn. The
+        // answer sits in the system prompt, so it waits for a cold turn: a
+        // change there re-reads the whole request at the uncached price.
         const warm =
-          input.client === 'channel'
+          input.client === 'channel' && input.coldTurn
             ? fetcher.readCached(input.roomId)
             : undefined;
         keepGathering();
@@ -7178,13 +7424,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       sessionId: string,
     ): Promise<SessionContextStatus | null> {
       if (!(await this.sessions!.getSession(sessionId))) return null;
-      const tuple = await this.saver!.getTuple({
-        configurable: { thread_id: sessionId },
-      });
-      const channel: unknown = tuple?.checkpoint.channel_values.messages;
-      const context: BaseMessage[] = Array.isArray(channel)
-        ? channel.filter(isBaseMessage)
-        : [];
+      const context = await this.contextMessages(sessionId);
       const thread = await this.saver!.listThreadMessages(sessionId);
       const stats = await this.ctx.storage.get<SessionContextCounters>(
         contextStatsKey(sessionId),
@@ -7204,6 +7444,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       };
     }
 
+    /** The messages the session's model calls start from (a summary, then the kept tail, once condensed). */
+    private async contextMessages(sessionId: string): Promise<BaseMessage[]> {
+      const tuple = await this.saver!.getTuple({
+        configurable: { thread_id: sessionId },
+      });
+      const channel: unknown = tuple?.checkpoint.channel_values.messages;
+      return Array.isArray(channel) ? channel.filter(isBaseMessage) : [];
+    }
+
     /** Fold a guard event into the session's stored counters (ordered, never throws). */
     private recordContextEvent(
       sessionId: string,
@@ -7222,7 +7471,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           switch (event.kind) {
             case 'prune':
               next.prunes += 1;
-              if (event.stage !== 'soft') next.hardPrunes += 1;
+              if (event.stage === 'hard' || event.stage === 'overflow')
+                next.hardPrunes += 1;
               next.prunedResults += event.pruned;
               break;
             case 'overflow-retry':
@@ -7721,6 +7971,13 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         configurable: { thread_id: req.sessionId },
       });
       const priorState = existing?.checkpoint.channel_values ?? {};
+      // A new thread, or quiet for longer than the provider's cache lives:
+      // this turn pays a miss whatever it sends, so it is the one to change
+      // the prefix on.
+      const coldTurn =
+        !existing ||
+        turnAt.getTime() - Date.parse(existing.checkpoint.ts) >=
+          contextBudget.cacheColdMs;
       // 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.
@@ -7734,6 +7991,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             prior: priorState.userContext,
             client: req.client,
             roomKind: req.roomKind,
+            coldTurn,
           });
 
       // A Matrix turn with no usable delegation: ask the web app to open its
@@ -7862,11 +8120,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         suppliedContextOnly ? {} : priorState,
       );
 
-      // Capability router: predict the on-demand plugin this message needs
-      // and preload it for THIS turn only. `on` is awaited here, ahead of the
-      // first model call; `shadow` returns at once and logs its verdict when
-      // it lands. The preload never enters `stateInput` — the checkpointed
-      // `loadedPlugins` channel is written by `load_capability` alone.
       const priorLoaded: ReadonlySet<string> = new Set(
         priorMeta.loadedPlugins ?? [],
       );
@@ -7885,45 +8138,49 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             client: req.client,
             env: langsmithEnvFromWorkerEnv(this.env),
           });
-      const preloadedPlugins =
-        !suppliedContextOnly && this.capabilityRouter
-          ? await this.capabilityRouter({
-              mode: capabilityRouterMode(core.validatedEnv.CAPABILITY_ROUTER),
-              manifests: core.registries.manifests.collect(),
-              loaded: priorLoaded,
-              hidden: () =>
-                bootHiddenPlugins({
-                  registries: core.registries,
-                  buildCtx: core.buildCtx(),
-                  has: (resource, action) =>
-                    ambient.ucan.hasCapability(
-                      ucanDelegation,
-                      resource,
-                      action,
+      // Capability router: from what is left to load this turn (the build
+      // works that out from the turn's tools), the plugins this message needs.
+      // `on` is awaited in the build, ahead of the first model call, and the
+      // plugins load on the thread like any other; `shadow` returns at once
+      // and logs its verdict when it lands. A resumed attempt keeps what the
+      // run started with.
+      const router = this.capabilityRouter;
+      const routeCapabilities =
+        !suppliedContextOnly && !run.resumed && router
+          ? (candidates: readonly RegisteredManifest[]) =>
+              router({
+                mode: capabilityRouterMode(core.validatedEnv.CAPABILITY_ROUTER),
+                candidates,
+                ...preloadThreshold(coldTurn, core.validatedEnv),
+                text: body.message,
+                recentTurns: async () =>
+                  recentTurnTexts(
+                    await saver.listRecentThreadMessages(
+                      req.sessionId,
+                      ROUTER_RECENT_ROWS,
                     ),
-                }),
-              hasCapability: (resource, action) =>
-                ambient.ucan.hasCapability(ucanDelegation, resource, action),
-              text: body.message,
-              requestId: req.requestId,
-              signal: abortController.signal,
-              trace: {
-                ...(tracing.callbacks && { callbacks: tracing.callbacks }),
-                // `thread_id` matches the graph run's, so LangSmith's thread
-                // view groups the router span with the turn.
-                metadata: {
-                  ...tracing.metadata,
-                  thread_id: req.sessionId,
-                  request_id: req.requestId,
+                    ROUTER_RECENT_TURNS,
+                    ROUTER_RECENT_TURN_CHARS,
+                  ),
+                requestId: req.requestId,
+                signal: abortController.signal,
+                trace: {
+                  ...(tracing.callbacks && { callbacks: tracing.callbacks }),
+                  // `thread_id` matches the graph run's, so LangSmith's thread
+                  // view groups the router span with the turn.
+                  metadata: {
+                    ...tracing.metadata,
+                    thread_id: req.sessionId,
+                    request_id: req.requestId,
+                  },
                 },
-              },
-              onShadowVerdict: (wouldPreload) =>
-                this.shadowRoutes.set(req.sessionId, {
-                  requestId: req.requestId,
-                  priorLoaded,
-                  wouldPreload,
-                }),
-            })
+                onShadowVerdict: (wouldPreload) =>
+                  this.shadowRoutes.set(req.sessionId, {
+                    requestId: req.requestId,
+                    priorLoaded,
+                    wouldPreload,
+                  }),
+              })
           : undefined;
 
       // Host page-context / safety-guardrail hooks, resolved against this
@@ -8094,13 +8351,44 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           )
         : undefined;
 
+      // On a cold turn the thread's history shows which capabilities it has
+      // moved on from. The messages are read only then, and only for a
+      // thread with something to unload; the editor stays while its context
+      // is active, and a resumed attempt keeps what the run started with.
+      const unloadable = (priorMeta.loadedPlugins ?? []).filter(
+        (plugin) =>
+          plugin !== EDITOR_PLUGIN_NAME ||
+          !editorContextActive(meta, priorMeta),
+      );
+      const capabilityExpiry =
+        coldTurn &&
+        !run.resumed &&
+        contextBudget.pluginIdleTurns > 0 &&
+        unloadable.length > 0
+          ? {
+              loaded: unloadable,
+              maxIdleTurns: contextBudget.pluginIdleTurns,
+              messages: await this.contextMessages(req.sessionId),
+            }
+          : undefined;
+
       const built = await createMainAgent({
         executionProfile: req.executionProfile,
+        ...(capabilityExpiry ? { capabilityExpiry } : {}),
         registries: core.registries,
         identity: core.identity,
         config: core.validatedEnv,
         availablePlugins: core.availablePlugins,
-        preloadedPlugins,
+        ...(routeCapabilities ? { routeCapabilities } : {}),
+        promptCache: {
+          cold: coldTurn && !run.resumed,
+          ...(priorMeta.promptGuides
+            ? { promptGuides: priorMeta.promptGuides }
+            : {}),
+          ...(priorMeta.capabilityUsage
+            ? { capabilityUsage: priorMeta.capabilityUsage }
+            : {}),
+        },
         byoProvider: byoTurn?.provider,
         contextBudget,
         turnBudget: budget,
@@ -8224,7 +8512,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         checkpointer: saver,
         abortSignal: abortController.signal,
       });
-      const { agent, context } = built;
+      const { agent, context, guideNote } = built;
       for (const [name, effect] of built.toolEffects)
         toolEffects.set(name, effect);
       for (const [name, surface] of built.toolSurfaces)
@@ -8277,9 +8565,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const referenced = replyNote
         ? withTurnTimeNote(noticed, replyNote)
         : noticed;
-      const content = timeNote
-        ? withTurnTimeNote(referenced, timeNote)
+      const guided = guideNote
+        ? withTurnTimeNote(referenced, guideNote.text)
         : referenced;
+      const content = timeNote ? withTurnTimeNote(guided, timeNote) : guided;
       const human = new HumanMessage({
         content,
         additional_kwargs: {
@@ -8289,6 +8578,12 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           ...(noticeNote
             ? { [CHANNEL_DELIVERY_NOTICE_KWARG]: noticeNote }
             : {}),
+          ...(guideNote
+            ? {
+                [TURN_GUIDE_NOTE_KWARG]: guideNote.text,
+                [USAGE_CARRIED_KWARG]: guideNote.plugins,
+              }
+            : {}),
           oracleName: core.identity.name,
           msgFromMatrixRoom: req.client === 'matrix',
           ...speakerKwargs,
@@ -8319,6 +8614,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         // every slot present; later turns write nothing and keep it.
         ...(userContext ? { userContext } : {}),
         ...metadataGraphInput(meta, priorMeta),
+        ...built.stateUpdate,
         ...surface.input,
       };
       const config = {

package/src/index.ts

@@ -60,6 +60,7 @@ export {
 } from './do/user-oracle-do';
 export type {
   DocumentRequest,
+  DomainBriefDetail,
   DomainCapsuleInspection,
   DomainContextOptions,
   DomainContextPins,