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

7.1 KB
Raw Blame
import { useEffect, useMemo, useRef, useState } from 'react';
import toast from '../components/ui/Toast';
import { useSseProgress, isTerminalSseFrame } from './useSseProgress.js';
import useMounted from './useMounted.js';

const defaultReadPercent = (frame) => frame.percent;
const IDLE_PROGRESS = Object.freeze({ percent: 0, stage: null });

/**
 * One single-slot SSE job: kickoff, captured target, progress and terminal
 * recovery. Reserve the slot synchronously, including the preparation window
 * before the server returns a jobId. Each independent surface owns one slot.
 *
 * Options:
 * - `startRequest(startArg)` → resolves `{ jobId }` — the feature's kickoff call.
 * - `eventsUrl(jobId)` / `cancelRequest(jobId, { silent })` — SSE URL + cancel call.
 * - `onSettled(reason, context)` — refresh saved state on success, failure, cancellation or disconnect.
 * - `onComplete(frame, context)` — fires on the terminal `complete` frame.
 * - `context` (the second `start` arg, or the start arg itself when omitted) is
 *   captured and exposed immediately at kickoff, including while `pending`.
 * - `trimStartArg` — trims URL input and ignores an empty start when true.
 * - `readPercent(frame)` — optional projection to 0–100 (default: frame.percent).
 *   Missing/non-finite values preserve the last reported progress.
 * - `successToast(frame)` — optional; toast.success its return when truthy.
 * - `errorFallback` / `canceledMessage` / `lostConnectionMessage` /
 *   `startErrorFallback` — the per-feature toast copy.
 * - `onErrorFrame(frame, context)` → return true to suppress the error toast.
 * - `onKickoffError(err, startArg)` → return true to suppress the kickoff toast.
 * - `onKickoffSuccess(jobId, startArg)` — fires when the kickoff resolves.
 *
 * `attach(jobId, context)` adopts a job some OTHER request already started
 * (e.g. a workflow step whose response carried the jobId) into the idle slot,
 * so it gets the same progress, terminal and cancel handling. Returns false
 * when the slot is busy.
 */
export default function useSseJobSlot({
  startRequest,
  eventsUrl,
  cancelRequest,
  onComplete,
  trimStartArg = false,
  readPercent = defaultReadPercent,
  successToast,
  errorFallback = 'Job failed',
  canceledMessage = 'Job cancelled',
  lostConnectionMessage = 'Lost connection to the job',
  startErrorFallback = 'Failed to start the job',
  onErrorFrame,
  onKickoffError,
  onKickoffSuccess,
  onSettled,
} = {}) {
  // jobId is null during preparation; context already owns the target then.
  const [job, setJob] = useState(null);
  const slotRef = useRef(null);
  const mounted = useMounted();
  useEffect(() => () => { slotRef.current = null; }, []);
  const jobUrl = job?.jobId ? eventsUrl(job.jobId) : null;
  // Latest-only consumer: no history, so each frame costs one render.
  const sse = useSseProgress(jobUrl, { maxFrames: 0 });
  const latest = sse.latest;
  const percent = latest ? readPercent(latest) : undefined;

  const clearJob = () => {
    slotRef.current = null;
    setJob(null);
  };

  // Progress is folded from `latest` during render (carried in a ref) rather
  // than through a state-setting effect, so a frame costs one render, not two.
  // Sparse metadata/warning frames preserve progress. A known mismatched URL
  // belongs to an older stream; absent URL identity remains tolerated for the
  // existing SSE test seams. The fold is idempotent per frame, so StrictMode's
  // double memo invocation lands on the same value.
  const progressRef = useRef(IDLE_PROGRESS);
  const progress = useMemo(() => {
    if (!job?.jobId || !latest) return progressRef.current;
    if (sse.latestUrl && sse.latestUrl !== jobUrl) return progressRef.current;
    const prev = progressRef.current;
    const next = {
      percent: Number.isFinite(percent) ? Math.round(percent) : prev.percent,
      stage: typeof latest.stage === 'string' && latest.stage ? latest.stage : prev.stage,
    };
    progressRef.current = next;
    return next;
  }, [latest, job, jobUrl, sse.latestUrl, percent]);

  useEffect(() => {
    if (!job?.jobId || !latest) return;
    if (sse.latestUrl && sse.latestUrl !== jobUrl) return;
    if (['complete', 'error', 'canceled', 'cancelled'].includes(latest.type)) onSettled?.(latest.type, job.context);
    if (latest.type === 'complete') {
      clearJob();
      // Completion follow-ups may throw synchronously or return a rejected
      // promise. Own both failures after releasing the slot.
      const finish = async () => {
        try {
          await onComplete?.(latest, job.context);
          const msg = successToast?.(latest);
          if (msg) toast.success(msg);
        } catch (err) {
          console.error(`❌ Job completion follow-up failed: ${err?.message || 'Unknown error'}`);
          toast.error('Finished, but the page could not update — reload to see the result');
        }
      };
      void finish();
    } else if (latest.type === 'error') {
      clearJob();
      if (!onErrorFrame?.(latest, job.context)) {
        toast.error(latest.error || errorFallback);
      }
    } else if (latest.type === 'canceled' || latest.type === 'cancelled') {
      clearJob();
      toast.info(canceledMessage);
    }
  }, [latest, sse.latestUrl]);

  useEffect(() => {
    if (job?.jobId && sse.closed && !isTerminalSseFrame(latest)) {
      if (sse.latestUrl && sse.latestUrl !== jobUrl) return;
      const context = job.context;
      clearJob();
      onSettled?.('disconnected', context);
      toast.info(lostConnectionMessage);
    }
  }, [sse.closed]);

  const start = (startArg, context) => {
    const arg = trimStartArg ? (startArg ?? '').trim() : startArg;
    if (trimStartArg && !arg) return;
    if (!mounted.current || slotRef.current) return;
    const slot = { jobId: null, context: context === undefined ? arg : context };
    slotRef.current = slot;
    progressRef.current = IDLE_PROGRESS;
    setJob(slot);
    const isCurrent = () => mounted.current && slotRef.current === slot;
    startRequest(arg)
      .then(({ jobId }) => {
        if (!isCurrent()) return;
        onKickoffSuccess?.(jobId, arg);
        setJob({ jobId, context: slot.context });
      })
      .catch((err) => {
        if (!isCurrent()) return;
        clearJob();
        if (onKickoffError?.(err, arg)) return;
        toast.error(err?.message || startErrorFallback);
      });
  };

  const attach = (jobId, context) => {
    if (!jobId || !mounted.current || slotRef.current) return false;
    const slot = { jobId, context: context ?? null };
    slotRef.current = slot;
    progressRef.current = IDLE_PROGRESS;
    setJob(slot);
    return true;
  };

  const cancel = () => {
    if (!mounted.current || !job?.jobId) return;
    cancelRequest(job.jobId, { silent: true }).catch(() => {});
  };

  return {
    active: !!job,
    connected: sse.isOpen,
    pending: !!job && !job.jobId,
    jobId: job?.jobId ?? null,
    percent: progress.percent,
    stage: progress.stage,
    // Most recent frame for THIS job (null until one arrives) — for features
    // that render counts the percent projection can't carry.
    latest: job?.jobId ? latest : null,
    context: job?.context ?? null,
    start,
    attach,
    cancel,
  };
}