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
/**
* `materializeRoute` (#7562): a (harness, method, service) composition is an
* executable record with no further lookup, and one that reads back as the
* service it was built for.
*
* Three contracts are pinned, each one a way the registries could drift apart
* without any single row looking wrong:
* 1. every (harness, definition) pair `isCompatible` accepts round-trips
* through `providerConnectionProfile` onto the same service;
* 2. the 55 shipped samples that profile cleanly are reproduced — every
* connection-owned value the sample declares is what the composition
* writes, byte for byte;
* 3. a bootstrap app becomes the `credentialBootstrap` object the spawn
* composer already understands, and only when one is supplied.
*/
import { describe, expect, it } from 'vitest';
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { composeBootstrapSpawn } from './aiToolkit/internal/credentialBootstrap.js';
import { ensurePiHeadlessArgs } from './pi.js';
import { providerConnectionProfile } from './providerConnections.js';
import { PROVIDER_HARNESSES, harnessForProvider, isCompatible } from './providerHarnesses.js';
import { materializeRoute, routeDescribesService } from './providerRouteRecipes.js';
import { SERVICE_DEFINITIONS, resolveServiceInstance, serviceDefinitionById, serviceDefinitionForLocalRuntime } from './serviceDefinitions.js';
const SAMPLES = JSON.parse(readFileSync(
resolve(dirname(fileURLToPath(import.meta.url)), 'aiToolkit/defaults/providers.sample.json'),
'utf8',
)).providers;
/** A local daemon's endpoints, as an install would declare them. */
const LOCAL_TRANSPORTS = { openai: { baseUrl: 'http://127.0.0.1:11434/v1' }, anthropic: { baseUrl: 'http://127.0.0.1:11434' } };
/** A remote endpoint for the definitions that default to none (a proxy, a peer). */
const REMOTE_TRANSPORTS = { openai: { baseUrl: 'https://gateway.example.com/v1' } };
/** An instance of `definition` with every endpoint and a key filled in. */
const instanceFor = (definition, credentials = { apiKey: 'example-key' }) => resolveServiceInstance({
definitionId: definition.id,
transports: Object.fromEntries(Object.keys(definition.transports).map((protocol) => [protocol, {
baseUrl: definition.transports[protocol].defaultBaseUrl
?? (definition.family === 'local' ? LOCAL_TRANSPORTS : REMOTE_TRANSPORTS)[protocol].baseUrl,
}])),
credentials,
});
const compatiblePairs = PROVIDER_HARNESSES.flatMap((harness) => SERVICE_DEFINITIONS
.map((definition) => instanceFor(definition))
.filter((instance) => isCompatible(harness, instance))
.map((instance) => ({ harness, instance, name: `${harness.id} × ${instance.definition.id}` })));
describe('materializeRoute round-trips onto its service', () => {
it('accepts a meaningful number of pairs', () => {
expect(compatiblePairs.length).toBeGreaterThan(25);
});
it.each(compatiblePairs)('$name', ({ harness, instance }) => {
const method = harness.modes[0];
const record = materializeRoute({ harness, method, serviceInstance: instance });
expect(record).toMatchObject({
id: `${harness.id}.${method}@${instance.slug}`,
type: method,
harnessId: harness.id,
method,
serviceId: instance.slug,
servicePlan: instance.plan,
enabled: true,
models: [],
});
expect(record).not.toHaveProperty('credentialBootstrap');
if (harness.recipe) expect(record.command).toBe(harness.recipe.command);
else expect(record).not.toHaveProperty('command');
const profile = providerConnectionProfile(record);
expect(profile.reasons, `${harness.id} on ${instance.definition.id} isolates: ${JSON.stringify(profile.reasons)}`).toEqual([]);
expect(harnessForProvider(record)?.id).toBe(harness.id);
expect(routeDescribesService(profile, instance)).toBe(true);
// A key never rides an unlisted env var: the profile reads every credential
// the record carries, or the record describes a backend it is not on.
for (const name of record.secretEnvVars) expect(record.envVars).toHaveProperty(name);
});
it('refuses the pairs the registries rule out, with a typed reason', () => {
const refuse = (input) => { try { materializeRoute(input); return null; } catch (err) { return err.code; } };
expect(refuse({ harness: 'claude', method: 'cli', serviceInstance: 'nvidia-nim' })).toBe('HARNESS_SERVICE_INCOMPATIBLE');
expect(refuse({ harness: 'antigravity', method: 'api', serviceInstance: 'antigravity' })).toBe('HARNESS_METHOD_UNSUPPORTED');
expect(refuse({ harness: 'nope', method: 'cli', serviceInstance: 'antigravity' })).toBe('HARNESS_UNKNOWN');
// A local daemon whose instance names no endpoint: never a guessed port.
expect(refuse({ harness: 'codex', method: 'cli', serviceInstance: 'ollama' })).toBe('SERVICE_ENDPOINT_REQUIRED');
// Claude Code will not start without a token, even to a daemon that ignores it.
expect(refuse({ harness: 'claude', method: 'cli', serviceInstance: { definitionId: 'ollama', transports: LOCAL_TRANSPORTS } })).toBe('SERVICE_CREDENTIAL_REQUIRED');
// ...while OpenCode on the same daemon needs none.
expect(refuse({ harness: 'opencode', method: 'cli', serviceInstance: { definitionId: 'ollama', transports: LOCAL_TRANSPORTS } })).toBeNull();
});
});
describe('materializeRoute writes what each binding shape says', () => {
it('materializes Bedrock through Claude Code\'s static env switch', () => {
const record = materializeRoute({ harness: 'claude', method: 'cli', serviceInstance: { definitionId: 'bedrock', credentials: { apiKey: 'token' } } });
expect(record.envVars).toEqual({ AWS_BEARER_TOKEN_BEDROCK: 'token', CLAUDE_CODE_USE_BEDROCK: '1' });
expect(record.secretEnvVars).toEqual(['AWS_BEARER_TOKEN_BEDROCK']);
expect(record).not.toHaveProperty('endpoint');
});
// The reviewer's catch: OpenCode's key binding names the gateway's env var,
// which a keyed non-gateway service does not have — the key must not vanish.
it('keeps a keyed non-gateway service\'s key on the OpenCode record', () => {
const record = materializeRoute({ harness: 'opencode', method: 'cli', serviceInstance: { definitionId: 'cerebras', credentials: { apiKey: 'cb' } } });
expect(record.apiKey).toBe('cb');
expect(record.secretEnvVars).toEqual([]);
expect(JSON.parse(record.envVars.OPENCODE_CONFIG_CONTENT).provider.cerebras.options.baseURL).toBe('https://api.cerebras.ai/v1');
});
it('records only an OpenAI-compatible URL as endpoint', () => {
const anthropicOnly = materializeRoute({ harness: 'claude', method: 'cli', serviceInstance: { definitionId: 'anthropic', credentials: { apiKey: 'k' } } });
expect(anthropicOnly.envVars.ANTHROPIC_BASE_URL).toBe('https://api.anthropic.com');
expect(anthropicOnly).not.toHaveProperty('endpoint');
const both = materializeRoute({ harness: 'claude', method: 'cli', serviceInstance: { definitionId: 'ollama', transports: LOCAL_TRANSPORTS, credentials: { apiKey: 'k' } } });
expect(both.endpoint).toBe(LOCAL_TRANSPORTS.openai.baseUrl);
});
it('declares OpenCode Zen as the provider OpenCode ships, permissions only', () => {
const record = materializeRoute({ harness: 'opencode', method: 'cli', serviceInstance: { definitionId: 'opencode-zen', credentials: { apiKey: 'zen' } } });
expect(record.envVars.OPENCODE_CONFIG_CONTENT).toBe(SAMPLES['opencode-zen-cli'].envVars.OPENCODE_CONFIG_CONTENT);
expect(record.envVars.OPENCODE_API_KEY).toBe('zen');
expect(record.secretEnvVars).toEqual(SAMPLES['opencode-zen-cli'].secretEnvVars);
});
it('starts Zen keyless on the free plan only — a paid plan still needs its key', () => {
const keyless = (plan) => { try { materializeRoute({ harness: 'opencode', method: 'cli', serviceInstance: { definitionId: 'opencode-zen', plan } }); return null; } catch (err) { return err.code; } };
expect(keyless('free')).toBeNull();
expect(keyless('paid')).toBe('SERVICE_CREDENTIAL_REQUIRED');
const free = materializeRoute({ harness: 'opencode', method: 'cli', serviceInstance: { definitionId: 'opencode-zen', plan: 'free' } });
expect(free.envVars).not.toHaveProperty('OPENCODE_API_KEY');
});
// Two instances of one definition under different plans are how "NVIDIA
// free vs paid" is represented; each is its own route.
it('keys a second plan of the same service by its slug', () => {
const free = materializeRoute({ harness: 'direct', method: 'api', serviceInstance: { definitionId: 'nvidia-nim', slug: 'nvidia-free', plan: 'free' } });
const paid = materializeRoute({ harness: 'direct', method: 'api', serviceInstance: { definitionId: 'nvidia-nim', slug: 'nvidia-paid', plan: 'paid', credentials: { apiKey: 'k' } } });
expect([free.id, paid.id]).toEqual(['direct.api@nvidia-free', 'direct.api@nvidia-paid']);
expect([free.servicePlan, paid.servicePlan]).toEqual(['free', 'paid']);
expect(free).toMatchObject({ endpoint: 'https://integrate.api.nvidia.com/v1', apiKey: '', timeout: 300000 });
// A direct record IS the gateway; the marker is for a wrapper in front of one.
expect(free).not.toHaveProperty('gatewayBacked');
expect(materializeRoute({ harness: 'opencode', method: 'cli', serviceInstance: 'nvidia-nim' }).gatewayBacked).toBe('nvidia-nim');
expect(paid.apiKey).toBe('k');
});
it('carries the selection onto the record', () => {
const record = materializeRoute({
harness: 'codex', method: 'cli', serviceInstance: { definitionId: 'nvidia-nim', credentials: { apiKey: 'k' } },
selection: { model: 'vendor/model-a', effort: 'high', tiers: { lightModel: 'vendor/model-b' } },
overrides: { timeout: 42 },
});
expect(record).toMatchObject({ defaultModel: 'vendor/model-a', effort: 'high', lightModel: 'vendor/model-b', timeout: 42 });
});
});
describe('Pi is pointed at a service by the provider name it ships (verified against pi 0.85)', () => {
it('selects the provider with --provider and keys it from the service\'s own env var', () => {
const record = materializeRoute({ harness: 'pi', method: 'cli', serviceInstance: { definitionId: 'nvidia-nim', credentials: { apiKey: 'nv' } } });
expect(record.command).toBe('pi');
expect(record.args).toEqual(['--print', '--approve', '--provider', 'nvidia']);
expect(record.envVars).toEqual({ NVIDIA_API_KEY: 'nv' });
expect(record.secretEnvVars).toEqual(['NVIDIA_API_KEY']);
// The spawn-time argv builder keeps the selection and adds the model in the
// `provider/id` form Pi documents for `--model`.
expect(ensurePiHeadlessArgs(record.args, 'nvidia/example-model', null))
.toEqual(['--print', '--approve', '--provider', 'nvidia', '--model', 'nvidia/example-model']);
});
it('cannot be pointed at a custom endpoint, which is Pi\'s own models.json', () => {
expect(() => materializeRoute({ harness: 'pi', method: 'cli', serviceInstance: { definitionId: 'ollama', transports: LOCAL_TRANSPORTS } }))
.toThrow(expect.objectContaining({ code: 'HARNESS_SERVICE_INCOMPATIBLE' }));
expect(() => materializeRoute({ harness: 'pi', method: 'cli', serviceInstance: { definitionId: 'openai-compatible', transports: LOCAL_TRANSPORTS } }))
.toThrow(expect.objectContaining({ code: 'HARNESS_SERVICE_INCOMPATIBLE' }));
});
});
describe('a bootstrap app becomes the credentialBootstrap the spawn composer reads', () => {
const BOOTSTRAP = { id: 'corp-auth', command: 'corp-auth', args: ['run'], argsSeparator: '--', harnessNames: { claude: 'claude-code' } };
const PROXY = { definitionId: 'openai-compatible', transports: { openai: { baseUrl: 'https://proxy.example.com/v1' } }, credential: { via: 'bootstrap' } };
it('emits <bootstrap> run <harness name> -- <args>', () => {
const record = materializeRoute({ harness: 'codex', method: 'cli', serviceInstance: PROXY, bootstrap: BOOTSTRAP });
expect(record.id).toBe('codex.cli@openai-compatible+corp-auth');
expect(record.credentialBootstrap).toEqual({ command: 'corp-auth', args: ['run'], harnessId: 'codex', argsSeparator: '--' });
expect(composeBootstrapSpawn(record, record.command, [...record.args, '--flag']))
.toEqual({ command: 'corp-auth', args: ['run', 'codex', '--', '--flag'], wrapped: true });
// The bootstrap-minted credential is not a stored key: none is required,
// and the key env var is left for the bootstrap CLI to provide.
expect(record.envVars).toEqual({ OPENAI_BASE_URL: 'https://proxy.example.com/v1' });
expect(record.secretEnvVars).toEqual([]);
});
it('uses the bootstrap CLI\'s own name for a harness when it has one', () => {
const record = materializeRoute({
harness: 'claude', method: 'tui', bootstrap: BOOTSTRAP,
serviceInstance: { definitionId: 'ollama', transports: LOCAL_TRANSPORTS, credential: { via: 'bootstrap' } },
});
expect(record.credentialBootstrap.harnessId).toBe('claude-code');
expect(composeBootstrapSpawn(record, record.command, record.args).args).toEqual(['run', 'claude-code', '--', '--dangerously-skip-permissions']);
});
it('refuses a bootstrap-credentialed service with no bootstrap, and never wraps an api route', () => {
expect(() => materializeRoute({ harness: 'codex', method: 'cli', serviceInstance: PROXY }))
.toThrow(expect.objectContaining({ code: 'SERVICE_CREDENTIAL_BOOTSTRAP_REQUIRED' }));
const api = materializeRoute({ harness: 'direct', method: 'api', serviceInstance: PROXY, bootstrap: BOOTSTRAP });
expect(api).not.toHaveProperty('credentialBootstrap');
expect(composeBootstrapSpawn(api, 'x', []).wrapped).toBe(false);
});
});
/**
* The service a shipped sample is on, read the same way a later migration
* will read it: from the record's own profile (kind + endpoint), then — for a
* record that names no backend — from the harness's subscription binding or
* the static switch it carries.
*/
function serviceForSample(sample, profile, harness) {
const local = serviceDefinitionForLocalRuntime(profile.kind);
if (local) return local;
if (profile.kind.startsWith('gateway:')) return serviceDefinitionById(profile.kind.slice('gateway:'.length));
if (sample.envVars?.CLAUDE_CODE_USE_BEDROCK === '1') return serviceDefinitionById('bedrock');
if (sample.secretEnvVars?.includes('OPENCODE_API_KEY')) return serviceDefinitionById('opencode-zen');
const endpoint = profile.transports.openai?.baseUrl;
if (endpoint) return SERVICE_DEFINITIONS.find((row) => row.transports.openai?.defaultBaseUrl === endpoint) || null;
const subscription = harness.bindings.find((binding) => binding.service && !binding.env);
return subscription ? serviceDefinitionById(subscription.service) : null;
}
describe('the shipped samples are reproduced by their (harness, service) composition', () => {
const mapped = [];
const unmapped = [];
for (const [id, sample] of Object.entries(SAMPLES)) {
const profile = providerConnectionProfile(sample);
const harness = harnessForProvider(sample);
const definition = harness && profile.reasons.length === 0 ? serviceForSample(sample, profile, harness) : null;
if (!definition) { unmapped.push(id); continue; }
const [credentialValue] = Object.values(profile.credentials);
const serviceInstance = resolveServiceInstance({
definitionId: definition.id,
// The profile reports ONE transport (the env var wins over `endpoint`);
// a sample that also stores the daemon's OpenAI URL declares both.
transports: {
...(definition.transports.openai && sample.endpoint ? { openai: { baseUrl: sample.endpoint } } : {}),
...profile.transports,
},
// A sample stores a blank key; the composition needs a real one where
// the program refuses to start without it. The VALUE is compared only
// where the sample itself carries one.
credentials: { apiKey: credentialValue ?? 'example-key' },
});
if (!isCompatible(harness, serviceInstance)) { unmapped.push(id); continue; }
mapped.push({ id, sample, profile, harness, serviceInstance });
}
// Kilo and OpenChamber bind to nothing; the two Pi samples name no service
// at all (Pi's default provider is whatever the user last logged into), so
// they are pinned by `providerRouteRecipes.sampleParity.test.js` instead.
it('maps every sample except the ones that name no service', () => {
expect(unmapped.sort()).toEqual(['kilo-cli', 'kilo-tui', 'openchamber-cli', 'pi-cli', 'pi-tui']);
expect(mapped.length + unmapped.length).toBe(Object.keys(SAMPLES).length);
});
it.each(mapped)('$id', ({ sample, profile, harness, serviceInstance }) => {
const minted = materializeRoute({ harness, method: sample.type, serviceInstance });
// Every connection-owned value the sample declares is what the composition
// writes: endpoint / apiKey fields and the transport + credential env vars.
for (const [field, value] of Object.entries(profile.owned.fields)) {
if (field === 'apiKey' && value === '') continue;
expect(minted[field], field).toBe(value);
}
for (const [name, value] of Object.entries(profile.owned.envVars)) {
if (value === '') continue;
expect(minted.envVars[name], name).toBe(value);
}
// ...and the composition reads back onto the same service and kind.
const reread = providerConnectionProfile(minted);
expect(reread.kind).toBe(profile.kind);
expect(routeDescribesService(reread, serviceInstance)).toBe(true);
});
});