@sagmans/pi-prefix 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sagmans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# @sagmans/pi-prefix
+
+A prefix key for [Pi](https://github.com/earendil-works/pi): press
+one configurable prefix key, then a second key, to trigger a Pi app action, a
+slash command, or an extension event.
+
+- **Zero-keymap by default.** No prefix and no bindings ship with the package.
+  Without configuration the extension is completely inert.
+- **Your keybindings stay authoritative.** A prefix that collides with an
+  active main-editor binding disables pi-prefix and reports the exact
+  keybinding ids. pi-prefix never edits `keybindings.json`.
+- **No arbitrary code.** Targets are app actions, slash commands, and events.
+  There is no executable target.
+
+## Security warning
+
+Pi packages execute with your user privileges. Review this repository before
+installing. Report vulnerabilities privately (see SECURITY.md).
+
+## Install
+
+After publication:
+
+```bash
+pi install npm:@sagmans/pi-prefix@0.1.0
+```
+
+Then restart Pi (or run `/reload`).
+
+## Ask your agent
+
+Ask your coding agent to configure pi-prefix for you, for example:
+
+> Set up @sagmans/pi-prefix for me: prefix ctrl+x, with m for model picker,
+> h for /hotkeys submitted, and a binding for the open event of the extension
+> I use.
+
+The package ships a skill that guides agents through the same steps.
+
+## Configuration
+
+Two layers, merged in order **defaults → global → project**:
+
+| Layer | Path | When loaded |
+| --- | --- | --- |
+| Global | `~/.pi/agent/pi-prefix.json` | always |
+| Project | `<project>/.pi/pi-prefix.json` | only when the project is trusted |
+
+Project scalar values (`prefix`, `timeoutMs`) replace global values. Project
+bindings add or replace global bindings by normalized key; `null` removes an
+inherited binding. Activation needs an effective `prefix` and at least one
+effective binding. Any parse or validation error fails the whole effective
+config with the source path and reason.
+
+`~/.pi/agent/pi-prefix.json` example:
+
+```json
+{
+  "$schema": "https://unpkg.com/@sagmans/pi-prefix/schema.json",
+  "prefix": "ctrl+x",
+  "timeoutMs": 2000,
+  "bindings": {
+    "m": { "action": "app.model.select" },
+    "h": { "command": "/hotkeys", "submit": true },
+    "a": { "command": "/third-party-command", "submit": false },
+    "o": { "event": "example-extension:open", "payload": { "source": "pi-prefix" } }
+  }
+}
+```
+
+Trusted project overlay example (`<project>/.pi/pi-prefix.json`):
+
+```json
+{
+  "bindings": {
+    "o": null,
+    "w": { "command": "/project-command", "submit": true }
+  }
+}
+```
+
+### Schema reference
+
+All properties are optional at layer level.
+
+- `prefix` — one key id, e.g. `ctrl+x`, `f9`, `alt+shift+p`. See Pi's
+  keybinding format (`modifier+key`, modifiers `ctrl`, `shift`, `alt`,
+  `super`; aliases `esc`/`return` are normalized to `escape`/`enter`).
+- `timeoutMs` — positive integer; prefix mode clears after this idle time.
+  Default `2000`.
+- `bindings` — map of second key id to exactly one target, or `null` to
+  remove an inherited binding:
+  - `{ "action": "app.model.select" }` — a Pi app action. Unknown or
+    context-only actions notify when pressed instead of throwing.
+  - `{ "command": "/hotkeys", "submit": true }` — a slash command.
+    `submit: true` runs the command immediately; extension commands run
+    without touching the editor draft, anything else replaces the draft and
+    submits. `submit: false` types the command and stops.
+  - `{ "event": "example-extension:open", "payload": {} }` — emits the event
+    name and exact JSON payload through `pi.events`. The extension that owns
+    the event defines valid names and payloads.
+
+Escape is reserved for canceling prefix mode; a binding on `escape` loads
+with a warning and can never dispatch. Enter, tab, and arrows are valid second
+keys.
+
+### Command behavior
+
+With `submit: true`, **extension commands** (those listed by `/commands` with
+the `extension` source, e.g. a mode toggle installed from another package) are
+dispatched directly through Pi's command pipeline and the current editor draft
+is preserved untouched. Any other command — built-ins like `/model` or
+third-party commands Pi reports without the `extension` source — replaces the
+draft and submits it through the editor,
+matching manual typing. With `submit: false` the command text sits in the
+editor until you press Enter, which is the right form for commands that take an
+argument.
+
+## Conflicts and /pi-prefix
+
+On startup pi-prefix scans Pi's main-editor bindings. A colliding prefix
+disables pi-prefix with an error naming the exact keybinding ids. Existing
+bindings are never changed. Fix by choosing another prefix or rebinding the
+conflicting action yourself in `~/.pi/agent/keybindings.json`, then `/reload`.
+
+Third-party extension shortcuts cannot be inventoried publicly: Pi reports
+those collisions under **[Extension issues]** and resolves them by load order.
+That limitation is Pi's, not pi-prefix's.
+
+`/pi-prefix` prints active/inactive state, loaded config paths, trust state,
+effective prefix, timeout, a binding summary, config errors and warnings, and
+any Pi keybinding conflicts.
+
+## What pi-prefix does not do
+
+- No shipped prefix, keymap, or bindings.
+- No self-registration protocol for other extensions.
+- No arbitrary-code targets and no private Pi APIs.
+- No automatic conflict edits; reports only.
+- No raw global terminal input interception; activation goes through Pi's
+  native shortcut registration.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm pack --dry-run   # package-content gate
+```

package/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest released line of `@sagmans/pi-prefix` is supported with
+security fixes.
+
+## Pi packages run with your privileges
+
+A Pi package is code that runs on your machine with your user privileges when
+Pi loads it. Review any package before installing it, including this one.
+
+## Reporting a vulnerability
+
+Report vulnerabilities through GitHub private vulnerability reporting
+(GitHub Security Advisories) for `sagmans/pi-prefix`. Do not open public
+issues for unpatched vulnerabilities; public reports about an unpatched flaw
+put every user at risk.
+
+Include the package version, the config layers involved, and reproduction
+steps where possible.

package/defaults.json

@@ -0,0 +1,3 @@
+{
+  "timeoutMs": 2000
+}

package/index.ts

@@ -0,0 +1,197 @@
+import { CustomEditor, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { EditorComponent, EditorTheme, KeyId, TUI } from "@earendil-works/pi-tui";
+import { loadConfig } from "./src/config.ts";
+import type { LoadConfigResult } from "./src/config.ts";
+import { findPrefixConflicts } from "./src/conflicts.ts";
+import type { PrefixConflict } from "./src/conflicts.ts";
+import { PrefixEditor } from "./src/prefix-editor.ts";
+
+const STATUS_KEY = "pi-prefix";
+const STATUS_COMMAND = "pi-prefix";
+const SHORTCUT_DESCRIPTION = "Activate the pi-prefix prefix key";
+// WHY: third-party shortcut collisions cannot be inventoried publicly; Pi
+// resolves them by load order and reports them under Extension issues.
+const THIRD_PARTY_LIMIT_NOTE =
+  "Third-party extension shortcut collisions are reported by Pi under [Extension issues] and resolved by load order.";
+// WHY: only extension-owned commands can execute through sendUserMessage;
+// built-in interactive commands and templates need the editor-submit path.
+const EXTENSION_COMMAND_SOURCE = "extension";
+const COMMAND_NAME_SEPARATOR = " ";
+const COMMAND_PREFIX = "/";
+
+type SessionState = {
+  result: LoadConfigResult;
+  projectTrusted: boolean;
+  wrapper: PrefixEditor | undefined;
+  conflicts: PrefixConflict[];
+  shortcutRegistered: boolean;
+};
+
+function formatDiagnostics(result: LoadConfigResult, level: "error" | "warning"): string[] {
+  return result.diagnostics
+    .filter((diagnostic) => diagnostic.level === level)
+    .map((diagnostic) => `${diagnostic.path}: ${diagnostic.message}`);
+}
+
+function extensionCommandName(command: string): string {
+  const withoutPrefix = command.startsWith(COMMAND_PREFIX) ? command.slice(COMMAND_PREFIX.length) : command;
+  const separatorIndex = withoutPrefix.indexOf(COMMAND_NAME_SEPARATOR);
+  return separatorIndex === -1 ? withoutPrefix : withoutPrefix.slice(0, separatorIndex);
+}
+
+function bindingSummary(state: SessionState): string {
+  const bindings = state.result.config?.bindings;
+  if (bindings === undefined) return "none";
+  return [...bindings.entries()]
+    .map(([key, target]) => {
+      const description =
+        "action" in target
+          ? `action ${target.action}`
+          : "command" in target
+            ? `command ${target.command}${target.submit ? " (submit)" : ""}`
+            : `event ${target.event}`;
+      return `${key} -> ${description}`;
+    })
+    .join(", ");
+}
+
+function statusMessage(state: SessionState | undefined, agentDir: string): string {
+  if (state === undefined || state.result.config === undefined) {
+    return [
+      "pi-prefix: inactive",
+      `global config: ${agentDir}/pi-prefix.json`,
+      "No effective prefix and bindings. See the package README for configuration.",
+    ].join(" | ");
+  }
+  const { config } = state.result;
+  const lines = [
+    state.conflicts.length > 0 ? "pi-prefix: disabled (conflicts)" : "pi-prefix: active",
+    `prefix: ${config.prefix}`,
+    `timeout: ${config.timeoutMs}ms`,
+    `bindings: ${bindingSummary(state)}`,
+    `project trusted: ${state.projectTrusted ? "yes" : "no"}`,
+    `global: ${state.result.globalPath}`,
+    `project: ${state.result.projectPath}${state.result.projectLoaded ? " (loaded)" : ""}`,
+  ];
+  for (const error of formatDiagnostics(state.result, "error")) {
+    lines.push(`error: ${error}`);
+  }
+  for (const warning of formatDiagnostics(state.result, "warning")) {
+    lines.push(`warning: ${warning}`);
+  }
+  for (const conflict of state.conflicts) {
+    lines.push(`conflict: ${conflict.key} is bound to ${conflict.keybinding}`);
+  }
+  lines.push(THIRD_PARTY_LIMIT_NOTE);
+  return lines.join(" | ");
+}
+
+export function setupPiPrefix(
+  pi: ExtensionAPI,
+  options: { agentDir: string },
+): void {
+  let state: SessionState | undefined;
+
+  pi.registerCommand(STATUS_COMMAND, {
+    description: "Show pi-prefix status, loaded config layers, and conflicts",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      ctx.ui.notify(statusMessage(state, options.agentDir), "info");
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    const result = loadConfig({
+      agentDir: options.agentDir,
+      cwd: ctx.cwd,
+      projectTrusted: ctx.isProjectTrusted(),
+    });
+    for (const error of formatDiagnostics(result, "error")) {
+      ctx.ui.notify(`pi-prefix: ${error}`, "error");
+    }
+    for (const warning of formatDiagnostics(result, "warning")) {
+      ctx.ui.notify(`pi-prefix: ${warning}`, "warning");
+    }
+    if (result.config === undefined) {
+      // WHY: absence of a full map is ordinary; the extension stays inert
+      // without touching the editor chain.
+      return;
+    }
+    state = {
+      result,
+      projectTrusted: ctx.isProjectTrusted(),
+      wrapper: undefined,
+      conflicts: [],
+      shortcutRegistered: false,
+    };
+    const sessionState: SessionState = state;
+    const previousFactory = ctx.ui.getEditorComponent();
+    ctx.ui.setEditorComponent(
+      (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => {
+        const inner: EditorComponent = previousFactory
+          ? previousFactory(tui, theme, keybindings)
+          : new CustomEditor(tui, theme, keybindings);
+        const config = sessionState.result.config;
+        if (config === undefined) {
+          return inner;
+        }
+        const wrapper = new PrefixEditor(tui, theme, keybindings, inner, {
+          config,
+          emitEvent: (event, payload) => pi.events.emit(event, payload),
+          setStatus: (text) => ctx.ui.setStatus(STATUS_KEY, text),
+          notify: (message, type) => ctx.ui.notify(message, type),
+          dispatchExtensionCommand: (command) => {
+            const name = extensionCommandName(command);
+            const isExtensionCommand = pi.getCommands().some(
+              (available) => available.name === name && available.source === EXTENSION_COMMAND_SOURCE,
+            );
+            if (!isExtensionCommand) return false;
+            pi.sendUserMessage(command, { expandPromptTemplates: true });
+            return true;
+          },
+        });
+        if (!sessionState.shortcutRegistered) {
+          // WHY: the editor factory is the only place Pi hands extensions the
+          // authoritative keybinding manager, so conflict scanning and native
+          // registration both happen here, once per session.
+          const conflicts = findPrefixConflicts(config.prefix, keybindings);
+          if (conflicts.length > 0) {
+            sessionState.conflicts = conflicts;
+            const ids = conflicts.map((conflict) => conflict.keybinding).join(", ");
+            ctx.ui.notify(
+              `pi-prefix disabled: prefix ${config.prefix} conflicts with ${ids}`,
+              "error",
+            );
+            wrapper.dispose();
+            sessionState.wrapper = wrapper;
+            return wrapper;
+          }
+          pi.registerShortcut(config.prefix as KeyId, {
+            description: SHORTCUT_DESCRIPTION,
+            handler: () => {
+              sessionState.wrapper?.activate();
+            },
+          });
+          sessionState.shortcutRegistered = true;
+        }
+        sessionState.wrapper = wrapper;
+        return wrapper;
+      },
+    );
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    state?.wrapper?.dispose();
+    state = undefined;
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  });
+}
+
+export default function (pi: ExtensionAPI): void {
+  setupPiPrefix(pi, { agentDir: getAgentDir() });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sagmans/pi-prefix",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Configurable prefix key that maps a second key to Pi app actions, slash commands, or extension events",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sagmans/pi-prefix.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "keybindings",
+    "prefix"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "defaults.json",
+    "schema.json",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "test": "node --experimental-transform-types --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.4 <0.85.0",
+    "@earendil-works/pi-tui": ">=0.84.4 <0.85.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.4 <0.85.0",
+    "@earendil-works/pi-tui": ">=0.84.4 <0.85.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  },
+  "pi": {
+    "extensions": ["./index.ts"],
+    "skills": ["./skills"]
+  }
+}

package/schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@sagmans/pi-prefix/schema.json",
+  "title": "pi-prefix configuration layer",
+  "description": "One configuration layer for @sagmans/pi-prefix. All properties are optional so project layers can be partial overlays.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "prefix": { "$ref": "#/definitions/keyId" },
+    "timeoutMs": { "type": "integer", "exclusiveMinimum": 0 },
+    "bindings": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "null" },
+          { "$ref": "#/definitions/actionTarget" },
+          { "$ref": "#/definitions/commandTarget" },
+          { "$ref": "#/definitions/eventTarget" }
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "keyId": {
+      "type": "string",
+      "pattern": "^(ctrl\+)?(shift\+)?(alt\+)?(super\+)?([a-z]|[0-9]|escape|enter|tab|space|backspace|delete|insert|clear|home|end|pageUp|pageDown|up|down|left|right|f1|f2|f3|f4|f5|f6|f7|f8|f9|f10|f11|f12|`|-|=|\[|\]|\\|;|'|,|\.|/|!|@|#|\$|%|\^|&|\*|\(|\)|_|\+|\||~|\{|\}|:|<|>|\?)$"
+    },
+    "actionTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "action": { "type": "string", "minLength": 1 }
+      }
+    },
+    "commandTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "submit"],
+      "properties": {
+        "command": { "type": "string", "pattern": "^/" },
+        "submit": { "type": "boolean" }
+      }
+    },
+    "eventTarget": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["event"],
+      "properties": {
+        "event": { "type": "string", "minLength": 1 },
+        "payload": {}
+      }
+    }
+  }
+}

