jeopi-cli 16.2.23 → 16.2.25

package/src/extensibility/plugins/trust.ts

@@ -0,0 +1,133 @@
+/**
+ * Plugin trust gate — trust-on-first-use consent for third-party plugin code.
+ *
+ * `custom-tools`/`hooks`/`commands`/`extensions` loaders all execute arbitrary
+ * TypeScript via native `import()` with full `exec`/`pi` API access. User-authored
+ * tools under `.jeopi/tools/` etc. are trusted by construction (the user wrote or
+ * explicitly configured them). Plugin-installed code is different: it arrives via
+ * `bun install <name>` from a marketplace/npm registry, i.e. third-party code the
+ * user did not author. This module gates that path specifically.
+ *
+ * Mirrors the `report-tool-issue.ts` auto-QA consent design: a process-global cache,
+ * a disk-backed decision store, a single host-registered handler for the interactive
+ * popup, and default-deny when no handler is registered (headless/CI/non-interactive
+ * runs never silently execute unreviewed third-party code).
+ *
+ * Trust is keyed by `"<name>@<version>"` — any version bump (including a
+ * marketplace auto-update) invalidates the previous grant and re-prompts, the same
+ * supply-chain assumption package managers use for pinned versions.
+ */
+import { $flag, getPluginTrustStorePath, isEnoent, logger } from "jeopi-utils";
+
+export type PluginTrustDecision = "granted" | "denied";
+
+/**
+ * Resolver for "do you trust this plugin?" consent.
+ *
+ * Return values mirror {@link import("../../tools/report-tool-issue").AutoQaConsentHandler}:
+ *   - `true`  — trusted; load for this run and persist.
+ *   - `false` — untrusted; skip for this run and persist.
+ *   - `null`  — dismissed without a decision; skip this run only, re-prompt next time.
+ */
+export type PluginTrustHandler = (plugin: { name: string; version: string }) => Promise<boolean | null>;
+
+interface TrustStoreShape {
+	[trustKey: string]: PluginTrustDecision;
+}
+
+let trustHandler: PluginTrustHandler | null = null;
+/** Process-global cache so a grant/denial in the parent applies to subagents immediately. */
+const cachedDecisions = new Map<string, PluginTrustDecision>();
+/** Single-flight in-flight prompts, keyed by trust key, so concurrent loaders don't stack popups. */
+const inFlightPrompts = new Map<string, Promise<boolean>>();
+let diskStoreCache: TrustStoreShape | null = null;
+
+export function pluginTrustKey(plugin: { name: string; version: string }): string {
+	return `${plugin.name}@${plugin.version}`;
+}
+
+/** Register the interactive trust-prompt handler. Passing `null` clears it (teardown). */
+export function setPluginTrustHandler(handler: PluginTrustHandler | null): void {
+	trustHandler = handler;
+}
+
+/** Test-only: reset all in-memory trust state. Never call from production code. */
+export function __resetPluginTrustForTests(): void {
+	trustHandler = null;
+	cachedDecisions.clear();
+	inFlightPrompts.clear();
+	diskStoreCache = null;
+}
+
+async function readTrustStore(): Promise<TrustStoreShape> {
+	if (diskStoreCache) return diskStoreCache;
+	try {
+		diskStoreCache = (await Bun.file(getPluginTrustStorePath()).json()) as TrustStoreShape;
+	} catch (err) {
+		if (!isEnoent(err)) {
+			logger.debug("plugin trust store read failed", { error: String(err) });
+		}
+		diskStoreCache = {};
+	}
+	return diskStoreCache;
+}
+
+async function persistTrustDecision(trustKey: string, decision: PluginTrustDecision): Promise<void> {
+	const store = await readTrustStore();
+	store[trustKey] = decision;
+	diskStoreCache = store;
+	try {
+		await Bun.write(getPluginTrustStorePath(), JSON.stringify(store, null, "\t"));
+	} catch (err) {
+		logger.warn("plugin trust store write failed", { error: String(err) });
+	}
+}
+
+/**
+ * Resolve whether `plugin` is trusted to load. Never throws — handler errors
+ * degrade to "denied for this call" without caching, so a later invocation
+ * (e.g. after the user fixes their terminal) can re-prompt.
+ */
+export async function resolvePluginTrust(plugin: { name: string; version: string }): Promise<boolean> {
+	// Escape hatch for headless/CI/scripted runs where no consent handler is ever
+	// registered (the default-deny branch below would otherwise silently disable
+	// every installed plugin). Explicit opt-in only — mirrors PI_AUTO_QA_PUSH.
+	if ($flag("PI_TRUST_ALL_PLUGINS", false)) return true;
+
+	const trustKey = pluginTrustKey(plugin);
+	const cached = cachedDecisions.get(trustKey);
+	if (cached !== undefined) return cached === "granted";
+
+	const store = await readTrustStore();
+	const persisted = store[trustKey];
+	if (persisted !== undefined) {
+		cachedDecisions.set(trustKey, persisted);
+		return persisted === "granted";
+	}
+
+	if (!trustHandler) return false;
+	const inFlight = inFlightPrompts.get(trustKey);
+	if (inFlight) return inFlight;
+
+	const handler = trustHandler;
+	const prompt = (async () => {
+		try {
+			const granted = await handler(plugin);
+			if (granted === null) {
+				// Dismissed (ESC/click-away): skip this call only, don't cache or persist.
+				return false;
+			}
+			const decision: PluginTrustDecision = granted ? "granted" : "denied";
+			cachedDecisions.set(trustKey, decision);
+			await persistTrustDecision(trustKey, decision);
+			return granted;
+		} catch (err) {
+			logger.warn("plugin trust handler threw", { error: String(err) });
+			return false;
+		} finally {
+			inFlightPrompts.delete(trustKey);
+		}
+	})();
+	inFlightPrompts.set(trustKey, prompt);
+	return prompt;
+}

