@robota-sdk/agent-transport 3.0.0-beta.83 → 3.0.0-beta.84

package/src/__tests__/session-directory-messages.test.ts

@@ -14,6 +14,7 @@ import type {
   ISessionDirectory,
   ISessionListing,
   TSessionChangeRefusalCode,
+  TSessionDeleteRefusalCode,
 } from '@robota-sdk/agent-interface-session';
 
 const listing: ISessionListing = {
@@ -35,6 +36,8 @@ function createDirectory(overrides: Partial<ISessionDirectory> = {}): ISessionDi
     listSessions: vi.fn(() => listing),
     switchSession: vi.fn(async () => undefined),
     newSession: vi.fn(async () => undefined),
+    renameSession: vi.fn(async () => undefined),
+    deleteSession: vi.fn(async () => undefined),
     ...overrides,
   };
 }
@@ -58,6 +61,11 @@ function refusal(code: TSessionChangeRefusalCode, message: string): Error {
   return Object.assign(new Error(message), { name: 'SessionChangeRefusal', code });
 }
 
+/** The shape `SessionDeleteRefusal` (agent-framework) has; this package cannot import the class. */
+function deleteRefusal(code: TSessionDeleteRefusalCode, message: string): Error {
+  return Object.assign(new Error(message), { name: 'SessionDeleteRefusal', code });
+}
+
 const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
 
 describe('session directory messages (#3189)', () => {
@@ -190,3 +198,125 @@ describe('session directory messages (#3189)', () => {
     expect(directory.newSession).not.toHaveBeenCalled();
   });
 });