package/skills/pi-prefix/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pi-prefix
+description: Configure or troubleshoot @sagmans/pi-prefix (Pi prefix-key package). Use when the user asks to set up, change, or fix pi-prefix prefix keys, bindings, conflicts, or config layers.
+---
+
+# pi-prefix configuration
+
+Configure @sagmans/pi-prefix. Two layers: global `~/.pi/agent/pi-prefix.json`,
+trusted project `<project>/.pi/pi-prefix.json`. Edit the smallest layer that
+fits: global for user-wide behavior, project for project-only additions,
+replacements, or removals (`null` removes an inherited binding).
+
+## Before editing
+
+1. Read both existing config layers if present.
+2. Read Pi's `~/.pi/agent/keybindings.json` for active bindings.
+3. Ask the user for the prefix and each target's intent when missing. Never
+   invent third-party event names, payloads, or command names; ask for the
+   exact values or check the target extension's documentation with the user.
+
+## Target selection order
+
+Prefer a built-in app action, then a slash command, then a documented
+extension event.
+
+## Writing the config
+
+- Bindings take exactly one of `action`, `command` (+ required `submit`),
+  or `event` (+ optional `payload`).
+- `submit: true` runs the command immediately — commands whose `/commands`
+  source is `extension` dispatch directly and keep the editor draft intact,
+  anything else replaces the draft; `submit: false` types it for
+  argument-taking commands.
+- Commands must start with `/`. Timeouts must be positive integers.
+- Validate the JSON against schema.json before saving.
+
+## Conflicts
+
+If the prefix collides with an active main-editor binding, pi-prefix reports
+the exact keybinding ids and stays disabled. Never silently unbind or reassign
+a conflict. Report it and ask the user which existing binding should move.
+
+## After editing
+
+Tell the user to run `/reload`, then `/pi-prefix` to verify the effective
+prefix, timeout, bindings, and warnings.

