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

package/src/routes.ts

@@ -0,0 +1,190 @@
+/**
+ * HTTP transport adapter — exposes the declared session capabilities over REST API.
+ *
+ * Built on Hono for Cloudflare Workers + Node.js + AWS Lambda compatibility.
+ * 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 { createHttpOpenPrompts } from './open-prompts.js';
+import { answerPromptHandler, listPromptsHandler } from './prompt-routes.js';
+import { submitHandler } from './submit-route.js';
+import { createTurnClaims } from './turn-claims.js';
+
+import type { TSessionFactory } from './submit-route.js';
+import type { TStreamFailureListener, TTurnAttribution } 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 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;
+  /**
+   * Who `/submit` turns and prompt answers are attributed to — the driver and product surface the
+   * HOST assigns, as the WebSocket transport's `driverId`/`surface` do. Never taken from the request
+   * body. Absent leaves the session's own default.
+   */
+  attribution?: TTurnAttribution;
+}
+
+/**
+ * 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, onStreamFailure, attribution } = options;
+  const app = new Hono();
+
+  // 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();
+  const openPrompts = createHttpOpenPrompts();
+
+  // 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 c.json({ error: 'unauthorized' }, 401);
+  });
+
+  // POST /submit — execute prompt, stream events via SSE
+  app.post(
+    '/submit',
+    submitHandler({ sessionFactory, claims, openPrompts, onStreamFailure, attribution }),
+  );
+
+  // GET /prompts — the open permission/ask prompts a prompt-receiving /submit stream forwarded
+  app.get('/prompts', listPromptsHandler({ sessionFactory, claims, openPrompts, attribution }));
+
+  // POST /prompts/:id — answer one of them
+  app.post(
+    '/prompts/:id',
+    answerPromptHandler({ sessionFactory, claims, openPrompts, attribution }),
+  );
+
+  // 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);
+    }
+
+    // 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);
+    }
+    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
+  //
+  // 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);
+    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
+  app.get('/pending', async (c) => {
+    const session = await sessionFactory(c);
+    return c.json({ pending: session.getPendingPrompt() });
+  });
+
+  return app;
+}

package/src/submit-route.ts

@@ -0,0 +1,196 @@
+/**
+ * `POST /submit` — the admission decision and the handler that hands an admitted turn to the relay.
+ *
+ * Split from `routes.ts` under the file-size ceiling, along the same seam the review rounds carved:
+ * the route factory is a LIST of routes, and this one carries the concurrency-admission decision
+ * plus the claim lifecycle, which is a different job from mounting endpoints.
+ */
+
+import { streamSSE } from 'hono/streaming';
+
+import { relayTurn } from './submit-stream.js';
+
+import type { IHttpTransportSession } from './http-session.js';
+import type { IHttpOpenPrompts } from './open-prompts.js';
+import type { IRelayPrompts, TStreamFailureListener, TTurnAttribution } from './submit-stream.js';
+import type { ITurnClaims } from './turn-claims.js';
+import type { Context } from 'hono';
+
+/**
+ * Callback that resolves an HTTP session port from the request context.
+ *
+ * It need NOT return the same object twice for the same logical session. It briefly did: `/submit`
+ * keyed its concurrent-turn claim on object identity, so a factory building a fresh wrapper per
+ * call — a proxy, an adapter, a `{...session}` copy — defeated the guard in silence. The first
+ * answer was to document that as a requirement callers had to keep, and a requirement neither the
+ * type system nor a test can check is not a contract, it is a hope.
+ *
+ * What the session already promises is enough. `getSession(): { getSessionId(): string }` names the
+ * session, the claim is keyed by that name, and the requirement is gone rather than written down.
+ *
+ * The session must therefore BE nameable. `/submit` refuses with 500 when `getSessionId()` returns
+ * nothing, because without an id the concurrent-turn guarantee does not exist and serving anyway
+ * would hand back the bug to whoever could least tell. The contract types that method as returning
+ * a `string`, so a conformant session never meets it.
+ *
+ * (Review moved this block here: it sat on the RE-EXPORT in `routes.ts` after the split, where the
+ * person editing the definition would never see it.)
+ */
+export type TSessionFactory = (
+  c: Context,
+) => IHttpTransportSession | Promise<IHttpTransportSession>;
+
+/**
+ * Admit this request to ONE turn on its session, or answer why not.
+ *
+ * Returns the claim key it HOLDS on success — the caller owes its release — or the refusal
+ * Response. A named unit, and review is why: the admission decision (nameable? busy? claim) is what
+ * this route decides, independently testable from the stream wiring it hands the turn to.
+ */
+function admitTurn(
+  c: Context,
+  session: IHttpTransportSession,
+  claims: ITurnClaims,
+): Response | { claim: string } {
+  // RUNTIME-38: the session is single-threaded (one turn at a time) and shared across requests, so a
+  // concurrent /submit would cross-subscribe to the same emitter and interleave two clients' events.
+  //
+  // The route CLAIMS the turn rather than asking whether one is running, and that difference is the
+  // whole fix. `session.isExecuting()` is set inside `submit()` past an `await ensureInitialized()`
+  // — an unconditional suspension point — so two requests both read `false`, both call `submit`, and
+  // the loser coalesces into the pending queue while its HTTP response streams back the WINNER'S
+  // events. One turn delivered to two clients as if each had asked for it, which is worse than the
+  // race the earlier comment described and then wrongly declared absent.
+  //
+  // A synchronous flag on the route closes it because there is no suspension point between reading
+  // and setting it. It is released in the stream's `finally`, so a turn that throws does not leave
+  // the route wedged.
+  //
+  // BOTH are asked because neither subsumes the other. The claim is what this ROUTE knows;
+  // `isExecuting()` is what the SESSION knows, including a turn started by another surface — the
+  // TUI, a WS client, a previous process — which the claim cannot see.
+  // A session that cannot name itself is REFUSED, not served racily. The busy check is a guarantee
+  // only while the claim is keyed by a real id: with no id it falls back to `isExecuting()` alone,
+  // which the comment above documents as the racy read this route exists to stop relying on.
+  // Serving anyway would degrade the fix back into the bug for exactly the callers who could not
+  // be told they were affected.
+  //
+  // `getSession(): { getSessionId(): string }` is required by the contract, so this is unreachable
+  // for a conformant session. It is a 500 rather than a 503: the session is not temporarily
+  // unavailable, it does not meet the contract this route is built on, which is a defect on the
+  // server side of the boundary and not a condition that clears on retry.
+  const claim = claims.keyFor(session);
+  if (claim === undefined) {
+    return c.json(
+      {
+        // No internal method signature: this route can be mounted outside a trust boundary, and
+        // the caller cannot act on `getSession().getSessionId()` anyway — it names a contract
+        // they do not implement. The HOST needs the detail and gets it from the comment above
+        // this branch; the client needs to know its request was refused and why in its own terms.
+        error:
+          'concurrent-turn tracking is unavailable for this session, so this request cannot be ' +
+          'served safely. Refusing rather than starting a turn that cannot be guaranteed to be ' +
+          'yours.',
+      },
+      500,
+    );
+  }
+  if (claims.isHeld(claim) || session.isExecuting()) {
+    return c.json({ error: 'session busy — a turn is already in flight' }, 409);
+  }
+  claims.hold(claim);
+  return { claim };
+}
+
+export interface ISubmitRouteDeps {
+  readonly sessionFactory: TSessionFactory;
+  readonly claims: ITurnClaims;
+  readonly openPrompts: IHttpOpenPrompts;
+  readonly onStreamFailure?: TStreamFailureListener;
+  readonly attribution?: TTurnAttribution;
+}
+
+export function submitHandler(deps: ISubmitRouteDeps) {
+  const { sessionFactory, claims, openPrompts, onStreamFailure, attribution } = deps;
+  return async (c: Context) => {
+    const session = await sessionFactory(c);
+    const body = await c.req.json<{ prompt: string; receivePrompts?: unknown }>();
+
+    if (!body.prompt || typeof body.prompt !== 'string') {
+      return c.json({ error: 'prompt is required' }, 400);
+    }
+    if (body.receivePrompts !== undefined && typeof body.receivePrompts !== 'boolean') {
+      return c.json({ error: 'receivePrompts must be a boolean' }, 400);
+    }
+
+    // A session still building itself cannot name itself yet, and the claim needs its name. The
+    // claim itself is still taken synchronously after this, so two requests that both waited here
+    // start one turn between them.
+    if (session.whenInitialized !== undefined) {
+      try {
+        await session.whenInitialized();
+      } catch {
+        // The reason can name host paths or settings; the client only needs to know it failed.
+        return c.json({ error: 'the session could not be started' }, 500);
+      }
+    }
+
+    const admitted = admitTurn(c, session, claims);
+    if (admitted instanceof Response) {
+      return admitted;
+    }
+    const { claim } = admitted;
+    // SINGLE-SHOT, and review traced the double-release it prevents: the relay's teardown releases
+    // this claim on the normal path, and if a future Hono ever rejected the outer promise AFTER the
+    // callback completed, the catch below would release the SAME KEY a second time — by which point
+    // another request may hold it, and the second release would free that request's claim, which is
+    // the cross-talk this registry exists to prevent. A release that has happened is not a release
+    // that can happen again.
+    let released = false;
+    const releaseOnce = (): void => {
+      if (!released) {
+        released = true;
+        // The stream that held this session's prompts is gone; what is still open is the session's
+        // to settle, and no longer this route's to list or answer.
+        openPrompts.clear(claim);
+        claims.release(claim);
+      }
+    };
+    const prompts: IRelayPrompts | undefined =
+      body.receivePrompts === true
+        ? {
+            record: (frame) => openPrompts.record(claim, frame),
+            forget: (id) => openPrompts.forget(claim, id),
+          }
+        : undefined;
+
+    // The claim is taken OUTSIDE the callback, so its release cannot live only in the callback's
+    // `finally` — a claim whose release is not in the same protected region is a lock, not a claim,
+    // which this file states one level in. If `streamSSE` throws before it ever runs the callback,
+    // this releases and rethrows; the callback's own `finally` covers everything after it starts.
+    //
+    // REPRODUCED at the module boundary: `routes-streamsse-throw.test.ts` mocks `hono/streaming`
+    // to throw before the callback ever runs and asserts the second request is not 409 — a leaked
+    // claim is what this catch exists to prevent. Two rounds shipped it as honestly-labelled
+    // unverified code (a throw from `session.on` lands INSIDE the callback, where the inner
+    // `finally` releases — measured, a case built that way is green with this catch removed), and
+    // review supplied the third option: stub the boundary, not Hono's internals.
+    try {
+      // NO third argument, deliberately: Hono's runner follows any `onError` by writing the raw
+      // `e.message` to the stream, so the only leak-proof shape is a callback nothing escapes —
+      // `relayTurn` catches its own failures and reports them generically. An onError here would be
+      // dead code that turns into a leak the day it stops being dead.
+      // `await`, so the catch below covers a REJECTION as well as a synchronous throw. Today's
+      // Hono returns the Response synchronously and only the sync path is real — but review is
+      // right that a version returning a rejecting promise would sail past a bare `return`, and
+      // the cost of closing that class is one keyword.
+      return await streamSSE(
+        c,
+        relayTurn(session, body.prompt, releaseOnce, onStreamFailure, attribution, prompts),
+      );
+    } catch (error) {
+      releaseOnce();
+      throw error;
+    }
+  };
+}

