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
import { randomUUID } from 'node:crypto';
import { isDeepStrictEqual } from 'node:util';
import { z } from 'zod';
import { REDACTED_CREDENTIAL, providerConnectionProfile } from './providerConnections.js';
import {
PROVIDER_GRAPH_SCHEMA_VERSION,
buildProviderGraphPreview,
} from './providerGraphPreview.js';
import { CREATABLE_HARNESS_IDS, PROVIDER_HARNESSES, PROVIDER_HARNESS_IDS, ROUTE_MODES, providerRouteMode } from './providerHarnesses.js';
import {
effectiveModelAliases,
modelAliasRevision,
sanitizeModelAliases,
staleModelAliases,
} from './providerModelAliases.js';
import { routeSettingsRevision, routeSettingsSchema } from './providerRouteSettings.js';
import { CREATABLE_CONNECTION_KINDS, connectionKindLabel } from './providerRouteRecipes.js';
import { SERVICE_CREDENTIAL_VIAS, SERVICE_PLANS } from './serviceDefinitions.js';
import { isNonBlankStr } from './textUtils.js';
// `PROVIDER_GRAPH_SCHEMA_VERSION` is deliberately NOT re-exported: it is one
// wire version shared with the preview, and two flat `export *` modules in this
// directory publishing one identifier is exactly what the barrel's collision
// detector refuses. Import it from `providerGraphPreview.js`.
/**
* The DURABLE half of the provider connection graph (#6367, design record
* `docs/plans/2026-09-06-provider-connections-and-harnesses.md`).
*
* `providerGraphPreview.js` (#6366) answers "what WOULD an import create?" from
* provider records alone. This module owns the records that survive a restart:
* how a preview becomes durable rows, how those rows are sanitized for a
* client, how they are materialized back into `data/providers.json`, and — the
* load-bearing part — how a persisted graph is RECONCILED against a provider
* file that may have moved underneath it.
*
* Everything here is pure. No database handle, no file I/O, no clock beyond the
* injected id minter, so the reconciliation contract (which is where the data
* loss lives) is testable without a Postgres or a temp directory.
*
* The three states a route's connection-owned values can be in:
*
* - `projected` — last snapshot ACKNOWLEDGED as present in providers.json.
* - `pending` — committed to the DB, not yet acknowledged as written.
* - the file's ACTUAL values, read fresh at reconcile time.
*
* Keeping both snapshots is what makes a crash between the DB commit and the
* file write recoverable, and what stops a retry from clobbering a third value
* some other writer put there — see {@link planGraphReconciliation}.
*/
// --- durable row DTOs --------------------------------------------------------
// `.strict()` for the same reason the preview DTOs are strict: a field added to
// a row must never ride out to a client because a mapper forgot to drop it.
const catalogSchema = z.object({
state: z.enum(['unknown', 'known', 'failed']),
models: z.array(z.string()),
// Why the last refresh failed, already stripped of credential material
// (#6369). Optional so rows written before the field existed still parse, and
// nullable so a later SUCCESS can clear it without deleting the key.
error: z.string().nullable().optional(),
// Per-model facts a listing declared (#7563) and when it was last asked.
// Optional for the same reason `error` is: older rows carry neither.
capabilities: z.record(z.string(), z.object({ contextWindow: z.number().optional() }).strict()).optional(),
refreshedAt: z.string().optional(),
}).strict();
/** One connection row as every management surface publishes it — exported so the service DTO extends it. */
export const connectionDtoSchema = z.object({
id: z.string().min(1),
revision: z.number().int().positive(),
kind: z.string().min(1),
label: z.string(),
transports: z.record(z.string(), z.object({ baseUrl: z.string().min(1) }).strict()),
hasCredentials: z.boolean(),
catalog: catalogSchema,
// The service-instance identity (#7563). Additive, so
// `PROVIDER_GRAPH_SCHEMA_VERSION` stays at 1 and an older client ignores them.
// `slug` / `definitionId` are null on a row the boot backfill has not named.
slug: z.string().nullable(),
definitionId: z.string().nullable(),
plan: z.enum(SERVICE_PLANS),
enabled: z.boolean(),
credentialVia: z.enum(SERVICE_CREDENTIAL_VIAS),
}).strict();
const bindingDtoSchema = z.object({
id: z.string().min(1),
revision: z.number().int().positive(),
connectionId: z.string().min(1),
harnessId: z.enum(PROVIDER_HARNESS_IDS).nullable(),
variantKey: z.string().min(1),
label: z.string(),
enabled: z.boolean(),
selectedModels: z.array(z.string()),
// Derived, never stored: a binding whose route projection is unresolved
// refuses further graph mutations until reconciliation repairs it.
blocked: z.boolean(),
}).strict();
const routeDtoSchema = z.object({
providerId: z.string().min(1),
bindingId: z.string().min(1),
mode: z.enum(ROUTE_MODES),
// The EFFECTIVE alias map: what the last refresh observed, with the user's
// hand-authored overrides laid over the top (#6369).
modelMap: z.record(z.string(), z.string()),
// The override half on its own, so the panel can say which aliases a human
// wrote and offer to remove them, plus the fingerprint an edit must send
// back. `ai_route_bindings` has no revision column, so the stale check is a
// hash of these values — the same technique the mode overrides use.
modelAliasOverrides: z.record(z.string(), z.string()),
modelAliasRevision: z.string().min(1),
// Overrides naming a spelling the record no longer lists. Reported, never
// repaired: a saved alias is only ever removed by the person who wrote it.
staleModelAliases: z.array(z.string()),
// Presence only — the snapshots themselves can carry secrets.
projectionPending: z.boolean(),
// This mode's own overrides, and the fingerprint a write must send back
// (#6369). Route-owned by construction: nothing here is connection state, so
// editing it moves no other harness.
settings: routeSettingsSchema,
settingsRevision: z.string().min(1),
// The effort ladder this route's harness actually accepts, or `null` for one
// that takes no effort flag at all. Published rather than re-derived in the
// browser so a renamed or path-configured binary still offers the right
// levels — and so "no control" stays distinct from "an empty list".
effortLevels: z.array(z.string()).nullable(),
// Display half of the Shell hand-off, present only on a launchable TUI route.
// The launch itself re-resolves this AND the provider's secret env server-side
// (`shell:start { providerId }`), so the command line is never the contract.
tuiCommandLine: z.string().optional(),
}).strict();
// What a client may CREATE (#6369). Both are constants derived from the code
// registries, published rather than mirrored into the browser: which harnesses
// carry a command recipe, and which backend kinds a minted route can honestly
// describe, are server decisions with no rendered value the browser could
// recompute. Additive, so `PROVIDER_GRAPH_SCHEMA_VERSION` stays at 1 and an
// older client simply ignores them.
const creatableHarnessSchema = z.object({
id: z.enum(PROVIDER_HARNESS_IDS),
label: z.string().min(1),
modes: z.array(z.enum(ROUTE_MODES)).min(1),
protocol: z.string().min(1),
// The credential key this program needs on the connection, and whether it
// refuses to start without one — so the form can say so BEFORE the create.
credentialKey: z.string().min(1),
credentialRequired: z.boolean(),
}).strict();
const creatableKindSchema = z.object({
id: z.string().min(1),
label: z.string().min(1),
}).strict();
/** The static half of the create surface. Derived from code, never from rows. */
const CREATABLE = Object.freeze({
// Creatable FROM A CONNECTION — a subscription program or Pi carries a
// recipe too (#7562) but composes only onto named services, not here.
harnesses: Object.freeze(PROVIDER_HARNESSES.filter((harness) => CREATABLE_HARNESS_IDS.includes(harness.id)).map((harness) => Object.freeze({
id: harness.id,
label: harness.label,
modes: [...harness.modes],
protocol: harness.protocol,
credentialKey: harness.recipe.credential.via === 'env' ? harness.recipe.credential.name : 'apiKey',
credentialRequired: harness.recipe.credential.required === true,
}))),
kinds: Object.freeze(CREATABLE_CONNECTION_KINDS.map((id) => Object.freeze({ id, label: connectionKindLabel(id) }))),
});
/** The full `GET /api/providers/management` body. */
export const managementGraphSchema = z.object({
schemaVersion: z.literal(PROVIDER_GRAPH_SCHEMA_VERSION),
activeProvider: z.string().nullable(),
connections: z.array(connectionDtoSchema),
bindings: z.array(bindingDtoSchema),
routes: z.array(routeDtoSchema),
creatableHarnesses: z.array(creatableHarnessSchema),
creatableConnectionKinds: z.array(creatableKindSchema),
}).strict();
/**
* The sanitized, validated body a client receives.
*
* Credentials, projection snapshots and raw provider records never appear: the
* browser is told only WHETHER a connection has credentials and whether a
* route's projection is settled. Every identity decision was already made
* server-side on real values.
*
* `routeSettings` carries the per-route mode overrides the service resolved
* from the live executable records (#6369). It arrives pre-resolved rather than
* being read here because the TUI command line it also carries needs the host's
* shell resolution, and this module stays pure. A route with no entry — a graph
* row whose record is mid-removal — publishes an empty override set rather than
* an absent field, so the client never has to branch on presence.
*
* A route entry also carries `storedModels` — the record's own model list — used
* only to decide which hand-authored aliases have gone stale. It is read here
* rather than from the graph row because `providers.json` is what a run
* actually executes, so the file is the honest thing to check an alias against.
*
* @param {{routeSettings?: Map<string, object>}} input
*/
export function toManagementGraphDto({ connections, bindings, routes, activeProvider = null, routeSettings = new Map() }) {
const blocked = new Set(routes.filter((route) => route.pending).map((route) => route.bindingId));
return managementGraphSchema.parse({
schemaVersion: PROVIDER_GRAPH_SCHEMA_VERSION,
activeProvider: typeof activeProvider === 'string' ? activeProvider : null,
creatableHarnesses: CREATABLE.harnesses,
creatableConnectionKinds: CREATABLE.kinds,
connections: connections.map(({
id, revision, kind, label, transports, credentials, catalog,
slug = null, definitionId = null, plan = 'paid', enabled = true, credentialVia = 'stored',
}) => ({
id,
revision,
kind,
label,
transports,
hasCredentials: connectionHasCredentials({ credentials, credentialVia }),
catalog,
slug,
definitionId,
plan,
enabled,
credentialVia,
})),
bindings: bindings.map(({ id, revision, connectionId, harnessId, variantKey, label, enabled, selectedModels }) => ({
id, revision, connectionId, harnessId, variantKey, label, enabled, selectedModels, blocked: blocked.has(id),
})),
routes: routes.map(({ providerId, bindingId, mode, modelMap, modelAliasOverrides, pending }) => {
const {
settings = {}, effortLevels = null, tuiCommandLine = null, storedModels = null,
} = routeSettings.get(providerId) || {};
const overrides = sanitizeModelAliases(modelAliasOverrides);
return {
providerId,
bindingId,
mode,
modelMap: effectiveModelAliases(modelMap, overrides),
modelAliasOverrides: overrides,
modelAliasRevision: modelAliasRevision(overrides),
staleModelAliases: staleModelAliases(overrides, storedModels),
projectionPending: Boolean(pending),
settings,
settingsRevision: routeSettingsRevision(settings),
effortLevels,
// Omitted rather than nulled: "not a launchable TUI" is the absence of
// the affordance, not an empty command.
...(tuiCommandLine ? { tuiCommandLine } : {}),
};
}),
});
}
/**
* Whether a row holds a secret. Only a `stored` instance does (#7563): a
* `bootstrap` one is supplied at spawn and an `env` / `cli-login` one is
* held by something else, so a key left on such a row is not the credential.
*/
export const connectionHasCredentials = ({ credentials, credentialVia = 'stored' }) =>
credentialVia === 'stored' && Object.keys(credentials || {}).length > 0;
/**
* One connection row, sanitized exactly as `GET /api/providers/management`
* sanitizes it (#6369).
*
* Routed through {@link toManagementGraphDto} rather than mapped separately, so
* the create response and the graph response cannot drift into publishing
* different things — there is one strict schema and one mapper.
*/
export const toConnectionDto = (connection) =>
toManagementGraphDto({ connections: [connection], bindings: [], routes: [] }).connections[0];
// --- import ------------------------------------------------------------------
/** The connection-owned half of one provider record, as stored in a snapshot. */
export const connectionOwnedSnapshot = (provider) => providerConnectionProfile(provider).owned;
/**
* The identity one ROUTE's profile asserts, secrets included. Server-side only.
*
* Two routes sharing this key describe the same backend as each other, which is
* what keeps a binding's modes together and splits them once they diverge.
* Whether a route still belongs on a STORED connection is a different question
* — see {@link routeBelongsOnConnection}.
*/
const identityKey = ({ kind, transports, credentials }) => JSON.stringify([
kind,
Object.entries(transports || {}).sort(([a], [b]) => a.localeCompare(b)),
Object.entries(credentials || {}).sort(([a], [b]) => a.localeCompare(b)),
]);
/**
* Whether a route of backend kind `routeKind` may sit on a connection of
* `connectionKind`. Equal kinds, plus one widening: a direct `api` record reads
* back as kind `api` even when its endpoint IS a hosted gateway's (the shipped
* `nvidia-nim` record holds the key its OpenCode wrappers use), so a `gateway:`
* service instance may hold it. The transport and credential checks below still
* have to pass — the kind alone never places a route.
*/
const routeKindFitsConnection = (routeKind, connectionKind) => routeKind === connectionKind
|| (routeKind === 'api' && typeof connectionKind === 'string' && connectionKind.startsWith('gateway:'));
/**
* Whether a stored connection still CONTAINS the backend a route describes.
*
* A provider record names exactly one endpoint, so a route's profile always
* reports exactly one transport — while a connection a human linked across
* protocols declares one per protocol (an Ollama daemon reached by Claude on
* its Anthropic port and by Codex on its `/v1` port is ONE backend). Demanding
* {@link identityKey} equality here would therefore match none of a
* multi-transport row's own routes and clone every binding off it, silently
* undoing the explicit link the connection graph exists to hold.
*
* Containment, precisely:
*
* - `kind` matches — a route never migrates between backend kinds, save a
* direct `api` record on a `gateway:` instance ({@link routeKindFitsConnection}).
* - The route's transport protocol is DECLARED by the connection at the same
* `baseUrl`. A route declaring no transport at all matches only a
* connection that declares none either: "names no endpoint" must never
* collapse into "sits on whichever backend you like".
* - The route's credentials are a SUBSET of the connection's, with every
* shared key equal. A row carrying one key per protocol is normal (Claude
* sends a token where OpenCode sends none); disagreeing on a key they share
* is a real move, and still detaches.
*
* `sameConnectionIdentity` stays strict on purpose: it answers "are these two
* records the same backend?" at IMPORT time, where equality is what stops an
* accidental merge. This is the looser question reconciliation asks about a
* link a human already made — and the same question `createBinding` asks of a
* freshly minted record, so a create is accepted on exactly the terms the next
* reconciliation pass will judge it by.
*/
export function routeBelongsOnConnection(profile, connection) {
if (!connection || !routeKindFitsConnection(profile.kind, connection.kind)) return false;
const declared = connection.transports || {};
const transports = Object.entries(profile.transports || {});
if (transports.length === 0) return Object.keys(declared).length === 0;
// Both sides must name a real URL. A row hand-edited into `{ anthropic: {} }`
// has no endpoint, and letting two absent values compare equal is exactly the
// collapse of "not set" into "matches" this rule exists to prevent.
const declaresSameEndpoint = ([protocol, transport]) => {
const url = declared[protocol]?.baseUrl;
return typeof url === 'string' && url !== '' && url === transport?.baseUrl;
};
if (!transports.every(declaresSameEndpoint)) return false;
const secrets = connection.credentials || {};
return Object.entries(profile.credentials || {}).every(([name, value]) => secrets[name] === value);
}
/**
* Mint durable rows from a read-only preview.
*
* Preview ids (`conn:…`, `binding:…`) are display scaffolding derived from a
* provider id, so they would change the moment a record is renamed. Durable
* rows get UUIDs, which is what lets a link survive a rename. Routes keep their
* EXECUTABLE provider ids untouched — those are the saved-selection contract.
*
* A preview route with no binding (an isolated legacy record) gets no row at
* all: it stays a valid legacy route the graph simply does not manage.
*
* @param {object} preview - from `buildProviderGraphPreview`
* @param {() => string} [mintId] - injected for deterministic tests
*/
export function graphFromPreview(preview, mintId = randomUUID) {
const connectionIds = new Map();
const connections = preview.connections.map((connection) => {
const id = mintId();
connectionIds.set(connection.id, id);
return {
id,
revision: 1,
kind: connection.kind,
label: connection.label,
transports: connection.transports,
credentials: connection.profile.credentials,
catalog: connection.catalog,
};
});
const bindingIds = new Map();
const bindings = preview.bindings.map((binding) => {
const id = mintId();
bindingIds.set(binding.id, id);
return {
id,
revision: 1,
connectionId: connectionIds.get(binding.connectionId),
harnessId: binding.harnessId,
variantKey: binding.variantKey,
label: binding.label,
enabled: binding.enabled,
selectedModels: binding.selectedModels,
};
});
const routes = preview.routes.filter((route) => route.bindingId).map((route) => ({
providerId: route.providerId,
bindingId: bindingIds.get(route.bindingId),
mode: route.mode,
modelMap: route.modelMap,
projected: route.owned,
pending: null,
pendingRevision: null,
}));
return { connections, bindings, routes };
}
/** Build the durable graph an install's current provider records imply. */
export const importGraphFromProviders = (data, mintId = randomUUID) =>
graphFromPreview(buildProviderGraphPreview(data), mintId);
// --- derived presets (#7565) ---------------------------------------------------
/**
* Whether a record is a DERIVED preset: one carrying the three structural keys
* — `harnessId`, `method`, `serviceId` — that name the service instance its
* connection-owned values are materialized from. Lives here (not in
* `providerPresets.js`, which imports this module) because reconciliation is
* the first reader.
*/
export const isDerivedPreset = (record) => Boolean(record) && typeof record === 'object'
&& [record.harnessId, record.method, record.serviceId].every(isNonBlankStr);
/**
* Whether a derived preset DECLARES it sits on this connection — its
* `serviceId` is the row's slug. A declaration outranks the profile
* containment test: "derived from service X" is a fact the record states, not
* one reconciliation infers, so a direct-API preset on a gateway instance
* (whose profile reads back as kind `api`, not `gateway:<id>`) stays on the row
* it names instead of being cloned onto a fragment of its own every pass.
*/
export const presetDeclaresConnection = (record, connection) =>
isDerivedPreset(record) && typeof connection?.slug === 'string' && connection.slug === record.serviceId;
/**
* Import derived presets ONTO the connections they declare, rather than as
* fragments of their own. The preview's own grouping (mode siblings, identity
* buckets) still decides which records share one binding; only the connection
* edge is retargeted, and the binding takes the first free variant key on its
* target so the database's uniqueness rules hold.
*
* A declared preset whose profile the preview isolates (a reason on it) gets
* no route row, exactly as any other isolated record.
*/
function importDeclaredPresets(records, graph, bySlug, mintId) {
const byId = new Map(records.map((record) => [record.id, record]));
const fragment = importGraphFromProviders({ providers: records }, mintId);
const variantKey = (connectionId, harnessId, key) => JSON.stringify([connectionId, harnessId ?? null, key]);
const taken = new Set(graph.bindings.map((binding) => variantKey(binding.connectionId, binding.harnessId, binding.variantKey)));
const bindings = [];
const routes = [];
for (const binding of fragment.bindings) {
const own = fragment.routes.filter((route) => route.bindingId === binding.id);
const target = bySlug.get(byId.get(own[0]?.providerId)?.serviceId);
if (!target) continue;
const key = taken.has(variantKey(target.id, binding.harnessId, 'default')) ? `variant:${own[0].providerId}` : 'default';
taken.add(variantKey(target.id, binding.harnessId, key));
bindings.push({ ...binding, connectionId: target.id, variantKey: key });
routes.push(...own);
}
return { connections: [], bindings, routes };
}
// --- reconciliation ----------------------------------------------------------
/**
* Reconcile a persisted graph against the provider file as it ACTUALLY is.
*
* One function serves three callers, because they are the same problem:
*
* - **boot** — the file may have been edited by a downgraded release, or a
* crash may have landed a DB commit without its file write;
* - **after a legacy write** — an old client's `PATCH /api/providers/:id`
* changed a connection-owned field with no idea a graph exists;
* - **after a restore** — half a backup can arrive without the other half.
*
* The rules, in the order they are applied per route:
*
* 1. The record is GONE → drop its row. A deleted provider is never
* resurrected; any saved selection naming it stays a visibly unresolved
* pin, and an emptied binding/connection is kept for explicit cleanup
* rather than deleted or auto-refilled.
* 2. A `pending` snapshot exists and the file matches it → the write landed;
* acknowledge it.
* 3. A `pending` snapshot exists and the file still matches `projected` → the
* write did not land; retry it.
* 4. A `pending` snapshot exists and the file matches NEITHER → a third
* writer changed it. Refuse: never overwrite, keep the row's last valid
* executable values readable, and report the binding as blocked.
* 5. Otherwise the file's values are authoritative. Routes are regrouped by
* the connection they actually describe: an unchanged group keeps its
* UUIDs; a changed group whose connection is SHARED with another binding
* clones it (detach) rather than editing a value another harness relies
* on; a changed group on an exclusive connection updates it in place; and
* a binding whose routes now disagree with each other splits.
* 6. A provider record the graph has no row for is imported independently,
* as its own fragment — never auto-linked into an existing connection.
*
* @param {{connections:object[], bindings:object[], routes:object[]}} graph
* @param {object[]} providers - current executable records
* @param {{mintId?: () => string}} [options]
*/
export function planGraphReconciliation(graph, providers, { mintId = randomUUID } = {}) {
const records = new Map(
(Array.isArray(providers) ? providers : [])
.filter((provider) => provider && typeof provider === 'object' && provider.id)
.map((provider) => [provider.id, provider]),
);
const bindingsById = new Map(graph.bindings.map((binding) => [binding.id, binding]));
const connectionsById = new Map(graph.connections.map((connection) => [connection.id, connection]));
const bindingsPerConnection = new Map();
for (const binding of graph.bindings) {
bindingsPerConnection.set(binding.connectionId, (bindingsPerConnection.get(binding.connectionId) || 0) + 1);
}
const plan = {
acknowledgements: [], // { providerId } — pending landed; promote it to projected
retries: [], // { providerId, owned } — rewrite these values into providers.json
conflicts: [], // { providerId, bindingId, reason } — refuse; the binding stays blocked
removals: [], // providerId[] — drop the row, never resurrect
regroups: [], // see below — detach / split / in-place update
snapshots: [], // { providerId, owned } — record the file's values as projected
imports: { connections: [], bindings: [], routes: [] }, // rows for records with no mapping yet
};
const routesByBinding = new Map();
for (const route of graph.routes) {
if (!records.has(route.providerId)) {
plan.removals.push(route.providerId);
continue;
}
const provider = records.get(route.providerId);
const owned = connectionOwnedSnapshot(provider);
if (route.pending) {
if (isDeepStrictEqual(owned, route.pending)) {
plan.acknowledgements.push({ providerId: route.providerId });
} else if (isDeepStrictEqual(owned, route.projected)) {
plan.retries.push({ providerId: route.providerId, owned: route.pending });
} else {
plan.conflicts.push({ providerId: route.providerId, bindingId: route.bindingId, reason: 'external-change' });
}
// A route with an unsettled projection is deliberately excluded from the
// regrouping below: its own values are exactly what is in dispute, and
// regrouping on them would bake the disputed state into the graph.
continue;
}
const list = routesByBinding.get(route.bindingId) || [];
list.push({ route, provider, owned, profile: providerConnectionProfile(provider) });
routesByBinding.set(route.bindingId, list);
}
for (const [bindingId, entries] of routesByBinding) {
const binding = bindingsById.get(bindingId);
if (!binding) continue;
const stored = connectionsById.get(binding.connectionId) || null;
const shared = (bindingsPerConnection.get(binding.connectionId) || 0) > 1;
// Routes the stored connection still CONTAINS stay on it together, whether
// or not they describe it identically — that is what keeps a cross-protocol
// link alive. Every other route regroups by the backend it now names.
const onStored = [];
const moved = new Map();
for (const entry of entries) {
if (presetDeclaresConnection(entry.provider, stored) || routeBelongsOnConnection(entry.profile, stored)) {
onStored.push(entry);
continue;
}
const key = identityKey(entry.profile);
moved.set(key, [...(moved.get(key) || []), entry]);
}
// The group that KEEPS this binding is the one still on the stored
// connection; failing that, the largest, so the fewest routes are moved.
const ordered = [...moved.values()].sort((a, b) => b.length - a.length);
if (onStored.length > 0) ordered.unshift(onStored);
for (const [index, group] of ordered.entries()) {
const isKeeper = index === 0;
const lead = group[0];
const unchanged = isKeeper && onStored.length > 0;
// A clone is required whenever the values changed AND the connection row
// is shared: editing it in place would silently repoint another harness.
const action = unchanged ? 'unchanged' : (isKeeper && !shared ? 'update' : 'clone');
const models = [...new Set(group.flatMap((entry) => Object.keys(entry.route.modelMap)))];
plan.regroups.push({
routeIds: group.map((entry) => entry.route.providerId),
// `null` means "mint this binding" — a split.
bindingId: isKeeper ? bindingId : null,
binding: isKeeper ? null : {
id: mintId(),
revision: 1,
harnessId: binding.harnessId,
// A split binding is a NEW configuration of the same harness on a
// different backend, so it gets its own labeled variant rather than
// colliding with the original's `default`.
variantKey: `variant:${lead.route.providerId}`,
label: String(lead.provider.name || lead.provider.id),
// OR across the group, exactly as import does. Consent flags stay
// per-route and never participate.
enabled: group.some((entry) => entry.provider.enabled === true),
selectedModels: models,
},
connectionAction: action,
connection: {
id: action === 'clone' ? mintId() : binding.connectionId,
kind: lead.profile.kind,
label: stored && isKeeper ? stored.label : String(lead.provider.name || lead.provider.id),
// An unchanged row is republished exactly AS STORED rather than
// narrowed to the single transport this route happens to name —
// otherwise "nothing moved" would still describe a backend the other
// harness on it cannot reach.
transports: unchanged ? stored.transports : lead.profile.transports,
credentials: unchanged ? stored.credentials : lead.profile.credentials,
catalog: unchanged ? stored.catalog : { state: models.length > 0 ? 'known' : 'unknown', models },
},
});
for (const entry of group) {
if (!isDeepStrictEqual(entry.owned, entry.route.projected)) {
plan.snapshots.push({ providerId: entry.route.providerId, owned: entry.owned });
}
}
}
}
const mapped = new Set(graph.routes.map((route) => route.providerId));
const unmapped = [...records.values()].filter((provider) => !mapped.has(provider.id));
// A derived preset naming an existing instance is imported ONTO it (#7565);
// everything else is its own fragment, never auto-linked.
const bySlug = new Map(graph.connections.filter((connection) => connection.slug).map((connection) => [connection.slug, connection]));
const declared = [];
const fragments = [];
for (const provider of unmapped) {
(isDerivedPreset(provider) && bySlug.has(provider.serviceId) ? declared : fragments).push(provider);
}
if (fragments.length > 0) plan.imports = importGraphFromProviders({ providers: fragments }, mintId);
if (declared.length > 0) {
const onto = importDeclaredPresets(declared, graph, bySlug, mintId);
plan.imports.bindings.push(...onto.bindings);
plan.imports.routes.push(...onto.routes);
}
return plan;
}
/** Whether a plan asks for any write at all. Lets boot skip a no-op pass. */
export const reconciliationIsNoop = (plan) =>
plan.acknowledgements.length === 0
&& plan.retries.length === 0
&& plan.removals.length === 0
&& plan.snapshots.length === 0
&& plan.imports.routes.length === 0
&& plan.regroups.every((regroup) => regroup.connectionAction === 'unchanged' && regroup.bindingId);
// --- explicit management edits (#6369) ---------------------------------------
/**
* Merge a credential patch into a connection's stored credentials.
*
* Three distinct inputs, three distinct outcomes — the sentinel-vs-empty rule
* from AGENTS.md, applied to secrets, where conflating them silently destroys
* one:
*
* - key ABSENT → preserve the stored secret (the client never had it)
* - value `null`→ an explicit clear
* - a string → set it
*
* A client can only have learned `REDACTED_CREDENTIAL` by reading a sanitized
* response, so echoing it back is never an intentional value. It is reported as
* `rejected` rather than written, because storing `'***'` as the real secret
* would break execution in a way no later edit could distinguish from a typo.
*
* @param {Record<string,string>} current
* @param {Record<string,string|null>|undefined} patch
* @returns {{credentials: Record<string,string>, rejected: string[]}}
*/
export function mergeConnectionCredentials(current, patch) {
const credentials = { ...(current || {}) };
const rejected = [];
for (const [name, value] of Object.entries(patch || {})) {
if (value === null) {
delete credentials[name];
continue;
}
if (value === REDACTED_CREDENTIAL) {
rejected.push(name);
continue;
}
credentials[name] = value;
}
return { credentials, rejected };
}
/** Bound on a persisted refresh error, so one runaway provider message cannot bloat a row. */
const CATALOG_ERROR_MAX = 300;
/**
* A refresh failure reduced to something safe to persist and show.
*
* Provider errors routinely echo the request that produced them, so the
* connection's OWN credential values are replaced before anything is stored —
* an exact match on known secrets, not a guess at what a secret looks like.
*
* @param {unknown} error
* @param {Record<string,string>} credentials - the connection's raw secrets
* @returns {string}
*/
export function sanitizeCatalogError(error, credentials = {}) {
const raw = (error && typeof error === 'object' && 'message' in error ? String(error.message) : String(error || ''))
|| 'The model refresh failed';
const redacted = Object.values(credentials)
.filter((secret) => typeof secret === 'string' && secret.length > 0)
.reduce((text, secret) => text.split(secret).join(REDACTED_CREDENTIAL), raw);
return redacted.length > CATALOG_ERROR_MAX ? `${redacted.slice(0, CATALOG_ERROR_MAX)}…` : redacted;
}
/**
* The catalog a refresh should leave behind.
*
* The rule that matters is the one this whole feature exists to protect: a
* FAILED probe keeps the models it already knew. Only a successful probe writes
* a model list, and a successful probe returning nothing writes `known` with an
* empty list — a real answer from a backend whose last model was deleted, not
* the same state as "never asked".
*
* A PARTIAL result — some harnesses on the backend answered, others did not —
* is `known` (the models it lists really were observed) that KEEPS the error,
* because reporting it as clean would hide a harness that cannot reach the
* backend behind the models of one that can.
*
* Every refresh stamps `refreshedAt` (#7563) — a failure too, so "last asked"
* and "last answered" stay distinct facts — and a success records the
* per-model `capabilities` its listing declared (today the context window),
* while a failure keeps the previous ones with the previous models.
*
* @param {{state:string, models:string[], capabilities?: object}} current - the stored catalog
* @param {{refreshed: boolean, models?: string[], error?: string|null, contextWindows?: Record<string, number>|null}} outcome
* @param {{now?: () => string}} [options] - injected clock, for tests
* @returns {{state:'unknown'|'known'|'failed', models:string[], error:string|null, capabilities?: object, refreshedAt: string}}
*/
export function nextConnectionCatalog(current, outcome, { now = () => new Date().toISOString() } = {}) {
const models = Array.isArray(current?.models) ? current.models : [];
if (!outcome?.refreshed) {
return {
state: 'failed',
models,
error: outcome?.error ?? 'The model refresh failed',
...(current?.capabilities ? { capabilities: current.capabilities } : {}),
refreshedAt: now(),
};
}
const next = [...new Set(outcome.models || [])];
const windows = outcome.contextWindows && typeof outcome.contextWindows === 'object' ? outcome.contextWindows : {};
const capabilities = Object.fromEntries(next
.filter((model) => Number.isFinite(windows[model]))
.map((model) => [model, { contextWindow: windows[model] }]));
return { state: 'known', models: next, error: outcome.error ?? null, capabilities, refreshedAt: now() };
}