@robota-sdk/agent-transport-http 3.0.0-beta.79 → 3.0.0-beta.82

package/src/__tests__/submit-stream.test.ts

@@ -0,0 +1,126 @@
+/**
+ * The relay's own failure modes — the ones an HTTP request cannot conveniently reach.
+ *
+ * `reportStreamFailure` runs after the headers are out, and `onAbort` runs when the client is
+ * already gone; both are places where "what does the other side learn" and "does the claim come
+ * back" have to be asked directly.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { relayTurn, reportStreamFailure } from '../submit-stream.js';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+import type { SSEStreamingApi } from 'hono/streaming';
+
+function fakeStream(overrides: Partial<SSEStreamingApi> = {}): {
+  stream: SSEStreamingApi;
+  written: Array<{ event?: string; data: string }>;
+} {
+  const written: Array<{ event?: string; data: string }> = [];
+  const stream = {
+    writeSSE: (message: { event?: string; data: string }) => {
+      written.push(message);
+      return Promise.resolve();
+    },
+    onAbort: () => {},
+    ...overrides,
+  } as unknown as SSEStreamingApi;
+  return { stream, written };
+}
+
+describe('what a client learns from a stream that failed after it opened', () => {
+  it('is a generic line, not the exception', async () => {
+    // Review, twice: this route can be mounted outside a trust boundary, and an exception ESCAPING
+    // the stream callback is not a message anything composed for a client — it can carry provider
+    // internals, paths, stack fragments. The detail goes to the package logger; the client learns
+    // that the stream failed, which is the part it can act on.
+    const { stream, written } = fakeStream();
+
+    await reportStreamFailure(new Error('ENOENT /home/op/.robota/providers/key.json'), stream);
+
+    expect(written).toHaveLength(1);
+    expect(written[0].data).not.toContain('key.json');
+    expect(written[0].data).toContain('the stream failed on the server');
+  });
+
+  it('swallows a write to a stream that is already gone', async () => {
+    const { stream } = fakeStream({
+      writeSSE: () => Promise.reject(new Error('closed')),
+    });
+
+    await expect(reportStreamFailure(new Error('x'), stream)).resolves.toBeUndefined();
+  });
+});
+
+describe('a failure in the callback never escapes to the runner', () => {
+  it('reports generically, hands the detail to the injected listener, and does not throw', async () => {
+    // Hono's runner follows any `onError` by writing the raw `e.message` to the stream — measured:
+    // the body carried the generic line AND the leak. So the boundary holds only if the callback
+    // catches its own failures, which is what this pins.
+    const detail = vi.fn();
+    const session = createTestInteractiveSession({
+      on: ((event: string) => {
+        if (event === 'text_delta') throw new Error('ENOENT /home/op/.robota/key.json');
+      }) as IInteractiveSession['on'],
+    });
+    const { stream, written } = fakeStream();
+
+    await expect(relayTurn(session, 'p', () => {}, detail)(stream)).resolves.toBeUndefined();
+
+    expect(detail).toHaveBeenCalledTimes(1);
+    expect(detail.mock.calls[0][0].message).toContain('key.json');
+    expect(written.map((w) => w.data).join('\n')).not.toContain('key.json');
+    expect(written.map((w) => w.data).join('\n')).toContain('the stream failed on the server');
+  });
+
+  it('still tells the client when the listener itself throws', async () => {
+    const { stream, written } = fakeStream();
+
+    await reportStreamFailure(new Error('detail'), stream, () => {
+      throw new Error('the host listener is broken');
+    });
+
+    expect(written).toHaveLength(1);
+    expect(written[0].data).toContain('the stream failed on the server');
+  });
+});
+
+describe('a client disconnect releases the claim even when abort throws', () => {
+  it('settles and releases', async () => {
+    // Review: before the claim registry this cost a listener leak; now an `abort()` that throws
+    // would hold the claim forever and 409 every future /submit to this session. `abort()` is typed
+    // as a synchronous void and the shipped one does not throw — this case is what turns that from
+    // a load-bearing assumption into an implementation detail.
+    const release = vi.fn();
+    // The conformant double, not a cast — the contract-cast ratchet refuses another one, and it is
+    // right to. `submit` resolves at once so the relay parks on `done`, which only the abort path
+    // settles here.
+    const session = createTestInteractiveSession({
+      abort: () => {
+        throw new Error('abort blew up');
+      },
+    });
+
+    let abortHandler!: () => void;
+    const { stream } = fakeStream({
+      onAbort: (handler: () => void) => {
+        abortHandler = handler;
+      },
+    });
+
+    const detail = vi.fn();
+    const relaying = relayTurn(session, 'prompt', release, detail)(stream);
+    // The abort handler runs inside Hono's abort dispatch, OUTSIDE the relay's try/catch — review
+    // traced where a rethrow lands (an unhandled rejection, not a reported failure). So it does not
+    // throw: the detail goes to the injected listener and the relay still settles.
+    expect(() => abortHandler()).not.toThrow();
+    await relaying;
+
+    expect(release).toHaveBeenCalledTimes(1);
+    expect(detail).toHaveBeenCalledTimes(1);
+    expect(detail.mock.calls[0][0].message).toBe('abort blew up');
+  });
+});

package/src/__tests__/turn-claims.test.ts

@@ -0,0 +1,102 @@
+/**
+ * RUNTIME-38 — the claim registry's own contract.
+ *
+ * It was exercised only through `routes.test.ts`, which asks HTTP questions and gets HTTP answers.
+ * Review asked for these directly, and the reason is the one this repository keeps rediscovering: a
+ * branch reached only through a wrapper is a branch whose behaviour is inferred. `keyFor` has three
+ * outcomes and two of them are about a session that misbehaves — the shapes an HTTP case would have
+ * to build a broken session to reach at all.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { createTurnClaims } from '../turn-claims.js';
+
+import type { IInteractiveSession } from '@robota-sdk/agent-interface-session';
+
+/**
+ * A session that names itself however the case needs it to.
+ *
+ * Built on the PUBLISHED conformant double rather than cast to the contract — `contract-cast-ratchet`
+ * refuses another cast, and it is right to: a cast is a partial re-implementation nothing checks
+ * against the real interface, so a member the contract gains later is silently absent from it.
+ */
+function sessionNamed(id: string): IInteractiveSession {
+  return createTestInteractiveSession({
+    getSession: () => ({ getSessionId: () => id }) as ReturnType<IInteractiveSession['getSession']>,
+  });
+}
+
+describe('the key a session is claimed under', () => {
+  it('is the id the session declares', () => {
+    expect(createTurnClaims().keyFor(sessionNamed('session_a'))).toBe('session_a');
+  });
+
+  it('does NOT depend on object identity', () => {
+    // The defect the id-keying replaced: a `sessionFactory` returning a fresh wrapper per call for
+    // one logical session made every request look unclaimed, and the guard was silently absent.
+    const claims = createTurnClaims();
+
+    expect(claims.keyFor(sessionNamed('same'))).toBe(claims.keyFor(sessionNamed('same')));
+  });
+
+  it('is undefined when the session names itself with an empty string', () => {
+    // Not `''`, which is a key: every unnameable session would collide into it and 409 each other.
+    expect(createTurnClaims().keyFor(sessionNamed(''))).toBeUndefined();
+  });
+
+  it('is undefined when the session THROWS while naming itself', () => {
+    const throwing = createTestInteractiveSession({
+      getSession: () => {
+        throw new Error('no session bound');
+      },
+    });
+
+    expect(createTurnClaims().keyFor(throwing)).toBeUndefined();
+  });
+});
+
+describe('holding and releasing a claim', () => {
+  it('reports a key as held only between hold and release', () => {
+    const claims = createTurnClaims();
+
+    expect(claims.isHeld('a')).toBe(false);
+    claims.hold('a');
+    expect(claims.isHeld('a')).toBe(true);
+    claims.release('a');
+    expect(claims.isHeld('a')).toBe(false);
+  });
+
+  it('holds each session separately', () => {
+    // PER SESSION, not one flag for the router: a busy neighbour is not a reason to refuse you, and
+    // a single flag made one tenant's turn refuse every other tenant's.
+    const claims = createTurnClaims();
+
+    claims.hold('tenant_a');
+
+    expect(claims.isHeld('tenant_a')).toBe(true);
+    expect(claims.isHeld('tenant_b')).toBe(false);
+  });
+
+  it('releases a key that was never held without complaint', () => {
+    // The teardown path runs in a `finally` and cannot know whether the claim was taken — a throw
+    // there would replace the error being unwound with one about bookkeeping.
+    const claims = createTurnClaims();
+
+    expect(() => claims.release('never-held')).not.toThrow();
+  });
+
+  it('is idempotent on a second hold, so one release still frees it', () => {
+    // The route holds once per request and releases once per request. Stating it here means a
+    // future counting implementation has to decide deliberately rather than by accident.
+    const claims = createTurnClaims();
+
+    claims.hold('a');
+    claims.hold('a');
+    claims.release('a');
+
+    expect(claims.isHeld('a')).toBe(false);
+  });
+});

