@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/domains/session/context-ledger.ts

@@ -0,0 +1,362 @@
+/**
+ * Holistic context-window accounting.
+ *
+ * `context-accounting.ts` answers "how full is the window" with a coarse four
+ * way split that the footer bar consumes. This module answers the richer
+ * question the `/context` overlay asks: where does every occupied token live?
+ * It folds the compiled prompt segment manifest, the active tool schemas, the
+ * conversation, and the autocompact reserve into a single categorized ledger
+ * whose content groups always sum to one authoritative `usedTokens` figure.
+ *
+ * The total respects two floors so the breakdown never lies to the user:
+ *  - the decomposed estimate (sum of every category we can name), and
+ *  - the live anchored total (provider-measured usage when one exists).
+ * When the measured total exceeds the decomposition, the delta is attributed
+ * to Messages — the only category that grows turn over turn — mirroring the
+ * proportional reconciliation the footer bar already performs.
+ */
+
+import type { ContextWindowSource } from "../providers/index.js";
+import { DEFAULT_COMPACTION_THRESHOLD } from "./compaction/auto.js";
+
+/** Distinct buckets a context window is divided into for display. */
+export type ContextLedgerCategory =
+	| "system"
+	| "tools"
+	| "agents"
+	| "skills"
+	| "memory"
+	| "project"
+	| "messages"
+	| "pending"
+	| "reserve"
+	| "free"
+	| "streaming";
+
+/** A compiled-prompt segment with its estimated token cost. */
+export interface ContextLedgerSegment {
+	id: string;
+	tokenEstimate: number;
+}
+
+export interface BuildContextLedgerInput {
+	provider: string | null;
+	model: string | null;
+	/** Reported model context window in tokens; 0 or null when unknown. */
+	contextWindow: number | null;
+	/** Which layer answered `contextWindow`; omitted before a runtime resolves. */
+	contextWindowSource?: ContextWindowSource | null;
+	/**
+	 * Per-segment token estimates from the prompt compiler's segment manifest.
+	 * When empty, `systemPromptTokens` is used as a single opaque system bucket.
+	 */
+	promptSegments?: ReadonlyArray<ContextLedgerSegment>;
+	/** Fallback opaque system-prompt estimate when no segment manifest exists. */
+	systemPromptTokens?: number;
+	/** Serialized active tool-schema token estimate (the JSON the provider sees). */
+	toolSchemaTokens?: number;
+	/** Number of active tool schemas this turn. */
+	toolCount?: number;
+	/** Conversation message token estimate. */
+	messageTokens?: number;
+	/** Tokens for text the user has typed but not yet submitted. */
+	pendingTokens?: number;
+	/** In-flight streaming output tokens. */
+	streamingTokens?: number;
+	agentsTokens?: number;
+	skillsTokens?: number;
+	memoryTokens?: number;
+	projectTokens?: number;
+	/**
+	 * Authoritative live total, already anchored to the latest provider usage
+	 * when one is available. Acts as the measured floor for `usedTokens`.
+	 */
+	liveTotalTokens?: number | null;
+	/** True when `liveTotalTokens` is anchored to real provider-reported usage. */
+	measured?: boolean;
+	/** Compaction trigger ratio (0..1); null when compaction is unconfigured. */
+	compactionThreshold?: number | null;
+	/** Whether automatic compaction is enabled. */
+	compactionAuto?: boolean;
+	/**
+	 * Project-context preload class label from the compiled session prompt,
+	 * e.g. "full (5.2kB, 130 lines)" or "synopsis (reason: size)". Null before
+	 * a prompt has compiled.
+	 */
+	projectPreload?: string | null;
+	/**
+	 * Absolute paths of the effective project handbooks the compiled prompt
+	 * selected, ancestor to nearest. Null before a prompt has compiled; empty
+	 * when the workspace has no parseable handbook.
+	 */
+	projectHandbookFiles?: ReadonlyArray<string> | null;
+	lastCompaction?: {
+		stage: string;
+		tokensBefore: number;
+		tokensAfter: number;
+		trigger: string;
+	} | null;
+	/** Prompt-cache honesty line; null until a turn has compiled and settled. */
+	promptCache?: PromptCacheStats | null;
+}
+
+/**
+ * Shell reuse and provider cache reuse are different facts and the overlay
+ * shows both: `shellReused` only means Clio's session-shell hash matched the
+ * previous turn; `cacheReadTokens` is what the provider actually reused.
+ * A reused shell with zero cache reads is the dishonest case this surfaces.
+ */
+export interface PromptCacheStats {
+	/** Compiled session-shell hash matched the previous turn. */
+	shellReused: boolean;
+	/** Provider-reported cache-read tokens for the last run; null when the provider reports no cache usage. */
+	cacheReadTokens: number | null;
+	/** Provider-reported cache-write tokens for the last run. */
+	cacheWriteTokens: number | null;
+	/** Provider-reported uncached input tokens for the last run. */
+	uncachedInputTokens: number | null;
+	/**
+	 * Cache verdict of the run's first API call, classified from the
+	 * provider-reported usage by `backendCacheVerdict`. Null before any
+	 * settled run. "Shell reused but backend cold" is the dishonest
+	 * combination the overlay renders as a warning.
+	 */
+	backendVerdict: "hot" | "partial" | "cold" | "small" | null;
+}
+
+export interface ContextLedgerGroup {
+	category: ContextLedgerCategory;
+	label: string;
+	tokens: number;
+	/** Share of the context window (0..100); null when the window is unknown. */
+	percent: number | null;
+}
+
+export interface ContextLedger {
+	provider: string | null;
+	model: string | null;
+	/** Context window in tokens; 0 when unknown. */
+	contextWindow: number;
+	/**
+	 * Which layer answered `contextWindow`. Null when the ledger was built
+	 * without a resolved runtime. The overlay states it: a window read off a
+	 * loaded instance and one assumed from a catalog are different claims, and
+	 * the difference decides whether autocompact fires in time.
+	 */
+	contextWindowSource: ContextWindowSource | null;
+	/** Sum of every content category (system..pending). */
+	usedTokens: number;
+	/** Autocompact headroom held in reserve above the conversation. */
+	reserveTokens: number;
+	/** Window left after used + reserve; 0 when the window is unknown. */
+	freeTokens: number;
+	/** used/window as a percentage; null when the window is unknown. */
+	percent: number | null;
+	/** True when `usedTokens` is anchored to provider-measured usage. */
+	measured: boolean;
+	compactionThreshold: number | null;
+	compactionAuto: boolean;
+	/** Preload class label for the project category detail line; null when unknown. */
+	projectPreload: string | null;
+	/**
+	 * Which handbook files won for this session, ancestor to nearest (an
+	 * override resets the inherited chain). Null before a prompt has compiled.
+	 */
+	projectHandbookFiles: ReadonlyArray<string> | null;
+	toolCount: number;
+	/** Non-empty content categories in display order (excludes reserve/free). */
+	groups: ReadonlyArray<ContextLedgerGroup>;
+	/** Every category including reserve and free, for the proportional meter. */
+	meter: ReadonlyArray<ContextLedgerGroup>;
+	lastCompaction?: {
+		stage: string;
+		tokensBefore: number;
+		tokensAfter: number;
+		trigger: string;
+	} | null;
+	promptCache: PromptCacheStats | null;
+}
+
+/** Maps a prompt segment id to the ledger bucket it belongs to. */
+const SEGMENT_CATEGORY: Readonly<Record<string, ContextLedgerCategory>> = {
+	identity: "system",
+	"operating-contract": "system",
+	delegation: "agents",
+	skills: "skills",
+	safety: "system",
+	runtime: "system",
+	"tool-contract": "system",
+	"retrieval-hints": "system",
+	"tool-catalog": "tools",
+	"tools-and-agents": "agents",
+	"agent-fleet-deltas": "agents",
+	"skills-catalog": "skills",
+	memory: "memory",
+	"project-context": "project",
+	"context.project-rules": "project",
+	"context.operator-profile": "memory",
+	"context.clio-repo-awareness": "system",
+	"history-summary": "messages",
+};
+
+/** Human labels for each bucket, shown verbatim in the overlay legend. */
+export const CONTEXT_CATEGORY_LABEL: Readonly<Record<ContextLedgerCategory, string>> = {
+	system: "System prompt",
+	tools: "Tool definitions",
+	agents: "Agent fleet",
+	skills: "Skills",
+	memory: "Memory",
+	project: "Project context",
+	messages: "Messages",
+	pending: "Pending input",
+	reserve: "Autocompact reserve",
+	free: "Free space",
+	streaming: "Streaming output",
+};
+
+/** Display order for the content categories and the meter. */
+const CONTENT_ORDER: ReadonlyArray<ContextLedgerCategory> = [
+	"system",
+	"tools",
+	"agents",
+	"skills",
+	"memory",
+	"project",
+	"messages",
+	"pending",
+	"streaming",
+];
+
+/**
+ * Single source of truth for the segment-id → bucket mapping. The snapshot
+ * ledger in `context-accounting.ts` reuses this so the overlay and the
+ * persisted JSONL accounting can never disagree about where a segment lives.
+ */
+export function categoryForSegment(id: string): ContextLedgerCategory {
+	return SEGMENT_CATEGORY[id] ?? "system";
+}
+
+function finiteNonNegative(value: number | null | undefined): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function percentOf(tokens: number, window: number): number | null {
+	if (window <= 0) return null;
+	return Math.min(100, (tokens / window) * 100);
+}
+
+/**
+ * Fold all context sources into a categorized ledger. Pure and synchronous so
+ * it can be unit-tested and called on every overlay open without side effects.
+ */
+export function buildContextLedger(input: BuildContextLedgerInput): ContextLedger {
+	const window = finiteNonNegative(input.contextWindow);
+
+	const raw: Record<ContextLedgerCategory, number> = {
+		system: 0,
+		tools: 0,
+		agents: 0,
+		skills: 0,
+		memory: 0,
+		project: 0,
+		messages: 0,
+		pending: 0,
+		reserve: 0,
+		free: 0,
+		streaming: 0,
+	};
+
+	const segments = input.promptSegments ?? [];
+	if (segments.length > 0) {
+		for (const segment of segments) {
+			raw[categoryForSegment(segment.id)] += finiteNonNegative(segment.tokenEstimate);
+		}
+	} else {
+		raw.system += finiteNonNegative(input.systemPromptTokens);
+	}
+	raw.tools += finiteNonNegative(input.toolSchemaTokens);
+	raw.messages += finiteNonNegative(input.messageTokens);
+	raw.pending += finiteNonNegative(input.pendingTokens);
+	raw.streaming += finiteNonNegative(input.streamingTokens);
+	raw.agents += finiteNonNegative(input.agentsTokens);
+	raw.skills += finiteNonNegative(input.skillsTokens);
+	raw.memory += finiteNonNegative(input.memoryTokens);
+	raw.project += finiteNonNegative(input.projectTokens);
+
+	const decomposed = CONTENT_ORDER.reduce((sum, category) => sum + raw[category], 0);
+	const liveTotal = finiteNonNegative(input.liveTotalTokens);
+
+	// Reconcile against the measured floor: attribute any excess the provider
+	// counted beyond our decomposition to the conversation, the one category
+	// that grows each turn.
+	if (liveTotal > decomposed) {
+		raw.messages += liveTotal - decomposed;
+	}
+	const usedTokens = Math.max(decomposed, liveTotal);
+
+	const effectiveThreshold =
+		typeof input.compactionThreshold === "number" && input.compactionThreshold > 0 && input.compactionThreshold < 1
+			? input.compactionThreshold
+			: input.compactionAuto
+				? DEFAULT_COMPACTION_THRESHOLD
+				: null;
+
+	let reserveTokens = 0;
+	let freeTokens = 0;
+	if (window > 0) {
+		const remaining = Math.max(0, window - usedTokens);
+		reserveTokens = effectiveThreshold !== null ? Math.min(Math.round(window * (1 - effectiveThreshold)), remaining) : 0;
+		freeTokens = Math.max(0, window - usedTokens - reserveTokens);
+	}
+
+	const groups: ContextLedgerGroup[] = [];
+	for (const category of CONTENT_ORDER) {
+		const tokens = raw[category];
+		if (tokens <= 0) continue;
+		groups.push({
+			category,
+			label: CONTEXT_CATEGORY_LABEL[category],
+			tokens,
+			percent: percentOf(tokens, window),
+		});
+	}
+
+	const meter: ContextLedgerGroup[] = [...groups];
+	if (reserveTokens > 0) {
+		meter.push({
+			category: "reserve",
+			label: CONTEXT_CATEGORY_LABEL.reserve,
+			tokens: reserveTokens,
+			percent: percentOf(reserveTokens, window),
+		});
+	}
+	if (window > 0) {
+		meter.push({
+			category: "free",
+			label: CONTEXT_CATEGORY_LABEL.free,
+			tokens: freeTokens,
+			percent: percentOf(freeTokens, window),
+		});
+	}
+
+	return {
+		provider: input.provider ?? null,
+		model: input.model ?? null,
+		contextWindow: window,
+		contextWindowSource: input.contextWindowSource ?? null,
+		usedTokens,
+		reserveTokens,
+		freeTokens,
+		percent: percentOf(usedTokens, window),
+		measured: input.measured === true && liveTotal > 0,
+		compactionThreshold: effectiveThreshold,
+		compactionAuto: input.compactionAuto === true,
+		projectPreload: input.projectPreload ?? null,
+		projectHandbookFiles: input.projectHandbookFiles ?? null,
+		toolCount: Math.max(0, Math.floor(input.toolCount ?? 0)),
+		groups,
+		meter,
+		lastCompaction: input.lastCompaction ?? null,
+		promptCache: input.promptCache ?? null,
+	};
+}

