pi-harness-runtime 1.1.447 → 1.1.450

package/packages/notification/src/pending-question.ts

@@ -13,9 +13,30 @@ import { logWarn } from "./file-logger.js";
 export type QuestionKind = 
   | "routine"      // "Should I continue?"
   | "approval"      // "Want me to implement X?"
+  | "choice"        // "Do you want X, or is Y intended?"
   | "clarification" // "Do you mean X or Y?"
   | "explicit";     // Explicit approval required
 
+/**
+ * The typed ask of a detected question.
+ *
+ * An ask is not the same thing as a question: a question is a sentence, an
+ * ask is what the agent wants. The distinction matters after the timeout:
+ * an ask of type "choice" can be decided autonomously (the decision names
+ * the chosen option), while an ask of type "clarification" or
+ * "explicit_authorization" waits for a human.
+ *
+ * A question the detector cannot interpret is NOT a routine ask: an
+ * unrecognized question is a clarification, because the harness does not
+ * know what the agent is waiting for and must not guess.
+ */
+export type AskType =
+  | "approval"
+  | "choice"
+  | "clarification"
+  | "explicit_authorization"
+  | "routine";
+
 /**
  * Question states
  */
@@ -69,6 +90,18 @@ export interface PendingQuestion {
   questionText: string;
   /** Question kind */
   kind: QuestionKind;
+  /** The typed ask of the question. */
+  askType?: AskType;
+  /** The concrete alternatives of a choice question. */
+  alternatives?: string[];
+  /** The complete assistant message the question was detected in. */
+  contextText?: string;
+  /** The option Jev selected for a choice question. */
+  selectedOption?: string;
+  /** The scope Jev chose for the selected option. */
+  scope?: DecisionScope;
+  /** The safe reason code of the last state transition. */
+  closedReason?: string;
   /** Does the proposed action need an explicit human authorization? */
   requiresExplicitAuthorization?: boolean;
   /** Can the proposed action destroy or damage something? */
@@ -118,6 +151,205 @@ export interface DetectionResult {
   questionText?: string;
   kind?: QuestionKind;
   isRoutine?: boolean;
+  /** The typed ask of the detected question. */
+  askType?: AskType;
+  /** The concrete alternatives of a choice question. */
+  alternatives?: string[];
+  /** The complete assistant message the question was detected in. */
+  contextText?: string;
+}
+
+/**
+ * The scope of an autonomous decision.
+ *
+ * A large or expensive job is not done in one step: the decision may
+ * limit itself to a canary that is verified before the work scales up.
+ */
+export type DecisionScope = "full_scope" | "canary_first" | "none";
+
+/**
+ * The structured resolution of an autonomous decision.
+ *
+ * It is the answer to the question the agent asked: the selected option,
+ * the scope and the reasoning. It is never a human answer.
+ */
+export interface JevResolution {
+  /** The option Jev selected for a choice question. */
+  selectedOption?: string;
+  /** The scope Jev chose. */
+  scope?: DecisionScope;
+  /** The reasoning of the decision. */
+  reasoning?: string;
+}
+
+/**
+ * The wording that asks for an explicit human authorization.
+ *
+ * The agent states the requirement itself ("I need your OK before ..."). It
+ * is part of the context of the question, not of the question sentence, so
+ * it is detected on the whole message.
+ */
+const EXPLICIT_AUTHORIZATION_PATTERNS: RegExp[] = [
+	/\b(?:need|needs|needing|require|requires|requiring|want|wants|waiting for|wait for)\s+(?:your|the)\s+(?:explicit\s+)?(?:ok|okay|approval|approbation|authorization|authorisation|permission|consent|confirmation|green light|sign[- ]?off|go[- ]?ahead)\b/i,
+	/\bexplicit\s+(?:approval|authorization|authorisation|permission)\b/i,
+	/\b(?:authorize|authorise)\s+me\b/i,
+	/\bonly\s+(?:with|after)\s+your\b/i,
+];
+
+/**
+ * Does the message ask for an explicit human authorization?
+ *
+ * An ask of this kind is never decided autonomously: only the human may
+ * authorize it.
+ */
+export function hasExplicitAuthorizationWording(text: string): boolean {
+	return EXPLICIT_AUTHORIZATION_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+/**
+ * The typed ask of a question kind.
+ */
+export function askTypeForKind(kind: QuestionKind): AskType {
+	switch (kind) {
+		case "approval":
+			return "approval";
+		case "choice":
+			return "choice";
+		case "clarification":
+			return "clarification";
+		case "explicit":
+			return "explicit_authorization";
+		case "routine":
+			return "routine";
+		default:
+			// An unknown kind is a clarification: the harness does not know
+			// what the agent is waiting for, so it waits for a human.
+			return "clarification";
+	}
+}
+
+/**
+ * The typed ask of a detected question.
+ *
+ * A choice keeps its type: the agent offers concrete alternatives, and a
+ * decision may pick one of them. Every other ask that the message
+ * explicitly reserves for the human is an explicit authorization.
+ */
+export function computeAskType(
+	kind: QuestionKind,
+	explicitAuthorization: boolean,
+): AskType {
+	if (kind === "choice") return "choice";
+	if (explicitAuthorization) return "explicit_authorization";
+	return askTypeForKind(kind);
+}
+
+/**
+ * The stem of a question: the part that carries no alternative.
+ */
+const QUESTION_STEM =
+	/^(?:do you want(?: me to)?|do you prefer|would you like me to|should i|should we|shall i|shall we|may i|can i|could i|is it|are you|which|what|do)\s+/i;
+
+/** The auxiliary verb of the second alternative. */
+const ALTERNATIVE_AUXILIARY =
+	/^(?:is|are|was|were|should|would|do|does|did|can|could|shall|will|to)\s+/i;
+
+/** The intent tail of an alternative ("... is intended"). */
+const ALTERNATIVE_INTENT =
+	/\s+(intended|expected|needed|required|desired|meant|correct|right|preferred)$/i;
+
+/**
+ * The longest question text that is parsed.
+ *
+ * A question is a sentence. The cap keeps the work of the parser
+ * bounded: the alternatives of a question are not longer than a line,
+ * and a bounded input cannot make a slow pattern slow.
+ */
+const MAX_QUESTION_LENGTH = 500;
+
+/** Is the character whitespace? */
+function isSpace(character: string | undefined): boolean {
+	return typeof character === "string" && /\s/.test(character);
+}
+
+/** Is the character the end of a sentence? */
+function isSentenceEnd(character: string | undefined): boolean {
+	return character === "?" || character === "!" || character === ".";
+}
+
+/**
+ * The question without the punctuation that ends the sentence.
+ *
+ * The punctuation is removed by a scan and not by a pattern: a pattern
+ * with two unbounded repetitions next to each other takes quadratic time
+ * on a long run of the same character.
+ */
+function withoutSentenceEnd(text: string): string {
+	let end = text.length;
+	while (end > 0 && isSentenceEnd(text[end - 1])) end -= 1;
+	return text.slice(0, end).trimEnd();
+}
+
+/**
+ * The index where the "or" of two alternatives starts.
+ *
+ * The separator is the word "or" with whitespace around it. A comma in
+ * front of it belongs to the separator. The search is a scan over the
+ * string: a pattern with two unbounded repetitions can take quadratic
+ * time, and a question is not a fixed length.
+ *
+ * @returns the boundaries of the separator, or null when there is none.
+ */
+function findOrSeparator(text: string): { leftEnd: number; orIndex: number } | null {
+	const lower = text.toLowerCase();
+	for (let index = 0; index + 1 < text.length; index += 1) {
+		if (lower[index] !== "o" || lower[index + 1] !== "r") continue;
+		if (!isSpace(text[index - 1]) || !isSpace(text[index + 2])) continue;
+		// The whitespace in front of the word, and the comma that may
+		// come with it.
+		let start = index;
+		while (start > 0 && isSpace(text[start - 1])) start -= 1;
+		const leftEnd = text[start - 1] === "," ? start - 1 : start;
+		return { leftEnd, orIndex: index };
+	}
+	return null;
+}
+
+/**
+ * Extract the alternatives of a choice question.
+ *
+ * The result is what the decision has to choose between, so it must be
+ * concrete: "the current staging state is intended" is an alternative,
+ * "is the current staging state intended?" is not. An empty or unusable
+ * half means the question is not a choice after all.
+ */
+export function extractAlternatives(question: string): string[] {
+	const text = withoutSentenceEnd(
+		question.trim().slice(0, MAX_QUESTION_LENGTH),
+	);
+
+	const separator = findOrSeparator(text);
+	if (!separator) return [];
+
+	// The left half ends before the separator, the right half after the
+	// word "or".
+	const left = text
+		.slice(0, separator.leftEnd)
+		.replace(QUESTION_STEM, "")
+		.replace(/[\s,]+$/, "")
+		.trim();
+	const rightRaw = text.slice(separator.orIndex + 2).trim();
+	const right = rightRaw.replace(ALTERNATIVE_AUXILIARY, "").trim();
+
+	if (!left || !right) return [];
+
+	// "the current staging state intended" -> "the current staging state is intended"
+	const intent = right.match(ALTERNATIVE_INTENT);
+	const normalizedRight = intent
+		? `${right.slice(0, intent.index).trimEnd()} is ${intent[1]}`
+		: right;
+
+	return [left, normalizedRight];
 }
 
 /**
@@ -176,13 +408,26 @@ export class PendingQuestionController {
 
 	/**
 	 * Detect if text contains a question requiring response
+	 *
+	 * The complete assistant message is kept as the context of the question:
+	 * the sentence that carries the question often leaves out what the agent
+	 * is really waiting for ("I need your OK before ..."). The risk facts and
+	 * the decision are derived from the whole message, not from the sentence
+	 * alone.
 	 */
-	detectQuestion(text: string, _options?: {
+	detectQuestion(text: string, options?: {
 		sessionId?: string;
 		workspacePath?: string;
 		jobId?: string;
+		/** The complete assistant message the question was detected in. */
+		contextText?: string;
 	}
 	): DetectionResult {
+		const contextText = options?.contextText ?? text;
+		// The message decides whether the agent reserves the decision for the
+		// human: "I need your OK before ..." is part of the context and not
+		// of the question sentence.
+		const explicitAuthorization = hasExplicitAuthorizationWording(contextText);
 		// Find all question positions and extract each question sentence
 		const questionPositions: Array<{ start: number; end: number; sentence: string }> = [];
 		let searchFrom = 0;
@@ -231,30 +476,39 @@ export class PendingQuestionController {
 			const isRoutine = this.isRoutineContinuation(q.sentence);
 			const kind = this.determineKind(q.sentence, isRoutine);
 			
-			// Return first approval or clarification question found
-			if (kind === "approval" || kind === "clarification") {
+			// Return first approval, choice or clarification question found
+			if (kind === "approval" || kind === "choice" || kind === "clarification") {
 				return {
 					detected: true,
 					questionText: q.sentence,
 					kind,
 					isRoutine,
+					askType: computeAskType(kind, explicitAuthorization),
+					alternatives: kind === "choice" ? extractAlternatives(q.sentence) : undefined,
+					contextText,
 				};
 			}
 		}
 		
-		// If no approval/clarification found, return first non-quoted routine question
+		// If no approval/choice/clarification was found, return the first
+		// non-quoted question. An unrecognized question is a clarification:
+		// the harness does not know what the agent is waiting for.
 		for (const q of questionPositions) {
 			if (this.isQuotedOrCode(text, q.sentence)) {
 				continue;
 			}
 			
 			const isRoutine = this.isRoutineContinuation(q.sentence);
+			const kind = this.determineKind(q.sentence, isRoutine);
 			
 			return {
 				detected: true,
 				questionText: q.sentence,
-				kind: "routine",
+				kind,
 				isRoutine,
+				askType: computeAskType(kind, explicitAuthorization),
+				alternatives: kind === "choice" ? extractAlternatives(q.sentence) : undefined,
+				contextText,
 			};
 		}
 		
@@ -305,6 +559,11 @@ export class PendingQuestionController {
 					questionText: text.trim(),
 					kind: "approval",
 					isRoutine: false,
+					askType: computeAskType(
+						"approval",
+						hasExplicitAuthorizationWording(text),
+					),
+					contextText: text,
 				};
 			}
 		}
@@ -386,10 +645,8 @@ export class PendingQuestionController {
       /\bwant me to\b/i,
       /\bwould you like me to\b/i,
       /\bshall i\b/i,
-      /\bshould i add\b/i,
-      /\bshould i implement\b/i,
-      /\bshould we add\b/i,
-      /\bshould we implement\b/i,
+      /\bshould i\b/i,
+      /\bshould we\b/i,
       /\bdo you want me to\b/i,
       /\bcan i (start|proceed|add|implement)\b/i,
     ];
@@ -400,7 +657,25 @@ export class PendingQuestionController {
       }
     }
 		
-    return "routine";
+    // A choice names concrete alternatives: "do you want X, or is Y
+    // intended?". The decision may pick one of them, but only when it
+    // names the picked option.
+    const choicePatterns = [
+      /,\s*or\s+(?:is|are|was|were|should|would|do|does|did|can|could|shall|will|to)\b/i,
+      /\beither\b[^?]*\bor\b/i,
+      /\b(?:do you want|do you prefer|would you like|should i|shall i|can i|could i|which)\b[^?]*\bor\b/i,
+    ];
+		
+    for (const pattern of choicePatterns) {
+      if (pattern.test(lower)) {
+        return "choice";
+      }
+    }
+		
+    // An unrecognized question is not a routine continuation: the harness
+    // does not know what the agent is waiting for, so it asks a human
+    // instead of continuing on a guess.
+    return "clarification";
   }
 
   /**
@@ -447,6 +722,12 @@ export class PendingQuestionController {
     workspacePath: string;
     jobId?: string;
     kind: QuestionKind;
+    /** The typed ask of the question. */
+    askType?: AskType;
+    /** The concrete alternatives of a choice question. */
+    alternatives?: string[];
+    /** The complete assistant message the question was detected in. */
+    contextText?: string;
     /** The deterministic risk facts of the proposed action. */
     risk?: {
       requiresExplicitAuthorization?: boolean;
@@ -465,6 +746,9 @@ export class PendingQuestionController {
       jobId: params.jobId,
       questionText: params.text,
       kind: params.kind,
+      askType: params.askType ?? askTypeForKind(params.kind),
+      alternatives: params.alternatives,
+      contextText: params.contextText,
       requiresExplicitAuthorization: params.risk?.requiresExplicitAuthorization,
       destructive: params.risk?.destructive,
       reversible: params.risk?.reversible,
@@ -554,6 +838,18 @@ export class PendingQuestionController {
       return false;
     }
 
+    // A question that was expired or cancelled is closed: a late click
+    // must not resurrect it and must not report an answer that never
+    // happened.
+    if (
+      this.currentQuestion.state === "expired" ||
+      this.currentQuestion.state === "cancelled"
+    ) {
+      logWarn("[PendingQuestion]",
+        `Question is ${this.currentQuestion.state} (${this.currentQuestion.closedReason ?? "no reason"}) - late callback ignored`);
+      return false;
+    }
+
     this.currentQuestion.state = "resolved";
     this.currentQuestion.resolution = params.resolution;
     this.currentQuestion.resolvedBy = params.by;
@@ -595,6 +891,7 @@ export class PendingQuestionController {
     requestId: string,
     outcome: JevOutcome,
     reason?: string,
+    resolution?: JevResolution,
   ): boolean {
     if (!this.currentQuestion) {
       logWarn("[PendingQuestion]", "No question to resolve - no pending question");
@@ -613,27 +910,108 @@ export class PendingQuestionController {
       return false;
     }
 
+    if (
+      this.currentQuestion.state === "expired" ||
+      this.currentQuestion.state === "cancelled"
+    ) {
+      logWarn("[PendingQuestion]",
+        `Question is ${this.currentQuestion.state} - jev decision ignored`);
+      return false;
+    }
+
     this.currentQuestion.state = "resolved";
     this.currentQuestion.resolvedBy = "jev";
     this.currentQuestion.jevOutcome = outcome;
     this.currentQuestion.jevReason = reason;
     this.currentQuestion.resolvedAt = new Date();
+    // The resolution is the answer to the question: the selected option and
+    // the scope travel with the request, so the agent can be told which
+    // option was chosen.
+    if (resolution?.selectedOption) {
+      this.currentQuestion.selectedOption = resolution.selectedOption;
+    }
+    if (resolution?.scope) {
+      this.currentQuestion.scope = resolution.scope;
+    }
 
     logWarn("[PendingQuestion]",
       `Closed question ${this.currentQuestion.requestId} with jev outcome ${outcome}`);
 
     if (this.jevDecisionCallback) {
+      const metadata: Record<string, unknown> = { outcome };
+      if (resolution?.selectedOption) {
+        metadata["selectedOption"] = resolution.selectedOption;
+      }
+      if (resolution?.scope) {
+        metadata["scope"] = resolution.scope;
+      }
       this.jevDecisionCallback(this.currentQuestion, {
         action: outcome === "reject" ? "stop" : outcome === "wait" ? "wait" : "continue",
         reason: reason ?? `jev:${outcome}`,
         eligible: true,
-        metadata: { outcome },
+        metadata,
+      });
+    }
+
+    return true;
+  }
+
+  /**
+   * Expire the pending question when the decision deadline is reached.
+   *
+   * The deadline is a terminal path: the question is closed with the safe
+   * reason code, the buttons of that request become stale, and the wait
+   * state is cleared. A question that is left open here looks like a
+   * request that is still waiting - forever.
+   *
+   * @returns true if the question was expired, false when it was already
+   *   answered by a human or closed by a decision.
+   */
+  expireByTimeout(requestId: string, reason: string = "deadline-expired"): boolean {
+    if (!this.currentQuestion) {
+      logWarn("[PendingQuestion]", "No question to expire - no pending question");
+      return false;
+    }
+
+    if (this.currentQuestion.requestId !== requestId) {
+      logWarn("[PendingQuestion]",
+        `Expiry for an unknown request: ${requestId} (current=${this.currentQuestion.requestId})`);
+      return false;
+    }
+
+    if (this.currentQuestion.state !== "pending" && this.currentQuestion.state !== "evaluating") {
+      logWarn("[PendingQuestion]",
+        `Question is ${this.currentQuestion.state} - expiry ignored`);
+      return false;
+    }
+
+    this.currentQuestion.state = "expired";
+    this.currentQuestion.resolvedBy = "timeout";
+    this.currentQuestion.resolvedAt = new Date();
+    this.currentQuestion.closedReason = reason;
+
+    logWarn("[PendingQuestion]",
+      `Expired question ${this.currentQuestion.requestId}: ${reason}`);
+
+    if (this.jevDecisionCallback) {
+      this.jevDecisionCallback(this.currentQuestion, {
+        action: "stop",
+        reason,
+        eligible: false,
+        metadata: { outcome: "expired" },
       });
     }
 
     return true;
   }
 
+  /**
+   * The state of the current question.
+   */
+  getState(): QuestionState | undefined {
+    return this.currentQuestion?.state;
+  }
+
   /**
    * Apply an approval action from a channel to the current question.
    *

package/packages/paperclip-integration/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/paperclip-integration",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Paperclip API integration: poll agent inbox, route tasks to pi.dev, Telegram alerts",
   "type": "module",
   "main": "./dist/index.js",

package/packages/performance-optimizer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/performance-optimizer",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Performance optimization analyzer for pi-harness runtime (RFC-0056)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/privilege-broker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/privilege-broker",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Privilege Broker — capability registry and command executor for autonomous runtime (RFC-0101 §7)",
   "type": "module",
   "main": "./dist/index.js",

package/packages/prompt-compiler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/prompt-compiler",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Deterministic prompt compiler for pi-harness-runtime",
   "type": "module",
   "main": "./dist/index.js",

package/packages/providers/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/providers",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "pi-harness-runtime — providers",
   "type": "module",
   "main": "./dist/index.js",

package/packages/qdrant-skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/qdrant-skills",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Qdrant vector search integration for Hermes-style skill system",
   "type": "module",
   "main": "./dist/index.js",

package/packages/quota-manager/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/quota-manager",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "pi-harness-runtime — quota-manager",
   "type": "module",
   "main": "./dist/index.js",

package/packages/relay/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/relay",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "type": "module",
   "description": "Cloud relay for remote access - T3 Connect style for pi-harness",
   "main": "./dist/index.js",

package/packages/skill-mcp-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi/skill-mcp-client",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "MCP client for Skills SaaS backend",
   "type": "module",
   "main": "./dist/index.js",

package/packages/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/skills",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "File-based skill system with pi.dev compatibility and Hermes self-improvement",
   "type": "module",
   "main": "src/index.ts",

package/packages/todo-bd-sync/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moocoding/todo-bd-sync",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Two-way sync between rpiv-todo overlay and bd issue tracker",
   "type": "module",
   "main": "src/index.ts",

package/packages/token-estimation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/token-estimation",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "pi-harness-runtime — token-estimation",
   "type": "module",
   "main": "./dist/index.js",

package/packages/tooling-preference/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tooling-preference",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "pi-harness-runtime — JS/TS tooling preference (Biome vs ESLint/Prettier) proposal",
   "type": "module",
   "main": "./dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/trajectory",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "Trajectory capture for the write-review loop — persists cycle records for learning",
   "type": "module",
   "main": "./dist/src/index.js",

package/packages/tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/tui",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "pi-harness-runtime — tui",
   "type": "module",
   "main": "./dist/index.js",

package/packages/two-phase-review/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-harness/two-phase-review",
-  "version": "1.1.447",
+  "version": "1.1.450",
   "description": "pi-harness-runtime — two-phase implementation and review workflow (queue review signals, gate the phase, scope the diff)",
   "type": "module",
   "main": "./dist/index.js",