@adeildo/pi-kit 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Adeildo
+
+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,84 @@
+# @adeildo/pi-kit
+
+What every pi-harness package is built on. It's a library, not a Pi package, so installing it adds nothing to Pi.
+
+## An app, and features in it
+
+```ts
+import { createApp, defineFeature, matching, setting } from "@adeildo/pi-kit";
+
+export const version = setting({
+	id: "subscription.claudeCodeVersion",
+	default: "2.1.280",
+	decoder: matching(/^\d+\.\d+\.\d+$/, "a version like 2.1.280"),
+});
+
+export const subscription = defineFeature({
+	id: "subscription",
+	description: "Bill Anthropic OAuth requests to the Claude plan",
+	settings: [version],
+	setup(scope) {
+		scope.on("before_provider_headers", (event) => {
+			event.headers["user-agent"] = `claude-cli/${version.get(scope)}`;
+		});
+	},
+});
+
+export default function (pi: ExtensionAPI): void {
+	createApp(pi, { name: "pi-providers" }).use(subscription).build();
+}
+```
+
+A package is one app. The harness will be one app with every feature in it, and Pi loads it as a single extension.
+
+## What a feature gets
+
+`setup` receives the feature's scope. It extends `ExtensionAPI`, so it has every pi method, with two of them wired to the feature:
+
+|                         |                                                                                                                                                                                                          |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scope.on`              | `pi.on`, but an error comes out as `pi-harness: permission: tool_call: boom` instead of just the extension's name. It's still thrown, because a `tool_call` handler that throws is how pi blocks a tool. |
+| `scope.registerCommand` | `pi.registerCommand`. If another feature in the same app already took the name, this one is skipped with a warning.                                                                                      |
+| `scope.onSessionStart`  | Runs once the session's settings are loaded. Anything that lasts, like a watcher, a server or a child process, starts here and never in `setup`.                                                         |
+| `scope.onShutdown`      | Runs once per session, newest first, even when pi fires `session_shutdown` twice.                                                                                                                        |
+| `scope.warn`            | Shows a notification when there's a UI and writes to stderr when there isn't. Messages sent before a session starts are held until it does.                                                              |
+| everything else         | The scope **is** the extension API, so `scope.registerTool`, `scope.appendEntry`, `scope.events` and the rest work as they always did.                                                                   |
+
+A feature whose `setup` throws turns into a warning, and the other features still mount. If the same feature runs in two apps of one Pi process, say the harness and a standalone package, the first app runs it and the second one logs who has it.
+
+## Settings
+
+Every app reads `~/.pi/agent/extensions/pi-harness/settings.json`. A setting's `id` is its path in that file. A store only reads the settings its own features declared, so keys that belong to other apps never produce a warning.
+
+`store.set` writes one value, and `store.setAll` writes several in one pass, which is what a feature does when it saves a whole config object. A value that already reads the same is not written, so a file holds what was decided and not a copy of every default, which would freeze them.
+
+A setting declared with `project: true` also reads `<project>/.pi/extensions/pi-harness/settings.json`, but only once pi trusts the project, and there the project value wins. Anything without that flag can only be set globally. A project file that tries to set it gets a warning, so a cloned repository can't loosen what runs without asking.
+
+A value that fails to decode is ignored, and the warning names the file and the key.
+
+Every feature also gets `features.<id>.enabled`, which defaults to on. A feature that's off never runs `setup`, so it registers nothing and costs nothing. The change takes effect on the next `/reload`.
+
+## Events and contracts
+
+```ts
+const accountChanged = defineEvent("providers:account-changed", object({ account: string }));
+
+accountChanged.on(scope, ({ account }) => …);
+accountChanged.emit(scope, { account: "work" });
+```
+
+Events travel over `pi.events` on the channel `harness:<name>`. Two features behave the same whether they share an app or come from different packages. The payload might come from an older or newer version of the other package, so it's decoded when it arrives, and one that doesn't decode is dropped with a warning.
+
+These rules hold for every event that crosses packages:
+
+- It's declared in `contracts/` in this package, never in the package that emits it. That way the listener doesn't depend on the emitter, and either one works without the other.
+- The payload is plain JSON, with no functions, classes or `Date`. A remote control or a web UI can then forward any contract without knowing what's inside.
+- A payload can gain fields but never lose them.
+
+## Testing
+
+`@adeildo/pi-kit/testing` has `fakePi()` and `fakeContext()`. Two fakes built on one `createEventBus()` behave like two extensions in the same Pi process. `fire` runs the handlers in order and returns what each one returned.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@adeildo/pi-kit",
+	"version": "4.0.0",
+	"description": "The app builder, settings and events that pi-harness packages are built on.",
+	"license": "MIT",
+	"author": {
+		"name": "Felipe Adeildo",
+		"email": "contato@felipeadeildo.com",
+		"url": "https://github.com/felipeadeildo"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/felipeadeildo/pi-harness.git",
+		"directory": "packages/kit"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./testing": "./src/testing.ts"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	}
+}

package/src/app/attribution.ts

@@ -0,0 +1,31 @@
+// In the harness every feature runs inside one extension, so pi reports every failure under the
+// same name. These put the app and the feature in front of it instead.
+
+export function describe(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+// A sync function stays sync, because pi treats some handler results differently when they are
+// promises.
+export function attributed<A extends unknown[], R>(
+	label: string,
+	run: (...args: A) => R,
+): (...args: A) => R {
+	return (...args: A): R => {
+		let result: R;
+		try {
+			result = run(...args);
+		} catch (error) {
+			throw relabel(label, error);
+		}
+		if (!(result instanceof Promise)) return result;
+		// Still the same kind of promise, only rejected with the relabeled error.
+		return result.catch((error: unknown) => {
+			throw relabel(label, error);
+		}) as R;
+	};
+}
+
+function relabel(label: string, error: unknown): Error {
+	return new Error(`${label}: ${describe(error)}`, { cause: error });
+}

package/src/app/builder.ts

@@ -0,0 +1,161 @@
+// The app builder. A package's extension is `createApp(pi, …).use(feature).build()`, and the
+// harness is the same call with every feature. The builder is where the rules from pi's extension
+// docs live: registration only in the factory, session work from `session_start`, cleanup once per
+// session, and a feature that fails to set up becomes a warning.
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { boolean } from "../decode.ts";
+import { globalSettingsPath, projectSettingsPath } from "../settings/files.ts";
+import { type Setting, type SettingsScope, setting } from "../settings/setting.ts";
+import { SettingsStore } from "../settings/store.ts";
+import { describe } from "./attribution.ts";
+import { answerClaims, ownerOf } from "./claim.ts";
+import type { Feature } from "./feature.ts";
+import { type AppState, createScope, type Hook } from "./scope.ts";
+
+export interface App extends SettingsScope {
+	/** Shown in front of every warning, like `pi-harness` or `pi-providers`. */
+	readonly name: string;
+	readonly settings: SettingsStore;
+	/** True when this app runs a feature with that id. */
+	has(featureId: string): boolean;
+}
+
+export interface AppOptions {
+	name: string;
+	settingsPath?: string;
+}
+
+export interface AppBuilder {
+	use(feature: Feature): AppBuilder;
+	build(): App;
+}
+
+export function createApp(pi: ExtensionAPI, options: AppOptions): AppBuilder {
+	const features: Feature[] = [];
+	const builder: AppBuilder = {
+		use(feature) {
+			features.push(feature);
+			return builder;
+		},
+		build: () => mount(pi, options, features),
+	};
+	return builder;
+}
+
+export function enabledSetting(feature: Feature): Setting<boolean> {
+	return setting({
+		id: `features.${feature.id}.enabled`,
+		default: true,
+		decoder: boolean,
+		ui: { group: "Features", label: feature.id, description: feature.description },
+	});
+}
+
+function mount(pi: ExtensionAPI, options: AppOptions, features: readonly Feature[]): App {
+	const settings = new SettingsStore(options.settingsPath ?? globalSettingsPath());
+	const mounted = new Set<string>();
+	const queued: string[] = [];
+	let session: ExtensionContext | undefined;
+	let live = true;
+
+	function deliver(line: string): void {
+		if (session === undefined) queued.push(line);
+		else if (session.hasUI) session.ui.notify(line, "warning");
+		else console.error(line);
+	}
+
+	const state: AppState = {
+		name: options.name,
+		pi,
+		settings,
+		mounted,
+		commands: new Map(),
+		starts: [],
+		shutdowns: [],
+		report: (source, message) => deliver(`${options.name}: ${source}: ${message}`),
+	};
+	const app: App = { name: options.name, settings, has: (id) => mounted.has(id) };
+
+	answerClaims(pi, options.name, mounted, () => live);
+
+	// Registered first, so these run ahead of the features' own handlers.
+	pi.on("session_start", async (_event, ctx) => {
+		live = true;
+		session = ctx;
+		for (const line of queued.splice(0)) deliver(line);
+		const project = ctx.isProjectTrusted() ? projectSettingsPath(ctx.cwd) : undefined;
+		for (const line of settings.load(project)) state.report("settings", line);
+		await runInOrder(
+			state.starts,
+			(run) => run(ctx),
+			(source, error) => {
+				state.report(source, `failed to start the session: ${describe(error)}`);
+			},
+		);
+	});
+
+	pi.on("session_shutdown", async () => {
+		if (!live) return;
+		live = false;
+		await runInOrder(
+			state.shutdowns.toReversed(),
+			(run) => run(),
+			(source, error) => {
+				state.report(source, `failed to shut down: ${describe(error)}`);
+			},
+		);
+		session = undefined;
+	});
+
+	// All the switches first: one read of the file decides what is on, and a feature that is off
+	// still shows up on the settings screen.
+	const candidates: { feature: Feature; enabled: Setting<boolean> }[] = [];
+	for (const feature of features) {
+		if (candidates.some((candidate) => candidate.feature.id === feature.id)) {
+			state.report(feature.id, "was added to this app twice; keeping the first");
+			continue;
+		}
+		const enabled = enabledSetting(feature);
+		try {
+			settings.register([enabled, ...(feature.settings ?? [])]);
+			candidates.push({ feature, enabled });
+		} catch (error) {
+			state.report(feature.id, `failed to set up: ${describe(error)}`);
+		}
+	}
+
+	for (const { feature, enabled } of candidates) {
+		if (!enabled.get(app)) continue;
+
+		const owner = ownerOf(pi, feature.id);
+		if (owner !== undefined) {
+			state.report(feature.id, `already loaded by ${owner}, so this copy stays off`);
+			continue;
+		}
+
+		try {
+			feature.setup(createScope(state, feature.id));
+			mounted.add(feature.id);
+		} catch (error) {
+			state.report(feature.id, `failed to set up: ${describe(error)}`);
+		}
+	}
+
+	return app;
+}
+
+async function runInOrder<T>(
+	hooks: readonly Hook<T>[],
+	call: (run: T) => void | Promise<void>,
+	failed: (source: string, error: unknown) => void,
+): Promise<void> {
+	for (const hook of hooks) {
+		try {
+			// oxlint-disable-next-line no-await-in-loop -- the order is the point
+			await call(hook.run);
+		} catch (error) {
+			failed(hook.source, error);
+		}
+	}
+}

package/src/app/claim.ts

@@ -0,0 +1,29 @@
+// Before mounting a feature, an app asks the other apps on pi.events whether one already runs it,
+// which is how the harness and a standalone copy of the same package avoid running it twice. The
+// answer is a field written on the payload, which works because pi's bus is synchronous. An app
+// answers only while it is live, and pi fires `session_shutdown` before a reload builds the next.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { isObject, object, string } from "../decode.ts";
+
+const CHANNEL = "harness:kit:claim";
+const claimShape = object({ feature: string });
+
+export function answerClaims(
+	pi: ExtensionAPI,
+	appName: string,
+	mounted: ReadonlySet<string>,
+	isLive: () => boolean,
+): void {
+	pi.events.on(CHANNEL, (data) => {
+		const claim = claimShape.decode(data, "");
+		if (!isLive() || !claim.ok || !isObject(data) || data.owner !== undefined) return;
+		if (mounted.has(claim.value.feature)) data.owner = appName;
+	});
+}
+
+export function ownerOf(pi: ExtensionAPI, featureId: string): string | undefined {
+	const claim: { feature: string; owner?: unknown } = { feature: featureId };
+	pi.events.emit(CHANNEL, claim);
+	return typeof claim.owner === "string" ? claim.owner : undefined;
+}

package/src/app/feature.ts

@@ -0,0 +1,44 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	RegisteredCommand,
+} from "@earendil-works/pi-coding-agent";
+
+import type { Setting, SettingsScope } from "../settings/setting.ts";
+import type { SettingsStore } from "../settings/store.ts";
+
+export type SessionHook = (ctx: ExtensionContext) => void | Promise<void>;
+export type ShutdownHook = () => void | Promise<void>;
+export type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+
+export interface Feature {
+	/** Unique across every package, like `subscription`. It names the feature's settings too. */
+	id: string;
+	/** One line for the settings screen. */
+	description: string;
+	settings?: readonly Setting<unknown>[];
+	/** Registers handlers, commands and providers. Starts nothing: that goes in `onSessionStart`. */
+	setup(scope: FeatureScope): void;
+}
+
+/**
+ * What a feature gets in `setup`: the extension API, with `on` and `registerCommand` wired to this
+ * feature, plus the app's services. It extends `ExtensionAPI` on purpose. Reading a method through
+ * another type collapses pi's per-event overloads, and extending an interface keeps them.
+ */
+export interface FeatureScope extends ExtensionAPI, SettingsScope {
+	readonly id: string;
+	readonly settings: SettingsStore;
+	/** Runs when a session starts, after the settings are loaded for it. */
+	onSessionStart(hook: SessionHook): void;
+	/** Runs once per session, newest first. */
+	onShutdown(hook: ShutdownHook): void;
+	/** Shown as `<app>: <feature>: <message>`. */
+	warn(message: string): void;
+	/** True when this app runs a feature with that id. */
+	has(featureId: string): boolean;
+}
+
+export function defineFeature(feature: Feature): Feature {
+	return feature;
+}

package/src/app/scope.ts

@@ -0,0 +1,63 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { SettingsStore } from "../settings/store.ts";
+import { attributed } from "./attribution.ts";
+import type { FeatureScope, SessionHook, ShutdownHook } from "./feature.ts";
+
+export interface Hook<T> {
+	/** The feature that registered it, named when it fails. */
+	source: string;
+	run: T;
+}
+
+/** The parts of an app a feature scope reads and writes. */
+export interface AppState {
+	name: string;
+	pi: ExtensionAPI;
+	settings: SettingsStore;
+	mounted: ReadonlySet<string>;
+	/** Command name to the feature that registered it. */
+	commands: Map<string, string>;
+	starts: Hook<SessionHook>[];
+	shutdowns: Hook<ShutdownHook>[];
+	report(source: string, message: string): void;
+}
+
+export function createScope(state: AppState, featureId: string): FeatureScope {
+	const label = `${state.name}: ${featureId}`;
+
+	return {
+		...state.pi,
+		id: featureId,
+		settings: state.settings,
+		on: attributedOn(state.pi, label),
+		registerCommand(name, options) {
+			const owner = state.commands.get(name);
+			if (owner !== undefined) {
+				state.report(featureId, `/${name} is already registered by ${owner}; skipped`);
+				return;
+			}
+			state.commands.set(name, featureId);
+			state.pi.registerCommand(name, {
+				...options,
+				handler: attributed(`${label}: /${name}`, options.handler),
+			});
+		},
+		onSessionStart: (run) => state.starts.push({ source: featureId, run }),
+		onShutdown: (run) => state.shutdowns.push({ source: featureId, run }),
+		warn: (message) => state.report(featureId, message),
+		has: (id) => state.mounted.has(id),
+	} as FeatureScope;
+}
+
+type UntypedHandler = (...args: unknown[]) => unknown;
+type UntypedOn = (event: string, handler: UntypedHandler) => () => void;
+
+// pi.on has one overload per event and TypeScript cannot implement an overloaded signature
+// generically, so this is the one place that casts. Callers keep the exact overload types.
+function attributedOn(pi: ExtensionAPI, label: string): ExtensionAPI["on"] {
+	const on = pi.on.bind(pi) as unknown as UntypedOn;
+	const wrapped: UntypedOn = (event, handler) =>
+		on(event, attributed(`${label}: ${event}`, handler));
+	return wrapped as unknown as ExtensionAPI["on"];
+}

package/src/decode.ts

@@ -0,0 +1,187 @@
+// Decoders for everything that comes from outside: settings files and event payloads from other
+// packages. The only module that inspects `typeof`, and no decoder throws.
+export interface Problem {
+	path: string;
+	message: string;
+}
+
+export type Decoded<T> =
+	| { ok: true; value: T; problems: Problem[] }
+	| { ok: false; problems: Problem[] };
+
+export interface Decoder<T> {
+	decode(input: unknown, path: string): Decoded<T>;
+}
+
+export function pass<T>(value: T, problems: Problem[] = []): Decoded<T> {
+	return { ok: true, value, problems };
+}
+
+export function fail<T>(entry: Problem): Decoded<T> {
+	return { ok: false, problems: [entry] };
+}
+
+export function problem(path: string, message: string): Problem {
+	return { path, message };
+}
+
+export function fieldPath(path: string, key: string): string {
+	return path === "" ? key : `${path}.${key}`;
+}
+
+export function formatProblems(problems: Problem[]): string[] {
+	return problems.map((entry) => `${entry.path}: ${entry.message}`);
+}
+
+export function isObject(input: unknown): input is Record<string, unknown> {
+	return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+
+export const string: Decoder<string> = {
+	decode(input, path) {
+		return typeof input === "string" ? pass(input) : fail(problem(path, "expected a string"));
+	},
+};
+
+export const trimmedString: Decoder<string> = {
+	decode(input, path) {
+		if (typeof input !== "string" || input.trim() === "")
+			return fail(problem(path, "expected a non-empty string"));
+		return pass(input.trim());
+	},
+};
+
+export const boolean: Decoder<boolean> = {
+	decode(input, path) {
+		return typeof input === "boolean" ? pass(input) : fail(problem(path, "expected a boolean"));
+	},
+};
+
+export const unit: Decoder<number> = {
+	decode(input, path) {
+		if (typeof input !== "number" || !Number.isFinite(input) || input < 0 || input > 1)
+			return fail(problem(path, "expected a number from 0 to 1"));
+		return pass(input);
+	},
+};
+
+export const duration: Decoder<number> = {
+	decode(input, path) {
+		if (typeof input !== "number" || !Number.isFinite(input) || input < 0)
+			return fail(problem(path, "expected a non-negative number of milliseconds"));
+		return pass(input);
+	},
+};
+
+/** A whole number from `min` to `max`, inclusive. */
+export function integer(min: number, max: number): Decoder<number> {
+	return {
+		decode(input, path) {
+			if (typeof input !== "number" || !Number.isInteger(input) || input < min || input > max) {
+				return fail(problem(path, `expected a whole number from ${min} to ${max}`));
+			}
+			return pass(input);
+		},
+	};
+}
+
+/** A string that matches `pattern`, described to the user as `expected`. */
+export function matching(pattern: RegExp, expected: string): Decoder<string> {
+	return {
+		decode(input, path) {
+			if (typeof input === "string" && pattern.test(input)) return pass(input);
+			return fail(problem(path, `expected ${expected}`));
+		},
+	};
+}
+
+export function literal<const T extends readonly string[]>(...values: T): Decoder<T[number]> {
+	const expected = values.map((value) => `"${value}"`).join(" or ");
+	return {
+		decode(input, path) {
+			if (typeof input === "string" && (values as readonly string[]).includes(input))
+				return pass(input as T[number]);
+			return fail(problem(path, `expected ${expected}`));
+		},
+	};
+}
+
+export function nullable<T>(inner: Decoder<T>): Decoder<T | null> {
+	return {
+		decode(input, path) {
+			return input === null ? pass(null) : inner.decode(input, path);
+		},
+	};
+}
+
+export function withDefaultOf<T>(inner: Decoder<T>, fallback: () => T): Decoder<T> {
+	return {
+		decode(input, path) {
+			if (input === undefined) return pass(fallback());
+			const result = inner.decode(input, path);
+			return result.ok ? result : pass(fallback(), result.problems);
+		},
+	};
+}
+
+export function withDefault<T>(inner: Decoder<T>, fallback: T): Decoder<T> {
+	return withDefaultOf(inner, () => fallback);
+}
+
+export function stringList(expected: string): Decoder<string[]> {
+	const notAList = `expected an array of ${expected}`;
+	const dropped = "ignored entries that are not non-empty strings";
+
+	return {
+		decode(input, path) {
+			if (!Array.isArray(input)) return fail(problem(path, notAList));
+
+			const value: string[] = [];
+			let missing = 0;
+			for (const entry of input) {
+				if (typeof entry === "string" && entry !== "") value.push(entry);
+				else missing++;
+			}
+
+			const problems = missing > 0 ? [problem(path, dropped)] : [];
+			return pass(value, problems);
+		},
+	};
+}
+
+export function stringListOrEmpty(
+	fallback: readonly string[],
+	expected: string,
+): Decoder<string[]> {
+	const parse = stringList(expected);
+	return {
+		decode(input, path) {
+			if (input === undefined) return pass([...fallback]);
+			const result = parse.decode(input, path);
+			return result.ok ? result : pass([], result.problems);
+		},
+	};
+}
+
+export function object<T extends Record<string, unknown>>(shape: {
+	[K in keyof T]: Decoder<T[K]>;
+}): Decoder<T> {
+	return {
+		decode(input, path) {
+			if (!isObject(input)) return fail(problem(path, "expected an object"));
+
+			const problems: Problem[] = [];
+			const value = {} as T;
+			let complete = true;
+
+			for (const key of Object.keys(shape) as (keyof T & string)[]) {
+				const result = shape[key].decode(input[key], fieldPath(path, key));
+				problems.push(...result.problems);
+				if (result.ok) value[key] = result.value;
+				else complete = false;
+			}
+
+			return complete ? pass(value, problems) : { ok: false, problems };
+		},
+	};
+}

package/src/events.ts

@@ -0,0 +1,40 @@
+// How features talk to each other, over pi.events, which every extension in a process shares. A
+// payload is decoded on arrival, because it may come from another version of the other package.
+//
+// An event that crosses packages is declared in `contracts/`, never in the package that emits it,
+// so the listener does not depend on the emitter.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { type Decoder, formatProblems } from "./decode.ts";
+
+/** What an event needs to travel. A feature scope is one. */
+export interface EventScope {
+	readonly events: ExtensionAPI["events"];
+	warn(message: string): void;
+}
+
+export interface HarnessEvent<T> {
+	/** The pi.events channel: `harness:` and the name. */
+	readonly channel: string;
+	emit(scope: EventScope, payload: T): void;
+	/** A payload that does not decode is dropped with a warning. */
+	on(scope: EventScope, listener: (payload: T) => void): () => void;
+}
+
+/** Name it `<area>:<what happened>`, like `providers:account-changed`. */
+export function defineEvent<T>(name: string, decoder: Decoder<T>): HarnessEvent<T> {
+	const channel = `harness:${name}`;
+	return {
+		channel,
+		emit(scope, payload) {
+			scope.events.emit(channel, payload);
+		},
+		on(scope, listener) {
+			return scope.events.on(channel, (data) => {
+				const result = decoder.decode(data, name);
+				if (result.ok) listener(result.value);
+				else scope.warn(`ignored a ${name} event: ${formatProblems(result.problems).join("; ")}`);
+			});
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./app/builder.ts";
+export * from "./app/feature.ts";
+export * from "./decode.ts";
+export * from "./events.ts";
+export { globalSettingsPath, projectSettingsPath } from "./settings/files.ts";
+export * from "./settings/setting.ts";
+export * from "./settings/store.ts";

package/src/settings/files.ts

@@ -0,0 +1,70 @@
+// Where the settings files live and how they are read and written. Every app shares them, so a
+// write keeps every key it does not know.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { isObject } from "../decode.ts";
+
+export type SettingsData = Record<string, unknown>;
+
+export interface SettingsFile {
+	data: SettingsData;
+	warnings: string[];
+}
+
+export function globalSettingsPath(): string {
+	return join(getAgentDir(), "extensions", "pi-harness", "settings.json");
+}
+
+export function projectSettingsPath(cwd: string): string {
+	return join(cwd, CONFIG_DIR_NAME, "extensions", "pi-harness", "settings.json");
+}
+
+export function readSettingsFile(path: string): SettingsFile {
+	if (!existsSync(path)) return { data: {}, warnings: [] };
+	try {
+		const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+		if (isObject(data)) return { data, warnings: [] };
+		return { data: {}, warnings: [`${path}: must contain a JSON object; using the defaults`] };
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return { data: {}, warnings: [`${path}: could not be read (${reason}); using the defaults`] };
+	}
+}
+
+export function writeSettingsFile(path: string, data: SettingsData): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, `${JSON.stringify(data, null, "\t")}\n`, "utf8");
+	renameSync(temporary, path);
+}
+
+export function lookup(data: SettingsData, id: string): unknown {
+	let node: unknown = data;
+	for (const key of id.split(".")) {
+		if (!isObject(node)) return undefined;
+		node = node[key];
+	}
+	return node;
+}
+
+export function assign(data: SettingsData, id: string, value: unknown): void {
+	const keys = id.split(".");
+	const last = keys.pop();
+	if (last === undefined) return;
+
+	let node = data;
+	for (const key of keys) {
+		const next = node[key];
+		if (isObject(next)) {
+			node = next;
+			continue;
+		}
+		const created: SettingsData = {};
+		node[key] = created;
+		node = created;
+	}
+	node[last] = value;
+}

package/src/settings/setting.ts

@@ -0,0 +1,39 @@
+// A setting is declared next to the feature that reads it. The declaration is plain data plus two
+// helpers, so one handle works against any app.
+import type { Decoder } from "../decode.ts";
+import type { SettingsStore } from "./store.ts";
+
+/** How a setting shows up on a settings screen. */
+export interface SettingUi {
+	group: string;
+	label: string;
+	description: string;
+}
+
+export interface SettingDefinition<T> {
+	/** Dotted path in the settings file, like `subscription.claudeCodeVersion`. */
+	id: string;
+	default: T;
+	decoder: Decoder<T>;
+	/** Accept a value from the project's settings file, once pi trusts the project. */
+	project?: boolean;
+	ui?: SettingUi;
+}
+
+export interface SettingsScope {
+	readonly settings: SettingsStore;
+}
+
+export interface Setting<T> extends SettingDefinition<T> {
+	get(scope: SettingsScope): T;
+	listen(scope: SettingsScope, listener: (value: T) => void): () => void;
+}
+
+export function setting<T>(definition: SettingDefinition<T>): Setting<T> {
+	const handle: Setting<T> = {
+		...definition,
+		get: (scope) => scope.settings.get(handle),
+		listen: (scope, listener) => scope.settings.listen(handle, listener),
+	};
+	return handle;
+}

package/src/settings/store.ts

@@ -0,0 +1,129 @@
+// One store per app, reading only the settings its own features declared. A value comes from the
+// first layer with a valid one: project (for settings that accept it, in a trusted project),
+// global, default.
+import { formatProblems } from "../decode.ts";
+import { assign, lookup, readSettingsFile, type SettingsData, writeSettingsFile } from "./files.ts";
+import type { Setting } from "./setting.ts";
+
+type Found<T> = { found: true; value: T } | { found: false };
+
+export class SettingsStore {
+	readonly globalPath: string;
+	#projectPath: string | undefined;
+	#known = new Map<string, Setting<unknown>>();
+	#values = new Map<string, unknown>();
+	#listeners = new Map<string, Set<(value: unknown) => void>>();
+	#loaded = false;
+
+	constructor(globalPath: string) {
+		this.globalPath = globalPath;
+	}
+
+	register(settings: readonly Setting<unknown>[]): void {
+		for (const entry of settings) {
+			const known = this.#known.get(entry.id);
+			if (known !== undefined && known !== entry)
+				throw new Error(`two settings are named "${entry.id}"`);
+			this.#known.set(entry.id, entry);
+		}
+		this.#loaded = false;
+	}
+
+	get<T>(entry: Setting<T>): T {
+		if (!this.#loaded) this.load(this.#projectPath);
+		// Only `load` writes to #values, and always with a value this setting's decoder produced.
+		return this.#values.has(entry.id) ? (this.#values.get(entry.id) as T) : entry.default;
+	}
+
+	listen<T>(entry: Setting<T>, listener: (value: T) => void): () => void {
+		const listeners = this.#listeners.get(entry.id) ?? new Set();
+		this.#listeners.set(entry.id, listeners);
+		// Same reasoning as `get`: every value handed to a listener came from this setting's decoder.
+		const untyped = listener as (value: unknown) => void;
+		listeners.add(untyped);
+		return () => listeners.delete(untyped);
+	}
+
+	/** Reads the files again. Pass the project file only when pi trusts the project. */
+	load(projectPath?: string): string[] {
+		this.#loaded = true;
+		this.#projectPath = projectPath;
+		const global = readSettingsFile(this.globalPath);
+		const project = projectPath === undefined ? undefined : readSettingsFile(projectPath);
+		const warnings = [...global.warnings, ...(project?.warnings ?? [])];
+
+		for (const entry of this.#known.values()) {
+			let value = entry.default;
+
+			const fromGlobal = decodeAt(entry, global.data, this.globalPath, warnings);
+			if (fromGlobal.found) value = fromGlobal.value;
+
+			if (project !== undefined && projectPath !== undefined) {
+				if (entry.project) {
+					const fromProject = decodeAt(entry, project.data, projectPath, warnings);
+					if (fromProject.found) value = fromProject.value;
+				} else if (lookup(project.data, entry.id) !== undefined) {
+					warnings.push(
+						`${projectPath}: ${entry.id}: only the global settings file can set this; ignored`,
+					);
+				}
+			}
+
+			this.#update(entry, value);
+		}
+
+		return warnings;
+	}
+
+	/** Writes one value to the global file, keeping the rest. Returns an error message on failure. */
+	set<T>(entry: Setting<T>, value: T): string | undefined {
+		return this.setAll([[entry, value]]);
+	}
+
+	/**
+	 * Writes several values in one pass, keeping the rest of the file. A value that already reads the
+	 * same is not written, so the file ends up holding what was decided and not a copy of every
+	 * default, which would freeze them.
+	 */
+	setAll(entries: readonly (readonly [Setting<unknown>, unknown])[]): string | undefined {
+		const changed = entries.filter(([entry, value]) => !same(this.get(entry), value));
+		if (changed.length === 0) return undefined;
+
+		const { data } = readSettingsFile(this.globalPath);
+		for (const [entry, value] of changed) assign(data, entry.id, value);
+		try {
+			writeSettingsFile(this.globalPath, data);
+		} catch (error) {
+			return error instanceof Error ? error.message : String(error);
+		}
+		this.load(this.#projectPath);
+		return undefined;
+	}
+
+	#update(entry: Setting<unknown>, value: unknown): void {
+		const previous = this.#values.has(entry.id) ? this.#values.get(entry.id) : entry.default;
+		this.#values.set(entry.id, value);
+		if (same(previous, value)) return;
+		for (const listener of this.#listeners.get(entry.id) ?? []) listener(value);
+	}
+}
+
+function decodeAt<T>(
+	entry: Setting<T>,
+	data: SettingsData,
+	path: string,
+	warnings: string[],
+): Found<T> {
+	const input = lookup(data, entry.id);
+	if (input === undefined) return { found: false };
+
+	const result = entry.decoder.decode(input, entry.id);
+	const suffix = result.ok ? "" : "; ignored";
+	for (const line of formatProblems(result.problems)) warnings.push(`${path}: ${line}${suffix}`);
+	return result.ok ? { found: true, value: result.value } : { found: false };
+}
+
+/** Decoders build new arrays and objects on every read, so two values are compared by content. */
+function same(left: unknown, right: unknown): boolean {
+	return JSON.stringify(left) === JSON.stringify(right);
+}

package/src/testing.ts

@@ -0,0 +1,128 @@
+// Fakes for testing features without a running pi. Two fakes on one bus behave like two extensions
+// in the same pi process.
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+	createEventBus,
+	type EntryRenderer,
+	type EventBus,
+	type ExtensionAPI,
+	type ExtensionContext,
+	type RegisteredCommand,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+import type { FeatureScope } from "./app/feature.ts";
+import { SettingsStore } from "./settings/store.ts";
+
+export type FakeHandler = (event: unknown, ctx: ExtensionContext) => unknown;
+type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+
+export interface FakePi {
+	pi: ExtensionAPI;
+	handlers: Map<string, FakeHandler[]>;
+	commands: Map<string, CommandOptions>;
+	shortcuts: string[];
+	tools: ToolDefinition[];
+	providers: { name: string; config: unknown }[];
+	renderers: Map<string, EntryRenderer>;
+	entries: { customType: string; data: unknown }[];
+	messages: unknown[];
+	/** Runs every handler registered for `name`, in order, and returns what each returned. */
+	fire(name: string, event: unknown, ctx: ExtensionContext): Promise<unknown[]>;
+	count(name: string): number;
+}
+
+export function fakePi(bus: EventBus = createEventBus()): FakePi {
+	const handlers = new Map<string, FakeHandler[]>();
+	const commands = new Map<string, CommandOptions>();
+	const fake: FakePi = {
+		pi: undefined as unknown as ExtensionAPI,
+		handlers,
+		commands,
+		shortcuts: [],
+		tools: [],
+		providers: [],
+		renderers: new Map(),
+		entries: [],
+		messages: [],
+		async fire(name, event, ctx) {
+			const results: unknown[] = [];
+			for (const handler of handlers.get(name) ?? []) {
+				// oxlint-disable-next-line no-await-in-loop -- pi runs handlers one at a time, in order
+				results.push(await handler(event, ctx));
+			}
+			return results;
+		},
+		count: (name) => handlers.get(name)?.length ?? 0,
+	};
+
+	fake.pi = {
+		on(name: string, handler: FakeHandler) {
+			handlers.set(name, [...(handlers.get(name) ?? []), handler]);
+			return () => {};
+		},
+		events: bus,
+		registerCommand: (name: string, options: CommandOptions) => void commands.set(name, options),
+		registerShortcut: (shortcut: unknown) => void fake.shortcuts.push(String(shortcut)),
+		registerTool: (tool: ToolDefinition) => void fake.tools.push(tool),
+		registerProvider: (name: unknown, config?: unknown) =>
+			void fake.providers.push({ name: String(name), config }),
+		registerEntryRenderer: (customType: string, renderer: EntryRenderer) =>
+			void fake.renderers.set(customType, renderer),
+		appendEntry: (customType: string, data?: unknown) =>
+			void fake.entries.push({ customType, data }),
+		sendMessage: (message: unknown) => void fake.messages.push(message),
+	} as unknown as ExtensionAPI;
+
+	return fake;
+}
+
+export interface FakeScopeOptions {
+	id?: string;
+	pi?: FakePi;
+	/** Collects what the feature warned about. */
+	notes?: string[];
+	settingsPath?: string;
+}
+
+/**
+ * A feature scope over a fake pi, for calling a feature's own modules directly. Session hooks
+ * registered through it run when `fire("session_start")` or `fire("session_shutdown")` is called.
+ * It does not add the app's error attribution, which the kit tests on its own.
+ */
+export function fakeScope(options: FakeScopeOptions = {}): FeatureScope {
+	const fake = options.pi ?? fakePi();
+	const notes = options.notes ?? [];
+	const settings = new SettingsStore(
+		options.settingsPath ?? join(tmpdir(), `pi-kit-scope-${process.pid}-${Math.random()}.json`),
+	);
+
+	return {
+		...fake.pi,
+		id: options.id ?? "test",
+		settings,
+		on: fake.pi.on,
+		registerCommand: (name, command) => fake.pi.registerCommand(name, command),
+		onSessionStart: (run) => void fake.pi.on("session_start", (_event, ctx) => run(ctx)),
+		onShutdown: (run) => void fake.pi.on("session_shutdown", () => run()),
+		warn: (message) => void notes.push(message),
+		has: () => false,
+	};
+}
+
+export function fakeContext(
+	notes: string[] = [],
+	hasUI = true,
+	extra: Record<string, unknown> = {},
+): ExtensionContext {
+	return {
+		hasUI,
+		mode: hasUI ? "tui" : "print",
+		cwd: "/nonexistent",
+		isProjectTrusted: () => false,
+		ui: { notify: (message: string) => notes.push(message) },
+		...extra,
+	} as unknown as ExtensionContext;
+}