myshell-tools 1.0.0 → 2.0.0

package/dist/infra/atomic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.js","sourceRoot":"","sources":["../../src/infra/atomic.ts"],"names":[],"mappings":"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"}

package/dist/infra/clock.d.ts

@@ -0,0 +1,9 @@
+/**
+ * src/infra/clock.ts — System clock implementation of the Clock port.
+ *
+ * This is the SINGLE place in the codebase where impure time/random globals
+ * (Date, Math.random, randomUUID) are allowed. All other modules receive a
+ * Clock via injection, keeping them pure and testable.
+ */
+import type { Clock } from '../core/types.js';
+export declare const systemClock: Clock;

package/dist/infra/clock.js

@@ -0,0 +1,15 @@
+/**
+ * src/infra/clock.ts — System clock implementation of the Clock port.
+ *
+ * This is the SINGLE place in the codebase where impure time/random globals
+ * (Date, Math.random, randomUUID) are allowed. All other modules receive a
+ * Clock via injection, keeping them pure and testable.
+ */
+import { randomUUID } from 'node:crypto';
+export const systemClock = {
+    now: () => Date.now(),
+    isoNow: () => new Date().toISOString(),
+    uuid: () => randomUUID(),
+    random: () => Math.random(),
+};
+//# sourceMappingURL=clock.js.map

package/dist/infra/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/infra/clock.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,CAAC,MAAM,WAAW,GAAU;IAChC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;IACrB,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IACtC,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE;IACxB,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE;CAC5B,CAAC"}

package/dist/infra/index.d.ts

@@ -0,0 +1,9 @@
+export { acquireLock, releaseLock, withLock, atomicWrite, atomicAppendJSONL } from './atomic.js';
+export type { LockOptions } from './atomic.js';
+export { getModelPricing, calculateCost, getCheapestForTier, isPricingStale, PRICING_TABLE, } from './pricing.js';
+export type { ModelPricing, PricingTable } from './pricing.js';
+export { systemClock } from './clock.js';
+export { getStateDir, getSessionsDir, getSessionFile, getLedgerFile } from './paths.js';
+export { createSessionWriter, readSession } from './session.js';
+export { createLedger, readLedger, summarizeLedger } from './ledger.js';
+export type { ModelSummary, LedgerSummary } from './ledger.js';

package/dist/infra/index.js

@@ -0,0 +1,7 @@
+export { acquireLock, releaseLock, withLock, atomicWrite, atomicAppendJSONL } from './atomic.js';
+export { getModelPricing, calculateCost, getCheapestForTier, isPricingStale, PRICING_TABLE, } from './pricing.js';
+export { systemClock } from './clock.js';
+export { getStateDir, getSessionsDir, getSessionFile, getLedgerFile } from './paths.js';
+export { createSessionWriter, readSession } from './session.js';
+export { createLedger, readLedger, summarizeLedger } from './ledger.js';
+//# sourceMappingURL=index.js.map

package/dist/infra/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/infra/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEjG,OAAO,EACL,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/infra/ledger.d.ts

@@ -0,0 +1,49 @@
+/**
+ * src/infra/ledger.ts — LedgerWriter implementation, ledger reader, and summarizer.
+ *
+ * The ledger is a JSONL file at `.myshell-tools/ledger.jsonl`. Each `record` call appends
+ * one LedgerEntry atomically. `readLedger` re-hydrates entries (skipping malformed
+ * lines). `summarizeLedger` is a pure reduction used by `myshell-tools cost`.
+ */
+import type { LedgerEntry, LedgerWriter } from '../core/types.js';
+/**
+ * Create a LedgerWriter for the given working directory.
+ *
+ * @param opts.cwd - The project working directory (parent of `.myshell-tools/`).
+ */
+export declare function createLedger(opts: {
+    cwd: string;
+}): LedgerWriter;
+/**
+ * Read all LedgerEntry records from the ledger JSONL file.
+ *
+ * Returns an empty array if the file does not exist. Malformed lines are
+ * silently skipped.
+ *
+ * @param cwd - The project working directory.
+ */
+export declare function readLedger(cwd: string): Promise<LedgerEntry[]>;
+/** Per-model aggregation used in the summary. */
+export interface ModelSummary {
+    readonly calls: number;
+    readonly usd: number;
+}
+/** Aggregate summary returned by `summarizeLedger`. */
+export interface LedgerSummary {
+    readonly totalUsd: number;
+    readonly calls: number;
+    readonly byModel: Record<string, ModelSummary>;
+}
+/**
+ * Pure reduction over a ledger entry array.
+ *
+ * Computes:
+ *  - `totalUsd`  — sum of all `entry.usd` values
+ *  - `calls`     — total number of entries
+ *  - `byModel`   — per-model breakdown keyed by `entry.model`
+ *
+ * No I/O. Safe to call in tests with hand-built arrays.
+ *
+ * @param entries - Array of LedgerEntry objects (may be empty).
+ */
+export declare function summarizeLedger(entries: LedgerEntry[]): LedgerSummary;

