@krtclcdy/tersio 2.5.0 → 2.7.0

package/cli/doctor.js

@@ -3,6 +3,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { BUN_BIN_DIR, HOME, OMP_AGENT_DIR, OMP_PLUGINS_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_VERSION, RTK_BINARY_NAME, execP, parseJsonObject, relTime, } from './common.js';
 import { runInteractivePhase } from './interactive.js';
+import { ledgerPath, readUsage } from '../extensions/shared/usage-ledger.js';
 import { checkForUpdate } from './update.js';
 import { readTextIfExists } from '../extensions/lib/utils.js';
 async function runDoctor() {
@@ -21,6 +22,7 @@ async function runDoctor() {
     const rtkIndex = path.join(extDir, 'rtk-session', 'index.js');
     const updaterIndex = path.join(extDir, 'ai-addons-updater', 'index.js');
     const comboIndex = path.join(extDir, 'combo-toggle', 'index.js');
+    const tersioIndex = path.join(extDir, 'tersio-commands', 'index.js');
     const modeReinforcement = path.join(extDir, 'shared', 'mode-reinforcement.js');
     const selfPkg = path.join(pluginsDir, 'node_modules', PACKAGE_NAME, 'package.json');
     // Independent probes start concurrently; sections report in fixed order as
@@ -41,6 +43,7 @@ async function runDoctor() {
         rtkIndexText: readTextIfExists(rtkIndex),
         updaterIndexText: readTextIfExists(updaterIndex),
         comboIndexText: readTextIfExists(comboIndex),
+        tersioIndexText: readTextIfExists(tersioIndex),
         modeReinforcementText: readTextIfExists(modeReinforcement),
         ruleMtime: fs.stat(cavemanRule).catch(() => null),
         rtkMtime: fs.stat(rtkBin).catch(() => null),
@@ -59,11 +62,12 @@ async function runDoctor() {
         probes.configText,
         probes.updateVersion,
     ]));
-    const [cavemanIndexText, rtkIndexText, updaterIndexText, comboIndexText, modeReinforcementText, ponytailPkgText, ponytailExtText, pluginsPkgRaw, selfPkgText] = await runInteractivePhase('Checking extensions and plugins', () => Promise.all([
+    const [cavemanIndexText, rtkIndexText, updaterIndexText, comboIndexText, tersioIndexText, modeReinforcementText, ponytailPkgText, ponytailExtText, pluginsPkgRaw, selfPkgText] = await runInteractivePhase('Checking extensions and plugins', () => Promise.all([
         probes.cavemanIndexText,
         probes.rtkIndexText,
         probes.updaterIndexText,
         probes.comboIndexText,
+        probes.tersioIndexText,
         probes.modeReinforcementText,
         probes.ponytailPkgText,
         probes.ponytailExtText,
@@ -112,6 +116,7 @@ async function runDoctor() {
     check('RTK extension', rtkIndexText !== null);
     check('Updater extension', updaterIndexText !== null);
     check('Combo extension', comboIndexText !== null);
+    check('Tersio commands extension', tersioIndexText !== null);
     check('Mode reinforcement extension', modeReinforcementText !== null);
     section('Plugins');
     check('Ponytail package', ponytailPkgText !== null);
@@ -123,6 +128,9 @@ async function runDoctor() {
     check('Self plugin package', selfPkgText !== null, parseJsonObject(selfPkgText)?.version ?? '');
     const selfDep = PACKAGE_NAME in (parseJsonObject(pluginsPkgRaw)?.dependencies || {});
     check('Self plugin in plugins/package.json', selfDep);
+    section('Usage');
+    const usageRows = readUsage();
+    check('Usage ledger', usageRows.length > 0, usageRows.length ? `${usageRows.length} rows · ${ledgerPath()}` : ledgerPath());
     section('Add-ons');
     const ruleAge = ruleMtime ? `updated ${relTime(Date.now() - ruleMtime.mtimeMs)}` : '';
     check('Caveman rule', cavemanRuleText !== null, ruleAge);

package/cli/install.js

@@ -3,10 +3,13 @@ import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { BUN_BIN_DIR, COMBO_PRESET_MODES, EXTENSIONS_KEY_RE, HOME, IS_WINDOWS, OMP_AGENT_DIR, OMP_PLUGINS_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_VERSION, RTK_BINARY_NAME, SCOPE_MAP, applyUpdate, cavemanDefaultFlag, comboDefaultFlag, command, dryRun, install, ponytailDefaultFlag, profileFlagsGiven, reinstall, rtkDefaultFlag, scopeFlag, verbose, yes, debug, ensureExtensionAfterConfigEntry, ensureExtensionInConfig, ensurePonytailConfigValue, execP, parseJsonObject, readPluginsPackage, writeIfChanged, } from './common.js';
-import { ask, askInteractiveChoice, closeRL, execNetwork, tty, withInteractiveSpinner, } from './interactive.js';
-import { checkForUpdate } from './update.js';
+import { BUN_BIN_DIR, COMBO_PRESET_MODES, EXTENSIONS_KEY_RE, HOME, IS_WINDOWS, OMP_AGENT_DIR, OMP_PLUGINS_DIR, OMP_BIN, PACKAGE_NAME, PACKAGE_VERSION, RTK_BINARY_NAME, SCOPE_MAP, applyUpdate, cavemanDefaultFlag, comboDefaultFlag, command, dryRun, install, ponytailDefaultFlag, profileFlagsGiven, reinstall, rtkDefaultFlag, scopeFlag, verbose, yes, dashboardExport, dashboardOpen, dashboardPort, debug, ensureExtensionAfterConfigEntry, ensureExtensionInConfig, ensurePonytailConfigValue, execP, parseJsonObject, readPluginsPackage, writeIfChanged, } from './common.js';
+import { ask, askInteractiveChoice, askInteractiveConfirm, closeRL, execNetwork, tty, withInteractiveSpinner, } from './interactive.js';
+import { checkForUpdate, runLatestUpdate } from './update.js';
 import { runUninstall } from './uninstall.js';
+import { runDoctor } from './doctor.js';
+import { runUsage } from './usage.js';
+import { runDashboard } from './dashboard.js';
 import { CAVEMAN_REMOTE_RULE, RTK_RELEASE_API, fetchJson, findFile, httpsGet, httpsDownload, parseChecksum, readTextIfExists, rtkPlatformSpec, sha256File, } from '../extensions/lib/utils.js';
 // Paths to extension source files (relative to this script)
 const EXT_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'extensions');
@@ -15,6 +18,7 @@ const CAVEMAN_INDEX = path.join(EXT_DIR, 'caveman-session', 'index.js');
 const RTK_SESSION_INDEX = path.join(EXT_DIR, 'rtk-session', 'index.js');
 const UPDATER_INDEX = path.join(EXT_DIR, 'ai-addons-updater', 'index.js');
 const COMBO_TOGGLE_INDEX = path.join(EXT_DIR, 'combo-toggle', 'index.js');
+const TERSIO_COMMANDS_INDEX = path.join(EXT_DIR, 'tersio-commands', 'index.js');
 const MODE_REINFORCEMENT_INDEX = path.join(EXT_DIR, 'shared', 'mode-reinforcement.js');
 const SHARED_TYPES = path.join(EXT_DIR, 'shared', 'types.js');
 const LIB_UTILS = path.join(EXT_DIR, 'lib', 'utils.js');
@@ -22,7 +26,7 @@ const SHARED_PLUGIN_SETTINGS = path.join(EXT_DIR, 'shared', 'plugin-settings.js'
 const PONYTAIL_GITHUB_SPEC = 'github:DietrichGebert/ponytail';
 const PONYTAIL_NPM_SPEC = '@dietrichgebert/ponytail@latest';
 async function stepPonytail(pluginsDir, userDir, options) {
-    console.log('\n[1/7] Installing Ponytail plugin...');
+    console.log('\n[1/8] Installing Ponytail plugin...');
     await fs.mkdir(pluginsDir, { recursive: true });
     const pkgPath = path.join(pluginsDir, 'package.json');
     const pkg = await readPluginsPackage(pkgPath);
@@ -124,7 +128,7 @@ async function stepPonytail(pluginsDir, userDir, options) {
 // Settings → Plugins page (OMP enumerates plugins/package.json dependencies).
 // Returns true when the package is verified in plugins/node_modules.
 async function stepSelfPlugin(pluginsDir, options) {
-    console.log('\n[2/7] Registering tersio as OMP plugin...');
+    console.log('\n[2/8] Registering tersio as OMP plugin...');
     const pkgPath = path.join(pluginsDir, 'package.json');
     const pkg = await readPluginsPackage(pkgPath);
     pkg.dependencies[PACKAGE_NAME] = `^${PACKAGE_VERSION}`;
@@ -253,7 +257,7 @@ async function extractRtkArchive(archivePath, extractDir) {
     return false;
 }
 async function stepRtk(binDir, options) {
-    console.log('\n[3/7] Installing RTK binary...');
+    console.log('\n[3/8] Installing RTK binary...');
     try {
         const release = await withInteractiveSpinner('Finding latest RTK release', () => fetchJson(RTK_RELEASE_API));
         const triple = resolveRtkTriple();
@@ -342,14 +346,14 @@ async function stepSharedSessionState(extDir, options) {
     ], 'shared/session-state.js', options);
 }
 async function stepModeReinforcement(extDir, ponytailExtPath, options) {
-    console.log('\n[7/7] Installing mode reinforcement extension...');
+    console.log('\n[8/8] Installing mode reinforcement extension...');
     const dest = path.join(extDir, 'shared', 'mode-reinforcement.js');
     if (!await copySources(extDir, [[MODE_REINFORCEMENT_INDEX, path.join('shared', 'mode-reinforcement.js')]], 'shared/mode-reinforcement.js', options))
         return;
     await ensureExtensionAfterConfigEntry(path.join(path.dirname(extDir), 'config.yml'), dest, ponytailExtPath, 'mode reinforcement', options);
 }
 async function stepRtkSession(extDir, options) {
-    console.log('\n[4/7] Installing RTK session extension...');
+    console.log('\n[4/8] Installing RTK session extension...');
     await copySources(extDir, [[RTK_SESSION_INDEX, path.join('rtk-session', 'index.js')]], 'rtk-session/index.js', options);
 }
 // One rule fetch serves user- and project-level installs; dry runs stay offline
@@ -366,7 +370,7 @@ async function fetchCavemanRule(options) {
     }
 }
 async function stepCaveman(extDir, rule, options) {
-    console.log('\n[5/7] Installing Caveman session extension...');
+    console.log('\n[5/8] Installing Caveman session extension...');
     const cavemanDir = path.join(extDir, 'caveman-session');
     if (!options.dryRun)
         await fs.mkdir(cavemanDir, { recursive: true });
@@ -383,11 +387,15 @@ async function stepCaveman(extDir, rule, options) {
     }
     await copySources(extDir, [[CAVEMAN_INDEX, path.join('caveman-session', 'index.js')]], 'caveman-session/index.js', options);
 }
+async function stepTersioCommands(extDir, options) {
+    console.log('\n[7/8] Installing Tersio root-command extension...');
+    await copySources(extDir, [[TERSIO_COMMANDS_INDEX, path.join('tersio-commands', 'index.js')]], 'tersio-commands/index.js', options);
+}
 async function stepUpdater(extDir, options) {
     await copySources(extDir, [[UPDATER_INDEX, path.join('ai-addons-updater', 'index.js')]], 'ai-addons-updater/index.js', options);
 }
 async function stepCombo(extDir, options) {
-    console.log('\n[6/7] Installing Combo toggle extension...');
+    console.log('\n[6/8] Installing Combo toggle extension...');
     const dest = path.join(extDir, 'combo-toggle', 'index.js');
     if (!await copySources(extDir, [[COMBO_TOGGLE_INDEX, path.join('combo-toggle', 'index.js')]], 'combo-toggle/index.js', options))
         return;
@@ -536,7 +544,81 @@ async function writePluginSettings(profile, options) {
     await fs.writeFile(lockPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
     console.log(`  [write] Plugin settings in ${lockPath}`);
 }
+let updatePromptDone = false;
+// Bare `tersio` at a terminal is a command picker, not an install run:
+// update offer first (when pending), then a Clack menu over every command.
+// Scripts, pipes, --yes, and --dry-run keep the old straight-to-install path.
+async function runCommandMenu() {
+    const newer = await checkForUpdate();
+    if (newer && !dryRun) {
+        const answer = await askInteractiveConfirm(`tersio ${newer} is available (installed ${PACKAGE_VERSION}). Install it now?`);
+        if (answer.status === 'confirmed' && answer.value) {
+            await runLatestUpdate();
+            closeRL();
+            return;
+        }
+        if (answer.status === 'cancelled') {
+            closeRL();
+            process.exit(130);
+        }
+        console.log(`\n  [update] staying on ${PACKAGE_VERSION} — run ` + '`tersio update`' + ` anytime`);
+    }
+    updatePromptDone = true;
+    const choice = await askInteractiveChoice('Tersio — what next?', [
+        { value: 'install', label: 'Install add-ons', hint: 'user/project scope + combo defaults' },
+        { value: 'check', label: 'Check for updates', hint: 'compare installed vs latest release' },
+        { value: 'update', label: 'Update everything', hint: 'CLI plus all ai-addons' },
+        { value: 'doctor', label: 'Doctor', hint: 'verify the installation' },
+        { value: 'usage', label: 'Usage', hint: 'token usage and savings report' },
+        { value: 'gain', label: 'Gain dashboard', hint: 'open the report in your browser' },
+        { value: 'dashboard', label: 'Serve dashboard', hint: 'localhost server, no browser' },
+        { value: 'uninstall', label: 'Uninstall', hint: 'remove tersio' },
+    ], 'install');
+    if (choice.status !== 'selected') {
+        closeRL();
+        process.exit(130);
+    }
+    switch (choice.value) {
+        case 'install':
+            await runInstall();
+            break;
+        case 'check': {
+            const latest = await checkForUpdate();
+            console.log(latest ? `  [update] tersio ${latest} available (installed ${PACKAGE_VERSION})` : `  [ok] tersio ${PACKAGE_VERSION} is the latest`);
+            closeRL();
+            break;
+        }
+        case 'update':
+            await runLatestUpdate();
+            closeRL();
+            break;
+        case 'doctor':
+            await runDoctor();
+            closeRL();
+            break;
+        case 'usage':
+            await runUsage();
+            closeRL();
+            break;
+        case 'gain':
+            await runDashboard({ port: dashboardPort, open: true, exportFile: null });
+            closeRL();
+            break;
+        case 'dashboard':
+            await runDashboard({ port: dashboardPort, open: dashboardOpen, exportFile: dashboardExport });
+            closeRL();
+            break;
+        case 'uninstall':
+            await runUninstall();
+            closeRL();
+            break;
+    }
+}
 async function runInstall() {
+    if (command === null && tty() && !yes) {
+        await runCommandMenu();
+        return;
+    }
     if (reinstall) {
         await runUninstall({ yes: true, removePonytail: false, removeRtk: true });
     }
@@ -550,8 +632,27 @@ async function runInstall() {
     // the apply-update payload, which is itself an update run.
     if (tty() && !applyUpdate && command !== 'uninstall') {
         const newer = await checkForUpdate();
-        if (newer)
-            console.log(`\n  [update] tersio ${newer} available (installed ${PACKAGE_VERSION}) — run \`tersio update\``);
+        if (newer) {
+            // Bare `tersio` with an update pending: offer it now (Y/n) instead of
+            // burying the banner above the install prompts. Yes runs the full
+            // update and stops here — the fresh binary owns what follows.
+            if (command === null && !dryRun && !yes && !updatePromptDone) {
+                const answer = await askInteractiveConfirm(`tersio ${newer} is available (installed ${PACKAGE_VERSION}). Install it now?`);
+                if (answer.status === 'confirmed' && answer.value) {
+                    await runLatestUpdate();
+                    closeRL();
+                    return;
+                }
+                if (answer.status === 'cancelled') {
+                    closeRL();
+                    process.exit(130);
+                }
+                console.log(`\n  [update] staying on ${PACKAGE_VERSION} — run \`tersio update\` anytime`);
+            }
+            else {
+                console.log(`\n  [update] tersio ${newer} available (installed ${PACKAGE_VERSION}) — run \`tersio update\``);
+            }
+        }
     }
     const scope = await resolveScope();
     // Resolve session defaults: flags > interactive prompt > defaults.
@@ -583,6 +684,7 @@ async function runInstall() {
         await stepRtkSession(userExtDir, options);
         await stepCaveman(userExtDir, cavemanRule, options);
         await stepCombo(userExtDir, options);
+        await stepTersioCommands(userExtDir, options);
         await stepModeReinforcement(userExtDir, ponytailExtPath, options);
         await stepUpdater(userExtDir, options);
         if (selfPlugin)
@@ -594,6 +696,7 @@ async function runInstall() {
         await stepSharedSessionState(projectExtDir, options);
         await stepRtkSession(projectExtDir, options);
         await stepCaveman(projectExtDir, cavemanRule, options);
+        await stepTersioCommands(projectExtDir, options);
         await stepUpdater(projectExtDir, options);
         console.log('  [note] Ponytail, RTK binary, and Combo toggle require user-level (global) install');
     }

package/cli/interactive.js

@@ -1,6 +1,6 @@
 // cli/interactive.ts — TTY layer: readline, Clack spinners, selects, task phases.
 import readline from 'node:readline';
-import { cancel as clackCancel, select as clackSelect, spinner as clackSpinner, tasks as clackTasks } from '@clack/prompts';
+import { cancel as clackCancel, confirm as clackConfirm, select as clackSelect, spinner as clackSpinner, tasks as clackTasks } from '@clack/prompts';
 import { execP } from './common.js';
 const RL = readline.createInterface({ input: process.stdin, output: process.stdout });
 let rlOpen = true;
@@ -56,6 +56,17 @@ async function askInteractiveChoice(message, options, initialValue) {
     }
     return { status: 'selected', value: choice };
 }
+async function askInteractiveConfirm(message, initialValue = true) {
+    if (!tty())
+        return { status: 'unavailable' };
+    closeRL();
+    const answer = await clackConfirm({ message, initialValue });
+    if (typeof answer !== 'boolean') {
+        clackCancel('Aborted.');
+        return { status: 'cancelled' };
+    }
+    return { status: 'confirmed', value: answer };
+}
 // Run collecting work under one TTY-only Clack task. Callers print after the
 // task completes, keeping normal output out of the spinner animation.
 async function runInteractivePhase(title, collect) {
@@ -69,4 +80,4 @@ async function runInteractivePhase(title, collect) {
 async function execNetwork(label, cmd, args, opts = {}) {
     return withInteractiveSpinner(label, () => execP(cmd, args, opts));
 }
-export { ask, closeRL, tty, withInteractiveSpinner, execNetwork, askInteractiveChoice, runInteractivePhase, };
+export { ask, closeRL, tty, withInteractiveSpinner, execNetwork, askInteractiveChoice, askInteractiveConfirm, runInteractivePhase, };

package/cli/uninstall.js

@@ -71,6 +71,7 @@ async function runUninstall(options = {}) {
         'rtk-session',
         'ai-addons-updater',
         'combo-toggle',
+        'tersio-commands',
         'shared',
         // Only consumed by ai-addons-updater (removed above); otherwise orphaned.
         'lib',

package/cli/usage.js

@@ -0,0 +1,71 @@
+// cli/usage.ts — ledger + session-token usage report, tokscale-style.
+import { co2Grams, importSessionTokens, readUsage, usdCost, } from '../extensions/shared/usage-ledger.js';
+import { withInteractiveSpinner } from './interactive.js';
+export function summarizeUsage(rows) {
+    const byKind = {};
+    const detailCounts = {};
+    for (const r of rows) {
+        byKind[r.kind] = (byKind[r.kind] ?? 0) + 1;
+        detailCounts[r.detail] = (detailCounts[r.detail] ?? 0) + 1;
+    }
+    const byDetail = Object.entries(detailCounts).sort((a, b) => b[1] - a[1]).slice(0, 10);
+    const session = importSessionTokens();
+    let usd = 0;
+    let priced = true;
+    for (const [model, t] of Object.entries(session.byModel)) {
+        const c = usdCost(t, model);
+        usd += c.usd;
+        if (!c.priced)
+            priced = false;
+    }
+    return {
+        total: rows.length,
+        byKind,
+        byDetail,
+        lastWrite: rows.length ? new Date(rows[rows.length - 1].ts).toISOString() : null,
+        empty: rows.length === 0 && session.messages === 0,
+        messages: session.messages,
+        tokens: session.totals,
+        byModel: session.byModel,
+        byDay: session.byDay,
+        usd,
+        priced,
+        co2g: co2Grams(session.totals.output),
+    };
+}
+function fmt(n) {
+    return n.toLocaleString('en-US');
+}
+function printReport(report) {
+    console.log('\n=== Tersio Usage ===');
+    if (report.empty) {
+        console.log('  No ledger rows or session tokens yet — run session commands first.');
+        return;
+    }
+    const t = report.tokens;
+    console.log(`  Tokens  input ${fmt(t.input)} · output ${fmt(t.output)} · cache read ${fmt(t.cacheRead)} · cache write ${fmt(t.cacheWrite)} (${report.messages} assistant messages)`);
+    console.log(`  Cost    $${report.usd.toFixed(2)}${report.priced ? '' : ' (includes default pricing for unknown models)'} · CO2 ~${report.co2g.toFixed(1)}g (est.)`);
+    const models = Object.entries(report.byModel).sort((a, b) => (b[1].input + b[1].output) - (a[1].input + a[1].output)).slice(0, 5);
+    if (models.length) {
+        console.log('  By model');
+        for (const [model, b] of models) {
+            console.log(`    ${model}: in ${fmt(b.input)} · out ${fmt(b.output)} · cache r/w ${fmt(b.cacheRead)}/${fmt(b.cacheWrite)}`);
+        }
+    }
+    if (report.total) {
+        console.log('  Activity');
+        for (const [kind, n] of Object.entries(report.byKind)) {
+            console.log(`    ${kind}: ${n}`);
+        }
+        console.log('  Top commands');
+        for (const [detail, n] of report.byDetail) {
+            console.log(`    ${n}× ${detail}`);
+        }
+        console.log(`  Total rows: ${report.total} · last write: ${report.lastWrite}`);
+    }
+}
+async function runUsage() {
+    const report = await withInteractiveSpinner('Reading usage ledger', async () => summarizeUsage(readUsage()));
+    printReport(report);
+}
+export { runUsage };

package/extensions/ai-addons-updater/index.js

@@ -82,6 +82,33 @@ function checkCaveman() {
         return `Caveman ${status}: local=${localHash || '—'} remote=${remoteHash}`;
     });
 }
+export async function checkAddonsSummary(ctx) {
+    return checkAddons(ctx);
+}
+export async function runAddonUpdate(pi, ctx, target, dryRun = false) {
+    const results = [];
+    const updaters = {
+        ponytail: () => updatePonytail(pi, ctx, dryRun),
+        rtk: () => updateRtk(ctx, dryRun),
+        caveman: () => updateCaveman(ctx, dryRun),
+    };
+    if (target === 'all') {
+        notify(ctx, `ai-addons update all${dryRun ? ' dry-run' : ''}: starting ponytail → rtk → caveman sequentially…`, 'info');
+        for (const name of ['ponytail', 'rtk', 'caveman'])
+            results.push(await updaters[name]());
+        if (!dryRun)
+            results.push(RELOAD_MSG);
+        notify(ctx, `ai-addons update all ${dryRun ? 'dry-run ' : ''}complete.${dryRun ? '' : ` ${RELOAD_MSG}`}`, 'info');
+    }
+    else if (Object.hasOwn(updaters, target)) {
+        results.push(await updaters[target]());
+    }
+    else {
+        const m = 'Usage: /ai-addons update <ponytail|rtk|caveman|all> [--dry-run]';
+        return report(ctx, m, 'warning');
+    }
+    return results.join('\n\n');
+}
 async function checkAddons(ctx) {
     const [ponytail, rtk, caveman] = await Promise.all([checkPonytail(), checkRtk(), checkCaveman()]);
     const lines = [];
@@ -294,29 +321,7 @@ export default function aiAddonsUpdaterExtension(pi) {
                 return summary;
             }
             if (sub === 'update' && cleanParts[1]) {
-                const target = cleanParts.slice(1).join(' ');
-                const results = [];
-                const updaters = {
-                    ponytail: () => updatePonytail(pi, ctx, dryRun),
-                    rtk: () => updateRtk(ctx, dryRun),
-                    caveman: () => updateCaveman(ctx, dryRun),
-                };
-                if (target === 'all') {
-                    notify(ctx, `ai-addons update all${dryRun ? ' dry-run' : ''}: starting ponytail → rtk → caveman sequentially…`, 'info');
-                    for (const name of ['ponytail', 'rtk', 'caveman'])
-                        results.push(await updaters[name]());
-                    if (!dryRun)
-                        results.push(RELOAD_MSG);
-                    notify(ctx, `ai-addons update all ${dryRun ? 'dry-run ' : ''}complete.${dryRun ? '' : ` ${RELOAD_MSG}`}`, 'info');
-                }
-                else if (Object.hasOwn(updaters, target)) {
-                    results.push(await updaters[target]());
-                }
-                else {
-                    const m = 'Usage: /ai-addons update <ponytail|rtk|caveman|all> [--dry-run]';
-                    return report(ctx, m, 'warning');
-                }
-                return results.join('\n\n');
+                return runAddonUpdate(pi, ctx, cleanParts.slice(1).join(' '), dryRun);
             }
             const m = 'Usage: /ai-addons <check|status|update ponytail|rtk|caveman|all> [--dry-run]';
             return report(ctx, m, 'warning');

package/extensions/shared/usage-ledger.js

@@ -0,0 +1,156 @@
+// Shared usage ledger: append-only JSON-lines file. One source of truth read
+// by `tersio usage`, `/tersio usage`, and the gain dashboard.
+// Best-effort by design: a ledger failure never breaks the caller, and
+// corrupt lines are skipped on read (same pattern as the config normalizer).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function ledgerPath() {
+    const override = process.env.TERSIO_USAGE_FILE;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.omp', 'plugins', 'tersio-usage.jsonl');
+}
+export function appendUsage(kind, detail) {
+    const row = JSON.stringify({ ts: Date.now(), kind, detail }) + '\n';
+    try {
+        fs.mkdirSync(path.dirname(ledgerPath()), { recursive: true });
+        fs.appendFileSync(ledgerPath(), row, 'utf8');
+    }
+    catch { /* ledger is best-effort; never break the caller */ }
+}
+function zeroBreakdown() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+function addInto(into, u) {
+    for (const k of ['input', 'output', 'cacheRead', 'cacheWrite']) {
+        const v = u[k];
+        if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+            into[k] += Math.floor(v);
+    }
+}
+export function sessionsDir() {
+    const override = process.env.TERSIO_SESSIONS_DIR;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.omp', 'agent', 'sessions');
+}
+function dayKey(ts) {
+    const ms = typeof ts === 'number' ? ts : Date.parse(ts);
+    if (!Number.isFinite(ms))
+        return null;
+    const d = new Date(ms);
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+function walkJsonl(dir, out, cap) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (out.length >= cap)
+            return;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            walkJsonl(full, out, cap);
+        else if (e.isFile() && e.name.endsWith('.jsonl'))
+            out.push(full);
+    }
+}
+export function importSessionTokens() {
+    const byModel = {};
+    const byDay = {};
+    const totals = zeroBreakdown();
+    let messages = 0;
+    const files = [];
+    walkJsonl(sessionsDir(), files, 2000);
+    for (const file of files) {
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const row = JSON.parse(line);
+                const msg = row.message;
+                if (!msg || msg.role !== 'assistant' || !msg.usage)
+                    continue;
+                const model = typeof msg.model === 'string' && msg.model ? msg.model : 'unknown';
+                addInto(totals, msg.usage);
+                byModel[model] ??= zeroBreakdown();
+                addInto(byModel[model], msg.usage);
+                const day = row.timestamp !== undefined ? dayKey(row.timestamp) : null;
+                if (day) {
+                    byDay[day] ??= zeroBreakdown();
+                    addInto(byDay[day], msg.usage);
+                }
+                messages += 1;
+            }
+            catch { /* skip corrupt lines */ }
+        }
+    }
+    return { messages, totals, byModel, byDay };
+}
+const PRICE_TABLE = [
+    { match: ':free', price: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } },
+    { match: 'opus', price: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 } },
+    { match: 'sonnet', price: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 } },
+    { match: 'haiku', price: { input: 0.8, output: 4, cacheRead: 0.08, cacheWrite: 1 } },
+    { match: 'gpt', price: { input: 2.5, output: 10, cacheRead: 1.25, cacheWrite: 2.5 } },
+    { match: 'gemini', price: { input: 1.25, output: 10, cacheRead: 0.125, cacheWrite: 1.25 } },
+    { match: 'glm', price: { input: 0.5, output: 1, cacheRead: 0.05, cacheWrite: 0.5 } },
+];
+const DEFAULT_PRICE = { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 };
+export function priceFor(model) {
+    const name = model.toLowerCase();
+    for (const row of PRICE_TABLE) {
+        if (name.includes(row.match))
+            return { price: row.price, known: true };
+    }
+    return { price: DEFAULT_PRICE, known: false };
+}
+export function usdCost(t, model) {
+    const { price, known } = model ? priceFor(model) : { price: DEFAULT_PRICE, known: false };
+    const m = 1 / 1_000_000;
+    return {
+        usd: (t.input * price.input + t.output * price.output + t.cacheRead * price.cacheRead + t.cacheWrite * price.cacheWrite) * m,
+        priced: model ? known : false,
+    };
+}
+// ponytail: CO2 is a rough server-energy multiple on output tokens, not metered.
+// Always render with ~est. and never merge with measured figures.
+export const CO2_G_PER_1K_OUTPUT = 0.2;
+export function co2Grams(outputTokens) {
+    return (outputTokens / 1000) * CO2_G_PER_1K_OUTPUT;
+}
+export function readUsage() {
+    let text;
+    try {
+        text = fs.readFileSync(ledgerPath(), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (typeof row.ts === 'number' && typeof row.kind === 'string' && typeof row.detail === 'string') {
+                rows.push({ ts: row.ts, kind: row.kind, detail: row.detail });
+            }
+        }
+        catch { /* skip corrupt lines */ }
+    }
+    return rows;
+}