@plannotator/pi-extension 0.28.38 → 0.28.39

package/server/agent-jobs-ask-ai-child.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Pi (Node) mirror of packages/server/agent-jobs-ask-ai-child.test.ts: every
+ * agent job the Pi review server starts (code review, Code Tour, Guided
+ * Review; Claude, Codex and the marker engines) runs with Plannotator's own
+ * integration off: PLANNOTATOR_ASK_AI_CHILD=1 with the Inbox tool and agent
+ * tool switches at 0 in its env, the Codex `-c` override that turns the Inbox
+ * MCP server off, and the Claude disallow of `mcp__plannotator-inbox`.
+ *
+ * Each job is built by its real (vendored) command builder and spawned through
+ * the real POST /api/agents/jobs handler. Fake `claude`, `codex` and
+ * `opencode` on PATH (never a real CLI) record the env and argv they get.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NO_BROWSER } from "../../../tests/helpers/no-browser.ts";
+import { buildClaudeCommand } from "../generated/claude-review.ts";
+import { buildCodexCommand, generateOutputPath } from "../generated/codex-review.ts";
+import { buildGuideClaudeCommand, buildGuideCodexCommand, generateGuideOutputPath } from "../generated/guide-review.ts";
+import { buildMarkerCommand, MARKER_ENGINES } from "../generated/marker-review.ts";
+import { buildTourClaudeCommand, buildTourCodexCommand, generateTourOutputPath } from "../generated/tour-review.ts";
+import { createAgentJobHandler, type AgentJobHandlerOptions } from "./agent-jobs.ts";
+import { requestUrl } from "./helpers.ts";
+
+const SWITCHES = ["PLANNOTATOR_ASK_AI_CHILD", "PLANNOTATOR_INBOX_TOOL", "PLANNOTATOR_AGENT_TOOL"] as const;
+const SANDBOX_KEYS = ["PATH", "HOME", "CODEX_HOME", "PLANNOTATOR_DATA_DIR", "PLANNOTATOR_INBOX_CONNECT", "NO_BROWSER", ...SWITCHES];
+
+type Built = Awaited<ReturnType<NonNullable<AgentJobHandlerOptions["buildCommand"]>>>;
+type JobRecord = { env: { [key: string]: string | null }; argv: string[] };
+
+let root = "";
+let saved: { [key: string]: string | undefined } = {};
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "plannotator-pi-job-ask-ai-child-"));
+	const bin = join(root, "bin");
+	for (const dir of [bin, join(root, "home"), join(root, "codex-home"), join(root, "data"), join(root, "cwd")]) mkdirSync(dir);
+	for (const name of ["claude", "codex", "opencode"]) {
+		const fake = join(bin, name);
+		writeFileSync(fake, [
+			`#!${process.execPath}`,
+			`const env = Object.fromEntries(${JSON.stringify(SWITCHES)}.map((k) => [k, process.env[k] ?? null]));`,
+			`require("node:fs").writeFileSync(${JSON.stringify(join(root, "record.json"))}, JSON.stringify({ env, argv: process.argv.slice(2) }));`,
+		].join("\n"));
+		chmodSync(fake, 0o755);
+	}
+	saved = Object.fromEntries(SANDBOX_KEYS.map((key) => [key, process.env[key]]));
+	// Only the fakes and the system tools: no real agent CLI is reachable.
+	process.env.PATH = `${bin}:/usr/bin:/bin`;
+	process.env.HOME = join(root, "home");
+	process.env.CODEX_HOME = join(root, "codex-home");
+	process.env.PLANNOTATOR_DATA_DIR = join(root, "data");
+	process.env.PLANNOTATOR_INBOX_CONNECT = "0";
+	process.env.NO_BROWSER = NO_BROWSER;
+	// The person's own switches, which a job must override, not inherit.
+	process.env.PLANNOTATOR_INBOX_TOOL = "1";
+	process.env.PLANNOTATOR_AGENT_TOOL = "1";
+	delete process.env.PLANNOTATOR_ASK_AI_CHILD;
+});
+
+afterEach(() => {
+	for (const [key, value] of Object.entries(saved)) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+	}
+	rmSync(root, { recursive: true, force: true });
+});
+
+/** Launch one job through the real handler; resolve with what the fake recorded. */
+async function runJob(provider: string, build: (cwd: string) => Promise<Built>, engine?: string): Promise<JobRecord> {
+	let done: (() => void) | undefined;
+	const completed = new Promise<void>((resolve) => {
+		done = resolve;
+	});
+	const handler = createAgentJobHandler({
+		mode: "review",
+		getServerUrl: () => "http://localhost:1234",
+		getCwd: () => join(root, "cwd"),
+		buildCommand: () => build(join(root, "cwd")),
+		async onJobComplete() {
+			done?.();
+		},
+	});
+	const server = createServer(async (req, res) => {
+		if (!(await handler.handle(req, res, requestUrl(req)))) {
+			res.writeHead(404);
+			res.end();
+		}
+	});
+	try {
+		await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+		const address = server.address();
+		if (!address || typeof address === "string") throw new Error("no port");
+		const res = await fetch(`http://127.0.0.1:${address.port}/api/agents/jobs`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ provider, ...(engine && { engine }) }),
+		});
+		expect(res.status).toBe(201);
+		await completed;
+		return JSON.parse(readFileSync(join(root, "record.json"), "utf8")) as JobRecord;
+	} finally {
+		handler.killAll();
+		await new Promise<void>((resolve) => server.close(() => resolve()));
+	}
+}
+
+const claudeJob = (command: string[], stdinPrompt: string, cwd: string): Built => ({ command, stdinPrompt, cwd, captureStdout: true, engine: "claude" });
+
+const JOBS: Array<{ name: string; provider: string; engine?: string; build: (cwd: string) => Promise<Built> }> = [
+	{ name: "code review, Claude", provider: "claude", build: async (cwd) => { const b = buildClaudeCommand("review"); return claudeJob(b.command, b.stdinPrompt, cwd); } },
+	{ name: "code review, Codex", provider: "codex", build: async (cwd) => { const outputPath = generateOutputPath(); return { command: await buildCodexCommand({ cwd, outputPath, prompt: "review" }), outputPath, cwd }; } },
+	{ name: "code review, OpenCode", provider: "opencode", build: async (cwd) => ({ command: buildMarkerCommand(MARKER_ENGINES.opencode, "review", undefined, cwd).command, cwd, captureStdout: true }) },
+	{ name: "Code Tour, Claude", provider: "tour", engine: "claude", build: async (cwd) => { const b = buildTourClaudeCommand("tour"); return claudeJob(b.command, b.stdinPrompt, cwd); } },
+	{ name: "Code Tour, Codex", provider: "tour", engine: "codex", build: async (cwd) => { const outputPath = generateTourOutputPath(); return { command: await buildTourCodexCommand({ cwd, outputPath, prompt: "tour" }), outputPath, cwd, engine: "codex" }; } },
+	{ name: "Guided Review, Claude", provider: "guide", engine: "claude", build: async (cwd) => { const b = buildGuideClaudeCommand("guide"); return claudeJob(b.command, b.stdinPrompt, cwd); } },
+	{ name: "Guided Review, Codex", provider: "guide", engine: "codex", build: async (cwd) => { const outputPath = generateGuideOutputPath(); return { command: await buildGuideCodexCommand({ cwd, outputPath, prompt: "guide" }), outputPath, cwd, engine: "codex" }; } },
+	{ name: "Guided Review, OpenCode", provider: "guide", engine: "opencode", build: async (cwd) => ({ command: buildMarkerCommand(MARKER_ENGINES.opencode, "guide", undefined, cwd).command, cwd, captureStdout: true, engine: "opencode" }) },
+];
+
+describe("pi agent jobs never load Plannotator's own integration", () => {
+	for (const job of JOBS) {
+		test(`${job.name}: the agent gets the marker and both switches off`, async () => {
+			if (process.platform === "win32") return; // the fakes rely on a shebang
+			const { env, argv } = await runJob(job.provider, job.build, job.engine);
+			expect(env).toEqual({ PLANNOTATOR_ASK_AI_CHILD: "1", PLANNOTATOR_INBOX_TOOL: "0", PLANNOTATOR_AGENT_TOOL: "0" });
+			// Only the job's env changed: the server's (the person's session) did not.
+			expect(process.env.PLANNOTATOR_ASK_AI_CHILD).toBeUndefined();
+			expect(process.env.PLANNOTATOR_INBOX_TOOL).toBe("1");
+
+			if (job.name.endsWith("Codex")) {
+				// Codex starts a stdio MCP server with none of this env, so the
+				// Inbox server is turned off by a global `-c`, before `exec`.
+				const at = argv.findIndex((arg) => arg.startsWith("mcp_servers.plannotator-inbox="));
+				expect(at).toBeGreaterThan(0);
+				expect(argv[at - 1]).toBe("-c");
+				expect(argv[at]).toContain("enabled=false");
+				expect(at).toBeLessThan(argv.indexOf("exec"));
+			}
+			if (job.name.endsWith("Claude")) {
+				const disallowed = argv[argv.indexOf("--disallowedTools") + 1]!.split(",");
+				expect(disallowed).toContain("mcp__plannotator-inbox");
+				expect(argv).toContain("--strict-mcp-config");
+			}
+		});
+	}
+});

