@ixo/oracle-runtime-workers 0.21.1 → 0.22.0

package/README.md

@@ -90,6 +90,7 @@ Every variable, binding and migration is explained in
 | `GET /matrix/status`, `POST /matrix/start`            | Gateway status and start                              |
 | `POST/GET /sessions`, `POST/GET /messages/:id`        | The chat API                                          |
 | `GET /runs/:runId`, `GET /sessions/:id/messages`      | Re-join a durable run; one page of a transcript       |
+| `GET /sessions/:id/run`, `GET /runs/active`           | A session's active run; every active run of the user  |
 | `/delegation`, `/models`, `/socket.io/`, `/byo-llm/*` | Delegation, models, realtime channel, BYO LLM         |
 | `POST /channels/turn`                                 | IXO Channels ingress; refusals carry a `code`         |
 | `POST /messages/:sessionId/:messageId/feedback`       | Anonymous feedback on a reply (when configured)       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.21.1",
+  "version": "0.22.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/env.ts

@@ -63,6 +63,10 @@ export const LLM_STREAM_RETRIES_DEFAULT = 1;
 export const LLM_STREAM_RETRIES_MAX = 5;
 /** The turn's wall-clock deadline when `TURN_TIMEOUT_MS` is unset. */
 export const TURN_TIMEOUT_MS_DEFAULT = 600_000;
