@linimin/pi-letscook 0.1.56 → 0.1.58

package/extensions/completion/proposal.ts

@@ -27,7 +27,7 @@ export type ContextProposalAlternate = {
 	analysis: ContextProposalAnalysis;
 	goalText: string;
 	basisPreview: string;
-	source: "session" | "analyst";
+	source: "session" | "analyst" | "handoff_capsule";
 };
 
 export type ContextProposal = ContextProposalAlternate & {
@@ -41,6 +41,48 @@ export type RecentDiscussionEntry = {
 	text: string;
 };
 
+export type RecentSessionMessage = RecentDiscussionEntry & {
+	messageId?: string;
+	timestampMs?: number;
+	isCommand: boolean;
+};
+
+export type CookHandoffCapsule = {
+	kind: "cook_handoff";
+	source: "primary_agent";
+	captured_at: string;
+	source_turn_id: string;
+	mission: string;
+	scope: string[];
+	constraints: string[];
+	non_goals: string[];
+	acceptance: string[];
+	risks: string[];
+	notes: string[];
+	handoff_kind: "implementation_workflow_handoff";
+	first_slice_goal: string;
+	first_slice_non_goals: string[];
+	implementation_surfaces: string[];
+	verification_commands: string[];
+	why_this_slice_first: string;
+	task_type?: string;
+	evaluation_profile?: string;
+	why_cook_now?: string;
+};
+
+export type CookHandoffProposalAssessment =
+	| {
+		status: "none";
+	  }
+	| {
+		status: "startable";
+		proposal: ContextProposal;
+	  }
+	| {
+		status: "fresh_but_not_startable";
+		message: string;
+	  };
+
 export type ContextProposalDecision = {
 	missionAnchor: string;
 	goalText: string;
@@ -113,6 +155,10 @@ function localAsStringArray(value: unknown): string[] {
 		: [];
 }
 
+function localAsNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
 function localIsRecord(value: unknown): value is JsonRecord {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -300,11 +346,12 @@ export function missionAnchorsLikelyEquivalent(left: string, right: string): boo
 	return missionAnchorBigramOverlapRatio(leftTokens, rightTokens) >= 0.5;
 }
 
-export function collectRecentDiscussionEntries(ctx: { sessionManager: any }, deps: {
+export function collectRecentSessionMessages(ctx: { sessionManager: any }, deps: {
 	isRecord: (value: unknown) => boolean;
 	asString?: (value: unknown) => string | undefined;
+	asNumber?: (value: unknown) => number | undefined;
 	isStaleContextError?: (error: unknown) => boolean;
-}, limit = 8): RecentDiscussionEntry[] {
+}, limit = 24): RecentSessionMessage[] {
 	let branch: any[] = [];
 	try {
 		branch = ctx.sessionManager?.getBranch?.() ?? [];
@@ -313,27 +360,42 @@ export function collectRecentDiscussionEntries(ctx: { sessionManager: any }, dep
 		throw error;
 	}
 	const asStringValue = deps.asString ?? localAsString;
-	const entries: RecentDiscussionEntry[] = [];
+	const asNumberValue = deps.asNumber ?? localAsNumber;
+	const entries: RecentSessionMessage[] = [];
 	for (let index = branch.length - 1; index >= 0; index -= 1) {
 		const entry = branch[index];
 		if (!deps.isRecord(entry) || entry.type !== "message" || !deps.isRecord(entry.message)) continue;
 		const message = entry.message as JsonRecord;
-		let text = "";
-		let role: RecentDiscussionEntry["role"] | undefined;
 		const messageRole = asStringValue(message.role);
-		if (messageRole === "user" || messageRole === "custom") {
-			text = extractTextFromMessageContent(message.content);
-			role = messageRole;
-		}
-		if (!text || !role) continue;
+		if (messageRole !== "user" && messageRole !== "assistant" && messageRole !== "custom" && messageRole !== "summary") continue;
+		const text = extractTextFromMessageContent(message.content);
+		if (!text) continue;
 		const trimmed = text.trim();
-		if (!trimmed || /^\/(?:cook|complete)\b/i.test(trimmed)) continue;
-		entries.push({ role, text: trimmed });
+		if (!trimmed) continue;
+		entries.push({
+			role: messageRole as RecentDiscussionEntry["role"],
+			text: trimmed,
+			messageId: asStringValue((entry as JsonRecord).id),
+			timestampMs: asNumberValue(message.timestamp),
+			isCommand: /^\//.test(trimmed),
+		});
 		if (entries.length >= limit) break;
 	}
 	return entries;
 }
 
+export function collectRecentDiscussionEntries(ctx: { sessionManager: any }, deps: {
+	isRecord: (value: unknown) => boolean;
+	asString?: (value: unknown) => string | undefined;
+	asNumber?: (value: unknown) => number | undefined;
+	isStaleContextError?: (error: unknown) => boolean;
+}, limit = 8): RecentDiscussionEntry[] {
+	return collectRecentSessionMessages(ctx, deps, Math.max(limit * 3, limit))
+		.filter((entry) => (entry.role === "user" || entry.role === "custom") && !entry.isCommand)
+		.slice(0, limit)
+		.map((entry) => ({ role: entry.role, text: entry.text }));
+}
+
 export function serializeRecentDiscussionEntries(entries: RecentDiscussionEntry[]): string {
 	return entries
 		.slice()
@@ -1182,6 +1244,270 @@ export function extractContextProposalFromStructuredSession(
 	return parseStrictStructuredSessionProposal(structuredTexts.join("\n\n"), projectName, deps);
 }
 
+const COOK_HANDOFF_BLOCK_REGEX = /```cook_handoff\s*([\s\S]*?)```/giu;
+const COOK_HANDOFF_MAX_AGE_MS = 45 * 60 * 1000;
+const COOK_HANDOFF_MAX_LATER_NON_COMMAND_MESSAGES = 2;
+const COOK_HANDOFF_NEGATIVE_MISSION_REGEX =
+	/(?:\b(?:do not|don't|dont|not|never|avoid|skip|refuse|recognize that|suppress|ignore|block|prevent)\b|(?:不要|別|别|勿|禁止|避免|忽略|阻止))/iu;
+const COOK_HANDOFF_WORKFLOW_ONLY_ACCEPTANCE_REGEX =
+	/(?:\b(?:confirm|discuss|clarify|decide|review|align(?: on)?|agree(?: on)?|explain|summari(?:s|z)e|describe|plan|proposal|spec(?:ification)?|design(?: doc(?:ument)?)?|next step|handoff|workflow|readiness)\b|(?:確認|确认|討論|讨论|釐清|厘清|決定|决定|審查|审查|對齊|对齐|同意|说明|說明|總結|总结|描述|規劃|规划|提案|方案|工作流|就緒|就绪))/iu;
+const COOK_HANDOFF_VERIFICATION_ACCEPTANCE_REGEX =
+	/(?:\b(?:test|tests|testing|verify|verification|validated?|regression|coverage|assert(?:ion)?s?|check|checks|smoke|snapshot(?:s)?)\b|(?:測試|测试|驗證|验证|回歸|回归|覆蓋|覆盖|斷言|断言|檢查|检查|快照))/iu;
+const COOK_HANDOFF_VERIFICATION_ACTION_REGEX =
+	/(?:\b(?:add|update|keep|run|rerun|cover|verify|validate|check|assert|exercise|prove)\b|(?:新增|更新|保持|執行|执行|重跑|覆蓋|覆盖|驗證|验证|檢查|检查|斷言|断言|證明|证明))/iu;
+
+function parseCookHandoffCapsulesFromText(
+	text: string,
+	messageId: string | undefined,
+	timestampMs: number | undefined,
+	deps: Pick<ProposalParseDeps, "asString" | "asStringArray">,
+): CookHandoffCapsule[] {
+	const capsules: CookHandoffCapsule[] = [];
+	for (const match of text.matchAll(COOK_HANDOFF_BLOCK_REGEX)) {
+		const rawJson = deps.asString(match[1]);
+		if (!rawJson) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(rawJson);
+		} catch {
+			continue;
+		}
+		if (!localIsRecord(parsed)) continue;
+		if (deps.asString(parsed.kind) !== "cook_handoff") continue;
+		if (deps.asString(parsed.source) !== "primary_agent") continue;
+		if (deps.asString(parsed.handoff_kind) !== "implementation_workflow_handoff") continue;
+		const mission = deps.asString(parsed.mission);
+		const firstSliceGoal = deps.asString(parsed.first_slice_goal ?? parsed.firstSliceGoal);
+		const whyThisSliceFirst = deps.asString(parsed.why_this_slice_first ?? parsed.whyThisSliceFirst);
+		if (!mission || !firstSliceGoal || !whyThisSliceFirst) continue;
+		const scope = deps.asStringArray(parsed.scope);
+		const constraints = deps.asStringArray(parsed.constraints);
+		const nonGoals = deps.asStringArray(parsed.non_goals ?? parsed.nonGoals);
+		const acceptance = deps.asStringArray(parsed.acceptance);
+		const risks = deps.asStringArray(parsed.risks);
+		const notes = deps.asStringArray(parsed.notes);
+		const firstSliceNonGoals = deps.asStringArray(parsed.first_slice_non_goals ?? parsed.firstSliceNonGoals);
+		const implementationSurfaces = deps.asStringArray(parsed.implementation_surfaces ?? parsed.implementationSurfaces);
+		const verificationCommands = deps.asStringArray(parsed.verification_commands ?? parsed.verificationCommands);
+		const capturedAt = deps.asString(parsed.captured_at) ?? (timestampMs ? new Date(timestampMs).toISOString() : undefined);
+		const sourceTurnId = deps.asString(parsed.source_turn_id) ?? messageId;
+		if (!capturedAt || !sourceTurnId) continue;
+		capsules.push({
+			kind: "cook_handoff",
+			source: "primary_agent",
+			captured_at: capturedAt,
+			source_turn_id: sourceTurnId,
+			mission,
+			scope,
+			constraints,
+			non_goals: nonGoals,
+			acceptance,
+			risks,
+			notes,
+			handoff_kind: "implementation_workflow_handoff",
+			first_slice_goal: firstSliceGoal,
+			first_slice_non_goals: firstSliceNonGoals,
+			implementation_surfaces: implementationSurfaces,
+			verification_commands: verificationCommands,
+			why_this_slice_first: whyThisSliceFirst,
+			task_type: deps.asString(parsed.task_type),
+			evaluation_profile: deps.asString(parsed.evaluation_profile),
+			why_cook_now: deps.asString(parsed.why_cook_now),
+		});
+	}
+	return capsules;
+}
+
+function buildCookHandoffBasisPreview(capsule: CookHandoffCapsule): string {
+	const parts = [
+		capsule.mission,
+		...capsule.scope,
+		...capsule.constraints,
+		...capsule.non_goals,
+		...capsule.acceptance,
+		`first_slice_goal: ${capsule.first_slice_goal}`,
+		...capsule.first_slice_non_goals.map((item) => `first_slice_non_goals: ${item}`),
+		...capsule.implementation_surfaces.map((item) => `implementation_surfaces: ${item}`),
+		...capsule.verification_commands.map((item) => `verification_commands: ${item}`),
+		`why_this_slice_first: ${capsule.why_this_slice_first}`,
+	];
+	if (capsule.why_cook_now) parts.push(`why_cook_now: ${capsule.why_cook_now}`);
+	return parts.join("\n").trim();
+}
+
+function cookHandoffAcceptanceItemIsRepoChangeOrVerificationOriented(item: string): boolean {
+	const normalized = normalizeProposalLine(item);
+	if (!normalized) return false;
+	if (hasExplicitPlanningOnlyDeliverable([normalized])) return false;
+	if (hasClearNoImplementationSignal([normalized])) return false;
+	if (implementationMissionSourceCandidateText(normalized)) return true;
+	if (COOK_HANDOFF_WORKFLOW_ONLY_ACCEPTANCE_REGEX.test(normalized)) return false;
+	return COOK_HANDOFF_VERIFICATION_ACCEPTANCE_REGEX.test(normalized) && COOK_HANDOFF_VERIFICATION_ACTION_REGEX.test(normalized);
+}
+
+function cookHandoffAcceptanceIsRepoChangeOriented(capsule: CookHandoffCapsule): boolean {
+	if (capsule.acceptance.length === 0) return false;
+	return capsule.acceptance.some((item) => cookHandoffAcceptanceItemIsRepoChangeOrVerificationOriented(item));
+}
+
+function cookHandoffStartabilityFailures(
+	capsule: CookHandoffCapsule,
+	deps: Pick<ProposalParseDeps, "normalizeMissionAnchorText" | "isWeakMissionAnchor">,
+): string[] {
+	const failures: string[] = [];
+	const mission = deps.normalizeMissionAnchorText(capsule.mission);
+	if (!mission || deps.isWeakMissionAnchor(mission)) failures.push("mission is missing a concrete implementation anchor");
+	else if (COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(mission)) failures.push("mission is negative or workflow-suppression-only");
+	if (capsule.scope.length === 0) failures.push("scope is empty");
+	if (capsule.acceptance.length === 0) failures.push("acceptance is empty");
+	else if (!cookHandoffAcceptanceIsRepoChangeOriented(capsule)) {
+		failures.push("acceptance is not anchored to concrete repo changes or verification");
+	}
+	const firstSliceGoal = deps.normalizeMissionAnchorText(capsule.first_slice_goal);
+	if (!firstSliceGoal || deps.isWeakMissionAnchor(firstSliceGoal) || COOK_HANDOFF_NEGATIVE_MISSION_REGEX.test(firstSliceGoal)) {
+		failures.push("first_slice_goal is not a bounded implementation slice");
+	} else if (hasExplicitPlanningOnlyDeliverable([capsule.first_slice_goal]) || hasClearNoImplementationSignal([capsule.first_slice_goal])) {
+		failures.push("first_slice_goal is planning-only instead of a repo-change slice");
+	}
+	if (capsule.implementation_surfaces.length === 0) failures.push("implementation_surfaces is empty");
+	if (capsule.verification_commands.length === 0) failures.push("verification_commands is empty");
+	return failures;
+}
+
+function buildNonStartableCookHandoffMessage(failures: string[]): string {
+	return [
+		"/cook failed closed because a fresh explicit primary-agent handoff exists, but it is not concrete enough to start implementation workflow yet.",
+		"Tighten the handoff in the main chat so it names a bounded first implementation slice, repo-change-oriented acceptance, implementation_surfaces, and verification_commands, then rerun /cook.",
+		`Blocking details: ${failures.join("; ")}.`,
+	].join(" ");
+}
+
+function isStartableCookHandoffCapsule(
+	capsule: CookHandoffCapsule,
+	deps: Pick<ProposalParseDeps, "normalizeMissionAnchorText" | "isWeakMissionAnchor">,
+): boolean {
+	return cookHandoffStartabilityFailures(capsule, deps).length === 0;
+}
+
+function laterMessagesInvalidateCookHandoff(
+	laterMessages: RecentSessionMessage[],
+	deps: Pick<ProposalParseDeps, "stripCodeBlocks">,
+): boolean {
+	const laterNonCommandMessages = laterMessages.filter((entry) => !entry.isCommand);
+	if (laterNonCommandMessages.length > COOK_HANDOFF_MAX_LATER_NON_COMMAND_MESSAGES) return true;
+	return laterNonCommandMessages.some((entry) => {
+		if (entry.role === "summary") return false;
+		if (!hasRecentDiscussionImplementationIntent(entry.text, deps.stripCodeBlocks)) return false;
+		return true;
+	});
+}
+
+function cookHandoffIsFreshEnough(capsule: CookHandoffCapsule, laterMessages: RecentSessionMessage[]): boolean {
+	const capturedAtMs = Date.parse(capsule.captured_at);
+	if (!Number.isFinite(capturedAtMs)) return false;
+	const laterTimestamps = laterMessages.map((entry) => entry.timestampMs).filter((value): value is number => value !== undefined);
+	if (laterTimestamps.length === 0) return true;
+	return Math.max(...laterTimestamps) - capturedAtMs <= COOK_HANDOFF_MAX_AGE_MS;
+}
+
+function buildContextProposalFromCookHandoffCapsule(
+	capsule: CookHandoffCapsule,
+	projectName: string,
+	deps: ProposalParseDeps,
+): ContextProposal | undefined {
+	if (!isStartableCookHandoffCapsule(capsule, deps)) return undefined;
+	const constraints = uniqueProposalItems([...capsule.constraints, ...capsule.non_goals]);
+	const mission = deps.assessMissionAnchor(capsule.mission, projectName).derived;
+	const goalText = buildContextProposalGoalText({
+		mission,
+		scope: capsule.scope,
+		constraints,
+		acceptance: capsule.acceptance,
+	});
+	const proposal: ContextProposal = {
+		mission,
+		scope: [...capsule.scope],
+		constraints,
+		acceptance: [...capsule.acceptance],
+		analysis: finalizeContextProposalAnalysis(
+			{
+				taskType: capsule.task_type,
+				evaluationProfile: capsule.evaluation_profile,
+				critique: [
+					...capsule.notes,
+					`First slice goal: ${capsule.first_slice_goal}`,
+					...(capsule.first_slice_non_goals.length > 0 ? [`First slice non-goals: ${capsule.first_slice_non_goals.join(" | ")}`] : []),
+					...(capsule.implementation_surfaces.length > 0 ? [`Implementation surfaces: ${capsule.implementation_surfaces.join(" | ")}`] : []),
+					...(capsule.verification_commands.length > 0 ? [`Verification commands: ${capsule.verification_commands.join(" | ")}`] : []),
+					`Why this slice first: ${capsule.why_this_slice_first}`,
+					...(capsule.why_cook_now ? [`Primary-agent /cook handoff rationale: ${capsule.why_cook_now}`] : []),
+				],
+				risks: capsule.risks,
+				possibleNoise: [],
+				alternateMissions: [],
+				suppressedCompletedTopics: [],
+				suppressedNegatedTopics: [],
+			},
+			[
+				mission,
+				goalText,
+				capsule.mission,
+				...capsule.scope,
+				...constraints,
+				...capsule.acceptance,
+				capsule.first_slice_goal,
+				...capsule.first_slice_non_goals,
+				...capsule.implementation_surfaces,
+				...capsule.verification_commands,
+				capsule.why_this_slice_first,
+			],
+		),
+		goalText,
+		basisPreview: buildCookHandoffBasisPreview(capsule),
+		source: "handoff_capsule",
+		alternateProposals: [],
+	};
+	return finalizeContextProposal(proposal, projectName, deps);
+}
+
+export function assessLatestCookHandoffProposal(
+	recentMessages: RecentSessionMessage[],
+	projectName: string,
+	deps: ProposalParseDeps,
+): CookHandoffProposalAssessment {
+	for (let index = 0; index < recentMessages.length; index += 1) {
+		const entry = recentMessages[index];
+		if (entry.role !== "assistant" || entry.isCommand) continue;
+		const capsules = parseCookHandoffCapsulesFromText(entry.text, entry.messageId, entry.timestampMs, deps);
+		if (capsules.length === 0) continue;
+		for (let capsuleIndex = capsules.length - 1; capsuleIndex >= 0; capsuleIndex -= 1) {
+			const capsule = capsules[capsuleIndex];
+			const laterMessages = recentMessages.slice(0, index);
+			if (!cookHandoffIsFreshEnough(capsule, laterMessages)) continue;
+			if (laterMessagesInvalidateCookHandoff(laterMessages, deps)) continue;
+			const failures = cookHandoffStartabilityFailures(capsule, deps);
+			if (failures.length > 0) {
+				return {
+					status: "fresh_but_not_startable",
+					message: buildNonStartableCookHandoffMessage(failures),
+				};
+			}
+			const proposal = buildContextProposalFromCookHandoffCapsule(capsule, projectName, deps);
+			if (proposal) return { status: "startable", proposal };
+		}
+	}
+	return { status: "none" };
+}
+
+export function extractLatestCookHandoffProposal(
+	recentMessages: RecentSessionMessage[],
+	projectName: string,
+	deps: ProposalParseDeps,
+): ContextProposal | undefined {
+	const assessment = assessLatestCookHandoffProposal(recentMessages, projectName, deps);
+	return assessment.status === "startable" ? assessment.proposal : undefined;
+}
+
 export async function deriveCookContextProposalFromRecentDiscussion(
 	projectName: string,
 	recentEntries: RecentDiscussionEntry[],

package/package.json

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