package/src/domains/session/contract.ts

@@ -0,0 +1,159 @@
+import type { SkillActivation } from "../../core/skill-activation.js";
+import type { ClioSessionMeta, ClioTurnRecord } from "../../engine/session.js";
+import type { SessionEntry } from "./entries.js";
+import type { TreeSnapshot } from "./tree/navigator.js";
+import type { WorkspaceSnapshot } from "./workspace/index.js";
+
+/**
+ * Domain-level session metadata. Extends the engine's on-disk meta with
+ * optional fork pointers and checkpoint bookkeeping. The extra fields live
+ * alongside the engine's keys in the same meta.json; readers that only know
+ * about ClioSessionMeta simply ignore them.
+ */
+export type ClioSessionMetaExtension = {
+	parentSessionId?: string | null;
+	parentTurnId?: string | null;
+	lastCheckpointAt?: string | null;
+	lastCheckpointReason?: string | null;
+	/** Latest display name discovered from sessionInfo entries. */
+	name?: string;
+	/** Latest non-empty turn labels discovered from sessionInfo entries. */
+	labels?: string[];
+	/**
+	 * First user-message text discovered while scanning current.jsonl. Used
+	 * by the /resume picker as the row's primary identifier so users can
+	 * recognize a session by its opening prompt instead of by uuid prefix.
+	 * Whitespace-collapsed but otherwise unmodified; the renderer truncates.
+	 */
+	firstMessagePreview?: string;
+	/**
+	 * Count of structured user-role message entries. Approximates "how
+	 * many things did I ask?" for the picker; tool calls and bookkeeping
+	 * entries do not contribute. Discovered alongside firstMessagePreview.
+	 */
+	messageCount?: number;
+	/**
+	 * Latest entry timestamp seen in current.jsonl, falling back to the
+	 * file's mtime. Lets the picker rank sessions by last-activity rather
+	 * than creation time so a long-running session moves up after each
+	 * turn.
+	 */
+	lastActivityAt?: string;
+	/**
+	 * Workspace snapshot captured at session bind. Populated by probeWorkspace
+	 * during create(); read-only thereafter. Omitted on resumed sessions that
+	 * pre-date this field; context(scope="workspace") lazy-fills then.
+	 */
+	workspace?: WorkspaceSnapshot;
+	/** Ordered record of skills activated in this session. */
+	skillActivations?: SkillActivation[];
+	/**
+	 * The turn `/tree` last switched the append point to, persisted so it
+	 * survives quit + resume. `resume()`/`switchBranch()` prefer this over
+	 * inferring the leaf from timestamps (`computeLeafId`) when it still
+	 * names a real turn; a plain append clears it, since once the tree grows
+	 * past it the inferred newest-node leaf is correct again.
+	 */
+	pinnedLeafTurnId?: string | null;
+};
+
+export type SessionMeta = ClioSessionMeta & ClioSessionMetaExtension;
+
+export type TurnInput = Omit<ClioTurnRecord, "id" | "at"> & { id?: string; at?: string };
+
+/**
+ * Rich entry input: caller may omit turnId and timestamp so the manager can
+ * fill them with a uuid v7 + now(). parentTurnId still has to be supplied
+ * (or null for the first entry in a branch). Distributes across the union
+ * so every kind keeps its discriminant + kind-specific fields.
+ */
+export type SessionEntryInput = SessionEntry extends infer T
+	? T extends SessionEntry
+		? Omit<T, "turnId" | "timestamp"> & { turnId?: string; timestamp?: string }
+		: never
+	: never;
+
+/** Options for SessionContract.deleteSession. */
+export interface DeleteSessionOptions {
+	/**
+	 * When true, retain current.jsonl + tree.json on disk and only tombstone
+	 * the meta.json (renamed to meta.deleted.json) so `history()` drops the
+	 * session from listings without destroying the transcript. Default false
+	 * wipes the entire session directory.
+	 */
+	keepFiles?: boolean;
+}
+
+export interface SessionContract {
+	current(): SessionMeta | null;
+	/** Create a new session for the given cwd. */
+	create(input?: { cwd?: string; model?: string; target?: string }): SessionMeta;
+	/** Append a turn to the current session. */
+	append(turn: TurnInput): ClioTurnRecord;
+	/**
+	 * Append a rich SessionEntry to the current session. Complements
+	 * `append(turn)` for Phase 12+ entry kinds (compactionSummary,
+	 * branchSummary, modelChange, etc.). Old callers keep using `append`.
+	 */
+	appendEntry(entry: SessionEntryInput): SessionEntry;
+	/**
+	 * Atomically replace the current session's rich entry list. Used by
+	 * observation masking to rewrite persisted payload bodies without
+	 * changing turn ids or tree shape.
+	 */
+	replaceEntries(entries: ReadonlyArray<SessionEntry>): void;
+	/** Append a skill activation ledger entry and mirror it into meta.json. */
+	recordSkillActivation(activation: SkillActivation): SkillActivation;
+	/** Write atomic checkpoint (current.jsonl flush, tree.json persist, meta update). */
+	checkpoint(reason?: string): Promise<void>;
+	/** Synchronously make current.jsonl appends durable; used by write-ahead safety journals. */
+	flushAppends?(): void;
+	/** Load an existing session and make it current. */
+	resume(sessionId: string): SessionMeta;
+	/** Fork from a parent turn, producing a new session with parentId pointer. */
+	fork(parentTurnId: string, input?: { cwd?: string }): SessionMeta;
+	/**
+	 * Return a serializable snapshot of the tree for a given session (defaults
+	 * to the current session). Built from `tree.json` + resolved labels via
+	 * `tree/navigator.ts`; the underlying on-disk artifacts stay engine-owned.
+	 */
+	tree(sessionId?: string): TreeSnapshot;
+	/**
+	 * Switch the active session to `sessionId`. Semantically mirrors `resume`:
+	 * the /tree overlay uses this to rewire the chat-loop when the user picks
+	 * a different branch. Returns the new SessionMeta.
+	 */
+	switchBranch(sessionId: string): SessionMeta;
+	/**
+	 * Move the current session's active append point to a turn in its tree.
+	 * The interactive chat loop uses this id as the next parent while the
+	 * on-disk tree keeps all sibling branches intact.
+	 */
+	switchTurn(turnId: string): SessionMeta;
+	/**
+	 * Persist a display-only label for `turnId`. The marker is a
+	 * SessionInfoEntry with `targetTurnId` + `label` written to the target
+	 * session's current.jsonl. Empty `label` clears the marker. If the target
+	 * session is the current one, writes flow through the live writer;
+	 * otherwise the helper appends directly to that session's transcript.
+	 */
+	editLabel(turnId: string, label: string, sessionId?: string): void;
+	/**
+	 * Persist the session's display name as a session-wide SessionInfoEntry.
+	 * Empty or whitespace-only names clear the name when history is rebuilt.
+	 * If the target session is current, writes flow through the live writer;
+	 * otherwise the entry is durably appended directly to its transcript.
+	 */
+	setName(name: string, sessionId?: string): void;
+	/**
+	 * Remove the given session. By default, wipes the session directory.
+	 * `opts.keepFiles` preserves the transcript and only tombstones meta.json.
+	 * Refuses to delete a session that is currently open; call `close()` first
+	 * or target a different id.
+	 */
+	deleteSession(id: string, opts?: DeleteSessionOptions): void;
+	/** List sessions for current cwd (most-recent first). */
+	history(): ReadonlyArray<SessionMeta>;
+	/** End current session. */
+	close(): Promise<void>;
+}

