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.9 KB
Raw Blame
/**
 * "Render here, or on a peer?" — one hook behind every interactive render form
 * that can route a job to a federated media provider (#4348).
 *
 * Three surfaces now ask this question (Music Studio, Image Gen, Video Gen).
 * Each one would otherwise have to fetch the peer list, intersect the local
 * allowlist with the peer's advertised capabilities, and decide for itself what
 * "ready" means — three chances to disagree with the server's own admission
 * check. `resolvePeerMediaReadiness` already collapsed the readiness verdict;
 * this collapses the selection state that feeds it.
 *
 * Deliberately does not poll. A capacity window expires on the clock, not on a
 * state change, so no poll interval makes the button's reading trustworthy at
 * the instant of a click — `verify()` re-derives against the clock at submit
 * time instead, which is the only moment that matters. The server re-probes and
 * fail-closes after that regardless.
 */

import { useCallback, useEffect, useMemo, useState } from 'react';
import { getInstances } from '../services/api';
import {
  federatedMediaModelKey,
  federatedMediaModelsForPeer,
  federatedMediaSupports,
  peerMediaProviderConfig,
  peerMediaProviderSnapshot,
  peerModelAcceptsInput,
  resolvePeerMediaReadiness,
  summarizePeerMediaQueue,
} from '../lib/federatedMediaReadiness.js';

// Stable identities so a form that memoizes on these doesn't re-run on every
// render while nothing is selected (the common case).
const NO_PEERS = Object.freeze([]);
const NO_SEGMENTS = Object.freeze([]);

const QUEUE_CLOSED = 'The peer’s shared media queue is not accepting new work right now.';

/**
 * Why this target cannot take the job, or `null` when it can.
 *
 * Mirrors the order `assertFederatedMediaProviderSelection` rejects in, so a
 * form never advertises a target the server is about to refuse. Every branch
 * returns the remedy rather than a bare "not ready".
 *
 * Takes `now` so the submit-time check and the rendered caption run the same
 * gates: the only difference between them is which clock reading they use.
 */
function blockingReason({ peer, models, model, kind, now }) {
  if (!peer) return null;
  const readiness = resolvePeerMediaReadiness(peer, { now });
  if (!readiness.usable) {
    return readiness.help || 'The selected peer is no longer reporting available capacity.';
  }
  if (models.length === 0) {
    // Two different failures, two different remedies: nothing allowlisted here
    // is a local config gap, while an allowlist the peer answers none of means
    // the model was removed or renamed on its side.
    return (peerMediaProviderConfig(peer).models[kind]?.length ?? 0) === 0
      ? `This peer has no allowlisted ${kind} model. Add one on its card under Instances.`
      : `The peer is not advertising any allowlisted ${kind} model right now.`;
  }
  if (readiness.queue?.accepting !== true) return QUEUE_CLOSED;
  if (model?.ready !== true) {
    return model?.unavailableReason || `The selected ${kind} model is not ready on that peer.`;
  }
  return null;
}

/**
 * @param {'audio'|'image'|'video'} kind
 * @returns {{
 *   peers: object[], peer: object|null, peerId: string, setPeerId: (id: string) => void,
 *   models: object[], model: object|null, modelKey: string, setModelKey: (key: string) => void,
 *   isRemote: boolean, readiness: object|null, queueSegments: string[],
 *   supports: (feature: string) => boolean, acceptsInput: (role: string) => boolean,
 *   canSubmit: boolean, blockedReason: string|null,
 *   submissionFields: object|null, verify: () => {ok: boolean, message?: string},
 * }}
 */
