@ixo/oracle-runtime-workers 0.21.2 → 0.22.0

package/src/do/run-store.ts

@@ -14,6 +14,8 @@
  *   - `turn_tool_marks`: one row per tool call, written BEFORE the tool runs
  *     (`started`) and updated when it returns (`done`). This is what makes a
  *     resume safe: a started-but-unfinished write call is never re-executed.
+ *     A frontend call also records when it reached a browser (`sent_at`):
+ *     one still parked at the restart never left the object and runs again.
  *   - `turn_write_claims`: one row per write whose outcome is not known yet
  *     (tool-execution.ts), keyed by the fingerprint of the tool name and
  *     arguments. Released by a returned outcome; kept by an abort, a deadline
@@ -22,7 +24,8 @@
  *
  * Cost shape (SQLite-backed DO storage bills rows written or deleted): a run
  * costs 1 insert + ~2 updates, a segment 1 insert + 1 delete, a tool call
- * 1 insert + 1 update, a write 1 insert + 1 delete more.
+ * 1 insert + 1 update (a frontend call 1 update more, when it is sent), a
+ * write 1 insert + 1 delete more.
  */
 import type { DoSqliteDatabase } from '../sqlite/database';
 import type { PackedSegment } from './run-buffer';
@@ -169,6 +172,14 @@ export interface ToolMark {
   outcome: string | null;
   /** Executions started for this call id (a read re-run bumps it). */
   attempts: number;
+  /**
+   * When the call was handed to its executor, for tools that run outside
+   * the object (frontend tools: the moment a browser socket received it).
+   * `null` while a frontend call is parked waiting for a socket, so a
+   * restart knows the call never left the object. Always `null` for tools
+   * that run in the object.
+   */
+  sentAt: string | null;
 }
 
 /** Rows of ended runs are kept a week (a re-join that late gets 404). */
@@ -331,6 +342,7 @@ type MarkRow = {
   done_at: string | null;
   outcome: string | null;
   attempts: number;
+  sent_at: string | null;
 } & Record<string, string | number | null>;
 
 type SegmentRow = {
@@ -393,6 +405,7 @@ function toMark(row: MarkRow): ToolMark {
     doneAt: row.done_at,
     outcome: row.outcome,
     attempts: Number(row.attempts),
+    sentAt: row.sent_at,
   };
 }
 
