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 { z } from 'zod';
import { providerModeGroups } from './aiToolkit/internal/providerModes.js';
import {
CONNECTION_ISOLATION_REASONS,
CONNECTION_PROTOCOLS,
compareBackendEndpoints,
connectionBucketKey,
providerConnectionProfile,
sameConnectionIdentity,
withConnectionOwnedFields,
withoutConnectionOwnedFields,
} from './providerConnections.js';
import {
PROVIDER_HARNESS_IDS,
ROUTE_MODES,
graphHarnessId,
harnessForProvider,
harnessSupportsMode,
providerRouteMode,
toCanonicalModelName,
} from './providerHarnesses.js';
import { isConfiguredDefaultModel } from './providerModels.js';
/**
* READ-ONLY import preview for the provider connection graph proposed in
* `docs/plans/2026-09-06-provider-connections-and-harnesses.md` (#6366).
*
* Given the provider records this install already runs, this answers what
* connections, harness bindings and executable routes an import WOULD create —
* and which records it would refuse to touch, with reasons. It persists
* nothing, migrates nothing, and changes no execution path. Slices #6367-#6369
* add the durable graph, the routing policy and the management UI on top.
*
* Two invariants make the preview trustworthy rather than merely informative:
*
* 1. **Every original route ID survives.** `routes` has exactly one entry per
* input provider, and {@link projectPreviewToProviders} reconstructs each
* original record — settings, pins, secrets and unknown custom fields
* included. A preview that cannot round-trip an install is a preview that
* would lose data on import.
* 2. **Automatic grouping is limited to PROVEN same-harness siblings.** The
* binding grouping is `providerModeGroups` — the already-shipped
* CLI/TUI pairing — and nothing else. Two harnesses reaching one daemon
* are surfaced in `suggestedLinks`, never merged: cross-harness sharing
* requires an explicit link in a later slice.
*
* Nothing here performs I/O. Building a preview must never make a generation
* call, probe a backend or launch a runtime.
*/
/** Wire version of the management DTOs. Bump with any breaking shape change. */
export const PROVIDER_GRAPH_SCHEMA_VERSION = 1;
/** Model pins a route can carry, in the order the management UI shows them. */
export const ROUTE_MODEL_PINS = Object.freeze([
'defaultModel',
'lightModel',
'mediumModel',
'heavyModel',
'ultraModel',
'fallbackModel',
]);
/** Why a route is not eligible to execute in its own mode. */
export const ROUTE_ELIGIBILITY_REASONS = Object.freeze([
'mode-unsupported',
'mode-not-allowed',
'route-disabled',
'consent-required',
]);
/** Why a stored model string or pin could not be resolved to the catalog. */
export const MODEL_RESOLUTION_REASONS = Object.freeze([
'unmappable-model-alias',
'pin-not-in-catalog',
]);
// --- version-1 management DTOs ----------------------------------------------
// `.strict()` throughout is a boundary guard, not tidiness: a field added to a
// provider record must never ride out to a client because a builder forgot to
// drop it. Validation failure is a bug in this module, so it throws.
const transportSchema = z.object({ baseUrl: z.string().min(1) }).strict();
// A record keyed by an enum is EXHAUSTIVE in zod 4 — every protocol would
// become required. A connection declares only the protocols it actually
// speaks, so the key set is checked rather than enumerated.
const transportsSchema = z.record(z.string(), transportSchema)
.refine((value) => Object.keys(value).every((protocol) => CONNECTION_PROTOCOLS.includes(protocol)),
{ message: `transports keys must be one of: ${CONNECTION_PROTOCOLS.join(', ')}` });
const connectionDtoSchema = z.object({
id: z.string().min(1),
revision: z.number().int().positive(),
kind: z.string().min(1),
label: z.string(),
transports: transportsSchema,
hasCredentials: z.boolean(),
catalog: z.object({
state: z.enum(['unknown', 'known', 'failed']),
models: z.array(z.string()),
}).strict(),
}).strict();
const bindingDtoSchema = z.object({
id: z.string().min(1),
revision: z.number().int().positive(),
variantKey: z.string().min(1),
connectionId: z.string().min(1),
harnessId: z.enum(PROVIDER_HARNESS_IDS).nullable(),
label: z.string(),
enabled: z.boolean(),
selectedModels: z.array(z.string()),
}).strict();
const routeDtoSchema = z.object({
providerId: z.string().min(1),
bindingId: z.string().min(1).nullable(),
mode: z.enum(ROUTE_MODES).nullable(),
modelMap: z.record(z.string(), z.string()),
unresolvedModels: z.array(z.object({
model: z.string(),
reason: z.enum(MODEL_RESOLUTION_REASONS),
}).strict()),
unresolvedPins: z.array(z.object({
pin: z.enum(ROUTE_MODEL_PINS),
model: z.string(),
reason: z.enum(MODEL_RESOLUTION_REASONS),
}).strict()),
eligibility: z.object({
mode: z.enum(ROUTE_MODES).nullable(),
supported: z.boolean(),
enabled: z.boolean(),
consentRequired: z.boolean(),
consentGranted: z.boolean(),
eligible: z.boolean(),
reasons: z.array(z.enum(ROUTE_ELIGIBILITY_REASONS)),
}).strict(),
}).strict();
const unresolvedDtoSchema = z.object({
providerId: z.string().min(1),
reasons: z.array(z.object({
code: z.enum(CONNECTION_ISOLATION_REASONS),
detail: z.string(),
}).strict()),
}).strict();
const suggestedLinkDtoSchema = z.object({
connectionIds: z.array(z.string().min(1)).length(2),
harnessIds: z.array(z.enum(PROVIDER_HARNESS_IDS).nullable()).length(2),
reason: z.literal('same-backend-endpoint'),
differences: z.array(z.string()),
requiresExplicitLink: z.literal(true),
}).strict();
/** The full `GET /api/providers/management/preview` body. */
export const managementPreviewSchema = 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),
unresolved: z.array(unresolvedDtoSchema),
suggestedLinks: z.array(suggestedLinkDtoSchema),
}).strict();
// --- builder ----------------------------------------------------------------
/** Attach secret-bearing internals so a stray `JSON.stringify` cannot leak them. */
function hide(target, props) {
for (const [key, value] of Object.entries(props)) {
Object.defineProperty(target, key, { value, enumerable: false, configurable: true });
}
return target;
}
/**
* Whether this route may execute in its own mode, from the record alone.
*
* Deliberately NOT a routing policy — prerequisite probes and fallback
* candidate selection need host I/O and belong to #6368. This is the pure,
* declarative half: the harness supports the mode, the route is enabled, the
* caller allows the mode, and any text-transport consent has been granted.
* `allowedModes` is the caller's intersection; a CLI-only caller passing
* `['cli']` can never receive a TUI route through it.
*
* @param {object} provider
* @param {{allowedModes?: readonly string[]}} [options]
*/
export function routeModeEligibility(provider, { allowedModes = ROUTE_MODES } = {}) {
const mode = providerRouteMode(provider);
const harness = harnessForProvider(provider);
// An `api` record is a direct API binding with no harness, so `api` support
// comes from the record's own type rather than a harness row.
const supported = mode === 'api' ? provider?.type === 'api' : harnessSupportsMode(harness?.id, mode);
const enabled = provider?.enabled !== false;
const consentRequired = typeof provider?.textTransport === 'string' && provider.textTransport !== '';
const consentGranted = provider?.textTransportEnabled === true;
const reasons = [];
if (!supported) reasons.push('mode-unsupported');
if (mode && !allowedModes.includes(mode)) reasons.push('mode-not-allowed');
if (!enabled) reasons.push('route-disabled');
if (consentRequired && !consentGranted) reasons.push('consent-required');
return { mode, supported, enabled, consentRequired, consentGranted, eligible: reasons.length === 0, reasons };
}
/**
* Canonical/executable model mapping, plus every stored alias that would not
* resolve.
*
* An alias resolves only when the harness's own adapter maps the candidate back
* to the exact stored string, so a bare `example-model` saved on an OpenCode
* route — which needs its `<namespace>/` prefix to execute, and could equally
* be a fully-qualified id for some other backend — is reported rather than
* rewritten. That verified round-trip is also why two DIFFERENT stored strings
* can never claim one canonical name: `modelMap` is keyed by canonical, so a
* literal duplicate collapses and nothing else can collide.
*/
export function resolveRouteModels(provider) {
const stored = Array.isArray(provider?.models) ? provider.models : [];
const modelMap = {};
const unresolvedModels = [];
for (const entry of stored) {
const { canonical, executable, resolved, reason } = toCanonicalModelName(provider, entry);
if (resolved) modelMap[canonical] = executable;
else if (!unresolvedModels.some((u) => u.model === entry)) unresolvedModels.push({ model: entry, reason });
}
const unresolvedPins = ROUTE_MODEL_PINS
.filter((pin) => typeof provider?.[pin] === 'string' && provider[pin] !== ''
&& !isConfiguredDefaultModel(provider[pin])
&& stored.length > 0 && !stored.includes(provider[pin]))
.map((pin) => ({ pin, model: provider[pin], reason: 'pin-not-in-catalog' }));
return { modelMap, unresolvedModels, unresolvedPins };
}
/** A record's model catalog as a connection-level catalog with an honest state. */
function connectionCatalog(models) {
// `[]` on a provider record cannot distinguish "never fetched" from
// "fetched and legitimately empty", so it reads as `unknown` rather than
// claiming a successful empty result the record does not attest to.
return models.length > 0 ? { state: 'known', models } : { state: 'unknown', models: [] };
}
/**
* Build the read-only import preview for a set of provider records.
*
* @param {{providers?: object[], activeProvider?: string|null}} data
* @returns {object} preview — secret-bearing internals are non-enumerable
*/
export function buildProviderGraphPreview({ providers = [], activeProvider = null } = {}) {
const records = Array.isArray(providers) ? providers.filter((p) => p && typeof p === 'object' && p.id) : [];
const connections = [];
const bindings = [];
const routes = [];
const unresolved = [];
const buckets = new Map();
const variantsByBinding = new Map();
const isolate = (group, reasons) => {
for (const provider of group) {
unresolved.push({ providerId: provider.id, reasons });
routes.push(hide({
providerId: provider.id,
bindingId: null,
...resolveRouteModels(provider),
mode: providerRouteMode(provider),
eligibility: routeModeEligibility(provider),
}, { record: provider, routeRecord: provider, owned: null }));
}
};
for (const group of providerModeGroups(records)) {
const lead = group.find((provider) => provider.type === 'cli') || group[0];
const harness = harnessForProvider(lead);
const profiles = group.map((provider) => providerConnectionProfile(provider));
const leadProfile = profiles[group.indexOf(lead)];
// A sibling whose transport or credentials read differently from the lead's
// is not the same connection, however conventional its id looks.
const reasons = profiles.flatMap((profile) => profile.reasons);
if (profiles.some((profile) => !sameConnectionIdentity(profile, leadProfile))) {
reasons.push({ code: 'sibling-configuration-mismatch', detail: 'siblings disagree on backend kind, transport or credentials' });
}
// A record whose `type` names no executable mode cannot become a route.
for (const provider of group.filter((candidate) => !providerRouteMode(candidate))) {
reasons.push({ code: 'unknown-harness', detail: `unsupported type: ${provider.type ?? ''}` });
}
if (reasons.length > 0) {
isolate(group, reasons);
continue;
}
// The registry names a direct API record's harness `direct` (#7562); the
// graph stores it as `NULL`, and this is the one translation point.
const harnessId = graphHarnessId(harness?.id);
const bucketKey = connectionBucketKey(harnessId, leadProfile);
const bucket = buckets.get(bucketKey) || [];
// A record that declares NO transport (a vendor subscription harness, say)
// offers no evidence about which backend it reaches, so it never shares a
// connection with another group — matching endpoints is the only thing that
// may make two records one connection, and "both named nothing" is not a
// match. Its connection is exclusive to this binding.
const sharable = Object.keys(leadProfile.transports).length > 0;
let connection = sharable
? bucket.find((candidate) => sameConnectionIdentity(candidate.profile, leadProfile))
: null;
if (!connection) {
connection = hide({
id: `conn:${harnessId ?? 'api'}:${lead.id}`,
revision: 1,
kind: leadProfile.kind,
label: String(lead.name || lead.id),
transports: leadProfile.transports,
hasCredentials: Object.keys(leadProfile.credentials).length > 0,
catalog: connectionCatalog([]),
}, { profile: leadProfile, harnessId });
connections.push(connection);
if (sharable) buckets.set(bucketKey, [...bucket, connection]);
}
// The connection's catalog is the union of what its bindings observe, by
// canonical name — a shared catalog, never a per-route one.
const resolvedModels = group.map((provider) => resolveRouteModels(provider));
const unionModels = [...new Set([
...connection.catalog.models,
...resolvedModels.flatMap((resolved) => Object.keys(resolved.modelMap)),
])];
connection.catalog = connectionCatalog(unionModels);
// UNIQUE(connection_id, harness_id, variant_key): the first binding on a
// connection is `default`; a second custom configuration of the same
// harness on the same connection is a distinct labeled variant, never a
// merge that would discard one of its executable route IDs.
const variantScope = `${connection.id}|${harnessId ?? ''}`;
const taken = variantsByBinding.get(variantScope) || [];
// Prefixed so a provider literally named `default` cannot collide with the
// first binding's reserved key.
const variantKey = taken.length === 0 ? 'default' : `variant:${lead.id}`;
variantsByBinding.set(variantScope, [...taken, variantKey]);
const binding = {
id: `binding:${lead.id}`,
revision: 1,
variantKey,
connectionId: connection.id,
harnessId,
label: String(lead.name || lead.id),
// OR across proven siblings, matching `unifyProviderModes`. Consent flags
// never participate — they are per-route and never granted by grouping.
enabled: group.some((provider) => provider.enabled === true),
selectedModels: unionModels,
};
bindings.push(binding);
for (const [index, provider] of group.entries()) {
const profile = profiles[index];
routes.push(hide({
providerId: provider.id,
bindingId: binding.id,
...resolvedModels[index],
mode: providerRouteMode(provider),
eligibility: routeModeEligibility(provider),
}, {
record: provider,
routeRecord: withoutConnectionOwnedFields(provider, profile.owned),
owned: profile.owned,
}));
}
}
const suggestedLinks = [];
for (let i = 0; i < connections.length; i += 1) {
for (let j = i + 1; j < connections.length; j += 1) {
const [a, b] = [connections[i], connections[j]];
if (a.harnessId === b.harnessId) continue;
const { sameEndpoint, differences } = compareBackendEndpoints(a.profile, b.profile);
if (!sameEndpoint) continue;
suggestedLinks.push({
connectionIds: [a.id, b.id],
harnessIds: [a.harnessId, b.harnessId],
reason: 'same-backend-endpoint',
differences,
requiresExplicitLink: true,
});
}
}
const preview = {
schemaVersion: PROVIDER_GRAPH_SCHEMA_VERSION,
activeProvider: typeof activeProvider === 'string' ? activeProvider : null,
connections,
bindings,
routes,
unresolved,
suggestedLinks,
};
const violations = providerGraphUniquenessViolations(preview);
if (violations.length > 0) {
throw new Error(`Provider graph preview violates uniqueness: ${violations.join('; ')}`);
}
return preview;
}
/**
* The uniqueness constraints the durable schema in #6367 will enforce, checked
* here so a preview can never propose a graph the database would reject.
*
* @returns {string[]} one message per violation; empty means valid
*/
export function providerGraphUniquenessViolations(preview) {
const violations = [];
const seen = (label, keys) => {
const counts = new Map();
for (const key of keys) counts.set(key, (counts.get(key) || 0) + 1);
for (const [key, count] of counts) if (count > 1) violations.push(`${label} ${key} x${count}`);
};
seen('route provider_id', preview.routes.map((route) => route.providerId));
seen('connection id', preview.connections.map((connection) => connection.id));
seen('binding id', preview.bindings.map((binding) => binding.id));
seen('(binding_id, mode)', preview.routes
.filter((route) => route.bindingId)
.map((route) => `${route.bindingId}|${route.mode}`));
seen('(connection_id, harness_id, variant_key)', preview.bindings
.filter((binding) => binding.harnessId !== null)
.map((binding) => `${binding.connectionId}|${binding.harnessId}|${binding.variantKey}`));
// The partial unique index for null-harness (direct API) bindings.
seen('(connection_id, variant_key) [api]', preview.bindings
.filter((binding) => binding.harnessId === null)
.map((binding) => `${binding.connectionId}|${binding.variantKey}`));
return violations;
}
/**
* The sanitized, validated body a client receives.
*
* Credentials, raw provider records and the connection-owned snapshots never
* appear: the browser is told only WHETHER a connection has credentials, and
* every identity decision was already made server-side on real values.
*/
export function toManagementPreviewDto(preview) {
return managementPreviewSchema.parse({
schemaVersion: preview.schemaVersion,
activeProvider: preview.activeProvider,
connections: preview.connections.map(({ id, revision, kind, label, transports, hasCredentials, catalog }) =>
({ id, revision, kind, label, transports, hasCredentials, catalog })),
bindings: preview.bindings,
routes: preview.routes.map(({ providerId, bindingId, mode, modelMap, unresolvedModels, unresolvedPins, eligibility }) =>
({ providerId, bindingId, mode, modelMap, unresolvedModels, unresolvedPins, eligibility })),
unresolved: preview.unresolved,
suggestedLinks: preview.suggestedLinks,
});
}
/**
* Re-materialize the executable provider records from a preview.
*
* This is the import-fidelity proof AND the downgrade contract in one function:
* an install that drops back to a graph-unaware release runs
* `data/providers.json` alone, so every connection-owned value has to be
* present in the executable record. Round-tripping must reproduce each input
* record exactly — including pins, secrets, consent flags and unknown custom
* fields this module has never heard of.
*
* @returns {Record<string, object>} keyed by the original provider id
*/
export function projectPreviewToProviders(preview) {
return Object.fromEntries(preview.routes.map((route) => [
route.providerId,
route.owned ? withConnectionOwnedFields(route.routeRecord, route.owned) : route.record,
]));
}