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

package/src/headless/headless-runner.ts

@@ -0,0 +1,141 @@
+import type { IInteractiveSession, IExecutionResult } from '@robota-sdk/agent-framework';
+import { executeSlashCommandIfPresent, subscribeStreamJsonEvents } from './headless-stream-json.js';
+
+export type TOutputFormat = 'text' | 'json' | 'stream-json';
+
+export interface IHeadlessRunnerOptions {
+  session: IInteractiveSession;
+  outputFormat: TOutputFormat;
+}
+
+export function createHeadlessRunner(options: IHeadlessRunnerOptions): {
+  run: (prompt: string) => Promise<number>;
+} {
+  const { session, outputFormat } = options;
+  return {
+    run: (prompt: string): Promise<number> => {
+      if (outputFormat === 'text') return runTextFormat(session, prompt);
+      if (outputFormat === 'json') return runJsonFormat(session, prompt);
+      return runStreamJsonFormat(session, prompt);
+    },
+  };
+}
+
+export function writeJsonResult(
+  sessionId: string,
+  result: string,
+  subtype: 'success' | 'error',
+): void {
+  const output = JSON.stringify({ type: 'result', result, session_id: sessionId, subtype });
+  process.stdout.write(output + '\n');
+}
+
+export function getSessionId(session: IInteractiveSession): string {
+  try {
+    return session.getSession().getSessionId();
+  } catch {
+    // allow-fallback: session may not be initialized yet
+    return '';
+  }
+}
+
+function runTextFormat(session: IInteractiveSession, prompt: string): Promise<number> {
+  return new Promise<number>((resolve) => {
+    const cleanup = (): void => {
+      session.off('complete', onComplete);
+      session.off('interrupted', onInterrupted);
+      session.off('error', onError);
+    };
+    const onComplete = (result: IExecutionResult): void => {
+      cleanup();
+      process.stdout.write(result.response + '\n');
+      resolve(0);
+    };
+    const onInterrupted = (result: IExecutionResult): void => {
+      cleanup();
+      if (result.response) process.stdout.write(result.response + '\n');
+      resolve(0);
+    };
+    const onError = (_error: Error): void => {
+      cleanup();
+      resolve(1);
+    };
+
+    session.on('complete', onComplete);
+    session.on('interrupted', onInterrupted);
+    session.on('error', onError);
+
+    void executeSlashCommandIfPresent(session, prompt).then((cmd) => {
+      if (cmd.kind === 'command-result') {
+        cleanup();
+        process.stdout.write(cmd.result.message + '\n');
+        resolve(cmd.result.success ? 0 : 1);
+        return;
+      }
+      if (cmd.kind !== 'session-execution') void session.submit(prompt);
+    });
+  });
+}
+
+function runJsonFormat(session: IInteractiveSession, prompt: string): Promise<number> {
+  return new Promise<number>((resolve) => {
+    const cleanup = (): void => {
+      session.off('complete', onComplete);
+      session.off('interrupted', onInterrupted);
+      session.off('error', onError);
+    };
+    const onComplete = (result: IExecutionResult): void => {
+      cleanup();
+      writeJsonResult(getSessionId(session), result.response, 'success');
+      resolve(0);
+    };
+    const onInterrupted = (result: IExecutionResult): void => {
+      cleanup();
+      writeJsonResult(getSessionId(session), result.response, 'success');
+      resolve(0);
+    };
+    const onError = (_error: Error): void => {
+      cleanup();
+      writeJsonResult(getSessionId(session), '', 'error');
+      resolve(1);
+    };
+
+    session.on('complete', onComplete);
+    session.on('interrupted', onInterrupted);
+    session.on('error', onError);
+
+    void executeSlashCommandIfPresent(session, prompt).then((cmd) => {
+      if (cmd.kind === 'command-result') {
+        cleanup();
+        writeJsonResult(
+          getSessionId(session),
+          cmd.result.message,
+          cmd.result.success ? 'success' : 'error',
+        );
+        resolve(cmd.result.success ? 0 : 1);
+        return;
+      }
+      if (cmd.kind !== 'session-execution') void session.submit(prompt);
+    });
+  });
+}
+
+function runStreamJsonFormat(session: IInteractiveSession, prompt: string): Promise<number> {
+  return new Promise<number>((resolve) => {
+    const cleanup = subscribeStreamJsonEvents(session, getSessionId, writeJsonResult, resolve);
+
+    void executeSlashCommandIfPresent(session, prompt).then((cmd) => {
+      if (cmd.kind === 'command-result') {
+        cleanup();
+        writeJsonResult(
+          getSessionId(session),
+          cmd.result.message,
+          cmd.result.success ? 'success' : 'error',
+        );
+        resolve(cmd.result.success ? 0 : 1);
+        return;
+      }
+      if (cmd.kind !== 'session-execution') void session.submit(prompt);
+    });
+  });
+}

