Self-hosted, plugin-based server management.
TypeScript dockerhomelabpluginsrdpremote-desktopself-hostedserver-managementsftpsshterminaltermixvnc
export const LOCAL_ADAPTIVE_ENGINE_KEY = "termix.local.adaptive-engine.v1";
const VERSION = 1;
const HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
const MAX_SCOPES = 128;
const MAX_ACTIONS_PER_SCOPE = 12;
const DEFAULT_MIN_EVIDENCE = 2.5;
const DEFAULT_MIN_SHARE = 0.6;
const DEFAULT_MIN_MARGIN = 1;
const EWMA_ALPHA = 0.25;
export interface LocalAdaptiveOutcome {
success?: boolean;
latencyMs?: number;
cancelled?: boolean;
fallback?: boolean;
}
export interface LocalAdaptiveActionStats {
weight: number;
updatedAt: number;
observations: number;
successes: number;
cancellations: number;
fallbacks: number;
latencyEwmaMs?: number;
}
interface AdaptiveScope {
actions: Record<string, LocalAdaptiveActionStats>;
updatedAt: number;
}
interface AdaptiveStore {
version: typeof VERSION;
scopes: Record<string, AdaptiveScope>;
}
export interface LocalAdaptiveDecision<T extends string> {
action: T;
confidence: number;
reason: "fallback" | "insufficient-evidence" | "learned";
expiresAt: number;
}
interface DecisionOptions<T extends string> {
scope: string;
candidates: readonly T[];
fallback: T;
now?: number;
ttlMs?: number;
minEvidence?: number;
minShare?: number;
minMargin?: number;
}
function emptyStore(): AdaptiveStore {
return { version: VERSION, scopes: {} };
}
function finiteNonNegative(value: unknown): number {
return Number.isFinite(value) && Number(value) >= 0 ? Number(value) : 0;
}
function sanitizeAction(value: unknown): LocalAdaptiveActionStats | null {
if (!value || typeof value !== "object") return null;
const stat = value as Partial<LocalAdaptiveActionStats>;
if (
!Number.isFinite(stat.weight) ||
Number(stat.weight) < 0 ||
!Number.isFinite(stat.updatedAt)
) {
return null;
}
const latencyEwmaMs = finiteNonNegative(stat.latencyEwmaMs);
return {
weight: Number(stat.weight),
updatedAt: Number(stat.updatedAt),
observations: finiteNonNegative(stat.observations),
successes: finiteNonNegative(stat.successes),
cancellations: finiteNonNegative(stat.cancellations),
fallbacks: finiteNonNegative(stat.fallbacks),
...(latencyEwmaMs > 0 ? { latencyEwmaMs } : {}),
};
}
function sanitizeStore(value: unknown): AdaptiveStore {
if (!value || typeof value !== "object") return emptyStore();
const candidate = value as Partial<AdaptiveStore>;
if (
candidate.version !== VERSION ||
!candidate.scopes ||
typeof candidate.scopes !== "object" ||
Array.isArray(candidate.scopes)
) {
return emptyStore();
}
const scopes: Record<string, AdaptiveScope> = {};
for (const [scope, rawScope] of Object.entries(candidate.scopes)) {
if (!rawScope || typeof rawScope !== "object") continue;
const value = rawScope as Partial<AdaptiveScope>;
if (
!Number.isFinite(value.updatedAt) ||
!value.actions ||
typeof value.actions !== "object" ||
Array.isArray(value.actions)
) {
continue;
}
const actions: Record<string, LocalAdaptiveActionStats> = {};
for (const [action, rawStat] of Object.entries(value.actions)) {
const stat = sanitizeAction(rawStat);
if (stat) actions[action] = stat;
}
scopes[scope] = { actions, updatedAt: Number(value.updatedAt) };
}
return { version: VERSION, scopes };
}
function readStore(): AdaptiveStore {
if (typeof localStorage === "undefined") return emptyStore();
try {
return sanitizeStore(
JSON.parse(localStorage.getItem(LOCAL_ADAPTIVE_ENGINE_KEY) ?? "null"),
);
} catch {
return emptyStore();
}
}
function writeStore(store: AdaptiveStore): void {
if (typeof localStorage === "undefined") return;
try {
localStorage.setItem(LOCAL_ADAPTIVE_ENGINE_KEY, JSON.stringify(store));
} catch {
// Local adaptation is optional and must never block the requested action.
}
}
function decayedWeight(stat: LocalAdaptiveActionStats, now: number): number {
const age = Math.max(0, now - stat.updatedAt);
return stat.weight * 2 ** (-age / HALF_LIFE_MS);
}
function trimStore(store: AdaptiveStore, now: number): void {
for (const scope of Object.values(store.scopes)) {
scope.actions = Object.fromEntries(
Object.entries(scope.actions)
.sort(
([, a], [, b]) =>
decayedWeight(b, now) - decayedWeight(a, now) ||
b.updatedAt - a.updatedAt,
)
.slice(0, MAX_ACTIONS_PER_SCOPE),
);
}
store.scopes = Object.fromEntries(
Object.entries(store.scopes)
.sort(([, a], [, b]) => b.updatedAt - a.updatedAt)
.slice(0, MAX_SCOPES),
);
}
function updateEwma(previous: number | undefined, value: number): number {
return previous === undefined
? value
: previous + EWMA_ALPHA * (value - previous);
}
function getActionStats(
store: AdaptiveStore,
scope: string,
action: string,
now: number,
): [AdaptiveScope, LocalAdaptiveActionStats] {
const scopeStats = store.scopes[scope] ?? { actions: {}, updatedAt: now };
return [
scopeStats,
scopeStats.actions[action] ?? {
weight: 0,
updatedAt: now,
observations: 0,
successes: 0,
cancellations: 0,
fallbacks: 0,
},
];
}
function saveActionStats(
store: AdaptiveStore,
scope: string,
action: string,
scopeStats: AdaptiveScope,
actionStats: LocalAdaptiveActionStats,
now: number,
): void {
scopeStats.actions[action] = actionStats;
scopeStats.updatedAt = now;
store.scopes[scope] = scopeStats;
trimStore(store, now);
writeStore(store);
}
/** Records an abstract user choice. Never pass raw paths, input, or content. */
export function recordLocalAdaptiveChoice(
scope: string,
action: string,
now = Date.now(),
): void {
if (!scope || !action) return;
const store = readStore();
const [scopeStats, previous] = getActionStats(store, scope, action, now);
saveActionStats(
store,
scope,
action,
scopeStats,
{
...previous,
weight: decayedWeight(previous, now) + 1,
updatedAt: now,
},
now,
);
}
/** Records performance separately so failed actions are not reinforced. */
export function recordLocalAdaptiveOutcome(
scope: string,
action: string,
outcome: LocalAdaptiveOutcome,
now = Date.now(),
): void {
if (
!scope ||
!action ||
!Object.values(outcome).some((v) => v !== undefined)
) {
return;
}
const store = readStore();
const [scopeStats, previous] = getActionStats(store, scope, action, now);
const latency = finiteNonNegative(outcome.latencyMs);
saveActionStats(
store,
scope,
action,
scopeStats,
{
...previous,
updatedAt: now,
observations: previous.observations + 1,
successes: previous.successes + (outcome.success === true ? 1 : 0),
cancellations:
previous.cancellations + (outcome.cancelled === true ? 1 : 0),
fallbacks: previous.fallbacks + (outcome.fallback === true ? 1 : 0),
...(latency > 0
? { latencyEwmaMs: updateEwma(previous.latencyEwmaMs, latency) }
: {}),
},
now,
);
}
export function chooseLocalAdaptiveAction<T extends string>({
scope,
candidates,
fallback,
now = Date.now(),
ttlMs = 5 * 60 * 1000,
minEvidence = DEFAULT_MIN_EVIDENCE,
minShare = DEFAULT_MIN_SHARE,
minMargin = DEFAULT_MIN_MARGIN,
}: DecisionOptions<T>): LocalAdaptiveDecision<T> {
const expiresAt = now + Math.max(0, ttlMs);
const stats = readStore().scopes[scope]?.actions;
if (!stats || candidates.length === 0) {
return { action: fallback, confidence: 0, reason: "fallback", expiresAt };
}
const ranked = candidates
.map((action) => ({
action,
weight: stats[action] ? decayedWeight(stats[action], now) : 0,
}))
.sort((a, b) => b.weight - a.weight);
const total = ranked.reduce((sum, item) => sum + item.weight, 0);
const [best, second] = ranked;
if (!best || total <= 0) {
return { action: fallback, confidence: 0, reason: "fallback", expiresAt };
}
const share = best.weight / total;
const margin = best.weight - (second?.weight ?? 0);
const confidence = Math.min(
1,
best.weight / Math.max(minEvidence, Number.EPSILON),
share / Math.max(minShare, Number.EPSILON),
margin / Math.max(minMargin, Number.EPSILON),
);
const learned =
best.weight >= minEvidence && share >= minShare && margin >= minMargin;
return {
action: learned ? best.action : fallback,
confidence,
reason: learned ? "learned" : "insufficient-evidence",
expiresAt,
};
}
export function getLocalAdaptiveStats(
scope: string,
): Readonly<Record<string, LocalAdaptiveActionStats>> {
return readStore().scopes[scope]?.actions ?? {};
}
export function clearLocalAdaptiveEngine(): void {
if (typeof localStorage === "undefined") return;
try {
localStorage.removeItem(LOCAL_ADAPTIVE_ENGINE_KEY);
} catch {
// Local adaptation is optional in restricted storage modes.
}
}