reasonix 0.4.23 → 0.4.24

package/dist/index.d.ts

@@ -2595,4 +2595,126 @@ declare function compareVersions(a: string, b: string): number;
  */
 declare function isNpxInstall(): boolean;
 
-export { AppendOnlyLog, type ApplyResult, type ApplyStatus, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CODE_SYSTEM_PROMPT, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DEFAULT_MAX_RESULT_CHARS, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EditBlock, type EditSnapshot, type EventRole, type FilesystemToolsOptions, type FlattenDecision, type FlattenOptions, type GetLatestVersionOptions, type GetPromptResult, HOOK_EVENTS, HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME, type HarvestOptions, type HookConfig, type HookEvent, type HookOutcome, type HookPayload, type HookReport, type HookScope, type HookSettings, type HookSpawnInput, type HookSpawnResult, type HookSpawner, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type InspectionReport, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, LATEST_CACHE_TTL_MS, LATEST_FETCH_TIMEOUT_MS, type ListPromptsResult, type ListResourcesResult, type ListToolsResult, type LoadHookSettingsOptions, type LoopEvent, MCP_PROTOCOL_VERSION, MEMORY_INDEX_FILE, MEMORY_INDEX_MAX_CHARS, McpClient, type McpClientOptions, type McpContentBlock, type McpProgressHandler, type McpProgressInfo, type McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResourceBlock, type McpResource, type McpResourceContents, type McpResourceContentsBlob, type McpResourceContentsText, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type MemoryEntry, type MemoryScope, MemoryStore, type MemoryStoreOptions, type MemoryToolsOptions, type MemoryType, type WriteInput as MemoryWriteInput, NeedsConfirmationError, PROJECT_MEMORY_FILE, PROJECT_MEMORY_MAX_CHARS, type PageContent, PlanProposedError, type PlanToolOptions, type ProgressNotificationParams, type ProjectMemory, type ReadResourceResult, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type ResolvedHook, type RetryInfo, type RetryOptions, type Role, type RunCommandResult, type RunHooksOptions, type ScavengeOptions, type ScavengeResult, type SearchResult, type SectionResult, type SessionInfo, SessionStats, type SessionSummary, type ShellToolsOptions, type SseMcpSpec, SseTransport, type SseTransportOptions, type StdioMcpSpec, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, type ToolCallContext, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, USER_MEMORY_DIR, Usage, VERSION, VolatileScratch, type WebFetchOptions, type WebSearchOptions, type WebToolsOptions, aggregateBranchUsage, analyzeSchema, appendSessionMessage, applyEditBlock, applyEditBlocks, applyMemoryStack, applyProjectMemory, applyUserMemory, bridgeMcpTools, claudeEquivalentCost, codeSystemPrompt, compareVersions, computeReplayStats, costUsd, decideOutcome, defaultConfigPath, defaultSelector, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatCommandResult, formatHookOutcomeMessage, formatLoopError, formatSearchResults, getLatestVersion, globalSettingsPath, harvest, healLoadedMessages, htmlToText, inputCostUsd, inspectMcpServer, isAllowed, isJsonRpcError, isNpxInstall, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadHooks, loadSessionMessages, matchesTool, memoryEnabled, nestArguments, openTranscriptFile, outputCostUsd, parseEditBlocks, parseMcpSpec, parseMojeekResults, parseTranscript, prepareSpawn, projectHash, projectSettingsPath, quoteForCmdExe, readConfig, readProjectMemory, readTranscript, recordFromLoopEvent, redactKey, registerFilesystemTools, registerMemoryTools, registerPlanTool, registerShellTools, registerWebTools, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, resolveExecutable, restoreSnapshots, runBranches, runCommand, runHooks, sanitizeMemoryName, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, tokenizeCommand, truncateForModel, webFetch, webSearch, writeConfig, writeMeta, writeRecord };
+/**
+ * Persistent per-turn usage log at `~/.reasonix/usage.jsonl`.
+ *
+ * Each line is a single `UsageRecord` — one turn's tokens + cost
+ * snapshot — appended after every `assistant_final` event. This is
+ * what drives `reasonix stats` (the dashboard, no-arg form), so the
+ * user can see how much they've spent vs what the equivalent Claude
+ * spend would have been. The Pillar 1 pitch (94–97% cost reduction
+ * vs Claude, from the v0.3 hard-number table) becomes a fact users
+ * can verify on their own machine.
+ *
+ * Format choices:
+ *   - **append-only JSONL** — one line per turn, durable, survives
+ *     abrupt exits. A corrupted tail line loses at most one record.
+ *   - **flat keys, no nesting** — readable with `jq` / `cut` / `awk`;
+ *     the model doesn't need to parse this, humans do.
+ *   - **best-effort writes** — disk errors never propagate into the
+ *     turn. We log nothing (no `console.error`) because the TUI is
+ *     rendering Ink; a silent skip is the least-worst failure mode.
+ *   - **no PII, no prompts, no completions** — the log contains
+ *     tokens and costs, that's it. Sessions are identified by the
+ *     user-chosen name (never a prompt).
+ *
+ * This file is deliberately NOT wired through project memory or
+ * skills — those are content pins. Usage is pure telemetry.
+ */
+
+/** One turn's snapshot — serialized verbatim as a JSONL line. */
+interface UsageRecord {
+    /** Epoch millis when the record was written. */
+    ts: number;
+    /** Session name if the turn ran inside a persisted session, `null` for ephemeral. */
+    session: string | null;
+    /** Model id the turn ran against (drives the pricing lookup). */
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    cacheHitTokens: number;
+    cacheMissTokens: number;
+    /** Total cost of the turn in USD. */
+    costUsd: number;
+    /** What the same turn would have cost at Claude Sonnet 4.6 rates. */
+    claudeEquivUsd: number;
+}
+/** Where the log lives. Tests override via `opts.path`. */
+declare function defaultUsageLogPath(homeDirOverride?: string): string;
+interface AppendUsageInput {
+    session: string | null;
+    model: string;
+    usage: Usage;
+    /** Override the timestamp (tests). */
+    now?: number;
+    /** Override the log path (tests). */
+    path?: string;
+}
+/**
+ * Append one record and return it. Swallows disk errors — the TUI
+ * should keep working even if `~/.reasonix/` is read-only.
+ *
+ * Returns the record that was written (or would have been written
+ * if the disk had cooperated) so tests / callers can assert on the
+ * computed cost fields without a round trip through the log file.
+ */
+declare function appendUsage(input: AppendUsageInput): UsageRecord;
+/**
+ * Read + parse the log. Malformed lines are silently skipped so a
+ * single corrupted write (half-flushed on power loss, user hand-edit)
+ * doesn't throw away the rest of the history.
+ */
+declare function readUsageLog(path?: string): UsageRecord[];
+/** One row of the `reasonix stats` dashboard — a rolled-up window. */
+interface UsageBucket {
+    label: string;
+    /** Start of the window as epoch millis. `0` = unbounded (all-time). */
+    since: number;
+    turns: number;
+    promptTokens: number;
+    completionTokens: number;
+    cacheHitTokens: number;
+    cacheMissTokens: number;
+    costUsd: number;
+    claudeEquivUsd: number;
+}
+/** Cache hit ratio for a bucket — zero denominator returns 0. */
+declare function bucketCacheHitRatio(b: UsageBucket): number;
+/** Savings vs Claude as a fraction (0.94 = 94% savings). 0 if Claude cost is 0. */
+declare function bucketSavingsFraction(b: UsageBucket): number;
+interface AggregateOptions {
+    /** Override `Date.now()` for deterministic tests. */
+    now?: number;
+}
+interface UsageAggregate {
+    /** Fixed-order rolling windows: today, week, month, all-time. */
+    buckets: UsageBucket[];
+    /** Model id → turn count. Sorted descending; top entry is the "most used." */
+    byModel: Array<{
+        model: string;
+        turns: number;
+    }>;
+    /** Session name → turn count. Sorted descending. Null sessions are grouped under `"(ephemeral)"`. */
+    bySession: Array<{
+        session: string;
+        turns: number;
+    }>;
+    /** Earliest record's ts, or `null` when the log is empty. Drives "saved $X since <date>". */
+    firstSeen: number | null;
+    /** Latest record's ts, or `null` when the log is empty. */
+    lastSeen: number | null;
+}
+/**
+ * Fold a flat record list into the dashboard shape — rolling windows
+ * plus model / session histograms. Windows are INCLUSIVE of boundary:
+ *   - today = last 24h (rolling, not calendar-day)
+ *   - week  = last 7d
+ *   - month = last 30d
+ *   - all   = every record
+ * Rolling windows avoid "it's 00:03, 'today' is empty" surprises.
+ */
+declare function aggregateUsage(records: UsageRecord[], opts?: AggregateOptions): UsageAggregate;
+/** File-size helper for the stats header — "1.2 MB" etc. Returns "" if missing. */
+declare function formatLogSize(path?: string): string;
+
+export { type AggregateOptions, AppendOnlyLog, type AppendUsageInput, type ApplyResult, type ApplyStatus, type BranchOptions, type BranchProgress, type BranchResult, type BranchSample, type BranchSelector, type BranchSummary, type BridgeOptions, type BridgeResult, CODE_SYSTEM_PROMPT, CacheFirstLoop, type CacheFirstLoopOptions, type CallToolResult, type ChatMessage, type ChatResponse, DEFAULT_MAX_RESULT_CHARS, DeepSeekClient, type DeepSeekClientOptions, type RenderOptions as DiffRenderOptions, type DiffReport, type DiffSide, type EditBlock, type EditSnapshot, type EventRole, type FilesystemToolsOptions, type FlattenDecision, type FlattenOptions, type GetLatestVersionOptions, type GetPromptResult, HOOK_EVENTS, HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME, type HarvestOptions, type HookConfig, type HookEvent, type HookOutcome, type HookPayload, type HookReport, type HookScope, type HookSettings, type HookSpawnInput, type HookSpawnResult, type HookSpawner, ImmutablePrefix, type ImmutablePrefixOptions, type InitializeResult, type InspectionReport, type JSONSchema, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, LATEST_CACHE_TTL_MS, LATEST_FETCH_TIMEOUT_MS, type ListPromptsResult, type ListResourcesResult, type ListToolsResult, type LoadHookSettingsOptions, type LoopEvent, MCP_PROTOCOL_VERSION, MEMORY_INDEX_FILE, MEMORY_INDEX_MAX_CHARS, McpClient, type McpClientOptions, type McpContentBlock, type McpProgressHandler, type McpProgressInfo, type McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResourceBlock, type McpResource, type McpResourceContents, type McpResourceContentsBlob, type McpResourceContentsText, type McpSpec, type McpTool, type McpToolSchema, type McpTransport, type MemoryEntry, type MemoryScope, MemoryStore, type MemoryStoreOptions, type MemoryToolsOptions, type MemoryType, type WriteInput as MemoryWriteInput, NeedsConfirmationError, PROJECT_MEMORY_FILE, PROJECT_MEMORY_MAX_CHARS, type PageContent, PlanProposedError, type PlanToolOptions, type ProgressNotificationParams, type ProjectMemory, type ReadResourceResult, type ReadTranscriptResult, type ReasonixConfig, type ReconfigurableOptions, type RepairReport, type ReplayStats, type ResolvedHook, type RetryInfo, type RetryOptions, type Role, type RunCommandResult, type RunHooksOptions, type ScavengeOptions, type ScavengeResult, type SearchResult, type SectionResult, type SessionInfo, SessionStats, type SessionSummary, type ShellToolsOptions, type SseMcpSpec, SseTransport, type SseTransportOptions, type StdioMcpSpec, StdioTransport, type StdioTransportOptions, StormBreaker, type StreamChunk, type ToolCall, type ToolCallContext, ToolCallRepair, type ToolCallRepairOptions, type ToolDefinition, type ToolFunctionSpec, ToolRegistry, type ToolSpec, type TranscriptMeta, type TranscriptRecord, type TruncationRepairResult, type TurnPair, type TurnStats, type TypedPlanState, USER_MEMORY_DIR, Usage, type UsageAggregate, type UsageBucket, type UsageRecord, VERSION, VolatileScratch, type WebFetchOptions, type WebSearchOptions, type WebToolsOptions, aggregateBranchUsage, aggregateUsage, analyzeSchema, appendSessionMessage, appendUsage, applyEditBlock, applyEditBlocks, applyMemoryStack, applyProjectMemory, applyUserMemory, bridgeMcpTools, bucketCacheHitRatio, bucketSavingsFraction, claudeEquivalentCost, codeSystemPrompt, compareVersions, computeReplayStats, costUsd, decideOutcome, defaultConfigPath, defaultSelector, defaultUsageLogPath, deleteSession, diffTranscripts, emptyPlanState, fetchWithRetry, flattenMcpResult, flattenSchema, formatCommandResult, formatHookOutcomeMessage, formatLogSize, formatLoopError, formatSearchResults, getLatestVersion, globalSettingsPath, harvest, healLoadedMessages, htmlToText, inputCostUsd, inspectMcpServer, isAllowed, isJsonRpcError, isNpxInstall, isPlanStateEmpty, isPlausibleKey, listSessions, loadApiKey, loadDotenv, loadHooks, loadSessionMessages, matchesTool, memoryEnabled, nestArguments, openTranscriptFile, outputCostUsd, parseEditBlocks, parseMcpSpec, parseMojeekResults, parseTranscript, prepareSpawn, projectHash, projectSettingsPath, quoteForCmdExe, readConfig, readProjectMemory, readTranscript, readUsageLog, recordFromLoopEvent, redactKey, registerFilesystemTools, registerMemoryTools, registerPlanTool, registerShellTools, registerWebTools, renderMarkdown as renderDiffMarkdown, renderSummaryTable as renderDiffSummary, repairTruncatedJson, replayFromFile, resolveExecutable, restoreSnapshots, runBranches, runCommand, runHooks, sanitizeMemoryName, sanitizeName as sanitizeSessionName, saveApiKey, scavengeToolCalls, sessionPath, sessionsDir, similarity, snapshotBeforeEdits, stripHallucinatedToolMarkup, tokenizeCommand, truncateForModel, webFetch, webSearch, writeConfig, writeMeta, writeRecord };

