Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

12.0 KB
Raw Blame
import { useCallback, useEffect, useRef, useState } from 'react';
import toast from '../components/ui/Toast';
import {
  createOutboxEntry, discardOutboxEntry, listOutboxEntries, sendOutboxEntry, reconcileOutboxEntry,
} from '../services/apiBeeper';
import useBeeperRealtime from './useBeeperRealtime';
import useMounted from './useMounted';

/**
 * The Beeper composer's send lifecycle (#36, decided on #8).
 *
 * Two server steps, deliberately: `POST /api/beeper/outbox` writes the durable
 * row from the typed body, then `POST /api/beeper/outbox/:id/send` performs the
 * send. This hook drives both from one `submit(body)` so the composer stays a
 * text box with a button, while the row exists on disk before anything is sent.
 *
 * Three rules it exists to keep:
 *
 *  - **A send that touched the wire never retries in place.** Beeper has no
 *    idempotency key on send, so retrying an attempt that reached
 *    `sendMessage` is a second real message. A `failed` row stays failed and
 *    visible in `entries`; sending again means composing again, via
 *    `submit()`, which creates a NEW row. `retry()` is the narrow exception:
 *    it only ever re-dispatches a row still `approved` — refused before the
 *    server could claim it (`OUTBOX_BREAKER_OPEN` is the practical case) —
 *    where nothing has touched the wire yet, so re-sending the same row is
 *    exactly as safe as sending it the first time.
 *  - **First contact confirms inline.** The server refuses the first outbound
 *    message to a conversation with `FIRST_CONTACT_CONFIRMATION_REQUIRED`;
 *    that answer is surfaced as `confirmation`, NOT as an error toast, so the
 *    composer can render an `InlineConfirmRow` (never `window.confirm`, which
 *    client conventions forbid). `confirmAndSend()` re-sends the SAME row with
 *    the flag — it does not create a second one.
 *  - **Confirmation is the server's business.** A sent row sits in
 *    `awaiting-confirmation` until the socket or the 30s fallback resolves it;
 *    this hook just refetches when an invalidation says the mirror moved.
 *
 * @param {string|null} conversationId the open conversation (a route param).
 * @param {object} [options]
 * @param {(conversationId: string, body: string) => void} [options.onSent]
 *   Called after a composer send is accepted, with its original conversation
 *   and text so navigation or a newer edit cannot clear an unrelated draft. A send
 *   whose text came from somewhere else — a failed row's Retry, which passes
 *   `submit(body, { clearsDraft: false })`, or `retry()` re-dispatching an
 *   existing row — never fires it: the draft may hold a newer message the
 *   user has typed since, and clearing it would discard text that was never
 *   sent.
 */
