@krtclcdy/tersio 2.23.0 → 2.24.0

package/extensions/shared/host.ts

@@ -0,0 +1,104 @@
+// extensions/shared/host.ts — one extension source, two agent hosts.
+//
+// OMP is a fork of pi, and six surfaces differ: tool schemas (OMP injects
+// `pi.zod`, pi takes any object it forwards as JSON Schema), `setLabel`
+// (pi's takes an entryId, so an extension name must never reach it),
+// `session_branch` (pi reports that switch as `session_tree`), select options
+// (pi takes plain strings), the status-bar theme (pi has no ctx.ui.theme), and
+// prompt injection (pi appends to its sections rather than replacing them).
+//
+// The host is read from the API shape, never a name or an env marker: OMP is
+// the fork that injects zod, and pi does not, including through the SDK.
+
+import { asPromptArray } from './session-state.ts';
+import type { ExtensionApi, ExtensionCtx, PromptInjection, SystemPromptEvent, ToolParams, UiApi } from './types.ts';
+
+/** The zod subset the one tool schema needs. */
+export interface ZodChain {
+  min: (n: number) => ZodChain;
+  describe: (text: string) => ZodChain;
+}
+
+export interface ZodFactory {
+  z: {
+    object: (shape: Record<string, unknown>) => ToolParams;
+    array: (element: unknown) => ZodChain;
+    string: () => ZodChain;
+  };
+}
+
+/** The host fields these adapters read. */
+export interface HostHandle {
+  zod?: unknown;
+  setLabel?: (...args: string[]) => void;
+}
+
+export function isPiHost(pi: HostHandle): boolean {
+  return !pi.zod;
+}
+
+export function setExtensionLabel(pi: HostHandle, label: string): void {
+  if (isPiHost(pi)) return;
+  pi.setLabel?.(label);
+}
+
+export function onHostEvent<E>(pi: ExtensionApi, event: string, handler: (event: E, ctx: ExtensionCtx) => unknown): void {
+  if (event === 'session_branch' && isPiHost(pi)) return;
+  pi.on<E>(event, handler);
+}
+
+export interface SelectOption {
+  label: string;
+  description?: string;
+}
+
+// Returns the option's label on both hosts: pi renders plain strings, so the
+// description rides along inside the label and is stripped back out.
+export async function hostSelect(
+  pi: HostHandle,
+  ui: UiApi | undefined,
+  title: string,
+  options: SelectOption[],
+  dialogOptions?: Record<string, unknown>,
+): Promise<string | undefined> {
+  if (!ui?.select) return undefined;
+  if (!isPiHost(pi)) return ui.select(title, options, dialogOptions);
+  const shown = options.map((option) => (option.description ? `${option.label} — ${option.description}` : option.label));
+  const picked = await ui.select(title, shown, dialogOptions);
+  if (picked === undefined) return undefined;
+  return options[shown.indexOf(picked)]?.label ?? picked;
+}
+
+// What a `before_agent_start` handler hands back; undefined once pi was
+// updated in place.
+export function injectPromptText(pi: HostHandle, event: SystemPromptEvent, text: string): PromptInjection | undefined {
+  if (!isPiHost(pi)) return { systemPrompt: [...asPromptArray(event.systemPrompt), text] };
+  // Appending keeps pi's sections and the transcript diff; replacing the
+  // prompt the OMP way would drop every section.
+  const options = event.systemPromptOptions;
+  if (options && typeof options.appendSystemPrompt === 'string') {
+    options.appendSystemPrompt = [options.appendSystemPrompt, text].filter(Boolean).join('\n\n');
+    return undefined;
+  }
+  return { systemPrompt: `${asPromptArray(event.systemPrompt).join('\n\n')}\n\n${text}` };
+}
+
+export interface StringArraySpec {
+  minItems?: number;
+  description?: string;
+}
+
+// One string-array argument in the active host's dialect. pi only requires an
+// object, so a JSON Schema literal suffices and no `typebox` import is needed.
+export function stringArrayToolParams(pi: ExtensionApi, name: string, spec: StringArraySpec = {}): ToolParams {
+  if (!isPiHost(pi)) {
+    const { z } = pi.zod as { z: ZodFactory['z'] };
+    const array = z.array(z.string());
+    const constrained = spec.minItems ? array.min(spec.minItems) : array;
+    return z.object({ [name]: spec.description ? constrained.describe(spec.description) : constrained });
+  }
+  const array: Record<string, unknown> = { type: 'array', items: { type: 'string' } };
+  if (spec.minItems) array.minItems = spec.minItems;
+  if (spec.description) array.description = spec.description;
+  return { type: 'object', properties: { [name]: array }, required: [name] };
+}

