@linimin/pi-letscook 0.1.50 → 0.1.52

package/extensions/completion/role-runner.ts

@@ -7,11 +7,17 @@ import { DynamicBorder, parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { Container, Text } from "@mariozechner/pi-tui";
 import {
 	buildContextProposalAnalystPromptFromEntries,
+	extractJsonObjectFromText,
 	parseContextProposalAnalystOutput,
+	serializeRecentDiscussionEntries,
 	type ContextProposal,
 	type RecentDiscussionEntry,
 } from "./proposal";
-import { contextProposalAnalystProgressLines } from "./prompt-surfaces";
+import {
+	buildCookTriggerClassifierPrompt,
+	contextProposalAnalystProgressLines,
+	maybeWriteCookTriggerClassifierSnapshot,
+} from "./prompt-surfaces";
 import {
 	applyLiveRoleEvent,
 	buildInlineRunningLines,
@@ -25,7 +31,13 @@ import {
 } from "./status-surface";
 import { completionRootKey, findCompletionRoot, findRepoRoot, loadCompletionDataForReminder } from "./state-store";
 import { parseReportFields, transcribeRoleOutput, type TranscriptionResult } from "./transcription";
-import type { AgentDefinition, CompletionRole, JsonRecord, LiveRoleActivity } from "./types";
+import type {
+	AgentDefinition,
+	CompletionRole,
+	CookTriggerClassification,
+	JsonRecord,
+	LiveRoleActivity,
+} from "./types";
 
 export type RunCompletionRoleParams = {
 	root: string;
@@ -67,6 +79,21 @@ export type AnalyzeContextProposalWithAgentParams = {
 	getCtxUi: <T extends { ui: any }>(ctx: T) => any | undefined;
 };
 
+export type ClassifyCookTriggerIntentWithAgentParams = {
+	ctx: { cwd: string; hasUI: boolean; ui: any; model?: any };
+	projectName: string;
+	inputText: string;
+	recentEntries: RecentDiscussionEntry[];
+	workflowContextLines?: string[];
+};
+
+export type CookTriggerClassifierResult = {
+	status: "classified" | "timeout" | "invalid_output" | "error";
+	classification?: CookTriggerClassification;
+	rawOutput?: string;
+	errorMessage?: string;
+};
+
 const AGENT_HOME = path.join(os.homedir(), ".pi", "agent");
 const EXTENSION_DIR = typeof __dirname === "string" ? __dirname : process.cwd();
 const PACKAGE_ROOT_CANDIDATE = path.resolve(EXTENSION_DIR, "..", "..");
@@ -93,6 +120,28 @@ const CONTEXT_PROPOSAL_ANALYST_SYSTEM_PROMPT = [
 ].join(" ");
 const STARTUP_ANALYST_ROLE = "cook-proposal-analyst";
 const ANALYST_HEARTBEAT_MS = 5_000;
+const COOK_TRIGGER_CLASSIFIER_SYSTEM_PROMPT = [
+	"You classify whether the latest user input should stay in the main chat or be intercepted by the workflow-aware router into the canonical /cook workflow before the primary agent starts implementation work.",
+	"Assume router mode reviews every non-bypass normal user turn. Do not require short trigger phrases or explicit /cook text before choosing offer_workflow.",
+	"Do not emit markdown, code fences, or commentary.",
+	"Return exactly one JSON object with keys: decision, confidence, workflow_bias, reason, evidence, riskFlags, focusHint. You may also include optional keys requires_clarification, clarification_slots, and adopted_artifact when clearly supported.",
+	"decision must be exactly one of offer_workflow, normal_prompt, or unclear.",
+	"Use offer_workflow when the latest input is directly asking to start, resume, refocus, or continue workflow-worthy repo work through the completion boundary, or explicitly asking to let /cook take over.",
+	"Use normal_prompt for ordinary questions, explanations, analysis-only requests, or direct requests that should stay with the primary agent.",
+	"Use unclear for ambiguous approvals, acknowledgements, or mixed signals where false-positive routing risk is material.",
+	"workflow_bias must be exactly one of startup, resume, refocus, next_round, or unknown.",
+	"Use startup when there is no active workflow yet, resume when the user is clearly continuing the current workflow, refocus when the user is clearly switching the active workflow to a different goal, and next_round when the previous workflow is done and the user is starting a new round.",
+	"When decision is not offer_workflow, prefer workflow_bias=unknown unless a stronger routing hint would still aid debugging.",
+	"confidence must be a number from 0 to 1.",
+	"reason must be a single concise sentence.",
+	"evidence must be an array of short grounded strings.",
+	"riskFlags must be an array of short machine-readable strings such as ambiguous-approval, possible-normal-agent-request, or active-workflow-refocus-risk.",
+	"focusHint is optional, must stay short, and must never rewrite the workflow mission or invent scope.",
+	"When explicit user adoption of a recent plan or repo markdown artifact is evident, adopted_artifact may describe it with kind recent_plan|repo_markdown, path when known, and basis explicit_user_adoption.",
+	"requires_clarification may be true when chooser-style disambiguation is safer than guessing, and clarification_slots may list short needs such as goal, scope, or non_goal.",
+	"Short acknowledgements like 好, 可以, ok, sure, or 那就這樣 should usually be unclear unless the surrounding context makes the handoff explicit.",
+].join(" ");
+const COOK_TRIGGER_CLASSIFIER_TIMEOUT_MS = 10_000;
 
 class StartupAnalystOverlay extends Container {
 	private readonly border: DynamicBorder;
@@ -175,7 +224,7 @@ async function runContextProposalAnalystSubprocess(params: AnalyzeContextProposa
 	const rootKey = completionRootKey(undefined, cwd);
 	const prompt = buildContextProposalAnalystPromptFromEntries(projectName, recentEntries, params.workflowContextLines);
 	const systemPromptTemp = await writeTempFile(runCwd, "pi-cook-proposal-analyst-", CONTEXT_PROPOSAL_ANALYST_SYSTEM_PROMPT);
-	const args: string[] = ["--mode", "json", "-p", "--no-session", "--append-system-prompt", systemPromptTemp.filePath, "--model", modelArg, prompt];
+	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath, "--model", modelArg, prompt];
 	const invocation = getPiInvocation(args);
 	const liveActivity = createLiveRoleActivity(STARTUP_ANALYST_ROLE);
 	liveActivity.progress = "Analyzing recent discussion";
@@ -324,6 +373,264 @@ export async function analyzeContextProposalWithAgent(params: AnalyzeContextProp
 	}
 }
 
+function uniqueStrings(items: string[]): string[] {
+	const seen = new Set<string>();
+	const result: string[] = [];
+	for (const item of items) {
+		const normalized = item.trim();
+		if (!normalized) continue;
+		const key = normalized.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(normalized);
+	}
+	return result;
+}
+
+function localAsStringArray(value: unknown): string[] {
+	return Array.isArray(value)
+		? uniqueStrings(value.filter((item): item is string => typeof item === "string" && item.trim().length > 0))
+		: [];
+}
+
+function confidenceFromUnknown(value: unknown): number {
+	const parsed =
+		typeof value === "number"
+			? value
+			: typeof value === "string" && value.trim().length > 0
+				? Number.parseFloat(value)
+				: Number.NaN;
+	if (!Number.isFinite(parsed)) return 0;
+	return Math.min(1, Math.max(0, parsed));
+}
+
+function parseCookTriggerClassification(raw: string): CookTriggerClassification | undefined {
+	const jsonText = extractJsonObjectFromText(raw);
+	if (!jsonText) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(jsonText);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(parsed)) return undefined;
+	const rawDecision = asString(parsed.decision ?? parsed.intent);
+	const decision =
+		rawDecision === "offer_workflow" || rawDecision === "normal_prompt" || rawDecision === "unclear"
+			? rawDecision
+			: rawDecision === "route_to_cook"
+				? "offer_workflow"
+				: undefined;
+	if (!decision) return undefined;
+	const rawWorkflowBias = asString(parsed.workflow_bias ?? parsed.workflowBias ?? parsed.routing_bias ?? parsed.routingBias);
+	const workflowBias =
+		rawWorkflowBias === "startup" ||
+		rawWorkflowBias === "resume" ||
+		rawWorkflowBias === "refocus" ||
+		rawWorkflowBias === "next_round" ||
+		rawWorkflowBias === "unknown"
+			? rawWorkflowBias
+			: decision === "offer_workflow" && rawDecision === "route_to_cook"
+				? "unknown"
+				: "unknown";
+	const evidence = localAsStringArray(parsed.evidence);
+	const riskFlags = localAsStringArray(parsed.riskFlags ?? parsed.risk_flags);
+	const reason = asString(parsed.reason) ?? asString(parsed.rationale) ?? evidence[0] ?? `Classifier returned ${decision}.`;
+	const focusHint = asString(parsed.focusHint ?? parsed.focus_hint);
+	return {
+		decision,
+		confidence: confidenceFromUnknown(parsed.confidence),
+		workflowBias,
+		reason,
+		focusHint,
+		evidence: evidence.length > 0 ? evidence : [reason],
+		riskFlags,
+	};
+}
+
+function triggerClassifierFailureModeFromEnv(): "timeout" | "error" | "invalid_output" | undefined {
+	const raw = asString(process.env.PI_COMPLETION_TEST_TRIGGER_CLASSIFIER_FAILURE)?.toLowerCase();
+	return raw === "timeout" || raw === "error" || raw === "invalid_output" ? raw : undefined;
+}
+
+function triggerClassifierSnapshotPath(): string | undefined {
+	return asString(process.env.PI_COMPLETION_TEST_TRIGGER_CLASSIFIER_SNAPSHOT_PATH);
+}
+
+async function runCookTriggerClassifierSubprocess(
+	params: ClassifyCookTriggerIntentWithAgentParams & { prompt: string },
+): Promise<CookTriggerClassifierResult> {
+	const cwd = params.ctx.cwd;
+	const runCwd = findCompletionRoot(cwd) ?? findRepoRoot(cwd) ?? cwd;
+	const modelArg = contextProposalAnalystModelArg(params.ctx.model);
+	const systemPromptTemp = await writeTempFile(runCwd, "pi-cook-trigger-classifier-", COOK_TRIGGER_CLASSIFIER_SYSTEM_PROMPT);
+	const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions", "--append-system-prompt", systemPromptTemp.filePath];
+	if (modelArg) args.push("--model", modelArg);
+	args.push(params.prompt);
+	const invocation = getPiInvocation(args);
+	const liveActivity = createLiveRoleActivity("cook-trigger-classifier");
+	const messages: RoleMessage[] = [];
+	let stderr = "";
+	let timedOut = false;
+	try {
+		const rawOutput = await new Promise<string | undefined>((resolve) => {
+			const proc = spawn(invocation.command, invocation.args, {
+				cwd: runCwd,
+				env: process.env,
+				stdio: ["ignore", "pipe", "pipe"],
+				shell: false,
+			});
+			let settled = false;
+			let buffer = "";
+			const resolveOnce = (value: string | undefined) => {
+				if (settled) return;
+				settled = true;
+				resolve(value);
+			};
+			const timeoutHandle = setTimeout(() => {
+				timedOut = true;
+				proc.kill("SIGTERM");
+				resolveOnce(undefined);
+			}, COOK_TRIGGER_CLASSIFIER_TIMEOUT_MS);
+			const processLine = (line: string) => {
+				if (!line.trim()) return;
+				try {
+					const event = JSON.parse(line) as JsonRecord;
+					applyLiveRoleEvent(liveActivity, event, messages);
+				} catch {
+					// ignore malformed lines from the subprocess event stream
+				}
+			};
+			proc.stdout.on("data", (chunk) => {
+				buffer += chunk.toString();
+				const lines = buffer.split("\n");
+				buffer = lines.pop() ?? "";
+				for (const line of lines) processLine(line);
+			});
+			proc.stderr.on("data", (chunk) => {
+				stderr += chunk.toString();
+			});
+			proc.on("close", (code) => {
+				clearTimeout(timeoutHandle);
+				if (buffer.trim()) processLine(buffer);
+				if (timedOut) return;
+				resolveOnce(code === 0 ? liveActivity.lastAssistantText?.trim() || undefined : undefined);
+			});
+			proc.on("error", () => {
+				clearTimeout(timeoutHandle);
+				resolveOnce(undefined);
+			});
+		});
+		if (!rawOutput) {
+			if (timedOut) {
+				return {
+					status: "timeout",
+					errorMessage: `Trigger classifier timed out after ${COOK_TRIGGER_CLASSIFIER_TIMEOUT_MS}ms.`,
+				};
+			}
+			return { status: "error", errorMessage: stderr.trim() || "Trigger classifier produced no assistant output." };
+		}
+		const classification = parseCookTriggerClassification(rawOutput);
+		if (!classification) {
+			return {
+				status: "invalid_output",
+				rawOutput,
+				errorMessage: "Trigger classifier returned invalid JSON output.",
+			};
+		}
+		return { status: "classified", classification, rawOutput };
+	} finally {
+		await fsp.rm(systemPromptTemp.dir, { recursive: true, force: true });
+	}
+}
+
+export async function classifyCookTriggerIntentWithAgent(
+	params: ClassifyCookTriggerIntentWithAgentParams,
+): Promise<CookTriggerClassifierResult> {
+	const recentDiscussion = serializeRecentDiscussionEntries(params.recentEntries);
+	const prompt = buildCookTriggerClassifierPrompt({
+		projectName: params.projectName,
+		inputText: params.inputText,
+		recentDiscussion,
+		workflowContextLines: params.workflowContextLines,
+	});
+	const snapshotPath = triggerClassifierSnapshotPath();
+	const testFailureMode = triggerClassifierFailureModeFromEnv();
+	if (testFailureMode) {
+		const result: CookTriggerClassifierResult = {
+			status: testFailureMode,
+			errorMessage: `Forced trigger classifier ${testFailureMode} for deterministic tests.`,
+		};
+		maybeWriteCookTriggerClassifierSnapshot(
+			{
+				projectName: params.projectName,
+				inputText: params.inputText,
+				recentEntries: params.recentEntries,
+				workflowContextLines: params.workflowContextLines ?? [],
+				prompt,
+				result,
+			},
+			snapshotPath,
+		);
+		return result;
+	}
+	const testOutput = asString(process.env.PI_COMPLETION_TEST_TRIGGER_CLASSIFIER_OUTPUT);
+	if (testOutput) {
+		const classification = parseCookTriggerClassification(testOutput);
+		const result: CookTriggerClassifierResult = classification
+			? { status: "classified", classification, rawOutput: testOutput }
+			: {
+				status: "invalid_output",
+				rawOutput: testOutput,
+				errorMessage: "Trigger classifier test override did not match the required JSON schema.",
+			};
+		maybeWriteCookTriggerClassifierSnapshot(
+			{
+				projectName: params.projectName,
+				inputText: params.inputText,
+				recentEntries: params.recentEntries,
+				workflowContextLines: params.workflowContextLines ?? [],
+				prompt,
+				result,
+			},
+			snapshotPath,
+		);
+		return result;
+	}
+	try {
+		const result = await runCookTriggerClassifierSubprocess({ ...params, prompt });
+		maybeWriteCookTriggerClassifierSnapshot(
+			{
+				projectName: params.projectName,
+				inputText: params.inputText,
+				recentEntries: params.recentEntries,
+				workflowContextLines: params.workflowContextLines ?? [],
+				prompt,
+				result,
+			},
+			snapshotPath,
+		);
+		return result;
+	} catch (error) {
+		const result: CookTriggerClassifierResult = {
+			status: "error",
+			errorMessage: error instanceof Error ? error.message : String(error),
+		};
+		maybeWriteCookTriggerClassifierSnapshot(
+			{
+				projectName: params.projectName,
+				inputText: params.inputText,
+				recentEntries: params.recentEntries,
+				workflowContextLines: params.workflowContextLines ?? [],
+				prompt,
+				result,
+			},
+			snapshotPath,
+		);
+		return result;
+	}
+}
+
 export async function loadAgentDefinition(cwd: string, role: CompletionRole): Promise<AgentDefinition> {
 	const projectAgent = walkUpForDir(cwd, [".pi", "agents", `${role}.md`]);
 	const packageAgent = PACKAGE_AGENTS_DIR ? path.join(PACKAGE_AGENTS_DIR, `${role}.md`) : undefined;

package/extensions/completion/types.ts

@@ -85,3 +85,117 @@ export type CompletionStatusSurface = {
 	liveStateDeltas?: string[];
 	liveDetailsLines?: string[];
 };
+
+export type NaturalLanguageCookTriggerMode = "off" | "assist" | "router" | "auto";
+export type CookTriggerClassifierDecision = "offer_workflow" | "normal_prompt" | "unclear";
+export type CookTriggerWorkflowBias = "startup" | "resume" | "refocus" | "next_round" | "unknown";
+
+export type CookTriggerClassification = {
+	decision: CookTriggerClassifierDecision;
+	confidence: number;
+	workflowBias: CookTriggerWorkflowBias;
+	reason: string;
+	focusHint?: string;
+	evidence: string[];
+	riskFlags: string[];
+};
+
+export type CookTriggerConfirmationAction = "start_workflow" | "send_as_normal_chat" | "cancel";
+export type CookTriggerClarificationAction =
+	| "route_startup"
+	| "route_resume"
+	| "route_refocus"
+	| "route_next_round"
+	| "send_as_normal_chat"
+	| "cancel";
+export type CookTriggerRecoveryAction = "retry_routing" | "send_as_normal_chat" | "cancel";
+export type CookTriggerAdoptedArtifactKind = "recent_plan" | "repo_markdown";
+
+export type CookTriggerConfirmationActionItem = {
+	id: CookTriggerConfirmationAction;
+	label: string;
+	description: string;
+};
+
+export type CookTriggerClarificationActionItem = {
+	id: CookTriggerClarificationAction;
+	label: string;
+	description: string;
+};
+
+export type CookTriggerConfirmationLayout = {
+	title: string;
+	intro: string;
+	evidenceHeading?: string;
+	evidenceBody?: string;
+	riskHeading?: string;
+	riskBody?: string;
+	focusHintHeading?: string;
+	focusHintBody?: string;
+	actionsHeading: string;
+	actions: CookTriggerConfirmationActionItem[];
+	footer: string;
+};
+
+export type CookTriggerClarificationCapsule = {
+	goal?: string;
+	scope?: string[];
+	nonGoal?: string[];
+	doneWhen?: string[];
+	selectedWorkflowBias: CookTriggerWorkflowBias;
+	reason: string;
+};
+
+export type CookTriggerAdoptedArtifact = {
+	kind: CookTriggerAdoptedArtifactKind;
+	basis: "explicit_user_adoption";
+	title: string;
+	path?: string;
+	preview?: string;
+};
+
+export type CookNaturalLanguageHandoff = {
+	preferredRoutingBias?: CookTriggerWorkflowBias;
+	triggerText?: string;
+	hintText?: string;
+	clarificationCapsule?: CookTriggerClarificationCapsule;
+	adoptedArtifact?: CookTriggerAdoptedArtifact;
+};
+
+export type CookTriggerClarificationLayout = {
+	title: string;
+	intro: string;
+	currentMissionHeading?: string;
+	currentMissionBody?: string;
+	candidateMissionHeading?: string;
+	candidateMissionBody?: string;
+	adoptedArtifactHeading?: string;
+	adoptedArtifactBody?: string;
+	actionsHeading: string;
+	actions: CookTriggerClarificationActionItem[];
+	footer: string;
+};
+
+export type CookTriggerRecoveryActionItem = {
+	id: CookTriggerRecoveryAction;
+	label: string;
+	description: string;
+};
+
+export type CookTriggerRecoveryLayout = {
+	title: string;
+	intro: string;
+	failureHeading?: string;
+	failureBody?: string;
+	actionsHeading: string;
+	actions: CookTriggerRecoveryActionItem[];
+	footer: string;
+};
+
+export type CookTriggerDecision = {
+	mode: NaturalLanguageCookTriggerMode;
+	action: "continue" | "handled" | "routed_to_cook";
+	reason: string;
+	classification?: CookTriggerClassification;
+	bypassReason?: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linimin/pi-letscook",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "description": "Pi package for long-running completion workflows with canonical .agent state, role-based subagents, continuity, and verification helpers.",
   "license": "MIT",
   "private": false,