package/src/http-session.ts

@@ -0,0 +1,20 @@
+import type {
+  ISessionCommands,
+  ISessionConversationRead,
+  ISessionEvents,
+  ISessionExecutionState,
+  ISessionIdentity,
+  ISessionTurnControl,
+  ISessionTurnSubmission,
+} from '@robota-sdk/agent-interface-session';
+
+/** The exact session capabilities consumed by the public HTTP transport. */
+export interface IHttpTransportSession
+  extends
+    ISessionTurnSubmission,
+    ISessionEvents,
+    ISessionTurnControl,
+    ISessionIdentity,
+    ISessionCommands,
+    ISessionConversationRead,
+    ISessionExecutionState {}

package/src/http-transport.ts

@@ -5,37 +5,88 @@
  * while exposing the underlying Hono app via getApp().
  */
 
+import { resolveAdmission } from '@robota-sdk/agent-transport/node';
+import { Hono } from 'hono';
+
 import { createAgentRoutes } from './routes.js';
 
-import type { IInteractiveSession, ITransportAdapter } from '@robota-sdk/agent-interface-transport';
-import type { Hono } from 'hono';
+import type { IHttpTransportSession } from './http-session.js';
+import type { TStreamFailureListener } from './submit-stream.js';
+import type {
+  ITransportAdapter,
+  ITransportAdmissionConfig,
+  ITransportLifecycleError,
+} from '@robota-sdk/agent-interface-transport';
 
 export interface IHttpTransportOptions {
   /** Optional: base path prefix for routes. */
   basePath?: string;
+  /**
+   * SEC-008: what a peer must present. Omitted means SECURE — a credential is minted and
+   * `getAdmissionToken()` returns it for the host to hand to its client.
+   *
+   * This transport previously had no gate at all, so omitting the option used to mean "anyone may
+   * execute anything". Omission now means the safe thing, and running open takes saying so.
+   */
+  admission?: ITransportAdmissionConfig;
+  /**
+   * Where the DETAIL of a post-headers stream failure goes — forwarded to `createAgentRoutes`.
+   * Review found this seam missing: the option existed on the routes and not on the entry point
+   * README and the examples actually use, so "the host decides the destination" was a decision no
+   * host on this path could make. Same forwarding rule as `admission`, which sat beside it.
+   */
+  onStreamFailure?: TStreamFailureListener;
+}
+
+export interface IHttpTransport extends ITransportAdapter<IHttpTransportSession> {
+  getApp(): Hono;
+  getAdmissionToken(): string | null;
 }
 