package/src/submit-stream.ts

@@ -0,0 +1,289 @@
+/**
+ * RUNTIME-14 / RUNTIME-38 — relaying ONE turn to an SSE client, and letting go of it afterwards.
+ *
+ * Split out of `routes.ts` under the file-size ceiling. The route's job is to decide whether this
+ * request may start a turn; relaying the turn's events, tearing the subscriptions down, and telling
+ * a client whose stream broke after the headers went out is a different job with its own failure
+ * modes, and it was four fifths of the handler.
+ */
+
+import type { IHttpTransportSession } from './http-session.js';
+import type { THttpPromptFrame } from './open-prompts.js';
+import type { SSEStreamingApi } from 'hono/streaming';
+import type {
+  IAskRequestEvent,
+  IPermissionRequestEvent,
+  IPromptResolvedEvent,
+  ISubmitOptions,
+} from '@robota-sdk/agent-interface-session';
+
+/**
+ * Where the DETAIL of a post-headers stream failure goes — injected, never imported.
+ *
+ * The first version imported `createLogger` from `agent-core`, and review held it against two
+ * authorities at once: `project-structure.md` declares this package contract-pure (transports
+ * depend on the contracts and the protocol, nothing else), and its side-concern rule says a logging
+ * destination "must be injected, not imported directly". The host that mounts this router decides
+ * where diagnostics go; a module-level singleton decided it for every host, with no override.
+ *
+ * Absent, the detail is dropped — by the HOST's explicit default, which is a different thing from
+ * this module deleting it: the client still learns the stream failed, and the host was offered the
+ * detail at the boundary where it mounts the route.
+ */
+export type TStreamFailureListener = (error: Error) => void;
+
+/**
+ * Who a submitted turn is attributed to, assigned by the HOST that composed the routes — never read
+ * from the request, because a client could otherwise claim to be the local operator or another
+ * surface in the usage record. Absent means the session's own default.
+ */
+export type TTurnAttribution = Pick<ISubmitOptions, 'driverId' | 'surface'>;
+
+/**
+ * Where a prompt-receiving stream reports the prompts it forwarded, so a later request can list or
+ * answer them. Present only when the client asked to receive prompts.
+ */
+export interface IRelayPrompts {
+  record(frame: THttpPromptFrame): void;
+  forget(id: string): void;
+}
+
+/**
+ * Wire every relay subscription and the abort path; answer with the promise that settles when the
+ * turn is over (or refused one).
+ *
+ * The subscriptions are wired OUTSIDE the promise executor. Inside it, a throw from `session.on` —
+ * a bad handler, an EventEmitter listener cap — is caught by the Promise constructor and becomes an
+ * already-rejected `done` instead of propagating. Execution then reaches `await session.submit`, so
+ * a REAL TURN is consumed with only some of its listeners attached and nothing to relay it, and the
+ * rejection surfaces afterwards at `await done` — by which point the turn is gone.
+ */
+function wireRelay(
+  session: IHttpTransportSession,
+  stream: SSEStreamingApi,
+  cleanup: Array<() => void>,
+  onFailure: TStreamFailureListener | undefined,
+  prompts: IRelayPrompts | undefined,
+): Promise<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));
+  };
+
+  // RUNTIME-14: await + catch every SSE write so a write to a client-closed stream is a blessed
+  // no-op, not an unhandled rejection (post-headers errors bypass Hono's onError).
+  const write = (event: string, data: unknown): Promise<void> =>
+    stream.writeSSE({ event, data: JSON.stringify(data) }).catch(() => {
+      // allow-fallback: client closed the stream mid-write — nothing to deliver; the finally teardown
+      // (RUNTIME-14) removes the listeners, so this write has nothing left to do.
+    });
+
+  let settle!: () => void;
+  const done = new Promise<void>((resolve) => {
+    settle = resolve;
+  });
+
+  subscribe('text_delta', (delta: string) => void write('text_delta', { delta }));
+  subscribe('tool_start', (state) => void write('tool_start', state));
+  subscribe('tool_end', (state) => void write('tool_end', state));
+  subscribe('thinking', (isThinking: boolean) => void write('thinking', { isThinking }));
+  if (prompts !== undefined) subscribePrompts(subscribe, write, prompts);
+
+  // Flush the terminal event before resolving, so the resolve → cleanup → stream-close
+  // continuation cannot race ahead of the write.
+  subscribe('complete', async (result) => {
+    await write('complete', result);
+    settle();
+  });
+  subscribe('interrupted', async (result) => {
+    await write('interrupted', result);
+    settle();
+  });
+  subscribe('error', async (error: Error) => {
+    await write('error', { message: error.message });
+    settle();
+  });
+
+  // RUNTIME-14: on client disconnect, CANCEL the underlying run (not merely stop writing) and
+  // unblock `done` so the finally teardown runs — otherwise `done` would never resolve and the
+  // listeners leak.
+  stream.onAbort(() => onClientAbort(session, onFailure, settle));
+
+  return done;
+}
+
+/**
+ * Forward the turn's permission and ask prompts, and their settlement, to a client that said it can
+ * answer them.
+ *
+ * Only such a client subscribes: the session parks a prompt only while someone listens for it, so a
+ * client that cannot answer must not listen, or the turn would wait on a prompt nobody settles
+ * instead of failing it closed at once.
+ */
+function subscribePrompts(
+  subscribe: <T>(event: string, handler: (data: T) => void) => void,
+  write: (event: string, data: unknown) => Promise<void>,
+  prompts: IRelayPrompts,
+): void {
+  subscribe('permission_request', (event: IPermissionRequestEvent) => {
+    prompts.record({ type: 'permission_request', event });
+    void write('permission_request', event);
+  });
+  subscribe('ask_request', (event: IAskRequestEvent) => {
+    prompts.record({ type: 'ask_request', event });
+    void write('ask_request', event);
+  });
+  subscribe('prompt_resolved', (event: IPromptResolvedEvent) => {
+    prompts.forget(event.id);
+    void write('prompt_resolved', event);
+  });
+}
+
+/**
+ * The abort path, alone, because every clause of it is load-bearing and review shaped each one.
+ *
+ * `settle` in a `finally`: an `abort()` that throws used to cost a listener leak, and with the
+ * claim registry it costs the SESSION — `done` never resolves, the teardown never runs, the claim
+ * is held forever, and every future /submit is 409.
+ *
+ * The throw is REPORTED, not rethrown: this handler runs inside Hono's abort dispatch, OUTSIDE the
+ * relay's try/catch, so a rethrow is an unhandled rejection rather than a reported failure. The
+ * detail goes where every other stream failure's detail goes.
+ */
+function onClientAbort(
+  session: IHttpTransportSession,
+  onFailure: TStreamFailureListener | undefined,
+  settle: () => void,
+): void {
+  try {
+    session.abort();
+  } catch (error) {
+    // allow-fallback: an abort that throws is the HOST's news, not the runner's
+    try {
+      onFailure?.(error instanceof Error ? error : new Error(String(error)));
+    } catch {
+      // allow-fallback: a listener that throws must not replace the abort path's settle
+      // Same rule as reportStreamFailure: the host's listener failing is the host's to see.
+    }
+  } finally {
+    settle();
+  }
+}
+
+/**
+ * Teardown that cannot take the claim with it.
+ *
+ * Each entry individually, and review is why: these are `session.off` calls, and one that throws
+ * inside a bare loop would end the caller's `finally` before `release()` ran — the same
+ * claim-held-forever the abort path closes, reintroduced two lines down. A failed unsubscribe
+ * forfeits one listener; taking the release with it forfeits the session.
+ */
+function teardown(cleanup: Array<() => void>, release: () => void): void {
+  for (const fn of cleanup) {
+    try {
+      fn();
+    } catch {
+      // allow-fallback: a failed unsubscribe must not take the claim release with it
+      // The listener stays attached — the lesser loss, and the one the next turn can survive.
+    }
+  }
+  // RUNTIME-38: released here for the same reason — a turn that throws must not wedge the session
+  // it claimed.
+  release();
+}
+
+/**
+ * The `streamSSE` callback for one submitted prompt.
+ *
+ * `release` is called in the teardown, ALWAYS — on completion, on error, and on client disconnect.
+ * It is passed in rather than taken here because the claim is made before the stream opens: a claim
+ * whose release lives only inside the stream is a lock that outlives the request that took it.
+ * (This block sat on `wireRelay` for one round after the split stranded it — the stale-doc shape
+ * this file keeps writing about, caught doing it.)
+ */
+export function relayTurn(
+  session: IHttpTransportSession,
+  prompt: string,
+  release: () => void,
+  onFailure?: TStreamFailureListener,
+  attribution?: TTurnAttribution,
+  prompts?: IRelayPrompts,
+): (stream: SSEStreamingApi) => Promise<void> {
+  return async (stream) => {
+    // NOTHING may escape this callback, and the reason is measured rather than stylistic. Hono's
+    // `streamSSE` runner calls its `onError` argument and then UNCONDITIONALLY writes
+    // `event: error, data: e.message` to the stream — so an escaped exception reaches the client
+    // verbatim no matter what the handler withheld. The probe that found it saw TWO error events:
+    // this module's generic line, then Hono's raw one. The only place the trust boundary can be
+    // held is here, before the throw reaches the runner at all.
+    try {
+      // The inner `try` opens BEFORE the wiring: a throw from `session.on` inside `wireRelay`
+      // leaves the session claimed, and the `finally` is what releases it — opened later, every
+      // later request gets 409 forever.
+      const cleanup: Array<() => void> = [];
+      try {
+        const done = wireRelay(session, stream, cleanup, onFailure, prompts);
+        await (attribution === undefined
+          ? session.submit(prompt)
+          : session.submit(prompt, undefined, undefined, { ...attribution }));
+        await done;
+      } finally {
+        // RUNTIME-14: teardown ALWAYS runs — on completion, error, OR client disconnect — so the
+        // session event listeners can never leak, and the claim always comes back.
+        teardown(cleanup, release);
+      }
+    } catch (error) {
+      await reportStreamFailure(
+        error instanceof Error ? error : new Error(String(error)),
+        stream,
+        onFailure,
+      );
+    }
+  };
+}
+
+/**
+ * What to tell a client whose stream failed AFTER the response headers were sent.
+ *
+ * A throw at that point cannot become an error status — the client already has a 200 and an open
+ * stream. Without this the throw is an UNHANDLED rejection: it left the process silently in a
+ * browser and turned the `quality` job red under vitest, which is how it was found.
+ *
+ * By the time this runs, `relayTurn`'s teardown has removed the listeners and released the claim.
+ * This handler owes only the telling.
+ *
+ * The CLIENT gets a generic line and the HOST gets the detail, and review moved this three times.
+ * The first version sent `error.message` verbatim; the second sent it to a package logger imported
+ * from `agent-core`, which the layering rule refuses (see `TStreamFailureListener`). What survives
+ * both rounds is the boundary itself: an exception escaping the stream callback is not a message
+ * anything composed for a client — it can carry provider internals, paths, or stack fragments,
+ * exactly what the 500 branch in `routes.ts` withholds at the same boundary.
+ *
+ * The session's own `error` EVENT is different and stays verbatim in `relayTurn` above: that is the
+ * session's client-facing error channel, worded by the session (`humanizeApiError`) and relayed
+ * identically by the WS transport. One is a message meant for the client; this one never was.
+ */
+export async function reportStreamFailure(
+  error: Error,
+  stream: SSEStreamingApi,
+  onFailure?: TStreamFailureListener,
+): Promise<void> {
+  try {
+    onFailure?.(error);
+  } catch {
+    // allow-fallback: a listener that throws must not take the client's only notification with it
+    // The listener is the host's code; its failure is the host's to see, and the write below is the
+    // one thing this function owes the client either way.
+  }
+  await stream
+    .writeSSE({
+      event: 'error',
+      data: JSON.stringify({
+        message: 'the stream failed on the server after it opened — the turn may not have run',
+      }),
+    })
+    .catch(() => {
+      // allow-fallback: the stream is already gone, which is the one case where there is nobody
+      // left to tell. Rethrowing here would restore the unhandled rejection this exists to remove.
+    });
+}