pi-harness-runtime 0.2.0

package/mirror.ts

@@ -0,0 +1,87 @@
+/**
+ * MirrorStore — manual sync of provider-side quota from console.
+ *
+ * User periodically glances at https://platform.minimax.io/console/usage
+ * and runs `/usage sync` to enter:
+ *   - 5h used %
+ *   - 5h resets in (h, m)
+ *   - weekly used %
+ *   - weekly resets in (d, h)
+ *
+ * This is the "ground truth" since most providers (MiniMax, Anthropic, OpenAI)
+ * don't expose rate limit headers publicly. Local tracking counts OUR usage
+ * only; the mirror counts TOTAL quota usage across all clients.
+ *
+ * File: ~/.pi/usage-status/mirror.json
+ */
+
+import {
+	getMirrorPath,
+	readJson,
+	writeJson,
+} from "./cli.ts";
+
+export interface MirrorRecord {
+	synced_at: string;           // ISO 8601 UTC
+	provider: string;            // e.g. "minimax"
+	model?: string;              // optional, e.g. "minimax/MiniMax-M3"
+	h5_used_pct?: number;        // 0-100
+	h5_resets_at?: string;       // ISO 8601 UTC — provider-reported
+	weekly_used_pct?: number;    // 0-100
+	weekly_resets_at?: string;   // ISO 8601 UTC — provider-reported
+}
+
+const STALE_WARN_MS = 30 * 60 * 1000;   // 30 min → orange
+const STALE_ERROR_MS = 2 * 60 * 60 * 1000;  // 2 h   → red
+
+export class MirrorStore {
+	private path: string;
+
+	constructor(path: string = getMirrorPath()) {
+		this.path = path;
+	}
+
+	/** Read the mirror record. Returns null if missing/corrupted. */
+	read(): MirrorRecord | null {
+		const raw = readJson(this.path);
+		if (!raw || typeof raw !== "object") return null;
+		return raw as MirrorRecord;
+	}
+
+	/** Write a new mirror record (overwrites). */
+	write(record: MirrorRecord): void {
+		writeJson(this.path, record);
+	}
+
+	/** Returns "fresh" | "stale" | "expired" based on age. */
+	freshness(record: MirrorRecord | null, nowMs: number): "fresh" | "stale" | "expired" | "missing" {
+		if (!record || !record.synced_at) return "missing";
+		const syncedMs = Date.parse(record.synced_at);
+		if (isNaN(syncedMs)) return "missing";
+		const ageMs = nowMs - syncedMs;
+		if (ageMs < STALE_WARN_MS) return "fresh";
+		if (ageMs < STALE_ERROR_MS) return "stale";
+		return "expired";
+	}
+
+	/** True if data is too stale to trust (> 2 hours old). */
+	isExpired(record: MirrorRecord | null, nowMs: number): boolean {
+		return this.freshness(record, nowMs) === "expired";
+	}
+
+	/** Convenience: human-readable age like "5 min ago" or "1 d 2 h ago". */
+	ageString(record: MirrorRecord | null, nowMs: number): string {
+		if (!record || !record.synced_at) return "never";
+		const syncedMs = Date.parse(record.synced_at);
+		if (isNaN(syncedMs)) return "unknown";
+		const delta = nowMs - syncedMs;
+		const sec = Math.floor(delta / 1000);
+		if (sec < 60) return `${sec}s ago`;
+		const min = Math.floor(sec / 60);
+		if (min < 60) return `${min} min ago`;
+		const hr = Math.floor(min / 60);
+		if (hr < 24) return `${hr} h ago`;
+		const day = Math.floor(hr / 24);
+		return `${day} d ago`;
+	}
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "pi-harness-runtime",
+  "version": "0.2.0",
+  "description": "Codex-style /usage status for pi: local token tracking + provider mirror",
+  "type": "module",
+  "scripts": {
+    "test": "node --test",
+    "release": "standard-version",
+    "release:patch": "standard-version --release-as patch",
+    "release:minor": "standard-version --release-as minor",
+    "release:major": "standard-version --release-as major",
+    "release:dry-run": "standard-version --dry-run"
+  },
+  "files": [
+    "index.ts",
+    "tracker.ts",
+    "mirror.ts",
+    "windows.ts",
+    "renderer.ts",
+    "sync-form.ts",
+    "cli.ts",
+    "skills",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "usage",
+    "tokens",
+    "cost",
+    "codex"
+  ],
+  "author": "MooCoding",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ManotLuijiu/pi-harness-runtime.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ManotLuijiu/pi-harness-runtime/issues"
+  },
+  "homepage": "https://github.com/ManotLuijiu/pi-harness-runtime#readme",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "standard-version": "^9.5.0"
+  }
+}