package/server/agent-jobs.ts

@@ -26,6 +26,7 @@ import {
 } from "../generated/agent-jobs.ts";
 import { resolveGuideLaunchInstructions } from "../generated/guide-instructions-store.ts";
 import { gitColorFreeEnvironment } from "../generated/review-core.ts";
+import { askAiChildEnv } from "../generated/ai/providers/ask-ai-env.ts";
 import { ghAccountEnvForPRUrl } from "../generated/pr-github-account.ts";
 import type { GuideLaunchReview } from "../generated/guide-format.ts";
 import { allowedToolsOf, CLAUDE_SHELL_BLOCKED_WARNING, detectClaudeShellBlocked, disallowedToolsOf, formatClaudeLogEvent } from "../generated/claude-review.ts";
@@ -312,7 +313,10 @@ export function createAgentJobHandler(options: AgentJobHandlerOptions) {
 					"pipe",
 				],
 				env: {
-					...process.env,
+					// The live env with Plannotator's own integration off (the Inbox MCP,
+					// the agent tool, the plan and Stop hooks). No job uses it: each
+					// returns its result on stdout or in its output file (ask-ai-env.ts).
+					...askAiChildEnv(),
 					// The agent runs `git diff` / `git log` itself through a pipe; keep a
 					// user's `color.diff = always` from filling its context with ANSI
 					// escapes (#1661).

package/server/serverReview.ts

@@ -252,6 +252,7 @@ import {
 import type { SemanticDiffAvailability, SemanticDiffResponse } from "../generated/semantic-diff-types.ts";
 import { CallFlowService } from "../generated/call-flow.ts";
 import { CallFlowInstallCoordinator, callFlowInstallOriginAllowed } from "../generated/call-flow-install.ts";
+import type { CallFlowInstallCoordinatorOptions } from "../generated/call-flow-install.ts";
 import { parseCallFlowInstallRequest, resolveCallFlowInstallTargets } from "../generated/call-flow-languages.ts";
 import type { CallFlowResponse } from "../generated/call-flow-types.ts";
 import { discoverCuratedSkills, resolveRequestedReviewProfile, listAllSkills, enableReviewSkill } from "../generated/review-skill-loader.ts";
@@ -376,6 +377,8 @@ export async function startReviewServer(options: {
 	repoFilesLazyThreshold?: number;
 	/** Tests only: how often a polled live listing looks (default `REPO_LIVE_POLL_MS`). */
 	repoLivePollMs?: number;
+	/** Tests only: the Call flow install and Node preflight, so a test never starts a real install. */
+	callFlowInstall?: Pick<CallFlowInstallCoordinatorOptions, "install" | "preflight">;
 	/** Tests: run the hover cards' `gh` / `glab` through this instead of the real ones (ref-cards.ts). */
 	refRunner?: RefRunner;
 	/** "Ask this session": the in-process bridge to the Pi session that opened this review. */
@@ -709,6 +712,7 @@ export async function startReviewServer(options: {
 	// invalidates the service's 30 second runtime probe cache so the very
 	// next capability advert resolves available without a server restart.
 	const callFlowInstall = new CallFlowInstallCoordinator({
+		...options.callFlowInstall,
 		onSettled: (ok) => {
 			if (ok) callFlowService.invalidateRuntimeState();
 		},

package/skills/plannotator/SKILL.md

@@ -182,7 +182,7 @@ plannotator inbox status [--json] | stop | restart
 
 The Plannotator Inbox is one local window per machine where you leave the person messages, `:::question` blocks they answer with a click, files to annotate and guided reviews. Nothing blocks: you send, then keep working or end your turn.
 
-- Use it for a decision only they can make (a `:::question` block, then go on with work that does not depend on it), long work you finished (one short summary, with the files to look at in `attachments`), or when they ask. A decision you sent to the Inbox stays there: when the person writes in the chat, say there what waits (a short summary and the thread's link), but never also ask it in the chat with a blocking question tool (AskUserQuestion or similar). Ask in the chat only about something new they raised there that needs no pictures or files, or when they ask. Be proactive about Inbox updates and about replying to the person through the Inbox when you think they would want you to. Don't withhold important updates or decisions, and don't batch updates to send later: proactivity is better than procrastination. Use a review (plan review, `annotate`, `review`) when you need a decision on this document or diff before you go on.
+- Use it for a decision only they can make (a `:::question` block, then go on with work that does not depend on it), long work you finished (one short summary, with the files to look at in `attachments`), or when they ask. One thread per work stream, unless the person says otherwise. A decision you sent to the Inbox stays there: when the person writes in the chat, say there what waits (a short summary and the thread's link), but never also ask it in the chat with a blocking question tool (AskUserQuestion or similar). Ask in the chat only about something new they raised there that needs no pictures or files, or when they ask. Be proactive about Inbox updates and about replying to the person through the Inbox when you think they would want you to. Don't withhold important updates or decisions, and don't batch updates to send later: proactivity is better than procrastination. Use a review (plan review, `annotate`, `review`) when you need a decision on this document or diff before you go on.
 - If you have a `plannotator_inbox` tool, use it; otherwise use the stdio MCP server `plannotator inbox mcp`. When send_message says the person's reply arrives in this session by itself, end your turn instead of waiting; otherwise call wait_for_reply when you need the answer.
 - Run `plannotator inbox --help` once and read it before your first use: it is the full guide (tools and arguments, threads, where replies go, question syntax, replacing questions, connecting other agents).
 - Never run `plannotator inbox` just to send: calls start a stopped Inbox in the background, and bare `plannotator inbox` opens the window for the person. `--tailscale` is the person's choice; never add it. `plannotator inbox status` only reads; never run `plannotator inbox stop` or `restart` unless the person asks.
@@ -257,8 +257,8 @@ Recommended: Local only, purged after 30 days
   - Add a screenshot (`![alt](path)`) for anything visual.
   - Link a file that shows it better (a plan, a mock): `[the mock](mock.html)`. In the Inbox, attach it too; the link opens it beside the thread.
 - Choices: `- [ ] label`, optionally `- [ ] label — why`. The reviewer can also answer "Other", add a note, or skip.
-- `Recommended: <label>` marks yours (`A, B and C` on `:::question-multi`); other text shows as one more answer, tagged Recommended.
-- Ask only what you cannot decide alone, about 8 a round at most. Do not ask rhetorical questions or questions the codebase answers.
+- `Recommended: <label>` marks yours (`A, B and C` on `:::question-multi`); other text is one more answer, tagged Recommended. Keep A, B, C order.
+- Ask only what you cannot decide alone, about 8 a round. Do not ask rhetorical questions or questions the codebase answers.
 - `- [x]` marks a settled choice. On resubmit, check the chosen answer, or drop the block and state the decision in prose.
 - Leave blank lines between the parts so the block reads well on GitHub.
 - Each answer comes back under its question (`### Q2. <question> (line N)`) as `Answer: <choice>`, marked `(your recommendation)` when the reviewer took yours, or as `Other: …`, free text in a quote, or `Skipped`, plus any `Note:`. A question you marked `- [x]` is settled and only comes back if the reviewer changed it or added a note.