gentle-pi 2.3.0 → 2.4.0

package/tests/package-manifest.test.ts

@@ -9,11 +9,12 @@ import {
 	rmSync,
 	writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { applyModelConfig } from "../extensions/gentle-ai.ts";
+import { resolveGentlePiAgentHome } from "../lib/agent-home.ts";
 import { installSddAssets } from "../lib/sdd-preflight.ts";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -261,20 +262,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v2.5.0 runtime pin", () => {
+test("package verification binds the published Gentle AI v2.6.0 runtime pin", () => {
 	const installer = readFileSync(join(PACKAGE_ROOT, "scripts", "gentle-ai-installer.mjs"), "utf8");
 	const binary = readFileSync(join(PACKAGE_ROOT, "lib", "gentle-ai-binary.ts"), "utf8");
 	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
 
-	assert.match(installer, /INSTALLER_VERSION = "2\.5\.0"/);
+	assert.match(installer, /INSTALLER_VERSION = "2\.6\.0"/);
 	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
-	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:0nvTLJFAf9ruBDwTvi\+aDrWt\/dt\/GKvUP2cFVB6c2DI="/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:scGoZYnPHh4oCVqlcfQAOSpm22Ii5lmB0kBbiBKvNZk="/);
 	assert.match(installer, /GOTOOLCHAIN: "local"/);
 	assert.match(installer, /GOSUMDB: "sum\.golang\.org"/);
 	assert.match(binary, /GENTLE_AI_VERSION = INSTALLER_VERSION/);
 	assert.match(binary, /GO_SUMDB_SOURCE_BUILD/);
 	assert.match(binary, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM/);
-	assert.match(verifier, /v2\.5\.0/);
+	assert.match(verifier, /v2\.6\.0/);
 });
 
 
@@ -895,6 +896,22 @@ test("jd-fix-agent packaged allowlist includes write tools", () => {
 	}
 });
 
+test("sdd-explore packages its CodeGraph-enabled exploration allowlist", () => {
+	const agentPath = join(PACKAGE_ROOT, "assets", "agents", "sdd-explore.md");
+	const { name, tools } = readAgentDefinition(agentPath);
+
+	assert.equal(name, "sdd-explore");
+	assert.deepEqual(tools, [
+		"read",
+		"grep",
+		"find",
+		"codegraph",
+		"edit",
+		"write",
+		"mem_save",
+	]);
+});
+
 test("gentle-ai-worker packages the exact scoped writer contract", () => {
 	const agentsDir = join(PACKAGE_ROOT, "assets", "agents");
 	const agentPath = join(agentsDir, "gentle-ai-worker.md");
@@ -1055,6 +1072,103 @@ test("installSddAssets installs gentle-ai-worker with a loader-compatible scoped
 	);
 });
 