+/** How long a frontend call waits unsent for a browser when `FRONTEND_PARK_TIMEOUT_MS` is unset. */
+export const FRONTEND_PARK_TIMEOUT_MS_DEFAULT = 300_000;
+/** The longest delay `setTimeout` honours (2^31 − 1 ms); a larger one fires at once. */
+export const MAX_TIMER_MS = 2_147_483_647;
 
 /** An https URL, or http on localhost / 127.0.0.1 (local harness). */
 const secureUrlSchema = z.string().refine((raw) => isSecureUrl(raw), {
@@ -220,6 +224,20 @@ export const baseEnvSchema = z.object({
     .int()
     .positive()
     .default(2_000),
+  /**
+   * How long a browser tool / AG-UI call waits, unsent, for a socket of its
+   * session that can run it (ms) before it fails as never sent. The turn's
+   * own deadline (`TURN_TIMEOUT_MS`) still ends it first when sooner. At
+   * most `MAX_TIMER_MS` (a timer holds it). The user object reads it
+   * through this field (`frontendParkTimeoutMs`,
+   * src/realtime/realtime-endpoint.ts).
+   */
+  FRONTEND_PARK_TIMEOUT_MS: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(MAX_TIMER_MS)
+    .default(FRONTEND_PARK_TIMEOUT_MS_DEFAULT),
 
   // --- decisions ----------------------------------------------------------
   // Bounded semantic Decision provider (`DECISION_PROVIDER`, `DECISION_MODEL`,

package/src/core/index.ts

@@ -802,5 +802,11 @@ export {
 export type { TurnLimits, TurnUsage } from './turn-budget';
 export { budgetedLlm } from './budgeted-llm';
 export type { BudgetedLlm, BudgetedLlmOptions } from './budgeted-llm';
-export { ToolScheduler } from './tool-scheduler';
-export type { ToolLane, ToolSchedulerOptions } from './tool-scheduler';
+export { sessionLaneKey, ToolScheduler } from './tool-scheduler';
+export type {
+  LaneOccupancy,
+  SessionToolLane,
+  ToolLane,
+  ToolSchedulerOptions,
+  ToolSchedulerSnapshot,
+} from './tool-scheduler';

package/src/core/main-agent-types.ts

@@ -218,6 +218,14 @@ export interface MainAgentBuildResult {
    * turn, `write` never does). Declared by the plugin, else by name.
    */
   toolEffects: Map<string, 'read' | 'write'>;
+  /**
+   * The plugin tools the turn can run that act in the user's browser
+   * (`PluginTool.surface`), a sub-agent's inner tools included: scheduled
+   * in their session's `frontend` lane. A tool absent from the map (meta,
+   * domain and dispatch tools, every server-side tool, and a name two tools
+   * disagree on) is scheduled by its effect.
+   */
+  toolSurfaces: Map<string, 'frontend'>;
   /** Names of the sub-agent dispatch tools (`call_*_agent`): scheduled in their own lane. */
   subAgentToolNames: ReadonlySet<string>;
   /**

package/src/core/main-agent.ts

@@ -235,6 +235,7 @@ export async function createMainAgent(
       systemPrompt,
       boundToolNames: [],
       toolEffects: new Map(),
+      toolSurfaces: new Map(),
       subAgentToolNames: new Set(),
       context: { user: requestCtx.user, session: requestCtx.session },
     };
@@ -556,6 +557,28 @@ export async function createMainAgent(
   for (const { tool } of allTools)
     toolEffects.set(tool.name, toolEffectOf(tool));
   for (const t of subAgentTools) toolEffects.set(t.name, 'write');
+  // The plugin tools that act in the user's browser (`PluginTool.surface`),
+  // a sub-agent's inner tools included (the execution middleware schedules
+  // them too, by name): scheduled in their session's frontend lane. A name
+  // is listed only when every tool of that name declares it; meta, domain
+  // and dispatch tools never are.
+  const surfaceOf = new Map<string, PluginTool['surface']>();
+  const declareSurface = (tool: PluginTool): void => {
+    const known = surfaceOf.get(tool.name);
+    surfaceOf.set(
+      tool.name,
+      surfaceOf.has(tool.name) && known !== tool.surface
+        ? undefined
+        : tool.surface,
+    );
+  };
+  for (const { tool } of [...turnTools, ...allTools]) declareSurface(tool);
+  for (const { subAgent } of subAgentEntries)
+    for (const tool of Array.isArray(subAgent.tools) ? subAgent.tools : [])
+      declareSurface(tool);
+  const toolSurfaces = new Map<string, 'frontend'>();
+  for (const [name, surface] of surfaceOf)
+    if (surface === 'frontend') toolSurfaces.set(name, surface);
   // Tools whose identical call is a new action (a browser step), which the
   // repetition guard caps like a read whatever their effect.
   const repeatableToolNames = new Set(
@@ -909,6 +932,7 @@ export async function createMainAgent(
     systemPrompt,
     boundToolNames: tools.map((t) => t.name),
     toolEffects,
+    toolSurfaces,
     subAgentToolNames: new Set(subAgentTools.map((t) => t.name)),
     context: runConfig.context,
     ...(domain

package/src/core/middlewares/tool-execution.ts

@@ -3,9 +3,11 @@
  * run: charged to the turn's budget, scheduled in its lane, and — for a
  * write — claimed in the run ledger for as long as its outcome is unknown.
  *
- * The claim is a fingerprint of the tool name and its canonical arguments,
- * recorded before the write starts. A returned result (success or a
- * reported failure) releases it; a failure that says nothing about whether
+ * The claim is a fingerprint of the tool name and its canonical arguments
+ * (and, for a frontend write, its session), recorded before the write
+ * starts; a write is claimed by its effect, whichever lane it runs in. A
+ * returned result (success or a reported failure) releases it, and so does
+ * a frontend call that was never sent; a failure that says nothing about whether
  * the write happened — abort, deadline, a dropped connection, a 5xx —
  * leaves it in place, whether the tool threw it or caught it and returned
  * it as an error result (many plugin tools and adapters never throw to the
@@ -30,6 +32,7 @@ import { type AgentMiddleware, createMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
 import type { ToolLane, ToolScheduler } from '../tool-scheduler';
 import { findProviderStall } from '../../llm/stream-liveness';
+import { isFrontendCallNotSent } from '../../realtime/frontend-call-registry';
 import { isHarnessLimitError, type TurnBudget } from '../turn-budget';
 import { NOOP_LOGGER } from '../utils';
 
@@ -51,8 +54,18 @@ export interface WriteClaimStore {
 export interface ToolExecutionOptions {
   budget: TurnBudget;
   scheduler: ToolScheduler;
-  /** Lane of a tool by name (`read`, `write`, or `subagent` for a dispatch). */
+  /**
+   * Lane of a tool by name: `read` / `write` (user-wide, by effect),
+   * `frontend` for a tool acting in the user's browser
+   * (`PluginTool.surface`), `subagent` for a dispatch. The two per-session
+   * lanes are keyed by `sessionId` below.
+   */
   laneOf: (toolName: string) => ToolLane;
+  /**
+   * Effect of a tool by name. A `write` is claimed in the ledger whatever
+   * its lane (a frontend write too); a sub-agent dispatch never is.
+   */
+  effectOf: (toolName: string) => 'read' | 'write';
   runId: string;
   sessionId: string;
   /** Omitted → writes are scheduled and charged but not claimed (stateless builds, tests). */
@@ -77,12 +90,21 @@ export function canonicalArguments(value: unknown): string {
   return JSON.stringify(value) ?? 'null';
 }
 
-/** SHA-256 of `name:args`, hex — the write's fingerprint in the ledger. */
+/**
+ * SHA-256 of `name:args`, hex — the write's fingerprint in the ledger. With
+ * `sessionId` (a frontend write: it acts in that session's own browser, so
+ * the same call in another chat is a different action) the session is part
+ * of it: `name@<sessionId>:args`.
+ */
 export async function operationKey(
   name: string,
   args: unknown,
+  sessionId?: string,
 ): Promise<string> {
-  const bytes = new TextEncoder().encode(`${name}:${canonicalArguments(args)}`);
+  const scope = sessionId === undefined ? '' : `@${sessionId}`;
+  const bytes = new TextEncoder().encode(
+    `${name}${scope}:${canonicalArguments(args)}`,
+  );
   const digest = await crypto.subtle.digest('SHA-256', bytes);
   return Array.from(new Uint8Array(digest), (b) =>
     b.toString(16).padStart(2, '0'),
@@ -141,12 +163,16 @@ const isServerStatus = (status: unknown): boolean =>
 /**
  * `true` when a thrown error says nothing about whether the tool's side
  * effect happened: the turn was aborted or hit its deadline, the transport
- * failed, or the service answered with a server error.
+ * failed, or the service answered with a server error. A frontend call that
+ * was never sent (`FrontendCallNotSentError`: parked until the turn aborted
+ * or its park deadline passed) is a known outcome even on an aborted turn:
+ * no browser saw it.
  */
 export function isUncertainOutcome(
   error: unknown,
   signal?: AbortSignal,
 ): boolean {
+  if (isFrontendCallNotSent(error)) return false;
   if (signal?.aborted) return true;
   if (isHarnessLimitError(error)) return true;
   // A tool whose own model call stalled (stream-liveness.ts) stopped at an
@@ -267,6 +293,10 @@ export function createToolExecutionMiddleware(
       const { toolCall } = request;
       const toolName = toolCall.name;
       const lane = options.laneOf(toolName);
+      // Claimed by effect, whatever the lane: a frontend write too. A
+      // dispatch is never fingerprinted (its inner writes are, by name).
+      const claimed =
+        lane !== 'subagent' && options.effectOf(toolName) === 'write';
       const callId = toolCall.id ?? '';
       const attempt = (attempts.get(callId) ?? 0) + 1;
       attempts.set(callId, attempt);
@@ -290,51 +320,62 @@ export function createToolExecutionMiddleware(
         );
         return output;
       };
-      return scheduler.run(lane, options.signal, async () => {
-        budget.reserveTool(options.signal);
-        if (lane !== 'write' || !claims) return run();
-        const fingerprint = await operationKey(toolName, toolCall.args);
-        const claim = await claims.claimWrite({
-          fingerprint,
-          toolName,
-          runId: options.runId,
-          sessionId: options.sessionId,
-        });
-        if (claim.status === 'blocked') {
-          logger.warn(
-            `[tool-execution] ${toolName}: an identical write since ${claim.since} has no known outcome; not run again`,
+      return scheduler.run(
+        lane,
+        options.signal,
+        async () => {
+          budget.reserveTool(options.signal);
+          if (!claimed || !claims) return run();
+          // The ledger is user-wide; a frontend write's fingerprint names its
+          // session, so the same browser action in two chats never collides.
+          const fingerprint = await operationKey(
+            toolName,
+            toolCall.args,
+            lane === 'frontend' ? options.sessionId : undefined,
           );
-          return new ToolMessage({
-            tool_call_id: toolCall.id ?? '',
-            name: toolName,
-            content: uncertainWriteToolResult(toolName),
-            status: 'error',
+          const claim = await claims.claimWrite({
+            fingerprint,
+            toolName,
+            runId: options.runId,
+            sessionId: options.sessionId,
           });
-        }
-        try {
-          const output = await run();
-          const uncertain = uncertainResultReason(output);
-          if (uncertain !== null) {
+          if (claim.status === 'blocked') {
             logger.warn(
-              `[tool-execution] ${toolName}: returned a failure that leaves its outcome unknown (${uncertain}); its claim stays in the ledger`,
+              `[tool-execution] ${toolName}: an identical write since ${claim.since} has no known outcome; not run again`,
             );
-          } else {
-            await claims.releaseWrite(fingerprint, options.runId);
+            return new ToolMessage({
+              tool_call_id: toolCall.id ?? '',
+              name: toolName,
+              content: uncertainWriteToolResult(toolName),
+              status: 'error',
+            });
           }
-          return output;
-        } catch (error) {
-          if (isUncertainOutcome(error, options.signal)) {
-            logger.warn(
-              `[tool-execution] ${toolName}: outcome unknown (${error instanceof Error ? error.message.split('\n')[0] : String(error)}); its claim stays in the ledger`,
-            );
-          } else {
-            await claims
-              .releaseWrite(fingerprint, options.runId)
-              .catch(() => undefined);
+          try {
+            const output = await run();
+            const uncertain = uncertainResultReason(output);
+            if (uncertain !== null) {
+              logger.warn(
+                `[tool-execution] ${toolName}: returned a failure that leaves its outcome unknown (${uncertain}); its claim stays in the ledger`,
+              );
+            } else {
+              await claims.releaseWrite(fingerprint, options.runId);
+            }
+            return output;
+          } catch (error) {
+            if (isUncertainOutcome(error, options.signal)) {
+              logger.warn(
+                `[tool-execution] ${toolName}: outcome unknown (${error instanceof Error ? error.message.split('\n')[0] : String(error)}); its claim stays in the ledger`,
+              );
+            } else {
+              await claims
+                .releaseWrite(fingerprint, options.runId)
+                .catch(() => undefined);
+            }
+            throw error;
           }
-          throw error;
-        }
-      });
+        },
+        options.sessionId,
+      );
     },
   });
 }

package/src/core/middlewares/tool-marks.ts

@@ -12,6 +12,11 @@
  *     gets a synthetic result saying the outcome is unknown, so it can tell
  *     the user or verify with a read;
  *   - a started, unfinished **read** call runs again (it has no effect);
+ *   - a started, unfinished **frontend** call (`PluginTool.surface`) that
+ *     was never sent — it was parked waiting for a browser socket when the
+ *     object restarted, so no browser saw it — runs again whatever its
+ *     effect. Once sent (`markSent`, recorded by the frontend bridge when a
+ *     socket receives it) it follows the read / write rules above;
  *   - a call that already finished is not executed again either (its result
  *     is in the checkpoint's pending writes; reaching here means LangGraph
  *     could not replay it) — writes get the unknown-outcome result, reads run.
@@ -41,6 +46,8 @@ export interface ToolMarkStore {
     effect: ToolEffect;
   }): Promise<ToolMark | undefined>;
   bumpMark(runId: string, toolCallId: string): Promise<void>;
+  /** The call was handed to its executor outside the object (a browser socket). */
+  markSent(runId: string, toolCallId: string): Promise<void>;
   finishMark(
     runId: string,
     toolCallId: string,
@@ -53,6 +60,12 @@ export interface ToolMarksOptions {
   store: ToolMarkStore;
   /** The effect of a tool by name; unknown tools are writes (see `toolEffectOf`). */
   effectOf: (toolName: string) => ToolEffect;
+  /**
+   * `frontend` for a tool that runs in the user's browser
+   * (`PluginTool.surface`); such a call that was never sent before a restart
+   * runs again whatever its effect. Omitted → no tool is a frontend tool.
+   */
+  surfaceOf?: (toolName: string) => 'frontend' | undefined;
   /**
    * The reply text the user already received before the run was cut off.
    * Set only on a resumed attempt; consumed by the first model call.
@@ -84,18 +97,32 @@ export function continuationNote(partialText: string): string {
   );
 }
 
-const READ_PREFIXES = [
-  'list_',
-  'get_',
-  'search_',
-  'read_',
-  'preview_',
-  'describe_',
-  'check_',
-  'explain_',
-  'validate_',
-  'view_',
+/**
+ * Verbs a read-only tool name starts with, in either convention: snake case
+ * (`get_entity`) or camel case (`getEntity`, as browser tools are named).
+ */
+const READ_VERBS = [
+  'list',
+  'get',
+  'find',
+  'search',
+  'read',
+  'preview',
+  'describe',
+  'check',
+  'explain',
+  'validate',
+  'view',
 ];
+
+function startsWithReadVerb(name: string): boolean {
+  for (const verb of READ_VERBS) {
+    if (!name.startsWith(verb)) continue;
+    const next = name.charAt(verb.length);
+    if (next === '_' || (next >= 'A' && next <= 'Z')) return true;
+  }
+  return false;
+}
 const READ_NAMES = new Set([
   'requirements',
   'flow_status',
@@ -125,9 +152,7 @@ export function toolEffectOf(tool: {
     ? tool.name.slice(tool.name.lastIndexOf('__') + 2)
     : tool.name;
   if (READ_NAMES.has(bare)) return 'read';
-  for (const prefix of READ_PREFIXES)
-    if (bare.startsWith(prefix)) return 'read';
-  return 'write';
+  return startsWithReadVerb(bare) ? 'read' : 'write';
 }
 
 /** Whether a tool call's output is an error result (`ToolMessage` status `error`). */
@@ -170,7 +195,16 @@ export function createToolMarksMiddleware(
         effect,
       });
       if (existing) {
-        if (effect === 'write') {
+        const neverSent =
+          !existing.doneAt &&
+          existing.sentAt === null &&
+          options.surfaceOf?.(toolName) === 'frontend';
+        if (neverSent) {
+          logger.log(
+            `[tool-marks] ${toolName} (${toolCallId}) was parked and never sent to a browser in an earlier attempt of run ${options.runId}; running it again`,
+          );
+          await options.store.bumpMark(options.runId, toolCallId);
+        } else if (effect === 'write') {
           logger.warn(
             `[tool-marks] ${toolName} (${toolCallId}) was ${existing.doneAt ? 'already executed' : 'interrupted mid-execution'} in an earlier attempt of run ${options.runId}; not run again`,
           );
@@ -185,11 +219,12 @@ export function createToolMarksMiddleware(
             content: unknownOutcomeToolResult(toolName),
             status: 'error',
           });
+        } else {
+          logger.log(
+            `[tool-marks] ${toolName} (${toolCallId}) is read-only; running it again after the interruption`,
+          );
+          await options.store.bumpMark(options.runId, toolCallId);
         }
-        logger.log(
-          `[tool-marks] ${toolName} (${toolCallId}) is read-only; running it again after the interruption`,
-        );
-        await options.store.bumpMark(options.runId, toolCallId);
       }
       try {
         const output = await handler(request);

package/src/core/runtime-context.ts

@@ -202,6 +202,12 @@ export interface AmbientServices {
   onTurnEnd?: (dispose: () => void | Promise<void>) => void;
   /** Host keep-alive for un-awaited work (`ctx.waitUntil` on Workers). */
   background?: (work: Promise<unknown>) => void;
+  /**
+   * Records that the tool call `toolCallId` of this turn left the object
+   * (`ctx.markDispatched`). Set per turn by a host that keeps write-ahead
+   * tool marks.
+   */
+  markDispatched?: (toolCallId: string) => void;
 }
 
 // ── Scoped emitter ──────────────────────────────────────────────────────────
@@ -434,6 +440,8 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
   };
 
   const delegation = user.ucanDelegation;
+  const toolCallId = runConfig.toolCall?.id;
+  const { markDispatched } = ambient;
 
   const ctx: RuntimeContext<TConfig> = {
     user,
@@ -527,7 +535,10 @@ export function buildRuntimeContext<TConfig = MergedConfig>(
     ...(ambient.onTurnEnd ? { onTurnEnd: ambient.onTurnEnd } : {}),
     ...(ambient.background ? { background: ambient.background } : {}),
     shared: EMPTY_SHARED,
-    ...(runConfig.toolCall?.id ? { toolCallId: runConfig.toolCall.id } : {}),
+    ...(toolCallId ? { toolCallId } : {}),
+    ...(toolCallId && markDispatched
+      ? { markDispatched: () => markDispatched(toolCallId) }
+      : {}),
   };
   if (sharedFactory) {
     ctx.shared = sharedFactory(ctx);
@@ -730,5 +741,8 @@ export function createNoopAmbient(
     logger: overrides.logger ?? NOOP_LOGGER,
     ...(overrides.decisions ? { decisions: overrides.decisions } : {}),
     ...(overrides.kv ? { kv: overrides.kv } : {}),
+    ...(overrides.markDispatched
+      ? { markDispatched: overrides.markDispatched }
+      : {}),
   };
 }

package/src/core/state.ts

@@ -21,6 +21,8 @@ export interface BrowserToolCall {
   name: string;
   description: string;
   schema: Record<string, unknown>;
+  /** The tool's effect as the client declares it (`'read'` / `'write'`). */
+  effect?: 'read' | 'write';
 }
 
 /** AG-UI action descriptor injected per request from the client. */