@iowarp/clio-coder 0.4.5 → 0.4.7

package/src/domains/agents/registry.ts

@@ -1,8 +1,10 @@
 import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
+import { readSettings } from "../../core/config.js";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import { clioConfigDir } from "../../core/xdg.js";
-import { enabledExtensionResourceRoots } from "../extensions/index.js";
+import { enabledPluginResourceRoots } from "../plugins/index.js";
+import { resolvePackageReferences } from "../resources/package-references.js";
 import { loadSkills } from "../resources/skills/loader.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { type AgentRecipe, type RecipeSource, recipeIdFromPath } from "./recipe.js";
@@ -15,6 +17,25 @@ export interface AgentRecipeDiagnostic {
 	source: RecipeSource["source"];
 	filepath: string;
 	message: string;
+	/**
+	 * Why a file is not in the catalog. `quarantine` is a parse/policy failure;
+	 * `ignored` is a reserved or protected id; `overridden` lost same-id
+	 * precedence to a later source. Absent on records from before this field.
+	 */
+	kind?: "quarantine" | "ignored" | "overridden";
+	/** Recipe id when it was parsed; quarantined files may not have one. */
+	id?: string;
+	/** Source that won, for `overridden`. */
+	by?: RecipeSource["source"];
+	/** Parsed audience of an ignored/overridden recipe, so listings can keep hiding internal ones. */
+	audience?: AgentRecipe["audience"];
+}
+
+/** Diagnostics are a bounded inspection aid, never a second catalog. */
+const MAX_AGENT_RECIPE_DIAGNOSTICS = 256;
+
+function recordDiagnostic(diagnostics: AgentRecipeDiagnostic[], diagnostic: AgentRecipeDiagnostic): void {
+	if (diagnostics.length < MAX_AGENT_RECIPE_DIAGNOSTICS) diagnostics.push(diagnostic);
 }
 
 function resolveBoundSkills(recipe: AgentRecipe, source: RecipeSource): AgentRecipe {
@@ -22,31 +43,35 @@ function resolveBoundSkills(recipe: AgentRecipe, source: RecipeSource): AgentRec
 	// Builtins may bind a package-owned skill. Custom recipes deliberately use
 	// only the operator's discovered skill roots; a recipe cannot smuggle an
 	// arbitrary filesystem path into worker context through a skill name.
-	const packageSkills = path.resolve(source.dir, "..", "..", "..", "..", "skills");
-	if (source.source === "extension" && source.skillRoot === undefined) {
-		throw new Error(`agent recipe: ${recipe.filepath}: extension declares bound skills but no skills resource root`);
+	const packageSkills = path.resolve(source.dir, "..", "..", "..", "..", "library", "skills");
+	if (source.source === "plugin" && source.skillRoot === undefined) {
+		throw new Error(
+			`agent recipe: ${recipe.filepath}: ${source.source} declares bound skills but no skills resource root`,
+		);
 	}
 	const skills =
-		source.source === "extension"
+		source.source === "plugin"
 			? loadSkills({
 					cwd: source.cwd ?? process.cwd(),
+					trustProjectCompatRoots: readSettings().integrations.projectResources.trustProjectImports,
 					disableDiscovery: true,
 					explicitSkillPaths: source.skillRoot === undefined ? [] : [source.skillRoot],
 				})
 			: loadSkills({
 					cwd: source.cwd ?? process.cwd(),
+					trustProjectCompatRoots: readSettings().integrations.projectResources.trustProjectImports,
 					...(source.source === "builtin" && existsSync(packageSkills) ? { explicitSkillPaths: [packageSkills] } : {}),
 				});
-	if (source.source === "extension" && source.skillRoot !== undefined) {
+	if (source.source === "plugin" && source.skillRoot !== undefined) {
 		const canonicalRoot = realpathSync(source.skillRoot);
 		for (const skill of skills.items) {
 			const relative = path.relative(canonicalRoot, realpathSync(skill.filePath));
 			if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-				throw new Error(`agent recipe: ${recipe.filepath}: bound skill escapes its extension: ${skill.filePath}`);
+				throw new Error(`agent recipe: ${recipe.filepath}: bound skill escapes its ${source.source}: ${skill.filePath}`);
 			}
 		}
 	}
-	const byName = new Map(skills.items.map((skill) => [skill.name, skill.filePath]));
+	const byName = new Map(skills.items.filter((skill) => skill.trusted).map((skill) => [skill.name, skill.filePath]));
 	const missing = recipe.skills.filter((skill) => !byName.has(skill));
 	if (missing.length > 0) {
 		throw new Error(`agent recipe: ${recipe.filepath}: bound skill(s) unavailable: ${missing.join(", ")}`);
@@ -83,7 +108,11 @@ export function loadRecipesFromDir(
 		try {
 			const id = recipeIdFromPath(filepath, source.dir);
 			const raw = readFileSync(filepath, "utf8");
-			const { frontmatter, body } = parseFrontmatter(raw, filepath);
+			const { frontmatter, body: rawBody } = parseFrontmatter(raw, filepath);
+			const body = resolvePackageReferences(rawBody, {
+				...(source.rootPath ? { rootPath: source.rootPath } : {}),
+				plugin: source.source === "plugin",
+			});
 			const parsedRecipe = parseAgentRecipeSchema({ id, source: source.source, filepath, body, frontmatter });
 			const recipe = resolveBoundSkills(parsedRecipe, source);
 			// Policy validation runs before a recipe enters any catalog, prompt, or
@@ -93,7 +122,7 @@ export function loadRecipesFromDir(
 		} catch (error) {
 			if (source.source === "builtin") throw error;
 			const message = error instanceof Error ? error.message : String(error);
-			diagnostics.push({ source: source.source, filepath, message });
+			recordDiagnostic(diagnostics, { kind: "quarantine", source: source.source, filepath, message });
 			process.stderr.write(`[clio-coder:agents] quarantine path=${filepath} source=${source.source} reason=${message}\n`);
 		}
 	}
@@ -102,7 +131,21 @@ export function loadRecipesFromDir(
 	return recipes;
 }
 
-function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>): ReadonlyArray<AgentRecipe> {
+function mergeRecipes(
+	diagnostics: AgentRecipeDiagnostic[],
+	...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>
+): ReadonlyArray<AgentRecipe> {
+	const ignored = (recipe: AgentRecipe, reason: string): void => {
+		process.stderr.write(`[clio-coder:agents] ignore id=${recipe.id} by=${recipe.source} reason=${reason}\n`);
+		recordDiagnostic(diagnostics, {
+			kind: "ignored",
+			id: recipe.id,
+			source: recipe.source,
+			audience: recipe.audience,
+			filepath: recipe.filepath,
+			message: `agent recipe ${recipe.id} from ${recipe.source} ignored: ${reason}`,
+		});
+	};
 	const byId = new Map<string, AgentRecipe>();
 	const builtinById = new Map<string, AgentRecipe>();
 	for (const group of sources) {
@@ -113,23 +156,35 @@ function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>): Re
 	for (const group of sources) {
 		for (const recipe of group) {
 			if (recipe.source !== "builtin" && RESERVED_CUSTOM_AGENT_IDS.has(recipe.id)) {
-				process.stderr.write(`[clio-coder:agents] ignore id=${recipe.id} by=${recipe.source} reason=reserved-agent-id\n`);
+				ignored(recipe, "reserved-agent-id");
 				continue;
 			}
 			const builtin = builtinById.get(recipe.id);
-			if (recipe.source === "extension" && builtin) {
-				process.stderr.write(`[clio-coder:agents] ignore override id=${recipe.id} by=extension reason=reserved-builtin\n`);
+			if (recipe.source === "plugin" && builtin) {
+				ignored(recipe, "reserved-builtin");
 				continue;
 			}
 			if (recipe.source === "user" && builtin && isShadowAgent(normalizeAgentSpec(builtin))) {
-				process.stderr.write(`[clio-coder:agents] ignore override id=${recipe.id} by=user reason=reserved-shadow\n`);
+				ignored(recipe, "reserved-shadow");
 				continue;
 			}
 			if (recipe.source === "project" && builtin) {
-				process.stderr.write(`[clio-coder:agents] ignore override id=${recipe.id} by=project reason=reserved-builtin\n`);
+				ignored(recipe, "reserved-builtin");
 				continue;
 			}
-			if (byId.has(recipe.id)) process.stderr.write(`[clio-coder:agents] override id=${recipe.id} by=${recipe.source}\n`);
+			const previous = byId.get(recipe.id);
+			if (previous) {
+				process.stderr.write(`[clio-coder:agents] override id=${recipe.id} by=${recipe.source}\n`);
+				recordDiagnostic(diagnostics, {
+					kind: "overridden",
+					id: previous.id,
+					source: previous.source,
+					audience: previous.audience,
+					by: recipe.source,
+					filepath: previous.filepath,
+					message: `agent recipe ${previous.id} from ${previous.source} overridden by ${recipe.source}`,
+				});
+			}
 			byId.set(recipe.id, recipe);
 		}
 	}
@@ -138,9 +193,9 @@ function mergeRecipes(...sources: ReadonlyArray<ReadonlyArray<AgentRecipe>>): Re
 
 /**
  * Discover the one native-agent catalog used by listing, fleet admission, and
- * dispatch. Extension recipes occupy the same precedence slot as extension
- * fleets: after builtins and before operator/user and project recipes. Their
- * skill bindings remain constrained to the declaring extension's skill root.
+ * dispatch. Plugin recipes occupy the same precedence slot as plugin fleets:
+ * after builtins and before operator/user and project recipes. Their skill
+ * bindings remain constrained to the declaring plugin's skill root.
  */
 export function discoverAgentRecipes(
 	cwd = process.cwd(),
@@ -154,15 +209,16 @@ export function discoverAgentRecipes(
 		},
 		diagnostics,
 	);
-	const skillRoots = new Map(enabledExtensionResourceRoots("skills", cwd).map((root) => [root.source, root.path]));
-	const extensionRecipes = enabledExtensionResourceRoots("agents", cwd)
+	const skillRoots = new Map(enabledPluginResourceRoots("skills", cwd).map((root) => [root.source, root.path]));
+	const pluginRecipes = enabledPluginResourceRoots("agents", cwd)
 		.sort((left, right) => left.source.localeCompare(right.source))
 		.map((root) => {
 			const skillRoot = skillRoots.get(root.source);
 			return loadRecipesFromDir(
 				{
 					dir: root.path,
-					source: "extension",
+					source: "plugin",
+					rootPath: root.rootPath,
 					cwd,
 					origin: root.source,
 					...(skillRoot === undefined ? {} : { skillRoot }),
@@ -175,5 +231,5 @@ export function discoverAgentRecipes(
 		{ dir: path.join(cwd, ".clio-coder", "agents"), source: "project", cwd },
 		diagnostics,
 	);
-	return mergeRecipes(builtin, ...extensionRecipes, user, project);
+	return mergeRecipes(diagnostics, builtin, ...pluginRecipes, user, project);
 }

package/src/domains/config/classify.ts

@@ -22,6 +22,7 @@ const HOT_RELOAD_FIELDS = new Set<string>([
 	"interface.keybindings",
 	"safety.autonomy",
 	"chat.modelPicker",
+	"interface.outputDetail",
 	"interface.smoothStreaming",
 	"interface.panes.notifications",
 	"integrations.git.commitAttribution",
@@ -49,7 +50,6 @@ const NEXT_TURN_FIELDS = new Set<string>([
 	"fleet.history",
 	"context",
 	"safety.limits",
-	"interface.outputDetail",
 	"interface.terminalProgress",
 	"interface.desktopNotifications",
 	"integrations.projectResources",

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";
 
 /**
@@ -19,6 +19,7 @@ import { TUI_KEYBINDINGS } from "../../engine/tui.js";
  * live in `resolveCtrlCAction` and are not a simple keybinding.
  */
 export interface ClioAppKeybindings {
+	"clio-coder.output.cycle": true;
 	"clio-coder.thinking.cycle": true;
 	"clio-coder.exit": true;
 	"clio-coder.status.toggle": true;
@@ -29,13 +30,9 @@ 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.tool.expand": true;
-	"clio-coder.tool.expandAll": true;
-	"clio-coder.tool.liveOutput": true;
-	"clio-coder.thinking.expand": true;
-	"clio-coder.thinking.expandAll": true;
 	"clio-coder.editor.external": true;
 	"clio-coder.message.followUp": true;
 	"clio-coder.message.interrupt": true;
@@ -56,153 +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",
-	},
-	"clio-coder.tool.expand": {
-		defaultKeys: "alt+o",
-		description:
-			"Fold or unfold the newest tool call or worker block between its one-line summary and full details, overriding the /output level for that block",
-	},
-	"clio-coder.tool.expandAll": {
-		// Alt+Shift+letter is commonly consumed by OS keyboard-layout switching.
-		// Keep it discoverable, but pair it with the legacy-safe Ctrl+Alt form.
-		defaultKeys: ["ctrl+alt+o", "alt+shift+o"],
-		description:
-			"Fold or unfold every tool call and worker block at once, overriding the /output level; changing /output clears the overrides",
-	},
-	"clio-coder.tool.liveOutput": {
-		defaultKeys: "alt+p",
-		description: "Toggle streaming partial tool output in expanded tool bodies",
-	},
-	"clio-coder.thinking.expand": {
-		defaultKeys: "alt+r",
-		description:
-			"Toggle the latest thinking block between hidden marker and full body (no effect while /output verbose pins it open)",
-	},
-	"clio-coder.thinking.expandAll": {
-		// Ctrl+Alt+R is the fallback for terminals/OSes that do not forward
-		// Alt+Shift+R as a distinct key event.
-		defaultKeys: ["ctrl+alt+r", "alt+shift+r"],
-		description:
-			"Toggle all thinking blocks between hidden markers and full bodies, overriding the /output level; changing /output clears the overrides",
+		defaultKeys: [],
+		description: "Previous scoped model",
+		scope: "composer",
+		kind: "cycle",
+		repeat: false,
 	},
-	"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;
+}