@robota-sdk/agent-transport 3.0.0-beta.75 → 3.0.0-beta.77

package/src/http/routes.ts

@@ -1,152 +0,0 @@
-/**
- * HTTP transport adapter — exposes IInteractiveSession over REST API.
- *
- * Built on Hono for Cloudflare Workers + Node.js + AWS Lambda compatibility.
- * Each endpoint maps 1:1 to an IInteractiveSession API method.
- */
-
-import { Hono } from 'hono';
-import { streamSSE } from 'hono/streaming';
-
-import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
-import type { Context } from 'hono';
-
-/** Callback that resolves an IInteractiveSession from the request context. */
-export type TSessionFactory = (c: Context) => IInteractiveSession | Promise<IInteractiveSession>;
-
-export interface IAgentRoutesOptions {
-  /** Resolve an IInteractiveSession per request (e.g., by auth token, session ID). */
-  sessionFactory: TSessionFactory;
-}
-
-/**
- * Create a Hono router with all agent HTTP endpoints.
- *
- * Usage:
- * ```typescript
- * const routes = createAgentRoutes({ sessionFactory });
- * app.route('/agent', routes);          // mount on existing app
- * export default routes;                // or use standalone (CF Workers)
- * ```
- */
-export function createAgentRoutes(options: IAgentRoutesOptions): Hono {
-  const { sessionFactory } = options;
-  const app = new Hono();
-
-  // POST /submit — execute prompt, stream events via SSE
-  app.post('/submit', async (c) => {
-    const session = await sessionFactory(c);
-    const body = await c.req.json<{ prompt: string }>();
-
-    if (!body.prompt || typeof body.prompt !== 'string') {
-      return c.json({ error: 'prompt is required' }, 400);
-    }
-
-    return streamSSE(c, async (stream) => {
-      const cleanup: Array<() => void> = [];
-
-      const subscribe = <T>(event: string, handler: (data: T) => void): void => {
-        session.on(event as 'text_delta', handler as () => void);
-        cleanup.push(() => session.off(event as 'text_delta', handler as () => void));
-      };
-
-      let completed = false;
-      const done = new Promise<void>((resolve) => {
-        subscribe('text_delta', (delta: string) => {
-          stream.writeSSE({ event: 'text_delta', data: JSON.stringify({ delta }) });
-        });
-
-        subscribe('tool_start', (state) => {
-          stream.writeSSE({ event: 'tool_start', data: JSON.stringify(state) });
-        });
-
-        subscribe('tool_end', (state) => {
-          stream.writeSSE({ event: 'tool_end', data: JSON.stringify(state) });
-        });
-
-        subscribe('thinking', (isThinking: boolean) => {
-          stream.writeSSE({ event: 'thinking', data: JSON.stringify({ isThinking }) });
-          if (!isThinking && completed) {
-            resolve();
-          }
-        });
-
-        subscribe('complete', (result) => {
-          completed = true;
-          stream.writeSSE({ event: 'complete', data: JSON.stringify(result) });
-        });
-
-        subscribe('interrupted', (result) => {
-          completed = true;
-          stream.writeSSE({ event: 'interrupted', data: JSON.stringify(result) });
-        });
-
-        subscribe('error', (error: Error) => {
-          completed = true;
-          stream.writeSSE({ event: 'error', data: JSON.stringify({ message: error.message }) });
-        });
-      });
-
-      await session.submit(body.prompt);
-      await done;
-
-      for (const fn of cleanup) fn();
-    });
-  });
-
-  // POST /command — execute system command
-  app.post('/command', async (c) => {
-    const session = await sessionFactory(c);
-    const body = await c.req.json<{ name: string; args?: string }>();
-
-    if (!body.name || typeof body.name !== 'string') {
-      return c.json({ error: 'name is required' }, 400);
-    }
-
-    const result = await session.executeCommand(body.name, body.args ?? '');
-    if (!result) {
-      return c.json({ error: `Unknown command: ${body.name}` }, 404);
-    }
-    return c.json(result);
-  });
-
-  // POST /abort — abort current execution
-  app.post('/abort', async (c) => {
-    const session = await sessionFactory(c);
-    session.abort();
-    return c.json({ ok: true });
-  });
-
-  // POST /cancel-queue — cancel queued prompt
-  app.post('/cancel-queue', async (c) => {
-    const session = await sessionFactory(c);
-    session.cancelQueue();
-    return c.json({ ok: true });
-  });
-
-  // GET /messages — get message history
-  app.get('/messages', async (c) => {
-    const session = await sessionFactory(c);
-    return c.json(session.getMessages());
-  });
-
-  // GET /context — get context window state
-  app.get('/context', async (c) => {
-    const session = await sessionFactory(c);
-    return c.json(session.getContextState());
-  });
-
-  // GET /executing — check if currently executing
-  app.get('/executing', async (c) => {
-    const session = await sessionFactory(c);
-    return c.json({ executing: session.isExecuting() });
-  });
-
-  // GET /pending — get pending queued prompt
-  app.get('/pending', async (c) => {
-    const session = await sessionFactory(c);
-    return c.json({ pending: session.getPendingPrompt() });
-  });
-
-  return app;
-}

