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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { useEffect, useRef, useState } from 'react';
import { safeParseJSON } from '../lib/genUtils';
import { maybeRedirectToLogin } from '../services/apiCore';
/**
* Shared streaming lifecycle for the BYO runtime install modals
* (Flux2InstallModal, RuntimeInstallModal). Both streamed the same shape of
* SSE install log — open on `open`, dispatch `stage`/`log`/`complete`/`error`
* frames, cap the retained log, surface a "connection lost" error when the
* socket drops before `complete`, and auto-scroll the log to the bottom — so
* the plumbing lives here once and each modal keeps only its own chrome.
*
* Frame contract (matches the server emitters in pythonSetup.js /
* setup-image-video.sh):
* { type: 'stage', stage, message? } → advances currentStage + logs it
* { type: 'log', message } → appends a log line
* { type: 'complete', message } → done=true, onComplete(frame), closes
* { type: 'error', message } → error set, closes
*
* Closing the EventSource or aborting the fetch stream (via `close()` on
* cancel, or unmount/disable) is what the server interprets as a cancel — it
* SIGTERMs the underlying pip/bash child.
*
* Deliberately NOT built on `useSseProgress`: this needs kind-tagged log
* accumulation with a cap + optional debounced flush, stage tracking, a
* `streamStarted` signal, `doneRef`-gated connection-lost suppression, an
* `onComplete` callback, and auto-scroll — all beyond what `useSseProgress`
* exposes. Wrapping it would add indirection without removing code.
*
* `flushMs` controls log batching: 0 flushes each line synchronously (fine for
* the structured, bounded FLUX.2 stream); >0 buffers and flushes on a debounce
* so a chatty pip/git stream re-renders the log list at ~1/flushMs Hz instead
* of once per line.
*
* @param {string|null} url - SSE endpoint; null/empty leaves the stream closed.
* @param {object} opts
* @param {boolean} [opts.enabled=true] - when false, the stream stays closed and state resets.
* @param {(frame: object) => void} [opts.onComplete] - fired once on the `complete` frame.
* @param {number} [opts.maxLogLines=500] - cap on retained log lines.
* @param {number} [opts.flushMs=0] - 0 = per-line flush; >0 = debounce window.
* @param {'GET'|'POST'} [opts.method='GET'] - GET uses EventSource; POST uses
* a single fetch-read SSE response for a non-idempotent install.
* @returns {{ logs, currentStage, done, error, streamStarted, logsEndRef, close }}
*/
const DEFAULT_MAX_LOG_LINES = 500;
const CONNECTION_LOST_MESSAGE = 'Connection to installer lost. Restart PortOS or try again.';
export function useInstallStream(url, {
enabled = true,
onComplete,
maxLogLines = DEFAULT_MAX_LOG_LINES,
flushMs = 0,
method = 'GET',
} = {}) {
const [logs, setLogs] = useState([]);
const [currentStage, setCurrentStage] = useState(null);
const [done, setDone] = useState(false);
const [error, setError] = useState(null);
const [streamStarted, setStreamStarted] = useState(false);
const logsEndRef = useRef(null);
const esRef = useRef(null);
const abortRef = useRef(null);
// Mirror `done` into a ref so es.onerror reads the latest value — the effect
// closure captures the initial done=false and never refreshes, so without
// this the modal can flash "Connection lost" when the server cleanly closes
// the socket right after sending `complete`.
const doneRef = useRef(false);
// Stash onComplete in a ref so the EventSource effect doesn't tear down the
// SSE connection on every parent re-render with a fresh inline arrow.
const onCompleteRef = useRef(onComplete);
useEffect(() => { onCompleteRef.current = onComplete; }, [onComplete]);
// Buffer incoming lines and flush them together. Pip and git can each emit
// hundreds of lines/sec; per-line setState would re-render the whole log list
// on every line.
const pendingRef = useRef([]);
const flushTimerRef = useRef(null);
const flush = () => {
flushTimerRef.current = null;
if (pendingRef.current.length === 0) return;
const incoming = pendingRef.current;
pendingRef.current = [];
setLogs((prev) => {
const combined = [...prev, ...incoming];
return combined.length > maxLogLines ? combined.slice(-maxLogLines) : combined;
});
};
const appendLog = (entry) => {
pendingRef.current.push(entry);
if (flushMs > 0) {
if (flushTimerRef.current == null) flushTimerRef.current = setTimeout(flush, flushMs);
} else {
flush();
}
};
useEffect(() => {
const clearFlush = () => {
if (flushTimerRef.current != null) { clearTimeout(flushTimerRef.current); flushTimerRef.current = null; }
// Drop any un-flushed lines too: with flushMs > 0 a superseded stream can
// leave buffered lines behind, and the next stream's flush would render
// them into its own log.
pendingRef.current = [];
};
const closeStream = () => {
if (esRef.current) { esRef.current.close(); esRef.current = null; }
if (abortRef.current) { abortRef.current.abort(); abortRef.current = null; }
};
if (!enabled || !url) {
setLogs([]);
setCurrentStage(null);
setDone(false);
doneRef.current = false;
setError(null);
setStreamStarted(false);
clearFlush();
closeStream();
return undefined;
}
// Reset state on every (re)subscribe, not just on disable — a url change
// while enabled (e.g. a retry that bumps an attempt counter) must start
// the new stream clean, or a prior run's `error`/`done`/log lines leak
// into it (wedging consumers that derive "installing" from those flags).
setLogs([]);
setCurrentStage(null);
setDone(false);
doneRef.current = false;
setError(null);
setStreamStarted(true);
const handleMessage = (msg, closeThis) => {
if (msg.type === 'stage') {
setCurrentStage(msg.stage);
appendLog({ kind: 'stage', text: msg.message || msg.stage });
} else if (msg.type === 'log') {
appendLog({ kind: 'log', text: msg.message });
} else if (msg.type === 'complete') {
setDone(true);
doneRef.current = true;
appendLog({ kind: 'success', text: msg.message });
flush();
closeThis();
onCompleteRef.current?.(msg);
} else if (msg.type === 'error') {
const message = msg.message || 'Installer failed.';
setError(message);
appendLog({ kind: 'error', text: message });
flush();
closeThis();
}
};
// A global CLI install changes host state. EventSource transparently
// reconnects after a transport drop, which would replay a non-idempotent
// request. POST callers use exactly one fetch stream instead. Delay the
// fetch one task turn so React's development-only strict-effect probe
// tears down before any request leaves the browser; otherwise its setup →
// cleanup → setup cycle can briefly start and cancel the same install.
if (String(method).toUpperCase() === 'POST') {
const controller = new AbortController();
abortRef.current = controller;
const isCurrent = () => abortRef.current === controller && !controller.signal.aborted;
const closeThis = () => {
if (abortRef.current === controller) abortRef.current = null;
controller.abort();
};
const startTimer = setTimeout(() => {
if (!isCurrent()) return;
const run = async () => {
let reader = null;
try {
const response = await fetch(url, { method: 'POST', signal: controller.signal });
if (!response.ok || !response.body?.getReader) {
const err = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
maybeRedirectToLogin(response, err);
throw new Error(err.error || `HTTP ${response.status}`);
}
reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
let terminalFrame = false;
const consumeFrame = (frame) => {
const dataLine = frame.split(/\r?\n/).find(line => line.startsWith('data:'));
if (!dataLine || !isCurrent()) return;
const msg = safeParseJSON(dataLine.slice('data:'.length).trim());
if (!msg) return;
terminalFrame ||= msg.type === 'complete' || msg.type === 'error';
handleMessage(msg, closeThis);
};
for (;;) {
const { done: streamDone, value } = await reader.read();
if (streamDone) break;
buffer += decoder.decode(value, { stream: true });
const frames = buffer.split(/\r?\n\r?\n/);
buffer = frames.pop() || '';
for (const frame of frames) consumeFrame(frame);
if (!isCurrent()) break;
}
buffer += decoder.decode();
if (isCurrent() && buffer.trim()) consumeFrame(buffer);
if (isCurrent() && !terminalFrame && !doneRef.current) {
setError((prev) => prev ?? CONNECTION_LOST_MESSAGE);
}
} catch (err) {
if (isCurrent()) setError((prev) => prev ?? (err?.message || CONNECTION_LOST_MESSAGE));
} finally {
if (reader) await reader.cancel().catch(() => {});
if (abortRef.current === controller) abortRef.current = null;
}
};
run();
}, 0);
return () => {
clearTimeout(startTimer);
clearFlush();
closeThis();
};
}
const es = new EventSource(url);
esRef.current = es;
// Close the instance that fired this event, not whatever esRef currently
// points at — so a late callback from a superseded stream can't tear down
// (or null out) a newer one after a url/enabled change.
const closeThis = () => { if (esRef.current === es) esRef.current = null; es.close(); };
es.onmessage = (ev) => {
if (esRef.current !== es) return; // stale callback from a superseded stream
const msg = safeParseJSON(ev.data);
if (!msg) return;
handleMessage(msg, closeThis);
};
es.onerror = () => {
if (esRef.current !== es) return; // stale callback from a superseded stream
// Network drop or server killed the stream. If we already saw `complete`
// this is harmless; otherwise surface it so the user isn't stuck on a
// forever-spinning modal.
setError((prev) => prev ?? (doneRef.current ? null : CONNECTION_LOST_MESSAGE));
closeThis();
};
return () => {
clearFlush();
closeThis();
};
// onComplete intentionally excluded — it lives in onCompleteRef.
}, [url, enabled, maxLogLines, flushMs, method]);
// Auto-scroll on every new line. behavior:'auto' (instant) avoids queueing
// hundreds of smooth-scroll animations during a chatty install.
useEffect(() => {
if (logsEndRef.current) {
logsEndRef.current.scrollIntoView({ behavior: 'auto', block: 'end' });
}
}, [logs.length]);
const close = () => {
if (esRef.current) { esRef.current.close(); esRef.current = null; }
if (abortRef.current) { abortRef.current.abort(); abortRef.current = null; }
};
return { logs, currentStage, done, error, streamStarted, logsEndRef, close };
}