package/src/config.ts

@@ -0,0 +1,373 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// WHY: rebranded Pi distributions may rename the project config directory;
+// the exported constant is the only rebrand-safe source.
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+export type PrefixTarget =
+  | { action: string }
+  | { command: string; submit: boolean }
+  | { event: string; payload?: unknown };
+
+export type PrefixConfigLayer = {
+  $schema?: string;
+  prefix?: string;
+  timeoutMs?: number;
+  bindings?: Record<string, PrefixTarget | null>;
+};
+
+export type EffectivePrefixConfig = {
+  prefix: KeyId;
+  timeoutMs: number;
+  bindings: ReadonlyMap<KeyId, PrefixTarget>;
+};
+
+export type ConfigDiagnostic = {
+  level: "error" | "warning";
+  path: string;
+  message: string;
+};
+
+export type LoadConfigOptions = {
+  agentDir: string;
+  cwd: string;
+  projectTrusted: boolean;
+};
+
+export type LoadConfigResult = {
+  config?: EffectivePrefixConfig;
+  diagnostics: ConfigDiagnostic[];
+  globalPath: string;
+  projectPath: string;
+  projectLoaded: boolean;
+};
+
+// WHY: pi-tui defines modifier order as ctrl, shift, alt, super; canonical
+// ordering keeps equivalent spellings from becoming distinct map entries.
+const MODIFIER_ORDER = ["ctrl", "shift", "alt", "super"] as const;
+
+const MODIFIER_SET = new Set<string>(MODIFIER_ORDER);
+
+// WHY: pi-tui accepts legacy aliases; canonicalizing them makes conflict
+// comparison and binding lookup unambiguous.
+const KEY_ALIASES: Record<string, string> = {
+  esc: "escape",
+  return: "enter",
+};
+
+const SPECIAL_KEYS = new Set([
+  "escape",
+  "enter",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "clear",
+  "home",
+  "end",
+  "pageUp",
+  "pageDown",
+  "up",
+  "down",
+  "left",
+  "right",
+  ...Array.from({ length: 12 }, (_, index) => `f${index + 1}`),
+]);
+
+const SYMBOL_KEYS = new Set(
+  "`-=[]\\;',./!@#$%^&*()_+|~{}:<>?".split(""),
+);
+
+const LAYER_TOP_LEVEL_KEYS = new Set(["$schema", "prefix", "timeoutMs", "bindings"]);
+const TARGET_KEYS = ["action", "command", "event"] as const;
+// WHY: submit belongs to command targets and payload to event targets; both
+// must pass the unknown-property guard before kind-specific validation.
+const TARGET_PROPERTIES = [...TARGET_KEYS, "submit", "payload"] as const;
+const ESCAPE_KEY = "escape";
+const DEFAULT_TIMEOUT_MS = 2000;
+const CONFIG_FILE_NAME = "pi-prefix.json";
+
+const DEFAULTS_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "defaults.json",
+);
+
+function isLetter(value: string): boolean {
+  return value.length === 1 && value >= "a" && value <= "z";
+}
+
+function isDigit(value: string): boolean {
+  return value.length === 1 && value >= "0" && value <= "9";
+}
+
+function isUpperLetter(value: string): boolean {
+  return value.length === 1 && value >= "A" && value <= "Z";
+}
+
+export function normalizeKeyId(value: string): KeyId | undefined {
+  if (typeof value !== "string" || value.length === 0) {
+    return undefined;
+  }
+  if (value === "+") {
+    // WHY: "+" is a valid symbol key whose spelling collides with the
+    // modifier separator; handle it before splitting.
+    return "+" as KeyId;
+  }
+  const parts = value.split("+");
+  // WHY: empty segments mean malformed ids like "ctrl++x".
+  if (parts.some((part) => part.length === 0)) {
+    return undefined;
+  }
+  const rawKey = parts[parts.length - 1];
+  const rawModifiers = parts.slice(0, -1);
+  if (rawModifiers.some((modifier) => !MODIFIER_SET.has(modifier))) {
+    return undefined;
+  }
+  const modifierSet = new Set(rawModifiers);
+  // WHY: duplicate modifiers like "ctrl+ctrl+x" must not silently collapse.
+  if (modifierSet.size !== rawModifiers.length) {
+    return undefined;
+  }
+  let key: string | undefined;
+  if (isUpperLetter(rawKey)) {
+    key = rawKey.toLowerCase();
+    modifierSet.add("shift");
+  } else if (isLetter(rawKey) || isDigit(rawKey)) {
+    key = rawKey;
+  } else if (KEY_ALIASES[rawKey] !== undefined) {
+    key = KEY_ALIASES[rawKey];
+  } else if (SPECIAL_KEYS.has(rawKey)) {
+    key = rawKey;
+  } else if (SYMBOL_KEYS.has(rawKey)) {
+    key = rawKey;
+  }
+  if (key === undefined) {
+    return undefined;
+  }
+  const ordered = MODIFIER_ORDER.filter((modifier) => modifierSet.has(modifier));
+  return (ordered.length > 0 ? `${ordered.join("+")}+${key}` : key) as KeyId;
+}
+
+type ParsedTarget = PrefixTarget | null;
+
+function validateTarget(
+  value: unknown,
+  keyLabel: string,
+  path: string,
+  diagnostics: ConfigDiagnostic[],
+): ParsedTarget | undefined {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" must be an object or null` });
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  for (const property of Object.keys(record)) {
+    if (!(TARGET_PROPERTIES as readonly string[]).includes(property)) {
+      diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" has unknown property "${property}"` });
+      return undefined;
+    }
+  }
+  const present = TARGET_KEYS.filter((kind) => record[kind] !== undefined);
+  if (present.length !== 1) {
+    diagnostics.push({
+      level: "error",
+      path,
+      message: `binding "${keyLabel}" must contain exactly one of action, command, or event`,
+    });
+    return undefined;
+  }
+  const kind = present[0];
+  if (record.payload !== undefined && kind !== "event") {
+    // WHY: payload is only meaningful for event targets; elsewhere it hides
+    // configuration mistakes.
+    diagnostics.push({
+      level: "error",
+      path,
+      message: `binding "${keyLabel}" payload is only allowed with event targets`,
+    });
+    return undefined;
+  }
+  if (kind === "action") {
+    if (typeof record.action !== "string" || record.action.length === 0) {
+      diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" action must be a non-empty string` });
+      return undefined;
+    }
+    return { action: record.action };
+  }
+  if (kind === "command") {
+    if (typeof record.command !== "string" || !record.command.startsWith("/")) {
+      diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" command must start with "/"` });
+      return undefined;
+    }
+    if (typeof record.submit !== "boolean") {
+      diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" submit must be a boolean` });
+      return undefined;
+    }
+    return { command: record.command, submit: record.submit };
+  }
+  if (typeof record.event !== "string" || record.event.length === 0) {
+    diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" event must be a non-empty string` });
+    return undefined;
+  }
+  if (record.payload !== undefined && typeof record.payload !== "object") {
+    diagnostics.push({ level: "error", path, message: `binding "${keyLabel}" payload must be an object` });
+    return undefined;
+  }
+  return record.payload !== undefined
+    ? { event: record.event, payload: record.payload }
+    : { event: record.event };
+}
+
+type ParsedLayer = {
+  prefix?: KeyId;
+  timeoutMs?: number;
+  bindings?: Map<KeyId, PrefixTarget | null>;
+};
+
+function parseLayer(
+  raw: string,
+  path: string,
+  isDefaults: boolean,
+  diagnostics: ConfigDiagnostic[],
+): ParsedLayer | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    diagnostics.push({ level: "error", path, message: `invalid JSON: ${(error as Error).message}` });
+    return undefined;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    diagnostics.push({ level: "error", path, message: "configuration must be a JSON object" });
+    return undefined;
+  }
+  const record = parsed as Record<string, unknown>;
+  for (const property of Object.keys(record)) {
+    if (!LAYER_TOP_LEVEL_KEYS.has(property)) {
+      diagnostics.push({ level: "error", path, message: `unknown property "${property}"` });
+      return undefined;
+    }
+  }
+  const layer: ParsedLayer = {};
+  if (record.prefix !== undefined) {
+    const normalized = normalizeKeyId(record.prefix as string);
+    if (normalized === undefined) {
+      diagnostics.push({ level: "error", path, message: `prefix "${String(record.prefix)}" is not a valid key id` });
+      return undefined;
+    }
+    layer.prefix = normalized;
+  }
+  if (record.timeoutMs !== undefined) {
+    const timeout = record.timeoutMs;
+    // WHY: any positive integer is accepted by design; the guard only rejects
+    // values a timer cannot schedule meaningfully.
+    if (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout <= 0) {
+      diagnostics.push({ level: "error", path, message: `timeoutMs must be a positive integer, got ${String(timeout)}` });
+      return undefined;
+    }
+    layer.timeoutMs = timeout;
+  }
+  if (record.bindings !== undefined) {
+    if (typeof record.bindings !== "object" || record.bindings === null || Array.isArray(record.bindings)) {
+      diagnostics.push({ level: "error", path, message: "bindings must be an object" });
+      return undefined;
+    }
+    const bindings = new Map<KeyId, PrefixTarget | null>();
+    for (const [rawKey, rawTarget] of Object.entries(record.bindings)) {
+      const normalizedKey = normalizeKeyId(rawKey);
+      if (normalizedKey === undefined) {
+        diagnostics.push({ level: "error", path, message: `binding key "${rawKey}" is not a valid key id` });
+        return undefined;
+      }
+      if (normalizedKey === ESCAPE_KEY) {
+        // WHY: escape is reserved for canceling prefix mode; warn instead of
+        // failing so a single bad binding never disables the whole map.
+        diagnostics.push({
+          level: "warning",
+          path,
+          message: 'binding "escape" can never dispatch; escape cancels prefix mode',
+        });
+      }
+      const target = validateTarget(rawTarget, rawKey, path, diagnostics);
+      if (target === undefined) {
+        return undefined;
+      }
+      bindings.set(normalizedKey, target);
+    }
+    layer.bindings = bindings;
+  }
+  if (isDefaults && (layer.prefix !== undefined || layer.bindings !== undefined)) {
+    // WHY: shipped defaults must stay neutral; a packaged default keymap would
+    // surprise users on first install.
+    diagnostics.push({ level: "error", path, message: "defaults must not ship a prefix or bindings" });
+    return undefined;
+  }
+  return layer;
+}
+
+function readLayer(
+  path: string,
+  isDefaults: boolean,
+  diagnostics: ConfigDiagnostic[],
+): ParsedLayer | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    // WHY: absence is ordinary; only malformed content is a diagnostic.
+    return undefined;
+  }
+  return parseLayer(raw, path, isDefaults, diagnostics);
+}
+
+export function loadConfig(options: LoadConfigOptions): LoadConfigResult {
+  const diagnostics: ConfigDiagnostic[] = [];
+  const globalPath = join(options.agentDir, CONFIG_FILE_NAME);
+  const projectPath = join(options.cwd, CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+
+  const defaultsLayer = readLayer(DEFAULTS_PATH, true, diagnostics);
+  const globalLayer = readLayer(globalPath, false, diagnostics);
+  let projectLayer: ParsedLayer | undefined;
+  let projectLoaded = false;
+  if (options.projectTrusted) {
+    projectLayer = readLayer(projectPath, false, diagnostics);
+    projectLoaded = projectLayer !== undefined;
+  }
+
+  const result: LoadConfigResult = { diagnostics, globalPath, projectPath, projectLoaded };
+  // WHY: any error in any loaded layer fails the whole effective config so a
+  // partially merged map can never activate.
+  if (diagnostics.some((diagnostic) => diagnostic.level === "error")) {
+    return result;
+  }
+  const prefix = projectLayer?.prefix ?? globalLayer?.prefix;
+  const timeoutMs =
+    projectLayer?.timeoutMs ?? globalLayer?.timeoutMs ?? defaultsLayer?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const bindings = new Map<KeyId, PrefixTarget>();
+  const overlays = [globalLayer, projectLayer];
+  for (const overlay of overlays) {
+    if (overlay?.bindings === undefined) {
+      continue;
+    }
+    for (const [key, target] of overlay.bindings) {
+      if (target === null) {
+        bindings.delete(key);
+      } else {
+        bindings.set(key, target);
+      }
+    }
+  }
+  if (prefix === undefined || bindings.size === 0) {
+    // WHY: inert is the safe default; absence of a full map is not an error.
+    return result;
+  }
+  result.config = { prefix, timeoutMs, bindings };
+  return result;
+}

package/src/conflicts.ts

@@ -0,0 +1,71 @@
+import type { KeyId, KeybindingsManager } from "@earendil-works/pi-tui";
+import { normalizeKeyId } from "./config.ts";
+
+export type PrefixConflict = {
+  key: KeyId;
+  keybinding: string;
+};
+
+// WHY: only these app actions are wired into Pi's main editor; picker- and
+// dialog-only actions (tui.select.*, app.tree.*, app.models.*) never fire
+// while the editor has focus, so they are not conflicts.
+const MAIN_EDITOR_APP_ACTIONS = [
+  "app.interrupt",
+  "app.clear",
+  "app.exit",
+  "app.suspend",
+  "app.thinking.cycle",
+  "app.model.cycleForward",
+  "app.model.cycleBackward",
+  "app.model.select",
+  "app.tools.expand",
+  "app.thinking.toggle",
+  "app.editor.external",
+  "app.message.copy",
+  "app.message.followUp",
+  "app.message.dequeue",
+  "app.clipboard.pasteImage",
+  "app.session.new",
+  "app.session.tree",
+  "app.session.fork",
+  "app.session.resume",
+] as const;
+
+const MAIN_EDITOR_PREFIXES = ["tui.editor.", "tui.input."];
+const MAIN_EDITOR_IDS = new Set<string>(MAIN_EDITOR_APP_ACTIONS);
+
+function isMainEditorBinding(id: string): boolean {
+  return (
+    MAIN_EDITOR_IDS.has(id) ||
+    MAIN_EDITOR_PREFIXES.some((prefix) => id.startsWith(prefix))
+  );
+}
+
+export function findPrefixConflicts(
+  prefix: KeyId,
+  keybindings: KeybindingsManager,
+): PrefixConflict[] {
+  const normalizedPrefix = normalizeKeyId(prefix);
+  if (normalizedPrefix === undefined) {
+    return [];
+  }
+  const conflicts: PrefixConflict[] = [];
+  for (const [id, keys] of Object.entries(keybindings.getResolvedBindings())) {
+    if (!isMainEditorBinding(id)) {
+      continue;
+    }
+    const keyList = Array.isArray(keys) ? keys : [keys];
+    for (const rawKey of keyList) {
+      if (rawKey === undefined) {
+        continue;
+      }
+      const normalized = normalizeKeyId(rawKey);
+      if (normalized === normalizedPrefix) {
+        conflicts.push({ key: normalized, keybinding: id });
+      }
+    }
+  }
+  // WHY: stable output keeps /pi-prefix diagnostics and tests deterministic.
+  conflicts.sort((a, b) => a.keybinding.localeCompare(b.keybinding));
+  return conflicts;
+}

package/src/prefix-editor.ts

@@ -0,0 +1,260 @@
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import type { AppKeybinding, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+import type {
+  AutocompleteProvider,
+  EditorComponent,
+  EditorTheme,
+  KeyId,
+  TUI,
+} from "@earendil-works/pi-tui";
+import type { EffectivePrefixConfig, PrefixTarget } from "./config.ts";
+
+export type PrefixEditorOptions = {
+  config: EffectivePrefixConfig;
+  emitEvent: (event: string, payload?: unknown) => void;
+  setStatus: (text: string | undefined) => void;
+  notify: (message: string, type?: "info" | "warning" | "error") => void;
+  // WHY: editor-independent commands must not sacrifice the user's draft, so
+  // the host decides whether direct dispatch applies before any setText.
+  dispatchExtensionCommand: (command: string) => boolean;
+};
+
+// WHY: Pi wires these three app actions through replaceable callbacks rather
+// than the ordinary actionHandlers map; dispatch must honor the same paths.
+const INTERRUPT_ACTION: AppKeybinding = "app.interrupt";
+const EXIT_ACTION: AppKeybinding = "app.exit";
+const PASTE_IMAGE_ACTION: AppKeybinding = "app.clipboard.pasteImage";
+const CANCEL_KEY: KeyId = "escape";
+const STATUS_KEY = "pi-prefix";
+const ENTER_INPUT = "\r";
+
+// Layer prefix behavior over whichever editor another extension installed.
+type WrappedEditor = EditorComponent & {
+  actionHandlers?: Map<AppKeybinding, () => void>;
+  onSubmit?: (text: string) => void;
+  onChange?: (text: string) => void;
+  disableSubmit?: boolean;
+  focused?: boolean;
+  onEscape?: () => void;
+  onCtrlD?: () => void;
+  onPasteImage?: () => void;
+  onExtensionShortcut?: (data: string) => boolean;
+};
+
+function modifierMask(parts: string[]): number {
+  let modifier = 0;
+  if (parts.includes("shift")) modifier |= 1;
+  if (parts.includes("alt")) modifier |= 2;
+  if (parts.includes("ctrl")) modifier |= 4;
+  if (parts.includes("super")) modifier |= 8;
+  return modifier;
+}
+
+function inputForKey(keyId: string): string | undefined {
+  const parts = keyId.toLowerCase().split("+");
+  const key = parts.pop();
+  if (!key) return undefined;
+  if (key === "enter" || key === "return") {
+    const modifier = modifierMask(parts);
+    return modifier === 0 ? ENTER_INPUT : `\x1b[13;${modifier + 1}u`;
+  }
+  if (parts.length === 1 && parts[0] === "ctrl" && key.length === 1) {
+    const code = key.charCodeAt(0);
+    if (code >= 97 && code <= 122) return String.fromCharCode(code - 96);
+  }
+  return undefined;
+}
+
+export class PrefixEditor extends CustomEditor {
+  private prefixActive = false;
+  private prefixTimer: ReturnType<typeof setTimeout> | undefined;
+  // WHY: a stale wrapper inside a rebuilt editor chain must never intercept
+  // keystrokes against a disposed dispatch surface.
+  private disposed = false;
+
+  private readonly appTui: TUI;
+  private readonly keybindingsManager: KeybindingsManager;
+  private readonly inner: WrappedEditor;
+  private readonly options: PrefixEditorOptions;
+
+  constructor(
+    appTui: TUI,
+    theme: EditorTheme,
+    keybindingsManager: KeybindingsManager,
+    inner: WrappedEditor,
+    options: PrefixEditorOptions,
+  ) {
+    super(appTui, theme, keybindingsManager);
+    this.appTui = appTui;
+    this.keybindingsManager = keybindingsManager;
+    this.inner = inner;
+    this.options = options;
+  }
+
+  private syncAppHandlers(): void {
+    if (this.inner.actionHandlers instanceof Map) {
+      this.inner.actionHandlers.clear();
+      for (const [action, handler] of this.actionHandlers) {
+        this.inner.actionHandlers.set(action, handler);
+      }
+    }
+    // WHY: the TUI sets focused only on the outermost component; wrappers
+    // must forward it or inner editors silently change focus behavior.
+    this.inner.focused = this.focused;
+    this.inner.onSubmit = this.onSubmit;
+    this.inner.onChange = this.onChange;
+    this.inner.disableSubmit = this.disableSubmit;
+    this.inner.onEscape = this.onEscape;
+    this.inner.onCtrlD = this.onCtrlD;
+    this.inner.onPasteImage = this.onPasteImage;
+    this.inner.onExtensionShortcut = this.onExtensionShortcut;
+  }
+
+  activate(): void {
+    if (this.disposed) return;
+    this.prefixActive = true;
+    if (this.prefixTimer) clearTimeout(this.prefixTimer);
+    this.prefixTimer = setTimeout(() => this.clearPrefix(), this.options.config.timeoutMs);
+    this.options.setStatus(`prefix ${this.options.config.prefix}`);
+    this.appTui.requestRender();
+  }
+
+  private clearPrefix(): void {
+    const wasActive = this.prefixActive;
+    this.prefixActive = false;
+    if (this.prefixTimer) {
+      clearTimeout(this.prefixTimer);
+      this.prefixTimer = undefined;
+    }
+    this.options.setStatus(undefined);
+    if (wasActive) this.appTui.requestRender();
+  }
+
+  private submitCurrentDraft(): void {
+    if (this.disableSubmit) return;
+    for (const key of this.keybindingsManager.getKeys("tui.input.submit")) {
+      const input = inputForKey(String(key));
+      if (input) {
+        this.syncAppHandlers();
+        this.inner.handleInput(input);
+        return;
+      }
+    }
+  }
+
+  private dispatch(target: PrefixTarget): void {
+    if ("action" in target) {
+      const action = target.action as AppKeybinding;
+      const handler =
+        action === INTERRUPT_ACTION
+          ? (this.onEscape ?? this.actionHandlers.get(action))
+          : action === EXIT_ACTION
+            ? (this.onCtrlD ?? this.actionHandlers.get(action))
+            : action === PASTE_IMAGE_ACTION
+              ? (this.onPasteImage ?? this.actionHandlers.get(action))
+              : this.actionHandlers.get(action);
+      if (handler) {
+        this.syncAppHandlers();
+        handler();
+      } else {
+        this.options.notify(`pi-prefix: action "${target.action}" is unavailable`, "warning");
+      }
+      return;
+    }
+    if ("command" in target) {
+      if (target.submit && this.options.dispatchExtensionCommand(target.command)) {
+        return;
+      }
+      this.setText(target.command);
+      if (target.submit) {
+        this.submitCurrentDraft();
+      }
+      return;
+    }
+    if ("event" in target) {
+      this.options.emitEvent(target.event, target.payload);
+      return;
+    }
+    // WHY: exhaustiveness guard so a future target kind fails compilation.
+    const exhaustive: never = target;
+    return exhaustive;
+  }
+
+  handleInput(data: string): void {
+    // WHY: Pi delivers registered shortcuts through this callback; honoring
+    // it first is what lets native registration activate prefix mode.
+    if (this.onExtensionShortcut?.(data)) {
+      return;
+    }
+    if (this.disposed) {
+      this.syncAppHandlers();
+      this.inner.handleInput(data);
+      return;
+    }
+    if (this.prefixActive) {
+      if (matchesKey(data, CANCEL_KEY)) {
+        this.clearPrefix();
+        return;
+      }
+      for (const [keyId, target] of this.options.config.bindings) {
+        if (matchesKey(data, keyId)) {
+          this.clearPrefix();
+          this.dispatch(target);
+          return;
+        }
+      }
+      this.clearPrefix();
+    }
+    this.syncAppHandlers();
+    this.inner.handleInput(data);
+  }
+
+  /** Mark transparent and release the prefix timer; called on session_shutdown. */
+  dispose(): void {
+    this.disposed = true;
+    this.clearPrefix();
+  }
+
+  render(width: number): string[] {
+    this.inner.borderColor = this.borderColor;
+    this.inner.focused = this.focused;
+    return this.inner.render(width);
+  }
+
+  invalidate(): void {
+    this.inner.invalidate();
+  }
+
+  getText(): string {
+    return this.inner.getText();
+  }
+
+  setText(text: string): void {
+    this.inner.setText(text);
+  }
+
+  addToHistory(text: string): void {
+    this.inner.addToHistory?.(text);
+  }
+
+  insertTextAtCursor(text: string): void {
+    this.inner.insertTextAtCursor?.(text);
+  }
+
+  getExpandedText(): string {
+    return this.inner.getExpandedText?.() ?? this.inner.getText();
+  }
+
+  setAutocompleteProvider(provider: AutocompleteProvider): void {
+    this.inner.setAutocompleteProvider?.(provider);
+  }
+
+  setPaddingX(padding: number): void {
+    this.inner.setPaddingX?.(padding);
+  }
+
+  setAutocompleteMaxVisible(maxVisible: number): void {
+    this.inner.setAutocompleteMaxVisible?.(maxVisible);
+  }
+}