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
/**
* `SERVICE_DEFINITIONS` — every backend a harness can be pointed at, as ONE
* table (#7562, the first slice of #7561).
*
* Before this file, "which backends exist?" was answered by four registries
* that never met: `PROVIDER_GATEWAYS` (hosted OpenAI-compatible gateways),
* `LOCAL_RUNTIMES` (daemons on this machine), the AI rows of
* `credentialRegistry.js` (vendor API keys), and the implicit vendor cloud a
* subscription harness signs into. A service is any of those, in one shape, so
* a harness's capability bindings (`providerHarnesses.js`) can name a service
* by id and `materializeRoute` (`providerRouteRecipes.js`) can turn a
* (harness, service) pair into an executable record from data alone.
*
* Three families, one shape (epic D2):
* - `subscription` — auth lives inside the harness (claude.ai login, the
* ChatGPT/Codex login, Google for Antigravity, xAI for Grok Build, Cursor).
* PortOS holds no key and the service is reachable ONLY by its own program
* (`harnessOnly`).
* - `api-key` — a hosted API PortOS holds a key for. Some are also hosted
* GATEWAYS an OpenCode wrapper can front-end; those rows carry `gateway`,
* and {@link PROVIDER_GATEWAYS} in `providerGateways.js` is DERIVED from
* them, so a gateway is one row here and nowhere else.
* - `local` — a daemon on this machine, one row per `LOCAL_RUNTIMES` id
* (`serviceDefinitions.test.js` pins the two id sets together). The daemon's
* endpoint is configured per install, so these rows declare WHICH transports
* the runtime speaks and no default URL: an instance must name its endpoint,
* exactly as `providerConnectionProfile` already demands of a local record.
* - `fleet` — a peer's OpenAI-compatible gateway.
*
* A DEFINITION is code; an INSTANCE (a definition + plan + credential + catalog)
* is a later slice's persisted row. {@link resolveServiceInstance} is the pure
* shape both halves agree on until then.
*
* Dependency-light on purpose: imports nothing, so `providerGateways.js` (which
* `providerModels.js` and the browser reach) can derive its table from here
* without growing its closure. Default base URLs are literal strings for the
* same reason — the local-runtime defaults, which need `PORTS`, stay in
* `LOCAL_RUNTIMES`.
*/
/** The four families a definition belongs to. */
export const SERVICE_FAMILIES = Object.freeze(['subscription', 'api-key', 'local', 'fleet']);
/**
* User-declared plans. `free` / `paid` are the two tiers a metered API sells;
* `subscription` is a login the harness owns; `local` is a daemon that bills
* nobody. A definition lists the plans it can honestly be instantiated under.
*/
export const SERVICE_PLANS = Object.freeze(['free', 'paid', 'subscription', 'local']);
/**
* How an instance's model catalog is learned. `probe` — GET `/models` on the
* endpoint; `daemon` — ask the local runtime manager; `harness` — ask the
* program that signs in (`claude`, `codex`, `agy` list their own catalogs);
* `static` — nothing to ask, the instance's declared list is the catalog.
*/
export const CATALOG_STRATEGIES = Object.freeze(['probe', 'daemon', 'harness', 'static']);
/**
* How an instance authenticates (#7563). Only `stored` holds a secret on the
* row; `env` reads the definition's conventional variable, `cli-login` is
* the harness's own sign-in, and `bootstrap` means a launch wrapper supplies
* the key at spawn.
*/
export const SERVICE_CREDENTIAL_VIAS = Object.freeze(['stored', 'env', 'cli-login', 'bootstrap']);
const METERED = Object.freeze(['free', 'paid']);
const PAID = Object.freeze(['paid']);
const SUBSCRIPTION = Object.freeze(['subscription']);
const LOCAL = Object.freeze(['local']);
/** A model-id suffix filter for the one plan a vendor marks in the id itself. */
const suffixPlanFilter = (suffix, { alsoFree = [] } = {}) => (plan, models) => (
plan === 'free'
? models.map(String).filter((id) => id.endsWith(suffix) || alsoFree.includes(id.split('/').pop()))
: models
);
const definition = ({ transports = {}, credential = {}, catalog, ...row }) => Object.freeze({
...row,
transports: Object.freeze(Object.fromEntries(
Object.entries(transports).map(([protocol, transport]) => [protocol, Object.freeze({ defaultBaseUrl: null, ...transport })]),
)),
credential: Object.freeze({ envVars: Object.freeze([]), ...credential }),
catalog: Object.freeze(catalog),
});
const localRuntime = (id, label, { anthropic = false } = {}) => definition({
id,
label,
family: 'local',
localRuntime: id,
transports: { openai: {}, ...(anthropic ? { anthropic: {} } : {}) },
plans: LOCAL,
catalog: { strategy: 'daemon' },
});
const subscription = (id, label, harnessOnly, extra = {}) => definition({
id,
label,
family: 'subscription',
harnessOnly,
plans: SUBSCRIPTION,
catalog: { strategy: 'harness' },
...extra,
});
/**
* @typedef {object} ServiceDefinition
* @property {string} id — stable identity; also the default instance slug, the
* OpenCode namespace for a gateway, and the `service` a harness binding names.
* @property {string} label
* @property {'subscription'|'api-key'|'local'|'fleet'} family
* @property {Record<'anthropic'|'openai', {defaultBaseUrl: string|null}>} transports —
* the wire protocols the service speaks. A service declaring none is reached
* only through a program that knows it (`harnessOnly`) or a static env switch.
* @property {{envVars: readonly string[], keyUrl?: string}} credential — the env
* var names a key for this service is conventionally held under (first is
* canonical), and where to obtain one.
* @property {readonly string[]} plans — the {@link SERVICE_PLANS} an instance may declare.
* @property {{strategy: string, planFilter?: (plan: string, models: string[]) => string[]}} catalog
* @property {string} [localRuntime] — the `LOCAL_RUNTIMES` id this row IS.
* @property {string} [harnessOnly] — reachable only through this harness id.
* @property {{apiKeyEnv: string, legacyMarker?: string, legacyApiKeyField?: string}} [gateway] —
* present on the rows `PROVIDER_GATEWAYS` derives from.
* @property {string} [piProvider] — the built-in provider name Pi ships for this
* service (`pi --provider <name>`), read by Pi's harness binding.
*/
/** @type {readonly ServiceDefinition[]} */
export const SERVICE_DEFINITIONS = Object.freeze([
// --- subscription ---------------------------------------------------------
subscription('claude-subscription', 'Claude subscription', 'claude'),
subscription('codex-subscription', 'ChatGPT / Codex subscription', 'codex'),
subscription('antigravity', 'Antigravity (Google)', 'antigravity'),
subscription('grok-build', 'Grok Build (xAI)', 'grok'),
subscription('cursor', 'Cursor', 'cursor', {
credential: { envVars: ['CURSOR_API_KEY'], keyUrl: 'https://cursor.com/dashboard' },
}),
// --- api-key --------------------------------------------------------------
definition({
id: 'anthropic',
label: 'Anthropic API',
family: 'api-key',
transports: { anthropic: { defaultBaseUrl: 'https://api.anthropic.com' } },
credential: { envVars: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN'], keyUrl: 'https://console.anthropic.com/settings/keys' },
plans: PAID,
catalog: { strategy: 'probe' },
piProvider: 'anthropic',
}),
definition({
id: 'openai',
label: 'OpenAI API',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://api.openai.com/v1' } },
credential: { envVars: ['OPENAI_API_KEY'], keyUrl: 'https://platform.openai.com/api-keys' },
plans: PAID,
catalog: { strategy: 'probe' },
piProvider: 'openai',
}),
definition({
id: 'google',
label: 'Google AI Studio (Gemini)',
family: 'api-key',
// Gemini's OpenAI-compatible surface; the native Generative Language API is
// reached only by programs that speak it (Pi's `google` provider).
transports: { openai: { defaultBaseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai' } },
credential: { envVars: ['GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GOOGLE_GENAI_API_KEY'], keyUrl: 'https://aistudio.google.com/apikey' },
plans: METERED,
catalog: { strategy: 'probe' },
piProvider: 'google',
}),
definition({
id: 'xai',
label: 'xAI API',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://api.x.ai/v1' } },
credential: { envVars: ['XAI_API_KEY', 'GROK_API_KEY'], keyUrl: 'https://console.x.ai/' },
plans: PAID,
catalog: { strategy: 'probe' },
piProvider: 'xai',
}),
definition({
id: 'bedrock',
label: 'Amazon Bedrock',
family: 'api-key',
// No transport of its own: Claude Code reaches it through a static env
// switch (`CLAUDE_CODE_USE_BEDROCK=1`) and Pi through its own provider name.
credential: { envVars: ['AWS_BEARER_TOKEN_BEDROCK'], keyUrl: 'https://console.aws.amazon.com/bedrock/' },
plans: PAID,
catalog: { strategy: 'static' },
piProvider: 'amazon-bedrock',
}),
definition({
id: 'kimi',
label: 'Kimi / Moonshot',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://api.moonshot.ai/v1' } },
credential: { envVars: ['KIMI_API_KEY', 'MOONSHOT_API_KEY'], keyUrl: 'https://platform.moonshot.ai/console/api-keys' },
plans: PAID,
catalog: { strategy: 'probe' },
harnessOnly: 'kimi',
piProvider: 'kimi-coding',
}),
// The three hosted gateways, in the order `PROVIDER_GATEWAYS` has always
// listed them — registry order breaks a tie on a record carrying two markers.
definition({
id: 'orcarouter',
label: 'OrcaRouter',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://api.orcarouter.ai/v1' } },
credential: { envVars: ['ORCAROUTER_API_KEY'] },
plans: PAID,
catalog: { strategy: 'probe' },
gateway: Object.freeze({ apiKeyEnv: 'ORCAROUTER_API_KEY', legacyMarker: 'orcarouterBacked', legacyApiKeyField: 'orcarouterApiKey' }),
}),
definition({
id: 'openrouter',
label: 'OpenRouter',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://openrouter.ai/api/v1' } },
credential: { envVars: ['OPENROUTER_API_KEY'] },
plans: METERED,
// OpenRouter marks its free tier in the model id itself — the one real signal.
catalog: { strategy: 'probe', planFilter: suffixPlanFilter(':free') },
gateway: Object.freeze({ apiKeyEnv: 'OPENROUTER_API_KEY' }),
piProvider: 'openrouter',
}),
definition({
id: 'nvidia-nim',
label: 'NVIDIA NIM',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://integrate.api.nvidia.com/v1' } },
credential: { envVars: ['NVIDIA_API_KEY'], keyUrl: 'https://build.nvidia.com' },
// Free vs paid is declared by the user: NIM's `/models` carries no tier field.
plans: METERED,
catalog: { strategy: 'probe' },
gateway: Object.freeze({ apiKeyEnv: 'NVIDIA_API_KEY' }),
piProvider: 'nvidia',
}),
definition({
id: 'opencode-zen',
label: 'OpenCode Zen',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://opencode.ai/zen/v1' } },
credential: { envVars: ['OPENCODE_API_KEY'], keyUrl: 'https://opencode.ai/auth' },
plans: METERED,
// Zen's free tier is `-free`-suffixed except its stealth model, which
// `opencode models` prints bare (`opencode/big-pickle`) — the default
// model of every shipped Zen preset, so the free plan must keep it.
catalog: { strategy: 'probe', planFilter: suffixPlanFilter('-free', { alsoFree: ['big-pickle'] }) },
piProvider: 'opencode',
}),
definition({
id: 'cerebras',
label: 'Cerebras',
family: 'api-key',
transports: { openai: { defaultBaseUrl: 'https://api.cerebras.ai/v1' } },
credential: { envVars: ['CEREBRAS_API_KEY'], keyUrl: 'https://cloud.cerebras.ai/' },
plans: METERED,
catalog: { strategy: 'probe' },
piProvider: 'cerebras',
}),
definition({
id: 'openai-compatible',
label: 'OpenAI-compatible endpoint',
family: 'api-key',
// A bare endpoint the user names; nothing conventional to default to.
transports: { openai: {} },
plans: METERED,
catalog: { strategy: 'probe' },
}),
// --- local ----------------------------------------------------------------
// Ollama serves an Anthropic-compatible surface beside its `/v1`, which is
// what lets Claude Code drive it.
localRuntime('ollama', 'Ollama', { anthropic: true }),
localRuntime('lmstudio', 'LM Studio'),
localRuntime('mtplx', 'MTPLX'),
localRuntime('llama', 'llama.cpp'),
localRuntime('vllm', 'vLLM'),
localRuntime('sglang', 'SGLang', { anthropic: true }),
localRuntime('slotstream', 'Slotstream'),
// --- fleet ----------------------------------------------------------------
definition({
id: 'fleet-host',
label: 'Fleet host',
family: 'fleet',
transports: { openai: {} },
plans: Object.freeze(['free']),
catalog: { strategy: 'probe' },
}),
]);
/** Every definition id. */
export const SERVICE_DEFINITION_IDS = Object.freeze(SERVICE_DEFINITIONS.map((row) => row.id));
/** The definition for an id, or `null`. */
export const serviceDefinitionById = (id) => SERVICE_DEFINITIONS.find((row) => row.id === id) || null;
/** The definition that IS a local runtime id, or `null`. */
export const serviceDefinitionForLocalRuntime = (runtimeId) =>
SERVICE_DEFINITIONS.find((row) => row.localRuntime === runtimeId) || null;
/**
* A slug an instance may be addressed by: `[a-z0-9][a-z0-9-]*`, so it can sit
* inside a composite provider id (`harness.method@service`) unescaped.
*/
export const SERVICE_SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
/**
* The pure INSTANCE shape the rest of the epic composes over: a definition,
* the slug it is addressed by, the plan the user declared, the endpoints it is
* actually reached at, and its credential material.
*
* Accepts a definition id, an instance input, or an already-resolved instance
* (resolution is idempotent), so every consumer can take any of them. A
* transport the instance does not
* override falls back to the definition's default base URL; a transport with
* neither is still DECLARED (the service speaks it) but has no endpoint, which
* `materializeRoute` refuses rather than guessing — a local daemon's port is an
* install-specific fact.
*
* `credentials` holds raw secret material, exactly as `providerConnectionProfile`'s
* does, and must never be serialized into a response.
*
* @param {{definitionId?: string, definition?: ServiceDefinition, slug?: string, plan?: string,
* transports?: Record<string, {baseUrl?: string|null}>, credentials?: {apiKey?: string},
* credential?: {via?: 'bootstrap'|'stored'}, credentialVia?: 'bootstrap'|'stored'}|string} input
* @returns {{definition: ServiceDefinition, slug: string, plan: string,
* transports: Record<string, {baseUrl: string|null}>, credentials: {apiKey?: string},
* credentialVia: 'stored'|'bootstrap'}}
*/
export function resolveServiceInstance(input) {
const raw = typeof input === 'string' ? { definitionId: input } : (input || {});
const definition = raw.definition || serviceDefinitionById(raw.definitionId);
if (!definition) throw serviceError('SERVICE_DEFINITION_UNKNOWN', `No service definition "${raw.definitionId ?? ''}"`);
const slug = raw.slug ?? definition.id;
if (!SERVICE_SLUG_RE.test(slug)) throw serviceError('SERVICE_SLUG_INVALID', `"${slug}" is not a service slug ([a-z0-9][a-z0-9-]*)`);
const plan = raw.plan ?? definition.plans[0];
assertServicePlan(definition, plan);
const transports = {};
for (const [protocol, transport] of Object.entries(definition.transports)) {
const override = raw.transports?.[protocol]?.baseUrl;
transports[protocol] = { baseUrl: typeof override === 'string' && override !== '' ? override : transport.defaultBaseUrl };
}
return {
definition,
slug,
plan,
transports,
credentials: { ...(raw.credentials || {}) },
credentialVia: raw.credentialVia === 'bootstrap' || raw.credential?.via === 'bootstrap' ? 'bootstrap' : 'stored',
};
}
/** Refuse a plan the definition does not sell — the one rule every instance write shares. */
export function assertServicePlan(definition, plan) {
if (!definition.plans.includes(plan)) {
throw serviceError('SERVICE_PLAN_UNSUPPORTED', `${definition.label} has no "${plan}" plan; choose one of ${definition.plans.join(', ')}`);
}
}
/**
* A typed error every consumer can key on. Every refusal here is about the
* caller's input, so it carries the 400 the error middleware reads — a route
* needs no translation layer to publish it.
*/
export function serviceError(code, message) {
const err = new Error(message);
err.code = code;
err.status = 400;
return err;
}