@ixo/oracle-runtime-workers 0.21.2 → 0.22.0

package/src/plugins/agui/agui.plugin.ts

@@ -98,11 +98,8 @@ export function buildActionTool(action: AgAction): PluginTool | null {
           `AG-UI action ${action.name} needs the realtime channel, which this host does not provide.`,
         );
       }
-      if (!frontend.hasClient(sessionId)) {
-        throw new Error(
-          `No browser is connected to session ${sessionId}, so AG-UI action ${action.name} cannot run — the client must open the realtime (socket.io) channel for this session first.`,
-        );
-      }
+      // No browser of the session connected yet: the bridge parks the call
+      // until one joins (or its park deadline / the turn's abort ends it).
       // The bridge makes every invocation unique (`ag_<requestId>:<uuid>`).
       let invocationId: string | undefined;
       const result = await frontend.callAgAction({
@@ -112,6 +109,7 @@ export function buildActionTool(action: AgAction): PluginTool | null {
         args: parseArgs(input),
         timeoutMs: AG_ACTION_TIMEOUT_MS,
         signal: ctx.abortSignal,
+        ...(ctx.markDispatched ? { onDispatched: ctx.markDispatched } : {}),
         onInvocation: (id) => {
           invocationId = id;
         },
@@ -125,6 +123,10 @@ export function buildActionTool(action: AgAction): PluginTool | null {
       schema,
       // A UI action on the user's screen: running it again is a new action.
       repeatable: true,
+      // It runs on this session's AG-UI surface in the browser: scheduled in
+      // the session's frontend lane, so a parked call holds no slot another
+      // chat needs.
+      surface: 'frontend',
     },
   );
 }

package/src/plugins/ixo-transaction/wallet-signing.ts

@@ -65,7 +65,10 @@ type WalletChannel =
 
 /**
  * The turn's way to the wallet: a session with a realtime channel and a
- * Portal browser connected to it.
+ * Portal tab that can run the action right now (`canDispatch`: a foreground
+ * socket; a background executor never runs an AG-UI action). A signing
+ * request is never parked: without such a tab it is refused at once, so it
+ * never waits minutes in the user-wide write lane for a tab to open.
  */
 function walletChannel(ctx: RuntimeContext): WalletChannel {
   const sessionId = ctx.session.id;
@@ -77,7 +80,7 @@ function walletChannel(ctx: RuntimeContext): WalletChannel {
         'Wallet signing needs a Portal session with a realtime connection, which this conversation does not have.',
     };
   }
-  if (!frontend.hasClient(sessionId)) {
+  if (!frontend.canDispatch(sessionId, 'agui', SIGN_TRANSACTION_ACTION_NAME)) {
     return {
       ok: false,
       reason:

package/src/plugins/portal/declared-tools.ts

@@ -25,6 +25,18 @@ export interface DeclaredTool {
   schema: Record<string, unknown>;
 }
 
+/**
+ * The effect a client declares for one of its tools (`effect` on a browser
+ * tool declaration): exactly `'read'` or `'write'`. Any other value is
+ * treated as no declaration — the entry itself is kept, and the runtime's
+ * own classification applies.
+ */
+export function declaredToolEffect(
+  value: unknown,
+): 'read' | 'write' | undefined {
+  return value === 'read' || value === 'write' ? value : undefined;
+}
+
 export interface DroppedDeclaration {
   name: string;
   reason: string;

package/src/plugins/portal/portal.plugin.ts

@@ -24,7 +24,11 @@ import type {
   RuntimeContext,
 } from '../../plugin-api/types';
 import { logFrontendAction } from './action-log';
-import { describeDropped, sanitizeDeclaredTools } from './declared-tools';
+import {
+  declaredToolEffect,
+  describeDropped,
+  sanitizeDeclaredTools,
+} from './declared-tools';
 
 const manifest: PluginManifest = {
   title: 'Portal',
@@ -79,6 +83,7 @@ const BROWSER_TOOL_SHAPE = z.object({
   name: z.string(),
   description: z.string(),
   schema: z.record(z.string(), z.unknown()),
+  effect: z.unknown().optional(),
 });
 
 const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
@@ -92,7 +97,9 @@ export function parseBrowserTools(value: unknown): BrowserToolCall[] {
     const parsed = BROWSER_TOOL_SHAPE.safeParse(entry);
     if (!parsed.success || names.has(parsed.data.name)) continue;
     names.add(parsed.data.name);
-    out.push(parsed.data);
+    const { effect: rawEffect, ...declaration } = parsed.data;
+    const effect = declaredToolEffect(rawEffect);
+    out.push(effect ? { ...declaration, effect } : declaration);
   }
   return out;
 }
@@ -170,11 +177,8 @@ export function buildBrowserTool(
           `Browser tool ${descriptor.name} needs the realtime channel, which this host does not provide.`,
         );
       }
-      if (!frontend.hasClient(sessionId)) {
-        throw new Error(
-          `No browser is connected to session ${sessionId}, so browser tool ${descriptor.name} cannot run — the client must open the realtime (socket.io) channel for this session first.`,
-        );
-      }
+      // No browser of the session connected yet: the bridge parks the call
+      // until one joins (or its park deadline / the turn's abort ends it).
       const args = withRuntimeSuppliedArgs(
         parseArgs(input),
         descriptor,
@@ -189,6 +193,7 @@ export function buildBrowserTool(
         args,
         timeoutMs: browserToolTimeoutMs(descriptor.name),
         signal: ctx.abortSignal,
+        ...(ctx.markDispatched ? { onDispatched: ctx.markDispatched } : {}),
         onInvocation: (id) => {
           invocationId = id;
         },
@@ -202,9 +207,18 @@ export function buildBrowserTool(
       schema,
       // A browser step (scroll, page, click) repeated is a new step.
       repeatable: !HUMAN_DECISION_TOOLS.has(descriptor.name),
+      // It runs in this session's browser tab: scheduled in the session's
+      // frontend lane, so a parked call (or a question to the user) holds
+      // no slot another chat needs.
+      surface: 'frontend',
+      // A question to the user is a write whatever the client declares:
+      // it is never asked twice after a restart once it was sent. Any
+      // other tool keeps the effect its declaration names, if any.
       ...(HUMAN_DECISION_TOOLS.has(descriptor.name)
         ? { effect: 'write' as const }
-        : {}),
+        : descriptor.effect
+          ? { effect: descriptor.effect }
+          : {}),
     },
   );
 }

package/src/realtime/frontend-call-registry.ts

@@ -10,11 +10,16 @@
  *     arriving on that socket — same engine.io sid, same session, same
  *     authenticated DID — settles it. Another tab of the same session, a
  *     reconnected tab (a new sid) or another session cannot;
+ *   - until it is sent an invocation is parked: its clock is the park
+ *     deadline, and a park deadline that passes — or the turn's abort —
+ *     rejects it as never sent (`FrontendCallNotSentError`, a definite
+ *     failure: no browser saw it). `dispatched` restarts the clock with the
+ *     call's own deadline;
  *   - a settled invocation is remembered (bounded by count and age), so a
  *     replayed or late result is recognised and rejected as such;
- *   - pending invocations are never evicted to make room; a full table
- *     refuses new calls instead;
- *   - an invocation whose answer cannot arrive any more — its deadline
+ *   - pending invocations — parked ones included — are never evicted to
+ *     make room; a full table refuses new calls instead;
+ *   - a sent invocation whose answer cannot arrive any more — its deadline
  *     passed, or its socket went — resolves with `FRONTEND_OUTCOME_UNKNOWN`:
  *     the browser may have performed the write, so it is neither a success
  *     nor a failure, and it is never sent again.
@@ -27,10 +32,12 @@
  *
  * Purely in-memory, which is exact on Workers: a pending call holds a timer,
  * so its object cannot hibernate before the call ends, and an object restart
- * ends the turn that made it (a resumed durable run does not re-run a write
- * that had started — see tool-marks). Finished-call records are lost when
- * the object hibernates; a result for a forgotten id is then rejected as
- * never issued, which is the same outcome.
+ * ends the turn that made it. What a resumed durable run does with the call
+ * is the tool marks' policy: `onDispatched` lets the caller record the
+ * moment the call left the object, so a call still parked at the restart
+ * (never sent) is issued again and a sent write is not (see tool-marks).
+ * Finished-call records are lost when the object hibernates; a result for a
+ * forgotten id is then rejected as never issued, which is the same outcome.
  */
 import {
   frontendOutcomeUnknown,
@@ -79,15 +86,40 @@ export interface PendingFrontendCall {
   toolName: string;
   sessionId: string;
   startedAt: number;
-  /** sid of the socket executing it (unset only before it is sent). */
+  /** Not sent yet: no socket that can run it has joined the session. */
+  parked: boolean;
+  /** sid of the socket executing it (unset while it is parked). */
   executorSid?: string;
 }
 
-interface Pending extends Omit<PendingFrontendCall, 'executorSid'> {
+interface Pending extends Omit<PendingFrontendCall, 'executorSid' | 'parked'> {
   executor?: FrontendExecutor;
+  /** The call's own deadline once it is sent. */
+  timeoutMs: number;
   resolve: (value: unknown) => void;
   reject: (error: Error) => void;
   timer: ReturnType<typeof setTimeout>;
+  /** Removes the listener on the turn's abort signal (set when one was added). */
+  detach?: () => void;
+  onDispatched?: () => void;
+}
+
+export interface FrontendCallOpenOptions {
+  /** How long the browser has to answer once the call is sent. */
+  timeoutMs: number;
+  /**
+   * How long the call may wait unsent for a socket that can run it (default
+   * `timeoutMs`). Past it the call rejects as never sent.
+   */
+  parkTimeoutMs?: number;
+  /** The turn's abort signal. */
+  signal?: AbortSignal;
+  /**
+   * Called once, when the call is sent to a socket (`dispatched`); never for
+   * a call that ends parked (park deadline, abort, full table). A throwing
+   * callback does not affect the call.
+   */
+  onDispatched?: () => void;
 }
 
 /** Finished invocations kept to recognise replays: at most this many… */
@@ -102,6 +134,53 @@ export const FRONTEND_CALL_LABEL: Record<FrontendCallKind, string> = {
   agui: 'AG-UI action',
 };
 
+/** Why a frontend call was never sent (see `FrontendCallNotSentError`). */
+export type FrontendCallNotSentReason =
+  /** The turn aborted while the call was parked (or before it was opened). */
+  | 'aborted'
+  /** No socket that can run it joined the session within the park deadline. */
+  | 'park-deadline'
+  /** An earlier call of the session hit its park deadline and no socket has joined since. */
+  | 'no-browser'
+  /** The user's table of calls in flight is full. */
+  | 'table-full';
+
+/**
+ * A frontend call that never reached a browser: a definite failure, so the
+ * tool layer releases a write's claim (`isUncertainOutcome` is false for it,
+ * even on an aborted turn). Its message never contains the words the tool
+ * layer reads as an uncertain outcome.
+ */
+export class FrontendCallNotSentError extends Error {
+  constructor(
+    readonly reason: FrontendCallNotSentReason,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'FrontendCallNotSentError';
+  }
+}
+
+/**
+ * Whether `error` is, or wraps (`cause`, as LangChain's middleware errors
+ * do), a `FrontendCallNotSentError`.
+ */
+export function isFrontendCallNotSent(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; depth < 8 && current instanceof Error; depth += 1) {
+    if (current instanceof FrontendCallNotSentError) return true;
+    current = current.cause;
+  }
+  return false;
+}
+
+/**
+ * The model-facing ending of a call that waited for a browser in vain: the
+ * user has to open the chat, and the model must not loop on the tool.
+ */
+export const OPEN_CHAT_HINT =
+  'Ask the user to open this chat; do not retry on your own.';
+
 export interface FrontendCallRegistryOptions {
   now?: () => number;
   maxPending?: number;
@@ -113,6 +192,11 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
+/** `300000` → `300`, `1500` → `1.5`: the park deadline as the error states it. */
+export function seconds(ms: number): string {
+  return String(Number((ms / 1000).toFixed(3)));
+}
+
 function sameExecutor(a: FrontendExecutor, b: FrontendExecutor): boolean {
   return (
     a.sid === b.sid && a.sessionId === b.sessionId && a.userDid === b.userDid
@@ -145,12 +229,13 @@ export class FrontendCallRegistry {
    * Register an invocation BEFORE it is sent, so an immediate answer cannot
    * be missed, and return the promise its result settles. Throws when the id
    * was already issued or the table is full — the call is then not sent.
-   * `signal` (the turn's abort signal) ends it early: rejected as not sent
-   * before `dispatched`, an unknown outcome after.
+   * Until `dispatched` the call is parked on `parkTimeoutMs`; past it the
+   * call rejects as never sent. `signal` (the turn's abort signal) ends it
+   * early: rejected as not sent before `dispatched`, an unknown outcome after.
    */
   open(
-    call: Omit<PendingFrontendCall, 'startedAt' | 'executorSid'>,
-    opts: { timeoutMs: number; signal?: AbortSignal },
+    call: Omit<PendingFrontendCall, 'startedAt' | 'executorSid' | 'parked'>,
+    opts: FrontendCallOpenOptions,
   ): Promise<unknown> {
     const id = call.toolCallId;
     const label = FRONTEND_CALL_LABEL[call.kind];
@@ -158,22 +243,35 @@ export class FrontendCallRegistry {
     if (this.pending.has(id) || this.completed.has(id))
       throw new Error(`${label} invocation ${id} was already issued`);
     if (this.pending.size >= this.maxPending)
-      throw new Error(
+      throw new FrontendCallNotSentError(
+        'table-full',
         `${label} ${call.toolName} was not sent: ${this.maxPending} frontend calls are already in flight`,
       );
+    const parkTimeoutMs = opts.parkTimeoutMs ?? opts.timeoutMs;
     return new Promise<unknown>((resolve, reject) => {
+      // The park deadline: the call was never sent, so it definitely did not
+      // run — worded so the tool layer never reads it as an uncertain outcome.
       const timer = setTimeout(() => {
-        if (this.complete(id)) resolve(frontendOutcomeUnknown(id));
-      }, opts.timeoutMs);
+        if (this.complete(id))
+          reject(
+            new FrontendCallNotSentError(
+              'park-deadline',
+              `${label} ${call.toolName} was not sent: no browser joined session ${call.sessionId} within ${seconds(parkTimeoutMs)} s. ${OPEN_CHAT_HINT}`,
+            ),
+          );
+      }, parkTimeoutMs);
       const entry: Pending = {
         ...call,
         startedAt: this.now(),
+        timeoutMs: opts.timeoutMs,
         resolve,
         reject,
         timer,
+        onDispatched: opts.onDispatched,
       };
       this.pending.set(id, entry);
-      if (opts.signal) {
+      const { signal } = opts;
+      if (signal) {
         // The turn ended (Stop, deadline). Before the call was sent it is a
         // definite failure; once sent, the browser may already have run it.
         const onAbort = () => {
@@ -182,13 +280,18 @@ export class FrontendCallRegistry {
           if (entry.executor) resolve(frontendOutcomeUnknown(id));
           else
             reject(
-              new Error(
+              new FrontendCallNotSentError(
+                'aborted',
                 `${label} ${call.toolName} was not sent: the turn was aborted`,
               ),
             );
         };
-        if (opts.signal.aborted) onAbort();
-        else opts.signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) onAbort();
+        else {
+          signal.addEventListener('abort', onAbort, { once: true });
+          // However the call ends, the turn's signal stops referencing it.
+          entry.detach = () => signal.removeEventListener('abort', onAbort);
+        }
       }
     });
   }
@@ -198,17 +301,32 @@ export class FrontendCallRegistry {
     return this.pending.has(toolCallId);
   }
 
-  /** Bind a pending invocation to the one socket it was sent to. */
-  dispatched(toolCallId: string, executor: FrontendExecutor): void {
+  /** Whether `toolCallId` is waiting unsent (parked). */
+  isParked(toolCallId: string): boolean {
     const entry = this.pending.get(toolCallId);
-    if (entry) entry.executor = executor;
+    return entry !== undefined && !entry.executor;
   }
 
-  /** End an invocation that never reached a browser: a definite failure. */
-  fail(toolCallId: string, error: Error): void {
+  /**
+   * Bind a pending invocation to the one socket it was sent to; its clock
+   * restarts with its own deadline, past which the outcome is unknown.
+   */
+  dispatched(toolCallId: string, executor: FrontendExecutor): void {
     const entry = this.pending.get(toolCallId);
-    if (!entry || !this.complete(toolCallId)) return;
-    entry.reject(error);
+    if (!entry || entry.executor) return;
+    entry.executor = executor;
+    clearTimeout(entry.timer);
+    entry.timer = setTimeout(() => {
+      if (this.complete(toolCallId))
+        entry.resolve(frontendOutcomeUnknown(toolCallId));
+    }, entry.timeoutMs);
+    const { onDispatched } = entry;
+    entry.onDispatched = undefined;
+    try {
+      onDispatched?.();
+    } catch {
+      // The record of the dispatch is best effort; the call is already sent.
+    }
   }
 
   /** Deliver a result that arrived on a socket. */
@@ -272,6 +390,7 @@ export class FrontendCallRegistry {
           toolName,
           sessionId,
           startedAt,
+          parked: !executor,
           ...(executor ? { executorSid: executor.sid } : {}),
         }),
       )
@@ -293,6 +412,7 @@ export class FrontendCallRegistry {
     const entry = this.pending.get(id);
     if (!entry) return false;
     clearTimeout(entry.timer);
+    entry.detach?.();
     this.pending.delete(id);
     this.completed.set(id, this.now());
     this.prune();