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
/**
* Harnesses — the coding-agent CLIs/TUIs PortOS drives, seen as things you
* MANAGE rather than as a footnote on a provider card.
*
* A harness is one binary (`opencode`, `kilo`, `openchamber`, `claude`,
* `codex`, `agy`, `grok`, `kimi`, `cursor-agent`) that several provider
* records share. Availability and
* the fixed install/update/remove invocations live in
* `providerRuntimeInstaller.js`; this module answers the two questions that
* need the provider records too:
*
* - **Which providers ride on this harness, and are any of them enabled?**
* Removing `opencode` takes eleven provider records offline at once, and a
* page offering that button has to say so before the click.
* - **Which models does this install of the harness know about?** Every
* vendor that can answer prints it in its own shape
* (`server/lib/harnessOutput.js` parses them), and the answer is only
* useful once it reaches the providers whose picker it feeds.
*
* **The model refresh is deliberately narrow.** It rewrites the `models` list of
* a provider only when that provider draws from the harness's OWN catalog — no
* local-runtime marker (`ollamaBacked`, `vllmBacked`, …) and no `gatewayBacked`.
* An OpenCode wrapper pointed at a local Ollama daemon serves `ollama/*` ids
* that `opencode models` never reports, and overwriting its list with
* `opencode/*` would leave it pointing at models its own config cannot resolve.
*
* **No AI provider call happens here.** `<harness> models` reads the vendor's
* own catalog endpoint or local config; it does not generate anything, and it
* runs only from an explicit click on the Harnesses page — nothing on the boot
* path calls it (root AGENTS.md, AI Provider Usage Policy).
*/
import { isDeepStrictEqual } from 'node:util';
import { prepareCliSpawn } from '../lib/bufferedSpawn.js';
import { hasCredentialBootstrap, resolveCliSpawn } from '../lib/credentialBootstrap.js';
import { commandOutput } from '../lib/commandExists.js';
import { compareHarnessVersions, parseHarnessModels, parseNpmLatestVersion } from '../lib/harnessOutput.js';
import { isDerivedPreset } from '../lib/providerGraphRecords.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import { primeOpencodeCatalogCache } from '../lib/opencodeCatalogCache.js';
import { getOpencodeLocalProviderNamespace, isConfiguredDefaultModel } from '../lib/providerModels.js';
import { providerRuntimeKey } from '../lib/providerPrerequisites.js';
import { createStaleWhileRevalidate } from '../lib/staleWhileRevalidate.js';
import * as providerService from './providers.js';
import { providerGraphEnabled } from './providerGraph.js';
import {
PROVIDER_RUNTIMES,
getProviderRuntime,
getProviderRuntimeStatuses,
getProviderRuntimeStatus,
} from './providerRuntimeInstaller.js';
/**
* A vendor `models` subcommand can reach the vendor's catalog API, so it is
* bounded well above the local `--version` probe but far below an agent run.
*/
const MODELS_PROBE_TIMEOUT_MS = 45_000;
/** `npm view` hits the registry; a slow or offline network must not hang the page. */
const REGISTRY_TIMEOUT_MS = 12_000;
/**
* How long a registry answer stays good. The published version of a CLI changes
* a few times a week at most, and the page re-reads the whole list after every
* action — without this, four visits are four registry round trips per
* npm-backed harness.
*
* `createStaleWhileRevalidate` rather than a hand-rolled TTL map, for the two
* behaviors that matter on a page opened while a laptop is off the network: a
* failed `npm view` keeps the last good answer and backs off instead of
* re-spawning on every load, and a stale-but-real version renders immediately
* while the refresh runs behind it. Keys are the five frozen package names in
* `PROVIDER_RUNTIMES`, so the map needs no eviction.
*/
const latestVersions = createStaleWhileRevalidate({
ttlMs: 6 * 60 * 60 * 1000,
// One offline load must not mean six hours of no registry reads; a minute is
// long enough that a page re-render doesn't re-spawn npm.
failureBackoffMs: 60 * 1000,
});
/**
* The latest published version of an npm-backed harness, or `null` when the
* registry could not be reached or the row is not npm-backed.
*
* `null` is NOT-KNOWN, never "no update": `updateAvailable` below is computed
* only from a definite comparison, so an offline install shows the version it
* has and no false "out of date" badge.
*/
export async function getLatestPublishedVersion(packageName, { fresh = false, run = commandOutput } = {}) {
if (typeof packageName !== 'string' || packageName === '') return null;
return latestVersions.read(packageName, async () => {
// `prepareCliSpawn`, like the version and models probes: `npm` is a `.cmd`
// shim on Windows and `execFile` under `shell: false` targets the literal
// string with no PATHEXT search, so a bare 'npm' never runs there —
// `latestVersion` would be permanently null and the staleness detection this
// page exists for silently dead.
const probe = prepareCliSpawn('npm', ['view', packageName, 'version']);
const stdout = await run(probe.command, probe.args, { timeoutMs: REGISTRY_TIMEOUT_MS });
const version = parseNpmLatestVersion(stdout);
// THROW, don't cache a null: an unreachable registry is a failure the
// backoff should pace, not an answer worth remembering for six hours.
if (!version) throw new Error(`npm view ${packageName} returned no version`);
return version;
}, fresh ? { wait: 'fresh' } : {}).catch(() => null);
}
/** Test-only: drop cached registry answers so the next read re-queries. */
export function __resetLatestVersionCache() {
latestVersions.clear();
}
/**
* Does this provider draw its models from the harness's own catalog?
*
* True only for a plain wrapper: one that resolves to NO backend namespace —
* neither a local runtime nor a hosted gateway. That single check covers both
* carve-outs because `getOpencodeLocalProviderNamespace` resolves the modern
* `gatewayBacked` marker, every legacy per-runtime boolean, AND the legacy
* `orcarouterBacked` alias — so a record written before any of those existed is
* classified correctly with no migration.
*
* **This is a test for the ABSENCE of a marker, which is a class that grows on
* its own** — every un-marked provider joins it. That is deliberate (a record
* with no backend really does run the harness's own models) but it is not
* self-policing, so `harnesses.test.js` walks the shipped seed and pins exactly
* which records a refresh may rewrite. A new seeded provider, or a harness that
* gains `modelsArgs`, has to move that list on purpose. The failure it guards
* is silent in the worst direction: a refresh replacing a working `models` list
* with ids that record's own backend cannot resolve.
*/
export const usesHarnessCatalog = (provider) =>
!getOpencodeLocalProviderNamespace(provider) && !declaresOwnOpencodeProvider(provider);
/**
* The harness runtime whose OWN catalog feeds this provider's models, or
* `null` for a record that keeps a catalog of its own.
*
* The full precondition for {@link refreshHarnessModels} in one place: the
* binary this record launches must know how to enumerate its models
* (`modelsArgs` or `listModels`), and the record must be a plain wrapper
* rather than one pointed at a local daemon or a hosted gateway
* ({@link usesHarnessCatalog}). A custom binary resolves to no runtime row at
* all and answers `null` on the first question.
*
* Lives here rather than beside its caller because the answer is exactly the
* set this refresh may rewrite, and TWO places ask it: the provider card's
* Refresh Models button (`server/routes/providers.js`) and the seed pin in
* this module's tests. Those used to be separate transcriptions, and the route's
* copy asked a third, narrower question — `providerRuntimeKey(provider) ===
* 'opencode'` — so Kilo and Grok cards offered no button for a catalog their
* harness could already print (#7505).
*/
export const harnessCatalogRuntime = (provider) => {
const runtime = getProviderRuntime(providerRuntimeKey(provider));
return (runtime?.modelsArgs || runtime?.listModels) && usesHarnessCatalog(provider) ? runtime : null;
};
/**
* Does this record hand-declare its own OpenCode provider entries?
*
* The `*Backed` / `gatewayBacked` markers above are only ever written by
* PortOS's own editor, so a user who hand-wrote an `OPENCODE_CONFIG_CONTENT`
* with `provider: { myco: … }` and a model list scoped to it is invisible to
* them — and one Refresh click would replace that curated list with the
* harness's own catalog, which their config cannot resolve. A declared provider
* entry IS the backend marker for those records.
*
* The seeded Zen wrappers ship `{"permission":"allow"}` with no `provider` key,
* so they stay in the class. An unparseable config declares nothing.
*/
function declaresOwnOpencodeProvider(provider) {
const stored = provider?.envVars?.OPENCODE_CONFIG_CONTENT;
if (typeof stored !== 'string' || stored === '') return false;
let parsed = null;
try {
parsed = JSON.parse(stored);
} catch {
return false; // unparseable — it declares nothing OpenCode can read either
}
return Object.keys(parsed?.provider || {}).length > 0;
}
/**
* The `vendor/` namespaces a record's stored model ids already use, or an empty
* set when it stores bare ids.
*
* `opencode models` prints every namespace the local OpenCode is authenticated
* for, not just `opencode/*` — so on a box where the user has run
* `opencode auth login <vendor>`, an unfiltered refresh would write
* `anthropic/*` ids into a record named "OpenCode Zen CLI" whose key field is
* `OPENCODE_API_KEY`, and its picker would then offer models that bill a
* different account. A refresh updates a record's catalog; it does not widen
* what that record is for.
*
* Empty for a harness whose ids are bare (agy, grok, cursor) — there is no
* namespace to hold, so nothing is filtered.
*/
const storedNamespaces = (provider) => new Set(
(provider?.models || [])
.filter((id) => typeof id === 'string' && id.includes('/'))
.map((id) => id.slice(0, id.indexOf('/'))),
);
/**
* Every provider record this harness's runtime row actually answers for.
*
* Keyed on `providerRuntimeKey`, the same helper the provider cards use, rather
* than on a bare basename: it deliberately returns `null` for a provider
* configured with an explicit path (`/opt/tools/opencode`) or carrying its own
* `PATH` override, because the PATH-scanning runtime table says nothing about
* those. Attributing them here would inflate the removal warning and — worse —
* let a model refresh rewrite a record from a catalog printed by a DIFFERENT
* binary than the one that record spawns.
*/
const providersForHarness = (providers, runtime) => {
const names = new Set([runtime.id, ...runtime.aliases]);
return providers.filter((provider) => names.has(providerRuntimeKey(provider)));
};
/**
* Every harness, with its runtime status and the providers riding on it.
*
* Publishes counts and ids, never resolved filesystem paths — same rule as
* `GET /api/providers/runtimes`, since a global bin directory embeds the host
* account name.
*/
export async function listHarnesses({ fresh = false, run = commandOutput, ...probeDeps } = {}) {
const [statuses, providers] = await Promise.all([
getProviderRuntimeStatuses({ ...probeDeps, fresh }),
// `listProviders()`, not `getAllProviders()`: that one resolves an ENVELOPE
// (`{ activeProvider, providers: [...] }`), and reaching past it by hand is
// the mistake its own docblock records.
providerService.listProviders(),
]);
return Promise.all(PROVIDER_RUNTIMES.map(async (runtime) => {
const status = statuses[runtime.id] || {};
const linked = providersForHarness(providers, runtime);
// Gated on `installed`, not just on the row being npm-backed: for a harness
// that is not here, the registry answer cannot change anything. Nothing
// renders `latestVersion` for an uninstalled row, and `updateAvailable`
// needs a definite "installed < latest", so a `null` installed version
// already makes it false. Ungated, every shipped-but-uninstalled harness
// cost an `npm view` child plus a registry round trip on each cache-cold
// page load — and the Kilo and OpenChamber rows, which ship disabled on
// every existing install, would have made that the common case.
const latestVersion = runtime.npmPackage && status.installed
? await getLatestPublishedVersion(runtime.npmPackage, { fresh, run })
: null;
return {
...status,
id: runtime.id,
label: runtime.label,
command: runtime.command,
vendor: runtime.vendor,
package: runtime.npmPackage,
latestVersion,
// Only a DEFINITE "installed < latest" is an update prompt. A missing
// version on either side leaves this false, and the row still offers the
// Update button — the user can always ask for one.
updateAvailable: compareHarnessVersions(status.version, latestVersion) === -1,
providers: linked.map((provider) => ({
id: provider.id,
name: provider.name,
type: provider.type,
enabled: provider.enabled === true,
// Which of these the model refresh would actually rewrite.
usesHarnessCatalog: usesHarnessCatalog(provider),
})),
};
}));
}
/**
* The target records bucketed by the credential their probe must run under.
*
* A bootstrap CLI mints auth for ONE account, and `<harness> models` under it
* prints THAT account's catalog — so a probe answers only for the records that
* share its credential. One bucket per distinct `credentialBootstrap`, plus one
* for the records that name none (`probeAs: null`, probed bare).
*
* A target's own credential is the only thing that decides which probe answers
* for it: there is deliberately no rule that degrades a mixed set to one bare
* probe, because "bare" is another account's answer, not a safe default.
*
* Deep equality rather than a serialized key: two records carrying the same
* bootstrap by different key order are one account, not two probes.
*/
const credentialProbeGroups = (targets) => {
const groups = [];
for (const target of targets) {
// The RECORD to probe as, not the bootstrap itself — `resolveCliSpawn`
// takes a provider, and null means "spawn the harness bare".
const probeAs = hasCredentialBootstrap(target) ? target : null;
const bucket = groups.find((group) => isDeepStrictEqual(
group.probeAs?.credentialBootstrap ?? null,
probeAs?.credentialBootstrap ?? null,
));
if (bucket) bucket.targets.push(target);
else groups.push({ probeAs, targets: [target] });
}
return groups;
};
/**
* Write one probe's catalog to the records that probe answers for, and return
* the ids actually rewritten.
*
* A DERIVED preset (#7565) never receives this write directly: its `models`
* IS its service's catalog narrowed, so the next re-derivation would discard
* whatever landed here and the underlying catalog would stay stale forever —
* exactly the bug the Harnesses page's bulk refresh shipped with, because it
* (unlike the provider card's own button, `POST /:id/refresh-models`) has no
* single record to special-case. Refresh the SERVICE instead, once per
* `serviceId` even when several of its presets target this harness, and reuse
* the catalog this call already fetched — passing it back through as an
* injected `harnessModels` answers `refreshServiceCatalog`'s harness strategy
* with no second probe and no re-entry into `refreshHarnessModels` (#8497).
*/
async function applyHarnessCatalog(runtime, models, targets) {
const updated = [];
const derivedProviderIdsByService = new Map();
for (const provider of targets) {
if (isDerivedPreset(provider) && providerGraphEnabled()) {
const ids = derivedProviderIdsByService.get(provider.serviceId) || [];
ids.push(provider.id);
derivedProviderIdsByService.set(provider.serviceId, ids);
continue;
}
// Hold the record's namespace scope (see `storedNamespaces`). A filter that
// matched nothing means the harness no longer lists anything this record is
// for — skip it rather than blanking a working list on that evidence.
const scope = storedNamespaces(provider);
const scoped = scope.size === 0
? models
: models.filter((id) => scope.has(id.slice(0, id.indexOf('/'))));
if (scoped.length === 0) {
console.log(`⏭️ ${runtime.label}: ${provider.id} lists no models in its own namespace — left alone`);
continue;
}
// A `*-configured-default` sentinel is NOT a model the vendor will ever
// print — it is the "send no --model, let the CLI use its own default"
// marker (`resolveCliModel` maps it to null). Dropping it would silently
// repin an agy/grok wrapper onto a concrete model AND remove the option
// from the editor's picker, which renders it from this same list. So it
// survives the rewrite rather than reading as an orphaned id.
const next = [...(provider.models || []).filter(isConfiguredDefaultModel), ...scoped];
// A stored default the harness no longer lists would leave the record
// pinned to a model its own picker cannot show. Keep it when it survived
// the refresh, otherwise fall to the first id (sentinel first when there
// is one, then whatever the vendor listed newest-first).
const defaultModel = next.includes(provider.defaultModel) ? provider.defaultModel : next[0];
// Serialized rather than batched: each write is a read-modify-write of the
// same providers.json, and Promise.all would have them clobber each other.
await providerService.updateProvider(provider.id, { models: next, defaultModel });
updated.push(provider.id);
}
if (derivedProviderIdsByService.size > 0) {
// Deferred: a bulk-refresh path that most calls never touch should not
// drag the whole provider-graph module into every caller of this file
// (server/AGENTS.md "Import scoping").
const { refreshServiceCatalog } = await import('./providerServices.js');
const alreadyListed = async () => ({ ok: true, models });
for (const [serviceId, providerIds] of derivedProviderIdsByService) {
const outcome = await refreshServiceCatalog(serviceId, { harnessModels: alreadyListed }).catch((err) => {
console.error(`❌ ${runtime.label}: could not refresh service "${serviceId}"'s catalog: ${err?.message || err}`);
return null;
});
if (outcome?.service?.catalog?.state !== 'failed') updated.push(...providerIds);
}
}
return updated;
}
/**
* Ask a harness which models it knows about, and write the answer to every
* provider that draws from its own catalog.
*
* One probe per credential, not one per harness — see {@link credentialProbeGroups}:
* the catalog a harness prints is the catalog of the account it ran as, so a
* record whose auth comes from a bootstrap CLI is answered by a probe run
* THROUGH that CLI and never by the ambient one.
*
* Refuses rather than guesses in three cases, each with its own reason string:
* an id not in the table, a harness with no `models` subcommand, and a harness
* that is not installed. A probe that RUNS but parses to nothing also refuses —
* an empty catalog is far more likely to be a vendor output change or a
* signed-out CLI than a real "this harness has zero models", and blanking every
* picker on that guess is worse than reporting the probe as failed. With
* several credentials in play those refusals are per-bucket, so `reason` is
* present on a partial success as well as on `ok: false`.
*
* `providerId` narrows the run to the ONE bucket that record belongs to — what
* a single provider card's button means. Without it a click on a plain wrapper
* would also spawn an unrelated record's bootstrap CLI, minting a credential
* nobody asked for. The Harnesses page button omits it and refreshes them all.
*
* `probeOnly` lists without writing any provider record. A caller already holding
* the provider-graph queue (`refreshServiceCatalog`) must use it: every record
* write awaits a graph reconcile that queues behind that caller and never returns.
*
* @returns {Promise<{ok:boolean, reason?:string, models:string[], updated:string[]}>}
*/
export async function refreshHarnessModels(id, { run = commandOutput, providerId = null, listModels, probeOnly = false, ...probeDeps } = {}) {
const runtime = getProviderRuntime(id);
if (!runtime) return { ok: false, reason: 'Unknown harness.', models: [], updated: [] };
// `listModels` is the alternative to `modelsArgs` for a harness whose
// catalog cannot be read from a single argv + stdout capture (Codex's lives
// behind an `app-server` JSON-RPC handshake — `providerRuntimeInstaller.js`).
// The caller may override it (tests do, to skip the real spawn), but never
// supplies one for a harness whose row declares its own.
const listModelsImpl = listModels || runtime.listModels;
if (!runtime.modelsArgs && !listModelsImpl) {
return {
ok: false,
reason: `${runtime.label} has no command for listing its models, so PortOS cannot refresh them from here.`,
noLister: true,
models: [],
updated: [],
};
}
const findCommand = probeDeps.findCommand || findCommandOnPath;
// The records this refresh will WRITE, resolved before the probe because the
// credential each probe must run under belongs to THEM — not to whichever
// card's button was clicked, and not to the ambient account.
const targets = providersForHarness(await providerService.listProviders(), runtime).filter(usesHarnessCatalog);
const buckets = credentialProbeGroups(targets);
const scoped = providerId ? buckets.filter((b) => b.targets.some((t) => t.id === providerId)) : buckets;
if (providerId && scoped.length === 0) {
return { ok: false, reason: `${providerId} does not draw its models from ${runtime.label}.`, models: [], updated: [] };
}
// No targets at all still runs one bare probe, so the Harnesses page can
// report what the harness lists even with nothing to write it to.
const groups = scoped.length ? scoped : [{ probeAs: null, targets: [] }];
// The SAME injected runner answers the availability probe, so a caller (and a
// test) drives one child-process boundary rather than two. Cache-respecting:
// the page rendered from a probe seconds ago, and re-spawning the binary for
// a 15s worst case ahead of the 45s models probe would double the wait on a
// user-facing button. A binary that broke since then still refuses below.
// Asked only when a BARE probe will run: a credentialed harness is reached
// through its bootstrap CLI and need not be on PATH, so a missing binary is
// that bucket's refusal alone and never the credentialed buckets'.
const notInstalled = `${runtime.label} is not installed on this host.`;
const probesBare = groups.some((group) => !group.probeAs);
const installed = probesBare
? Boolean((await getProviderRuntimeStatus(runtime.id, { ...probeDeps, probeCommand: run }))?.installed)
: false;
// `opencode models` prints from an on-disk catalog OpenCode refreshes on its
// own — silently, and not at all on a host where its fetch fails (see
// `lib/opencodeCatalogCache.js`). Without this the button faithfully re-reads
// a catalog frozen weeks ago and reports success, while the same account on
// another machine lists models this one has never heard of. Best-effort by
// design: a refusal or a failed fetch leaves the probes below unchanged.
// Gated on a probe actually being able to run, so the refusal below doesn't
// first pay for a catalog nothing is going to read.
if (runtime.id === 'opencode' && (installed || groups.some((group) => group.probeAs))) {
const catalog = await primeOpencodeCatalogCache();
console.log(`📚 ${runtime.label} catalog: ${catalog.primed ? 'refreshed' : 'left alone'} — ${catalog.reason}`);
}
// Probe every bucket CONCURRENTLY: each is a distinct child with its own 45s
// cap, so running them in series would make the Harnesses page button cost
// one timeout per credential. Only the WRITES have to be serialized, and they
// stay so in the apply pass below.
const probed = await Promise.all(groups.map(async (group) => {
if (!group.probeAs && !installed) return { group, failure: notInstalled };
// Resolve exactly as the version probe does. An npm-installed harness is a
// `.cmd` shim on Windows, which `execFile` under `shell: false` refuses
// outright — the probe would answer nothing and the page would tell a
// signed-in user to go sign in. A credentialed bucket skips the PATH walk
// (its harness need not be there); `resolveCliSpawn` resolves the bootstrap
// binary's own shim instead.
const resolved = group.probeAs ? null : await findCommand(runtime.command);
if (listModelsImpl) {
// A harness-specific lister owns its own spawn shape (Codex drives a
// JSON-RPC handshake, not a single argv + stdout capture) — hand it the
// same resolved credential/command context `resolveCliSpawn` would use.
// Per-bucket, same as the generic path below: one credential's failure
// must not fail buckets probed under a different one.
const listed = await listModelsImpl({
probeAs: group.probeAs,
resolvedCommand: resolved || runtime.command,
env: process.env,
timeoutMs: MODELS_PROBE_TIMEOUT_MS,
}).catch((err) => ({ error: err?.message || `${runtime.label} failed to list its models.` }));
if (Array.isArray(listed) && listed.length > 0) return { group, listed };
return { group, failure: Array.isArray(listed) ? `${runtime.label} returned no models.` : listed.error };
}
const probe = resolveCliSpawn(group.probeAs, resolved || runtime.command, [...runtime.modelsArgs], process.env);
const listed = parseHarnessModels(runtime.id, await run(probe.command, probe.args, { timeoutMs: MODELS_PROBE_TIMEOUT_MS }));
if (listed.length > 0) return { group, listed };
// Name what RAN, and only send the user to a terminal when a terminal could
// help: a credentialed harness mints its own auth and is not something they
// can sign in to by hand.
const ran = `\`${probe.command} ${probe.args.join(' ')}\` returned no models.`;
return { group, failure: group.probeAs ? ran : `${ran} Sign in to ${runtime.label} in a terminal, then try again.` };
}));
const seen = new Set();
const updated = [];
const failures = [];
for (const { group, listed, failure } of probed) {
if (failure) {
failures.push(failure);
continue;
}
for (const model of listed) seen.add(model);
if (!probeOnly) updated.push(...await applyHarnessCatalog(runtime, listed, group.targets));
}
// `reason` rides along on a PARTIAL success too: with one bucket probed per
// credential, the caller that asked on behalf of ONE record (the provider
// card's button, which checks `updated` for its own id) needs the message
// from the bucket that failed, not silence because another bucket answered.
const reason = failures.length ? failures.join(' ') : undefined;
const models = [...seen];
if (models.length === 0) return { ok: false, reason, models: [], updated: [] };
console.log(`🔄 ${runtime.label}: ${models.length} models → ${updated.length} provider(s)`);
return { ok: true, reason, models, updated };
}