package/extensions/shared/omp-prompt.js

@@ -0,0 +1,12 @@
+// extensions/omp/omp-prompt.ts — OMP's system-prompt surface.
+// The subagent marker OMP puts in a delegated agent's prompt.
+export const OMP_SUBAGENT_MARKER = 'You are operating on a piece of work assigned to you by the main agent.';
+export function asPromptArray(systemPrompt) {
+    return Array.isArray(systemPrompt) ? systemPrompt : [systemPrompt];
+}
+export function systemPromptIncludes(systemPrompt, marker) {
+    return asPromptArray(systemPrompt).some((prompt) => typeof prompt === 'string' && prompt.includes(marker));
+}
+export function isOmpSubagentPrompt(systemPrompt) {
+    return systemPromptIncludes(systemPrompt, OMP_SUBAGENT_MARKER);
+}

package/extensions/shared/plugin-settings.js

@@ -1,22 +1,31 @@
-// Plugin settings reader for the Tersio extensions.
-// Reads omp's persisted plugin state (~/.omp/plugins/omp-plugins.lock.json),
-// written by `omp plugin config set @krtclcdy/tersio <key> <value>` and by
-// the installer profile step. Tolerant: any parse failure yields {} so every
-// caller falls back to its own default.
+// Settings reader for the Tersio extensions.
+//
+// One file, under Tersio's own home (~/.tersio/settings.json), serves every
+// host: OMP has no reason to keep its own copy and pi never had a store. The
+// profile CLI writes the same file, so the extensions, `tersio settings`, and
+// both hosts always agree.
+//
+// Tolerant: any parse failure yields {} so every caller falls back to its own
+// default.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { tersioHome } from '../lib/utils.js';
 export const PLUGIN_NAME = '@krtclcdy/tersio';
