osdy-pi 1.3.0 → 1.4.0

package/README.md

@@ -99,6 +99,18 @@ git clone https://github.com/Gentleman-Programming/gentle-pi.git
 osdy-pi gentle setup "$(pwd)/gentle-pi"
 ```
 
+## Explicit Joker agents setup in normal Pi
+
+After `pi install npm:osdy-pi`, open **normal personal Pi** (not `osdy`'s isolated profile) and run:
+
+```text
+/osdy-pi agents setup
+```
+
+Review the confirmation: it names `~/.pi/agent/settings.json`, installs `npm:pi-subagents-j0k3r` using Pi's package command, and adds only `-extensions/gentle-agents.ts` to each eligible Gentle package entry. It preserves unrelated settings and Gentle resources; if no Gentle package is present, it only installs Joker. After success, Pi reloads resources (restart Pi if reload fails). `/osdy-pi agents status` checks the personal Joker/Gentle setup without writing. Cancel changes nothing; rerunning is safe. This command is available inside Pi after the Pi package install—no global npm CLI or package postinstall hook is required.
+
+Gentle package detection supports `npm:gentle-pi` and validated local checkouts (absolute, settings-relative, `~/`, and `file:` paths). Remote Git/HTTPS Gentle sources are not reconciled: when recognized, setup stops before installing Joker rather than reporting a false success. Register a local Gentle checkout or npm Gentle source in personal Pi first; the existing `osdy-pi gentle setup /absolute/path/to/gentle-pi` command can configure local coexistence if you have that CLI. Setup refuses an isolated/custom `$PI_CODING_AGENT_DIR` or a project-local Gentle override because a personal filter cannot reliably control those contexts. Run it in normal Pi without a conflicting project package; an invalid settings file or failed install produces an error rather than silently applying only part of the filter. It does not edit credentials.
+
 ## Gentle coexistence setup
 
 To load a local `gentle-pi` checkout while keeping Osdy Pi's UI authoritative, run:

package/extensions/osdy-pi/agent-coexistence-setup.test.ts

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { registerHooks } from "node:module";
+import test from "node:test";
+
+registerHooks({ resolve(specifier, context, nextResolve) {
+	if (specifier === "./agent-coexistence-setup.js" && context.parentURL?.endsWith(".test.ts"))
+		return { shortCircuit: true, url: new URL("./agent-coexistence-setup.ts", context.parentURL).href };
+	return nextResolve(specifier, context);
+} });
+const { setupJokerAgents } = await import("./agent-coexistence-setup.js");
+
+async function fixture() {
+	const root = await mkdtemp(join(tmpdir(), "osdy-joker-"));
+	const agentDir = join(root, ".pi", "agent");
+	const gentle = join(root, "gentle");
+	await mkdir(agentDir, { recursive: true });
+	await mkdir(gentle);
+	await writeFile(join(gentle, "package.json"), '{"name":"gentle-pi"}');
+	const settingsPath = join(agentDir, "settings.json");
+	const packages = ["npm:other", { source: gentle, extensions: ["-extensions/gentle-todo.ts"], themes: [], skills: ["skills/*"] }, "npm:gentle-pi@1.2.0", { source: "npm:gentle-pi", extensions: ["-extensions/gentle-agents.ts"] }];
+	await writeFile(settingsPath, JSON.stringify({ theme: "dark", packages }));
+	return { root, agentDir, gentle, settingsPath, packages };
+}
+
+const base = (f: Awaited<ReturnType<typeof fixture>>) => ({
+	agentDir: f.agentDir, home: f.root, cwd: f.root, env: {},
+});
+
+void test("installs Joker then narrowly reconciles every Gentle entry using latest settings", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = async () => {
+		calls++;
+		const latest = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[] };
+		latest.packages.push("npm:pi-subagents-j0k3r", "npm:newly-added");
+		await writeFile(f.settingsPath, JSON.stringify(latest));
+	};
+	await setupJokerAgents({ ...base(f), install });
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[]; theme: string };
+	assert.equal(calls, 1);
+	assert.deepEqual(settings.packages, [
+		"npm:other",
+		{ source: f.gentle, extensions: ["-extensions/gentle-todo.ts", "-extensions/gentle-agents.ts"], themes: [], skills: ["skills/*"] },
+		{ source: "npm:gentle-pi@1.2.0", extensions: ["-extensions/gentle-agents.ts"] },
+		{ source: "npm:gentle-pi", extensions: ["-extensions/gentle-agents.ts"] },
+		"npm:pi-subagents-j0k3r", "npm:newly-added",
+	]);
+	assert.equal(settings.theme, "dark");
+	await setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("duplicate install")) });
+	assert.equal((await readFile(f.settingsPath, "utf8")).includes("duplicate"), false);
+});
+
+void test("relative Gentle sources resolve from settings and project overrides fail closed", async () => {
+	const f = await fixture();
+	const local = join(f.agentDir, "gentle-local");
+	await mkdir(local);
+	await writeFile(join(local, "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(f.settingsPath, '{"packages":["./gentle-local","npm:pi-subagents-j0k3r"]}');
+	await setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("should skip")) });
+	const result = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[] };
+	assert.deepEqual(result.packages[0], { source: "./gentle-local", extensions: ["-extensions/gentle-agents.ts"] });
+	const project = join(f.root, "project");
+	await mkdir(join(project, ".pi", "gentle"), { recursive: true });
+	await writeFile(join(project, ".pi", "gentle", "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":["./gentle"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), cwd: project }), /project-local Gentle/i);
+});
+
+void test("bare, tilde, and file URL local Gentle entries get the narrow personal filter", async () => {
+	const f = await fixture();
+	const bare = join(f.agentDir, "gentle");
+	await mkdir(bare);
+	await writeFile(join(bare, "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(f.settingsPath, JSON.stringify({ packages: ["gentle", "~/gentle", pathToFileURL(f.gentle).href, "npm:pi-subagents-j0k3r"] }));
+	const result = await setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("no install")) });
+	assert.equal(result.gentleCount, 3);
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: Array<{ source: string; extensions: string[] }> };
+	assert.deepEqual(settings.packages.slice(0, 3).map((entry) => entry.extensions), Array(3).fill(["-extensions/gentle-agents.ts"]));
+});
+
+void test("bare project Gentle override and ambiguous Gentle local path fail before install", async () => {
+	const f = await fixture();
+	const project = join(f.root, "project");
+	await mkdir(join(project, ".pi", "gentle"), { recursive: true });
+	await writeFile(join(project, ".pi", "gentle", "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":["gentle"]}');
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	await assert.rejects(setupJokerAgents({ ...base(f), cwd: project, install }), /project-local Gentle/i);
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":[]}');
+	await writeFile(f.settingsPath, '{"packages":["gentle","npm:pi-subagents-j0k3r"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), install }), /Gentle.*resolve|Gentle.*source/i);
+	assert.equal(calls, 0);
+});
+
+void test("recognizable remote Gentle sources fail closed before install, but unrelated Git packages remain", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	for (const remote of [
+		"git:github.com/Gentleman-Programming/gentle-pi",
+		"https://github.com/Gentleman-Programming/gentle-pi.git",
+	]) {
+		await writeFile(f.settingsPath, JSON.stringify({ packages: [remote, "git:github.com/owner/other-package"] }));
+		await assert.rejects(setupJokerAgents({ ...base(f), install }), /remote Gentle.*local.*npm/i);
+		const project = join(f.root, "project");
+		await mkdir(join(project, ".pi"), { recursive: true });
+		await writeFile(join(project, ".pi", "settings.json"), JSON.stringify({ packages: [remote] }));
+		await writeFile(f.settingsPath, '{"packages":["npm:pi-subagents-j0k3r"]}');
+		await assert.rejects(setupJokerAgents({ ...base(f), cwd: project, install }), /remote Gentle.*local.*npm/i);
+		await writeFile(join(project, ".pi", "settings.json"), '{"packages":[]}');
+	}
+	assert.equal(calls, 0);
+	await writeFile(f.settingsPath, '{"packages":["git:github.com/owner/other-package","npm:pi-subagents-j0k3r"]}');
+	const result = await setupJokerAgents({ ...base(f), install });
+	assert.equal(result.gentleCount, 0);
+});
+
+void test("invalid Gentle filters or duplicate Joker declarations block setup before further writes", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	await writeFile(f.settingsPath, '{"packages":[{"source":"npm:gentle-pi","extensions":false}]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), install }), /Gentle extensions/i);
+	await writeFile(f.settingsPath, '{"packages":["npm:pi-subagents-j0k3r","npm:pi-subagents-j0k3r"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), install }), /duplicate Joker/i);
+	assert.equal(calls, 0);
+});
+
+void test("without Gentle, only Joker installation changes settings", async () => {
+	const f = await fixture();
+	await writeFile(f.settingsPath, '{"packages":["npm:other"]}');
+	await setupJokerAgents({ ...base(f), install: async () => {
+		await writeFile(f.settingsPath, '{"packages":["npm:other","npm:pi-subagents-j0k3r"]}');
+	} });
+	assert.deepEqual(JSON.parse(await readFile(f.settingsPath, "utf8")) as unknown, { packages: ["npm:other", "npm:pi-subagents-j0k3r"] });
+});
+
+void test("rejects alternate agent directories and project-local Gentle overrides before install", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	await assert.rejects(setupJokerAgents({ ...base(f), agentDir: join(f.root, "isolated"), install }), /personal|agent/i);
+	await assert.rejects(setupJokerAgents({ ...base(f), env: { PI_CODING_AGENT_DIR: f.agentDir }, install }), /override|normal/i);
+	const project = join(f.root, "project");
+	await mkdir(join(project, ".pi"), { recursive: true });
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":["npm:gentle-pi"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), cwd: project, install }), /project|Gentle/i);
+	assert.equal(calls, 0);
+});
+
+void test("failed installer or malformed latest settings cannot rewrite personal settings", async () => {
+	const f = await fixture();
+	const original = await readFile(f.settingsPath, "utf8");
+	await assert.rejects(setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("install failed")) }), /install failed/);
+	assert.equal(await readFile(f.settingsPath, "utf8"), original);
+	await assert.rejects(setupJokerAgents({ ...base(f), install: async () => { await writeFile(f.settingsPath, "{bad"); } }), /settings/i);
+	assert.equal(await readFile(f.settingsPath, "utf8"), "{bad");
+});

package/extensions/osdy-pi/agent-coexistence-setup.ts

@@ -0,0 +1,196 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstat, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const runFile = promisify(execFile);
+const JOKER = "npm:pi-subagents-j0k3r";
+const GENTLE_EXCLUSION = "-extensions/gentle-agents.ts";
+
+type Settings = Record<string, unknown> & { packages?: unknown[] };
+
+type SetupOptions = {
+	agentDir: string;
+	home?: string;
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+	install?: () => Promise<void>;
+};
+
+function object(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function source(entry: unknown): string | undefined {
+	if (typeof entry === "string") return entry;
+	return object(entry) && typeof entry.source === "string" ? entry.source : undefined;
+}
+
+function npmGentle(entry: unknown): boolean {
+	return /^npm:gentle-pi(?:@[^\s]+)?$/i.test(source(entry) ?? "");
+}
+
+function joker(entry: unknown): boolean {
+	return /^npm:pi-subagents-j0k3r(?:@[^\s]+)?$/i.test(source(entry) ?? "");
+}
+
+async function gentle(entry: unknown, settingsDir: string, home: string): Promise<boolean> {
+	if (npmGentle(entry)) return true;
+	const value = source(entry);
+	if (!value || /^npm:/i.test(value)) return false;
+	if (/^(?:git:|https?:\/\/)/i.test(value)) {
+		if (/(?:^|\/)gentle-pi(?:\.git)?(?:[@#?][^\s]*)?$/i.test(value))
+			throw new Error("Remote Gentle source unsupported: register a local gentle-pi checkout or npm:gentle-pi in personal Pi, then rerun agents setup.");
+		return false;
+	}
+	let path: string;
+	try {
+		if (value.startsWith("file:")) path = fileURLToPath(value);
+		else if (value === "~" || value.startsWith("~/")) path = resolve(home, value.slice(value === "~" ? 1 : 2));
+		else if (!value.includes(":")) path = resolve(settingsDir, value);
+		else return false;
+	} catch {
+		throw new Error(`Gentle source cannot be resolved: ${value}`);
+	}
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(path, "package.json"), "utf8"));
+		return object(manifest) && manifest.name === "gentle-pi";
+	} catch {
+		if (/(?:^|[\\/])gentle(?:-pi)?$/i.test(path))
+			throw new Error(`Gentle source cannot be resolved: ${value}`);
+		return false;
+	}
+}
+
+function validateGentleFilters(entry: unknown): void {
+	if (!object(entry) || entry.extensions === undefined) return;
+	if (!Array.isArray(entry.extensions) || !entry.extensions.every((value: unknown) => typeof value === "string"))
+		throw new Error("Gentle extensions filter must be an array of strings.");
+}
+
+async function regularSettings(path: string): Promise<Settings> {
+	if (!(await lstat(path)).isFile()) throw new Error("Personal settings.json must be a regular file, not a link.");
+	let value: unknown;
+	try {
+		value = JSON.parse(await readFile(path, "utf8"));
+	} catch {
+		throw new Error("Personal settings.json must contain valid JSON.");
+	}
+	if (!object(value) || (value.packages !== undefined && !Array.isArray(value.packages)))
+		throw new Error("Personal settings.json must have an object root and array packages.");
+	return value;
+}
+
+async function assertNoProjectGentle(cwd: string, home: string): Promise<void> {
+	let directory = resolve(cwd);
+	while (true) {
+		const local = join(directory, ".pi", "settings.json");
+		let text: string;
+		try {
+			text = await readFile(local, "utf8");
+		} catch (error) {
+			if (object(error) && error.code === "ENOENT") {
+				const parent = dirname(directory);
+				if (parent === directory) return;
+				directory = parent;
+				continue;
+			}
+			throw error;
+		}
+		let settings: unknown;
+		try { settings = JSON.parse(text); }
+		catch { throw new Error(`Project settings invalid at ${local}; cannot guarantee Gentle filtering.`); }
+		if (!object(settings) || (settings.packages !== undefined && !Array.isArray(settings.packages)))
+			throw new Error(`Project settings invalid at ${local}; cannot guarantee Gentle filtering.`);
+		for (const entry of settings.packages ?? []) {
+			if (await gentle(entry, dirname(local), home)) throw new Error(`Project-local Gentle package at ${local} can override the personal filter.`);
+		}
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
+	}
+}
+
+async function installJoker(): Promise<void> {
+	await runFile("pi", ["install", JOKER], { cwd: homedir(), maxBuffer: 4096 });
+}
+
+export async function inspectJokerAgents(options: Omit<SetupOptions, "install">): Promise<{ jokerInstalled: boolean; gentleCount: number; filtered: boolean }> {
+	const target = await validateTarget(options);
+	const settings = await regularSettings(join(target, "settings.json"));
+	const packages = settings.packages ?? [];
+	const flags = await Promise.all(packages.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	return {
+		jokerInstalled: packages.some(joker),
+		gentleCount: flags.filter(Boolean).length,
+		filtered: flags.every((isGentle, index) => !isGentle ||
+			(object(packages[index]) && Array.isArray(packages[index].extensions) && packages[index].extensions.includes(GENTLE_EXCLUSION))),
+	};
+}
+
+async function validateTarget(options: Omit<SetupOptions, "install">): Promise<string> {
+	const home = resolve(options.home ?? homedir());
+	const target = resolve(options.agentDir);
+	if (options.env?.PI_CODING_AGENT_DIR !== undefined || !isAbsolute(options.agentDir))
+		throw new Error("Agents setup requires normal personal Pi; agent directory override or isolated profile is unsupported.");
+	let personal: boolean;
+	try {
+		personal = (await realpath(target)) === (await realpath(join(home, ".pi", "agent")));
+	} catch {
+		personal = false;
+	}
+	if (!personal)
+		throw new Error("Agents setup requires the normal personal Pi agent directory, not an isolated profile.");
+	await assertNoProjectGentle(options.cwd, home);
+	return target;
+}
+
+export async function setupJokerAgents(options: SetupOptions): Promise<{ installed: boolean; changed: boolean; gentleCount: number }> {
+	const target = await validateTarget(options);
+	const path = join(target, "settings.json");
+	const before = await regularSettings(path);
+	const original = before.packages ?? [];
+	if (original.some((entry) => entry !== null && typeof entry !== "string" && !object(entry)))
+		throw new Error("Personal settings packages contain an invalid entry.");
+	const initialGentle = await Promise.all(original.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	if (original.filter(joker).length > 1) throw new Error("Personal settings contain duplicate Joker entries.");
+	const alreadyJoker = original.some(joker);
+	for (const [index, isGentle] of initialGentle.entries()) {
+		if (isGentle) validateGentleFilters(original[index]);
+	}
+	const filtered = initialGentle.every((isGentle, index) => !isGentle ||
+		(object(original[index]) && Array.isArray(original[index].extensions) && original[index].extensions.includes(GENTLE_EXCLUSION)));
+	if (alreadyJoker && filtered) return { installed: false, changed: false, gentleCount: initialGentle.filter(Boolean).length };
+	if (!alreadyJoker) await (options.install ?? installJoker)();
+	// Install owns only Joker. Re-read the latest settings instead of replaying a stale snapshot.
+	await assertNoProjectGentle(options.cwd, options.home ?? homedir());
+	const latest = await regularSettings(path);
+	const packages = latest.packages ?? [];
+	if (!packages.some(joker)) throw new Error("Pi install did not register Joker in personal settings; no Gentle filters were changed.");
+	if (packages.filter(joker).length > 1) throw new Error("Personal settings contain duplicate Joker entries.");
+	const gentleFlags = await Promise.all(packages.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	let changed = false;
+	const updated = packages.map((entry, index) => {
+		if (!gentleFlags[index]) return entry;
+		if (typeof entry !== "string" && !object(entry)) throw new Error("Gentle package entry is invalid.");
+		const item = typeof entry === "string" ? { source: entry } : entry;
+		validateGentleFilters(item);
+		const extensions = item.extensions as string[] | undefined;
+		if (extensions?.includes(GENTLE_EXCLUSION)) return entry;
+		changed = true;
+		return { ...item, extensions: [...(extensions ?? []), GENTLE_EXCLUSION] };
+	});
+	if (changed) {
+		const temporary = join(target, `.settings.${randomUUID()}.tmp`);
+		try {
+			await writeFile(temporary, `${JSON.stringify({ ...latest, packages: updated }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+			await rename(temporary, path);
+		} finally {
+			await unlink(temporary).catch(() => {});
+		}
+	}
+	return { installed: !alreadyJoker, changed, gentleCount: gentleFlags.filter(Boolean).length };
+}

