pi-plans 0.5.7 → 0.7.0

package/src/global-state.ts

@@ -0,0 +1,304 @@
+/**
+ * Global (user-level) pi-plans configuration.
+ *
+ * The reviewer role lives here as the single source of truth (v0.7.0): one
+ * file, shared across every workspace, confirmed once. The file is
+ * `~/.pi/pi-plans/config.json` — a standalone pi-plans file, NOT Pi's own
+ * `~/.pi/agent/settings.json` — and its directory can be overridden with
+ * `PI_PLANS_GLOBAL_DIR` (tests, CI, and bench containers rely on this).
+ *
+ * Workspace `.git/pi-plans/config.json` keeps a read-tolerated legacy
+ * `reviewer` block (pre-0.7.0). It is honored read-only until the first
+ * mutating state call migrates it (see `seedGlobalRoleFromLegacy`) and is
+ * stripped from the workspace config on the next write.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export class GlobalStateError extends Error {}
+
+export const GLOBAL_DIR_ENV = "PI_PLANS_GLOBAL_DIR";
+
+/** Test hook so tests can pin the clock (run-id dedup etc.). Shared with
+ * state.ts via re-export so both modules stamp identical timestamps. */
+export const testHooks: { now: () => Date } = { now: () => new Date() };
+
+export function utcNow(): string {
+	return testHooks.now().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+export type ThinkingLevelValue = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/** Valid stored thinking levels. `null` means "default": the spawned child
+ * gets no `--thinking` flag and resolves its own default chain (per-model
+ * settings → defaultThinkingLevel → medium). */
+export const VALID_THINKING_LEVELS = new Set<string>([
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+]);
+
+export const VALID_ROLE_MODES = new Set(["delegated-subagent", "current-session"]);
+
+export interface GlobalRoleConfig {
+	mode: string;
+	/** Exact `provider/model` selector. `null` = unconfirmed (delegated mode
+	 * refuses to spawn until a concrete selector is confirmed; the inherit
+	 * entry point was removed in v0.7.0). */
+	model_selector: string | null;
+	/** `null` = default (omit `--thinking`); "off" is an explicit level and
+	 * deliberately distinct from null. */
+	thinking_level: ThinkingLevelValue | null;
+	name_prefix: string;
+	confirmed_at: string | null;
+}
+
+export interface GlobalConfig {
+	schema: 1;
+	reviewer: GlobalRoleConfig;
+}
+
+export const DEFAULT_GLOBAL_ROLE: GlobalRoleConfig = {
+	mode: "delegated-subagent",
+	model_selector: null,
+	thinking_level: null,
+	name_prefix: "pi-plans-reviewer",
+	confirmed_at: null,
+};
+
+export const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
+	schema: 1,
+	reviewer: structuredClone(DEFAULT_GLOBAL_ROLE),
+};
+
+/** Resolve the global config directory: `$PI_PLANS_GLOBAL_DIR` when set,
+ * otherwise `~/.pi/pi-plans`. */
+export function resolveGlobalDir(): string {
+	const override = process.env[GLOBAL_DIR_ENV];
+	if (override && override.trim() !== "") return path.resolve(override);
+	return path.join(os.homedir(), ".pi", "pi-plans");
+}
+
+export function resolveGlobalConfigPath(): string {
+	return path.join(resolveGlobalDir(), "config.json");
+}
+
+export interface GlobalLoadResult {
+	config: GlobalConfig;
+	/** Load-time diagnostics (corrupt file, invalid fields). */
+	notices: string[];
+	/** True when no global file exists yet (defaults returned). */
+	fresh: boolean;
+	/** True when the file exists but was unusable (never clobbered). */
+	corrupt: boolean;
+}
+
+/** Normalize an unknown value into a GlobalRoleConfig, collecting
+ * diagnostics. Invalid fields fall back to defaults; the file is never
+ * rewritten by a read. */
+export function normalizeGlobalRole(
+	raw: unknown,
+	notices: string[],
+	label: string,
+): GlobalRoleConfig {
+	const role = structuredClone(DEFAULT_GLOBAL_ROLE);
+	if (raw === null || raw === undefined || typeof raw !== "object") {
+		notices.push(`${label}: missing reviewer block; using defaults`);
+		return role;
+	}
+	const record = raw as Record<string, unknown>;
+	if (typeof record.mode === "string") {
+		if (VALID_ROLE_MODES.has(record.mode)) {
+			role.mode = record.mode;
+		} else {
+			notices.push(`${label}: invalid reviewer mode ${JSON.stringify(record.mode)}; using default`);
+		}
+	}
+	if (record.model_selector === null) {
+		role.model_selector = null;
+	} else if (typeof record.model_selector === "string" && record.model_selector.trim() !== "") {
+		role.model_selector = record.model_selector;
+	} else if (record.model_selector !== undefined) {
+		notices.push(`${label}: invalid model_selector; treating as unconfirmed`);
+	}
+	if (record.thinking_level === null || record.thinking_level === undefined) {
+		role.thinking_level = null;
+	} else if (typeof record.thinking_level === "string" && VALID_THINKING_LEVELS.has(record.thinking_level)) {
+		role.thinking_level = record.thinking_level as ThinkingLevelValue;
+	} else {
+		notices.push(`${label}: invalid thinking_level ${JSON.stringify(record.thinking_level)}; using default`);
+	}
+	if (typeof record.name_prefix === "string" && record.name_prefix.trim() !== "") {
+		role.name_prefix = record.name_prefix;
+	}
+	if (typeof record.confirmed_at === "string" && record.confirmed_at !== "") {
+		role.confirmed_at = record.confirmed_at;
+	}
+	return role;
+}
+
+/** Read the global config. Never writes; a corrupt or wrong-schema file is
+ * reported and left untouched (defaults are used for this call only). */
+export function loadGlobalConfig(): GlobalLoadResult {
+	const configPath = resolveGlobalConfigPath();
+	if (!existsSync(configPath)) {
+		return { config: structuredClone(DEFAULT_GLOBAL_CONFIG), notices: [], fresh: true, corrupt: false };
+	}
+	const notices: string[] = [];
+	let data: unknown;
+	try {
+		data = JSON.parse(readFileSync(configPath, "utf8"));
+	} catch (error) {
+		notices.push(
+			`global config is invalid JSON (${(error as Error).message}); using defaults and leaving ${configPath} untouched`,
+		);
+		return { config: structuredClone(DEFAULT_GLOBAL_CONFIG), notices, fresh: false, corrupt: true };
+	}
+	if (data === null || typeof data !== "object" || (data as Record<string, unknown>).schema !== 1) {
+		notices.push(
+			`global config schema is unsupported; using defaults and leaving ${configPath} untouched`,
+		);
+		return { config: structuredClone(DEFAULT_GLOBAL_CONFIG), notices, fresh: false, corrupt: true };
+	}
+	const reviewer = normalizeGlobalRole((data as Record<string, unknown>).reviewer, notices, "global config");
+	return { config: { schema: 1, reviewer }, notices, fresh: false, corrupt: false };
+}
+
+/** Atomic write with a unique temp name (concurrent writers never collide
+ * on a shared `.tmp` path). */
+export function writeGlobalConfig(config: GlobalConfig): void {
+	const configPath = resolveGlobalConfigPath();
+	mkdirSync(path.dirname(configPath), { recursive: true });
+	const tmp = `${configPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+	writeFileSync(tmp, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+	renameSync(tmp, configPath);
+}
+
+/**
+ * Gate predicate shared by every spawn site: current-session runs in the
+ * main session (no model needed); delegated-subagent requires a confirmed,
+ * CONCRETE `provider/model` selector (the inherit entry point was removed —
+ * a null selector can never pass confirmation).
+ */
+export function reviewerReady(role: GlobalRoleConfig): boolean {
+	if (role.mode === "current-session") return true;
+	return role.confirmed_at !== null && role.model_selector !== null;
+}
+
+export interface SetGlobalRoleOptions {
+	mode?: string;
+	/** Exact "provider/model" selector; "inherit" resets BOTH the selector
+	 * and the confirmation (a pure reset, never a confirmable state). */
+	modelSelector?: string;
+	/** Level from VALID_THINKING_LEVELS, or "default" for null (omit
+	 * --thinking). Omitted = keep, except when modelSelector changes
+	 * concurrently, which resets the level. */
+	thinkingLevel?: string;
+	confirmed?: boolean;
+	resetConfirmation?: boolean;
+}
+
+/** Apply set-role options to a role snapshot. Throws GlobalStateError on
+ * invalid combinations BEFORE any mutation lands on disk. */
+export function applyGlobalRoleOptions(base: GlobalRoleConfig, options: SetGlobalRoleOptions): GlobalRoleConfig {
+	const role = { ...base };
+	if (options.mode !== undefined && !VALID_ROLE_MODES.has(options.mode)) {
+		throw new GlobalStateError(`mode must be one of ${[...VALID_ROLE_MODES].sort().join(", ")}`);
+	}
+	if (options.confirmed && options.resetConfirmation) {
+		throw new GlobalStateError("confirmed and resetConfirmation are mutually exclusive");
+	}
+	if (options.thinkingLevel !== undefined) {
+		if (options.thinkingLevel === "default") {
+			role.thinking_level = null;
+		} else if (!VALID_THINKING_LEVELS.has(options.thinkingLevel)) {
+			throw new GlobalStateError(
+				`thinkingLevel must be one of ${[...VALID_THINKING_LEVELS].join(", ")}, or "default"`,
+			);
+		} else {
+			role.thinking_level = options.thinkingLevel as ThinkingLevelValue;
+		}
+	}
+	if (options.modelSelector !== undefined) {
+		if (options.modelSelector === "inherit") {
+			if (options.confirmed) {
+				throw new GlobalStateError(
+					"'inherit' is a reset and cannot be combined with confirmed; confirm an exact provider/model selector instead",
+				);
+			}
+			role.model_selector = null;
+			role.confirmed_at = null;
+		} else {
+			role.model_selector = options.modelSelector;
+			// Switching models invalidates a stored level (the level domain is
+			// per-model); callers that keep the level pass it explicitly.
+			if (options.thinkingLevel === undefined) role.thinking_level = null;
+		}
+	}
+	if (options.mode !== undefined) role.mode = options.mode;
+	if (options.confirmed) {
+		if (role.mode === "delegated-subagent" && role.model_selector === null) {
+			throw new GlobalStateError(
+				"confirmed requires an exact provider/model selector for delegated-subagent; use the first-use model panel or pass modelSelector",
+			);
+		}
+		role.confirmed_at = utcNow();
+	}
+	if (options.resetConfirmation) role.confirmed_at = null;
+	return role;
+}
+
+export interface SetGlobalRoleResult {
+	global: GlobalConfig;
+	/** Load-time diagnostics merged from the initial load. */
+	notices: string[];
+}
+
+/** Load → apply → write the global reviewer role. Global writes never touch
+ * workspace state (no git-init side effects, F-013). */
+export function setGlobalRole(options: SetGlobalRoleOptions): SetGlobalRoleResult {
+	const loaded = loadGlobalConfig();
+	const reviewer = applyGlobalRoleOptions(loaded.config.reviewer, options);
+	const config: GlobalConfig = { schema: 1, reviewer };
+	writeGlobalConfig(config);
+	return { global: config, notices: loaded.notices };
+}
+
+/** True when a legacy workspace reviewer block carries real user intent
+ * (anything but the scaffold defaults). Scaffolded blocks are dropped
+ * silently; intent blocks seed the global file exactly once (the first
+ * touched workspace wins, Q-1=A). */
+export function legacyReviewerHasUserIntent(raw: unknown): boolean {
+	if (raw === null || raw === undefined || typeof raw !== "object") return false;
+	const record = raw as Record<string, unknown>;
+	if (record.confirmed_at !== null && record.confirmed_at !== undefined) return true;
+	if (typeof record.model_selector === "string" && record.model_selector.trim() !== "") return true;
+	if (typeof record.mode === "string" && record.mode !== "delegated-subagent") return true;
+	return false;
+}
+
+/** Seed a global role from a legacy workspace reviewer block (v0.6.x). A
+ * confirmed-inherit block (model_selector null) loses its confirmation —
+ * under v0.7.0 semantics a delegated reviewer needs a concrete model, so
+ * the first refine re-asks once with the native panel (decision 8). */
+export function seedGlobalRoleFromLegacy(raw: unknown): { role: GlobalRoleConfig; notices: string[] } {
+	const notices: string[] = [];
+	const role = normalizeGlobalRole(raw, notices, "legacy workspace reviewer");
+	role.thinking_level = null; // pre-0.7.0 blocks never carried a level
+	if (role.model_selector === null) role.confirmed_at = null;
+	return { role, notices };
+}
+
+export function globalMigratedNotice(globalPath: string): string {
+	return `migrated the reviewer role from workspace config.json to the global config (${globalPath}); the workspace reviewer key is removed on the next config write`;
+}
+
+export function globalIgnoredNotice(globalPath: string): string {
+	return `workspace config.json still carries a reviewer block; the global config (${globalPath}) is the source of truth — the workspace block is ignored and will be removed on the next config write`;
+}

package/src/guard.ts

@@ -2,13 +2,15 @@
  * Planning write guard: while a planning run is active (status planning or
  * accepted) and execution has not been approved, edit/write may only target
  * planning artifacts — the pi-plans state dir, the active run's artifact
- * directory, and the pi-plans reference cache.
+ * directory, and the pi-plans reference cache. Other runs' artifact
+ * directories are denied outright, including when they sit inside the state
+ * root (the default artifact root does).
  */
 
 import * as os from "node:os";
 import * as path from "node:path";
-import { getRun, loadConfig, readActive, resolveStateRootOrNull } from "./state.ts";
 import { activeInfoById } from "./run-context.ts";
+import { getRun, listRuns, loadConfig, readActive, resolveStateRootOrNull } from "./state.ts";
 
 const GUARDED_TOOLS = new Set(["write", "edit"]);
 const GUARDED_STATUSES = new Set(["planning", "accepted"]);
@@ -51,7 +53,18 @@ export function planningWriteBlockReason(input: GuardInput): string | null {
 		}
 	}
 	const allowed = allowedRoots.some((root) => target === root || target.startsWith(`${root}${path.sep}`));
+
+	// The artifact root defaults inside the state root, so the blanket stateRoot
+	// allowance above also covers every other run's plans. Deny those explicitly
+	// before the allowed check: a run's artifacts stay read-only for the session
+	// that is not bound to that run, wherever the artifact root lives.
+	const otherRunArtifactDirs = listRuns(input.workdir)
+		.filter((run) => run.run_id !== active.run_id)
+		.map((run) => path.resolve(input.workdir, run.artifact_dir));
+	if (otherRunArtifactDirs.some((dir) => target === dir || target.startsWith(`${dir}${path.sep}`))) {
+		return `pi-plans: planning artifacts of other runs are read-only while "${active.run_id}" is active. Bind the run you mean via /resume-plans, or pick the run explicitly.`;
+	}
 	if (allowed) return null;
 
-	return `pi-plans: active planning run "${active.run_id}" is read-only outside planning artifacts. Allowed write roots: ${allowedRoots.join(", ")}. Finish planning and get execution approval (execute_plan tool or /plans-execute), or abandon the run (/plans-abandon).`;
+	return `pi-plans: active planning run "${active.run_id}" is read-only outside planning artifacts (this session is not bound to it; if you are operating on a different run, bind it via /resume-plans or pick the run explicitly). Allowed write roots: ${allowedRoots.join(", ")}. Finish planning and get execution approval (execute_plan tool or /plans-execute), or abandon the run (/plans-abandon).`;
 }

package/src/messaging.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Messaging surface for pi-plans: the subset of ExtensionAPI that tools,
+ * commands, and event handlers need for session writes (appendEntry /
+ * sendMessage / sendUserMessage).
+ *
+ * SDK facts (agent-session.js / extensions/types.d.ts, pi 0.99.0):
+ * - These methods exist ONLY on the ExtensionAPI ("pi") handed to the
+ *   extension factory. The per-call ExtensionContext does NOT carry them.
+ * - Session replacement (newSession/fork/switchSession) disposes the old
+ *   session and constructs a new one whose extension runner RE-RUNS every
+ *   extension factory; reload() does the same. Therefore the correct
+ *   staleness-safe pattern is to refresh this module-level reference at the
+ *   TOP of the factory on every run — never hold a ctx/pi captured anywhere
+ *   else across turns.
+ *
+ * Invariant (verified for pi 0.99.x hosts): ONE live session per process.
+ * Teardown strictly precedes rebuild (agent-session-runtime teardownCurrent
+ * → createRuntime), and pi-plans subagents run as separate processes, so the
+ * last factory to run always belongs to the only live session. A future
+ * same-process multi-session host sharing the extension cache would break
+ * this assumption (last factory wins); that would need per-session keying.
+ */
+export type Messaging = Pick<ExtensionAPI, "appendEntry" | "sendMessage" | "sendUserMessage">;
+
+let messagingApi: Messaging | null = null;
+
+/** Called at the top of the extension factory on every (re)load and session construction. */
+export function setMessagingApi(api: Messaging | null): void {
+	messagingApi = api;
+}
+
+/** Current-session messaging surface. Throws if used before the extension factory ran. */
+export function messaging(): Messaging {
+	if (!messagingApi) throw new Error("pi-plans messaging used before extension initialization");
+	return messagingApi;
+}
+
+/** Best-effort variant for optional writes (e.g. auto-complete state entries):
+ * returns null when the factory has not run; callers swallow transient errors. */
+export function tryMessaging(): Messaging | null {
+	return messagingApi;
+}