Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

41.2 KB
Raw Blame
import type {
  AddToolResultOptions,
  AppendMessage,
  ThreadMessage as AuiThreadMessage,
  RespondToToolApprovalOptions,
  ThreadMessageLike,
  ThreadSuggestion,
} from '@assistant-ui/react';
import debug from 'debug';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';

import { toast } from '../components/ui/Toast';
import { useOpenHumanQueueAdapter } from '../features/conversations/aui/queueAdapter';
import { mapDisplayItems } from '../features/conversations/derived/mapDisplayItems';
import { useT } from '../lib/i18n/I18nContext';
import { type ApprovalDecision, decideApproval } from '../services/api/approvalApi';
import { threadApi } from '../services/api/threadApi';
import { editMessage, regenerateMessage } from '../services/chatService';
import {
  clearPendingApprovalForThread,
  type InferenceStatus,
  isActiveTimelineStatus,
  type ToolTimelineEntry,
} from '../store/chatRuntimeSlice';
import { toThreadSuggestions } from '../store/followupSuggestionsSlice';
import { useAppDispatch, useAppSelector } from '../store/hooks';
import {
  FEEDBACK_ROW_IDS_METADATA_KEY,
  persistMessageFeedback,
  removeMessagesById,
  truncateMessagesFrom,
} from '../store/threadSlice';
import type { DerivedDisplayItem } from '../types/derivedTranscript';
import type { ThreadMessage } from '../types/thread';
import { buildRuntimeMessages, STREAMING_TAIL_ID } from './assistantUiMessages';
import { getChatSurface } from './chatSurfaceHandlers';
import { openHumanSpeechAdapter } from './speechAdapter';

const log = debug('openhuman:chat:external-store');

const EMPTY_MESSAGES: ThreadMessage[] = [];
const EMPTY_SUGGESTIONS: readonly ThreadSuggestion[] = [];
const EMPTY_TIMELINE: never[] = [];
const EMPTY_TRANSCRIPT: never[] = [];
const EMPTY_TURN_MAP = {};
const EMPTY_SETTLED = {};
/** Items per derived-transcript RPC page; the core caps a page at this size. */
const DERIVED_TRANSCRIPT_PAGE_LIMIT = 500;
/**
 * Upper bound on pages walked for one thread (10k items). A thread longer than
 * this is truncated at its oldest end rather than fetched without limit; the
 * turn-bounded RPC contract that removes the ceiling altogether is tracked with
 * the transcript RPC, not here.
 */
const DERIVED_TRANSCRIPT_MAX_PAGES = 20;

/**
 * A projected item the core can still rewrite in place: a running tool call, or
 * a sub-agent that is running or can be continued (`incomplete`/`interrupted`)
 * and so changes status and contents without moving the thread's total (#7777).
 */
const isUnsettled = (item: DerivedDisplayItem) =>
  item.kind === 'toolCall'
    ? item.status === 'running'
    : item.kind === 'subagent' &&
      (item.status === 'running' || item.status === 'incomplete' || item.status === 'interrupted');

/**
 * Everything the assistant-ui surface needs about the *currently running* turn
 * that is not a message, a tool part or a stream delta.
 *
 * assistant-ui derives its own running state from `thread.isRunning` alone, so
 * without this channel a long turn is a bare spinner: no phase, no round
 * counter, no active tool. The socket handlers already maintain all three in
 * `chatRuntime.inferenceStatusByThread` (`onInferenceStart`, `onIterationStart`,
 * `onToolCall`); this projects that slice onto the runtime the surface reads.
 *
 * It travels on the adapter's `extras` channel rather than being read from
 * Redux by the renderer so it stays scoped to *this runtime's* thread — the
 * Workflow Copilot mounts a second runtime on a thread that is deliberately not
 * `selectedThreadId`, and a renderer-side Redux read would paint the home
 * chat's progress inside it.
 */
export type OpenHumanThreadExtras = {
  /** Live phase/round/active-tool for the running turn, or `null` when idle. */
  inferenceStatus: InferenceStatus | null;
  /** Newest running non-subagent row, used to title the `tool_use` phase. */
  activeToolEntry?: ToolTimelineEntry | undefined;
  /** Running subagent row, used to title the `subagent` phase. */
  activeSubagentEntry?: ToolTimelineEntry | undefined;
};

const convertRuntimeMessage = (message: ThreadMessageLike) => message;

const EMPTY_EXTRAS: OpenHumanThreadExtras = { inferenceStatus: null };

/**
 * Narrow assistant-ui's untyped `thread.extras` back to our own shape.
 *
 * `extras` is `unknown` by contract, and a surface can be mounted on a runtime
 * that is not ours (or on none at all), so this returns `null` rather than
 * asserting.
 */
export function readOpenHumanThreadExtras(extras: unknown): OpenHumanThreadExtras | null {
  if (typeof extras !== 'object' || extras === null) return null;
  if (!('inferenceStatus' in extras)) return null;
  return extras as OpenHumanThreadExtras;
}

type CoreTranscriptProjection = {
  threadId: string | null;
  timelines: ReturnType<typeof mapDisplayItems>['timelines'];
  transcripts: ReturnType<typeof mapDisplayItems>['transcripts'];
};