package/src/mcp/__tests__/mcp-server.test.ts

@@ -1,66 +0,0 @@
-/**
- * Tests for MCP transport adapter.
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { createAgentMcpServer } from '../mcp-server.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
-
-function createMockSession(commands?: Array<{ name: string; description: string }>) {
-  return {
-    submit: vi.fn(),
-    abort: vi.fn(),
-    cancelQueue: vi.fn(),
-    getMessages: vi.fn().mockReturnValue([]),
-    getContextState: vi
-      .fn()
-      .mockReturnValue({ usedTokens: 0, maxTokens: 200000, usedPercentage: 0 }),
-    isExecuting: vi.fn().mockReturnValue(false),
-    getPendingPrompt: vi.fn().mockReturnValue(null),
-    executeCommand: vi.fn().mockResolvedValue({ message: 'done', success: true }),
-    listCommands: vi.fn().mockReturnValue(
-      commands ?? [
-        { name: 'clear', description: 'Clear history' },
-        { name: 'mode', description: 'Permission mode' },
-      ],
-    ),
-    on: vi.fn(),
-    off: vi.fn(),
-  } as unknown as IInteractiveSession;
-}
-
-describe('createAgentMcpServer', () => {
-  it('creates a server instance', () => {
-    const server = createAgentMcpServer({
-      name: 'test-agent',
-      version: '1.0.0',
-      session: createMockSession(),
-    });
-    expect(server).toBeDefined();
-  });
-
-  it('exposeCommands=false does not call listCommands', () => {
-    const session = createMockSession();
-    createAgentMcpServer({
-      name: 'test',
-      version: '1.0.0',
-      session,
-      exposeCommands: false,
-    });
-    expect(session.listCommands).not.toHaveBeenCalled();
-  });
-
-  it('exposeCommands=true calls session.listCommands()', () => {
-    const session = createMockSession([
-      { name: 'clear', description: 'Clear' },
-      { name: 'help', description: 'Help' },
-    ]);
-    createAgentMcpServer({
-      name: 'test',
-      version: '1.0.0',
-      session,
-      exposeCommands: true,
-    });
-    expect(session.listCommands).toHaveBeenCalled();
-  });
-});

package/src/mcp/__tests__/mcp-transport.test.ts

@@ -1,46 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { createMcpTransport } from '../mcp-transport.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
-
-function createMockSession(): IInteractiveSession {
-  return {
-    submit: vi.fn(),
-    abort: vi.fn(),
-    cancelQueue: vi.fn(),
-    getMessages: vi.fn().mockReturnValue([]),
-    getContextState: vi
-      .fn()
-      .mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 200000 }),
-    isExecuting: vi.fn().mockReturnValue(false),
-    getPendingPrompt: vi.fn().mockReturnValue(null),
-    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
-    listCommands: vi.fn().mockReturnValue([]),
-    on: vi.fn(),
-    off: vi.fn(),
-  } as unknown as IInteractiveSession;
-}
-
-describe('createMcpTransport', () => {
-  it('returns an adapter with name "mcp"', () => {
-    const transport = createMcpTransport({ name: 'test', version: '1.0.0' });
-    expect(transport.name).toBe('mcp');
-  });
-
-  it('throws if start() is called without attach()', async () => {
-    const transport = createMcpTransport({ name: 'test', version: '1.0.0' });
-    await expect(transport.start()).rejects.toThrow('No session attached');
-  });
-
-  it('throws if getServer() is called before start()', () => {
-    const transport = createMcpTransport({ name: 'test', version: '1.0.0' });
-    expect(() => transport.getServer()).toThrow('Transport not started');
-  });
-
-  it('creates an MCP server after attach + start', async () => {
-    const transport = createMcpTransport({ name: 'test', version: '1.0.0' });
-    transport.attach(createMockSession() as never);
-    await transport.start();
-    const server = transport.getServer();
-    expect(server).toBeDefined();
-  });
-});

package/src/mcp/index.ts

@@ -1,4 +0,0 @@
-export { createAgentMcpServer } from './mcp-server.js';
-export type { IAgentMcpOptions } from './mcp-server.js';
-export { createMcpTransport } from './mcp-transport.js';
-export type { IMcpTransportOptions } from './mcp-transport.js';

package/src/mcp/mcp-server.ts

@@ -1,163 +0,0 @@
-/**
- * MCP transport adapter — exposes IInteractiveSession as an MCP server.
- *
- * Uses the low-level MCP Server class to avoid TypeScript depth issues
- * with McpServer.registerTool() generics. Registers tools/list and
- * tools/call handlers directly.
- */
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-
-import type { IExecutionResult, IInteractiveSession } from '@robota-sdk/agent-interface-transport';
-
-export interface IAgentMcpOptions {
-  /** Name for the MCP server. */
-  name: string;
-  /** Version string. */
-  version: string;
-  /** IInteractiveSession to expose. */
-  session: IInteractiveSession;
-  /** If true, register each system command as a separate MCP tool. Default: true. */
-  exposeCommands?: boolean;
-}
-
-/**
- * Create an MCP server that exposes IInteractiveSession over Model Context Protocol.
- *
- * Usage:
- * ```typescript
- * const server = createAgentMcpServer({
- *   name: 'robota-agent',
- *   version: '1.0.0',
- *   session: interactiveSession,
- * });
- *
- * import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
- * await server.connect(new StdioServerTransport());
- * ```
- */
-export function createAgentMcpServer(options: IAgentMcpOptions): Server {
-  const { name, version, session, exposeCommands = true } = options;
-
-  const server = new Server({ name, version }, { capabilities: { tools: {} } });
-
-  // Build tool definitions
-  const tools: Array<{
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-  }> = [
-    {
-      name: 'submit',
-      description: 'Submit a prompt to the AI agent and wait for the response',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          prompt: { type: 'string', description: 'The prompt to send to the agent' },
-        },
-        required: ['prompt'],
-      },
-    },
-  ];
-
-  if (exposeCommands) {
-    for (const cmd of session.listCommands()) {
-      tools.push({
-        name: `command_${cmd.name}`,
-        description: cmd.description,
-        inputSchema: {
-          type: 'object',
-          properties: {
-            args: { type: 'string', description: 'Command arguments' },
-          },
-        },
-      });
-    }
-  }
-
-  // tools/list handler
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools,
-  }));
-
-  // tools/call handler
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name: toolName, arguments: toolArgs } = request.params;
-
-    if (toolName === 'submit') {
-      const prompt = (toolArgs as Record<string, string>)?.prompt;
-      if (!prompt) {
-        return {
-          content: [{ type: 'text', text: 'Error: prompt is required' }],
-          isError: true,
-        };
-      }
-      const result = await waitForCompletion(session, prompt);
-      return {
-        content: [{ type: 'text', text: result.response }],
-      };
-    }
-
-    // System commands: command_<name>
-    if (toolName.startsWith('command_')) {
-      const cmdName = toolName.slice('command_'.length);
-      const args = (toolArgs as Record<string, string>)?.args ?? '';
-      const result = await session.executeCommand(cmdName, args);
-      return {
-        content: [
-          {
-            type: 'text',
-            text: result?.message ?? `Unknown command: ${cmdName}`,
-          },
-        ],
-        isError: !result,
-      };
-    }
-
-    return {
-      content: [{ type: 'text', text: `Unknown tool: ${toolName}` }],
-      isError: true,
-    };
-  });
-
-  return server;
-}
-
-/**
- * Submit a prompt and wait for the complete/interrupted/error event.
- */
-function waitForCompletion(
-  session: IInteractiveSession,
-  prompt: string,
-): Promise<IExecutionResult> {
-  return new Promise((resolve, reject) => {
-    const onComplete = (result: IExecutionResult): void => {
-      cleanup();
-      resolve(result);
-    };
-    const onInterrupted = (result: IExecutionResult): void => {
-      cleanup();
-      resolve(result);
-    };
-    const onError = (error: Error): void => {
-      cleanup();
-      reject(error);
-    };
-
-    const cleanup = (): void => {
-      session.off('complete', onComplete);
-      session.off('interrupted', onInterrupted);
-      session.off('error', onError);
-    };
-
-    session.on('complete', onComplete);
-    session.on('interrupted', onInterrupted);
-    session.on('error', onError);
-
-    session.submit(prompt).catch((err) => {
-      cleanup();
-      reject(err instanceof Error ? err : new Error(String(err)));
-    });
-  });
-}

