@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.0

package/extensions/goal-detail.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { taskIndex } from "./goal-task-index.ts";
+import type { GoalRecord } from "./goal-record.ts";
+import type { GoalLedgerEvent } from "./goal-ledger.ts";
+
+export const GOAL_DETAIL_PAGE_CHARS = 4000;
+export type GoalDetailSection = "objective" | "tasks" | "history";
+export interface GoalDetailQuery { section: GoalDetailSection; task_id?: string; cursor?: string }
+export type GoalDetailPage = {ok: true; text: string; content: string; nextCursor?: string; totalChars: number} | {ok: false; text: string};
+
+interface DetailSource { source: string; key: string }
+const detailCache: Array<{inputs: readonly unknown[]; result: DetailSource}> = [];
+let detailCacheChars = 0;
+
+function compiledSource(goal: GoalRecord, query: GoalDetailQuery, events: readonly GoalLedgerEvent[], revision?: object): DetailSource | undefined {
+ const index = query.section === "tasks" ? taskIndex(goal.taskList?.tasks) : undefined;
+ const inputs = [goal.id, query.section, query.task_id, ...(query.section === "objective" ? [goal.objective, goal.verificationContract]
+  : query.section === "tasks" ? [index, goal.currentTaskId] : [revision])];
+ // Arbitrary caller-owned histories remain content checked; only the ledger can supply a generation.
+ const cacheable = query.section !== "history" || revision !== undefined;
+ if (cacheable) for (let i = detailCache.length - 1; i >= 0; i--) {
+  const entry = detailCache[i]!;
+  if (inputs.length === entry.inputs.length && inputs.every((value, j) => value === entry.inputs[j])) return entry.result;
+ }
+ let source: string;
+ if (query.section === "objective") source = `${goal.objective}${goal.verificationContract ? `\n\nVerification contract:\n${goal.verificationContract}` : ""}`;
+ else if (query.section === "history") source = events.filter(e => "goalId" in e && e.goalId === goal.id).map(e => JSON.stringify(e)).join("\n");
+ else {
+  const rows = index!.ordered;
+  const selected = query.task_id ? rows.find(row => row.task.id === query.task_id) : undefined;
+  if (query.task_id && !selected) return undefined;
+  source = (selected ? [selected] : rows).map(({task: {subtasks, ...task}, parentId}) => JSON.stringify({...task, parent_id: parentId, ...(task.id === goal.currentTaskId ? {current: true} : {})})).join("\n");
+ }
+ const key = createHash("sha256").update(JSON.stringify([goal.id, query.section, query.task_id, source])).digest("hex");
+ const result = {source, key};
+ // Full data remains available even when it exceeds the bounded shared page cache.
+ if (cacheable && source.length <= 16_000_000) {
+  while (detailCache.length >= 16 || detailCacheChars + source.length > 16_000_000) detailCacheChars -= detailCache.shift()!.result.source.length;
+  detailCache.push({inputs, result}); detailCacheChars += source.length;
+ }
+ return result;
+}
+
+/** Stable, lossless detail text. Ledger revisions are opaque generations, never timestamps. */
+export function goalDetailPage(goal: GoalRecord, query: GoalDetailQuery, events: readonly GoalLedgerEvent[] = [], historyRevision?: object): GoalDetailPage {
+ if (query.task_id !== undefined && query.section !== "tasks") return {ok: false, text: "task_id requires section=tasks."};
+ const compiled = compiledSource(goal, query, events, historyRevision);
+ if (!compiled) return {ok: false, text: `Task "${query.task_id}" not found.`};
+ const {source, key} = compiled;
+ let offset = 0;
+ if (query.cursor) {
+  try {
+   if (query.cursor.length > 256) throw new Error();
+   const parsed = JSON.parse(Buffer.from(query.cursor, "base64url").toString("utf8"));
+   if (parsed.v !== 1 || parsed.key !== key || !Number.isSafeInteger(parsed.offset) || parsed.offset < 0 || parsed.offset > source.length) throw new Error();
+   offset = parsed.offset;
+  } catch { return {ok: false, text: "Invalid or stale cursor: goal details changed or the section/task differs. Restart this section without cursor."}; }
+ }
+ let end = Math.min(offset + GOAL_DETAIL_PAGE_CHARS, source.length);
+ if (end < source.length && /[\uD800-\uDBFF]/.test(source[end - 1]!)) end--;
+ const content = source.slice(offset, end);
+ const nextCursor = end < source.length ? Buffer.from(JSON.stringify({v: 1, key, offset: end})).toString("base64url") : undefined;
+ const text = `${query.section} for ${goal.id} (${offset}–${end}/${source.length} chars)\n${content}${nextCursor ? `\nMore content: repeat this section/task with cursor="${nextCursor}".` : "\nEnd of section."}`;
+ return {ok: true, text, content, nextCursor, totalChars: source.length};
+}

