@ixo/oracle-runtime-workers 0.11.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.11.1",
+  "version": "0.13.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": {
@@ -33,7 +33,7 @@
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
     "@ixo/editor": "6.0.1",
-    "@ixo/matrix-bot-workers-sdk": "0.4.0",
+    "@ixo/matrix-bot-workers-sdk": "0.7.0",
     "@ixo/matrix-crdt": "^1.2.5",
     "@langchain/core": "1.1.48",
     "@langchain/langgraph": "1.3.2",

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

@@ -73,6 +73,34 @@ export interface OracleWorkerEnv {
   MATRIX_HOT_ROOMS?: string;
   /** Cap on events replayed per room after a restart (SDK default 0 = unbounded). */
   MATRIX_BACKFILL_MAX_EVENTS?: string;
+  /**
+   * Gateway memory guards (`@ixo/matrix-bot-workers-sdk` 0.5+): events per
+   * room per `/sync` batch (default 30), the largest `/sync` response held
+   * in memory (default 16 MiB; over it the batch is re-requested at timeline
+   * limit 1 and the rooms catch up through `/messages`), events per catch-up
+   * page (default 100), the largest catch-up page (default 10 MiB; a bigger
+   * one is fetched again smaller) and the largest ciphertext the bot will
+   * decrypt (default 0 = no cap). A cap of `0` switches that guard off.
+   */
+  MATRIX_SYNC_TIMELINE_LIMIT?: string;
+  MATRIX_SYNC_BYTES_CAP?: string;
+  MATRIX_CATCHUP_PAGE_SIZE?: string;
+  MATRIX_PAGE_BYTES_CAP?: string;
+  MATRIX_MAX_DECRYPT_BYTES?: string;
+  /**
+   * `true` restores every room key the account's key backup holds on a
+   * device's first start (SDK 0.6+), capped at `..._MAX_KEYS` (default
+   * 5,000; a larger backup is skipped and keys stay on demand). Off by
+   * default: the gateway reads keys from the backup one session at a time.
+   */
+  MATRIX_BACKUP_BULK_RESTORE?: string;
+  MATRIX_BACKUP_BULK_RESTORE_MAX_KEYS?: string;
+  /**
+   * Keep-alive fuse (SDK 0.7+): while the gateway object works, its alarm is
+   * re-armed this far ahead so a host drain brings it back within the fuse
+   * (default 10 s, floor 2 s, `0` = off).
+   */
+  MATRIX_KEEPALIVE_FUSE_MS?: string;
 
   // --- storage ------------------------------------------------------------
   /**

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

@@ -200,6 +200,7 @@ import {
 } from './run-store';
 import {
   runSummaryOf,
+  clientSurfaceFor,
   storedRunRequest,
   type StoredRunRequest,
 } from './run-request';
@@ -3011,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,
@@ -3020,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,
           }),
         ),
@@ -3138,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 }),
         },
         {
@@ -3178,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),
@@ -3858,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
@@ -3965,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,
@@ -4036,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

package/src/matrix/gateway-do.ts

@@ -310,6 +310,23 @@ export class MatrixGatewayDO
         env.MATRIX_RECYCLE_AFTER_SENDS ?? String(DEFAULT_RECYCLE_AFTER_SENDS),
       MATRIX_HOT_ROOMS: env.MATRIX_HOT_ROOMS,
       MATRIX_BACKFILL_MAX_EVENTS: env.MATRIX_BACKFILL_MAX_EVENTS,
+      // Memory guards (SDK 0.5+): byte-capped /sync and catch-up pages and
+      // an optional ciphertext cap on decryption. Unset = the SDK defaults.
+      MATRIX_SYNC_TIMELINE_LIMIT: env.MATRIX_SYNC_TIMELINE_LIMIT,
+      MATRIX_SYNC_BYTES_CAP: env.MATRIX_SYNC_BYTES_CAP,
+      MATRIX_CATCHUP_PAGE_SIZE: env.MATRIX_CATCHUP_PAGE_SIZE,
+      MATRIX_PAGE_BYTES_CAP: env.MATRIX_PAGE_BYTES_CAP,
+      MATRIX_MAX_DECRYPT_BYTES: env.MATRIX_MAX_DECRYPT_BYTES,
+      // Opt-in bulk restore of the key backup on a device's first start
+      // (SDK 0.6+); off by default — the gateway fetches room keys from the
+      // backup on demand, one session at a time.
+      MATRIX_BACKUP_BULK_RESTORE: env.MATRIX_BACKUP_BULK_RESTORE,
+      MATRIX_BACKUP_BULK_RESTORE_MAX_KEYS:
+        env.MATRIX_BACKUP_BULK_RESTORE_MAX_KEYS,
+      // Keep-alive fuse (SDK 0.7+): the alarm is re-armed a few seconds
+      // ahead while the object works, so a host drain brings it back within
+      // the fuse instead of at the next cycle.
+      MATRIX_KEEPALIVE_FUSE_MS: env.MATRIX_KEEPALIVE_FUSE_MS,
       LOG_LEVEL: env.LOG_LEVEL,
     });
     return {
@@ -685,14 +702,13 @@ export class MatrixGatewayDO
   }
 
   /**
-   * Every start of this instance — first request, keep-alive alarm, RPC —
-   * goes through here. A start that actually brought the bot up is the
+   * After every successful start of this instance — a request, the
+   * keep-alive alarm bringing it back after a reset, a device rotation
+   * (the SDK's `onStarted` hook, detached from the caller). That is the
    * moment to re-dispatch the turns a previous incarnation left unfinished.
    */
-  override async ensureStarted(): Promise<StartResult> {
-    const result = await super.ensureStarted();
-    if (result.started) this.scheduleInboxReplay();
-    return result;
+  protected override async onStarted(_result: StartResult): Promise<void> {
+    this.scheduleInboxReplay();
   }
 
   private scheduleInboxReplay(): void {