@danypops/pi-packed 0.19.9 → 0.19.11

package/service/src/pi/pi-version.ts

@@ -0,0 +1,171 @@
+/**
+ * Tracks the running Pi coding agent version against the same first-party
+ * source Pi's own update-check uses -- never the npm registry, which could
+ * disagree with pi.dev/api/latest-version during a package-rename
+ * migration (the API's own packageName field exists for exactly that).
+ */
+
+import { defaultPiBin } from "../packages/install.ts";
+import {
+	type InteractiveRunResult,
+	runBounded,
+	runInherited,
+	type VersionCommand,
+	type VersionCommandResult,
+	versionAtLeast,
+} from "../publish/publish.ts";
+
+const LATEST_VERSION_URL = "https://pi.dev/api/latest-version";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_NOTE_BYTES = 2_000;
+/** The API response includes this field on every response, not only during
+ * an actual rename (confirmed live) -- a genuine migration signal is
+ * `packageName !== CURRENT_PI_PACKAGE_NAME`, matching Pi's own
+ * getSelfUpdatePlan comparison, never mere field presence. */
+export const CURRENT_PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
+
+/** Resolves the real pi binary the same way install.ts's ExecInstaller
+ * does (PI_PACKED_PI_BIN / PI_BIN / bare "pi" fallback) -- a bare "pi"
+ * argv fails under systemd's minimal PATH, which doesn't include wherever
+ * a user's own pi install actually lives. */
+export const readPiVersion: VersionCommand = () => runBounded([defaultPiBin(), "--version"]);
+
+export interface PiReleaseInfo {
+	version: string;
+	/** Exists for a future package-rename migration -- absent under normal operation. */
+	packageName?: string;
+	note?: string;
+}
+
+function packedUserAgent(): string {
+	const runtime = process.versions.bun ? `bun/${process.versions.bun}` : `node/${process.version}`;
+	return `packed (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+function parseVersionOutput(result: VersionCommandResult): string | undefined {
+	if (result.code !== 0) return undefined;
+	const trimmed = result.stdout.trim();
+	return /^\d+\.\d+\.\d+/.test(trimmed) ? trimmed : undefined;
+}
+
+/** Resolves only the locally running Pi version -- no network call, unlike
+ * checkPiVersion, which also fetches the latest release. Compatibility
+ * scoring needs the current version only, so it never pays pi.dev latency
+ * or fails closed on a network blip that has nothing to do with it. */
+export async function resolveCurrentPiVersion(versionCommand: VersionCommand = readPiVersion): Promise<string | undefined> {
+	return parseVersionOutput(await versionCommand().catch((): VersionCommandResult => ({ code: 1, stdout: "", stderr: "" })));
+}
+
+export type FetchLatestPiRelease = (options?: { timeoutMs?: number }) => Promise<PiReleaseInfo | undefined>;
+
+/**
+ * Fetches the exact endpoint Pi's own self-update check uses. Respects the
+ * same opt-outs Pi's own checker does (PI_SKIP_VERSION_CHECK, PI_OFFLINE)
+ * so Packed never makes a network call the user already disabled. Never
+ * throws -- an unreachable endpoint, timeout, or malformed response all
+ * resolve to undefined ("unknown"), never a crash. `baseUrl` is test-only
+ * (points at a real local Bun.serve() fixture instead of the live endpoint,
+ * matching this codebase's existing HttpRegistry test convention).
+ */
+export function createFetchLatestPiRelease(baseUrl: string = LATEST_VERSION_URL): FetchLatestPiRelease {
+	return async (options = {}) => {
+		if (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;
+		try {
+			const response = await fetch(baseUrl, {
+				headers: { "User-Agent": packedUserAgent(), accept: "application/json" },
+				signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+			});
+			if (!response.ok) return undefined;
+			const data = (await response.json()) as { packageName?: unknown; version?: unknown; note?: unknown };
+			if (typeof data.version !== "string" || !data.version.trim()) return undefined;
+			const packageName = typeof data.packageName === "string" && data.packageName.trim() ? data.packageName.trim() : undefined;
+			const note = typeof data.note === "string" && data.note.trim() ? data.note.trim().slice(0, MAX_NOTE_BYTES) : undefined;
+			return { version: data.version.trim(), ...(packageName ? { packageName } : {}), ...(note ? { note } : {}) };
+		} catch {
+			return undefined;
+		}
+	};
+}
+
+export const fetchLatestPiRelease: FetchLatestPiRelease = createFetchLatestPiRelease();
+
+export interface PiVersionReport {
+	/** undefined when `pi` isn't on PATH or its output couldn't be parsed. */
+	current?: string;
+	/** undefined when the latest-version check failed, timed out, or was opted out of. */
+	latest?: string;
+	/** undefined whenever either current or latest is unknown -- never a guess. */
+	upToDate?: boolean;
+	packageName?: string;
+	note?: string;
+}
+
+/** Pure argv construction, kept separate from the actual spawn so tests
+ * never risk invoking a real `pi update --self`. */
+export function piUpdateSelfArgs(): string[] {
+	return [defaultPiBin(), "update", "--self"];
+}
+
+/**
+ * Runs Pi's own already-correct self-update command directly -- npm/pnpm/
+ * yarn/bun install-method detection, Windows quirks, its own release note,
+ * all already solved there. Packed orchestrates it, never reimplements it,
+ * matching the exact boundary already established for npm login/trust.
+ * Inherited stdio so any interactive prompt Pi itself shows still works.
+ */
+export function runPiUpdateSelf(): Promise<InteractiveRunResult> {
+	return runInherited(piUpdateSelfArgs());
+}
+
+export interface PiVersionCheckOptions {
+	versionCommand?: VersionCommand;
+	fetchLatest?: FetchLatestPiRelease;
+	timeoutMs?: number;
+}
+
+export async function checkPiVersion(options: PiVersionCheckOptions = {}): Promise<PiVersionReport> {
+	const fetchLatest = options.fetchLatest ?? fetchLatestPiRelease;
+	const current = await resolveCurrentPiVersion(options.versionCommand);
+	const release = await fetchLatest({ timeoutMs: options.timeoutMs });
+	if (!release) return current ? { current } : {};
+	const upToDate = current ? versionAtLeast(current, release.version) : undefined;
+	const renamed = release.packageName && release.packageName !== CURRENT_PI_PACKAGE_NAME ? release.packageName : undefined;
+	return {
+		...(current ? { current } : {}),
+		latest: release.version,
+		...(upToDate !== undefined ? { upToDate } : {}),
+		...(renamed ? { packageName: renamed } : {}),
+		...(release.note ? { note: release.note } : {}),
+	};
+}
+
+export interface PiStatusInteractiveDeps {
+	/** Reads current status; called once up front, and again after a
+	 * successful update to report the refreshed state. */
+	check(): Promise<PiVersionReport>;
+	/** Asks the human a yes/no question. Real callers gate this on a TTY
+	 * themselves before ever invoking this function at all. */
+	confirm(question: string): Promise<boolean>;
+	/** Runs the real update subprocess. Only ever called after confirm()
+	 * resolves true. */
+	runUpdate(): Promise<{ ok: boolean }>;
+}
+
+/**
+ * Pure orchestration decision logic for "packed pi status", fully
+ * dependency-injected and unit-testable without a real terminal, a real
+ * subprocess, or a real network call: confirm only when genuinely behind,
+ * update only after a yes, re-check only after a successful update, never
+ * silently swallow a failed update by reporting stale success. The real
+ * CLI entrypoint supplies real confirm/runUpdate/check implementations and
+ * is itself not unit tested, matching this codebase's established split
+ * between tested decision logic and untested real-I/O glue.
+ */
+export async function runPiStatusInteractive(deps: PiStatusInteractiveDeps): Promise<PiVersionReport> {
+	const report = await deps.check();
+	if (report.upToDate !== false || !report.current || !report.latest) return report;
+	if (!(await deps.confirm(`pi ${report.current} is behind the latest ${report.latest}. Run pi update --self now?`))) return report;
+	const result = await deps.runUpdate();
+	if (!result.ok) return report;
+	return deps.check();
+}

package/service/src/public/atomic-json.ts

@@ -0,0 +1,32 @@
+/**
+ * A Pi extension package (pi-packed) can't safely import ../shared/*.ts
+ * raw at extension runtime -- pi's jiti-based extension loader has a real,
+ * demonstrated failure class transpiling a dependency's raw, unbuilt
+ * TypeScript. Duplicated (not re-exported) from ../shared/atomic-json.ts
+ * for that reason, same rationale as client.ts/protocol.ts living under
+ * src/public/ as their own self-contained compiled entry points rather
+ * than thin re-exports of internal daemon-side modules.
+ */
+import { existsSync, lstatSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createAtomicJsonWriter } from "@danypops/vehicle-core";
+import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
+
+const writer = createAtomicJsonWriter({ fs: createNodeAtomicJsonFsAdapter() });
+
+export interface WriteJsonAtomicOptions {
+	/** POSIX mode for the written file. Omitted means the OS/adapter's own default. */
+	mode?: number;
+	/** Pretty-prints with 2-space indentation. Defaults to false (compact). */
+	pretty?: boolean;
+	/** Appends a trailing newline. Defaults to true. */
+	trailingNewline?: boolean;
+	/** Parent directory mode, created if missing. Defaults to 0o700 (private). */
+	dirMode?: number;
+}
+
+export async function writeJsonAtomic(path: string, value: unknown, options: WriteJsonAtomicOptions = {}): Promise<void> {
+	mkdirSync(dirname(path), { recursive: true, mode: options.dirMode ?? 0o700 });
+	if (existsSync(path) && lstatSync(path).isSymbolicLink()) throw new Error(`ATOMIC_JSON_PATH_UNSAFE: refusing to replace symlink ${path}`);
+	await writer.write(path, value, { mode: options.mode, pretty: options.pretty, trailingNewline: options.trailingNewline ?? true });
+}

package/service/src/public/client.ts

@@ -0,0 +1,277 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
+import { readDaemonHandle, resolveDaemonPaths } from "@danypops/vehicle-server/paths";
+import { isServiceInstalled as vehicleIsServiceInstalled } from "@danypops/vehicle-server/service";
+import type {
+	ExtensionOperationInputs,
+	ExtensionOperationName,
+	ExtensionOperationOutputs,
+	PackageInfo,
+	PackageResources,
+	PackageSummary,
+	PiStatus,
+	ResourceField,
+	SecuritySettings,
+	ServiceSpecSummary,
+	SetupApplyResult,
+	SetupPlan,
+	UpdateEntry,
+	UpdateOutcome,
+} from "./protocol.js";
+
+/** notADaemon: the overwhelmingly common case for install() -- most Pi packages aren't daemons at all. Distinct from a real installService failure (systemctl unavailable, spec resolved but installation itself failed). */
+export class InstallServiceError extends Error {
+	constructor(
+		message: string,
+		readonly notADaemon?: boolean,
+	) {
+		super(message);
+		this.name = "InstallServiceError";
+	}
+}
+
+export interface PackedClientPaths {
+	token: string;
+	handle: string;
+	serviceDescriptor: string;
+}
+const SERVICE_NAME = "pi-packed";
+const SERVICE_UNIT_NAME = "pi-packed.service";
+export interface PackedPathOptions {
+	env?: Record<string, string | undefined>;
+	home?: string;
+	platform?: NodeJS.Platform;
+}
+export interface PackedExtensionClient {
+	search(query: string, limit: number, offline?: boolean): Promise<{ query: string; total: number; results: PackageSummary[] }>;
+	info(name: string): Promise<PackageInfo>;
+	installed(): Promise<ExtensionOperationOutputs["package.installed"]>;
+	updates(): Promise<UpdateEntry[]>;
+	security(): Promise<SecuritySettings>;
+	setMutationApproval(value: SecuritySettings["mutationApproval"], approved?: boolean): Promise<SecuritySettings>;
+	install(source: string, approved?: boolean): Promise<string>;
+	installService(source: string, approved?: boolean): Promise<{ output: string; spec?: ServiceSpecSummary }>;
+	remove(name: string, approved?: boolean): Promise<string>;
+	update(source: string, approved?: boolean): Promise<UpdateOutcome>;
+	setupPlan(manifestPath: string, prune?: boolean): Promise<SetupPlan>;
+	setupApply(manifestPath: string, approved?: boolean, prune?: boolean): Promise<SetupApplyResult>;
+	listResources(projectRoot?: string): Promise<{ global: PackageResources[]; project: PackageResources[] }>;
+	toggleResource(
+		source: string,
+		field: ResourceField,
+		path: string,
+		enabled: boolean,
+		projectRoot?: string,
+		approved?: boolean,
+	): Promise<string>;
+	piStatus(): Promise<PiStatus>;
+}
+
+export function resolvePackedClientPaths(options: PackedPathOptions = {}): PackedClientPaths {
+	const env = options.env ?? process.env;
+	if (env.PI_PACKED_HOME) {
+		const directory = resolve(env.PI_PACKED_HOME);
+		return { token: `${directory}/token`, handle: `${directory}/handle.json`, serviceDescriptor: `${directory}/${SERVICE_UNIT_NAME}` };
+	}
+	const paths = resolveDaemonPaths(
+		{
+			stateDirectoryName: "pi-packed",
+			databaseFilename: "packages.db",
+			tokenFilename: "token",
+			handleFilename: "handle.json",
+			systemdUnitName: SERVICE_UNIT_NAME,
+		},
+		options,
+	);
+	return { token: paths.token, handle: paths.handle, serviceDescriptor: paths.serviceDescriptor };
+}
+
+/** Real, file-existence-only check on Linux/macOS (Windows checks a
+ * registry Run key instead) -- cheap, synchronous, no subprocess. */
+function isPackedServiceInstalled(serviceDescriptor: string): boolean {
+	return vehicleIsServiceInstalled(
+		{ name: SERVICE_NAME, binPath: "", descriptorPath: serviceDescriptor },
+		{
+			fileExists: existsSync,
+			writeFile: () => {},
+			readFile: () => null,
+			removeFile: () => {},
+			mkdirp: () => {},
+			runCommand: () => ({ ok: false, output: "" }),
+			which: () => false,
+		},
+	);
+}
+
+export type FetchTransport = (request: Request) => Promise<Response>;
+
+function boundedTransport(transport: FetchTransport, timeoutMs = 30_000): FetchTransport {
+	return (request) => transport(new Request(request, { signal: AbortSignal.any([request.signal, AbortSignal.timeout(timeoutMs)]) }));
+}
+
+export class PackedClient implements PackedExtensionClient {
+	private readonly rpc: AuthenticatedRpcClient<ExtensionOperationName, ExtensionOperationInputs, ExtensionOperationOutputs>;
+	constructor(base: string, token: string, transport: FetchTransport = fetch) {
+		this.rpc = new AuthenticatedRpcClient(base, token, { label: "Packed", transport: boundedTransport(transport) });
+	}
+	private call<Name extends ExtensionOperationName>(
+		name: Name,
+		input: ExtensionOperationInputs[Name],
+	): Promise<ExtensionOperationOutputs[Name]> {
+		return this.rpc.call(name, input);
+	}
+	health(): Promise<unknown> {
+		return this.rpc.health();
+	}
+	search(query: string, limit: number, offline = false) {
+		return this.call("package.search", { query, limit, offline });
+	}
+	info(name: string) {
+		return this.call("package.info", { name });
+	}
+	installed() {
+		return this.call("package.installed", {});
+	}
+	async updates() {
+		return (await this.call("package.updates", {})).updates;
+	}
+	security() {
+		return this.call("package.security.get", {});
+	}
+	setMutationApproval(mutationApproval: SecuritySettings["mutationApproval"], approved = false) {
+		return this.call("package.security.set", { mutationApproval, approved });
+	}
+	async install(source: string, approved = false) {
+		const result = await this.call("package.install", { source, approved });
+		if (!result.ok) throw new Error(result.output);
+		return result.output;
+	}
+	async installService(source: string, approved = false) {
+		const result = await this.call("package.install_service", { source, approved });
+		if (!result.ok) throw new InstallServiceError(result.output, result.notADaemon);
+		return { output: result.output, spec: result.spec };
+	}
+	async remove(name: string, approved = false) {
+		const result = await this.call("package.remove", { name, approved });
+		if (!result.ok) throw new Error(result.output);
+		return result.output;
+	}
+	async update(source: string, approved = false): Promise<UpdateOutcome> {
+		const result = await this.call("package.update", { source, approved });
+		if (!result.ok) throw new Error(result.output);
+		return {
+			output: result.output,
+			reloadRequired: result.reloadRequired ?? true,
+			alreadyUpToDate: result.alreadyUpToDate ?? false,
+			pinned: result.pinned ?? false,
+			previousVersion: result.previousVersion,
+			currentVersion: result.currentVersion,
+		};
+	}
+	setupPlan(manifestPath: string, prune = false) {
+		return this.call("setup.plan", { manifestPath, prune });
+	}
+	setupApply(manifestPath: string, approved = false, prune = false) {
+		return this.call("setup.apply", { manifestPath, approved, prune });
+	}
+	listResources(projectRoot?: string) {
+		return this.call("resources.list", { projectRoot });
+	}
+	async toggleResource(source: string, field: ResourceField, path: string, enabled: boolean, projectRoot?: string, approved = false) {
+		const result = await this.call("resources.toggle", { source, field, path, enabled, projectRoot, approved });
+		if (!result.ok) throw new Error(result.output);
+		return result.output;
+	}
+	piStatus() {
+		return this.call("pi.status", {});
+	}
+}
+
+export async function connectPackedClient(paths = resolvePackedClientPaths(), transport: FetchTransport = fetch): Promise<PackedClient> {
+	const handle = readDaemonHandle(paths.handle);
+	if (!handle) throw new Error("Packed daemon is not running");
+	let token: string;
+	try {
+		token = readFileSync(paths.token, "utf8").trim();
+	} catch {
+		throw new Error("Packed daemon token is unavailable");
+	}
+	if (!/^[a-f0-9]{64}$/.test(token)) throw new Error("Packed daemon token is invalid");
+	const client = new PackedClient(`http://${handle.host}:${handle.port}`, token, transport);
+	await client.health();
+	return client;
+}
+
+export interface EnsureClientDeps {
+	connect(): Promise<PackedClient>;
+	/** Real OS check, not a guess -- does this machine have a supervised
+	 * service registered for this daemon (systemd --user unit / launchd
+	 * plist / Windows Run key)? */
+	isServiceInstalled(): boolean;
+	/** Spawns a detached, self-contained daemon for this session only.
+	 * Never called when isServiceInstalled() is true. */
+	spawn(): void;
+	sleep(ms: number): Promise<void>;
+	retryAttempts?: number;
+	retryDelayMs?: number;
+}
+
+/**
+ * Pure connect-or-provision decision, fully dependency-injected and
+ * unit-testable without a real filesystem, subprocess, or network call.
+ *
+ * A real, confirmed hazard motivates the isServiceInstalled() branch: an
+ * auto-spawned orphan gets vehicle-server's 30-minute idle budget (vs. a
+ * supervised service's own, typically much shorter, policy), so it can
+ * keep winning vehicle-server's single-instance lock race against every
+ * subsequent supervised restart, invisibly, for up to half an hour. When a
+ * service is installed, this never spawns a second, differently-supervised
+ * process -- it retries the connection instead, on the assumption the
+ * supervisor is responsible for the daemon actually being reachable, and
+ * fails with a message pointing at the service rather than silently
+ * creating a competing one.
+ */
+export async function ensureClient(deps: EnsureClientDeps): Promise<PackedClient> {
+	try {
+		return await deps.connect();
+	} catch {}
+	const attempts = deps.retryAttempts ?? 30;
+	const delayMs = deps.retryDelayMs ?? 100;
+	const serviceInstalled = deps.isServiceInstalled();
+	if (!serviceInstalled) deps.spawn();
+	for (let attempt = 0; attempt < attempts; attempt++) {
+		await deps.sleep(delayMs);
+		try {
+			return await deps.connect();
+		} catch {}
+	}
+	const waitedSeconds = (attempts * delayMs) / 1000;
+	throw new Error(
+		serviceInstalled
+			? `Packed daemon did not become ready within ${waitedSeconds} seconds, but a supervised service is installed -- check it directly (e.g. systemctl --user status pi-packed.service) rather than auto-spawning a second one`
+			: `Packed daemon did not become ready within ${waitedSeconds} seconds`,
+	);
+}
+
+export async function ensurePackedClient(paths = resolvePackedClientPaths(), transport: FetchTransport = fetch): Promise<PackedClient> {
+	return ensureClient({
+		connect: () => connectPackedClient(paths, transport),
+		isServiceInstalled: () => isPackedServiceInstalled(paths.serviceDescriptor),
+		spawn: () => {
+			const override = process.env.PI_PACKED_BIN;
+			const command = override ?? process.env.PI_PACKED_BUN ?? "bun";
+			const args = override ? ["serve"] : [join(dirname(fileURLToPath(import.meta.url)), "../service/src/cli/cli.ts"), "serve"];
+			const child = spawn(command, args, {
+				detached: true,
+				stdio: "ignore",
+				env: { ...process.env, DAEMON_KIT_LAUNCH_PROVENANCE: "auto-spawn" },
+			});
+			child.once("error", () => {});
+			child.unref();
+		},
+		sleep: (ms) => new Promise((resolveDelay) => setTimeout(resolveDelay, ms)),
+	});
+}

