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

package/src/http/routes.ts

@@ -0,0 +1,151 @@
+/**
+ * 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 { Context } from 'hono';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+
+/** 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/index.ts

@@ -0,0 +1,5 @@
+export * from './tui/index.js';
+export * from './headless/index.js';
+export * from './http/index.js';
+export * from './ws/index.js';
+export * from './mcp/index.js';

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

@@ -0,0 +1,66 @@
+/**
+ * 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-framework';
+
+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

@@ -0,0 +1,46 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createMcpTransport } from '../mcp-transport.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+
+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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,162 @@
+/**
+ * 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 { IInteractiveSession, IExecutionResult } from '@robota-sdk/agent-framework';
+
+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

@@ -0,0 +1,48 @@
+/**
+ * ITransportAdapter implementation for MCP transport.
+ *
+ * Wraps createAgentMcpServer into the unified ITransportAdapter interface
+ * while exposing the underlying MCP Server via getServer().
+ */
+
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import { createAgentMcpServer } from './mcp-server.js';
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+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;
+    },
+  };
+}