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

6.4 KB
Raw Blame
/**
 * Which provider a burn job spends — shared by every job type.
 *
 * Its own module rather than a sibling job's export: the registry lazy-imports
 * job modules specifically so a status read doesn't drag in a job's heavy
 * dependencies (`agentPrompt.js` pulls the CoS task store and the managed-app
 * store), and importing this helper from there would have made every
 * programmatic job's probe load exactly that.
 */

import { isProcessProvider } from '../../lib/providerTypes.js';
import { getAllProviders } from '../providers.js';
import { commandBasename } from '../../lib/providerModels.js';

/**
 * Is this the "no subscription family" identity?
 *
 * A MANUAL maintenance run (`services/maintenanceRun.js`) may be pinned to a
 * provider that belongs to no family at all — an OpenCode TUI, an Ollama- or
 * LM-Studio-backed wrapper — because the run is a ladder of audits the user
 * asked for, not an attempt to drain a window before it expires. That run
 * constructs this identity explicitly; every other caller hands over a family
 * record from a burn plan, which always names a real family. Recognizing the
 * state HERE (rather than inferring it from a falsy `familyId`) is what keeps
 * the automatic burn sweep out of it: a sweep whose family id somehow came
 * through empty still resolves nothing, exactly as before.
 */
export const isUnfamiliedBurn = (family) => family?.unfamilied === true && !family.id;

/**
 * An agent-capable provider in the burning family. A job's explicit
 * `providerId` wins; otherwise match the family id against the enabled
 * providers, PREFERRING the type named by `prefer` (default `tui`).
 *
 * Preferring the TUI is the point for an AGENT burn: it runs unattended for
 * minutes on the user's own subscription, and a TUI agent is watchable in Active
 * Agents and can be steered mid-run, where a headless CLI run can only be read
 * after it has finished. Most families have both registered (`claude-code` +
 * `claude-code-tui`, `codex` + `codex-tui`, …) and the CLI sorts first, so a
 * plain `find` silently picked the unobservable one every time.
 * `pickScrapeProvider` applies the same preference when reading `/usage`.
 *
 * A PROGRAMMATIC job passes `prefer: 'cli'` instead: it sends one headless
 * prompt through the stage runner, with no agent session to watch or steer, so
 * the TUI's observability buys nothing and its interactive startup is pure
 * overhead. The other type is still accepted as a fallback — a family with only
 * a TUI registered must not silently stop burning.
 *
 * Two exclusions, both about what a burn is FOR — spending a subscription window
 * that would otherwise expire unused:
 * - API-type providers bill per token rather than drawing down a window.
 * - Local-runtime wrappers run a LOCAL model, so there is no window to spend and
 *   burning through one accomplishes nothing. `resolveEnabledFamilies` drops
 *   them from the quota cards for exactly this reason; a `claude-ollama-tui`
 *   would otherwise be a perfectly good match for the `claude` family.
 *
 * `unfamilied` lifts the SECOND exclusion, and only together with an explicit
 * `providerId`. It says the caller is not burning a window at all — it is a
 * manual maintenance run dispatching the ladder onto the one provider the user
 * named — so "this model is local and free" stops being a disqualification and
 * becomes the whole point. The API-type exclusion stays: `isProcessProvider`
 * still has to hold, because the ladder spawns a CLI/TUI agent. A caller that
 * sets the flag without naming a provider resolves nothing, since there is no
 * family left to match against.
 */
export function providerForFamily(providers, { familyId, providerId, prefer = 'tui', unfamilied = false }) {
  const localRuntimeAllowed = unfamilied === true && !familyId && Boolean(providerId);
  const available = (providers || []).filter((provider) =>
    provider?.enabled
    && (localRuntimeAllowed || (provider.ollamaBacked !== true && provider.lmstudioBacked !== true && provider.mtplxBacked !== true && provider.llamaBacked !== true && provider.vllmBacked !== true && provider.sglangBacked !== true))
    && isProcessProvider(provider));
  if (providerId) return available.find((provider) => provider.id === providerId) || null;
  const inFamily = available.filter((provider) => matchesFamily(provider, familyId));
  return inFamily.find((provider) => provider.type === prefer) || inFamily[0] || null;
}

/**
 * Does this provider belong to `familyId`?
 *
 * The BINARY is what actually identifies the family — the provider id is a
 * user-facing label and does not have to contain the family name. Matching on
 * the id alone silently stranded the whole `agy` family: its providers ship as
 * `antigravity-cli` / `antigravity-tui`, neither of which contains "agy", so a
 * configured Antigravity burn plan reported "no enabled CLI/TUI provider" and
 * could never dispatch — while the quota card sat right above it showing a
 * healthy window, because `providerUsage`'s own matcher checks the command.
 *
 * The id substring stays as a fallback for a provider registered under a wrapper
 * script whose basename isn't the family name.
 *
 * Exported because `providerForFamily` deliberately honors an explicit
 * `providerId` pin without re-checking it — a caller that must refuse an
 * out-of-family pin (`quotaBurnInvoke.js`, where the pin would spend the wrong
 * subscription) asks this directly rather than re-deriving the rule.
 */
export const matchesFamily = (provider, familyId) => {
  const needle = String(familyId || '').toLowerCase();
  if (!needle) return false;
  return commandBasename(provider.command) === needle
    || String(provider.id || '').toLowerCase().includes(needle);
};

/**
 * The reason a job reports when its family has nothing it is allowed to spend.
 * An unfamilied run has no family to name, and reaches here only when it was
 * given no provider to pin — so it says that instead.
 */
export const noProviderReason = (family) => (isUnfamiliedBurn(family)
  ? 'a run outside every subscription family must name the provider to use'
  : `no enabled CLI/TUI provider in the ${family?.id} family`);

/** `providerForFamily` against the live provider list. */
export async function resolveBurnProvider({ job, family, prefer }) {
  const result = await getAllProviders();
  return providerForFamily(Array.isArray(result) ? result : result?.providers, {
    familyId: family?.id,
    providerId: job?.providerId || null,
    prefer,
    unfamilied: isUnfamiliedBurn(family),
  });
}