const EMPTY_CORE_TRANSCRIPT: CoreTranscriptProjection = {
  threadId: null,
  timelines: EMPTY_TURN_MAP,
  transcripts: EMPTY_TURN_MAP,
};

/**
 * Keep the previous array for every turn whose re-projection is unchanged.
 *
 * The projection refetches whenever the thread's last message or lifecycle
 * moves — several times per turn — and each fetch minted fresh arrays for
 * EVERY turn. The settled-message conversion cache is keyed on those array
 * identities, so each refetch re-converted the whole thread and handed
 * assistant-ui new part objects for turns nothing had happened to.
 */
function reuseUnchangedTurns<T>(
  previous: Record<string, T[]>,
  next: Record<string, T[]>
): Record<string, T[]> {
  const nextKeys = Object.keys(next);
  let allReused = nextKeys.length === Object.keys(previous).length;
  const merged: Record<string, T[]> = {};
  for (const key of nextKeys) {
    const before = previous[key];
    if (before !== undefined && JSON.stringify(before) === JSON.stringify(next[key])) {
      merged[key] = before;
    } else {
      merged[key] = next[key];
      allReused = false;
    }
  }
  return allReused ? previous : merged;
}

/**
 * Read settled process history straight from the core's transcript projection.
 * The Rust side owns a bounded, mtime-keyed LRU, so this hook deliberately does
 * not establish a second Redux transcript store or duplicate cache policy.
 */
export function useCoreTranscriptProjection(
  threadId: string | null,
  revision: string,
  liveRequestId: string | undefined
): CoreTranscriptProjection {
  const [projection, setProjection] = useState<CoreTranscriptProjection>(EMPTY_CORE_TRANSCRIPT);
  // Read by the fetch loop after each await: the thread may have changed.
  const latest = useRef({ threadId, liveRequestId });
  latest.current = { threadId, liveRequestId };
  // Newest-first items already fetched for one thread, and the thread's
  // `total` when they were. Cursors are chronological, so items older than the
  // newest page keep their position and a refresh only needs that page (#7731).
  const held = useRef<{ threadId: string; total: number; items: DerivedDisplayItem[] } | null>(
    null
  );
  // One fetch loop at a time; a change while it runs asks for one more pass.
  // `loop` numbers the loops, so an abandoned one stays stale even when its
  // thread is selected again.
  const inFlight = useRef<string | null>(null);
  const rerun = useRef(false);
  const loop = useRef(0);

  useEffect(() => {
    if (!threadId) {
      setProjection(EMPTY_CORE_TRANSCRIPT);
      return;
    }
    // Defensive for narrow test/embedder shims that expose only a subset of
    // threadApi. Production builds always provide this method.
    if (typeof threadApi.getDerivedTranscript !== 'function') {
      setProjection({ threadId, timelines: EMPTY_TURN_MAP, transcripts: EMPTY_TURN_MAP });
      return;
    }
    if (inFlight.current === threadId) {
      rerun.current = true;
      return;
    }
    const id = ++loop.current;
    const stale = () => loop.current !== id || latest.current.threadId !== threadId;
    const project = (items: DerivedDisplayItem[], partial = false) => {
      const live = latest.current.liveRequestId;
      const mapped = mapDisplayItems(items, { skipRequestIds: live ? new Set([live]) : undefined });
      setProjection(previous => {
        if (partial && previous.threadId === threadId && Object.keys(previous.timelines).length > 0)
          return previous;
        if (previous.threadId !== threadId) {
          return { threadId, timelines: mapped.timelines, transcripts: mapped.transcripts };
        }
        const timelines = reuseUnchangedTurns(previous.timelines, mapped.timelines);
        const transcripts = reuseUnchangedTurns(previous.transcripts, mapped.transcripts);
        if (timelines === previous.timelines && transcripts === previous.transcripts) {
          return previous;
        }
        return { threadId, timelines, transcripts };
      });
    };
    const refresh = async () => {
      const first = await threadApi.getDerivedTranscript(threadId, {
        limit: DERIVED_TRANSCRIPT_PAGE_LIMIT,
      });
      if (stale()) return;
      if (!first.hasTranscript) {
        held.current = null;
        setProjection({ threadId, timelines: EMPTY_TURN_MAP, transcripts: EMPTY_TURN_MAP });
        return;
      }
      const prev = held.current?.threadId === threadId ? held.current : null;
      // Chronological index of the page's oldest item.
      const lower = Math.max(0, first.total - first.items.length);
      let items = first.items;
      const older = prev ? prev.items.slice(prev.total - lower) : [];
      if (prev && first.total >= prev.total && lower <= prev.total && !older.some(isUnsettled)) {
        // The newest page reaches into what is held: keep the held items older
        // than it, within the same cap as a full walk. A shrunk total (edit,
        // regenerate), a gap, or an older item still running (a detached
        // sub-agent finishes in place) walks in full.
        items = [...items, ...older].slice(
          0,
          DERIVED_TRANSCRIPT_PAGE_LIMIT * DERIVED_TRANSCRIPT_MAX_PAGES
        );
      } else {
        // Paint the newest page immediately, then walk the older pages and
        // re-project once with the whole history. A page that begins mid-turn
        // hides that turn's leading tool calls until its boundary is in view.
        if (first.hasMore) project(items, true);
        let cursor = first.hasMore ? first.nextCursor : undefined;
        let pages = 1;
        while (cursor && pages < DERIVED_TRANSCRIPT_MAX_PAGES) {
          const page = await threadApi.getDerivedTranscript(threadId, {
            limit: DERIVED_TRANSCRIPT_PAGE_LIMIT,
            cursor,
          });
          if (stale()) return;
          // Pages are newest-first and each next page is older, so appending
          // keeps the newest-first order `mapDisplayItems` expects.
          items = [...items, ...page.items];
          pages += 1;
          cursor = page.hasMore ? page.nextCursor : undefined;
        }
      }
      held.current = { threadId, total: first.total, items };
      project(items);
    };
    inFlight.current = threadId;
    void (async () => {
      do {
        rerun.current = false;
        try {
          await refresh();
        } catch {
          // A missing/older core has no settled process trail; message text and
          // the live socket projection remain usable. Navigation must not fail.
          // A transient refresh failure must not erase the last complete trail,
          // and a pass queued meanwhile still runs.
        }
      } while (rerun.current && !stale());
      if (loop.current === id) inFlight.current = null;
    })();
  }, [liveRequestId, revision, threadId]);

  return projection.threadId === threadId ? projection : EMPTY_CORE_TRANSCRIPT;
}

