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

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

@@ -10,6 +10,7 @@ import { createSessionMessageHandler } from '../session-message-handler.js';
 import { PROTOCOL_SESSION_EVENT_CLASSIFICATION } from '../session-events.js';
 import type { TServerMessage } from '../wire-messages.js';
 import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { ICommandListEntry } from '@robota-sdk/agent-interface-command';
 import type {
   IBackgroundJobGroupState,
   IExecutionWorkspaceEvent,
@@ -157,6 +158,73 @@ describe('WebSocket Transport Handler', () => {
     expect(sent[0]!.type).toBe('context');
   });
 
+  it('#3186: get-commands sends the commands and skills a client can offer', () => {
+    const { onMessage, session, sent } = setup();
+    const command: ICommandListEntry = {
+      name: 'help',
+      description: 'Show commands',
+      modelInvocable: false,
+      runner: 'runtime',
+    };
+    const skill = {
+      name: 'parity-demo',
+      description: 'Demo',
+      source: 'project',
+      modelInvocable: true,
+      userInvocable: true,
+    };
+    Object.assign(session, {
+      listCommands: vi.fn().mockReturnValue([command]),
+      listSkills: vi.fn().mockReturnValue([skill]),
+    });
+    onMessage(JSON.stringify({ type: 'get-commands' }));
+    expect(sent).toEqual([{ type: 'commands', commands: [command], skills: [skill] }]);
+  });
+
+  it('#3186: get-status sends the session status snapshot', () => {
+    const { onMessage, session, sent } = setup();
+    onMessage(JSON.stringify({ type: 'get-status' }));
+    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' }));
@@ -166,7 +234,35 @@ describe('WebSocket Transport Handler', () => {
   it('get-pending sends pending prompt', () => {
     const { onMessage, sent } = setup();
     onMessage(JSON.stringify({ type: 'get-pending' }));
-    expect(sent[0]).toEqual({ type: 'pending', pending: null });
+    expect(sent[0]).toEqual({ type: 'pending', pending: null, pendingCount: 0 });
+  });
+
+  it('#3189: answers a submit with the queue once the prompt is taken, so a queued prompt shows', async () => {
+    const { onMessage, sent, session } = setup();
+    const mock = session as unknown as {
+      submit: ReturnType<typeof vi.fn>;
+      getPendingPrompt: ReturnType<typeof vi.fn>;
+      getPendingCount: ReturnType<typeof vi.fn>;
+    };
+    let queue: () => void = () => undefined;
+    // A turn is running: the session queues the prompt only after its own initialization yields.
+    mock.submit.mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          queue = () => {
+            mock.getPendingPrompt.mockReturnValue('follow-up');
+            mock.getPendingCount.mockReturnValue(1);
+            resolve();
+          };
+        }),
+    );
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'follow-up' }));
+    // A `get-pending` sent beside the submit is answered before the prompt is queued.
+    onMessage(JSON.stringify({ type: 'get-pending' }));
+    expect(sent).toEqual([{ type: 'pending', pending: null, pendingCount: 0 }]);
+    queue();
+    await new Promise((r) => setTimeout(r, 0));
+    expect(sent.at(-1)).toEqual({ type: 'pending', pending: 'follow-up', pendingCount: 1 });
   });
 
   it('get-background-tasks sends current background task list', () => {
@@ -309,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 () => {
@@ -327,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)', () => {
@@ -447,6 +559,29 @@ describe('WebSocket Transport Handler', () => {
     expect(sent).toEqual([{ type: 'protocol_error', message: 'command failed' }]);
   });
 
+  it("#3189: echoes a command's requestId on its result and on its failure, and on nothing else", async () => {
+    const { onMessage, sent, session } = setup();
+    const { executeCommand, submit } = session as unknown as {
+      executeCommand: ReturnType<typeof vi.fn>;
+      submit: ReturnType<typeof vi.fn>;
+    };
+    executeCommand.mockResolvedValueOnce({ message: 'done', success: true });
+    executeCommand.mockRejectedValueOnce(new Error('command failed'));
+    submit.mockRejectedValueOnce(new Error('A turn is running.'));
+    onMessage(JSON.stringify({ type: 'command', name: 'clear', requestId: 'c1' }));
+    onMessage(JSON.stringify({ type: 'command', name: 'broken', requestId: 'c2' }));
+    onMessage(JSON.stringify({ type: 'submit', prompt: 'hello' }));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(sent).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'command_result', name: 'clear', requestId: 'c1' }),
+        { type: 'protocol_error', message: 'command failed', requestId: 'c2' },
+        { type: 'protocol_error', message: 'A turn is running.' },
+      ]),
+    );
+    expect(sent).toHaveLength(3);
+  });
+
   it('forwards InteractiveSession events to client', () => {
     const { session, sent } = setup();
     (session as unknown as { _emit: (e: string, ...args: unknown[]) => void })._emit(

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/__tests__/ws-broadcast-events.test.ts

@@ -81,4 +81,14 @@ describe('CMD-004 Stage E — session_renamed / history_cleared broadcast to EVE
     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/client.ts

@@ -6,4 +6,12 @@ export {
   decodeServerMessage,
 } from './message-decoders.js';
 export type { TMessageDecodeResult } from './message-decoders.js';
-export type { TClientMessage, TServerMessage, TSeqServerMessage } from './wire-messages.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';
+export type {
+  IWireHistoryEntry,
+  TClientMessage,
+  TServerMessage,
+  TSeqServerMessage,
+  TWireExecutionResult,
+} from './wire-messages.js';

package/src/index.ts

@@ -33,9 +33,13 @@
  */
 
 export { createSessionMessageHandler } from './session-message-handler.js';
-export type { ISessionMessageHandlerOptions } from './session-message-handler.js';
+export type {
+  ISessionMessageHandlerOptions,
+  TSessionSurfaceRole,
+} from './session-message-handler.js';
 // ARCH-030: the connection-scoped outbound delivery boundary every carrier builds and passes down.
 export {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
   createOutboundDelivery,
   createPendingStallClock,
   isOverPendingBudget,
@@ -48,9 +52,18 @@ export type {
   TOutboundDeliver,
 } from './outbound-delivery.js';
 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';
 export type { TProtocolSessionEventClassification } from './session-events.js';
 export type { IProtocolSession } from './protocol-session.js';
-export type { TClientMessage, TServerMessage, TSeqServerMessage } from './wire-messages.js';
+export type {
+  IWireAgentDefinitionSummary,
+  IWireHistoryEntry,
+  TClientMessage,
+  TServerMessage,
+  TSeqServerMessage,
+  TWireExecutionResult,
+} from './wire-messages.js';
 // Issue #2045: the owner-side runtime decoders; carriers implement `raw → decodeFrame → typed`.
 export {
   MAX_INBOUND_FRAME_BYTES,
@@ -76,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

package/src/loop-control-messages.ts

@@ -0,0 +1,34 @@
+import type { TOutboundDeliver } from './outbound-delivery.js';
+import type { IProtocolSession } from './protocol-session.js';
+import type { TClientMessage } from './wire-messages.js';
+
+type TLoopControlMessage = Extract<TClientMessage, { type: 'stop-waiting-loop' }>;
+
+export function isLoopControlMessage(msg: TClientMessage): msg is TLoopControlMessage {
+  return msg.type === 'stop-waiting-loop';
+}
+
+/**
+ * Stop the self-paced loop that is waiting for its next wake. The session decides which loop, if
+ * any; the reply carries its outcome, and a session that throws is reported as a failed stop.
+ */
+export function handleLoopControlMessage(
+  session: IProtocolSession,
+  deliver: TOutboundDeliver,
+  msg: TLoopControlMessage,
+): void {
+  const { requestId } = msg;
+  session.stopWaitingSelfPacedLoop().then(
+    (outcome) => deliver({ type: 'waiting_loop_stop', requestId, outcome }),
+    (error: unknown) =>
+      deliver({
+        type: 'waiting_loop_stop',
+        requestId,
+        outcome: { kind: 'failed', message: errorMessage(error) },
+      }),
+  );
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}