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

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();
+  });
+});

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' });
+  });
+});