pi-harness-runtime 1.1.397 → 1.1.402

package/packages/jev-judge/src/question-risk.ts

@@ -0,0 +1,151 @@
+/**
+ * The risk facts of a pending question.
+ *
+ * The autonomous decision is only as safe as the facts it is based on: a
+ * question that asks for permission for a destructive or irreversible
+ * action must never be approved while the user is away. The facts are
+ * derived deterministically from the question the agent asked and from the
+ * kind of the question - never from a guess.
+ *
+ * The classifier is deliberately conservative: an uncertain case is
+ * classified as "needs an explicit authorization", so the deterministic
+ * policy waits for a human instead of continuing the work.
+ */
+
+export type QuestionKindLike =
+  | "routine"
+  | "approval"
+  | "clarification"
+  | "explicit"
+  | (string & {});
+
+/** The risk facts of a proposed action. */
+export interface QuestionRiskFacts {
+  /** Does the action need an explicit human authorization? */
+  requiresExplicitAuthorization: boolean;
+  /** Can the action destroy or damage something? */
+  destructive: boolean;
+  /** Can the action be undone? */
+  reversible: boolean;
+  /** Does the action reach the outside world? */
+  external: boolean;
+  /** The signals that produced the facts (for diagnostics). */
+  signals: string[];
+}
+
+export interface QuestionRiskInput {
+  /** The kind of the question ("routine", "approval", ...). */
+  kind?: QuestionKindLike;
+  /** The complete question text. */
+  text?: string;
+}
+
+interface RiskPattern {
+  /** The name of the signal, used for diagnostics. */
+  name: string;
+  pattern: RegExp;
+}
+
+/**
+ * Words that name an action that destroys, drops or overwrites something.
+ */
+const DESTRUCTIVE_PATTERNS: RiskPattern[] = [
+	{ name: "delete", pattern: /\b(delete|remove|drop|truncate|wipe|purge|destroy|erase)\b/ },
+	{ name: "reset", pattern: /\b(reset|rollback|revert)\b/ },
+	{ name: "revoke", pattern: /\b(revoke|rotate|invalidate)\b/ },
+	{ name: "force-push", pattern: /\b(force[\s-]?push|push\s+(--force|-f\b)|reset\s+--hard|clean\s+-\w*f)\b/ },
+	{ name: "drop-object", pattern: /\bdrop\s+(table|database|schema|collection|index|bucket)\b/ },
+	{ name: "delete-object", pattern: /\bdelete\s+(the\s+)?(database|table|file|folder|branch|tag|user|account|volume|key)\b/ },
+	{ name: "terminate", pattern: /\b(terminate|kill|shutdown|stop)\b/ },
+	{ name: "overwrite", pattern: /\boverwrite\b/ },
+];
+
+/**
+ * Words that name an action that reaches the outside world.
+ */
+const EXTERNAL_PATTERNS: RiskPattern[] = [
+	{ name: "production", pattern: /\b(production|prod|live)\b/ },
+	{ name: "deploy", pattern: /\b(deploy|publish|release|ship)\b/ },
+	{ name: "merge-main", pattern: /\bmerge\b.*\b(main|master|develop)\b/ },
+	{ name: "notify-people", pattern: /\b(send|post|notify|email|message|announce)\b.*\b(users|customers|clients|everyone|subscribers|team|customer)\b/ },
+	{ name: "money", pattern: /\b(payment|purchase|order|invoice|charge|refund|spend|billing)\b/ },
+];
+
+/**
+ * Words that name a secret or a credential.
+ */
+const SENSITIVE_PATTERNS: RiskPattern[] = [
+	{ name: "credentials", pattern: /\b(secret|credential|api[\s-]?key|token|password)\b/ },
+];
+
+function matchPatterns(
+	text: string,
+	patterns: RiskPattern[],
+	signals: string[],
+): boolean {
+	let matched = false;
+	for (const { name, pattern } of patterns) {
+		if (pattern.test(text)) {
+			signals.push(name);
+			matched = true;
+		}
+	}
+	return matched;
+}
+
+/**
+ * Derive the risk facts of a pending question.
+ *
+ * The rules:
+ *
+ * - A question that asks for permission for a concrete action ("approval",
+ *   "explicit") needs the explicit authorization of a human. Jev never
+ *   approves it on its own.
+ * - A question that names a destructive action is destructive, and its
+ *   reversibility cannot be proven - so it waits.
+ * - A question with an unknown kind or an empty text is uncertain, and an
+ *   uncertain case waits for the human.
+ * - Only a routine question without a destructive or external signal is
+ *   harmless enough for an autonomous decision.
+ */
+export function classifyQuestionRisk(
+	input: QuestionRiskInput,
+): QuestionRiskFacts {
+	const text = (input.text ?? "").toLowerCase();
+	const kind = input.kind;
+	const signals: string[] = [];
+
+	const destructive = matchPatterns(text, DESTRUCTIVE_PATTERNS, signals);
+	const external = matchPatterns(text, EXTERNAL_PATTERNS, signals);
+	const sensitive = matchPatterns(text, SENSITIVE_PATTERNS, signals);
+
+	// The agent asked for permission for a concrete action.
+	let requiresExplicitAuthorization =
+		kind === "approval" || kind === "explicit";
+
+	// A destructive action never gets an autonomous approval.
+	if (destructive) {
+		requiresExplicitAuthorization = true;
+	}
+
+	// An action that reaches the outside world or touches a secret needs a
+	// human as well.
+	if (external || sensitive) {
+		requiresExplicitAuthorization = true;
+	}
+
+	// Unknown kind or unknown text: the action cannot be judged.
+	if (!kind || !text.trim()) {
+		requiresExplicitAuthorization = true;
+		signals.push("unknown-question");
+	}
+
+	return {
+		requiresExplicitAuthorization,
+		destructive,
+		// A destructive action is not provably reversible.
+		reversible: !destructive,
+		external,
+		signals,
+	};
+}

