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

package/src/__tests__/routes.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Tests for HTTP transport routes.
+ * Uses Hono's built-in test client — no real HTTP server needed.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createAgentRoutes } from '../routes.js';
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
+
+function createMockSession(overrides?: Record<string, unknown>) {
+  return {
+    submit: vi.fn(),
+    abort: vi.fn(),
+    cancelQueue: vi.fn(),
+    getMessages: vi.fn().mockReturnValue([
+      { role: 'user', content: 'hello' },
+      { role: 'assistant', content: 'world' },
+    ]),
+    getContextState: vi.fn().mockReturnValue({
+      usedPercentage: 10,
+      usedTokens: 1000,
+      maxTokens: 200000,
+    }),
+    isExecuting: vi.fn().mockReturnValue(false),
+    getPendingPrompt: vi.fn().mockReturnValue(null),
+    executeCommand: vi.fn().mockResolvedValue({
+      message: 'Conversation cleared.',
+      success: true,
+    }),
+    listCommands: vi.fn().mockReturnValue([]),
+    on: vi.fn(),
+    off: vi.fn(),
+    ...overrides,
+  } as unknown as IInteractiveSession;
+}
+
+describe('HTTP Transport Routes', () => {
+  function createApp(session?: IInteractiveSession) {
+    const mockSession = session ?? createMockSession();
+    const app = createAgentRoutes({
+      sessionFactory: () => mockSession,
+    });
+    return { app, mockSession };
+  }
+
+  // ── POST /abort ───────────────────────────────────────────────
+
+  it('POST /abort calls session.abort()', async () => {
+    const { app, mockSession } = createApp();
+    const res = await app.request('/abort', { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+    expect(mockSession.abort).toHaveBeenCalled();
+  });
+
+  // ── POST /cancel-queue ────────────────────────────────────────
+
+  it('POST /cancel-queue calls session.cancelQueue()', async () => {
+    const { app, mockSession } = createApp();
+    const res = await app.request('/cancel-queue', { method: 'POST' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+    expect(mockSession.cancelQueue).toHaveBeenCalled();
+  });
+
+  // ── GET /messages ─────────────────────────────────────────────
+
+  it('GET /messages returns message history', async () => {
+    const { app } = createApp();
+    const res = await app.request('/messages');
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toHaveLength(2);
+    expect(body[0].role).toBe('user');
+    expect(body[1].role).toBe('assistant');
+  });
+
+  // ── GET /context ──────────────────────────────────────────────
+
+  it('GET /context returns context window state', async () => {
+    const { app } = createApp();
+    const res = await app.request('/context');
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.usedTokens).toBe(1000);
+    expect(body.maxTokens).toBe(200000);
+  });
+
+  // ── GET /executing ────────────────────────────────────────────
+
+  it('GET /executing returns execution status', async () => {
+    const { app } = createApp();
+    const res = await app.request('/executing');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ executing: false });
+  });
+
+  // ── GET /pending ──────────────────────────────────────────────
+
+  it('GET /pending returns null when no queue', async () => {
+    const { app } = createApp();
+    const res = await app.request('/pending');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ pending: null });
+  });
+
+  it('GET /pending returns queued prompt', async () => {
+    const mockSession = createMockSession({
+      getPendingPrompt: vi.fn().mockReturnValue('queued prompt'),
+    });
+    const { app } = createApp(mockSession);
+    const res = await app.request('/pending');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ pending: 'queued prompt' });
+  });
+
+  // ── POST /command ─────────────────────────────────────────────
+
+  it('POST /command executes system command via session.executeCommand()', async () => {
+    const { app, mockSession } = createApp();
+    const res = await app.request('/command', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'clear', args: '' }),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.success).toBe(true);
+    expect(body.message).toBe('Conversation cleared.');
+    expect(mockSession.executeCommand).toHaveBeenCalledWith('clear', '');
+  });
+
+  it('POST /command returns 400 without name', async () => {
+    const { app } = createApp();
+    const res = await app.request('/command', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it('POST /command returns 404 for unknown command', async () => {
+    const mockSession = createMockSession({
+      executeCommand: vi.fn().mockResolvedValue(null),
+    });
+    const { app } = createApp(mockSession);
+
+    const res = await app.request('/command', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'nonexistent' }),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  // ── POST /submit validation ───────────────────────────────────
+
+  it('POST /submit returns 400 without prompt', async () => {
+    const { app } = createApp();
+    const res = await app.request('/submit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+});

package/src/http-transport.ts

@@ -0,0 +1,41 @@
+/**
+ * ITransportAdapter implementation for HTTP transport.
+ *
+ * Wraps createAgentRoutes into the unified ITransportAdapter interface
+ * while exposing the underlying Hono app via getApp().
+ */
+
+import { createAgentRoutes } from './routes.js';
+
+import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { Hono } from 'hono';
+
+export interface IHttpTransportOptions {
+  /** Optional: base path prefix for routes. */
+  basePath?: string;
+}
+
+export function createHttpTransport(
+  options?: IHttpTransportOptions,
+): ITransportAdapter<IInteractiveSession> & { getApp(): Hono } {
+  let session: IInteractiveSession | null = null;
+  let app: Hono | null = null;
+
+  return {
+    name: 'http',
+    attach(s: IInteractiveSession) {
+      session = s;
+    },
+    async start() {
+      if (!session) throw new Error('No session attached. Call attach() first.');
+      app = createAgentRoutes({ sessionFactory: () => session! });
+    },
+    async stop() {
+      app = null;
+    },
+    getApp() {
+      if (!app) throw new Error('Transport not started. Call start() first.');
+      return app;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createAgentRoutes } from './routes.js';
+export type { IAgentRoutesOptions, TSessionFactory } from './routes.js';
+export { createHttpTransport } from './http-transport.js';
+export type { IHttpTransportOptions } from './http-transport.js';

package/src/routes.ts

@@ -0,0 +1,152 @@
+/**
+ * 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/dist/node/index.d.cts

@@ -1,44 +0,0 @@
-import { Context, Hono } from 'hono';
-import { InteractiveSession, ITransportAdapter } from '@robota-sdk/agent-sdk';
-
-/**
- * HTTP transport adapter — exposes InteractiveSession over REST API.
- *
- * Built on Hono for Cloudflare Workers + Node.js + AWS Lambda compatibility.
- * Each endpoint maps 1:1 to an InteractiveSession API method.
- */
-
-/** Callback that resolves an InteractiveSession from the request context. */
-type ISessionFactory = (c: Context) => InteractiveSession | Promise<InteractiveSession>;
-interface IAgentRoutesOptions {
-    /** Resolve an InteractiveSession per request (e.g., by auth token, session ID). */
-    sessionFactory: ISessionFactory;
-}
-/**
- * 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)
- * ```
- */
-declare function createAgentRoutes(options: IAgentRoutesOptions): Hono;
-
-/**
- * ITransportAdapter implementation for HTTP transport.
- *
- * Wraps createAgentRoutes into the unified ITransportAdapter interface
- * while exposing the underlying Hono app via getApp().
- */
-
-interface IHttpTransportOptions {
-    /** Optional: base path prefix for routes. */
-    basePath?: string;
-}
-declare function createHttpTransport(options?: IHttpTransportOptions): ITransportAdapter & {
-    getApp(): Hono;
-};
-
-export { type IAgentRoutesOptions, type IHttpTransportOptions, type ISessionFactory, createAgentRoutes, createHttpTransport };