@hachej/boring-ask-user 0.1.54 → 0.1.56

package/dist/server/index.js

@@ -357,15 +357,27 @@ var AskUserRuntime = class {
     }
   }
   async ask(request, signal) {
-    this.assertAllowed(request.sessionId);
-    const question = this.createQuestion(request);
+    const ownerPrincipalId = request.ownerPrincipalId ?? this.ownerPrincipalId;
+    this.assertAllowed(request.sessionId, ownerPrincipalId);
+    const question = this.createQuestion({ ...request, ownerPrincipalId });
     const parsed = AskUserFormSchemaSchema.safeParse(request.schema);
     if (!parsed.success) throw new AskUserRuntimeError(ASK_USER_ERROR_CODES.SCHEMA_INVALID, parsed.error.message);
     question.schema = parsed.data;
-    await this.store.createPending(question);
-    await this.store.appendTranscriptEvent({ type: "created", question, at: this.isoNow() });
-    await this.store.appendTranscriptEvent({ type: "ready", questionId: question.questionId, sessionId: question.sessionId, schema: parsed.data, at: this.isoNow() });
-    return this.waitForAnswerWithOpen(question, request.timeoutMs, signal);
+    const pendingAnswer = this.coordinator.registerWaiter(question.questionId, question.sessionId);
+    try {
+      await this.store.createPending(question);
+      await this.store.appendTranscriptEvent({ type: "created", question, at: this.isoNow() });
+      await this.store.appendTranscriptEvent({ type: "ready", questionId: question.questionId, sessionId: question.sessionId, schema: parsed.data, at: this.isoNow() });
+      if (signal?.aborted) {
+        await this.cancelQuestion(question.questionId, question.sessionId, "aborted");
+        return await pendingAnswer;
+      }
+      void this.openQuestionSurface(question);
+      return await this.waitForAnswer(question, pendingAnswer, request.timeoutMs, signal);
+    } catch (error) {
+      this.coordinator.resolveCancelled(question.questionId, "abandoned");
+      throw error;
+    }
   }
   async submitAnswer(questionId, sessionId, values) {
     const question = await this.store.getByQuestionId(questionId);
@@ -375,9 +387,14 @@ var AskUserRuntime = class {
       return "abandoned";
     }
     const answer = { questionId, sessionId, values, submittedAt: this.isoNow() };
-    await this.store.answer(questionId, answer);
-    await this.store.appendTranscriptEvent({ type: "answered", answer, at: this.isoNow() });
-    this.coordinator.resolveAnswered(questionId, answer);
+    let answerPersisted = false;
+    try {
+      await this.store.answer(questionId, answer);
+      answerPersisted = true;
+      await this.store.appendTranscriptEvent({ type: "answered", answer, at: this.isoNow() });
+    } finally {
+      if (answerPersisted) this.coordinator.resolveAnswered(questionId, answer);
+    }
     return "answered";
   }
   async cancelQuestion(questionId, sessionId, reason = "user_cancelled") {
@@ -387,41 +404,49 @@ var AskUserRuntime = class {
       await this.abandon(questionId, sessionId);
       return;
     }
-    await this.store.cancel(questionId);
-    await this.store.appendTranscriptEvent({ type: "cancelled", questionId, sessionId, reason, at: this.isoNow() });
-    this.coordinator.resolveCancelled(questionId, reason);
-  }
-  async waitForAnswerWithOpen(question, timeoutMs, signal) {
-    const pendingAnswer = this.waitForAnswer(question, timeoutMs, signal);
-    void this.openQuestionSurface(question);
-    return pendingAnswer;
+    let cancelPersisted = false;
+    try {
+      await this.store.cancel(questionId);
+      cancelPersisted = true;
+      await this.store.appendTranscriptEvent({ type: "cancelled", questionId, sessionId, reason, at: this.isoNow() });
+    } catch (error) {
+      if (!cancelPersisted) await this.resolveCancelledUnlessAnswered(questionId, reason);
+      throw error;
+    } finally {
+      if (cancelPersisted) this.coordinator.resolveCancelled(questionId, reason);
+    }
   }
   async openQuestionSurface(question) {
     if (!this.uiBridge) return;
     try {
-      await this.uiBridge.postCommand({ kind: "openSurface", params: { kind: ASK_USER_SURFACE_KIND, target: question.questionId, meta: { question } } });
+      await this.uiBridge.postCommand({ kind: "openSurface", params: { kind: ASK_USER_SURFACE_KIND, target: question.questionId, meta: { sessionId: question.sessionId, openOnlyWhenSessionOpen: true } } });
     } catch {
     }
   }
