@zhushanwen/pi-goal 0.2.0 → 0.4.0

package/src/state.ts

@@ -1,250 +0,0 @@
-/**
- * Goal 状态定义和管理
- *
- * 状态机参考 Codex /goal 的 6 种状态：
- *   Active → Paused (用户暂停)
- *   Active → Blocked (连续 stall)
- *   Active → Complete (目标达成)
- *   Active → BudgetLimited (token 预算耗尽)
- *   Active → TimeLimited (时间预算耗尽)
- *   Active → Cancelled (用户清除)
- *
- * 终态（不可被任何状态覆盖）：Complete, BudgetLimited, TimeLimited, Cancelled
- * Paused/Blocked 可被 Active 覆盖（用户 resume）
- */
-
-import { MS_PER_SECOND } from "./constants";
-
-// ── Cross-extension API type ─────────────────────────────
-
-/** Budget options for external goal initialization. */
-export interface GoalExternalBudget {
-	tokenBudget?: number;
-	timeBudgetMinutes?: number;
-	maxTurns?: number;
-}
-
-/**
- * Function signature for programmatically initializing a goal from another extension.
- * Exposed via `pi.__goalInit` by the goal extension.
- */
-export type GoalExternalInit = (
-	objective: string,
-	tasks: string[],
-	budget?: GoalExternalBudget,
-) => boolean;
-
-// ── Goal 状态枚举 ──────────────────────────────────────
-
-export type GoalStatus =
-	| "active"
-	| "paused"
-	| "blocked"
-	| "complete"
-	| "budget_limited"
-	| "time_limited"
-	| "cancelled";
-
-// 终态：不可被其他状态覆盖
-const TERMINAL_STATUSES: ReadonlySet<GoalStatus> = new Set([
-	"complete",
-	"budget_limited",
-	"time_limited",
-	"cancelled",
-]);
-
-// ── 任务数据结构 ──────────────────────────────────────
-
-export type TaskStatus = "pending" | "in_progress" | "completed" | "cancelled";
-
-export type SubtaskStatus = "pending" | "in_progress" | "completed";
-
-export const SUBTASK_STATUSES: readonly SubtaskStatus[] = [
-	"pending",
-	"in_progress",
-	"completed",
-] as const;
-
-export interface Subtask {
-	id: number;
-	text: string;
-	status: SubtaskStatus;
-	lastUpdatedTurn: number;
-}
-
-export const GOAL_TASK_STATUSES: readonly TaskStatus[] = [
-	"pending",
-	"in_progress",
-	"completed",
-	"cancelled",
-] as const;
-
-export function isTerminalTaskStatus(status: TaskStatus): boolean {
-	return status === "completed" || status === "cancelled";
-}
-
-export interface GoalTask {
-	id: number;
-	description: string;
-	status: TaskStatus;
-	evidence?: string; // 完成时的证据描述
-	subtasks?: Subtask[];
-	lastUpdatedTurn: number;
-}
-
-// ── 预算配置 ──────────────────────────────────────────
-
-export interface BudgetConfig {
-	tokenBudget?: number; // token 预算上限 (undefined = 不限制)
-	timeBudgetMinutes?: number; // 时间预算 (分钟, undefined = 不限制)
-	maxStallTurns: number; // 连续无进展轮数阈值，触发 blocked
-	maxTurns: number; // 最大 turn 数上限
-}
-
-// ── 运行时状态（也是持久化数据格式，保持统一）─────────────
-
-export interface GoalRuntimeState {
-	goalId: string;
-	objective: string;
-	status: GoalStatus;
-	tasks: GoalTask[];
-	turnCount: number;
-	stallCount: number;
-	tokensUsed: number;
-	timeStartedAt: number; // Date.now() timestamp
-	timeUsedSeconds: number; // 累计使用秒数（不含当前活跃段）
-	budget: BudgetConfig;
-	lastProgressTurn: number; // 上次有进展的 turn number
-	budgetLimitSteeringSent: boolean; // 是否已发送预算耗尽 steering
-	objectiveUpdatedAt: number; // objective 最后更新时间
-	lastBlockerReason: string | null; // 上次 report_blocked 的原因，resume 时注入
-	budgetWarning70Sent: boolean; // 70% 预算预警已发送（token 或时间任一达 70%）
-	budgetWarning90Sent: boolean; // 90% 预算预警已发送
-	lastTurnTokensUsed: number; // 上一 turn 结束时的 tokensUsed，用于去抖检测
-	currentTurnIndex: number;                    // turn_end 粒度计数器
-	completedAtTurnIndex?: number;               // 进入终态时的 currentTurnIndex
-}
-
-// ── 默认值 ────────────────────────────────────────────
-
-export const DEFAULT_BUDGET: BudgetConfig = {
-	maxStallTurns: 5,
-	maxTurns: 50,
-};
-
-export function createInitialState(objective: string, budget: Partial<BudgetConfig> = {}): GoalRuntimeState {
-	return {
-		goalId: crypto.randomUUID(),
-		objective,
-		status: "active",
-		tasks: [],
-		turnCount: 0,
-		stallCount: 0,
-		tokensUsed: 0,
-		timeStartedAt: Date.now(),
-		timeUsedSeconds: 0,
-		budget: { ...DEFAULT_BUDGET, ...budget },
-		lastProgressTurn: 0,
-		budgetLimitSteeringSent: false,
-		objectiveUpdatedAt: Date.now(),
-		lastBlockerReason: null,
-		budgetWarning70Sent: false,
-		budgetWarning90Sent: false,
-		lastTurnTokensUsed: 0,
-		currentTurnIndex: 0,
-		completedAtTurnIndex: undefined,
-	};
-}
-
-// ── 状态转换 ──────────────────────────────────────────
-
-/**
- * 安全的状态转换。终态不可被覆盖。
- */
-export function transitionStatus(current: GoalStatus, next: GoalStatus): GoalStatus {
-	if (TERMINAL_STATUSES.has(current)) return current;
-	return next;
-}
-
-export function isTerminalStatus(status: GoalStatus): boolean {
-	return TERMINAL_STATUSES.has(status);
-}
-
-export function isActiveStatus(status: GoalStatus): boolean {
-	return status === "active";
-}
-
-// ── 序列化（直接用相同类型，避免维护两个相同接口）──────
-
-export function serializeState(state: GoalRuntimeState): GoalRuntimeState {
-	return {
-		...state,
-		tasks: state.tasks.map((t) => ({
-			...t,
-			subtasks: t.subtasks?.map((s) => ({ ...s })),
-		})),
-		budget: { ...state.budget },
-	};
-}
-
-/**
- * 反序列化，补全缺失字段的默认值（向后兼容旧格式数据）
- */
-export function deserializeState(data: Record<string, unknown>): GoalRuntimeState {
-	return {
-		goalId: (data.goalId as string) ?? "",
-		objective: (data.objective as string) ?? "",
-		status: (data.status as GoalStatus) ?? "active",
-		tasks: ((data.tasks as Record<string, unknown>[]) ?? []).map((t: Record<string, unknown>) => {
-		if (!("status" in t)) {
-			throw new Error("Legacy goal-state format detected, session reset required");
-		}
-		const rawSubtasks = (t.subtasks ?? t.subTodos) as Record<string, unknown>[] | undefined;
-		const subtasks = Array.isArray(rawSubtasks)
-			? rawSubtasks
-					.filter((s) => typeof s.id === "number" && typeof s.text === "string" && typeof s.status === "string")
-					.map((s) => ({
-						id: s.id as number,
-						text: s.text as string,
-						status: s.status as SubtaskStatus,
-						lastUpdatedTurn: (s.lastUpdatedTurn as number) ?? 0,
-					}))
-			: undefined;
-		return { ...t, subtasks, lastUpdatedTurn: (t.lastUpdatedTurn as number) ?? 0 } as unknown as GoalTask;
-	}),
-		turnCount: (data.turnCount as number) ?? 0,
-		stallCount: (data.stallCount as number) ?? 0,
-		tokensUsed: (data.tokensUsed as number) ?? 0,
-		timeStartedAt: (data.timeStartedAt as number) ?? Date.now(),
-		timeUsedSeconds: (data.timeUsedSeconds as number) ?? 0,
-		budget: { ...DEFAULT_BUDGET, ...((data.budget as Partial<BudgetConfig>) ?? {}) },
-		lastProgressTurn: (data.lastProgressTurn as number) ?? 0,
-		budgetLimitSteeringSent: (data.budgetLimitSteeringSent as boolean) ?? false,
-		objectiveUpdatedAt: (data.objectiveUpdatedAt as number) ?? Date.now(),
-		lastBlockerReason: (data.lastBlockerReason as string | null) ?? null,
-		budgetWarning70Sent: (data.budgetWarning70Sent as boolean) ?? false,
-		budgetWarning90Sent: (data.budgetWarning90Sent as boolean) ?? false,
-		lastTurnTokensUsed: (data.lastTurnTokensUsed as number) ?? 0,
-		currentTurnIndex: (data.currentTurnIndex as number) ?? 0,
-		completedAtTurnIndex: data.completedAtTurnIndex as number | undefined,
-	};
-}
-
-// ── 进度计算 ──────────────────────────────────────────
-
-export function getCompletedCount(tasks: GoalTask[]): number {
-	return tasks.filter((t) => t.status === "completed").length;
-}
-
-export function getIncompleteTasks(tasks: GoalTask[]): GoalTask[] {
-	return tasks.filter((t) => !isTerminalTaskStatus(t.status));
-}
-
-export function getElapsedTimeSeconds(state: GoalRuntimeState): number {
-	if (isTerminalStatus(state.status) || state.status === "paused") return state.timeUsedSeconds;
-	return state.timeUsedSeconds + (Date.now() - state.timeStartedAt) / MS_PER_SECOND;
-}
-
-// getTokenUsagePercent 和 getTimeUsagePercent 已移至 budget.ts
-// 保留 re-export 以便渐进迁移
-export { getTimeUsagePercent,getTokenUsagePercent } from "./budget.js";

