@robota-sdk/agent-transport 3.0.0-beta.100

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/__tests__/submit-prompt-shape.test.ts

@@ -0,0 +1,78 @@
+/**
+ * TRANS-008 (issue #2045) — a `submit` prompt that is not a string must not reach the session.
+ *
+ * `parseClientMessage` does `JSON.parse(data) as TClientMessage`, and the only guard in the submit
+ * handler is `if (!msg.prompt)`. That is a FALSY check, not a type check: `{}`, `[]` and `42` are
+ * truthy, so they pass it and reach `session.submit(input: string)`.
+ *
+ * Why this one field and not the other thirteen with payloads: the value does not stop at the
+ * session. `interactive-session-execution-controller.ts:249` does
+ * `emit('user_message', displayInput ?? input)`, `session-events.ts` classifies `user_message` as
+ * `'forwarded'` and delivers `{ type: 'user_message', content, … }` — declared `content: string` —
+ * to EVERY attached client, not only the sender. Both client cast sites (`ws-session-client.ts:66`,
+ * `rtc-responder-gate.ts:118`) accept it with `as TServerMessage`, so nothing on the receiving side
+ * rejects it either.
+ *
+ * So one unguarded field lets a client put a shape-invalid value into a typed frame delivered to its
+ * peers. The permission and resume paths were measured too and do NOT cross that way: `interpretApproval`
+ * compares by strict equality against a closed set and defaults to deny, and a malformed `ack`/`resume`
+ * seq degrades only the sender's own attachment.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TServerMessage } from '../wire-messages.js';
+
+function setup() {
+  const submit = vi.fn().mockResolvedValue({ turnId: 't1', completed: Promise.resolve() });
+  // The published conformant double, not a cast: a hand-rolled object asserted to be an
+  // `IInteractiveSession` is a partial re-implementation nothing checks against the real contract.
+  const session = Object.assign(createTestInteractiveSession(), { submit });
+  const sent: TServerMessage[] = [];
+  const { onMessage } = createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((msg) => sent.push(msg), vi.fn()),
+  });
+  return { submit, sent, onMessage };
+}
+
+describe('TRANS-008: a non-string submit prompt is refused at the ingress', () => {
+  it.each([
+    ['an object', {}],
+    ['an array', []],
+    ['a number', 42],
+    ['a boolean', true],
+  ])('refuses %s — it is truthy, so the falsy guard passes it', (_label, prompt) => {
+    const { submit, sent, onMessage } = setup();
+
+    onMessage(JSON.stringify({ type: 'submit', prompt }));
+
+    // The session must never see it: once it does, the value is re-emitted as `user_message` to
+    // every attached client inside a frame whose `content` is declared `string`.
+    expect(submit).not.toHaveBeenCalled();
+    expect(sent.some((msg) => msg.type === 'protocol_error')).toBe(true);
+  });
+
+  it('still refuses an EMPTY prompt, which the falsy guard already caught', () => {
+    // The control for the guard that exists. A type check that replaced it would otherwise let
+    // `''` through — a regression hidden by the new assertions above.
+    const { submit, sent, onMessage } = setup();
+
+    onMessage(JSON.stringify({ type: 'submit', prompt: '' }));
+
+    expect(submit).not.toHaveBeenCalled();
+    expect(sent.some((msg) => msg.type === 'protocol_error')).toBe(true);
+  });
+
+  it('still accepts a real string prompt, so the refusal is about shape and not about submitting', () => {
+    const { submit, onMessage } = setup();
+
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'hello' }));
+
+    expect(submit).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/usage-report-carrier.test.ts

@@ -0,0 +1,98 @@
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, it, expect, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+import type { TServerMessage } from '../wire-messages.js';
+import type { IUsageBySourceReport } from '@robota-sdk/agent-interface-analytics';
+
+/**
+ * SELFHOST-004 P5 (TC-08): the new `usage_report` TServerMessage variant carries the assembled
+ * trace/cost read-model (per-operation span timeline + cost-by-source) across the sidecar boundary.
+ * No pre-existing variant carries per-op `durationMs` or per-source `costUsd`; this test proves the
+ * carrier is well-typed AND survives JSON serialization (the WS stream is JSON) so the timeline/cost
+ * actually reaches the GUI — not assumed "free".
+ */
+describe('SELFHOST-004 TC-08 — usage_report server-message carrier', () => {
+  const report: IUsageBySourceReport = {
+    sessionId: 'sess-1',
+    totalTokens: 300,
+    promptTokens: 200,
+    completionTokens: 100,
+    costUsd: 0.0015,
+    costExact: true,
+    bySource: [
+      {
+        key: 'main:',
+        source: { scope: 'main', label: 'main thread' },
+        label: 'main thread',
+        promptTokens: 200,
+        completionTokens: 100,
+        totalTokens: 300,
+        turns: 1,
+        percentage: 100,
+        costUsd: 0.0015,
+        costExact: true,
+      },
+    ],
+    timeline: [
+      {
+        turnIndex: 0,
+        source: { scope: 'main', label: 'main thread' },
+        label: 'main thread',
+        spans: [
+          { spanId: 'span_a', op: 'read', durationMs: 5 },
+          { spanId: 'span_b', op: 'grep', durationMs: 7 },
+        ],
+        totalDurationMs: 12,
+      },
+    ],
+  };
+
+  it('is assignable to TServerMessage and carries per-op durationMs + per-source costUsd together', () => {
+    const message: TServerMessage = { type: 'usage_report', report };
+
+    // narrow by discriminant — the carrier’s payload is the assembled read-model
+    expect(message.type).toBe('usage_report');
+    if (message.type !== 'usage_report') throw new Error('unreachable');
+
+    // per-op timing rides the carrier (the datum no prior variant carried)
+    expect(message.report.timeline[0]?.spans.map((s) => s.durationMs)).toEqual([5, 7]);
+    // per-source cost rides the carrier
+    expect(message.report.bySource[0]?.costUsd).toBeCloseTo(0.0015, 6);
+    expect(message.report.costUsd).toBeCloseTo(0.0015, 6);
+  });
+
+  it('survives JSON round-trip (the WS stream) with the timeline + cost intact', () => {
+    const message: TServerMessage = { type: 'usage_report', report };
+
+    const wire = JSON.parse(JSON.stringify(message)) as TServerMessage;
+    expect(wire).toEqual(message);
+    if (wire.type !== 'usage_report') throw new Error('unreachable');
+    expect(wire.report.timeline[0]?.totalDurationMs).toBe(12);
+    expect(wire.report.bySource[0]?.costUsd).toBeCloseTo(0.0015, 6);
+  });
+
+  it('requests are expressible via the get-usage-report client message', () => {
+    // compile-time proof the request variant exists (the GUI asks for the report)
+    const req = { type: 'get-usage-report' } as const;
+    expect(req.type).toBe('get-usage-report');
+  });
+
+  it('routes the request through the host producer and delivers the report', async () => {
+    const sent: TServerMessage[] = [];
+    const reporter = vi.fn().mockReturnValue(report);
+    const session = createTestInteractiveSession();
+    const { onMessage } = createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+      usageReporter: reporter,
+    });
+
+    onMessage(JSON.stringify({ type: 'get-usage-report' }));
+    await Promise.resolve();
+
+    expect(reporter).toHaveBeenCalledWith(session);
+    expect(sent).toContainEqual({ type: 'usage_report', report });
+  });
+});

