@caph42/pi-ccline 0.0.0-stage → 0.1.0

package/extensions/pi-ccline/input.ts

@@ -0,0 +1,241 @@
+// Maps pi session state to the JSON shape CCometixLine reads from stdin.
+// Every helper here is pure so the mapping can be tested without a session.
+// The upstream schema (src/input.rs, ccline 2.0.1) is entirely optional and
+// lenient, so unknown values are omitted instead of guessed.
+
+/** Thinking levels ccline renders in its effort segment. */
+const EFFORT_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh", "max"]);
+
+export interface PiSnapshotModel {
+	id?: string | undefined;
+	/** Human readable model name; ccline shows this as `display_name`. */
+	name?: string | undefined;
+	/** Provider id from pi ("anthropic", "openai-codex", ...). */
+	provider?: string | undefined;
+	contextWindow?: number | undefined;
+}
+
+export interface PiSnapshotContextUsage {
+	tokens: number | null;
+	contextWindow: number | null;
+	percent: number | null;
+}
+
+export interface PiSnapshotTotals {
+	/** Cumulative USD cost over the visible branch. */
+	costUsd?: number | undefined;
+	/** Wall-clock time since the first visible branch entry. */
+	durationMs?: number | undefined;
+}
+
+export interface PiSnapshotSession {
+	id?: string | undefined;
+	name?: string | undefined;
+}
+
+export interface PiSnapshot {
+	cwd: string;
+	model?: PiSnapshotModel | undefined;
+	thinkingLevel?: string | undefined;
+	contextUsage?: PiSnapshotContextUsage | undefined;
+	totals?: PiSnapshotTotals | undefined;
+	session?: PiSnapshotSession | undefined;
+}
+
+/** The subset of pi's session entries this extension reads. */
+export interface BranchEntryLike {
+	type?: string | undefined;
+	/** ISO timestamp written by pi when the entry was appended. */
+	timestamp?: string | undefined;
+	message?:
+		| {
+				role?: string | undefined;
+				usage?:
+					| {
+							input?: number | undefined;
+							output?: number | undefined;
+							cacheRead?: number | undefined;
+							cacheWrite?: number | undefined;
+							cost?: { total?: number | undefined } | undefined;
+					  }
+					| undefined;
+		  }
+		| undefined;
+}
+
+/** The subset of `ExtensionContext` used to build a snapshot. */
+export interface SnapshotContextLike {
+	cwd: string;
+	model?:
+		| {
+				id?: string | undefined;
+				name?: string | undefined;
+				provider?: string | undefined;
+				contextWindow?: number | undefined;
+		  }
+		| undefined;
+	thinkingLevel?: string | undefined;
+	getContextUsage(): { tokens: number | null; contextWindow: number; percent: number | null } | undefined;
+	sessionManager: {
+		getBranch(): readonly BranchEntryLike[];
+		getSessionId?(): string;
+		getSessionName?(): string | undefined;
+	};
+}
+
+function num(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function finite(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function round1(value: number): number {
+	return Math.round(value * 10) / 10;
+}
+
+function trimmed(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const text = value.trim();
+	return text ? text : undefined;
+}
+
+function attempt<T>(read: () => T): T | undefined {
+	try {
+		return read();
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Collect the state pi exposes into a plain snapshot.
+ * Values that cannot be read are left undefined so they are omitted downstream.
+ */
+export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnapshot {
+	const usage = attempt(() => ctx.getContextUsage());
+	const branch = attempt(() => ctx.sessionManager.getBranch()) ?? [];
+
+	let costUsd = 0;
+	let sawAssistantUsage = false;
+	let firstTimestamp: number | undefined;
+
+	for (const entry of branch) {
+		const timestamp = entry.timestamp ? Date.parse(entry.timestamp) : Number.NaN;
+		if (Number.isFinite(timestamp) && (firstTimestamp === undefined || timestamp < firstTimestamp)) {
+			firstTimestamp = timestamp;
+		}
+		if (entry.type !== "message" || entry.message?.role !== "assistant") continue;
+		const entryUsage = entry.message.usage;
+		if (!entryUsage) continue;
+		sawAssistantUsage = true;
+		costUsd += num(entryUsage.cost?.total);
+	}
+
+	const totals: PiSnapshotTotals | undefined = sawAssistantUsage
+		? {
+				costUsd,
+				durationMs: firstTimestamp === undefined ? undefined : Math.max(0, nowMs - firstTimestamp),
+			}
+		: undefined;
+
+	const sessionId = attempt(() => ctx.sessionManager.getSessionId?.());
+	const sessionName = attempt(() => ctx.sessionManager.getSessionName?.());
+
+	return {
+		cwd: ctx.cwd,
+		model: ctx.model,
+		thinkingLevel: ctx.thinkingLevel,
+		contextUsage: usage
+			? {
+					tokens: usage.tokens,
+					contextWindow: finite(usage.contextWindow) ?? null,
+					percent: usage.percent,
+				}
+			: undefined,
+		totals,
+		session: { id: trimmed(sessionId), name: trimmed(sessionName) },
+	};
+}
+
+export interface BuildCclineInputOptions {
+	/** Append the provider to the model segment: `Sonnet 4.5 (anthropic)`. */
+	showProvider?: boolean | undefined;
+}
+
+/**
+ * ccline 2.0.1 has no provider field: the only place a provider can surface is
+ * the model segment, which renders `display_name` verbatim. So the provider is
+ * appended there, and skipped when the name already carries it.
+ */
+export function withProvider(name: string, provider: string | undefined, enabled: boolean): string {
+	if (!name || !provider || !enabled) return name;
+	const suffix = `(${provider})`;
+	return name.toLowerCase().endsWith(suffix.toLowerCase()) ? name : `${name} ${suffix}`;
+}
+
+/**
+ * Build the ccline stdin payload.
+ *
+ * `version` is intentionally never set: ccline 2.0.1 parses it as the Claude
+ * Code version and rejects anything older than 2.1.153.
+ */
+export function buildCclineInput(snapshot: PiSnapshot, options: BuildCclineInputOptions = {}): Record<string, unknown> {
+	const input: Record<string, unknown> = {};
+
+	const cwd = trimmed(snapshot.cwd);
+	if (cwd) {
+		input.cwd = cwd;
+		input.workspace = { current_dir: cwd };
+	}
+
+	const modelId = trimmed(snapshot.model?.id);
+	const modelName = trimmed(snapshot.model?.name);
+	if (modelId || modelName) {
+		const model: Record<string, string> = {};
+		if (modelId) model.id = modelId;
+		model.display_name = withProvider(modelName ?? modelId ?? "", trimmed(snapshot.model?.provider), options.showProvider !== false);
+		input.model = model;
+	}
+
+	const level = trimmed(snapshot.thinkingLevel);
+	if (level && EFFORT_LEVELS.has(level)) {
+		input.effort = { level };
+	}
+
+	const usage = snapshot.contextUsage;
+	const totals = snapshot.totals;
+	const contextWindowSize = finite(usage?.contextWindow) ?? finite(snapshot.model?.contextWindow);
+	// Only the live context goes into context_window: pi reports an aggregate
+	// estimate, carried as input tokens. Cumulative session totals are not sent,
+	// because ccline prefers them over current_usage and would then show a token
+	// count that disagrees with used_percentage.
+	const currentTokens = finite(usage?.tokens);
+	const percent = finite(usage?.percent);
+
+	if (contextWindowSize !== undefined || currentTokens !== undefined || percent !== undefined) {
+		const contextWindow: Record<string, unknown> = {};
+		if (contextWindowSize !== undefined) contextWindow.context_window_size = Math.round(contextWindowSize);
+		if (currentTokens !== undefined) contextWindow.current_usage = { input_tokens: Math.round(currentTokens) };
+		if (percent !== undefined) contextWindow.used_percentage = round1(percent);
+		input.context_window = contextWindow;
+	}
+
+	const costUsd = finite(totals?.costUsd);
+	const durationMs = finite(totals?.durationMs);
+	if (costUsd !== undefined || durationMs !== undefined) {
+		const cost: Record<string, unknown> = {};
+		if (costUsd !== undefined) cost.total_cost_usd = costUsd;
+		if (durationMs !== undefined) cost.total_duration_ms = Math.round(durationMs);
+		input.cost = cost;
+	}
+
+	const sessionId = trimmed(snapshot.session?.id);
+	if (sessionId) input.session_id = sessionId;
+	const sessionName = trimmed(snapshot.session?.name);
+	if (sessionName) input.session_name = sessionName;
+
+	// rate_limits has no pi data source; omitting it removes the quota segment.
+	return input;
+}

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

@@ -0,0 +1,285 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { RefreshScheduler, RefreshTicker, type TimerHandle } from "./refresh.ts";
+
+/** Deterministic clock plus a manual timer queue. */
+class FakeClock {
+	time = 0;
+	private nextId = 1;
+	private timers = new Map<number, { at: number; callback: () => void }>();
+
+	now = (): number => this.time;
+
+	setTimer = (callback: () => void, delayMs: number): TimerHandle => {
+		const id = this.nextId++;
+		this.timers.set(id, { at: this.time + delayMs, callback });
+		return id as unknown as TimerHandle;
+	};
+
+	clearTimer = (handle: TimerHandle): void => {
+		this.timers.delete(handle as unknown as number);
+	};
+
+	get pending(): number {
+		return this.timers.size;
+	}
+
+	/** Advance time and fire due timers, letting awaited microtasks settle. */
+	async advance(ms: number): Promise<void> {
+		const target = this.time + ms;
+		for (;;) {
+			await flush();
+			const due = [...this.timers.entries()]
+				.filter(([, timer]) => timer.at <= target)
+				.sort((a, b) => a[1].at - b[1].at)[0];
+			if (!due) break;
+			const [id, timer] = due;
+			this.timers.delete(id);
+			this.time = Math.max(this.time, timer.at);
+			timer.callback();
+		}
+		this.time = Math.max(this.time, target);
+		await flush();
+	}
+}
+
+async function flush(): Promise<void> {
+	for (let i = 0; i < 5; i += 1) await Promise.resolve();
+}
+
+function deferred() {
+	let resolve!: () => void;
+	const promise = new Promise<void>((resolvePromise) => {
+		resolve = resolvePromise;
+	});
+	return { promise, resolve };
+}
+
+function makeScheduler(clock: FakeClock, task: () => Promise<void>, throttleMs = 1000) {
+	return new RefreshScheduler({ throttleMs, task, now: clock.now, setTimer: clock.setTimer, clearTimer: clock.clearTimer });
+}
+
+/** Deterministic clock for interval timers; unlike FakeClock they fire repeatedly. */
+class FakeIntervalClock {
+	time = 0;
+	private nextId = 1;
+	private timers = new Map<number, { every: number; at: number; callback: () => void }>();
+
+	setInterval = (callback: () => void, delayMs: number): TimerHandle => {
+		const id = this.nextId++;
+		this.timers.set(id, { every: Math.max(1, delayMs), at: this.time + delayMs, callback });
+		return id as unknown as TimerHandle;
+	};
+
+	clearInterval = (handle: TimerHandle): void => {
+		this.timers.delete(handle as unknown as number);
+	};
+
+	get pending(): number {
+		return this.timers.size;
+	}
+
+	async advance(ms: number): Promise<void> {
+		const target = this.time + ms;
+		for (;;) {
+			await flush();
+			const due = [...this.timers.entries()]
+				.filter(([, timer]) => timer.at <= target)
+				.sort((a, b) => a[1].at - b[1].at)[0];
+			if (!due) break;
+			const [id, timer] = due;
+			this.time = Math.max(this.time, timer.at);
+			timer.at += timer.every;
+			timer.callback();
+			if (!this.timers.has(id)) continue;
+		}
+		this.time = Math.max(this.time, target);
+		await flush();
+	}
+}
+
+function makeTicker(clock: FakeIntervalClock, intervalMs: number, onTick: () => void) {
+	return new RefreshTicker({ intervalMs, onTick, setInterval: clock.setInterval, clearInterval: clock.clearInterval });
+}
+
+test("the ticker asks for a refresh once per interval", async () => {
+	const clock = new FakeIntervalClock();
+	let ticks = 0;
+	const ticker = makeTicker(clock, 1000, () => {
+		ticks += 1;
+	});
+
+	ticker.start();
+	assert.equal(ticks, 0, "starting must not tick immediately");
+	await clock.advance(3500);
+	assert.equal(ticks, 3);
+	ticker.stop();
+});
+
+test("starting twice does not stack intervals and stopping halts them", async () => {
+	const clock = new FakeIntervalClock();
+	let ticks = 0;
+	const ticker = makeTicker(clock, 1000, () => {
+		ticks += 1;
+	});
+
+	ticker.start();
+	ticker.start();
+	assert.equal(clock.pending, 1);
+	await clock.advance(2000);
+	assert.equal(ticks, 2);
+
+	ticker.stop();
+	assert.equal(clock.pending, 0);
+	await clock.advance(5000);
+	assert.equal(ticks, 2, "no ticks after stop");
+});
+
+test("a zero interval never starts a timer", async () => {
+	const clock = new FakeIntervalClock();
+	let ticks = 0;
+	const ticker = makeTicker(clock, 0, () => {
+		ticks += 1;
+	});
+
+	ticker.start();
+	assert.equal(ticker.isRunning, false);
+	assert.equal(clock.pending, 0);
+	await clock.advance(10_000);
+	assert.equal(ticks, 0);
+});
+
+test("a throwing tick does not kill the ticker", async () => {
+	const clock = new FakeIntervalClock();
+	let ticks = 0;
+	const ticker = makeTicker(clock, 1000, () => {
+		ticks += 1;
+		throw new Error("boom");
+	});
+
+	ticker.start();
+	await clock.advance(2500);
+	assert.equal(ticks, 2);
+	ticker.stop();
+});
+
+test("request never runs the task synchronously", async () => {
+	const clock = new FakeClock();
+	let runs = 0;
+	const scheduler = makeScheduler(clock, async () => {
+		runs += 1;
+	});
+
+	scheduler.request();
+	assert.equal(runs, 0, "render passes must not spawn inline");
+
+	await clock.advance(0);
+	assert.equal(runs, 1);
+	scheduler.dispose();
+});
+
+test("a burst of requests collapses into one run", async () => {
+	const clock = new FakeClock();
+	let runs = 0;
+	const scheduler = makeScheduler(clock, async () => {
+		runs += 1;
+	});
+
+	scheduler.request();
+	scheduler.request();
+	scheduler.request();
+	await clock.advance(0);
+	assert.equal(runs, 1);
+	scheduler.dispose();
+});
+
+test("requests during a run collapse into a single follow-up that sees latest state", async () => {
+	const clock = new FakeClock();
+	const gate = deferred();
+	let runs = 0;
+	let observed = -1;
+	let state = 0;
+	const scheduler = makeScheduler(clock, async () => {
+		runs += 1;
+		observed = state;
+		if (runs === 1) await gate.promise;
+	});
+
+	scheduler.request();
+	await clock.advance(0);
+	assert.equal(runs, 1);
+
+	state = 1;
+	scheduler.request();
+	state = 2;
+	scheduler.request();
+	state = 3;
+	scheduler.request();
+	assert.equal(runs, 1, "still single-flight");
+
+	gate.resolve();
+	await clock.advance(1000);
+	assert.equal(runs, 2);
+	assert.equal(observed, 3, "latest wins");
+	scheduler.dispose();
+});
+
+test("refreshes stay at least throttleMs apart", async () => {
+	const clock = new FakeClock();
+	const starts: number[] = [];
+	const scheduler = makeScheduler(clock, async () => {
+		starts.push(clock.time);
+	});
+
+	scheduler.request();
+	await clock.advance(0);
+	assert.deepEqual(starts, [0]);
+
+	// Immediate second request has to wait for the throttle window.
+	await clock.advance(100);
+	scheduler.request();
+	await clock.advance(100);
+	assert.deepEqual(starts, [0], "not yet");
+
+	await clock.advance(800);
+	assert.deepEqual(starts, [0, 1000]);
+	scheduler.dispose();
+});
+
+test("dispose stops pending and future runs", async () => {
+	const clock = new FakeClock();
+	let runs = 0;
+	const scheduler = makeScheduler(clock, async () => {
+		runs += 1;
+	});
+
+	scheduler.request();
+	scheduler.dispose();
+	await clock.advance(5000);
+	assert.equal(runs, 0);
+	assert.equal(clock.pending, 0);
+
+	scheduler.request();
+	await clock.advance(5000);
+	assert.equal(runs, 0);
+});
+
+test("a throwing task does not wedge the scheduler", async () => {
+	const clock = new FakeClock();
+	let runs = 0;
+	const scheduler = makeScheduler(clock, async () => {
+		runs += 1;
+		throw new Error("boom");
+	});
+
+	scheduler.request();
+	await clock.advance(0);
+	assert.equal(runs, 1);
+	assert.equal(scheduler.isRunning, false);
+
+	scheduler.request();
+	await clock.advance(1000);
+	assert.equal(runs, 2);
+	scheduler.dispose();
+});

package/extensions/pi-ccline/refresh.ts

@@ -0,0 +1,145 @@
+// Single-flight, throttled refresh scheduler.
+// The footer's render(width) runs on every repaint, so refresh work must never
+// start synchronously from there: request() always defers to a timer, and at
+// most one task runs at a time. Extra requests made while a task is running
+// collapse into one follow-up run that reads the latest state (latest wins).
+
+export type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface RefreshSchedulerOptions {
+	/** Minimum delay between two starts. Callers pass a value already clamped to >= 1000. */
+	throttleMs: number;
+	task: () => Promise<void>;
+	now?: () => number;
+	setTimer?: (callback: () => void, delayMs: number) => TimerHandle;
+	clearTimer?: (handle: TimerHandle) => void;
+}
+
+export interface RefreshTickerOptions {
+	/** 0 (or any non-positive value) disables ticking. */
+	intervalMs: number;
+	onTick: () => void;
+	setInterval?: (callback: () => void, delayMs: number) => TimerHandle;
+	clearInterval?: (handle: TimerHandle) => void;
+}
+
+/**
+ * Drives time-based parts of the footer. Event-driven refreshes cannot advance
+ * a clock, so while the agent runs a fixed interval asks the scheduler for a
+ * fresh frame. stop() only clears the timer: a request already queued in the
+ * scheduler may still land once, and nothing is scheduled after that.
+ */
+export class RefreshTicker {
+	private readonly intervalMs: number;
+	private readonly onTick: () => void;
+	private readonly setTimer: (callback: () => void, delayMs: number) => TimerHandle;
+	private readonly clearTimer: (handle: TimerHandle) => void;
+	private handle: TimerHandle | null = null;
+
+	constructor(options: RefreshTickerOptions) {
+		this.intervalMs = Number.isFinite(options.intervalMs) ? options.intervalMs : 0;
+		this.onTick = options.onTick;
+		this.setTimer = options.setInterval ?? ((callback, delayMs) => setInterval(callback, delayMs));
+		this.clearTimer = options.clearInterval ?? ((handle) => clearInterval(handle));
+	}
+
+	get isRunning(): boolean {
+		return this.handle !== null;
+	}
+
+	/** Idempotent: a second start does not stack another interval. */
+	start(): void {
+		if (this.handle !== null || this.intervalMs <= 0) return;
+		this.handle = this.setTimer(() => {
+			// The scheduler reports its own failures; a throw must not kill the timer.
+			try {
+				this.onTick();
+			} catch {
+				// ignore
+			}
+		}, this.intervalMs);
+	}
+
+	stop(): void {
+		if (this.handle === null) return;
+		this.clearTimer(this.handle);
+		this.handle = null;
+	}
+}
+
+export class RefreshScheduler {
+	private readonly throttleMs: number;
+	private readonly task: () => Promise<void>;
+	private readonly now: () => number;
+	private readonly setTimer: (callback: () => void, delayMs: number) => TimerHandle;
+	private readonly clearTimer: (handle: TimerHandle) => void;
+
+	private timer: TimerHandle | null = null;
+	private pending = false;
+	private running = false;
+	private disposed = false;
+	private lastRunAt = Number.NEGATIVE_INFINITY;
+
+	/** Number of task runs; used by tests and `/pi-ccline status`. */
+	runs = 0;
+
+	constructor(options: RefreshSchedulerOptions) {
+		this.throttleMs = Number.isFinite(options.throttleMs) ? Math.max(0, options.throttleMs) : 0;
+		this.task = options.task;
+		this.now = options.now ?? (() => Date.now());
+		this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+		this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+	}
+
+	get isRunning(): boolean {
+		return this.running;
+	}
+
+	get isDisposed(): boolean {
+		return this.disposed;
+	}
+
+	/** Ask for a refresh. Safe to call from a render pass: it never runs the task inline. */
+	request(): void {
+		if (this.disposed) return;
+		this.pending = true;
+		this.arm();
+	}
+
+	dispose(): void {
+		this.disposed = true;
+		this.pending = false;
+		if (this.timer !== null) {
+			this.clearTimer(this.timer);
+			this.timer = null;
+		}
+	}
+
+	private arm(): void {
+		if (this.disposed || this.running || this.timer !== null || !this.pending) return;
+		const elapsed = this.now() - this.lastRunAt;
+		const delay = elapsed >= this.throttleMs ? 0 : Math.max(0, this.throttleMs - elapsed);
+		this.timer = this.setTimer(() => {
+			this.timer = null;
+			void this.flush();
+		}, delay);
+	}
+
+	private async flush(): Promise<void> {
+		if (this.disposed || this.running || !this.pending) return;
+		this.pending = false;
+		this.running = true;
+		this.lastRunAt = this.now();
+		this.runs += 1;
+		try {
+			await this.task();
+		} catch {
+			// The task reports its own failures through the frame; a throw must not
+			// leave the scheduler stuck in the running state.
+		} finally {
+			this.running = false;
+		}
+		if (this.disposed) return;
+		this.arm();
+	}
+}