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

package/extensions/goal-runtime.ts

@@ -0,0 +1,277 @@
+/**
+ * GoalRuntime — continuation scheduling, stale-checkpoint state, the turn-stop
+ * guard, and one-time steering reminders (post-compaction, budget reached).
+ *
+ * The extension (`extensions/goal.ts`) instantiates one GoalRuntime with hooks
+ * bound to its closure state and the pi API; every runtime decision is
+ * encapsulated here so the scheduling/guarding behavior is independently
+ * testable with a mock context.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GoalCheckpointDetailsV3, GoalRecord } from "./goal-record.ts";
+import { checkpointTriggerPrompt } from "./prompts/goal-prompts.ts";
+import { POST_STOP_ALLOWED_TOOLS } from "./goal-tool-names.ts";
+import { networkErrorBackoffPlan, type NetworkErrorBackoffPlan, type NetworkErrorRecoveryPolicy } from "./network-error-backoff.ts";
+
+export const CONTINUATION_IDLE_RETRY_MS = 50;
+
+const POST_STOP_ALLOWED = new Set<string>(POST_STOP_ALLOWED_TOOLS);
+
+export interface GoalRuntimeHooks {
+	authorize?(ctx: ExtensionContext, goal: GoalRecord): Record<string, unknown> | null;
+	recover?(ctx: ExtensionContext): void;
+	dispatchFailed?(ctx: ExtensionContext): void;
+	/** Dispatch a hidden follow-up checkpoint message (pi.sendMessage + triggerTurn). */
+	sendFollowUp(content: string, details: Record<string, unknown>): void;
+	/** Current focused goal (state.goal). */
+	getGoal(): GoalRecord | null;
+	/** Whether a checkpointed goal id is still actionable (active + autoContinue). */
+	isActionable(goalId: string | null | undefined): boolean;
+}
+
+export class GoalRuntime {
+	// ── continuation scheduling ──────────────────────────────────────────
+	private continuationQueuedFor: string | null = null;
+	private continuationScheduledFor: string | null = null;
+	private continuationTimer: ReturnType<typeof setTimeout> | null = null;
+	private networkErrorRetryGoalId: string | null = null;
+	private networkErrorRetryAttempt = 0;
+	private networkErrorRetryTimer: ReturnType<typeof setTimeout> | null = null;
+
+	// ── turn-stop guard ──────────────────────────────────────────────────
+	private turnSeq = 0;
+	private turnStoppedFor: { goalId: string; turnSeq: number } | null = null;
+	private draftResolvedTurnSeq: number | null = null;
+
+	// ── stale checkpoint state ───────────────────────────────────────────
+	private checkpointGoalId: string | null = null;
+
+	/** Monotonic per-session counter persisted on v2 checkpoint details (issue #30). */
+	private checkpointSeq = 0;
+
+	// ── one-time steering reminders ──────────────────────────────────────
+	private postCompactReminderPending = false;
+	private postBudgetReminderPending = false;
+
+	private readonly hooks: GoalRuntimeHooks;
+
+	constructor(hooks: GoalRuntimeHooks) {
+		this.hooks = hooks;
+	}
+
+	// ── continuation scheduling ──────────────────────────────────────────
+
+	clearContinuationState(resetNetworkErrorBackoff = true): void {
+		this.clearContinuationTimer();
+		this.continuationQueuedFor = null;
+		if (resetNetworkErrorBackoff) this.clearNetworkErrorBackoff();
+	}
+
+	/** Clear the pending timer but keep the queued marker (used at session shutdown). */
+	clearContinuationTimer(): void {
+		if (this.continuationTimer) {
+			clearTimeout(this.continuationTimer);
+			this.continuationTimer = null;
+		}
+		this.continuationScheduledFor = null;
+	}
+
+	/** Whether a continuation is queued or scheduled for this goal id. */
+	continuationPendingFor(goalId: string): boolean {
+		return this.continuationQueuedFor === goalId || this.continuationScheduledFor === goalId;
+	}
+
+	/**
+	 * Schedule the next auto-continuation for the focused active goal.
+	 * Only `active` + autoContinue goals can queue. `force` bypasses the
+	 * already-queued/scheduled dedup (used right after creation/resume).
+	 */
+	queueContinuation(ctx: ExtensionContext, goal: GoalRecord, force = false): void {
+		if (goal.status !== "active" || !goal.autoContinue) return;
+		const goalId = goal.id;
+		if (!force && this.continuationPendingFor(goalId)) return;
+		this.clearContinuationTimer();
+		let delay = CONTINUATION_IDLE_RETRY_MS;
+		try {
+			delay = ctx.isIdle() && !ctx.hasPendingMessages() ? 0 : CONTINUATION_IDLE_RETRY_MS;
+		} catch {
+			return;
+		}
+		this.continuationScheduledFor = goalId;
+		this.continuationTimer = setTimeout(() => this.sendQueuedContinuation(ctx, goalId), delay);
+		this.continuationTimer.unref?.();
+	}
+
+	/** Cancel a pending continuation for a goal id (e.g. after update/clear/focus change). */
+	cancelContinuationFor(goalId: string): void {
+		if (this.continuationQueuedFor === goalId) this.continuationQueuedFor = null;
+		if (this.continuationScheduledFor === goalId) this.clearContinuationState();
+		if (this.networkErrorRetryGoalId === goalId) this.clearNetworkErrorBackoff();
+	}
+
+	/**
+	 * Schedule the next bounded recovery after Pi's built-in provider retries
+	 * have failed. The counter stays in memory and is cleared on a successful
+	 * turn or any user-owned cancellation path.
+	 */
+	scheduleNetworkErrorRetry(ctx: ExtensionContext, goal: GoalRecord, policy?: NetworkErrorRecoveryPolicy): NetworkErrorBackoffPlan | null {
+		if (goal.status !== "active" || !goal.autoContinue || this.networkErrorRetryTimer) return null;
+		if (this.networkErrorRetryGoalId !== goal.id) {
+			this.networkErrorRetryGoalId = goal.id;
+			this.networkErrorRetryAttempt = 0;
+		}
+		const plan = networkErrorBackoffPlan(this.networkErrorRetryAttempt + 1, policy);
+		if (!plan) return null;
+		this.networkErrorRetryAttempt = plan.attempt;
+		this.networkErrorRetryTimer = setTimeout(() => {
+			this.networkErrorRetryTimer = null;
+			if (!this.hooks.isActionable(goal.id)) return;
+			const currentGoal = this.hooks.getGoal();
+			if (!currentGoal || currentGoal.id !== goal.id) return;
+			this.hooks.recover?.(ctx);
+		}, plan.delayMs);
+		this.networkErrorRetryTimer.unref?.();
+		return plan;
+	}
+
+	/** Cancel and forget all goal-level network-error recovery state. */
+	clearNetworkErrorBackoff(): void {
+		if (this.networkErrorRetryTimer) clearTimeout(this.networkErrorRetryTimer);
+		this.networkErrorRetryTimer = null;
+		this.networkErrorRetryGoalId = null;
+		this.networkErrorRetryAttempt = 0;
+	}
+
+	/**
+	 * Issue #30: the delivered follow-up must trigger the turn, but it no longer
+	 * carries goal state. The persisted content is a tiny v2 marker and the
+	 * details are a bounded structured record; before_agent_start injects the
+	 * authoritative full prompt once per turn.
+	 */
+	private sendQueuedContinuation(ctx: ExtensionContext, scheduledGoalId: string): void {
+		this.continuationTimer = null;
+		this.continuationScheduledFor = null;
+		if (!this.hooks.isActionable(scheduledGoalId)) {
+			if (this.continuationQueuedFor === scheduledGoalId) this.continuationQueuedFor = null;
+			return;
+		}
+
+		let ready: boolean;
+		try {
+			ready = !ctx.hasPendingMessages() && ctx.isIdle();
+		} catch {
+			if (this.continuationQueuedFor === scheduledGoalId) this.continuationQueuedFor = null;
+			return;
+		}
+
+		if (!ready) {
+			this.continuationScheduledFor = scheduledGoalId;
+			this.continuationTimer = setTimeout(() => this.sendQueuedContinuation(ctx, scheduledGoalId), CONTINUATION_IDLE_RETRY_MS);
+			this.continuationTimer.unref?.();
+			return;
+		}
+		const goal = this.hooks.getGoal();
+		if (!goal || goal.id !== scheduledGoalId) {
+			if (this.continuationQueuedFor === scheduledGoalId) this.continuationQueuedFor = null;
+			return;
+		}
+		const authorization = this.hooks.authorize?.(ctx, goal);
+		if (!authorization) return;
+		this.checkpointSeq += 1;
+		this.continuationQueuedFor = goal.id;
+		const details: GoalCheckpointDetailsV3 = {
+			version: 3,
+			generation: String(authorization.generation),
+			dispatchId: String(authorization.dispatchId),
+			kind: "checkpoint",
+			goalId: goal.id,
+			status: "active",
+			revision: goal.revision ?? 0,
+			checkpointSeq: this.checkpointSeq,
+			timestamp: Date.now(),
+		};
+		try { this.hooks.sendFollowUp(checkpointTriggerPrompt(goal.id), details as unknown as Record<string, unknown>); }
+		catch { this.hooks.dispatchFailed?.(ctx); }
+	}
+
+	// ── turn-stop guard ──────────────────────────────────────────────────
+
+	advanceTurn(): void {
+		this.turnSeq += 1;
+		if (this.turnStoppedFor?.turnSeq !== this.turnSeq) this.turnStoppedFor = null;
+	}
+
+	/** Mark the current turn stopped after a terminal/mutating goal tool. */
+	markTurnStopped(goalId: string): void {
+		this.turnStoppedFor = { goalId, turnSeq: this.turnSeq };
+	}
+
+	/** Goal id that stopped the current turn, or null. Stale markers are dropped. */
+	currentTurnStoppedGoalId(): string | null {
+		if (!this.turnStoppedFor) return null;
+		if (this.turnStoppedFor.turnSeq !== this.turnSeq) {
+			this.turnStoppedFor = null;
+			return null;
+		}
+		return this.turnStoppedFor.goalId;
+	}
+
+	/** Mark that a guided draft was confirmed or cancelled in the current turn. */
+	markDraftResolved(): void {
+		this.draftResolvedTurnSeq = this.turnSeq;
+	}
+
+	/** Whether a guided draft was confirmed or cancelled earlier in the current turn. */
+	isDraftResolvedThisTurn(): boolean {
+		return this.draftResolvedTurnSeq === this.turnSeq;
+	}
+
+	// ── stale checkpoint state ───────────────────────────────────────────
+
+	setCheckpoint(goalId: string | null): void {
+		this.checkpointGoalId = goalId;
+	}
+
+	getCheckpointGoalId(): string | null {
+		return this.checkpointGoalId;
+	}
+
+	/** Tools blocked when a stale checkpoint triggered the current turn. */
+	isStaleCheckpointBlocked(toolName: string): boolean {
+		return !POST_STOP_ALLOWED.has(toolName);
+	}
+
+	// ── one-time steering reminders ──────────────────────────────────────
+
+	armPostCompactReminder(): void {
+		this.postCompactReminderPending = true;
+	}
+
+	/** Whether a post-compaction reminder is pending (read-only). */
+	isPostCompactReminderPending(): boolean {
+		return this.postCompactReminderPending;
+	}
+
+	clearPostCompactReminder(): void {
+		this.postCompactReminderPending = false;
+	}
+
+	/** True once if a post-compaction reminder is pending; clears it. */
+	consumePostCompactReminder(): boolean {
+		if (!this.postCompactReminderPending) return false;
+		this.postCompactReminderPending = false;
+		return true;
+	}
+
+	armPostBudgetReminder(): void {
+		this.postBudgetReminderPending = true;
+	}
+
+	/** True once if a post-budget-limit reminder is pending; clears it. */
+	consumePostBudgetReminder(): boolean {
+		if (!this.postBudgetReminderPending) return false;
+		this.postBudgetReminderPending = false;
+		return true;
+	}
+}

