@robota-sdk/agent-transport-http 3.0.0-beta.87 → 3.0.0-beta.90

package/src/submit-route.ts

@@ -11,7 +11,8 @@ 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 { 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';
 
@@ -101,18 +102,26 @@ function admitTurn(
   return { claim };
 }
 
-export function submitHandler(
-  sessionFactory: TSessionFactory,
-  claims: ITurnClaims,
-  onStreamFailure?: TStreamFailureListener,
-) {
+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 }>();
+    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
@@ -141,9 +150,19 @@ export function submitHandler(
     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,
@@ -165,7 +184,10 @@ export function submitHandler(
       // 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));
+      return await streamSSE(
+        c,
+        relayTurn(session, body.prompt, releaseOnce, onStreamFailure, attribution, prompts),
+      );
     } catch (error) {
       releaseOnce();
       throw error;

package/src/submit-stream.ts

@@ -8,7 +8,14 @@
  */
 
 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.
@@ -25,6 +32,22 @@ import type { SSEStreamingApi } from 'hono/streaming';
  */
 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).
@@ -40,6 +63,7 @@ function wireRelay(
   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);
@@ -63,6 +87,7 @@ function wireRelay(
   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.
@@ -87,6 +112,33 @@ function wireRelay(
   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.
  *
@@ -154,6 +206,8 @@ export function relayTurn(
   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
@@ -168,8 +222,10 @@ export function relayTurn(
       // later request gets 409 forever.
       const cleanup: Array<() => void> = [];
       try {
-        const done = wireRelay(session, stream, cleanup, onFailure);
-        await session.submit(prompt);
+        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