pi-libactions 0.3.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luan Santos
+
+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,195 @@
+# pi-libactions
+
+`pi-libactions` is a UI-free action registry and keybinding loader
+for Pi extensions. It is a library, not a Pi extension: importing it registers
+no commands, shortcuts, tools, or UI, and it is not installed with `pi install`
+on its own. It reaches users as a dependency of the extensions that use it.
+
+The registry lets an extension publish a named action without knowing which
+host will expose it. A shortcut host (currently `pi-xsettings`) reads
+the user's `keybindings.json` and binds each configured key to the matching
+action. Modal features such as `pi-copy-mode` read the same snapshot
+without registering their keys as global editor shortcuts.
+
+## Preview
+
+Actions registered by Side Panel and Side Chat, bound by Xsettings, and listed in Pi's `/hotkeys`. The library itself registers no UI.
+
+![pi-libactions in Bootty](https://github.com/luan/agents/releases/download/v0.3.2/pi-libactions.png)
+
+[Watch the demo](https://github.com/luan/agents/releases/download/v0.3.2/pi-libactions.mp4).
+
+## For users: `keybindings.json`
+
+Actions registered through this library have no default keys. You choose every
+binding in one file in Pi's agent directory:
+
+```text
+<Pi agent directory>/keybindings.json
+```
+
+For a normal local install this is `~/.pi/agent/keybindings.json` (the path is
+`join(getAgentDir(), "keybindings.json")`, so it follows Pi's agent directory).
+
+The file is a JSON object. Each property name is an action ID; each value is a
+single key ID string or an array of key ID strings:
+
+```json
+{
+  "example.open": "ctrl+o",
+  "xsettings.effort.increase": ["alt+."],
+  "codex.context.cycle": "ctrl+shift+w"
+}
+```
+
+A key ID is a base key optionally preceded by modifiers, joined with `+`, for
+example `ctrl+shift+p`. Modifiers are `ctrl`, `shift`, `alt`, and `super`, and
+each may appear once. Accepted base keys are:
+
+- lowercase letters `a`-`z` and digits `0`-`9`
+- punctuation: `` ` `` `-` `=` `[` `]` `\` `;` `'` `,` `.` `/` `!` `@` `#` `$`
+  `%` `^` `&` `*` `(` `)` `_` `+` `|` `~` `{` `}` `:` `<` `>` `?`
+- `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`,
+  `insert`, `clear`, `home`, `end`, `pageUp`, `pageDown`
+- `up`, `down`, `left`, `right`
+- `f1` through `f12`
+
+Rules the loader applies:
+
+- Base keys are case-sensitive (`pageUp`, not `pageup`). Array order is kept.
+- Invalid key IDs inside a value are dropped; the remaining keys are kept. A
+  value that is not a string or array leaves the action with no keys.
+- Collisions between two action IDs bound to the same key are not resolved
+  here; the host decides.
+- Malformed JSON, an unreadable or missing file, or a top-level value that is
+  not an object yields an empty map, so nothing is bound.
+- The file is read on load, not watched. Reload extensions after editing.
+
+Which action IDs exist depends on the extensions you have installed; each
+extension's README lists its IDs. Bindings only take effect when a shortcut
+host is installed: `pi install npm:pi-xsettings` provides one that
+calls `pi.registerShortcut()` for every configured key. Without a host, the
+registry still works but nothing binds global keys.
+
+## For extension authors
+
+### Install and import
+
+Add the library to your package's `dependencies` and `bundledDependencies` so it
+ships inside your published package:
+
+```json
+{
+  "dependencies": {
+    "pi-libactions": "^0.1.0"
+  },
+  "bundledDependencies": ["pi-libactions"]
+}
+```
+
+Then import the public SDK:
+
+```ts
+import { registerAction } from "pi-libactions/sdk";
+```
+
+The package has no runtime dependencies; `@earendil-works/pi-coding-agent` and
+`@earendil-works/pi-tui` are peer dependencies that Pi provides. The root
+export and `/sdk` expose the same symbols: `ACTIONS_PROTOCOL`,
+`ACTIONS_REGISTRY_KEY`, `ensureActionsRegistry`, `registerAction`,
+`loadActionKeybindings`, `isActionKeyId`, and the types `ActionRegistration`,
+`ActionsRegistry`, `ActionKeybindings`.
+
+### Action registry
+
+The registry protocol is `pi-libactions/registry/v1`, stored on `globalThis`
+under `Symbol.for("pi-libactions/registry/v1")`.
+
+An action has this shape:
+
+```ts
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type ActionRegistration = {
+  id: string;
+  description: string;
+  run(ctx: ExtensionContext): void | Promise<void>;
+};
+```
+
+Use a stable, namespaced ID (for example `myext.panel.open`). Register during
+extension setup and keep the disposer for reload and shutdown:
+
+```ts
+import { registerAction } from "pi-libactions/sdk";
+
+const unregister = registerAction({
+  id: "example.open",
+  description: "Open the example panel",
+  async run(ctx) {
+    await openExamplePanel(ctx);
+  },
+});
+
+// Call when the extension is disposed or reloaded.
+unregister();
+```
+
+`registerAction()` uses the process-wide registry returned by
+`ensureActionsRegistry()`. A host that needs to inspect or listen to the
+registry uses the full API:
+
+```ts
+import { ensureActionsRegistry } from "pi-libactions/sdk";
+
+const actions = ensureActionsRegistry();
+const stopListening = actions.onRegister((action) => {
+  console.log(action.id, action.description);
+});
+const action = actions.find("example.open");
+```
+
+Behaviour, as implemented in `src/protocol/actions.ts`:
+
+- The registry exposes `protocol` and `version` (`1`). `register()` and
+  `onRegister()` each return a disposer.
+- `onRegister()` receives registrations made after the listener is attached;
+  it does not replay existing actions. The registry never calls `run()` itself.
+- Registering an existing ID replaces its action. A disposer only removes the
+  exact action instance it registered, so disposing an older registration
+  cannot remove a newer replacement.
+- Listener errors are swallowed so an optional host cannot break registration.
+- `registerAction()` returns a no-op disposer if the global capability cannot
+  be created.
+- Action fields are not validated at runtime; callers must provide the
+  documented shape.
+- Separate copies of this package in the same JavaScript realm find the same
+  registry through `Symbol.for`. `ensureActionsRegistry(scope)` accepts a
+  custom global-like object when an isolated scope is required.
+
+### Reading keybindings from an extension
+
+```ts
+import { loadActionKeybindings, isActionKeyId } from "pi-libactions/sdk";
+
+const bindings = loadActionKeybindings(); // defaults to <agent dir>/keybindings.json
+const keys = bindings["example.open"] ?? []; // readonly KeyId[], frozen
+```
+
+`loadActionKeybindings(path?)` returns `ActionKeybindings`, a frozen
+`Readonly<Record<string, readonly KeyId[]>>` with frozen inner arrays.
+`isActionKeyId(value)` validates one key ID without touching the filesystem.
+
+## Layout
+
+| Responsibility | File |
+| --- | --- |
+| Public SDK re-exports | `src/sdk.ts` (root `src/index.ts` re-exports it) |
+| Action registry protocol and `Symbol.for` capability | `src/protocol/actions.ts` |
+| `keybindings.json` loader and key ID validation | `src/keybindings.ts` |
+
+## Develop
+
+Source: https://github.com/luan/agents, directory
+harnesses/pi/agent/packages/pi-libactions. Run `bun run typecheck` and
+`bun test test` in that directory.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pi-libactions",
+  "version": "0.3.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luan/agents.git",
+    "directory": "harnesses/pi/agent/packages/pi-libactions"
+  },
+  "description": "UI-free action registry capability for Pi extensions",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./sdk": "./src/sdk.ts"
+  },
+  "pi": {
+    "extensions": [],
+    "image": "https://github.com/luan/agents/releases/download/v0.3.2/pi-libactions.png",
+    "video": "https://github.com/luan/agents/releases/download/v0.3.2/pi-libactions.mp4"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
+    "@types/bun": "^1.3.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "test": "bun test --only-failures test"
+  },
+  "bundledDependencies": []
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./sdk.ts";

package/src/keybindings.ts

@@ -0,0 +1,94 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+/** Immutable user keybindings indexed by action ID. */
+export type ActionKeybindings = Readonly<Record<string, readonly KeyId[]>>;
+
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+const BASE_KEYS = new Set([
+	..."abcdefghijklmnopqrstuvwxyz0123456789".split(""),
+	"`",
+	"-",
+	"=",
+	"[",
+	"]",
+	"\\",
+	";",
+	"'",
+	",",
+	".",
+	"/",
+	"!",
+	"@",
+	"#",
+	"$",
+	"%",
+	"^",
+	"&",
+	"*",
+	"(",
+	")",
+	"_",
+	"+",
+	"|",
+	"~",
+	"{",
+	"}",
+	":",
+	"<",
+	">",
+	"?",
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageUp",
+	"pageDown",
+	"up",
+	"down",
+	"left",
+	"right",
+	...Array.from({ length: 12 }, (_unused, index) => `f${index + 1}`),
+]);
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+/** Validate one pi-tui key identifier without registering it. */
+export function isActionKeyId(value: string): value is KeyId {
+	const parts = value.split("+");
+	const base = parts.pop();
+	if (!base || !BASE_KEYS.has(base)) return false;
+	const seen = new Set<string>();
+	return parts.every((part) => MODIFIERS.has(part) && !seen.has(part) && Boolean(seen.add(part)));
+}
+
+/**
+ * Read the user-owned action bindings used by extension action hosts and modal features.
+ * Invalid documents, action values, and key identifiers are omitted.
+ * @param path Optional keybindings file path; defaults to Pi's active agent directory.
+ * @returns A deeply immutable action-to-key snapshot refreshed when extensions reload.
+ */
+export function loadActionKeybindings(path = join(getAgentDir(), "keybindings.json")): ActionKeybindings {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as JsonValue;
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return Object.freeze({});
+		const result: Record<string, readonly KeyId[]> = {};
+		for (const [action, value] of Object.entries(parsed)) {
+			const keys = typeof value === "string" ? [value] : Array.isArray(value) ? value : [];
+			result[action] = Object.freeze(keys.filter((key): key is KeyId => typeof key === "string" && isActionKeyId(key)));
+		}
+		return Object.freeze(result);
+	} catch {
+		return Object.freeze({});
+	}
+}

