@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/session/tree/preview.ts

@@ -0,0 +1,259 @@
+/**
+ * Single-line preview generation for /tree overlay rows.
+ *
+ * The /tree overlay flattens a TreeSnapshot into one row per turn. The raw
+ * snapshot only carries kind + ids + label; this module computes a short,
+ * single-line description for each row from the underlying structured message
+ * payload so users can recognise turns at a glance instead of seeing a wall
+ * of generic `[role]` placeholders.
+ *
+ * The function is pure: it takes a turn-shape input and returns a string. No
+ * I/O, no time, no width-aware truncation (the overlay layer applies its own
+ * width budget after calling). It is defensive against the supported message
+ * payload shapes.
+ */
+import type { ClioTurnRecord } from "../../../engine/session.js";
+import { stripTokenizerSentinels } from "../../../engine/strip-tokenizer-sentinels.js";
+
+/**
+ * Maximum characters for the inline preview slice. Keeps a row readable on
+ * an 88-column overlay even after the role marker, indent, short turn id,
+ * and optional label suffix. Callers that need a tighter budget can clamp
+ * the output further.
+ */
+export const TURN_PREVIEW_MAX_CHARS = 60;
+
+/** Minimal turn shape buildTurnPreview accepts. */
+export type TurnPreviewInput = Pick<ClioTurnRecord, "kind" | "payload">;
+
+/**
+ * Strip ANSI escape sequences. Tool outputs sometimes carry colour codes
+ * that survive into the persisted payload; rendering them inside a single
+ * row breaks the overlay's frame because pi-tui's truncateToWidth treats
+ * them as zero-width control bytes but our brandedContentRow padding then
+ * miscounts. The regexes are constructed from String.fromCharCode(0x1b) so
+ * the source file stays free of literal control bytes.
+ */
+const ESC = String.fromCharCode(0x1b);
+const ANSI_CSI_RE = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]`, "g");
+const ANSI_FALLBACK_RE = new RegExp(`${ESC}[@-_]`, "g");
+
+function stripAnsi(text: string): string {
+	return text.replace(ANSI_CSI_RE, "").replace(ANSI_FALLBACK_RE, "");
+}
+
+/**
+ * Collapse all whitespace runs (including newlines, tabs, and CR) into a
+ * single space and trim the ends. Combined with stripAnsi + sentinel
+ * stripping this guarantees a single-line preview suitable for a row.
+ */
+function collapseSingleLine(text: string): string {
+	return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Apply every defensive cleanup pass we want on persisted text before it
+ * shows up in a row. Order matters: ANSI removal must run before whitespace
+ * collapse because some CSI sequences embed literal spaces.
+ */
+function sanitize(text: string): string {
+	return collapseSingleLine(stripTokenizerSentinels(stripAnsi(text)));
+}
+
+function clamp(text: string, max: number): string {
+	if (text.length <= max) return text;
+	if (max <= 1) return text.slice(0, max);
+	return `${text.slice(0, max - 1)}…`;
+}
+
+/**
+ * Pull user-authored or assistant text from supported message payloads.
+ * Payloads may be bare strings, objects with a text property, or pi-ai
+ * content blocks. Returns null when no usable text is found.
+ */
+function extractPlainText(payload: unknown): string | null {
+	if (typeof payload === "string") {
+		const sanitized = sanitize(payload);
+		return sanitized.length > 0 ? sanitized : null;
+	}
+	if (!payload || typeof payload !== "object") return null;
+	const obj = payload as Record<string, unknown>;
+	if (typeof obj.text === "string") {
+		const sanitized = sanitize(obj.text);
+		if (sanitized.length > 0) return sanitized;
+	}
+	if (Array.isArray(obj.content)) {
+		const parts: string[] = [];
+		for (const block of obj.content) {
+			if (!block || typeof block !== "object") continue;
+			const b = block as Record<string, unknown>;
+			if (b.type === "text" && typeof b.text === "string") parts.push(b.text);
+		}
+		if (parts.length > 0) {
+			const sanitized = sanitize(parts.join(" "));
+			if (sanitized.length > 0) return sanitized;
+		}
+	}
+	return null;
+}
+
+/**
+ * Identify the most distinguishing argument value for a tool call so the
+ * preview reads like a function call. The picked key is heuristic: known
+ * tool argument shapes route to their natural identifier; everything else
+ * falls back to the first scalar arg.
+ */
+function pickToolArg(toolName: string, args: unknown): string {
+	if (!args || typeof args !== "object") return "";
+	const a = args as Record<string, unknown>;
+	const preferred: Record<string, ReadonlyArray<string>> = {
+		read: ["path"],
+		write: ["path"],
+		edit: ["path"],
+		bash: ["command"],
+		code_nav: ["query", "mode"],
+		git: ["op"],
+		verify: ["check"],
+		grep: ["pattern", "query"],
+		search: ["query", "pattern"],
+		web_fetch: ["url"],
+		web_search: ["query"],
+	};
+	const order = preferred[toolName] ?? [];
+	for (const key of order) {
+		const value = a[key];
+		if (typeof value === "string" && value.length > 0) return sanitize(value);
+		if (typeof value === "number") return String(value);
+	}
+	// Fallback: first scalar arg, in declaration order.
+	for (const [, value] of Object.entries(a)) {
+		if (typeof value === "string" && value.length > 0) return sanitize(value);
+		if (typeof value === "number" || typeof value === "boolean") return String(value);
+	}
+	return "";
+}
+
+interface ToolCallShape {
+	toolName: string;
+	args: unknown;
+}
+
+function extractToolCall(payload: unknown): ToolCallShape | null {
+	if (!payload || typeof payload !== "object") return null;
+	const p = payload as Record<string, unknown>;
+	const toolName = typeof p.name === "string" ? p.name : typeof p.toolName === "string" ? p.toolName : null;
+	if (!toolName) return null;
+	const args = p.args !== undefined ? p.args : (p.arguments ?? p.input);
+	return { toolName, args };
+}
+
+interface ToolResultShape {
+	isError: boolean;
+	text: string;
+}
+
+function extractToolResult(payload: unknown): ToolResultShape | null {
+	if (!payload || typeof payload !== "object") return null;
+	const p = payload as Record<string, unknown>;
+	if (!("toolCallId" in p) && !("result" in p) && !("isError" in p)) return null;
+	const isError = p.isError === true;
+	let text = "";
+	const result = p.result;
+	if (typeof result === "string") text = result;
+	else if (result && typeof result === "object") {
+		const r = result as Record<string, unknown>;
+		if (Array.isArray(r.content)) {
+			const parts: string[] = [];
+			for (const block of r.content) {
+				if (!block || typeof block !== "object") continue;
+				const b = block as Record<string, unknown>;
+				if (b.type === "text" && typeof b.text === "string") parts.push(b.text);
+			}
+			text = parts.join(" ");
+		} else if (typeof r.text === "string") {
+			text = r.text;
+		}
+	}
+	if (text.length === 0 && typeof p.errorMessage === "string") text = p.errorMessage;
+	return { isError, text: sanitize(text) };
+}
+
+/**
+ * Detect the assistant aborted/error sentinel. Persisted assistant turns
+ * carry `stopReason` from the engine; `"aborted"` and `"error"` warrant
+ * dedicated markers because the text body is typically empty or partial in
+ * those states.
+ */
+function assistantStopMarker(payload: unknown): "(aborted)" | "(error)" | null {
+	if (!payload || typeof payload !== "object") return null;
+	const sr = (payload as { stopReason?: unknown }).stopReason;
+	if (sr === "aborted") return "(aborted)";
+	if (sr === "error") return "(error)";
+	return null;
+}
+
+/**
+ * Compose the per-row preview for a turn. The string is single-line, ANSI-
+ * stripped, sentinel-stripped, and clamped to {@link TURN_PREVIEW_MAX_CHARS}.
+ * Empty / aborted / streaming-style states get a parenthesised marker so
+ * the row never reads as a duplicate of its neighbours.
+ */
+export function buildTurnPreview(turn: TurnPreviewInput, max: number = TURN_PREVIEW_MAX_CHARS): string {
+	const budget = Math.max(1, max);
+	switch (turn.kind) {
+		case "user": {
+			const text = extractPlainText(turn.payload);
+			return text === null ? "(empty)" : clamp(text, budget);
+		}
+		case "assistant": {
+			const stop = assistantStopMarker(turn.payload);
+			const text = extractPlainText(turn.payload);
+			if (text !== null) return clamp(text, budget);
+			if (stop !== null) return stop;
+			// No text content: typically a tool-call-only turn or a streaming
+			// shell that was persisted without a body.
+			if (
+				turn.payload &&
+				typeof turn.payload === "object" &&
+				Array.isArray((turn.payload as { content?: unknown }).content)
+			) {
+				const content = (turn.payload as { content: unknown[] }).content;
+				const toolCalls = content.filter(
+					(b) => b && typeof b === "object" && (b as { type?: unknown }).type === "toolCall",
+				);
+				if (toolCalls.length > 0) {
+					const names = toolCalls
+						.map((b) => (b as { name?: unknown }).name)
+						.filter((n): n is string => typeof n === "string");
+					if (names.length > 0) return clamp(`(tool calls) ${names.join(", ")}`, budget);
+				}
+			}
+			return "(empty)";
+		}
+		case "tool_call": {
+			const call = extractToolCall(turn.payload);
+			if (!call) return "(empty)";
+			const arg = pickToolArg(call.toolName, call.args);
+			const inner = arg.length > 0 ? `"${clamp(arg, Math.max(8, budget - call.toolName.length - 4))}"` : "";
+			const composed = `${call.toolName}(${inner})`;
+			return clamp(composed, budget);
+		}
+		case "tool_result": {
+			const result = extractToolResult(turn.payload);
+			if (!result) return "(empty)";
+			const status = result.isError ? "err" : "ok";
+			const head = `[${status}]`;
+			if (result.text.length === 0) return head;
+			const remaining = Math.max(4, budget - head.length - 1);
+			return `${head} ${clamp(result.text, remaining)}`;
+		}
+		case "system": {
+			const text = extractPlainText(turn.payload);
+			return text === null ? "(system)" : clamp(text, budget);
+		}
+		case "checkpoint":
+			return "(checkpoint)";
+		default:
+			return `(${String(turn.kind)})`;
+	}
+}

package/src/domains/session/usage.ts

@@ -0,0 +1,148 @@
+/**
+ * Fold a session ledger's assistant turns into the per-call usage the rest of
+ * Clio reports: tokens in and out, cache reads and writes, reasoning tokens,
+ * and provider-reported cost, attributed to the target and wire model that
+ * served each call.
+ *
+ * This lives in the session domain because the ledger is the only durable
+ * record of what a session spent, and three surfaces read it: the `/cost`
+ * overlay and footer reseed from it on every session change, and `clio-coder usage
+ * report` folds it across sessions. It was written for the overlay first and
+ * sat under src/interactive; a headless report reaching into the TUI surface's
+ * directory for it would have made one surface's presentation a dependency of
+ * every surface's accounting, which is the same thing the tools/interactive
+ * boundary rule exists to prevent.
+ *
+ * Assistant turns marked aborted or error are skipped for the same reason the
+ * context estimator skips them: their usage is not a completed call. A
+ * cancelled partial persists a fully populated all-zero usage object, so
+ * counting it would add an API call worth nothing.
+ */
+
+import type { SessionEntry } from "./entries.js";
+
+/** One completed assistant API call, as the ledger recorded it. */
+export interface LedgerUsageCall {
+	providerId: string;
+	modelId: string;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoningTokens: number;
+	totalTokens: number;
+	costUsd: number;
+	/** API calls this row accounts for. Absent means one, which is every message row. */
+	apiCalls?: number;
+}
+
+/** The target and model a session ran under before any modelChange row. */
+export interface SessionUsageDefaults {
+	target?: string | null;
+	model?: string | null;
+}
+
+function numberAt(source: Record<string, unknown>, key: string): number {
+	const value = source[key];
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function reasoningTokensOf(usage: Record<string, unknown>): number {
+	const direct = numberAt(usage, "reasoningTokens");
+	if (direct > 0) return direct;
+	const details = usage.outputTokensDetails ?? usage.completionTokensDetails;
+	if (details && typeof details === "object") return numberAt(details as Record<string, unknown>, "reasoningTokens");
+	return 0;
+}
+
+function stringAt(source: Record<string, unknown>, ...keys: string[]): string | null {
+	for (const key of keys) {
+		const value = source[key];
+		if (typeof value === "string" && value.trim().length > 0) return value;
+	}
+	return null;
+}
+
+/**
+ * One entry per completed assistant API call that carried provider usage.
+ *
+ * Attribution follows the live path, which records under the *target* id and
+ * the wire model rather than the runtime name. Reading the runtime out of the
+ * payload instead split one endpoint into two blocks in `/cost`, so a single
+ * `node-a` target on `llamacpp` rendered as two providers whose turn counts
+ * diverged with every resume. `modelChange` rows are replayed in order so a
+ * session that switched targets mid-way attributes each call to the one that
+ * served it.
+ */
+export function ledgerUsageCalls(
+	entries: ReadonlyArray<SessionEntry>,
+	defaults: SessionUsageDefaults = {},
+): LedgerUsageCall[] {
+	const calls: LedgerUsageCall[] = [];
+	let currentTarget = defaults.target ?? null;
+	let currentModel = defaults.model ?? null;
+	for (const entry of entries) {
+		// A compaction summarizes history through a real model call, billed like
+		// any other. Its usage rides on the compactionSummary entry rather than on
+		// an assistant message, because the summary is context machinery and never
+		// enters the conversation; folding it here is what puts it on `/cost` and
+		// in `clio-coder usage report`.
+		if (entry?.kind === "compactionSummary") {
+			const usage = entry.usage;
+			if (!usage || usage.totalTokens <= 0) continue;
+			calls.push({
+				providerId: currentTarget ?? "unknown",
+				modelId: currentModel ?? "unknown",
+				input: usage.input,
+				output: usage.output,
+				cacheRead: usage.cacheRead,
+				cacheWrite: usage.cacheWrite,
+				reasoningTokens: usage.reasoning,
+				totalTokens: usage.totalTokens,
+				costUsd: usage.cost.total,
+				// A split turn runs two summarization streams under one entry; the
+				// provider served that many calls even though one row records them.
+				apiCalls: Math.max(1, Math.round(usage.apiCalls)),
+			});
+			continue;
+		}
+		if (entry?.kind === "modelChange") {
+			const change = entry as { target?: unknown; modelId?: unknown; provider?: unknown };
+			if (typeof change.target === "string" && change.target.length > 0) currentTarget = change.target;
+			else if (typeof change.provider === "string" && change.provider.length > 0) currentTarget = change.provider;
+			if (typeof change.modelId === "string" && change.modelId.length > 0) currentModel = change.modelId;
+			continue;
+		}
+		if (entry?.kind !== "message" || entry.role !== "assistant") continue;
+		const payload = entry.payload;
+		if (!payload || typeof payload !== "object" || Array.isArray(payload)) continue;
+		const record = payload as Record<string, unknown>;
+		const stopReason = record.stopReason;
+		if (stopReason === "aborted" || stopReason === "error") continue;
+		const rawUsage = record.usage;
+		if (!rawUsage || typeof rawUsage !== "object" || Array.isArray(rawUsage)) continue;
+		const usage = rawUsage as Record<string, unknown>;
+		const input = numberAt(usage, "input");
+		const output = numberAt(usage, "output");
+		const cacheRead = numberAt(usage, "cacheRead");
+		const cacheWrite = numberAt(usage, "cacheWrite");
+		const totalTokens = numberAt(usage, "totalTokens") || input + output + cacheRead + cacheWrite;
+		// An all-zero usage block is a call that never reported anything. Adding it
+		// would inflate the call count while contributing no tokens.
+		if (totalTokens === 0) continue;
+		const cost = usage.cost;
+		const costUsd = cost && typeof cost === "object" ? numberAt(cost as Record<string, unknown>, "total") : 0;
+		calls.push({
+			providerId: currentTarget ?? stringAt(record, "provider", "api") ?? "unknown",
+			modelId: currentModel ?? stringAt(record, "responseModel", "model") ?? "unknown",
+			input,
+			output,
+			cacheRead,
+			cacheWrite,
+			reasoningTokens: reasoningTokensOf(usage),
+			totalTokens,
+			costUsd,
+		});
+	}
+	return calls;
+}

package/src/domains/session/workspace/git-probe.ts

@@ -0,0 +1,161 @@
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const TIMEOUT_MS = 1000;
+
+export interface GitProbeResult {
+	isGit: boolean;
+	branch: string | null;
+	dirty: boolean | null;
+	ahead: number | null;
+	behind: number | null;
+	recentCommits: ReadonlyArray<{ sha: string; subject: string }>;
+	remoteUrl: string | null;
+}
+
+/**
+ * The subset a live status surface actually paints. Deliberately narrower than
+ * `GitProbeResult`: ahead/behind and recent commits cost two more subprocesses
+ * per poll and are only ever read by the workspace context tool, which probes
+ * once at session bind rather than on a timer.
+ */
+export interface GitStatusProbeResult {
+	isGit: boolean;
+	branch: string | null;
+	dirty: boolean | null;
+	remoteUrl: string | null;
+}
+
+const EMPTY_PROBE: GitProbeResult = {
+	isGit: false,
+	branch: null,
+	dirty: null,
+	ahead: null,
+	behind: null,
+	recentCommits: [],
+	remoteUrl: null,
+};
+
+const EMPTY_STATUS_PROBE: GitStatusProbeResult = { isGit: false, branch: null, dirty: null, remoteUrl: null };
+
+function gitOk(cwd: string, args: string[]): string | null {
+	try {
+		const out = execFileSync("git", args, { cwd, timeout: TIMEOUT_MS, stdio: ["ignore", "pipe", "ignore"] });
+		return out.toString().trim();
+	} catch {
+		return null;
+	}
+}
+
+async function gitOkAsync(cwd: string, args: string[]): Promise<string | null> {
+	try {
+		const { stdout } = await execFileAsync("git", args, { cwd, timeout: TIMEOUT_MS, encoding: "utf8" });
+		return stdout.trim();
+	} catch {
+		return null;
+	}
+}
+
+function normalizeRemote(url: string): string {
+	let out = url.trim();
+	if (out.endsWith(".git")) out = out.slice(0, -4);
+	const sshMatch = /^git@([^:]+):(.+)$/.exec(out);
+	if (sshMatch) {
+		const [, host, path] = sshMatch;
+		return `https://${host}/${path}`;
+	}
+	return out;
+}
+
+function branchFrom(raw: string | null): string | null {
+	return raw && raw !== "HEAD" ? raw : null;
+}
+
+function dirtyFrom(status: string | null): boolean | null {
+	return status === null ? null : status.length > 0;
+}
+
+function aheadBehindFrom(raw: string | null): { ahead: number | null; behind: number | null } {
+	if (!raw) return { ahead: null, behind: null };
+	const parts = raw.split(/\s+/);
+	const a = Number.parseInt(parts[0] ?? "", 10);
+	const b = Number.parseInt(parts[1] ?? "", 10);
+	return { ahead: Number.isFinite(a) ? a : null, behind: Number.isFinite(b) ? b : null };
+}
+
+function recentCommitsFrom(log: string | null): ReadonlyArray<{ sha: string; subject: string }> {
+	if (!log) return [];
+	return log
+		.split("\n")
+		.map((line) => {
+			const tab = line.indexOf("\t");
+			if (tab < 0) return null;
+			return { sha: line.slice(0, tab), subject: line.slice(tab + 1) };
+		})
+		.filter((commit): commit is { sha: string; subject: string } => commit !== null);
+}
+
+function remoteFrom(raw: string | null): string | null {
+	return raw ? normalizeRemote(raw) : null;
+}
+
+export function probeGit(cwd: string): GitProbeResult {
+	const inside = gitOk(cwd, ["rev-parse", "--is-inside-work-tree"]);
+	if (inside !== "true") return EMPTY_PROBE;
+	const branch = branchFrom(gitOk(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]));
+	const dirty = dirtyFrom(gitOk(cwd, ["status", "--porcelain"]));
+	const { ahead, behind } = aheadBehindFrom(gitOk(cwd, ["rev-list", "--left-right", "--count", "HEAD...@{u}"]));
+	const recentCommits = recentCommitsFrom(gitOk(cwd, ["log", "-5", "--format=%H%x09%s"]));
+	const remoteUrl = remoteFrom(gitOk(cwd, ["remote", "get-url", "origin"]));
+	return { isGit: true, branch, dirty, ahead, behind, recentCommits, remoteUrl };
+}
+
+/**
+ * The full probe without blocking the event loop. Six subprocesses cost 63-100 ms
+ * of blocked loop on a large repository; the five that follow the work-tree gate
+ * are independent, so they run concurrently and the caller waits on none of them.
+ */
+export async function probeGitAsync(cwd: string): Promise<GitProbeResult> {
+	const inside = await gitOkAsync(cwd, ["rev-parse", "--is-inside-work-tree"]);
+	if (inside !== "true") return EMPTY_PROBE;
+	const [branchRaw, status, aheadBehindRaw, log, remoteRaw] = await Promise.all([
+		gitOkAsync(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+		gitOkAsync(cwd, ["status", "--porcelain"]),
+		gitOkAsync(cwd, ["rev-list", "--left-right", "--count", "HEAD...@{u}"]),
+		gitOkAsync(cwd, ["log", "-5", "--format=%H%x09%s"]),
+		gitOkAsync(cwd, ["remote", "get-url", "origin"]),
+	]);
+	const { ahead, behind } = aheadBehindFrom(aheadBehindRaw);
+	return {
+		isGit: true,
+		branch: branchFrom(branchRaw),
+		dirty: dirtyFrom(status),
+		ahead,
+		behind,
+		recentCommits: recentCommitsFrom(log),
+		remoteUrl: remoteFrom(remoteRaw),
+	};
+}
+
+/**
+ * Branch, dirty flag, and remote only: four subprocesses instead of six, run
+ * concurrently and off the loop. This is what the interactive footer polls on
+ * its ticker and re-reads at the end of every turn.
+ */
+export async function probeGitStatusAsync(cwd: string): Promise<GitStatusProbeResult> {
+	const inside = await gitOkAsync(cwd, ["rev-parse", "--is-inside-work-tree"]);
+	if (inside !== "true") return EMPTY_STATUS_PROBE;
+	const [branchRaw, status, remoteRaw] = await Promise.all([
+		gitOkAsync(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+		gitOkAsync(cwd, ["status", "--porcelain"]),
+		gitOkAsync(cwd, ["remote", "get-url", "origin"]),
+	]);
+	return {
+		isGit: true,
+		branch: branchFrom(branchRaw),
+		dirty: dirtyFrom(status),
+		remoteUrl: remoteFrom(remoteRaw),
+	};
+}

package/src/domains/session/workspace/index.ts

@@ -0,0 +1,4 @@
+export type { GitProbeResult, GitStatusProbeResult } from "./git-probe.js";
+export { probeGit, probeGitAsync, probeGitStatusAsync } from "./git-probe.js";
+export type { WorkspaceCommit, WorkspaceSnapshot } from "./snapshot.js";
+export { emptyWorkspaceSnapshot, probeWorkspace, probeWorkspaceAsync } from "./snapshot.js";