import {
type Keybinding,
type KeybindingDefinitions,
type KeybindingsConfig,
type KeyId,
TUI_KEYBINDINGS,
KeybindingsManager as TuiKeybindingsManager,
} from "@earendil-works/pi-tui";
import { existsSync, readFileSync } from "fs";
import { join } from "path";
import { getAgentDir } from "../config.js";
export interface AppKeybindings {
"app.interrupt": true;
"app.clear": true;
"app.input.clear": true;
"app.shortcuts": true;
"app.exit": true;
"app.suspend": true;
"app.model.select": true;
"app.model.toggleScope": true;
"app.configuration.previousTab": true;
"app.tools.expand": true;
"app.messages.expand": true;
"app.edits.expand": true;
"app.thinking.toggle": true;
"app.subagents.focus": true;
"app.heartbeats.open": true;
"app.heartbeats.openSelected": true;
"app.editor.external": true;
"app.prompt.stash": true;
"app.message.followUp": true;
"app.message.navigateOlder": true;
"app.message.navigateNewer": true;
"app.message.moveEarlier": true;
"app.message.moveLater": true;
"app.clipboard.pasteImage": true;
"app.clipboard.copyLoginUrl": true;
"app.session.new": true;
"app.session.tree": true;
"app.session.fork": true;
"app.session.resume": true;
"app.agents.back": true;
"app.agents.open": true;
"app.modal.back": true;
"app.agents.reply": true;
"app.agents.new": true;
"app.agents.delete": true;
"app.agents.program": true;
"app.agents.rename": true;
"app.tree.foldOrUp": true;
"app.tree.unfoldOrDown": true;
"app.tree.editLabel": true;
"app.tree.toggleLabelTimestamp": true;
"app.models.save": true;
"app.models.enableAll": true;
"app.models.clearAll": true;
"app.models.toggleProvider": true;
"app.models.reorderUp": true;
"app.models.reorderDown": true;
"app.tree.filter.default": true;
"app.tree.filter.noTools": true;
"app.tree.filter.userOnly": true;
"app.tree.filter.labeledOnly": true;
"app.tree.filter.all": true;
"app.tree.filter.cycleForward": true;
"app.tree.filter.cycleBackward": true;
}
export type AppKeybinding = keyof AppKeybindings;
declare module "@earendil-works/pi-tui" {
interface Keybindings extends AppKeybindings {}
}
export const KEYBINDINGS = {
...TUI_KEYBINDINGS,
"app.interrupt": { defaultKeys: [], description: "Interrupt current operation" },
"app.clear": { defaultKeys: "ctrl+c", description: "Interrupt current operation, then exit" },
"app.input.clear": { defaultKeys: "escape", description: "Interrupt response or clear prompt" },
"app.shortcuts": { defaultKeys: "?", description: "Show keyboard shortcuts" },
"app.exit": { defaultKeys: "ctrl+d", description: "Exit when editor is empty" },
"app.suspend": {
defaultKeys: process.platform === "win32" ? [] : "ctrl+z",
description: "Suspend to background",
},
"app.model.select": { defaultKeys: "ctrl+l", description: "Open model selector" },
"app.model.toggleScope": { defaultKeys: "alt+s", description: "Toggle model selector scope" },
"app.configuration.previousTab": { defaultKeys: "shift+tab", description: "Select previous configuration tab" },
"app.tools.expand": { defaultKeys: "ctrl+o", description: "Toggle tool output", defaultKeyScope: "editor" },
"app.messages.expand": {
defaultKeys: "ctrl+p",
description: "Toggle agent message expansion",
defaultKeyScope: "editor",
},
"app.edits.expand": { defaultKeys: "ctrl+j", description: "Toggle edit diffs", defaultKeyScope: "editor" },
"app.thinking.toggle": {
defaultKeys: "ctrl+t",
description: "Toggle thinking blocks",
defaultKeyScope: "editor",
},
"app.subagents.focus": {
defaultKeys: "alt+a",
description: "Open child agents",
},
"app.heartbeats.open": {
defaultKeys: "ctrl+r",
description: "Manage heartbeats",
},
"app.heartbeats.openSelected": {
defaultKeys: "right",
description: "Open selected heartbeat",
},
"app.editor.external": {
defaultKeys: "ctrl+g",
description: "Open external editor",
},
"app.prompt.stash": {
defaultKeys: "ctrl+s",
description: "Stash or restore draft prompt",
},
"app.message.followUp": {
defaultKeys: "alt+enter",
description: "Queue follow-up message",
},
"app.message.navigateOlder": {
defaultKeys: "alt+up",
description: "Select older pending message",
},
"app.message.navigateNewer": {
defaultKeys: "alt+down",
description: "Select newer pending message or draft",
},
"app.message.moveEarlier": {
defaultKeys: "ctrl+alt+up",
description: "Move selected pending message earlier",
},
"app.message.moveLater": {
defaultKeys: "ctrl+alt+down",
description: "Move selected pending message later",
},
"app.clipboard.pasteImage": {
defaultKeys: process.platform === "win32" ? "alt+v" : "ctrl+v",
description: "Paste image from clipboard",
},
"app.clipboard.copyLoginUrl": {
defaultKeys: ["c", "alt+c"],
description: "Copy login URL",
},
"app.session.new": { defaultKeys: [], description: "Start a new session" },
"app.session.tree": { defaultKeys: [], description: "Open session tree" },
"app.session.fork": { defaultKeys: [], description: "Fork current session" },
"app.session.resume": { defaultKeys: [], description: "Resume a session" },
"app.agents.back": { defaultKeys: "left", description: "Return to parent agent scope" },
"app.agents.open": { defaultKeys: "right", description: "Drill into selected agent" },
"app.modal.back": { defaultKeys: "left", description: "Go back / close the current dialog" },
"app.agents.reply": { defaultKeys: "space", description: "Reply to selected agent" },
"app.agents.new": { defaultKeys: "ctrl+n", description: "Start a new session from the agents view" },
"app.agents.delete": { defaultKeys: "ctrl+x", description: "Stop or delete selected agent" },
"app.agents.program": { defaultKeys: "ctrl+o", description: "Show the program that spawned subagents" },
"app.agents.rename": { defaultKeys: "ctrl+r", description: "Rename selected agent session" },
"app.tree.foldOrUp": {
defaultKeys: ["ctrl+left", "alt+left"],
description: "Fold tree branch or move up",
},
"app.tree.unfoldOrDown": {
defaultKeys: ["ctrl+right", "alt+right"],
description: "Unfold tree branch or move down",
},
"app.tree.editLabel": {
defaultKeys: "shift+l",
description: "Edit tree label",
},
"app.tree.toggleLabelTimestamp": {
defaultKeys: "shift+t",
description: "Toggle tree label timestamps",
},
"app.models.save": {
defaultKeys: "ctrl+s",
description: "Save model selection",
},
"app.models.enableAll": {
defaultKeys: "ctrl+a",
description: "Enable all models",
},
"app.models.clearAll": {
defaultKeys: "ctrl+x",
description: "Clear all models",
},
"app.models.toggleProvider": {
defaultKeys: "ctrl+p",
description: "Toggle all models for provider",
},
"app.models.reorderUp": {
defaultKeys: "alt+up",
description: "Move model up in order",
},
"app.models.reorderDown": {
defaultKeys: "alt+down",
description: "Move model down in order",
},
"app.tree.filter.default": {
defaultKeys: "ctrl+d",
description: "Tree filter: default view",
},
"app.tree.filter.noTools": {
defaultKeys: "ctrl+t",
description: "Tree filter: hide tool results",
},
"app.tree.filter.userOnly": {
defaultKeys: "ctrl+u",
description: "Tree filter: user messages only",
},
"app.tree.filter.labeledOnly": {
defaultKeys: "ctrl+l",
description: "Tree filter: labeled entries only",
},
"app.tree.filter.all": {
defaultKeys: "ctrl+a",
description: "Tree filter: show all entries",
},
"app.tree.filter.cycleForward": {
defaultKeys: "ctrl+o",
description: "Tree filter: cycle forward",
},
"app.tree.filter.cycleBackward": {
defaultKeys: "shift+ctrl+o",
description: "Tree filter: cycle backward",
},
} as const satisfies KeybindingDefinitions;
const KEYBINDING_NAME_MIGRATIONS = {
"app.message.dequeue": "app.message.navigateOlder",
cursorUp: "tui.editor.cursorUp",
cursorDown: "tui.editor.cursorDown",
cursorLeft: "tui.editor.cursorLeft",
cursorRight: "tui.editor.cursorRight",
cursorWordLeft: "tui.editor.cursorWordLeft",
cursorWordRight: "tui.editor.cursorWordRight",
cursorLineStart: "tui.editor.cursorLineStart",
cursorLineEnd: "tui.editor.cursorLineEnd",
jumpForward: "tui.editor.jumpForward",
jumpBackward: "tui.editor.jumpBackward",
pageUp: "tui.editor.pageUp",
pageDown: "tui.editor.pageDown",
deleteCharBackward: "tui.editor.deleteCharBackward",
deleteCharForward: "tui.editor.deleteCharForward",
deleteWordBackward: "tui.editor.deleteWordBackward",
deleteWordForward: "tui.editor.deleteWordForward",
deleteToLineStart: "tui.editor.deleteToLineStart",
deleteToLineEnd: "tui.editor.deleteToLineEnd",
yank: "tui.editor.yank",
yankPop: "tui.editor.yankPop",
undo: "tui.editor.undo",
newLine: "tui.input.newLine",
submit: "tui.input.submit",
tab: "tui.input.tab",
copy: "tui.input.copy",
selectUp: "tui.select.up",
selectDown: "tui.select.down",
selectPageUp: "tui.select.pageUp",
selectPageDown: "tui.select.pageDown",
selectConfirm: "tui.select.confirm",
selectCancel: "tui.select.cancel",
interrupt: "app.interrupt",
clear: "app.clear",
clearInput: "app.input.clear",
exit: "app.exit",
suspend: "app.suspend",
selectModel: "app.model.select",
expandTools: "app.tools.expand",
toggleThinking: "app.thinking.toggle",
focusSubagents: "app.subagents.focus",
externalEditor: "app.editor.external",
followUp: "app.message.followUp",
dequeue: "app.message.navigateOlder",
pasteImage: "app.clipboard.pasteImage",
newSession: "app.session.new",
tree: "app.session.tree",
fork: "app.session.fork",
resume: "app.session.resume",
agentsBack: "app.agents.back",
agentsReply: "app.agents.reply",
agentsNew: "app.agents.new",
agentsDelete: "app.agents.delete",
agentsProgram: "app.agents.program",
agentsRename: "app.agents.rename",
treeFoldOrUp: "app.tree.foldOrUp",
treeUnfoldOrDown: "app.tree.unfoldOrDown",
treeEditLabel: "app.tree.editLabel",
treeToggleLabelTimestamp: "app.tree.toggleLabelTimestamp",
} as const satisfies Record<string, Keybinding>;
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function isLegacyKeybindingName(key: string): key is keyof typeof KEYBINDING_NAME_MIGRATIONS {
return key in KEYBINDING_NAME_MIGRATIONS;
}
function toKeybindingsConfig(value: unknown): KeybindingsConfig {
if (!isRecord(value)) return {};
const config: KeybindingsConfig = {};
for (const [key, binding] of Object.entries(value)) {
if (typeof binding === "string") {
config[key] = binding as KeyId;
continue;
}
if (Array.isArray(binding) && binding.every((entry) => typeof entry === "string")) {
config[key] = binding as KeyId[];
}
}
return config;
}
export function migrateKeybindingsConfig(rawConfig: Record<string, unknown>): {
config: Record<string, unknown>;
migrated: boolean;
} {
const config: Record<string, unknown> = {};
let migrated = false;
for (const [key, value] of Object.entries(rawConfig)) {
const nextKey = isLegacyKeybindingName(key) ? KEYBINDING_NAME_MIGRATIONS[key] : key;
if (nextKey !== key) {
migrated = true;
}
if (key !== nextKey && Object.hasOwn(rawConfig, nextKey)) {
migrated = true;
continue;
}
config[nextKey] = value;
}
return { config: orderKeybindingsConfig(config), migrated };
}
function orderKeybindingsConfig(config: Record<string, unknown>): Record<string, unknown> {
const ordered: Record<string, unknown> = {};
for (const keybinding of Object.keys(KEYBINDINGS)) {
if (Object.hasOwn(config, keybinding)) {
ordered[keybinding] = config[keybinding];
}
}
const extras = Object.keys(config)
.filter((key) => !Object.hasOwn(ordered, key))
.sort();
for (const key of extras) {
ordered[key] = config[key];
}
return ordered;
}
function loadRawConfig(path: string): Record<string, unknown> | undefined {
if (!existsSync(path)) return undefined;
try {
const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
return isRecord(parsed) ? parsed : undefined;
} catch {
return undefined;
}
}
export class KeybindingsManager extends TuiKeybindingsManager {
private configPath: string | undefined;
constructor(userBindings: KeybindingsConfig = {}, configPath?: string) {
super(KEYBINDINGS, userBindings);
this.configPath = configPath;
}
static create(agentDir: string = getAgentDir()): KeybindingsManager {
const configPath = join(agentDir, "keybindings.json");
const userBindings = KeybindingsManager.loadFromFile(configPath);
return new KeybindingsManager(userBindings, configPath);
}
reload(): void {
if (!this.configPath) return;
this.setUserBindings(KeybindingsManager.loadFromFile(this.configPath));
}
getEffectiveConfig(): KeybindingsConfig {
return this.getResolvedBindings();
}
private static loadFromFile(path: string): KeybindingsConfig {
const rawConfig = loadRawConfig(path);
if (!rawConfig) return {};
return toKeybindingsConfig(migrateKeybindingsConfig(rawConfig).config);
}
}
export type { Keybinding, KeybindingsConfig, KeyId };