swarmdo 1.30.0 → 1.45.0

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

@@ -14,6 +14,7 @@
  * rows the parser already produces. See #47.
  */
 import type { DayRow, ModelRow } from './diff.js';
+import { type TranscriptModelPrice } from './claude-pricing.js';
 export interface ModelShare {
     model: string;
     costUsd: number;
@@ -45,6 +46,8 @@ export interface Reflection {
         costUsd: number;
         totalTokens: number;
     } | null;
+    /** active days whose cost is an outlier vs the median (possible runaways) */
+    spikeDays: SpikeDay[];
     /** models ranked by cost desc (capped to opts.topModels) */
     topModels: ModelShare[];
     /** projects ranked by cost desc (ModelShare.model holds the project path) */
@@ -68,12 +71,16 @@ export interface Reflection {
         secondHalfCost: number;
         direction: 'up' | 'down' | 'flat';
     };
+    /** $ prompt-caching saved this period (vs paying full input rate); 0 if no priced models */
+    cacheSavingsUsd: number;
 }
 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;
+    /** price resolver for cache-savings (injected for tests; default = the real table) */
+    resolvePrice?: (model: string) => TranscriptModelPrice | undefined;
 }
 /** The calendar day after an ISO date (handles month/year rollover). Pure. */
 export declare function nextDay(iso: string): string;
@@ -83,10 +90,37 @@ export declare function nextDay(iso: string): string;
  * 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. */
+/**
+ * Inclusive whole-day span between two ISO dates (from <= to). Pure.
+ *
+ * Counts on the UTC timeline (`Date.UTC`), NOT local midnights: a local
+ * `new Date('…T00:00:00')` is DST-sensitive, so a range crossing a spring-forward
+ * day (only 23h long) would floor-divide to one day short — e.g. under
+ * TZ=America/New_York a full March would read 30. UTC calendar midnights are
+ * always an exact 86.4M ms apart, so this is correct in every process timezone.
+ */
 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;
+export interface SpikeDay {
+    day: string;
+    costUsd: number;
+    /** costUsd / median active-day cost */
+    ratioToMedian: number;
+}
+/**
+ * Days whose cost is an outlier vs the median active-day cost — a heads-up for
+ * runaway sessions. Median (not mean) so the spikes don't inflate the baseline.
+ * Needs ≥3 active days for a meaningful median; a floor keeps trivially-cheap
+ * days from tripping the ratio. Sorted by cost desc. Pure.
+ */
+export declare function detectSpikeDays(days: Array<{
+    day: string;
+    costUsd: number;
+}>, opts?: {
+    minRatio?: number;
+    minCostUsd?: number;
+}): SpikeDay[];
 /** 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). */

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

@@ -13,6 +13,8 @@
  * without touching disk. The command layer in ../commands/usage.ts feeds it the
  * rows the parser already produces. See #47.
  */
+import { modelCacheSavings } from './cache-stats.js';
+import { resolveTranscriptPrice } from './claude-pricing.js';
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 /** The calendar day after an ISO date (handles month/year rollover). Pure. */
 export function nextDay(iso) {
@@ -38,11 +40,21 @@ export function monthsBefore(iso, n) {
     const dd = String(dt.getDate()).padStart(2, '0');
     return `${yy}-${mm}-${dd}`;
 }
-/** Inclusive whole-day span between two ISO dates (from <= to). Pure. */
+/**
+ * Inclusive whole-day span between two ISO dates (from <= to). Pure.
+ *
+ * Counts on the UTC timeline (`Date.UTC`), NOT local midnights: a local
+ * `new Date('…T00:00:00')` is DST-sensitive, so a range crossing a spring-forward
+ * day (only 23h long) would floor-divide to one day short — e.g. under
+ * TZ=America/New_York a full March would read 30. UTC calendar midnights are
+ * always an exact 86.4M ms apart, so this is correct in every process timezone.
+ */
 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;
+    const [ay, am, ad] = from.split('-').map(Number);
+    const [by, bm, bd] = to.split('-').map(Number);
+    const a = Date.UTC(ay, am - 1, ad);
+    const b = Date.UTC(by, bm - 1, bd);
+    return Math.round((b - a) / 86_400_000) + 1;
 }
 /** Longest run of consecutive calendar days present in the set. Pure. */
 export function longestStreakOf(days) {
@@ -58,6 +70,27 @@ export function longestStreakOf(days) {
     }
     return best;
 }
