@hachej/boring-ask-user 0.1.13

package/dist/server/index.js

@@ -0,0 +1,1011 @@
+// src/server/askUserServerPlugin.ts
+import { join as join2 } from "path";
+import { defineServerPlugin } from "@hachej/boring-workspace/server";
+
+// src/shared/constants.ts
+var ASK_USER_PLUGIN_ID = "ask-user";
+var ASK_USER_SURFACE_KIND = "questions";
+var ASK_USER_COMMAND_KINDS = {
+  SUBMIT: "questions.submit",
+  CANCEL: "questions.cancel"
+};
+var ASK_USER_UI_STATE_SLOTS = {
+  PENDING: "questions.pending"
+};
+var ASK_USER_SCHEMA_LIMITS = {
+  maxFields: 8,
+  maxOptionsPerField: 50,
+  maxFieldNameLength: 64,
+  maxTitleLength: 200,
+  maxLabelLength: 160,
+  maxHelpTextLength: 500,
+  maxContextLength: 4e3,
+  maxSerializedSchemaBytes: 32e3,
+  maxFreeformAnswerLength: 4e3,
+  minTimeoutMs: 1e3,
+  maxTimeoutMs: 30 * 6e4,
+  defaultTimeoutMs: 10 * 6e4
+};
+var ASK_USER_FIELD_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+var ASK_USER_RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
+  "__proto__",
+  "prototype",
+  "constructor"
+]);
+
+// src/server/askUserRuntime.ts
+import { randomBytes, randomUUID } from "crypto";
+
+// src/shared/error-codes.ts
+var ASK_USER_ERROR_CODES = {
+  PENDING_EXISTS: "ASK_USER_PENDING_EXISTS",
+  QUESTION_NOT_FOUND: "ASK_USER_QUESTION_NOT_FOUND",
+  QUESTION_ABANDONED: "ASK_USER_QUESTION_ABANDONED",
+  QUESTION_NOT_READY: "ASK_USER_QUESTION_NOT_READY",
+  SCHEMA_INVALID: "ASK_USER_SCHEMA_INVALID",
+  ANSWER_INVALID: "ASK_USER_ANSWER_INVALID",
+  SESSION_MISMATCH: "ASK_USER_SESSION_MISMATCH",
+  UI_UNAVAILABLE: "ASK_USER_UI_UNAVAILABLE",
+  ALREADY_ANSWERED: "ASK_USER_ALREADY_ANSWERED",
+  ALREADY_CANCELLED: "ASK_USER_ALREADY_CANCELLED",
+  UNAUTHORIZED: "ASK_USER_UNAUTHORIZED",
+  UI_ACK_TIMEOUT: "ASK_USER_UI_ACK_TIMEOUT",
+  RATE_LIMITED: "ASK_USER_RATE_LIMITED",
+  RUNTIME_UNAVAILABLE: "ASK_USER_RUNTIME_UNAVAILABLE"
+};
+var ASK_USER_ERROR_CODE_VALUES = Object.values(ASK_USER_ERROR_CODES);
+
+// src/shared/schema.ts
+import { z } from "zod";
+var isoStringSchema = z.string().min(1);
+var fieldNameSchema = z.string().regex(ASK_USER_FIELD_NAME_PATTERN, "field name must match ^[A-Za-z][A-Za-z0-9_-]{0,63}$").refine((name) => !ASK_USER_RESERVED_FIELD_NAMES.has(name), "field name is reserved");
+var boundedString = (max) => z.string().max(max);
+var optionalBoundedString = (max) => boundedString(max).optional();
+var askUserOptionSchema = z.object({
+  value: z.string().min(1).max(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  label: boundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  description: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxHelpTextLength)
+}).strict();
+var baseFieldSchema = {
+  name: fieldNameSchema,
+  label: boundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  required: z.boolean().optional(),
+  helpText: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxHelpTextLength)
+};
+function safePattern(pattern) {
+  try {
+    if (/\\[1-9]/.test(pattern)) return false;
+    if (/\(\?([=!<]|<=|<!)/.test(pattern)) return false;
+    new RegExp(pattern);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var textFieldSchema = z.object({
+  type: z.literal("text"),
+  ...baseFieldSchema,
+  placeholder: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  defaultValue: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength),
+  minLength: z.number().int().min(0).max(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength).optional(),
+  maxLength: z.number().int().min(0).max(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength).optional(),
+  pattern: z.string().max(512).refine(safePattern, "pattern must be safe and valid").optional()
+}).strict().superRefine((field, ctx) => {
+  if (field.minLength !== void 0 && field.maxLength !== void 0 && field.minLength > field.maxLength) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["minLength"], message: "minLength must be <= maxLength" });
+  }
+  if (field.defaultValue !== void 0) {
+    if (field.minLength !== void 0 && field.defaultValue.length < field.minLength) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue shorter than minLength" });
+    }
+    if (field.maxLength !== void 0 && field.defaultValue.length > field.maxLength) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue longer than maxLength" });
+    }
+  }
+});
+var textareaFieldSchema = z.object({
+  type: z.literal("textarea"),
+  ...baseFieldSchema,
+  placeholder: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  defaultValue: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength),
+  minLength: z.number().int().min(0).max(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength).optional(),
+  maxLength: z.number().int().min(0).max(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength).optional()
+}).strict().superRefine((field, ctx) => {
+  if (field.minLength !== void 0 && field.maxLength !== void 0 && field.minLength > field.maxLength) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["minLength"], message: "minLength must be <= maxLength" });
+  }
+});
+function optionsRefinement(field, ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < field.options.length; i++) {
+    const value = field.options[i]?.value;
+    if (seen.has(value)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["options", i, "value"], message: "duplicate option value" });
+    }
+    seen.add(value);
+  }
+  if (field.defaultValue !== void 0 && !seen.has(field.defaultValue)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue must reference an option value" });
+  }
+}
+var selectFieldSchema = z.object({
+  type: z.literal("select"),
+  ...baseFieldSchema,
+  options: z.array(askUserOptionSchema).min(2).max(ASK_USER_SCHEMA_LIMITS.maxOptionsPerField),
+  defaultValue: z.string().optional()
+}).strict().superRefine(optionsRefinement);
+var radioFieldSchema = z.object({
+  type: z.literal("radio"),
+  ...baseFieldSchema,
+  options: z.array(askUserOptionSchema).min(2).max(ASK_USER_SCHEMA_LIMITS.maxOptionsPerField),
+  defaultValue: z.string().optional()
+}).strict().superRefine(optionsRefinement);
+var multiselectFieldSchema = z.object({
+  type: z.literal("multiselect"),
+  ...baseFieldSchema,
+  options: z.array(askUserOptionSchema).min(1).max(ASK_USER_SCHEMA_LIMITS.maxOptionsPerField),
+  defaultValue: z.array(z.string()).optional(),
+  minSelections: z.number().int().min(0).optional(),
+  maxSelections: z.number().int().min(0).optional()
+}).strict().superRefine((field, ctx) => {
+  const values = /* @__PURE__ */ new Set();
+  for (let i = 0; i < field.options.length; i++) {
+    const value = field.options[i]?.value;
+    if (values.has(value)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["options", i, "value"], message: "duplicate option value" });
+    }
+    values.add(value);
+  }
+  if (field.defaultValue) {
+    for (const value of field.defaultValue) {
+      if (!values.has(value)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue must reference option values" });
+      }
+    }
+  }
+  if (field.minSelections !== void 0 && field.maxSelections !== void 0 && field.minSelections > field.maxSelections) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["minSelections"], message: "minSelections must be <= maxSelections" });
+  }
+  if (field.maxSelections !== void 0 && field.maxSelections > field.options.length) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["maxSelections"], message: "maxSelections must be <= options.length" });
+  }
+});
+var checkboxFieldSchema = z.object({
+  type: z.literal("checkbox"),
+  name: fieldNameSchema,
+  label: boundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  defaultValue: z.boolean().optional(),
+  helpText: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxHelpTextLength)
+}).strict();
+var numberFieldSchema = z.object({
+  type: z.literal("number"),
+  ...baseFieldSchema,
+  defaultValue: z.number().finite().optional(),
+  placeholder: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength),
+  min: z.number().finite().optional(),
+  max: z.number().finite().optional(),
+  step: z.number().finite().positive().optional(),
+  integer: z.boolean().optional()
+}).strict().superRefine((field, ctx) => {
+  if (field.min !== void 0 && field.max !== void 0 && field.min > field.max) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["min"], message: "min must be <= max" });
+  }
+  if (field.defaultValue !== void 0) {
+    if (field.integer && !Number.isInteger(field.defaultValue)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue must be an integer" });
+    }
+    if (field.min !== void 0 && field.defaultValue < field.min) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue must be >= min" });
+    }
+    if (field.max !== void 0 && field.defaultValue > field.max) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["defaultValue"], message: "defaultValue must be <= max" });
+    }
+  }
+});
+var AskUserFieldSchema = z.union([
+  textFieldSchema,
+  textareaFieldSchema,
+  selectFieldSchema,
+  multiselectFieldSchema,
+  checkboxFieldSchema,
+  radioFieldSchema,
+  numberFieldSchema
+]);
+var AskUserFormSchemaSchema = z.object({
+  wireVersion: z.literal(1),
+  fields: z.array(AskUserFieldSchema).min(1).max(ASK_USER_SCHEMA_LIMITS.maxFields),
+  submitLabel: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxLabelLength)
+}).strict().superRefine((schema, ctx) => {
+  const names = /* @__PURE__ */ new Set();
+  for (let i = 0; i < schema.fields.length; i++) {
+    const name = schema.fields[i]?.name;
+    if (names.has(name)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["fields", i, "name"], message: "duplicate field name" });
+    }
+    names.add(name);
+  }
+  if (serializedSize(schema) > ASK_USER_SCHEMA_LIMITS.maxSerializedSchemaBytes) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "schema exceeds max serialized size" });
+  }
+});
+var AskUserToolInputSchema = z.object({
+  title: boundedString(ASK_USER_SCHEMA_LIMITS.maxTitleLength).min(1),
+  context: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxContextLength),
+  schema: AskUserFormSchemaSchema,
+  timeoutMs: z.number().int().min(ASK_USER_SCHEMA_LIMITS.minTimeoutMs).max(ASK_USER_SCHEMA_LIMITS.maxTimeoutMs).optional()
+}).strict();
+var AskUserRequestSchema = z.object({
+  sessionId: z.string().min(1),
+  title: boundedString(ASK_USER_SCHEMA_LIMITS.maxTitleLength).optional(),
+  context: optionalBoundedString(ASK_USER_SCHEMA_LIMITS.maxContextLength),
+  schema: AskUserFormSchemaSchema.optional(),
+  timeoutMs: z.number().int().min(ASK_USER_SCHEMA_LIMITS.minTimeoutMs).max(ASK_USER_SCHEMA_LIMITS.maxTimeoutMs).optional()
+}).strict();
+var AskUserAnswerValueSchema = z.union([
+  z.string().max(ASK_USER_SCHEMA_LIMITS.maxFreeformAnswerLength),
+  z.array(z.string()).max(ASK_USER_SCHEMA_LIMITS.maxOptionsPerField),
+  z.boolean(),
+  z.number().finite(),
+  z.null()
+]);
+var AskUserAnswerSchema = z.object({
+  questionId: z.string().min(1),
+  sessionId: z.string().min(1),
+  values: z.record(fieldNameSchema, AskUserAnswerValueSchema),
+  submittedAt: isoStringSchema
+}).strict();
+var commandParamsBase = {
+  questionId: z.string().min(1),
+  sessionId: z.string().min(1)
+};
+var QuestionsSubmitCommandSchema = z.object({
+  kind: z.literal(ASK_USER_COMMAND_KINDS.SUBMIT),
+  params: z.object({
+    ...commandParamsBase,
+    answerToken: z.string().min(1),
+    values: z.record(fieldNameSchema, AskUserAnswerValueSchema)
+  }).strict()
+}).strict();
+var QuestionsCancelCommandSchema = z.object({
+  kind: z.literal(ASK_USER_COMMAND_KINDS.CANCEL),
+  params: z.object({ ...commandParamsBase, answerToken: z.string().min(1) }).strict()
+}).strict();
+var QuestionsCommandSchema = z.discriminatedUnion("kind", [
+  QuestionsSubmitCommandSchema,
+  QuestionsCancelCommandSchema
+]);
+function serializedSize(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).length;
+}
+function validateAskUserToolInput(value) {
+  return AskUserToolInputSchema.safeParse(value);
+}
+
+// src/server/askUserRuntime.ts
+var AskUserRuntimeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+var InProcessAskUserCoordinator = class {
+  waiters = /* @__PURE__ */ new Map();
+  registerWaiter(questionId, sessionId, signal) {
+    if (this.waiters.has(questionId)) {
+      throw new AskUserRuntimeError(ASK_USER_ERROR_CODES.PENDING_EXISTS, `waiter already exists for ${questionId}`);
+    }
+    if (signal?.aborted) return Promise.resolve({ status: "cancelled", questionId, sessionId, reason: "aborted" });
+    return new Promise((resolve) => {
+      const onAbort = () => this.resolveCancelled(questionId, "aborted");
+      const waiter = {
+        sessionId,
+        settled: false,
+        resolve,
+        cleanup: () => signal?.removeEventListener("abort", onAbort)
+      };
+      this.waiters.set(questionId, waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+  hasWaiter(questionId) {
+    return this.waiters.has(questionId);
+  }
+  resolveAnswered(questionId, answer) {
+    return this.resolve(questionId, { status: "answered", answer });
+  }
+  resolveCancelled(questionId, reason) {
+    const waiter = this.waiters.get(questionId);
+    const sessionId = waiter?.sessionId ?? "";
+    return this.resolve(questionId, { status: "cancelled", questionId, sessionId, reason });
+  }
+  resolve(questionId, result) {
+    const waiter = this.waiters.get(questionId);
+    if (!waiter || waiter.settled) return false;
+    waiter.settled = true;
+    this.waiters.delete(questionId);
+    waiter.cleanup();
+    waiter.resolve(result);
+    return true;
+  }
+};
+var AskUserRuntime = class {
+  coordinator;
+  store;
+  ownerPrincipalId;
+  now;
+  perSessionPerMinute;
+  perPrincipalPerHour;
+  uiBridge;
+  sessionBuckets = /* @__PURE__ */ new Map();
+  principalBuckets = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.store = options.store;
+    this.coordinator = options.coordinator ?? new InProcessAskUserCoordinator();
+    this.ownerPrincipalId = options.ownerPrincipalId ?? "anonymous";
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.perSessionPerMinute = options.limits?.perSessionPerMinute ?? 6;
+    this.perPrincipalPerHour = options.limits?.perPrincipalPerHour ?? 30;
+    this.uiBridge = options.uiBridge;
+  }
+  async abandonOrphanedPending(sessionIds) {
+    for (const sessionId of sessionIds) {
+      const pending = await this.store.getPending(sessionId);
+      if (pending && !this.coordinator.hasWaiter(pending.questionId)) {
+        await this.abandon(pending.questionId, pending.sessionId);
+      }
+    }
+  }
+  async ask(request, signal) {
+    this.assertAllowed(request.sessionId);
+    const question = this.createQuestion(request);
+    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);
+  }
+  async submitAnswer(questionId, sessionId, values) {
+    const question = await this.store.getByQuestionId(questionId);
+    if (!question || question.sessionId !== sessionId) throw new AskUserRuntimeError(ASK_USER_ERROR_CODES.QUESTION_NOT_FOUND, "question not found");
+    if (!this.coordinator.hasWaiter(questionId)) {
+      await this.abandon(questionId, sessionId);
+      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);
+    return "answered";
+  }
+  async cancelQuestion(questionId, sessionId, reason = "user_cancelled") {
+    const question = await this.store.getByQuestionId(questionId);
+    if (!question || question.sessionId !== sessionId) throw new AskUserRuntimeError(ASK_USER_ERROR_CODES.QUESTION_NOT_FOUND, "question not found");
+    if (!this.coordinator.hasWaiter(questionId)) {
+      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;
+  }
+  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 } } });
+    } 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 };
+    }
+    return result;
+  }
+  async abandon(questionId, sessionId) {
+    await this.store.markAbandoned(questionId);
+    await this.store.appendTranscriptEvent({ type: "abandoned", questionId, sessionId, at: this.isoNow() });
+    this.coordinator.resolveCancelled(questionId, "abandoned");
+  }
+  createQuestion(request) {
+    const at = this.isoNow();
+    return {
+      questionId: randomUUID(),
+      sessionId: request.sessionId,
+      ownerPrincipalId: this.ownerPrincipalId,
+      status: "ready",
+      title: request.title,
+      context: request.context,
+      answerToken: randomBytes(32).toString("base64url"),
+      createdAt: at,
+      updatedAt: at
+    };
+  }
+  assertAllowed(sessionId) {
+    const principalId = this.ownerPrincipalId;
+    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");
+    }
+  }
+  consume(buckets, key, windowMs, limit) {
+    const now = this.now().getTime();
+    const bucket = buckets.get(key);
+    if (!bucket || bucket.resetAt <= now) {
+      buckets.set(key, { count: 1, resetAt: now + windowMs });
+      return true;
+    }
+    if (bucket.count >= limit) return false;
+    bucket.count += 1;
+    return true;
+  }
+  isoNow() {
+    return this.now().toISOString();
+  }
+};
+function requireAskUserRuntime(runtime) {
+  if (!runtime) throw new AskUserRuntimeError(ASK_USER_ERROR_CODES.RUNTIME_UNAVAILABLE, "ask_user runtime unavailable");
+  return runtime;
+}
+
+// src/server/askUserStore.ts
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+var AskUserStoreError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+var EMPTY_STATE = {
+  questions: {},
+  pendingBySession: {},
+  answers: {},
+  transcriptsBySession: {}
+};
+var FileAskUserStore = class {
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  filePath;
+  state = null;
+  writeChain = Promise.resolve();
+  listeners = /* @__PURE__ */ new Set();
+  async getPending(sessionId) {
+    const state = await this.load();
+    const questionId = state.pendingBySession[sessionId];
+    if (!questionId) return null;
+    const question = state.questions[questionId];
+    if (!question || !isPending(question)) return null;
+    return 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");
+      }
+      state.questions[question.questionId] = clone(question);
+      if (isPending(question)) state.pendingBySession[question.sessionId] = question.questionId;
+      this.emit({ sessionId: question.sessionId, questionId: question.questionId, reason: "create" });
+    });
+  }
+  async answer(questionId, answer) {
+    await this.mutate(async (state) => {
+      const question = requireQuestion(state, questionId);
+      if (answer.questionId !== questionId || answer.sessionId !== question.sessionId) {
+        throw new AskUserStoreError(ASK_USER_ERROR_CODES.SESSION_MISMATCH, "answer does not match question/session");
+      }
+      if (question.status === "cancelled") throw new AskUserStoreError(ASK_USER_ERROR_CODES.ALREADY_CANCELLED, "question already cancelled");
+      if (question.status === "answered") throw new AskUserStoreError(ASK_USER_ERROR_CODES.ALREADY_ANSWERED, "question already answered");
+      if (question.status !== "ready") throw new AskUserStoreError(ASK_USER_ERROR_CODES.ANSWER_INVALID, "question is not ready");
+      question.status = "answered";
+      question.updatedAt = nowIso();
+      state.answers[questionId] = clone(answer);
+      delete state.pendingBySession[question.sessionId];
+      this.emit({ sessionId: question.sessionId, questionId, reason: "answer" });
+    });
+  }
+  async cancel(questionId) {
+    await this.mutate(async (state) => {
+      const question = requireQuestion(state, questionId);
+      if (question.status === "answered") throw new AskUserStoreError(ASK_USER_ERROR_CODES.ALREADY_ANSWERED, "question already answered");
+      if (question.status === "cancelled") throw new AskUserStoreError(ASK_USER_ERROR_CODES.ALREADY_CANCELLED, "question already cancelled");
+      if (!isPending(question)) throw new AskUserStoreError(ASK_USER_ERROR_CODES.QUESTION_NOT_FOUND, "question is not pending");
+      question.status = "cancelled";
+      question.updatedAt = nowIso();
+      delete state.pendingBySession[question.sessionId];
+      this.emit({ sessionId: question.sessionId, questionId, reason: "cancel" });
+    });
+  }
+  async markAbandoned(questionId) {
+    await this.mutate(async (state) => {
+      const question = requireQuestion(state, questionId);
+      if (!isPending(question)) return;
+      question.status = "abandoned";
+      question.updatedAt = nowIso();
+      delete state.pendingBySession[question.sessionId];
+      this.emit({ sessionId: question.sessionId, questionId, reason: "abandon" });
+    });
+  }
+  async clearPending(sessionId) {
+    await this.mutate(async (state) => {
+      const questionId = state.pendingBySession[sessionId];
+      if (!questionId) return;
+      delete state.pendingBySession[sessionId];
+      this.emit({ sessionId, questionId, reason: "clear" });
+    });
+  }
+  async appendTranscriptEvent(event) {
+    await this.mutate(async (state) => {
+      const sessionId = transcriptSessionId(event);
+      state.transcriptsBySession[sessionId] = [...state.transcriptsBySession[sessionId] ?? [], clone(event)];
+      this.emit({ sessionId, questionId: transcriptQuestionId(event), reason: "transcript" });
+    });
+  }
+  async listTranscriptEvents(sessionId) {
+    const state = await this.load();
+    return clone(state.transcriptsBySession[sessionId] ?? []);
+  }
+  async getTranscriptEventsForQuestion(questionId) {
+    const state = await this.load();
+    const events = Object.values(state.transcriptsBySession).flat().filter((event) => transcriptQuestionId(event) === questionId);
+    return clone(events);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async mutate(fn) {
+    const run = this.writeChain.then(async () => {
+      const state = await this.load();
+      await fn(state);
+      await this.save(state);
+    });
+    this.writeChain = run.catch(() => void 0);
+    return run;
+  }
+  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);
+    }
+    return this.state;
+  }
+  async save(state) {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    const tmp = join(dirname(this.filePath), `.${randomUUID2()}.tmp`);
+    await writeFile(tmp, JSON.stringify(state, null, 2), "utf8");
+    await rename(tmp, this.filePath);
+  }
+  emit(change) {
+    for (const listener of this.listeners) {
+      try {
+        const result = listener(change);
+        if (isPromiseLike(result)) result.catch(() => void 0);
+      } catch {
+      }
+    }
+  }
+};
+function isPromiseLike(value) {
+  return !!value && typeof value === "object" && "catch" in value && typeof value.catch === "function";
+}
+function isPending(question) {
+  return question?.status === "ready";
+}
+function requireQuestion(state, questionId) {
+  const question = state.questions[questionId];
+  if (!question) throw new AskUserStoreError(ASK_USER_ERROR_CODES.QUESTION_NOT_FOUND, `question ${questionId} not found`);
+  return question;
+}
+function transcriptSessionId(event) {
+  switch (event.type) {
+    case "created":
+      return event.question.sessionId;
+    case "answered":
+      return event.answer.sessionId;
+    default:
+      return event.sessionId;
+  }
+}
+function transcriptQuestionId(event) {
+  switch (event.type) {
+    case "created":
+      return event.question.questionId;
+    case "answered":
+      return event.answer.questionId;
+    default:
+      return event.questionId;
+  }
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+// src/server/askUserStatePublisher.ts
+var AskUserStatePublisher = class {
+  constructor(store, bridge) {
+    this.store = store;
+    this.bridge = bridge;
+  }
+  store;
+  bridge;
+  unsubscribe;
+  start() {
+    if (this.unsubscribe) return this.unsubscribe;
+    this.unsubscribe = this.store.subscribe((change) => {
+      void this.publishSession(change.sessionId);
+    });
+    return () => this.stop();
+  }
+  stop() {
+    this.unsubscribe?.();
+    this.unsubscribe = void 0;
+  }
+  async publishSession(sessionId) {
+    const question = await this.store.getPending(sessionId);
+    const current = await this.bridge.getState() ?? {};
+    const next = {
+      ...current,
+      [ASK_USER_UI_STATE_SLOTS.PENDING]: { question }
+    };
+    await this.bridge.setState(next);
+  }
+};
+
+// src/server/createAskUserTool.ts
+function createAskUserTool(options) {
+  return {
+    name: "ask_user",
+    label: "Ask user",
+    description: "Ask the user a blocking structured question in the Workspace Questions pane. Supports true multi-field forms via schema.fields (text, textarea, select, radio, multiselect, checkbox, number).",
+    promptSnippet: "Use `ask_user` whenever you need a missing user decision before continuing. It opens a blocking form in the Workspace Questions pane; do not simulate the question in chat. Pass `schema: { wireVersion: 1, fields: [...] }` with field types `text`, `textarea`, `select`, `radio`, `multiselect`, `checkbox`, or `number`. Do not use JSON Schema `properties`; put every requested input in `schema.fields`.",
+    parameters: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "Short question title." },
+        context: { type: "string", description: "Optional context shown above the form." },
+        schema: {
+          type: "object",
+          description: "Structured multi-field form schema. Use { wireVersion: 1, fields: [...] }. Supported field types: text, textarea, select, radio, multiselect, checkbox, number.",
+          properties: {
+            wireVersion: { type: "number", enum: [1] },
+            submitLabel: { type: "string" },
+            fields: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  type: { type: "string", enum: ["text", "textarea", "select", "radio", "multiselect", "checkbox", "number"] },
+                  name: { type: "string" },
+                  label: { type: "string" },
+                  required: { type: "boolean" },
+                  helpText: { type: "string" },
+                  placeholder: { type: "string" },
+                  options: { type: "array", items: { type: "object", properties: { value: { type: "string" }, label: { type: "string" }, description: { type: "string" } }, required: ["value", "label"] } }
+                },
+                required: ["type", "name", "label"],
+                additionalProperties: true
+              }
+            }
+          },
+          required: ["wireVersion", "fields"],
+          additionalProperties: true
+        },
+        timeoutMs: { type: "number", description: "Optional timeout in milliseconds." }
+      },
+      required: ["title", "schema"],
+      additionalProperties: false
+    },
+    async execute(_toolCallId, params, signal, sessionId) {
+      const parsed = validateAskUserToolInput(params);
+      if (!parsed.success) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Invalid ask_user input: ${parsed.error.issues[0]?.message ?? parsed.error.message}. Pass schema: { wireVersion: 1, fields: [{ type, name, label, ... }] }.` }]
+        };
+      }
+      const input = parsed.data;
+      try {
+        const result = await options.runtime.ask({ ...input, sessionId: sessionId ?? resolveSessionId(options.sessionId) }, signal);
+        return formatAskUserResult(result);
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `ask_user failed: ${error instanceof Error ? error.message : String(error)}` }],
+          details: error && typeof error === "object" && "code" in error ? { code: error.code } : void 0
+        };
+      }
+    }
+  };
+}
+function resolveSessionId(sessionId) {
+  return typeof sessionId === "function" ? sessionId() : sessionId;
+}
+function formatAskUserResult(result) {
+  if (result.status === "answered") {
+    return {
+      content: [{ type: "text", text: `User answered: ${JSON.stringify(result.answer.values)}` }],
+      details: result
+    };
+  }
+  return {
+    isError: true,
+    content: [{ type: "text", text: `User question cancelled: ${result.reason}` }],
+    details: result
+  };
+}
+
+// src/server/questionsBridge.ts
+import { timingSafeEqual } from "crypto";
+var QuestionsBridgeError = class extends Error {
+  constructor(code, message, statusCode = 400) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+  code;
+  statusCode;
+};
+var QuestionsBridge = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  async handle(command) {
+    const auth = await this.resolveAuth();
+    const question = await this.requireQuestion(command.params.questionId);
+    this.assertSession(question, command.params.sessionId, auth);
+    this.assertToken(question.answerToken, command.params.answerToken);
+    if (command.kind === "questions.cancel") {
+      if (question.status === "answered") throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.ALREADY_ANSWERED, "question already answered", 409);
+      if (question.status === "cancelled") return { ok: true, status: "cancelled" };
+      if (question.status !== "ready") throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.QUESTION_NOT_READY, "question is not ready", 409);
+      await this.options.runtime.cancelQuestion(question.questionId, question.sessionId, "user_cancelled");
+      return { ok: true, status: "cancelled" };
+    }
+    if (question.status === "answered") return { ok: true, status: "answered" };
+    if (question.status === "cancelled") throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.ALREADY_CANCELLED, "question already cancelled", 409);
+    if (question.status !== "ready" || !question.schema) throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.ANSWER_INVALID, "question is not ready", 409);
+    validateAnswerValues(question.schema.fields, command.params.values);
+    try {
+      const status = await this.options.runtime.submitAnswer(question.questionId, question.sessionId, command.params.values);
+      if (status === "abandoned") {
+        const latest = await this.options.store.getByQuestionId(question.questionId);
+        if (latest?.status === "answered") return { ok: true, status: "answered" };
+        throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.QUESTION_NOT_FOUND, "question waiter is no longer available", 409);
+      }
+    } catch (error) {
+      if (isCode(error, ASK_USER_ERROR_CODES.ALREADY_ANSWERED)) return { ok: true, status: "answered" };
+      throw error;
+    }
+    return { ok: true, status: "answered" };
+  }
+  async resolveAuth() {
+    return await this.options.getAuthContext?.() ?? { sessionId: "anonymous", principalId: "anonymous" };
+  }
+  async requireQuestion(questionId) {
+    const question = await this.options.store.getByQuestionId(questionId);
+    if (!question) throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.QUESTION_NOT_FOUND, "question not found", 404);
+    return question;
+  }
+  assertSession(question, browserSessionId, auth) {
+    if (question.sessionId !== browserSessionId || auth.sessionId !== browserSessionId) {
+      throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.SESSION_MISMATCH, "session mismatch", 403);
+    }
+    if (question.ownerPrincipalId !== auth.principalId) {
+      throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.UNAUTHORIZED, "principal mismatch", 403);
+    }
+  }
+  assertToken(expected, actual) {
+    if (!constantTimeEqual(expected, actual)) {
+      throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.UNAUTHORIZED, "invalid answer token", 403);
+    }
+  }
+};
+function constantTimeEqual(expected, actual) {
+  const expectedBytes = new TextEncoder().encode(expected);
+  const actualBytes = new TextEncoder().encode(actual);
+  const length = Math.max(expectedBytes.length, actualBytes.length);
+  const left = new Uint8Array(length);
+  const right = new Uint8Array(length);
+  left.set(expectedBytes);
+  right.set(actualBytes);
+  return timingSafeEqual(left, right) && expectedBytes.length === actualBytes.length;
+}
+function validateAnswerValues(fields, values) {
+  const fieldByName = new Map(fields.map((field) => [field.name, field]));
+  for (const name of Object.keys(values)) {
+    if (!fieldByName.has(name)) throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.ANSWER_INVALID, `unknown answer field ${name}`);
+  }
+  for (const field of fields) {
+    const value = values[field.name];
+    if (value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0) {
+      if ("required" in field && field.required) throw new QuestionsBridgeError(ASK_USER_ERROR_CODES.ANSWER_INVALID, `${field.name} is required`);
+      continue;
+    }
+    switch (field.type) {
+      case "text":
+      case "textarea":
+        if (typeof value !== "string") throw invalid(field.name);
+        if (field.minLength !== void 0 && value.length < field.minLength) throw invalid(field.name);
+        if (field.maxLength !== void 0 && value.length > field.maxLength) throw invalid(field.name);
+        if (field.type === "text" && field.pattern && !new RegExp(field.pattern).test(value)) throw invalid(field.name);
+        break;
+      case "select":
+      case "radio":
+        if (typeof value !== "string" || !field.options.some((option) => option.value === value)) throw invalid(field.name);
+        break;
+      case "multiselect":
+        if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !field.options.some((option) => option.value === item))) throw invalid(field.name);
+        if (field.minSelections !== void 0 && value.length < field.minSelections) throw invalid(field.name);
+        if (field.maxSelections !== void 0 && value.length > field.maxSelections) throw invalid(field.name);
+        break;
+      case "checkbox":
+        if (typeof value !== "boolean") throw invalid(field.name);
+        break;
+      case "number":
+        if (typeof value !== "number" || !Number.isFinite(value)) throw invalid(field.name);
+        if (field.integer && !Number.isInteger(value)) throw invalid(field.name);
+        if (field.min !== void 0 && value < field.min) throw invalid(field.name);
+        if (field.max !== void 0 && value > field.max) throw invalid(field.name);
+        break;
+    }
+  }
+}
+function invalid(name) {
+  return new QuestionsBridgeError(ASK_USER_ERROR_CODES.ANSWER_INVALID, `invalid answer for ${name}`);
+}
+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" });
+    }
+    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/askUserServerPlugin.ts
+function createAskUserServerPlugin(options) {
+  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) => {
+    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({
+    id: ASK_USER_PLUGIN_ID,
+    label: "Questions",
+    systemPrompt: "When you need a blocking decision from the user, call the `ask_user` tool. Do not roleplay or simulate the form in chat; the active form appears in the Workspace Questions pane.",
+    agentTools: [{
+      name: askUserTool.name,
+      description: askUserTool.description,
+      promptSnippet: askUserTool.promptSnippet,
+      parameters: askUserTool.parameters,
+      execute(params, ctx) {
+        return askUserTool.execute(ctx.toolCallId, params, ctx.abortSignal, ctx.sessionId);
+      }
+    }],
+    routes,
+    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/index.ts
+function defaultAskUserServerPlugin(options, ctx) {
+  return createAskUserServerPlugin({
+    ...options ?? {},
+    workspaceRoot: options?.workspaceRoot ?? ctx.workspaceRoot,
+    bridge: options?.bridge ?? ctx.bridge
+  });
+}
+export {
+  ASK_USER_PLUGIN_ID,
+  AskUserRuntime,
+  AskUserRuntimeError,
+  AskUserStatePublisher,
+  AskUserStoreError,
+  FileAskUserStore,
+  InProcessAskUserCoordinator,
+  QuestionsBridge,
+  QuestionsBridgeError,
+  constantTimeEqual,
+  createAskUserServerPlugin,
+  createAskUserTool,
+  defaultAskUserServerPlugin as default,
+  questionsRoutes,
+  requireAskUserRuntime,
+  validateAnswerValues
+};