pi-harness-runtime 0.10.11 → 0.10.12

package/cli.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure helper functions — testable without pi context.
+ * Imported by tracker.ts, mirror.ts, windows.ts, renderer.ts.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** Resolve the ~/.pi/usage-status/ directory. Override with PI_USAGE_DIR env var (testing). */
+export function getUsageDir(): string {
+	const override = process.env.PI_USAGE_DIR;
+	if (override) return override;
+	return join(homedir(), ".pi", "usage-status");
+}
+
+/** Resolve the JSONL usage log path. */
+export function getUsageLogPath(): string {
+	return join(getUsageDir(), "usage.jsonl");
+}
+
+/** Resolve the mirror JSON path. */
+export function getMirrorPath(): string {
+	return join(getUsageDir(), "mirror.json");
+}
+
+/** Ensure the directory exists. Idempotent. */
+export function ensureUsageDir(): void {
+	const dir = getUsageDir();
+	if (!existsSync(dir)) {
+		mkdirSync(dir, { recursive: true });
+	}
+}
+
+/** Read the JSONL usage log as an array of UsageRecord. Returns [] if missing. */
+export function readJsonl<T>(path: string): T[] {
+	if (!existsSync(path)) return [];
+	const text = readFileSync(path, "utf-8");
+	const out: T[] = [];
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			out.push(JSON.parse(trimmed) as T);
+		} catch {
+			// skip corrupted line
+		}
+	}
+	return out;
+}
+
+/** Append a single JSON line to a JSONL file. */
+export function appendJsonl(path: string, record: unknown): void {
+	ensureUsageDir();
+	const line = JSON.stringify(record) + "\n";
+	appendFileSync(path, line, "utf-8");
+}
+
+/** Read JSON file safely. Returns null if missing or corrupted. */
+export function readJson(path: string): unknown | null {
+	if (!existsSync(path)) return null;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+
+/** Write JSON file (creates parent dir if needed). */
+export function writeJson(path: string, data: unknown): void {
+	ensureUsageDir();
+	if (!existsSync(dirname(path))) {
+		mkdirSync(dirname(path), { recursive: true });
+	}
+	writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/** Format milliseconds as "Xh Ym" or "Xd Yh" or "Xm" or "Xs". */
+export function formatDuration(ms: number): string {
+	const abs = Math.max(0, Math.floor(ms / 1000));
+	const sec = abs % 60;
+	const min = Math.floor(abs / 60) % 60;
+	const hr = Math.floor(abs / 3600) % 24;
+	const day = Math.floor(abs / 86400);
+	if (day > 0) return `${day}d ${hr}h`;
+	if (hr > 0) return `${hr}h ${min}m`;
+	if (min > 0) return `${min}m`;
+	return `${sec}s`;
+}
+
+/** Format a timestamp as relative time "X min ago". */
+export function formatRelative(fromIso: string, nowMs: number): string {
+	const fromMs = Date.parse(fromIso);
+	if (isNaN(fromMs)) return "unknown";
+	const deltaMs = nowMs - fromMs;
+	return formatDuration(deltaMs) + " ago";
+}
+
+/** Format a token count with k/M suffix. */
+export function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+	return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/** Format USD cost with 2-4 decimals depending on size. */
+export function formatUsd(n: number): string {
+	if (n < 0.01) return `$${n.toFixed(4)}`;
+	if (n < 100) return `$${n.toFixed(2)}`;
+	return `$${n.toFixed(0)}`;
+}

package/footer-status.ts

@@ -0,0 +1,204 @@
+import type { MirrorRecord, ProviderMirrorRecord } from "./mirror.ts";
+
+import {
+	parseContextWindowStatusLine,
+	parseQuotaUsageStatusLine,
+	type ParsedContextWindowUsage,
+	type ParsedQuotaUsageData,
+} from "./status-parsers.ts";
+import { getProviderLabel } from "./packages/types/src/ai-providers.js";
+import {
+	providerHasContinuousScrape,
+	providerHasTUISignal,
+} from "./packages/providers/src/provider-id.js";
+
+export type ParsedFooterStatusValue =
+	| { kind: "quota"; value: ParsedQuotaUsageData }
+	| { kind: "context-window"; value: ParsedContextWindowUsage }
+	| { kind: "today"; value: { tokens: number; cost: number } }
+	| { kind: "unknown"; value: null };
+
+export function parseFooterStatusValue(value: string): ParsedFooterStatusValue {
+	const quota = parseQuotaUsageStatusLine(value);
+	if (quota) {
+		return { kind: "quota", value: quota };
+	}
+
+	const contextWindow = parseContextWindowStatusLine(value);
+	if (contextWindow) {
+		return { kind: "context-window", value: contextWindow };
+	}
+
+	const todayMatch = value.match(/^today:\s*([\d,.]+)k tok\s*·\s*\$([\d,.]+)/i);
+	if (todayMatch) {
+		const tokens = Number.parseFloat(todayMatch[1].replace(/,/g, "")) * 1000;
+		const cost = Number.parseFloat(todayMatch[2].replace(/,/g, ""));
+		if (Number.isFinite(tokens) && Number.isFinite(cost)) {
+			return {
+				kind: "today",
+				value: { tokens, cost },
+			};
+		}
+	}
+
+	return { kind: "unknown", value: null };
+}
+
+/**
+ * Get display label for a provider id.
+ * Uses the canonical getProviderLabel() from packages/types/src/ai-providers.ts
+ * which handles all 9 known providers: minimax, openai, anthropic, glm,
+ * openrouter, openai-codex, deepseek, gemini, kimi.
+ */
+function providerDisplayName(provider: string | null | undefined): string {
+	if (!provider) return "Provider";
+	return getProviderLabel(provider);
+}
+
+/**
+ * Hint shown when the provider has no usage data yet.
+ * Covers all 9 known providers from KNOWN_AI_PROVIDERS.
+ */
+function missingDataHint(
+	provider: string | null | undefined,
+	hasCookieSource: boolean,
+): string {
+	if (!provider) return "no usage source configured";
+
+	// MiniMax: needs cookies for continuous scrape
+	if (provider === "minimax") {
+		return hasCookieSource
+			? "no data yet (updates after first scrape)"
+			: "drop minimax cookies into ~/.pi-harness-runtime/cookies/";
+	}
+
+	// TUI signal providers: one-shot signal on limit hit
+	if (providerHasTUISignal(provider)) {
+		return "no signal yet (updates on first limit hit)";
+	}
+
+	// Providers without any tracking implementation yet
+	// deepseek, gemini, kimi, or any unknown provider
+	if (provider === "deepseek") {
+		return "deepseek usage tracking not yet implemented";
+	}
+	if (provider === "gemini") {
+		return "gemini usage tracking not yet implemented";
+	}
+	if (provider === "kimi") {
+		return "kimi usage tracking not yet implemented";
+	}
+
+	// Generic fallback for any other unknown provider
+	if (!hasCookieSource) return "no usage source configured";
+	return "no data yet";
+}
+
+/** Normalize an unknown mirror record into a ProviderMirrorRecord view. */
+function toProviderView(
+	mirror: MirrorRecord | ProviderMirrorRecord | null,
+): ProviderMirrorRecord | null {
+	if (!mirror) return null;
+	const m = mirror as ProviderMirrorRecord;
+	if (typeof m.provider === "string") return m;
+	// Legacy flat-shape: already a single record without a provider wrapper.
+	return {
+		synced_at: m.synced_at ?? new Date().toISOString(),
+		provider: (m as MirrorRecord).provider ?? "",
+		source: "scrape",
+		model: (m as MirrorRecord).model,
+		h5_used_pct: (m as MirrorRecord).h5_used_pct,
+		h5_resets_at: (m as MirrorRecord).h5_resets_at,
+		weekly_used_pct: (m as MirrorRecord).weekly_used_pct,
+		weekly_resets_at: (m as MirrorRecord).weekly_resets_at,
+	};
+}
+
+export function buildFooterStatusValue(
+	local: { today: { tokens: number; cost: number } },
+	mirror: MirrorRecord | ProviderMirrorRecord | null,
+	freshness: "fresh" | "stale" | "expired" | "missing",
+	hasCookieSource: boolean = true,
+	activeProvider: string | null = null,
+): string {
+	const view = toProviderView(mirror);
+	const provider = activeProvider ?? view?.provider ?? null;
+	const label = providerDisplayName(provider);
+
+	// TUI-signal exhaustion path: fires when limit is hit (one-shot signal).
+	// This takes priority over continuous data to show the most recent state.
+	if (
+		provider &&
+		view &&
+		view.exhausted &&
+		(view.limitType !== undefined ||
+			view.resets_at !== undefined ||
+			view.h5_resets_at !== undefined)
+	) {
+		const reset = view.resets_at ?? view.h5_resets_at ?? "soon";
+		const limitType = view.limitType ?? "tokens";
+		return `${label}: limit hit (${limitType}), reset ${reset}`;
+	}
+
+	// Continuous data path: providers with continuous scrape (MiniMax has 5h+weekly, OpenAI has weekly-only)
+	if (
+		provider &&
+		providerHasContinuousScrape(provider) &&
+		view &&
+		freshness !== "expired" &&
+		(view.h5_used_pct !== undefined || view.weekly_used_pct !== undefined)
+	) {
+		const weeklyPct = view.weekly_used_pct ?? 0;
+		const weeklyLeft = Math.max(0, 100 - weeklyPct);
+		const weeklyResets = view.weekly_resets_at ?? "soon";
+
+		let statusLine: string;
+		if (view.h5_used_pct !== undefined) {
+			// MiniMax: has both 5h and weekly windows
+			const h5Pct = view.h5_used_pct;
+			const h5Left = Math.max(0, 100 - h5Pct);
+			statusLine = `5h: ${h5Left.toFixed(0)}% left · week: ${weeklyLeft.toFixed(0)}% left`;
+		} else {
+			// OpenAI: weekly-only (no 5h window)
+			statusLine = `week: ${weeklyLeft.toFixed(0)}% left (resets ${weeklyResets})`;
+		}
+
+		const freshnessSuffix =
+			freshness === "fresh" || freshness === "missing" ? "" : ` · ${freshness}`;
+		return `${label}: ${statusLine}${freshnessSuffix}`;
+	}
+
+	// TUI signal providers (OpenAI, Anthropic, GLM, OpenRouter):
+	// Show monitoring status when we have a record but haven't hit limits.
+	// These providers only emit data when a limit is hit.
+	if (
+		provider &&
+		providerHasTUISignal(provider) &&
+		view &&
+		freshness !== "expired"
+	) {
+		// If exhausted is not set, we're monitoring normally
+		if (!view.exhausted) {
+			return `${label}: monitoring (no limits hit)`;
+		}
+	}
+
+	// Discoverable hint when we have no data yet.
+	if (
+		provider &&
+		(!view || freshness === "expired" || freshness === "missing")
+	) {
+		const hint = missingDataHint(provider, hasCookieSource);
+		// MiniMax-on-fresh-machine still gets the cookie hint; for others
+		// the hint explains the signal-driven design.
+		if (provider === "minimax" && !hasCookieSource) {
+			return `${label}: 5h: -- (${hint})`;
+		}
+		return `${label}: 5h: -- · week: -- (${hint})`;
+	}
+
+	// Silent fallback: only reached if we genuinely don't know the provider.
+	// No "5h/week: --" line here because we'd be making up data.
+	const todayStr = `${(local.today.tokens / 1000).toFixed(1)}k tok · $${local.today.cost.toFixed(3)}`;
+	return `today: ${todayStr}`;
+}

package/harness/agent-handoff.ts

@@ -0,0 +1,189 @@
+/**
+ * Agent Handoff Protocol — RFC-0012
+ *
+ * Clean handoff between agents with context transfer.
+ * Ensures continuity when switching agents mid-task.
+ */
+
+import type {
+	HandoffContext,
+	HandoffEvent,
+} from "../packages/types/src/runtime-types.ts";
+import { writeJson, readJson } from "../cli.ts";
+// @ts-expect-error - Bun has built-in Node.js types
+import { join } from "node:path";
+
+export interface HandoffData {
+	fromAgent: string;
+	toAgent: string;
+	taskId: string;
+	taskSummary: string;
+	contextFiles: string[];
+	recentHistory: string[];
+	currentState: Record<string, unknown>;
+}
+
+export class AgentHandoffProtocol {
+	private readonly rootDir: string;
+
+	constructor(rootDir: string) {
+		this.rootDir = rootDir;
+	}
+
+	/**
+	 * Create a handoff context for switching agents
+	 */
+	createHandoff(
+		jobId: string,
+		taskId: string,
+		fromAgent: string,
+		toAgent: string,
+		currentState?: Record<string, unknown>,
+	): HandoffContext {
+		const events = this.loadHandoffHistory(jobId, taskId);
+
+		return {
+			jobId,
+			taskId,
+			fromAgent,
+			toAgent,
+			sharedFiles: [],
+			taskHistory: events,
+			summary: this.generateSummary(taskId, currentState),
+		};
+	}
+
+	/**
+	 * Record a handoff event
+	 */
+	recordHandoff(context: HandoffContext, result?: string): void {
+		const path = join(
+			this.rootDir,
+			"jobs",
+			context.jobId,
+			"handoffs",
+			`${context.taskId}.json`,
+		);
+		const event: HandoffEvent = {
+			ts: new Date().toISOString(),
+			agentId: context.toAgent,
+			action: "handoff_received",
+			result,
+		};
+		context.taskHistory.push(event);
+		writeJson(path, context);
+	}
+
+	/**
+	 * Generate handoff prompt for the receiving agent
+	 */
+	generateHandoffPrompt(context: HandoffContext): string {
+		const lines = [
+			`## Agent Handoff`,
+			``,
+			`**From Agent:** ${context.fromAgent}`,
+			`**To Agent:** ${context.toAgent}`,
+			`**Task:** ${context.taskId}`,
+			``,
+			`### Task History`,
+		];
+
+		for (const event of context.taskHistory) {
+			lines.push(`- [${event.ts}] ${event.agentId}: ${event.action}`);
+			if (event.result) {
+				lines.push(`  Result: ${event.result}`);
+			}
+		}
+
+		lines.push(``);
+		lines.push(`### Summary`);
+		lines.push(context.summary);
+
+		if (context.sharedFiles.length > 0) {
+			lines.push(``);
+			lines.push(`### Shared Files`);
+			for (const file of context.sharedFiles) {
+				lines.push(`- ${file}`);
+			}
+		}
+
+		return lines.join("\n");
+	}
+
+	/**
+	 * Validate handoff readiness
+	 */
+	validateHandoff(context: HandoffContext): {
+		valid: boolean;
+		issues: string[];
+	} {
+		const issues: string[] = [];
+
+		if (!context.summary) {
+			issues.push("Task summary is empty");
+		}
+
+		if (context.taskHistory.length === 0) {
+			issues.push("No task history recorded");
+		}
+
+		// Check for recent handoffs
+		const recentHandoffs = context.taskHistory.filter((h) => {
+			const age = Date.now() - Date.parse(h.ts);
+			return age < 5 * 60 * 1000; // 5 minutes
+		});
+
+		if (recentHandoffs.length > 3) {
+			issues.push(
+				`Too many recent handoffs (${recentHandoffs.length}). Possible ping-pong.`,
+			);
+		}
+
+		return { valid: issues.length === 0, issues };
+	}
+
+	/**
+	 * Load handoff history for a task
+	 */
+	private loadHandoffHistory(jobId: string, taskId: string): HandoffEvent[] {
+		const path = join(
+			this.rootDir,
+			"jobs",
+			jobId,
+			"handoffs",
+			`${taskId}.json`,
+		);
+		const data = readJson(path) as HandoffContext | null;
+		return data?.taskHistory ?? [];
+	}
+
+	/**
+	 * Generate a summary of the task state
+	 */
+	private generateSummary(
+		taskId: string,
+		currentState?: Record<string, unknown>,
+	): string {
+		if (!currentState) {
+			return `Task ${taskId} requires continuation. Check task files for current state.`;
+		}
+
+		const lines = [`Task ${taskId} is in progress.`];
+
+		if (currentState.filesModified) {
+			lines.push(
+				`Files modified: ${(currentState.filesModified as string[]).join(", ")}`,
+			);
+		}
+
+		if (currentState.lastAction) {
+			lines.push(`Last action: ${currentState.lastAction}`);
+		}
+
+		if (currentState.blockers) {
+			lines.push(`Blockers: ${currentState.blockers}`);
+		}
+
+		return lines.join("\n");
+	}
+}