package/renderer.ts

@@ -0,0 +1,170 @@
+/**
+ * StatusRenderer — Codex-style output formatting.
+ *
+ * Produces the same visual style as Codex's `/status`:
+ *   5h limit:     [████████░░░░░░░░░░░░] 18% left (resets in 4h 56m)
+ *   Weekly limit: [████████████████░░░░] 81% left (resets in 2d 13h)
+ *
+ * We render with plain text (no TUI dependency) so it's testable with
+ * node --test and works in `ctx.ui.notify()`.
+ */
+
+import { formatDuration, formatRelative, formatTokens, formatUsd } from "./cli.ts";
+import type { AggregatedWindows } from "./windows.ts";
+import { FIVE_HOURS_MS, SEVEN_DAYS_MS, computeLocalResetTime } from "./windows.ts";
+import type { MirrorRecord } from "./mirror.ts";
+import type { MirrorStore } from "./mirror.ts";
+
+const BAR_WIDTH = 20;
+const FILLED = "█";
+const EMPTY = "░";
+
+export interface RenderInput {
+	model: string | null;
+	cwd: string;
+	local: AggregatedWindows;
+	mirror: MirrorRecord | null;
+	mirrorStore: MirrorStore;        // for freshness check
+	nowMs: number;
+	// Optional: local usage limit configuration (for "X% of limit used")
+	localFiveHLimitTokens?: number;
+	localWeeklyLimitTokens?: number;
+}
+
+export function renderProgressBar(pct: number, width: number = BAR_WIDTH): string {
+	const clamped = Math.max(0, Math.min(100, pct));
+	const filledCount = Math.round((clamped / 100) * width);
+	const emptyCount = width - filledCount;
+	return "[" + FILLED.repeat(filledCount) + EMPTY.repeat(emptyCount) + "]";
+}
+
+/** Render the "18% left" style label (what's REMAINING, like Codex). */
+function renderLeftLabel(pct: number): string {
+	const left = Math.max(0, Math.min(100, 100 - pct));
+	return `${left.toFixed(0)}% left`;
+}
+
+/** Render the full status block. */
+export function renderStatus(input: RenderInput): string {
+	const lines: string[] = [];
+	const divider = "─".repeat(64);
+
+	// ─── Header ──────────────────────────────────────────────────────────
+	lines.push("Codex-style usage status for pi");
+	lines.push(divider);
+	lines.push(` Model:        ${input.model ?? "unknown"}`);
+	lines.push(` Directory:    ${input.cwd}`);
+	lines.push("");
+
+	// ─── Local tracking ─────────────────────────────────────────────────
+	lines.push(" ① LOCAL TRACKED (ground truth — we count this)");
+	lines.push(
+		`    This session:   ${formatUsd(input.local.lifetime.cost)} · ${formatTokens(input.local.lifetime.tokens)} tokens · ${input.local.lifetime.requests} requests`,
+	);
+	lines.push(
+		`    This 5h:        ${formatTokens(input.local.five_h.tokens)} tokens · ${input.local.five_h.requests} requests · ${formatUsd(input.local.five_h.cost)}`,
+	);
+	lines.push(
+		`    This week:      ${formatTokens(input.local.weekly.tokens)} tokens · ${input.local.weekly.requests} requests · ${formatUsd(input.local.weekly.cost)}`,
+	);
+	lines.push(
+		`    Lifetime:       ${input.local.lifetime.requests} requests · ${formatUsd(input.local.lifetime.cost)}`,
+	);
+	lines.push("");
+
+	// ─── Provider mirror ─────────────────────────────────────────────────
+	if (input.mirror) {
+		const fresh = input.mirrorStore.freshness(input.mirror, input.nowMs);
+		const freshnessLabel = fresh === "fresh" ? "fresh" : fresh === "stale" ? "stale" : fresh === "expired" ? "EXPIRED" : "missing";
+		lines.push(` ② PROVIDER MIRROR (you enter from console.minimax.io)`);
+		lines.push(`    Last sync:      ${formatRelative(input.mirror.synced_at, input.nowMs)} [${freshnessLabel}]`);
+		lines.push(`    Provider:       ${input.mirror.provider ?? "unknown"}`);
+
+		// 5h line
+		if (input.mirror.h5_used_pct !== undefined) {
+			const pct = input.mirror.h5_used_pct;
+			const resetStr = input.mirror.h5_resets_at
+				? formatDuration(Date.parse(input.mirror.h5_resets_at) - input.nowMs)
+				: "unknown";
+			lines.push(
+				`    5h limit:       ${renderProgressBar(pct)} ${renderLeftLabel(pct)} (resets in ${resetStr})`,
+			);
+		} else {
+			lines.push(`    5h limit:       (not yet synced — run /usage sync)`);
+		}
+
+		// Weekly line
+		if (input.mirror.weekly_used_pct !== undefined) {
+			const pct = input.mirror.weekly_used_pct;
+			const resetStr = input.mirror.weekly_resets_at
+				? formatDuration(Date.parse(input.mirror.weekly_resets_at) - input.nowMs)
+				: "unknown";
+			lines.push(
+				`    Weekly limit:   ${renderProgressBar(pct)} ${renderLeftLabel(pct)} (resets in ${resetStr})`,
+			);
+		} else {
+			lines.push(`    Weekly limit:   (not yet synced — run /usage sync)`);
+		}
+		lines.push("");
+	} else {
+		lines.push(` ② PROVIDER MIRROR`);
+		lines.push(`    Not synced yet. Run /usage sync to mirror from console.minimax.io.`);
+		lines.push("");
+	}
+
+	// ─── Local reset times (derived) ────────────────────────────────────
+	lines.push(" ③ LOCAL RESET TIMES (derived from your data)");
+	const local5hReset = computeLocalResetTime(input.local.five_h, FIVE_HOURS_MS);
+	const localWeekReset = computeLocalResetTime(input.local.weekly, SEVEN_DAYS_MS);
+	if (local5hReset) {
+		const remaining = local5hReset - input.nowMs;
+		lines.push(
+			`    Local 5h reset:    in ${formatDuration(remaining)} (oldest request falls out of window)`,
+		);
+	} else {
+		lines.push(`    Local 5h reset:    no requests in last 5 hours`);
+	}
+	if (localWeekReset) {
+		const remaining = localWeekReset - input.nowMs;
+		lines.push(
+			`    Local week reset:  in ${formatDuration(remaining)} (oldest request falls out of window)`,
+		);
+	} else {
+		lines.push(`    Local week reset:  no requests in last 7 days`);
+	}
+
+	// ─── Local-vs-mirror divergence ─────────────────────────────────────
+	if (input.mirror?.h5_used_pct !== undefined) {
+		const localPct = input.localFiveHLimitTokens
+			? (input.local.five_h.tokens / input.localFiveHLimitTokens) * 100
+			: 0;
+		const delta = localPct - input.mirror.h5_used_pct;
+		const deltaStr = delta >= 0 ? `+${delta.toFixed(1)}%` : `${delta.toFixed(1)}%`;
+		const warning = Math.abs(delta) > 5 ? " ⚠️  divergence > 5%" : "";
+		lines.push(`    Local-vs-mirror:  ${deltaStr}${warning}`);
+	}
+
+	// ─── Burn rate ──────────────────────────────────────────────────────
+	if (input.mirror?.weekly_used_pct !== undefined && input.mirror.weekly_resets_at) {
+		const resetMs = Date.parse(input.mirror.weekly_resets_at);
+		const elapsedMs = input.nowMs - resetMs;
+		const elapsedDays = elapsedMs / (24 * 60 * 60 * 1000);
+		if (elapsedDays > 0) {
+			const pctPerDay = input.mirror.weekly_used_pct / elapsedDays;
+			const remaining = 100 - input.mirror.weekly_used_pct;
+			const daysLeft = pctPerDay > 0 ? remaining / pctPerDay : Infinity;
+			const daysLeftStr = daysLeft === Infinity ? "∞" : `${daysLeft.toFixed(1)} d`;
+			lines.push(
+				`    Burn rate:        ${pctPerDay.toFixed(1)}% / day → 100% in ${daysLeftStr}`,
+			);
+		}
+	}
+
+	lines.push(divider);
+	lines.push(` Data dir:    ${process.env.PI_USAGE_DIR ?? "~/.pi/usage-status"}`);
+	lines.push(` Local time:  ${new Date(input.nowMs).toISOString()}`);
+	lines.push("");
+	lines.push(" Run `/usage sync` to update the provider mirror.");
+
+	return lines.join("\n");
+}