export function useFederatedMediaTarget(kind) {
  const [allPeers, setAllPeers] = useState(NO_PEERS);
  const [peerId, setPeerId] = useState('');
  const [modelKey, setModelKey] = useState('');

  // Only the opted-in peers are stored, and only when there is at least one:
  // on an install with no media provider (the common case) the mount fetch then
  // produces NO state update at all, so adding this hook to a form costs it no
  // extra commit. Filtering here rather than in a `useMemo` below is what makes
  // that possible — the raw list is never state, so its identity cannot churn.
  useEffect(() => {
    getInstances({ silent: true })
      .then((data) => {
        if (!Array.isArray(data?.peers)) return;
        const providers = data.peers.filter((candidate) => candidate?.mediaProvider?.enabled === true);
        setAllPeers((current) => (providers.length === 0 && current.length === 0 ? current : providers));
      })
      .catch(() => {});
  }, []);

  // Opting a peer in is a local config fact that survives a failed probe, which
  // is why the stored list is filtered on that alone (above). A peer whose
  // capacity has gone stale stays listed — carrying its own suffix — rather
  // than vanishing from the dropdown with no explanation of where it went.
  const peers = allPeers;
  const peer = useMemo(() => peers.find((candidate) => candidate.id === peerId) || null, [peers, peerId]);
  const models = useMemo(() => federatedMediaModelsForPeer(peer, kind), [peer, kind]);
  // Fall back to the first option for the same reason a native <select> does:
  // that is what the closed dropdown is displaying while `modelKey` is empty or
  // still points at the previous peer's list.
  const model = models.find((entry) => federatedMediaModelKey(entry) === modelKey) || models[0] || null;

  useEffect(() => {
    const next = models[0];
    setModelKey(next ? federatedMediaModelKey(next) : '');
  }, [peer?.id, models]);

  const readiness = useMemo(() => (peer ? resolvePeerMediaReadiness(peer) : null), [peer]);
  // The peer's own status payload, exposed so a form can ask what the peer's
  // BUILD speaks rather than re-deriving it from a per-capability field (#4826).
  // Not memoized: the helper returns the stored reference (or null) rather than
  // building anything, so its identity already tracks `peer`.
  const snapshot = peerMediaProviderSnapshot(peer);
  // Bound to the selected model so callers ask one question instead of two: the
  // root feature list, with the overlap fallback against a peer still on the
  // previous build. Fails closed on an absent status, like every gate here.
  const supports = useCallback(
    (feature) => federatedMediaSupports(snapshot, feature, model),
    [snapshot, model],
  );
  // Bound for the same reason: `peerModelAcceptsInput`'s status argument is
  // optional and omitting it falls silently back to the pre-#4826 reading, so a
  // page that forgot to thread the snapshot would fail OPEN with nothing to
  // catch it. Nothing outside this hook needs to hold the snapshot at all.
  const acceptsInput = useCallback(
    (role) => peerModelAcceptsInput(model, role, snapshot),
    [snapshot, model],
  );
  const queueSegments = useMemo(
    () => (readiness ? summarizePeerMediaQueue(readiness.queue) : NO_SEGMENTS),
    [readiness],
  );
  const blockedReason = useMemo(
    () => blockingReason({ peer, models, model, kind, now: Date.now() }),
    [peer, models, model, kind],
  );

  // The three fields the generate routes read. Built here so a page cannot ship
  // a peer id without the engine that pairs with it — the provider allowlist is
  // keyed on the (engine, modelId) pair, not on the model id alone.
  const submissionFields = useMemo(() => (peer && model ? {
    mediaProviderPeerId: peer.id,
    mediaProviderEngine: model.engine,
    modelId: model.modelId,
  } : null), [peer, model]);

  const verify = useCallback(() => {
    const reason = blockingReason({ peer, models, model, kind, now: Date.now() });
    return reason ? { ok: false, message: reason } : { ok: true };
  }, [peer, models, model, kind]);

  return {
    peers,
    peer,
    peerId,
    setPeerId,
    models,
    model,
    modelKey,
    setModelKey,
    isRemote: Boolean(peer),
    readiness,
    queueSegments,
    supports,
    acceptsInput,
    canSubmit: Boolean(peer) && blockedReason === null,
    blockedReason,
    submissionFields,
    verify,
  };
}