package/src/protocol/actions.ts

@@ -0,0 +1,123 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const ACTIONS_REGISTRY_KEY = Symbol.for("pi-libactions/registry/v1");
+export const ACTIONS_PROTOCOL = "pi-libactions/registry/v1" as const;
+
+export interface ActionRegistration {
+	id: string;
+	description: string;
+	run(ctx: ExtensionContext): void | Promise<void>;
+}
+
+export interface ActionsRegistry {
+	readonly protocol: typeof ACTIONS_PROTOCOL;
+	readonly version: 1;
+	register(action: ActionRegistration): () => void;
+	onRegister(listener: (action: ActionRegistration) => void): () => void;
+	find(id: string): ActionRegistration | undefined;
+}
+
+type RegistryState = {
+	actions: Map<string, ActionRegistration>;
+	listeners: Set<(action: ActionRegistration) => void>;
+};
+
+const STATE_KEY = Symbol.for("pi-libactions/registry-state/v1");
+const states = new WeakMap<ActionsRegistry, RegistryState>();
+
+// type-boundary: Symbol.for capabilities can be populated by another extension realm; this validator narrows the public methods.
+type UntrustedRegistryValue = unknown;
+
+function isRegistry(value: UntrustedRegistryValue): value is ActionsRegistry {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<ActionsRegistry>;
+	return (
+		candidate.protocol === ACTIONS_PROTOCOL &&
+		candidate.version === 1 &&
+		typeof candidate.register === "function" &&
+		typeof candidate.onRegister === "function" &&
+		typeof candidate.find === "function"
+	);
+}
+
+function stateFor(registry: ActionsRegistry): RegistryState {
+	const existing = states.get(registry);
+	if (existing) return existing;
+	const shared = Reflect.get(registry as object, STATE_KEY) as UntrustedRegistryValue;
+	if (isState(shared)) {
+		states.set(registry, shared);
+		return shared;
+	}
+	const state: RegistryState = { actions: new Map(), listeners: new Set() };
+	Object.defineProperty(registry, STATE_KEY, { value: state, enumerable: false, configurable: false });
+	states.set(registry, state);
+	return state;
+}
+
+function isState(value: UntrustedRegistryValue): value is RegistryState {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as Partial<RegistryState>;
+	return isMap(candidate.actions) && isSet(candidate.listeners);
+}
+
+function isMap(value: UntrustedRegistryValue): value is Map<never, never> {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as {
+		get?: UntrustedRegistryValue;
+		set?: UntrustedRegistryValue;
+		delete?: UntrustedRegistryValue;
+	};
+	return (
+		typeof candidate.get === "function" && typeof candidate.set === "function" && typeof candidate.delete === "function"
+	);
+}
+
+function isSet(value: UntrustedRegistryValue): value is Set<never> {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value as { add?: UntrustedRegistryValue; delete?: UntrustedRegistryValue };
+	return typeof candidate.add === "function" && typeof candidate.delete === "function";
+}
+
+export function ensureActionsRegistry(scope: typeof globalThis = globalThis): ActionsRegistry {
+	const slots = scope as Record<PropertyKey, UntrustedRegistryValue>;
+	const existing = slots[ACTIONS_REGISTRY_KEY];
+	if (isRegistry(existing)) return existing;
+
+	const registry: ActionsRegistry = {
+		protocol: ACTIONS_PROTOCOL,
+		version: 1,
+		register(action) {
+			const state = stateFor(registry);
+			state.actions.set(action.id, action);
+			for (const listener of [...state.listeners]) {
+				try {
+					listener(action);
+				} catch {
+					// Optional action consumers must not affect registration.
+				}
+			}
+			return () => {
+				if (state.actions.get(action.id) === action) state.actions.delete(action.id);
+			};
+		},
+		onRegister(listener) {
+			const state = stateFor(registry);
+			state.listeners.add(listener);
+			return () => state.listeners.delete(listener);
+		},
+		find(id) {
+			return stateFor(registry).actions.get(id);
+		},
+	};
+	stateFor(registry);
+	slots[ACTIONS_REGISTRY_KEY] = registry;
+	return registry;
+}
+
+export function registerAction(action: ActionRegistration): () => void {
+	try {
+		return ensureActionsRegistry().register(action);
+	} catch {
+		return () => {};
+	}
+}