package/src/mcp/mcp-transport.ts

@@ -1,48 +0,0 @@
-/**
- * ITransportAdapter implementation for MCP transport.
- *
- * Wraps createAgentMcpServer into the unified ITransportAdapter interface
- * while exposing the underlying MCP Server via getServer().
- */
-
-import { createAgentMcpServer } from './mcp-server.js';
-
-import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
-
-export interface IMcpTransportOptions {
-  /** Name for the MCP server. */
-  name: string;
-  /** Version string. */
-  version: string;
-  /** If true, register each system command as a separate MCP tool. Default: true. */
-  exposeCommands?: boolean;
-}
-
-export function createMcpTransport(
-  options: IMcpTransportOptions,
-): ITransportAdapter<IInteractiveSession> & { getServer(): Server } {
-  let session: IInteractiveSession | null = null;
-  let server: Server | null = null;
-
-  return {
-    name: 'mcp',
-    attach(s: IInteractiveSession) {
-      session = s;
-    },
-    async start() {
-      if (!session) throw new Error('No session attached. Call attach() first.');
-      server = createAgentMcpServer({ ...options, session });
-    },
-    async stop() {
-      if (server) {
-        await server.close();
-        server = null;
-      }
-    },
-    getServer() {
-      if (!server) throw new Error('Transport not started. Call start() first.');
-      return server;
-    },
-  };
-}