package/skills/harness-runtime/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: harness-runtime
+description: Show Codex-style /usage status for pi — local token tracking + manual provider mirror. Use when the user asks about token usage, API quota, 5h limit, weekly limit, or wants to know how much they've spent.
+---
+
+# pi-harness-runtime
+
+Codex-style `/usage` slash command for pi coding agent.
+
+## When to use
+
+User says:
+
+- "show me my usage"
+- "how much have I used?"
+- "what's my 5h limit?"
+- "weekly quota?"
+- "/usage"
+- "/usage sync"
+- "how many tokens today?"
+
+## Quick reference
+
+```bash
+/usage         # full status (model, local tracking, provider mirror)
+/usage sync    # open form to mirror provider-side quota
+/usage today   # focused: this 5h + today (UTC)
+/usage week    # focused: this week + lifetime
+/usage reset   # clear provider mirror
+```
+
+## Data sources (3-source model)
+
+1. **Local tracked** — every assistant message is logged to `~/.pi/usage-status/usage.jsonl`
+   - Auto-tracked via `message_end` event
+   - Contains: timestamp, model, input/output/cache tokens, cost
+   - Real-time, exact, but only counts THIS pi session
+
+2. **Provider mirror** — manually entered from `https://platform.minimax.io/console/usage`
+   - Stored at `~/.pi/usage-status/mirror.json`
+   - Synced via `/usage sync` form
+   - Ground truth for TOTAL quota (across all clients)
+
+3. **Derived** — burn rate, reset times, divergence
+   - Local reset time = oldest request in window + window duration
+   - Burn rate = mirror weekly % / elapsed days
+   - Divergence warning if local tracking differs from mirror by >5%
+
+## Files written
+
+- `~/.pi/usage-status/usage.jsonl` — append-only usage log
+- `~/.pi/usage-status/mirror.json` — manual provider mirror
+
+Override location with `PI_USAGE_DIR` env var.
+
+## Sample output
+
+```
+Codex-style usage status for pi
+────────────────────────────────────────────────────────────────
+ Model:        minimax/MiniMax-M3
+ Directory:    ~/frappe-bench/apps/thai_business_suite
+
+ ① LOCAL TRACKED (ground truth — we count this)
+    This session:   $0.17 · 142k tokens · 17 requests
+    This 5h:        384k tokens · 23 requests · $0.04
+    This week:      1.2M tokens · 67 requests · $0.13
+    Lifetime:       4592 requests · $81.61
+
+ ② PROVIDER MIRROR (you enter from console.minimax.io)
+    Last sync:      2 min ago [fresh]
+    Provider:       minimax
+    5h limit:       [████████░░░░░░░░░░░░] 18% left (resets in 4h 54m)
+    Weekly limit:   [████████████████░░░░] 81% left (resets in 2d 13h)
+
+ ③ LOCAL RESET TIMES (derived from your data)
+    Local 5h reset:    in 3h 12m (oldest request falls out of window)
+    Local week reset:  in 5d 7h (oldest request falls out of window)
+    Local-vs-mirror:  -12.4% ⚠️  divergence > 5%
+    Burn rate:        11.4% / day → 100% in 2.5 d
+────────────────────────────────────────────────────────────────
+```
+
+## Safety properties
+
+- **No auto-tracking of other clients** — local data is just this pi session
+- **No scraping** — provider mirror is manual (5-second task)
+- **No fabrication** — divergence warning if local and mirror disagree by >5%
+- **Idempotent** — running `/usage` repeatedly has no side effects
+- **Privacy-respecting** — all data stays on local disk
+
+## Related
+
+- `context-mode` provides overall session cost via `ctx_stats`
+- pi's built-in footer shows model + git branch

