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 { ServerError } from '../lib/errorHandler.js';
import {
compareBackendEndpoints,
providerConnectionProfile,
projectConnectionOwnedFields,
withConnectionOwnedFields,
} from '../lib/providerConnections.js';
import {
connectionOwnedSnapshot,
isDerivedPreset,
mergeConnectionCredentials,
nextConnectionCatalog,
planGraphReconciliation,
reconciliationIsNoop,
routeBelongsOnConnection,
sanitizeCatalogError,
toConnectionDto,
toManagementGraphDto,
} from '../lib/providerGraphRecords.js';
import { resolveRouteModels } from '../lib/providerGraphPreview.js';
import {
applyModelAliasPatch,
connectionCatalogModels,
effectiveModelAliases,
modelAliasRevision,
} from '../lib/providerModelAliases.js';
import { harnessById } from '../lib/providerHarnesses.js';
import { modeSiblingName } from '../lib/aiToolkit/internal/providerModes.js';
import {
planPresetBackfill,
presetBackfillVerdict,
rederivePreset,
} from '../lib/providerPresets.js';
import { effortLevelsForProvider } from '../lib/providerModels.js';
import {
bindingBlocker,
buildRouteRecord,
connectionBlocker,
connectionKindLabel,
mintRouteIds,
} from '../lib/providerRouteRecipes.js';
import {
routeSettingsFor,
routeSettingsRevision,
unsupportedRouteSettings,
} from '../lib/providerRouteSettings.js';
import { buildTuiShellLaunch } from '../lib/tuiShellLaunch.js';
import {
allocateServiceSlug,
instanceForConnection,
planServiceColumnBackfill,
serviceColumnsForConnection,
takenServiceSlugs,
} from '../lib/providerServiceInstances.js';
import { planServiceInstanceMerges } from '../lib/providerServiceMerge.js';
import { SERVICE_CREDENTIAL_VIAS, assertServicePlan, serviceDefinitionById } from '../lib/serviceDefinitions.js';
import { requireToolkit } from '../lib/aiToolkitState.js';
import {
acknowledgeProjection,
applyReconciliation,
applyServiceColumnBackfill,
commitPendingProjection,
deleteConnection,
detachBindingToConnection,
mergeServiceInstances,
readGraph,
relinkBinding,
saveBindingSettings,
saveConnectionSettings,
saveRouteModelAliases,
saveRouteModelMap,
writeGraph,
} from './providerGraphStore.js';
/**
* The provider connection graph's orchestration layer (#6367).
*
* Two stores have to agree here and neither can be locked against the other:
* the DB graph (`providerGraphStore.js`) and the executable
* `data/providers.json` the toolkit owns. `providers.json` stays fully
* materialized and authoritative for EXECUTION -- a downgraded release runs it
* with no graph at all -- so every rule below is written from that direction:
* the file is what a run reads, and the graph follows it.
*
* **Serialization.** Every pass runs on one promise queue, so a legacy provider
* write, a boot reconcile and a link can never interleave their reads and
* writes. This is re-entrancy control, not multi-actor locking (AGENTS.md
* Security Model): there is one server process and one human.
*
* **Projection ordering.** A graph mutation commits its rows AND the pending
* projection snapshot in one DB transaction, writes providers.json through the
* toolkit, then acknowledges. A crash at any point leaves a `pending` snapshot
* the next reconcile pass can resolve against the file's actual values --
* retrying only when the file still holds the old value, and refusing outright
* when it holds a third one.
*
* **No AI provider is ever contacted here.** Import, reconcile, link, unlink
* and projection are local I/O only (AGENTS.md "No cold-bootstrap LLM calls").
*/
/** Off until the database phase says the graph tables exist. */
let graphEnabled = false;
/** Re-entrancy latch: a projection's own file write must not re-trigger a pass. */
let reconciling = false;
let queue = Promise.resolve();
/**
* Why each routed legacy record stayed legacy on the LAST pass (#7565), by
* provider id. The editor offers "Convert to derived preset" only where this
* holds no reason: the conversion runs the very same pass, so a record the pass
* just refused would refuse again (the pre-fix editor offered the button to
* every shipped preset it could never convert).
*/
let presetSkipReasons = new Map();
/**
* One-at-a-time execution. A rejected pass must not poison the next one.
* Exported (as `serializeProviderGraph`) for the service-instance operations
* in `providerServices.js`, which mutate the same rows.
*/
const serialize = (fn) => {
queue = queue.then(() => undefined, () => undefined).then(fn);
return queue;
};
export { serialize as serializeProviderGraph };
export const providerGraphEnabled = () => graphEnabled;
/** The reason the last pass left `providerId` a legacy preset, or null when it did not refuse it. */
export const presetSkipReason = (providerId) => presetSkipReasons.get(providerId) ?? null;
/** Test seam: reset module state between suites. */
export function resetProviderGraphState() {
graphEnabled = false;
reconciling = false;
queue = Promise.resolve();
presetSkipReasons = new Map();
}
const providerService = () => requireToolkit().services.providers;
// Deferred: the bootstrap-app table is read only when a preset is derived, and
// its module reaches `lib/validation.js` — a closure nothing on the graph's
// boot path otherwise pays for (server/AGENTS.md "Import scoping").
const bootstrapApps = async () => (await import('./credentialBootstrapApps.js')).listCredentialBootstraps();
/**
* A connection addressed by UUID or by service slug (#7563). Every
* `/connections/:id` route accepts either, so a client that learned the slug
* from `/services` can use it on the older surface too. `null` when neither
* matches — and never a label match.
*/
export const findConnectionByRef = (graph, ref) =>
graph.connections.find((candidate) => candidate.id === ref || (candidate.slug != null && candidate.slug === ref)) ?? null;
/**
* The patch that materializes a connection-owned snapshot into an executable
* record. Built from the live record so unknown custom fields and route-owned
* env vars survive untouched.
*/
function projectionPatch(provider, owned) {
const merged = withConnectionOwnedFields(provider, owned);
const patch = { ...owned.fields };
if (owned.hasEnvVars) patch.envVars = merged.envVars;
return patch;
}
/**
* One reconciliation pass: read both stores, plan, apply.
*
* Retries are written to the file BEFORE the plan is applied so their rows can
* be acknowledged in the same transaction -- a retry that could not be written
* stays pending and is retried on the next pass rather than being marked done.
*/
async function reconcilePass(reason) {
const graph = await readGraph();
const { providers, activeProvider } = await providerService().getAllProviders();
const plan = planGraphReconciliation(graph, providers, { mintId: randomUUID });
if (plan.retries.length > 0) {
const byId = new Map(providers.map((provider) => [provider.id, provider]));
const patches = Object.fromEntries(plan.retries
.filter(({ providerId }) => byId.has(providerId))
.map(({ providerId, owned }) => [providerId, projectionPatch(byId.get(providerId), owned)]));
const written = await providerService().applyProviderPatches(patches);
plan.acknowledgements.push(...written.map((providerId) => ({ providerId })));
}
// Service-instance columns (#7563): a row written before they existed, an
// imported fragment and a detached clone all arrive with no slug. The fresh
// rows in the plan are named BEFORE it is applied, so they land addressed;
// the pre-existing unnamed rows are backfilled after. Row-derived (never a
// seed) and idempotent, so it rides every pass rather than a one-shot
// migration. Local I/O only; nothing here contacts a provider.
const taken = takenServiceSlugs(graph.connections);
const harnessOf = (bindings, test) => bindings.find(test)?.harnessId ?? null;
for (const connection of plan.imports.connections) {
const harnessId = harnessOf(plan.imports.bindings, (binding) => binding.connectionId === connection.id);
Object.assign(connection, serviceColumnsForConnection(connection, { harnessId, taken }));
}
for (const regroup of plan.regroups) {
if (regroup.connectionAction !== 'clone') continue;
const harnessId = regroup.binding?.harnessId ?? harnessOf(graph.bindings, (binding) => binding.id === regroup.bindingId);
Object.assign(regroup.connection, serviceColumnsForConnection(regroup.connection, { harnessId, taken }));
}
const backfill = planServiceColumnBackfill(graph, taken);
const noop = reconciliationIsNoop(plan);
if (!noop) await applyReconciliation(plan);
if (backfill.length > 0) {
await applyServiceColumnBackfill(backfill);
console.log(`🔗 Provider graph: named ${backfill.length} service instance(s) (${backfill.map((row) => row.slug).join(', ')})`);
}
// Derived presets (#7565): every legacy record the graph now routes onto a
// named instance is stamped with its structural keys — when re-deriving it
// from that service is a fixpoint. Row-derived like the slugs above, so it
// rides every pass; the latch this pass holds keeps the file write from
// re-entering. The view it reads is the graph AS APPLIED, composed from the
// plan rather than re-read (one read per pass is the recursion guard the
// save hook relies on): the rows this pass imported and the slugs it named
// are eligible now, a clone or split waits for the next pass.
const named = new Map(backfill.map((row) => [row.id, row]));
const removed = new Set(plan.removals);
const applied = {
connections: [...graph.connections.map((connection) => ({ ...connection, ...(named.get(connection.id) || {}) })), ...plan.imports.connections],
bindings: [...graph.bindings, ...plan.imports.bindings],
routes: [...graph.routes.filter((route) => !removed.has(route.providerId)), ...plan.imports.routes],
};
const presets = await backfillPresets(applied, providers);
presetSkipReasons = new Map(presets.skipped.map(({ id, reason }) => [id, reason]));
// One service per backend (epic #7561): the import gave every harness its
// own row, so fold rows that provably reach one backend under one set of
// terms into a single instance. Row-derived and idempotent like the steps
// above — a folded graph plans nothing — so it rides every pass. It reads
// the same as-applied view, which a regroup (clone, split, in-place update)
// leaves stale, so a pass that moved rows leaves the fold to the next one.
const regrouped = plan.regroups.some((regroup) => regroup.connectionAction !== 'unchanged' || !regroup.bindingId);
const folded = regrouped ? 0 : await foldDuplicateServices(applied, presets.stamped.length > 0 ? null : providers);
const detached = plan.regroups.filter((regroup) => regroup.connectionAction === 'clone').length;
const split = plan.regroups.filter((regroup) => !regroup.bindingId).length;
if (!noop || plan.conflicts.length > 0 || presets.stamped.length > 0 || folded > 0) {
console.log(`🔗 Provider graph reconciled (${reason}): ${plan.imports.routes.length} imported, `
+ `${detached} detached, ${split} split, ${plan.removals.length} removed, `
+ `${plan.acknowledgements.length} acknowledged, ${plan.conflicts.length} conflicted, ${presets.stamped.length} presets derived, `
+ `${folded} services folded`);
}
for (const conflict of plan.conflicts) {
console.error(`⚠️ Provider route ${conflict.providerId} changed outside the graph mid-projection; `
+ 'leaving it untouched and blocking its binding until repaired');
}
return { activeProvider, plan, noop, presets };
}
/**
* The service-fold half of a pass: `planServiceInstanceMerges` over the graph
* as the steps above left it, applied one fold at a time. The provider file is
* re-read only when the preset backfill just wrote it (`current` is null), so
* the fold judges each record as derived or legacy by what it now is. Each
* fold's derived presets are re-pointed in `providers.json` BEFORE the rows
* move — they then name a slug that already exists, so a crash between the two
* writes leaves every record resolvable and the next pass re-plans the same
* fold. Writes through the toolkit directly, under the pass's latch, like
* {@link backfillPresets}. Local I/O only.
*
* @returns {Promise<number>} how many rows were folded away
*/
async function foldDuplicateServices(graph, current) {
const providers = current ?? (await providerService().getAllProviders()).providers;
// Only a preset naming a bootstrap app consults the table.
const bootstraps = providers.some((record) => record?.credentialBootstrapId) ? await bootstrapApps() : {};
const merges = planServiceInstanceMerges(graph, providers, { bootstraps, env: process.env });
for (const merge of merges) {
if (Object.keys(merge.presetPatches).length > 0) await providerService().applyProviderPatches(merge.presetPatches);
await mergeServiceInstances(merge);
console.log(`🔗 Provider graph: folded service(s) ${merge.absorbedSlugs.join(', ')} into ${merge.keeper.slug}`);
}
return merges.reduce((sum, merge) => sum + merge.absorbedIds.length, 0);
}
/**
* The preset backfill half of a pass (#7565). Writes through the toolkit
* directly: the caller already holds the `reconciling` latch for the whole
* pass, so the save hook this write fires returns immediately.
*
* @returns {Promise<{stamped: string[], skipped: {id: string, reason: string}[]}>}
*/
async function backfillPresets(graph, providers) {
// The bootstrap table is read only when a legacy record is routed at all.
const routed = new Set(graph.routes.map((route) => route.providerId));
if (!providers.some((record) => routed.has(record?.id) && !isDerivedPreset(record))) return { stamped: [], skipped: [] };
const { patches, skipped } = planPresetBackfill({ graph, providers, bootstraps: await bootstrapApps(), env: process.env });
const stamped = Object.keys(patches).length > 0 ? await providerService().applyProviderPatches(patches) : [];
if (stamped.length > 0) console.log(`🔗 Provider graph: derived ${stamped.length} preset(s) from their services (${stamped.join(', ')})`);
// Aggregate only: a reason names a record, never a value off it.
const legacy = skipped.filter(({ reason }) => reason !== 'unmapped').length;
if (legacy > 0) console.log(`🔗 Provider graph: ${legacy} routed record(s) stay legacy presets`);
return { stamped, skipped };
}
/**
* Re-derive every DERIVED preset on `connection` from the row as it now is,
* and write what changed (#7565). The complement of `projectRoutes`: that one
* carries the endpoint and credential through the pending/projected snapshot
* protocol, this one re-runs the whole materialization — the inline OpenCode
* config, the plan-filtered catalog, the bootstrap app — none of which the
* connection profile owns. Called from inside a serialized pass, after the row
* is saved; a preset whose derivation is refused (the service lost its
* endpoint, its bootstrap app was deleted) is left exactly as it was.
*
* @param {object} connection - the row as saved
* @param {{providerIds?: string[]|null}} [options] - the derived presets to re-derive
* ONTO this row (a binding that just moved here), instead of the ones already naming it
* @param {string|null} [options.resetPresetId] preset whose explicit refresh clears its model narrowing
* @returns {Promise<string[]>} the preset ids rewritten
*/
export async function rematerializeDerivedPresets(connection, { providerIds = null, resetPresetId = null } = {}) {
const instance = instanceForConnection(connection);
if (!instance) return [];
const [{ providers }, bootstraps] = await Promise.all([providerService().getAllProviders(), bootstrapApps()]);
const onRow = (record) => (providerIds ? providerIds.includes(record.id) : record.serviceId === connection.slug);
const patches = {};
for (const record of providers) {
if (!isDerivedPreset(record) || !onRow(record)) continue;
// A preset refresh explicitly replaces its model list. Service refreshes
// and sibling presets retain their declared narrowing.
const candidate = record.id === resetPresetId ? { ...record, catalogNarrowing: null } : record;
const patch = rederivePreset(candidate, { instance, catalog: connection.catalog, bootstraps, stored: record })?.patch;
if (patch && Object.keys(patch).length > 0) patches[record.id] = patch;
}
if (Object.keys(patches).length === 0) return [];
const written = await writeProviderPatches(patches);
if (written.length > 0) console.log(`🔗 Re-derived ${written.length} preset(s) from service ${connection.slug}`);
return written;
}
/**
* Refresh the cached preset-conversion verdict — {@link presetSkipReason} —
* for every LEGACY (not yet derived) record routed on `connection`, against
* `connection` AS JUST SAVED (#8159).
*
* `presetSkipReasons` is otherwise updated only by a full reconcile pass
* (`reconcilePass`, on boot or a `providers.json` write), so a connection
* SETTINGS edit — which changes nothing `onProvidersSaved` watches — left the
* "Convert to derived preset" gate answering against whatever the connection
* looked like at the last pass. Scoped to `connection`'s own routes rather
* than a whole-graph {@link planPresetBackfill}, because no OTHER route's
* verdict can have changed from this edit; and to {@link presetBackfillVerdict}
* rather than a write, because this is a read-cache refresh, not a conversion
* — an eligible record still needs its own reconcile pass or explicit
* "Convert" action to actually stamp.
*/
async function refreshPresetSkipReasonsForConnection(graph, connection) {
const boundBindings = new Set(
graph.bindings.filter((binding) => binding.connectionId === connection.id).map((binding) => binding.id),
);
const routes = graph.routes.filter((route) => boundBindings.has(route.bindingId));
if (routes.length === 0) return;
const { providers } = await providerService().getAllProviders();
const byId = new Map(providers.map((record) => [record.id, record]));
const legacy = routes
.map((route) => ({ route, record: byId.get(route.providerId) }))
.filter(({ record }) => record && typeof record === 'object' && !isDerivedPreset(record));
if (legacy.length === 0) return;
const instance = instanceForConnection(connection, process.env);
const bootstraps = await bootstrapApps();
for (const { route, record } of legacy) {
const { reason } = presetBackfillVerdict(record, { route, connection, instance, bootstraps, env: process.env });
if (reason) presetSkipReasons.set(record.id, reason);
else presetSkipReasons.delete(record.id);
}
}
/**
* A binding moved between instances (link, unlink): the derived presets on its
* routes now sit on `connection` and must say so. One re-derivation from the
* row they landed on writes the new `serviceId` with everything else.
*/
const repointDerivedPresets = (providerIds, connection) =>
(connection?.slug ? rematerializeDerivedPresets(connection, { providerIds }) : Promise.resolve([]));
/**
* Reconcile the graph against providers.json.
*
* `reconciling` is set for the WHOLE pass, not just its write: the retry path
* saves through the toolkit, which fires the same hook that calls this -- the
* latch is what keeps that from recursing.
*/
export function reconcileProviderGraph(reason = 'manual') {
if (!graphEnabled || reconciling) return Promise.resolve(null);
return serialize(() => {
reconciling = true;
return reconcilePass(reason).finally(() => { reconciling = false; });
});
}
/**
* Boot entry, called from the database phase once the schema is up.
*
* The first pass on an install with no graph rows imports every provider record
* -- including disabled and custom ones -- because each is simply "unmapped" to
* the planner. That keeps ONE code path responsible for import, crash recovery
* and downgrade reconciliation, so they cannot drift apart.
*/
export async function initProviderGraph() {
graphEnabled = true;
return reconcileProviderGraph('boot');
}
/**
* The toolkit's post-save hook (wired in `bootstrap.js`).
*
* An old client's `PATCH /api/providers/:id` knows nothing about the graph, so
* a connection-owned edit arrives here as a plain file change. Reconciliation
* detaches the affected binding rather than letting the edit silently repoint
* another harness's backend; a mode-only edit changes no connection-owned value
* and is therefore route-scoped and a no-op here; and a deleted record drops
* its row without being resurrected.
*/
export const onProvidersSaved = () => reconcileProviderGraph('legacy-write');
/**
* What one executable record contributes to its route's DTO: the overrides this
* mode carries, the effort ladder its harness really accepts, and — for a
* launchable TUI — the command line the Shell page would show.
*
* The command line is DISPLAY ONLY and its env half is dropped here: a launch
* goes through `shell:start { providerId }`, which re-resolves both server-side,
* so the provider's secret env never reaches a management payload.
*/
function describeRoute(provider) {
const settings = routeSettingsFor(provider);
return {
settings,
effortLevels: effortLevelsForProvider(provider, settings.defaultModel ?? null),
tuiCommandLine: buildTuiShellLaunch(provider)?.commandLine ?? null,
// The record's own model strings, so the DTO can say which hand-authored
// aliases name a spelling this route no longer carries (#6369).
storedModels: Array.isArray(provider?.models) ? provider.models : null,
};
}
/** The sanitized `GET /api/providers/management` body. */
export async function getManagementGraph() {
requireProviderGraph();
const [graph, data] = await Promise.all([readGraph(), providerService().getAllProviders()]);
// Only the records the graph actually routes: an unmapped legacy provider has
// no row to decorate, and resolving a shell invocation for it would be work
// this response throws away.
const byId = new Map(data.providers.map((provider) => [provider.id, provider]));
const routeSettings = new Map(graph.routes
.filter((route) => byId.has(route.providerId))
.map((route) => [route.providerId, describeRoute(byId.get(route.providerId))]));
return toManagementGraphDto({ ...graph, activeProvider: data.activeProvider, routeSettings });
}
// --- link / unlink -----------------------------------------------------------
export const requireProviderGraph = () => {
if (!graphEnabled) {
throw new ServerError('Provider connection graph is unavailable on this install', { status: 503, code: 'PROVIDER_GRAPH_UNAVAILABLE' });
}
};
const requireConnection = (graph, ref) => {
const connection = findConnectionByRef(graph, ref);
if (!connection) throw new ServerError('Connection not found', { status: 404, code: 'CONNECTION_NOT_FOUND' });
return connection;
};
const stale = (what) => new ServerError(
`${what} changed since the preview was taken; take a new preview`,
{ status: 409, code: 'PROVIDER_GRAPH_STALE_REVISION' });
/**
* Resolve and revision-check every row a link touches.
*
* All three revisions are checked -- binding, source connection and target
* connection -- because a link is a decision about a difference the human just
* reviewed. Any of the three moving invalidates that review, so a stale one is
* a 409 requiring a fresh preview rather than a last-writer merge.
*/
async function resolveLink({ bindingId, targetConnectionId = null, expectedRevisions = {} }) {
requireProviderGraph();
const graph = await readGraph();
const binding = graph.bindings.find((candidate) => candidate.id === bindingId);
if (!binding) throw new ServerError('Binding not found', { status: 404, code: 'BINDING_NOT_FOUND' });
const source = graph.connections.find((candidate) => candidate.id === binding.connectionId) || null;
const target = targetConnectionId ? findConnectionByRef(graph, targetConnectionId) : null;
if (targetConnectionId && !target) throw new ServerError('Connection not found', { status: 404, code: 'CONNECTION_NOT_FOUND' });
if (target && target.id === binding.connectionId) {
throw new ServerError('That binding already uses this connection', { status: 409, code: 'PROVIDER_GRAPH_ALREADY_LINKED' });
}
// A route mid-projection is precisely the state where the graph and the file
// disagree, so a link decided against it would be decided against unknown
// values. Refuse until reconciliation settles it.
if (graph.routes.some((route) => route.bindingId === bindingId && route.pending)) {
throw new ServerError('This binding has an unresolved projection and cannot be changed yet',
{ status: 409, code: 'PROVIDER_GRAPH_BINDING_BLOCKED' });
}
if (expectedRevisions.binding !== undefined && expectedRevisions.binding !== binding.revision) throw stale('The binding');
if (expectedRevisions.sourceConnection !== undefined && expectedRevisions.sourceConnection !== source?.revision) {
throw stale('The source connection');
}
if (target && expectedRevisions.targetConnection !== undefined && expectedRevisions.targetConnection !== target.revision) {
throw stale('The target connection');
}
return { graph, binding, source, target };
}
/** A connection row in the shape the endpoint comparator expects. */
const asProfile = (connection) => ({
kind: connection.kind,
protocol: Object.keys(connection.transports)[0] || null,
transports: connection.transports,
credentials: connection.credentials,
});
/**
* What linking this binding into `targetConnectionId` would change.
*
* Read-only and secret-free: the caller learns WHICH routes move, how the two
* backends differ (protocol / credentials / catalog), and which variant key the
* binding would land on -- never a credential, and never a comparison the
* browser could make itself.
*/
export async function previewBindingLink(input) {
const { graph, binding, source, target } = await resolveLink(input);
const routes = graph.routes.filter((route) => route.bindingId === binding.id);
const { differences } = compareBackendEndpoints(asProfile(source), asProfile(target));
const catalogDiffers = source.catalog.models.join('\u0000') !== target.catalog.models.join('\u0000');
return {
bindingId: binding.id,
revisions: { binding: binding.revision, sourceConnection: source.revision, targetConnection: target.revision },
affectedRouteIds: routes.map((route) => route.providerId),
variantKey: allocateVariantKey(graph, target.id, binding),
differences: catalogDiffers ? [...differences, 'catalog'] : differences,
// Union by canonical identity -- linking never drops a model either side saw.
unionModels: [...new Set([...source.catalog.models, ...target.catalog.models])],
// Applying is an explicit second call; a preview changes nothing.
requiresConfirmation: true,
};
}
/**
* The variant key `binding` may occupy on `connectionId`.
*
* `default` when free; otherwise a distinct labeled variant. Never a merge:
* two harness configurations sharing one connection are both legitimate, and
* collapsing them would discard one side's executable route ids.
*/
function allocateVariantKey(graph, connectionId, binding) {
const taken = new Set(graph.bindings
.filter((candidate) => candidate.connectionId === connectionId
&& candidate.harnessId === binding.harnessId
&& candidate.id !== binding.id)
.map((candidate) => candidate.variantKey));
return taken.has('default') ? `variant:${binding.id}` : 'default';
}
/**
* Repoint one binding at an existing connection, then project the target's
* connection-owned values into that binding's executable routes.
*
* Route ids, `activeProvider`, task pins and fallback references are untouched
* -- only the backend those routes reach changes, which is the whole point of a
* link. The projection runs through the pending-snapshot protocol so an
* interrupted file write is recoverable.
*/
export function linkBinding(input) {
return serialize(async () => {
const { graph, binding, target } = await resolveLink(input);
const routes = graph.routes.filter((route) => route.bindingId === binding.id);
await relinkBinding({ bindingId: binding.id, connectionId: target.id });
const applied = await projectRoutes(routes.map((route) => route.providerId), target);
await repointDerivedPresets(routes.map((route) => route.providerId), target);
console.log(`🔗 Linked binding ${binding.id} to connection ${target.id} (${applied.length} routes projected)`);
return { bindingId: binding.id, connectionId: target.id, affectedRouteIds: applied };
});
}
/**
* Give this binding its own copy of the connection it currently shares.
*
* The clone keeps the transports, credentials and catalog, so nothing about
* execution changes and no route needs rewriting; only the graph edge moves.
* Route ids and every mode setting are retained by construction.
*/
export function unlinkBinding(input) {
return serialize(async () => {
const { graph, binding, source } = await resolveLink({ ...input, targetConnectionId: null });
// A clone is a second INSTANCE of the same service, so it takes the next
// free slug rather than the source's — `uq_ai_connections_slug` would
// refuse the copy, and two rows answering to one address is the bug.
const taken = takenServiceSlugs(graph.connections);
const connection = {
...source,
id: randomUUID(),
revision: 1,
slug: allocateServiceSlug(source.slug ?? source.definitionId ?? source.kind, taken),
};
await detachBindingToConnection({ bindingId: binding.id, connection });
// A derived preset names its instance by slug, and the clone has a new one.
await repointDerivedPresets(graph.routes.filter((route) => route.bindingId === binding.id).map((route) => route.providerId), connection);
console.log(`🔗 Unlinked binding ${binding.id} onto its own connection ${connection.id}`);
return { bindingId: binding.id, connectionId: connection.id };
});
}
/**
* Delete a connection nothing binds any more.
*
* Reconciliation deliberately KEEPS an emptied connection rather than
* garbage-collecting it — a backend the user configured is not something to
* remove because a route was temporarily deleted. This is the explicit cleanup
* that keeps them from accumulating forever, and it is refused while a binding
* still names the row: unlink first, so no binding is ever silently orphaned.
*/
export async function removeConnection(connectionRef) {
requireProviderGraph();
return serialize(async () => {
const connectionId = requireConnection(await readGraph(), connectionRef).id;
const result = await deleteConnection(connectionId);
if (!result.deleted) {
throw new ServerError('Unlink the bindings that use this connection first',
{ status: 409, code: 'PROVIDER_GRAPH_CONNECTION_IN_USE' });
}
console.log(`🔗 Deleted unused provider connection ${connectionId}`);
return result;
});
}
/**
* Stage, write, acknowledge -- the three-step projection the crash-recovery
* contract depends on. Never call the steps separately.
*/
async function projectRoutes(providerIds, connection) {
const { providers } = await providerService().getAllProviders();
const byId = new Map(providers.map((provider) => [provider.id, provider]));
const projections = providerIds
.filter((providerId) => byId.has(providerId))
.map((providerId) => ({ providerId, owned: projectConnectionOwnedFields(byId.get(providerId), connection) }));
if (projections.length === 0) return [];
await commitPendingProjection(projections);
const written = await writeProviderPatches(Object.fromEntries(
projections.map(({ providerId, owned }) => [providerId, projectionPatch(byId.get(providerId), owned)]),
));
await acknowledgeProjection(written);
return written;
}
/**
* Write `providers.json` from INSIDE a serialized graph pass.
*
* The latch is load-bearing, not defensive: the toolkit's post-save hook calls
* back into `reconcileProviderGraph`, which queues behind the pass currently
* awaiting this write. Holding `reconciling` makes that call return
* immediately, so the pass cannot wait on work that is waiting on the pass.
*
* @param {Record<string, object>} patches - provider id → partial update
* @returns {Promise<string[]>} the ids that existed and were written
*/
function writeProviderPatches(patches) {
return duringProviderWrite(() => providerService().applyProviderPatches(patches));
}
/**
* Hold the re-entrancy latch across any provider-file write made from inside a
* serialized pass — a projection patch, or a freshly minted route.
*
* See {@link writeProviderPatches} for why this is load-bearing rather than
* defensive: the toolkit's post-save hook calls back into the graph, and
* without the latch that call would queue behind the pass awaiting this write.
*/
function duringProviderWrite(work) {
reconciling = true;
return Promise.resolve().then(work).finally(() => { reconciling = false; });
}
// --- explicit management edits (#6369) ---------------------------------------
//
// The three edits a human makes to a SHARED backend, as opposed to the link and
// unlink above which change which backend a harness reaches:
//
// 1. edit the connection once and have every attached route follow it,
// 2. refresh its model catalog once for every harness on it,
// 3. choose the subset of that catalog a harness offers.
//
// All three are revision-checked against exactly what the human was looking at,
// all three run on the same serialization queue as reconciliation, and none of
// them contacts an AI provider except (3)'s explicitly requested model list.
/** Locate a row the caller named, or 404. Never a partial match on a label. */
function requireRow(rows, id, what, code) {
const row = rows.find((candidate) => candidate.id === id);
if (!row) throw new ServerError(`${what} not found`, { status: 404, code });
return row;
}
/**
* Refuse a mutation while any of these routes is mid-projection.
*
* That state is precisely where the graph and `providers.json` disagree, so an
* edit decided against it would be decided against unknown values. Same guard
* `resolveLink` applies, applied to the connection's whole route set.
*/
function requireSettledRoutes(routes) {
if (routes.some((route) => route.pending)) {
throw new ServerError('This connection has an unresolved projection and cannot be changed yet',
{ status: 409, code: 'PROVIDER_GRAPH_BINDING_BLOCKED' });
}
}
/** Every binding on a connection, and the executable routes those bindings own. */
export function connectionFanout(graph, connectionId) {
const bindings = graph.bindings.filter((binding) => binding.connectionId === connectionId);
const bindingIds = new Set(bindings.map((binding) => binding.id));
return { bindings, routes: graph.routes.filter((route) => bindingIds.has(route.bindingId)) };
}
/**
* Edit one shared backend: its label, its transports, its credentials.
*
* This is the whole point of the graph — the endpoint and secret a human
* changes here are materialized into EVERY route on the connection in one
* projection, instead of being retyped per harness and drifting. Route ids,
* mode settings, pins, `activeProvider` and fallback references are untouched.
*
* A stale `expectedRevision` is a 409, not a last-writer merge: the human was
* editing values they had read, and a moved row means they were not.
*
* `transports` replaces the map WHOLESALE rather than merging into it, so
* dropping a protocol is expressible. That is why the editor renders one field
* per declared transport and sends them all back: a client that sends a partial
* map is asking to remove the rest.
*/
export function updateConnectionSettings({
connectionId, expectedRevision, label, transports, credentials, plan, enabled, credentialVia,
}) {
return serialize(async () => {
requireProviderGraph();
const graph = await readGraph();
const connection = requireConnection(graph, connectionId);
if (connection.revision !== expectedRevision) throw stale('The connection');
const definition = connection.definitionId ? serviceDefinitionById(connection.definitionId) : null;
// A row with no definition takes any plan: there is nothing to check it
// against, and refusing would strand a legacy row a human is labelling.
if (plan !== undefined && definition) assertServicePlan(definition, plan);
if (credentialVia !== undefined && !SERVICE_CREDENTIAL_VIAS.includes(credentialVia)) {
throw new ServerError(`credentialVia must be one of ${SERVICE_CREDENTIAL_VIAS.join(', ')}`,
{ status: 400, code: 'PROVIDER_SERVICE_CREDENTIAL_VIA_INVALID' });
}
const { routes } = connectionFanout(graph, connection.id);
requireSettledRoutes(routes);
const merged = mergeConnectionCredentials(connection.credentials, credentials);
if (merged.rejected.length > 0) {
throw new ServerError(
`Send the real value or null for ${merged.rejected.join(', ')} — a redacted placeholder is not a credential`,
{ status: 400, code: 'PROVIDER_GRAPH_REDACTED_CREDENTIAL' });
}
const nextVia = credentialVia ?? connection.credentialVia;
const next = {
...connection,
label: label ?? connection.label,
transports: transports ?? connection.transports,
// A `bootstrap` instance stores no secret by definition: the launch
// wrapper supplies it at spawn. Switching to it drops whatever was held.
credentials: nextVia === 'bootstrap' ? {} : merged.credentials,
plan: plan ?? connection.plan,
enabled: enabled ?? connection.enabled,
credentialVia: nextVia,
};
const revision = await saveConnectionSettings(next);
const saved = { ...next, revision: revision ?? next.revision };
const applied = await projectRoutes(routes.map((route) => route.providerId), next);
// The derived presets on this instance follow the whole row, not only the
// profile-owned half the projection carried (#7565).
const rederived = await rematerializeDerivedPresets(saved);
// This connection's still-legacy routes may have just become convertible,
// or stopped being — keep `presetSkipReason` current rather than leaving
// it to the next full reconcile pass, which this write never triggers (#8159).
await refreshPresetSkipReasonsForConnection(graph, saved);
console.log(`🔗 Updated connection ${connection.id} (${applied.length} routes projected, ${rederived.length} presets re-derived)`);
return { connectionId: connection.id, revision, affectedRouteIds: [...new Set([...applied, ...rederived])] };
});
}
/**
* Choose which of the shared catalog a harness offers, and rename the binding.
*
* Management state only — nothing here is projected into an executable record,
* so choosing a subset can never enable a route, grant a mode's execution
* consent, or repoint a saved selection. A pin outside the new subset stays
* exactly where it was and simply reads as stale, which is what keeps a
* narrowed catalog from silently repicking somebody's model.
*/
export function updateBindingSettings({ bindingId, expectedRevision, label, selectedModels }) {
return serialize(async () => {
requireProviderGraph();
const graph = await readGraph();
const binding = requireRow(graph.bindings, bindingId, 'Binding', 'BINDING_NOT_FOUND');
if (binding.revision !== expectedRevision) throw stale('The binding');
requireSettledRoutes(graph.routes.filter((route) => route.bindingId === binding.id));
const next = {
id: binding.id,
label: label ?? binding.label,
selectedModels: selectedModels ?? binding.selectedModels,
};
const revision = await saveBindingSettings(next);
return { bindingId: binding.id, revision, label: next.label, selectedModels: next.selectedModels };
});
}
/**
* Refresh the shared model catalog — ONE probe per backend, not one per route.
*
* `refreshProviderModelsBatch` groups the connection's routes by daemon and
* probe shape, so a connection carrying Claude CLI, Claude TUI and OpenCode
* routes is asked once and written once. It never throws for a per-route
* failure, which is what lets a partial answer stay a partial answer.
*
* The failure rule is the one this endpoint exists for: **a failed probe keeps
* the models the connection already knew**, with a sanitized reason attached.
* A successful probe that returns nothing writes `known` with an empty list —
* a backend whose last model was deleted is a real answer, not "never asked".
* No pin, default or `activeProvider` is repicked either way.
*/
export function refreshConnectionCatalog(connectionRef) {
return serialize(async () => {
requireProviderGraph();
const graph = await readGraph();
const connection = requireConnection(graph, connectionRef);
const { routes } = connectionFanout(graph, connection.id);
if (routes.length === 0) {
throw new ServerError('This connection has no executable route to probe',
{ status: 409, code: 'PROVIDER_GRAPH_CONNECTION_UNROUTED' });
}
const groups = await providerService().refreshProviderModelsBatch(routes.map((route) => route.providerId));
const failures = groups.filter((group) => group.status === 'failed');
const refreshed = groups.some((group) => group.status === 'updated');
// Canonical names come from the records as they are AFTER the write, so the
// catalog and each route's alias map describe the same observation.
const { providers } = await providerService().getAllProviders();
const byId = new Map(providers.map((provider) => [provider.id, provider]));
const refreshedRoutes = [];
for (const route of routes) {
const provider = byId.get(route.providerId);
if (!provider) continue;
const { modelMap } = resolveRouteModels(provider);
// Only the OBSERVED half is written back. The user's overrides stay in
// their own column, which is what lets a hand-authored alias outlast this
// refresh — but they still count towards the shared catalog below,
// because a correction that no model menu offers has corrected nothing.
await saveRouteModelMap(route.providerId, modelMap);
refreshedRoutes.push({ ...route, modelMap });
}
const models = connectionCatalogModels(refreshedRoutes);
// A failure is reported whether or not another group succeeded: a partial
// answer is still a harness that cannot reach this backend.
const error = failures.length > 0
? sanitizeCatalogError(failures[0].error, connection.credentials)
: null;
const catalog = nextConnectionCatalog(connection.catalog,
refreshed ? { refreshed: true, models, error } : { refreshed: false, error });
await saveConnectionSettings({ ...connection, catalog });
console.log(`🔗 Refreshed connection ${connection.id} catalog: ${catalog.state}, `
+ `${catalog.models.length} models across ${groups.length} probe groups (${failures.length} failed)`);
return { connectionId: connection.id, catalog, probedGroups: groups.length, failedGroups: failures.length };
});
}
/**
* Edit ONE route's mode overrides — its args, timeout, effort and model pins.
*
* The counterpart to `updateConnectionSettings`: that one changes a value every
* harness on the backend shares, this one changes a value that belongs to a
* single execution mode. Both live on this screen so a human stops bouncing
* between a connection and three route editors to configure one backend.
*
* Three rules make it a genuine OVERRIDE rather than a second way to edit a
* provider:
*
* - **No sibling fan-out.** The write goes through `applyProviderPatches`,
* which names exactly this route. `updateProvider` would spread the edit
* onto the record's sibling modes, and a CLI route's `--effort` is not the
* TUI route's.
* - **No connection-owned field is reachable.** The accepted key set is the
* route-owned table in `providerRouteSettings.js`, so an endpoint or a
* credential can never be retyped here and silently escape the projection
* that keeps every other harness on the backend in step.
* - **No execution consent.** `enabled` and the transport opt-ins are absent
* from that table; granting them stays an explicit act on the route editor.
*
* The stale check is a fingerprint of the values as they are ON DISK, so an
* edit made in `/ai/edit/:providerId` while this panel was open is caught too —
* see `routeSettingsRevision`.
*/
export function updateRouteSettings({ providerId, expectedRevision, settings }) {
return serialize(async () => {
requireProviderGraph();
const graph = await readGraph();
const route = graph.routes.find((candidate) => candidate.providerId === providerId);
if (!route) throw new ServerError('Route not found', { status: 404, code: 'ROUTE_NOT_FOUND' });
requireSettledRoutes([route]);
const { providers } = await providerService().getAllProviders();
const provider = providers.find((candidate) => candidate.id === providerId);
// A graph row whose record is gone is a reconciliation removal in flight.
// Reported as the same 404, because there is nothing left to override.
if (!provider) throw new ServerError('Route not found', { status: 404, code: 'ROUTE_NOT_FOUND' });
const current = routeSettingsFor(provider);
if (routeSettingsRevision(current) !== expectedRevision) throw stale("This route's settings");
const unsupported = unsupportedRouteSettings(route.mode, settings);
if (unsupported.length > 0) {
throw new ServerError(`A ${route.mode} route has no ${unsupported.join(', ')} setting`,
{ status: 400, code: 'PROVIDER_ROUTE_SETTING_UNSUPPORTED' });
}
// Effort is a harness capability, not free text: a route whose program takes
// no `--effort` gets no control, and a level outside its ladder would be
// stored and then silently dropped at spawn time.
if (settings.effort != null) {
const levels = effortLevelsForProvider(provider, settings.defaultModel ?? current.defaultModel ?? null);
if (!levels || !levels.includes(settings.effort)) {
throw new ServerError(
levels
? `This route accepts effort ${levels.join(', ')}`
: 'This route\'s harness takes no effort setting',
{ status: 400, code: 'PROVIDER_ROUTE_EFFORT_UNSUPPORTED' });
}
}
const next = { ...current, ...settings };
const applied = await writeProviderPatches({ [providerId]: settings });
if (applied.length === 0) throw new ServerError('Route not found', { status: 404, code: 'ROUTE_NOT_FOUND' });
// No graph row is touched on purpose. These fields are route-owned, so the
// connection's `projected` snapshot still describes the record accurately
// and the binding must NOT be detached — the reconcile this write triggers
// is a documented no-op.
console.log(`🔗 Updated route ${providerId} overrides: ${Object.keys(settings).join(', ')}`);
return { providerId, settings: next, settingsRevision: routeSettingsRevision(next) };
});
}
/**
* Edit ONE route's hand-authored model aliases (#6369).
*
* The correction surface for `modelMap`. A refresh only ever records the
* aliases it could VERIFY — a stored model string round-trips through the
* harness's own adapter or it is reported unresolved rather than rewritten — so
* a bare `example-model` on an OpenCode route that needs its `<namespace>/`
* prefix resolves to nothing, reaches no catalog, and can be offered by no
* model menu. Naming the pair by hand is the repair.
*
* The merge rule, which is the whole design decision behind this endpoint:
*
* - Observed aliases and user overrides live in SEPARATE columns. A refresh
* rewrites the observed one wholesale and never touches the other, so an
* override survives every refresh and is removed only by the person who
* wrote it (`null` for its key).
* - The effective map is `{ ...observed, ...overrides }` — an override wins.
* - An override naming a spelling the record no longer lists is KEPT and
* reported stale, the same way a model pin outside the catalog is.
*
* The connection's catalog is re-derived here from the maps already stored,
* because an alias that no model menu offers has fixed nothing. That is a pure
* recompute: no backend is probed, `state` and `error` are preserved, and a
* failed catalog keeps reading as failed.
*
* Stale-checked with a fingerprint of the overrides rather than a row revision,
* for the reason `routeSettingsRevision` documents: `ai_route_bindings` has no
* revision column, and a hash of the values catches every writer.
*/
export function updateRouteModelAliases({ providerId, expectedRevision, aliases }) {
return serialize(async () => {
requireProviderGraph();
const graph = await readGraph();
const route = graph.routes.find((candidate) => candidate.providerId === providerId);
if (!route) throw new ServerError('Route not found', { status: 404, code: 'ROUTE_NOT_FOUND' });
requireSettledRoutes([route]);
if (modelAliasRevision(route.modelAliasOverrides) !== expectedRevision) {
throw stale("This route's model aliases");
}
const { aliases: overrides, removed } = applyModelAliasPatch(route.modelAliasOverrides, aliases);
await saveRouteModelAliases(providerId, overrides);
// Re-derive the shared catalog from every route on this backend, reading
// the row we just wrote rather than the stale one the graph read.
const bindingConnectionId = graph.bindings.find((binding) => binding.id === route.bindingId)?.connectionId;
const connection = graph.connections.find((candidate) => candidate.id === bindingConnectionId);
if (connection) {
const { routes } = connectionFanout(graph, connection.id);
const models = connectionCatalogModels(routes.map((entry) => (entry.providerId === providerId
? { ...entry, modelAliasOverrides: overrides }
: entry)));
await saveConnectionSettings({ ...connection, catalog: { ...connection.catalog, models } });
}
console.log(`🔗 Updated route ${providerId} model aliases: `
+ `${Object.keys(overrides).length} kept, ${removed.length} removed`);
return {
providerId,
modelMap: effectiveModelAliases(route.modelMap, overrides),
modelAliasOverrides: overrides,
modelAliasRevision: modelAliasRevision(overrides),
};
});
}
// --- creating a backend and a harness on it (#6369) ---------------------------
//
// The two writes that ADD to the graph rather than editing it. Both are local
// I/O only: creating a backend probes nothing, and creating a harness binding
// mints DISABLED routes — configuration never generates, never launches and
// never grants execution consent (AGENTS.md "No cold-bootstrap LLM calls").
/**
* Create a new backend connection.
*
* Deliberately NOT deduplicated against the connections already stored. Two
* backends that look identical — same vendor, same model names, even the same
* URL reached differently — are still two backends until a human says
* otherwise, and inferring otherwise is exactly what the identity rules in
* `providerConnections.js` exist to forbid. Linking stays an explicit,
* previewed act.
*
* The catalog starts `unknown`, not empty: nothing has been asked yet, and
* `[]` would claim a backend with no models. Discovery is the separate,
* explicitly requested `POST /connections/:id/refresh-models`.
*/
export function createConnection({ kind, label, transports, credentials }) {
return serialize(async () => {
requireProviderGraph();
const blocker = connectionBlocker({ kind, transports });
if (blocker) throw new ServerError(blocker.message, { status: 400, code: blocker.code });
const graph = await readGraph();
const connection = {
id: randomUUID(),
revision: 1,
kind,
label,
transports,
credentials: credentials || {},
catalog: { state: 'unknown', models: [] },
// Named as a service instance from the start (#7563), so the row is
// addressable without waiting for the next reconcile pass.
...serviceColumnsForConnection({ kind }, { taken: takenServiceSlugs(graph.connections) }),
enabled: true,
credentialVia: 'stored',
};
await writeGraph({ connections: [connection], bindings: [], routes: [] });
console.log(`🔗 Created provider connection ${connection.id} (${kind}, no routes yet)`);
return { connection: toConnectionDto(connection) };
});
}
/**
* Create a harness binding on an existing backend, plus one executable route
* per requested mode.
*
* This is the create the whole registry work was blocked on: minting a route
* needs a per-harness COMMAND RECIPE (`PROVIDER_HARNESSES[].recipe`), because
* the graph could previously only classify records it was handed, never
* describe how to spawn a fresh one.
*
* Three guarantees, in the order they are enforced:
*
* 1. **Refuse before writing.** `bindingBlocker` rejects a harness with no
* recipe, a mode it has no support for, a backend whose transport it does
* not speak, and a backend missing a credential the program requires.
* 2. **A minted route must sit on the connection it was minted for.** The
* record is fed straight back through `providerConnectionProfile` and
* checked with `routeBelongsOnConnection` — the SAME containment test
* reconciliation applies, so a create is judged on exactly the terms the
* next pass will judge it by. A route the row does not contain is refused
* rather than stored, because reconciliation would otherwise clone the
* binding onto a connection of its own on the very next pass. Containment
* rather than identity is what lets one route be minted on a backend that
* declares a second protocol for another harness (#6460).
* 3. **Nothing is enabled.** The binding and every route arrive disabled with
* no model pins and no transport consent. Enabling stays an explicit act
* on the route editor, which is where granting execution belongs.
*
* The `projected` snapshot is read back off the records the toolkit actually
* wrote, so the graph starts in agreement with `providers.json` and the
* reconcile this write triggers is a no-op.
*/
export function createBinding({ connectionId, harnessId, modes, label }) {
return serialize(async () => {
requireProviderGraph();
const graph = await readGraph();
const connection = requireConnection(graph, connectionId);
// A backend mid-projection is precisely where the graph and providers.json
// disagree about the endpoint and credentials this route would be built
// from, so a new route decided against it would be built from values still
// in dispute. Same guard every other mutation on a connection applies.
requireSettledRoutes(connectionFanout(graph, connection.id).routes);
const blocker = bindingBlocker({ harnessId, modes, connection });
if (blocker) {
const badRequest = blocker.code === 'PROVIDER_HARNESS_NOT_CREATABLE'
|| blocker.code === 'PROVIDER_HARNESS_MODE_UNSUPPORTED';
throw new ServerError(blocker.message, { status: badRequest ? 400 : 409, code: blocker.code });
}
const { providers, activeProvider } = await providerService().getAllProviders();
const taken = new Set([...providers.map((provider) => provider.id), ...graph.routes.map((route) => route.providerId)]);
const ids = mintRouteIds({ harnessId, kind: connection.kind, modes, taken });
const harnessLabel = harnessId ? harnessById(harnessId).label : 'Direct API';
const name = label || `${harnessLabel} · ${connection.label || connectionKindLabel(connection.kind)}`;
const records = modes.map((mode) => buildRouteRecord({
harnessId,
mode,
providerId: ids[mode],
name: modeSiblingName(name, mode),
connection,
}));
for (const record of records) {
if (!routeBelongsOnConnection(providerConnectionProfile(record), connection)) {
throw new ServerError(
`A ${harnessLabel} route cannot describe this backend as it is configured; adjust the backend's transport or credentials first`,
{ status: 409, code: 'PROVIDER_GRAPH_CONNECTION_INCOMPATIBLE' });
}
}
const bindingId = randomUUID();
const binding = {
id: bindingId,
revision: 1,
connectionId: connection.id,
harnessId,
// `default` when this harness is not already on the backend, a labeled
// variant otherwise — two configurations of one program on one backend
// are both legitimate and must not collapse into each other.
variantKey: allocateVariantKey(graph, connection.id, { id: bindingId, harnessId }),
label: name,
enabled: false,
selectedModels: [],
};
// If a create fails part-way, the records that landed simply have no graph
// row yet — the next reconciliation pass imports them as their own fragment
// rather than losing them. That is the same path a legacy write takes.
await duringProviderWrite(async () => {
for (const record of records) await providerService().createProvider(record);
});
const { providers: written, activeProvider: activeAfter } = await providerService().getAllProviders();
const byId = new Map(written.map((provider) => [provider.id, provider]));
const routes = modes
.filter((mode) => byId.has(ids[mode]))
.map((mode) => ({
providerId: ids[mode],
bindingId: binding.id,
mode,
modelMap: {},
modelAliasOverrides: {},
projected: connectionOwnedSnapshot(byId.get(ids[mode])),
pending: null,
pendingRevision: null,
}));
await writeGraph({ connections: [], bindings: [binding], routes });
console.log(`🔗 Created ${harnessLabel} binding ${binding.id} on connection ${connection.id}: `
+ `${routes.map((route) => route.providerId).join(', ')} (disabled)`);
return {
connectionId: connection.id,
bindingId: binding.id,
harnessId,
variantKey: binding.variantKey,
label: binding.label,
enabled: false,
routeIds: routes.map((route) => route.providerId),
// Reported rather than hidden: the toolkit adopts the first route as the
// system default on an install that has none, and a disabled route being
// named the default grants no execution — but the caller should still be
// told its default moved.
activeProvider: activeAfter ?? null,
activeProviderChanged: (activeAfter ?? null) !== (activeProvider ?? null),
};
});
}