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

package/src/__tests__/project-read-messages.test.ts

@@ -0,0 +1,118 @@
+/**
+ * #3282 §4c — the Project panel's reads dispatch: success answers the matching `project_*` message
+ * under the request's `requestId`; a rejected read becomes a `failed`/`unavailable` result (never an
+ * uncaught rejection — the exact class of bug the `/memory` red-toast fix addresses at the command
+ * layer, guarded again here at the wire boundary); a session that does not implement the capability
+ * (`Partial<ISessionProjectRead>` — see `protocol-session.ts`) answers `protocol_error`, never a throw.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { handleProjectReadMessage, isProjectReadMessage } from '../project-read-messages.js';
+
+import type { TOutboundDeliver } from '../outbound-delivery.js';
+import type { TProjectReadCapableSession } from '../protocol-session.js';
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+
+function collect(): { sent: TServerMessage[]; deliver: TOutboundDeliver } {
+  const sent: TServerMessage[] = [];
+  return { sent, deliver: createOutboundDelivery((m) => sent.push(m), vi.fn()) };
+}
+
+describe('isProjectReadMessage', () => {
+  it('recognizes exactly the three Project panel read types', () => {
+    expect(isProjectReadMessage({ type: 'project-status', requestId: 'r' })).toBe(true);
+    expect(isProjectReadMessage({ type: 'project-diff', requestId: 'r', path: 'a.txt' })).toBe(true);
+    expect(isProjectReadMessage({ type: 'project-memory', requestId: 'r' })).toBe(true);
+    expect(isProjectReadMessage({ type: 'get-status' } as TClientMessage)).toBe(false);
+  });
+});
+
+describe('handleProjectReadMessage', () => {
+  it('answers project_status with the session result under the same requestId', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectStatus: vi.fn().mockResolvedValue({ kind: 'not-a-repository' }),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-status', requestId: 'r1' });
+    await Promise.resolve();
+    expect(sent).toEqual([
+      { type: 'project_status', requestId: 'r1', result: { kind: 'not-a-repository' } },
+    ]);
+  });
+
+  it('passes the path through to readProjectDiff and answers project_diff', async () => {
+    const { sent, deliver } = collect();
+    const readProjectDiff = vi.fn().mockResolvedValue({ kind: 'diff', diffLines: [], truncated: false });
+    const session = { readProjectDiff } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, {
+      type: 'project-diff',
+      requestId: 'r2',
+      path: 'src/a.ts',
+    });
+    await Promise.resolve();
+    expect(readProjectDiff).toHaveBeenCalledExactlyOnceWith('src/a.ts');
+    expect(sent).toEqual([
+      { type: 'project_diff', requestId: 'r2', result: { kind: 'diff', diffLines: [], truncated: false } },
+    ]);
+  });
+
+  it('answers project_memory with the session result', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectMemory: vi
+        .fn()
+        .mockResolvedValue({ kind: 'memory', content: 'x', path: 'MEMORY.md', truncated: false }),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-memory', requestId: 'r3' });
+    await Promise.resolve();
+    expect(sent).toEqual([
+      {
+        type: 'project_memory',
+        requestId: 'r3',
+        result: { kind: 'memory', content: 'x', path: 'MEMORY.md', truncated: false },
+      },
+    ]);
+  });
+
+  it('turns a rejected readProjectStatus into a failed result, never an uncaught rejection', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectStatus: vi.fn().mockRejectedValue(new Error('git not found')),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-status', requestId: 'r4' });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(sent).toEqual([
+      { type: 'project_status', requestId: 'r4', result: { kind: 'failed', message: 'git not found' } },
+    ]);
+  });
+
+  it('turns a rejected readProjectMemory into an unavailable result', async () => {
+    const { sent, deliver } = collect();
+    const session = {
+      readProjectMemory: vi.fn().mockRejectedValue(new Error('no store')),
+    } as unknown as TProjectReadCapableSession;
+    handleProjectReadMessage(session, deliver, { type: 'project-memory', requestId: 'r5' });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(sent).toEqual([
+      { type: 'project_memory', requestId: 'r5', result: { kind: 'unavailable', message: 'no store' } },
+    ]);
+  });
+
+  it('answers protocol_error, never a throw, when the session has no project-read capability', () => {
+    const { sent, deliver } = collect();
+    const session = {} as unknown as TProjectReadCapableSession;
+    expect(() =>
+      handleProjectReadMessage(session, deliver, { type: 'project-status', requestId: 'r6' }),
+    ).not.toThrow();
+    expect(sent).toEqual([
+      {
+        type: 'protocol_error',
+        message: 'This host does not support the Project panel.',
+        requestId: 'r6',
+      },
+    ]);
+  });
+});

package/src/__tests__/session-detail-loop-status.test.ts

@@ -0,0 +1,169 @@
+/**
+ * #3189 step 3b: an attached client reads a workspace entry's detail, stops a waiting self-paced
+ * loop, and follows status changes another client made.
+ */
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { describe, expect, it, vi } from 'vitest';
+
+import { isObserverMessageType as isObserverMessageTypeFromClient } from '../client.js';
+import { isObserverMessageType } from '../index.js';
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { createSessionMessageHandler } from '../session-message-handler.js';
+
+import type { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type { IExecutionDetailPage } from '@robota-sdk/agent-interface-execution';
+import type {
+  IInteractiveSession,
+  ISessionStatusSnapshot,
+} from '@robota-sdk/agent-interface-session';
+
+type TListener = (...args: unknown[]) => void;
+
+const page: IExecutionDetailPage = {
+  entryId: 'main',
+  cursor: { offset: 20 },
+  nextCursor: { offset: 40 },
+  records: [{ id: 'main:20:0', kind: 'message', text: 'hello' }],
+};
+
+function createSession(overrides: Partial<IInteractiveSession> = {}): IInteractiveSession & {
+  emit: (event: string, ...args: unknown[]) => void;
+} {
+  const listeners = new Map<string, Set<TListener>>();
+  const session = createTestInteractiveSession({
+    readExecutionWorkspaceDetail: vi.fn().mockResolvedValue(page),
+    stopWaitingSelfPacedLoop: vi.fn().mockResolvedValue({ kind: 'stopped', loopId: 'loop-a' }),
+    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'],
+    ...overrides,
+  });
+  return Object.assign(session, {
+    emit: (event: string, ...args: unknown[]) => {
+      listeners.get(event)?.forEach((handler) => handler(...args));
+    },
+  });
+}
+
+function attach(
+  session: IInteractiveSession,
+  role: 'drive' | 'observe' = 'drive',
+): { sent: TServerMessage[]; send: (message: TClientMessage) => void } {
+  const sent: TServerMessage[] = [];
+  const { onMessage } = createSessionMessageHandler({
+    session,
+    role,
+    deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+  });
+  return { sent, send: (message) => onMessage(JSON.stringify(message)) };
+}
+
+const flush = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0));
+
+describe('read-execution-detail', () => {
+  it('answers with the page the session read, under the request id', async () => {
+    const session = createSession();
+    const client = attach(session);
+    client.send({
+      type: 'read-execution-detail',
+      requestId: 'detail-1',
+      entryId: 'main',
+      cursor: { offset: 20 },
+    });
+    await flush();
+    expect(session.readExecutionWorkspaceDetail).toHaveBeenCalledExactlyOnceWith('main', {
+      offset: 20,
+    });
+    expect(client.sent).toEqual([{ type: 'execution_detail', requestId: 'detail-1', page }]);
+  });
+
+  it('answers with an error reply when the session cannot read the entry', async () => {
+    const session = createSession({
+      readExecutionWorkspaceDetail: vi.fn().mockRejectedValue(new Error('Unknown entry: gone')),
+    });
+    const client = attach(session);
+    client.send({ type: 'read-execution-detail', requestId: 'detail-2', entryId: 'gone' });
+    await flush();
+    expect(client.sent).toEqual([
+      { type: 'execution_detail_error', requestId: 'detail-2', message: 'Unknown entry: gone' },
+    ]);
+  });
+});
+
+describe('stop-waiting-loop', () => {
+  it('answers with the outcome the session reports', async () => {
+    const session = createSession();
+    const client = attach(session);
+    client.send({ type: 'stop-waiting-loop', requestId: 'loop-1' });
+    await flush();
+    expect(session.stopWaitingSelfPacedLoop).toHaveBeenCalledOnce();
+    expect(client.sent).toEqual([
+      {
+        type: 'waiting_loop_stop',
+        requestId: 'loop-1',
+        outcome: { kind: 'stopped', loopId: 'loop-a' },
+      },
+    ]);
+  });
+
+  it('reports a session that throws as a failed stop', async () => {
+    const session = createSession({
+      stopWaitingSelfPacedLoop: vi.fn().mockRejectedValue(new Error('store unavailable')),
+    });
+    const client = attach(session);
+    client.send({ type: 'stop-waiting-loop', requestId: 'loop-2' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'waiting_loop_stop',
+        requestId: 'loop-2',
+        outcome: { kind: 'failed', message: 'store unavailable' },
+      },
+    ]);
+  });
+});
+
+describe('observers', () => {
+  it('may read an entry detail but may not stop a loop', async () => {
+    const session = createSession();
+    const observer = attach(session, 'observe');
+    observer.send({ type: 'read-execution-detail', requestId: 'detail-3', entryId: 'main' });
+    observer.send({ type: 'stop-waiting-loop', requestId: 'loop-3' });
+    await flush();
+    expect(session.stopWaitingSelfPacedLoop).not.toHaveBeenCalled();
+    expect(observer.sent).toEqual([
+      { type: 'protocol_error', message: 'Not permitted for an observer: stop-waiting-loop' },
+      { type: 'execution_detail', requestId: 'detail-3', page },
+    ]);
+  });
+
+  it('share one allowlist between the host and both package entries', () => {
+    expect(isObserverMessageTypeFromClient).toBe(isObserverMessageType);
+    expect(isObserverMessageType('read-execution-detail')).toBe(true);
+    expect(isObserverMessageType('get-status')).toBe(true);
+    expect(isObserverMessageType('stop-waiting-loop')).toBe(false);
+    expect(isObserverMessageType('get-prompts')).toBe(false);
+    expect(isObserverMessageType('submit')).toBe(false);
+    expect(isObserverMessageType('not-a-message')).toBe(false);
+  });
+});
+
+describe('status_changed', () => {
+  it('pushes the new status to every attached client as session_status', () => {
+    const session = createSession();
+    const drive = attach(session);
+    const observer = attach(session, 'observe');
+    const status: ISessionStatusSnapshot = {
+      ...session.getStatusSnapshot(),
+      permissionMode: 'plan',
+    };
+    session.emit('status_changed', status);
+    expect(drive.sent).toEqual([{ type: 'session_status', status }]);
+    expect(observer.sent).toEqual([{ type: 'session_status', status }]);
+  });
+});

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