-export function createHttpTransport(
-  options?: IHttpTransportOptions,
-): ITransportAdapter<IInteractiveSession> & { getApp(): Hono } {
-  let session: IInteractiveSession | null = null;
+export function createHttpTransport(options?: IHttpTransportOptions): IHttpTransport {
+  let session: IHttpTransportSession | null = null;
   let app: Hono | null = null;
+  // Resolved at CONSTRUCTION, not at start: a host needs the credential to hand to its client, and
+  // a transport that cannot mint one must fail before anything is served.
+  const admission = resolveAdmission(options?.admission);
+  const lifecycleError = (code: ITransportLifecycleError['code']): ITransportLifecycleError =>
+    Object.assign(new Error(`HTTP transport ${code}.`), {
+      name: 'TransportLifecycleError' as const,
+      code,
+      transportName: 'http',
+    });
 
   return {
     name: 'http',
-    attach(s: IInteractiveSession) {
+    lifecycle: Object.freeze({ kind: 'service' }),
+    attach(s: IHttpTransportSession) {
       session = s;
     },
     async start() {
-      if (!session) throw new Error('No session attached. Call attach() first.');
-      app = createAgentRoutes({ sessionFactory: () => session! });
+      if (!session) throw lifecycleError('not-attached');
+      if (app) throw lifecycleError('already-started');
+      const routes = createAgentRoutes({
+        sessionFactory: () => session!,
+        // The decision already made, passed through — not taken apart and rebuilt for the routes to
+        // resolve a second time.
+        admission,
+        onStreamFailure: options?.onStreamFailure,
+      });
+      // TRANS-002 (issue #2480): `basePath` was declared and advertised but never read, so routes
+      // always mounted at root. It is honored here — or absent, in which case the routes ARE the app.
+      app = options?.basePath ? new Hono().route(options.basePath, routes) : routes;
     },
     async stop() {
       app = null;
+      session = null;
     },
     getApp() {
       if (!app) throw new Error('Transport not started. Call start() first.');
       return app;
     },
+    /** The credential this transport requires, or `null` when the host explicitly opened it. */
+    getAdmissionToken() {
+      return admission.token;
+    },
   };
 }

package/src/index.ts

@@ -1,4 +1,6 @@
 export { createAgentRoutes } from './routes.js';
 export type { IAgentRoutesOptions, TSessionFactory } from './routes.js';
+export type { TStreamFailureListener } from './submit-stream.js';
 export { createHttpTransport } from './http-transport.js';
-export type { IHttpTransportOptions } from './http-transport.js';
+export type { IHttpTransport, IHttpTransportOptions } from './http-transport.js';
+export type { IHttpTransportSession } from './http-session.js';

package/src/routes.ts

@@ -1,22 +1,49 @@
 /**
- * HTTP transport adapter — exposes IInteractiveSession over REST API.
+ * HTTP transport adapter — exposes the declared session capabilities over REST API.
  *
  * Built on Hono for Cloudflare Workers + Node.js + AWS Lambda compatibility.
- * Each endpoint maps 1:1 to an IInteractiveSession API method.
+ * Exposes the core session methods (a subset; background-task, job-group, and
+ * execution-workspace methods are WS-only).
  */
 
+import {
+  bearerCredential,
+  credentialMatches,
+  resolveAdmission,
+} from '@robota-sdk/agent-transport/node';
 import { Hono } from 'hono';
-import { streamSSE } from 'hono/streaming';
 
-import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
-import type { Context } from 'hono';
+import { submitHandler } from './submit-route.js';
+import { createTurnClaims } from './turn-claims.js';
 
-/** Callback that resolves an IInteractiveSession from the request context. */
-export type TSessionFactory = (c: Context) => IInteractiveSession | Promise<IInteractiveSession>;
+import type { TSessionFactory } from './submit-route.js';
+import type { TStreamFailureListener } from './submit-stream.js';
+import type {
+  ITransportAdmission,
+  ITransportAdmissionConfig,
+} from '@robota-sdk/agent-interface-transport';
+
+// Re-exported so existing importers keep their path; the definition and its rationale live with
+// the code that enforces them, in `submit-route.ts`.
+export type { TSessionFactory } from './submit-route.js';
 
 export interface IAgentRoutesOptions {
-  /** Resolve an IInteractiveSession per request (e.g., by auth token, session ID). */
+  /** Resolve an HTTP session port per request (e.g., by auth token, session ID). */
   sessionFactory: TSessionFactory;
+  /**
+   * Where the DETAIL of a post-headers stream failure goes (the client gets only a generic line —
+   * see `submit-stream.ts`). Injected per the side-concern rule: the host decides the destination,
+   * and absent means the host chose to drop it.
+   */
+  onStreamFailure?: TStreamFailureListener;
+  /**
+   * SEC-008: what a peer must present to reach the session. REQUIRED — there is no shape of this
+   * option that means "I did not think about it", which is the state these routes shipped in.
+   *
+   * `{ open: true, openReason: '…' }` still runs with no credential, and that is a legitimate answer
+   * for a host that has its own boundary in front. It just has to be written down.
+   */
+  admission: ITransportAdmissionConfig | ITransportAdmission;
 }
 
 /**
@@ -30,70 +57,49 @@ export interface IAgentRoutesOptions {
  * ```
  */
 export function createAgentRoutes(options: IAgentRoutesOptions): Hono {
-  const { sessionFactory } = options;
+  const { sessionFactory, onStreamFailure } = 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);
+  // RUNTIME-38: one turn at a time, per session — `turn-claims.ts` owns what that means and why it
+  // is keyed by the session's declared ID rather than by object identity.
+  const claims = createTurnClaims();
+
+  // SEC-008: resolved ONCE, at construction, so a transport that cannot mint a credential fails to
+  // build rather than serving without one. Resolving per request would also mint a new token per
+  // request, which no peer could ever present.
+  // Either shape goes in: `resolveAdmission` is idempotent, so an already-resolved admission comes
+  // back unchanged and a config is resolved. `http-transport.ts` therefore does not have to take
+  // its resolved admission apart and rebuild a config for this to resolve again — two resolutions
+  // of one decision, and a mint on the second if the first had opened without a reason (review).
+  //
+  // This used to pick between the two with `'token' in options.admission`, and review showed that
+  // cannot work: BOTH interfaces declare a `token`, so the shapes differ only by VALUE. A config of
+  // `{ token: '' }` — documented as "mint a fresh one" — was read as pre-resolved and installed the
+  // EMPTY STRING as the required credential, which a peer sending an empty bearer would match. The
+  // discriminator is gone rather than repaired; there is nothing here left to get wrong.
+  const admission = resolveAdmission(options.admission);
+
+  /**
+   * The trust boundary, installed BEFORE every route rather than checked inside each one.
+   *
+   * Before this, `POST /submit` reached `session.submit` and `POST /command` reached
+   * `session.executeCommand` with nothing in between — remote arbitrary execution with no gate, and
+   * an unauthenticated request looked exactly like an authorised one in both directions.
+   *
+   * A missing credential and a wrong one get the same answer, deliberately: telling them apart tells
+   * a caller which half they got right.
+   */
+  app.use('*', async (c, next) => {
+    if (admission.token === null) return next();
+    if (credentialMatches(admission.token, bearerCredential(c.req.header('authorization')))) {
+      return next();
     }
-
-    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();
-    });
+    return c.json({ error: 'unauthorized' }, 401);
   });
 