@@ -474,8 +487,21 @@ export class RunStore {
         done_at TEXT,
         outcome TEXT,
         attempts INTEGER NOT NULL DEFAULT 1,
+        sent_at TEXT,
         PRIMARY KEY (run_id, tool_call_id)
       ) WITHOUT ROWID`);
+    // When a call left the object (frontend calls; see `markSent`). Marks
+    // from before the column cannot tell, so they count as sent: a resume
+    // keeps treating them as it did when they were written.
+    const markColumns = await this.db.exec<{ name: string }>(
+      'PRAGMA table_info(turn_tool_marks)',
+    );
+    if (!markColumns.some((c) => c.name === 'sent_at')) {
+      await this.db.run('ALTER TABLE turn_tool_marks ADD COLUMN sent_at TEXT');
+      await this.db.run(
+        'UPDATE turn_tool_marks SET sent_at = started_at WHERE sent_at IS NULL',
+      );
+    }
     await this.db.run(`
       CREATE TABLE IF NOT EXISTS turn_write_claims (
         fingerprint TEXT PRIMARY KEY,
@@ -705,12 +731,12 @@ export class RunStore {
     return row ? toRecord(row) : undefined;
   }
 
-  /** Every run that is not over, oldest first. */
+  /** Every run that is not over, oldest first (run id breaks a tie). */
   async listActive(): Promise<RunRecord[]> {
     await this.setup();
     const rows = await this.db.exec<RunRow>(
       `SELECT ${RUN_COLUMNS} FROM turn_runs
-       WHERE status IN ('running','recovering','queued') ORDER BY started_at ASC`,
+       WHERE status IN ('running','recovering','queued') ORDER BY started_at ASC, run_id ASC`,
     );
     return rows.map(toRecord);
   }
@@ -853,16 +879,32 @@ export class RunStore {
     return undefined;
   }
 
-  /** A read-only call re-executed on resume: count the execution, keep the row open. */
+  /**
+   * A call re-executed on resume: count the execution, keep the row open.
+   * The new execution has not been handed to an executor yet, so `sent_at`
+   * is cleared with it.
+   */
   async bumpMark(runId: string, toolCallId: string): Promise<void> {
     await this.setup();
     await this.db.run(
-      `UPDATE turn_tool_marks SET attempts = attempts + 1, started_at = ?, done_at = NULL, outcome = NULL
+      `UPDATE turn_tool_marks SET attempts = attempts + 1, started_at = ?, done_at = NULL, outcome = NULL, sent_at = NULL
        WHERE run_id = ? AND tool_call_id = ?`,
       [this.iso(), runId, toolCallId],
     );
   }
 
+  /**
+   * The call left the object: its executor (a browser socket for a frontend
+   * tool) received it. From here on a restart cannot tell whether it ran.
+   */
+  async markSent(runId: string, toolCallId: string): Promise<void> {
+    await this.setup();
+    await this.db.run(
+      `UPDATE turn_tool_marks SET sent_at = ? WHERE run_id = ? AND tool_call_id = ?`,
+      [this.iso(), runId, toolCallId],
+    );
+  }
+
   async finishMark(
     runId: string,
     toolCallId: string,
@@ -881,7 +923,7 @@ export class RunStore {
   ): Promise<ToolMark | undefined> {
     await this.setup();
     const row = await this.db.get<MarkRow>(
-      `SELECT run_id, tool_call_id, tool_name, effect, started_at, done_at, outcome, attempts
+      `SELECT run_id, tool_call_id, tool_name, effect, started_at, done_at, outcome, attempts, sent_at
        FROM turn_tool_marks WHERE run_id = ? AND tool_call_id = ?`,
       [runId, toolCallId],
     );
@@ -891,7 +933,7 @@ export class RunStore {
   async listMarks(runId: string): Promise<ToolMark[]> {
     await this.setup();
     const rows = await this.db.exec<MarkRow>(
-      `SELECT run_id, tool_call_id, tool_name, effect, started_at, done_at, outcome, attempts
+      `SELECT run_id, tool_call_id, tool_name, effect, started_at, done_at, outcome, attempts, sent_at
        FROM turn_tool_marks WHERE run_id = ? ORDER BY started_at ASC`,
       [runId],
     );
@@ -902,10 +944,14 @@ export class RunStore {
 
   /**
    * Claim a write before it runs. `claimed` when no identical write is
-   * outstanding. `blocked` when one is: a `pending` claim becomes `warned`
-   * (owned by this run, so the same turn stays blocked); a claim already
-   * `warned` by an earlier run is released to this run — the user was told
-   * and asked again.
+   * outstanding. `blocked` when one is: a `pending` claim of this run, or of
+   * a run that is over, becomes `warned` (owned by this run, so the same
+   * turn stays blocked); a `pending` claim of ANOTHER run that is still
+   * active (queued / running / recovering) is left exactly as it is — its
+   * owner may still release it when its write returns, and a takeover would
+   * make that release delete nothing; a claim already `warned` by an
+   * earlier run is released to this run — the user was told and asked
+   * again.
    */
   async claimWrite(input: {
     fingerprint: string;
@@ -939,9 +985,16 @@ export class RunStore {
       return { status: 'claimed' };
     }
     if (existing.state === 'pending')
+      // One statement: the owner's liveness is read where the row is
+      // written, so no release or run end can slip in between.
       await this.db.run(
-        `UPDATE turn_write_claims SET state = 'warned', run_id = ? WHERE fingerprint = ? AND state = 'pending'`,
-        [input.runId, input.fingerprint],
+        `UPDATE turn_write_claims SET state = 'warned', run_id = ?
+         WHERE fingerprint = ? AND state = 'pending'
+           AND (run_id = ? OR NOT EXISTS (
+             SELECT 1 FROM turn_runs r WHERE r.run_id = turn_write_claims.run_id
+               AND r.status IN ('running','recovering','queued')
+           ))`,
+        [input.runId, input.fingerprint, input.runId],
       );
     return {
       status: 'blocked',

package/src/do/turn-body.ts

@@ -5,6 +5,8 @@
  * missing `message` are all 400s, never a failed turn or a 500.
  */
 
+import { declaredToolEffect } from '../plugins/portal/declared-tools';
+
 /** Top-level fields of Node's `SendMessageDto`; anything else is rejected. */
 export const TURN_BODY_KEYS: ReadonlySet<string> = new Set([
   'message',
@@ -45,6 +47,8 @@ export interface TurnBody {
     name: string;
     description: string;
     schema: Record<string, unknown>;
+    /** Declared effect; any value but `'read'` / `'write'` is dropped. */
+    effect?: 'read' | 'write';
   }>;
   agActions?: Array<{
     name: string;
@@ -87,6 +91,14 @@ function toolDeclaration(value: unknown): ToolDeclaration | null {
   };
 }
 
+/** A browser tool declaration: a tool declaration plus its optional `effect`. */
+function browserToolDeclaration(value: unknown): ToolDeclaration | null {
+  const declaration = toolDeclaration(value);
+  if (!declaration || !isRecord(value)) return declaration;
+  const effect = declaredToolEffect(value.effect);
+  return effect ? { ...declaration, effect } : declaration;
+}
+
 /**
  * Parse and validate a raw request body. Never throws. Every field the
  * runtime reads is checked for its type here, so a wrong one is a 400 and
@@ -147,7 +159,7 @@ export function parseTurnBody(raw: string): ParsedTurnBody {
     if (!Array.isArray(record.tools)) return reject('tools must be an array');
     tools = [];
     for (const item of record.tools) {
-      const tool = toolDeclaration(item);
+      const tool = browserToolDeclaration(item);
       if (!tool)
         return reject(
           'each tool needs a string name, description and an object schema',

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

@@ -118,6 +118,7 @@ import {
   priorMetadataState,
 } from './turn-metadata';
 import {
+  frontendParkTimeoutMs,
   RealtimeEndpoint,
   type RealtimeStatus,
 } from '../realtime/realtime-endpoint';
@@ -261,6 +262,13 @@ import {
   storedRunRequest,
   type StoredRunRequest,
 } from './run-request';
+import {
+  activeChatRuns,
+  activeRunSummaryOf,
+  listedChatRuns,
+  withActiveRuns,
+  withWaitingFor,
+} from './active-runs';
 import {
   createToolMarksMiddleware,
   toolEffectOf,
@@ -558,6 +566,14 @@ const META_LAST_ACCESS = 'meta:lastAccessAt';
  * `POST /delegation` — the same place the Node runtime reads it from.
  */
 const META_DELEGATION = 'meta:delegation';
+/**
+ * `false` only when no run can be active: written at a boot that found
+ * none, turned `true` before the first run row an instance creates (once
+ * per instance, not per turn). A cold object whose flag is `false` answers
+ * `GET /runs/active` without booting; absent or `true`, it boots and asks
+ * the coordinator.
+ */
+const META_RUNS_MAYBE_ACTIVE = 'meta:runsMaybeActive';
 /** How long a "no deposited delegation" verdict is trusted before re-checking the room. */
 const DELEGATION_MISS_TTL_MS = 60_000;
 /** Storage key prefix: a room this object found end-to-end encrypted. */
@@ -818,8 +834,9 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     private runStore: RunStore | null = null;
     /**
      * Tool concurrency of this user object (tool-scheduler.ts): writes one
-     * at a time across every session and turn, reads and sub-agents in
-     * bounded lanes. Lives as long as the object.
+     * at a time across every session and turn, reads in a bounded lane,
+     * browser tools and sub-agents in bounded lanes per session. Lives as
+     * long as the object; `GET /debug/runs` reports its occupancy.
      */
     private readonly toolScheduler = new ToolScheduler();
     /**
@@ -832,6 +849,14 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
     /** Per-turn domain-context provenance (`domain_context_runs`). */
     private domainContextStore: DomainContextStore | null = null;
     private runs: RunCoordinator | null = null;
+    /**
+     * The boot's scan for runs a previous incarnation left failed: rows may
+     * be active that the coordinator does not hold, so the user-wide run
+     * listings read the store as well.
+     */
+    private runRecoveryFailed = false;
+    /** Whether this instance has written `META_RUNS_MAYBE_ACTIVE` true. */
+    private runsMarkedActive = false;
     private readonly runConfig: RunDurabilityConfig = runDurabilityConfig(
       this.env,
     );
@@ -1788,6 +1813,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         runAttempt: (live, resumed) => this.runAttempt(live, resumed),
         checkpointIdOf: (sessionId) => this.checkpointIdOf(sessionId),
         onRunEnded: (record, outcome) => this.onRunEnded(record, outcome),
+        beforeCreate: () => this.markRunsMaybeActive(),
       });
 
       this.channelTurns = new ChannelTurns(liveDb, {
@@ -1909,11 +1935,25 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       // (attempts run from the alarm, never inside this boot).
       try {
         await this.runs.recoverOrphans();
+        this.runRecoveryFailed = false;
       } catch (err) {
+        this.runRecoveryFailed = true;
         console.error(
           `[user-do] run recovery scan failed for ${userDid}: ${err instanceof Error ? err.message : String(err)}`,
         );
       }
+      // Nothing left in flight: a cold poll of `GET /runs/active` may skip
+      // the boot until this or a later instance creates a run.
+      const runsMarked = await this.ctx.storage.get<boolean>(
+        META_RUNS_MAYBE_ACTIVE,
+      );
+      if (!this.runRecoveryFailed && this.runs.size === 0) {
+        if (runsMarked !== false)
+          await this.ctx.storage.put(META_RUNS_MAYBE_ACTIVE, false);
+        this.runsMarkedActive = false;
+      } else {
+        this.runsMarkedActive = runsMarked === true;
+      }
 
       // Resume (or start) legacy-blob compaction in the background: files
       // imported from the Node runtime arrive with uncompressed blobs.
@@ -2875,7 +2915,15 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         o.offset ?? 0,
         TASK_SESSION_PREFIX,
       );
-      return { sessions: sessions.map(toSummary), total };
+      // One read of the active runs for the whole page, never one per row.
+      return {
+        sessions: withActiveRuns(
+          sessions.map(toSummary),
+          await this.activeChatRunRecords(),
+          this.parkedFrontendCall,
+        ),
+        total,
+      };
     }
 
     /**
@@ -3562,8 +3610,23 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
      * a queued run is dropped. (A client that merely disconnects does NOT
      * reach here — runs outlive their connections.)
      */
-    async abortTurn(sessionId: string): Promise<boolean> {
-      if (this.runs?.abortSession(sessionId)) return true;
+    /**
+     * Stop the session's current message. From `POST /messages/abort`
+     * (`identity` given) the object is booted first — the boot recovers the
+     * runs a previous incarnation left, so a run only the store still knows
+     * (`recovering` after a reset) is live and stopped like any other — and
+     * the answer waits until the runs it stopped have ended (at most the
+     * supersede grace), so the client's next look sees the chat idle. The
+     * scheduler calls it on a booted object without `identity`.
+     */
+    async abortTurn(
+      sessionId: string,
+      identity?: TurnIdentity,
+    ): Promise<boolean> {
+      if (identity) {
+        await this.ready(identity);
+        if (await this.runs?.abortSessionSettled(sessionId)) return true;
+      } else if (this.runs?.abortSession(sessionId)) return true;
       const controller = this.aborts.get(sessionId);
       if (!controller) return false;
       controller.abort();
@@ -4311,10 +4374,18 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         // disconnects (`WsService.removeClientConnection`); same trigger here.
         onSessionDrained: (sessionId) =>
           this.scheduleHistoryIndexing(sessionId),
+        parkTimeoutMs: frontendParkTimeoutMs(this.env),
       });
       return this.realtimeEndpoint;
     }
 
+    /**
+     * The session's parked frontend call, for `waitingFor` on run
+     * summaries. Never builds the endpoint: without one nothing is parked.
+     */
+    private readonly parkedFrontendCall = (sessionId: string) =>
+      this.realtimeEndpoint?.frontend.parkedFor(sessionId) ?? null;
+
     async realtimeStatus(): Promise<RealtimeStatus> {
       return {
         ...this.realtime.status(),
@@ -5079,7 +5150,60 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const live = this.runs?.activeForSession(sessionId);
       const record =
         live?.record ?? (await this.runStore?.activeForSession(sessionId));
-      return record ? runSummaryOf(record) : null;
+      return record
+        ? withWaitingFor(runSummaryOf(record), this.parkedFrontendCall)
+        : null;
+    }
+
+    /**
+     * `GET /runs/active` — the active runs of the chats `GET /sessions`
+     * lists (same room rule, task runs out), oldest first. A cold object
+     * that has run nothing since a boot found none answers without booting
+     * (`META_RUNS_MAYBE_ACTIVE`): an idle user's polls never pay a boot,
+     * and do not count as access for the idle eviction.
+     */
+    async activeRuns(identity: TurnIdentity): Promise<RunSummary[]> {
+      if (
+        !this.initPromise &&
+        (await this.ctx.storage.get<boolean>(META_RUNS_MAYBE_ACTIVE)) === false
+      )
+        return [];
+      await this.ready(identity);
+      const runs = await this.activeChatRunRecords();
+      if (runs.length === 0) return [];
+      const mainRoomId = await this.resolveMainRoomId(identity.userDid);
+      const sessionRooms =
+        mainRoomId === null
+          ? new Map<string, string | null>()
+          : await this.sessions!.roomsOf([
+              ...new Set(runs.map((run) => run.sessionId)),
+            ]);
+      return listedChatRuns(runs, { mainRoomId, sessionRooms }).map((run) =>
+        activeRunSummaryOf(run, this.parkedFrontendCall),
+      );
+    }
+
+    /**
+     * The active chat runs (task runs excluded). After a boot whose
+     * recovery scan succeeded every active row is live, and the live record
+     * is the truth (a run leaves the map before its row is closed): no SQL.
+     * Without a coordinator, or after a failed scan, the stored rows count
+     * too, live records winning.
+     */
+    private async activeChatRunRecords(): Promise<RunRecord[]> {
+      if (this.runs && !this.runRecoveryFailed)
+        return activeChatRuns(this.runs.records(), []);
+      return activeChatRuns(
+        this.runs?.records() ?? [],
+        (await this.runStore?.listActive()) ?? [],
+      );
+    }
+
+    /** Before a run row is created: from now on a cold poll must boot. */
+    private async markRunsMaybeActive(): Promise<void> {
+      if (this.runsMarkedActive) return;
+      await this.ctx.storage.put(META_RUNS_MAYBE_ACTIVE, true);
+      this.runsMarkedActive = true;
     }
 
     /** `GET /debug/context?model=` — the context budget a model gets here. */
@@ -5246,6 +5370,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         live: this.runs?.snapshot() ?? [],
         runs,
         claims: store ? await store.listClaims() : [],
+        tools: this.toolScheduler.snapshot(),
       };
     }
 
@@ -5825,19 +5950,40 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         : 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
-      // call time, so the middleware can be created before the agent.
+      // effect and surface maps are filled from the build below; the
+      // closures read them at call time, so the middleware can be created
+      // before the agent.
       const toolEffects = new Map<string, ToolEffect>();
+      const toolSurfaces = new Map<string, 'frontend'>();
       const subAgentToolNames = new Set<string>();
       const effectOf = (name: string): ToolEffect =>
         toolEffects.get(name) ?? toolEffectOf({ name });
+      const runStore = this.runStore!;
       const marksMiddleware = createToolMarksMiddleware({
         runId: run.runId,
-        store: this.runStore!,
+        store: runStore,
         effectOf,
+        surfaceOf: (name) => toolSurfaces.get(name),
         continuation: run.continuation,
         logger: console,
       });
+      // `ctx.markDispatched`: a frontend call reached a browser socket, so a
+      // restart from here on cannot tell whether it ran. A tool's context
+      // carries its own LangChain call id, which is its mark's id on the
+      // main agent. A sub-agent's inner marks are scoped to the dispatch
+      // (`<dispatch>/<id>`), so an inner call's report names no mark and
+      // they stay unsent; that never decides a resume, since a dispatch is a
+      // write and is not run again. (An inner id equal to a main-agent call
+      // id would mark that call sent early: the conservative side.)
+      const markDispatched = (toolCallId: string): void => {
+        void runStore
+          .markSent(run.runId, toolCallId)
+          .catch((error: unknown) =>
+            console.warn(
+              `[runs] ${run.runId}: could not record that ${toolCallId} was sent: ${error instanceof Error ? error.message : String(error)}`,
+            ),
+          );
+      };
       // The turn's budget (turn-budget.ts): model tokens are accounted (for
       // the usage line below, never limited) by the metered adapter every
       // model of this turn comes from, tool calls are charged by
@@ -5874,12 +6020,20 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           `[harness] turn ${req.requestId} usage: ~${usage.tokens} tokens (${usage.reportedTokens} reported over ${usage.modelCalls} model calls), ${usage.toolAttempts} tool attempts, ${usage.elapsedMs} ms`,
         );
       });
+      // A dispatch waits in its session's sub-agent lane, a browser tool
+      // (`surface: 'frontend'`) in its session's frontend lane whatever its
+      // effect, every other tool in the user-wide lane of its effect.
       const laneOf = (name: string): ToolLane =>
-        subAgentToolNames.has(name) ? 'subagent' : effectOf(name);
+        subAgentToolNames.has(name)
+          ? 'subagent'
+          : toolSurfaces.has(name)
+            ? 'frontend'
+            : effectOf(name);
       const executionMiddleware = createToolExecutionMiddleware({
         budget,
         scheduler: this.toolScheduler,
         laneOf,
+        effectOf,
         runId: run.runId,
         sessionId: req.sessionId,
         claims: this.runStore!,
@@ -5976,6 +6130,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           llm: meteredLlm,
           attachments: attachmentAccess,
           onTurnEnd: (dispose) => turnDisposables.add(dispose),
+          markDispatched,
         },
         hooks: {
           // Drives the Matrix `work_status` card (one step per model/tool
@@ -6051,6 +6206,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const { agent, context } = built;
       for (const [name, effect] of built.toolEffects)
         toolEffects.set(name, effect);
+      for (const [name, surface] of built.toolSurfaces)
+        toolSurfaces.set(name, surface);
       for (const name of built.subAgentToolNames) subAgentToolNames.add(name);
 
       const attachmentKwargs =

package/src/plugin-api/tool-helper.ts

@@ -31,6 +31,8 @@ export interface ToolHelperOptions {
   effect?: PluginTool['effect'];
   /** Same arguments again is a new action (a UI step); see `PluginTool.repeatable`. */
   repeatable?: PluginTool['repeatable'];
+  /** `'frontend'` for a tool that acts in the user's browser; see `PluginTool.surface`. */
+  surface?: PluginTool['surface'];
   /**
    * Billing gate marker, kept for source compatibility with the Node
    * runtime's plugin contract. The Workers runtime has no commerce lane, so
@@ -72,6 +74,7 @@ export function tool(
     billing,
     effect,
     repeatable,
+    surface,
   } = options;
   if (!name || typeof name !== 'string') {
     throw new TypeError(
@@ -110,5 +113,8 @@ export function tool(
   if (repeatable !== undefined) {
     pluginTool.repeatable = repeatable;
   }
+  if (surface !== undefined) {
+    pluginTool.surface = surface;
+  }
   return pluginTool;
 }

package/src/plugin-api/types.ts

@@ -833,6 +833,18 @@ export interface RuntimeContext<TConfig = MergedConfig> {
    * to the state update.
    */
   toolCallId?: string;
+
+  /**
+   * Record that THIS tool call has left the object: the executor that runs
+   * it outside the runtime received it (for a frontend tool, a browser
+   * socket). Present when the host keeps write-ahead marks for the turn's
+   * tool calls (durable runs on Workers) and the call has an id. A call
+   * restarted before this was recorded is known not to have run and is
+   * issued again on resume; after it, a write's outcome is unknown. A tool
+   * that may wait before sending (a parked frontend call) passes it as
+   * `FrontendCallParams.onDispatched`.
+   */
+  markDispatched?: () => void;
 }
 
 /** Lifecycle of a scheduled task. */
@@ -891,18 +903,46 @@ export interface OracleTaskInput {
 /**
  * Bridge to the user's browser over the realtime channel. Each call is one
  * invocation with its own id, sent (`browser_tool_call` / `action_call`) to
- * ONE authenticated socket of `sessionId`; only that socket's answer settles
- * it. It resolves with the browser's answer and rejects on the browser's
- * `error`, an AG-UI `success: false`, or when no socket could take it. When
- * the answer cannot arrive — the deadline passed or the socket went — it
- * resolves with `FRONTEND_OUTCOME_UNKNOWN` (`@ixo/common/ai/frontend-bridge`):
- * the browser may have performed the action, and it is never sent again.
+ * ONE authenticated socket of `sessionId` that can run it; only that socket's
+ * answer settles it. With no such socket the call is parked: it waits,
+ * unsent, for one to join the session (the turn's abort and the park
+ * deadline end the wait, rejecting the call as never sent). It resolves with
+ * the browser's answer and rejects on the browser's `error` or an AG-UI
+ * `success: false`. When the answer of a sent call cannot arrive — the
+ * deadline passed or the socket went — it resolves with
+ * `FRONTEND_OUTCOME_UNKNOWN` (`@ixo/common/ai/frontend-bridge`): the browser
+ * may have performed the action, and it is never sent again.
  */
 export interface FrontendCallSurface {
   callBrowserTool(params: FrontendCallParams): Promise<unknown>;
   callAgAction(params: FrontendCallParams): Promise<unknown>;
-  /** Whether at least one authenticated realtime client is attached to the session. */
+  /**
+   * Whether at least one authenticated realtime client is attached to the
+   * session, background executors included (see `canDispatch`).
+   */
   hasClient(sessionId: string): boolean;
+  /**
+   * Whether a call of `kind` to `toolName` would be sent right now rather
+   * than parked: an authenticated socket of the session can run it (any
+   * foreground socket; a background executor only for a browser tool it
+   * declared). A caller that must not park — wallet signing refuses at once
+   * — checks this first.
+   */
+  canDispatch(
+    sessionId: string,
+    kind: 'browser' | 'agui',
+    toolName: string,
+  ): boolean;
+  /** The session's oldest parked call (waiting unsent for a browser), if any. */
+  parkedFor(sessionId: string): FrontendWaitingFor | null;
+}
+
+/** A frontend call waiting, unsent, for a browser of its session to join. */
+export interface FrontendWaitingFor {
+  kind: 'browser' | 'agui';
+  toolName: string;
+  /** When the call was parked (ISO 8601). */
+  since: string;
 }
 
 export interface FrontendCallParams {
@@ -921,6 +961,12 @@ export interface FrontendCallParams {
    * `FRONTEND_OUTCOME_UNKNOWN` at once — the browser may already have run it.
    */
   signal?: AbortSignal;
+  /**
+   * Called once, when the call is sent to a socket (at once, or later when
+   * a parked call is dispatched); never for a call that ends unsent. A tool
+   * passes `ctx.markDispatched` here.
+   */
+  onDispatched?: () => void;
 }
 
 /**
@@ -984,6 +1030,16 @@ export interface PluginTool {
    * `effect` still governs retries, write claims and resume.
    */
   repeatable?: boolean;
+  /**
+   * `'frontend'`: the tool acts in the user's browser through the frontend
+   * bridge (`ctx.frontend`). It is scheduled in the session's own
+   * `frontend` lane, one call at a time per session, never in the user-wide
+   * read/write lanes, so a call parked while the chat has no tab holds no
+   * server slot another chat needs. The identical-write ledger still
+   * applies when its `effect` is `write` (its fingerprint then includes the
+   * session). Omitted: a server-side tool, scheduled by its effect.
+   */
+  surface?: 'frontend';
   /**
    * Billing gate. `'contracted'` marks a tool that performs paid contracted
    * work: the runtime binds it only while the turn runs inside an active work