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
/**
* Character Metrics Grid (#2676, epic #2672)
*
* The "other stats" block on the Character sheet: current-value engagement tiles read off
* the same domain signals the skill registry (#2674) already assembles, so the sheet reads
* like a profile of the human's actual activity rather than a D&D pastiche.
*
* **Metrics are not skills.** Skills are *cumulative* — a level, once earned, never
* un-learns itself. Metrics report the CURRENT value, streaks and rates included, and are
* free to fall. The two are complementary readings of one signal set: `mentalist` says "you
* have practiced 200 times"; `postStreakDays` says "you have practiced 4 days running".
*
* **A tile must be able to MOVE, and must claim only what its signal carries.** Two traps
* worth naming, because both produced a plausible-looking tile that was really a constant or
* an overclaim (caught in review):
* - A ratio whose denominator no UI can populate is a decorative constant — see
* `goalCompletionRate`, where an `abandoned` status exists in the enum but nothing writes.
* - A tally is only as specific as its rows — see `mediaAssets`, an unfiltered count over an
* index that deliberately holds downloads and uploads, so it cannot be called "rendered".
* When picking a new signal, check what the UI actually records before naming the tile.
*
* **No new DOMAIN reads.** Every `compute()` composes signals from `characterSignals.js`, the
* same context the skills fan out over — so the tiles below add no stat reads to
* `GET /api/character`, and a domain the user has never touched still costs nothing extra.
* (`daysActive` added the one non-domain signal, `userTimezone` — a `getSettings()` read, not a
* stat — because a cross-domain day union has to pick a day boundary; see #4120.) There is
* deliberately no new usage-event tracking behind any of this.
*
* **Derived on read, never persisted, never federated.** `getCharacter()` attaches these;
* `saveCharacter()` strips them (`metrics` is in `character.js`'s `DERIVED_FIELDS`) and
* `getWireCharacter()` keeps them off the wire. Same reasoning as skills: usage differs per
* machine, so federating a usage-derived value under LWW would let the peer you use *least*
* overwrite the peer you use *most*.
*
* **Three states, never two (sentinel + validate).** A tile is one of:
* - a real value — `{ value: <number>, unavailable: false, notApplicable: false }`,
* and a real 0 is a legitimate answer ("no memories yet")
* - not applicable — `{ value: null, notApplicable: true }`: the metric is a ratio
* with an empty denominator. There is no honest number, and 0 is
* NOT it — "0% of your goals are done" is a lie to tell someone who
* has never filed one.
* - unavailable — `{ value: null, unavailable: true }`: the stat could not be read.
* Collapsing any of these into a fake 0 is the exact lie the sentinels exist to prevent.
* Both non-value states are distinct SYMBOLS rather than in-band `null`s, so a getter that
* resolves `null` because it is broken lands in `unavailable` and cannot pass itself off as
* a legitimately-empty ratio.
*
* See `characterSignals.js` for the read-failure gap the file-backed signals still have
* (#2726) — it applies identically here, and needs no change in this module when it lands.
*/
import { computeUnifiedStreak } from '../lib/postStreak.js';
import { unionActiveDayKeys } from '../lib/activeDays.js';
import { createSignalContext } from './characterSignals.js';
// Returned by a compute() whose ratio has an empty denominator. A unique Symbol (not null/0)
// so it can never be mistaken for a real value a domain reported, nor for a failed read.
export const METRIC_NOT_APPLICABLE = Symbol('metric-not-applicable');
// Sentinel for a failed stat read. Mirrors characterSkills.js — same reasoning, and kept
// module-private in both so neither can leak into a response payload.
const STAT_UNAVAILABLE = Symbol('stat-unavailable');
/**
* The registry. Each entry is `{ id, label, unit, hint, emptyLabel?, compute }`:
*
* - `unit` — `count` | `days` | `percent`. The client formats off this; the server
* never ships a pre-formatted string (formatting is the client's job —
* `client/src/utils/formatters.js`).
* - `hint` — one-line gloss of what the number actually measures, shown as the tile's
* sublabel. Lives here, next to the compute that defines the semantic, so
* the two can't drift.
* - `emptyLabel` — what to say when compute returns METRIC_NOT_APPLICABLE. Only a ratio
* metric needs one.
* - `compute(read)` — resolves to a non-negative number, or METRIC_NOT_APPLICABLE.
*/
export const METRICS = [
{
id: 'postStreakDays',
label: 'POST Streak',
unit: 'days',
hint: 'Consecutive days of POST practice',
// The unified sessions-OR-training streak — the same helper (and the same user-timezone
// day boundary) the Progress page and the dashboard widgets use, so the Character sheet
// can't quote a different streak than the rest of PortOS (#2091).
compute: async (read) => {
const [sessions, training, today, timezone] = await Promise.all([
read('postSessions'),
read('postTraining'),
read('postToday'),
read('userTimezone'),
]);
return computeUnifiedStreak(sessions, training, today, timezone).current;
},
},
{
id: 'healthLoggingStreak',
label: 'Health Streak',
unit: 'days',
hint: 'Consecutive days with a health log',
compute: async (read) => (await read('loggingStats')).currentStreak,
},
{
id: 'daysActive',
label: 'Days Active',
unit: 'days',
hint: 'Distinct days with any logged activity',
// A UNION of day sets, never a SUM of per-domain day counts. Summing would double-count
// every day the user both practiced POST and logged a health entry — the exact reason this
// tile was cut from #2676 rather than approximated: a POST-only or a summed reading is
// wrong in a way the number itself doesn't advertise.
//
// The two domains disagreed about where a day starts (POST stamps `userLocalToday()`, the
// health logs stamp the server-local `getDateString()`), so the union standardizes on the
// USER-local day and normalizes on read. `server/lib/activeDays.js` owns that decision and
// documents exactly what it can and cannot fix — notably that a stored bare day LABEL is
// taken as authored, because no instant survives to re-derive it from.
//
// The shared streak helper re-keys legacy full-ISO entries through the same user-local
// boundary as this union, while bare `YYYY-MM-DD` labels remain authored day keys.
//
// Missing keys are a FAILED read, not an idle install: each source is validated as an
// array and a throw here lands in `readMetric`'s `unavailable`, so a shape mismatch can
// never render as a confident "0 days active" for someone with years of history.
compute: async (read) => {
const [logging, postEnabled, timezone] = await Promise.all([
read('loggingStats'),
read('postEnabled'),
read('userTimezone'),
]);
if (!Array.isArray(logging?.activeDayKeys)) throw new Error('logging stats reported no activeDayKeys');
if (!postEnabled) return unionActiveDayKeys([logging.activeDayKeys], timezone).length;
const [sessions, training] = await Promise.all([
read('postSessions'),
read('postTraining'),
]);
if (!Array.isArray(sessions)) throw new Error('POST sessions unreadable');
if (!Array.isArray(training)) throw new Error('POST training log unreadable');
return unionActiveDayKeys([
logging.activeDayKeys,
sessions.map((s) => s?.date),
training.map((e) => e?.date),
], timezone).length;
},
},
{
id: 'recordsCreated',
label: 'Records Created',
unit: 'count',
hint: 'Universes, works, catalog entries & scraps',
// Same four tallies Wordsmith levels off — reported raw here rather than on the log
// curve. Shares every read with that skill via the signal context.
compute: async (read) => {
const [universeCount, workCount, catalog] = await Promise.all([
read('universeCount'),
read('workCount'),
read('catalogStats'),
]);
return universeCount + workCount + catalog.total + catalog.scraps;
},
},
{
id: 'memoryCount',
label: 'Memories',
unit: 'count',
hint: 'Active memories across PortOS',
// "across PortOS", NOT "captured in Brain": the signal is `countMemories({})`, and
// `filterMemoryIndex` with no options filters by `status: 'active'` ONLY — so agent-, CoS-
// and API-created memories are all in here, not just the Brain-tagged ones
// (`sourceAppId: 'brain'`, per brainMemoryBridge.js). The whole store is the more useful
// number AND the one that matches the `archivist` skill's reading of the same signal;
// narrowing to Brain would undercount the user's memories and make the two disagree.
compute: async (read) => read('memoryCount'),
},
{
id: 'mediaAssets',
label: 'Media Assets',
unit: 'count',
hint: 'Images & videos in your media library',
// Deliberately "assets in your library", NOT "media you rendered". `countAssets()` is an
// unfiltered COUNT(*) over `media_assets`, which by design holds every on-disk asset:
// `reconcileMediaAssets()` upserts everything in the gallery at boot (uploads included),
// and `videoDownload.js` routes downloads through the same index on purpose. Labelling it
// "Media Rendered" would claim a provenance the row doesn't carry.
//
// Deletes decrement live: the in-app delete paths retire the index row with the file
// (#2738 — `unindexImage`/`unindexVideo` → `removeAsset`). The boot-time
// `reconcileMediaAssets()` sweep remains the backstop for files removed outside PortOS,
// so only an out-of-band disk delete can read high until the next restart.
compute: async (read) => read('assetCount'),
},
{
id: 'goalCompletionRate',
label: 'Goal Completion',
unit: 'percent',
hint: 'Share of your goals that are done',
emptyLabel: 'No goals filed yet',
// Denominator is ALL goals, not just "resolved" (completed + abandoned) ones.
//
// The resolved-only denominator is tempting — it reads as follow-through and doesn't
// penalize having ambitious work in flight — but it CANNOT MOVE on this install. The
// Goals UI (`client/src/components/digital-twin/tabs/GoalsTab.jsx`) offers exactly two
// terminal actions: Complete (writes `status: 'completed'`) and Delete (drops the record
// outright). Nothing in the client ever writes `status: 'abandoned'` — it exists in
// `goalStatusEnum` and is honored by the API and the OpenWorld monuments, but no UI
// produces it. So `abandoned` is always 0, `resolved === completed`, and the tile would
// read a self-congratulatory constant 100% forever after the first completion.
//
// A metric that cannot vary is worse than one with a debatable denominator, so this
// measures what the UI actually records: of the goals you have filed, how many are done.
// If an explicit "abandon" outcome ever ships, an abandoned goal naturally lands in the
// denominator here without a change.
compute: async (read) => {
const { goals } = await read('goals');
const all = goals || [];
// No goals at all → there is no rate. That is NOT 0% (see the header's three states):
// "0% of your goals are done" is a lie to tell someone who has never filed one.
if (all.length === 0) return METRIC_NOT_APPLICABLE;
const completed = all.filter((g) => g?.status === 'completed').length;
return Math.round((completed / all.length) * 100);
},
},
];
/**
* Resolve one metric to its response shape, classifying the three states the header
* describes. Failure paths kept distinct on purpose:
* - `compute` rejects → unavailable (the domain could not be read)
* - `compute` resolves non-finite → unavailable (the domain lied; a fake 0 would read as
* real activity data)
* - `compute` returns the N/A symbol → notApplicable (no honest number exists yet)
* - `compute` resolves 0 → a real, earned 0
*/
async function readMetric(metric, read) {
// `Promise.resolve().then(...)` rather than `metric.compute(read).catch(...)`: a compute
// declared without `async` that throws synchronously would otherwise escape before `.catch`
// is attached, rejecting the whole GET instead of degrading this one tile.
const raw = await Promise.resolve().then(() => metric.compute(read)).catch((err) => {
// `err?.message ?? err` — a non-Error rejection (a thrown string, a rejected `undefined`)
// would otherwise throw *inside* the catch and defeat the per-metric containment below.
console.warn(`⚠️ Character metric ${metric.id}: stat read failed — ${err?.message ?? err}`);
return STAT_UNAVAILABLE;
});
// One uniform shape across all three states — every key is always present, so a consumer
// never has to distinguish "absent key" from "null value" on top of everything else.
const base = {
id: metric.id,
label: metric.label,
unit: metric.unit,
hint: metric.hint,
emptyLabel: metric.emptyLabel ?? null,
};
if (raw === METRIC_NOT_APPLICABLE) {
return { ...base, value: null, unavailable: false, notApplicable: true };
}
if (raw === STAT_UNAVAILABLE || !Number.isFinite(raw) || raw < 0) {
if (raw !== STAT_UNAVAILABLE) {
console.warn(`⚠️ Character metric ${metric.id}: stat returned a non-countable value`);
}
// value stays null — NOT 0 — so no consumer can render an unread domain as an idle one.
return { ...base, value: null, unavailable: true, notApplicable: false };
}
return { ...base, value: raw, unavailable: false, notApplicable: false };
}
/**
* Compute every metric. Signals are read in parallel and each failure is contained to its own
* tile, so one unreachable domain (Postgres down for the memory/catalog reads, say) degrades
* that tile to `unavailable` instead of failing the whole `GET /api/character`.
*
* `read` is the shared signal context — pass the SAME one the skills got (see
* `getCharacterSkills`) or the six signals the two registries share get read twice.
*/
export async function getCharacterMetrics(read = createSignalContext()) {
const postEnabled = await read('postEnabled');
const metrics = postEnabled ? METRICS : METRICS.filter((metric) => metric.id !== 'postStreakDays');
return Promise.all(metrics.map((metric) => readMetric(metric, read)));
}