@narumitw/pi-plan-mode 0.55.3 → 0.57.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +113 -292
- package/dist/chunks/{chunk-TZVK4O2Q.js → chunk-YUFPCQVG.js} +1664 -1455
- package/dist/chunks/chunk-YUFPCQVG.js.map +7 -0
- package/dist/chunks/{interactive-ui-S7ZRCAGJ.js → interactive-ui-M3GEZN4M.js} +183 -84
- package/dist/chunks/interactive-ui-M3GEZN4M.js.map +7 -0
- package/dist/index.ts +185 -17
- package/dist/index.ts.map +3 -3
- package/docs/command-workflows.md +52 -0
- package/docs/settings.md +169 -0
- package/package.json +5 -7
- package/src/fresh-implementation-preferences.ts +102 -0
- package/src/fresh-implementation.ts +46 -3
- package/src/implementation-options.ts +127 -0
- package/src/implementation-preferences.ts +145 -0
- package/src/plan-action-controller.ts +26 -10
- package/src/plan-action-menus.ts +65 -104
- package/src/plan-mode.ts +106 -6
- package/src/saved-plan-menu.ts +35 -7
- package/src/settings-menu.ts +35 -1
- package/src/settings.ts +55 -31
- package/src/tool-policy.ts +97 -5
- package/dist/chunks/chunk-TZVK4O2Q.js.map +0 -7
- package/dist/chunks/interactive-ui-S7ZRCAGJ.js.map +0 -7
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Plan command workflows
|
|
2
|
+
|
|
3
|
+
[Back to README](../README.md#-commands)
|
|
4
|
+
|
|
5
|
+
## Start and choose tools
|
|
6
|
+
|
|
7
|
+
`/plan start` activates Plan mode without sending a model message.
|
|
8
|
+
`/plan <prompt>` starts with an initial planning message, or sends an ordinary follow-up when already active.
|
|
9
|
+
Only the exact argument `start` selects direct activation; `/plan start a migration` is a planning prompt.
|
|
10
|
+
There is no startup flag; run `/plan start` after Pi launches.
|
|
11
|
+
|
|
12
|
+
Before starting, `/plan tools` or **Choose tools, then start…** stages a session-specific tool policy.
|
|
13
|
+
**Done — start with this policy** stores the selection and starts Plan mode.
|
|
14
|
+
Back, Escape, Ctrl+C, disposal, session replacement, or shutdown discards the unconfirmed draft without changing Plan state, active tools, thinking, or stored selection.
|
|
15
|
+
Persistent defaults belong in [Settings](./settings.md).
|
|
16
|
+
|
|
17
|
+
The TUI selector supports fuzzy search and paging; RPC shows the unfiltered list.
|
|
18
|
+
Blocked, inactive, or not-yet-registered tools remain distinguishable, and selected names awaiting metadata stay selected for first-request resolution.
|
|
19
|
+
Reopen the selector to refresh newly registered tools.
|
|
20
|
+
Active and ready workflows lock planning tools and persistent settings; exit and start a new workflow to change the allowlist.
|
|
21
|
+
Ready and saved plans expose **Implementation options…**, which stages model/thinking for that menu's implementation actions without changing the planner or saved defaults.
|
|
22
|
+
See [Planning and implementation](../README.md#-planning-and-implementation) for the first-request policy boundary, completion, and same-session versus fresh-session handoff.
|
|
23
|
+
|
|
24
|
+
## Busy transitions and recovery
|
|
25
|
+
|
|
26
|
+
Wait for Pi's run to settle before starting, exiting, saving, exporting a ready plan, implementing, or using another state-changing menu action or configured shortcut.
|
|
27
|
+
Busy transitions leave state unchanged and report a warning in TUI/RPC or an error in print/JSON mode.
|
|
28
|
+
An ordinary follow-up or `/plan finalize` can still run while Plan mode is active because neither changes its mode contract.
|
|
29
|
+
|
|
30
|
+
`show`, `save`, `export`, and `implement` require an applicable stored plan; `finalize` requires active Plan mode.
|
|
31
|
+
Cancellation and failed implementation preflight leave the stored plan intact.
|
|
32
|
+
`/plan implement` applies saved implementation preferences; menu actions additionally accept the current menu's draft overrides.
|
|
33
|
+
After kickoff, settlement, abort, and clearing an active plan do not restore model/thinking.
|
|
34
|
+
See [implementation preferences](./settings.md#implementation-model-and-thinking) for inheritance, provider-transfer effects, and partial fresh-session recovery.
|
|
35
|
+
For finalization retries, fresh-session recovery, and non-interactive limitations, see [Planning and implementation](../README.md#-planning-and-implementation).
|
|
36
|
+
|
|
37
|
+
## Export Markdown
|
|
38
|
+
|
|
39
|
+
`/plan export [path]` writes a ready, saved, or active implementation plan.
|
|
40
|
+
Without a path, it uses the configured **Export destination**, defaulting to `PLAN.md`; an explicit path always overrides the setting for that export.
|
|
41
|
+
Relative paths resolve from Pi's current working directory at export time, absolute paths stay absolute, a leading `@` is accepted, and missing parent directories are created.
|
|
42
|
+
Existing files, directories, and symbolic links are never overwritten: choose another path or remove the target first.
|
|
43
|
+
The output preserves accepted Markdown exactly apart from one trailing newline.
|
|
44
|
+
|
|
45
|
+
In TUI or RPC, **Export plan…** asks for a destination and shows the configured value and its resolved path.
|
|
46
|
+
Submit an empty value to use the configured destination.
|
|
47
|
+
A failed export retains the TUI draft for correction or reopens the RPC input; Escape returns without writing.
|
|
48
|
+
|
|
49
|
+
A successful ready-plan export ends Plan mode, restores thinking, and clears the ready state without starting a model turn or changing active tools.
|
|
50
|
+
Saved and active implementation exports preserve their existing state.
|
|
51
|
+
Failed or cancelled exports leave Plan state unchanged.
|
|
52
|
+
Export is an explicit user-requested file mutation, and the resulting file can be read with normal tools; model-initiated Plan-mode writes remain blocked.
|
package/docs/settings.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# Pi Plan Mode settings reference
|
|
2
|
+
|
|
3
|
+
[Back to README](../README.md)
|
|
4
|
+
|
|
5
|
+
- [Implementation model and thinking](#implementation-model-and-thinking)
|
|
6
|
+
- [Default Plan policy tools](#default-plan-policy-tools)
|
|
7
|
+
- [Plan reinjection](#plan-reinjection)
|
|
8
|
+
- [Export destination](#export-destination)
|
|
9
|
+
- [Toggle shortcut](#toggle-shortcut)
|
|
10
|
+
- [Safe shell subcommands](#safe-shell-subcommands)
|
|
11
|
+
- [Thinking level and persistence](#thinking-level)
|
|
12
|
+
|
|
13
|
+
## ⚙️ Settings
|
|
14
|
+
|
|
15
|
+
Open **Settings** from an inactive `/plan` menu to edit planning defaults, implementation model/thinking, reinjection, export destination, and the shortcut.
|
|
16
|
+
You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
|
|
17
|
+
`safeSubcommands` is JSON-only.
|
|
18
|
+
The optional file is read at session start, watched for changes, and created only by an explicit Settings save or manual edit.
|
|
19
|
+
The shortcut is disabled when `toggleShortcut` is omitted.
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"thinkingLevel": "inherit",
|
|
23
|
+
"defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
|
|
24
|
+
"implementationPlanRetention": "clear-on-start",
|
|
25
|
+
"defaultPlanExportPath": "PLAN.md",
|
|
26
|
+
"safeSubcommands": {
|
|
27
|
+
"git": ["rev-parse", "blame"],
|
|
28
|
+
"gh": ["pr view", "issue list"],
|
|
29
|
+
"kubectl": ["get", "apply"],
|
|
30
|
+
"npm": ["run inspect-custom"]
|
|
31
|
+
},
|
|
32
|
+
"toggleShortcut": "<your_key>"
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Implementation model and thinking
|
|
37
|
+
|
|
38
|
+
`implementationModel` is an optional object with exact, case-sensitive `provider` and `id` strings. Both must be non-blank and at most 4,096 characters; IDs are opaque, so slashes and colons are not parsed. Omit this field or choose **Use current** to make no model change. For fresh implementation, that means the destination's normal startup model, not a forced copy of the source model.
|
|
39
|
+
|
|
40
|
+
`implementationThinkingLevel` accepts `inherit` (the default), `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. `inherit` preserves normal behavior: same-session handoff restores a temporary Plan thinking override when appropriate, a model switch uses Pi's model/default thinking policy, and a fresh session uses its normal startup thinking. It does not promise to retain the planner's temporary thinking level. Explicit implementation thinking applies after model selection; Pi clamps it to the target's supported levels, and Plan mode reports an adjustment.
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"implementationModel": { "provider": "openai", "id": "your-registered-model-id" },
|
|
45
|
+
"implementationThinkingLevel": "high"
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Settings saves immediately but does not switch the running session. Each implementation menu snapshots those defaults when opened. **Implementation options…** edits a draft shared by both implementation actions in that menu; backing out of a nested picker leaves its previous choice, while closing the owning menu discards all its overrides. Reopen `/plan` to use updated defaults. `/plan implement` uses current saved defaults without a selector. Precedence is built-in behavior, user defaults, then the current menu's override; **Use current** and `inherit` can explicitly override fixed defaults.
|
|
50
|
+
|
|
51
|
+
The model picker uses Pi's scoped models when configured, otherwise its available catalogue. It does not refresh providers or resolve auth merely to display choices; close and reopen the owning menu after refreshing Pi's catalogue. Display labels are sanitized without changing raw model identity. No registered match or failed authentication blocks an explicit target rather than silently selecting a fallback.
|
|
52
|
+
|
|
53
|
+
Before kickoff, failed or cancelled preparation retains the ready/saved plan. Same-session recovery restores only still-owned runtime changes and does not overwrite a later manual choice. Pi owns authentication and model-selection operations, which have no public cancellation signal; the extension waits for them to settle and rejects stale continuations. After a fresh replacement commits, a preference failure leaves the request in the destination editor instead of starting with a fallback. If kickoff then fails, the destination retains its selected model/thinking and existing editor or active-plan recovery; the source remains resumable. Reload/resume never replays a pending preference request.
|
|
54
|
+
|
|
55
|
+
After successful kickoff there is **no automatic restoration** on `agent_end`, `agent_settled`, user abort, or active-plan clearing. A settled run is not proof that the implementation task is complete. Later manual model/thinking changes are preserved. These preferences never write Pi's global model or thinking defaults, and existing plan-retention cleanup is unchanged.
|
|
56
|
+
|
|
57
|
+
### Plan helper tools
|
|
58
|
+
|
|
59
|
+
Plan helper schemas are stable from extension registration onward, and Plan mode does not call `setActiveTools()`.
|
|
60
|
+
Tool visibility alone is not Plan activation.
|
|
61
|
+
Only the latest effective active Plan contract authorizes `plan_mode_question` or `plan_mode_complete`; ordinary planning and the `writing-plans` skill use their own workflow instead.
|
|
62
|
+
The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved or a legacy settings file is migrated.
|
|
63
|
+
|
|
64
|
+
### Default Plan policy tools
|
|
65
|
+
|
|
66
|
+
`defaultPlanTools` defines the initial runtime allowlist when a session has no stored pre-start selection.
|
|
67
|
+
Omit it—or choose **Use automatic safe built-ins**—to allow already-active safe built-ins by default.
|
|
68
|
+
An explicit empty array appears as **No optional tools** and denies every ordinary tool while the required helpers remain callable in Plan mode.
|
|
69
|
+
Neither setting changes model-visible tool schemas.
|
|
70
|
+
|
|
71
|
+
Tool names must be non-empty strings; duplicates are removed in first-seen order.
|
|
72
|
+
Explicit configured or session-selected names remain policy intent when their tool is unknown or inactive, but Plan mode never registers or activates them.
|
|
73
|
+
The inactive menu takes a fresh registered and active tool snapshot each time it opens, while an already open picker does not update in place.
|
|
74
|
+
At the workflow's first provider-bound context, after every `before_agent_start` handler has settled, Plan mode resolves retained names against Pi's live registered and active tools and freezes the executable allowlist.
|
|
75
|
+
Automatic defaults recheck the effective source metadata at that boundary, so a custom override of a safe built-in name still requires explicit opt-in.
|
|
76
|
+
The resolved allowlist persists with the active workflow and restores without reopening the resolution boundary after reload, resume, or tree navigation.
|
|
77
|
+
Unknown, inactive, and Plan-mode-blocked names remain unavailable after that resolution, and a later registration or activation waits for the next Plan workflow rather than a new session.
|
|
78
|
+
Settings shows unresolved names as pending registration; resetting to automatic removes the entire override.
|
|
79
|
+
Non-built-in names in this global setting are an explicit user-risk opt-in, just like selecting them in the pre-start workflow selector.
|
|
80
|
+
Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
|
|
81
|
+
Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
|
|
82
|
+
An effective active tool named `bash` or `powershell` remains subject to its limited-shell policy regardless of its source metadata.
|
|
83
|
+
|
|
84
|
+
A selection accepted through **Choose tools, then start…** or `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes.
|
|
85
|
+
The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
|
|
86
|
+
Settings saves immediately, but saved policy names and thinking apply only when a later Plan workflow starts; they never mutate active schemas or a workflow already in progress.
|
|
87
|
+
|
|
88
|
+
### Plan reinjection
|
|
89
|
+
|
|
90
|
+
The stable JSON field `implementationPlanRetention` controls whether and how long the `context` hook restores the exact approved plan when ordinary model context no longer contains it.
|
|
91
|
+
Omit it or use `clear-on-start` for **Off — conversation history only**, the default Codex-like behavior with no active-plan state or hidden context injection.
|
|
92
|
+
In the planning session, this policy sends `Implement the plan.` and relies on the accepted plan already present in ordinary conversation history.
|
|
93
|
+
A fresh session or saved-plan implementation instead places the complete plan in one ordinary kickoff prompt because its planning history is unavailable or intentionally excluded.
|
|
94
|
+
Use `clear-after-first-run` for **Through first implementation run** to guarantee the exact plan until that implementation's first fully settled run ends.
|
|
95
|
+
Use `keep` for **Until manually cleared** to guarantee and reinject the exact plan until `/plan exit` or supersession.
|
|
96
|
+
A resumed guaranteed-plan cleanup policy re-arms against the first context in the replacement session.
|
|
97
|
+
Failed handoff delivery restores the ready or saved plan and does not run automatic cleanup.
|
|
98
|
+
|
|
99
|
+
Changing this setting applies to the next Implement action only.
|
|
100
|
+
Each guaranteed-plan implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
|
|
101
|
+
Conversation-history-only implementation has no active Plan-mode state to show, export, or clear after kickoff.
|
|
102
|
+
|
|
103
|
+
### Export destination
|
|
104
|
+
|
|
105
|
+
`defaultPlanExportPath` controls only exports that omit a path.
|
|
106
|
+
Omit it—or submit an empty value in Settings—to use `PLAN.md`.
|
|
107
|
+
The value must be a non-empty string of at most 4,096 characters without terminal control characters or NUL.
|
|
108
|
+
Relative values are resolved against the current working directory at export time; the Settings detail and every export input preview the concrete resolved destination.
|
|
109
|
+
An explicit `/plan export <path>` is a one-off override and does not edit Settings.
|
|
110
|
+
Saving a new destination affects the next export immediately, including export of a currently active implementation.
|
|
111
|
+
|
|
112
|
+
The existing no-overwrite, cancellation, and atomic Plan-state behavior is unchanged.
|
|
113
|
+
A failed save rolls the row back to its previous value; a failed or cancelled export preserves the plan and target.
|
|
114
|
+
Long previews wrap or truncate to the available terminal width without changing the raw path used by the action.
|
|
115
|
+
|
|
116
|
+
### Toggle shortcut
|
|
117
|
+
|
|
118
|
+
`toggleShortcut` controls the global Plan-mode keybinding used by the TUI shortcut.
|
|
119
|
+
Omit this setting to keep the shortcut disabled.
|
|
120
|
+
Set `toggleShortcut` to the key string you want.
|
|
121
|
+
Avoid values that conflict with editor shortcuts.
|
|
122
|
+
|
|
123
|
+
### Safe shell subcommands
|
|
124
|
+
|
|
125
|
+
`safeSubcommands` maps any command prefix to subcommand prefixes that the user chooses to trust completely in limited `bash` and `powershell`.
|
|
126
|
+
For example, `"kubectl": ["get", "apply"]` trusts commands beginning with `kubectl get` or `kubectl apply`, while `"npm": ["run inspect-custom"]` trusts commands beginning with `npm run inspect-custom`.
|
|
127
|
+
Command keys and subcommand entries are trimmed and must be non-empty strings.
|
|
128
|
+
Matches are literal and case-sensitive after leading whitespace in the submitted command is ignored.
|
|
129
|
+
A match requires the complete `<command> <subcommand>` prefix followed by whitespace, a shell control operator, or the end of the submitted command, so `"kubectl": ["apply"]` does not match `kubectl applies`.
|
|
130
|
+
Duplicate values and command keys that become equal after trimming are merged in first-seen order.
|
|
131
|
+
Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
|
|
132
|
+
|
|
133
|
+
When a configured prefix matches, Plan mode permits the complete submitted command without parsing or applying any command, argument, mutation, chain, redirect, expansion, substitution, multiline, or PowerShell syntax checks.
|
|
134
|
+
For example, `"kubectl": ["apply"]` also permits `kubectl apply -f deployment.yaml && rm -rf build`.
|
|
135
|
+
Likewise, `"gh": ["pr view"]` permits `gh pr view 218 --web`, `gh pr view 218 > pr.txt`, and any trailing shell content.
|
|
136
|
+
The setting therefore delegates the complete shell decision to the user and can allow arbitrary code execution with Pi's permissions.
|
|
137
|
+
It is not a sandbox, confirmation gate, or read-only guarantee.
|
|
138
|
+
Choose entries that are as specific as your workflow permits, and configure them only for commands and repositories you fully trust.
|
|
139
|
+
|
|
140
|
+
Commands that do not match still use the built-in fail-closed reviewed policy.
|
|
141
|
+
That default policy includes Git `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, and `grep`, with command-specific argument checks.
|
|
142
|
+
It rejects output and input redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff, textconv, filter, or signature helpers, mutating flags, malformed command layouts, and any parsed chain containing an unsafe segment.
|
|
143
|
+
Read-dominant Git validators accept ordinary inspection flags without requiring `--no-textconv` or `--no-ext-diff`; Git may therefore invoke a helper configured by the user or trusted repository even when the command does not request one explicitly.
|
|
144
|
+
Use the negative flags when you want to suppress those configured helpers.
|
|
145
|
+
Mixed read/write surfaces remain narrower: use `git remote show -n` to avoid invoking a transport helper, while mutating `branch` and `remote` forms remain blocked unless explicitly trusted through `safeSubcommands`.
|
|
146
|
+
|
|
147
|
+
Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while configured commands can expose or modify any data available to Pi's process.
|
|
148
|
+
A built-in-policy `git -C <path>` inspection is accepted only when the path keeps Git in Pi's current working directory.
|
|
149
|
+
The default policy reduces accidental mutation and cross-repository executable configuration; configured `safeSubcommands` bypass that protection.
|
|
150
|
+
A non-object `safeSubcommands`, empty command or subcommand string, non-array value, or non-string entry invalidates the entire settings file and triggers the normal warning/default fallback on session start.
|
|
151
|
+
|
|
152
|
+
### Thinking level
|
|
153
|
+
|
|
154
|
+
Plan mode inherits Pi's current thinking level by default.
|
|
155
|
+
Set `thinkingLevel` to request a fixed level only while Plan mode is active.
|
|
156
|
+
Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
157
|
+
The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved.
|
|
158
|
+
A Settings save does not change Pi's current or default thinking level and takes effect only when the next Plan workflow starts.
|
|
159
|
+
|
|
160
|
+
Settings saves are serialized in invocation order inside one Pi process.
|
|
161
|
+
Each save re-reads the latest valid document, preserves unknown top-level fields and unedited `safeSubcommands`, then publishes through a same-directory temporary file and rename.
|
|
162
|
+
A missing file stays absent until an explicit save.
|
|
163
|
+
Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
|
|
164
|
+
This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
|
|
165
|
+
|
|
166
|
+
Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
|
|
167
|
+
Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
|
|
168
|
+
If Settings is explicitly saved while only that legacy file exists, the extension creates canonical `pi-plan-mode.json` from the complete legacy document, applies the selected change, preserves unknown fields, and leaves the legacy file untouched.
|
|
169
|
+
If both files exist, the canonical filename takes precedence.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@narumitw/pi-plan-mode",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.57.0",
|
|
4
4
|
"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"files": [
|
|
16
16
|
"src",
|
|
17
17
|
"dist",
|
|
18
|
+
"docs",
|
|
18
19
|
"README.md",
|
|
19
20
|
"LICENSE"
|
|
20
21
|
],
|
|
@@ -23,9 +24,6 @@
|
|
|
23
24
|
"./dist/index.ts"
|
|
24
25
|
]
|
|
25
26
|
},
|
|
26
|
-
"piExtension": {
|
|
27
|
-
"lifecycle": "stable"
|
|
28
|
-
},
|
|
29
27
|
"scripts": {
|
|
30
28
|
"build": "node scripts/build-runtime.mjs",
|
|
31
29
|
"check": "npm run build && biome check . && npm run typecheck",
|
|
@@ -38,9 +36,9 @@
|
|
|
38
36
|
"@earendil-works/pi-tui": "*"
|
|
39
37
|
},
|
|
40
38
|
"devDependencies": {
|
|
41
|
-
"@biomejs/biome": "2.5.
|
|
42
|
-
"@earendil-works/pi-coding-agent": "0.
|
|
43
|
-
"@earendil-works/pi-tui": "0.
|
|
39
|
+
"@biomejs/biome": "2.5.11",
|
|
40
|
+
"@earendil-works/pi-coding-agent": "0.85.0",
|
|
41
|
+
"@earendil-works/pi-tui": "0.85.0",
|
|
44
42
|
"esbuild": "0.28.2",
|
|
45
43
|
"typescript": "7.0.2"
|
|
46
44
|
},
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import {
|
|
3
|
+
createImplementationPreferenceChange,
|
|
4
|
+
hasImplementationPreferences,
|
|
5
|
+
type ImplementationSnapshot,
|
|
6
|
+
preferenceError,
|
|
7
|
+
preflightImplementationPreferences,
|
|
8
|
+
sameModel,
|
|
9
|
+
} from "./implementation-preferences.js";
|
|
10
|
+
import { type ImplementationPreferences, normalizePlanModeSettings } from "./settings.js";
|
|
11
|
+
|
|
12
|
+
export const FRESH_PREFERENCES_ENTRY = "plan-mode:fresh-preferences:v1";
|
|
13
|
+
|
|
14
|
+
export interface FreshPreferencesRequest {
|
|
15
|
+
id: string;
|
|
16
|
+
status: "pending";
|
|
17
|
+
preferences: ImplementationPreferences;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Called only for reason=new, with the destination instance's own API. */
|
|
21
|
+
export async function applyFreshImplementationPreferences(
|
|
22
|
+
pi: ExtensionAPI,
|
|
23
|
+
ctx: ExtensionContext,
|
|
24
|
+
isCurrent: () => boolean,
|
|
25
|
+
selectionSnapshot?: () => ImplementationSnapshot | undefined,
|
|
26
|
+
) {
|
|
27
|
+
if (!isCurrent() || !ctx.isIdle()) return;
|
|
28
|
+
const entry = latestPreferenceEntry(ctx);
|
|
29
|
+
if (entry?.type !== "custom" || !entry.data || typeof entry.data !== "object") return;
|
|
30
|
+
const request = entry.data as Partial<FreshPreferencesRequest>;
|
|
31
|
+
if (request.status !== "pending" || typeof request.id !== "string") return;
|
|
32
|
+
const preferences = normalizePlanModeSettings(request.preferences);
|
|
33
|
+
// Consume before any await. Reload/resume never replays a handoff selection.
|
|
34
|
+
pi.appendEntry(FRESH_PREFERENCES_ENTRY, { id: request.id, status: "failed" });
|
|
35
|
+
if (!preferences || !hasImplementationPreferences(preferences)) return;
|
|
36
|
+
const change = createImplementationPreferenceChange(
|
|
37
|
+
pi,
|
|
38
|
+
ctx,
|
|
39
|
+
isCurrent,
|
|
40
|
+
undefined,
|
|
41
|
+
selectionSnapshot,
|
|
42
|
+
);
|
|
43
|
+
try {
|
|
44
|
+
const originalModel = ctx.model;
|
|
45
|
+
const originalThinking = pi.getThinkingLevel();
|
|
46
|
+
const current = () => isCurrent() && ctx.isIdle();
|
|
47
|
+
const model = await preflightImplementationPreferences(
|
|
48
|
+
ctx,
|
|
49
|
+
preferences,
|
|
50
|
+
() =>
|
|
51
|
+
current() &&
|
|
52
|
+
sameModel(ctx.model, originalModel) &&
|
|
53
|
+
pi.getThinkingLevel() === originalThinking,
|
|
54
|
+
);
|
|
55
|
+
if (!model || !current()) return;
|
|
56
|
+
if (!(await change.apply(model, preferences, current)) || !current()) {
|
|
57
|
+
await change.rollback();
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
pi.appendEntry(FRESH_PREFERENCES_ENTRY, {
|
|
61
|
+
id: request.id,
|
|
62
|
+
status: "applied",
|
|
63
|
+
model: { provider: ctx.model?.provider, id: ctx.model?.id },
|
|
64
|
+
thinking: pi.getThinkingLevel(),
|
|
65
|
+
});
|
|
66
|
+
} catch (error) {
|
|
67
|
+
if (!isCurrent()) return;
|
|
68
|
+
await change.rollback().catch(() => undefined);
|
|
69
|
+
if (!isCurrent()) return;
|
|
70
|
+
pi.appendEntry(FRESH_PREFERENCES_ENTRY, {
|
|
71
|
+
id: request.id,
|
|
72
|
+
status: "failed",
|
|
73
|
+
error: preferenceError(error),
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** No captured source API is usable here; inspect only the replacement context. */
|
|
79
|
+
function latestPreferenceEntry(ctx: ExtensionContext) {
|
|
80
|
+
return ctx.sessionManager
|
|
81
|
+
.getBranch()
|
|
82
|
+
.slice()
|
|
83
|
+
.reverse()
|
|
84
|
+
.find((entry) => entry.type === "custom" && entry.customType === FRESH_PREFERENCES_ENTRY);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
export function freshPreferencesApplied(ctx: ExtensionContext, id: string) {
|
|
88
|
+
const entry = latestPreferenceEntry(ctx);
|
|
89
|
+
if (entry?.type !== "custom" || !entry.data || typeof entry.data !== "object") return false;
|
|
90
|
+
const result = entry.data as {
|
|
91
|
+
id?: string;
|
|
92
|
+
status?: string;
|
|
93
|
+
model?: { provider: string; id: string };
|
|
94
|
+
thinking?: string;
|
|
95
|
+
};
|
|
96
|
+
return (
|
|
97
|
+
result.id === id &&
|
|
98
|
+
result.status === "applied" &&
|
|
99
|
+
sameModel(ctx.model, result.model) &&
|
|
100
|
+
ctx.thinkingLevel === result.thinking
|
|
101
|
+
);
|
|
102
|
+
}
|
|
@@ -1,14 +1,24 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
2
|
import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
3
|
+
import {
|
|
4
|
+
FRESH_PREFERENCES_ENTRY,
|
|
5
|
+
freshPreferencesApplied,
|
|
6
|
+
} from "./fresh-implementation-preferences.js";
|
|
7
|
+
import {
|
|
8
|
+
hasImplementationPreferences,
|
|
9
|
+
preflightImplementationPreferences,
|
|
10
|
+
sameModel,
|
|
11
|
+
} from "./implementation-preferences.js";
|
|
3
12
|
import { PLAN_HISTORY_IMPLEMENTATION_PROMPT } from "./message-transform.js";
|
|
4
13
|
import { createModeContractMessage } from "./mode-contract.js";
|
|
5
|
-
import type { ImplementationPlanRetention } from "./settings.js";
|
|
14
|
+
import type { ImplementationPlanRetention, ImplementationPreferences } from "./settings.js";
|
|
6
15
|
import type { PlanCompletionSource, PlanModeState } from "./state.js";
|
|
7
16
|
|
|
8
17
|
type NewSessionOptions = Exclude<Parameters<ExtensionCommandContext["newSession"]>[0], undefined>;
|
|
9
18
|
type ReplacementContext = Parameters<NonNullable<NewSessionOptions["withSession"]>>[0];
|
|
10
19
|
|
|
11
20
|
export interface FreshImplementationRequest {
|
|
21
|
+
preferences?: ImplementationPreferences;
|
|
12
22
|
plan: string;
|
|
13
23
|
source: PlanCompletionSource;
|
|
14
24
|
retention: ImplementationPlanRetention;
|
|
@@ -17,6 +27,7 @@ export interface FreshImplementationRequest {
|
|
|
17
27
|
}
|
|
18
28
|
|
|
19
29
|
interface FreshImplementationFromStateOptions {
|
|
30
|
+
preferences?: ImplementationPreferences;
|
|
20
31
|
getState(): PlanModeState;
|
|
21
32
|
menuIsCurrent(): boolean;
|
|
22
33
|
retention: ImplementationPlanRetention;
|
|
@@ -76,6 +87,7 @@ export async function startFreshImplementationFromState(
|
|
|
76
87
|
return startFreshImplementationSession(ctx, {
|
|
77
88
|
plan,
|
|
78
89
|
source,
|
|
90
|
+
preferences: options.preferences,
|
|
79
91
|
retention: options.retention,
|
|
80
92
|
stateEntryType: options.stateEntryType,
|
|
81
93
|
isCurrent,
|
|
@@ -92,8 +104,25 @@ export async function startFreshImplementationSession(
|
|
|
92
104
|
|
|
93
105
|
await ctx.waitForIdle();
|
|
94
106
|
if (!request.isCurrent()) return { kind: "stale" };
|
|
95
|
-
|
|
96
|
-
|
|
107
|
+
const preferences = request.preferences ?? {};
|
|
108
|
+
const originalModel = ctx.model;
|
|
109
|
+
const originalThinking = ctx.thinkingLevel;
|
|
110
|
+
const preflightCurrent = () =>
|
|
111
|
+
request.isCurrent() &&
|
|
112
|
+
sameModel(ctx.model, originalModel) &&
|
|
113
|
+
ctx.thinkingLevel === originalThinking;
|
|
114
|
+
const preferencesId = hasImplementationPreferences(preferences) ? randomUUID() : undefined;
|
|
115
|
+
if (preferencesId) {
|
|
116
|
+
try {
|
|
117
|
+
if (!(await preflightImplementationPreferences(ctx, preferences, preflightCurrent)))
|
|
118
|
+
return { kind: "stale" };
|
|
119
|
+
} catch (error) {
|
|
120
|
+
if (preflightCurrent())
|
|
121
|
+
safeNotify(ctx, `Unable to implement the plan: ${safeErrorDetail(error)}`, "error");
|
|
122
|
+
return { kind: "rejected" };
|
|
123
|
+
}
|
|
124
|
+
} else if (!(await preflightModel(ctx, preflightCurrent))) return { kind: "rejected" };
|
|
125
|
+
if (!preflightCurrent() || !ctx.isIdle()) return { kind: "stale" };
|
|
97
126
|
|
|
98
127
|
const usesConversationHistory = request.retention === "clear-on-start";
|
|
99
128
|
const destinationState: PlanModeState | undefined = usesConversationHistory
|
|
@@ -124,6 +153,12 @@ export async function startFreshImplementationSession(
|
|
|
124
153
|
...(parentSession ? { parentSession } : {}),
|
|
125
154
|
setup: async (sessionManager) => {
|
|
126
155
|
try {
|
|
156
|
+
if (preferencesId)
|
|
157
|
+
sessionManager.appendCustomEntry(FRESH_PREFERENCES_ENTRY, {
|
|
158
|
+
id: preferencesId,
|
|
159
|
+
status: "pending",
|
|
160
|
+
preferences,
|
|
161
|
+
});
|
|
127
162
|
const contract = createModeContractMessage("normal");
|
|
128
163
|
sessionManager.appendCustomMessageEntry(
|
|
129
164
|
contract.customType,
|
|
@@ -139,6 +174,14 @@ export async function startFreshImplementationSession(
|
|
|
139
174
|
}
|
|
140
175
|
},
|
|
141
176
|
withSession: async (replacementCtx) => {
|
|
177
|
+
if (
|
|
178
|
+
!setupError &&
|
|
179
|
+
preferencesId &&
|
|
180
|
+
!freshPreferencesApplied(replacementCtx, preferencesId)
|
|
181
|
+
) {
|
|
182
|
+
setupError =
|
|
183
|
+
"Implementation model/thinking could not be applied or changed before kickoff";
|
|
184
|
+
}
|
|
142
185
|
if (setupError) {
|
|
143
186
|
recoverSetupFailure(replacementCtx, handoff, setupError);
|
|
144
187
|
return;
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import type { ChoiceScreen, SettingsScreen } from "@narumitw/pi-tui-kit";
|
|
3
|
+
import { safeImplementationText as terminalText } from "./implementation-preferences.js";
|
|
4
|
+
import { type ImplementationPreferences, PLAN_MODE_THINKING_LEVELS } from "./settings.js";
|
|
5
|
+
|
|
6
|
+
export function implementationModelLabel(model: ImplementationPreferences["implementationModel"]) {
|
|
7
|
+
return model ? terminalText(`${model.provider} / ${model.id}`) : "Use current";
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
export function implementationSummary(preferences: ImplementationPreferences) {
|
|
11
|
+
return `Model: ${implementationModelLabel(preferences.implementationModel)} · Thinking: ${preferences.implementationThinkingLevel && preferences.implementationThinkingLevel !== "inherit" ? preferences.implementationThinkingLevel : "Use normal behavior"}`;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export type ImplementationOptionAction =
|
|
15
|
+
| "open-implementation-model"
|
|
16
|
+
| "set-implementation-model"
|
|
17
|
+
| "set-implementation-thinking";
|
|
18
|
+
|
|
19
|
+
export function implementationSettingItems(
|
|
20
|
+
preferences: ImplementationPreferences,
|
|
21
|
+
): SettingsScreen<ImplementationOptionAction>["items"] {
|
|
22
|
+
return [
|
|
23
|
+
{
|
|
24
|
+
id: "implementationModel",
|
|
25
|
+
label: "Implementation model",
|
|
26
|
+
currentValue: implementationModelLabel(preferences.implementationModel),
|
|
27
|
+
description:
|
|
28
|
+
"Select the model only when implementation starts; never switch back automatically.",
|
|
29
|
+
action: "open-implementation-model",
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
id: "implementationThinkingLevel",
|
|
33
|
+
label: "Implementation thinking",
|
|
34
|
+
currentValue: preferences.implementationThinkingLevel ?? "inherit",
|
|
35
|
+
values: PLAN_MODE_THINKING_LEVELS,
|
|
36
|
+
description:
|
|
37
|
+
"inherit preserves normal behavior, including restoration of Plan thinking. Explicit levels apply after model selection and are clamped by Pi.",
|
|
38
|
+
action: "set-implementation-thinking",
|
|
39
|
+
},
|
|
40
|
+
];
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export function createImplementationModelPicker(ctx: ExtensionContext) {
|
|
44
|
+
// Snapshot Pi's scoped catalogue without network refresh or auth execution.
|
|
45
|
+
// Unlike /model, this picker stages a preference and never persists Pi defaults.
|
|
46
|
+
const models = ctx.scopedModels?.length
|
|
47
|
+
? ctx.scopedModels.map(({ model }) => model)
|
|
48
|
+
: ctx.modelRegistry.getAvailable();
|
|
49
|
+
const byId = new Map(
|
|
50
|
+
models.map((model, index) => [
|
|
51
|
+
`implementation-model:${index}`,
|
|
52
|
+
{ provider: model.provider, id: model.id },
|
|
53
|
+
]),
|
|
54
|
+
);
|
|
55
|
+
return {
|
|
56
|
+
selection(itemId: string) {
|
|
57
|
+
return itemId === "implementation-current" ? null : byId.get(itemId);
|
|
58
|
+
},
|
|
59
|
+
screen(preferences: ImplementationPreferences): ChoiceScreen<"set-implementation-model"> {
|
|
60
|
+
return {
|
|
61
|
+
kind: "choice",
|
|
62
|
+
title: "Implementation model",
|
|
63
|
+
enableSearch: true,
|
|
64
|
+
viewportSize: 10,
|
|
65
|
+
hint: "back",
|
|
66
|
+
action: "set-implementation-model",
|
|
67
|
+
lines: [
|
|
68
|
+
"Use current makes no model change. Reopen this menu to refresh the catalogue.",
|
|
69
|
+
"Implement here sends the planning conversation to the selected provider; fresh transfers only the approved plan and normal destination resources.",
|
|
70
|
+
`Selected: ${implementationModelLabel(preferences.implementationModel)}`,
|
|
71
|
+
],
|
|
72
|
+
items: [
|
|
73
|
+
{ id: "implementation-current", label: "Use current" },
|
|
74
|
+
...[...byId].map(([id, model]) => ({ id, label: implementationModelLabel(model) })),
|
|
75
|
+
],
|
|
76
|
+
};
|
|
77
|
+
},
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Local draft lives only as long as the owning action menu. */
|
|
82
|
+
export function createImplementationOptions(
|
|
83
|
+
ctx: ExtensionContext,
|
|
84
|
+
initial: ImplementationPreferences = {},
|
|
85
|
+
) {
|
|
86
|
+
let preferences = { ...initial };
|
|
87
|
+
let picker: ReturnType<typeof createImplementationModelPicker> | undefined;
|
|
88
|
+
return {
|
|
89
|
+
get: () => preferences,
|
|
90
|
+
summary: () => implementationSummary(preferences),
|
|
91
|
+
screens: {
|
|
92
|
+
"implementation-options": (): SettingsScreen<ImplementationOptionAction> => ({
|
|
93
|
+
kind: "settings",
|
|
94
|
+
title: "Implementation options",
|
|
95
|
+
lines: [
|
|
96
|
+
"Applies to both implementation actions in this menu only.",
|
|
97
|
+
"Changes take effect only when implementation starts. No automatic restoration afterwards.",
|
|
98
|
+
`Current model: ${implementationModelLabel(ctx.model)}`,
|
|
99
|
+
"inherit keeps normal thinking behavior, not necessarily the temporary Plan thinking level.",
|
|
100
|
+
],
|
|
101
|
+
items: implementationSettingItems(preferences),
|
|
102
|
+
}),
|
|
103
|
+
"implementation-model": () => {
|
|
104
|
+
picker ??= createImplementationModelPicker(ctx);
|
|
105
|
+
return picker.screen(preferences);
|
|
106
|
+
},
|
|
107
|
+
},
|
|
108
|
+
actions: {
|
|
109
|
+
"open-implementation-model": async () => ({
|
|
110
|
+
kind: "to" as const,
|
|
111
|
+
screen: "implementation-model" as const,
|
|
112
|
+
}),
|
|
113
|
+
"set-implementation-model": async ({ itemId }: { itemId: string }) => {
|
|
114
|
+
const selected = picker?.selection(itemId);
|
|
115
|
+
if (selected === undefined) return { kind: "rejected" as const };
|
|
116
|
+
preferences = { ...preferences, implementationModel: selected ?? undefined };
|
|
117
|
+
return { kind: "back" as const };
|
|
118
|
+
},
|
|
119
|
+
"set-implementation-thinking": async ({ value }: { value?: string }) => {
|
|
120
|
+
const level = PLAN_MODE_THINKING_LEVELS.find((level) => level === value);
|
|
121
|
+
if (!level) return { kind: "rejected" as const };
|
|
122
|
+
preferences = { ...preferences, implementationThinkingLevel: level };
|
|
123
|
+
return { kind: "stay" as const };
|
|
124
|
+
},
|
|
125
|
+
},
|
|
126
|
+
};
|
|
127
|
+
}
|