+/**
+ * Days whose cost is an outlier vs the median active-day cost — a heads-up for
+ * runaway sessions. Median (not mean) so the spikes don't inflate the baseline.
+ * Needs ≥3 active days for a meaningful median; a floor keeps trivially-cheap
+ * days from tripping the ratio. Sorted by cost desc. Pure.
+ */
+export function detectSpikeDays(days, opts = {}) {
+    const minRatio = opts.minRatio ?? 2.5;
+    const minCostUsd = opts.minCostUsd ?? 0.5;
+    const costs = days.map((d) => d.costUsd).filter((c) => c > 0).sort((a, b) => a - b);
+    if (costs.length < 3)
+        return [];
+    const mid = costs.length >> 1;
+    const median = costs.length % 2 ? costs[mid] : (costs[mid - 1] + costs[mid]) / 2;
+    if (median <= 0)
+        return [];
+    return days
+        .filter((d) => d.costUsd >= minCostUsd && d.costUsd >= minRatio * median)
+        .map((d) => ({ day: d.day, costUsd: d.costUsd, ratioToMedian: d.costUsd / median }))
+        .sort((a, b) => b.costUsd - a.costUsd);
+}
 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).
@@ -145,6 +178,25 @@ export function computeReflection(dayRows, modelRows, from, to, opts = {}, proje
     // 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);
+    // $ saved by prompt caching this period: fold windowed per-model token counts,
+    // then price each via the (injected) resolver. Unpriced models contribute 0.
+    const resolvePrice = opts.resolvePrice ?? resolveTranscriptPrice;
+    const cacheTokens = new Map();
+    for (const r of modelRows) {
+        if (!within(r.day, from, to))
+            continue;
+        const s = cacheTokens.get(r.key) ?? { inputTokens: 0, cacheWriteTokens: 0, cacheReadTokens: 0 };
+        s.inputTokens += r.totals.inputTokens;
+        s.cacheWriteTokens += r.totals.cacheWriteTokens;
+        s.cacheReadTokens += r.totals.cacheReadTokens;
+        cacheTokens.set(r.key, s);
+    }
+    let cacheSavingsUsd = 0;
+    for (const [model, tok] of cacheTokens) {
+        const sv = modelCacheSavings(tok, resolvePrice(model));
+        if (sv !== null)
+            cacheSavingsUsd += sv;
+    }
     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';
@@ -152,6 +204,7 @@ export function computeReflection(dayRows, modelRows, from, to, opts = {}, proje
         period: { from, to, spanDays: spanDays(from, to) },
         totals,
         busiestDay,
+        spikeDays: detectSpikeDays(days.map((r) => ({ day: r.key, costUsd: r.totals.costUsd }))),
         topModels,
         topProjects,
         peakHour: peakHourOf(hourHistogram),
@@ -160,6 +213,7 @@ export function computeReflection(dayRows, modelRows, from, to, opts = {}, proje
         cacheReadPct: inputSide > 0 ? totals.cacheReadTokens / inputSide : 0,
         avgCostPerActiveDay: totals.activeDays > 0 ? totals.costUsd / totals.activeDays : 0,
         trend: { firstHalfCost, secondHalfCost, direction },
+        cacheSavingsUsd,
     };
 }
 //# sourceMappingURL=reflect.js.map

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

@@ -77,7 +77,14 @@ export declare function normalizeDateBound(raw: string | undefined): string | un
  * report must not fail because one session file is mid-write.
  */
 export declare function collectUsage(opts?: CollectOptions): UsageCollection;
-export type UsageDimension = 'day' | 'month' | 'model' | 'project' | 'session';
+export type UsageDimension = 'day' | 'week' | 'month' | 'model' | 'project' | 'session';
+/**
+ * ISO-8601 week key for a `YYYY-MM-DD` date, e.g. '2026-W28'. The week belongs to
+ * the year of its Thursday, so a late-December / early-January week can carry the
+ * neighbouring ISO year (e.g. 2025-12-31 → 2026-W01, 2027-01-01 → 2026-W53).
+ * Keys sort chronologically as strings. Pure.
+ */
+export declare function isoWeekKey(iso: string): string;
 /**
  * Group events along one dimension. Time dimensions sort chronologically;
  * the rest sort by descending cost (what a "top spenders" view wants).

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

@@ -209,8 +209,28 @@ function toUsageEvent(line, project, seen, unpriced) {
         costSource,
     };
 }
+/**
+ * ISO-8601 week key for a `YYYY-MM-DD` date, e.g. '2026-W28'. The week belongs to
+ * the year of its Thursday, so a late-December / early-January week can carry the
+ * neighbouring ISO year (e.g. 2025-12-31 → 2026-W01, 2027-01-01 → 2026-W53).
+ * Keys sort chronologically as strings. Pure.
+ */
+export function isoWeekKey(iso) {
+    const [y, m, d] = iso.split('-').map(Number);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    const dayNum = (date.getUTCDay() + 6) % 7; // Mon=0 … Sun=6
+    date.setUTCDate(date.getUTCDate() - dayNum + 3); // Thursday of this week
+    const isoYear = date.getUTCFullYear();
+    const jan4 = new Date(Date.UTC(isoYear, 0, 4)); // Jan 4 is always in week 1
+    const jan4Day = (jan4.getUTCDay() + 6) % 7;
+    const week1Monday = new Date(jan4);
+    week1Monday.setUTCDate(jan4.getUTCDate() - jan4Day);
+    const week = 1 + Math.round((date.getTime() - week1Monday.getTime()) / (7 * 86_400_000));
+    return `${isoYear}-W${String(week).padStart(2, '0')}`;
+}
 const DIMENSION_KEY = {
     day: (e) => e.dateKey,
+    week: (e) => isoWeekKey(e.dateKey),
     month: (e) => e.monthKey,
     model: (e) => e.model,
     project: (e) => e.project,
@@ -253,7 +273,7 @@ export function aggregateUsage(events, dimension) {
         addEvent(t, e);
     }
     const rows = Array.from(groups.entries()).map(([key, totals]) => ({ key, totals }));
-    if (dimension === 'day' || dimension === 'month') {
+    if (dimension === 'day' || dimension === 'week' || dimension === 'month') {
         rows.sort((a, b) => a.key.localeCompare(b.key));
     }
     else {

package/v3/@swarmdo/cli/dist/src/util/since.d.ts

@@ -0,0 +1,13 @@
+/**
+ * since.ts — normalize compact age windows for `git log --since`.
+ *
+ * git's approxidate parser does NOT understand the bare compact form `90d`
+ * (it silently matches nothing — `git log --since=90d` returns zero commits),
+ * yet `hotspots`/`coupling` document `--since 90d`. This maps the compact forms
+ * (`90d`, `6mo`, `2w`, `1y`, `3h`) to the spelled-out `"90 days ago"` git DOES
+ * understand. Anything already spelled out (`"3 months ago"`), an ISO date, or
+ * an unrecognized token passes through unchanged. Pure + unit-tested.
+ */
+/** Convert `90d`→`90 days ago`, `6mo`→`6 months ago`, etc. Passthrough otherwise. */
+export declare function normalizeSince(since: string): string;
+//# sourceMappingURL=since.d.ts.map

package/v3/@swarmdo/cli/dist/src/util/since.js

@@ -0,0 +1,21 @@
+/**
+ * since.ts — normalize compact age windows for `git log --since`.
+ *
+ * git's approxidate parser does NOT understand the bare compact form `90d`
+ * (it silently matches nothing — `git log --since=90d` returns zero commits),
+ * yet `hotspots`/`coupling` document `--since 90d`. This maps the compact forms
+ * (`90d`, `6mo`, `2w`, `1y`, `3h`) to the spelled-out `"90 days ago"` git DOES
+ * understand. Anything already spelled out (`"3 months ago"`), an ISO date, or
+ * an unrecognized token passes through unchanged. Pure + unit-tested.
+ */
+const COMPACT = /^\s*(\d+)\s*(d|days?|w|wks?|weeks?|mo|mons?|months?|y|yrs?|years?|h|hrs?|hours?)\s*$/i;
+/** Convert `90d`→`90 days ago`, `6mo`→`6 months ago`, etc. Passthrough otherwise. */
+export function normalizeSince(since) {
+    const m = COMPACT.exec(since);
+    if (!m)
+        return since;
+    const c0 = m[2][0].toLowerCase(); // the allowed units are uniquely keyed by first letter
+    const unit = c0 === 'd' ? 'days' : c0 === 'w' ? 'weeks' : c0 === 'y' ? 'years' : c0 === 'h' ? 'hours' : 'months';
+    return `${m[1]} ${unit} ago`;
+}
+//# sourceMappingURL=since.js.map

package/v3/@swarmdo/cli/dist/src/util/stdout.d.ts

@@ -7,6 +7,28 @@
  * (`swarmdo sbom | …`, `pack`, `compact`, `redact`) truncates at the ~64 KiB
  * pipe buffer. Awaiting the write callback guarantees the data reached the OS
  * before we hand control back. For a TTY (synchronous) this is a no-op await.
+ *
+ * Broken-pipe (EPIPE) handling: when the reader closes the pipe early (`… |
+ * head`), Node emits an `'error'` event on the stdout Socket — often
+ * ASYNCHRONOUSLY, after our write callback has already fired — and an unhandled
+ * `'error'` event crashes the process with a raw stack trace. A per-write
+ * listener therefore doesn't cover it (it's gone by the time the async error
+ * lands). So we install ONE persistent EPIPE guard per stream that swallows the
+ * broken pipe (normal producer termination) while still rethrowing any other
+ * stream error, and additionally resolve the write promise on an EPIPE callback.
+ * The `stream` param is injectable so this is unit-testable without a subprocess.
+ */
+/** The subset of a writable stream writeStdout needs (process.stdout satisfies it). */
+export interface WritableLike {
+    write(data: string, cb: (err?: Error | null) => void): boolean;
+    on(event: 'error', listener: (err: Error) => void): unknown;
+}
+/**
+ * Install (once per stream) a persistent `'error'` handler that swallows EPIPE —
+ * a closed reader is normal termination for a Unix producer, not a crash — and
+ * rethrows everything else so genuine stream errors still surface. Exported for
+ * the CLI entry point to arm stdout/stderr before any write happens.
  */
-export declare function writeStdout(data: string): Promise<void>;
+export declare function guardStreamEpipe(stream: WritableLike): void;
+export declare function writeStdout(data: string, stream?: WritableLike): Promise<void>;
 //# sourceMappingURL=stdout.d.ts.map

package/v3/@swarmdo/cli/dist/src/util/stdout.js

@@ -7,10 +7,42 @@
  * (`swarmdo sbom | …`, `pack`, `compact`, `redact`) truncates at the ~64 KiB
  * pipe buffer. Awaiting the write callback guarantees the data reached the OS
  * before we hand control back. For a TTY (synchronous) this is a no-op await.
+ *
+ * Broken-pipe (EPIPE) handling: when the reader closes the pipe early (`… |
+ * head`), Node emits an `'error'` event on the stdout Socket — often
+ * ASYNCHRONOUSLY, after our write callback has already fired — and an unhandled
+ * `'error'` event crashes the process with a raw stack trace. A per-write
+ * listener therefore doesn't cover it (it's gone by the time the async error
+ * lands). So we install ONE persistent EPIPE guard per stream that swallows the
+ * broken pipe (normal producer termination) while still rethrowing any other
+ * stream error, and additionally resolve the write promise on an EPIPE callback.
+ * The `stream` param is injectable so this is unit-testable without a subprocess.
+ */
+const guarded = new WeakSet();
+/**
+ * Install (once per stream) a persistent `'error'` handler that swallows EPIPE —
+ * a closed reader is normal termination for a Unix producer, not a crash — and
+ * rethrows everything else so genuine stream errors still surface. Exported for
+ * the CLI entry point to arm stdout/stderr before any write happens.
  */
-export function writeStdout(data) {
+export function guardStreamEpipe(stream) {
+    if (guarded.has(stream))
+        return;
+    guarded.add(stream);
+    stream.on('error', (err) => {
+        if (err.code !== 'EPIPE')
+            throw err;
+    });
+}
+export function writeStdout(data, stream = process.stdout) {
+    guardStreamEpipe(stream);
     return new Promise((resolve, reject) => {
-        process.stdout.write(data, (err) => (err ? reject(err) : resolve()));
+        stream.write(data, (err) => {
+            if (err && err.code !== 'EPIPE')
+                reject(err);
+            else
+                resolve();
+        });
     });
 }
 //# sourceMappingURL=stdout.js.map

package/v3/@swarmdo/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmdo/cli",
-  "version": "1.30.0",
+  "version": "1.45.0",
   "type": "module",
   "description": "Swarmdo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",