/** Flatten an assistant-ui append payload down to the plain text our core takes. */
function appendMessageText(message: AppendMessage): string {
  return message.content
    .map(part => (part.type === 'text' ? part.text : ''))
    .join('')
    .trim();
}

/**
 * The starter prompts offered on an empty thread, in display order.
 *
 * Each key's translation is used as BOTH the chip's text and the message the
 * chip sends: `ThreadSuggestion.title` falls back to `prompt` upstream
 * (`@assistant-ui/core`'s suggestions client, `title: s.title ?? s.prompt`), so
 * one string per suggestion keeps the chip and the sent turn from ever drifting
 * apart — and keeps this at six translated strings rather than twelve.
 */
const WELCOME_SUGGESTION_KEYS = [
  'chat.welcomeSuggestion.calendarToday',
  'chat.welcomeSuggestion.unreadEmail',
  'chat.welcomeSuggestion.draftReply',
  'chat.welcomeSuggestion.followUps',
  'chat.welcomeSuggestion.connectIntegration',
  'chat.welcomeSuggestion.dailySummaryFlow',
] as const;

/**
 * Starter chips for an empty thread — and nothing once the thread has content.
 *
 * **The emptiness gate is the whole point of this hook, not an optimisation.**
 * The welcome chips and the follow-up chips read the *same* field
 * (`s.thread.suggestions`) and their render gates are complementary rather than
 * overlapping, so between them they partition every state:
 *
 * - welcome  — `isNewChatView && composer.isEmpty`  (`thread.tsx`)
 * - follow-up — `!isEmpty && !isRunning && length > 0` (`follow-up-suggestions.tsx`)
 *
 * They therefore never render at the same time, which is exactly what makes an
 * ungated list dangerous: a constant set shows correctly on the empty thread and
 * then *reappears as follow-up chips under every settled turn, forever*. Static
 * starter prompts hanging under turn 30 are worse than no chips at all.
 *
 * Gating here — at the only inlet — keeps the follow-up surface for what only
 * `useFollowupSuggestions` produces: the core's per-turn `chat_suggestions`
 * (openhuman#6465 records this constraint). Do not lift the gate to the
 * renderer: it cannot tell the two surfaces apart, because they read one field.
 *
 * `messageCount` is the *runtime's* message count (settled turns plus any live
 * tail), which is precisely what `isNewChatView` tests upstream — not the
 * Redux row count, which excludes the in-flight turn and would leave the chips
 * up for the first streaming answer.
 */
function useWelcomeSuggestions(
  messageCount: number,
  enabled: boolean
): readonly ThreadSuggestion[] {
  const { t } = useT();
  return useMemo(
    () =>
      enabled && messageCount === 0
        ? WELCOME_SUGGESTION_KEYS.map(key => ({ prompt: t(key) }))
        : EMPTY_SUGGESTIONS,
    [enabled, messageCount, t]
  );
}

/**
 * The core's follow-up chips for the thread's latest turn, and nothing else.
 *
 * The complement of `useWelcomeSuggestions`: empty on an empty thread (the
 * welcome chips own that state), empty while a turn runs, and empty unless
 * the transcript ends on an assistant reply, because the chips follow that
 * reply. The set comes from `chat_suggestions` via `followupSuggestionsSlice`,
 * which also drops it the moment the next turn starts.
 */
function useFollowupSuggestions(
  threadId: string | null,
  messageCount: number,
  lastRole: string | undefined,
  isRunning: boolean
): readonly ThreadSuggestion[] {
  const stored = useAppSelector(state =>
    threadId ? (state.followupSuggestions?.byThread[threadId] ?? null) : null
  );
  return useMemo(() => {
    if (!stored || messageCount === 0 || isRunning || lastRole !== 'assistant') {
      return EMPTY_SUGGESTIONS;
    }
    return toThreadSuggestions(stored.suggestions);
  }, [stored, messageCount, lastRole, isRunning]);
}

