@robota-sdk/agent-transport 3.0.0-beta.94 → 3.0.0-beta.95

package/src/__tests__/session-resume-bridge.test.ts

@@ -404,3 +404,69 @@ describe('SessionResumeBridge (REMOTE-013 TC-02)', () => {
     });
   });
 });
+
+describe('app view messages through the resume bridge', () => {
+  const view = {
+    sourceId: 'files',
+    resourceUri: 'ui://files/list',
+    mimeType: 'text/html;profile=mcp-app',
+    html: '<main>rows</main>',
+    callableTools: { list_files: 'mcp__files__list_files' },
+  };
+  const call = {
+    type: 'call-app-tool',
+    requestId: 'c1',
+    viewId: 'view-1',
+    name: 'mcp__files__list_files',
+    arguments: {},
+  };
+
+  it('cancels a call waiting on its prompt when the host gives up on the bridge, not when a channel drops', async () => {
+    let signal: AbortSignal | undefined;
+    const base = fakeSession().session;
+    const session = Object.assign(base, {
+      readToolAppView: vi.fn().mockReturnValue(view),
+      invokeRuntimeTool: vi.fn(
+        (_name: string, _arguments: unknown, options?: { signal?: AbortSignal }) => {
+          signal = options?.signal;
+          return new Promise(() => undefined);
+        },
+      ),
+    });
+    const bridge = new SessionResumeBridge({ session });
+    bridge.attach(sink(), TEST_ATTACH_OPTIONS);
+
+    bridge.onClientMessage(JSON.stringify(call));
+    await vi.waitFor(() => expect(signal).toBeDefined());
+
+    // A channel drop leaves the session reconnectable: the call keeps waiting for its prompt.
+    bridge.detach();
+    expect(signal?.aborted).toBe(false);
+
+    bridge.dispose();
+    expect(signal?.aborted).toBe(true);
+  });
+
+  it('holds an app view to the channel limit before the frame reaches the buffer', () => {
+    const base = fakeSession().session;
+    const session = Object.assign(base, {
+      readToolAppView: vi.fn().mockReturnValue({ ...view, html: 'x'.repeat(5_000) }),
+    });
+    const bridge = new SessionResumeBridge({ session, maxFrameBytes: 2_000 });
+    const output = sink();
+    bridge.attach(output, TEST_ATTACH_OPTIONS);
+
+    bridge.onClientMessage(JSON.stringify({ type: 'read-app-view', requestId: 'v1', viewId: 'view-1' }));
+
+    expect(frames(output).map((frame) => frame.type)).toEqual(['protocol_error']);
+    // Nothing large was retained for a later `resume` either.
+    const replay = sink();
+    bridge.detach();
+    bridge.attach(replay, TEST_ATTACH_OPTIONS);
+    bridge.onClientMessage(JSON.stringify({ type: 'resume', lastSeq: 0 }));
+    expect(frames(replay).map((frame) => frame.type)).toEqual(['protocol_error']);
+    expect(replay.calls.join('').length).toBeLessThan(2_000);
+    bridge.dispose();
+  });
+});
+

package/src/__tests__/stdio-carrier.test.ts