package/service/src/public/protocol.ts

@@ -0,0 +1,169 @@
+export interface PackageEvidence {
+	shape: "keyword-only" | "manifest" | "conventional";
+	verified: boolean;
+	evidence: string[];
+}
+export interface PublicationEvidence {
+	integrity?: string;
+	provenanceUrl?: string;
+	trustedPublisher: "verified" | "not-verified" | "unknown";
+}
+export interface PackageSummary {
+	name: string;
+	version: string;
+	description?: string;
+	date?: string;
+	packageEvidence?: PackageEvidence;
+	publication?: PublicationEvidence;
+}
+export interface PackageInfo extends PackageSummary {
+	homepage?: string;
+	repository?: string;
+	license?: string;
+	keywords?: string[];
+	pi?: Record<string, unknown>;
+	modified?: string;
+	unpackedSize?: number;
+	readme?: string;
+	readmeAvailable?: boolean;
+	bugs?: string;
+	peerDependencies?: Record<string, string>;
+}
+export interface InstalledPackage {
+	name: string;
+	pinned?: string;
+	installed?: string;
+}
+export interface UpdateEntry {
+	name: string;
+	installed: string;
+	latest: string;
+	detectedAt?: string;
+}
+export interface UpdateOutcome {
+	output: string;
+	reloadRequired: boolean;
+	alreadyUpToDate: boolean;
+	pinned: boolean;
+	previousVersion?: string;
+	currentVersion?: string;
+}
+export interface Diagnostic {
+	code: string;
+	severity: "error" | "warning" | "info";
+	path: string;
+	message: string;
+	fix?: string;
+}
+export interface SetupOperation {
+	kind: "install-package" | "update-package" | "remove-package" | "write-profile" | "remove-profile";
+	packageName?: string;
+	name?: string;
+	scope: "global" | "project";
+	source?: string;
+	resolved?: string;
+	fields?: string[];
+}
+export interface SetupPlan {
+	ok: boolean;
+	manifestPath: string;
+	operations: SetupOperation[];
+	manifestSha256?: string;
+	prune?: boolean;
+	diagnostics: Diagnostic[];
+}
+export interface SetupApplyResult {
+	ok: boolean;
+	manifestPath: string;
+	operations: Array<{ kind: SetupOperation["kind"]; target: string; status: "succeeded" | "failed"; output?: string }>;
+	reloadRequired: boolean;
+	diagnostics: Diagnostic[];
+}
+export interface SecuritySettings {
+	mutationApproval: "always" | "never";
+}
+export type ResourceField = "extensions" | "skills" | "prompts" | "themes";
+export interface ResourceItem {
+	path: string;
+	enabled: boolean;
+}
+export type PackageResources = { source: string; name: string; scope: "global" | "project" } & Record<ResourceField, ResourceItem[]>;
+
+export interface ServiceSpecSummary {
+	name: string;
+	binPath: string;
+	descriptorPath: string;
+}
+
+/** Mirrors service/src/pi/pi-version.ts's CURRENT_PI_PACKAGE_NAME
+ * literal -- not a shared import, since the public boundary deliberately
+ * stays free of internal runtime-specific modules. Keep the two in sync by hand. */
+export const PI_COMMAND_NAME = "@earendil-works/pi-coding-agent";
+
+/** Mirrors pi/pi-version.ts's PiVersionReport. */
+export interface PiStatus {
+	current?: string;
+	latest?: string;
+	upToDate?: boolean;
+	packageName?: string;
+	note?: string;
+}
+
+export type ExtensionOperationName =
+	| "package.search"
+	| "package.info"
+	| "package.installed"
+	| "package.updates"
+	| "package.security.get"
+	| "package.security.set"
+	| "package.install"
+	| "package.install_service"
+	| "package.remove"
+	| "package.update"
+	| "setup.plan"
+	| "setup.apply"
+	| "resources.list"
+	| "resources.toggle"
+	| "pi.status";
+export interface ExtensionOperationInputs {
+	"package.search": { query: string; limit: number; offline?: boolean };
+	"package.info": { name: string };
+	"package.installed": Record<string, never>;
+	"package.updates": Record<string, never>;
+	"pi.status": Record<string, never>;
+	"package.security.get": Record<string, never>;
+	"package.security.set": { mutationApproval: SecuritySettings["mutationApproval"]; approved?: boolean };
+	"package.install": { source: string; approved?: boolean };
+	"package.install_service": { source: string; approved?: boolean };
+	"package.remove": { name: string; approved?: boolean };
+	"package.update": { source: string; approved?: boolean };
+	"setup.plan": { manifestPath: string; prune?: boolean };
+	"setup.apply": { manifestPath: string; approved?: boolean; prune?: boolean };
+	"resources.list": { projectRoot?: string };
+	"resources.toggle": { source: string; field: ResourceField; path: string; enabled: boolean; projectRoot?: string; approved?: boolean };
+}
+export interface ExtensionOperationOutputs {
+	"package.search": { query: string; total: number; results: PackageSummary[]; offline?: boolean };
+	"package.info": PackageInfo;
+	"package.installed": InstalledPackage[];
+	"package.updates": { updates: UpdateEntry[] };
+	"package.security.get": SecuritySettings;
+	"package.security.set": SecuritySettings;
+	"package.install": { ok: boolean; output: string };
+	"package.install_service": { ok: boolean; output: string; spec?: ServiceSpecSummary; notADaemon?: boolean };
+	"package.remove": { ok: boolean; output: string };
+	"package.update": {
+		ok: boolean;
+		output: string;
+		reloadRequired?: boolean;
+		alreadyUpToDate?: boolean;
+		pinned?: boolean;
+		previousVersion?: string;
+		currentVersion?: string;
+	};
+	"setup.plan": SetupPlan;
+	"setup.apply": SetupApplyResult;
+	"resources.list": { global: PackageResources[]; project: PackageResources[] };
+	"resources.toggle": { ok: boolean; output: string };
+	"pi.status": PiStatus;
+}