@opengeni/react 1.4.4 → 1.4.5-canary.37458084490001

package/src/composer-messages.ts

@@ -0,0 +1,150 @@
+/**
+ * The composer's user-facing copy, renderer-free so web and native composers
+ * (and hosts translating them) share one message catalog.
+ */
+import type { SlashCommand } from "./commands/types";
+import { formatBytes, formatRelativeTime } from "./lib/format";
+
+export type ChatComposerMessages = {
+  messagePlaceholder: string;
+  pausedPlaceholder: string;
+  inputLabel: string;
+  keyboardHint: string;
+  slashCommandBlocked: string;
+  controlChangedError: string;
+  sendFailedError: string;
+  dropFiles: string;
+  attachFiles: string;
+  pauseAriaLabel: string;
+  pauseTitle: string;
+  /** Stop control shown while a response runs (`runControl="stop"`). */
+  stopAriaLabel?: string | undefined;
+  stopTitle?: string | undefined;
+  sendMessageAriaLabel: string;
+  sendAndResumeAriaLabel: string;
+  sendTitle: string;
+  sendAndResumeTitle: string;
+  annotationNotesRequired: string;
+  workspacePaused: string;
+  pausedHere: string;
+  parentBlocker: string;
+  narrowerPause: string;
+  pausedBy: (displayName: string) => string;
+  queuedAhead: (count: number) => string;
+  resumingAndSending: string;
+  nextMessageResumes: string;
+  resumeThisWorkstream: string;
+  resumeShort: string;
+  hidePauseDetails: string;
+  showPauseDetails: string;
+  pauseReasonsLabel: string;
+  pausedByLabel: string;
+  alsoPausedByLabel: string;
+  resumeWorkspace: string;
+  resumeFromSession: string;
+  sessionCanRun: string;
+  stillPausedBy: (displayName: string) => string;
+  restoredResourcesLabel: string;
+  restoredFile: (fileId: string) => string;
+  removeRestoredResource: (index: number) => string;
+  uploading: string;
+  uploadFailed: string;
+  previewAttachment: (name: string) => string;
+  previewUnavailable?: string | undefined;
+  attachmentPreviewLabel: string;
+  downloadAttachment: (name: string) => string;
+  closeAttachmentPreview: string;
+  retryAttachment: (name: string) => string;
+  retryUpload: string;
+  removeAttachment: (name: string) => string;
+  confirmCommand: (name: string) => string;
+  confirmDescription: (command: SlashCommand) => string;
+  cancel: string;
+  runCommand: (name: string) => string;
+  commands: string;
+  slashCommandsLabel: string;
+  modelLabel: string;
+  close: string;
+  danger: string;
+  draftConflict: string;
+  useOtherDraft: string;
+  keepMine: string;
+  savingDraft: string;
+  formatBytes: (bytes: number) => string;
+  formatRelativeTime: (changedAt: string) => string;
+};
+
+export const defaultChatComposerMessages: ChatComposerMessages = {
+  messagePlaceholder: "Message the agent…",
+  pausedPlaceholder: "Message the agent — it will wait in the queue…",
+  inputLabel: "Message the agent",
+  // Shortcuts live in the send button's title; the footer stays quiet unless
+  // the host supplies its own hint.
+  keyboardHint: "",
+  slashCommandBlocked:
+    "That's a slash command — press Enter in the command list to run it, or edit the line to send a message.",
+  controlChangedError:
+    "This workstream was paused while you were sending. Nothing was sent, and your draft is still here.",
+  sendFailedError: "Sending failed — your draft is still here. Try again.",
+  dropFiles: "Drop files to attach",
+  attachFiles: "Attach files",
+  pauseAriaLabel: "Pause this workstream",
+  pauseTitle: "Pause this workstream; queued prompts and approvals are preserved",
+  stopAriaLabel: "Stop",
+  stopTitle: "Stop the response",
+  sendMessageAriaLabel: "Send message",
+  sendAndResumeAriaLabel: "Add message to queue",
+  sendTitle: "Queue message (Enter); steer with Cmd/Ctrl+Enter",
+  sendAndResumeTitle: "Add to queue (Enter); steer now with Cmd/Ctrl+Enter",
+  annotationNotesRequired: "Add a note to each quote before sending.",
+  workspacePaused: "Workspace paused",
+  pausedHere: "Paused here",
+  parentBlocker: "parent",
+  narrowerPause: "a narrower pause",
+  pausedBy: (displayName) => `Paused by ${displayName}`,
+  queuedAhead: (count) =>
+    `${count} waiting prompt${count === 1 ? "" : "s"}; your message joins the queue.`,
+  resumingAndSending: "Sending…",
+  nextMessageResumes: "Messages wait in the queue until you resume.",
+  resumeThisWorkstream: "Resume this workstream",
+  resumeShort: "Resume",
+  hidePauseDetails: "Hide pause details",
+  showPauseDetails: "Show pause details",
+  pauseReasonsLabel: "Reasons this workstream is paused",
+  pausedByLabel: "Paused by ",
+  alsoPausedByLabel: "Also paused by ",
+  resumeWorkspace: "Resume workspace",
+  resumeFromSession: "Resume from this session",
+  sessionCanRun: "This session will be able to run",
+  stillPausedBy: (displayName) => `Still paused by ${displayName}`,
+  restoredResourcesLabel: "Restored prompt resources",
+  restoredFile: (fileId) => `File ${fileId.slice(0, 8)}`,
+  removeRestoredResource: (index) => `Remove restored resource ${index + 1}`,
+  uploading: "Uploading",
+  uploadFailed: "Upload failed",
+  previewAttachment: (name) => `Preview ${name}`,
+  previewUnavailable: "Preview unavailable",
+  attachmentPreviewLabel: "Attachment preview",
+  downloadAttachment: (name) => `Download ${name}`,
+  closeAttachmentPreview: "Close",
+  retryAttachment: (name) => `Retry ${name}`,
+  retryUpload: "Retry upload",
+  removeAttachment: (name) => `Remove ${name}`,
+  confirmCommand: (name) => `Confirm /${name}`,
+  confirmDescription: (command) => `Run /${command.name}? ${command.description}`,
+  cancel: "Cancel",
+  runCommand: (name) => `Run /${name}`,
+  commands: "Commands",
+  slashCommandsLabel: "Slash commands",
+  modelLabel: "Model",
+  close: "Close",
+  danger: "danger",
+  draftConflict: "This draft changed in another tab. Your local draft is still here.",
+  useOtherDraft: "Use other draft",
+  keepMine: "Keep mine",
+  // Kept for embedder message overrides / back-compat. Routine autosave is
+  // silent — only draft conflicts surface under the composer.
+  savingDraft: "Saving draft…",
+  formatBytes,
+  formatRelativeTime,
+};