package/sync-form.ts

@@ -0,0 +1,104 @@
+/**
+ * Sync form — opens an interactive form for the user to mirror provider-side
+ * quota from console.minimax.io (or any provider dashboard).
+ *
+ * Uses ctx.ui.custom() to build a small TUI form with 4 fields:
+ *   - 5h used %   (number 0-100)
+ *   - 5h resets in (h, m)
+ *   - weekly %    (number 0-100)
+ *   - weekly resets in (d, h)
+ *
+ * On submit, writes a MirrorRecord to disk.
+ */
+
+import type { MirrorRecord } from "./mirror.ts";
+import type { MirrorStore } from "./mirror.ts";
+
+export interface SyncFormValues {
+	h5_used_pct: number;
+	h5_resets_h: number;
+	h5_resets_m: number;
+	weekly_used_pct: number;
+	weekly_resets_d: number;
+	weekly_resets_h: number;
+}
+
+/** Compute ISO 8601 reset time from "in Hh Mm" relative to now. */
+export function computeResetIso(nowMs: number, h: number, m: number): string {
+	return new Date(nowMs + h * 3600_000 + m * 60_000).toISOString();
+}
+
+/** Build a MirrorRecord from form values. */
+export function buildMirrorRecord(
+	values: SyncFormValues,
+	provider: string,
+	nowMs: number,
+): MirrorRecord {
+	return {
+		synced_at: new Date(nowMs).toISOString(),
+		provider,
+		h5_used_pct: values.h5_used_pct,
+		h5_resets_at: computeResetIso(nowMs, values.h5_resets_h, values.h5_resets_m),
+		weekly_used_pct: values.weekly_used_pct,
+		weekly_resets_at: computeResetIso(nowMs, values.weekly_resets_d * 24 + values.weekly_resets_h, 0),
+	};
+}
+
+/**
+ * Open the sync form. Implemented as a thin wrapper around ctx.ui.custom()
+ * — the actual TUI component lives in sync-form-ui.ts (or inline here).
+ *
+ * For simplicity (and testability), this file exports the pure form-data
+ * conversion. The actual TUI rendering is handled in index.ts which has
+ * access to ExtensionContext.
+ */
+export async function handleSyncSubmit(
+	values: SyncFormValues,
+	mirrorStore: MirrorStore,
+	provider: string = "minimax",
+): Promise<MirrorRecord> {
+	const now = Date.now();
+	const record = buildMirrorRecord(values, provider, now);
+	mirrorStore.write(record);
+	return record;
+}
+
+/**
+ * Parse a mirror record from raw form input strings (validates).
+ * Returns null if invalid.
+ */
+export function parseSyncValues(input: {
+	h5_used_pct: string;
+	h5_resets_h: string;
+	h5_resets_m: string;
+	weekly_used_pct: string;
+	weekly_resets_d: string;
+	weekly_resets_h: string;
+}): SyncFormValues | null {
+	const h5_used = Number(input.h5_used_pct);
+	const h5_h = Number(input.h5_resets_h);
+	const h5_m = Number(input.h5_resets_m);
+	const wk_used = Number(input.weekly_used_pct);
+	const wk_d = Number(input.weekly_resets_d);
+	const wk_h = Number(input.weekly_resets_h);
+
+	if (
+		!Number.isFinite(h5_used) || h5_used < 0 || h5_used > 100 ||
+		!Number.isFinite(h5_h) || h5_h < 0 || h5_h > 24 ||
+		!Number.isFinite(h5_m) || h5_m < 0 || h5_m > 59 ||
+		!Number.isFinite(wk_used) || wk_used < 0 || wk_used > 100 ||
+		!Number.isFinite(wk_d) || wk_d < 0 || wk_d > 7 ||
+		!Number.isFinite(wk_h) || wk_h < 0 || wk_h > 23
+	) {
+		return null;
+	}
+
+	return {
+		h5_used_pct: h5_used,
+		h5_resets_h: h5_h,
+		h5_resets_m: h5_m,
+		weekly_used_pct: wk_used,
+		weekly_resets_d: wk_d,
+		weekly_resets_h: wk_h,
+	};
+}