package/packages/jev-judge/tests/auto-continue-context.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Decision context tests.
+ *
+ * Jev has to see the question it decides about, and the deterministic policy
+ * has to decide what is actually allowed. A clarification is never an
+ * approval, and an action that needs an explicit authorization or that
+ * cannot be undone is never approved autonomously.
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+	applyDecisionPolicy,
+	buildDecisionState,
+	createTaskState,
+	isEligibleForDecision,
+	MAX_LISTED_TASKS,
+	MAX_QUESTION_CHARS,
+	type DecisionContext,
+} from "../src/auto-continue.js";
+
+function context(overrides: Partial<DecisionContext> = {}): DecisionContext {
+	return {
+		question: {
+			requestId: "q-123",
+			text: "Want me to implement the toggle buttons now?",
+			kind: "approval",
+			proposedAction: "implement the toggle buttons",
+			consequence: "the button files change",
+			requiresExplicitAuthorization: false,
+			destructive: false,
+			external: false,
+			reversible: true,
+		},
+		currentTask: "Build the toggle",
+		completionRatio: 0.5,
+		totalTasks: 4,
+		completedTasks: 2,
+		blockers: [],
+		nextTasks: ["Build the toggle", "Write the test"],
+		validationStatus: "no pending final tier",
+		waitedMinutes: 6,
+		deadlineMinutes: 30,
+		...overrides,
+	};
+}
+
+describe("decision threshold", () => {
+	it("is not eligible before the threshold", () => {
+		expect(isEligibleForDecision(4.9, 5)).toBe(false);
+		expect(isEligibleForDecision(5, 5)).toBe(true);
+		expect(isEligibleForDecision(30, 5)).toBe(true);
+	});
+});
+
+describe("decision state", () => {
+	it("carries the question, the kind and the risk of the action", () => {
+		const state = buildDecisionState(
+			createTaskState(["a"], ["b"], new Date(), new Date(), context()),
+		) as any;
+
+		expect(state.pending_question.request_id).toBe("q-123");
+		expect(state.pending_question.kind).toBe("approval");
+		expect(state.pending_question.text).toContain("toggle buttons");
+		expect(state.pending_question.proposed_action).toBe(
+			"implement the toggle buttons",
+		);
+		expect(state.pending_question.consequence_of_approval).toBe(
+			"the button files change",
+		);
+		expect(state.pending_question.destructive).toBe(false);
+		expect(state.pending_question.reversible).toBe(true);
+	});
+
+	it("carries the bounded task and risk context", () => {
+		const state = buildDecisionState(
+			createTaskState(["a"], ["b"], new Date(), new Date(), context()),
+		) as any;
+
+		expect(state.decision_context.current_task).toBe("Build the toggle");
+		expect(state.decision_context.completion_ratio).toBe(0.5);
+		expect(state.decision_context.validation_status).toBe(
+			"no pending final tier",
+		);
+		expect(state.decision_context.waited_minutes).toBe(6);
+		expect(state.decision_context.deadline_minutes).toBe(30);
+		expect(state.decision_context.next_tasks).toHaveLength(2);
+	});
+
+	it("bounds the task lists and the question text", () => {
+		const many = Array.from({ length: 50 }, (_, i) => `task ${i}`);
+		const state = buildDecisionState(
+			createTaskState(
+				many,
+				many,
+				new Date(),
+				new Date(),
+				context({
+					question: {
+						requestId: "q-123",
+						text: "x".repeat(MAX_QUESTION_CHARS + 500),
+						kind: "approval",
+					},
+					nextTasks: many,
+				}),
+			),
+		) as any;
+
+		expect(state.task_summary.completed_list).toHaveLength(MAX_LISTED_TASKS);
+		expect(state.task_summary.remaining_list).toHaveLength(MAX_LISTED_TASKS);
+		expect(state.decision_context.next_tasks).toHaveLength(MAX_LISTED_TASKS);
+		expect(state.pending_question.text).toHaveLength(MAX_QUESTION_CHARS);
+	});
+
+	it("has no question when there is none", () => {
+		const state = buildDecisionState(
+			createTaskState(["a"], ["b"], new Date(), new Date()),
+		) as any;
+
+		expect(state.pending_question).toBeNull();
+	});
+});
+
+describe("decision policy", () => {
+	it("never turns a clarification into an approval", () => {
+		const result = applyDecisionPolicy(
+			"approve",
+			context({
+				question: {
+					requestId: "q-1",
+					text: "Do you mean the toggle or the switch?",
+					kind: "clarification",
+				},
+			}),
+			{ confidence: 0.99 },
+		);
+
+		expect(result.outcome).toBe("wait");
+		expect(result.appliedRule).toBe("clarification-never-approved");
+	});
+
+	it("never approves an action that needs an explicit authorization", () => {
+		const result = applyDecisionPolicy(
+			"approve",
+			context({
+				question: {
+					requestId: "q-1",
+					text: "Shall I deploy to production?",
+					kind: "explicit",
+					requiresExplicitAuthorization: true,
+				},
+			}),
+			{ confidence: 0.99 },
+		);
+
+		expect(result.outcome).toBe("wait");
+		expect(result.appliedRule).toBe("explicit-authorization-required");
+	});
+
+	it("never approves an irreversible destructive action", () => {
+		const result = applyDecisionPolicy(
+			"approve",
+			context({
+				question: {
+					requestId: "q-1",
+					text: "Shall I drop the production table?",
+					kind: "approval",
+					destructive: true,
+					reversible: false,
+				},
+			}),
+			{ confidence: 0.99 },
+		);
+
+		expect(result.outcome).toBe("wait");
+		expect(result.appliedRule).toBe("irreversible-action");
+	});
+
+	it("proceeds with caution when a destructive action is reversible", () => {
+		const result = applyDecisionPolicy(
+			"approve",
+			context({
+				question: {
+					requestId: "q-1",
+					text: "Shall I regenerate the snapshots?",
+					kind: "approval",
+					destructive: true,
+					reversible: true,
+				},
+			}),
+			{ confidence: 0.99 },
+		);
+
+		expect(result.outcome).toBe("proceed_with_caution");
+		expect(result.appliedRule).toBe("destructive-action");
+	});
+
+	it("waits when the confidence is below the threshold", () => {
+		const result = applyDecisionPolicy("approve", context(), {
+			confidence: 0.4,
+			confidenceThreshold: 0.7,
+		});
+
+		expect(result.outcome).toBe("wait");
+		expect(result.appliedRule).toBe("confidence-below-threshold");
+	});
+
+	it("approves a low risk approval with a high confidence", () => {
+		const result = applyDecisionPolicy("approve", context(), {
+			confidence: 0.9,
+			confidenceThreshold: 0.7,
+		});
+
+		expect(result.outcome).toBe("approve");
+		expect(result.appliedRule).toBeUndefined();
+	});
+
+	it("keeps a wait and a reject decision", () => {
+		expect(applyDecisionPolicy("wait", context()).outcome).toBe("wait");
+		expect(applyDecisionPolicy("reject", context()).outcome).toBe("reject");
+	});
+});

