@robota-sdk/agent-transport-http 3.0.0-beta.78 → 3.0.0-beta.81

package/src/submit-route.ts

@@ -0,0 +1,162 @@
+/**
+ * `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 { TStreamFailureListener } 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 function submitHandler(
+  sessionFactory: TSessionFactory,
+  claims: ITurnClaims,
+  onStreamFailure?: TStreamFailureListener,
+) {
+  return async (c: Context) => {
+    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);
+    }
+
+    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;
+        claims.release(claim);
+      }
+    };
+
+    // 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));
+    } catch (error) {
+      releaseOnce();
+      throw error;
+    }
+  };
+}

package/src/submit-stream.ts

@@ -0,0 +1,233 @@
+/**
+ * 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 { SSEStreamingApi } from 'hono/streaming';
+
+/**
+ * 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;
+
+/**
+ * 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,
+): 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 }));
+
+  // 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;
+}
+
+/**
+ * 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,
+): (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);
+        await session.submit(prompt);
+        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.
+    });
+}

package/src/turn-claims.ts

@@ -0,0 +1,62 @@
+/**
+ * RUNTIME-38 — who currently holds the one turn a session can run.
+ *
+ * Split out of `routes.ts`, which had grown past its size ceiling: routing is one job and deciding
+ * whether a second turn may start on a session is another, and the second is the only part of that
+ * file with state of its own.
+ *
+ * PER SESSION, not one flag for the router. `sessionFactory` resolves a session per request (the
+ * documented multi-tenant shape), so a single flag made one tenant's turn refuse every other
+ * tenant's — a busy neighbour is not a reason to refuse you, and that is a worse defect than the
+ * race it closed.
+ */
+
+import type { IHttpTransportSession } from './http-session.js';
+
+export interface ITurnClaims {
+  /** The key this session is claimed under, or `undefined` when it will not name itself. */
+  keyFor(session: IHttpTransportSession): string | undefined;
+  isHeld(key: string): boolean;
+  hold(key: string): void;
+  release(key: string): void;
+}
+
+/**
+ * A claim registry keyed by the session's declared ID, not by object identity.
+ *
+ * Keying on the OBJECT makes identity-stability a requirement of every caller that nothing can
+ * check: a `sessionFactory` returning a fresh wrapper per call for the same logical session — a
+ * proxy, an adapter, a spread copy — defeats the guard in silence, and every request looks
+ * unclaimed. `getSession(): { getSessionId(): string }` already names the session, so asking for the
+ * id turns an unenforceable requirement into no requirement at all.
+ *
+ * A claim is released in the caller's `finally`, so this does not grow with the number of sessions
+ * the host has ever served — which is what weak keying would otherwise buy.
+ */
+export function createTurnClaims(): ITurnClaims {
+  const held = new Set<string>();
+
+  return {
+    keyFor(session) {
+      try {
+        // No `?.`: `getSession(): { getSessionId(): string }` is non-nullable, and optional chaining
+        // here would suggest the contract allows an absent session when it does not. A session that
+        // breaks the contract anyway is caught below.
+        const id = session.getSession().getSessionId();
+        return typeof id === 'string' && id !== '' ? id : undefined;
+      } catch {
+        // allow-fallback: an unnameable session must not be guessed at
+        // A session that throws while naming itself has not told us who it is, and guessing would
+        // claim the wrong turn. The CALLER refuses on `undefined`, so nothing is swallowed here.
+        //
+        // `undefined` rather than a placeholder — a shared fallback key would collide every
+        // unnameable session into one claim and refuse them all as each other's neighbours. There is
+        // no `isExecuting()` fallback on the submit path, and an earlier comment said there was.
+        return undefined;
+      }
+    },
+    isHeld: (key) => held.has(key),
+    hold: (key) => void held.add(key),
+    release: (key) => void held.delete(key),
+  };
+}