package/src/headless/headless-stream-json.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  IInteractiveSession,
+  IExecutionResult,
+  ICommandResult,
+  TBackgroundJobGroupEvent,
+  TBackgroundTaskEvent,
+} from '@robota-sdk/agent-framework';
+
+type TSlashCommandExecution =
+  | { readonly kind: 'not-slash' }
+  | { readonly kind: 'command-result'; readonly result: ICommandResult }
+  | { readonly kind: 'session-execution' };
+
+function parseSlashCommand(prompt: string): { name: string; args: string } | null {
+  const trimmed = prompt.trimStart();
+  if (!trimmed.startsWith('/')) return null;
+  const withoutSlash = trimmed.slice(1);
+  const [name = '', ...args] = withoutSlash.split(/\s+/);
+  if (name.length === 0) return null;
+  return { name, args: args.join(' ') };
+}
+
+export async function executeSlashCommandIfPresent(
+  session: IInteractiveSession,
+  prompt: string,
+): Promise<TSlashCommandExecution> {
+  const command = parseSlashCommand(prompt);
+  if (!command) return { kind: 'not-slash' };
+
+  const result = await session.executeCommand(command.name, command.args);
+  if (result) {
+    if (result.effects?.some((effect) => effect.type === 'session-execution-started')) {
+      return { kind: 'session-execution' };
+    }
+    return { kind: 'command-result', result };
+  }
+  return {
+    kind: 'command-result',
+    result: { message: `Unknown command "/${command.name}".`, success: false },
+  };
+}
+
+type TStreamJsonEvent =
+  | {
+      type: 'content_block_delta';
+      delta: { type: 'text_delta'; text: string };
+    }
+  | {
+      type: 'background_task_event';
+      background_task_event: TBackgroundTaskEvent;
+    }
+  | {
+      type: 'background_job_group_event';
+      background_job_group_event: TBackgroundJobGroupEvent;
+    };
+
+interface IStreamJsonHandlers {
+  onTextDelta: (text: string) => void;
+  onBackgroundTaskEvent: (event: TBackgroundTaskEvent) => void;
+  onBackgroundJobGroupEvent: (event: TBackgroundJobGroupEvent) => void;
+  onComplete: (result: IExecutionResult) => void;
+  onInterrupted: (result: IExecutionResult) => void;
+  onError: (error: Error) => void;
+}
+
+export function writeStreamJsonEvent(
+  session: IInteractiveSession,
+  getSessionId: (s: IInteractiveSession) => string,
+  event: TStreamJsonEvent,
+): void {
+  const output = JSON.stringify({
+    type: 'stream_event',
+    event,
+    session_id: getSessionId(session),
+    uuid: randomUUID(),
+  });
+  process.stdout.write(output + '\n');
+}
+
+export function subscribeStreamJsonEvents(
+  session: IInteractiveSession,
+  getSessionId: (s: IInteractiveSession) => string,
+  writeJsonResult: (sessionId: string, result: string, subtype: 'success' | 'error') => void,
+  resolve: (exitCode: number) => void,
+): () => void {
+  const emit = (event: TStreamJsonEvent): void =>
+    writeStreamJsonEvent(session, getSessionId, event);
+
+  const onTextDelta = (text: string): void =>
+    emit({ type: 'content_block_delta', delta: { type: 'text_delta', text } });
+  const onBackgroundTaskEvent = (event: TBackgroundTaskEvent): void =>
+    emit({ type: 'background_task_event', background_task_event: event });
+  const onBackgroundJobGroupEvent = (event: TBackgroundJobGroupEvent): void =>
+    emit({ type: 'background_job_group_event', background_job_group_event: event });
+
+  const cleanup = (): void =>
+    unsubscribeStreamJsonEvents(session, {
+      onTextDelta,
+      onBackgroundTaskEvent,
+      onBackgroundJobGroupEvent,
+      onComplete,
+      onInterrupted,
+      onError,
+    });
+
+  const onComplete = (result: IExecutionResult): void => {
+    cleanup();
+    writeJsonResult(getSessionId(session), result.response, 'success');
+    resolve(0);
+  };
+  const onInterrupted = (result: IExecutionResult): void => {
+    cleanup();
+    writeJsonResult(getSessionId(session), result.response, 'success');
+    resolve(0);
+  };
+  const onError = (_error: Error): void => {
+    cleanup();
+    writeJsonResult(getSessionId(session), '', 'error');
+    resolve(1);
+  };
+
+  session.on('text_delta', onTextDelta);
+  session.on('background_task_event', onBackgroundTaskEvent);
+  session.on('background_job_group_event', onBackgroundJobGroupEvent);
+  session.on('complete', onComplete);
+  session.on('interrupted', onInterrupted);
+  session.on('error', onError);
+  return cleanup;
+}
+
+function unsubscribeStreamJsonEvents(
+  session: IInteractiveSession,
+  handlers: IStreamJsonHandlers,
+): void {
+  session.off('text_delta', handlers.onTextDelta);
+  session.off('background_task_event', handlers.onBackgroundTaskEvent);
+  session.off('background_job_group_event', handlers.onBackgroundJobGroupEvent);
+  session.off('complete', handlers.onComplete);
+  session.off('interrupted', handlers.onInterrupted);
+  session.off('error', handlers.onError);
+}