package/src/domains/session/cwd-fallback.ts

@@ -0,0 +1,65 @@
+/**
+ * Session cwd fallback resolver (Phase 12 slice 12d).
+ *
+ * Pure guard used by the interactive layer when a session is resumed.
+ * `meta.cwd` is captured at session creation time; by the time the user
+ * runs `/resume`, that directory may no longer exist (repo deleted,
+ * external drive unmounted, user renamed the project directory). This
+ * helper answers "is the recorded cwd still usable?" without touching
+ * clio's orchestrator or the TUI; the caller pops `cwd-fallback` overlay
+ * on a negative answer.
+ *
+ * Injectable `fsProbe` so that the resumption path can be verified.
+ */
+
+import { existsSync, statSync } from "node:fs";
+
+/**
+ * Minimal filesystem surface `resolveSessionCwd` consults. Production
+ * callers use `defaultFsProbe`; tests inject a deterministic stub.
+ */
+export interface FsProbe {
+	exists(path: string): boolean;
+	isDirectory(path: string): boolean;
+}
+
+export const defaultFsProbe: FsProbe = {
+	exists: (p) => existsSync(p),
+	isDirectory: (p) => {
+		try {
+			return statSync(p).isDirectory();
+		} catch {
+			return false;
+		}
+	},
+};
+
+/**
+ * Discriminated result the overlay layer branches on.
+ *   - `no-cwd`: the meta record has no cwd field or it is blank after
+ *     trimming. Pre-Phase-12 sessions occasionally land here.
+ *   - `missing`: cwd string is set but the directory does not exist on
+ *     disk (fsProbe.exists returned false).
+ *   - `not-a-directory`: the path exists but resolves to a file or a
+ *     symlink target that is not a directory.
+ */
+export type ResolveSessionCwdResult =
+	| { ok: true; cwd: string }
+	| { ok: false; reason: "no-cwd" | "missing" | "not-a-directory" };
+
+/**
+ * Check whether a resumed session's recorded cwd still points at a live
+ * directory on disk. Returns `{ok: true, cwd}` when the path resolves and
+ * is a directory; a typed reason otherwise. No side effects. Callers
+ * persist nothing here; they decide how to react based on the reason.
+ */
+export function resolveSessionCwd(
+	meta: { cwd?: string | null },
+	fsProbe: FsProbe = defaultFsProbe,
+): ResolveSessionCwdResult {
+	const raw = typeof meta.cwd === "string" ? meta.cwd.trim() : "";
+	if (raw.length === 0) return { ok: false, reason: "no-cwd" };
+	if (!fsProbe.exists(raw)) return { ok: false, reason: "missing" };
+	if (!fsProbe.isDirectory(raw)) return { ok: false, reason: "not-a-directory" };
+	return { ok: true, cwd: raw };
+}