package/src/sdk.ts

@@ -0,0 +1,9 @@
+export {
+	ensureActionsRegistry,
+	registerAction,
+	ACTIONS_PROTOCOL,
+	ACTIONS_REGISTRY_KEY,
+	type ActionRegistration,
+	type ActionsRegistry,
+} from "./protocol/actions.ts";
+export { isActionKeyId, loadActionKeybindings, type ActionKeybindings } from "./keybindings.ts";

package/test/registry.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ensureActionsRegistry, loadActionKeybindings } from "../src/sdk.ts";
+
+describe("pi-libactions registry", () => {
+	test("supports consumer-first registration and identity-safe disposal", () => {
+		const scope = Object.create(null) as typeof globalThis;
+		const registry = ensureActionsRegistry(scope);
+		const action = { id: "test.action", description: "Test", run: () => {} };
+		const remove = registry.register(action);
+		expect(registry.find(action.id)).toBe(action);
+		remove();
+		expect(registry.find(action.id)).toBeUndefined();
+	});
+
+	test("isolates listener failures", () => {
+		const scope = Object.create(null) as typeof globalThis;
+		const registry = ensureActionsRegistry(scope);
+		registry.onRegister(() => {
+			throw new Error("listener");
+		});
+		expect(() => registry.register({ id: "safe", description: "Safe", run: () => {} })).not.toThrow();
+	});
+
+	test("loads one strict immutable user keybinding snapshot", () => {
+		const directory = mkdtempSync(join(tmpdir(), "pi-libactions-"));
+		const path = join(directory, "keybindings.json");
+		writeFileSync(path, JSON.stringify({ action: ["ctrl+c", "bad+key"], single: "space", invalid: 42 }));
+		const bindings = loadActionKeybindings(path);
+		expect(bindings).toEqual({ action: ["ctrl+c"], single: ["space"], invalid: [] });
+		expect(Object.isFrozen(bindings)).toBe(true);
+		expect(Object.isFrozen(bindings.action)).toBe(true);
+	});
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "incremental": true,
+    "tsBuildInfoFile": "../../../../../target/tsbuildinfo/pi-libactions.tsbuildinfo",
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["src", "test"]
+}