+
+describe('rename-session (#3289 §1)', () => {
+  it('renames and answers session_renamed_in_list, correlated by requestId', async () => {
+    const directory = createDirectory();
+    const client = attach({ directory });
+    client.send({ type: 'rename-session', sessionId: 'session-2', name: 'Renamed', requestId: 'r1' });
+    await flush();
+    expect(directory.renameSession).toHaveBeenCalledExactlyOnceWith('session-2', 'Renamed');
+    expect(client.sent).toEqual([
+      { type: 'session_renamed_in_list', requestId: 'r1', sessionId: 'session-2', name: 'Renamed' },
+    ]);
+  });
+
+  it('answers session_rename_failed with the reason when the directory refuses', async () => {
+    const directory = createDirectory({
+      renameSession: vi.fn(async () => {
+        throw new Error('No session session-2 in this workspace.');
+      }),
+    });
+    const client = attach({ directory });
+    client.send({ type: 'rename-session', sessionId: 'session-2', name: 'x', requestId: 'r1' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'session_rename_failed',
+        requestId: 'r1',
+        message: 'No session session-2 in this workspace.',
+      },
+    ]);
+  });
+
+  it('answers not_available on a host without a directory', () => {
+    const client = attach({});
+    client.send({ type: 'rename-session', sessionId: 'session-2', name: 'x', requestId: 'r1' });
+    expect(client.sent).toEqual([
+      {
+        type: 'session_rename_failed',
+        requestId: 'r1',
+        message: 'Sessions cannot be renamed on this host.',
+      },
+    ]);
+  });
+
+  it('refuses an observer', async () => {
+    const directory = createDirectory();
+    const observer = attach({ directory, role: 'observe' });
+    observer.send({ type: 'rename-session', sessionId: 'session-2', name: 'x', requestId: 'r1' });
+    expect(observer.sent).toEqual([
+      { type: 'protocol_error', message: 'Not permitted for an observer: rename-session' },
+    ]);
+    expect(directory.renameSession).not.toHaveBeenCalled();
+  });
+});
+
+describe('delete-session round-trip (#3289 §1)', () => {
+  it('deletes and answers session_deleted, correlated by requestId', async () => {
+    const directory = createDirectory();
+    const client = attach({ directory });
+    client.send({ type: 'delete-session', sessionId: 'session-2', requestId: 'r1' });
+    await flush();
+    expect(directory.deleteSession).toHaveBeenCalledExactlyOnceWith('session-2');
+    expect(client.sent).toEqual([
+      { type: 'session_deleted', requestId: 'r1', sessionId: 'session-2' },
+    ]);
+  });
+
+  it('answers session_delete_failed with the refusal code and reason', async () => {
+    const directory = createDirectory({
+      deleteSession: vi.fn(async () => {
+        throw deleteRefusal('live_elsewhere', 'Another client is on this session.');
+      }),
+    });
+    const client = attach({ directory });
+    client.send({ type: 'delete-session', sessionId: 'session-2', requestId: 'r1' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'session_delete_failed',
+        requestId: 'r1',
+        code: 'live_elsewhere',
+        message: 'Another client is on this session.',
+      },
+    ]);
+  });
+
+  it('reports code failed for an error that is not a declared delete refusal', async () => {
+    const directory = createDirectory({
+      deleteSession: vi.fn(async () => {
+        throw new Error('disk full');
+      }),
+    });
+    const client = attach({ directory });
+    client.send({ type: 'delete-session', sessionId: 'session-2', requestId: 'r1' });
+    await flush();
+    expect(client.sent).toEqual([
+      { type: 'session_delete_failed', requestId: 'r1', code: 'failed', message: 'disk full' },
+    ]);
+  });
+
+  it('answers not_available on a host without a directory', () => {
+    const client = attach({});
+    client.send({ type: 'delete-session', sessionId: 'session-2', requestId: 'r1' });
+    expect(client.sent).toEqual([
+      {
+        type: 'session_delete_failed',
+        requestId: 'r1',
+        code: 'not_available',
+        message: 'Sessions cannot be deleted on this host.',
+      },
+    ]);
+  });
+
+  it('refuses an observer', async () => {
+    const directory = createDirectory();
+    const observer = attach({ directory, role: 'observe' });
+    observer.send({ type: 'delete-session', sessionId: 'session-2', requestId: 'r1' });
+    expect(observer.sent).toEqual([
+      { type: 'protocol_error', message: 'Not permitted for an observer: delete-session' },
+    ]);
+    expect(directory.deleteSession).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/session-error-classification.test.ts

@@ -0,0 +1,113 @@
+import {
+  AuthenticationError,
+  ModelNotAvailableError,
+  NetworkError,
+  ProviderError,
+  RateLimitError,
+} from '@robota-sdk/agent-core';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { classifySessionErrorForWire } from '../session-error-classification.js';
+import { subscribeSessionEvents } from '../session-events.js';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+/**
+ * #3289 §3: the `error` wire frame gains a typed `code`/`provider`/`retryAfterSeconds` alongside the
+ * raw `message`, so a renderer can say what happened in plain words instead of showing the vendor's
+ * raw text. Additive — an error this classification does not recognize carries no `code` at all,
+ * which is exactly today's behavior (unchanged).
+ */
+describe('classifySessionErrorForWire', () => {
+  it('classifies an AuthenticationError', () => {
+    expect(classifySessionErrorForWire(new AuthenticationError('bad key', 'anthropic'))).toEqual({
+      code: 'auth',
+      provider: 'anthropic',
+    });
+  });
+
+  it('classifies a RateLimitError, carrying retryAfterSeconds when the provider gave one', () => {
+    expect(
+      classifySessionErrorForWire(new RateLimitError('slow down', 30, 'openai')),
+    ).toEqual({ code: 'rate_limit', provider: 'openai', retryAfterSeconds: 30 });
+    expect(classifySessionErrorForWire(new RateLimitError('slow down', undefined, 'openai'))).toEqual(
+      { code: 'rate_limit', provider: 'openai' },
+    );
+  });
+
+  it('classifies a ModelNotAvailableError, carrying the model when the failure named one', () => {
+    expect(
+      classifySessionErrorForWire(new ModelNotAvailableError('claude-x', 'anthropic')),
+    ).toEqual({ code: 'model_unavailable', provider: 'anthropic', model: 'claude-x' });
+    expect(
+      classifySessionErrorForWire(new ModelNotAvailableError(undefined, 'anthropic')),
+    ).toEqual({ code: 'model_unavailable', provider: 'anthropic' });
+  });
+
+  it('classifies a NetworkError, carrying the provider when the failure named one', () => {
+    expect(
+      classifySessionErrorForWire(new NetworkError('down', undefined, undefined, 'anthropic')),
+    ).toEqual({
+      code: 'network',
+      provider: 'anthropic',
+    });
+    expect(classifySessionErrorForWire(new NetworkError('down'))).toEqual({ code: 'network' });
+  });
+
+  it('classifies a generic ProviderError as the fallback "provider" code', () => {
+    expect(classifySessionErrorForWire(new ProviderError('failed', 'gemini'))).toEqual({
+      code: 'provider',
+      provider: 'gemini',
+    });
+  });
+
+  it('classifies through a wrapping layer (e.g. a higher-level "Conversation failed")', () => {
+    const wrapped = new ProviderError(
+      'Conversation failed',
+      'conversation',
+      new AuthenticationError('bad key', 'openai'),
+    );
+    expect(classifySessionErrorForWire(wrapped)).toEqual({ code: 'auth', provider: 'openai' });
+  });
+
+  it('leaves an unrelated error uncoded, so the caller keeps showing its raw message unchanged', () => {
+    expect(classifySessionErrorForWire(new Error('some internal failure'))).toEqual({});
+  });
+});
+
+describe('the error wire frame carries the classification (#3289 §3)', () => {
+  it('adds code/provider/retryAfterSeconds onto the delivered error frame', () => {
+    const send = vi.fn();
+    const session = createTestInteractiveSession({ on: vi.fn(), off: vi.fn() });
+    subscribeSessionEvents(session, createOutboundDelivery(send, vi.fn()));
+
+    const onError = vi.mocked(session.on).mock.calls.find(([name]) => name === 'error')?.[1] as (
+      error: Error,
+    ) => void;
+    onError(new RateLimitError('slow down', 12, 'anthropic'));
+
+    expect(send).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'error',
+        message: 'Rate Limit Error: slow down',
+        code: 'rate_limit',
+        provider: 'anthropic',
+        retryAfterSeconds: 12,
+      }),
+    );
+  });
+
+  it('delivers an unrelated error with no code, exactly as before', () => {
+    const send = vi.fn();
+    const session = createTestInteractiveSession({ on: vi.fn(), off: vi.fn() });
+    subscribeSessionEvents(session, createOutboundDelivery(send, vi.fn()));
+
+    const onError = vi.mocked(session.on).mock.calls.find(([name]) => name === 'error')?.[1] as (
+      error: Error,
+    ) => void;
+    onError(new Error('boom'));
+
+    expect(send).toHaveBeenCalledWith({ type: 'error', message: 'boom' });
+  });
+});

