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
/**
* Provider prerequisites, probed.
*
* `lib/providerPrerequisites.js` decides what a provider is missing given the
* facts; this module supplies the facts and exposes the two shapes PortOS
* needs:
*
* - `getProviderPrerequisiteMap(providers)` — the whole collection's verdict,
* for decorating `GET /api/providers` so the AI Providers page reads the
* same answer the router uses instead of deriving its own.
* - `getProviderPrerequisiteReadinessMap(providers)` — strict tri-state
* readiness for authoritative choices that cannot treat unprobed as ready.
* - `prerequisitesMetForRouting(provider, providers)` — the gate the
* fallback-provider chain in `aiToolkit/providerStatus.js` consults.
*
* The provider-page map and fallback route stay synchronous and read only what
* the runtime probe has already cached. The strict readiness map is async: its
* authoritative callers await a cold/expired probe before publishing choices.
* This keeps `GET /api/providers` off the multi-second `--version` sweep while
* preventing a Persistent Mind turn from receiving an empty, stale catalog.
*
* The result is permissive in three deliberate ways. An un-probed runtime
* yields no finding, so the first pick after boot behaves exactly as it did
* before and the refresh it triggers makes later picks accurate. An EXPIRED
* probe is likewise no answer, so a CLI installed by hand stops being skipped
* within the TTL rather than until the next restart. And routing acts only on
* `ROUTING_BLOCKING_CODES` (the missing binary), never on the credential
* findings the card also shows. Never the other way round: taking a working
* provider out of the fallback chain is worse than the late ENOENT this
* prevents.
*
* No LLM call is made here. Probing a CLI is a `--version` spawn, so this is
* safe under the no-cold-bootstrap policy in AGENTS.md.
*/
import { blocksRouting, describeMissingPrerequisites, providerPrerequisites, providerRuntimeKey } from '../lib/providerPrerequisites.js';
import { PROVIDER_GATEWAYS } from '../lib/providerGateways.js';
import { readCodexRoutingOverride } from '../lib/codexUserConfig.js';
import { inferTuiCommand } from '../lib/providerVendors.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import { applyCredentialBootstrap } from '../lib/credentialBootstrap.js';
import { peekCodexAccountReadiness } from './codexAppServer.js';
import { getCodexOssSupport, peekCodexOssSupport, refreshCodexOssSupportInBackground } from './codexOssSupport.js';
import { codexOssLocalProvider } from '../lib/providerModels.js';
import { delimiter, isAbsolute } from 'path';
import {
getProviderRuntime,
getProviderRuntimeStatus,
getProviderRuntimeStatuses,
peekProviderRuntimeStatuses,
} from './providerRuntimeInstaller.js';
/**
* Per gateway id, does the sibling API provider of that id hold the key an
* OpenCode wrapper inherits at spawn time?
*
* `null` (cannot tell) when there is no provider collection to look in —
* distinct from `false` ("looked, and the sibling has no key"), which is what a
* present-but-keyless or deleted sibling gives. Accepts a raw map (keyed by id)
* or a sanitized array.
*
* A map keyed by gateway id rather than one boolean, so a wrapper is only ever
* judged against ITS OWN sibling — an OrcaRouter key must never satisfy an
* OpenRouter wrapper.
*/
const gatewayKeyState = (providers) => {
if (!providers || typeof providers !== 'object') return null;
const entries = Array.isArray(providers) ? providers : Object.values(providers);
// An EMPTY collection is "nothing loaded", not "the sibling is gone" — the
// same `null`-vs-`false` distinction the whole module runs on.
if (entries.length === 0) return null;
return Object.fromEntries(PROVIDER_GATEWAYS.map((gateway) => {
const sibling = entries.find((p) => p?.id === gateway.id);
return [gateway.id, sibling?.hasApiKey === true || Boolean(sibling?.apiKey)];
}));
};
// Coalesced background refresh — one probe in flight at a time, so a failure
// storm picking a fallback per failed run doesn't fan out a `--version` spawn
// per CLI per run. Errors are logged and swallowed: this runs outside the
// request lifecycle, where an unhandled rejection kills the process.
let refreshInFlight = null;
const refreshRuntimesInBackground = () => {
if (refreshInFlight) return;
refreshInFlight = getProviderRuntimeStatuses()
.catch((err) => console.error(`❌ Provider runtime probe failed: ${err.message}`))
.finally(() => { refreshInFlight = null; });
};
/**
* The cached runtime statuses, plus a background refresh for any runtime this
* batch wanted and the cache had nothing current for.
*
* Scoped to runtimes the table actually covers: a custom command will never
* appear in the probe's answer, so re-requesting it per call would be a refresh
* that can never succeed.
*/
const runtimeSnapshotFor = (keys) => {
const runtimes = peekProviderRuntimeStatuses();
if (keys.some((key) => key && !runtimes[key] && getProviderRuntime(key))) refreshRuntimesInBackground();
return runtimes;
};
// The codex `--oss` verdict for a LOCAL-BACKED codex record, read cache-only.
// Unlike the ChatGPT account read (a heavyweight `codex app-server` spawn, so
// cache-only with no background fill), `codex exec --help` is the same class of
// probe as the runtime `--version` sweep above — so a cold cache kicks the same
// kind of background refresh and the NEXT read is accurate. A record with no
// local backing is never probed: the flags are not among its prerequisites.
const codexOssSupportFor = (provider) => {
if (!codexOssLocalProvider(provider)) return null;
const support = peekCodexOssSupport(provider?.command);
if (!support) refreshCodexOssSupportInBackground(provider?.command);
return support;
};
// CACHE-ONLY (`peek`, never `get`): the Codex ChatGPT readiness a card shows
// must never be the thing that spawns `codex app-server`. A cold cache answers
// `null` — NOT PROBED — so `GET /api/providers` stays a synchronous read and a
// fresh boot starts no auth check (AGENTS.md, no cold-bootstrap provider calls).
// The Providers page's own explicit fetch is what fills it.
const forProvider = (provider, runtimes, gatewayKeySet) => providerPrerequisites(provider, {
// `undefined` (no entry in the map) is NOT PROBED — normalize it to the
// module's `null` sentinel rather than letting it fall through as a value.
runtime: runtimes?.[providerRuntimeKey(provider) ?? ''] ?? null,
gatewayKeySet,
codexAccount: peekCodexAccountReadiness(),
// A short-TTL read of a small local file — no spawn, no network, no LLM.
// Advisory only: it never reaches `missing`, so it cannot change routing or
// a readiness verdict.
codexRouting: readCodexRoutingOverride(),
codexOssSupport: codexOssSupportFor(provider),
});
const effectiveProcessCommand = (provider) => {
const configured = typeof provider?.command === 'string' ? provider.command.trim() : '';
if (configured) return configured;
return provider?.type === 'tui' ? inferTuiCommand(provider?.id) : 'claude';
};
const configuredCommandIsNormalized = (provider) => typeof provider?.command !== 'string'
|| provider.command === ''
|| provider.command === provider.command.trim();
const prerequisiteReadinessFor = (provider, runtimes, gatewayKeySet) => {
const effectiveProvider = provider?.command
? provider
: { ...provider, command: effectiveProcessCommand(provider) };
const runtimeKey = providerRuntimeKey(effectiveProvider);
const runtime = runtimes?.[runtimeKey ?? ''] ?? null;
const { missing } = forProvider(effectiveProvider, runtimes, gatewayKeySet);
if (missing.length > 0) {
return {
status: 'blocked',
reasonCodes: [...new Set(missing.map((entry) => entry.code).filter(Boolean))],
};
}
if (runtimeKey && getProviderRuntime(runtimeKey) && !runtime) {
return { status: 'unknown', reasonCodes: ['runtime-unprobed'] };
}
return { status: 'ready', reasonCodes: [] };
};
const processProviderRuntimeStatus = (provider, { cwd = null, deferCwdDependent = false } = {}) => {
if (provider?.type !== 'cli' && provider?.type !== 'tui') return null;
if (!configuredCommandIsNormalized(provider)) return { installed: false, reasonCode: 'command' };
const harnessCommand = effectiveProcessCommand(provider);
const effectiveProvider = { ...provider, command: harnessCommand };
const runtimeKey = providerRuntimeKey(effectiveProvider);
// A managed runtime installs the HARNESS; a credential-bootstrap provider
// still spawns its bootstrap binary in front of it, so that one is probed
// regardless. The probe targets whatever PortOS actually spawns
// (credentialBootstrap.js): the harness may legitimately be absent from PATH
// when the bootstrap CLI supplies it, and a missing bootstrap binary is the
// ENOENT every run would hit.
const { command } = applyCredentialBootstrap(provider, harnessCommand, []);
if (command === harnessCommand && runtimeKey && getProviderRuntime(runtimeKey)) return null;
const env = { ...process.env, ...(provider?.envVars || {}) };
const explicitRelativeCommand = /[\\/]/.test(command) && !isAbsolute(command);
const relativePathEntry = String(env.PATH || env.Path || '')
.split(delimiter)
.some((entry) => entry === '' || !isAbsolute(entry));
if (deferCwdDependent && !cwd && (explicitRelativeCommand || relativePathEntry)) return null;
return findCommandOnPath(command, { env, ...(cwd ? { cwd } : {}) })
? { installed: true }
: { installed: false };
};
/**
* `{ [providerId]: { met, missing } }` for a whole provider collection.
* @param {Array<object>} providers — raw or sanitized provider records
*/
export function getProviderPrerequisiteMap(providers) {
const list = Array.isArray(providers) ? providers : [];
if (list.length === 0) return {};
const runtimes = runtimeSnapshotFor(list.map(providerRuntimeKey));
const gatewayKeySet = gatewayKeyState(list);
return Object.fromEntries(list.map((provider) => [provider.id, forProvider(provider, runtimes, gatewayKeySet)]));
}
/**
* A strict, non-secret prerequisite verdict for authoritative task choices.
* Unlike routing, this distinguishes a cold/expired runtime probe from a known
* runnable provider so callers that promise a provider choice can fail closed.
* Commands outside the fixed installer table are resolved against the same
* configured PATH/explicit-path rules the child process uses. `candidates`
* limits expensive runtime probes while `providers` remains the full sibling
* set used for inherited credential checks. A catalog may defer cwd-dependent
* commands, then its execution path must call again with the selected app cwd.
*/
export async function getProviderPrerequisiteReadinessMap(providers, {
candidates = providers,
cwd = null,
deferCwdDependent = false,
} = {}) {
const list = Array.isArray(providers) ? providers : [];
const targetList = Array.isArray(candidates) ? candidates : [];
if (list.length === 0 || targetList.length === 0) return {};
const processProviders = targetList.map((provider) => {
const command = effectiveProcessCommand(provider);
return { ...provider, command };
});
const runtimeKeys = processProviders.map(providerRuntimeKey);
const cached = peekProviderRuntimeStatuses();
const missingRuntimeKeys = [...new Set(runtimeKeys
.filter((key) => key && getProviderRuntime(key) && !cached[key]))];
const probed = await Promise.all(missingRuntimeKeys.map(async (key) => [
key,
await getProviderRuntimeStatus(key),
]));
const runtimes = { ...cached, ...Object.fromEntries(probed) };
// An authoritative caller cannot publish a codex-local choice on an unprobed
// flag verdict, so this path AWAITS the `--help` probe the sync path can only
// kick in the background. One probe per distinct command, not per provider.
await Promise.all([...new Set(processProviders
.filter((provider) => codexOssLocalProvider(provider))
.map((provider) => provider.command))]
.map((command) => getCodexOssSupport(command).catch(() => null)));
const gatewayKeySet = gatewayKeyState(list);
return Object.fromEntries(targetList.map((provider, index) => {
const effectiveProvider = processProviders[index];
const customRuntime = processProviderRuntimeStatus(provider, { cwd, deferCwdDependent });
const verdict = customRuntime?.installed === false
? { status: 'blocked', reasonCodes: [customRuntime.reasonCode || 'runtime'] }
: prerequisiteReadinessFor(effectiveProvider, runtimes, gatewayKeySet);
return [provider.id, verdict];
}));
}
/**
* Can this provider run right now, as far as the already-probed facts say?
*
* The gate the fallback chain uses. Returns `true` for anything not KNOWN to be
* un-runnable — see the module note above — and logs the one line that explains
* a skip, which is the whole point of the change: a run that used to die on
* `spawn codex ENOENT` now says which binary is absent and moves on to the next
* candidate.
*
* @param {object} provider
* @param {object|Array} providers — the sibling collection (for inherited keys)
* @returns {boolean}
*/
export function prerequisitesMetForRouting(provider, providers) {
const runtimes = runtimeSnapshotFor([providerRuntimeKey(provider)]);
const { missing } = forProvider(provider, runtimes, gatewayKeyState(providers));
if (!blocksRouting(missing)) return true;
console.warn(`⛔ Skipping fallback ${provider?.id || 'provider'}: ${describeMissingPrerequisites(missing)}`);
return false;
}
/** Test-only: drop the in-flight refresh handle so a suite starts clean. */
export function __resetPrerequisiteRefresh() {
refreshInFlight = null;
}