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
/**
* Presentation helpers for the Persistent Mind's temporary thinking sessions.
*
* The mechanism (saved presets, exact-or-refuse resolution, per-call receipts)
* lives on the server. This module answers only the questions the Mind page has
* to answer BEFORE the user commits: what exact route is about to be borrowed,
* whether taking it can spend an account, and — afterwards — what a receipt
* actually says versus what the provider never reported.
*
* Everything here is pure: no fetches, no provider probes. Previewing a preset
* must never contact a provider, so the classification is deliberately a
* READ of the already-loaded provider record, not a capability call.
*/
import { formatCount, formatRuntime, formatUsd } from '../utils/formatters.js';
import {
credentialSource,
isApiProvider,
isLocalInstanceProvider,
isOllamaBackedProvider,
isPrivateNetworkEndpoint,
localBackendForProvider,
} from '../utils/providers.js';
/**
* How a route is paid for, as far as the client can prove from the provider
* record alone.
*
* - `local` — a daemon the user hosts, on this machine or elsewhere inside the
* private network. Running it spends no vendor account.
* - `account` — a stored key, an inherited gateway key, a credential env var,
* or a vendor subscription stands behind it.
* - `unknown` — cannot be determined. Treated as account-backed everywhere it
* matters, because guessing "free" is the one direction that costs money.
*/
export const MIND_ROUTE_BILLING = Object.freeze({
LOCAL: 'local',
ACCOUNT: 'account',
UNKNOWN: 'unknown',
});
const isLocalBackedRecord = (provider) => Boolean(
localBackendForProvider(provider) || isOllamaBackedProvider(provider)
|| provider?.llamaBacked === true || provider?.mtplxBacked === true
|| provider?.vllmBacked === true || provider?.sglangBacked === true,
);
/**
* Does the inference run on hardware the user owns?
*
* Deliberately NOT `isLocalInstanceProvider` alone: that helper reads a BLANK
* endpoint as local, which is right for an `ollama` record (every default it
* falls back to is a loopback URL) and badly wrong for a cloud API provider
* whose endpoint is implied by its id — calling that one free is exactly the
* mistake this classification exists to prevent. So a bare API provider must
* name a private-network endpoint, while a record already identified as a local
* backend (or a CLI/TUI wrapper fronting one) may leave it blank.
*/
const isSelfHostedRoute = (provider) => (
(isApiProvider(provider) && isPrivateNetworkEndpoint(provider?.endpoint))
|| (isLocalBackedRecord(provider)
&& (isLocalInstanceProvider(provider) || isPrivateNetworkEndpoint(provider?.endpoint)))
);
/**
* Classify what sending on this provider can spend.
*
* @param {object|null|undefined} provider - a provider record from `GET /api/providers`
* @returns {{billing: string, label: string, detail: string, spendsAccount: boolean}}
*/
export function classifyMindRouteBilling(provider) {
if (!provider) {
return {
billing: MIND_ROUTE_BILLING.UNKNOWN,
label: 'Routing unknown',
detail: 'This provider is not in the current catalog, so PortOS cannot say whether sending spends an account. Treat it as billable.',
spendsAccount: true,
};
}
if (isSelfHostedRoute(provider)) {
return {
billing: MIND_ROUTE_BILLING.LOCAL,
label: 'Local model',
detail: 'Runs on hardware you host. Sending spends no account credit.',
spendsAccount: false,
};
}
if (credentialSource(provider).kind !== 'none') {
return {
billing: MIND_ROUTE_BILLING.ACCOUNT,
label: 'Account-backed',
detail: 'Backed by a credential or vendor subscription. Sending can use paid quota.',
spendsAccount: true,
};
}
return {
billing: MIND_ROUTE_BILLING.UNKNOWN,
label: 'Routing unknown',
detail: 'PortOS cannot tell whether this route runs on your own hardware or against an account. Treat it as billable.',
spendsAccount: true,
};
}
/** "provider / model · high" — the one phrasing for an exact borrowed route. */
export function formatMindRoute({ providerId, model, effort } = {}, { providerName = null } = {}) {
const provider = providerName || providerId || 'Unknown provider';
const modelText = model || 'Unknown model';
return `${provider} / ${modelText}${effort ? ` · ${effort}` : ''}`;
}
/**
* Is this saved preset still exactly the route the composer is displaying?
*
* The server refuses a selection whose preset changed after acceptance, so the
* composer must not offer to send a stale one. Labels are presentation and do
* not participate — only the exact route does, mirroring
* `samePersistentMindThinkingSelection` on the server.
*/
export function sameMindRoute(left, right) {
if (!left || !right) return false;
return ['providerId', 'model'].every((key) => left[key] === right[key])
&& (left.effort || '') === (right.effort || '');
}
/** Find one saved preset by id, or null. Never falls back to another preset. */
export function findMindThinkingPreset(presets, presetId) {
if (!presetId) return null;
return (Array.isArray(presets) ? presets : []).find((preset) => preset.id === presetId) || null;
}
const PRESET_ID_MAX = 64;
/**
* Mint a stable, server-legal preset id from a label.
*
* Must satisfy the server's `^[A-Za-z0-9][A-Za-z0-9_-]*$`. A label that reduces
* to nothing (emoji, CJK) still gets an id, because refusing to save a preset
* over its display name would be a worse failure than a generated id.
*/
export function mintMindPresetId(label, existingIds = []) {
const taken = new Set(existingIds);
const slug = String(label || '')
.normalize('NFKD')
.replace(/[^A-Za-z0-9]+/g, '-')
.replace(/^-+|-+$/g, '')
.toLowerCase()
.slice(0, PRESET_ID_MAX - 4);
const base = /^[A-Za-z0-9]/.test(slug) ? slug : `preset${slug ? `-${slug}` : ''}`;
if (!taken.has(base)) return base;
for (let suffix = 2; suffix < 1000; suffix += 1) {
const candidate = `${base}-${suffix}`.slice(0, PRESET_ID_MAX);
if (!taken.has(candidate)) return candidate;
}
return `${base}-${Date.now()}`.slice(0, PRESET_ID_MAX);
}
/**
* Render a call receipt's usage block.
*
* `state: 'unknown'` is a real answer — the provider reported nothing — and it
* must read as unknown rather than as a free call. Never coerce a missing count
* or price to zero.
*/
export function formatMindCallUsage(usage) {
if (usage?.state !== 'reported') return 'Usage unknown';
const parts = [];
if (usage.totalTokens !== null && usage.totalTokens !== undefined) {
parts.push(`${formatCount(usage.totalTokens)} tokens`);
} else if (usage.inputTokens !== null && usage.inputTokens !== undefined) {
parts.push(`${formatCount(usage.inputTokens)} in`);
}
if (usage.costUsd !== null && usage.costUsd !== undefined) {
parts.push(formatUsd(usage.costUsd, { maximumFractionDigits: 4 }));
}
return parts.length > 0 ? parts.join(' · ') : 'Usage unknown';
}
/**
* Wall time of a call or turn — "Elapsed unknown" when nothing measured it.
*
* The one phrasing, so the route card and the receipt list cannot disagree
* about what an unmeasured span reads as. A measured zero is a real value and
* renders as one.
*/
export function formatMindElapsed(ms) {
if (!Number.isFinite(ms) || ms < 0) return 'Elapsed unknown';
return formatRuntime(ms) || '0ms';
}
const OUTCOME_LABELS = Object.freeze({
completed: 'Completed',
failed: 'Failed',
denied: 'Refused',
interrupted: 'Interrupted',
});
/** Human label for a receipt/turn outcome; an unrecognized value is unknown. */
export function formatMindCallOutcome(outcome) {
return OUTCOME_LABELS[outcome] || 'Outcome unknown';
}
const TERMINAL_TURN_STATUSES = Object.freeze(['completed', 'failed', 'denied', 'interrupted']);
/**
* Terminal outcome of one turn, from its own status when it has one and
* otherwise from its last receipt.
*
* A turn that has not finished reads as `running` REGARDLESS of its receipts.
* A turn spans bounded tool rounds, so round 0 can report `completed` while
* the turn is still working — consulting the last receipt first would call an
* in-flight turn finished, and the caller renders that as a terminal outcome.
*/
export function mindTurnOutcome(turn) {
if (TERMINAL_TURN_STATUSES.includes(turn?.status)) return turn.status;
if (!turn?.completedAt) return 'running';
const calls = Array.isArray(turn.calls) ? turn.calls : [];
const last = calls[calls.length - 1];
return TERMINAL_TURN_STATUSES.includes(last?.outcome) ? last.outcome : 'completed';
}
/**
* Wall time of a turn, preferring its own timestamps and falling back to the
* sum of its receipts. Returns null — never 0 — when neither is available.
*/
export function mindTurnElapsedMs(turn) {
const startedAt = Date.parse(turn?.startedAt);
const completedAt = Date.parse(turn?.completedAt);
if (Number.isFinite(startedAt) && Number.isFinite(completedAt) && completedAt >= startedAt) {
return completedAt - startedAt;
}
const calls = Array.isArray(turn?.calls) ? turn.calls : [];
const measured = calls.filter((call) => Number.isFinite(call?.elapsedMs));
return measured.length > 0 ? measured.reduce((total, call) => total + call.elapsedMs, 0) : null;
}
/** Only the turns that borrowed a preset — the ones this page is accountable for. */
export function temporaryMindTurns(turnExecutions) {
return (Array.isArray(turnExecutions) ? turnExecutions : [])
.filter((turn) => Boolean(turn?.thinkingPresetId)
|| (Array.isArray(turn?.calls) && turn.calls.some((call) => call?.temporaryRoute === true)));
}