@@ -0,0 +1,85 @@
+/**
+ * The stdio carrier bridge: what a protocol carrier hands its SDK in place of the process input, and
+ * how it learns that either end went away. Two carriers share it, so the cases here are the contract
+ * both rely on rather than either carrier's own behavior.
+ */
+
+import { PassThrough } from 'node:stream';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { attachStdioCarrier } from '../node/stdio-carrier.js';
+
+function handlers() {
+  return { onInputClose: vi.fn(), onOutputClose: vi.fn(), onOutputError: vi.fn() };
+}
+
+describe('attachStdioCarrier', () => {
+  it('forwards input to the bridge and keeps bytes written before anyone reads', async () => {
+    const input = new PassThrough();
+    const carrier = attachStdioCarrier(input, new PassThrough(), handlers());
+    input.write('early\n');
+    const chunks: string[] = [];
+    carrier.bridge.on('data', (chunk: Buffer) => chunks.push(chunk.toString()));
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(chunks.join('')).toBe('early\n');
+    carrier.release();
+  });
+
+  it('reports the input ending, and the bridge ends with it', async () => {
+    const input = new PassThrough();
+    const h = handlers();
+    const carrier = attachStdioCarrier(input, new PassThrough(), h);
+    const ended = new Promise<void>((resolve) => carrier.bridge.once('end', resolve));
+    carrier.bridge.resume();
+    input.end();
+    await ended;
+    expect(h.onInputClose).toHaveBeenCalled();
+    carrier.release();
+  });
+
+  it('reports the input closing without an end', () => {
+    const input = new PassThrough();
+    const h = handlers();
+    const carrier = attachStdioCarrier(input, new PassThrough(), h);
+    input.emit('close');
+    expect(h.onInputClose).toHaveBeenCalledTimes(1);
+    carrier.release();
+  });
+
+  it('reports the output closing and failing', () => {
+    const output = new PassThrough();
+    const h = handlers();
+    const carrier = attachStdioCarrier(new PassThrough(), output, h);
+    const failure = new Error('EPIPE');
+    output.emit('error', failure);
+    output.emit('close');
+    expect(h.onOutputError).toHaveBeenCalledWith(failure);
+    expect(h.onOutputClose).toHaveBeenCalledTimes(1);
+    carrier.release();
+  });
+
+  it('destroys the bridge on release but leaves the real input alone', () => {
+    const input = new PassThrough();
+    const carrier = attachStdioCarrier(input, new PassThrough(), handlers());
+    carrier.release();
+    expect(carrier.bridge.destroyed).toBe(true);
+    expect(input.destroyed).toBe(false);
+    expect(input.listenerCount('end')).toBe(0);
+    expect(input.listenerCount('close')).toBe(0);
+  });
+
+  it('stops reporting after release, and release is idempotent', () => {
+    const input = new PassThrough();
+    const output = new PassThrough();
+    const h = handlers();
+    const carrier = attachStdioCarrier(input, output, h);
+    carrier.release();
+    carrier.release();
+    input.emit('close');
+    output.emit('close');
+    expect(h.onInputClose).not.toHaveBeenCalled();
+    expect(h.onOutputClose).not.toHaveBeenCalled();
+    expect(h.onOutputError).not.toHaveBeenCalled();
+  });
+});

package/src/app-tool-messages.ts