package/extensions/goal-dialog-controls.ts

@@ -0,0 +1,31 @@
+import { getKeybindings, isKittyProtocolActive, matchesKey } from "@earendil-works/pi-tui";
+import { GOAL_DIALOG_KEYS, bindingKeys, sameGoalKey, type GoalDialogAction, type GoalKeybinding } from "./goal-controls.ts";
+import { loadGoalSettings, formatGoalKeybinding } from "./goal-settings.ts";
+
+/** Snapshot the dialog's controls once; the modal owns input until it closes. */
+export function goalDialogControls(cwd: string) {
+	const configured = loadGoalSettings(cwd).keybindings?.dialog;
+	const binding = (action: GoalDialogAction) => configured?.[action] ?? GOAL_DIALOG_KEYS[action];
+	const hint = (action: GoalDialogAction) => action === "toggleAuditor" && binding(action) === "a" ? "a" : formatGoalKeybinding(binding(action));
+	let editorKeys: string[] = [];
+	try { editorKeys = Object.entries(getKeybindings().getResolvedBindings()).filter(([id]) => /^tui\.(editor|input)\./.test(id)).flatMap(([, keys]) => bindingKeys(keys)); } catch { /* Older keymap inspection is optional. */ }
+	const safeWhileEditing = (key: string) => {
+		const textKey = key.replace(/^shift\+/, "");
+		if (textKey.length === 1 || textKey === "space" || key === "left" || key === "right") return false;
+		// Tab has always switched questions from the answer editor.
+		return key === "tab" || key === "shift+tab" || !editorKeys.some(native => sameGoalKey(native, key, isKittyProtocolActive()));
+	};
+	const editingBindings = new Map(Object.keys(GOAL_DIALOG_KEYS).map(action => {
+		const id = action as GoalDialogAction;
+		return [id, bindingKeys(binding(id)).filter(safeWhileEditing)] as const;
+	}));
+	const matches = (data: string, action: GoalDialogAction, editing = false) => (editing ? editingBindings.get(action)! : bindingKeys(binding(action))).some(key => matchesKey(data, key));
+	return {
+		matches,
+		cancelEditing: (data: string) => matchesKey(data, "escape") || matches(data, "cancel", true),
+		editorCancelHint: () => formatGoalKeybinding([...new Set(["escape", ...editingBindings.get("cancel")!])] as GoalKeybinding),
+		hint,
+		navigationHint: () => hint("up") === "↑" && hint("down") === "↓" ? "↑↓" : `${hint("up")} / ${hint("down")}`,
+		pagingHint: () => `${hint("pageUp")}/${hint("pageDown")}`.replaceAll("PageUp", "PgUp").replaceAll("PageDown", "PgDn"),
+	};
+}

package/extensions/goal-draft.ts