package/extensions/goal-scheduler-state.ts

@@ -0,0 +1,100 @@
+import { commandHint, commandInstructions, type GoalCommands } from "./goal-controls.ts";
+import { randomUUID } from "node:crypto";
+
+export type GoalDispatchKind = "ready" | "check" | "wake" | "repair" | "kickoff" | "recovery";
+export interface GoalWait {
+	id: string;
+	token: string;
+	reason: string;
+	deadline: number;
+	intervalMs?: number;
+	remainingChecks?: number;
+	nextCheckAt?: number;
+	signalled?: boolean;
+}
+export interface GoalSchedulerState {
+	version: 1;
+	owner: string;
+	generation: string;
+	used: number;
+	phase: "idle" | "ready" | "waiting" | "claimed" | "running" | "interrupted";
+	decision?: { kind: "ready"; purpose: GoalDispatchKind } | { kind: "wait" };
+	wait?: GoalWait;
+	dispatch?: { id: string; kind: GoalDispatchKind; claimedAt: number };
+	repairUsed: boolean;
+	/** Optional idle pacing, effective only with idleContinuationBackoff=true. */
+	idle?: { runs: number; nextAt: number };
+}
+export type GoalContinuation =
+	| { kind: "ready" }
+	| { kind: "wait"; reason: string; deadline: string; wait_id?: string; polling?: { interval_seconds: number; max_checks: number } };
+
+export function newGoalScheduler(owner: string): GoalSchedulerState {
+	return { version: 1, owner, generation: randomUUID(), used: 0, phase: "idle", repairUsed: false };
+}
+
+/** Corrupt scheduling data must not silently reset spent allowance. */
+export function normalizeGoalScheduler(raw: unknown): GoalSchedulerState | undefined {
+	if (raw === undefined) return undefined;
+	const invalid = (): GoalSchedulerState => ({ ...newGoalScheduler("invalid"), phase: "interrupted", used: Number.MAX_SAFE_INTEGER });
+	if (!raw || typeof raw !== "object") return invalid();
+	const s = raw as GoalSchedulerState;
+	const integer = (n: unknown) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+	const text = (v: unknown) => typeof v === "string" && v.length > 0 && v.length <= 2000;
+	if (s.version !== 1 || !text(s.owner) || !text(s.generation) || !integer(s.used) || typeof s.repairUsed !== "boolean" || !["idle", "ready", "waiting", "claimed", "running", "interrupted"].includes(s.phase)) return invalid();
+	if (s.idle !== undefined && (!s.idle || typeof s.idle !== "object" || !integer(s.idle.runs) || s.idle.runs < 1 || s.idle.runs > 6 || !integer(s.idle.nextAt) || s.idle.nextAt > 8_640_000_000_000_000)) return invalid();
+	// Goals saved before next actions were removed still carry decision.nextAction.
+	// The field is stripped after validation and never makes a goal invalid:
+	// rejecting one would strand it as interrupted with spent allowance.
+	if (s.decision && (s.decision.kind !== "wait" && (s.decision.kind !== "ready" || !["ready", "repair", "kickoff", "recovery"].includes(s.decision.purpose)))) return invalid();
+	if (s.wait) {
+		const w = s.wait;
+		if (!text(w.id) || !text(w.token) || !text(w.reason) || (!integer(w.deadline) || w.deadline > 8_640_000_000_000_000)) return invalid();
+		if (w.intervalMs !== undefined && (!integer(w.intervalMs) || w.intervalMs < 1000 || !integer(w.remainingChecks) || !integer(w.nextCheckAt))) return invalid();
+		if (w.intervalMs === undefined && (w.remainingChecks !== undefined || w.nextCheckAt !== undefined)) return invalid();
+		if (w.signalled !== undefined && typeof w.signalled !== "boolean") return invalid();
+	}
+	if (s.dispatch && (!text(s.dispatch.id) || !integer(s.dispatch.claimedAt) || !["ready", "check", "wake", "repair", "kickoff", "recovery"].includes(s.dispatch.kind))) return invalid();
+	if ((s.phase === "claimed" || s.phase === "running") && !s.dispatch) return invalid();
+	if (s.phase === "ready" && s.decision?.kind !== "ready") return invalid();
+	if (s.phase === "waiting" && (!s.wait || s.decision?.kind !== "wait")) return invalid();
+	const normalized = structuredClone(s) as GoalSchedulerState;
+	if (normalized.decision && "nextAction" in normalized.decision) delete (normalized.decision as Record<string, unknown>).nextAction;
+	return normalized;
+}
+
+/**
+ * Split scheduling text into an append-safe counter line and the standing
+ * instructions. Instructions (next action, wait, admission) are cleared by
+ * omission, so a retained stale copy would keep issuing a cancelled order:
+ * they belong with the reset-on-change state, never with retained counters.
+ */
+export function schedulerSummaryParts(s: GoalSchedulerState | undefined, limit?: number, showRuns = true, idleBackoff = false, commands?: GoalCommands): { runs: string; instructions: string; idlePacing?: string } {
+	// An unlimited allowance has no limit to report, so the runs line is left
+	// empty rather than rendered as "used/unlimited". A finite allowance is
+	// reported unless showAutonomousRuns is off. Enforcement reads the limit
+	// elsewhere; this is display only.
+	const runs = limit !== undefined && showRuns ? `Autonomous runs: ${s?.used ?? 0}/${limit}${limit === 0 ? " (automatic continuation disabled)" : ""}.` : "";
+	const lines: string[] = [];
+	let idlePacing: string | undefined;
+	if (s) {
+		if (idleBackoff && s.phase === "ready" && s.decision?.kind === "ready" && s.decision.purpose === "ready" && s.idle && s.idle.nextAt > Date.now()) {
+			const seconds = Math.ceil((s.idle.nextAt - Date.now()) / 1000);
+			const time = new Date(s.idle.nextAt).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit", hour12: false });
+			idlePacing = `Next automatic attempt in ${seconds}s (${time} local). ${commandHint("goal-resume", commands)} now.`;
+			lines.push(idlePacing);
+		}
+		if (s.wait) {
+			lines.push(`Waiting: ${s.wait.reason}; wait_id=${s.wait.id}; deadline=${new Date(s.wait.deadline).toISOString()}.`);
+			if (s.wait.nextCheckAt !== undefined) lines.push(`Next check: ${new Date(s.wait.nextCheckAt).toISOString()}; ${s.wait.remainingChecks} checks remaining.`);
+		}
+		if (s.phase === "interrupted") lines.push("Turn stopped. Resume or send a message to continue.");
+		if (s.phase === "claimed") lines.push(commandInstructions("Execution requires dispatch admission or explicit /goal-resume after interruption.", commands));
+	}
+	return { runs, instructions: lines.join("\n"), idlePacing };
+}
+
+export function schedulerSummary(s: GoalSchedulerState | undefined, limit?: number, showRuns = true, idleBackoff = false, commands?: GoalCommands): string {
+	const { runs, instructions } = schedulerSummaryParts(s, limit, showRuns, idleBackoff, commands);
+	return [runs, instructions].filter(Boolean).join("\n");
+}