@quantmind-br/pi-goal-x 0.35.0 → 0.35.1

package/docs/prompt-caching.md

@@ -6,7 +6,7 @@ The request layout is:
 
 1. Host system prompt and tool schemas.
 2. Conversation history, with each goal checkpoint normalized to a tiny, stable trigger in its original position.
-3. Request-only goal policy plus compact counter/context snapshots, replayed at verified history anchors when safe. Current policy includes the objective, tasks, lifecycle rules, limits, scheduling state and applicable recovery/auditor reminders.
+3. Request-only goal policy, then a task snapshot, then compact counter/context snapshots, replayed at verified history anchors when safe. Current policy includes the objective, lifecycle rules, the task gate, limits, scheduling state and applicable recovery/auditor reminders. The task snapshot carries task progress: the `[TASK LIST]` header with completed/total counts, the current task with its contract, pending tasks, and the count of omitted pending tasks.
 
 Changing goal state never rewrites the system prompt or historical messages. The full goal-state message is not persisted into the session. Old checkpoints remain until Pi compacts history; retaining small markers avoids shifting the prefix on every continuation. Display-only auditor messages are consistently excluded, and tool calls stay adjacent to their results.
 
@@ -24,7 +24,7 @@ Validation includes consecutive request-prefix regressions; actual Anthropic, An
 
 Provider references: [Anthropic prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) describes exact-prefix matching and explicit breakpoints; [DeepSeek context caching](https://api-docs.deepseek.com/guides/kv_cache/) describes its automatic prefix cache and usage counters.
 
-Active requests split policy from compact counter/context snapshots. Already-sent tails are replayed at verified history anchors so implicit-cache requests extend their previous prefix. Policy changes (including budget/run-limit removal), rewritten history and unsafe tool-result boundaries reset retention. At most 32 tails and 4 KiB of counter text are retained per session, across at most 16 session/model identities; no full-state tails are persisted. Unchanged requests add no tail. Older snapshots are historical, and current policy takes precedence over cache reuse.
+Active requests split policy, task snapshots and compact counter/context snapshots into separate tails, always in that order. Already-sent tails are replayed at verified history anchors so implicit-cache requests extend their previous prefix. Each kind is appended only when it differs from its previous copy, so starting, completing or skipping a task, or changing the current task, appends one task snapshot instead of resetting retention (#108 measured four prefix breaks across one three-task run; now only the task setup that enables the completion gate resets). With `blockCompletion` enabled, the policy carries a fixed TASK GATE line that defers to the latest task snapshot, so the pending count never changes policy. Policy changes (including budget/run-limit removal and enabling or disabling the task gate), dropping the task list, rewritten history and unsafe tool-result boundaries reset retention. At most 32 tails, 16 KiB of task snapshots and 4 KiB of counter text are retained per session, across at most 16 session/model identities; exceeding a bound performs one full reset. No full-state tails are persisted. Unchanged requests add no tail. Older task and counter snapshots are historical: the latest snapshot supersedes earlier ones, and current policy takes precedence over cache reuse.
 
 Explicit-marker relocation skips all retained live text and tolerates Pi's trailing effort-only messages. Another extension's content-bearing suffix is left alone. Changing models/providers starts a separate retention identity. Unknown session identities do not retain history between requests.
 

package/extensions/goal-events.ts

@@ -108,8 +108,8 @@ export function registerGoalEvents(core: GoalCore): void {
 		if (parts) {
 			// Retain previously sent tails verbatim at their anchors so this
 			// request extends the previous one instead of displacing its tail.
-			// Only genuinely new state/counters content is appended.
-			const { messages: retained } = liveRetention.apply(sessionKey, base, { state: parts.state, counters: parts.counters });
+			// Only genuinely new state, task, or counter content is appended.
+			const { messages: retained } = liveRetention.apply(sessionKey, base, { state: parts.state, tasks: parts.tasks, counters: parts.counters });
 			return retained;
 		}
 		liveRetention.clear(sessionKey);
@@ -468,8 +468,8 @@ export function registerGoalEvents(core: GoalCore): void {
 	});
 
 	/** Request-only state: no live counters, focus, or reminders enter the system prefix. */
-	/** Request-only goal state split into a rarely-changing policy block and per-turn counters. Other branches are stable-only. */
-	function currentGoalContextParts(ctx: ExtensionContext): { state: string; counters?: string } | undefined {
+	/** Request-only goal state split into a rarely-changing policy block, a task snapshot, and per-turn counters. Other branches are stable-only. */
+	function currentGoalContextParts(ctx: ExtensionContext): { state: string; tasks?: string; counters?: string } | undefined {
 		const checkpoint = core.runtime.getCheckpointGoalId();
 		if (checkpoint !== null && (core.scheduler.isDenied() || !core.isActionableContinuationGoal(checkpoint))) {
 			return { state: staleContinuationPrompt(checkpoint, core.state.goal) };
@@ -536,7 +536,7 @@ export function registerGoalEvents(core: GoalCore): void {
   }
 		const activeGoal = core.state.goal;
 		const settings = loadGoalSettings(ctx.cwd);
-		const { state: policy, counters } = goalPromptParts(activeGoal, { ...settings, commands: core.loadedCommands }, ctx.getContextUsage?.());
+		const { state: policy, tasks, counters } = goalPromptParts(activeGoal, { ...settings, commands: core.loadedCommands }, ctx.getContextUsage?.());
 		// Rare transitional steering rides in the stable block; per-turn usage and
 		// scheduling counters stay in the volatile block so retention grows slowly.
 		let state = policy;
@@ -568,7 +568,7 @@ export function registerGoalEvents(core: GoalCore): void {
 				state = `${state}\n\n[POST-COMPACTION RESYNC goalId=${core.state.goal.id}]\nThe conversation was just compacted. Re-read the objective and continue from the actual artifacts/state; do not rely on memory of the prior chat.`;
 			}
 		}
-		return { state, counters };
+		return { state, tasks, counters };
 	}
 
 	pi.on("agent_end", async (event, ctx) => {

package/extensions/goal-live-retention.ts

@@ -21,11 +21,15 @@ import { asRecord } from "./goal-record.ts";
  * edits), an unsafe insertion point, or overflow all perform one documented
  * full reset instead of silently shifting the prefix or corrupting message
  * structure.
+ *
+ * Task snapshots and usage counters are separate tail kinds. Each is appended
+ * only when it differs from its previous emission, so task progress extends
+ * the prefix instead of resetting it; only the policy block forces a reset.
  */
 
 export const LIVE_CONTEXT_TYPE = "pi-goal-live-context";
 
-export type LiveTailKind = "goal-state" | "goal-counters";
+export type LiveTailKind = "goal-state" | "goal-tasks" | "goal-counters";
 
 /** A request-only tail message. Never persisted; the hook replays it per request. */
 export interface LiveMessage {
@@ -48,19 +52,28 @@ export const MAX_RETAINED_LIVE_TAILS = 32;
 export const MAX_TRACKED_SESSIONS = 16;
 /** Extra historical observations, excluding the single current policy block. */
 export const MAX_RETAINED_COUNTER_BYTES = 4096;
+/**
+ * Retained task snapshots. Each task transition appends one snapshot, so a
+ * long task run stays prefix-stable until this bound forces a single reset.
+ */
+export const MAX_RETAINED_TASK_BYTES = 16_384;
 
 export interface FreshLiveTails {
 	state: string;
+	tasks?: string | undefined;
 	counters?: string | undefined;
 }
 
-interface RetainedTail {
-	anchorIndex: number;
-	anchorFingerprint: string | null;
+interface LiveBlock {
 	content: string;
 	kind: LiveTailKind;
 }
 
+interface RetainedTail extends LiveBlock {
+	anchorIndex: number;
+	anchorFingerprint: string | null;
+}
+
 interface SessionRetention {
 	tails: RetainedTail[];
 	lastFresh: FreshLiveTails | undefined;
@@ -68,8 +81,15 @@ interface SessionRetention {
 	baseFingerprints: Array<string | null>;
 }
 
-function freshBlocks(fresh: FreshLiveTails): string[] {
-	return fresh.counters === undefined ? [fresh.state] : [fresh.state, fresh.counters];
+function freshBlocks(fresh: FreshLiveTails): LiveBlock[] {
+	const blocks: LiveBlock[] = [{ content: fresh.state, kind: "goal-state" }];
+	if (fresh.tasks) blocks.push({ content: fresh.tasks, kind: "goal-tasks" });
+	if (fresh.counters !== undefined) blocks.push({ content: fresh.counters, kind: "goal-counters" });
+	return blocks;
+}
+
+function kindBytes(blocks: readonly LiveBlock[], kind: LiveTailKind): number {
+	return blocks.reduce((n, block) => block.kind === kind ? n + Buffer.byteLength(block.content) : n, 0);
 }
 
 /** Full-message digest, or null (never a match) when serialization fails. */
@@ -144,8 +164,10 @@ export class LiveTailRetention {
 		};
 		// A changed state block supersedes every previously sent tail: start
 		// fresh rather than leave a stale objective or a cancelled scheduling
-		// instruction lingering mid-history.
+		// instruction lingering mid-history. A dropped task snapshot or counter
+		// block resets too, so its last copy never reads as the current one.
 		if (session.lastFresh !== undefined && (session.lastFresh.state !== fresh.state
+			|| (session.lastFresh.tasks !== undefined && !fresh.tasks)
 			|| (session.lastFresh.counters !== undefined && fresh.counters === undefined))) reset();
 		// Tails anchored while history was empty would linger at the head once
 		// real history arrives. Reset once so fresh tails anchor at the tail.
@@ -178,34 +200,32 @@ export class LiveTailRetention {
 		}
 		if (valid < session.tails.length) reset();
 		const blocks = freshBlocks(fresh);
-		// Append only the suffix that differs from the last emitted tails, so
-		// unchanged content across repeats, tool loops, and history advances
-		// adds zero blocks while keeping the prefix literal.
+		// Append only blocks that differ from the last emitted block of the same
+		// kind, so unchanged content across repeats, tool loops, and history
+		// advances adds zero blocks while keeping the prefix literal. The state
+		// block never differs here: a changed state already reset above.
 		const previous = session.lastFresh === undefined ? [] : freshBlocks(session.lastFresh);
-		let shared = 0;
-		while (shared < blocks.length && shared < previous.length && blocks[shared] === previous[shared]) shared++;
+		let appended = blocks.filter(block => !previous.some(prior => prior.kind === block.kind && prior.content === block.content));
 		// Overflow is measured against what this request actually appends: an
 		// unchanged request adds nothing and must never trigger a reset.
-		if (session.tails.length + (blocks.length - shared) > MAX_RETAINED_LIVE_TAILS
-			|| session.tails.filter(tail => tail.kind === "goal-counters").reduce((n, tail) => n + Buffer.byteLength(tail.content), 0)
-				+ (fresh.counters === undefined || shared === blocks.length ? 0 : Buffer.byteLength(fresh.counters)) > MAX_RETAINED_COUNTER_BYTES) {
+		if (session.tails.length + appended.length > MAX_RETAINED_LIVE_TAILS
+			|| kindBytes(session.tails, "goal-counters") + kindBytes(appended, "goal-counters") > MAX_RETAINED_COUNTER_BYTES
+			|| kindBytes(session.tails, "goal-tasks") + kindBytes(appended, "goal-tasks") > MAX_RETAINED_TASK_BYTES) {
 			reset();
-			shared = 0;
+			appended = blocks;
 		}
 		const messages: Array<T | LiveMessage> = [...base];
 		for (let i = session.tails.length - 1; i >= 0; i--) {
 			const tail = session.tails[i]!;
 			messages.splice(tail.anchorIndex, 0, makeLiveMessage(tail.content));
 		}
-		for (let i = shared; i < blocks.length; i++) {
-			const content = blocks[i]!;
-			const kind: LiveTailKind = i === 0 ? "goal-state" : "goal-counters";
-			messages.push(makeLiveMessage(content));
-			session.tails.push({ anchorIndex: base.length, anchorFingerprint: fingerprints.at(-1) ?? null, content, kind });
+		for (const block of appended) {
+			messages.push(makeLiveMessage(block.content));
+			session.tails.push({ anchorIndex: base.length, anchorFingerprint: fingerprints.at(-1) ?? null, content: block.content, kind: block.kind });
 		}
 		session.baseFingerprints = fingerprints;
-		session.lastFresh = { state: fresh.state, counters: fresh.counters };
-		return { messages, transientContents: [...new Set([...session.tails.map(tail => tail.content), ...blocks])] };
+		session.lastFresh = { state: fresh.state, tasks: fresh.tasks || undefined, counters: fresh.counters };
+		return { messages, transientContents: [...new Set([...session.tails.map(tail => tail.content), ...blocks.map(block => block.content)])] };
 	}
 
 	contents(sessionKey: string): string[] | undefined {

package/extensions/prompts/goal-prompts.ts

@@ -100,6 +100,10 @@ function renderPendingTasks(tasks: GoalTask[], indent: number, rendered: { count
  * indentation and contract snippets; completed/skipped are collapsed to the
  * header counts. Previously the ENTIRE tree (up to 50 tasks + subtrees) was
  * injected into every continuation prompt — most of it already-completed work.
+ *
+ * This is the request-only task snapshot: it changes with task progress, so it
+ * travels apart from the stable policy block (see goalPromptParts). The
+ * completion gate is policy and lives in taskGateBlock.
  */
 export function taskListBlock(goal: GoalRecord, settings?: GoalSettings): string {
 	if (settings?.disableTasks) return "";
@@ -145,12 +149,19 @@ export function taskListBlock(goal: GoalRecord, settings?: GoalSettings): string
 			lines.push(`  ${hiddenPending} additional pending tasks omitted; retrieve with get_goal(section="tasks").`);
 		}
 	}
-	if (goal.taskList.blockCompletion && pending! > 0) {
-		lines.push("  TASK GATE: do not request completion while tasks remain in [ ] pending state");
-	}
 	return lines.join("\n");
 }
 
+/**
+ * Stable completion gate for the policy block. It depends only on the
+ * blockCompletion setting, never on how many tasks are pending, so task
+ * progress cannot change the policy block and reset prompt-cache retention.
+ */
+export function taskGateBlock(goal: GoalRecord, settings?: GoalSettings): string {
+	if (settings?.disableTasks || goal.taskList?.blockCompletion !== true) return "";
+	return "TASK GATE: do not request completion while the latest [TASK LIST] snapshot shows tasks in [ ] pending state.";
+}
+
 /** Bounded verification-contract block. */
 function excerpt(text: string, cap: number, section: "objective" | "tasks"): string {
  const safe = promptSafeObjective(text);
@@ -207,46 +218,44 @@ const promptFragmentCache: Array<{key: readonly unknown[]; value: string; chars:
 let promptCacheChars = 0;
 
 function cachedPrompt(goal: GoalRecord, settings: GoalSettings | undefined, kind: "goal" | "continuation", build: () => string): string {
+ // Task progress is deliberately absent: it renders in the separate task
+ // snapshot, so starting or finishing a task reuses the cached policy block.
  const key = [kind, goal.id, goal.status, goal.autoContinue, goal.sisyphus, goal.objective,
-  goal.verificationContract, settings?.disableTasks ? undefined : taskIndex(goal.taskList?.tasks),
-  goal.taskList?.blockCompletion, promptProfile(), goal.currentTaskId, settings?.disableTasks, settings?.disableContracts, settings?.maxAutonomousRuns !== 0, settings?.strictExecutionContract === true, !!goal.scheduler?.wait, settings?.commands ? JSON.stringify(settings.commands) : undefined];
+  goal.verificationContract, goal.taskList?.blockCompletion, promptProfile(), settings?.disableTasks, settings?.disableContracts, settings?.maxAutonomousRuns !== 0, settings?.strictExecutionContract === true, !!goal.scheduler?.wait, settings?.commands ? JSON.stringify(settings.commands) : undefined];
  for (let i = promptFragmentCache.length - 1; i >= 0; i--) {
   const entry = promptFragmentCache[i]!;
   if (key.every((part, j) => part === entry.key[j])) return entry.value;
  }
  const value = build();
  // Include source text retained by this entry in the cache's memory allowance.
- const chars = goal.objective.length + (goal.verificationContract?.length ?? 0) + value.length
-  + (goal.taskList ? goal.taskList.tasks.reduce((n, task) => n + retainedTaskChars(task), 0) : 0);
+ const chars = goal.objective.length + (goal.verificationContract?.length ?? 0) + value.length;
  if (chars <= 2_000_000) {
   while (promptFragmentCache.length >= 32 || promptCacheChars + chars > 2_000_000) promptCacheChars -= promptFragmentCache.shift()!.chars;
   promptFragmentCache.push({key, value, chars}); promptCacheChars += chars;
  }
  return value;
 }
-function retainedTaskChars(task: GoalTask): number {
- return task.id.length + task.title.length + (task.verificationContract?.length ?? 0) + (task.evidence?.length ?? 0)
-  + (task.skipReason?.length ?? 0) + (task.subtasks?.reduce((n, child) => n + retainedTaskChars(child), 0) ?? 0);
-}
 
-export function goalPromptParts(goal: GoalRecord, settings?: GoalSettings, contextUsage?: GoalContextUsage): { state: string; counters: string } {
-	// The policy block changes only when the goal itself changes; the counters
-	// change nearly every turn. Splitting them lets request-only injection retain
-	// each at its own rate so consecutive provider requests stay prefix-stable.
+export function goalPromptParts(goal: GoalRecord, settings?: GoalSettings, contextUsage?: GoalContextUsage): { state: string; tasks?: string; counters: string } {
+	// The policy block changes only when the goal itself changes; the task
+	// snapshot changes with task progress and the counters nearly every turn.
+	// Splitting them lets request-only injection retain each at its own rate so
+	// consecutive provider requests stay prefix-stable.
 	// Scheduling instructions ride with the policy block: they are cleared by
 	// omission, so a retained copy would keep issuing a cancelled order.
 	const fixed = cachedPrompt(goal, settings, "goal", () => buildGoalPrompt(goal, settings));
 	const { runs, instructions } = schedulerSummaryParts(goal.scheduler, settings?.maxAutonomousRuns, settings?.showAutonomousRuns, settings?.idleContinuationBackoff === true, settings?.commands);
 	const limits = `Limits: lifetime tokens=${goal.tokenBudget ?? "none"}; runs=${settings?.maxAutonomousRuns ?? "unlimited"}.`;
-	const state = [fixed, instructions, limits, "Usage spans goal turns, not context. Latest snapshot supersedes earlier snapshots."].filter(Boolean).join("\n");
+	const state = [fixed, instructions, limits, "Usage spans goal turns, not context. The latest task and usage snapshots supersede earlier snapshots."].filter(Boolean).join("\n");
+	const tasks = taskListBlock(goal, settings);
 	const context = settings?.showContextUsage === true ? `\n${contextUsageLine(contextUsage)}` : "";
 	const counters = `Goal snapshot: ${formatUsage(goal)}${context}\n${runs}`;
-	return { state, counters };
+	return tasks ? { state, tasks, counters } : { state, counters };
 }
 
 export function goalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
-	const { state, counters } = goalPromptParts(goal, settings);
-	return `${state}\n${counters}`;
+	const { state, tasks, counters } = goalPromptParts(goal, settings);
+	return [state, tasks, counters].filter(Boolean).join("\n");
 }
 
 function buildGoalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
@@ -256,7 +265,7 @@ function buildGoalPrompt(goal: GoalRecord, settings?: GoalSettings): string {
   `[PI GOAL ACTIVE goalId=${goal.id}]`,
   lifecyclePolicyBlock(settings?.maxAutonomousRuns !== 0, settings?.strictExecutionContract === true || !!goal.scheduler?.wait, settings?.commands), sisyphusDisciplineBlock(goal),
   `Status: ${statusLabel(goal)}\nMode: ${goal.sisyphus ? "sisyphus" : "regular"}`,
-  untrustedObjectiveBlock(goal), taskListBlock(goal, settings), verificationContractBlock(goal, settings),
+  untrustedObjectiveBlock(goal), taskGateBlock(goal, settings), verificationContractBlock(goal, settings),
  ].filter(Boolean).join("\n\n");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantmind-br/pi-goal-x",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "description": "Fork of pi-goal-x with a fixed, cache-stable goal tool profile. Adds /goal to pi: conversational goal planning, flexible or ordered goals, persistent progress, and an independent completion auditor.",
   "license": "MIT",
   "author": "pi-goal-x contributors",