-function lockPaths() {
+// Session-start defaults, shared by every host: one file under Tersio's own
+// home, so OMP and pi read the same values. This module owns the path.
+export function tersioSettingsFile() {
+    return path.join(tersioHome(), 'settings.json');
+}
+// Older installs stored the same values as OMP plugin settings, and an install
+// that predates ~/.tersio still has them there. Read once and keep them, so
+// switching the store does not reset a user's defaults.
+function legacyOmpSettings() {
     const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-    return [
+    for (const p of [
         path.join(os.homedir(), '.omp', 'plugins', 'omp-plugins.lock.json'),
         path.join(configHome, 'omp', 'plugins', 'omp-plugins.lock.json'),
-    ];
-}
-// `settings[PLUGIN_NAME]` in the lock file; empty object when missing.
-export function readPluginSettings() {
-    for (const p of lockPaths()) {
+    ]) {
         if (!existsSync(p))
             continue;
         try {
@@ -27,7 +36,23 @@ export function readPluginSettings() {
         }
         catch { /* tolerate corrupt file */ }
     }
-    return {};
+    return null;
+}
+function readSettingsFile() {
+    const p = tersioSettingsFile();
+    if (!existsSync(p))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The stored settings; empty when the file is missing, corrupt, or empty.
+export function readPluginSettings() {
+    return readSettingsFile() ?? legacyOmpSettings() ?? {};
 }
 const COMBO_LEVELS = new Set(['off', 'medium', 'balanced', 'max']);
 const CAVEMAN_MODES = new Set(['off', 'lite', 'full', 'ultra', 'wenyan', 'wenyan-lite', 'wenyan-full', 'wenyan-ultra']);
@@ -61,25 +86,13 @@ const COMBO_MODE_DEFAULTS = {
 export function saveComboSetup(level) {
     if (!(level in COMBO_MODE_DEFAULTS))
         return false;
-    const lockPath = lockPaths()[0];
-    let lock = {};
-    if (existsSync(lockPath)) {
-        try {
-            lock = JSON.parse(readFileSync(lockPath, 'utf8'));
-        }
-        catch {
-            lock = {};
-        }
-    }
-    lock.plugins ||= {};
-    lock.settings ||= {};
-    lock.settings[PLUGIN_NAME] = {
-        ...lock.settings[PLUGIN_NAME],
+    const file = tersioSettingsFile();
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({
+        ...readPluginSettings(),
         comboDefault: level,
         ...COMBO_MODE_DEFAULTS[level],
         comboSetupComplete: true,
-    };
-    mkdirSync(path.dirname(lockPath), { recursive: true });
-    writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+    }, null, 2)}\n`, 'utf8');
     return true;
 }

package/extensions/shared/plugin-settings.ts

@@ -1,25 +1,35 @@
-// Plugin settings reader for the Tersio extensions.
-// Reads omp's persisted plugin state (~/.omp/plugins/omp-plugins.lock.json),
-// written by `omp plugin config set @krtclcdy/tersio <key> <value>` and by
-// the installer profile step. Tolerant: any parse failure yields {} so every
-// caller falls back to its own default.
+// Settings reader for the Tersio extensions.
+//
+// One file, under Tersio's own home (~/.tersio/settings.json), serves every
+// host: OMP has no reason to keep its own copy and pi never had a store. The
+// profile CLI writes the same file, so the extensions, `tersio settings`, and
+// both hosts always agree.
+//
+// Tolerant: any parse failure yields {} so every caller falls back to its own
+// default.
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { tersioHome } from '../lib/utils.ts';
+
 export const PLUGIN_NAME = '@krtclcdy/tersio';
 
-function lockPaths(): string[] {
+// Session-start defaults, shared by every host: one file under Tersio's own
+// home, so OMP and pi read the same values. This module owns the path.
+export function tersioSettingsFile(): string {
+  return path.join(tersioHome(), 'settings.json');
+}
+
+// Older installs stored the same values as OMP plugin settings, and an install
+// that predates ~/.tersio still has them there. Read once and keep them, so
+// switching the store does not reset a user's defaults.
+function legacyOmpSettings(): Record<string, unknown> | null {
   const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
-  return [
+  for (const p of [
     path.join(os.homedir(), '.omp', 'plugins', 'omp-plugins.lock.json'),
     path.join(configHome, 'omp', 'plugins', 'omp-plugins.lock.json'),
-  ];
-}
-
-// `settings[PLUGIN_NAME]` in the lock file; empty object when missing.
-export function readPluginSettings(): Record<string, unknown> {
-  for (const p of lockPaths()) {
+  ]) {
     if (!existsSync(p)) continue;
     try {
       const config = JSON.parse(readFileSync(p, 'utf8')) as { settings?: Record<string, Record<string, unknown>> };
@@ -27,7 +37,23 @@ export function readPluginSettings(): Record<string, unknown> {
       if (values && typeof values === 'object' && !Array.isArray(values)) return values;
     } catch { /* tolerate corrupt file */ }
   }
-  return {};
+  return null;
+}
+
+function readSettingsFile(): Record<string, unknown> | null {
+  const p = tersioSettingsFile();
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown>;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// The stored settings; empty when the file is missing, corrupt, or empty.
+export function readPluginSettings(): Record<string, unknown> {
+  return readSettingsFile() ?? legacyOmpSettings() ?? {};
 }
 
 const COMBO_LEVELS = new Set(['off', 'medium', 'balanced', 'max']);
@@ -69,20 +95,13 @@ const COMBO_MODE_DEFAULTS = {
 
 export function saveComboSetup(level: string): boolean {
   if (!(level in COMBO_MODE_DEFAULTS)) return false;
-  const lockPath = lockPaths()[0];
-  let lock: { plugins?: Record<string, unknown>; settings?: Record<string, Record<string, unknown>> } = {};
-  if (existsSync(lockPath)) {
-    try { lock = JSON.parse(readFileSync(lockPath, 'utf8')) as typeof lock; } catch { lock = {}; }
-  }
-  lock.plugins ||= {};
-  lock.settings ||= {};
-  lock.settings[PLUGIN_NAME] = {
-    ...lock.settings[PLUGIN_NAME],
+  const file = tersioSettingsFile();
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({
+    ...readPluginSettings(),
     comboDefault: level,
     ...COMBO_MODE_DEFAULTS[level as keyof typeof COMBO_MODE_DEFAULTS],
     comboSetupComplete: true,
-  };
-  mkdirSync(path.dirname(lockPath), { recursive: true });
-  writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+  }, null, 2)}\n`, 'utf8');
   return true;
 }

package/extensions/shared/pricing.js

@@ -1,17 +1,14 @@
 // extensions/shared/pricing.ts — dynamic model pricing from LiteLLM.
-// Lookup order: exact id in the live cache → provider-prefix strip → default.
-// The cache is the full LiteLLM feed (3k+ ids), refreshed lazily in background
-// and on `tersio update`; every reader is sync and offline-safe. No static
-// per-model table — list prices rot, the feed does not. Unknown models report
-// the default with known:false so the dashboard labels them honestly.
+// Exact id → provider-prefix strip → default, which reports with known:false so
+// the Dashboard labels an unpriced model honestly. No static table: prices rot.
 import fs from 'node:fs';
 import path from 'node:path';
 import { tersioDataPath } from '../lib/utils.js';
 // Sonnet-class default for unpriced models; always paired with known:false.
 export const DEFAULT_PRICE = { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 };
 const LITELLM_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
-// Live cache refreshes lazily: readers use the file even when stale, and only
-// one refresh runs per process. `tersio update` still forces a fresh fetch.
+// Readers use the file even when stale, and only one refresh runs per process;
+// `tersio update` still forces a fresh fetch.
 const CACHE_TTL_MS = 7 * 24 * 3600 * 1000;
 let refreshInflight = null;
 export function pricesCachePath() {
@@ -26,8 +23,8 @@ export function pricesUrl() {
 function toPrice(t) {
     return { input: t[0], output: t[1], cacheRead: t[2], cacheWrite: t[3] };
 }
-// Tolerate both cache shapes: compact tuples (new) and ModelPrice objects
-// (written by older refreshes) — a version bump never orphans the cache.
+// Tolerate both cache shapes (compact tuples and ModelPrice objects) so a
+// version bump never orphans the cache.
 function asPrice(v) {
     if (Array.isArray(v) && v.length === 4 && v.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) {
         return toPrice(v);
@@ -35,6 +32,8 @@ function asPrice(v) {
     if (v && typeof v === 'object') {
         const o = v;
         if (['input', 'output', 'cacheRead', 'cacheWrite'].every((k) => typeof o[k] === 'number' && Number.isFinite(o[k]) && o[k] >= 0)) {
+            // SAFETY: the line above verified all four keys are finite numbers >= 0,
+            // which is the whole of ModelPrice.
             return o;
         }
     }
@@ -71,15 +70,28 @@ export function loadLivePrices() {
 function num(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
 }
+// One model, two spellings: transcripts say `space-bunny`, the feed keys it
+// `openrouter/stealth/space-bunny-alpha` at zero. Aliases fold to the first, so
+// a free stealth model never reports the default price.
+export const MODEL_ALIASES = [
+    { id: 'space-bunny', feed: 'stealth/space-bunny-alpha' },
+];
+export function canonicalPriceId(model) {
+    const key = model.toLowerCase();
+    return MODEL_ALIASES.find((a) => a.id === key || a.feed === key)?.id ?? key;
+}
 export function priceFor(model, live) {
     const table = live === undefined ? loadLivePrices() : live;
+    // An alias goes through the same exact-then-suffix chain as any other id, so
+    // it still resolves when the feed keys it under a provider prefix.
+    const id = MODEL_ALIASES.find((a) => a.id === model.toLowerCase())?.feed ?? model;
     if (table) {
-        const hit = asPrice(table.exact[model] ?? table.exact[model.toLowerCase()]);
+        const hit = asPrice(table.exact[id] ?? table.exact[id.toLowerCase()]);
         if (hit)
             return { price: hit, known: true, live: true };
         // Provider-prefixed ids ("azure/gpt-4o", "dashscope/qwen-max"): match the
         // first cached id that ends with the bare model name.
-        const name = model.toLowerCase();
+        const name = id.toLowerCase();
         const key = Object.keys(table.exact).find((k) => k.toLowerCase() === name || k.toLowerCase().endsWith(`/${name}`));
         const prefixed = key ? asPrice(table.exact[key]) : null;
         if (prefixed)
@@ -87,8 +99,7 @@ export function priceFor(model, live) {
     }
     return { price: DEFAULT_PRICE, known: false, live: false };
 }
-// Fetch LiteLLM pricing, keep every id with valid input/output rates, write
-// the cache. False on any failure (offline, timeout, shape change) — callers
+// Fetch LiteLLM pricing and write the cache. False on any failure — callers
 // fall back silently.
 export async function refreshPrices() {
     if (refreshInflight)
@@ -153,8 +164,8 @@ export async function refreshPrices() {
         refreshInflight = null;
     }
 }
-// Fire-and-forget refresh when the cache is stale or missing. Readers keep
-// using the stale file (or the built-in table) — pricing never blocks.
+// Fire-and-forget refresh when the cache is stale; readers keep the stale
+// file, so pricing never blocks.
 export function refreshPricesIfStale() {
     const live = loadLivePrices();
     if (live && Date.now() - live.fetchedAt <= CACHE_TTL_MS)

package/extensions/shared/pricing.ts

@@ -1,11 +1,7 @@
 // extensions/shared/pricing.ts — dynamic model pricing from LiteLLM.
-// Lookup order: exact id in the live cache → provider-prefix strip → default.
-// The cache is the full LiteLLM feed (3k+ ids), refreshed lazily in background
-// and on `tersio update`; every reader is sync and offline-safe. No static
-// per-model table — list prices rot, the feed does not. Unknown models report
-// the default with known:false so the dashboard labels them honestly.
+// Exact id → provider-prefix strip → default, which reports with known:false so
+// the Dashboard labels an unpriced model honestly. No static table: prices rot.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { tersioDataPath } from '../lib/utils.ts';
 
@@ -20,8 +16,8 @@ export interface ModelPrice {
 export const DEFAULT_PRICE: ModelPrice = { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 };
 
 const LITELLM_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
-// Live cache refreshes lazily: readers use the file even when stale, and only
-// one refresh runs per process. `tersio update` still forces a fresh fetch.
+// Readers use the file even when stale, and only one refresh runs per process;
+// `tersio update` still forces a fresh fetch.
 const CACHE_TTL_MS = 7 * 24 * 3600 * 1000;
 let refreshInflight: Promise<boolean> | null = null;
 
@@ -47,8 +43,8 @@ function toPrice(t: [number, number, number, number]): ModelPrice {
   return { input: t[0], output: t[1], cacheRead: t[2], cacheWrite: t[3] };
 }
 
-// Tolerate both cache shapes: compact tuples (new) and ModelPrice objects
-// (written by older refreshes) — a version bump never orphans the cache.
+// Tolerate both cache shapes (compact tuples and ModelPrice objects) so a
+// version bump never orphans the cache.
 function asPrice(v: unknown): ModelPrice | null {
   if (Array.isArray(v) && v.length === 4 && v.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) {
     return toPrice(v as [number, number, number, number]);
@@ -56,6 +52,8 @@ function asPrice(v: unknown): ModelPrice | null {
   if (v && typeof v === 'object') {
     const o = v as Record<string, unknown>;
     if (['input', 'output', 'cacheRead', 'cacheWrite'].every((k) => typeof o[k] === 'number' && Number.isFinite(o[k]) && (o[k] as number) >= 0)) {
+      // SAFETY: the line above verified all four keys are finite numbers >= 0,
+      // which is the whole of ModelPrice.
       return o as unknown as ModelPrice;
     }
   }
@@ -90,22 +88,36 @@ function num(v: unknown): number | null {
   return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
 }
 
+// One model, two spellings: transcripts say `space-bunny`, the feed keys it
+// `openrouter/stealth/space-bunny-alpha` at zero. Aliases fold to the first, so
+// a free stealth model never reports the default price.
+export const MODEL_ALIASES: ReadonlyArray<{ id: string; feed: string }> = [
+  { id: 'space-bunny', feed: 'stealth/space-bunny-alpha' },
+];
+
+export function canonicalPriceId(model: string): string {
+  const key = model.toLowerCase();
+  return MODEL_ALIASES.find((a) => a.id === key || a.feed === key)?.id ?? key;
+}
+
 export function priceFor(model: string, live?: LivePrices | null): { price: ModelPrice; known: boolean; live: boolean } {
   const table = live === undefined ? loadLivePrices() : live;
+  // An alias goes through the same exact-then-suffix chain as any other id, so
+  // it still resolves when the feed keys it under a provider prefix.
+  const id = MODEL_ALIASES.find((a) => a.id === model.toLowerCase())?.feed ?? model;
   if (table) {
-    const hit = asPrice(table.exact[model] ?? table.exact[model.toLowerCase()]);
+    const hit = asPrice(table.exact[id] ?? table.exact[id.toLowerCase()]);
     if (hit) return { price: hit, known: true, live: true };
     // Provider-prefixed ids ("azure/gpt-4o", "dashscope/qwen-max"): match the
     // first cached id that ends with the bare model name.
-    const name = model.toLowerCase();
+    const name = id.toLowerCase();
     const key = Object.keys(table.exact).find((k) => k.toLowerCase() === name || k.toLowerCase().endsWith(`/${name}`));
     const prefixed = key ? asPrice(table.exact[key]) : null;
     if (prefixed) return { price: prefixed, known: true, live: true };
   }
   return { price: DEFAULT_PRICE, known: false, live: false };
 }
-// Fetch LiteLLM pricing, keep every id with valid input/output rates, write
-// the cache. False on any failure (offline, timeout, shape change) — callers
+// Fetch LiteLLM pricing and write the cache. False on any failure — callers
 // fall back silently.
 export async function refreshPrices(): Promise<boolean> {
   if (refreshInflight) return refreshInflight;
@@ -160,8 +172,8 @@ export async function refreshPrices(): Promise<boolean> {
   }
 }
 
-// Fire-and-forget refresh when the cache is stale or missing. Readers keep
-// using the stale file (or the built-in table) — pricing never blocks.
+// Fire-and-forget refresh when the cache is stale; readers keep the stale
+// file, so pricing never blocks.
 export function refreshPricesIfStale(): void {
   const live = loadLivePrices();
   if (live && Date.now() - live.fetchedAt <= CACHE_TTL_MS) return;

package/extensions/shared/rtk-gain.js

@@ -1,28 +1,18 @@
-// extensions/shared/rtk-gain.ts — measured RTK savings from its own store.
-// RTK records every invocation (input/output/saved tokens, savings %, exec
-// time) in history.db; `rtk gain` renders the same rows. We read them with
-// the sqlite3 CLI (present on macOS; best-effort elsewhere) so the dashboard
-// shows measured figures, never estimates. Missing DB/CLI → empty, no throw.
-//
-// Caveman and Ponytail have no per-command counters (instruction-following
-// isn't metered); their gains are bench-measured in BENCHMARK.md and cited
-// as static figures wherever RTK rows appear.
-//
-// Rows group by command alone, machine-wide: one row per command no matter
-// which repo ran it. Project filtering stays out — wasted column, same logic.
+// extensions/shared/rtk-gain.ts — measured RTK savings read from rtk's own
+// history.db with the sqlite3 CLI, so the dashboard shows measured figures and
+// never estimates. Missing DB or CLI returns empty. Caveman and Ponytail are
+// bench-measured in BENCHMARK.md instead: instruction-following is not metered.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 const EMPTY = { commands: 0, saved: 0, input: 0, avgPct: 0, totalMs: 0, byCommand: [] };
-// RTK stores the whole command line, and `rtk ls -d` with a long path list
-// runs to tens of KB. The table shows one clipped cell, so bound the string
-// before it crosses the sqlite3 CLI and lands in every /data.json poll.
+// The table shows one clipped cell, so bound the command before it crosses the
+// sqlite3 CLI and lands in every /data.json poll.
 const MAX_CMD_CHARS = 200;
-// The query() reader is line- and tab-delimited, and RTK stores heredocs and
-// `node -e` scripts verbatim (~67 rows here), so one logical row can arrive as
-// several lines and derail every row after it. Fold whitespace into spaces
-// first: the stored command keeps its newlines, only the read view flattens.
+// RTK stores heredocs and `node -e` scripts verbatim, so one row can arrive as
+// several lines and derail every row after it. The stored command keeps its
+// newlines; only the read view flattens.
 const CMD_ONE_LINE = `replace(replace(replace(rtk_cmd, char(10), ' '), char(13), ' '), char(9), ' ')`;
 export function rtkDbPath() {
     const override = process.env.TERSIO_RTK_DB;
@@ -49,9 +39,8 @@ export function readRtkGain(limit = 10, cutoffMs) {
     try {
         if (!fs.existsSync(rtkDbPath()))
             return EMPTY;
-        // View-level cutoff only: rows stay in rtk's own database untouched.
-        // strftime('%s') normalizes ISO-8601 timestamps to epoch seconds; rows
-        // with unparseable timestamps (0) drop out of a filtered view.
+        // View-level cutoff only: rtk's own rows stay untouched. Timestamps that do
+        // not parse land on 0 and drop out of a filtered view.
         const where = cutoffMs && cutoffMs > 0
             ? `WHERE CAST(strftime('%s', timestamp) AS INTEGER) >= ${Math.floor(cutoffMs / 1000)}`
             : '';

package/extensions/shared/rtk-gain.ts

@@ -1,15 +1,7 @@
-// extensions/shared/rtk-gain.ts — measured RTK savings from its own store.
-// RTK records every invocation (input/output/saved tokens, savings %, exec
-// time) in history.db; `rtk gain` renders the same rows. We read them with
-// the sqlite3 CLI (present on macOS; best-effort elsewhere) so the dashboard
-// shows measured figures, never estimates. Missing DB/CLI → empty, no throw.
-//
-// Caveman and Ponytail have no per-command counters (instruction-following
-// isn't metered); their gains are bench-measured in BENCHMARK.md and cited
-// as static figures wherever RTK rows appear.
-//
-// Rows group by command alone, machine-wide: one row per command no matter
-// which repo ran it. Project filtering stays out — wasted column, same logic.
+// extensions/shared/rtk-gain.ts — measured RTK savings read from rtk's own
+// history.db with the sqlite3 CLI, so the dashboard shows measured figures and
+// never estimates. Missing DB or CLI returns empty. Caveman and Ponytail are
+// bench-measured in BENCHMARK.md instead: instruction-following is not metered.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -34,15 +26,13 @@ export interface RtkGain {
 
 const EMPTY: RtkGain = { commands: 0, saved: 0, input: 0, avgPct: 0, totalMs: 0, byCommand: [] };
 
-// RTK stores the whole command line, and `rtk ls -d` with a long path list
-// runs to tens of KB. The table shows one clipped cell, so bound the string
-// before it crosses the sqlite3 CLI and lands in every /data.json poll.
+// The table shows one clipped cell, so bound the command before it crosses the
+// sqlite3 CLI and lands in every /data.json poll.
 const MAX_CMD_CHARS = 200;
 
-// The query() reader is line- and tab-delimited, and RTK stores heredocs and
-// `node -e` scripts verbatim (~67 rows here), so one logical row can arrive as
-// several lines and derail every row after it. Fold whitespace into spaces
-// first: the stored command keeps its newlines, only the read view flattens.
+// RTK stores heredocs and `node -e` scripts verbatim, so one row can arrive as
+// several lines and derail every row after it. The stored command keeps its
+// newlines; only the read view flattens.
 const CMD_ONE_LINE = `replace(replace(replace(rtk_cmd, char(10), ' '), char(13), ' '), char(9), ' ')`;
 
 export function rtkDbPath(): string {
@@ -70,9 +60,8 @@ function query(db: string, sql: string): string[][] {
 export function readRtkGain(limit = 10, cutoffMs?: number): RtkGain {
   try {
     if (!fs.existsSync(rtkDbPath())) return EMPTY;
-    // View-level cutoff only: rows stay in rtk's own database untouched.
-    // strftime('%s') normalizes ISO-8601 timestamps to epoch seconds; rows
-    // with unparseable timestamps (0) drop out of a filtered view.
+    // View-level cutoff only: rtk's own rows stay untouched. Timestamps that do
+    // not parse land on 0 and drop out of a filtered view.
     const where = cutoffMs && cutoffMs > 0
       ? `WHERE CAST(strftime('%s', timestamp) AS INTEGER) >= ${Math.floor(cutoffMs / 1000)}`
       : '';