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
/**
* Per-domain autonomy usage ledger (#711, budgets slice).
*
* Tracks how much autonomous work each domain has done *today* so the gate
* sites can compare it against the per-domain caps in `lib/domainBudgets.js`.
* Where `domainAutonomy` answers "may this domain act?" and `domainBudgets`
* defines the caps, this service is the running tally that makes the caps bite.
*
* Storage is one small rolling-day JSON file (`data/cos/domain-usage.json`):
* `{ date: 'YYYY-MM-DD', usage: { brain: { actions, ms }, ... } }`. When the
* stored date isn't today the ledger resets to zero on the next read or write —
* so "daily" budgets reset at UTC midnight, matching how `cosAgents` buckets
* completed agents by `toISOString().slice(0,10)` (budgets and agent archives
* roll over together). All writes serialize on a single file write tail.
*/
import { join } from 'path';
import { PATHS, atomicWrite, readJSONFile } from '../lib/fileUtils.js';
import { createFileWriteQueue } from '../lib/fileWriteQueue.js';
import { DOMAIN_IDS } from '../lib/domainAutonomy.js';
import { getDomainBudget, hasBudget, evaluateBudget } from '../lib/domainBudgets.js';
import { loadState } from './cosState.js';
import { pendingCosActionReservations } from './cosAdmissionReservations.js';
export const USAGE_FILE = join(PATHS.cos, 'domain-usage.json');
// Single tail so two concurrent record calls can't read-modify-write the same
// ledger file and clobber each other (same convention as cosState's withStateLock).
const usageWriteTail = createFileWriteQueue();
// The UTC calendar day key the ledger buckets against. Exported for tests.
export function todayKey() {
return new Date().toISOString().slice(0, 10);
}
function emptyUsageMap() {
return Object.fromEntries(DOMAIN_IDS.map((id) => [id, { actions: 0, ms: 0 }]));
}
// Read the ledger from disk, rolling it to a fresh empty map when the stored
// date isn't today (or the file is missing / hand-edited into a bad shape).
async function readFreshLedger() {
const today = todayKey();
// STRICT (#4115): the fall-through below resets the ledger to an empty map,
// and `recordDomainUsage` writes that back — so a swallowed unreadable file
// both zeroes the Domain Budgets panel's actions/ms and re-opens a domain that
// had already spent its daily cap. Only ENOENT / a stale date are real rolls.
const stored = await readJSONFile(USAGE_FILE, null, { logError: false, strict: true });
if (!stored || stored.date !== today || typeof stored.usage !== 'object' || stored.usage === null) {
return { date: today, usage: emptyUsageMap() };
}
// Backfill any domain missing from an older-shape / partial file, and coerce
// non-numeric tallies to 0 so a hand edit can't poison the math.
const usage = emptyUsageMap();
for (const id of DOMAIN_IDS) {
const u = stored.usage[id];
if (u && typeof u === 'object') {
usage[id] = { actions: Number(u.actions) || 0, ms: Number(u.ms) || 0 };
}
}
return { date: today, usage };
}
/**
* Add to a domain's usage for today (rolling the ledger to a new day if needed).
* No-op for unknown domains or an empty delta.
*
* @param {string} domainId - one of DOMAIN_IDS
* @param {{actions?: number, ms?: number}} delta
*/
export async function recordDomainUsage(domainId, { actions = 0, ms = 0 } = {}) {
if (!DOMAIN_IDS.includes(domainId)) return;
const addActions = Number(actions) || 0;
const addMs = Number(ms) || 0;
if (!addActions && !addMs) return;
await usageWriteTail(async () => {
const ledger = await readFreshLedger();
ledger.usage[domainId].actions += addActions;
ledger.usage[domainId].ms += addMs;
await atomicWrite(USAGE_FILE, ledger);
});
}
/**
* Today's accumulated usage for one domain.
* @returns {Promise<{actions: number, ms: number}>}
*/
export async function getDomainUsageToday(domainId) {
const ledger = await readFreshLedger();
return ledger.usage[domainId] || { actions: 0, ms: 0 };
}
/**
* Today's usage for every domain (for the settings UI).
* @returns {Promise<{date: string, usage: Record<string, {actions: number, ms: number}>}>}
*/
export async function getAllDomainUsageToday() {
return readFreshLedger();
}
/**
* Resolve a domain's live budget status from the stored CoS config + today's
* usage. Domains with no caps short-circuit without reading the ledger. Returns
* the budget and usage too, so the gate sites can log/display specifics.
*
* @param {string} domainId - one of DOMAIN_IDS
* @returns {Promise<{withinBudget: boolean, exceeded: 'actions'|'minutes'|null,
* budget: object, usage: {actions: number, ms: number}}>}
*/
export async function getDomainBudgetStatus(domainId) {
const state = await loadState();
const budget = getDomainBudget(state.config, domainId);
if (!hasBudget(budget)) {
return { withinBudget: true, exceeded: null, budget, usage: { actions: 0, ms: 0 } };
}
const usage = await getDomainUsageToday(domainId);
const effectiveUsage = domainId === 'cos'
? { ...usage, actions: usage.actions + pendingCosActionReservations() }
: usage;
const { withinBudget, exceeded } = evaluateBudget(budget, effectiveUsage);
return { withinBudget, exceeded, budget, usage };
}