/**
 * The excerpt the user quoted, as a markdown blockquote, or `''`.
 *
 * The composer carries a quote as STRUCTURE — `metadata.custom.quote`, a
 * `{ text, messageId }` set by `SelectionToolbarPrimitive.Quote` — but
 * `surface.send` takes a string, so it has to be rendered into the message or
 * it never reaches the model. Dropping it would leave the quote chip in the
 * composer as decoration: the user would watch themselves quote a paragraph
 * and the agent would answer as though they had not.
 *
 * A blockquote is the representation to pick: it is what the excerpt already
 * is, every model reads it as quoted material, and it survives in the
 * persisted message so the turn still makes sense on reload.
 *
 * `messageId` is deliberately dropped. Nothing downstream can resolve it — the
 * core stores no reference between messages — and a raw id in the prompt is
 * noise to the model.
 */
function appendMessageQuote(message: AppendMessage): string {
  const quote = (message.metadata as { custom?: { quote?: { text?: unknown } } } | undefined)
    ?.custom?.quote;
  const text = typeof quote?.text === 'string' ? quote.text.trim() : '';
  if (text.length === 0) return '';
  return `${text
    .split('\n')
    .map(line => `> ${line}`)
    .join('\n')}\n\n`;
}

/** Prefix of the core's deterministic assistant-reply ids (`agent:<request_id>`). */
const AGENT_REPLY_ID_PREFIX = 'agent:';

/**
 * Which id to hand `threads.regenerate` for the reply `sourceId`, or `null`
 * when it cannot be regenerated.
 *
 * The core accepts only an assistant reply id (`agent:<request_id>`) or no id
 * (redo the thread's last turn), so in order:
 * - `sourceId` is already an `agent:` reply id → send it;
 * - the reply carries its turn's `requestId` (older rows persisted under a
 *   `msg_<uuid>` id do) → send `agent:<requestId>`;
 * - it is the thread's last assistant message, or no reply was named at all →
 *   send no id, which the core reads as "the last turn";
 * - anything else is an earlier reply the core has no handle on → `null`.
 */
export function resolveRegenerateTarget(
  runtimeMessages: readonly ThreadMessageLike[],
  sourceId: string | null
): { messageId: string | undefined } | null {
  if (!sourceId) return { messageId: undefined };
  if (sourceId.startsWith(AGENT_REPLY_ID_PREFIX)) return { messageId: sourceId };
  const source = runtimeMessages.find(message => message.id === sourceId);
  const custom = source?.metadata?.custom as
    | { extraMetadata?: Record<string, unknown> }
    | undefined;
  const requestId = custom?.extraMetadata?.requestId;
  if (typeof requestId === 'string' && requestId.length > 0) {
    return { messageId: `${AGENT_REPLY_ID_PREFIX}${requestId}` };
  }
  const lastAssistant = [...runtimeMessages]
    .reverse()
    .find(message => message.role === 'assistant');
  if (source && lastAssistant?.id === sourceId) return { messageId: undefined };
  return null;
}

/**
 * Build the `ExternalStoreAdapter` that backs `useExternalStoreRuntime`.
 *
 * Settled messages and live deltas remain in their existing UI stores, while
 * reasoning/tool/sub-agent history comes directly from the core transcript
 * projection. Redux is not a second transcript database.
 */
