pi-goal-x 0.32.3 → 0.34.0

package/docs/advanced-usage.md

@@ -4,7 +4,13 @@ For installation, goal workflows, commands and the settings overview, see the [R
 
 ## Automatic continuation and optional execution contracts
 
-Active goals continue automatically after successful executions, including reasoning-only responses and final-task verification. No tool call, task update, scheduling declaration, or cooldown is required. Unproductive loops remain possible; optional run limits and token budgets still apply.
+Active goals continue automatically after successful executions, including reasoning-only responses and final-task verification. No tool call, task update, or scheduling declaration is required.
+
+Default continuation is immediate. To slow repeated replies without recognized work, enable **slow repeated idle replies (opt-in)** under Advanced execution in `/goal-settings` (`idleContinuationBackoff: true`). Use the scope switch to choose a global default or a project override. An explicit project `false` overrides global `true`; removing the override restores inheritance.
+
+When enabled, one execution without recognized work continues immediately. Further such executions wait 30, 60, 120, 240, then 300 seconds between attempts. Work observed anywhere in the execution or a change to the objective, requirements or tasks resets the delay. Goal inspection, echo-only calls, accounting and scheduling declarations alone do not reset it. This heuristic may delay reasoning or unfamiliar custom tools, and repeated recognized tool calls can bypass it. It reduces request rate; it does not guarantee progress or finite spending. Use a run allowance or token budget for a hard limit.
+
+The delay survives reloads and shows a relative time, local clock time and resume command. Waiting spends no autonomous runs or active time. Turning the option off cancels a pending delay promptly without renewing spent runs or resuming a paused goal. Turning it on starts observing a subsequent execution, rather than classifying work retroactively. Old saved delay metadata has no effect without opt-in. `/goal-resume` renews the run allowance and continues now; incoming user/producer messages remain ordinary host work outside that allowance. Strict waits and provider-error recovery keep their separate timing.
 
 Enable `strictExecutionContract: true` in `/goal-settings` or your global/project settings to require explicit ready/wait decisions. In that mode, a missing decision permits one repair prompt within the remaining allowance, then pauses. This is a user preference; agents should not enable it merely to continue.
 
@@ -63,7 +69,7 @@ After confirmation, a goal stopped only by its budget can continue if the revise
 
 Some Pi `openai-responses` configurations omit the wire-level `strict` flag. OpenAI Responses may normalize schemas into strict mode when that flag is omitted. This can conflict with optional goal arguments; it is separate from pi-goal-x's `strictExecutionContract` scheduling setting.
 
-For the reported OpenCode model, a narrowly scoped Pi `models.json` override makes the supported Pi 0.84.1 adapter send `strict: false` for ordinary tools:
+For the reported OpenCode model, a narrowly scoped Pi `models.json` override makes the Pi adapter send `strict: false` for ordinary tools:
 
 ```json
 {

package/docs/architecture.md

@@ -249,6 +249,26 @@ token/time intervals per turn; a goal never double-charges the same interval.
 `GoalRuntime` (goal-runtime.ts) owns continuation scheduling, the stale
 checkpoint state, the turn-stop guard, and one-shot steering reminders.
 
+`GoalScheduler` persists dispatch intent and allowance consumption. Default
+continuation is immediate. Explicit `idleContinuationBackoff=true` also records a
+bounded idle streak and earliest next attempt: one immediate continuation, then
+30 seconds doubling to five minutes. Work accumulates over the whole logical run;
+content snapshots exclude usage, revisions and scheduler writes. Disabled pacing
+skips those snapshots. Settings are rechecked at scheduling and admission; opting
+out removes saved delay metadata without renewing consumption. Resume and genuine
+host input reset pacing; strict waits and provider recovery remain independent.
+
+Pi 1.4 prepares goal-triggered turns natively. The extension uses
+`context_with_system` to filter its messages and add current goal state after
+Pi has restored the system prompt and tool declarations. System messages stay
+at their original history boundaries, including deltas from other extensions.
+`agent_settled.aborted` stops continuation/recovery and pauses the associated
+goal. Rejected stale checkpoints settle without changing the replacement goal.
+
+Audit display messages flush only at idle settlement and remain scoped to their
+session. If Pi has invalidated a settlement context, the handler skips it before
+consuming continuation intent or changing the replacement session's queue.
+
 An optional `token_budget` may be set at creation. When accounted usage
 reaches the budget, `accountProgress` transitions the goal to the distinct
 `budget_limited` status exactly once (status leaves `active`, so accounting
@@ -306,11 +326,10 @@ npm run check
 ```
 
 `test:unit`, `test:integration`, and `test:all` automatically discover test
-entries and run them in one Node process with small test-only adapters for the
+entries and run them with small test-only adapters for the
 SDK values used by handlers. This avoids loading unrelated model-provider and
-TUI media modules. The fast path requires Node 22.15+; `test:serial` remains
-the slow, real-SDK, process-isolated
-compatibility path. The suites cover: surface baselines (lifecycle-dependent goal tool
+TUI media modules. The fast path requires Node 22.19+; `test:serial` remains
+the slow, real-SDK, process-isolated alternative. The suites cover: surface baselines (lifecycle-dependent goal tool
 profile and fourteen commands), golden file/ledger fixtures, stale-continuation behavior,
 GoalService mutation boundary, runtime/accounting, token-budget transitions,
 task-tool consolidation, verification contracts, the independent auditor,

package/docs/controls.md

@@ -0,0 +1,140 @@
+# Commands and keys
+
+Open `/goal-settings` and choose **Controls**, or run `/goal-settings controls`.
+The screen has three sections: **Commands**, **Keys** and **Pausing**. Type to
+filter, use the arrow keys and Enter to edit, and Tab to switch sections.
+Page Up/Down moves through long lists; Home/End jumps to the first/last row.
+Ctrl+S switches between **This project** and **All projects**. The selected row shows
+whether its value comes from the project, global settings or the default.
+
+Changes are saved when you choose Save or confirm a recorded key. Escape backs
+out of an edit without saving. **Use inherited value** removes a project
+override; **Remove global override** restores the default. **Use default** pins
+the default in the selected scope. Each section also has a reset action that
+removes only that section's overrides in the selected scope.
+
+## Commands
+
+Each action has a preferred command followed by any aliases. Choose **Edit
+command paths** to replace them, **Add an alias** to keep the current spellings,
+or **Disable** to remove its command invocations. For example, add `/goal edit`
+to **Revise the goal** to use the existing confirmation workflow with that
+spelling. Arguments after the command path are passed through to the action.
+Subcommands appear in argument completion; the longest matching complete path
+wins. A routing-only root lists its available subcommands when called without
+a matching action.
+
+Command changes need a reload. The screen shows when changes are pending;
+Ctrl+R applies them while Pi is idle when controls were opened through a slash
+command. If controls were opened from a shortcut, close them and run `/reload`.
+Keys and pause order take effect immediately.
+
+`/goal-settings` always remains available as a recovery entry. You can give the
+settings action other spellings, but this entry cannot be removed. Pi command
+roots such as `/reload` and `/settings` are reserved. The editor checks conflicts
+with other commands before saving.
+For settings, **Recovery entry only** removes additional aliases while keeping
+`/goal-settings` available.
+
+The settings keys below are stable action IDs, even after renaming an invocation:
+
+| Action ID | Action |
+| --- | --- |
+| `goal` | Guided goal draft |
+| `sisyphus` | Guided Sisyphus draft |
+| `goal-direct` | Immediate goal creation |
+| `sisyphus-direct` | Immediate Sisyphus creation |
+| `goal-tweak` | Confirmed revision |
+| `goal-pause` | Pause goal and stop turn |
+| `goal-resume` | Resume and renew the run allowance |
+| `goal-clear` | Confirmed archival |
+| `goal-list` | List open goals |
+| `goal-status` | Status; also accepts `verbose` or `health` |
+| `goal-refresh` | Read state and settings again |
+| `goal-recovery` | Recovery report; also accepts `repair` |
+| `goal-focus` | Choose a goal |
+| `goal-unfocus` | Detach this session |
+| `goal-settings` | Settings and controls |
+| `goal-cancel` | Cancel a draft |
+
+## Keys
+
+Choose an action under **Keys**, then record a key or edit its Pi key names.
+**Record another key** adds a second binding. **Disable** leaves it unbound.
+Conflicts are checked before saving; errors leave your input available to fix.
+Use a free key or change a conflicting Pi binding in its `keybindings.json`.
+
+Every public goal shortcut is listed: pause, audit interruption, auditor toggle,
+dashboard expansion, compact scrolling, expanded navigation, and goal dialog
+controls. Each command action can also have a shortcut, independently of its
+slash command names. A shortcut for direct creation or revision asks for the
+objective or change before invoking the usual workflow.
+
+Goal dialog controls apply to questionnaires and confirmation dialogs. They
+have their own context, so the same key can confirm a dialog and pause a live
+goal. Text editing and the settings screen use Pi's usual UI controls. The
+settings screen remains usable when you change goal dialog navigation.
+While typing an answer, letters and Pi's editing keys keep editing text. Escape
+leaves the answer editor; free custom keys such as F7 can do the same.
+
+Pi key names include `escape`, `f6`, `ctrl+alt+p`, `pageUp` and `super+k`. Multiple
+keys can be separated with commas. For a comma key combined with other bindings,
+the text editor also accepts a JSON key list, for example `["ctrl+,", "f6"]`.
+Existing comma-key lists reopen in this form so they can be saved unchanged.
+Terminals must report a key before Pi can use it; some modifier combinations
+require the Kitty keyboard protocol. See [Pi's keybinding reference](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/keybindings.md).
+
+## Pausing
+
+The default is still Escape, with **Goal and turn together**. An open dialog
+owns its input; closing the expanded dashboard or interrupting an audit takes
+priority over pausing in that view.
+
+| Pause order | First press | Next press |
+| --- | --- | --- |
+| Goal and turn together | Pause the goal and stop the turn | Pi's normal interrupt |
+| Goal first | Pause the goal; let the current turn finish | Stop the remaining turn |
+| Turn first | Stop the turn and wait for the user, keeping the goal active | Pause the goal |
+
+Goal first finishes the current Pi turn, then stops before another model
+request. A turn-only stop holds automatic continuation, provider recovery and wake-ups.
+It does not spend another run allowance. Resume or send a new user message to
+continue. Reloading an interrupted autonomous run does not replay it.
+
+When you move the pause key away from Pi's interrupt key, Pi's interrupt stops
+the turn and waits for you without pausing the goal. The configured pause key
+uses the selected order. The explicit **Pause the goal** command always stops
+both the goal and its turn, including a turn left running by **Goal first**.
+
+## Settings files
+
+The UI writes the existing sparse settings layers:
+
+- Global: `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-goal-x-settings.json`.
+- Project: `<project>/.pi/pi-goal-x-settings.json`.
+
+Project leaves override global leaves. Missing leaves inherit; an empty list
+explicitly disables an action. Existing `keybindings.dashboard` settings keep
+their meaning. For example:
+
+```json
+{
+  "commands": {
+    "goal-tweak": ["goal-tweak", "goal edit"],
+    "goal-resume": ["work continue"]
+  },
+  "pauseOrder": "turn-first",
+  "keybindings": {
+    "pause": ["f6", "ctrl+alt+p"],
+    "toggleAuditor": "ctrl+alt+a",
+    "interruptAudit": "escape",
+    "dashboard": { "toggleExpand": "ctrl+alt+t" },
+    "dialog": { "confirm": "enter", "cancel": "escape" },
+    "commands": { "goal-settings": "f10", "goal-status": [] }
+  }
+}
+```
+
+Use `/goal-refresh` after external key or pause-order edits, and `/reload` after
+external command edits. Verbose goal status reports the effective controls and
+their sources. Developer-only `PI_GOAL_DEBUG` shortcuts are unchanged.

package/docs/prompt-caching.md

@@ -10,11 +10,15 @@ The request layout is:
 
 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.
 
+Goal context filtering and live-state tails use Pi's `context_with_system` event, preserving system and tool deltas in their original positions. Parent and delegated sessions use this hook from their first request.
+
 For Anthropic-style explicit caching, the extension moves Pi's existing cache_control breakpoint from the transient state message onto the preceding cacheable history block. The Bedrock equivalent moves the cachePoint. Both preserve the configured TTL and do not add breakpoints. Payloads without an existing explicit marker—including caching disabled and implicit-cache providers—receive no marker changes. The extension does not set cache keys, enable paid extended retention, or replace provider defaults.
 
 Execution tools already use an idempotent profile: goal progress, focus, and lifecycle changes do not change schemas. Explicit switches into/out of drafting and changes to disableTasks can change tools and legitimately rebuild the cache. Drafting messages are appended to conversation history. Isolated auditor and Oracle sessions already use fixed instructions/tool profiles and place goal-specific evidence in their user messages; their tool loops retain history. They have separate sessions and use Pi's cache defaults. Opting these sessions into project resources also opts into any behavior from those resources.
 
-Cache reuse can still be interrupted by Pi compaction, branch/session changes, model/provider switches, other extensions changing earlier content, changed tool schemas, provider expiry, minimum-length or breakpoint-lookback limits, or routing. The extension cannot guarantee a hit rate or a particular cost reduction. The supported Pi range is 0.83 through 0.87. Validation covers each supported minor; development dependencies pin 0.87.0.
+Cache reuse can still be interrupted by Pi compaction, branch/session changes, model/provider switches, other extensions changing earlier content, changed tool schemas, provider expiry, minimum-length or breakpoint-lookback limits, or routing. The extension cannot guarantee a hit rate or a particular cost reduction. The supported host range is Pi 1.4+ within 1.x, with Node 22.19 or newer. Development dependencies pin Pi 1.4.0.
+
+Pi 1.4 prepares custom-triggered turns through the same public startup protocol as user prompts. The extension leaves structured prompt and tool deltas intact, including additional sections supplied by other extensions. Direct creation, drafting, resume and reload use the host's native prompt preparation from the first request. Explicit tool-profile changes can still rebuild the prefix.
 
 Validation includes consecutive request-prefix regressions; actual Anthropic, Anthropic-compatible Chat Completions, OpenAI Chat Completions and Responses serialization with short/long/disabled retention; Bedrock payload-shape checks; lifecycle/tool-pair safety tests; and full SDK parent/auditor/Oracle payload captures. These tests stop before HTTP dispatch. They verify request construction, not live provider hit rates.
 

package/extensions/auditor-selector.ts

@@ -5,9 +5,11 @@
  * current-session/default choice (which clears the explicit provider/model),
  * authenticated models from the model registry (with a ✓ marker on the exact
  * current selection), and an advanced manual `provider/model` entry. The
- * thinking-level row offers the six levels or `(default)`.
+ * thinking-level row offers Pi's seven levels or `(default)`.
  */
 
+import { GOAL_THINKING_LEVELS } from "./goal-settings.ts";
+
 export type AuditorModelSummary = { provider: string; id: string; name?: string };
 
 export type AuditorChoice =
@@ -15,7 +17,7 @@ export type AuditorChoice =
 	| { kind: "model"; provider: string; model: string; label: string }
 	| { kind: "manual"; label: string };
 
-export const AUDITOR_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export const AUDITOR_THINKING_LEVELS = GOAL_THINKING_LEVELS;
 
 export function auditorModelLabel(model: AuditorModelSummary): string {
 	return `${model.provider}/${model.id}${model.name && model.name !== model.id ? ` — ${model.name}` : ""}`;

package/extensions/goal-auditor.ts

@@ -10,11 +10,12 @@ import {
 	SessionManager,
 	SettingsManager,
 	type ExtensionContext,
+	type ModelRuntime,
 	type ResourceLoader,
 } from "@earendil-works/pi-coding-agent";
 import type { GoalRecord, GoalTask, GoalTaskList } from "./goal-record.ts";
 import { countTaskSubtree } from "./goal-task-count.ts";
-import { loadGoalSettings, type GoalSettings, type ThinkingLevel } from "./goal-settings.ts";
+import { GOAL_THINKING_LEVELS, loadGoalSettings, type GoalSettings, type ThinkingLevel } from "./goal-settings.ts";
 import { statusLabel } from "./goal-core.ts";
 
 export interface AuditorProgress {
@@ -47,7 +48,7 @@ export interface GoalAuditorResult {
 	error?: string;
 }
 
-const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
+const THINKING_LEVELS = new Set<string>(GOAL_THINKING_LEVELS);
 
 function asNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value.trim() ? value.trim() : undefined;
@@ -277,25 +278,15 @@ export function resolveAuditorModel(ctx: ExtensionContext, config: GoalSettings)
 /**
  * Options that reuse the parent session's auth + registered providers for the nested auditor.
  *
- * Pi 0.81+ `createAgentSession` accepts `modelRuntime` (and ignores `modelRegistry`).
- * ExtensionContext still exposes `modelRegistry`, which wraps the live ModelRuntime.
+ * Pi 1.4's extension ModelRegistry wraps the live ModelRuntime.
  * Sharing that runtime keeps extension providers such as `pi-cursor-sdk`'s `cursor`
  * provider (and its auth) available. Without this, the auditor builds a fresh runtime
  * with an empty resource loader, so Cursor models fail with "No API key found for cursor"
  * even when `~/.pi/agent/auth.json` has a Cursor key.
- *
- * Older SDKs still accept `modelRegistry`; pass both for compatibility.
  */
-export function resolveAuditorSessionModelOptions(ctx: ExtensionContext): {
-	modelRegistry: ExtensionContext["modelRegistry"];
-	modelRuntime?: unknown;
-} {
-	const registry = ctx.modelRegistry as unknown as { runtime?: unknown } | undefined;
-	const runtime = registry?.runtime;
-	if (runtime) {
-		return { modelRegistry: ctx.modelRegistry, modelRuntime: runtime };
-	}
-	return { modelRegistry: ctx.modelRegistry };
+export function resolveAuditorSessionModelOptions(ctx: ExtensionContext): { modelRuntime?: ModelRuntime } {
+	const registry = ctx.modelRegistry as unknown as { runtime?: ModelRuntime } | undefined;
+	return { modelRuntime: registry?.runtime };
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- pi SDK types Model<any> idiomatically (pi-coding-agent sdk.d.ts)