@@ -0,0 +1,244 @@
+import { commandInstructions, type GoalCommands } from "./goal-controls.ts";
+import type { GoalTask, GoalTaskList } from "./goal-record.ts";
+import { promptSafeObjective } from "./goal-contract.ts";
+import { renderConfirmationTasks } from "./goal-task-confirmation.ts";
+
+export type GoalDraftingFocus = "goal" | "sisyphus";
+
+export interface GoalConfirmationIntentLike {
+	focus: GoalDraftingFocus;
+	originalTopic: string;
+	startedAt?: number;
+}
+
+export interface DraftProposalInput {
+	intent: GoalConfirmationIntentLike | null;
+	hasUnfinishedGoal: boolean;
+	objective: string;
+	sisyphus?: boolean;
+	draftId?: string;
+}
+
+export type DraftProposalValidation =
+	| { ok: true; objective: string; expectedSisyphus: boolean }
+	| { ok: false; message: string; clearDrafting?: boolean };
+
+export type ToolGateDecision =
+	| { block: false }
+	| { block: true; reason: string };
+
+// ── Shared formatting helpers ──────────────────────────────────────────────
+function formatModeLabel(sisyphus: boolean): string {
+	return sisyphus ? "Sisyphus (prompt/criteria style)" : "Normal goal";
+}
+
+function formatPrefixedLines(content: string): string[] {
+	const lines: string[] = [];
+	for (const rawLine of content.split("\n")) {
+		const trimmed = rawLine.trim();
+		if (!trimmed) continue;
+		if (trimmed.startsWith("│")) {
+			lines.push(rawLine);
+		} else {
+			lines.push(`│   ${rawLine}`);
+		}
+	}
+	return lines;
+}
+
+function formatSection(title: string, content: string): string[] {
+	const body = formatPrefixedLines(content);
+	return ["", `─── ${title} ───`, "", ...body];
+}
+
+export function buildDraftConfirmationText(args: {
+	focus: GoalDraftingFocus;
+	originalTopic: string;
+	objective: string;
+	autoContinue: boolean;
+}): string {
+	const lines: string[] = [];
+	lines.push("● Goal draft ready for confirmation.");
+	lines.push("");
+	lines.push("─── Draft Details ───");
+	lines.push(`│   Mode: ${formatModeLabel(args.focus === "sisyphus")}`);
+	lines.push(`│   Auto-continue: ${args.autoContinue ? "yes" : "no"}`);
+	lines.push(...formatSection("Original Topic", args.originalTopic.trim()));
+	lines.push(...formatSection("Proposed Goal", args.objective));
+	return lines.join("\n");
+}
+
+export function buildTweakConfirmationText(args: {
+	currentObjective: string;
+	newObjective: string;
+	changeSummary: string;
+	sisyphus: boolean;
+	tasks?: GoalTask[];
+}): string {
+	const lines: string[] = [];
+	lines.push("● Goal tweak ready for confirmation.");
+	lines.push("");
+	lines.push("─── Draft Details ───");
+	lines.push(`│   Mode: ${formatModeLabel(args.sisyphus)}`);
+	lines.push(...formatSection("Change", args.changeSummary));
+	lines.push(...formatSection("Current Objective", args.currentObjective));
+	lines.push(...formatSection("Proposed New Objective", args.newObjective));
+	if (args.tasks && args.tasks.length > 0) {
+		const taskLines = renderConfirmationTasks(args.tasks, 0);
+		lines.push("");
+		lines.push(`┌─ TASKS ─────────────────────────────────────┐`);
+		for (const tl of taskLines) lines.push(tl);
+		lines.push(`└──────────────────────────────────────────────┘`);
+	}
+	return lines.join("\n");
+}
+
+export function evaluateDraftingToolGate(args: {
+	toolName: string;
+	draftingFocus?: GoalDraftingFocus | null;
+	tweakDraftingGoalId?: string | null;
+	activeGoalId?: string | null;
+	proposeToolName?: string;
+	tweakApplyToolName?: string;
+	getGoalToolName?: string;
+}): ToolGateDecision {
+	// Goal confirmation is prompt-guided, not runtime-enforced. The agent should
+	// avoid substantive work before confirmation, but minimal reconnaissance is allowed.
+	void args;
+	return { block: false };
+}
+
+export function validateGoalDraftProposal(input: DraftProposalInput): DraftProposalValidation {
+	if (input.intent === null) {
+		return {
+			ok: false,
+			message: "propose_goal_draft REJECTED: no /goal, /sisyphus, or /goal-tweak guided draft is in progress.",
+		};
+	}
+
+	const expectedSisyphus = input.intent.focus === "sisyphus";
+	const actualSisyphus = input.sisyphus === true;
+	if (actualSisyphus !== expectedSisyphus) {
+		return {
+			ok: false,
+			message: `propose_goal_draft REJECTED (focus gate): the user invoked ${input.intent.focus === "sisyphus" ? "/sisyphus" : "/goal"} but you passed sisyphus=${actualSisyphus}. Set sisyphus=${expectedSisyphus} to match their choice.`,
+		};
+	}
+
+	const objective = input.objective.trim();
+	if (!objective) {
+		return { ok: false, message: "propose_goal_draft REJECTED: objective is empty." };
+	}
+
+	return { ok: true, objective, expectedSisyphus };
+}
+
+export function goalDraftingPrompt(topic: string, focus: GoalDraftingFocus, commands?: GoalCommands): string {
+	const safeTopic = promptSafeObjective(topic.trim() || "(no topic provided — ask the user what they want to accomplish)");
+	const header = focus === "sisyphus"
+		? "[GOAL CONFIRMATION focus=sisyphus]\nThe user invoked Sisyphus intent discussion (/sisyphus). Help turn their request into a confirmed goal contract. Do NOT start substantive work yet."
+		: "[GOAL CONFIRMATION focus=goal]\nThe user invoked guided goal drafting (/goal). Help turn their request into a confirmed goal contract. Do NOT start substantive work yet.";
+
+	const commonProtocol = [
+		"Confirmation protocol:",
+		"- Treat this as a lightweight conversation with the user, not a separate long-running runtime phase.",
+		"- If the topic is vague, ask one focused question with a recommended default. Use goal_question or goal_questionnaire when a structured answer would help, but plain conversation is acceptable.",
+		"- Targeted read-only research is allowed when it helps define a better goal contract; do not start implementation before confirmation.",
+		"- If the topic is already concrete, you may proceed directly to propose_goal_draft.",
+		"- The goal contract should make the objective, success criteria, boundaries, constraints, and blocker rule explicit.",
+		"- Keep grilling assumptions until the objective, success criteria, boundaries, constraints, and blocker rule are clear enough to confirm.",
+		"- If the objective naturally decomposes into trackable milestones, you MUST include the task list in the `tasks` parameter of `propose_goal_draft` so the user can accept both goal and tasks in a single confirmation dialog. Do NOT propose the goal without tasks and then call `propose_task_list` separately.",
+		"- For simple single-step goals, no task list is required. The `tasks` parameter can be omitted.",
+		"- After goal creation, `propose_task_list` is still available for user-requested task additions or structural changes.",
+		"- propose_goal_draft opens the user's Confirm / Continue Chatting dialog. Confirm creates and focuses the goal; Continue Chatting means keep refining through normal proposal cycles.",
+		"- Call propose_goal_draft with the complete structured proposal. The tool call renderer is the scrollable, complete human presentation of the objective and task tree — do NOT duplicate the full proposal in a preceding prose message. A brief orientation sentence is fine.",
+		"- create_goal is not a shortcut. Direct create_goal calls are rejected so the user keeps explicit say in goal creation.",
+	];
+
+	const goalFocusItems = [
+		"For /goal, propose a normal goal in this shape when ready:",
+		"=== Goal ===",
+		"Objective: <one-sentence outcome>",
+		"Success criteria: <observable evidence the goal is done>",
+		"Boundaries: <in scope / out of scope>",
+		"Constraints: <hard rules>",
+		"Verification contract: <optional — what verification evidence is required before marking complete, e.g. 'Run npm test (0 failures), grep for remaining references, re-read requirements and confirm every item is addressed'>",
+		"If blocked: <default = stop and ask the user>",
+		"Call propose_goal_draft with sisyphus=false and autoContinue=true unless the user asked otherwise.",
+	];
+
+	const sisyphusFocusItems = [
+		"For /sisyphus, remember that Sisyphus is a prompt/criteria style, not a separate step-counter mechanism.",
+		"Propose a Sisyphus goal in this shape when ready:",
+		"=== Sisyphus Goal ===",
+		"Objective: <one-sentence outcome>",
+		"Success criteria: <observable evidence the whole ordered goal is done>",
+		"Boundaries: <in scope / out of scope>",
+		"Constraints: <hard rules, files not to touch, etc.>",
+		"Verification contract: <optional — what verification evidence is required before marking complete>",
+		"Ordered steps: <preserve the user's requested steps and ordering; do not add preflight or reconnaissance steps they did not ask for>",
+		"If blocked / unclear / failing: <default = stop and ask the user>",
+		"Sisyphus reminder: Work patiently and sequentially. No rushing, no unrequested preflight steps, no improvising around blockers.",
+		"Call propose_goal_draft with sisyphus=true and autoContinue=true unless the user asked otherwise.",
+	];
+
+	return [
+		commandInstructions(header, commands),
+		"",
+		"Topic the user provided:",
+		"<goal_topic>",
+		safeTopic,
+		"</goal_topic>",
+		"",
+		...commonProtocol,
+		"",
+		...(focus === "sisyphus" ? sisyphusFocusItems : goalFocusItems).map(line => commandInstructions(line, commands)),
+	].join("\n");
+}
+
+
+// ── §14 durable proposal summary ─────────────────────────────────────────────
+
+export interface ProposalSummaryArgs {
+	objective: string;
+	taskList?: GoalTaskList;
+	verificationContract?: string;
+	autoContinue: boolean;
+	auditorEnabled: boolean;
+}
+
+/**
+ * Durable proposal summary written to the terminal transcript (plan §14):
+ * proposed objective, proposed plan (numbered top-level tasks), verification,
+ * automatic-continuation state, and auditor state. Produced for every proposal
+ * outcome (confirm / continue refining / cancel) so the summary is always part
+ * of the conversation, not only the confirmation dialog.
+ */
+export function buildProposalSummary(args: ProposalSummaryArgs): string {
+	const lines: string[] = ["Proposed objective:", args.objective.trim()];
+	if (args.taskList && args.taskList.tasks.length > 0) {
+		lines.push("", "Proposed plan:");
+		lines.push(...renderProposalPlan(args.taskList.tasks));
+	}
+	if (args.verificationContract?.trim()) {
+		lines.push("", "Verification:", args.verificationContract.trim());
+	}
+	lines.push("", `Automatic continuation: ${args.autoContinue ? "enabled" : "disabled"}`);
+	lines.push(`Independent auditor: ${args.auditorEnabled ? "enabled" : "disabled"}`);
+	return lines.join("\n");
+}
+
+function renderProposalPlan(tasks: GoalTask[]): string[] {
+	const lines: string[] = [];
+	let index = 1;
+	for (const t of tasks) {
+		lines.push(`${index}. ${t.title}`);
+		if (t.subtasks && t.subtasks.length > 0) {
+			for (const child of t.subtasks) {
+				lines.push(`   - ${child.title}`);
+			}
+		}
+		index++;
+	}
+	return lines;
+}