package/src/__tests__/session-message-handler-observe.test.ts

@@ -20,6 +20,9 @@ type TListener = (...args: unknown[]) => void;
 function createSession(): IInteractiveSession & {
   emit: (event: string, ...args: unknown[]) => void;
   listenerCount: (event: string) => number;
+  // #3282 §4c: `Partial<ISessionProjectRead>` — not part of `IInteractiveSession`, so it is assigned
+  // ad hoc (below) rather than passed to `createTestInteractiveSession`'s strict literal.
+  readProjectStatus: ReturnType<typeof vi.fn>;
 } {
   const listeners = new Map<string, Set<TListener>>();
   const session = createTestInteractiveSession({
@@ -43,6 +46,7 @@ function createSession(): IInteractiveSession & {
     }) as IInteractiveSession['off'],
   });
   return Object.assign(session, {
+    readProjectStatus: vi.fn().mockResolvedValue({ kind: 'not-a-repository' }),
     emit: (event: string, ...args: unknown[]) => {
       listeners.get(event)?.forEach((handler) => handler(...args));
     },
@@ -106,11 +110,31 @@ describe('observe role', () => {
     observer.send({ type: 'get-messages' });
     observer.send({ type: 'get-executing' });
     expect(observer.sent).toEqual([
-      { type: 'messages', messages: [{ role: 'user', content: 'hi' }] },
+      // #3288 §2: `display` rides the same frame (the test double's default projects to `[]`).
+      { type: 'messages', messages: [{ role: 'user', content: 'hi' }], display: [] },
       { type: 'executing', executing: true },
     ]);
   });
 
+  it('#3282 §4c: reads the Project panel status — read-only, so an observer may too', async () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'project-status', requestId: 'ps-1' });
+    await Promise.resolve();
+    expect(observer.sent).toEqual([
+      { type: 'project_status', requestId: 'ps-1', result: { kind: 'not-a-repository' } },
+    ]);
+  });
+
+  it('#3282 §4: reads the agent switcher roster, a query, never a write', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'get-agent-definitions', requestId: 'req-agents-1' });
+    expect(observer.sent).toEqual([
+      { type: 'agent_definitions', requestId: 'req-agents-1', agents: [], current: 'general-purpose' },
+    ]);
+  });
+
   it('#3186: reads the session status and the command catalog, which every client shows', () => {
     const session = createSession();
     const observer = attach(session, 'observe');

package/src/__tests__/session-message-handler.test.ts

@@ -187,6 +187,44 @@ describe('WebSocket Transport Handler', () => {
     expect(sent).toEqual([{ type: 'session_status', status: session.getStatusSnapshot() }]);
   });
 
+  it('#3282 §2: list-models sends the model list, echoing requestId', () => {
+    const { onMessage, session, sent } = setup();
+    const snapshot = {
+      groups: [
+        {
+          profileName: 'anthropic',
+          providerLabel: 'Anthropic',
+          models: [{ id: 'claude-sonnet-4-6', label: 'Claude Sonnet 4.6' }],
+        },
+      ],
+      currentProfile: 'anthropic',
+      currentModel: 'claude-sonnet-4-6',
+    };
+    Object.assign(session, { listModels: vi.fn().mockReturnValue(snapshot) });
+
+    onMessage(JSON.stringify({ type: 'list-models', requestId: 'req-models-1' }));
+
+    expect(sent).toEqual([{ type: 'model_list', requestId: 'req-models-1', ...snapshot }]);
+  });
+
+  it('#3282 §4: get-agent-definitions sends the roster and the current default, echoing requestId', () => {
+    const { onMessage, session, sent } = setup();
+    const agents = [
+      { name: 'general-purpose', description: 'General-purpose task execution agent.', definedIn: 'Built-in' },
+      { name: 'Explore', description: 'Read-only codebase exploration agent.', definedIn: 'Built-in' },
+    ];
+    Object.assign(session, {
+      listAgentDefinitions: vi.fn().mockReturnValue(agents),
+      getDefaultAgentType: vi.fn().mockReturnValue('Explore'),
+    });
+
+    onMessage(JSON.stringify({ type: 'get-agent-definitions', requestId: 'req-agents-1' }));
+
+    expect(sent).toEqual([
+      { type: 'agent_definitions', requestId: 'req-agents-1', agents, current: 'Explore' },
+    ]);
+  });
+
   it('get-executing sends executing status', () => {
     const { onMessage, sent } = setup();
     onMessage(JSON.stringify({ type: 'get-executing' }));
@@ -367,10 +405,11 @@ describe('WebSocket Transport Handler', () => {
     // A transport-origin command is an untrusted remote origin — the handler tags it `'remote'` so the session
     // applies its (optional, allow-by-default) remote-command policy.
     // CMD-004 Phase 2: the 4th arg is the command-origin driver id — undefined when the handler has
-    // no server-assigned id (unattributed; a client-sent id is NEVER trusted).
+    // no server-assigned id (unattributed; a client-sent id is NEVER trusted). The 5th (#3282 §4
+    // part b-2) is this carrier's locality — undefined here since this handler was not given one.
     expect(
       (session as unknown as { executeCommand: ReturnType<typeof vi.fn> }).executeCommand,
-    ).toHaveBeenCalledWith('clear', '', 'remote', undefined);
+    ).toHaveBeenCalledWith('clear', '', 'remote', undefined, undefined);
   });
 
   it('command carries the SERVER-ASSIGNED driver id as the command origin (CMD-004 Phase 2)', async () => {
@@ -385,7 +424,22 @@ describe('WebSocket Transport Handler', () => {
     await new Promise((r) => setTimeout(r, 10));
     expect(
       (session as unknown as { executeCommand: ReturnType<typeof vi.fn> }).executeCommand,
-    ).toHaveBeenCalledWith('settings', '', 'remote', 'device-7');
+    ).toHaveBeenCalledWith('settings', '', 'remote', 'device-7', undefined);
+  });
+
+  it("forwards this carrier's commandSurfaceLocality to executeCommand (#3282 §4 part b-2)", async () => {
+    const session = createMockSession();
+    const sent: TServerMessage[] = [];
+    const { onMessage } = createSessionMessageHandler({
+      session,
+      deliver: createOutboundDelivery((msg) => sent.push(msg), vi.fn()),
+      commandSurfaceLocality: 'remote',
+    });
+    onMessage(JSON.stringify({ type: 'command', name: 'plugin', args: 'install demo@community' }));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(
+      (session as unknown as { executeCommand: ReturnType<typeof vi.fn> }).executeCommand,
+    ).toHaveBeenCalledWith('plugin', 'install demo@community', 'remote', undefined, 'remote');
   });
 
   it('forwards ui_intent session events to the requesting client (CMD-004 Phase 2)', () => {

package/src/__tests__/settings-messages.test.ts

@@ -0,0 +1,193 @@
+/**
+ * #3282 §4a: the GUI Settings screen reads and writes through `get-settings`/`update-settings`,
+ * correlated by `requestId` and answered by `settings` or `settings_error` — the same request/error
+ * shape as `get-personal-usage-report`. The host-owned reporter decides what a read or write means;
+ * this layer only correlates and carries the result.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { ISettingsReporter, TSettingsUpdateOutcome } from '../settings-messages.js';
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { ISettingsSnapshot } from '@robota-sdk/agent-interface-session';
+
+const snapshot: ISettingsSnapshot = {
+  language: { current: 'en', recommended: [], appliesNote: 'Takes effect after a restart.' },
+  outputStyle: { current: 'default', choices: [] },
+  preset: { current: 'default', choices: [], skipsAllChecksPresetIds: [] },
+  permissionMode: { current: 'default', choices: [], skipsAllChecksMode: 'bypassPermissions' },
+  permissionRules: [],
+  sandbox: { enabled: true, available: true, description: 'Confines shell commands.' },
+  mcp: { servers: [] },
+  plugins: { plugins: [], canInstall: true },
+  providers: { profiles: [] },
+};
+
+function createReporter(overrides: Partial<ISettingsReporter> = {}): ISettingsReporter {
+  return {
+    getSettings: vi.fn(() => snapshot),
+    updateSettings: vi.fn(
+      (): TSettingsUpdateOutcome => ({ ok: true, settings: snapshot }),
+    ),
+    ...overrides,
+  };
+}
+
+function attach(
+  options: {
+    reporter?: ISettingsReporter;
+    role?: 'drive' | 'observe';
+    commandSurfaceLocality?: 'local' | 'remote';
+  } = {},
+): {
+  sent: TServerMessage[];
+  send: (message: TClientMessage) => void;
+} {
+  const sent: TServerMessage[] = [];
+  const { onMessage } = createSessionMessageHandler({
+    session: createTestInteractiveSession(),
+    deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+    ...(options.reporter ? { settingsReporter: options.reporter } : {}),
+    ...(options.role ? { role: options.role } : {}),
+    ...(options.commandSurfaceLocality
+      ? { commandSurfaceLocality: options.commandSurfaceLocality }
+      : {}),
+  });
+  return { sent, send: (message) => onMessage(JSON.stringify(message)) };
+}
+
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('settings messages (#3282 §4a)', () => {
+  it('answers get-settings with the reporter snapshot, correlated by requestId', async () => {
+    const reporter = createReporter();
+    const client = attach({ reporter });
+    client.send({ type: 'get-settings', requestId: 'r1' });
+    await flush();
+    expect(client.sent).toEqual([{ type: 'settings', requestId: 'r1', settings: snapshot }]);
+  });
+
+  it('answers not_available when the host has no settings reporter', async () => {
+    const client = attach({});
+    client.send({ type: 'get-settings', requestId: 'r1' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'settings_error',
+        requestId: 'r1',
+        code: 'not_available',
+        message: 'Settings are not available on this host.',
+      },
+    ]);
+  });
+
+  it('applies a patch through the reporter and answers with the fresh snapshot', async () => {
+    const reporter = createReporter();
+    const client = attach({ reporter });
+    const patch = { field: 'outputStyle' as const, styleId: 'concise' };
+    client.send({ type: 'update-settings', requestId: 'r2', patch });
+    await flush();
+    expect(reporter.updateSettings).toHaveBeenCalledOnce();
+    expect(vi.mocked(reporter.updateSettings).mock.calls[0]?.[1]).toEqual(patch);
+    expect(client.sent).toEqual([{ type: 'settings', requestId: 'r2', settings: snapshot }]);
+  });
+
+  it('reports a refused patch as settings_error with the reporter code and message, writing nothing', async () => {
+    const reporter = createReporter({
+      updateSettings: vi.fn(
+        (): TSettingsUpdateOutcome => ({
+          ok: false,
+          code: 'refused',
+          message: 'Entering "bypassPermissions" is blocked for this workspace.',
+        }),
+      ),
+    });
+    const client = attach({ reporter });
+    client.send({
+      type: 'update-settings',
+      requestId: 'r3',
+      patch: { field: 'permissionMode', mode: 'bypassPermissions' },
+    });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'settings_error',
+        requestId: 'r3',
+        code: 'refused',
+        message: 'Entering "bypassPermissions" is blocked for this workspace.',
+      },
+    ]);
+  });
+
+  it('reports a thrown error from the reporter as update_failed', async () => {
+    const reporter = createReporter({
+      updateSettings: vi.fn(() => {
+        throw new Error('disk full');
+      }),
+    });
+    const client = attach({ reporter });
+    client.send({
+      type: 'update-settings',
+      requestId: 'r4',
+      patch: { field: 'language', language: 'ko' },
+    });
+    await flush();
+    expect(client.sent).toEqual([
+      { type: 'settings_error', requestId: 'r4', code: 'update_failed', message: 'disk full' },
+    ]);
+  });
+
+  it('lets an observer read settings but never write them', async () => {
+    const reporter = createReporter();
+    const observer = attach({ reporter, role: 'observe' });
+    observer.send({ type: 'get-settings', requestId: 'r5' });
+    observer.send({
+      type: 'update-settings',
+      requestId: 'r6',
+      patch: { field: 'sandbox', enabled: false },
+    });
+    await flush();
+    // The observer-role refusal is synchronous; the reporter's (possibly async) snapshot reply is
+    // not, so it lands second even though `get-settings` was sent first.
+    expect(observer.sent).toEqual([
+      { type: 'protocol_error', message: 'Not permitted for an observer: update-settings' },
+      { type: 'settings', requestId: 'r5', settings: snapshot },
+    ]);
+    expect(reporter.updateSettings).not.toHaveBeenCalled();
+  });
+
+  it('forwards this carrier\'s commandSurfaceLocality to both a read and a write (#3282 §4 part b-2)', async () => {
+    const reporter = createReporter();
+    const client = attach({ reporter, commandSurfaceLocality: 'remote' });
+    client.send({ type: 'get-settings', requestId: 'r7' });
+    client.send({
+      type: 'update-settings',
+      requestId: 'r8',
+      patch: { field: 'reloadMcpServers' },
+    });
+    await flush();
+    expect(vi.mocked(reporter.getSettings).mock.calls[0]?.[1]).toBe('remote');
+    expect(vi.mocked(reporter.updateSettings).mock.calls[0]?.[2]).toBe('remote');
+  });
+
+  it.each([
+    { field: 'mcpServerEnabled', serverId: 'docs', enabled: false },
+    { field: 'reloadMcpServers' },
+    { field: 'pluginEnabled', pluginId: 'formatter@robota', enabled: true },
+    { field: 'reloadPlugins' },
+    { field: 'installPlugin', pluginId: 'linter@robota' },
+    { field: 'uninstallPlugin', pluginId: 'formatter@robota' },
+  ] as const)('round-trips the $field patch through the reporter', async (patch) => {
+    const reporter = createReporter();
+    const client = attach({ reporter });
+    client.send({ type: 'update-settings', requestId: 'rt', patch });
+    await flush();
+    expect(reporter.updateSettings).toHaveBeenCalledOnce();
+    expect(vi.mocked(reporter.updateSettings).mock.calls[0]?.[1]).toEqual(patch);
+    expect(client.sent).toEqual([{ type: 'settings', requestId: 'rt', settings: snapshot }]);
+  });
+});

package/src/index.ts

@@ -57,6 +57,7 @@ export { isObserverMessageType } from './observer-messages.js';
 export type { TProtocolSessionEventClassification } from './session-events.js';
 export type { IProtocolSession } from './protocol-session.js';
 export type {
+  IWireAgentDefinitionSummary,
   IWireHistoryEntry,
   TClientMessage,
   TServerMessage,
@@ -88,6 +89,9 @@ export type {
   TResumeSink,
   IAttachOptions,
 } from './session-resume-bridge.js';
+// #3282 §4a: the Settings screen's host-owned read/write seam (parallels `IUsageQueryReporters`).
+export { handleSettingsMessage, isSettingsMessage } from './settings-messages.js';
+export type { ISettingsReporter, TSettingsUpdateOutcome } from './settings-messages.js';
 
 // SEC-008 admission is NOT here: `src/node/admission.ts` mints and compares transport tokens with
 // `node:crypto`. A browser never mints one — it presents one it was handed — so the exclusion costs