swarmdo 1.27.0 → 1.30.0

package/v3/@swarmdo/cli/dist/src/usage/claude-pricing.js

@@ -16,11 +16,20 @@
  * Price families, matched by LONGEST normalized-id prefix so dated ids like
  * `claude-sonnet-4-6-20260115` resolve without per-snapshot entries.
  *
- * The Claude 5 tier (fable/mythos) is intentionally absent until Anthropic
- * publishes rates — absent means "unpriced", never "guessed".
+ * Opus pricing split (#41): Opus 4.0/4.1 were $15/$75, but Opus 4.5 dropped
+ * the tier to $5/$25 and 4.6/4.7/4.8 kept it. The bare 'claude-opus-4' entry
+ * stays at legacy rates for 4.0/4.1; the longer per-version prefixes win for
+ * 4.5+ via longest-prefix matching.
  */
 const PRICE_FAMILIES = {
+    'claude-fable-5': { in: 10, out: 50, cacheWrite: 12.5, cacheWrite1h: 20, cacheRead: 1 },
+    'claude-mythos-5': { in: 10, out: 50, cacheWrite: 12.5, cacheWrite1h: 20, cacheRead: 1 },
     'claude-opus-4': { in: 15, out: 75, cacheWrite: 18.75, cacheWrite1h: 30, cacheRead: 1.5 },
+    'claude-opus-4-5': { in: 5, out: 25, cacheWrite: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+    'claude-opus-4-6': { in: 5, out: 25, cacheWrite: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+    'claude-opus-4-7': { in: 5, out: 25, cacheWrite: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+    'claude-opus-4-8': { in: 5, out: 25, cacheWrite: 6.25, cacheWrite1h: 10, cacheRead: 0.5 },
+    'claude-sonnet-5': { in: 3, out: 15, cacheWrite: 3.75, cacheWrite1h: 6, cacheRead: 0.3 },
     'claude-sonnet-4': { in: 3, out: 15, cacheWrite: 3.75, cacheWrite1h: 6, cacheRead: 0.3 },
     'claude-haiku-4': { in: 1, out: 5, cacheWrite: 1.25, cacheWrite1h: 2, cacheRead: 0.1 },
     'claude-3-7-sonnet': { in: 3, out: 15, cacheWrite: 3.75, cacheWrite1h: 6, cacheRead: 0.3 },
@@ -29,6 +38,15 @@ const PRICE_FAMILIES = {
     'claude-3-opus': { in: 15, out: 75, cacheWrite: 18.75, cacheWrite1h: 30, cacheRead: 1.5 },
     'claude-3-haiku': { in: 0.25, out: 1.25, cacheWrite: 0.3, cacheWrite1h: 0.5, cacheRead: 0.03 },
 };
+const PROMOS = [
+    {
+        // Sonnet 5 introductory pricing: $2/$10 per Mtok through 2026-08-31.
+        prefix: 'claude-sonnet-5',
+        fromMs: Date.UTC(2026, 5, 30), // launched 2026-06-30
+        untilMs: Date.UTC(2026, 7, 31, 23, 59, 59, 999),
+        price: { in: 2, out: 10, cacheWrite: 2.5, cacheWrite1h: 4, cacheRead: 0.2 },
+    },
+];
 /**
  * Reduce a transcript/gateway model id to the bare Anthropic id:
  *   'anthropic/claude-opus-4-8'            → 'claude-opus-4-8'
@@ -47,9 +65,20 @@ export function normalizeTranscriptModelId(raw) {
     id = id.replace(/-v\d+$/, ''); // Bedrock '-v2'
     return id;
 }
-/** Longest-prefix price lookup; undefined = unpriced (report it, don't guess). */
-export function resolveTranscriptPrice(rawModelId) {
+/**
+ * Longest-prefix price lookup; undefined = unpriced (report it, don't guess).
+ * Pass the transcript entry's timestamp as `atMs` to get date-ranged promo
+ * rates (e.g. Sonnet 5 intro pricing); omitted → sticker price.
+ */
+export function resolveTranscriptPrice(rawModelId, atMs) {
     const id = normalizeTranscriptModelId(rawModelId);
+    if (atMs !== undefined) {
+        for (const promo of PROMOS) {
+            if (id.startsWith(promo.prefix) && atMs >= promo.fromMs && atMs <= promo.untilMs) {
+                return promo.price;
+            }
+        }
+    }
     let best;
     let bestLen = 0;
     for (const [prefix, price] of Object.entries(PRICE_FAMILIES)) {

package/v3/@swarmdo/cli/dist/src/usage/limits.d.ts

@@ -0,0 +1,77 @@
+/**
+ * limits.ts — forecast when a Claude Code usage window will hit its cap.
+ *
+ * Claude Code passes an official `rate_limits` payload to statusline scripts:
+ * for the rolling 5-hour and 7-day windows it reports `used_percentage` and
+ * `resets_at`. This is the projection layer on top — at the current burn rate,
+ * when will the window hit 100%, and does that land before the window resets?
+ * ("at this pace you hit the weekly cap Thu 14:00, 6h before it resets").
+ *
+ * Pure + deterministic: it takes a normalized window state + an injected `now`
+ * (the statusline shim maps the raw payload to WindowState — see #46), so the
+ * projection math is unit-tested with zero clock or wire-format coupling.
+ */
+export type LimitStatus = 'ok' | 'warn' | 'over';
+/** Rolling-window durations Claude Code reports (5-hour + 7-day caps). */
+export declare const FIVE_HOUR_MS: number;
+export declare const SEVEN_DAY_MS: number;
+export interface NamedWindow {
+    /** short label, '5h' | '7d' */
+    label: string;
+    state: WindowState;
+}
+/**
+ * Map Claude Code's statusline `rate_limits` payload to normalized windows.
+ * Tolerant of shape drift: accepts the payload bare or wrapped in `rate_limits`,
+ * snake_case or camelCase keys, and epoch-seconds / epoch-ms / ISO `resets_at`.
+ * Windows missing usage or a reset time are dropped. Pure.
+ */
+export declare function parseRateLimits(payload: unknown): NamedWindow[];
+export interface WindowState {
+    /** percent of the window's quota consumed, 0..100 */
+    usedPercentage: number;
+    /** window duration in ms (5h = 18_000_000, 7d = 604_800_000) */
+    windowMs: number;
+    /** epoch ms when the window resets to 0% */
+    resetsAtMs: number;
+}
+export interface LimitForecast {
+    usedPercentage: number;
+    resetsAtMs: number;
+    /** ms from now until the window resets (never negative) */
+    msToReset: number;
+    /** projected epoch ms when usage reaches 100% at the current burn rate, or
+     *  null when it can't be projected (no burn yet, already at/over 100%, or the
+     *  window hasn't started per the clock) */
+    exhaustionMs: number | null;
+    /** true when exhaustion is projected at or before the window resets */
+    willExhaust: boolean;
+    status: LimitStatus;
+}
+/**
+ * Forecast a single window. Burn rate is `usedPercentage / elapsed`, where
+ * elapsed = now − windowStart and windowStart = resetsAt − windowMs. Pure.
+ */
+export declare function forecastWindow(w: WindowState, nowMs: number, opts?: {
+    warnPct?: number;
+}): LimitForecast;
+/** Worst status across windows (over > warn > ok). Pure. */
+export declare function worstStatus(forecasts: LimitForecast[]): LimitStatus;
+/**
+ * The binding window — the one that constrains you first. A window projected to
+ * exhaust before reset outranks one that won't; among those that will, the
+ * earlier exhaustion wins; otherwise the higher used_percentage. null for [].
+ */
+export declare function bindingWindow(forecasts: LimitForecast[]): LimitForecast | null;
+/** Compact human duration for a ms span, e.g. 9000000 → "2h30m", 90000 → "1m". */
+export declare function humanizeMs(ms: number): string;
+/** Ultra-compact one-line indicator for a statusline, e.g. "5h 72%⚠ · 7d 12%".
+ * `!` marks an over-cap window, `⚠` an at-risk one. Pure. */
+export declare function formatLimitSegment(forecasts: Array<{
+    label: string;
+    f: LimitForecast;
+}>): string;
+/** One-line summary for a window, e.g. "5h window: 42% used, resets in 2h14m —
+ * on pace to hit the cap in ~1h20m (before reset)". `label` names the window. */
+export declare function formatForecast(label: string, f: LimitForecast, nowMs: number): string;
+//# sourceMappingURL=limits.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/limits.js

@@ -0,0 +1,134 @@
+/**
+ * limits.ts — forecast when a Claude Code usage window will hit its cap.
+ *
+ * Claude Code passes an official `rate_limits` payload to statusline scripts:
+ * for the rolling 5-hour and 7-day windows it reports `used_percentage` and
+ * `resets_at`. This is the projection layer on top — at the current burn rate,
+ * when will the window hit 100%, and does that land before the window resets?
+ * ("at this pace you hit the weekly cap Thu 14:00, 6h before it resets").
+ *
+ * Pure + deterministic: it takes a normalized window state + an injected `now`
+ * (the statusline shim maps the raw payload to WindowState — see #46), so the
+ * projection math is unit-tested with zero clock or wire-format coupling.
+ */
+/** Rolling-window durations Claude Code reports (5-hour + 7-day caps). */
+export const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+export const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+/** Coerce an epoch-seconds, epoch-ms, or ISO-string timestamp to epoch ms. */
+function toEpochMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v < 1e12 ? v * 1000 : v; // secs vs ms
+    if (typeof v === 'string') {
+        const t = Date.parse(v);
+        return Number.isNaN(t) ? null : t;
+    }
+    return null;
+}
+function pickWindow(obj, windowMs, label) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const o = obj;
+    const used = (o.used_percentage ?? o.usedPercentage);
+    const resetsAtMs = toEpochMs(o.resets_at ?? o.resetsAt);
+    if (typeof used !== 'number' || !Number.isFinite(used) || resetsAtMs === null)
+        return null;
+    return { label, state: { usedPercentage: Math.max(0, Math.min(100, used)), windowMs, resetsAtMs } };
+}
+/**
+ * Map Claude Code's statusline `rate_limits` payload to normalized windows.
+ * Tolerant of shape drift: accepts the payload bare or wrapped in `rate_limits`,
+ * snake_case or camelCase keys, and epoch-seconds / epoch-ms / ISO `resets_at`.
+ * Windows missing usage or a reset time are dropped. Pure.
+ */
+export function parseRateLimits(payload) {
+    const p = payload && typeof payload === 'object' ? payload : {};
+    const rl = (p.rate_limits ?? p.rateLimits ?? p);
+    const out = [];
+    const w5 = pickWindow(rl.five_hour ?? rl.fiveHour, FIVE_HOUR_MS, '5h');
+    const w7 = pickWindow(rl.seven_day ?? rl.sevenDay, SEVEN_DAY_MS, '7d');
+    if (w5)
+        out.push(w5);
+    if (w7)
+        out.push(w7);
+    return out;
+}
+/**
+ * Forecast a single window. Burn rate is `usedPercentage / elapsed`, where
+ * elapsed = now − windowStart and windowStart = resetsAt − windowMs. Pure.
+ */
+export function forecastWindow(w, nowMs, opts = {}) {
+    const warnPct = opts.warnPct ?? 80;
+    const used = w.usedPercentage;
+    const msToReset = Math.max(0, w.resetsAtMs - nowMs);
+    const windowStartMs = w.resetsAtMs - w.windowMs;
+    const elapsed = nowMs - windowStartMs;
+    let exhaustionMs = null;
+    if (used >= 100) {
+        // already exhausted — mark exhaustion as "now"
+        exhaustionMs = nowMs;
+    }
+    else if (used > 0 && elapsed > 0) {
+        const msTo100 = ((100 - used) * elapsed) / used; // (remaining%) / (used%/elapsed)
+        exhaustionMs = nowMs + msTo100;
+    }
+    const willExhaust = exhaustionMs !== null && exhaustionMs <= w.resetsAtMs;
+    const status = used >= 100 ? 'over' : (willExhaust || used >= warnPct) ? 'warn' : 'ok';
+    return { usedPercentage: used, resetsAtMs: w.resetsAtMs, msToReset, exhaustionMs, willExhaust, status };
+}
+/** Worst status across windows (over > warn > ok). Pure. */
+export function worstStatus(forecasts) {
+    const rank = { ok: 0, warn: 1, over: 2 };
+    return forecasts.reduce((acc, f) => (rank[f.status] > rank[acc] ? f.status : acc), 'ok');
+}
+/**
+ * The binding window — the one that constrains you first. A window projected to
+ * exhaust before reset outranks one that won't; among those that will, the
+ * earlier exhaustion wins; otherwise the higher used_percentage. null for [].
+ */
+export function bindingWindow(forecasts) {
+    if (forecasts.length === 0)
+        return null;
+    return [...forecasts].sort((a, b) => {
+        if (a.willExhaust !== b.willExhaust)
+            return a.willExhaust ? -1 : 1;
+        if (a.willExhaust && b.willExhaust)
+            return a.exhaustionMs - b.exhaustionMs;
+        return b.usedPercentage - a.usedPercentage;
+    })[0];
+}
+/** Compact human duration for a ms span, e.g. 9000000 → "2h30m", 90000 → "1m". */
+export function humanizeMs(ms) {
+    if (ms <= 0)
+        return '0m';
+    const totalMin = Math.floor(ms / 60_000);
+    const d = Math.floor(totalMin / 1440);
+    const h = Math.floor((totalMin % 1440) / 60);
+    const m = totalMin % 60;
+    if (d > 0)
+        return `${d}d${h > 0 ? `${h}h` : ''}`;
+    if (h > 0)
+        return `${h}h${m > 0 ? `${m}m` : ''}`;
+    return `${m}m`;
+}
+/** Ultra-compact one-line indicator for a statusline, e.g. "5h 72%⚠ · 7d 12%".
+ * `!` marks an over-cap window, `⚠` an at-risk one. Pure. */
+export function formatLimitSegment(forecasts) {
+    if (forecasts.length === 0)
+        return 'limits: n/a';
+    const mark = (s) => (s === 'over' ? '!' : s === 'warn' ? '⚠' : '');
+    return forecasts.map(({ label, f }) => `${label} ${Math.round(f.usedPercentage)}%${mark(f.status)}`).join(' · ');
+}
+/** One-line summary for a window, e.g. "5h window: 42% used, resets in 2h14m —
+ * on pace to hit the cap in ~1h20m (before reset)". `label` names the window. */
+export function formatForecast(label, f, nowMs) {
+    const head = `${label}: ${Math.round(f.usedPercentage)}% used, resets in ${humanizeMs(f.msToReset)}`;
+    if (f.status === 'over')
+        return `${head} — CAP REACHED`;
+    if (f.willExhaust && f.exhaustionMs !== null) {
+        const inMs = Math.max(0, f.exhaustionMs - nowMs);
+        const before = humanizeMs(f.resetsAtMs - f.exhaustionMs);
+        return `${head} — on pace to hit the cap in ~${humanizeMs(inMs)} (${before} before reset)`;
+    }
+    return `${head} — on pace to stay under the cap`;
+}
+//# sourceMappingURL=limits.js.map

package/v3/@swarmdo/cli/dist/src/usage/reflect-html.d.ts

@@ -0,0 +1,23 @@
+/**
+ * reflect-html.ts — render a Reflection (see reflect.ts) into a self-contained,
+ * shareable HTML dashboard for `swarmdo usage reflect --html`.
+ *
+ * Pure + deterministic: it takes an already-computed Reflection and returns a
+ * complete HTML document string with all CSS inlined (no external requests, no
+ * clock — any timestamp is passed in), so it unit-tests without a browser or a
+ * network. Every user-controlled string (model ids, project paths) is HTML-
+ * escaped. See #47.
+ */
+import type { Reflection } from './reflect.js';
+/** HTML-escape a string for safe interpolation into text or attributes. */
+export declare function escapeHtml(s: string): string;
+/** Render the retrospective to a complete self-contained HTML document. Pure. */
+export declare function renderReflectionHtml(r: Reflection, opts?: {
+    generatedAt?: string;
+    delegation?: {
+        taskCalls: number;
+        toolCalls: number;
+        ratio: number;
+    };
+}): string;
+//# sourceMappingURL=reflect-html.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/reflect-html.js

@@ -0,0 +1,94 @@
+/**
+ * reflect-html.ts — render a Reflection (see reflect.ts) into a self-contained,
+ * shareable HTML dashboard for `swarmdo usage reflect --html`.
+ *
+ * Pure + deterministic: it takes an already-computed Reflection and returns a
+ * complete HTML document string with all CSS inlined (no external requests, no
+ * clock — any timestamp is passed in), so it unit-tests without a browser or a
+ * network. Every user-controlled string (model ids, project paths) is HTML-
+ * escaped. See #47.
+ */
+/** HTML-escape a string for safe interpolation into text or attributes. */
+export function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+const num = (n) => n.toLocaleString('en-US');
+const pct = (x) => `${Math.round(x * 100)}%`;
+/** A labelled proportional bar (width is % of the largest value in its group). */
+function bar(label, valueText, fillPct) {
+    const w = Math.max(0, Math.min(100, fillPct));
+    return `<div class="bar"><div class="bar-label" title="${escapeHtml(label)}">${escapeHtml(label)}</div>`
+        + `<div class="bar-track"><div class="bar-fill" style="width:${w.toFixed(1)}%"></div></div>`
+        + `<div class="bar-val">${escapeHtml(valueText)}</div></div>`;
+}
+function shareBars(rows) {
+    if (!rows.length)
+        return '<p class="empty">—</p>';
+    const max = Math.max(...rows.map((r) => r.costUsd), 0) || 1;
+    return rows.map((r) => bar(r.model, `${usd(r.costUsd)} · ${pct(r.pct)}`, (r.costUsd / max) * 100)).join('');
+}
+function hourBars(hist) {
+    if (!hist.some((v) => v > 0))
+        return '<p class="empty">—</p>';
+    const max = Math.max(...hist) || 1;
+    const cells = hist.map((v, h) => {
+        const hpct = (v / max) * 100;
+        return `<div class="hour" title="${String(h).padStart(2, '0')}:00 — ${usd(v)}">`
+            + `<div class="hour-bar" style="height:${hpct.toFixed(1)}%"></div>`
+            + `<div class="hour-tick">${h % 6 === 0 ? String(h).padStart(2, '0') : ''}</div></div>`;
+    }).join('');
+    return `<div class="hours">${cells}</div>`;
+}
+function stat(label, value) {
+    return `<div class="stat"><div class="stat-val">${escapeHtml(value)}</div><div class="stat-label">${escapeHtml(label)}</div></div>`;
+}
+/** Render the retrospective to a complete self-contained HTML document. Pure. */
+export function renderReflectionHtml(r, opts = {}) {
+    const arrow = r.trend.direction === 'up' ? '↑' : r.trend.direction === 'down' ? '↓' : '→';
+    const peak = r.peakHour ? `${String(r.peakHour.hour).padStart(2, '0')}:00` : '—';
+    const busiest = r.busiestDay ? `${r.busiestDay.day} (${usd(r.busiestDay.costUsd)})` : '—';
+    const gen = opts.generatedAt ? `<p class="gen">generated ${escapeHtml(opts.generatedAt)}</p>` : '';
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Claude Code Reflect — ${escapeHtml(r.period.from)}..${escapeHtml(r.period.to)}</title>
+<style>
+:root{--bg:#0f1117;--card:#181b24;--fg:#e6e8ee;--muted:#8b90a0;--accent:#7c9cff;--track:#262a36}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;padding:32px}
+.wrap{max-width:840px;margin:0 auto}
+h1{font-size:22px;margin:0 0 2px}.sub{color:var(--muted);margin:0 0 24px}.gen{color:var(--muted);font-size:12px;margin:24px 0 0}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin-bottom:28px}
+.stat{background:var(--card);border-radius:12px;padding:16px}
+.stat-val{font-size:22px;font-weight:600}.stat-label{color:var(--muted);font-size:12px;margin-top:4px}
+h2{font-size:14px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted);margin:28px 0 12px}
+.bar{display:grid;grid-template-columns:minmax(0,1fr) 3fr minmax(0,auto);align-items:center;gap:10px;margin:6px 0}
+.bar-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:13px}
+.bar-track{background:var(--track);border-radius:6px;height:14px;overflow:hidden}
+.bar-fill{background:var(--accent);height:100%;border-radius:6px}
+.bar-val{font-size:12px;color:var(--muted);white-space:nowrap}
+.hours{display:flex;align-items:flex-end;gap:3px;height:90px}
+.hour{flex:1;display:flex;flex-direction:column;justify-content:flex-end;align-items:center;height:100%}
+.hour-bar{width:100%;background:var(--accent);border-radius:3px 3px 0 0;min-height:1px}
+.hour-tick{font-size:9px;color:var(--muted);margin-top:4px;height:12px}
+.empty{color:var(--muted)}
+</style></head><body><div class="wrap">
+<h1>Claude Code Reflect ${escapeHtml(arrow)}</h1>
+<p class="sub">${escapeHtml(r.period.from)} .. ${escapeHtml(r.period.to)} · ${r.period.spanDays} days · ${r.totals.activeDays} active</p>
+<div class="grid">
+${stat('Total spend', usd(r.totals.costUsd))}
+${stat('Total tokens', num(r.totals.totalTokens))}
+${stat('Avg / active day', usd(r.avgCostPerActiveDay))}
+${stat('Longest streak', `${r.longestStreak} day${r.longestStreak === 1 ? '' : 's'}`)}
+${stat('Peak hour', peak)}
+${stat('Cache read', pct(r.cacheReadPct))}
+${stat('Busiest day', busiest)}
+${stat('Trend', `${arrow} ${pct(r.trend.firstHalfCost > 0 ? (r.trend.secondHalfCost - r.trend.firstHalfCost) / r.trend.firstHalfCost : 0)}`)}
+${opts.delegation && opts.delegation.toolCalls > 0 ? stat('Delegation', pct(opts.delegation.ratio)) : ''}
+</div>
+<h2>Cost by hour of day</h2>${hourBars(r.hourHistogram)}
+<h2>Top models</h2>${shareBars(r.topModels)}
+<h2>Top projects</h2>${shareBars(r.topProjects)}
+${gen}
+</div></body></html>`;
+}
+//# sourceMappingURL=reflect-html.js.map

package/v3/@swarmdo/cli/dist/src/usage/reflect.d.ts

@@ -0,0 +1,105 @@
+/**
+ * reflect.ts — a "wrapped"-style retrospective over Claude Code usage.
+ *
+ * Anthropic's Reflect (2026-07-09) summarizes claude.ai *chats*; it doesn't
+ * touch Claude Code terminal work. swarmdo already parses the local transcripts
+ * for `usage daily/monthly/blocks/errors/cache`, so this is the retrospective
+ * layer on top: fold the existing per-day and per-(model,day) aggregation rows
+ * into headline stats — totals, the busiest day, the top models, the longest
+ * active-day streak, the cost trend, and cache efficiency.
+ *
+ * Pure + deterministic: it takes already-aggregated rows (no transcripts, no
+ * clock — the period bounds are passed in), so the whole thing is unit-tested
+ * without touching disk. The command layer in ../commands/usage.ts feeds it the
+ * rows the parser already produces. See #47.
+ */
+import type { DayRow, ModelRow } from './diff.js';
+export interface ModelShare {
+    model: string;
+    costUsd: number;
+    totalTokens: number;
+    /** share of total cost, 0..1 (0 when the period cost is 0) */
+    pct: number;
+}
+export interface ReflectionTotals {
+    costUsd: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    entries: number;
+    /** days in [from,to] with any token activity */
+    activeDays: number;
+}
+export interface Reflection {
+    period: {
+        from: string;
+        to: string; /** inclusive calendar span in days */
+        spanDays: number;
+    };
+    totals: ReflectionTotals;
+    /** highest-cost active day in the period, or null if the period is empty */
+    busiestDay: {
+        day: string;
+        costUsd: number;
+        totalTokens: number;
+    } | null;
+    /** models ranked by cost desc (capped to opts.topModels) */
+    topModels: ModelShare[];
+    /** projects ranked by cost desc (ModelShare.model holds the project path) */
+    topProjects: ModelShare[];
+    /** busiest local hour-of-day by cost (0..23), or null if no activity */
+    peakHour: {
+        hour: number;
+        value: number;
+    } | null;
+    /** cost per local hour-of-day, as supplied by the caller (length 24 when set) */
+    hourHistogram: number[];
+    /** longest run of consecutive active calendar days */
+    longestStreak: number;
+    /** cacheRead / (input + cacheWrite + cacheRead), 0..1 */
+    cacheReadPct: number;
+    /** total cost / active days (0 when no active days) */
+    avgCostPerActiveDay: number;
+    /** first-half vs second-half spend across the period */
+    trend: {
+        firstHalfCost: number;
+        secondHalfCost: number;
+        direction: 'up' | 'down' | 'flat';
+    };
+}
+export interface ReflectOptions {
+    /** how many models to keep in topModels (default 5) */
+    topModels?: number;
+    /** relative change below which the trend reads 'flat' (default 0.05 = 5%) */
+    flatThreshold?: number;
+}
+/** The calendar day after an ISO date (handles month/year rollover). Pure. */
+export declare function nextDay(iso: string): string;
+/**
+ * The ISO date `n` whole months before `iso`, clamping the day to the target
+ * month's length so "Mar 31 − 1 month" is Feb 28/29 (not a rolled-over Mar 3).
+ * Pure. Used to derive a `--period 1m|3m|…` window start from today.
+ */
+export declare function monthsBefore(iso: string, n: number): string;
+/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+export declare function spanDays(from: string, to: string): number;
+/** Longest run of consecutive calendar days present in the set. Pure. */
+export declare function longestStreakOf(days: string[]): number;
+/** Render a numeric series as a Unicode block sparkline (one char per bucket).
+ * Zero buckets are blank; the rest scale ▁..█ against the max. Pure — used for
+ * the terminal cost-by-hour view (the HTML dashboard draws the same data). */
+export declare function hourSparkline(hist: number[]): string;
+/** Window + aggregate `{key, day, totals}` rows into cost-ranked shares. Pure.
+ * Reused for both models and projects (ModelShare.model carries whichever key). */
+export declare function rankShares(rows: ModelRow[], from: string, to: string, totalCost: number, topN: number): ModelShare[];
+/** Busiest bucket in a per-hour cost histogram (argmax; earliest hour wins ties),
+ * or null when every bucket is empty. Pure. */
+export declare function peakHourOf(hourHistogram: number[]): {
+    hour: number;
+    value: number;
+} | null;
+/** Fold pre-aggregated usage rows into a retrospective. Pure. */
+export declare function computeReflection(dayRows: DayRow[], modelRows: ModelRow[], from: string, to: string, opts?: ReflectOptions, projectRows?: ModelRow[], hourHistogram?: number[]): Reflection;
+//# sourceMappingURL=reflect.d.ts.map

package/v3/@swarmdo/cli/dist/src/usage/reflect.js

@@ -0,0 +1,165 @@
+/**
+ * reflect.ts — a "wrapped"-style retrospective over Claude Code usage.
+ *
+ * Anthropic's Reflect (2026-07-09) summarizes claude.ai *chats*; it doesn't
+ * touch Claude Code terminal work. swarmdo already parses the local transcripts
+ * for `usage daily/monthly/blocks/errors/cache`, so this is the retrospective
+ * layer on top: fold the existing per-day and per-(model,day) aggregation rows
+ * into headline stats — totals, the busiest day, the top models, the longest
+ * active-day streak, the cost trend, and cache efficiency.
+ *
+ * Pure + deterministic: it takes already-aggregated rows (no transcripts, no
+ * clock — the period bounds are passed in), so the whole thing is unit-tested
+ * without touching disk. The command layer in ../commands/usage.ts feeds it the
+ * rows the parser already produces. See #47.
+ */
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** The calendar day after an ISO date (handles month/year rollover). Pure. */
+export function nextDay(iso) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const dt = new Date(y, m - 1, d + 1);
+    const yy = dt.getFullYear();
+    const mm = String(dt.getMonth() + 1).padStart(2, '0');
+    const dd = String(dt.getDate()).padStart(2, '0');
+    return `${yy}-${mm}-${dd}`;
+}
+/**
+ * The ISO date `n` whole months before `iso`, clamping the day to the target
+ * month's length so "Mar 31 − 1 month" is Feb 28/29 (not a rolled-over Mar 3).
+ * Pure. Used to derive a `--period 1m|3m|…` window start from today.
+ */
+export function monthsBefore(iso, n) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const monthIndex = m - 1 - n; // may be negative — Date normalizes the year
+    const lastDay = new Date(y, monthIndex + 1, 0).getDate();
+    const dt = new Date(y, monthIndex, Math.min(d, lastDay));
+    const yy = dt.getFullYear();
+    const mm = String(dt.getMonth() + 1).padStart(2, '0');
+    const dd = String(dt.getDate()).padStart(2, '0');
+    return `${yy}-${mm}-${dd}`;
+}
+/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+export function spanDays(from, to) {
+    const a = new Date(from + 'T00:00:00');
+    const b = new Date(to + 'T00:00:00');
+    return Math.floor((b.getTime() - a.getTime()) / 86_400_000) + 1;
+}
+/** Longest run of consecutive calendar days present in the set. Pure. */
+export function longestStreakOf(days) {
+    const uniq = [...new Set(days)].sort();
+    let best = 0;
+    let run = 0;
+    let prev = null;
+    for (const d of uniq) {
+        run = prev !== null && nextDay(prev) === d ? run + 1 : 1;
+        if (run > best)
+            best = run;
+        prev = d;
+    }
+    return best;
+}
+const within = (key, from, to) => key >= from && key <= to;
+const SPARK_BLOCKS = ' ▁▂▃▄▅▆▇█'; // index 0 = empty (zero), 1..8 = ▁..█ scaled to max
+/** Render a numeric series as a Unicode block sparkline (one char per bucket).
+ * Zero buckets are blank; the rest scale ▁..█ against the max. Pure — used for
+ * the terminal cost-by-hour view (the HTML dashboard draws the same data). */
+export function hourSparkline(hist) {
+    const max = Math.max(0, ...hist);
+    if (max <= 0)
+        return ' '.repeat(hist.length);
+    return hist.map((v) => SPARK_BLOCKS[v <= 0 ? 0 : Math.min(8, 1 + Math.floor((v / max) * 7))]).join('');
+}
+/** Window + aggregate `{key, day, totals}` rows into cost-ranked shares. Pure.
+ * Reused for both models and projects (ModelShare.model carries whichever key). */
+export function rankShares(rows, from, to, totalCost, topN) {
+    const per = new Map();
+    for (const r of rows) {
+        if (!within(r.day, from, to))
+            continue;
+        const slot = per.get(r.key) ?? { costUsd: 0, totalTokens: 0 };
+        slot.costUsd += r.totals.costUsd;
+        slot.totalTokens += r.totals.totalTokens;
+        per.set(r.key, slot);
+    }
+    return [...per.entries()]
+        .map(([key, v]) => ({ model: key, costUsd: v.costUsd, totalTokens: v.totalTokens, pct: totalCost > 0 ? v.costUsd / totalCost : 0 }))
+        .filter((m) => m.costUsd > 0 || m.totalTokens > 0)
+        .sort((a, b) => b.costUsd - a.costUsd || b.totalTokens - a.totalTokens || (a.model < b.model ? -1 : 1))
+        .slice(0, topN);
+}
+/** Busiest bucket in a per-hour cost histogram (argmax; earliest hour wins ties),
+ * or null when every bucket is empty. Pure. */
+export function peakHourOf(hourHistogram) {
+    let best = -1;
+    let bestVal = 0;
+    for (let h = 0; h < hourHistogram.length; h++) {
+        if (hourHistogram[h] > bestVal) {
+            bestVal = hourHistogram[h];
+            best = h;
+        }
+    }
+    return best < 0 ? null : { hour: best, value: bestVal };
+}
+/** Fold pre-aggregated usage rows into a retrospective. Pure. */
+export function computeReflection(dayRows, modelRows, from, to, opts = {}, projectRows = [], hourHistogram = []) {
+    if (!DATE.test(from) || !DATE.test(to))
+        throw new Error(`bad period bounds: ${from}..${to}`);
+    if (from > to)
+        throw new Error(`period "${from}..${to}" is reversed (from > to)`);
+    const topN = opts.topModels ?? 5;
+    const flat = opts.flatThreshold ?? 0.05;
+    const days = dayRows.filter((r) => within(r.key, from, to));
+    const totals = {
+        costUsd: 0, totalTokens: 0, inputTokens: 0, outputTokens: 0,
+        cacheReadTokens: 0, cacheWriteTokens: 0, entries: 0, activeDays: 0,
+    };
+    let busiestDay = null;
+    const activeDayKeys = [];
+    const mid = spanDays(from, to) / 2;
+    let firstHalfCost = 0;
+    let secondHalfCost = 0;
+    for (const r of days) {
+        const t = r.totals;
+        totals.costUsd += t.costUsd;
+        totals.totalTokens += t.totalTokens;
+        totals.inputTokens += t.inputTokens;
+        totals.outputTokens += t.outputTokens;
+        totals.cacheReadTokens += t.cacheReadTokens;
+        totals.cacheWriteTokens += t.cacheWriteTokens;
+        if (t.totalTokens > 0) {
+            totals.activeDays += 1;
+            activeDayKeys.push(r.key);
+        }
+        if (!busiestDay || t.costUsd > busiestDay.costUsd) {
+            busiestDay = { day: r.key, costUsd: t.costUsd, totalTokens: t.totalTokens };
+        }
+        // Trend: which half of the period does this day fall in?
+        if (spanDays(from, r.key) <= mid)
+            firstHalfCost += t.costUsd;
+        else
+            secondHalfCost += t.costUsd;
+    }
+    // A period with zero active days has no meaningful busiest day.
+    if (totals.activeDays === 0)
+        busiestDay = null;
+    // Cost-ranked shares over the same window, for both models and projects.
+    const topModels = rankShares(modelRows, from, to, totals.costUsd, topN);
+    const topProjects = rankShares(projectRows, from, to, totals.costUsd, topN);
+    const inputSide = totals.inputTokens + totals.cacheWriteTokens + totals.cacheReadTokens;
+    const relChange = firstHalfCost > 0 ? (secondHalfCost - firstHalfCost) / firstHalfCost : (secondHalfCost > 0 ? 1 : 0);
+    const direction = Math.abs(relChange) < flat ? 'flat' : relChange > 0 ? 'up' : 'down';
+    return {
+        period: { from, to, spanDays: spanDays(from, to) },
+        totals,
+        busiestDay,
+        topModels,
+        topProjects,
+        peakHour: peakHourOf(hourHistogram),
+        hourHistogram,
+        longestStreak: longestStreakOf(activeDayKeys),
+        cacheReadPct: inputSide > 0 ? totals.cacheReadTokens / inputSide : 0,
+        avgCostPerActiveDay: totals.activeDays > 0 ? totals.costUsd / totals.activeDays : 0,
+        trend: { firstHalfCost, secondHalfCost, direction },
+    };
+}
+//# sourceMappingURL=reflect.js.map