@@ -0,0 +1,140 @@
+/**
+ * A driving surface that hosts an MCP app view acts for it here: it invokes one runtime tool
+ * through the session's own permission gate, and it reads a finished call's view on demand.
+ *
+ * Both are drive-only (neither is in `OBSERVER_MESSAGES`): an observer neither runs a tool nor
+ * receives a view's document. A message that decoded but cannot be served answers `protocol_error`
+ * echoing `requestId`, so the view that asked can tell which call it was.
+ */
+import { MAX_INBOUND_FRAME_BYTES } from './message-decoders.js';
+
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { TClientMessage, TServerMessage } from './wire-messages.js';
+import type {
+  ISessionRuntimeTools,
+  ISessionToolAppViews,
+  TDriverId,
+} from '@robota-sdk/agent-interface-session';
+
+type TCallAppToolMessage = Extract<TClientMessage, { type: 'call-app-tool' }>;
+type TReadAppViewMessage = Extract<TClientMessage, { type: 'read-app-view' }>;
+
+/**
+ * Room a carrier that stamps frames after they are produced (the resume bridge adds `seq`) needs
+ * beneath the inbound limit, so a frame sent within the limit is still received within it.
+ */
+const FRAME_STAMP_MARGIN_BYTES = 1024;
+
+/** Where a frame answering an app message is measured, and what ends the work behind it. */
+export interface IAppMessageOptions {
+  /** The most bytes one answering frame may take; defaults to the inbound limit less a margin. */
+  readonly maxFrameBytes?: number;
+  /** Ends the connection's work: aborting it cancels a call still waiting on its prompt. */
+  readonly signal?: AbortSignal;
+}
+
+export function isAppToolMessage(msg: TClientMessage): msg is TCallAppToolMessage {
+  return msg.type === 'call-app-tool';
+}
+
+export function isAppViewMessage(msg: TClientMessage): msg is TReadAppViewMessage {
+  return msg.type === 'read-app-view';
+}
+
+function frameLimit(options: IAppMessageOptions | undefined): number {
+  return options?.maxFrameBytes ?? MAX_INBOUND_FRAME_BYTES - FRAME_STAMP_MARGIN_BYTES;
+}
+
+/** Checked before `deliver`, so a frame the channel cannot carry never enters a buffer. */
+function fitsFrame(frame: TServerMessage, limit: number): boolean {
+  return new TextEncoder().encode(JSON.stringify(frame)).byteLength <= limit;
+}
+
+/**
+ * Runs the tool as an interactive call acting for this connection's driver, so a permission prompt
+ * it raises is shown to the surfaces that can answer and is attributed to that driver. The call is
+ * limited to the tools the named view's own source declared: the surface says which view it acts
+ * for, and the session, not the surface, says what that view may reach.
+ */
+export function handleAppToolMessage(
+  session: ISessionRuntimeTools & ISessionToolAppViews,
+  deliver: TOutboundDeliver,
+  msg: TCallAppToolMessage,
+  driverId?: TDriverId,
+  options?: IAppMessageOptions,
+): void {
+  const { requestId } = msg;
+  const view = session.readToolAppView(msg.viewId);
+  if (view === undefined) {
+    deliver({ type: 'protocol_error', message: 'This app view is no longer available.', requestId });
+    return;
+  }
+  if (!Object.values(view.callableTools).includes(msg.name)) {
+    deliver({
+      type: 'protocol_error',
+      message: 'This tool is not available to this app view.',
+      requestId,
+    });
+    return;
+  }
+  const { signal } = options ?? {};
+  const limit = frameLimit(options);
+  session
+    .invokeRuntimeTool(msg.name, msg.arguments, {
+      permissionInteraction: 'interactive',
+      ...(driverId ? { driverId } : {}),
+      ...(signal ? { signal } : {}),
+    })
+    .then(
+      (result) => {
+        // The connection that asked is gone: there is nobody to answer.
+        if (signal?.aborted) return;
+        const frame: TServerMessage = {
+          type: 'app_tool_result',
+          requestId,
+          success: result.success,
+          ...(result.result !== undefined ? { data: result.result } : {}),
+          ...(result.parts !== undefined ? { parts: result.parts } : {}),
+          ...(result.error !== undefined ? { error: result.error } : {}),
+        };
+        if (fitsFrame(frame, limit)) {
+          deliver(frame);
+        } else {
+          deliver({
+            type: 'protocol_error',
+            message: 'This app tool result is too large to send.',
+            requestId,
+          });
+        }
+      },
+      (error: unknown) => {
+        if (signal?.aborted) return;
+        deliver({
+          type: 'protocol_error',
+          message: error instanceof Error ? error.message : String(error),
+          requestId,
+        });
+      },
+    );
+}
+
+/** Answers with the whole document, or says why not: gone, or too large for a frame. */
+export function handleAppViewMessage(
+  session: ISessionToolAppViews,
+  deliver: TOutboundDeliver,
+  msg: TReadAppViewMessage,
+  options?: IAppMessageOptions,
+): void {
+  const { requestId } = msg;
+  const view = session.readToolAppView(msg.viewId);
+  if (view === undefined) {
+    deliver({ type: 'protocol_error', message: 'This app view is no longer available.', requestId });
+    return;
+  }
+  const frame: TServerMessage = { type: 'app_view', requestId, view };
+  if (!fitsFrame(frame, frameLimit(options))) {
+    deliver({ type: 'protocol_error', message: 'This app view is too large to send.', requestId });
+    return;
+  }
+  deliver(frame);
+}

package/src/index.ts

