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 { observeModelResource, observeModelMutations } from '../services/modelObservation.js';
import { providerModeGroups } from '../lib/aiToolkit/internal/providerModes.js';
import { tuiModeAddition } from '../lib/providerModePairing.js';
import { buildProviderGraphPreview, toManagementPreviewDto } from '../lib/providerGraphPreview.js';
import {
createBinding,
createConnection,
getManagementGraph,
linkBinding,
presetSkipReason,
previewBindingLink,
providerGraphEnabled,
refreshConnectionCatalog,
removeConnection,
unlinkBinding,
updateBindingSettings,
updateConnectionSettings,
updateRouteModelAliases,
updateRouteSettings,
} from '../services/providerGraph.js';
import {
createService,
getService,
listServices,
refreshServiceCatalog,
updateService,
} from '../services/providerServices.js';
import { Router } from 'express';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import { testVision, runVisionTestSuite, checkVisionHealth } from '../services/visionTest.js';
import { auditModelPins, clearModelPin } from '../services/modelPinAudit.js';
import { providerCreateSchema, providerSchema, providerActiveSchema, validate } from '../lib/aiToolkit/validation.js';
import { canRefreshModels, withRefreshCapability } from '../lib/aiToolkit/internal/modelFetchers.js';
import { applyModelAccess, applyModelAccessList } from '../lib/aiToolkit/internal/modelAccess.js';
import { ALLOWED_COMMANDS } from '../cos-runner/allowedCommands.js';
import { onClientDisconnect, openSseStream } from '../lib/sseDownload.js';
import { createInstallLogger } from '../lib/installLogger.js';
import {
validateRequest,
codexLoginCancelSchema,
codexLoginStartSchema,
modelPinClearSchema,
providerVisionTestSchema,
providerVisionSuiteSchema,
providerBindingCreateSchema,
providerBindingLinkSchema,
providerBindingUnlinkSchema,
providerBindingUpdateSchema,
providerConnectionCreateSchema,
providerConnectionUpdateSchema,
providerServiceCreateSchema,
providerServiceUpdateSchema,
providerRouteModelAliasSchema,
providerRouteSettingsUpdateSchema,
providerPresetCreateSchema,
credentialBootstrapsSettingsSchema,
harnessEnablementUpdateSchema,
harnessIdParamSchema,
} from '../lib/validation.js';
import {
getProviderRuntimeStatus,
getProviderRuntimeStatuses,
} from '../services/providerRuntimeInstaller.js';
import { harnessCatalogRuntime, refreshHarnessModels } from '../services/harnesses.js';
import { streamHarnessAction } from '../services/harnessActionStream.js';
import { getProviderReadinessMap, resetProviderReadinessCache, servedModelId } from '../services/providerReadiness.js';
import { getLlamaServerEndpoint, relaunchLlamaServerWithAlias } from '../services/llamaServerManager.js';
import { claimHeavyLocalJob } from '../lib/heavyJobClaim.js';
import { getProviderPrerequisiteMap } from '../services/providerPrerequisites.js';
import { isCodexSubscriptionProvider } from '../lib/codexAccount.js';
import {
cancelCodexChatGptLogin,
peekCodexAccountReadiness,
peekCodexModelCatalog,
codexLogout,
listCodexModels,
getCodexAccountReadiness,
startCodexChatGptLogin,
} from '../services/codexAppServer.js';
import { runLocalRuntimeSetup, SETUP_ACTIONS } from '../services/localRuntimeSetup.js';
import { localEndpointPort, localRuntimeForProvider } from '../lib/localProviderRuntime.js';
import {
isAuthoringOneShotProvider,
isToolFreeOneShotProvider,
enforcedPublicReviewPosturesForProvider,
publicReviewPosturesForProvider,
PUBLIC_REVIEW_NO_TOOL_POSTURE,
PUBLIC_REVIEW_ACTIONS_POSTURE,
} from '../lib/providerVendors.js';
import { buildTuiShellLaunch } from '../lib/tuiShellLaunch.js';
import { isMaskedEnvVar } from '../lib/credentialEnvVars.js';
import { presetDerivable, presetKind } from '../lib/providerPresets.js';
import { isDerivedPreset } from '../lib/providerGraphRecords.js';
import {
captureSystemCapabilities,
detectSystemCapabilities,
withProviderHardwareCompatibility,
} from '../lib/systemCapabilities.js';
/**
* The CoS Agent Runner's exec allowlist, published read-only so the AI
* Providers editor can warn that a custom `command` will never spawn via
* `/spawn` / `/spawn-tui` (#4143). Direct (non-runner) spawn does NOT consult
* this list, so an off-list command is a legitimate config — informational
* only, never a save-time rejection.
*
* Published as a list rather than a per-provider `runnerAllowed` flag on
* purpose: the editor has to warn about the command the user is TYPING, which
* has no persisted provider to decorate. Sorted so the payload is stable.
*
* This is a one-way read: the allowlist stays hand-curated in
* `cos-runner/allowedCommands.js` and is never derived from the user-writable
* `data/providers.json`, or a config write could choose the exec target.
*/
const RUNNER_ALLOWED_COMMANDS = [...ALLOWED_COMMANDS].sort();
// Same re-entrancy guard for the local-daemon setup lane. Separate from the CLI
// one because they install different things, but each is single-flight: two
// concurrent `brew install`s (or two copies of one daemon racing for a port) is
// never what a double-click meant.
let runtimeSetupInFlight = false;
/**
* Sanitize a provider object for client responses.
* Strips apiKey (replaces with hasApiKey boolean) and redacts secretEnvVars
* values. An explicitly empty secret value stays empty so the client can
* distinguish "configured but blank" from an unknown redacted value when it
* paints provider readiness.
*/
const sanitizeProvider = (provider) => {
if (!provider) return provider;
const { apiKey, envVars, secretEnvVars, ...rest } = provider;
const sanitized = {
...rest,
hasApiKey: Boolean(apiKey),
envVars: envVars ? { ...envVars } : {},
secretEnvVars: secretEnvVars || []
};
// Redact secret-listed AND credential-named env vars (Secret box may be off)
for (const key of Object.keys(sanitized.envVars)) {
if (isMaskedEnvVar(key, secretEnvVars)) {
sanitized.envVars[key] = sanitized.envVars[key] === '' ? '' : '***';
}
}
return sanitized;
};
/**
* Decorate a TUI provider with the command line the Shell page will run for it,
* so the card can render a "Launch in Shell" button and show what it will type.
*
* DISPLAY ONLY — the launch itself goes through `shell:start { providerId }`,
* which re-resolves this server-side and pairs it with the provider's env (see
* `lib/tuiShellLaunch.js`). Publishing the line does not publish the env: those
* values are secret and stay on the server.
*
* Non-TUI providers get no field at all: the button is TUI-only, and an absent
* key (rather than an empty string) keeps "not a TUI" distinct from "a TUI
* whose command line came back blank".
*/
const withTuiLaunchCommand = (provider) => {
const launch = buildTuiShellLaunch(provider);
return launch ? { ...provider, tuiCommandLine: launch.commandLine } : provider;
};
/**
* The shape a provider takes on its way OUT to the client: secrets stripped,
* plus the derived `canRefreshModels` flag the AI Providers page reads to
* decide whether to offer a "Refresh Models" button (#3620).
*
* Order matters, and BOTH derivations run on the RAW provider, before
* sanitization. `canRefreshModels`: the ollama row of the fetcher table keys
* partly on `envVars.ANTHROPIC_BASE_URL`, which `sanitizeProvider` redacts to
* `'***'` when the user marked it secret — deriving after would silently drop
* the Refresh button for a Claude-Ollama provider. `tuiCommandLine`: the same
* trap one layer down, since `buildTuiInvocation` consults `envVars` for the
* Bedrock model mapping (`CLAUDE_CODE_USE_BEDROCK`) — a redacted `'***'` reads
* truthy, so a card whose provider has that var marked secret and switched OFF
* would advertise a Bedrock-mapped model the real launch never uses.
*
* These PortOS routes SHADOW the toolkit's own (which decorate the same way);
* the toolkit keeps its copy so it stays correct standalone. Both decorate on
* the way out only — the field is never persisted.
*/
const presentProvider = (provider, capabilities = captureSystemCapabilities()) => {
const decorated = withProviderHardwareCompatibility(
withTuiLaunchCommand(withRefreshCapability(provider)),
capabilities,
);
// Derived on read from the raw provider. This is an explicit capability of
// the maintained public-review recipe, not a client-side guess based on a
// provider name or a user-writable `args` list.
// `publicReviewPostures` is the value the schedule UI filters on, so a stage
// offers exactly the providers this install can actually run it on;
// `publicReviewEnforcedPostures` is the subset backed by a vendor sandbox
// recipe. The two booleans are derived from it and kept for existing consumers.
const publicReviewPostures = publicReviewPosturesForProvider(provider);
// Narrow `models` to the install's declared entitlement, LAST, so every
// derivation above still reads the provider's full advertised catalog. The
// untouched list rides along as `modelCatalog` — the editor seeds its
// "Available Models" box from it, so an ordinary Save on a scoped provider
// cannot persist the narrowed list over the real one.
return sanitizeProvider({
...applyModelAccess(decorated),
// The RAW record's key: an inherited or materialized one rides
// NON-enumerably (`withGatewayApiKey`, the composite resolver), so the
// decorating spreads above dropped it — re-carried here so `hasApiKey`
// reports the key the run would actually use (#7564).
apiKey: provider?.apiKey,
// The UNION of the two refresh paths, because the button asks only
// whether SOME path can serve this record. Which one actually serves it is
// decided in `POST /:id/refresh-models`, and the two must stay in step or
// a card offers a button the route refuses.
canRefreshModels: decorated.canRefreshModels || Boolean(harnessCatalogRuntime(provider)),
toolFreeOneShot: isToolFreeOneShotProvider(provider),
authoringOneShot: isAuthoringOneShotProvider(provider),
publicReviewPostures,
publicReviewEnforcedPostures: enforcedPublicReviewPosturesForProvider(provider),
publicReviewSupported: publicReviewPostures.includes(PUBLIC_REVIEW_NO_TOOL_POSTURE),
publicReviewActionsSupported: publicReviewPostures.includes(PUBLIC_REVIEW_ACTIONS_POSTURE),
// Preset structure (#7565): `derived` when the record names the service it
// is materialized from, else `legacy`; and whether a legacy record is a
// candidate for "Convert to derived preset": pure over the record, AND not
// refused by the last reconcile pass — the conversion re-runs that pass, so
// a record it just left legacy would only fail again (#7565).
presetKind: presetKind(provider),
presetDerivable: presetDerivable(provider) && !presetSkipReason(provider?.id),
});
};
// Deferred: the preset service reaches the graph store and the composite
// resolver, which every suite that mounts these routes would otherwise pay for.
const presetService = () => import('../services/providerPresets.js');
/**
* Carry a gateway-backed wrapper's RESOLVED model-access policy from the read
* that preceded a write onto the record the write handed back.
*
* A write returns the PERSISTED record, and a wrapper stores no policy of its
* own — the gateway sibling owns it, and `withGatewayModelAccess` resolves it on
* read. Presenting the raw write result would answer that one request with the
* unscoped catalog and the next GET with the scoped one, which reads as a bug.
* The route already holds a resolved read (it needs it for the 404 and for
* secret preservation), so this is a field copy rather than a second load.
*
* Deliberately not a re-read: several suites drive these routes with a provider
* service double whose `getProviderById` answers a different fixture than the
* write does, and a write path is the wrong place to depend on a second lookup.
*
* Safe against a write that CHANGED the policy: `applyModelAccess` reads the
* record's own `modelAccess` first and only falls back to the resolved field,
* so a freshly written own policy outranks the inherited one copied here.
*/
const withResolvedModelAccess = (provider, resolved) => (
provider && resolved?.modelAccessEffective
? { ...provider, modelAccessEffective: resolved.modelAccessEffective, modelAccessSource: resolved.modelAccessSource }
: provider
);
/**
* Create PortOS-specific provider routes
* Extends AI Toolkit routes with vision testing endpoints
*/
export function createPortOSProviderRoutes(aiToolkit) {
const router = Router();
router.use((req, res, next) => {
if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method)) {
res.once('finish', () => {
if (res.statusCode < 400) req.app.get('io')?.emit('providers:changed');
});
}
next();
});
router.get('/fleet-host', asyncHandler(async (req, res) => {
const { readFleetHostStatus } = await import('../services/fleetHostNotify.js');
res.set('Cache-Control', 'no-store').json(await readFleetHostStatus({ refresh: req.query.fresh === '1' }));
}));
// Who has been using this machine's GPU. Never cached: the point of the
// report is what is happening right now.
router.get('/fleet-host/usage', asyncHandler(async (req, res) => {
const { getFleetLlmHostUsage } = await import('../services/fleetLlmHost.js');
res.set('Cache-Control', 'no-store').json(await getFleetLlmHostUsage());
}));
// The counterpart to `/fleet-host/setup`: close the queue, clear the
// enable marker, drop the login task and remove the container.
router.post('/fleet-host/stop', asyncHandler(async (req, res) => {
const { disableFleetLlmHost, getFleetLlmHostStatus } = await import('../services/fleetLlmHost.js');
if (runtimeSetupInFlight) throw new ServerError('Model host setup is running — wait for it to finish before stopping the host.', { status: 409, code: 'SETUP_BUSY' });
const log = [];
const result = await disableFleetLlmHost({ emit: (message) => log.push(message) });
resetProviderReadinessCache();
res.set('Cache-Control', 'no-store').json({ ...result, log, status: await getFleetLlmHostStatus().catch(() => null) });
}));
router.get('/fleet-peer-hosts', asyncHandler(async (req, res) => {
const { getFleetPeerHosts } = await import('../services/fleetLlmHost.js');
res.set('Cache-Control', 'no-store').json(await getFleetPeerHosts());
}));
router.post('/fleet-peer-hosts/:peerId/key', asyncHandler(async (req, res) => {
const { revealFleetPeerHostKey } = await import('../services/fleetLlmHost.js');
res.set('Cache-Control', 'no-store').json(await revealFleetPeerHostKey(req.params.peerId));
}));
// Explicit reveal; secrets are never included in status, URLs or install logs.
router.post('/fleet-host/key', asyncHandler(async (req, res) => {
const { revealFleetLlmKey } = await import('../services/fleetLlmHost.js');
res.set('Cache-Control', 'no-store').json({ apiKey: await revealFleetLlmKey() });
}));
router.post('/fleet-host/setup', asyncHandler(async (req, res) => {
const { configureFleetLlmHost, getFleetLlmHostStatus } = await import('../services/fleetLlmHost.js');
if (runtimeSetupInFlight) throw new ServerError('Another model setup is running.', { status: 409, code: 'SETUP_BUSY' });
runtimeSetupInFlight = true;
const { send, safeEnd } = openSseStream(res);
let clientGone = false;
onClientDisconnect(req, res, () => { clientGone = true; });
const result = await configureFleetLlmHost({
emit: (message) => send({ type: 'log', message }),
isCancelled: () => clientGone,
}).catch((err) => ({ success: false, error: err.message }))
.finally(() => { runtimeSetupInFlight = false; resetProviderReadinessCache(); });
const status = await getFleetLlmHostStatus().catch(() => null);
send(result.success ? { type: 'complete', message: 'Host configured. Check model readiness below.', status } : { type: 'error', message: result.error });
safeEnd();
}));
const providerService = aiToolkit.services.providers;
const providerStatusService = aiToolkit.services.providerStatus;
router.use(observeModelMutations('provider-readiness', 'provider-status', 'codex-account'));
const readinessObservation = observeModelResource('provider-readiness', async () => {
const data = await providerService.getAllProviders();
return { readiness: await getProviderReadinessMap(data.providers) };
});
const accountObservation = observeModelResource('codex-account', async ({ fresh }) => ({
readiness: await getCodexAccountReadiness({ fresh }),
}));
// Sanitized GET routes — intercept toolkit GET endpoints to strip secrets
/**
* The provider list, each record decorated with the SERVER's verdict on its
* prerequisites (#4611): `prerequisitesMet` plus the `missingPrerequisites`
* findings behind it. The AI Providers page paints its `NEEDS SETUP` cards
* from this instead of re-deriving the same rules in the browser, and the
* fallback router gates on the same computation — so a card that says a
* provider can't run and a router that hands it a run can no longer disagree.
*
* Computed on the RAW providers, before sanitization: the API-key check reads
* `apiKey`, which `sanitizeProvider` replaces with a boolean.
*
* The capability probe is cached and performed once per response, so every
* provider shares one host snapshot instead of triggering its own hardware
* checks. An unreadable probe remains `unknown`, which keeps the provider
* visible until the runtime can make a confirmed decision.
*/
router.get('/', asyncHandler(async (req, res) => {
const data = await providerService.getAllProviders();
const prerequisites = getProviderPrerequisiteMap(data.providers);
const modeGroups = new Map(providerModeGroups(data.providers).flatMap(group =>
group.map(provider => [provider.id, group.map(({ id, type }) => ({ id, type }))])));
const capabilities = await detectSystemCapabilities();
// Cache-only: this list must stay a synchronous read that spawns nothing.
// `null` here means NOT PROBED, and the dedicated `/codex/account` fetch is
// what fills it — a card renders "unknown", never "signed out", until then.
const codexAccount = peekCodexAccountReadiness();
// Same cache-only contract, for the CoS/model pickers (#6306): the signed-in
// account's real catalog when one has been fetched, otherwise the three-state
// shape that tells the client to keep showing its shipped list. Rendering a
// picker must never be what starts `codex app-server`.
const codexModelCatalog = peekCodexModelCatalog();
res.json({
activeProvider: data.activeProvider,
providers: data.providers.map((provider) => ({
...presentProvider(provider, capabilities),
executionModes: modeGroups.get(provider.id),
// Whether this record can be COMPLETED into a CLI/TUI pair. Derived
// here rather than on the record alone because the verdict reads the
// whole list — this record's mode GROUP (a `<stem>-cli` record is
// already paired while its `<id>-tui` sits unclaimed) and the sibling
// id — and decided server-side for the same reason `prerequisitesMet`
// is: the card offering the action and the endpoint performing it must
// not re-derive the rule apart.
canAddTuiMode: tuiModeAddition(provider, data.providers, modeGroups.get(provider.id)).ok,
prerequisitesMet: prerequisites[provider.id]?.met ?? true,
missingPrerequisites: prerequisites[provider.id]?.missing ?? [],
// NON-blocking notices — today only 'this install's own ~/.codex/config.toml
// re-points Codex model routing'. Kept OUT of `missingPrerequisites` so a
// legitimate user choice never buckets a card as NEEDS SETUP; the card
// renders it as a badge and caveats the subscription quota with it.
prerequisiteAdvisories: prerequisites[provider.id]?.advisories ?? [],
...(isCodexSubscriptionProvider(provider) ? { codexAccount, codexModelCatalog } : {}),
})),
runnerAllowedCommands: RUNNER_ALLOWED_COMMANDS
});
}));
router.get('/active', asyncHandler(async (req, res) => {
const provider = await providerService.getActiveProvider();
res.json(presentProvider(provider, await detectSystemCapabilities()));
}));
// PUT /active must be defined before PUT /:id to avoid the wildcard
// catching "active" as a provider ID (which causes 404 "Provider not found")
router.put('/active', asyncHandler(async (req, res) => {
const validation = validate(providerActiveSchema, req.body);
if (!validation.success) {
throw new ServerError('Invalid provider data', { status: 400, code: 'VALIDATION_ERROR', context: { details: validation.errors } });
}
const { id } = validation.data;
const provider = await providerService.setActiveProvider(id);
if (!provider) {
throw new ServerError('Provider not found', { status: 404 });
}
res.json(presentProvider(provider, await detectSystemCapabilities()));
}));
/**
* READ-ONLY preview of the provider connection graph (#6366) — what an
* import WOULD create from the records this install already runs, and which
* records it would leave isolated, with reasons.
*
* Nothing is persisted, no provider is written, and no AI provider is
* contacted: this is a pure projection of `providers.json` and must stay one,
* because it is meant to be safe to open from a configuration screen. The
* flat `GET /api/providers` shape is untouched and remains the execution
* contract; `activeProvider` here is the same executable provider id string.
*
* A client talking to a server without this endpoint gets a 404 and falls
* back to the flat list — an explicit unsupported answer, not a guess.
*/
router.get('/management/preview', asyncHandler(async (_req, res) => {
const data = await providerService.getAllProviders();
// Scoped like every other picker payload: the preview's connection catalogs
// and binding model menus are what the Backend Connections page offers, so
// an unscoped read here would contradict the model-access policy four
// handlers below (docs/MODEL_ACCESS.md).
const scoped = { ...data, providers: applyModelAccessList(data.providers) };
res.set('Cache-Control', 'no-store').json(toManagementPreviewDto(buildProviderGraphPreview(scoped)));
}));
/**
* The DURABLE provider connection graph (#6367) — the same shape as the
* preview above, but read from ai_connections / ai_harness_bindings /
* ai_route_bindings rather than derived on every request.
*
* Sanitized identically: credential PRESENCE only, no projection snapshots,
* no raw provider records. An install whose database is unavailable gets an
* explicit 503 `PROVIDER_GRAPH_UNAVAILABLE` rather than a silent empty graph,
* so a client can fall back to the flat list on a known answer instead of
* guessing from a failed request.
*/
router.get('/management', asyncHandler(async (_req, res) => {
res.set('Cache-Control', 'no-store').json(await getManagementGraph());
}));
/**
* Add a NEW backend to the graph (#6369) — mock flow 3 in the decision
* record: a distinct remote endpoint with its own credentials, created as its
* own identity even when its model names match a backend already configured.
*
* Creation only. Nothing is probed, no model list is fetched, no route is
* minted and `activeProvider` does not move: a connection with no binding is
* a legitimate row the user then attaches a harness to.
*/
router.post('/connections', asyncHandler(async (req, res) => {
const input = validateRequest(providerConnectionCreateSchema, req.body ?? {});
res.status(201).json(await createConnection(input));
}));
/**
* Add a harness to an existing backend (#6369) — mock flow 2: the same
* daemon, driven by a second program, as an INDEPENDENT binding with its own
* executable route ids.
*
* The route records are minted from the harness's command recipe
* (`PROVIDER_HARNESSES[].recipe`), which is what this endpoint waited on: the
* registry could classify an existing record but not describe how to spawn a
* fresh one.
*
* Every minted route arrives DISABLED with no model pins. Creating a route is
* a management act; executing one is a separate grant on `PATCH
* /api/providers/:id`, and nothing here launches, probes or generates.
*/
router.post('/bindings', asyncHandler(async (req, res) => {
const input = validateRequest(providerBindingCreateSchema, req.body ?? {});
res.status(201).json(await createBinding(input));
}));
/**
* What linking this binding into another connection WOULD change: which
* executable route ids move, how the two backends differ, and which variant
* key the binding would occupy. Read-only — POST because the body carries the
* revisions being reviewed, not because anything is written.
*/
router.post('/bindings/:id/link/preview', asyncHandler(async (req, res) => {
const input = validateRequest(providerBindingLinkSchema, req.body ?? {});
res.json(await previewBindingLink({ bindingId: req.params.id, ...input }));
}));
// Apply a reviewed link. Every named revision is re-checked inside the graph
// transaction; a stale one is a 409 that requires a fresh preview.
router.post('/bindings/:id/link', asyncHandler(async (req, res) => {
const input = validateRequest(providerBindingLinkSchema, req.body ?? {});
res.json(await linkBinding({ bindingId: req.params.id, ...input }));
}));
// Give this binding its own copy of the connection it shares. Route ids,
// activeProvider, task pins and fallback references are all retained.
router.post('/bindings/:id/unlink', asyncHandler(async (req, res) => {
const input = validateRequest(providerBindingUnlinkSchema, req.body ?? {});
res.json(await unlinkBinding({ bindingId: req.params.id, ...input }));
}));
// Remove a connection no binding uses. Refused with a 409 while one still
// does — the graph never silently orphans a binding to tidy a row away.
router.delete('/connections/:id', asyncHandler(async (req, res) => {
res.json(await removeConnection(req.params.id));
}));
/**
* Edit one SHARED backend (#6369) — its label, transports and credentials —
* and materialize the result into every executable route on it.
*
* This is the edit the graph exists for: an endpoint or key changed once
* rather than retyped per harness. `expectedRevision` is required and
* re-checked inside the serialized pass, so an edit made against a row that
* has since moved is a 409 instead of a silent overwrite.
*/
router.patch('/connections/:id', asyncHandler(async (req, res) => {
const input = validateRequest(providerConnectionUpdateSchema, req.body ?? {});
res.json(await updateConnectionSettings({ connectionId: req.params.id, ...input }));
}));
/**
* Refresh a connection's SHARED model catalog once for every harness on it.
*
* An explicit discovery request and nothing more: it lists models, it never
* generates, and a failed probe keeps the catalog the connection already had
* rather than reporting an empty backend.
*/
router.post('/connections/:id/refresh-models', asyncHandler(async (req, res) => {
res.json(await refreshConnectionCatalog(req.params.id));
}));
/**
* Service INSTANCES (#7563) — the same `ai_connections` rows read as one
* instance each of a `SERVICE_DEFINITIONS` entry: slug, definition, plan,
* enabled, how it authenticates, and the catalog it last listed. Sanitized
* like the graph: credential PRESENCE and SOURCE only, never a value.
*
* `:slug` also accepts the row's UUID, and every `/connections/:id` route
* above accepts a slug, so the two surfaces address one row either way.
*/
router.get('/services', asyncHandler(async (_req, res) => {
res.set('Cache-Control', 'no-store').json(await listServices());
}));
/**
* Every `SERVICE_DEFINITIONS` row an "Add service" flow may instantiate
* (#7567): family, plans, transports with default base URLs, and where a key
* is obtained. Code-only data — no instance, no credential — so it is
* cacheable for the process lifetime. Declared above `/services/:slug` by
* name rather than position: its own segment can never be read as a slug.
* Deferred imports like the catalog handler below: a suite that mocks
* `providerServices.js` would otherwise instantiate the instance/definition
* subtree through this route file alone (server/AGENTS.md "Import scoping").
*/
router.get('/service-definitions', asyncHandler(async (_req, res) => {
const [{ SERVICE_DEFINITIONS }, { presentServiceDefinition }] = await Promise.all([
import('../lib/serviceDefinitions.js'),
import('../lib/providerServiceInstances.js'),
]);
res.json({ definitions: SERVICE_DEFINITIONS.map(presentServiceDefinition) });
}));
// Create an instance from a definition. Nothing is probed and no route is
// minted; the catalog starts `unknown` until the explicit refresh below.
router.post('/services', asyncHandler(async (req, res) => {
const input = validateRequest(providerServiceCreateSchema, req.body ?? {});
res.status(201).json(await createService(input));
}));
router.get('/services/:slug', asyncHandler(async (req, res) => {
res.set('Cache-Control', 'no-store').json(await getService(req.params.slug));
}));
// The shared-backend edit plus plan / enabled / credential mode. Same
// required `expectedRevision`, same three-valued credential rule, same
// projection into every route on the row.
router.patch('/services/:slug', asyncHandler(async (req, res) => {
const input = validateRequest(providerServiceUpdateSchema, req.body ?? {});
res.json(await updateService(req.params.slug, input));
}));
// Refused with a 409 while a binding still names the row — the same rule as
// the connection delete, because it IS the connection delete.
router.delete('/services/:slug', asyncHandler(async (req, res) => {
res.json(await removeConnection(req.params.slug));
}));
/**
* List the instance's models through its DEFINITION's strategy — a probe of
* its own endpoint with its own key, the local daemon, the program that signs
* in, or the declared list — filtered to its plan. Needs no executable route.
* An explicit discovery request: it lists, never generates, and a failure
* keeps the catalog the instance already had.
*/
router.post('/services/:slug/refresh-catalog', asyncHandler(async (req, res) => {
res.json(await refreshServiceCatalog(req.params.slug));
}));
/**
* Edit one harness binding's management state: its label and the subset of
* the shared catalog it offers. Never its routes' enablement or consent —
* those stay on `PATCH /api/providers/:id`, where granting them is explicit.
*/
router.patch('/bindings/:id', asyncHandler(async (req, res) => {
const input = validateRequest(providerBindingUpdateSchema, req.body ?? {});
res.json(await updateBindingSettings({ bindingId: req.params.id, ...input }));
}));
/**
* Edit ONE route's mode overrides (#6369) — args, timeout, effort, model pins.
*
* The per-mode counterpart to the shared-backend edit above, so a whole
* backend is configurable from one screen instead of a connection plus three
* route editors. Route-owned only: an endpoint, a credential and the `enabled`
* flag are all unreachable here by construction, and `PATCH
* /api/providers/:id` remains the place execution consent is granted.
*
* `expectedRevision` is the route's `settingsRevision` from
* `GET /api/providers/management` — a fingerprint of the values on disk, so an
* edit made in the route editor while this panel was open is a 409 too.
*/
router.patch('/routes/:providerId', asyncHandler(async (req, res) => {
const input = validateRequest(providerRouteSettingsUpdateSchema, req.body ?? {});
res.json(await updateRouteSettings({ providerId: req.params.providerId, ...input }));
}));
/**
* Correct ONE route's canonical→executable model aliases by hand (#6369).
*
* A refresh records only the aliases it can VERIFY — a stored model string
* round-trips through the harness's own adapter or it stays an unresolved
* alias rather than being rewritten — so a spelling the adapter cannot
* reproduce reaches no shared catalog and no model menu. This is where a
* human supplies it.
*
* `null` for a key removes that override and is the ONLY thing that does: a
* refresh rewrites what it observed in a separate column, so a correction
* survives it and an alias for a model the route no longer lists is kept and
* reported stale rather than dropped.
*/
router.patch('/routes/:providerId/model-aliases', asyncHandler(async (req, res) => {
const input = validateRequest(providerRouteModelAliasSchema, req.body ?? {});
res.json(await updateRouteModelAliases({ providerId: req.params.providerId, ...input }));
}));
router.get('/samples', asyncHandler(async (req, res) => {
const providers = await providerService.getSampleProviders();
const capabilities = await detectSystemCapabilities();
res.json({ providers: providers.map((provider) => presentProvider(provider, capabilities)) });
}));
// A CLI/TUI provider is only usable if its runtime binary is on PortOS's
// PATH. These are local coding tools, not LLM services PortOS may silently
// bootstrap, so this endpoint only reports availability and the companion
// install endpoint services an explicit click from the Providers page. Both
// intentionally return no resolved filesystem paths, which could disclose the
// host account name.
router.get('/runtimes', asyncHandler(async (_req, res) => {
res.json({ runtimes: await getProviderRuntimeStatuses() });
}));
/**
* Requirements checklist for every provider backed by a LOCAL daemon
* (llama.cpp, Ollama, LM Studio, MTPLX) — see `services/providerReadiness.js`.
*
* `/runtimes` above answers "can PortOS run this CLI?"; this answers "is the
* daemon that CLI talks to installed, running, and serving the model this
* provider asks for?" — the failure that otherwise only surfaces as
* "Cannot connect to API" inside a dead agent transcript.
*
* Computed on the RAW providers on purpose: a sanitized copy redacts secret
* env values, and a user's custom base URL can live in one
* (`OPENCODE_CONFIG_CONTENT`, `ANTHROPIC_BASE_URL`), which would send the
* probe at the wrong endpoint. The response carries booleans, labels, and the
* provider's own already-displayed endpoint — never a resolved binary path.
*/
router.get('/readiness', asyncHandler(async (req, res) => {
// `?providerId=<composite>` answers for ONE composition (#7564): the
// materialized record is what the readiness probe reads, so a composite
// that resolves is judged exactly as a stored record on the same daemon.
const compositeId = typeof req.query.providerId === 'string' ? req.query.providerId : null;
if (compositeId) {
const provider = await providerService.getProviderById(compositeId);
res.json({ readiness: provider ? await getProviderReadinessMap([provider]) : {} });
return;
}
res.json(await readinessObservation.read());
}));
/**
* The composition catalog (#7564): every axis a `{ providerId, model, effort }`
* picker composes over — harnesses with their enablement, service instances,
* bootstrap apps, which harness reaches which service, the effort ladder per
* harness (and per model where a model narrows it), and the stored presets.
* Derived from cache and settings only: harness detection is the runtime
* probe's cache, nothing is spawned, no provider is contacted.
*
* `GET /api/providers` stays presets-only — every existing `useProviderModels`
* consumer keeps its shape; this is the additive surface for composing.
*/
router.get('/catalog', asyncHandler(async (_req, res) => {
const { buildProviderCatalog } = await import('../services/compositeProviders.js');
const [catalog, data, capabilities] = await Promise.all([buildProviderCatalog(), providerService.getAllProviders(), detectSystemCapabilities()]);
res.json({ ...catalog, presets: data.providers.map((provider) => presentProvider(provider, capabilities)) });
}));
/** Per-harness enablement (#7564): the user's word, else PATH detection, `direct` always on. */
router.get('/harnesses', asyncHandler(async (_req, res) => {
const { listHarnessEnablement } = await import('../services/harnessEnablement.js');
res.json({ harnesses: await listHarnessEnablement() });
}));
router.put('/harnesses/:id', asyncHandler(async (req, res) => {
const harnessId = validateRequest(harnessIdParamSchema, req.params.id);
const { enabled } = validateRequest(harnessEnablementUpdateSchema, req.body || {});
const { setHarnessEnabled } = await import('../services/harnessEnablement.js');
res.json({ harness: { id: harnessId, ...(await setHarnessEnabled(harnessId, enabled)) } });
}));
/**
* Credential-bootstrap apps (#7564): the wrapper CLIs a composite's
* `+<slug>` suffix names. Saving never spawns anything — `setupCommand` is
* advisory text, and the wrapper runs only when a composite is executed.
*/
router.get('/bootstraps', asyncHandler(async (_req, res) => {
const { listCredentialBootstraps } = await import('../services/credentialBootstrapApps.js');
res.json({ bootstraps: await listCredentialBootstraps() });
}));
router.put('/bootstraps', asyncHandler(async (req, res) => {
const bootstraps = validateRequest(credentialBootstrapsSettingsSchema, req.body?.bootstraps ?? req.body ?? {});
const { saveCredentialBootstraps } = await import('../services/credentialBootstrapApps.js');
res.json({ bootstraps: await saveCredentialBootstraps(bootstraps) });
}));
/**
* One composite's verdict (#7564): eligible or not, with the reason a picker
* shows beside a saved selection that names it, and — when eligible — the
* materialized record sanitized exactly as a stored one (`presentProvider`:
* `apiKey` → `hasApiKey`, secret env values redacted).
*/
router.get('/composites/:id', asyncHandler(async (req, res) => {
const { describeCompositeProvider } = await import('../services/compositeProviders.js');
const { record, ...verdict } = await describeCompositeProvider(req.params.id);
res.json({ ...verdict, provider: record ? presentProvider(record, await detectSystemCapabilities()) : null });
}));
/**
* "Save as preset" (#7565): store the record a composite id resolves to, as
* an enabled derived preset the picker can name like any other. The
* resolver's verdict gates it — an ineligible composite is a 400 with its
* code and reason, never a stored record that cannot run. `model` and
* `effort` become the preset's defaults; a `+<bootstrap>` suffix becomes
* its `credentialBootstrapId`.
*/
router.post('/presets', asyncHandler(async (req, res) => {
const input = validateRequest(providerPresetCreateSchema, req.body ?? {});
const { createPresetFromComposite } = await presetService();
const created = await createPresetFromComposite(input);
res.status(201).json(presentProvider(created, await detectSystemCapabilities()));
}));
/**
* Is a ChatGPT subscription signed in, and is it usable right now?
*
* The Codex CLI/TUI cards could already say whether the `codex` binary
* exists; they could not say whether the account behind it is signed in, on
* which plan, expired, or out of quota — the user learned that from a failed
* agent transcript. The answer comes from the Codex app-server's own
* `account/read`: PortOS never reads Codex's credential file and never holds
* a token.
*
* LAZY BY CONTRACT. This is the call that may spawn `codex app-server`, and
* it runs only from an explicit page fetch — nothing on the boot path calls
* it, and `GET /api/providers` decorates its cards from the cache-only peek.
* `?fresh=1` skips the TTL for the poll that follows a sign-in.
*
* The payload carries a status, a plan name, and quota percentages. No token,
* no account id, no email, no credential path.
*/
router.get('/codex/account', asyncHandler(async (req, res) => {
res.json(await accountObservation.read({ fresh: req.query.fresh === '1' }));
}));
/**
* Begin an explicit ChatGPT sign-in and return only the URL (browser flow) or
* the verification URL plus short code (device-code flow) the user needs.
*
* A POST because it starts an OAuth flow — never a side effect of a read.
* The response deliberately contains no token material, and `loginId` is the
* bounded handle the cancel endpoint takes.
*/
router.post('/codex/account/login', asyncHandler(async (req, res) => {
const { deviceCode } = validateRequest(codexLoginStartSchema, req.body ?? {});
res.json({ login: await startCodexChatGptLogin({ deviceCode }) });
}));
/**
* Abandon the sign-in this PortOS started. The id must match the pending
* login, so a stale tab cannot cancel a flow the user began afterwards.
*/
router.post('/codex/account/login/cancel', asyncHandler(async (req, res) => {
const { loginId } = validateRequest(codexLoginCancelSchema, req.body ?? {});
res.json({ readiness: await cancelCodexChatGptLogin(loginId) });
}));
/**
* Which models this ChatGPT subscription may run, from the app-server's own
* catalog rather than a hard-coded list — so the picker reflects the account's
* actual plan.
*
* LAZY, like `/codex/account`: only an explicit page fetch reaches it.
* `?fresh=1` skips the TTL after a plan change or a sign-in.
*
* `models: null` means NEVER FETCHED, `[]` means fetched-and-empty, and a read
* that fails returns the last-known-good list alongside `error` — the client
* must not repaint an empty picker because one call timed out.
*/
router.get('/codex/models', asyncHandler(async (req, res) => {
res.json(await listCodexModels({ fresh: req.query.fresh === '1' }));
}));
/** Sign out. Codex drops its own credentials; PortOS has none to clear. */
router.post('/codex/account/logout', asyncHandler(async (_req, res) => {
res.json({ readiness: await codexLogout() });
}));
// Install-only: the update and remove lanes of the shared runner are reached
// from `/api/harnesses`, which is where the Harnesses page drives them. See
// `services/harnessActionStream.js` for the stream contract.
const streamRuntimeInstall = (req, res, runtimeId) =>
streamHarnessAction(req, res, { runtime: runtimeId, action: 'install' });
/**
* Install and/or start the LOCAL DAEMON one provider points at, streaming
* progress as SSE. This is the "do it for me" half of `/readiness`: the
* checklist says llama.cpp / Ollama / LM Studio / MTPLX is missing or down,
* and this fixes it without sending the user to a vendor setup doc.
*
* The request names a PROVIDER id, never an endpoint, port, or command. The
* runtime kind and the endpoint are both re-derived server-side from the
* stored provider record, so nothing from the query reaches a spawn argument
* — the `runtime` param is only cross-checked against what the record
* resolves to, so a stale page cannot set up a different daemon than the card
* it was clicked on.
*/
router.post('/readiness/setup', asyncHandler(async (req, res) => {
const providerId = String(req.query.provider || '');
const data = await providerService.getAllProviders();
// RAW record on purpose — a sanitized copy redacts the secret env values a
// custom base URL can live in, which would resolve the wrong endpoint.
const provider = (data.providers || []).find((row) => row.id === providerId);
if (!provider) {
throw new ServerError('Unknown provider', { status: 404, code: 'UNKNOWN_PROVIDER', context: { provider: providerId } });
}
const runtime = localRuntimeForProvider(provider);
if (!runtime) {
throw new ServerError('This provider does not depend on a local runtime PortOS can set up.', { status: 400, code: 'NO_LOCAL_RUNTIME' });
}
const requested = req.query.runtime ? String(req.query.runtime) : runtime.kind;
if (requested !== runtime.kind) {
throw new ServerError('This provider no longer uses that runtime — reload the page and try again.', { status: 409, code: 'RUNTIME_MISMATCH' });
}
// Which of the fixed steps the checklist's button named. Matched against the
// closed set rather than passed through, so the only thing an unexpected
// value can do is 400 — it never reaches a command. Absent stays `null`
// rather than becoming a default here: a client built before this parameter
// existed still renders THIS server's button label, so the service resolves
// what the checklist is currently offering instead of assuming a start.
const action = req.query.action ? String(req.query.action) : null;
if (action !== null && !SETUP_ACTIONS.includes(action)) {
throw new ServerError('Unknown setup action.', { status: 400, code: 'UNKNOWN_SETUP_ACTION', context: { action } });
}
const { send, safeEnd } = openSseStream(res);
const installLog = createInstallLogger({ installer: runtime.label, target: runtime.endpoint });
let clientGone = false;
let holdsLock = false;
// Closing the modal stops the WAIT, not the work: unlike the CLI installer
// above there is no single child to SIGTERM (a step may be mid-`brew
// install`), so the lock stays held until the setup actually settles —
// releasing it here would let a second click start a competing install
// into the same prefix. `isCancelled` makes that window short: the setup
// bails before its next step rather than running to the end.
onClientDisconnect(req, res, () => {
clientGone = true;
installLog.cancel();
safeEnd();
});
if (runtimeSetupInFlight) {
send({ type: 'error', message: 'Another local-runtime setup is already running. Wait for it to finish.' });
return safeEnd();
}
if (clientGone) return safeEnd();
runtimeSetupInFlight = true;
holdsLock = true;
send({ type: 'stage', stage: 'setup', message: `Setting up ${runtime.label} for ${runtime.endpoint}.` });
installLog.start();
const emit = (message) => {
const event = { type: 'log', message };
installLog.onEvent(event);
send(event);
};
// `runLocalRuntimeSetup` resolves for every expected failure; the `.catch`
// covers the unexpected throw. Either way the headers are already flushed,
// so the outcome has to be a terminal SSE frame rather than a 500 body.
const result = await runLocalRuntimeSetup(runtime.kind, {
endpoint: runtime.endpoint,
emit,
isCancelled: () => clientGone,
action,
}).catch((err) => ({ success: false, error: err.message }));
if (holdsLock) { runtimeSetupInFlight = false; holdsLock = false; }
// A daemon just came up (or a binary just landed) — the readiness caches
// remember it being down, and the page polls them within seconds.
resetProviderReadinessCache();
if (clientGone) return safeEnd();
const terminal = result.success
? { type: 'complete', message: result.message || `${runtime.label} is ready.` }
: { type: 'error', message: result.error || `${runtime.label} setup failed.` };
installLog.onEvent(terminal);
send(terminal);
safeEnd();
}));
/**
* Relaunch the local daemon so it answers under the model id THIS provider
* sends — the other half of the readiness checklist's model mismatch.
*
* "Use `dflash` as default" already moved the provider onto whatever the
* server happens to answer as. This moves the server instead, which is what a
* user wants when they picked the model id deliberately: llama.cpp serves one
* model per process under the `--alias` on its launch line, so the mismatch is
* a label, not a missing download, and renaming it keeps the weights that are
* already loaded.
*
* Only runtimes that HAVE such a label (`aliasFlag`) qualify; the model id is
* re-derived server-side from the stored provider record, so nothing from the
* query reaches a launch argument.
*/
router.post('/readiness/serve-model', asyncHandler(async (req, res) => {
const providerId = String(req.query.provider || '');
const data = await providerService.getAllProviders();
// RAW record — a sanitized copy redacts the secret env values a custom base
// URL can live in, which would resolve the wrong runtime.
const provider = (data.providers || []).find((row) => row.id === providerId);
if (!provider) {
throw new ServerError('Unknown provider', { status: 404, code: 'UNKNOWN_PROVIDER', context: { provider: providerId } });
}
const runtime = localRuntimeForProvider(provider);
if (!runtime?.aliasFlag) {
throw new ServerError(
'This provider\'s runtime names its model after the weights it loaded, so PortOS cannot rename it — change the provider\'s default model instead.',
{ status: 400, code: 'NO_MODEL_ALIAS' },
);
}
const wanted = servedModelId(provider, runtime.kind);
if (!wanted) {
throw new ServerError('This provider selects no specific model, so there is nothing to serve it as.', { status: 400, code: 'NO_DEFAULT_MODEL' });
}
// The provider's OWN endpoint, not the runtime's default: a second
// llama-server on another loopback port is a different daemon, and PortOS
// only manages one (`portos-llama-server`). Without this the button on a
// provider pointed at that second server would restart the managed one under
// the second one's model id — breaking the provider that WAS working and
// leaving the clicked one mismatched exactly as before.
const managedEndpoint = await getLlamaServerEndpoint();
// Compared by PORT, not by string: the manager renders its host as
// `127.0.0.1` while a provider may spell the same daemon `localhost`, and a
// string compare would refuse a setup that works. `localRuntimeForProvider`
// already guarantees `runtime.endpoint` is a local-instance host, so a
// matching port is the same daemon.
if (localEndpointPort(runtime.endpoint) !== localEndpointPort(managedEndpoint)) {
throw new ServerError(
`This provider points at ${runtime.endpoint}, but the llama-server PortOS manages serves ${managedEndpoint}. Add \`--alias ${wanted}\` to that server's own launch line instead.`,
{ status: 409, code: 'LLAMA_ENDPOINT_MISMATCH' },
);
}
// A relaunch reloads multi-gigabyte weights onto the accelerator, and an
// assessment sweep relaunches the same daemon on its own schedule — so this
// takes the machine-wide claim those jobs take rather than a lock private to
// this route. Zero timeout: an interactive click refuses immediately with
// who holds it rather than queueing behind hours of sweep.
const claim = await claimHeavyLocalJob({ kind: 'llama-server model id', id: wanted, timeoutMs: 0 });
if (!claim.ok) {
throw new ServerError(claim.message, { status: 409, code: 'LOCAL_ACCELERATOR_BUSY' });
}
// `relaunchLlamaServerWithAlias` resolves for every expected refusal, so
// this covers the unexpected throw — the claim must not survive it, or every
// later heavy local job is refused until the process exits.
const result = await relaunchLlamaServerWithAlias(wanted).finally(() => claim.release());
// The daemon's launch line just changed under the readiness caches, and the
// page polls them within seconds.
resetProviderReadinessCache();
if (result.applied === false) {
throw new ServerError(result.reason, {
// A PM2 read that failed says nothing about the daemon — the fix is to
// retry, not to go edit a launch line.
status: result.retryable ? 503 : 409,
code: result.retryable ? 'SERVE_MODEL_UNAVAILABLE' : 'SERVE_MODEL_FAILED',
context: { model: wanted },
});
}
res.json({
success: true,
model: wanted,
// `null` = it already answered under that id, so nothing was restarted.
relaunched: result.applied === true,
});
}));
// `runtime` rides in the query string because the shared RuntimeInstallModal
// already appends it there for every BYO-runtime installer.
router.post('/runtimes/install', asyncHandler(async (req, res) => {
await streamRuntimeInstall(req, res, req.query.runtime);
}));
// Back-compat for a client build that predates the generalized routes (a
// deployed `client/dist` can lag the server across an upgrade). Both mirror
// the old OpenCode-only response shape exactly.
router.get('/opencode/installation', asyncHandler(async (_req, res) => {
const status = await getProviderRuntimeStatus('opencode');
res.json({ installed: status.installed, npmAvailable: status.installable });
}));
router.post('/opencode/install', asyncHandler(async (req, res) => {
await streamRuntimeInstall(req, res, 'opencode');
}));
// Provider status routes MUST be defined before toolkit routes,
// because the toolkit has a GET /:id route that would catch /status
const presentProviderStatus = (status) => {
// Keep a second allowlist at the HTTP boundary even though the toolkit
// service already presents sanitized status. The route is the final guard
// if a host injects a different provider-status implementation.
const { rateLimitWindow, ...publicStatus } = status || {};
if (!rateLimitWindow || typeof rateLimitWindow !== 'object') return publicStatus;
const allowedWindow = Object.fromEntries(
['observedAt', 'retryAfterMs', 'resetAt', 'remaining', 'limit']
.filter(key => rateLimitWindow[key] != null)
.map(key => [key, rateLimitWindow[key]])
);
return Object.keys(allowedWindow).length
? { ...publicStatus, rateLimitWindow: allowedWindow }
: publicStatus;
};
// GET /model-pins — stored model pins naming a model their provider no longer
// lists (#7315). Registered BEFORE '/:id' so the literal path is not read as a
// provider id. Derived on read, never persisted: see services/modelPinAudit.js.
router.get('/model-pins', asyncHandler(async (_req, res) => {
res.json(await auditModelPins());
}));
// POST /model-pins/clear — clear ONE pin back to "inherit". A pin is the
// user's own choice, so PortOS surfaces a retirement and never rewrites it;
// this is that one-click clear. Clearing a pin that is already gone is a
// success with `cleared: false`, not a 404 — the outcome the caller wanted.
router.post('/model-pins/clear', asyncHandler(async (req, res) => {
const { pinId } = validateRequest(modelPinClearSchema, req.body ?? {});
res.json(await clearModelPin(pinId));
}));
const statusObservation = observeModelResource('provider-status', async () => {
const statuses = providerStatusService.getAllStatuses();
// Enrich with time until recovery
const enriched = { ...statuses, providers: { ...statuses.providers } };
for (const [providerId, status] of Object.entries(enriched.providers)) {
enriched.providers[providerId] = {
...presentProviderStatus(status),
timeUntilRecovery: providerStatusService.getTimeUntilRecovery(providerId)
};
}
return enriched;
});
router.get('/status', asyncHandler(async (_req, res) => {
res.json(await statusObservation.read());
}));
router.get('/:id/status', asyncHandler(async (req, res) => {
const status = presentProviderStatus(providerStatusService.getStatus(req.params.id));
res.json({
...status,
timeUntilRecovery: providerStatusService.getTimeUntilRecovery(req.params.id)
});
}));
router.post('/:id/status/recover', asyncHandler(async (req, res) => {
const status = await providerStatusService.markAvailable(req.params.id);
res.json({ success: true, status });
}));
// PortOS-specific extensions (parameterized routes before toolkit mount)
router.get('/:id/vision-health', asyncHandler(async (req, res) => {
const result = await checkVisionHealth(req.params.id);
res.json(result);
}));
router.post('/:id/test-vision', asyncHandler(async (req, res) => {
const { imagePath, prompt, expectedContent, model } = validateRequest(providerVisionTestSchema, req.body);
const result = await testVision({
imagePath,
prompt: prompt || 'Describe what you see in this image.',
expectedContent: expectedContent || [],
providerId: req.params.id,
model
});
res.json(result);
}));
router.post('/:id/vision-suite', asyncHandler(async (req, res) => {
const { model } = validateRequest(providerVisionSuiteSchema, req.body);
const result = await runVisionTestSuite(req.params.id, model);
res.json(result);
}));
/**
* "Convert to derived preset" (#7565): stamp one legacy record with the
* harness, method and service instance it already runs on — only when
* re-deriving it from that service reproduces every connection-owned value
* it carries (the same fixpoint the boot backfill applies). Refused with the
* reason otherwise; nothing about how the record runs is changed either way.
*/
router.post('/:id/derive', asyncHandler(async (req, res) => {
const { derivePreset } = await presetService();
const provider = await derivePreset(req.params.id);
res.json(presentProvider(provider, await detectSystemCapabilities()));
}));
// Sanitized GET /:id — must be after specific /:id/* routes above
router.get('/:id', asyncHandler(async (req, res) => {
const provider = await providerService.getProviderById(req.params.id);
if (!provider) throw new ServerError('Provider not found', { status: 404 });
res.json(presentProvider(provider, await detectSystemCapabilities()));
}));
// PUT /:id — intercept to (a) validate the body via a partial provider
// schema (PUT can be a partial update; only the fields the client sent are
// re-validated), and (b) preserve redacted secrets before passing to the
// toolkit. Without partial validation, an `updateProvider` call could
// still persist invalid types (timeout: "abc", non-object envVars) the
// POST path now blocks.
router.put('/:id', asyncHandler(async (req, res) => {
const existing = await providerService.getProviderById(req.params.id);
if (!existing) throw new ServerError('Provider not found', { status: 404 });
const validation = validate(providerSchema.partial(), req.body);
if (!validation.success) {
throw new ServerError('Invalid provider data', { status: 400, code: 'VALIDATION_ERROR', context: { details: validation.errors } });
}
const updates = { ...validation.data };
// Preserve an actually persisted apiKey if the client didn't send a new
// one. Gateway-backed CLI/TUI wrappers receive their sibling API key as a
// non-enumerable, execution-only property; carrying that value into a
// derived-preset update turns an inherited credential into a direct edit
// and makes an otherwise harmless save fail with PRESET_FIELD_DERIVED.
if (!('apiKey' in updates) && Object.prototype.propertyIsEnumerable.call(existing, 'apiKey')) {
updates.apiKey = existing.apiKey;
}
// Preserve existing secret/credential-named env var values when client sends redacted '***' placeholders
if (updates.envVars) {
for (const [key, value] of Object.entries(updates.envVars)) {
if (value === '***' && existing.envVars?.[key] && isMaskedEnvVar(key, existing.secretEnvVars)) {
updates.envVars[key] = existing.envVars[key];
}
}
}
// A DERIVED preset (#7565) stores what its service derives — see
// `storableProviderRecord` for what is refused and what is read as a narrowing.
const { storableProviderRecord } = await presetService();
const stored = await storableProviderRecord({ ...existing, ...updates, id: req.params.id }, updates, existing);
const provider = await providerService.updateProvider(req.params.id, stored);
res.json(presentProvider(withResolvedModelAccess(provider, existing), await detectSystemCapabilities()));
}));
// POST /:id/refresh-models — intercept the toolkit response so the refreshed
// provider record receives the same secret redaction as every other provider
// response. The toolkit returns its raw persisted record here.
router.post('/:id/refresh-models', asyncHandler(async (req, res) => {
const stored = await providerService.getProviderById(req.params.id);
if (!stored) throw new ServerError('Provider not found', { status: 404 });
// A record can match BOTH paths — `cursor-cli` and `antigravity-cli` do
// today — so the precedence is fixed here: the TOOLKIT FETCHER WINS, and
// the harness catalog serves only records no fetcher claims. The fetcher
// table keys on the launch command (and, failing that, the display name),
// which is a per-record answer; routing a record the table already claims
// to its harness instead would silently move where its catalog comes from.
const harness = canRefreshModels(stored) ? null : harnessCatalogRuntime(stored);
let provider;
if (isDerivedPreset(stored) && providerGraphEnabled()) {
// A DERIVED preset's models are its service's catalog (#7565). Writing a
// probe onto the record alone leaves that catalog stale, so the next
// derivation discards what was found — refresh the service instead, which
// re-derives every preset on it.
const { service } = await refreshServiceCatalog(stored.serviceId, { resetPresetId: stored.id });
if (service.catalog?.state === 'failed') {
throw new ServerError(service.catalog.error || 'The service could not list its models; its catalog was preserved.', { status: 502 });
}
provider = await providerService.getProviderById(stored.id);
} else if (harness) {
// Scoped to THIS record: the harness is probed once per bootstrap
// credential (services/harnesses.js), and a card's button must not spawn
// another record's credential CLI to answer for its own.
const result = await refreshHarnessModels(harness.id, { providerId: stored.id });
if (!result.ok || !result.updated.includes(stored.id)) {
throw new ServerError(result.reason || 'No models matched this provider’s namespace; its catalog was preserved.', { status: 502 });
}
provider = await providerService.getProviderById(stored.id);
} else {
provider = await providerService.refreshProviderModels(req.params.id);
}
if (!provider) throw new ServerError('Provider not found', { status: 404 });
res.json(presentProvider(withResolvedModelAccess(provider, stored), await detectSystemCapabilities()));
}));
/**
* POST /:id/modes/tui — give an existing CLI record the TUI half of its
* harness, minted from the record already on disk.
*
* A NEW endpoint rather than a flag on `PUT /:id`, because `modes` is
* deliberately create-only: a PATCH against one record cannot mean "make me
* two". `:id` names the record the sibling is DERIVED from, and the sibling
* is built from what is stored — the user does not retype the command,
* endpoint, credentials and env that `providerModeGroups` then has to find
* identical on both halves.
*
* There is no request body: every field either comes from the stored record
* or from the harness recipe. The new record is editable like any other
* afterwards.
*/
router.post('/:id/modes/tui', asyncHandler(async (req, res) => {
const { providers } = await providerService.getAllProviders();
const stored = providers.find(provider => provider.id === req.params.id);
if (!stored) throw new ServerError('Provider not found', { status: 404 });
// The same verdict the list decorated this record with, so a card can only
// ever offer an action this endpoint accepts.
const verdict = tuiModeAddition(stored, providers);
if (!verdict.ok) throw new ServerError(verdict.message, { status: verdict.status, code: verdict.code });
const created = await providerService.createProviderTuiMode(stored.id, { args: verdict.args });
res.status(201).json(presentProvider(created, await detectSystemCapabilities()));
}));
// POST / — intercept to (a) validate the body against providerCreateSchema so
// invalid fields like `timeout: "abc"` or non-object `envVars` don't
// persist and later break runner behavior, and (b) sanitize the created
// provider before responding so apiKey/secret envVar values don't echo
// back to the client (the toolkit's POST returns the raw provider).
//
// A body declaring `modes` creates BOTH execution modes of one harness and
// responds with `{ providers: [cli, tui] }` — a distinct shape rather than a
// polymorphic one, so a caller reading `.id` off a single-mode create keeps
// working and a pair create cannot silently hide the id of the second record.
router.post('/', asyncHandler(async (req, res) => {
const validation = validate(providerCreateSchema, req.body);
if (!validation.success) {
throw new ServerError('Invalid provider data', { status: 400, code: 'VALIDATION_ERROR', context: { details: validation.errors } });
}
if (validation.data.modes) {
const created = await providerService.createProviderModes(validation.data);
// One snapshot for the pair — the probe is per-host, not per-record, and
// it stays BEHIND the create so a refused one never pays for it.
const capabilities = await detectSystemCapabilities();
res.status(201).json({ providers: created.map(provider => presentProvider(provider, capabilities)) });
return;
}
// A body naming a harness, method and service is a DERIVED preset (#7565).
const { storableProviderRecord } = await presetService();
const provider = await providerService.createProvider(await storableProviderRecord(validation.data, validation.data));
res.status(201).json(presentProvider(provider, await detectSystemCapabilities()));
}));
// Mount base toolkit routes last (GET/PUT /:id, POST /, and
// POST /:id/refresh-models are now shadowed by sanitized versions above).
// DELETE /:id has no provider body; POST /:id/test returns only its test
// result, so neither endpoint needs a sanitizing shadow.
router.use('/', aiToolkit.routes.providers);
return router;
}