@ixo/oracle-runtime-workers 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {

package/src/core/main-agent.ts

@@ -46,6 +46,7 @@ import {
   composePrompt,
   formatTimeContext,
   formatUserPreferences,
+  PORTAL_CAPABILITY,
 } from './prompt-composer';
 import { formatByPlugin, type ManifestRegistry } from './registries';
 import {
@@ -54,7 +55,7 @@ import {
   type RunConfig,
   type RuntimeStateInput,
 } from './runtime-context';
-import { MainAgentGraphState } from './state';
+import { MainAgentGraphState, type BrowserToolCall } from './state';
 import { toolEffectOf } from './middlewares/tool-marks';
 import { collectSubAgentsWithFallback } from './sub-agent-fallback';
 import { computeSubAgentToolName } from './subagent-as-tool';
@@ -97,6 +98,21 @@ function selectByVisibility(
   });
 }
 
+/**
+ * Names of the browser tools the client declared on this request. The array
+ * comes straight off the wire, so an entry without a usable name is skipped
+ * rather than rendered as "undefined".
+ */
+function browserToolNames(
+  browserTools: BrowserToolCall[] | undefined,
+): string[] {
+  return (browserTools ?? []).flatMap((entry) =>
+    typeof entry?.name === 'string' && entry.name.length > 0
+      ? [entry.name]
+      : [],
+  );
+}
+
 /**
  * Build a compiled main agent from the runtime's registries plus per-request
  * context. Same pipeline as the Node runtime — tools from the registries
@@ -472,9 +488,20 @@ export async function createMainAgent(
 
   const customInstructions = identity.prompt?.customInstructions?.trim() ?? '';
 
+  // Browser tools never surface through `search_skills` / `list_capabilities`,
+  // so the prompt names them per turn and says whether the capability gate
+  // still hides them (portal is on-demand by default).
+  const browserTools = {
+    names: browserToolNames(state.browserTools),
+    bound:
+      manifestViz.get(PORTAL_CAPABILITY) === 'always' ||
+      loadedSet.has(PORTAL_CAPABILITY),
+  };
+
   const systemPrompt = await composePrompt({
     identity,
     capabilityBlock: tier1.block,
+    browserTools,
     customInstructions,
     operationalMode: hooks?.operationalMode ?? DEFAULT_OPERATIONAL_MODE,
     userPreferencesContext: formatUserPreferences(state.userPreferences),

package/src/core/prompt-composer.ts

@@ -76,6 +76,13 @@ export interface ComposePromptInput {
    * mandate a discovery flow the model cannot run.
    */
   capabilityDiscovery?: boolean;
+  /**
+   * Browser tools the client declared for this turn (`state.browserTools`),
+   * by name, plus whether they are already callable: `bound` is true when the
+   * portal plugin is `always` visible or has been loaded on this thread.
+   * Omit (or pass empty `names`) on non-Portal turns — nothing renders.
+   */
+  browserTools?: { names: string[]; bound: boolean };
   /** User preferences rendered as bullets. Empty when not set. */
   userPreferencesContext: string;
   /** Memory-engine context blocks. */