@@ -0,0 +1,322 @@
+/**
+ * #3189: clients list the host's sessions, start a new one and switch to another over the wire. The
+ * host owns the directory; the protocol correlates the listing and carries a refusal's code and reason.
+ */
+
+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 { TClientMessage, TServerMessage } from '../wire-messages.js';
+import type {
+  ISessionDirectory,
+  ISessionListing,
+  TSessionChangeRefusalCode,
+  TSessionDeleteRefusalCode,
+} from '@robota-sdk/agent-interface-session';
+
+const listing: ISessionListing = {
+  currentSessionId: 'session-1',
+  sessions: [
+    {
+      id: 'session-1',
+      cwd: '/repo',
+      updatedAt: '2026-09-26T00:00:00.000Z',
+      messageCount: 2,
+      preview: 'hello',
+    },
+  ],
+  unreadableSessionIds: ['session-broken'],
+};
+
+function createDirectory(overrides: Partial<ISessionDirectory> = {}): ISessionDirectory {
+  return {
+    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,
+  };
+}
+
+function attach(options: { directory?: ISessionDirectory; role?: 'drive' | 'observe' }): {
+  sent: TServerMessage[];
+  send: (message: TClientMessage) => void;
+} {
+  const sent: TServerMessage[] = [];
+  const { onMessage } = createSessionMessageHandler({
+    session: createTestInteractiveSession(),
+    deliver: createOutboundDelivery((message) => sent.push(message), vi.fn()),
+    ...(options.directory ? { sessionDirectory: options.directory } : {}),
+    ...(options.role ? { role: options.role } : {}),
+  });
+  return { sent, send: (message) => onMessage(JSON.stringify(message)) };
+}
+
+/** The shape `SessionChangeRefusal` (agent-framework) has; this package cannot import the class. */
+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)', () => {
+  it('answers list-sessions with the host listing, correlated by requestId', () => {
+    const client = attach({ directory: createDirectory() });
+    client.send({ type: 'list-sessions', requestId: 'r1' });
+    expect(client.sent).toEqual([{ type: 'sessions', requestId: 'r1', listing }]);
+  });
+
+  it('answers not_available when the host has no session directory', () => {
+    const client = attach({});
+    client.send({ type: 'list-sessions', requestId: 'r1' });
+    expect(client.sent).toEqual([
+      {
+        type: 'sessions_error',
+        requestId: 'r1',
+        code: 'not_available',
+        message: 'Session listing is not available on this host.',
+      },
+    ]);
+  });
+
+  it('answers list_failed with the reason when the listing throws', () => {
+    const directory = createDirectory({
+      listSessions: vi.fn(() => {
+        throw new Error('session store unreadable');
+      }),
+    });
+    const client = attach({ directory });
+    client.send({ type: 'list-sessions', requestId: 'r1' });
+    expect(client.sent).toEqual([
+      {
+        type: 'sessions_error',
+        requestId: 'r1',
+        code: 'list_failed',
+        message: 'session store unreadable',
+      },
+    ]);
+  });
+
+  it('switches by id and answers nothing itself — session_switched from its session is the signal', async () => {
+    const directory = createDirectory();
+    const client = attach({ directory });
+    client.send({ type: 'switch-session', sessionId: 'session-2', requestId: 'r2' });
+    await flush();
+    expect(directory.switchSession).toHaveBeenCalledExactlyOnceWith('session-2');
+    expect(client.sent).toEqual([]);
+  });
+
+  it('delivers a declared refusal as session_change_failed with its code and the requestId', async () => {
+    const directory = createDirectory({
+      switchSession: vi.fn(async () => {
+        throw refusal('prompt_pending', 'Answer the pending prompt first.');
+      }),
+    });
+    const client = attach({ directory });
+    client.send({ type: 'switch-session', sessionId: 'session-2', requestId: 'r2' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'session_change_failed',
+        code: 'prompt_pending',
+        message: 'Answer the pending prompt first.',
+        requestId: 'r2',
+      },
+    ]);
+  });
+
+  it('delivers any other error as code failed with its message, and omits an absent requestId', async () => {
+    const directory = createDirectory({
+      switchSession: vi.fn(async () => {
+        throw new Error('disk full');
+      }),
+    });
+    const client = attach({ directory });
+    client.send({ type: 'switch-session', sessionId: 'session-2' });
+    await flush();
+    expect(client.sent).toEqual([
+      { type: 'session_change_failed', code: 'failed', message: 'disk full' },
+    ]);
+  });
+
+  it('starts a new session, and reports a refusal the same way', async () => {
+    const directory = createDirectory();
+    const client = attach({ directory });
+    client.send({ type: 'new-session' });
+    await flush();
+    expect(directory.newSession).toHaveBeenCalledTimes(1);
+    expect(client.sent).toEqual([]);
+
+    vi.mocked(directory.newSession).mockRejectedValueOnce(
+      refusal('limit', 'Four sessions are live already.'),
+    );
+    client.send({ type: 'new-session', requestId: 'r3' });
+    await flush();
+    expect(client.sent).toEqual([
+      {
+        type: 'session_change_failed',
+        code: 'limit',
+        message: 'Four sessions are live already.',
+        requestId: 'r3',
+      },
+    ]);
+  });
+
+  it('answers not_available to a switch or new session on a host without a directory', () => {
+    const client = attach({});
+    client.send({ type: 'switch-session', sessionId: 'session-2', requestId: 'r4' });
+    client.send({ type: 'new-session' });
+    const message = 'Sessions cannot be switched on this host.';
+    expect(client.sent).toEqual([
+      { type: 'session_change_failed', code: 'not_available', message, requestId: 'r4' },
+      { type: 'session_change_failed', code: 'not_available', message },
+    ]);
+  });
+
+  it('lets an observer list sessions but never start or switch one', async () => {
+    const directory = createDirectory();
+    const observer = attach({ directory, role: 'observe' });
+    observer.send({ type: 'list-sessions', requestId: 'r1' });
+    observer.send({ type: 'switch-session', sessionId: 'session-2' });
+    observer.send({ type: 'new-session' });
+    await flush();
+    expect(observer.sent).toEqual([
+      { type: 'sessions', requestId: 'r1', listing },
+      { type: 'protocol_error', message: 'Not permitted for an observer: switch-session' },
+      { type: 'protocol_error', message: 'Not permitted for an observer: new-session' },
+    ]);
+    expect(directory.switchSession).not.toHaveBeenCalled();
+    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();
+  });
+});