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

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/.fixture-state/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/.fixture-state/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,29 @@
+import type {
+  ISessionCommands,
+  ISessionConversationRead,
+  ISessionEvents,
+  ISessionExecutionState,
+  ISessionIdentity,
+  ISessionPromptResolution,
+  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,
+    ISessionPromptResolution,
+    ISessionCommands,
+    ISessionConversationRead,
+    ISessionExecutionState {
+  /**
+   * Resolves once the session can name itself, and rejects if it failed to start. A session that
+   * builds itself in the background (`InteractiveSession`) has no id before then, so `/submit` waits
+   * on this before claiming a turn. A session that is ready at construction can omit it.
+   */
+  whenInitialized?(): Promise<void>;
+}

package/src/http-transport.ts

@@ -0,0 +1,95 @@
+/**
+ * ITransportAdapter implementation for HTTP transport.
+ *
+ * Wraps createAgentRoutes into the unified ITransportAdapter interface
+ * 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 { IHttpTransportSession } from './http-session.js';
+import type { TStreamFailureListener, TTurnAttribution } 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;
+  /** Who `/submit` turns are attributed to — forwarded to `createAgentRoutes`, like `admission`. */
+  attribution?: TTurnAttribution;
+}
+
+export interface IHttpTransport extends ITransportAdapter<IHttpTransportSession> {
+  getApp(): Hono;
+  getAdmissionToken(): string | 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',
+    lifecycle: Object.freeze({ kind: 'service' }),
+    attach(s: IHttpTransportSession) {
+      session = s;
+    },
+    async start() {
+      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,
+        attribution: options?.attribution,
+      });
+      // 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

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

package/src/open-prompts.ts

@@ -0,0 +1,56 @@
+/**
+ * The permission and ask prompts a `/submit` stream forwarded and that are still open, per session.
+ *
+ * The session emits a prompt once, when it is asked, so a client that comes later would never see
+ * it; `GET /prompts` answers from here, and `POST /prompts/:id` refuses an id that is not here.
+ *
+ * Keyed by the session's id, the same key as the turn claim, and not by object identity: the session
+ * factory may return a fresh wrapper per request, so the `agent-transport` registry (a WeakMap on the
+ * session object) would never find the prompt a different request recorded.
+ *
+ * It learns only through the prompt-receiving stream's own subscriptions and never listens to the
+ * session itself. A listener of its own would keep an unattended turn's prompt parked instead of
+ * letting the session fail it closed. A session's entries go when that stream's claim is released.
+ */
+
+import type {
+  IAskRequestEvent,
+  IPermissionRequestEvent,
+} from '@robota-sdk/agent-interface-session';
+
+export type THttpPromptFrame =
+  | { readonly type: 'permission_request'; readonly event: IPermissionRequestEvent }
+  | { readonly type: 'ask_request'; readonly event: IAskRequestEvent };
+
+export interface IHttpOpenPrompts {
+  record(sessionKey: string, frame: THttpPromptFrame): void;
+  forget(sessionKey: string, id: string): void;
+  /** The session's open prompts, oldest first. */
+  list(sessionKey: string): readonly THttpPromptFrame[];
+  find(sessionKey: string, id: string): THttpPromptFrame | undefined;
+  /** The stream that received the session's prompts has ended. */
+  clear(sessionKey: string): void;
+}
+
+export function createHttpOpenPrompts(): IHttpOpenPrompts {
+  const bySession = new Map<string, Map<string, THttpPromptFrame>>();
+
+  return {
+    record(sessionKey, frame) {
+      let open = bySession.get(sessionKey);
+      if (open === undefined) {
+        open = new Map();
+        bySession.set(sessionKey, open);
+      }
+      open.set(frame.event.id, frame);
+    },
+    forget(sessionKey, id) {
+      bySession.get(sessionKey)?.delete(id);
+    },
+    list: (sessionKey) => [...(bySession.get(sessionKey)?.values() ?? [])],
+    find: (sessionKey, id) => bySession.get(sessionKey)?.get(id),
+    clear(sessionKey) {
+      bySession.delete(sessionKey);
+    },
+  };
+}

package/src/prompt-routes.ts