@@ -331,13 +338,40 @@ export function buildOracleSection(input: {
   return `You are ${oracleName}, an AI agent built on QiForge.`;
 }
 
+/** The plugin that binds the client-declared browser tools. */
+export const PORTAL_CAPABILITY = 'portal';
+
+/**
+ * Render the per-turn "Browser tools this turn" section. Empty string when the
+ * client declared no browser tools, so non-Portal turns pay nothing for it.
+ * The load line appears only while the tools sit behind the capability gate
+ * (portal is `on-demand` and not yet in `loadedPlugins`).
+ */
+function buildBrowserToolsBlock(
+  browserTools: ComposePromptInput['browserTools'],
+): string {
+  if (!browserTools || browserTools.names.length === 0) return '';
+  const lines = [
+    '## Browser tools this turn',
+    '',
+    `The Portal exposed these browser-side tools for this turn (they act on the user's screen): ${browserTools.names.join(', ')}`,
+  ];
+  if (!browserTools.bound) {
+    lines.push(
+      `They are bound behind the \`${PORTAL_CAPABILITY}\` capability — call \`load_capability({ names: ['${PORTAL_CAPABILITY}'] })\` once before using them.`,
+    );
+  }
+  return lines.join('\n');
+}
+
 /**
  * The discovery mandate. Rendered on every turn whose surface can actually
  * grow — i.e. wherever the meta-tools are bound.
  */
-const DISCOVERY_PRINCIPLE = `- **Search first, build second.** Before doing any non-trivial task, you MUST run discovery before producing the answer yourself. That means:
-  1. Call \`search_skills\` against the user's request whenever a packaged skill could plausibly do the job (anything that involves generating a file, document, report, page, integration, calculation, lookup, or multi-step workflow).
-  2. Call \`list_capabilities\` to scan loaded + on-demand plugins when the task could be served by a plugin you haven't loaded yet. Then call \`load_capability({ names: [...] })\` with ALL the capabilities you need in a single call — it accepts an array, so never make multiple \`load_capability\` calls in the same turn.
+const DISCOVERY_PRINCIPLE = `- **Search first, build second.** Before doing any non-trivial task, you MUST run discovery before producing the answer yourself. Capabilities live in three lanes, each found differently:
+  1. **Packaged skills** — call \`search_skills\` against the user's request whenever a skill could plausibly do the job (generating a file, document, report, or page; calculations; lookups; multi-step workflows).
+  2. **Server-side plugins and third-party integrations** (memory, sandbox, email, calendar, web, files, external services) — call \`list_capabilities\` to scan loaded + on-demand plugins, then call \`load_capability({ names: [...] })\` ONCE with everything you need — it accepts an array, so never make multiple \`load_capability\` calls in the same turn.
+  3. **Browser tools** — the \`[Portal]\`-prefixed tools already in your tool list. They run on the user's screen inside the Portal: navigate, open a URL or page, create pages/rooms, fill forms, grant access, change what the user sees. Use them for anything that happens on the user's side. They NEVER appear in \`search_skills\` or \`list_capabilities\` results — check your tool list (and the "Browser tools this turn" section when present) directly.
   Do this proactively — even when the task wording doesn't literally match a capability's \`whenToUse\`. Tell the user in ONE short sentence what you're checking ("Checking the skills registry for an invoice generator…") before the search call, not after. If something fits, use it (load + run). If nothing fits after the search, say so in one short sentence and only THEN build from scratch. Reusing a vetted capability is almost always better than reinventing it; silently skipping discovery is the worst failure mode.`;
 
 /**
@@ -357,6 +391,10 @@ const TEMPLATE = `{{{ORACLE_SECTION}}}
 {{{CAPABILITY_BLOCK}}}
 
 {{/CAPABILITY_BLOCK}}
+{{#BROWSER_TOOLS_BLOCK}}
+{{{BROWSER_TOOLS_BLOCK}}}
+
+{{/BROWSER_TOOLS_BLOCK}}
 ## Operating principles
 
 - The user's current message is your primary instruction. Background context (what you already know about them) is for adapting tone and suggestions, not for overriding their intent.
@@ -436,6 +474,7 @@ export async function composePrompt(
     ORACLE_SECTION: oracleSection,
     CAPABILITIES_NOTE: capabilitiesNote,
     CAPABILITY_BLOCK: input.capabilityBlock,
+    BROWSER_TOOLS_BLOCK: buildBrowserToolsBlock(input.browserTools),
     DISCOVERY_PRINCIPLE:
       input.capabilityDiscovery === false ? '' : DISCOVERY_PRINCIPLE,
     CUSTOM_INSTRUCTIONS: input.customInstructions,

package/src/do/contracts.ts

@@ -439,6 +439,8 @@ export interface StorageStatus {
   pages: number;
   ownerEtag?: string;
   lastFlushAt?: number;
+  /** When the dirty copy is due to be uploaded (absent when clean). */
+  nextFlushAt?: number;
   dirty: boolean;
   flushInFlight: boolean;
   /** VFS write generation now vs. at the last successful upload. */

package/src/do/flush-schedule.ts

@@ -0,0 +1,40 @@
+/**
+ * Whether a housekeeping wake should upload the working copy to the owner
+ * store. The object's single alarm serves several clients (realtime
+ * heartbeats, the durable-run keep-alive, task runs, compaction, the R2
+ * tier, idle eviction), so a wake says nothing about WHY it happened. The
+ * flush has its own persisted deadline (`meta:flushAt`, armed by the first
+ * write after an upload and replaced by the retry delay after a failure)
+ * and runs only when that deadline is due — every other wake leaves a
+ * dirty copy alone. Two exceptions upload right away: a copy about to be
+ * evicted (the wipe must never drop unsaved turns) and a copy marked dirty
+ * before the deadline existed (older objects; one upload, then the
+ * debounce applies).
+ */
+export interface FlushScheduleInput {
+  /** The object holds writes the owner store has not seen (and a database is open). */
+  dirty: boolean;
+  /** The persisted flush deadline (undefined = none recorded). */
+  flushAt: unknown;
+  now: number;
+  /** The idle-eviction path is about to wipe the working copy. */
+  idle: boolean;
+}
+
+export type FlushScheduleDecision =
+  | { action: 'skip'; reason: 'clean' }
+  | { action: 'flush'; reason: 'due' | 'idle' | 'no-deadline' }
+  | { action: 'wait'; at: number };
+
+/** Alarms fire a hair early; a deadline this close counts as due. */
+export const FLUSH_DUE_SLACK_MS = 1000;
+
+export function decideFlush(input: FlushScheduleInput): FlushScheduleDecision {
+  if (!input.dirty) return { action: 'skip', reason: 'clean' };
+  if (input.idle) return { action: 'flush', reason: 'idle' };
+  if (typeof input.flushAt !== 'number' || !Number.isFinite(input.flushAt))
+    return { action: 'flush', reason: 'no-deadline' };
+  if (input.flushAt <= input.now + FLUSH_DUE_SLACK_MS)
+    return { action: 'flush', reason: 'due' };
+  return { action: 'wait', at: input.flushAt };
+}

package/src/do/run-request.ts

@@ -1,39 +1,75 @@
 /**
  * What a run row stores so a later incarnation of the user object can
  * rebuild the attempt: the `TurnRequest` (minus attachments — they are in
- * the checkpointed first message) and the stream options the frame producer
- * needs. The browser tool catalogue and the AG-UI action schemas are NOT
- * stored: they live in the graph state (`browserTools` / `agActions`), which
- * a resumed attempt reads back from the checkpoint.
+ * the checkpointed first message), the client-declared tool surface of the
+ * turn (browser tools + AG-UI actions: the portal and agui plugins bind
+ * them at build time, so an attempt cannot recover them from anywhere
+ * else), and the stream options the frame producer needs.
  */
 import type { RunSummary, TurnRequest } from './contracts';
 import type { RunRecord } from './run-store';
+import type { TurnBody } from './turn-body';
 
-export interface StoredRunRequest {
+/** The client-declared surface of a turn, as the body carries it. */
+export type ClientSurfaceBody = Pick<TurnBody, 'tools' | 'agActions'>;
+
+export interface StoredRunRequest extends ClientSurfaceBody {
   turn: Omit<TurnRequest, 'attachments'> & {
     attachments?: TurnRequest['attachments'];
   };
   timezone?: string;
-  /** Names the client declared as AG-UI actions (rendered as `action_call`). */
-  agActionNames?: string[];
   stream?: boolean;
 }
 
 export function storedRunRequest(
   req: TurnRequest,
-  extra: Pick<StoredRunRequest, 'timezone' | 'agActionNames' | 'stream'> = {},
+  extra: Pick<
+    StoredRunRequest,
+    'timezone' | 'tools' | 'agActions' | 'stream'
+  > = {},
 ): StoredRunRequest {
   const { attachments, ...turn } = req;
   return {
     turn: { ...turn, ...(attachments?.length ? { attachments } : {}) },
     ...(extra.timezone ? { timezone: extra.timezone } : {}),
-    ...(extra.agActionNames?.length
-      ? { agActionNames: extra.agActionNames }
-      : {}),
+    ...(extra.tools?.length ? { tools: extra.tools } : {}),
+    ...(extra.agActions?.length ? { agActions: extra.agActions } : {}),
     ...(extra.stream !== undefined ? { stream: extra.stream } : {}),
   };
 }
 
+/** The surface as the graph state stores it (`browserTools` / `agActions`). */
+export interface ClientSurfaceState {
+  browserTools?: TurnBody['tools'];
+  agActions?: TurnBody['agActions'];
+}
+
+/**
+ * The client-declared surface of one attempt, by the Node agent-builder's
+ * rule: what the body carries, else what the thread's checkpoint holds.
+ *
+ * `state` feeds the agent build (the portal / agui plugins read it from
+ * `history.state`, so it must be complete). `input` is what the graph input
+ * writes back to the checkpoint: only what THIS body declared, so a turn
+ * without a catalogue (a resumed attempt, a Matrix turn, a task run) never
+ * erases the one the client sent earlier.
+ */
+export function clientSurfaceFor(
+  body: ClientSurfaceBody,
+  prior: ClientSurfaceState,
+): { state: Required<ClientSurfaceState>; input: ClientSurfaceState } {
+  return {
+    state: {
+      browserTools: body.tools ?? prior.browserTools ?? [],
+      agActions: body.agActions ?? prior.agActions ?? [],
+    },
+    input: {
+      ...(body.tools !== undefined ? { browserTools: body.tools } : {}),
+      ...(body.agActions !== undefined ? { agActions: body.agActions } : {}),
+    },
+  };
+}
+
 export function runSummaryOf(record: RunRecord): RunSummary {
   return {
     runId: record.runId,

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

@@ -156,6 +156,7 @@ import {
 import { turnRecursionLimit } from './turn-config';
 import { decideMatrixTurn, MatrixTurnLedger } from './matrix-turn-ledger';
 import { decideBootDirty } from './boot-dirty';
+import { decideFlush } from './flush-schedule';
 import { mirrorTxnId, RoomMirror } from './room-mirror';
 import { prefixSpeaker } from './speaker-prefix';
 import {
@@ -199,6 +200,7 @@ import {
 } from './run-store';
 import {
   runSummaryOf,
+  clientSurfaceFor,
   storedRunRequest,
   type StoredRunRequest,
 } from './run-request';
@@ -320,6 +322,15 @@ const TIER_PASS_INTERVAL_MS = 6 * 60 * 60_000;
  * silently stale.
  */
 const META_DIRTY = 'meta:dirty';
+/**
+ * When the dirty working copy is due to be uploaded. Armed by the first
+ * write after an upload (`FLUSH_DEBOUNCE_MS` later), replaced by the retry
+ * delay after a failed upload, cleared with the dirty mark. The alarm is
+ * shared with the realtime heartbeat, the durable-run keep-alive, task runs
+ * and compaction, so a wake alone never means "upload now" — the tick
+ * consults this deadline (`do/flush-schedule.ts`).
+ */
+const META_FLUSH_AT = 'meta:flushAt';
 const META_OWNER_ETAG = 'meta:ownerEtag';
 const META_LAST_FLUSH = 'meta:lastFlushAt';
 const META_LAST_CHECKSUM = 'meta:lastChecksum';
@@ -1083,9 +1094,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           console.warn(
             `[user-do] VFS migration write failed for ${userDid} — serving the legacy Matrix copy for now: ${err instanceof Error ? err.message : String(err)}`,
           );
-          // Sooner than the 24 h debounce `markDirty` armed: the system of
-          // record is still empty for this user.
-          this.requestAlarm(Date.now() + FLUSH_RETRY_DELAY_MS);
+          // The failed upload armed the 10-minute retry (`flushOnce`), well
+          // before the 24 h debounce `markDirty` set: the system of record
+          // is still empty for this user.
         }
       }
       await this.reconcileDirtyOnBoot(liveDb, userDid);
@@ -1278,6 +1289,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         META_OWNER_ETAG,
         META_LAST_CHECKSUM,
         META_LAST_FLUSH,
+        META_FLUSH_AT,
         META_UPLOADED_GEN,
         META_FLUSH_FAILURES,
         META_LAST_VACUUM,
@@ -1383,7 +1395,30 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     private markDirty(): void {
       this.dirty = true;
       void this.ctx.storage.put(META_DIRTY, true);
-      this.requestAlarm(Date.now() + FLUSH_DEBOUNCE_MS);
+      void this.armFlush(Date.now() + FLUSH_DEBOUNCE_MS);
+    }
+
+    /**
+     * Record the flush deadline and arm the alarm for it. An earlier
+     * deadline already on disk wins, so a burst of writes uploads once,
+     * `FLUSH_DEBOUNCE_MS` after the first of them, never later.
+     */
+    private async armFlush(at: number): Promise<void> {
+      const existing = await this.ctx.storage.get<number>(META_FLUSH_AT);
+      const deadline =
+        typeof existing === 'number' && existing <= at ? existing : at;
+      if (deadline !== existing)
+        await this.ctx.storage.put(META_FLUSH_AT, deadline);
+      this.requestAlarm(deadline);
+    }
+
+    /**
+     * After a failed upload: the next attempt is `at`, replacing the deadline
+     * that just came due (which would otherwise make every wake retry).
+     */
+    private async scheduleFlushRetry(at: number): Promise<void> {
+      await this.ctx.storage.put(META_FLUSH_AT, at);
+      this.requestAlarm(at);
     }
 
     /** Arm the object's single alarm no later than `at` (multiplexed). */
@@ -1481,15 +1516,35 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           deadlines.push(Math.max(nextRecovery, now + 1000));
       }
 
-      if (this.dirty && this.db) {
+      const lastAccess =
+        (await this.ctx.storage.get<number>(META_LAST_ACCESS)) ?? now;
+      const idle = now - lastAccess > IDLE_EVICT_MS;
+
+      // Owner-store flush: only when its own deadline is due, or the copy
+      // is about to be evicted below. A wake for anything else (a run's
+      // keep-alive, a heartbeat round that fell through, a compaction or
+      // tier re-arm) leaves a dirty copy alone — the upload is a full-file
+      // transfer and is meant to happen once a day, not once a turn.
+      const flush = decideFlush({
+        dirty: this.dirty && this.db !== null,
+        flushAt: await this.ctx.storage.get<number>(META_FLUSH_AT),
+        now,
+        idle,
+      });
+      if (flush.action === 'flush') {
         try {
           await this.flushToOwnerStore();
         } catch (err) {
           console.error(
             `[user-do] flush failed for ${this.userDid}: ${err instanceof Error ? err.message : String(err)}`,
           );
+          // `flushOnce` arms the retry on an upload failure; anything that
+          // failed before the upload gets the same retry window here.
+          await this.scheduleFlushRetry(now + FLUSH_RETRY_DELAY_MS);
           deadlines.push(now + FLUSH_RETRY_DELAY_MS);
         }
+      } else if (flush.action === 'wait') {
+        deadlines.push(Math.max(flush.at, now + 1000));
       }
 
       if (this.taskScheduler) {
@@ -1522,9 +1577,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         }
       }
 
-      const lastAccess =
-        (await this.ctx.storage.get<number>(META_LAST_ACCESS)) ?? now;
-
       // Free-page reclaim on a quiet object (policy in sqlite/vacuum-policy.ts):
       // runs after the flush above so the upload holds the pre-rebuild file,
       // and marks dirty so the smaller file goes up on the next tick.
@@ -1551,7 +1603,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // evict while tasks are scheduled: their runs ARE activity. The flush
       // above ran first; the wipe additionally verifies the upstream copy
       // matches the working copy, else the copy stays until it does.
-      const idle = now - lastAccess > IDLE_EVICT_MS;
       if (
         idle &&
         !this.dirty &&
@@ -2052,9 +2103,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         writeGeneration: db.writeGeneration,
       });
       if (decision === 'flagged') {
-        // The mark is on disk already (its flush alarm too); just adopt it.
+        // The mark is on disk already (its deadline too); adopt it and make
+        // sure the alarm is armed for that deadline.
         this.dirty = true;
-        this.requestAlarm(Date.now() + FLUSH_DEBOUNCE_MS);
+        void this.armFlush(Date.now() + FLUSH_DEBOUNCE_MS);
       } else if (decision === 'behind-upload') {
         console.log(
           `[user-do] working copy of ${userDid} is at generation ${db.writeGeneration}, last upload at ${String(got.get(META_UPLOADED_GEN))} — a turn ended without marking it; flushing`,
@@ -2431,6 +2483,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           const line = `[user-do] owner-store flush failed (${failures} in a row) for ${this.userDid} — working copy kept dirty, retrying in ${FLUSH_RETRY_DELAY_MS / 60_000} min: ${detail}`;
           if (failures >= FLUSH_FAILURES_ERROR_THRESHOLD) console.error(line);
           else console.warn(line);
+          await this.scheduleFlushRetry(Date.now() + FLUSH_RETRY_DELAY_MS);
           throw err;
         }
         await this.ctx.storage.put(META_OWNER_ETAG, saved.etag);
@@ -2510,18 +2563,22 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     }
 
     private async clearDirty(): Promise<void> {
-      // A write that landed while the snapshot was being uploaded already
-      // re-armed the alarm through `markDirty`; only clear when the file's
-      // generation still matches what was just recorded.
+      // A write that landed while the snapshot was being uploaded keeps the
+      // copy dirty; its upload is a full debounce away (the deadline the
+      // write found on disk was the one that just ran).
       const uploadedGen = await this.ctx.storage.get<number>(META_UPLOADED_GEN);
       if (
         this.db &&
         uploadedGen !== undefined &&
         uploadedGen !== this.db.writeGeneration
-      )
+      ) {
+        const at = Date.now() + FLUSH_DEBOUNCE_MS;
+        await this.ctx.storage.put(META_FLUSH_AT, at);
+        this.requestAlarm(at);
         return;
+      }
       this.dirty = false;
-      await this.ctx.storage.delete(META_DIRTY);
+      await this.ctx.storage.delete([META_DIRTY, META_FLUSH_AT]);
     }
 
     async resetWorkingCopy(): Promise<{ reloadedFromOwnerStore: boolean }> {
@@ -2650,6 +2707,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         pages: Math.ceil(fileBytes / 4096),
         ownerEtag: await this.ctx.storage.get<string>(META_OWNER_ETAG),
         lastFlushAt: await this.ctx.storage.get<number>(META_LAST_FLUSH),
+        nextFlushAt: await this.ctx.storage.get<number>(META_FLUSH_AT),
         dirty: this.dirty,
         flushInFlight: this.flushInFlight !== null,
         writeGeneration: db?.writeGeneration,
@@ -2954,7 +3012,6 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // (docs/plans/durable-runs.md). The response is one subscriber of the
       // run's buffer; the run itself outlives it.
       this.replayToRoom(req, body.message, 'user');
-      const agActionNames = (body.agActions ?? []).map((a) => a.name);
       const { live, queued } = await this.runs!.begin({
         runId: crypto.randomUUID(),
         sessionId,
@@ -2963,7 +3020,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         request: JSON.stringify(
           storedRunRequest(req, {
             timezone: body.timezone,
-            agActionNames,
+            tools: body.tools,
+            agActions: body.agActions,
             stream: true,
           }),
         ),
@@ -3081,6 +3139,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           message: req.message,
           timezone: stored.timezone ?? req.identity.timezone,
           model: req.model,
+          tools: stored.tools,
+          agActions: stored.agActions,
           ...(resumed ? {} : { attachments: req.attachments }),
         },
         {
@@ -3121,7 +3181,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           abortController: live.abort,
           mirror: (eventName, payload) =>
             this.events.emitToTaps(eventName, payload),
-          agActionNames: new Set(stored.agActionNames ?? []),
+          agActionNames: new Set((stored.agActions ?? []).map((a) => a.name)),
           byoProvider,
           toolOutputCapChars,
           messageIdOf: () => lastAiMessageId(capture),
@@ -3801,20 +3861,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const hostRoomTitle = opts.hooks?.getRoomTitle;
       const hostSafetyModel = opts.hooks?.safetyModel;
 
-      // A resumed attempt reads the client's tool surface back from the
-      // checkpointed state (the run row does not store the catalogue).
-      const priorSurface = priorState as {
-        browserTools?: TurnBody['tools'];
-        agActions?: TurnBody['agActions'];
-      };
-      const browserTools =
-        body.tools ??
-        (run.resumed ? priorSurface.browserTools : undefined) ??
-        [];
-      const agActions =
-        body.agActions ??
-        (run.resumed ? priorSurface.agActions : undefined) ??
-        [];
+      // The client-declared tool surface: this body's, else the thread's
+      // checkpointed one (run-request.ts).
+      const surface = clientSurfaceFor(body, priorState);
 
       // Write-ahead tool marks + the resume policy (tool-marks.ts). The
       // effect map is filled from the build below; the closure reads it at
@@ -3908,12 +3957,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           ...priorState,
           userPreferences,
           ...metadataBuildState(meta, priorMeta),
-          // The client-declared surface of THIS request: the portal and
-          // AG-UI plugins turn these into tools at build time
-          // (`getRequestTools` reads `history.state`), so they must be here
-          // and not only in the graph input.
-          browserTools,
-          agActions,
+          // The client-declared surface: the portal and AG-UI plugins turn
+          // these into tools at build time (`getRequestTools` reads
+          // `history.state`), so they must be here and not only in the
+          // graph input.
+          ...surface.state,
         },
         checkpointer: saver,
         abortSignal: abortController.signal,
@@ -3979,8 +4027,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         config: { did: req.identity.userDid },
         client: req.client,
         ...metadataGraphInput(meta, priorMeta),
-        browserTools,
-        agActions,
+        ...surface.input,
       };
       // LangSmith: metadata is attached unconditionally (inert without a
       // tracer); the explicit tracer only when this turn is traced (global