@kky42/pi-goal 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+## Unreleased
+
+## 1.0.0 - 2026-05-30
+
+- Renames the public package to `@kky42/pi-goal` for npm and pi package installs.
+- Aligns goal initialization, continuation, blocked handling, prompt cache behavior, and tool-facing goal output with the Codex-style goal contract.
+- Refreshes the README around installation, usage, and the Pi-Goal vs. Codex Goal comparison for the public 1.0.0 release.
+
+## 0.1.15 - 2026-05-27
+
+- Refactors the goal runtime monolith into focused modules for clearer lifecycle ownership, event handling, and continuation orchestration.
+- Narrows runtime handler dependency interfaces so input/context, turn, agent, and session handlers only receive the lifecycle ports they use.
+- Moves goal transition effect application into a focused effect module so transition planning stays centered on goal snapshots and persistence decisions.
+- Reworks the stale queued-work reducer around per-lifecycle default transition tables and focused state reducers, keeping no-op handling centralized while preserving explicit exceptional transitions.
+- Removes the queued provider-context rewrite type assertion by returning typed provider-context rewrite intersections and clarifies the message normalization boundary comments.
+- Hardens stale queued-work cleanup across abort, delayed terminal events, and continuation boundaries so stale work is consumed without mutating replacement-goal accounting.
+- Tightens runtime continuation scheduling, recovery sequencing, and persistence/accounting handoff behavior with expanded regression coverage around lifecycle edge cases.
+- Updates the local pi development baseline to `@earendil-works/*` `0.76.0` and refreshes the npm lockfile.
+- Aligns recovery retry classification with Pi 0.76.0 so terminal quota, billing, and provider-limit errors do not stay pending for host retries even when they include `429` wording.
+- Validates the cutover with the existing typecheck/test suite plus package metadata and dry-run pack checks.
+
+## 0.1.14 - 2026-05-26
+
+- Widens the package Node engine range to support Node 22.19.0 through Node 26.x.
+
+## 0.1.13 - 2026-05-26
+
+- Bounds hidden goal continuation provider context by superseding older active-goal continuations with short bookkeeping markers, refreshing only the latest continuation, and using compact auto-continuation prompts after `/goal` start or resume.
+- Stops provider-error continuation retry storms by skipping immediate hidden requeues on `stopReason: "error"`, auto-compacting on context-window overflow when available, using bounded backoff for transient failures, and pausing with a recoverable `/goal resume` path when recovery is exhausted.
+- Makes goal lifecycle transitions terminal and idempotent: duplicate `update_goal complete` calls no longer append extra session entries, completed goals cannot be paused or resumed, and runtime/compaction skips unchanged goal snapshots.
+- Coalesces runtime goal persistence so repeated tool completions and unchanged compaction snapshots do not append full goal entries on every event; live footer usage stays current, and turn boundaries, shutdown, budget crossings, and bounded long-run intervals flush pending accounting to session history.
+- Allows `create_goal` to replace a completed goal and clarifies recovery via `/goal <objective>` or `/goal clear`.
+- Surfaces failed goal tool calls as real pi tool errors by throwing from tool handlers.
+
+## 0.1.12 - 2026-05-23
+
+- Updated the local pi development baseline to `@earendil-works/*` `0.75.5`, refreshed Node/tsx tooling, and regenerated the npm lockfile.
+- Reviewed the pi `0.75.5` changelog and package guidance; the goal extension remains compatible with current extension lifecycle and package install/update behavior.
+
+## 0.1.11 - 2026-05-21
+
+- Cancels stale hidden goal continuations before they can reach the model after a goal is completed, cleared, or replaced.
+- Keeps stale abort cleanup from charging tokens, pausing active replacement goals, persisting extra entries, or requeueing continuations during compaction and shutdown.
+- Allows normal interactive and RPC prompts that paste continuation marker text to pass through instead of being treated as hidden extension follow-up work.
+- Adds regression coverage for stale queued work across missing or delayed `agent_end`, late stale terminal events, compaction cleanup, and pasted marker input sources.
+
+## 0.1.10 - 2026-05-18
+
+- Updated the local pi package baseline to `@earendil-works/*` `0.75.3` and refreshed the npm lockfile.
+- Removed tracked CueLoop runtime state from the package and ignored local `.cueloop/` artifacts.
+
+
+## 0.1.9 - 2026-05-09
+
+- Escapes goal objectives in hidden continuation and budget-limit prompts before embedding them in XML-style untrusted blocks.
+- Keeps budget-limited goals from being paused or resumed back to active while they remain at or over budget.
+- Sends a one-shot hidden budget-limit steering message when token accounting crosses the configured budget.
+- Keeps ordinary user prompts from silently reactivating paused goals; session resume now prompts before restarting a paused goal.
+- Returns Codex-shaped goal tool responses with `remainingTokens` and completion budget reports.
+- Prevents tokens from an old in-flight turn from being charged to a replacement goal.
+- Updates `/goal` summary and footer labels toward Codex-style status wording while retaining this package's 8000-character objective limit.
+
+## 0.1.8 - 2026-05-07
+
+- Migrates the local pi development baseline and peer metadata from deprecated `@mariozechner/*` packages to maintained `@earendil-works/*` `0.74.0`.
+- Regenerates the npm lockfile against the current stable dependency graph.
+
+## 0.1.7 - 2026-05-07
+
+- Keeps active goals continuing after auto-compaction, including length-stop compactions.
+- Prevents stale queued goal continuations from running after a goal is completed or changed.
+- Strengthens completion-audit prompts and update-goal guidance so goals are marked complete only after verified completion.
+- Avoids duplicate persisted completion entries from `update_goal`.
+
+## 0.1.6 - 2026-05-06
+
+- Clarifies README install commands for npm, pinned npm, GitHub, and pinned GitHub package installs.
+
+## 0.1.5 - 2026-05-06
+
+- Counts goal tokens from completed assistant input plus output usage instead of `usage.totalTokens`.
+- Excludes cache read and cache write accounting channels from goal token budgets so cached provider tokens do not inflate sent and received totals.
+
+## 0.1.4 - 2026-05-06
+
+- Pauses active goals when pi reports an aborted assistant turn, including user Esc aborts.
+- Resumes paused goals automatically on the next user-driven agent start, while keeping `/goal resume` available.
+- Prevents aborted turns from immediately queueing hidden continuation messages.
+
+## 0.1.3 - 2026-05-06
+
+- Corrects the README behavior summary to describe completed assistant turn token accounting.
+
+## 0.1.2 - 2026-05-06
+
+- Counts completed assistant turn usage via pi's `usage.totalTokens` instead of using context-window deltas, so goal token totals track tokens sent and received across compaction.
+- Keeps elapsed-time accounting stable before and after compaction while continuing to persist active goal state.
+
+## 0.1.1 - 2026-05-06
+
+- Marks pi runtime peer dependencies as optional so `pi install npm:pi-codex-goal` stays lightweight while still documenting the extension runtime contract.
+
+## 0.1.0 - 2026-05-06
+
+- Initial public release.
+- Adds Codex-style `/goal` tracking for pi.
+- Adds model-callable `get_goal`, `create_goal`, and `update_goal` tools.
+- Persists goal state in pi session custom entries for resume, reload, fork, tree navigation, and compaction.
+- Starts and resumes goals with hidden follow-up messages so active objectives keep moving.
+- Shows live elapsed active time and compact/exact token counts in the pi footer.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitch Fultz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Pi-Goal
+
+Pi-Goal brings Codex-style persistent goals to pi. It keeps a thread-scoped objective moving across turns, resumes, forks, compaction, provider errors, and queued user messages while preserving user control with `/goal pause`, `/goal resume`, and `/goal clear`.
+
+## Install and How to Use
+
+```sh
+pi install npm:@kky42/pi-goal
+```
+
+Use `/goal` from any pi session:
+
+```text
+/goal
+/goal Build the requested feature and verify it end to end
+/goal pause
+/goal resume
+/goal clear
+```
+
+`/goal <objective>` creates an active goal, displays the full goal summary, and asks the agent to continue immediately. Token budgets are set through the goal tool, matching Codex behavior, rather than parsed from `/goal --tokens`.
+
+## Pi-Goal vs. Codex Goal
+
+| Area | Pi-Goal | Codex Goal |
+| --- | --- | --- |
+| Availability | Installable pi package: `pi install npm:@kky42/pi-goal` | Built into Codex |
+| Goal start | `/goal <objective>` stores a thread-scoped goal and sends full goal context to the agent | Native goal initialization in the Codex thread |
+| Continuation | Scheduler-owned hidden continuations after idle; queued user messages win | Native Codex continuation loop |
+| State | Persisted as pi session custom entries, so it survives resume, fork, tree navigation, reload, and compaction | Stored in Codex's internal thread goal state |
+| Completion | Agent marks `complete` only after a completion audit via `update_goal` | Same completion-audit contract |
+| Blocked state | Agent can mark `blocked`; `/goal resume` reactivates paused or blocked goals | Same blocked/resume behavior |
+| Token budget | Optional model-side budget; reaching it marks the goal `budgetLimited` and asks the agent to wrap up | Native Codex goal budget handling |
+| Prompt caching | Historical continuation prompts stay byte-stable; stale continuations are dropped at runtime using metadata | Managed by Codex internals |
+| Main difference | Codex-style goal behavior implemented as an inspectable pi extension | First-party Codex implementation |

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@kky42/pi-goal",
+  "version": "1.0.0",
+  "description": "Codex-style goal tracking and continuation for pi.",
+  "type": "module",
+  "author": "kky42",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "extension",
+    "codex",
+    "goal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kky42/pi-goal.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kky42/pi-goal/issues"
+  },
+  "homepage": "https://github.com/kky42/pi-goal#readme",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "test:e2e:real": "PI_GOAL_REAL_E2E=1 node --import tsx --test test/real-e2e.test.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.76.0",
+    "@earendil-works/pi-coding-agent": "0.76.0",
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typebox": "1.1.38",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22.19.0 <27"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "npm@11.0.0"
+}