+test("agent home resolver centralizes Gentle and Pi agent-dir precedence", () => {
+	const explicitGentleHome = mkdtempSync(join(tmpdir(), "gentle-pi-resolver-explicit-"));
+	const piAgentDir = mkdtempSync(join(tmpdir(), "gentle-pi-resolver-pi-dir-"));
+
+	try {
+		assert.equal(
+			resolveGentlePiAgentHome({
+				GENTLE_PI_AGENT_HOME: explicitGentleHome,
+				PI_CODING_AGENT_DIR: piAgentDir,
+			}),
+			explicitGentleHome,
+		);
+		assert.equal(resolveGentlePiAgentHome({ PI_CODING_AGENT_DIR: piAgentDir }), piAgentDir);
+		assert.equal(resolveGentlePiAgentHome({}), join(homedir(), ".pi", "agent"));
+		assert.equal(
+			resolveGentlePiAgentHome({ GENTLE_PI_AGENT_HOME: "", PI_CODING_AGENT_DIR: piAgentDir }),
+			piAgentDir,
+			"an empty explicit override falls through like Pi Subagents does",
+		);
+		assert.equal(
+			resolveGentlePiAgentHome({ PI_CODING_AGENT_DIR: "" }),
+			join(homedir(), ".pi", "agent"),
+			"an empty PI_CODING_AGENT_DIR falls through like Pi Subagents does",
+		);
+	} finally {
+		rmSync(explicitGentleHome, { recursive: true, force: true });
+		rmSync(piAgentDir, { recursive: true, force: true });
+	}
+});
+
+test("asset installation uses PI_CODING_AGENT_DIR as the Pi agent home when no explicit Gentle override is set", () => {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+	const temporaryPiAgentDir = mkdtempSync(join(tmpdir(), "gentle-pi-agent-dir-"));
+	const explicitGentleHome = mkdtempSync(join(tmpdir(), "gentle-pi-explicit-home-"));
+
+	try {
+		delete process.env.GENTLE_PI_AGENT_HOME;
+		process.env.PI_CODING_AGENT_DIR = temporaryPiAgentDir;
+
+		installSddAssets(PACKAGE_ROOT, true);
+
+		const installedPath = join(temporaryPiAgentDir, "agents", "gentle-ai-explore.md");
+		assert.ok(existsSync(installedPath), "managed agents must install where Pi Subagents reads global definitions");
+		assert.deepEqual(readAgentDefinition(installedPath).tools, MANAGED_EXEMPLAR_TOOLS);
+		assert.ok(
+			!existsSync(join(explicitGentleHome, "agents", "gentle-ai-explore.md")),
+			"the explicit override fixture must still be untouched before it is selected",
+		);
+
+		process.env.GENTLE_PI_AGENT_HOME = explicitGentleHome;
+		installSddAssets(PACKAGE_ROOT, true);
+		assert.ok(
+			existsSync(join(explicitGentleHome, "agents", "gentle-ai-explore.md")),
+			"GENTLE_PI_AGENT_HOME remains the explicit test/operator override",
+		);
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousPiAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+		rmSync(temporaryPiAgentDir, { recursive: true, force: true });
+		rmSync(explicitGentleHome, { recursive: true, force: true });
+	}
+});
+
+test("global model routing uses PI_CODING_AGENT_DIR for package-installed agents", () => {
+	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
+	const previousPiAgentDir = process.env.PI_CODING_AGENT_DIR;
+	const temporaryPiAgentDir = mkdtempSync(join(tmpdir(), "gentle-pi-model-agent-dir-"));
+	const temporaryProject = mkdtempSync(join(tmpdir(), "gentle-pi-model-project-"));
+
+	try {
+		delete process.env.GENTLE_PI_AGENT_HOME;
+		process.env.PI_CODING_AGENT_DIR = temporaryPiAgentDir;
+		installSddAssets(PACKAGE_ROOT, true);
+
+		const result = applyModelConfig(temporaryProject, {
+			"gentle-ai-explore": { model: "provider/model", thinking: "high" },
+		});
+
+		assert.equal(result.updated, 2);
+		const config = JSON.parse(readFileSync(join(temporaryPiAgentDir, "subagents.json"), "utf8"));
+		assert.deepEqual(config.model_profiles["gentle-ai-explore"], {
+			model: "provider/model",
+			effort: "high",
+		});
+	} finally {
+		if (previousAgentHome === undefined) delete process.env.GENTLE_PI_AGENT_HOME;
+		else process.env.GENTLE_PI_AGENT_HOME = previousAgentHome;
+		if (previousPiAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = previousPiAgentDir;
+		rmSync(temporaryPiAgentDir, { recursive: true, force: true });
+		rmSync(temporaryProject, { recursive: true, force: true });
+	}
+});
+
 test("normal and forced installation copy generic agents with complete role contracts", () => {
 	const previousAgentHome = process.env.GENTLE_PI_AGENT_HOME;
 	const expectedTools = {
@@ -1146,8 +1260,8 @@ test("orchestrator routes generic roles without static RDD lens routing", () =>
 	}
 
 	const core = readFileSync(join(PACKAGE_ROOT, "assets", "orchestrator.md"), "utf8");
-	assert.match(core, /Gentle AI dynamically supplies runtime-specific RDD instructions/);
-	assert.match(core, /this package does not invent or fall back/);
+	assert.match(core, /injects the mirrored provider-bundle review execution contract/);
+	assert.match(core, /this package invents no lifecycle instructions/);
 });
 
 test("pi-pretty wrapper uses real package path resolution for pnpm symlink installs", () => {
@@ -1163,9 +1277,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v2.3.0 release package and runtime stop before publication", () => {
+test("v2.4.0 release package and runtime stop before publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "2.3.0", "the release manifest must remain explicitly pinned to v2.3.0");
+	assert.equal(packageJson.version, "2.4.0", "the release manifest must remain explicitly pinned to v2.4.0");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run check:provider-contract && pnpm run test:harness",

package/tests/provider-contract-bundle.test.ts

@@ -35,6 +35,16 @@ function fixtureEntries(): Map<string, Buffer> {
 	return new Map(FIXTURE_PATHS.map((path) => [path, readFileSync(join(FIXTURE_ROOT, path))]));
 }
 
+// Fixture provenance: the real gentle-ai provider contract bundle 1.2.0
+// release archive (contract semver 1.2.0), extracted. Adds `orchestration`
+// to the manifest: gentle-pi#560 / gentle-ai#4056, #4057.
+const FIXTURE_1_2_0_ROOT = join(import.meta.dirname, "fixtures", "provider-contract-bundle", "v1.2.0");
+const FIXTURE_1_2_0_PATHS = [...FIXTURE_PATHS, "orchestration/pi.md"] as const;
+
+function fixture120Entries(): Map<string, Buffer> {
+	return new Map(FIXTURE_1_2_0_PATHS.map((path) => [path, readFileSync(join(FIXTURE_1_2_0_ROOT, path))]));
+}
+
 function sha256Hex(bytes: Buffer): string {
 	return createHash("sha256").update(bytes).digest("hex");
 }
@@ -177,11 +187,25 @@ test("generated baselines project roles, capabilities, and runtime registration
 	assert.equal(capabilities.transport_capability, PROVIDER_TRANSPORT_CAPABILITY);
 	assert.deepEqual(capabilities.mandatory_capabilities, [PROVIDER_TRANSPORT_CAPABILITY]);
 	assert.equal(capabilities.pi_registered, true);
+	assert.deepEqual(capabilities.orchestration, []);
 	// Byte determinism: regenerating from the same bundle is identical.
 	const again = generateProviderContractBaselines(verifyProviderContractBundleTree(FIXTURE_ROOT));
 	assert.deepEqual([...again.entries()], [...baselines.entries()]);
 });
 
+test("generated 1.2.0 baselines record the mirrored orchestration entry", () => {
+	const bundle = verifyProviderContractBundleTree(FIXTURE_1_2_0_ROOT);
+	const baselines = generateProviderContractBaselines(bundle);
+	const capabilities = JSON.parse(baselines.get("provider-capabilities.baseline.json") as string) as { orchestration: { runtime: string; path: string; sha256: string }[] };
+	assert.deepEqual(capabilities.orchestration, [
+		{
+			runtime: PI_RUNTIME_IDENTITY,
+			path: "orchestration/pi.md",
+			sha256: bundle.entrySha256.get("orchestration/pi.md"),
+		},
+	]);
+});
+
 // --- inventory and hash rejections ---------------------------------------------
 
 test("rejects a ninth file in the inventory", () => {
@@ -315,6 +339,58 @@ test("rejects a schema whose $id does not match the manifest result schema id",
 	);
 });
 
+// --- orchestration (contract 1.2.0) -------------------------------------------------
+
+test("verifies the 1.2.0 fixture tree and exposes the mirrored pi orchestration text", () => {
+	const bundle = verifyProviderContractBundleTree(FIXTURE_1_2_0_ROOT);
+	assert.equal(bundle.contractSemver, "1.2.0");
+	assert.deepEqual([bundle.major, bundle.minor, bundle.patch], [1, 2, 0]);
+	assert.equal(bundle.entries.size, 9);
+	assert.deepEqual([...bundle.orchestration.keys()], [PI_RUNTIME_IDENTITY]);
+	const piText = bundle.orchestration.get(PI_RUNTIME_IDENTITY);
+	assert.equal(piText, readFileSync(join(FIXTURE_1_2_0_ROOT, "orchestration/pi.md"), "utf8"));
+	assert.equal(bundle.entrySha256.get("orchestration/pi.md"), sha256Hex(readFileSync(join(FIXTURE_1_2_0_ROOT, "orchestration/pi.md"))));
+});
+
+test("rejects a 1.2.0 manifest without the required orchestration array", () => {
+	assertRejects(
+		withManifest(fixture120Entries(), (manifest) => {
+			delete manifest.orchestration;
+		}),
+		"manifest.orchestration is required from contract 1.2.0",
+	);
+});
+
+test("rejects a 1.2.0 orchestration entry whose runtime is not registered in manifest.runtimes", () => {
+	assertRejects(
+		withManifest(fixture120Entries(), (manifest) => {
+			const orchestration = manifest.orchestration as { runtime: string; file: { path: string } }[];
+			orchestration[0]!.runtime = "aider";
+			orchestration[0]!.file.path = "orchestration/aider.md";
+		}),
+		'manifest.orchestration[0].runtime "aider" is not registered in manifest.runtimes',
+	);
+});
+
+test("rejects a 1.2.0 orchestration entry whose file bytes do not match its manifest SHA-256", () => {
+	const entries = fixture120Entries();
+	const tampered = Buffer.from(entries.get("orchestration/pi.md") as Buffer);
+	tampered[tampered.length - 2] = 0x20;
+	entries.set("orchestration/pi.md", tampered);
+	assertRejects(entries, "does not match its manifest SHA-256");
+});
+
+test("rejects an orchestration array on a 1.1.0 manifest", () => {
+	assertRejects(
+		withManifest(fixtureEntries(), (manifest) => {
+			manifest.orchestration = [
+				{ runtime: PI_RUNTIME_IDENTITY, file: { path: "orchestration/pi.md", sha256: "0".repeat(64) } },
+			];
+		}),
+		"manifest.orchestration is not part of contract 1.1.0",
+	);
+});
+
 // --- archive safety ------------------------------------------------------------------
 
 test("rejects a tar entry that escapes the bundle root", () => {

package/tests/provider-contract-mirror.test.ts

@@ -27,6 +27,10 @@ const FIXTURE_PATHS = [
 	"vectors/targeted-validator.json",
 ] as const;
 
+// Fixture provenance: the real gentle-ai provider contract bundle 1.2.0
+// release archive, extracted. gentle-pi#560 / gentle-ai#4056, #4057.
+const FIXTURE_1_2_0_ROOT = join(import.meta.dirname, "fixtures", "provider-contract-bundle", "v1.2.0");
+
 interface LockRecord {
 	schema: string;
 	acquisition: string;
@@ -105,6 +109,21 @@ test("mirrors a verified local bundle tree and the offline drift check passes",
 	});
 });
 
+test("mirrors a verified local 1.2.0 bundle tree, including its orchestration entry, and the offline drift check passes", () => {
+	withTemporaryRoot((packageRoot) => {
+		mirrorProviderContractBundle(FIXTURE_1_2_0_ROOT, packageRoot);
+		const lockPath = join(packageRoot, PROVIDER_CONTRACT_MIRROR_ROOT, PROVIDER_CONTRACT_LOCK_FILE);
+		const lock = JSON.parse(readFileSync(lockPath, "utf8")) as LockRecord;
+		assert.equal(lock.contract_semver, "1.2.0");
+		assert.equal(Object.keys(lock.entries).length, 9);
+		assert.ok("orchestration/pi.md" in lock.entries, "the mirrored lock must record orchestration/pi.md");
+		const mirrored = join(packageRoot, PROVIDER_CONTRACT_MIRROR_ROOT, "v1.2.0", "bundle", "orchestration", "pi.md");
+		assert.ok(existsSync(mirrored), "orchestration/pi.md must be mirrored");
+		assert.deepEqual(readFileSync(mirrored), readFileSync(join(FIXTURE_1_2_0_ROOT, "orchestration", "pi.md")));
+		assert.deepEqual(checkProviderContractMirror(packageRoot), []);
+	});
+});
+
 test("mirrors a verified local archive and records the archive digest in the lock", () => {
 	withTemporaryRoot((packageRoot) => {
 		const archivePath = join(packageRoot, "gentle-ai-review-provider-contract-1.1.0.tar.gz");