@@ -54,6 +54,9 @@ export type {
 export { PROTOCOL_SESSION_EVENT_CLASSIFICATION } from './session-events.js';
 // The one list of messages an observer may send: the host refuses the rest, a client sends no others.
 export { isObserverMessageType } from './observer-messages.js';
+// The most history one frame carries, sized for the tightest channel; a carrier whose channel is
+// small (a WebRTC data channel) bounds an app view's frame by the same number.
+export { HISTORY_PAGE_MAX_BYTES } from './session-query-messages.js';
 export type { TProtocolSessionEventClassification } from './session-events.js';
 export type { IProtocolSession } from './protocol-session.js';
 export type {
@@ -112,6 +115,10 @@ export type {
   IPeerMessageVerdict,
 } from './peer-message-ledger.js';
 
+// The argument a person recognises a tool call by, shared by every transport that asks a person
+// about a permission in its own wire form, so they name the same call the same way.
+export { permissionSummaryArgument } from './permission-summary.js';
+
 // The handoff integrity helpers (`sealHandoffRecord`, `verifyHandoffPayload`) are NOT
 // here: it hashes with `node:crypto`. Chunking is, because it never hashes anything.
 export {

package/src/message-decoders.ts

@@ -269,6 +269,13 @@ export const CLIENT_MESSAGE_SHAPES: Readonly<Record<TClientMessage['type'], TVar
   'project-status': { requestId: isNonEmptyString },
   'project-diff': { requestId: isNonEmptyString, path: isNonEmptyString },
   'project-memory': { requestId: isNonEmptyString },
+  'call-app-tool': {
+    requestId: isNonEmptyString,
+    viewId: isNonEmptyString,
+    name: isNonEmptyString,
+    arguments: isRecord,
+  },
+  'read-app-view': { requestId: isNonEmptyString, viewId: isNonEmptyString },
   'get-background-tasks': { filter: isOptional(isBackgroundTaskListFilter) },
   'get-background-task': { taskId: isNonEmptyString },
   'get-background-job-groups': {},
@@ -380,6 +387,15 @@ export const SERVER_MESSAGE_SHAPES: Readonly<Record<TServerMessage['type'], TVar
   project_status: { requestId: isNonEmptyString, result: isProjectStatusRead },
   project_diff: { requestId: isNonEmptyString, result: isProjectDiffRead },
   project_memory: { requestId: isNonEmptyString, result: isProjectMemoryRead },
+  // `data` is whatever JSON the tool returned, so any value passes, null included; absent is fine.
+  app_tool_result: {
+    requestId: isNonEmptyString,
+    success: isBoolean,
+    data: () => true,
+    parts: isOptional(isRecordArray),
+    error: isOptional(isString),
+  },
+  app_view: { requestId: isNonEmptyString, view: isRecord },
   background_task_event: { event: isRecord },
   background_job_group_event: { event: isRecord },
   plan_event: { event: isRecord },

package/src/node/index.ts

@@ -41,3 +41,5 @@ export type {
   TFileSendOutcome,
   TFileTransferRefusal,
 } from './file-transfer.js';
+export { attachStdioCarrier } from './stdio-carrier.js';
+export type { IStdioCarrier, IStdioCarrierHandlers } from './stdio-carrier.js';

package/src/node/stdio-carrier.ts

@@ -0,0 +1,59 @@
+/**
+ * The input bridge and close observation a stdio protocol carrier shares.
+ *
+ * A protocol SDK that reads a stream owns what it reads: closing the SDK connection destroys its
+ * source. Handing it the process input directly would let one carrier's `stop()` destroy `process.stdin`
+ * for the whole process, so the carrier reads a `PassThrough` bridge fed by the input instead. Piping
+ * also makes EOF observable before the SDK starts reading and keeps early frames, with backpressure,
+ * until it does.
+ *
+ * This module only attaches and detaches. What a close or failure means — settle a promise, cancel a
+ * startup, end the process — stays with each carrier.
+ */
+
+import { PassThrough } from 'node:stream';
+
+import type { Readable, Writable } from 'node:stream';
+
+export interface IStdioCarrierHandlers {
+  /** The peer ended its side: `end` or `close` on the input. May fire more than once. */
+  readonly onInputClose: () => void;
+  /** The output closed. */
+  readonly onOutputClose: () => void;
+  /** The output failed to accept a write. */
+  readonly onOutputError: (error: Error) => void;
+}
+
+export interface IStdioCarrier {
+  /** Hand this to the protocol SDK in place of the input; destroying it never destroys the input. */
+  readonly bridge: PassThrough;
+  /** Remove the listeners, unpipe and destroy the bridge. Safe to call again; the streams stay open. */
+  release(): void;
+}
+
+export function attachStdioCarrier(
+  input: Readable,
+  output: Writable,
+  handlers: IStdioCarrierHandlers,
+): IStdioCarrier {
+  const bridge = new PassThrough();
+  let released = false;
+  input.once('end', handlers.onInputClose);
+  input.once('close', handlers.onInputClose);
+  output.once('close', handlers.onOutputClose);
+  output.on('error', handlers.onOutputError);
+  input.pipe(bridge);
+  return {
+    bridge,
+    release() {
+      if (released) return;
+      released = true;
+      input.off('end', handlers.onInputClose);
+      input.off('close', handlers.onInputClose);
+      output.off('close', handlers.onOutputClose);
+      output.off('error', handlers.onOutputError);
+      input.unpipe(bridge);
+      bridge.destroy();
+    },
+  };
+}

package/src/permission-summary.ts

@@ -0,0 +1,18 @@
+/**
+ * The one argument a person recognises a tool call by, for every transport that puts a permission
+ * request to a person in its own wire form. Shared so the transports name the same call the same
+ * way; the built-in file tools take `filePath`, other tools `file_path` or `path`.
+ */
+import type { TToolArgs } from '@robota-sdk/agent-core';
+
+/** In the order the tools put them first. */
+const SUMMARY_ARGUMENTS = ['command', 'filePath', 'file_path', 'path', 'url', 'pattern', 'query'];
+
+/** The call's identifying argument, or `undefined` when it has none worth showing. */
+export function permissionSummaryArgument(toolArgs: TToolArgs): string | undefined {
+  for (const key of SUMMARY_ARGUMENTS) {
+    const value = toolArgs[key];
+    if (typeof value === 'string' && value !== '') return value;
+  }
+  return undefined;
+}

package/src/protocol-session.ts

@@ -11,8 +11,10 @@ import type {
   ISessionExecutionWorkspace,
   ISessionProjectRead,
   ISessionPromptResolution,
+  ISessionRuntimeTools,
   ISessionSelfPacedLoopControl,
   ISessionStatusRead,
+  ISessionToolAppViews,
   ISessionTurnControl,
   ISessionTurnSubmission,
 } from '@robota-sdk/agent-interface-session';
@@ -37,7 +39,11 @@ export interface IProtocolSession
     // #3282 §4: the agent switcher's read (`listAgentDefinitions`/`getDefaultAgentType`) — the
     // group's write members (`spawnAgentJob` and friends) stay unused by any wire handler; they run
     // only through `executeCommand`, same as every other command-only write.
-    ISessionAgentJobs {}
+    ISessionAgentJobs,
+    // A driving surface that hosts an app view runs one runtime tool for it (`call-app-tool`) and
+    // reads a finished call's view (`read-app-view`).
+    ISessionRuntimeTools,
+    ISessionToolAppViews {}
 
 /**
  * #3282 §4c: a protocol session that ALSO answers the Project panel's reads. `Partial` (not a fourth

package/src/session-events.ts

@@ -45,6 +45,7 @@ export const PROTOCOL_SESSION_EVENT_CLASSIFICATION = {
   tool_start: 'forwarded',
   tool_end: 'forwarded',
   thinking: 'forwarded',
+  thinking_delta: 'non-surface',
   complete: 'forwarded',
   error: 'forwarded',
   context_update: 'forwarded',

package/src/session-message-handler.ts

@@ -8,6 +8,13 @@
  * Server pushes IProtocolSession events to client in real-time.
  */
 
+import {
+  handleAppToolMessage,
+  handleAppViewMessage,
+  isAppToolMessage,
+  isAppViewMessage,
+  type IAppMessageOptions,
+} from './app-tool-messages.js';
 import {
   handleBackgroundControlMessage,
   handleBackgroundQueryMessage,
@@ -93,6 +100,13 @@ export interface ISessionMessageHandlerOptions {
    * command that runs code from outside the session (installing a plugin) can refuse a remote device.
    */
   commandSurfaceLocality?: TCommandSurfaceLocality;
+  /**
+   * The most bytes one frame answering an app tool call or view read may take, for a carrier whose
+   * channel carries less than the inbound limit (a WebRTC data channel). An answer over it is
+   * replaced by a `protocol_error` before it reaches any buffer. Defaults to the inbound limit less
+   * a margin for a carrier that stamps frames afterwards.
+   */
+  maxFrameBytes?: number;
 }
 
 /**
@@ -119,10 +133,17 @@ export function createSessionMessageHandler(options: ISessionMessageHandlerOptio
   cleanup: () => void;
 } {
   const role = options.role ?? 'drive';
-  const cleanup = subscribeSessionEvents(options.session, options.deliver, {
+  const unsubscribe = subscribeSessionEvents(options.session, options.deliver, {
     getSurfaceDriverId: () => options.driverId,
     receivePrompts: role === 'drive',
   });
+  // One per connection: when the connection goes, work it started for a hosted app view (a tool call
+  // waiting on its permission prompt) is cancelled, so the prompt is withdrawn instead of left open.
+  const connection = new AbortController();
+  const cleanup = (): void => {
+    connection.abort();
+    unsubscribe();
+  };
   const onMessage = createMessageHandler(
     options.session,
     options.deliver,
@@ -137,6 +158,10 @@ export function createSessionMessageHandler(options: ISessionMessageHandlerOptio
     options.sessionDirectory,
     options.settingsReporter,
     options.commandSurfaceLocality,
+    {
+      signal: connection.signal,
+      ...(options.maxFrameBytes !== undefined ? { maxFrameBytes: options.maxFrameBytes } : {}),
+    },
   );
 
   return { onMessage, cleanup };
@@ -152,6 +177,7 @@ function createMessageHandler(
   sessionDirectory?: ISessionDirectory,
   settingsReporter?: ISettingsReporter,
   commandSurfaceLocality?: TCommandSurfaceLocality,
+  appMessages?: IAppMessageOptions,
 ): (data: string) => void {
   return (data: string): void => {
     const msg = parseClientMessage(data, deliver);
@@ -170,6 +196,7 @@ function createMessageHandler(
       sessionDirectory,
       settingsReporter,
       commandSurfaceLocality,
+      appMessages,
     );
   };
 }
@@ -194,6 +221,7 @@ export function handleClientMessage(
   sessionDirectory?: ISessionDirectory,
   settingsReporter?: ISettingsReporter,
   commandSurfaceLocality?: TCommandSurfaceLocality,
+  appMessages?: IAppMessageOptions,
 ): void {
   if (handleUsageQueryMessage(session, deliver, msg, reporters)) {
     return;
@@ -230,6 +258,14 @@ export function handleClientMessage(
     handleProjectReadMessage(session, deliver, msg);
     return;
   }
+  if (isAppToolMessage(msg)) {
+    handleAppToolMessage(session, deliver, msg, driverId, appMessages);
+    return;
+  }
+  if (isAppViewMessage(msg)) {
+    handleAppViewMessage(session, deliver, msg, appMessages);
+    return;
+  }
   if (isBackgroundQueryMessage(msg)) {
     handleBackgroundQueryMessage(session, deliver, msg);
     return;

package/src/session-resume-bridge.ts

@@ -68,6 +68,8 @@ export interface ISessionResumeBridgeOptions {
   readonly storedSessionUsageReporter?: IUsageQueryReporters['storedSessionUsageReporter'];
   /** #3282 §4 part b-2: this bridge is the reconnectable WebRTC path, so it is always `'remote'`. */
   readonly commandSurfaceLocality?: TCommandSurfaceLocality;
+  /** See {@link ISessionMessageHandlerOptions.maxFrameBytes}: the channel's limit, not the inbound one. */
+  readonly maxFrameBytes?: number;
 }
 
 export class SessionResumeBridge {
@@ -77,6 +79,13 @@ export class SessionResumeBridge {
   private readonly reporters: IUsageQueryReporters;
   private readonly surface?: TUsageSurface;
   private readonly commandSurfaceLocality?: TCommandSurfaceLocality;
+  private readonly maxFrameBytes?: number;
+  /**
+   * Ends with the bridge, not with a channel: a channel drop keeps the session reconnectable, so work
+   * started for a hosted app view (a call waiting on its prompt) survives it and is cancelled only when
+   * the host gives up on the session.
+   */
+  private readonly lifetime = new AbortController();
   private readonly unsubscribe: () => void;
   private onDeliveryError?: IAttachOptions['onDeliveryError'];
   /**
@@ -110,6 +119,7 @@ export class SessionResumeBridge {
     this.driverId = options.driverId;
     this.surface = options.surface;
     this.commandSurfaceLocality = options.commandSurfaceLocality;
+    this.maxFrameBytes = options.maxFrameBytes;
     this.reporters = {
       personalUsageReporter: options.personalUsageReporter,
       usageReporter: options.usageReporter,
@@ -186,6 +196,10 @@ export class SessionResumeBridge {
       undefined,
       undefined,
       this.commandSurfaceLocality,
+      {
+        signal: this.lifetime.signal,
+        ...(this.maxFrameBytes !== undefined ? { maxFrameBytes: this.maxFrameBytes } : {}),
+      },
     );
   }
 
@@ -193,6 +207,7 @@ export class SessionResumeBridge {
   public dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
+    this.lifetime.abort();
     // Through `detach`, not a field assignment: the boundary's closure is what holds the channel, so
     // clearing anything else released nothing and left teardown documented but not performed.
     this.detach();

package/src/wire-messages.ts

@@ -1,3 +1,9 @@
+import type {
+  IToolAppView,
+  IToolExecutionResult,
+  TToolParameters,
+  TUniversalMessagePart,
+} from '@robota-sdk/agent-core';
 import type {
   IPersonalUsageReport,
   IPersonalUsageRequest,
@@ -157,6 +163,23 @@ export type TClientMessage =
   // The Project panel's "Memory" section — project memory as readable text. Answered by
   // `project_memory`.
   | { type: 'project-memory'; requestId: string }
+  // A driving surface invokes one runtime tool for a hosted app view, through the session's
+  // permission gate; a prompt it raises is attributed to that surface's driver. `viewId` names the
+  // view (from a `tool_end`'s `appView`) and limits the call to the tools that view's own source
+  // declared. Answered by `app_tool_result`; a call that decoded but is refused (the view is gone,
+  // the tool is not the view's, the invocation is refused) is answered by `protocol_error` echoing
+  // `requestId`. A frame that does not decode, or one an observer sends, carries no `requestId`.
+  | {
+      type: 'call-app-tool';
+      requestId: string;
+      viewId: string;
+      name: string;
+      arguments: TToolParameters;
+    }
+  // A driving surface reads the view a finished model call named in its `tool_end` (`appView`).
+  // Answered by `app_view`; a read that decoded but cannot be served (gone, or too large to send)
+  // is answered by `protocol_error` echoing `requestId`.
+  | { type: 'read-app-view'; requestId: string; viewId: string }
   | { type: 'get-background-tasks'; filter?: IBackgroundTaskListFilter }
   | { type: 'get-background-task'; taskId: string }
   | { type: 'get-background-job-groups' }
@@ -338,6 +361,18 @@ export type TServerMessage =
   | { type: 'project_status'; requestId: string; result: TProjectStatusRead }
   | { type: 'project_diff'; requestId: string; result: TProjectDiffRead }
   | { type: 'project_memory'; requestId: string; result: TProjectMemoryRead }
+  // The outcome of a `call-app-tool`, correlated by `requestId`: the tool's own result, as the
+  // session returned it.
+  | {
+      type: 'app_tool_result';
+      requestId: string;
+      success: boolean;
+      data?: IToolExecutionResult['result'];
+      parts?: TUniversalMessagePart[];
+      error?: string;
+    }
+  // The answer to a `read-app-view`: the whole document, to the surface that asked and no other.
+  | { type: 'app_view'; requestId: string; view: IToolAppView }
   | { type: 'background_task_event'; event: TBackgroundTaskEvent }
   | { type: 'background_job_group_event'; event: TBackgroundJobGroupEvent }
   | { type: 'plan_event'; event: IPlanApprovalEvent }