package/src/__tests__/ws-broadcast-events.test.ts

@@ -0,0 +1,94 @@
+/**
+ * CMD-004 Phase 2 Stage E — broadcast session events over the WS transport.
+ *
+ * The spec's final carriers: `session_renamed` and `history_cleared` are BROADCAST session events —
+ * every attached surface (including co-driving ones) receives them, so titles update and transcripts
+ * refresh everywhere. Unlike `ui_intent` (requester-routed), these are never filtered by driver id.
+ *
+ * Red-first evidence: against pre-Stage-E code neither event is forwarded by
+ * `subscribeSessionEvents` at all — a co-driving surface's title/transcript went stale.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TServerMessage } from '../wire-messages.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+type TEmittingSession = IInteractiveSession & {
+  _emit: (event: string, ...args: unknown[]) => void;
+};
+
+function createMockSession(): TEmittingSession {
+  const listeners = new Map<string, Set<(...args: unknown[]) => void>>();
+  return {
+    // ARCH-012: required. This double feeds `subscribeSessionEvents`, which calls it on every
+    // turn-authored event — omitting it throws the moment a case emits one.
+    getActiveDriverId: () => null,
+    on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }),
+    off: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+      listeners.get(event)?.delete(handler);
+    }),
+    _emit: (event: string, ...args: unknown[]) => {
+      listeners.get(event)?.forEach((h) => h(...args));
+    },
+  } as unknown as TEmittingSession;
+}
+
+/** Two real WS handlers (surfaces) over ONE session — the co-driving topology. */
+function setupTwoSurfaces(): {
+  session: TEmittingSession;
+  sentA: TServerMessage[];
+  sentB: TServerMessage[];
+} {
+  const session = createMockSession();
+  const sentA: TServerMessage[] = [];
+  const sentB: TServerMessage[] = [];
+  createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((m) => sentA.push(m), vi.fn()),
+    driverId: 'device-A',
+  });
+  createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((m) => sentB.push(m), vi.fn()),
+    driverId: 'device-B',
+  });
+  return { session, sentA, sentB };
+}
+
+describe('CMD-004 Stage E — session_renamed / history_cleared broadcast to EVERY surface', () => {
+  it('session_renamed reaches both attached surfaces (titles update everywhere)', () => {
+    const { session, sentA, sentB } = setupTwoSurfaces();
+
+    session._emit('session_renamed', { name: 'Renamed Everywhere' });
+
+    const expected = { type: 'session_renamed', event: { name: 'Renamed Everywhere' } };
+    expect(sentA).toEqual([expected]);
+    expect(sentB).toEqual([expected]);
+  });
+
+  it('history_cleared reaches both attached surfaces (transcripts refresh everywhere)', () => {
+    const { session, sentA, sentB } = setupTwoSurfaces();
+
+    session._emit('history_cleared');
+
+    expect(sentA).toEqual([{ type: 'history_cleared' }]);
+    expect(sentB).toEqual([{ type: 'history_cleared' }]);
+  });
+
+  it('#3189: session_switched reaches both attached surfaces (each re-reads the new session)', () => {
+    const { session, sentA, sentB } = setupTwoSurfaces();
+
+    session._emit('session_switched', { sessionId: 'session-2' });
+
+    const expected = { type: 'session_switched', event: { sessionId: 'session-2' } };
+    expect(sentA).toEqual([expected]);
+    expect(sentB).toEqual([expected]);
+  });
+});

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/background-messages.ts