package/extensions/osdy-pi/runtime.test.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { registerHooks } from "node:module";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import ts from "typescript";
 
 registerHooks({
@@ -43,6 +43,7 @@ const { PLUGIN_EVENTS, subscribeQuestionPromptAudioNotification } =
 const {
 	createActiveSessionRefresh,
 	getOsdyCommandCompletions,
+	handleAgentsSetupCommand,
 	refreshCodexUsage,
 } = await import("./runtime.js");
 
@@ -80,6 +81,39 @@ class TestSessionContextProvider {
 	}
 }
 
+void test("agents setup requires interactive confirmation and reloads only after success", async () => {
+	const notices: string[] = [];
+	let installs = 0;
+	let reloads = 0;
+	let accepted = false;
+	const ui = {
+		confirm: (_title: string, message: string) => {
+			assert.match(message, /pi-subagents-j0k3r/);
+			assert.match(message, /gentle-agents\.ts/);
+			assert.match(message, /settings\.json/);
+			return Promise.resolve(accepted);
+		},
+		notify: (message: string) => { notices.push(message); },
+	};
+	const ctx = { mode: "tui", hasUI: true, cwd: "/tmp", ui, reload: () => { reloads++; return Promise.resolve(); } } as unknown as ExtensionCommandContext;
+	const setup = () => { installs++; return Promise.resolve({ installed: true, changed: true, gentleCount: 1 }); };
+	await handleAgentsSetupCommand("setup", ctx, setup);
+	assert.equal(installs, 0);
+	accepted = true;
+	await handleAgentsSetupCommand("setup", ctx, setup);
+	assert.equal(installs, 1);
+	assert.equal(reloads, 1);
+	await handleAgentsSetupCommand("status", ctx, setup, () => Promise.resolve({ jokerInstalled: true, gentleCount: 1, filtered: true }));
+	assert.ok(notices.some((notice) => notice.includes("agent exclusion complete")));
+	await handleAgentsSetupCommand("invalid", ctx, setup);
+	assert.equal(installs, 1);
+	assert.ok(notices.some((notice) => notice.includes("Usage:")));
+	assert.deepEqual(getOsdyCommandCompletions("agents"), [
+		{ value: "agents setup", label: "agents setup" },
+		{ value: "agents status", label: "agents status" },
+	]);
+});
+
 void test("header command completes only catalog choices and is persisted through session wiring", () => {
 	assert.deepEqual(getOsdyCommandCompletions("header"), [
 		{ value: "header osdy-theme", label: "header osdy-theme" },

package/extensions/osdy-pi/runtime.ts

@@ -1,7 +1,11 @@
 import type {
 	ExtensionAPI,
+	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { inspectJokerAgents, setupJokerAgents } from "./agent-coexistence-setup.js";
 import { createAudioEventRouter } from "./audio-event-router.js";
 import { registerAudioNotificationFlags } from "./audio-notification-config.js";
 import { createAudioNotificationService } from "./audio-notification-service.js";
@@ -250,6 +254,7 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"on",
 			"off",
 			"status",
+			"agents",
 			"sound",
 			"working-tree",
 			"editor",
@@ -258,6 +263,9 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"diff",
 		].map((value) => ({ value, label: value }));
 	}
+	if (trimmed === "agents") {
+		return ["agents setup", "agents status"].map((value) => ({ value, label: value }));
+	}
 	if (trimmed === "sound") {
 		return [{ value: "sound setup", label: "sound setup" }];
 	}
@@ -302,6 +310,7 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"on",
 			"off",
 			"status",
+			"agents",
 			"sound",
 			"working-tree",
 			"editor",
@@ -312,6 +321,12 @@ export function getOsdyCommandCompletions(prefix: string) {
 			.filter((value) => value.startsWith(valuePrefix))
 			.map((value) => ({ value, label: value }));
 	}
+	if (parts[0] === "agents" && parts.length === 2) {
+		const valuePrefix = parts[1] ?? "";
+		return ["setup", "status"]
+			.filter((value) => value.startsWith(valuePrefix))
+			.map((value) => ({ value: `agents ${value}`, label: `agents ${value}` }));
+	}
 	if (parts[0] === "sound" && parts.length === 2) {
 		const valuePrefix = parts[1] ?? "";
 		return ["setup"]
@@ -692,6 +707,49 @@ function registerUsageCommand(
 	});
 }
 
+export async function handleAgentsSetupCommand(
+	action: string | undefined,
+	ctx: ExtensionCommandContext,
+	setup: typeof setupJokerAgents = setupJokerAgents,
+	inspect: typeof inspectJokerAgents = inspectJokerAgents,
+): Promise<void> {
+	if (action !== "setup" && action !== "status") {
+		ctx.ui.notify("Usage: /osdy-pi agents setup|status", "warning");
+		return;
+	}
+	if (!ctx.hasUI) {
+		ctx.ui.notify("Agents setup requires an interactive confirmation.", "warning");
+		return;
+	}
+	const target = join(homedir(), ".pi", "agent");
+	if (action === "status") {
+		try {
+			const status = await inspect({ agentDir: target, cwd: ctx.cwd, env: process.env });
+			ctx.ui.notify(`Joker ${status.jokerInstalled ? "installed" : "not installed"}; ${status.gentleCount} Gentle entries; agent exclusion ${status.filtered ? "complete" : "incomplete"}.`, "info");
+		} catch (error) {
+			ctx.ui.notify(`Agents status unavailable: ${error instanceof Error ? error.message : "unknown error"}`, "warning");
+		}
+		return;
+	}
+	const confirmed = await ctx.ui.confirm(
+		"Set up Joker agents in normal Pi?",
+		`Target: ${join(target, "settings.json")}\nInstall npm:pi-subagents-j0k3r with Pi and exclude only -extensions/gentle-agents.ts from eligible Gentle packages. No isolated profile or credentials are changed.`,
+	);
+	if (!confirmed) return;
+	try {
+		const result = await setup({ agentDir: target, cwd: ctx.cwd, env: process.env });
+		ctx.ui.notify(`Joker agents ready (${result.gentleCount} Gentle entries checked). Reloading resources.`, "info");
+	} catch (error) {
+		ctx.ui.notify(`Agents setup failed: ${error instanceof Error ? error.message : "unknown error"}. Check settings and retry after resolving the error.`, "error");
+		return;
+	}
+	try {
+		await ctx.reload();
+	} catch {
+		ctx.ui.notify("Agents setup saved, but reload failed; restart Pi to apply the changes.", "warning");
+	}
+}
+
 function registerCommand(
 	pi: ExtensionAPI,
 	state: OsdyState,
@@ -709,6 +767,10 @@ function registerCommand(
 		getArgumentCompletions: getOsdyCommandCompletions,
 		handler: async (args, ctx) => {
 			const [action = "status", ...rest] = parseCommandArgs(args);
+			if (action === "agents") {
+				await handleAgentsSetupCommand(rest.length === 1 ? rest[0] : undefined, ctx);
+				return;
+			}
 			if (["enable", "on"].includes(action)) {
 				await enableOsdyPi(
 					pi,
@@ -797,7 +859,7 @@ function registerCommand(
 				return;
 			}
 			ctx.ui.notify(
-				`Usage: /osdy-pi enable|disable|on|off|status | mascot ${MASCOT_CHOICES.join("|")}|status | header ${HEADER_VARIANT_CHOICES.join("|")}|status | editor auto|extended|simple|on|off|toggle|status | sound setup | working-tree ... | diff`,
+				`Usage: /osdy-pi agents setup|status | enable|disable|on|off|status | mascot ${MASCOT_CHOICES.join("|")}|status | header ${HEADER_VARIANT_CHOICES.join("|")}|status | editor auto|extended|simple|on|off|toggle|status | sound setup | working-tree ... | diff`,
 				"warning",
 			);
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "osdy-pi",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "Osdy Pi package: themes, header, and custom editor for Pi.",
 	"license": "MIT",
 	"type": "module",