package/src/commands.ts

@@ -0,0 +1,107 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { formatGoalSummary } from "./format.js";
+import { replaceGoal, updateGoalStatus } from "./state.js";
+import type { GoalEntrySource, ThreadGoal } from "./types.js";
+
+export interface CommandHost {
+  getGoal(): ThreadGoal | null;
+  setGoal(goal: ThreadGoal, source: GoalEntrySource, ctx: GoalCommandContext): void;
+  clearGoal(source: GoalEntrySource, ctx: GoalCommandContext): void;
+  requestContinuation(ctx: GoalCommandContext): void;
+}
+
+const COMMANDS = ["pause", "resume", "clear"] as const;
+const GOLDEN_SET_BANNER = "\x1b[38;5;220mGoal set.\x1b[39m";
+
+export type GoalCommandPi = Pick<ExtensionAPI, "registerCommand">;
+
+export interface GoalCommandContext {
+  hasUI: boolean;
+  ui: Pick<ExtensionCommandContext["ui"], "confirm" | "notify" | "setStatus">;
+}
+
+function completions(prefix: string) {
+  return COMMANDS.filter((command) => command.startsWith(prefix)).map((command) => ({
+    value: command,
+    label: command,
+    description: `goal ${command}`,
+  }));
+}
+
+export async function handleGoalCommand(
+  _pi: GoalCommandPi,
+  host: CommandHost,
+  args: string,
+  ctx: GoalCommandContext,
+): Promise<void> {
+  const trimmed = args.trim();
+  if (trimmed.length === 0) {
+    ctx.ui.notify(formatGoalSummary(host.getGoal()));
+    return;
+  }
+
+  if (trimmed === "clear") {
+    const goal = host.getGoal();
+    if (!goal) {
+      ctx.ui.notify("No goal is set.", "warning");
+      return;
+    }
+    host.clearGoal("command", ctx);
+    ctx.ui.notify("Goal cleared.");
+    return;
+  }
+
+  if (trimmed === "pause" || trimmed === "resume") {
+    const current = host.getGoal();
+    const status = trimmed === "pause" ? "paused" : "active";
+    const result = updateGoalStatus(current, status);
+    if (!result.ok || !result.goal) {
+      ctx.ui.notify(result.message, "warning");
+      return;
+    }
+    host.setGoal(result.goal, "command", ctx);
+    ctx.ui.notify(result.message);
+    if (trimmed === "resume" && result.goal.status === "active") {
+      host.requestContinuation(ctx);
+    }
+    return;
+  }
+
+  const current = host.getGoal();
+  if (current && current.status !== "complete") {
+    if (!ctx.hasUI) {
+      ctx.ui.notify("Clear the existing goal before replacing it.", "error");
+      return;
+    }
+    const shouldReplace = await ctx.ui.confirm(
+      "Replace goal?",
+      `Current goal:\n${current.objective}\n\nNew goal:\n${trimmed}`,
+    );
+    if (!shouldReplace) {
+      ctx.ui.notify("Goal unchanged.");
+      return;
+    }
+  }
+
+  const result = replaceGoal(trimmed);
+  if (!result.ok || !result.goal) {
+    ctx.ui.notify(result.message, "error");
+    return;
+  }
+  host.setGoal(result.goal, "command", ctx);
+  ctx.ui.notify([GOLDEN_SET_BANNER, formatGoalSummary(result.goal)].join("\n"));
+  host.requestContinuation(ctx);
+}
+
+export function registerGoalCommand(pi: GoalCommandPi, host: CommandHost): void {
+  pi.registerCommand("goal", {
+    description: "Show or manage the current Codex-style goal.",
+    getArgumentCompletions(argumentPrefix) {
+      return completions(argumentPrefix.trim());
+    },
+    async handler(args: string, ctx: ExtensionCommandContext) {
+      await handleGoalCommand(pi, host, args, ctx);
+    },
+  });
+}

