@caph42/pi-ccline 0.0.0-stage → 0.1.1

package/extensions/pi-ccline/index.ts

@@ -0,0 +1,374 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import { clearBinaryCache, probeVersion, resolveBinary, spawnCcline, type ResolvedBinary } from "./binary.ts";
+import { loadConfig, saveConfig, type PiCclineConfig } from "./config.ts";
+import { buildCclineInput, collectSnapshot } from "./input.ts";
+import { RefreshScheduler, RefreshTicker } from "./refresh.ts";
+import { extensionStatusLine, loadingNotice, missingBinaryNotice, normalizeFrame, noticeFrame, withStaleMarker } from "./render.ts";
+
+/** Structural subsets so the footer does not depend on pi-tui internals. */
+type TuiLike = { requestRender(force?: boolean): void };
+type ThemeLike = { fg(color: string, text: string): string };
+type FooterDataLike = {
+	onBranchChange(callback: () => void): () => void;
+	/** Present on pi >= 1.4; absent on older footers, hence optional. */
+	getExtensionStatuses?(): ReadonlyMap<string, string>;
+};
+
+const DEFAULT_WIDTH = 120;
+
+/**
+ * Best-effort initial width so the very first refresh wraps like the footer
+ * will. render(width) corrects it once pi paints the first frame.
+ */
+function initialWidth(): number {
+	try {
+		const columns = process.stdout.columns;
+		if (typeof columns === "number" && Number.isFinite(columns) && columns > 0) return Math.floor(columns);
+	} catch {
+		// not a terminal
+	}
+	return DEFAULT_WIDTH;
+}
+
+function firstLine(text: string): string {
+	return (text.split("\n")[0] ?? "").trim().slice(0, 160);
+}
+
+/**
+ * Owns one footer installation: the cached frame, the single-flight refresh
+ * scheduler and the in-flight child process.
+ */
+export class CclineFooter {
+	private readonly ctx: ExtensionContext;
+	private readonly config: PiCclineConfig;
+	private readonly scheduler: RefreshScheduler;
+	/** Only runs while the agent is active so an idle session spawns nothing. */
+	private readonly ticker: RefreshTicker;
+	private controller: AbortController | null = null;
+	/** Bumped on dispose and on every refresh so late results are dropped. */
+	private generation = 0;
+	private frame: string[] | null = null;
+	private stale = false;
+	private lastError: string | null = null;
+	private width = initialWidth();
+	private theme: ThemeLike | null = null;
+	private footerData: FooterDataLike | null = null;
+	private requestRenderFn: (() => void) | null = null;
+	private branchUnsubscribe: (() => void) | null = null;
+	private disposed = false;
+
+	readonly stats = {
+		refreshes: 0,
+		lastRefreshAt: null as number | null,
+		lastDurationMs: null as number | null,
+	};
+	resolved: ResolvedBinary = { path: null, source: "missing" };
+
+	constructor(ctx: ExtensionContext, config: PiCclineConfig) {
+		this.ctx = ctx;
+		this.config = config;
+		this.scheduler = new RefreshScheduler({
+			throttleMs: config.refreshThrottleMs,
+			task: () => this.refresh(),
+		});
+		this.ticker = new RefreshTicker({
+			intervalMs: config.liveRefreshMs,
+			onTick: () => this.requestRefresh(),
+		});
+	}
+
+	/** Called by pi with the live TUI, theme and footer data. */
+	attach(tui: TuiLike, theme: ThemeLike, footerData: FooterDataLike) {
+		this.theme = theme;
+		this.footerData = footerData;
+		this.requestRenderFn = () => tui.requestRender();
+		try {
+			this.branchUnsubscribe = footerData.onBranchChange(() => {
+				this.requestRefresh();
+				tui.requestRender();
+			});
+		} catch {
+			this.branchUnsubscribe = null;
+		}
+		this.requestRefresh();
+		// The footer can be installed (or re-enabled) in the middle of a run, when
+		// no agent_start will arrive until the next one. Start ticking right away.
+		if (!this.agentIsIdle()) this.startLive();
+
+		return {
+			dispose: () => this.dispose(),
+			invalidate: () => this.requestRefresh(),
+			render: (width: number) => this.render(width),
+		};
+	}
+
+	/** Coalesced, throttled refresh request. Never starts work synchronously. */
+	requestRefresh(): void {
+		if (this.disposed) return;
+		this.scheduler.request();
+	}
+
+	/**
+	 * Start ticking so time-based segments (elapsed duration) stay live.
+	 * Called when an agent run starts; idempotent.
+	 */
+	startLive(): void {
+		if (this.disposed) return;
+		this.ticker.start();
+	}
+
+	stopLive(): void {
+		this.ticker.stop();
+	}
+
+	/** Idle unless pi says otherwise; an unreadable state must not start a timer. */
+	private agentIsIdle(): boolean {
+		try {
+			return this.ctx.isIdle();
+		} catch {
+			return true;
+		}
+	}
+
+	get error(): string | null {
+		return this.lastError;
+	}
+
+	get hasFrame(): boolean {
+		return this.frame !== null;
+	}
+
+	private render(width: number): string[] {
+		const requested = Math.floor(width);
+		const safeWidth = Math.max(1, requested || this.width);
+		// The width is only known during a render pass. Record it and let the
+		// scheduler wrap it into a later refresh; never spawn from here.
+		if (requested > 0 && requested !== this.width) {
+			this.width = requested;
+			this.requestRefresh();
+		}
+
+		const frame = this.frame;
+		const lines = frame
+			? (() => {
+					const fitted = frame.map((line) => (visibleWidth(line) > safeWidth ? truncateToWidth(line, safeWidth) : line));
+					return this.stale && this.theme ? withStaleMarker(fitted, safeWidth, this.theme.fg("dim", " ·stale")) : fitted;
+				})()
+			: loadingNotice(safeWidth);
+
+		// Read live: pi repaints on setStatus, so no subscription is needed and a
+		// status change shows up on the next frame even while ccline is throttled.
+		const statuses = (() => {
+			try {
+				return this.footerData?.getExtensionStatuses?.() ?? null;
+			} catch {
+				return null;
+			}
+		})();
+		const status = extensionStatusLine(statuses, safeWidth, this.theme ? this.theme.fg("dim", "…") : "…");
+		return status ? [...lines, status] : lines;
+	}
+
+	private applyFrame(lines: string[], stale: boolean, error: string | null): void {
+		this.frame = lines;
+		this.stale = stale;
+		this.lastError = error;
+		this.requestRenderFn?.();
+	}
+
+	private async refresh(): Promise<void> {
+		if (this.disposed) return;
+		const generation = ++this.generation;
+		const startedAt = Date.now();
+		const binary = resolveBinary(this.config.binary);
+		this.resolved = binary;
+
+		if (!binary.path) {
+			this.applyFrame(missingBinaryNotice(this.width), false, "ccline binary not found");
+			return;
+		}
+
+		this.controller?.abort();
+		const controller = new AbortController();
+		this.controller = controller;
+
+		const snapshot = collectSnapshot(this.ctx, Date.now());
+		const payload = JSON.stringify(buildCclineInput(snapshot, { showProvider: this.config.showProvider }));
+
+		const result = await spawnCcline({
+			binary: binary.path,
+			payload,
+			timeoutMs: this.config.timeoutMs,
+			columns: this.width,
+			env: this.config.env,
+			signal: controller.signal,
+		});
+
+		// A newer refresh or a dispose superseded this run; drop its result.
+		if (this.disposed || generation !== this.generation) return;
+		this.controller = null;
+		this.stats.lastRefreshAt = Date.now();
+		this.stats.lastDurationMs = Date.now() - startedAt;
+
+		if (result.ok) {
+			const lines = normalizeFrame(result.stdout, this.width);
+			if (lines.length > 0) {
+				this.stats.refreshes += 1;
+				this.applyFrame(lines, false, null);
+				return;
+			}
+		}
+
+		const reason = result.aborted
+			? "aborted"
+			: result.timedOut
+				? `timed out after ${this.config.timeoutMs}ms`
+				: result.error
+					? result.error
+					: `exited with code ${result.code}${result.stderr.trim() ? `: ${firstLine(result.stderr)}` : ""}`;
+
+		if (this.frame) {
+			// Keep the last good frame and only mark it stale.
+			this.applyFrame(this.frame, true, reason);
+		} else {
+			this.applyFrame(noticeFrame(`ccline failed: ${reason}`, this.width), false, reason);
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.generation += 1;
+		this.ticker.stop();
+		this.scheduler.dispose();
+		this.controller?.abort();
+		this.controller = null;
+		try {
+			this.branchUnsubscribe?.();
+		} catch {
+			// ignore
+		}
+		this.branchUnsubscribe = null;
+		this.footerData = null;
+		this.requestRenderFn = null;
+	}
+}
+
+/** Optional seams so the extension lifecycle can be tested without a real session. */
+export interface PiCclineDeps {
+	loadConfig?: () => PiCclineConfig;
+}
+
+export default function piCcline(pi: ExtensionAPI, deps: PiCclineDeps = {}) {
+	let footer: CclineFooter | null = null;
+	const readConfig = deps.loadConfig ?? (() => loadConfig());
+
+	const teardown = () => {
+		footer?.dispose();
+		footer = null;
+	};
+
+	/** Install the footer for the current session. Returns false when it does not apply. */
+	const install = (ctx: ExtensionContext): boolean => {
+		teardown();
+		if (ctx.mode !== "tui" || !ctx.hasUI) return false;
+		const config = readConfig();
+		if (!config.enabled) return false;
+		const next = new CclineFooter(ctx, config);
+		ctx.ui.setFooter((tui, theme, footerData) => next.attach(tui, theme, footerData));
+		footer = next;
+		return true;
+	};
+
+	const requestRefresh = () => footer?.requestRefresh();
+
+	// Processes, timers and the footer only start from a session, never from the
+	// extension factory (some invocations load extensions without a session).
+	pi.on("session_start", (_event, ctx) => {
+		install(ctx);
+	});
+	pi.on("turn_start", () => {
+		requestRefresh();
+		// Covers a footer installed while a run was already in progress.
+		footer?.startLive();
+	});
+	pi.on("turn_end", () => requestRefresh());
+	// An agent run can contain many turns and can sit inside one turn for a long
+	// time, so events alone leave the elapsed segment frozen. Tick while the run
+	// is active and stop again when it settles.
+	pi.on("agent_start", () => footer?.startLive());
+	pi.on("agent_end", () => {
+		requestRefresh();
+		footer?.stopLive();
+	});
+	pi.on("agent_settled", () => footer?.stopLive());
+	pi.on("model_select", () => requestRefresh());
+	pi.on("thinking_level_select", () => requestRefresh());
+	pi.on("session_info_changed", () => requestRefresh());
+	pi.on("session_shutdown", () => teardown());
+
+	pi.registerCommand("pi-ccline", {
+		description: "ccline footer: on | off | status | path",
+		handler: async (args, ctx) => {
+			const subcommand = (args ?? "").trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+
+			if (subcommand === "on") {
+				if (!saveConfig({ ...loadConfig(), enabled: true })) {
+					ctx.ui.notify("pi-ccline: could not write config.json", "warning");
+				}
+				clearBinaryCache();
+				if (install(ctx)) ctx.ui.notify("pi-ccline footer enabled", "info");
+				else ctx.ui.notify("pi-ccline: footer needs interactive (tui) mode", "warning");
+				return;
+			}
+
+			if (subcommand === "off") {
+				saveConfig({ ...loadConfig(), enabled: false });
+				teardown();
+				if (ctx.hasUI) ctx.ui.setFooter(undefined);
+				ctx.ui.notify("pi-ccline footer disabled", "info");
+				return;
+			}
+
+			if (subcommand === "path") {
+				const config = loadConfig();
+				const binary = resolveBinary(config.binary);
+				if (!binary.path) {
+					ctx.ui.notify(
+						"ccline not found\nlooked at: config.binary, ~/.claude/ccline/ccline, PATH\ninstall: npm i -g @cometix/ccline",
+						"warning",
+					);
+					return;
+				}
+				const version = await probeVersion(binary.path, config.timeoutMs);
+				ctx.ui.notify(`${binary.path}\nsource: ${binary.source}\nversion: ${version ?? "unknown"}`, "info");
+				return;
+			}
+
+			if (subcommand !== "" && subcommand !== "status") {
+				ctx.ui.notify("usage: /pi-ccline on | off | status | path", "warning");
+				return;
+			}
+
+			const config = loadConfig();
+			const binary = footer?.resolved ?? resolveBinary(config.binary);
+			const lines = [
+				`enabled: ${config.enabled ? "yes" : "no"} · mode: ${ctx.mode}`,
+				`binary: ${binary.path ?? "not found"}${binary.path ? ` (${binary.source})` : ""}`,
+				`timeout: ${config.timeoutMs}ms · throttle: ${config.refreshThrottleMs}ms`,
+				`live: ${config.liveRefreshMs > 0 ? `${config.liveRefreshMs}ms while the agent runs` : "off"}`,
+			];
+			if (footer) {
+				const { refreshes, lastRefreshAt, lastDurationMs } = footer.stats;
+				lines.push(`refreshes: ${refreshes} · last: ${lastRefreshAt === null ? "never" : `${Math.round((Date.now() - lastRefreshAt) / 1000)}s ago`}`);
+				lines.push(`duration: ${lastDurationMs === null ? "n/a" : `${lastDurationMs}ms`} · frame: ${footer.hasFrame ? "cached" : "none"}`);
+				lines.push(`state: ${footer.error ? `stale — ${footer.error}` : "ok"}`);
+			} else {
+				lines.push("state: footer not installed");
+			}
+			ctx.ui.notify(lines.join("\n"), footer?.error ? "warning" : "info");
+		},
+	});
+}

package/extensions/pi-ccline/input.test.ts

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { buildCclineInput, collectSnapshot, type BranchEntryLike, type PiSnapshot, type SnapshotContextLike } from "./input.ts";
+
+function snapshot(overrides: Partial<PiSnapshot> = {}): PiSnapshot {
+	return {
+		cwd: "/work/project",
+		model: { id: "gpt-5.6-codex", name: "GPT-5.6 Codex", contextWindow: 272_000 },
+		thinkingLevel: "high",
+		contextUsage: { tokens: 42_000, contextWindow: 272_000, percent: 15.4 },
+		totals: { costUsd: 1.2345, durationMs: 1_830_000 },
+		session: { id: "sess-1", name: "demo" },
+		...overrides,
+	};
+}
+
+test("maps a full snapshot to the ccline schema", () => {
+	assert.deepEqual(buildCclineInput(snapshot()), {
+		cwd: "/work/project",
+		workspace: { current_dir: "/work/project" },
+		model: { id: "gpt-5.6-codex", display_name: "GPT-5.6 Codex" },
+		effort: { level: "high" },
+		context_window: {
+			context_window_size: 272_000,
+			current_usage: { input_tokens: 42_000 },
+			used_percentage: 15.4,
+		},
+		cost: { total_cost_usd: 1.2345, total_duration_ms: 1_830_000 },
+		session_id: "sess-1",
+		session_name: "demo",
+	});
+});
+
+test("never sends version, which ccline 2.0.1 rejects, and never sends rate_limits", () => {
+	const input = buildCclineInput(snapshot());
+	assert.equal("version" in input, false);
+	assert.equal("rate_limits" in input, false);
+});
+
+test("omits model and effort when pi has none", () => {
+	const input = buildCclineInput(snapshot({ model: undefined, thinkingLevel: undefined }));
+	assert.equal("model" in input, false);
+	assert.equal("effort" in input, false);
+	// Context usage still carries its own window size without a model.
+	const contextWindow = input.context_window as Record<string, unknown>;
+	assert.equal(contextWindow.context_window_size, 272_000);
+	// cwd and session data do not depend on the model.
+	assert.deepEqual(input.workspace, { current_dir: "/work/project" });
+	assert.equal(input.session_id, "sess-1");
+});
+
+test("ignores an unknown thinking level instead of guessing", () => {
+	const input = buildCclineInput(snapshot({ thinkingLevel: "off" }));
+	assert.equal("effort" in input, false);
+});
+
+test("omits cost when no assistant usage was recorded", () => {
+	const input = buildCclineInput(snapshot({ totals: undefined }));
+	assert.equal("cost" in input, false);
+	assert.equal("context_window" in input, true);
+	const contextWindow = input.context_window as Record<string, unknown>;
+	assert.equal(contextWindow.used_percentage, 15.4);
+});
+
+test("sends only the live context, never cumulative token totals", () => {
+	// ccline prefers total_input_tokens over current_usage, which would show a
+	// token count that disagrees with used_percentage.
+	const contextWindow = buildCclineInput(snapshot()).context_window as Record<string, unknown>;
+	assert.equal("total_input_tokens" in contextWindow, false);
+	assert.equal("total_output_tokens" in contextWindow, false);
+	assert.deepEqual(contextWindow.current_usage, { input_tokens: 42_000 });
+});
+
+test("keeps a partial context window when usage is unknown", () => {
+	const input = buildCclineInput(snapshot({ contextUsage: { tokens: null, contextWindow: 272_000, percent: null } }));
+	const contextWindow = input.context_window as Record<string, unknown>;
+	assert.equal(contextWindow.context_window_size, 272_000);
+	assert.equal("current_usage" in contextWindow, false);
+	assert.equal("used_percentage" in contextWindow, false);
+});
+
+test("falls back to the model context window and drops the session when unset", () => {
+	const input = buildCclineInput(snapshot({ contextUsage: undefined, session: {} }));
+	const contextWindow = input.context_window as Record<string, unknown>;
+	assert.equal(contextWindow.context_window_size, 272_000);
+	assert.equal("session_id" in input, false);
+	assert.equal("session_name" in input, false);
+});
+
+test("uses the model id as display_name when no name is available", () => {
+	const input = buildCclineInput(snapshot({ model: { id: "some-model" } }));
+	assert.deepEqual(input.model, { id: "some-model", display_name: "some-model" });
+});
+
+test("appends the provider to the model name", () => {
+	const input = buildCclineInput(snapshot({ model: { id: "claude-sonnet-4-5", name: "Sonnet 4.5", provider: "anthropic" } }));
+	assert.deepEqual(input.model, { id: "claude-sonnet-4-5", display_name: "Sonnet 4.5 (anthropic)" });
+});
+
+test("appends the provider to an id-only model and skips a duplicate suffix", () => {
+	const idOnly = buildCclineInput(snapshot({ model: { id: "gpt-5.1", provider: "openai-codex" } }));
+	assert.deepEqual(idOnly.model, { id: "gpt-5.1", display_name: "gpt-5.1 (openai-codex)" });
+
+	const already = buildCclineInput(snapshot({ model: { id: "m", name: "Sonnet 4.5 (anthropic)", provider: "anthropic" } }));
+	assert.deepEqual(already.model, { id: "m", display_name: "Sonnet 4.5 (anthropic)" });
+});
+
+test("showProvider false or an unknown provider keeps the bare name", () => {
+	const model = { id: "m", name: "Sonnet 4.5", provider: "anthropic" };
+	assert.deepEqual(buildCclineInput(snapshot({ model }), { showProvider: false }).model, {
+		id: "m",
+		display_name: "Sonnet 4.5",
+	});
+	assert.deepEqual(buildCclineInput(snapshot({ model: { id: "m", name: "Sonnet 4.5", provider: "  " } })).model, {
+		id: "m",
+		display_name: "Sonnet 4.5",
+	});
+});
+
+test("omits blank strings instead of sending empty values", () => {
+	const input = buildCclineInput(snapshot({ cwd: "  ", session: { id: " ", name: "" } }));
+	assert.equal("cwd" in input, false);
+	assert.equal("workspace" in input, false);
+	assert.equal("session_id" in input, false);
+});
+
+function entry(partial: BranchEntityInput): BranchEntryLike {
+	return partial as BranchEntryLike;
+}
+
+type BranchEntityInput = {
+	type?: string;
+	timestamp?: string;
+	message?: { role?: string; usage?: Record<string, unknown> };
+};
+
+function fakeContext(branch: BranchEntryLike[], overrides: Partial<SnapshotContextLike> = {}): SnapshotContextLike {
+	return {
+		cwd: "/work/project",
+		model: { id: "m", name: "M", contextWindow: 200_000 },
+		thinkingLevel: "low",
+		getContextUsage: () => ({ tokens: 1000, contextWindow: 200_000, percent: 0.5 }),
+		sessionManager: {
+			getBranch: () => branch,
+			getSessionId: () => "sess-9",
+			getSessionName: () => "named",
+		},
+		...overrides,
+	};
+}
+
+test("collectSnapshot sums only assistant usage on the branch", () => {
+	const branch: BranchEntryLike[] = [
+		entry({ type: "message", timestamp: "2026-01-01T00:00:00.000Z", message: { role: "user" } }),
+		entry({
+			type: "message",
+			timestamp: "2026-01-01T00:00:10.000Z",
+			message: {
+				role: "assistant",
+				usage: { input: 100, output: 20, cacheRead: 30, cacheWrite: 5, cost: { total: 0.5 } },
+			},
+		}),
+		entry({
+			type: "message",
+			timestamp: "2026-01-01T00:00:20.000Z",
+			message: {
+				role: "assistant",
+				usage: { input: 200, output: 40, cacheRead: 0, cacheWrite: 0, cost: { total: 0.25 } },
+			},
+		}),
+		entry({ type: "custom", timestamp: "2026-01-01T00:00:30.000Z" }),
+	];
+
+	const snapshotValue = collectSnapshot(fakeContext(branch), Date.parse("2026-01-01T00:10:00.000Z"));
+	assert.deepEqual(snapshotValue.totals, {
+		costUsd: 0.75,
+		durationMs: 600_000,
+	});
+	assert.equal(snapshotValue.session?.id, "sess-9");
+	assert.equal(snapshotValue.session?.name, "named");
+	assert.equal(snapshotValue.contextUsage?.tokens, 1000);
+});
+
+test("collectSnapshot reports no totals for an empty branch", () => {
+	const snapshotValue = collectSnapshot(fakeContext([]), Date.now());
+	assert.equal(snapshotValue.totals, undefined);
+	assert.equal(snapshotValue.session?.name, "named");
+});
+
+test("collectSnapshot carries the provider from ctx.model", () => {
+	const ctx = fakeContext([], { model: { id: "m", name: "M", provider: "anthropic", contextWindow: 200_000 } });
+	const snapshotValue = collectSnapshot(ctx, Date.now());
+	assert.equal(snapshotValue.model?.provider, "anthropic");
+	assert.equal((buildCclineInput(snapshotValue).model as Record<string, string>).display_name, "M (anthropic)");
+});
+
+test("collectSnapshot survives throwing context accessors", () => {
+	const ctx = fakeContext([], {
+		getContextUsage: () => {
+			throw new Error("boom");
+		},
+	});
+	const snapshotValue = collectSnapshot(ctx, Date.now());
+	assert.equal(snapshotValue.contextUsage, undefined);
+	assert.equal(buildCclineInput(snapshotValue).context_window !== undefined, true);
+});