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

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

@@ -0,0 +1,223 @@
+/**
+ * The read-only `observe` role: an observer reads the session's own conversation and state, never
+ * counts as a surface that can answer a prompt, and cannot submit, answer, or control anything.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ATTACHED_SURFACE_MAX_PENDING_BYTES,
+  createOutboundDelivery,
+} from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+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({
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    executeCommand: vi.fn(),
+    resolvePermission: vi.fn(),
+    resolveAsk: vi.fn(),
+    cancelBackgroundTask: vi.fn(),
+    closeBackgroundTask: vi.fn(),
+    sendBackgroundTask: vi.fn(),
+    invokeRuntimeTool: vi.fn(),
+    readToolAppView: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([{ role: 'user', content: 'hi' }]),
+    isExecuting: vi.fn().mockReturnValue(true),
+    on: ((event: string, handler: TListener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: TListener) => {
+      listeners.get(event)?.delete(handler);
+    }) 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));
+    },
+    listenerCount: (event: string) => listeners.get(event)?.size ?? 0,
+  });
+}
+
+function attach(
+  session: IInteractiveSession,
+  role?: 'drive' | 'observe',
+): { sent: TServerMessage[]; send: (message: TClientMessage) => void; cleanup: () => void } {
+  const sent: TServerMessage[] = [];
+  const { onMessage, cleanup } = createSessionMessageHandler({
+    session,
+    deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+    driverId: role === 'observe' ? 'attach:2' : 'attach:1',
+    ...(role === undefined ? {} : { role }),
+  });
+  return { sent, send: (message) => onMessage(JSON.stringify(message)), cleanup };
+}
+
+const MUTATING: readonly TClientMessage[] = [
+  { type: 'submit', prompt: 'hello' },
+  { type: 'command', name: 'exit' },
+  { type: 'abort' },
+  { type: 'cancel-queue' },
+  { type: 'cancel-background-task', taskId: 't1' },
+  { type: 'close-background-task', taskId: 't1' },
+  { type: 'send-background-task', taskId: 't1', input: { prompt: 'x' } },
+  { type: 'permission-response', id: 'p1', result: true },
+  { type: 'ask-response', id: 'a1', response: { type: 'answer', values: ['React'] } } as TClientMessage,
+  { type: 'get-personal-usage-report', requestId: 'r1', period: '7d', timezone: 'UTC' },
+  { type: 'get-stored-session-usage-report', requestId: 'r2', sessionId: 'other' },
+  { type: 'call-app-tool', requestId: 'r3', viewId: 'view-1', name: 'Write', arguments: {} },
+  { type: 'read-app-view', requestId: 'r4', viewId: 'view-1' },
+];
+
+describe('observe role', () => {
+  it('refuses every mutating or cross-session message with protocol_error and touches nothing', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    for (const message of MUTATING) {
+      observer.sent.length = 0;
+      observer.send(message);
+      expect(observer.sent).toEqual([
+        { type: 'protocol_error', message: `Not permitted for an observer: ${message.type}` },
+      ]);
+    }
+    expect(session.submit).not.toHaveBeenCalled();
+    expect(session.executeCommand).not.toHaveBeenCalled();
+    expect(session.abort).not.toHaveBeenCalled();
+    expect(session.cancelQueue).not.toHaveBeenCalled();
+    expect(session.cancelBackgroundTask).not.toHaveBeenCalled();
+    expect(session.closeBackgroundTask).not.toHaveBeenCalled();
+    expect(session.sendBackgroundTask).not.toHaveBeenCalled();
+    expect(session.resolvePermission).not.toHaveBeenCalled();
+    expect(session.resolveAsk).not.toHaveBeenCalled();
+    expect(session.invokeRuntimeTool).not.toHaveBeenCalled();
+    expect(session.readToolAppView).not.toHaveBeenCalled();
+  });
+
+  it('keeps the read queries for this session', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'get-messages' });
+    observer.send({ type: 'get-executing' });
+    expect(observer.sent).toEqual([
+      // #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');
+    observer.send({ type: 'get-status' });
+    observer.send({ type: 'get-commands' });
+    expect(observer.sent).toEqual([
+      { type: 'session_status', status: session.getStatusSnapshot() },
+      { type: 'commands', commands: [], skills: [] },
+    ]);
+  });
+
+  it('never subscribes to prompt events, so it does not count as a surface that can answer', () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    expect(session.listenerCount('permission_request')).toBe(0);
+    expect(session.listenerCount('ask_request')).toBe(0);
+    expect(session.listenerCount('prompt_resolved')).toBe(1);
+    expect(session.listenerCount('text_delta')).toBe(1);
+    session.emit('permission_request', { id: 'p1', toolName: 'Bash', toolArgs: {} });
+    session.emit('ask_request', { id: 'a1', request: { id: 'r', title: 'Pick' } });
+    session.emit('prompt_resolved', { id: 'p1' });
+    expect(observer.sent).toEqual([{ type: 'prompt_resolved', event: { id: 'p1' } }]);
+    observer.cleanup();
+    expect(session.listenerCount('prompt_resolved')).toBe(0);
+  });
+
+  it('cannot answer a prompt that a drive surface holds', () => {
+    const session = createSession();
+    const drive = attach(session, 'drive');
+    const observer = attach(session, 'observe');
+    session.emit('permission_request', { id: 'p1', toolName: 'Bash', toolArgs: {} });
+    expect(drive.sent).toContainEqual({
+      type: 'permission_request',
+      event: { id: 'p1', toolName: 'Bash', toolArgs: {} },
+    });
+    observer.send({ type: 'permission-response', id: 'p1', result: true });
+    expect(session.resolvePermission).not.toHaveBeenCalled();
+    drive.send({ type: 'permission-response', id: 'p1', result: false });
+    expect(session.resolvePermission).toHaveBeenCalledExactlyOnceWith('p1', false, 'attach:1');
+  });
+
+  it('leaves the drive role unchanged', () => {
+    const session = createSession();
+    const drive = attach(session);
+    expect(session.listenerCount('permission_request')).toBe(1);
+    expect(session.listenerCount('ask_request')).toBe(1);
+    drive.send({ type: 'abort' });
+    drive.send({ type: 'permission-response', id: 'p1', result: true });
+    expect(session.abort).toHaveBeenCalledTimes(1);
+    expect(session.resolvePermission).toHaveBeenCalledExactlyOnceWith('p1', true, 'attach:1');
+    expect(drive.sent).toEqual([]);
+  });
+
+  it('disconnects an observer that stops reading while the session keeps streaming to others', () => {
+    const session = createSession();
+    const drive = attach(session, 'drive');
+    let pending = 0;
+    const onDeliveryError = vi.fn();
+    const received: TServerMessage[] = [];
+    createSessionMessageHandler({
+      session,
+      role: 'observe',
+      deliver: createOutboundDelivery(
+        (message) => {
+          received.push(message);
+          pending += 64 * 1024;
+        },
+        onDeliveryError,
+        () => pending,
+        ATTACHED_SURFACE_MAX_PENDING_BYTES,
+      ),
+    });
+    for (let index = 0; index < 64; index++) {
+      expect(() => session.emit('text_delta', `delta ${index}`)).not.toThrow();
+    }
+    expect(onDeliveryError).toHaveBeenCalledTimes(1);
+    expect(received.length).toBeLessThan(64);
+    expect(drive.sent.filter((message) => message.type === 'text_delta')).toHaveLength(64);
+  });
+});