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

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@robota-sdk/agent-transport-http",
+  "version": "3.0.0-beta.100",
+  "description": "HTTP (Hono) transport for the Robota SDK",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "node": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      },
+      "default": {
+        "import": {
+          "types": "./dist/node/index.d.ts",
+          "default": "./dist/node/index.js"
+        },
+        "require": {
+          "types": "./dist/node/index.d.cts",
+          "default": "./dist/node/index.cjs"
+        }
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "hono": "^4.12.32",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.100",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.100",
+    "@robota-sdk/agent-transport": "3.0.0-beta.100"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.10",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6"
+  },
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "publishConfig": {
+    "access": "public"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}

package/src/__tests__/admission-loopback-scenario.test.ts

@@ -0,0 +1,198 @@
+/**
+ * SEC-008 — the user-execution scenario, as CODE.
+ *
+ * The closure of SEC-008 first carried this evidence as prose: a report that a run had happened
+ * once, with the runner not checked in. Review named the irony — SEC-008 is precisely about "the
+ * trust boundary being documentation rather than code", and the evidence for closing it was
+ * documentation rather than code. So the scenario lives here, where anyone can re-run it.
+ *
+ * What makes this different from the sibling route suites, which already cover the same code paths:
+ * it is a REAL HTTP round-trip over a REAL loopback socket, not an in-process `app.fetch()`. The
+ * thing being demonstrated is what an unauthenticated remote request DOES to a served transport, so
+ * the request has to actually travel.
+ *
+ * The observable is the session TRANSCRIPT — what reached `submit` — because "rejected" and "never
+ * executed" are different claims and only the second one is the security property.
+ */
+
+import { createServer, type Server } from 'node:http';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createHttpTransport } from '../http-transport.js';
+
+import type { IInteractiveSession, ITurnHandle } from '@robota-sdk/agent-interface-session';
+
+/**
+ * A CONFORMANT turn handle. Not `{ status: 'started' }` behind a cast: `ITurnHandle` is
+ * `{ turnId, completed }`, and a double that answers a different shape is a partial
+ * re-implementation the compiler was told to stop checking. The route only awaits the terminal
+ * event today, so the difference is invisible — until a call site reads `.completed`, at which
+ * point the double would misrepresent the contract silently. (#1684 review)
+ */
+function stubHandle(turnId: string): ITurnHandle {
+  return {
+    turnId,
+    completed: Promise.resolve({
+      response: '',
+      history: [],
+      toolSummaries: [],
+      contextState: { usedTokens: 0, maxTokens: 0, usedPercentage: 0, remainingPercentage: 100 },
+    }),
+  };
+}
+
+/** A session that RECORDS what actually reached it — the transcript the scenario asserts on. */
+function createRecordingSession(): { session: IInteractiveSession; transcript: string[] } {
+  const transcript: string[] = [];
+  const listeners = new Map<string, Set<(data: unknown) => void>>();
+  const emit = (event: string, data: unknown): void => {
+    for (const handler of listeners.get(event) ?? []) handler(data);
+  };
+  const session = createTestInteractiveSession({
+    isExecuting: () => false,
+    submit: (async (prompt: string) => {
+      transcript.push(prompt);
+      // The route's SSE stream ends on the terminal event; a session that never emits one leaves
+      // the request hanging, so the case would fail on a timeout — a red for the wrong reason.
+      queueMicrotask(() => emit('complete', { success: true, content: 'done' }));
+      return stubHandle('scenario-turn');
+    }) as IInteractiveSession['submit'],
+    on: ((event: string, handler: (data: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)?.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: (data: unknown) => void) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+  });
+  return { session, transcript };
+}
+
+const servers: Server[] = [];
+afterEach(async () => {
+  while (servers.length > 0) {
+    const server = servers.pop();
+    await new Promise<void>((resolve) => server?.close(() => resolve()));
+  }
+});
+
+/**
+ * Serve a transport's app on a real loopback port and return its base URL.
+ *
+ * `fetch` is typed as `Response | Promise<Response>` on Hono — it answers synchronously for some
+ * routes — so the parameter accepts both and the call site awaits, rather than narrowing the app to
+ * a shape it does not have.
+ */
+async function serve(app: {
+  fetch: (request: Request) => Response | Promise<Response>;
+}): Promise<string> {
+  const server = createServer((req, res) => {
+    void (async () => {
+      // Everything inside is guarded: an unhandled rejection here would leave `res.end()` uncalled,
+      // so the client-side `fetch` below would hang to the test timeout instead of failing with a
+      // cause. In a file whose whole subject is a gate that refuses LEGIBLY, an illegible hang is
+      // the wrong failure mode to build the harness on. (#1684 review)
+      try {
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) chunks.push(chunk as Buffer);
+        const address = server.address();
+        const port = typeof address === 'object' && address ? address.port : 0;
+        // Node's `IncomingHttpHeaders` values are `string | string[] | undefined`, which is not
+        // `HeadersInit` — casting across that gap works for this fixture's simple headers and
+        // silently mangles an array-valued one (`set-cookie`, a repeated header) the day the
+        // harness is reused. Built explicitly instead, so a repeated header stays repeated.
+        // (#1684 review)
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(req.headers)) {
+          if (Array.isArray(value)) for (const item of value) headers.append(name, item);
+          else if (value !== undefined) headers.set(name, value);
+        }
+        const response = await app.fetch(
+          new Request(`http://127.0.0.1:${port}${req.url ?? '/'}`, {
+            method: req.method,
+            headers,
+            body: req.method === 'GET' || req.method === 'HEAD' ? undefined : Buffer.concat(chunks),
+          }),
+        );
+        res.statusCode = response.status;
+        res.end(await response.text());
+      } catch (error) {
+        // 500 with the cause in the body, so a broken harness reads as a broken harness rather than
+        // as a transport that answered nothing.
+        res.statusCode = 500;
+        res.end(
+          `scenario harness failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    })();
+  });
+  servers.push(server);
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  return `http://127.0.0.1:${port}`;
+}
+
+async function submit(base: string, prompt: string, headers: Record<string, string> = {}) {
+  const res = await fetch(`${base}/submit`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: JSON.stringify({ prompt }),
+  });
+  return { status: res.status, body: await res.text() };
+}
+
+describe('SEC-008 scenario — an unauthenticated remote request reaches no session', () => {
+  it('rejects POST /submit with no credential, and the prompt is NEVER executed', async () => {
+    // `admission` omitted is the shipped default and means SECURE: a credential is minted.
+    const transport = createHttpTransport();
+    const { session, transcript } = createRecordingSession();
+    transport.attach(session);
+    await transport.start();
+    const base = await serve(transport.getApp());
+
+    const res = await submit(base, 'hello from an unauthenticated caller');
+
+    expect(res.status, `expected a rejection, got ${res.status} ${res.body}`).toBe(401);
+    // The security property is not "answered 401" — it is that nothing ran.
+    expect(transcript, 'the unauthenticated prompt reached the session').toEqual([]);
+  });
+
+  it('accepts the same request with the minted credential, and only that prompt runs', async () => {
+    const transport = createHttpTransport();
+    const { session, transcript } = createRecordingSession();
+    transport.attach(session);
+    await transport.start();
+    const base = await serve(transport.getApp());
+    const token = transport.getAdmissionToken();
+
+    expect(token, 'omitting admission must MINT a credential, not run open').toBeTruthy();
+
+    const rejected = await submit(base, 'unauthenticated');
+    const accepted = await submit(base, 'authenticated', { authorization: `Bearer ${token}` });
+
+    expect(rejected.status).toBe(401);
+    expect(accepted.status, `expected success, got ${accepted.status} ${accepted.body}`).toBe(200);
+    expect(transcript).toEqual(['authenticated']);
+  });
+
+  it('CONTRAST: an explicitly OPEN transport executes the same unauthenticated prompt', async () => {
+    // What the absent gate used to do for every caller. Reaching this state now takes asking for it
+    // AND writing down why — `openReason` is required, and `open` with a token is refused outright.
+    const transport = createHttpTransport({
+      admission: { open: true, openReason: 'SEC-008 scenario: the contrast this closure rests on' },
+    });
+    const { session, transcript } = createRecordingSession();
+    transport.attach(session);
+    await transport.start();
+    const base = await serve(transport.getApp());
+
+    const res = await submit(base, 'unauthenticated against an open transport');
+
+    expect(transport.getAdmissionToken(), 'an open transport holds no credential').toBeNull();
+    expect(res.status).toBe(200);
+    expect(transcript).toEqual(['unauthenticated against an open transport']);
+  });
+});

package/src/__tests__/http-base-path.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { createHttpTransport } from '../http-transport.js';
+
+import type { IHttpTransportSession } from '../http-session.js';
+
+/**
+ * Issue #2480 (TRANS-002): `basePath` was declared and advertised but never read, so routes always
+ * mounted at root. It is honored now.
+ */
+describe('createHttpTransport basePath', () => {
+  it('mounts every route under basePath when one is given', async () => {
+    const transport = createHttpTransport({
+      basePath: '/api',
+      admission: { open: true, openReason: 'basePath test' },
+    });
+    transport.attach({} as IHttpTransportSession);
+    await transport.start();
+    const paths = transport.getApp().routes.map((route) => route.path);
+    expect(paths.length).toBeGreaterThan(0);
+    expect(paths.every((path) => path.startsWith('/api'))).toBe(true);
+  });
+
+  it('mounts at root when basePath is absent', async () => {
+    const transport = createHttpTransport({
+      admission: { open: true, openReason: 'basePath test' },
+    });
+    transport.attach({} as IHttpTransportSession);
+    await transport.start();
+    const paths = transport.getApp().routes.map((route) => route.path);
+    expect(paths.some((path) => path.startsWith('/api'))).toBe(false);
+  });
+});

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

@@ -0,0 +1,174 @@
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, it, expect, expectTypeOf } from 'vitest';
+import { createHttpTransport } from '../http-transport.js';
+import type { IHttpTransportSession } from '../http-session.js';
+import type { IHttpTransport } from '../http-transport.js';
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
+
+function createMockSession(): IHttpTransportSession {
+  const full = createTestInteractiveSession();
+  const {
+    submit,
+    on,
+    off,
+    abort,
+    cancelQueue,
+    getSession,
+    executeCommand,
+    listCommands,
+    listSkills,
+    listModels,
+    getMessages,
+    getFullHistory,
+    getMessagesDisplay,
+    getContextState,
+    isExecuting,
+    getPendingPrompt,
+    getPendingCount,
+    resolvePermission,
+    resolveAsk,
+  } = full;
+  return {
+    submit,
+    on,
+    off,
+    abort,
+    cancelQueue,
+    getSession,
+    executeCommand,
+    listCommands,
+    listSkills,
+    listModels,
+    getMessages,
+    getFullHistory,
+    getMessagesDisplay,
+    getContextState,
+    isExecuting,
+    getPendingPrompt,
+    getPendingCount,
+    resolvePermission,
+    resolveAsk,
+  };
+}
+
+describe('createHttpTransport', () => {
+  it('requires exactly the HTTP session port without a broad attach overload', () => {
+    const transport = createHttpTransport();
+    expectTypeOf(transport).toMatchTypeOf<ITransportAdapter<IHttpTransportSession>>();
+    expectTypeOf<IHttpTransport['attach']>().toEqualTypeOf<
+      (session: IHttpTransportSession) => void
+    >();
+    expectTypeOf<IHttpTransportSession>().not.toHaveProperty('listRuntimeTools');
+    // #3282 §2 added `listModels` to `ISessionCommands` (15 + 1); #3288 §2 added `getMessagesDisplay`
+    // to `ISessionConversationRead` (16 + 1); #3449 added `ISessionPromptResolution` (17 + 2).
+    expect(Object.keys(createMockSession())).toHaveLength(19);
+  });
+
+  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.toMatchObject({
+      name: 'TransportLifecycleError',
+      code: 'not-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());
+    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());
+    await transport.start();
+    await transport.stop();
+    expect(() => transport.getApp()).toThrow('Transport not started');
+  });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-http#createHttpTransport',
+      kind: 'service',
+      createAdapter: () =>
+        createHttpTransport({
+          admission: { open: true, openReason: 'ARCH-011 lifecycle conformance' },
+        }),
+      createSession: createMockSession,
+      assertReady: (transport) => {
+        if (typeof transport.getApp().fetch !== 'function') throw new Error('HTTP app not ready');
+      },
+      assertStopped: (transport) => {
+        try {
+          transport.getApp();
+          throw new Error('HTTP app still ready');
+        } catch (error) {
+          if (!(error instanceof Error) || error.message === 'HTTP app still ready') throw error;
+        }
+      },
+    });
+  });
+});
+
+describe('SEC-008: the decision is resolved once', () => {
+  it('requires the credential it minted, not a second one', async () => {
+    // The transport resolved admission at construction and then rebuilt a CONFIG for the routes to
+    // resolve again. Two resolutions of one decision: harmless while a token was given, and a fresh
+    // mint on the second pass if the first had opened without a reason — so the credential the host
+    // was handed by `getAdmissionToken()` would not be the one the routes required.
+    const transport = createHttpTransport();
+    transport.attach(createMockSession());
+    await transport.start();
+    const token = transport.getAdmissionToken();
+
+    expect(token).not.toBeNull();
+    const refused = await transport.getApp().request('/executing');
+    const admitted = await transport
+      .getApp()
+      .request('/executing', { headers: { authorization: `Bearer ${token}` } });
+
+    expect(refused.status).toBe(401);
+    expect(admitted.status, 'the token the host was handed does not open the door').toBe(200);
+  });
+
+  it('MINTS for `token: ""`, and the host is handed what it must present', async () => {
+    // `{ token: '' }` is documented as "mint a fresh one". This pins the outcome end to end.
+    //
+    // It does NOT red-prove the discriminator defect, and saying so is the point of this comment:
+    // `createHttpTransport` resolves at construction, so the routes it builds receive an
+    // already-resolved admission and the discriminator handled that case correctly. The defect was
+    // only reachable through `createAgentRoutes` DIRECTLY — measured, this case passes either way.
+    //
+    // Through that direct path the defect has no black-box symptom either: "requires the empty
+    // string" and "requires a token you were not given" are both 401 forever, because
+    // `bearerCredential` requires at least one character after `Bearer ` and so a presented
+    // credential is never the empty string. It is a LOCKOUT, not a bypass. That is exactly why the
+    // fix deletes the discriminator instead of testing around it, and why the case that IS red on
+    // it lives at the seam (`agent-transport/src/__tests__/admission.test.ts`).
+    const transport = createHttpTransport({ admission: { token: '' } });
+    transport.attach(createMockSession());
+    await transport.start();
+    const token = transport.getAdmissionToken();
+
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+    const admitted = await transport
+      .getApp()
+      .request('/executing', { headers: { authorization: `Bearer ${token}` } });
+    expect(admitted.status, 'the token the host was handed does not open the door').toBe(200);
+  });
+});