package/packages/jev-judge/tests/outcome-application.test.ts

@@ -0,0 +1,132 @@
+/**
+ * The structured outcome of the evaluation.
+ *
+ * Jev has to be able to reject a proposed action, and the outcome of the
+ * evaluation may only tighten the decision the thresholds allow.
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+	applyDecisionPolicy,
+	isDecisionOutcome,
+	tightenOutcome,
+	type DecisionContext,
+} from "../src/auto-continue.js";
+
+const context: DecisionContext = {
+	question: {
+		requestId: "q-1",
+		text: "Should I continue with the remaining tasks?",
+		kind: "routine",
+		requiresExplicitAuthorization: false,
+		destructive: false,
+		external: false,
+		reversible: true,
+	},
+	currentTask: "Build the toggle",
+	completionRatio: 0.5,
+	totalTasks: 4,
+	completedTasks: 2,
+	blockers: [],
+	nextTasks: ["Build the toggle"],
+	validationStatus: "no pending final tier",
+	waitedMinutes: 6,
+	deadlineMinutes: 30,
+};
+
+describe("the structured outcome of the evaluation", () => {
+	it("recognizes the known outcomes", () => {
+		expect(isDecisionOutcome("approve")).toBe(true);
+		expect(isDecisionOutcome("proceed_with_caution")).toBe(true);
+		expect(isDecisionOutcome("wait")).toBe(true);
+		expect(isDecisionOutcome("reject")).toBe(true);
+	});
+
+	it("ignores an unknown outcome", () => {
+		expect(isDecisionOutcome("maybe")).toBe(false);
+		expect(isDecisionOutcome(undefined)).toBe(false);
+	});
+});
+
+describe("tightenOutcome", () => {
+	it("keeps a rejection a rejection", () => {
+		expect(tightenOutcome("approve", "reject")).toBe("reject");
+		expect(tightenOutcome("wait", "reject")).toBe("reject");
+	});
+
+	it("keeps a wait a wait", () => {
+		expect(tightenOutcome("approve", "wait")).toBe("wait");
+	});
+
+	it("turns an approval into a cautious approval", () => {
+		expect(tightenOutcome("approve", "proceed_with_caution")).toBe(
+			"proceed_with_caution",
+		);
+	});
+
+	it("never lets an approval beat the thresholds", () => {
+		expect(tightenOutcome("wait", "approve")).toBe("wait");
+		expect(tightenOutcome("proceed_with_caution", "approve")).toBe(
+			"proceed_with_caution",
+		);
+	});
+
+	it("keeps the threshold outcome without a proposal", () => {
+		expect(tightenOutcome("approve", undefined)).toBe("approve");
+	});
+});
+
+describe("the policy of a rejection", () => {
+	it("keeps a rejection", () => {
+		const result = applyDecisionPolicy("reject", context);
+
+		expect(result.outcome).toBe("reject");
+		expect(result.appliedRule).toBeUndefined();
+	});
+
+	it("never turns a rejection into an approval", () => {
+		const result = applyDecisionPolicy("reject", context, {
+			confidence: 0.99,
+		});
+
+		expect(result.outcome).toBe("reject");
+	});
+});
+
+describe("the policy of unknown risk facts", () => {
+	it("waits when nothing is known about the action", () => {
+		const result = applyDecisionPolicy(
+			"approve",
+			{
+				...context,
+				question: {
+					requestId: "q-1",
+					text: "Should I continue?",
+					kind: "routine",
+				},
+			},
+			{ confidence: 0.99 },
+		);
+
+		expect(result.outcome).toBe("wait");
+		expect(result.appliedRule).toBe("unknown-risk-facts");
+	});
+
+	it("still blocks a clarification first", () => {
+		const result = applyDecisionPolicy(
+			"approve",
+			{
+				...context,
+				question: {
+					requestId: "q-1",
+					text: "Do you mean the toggle or the switch?",
+					kind: "clarification",
+				},
+			},
+			{ confidence: 0.99 },
+		);
+
+		expect(result.outcome).toBe("wait");
+		expect(result.appliedRule).toBe("clarification-never-approved");
+	});
+});

package/packages/jev-judge/tests/question-risk.test.ts

@@ -0,0 +1,116 @@
+/**
+ * The risk facts of a pending question.
+ *
+ * The autonomous decision is only as safe as the facts it rests on: a
+ * question that asks for permission for a destructive or irreversible
+ * action must never be approved while the user is away.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { classifyQuestionRisk } from "../src/question-risk.js";
+
+describe("classifyQuestionRisk", () => {
+	describe("a routine continuation question", () => {
+		it("is harmless enough for an autonomous decision", () => {
+			const risk = classifyQuestionRisk({
+				kind: "routine",
+				text: "Should I continue with the remaining tasks?",
+			});
+
+			expect(risk.requiresExplicitAuthorization).toBe(false);
+			expect(risk.destructive).toBe(false);
+			expect(risk.reversible).toBe(true);
+			expect(risk.external).toBe(false);
+		});
+	});
+
+	describe("a question that asks for permission", () => {
+		it("needs an explicit authorization for an approval question", () => {
+			const risk = classifyQuestionRisk({
+				kind: "approval",
+				text: "Want me to implement the toggle buttons now?",
+			});
+
+			expect(risk.requiresExplicitAuthorization).toBe(true);
+			expect(risk.destructive).toBe(false);
+		});
+
+		it("needs an explicit authorization for an explicit question", () => {
+			const risk = classifyQuestionRisk({
+				kind: "explicit",
+				text: "Shall I push the release?",
+			});
+
+			expect(risk.requiresExplicitAuthorization).toBe(true);
+		});
+	});
+
+	describe("a destructive action", () => {
+		it("is destructive even in a routine question", () => {
+			const risk = classifyQuestionRisk({
+				kind: "routine",
+				text: "Should I remove the old config file now?",
+			});
+
+			expect(risk.destructive).toBe(true);
+			expect(risk.requiresExplicitAuthorization).toBe(true);
+			expect(risk.reversible).toBe(false);
+		});
+
+		it("recognizes a dropped database table", () => {
+			const risk = classifyQuestionRisk({
+				kind: "routine",
+				text: "Should I drop table users from the dev database?",
+			});
+
+			expect(risk.destructive).toBe(true);
+			expect(risk.reversible).toBe(false);
+		});
+
+		it("recognizes a force push", () => {
+			const risk = classifyQuestionRisk({
+				kind: "routine",
+				text: "Should I git push --force to the remote?",
+			});
+
+			expect(risk.destructive).toBe(true);
+		});
+	});
+
+	describe("an uncertain question", () => {
+		it("waits when the kind is unknown", () => {
+			const risk = classifyQuestionRisk({ text: "Should I go on?" });
+
+			expect(risk.requiresExplicitAuthorization).toBe(true);
+			expect(risk.signals).toContain("unknown-question");
+		});
+
+		it("waits when the text is empty", () => {
+			const risk = classifyQuestionRisk({ kind: "routine", text: "   " });
+
+			expect(risk.requiresExplicitAuthorization).toBe(true);
+			expect(risk.signals).toContain("unknown-question");
+		});
+	});
+
+	describe("an action that reaches the outside world", () => {
+		it("is external", () => {
+			const risk = classifyQuestionRisk({
+				kind: "routine",
+				text: "Should I deploy to production now?",
+			});
+
+			expect(risk.external).toBe(true);
+			expect(risk.requiresExplicitAuthorization).toBe(true);
+		});
+
+		it("recognizes a message to the users", () => {
+			const risk = classifyQuestionRisk({
+				kind: "routine",
+				text: "Should I send the announcement email to all customers?",
+			});
+
+			expect(risk.external).toBe(true);
+		});
+	});
+});

package/packages/knowledge-graph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/knowledge-graph",
-  "version": "1.1.397",
+  "version": "1.1.402",
   "description": "Knowledge Graph extraction and provenance linking for SKILL.md files",
   "type": "module",
   "main": "./dist/index.js",

package/packages/knowledge-retrieval/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/knowledge-retrieval",
-  "version": "1.1.397",
+  "version": "1.1.402",
   "description": "Knowledge retrieval via TencentDB-Agent-Memory MCP (RFC-0105)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/laravel-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/laravel-plugin",
-  "version": "1.1.397",
+  "version": "1.1.402",
   "description": "Laravel framework analysis — artisan commands, Eloquent models, Blade",
   "type": "module",
   "main": "./dist/index.js",

package/packages/learning-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/learning-engine",
-  "version": "1.1.397",
+  "version": "1.1.402",
   "description": "Learning engine for extracting lessons from runtime execution (RFC-0058)",
   "type": "module",
   "main": "./dist/index.js",