@kakedashi/paylog 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# paylog
+
+CLI tool to view your [MPP](https://mpp.dev) spending history, powered by [paylog.dev](https://paylog.dev).
+
+## Usage
+
+```bash
+npx paylog report --days 7
+npx paylog report --days 30 --enrich
+npx paylog wallet
+npx paylog balance
+```
+
+## Commands
+
+### `paylog report`
+
+Show a spending report for your Tempo wallet.
+
+```
+Options:
+  -d, --days <n>      Past N days (default: 7)
+  --from <date>       Start date YYYY-MM-DD
+  --to <date>         End date YYYY-MM-DD
+  --wallet <address>  Override auto-detected wallet
+  --enrich            Enrich Locus payments using local history
+```
+
+The `--enrich` flag reads your shell history and Claude Code chat logs to identify which Locus MPP services you used, since all Locus services share a single on-chain recipient address.
+
+### `paylog wallet`
+
+Display the auto-detected wallet address and its source.
+
+### `paylog balance`
+
+Run `tempo wallet whoami` (requires the [Tempo CLI](https://tempo.xyz)).
+
+## Wallet Auto-Detection
+
+The wallet address is resolved in this order:
+
+1. `~/.agentcash/wallet.json` → `address` field
+2. `~/.mppx/wallet.json` → `address` field
+3. `~/.tempo/wallet/keys.toml` → `wallet_address` field
+4. `--wallet 0x...` option
+
+## `--enrich` Details
+
+Locus routes 40+ services through a single on-chain recipient (`0x060b0fb0...`), making them indistinguishable from on-chain data alone. The `--enrich` flag uses local history to estimate which service was used:
+
+**History sources scanned:**
+- `~/.zsh_history` (with timestamps)
+- `~/.bash_history`
+- `~/.local/share/fish/fish_history`
+- `~/.claude/projects/*/chat.jsonl`
+
+**Matching logic:**
+
+| Confidence | Condition |
+|-----------|-----------|
+| High      | Timestamp matches within ±30 seconds |
+| Medium    | Timestamp matches within ±60 seconds + price match |
+| Low       | Price match only |
+
+**Example output:**
+```
+  Locus (paywithlocus.com)    $0.048   4 txns
+      ┌─ Locus内訳 (ローカル履歴より推定) ─────────────────
+      │ ✓ Brave             $0.010  1件  信頼度：高
+      │ ✓ Perplexity        $0.010  1件  信頼度：高
+      │ ? Deepseek          $0.020  1件  信頼度：中
+      └─ ※ ローカル履歴との照合による推定 ──────────────
+```
+
+## Cost
+
+Reports cost **$0.001 USDC** per call via MPP (Tempo chain). Your wallet must be funded.
+
+## License
+
+MIT

package/bin/paylog.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveWallet } from '../src/wallet.js';
+import { fetchReport } from '../src/api.js';
+import { enrichLocusPayments } from '../src/enrich.js';
+import { printReport, printWallet, printError } from '../src/format.js';
+const program = new Command();
+program
+    .name('paylog')
+    .description('View your MPP spending history from paylog.dev')
+    .version('0.1.0');
+// ---------------------------------------------------------------------------
+// paylog report
+// ---------------------------------------------------------------------------
+program
+    .command('report')
+    .description('Show spending report for your Tempo wallet')
+    .option('-d, --days <n>', 'Number of past days to include', '7')
+    .option('--from <date>', 'Start date (YYYY-MM-DD)')
+    .option('--to <date>', 'End date (YYYY-MM-DD)')
+    .option('--wallet <address>', 'Wallet address (overrides auto-detection)')
+    .option('--enrich', 'Enrich Locus payments using local shell/Claude history', false)
+    .action(async (opts) => {
+    // Resolve wallet
+    let wallet;
+    try {
+        wallet = resolveWallet(opts.wallet);
+    }
+    catch (err) {
+        printError(err.message);
+        process.exit(1);
+    }
+    if (!wallet) {
+        printError('No wallet found. Provide one via --wallet, or set up a Tempo/mppx/agentcash wallet.');
+        process.exit(1);
+    }
+    // Resolve date range
+    const toDate = opts.to ?? new Date().toISOString().slice(0, 10);
+    let fromDate;
+    if (opts.from) {
+        fromDate = opts.from;
+    }
+    else {
+        const days = parseInt(opts.days, 10);
+        if (isNaN(days) || days < 1) {
+            printError('--days must be a positive integer');
+            process.exit(1);
+        }
+        const d = new Date();
+        d.setUTCDate(d.getUTCDate() - days);
+        fromDate = d.toISOString().slice(0, 10);
+    }
+    // Fetch report
+    let report;
+    try {
+        report = await fetchReport(wallet, fromDate, toDate, opts.enrich);
+    }
+    catch (err) {
+        printError(err.message);
+        process.exit(1);
+    }
+    // Optionally enrich Locus payments
+    const enrich = opts.enrich ? enrichLocusPayments(report) : undefined;
+    printReport(report, enrich);
+});
+// ---------------------------------------------------------------------------
+// paylog wallet
+// ---------------------------------------------------------------------------
+program
+    .command('wallet')
+    .description('Show the detected wallet address')
+    .option('--wallet <address>', 'Wallet address (overrides auto-detection)')
+    .action((opts) => {
+    const home = homedir();
+    const sources = [
+        { path: join(home, '.agentcash', 'wallet.json'), label: '~/.agentcash/wallet.json' },
+        { path: join(home, '.mppx', 'wallet.json'), label: '~/.mppx/wallet.json' },
+        { path: join(home, '.tempo', 'wallet', 'keys.toml'), label: '~/.tempo/wallet/keys.toml' },
+    ];
+    if (opts.wallet) {
+        try {
+            const addr = resolveWallet(opts.wallet);
+            printWallet(addr, '--wallet option');
+        }
+        catch (err) {
+            printError(err.message);
+            process.exit(1);
+        }
+        return;
+    }
+    let foundSource = 'auto-detected';
+    for (const src of sources) {
+        if (existsSync(src.path)) {
+            foundSource = src.label;
+            break;
+        }
+    }
+    const wallet = resolveWallet();
+    if (wallet) {
+        printWallet(wallet, foundSource);
+        return;
+    }
+    printError('No wallet found. Try:\n' +
+        '  ~/.agentcash/wallet.json   { "address": "0x..." }\n' +
+        '  ~/.mppx/wallet.json        { "address": "0x..." }\n' +
+        '  ~/.tempo/wallet/keys.toml  wallet_address = "0x..."\n' +
+        '  paylog wallet --wallet 0x...');
+    process.exit(1);
+});
+// ---------------------------------------------------------------------------
+// paylog balance
+// ---------------------------------------------------------------------------
+program
+    .command('balance')
+    .description('Show Tempo wallet balance (requires tempo CLI)')
+    .action(() => {
+    const result = spawnSync('tempo', ['wallet', 'whoami'], { stdio: 'inherit' });
+    if (result.error) {
+        printError('Could not run `tempo wallet whoami`. Is the tempo CLI installed?');
+        process.exit(1);
+    }
+    process.exit(result.status ?? 0);
+});
+program.parse();

package/bin/paylog.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { resolveWallet } from '../src/wallet.js'
+import { fetchReport } from '../src/api.js'
+import { enrichLocusPayments } from '../src/enrich.js'
+import { printReport, printWallet, printError } from '../src/format.js'
+
+const program = new Command()
+
+program
+  .name('paylog')
+  .description('View your MPP spending history from paylog.dev')
+  .version('0.1.0')
+
+// ---------------------------------------------------------------------------
+// paylog report
+// ---------------------------------------------------------------------------
+program
+  .command('report')
+  .description('Show spending report for your Tempo wallet')
+  .option('-d, --days <n>', 'Number of past days to include', '7')
+  .option('--from <date>', 'Start date (YYYY-MM-DD)')
+  .option('--to <date>', 'End date (YYYY-MM-DD)')
+  .option('--wallet <address>', 'Wallet address (overrides auto-detection)')
+  .option('--enrich', 'Enrich Locus payments using local shell/Claude history', false)
+  .action(async (opts) => {
+    // Resolve wallet
+    let wallet: string | null
+    try {
+      wallet = resolveWallet(opts.wallet as string | undefined)
+    } catch (err: unknown) {
+      printError((err as Error).message)
+      process.exit(1)
+    }
+    if (!wallet) {
+      printError(
+        'No wallet found. Provide one via --wallet, or set up a Tempo/mppx/agentcash wallet.',
+      )
+      process.exit(1)
+    }
+
+    // Resolve date range
+    const toDate = (opts.to as string | undefined) ?? new Date().toISOString().slice(0, 10)
+    let fromDate: string
+    if (opts.from) {
+      fromDate = opts.from as string
+    } else {
+      const days = parseInt(opts.days as string, 10)
+      if (isNaN(days) || days < 1) {
+        printError('--days must be a positive integer')
+        process.exit(1)
+      }
+      const d = new Date()
+      d.setUTCDate(d.getUTCDate() - days)
+      fromDate = d.toISOString().slice(0, 10)
+    }
+
+    // Fetch report
+    let report
+    try {
+      report = await fetchReport(wallet, fromDate, toDate, opts.enrich as boolean)
+    } catch (err: unknown) {
+      printError((err as Error).message)
+      process.exit(1)
+    }
+
+    // Optionally enrich Locus payments
+    const enrich = (opts.enrich as boolean) ? enrichLocusPayments(report) : undefined
+
+    printReport(report, enrich)
+  })
+
+// ---------------------------------------------------------------------------
+// paylog wallet
+// ---------------------------------------------------------------------------
+program
+  .command('wallet')
+  .description('Show the detected wallet address')
+  .option('--wallet <address>', 'Wallet address (overrides auto-detection)')
+  .action((opts) => {
+    const home = homedir()
+    const sources = [
+      { path: join(home, '.agentcash', 'wallet.json'), label: '~/.agentcash/wallet.json' },
+      { path: join(home, '.mppx', 'wallet.json'),      label: '~/.mppx/wallet.json' },
+      { path: join(home, '.tempo', 'wallet', 'keys.toml'), label: '~/.tempo/wallet/keys.toml' },
+    ]
+
+    if (opts.wallet) {
+      try {
+        const addr = resolveWallet(opts.wallet as string)
+        printWallet(addr!, '--wallet option')
+      } catch (err: unknown) {
+        printError((err as Error).message)
+        process.exit(1)
+      }
+      return
+    }
+
+    let foundSource = 'auto-detected'
+    for (const src of sources) {
+      if (existsSync(src.path)) {
+        foundSource = src.label
+        break
+      }
+    }
+
+    const wallet = resolveWallet()
+    if (wallet) {
+      printWallet(wallet, foundSource)
+      return
+    }
+
+    printError(
+      'No wallet found. Try:\n' +
+      '  ~/.agentcash/wallet.json   { "address": "0x..." }\n' +
+      '  ~/.mppx/wallet.json        { "address": "0x..." }\n' +
+      '  ~/.tempo/wallet/keys.toml  wallet_address = "0x..."\n' +
+      '  paylog wallet --wallet 0x...',
+    )
+    process.exit(1)
+  })
+
+// ---------------------------------------------------------------------------
+// paylog balance
+// ---------------------------------------------------------------------------
+program
+  .command('balance')
+  .description('Show Tempo wallet balance (requires tempo CLI)')
+  .action(() => {
+    const result = spawnSync('tempo', ['wallet', 'whoami'], { stdio: 'inherit' })
+    if (result.error) {
+      printError('Could not run `tempo wallet whoami`. Is the tempo CLI installed?')
+      process.exit(1)
+    }
+    process.exit(result.status ?? 0)
+  })
+
+program.parse()

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kakedashi/paylog",
+  "version": "0.1.0",
+  "description": "CLI tool to view your MPP spending history powered by paylog.dev",
+  "type": "module",
+  "bin": {
+    "paylog": "./bin/paylog.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx bin/paylog.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mpp",
+    "tempo",
+    "usdc",
+    "payments",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,17 @@
+const BASE_URL = 'https://paylog.dev';
+export async function fetchReport(wallet, from, to, resolve = false) {
+    const params = new URLSearchParams({ wallet, from, to });
+    if (resolve)
+        params.set('resolve', 'true');
+    const url = `${BASE_URL}/api/v1/report?${params}`;
+    const res = await fetch(url);
+    if (res.status === 402) {
+        throw new Error('Payment required (402). This API costs $0.001 USDC per call.\n' +
+            'Make sure your Tempo wallet is funded and the mppx client is configured.');
+    }
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`API error ${res.status}: ${body}`);
+    }
+    return res.json();
+}

package/src/api.ts

@@ -0,0 +1,52 @@
+const BASE_URL = 'https://paylog.dev'
+
+export interface ServiceSummary {
+  name: string
+  url: string
+  spent: number
+  txns: number
+}
+
+export interface DailyBreakdown {
+  date: string
+  total_usd: number
+  by_service: ServiceSummary[]
+}
+
+export interface ReportResponse {
+  wallet: string
+  period: { from: string; to: string }
+  total_spent_usd: number
+  service_spent_usd: number
+  by_service: ServiceSummary[]
+  session_deposits: { total_usd: number; txns: number; note: string }
+  network_fees: { total_usd: number; txns: number }
+  other: { total_usd: number; txns: number }
+  daily_breakdown: DailyBreakdown[]
+}
+
+export async function fetchReport(
+  wallet: string,
+  from: string,
+  to: string,
+  resolve = false,
+): Promise<ReportResponse> {
+  const params = new URLSearchParams({ wallet, from, to })
+  if (resolve) params.set('resolve', 'true')
+
+  const url = `${BASE_URL}/api/v1/report?${params}`
+  const res = await fetch(url)
+
+  if (res.status === 402) {
+    throw new Error(
+      'Payment required (402). This API costs $0.001 USDC per call.\n' +
+      'Make sure your Tempo wallet is funded and the mppx client is configured.',
+    )
+  }
+  if (!res.ok) {
+    const body = await res.text()
+    throw new Error(`API error ${res.status}: ${body}`)
+  }
+
+  return res.json() as Promise<ReportResponse>
+}

package/src/enrich.js

@@ -0,0 +1,108 @@
+import { readLocalHistory } from './history.js';
+// Locus gateway address (all Locus MPP services share this)
+const LOCUS_RECIPIENT = '0x060b0fb0be9d90557577b3aee480711067149ff0';
+// ---------------------------------------------------------------------------
+// Block-time → unix seconds estimate
+// (paylog.dev returns daily_breakdown with date; we approximate block timestamp
+//  from the date. In a future version the API could return block timestamps.)
+// ---------------------------------------------------------------------------
+/** Confidence rules:
+ *  high:   |Δt| ≤ 30s
+ *  medium: |Δt| ≤ 60s  AND price within 0.5% of history entry (same endpoint cost)
+ *  low:    price within 2% but timestamp unknown or >60s
+ */
+function calcConfidence(deltaSec, priceMatch) {
+    const absDelta = Math.abs(deltaSec);
+    if (absDelta <= 30)
+        return 'high';
+    if (absDelta <= 60 && priceMatch)
+        return 'medium';
+    return null;
+}
+function extractLocusTxStubs(report) {
+    const stubs = [];
+    for (const day of report.daily_breakdown) {
+        // Find "Locus" service in this day's breakdown
+        // The API returns service named "Locus (paywithlocus.com)"
+        const locusEntry = day.by_service.find(s => s.name.toLowerCase().includes('locus') || s.url.includes('paywithlocus'));
+        if (!locusEntry || locusEntry.txns === 0)
+            continue;
+        stubs.push({
+            date: day.date,
+            amount: locusEntry.spent / locusEntry.txns, // avg per tx
+            txns: locusEntry.txns,
+        });
+    }
+    return stubs;
+}
+/** Date string YYYY-MM-DD → approximate unix timestamp (noon UTC) */
+function dateToNoonUtc(date) {
+    return Math.floor(new Date(`${date}T12:00:00Z`).getTime() / 1000);
+}
+// ---------------------------------------------------------------------------
+// Match history entries to Locus payments
+// ---------------------------------------------------------------------------
+export function enrichLocusPayments(report) {
+    const locusService = report.by_service.find(s => s.name.toLowerCase().includes('locus') || s.url.includes('paywithlocus'));
+    if (!locusService || locusService.txns === 0) {
+        return { total_usd: 0, txns: 0, matched: [], unmatched_txns: 0, unmatched_usd: 0 };
+    }
+    const history = readLocalHistory();
+    const stubs = extractLocusTxStubs(report);
+    const matched = [];
+    let matchedTxns = 0;
+    for (const stub of stubs) {
+        const dayStart = Math.floor(new Date(`${stub.date}T00:00:00Z`).getTime() / 1000);
+        const dayEnd = Math.floor(new Date(`${stub.date}T23:59:59Z`).getTime() / 1000);
+        const noonApprox = dateToNoonUtc(stub.date);
+        // Filter history entries with known timestamps that fall within this day (±1 day buffer)
+        const dayEntries = history.filter(h => h.timestamp > 0 && h.timestamp >= dayStart - 86400 && h.timestamp <= dayEnd + 86400);
+        // Group by service for this day
+        const serviceHits = new Map();
+        for (const entry of dayEntries) {
+            const key = entry.service;
+            if (!serviceHits.has(key))
+                serviceHits.set(key, []);
+            serviceHits.get(key).push(entry);
+        }
+        // For each history service hit, try to match against stub's txns
+        let remainingTxns = stub.txns;
+        for (const [service, entries] of serviceHits) {
+            if (remainingTxns <= 0)
+                break;
+            // Find the closest-in-time entry
+            const closest = entries.reduce((best, e) => {
+                const d = Math.abs(e.timestamp - noonApprox);
+                const bd = Math.abs(best.timestamp - noonApprox);
+                return d < bd ? e : best;
+            });
+            const delta = closest.timestamp - noonApprox;
+            // Price match: within 10% (we only have avg, not per-tx price from API)
+            const priceMatch = true; // can't reliably match price from daily avg
+            const confidence = calcConfidence(delta, priceMatch);
+            if (!confidence)
+                continue;
+            const serviceUrl = new URL(closest.url).hostname;
+            matched.push({
+                timestamp: closest.timestamp,
+                amount: stub.amount,
+                service,
+                serviceUrl,
+                confidence,
+            });
+            matchedTxns++;
+            remainingTxns--;
+        }
+    }
+    const unmatchedTxns = locusService.txns - matchedTxns;
+    const unmatchedUsd = unmatchedTxns > 0
+        ? (locusService.spent / locusService.txns) * unmatchedTxns
+        : 0;
+    return {
+        total_usd: locusService.spent,
+        txns: locusService.txns,
+        matched,
+        unmatched_txns: Math.max(0, unmatchedTxns),
+        unmatched_usd: Math.max(0, unmatchedUsd),
+    };
+}

package/src/enrich.ts

@@ -0,0 +1,158 @@
+import type { ReportResponse, ServiceSummary } from './api.js'
+import { readLocalHistory, type HistoryEntry } from './history.js'
+
+// Locus gateway address (all Locus MPP services share this)
+const LOCUS_RECIPIENT = '0x060b0fb0be9d90557577b3aee480711067149ff0'
+
+export type Confidence = 'high' | 'medium' | 'low'
+
+export interface EnrichedLocusPayment {
+  timestamp: number   // unix seconds (estimated from block)
+  amount: number      // USDC
+  service: string     // matched service name
+  serviceUrl: string  // e.g. brave.mpp.paywithlocus.com
+  confidence: Confidence
+}
+
+export interface EnrichResult {
+  total_usd: number
+  txns: number
+  matched: EnrichedLocusPayment[]
+  unmatched_txns: number
+  unmatched_usd: number
+}
+
+// ---------------------------------------------------------------------------
+// Block-time → unix seconds estimate
+// (paylog.dev returns daily_breakdown with date; we approximate block timestamp
+//  from the date. In a future version the API could return block timestamps.)
+// ---------------------------------------------------------------------------
+
+/** Confidence rules:
+ *  high:   |Δt| ≤ 30s
+ *  medium: |Δt| ≤ 60s  AND price within 0.5% of history entry (same endpoint cost)
+ *  low:    price within 2% but timestamp unknown or >60s
+ */
+function calcConfidence(deltaSec: number, priceMatch: boolean): Confidence | null {
+  const absDelta = Math.abs(deltaSec)
+  if (absDelta <= 30) return 'high'
+  if (absDelta <= 60 && priceMatch) return 'medium'
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// In-memory "Locus payment" extraction from the report
+// The report doesn't include per-tx timestamps yet; we use the daily_breakdown
+// to get approximate block times, then match against history entries.
+// ---------------------------------------------------------------------------
+
+interface LocusTxStub {
+  date: string       // YYYY-MM-DD
+  amount: number     // USDC per tx (approximated as avg)
+  txns: number
+}
+
+function extractLocusTxStubs(report: ReportResponse): LocusTxStub[] {
+  const stubs: LocusTxStub[] = []
+  for (const day of report.daily_breakdown) {
+    // Find "Locus" service in this day's breakdown
+    // The API returns service named "Locus (paywithlocus.com)"
+    const locusEntry = day.by_service.find(
+      s => s.name.toLowerCase().includes('locus') || s.url.includes('paywithlocus'),
+    )
+    if (!locusEntry || locusEntry.txns === 0) continue
+    stubs.push({
+      date: day.date,
+      amount: locusEntry.spent / locusEntry.txns,  // avg per tx
+      txns: locusEntry.txns,
+    })
+  }
+  return stubs
+}
+
+/** Date string YYYY-MM-DD → approximate unix timestamp (noon UTC) */
+function dateToNoonUtc(date: string): number {
+  return Math.floor(new Date(`${date}T12:00:00Z`).getTime() / 1000)
+}
+
+// ---------------------------------------------------------------------------
+// Match history entries to Locus payments
+// ---------------------------------------------------------------------------
+export function enrichLocusPayments(report: ReportResponse): EnrichResult {
+  const locusService = report.by_service.find(
+    s => s.name.toLowerCase().includes('locus') || s.url.includes('paywithlocus'),
+  )
+  if (!locusService || locusService.txns === 0) {
+    return { total_usd: 0, txns: 0, matched: [], unmatched_txns: 0, unmatched_usd: 0 }
+  }
+
+  const history = readLocalHistory()
+  const stubs = extractLocusTxStubs(report)
+
+  const matched: EnrichedLocusPayment[] = []
+  let matchedTxns = 0
+
+  for (const stub of stubs) {
+    const dayStart = Math.floor(new Date(`${stub.date}T00:00:00Z`).getTime() / 1000)
+    const dayEnd   = Math.floor(new Date(`${stub.date}T23:59:59Z`).getTime() / 1000)
+    const noonApprox = dateToNoonUtc(stub.date)
+
+    // Filter history entries with known timestamps that fall within this day (±1 day buffer)
+    const dayEntries = history.filter(
+      h => h.timestamp > 0 && h.timestamp >= dayStart - 86400 && h.timestamp <= dayEnd + 86400,
+    )
+
+    // Group by service for this day
+    const serviceHits = new Map<string, HistoryEntry[]>()
+    for (const entry of dayEntries) {
+      const key = entry.service
+      if (!serviceHits.has(key)) serviceHits.set(key, [])
+      serviceHits.get(key)!.push(entry)
+    }
+
+    // For each history service hit, try to match against stub's txns
+    let remainingTxns = stub.txns
+    for (const [service, entries] of serviceHits) {
+      if (remainingTxns <= 0) break
+
+      // Find the closest-in-time entry
+      const closest = entries.reduce((best, e) => {
+        const d = Math.abs(e.timestamp - noonApprox)
+        const bd = Math.abs(best.timestamp - noonApprox)
+        return d < bd ? e : best
+      })
+
+      const delta = closest.timestamp - noonApprox
+      // Price match: within 10% (we only have avg, not per-tx price from API)
+      const priceMatch = true  // can't reliably match price from daily avg
+
+      const confidence = calcConfidence(delta, priceMatch)
+      if (!confidence) continue
+
+      const serviceUrl = new URL(closest.url).hostname
+
+      matched.push({
+        timestamp: closest.timestamp,
+        amount: stub.amount,
+        service,
+        serviceUrl,
+        confidence,
+      })
+      matchedTxns++
+      remainingTxns--
+    }
+  }
+
+  const unmatchedTxns = locusService.txns - matchedTxns
+  const unmatchedUsd = unmatchedTxns > 0
+    ? (locusService.spent / locusService.txns) * unmatchedTxns
+    : 0
+
+  return {
+    total_usd: locusService.spent,
+    txns: locusService.txns,
+    matched,
+    unmatched_txns: Math.max(0, unmatchedTxns),
+    unmatched_usd: Math.max(0, unmatchedUsd),
+  }
+}

package/src/format.js

@@ -0,0 +1,92 @@
+// ---------------------------------------------------------------------------
+// ANSI helpers
+// ---------------------------------------------------------------------------
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+function usd(n) {
+    return `$${n.toFixed(3)}`;
+}
+// ---------------------------------------------------------------------------
+// Report display
+// ---------------------------------------------------------------------------
+export function printReport(report, enrich) {
+    const { wallet, period, total_spent_usd, service_spent_usd, by_service, session_deposits, network_fees, other } = report;
+    console.log();
+    console.log(bold('MPP Spending Report'));
+    console.log(dim(`Wallet: ${wallet}`));
+    console.log(dim(`Period: ${period.from} → ${period.to}`));
+    console.log();
+    // Total summary
+    console.log(`${bold('Total spent')}     ${bold(usd(total_spent_usd))}`);
+    if (session_deposits.txns > 0) {
+        console.log(`  Session deposits ${usd(session_deposits.total_usd).padStart(8)}  ${dim(`(${session_deposits.txns} txns — ${session_deposits.note})`)}`);
+    }
+    if (network_fees.txns > 0) {
+        console.log(`  Network fees     ${usd(network_fees.total_usd).padStart(8)}  ${dim(`(${network_fees.txns} txns)`)}`);
+    }
+    console.log();
+    // By service
+    if (by_service.length > 0) {
+        console.log(bold('By service:'));
+        const maxName = Math.max(...by_service.map(s => s.name.length), 10);
+        for (const svc of by_service) {
+            const isLocus = svc.name.toLowerCase().includes('locus') || svc.url.includes('paywithlocus');
+            const namePad = svc.name.padEnd(maxName + 2);
+            const line = `  ${cyan(namePad)}${usd(svc.spent).padStart(10)}  ${dim(`${svc.txns} txns`)}`;
+            console.log(line);
+            // If this is Locus and we have enrich data, show the breakdown
+            if (isLocus && enrich && (enrich.matched.length > 0 || enrich.unmatched_txns > 0)) {
+                printEnrichBreakdown(enrich);
+            }
+        }
+    }
+    if (other.txns > 0) {
+        console.log(`  ${'Other'.padEnd(20)}${usd(other.total_usd).padStart(10)}  ${dim(`${other.txns} txns`)}`);
+    }
+    console.log();
+}
+function printEnrichBreakdown(enrich) {
+    console.log(dim(`      ┌─ Locus内訳 (ローカル履歴より推定) ─────────────────`));
+    // Group matched by service
+    const byService = new Map();
+    for (const m of enrich.matched) {
+        const key = m.service;
+        const existing = byService.get(key);
+        if (existing) {
+            existing.amount += m.amount;
+            existing.count++;
+        }
+        else {
+            byService.set(key, { amount: m.amount, count: 1, confidence: m.confidence });
+        }
+    }
+    for (const [service, { amount, count, confidence }] of byService) {
+        const marker = confidence === 'high' ? green('✓') : confidence === 'medium' ? yellow('?') : dim('?');
+        const confLabel = confidence === 'high' ? green('高') : confidence === 'medium' ? yellow('中') : dim('低');
+        const line = `      │ ${marker} ${service.padEnd(16)} ${usd(amount).padStart(8)}  ${dim(`${count}件  信頼度：`)}${confLabel}`;
+        console.log(line);
+    }
+    if (enrich.unmatched_txns > 0) {
+        console.log(dim(`      │ ? 未照合              ${usd(enrich.unmatched_usd).padStart(8)}  ${enrich.unmatched_txns}件`));
+    }
+    console.log(dim(`      └─ ※ ローカル履歴との照合による推定 ──────────────`));
+}
+// ---------------------------------------------------------------------------
+// Wallet display
+// ---------------------------------------------------------------------------
+export function printWallet(wallet, source) {
+    console.log();
+    console.log(bold('Wallet'));
+    console.log(`  Address  ${cyan(wallet)}`);
+    console.log(dim(`  Source   ${source}`));
+    console.log();
+}
+// ---------------------------------------------------------------------------
+// Error display
+// ---------------------------------------------------------------------------
+export function printError(msg) {
+    console.error(`\x1b[31mError:\x1b[0m ${msg}`);
+}

package/src/format.ts

@@ -0,0 +1,114 @@
+import type { ReportResponse } from './api.js'
+import type { EnrichResult } from './enrich.js'
+
+// ---------------------------------------------------------------------------
+// ANSI helpers
+// ---------------------------------------------------------------------------
+const bold  = (s: string) => `\x1b[1m${s}\x1b[0m`
+const dim   = (s: string) => `\x1b[2m${s}\x1b[0m`
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`
+const cyan  = (s: string) => `\x1b[36m${s}\x1b[0m`
+
+function usd(n: number): string {
+  return `$${n.toFixed(3)}`
+}
+
+// ---------------------------------------------------------------------------
+// Report display
+// ---------------------------------------------------------------------------
+export function printReport(
+  report: ReportResponse,
+  enrich?: EnrichResult,
+): void {
+  const { wallet, period, total_spent_usd, service_spent_usd, by_service,
+          session_deposits, network_fees, other } = report
+
+  console.log()
+  console.log(bold('MPP Spending Report'))
+  console.log(dim(`Wallet: ${wallet}`))
+  console.log(dim(`Period: ${period.from} → ${period.to}`))
+  console.log()
+
+  // Total summary
+  console.log(`${bold('Total spent')}     ${bold(usd(total_spent_usd))}`)
+  if (session_deposits.txns > 0) {
+    console.log(`  Session deposits ${usd(session_deposits.total_usd).padStart(8)}  ${dim(`(${session_deposits.txns} txns — ${session_deposits.note})`)}`)
+  }
+  if (network_fees.txns > 0) {
+    console.log(`  Network fees     ${usd(network_fees.total_usd).padStart(8)}  ${dim(`(${network_fees.txns} txns)`)}`)
+  }
+  console.log()
+
+  // By service
+  if (by_service.length > 0) {
+    console.log(bold('By service:'))
+    const maxName = Math.max(...by_service.map(s => s.name.length), 10)
+
+    for (const svc of by_service) {
+      const isLocus = svc.name.toLowerCase().includes('locus') || svc.url.includes('paywithlocus')
+
+      const namePad = svc.name.padEnd(maxName + 2)
+      const line = `  ${cyan(namePad)}${usd(svc.spent).padStart(10)}  ${dim(`${svc.txns} txns`)}`
+      console.log(line)
+
+      // If this is Locus and we have enrich data, show the breakdown
+      if (isLocus && enrich && (enrich.matched.length > 0 || enrich.unmatched_txns > 0)) {
+        printEnrichBreakdown(enrich)
+      }
+    }
+  }
+
+  if (other.txns > 0) {
+    console.log(`  ${'Other'.padEnd(20)}${usd(other.total_usd).padStart(10)}  ${dim(`${other.txns} txns`)}`)
+  }
+  console.log()
+}
+
+function printEnrichBreakdown(enrich: EnrichResult): void {
+  console.log(dim(`      ┌─ Locus内訳 (ローカル履歴より推定) ─────────────────`))
+
+  // Group matched by service
+  const byService = new Map<string, { amount: number; count: number; confidence: string }>()
+  for (const m of enrich.matched) {
+    const key = m.service
+    const existing = byService.get(key)
+    if (existing) {
+      existing.amount += m.amount
+      existing.count++
+    } else {
+      byService.set(key, { amount: m.amount, count: 1, confidence: m.confidence })
+    }
+  }
+
+  for (const [service, { amount, count, confidence }] of byService) {
+    const marker = confidence === 'high' ? green('✓') : confidence === 'medium' ? yellow('?') : dim('?')
+    const confLabel = confidence === 'high' ? green('高') : confidence === 'medium' ? yellow('中') : dim('低')
+    const line = `      │ ${marker} ${service.padEnd(16)} ${usd(amount).padStart(8)}  ${dim(`${count}件  信頼度：`)}${confLabel}`
+    console.log(line)
+  }
+
+  if (enrich.unmatched_txns > 0) {
+    console.log(dim(`      │ ? 未照合              ${usd(enrich.unmatched_usd).padStart(8)}  ${enrich.unmatched_txns}件`))
+  }
+
+  console.log(dim(`      └─ ※ ローカル履歴との照合による推定 ──────────────`))
+}
+
+// ---------------------------------------------------------------------------
+// Wallet display
+// ---------------------------------------------------------------------------
+export function printWallet(wallet: string, source: string): void {
+  console.log()
+  console.log(bold('Wallet'))
+  console.log(`  Address  ${cyan(wallet)}`)
+  console.log(dim(`  Source   ${source}`))
+  console.log()
+}
+
+// ---------------------------------------------------------------------------
+// Error display
+// ---------------------------------------------------------------------------
+export function printError(msg: string): void {
+  console.error(`\x1b[31mError:\x1b[0m ${msg}`)
+}

package/src/history.js

@@ -0,0 +1,131 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const LOCUS_PATTERN = /paywithlocus\.com/;
+// ---------------------------------------------------------------------------
+// zsh_history  format: ": 1742817152:0;command"
+// ---------------------------------------------------------------------------
+function parseZshHistory(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        const m = line.match(/^:\s*(\d+):\d+;(.+)/);
+        if (!m)
+            continue;
+        const ts = parseInt(m[1], 10);
+        for (const url of extractLocusUrls(m[2])) {
+            entries.push({ timestamp: ts, url, service: urlToService(url), source: 'zsh' });
+        }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// bash_history  (no timestamps by default)
+// ---------------------------------------------------------------------------
+function parseBashHistory(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        for (const url of extractLocusUrls(line)) {
+            entries.push({ timestamp: 0, url, service: urlToService(url), source: 'bash' });
+        }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// fish_history  format: "- cmd: ...\n  when: 1742817152"
+// ---------------------------------------------------------------------------
+function parseFishHistory(text) {
+    const entries = [];
+    for (const block of text.split(/^- cmd:/m).slice(1)) {
+        const whenMatch = block.match(/when:\s*(\d+)/);
+        const ts = whenMatch ? parseInt(whenMatch[1], 10) : 0;
+        for (const url of extractLocusUrls(block.split('\n')[0])) {
+            entries.push({ timestamp: ts, url, service: urlToService(url), source: 'fish' });
+        }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Claude Code  ~/.claude/projects/*/chat.jsonl
+// Each line is a JSON message object with optional timestamp field
+// ---------------------------------------------------------------------------
+function parseClaudeJsonl(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim() || !LOCUS_PATTERN.test(line))
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            const ts = obj.timestamp
+                ? Math.floor(new Date(obj.timestamp).getTime() / 1000)
+                : 0;
+            for (const url of extractLocusUrls(JSON.stringify(obj))) {
+                entries.push({ timestamp: ts, url, service: urlToService(url), source: 'claude' });
+            }
+        }
+        catch { /* malformed line */ }
+    }
+    return entries;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractLocusUrls(text) {
+    const results = [];
+    for (const m of text.matchAll(/https?:\/\/([a-z0-9-]+\.mpp\.paywithlocus\.com[^\s"'`>\]]*)/gi)) {
+        results.push(m[0]);
+    }
+    return results;
+}
+function urlToService(url) {
+    try {
+        const hostname = new URL(url).hostname; // e.g. brave.mpp.paywithlocus.com
+        const sub = hostname.split('.')[0]; // e.g. "brave"
+        return sub.charAt(0).toUpperCase() + sub.slice(1);
+    }
+    catch {
+        return 'Unknown';
+    }
+}
+function tryRead(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export function readLocalHistory() {
+    const home = homedir();
+    const entries = [];
+    // zsh
+    const zsh = tryRead(join(home, '.zsh_history'));
+    if (zsh)
+        entries.push(...parseZshHistory(zsh));
+    // bash
+    const bash = tryRead(join(home, '.bash_history'));
+    if (bash)
+        entries.push(...parseBashHistory(bash));
+    // fish
+    const fish = tryRead(join(home, '.local', 'share', 'fish', 'fish_history'));
+    if (fish)
+        entries.push(...parseFishHistory(fish));
+    // Claude Code chat.jsonl — scan ~/.claude/projects/*/chat.jsonl
+    const claudeProjects = join(home, '.claude', 'projects');
+    if (existsSync(claudeProjects)) {
+        try {
+            for (const projectDir of readdirSync(claudeProjects)) {
+                const jsonlPath = join(claudeProjects, projectDir, 'chat.jsonl');
+                const content = tryRead(jsonlPath);
+                if (content)
+                    entries.push(...parseClaudeJsonl(content));
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return entries;
+}

package/src/history.ts

@@ -0,0 +1,137 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const LOCUS_PATTERN = /paywithlocus\.com/
+
+export interface HistoryEntry {
+  timestamp: number  // unix seconds (0 = unknown)
+  url: string        // full matched URL
+  service: string    // e.g. "Brave" from brave.mpp.paywithlocus.com
+  source: string     // 'zsh' | 'bash' | 'fish' | 'claude'
+}
+
+// ---------------------------------------------------------------------------
+// zsh_history  format: ": 1742817152:0;command"
+// ---------------------------------------------------------------------------
+function parseZshHistory(text: string): HistoryEntry[] {
+  const entries: HistoryEntry[] = []
+  for (const line of text.split('\n')) {
+    const m = line.match(/^:\s*(\d+):\d+;(.+)/)
+    if (!m) continue
+    const ts = parseInt(m[1], 10)
+    for (const url of extractLocusUrls(m[2])) {
+      entries.push({ timestamp: ts, url, service: urlToService(url), source: 'zsh' })
+    }
+  }
+  return entries
+}
+
+// ---------------------------------------------------------------------------
+// bash_history  (no timestamps by default)
+// ---------------------------------------------------------------------------
+function parseBashHistory(text: string): HistoryEntry[] {
+  const entries: HistoryEntry[] = []
+  for (const line of text.split('\n')) {
+    for (const url of extractLocusUrls(line)) {
+      entries.push({ timestamp: 0, url, service: urlToService(url), source: 'bash' })
+    }
+  }
+  return entries
+}
+
+// ---------------------------------------------------------------------------
+// fish_history  format: "- cmd: ...\n  when: 1742817152"
+// ---------------------------------------------------------------------------
+function parseFishHistory(text: string): HistoryEntry[] {
+  const entries: HistoryEntry[] = []
+  for (const block of text.split(/^- cmd:/m).slice(1)) {
+    const whenMatch = block.match(/when:\s*(\d+)/)
+    const ts = whenMatch ? parseInt(whenMatch[1], 10) : 0
+    for (const url of extractLocusUrls(block.split('\n')[0])) {
+      entries.push({ timestamp: ts, url, service: urlToService(url), source: 'fish' })
+    }
+  }
+  return entries
+}
+
+// ---------------------------------------------------------------------------
+// Claude Code  ~/.claude/projects/*/chat.jsonl
+// Each line is a JSON message object with optional timestamp field
+// ---------------------------------------------------------------------------
+function parseClaudeJsonl(text: string): HistoryEntry[] {
+  const entries: HistoryEntry[] = []
+  for (const line of text.split('\n')) {
+    if (!line.trim() || !LOCUS_PATTERN.test(line)) continue
+    try {
+      const obj = JSON.parse(line)
+      const ts = obj.timestamp
+        ? Math.floor(new Date(obj.timestamp as string).getTime() / 1000)
+        : 0
+      for (const url of extractLocusUrls(JSON.stringify(obj))) {
+        entries.push({ timestamp: ts, url, service: urlToService(url), source: 'claude' })
+      }
+    } catch { /* malformed line */ }
+  }
+  return entries
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function extractLocusUrls(text: string): string[] {
+  const results: string[] = []
+  for (const m of text.matchAll(/https?:\/\/([a-z0-9-]+\.mpp\.paywithlocus\.com[^\s"'`>\]]*)/gi)) {
+    results.push(m[0])
+  }
+  return results
+}
+
+function urlToService(url: string): string {
+  try {
+    const hostname = new URL(url).hostname   // e.g. brave.mpp.paywithlocus.com
+    const sub = hostname.split('.')[0]        // e.g. "brave"
+    return sub.charAt(0).toUpperCase() + sub.slice(1)
+  } catch {
+    return 'Unknown'
+  }
+}
+
+function tryRead(path: string): string | null {
+  if (!existsSync(path)) return null
+  try { return readFileSync(path, 'utf8') } catch { return null }
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+export function readLocalHistory(): HistoryEntry[] {
+  const home = homedir()
+  const entries: HistoryEntry[] = []
+
+  // zsh
+  const zsh = tryRead(join(home, '.zsh_history'))
+  if (zsh) entries.push(...parseZshHistory(zsh))
+
+  // bash
+  const bash = tryRead(join(home, '.bash_history'))
+  if (bash) entries.push(...parseBashHistory(bash))
+
+  // fish
+  const fish = tryRead(join(home, '.local', 'share', 'fish', 'fish_history'))
+  if (fish) entries.push(...parseFishHistory(fish))
+
+  // Claude Code chat.jsonl — scan ~/.claude/projects/*/chat.jsonl
+  const claudeProjects = join(home, '.claude', 'projects')
+  if (existsSync(claudeProjects)) {
+    try {
+      for (const projectDir of readdirSync(claudeProjects)) {
+        const jsonlPath = join(claudeProjects, projectDir, 'chat.jsonl')
+        const content = tryRead(jsonlPath)
+        if (content) entries.push(...parseClaudeJsonl(content))
+      }
+    } catch { /* ignore */ }
+  }
+
+  return entries
+}

package/src/wallet.js

@@ -0,0 +1,53 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+function tryReadJson(filePath, field) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(filePath, 'utf8'));
+        const val = data[field];
+        if (typeof val === 'string' && /^0x[0-9a-fA-F]{40}$/.test(val))
+            return val.toLowerCase();
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+function tryReadToml(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const text = readFileSync(filePath, 'utf8');
+        const match = text.match(/wallet_address\s*=\s*["']?(0x[0-9a-fA-F]{40})["']?/);
+        if (match)
+            return match[1].toLowerCase();
+    }
+    catch {
+        // ignore
+    }
+    return null;
+}
+export function resolveWallet(explicit) {
+    if (explicit) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(explicit)) {
+            throw new Error(`Invalid wallet address: ${explicit}`);
+        }
+        return explicit.toLowerCase();
+    }
+    const home = homedir();
+    // 1. ~/.agentcash/wallet.json
+    const agentcash = tryReadJson(join(home, '.agentcash', 'wallet.json'), 'address');
+    if (agentcash)
+        return agentcash;
+    // 2. ~/.mppx/wallet.json
+    const mppx = tryReadJson(join(home, '.mppx', 'wallet.json'), 'address');
+    if (mppx)
+        return mppx;
+    // 3. ~/.tempo/wallet/keys.toml
+    const tempo = tryReadToml(join(home, '.tempo', 'wallet', 'keys.toml'));
+    if (tempo)
+        return tempo;
+    return null;
+}

package/src/wallet.ts

@@ -0,0 +1,52 @@
+import { readFileSync, existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+function tryReadJson(filePath: string, field: string): string | null {
+  if (!existsSync(filePath)) return null
+  try {
+    const data = JSON.parse(readFileSync(filePath, 'utf8'))
+    const val = data[field]
+    if (typeof val === 'string' && /^0x[0-9a-fA-F]{40}$/.test(val)) return val.toLowerCase()
+  } catch {
+    // ignore
+  }
+  return null
+}
+
+function tryReadToml(filePath: string): string | null {
+  if (!existsSync(filePath)) return null
+  try {
+    const text = readFileSync(filePath, 'utf8')
+    const match = text.match(/wallet_address\s*=\s*["']?(0x[0-9a-fA-F]{40})["']?/)
+    if (match) return match[1].toLowerCase()
+  } catch {
+    // ignore
+  }
+  return null
+}
+
+export function resolveWallet(explicit?: string): string | null {
+  if (explicit) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(explicit)) {
+      throw new Error(`Invalid wallet address: ${explicit}`)
+    }
+    return explicit.toLowerCase()
+  }
+
+  const home = homedir()
+
+  // 1. ~/.agentcash/wallet.json
+  const agentcash = tryReadJson(join(home, '.agentcash', 'wallet.json'), 'address')
+  if (agentcash) return agentcash
+
+  // 2. ~/.mppx/wallet.json
+  const mppx = tryReadJson(join(home, '.mppx', 'wallet.json'), 'address')
+  if (mppx) return mppx
+
+  // 3. ~/.tempo/wallet/keys.toml
+  const tempo = tryReadToml(join(home, '.tempo', 'wallet', 'keys.toml'))
+  if (tempo) return tempo
+
+  return null
+}