package/src/testing/__tests__/scripted-provider.test.ts

@@ -1,73 +0,0 @@
-/**
- * Scripted provider fixture tests (CLI-074 TC-01).
- *
- * The fixture must replay declared turns in order, record every request's
- * message array for assertions, and fail fast on script exhaustion — never
- * silently improvise a response.
- */
-
-import { describe, expect, it } from 'vitest';
-
-import { createScriptedProvider } from '../scripted-provider.js';
-
-describe('createScriptedProvider (CLI-074)', () => {
-  it('TC-01: replays text turns in order and records requests', async () => {
-    const { provider, requests } = createScriptedProvider([
-      { text: 'first answer' },
-      { text: 'second answer' },
-    ]);
-
-    const first = await provider.chat([
-      { id: 'u1', role: 'user', content: 'hi', state: 'complete', timestamp: new Date() },
-    ]);
-    const second = await provider.chat([
-      { id: 'u2', role: 'user', content: 'again', state: 'complete', timestamp: new Date() },
-    ]);
-
-    expect(first.role).toBe('assistant');
-    expect(first.content).toBe('first answer');
-    expect(second.content).toBe('second answer');
-    expect(requests).toHaveLength(2);
-    expect(requests[0]?.map((message) => message.content)).toContain('hi');
-    expect(requests[1]?.map((message) => message.content)).toContain('again');
-  });
-
-  it('TC-01: replays tool_use turns as assistant toolCalls', async () => {
-    const { provider } = createScriptedProvider([
-      { toolCalls: [{ name: 'Read', args: { file_path: '/tmp/a.txt' } }] },
-      { text: 'done reading' },
-    ]);
-
-    const turn = await provider.chat([
-      { id: 'u1', role: 'user', content: 'read it', state: 'complete', timestamp: new Date() },
-    ]);
-
-    expect(turn.role).toBe('assistant');
-    if (turn.role !== 'assistant') throw new Error('unreachable');
-    expect(turn.content).toBeNull();
-    expect(turn.toolCalls).toHaveLength(1);
-    expect(turn.toolCalls?.[0]?.function.name).toBe('Read');
-    expect(JSON.parse(turn.toolCalls?.[0]?.function.arguments ?? '{}')).toEqual({
-      file_path: '/tmp/a.txt',
-    });
-  });
-
-  it('TC-01: throws on script exhaustion instead of improvising', async () => {
-    const { provider } = createScriptedProvider([{ text: 'only turn' }]);
-
-    await provider.chat([
-      { id: 'u1', role: 'user', content: 'one', state: 'complete', timestamp: new Date() },
-    ]);
-
-    await expect(
-      provider.chat([
-        { id: 'u2', role: 'user', content: 'two', state: 'complete', timestamp: new Date() },
-      ]),
-    ).rejects.toThrow(/script exhausted/i);
-  });
-
-  it('supportsTools is true and validateConfig passes (agent-loop prerequisites)', () => {
-    const { provider } = createScriptedProvider([{ text: 'x' }]);
-    expect(provider.supportsTools()).toBe(true);
-  });
-});