export function useOpenHumanExternalStore(
  threadId: string | null,
  {
    welcomeSuggestions = true,
  }: {
    /**
     * Offer the home chat's starter prompts on an empty thread. Off for a
     * surface whose agent is not the general assistant (the workflow copilot):
     * a click SENDS the prompt, and those prompts are not builder requests.
     */
    welcomeSuggestions?: boolean;
  } = {}
) {
  const dispatch = useAppDispatch();
  const { t } = useT();
  const messages = useAppSelector(state =>
    threadId ? (state.thread.messagesByThreadId[threadId] ?? EMPTY_MESSAGES) : EMPTY_MESSAGES
  );
  const streaming = useAppSelector(state =>
    threadId ? (state.chatRuntime.streamingAssistantByThread?.[threadId] ?? null) : null
  );
  const lifecycle = useAppSelector(state =>
    threadId ? (state.chatRuntime.inferenceTurnLifecycleByThread?.[threadId] ?? null) : null
  );
  const isLoading = useAppSelector(state => Boolean(threadId && state.thread.isLoadingMessages));
  const liveTimeline = useAppSelector(state =>
    threadId
      ? (state.chatRuntime.toolTimelineByThread?.[threadId] ?? EMPTY_TIMELINE)
      : EMPTY_TIMELINE
  );
  const liveTranscript = useAppSelector(state =>
    threadId
      ? (state.chatRuntime.processingByThread?.[threadId] ?? EMPTY_TRANSCRIPT)
      : EMPTY_TRANSCRIPT
  );
  // Progress status for the running turn. Cleared by the socket layer on turn
  // end/error/cancel, so its presence is itself the "still working" signal.
  const inferenceStatus = useAppSelector(state =>
    threadId ? (state.chatRuntime.inferenceStatusByThread?.[threadId] ?? null) : null
  );
  // The thread's parked ApprovalGate request. Selected here rather than read by
  // a card somewhere else on the page: the decision belongs on the tool call it
  // gates, and only this adapter can put it there.
  const pendingApproval = useAppSelector(state =>
    threadId ? (state.chatRuntime.pendingApprovalByThread?.[threadId] ?? null) : null
  );
  const liveRequestId = useAppSelector(state =>
    threadId ? state.chatRuntime.liveRequestIdByThread?.[threadId] : undefined
  );
  const liveTimelineRequestId = useAppSelector(state =>
    threadId ? state.chatRuntime.toolTimelineRequestByThread?.[threadId] : undefined
  );
  const settledTurns = useAppSelector(state =>
    threadId ? (state.chatRuntime.settledTurnsByThread?.[threadId] ?? EMPTY_SETTLED) : EMPTY_SETTLED
  );
  const settledRevision = `${messages.at(-1)?.id ?? ''}:${messages.at(-1)?.content?.length ?? 0}:${lifecycle ?? ''}`;
  const tailRequestId = liveRequestId ?? streaming?.requestId;
  const coreTranscript = useCoreTranscriptProjection(threadId, settledRevision, tailRequestId);

  // `started` and `streaming` are both in-flight. A completed turn can retain
  // its tool/reasoning arrays while the persisted projection catches up; those
  // arrays must not mint a forever-running assistant-ui tail.
  const isRunning = lifecycle === 'started' || lifecycle === 'streaming';

  // Recomputed only when the settled transcript or the live tail changes.
  // Settled messages are converted through an identity-keyed cache, so a token
  // landing on the tail re-converts exactly one message, never the transcript.
  const runtimeMessages = useMemo(
    () =>
      buildRuntimeMessages(messages, streaming, {
        isRunning,
        liveTimeline,
        liveTranscript,
        liveTimelineRequestId,
        pendingApproval,
        turnTimelines: coreTranscript.timelines,
        turnTranscripts: coreTranscript.transcripts,
        settledTurns,
        liveRequestId: tailRequestId,
      }),
    [
      messages,
      streaming,
      isRunning,
      liveTimeline,
      liveTranscript,
      liveTimelineRequestId,
      pendingApproval,
      coreTranscript,
      settledTurns,
      tailRequestId,
    ]
  );

  // The two gates are disjoint (welcome needs an empty thread, follow-ups a
  // settled reply), so at most one of these is ever non-empty.
  const welcomeChips = useWelcomeSuggestions(runtimeMessages.length, welcomeSuggestions);
  const followupChips = useFollowupSuggestions(
    threadId,
    runtimeMessages.length,
    runtimeMessages.at(-1)?.role,
    isRunning
  );
  const suggestions = welcomeChips.length > 0 ? welcomeChips : followupChips;

  // The status line titles its `tool_use` / `subagent` phases from the matching
  // running timeline row (the same rows the surface renders as tool parts), so
  // "Running command: npm test..." reads like the row rather than the raw tool
  // id. Resolved here so the renderer stays a pure projection of `extras`.
  const extras = useMemo<OpenHumanThreadExtras>(() => {
    if (!inferenceStatus) return EMPTY_EXTRAS;
    return {
      inferenceStatus,
      // `isActiveTimelineStatus`, not `status === 'running'`: a delegated child
      // parked on `ask_user_clarification` carries `awaiting_user` on the row's
      // top-level status, and dropping the match there loses the sub-agent's
      // identity at the one moment the user is the thing being waited on.
      activeToolEntry: [...liveTimeline]
        .reverse()
        .find(entry => isActiveTimelineStatus(entry.status) && !entry.name.startsWith('subagent:')),
      activeSubagentEntry: liveTimeline.find(
        entry => isActiveTimelineStatus(entry.status) && entry.name.startsWith('subagent:')
      ),
    };
  }, [inferenceStatus, liveTimeline]);

  const onNew = useCallback(
    async (message: AppendMessage) => {
      const surface = getChatSurface(threadId);
      // Fail loudly. A silent no-op here would look like a dropped message.
      if (!surface) {
        throw new Error(`No chat surface registered for thread ${threadId ?? '(none)'}`);
      }
      const text = appendMessageText(message);
      if (text.length === 0) return;
      await surface.send(`${appendMessageQuote(message)}${text}`);
    },
    [threadId]
  );

  /**
   * Thumbs on a settled assistant reply.
   *
   * Supplying this key is what turns the capability on at all — the runtime
   * computes `capabilities.feedback` as `!!adapters?.feedback` and renders
   * nothing without it.
   *
   * `submit` returns `void` by contract: there is no promise for the runtime to
   * await and no error channel back to it. A failed persist therefore cannot
   * surface through the adapter, so the thunk owns the failure, and the
   * optimistic value is only committed by its `fulfilled` reducer — a rejected
   * write leaves the thumb unpressed rather than showing a rating that was never
   * stored.
   */
  const feedbackAdapter = useMemo(
    () => ({
      submit: ({ message, type }: { message: AuiThreadMessage; type: 'positive' | 'negative' }) => {
        // The live tail is not a persisted row; there is nothing to attach a
        // rating to until the turn settles.
        if (
          !threadId ||
          message.id === STREAMING_TAIL_ID ||
          (message.metadata?.custom as { streaming?: boolean })?.streaming
        )
          return;
        const custom = message.metadata?.custom as
          | { extraMetadata?: Record<string, unknown> }
          | undefined;
        const rowIds = custom?.extraMetadata?.[FEEDBACK_ROW_IDS_METADATA_KEY];
        void dispatch(
          persistMessageFeedback({
            threadId,
            // `toThreadMessageLike` carries our own row id through unchanged, and
            // for a merged run that is the LAST row's (see `mergeAssistantRun`).
            messageId: message.id,
            feedback: type,
            rowIds: Array.isArray(rowIds) ? (rowIds as string[]) : undefined,
          })
        );
      },
    }),
    [dispatch, threadId]
  );

  const onCancel = useCallback(async () => {
    await getChatSurface(threadId)?.cancel?.();
  }, [threadId]);

  // The core's run queue, as assistant-ui's message queue. Supplying it makes
  // the runtime send through `queue.enqueue` / `queue.steer` instead of
  // `onNew`; both forward to `onNew`, so the surface still picks the
  // `queue_mode` (see `features/conversations/aui/queueAdapter.ts`).
  const queue = useOpenHumanQueueAdapter(threadId, onNew);

  /**
   * Rewrite a settled message and resend it, via the `threads.edit_message`
   * RPC (wire-contract.md; core workstream C4). `message.sourceId` is
   * assistant-ui's own field for "the id of the message that was edited" —
   * present because `EditComposer`/the vendored `EditMessage` element calls
   * `useAui().thread.append` with the original message's id as `sourceId`.
   *
   * Supplying this key at all is what turns `capabilities.edit` on
   * (`ExternalStoreThreadRuntimeCore` computes it as `!!this._store.onEdit`),
   * which un-gates `UserActionBar`'s Edit button and `EditComposer` in
   * `thread.tsx` (`useAuiEditCapabilities`).
   */
  const onEdit = useCallback(
    async (message: AppendMessage) => {
      if (!threadId) {
        throw new Error('No thread selected for edit');
      }
      const messageId = message.sourceId;
      if (!messageId) {
        throw new Error('Edit is missing the source message id');
      }
      const sourceRow = messages.find(row => row.id === messageId);
      const text = `${appendMessageQuote(message)}${appendMessageText(message)}`;
      // Truncate the local cache FIRST: the edit RPC returns no message list,
      // and the socket events that follow (`inference_start` … `chat_done`)
      // only carry the new turn, so a reader would still see the discarded
      // replies until the next full refetch if this waited on the RPC.
      dispatch(truncateMessagesFrom({ threadId, messageId, inclusive: true }));
      await editMessage({
        threadId,
        messageId,
        content: text,
        // Keep the source row's media when editing its text. The core accepts
        // only these opaque refs, validates them against this exact row, and
        // stages fresh ownership before truncating history.
        attachments: sourceRow?.attachments?.length ? sourceRow.attachments : undefined,
      });
    },
    [dispatch, messages, threadId]
  );

  /**
   * Regenerate an assistant reply via the `threads.regenerate` RPC. Same
   * capability-gating rule as `onEdit`: supplying `onReload` is what turns
   * `capabilities.reload` on, which un-gates the Reload button in
   * `AssistantActionBar` (`useAuiReloadCapability`).
   *
   * assistant-ui's `MessageRuntime.reload()` calls this with `parentId` = the
   * USER prompt that preceded the reply and `config.sourceId` = the reply
   * itself. The core only regenerates an assistant reply id
   * (`agent:<request_id>`) or, with no id, the thread's last turn — a user
   * prompt's `msg_<uuid>` is rejected as "not a regenerable assistant reply".
   * See {@link resolveRegenerateTarget} for how the reply id is resolved.
   *
   * The local cache is trimmed only once the core has accepted the
   * regenerate, and a failure is reported to the user rather than rethrown —
   * the runtime has no error channel for a reload, so a rethrow surfaced as an
   * unhandled rejection.
   */
  const onReload = useCallback(
    async (parentId: string | null, config?: { sourceId?: string | null }) => {
      if (!threadId) {
        log('reload skipped: no thread selected');
        return;
      }
      // assistant-ui always sends the reply as `sourceId`; if only the user
      // prompt (`parentId`) arrives, the reply is the first agent row after it.
      let sourceId = config?.sourceId ?? null;
      if (!sourceId && parentId) {
        const parentIndex = messages.findIndex(m => m.id === parentId);
        if (parentIndex >= 0) {
          sourceId = messages.slice(parentIndex + 1).find(m => m.sender === 'agent')?.id ?? null;
        }
      }
      const target = resolveRegenerateTarget(runtimeMessages, sourceId);
      if (!target) {
        log('reload refused: reply has no regenerable id thread=%s', threadId);
        toast.add({ type: 'error', title: t('chat.regenerate.unavailable') });
        return;
      }
      // Snapshot the rows this regenerate discards — the reply (and anything
      // after it) — BEFORE the RPC. The new turn can stream in over the socket
      // before the RPC resolves, and trimming by position afterwards would drop
      // it too.
      let discardFrom = -1;
      let discardedIds: string[] = [];
      if (parentId) {
        const parentIndex = messages.findIndex(m => m.id === parentId);
        if (parentIndex >= 0) discardFrom = parentIndex + 1;
      } else if (sourceId) {
        discardFrom = messages.findIndex(m => m.id === sourceId);
      } else {
        // No ids at all: the core regenerates the thread's last turn. Discard
        // every cached row of the final assistant bubble (it can span several).
        const lastAssistant = [...runtimeMessages]
          .reverse()
          .find(message => message.role === 'assistant');
        const custom = lastAssistant?.metadata?.custom as
          | { extraMetadata?: Record<string, unknown> }
          | undefined;
        const rowIds = custom?.extraMetadata?.[FEEDBACK_ROW_IDS_METADATA_KEY];
        const turnRowIds =
          Array.isArray(rowIds) && rowIds.length > 0
            ? rowIds.filter((id): id is string => typeof id === 'string')
            : lastAssistant?.id
              ? [lastAssistant.id]
              : [];
        const turnRowIdSet = new Set(turnRowIds);
        discardedIds = messages.filter(m => turnRowIdSet.has(m.id)).map(m => m.id);
      }
      if (discardFrom >= 0) {
        discardedIds = messages.slice(discardFrom).map(m => m.id);
      }
      try {
        await regenerateMessage({ threadId, messageId: target.messageId });
      } catch (err) {
        log(
          'reload failed thread=%s error=%s',
          threadId,
          err instanceof Error ? err.name : typeof err
        );
        toast.add({ type: 'error', title: t('chat.regenerate.failed') });
        return;
      }
      // The regenerate RPC returns no message list, and the socket events
      // that follow only carry the new turn, so drop the discarded rows from
      // the cache now that the core has forked.
      dispatch(removeMessagesById({ threadId, messageIds: discardedIds }));
    },
    [dispatch, messages, runtimeMessages, t, threadId]
  );

  /**
   * Required alongside `onEdit`/`onReload` to un-gate `BranchPicker`
   * (`capabilities.switchToBranch` is `!!this._store.setMessages`). A no-op:
   * there is no per-branch message model on the core yet — `onEdit` and
   * `onReload` both truncate the thread's single lineage rather than forking
   * one, so the runtime never has an alternate branch to hand back here.
   */
  const setMessages = useCallback(() => {}, []);

  /**
   * Drop a message from the local cache only — there is no backend RPC to
   * delete a persisted turn.
   *
   * Backs the vendored `StoppedRun` element's Discard action
   * (`components/assistant-ui/thread.tsx`): the partial reply a stopped turn
   * persists (`extraMetadata.stopped`, `Conversations.tsx`) is real content
   * server-side, so this hides it from THIS client rather than erasing it —
   * the same "never erases, only trims what the client reads" posture the
   * transcript takes on compaction.
   *
   * Supplying `onDelete` at all is what the runtime checks FIRST
   * (`ExternalStoreThreadRuntimeCore.deleteMessage`), ahead of the
   * `setMessages`-based fallback that already made `capabilities.delete`
   * true. That fallback filters its own internal repository and hands the
   * result to `setMessages`, which above is a no-op — so without this, a
   * `message.delete()` call would flash the message away and then restore it
   * on the next render, since `messages` here is still bound to the
   * unmodified Redux array. Reusing `truncateMessagesFrom` (the same local
   * cache trim `onEdit`/`onReload` use) is what actually removes it.
   */
  const onDelete = useCallback(
    (messageId: string) => {
      if (!threadId) return;
      dispatch(truncateMessagesFrom({ threadId, messageId, inclusive: true }));
    },
    [dispatch, threadId]
  );

  /**
   * Record the user's decision on the parked tool call.
   *
   * `optionId` is the core's own `decision` literal (see
   * `APPROVAL_DECISION_OPTIONS`), so it forwards unchanged; the boolean
   * `approved` is only the fallback for a renderer that answered with a plain
   * allow/deny rather than picking one of the declared options.
   *
   * Supplying this at all is load-bearing, not optional: without it the runtime
   * *throws* `Runtime does not support tool approvals.` the moment a decision
   * button is pressed, rather than no-opping.
   */
  const onRespondToToolApproval = useCallback(
    async ({ approvalId, approved, optionId }: RespondToToolApprovalOptions) => {
      const decision = (optionId ?? (approved ? 'approve_once' : 'deny')) as ApprovalDecision;
      await decideApproval(approvalId, decision);
      // Resolve optimistically, exactly as `ApprovalRequestCard` does — the
      // turn-end handlers in `ChatRuntimeProvider` clear it again if the turn
      // is cancelled instead. Only on success: a failed decide leaves the call
      // parked, and dropping the prompt would strand the thread until the
      // gate's TTL with nothing left on screen to retry from.
      if (threadId) dispatch(clearPendingApprovalForThread({ threadId }));
    },
    [dispatch, threadId]
  );

  /**
   * Answer a structured human-input request the run is parked on
   * (`ask_user_clarification`, and any WS-D sub-agent clarification that
   * reuses `ElicitationAdapter`).
   *
   * Every OpenHuman tool is a `type: 'backend'` toolkit entry (`aui/
   * toolkit.tsx`) — the core executes it, never the browser — so there is no
   * "resolve this call with a client-computed result" RPC for
   * `onAddToolResult` to call. What unblocks the parked call is the SAME
   * mechanism `ChatToolParts.tsx`'s `SubagentCall.onAnswer` already uses for
   * the sub-agent case: an ordinary next turn through the registered chat
   * surface, which the core's orchestrator treats as the clarification
   * reply. Supplying this key is what turns `onAddToolResult` into a real
   * capability rather than a throw the moment `ElicitationAdapter`'s Send
   * button is wired to it.
   */
  const onAddToolResult = useCallback(
    async ({ result }: AddToolResultOptions) => {
      const surface = getChatSurface(threadId);
      if (!surface) return;
      const text = typeof result === 'string' ? result : JSON.stringify(result);
      if (text.trim().length === 0) return;
      await surface.send(text);
    },
    [threadId]
  );

  /** Same rationale as `onAddToolResult` above, for a resumed (paused) call. */
  const onResumeToolCall = useCallback(
    async ({ payload }: { toolCallId: string; payload: unknown }) => {
      const surface = getChatSurface(threadId);
      if (!surface) return;
      const text = typeof payload === 'string' ? payload : JSON.stringify(payload);
      if (text.trim().length === 0) return;
      await surface.send(text);
    },
    [threadId]
  );

  // DO NOT add `dictation: new WebSpeechDictationAdapter()` to the `adapters`
  // key below.
  //
  // It is exported by `@assistant-ui/react` at our pinned 0.15.16 and looks like
  // a one-line win: the transcript already renders Dictate / StopDictation
  // behind `s.thread.capabilities.dictation` (`thread.tsx`), and the runtime
  // derives that capability from nothing but the key's presence —
  // `dictation: this._store.adapters?.dictation !== void 0`. Supplying the
  // adapter would light the button up immediately. It would also trap the user.
  //
  // Measured in a WKWebView harness, which is the engine Wry gives us on macOS:
  //
  //   no Info.plist            `webkitSpeechRecognition` present, start() →
  //                            onerror "service-not-allowed"
  //   + NSMicrophoneUsage…     `webkitSpeechRecognition` present, start() →
  //     + NSSpeechRecognition…  NO EVENT AT ALL within 6s
  //
  // The second row is the dangerous one. A detectable error could be caught and
  // the capability withdrawn; silence cannot. The composer would enter
  // `dictation != null`, never leave it, and `StopDictation` would be the only
  // way out — an affordance that looks like it works, unlike the merely inert
  // Edit / BranchPicker / Reload controls gated off in #5897 and #6467.
  //
  // This is NOT "speech is impossible here". The app already ships working
  // speech-to-text by a different route: the `mic-cloud` composer captures with
  // `MediaRecorder` and transcribes through the core's `voice_*` RPC
  // (`features/human/voice/sttClient.ts`), with `voice` in
  // `scripts/ci/product-features.txt`. Its entry point is the "Voice mode" mic
  // button rendered a few pixels from the dictation gate it would duplicate.
  // The desktop `Info.plist` even describes that path — it declares
  // `NSMicrophoneUsageDescription` ("voice dictation") and, tellingly, no
  // `NSSpeechRecognitionUsageDescription`, which only the mobile plist carries.
  //
  // Inline dictation into the composer is still worth having; it should reuse
  // that shipped capture + transcription rather than Web Speech. Tracked
  // separately — it needs a capture lifecycle, interim results, cancellation
  // and error surfacing, none of which this key would provide.
  return useMemo(
    () => ({
      messages: runtimeMessages,
      isRunning,
      isLoading,
      extras,
      // Welcome chips on an empty thread, the core's follow-ups after a settled
      // reply, otherwise empty — see `useWelcomeSuggestions`.
      suggestions,
      // Already `ThreadMessageLike`; the runtime's converter is the identity.
      convertMessage: convertRuntimeMessage,
      onNew,
      onCancel,
      queue,
      onEdit,
      onReload,
      setMessages,
      onDelete,
      onRespondToToolApproval,
      onAddToolResult,
      onResumeToolCall,
      // Read-aloud for a single message. Supplying this is what makes
      // `capabilities.speech` true and the Speak / StopSpeaking controls
      // usable — and it must ship WITH the buttons, never before or after
      // them: `actionBarSpeakDisabled` does not consult the capability (it
      // checks only role and running status), so a Speak button rendered
      // without an adapter is enabled, clickable, and throws "Runtime does not
      // support speech." That is the #5897 defect shape, and Reload already
      // sits in the same trap today.
      // No `dictation` key here — see the Web Speech note above this object.
      adapters: {
        feedback: feedbackAdapter,
        speech: openHumanSpeechAdapter,
        // Native viewport and composer resets need the real conversation identity.
        threadList: { threadId: threadId ?? undefined },
      },
    }),
    [
      threadId,
      runtimeMessages,
      isRunning,
      isLoading,
      extras,
      suggestions,
      feedbackAdapter,
      onNew,
      onCancel,
      queue,
      onEdit,
      onReload,
      setMessages,
      onDelete,
      onRespondToToolApproval,
      onAddToolResult,
      onResumeToolCall,
    ]
  );
}