package/src/headless/headless-transport.ts

@@ -0,0 +1,43 @@
+/**
+ * ITransportAdapter implementation for headless transport.
+ *
+ * Wraps createHeadlessRunner into the unified ITransportAdapter interface.
+ * After start() completes, getExitCode() returns the runner's exit code.
+ */
+
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import { createHeadlessRunner } from './headless-runner.js';
+import type { TOutputFormat } from './headless-runner.js';
+
+export interface IHeadlessTransportOptions {
+  /** Output format: 'text', 'json', or 'stream-json'. */
+  outputFormat: TOutputFormat;
+  /** The prompt to execute. */
+  prompt: string;
+}
+
+export function createHeadlessTransport(
+  options: IHeadlessTransportOptions,
+): ITransportAdapter<IInteractiveSession> & { getExitCode(): number } {
+  let session: IInteractiveSession | null = null;
+  let exitCode = 0;
+
+  return {
+    name: 'headless',
+    attach(s: IInteractiveSession) {
+      session = s;
+    },
+    async start() {
+      if (!session) throw new Error('No session attached. Call attach() first.');
+      const runner = createHeadlessRunner({ session, outputFormat: options.outputFormat });
+      exitCode = await runner.run(options.prompt);
+    },
+    async stop() {
+      /* no-op: headless runner completes in start() */
+    },
+    getExitCode() {
+      return exitCode;
+    },
+  };
+}

package/src/headless/index.ts

@@ -0,0 +1,4 @@
+export { createHeadlessRunner } from './headless-runner.js';
+export type { IHeadlessRunnerOptions, TOutputFormat } from './headless-runner.js';
+export { createHeadlessTransport } from './headless-transport.js';
+export type { IHeadlessTransportOptions } from './headless-transport.js';

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

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createHttpTransport } from '../http-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('createHttpTransport', () => {
+  it('returns an adapter with name "http"', () => {
+    const transport = createHttpTransport();
+    expect(transport.name).toBe('http');
+  });
+
+  it('throws if start() is called without attach()', async () => {
+    const transport = createHttpTransport();
+    await expect(transport.start()).rejects.toThrow('No session attached');
+  });
+
+  it('throws if getApp() is called before start()', () => {
+    const transport = createHttpTransport();
+    expect(() => transport.getApp()).toThrow('Transport not started');
+  });
+
+  it('creates a Hono app after attach + start', async () => {
+    const transport = createHttpTransport();
+    transport.attach(createMockSession() as never);
+    await transport.start();
+    const app = transport.getApp();
+    expect(app).toBeDefined();
+    expect(typeof app.fetch).toBe('function');
+  });
+
+  it('nullifies app after stop()', async () => {
+    const transport = createHttpTransport();
+    transport.attach(createMockSession() as never);
+    await transport.start();
+    await transport.stop();
+    expect(() => transport.getApp()).toThrow('Transport not started');
+  });
+});

package/src/http/__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-framework';
+
+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/http-transport.ts

@@ -0,0 +1,42 @@
+/**
+ * ITransportAdapter implementation for HTTP transport.
+ *
+ * Wraps createAgentRoutes into the unified ITransportAdapter interface
+ * while exposing the underlying Hono app via getApp().
+ */
+
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+import type { IInteractiveSession } from '@robota-sdk/agent-framework';
+
+import { createAgentRoutes } from './routes.js';
+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/http/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';