package/tracker.ts

@@ -0,0 +1,72 @@
+/**
+ * UsageTracker — append-only JSONL log of every assistant message.
+ *
+ * Stores one record per assistant message with: timestamp, model id,
+ * input/output tokens, cache read/write tokens, total cost USD.
+ *
+ * File: ~/.pi/usage-status/usage.jsonl (one JSON object per line)
+ *
+ * No locking — single-process pi uses single-writer. Multi-process safety
+ * is not a goal; SQLite would be needed for that.
+ */
+
+import {
+	appendJsonl,
+	ensureUsageDir,
+	getUsageLogPath,
+	readJsonl,
+} from "./cli.ts";
+import { unlinkSync } from "node:fs";
+
+export interface UsageRecord {
+	ts: number;          // unix ms
+	model: string;       // model id, e.g. "minimax/MiniMax-M3"
+	input: number;
+	output: number;
+	cache_read: number;
+	cache_write: number;
+	cost: number;        // USD total
+}
+
+export class UsageTracker {
+	private path: string;
+
+	constructor(path: string = getUsageLogPath()) {
+		this.path = path;
+		ensureUsageDir();
+	}
+
+	/** Append one usage record. */
+	append(record: UsageRecord): void {
+		appendJsonl(this.path, record);
+	}
+
+	/** Read all records (newest last). Returns [] if file missing. */
+	all(): UsageRecord[] {
+		return readJsonl<UsageRecord>(this.path);
+	}
+
+	/** Filter records newer than `sinceMs` (inclusive). */
+	since(sinceMs: number): UsageRecord[] {
+		return this.all().filter((r) => r.ts >= sinceMs);
+	}
+
+	/** Filter records within [fromMs, toMs). */
+	between(fromMs: number, toMs: number): UsageRecord[] {
+		return this.all().filter((r) => r.ts >= fromMs && r.ts < toMs);
+	}
+
+	/** Clear all records (testing only). */
+	clear(): void {
+		try {
+			unlinkSync(this.path);
+		} catch {
+			// ignore
+		}
+	}
+
+	/** Total record count. */
+	count(): number {
+		return this.all().length;
+	}
+}