package/src/testing/scripted-provider.ts

@@ -1,73 +0,0 @@
-/**
- * Deterministic scripted provider for E2E tests (CLI-074).
- *
- * Replays a declared sequence of assistant turns through the REAL agent loop —
- * tool execution, permission gate, session persistence, and output transports all
- * run unmocked. Test-only: exported via the `@robota-sdk/agent-transport/testing`
- * subpath and never imported by runtime code.
- */
-
-import type { IAIProvider, IRawProviderResponse, TUniversalMessage } from '@robota-sdk/agent-core';
-
-/** One scripted assistant turn: plain text or tool invocations. */
-export type TScriptedTurn =
-  | { text: string }
-  | { toolCalls: ReadonlyArray<{ name: string; args: Record<string, unknown> }> };
-
-export interface IScriptedProvider {
-  provider: IAIProvider;
-  /** Message arrays of every chat() call, in order, for request assertions. */
-  requests: TUniversalMessage[][];
-}
-
-export function createScriptedProvider(turns: readonly TScriptedTurn[]): IScriptedProvider {
-  const requests: TUniversalMessage[][] = [];
-  let cursor = 0;
-
-  const provider: IAIProvider = {
-    name: 'scripted-test-provider',
-    version: 'test',
-    async chat(messages: TUniversalMessage[]): Promise<TUniversalMessage> {
-      requests.push([...messages]);
-      const turn = turns[cursor];
-      if (turn === undefined) {
-        throw new Error(
-          `Scripted provider: script exhausted at call ${cursor + 1} (script declares ${turns.length} turn(s)) — extend the script instead of relying on improvised responses`,
-        );
-      }
-      cursor += 1;
-      if ('text' in turn) {
-        return {
-          id: `scripted-${cursor}`,
-          role: 'assistant',
-          content: turn.text,
-          state: 'complete',
-          timestamp: new Date(),
-        };
-      }
-      return {
-        id: `scripted-${cursor}`,
-        role: 'assistant',
-        content: null,
-        state: 'complete',
-        timestamp: new Date(),
-        toolCalls: turn.toolCalls.map((call, index) => ({
-          id: `scripted-call-${cursor}-${index}`,
-          type: 'function' as const,
-          function: { name: call.name, arguments: JSON.stringify(call.args) },
-        })),
-      };
-    },
-    async generateResponse(): Promise<IRawProviderResponse> {
-      return { content: 'scripted provider does not implement raw responses' };
-    },
-    supportsTools(): boolean {
-      return true;
-    },
-    validateConfig(): boolean {
-      return true;
-    },
-  };
-
-  return { provider, requests };
-}