package/src/goals/completion-evidence.ts

@@ -0,0 +1,73 @@
+/**
+ * Validation for the `evidence` argument the `complete` goal-tool op requires.
+ *
+ * Code-level counterpart to the prompt rule ("call `complete` only when the goal is
+ * actually done and verified" — `prompts/tools/goal.md`, `goal-continuation.md`).
+ * Before this, "call complete" was pure self-attestation: a model under budget
+ * pressure or scope-shrink temptation could close a goal with zero code-level
+ * friction. This does not (cannot) verify the claim is *true* — that still requires
+ * the model to have actually checked the repo state — but it forces the model to
+ * commit to a specific, non-trivial claim that a human reviewing the transcript can
+ * hold it to, and it rejects the exact rubber-stamp phrases the prompt already
+ * tells the model never to use as a reason to complete.
+ */
+
+/** Below this length, evidence can't meaningfully describe what was verified. */
+export const MIN_COMPLETION_EVIDENCE_LENGTH = 15;
+
+/** Rubber-stamp phrases that carry no verification content, normalized (trimmed,
+ * lowercased, trailing punctuation stripped). Mirrors the intent of
+ * `advisor/emission-guard.ts`'s `SUPPRESSED_NORMALIZED_PHRASES`. */
+const TRIVIAL_COMPLETION_EVIDENCE_PHRASES = new Set([
+	"done",
+	"complete",
+	"completed",
+	"finished",
+	"ok",
+	"okay",
+	"yes",
+	"verified",
+	"all done",
+	"n/a",
+	"na",
+	"none",
+	"good",
+	"looks good",
+	"lgtm",
+	"task complete",
+	"task done",
+	"goal complete",
+	"goal achieved",
+	"it works",
+	"it's done",
+]);
+
+function normalizeCompletionEvidence(text: string): string {
+	return text
+		.trim()
+		.toLowerCase()
+		.replace(/[.!]+$/, "");
+}
+
+/**
+ * Validate that `evidence` is a substantive, non-generic completion claim.
+ * Returns the trimmed evidence on success; throws a plain `Error` describing
+ * what's missing otherwise (callers map this to their own error type).
+ */
+export function assertSubstantiveCompletionEvidence(evidence: string | undefined): string {
+	const trimmed = evidence?.trim();
+	if (!trimmed) {
+		throw new Error(
+			"evidence is required when op=complete: state which deliverables you verified and how (tests run, output inspected, files diffed, etc.)",
+		);
+	}
+	if (
+		trimmed.length < MIN_COMPLETION_EVIDENCE_LENGTH ||
+		TRIVIAL_COMPLETION_EVIDENCE_PHRASES.has(normalizeCompletionEvidence(trimmed))
+	) {
+		throw new Error(
+			"evidence is too generic to count as verification — describe the specific deliverables checked and how, not a status word",
+		);
+	}
+	return trimmed;
+}

package/src/goals/runtime.ts

