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
import { createHash, randomUUID } from 'node:crypto';
import { link, open, readFile, readdir } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { z } from 'zod';
import { atomicWrite, ensureDir, unlinkGuarded } from '../lib/fileCore.js';
import { PATHS } from '../lib/paths.js';
const ledgerDir = () => join(PATHS.data, 'image-render-usage');
const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
const timestamp = value => {
if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.test(value)) return null;
const day = value.slice(0, 10);
const calendar = Date.parse(`${day}T00:00:00Z`);
if (!Number.isFinite(calendar) || new Date(calendar).toISOString().slice(0, 10) !== day) return null;
return Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
};
const digest = value => createHash('sha256').update(value).digest('hex');
const hashIdentity = z.string().regex(/^[a-f0-9]{64}$/);
// Missing evidence must fail the ledger read rather than imply a known session
// or a measured zero. Use the same contract for new and existing receipts.
const receiptSchema = z.object({
version: z.literal(1), id: hashIdentity, renderKey: hashIdentity,
occurredAt: z.string().refine(value => timestamp(value) === value),
timestampSource: z.enum(['renderStartedAt', 'createdAt']),
identitySource: z.enum(['codex-session', 'portos-job']),
driverModel: z.string().nullable(),
driverTokens: z.object({
reportedTotal: z.number().int().nonnegative().safe(),
source: z.literal('codex-cli-footer'),
}).nullable(),
imageTokens: z.null(), imageCostUsd: z.null(), allowanceUnits: z.null(),
source: z.literal('portos-saved-render'),
backfillBatch: z.string().regex(uuid).optional(),
});
// Project only accounting evidence. Never persist prompts, filenames, paths or
// session contents. A driver session may produce several image-tool outputs.
export function codexRenderReceipt(meta) {
if (meta?.mode !== 'codex' || meta.cleanedFrom || meta.filmLookFrom || meta.sourceFilename) return null;
const session = uuid.test(meta.codexSessionId) ? meta.codexSessionId : null;
const job = [meta.id, meta.jobId].find(value => typeof value === 'string' && uuid.test(value));
if (!session && !job) return null;
const occurredAt = timestamp(meta.renderStartedAt) || timestamp(meta.createdAt);
if (!occurredAt) return null;
const renderKey = digest(`codex:${session || job}`);
// Without a job id, a recovered tool call supplies a stable output identity.
const outputKey = digest(job ? `codex-job:${job.toLowerCase()}` : `${renderKey}:${meta.codexCallId || 'saved-output'}`);
return {
version: 1, id: outputKey, renderKey, occurredAt,
timestampSource: timestamp(meta.renderStartedAt) ? 'renderStartedAt' : 'createdAt',
identitySource: session ? 'codex-session' : 'portos-job',
driverModel: typeof meta.model === 'string' ? meta.model : null,
driverTokens: Number.isSafeInteger(meta.driverReportedTokens) && meta.driverReportedTokens >= 0
? { reportedTotal: meta.driverReportedTokens, source: 'codex-cli-footer' } : null,
imageTokens: null, imageCostUsd: null, allowanceUnits: null,
source: 'portos-saved-render',
};
}
export async function readRenderReceipts({ directory = ledgerDir() } = {}) {
const entries = await readdir(directory, { withFileTypes: true }).catch(err => {
if (err.code === 'ENOENT') return [];
throw err;
});
const receipts = [];
for (const entry of entries) {
if (!entry.isFile() || !/^[a-f0-9]{64}\.json$/.test(entry.name)) continue;
const receipt = JSON.parse(await readFile(join(directory, entry.name), 'utf8'));
if (!receiptSchema.safeParse(receipt).success || receipt.id !== entry.name.slice(0, -5)) {
throw new Error('Invalid image render usage receipt');
}
receipts.push(receipt);
}
return receipts;
}
// Publish a complete inode without replacing an existing receipt. Unlike a
// read/modify/write ledger this also serializes live renders against a separate
// backfill process. A crash leaves at most an ignored staging file.
export async function publishAccountingFile(path, value) {
await ensureDir(dirname(path));
const staging = join(dirname(path), `.${randomUUID()}.tmp`);
await atomicWrite(staging, value);
try {
await link(staging, path);
// The file bytes were flushed by atomicWrite. Flush the new directory
// entry too; Windows does not support opening directories for fsync.
if (process.platform !== 'win32') {
const directory = await open(dirname(path), 'r');
try { await directory.sync(); } finally { await directory.close(); }
}
return true;
} catch (err) {
if (err.code !== 'EEXIST') throw err;
return false;
} finally {
await unlinkGuarded(staging);
}
}
export async function recordRenderReceipt(receipt, { directory = ledgerDir() } = {}) {
if (!receiptSchema.safeParse(receipt).success) throw new Error('Invalid image render receipt');
const path = join(directory, `${receipt.id}.json`);
let existing = await readFile(path, 'utf8').then(JSON.parse).catch(err => {
if (err.code === 'ENOENT') return undefined;
throw err;
});
if (existing === undefined) {
if (await publishAccountingFile(path, receipt)) return true;
existing = JSON.parse(await readFile(path, 'utf8'));
}
if (!receiptSchema.safeParse(existing).success || existing.id !== receipt.id) throw new Error('Conflicting image render receipt');
return false;
}
// Human-mode Codex prints a token footer, not image usage or a directional
// breakdown. Retain exactly that reported driver total without pricing it or
// adding it again to the independently reconciled text-token ledger.
export function codexDriverReportedTokens(output) {
const match = output.match(/(?:^|\n)tokens used\r?\n([\d,]+)\s*$/);
const value = match ? Number(match[1].replaceAll(',', '')) : NaN;
return Number.isSafeInteger(value) && value >= 0 ? value : null;
}
export async function recordCodexRender(meta) {
const receipt = codexRenderReceipt(meta);
if (!receipt) throw new Error('Codex render lacks accounting identity or original timestamp');
return recordRenderReceipt(receipt);
}
export async function getImageRenderUsage({ from = null, to = null, directory } = {}) {
const receipts = await readRenderReceipts({ directory });
// Filter sessions by their first observed output so a session spanning UTC
// midnight is not counted twice in adjacent reporting windows.
const sessions = new Map();
for (const receipt of receipts) {
const session = sessions.get(receipt.renderKey) || { occurredAt: receipt.occurredAt, outputs: 0, fallback: false, driverTotal: null };
if (receipt.occurredAt < session.occurredAt) session.occurredAt = receipt.occurredAt;
session.outputs++;
if (receipt.driverTokens?.source === 'codex-cli-footer' && Number.isSafeInteger(receipt.driverTokens.reportedTotal)) {
session.driverTotal = Math.max(session.driverTotal ?? 0, receipt.driverTokens.reportedTotal);
}
session.fallback ||= receipt.identitySource === 'portos-job';
sessions.set(receipt.renderKey, session);
}
let renderSessions = 0, savedOutputs = 0, jobIdentitySessions = 0, driverSessionsMeasured = 0, driverReportedTotal = 0;
for (const session of sessions.values()) {
const day = session.occurredAt.slice(0, 10);
if ((from && day < from) || (to && day > to)) continue;
renderSessions++;
savedOutputs += session.outputs;
if (session.fallback) jobIdentitySessions++;
if (session.driverTotal !== null) { driverSessionsMeasured++; driverReportedTotal += session.driverTotal; }
}
return {
scope: 'local-codex-saved-renders', renderGroups: renderSessions, codexSessions: renderSessions - jobIdentitySessions, savedOutputs, jobIdentityGroups: jobIdentitySessions,
driverTokens: driverSessionsMeasured ? { reportedTotal: driverReportedTotal, sessionsMeasured: driverSessionsMeasured } : null,
driverSessionsUnknown: renderSessions - driverSessionsMeasured,
imageTokens: null, imageCostUsd: null, allowanceUnits: null,
};
}