@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/config/keybindings.ts

@@ -9,7 +9,7 @@
  * complains.
  */
 
-import type { KeybindingDefinitions } from "../../engine/tui.js";
+import type { KeybindingDefinitions, KeyId } from "../../engine/tui.js";
 import { TUI_KEYBINDINGS } from "../../engine/tui.js";
 
 /**
@@ -30,6 +30,7 @@ export interface ClioAppKeybindings {
 	"clio-coder.decisions.open": true;
 	"clio-coder.dispatch.background": true;
 	"clio-coder.model.select": true;
+	"clio-coder.library.toggle": true;
 	"clio-coder.model.cycleForward": true;
 	"clio-coder.model.cycleBackward": true;
 	"clio-coder.editor.external": true;
@@ -52,129 +53,188 @@ declare module "@earendil-works/pi-tui" {
 	interface Keybindings extends ClioAppKeybindings {}
 }
 
-/**
- * Built-in defaults. Users override via `settings.yaml.keybindings`; the
- * manager reads those and patches this table before the TUI starts.
- *
- * Clio's app bindings follow one scheme: `Alt + <key>` (with `shift+tab`,
- * `ctrl+d`, and the portable `ctrl+g` leader retained because every terminal
- * already transmits them). `Alt + <letter>` decodes from the legacy
- * `ESC <letter>` sequence on meta-capable terminals. The chosen letters avoid
- * pi-tui's editor reserves except for the approved `Alt+B` and `Alt+D`
- * application-boundary overrides. They open the task and decision boards
- * before the editor can interpret those chords as word-back or word-delete.
- * The CSI-u/reserved-key detector in `keybinding-manager.ts` stays as a safety
- * net for user rebinds.
- */
+/** Stable application descriptors. Fixed leader suffixes never derive from overrides. */
+interface AppActionDescriptor {
+	defaultKeys: KeyId | KeyId[];
+	description: string;
+	scope: "composer";
+	kind: "toggle" | "cycle" | "send" | "exit" | "edit" | "dismiss";
+	repeat: false;
+	leader?: string;
+}
 export const CLIO_APP_KEYBINDINGS = {
-	"clio-coder.thinking.cycle": {
-		defaultKeys: "shift+tab",
-		description: "Cycle orchestrator thinking level",
+	"clio-coder.library.toggle": {
+		defaultKeys: "alt+l",
+		description: "Library",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
+		leader: "l",
 	},
-	"clio-coder.exit": {
-		defaultKeys: "ctrl+d",
-		description: "Exit when the editor is empty",
+	"clio-coder.model.select": {
+		defaultKeys: "alt+m",
+		description: "Model picker",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
+		leader: "m",
+	},
+	"clio-coder.output.cycle": {
+		defaultKeys: "alt+o",
+		description: "Output style",
+		scope: "composer",
+		kind: "cycle",
+		repeat: false,
+		leader: "o",
 	},
 	"clio-coder.status.toggle": {
 		defaultKeys: "alt+u",
-		description: "Toggle the footer dashboard (compact / expanded)",
-	},
-	"clio-coder.session.tree": {
-		defaultKeys: "alt+t",
-		description: "Open the /tree navigator",
+		description: "Dashboard",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
+		leader: "u",
 	},
 	"clio-coder.dispatchBoard.toggle": {
 		defaultKeys: "alt+w",
-		description: "Toggle the dispatch (workers) board overlay",
+		description: "Workers",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
+		leader: "w",
 	},
 	"clio-coder.files.toggle": {
-		// Alt+F is a pi-tui editor reserve (word-forward), so the files pane
-		// takes the next letter that reads as "explorer" and stays inside the
-		// Alt+<letter> scheme, which also earns it the Ctrl+G leader fallback.
 		defaultKeys: "alt+e",
-		description: "Toggle the files pane beside the session (a --with-panes session inside herdr)",
+		description: "Files (from Clio focus)",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
+		leader: "e",
+	},
+	"clio-coder.thinking.cycle": {
+		defaultKeys: "shift+tab",
+		description: "Thinking effort",
+		scope: "composer",
+		kind: "cycle",
+		repeat: false,
+		leader: "t",
+	},
+	"clio-coder.message.followUp": {
+		defaultKeys: "ctrl+q",
+		description: "Send after the active run",
+		scope: "composer",
+		kind: "send",
+		repeat: false,
+		leader: "f",
+	},
+	"clio-coder.message.dequeue": {
+		defaultKeys: "alt+q",
+		description: "Restore queued messages",
+		scope: "composer",
+		kind: "send",
+		repeat: false,
+		leader: "q",
+	},
+	"clio-coder.exit": {
+		defaultKeys: "ctrl+d",
+		description: "Exit empty idle composer with no queued messages",
+		scope: "composer",
+		kind: "exit",
+		repeat: false,
+	},
+	"clio-coder.leader": {
+		defaultKeys: "ctrl+g",
+		description: "Open contextual action menu",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
 	},
 	"clio-coder.tasks.open": {
-		// Approved application-boundary override of pi-tui editor word-back.
-		defaultKeys: "alt+b",
-		description: "Open the composite session and operator task board",
+		defaultKeys: [],
+		description: "Tasks (/tasks)",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
 	},
 	"clio-coder.decisions.open": {
-		// Approved application-boundary override of pi-tui editor word-delete.
-		defaultKeys: "alt+d",
-		description: "Open the settled interview decision board",
-	},
-	"clio-coder.dispatch.background": {
-		// Ctrl+B alone is pi-tui's editor cursor-left, so the Claude Code chord
-		// cannot be the primary here. Alt+S ("send to background") keeps the app
-		// scheme and earns the Ctrl+G leader fallback, which only alt+<letter>
-		// bindings get; Ctrl+Alt+B stays for the b-for-background muscle memory.
-		defaultKeys: ["alt+s", "ctrl+alt+b"],
-		description: "Send the running attached dispatch to the background as a detached batch",
+		defaultKeys: [],
+		description: "Decisions (/decisions)",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
 	},
-	"clio-coder.model.select": {
-		defaultKeys: "alt+l",
-		description: "Open the model + targets selector",
+	"clio-coder.session.tree": {
+		defaultKeys: [],
+		description: "Session tree (/tree)",
+		scope: "composer",
+		kind: "toggle",
+		repeat: false,
 	},
 	"clio-coder.model.cycleForward": {
-		defaultKeys: "alt+j",
-		description: "Cycle to next scoped model",
+		defaultKeys: [],
+		description: "Next scoped model",
+		scope: "composer",
+		kind: "cycle",
+		repeat: false,
 	},
 	"clio-coder.model.cycleBackward": {
-		defaultKeys: "alt+k",
-		description: "Cycle to previous scoped model",
+		defaultKeys: [],
+		description: "Previous scoped model",
+		scope: "composer",
+		kind: "cycle",
+		repeat: false,
 	},
-	"clio-coder.output.cycle": {
-		defaultKeys: "alt+o",
-		description: "Cycle output style: Compact, Standard, Detailed",
-	},
-	"clio-coder.editor.external": {
-		defaultKeys: "alt+g",
-		description: "Open the current input in an external editor",
-	},
-	"clio-coder.message.followUp": {
-		defaultKeys: "alt+enter",
-		description:
-			"End of turn: queue the current input for delivery when the active run settles (Enter delivers it at the next slot, between tool batches)",
+	"clio-coder.dispatch.background": {
+		defaultKeys: [],
+		description: "Background attached dispatch",
+		scope: "composer",
+		kind: "send",
+		repeat: false,
+		leader: "s",
 	},
 	"clio-coder.message.interrupt": {
-		// Alt+I keeps the app scheme and earns the Ctrl+G leader fallback. A
-		// Ctrl+Enter chord was rejected because legacy terminals send it as a
-		// plain Enter, which would turn every send into a cancel.
-		defaultKeys: "alt+i",
-		description:
-			"Interrupt: cancel the active run and deliver the current input now (refused while an attached dispatch runs or a permission ask is parked; the input then queues for the next slot)",
+		defaultKeys: [],
+		description: "Interrupt with draft",
+		scope: "composer",
+		kind: "send",
+		repeat: false,
+		leader: "i",
 	},
-	"clio-coder.message.dequeue": {
-		defaultKeys: "alt+up",
-		description: "Restore queued steering and follow-up messages to the editor",
+	"clio-coder.editor.external": {
+		defaultKeys: [],
+		description: "Edit expanded draft externally",
+		scope: "composer",
+		kind: "edit",
+		repeat: false,
+		leader: "g",
 	},
 	"clio-coder.notifications.dismiss": {
-		defaultKeys: "alt+x",
-		description: "Dismiss footer notifications",
-	},
-	"clio-coder.leader": {
-		defaultKeys: "ctrl+g",
-		description: "Start portable leader-key fallback for Alt shortcuts",
-	},
-} as const satisfies KeybindingDefinitions;
+		defaultKeys: [],
+		description: "Dismiss oldest notification",
+		scope: "composer",
+		kind: "dismiss",
+		repeat: false,
+		leader: "x",
+	},
+} as const satisfies Record<ClioKeybinding, AppActionDescriptor>;
 
-/**
- * Full definition table = pi-tui editor/select defaults + Clio app ids.
- * pi-tui 0.84 supplies dedicated prompt-history actions but leaves them
- * unbound for applications to place. Clio uses the readline-style Ctrl+P and
- * Ctrl+N pair because its model cycling already lives on Alt+J and Alt+K.
- */
 export const CLIO_KEYBINDINGS = {
 	...TUI_KEYBINDINGS,
-	"tui.editor.historyPrevious": {
-		...TUI_KEYBINDINGS["tui.editor.historyPrevious"],
-		defaultKeys: "ctrl+p",
-	},
-	"tui.editor.historyNext": {
-		...TUI_KEYBINDINGS["tui.editor.historyNext"],
-		defaultKeys: "ctrl+n",
-	},
+	"tui.editor.historyPrevious": { ...TUI_KEYBINDINGS["tui.editor.historyPrevious"], defaultKeys: "ctrl+p" },
+	"tui.editor.historyNext": { ...TUI_KEYBINDINGS["tui.editor.historyNext"], defaultKeys: "ctrl+n" },
+	"tui.editor.deleteWordBackward": {
+		...TUI_KEYBINDINGS["tui.editor.deleteWordBackward"],
+		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace"],
+	},
+	"tui.editor.undo": { ...TUI_KEYBINDINGS["tui.editor.undo"], defaultKeys: "ctrl+_" },
+	"tui.input.newLine": { ...TUI_KEYBINDINGS["tui.input.newLine"], defaultKeys: ["ctrl+j", "shift+enter"] },
+	"tui.altScreen.top": { ...TUI_KEYBINDINGS["tui.altScreen.top"], defaultKeys: [] },
+	"tui.altScreen.bottom": { ...TUI_KEYBINDINGS["tui.altScreen.bottom"], defaultKeys: [] },
+	"tui.altScreen.previousPrompt": { ...TUI_KEYBINDINGS["tui.altScreen.previousPrompt"], defaultKeys: "ctrl+up" },
+	"tui.altScreen.nextPrompt": { ...TUI_KEYBINDINGS["tui.altScreen.nextPrompt"], defaultKeys: "ctrl+down" },
+	"tui.altScreen.search": { ...TUI_KEYBINDINGS["tui.altScreen.search"], defaultKeys: "ctrl+r" },
+	"tui.altScreen.searchNext": { ...TUI_KEYBINDINGS["tui.altScreen.searchNext"], defaultKeys: "enter" },
+	"tui.altScreen.searchPrevious": { ...TUI_KEYBINDINGS["tui.altScreen.searchPrevious"], defaultKeys: "up" },
 	...CLIO_APP_KEYBINDINGS,
 } as const satisfies KeybindingDefinitions;
 

package/src/domains/context/worker/contract.ts

@@ -0,0 +1,91 @@
+import type { AgentMessage } from "../../../engine/types.js";
+
+/** Conversation inheritance is independent of dispatch's scheduling mode. */
+export type WorkerContextPolicy =
+	| { mode: "isolated" }
+	| { mode: "fork"; max_tokens?: number }
+	| { mode: "splice"; max_tokens?: number; paths?: string[]; refs?: string[] };
+
+export const WORKER_CONTEXT_SPLICE_TOKENS = 8_000;
+
+export interface WorkerContextSource {
+	sessionId: string;
+	leafTurnId: string | null;
+	cwd: string;
+}
+
+/** Host-only snapshot of model-visible messages, never the raw session archive. */
+export interface WorkerContextSnapshot {
+	version: 1;
+	source: WorkerContextSource;
+	messages: ReadonlyArray<AgentMessage>;
+	excludedTailMessages: number;
+	excludedInterruptedMessages: number;
+	contentHash: string;
+}
+
+/** Integrity-covered receipt metadata; the messages themselves live in a seed artifact. */
+export interface WorkerContextProvenance {
+	version: 1;
+	mode: "fork" | "splice";
+	source: WorkerContextSource;
+	snapshotHash: string;
+	contentHash: string;
+	messageCount: number;
+	estimatedTokens: number;
+	bytes: number;
+	omittedMessages: number;
+	excludedTailMessages: number;
+	excludedInterruptedMessages: number;
+	selectedRefs: string[];
+}
+
+/** Self-contained seed, usable on a remote native worker without parent filesystem access. */
+export interface WorkerContextSeed {
+	provenance: WorkerContextProvenance;
+	messages: AgentMessage[];
+}
+
+export function parseWorkerContextPolicy(value: unknown): WorkerContextPolicy {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("context must be an object");
+	const policy = value as Record<string, unknown>;
+	const mode = policy.mode;
+	if (mode !== "isolated" && mode !== "fork" && mode !== "splice")
+		throw new Error("context.mode must be isolated, fork, or splice");
+	const keys =
+		mode === "isolated" ? ["mode"] : mode === "fork" ? ["mode", "max_tokens"] : ["mode", "max_tokens", "paths", "refs"];
+	for (const key of Object.keys(policy))
+		if (!keys.includes(key)) throw new Error(`context.${key} is unsupported for ${mode}`);
+	if (mode === "isolated") return { mode };
+	const result: Exclude<WorkerContextPolicy, { mode: "isolated" }> = { mode };
+	if (policy.max_tokens !== undefined) {
+		if (
+			!Number.isSafeInteger(policy.max_tokens) ||
+			(policy.max_tokens as number) < 256 ||
+			(policy.max_tokens as number) > 262_144
+		)
+			throw new Error("context.max_tokens must be an integer between 256 and 262144");
+		result.max_tokens = policy.max_tokens as number;
+	}
+	if (result.mode === "splice") {
+		for (const key of ["paths", "refs"] as const) {
+			const items = policy[key];
+			if (items === undefined) continue;
+			if (
+				!Array.isArray(items) ||
+				items.length === 0 ||
+				items.length > 64 ||
+				items.some(
+					(item) =>
+						typeof item !== "string" ||
+						item.trim().length === 0 ||
+						item.length > 4096 ||
+						Array.from(item).some((char) => char.charCodeAt(0) < 32),
+				)
+			)
+				throw new Error(`context.${key} must contain 1 to 64 nonempty strings`);
+			result[key] = [...new Set((items as string[]).map((item) => item.trim()))];
+		}
+	}
+	return result;
+}

package/src/domains/context/worker/pressure.ts

@@ -0,0 +1,120 @@
+import type { AgentMessage } from "../../../engine/types.js";
+import { estimateAgentContextBreakdown, estimateAgentMessageTokens } from "../../session/context-accounting.js";
+import { contextHash, messageToolCalls } from "./snapshot.js";
+
+interface WorkerPressureInput {
+	messages: ReadonlyArray<AgentMessage>;
+	systemPrompt: string;
+	tools: ReadonlyArray<unknown>;
+	contextWindow: number;
+	outputReserve: number;
+	threshold?: number;
+	autoEvict?: boolean;
+}
+
+export class WorkerContextExhaustedError extends Error {}
+
+/** Per-worker reversible projection. Stable markers never rewrite its raw history. */
+export function createWorkerContextGuard(archive: (ref: string, message: AgentMessage) => string) {
+	const evicted = new Map<string, AgentMessage>();
+	let calls = 0;
+	let firstInputLength = 0;
+	let lastRequestTokens = 0;
+	let anchorKey = "";
+	let anchorUsage = 0;
+	let anchorFootprint = 0;
+	return (input: WorkerPressureInput): AgentMessage[] => {
+		const ceiling = Math.min(
+			Math.floor(input.contextWindow * (input.threshold ?? 0.8)),
+			input.contextWindow - input.outputReserve,
+		);
+		const key = (message: AgentMessage) => contextHash(message);
+		const messages = input.messages.map((message) => evicted.get(key(message)) ?? message);
+
+		const breakdown = estimateAgentContextBreakdown({ systemPrompt: input.systemPrompt, tools: input.tools, messages });
+		let structural = Object.values(breakdown).reduce((sum, value) => sum + value, 0);
+
+		// Parent usage never anchors a child. Only a response to this worker's own request can do so.
+		if (calls === 0) firstInputLength = input.messages.length;
+		else {
+			for (let index = messages.length - 1; index >= firstInputLength; index--) {
+				const message = messages[index];
+				if (
+					message?.role !== "assistant" ||
+					!message.usage ||
+					message.stopReason === "error" ||
+					message.stopReason === "aborted"
+				)
+					continue;
+				const usage = message.usage;
+				const actual = usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+				const nextKey = key(message);
+				if (nextKey !== anchorKey) {
+					anchorKey = nextKey;
+					anchorUsage = Number.isFinite(actual) && actual > 0 ? actual : 0;
+					// Usage describes the previous projected request plus this answer.
+					// Keep that footprint stable across repeated projection of the same answer.
+					anchorFootprint = lastRequestTokens + estimateAgentMessageTokens(message);
+				}
+				break;
+			}
+		}
+		const count = () => Math.max(structural, anchorUsage > 0 ? anchorUsage + structural - anchorFootprint : 0);
+		const accepted = () => {
+			calls++;
+			lastRequestTokens = structural;
+			return messages;
+		};
+		const replace = (index: number, original: AgentMessage, projected: AgentMessage) => {
+			const saved = estimateAgentMessageTokens(original) - estimateAgentMessageTokens(projected);
+			if (saved <= 0) return;
+			evicted.set(key(original), projected);
+			messages[index] = projected;
+			structural -= saved;
+		};
+
+		if (count() <= ceiling) return accepted();
+		// The first request must honor the selected fork; never auto-trim it into a splice.
+		if (calls === 0)
+			throw new WorkerContextExhaustedError(
+				"worker context: initial request leaves insufficient context headroom; use a smaller splice",
+			);
+		if (input.autoEvict === false)
+			throw new WorkerContextExhaustedError("worker context: context budget exhausted with automatic eviction disabled");
+		const assistantIndices = input.messages.flatMap((message, index) => (message.role === "assistant" ? [index] : []));
+		const cutoff = assistantIndices[Math.max(0, assistantIndices.length - 2)] ?? 0;
+		const toolCalls = new Map(input.messages.flatMap(messageToolCalls).map((call) => [call.id, call]));
+		for (let index = 0; index < cutoff && count() > ceiling; index++) {
+			const message = input.messages[index];
+			if (!message || evicted.has(key(message))) continue;
+			if (message.role === "assistant") {
+				const content = message.content.filter((block) => block.type !== "thinking");
+				if (content.length === 0 || content.length === message.content.length) continue;
+				const projected = { ...message, content };
+				replace(index, message, projected);
+			} else if (message.role === "toolResult" && !message.isError) {
+				const name = toolCalls.get(message.toolCallId)?.name;
+				// Only observations with known read semantics. Preserve mutations and opaque tools.
+				if (!name || !["read", "grep", "find", "ls", "code_nav", "web_fetch"].includes(name)) continue;
+				if (JSON.stringify(message.content).length < 1000) continue;
+				const ref = key(message);
+				const file = archive(ref, structuredClone(message));
+				const projected = {
+					...message,
+					content: [
+						{
+							type: "text" as const,
+							text: `[Worker context observation worker:${ref} evicted. Recover with context(scope="recall", ref="worker:${ref}"). Exact historical result: ${file}. Read that file if needed; reread the source for current contents.]`,
+						},
+					],
+				};
+				replace(index, message, projected);
+			}
+		}
+		if (count() > ceiling)
+			throw new WorkerContextExhaustedError(
+				"worker context: protected task context exceeds available headroom after reversible eviction",
+			);
+		return accepted();
+	};
+}

package/src/domains/context/worker/recall.ts

@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { clioStateDir } from "../../../core/xdg.js";
+import type { AgentMessage } from "../../../engine/types.js";
+import { contextHash } from "./snapshot.js";
+
+export type WorkerRecallResult =
+	| { error: string }
+	| { body: string; total: number; shown: number; nextOffset?: number };
+export type WorkerRecall = (args: Record<string, unknown>) => WorkerRecallResult;
+
+/** The in-memory allowlist is the capability. A ref never grants arbitrary file or parent-ledger access. */
+export function createWorkerObservationStore(): {
+	archive(ref: string, message: AgentMessage): string;
+	recall: WorkerRecall;
+} {
+	const records = new Map<string, { file: string; label: string }>();
+	return {
+		archive(ref, message) {
+			if (contextHash(message) !== ref) throw new Error("worker context: observation digest mismatch");
+			const file = join(clioStateDir(), "context-observations", `${ref}.json`);
+			safeResourceWrite(file, `${JSON.stringify(message)}\n`, { mode: 0o600 });
+			records.set(`worker:${ref}`, { file, label: message.role === "toolResult" ? message.toolName : message.role });
+			return file;
+		},
+		recall(args) {
+			if (args.ref !== undefined) {
+				const ref = typeof args.ref === "string" ? args.ref.trim() : "";
+				const record = records.get(ref);
+				if (!record) return { error: "ref is not an evicted observation from this worker run" };
+				try {
+					const body = readFileSync(record.file, "utf8");
+					if (`worker:${contextHash(JSON.parse(body))}` !== ref) return { error: "observation digest mismatch" };
+					return { body: `Historical observation ${ref}; this is not a new source read.\n${body}`, total: 1, shown: 1 };
+				} catch {
+					return { error: "persisted worker observation is unavailable or malformed" };
+				}
+			}
+			const query = typeof args.query === "string" ? args.query.trim().toLowerCase() : "";
+			const limit =
+				typeof args.limit === "number" && Number.isSafeInteger(args.limit) ? Math.max(1, Math.min(12, args.limit)) : 8;
+			const offset = typeof args.offset === "number" && Number.isSafeInteger(args.offset) ? Math.max(0, args.offset) : 0;
+			const matches = [...records]
+				.map(([ref, item]) => `${ref} ${item.label}`)
+				.filter((line) => line.toLowerCase().includes(query));
+			const page = matches.slice(offset, offset + limit);
+			const nextOffset = offset + page.length < matches.length ? offset + page.length : undefined;
+			return {
+				body: [
+					...page,
+					nextOffset === undefined
+						? "End of this worker's evicted observations."
+						: `More observations: offset=${nextOffset}.`,
+				].join("\n"),
+				total: matches.length,
+				shown: page.length,
+				...(nextOffset === undefined ? {} : { nextOffset }),
+			};
+		},
+	};
+}