package/src/connect-setup.tsx

@@ -19,6 +19,11 @@ const setupStatus: Record<ConnectAttempt["state"], string> = {
   uncertain: "Setup outcome needs checking",
 };
 
+/** GitHub returned from a non-owner's install request: an organization owner must approve. */
+export function isOwnerApprovalPending(attempt: Pick<ConnectAttempt, "error">): boolean {
+  return attempt.error?.code === "owner_approval_pending";
+}
+
 function deviceVerificationUrl(action: ConnectAttempt["nextAction"]): string | null {
   if (action.type !== "wait" || !action.verificationUrl) return null;
   try {
@@ -91,6 +96,11 @@ function ScopedSetup({
   const action = attempt.nextAction;
   const verificationUrl = deviceVerificationUrl(action);
   const terminal = ["complete", "cancelled", "expired"].includes(attempt.state);
+  const awaitingOwner = isOwnerApprovalPending(attempt);
+  const offersGitHubRequest =
+    action.type === "select_account" &&
+    attempt.providerId.startsWith("github") &&
+    action.accounts.some((account) => account.id === "new");
   const submit = (event: FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     const form = event.currentTarget;
@@ -148,7 +158,7 @@ function ScopedSetup({
           {attempt.ownership === "personal" ? "Personal connection" : "Workspace connection"}
         </p>
         <p role="status" className="og-connect-setup-status">
-          {setupStatus[attempt.state]}
+          {awaitingOwner ? "Waiting for an organization owner" : setupStatus[attempt.state]}
         </p>
         <p className="og-connect-setup-description">
           {attempt.ownership === "personal"
@@ -157,7 +167,22 @@ function ScopedSetup({
         </p>
       </div>
       {attempt.account && <p>Account: {attempt.account.label}</p>}
-      {(localError || view.error || attempt.error) && (
+      {awaitingOwner && (
+        <div className="og-connect-setup-pending">
+          <p>
+            Your request was sent. GitHub asked the owners of your organization to approve Opengeni.
+          </p>
+          <ol>
+            <li>An organization owner approves the request on GitHub.</li>
+            <li>
+              An owner then connects the organization here. If they don't use Opengeni yet, invite
+              them to this workspace first.
+            </li>
+          </ol>
+          <p>Nothing is connected until then. You can close this and keep working.</p>
+        </div>
+      )}
+      {(localError || view.error || (attempt.error && !awaitingOwner)) && (
         <p role="alert">
           {attempt.error?.code === "source_changed"
             ? "The integration source changed. Review the updated tools before adding them."
@@ -172,15 +197,17 @@ function ScopedSetup({
             ) ? (
               <legend>Connection details</legend>
             ) : null}
-            {attempt.state === "connected_but_incomplete" && action.type === "none" && (
-              <button
-                type="button"
-                className="og-connect-setup-primary"
-                onClick={() => invoke(() => view.advance({ type: "retry" }, crypto.randomUUID()))}
-              >
-                Choose tools
-              </button>
-            )}
+            {attempt.state === "connected_but_incomplete" &&
+              action.type === "none" &&
+              !awaitingOwner && (
+                <button
+                  type="button"
+                  className="og-connect-setup-primary"
+                  onClick={() => invoke(() => view.advance({ type: "retry" }, crypto.randomUUID()))}
+                >
+                  Choose tools
+                </button>
+              )}
             {action.type === "credentials" &&
               action.fields.map((field, i) => (
                 <label key={field.name}>
@@ -225,6 +252,13 @@ function ScopedSetup({
                 </select>
               </label>
             )}
+            {offersGitHubRequest && (
+              <p className="og-connect-setup-hint">
+                Don't see your organization? Only its owners can connect it. Choose "Install on
+                another GitHub account" and pick the organization: GitHub lets you send its owners a
+                request to approve.
+              </p>
+            )}
             {action.type === "select_resources" &&
               action.resources.map((resource) => (
                 <label key={resource.id}>

package/src/connect.ts

@@ -15,7 +15,7 @@ export {
   type SkillDiscoveryItem,
   type SkillDiscoveryPage,
 } from "./skill-discovery";
-export { ConnectSetup, type ConnectSetupProps } from "./connect-setup";
+export { ConnectSetup, isOwnerApprovalPending, type ConnectSetupProps } from "./connect-setup";
 export { ConnectChooser, type ConnectChooserProps } from "./connect-chooser";
 export { ConnectAccounts, type ConnectAccountsProps } from "./connect-accounts";
 export { ConnectPanel, type ConnectPanelProps } from "./connect-panel";

package/src/hooks/shared-machines-list.ts

@@ -31,10 +31,22 @@ type Share = {
   inFlight: Promise<void> | null;
   trailing: Promise<void> | null;
   generation: number;
+  /** The last read was refused (401/403/404). Polling stays stopped until the
+   *  read is disabled (a permission/workspace change) or explicitly refreshed. */
+  halted: boolean;
 };
 
 const shares = new Map<string, Share>();
 
+/** A refusal that repeating the identical read cannot fix: the caller lacks
+ *  `enrollments:read` (403), is signed out (401), or the workspace/feature is
+ *  gone (404). Structural so host adapters with their own error types work. */
+export function isMachinesAccessRefusal(cause: unknown): boolean {
+  if (!cause || typeof cause !== "object" || !("status" in cause)) return false;
+  const status = (cause as { status: unknown }).status;
+  return status === 401 || status === 403 || status === 404;
+}
+
 function emit(share: Share): void {
   for (const subscriber of share.subscribers) {
     subscriber.onChange();
@@ -81,6 +93,7 @@ function cancelDispose(share: Share): void {
 
 function arm(share: Share): void {
   stopTimer(share);
+  if (share.halted) return;
   const { enabled, pollIntervalMs } = effective(share);
   if (!enabled || pollIntervalMs === undefined) return;
   share.timer = setTimeout(() => {
@@ -98,10 +111,15 @@ async function runFresh(share: Share): Promise<void> {
   try {
     const data = await load(abort.signal);
     if (ticket !== share.generation || abort.signal.aborted) return;
+    share.halted = false;
     share.snapshot = { data, loading: false, error: null };
     emit(share);
   } catch (cause) {
     if (ticket !== share.generation || abort.signal.aborted) return;
+    if (isMachinesAccessRefusal(cause)) {
+      share.halted = true;
+      stopTimer(share);
+    }
     share.snapshot = {
       data: share.snapshot.data,
       loading: false,
@@ -120,7 +138,7 @@ function run(share: Share, force = false): Promise<void> {
     let trailing!: Promise<void>;
     trailing = share.inFlight
       .then(async () => {
-        if (!effective(share).enabled) return;
+        if (!effective(share).enabled || share.halted) return;
         await run(share);
       })
       .finally(() => {
@@ -145,12 +163,21 @@ function reconcile(share: Share): void {
     share.abort = null;
     share.inFlight = null;
     stopTimer(share);
+    if (share.halted) {
+      // Disabling is the host's permission/workspace signal. Forget the
+      // refusal so a later re-enable reads once immediately.
+      share.halted = false;
+      share.snapshot = { data: share.snapshot.data, loading: false, error: null };
+      emit(share);
+      return;
+    }
     if (share.snapshot.loading) {
       share.snapshot = { ...share.snapshot, loading: false };
       emit(share);
     }
     return;
   }
+  if (share.halted) return;
   if (share.snapshot.data !== null || share.snapshot.error) {
     arm(share);
     return;
@@ -175,6 +202,7 @@ function getOrCreate(shareKey: string): Share {
     inFlight: null,
     trailing: null,
     generation: 0,
+    halted: false,
   };
   shares.set(shareKey, created);
   return created;
@@ -183,7 +211,12 @@ function getOrCreate(shareKey: string): Share {
 export async function refreshSharedMachinesList(shareKey: string): Promise<void> {
   const share = shares.get(shareKey);
   if (!share) return;
+  // An explicit refresh (user action, post-mutation reconcile) may retry once;
+  // a repeated refusal halts polling again.
+  const wasHalted = share.halted;
+  share.halted = false;
   await run(share, true);
+  if (wasHalted) arm(share);
 }
 
 export function useSharedMachinesList(

package/src/hooks/use-client-config-flags.ts

@@ -39,6 +39,12 @@ export type ClientConfigFlags = {
    * it off; availability otherwise comes from the realtime model catalog.
    */
   realtimeVoice: boolean;
+  /**
+   * The host explicitly offers live voice to end users (a session proxy with
+   * `realtimeVoice: true`). Embedded conversations show the voice button only
+   * then or when their `realtimeVoice` prop is `true`.
+   */
+  realtimeVoiceOffered: boolean;
 };
 
 const INITIAL_FLAGS: ClientConfigFlags = {
@@ -52,6 +58,7 @@ const INITIAL_FLAGS: ClientConfigFlags = {
   archive: true,
   voiceInput: null,
   realtimeVoice: false,
+  realtimeVoiceOffered: false,
 };
 
 type ClientConfigFlagsInput = Awaited<ReturnType<ClientConfigFlagsSource["getClientConfig"]>>;
@@ -97,6 +104,7 @@ export function useClientConfigFlags(
             archive: config.archive !== false,
             voiceInput: config.voiceInput?.available === true ? config.voiceInput : null,
             realtimeVoice: config.realtimeVoice !== false,
+            realtimeVoiceOffered: config.realtimeVoice === true,
           });
         }
       },

package/src/hooks/use-goal.ts

@@ -1,5 +1,5 @@
 import { OpenGeniApiError, type SessionEvent, type SessionGoal } from "@opengeni/sdk";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { useEmbeddedGoal, type EmbeddedGoalClientOverride } from "../session-context";
 import { normalizeError } from "../lib/error-message";
 import {
@@ -65,7 +65,8 @@ export type UseGoalResult = {
 /**
  * The session's goal: state, the autonomy counters (`autoContinuations`,
  * `noProgressStreak`), and pause/resume control. A goal-less session yields
- * `goal: null` (the 404 is absorbed). Live-updates on goal, turn, session,
+ * `goal: null`: read through `findGoal` as a successful null when the client
+ * has it, otherwise from an absorbed 404. Live-updates on goal, turn, session,
  * control, and system-update events — pass `options.events` from
  * `useSessionEvents` to reuse its stream.
  */
@@ -84,10 +85,19 @@ export function useGoal(
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
   const generation = useRef(0);
   const targetKeyRef = useRef<string | null>(null);
-  // True after the server answered 404. Only a goal event can create a goal,
-  // so turn/session traffic must not refetch (and 404) while none exists.
+  // True after the server answered that no goal exists. Only a goal event can
+  // create a goal, so turn/session traffic must not refetch while none exists.
   const goalAbsentRef = useRef(false);
+  // Refresh events not yet covered by a read: "goal" when any was a goal.*
+  // event. Events that arrive while a read is in flight are decided when it
+  // settles, so the stream's opening burst never re-reads a goal-less session.
+  const pendingRefreshRef = useRef<"none" | "refresh" | "goal">("none");
+  const sharedEventsRef = useRef(sharedEvents);
+  useLayoutEffect(() => {
+    sharedEventsRef.current = sharedEvents;
+  }, [sharedEvents]);
   const loadAbort = useRef<AbortController | null>(null);
+  const scheduleRefreshRef = useRef<() => void>(() => undefined);
 
   const retireLoads = useCallback(() => {
     generation.current += 1;
@@ -100,15 +110,20 @@ export function useGoal(
       return;
     }
     const ticket = ++generation.current;
+    pendingRefreshRef.current = "none";
     loadAbort.current?.abort();
     const controller = new AbortController();
     loadAbort.current = controller;
     try {
-      const fetched = await client.getGoal(workspaceId, sessionId, {
-        signal: controller.signal,
-      });
+      // findGoal reads a goal-less session as a successful null, so no failed
+      // request reaches the browser console. Custom clients without it keep
+      // getGoal, whose 404 is absorbed below (as it is from older servers).
+      const fetched =
+        typeof client.findGoal === "function"
+          ? await client.findGoal(workspaceId, sessionId, { signal: controller.signal })
+          : await client.getGoal(workspaceId, sessionId, { signal: controller.signal });
       if (ticket === generation.current) {
-        goalAbsentRef.current = false;
+        goalAbsentRef.current = fetched === null;
         setGoal(fetched);
         setError(null);
         setLoading(false);
@@ -129,6 +144,26 @@ export function useGoal(
     } finally {
       if (loadAbort.current === controller) loadAbort.current = null;
     }
+    if (ticket !== generation.current || pendingRefreshRef.current === "none") {
+      return;
+    }
+    // Events arrived during this read. A shared feed's first batch reports only
+    // its latest match, so a goal.* event behind newer turn traffic is visible
+    // only in the log: re-read when its latest goal event is not a clear.
+    if (goalAbsentRef.current && pendingRefreshRef.current === "refresh") {
+      const events = sharedEventsRef.current ?? [];
+      let latestGoalEvent: SessionEvent | undefined;
+      for (let index = events.length - 1; index >= 0 && !latestGoalEvent; index -= 1) {
+        const event = events[index];
+        if (event && isGoalEvent(event)) latestGoalEvent = event;
+      }
+      if (!latestGoalEvent || latestGoalEvent.type === "goal.cleared") {
+        pendingRefreshRef.current = "none";
+        return;
+      }
+      pendingRefreshRef.current = "goal";
+    }
+    scheduleRefreshRef.current();
   }, [client, workspaceId, sessionId]);
 
   useEffect(() => {
@@ -136,6 +171,7 @@ export function useGoal(
     if (targetKeyRef.current !== targetKey) {
       targetKeyRef.current = targetKey;
       goalAbsentRef.current = false;
+      pendingRefreshRef.current = "none";
       setGoal(null);
       setError(null);
     }
@@ -186,13 +222,33 @@ export function useGoal(
     sharedFeed,
   ]);
 
-  const scheduleRefresh = useDebouncedCallback(() => void load());
+  const scheduleRefresh = useDebouncedCallback(() => {
+    const pending = pendingRefreshRef.current;
+    // An in-flight read settles pending events itself.
+    if (pending === "none" || loadAbort.current !== null) return;
+    if (pending === "refresh" && goalAbsentRef.current) {
+      pendingRefreshRef.current = "none";
+      return;
+    }
+    void load();
+  });
+  useLayoutEffect(() => {
+    scheduleRefreshRef.current = scheduleRefresh;
+  }, [scheduleRefresh]);
   const isRefreshEvent = useCallback(
     (event: SessionEvent) =>
       goalAbsentRef.current ? isGoalEvent(event) : isGoalRefreshEvent(event),
     [],
   );
-  useSessionEventTrigger(client, workspaceId, sessionId, isRefreshEvent, scheduleRefresh, {
+  const onRefreshEvent = useCallback(
+    (event: SessionEvent) => {
+      if (isGoalEvent(event)) pendingRefreshRef.current = "goal";
+      else if (pendingRefreshRef.current === "none") pendingRefreshRef.current = "refresh";
+      scheduleRefresh();
+    },
+    [scheduleRefresh],
+  );
+  useSessionEventTrigger(client, workspaceId, sessionId, isRefreshEvent, onRefreshEvent, {
     enabled,
     ...(sharedEvents !== undefined ? { events: sharedEvents } : {}),
   });

package/src/human-input-model.ts

@@ -0,0 +1,147 @@
+import type { HumanInputAnswer, HumanInputQuestion } from "@opengeni/sdk";
+
+/* Pure drafting and validation rules for structured human-input requests,
+   shared by the web HumanInputForm and non-DOM renderers. */
+
+export type HumanInputAnswerDraft = {
+  values: string[];
+  other: string;
+  otherSelected: boolean;
+};
+
+export type HumanInputFormMessages = {
+  title: string;
+  description: string;
+  submit: string;
+  skip: string;
+  submitting: string;
+  other: string;
+  deadlineLabel: string;
+  formatDeadline: (value: string) => string;
+  required: string;
+  otherRequired: string;
+  minSelections: (count: number) => string;
+  maxSelections: (count: number) => string;
+  optional: string;
+  /** Shown when the question list overflows the card and more content is below. */
+  moreBelow: string;
+  questionCount: (count: number) => string;
+  collapse: string;
+  expand: string;
+  selectionHint: (min: number | null | undefined, max: number | null | undefined) => string | null;
+};
+
+export const defaultHumanInputFormMessages: HumanInputFormMessages = {
+  title: "Input required",
+  /** Multi-question chrome has no default subtitle; hosts may still override. */
+  description: "",
+  submit: "Send answers",
+  skip: "Skip",
+  submitting: "Submitting…",
+  other: "Other",
+  deadlineLabel: "Expires",
+  formatDeadline,
+  required: "This question is required.",
+  otherRequired: "Enter a value for Other.",
+  minSelections: (count) => `Choose at least ${count} option${count === 1 ? "" : "s"}.`,
+  maxSelections: (count) => `Choose no more than ${count} option${count === 1 ? "" : "s"}.`,
+  optional: "Optional",
+  moreBelow: "More below",
+  questionCount: (count) => `${count} questions`,
+  collapse: "Collapse",
+  expand: "Expand",
+  selectionHint: (min, max) => {
+    if (min != null && max != null) return `Choose ${min}–${max}.`;
+    if (min != null) return `Choose at least ${min}.`;
+    if (max != null) return `Choose up to ${max}.`;
+    return null;
+  },
+};
+
+export function answersFromDrafts(
+  questions: HumanInputQuestion[],
+  drafts: Record<string, HumanInputAnswerDraft>,
+  messageOverrides: Partial<HumanInputFormMessages> = {},
+): { answers: HumanInputAnswer[]; errors: Record<string, string> } {
+  const messages = { ...defaultHumanInputFormMessages, ...messageOverrides };
+  const answers: HumanInputAnswer[] = [];
+  const errors: Record<string, string> = {};
+  for (const question of questions) {
+    const draft = drafts[question.id] ?? emptyDraft();
+    const values = question.kind === "text" ? draft.values.filter(Boolean) : draft.values;
+    const other = draft.otherSelected ? draft.other : "";
+    const hasOther = Boolean(other.trim());
+    const supplied = values.length + (hasOther ? 1 : 0);
+
+    // Other-selected-but-empty must win over generic "required" — otherwise the
+    // user sees the wrong diagnosis next to a clearly selected control.
+    if (question.kind !== "text" && draft.otherSelected && !hasOther) {
+      errors[question.id] = messages.otherRequired;
+      continue;
+    }
+
+    if (question.required && supplied === 0) {
+      errors[question.id] = messages.required;
+      continue;
+    }
+    if (question.kind !== "text") {
+      const min = question.validation?.minSelections;
+      const max = question.kind === "single_select" ? 1 : question.validation?.maxSelections;
+      if (min != null && supplied < min) {
+        errors[question.id] = messages.minSelections(min);
+        continue;
+      }
+      if (max != null && supplied > max) {
+        errors[question.id] = messages.maxSelections(max);
+        continue;
+      }
+    }
+    if (supplied > 0) {
+      answers.push({
+        questionId: question.id,
+        values,
+        ...(hasOther ? { other } : {}),
+      });
+    }
+  }
+  return { answers, errors };
+}
+
+export function initialDrafts(
+  questions: HumanInputQuestion[],
+): Record<string, HumanInputAnswerDraft> {
+  return Object.fromEntries(questions.map((question) => [question.id, emptyDraft()]));
+}
+
+export function emptyDraft(): HumanInputAnswerDraft {
+  return { values: [], other: "", otherSelected: false };
+}
+
+export function formatDeadline(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  const ms = date.getTime() - Date.now();
+  if (ms <= 0) return "deadline passed";
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 1) return "in under a minute";
+  if (minutes < 60) return `in ${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `in ${hours}h`;
+  return date.toLocaleString();
+}
+
+/** The form heading: a single question leads with its own label/prompt. */
+export function humanInputHeading(
+  questions: readonly HumanInputQuestion[],
+  messages: Pick<HumanInputFormMessages, "title" | "description">,
+): { title: string; description: string | null } {
+  const single = questions.length === 1 ? questions[0]! : null;
+  return {
+    title: single ? (single.label ?? single.prompt) : messages.title,
+    description: single
+      ? single.label
+        ? single.prompt
+        : (single.helpText ?? null)
+      : messages.description || null,
+  };
+}