-  async waitForAnswer(question, timeoutMs, signal) {
-    const controller = new AbortController();
-    const relayAbort = () => controller.abort();
-    signal?.addEventListener("abort", relayAbort, { once: true });
-    if (signal?.aborted) controller.abort();
-    const timeout = timeoutMs ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
-    const result = await this.coordinator.registerWaiter(question.questionId, question.sessionId, controller.signal);
-    signal?.removeEventListener("abort", relayAbort);
-    if (timeout) clearTimeout(timeout);
-    if (result.status === "cancelled" && result.reason === "aborted") {
-      const reason = signal?.aborted ? "aborted" : "timeout";
-      try {
-        await this.store.cancel(question.questionId);
-        await this.store.appendTranscriptEvent({ type: "cancelled", questionId: question.questionId, sessionId: question.sessionId, reason, at: this.isoNow() });
-      } catch {
-      }
-      return { status: "cancelled", questionId: question.questionId, sessionId: question.sessionId, reason };
+  async waitForAnswer(question, pendingAnswer, timeoutMs, signal) {
+    let settled = false;
+    const cancel = (reason) => {
+      if (settled) return;
+      void this.cancelQuestion(question.questionId, question.sessionId, reason).catch(() => void 0);
+    };
+    const onAbort = () => cancel("aborted");
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) cancel("aborted");
+    const timeout = timeoutMs ? setTimeout(() => cancel("timeout"), timeoutMs) : void 0;
+    try {
+      const result = await pendingAnswer;
+      settled = true;
+      return result;
+    } finally {
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      if (timeout) clearTimeout(timeout);
     }
-    return result;
+  }
+  async resolveCancelledUnlessAnswered(questionId, reason) {
+    const latest = await this.store.getByQuestionId(questionId).catch(() => null);
+    if (latest?.status === "answered") return;
+    this.coordinator.resolveCancelled(questionId, reason);
   }
   async abandon(questionId, sessionId) {
     await this.store.markAbandoned(questionId);
@@ -433,7 +458,7 @@ var AskUserRuntime = class {
     return {
       questionId: randomUUID(),
       sessionId: request.sessionId,
-      ownerPrincipalId: this.ownerPrincipalId,
+      ownerPrincipalId: request.ownerPrincipalId ?? this.ownerPrincipalId,
       status: "ready",
       title: request.title,
       context: request.context,
@@ -442,8 +467,7 @@ var AskUserRuntime = class {
       updatedAt: at
     };
   }
-  assertAllowed(sessionId) {
-    const principalId = this.ownerPrincipalId;
+  assertAllowed(sessionId, principalId) {
     if (!this.consume(this.sessionBuckets, sessionId, 6e4, this.perSessionPerMinute) || !this.consume(this.principalBuckets, principalId, 36e5, this.perPrincipalPerHour)) {
       throw new AskUserRuntimeError(ASK_USER_ERROR_CODES.RATE_LIMITED, "ask_user rate limit exceeded");
     }
@@ -491,6 +515,7 @@ var FileAskUserStore = class {
   }
   filePath;
   state = null;
+  loadInFlight = null;
   writeChain = Promise.resolve();
   listeners = /* @__PURE__ */ new Set();
   async getPending(sessionId) {
@@ -501,15 +526,19 @@ var FileAskUserStore = class {
     if (!question || !isPending(question)) return null;
     return clone(question);
   }
+  async listPending() {
+    const state = await this.load();
+    return Object.values(state.pendingBySession).map((questionId) => state.questions[questionId]).filter(isPending).map((question) => clone(question));
+  }
   async getByQuestionId(questionId) {
     const state = await this.load();
     return state.questions[questionId] ? clone(state.questions[questionId]) : null;
   }
   async createPending(question) {
     await this.mutate(async (state) => {
-      const existing = Object.values(state.pendingBySession).find((questionId) => isPending(state.questions[questionId]));
-      if (existing) {
-        throw new AskUserStoreError(ASK_USER_ERROR_CODES.PENDING_EXISTS, "a pending question already exists");
+      const existing = state.pendingBySession[question.sessionId];
+      if (existing && isPending(state.questions[existing])) {
+        throw new AskUserStoreError(ASK_USER_ERROR_CODES.PENDING_EXISTS, "a pending question already exists for this session");
       }
       state.questions[question.questionId] = clone(question);
       if (isPending(question)) state.pendingBySession[question.sessionId] = question.questionId;
@@ -593,14 +622,21 @@ var FileAskUserStore = class {
   }
   async load() {
     if (this.state) return this.state;
-    try {
-      const raw = await readFile(this.filePath, "utf8");
-      this.state = { ...clone(EMPTY_STATE), ...JSON.parse(raw) };
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-      this.state = clone(EMPTY_STATE);
+    if (!this.loadInFlight) {
+      this.loadInFlight = (async () => {
+        try {
+          const raw = await readFile(this.filePath, "utf8");
+          this.state = { ...clone(EMPTY_STATE), ...JSON.parse(raw) };
+        } catch (error) {
+          if (error.code !== "ENOENT") throw error;
+          this.state = clone(EMPTY_STATE);
+        }
+        return this.state;
+      })().finally(() => {
+        this.loadInFlight = null;
+      });
     }
-    return this.state;
+    return this.loadInFlight;
   }
   async save(state) {
     await mkdir(dirname(this.filePath), { recursive: true });
@@ -665,27 +701,74 @@ var AskUserStatePublisher = class {
   store;
   bridge;
   unsubscribe;
+  publishChain = Promise.resolve();
+  hintsBySession = /* @__PURE__ */ new Map();
   start() {
     if (this.unsubscribe) return this.unsubscribe;
     this.unsubscribe = this.store.subscribe((change) => {
-      void this.publishSession(change.sessionId);
+      void this.enqueuePublishSession(change.sessionId);
     });
+    void this.enqueueInitializeFromStore().catch(() => void 0);
     return () => this.stop();
   }
   stop() {
     this.unsubscribe?.();
     this.unsubscribe = void 0;
+    this.publishChain = Promise.resolve();
+    this.hintsBySession.clear();
   }
   async publishSession(sessionId) {
-    const question = await this.store.getPending(sessionId);
+    const hint = toPendingHint(await this.store.getPending(sessionId));
     const current = await this.bridge.getState() ?? {};
+    if (hint) this.hintsBySession.set(sessionId, hint);
+    else this.hintsBySession.delete(sessionId);
     const next = {
       ...current,
-      [ASK_USER_UI_STATE_SLOTS.PENDING]: { question }
+      [ASK_USER_UI_STATE_SLOTS.PENDING]: this.currentPendingState(hint)
     };
     await this.bridge.setState(next);
   }
+  currentPendingState(preferredHint) {
+    const hintsBySession = Object.fromEntries(this.hintsBySession.entries());
+    return {
+      hint: preferredHint ?? Object.values(hintsBySession)[0] ?? null,
+      hintsBySession
+    };
+  }
+  enqueuePublishSession(sessionId) {
+    return this.enqueuePublish(() => this.publishSession(sessionId));
+  }
+  enqueueInitializeFromStore() {
+    return this.enqueuePublish(() => this.initializeFromStore());
+  }
+  enqueuePublish(run) {
+    const next = this.publishChain.catch(() => void 0).then(run);
+    this.publishChain = next.catch(() => void 0);
+    return next;
+  }
+  async initializeFromStore() {
+    this.hintsBySession.clear();
+    for (const question of await this.store.listPending()) {
+      const hint = toPendingHint(question);
+      if (hint) this.hintsBySession.set(hint.sessionId, hint);
+    }
+    const current = await this.bridge.getState() ?? {};
+    const nextPending = this.currentPendingState();
+    if (JSON.stringify(current[ASK_USER_UI_STATE_SLOTS.PENDING]) === JSON.stringify(nextPending)) return;
+    await this.bridge.setState({
+      ...current,
+      [ASK_USER_UI_STATE_SLOTS.PENDING]: nextPending
+    });
+  }
 };
+function toPendingHint(question) {
+  if (!question) return null;
+  return {
+    questionId: question.questionId,
+    sessionId: question.sessionId,
+    status: question.status
+  };
+}
 
 // src/server/createAskUserTool.ts
 function createAskUserTool(options) {
@@ -759,7 +842,7 @@ function resolveSessionId(sessionId) {
 function formatAskUserResult(result) {
   if (result.status === "answered") {
     return {
-      content: [{ type: "text", text: `User answered: ${JSON.stringify(result.answer.values)}` }],
+      content: [{ type: "text", text: `User answered: ${JSON.stringify(result.answer.values)}. Continue the conversation using this answer.` }],
       details: result
     };
   }
@@ -770,6 +853,29 @@ function formatAskUserResult(result) {
   };
 }
 
+// src/server/askUserBridgeHandlers.ts
+import {
+  WorkspaceBridgeErrorCode,
+  createWorkspaceBridgeError,
+  defineTrustedDomainBridgeHandler
+} from "@hachej/boring-workspace/server";
+
+// src/shared/bridge.ts
+var ASK_USER_BRIDGE_OPS = {
+  request: "ask-user.v1.request",
+  answer: "ask-user.v1.answer",
+  cancel: "ask-user.v1.cancel",
+  pending: "ask-user.v1.pending",
+  transcript: "ask-user.v1.transcript"
+};
+var ASK_USER_BRIDGE_CAPABILITIES = {
+  request: "ask-user:request",
+  answer: "ask-user:answer",
+  cancel: "ask-user:cancel",
+  pending: "ask-user:pending",
+  transcriptRead: "ask-user:transcript.read"
+};
+
 // src/server/questionsBridge.ts
 import { timingSafeEqual } from "crypto";
 var QuestionsBridgeError = class extends Error {
@@ -827,7 +933,7 @@ var QuestionsBridge = class {
     if (question.sessionId !== browserSessionId || auth.sessionId !== browserSessionId) {
       throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.SESSION_MISMATCH, "session mismatch", 403);
     }
-    if (question.ownerPrincipalId !== auth.principalId) {
+    if (question.ownerPrincipalId !== "anonymous" && question.ownerPrincipalId !== auth.principalId) {
       throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.UNAUTHORIZED, "principal mismatch", 403);
     }
   }
@@ -894,58 +1000,268 @@ function isCode(error, code) {
   return !!error && typeof error === "object" && "code" in error && error.code === code;
 }
 
-// src/server/questionsRoutes.ts
-function questionsRoutes(app, opts, done) {
-  app.post("/api/v1/questions/commands", async (request, reply) => {
-    if (!passesOrigin(request, opts.allowedOrigins)) return reply.code(403).send({ error: "forbidden", message: "invalid origin" });
-    if (!await passesCsrf(request, opts)) return reply.code(403).send({ error: "forbidden", message: "invalid csrf token" });
-    const parsed = QuestionsCommandSchema.safeParse(request.body);
-    if (!parsed.success) {
-      return reply.code(400).send({ error: "validation_error", message: parsed.error.issues[0]?.message ?? "invalid command" });
+// src/server/askUserBridgeHandlers.ts
+var MAX_QUESTION_BYTES = 64 * 1024;
+var MAX_TRANSCRIPT_BYTES = 256 * 1024;
+var REQUEST_TIMEOUT_MS = 10 * 6e4;
+var MUTATION_TIMEOUT_MS = 3e4;
+var READ_TIMEOUT_MS = 1e4;
+function createAskUserBridgeHandlers(options) {
+  return [
+    contribution(defineTrustedDomainBridgeHandler({
+      op: ASK_USER_BRIDGE_OPS.request,
+      version: 1,
+      owner: ASK_USER_PLUGIN_ID,
+      callerClassesAllowed: ["runtime", "server"],
+      requiredCapabilities: [ASK_USER_BRIDGE_CAPABILITIES.request],
+      inputSchema: { type: "object" },
+      outputSchema: { type: "object" },
+      timeoutMs: REQUEST_TIMEOUT_MS,
+      maxInputBytes: MAX_QUESTION_BYTES,
+      maxOutputBytes: MAX_QUESTION_BYTES,
+      idempotencyPolicy: "request-id",
+      handler: requestHandler(options)
+    })),
+    contribution(defineTrustedDomainBridgeHandler({
+      op: ASK_USER_BRIDGE_OPS.answer,
+      version: 1,
+      owner: ASK_USER_PLUGIN_ID,
+      callerClassesAllowed: ["browser", "server"],
+      requiredCapabilities: [ASK_USER_BRIDGE_CAPABILITIES.answer],
+      inputSchema: { type: "object" },
+      outputSchema: { type: "object" },
+      timeoutMs: MUTATION_TIMEOUT_MS,
+      maxInputBytes: MAX_QUESTION_BYTES,
+      maxOutputBytes: 1024,
+      idempotencyPolicy: "required",
+      handler: answerHandler(options)
+    })),
+    contribution(defineTrustedDomainBridgeHandler({
+      op: ASK_USER_BRIDGE_OPS.cancel,
+      version: 1,
+      owner: ASK_USER_PLUGIN_ID,
+      callerClassesAllowed: ["browser", "server"],
+      requiredCapabilities: [ASK_USER_BRIDGE_CAPABILITIES.cancel],
+      inputSchema: { type: "object" },
+      outputSchema: { type: "object" },
+      timeoutMs: MUTATION_TIMEOUT_MS,
+      maxInputBytes: MAX_QUESTION_BYTES,
+      maxOutputBytes: 1024,
+      idempotencyPolicy: "required",
+      handler: cancelHandler(options)
+    })),
+    contribution(defineTrustedDomainBridgeHandler({
+      op: ASK_USER_BRIDGE_OPS.pending,
+      version: 1,
+      owner: ASK_USER_PLUGIN_ID,
+      callerClassesAllowed: ["browser", "server"],
+      requiredCapabilities: [ASK_USER_BRIDGE_CAPABILITIES.pending],
+      inputSchema: { type: "object" },
+      outputSchema: { type: "object" },
+      timeoutMs: READ_TIMEOUT_MS,
+      maxInputBytes: 1024,
+      maxOutputBytes: MAX_QUESTION_BYTES,
+      idempotencyPolicy: "none",
+      handler: pendingHandler(options)
+    })),
+    contribution(defineTrustedDomainBridgeHandler({
+      op: ASK_USER_BRIDGE_OPS.transcript,
+      version: 1,
+      owner: ASK_USER_PLUGIN_ID,
+      callerClassesAllowed: ["server"],
+      requiredCapabilities: [ASK_USER_BRIDGE_CAPABILITIES.transcriptRead],
+      inputSchema: { type: "object" },
+      outputSchema: { type: "object" },
+      timeoutMs: READ_TIMEOUT_MS,
+      maxInputBytes: 1024,
+      maxOutputBytes: MAX_TRANSCRIPT_BYTES,
+      idempotencyPolicy: "none",
+      handler: transcriptHandler(options)
+    }))
+  ];
+}
+function contribution(entry) {
+  return {
+    definition: entry.definition,
+    handler: entry.handler
+  };
+}
+function requestHandler({ runtime }) {
+  return async ({ input, context, signal }) => {
+    assertRequestInput(input);
+    assertRequestSessionScope(input.sessionId, context);
+    try {
+      return await runtime.ask({
+        sessionId: input.sessionId,
+        title: input.title,
+        context: input.context,
+        schema: input.schema,
+        timeoutMs: input.timeoutMs,
+        ownerPrincipalId: ownerPrincipalIdFromRuntimeContext(context)
+      }, signal);
+    } catch (error) {
+      throw mapAskUserError(error);
     }
-    const bridge = new QuestionsBridge({
-      store: opts.store,
-      runtime: opts.runtime,
-      getAuthContext: opts.getAuthContext ? () => opts.getAuthContext(request) : void 0
+  };
+}
+function answerHandler(options) {
+  return async ({ input, context }) => {
+    assertAnswerInput(input);
+    assertBrowserSessionScope(input.sessionId, context);
+    return await runQuestionsBridge(options, context, {
+      kind: "questions.submit",
+      params: {
+        questionId: input.questionId,
+        sessionId: input.sessionId,
+        answerToken: input.answerToken,
+        values: input.values
+      }
     });
+  };
+}
+function cancelHandler(options) {
+  return async ({ input, context }) => {
+    assertCancelInput(input);
+    assertBrowserSessionScope(input.sessionId, context);
+    return await runQuestionsBridge(options, context, {
+      kind: "questions.cancel",
+      params: {
+        questionId: input.questionId,
+        sessionId: input.sessionId,
+        answerToken: input.answerToken
+      }
+    });
+  };
+}
+function pendingHandler({ store }) {
+  return async ({ input, context }) => {
+    if (!input || typeof input.sessionId !== "string" || input.sessionId.length === 0) {
+      throw invalid2("ask-user pending requires sessionId");
+    }
+    assertBrowserSessionScope(input.sessionId, context);
     try {
-      return await bridge.handle(parsed.data);
+      const pending = await store.getPending(input.sessionId);
+      assertQuestionOwner(context, pending);
+      return { pending };
     } catch (error) {
-      return sendError(reply, error);
+      throw mapAskUserError(error);
     }
+  };
+}
+function transcriptHandler({ store }) {
+  return async ({ input }) => {
+    if (!input || typeof input.sessionId !== "string" || input.sessionId.length === 0) {
+      throw invalid2("ask-user transcript requires sessionId");
+    }
+    try {
+      return { events: await store.listTranscriptEvents(input.sessionId) };
+    } catch (error) {
+      throw mapAskUserError(error);
+    }
+  };
+}
+async function runQuestionsBridge({ runtime, store }, context, command) {
+  const auth = commandAuthSessionId(command.params.sessionId, context);
+  const bridge = new QuestionsBridge({
+    runtime,
+    store,
+    getAuthContext: () => auth
   });
-  done();
+  try {
+    return await bridge.handle(command);
+  } catch (error) {
+    throw mapAskUserError(error);
+  }
 }
-function passesOrigin(request, allowedOrigins) {
-  if (!allowedOrigins || allowedOrigins.length === 0) return true;
-  const origin = request.headers.origin;
-  return typeof origin === "string" && allowedOrigins.includes(origin);
+function assertRequestInput(input) {
+  if (!input || typeof input !== "object") throw invalid2("ask-user request input is required");
+  if (typeof input.sessionId !== "string" || input.sessionId.length === 0) throw invalid2("ask-user request requires sessionId");
+  if (!input.schema || typeof input.schema !== "object") throw invalid2("ask-user request requires schema");
+  if (input.title !== void 0 && typeof input.title !== "string") throw invalid2("ask-user request title must be a string");
+  if (input.context !== void 0 && typeof input.context !== "string") throw invalid2("ask-user request context must be a string");
+  if (input.timeoutMs !== void 0 && (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)) throw invalid2("ask-user request timeoutMs must be positive");
 }
-async function passesCsrf(request, opts) {
-  if (!opts.csrfToken) return true;
-  const headerName = (opts.csrfHeaderName ?? "x-csrf-token").toLowerCase();
-  const actual = request.headers[headerName];
-  const expected = typeof opts.csrfToken === "function" ? await opts.csrfToken(request) : opts.csrfToken;
-  return typeof actual === "string" && typeof expected === "string" && constantTimeEqual(expected, actual);
+function assertAnswerInput(input) {
+  assertMutationBase(input, "answer");
+  if (!input.values || typeof input.values !== "object" || Array.isArray(input.values)) throw invalid2("ask-user answer requires values");
 }
-function sendError(reply, error) {
+function assertCancelInput(input) {
+  assertMutationBase(input, "cancel");
+}
+function assertMutationBase(input, op) {
+  if (!input || typeof input !== "object") throw invalid2(`ask-user ${op} input is required`);
+  if (typeof input.questionId !== "string" || input.questionId.length === 0) throw invalid2(`ask-user ${op} requires questionId`);
+  if (typeof input.sessionId !== "string" || input.sessionId.length === 0) throw invalid2(`ask-user ${op} requires sessionId`);
+  if (typeof input.answerToken !== "string" || input.answerToken.length === 0) throw invalid2(`ask-user ${op} requires answerToken`);
+}
+function assertBrowserSessionScope(sessionId, context) {
+  if (context.callerClass !== "browser") return;
+  if (context.sessionId && context.sessionId === sessionId) return;
+  throw createWorkspaceBridgeError(
+    WorkspaceBridgeErrorCode.ResourceScopeDenied,
+    "ask-user session does not match browser bridge context"
+  );
+}
+function assertRequestSessionScope(sessionId, context) {
+  if (context.callerClass !== "runtime") return;
+  if (context.sessionId && context.sessionId === sessionId) return;
+  throw createWorkspaceBridgeError(
+    WorkspaceBridgeErrorCode.ResourceScopeDenied,
+    "ask-user request session does not match runtime bridge context"
+  );
+}
+function assertQuestionOwner(context, question) {
+  if (!question || context.callerClass !== "browser") return;
+  if (question.ownerPrincipalId === "anonymous") return;
+  const principalId = context.actor.performedBy?.id;
+  if (!principalId || principalId !== question.ownerPrincipalId) {
+    throw createWorkspaceBridgeError(
+      WorkspaceBridgeErrorCode.ResourceScopeDenied,
+      "ask-user question is not owned by this browser principal"
+    );
+  }
+}
+function commandAuthSessionId(sessionId, context) {
+  if (context.callerClass !== "browser") {
+    return { sessionId, principalId: principalIdFromContext(context) };
+  }
+  assertBrowserSessionScope(sessionId, context);
+  return { sessionId: context.sessionId, principalId: principalIdFromContext(context) };
+}
+function principalIdFromContext(context) {
+  return context.actor.performedBy?.id ?? context.actor.onBehalfOf?.id ?? "anonymous";
+}
+function ownerPrincipalIdFromRuntimeContext(context) {
+  return context.actor.onBehalfOf?.id;
+}
+function mapAskUserError(error) {
   if (error instanceof QuestionsBridgeError) {
-    return reply.code(error.statusCode).send({ error: error.code, message: error.message });
+    const code = error.statusCode === 403 ? WorkspaceBridgeErrorCode.ResourceScopeDenied : WorkspaceBridgeErrorCode.InvalidRequest;
+    throw createWorkspaceBridgeError(code, error.message, { askUserCode: error.code });
+  }
+  if (error instanceof AskUserRuntimeError || error instanceof AskUserStoreError) {
+    const code = error.code === ASK_USER_ERROR_CODES.RATE_LIMITED ? WorkspaceBridgeErrorCode.CapabilityDenied : WorkspaceBridgeErrorCode.InvalidRequest;
+    throw createWorkspaceBridgeError(code, error.message, { askUserCode: error.code });
   }
   throw error;
 }
+function invalid2(message) {
+  throw createWorkspaceBridgeError(WorkspaceBridgeErrorCode.InvalidRequest, message);
+}
 
 // src/server/askUserServerPlugin.ts
 function createAskUserServerPlugin(options) {
+  if (options.routes) {
+    throw new Error("createAskUserServerPlugin no longer registers /api/v1/questions/commands; use WorkspaceBridge ask-user.v1.* handlers or import questionsRoutes for manual legacy wiring");
+  }
   const store = options.store ?? createDefaultStore(options.workspaceRoot);
   const runtime = options.runtime ?? new AskUserRuntime({ store, uiBridge: options.bridge });
   const stopPublisher = options.bridge ? new AskUserStatePublisher(store, options.bridge).start() : void 0;
-  const routes = async (app) => {
+  const lifecycle = async (app) => {
     app.addHook("onClose", async () => {
       stopPublisher?.();
       options.onClose?.();
     });
-    await app.register(questionsRoutes, { ...defaultRoutes, ...options.routes, runtime, store });
   };
   const askUserTool = createAskUserTool({ runtime, sessionId: options.sessionId ?? (() => "default") });
   return defineServerPlugin({
@@ -961,28 +1277,57 @@ function createAskUserServerPlugin(options) {
         return askUserTool.execute(ctx.toolCallId, params, ctx.abortSignal, ctx.sessionId);
       }
     }],
-    routes,
+    workspaceBridgeHandlers: createAskUserBridgeHandlers({ runtime, store }),
+    routes: lifecycle,
     preservedUiStateKeys: [ASK_USER_UI_STATE_SLOTS.PENDING]
   });
 }
-var defaultRoutes = {
-  // No-auth playground/default shells still need the browser command channel to
-  // bind to the question's owning session. The answerToken remains the terminal
-  // mutation secret; this context only prevents the default anonymous session
-  // sentinel from rejecting legitimate no-auth submits as SESSION_MISMATCH.
-  getAuthContext: (request) => {
-    const body = request.body;
-    return {
-      sessionId: typeof body?.params?.sessionId === "string" ? body.params.sessionId : "anonymous",
-      principalId: "anonymous"
-    };
-  }
-};
 function createDefaultStore(workspaceRoot) {
   if (!workspaceRoot) throw new Error("createAskUserServerPlugin requires workspaceRoot when store is not provided");
   return new FileAskUserStore(join2(workspaceRoot, ".boring", "ask-user.json"));
 }
 
+// src/server/questionsRoutes.ts
+function questionsRoutes(app, opts, done) {
+  app.post("/api/v1/questions/commands", async (request, reply) => {
+    if (!passesOrigin(request, opts.allowedOrigins)) return reply.code(403).send({ error: "forbidden", message: "invalid origin" });
+    if (!await passesCsrf(request, opts)) return reply.code(403).send({ error: "forbidden", message: "invalid csrf token" });
+    const parsed = QuestionsCommandSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "validation_error", message: parsed.error.issues[0]?.message ?? "invalid command" });
+    }
+    const bridge = new QuestionsBridge({
+      store: opts.store,
+      runtime: opts.runtime,
+      getAuthContext: opts.getAuthContext ? () => opts.getAuthContext(request) : void 0
+    });
+    try {
+      return await bridge.handle(parsed.data);
+    } catch (error) {
+      return sendError(reply, error);
+    }
+  });
+  done();
+}
+function passesOrigin(request, allowedOrigins) {
+  if (!allowedOrigins || allowedOrigins.length === 0) return true;
+  const origin = request.headers.origin;
+  return typeof origin === "string" && allowedOrigins.includes(origin);
+}
+async function passesCsrf(request, opts) {
+  if (!opts.csrfToken) return true;
+  const headerName = (opts.csrfHeaderName ?? "x-csrf-token").toLowerCase();
+  const actual = request.headers[headerName];
+  const expected = typeof opts.csrfToken === "function" ? await opts.csrfToken(request) : opts.csrfToken;
+  return typeof actual === "string" && typeof expected === "string" && constantTimeEqual(expected, actual);
+}
+function sendError(reply, error) {
+  if (error instanceof QuestionsBridgeError) {
+    return reply.code(error.statusCode).send({ error: error.code, message: error.message });
+  }
+  throw error;
+}
+
 // src/server/index.ts
 function defaultAskUserServerPlugin(options, ctx) {
   return createAskUserServerPlugin({
@@ -1002,6 +1347,7 @@ export {
   QuestionsBridge,
   QuestionsBridgeError,
   constantTimeEqual,
+  createAskUserBridgeHandlers,
   createAskUserServerPlugin,
   createAskUserTool,
   defaultAskUserServerPlugin as default,