package/src/templates.ts

@@ -1,232 +0,0 @@
-/**
- * Steering prompt 模板
- *
- * 参考 Codex /goal 的三套模板：
- * 1. continuation.md — 每个 continuation turn 开始时注入
- * 2. budget_limit.md — 首次达到 token budget 时注入
- * 3. objective_updated.md — 外部修改了 goal objective 时注入
- *
- * 所有模板中的 objective 文本都经过 XML 转义，防止 prompt 注入。
- */
-
-import { PERCENT_FACTOR, SECONDS_PER_MINUTE, TASK_STALL_TURN_THRESHOLD } from "./constants";
-import type { GoalRuntimeState, GoalTask } from "./state";
-import { getCompletedCount, getElapsedTimeSeconds,getIncompleteTasks } from "./state";
-
-// ── XML 转义（防止 objective 中的 XML 标签破坏 prompt 结构）──
-
-function escapeXmlText(input: string): string {
-	return input
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;");
-}
-
-// ── Continuation Prompt ───────────────────────────────
-// 精简版，对标 Codex ~500 chars。详细信息在 before_agent_start 注入。
-
-export function continuationPrompt(state: GoalRuntimeState): string {
-	const objective = escapeXmlText(state.objective);
-	const incomplete = getIncompleteTasks(state.tasks);
-	const completedCount = getCompletedCount(state.tasks);
-	const total = state.tasks.length;
-
-	// Budget info (single line, Codex style)
-	const budgetLine = formatBudgetLine(state);
-	const stallLine = state.stallCount > 0 ? `\nStall: ${state.stallCount}/${state.budget.maxStallTurns} turns stalled` : "";
-
-	// Task summary (only IDs, not full descriptions — descriptions in before_agent_start)
-	const taskLine = total > 0
-		? `Tasks: ${completedCount}/${total}${incomplete.length > 0 ? ` (remaining: ${incomplete.map(t => `#${t.id}`).join(",")})` : " ✓"}`
-		: "Tasks: Not created. Call create_tasks immediately.";
-
-	return (
-		`<goal_context>\n` +
-		`[GOAL] Turn ${state.currentTurnIndex}/${state.budget.maxTurns}${budgetLine}${stallLine}\n` +
-		`<objective>${objective}</objective>\n` +
-		`${taskLine}\n` +
-		`Rules: create_tasks→update_tasks(evidence)→complete_goal(evidence). blocked→report_blocked(reason). subtask: add_subtasks/update_subtasks (replaces todo tool).\n` +
-		`Audit: Verify each requirement has authoritative evidence. Do not mark completed due to budget exhaustion, do not mark blocked due to difficulty.\n` +
-		`</goal_context>`
-	);
-}
-
-// ── Budget Limit Prompt ───────────────────────────────
-
-export function budgetLimitPrompt(state: GoalRuntimeState, limitType: "token" | "time"): string {
-	const objective = escapeXmlText(state.objective);
-	const completedCount = getCompletedCount(state.tasks);
-	const total = state.tasks.length;
-	const elapsed = getElapsedTimeSeconds(state);
-
-	const incomplete = getIncompleteTasks(state.tasks);
-	const incompleteSummary =
-		incomplete.length > 0
-			? `Incomplete: ${incomplete.map((t) => `#${t.id}`).join(", ")}`
-			: "All tasks completed.";
-
-	return (
-		`<goal_context>\n` +
-		`[GOAL — ${limitType === "token" ? "TOKEN budget" : "time budget"} almost exhausted]\n\n` +
-		`<objective>\n${objective}\n</objective>\n\n` +
-		`Current progress: ${completedCount}/${total} tasks completed\n` +
-		`${incompleteSummary}\n` +
-		(limitType === "token"
-			? `Tokens used: ${state.tokensUsed} / ${state.budget.tokenBudget ?? "unknown"}\n`
-			: `Time elapsed: ${Math.floor(elapsed / SECONDS_PER_MINUTE)}m${Math.floor(elapsed % SECONDS_PER_MINUTE)}s / ${state.budget.timeBudgetMinutes ?? "unknown"} min\n`) +
-		`\nYou must wrap up immediately:\n` +
-		`1. Use goal_manager's list_tasks to check remaining tasks\n` +
-		`2. Only mark tasks you have genuinely completed with evidence\n` +
-		`3. If the objective is met, call goal_manager's complete_goal\n` +
-		`4. Summarize current progress and remaining work\n` +
-		`Do not start new tasks. Do not mark completed due to budget exhaustion.\n` +
-		`</goal_context>`
-	);
-}
-
-// ── Objective Updated Prompt ──────────────────────────
-
-export function objectiveUpdatedPrompt(state: GoalRuntimeState, oldObjective: string): string {
-	const newObjective = escapeXmlText(state.objective);
-	const escapedOld = escapeXmlText(oldObjective);
-
-	return (
-		`<goal_context>\n` +
-		`[GOAL — Objective updated]\n\n` +
-		`Previous objective: ${escapedOld}\n` +
-		`<untrusted_objective>\n${newObjective}\n</untrusted_objective>\n\n` +
-		`This new objective supersedes all prior objective context. You must:\n` +
-		`1. Immediately stop working toward the old objective\n` +
-		`2. Re-evaluate the task list — call goal_manager's create_tasks to re-decompose if needed\n` +
-		`3. Only continue old work if it also serves the new objective\n` +
-		`4. Proceed with the new objective\n` +
-		`</goal_context>`
-	);
-}
-
-// ── Context Injection Prompt (before_agent_start) ─────
-
-export function contextInjectionPrompt(state: GoalRuntimeState): string {
-	const objective = escapeXmlText(state.objective);
-	const completedCount = getCompletedCount(state.tasks);
-	const total = state.tasks.length;
-	const budgetInfo = formatBudgetInfo(state);
-
-	return (
-		`<goal_context>\n` +
-		`[GOAL mode activated]\n\n` +
-		`<objective>\n${objective}\n</objective>\n` +
-		`Status: ${state.status}\n` +
-		`Turn: ${state.currentTurnIndex}/${state.budget.maxTurns}${budgetInfo}\n` +
-		`Task progress: ${completedCount}/${total}\n\n` +
-		`Strict rules:\n` +
-		`1. First step: call goal_manager's create_tasks to decompose tasks (if not yet created)\n` +
-		`2. After completing a task, call update_tasks with status=completed and provide evidence\n` +
-		`3. Only call complete_goal with concrete evidence\n` +
-		`4. If blocked, call report_blocked\n` +
-		`5. In Goal mode, do not use the todo tool — use add_subtasks / update_subtasks for fine-grained tracking\n` +
-		`</goal_context>`
-	);
-}
-
-// ── Staleness Reminder Prompt ────────────────────────
-
-export function stalenessReminderPrompt(
-	state: GoalRuntimeState,
-	staleTasks: Array<{
-		task: GoalTask;
-		staleTurns: number;
-		staleSubtasks: Array<{ text: string; staleTurns: number }>;
-	}>,
-	allTerminal: boolean,
-): string {
-	const objective = escapeXmlText(state.objective);
-	const lines: string[] = [];
-
-	lines.push("<goal_context>");
-	lines.push("[GOAL reminder — tasks stalled]\n");
-
-	if (allTerminal) {
-		lines.push("All tasks completed but goal_manager is still open. Call complete_goal or cancel_goal.");
-	} else {
-		lines.push(`The following tasks have exceeded ${TASK_STALL_TURN_THRESHOLD} turns without update:\n`);
-		for (const item of staleTasks) {
-			lines.push(`  #${item.task.id}: ${item.task.description} (${item.staleTurns} turns idle)`);
-			for (const s of item.staleSubtasks) {
-				lines.push(`    - ${s.text} (${s.staleTurns} turns)`);
-			}
-		}
-		lines.push("\nCheck these tasks — call update_tasks to report progress or cancel tasks that are no longer needed.");
-	}
-
-	lines.push(`\nObjective: ${objective}`);
-	lines.push(`Turn: ${state.currentTurnIndex}/${state.budget.maxTurns}`);
-	lines.push("</goal_context>");
-
-	return lines.join("\n");
-}
-
-// ── Helpers ───────────────────────────────────────────
-
-function formatBudgetInfo(state: GoalRuntimeState): string {
-	const parts: string[] = [];
-	if (state.budget.tokenBudget) {
-		const pct = Math.round((state.tokensUsed / state.budget.tokenBudget) * PERCENT_FACTOR);
-		parts.push(`Token: ${pct}%`);
-	}
-	if (state.budget.timeBudgetMinutes) {
-		const elapsed = getElapsedTimeSeconds(state);
-		const pct = Math.round((elapsed / (state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE)) * PERCENT_FACTOR);
-		parts.push(`Time: ${pct}%`);
-	}
-	return parts.length > 0 ? ` (${parts.join(", ")})` : "";
-}
-
-function formatBudgetLine(state: GoalRuntimeState): string {
-	const parts: string[] = [];
-	if (state.budget.tokenBudget) {
-		const remaining = Math.max(state.budget.tokenBudget - state.tokensUsed, 0);
-		parts.push(`Tokens: ${remaining}/${state.budget.tokenBudget}`);
-	}
-	if (state.budget.timeBudgetMinutes) {
-		const elapsed = getElapsedTimeSeconds(state);
-		const remaining = Math.max(state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE - elapsed, 0);
-		parts.push(`Time: ${Math.floor(remaining / SECONDS_PER_MINUTE)}m/${state.budget.timeBudgetMinutes}m`);
-	}
-	return parts.length > 0 ? ` | ${parts.join(" ")}` : "";
-}
-
-export function formatTaskList(tasks: GoalTask[]): string {
-	if (tasks.length === 0) return "No tasks yet.";
-	const completed = tasks.filter(t => t.status === "completed");
-	const active = tasks.filter(t => t.status === "in_progress" || t.status === "pending");
-	const cancelled = tasks.filter(t => t.status === "cancelled");
-	const lines: string[] = [];
-	if (active.length > 0) {
-		lines.push(`In progress / Pending (${active.length}):`);
-		for (const t of active) {
-			const icon = t.status === "in_progress" ? "●" : "☐";
-			lines.push(`  ${icon} #${t.id}: ${t.description}`);
-			if (t.subtasks && t.subtasks.length > 0) {
-				for (const s of t.subtasks) {
-					const sIcon = s.status === "completed" ? "✓" : s.status === "in_progress" ? "●" : "○";
-					lines.push(`    ${sIcon} #${t.id}.${s.id}: ${s.text}`);
-				}
-			}
-		}
-	}
-	if (completed.length > 0) {
-		lines.push(`Completed (${completed.length}):`);
-		for (const t of completed) {
-			const evidence = t.evidence ? ` — ${t.evidence}` : "";
-			lines.push(`  ✓ #${t.id}: ${t.description}${evidence}`);
-		}
-	}
-	if (cancelled.length > 0) {
-		lines.push(`Cancelled (${cancelled.length}):`);
-		for (const t of cancelled) lines.push(`  ✗ #${t.id}: ${t.description}`);
-	}
-	const summary = `${completed.length}/${tasks.length} completed` + (cancelled.length > 0 ? `, ${cancelled.length} cancelled` : "");
-	lines.push(summary);
-	return lines.join("\n");
-}