export default function useBeeperOutbox(conversationId, { onSent } = {}) {
  const [entries, setEntries] = useState([]);
  const [sending, setSending] = useState(false);
  // `null` = no confirmation pending. When set it carries the entry the user is
  // being asked about, so confirming re-sends that row rather than a new one.
  const [confirmation, setConfirmation] = useState(null);
  const [error, setError] = useState(null);
  const mountedRef = useMounted();
  const onSentRef = useRef(onSent);
  onSentRef.current = onSent;
  const scopeRef = useRef({ conversationId, refreshGeneration: 0 });
  if (scopeRef.current.conversationId !== conversationId) {
    scopeRef.current = { conversationId, refreshGeneration: 0 };
  }
  const scope = scopeRef.current;

  const refresh = useCallback(async () => {
    if (!conversationId) {
      setEntries([]);
      return;
    }
    const generation = ++scope.refreshGeneration;
    const result = await listOutboxEntries(conversationId, { silent: true }).catch(() => null);
    if (!mountedRef.current || scopeRef.current !== scope || generation !== scope.refreshGeneration) return;
    // A failed GET leaves the list alone rather than blanking it — absent is
    // not the same as empty, and an emptied list would hide a failed send.
    if (Array.isArray(result?.entries)) setEntries(result.entries);
  }, [conversationId, scope]);

  useEffect(() => {
    setEntries([]);
    setSending(false);
    setConfirmation(null);
    setError(null);
    refresh();
  }, [refresh]);

  // A send confirms server-side (socket `message.upserted`, or the 30s GET
  // fallback), and the server re-broadcasts an id-only invalidation when it
  // lands. That is the cue to refetch the outbox — no polling, no timers here.
  const awaitingRef = useRef(false);
  awaitingRef.current = entries.some((entry) => entry.state === 'awaiting-confirmation' || entry.state === 'sending');
  useBeeperRealtime({
    onInvalidate: (frame) => {
      if (!['message.upserted', 'outbox.updated'].includes(frame?.kind) || !awaitingRef.current) return;
      refresh();
    },
  });

  /**
   * Send one existing row. Shared by the first attempt and the confirmation.
   * @param {object} [options]
   * @param {boolean} [options.confirmFirstContact=false] Whether the human confirmed a first-contact send.
   * @param {boolean} [options.clearsDraft=false] Whether this send's text is the composer's current draft.
   */
  const dispatch = useCallback(async (entry, { confirmFirstContact = false, clearsDraft = false } = {}) => {
    setSending(true);
    const [sent, err] = await sendOutboxEntry(entry.id, { confirmFirstContact }, { silent: true })
      .then((value) => [value, null])
      .catch((sendError) => [null, sendError]);
    if (!mountedRef.current) return false;
    if (!err && clearsDraft) onSentRef.current?.(conversationId, entry.body);
    if (scopeRef.current !== scope) return !err;
    setSending(false);

    if (err?.code === 'FIRST_CONTACT_CONFIRMATION_REQUIRED') {
      // Not an error state: a question. The composer renders it inline.
      // `clearsDraft` rides along so answering "Send anyway" keeps whatever
      // this attempt's origin decided, rather than defaulting back to the
      // composer's.
      setConfirmation({ entry, message: err.message, clearsDraft });
      return false;
    }
    setConfirmation(null);
    if (err) {
      setError(err.message || 'Could not send the message');
      toast.error(err.message || 'Could not send the message');
      await refresh();
      return false;
    }
    setError(null);
    setEntries((prev) => [sent, ...prev.filter((row) => row.id !== sent.id)]);
    return true;
  }, [refresh, conversationId, scope]);

  // `sending` is React state, so it only reflects a send that has already
  // re-rendered. Two `submit()` calls inside ONE render — a double-fired Send
  // button, an Enter keydown racing the click — both read it as false, both
  // create a durable row, and both dispatch a real message. Beeper has no
  // idempotency key, so that second message is unrecallable. This ref latches
  // synchronously, before the first await, and is the actual guard; `sending`
  // stays as the RENDER signal it already is.
  const submittingRef = useRef(false);

  /**
   * Step one + step two, from the composer's Send action.
   *
   * `clearsDraft` defaults to true because the composer is the ordinary
   * caller. The one caller that passes false is a `failed` row's Retry, which
   * composes a new entry from that ROW's text — clearing the composer there
   * would throw away a message typed since the failure.
   */
  const submit = useCallback(async (body, { clearsDraft = true } = {}) => {
    const text = typeof body === 'string' ? body.trim() : '';
    if (!conversationId || !text || sending || submittingRef.current) return false;
    submittingRef.current = true;
    try {
      setError(null);
      const [entry, err] = await createOutboxEntry(conversationId, text, { silent: true })
        .then((value) => [value, null])
        .catch((createError) => [null, createError]);
      if (!mountedRef.current || scopeRef.current !== scope) return false;
      if (err) {
        setError(err.message || 'Could not queue the message');
        toast.error(err.message || 'Could not queue the message');
        return false;
      }
      setEntries((prev) => [entry, ...prev]);
      // Awaited into a local rather than returned bare: `return dispatch(...)`
      // would run the `finally` and drop the latch before the send resolved.
      const dispatched = await dispatch(entry, { clearsDraft });
      return dispatched;
    } finally {
      // `finally`, not a catch: nothing is swallowed, but the latch must not
      // survive a throw or the composer is wedged shut for the session.
      submittingRef.current = false;
    }
  }, [conversationId, dispatch, sending, scope]);

  /** The inline confirmation's "Send" — the same row, now explicitly confirmed. */
  const confirmAndSend = useCallback(async () => {
    if (!confirmation?.entry) return false;
    return dispatch(confirmation.entry, {
      confirmFirstContact: true,
      clearsDraft: confirmation.clearsDraft === true,
    });
  }, [confirmation, dispatch]);

  /**
   * Discard a row the human has given up on. Legal only while the row is
   * still `approved` — the server enforces that, and this mirrors it exactly
   * — because that is the only state meaning nothing has POSTed to Beeper
   * for it yet. Leaving an unwanted `approved` row behind was the original
   * design, but the composer had no way to render or dismiss it distinctly
   * from "sending": it fell into `OutboxRow`'s default branch and rendered
   * as a permanent "Sending…" bubble, including across a reload, because
   * `GET /outbox` returns every approved row (#53's Cancel fix; #60 blocker
   * 1 closed the other way in — a refused send, e.g. `OUTBOX_BREAKER_OPEN`
   * — into the same phantom). A discard failure (e.g. a network hiccup)
   * refetches instead of silently dropping the row from just the client's
   * view — the truth is the server's.
   */
  const discardEntry = useCallback(async (entry) => {
    if (!entry) return;
    const [, err] = await discardOutboxEntry(entry.id, { silent: true })
      .then(() => [true, null])
      .catch((discardError) => [null, discardError]);
    if (!mountedRef.current || scopeRef.current !== scope) return;
    if (err) {
      toast.error(err.message || 'Could not discard the message');
      await refresh();
      return;
    }
    setEntries((prev) => prev.filter((row) => row.id !== entry.id));
  }, [refresh, scope]);

  /** The inline confirmation's "Cancel" — see `discardEntry`. */
  const cancelConfirmation = useCallback(async () => {
    const entry = confirmation?.entry;
    setConfirmation(null);
    if (!entry) return;
    await discardEntry(entry);
  }, [confirmation, discardEntry]);

  /**
   * Retry a row that never reached Beeper — a stalled `approved` entry
   * refused before the server could claim it (`OUTBOX_BREAKER_OPEN` is the
   * practical case, #60 blocker 1). Re-dispatches the SAME row rather than
   * composing a new one: nothing has touched the wire for it, so this is as
   * safe as sending it the first time, and it means a stuck breaker does not
   * manufacture a fresh phantom on every click the way retrying via `submit`
   * would. It never clears the composer: the row's text is not the draft.
   */
  const retry = useCallback((entry) => dispatch(entry), [dispatch]);

  /** Give up on a stalled `approved` row outright — see `discardEntry`. */
  const dismiss = useCallback((entry) => discardEntry(entry), [discardEntry]);

  const reconcile = useCallback(async (entry) => {
    const generation = ++scope.refreshGeneration;
    const updated = await reconcileOutboxEntry(entry.id, { silent: true }).catch((err) => {
      if (mountedRef.current && scopeRef.current === scope) toast.error(err.message || 'Could not check delivery');
      return null;
    });
    if (!updated || !mountedRef.current || scopeRef.current !== scope || generation !== scope.refreshGeneration) return;
    setEntries((prev) => prev.map((row) => row.id === updated.id ? updated : row));
  }, [scope]);

  return {
    entries,
    sending,
    error,
    confirmation,
    submit,
    confirmAndSend,
    cancelConfirmation,
    retry,
    dismiss,
    reconcile,
    refresh,
  };
}