+  // POST /submit — execute prompt, stream events via SSE
+  app.post('/submit', submitHandler(sessionFactory, claims, onStreamFailure));
+
   // POST /command — execute system command
   app.post('/command', async (c) => {
     const session = await sessionFactory(c);
@@ -103,7 +109,11 @@ export function createAgentRoutes(options: IAgentRoutesOptions): Hono {
       return c.json({ error: 'name is required' }, 400);
     }
 
-    const result = await session.executeCommand(body.name, body.args ?? '');
+    // SEC-008: 'remote', not the default 'user'. A peer over HTTP is not the person at the keyboard,
+    // and defaulting to the local operator both mis-attributes the call and skips the 'remote' policy
+    // seam that exists to treat the two differently. Admission decided WHO may reach the session; it
+    // does not say who they are. (The MCP adapter had the same defect; this is its sibling.)
+    const result = await session.executeCommand(body.name, body.args ?? '', 'remote');
     if (!result) {
       return c.json({ error: `Unknown command: ${body.name}` }, 404);
     }
@@ -137,9 +147,16 @@ export function createAgentRoutes(options: IAgentRoutesOptions): Hono {
   });
 
   // GET /executing — check if currently executing
+  //
+  // Reports the SAME "busy" that `/submit` refuses on: the route's own claim OR the session's
+  // `isExecuting()`. Asking only the session lets a client polling here see `executing: false` and
+  // still get a 409 from `/submit`, and two endpoints disagreeing about one word is a worse answer
+  // than either of them alone.
   app.get('/executing', async (c) => {
     const session = await sessionFactory(c);
-    return c.json({ executing: session.isExecuting() });
+    const claim = claims.keyFor(session);
+    const claimed = claim !== undefined && claims.isHeld(claim);
+    return c.json({ executing: claimed || session.isExecuting() });
   });
 
   // GET /pending — get pending queued prompt