package/dist/infra/ledger.js

@@ -0,0 +1,90 @@
+/**
+ * src/infra/ledger.ts — LedgerWriter implementation, ledger reader, and summarizer.
+ *
+ * The ledger is a JSONL file at `.myshell-tools/ledger.jsonl`. Each `record` call appends
+ * one LedgerEntry atomically. `readLedger` re-hydrates entries (skipping malformed
+ * lines). `summarizeLedger` is a pure reduction used by `myshell-tools cost`.
+ */
+import { mkdir, readFile } from 'node:fs/promises';
+import { atomicAppendJSONL } from './atomic.js';
+import { getStateDir, getLedgerFile } from './paths.js';
+/**
+ * Create a LedgerWriter for the given working directory.
+ *
+ * @param opts.cwd - The project working directory (parent of `.myshell-tools/`).
+ */
+export function createLedger(opts) {
+    const { cwd } = opts;
+    return {
+        async record(entry) {
+            await mkdir(getStateDir(cwd), { recursive: true });
+            await atomicAppendJSONL(getLedgerFile(cwd), entry);
+        },
+    };
+}
+/**
+ * Read all LedgerEntry records from the ledger JSONL file.
+ *
+ * Returns an empty array if the file does not exist. Malformed lines are
+ * silently skipped.
+ *
+ * @param cwd - The project working directory.
+ */
+export async function readLedger(cwd) {
+    let raw;
+    try {
+        raw = await readFile(getLedgerFile(cwd), 'utf8');
+    }
+    catch (err) {
+        const nodeErr = err;
+        if (nodeErr.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+/**
+ * Pure reduction over a ledger entry array.
+ *
+ * Computes:
+ *  - `totalUsd`  — sum of all `entry.usd` values
+ *  - `calls`     — total number of entries
+ *  - `byModel`   — per-model breakdown keyed by `entry.model`
+ *
+ * No I/O. Safe to call in tests with hand-built arrays.
+ *
+ * @param entries - Array of LedgerEntry objects (may be empty).
+ */
+export function summarizeLedger(entries) {
+    let totalUsd = 0;
+    const byModel = {};
+    for (const entry of entries) {
+        totalUsd += entry.usd;
+        const existing = byModel[entry.model];
+        if (existing !== undefined) {
+            existing.calls += 1;
+            existing.usd += entry.usd;
+        }
+        else {
+            byModel[entry.model] = { calls: 1, usd: entry.usd };
+        }
+    }
+    return {
+        totalUsd,
+        calls: entries.length,
+        byModel,
+    };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/infra/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/infra/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAqB;IAChD,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAErB,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAkB;YAC7B,MAAM,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,iBAAiB,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,OAAsB;IACpD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,OAAO,GAAmD,EAAE,CAAC;IAEnE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC;QAEtB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC;YACpB,QAAQ,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QACtD,CAAC;IACH,CAAC;IAED,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,OAAO,CAAC,MAAM;QACrB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/infra/paths.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/infra/paths.ts — Pure path helpers for myshell-tools's filesystem layout.
+ *
+ * All functions are pure path joins (no fs I/O). The canonical layout is:
+ *   <cwd>/
+ *     .myshell-tools/
+ *       sessions/
+ *         current.jsonl   ← active session log
+ *       ledger.jsonl       ← cost/usage ledger
+ */
+/**
+ * Returns the path to the `.myshell-tools` directory inside the given working dir.
+ */
+export declare function getStateDir(cwd: string): string;
+/**
+ * Returns the path to the `sessions` subdirectory inside `.myshell-tools`.
+ */
+export declare function getSessionsDir(cwd: string): string;
+/**
+ * Returns the path to the current session JSONL file.
+ * Path: <cwd>/.myshell-tools/sessions/current.jsonl
+ */
+export declare function getSessionFile(cwd: string): string;
+/**
+ * Returns the path to the cost/usage ledger JSONL file.
+ * Path: <cwd>/.myshell-tools/ledger.jsonl
+ */
+export declare function getLedgerFile(cwd: string): string;

package/dist/infra/paths.js

@@ -0,0 +1,38 @@
+/**
+ * src/infra/paths.ts — Pure path helpers for myshell-tools's filesystem layout.
+ *
+ * All functions are pure path joins (no fs I/O). The canonical layout is:
+ *   <cwd>/
+ *     .myshell-tools/
+ *       sessions/
+ *         current.jsonl   ← active session log
+ *       ledger.jsonl       ← cost/usage ledger
+ */
+import { join } from 'node:path';
+/**
+ * Returns the path to the `.myshell-tools` directory inside the given working dir.
+ */
+export function getStateDir(cwd) {
+    return join(cwd, '.myshell-tools');
+}
+/**
+ * Returns the path to the `sessions` subdirectory inside `.myshell-tools`.
+ */
+export function getSessionsDir(cwd) {
+    return join(getStateDir(cwd), 'sessions');
+}
+/**
+ * Returns the path to the current session JSONL file.
+ * Path: <cwd>/.myshell-tools/sessions/current.jsonl
+ */
+export function getSessionFile(cwd) {
+    return join(getSessionsDir(cwd), 'current.jsonl');
+}
+/**
+ * Returns the path to the cost/usage ledger JSONL file.
+ * Path: <cwd>/.myshell-tools/ledger.jsonl
+ */
+export function getLedgerFile(cwd) {
+    return join(getStateDir(cwd), 'ledger.jsonl');
+}
+//# sourceMappingURL=paths.js.map

package/dist/infra/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/infra/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,eAAe,CAAC,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC;AAChD,CAAC"}

package/dist/infra/pricing.d.ts

@@ -0,0 +1,47 @@
+/**
+ * src/infra/pricing.ts
+ *
+ * Corrected price table — Appendix A of the myshell-tools project plan.
+ *
+ * Provenance
+ * ----------
+ * Claude pricing  : https://www.anthropic.com/pricing
+ * OpenAI pricing  : https://platform.openai.com/docs/pricing
+ * Captured        : 2026-05-29
+ */
+export interface ModelPricing {
+    readonly provider: 'claude' | 'codex';
+    readonly model: string;
+    readonly aliases: readonly string[];
+    readonly tier: 'worker' | 'ic' | 'manager';
+    readonly inputPer1M: number;
+    readonly outputPer1M: number;
+    readonly contextWindow: number;
+}
+export interface PricingTable {
+    readonly asOf: string;
+    readonly sourceUrls: readonly string[];
+    readonly models: readonly ModelPricing[];
+}
+export declare const PRICING_TABLE: PricingTable;
+/**
+ * Look up a model entry by exact model ID or any of its aliases.
+ * The lookup is case-insensitive.
+ */
+export declare function getModelPricing(provider: string, model: string): ModelPricing | undefined;
+/**
+ * Calculate the USD cost for a given number of input and output tokens.
+ */
+export declare function calculateCost(inputTokens: number, outputTokens: number, pricing: ModelPricing): number;
+/**
+ * Return the cheapest model (lowest inputPer1M) for a given tier,
+ * optionally restricted to the supplied provider IDs.
+ *
+ * Throws if no matching model exists.
+ */
+export declare function getCheapestForTier(tier: 'worker' | 'ic' | 'manager', availableProviders?: string[]): ModelPricing;
+/**
+ * Returns true when the pricing table is older than maxAgeDays (default 90).
+ * Useful for emitting a staleness warning at runtime.
+ */
+export declare function isPricingStale(maxAgeDays?: number): boolean;

package/dist/infra/pricing.js

@@ -0,0 +1,151 @@
+/**
+ * src/infra/pricing.ts
+ *
+ * Corrected price table — Appendix A of the myshell-tools project plan.
+ *
+ * Provenance
+ * ----------
+ * Claude pricing  : https://www.anthropic.com/pricing
+ * OpenAI pricing  : https://platform.openai.com/docs/pricing
+ * Captured        : 2026-05-29
+ */
+// ---------------------------------------------------------------------------
+// Data
+// ---------------------------------------------------------------------------
+export const PRICING_TABLE = {
+    asOf: '2026-05-29',
+    sourceUrls: [
+        'https://www.anthropic.com/pricing',
+        'https://platform.openai.com/docs/pricing',
+    ],
+    models: [
+        // ---- Anthropic / Claude ------------------------------------------------
+        {
+            provider: 'claude',
+            model: 'claude-opus-4-7',
+            aliases: ['opus', 'opus-4.7', 'claude-opus-4.7'],
+            tier: 'manager',
+            inputPer1M: 5,
+            outputPer1M: 25,
+            contextWindow: 200_000,
+        },
+        {
+            provider: 'claude',
+            model: 'claude-sonnet-4-6',
+            aliases: ['sonnet', 'sonnet-4.6', 'claude-sonnet-4.6'],
+            tier: 'ic',
+            inputPer1M: 3,
+            outputPer1M: 15,
+            contextWindow: 200_000,
+        },
+        {
+            provider: 'claude',
+            model: 'claude-haiku-4-5',
+            aliases: ['haiku', 'haiku-4.5', 'claude-haiku-4.5'],
+            tier: 'worker',
+            inputPer1M: 0.8,
+            outputPer1M: 4,
+            contextWindow: 200_000,
+        },
+        // ---- OpenAI / Codex ----------------------------------------------------
+        {
+            provider: 'codex',
+            model: 'gpt-5.5',
+            aliases: ['gpt5.5', 'gpt-5-5'],
+            tier: 'manager',
+            inputPer1M: 5,
+            outputPer1M: 30,
+            contextWindow: 128_000,
+        },
+        {
+            provider: 'codex',
+            model: 'gpt-5.4',
+            aliases: ['gpt5.4', 'gpt-5-4'],
+            tier: 'ic',
+            inputPer1M: 2.5,
+            outputPer1M: 15,
+            contextWindow: 128_000,
+        },
+        {
+            provider: 'codex',
+            model: 'gpt-5.4-mini',
+            aliases: ['gpt5.4-mini', 'gpt-5-4-mini'],
+            tier: 'worker',
+            inputPer1M: 0.75,
+            outputPer1M: 4.5,
+            contextWindow: 128_000,
+        },
+        {
+            provider: 'codex',
+            model: 'gpt-5.4-nano',
+            aliases: ['gpt5.4-nano', 'gpt-5-4-nano'],
+            tier: 'worker',
+            inputPer1M: 0.2,
+            outputPer1M: 1.25,
+            contextWindow: 128_000,
+        },
+        {
+            provider: 'codex',
+            model: 'gpt-5.2-codex',
+            aliases: ['codex', 'gpt5.2-codex', 'gpt-5-2-codex'],
+            tier: 'ic',
+            inputPer1M: 1.75,
+            outputPer1M: 14,
+            contextWindow: 128_000,
+        },
+    ],
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Look up a model entry by exact model ID or any of its aliases.
+ * The lookup is case-insensitive.
+ */
+export function getModelPricing(provider, model) {
+    const needle = model.toLowerCase();
+    return PRICING_TABLE.models.find((m) => m.provider === provider &&
+        (m.model.toLowerCase() === needle ||
+            m.aliases.some((a) => a.toLowerCase() === needle)));
+}
+/**
+ * Calculate the USD cost for a given number of input and output tokens.
+ */
+export function calculateCost(inputTokens, outputTokens, pricing) {
+    const inputCost = (inputTokens / 1_000_000) * pricing.inputPer1M;
+    const outputCost = (outputTokens / 1_000_000) * pricing.outputPer1M;
+    return inputCost + outputCost;
+}
+/**
+ * Return the cheapest model (lowest inputPer1M) for a given tier,
+ * optionally restricted to the supplied provider IDs.
+ *
+ * Throws if no matching model exists.
+ */
+export function getCheapestForTier(tier, availableProviders) {
+    let candidates = PRICING_TABLE.models.filter((m) => m.tier === tier);
+    if (availableProviders && availableProviders.length > 0) {
+        candidates = candidates.filter((m) => availableProviders.includes(m.provider));
+    }
+    if (candidates.length === 0) {
+        throw new Error(`No models available for tier "${tier}"` +
+            (availableProviders ? ` with providers [${availableProviders.join(', ')}]` : ''));
+    }
+    // Primary sort: inputPer1M ascending; secondary: outputPer1M ascending
+    return candidates.reduce((cheapest, m) => m.inputPer1M < cheapest.inputPer1M ||
+        (m.inputPer1M === cheapest.inputPer1M && m.outputPer1M < cheapest.outputPer1M)
+        ? m
+        : cheapest);
+}
+/**
+ * Returns true when the pricing table is older than maxAgeDays (default 90).
+ * Useful for emitting a staleness warning at runtime.
+ */
+export function isPricingStale(maxAgeDays = 90) {
+    const asOf = new Date(PRICING_TABLE.asOf);
+    const now = new Date();
+    const diffMs = now.getTime() - asOf.getTime();
+    const diffDays = diffMs / (1_000 * 60 * 60 * 24);
+    return diffDays > maxAgeDays;
+}
+//# sourceMappingURL=pricing.js.map

package/dist/infra/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/infra/pricing.ts"],"names":[],"mappings":"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"}

package/dist/infra/session.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/infra/session.ts — SessionWriter implementation and session reader.
+ *
+ * Sessions are persisted as JSONL files under `.myshell-tools/sessions/current.jsonl`.
+ * Each call to `append` writes a single line atomically using `atomicAppendJSONL`.
+ * `readSession` re-hydrates a session from the JSONL file, skipping any malformed
+ * lines so a partial write can never break a resume.
+ */
+import type { SessionEntry, SessionWriter } from '../core/types.js';
+/**
+ * Create a SessionWriter for the given working directory and session id.
+ *
+ * @param opts.cwd - The project working directory (parent of `.myshell-tools/`).
+ * @param opts.id  - A unique session identifier (typically a UUID).
+ */
+export declare function createSessionWriter(opts: {
+    cwd: string;
+    id: string;
+}): SessionWriter;
+/**
+ * Read all SessionEntry records from the current session JSONL file.
+ *
+ * Returns an empty array if the file does not exist. Malformed lines (e.g.
+ * caused by a partial write) are silently skipped.
+ *
+ * @param cwd - The project working directory.
+ */
+export declare function readSession(cwd: string): Promise<SessionEntry[]>;

package/dist/infra/session.js

@@ -0,0 +1,61 @@
+/**
+ * src/infra/session.ts — SessionWriter implementation and session reader.
+ *
+ * Sessions are persisted as JSONL files under `.myshell-tools/sessions/current.jsonl`.
+ * Each call to `append` writes a single line atomically using `atomicAppendJSONL`.
+ * `readSession` re-hydrates a session from the JSONL file, skipping any malformed
+ * lines so a partial write can never break a resume.
+ */
+import { mkdir, readFile } from 'node:fs/promises';
+import { atomicAppendJSONL } from './atomic.js';
+import { getSessionsDir, getSessionFile } from './paths.js';
+/**
+ * Create a SessionWriter for the given working directory and session id.
+ *
+ * @param opts.cwd - The project working directory (parent of `.myshell-tools/`).
+ * @param opts.id  - A unique session identifier (typically a UUID).
+ */
+export function createSessionWriter(opts) {
+    const { cwd, id } = opts;
+    return {
+        id,
+        async append(entry) {
+            await mkdir(getSessionsDir(cwd), { recursive: true });
+            await atomicAppendJSONL(getSessionFile(cwd), entry);
+        },
+    };
+}
+/**
+ * Read all SessionEntry records from the current session JSONL file.
+ *
+ * Returns an empty array if the file does not exist. Malformed lines (e.g.
+ * caused by a partial write) are silently skipped.
+ *
+ * @param cwd - The project working directory.
+ */
+export async function readSession(cwd) {
+    let raw;
+    try {
+        raw = await readFile(getSessionFile(cwd), 'utf8');
+    }
+    catch (err) {
+        const nodeErr = err;
+        if (nodeErr.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const entries = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=session.js.map

package/dist/infra/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/infra/session.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAiC;IACnE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC;IAEzB,OAAO;QACL,EAAE;QAEF,KAAK,CAAC,MAAM,CAAC,KAAmB;YAC9B,MAAM,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,MAAM,iBAAiB,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAiB,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/interface/render.d.ts

@@ -0,0 +1,27 @@
+/**
+ * src/interface/render.ts — Human-readable event stream renderer.
+ *
+ * Consumes the AsyncIterable<CoreEvent> produced by orchestrate() and writes
+ * a clean, truthful transcript to an OutputSink. All displayed values come
+ * directly from CoreEvent data — no fabricated metrics, no hardcoded strings.
+ *
+ * Honesty Contract: confidence is rendered as a computed percentage or the
+ * literal word "unrated" when null. No digit-% literals appear in this file.
+ */
+import type { CoreEvent } from '../core/types.js';
+export interface OutputSink {
+    write(s: string): void;
+    readonly color: boolean;
+    readonly isTty: boolean;
+}
+/**
+ * Iterate events from orchestrate() and write a human-readable, truthful
+ * transcript to the OutputSink. Returns the success flag and the final event
+ * once the stream is exhausted.
+ */
+export declare function renderStream(events: AsyncIterable<CoreEvent>, out: OutputSink): Promise<{
+    success: boolean;
+    final?: Extract<CoreEvent, {
+        type: 'final';
+    }>;
+}>;