package/dist/index.js

@@ -5099,6 +5099,132 @@ function isNpxInstall() {
   if (ua.includes("npx/")) return true;
   return false;
 }
+
+// src/usage.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync12, statSync as statSync4 } from "fs";
+import { homedir as homedir7 } from "os";
+import { dirname as dirname6, join as join10 } from "path";
+function defaultUsageLogPath(homeDirOverride) {
+  return join10(homeDirOverride ?? homedir7(), ".reasonix", "usage.jsonl");
+}
+function appendUsage(input) {
+  const record = {
+    ts: input.now ?? Date.now(),
+    session: input.session,
+    model: input.model,
+    promptTokens: input.usage.promptTokens,
+    completionTokens: input.usage.completionTokens,
+    cacheHitTokens: input.usage.promptCacheHitTokens,
+    cacheMissTokens: input.usage.promptCacheMissTokens,
+    costUsd: costUsd(input.model, input.usage),
+    claudeEquivUsd: claudeEquivalentCost(input.usage)
+  };
+  const path = input.path ?? defaultUsageLogPath();
+  try {
+    mkdirSync6(dirname6(path), { recursive: true });
+    appendFileSync2(path, `${JSON.stringify(record)}
+`, "utf8");
+  } catch {
+  }
+  return record;
+}
+function readUsageLog(path = defaultUsageLogPath()) {
+  if (!existsSync10(path)) return [];
+  let raw;
+  try {
+    raw = readFileSync12(path, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (isValidRecord(rec)) out.push(rec);
+    } catch {
+    }
+  }
+  return out;
+}
+function isValidRecord(rec) {
+  if (!rec || typeof rec !== "object") return false;
+  const r = rec;
+  return typeof r.ts === "number" && typeof r.model === "string" && typeof r.promptTokens === "number" && typeof r.completionTokens === "number" && typeof r.cacheHitTokens === "number" && typeof r.cacheMissTokens === "number" && typeof r.costUsd === "number" && typeof r.claudeEquivUsd === "number";
+}
+function bucketCacheHitRatio(b) {
+  const denom = b.cacheHitTokens + b.cacheMissTokens;
+  return denom > 0 ? b.cacheHitTokens / denom : 0;
+}
+function bucketSavingsFraction(b) {
+  return b.claudeEquivUsd > 0 ? 1 - b.costUsd / b.claudeEquivUsd : 0;
+}
+function emptyBucket(label, since) {
+  return {
+    label,
+    since,
+    turns: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    cacheHitTokens: 0,
+    cacheMissTokens: 0,
+    costUsd: 0,
+    claudeEquivUsd: 0
+  };
+}
+function addToBucket(b, r) {
+  b.turns += 1;
+  b.promptTokens += r.promptTokens;
+  b.completionTokens += r.completionTokens;
+  b.cacheHitTokens += r.cacheHitTokens;
+  b.cacheMissTokens += r.cacheMissTokens;
+  b.costUsd += r.costUsd;
+  b.claudeEquivUsd += r.claudeEquivUsd;
+}
+function aggregateUsage(records, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const day = 24 * 60 * 60 * 1e3;
+  const today = emptyBucket("today", now - day);
+  const week = emptyBucket("week", now - 7 * day);
+  const month = emptyBucket("month", now - 30 * day);
+  const all = emptyBucket("all-time", 0);
+  const modelCounts = /* @__PURE__ */ new Map();
+  const sessionCounts = /* @__PURE__ */ new Map();
+  let firstSeen = null;
+  let lastSeen = null;
+  for (const r of records) {
+    addToBucket(all, r);
+    if (r.ts >= today.since) addToBucket(today, r);
+    if (r.ts >= week.since) addToBucket(week, r);
+    if (r.ts >= month.since) addToBucket(month, r);
+    modelCounts.set(r.model, (modelCounts.get(r.model) ?? 0) + 1);
+    const sessKey = r.session ?? "(ephemeral)";
+    sessionCounts.set(sessKey, (sessionCounts.get(sessKey) ?? 0) + 1);
+    if (firstSeen === null || r.ts < firstSeen) firstSeen = r.ts;
+    if (lastSeen === null || r.ts > lastSeen) lastSeen = r.ts;
+  }
+  const byModel = Array.from(modelCounts.entries()).map(([model, turns]) => ({ model, turns })).sort((a, b) => b.turns - a.turns);
+  const bySession = Array.from(sessionCounts.entries()).map(([session, turns]) => ({ session, turns })).sort((a, b) => b.turns - a.turns);
+  return {
+    buckets: [today, week, month, all],
+    byModel,
+    bySession,
+    firstSeen,
+    lastSeen
+  };
+}
+function formatLogSize(path = defaultUsageLogPath()) {
+  if (!existsSync10(path)) return "";
+  try {
+    const s = statSync4(path);
+    const bytes = s.size;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  } catch {
+    return "";
+  }
+}
 export {
   AppendOnlyLog,
   CODE_SYSTEM_PROMPT,
@@ -5131,14 +5257,18 @@ export {
   VERSION,
   VolatileScratch,
   aggregateBranchUsage,
+  aggregateUsage,
   analyzeSchema,
   appendSessionMessage,
+  appendUsage,
   applyEditBlock,
   applyEditBlocks,
   applyMemoryStack,
   applyProjectMemory,
   applyUserMemory,
   bridgeMcpTools,
+  bucketCacheHitRatio,
+  bucketSavingsFraction,
   claudeEquivalentCost,
   codeSystemPrompt,
   compareVersions,
@@ -5147,6 +5277,7 @@ export {
   decideOutcome,
   defaultConfigPath,
   defaultSelector,
+  defaultUsageLogPath,
   deleteSession,
   diffTranscripts,
   emptyPlanState,
@@ -5155,6 +5286,7 @@ export {
   flattenSchema,
   formatCommandResult,
   formatHookOutcomeMessage,
+  formatLogSize,
   formatLoopError,
   formatSearchResults,
   getLatestVersion,
@@ -5190,6 +5322,7 @@ export {
   readConfig,
   readProjectMemory,
   readTranscript,
+  readUsageLog,
   recordFromLoopEvent,
   redactKey,
   registerFilesystemTools,