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
/**
* The per-call boundary every persistent-mind provider call passes through.
*
* The supervisor admits a TURN: one global slot, one action reservation, one
* local-endpoint slot, one budget check. But a turn is not one provider call —
* the optional context summary is one, the turn itself is another, and each
* tool round after it is another again. Checking admission once and accounting
* one action for that whole span meant a mind could keep spending after the
* budget was exhausted, after its preset was revoked, or after the user stopped
* it, and the ledger only ever heard about it once.
*
* So this module re-checks the things that can change WHILE a turn runs — the
* live exact route, provider availability/authorization, mind lifecycle,
* capability grants, remaining budget — immediately before each call, and
* accounts every attempt that actually started, failures included.
*
* It deliberately acquires NOTHING. The turn already holds the global slot, the
* action reservation, and the endpoint slot; taking nested ones here would
* deadlock a turn against its own admission. This boundary only ever refuses.
*/
import { isRuntimeBudgetError } from '../lib/aiToolkit/errorDetection.js';
import { normalizePersistentMindMaintainer } from '../lib/persistentMindMaintainer.js';
import { getDomainMode } from '../lib/domainAutonomy.js';
import { canonicalStringify } from '../lib/objects.js';
import { normalizePersistentMindState } from '../lib/persistentMind.js';
import { normalizePersistentMindCapabilities } from '../lib/persistentMindCapabilities.js';
import { buildPersistentMindCallDenial, buildPersistentMindCallReceipt } from '../lib/persistentMindTrajectory.js';
import { loadState } from './cosState.js';
import { appendMindEvent } from './agentRunEventLog.js';
import { getDomainBudgetStatus, recordDomainUsage } from './domainUsage.js';
import { resolvePersistentMindSelfThinkingRequest } from './persistentMindThinkingRequests.js';
import { resolvePersistentMindProfile, resolvePersistentMindThinkingSession } from './persistentMindProfile.js';
/** Mind status a denial should park the turn under, by cause. */
const DENIAL_STATUS = Object.freeze({
interrupted: 'interrupted',
budget: 'waiting',
authorization: 'degraded',
});
const denial = (reason, status, extra = {}) => ({ ok: false, reason, status, code: 'policy', disposition: 'hold', ...extra });
/**
* The comparable fingerprint of the mind's capability grants.
*
* Any change — widening or narrowing — ends the turn's remaining calls. The
* turn's prompt, its tool catalog, and its already-executed rounds were all
* built against the snapshot, so continuing on a different grant set would run
* the second half of a turn under authority the first half never described.
*/
export function persistentMindCapabilityGrantFingerprint(rawCapabilities) {
return canonicalStringify(normalizePersistentMindCapabilities(rawCapabilities)) ?? '';
}
/**
* Decide whether one more provider call may start on this turn.
*
* Ordered cheapest-and-most-decisive first: an aborted turn or a stopped mind
* short-circuits before any provider registry or budget read.
*
* @param {object} input
* @param {string} input.turnId - the turn that must still be the active one
* @param {object} input.route - { providerId, model, effort } pinned at admission
* @param {string} [input.thinkingPresetId] - set for a temporary thinking session
* @param {object} [input.thinkingSelection] - the ACCEPTED preset snapshot (#6283);
* never re-derived from the mutable preset id
* @param {string} [input.capabilityFingerprint] - snapshot from turn admission
* @param {AbortSignal} [input.signal]
* @returns {Promise<{ok: boolean, reason?: string, status?: string, requiresResubmission?: boolean}>}
*/
export async function evaluatePersistentMindCallAdmission({
turnId,
route,
thinkingPresetId = null,
thinkingSelection = null,
selfThinkingRequest = null,
capabilityFingerprint = null,
signal,
maintainerFingerprint = null,
promptChars, promptBytes,
} = {}) {
if (signal?.aborted) {
return denial(String(signal.reason || 'Persistent mind turn interrupted'), DENIAL_STATUS.interrupted);
}
const root = await loadState();
if (root?.paused) return denial('PortOS autonomy was paused during the turn', DENIAL_STATUS.interrupted);
if (getDomainMode(root?.config, 'cos') !== 'execute') {
return denial('CoS autonomy left execute mode during the turn', DENIAL_STATUS.interrupted);
}
const mind = normalizePersistentMindState(root?.persistentMind);
if (!mind.enabled || !mind.started) return denial('Persistent mind was stopped during the turn', DENIAL_STATUS.interrupted);
if (mind.status === 'paused') return denial('Persistent mind was paused during the turn', DENIAL_STATUS.interrupted);
if (mind.activeTurn?.id !== turnId) return denial('Persistent mind turn is no longer the active turn', DENIAL_STATUS.interrupted);
if (capabilityFingerprint !== null
&& persistentMindCapabilityGrantFingerprint(root?.config?.persistentMindCapabilities) !== capabilityFingerprint) {
return denial('Persistent mind capability grants changed during the turn', DENIAL_STATUS.authorization);
}
const maintainer = normalizePersistentMindMaintainer(root?.config?.persistentMindMaintainer);
if (maintainerFingerprint !== null && canonicalStringify(maintainer) !== maintainerFingerprint) {
return denial('Maintainer inference policy changed during the turn', DENIAL_STATUS.authorization);
}
// Provider availability/authorization and preset lifecycle both resolve here:
// the same exact-or-refuse resolvers the supervisor admitted the turn with.
const resolved = selfThinkingRequest
? await resolvePersistentMindSelfThinkingRequest({ request: selfThinkingRequest, config: root?.config })
: thinkingPresetId
? await resolvePersistentMindThinkingSession({ presetId: thinkingPresetId, selection: thinkingSelection, config: root?.config })
: await resolvePersistentMindProfile(root?.config?.persistentMindProfile);
if (!resolved.ok) {
return denial(resolved.error, DENIAL_STATUS.authorization, { requiresResubmission: resolved.requiresResubmission === true });
}
if ((resolved.provider?.id || null) !== (route?.providerId || null)
|| (resolved.model || null) !== (route?.model || null)
|| (resolved.effort || null) !== (route?.effort || null)) {
return denial('Persistent mind route changed during the turn', DENIAL_STATUS.authorization);
}
// Fail closed: an unreadable ledger must not read as unlimited budget.
let budget;
try {
budget = await getDomainBudgetStatus('cos');
} catch (error) {
return denial(`Persistent mind budget check failed: ${error?.message || 'unknown error'}`, DENIAL_STATUS.budget, { code: 'ledger-unavailable' });
}
if (!budget.withinBudget) {
return denial(`CoS ${budget.exceeded || 'daily'} budget exhausted`, DENIAL_STATUS.budget, { code: 'cos-budget-exhausted', disposition: 'retry' });
}
if (maintainer.enabled) {
const { inspectMaintainerInferenceRoute } = await import('./persistentMindMaintainerInference.js');
const checked = await inspectMaintainerInferenceRoute({ role: maintainer, provider: resolved.provider,
model: resolved.model, thinkingPresetId, thinkingSelection, selfThinkingRequest, promptChars, promptBytes });
if (!checked.ok) return denial(checked.reason, DENIAL_STATUS.authorization);
return { ok: true, maintainer: checked };
}
return { ok: true };
}
/**
* Build the per-turn boundary the supervisor hands to the adapter.
*
* `call({ purpose, round }, run)` re-checks admission, runs `run`, times it,
* accounts it against the domain ledger, and writes one bounded receipt to the
* trajectory — for completed, failed, interrupted AND denied attempts. `run`
* receives `{ reportRunId }` so the receipt names the concrete provider run id
* even when the call throws before returning one.
*
* @returns {{call: Function, accountedCalls: () => number}}
*/
export function createPersistentMindCallBoundary({
mindId,
turnId,
route,
thinkingPresetId = null,
thinkingSelection = null,
selfThinkingRequest = null,
capabilityFingerprint = null,
signal,
maintainerFingerprint = null,
now = () => Date.now(),
evaluate = evaluatePersistentMindCallAdmission,
appendEvent = appendMindEvent,
recordUsage = recordDomainUsage,
reserveInference = async args => (await import('./persistentMindMaintainerInference.js')).reserveMaintainerInference(args),
} = {}) {
let receiptIndex = 0;
let accountedCalls = 0;
let runtimeHold = null;
const writeReceipt = async (fields) => {
const index = receiptIndex;
receiptIndex += 1;
const receipt = buildPersistentMindCallReceipt({ turnId, route, ...fields });
await appendEvent({
kind: 'mind.model.call',
mindId,
turnId,
eventId: `mind-model-call:${turnId}:${index}`,
data: receipt,
});
return receipt;
};
const account = async (elapsedMs) => {
accountedCalls += 1;
await recordUsage('cos', { actions: 1, ms: elapsedMs }).catch((error) => {
console.error(`❌ Failed to record persistent mind call usage: ${error.message}`);
});
};
const call = async ({ purpose, round = null, promptChars, promptBytes } = {}, run) => {
if (runtimeHold) throw runtimeHold;
const admission = await evaluate({ turnId, route, thinkingPresetId, thinkingSelection, selfThinkingRequest, capabilityFingerprint, signal, maintainerFingerprint, promptChars, promptBytes });
if (!admission.ok) {
await writeReceipt({ purpose, round, outcome: 'denied', reason: admission.reason });
throw buildPersistentMindCallDenial(admission);
}
let reservation = null;
if (admission.maintainer?.enforced) {
const reserved = await reserveInference({ turnId, lane: admission.maintainer.lane,
policy: admission.maintainer.policy, now }).catch(() => ({ ok: false, reason: 'Maintainer inference budget is unreadable; restore or repair its ledger before retrying.' }));
if (!reserved.ok) {
await writeReceipt({ purpose, round, outcome: 'denied', reason: reserved.reason });
throw buildPersistentMindCallDenial(reserved);
}
reservation = reserved.reservation;
await appendEvent({ kind: 'mind.maintainer.reservation', mindId, turnId,
eventId: `maintainer-reservation:${turnId}:${reservation.turnCall}`, data: reservation });
}
let runId = null;
const reportRunId = (id) => { if (typeof id === 'string' && id) runId = id; };
const startedAt = now();
try {
const result = await run({ reportRunId, timeoutMs: 0 });
const elapsedMs = Math.max(0, now() - startedAt);
reportRunId(result?.runId);
await account(elapsedMs);
await writeReceipt({ purpose, round, runId, elapsedMs, outcome: 'completed', usage: result?.usage });
return result;
} catch (error) {
const elapsedMs = Math.max(0, now() - startedAt);
// The attempt reached the provider, so it is accounted even though it
// produced nothing — an uncertain spend is still a spend, and never a
// reason to silently retry.
await account(elapsedMs);
await writeReceipt({
purpose,
round,
runId,
elapsedMs,
outcome: signal?.aborted ? 'interrupted' : 'failed',
reason: error?.message,
});
if (reservation && !signal?.aborted && isRuntimeBudgetError(error)) {
runtimeHold = Object.assign(buildPersistentMindCallDenial({
reason: `Maintainer runtime budget of ${reservation.timeoutMs}ms exhausted; adjust inference policy and explicitly resume.`,
status: 'waiting', code: 'runtime-budget-exhausted', disposition: 'hold',
}), { cause: error, code: 'RUN_RUNTIME_BUDGET_EXHAUSTED', errorAnalysis: error.errorAnalysis });
throw runtimeHold;
}
throw error;
}
};
return { call, accountedCalls: () => accountedCalls };
}