@@ -0,0 +1,101 @@
+/**
+ * `GET /prompts` and `POST /prompts/:id` — reading and answering the permission and ask prompts a
+ * prompt-receiving `/submit` stream forwarded.
+ *
+ * Split from `routes.ts` for the same reason `/submit` is: these routes carry a decision of their own
+ * (is this id open here, and is this answer the right kind for it), not just a mount.
+ */
+
+import { decodeClientMessage } from '@robota-sdk/agent-transport';
+
+import type { IHttpOpenPrompts } from './open-prompts.js';
+import type { TSessionFactory } from './submit-route.js';
+import type { TTurnAttribution } from './submit-stream.js';
+import type { ITurnClaims } from './turn-claims.js';
+import type { Context } from 'hono';
+
+export interface IPromptRouteDeps {
+  readonly sessionFactory: TSessionFactory;
+  readonly claims: ITurnClaims;
+  readonly openPrompts: IHttpOpenPrompts;
+  readonly attribution?: TTurnAttribution;
+}
+
+/** The open prompts of the request's session, oldest first: what a client that came later reads. */
+export function listPromptsHandler(deps: IPromptRouteDeps) {
+  return async (c: Context) => {
+    const session = await deps.sessionFactory(c);
+    const key = deps.claims.keyFor(session);
+    return c.json({ prompts: key === undefined ? [] : deps.openPrompts.list(key) });
+  };
+}
+
+/**
+ * Answer one open prompt by id.
+ *
+ * The id must be one this session's prompt-receiving stream forwarded and that is still open. An id
+ * that never was and one already settled get the same 404: the client cannot act differently on the
+ * two, and the registry forgets a prompt once it settles.
+ *
+ * The answerer is the HOST's `attribution.driverId`, never the request, for the same reason `/submit`
+ * attribution is: a client must not record its answer as another surface's.
+ *
+ * Nothing awaits between the lookup and the resolve. The session settles synchronously and emits
+ * `prompt_resolved`, which the stream forwards and the registry forgets, so a second answer for the
+ * same id finds nothing open and is refused rather than reported as accepted.
+ *
+ * `200` means the prompt settled, not merely that the answer was handed over: the session ignores an
+ * answer it does not take (one in an outside party's name, say), and a prompt still open after the
+ * resolve is answered `409` so the client does not believe it decided something it did not.
+ */
+export function answerPromptHandler(deps: IPromptRouteDeps) {
+  const { sessionFactory, claims, openPrompts, attribution } = deps;
+  return async (c: Context) => {
+    const session = await sessionFactory(c);
+    const id = c.req.param('id') ?? '';
+    let body: { result?: unknown; response?: unknown };
+    try {
+      body = await c.req.json();
+    } catch {
+      return c.json({ error: 'the body must be a JSON object' }, 400);
+    }
+
+    const key = claims.keyFor(session);
+    const frame = key === undefined ? undefined : openPrompts.find(key, id);
+    if (key === undefined || frame === undefined) {
+      return c.json({ error: 'no open prompt with this id' }, 404);
+    }
+
+    if (frame.type === 'permission_request') {
+      const decoded = decodeClientMessage({
+        type: 'permission-response',
+        id,
+        result: body?.result,
+      });
+      if (!decoded.ok || decoded.message.type !== 'permission-response') {
+        return c.json(
+          { error: 'result must be true, false, "allow-session" or "allow-project"' },
+          400,
+        );
+      }
+      session.resolvePermission(id, decoded.message.result, attribution?.driverId);
+    } else {
+      const decoded = decodeClientMessage({ type: 'ask-response', id, response: body?.response });
+      if (!decoded.ok || decoded.message.type !== 'ask-response') {
+        return c.json(
+          {
+            error:
+              'response must be { "type": "answer", "values": string[], "text"?: string } or ' +
+              '{ "type": "cancelled" }',
+          },
+          400,
+        );
+      }
+      session.resolveAsk(id, decoded.message.response, attribution?.driverId);
+    }
+    if (openPrompts.find(key, id) !== undefined) {
+      return c.json({ error: 'the session did not accept this answer' }, 409);
+    }
+    return c.json({ ok: true });
+  };
+}