@@ -0,0 +1,169 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TBackgroundControlAction, TClientMessage } from './wire-messages.js';
+
+export function handleBackgroundQueryMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<
+    TClientMessage,
+    | { type: 'get-background-tasks' | 'get-background-task' | 'read-background-task-log' }
+    | {
+        type:
+          'get-background-job-groups' | 'get-background-job-group' | 'wait-background-job-group';
+      }
+  >,
+): void {
+  if (msg.type === 'get-background-tasks') {
+    deliver({ type: 'background_tasks', tasks: session.listBackgroundTasks(msg.filter) });
+    return;
+  }
+  if (msg.type === 'get-background-task') {
+    sendBackgroundTaskSnapshot(session, deliver, msg);
+    return;
+  }
+  if (msg.type === 'get-background-job-groups') {
+    deliver({ type: 'background_job_groups', groups: session.listBackgroundJobGroups() });
+    return;
+  }
+  if (msg.type === 'get-background-job-group') {
+    sendBackgroundJobGroupSnapshot(session, deliver, msg);
+    return;
+  }
+  if (msg.type === 'wait-background-job-group') {
+    sendBackgroundJobGroupWaitResult(session, deliver, msg);
+    return;
+  }
+  sendBackgroundTaskLogPage(session, deliver, msg);
+}
+
+export function handleBackgroundControlMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<
+    TClientMessage,
+    { type: 'cancel-background-task' | 'close-background-task' | 'send-background-task' }
+  >,
+): void {
+  if (!msg.taskId) {
+    deliver({ type: 'protocol_error', message: 'taskId is required' });
+    return;
+  }
+  if (msg.type === 'cancel-background-task') {
+    sendBackgroundTaskControlResult(
+      deliver,
+      'cancel',
+      msg.taskId,
+      session.cancelBackgroundTask(msg.taskId, msg.reason),
+    );
+    return;
+  }
+  if (msg.type === 'close-background-task') {
+    sendBackgroundTaskControlResult(
+      deliver,
+      'close',
+      msg.taskId,
+      session.closeBackgroundTask(msg.taskId),
+    );
+    return;
+  }
+  sendBackgroundTaskInput(session, deliver, msg);
+}
+
+function sendBackgroundTaskSnapshot(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-background-task' }>,
+): void {
+  if (!msg.taskId) {
+    deliver({ type: 'protocol_error', message: 'taskId is required' });
+    return;
+  }
+  deliver({
+    type: 'background_task',
+    taskId: msg.taskId,
+    task: session.getBackgroundTask(msg.taskId) ?? null,
+  });
+}
+
+function sendBackgroundTaskLogPage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'read-background-task-log' }>,
+): void {
+  if (!msg.taskId) {
+    deliver({ type: 'protocol_error', message: 'taskId is required' });
+    return;
+  }
+  session.readBackgroundTaskLog(msg.taskId, msg.cursor).then(
+    (page) => deliver({ type: 'background_task_log', taskId: msg.taskId, page }),
+    (error: Error) => deliver({ type: 'protocol_error', message: error.message }),
+  );
+}
+
+function sendBackgroundJobGroupSnapshot(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'get-background-job-group' }>,
+): void {
+  if (!msg.groupId) {
+    deliver({ type: 'protocol_error', message: 'groupId is required' });
+    return;
+  }
+  deliver({
+    type: 'background_job_group',
+    groupId: msg.groupId,
+    group: session.getBackgroundJobGroup(msg.groupId) ?? null,
+  });
+}
+
+function sendBackgroundJobGroupWaitResult(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'wait-background-job-group' }>,
+): void {
+  if (!msg.groupId) {
+    deliver({ type: 'protocol_error', message: 'groupId is required' });
+    return;
+  }
+  session.waitBackgroundJobGroup(msg.groupId).then(
+    (group) => deliver({ type: 'background_job_group', groupId: msg.groupId, group }),
+    (error: Error) => deliver({ type: 'protocol_error', message: error.message }),
+  );
+}
+
+function sendBackgroundTaskInput(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: Extract<TClientMessage, { type: 'send-background-task' }>,
+): void {
+  if (!msg.input) {
+    deliver({ type: 'protocol_error', message: 'input is required' });
+    return;
+  }
+  sendBackgroundTaskControlResult(
+    deliver,
+    'send',
+    msg.taskId,
+    session.sendBackgroundTask(msg.taskId, msg.input),
+  );
+}
+
+function sendBackgroundTaskControlResult(
+  deliver: TOutboundDeliver,
+  action: TBackgroundControlAction,
+  taskId: string,
+  operation: Promise<void>,
+): void {
+  operation.then(
+    () => deliver({ type: 'background_task_control_result', action, taskId, success: true }),
+    (error: Error) =>
+      deliver({
+        type: 'background_task_control_result',
+        action,
+        taskId,
+        success: false,
+        message: error.message,
+      }),
+  );
+}