package/src/continuation-scheduler.ts

@@ -0,0 +1,174 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { continuationGoalIdFromPrompt, continuationPrompt } from "./prompts.js";
+import {
+  recoveryPhaseBlocksContinuation,
+  type GoalRecoveryMachineState,
+} from "./recovery-machine.js";
+import { isRecoveryPendingAttention } from "./recovery.js";
+import { CONTINUATION_RETRY_MS } from "./runtime-config.js";
+import type { StaleQueuedWorkGuard } from "./stale-queued-work-guard.js";
+import { CUSTOM_ENTRY_TYPE, type ThreadGoal } from "./types.js";
+
+interface ContinuationSchedulerDeps {
+  pi: Pick<ExtensionAPI, "sendMessage">;
+  getGoal: () => ThreadGoal | null;
+  getRecoveryState: () => GoalRecoveryMachineState;
+  staleQueuedWorkGuard: StaleQueuedWorkGuard;
+  getCurrentTurnIndex: () => number | null;
+}
+
+export function createContinuationScheduler(deps: ContinuationSchedulerDeps) {
+  let continuationQueuedFor: string | null = null;
+  let continuationScheduledFor: string | null = null;
+  let continuationTimer: ReturnType<typeof setTimeout> | null = null;
+  let passthroughContinuationInput: { text: string; turnIndex: number | null } | null = null;
+
+  const clearContinuationTimer = (): void => {
+    if (continuationTimer) {
+      clearTimeout(continuationTimer);
+      continuationTimer = null;
+    }
+    continuationScheduledFor = null;
+  };
+
+  const clearContinuationState = (): void => {
+    clearContinuationTimer();
+    continuationQueuedFor = null;
+  };
+
+  const clearContinuationStateFor = (goalId: string): void => {
+    if (continuationQueuedFor === goalId) {
+      continuationQueuedFor = null;
+    }
+    if (continuationScheduledFor === goalId) {
+      clearContinuationTimer();
+    }
+  };
+
+  const markContinuationQueued = (goalId: string): void => {
+    continuationQueuedFor = goalId;
+  };
+
+  const clearPassthroughContinuationInput = (): void => {
+    passthroughContinuationInput = null;
+  };
+
+  const bindPassthroughContinuationInputToTurn = (turnIndex: number): void => {
+    if (!passthroughContinuationInput) {
+      return;
+    }
+    if (passthroughContinuationInput.turnIndex === null) {
+      passthroughContinuationInput = { ...passthroughContinuationInput, turnIndex };
+      return;
+    }
+    if (passthroughContinuationInput.turnIndex !== turnIndex) {
+      clearPassthroughContinuationInput();
+    }
+  };
+
+  const isPassthroughContinuationInput = (text: string): boolean => {
+    if (!passthroughContinuationInput || passthroughContinuationInput.text !== text) {
+      return false;
+    }
+    const currentTurnIndex = deps.getCurrentTurnIndex();
+    return (
+      passthroughContinuationInput.turnIndex === null ||
+      passthroughContinuationInput.turnIndex === currentTurnIndex
+    );
+  };
+
+  const continuationGoalIdFromRuntimePrompt = (prompt: string): string | null => {
+    if (isPassthroughContinuationInput(prompt)) {
+      return null;
+    }
+    return continuationGoalIdFromPrompt(prompt);
+  };
+
+  const notePassthroughContinuationInput = (text: string): void => {
+    passthroughContinuationInput = { text, turnIndex: null };
+  };
+
+  const hasPendingRecoveryAttention = (): boolean => {
+    const goal = deps.getGoal();
+    return Boolean(goal?.status === "active" && isRecoveryPendingAttention(deps.getRecoveryState().attention));
+  };
+
+  const sendContinuation = (goalToContinue: ThreadGoal): void => {
+    continuationQueuedFor = goalToContinue.goalId;
+    deps.pi.sendMessage(
+      {
+        customType: CUSTOM_ENTRY_TYPE,
+        content: continuationPrompt(goalToContinue),
+        display: false,
+        details: { kind: "continuation", goalId: goalToContinue.goalId },
+      },
+      { triggerTurn: true, deliverAs: "followUp" },
+    );
+  };
+
+  const requestContinuation = (ctx: ExtensionContext): void => {
+    const goal = deps.getGoal();
+    if (
+      deps.staleQueuedWorkGuard.isBlockingContinuation() ||
+      !goal ||
+      goal.status !== "active" ||
+      continuationQueuedFor === goal.goalId ||
+      hasPendingRecoveryAttention() ||
+      recoveryPhaseBlocksContinuation(deps.getRecoveryState().phase)
+    ) {
+      return;
+    }
+
+    const goalId = goal.goalId;
+    if (ctx.hasPendingMessages()) {
+      if (continuationScheduledFor === goalId) {
+        clearContinuationTimer();
+      }
+      return;
+    }
+
+    if (!ctx.isIdle()) {
+      if (continuationScheduledFor === goalId) {
+        return;
+      }
+      continuationScheduledFor = goalId;
+      continuationTimer = setTimeout(() => {
+        continuationTimer = null;
+        continuationScheduledFor = null;
+        requestContinuation(ctx);
+      }, CONTINUATION_RETRY_MS);
+      continuationTimer.unref?.();
+      return;
+    }
+
+    clearContinuationTimer();
+    const currentGoal = deps.getGoal();
+    if (
+      deps.staleQueuedWorkGuard.isBlockingContinuation() ||
+      !ctx.isIdle() ||
+      ctx.hasPendingMessages() ||
+      !currentGoal ||
+      currentGoal.status !== "active" ||
+      currentGoal.goalId !== goalId ||
+      continuationQueuedFor === goalId ||
+      hasPendingRecoveryAttention() ||
+      recoveryPhaseBlocksContinuation(deps.getRecoveryState().phase)
+    ) {
+      return;
+    }
+    sendContinuation(currentGoal);
+  };
+
+  return {
+    bindPassthroughContinuationInputToTurn,
+    clearContinuationState,
+    clearContinuationStateFor,
+    clearContinuationTimer,
+    clearPassthroughContinuationInput,
+    continuationGoalIdFromRuntimePrompt,
+    markContinuationQueued,
+    notePassthroughContinuationInput,
+    requestContinuation,
+  };
+}