@@ -2,6 +2,7 @@ import { escapeXmlText, prompt, Snowflake } from "jeopi-utils";
 import goalBudgetLimitPrompt from "../prompts/goals/goal-budget-limit.md" with { type: "text" };
 import goalContinuationPrompt from "../prompts/goals/goal-continuation.md" with { type: "text" };
 import goalModeActivePrompt from "../prompts/goals/goal-mode-active.md" with { type: "text" };
+import { assertSubstantiveCompletionEvidence } from "./completion-evidence";
 import type { Goal, GoalBudgetSteering, GoalModeState, GoalRuntimeEvent, GoalTokenUsage } from "./state";
 
 export interface GoalRuntimeHost {
@@ -470,7 +471,10 @@ export class GoalRuntime {
 		});
 	}
 
-	async completeGoalFromTool(): Promise<Goal> {
+	async completeGoalFromTool(evidence: string): Promise<Goal> {
+		// Validated here too (not just in GoalTool), so any direct GoalRuntime caller
+		// (SDK embedders bypassing the tool schema) gets the same guardrail.
+		const verifiedEvidence = assertSubstantiveCompletionEvidence(evidence);
 		return await this.#withAccounting(async () => {
 			await this.#flushUsageLocked("suppressed");
 			const state = this.#getStateClone();
@@ -485,6 +489,7 @@ export class GoalRuntime {
 			}
 			state.enabled = false;
 			state.goal.status = "complete";
+			state.goal.completionEvidence = verifiedEvidence;
 			state.goal.updatedAt = this.#now();
 			state.mode = "exiting";
 			state.reason = "completed";

package/src/goals/state.ts

@@ -11,6 +11,9 @@ export interface Goal {
 	timeUsedSeconds: number;
 	createdAt: number;
 	updatedAt: number;
+	/** Set only when status transitions to "complete"; the caller's verification claim
+	 * (see `goals/completion-evidence.ts`). Absent for goals that never completed. */
+	completionEvidence?: string;
 }
 
 export interface GoalModeState {

package/src/goals/tools/goal-tool.ts

@@ -11,6 +11,7 @@ import type { ToolSession } from "../../tools";
 import { formatErrorDetail, TRUNCATE_LENGTHS } from "../../tools/render-utils";
 import { ToolError } from "../../tools/tool-errors";
 import { framedBlock, renderStatusLine, truncateToWidth } from "../../tui";
+import { assertSubstantiveCompletionEvidence } from "../completion-evidence";
 import { completionBudgetReport, remainingTokens } from "../runtime";
 import type { Goal, GoalStatus, GoalToolDetails } from "../state";
 
@@ -18,6 +19,9 @@ const goalSchema = type({
 	op: type("'create' | 'get' | 'complete' | 'resume' | 'drop'").describe("goal operation"),
 	"objective?": type("string").describe("goal objective"),
 	"token_budget?": type("number.integer").describe("token budget"),
+	"evidence?": type("string").describe(
+		"required when op=complete: what you verified and how (tests run, output inspected, files diffed, etc.)",
+	),
 });
 
 export type GoalToolInput = typeof goalSchema.infer;
@@ -55,6 +59,14 @@ function validateCreateParams(params: GoalToolInput): { objective: string; token
 	return { objective, tokenBudget };
 }
 
+function validateCompleteParams(params: GoalToolInput): string {
+	try {
+		return assertSubstantiveCompletionEvidence(params.evidence);
+	} catch (err) {
+		throw new ToolError(err instanceof Error ? err.message : String(err));
+	}
+}
+
 export class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
 	readonly name = "goal";
 	readonly label = "Goal";
@@ -94,7 +106,7 @@ export class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
 			const dropped = await runtime.dropGoal();
 			response = buildGoalToolResponse(dropped ?? null);
 		} else {
-			const completed = await runtime.completeGoalFromTool();
+			const completed = await runtime.completeGoalFromTool(validateCompleteParams(params));
 			response = buildGoalToolResponse(completed, { includeCompletionReport: true });
 		}
 		let text: string;
@@ -106,6 +118,9 @@ export class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
 			if (response.remainingTokens !== null) {
 				text += `\nRemaining tokens: ${response.remainingTokens}`;
 			}
+			if (response.goal.completionEvidence) {
+				text += `\nEvidence: ${response.goal.completionEvidence}`;
+			}
 			if (response.completionBudgetReport) {
 				text += `\n\n${response.completionBudgetReport}`;
 			}