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

package/src/__tests__/prompt-routes.test.ts

@@ -0,0 +1,299 @@
+/**
+ * Permission and ask prompts over the HTTP routes: forwarded on a prompt-receiving `/submit` stream,
+ * listed by `GET /prompts` for a client that came later, and answered by `POST /prompts/:id`.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { createAgentRoutes } from '../routes.js';
+
+import type {
+  IInteractiveSession,
+  ITurnHandle,
+  TPermissionResultValue,
+} from '@robota-sdk/agent-interface-session';
+
+type TActionResponse = Parameters<IInteractiveSession['resolveAsk']>[1];
+
+const DRIVER = 'remote:http';
+
+function stubHandle(): ITurnHandle {
+  return {
+    turnId: 'turn-1',
+    completed: Promise.resolve({
+      response: '',
+      history: [],
+      toolSummaries: [],
+      contextState: { usedTokens: 0, maxTokens: 0, usedPercentage: 0, remainingPercentage: 100 },
+    }),
+  };
+}
+
+/**
+ * A session whose turn asks once, the way the real prompt registry does: it parks the prompt only
+ * while someone listens for it and fails closed otherwise, settles the first answer for an id, and
+ * emits `prompt_resolved` synchronously as it settles.
+ */
+function createAskingSession(
+  kind: 'permission' | 'ask',
+  options: { ignoreAnswers?: boolean; throwAfterAsk?: boolean } = {},
+) {
+  const listeners = new Map<string, Set<(data: unknown) => void>>();
+  const emit = (event: string, data: unknown): void => {
+    for (const h of [...(listeners.get(event) ?? [])]) h(data);
+  };
+  const parked = new Map<string, (value: TPermissionResultValue | TActionResponse) => void>();
+  const settle = (id: string, value: TPermissionResultValue | TActionResponse): void => {
+    const resolve = parked.get(id);
+    if (resolve === undefined) return;
+    parked.delete(id);
+    resolve(value);
+    emit('prompt_resolved', { id });
+  };
+  const gate = kind === 'permission' ? 'permission_request' : 'ask_request';
+  const ask = (): Promise<TPermissionResultValue | TActionResponse> => {
+    if ((listeners.get(gate)?.size ?? 0) === 0) {
+      return Promise.resolve(kind === 'permission' ? false : { type: 'cancelled' });
+    }
+    const id = kind === 'permission' ? 'p1' : 'a1';
+    return new Promise((resolve) => {
+      parked.set(id, resolve);
+      emit(
+        gate,
+        kind === 'permission'
+          ? { id, toolName: 'Bash', toolArgs: { command: 'ls' } }
+          : { id, request: { id: 'q', title: 'Pick one', options: [{ value: 'x', label: 'X' }] } },
+      );
+    });
+  };
+  const resolvePermission = vi.fn((id: string, result: TPermissionResultValue) => {
+    if (options.ignoreAnswers !== true) settle(id, result);
+  });
+  const resolveAsk = vi.fn((id: string, response: TActionResponse) => {
+    if (options.ignoreAnswers !== true) settle(id, response);
+  });
+  const failAllClosed = (): void => {
+    for (const id of [...parked.keys()]) {
+      settle(id, kind === 'permission' ? false : { type: 'cancelled' });
+    }
+  };
+  const session = createTestInteractiveSession({
+    // Like the real session: an aborted turn settles every prompt it left parked.
+    abort: failAllClosed,
+    submit: (async () => {
+      if (options.throwAfterAsk === true) {
+        void ask();
+        await new Promise((r) => setTimeout(r, 5));
+        throw new Error('the turn failed while its prompt was open');
+      }
+      const answer = await ask();
+      emit('complete', { success: true, content: JSON.stringify(answer) });
+      return stubHandle();
+    }) as IInteractiveSession['submit'],
+    resolvePermission: resolvePermission as IInteractiveSession['resolvePermission'],
+    resolveAsk: resolveAsk as IInteractiveSession['resolveAsk'],
+    on: ((event: string, handler: (data: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)?.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: (data: unknown) => void) => {
+      listeners.get(event)?.delete(handler);
+      // Like the real session: the last prompt listener leaving settles what it left parked.
+      if ((listeners.get(gate)?.size ?? 0) === 0) failAllClosed();
+    }) as IInteractiveSession['off'],
+  });
+  return {
+    session,
+    resolvePermission,
+    resolveAsk,
+    listenerCount: (e: string) => listeners.get(e)?.size ?? 0,
+  };
+}
+
+function routesFor(session: IInteractiveSession) {
+  return createAgentRoutes({
+    sessionFactory: () => ({ ...session }),
+    admission: { open: true, openReason: 'unit test' },
+    attribution: { driverId: DRIVER, surface: 'remote' },
+  });
+}
+
+const json = (body: unknown): RequestInit => ({
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(body),
+});
+
+/** Read an SSE response until `until` appears in it; returns everything read so far. */
+async function readUntil(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  seen: { text: string },
+  until: string,
+): Promise<string> {
+  const decoder = new TextDecoder();
+  while (!seen.text.includes(until)) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    seen.text += decoder.decode(value, { stream: true });
+  }
+  return seen.text;
+}
+
+async function openTurn(routes: ReturnType<typeof routesFor>, receivePrompts?: boolean) {
+  const res = await routes.request(
+    '/submit',
+    json({ prompt: 'go', ...(receivePrompts === undefined ? {} : { receivePrompts }) }),
+  );
+  expect(res.status).toBe(200);
+  const reader = res.body!.getReader();
+  return { reader, seen: { text: '' } };
+}
+
+describe('HTTP prompt routes', () => {
+  it('forwards a live permission prompt, lists it for a late client, and settles it on approve', async () => {
+    const { session, resolvePermission } = createAskingSession('permission');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+
+    expect(await readUntil(reader, seen, 'event: permission_request')).toContain(
+      '"toolName":"Bash"',
+    );
+
+    const late = await routes.request('/prompts');
+    expect(await late.json()).toEqual({
+      prompts: [
+        {
+          type: 'permission_request',
+          event: { id: 'p1', toolName: 'Bash', toolArgs: { command: 'ls' } },
+        },
+      ],
+    });
+
+    const answer = await routes.request('/prompts/p1', json({ result: true }));
+    expect(answer.status).toBe(200);
+    expect(resolvePermission).toHaveBeenCalledWith('p1', true, DRIVER);
+
+    const rest = await readUntil(reader, seen, 'event: complete');
+    expect(rest).toContain('event: prompt_resolved');
+    expect(rest).toContain('"content":"true"');
+    expect(await (await routes.request('/prompts')).json()).toEqual({ prompts: [] });
+  });
+
+  it('settles the turn denied when the client answers false', async () => {
+    const { session } = createAskingSession('permission');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+    await readUntil(reader, seen, 'event: permission_request');
+
+    expect((await routes.request('/prompts/p1', json({ result: false }))).status).toBe(200);
+    expect(await readUntil(reader, seen, 'event: complete')).toContain('"content":"false"');
+  });
+
+  it('answers an ask prompt', async () => {
+    const { session, resolveAsk } = createAskingSession('ask');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+    await readUntil(reader, seen, 'event: ask_request');
+
+    const response = { type: 'answer', values: ['x'] };
+    expect((await routes.request('/prompts/a1', json({ response }))).status).toBe(200);
+    expect(resolveAsk).toHaveBeenCalledWith('a1', response, DRIVER);
+    await readUntil(reader, seen, 'event: complete');
+  });
+
+  it('refuses an unknown id and an already-settled id with 404', async () => {
+    const { session, resolvePermission } = createAskingSession('permission');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+    await readUntil(reader, seen, 'event: permission_request');
+
+    expect((await routes.request('/prompts/nope', json({ result: true }))).status).toBe(404);
+    expect((await routes.request('/prompts/p1', json({ result: true }))).status).toBe(200);
+    const again = await routes.request('/prompts/p1', json({ result: false }));
+    expect(again.status).toBe(404);
+    expect(resolvePermission).toHaveBeenCalledTimes(1);
+    await readUntil(reader, seen, 'event: complete');
+  });
+
+  it('refuses a malformed answer and an answer of the wrong kind with 400', async () => {
+    const { session, resolvePermission } = createAskingSession('permission');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+    await readUntil(reader, seen, 'event: permission_request');
+
+    expect((await routes.request('/prompts/p1', json({ result: 'yes' }))).status).toBe(400);
+    expect(
+      (await routes.request('/prompts/p1', json({ response: { type: 'cancelled' } }))).status,
+    ).toBe(400);
+    expect(
+      (
+        await routes.request('/prompts/p1', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: 'not json',
+        })
+      ).status,
+    ).toBe(400);
+    expect(resolvePermission).not.toHaveBeenCalled();
+
+    await routes.request('/prompts/p1', json({ result: true }));
+    await readUntil(reader, seen, 'event: complete');
+  });
+
+  it('leaves prompts unsubscribed without receivePrompts, so the turn fails closed as before', async () => {
+    const { session, listenerCount } = createAskingSession('permission');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes);
+
+    const all = await readUntil(reader, seen, 'event: complete');
+    expect(all).not.toContain('permission_request');
+    expect(all).toContain('"content":"false"');
+    expect(listenerCount('permission_request')).toBe(0);
+    expect(await (await routes.request('/prompts')).json()).toEqual({ prompts: [] });
+  });
+
+  it('refuses a receivePrompts that is not a boolean', async () => {
+    const { session } = createAskingSession('permission');
+    const res = await routesFor(session).request(
+      '/submit',
+      json({ prompt: 'go', receivePrompts: 'yes' }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  it('forgets the session prompts when the prompt-receiving stream ends', async () => {
+    const { session } = createAskingSession('permission');
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+    await readUntil(reader, seen, 'event: permission_request');
+
+    await reader.cancel();
+    await vi.waitFor(async () => {
+      expect(await (await routes.request('/prompts')).json()).toEqual({ prompts: [] });
+    });
+    expect((await routes.request('/prompts/p1', json({ result: true }))).status).toBe(404);
+  });
+
+  it('answers 409 when the session did not take the answer', async () => {
+    const { session } = createAskingSession('permission', { ignoreAnswers: true });
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+    await readUntil(reader, seen, 'event: permission_request');
+
+    expect((await routes.request('/prompts/p1', json({ result: true }))).status).toBe(409);
+    await reader.cancel();
+  });
+
+  it('stops listing a prompt another surface still holds once this stream ended', async () => {
+    const { session } = createAskingSession('permission', { throwAfterAsk: true });
+    // Another surface listening keeps the prompt parked after this stream lets go of it.
+    session.on('permission_request', () => {});
+    const routes = routesFor(session);
+    const { reader, seen } = await openTurn(routes, true);
+
+    await readUntil(reader, seen, 'event: error');
+    expect(await (await routes.request('/prompts')).json()).toEqual({ prompts: [] });
+    expect((await routes.request('/prompts/p1', json({ result: true }))).status).toBe(404);
+  });
+});

package/src/__tests__/routes.test.ts

@@ -137,6 +137,8 @@ describe('HTTP Transport Routes', () => {
       isExecuting,
       getPendingPrompt,
       getPendingCount,
+      resolvePermission,
+      resolveAsk,
     } = full;
     const port: IHttpTransportSession = {
       submit,
@@ -156,10 +158,13 @@ describe('HTTP Transport Routes', () => {
       isExecuting,
       getPendingPrompt,
       getPendingCount,
+      resolvePermission,
+      resolveAsk,
     };
     // #3282 §2 added `listModels` to `ISessionCommands` (15 + 1); #3288 §2 added
-    // `getMessagesDisplay` to `ISessionConversationRead` (16 + 1).
-    expect(Object.keys(port)).toHaveLength(17);
+    // `getMessagesDisplay` to `ISessionConversationRead` (16 + 1); #3449 added the two prompt
+    // answers of `ISessionPromptResolution` (17 + 2).
+    expect(Object.keys(port)).toHaveLength(19);
     const transport = createHttpTransport({
       admission: { open: true, openReason: 'least-authority HTTP port scenario' },
     });
@@ -366,6 +371,31 @@ describe('HTTP Transport Routes', () => {
     return res.text();
   }
 
+  it('POST /submit attributes the turn to the host-assigned driver and surface, never the client', async () => {
+    const session = createEmitterSession('complete', { ok: true });
+    const app = createAgentRoutes({
+      sessionFactory: () => session,
+      admission: { open: true, openReason: 'this case is about attribution, not admission' },
+      attribution: { driverId: 'remote:http', surface: 'remote' },
+    });
+    const res = await app.request('/submit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prompt: 'hi', driverId: 'owner', surface: 'cli' }),
+    });
+    await res.text();
+    expect(session.submit).toHaveBeenCalledWith('hi', undefined, undefined, {
+      driverId: 'remote:http',
+      surface: 'remote',
+    });
+  });
+
+  it('POST /submit leaves attribution to the session when the host assigns none', async () => {
+    const session = createEmitterSession('complete', { ok: true });
+    await requestSubmit(session);
+    expect(session.submit).toHaveBeenCalledWith('hi');
+  });
+
   it('POST /submit receives the complete event without a trailing thinking(false)', async () => {
     const session = createEmitterSession('complete', { ok: true });
     const body = await requestSubmit(session);

package/src/http-session.ts

@@ -4,6 +4,7 @@ import type {
   ISessionEvents,
   ISessionExecutionState,
   ISessionIdentity,
+  ISessionPromptResolution,
   ISessionTurnControl,
   ISessionTurnSubmission,
 } from '@robota-sdk/agent-interface-session';
@@ -15,6 +16,7 @@ export interface IHttpTransportSession
     ISessionEvents,
     ISessionTurnControl,
     ISessionIdentity,
+    ISessionPromptResolution,
     ISessionCommands,
     ISessionConversationRead,
     ISessionExecutionState {

package/src/http-transport.ts

@@ -11,7 +11,7 @@ import { Hono } from 'hono';
 import { createAgentRoutes } from './routes.js';
 
 import type { IHttpTransportSession } from './http-session.js';
-import type { TStreamFailureListener } from './submit-stream.js';
+import type { TStreamFailureListener, TTurnAttribution } from './submit-stream.js';
 import type {
   ITransportAdapter,
   ITransportAdmissionConfig,
@@ -36,6 +36,8 @@ export interface IHttpTransportOptions {
    * 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> {
@@ -71,6 +73,7 @@ export function createHttpTransport(options?: IHttpTransportOptions): IHttpTrans
         // 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.

package/src/index.ts

@@ -1,6 +1,6 @@
 export { createAgentRoutes } from './routes.js';
 export type { IAgentRoutesOptions, TSessionFactory } from './routes.js';
-export type { TStreamFailureListener } from './submit-stream.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 });
+  };
+}

package/src/routes.ts

@@ -13,11 +13,13 @@ import {
 } 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 } from './submit-stream.js';
+import type { TStreamFailureListener, TTurnAttribution } from './submit-stream.js';
 import type {
   ITransportAdmission,
   ITransportAdmissionConfig,
@@ -44,6 +46,12 @@ export interface IAgentRoutesOptions {
    * 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;
 }
 
 /**
@@ -57,12 +65,13 @@ export interface IAgentRoutesOptions {
  * ```
  */
 export function createAgentRoutes(options: IAgentRoutesOptions): Hono {
-  const { sessionFactory, onStreamFailure } = options;
+  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
@@ -98,7 +107,19 @@ export function createAgentRoutes(options: IAgentRoutesOptions): Hono {
   });
 
   // POST /submit — execute prompt, stream events via SSE
-  app.post('/submit', submitHandler(sessionFactory, claims, onStreamFailure));
+  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) => {