@narumitw/pi-btw 0.61.2 → 0.63.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/docs/workflows.md CHANGED
@@ -6,54 +6,109 @@
6
6
 
7
7
  `/btw` lets you start from the current conversation or choose **Start from main thread tree…** to use the root-to-selected-entry path, including the selected entry.
8
8
  The tree snapshots persisted entries and preserves the main editor draft without navigating, forking, appending to, or switching the main conversation.
9
- Side-thread context stays immutable if the main conversation later changes.
9
+
10
+ For either context source, only user and assistant messages contribute text and formatted tool-call or tool-result blocks.
11
+ Images, standalone tool-result messages, compaction summaries, branch summaries, and other session entries are excluded.
12
+ The side thread retains the last 40,000 characters of this text and adds a truncation notice when earlier content is omitted.
13
+ The initial snapshot stays immutable. Later main progress reaches the side model only after an explicit import; see [Import main updates](#import-main-updates).
10
14
  An explicit `Shift+L` label edit is the selector's only main-session mutation and persists through Pi.
11
15
  Native tree copying reports success or failure; Escape returns to the manager and Ctrl+C closes the flow.
12
16
 
13
- **Resume side thread** searches non-empty in-memory threads by their first question and question count.
17
+ **Resume side thread** searches retained in-memory threads by their first question and question count; threads containing only confirmed imports use **Main context updates** as their title.
14
18
  The first question remains the title; threads are ordered by their newest answer or visible error.
15
19
  Opening and closing without a new result does not reorder them.
16
20
  `/btw <question>` bypasses selection and always starts a new thread.
17
21
 
22
+ ## Import main updates
23
+
24
+ While the side composer is idle, use **Import main updates** (`F9` by default, then the first usable `F10` or `F11`) to review new persisted main-thread context.
25
+ The shortcut is configurable in `/btw` → **Settings**.
26
+ A `(new)` hint indicates eligible updates when the footer has room; main progress never imports content automatically.
27
+ If no shortcut is available, change the BTW shortcut or the conflicting Pi binding.
28
+ Import is unavailable while answering or draining queued side questions.
29
+
30
+ The read-only preview shows the source session, entry range, retained character count, and any omission notices.
31
+ Confirm to append exactly that snapshot, or press Escape to return without changes.
32
+ Ctrl+C closes the side flow without applying the pending import.
33
+ The main agent keeps running; entries added after the preview opens remain available for the next explicit import.
34
+ The side draft is restored when returning to the composer.
35
+
36
+ Imports contain new user text, finalized assistant text, and textual tool calls and standalone tool results in source order.
37
+ Finalized error, aborted, and length-limited assistant responses retain their status labels; they are not evidence of successful work.
38
+ Tool calls on error or aborted responses are not executed by Pi; length-limited calls receive synthetic error results instead of execution.
39
+ A tool-call batch waits until all its results exist, including parallel results; live stream deltas and partial tool updates are excluded.
40
+ Thinking, images, system instructions, and unrelated state entries are excluded.
41
+ Persisted pending responses or deferred provider handles block the cursor from advancing past them; start a new side thread from a later completed source if needed.
42
+ Each text or tool-call block is limited to 8,000 characters, and each import is limited to 40,000 characters including explicit omission notices.
43
+ Imports are limited background snapshots, not complete transcripts. Repeated imports increase total context and can increase provider cost or reach the model's context limit.
44
+ Confirmed text is sent to the selected side model's provider with the next question, not at confirmation time.
45
+
46
+ Each import appears as a searchable **Main context update**, between earlier side exchanges and later questions.
47
+ It does not count as a question or change the title.
48
+ The existing bring-to-main scopes still export successful side Q&A only, not imported main content.
49
+ Repeated imports do not duplicate the same entry range, and a later failed or cancelled side response does not undo a confirmed import.
50
+ Closing and resuming retains imports in memory, including imports made before the first question; these appear as **Main context updates** until the first question supplies a title.
51
+
52
+ The cursor must remain on the current main branch.
53
+ Navigation to an ancestor or another branch, a missing cursor, or a compaction, branch summary, or context edit after the cursor blocks import without changing the side thread.
54
+ Start a new side thread from the desired context in those cases.
55
+ Historical-tree sources can import only when they are ancestors of the current main branch.
56
+ Session replacement, reload, and restart discard imports with the rest of the retained side thread.
57
+ The [runtime audit](./main-context-runtime.md) records source boundaries, tests, and terminal-only verification limits.
58
+
18
59
  ## Read, select, and search
19
60
 
20
- The dedicated workspace keeps answers above the editor and identifies itself with a fixed `btw · side thread` header.
61
+ The dedicated workspace places the scrollable transcript above pending questions, the editor, and a compact footer.
62
+ The footer identifies BTW and shows the selected side model and thinking level when space permits; a split workspace also shows **BTW focus** or **Main focus**.
63
+ Reachable shortcut hints appear below the editor, not above it.
64
+ At constrained sizes, the active input cursor takes priority over queue previews, metadata, and hints; zero-sized views remain empty.
65
+ The [appearance reference](./native-appearance.md) records native-default comparisons and limits.
21
66
  The default **Fullscreen** layout gives the side thread the complete workspace.
22
67
  **Side thread left** and **Side thread right** place it beside Pi's native, live main-thread rendering; terminals narrower than 80 columns show only the side thread.
23
- A single muted divider separates the panes; click either pane to move keyboard focus to it.
68
+ A single muted divider separates the panes; click either pane or use the displayed pane-switch key to move keyboard focus.
69
+ By default, the switch key is the first usable F6, F7, or F8; it can be changed in [Keybindings](../README.md#keybindings).
70
+ Nested overlays keep their input ownership and block background pane switching.
24
71
  Drag the divider with the primary mouse button to resize the side thread between 20% and 80% of the workspace.
25
72
  Releasing the button saves that side-thread ratio for either pane placement; a failed save restores the last saved width and reports the error.
26
73
  Pi's search and keyboard viewport controls apply to the active pane.
27
74
  The mouse wheel scrolls the pane under the pointer without moving keyboard focus, and a narrow terminal returns focus to the visible side thread.
28
75
  A branch selected through **Start from main thread tree…** supplies side-model context but does not replace the active main thread shown in the other pane.
29
76
  The main agent may keep running, and the main pane redraws its progress while either pane is active.
30
- Submit each question with Enter; successful prior questions and answers remain available to the side model.
77
+ Submit each question with Pi's effective editor submission binding, Enter by default; successful prior questions and answers remain available to the side model.
31
78
 
32
79
  Drag the primary mouse button across the transcript to select text.
33
80
  Automatic selection copying requests Pi's host clipboard helper immediately and is enabled by default.
34
81
  With **Copy selection automatically** off, the selection stays highlighted and Pi's effective `app.message.copy` binding copies it.
35
82
  Manual copying requires Pi's fullscreen selection APIs; if unavailable, pi-btw restores the main TUI and asks you to update Pi or re-enable automatic copying.
36
- The view reports `No selection to copy`, `Copied!`, or `Copy failed` for the request; actual clipboard access still depends on the operating system and terminal.
83
+ The view reports `No selection to copy`, `Copied!`, or a sanitized clipboard error for the request; actual clipboard access still depends on the operating system and terminal.
84
+ Right-click clipboard paste is not installed because Pi has no public clipboard-read callback for this workspace.
37
85
  Ctrl+C always cancels the side flow, even if `app.message.copy` is also mapped to Ctrl+C.
38
86
 
39
- Press `Ctrl+Shift+F` to search completed or in-progress transcript text, excluding the fixed header and footer.
40
- Enter or `Ctrl+G` finds the next match; `Shift+Enter` or `Ctrl+Shift+G` finds the previous match.
41
- Escape closes search and returns focus to the composer.
87
+ Use Pi's effective transcript-search binding (`Ctrl+Shift+F` by default) to search the displayed transcript, excluding the footer.
88
+ Search remains available while answering, covering previous turns and the current question; the current answer appears only after the response completes.
89
+ The default next-match keys are Enter or `Ctrl+G`; previous-match keys are `Shift+Enter` or `Ctrl+Shift+G`.
90
+ Pi's effective search-close binding, Escape by default, closes search and returns focus to the composer.
42
91
 
43
- Scroll with the mouse wheel, trackpad, or `PgUp`/`PgDn`.
92
+ Scroll with the mouse wheel, trackpad, or Pi's effective viewport paging bindings (`PgUp`/`PgDn` by default).
93
+ Remapped or disabled bindings control behavior; the composer does not retain hidden literal paging shortcuts.
94
+ The native transcript uses automatic scrollbars and previous/next-message navigation metadata.
95
+ Manual scrolling stays fixed when new turns appear, during resize, and when content temporarily fits; explicitly returning to the latest content resumes follow mode.
44
96
  On Pi 0.85 or newer, scrolling away from the latest content reveals **Jump to latest message**.
45
- Click it or use Pi's effective `tui.altScreen.bottom` binding (`End` by default) to resume following new output.
97
+ Click it or use Pi's effective `tui.altScreen.bottom` binding (`Ctrl+End` by default) to resume following new output.
46
98
 
47
99
  ## Thinking and queued questions
48
100
 
49
- The header shows the current side-thread thinking level.
50
- Use the thinking-cycle shortcut shown in the composer to cycle supported levels for later questions.
101
+ The footer shows the current side-thread thinking level when space permits.
102
+ Use the thinking-cycle shortcut shown below the editor to cycle supported levels for later questions.
51
103
  It inherits Pi's `app.thinking.cycle` (`Shift+Tab` by default) unless overridden in [Keybindings](../README.md#keybindings).
52
104
  Whether that change is remembered depends on [Settings](../README.md#-settings); it never changes the main session's thinking level.
53
105
 
54
- During a response, submit another question to queue it as `Steering`.
106
+ During a response, the editor's top border shows `Answering…` with a spinner.
107
+ Submit another question to queue it as `Steering next`.
55
108
  Queued questions run in order after the current response, using the thinking level effective when each turn starts.
109
+ They do not interrupt the current provider response or enter Pi's main-session steering/follow-up queue.
56
110
  A failed response remains visible without discarding later queued questions.
111
+ The bounded preview above the editor shows queued questions in order and an omitted-item count when needed.
57
112
  Steering does not append to the main conversation or editor.
58
113
 
59
114
  The configured exit shortcut, or the permanent Ctrl+C hard-cancel key, cancels the active response and discards the current draft and steering queue.
@@ -62,8 +117,10 @@ Completed questions, answers, and visible errors remain resumable until the exte
62
117
  ## Bring context to the main editor
63
118
 
64
119
  After a successful answer, use the bring-to-main shortcut (`Ctrl+R` by default) to choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
120
+ All scopes, including the exact-range selector, use successful question-and-answer exchanges only; failed questions and error messages are excluded.
65
121
  The scope chooser reports the latest exchange and full-thread sizes.
66
- Question-suffix, exact-range, and full-thread choices preview an editable context block before closing the side thread.
122
+ Question-suffix, exact-range, and full-thread choices show an exact, read-only preview before closing the side thread.
123
+ The context block is editable after it is loaded into the main editor.
67
124
  Escape returns; Ctrl+C closes without bringing context back.
68
125
 
69
126
  The exact-range selector works on raw source text, not terminal-wrapped rows, and reports line, message, and approximate token counts.
@@ -78,5 +135,12 @@ Cancel returns to the side thread without changing either draft, and concurrent
78
135
  The success message reports whether context was loaded, appended, or replaced and its approximate size.
79
136
 
80
137
  Without an explicit bring action, closing `/btw` never changes the main conversation.
81
- Resume state is memory-only: `/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard it.
138
+ Resume state is memory-only: `/new`, Pi `/resume`, `/fork`, `/reload`, extension replacement, and process restart discard it.
82
139
  Unsent drafts, steering queues, interrupted answers, and model credentials are not retained.
140
+
141
+ ## Core compatibility and verification
142
+
143
+ The [core-alignment handoff](./core-alignment.md) records finding dispositions, deterministic evidence, retained workspace deviations, and proposed Pi APIs.
144
+ The [appearance reference](./native-appearance.md) contains native CLI reference frames, before/after BTW frames, public API reuse decisions, and terminal-review instructions.
145
+ The package-directory smoke is non-interactive and does not contact a provider.
146
+ Terminal-specific mouse, clipboard, IME, keyboard-protocol, and visual acceptance still require a terminal operator.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-btw",
3
- "version": "0.61.2",
3
+ "version": "0.63.0",
4
4
  "description": "Pi extension that adds a /btw side-question command.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -32,9 +32,9 @@
32
32
  "prepack": "npm run build"
33
33
  },
34
34
  "devDependencies": {
35
- "@earendil-works/pi-ai": "1.2.0",
36
- "@earendil-works/pi-coding-agent": "1.2.0",
37
- "@earendil-works/pi-tui": "1.2.0",
35
+ "@earendil-works/pi-ai": "1.3.0",
36
+ "@earendil-works/pi-coding-agent": "1.3.0",
37
+ "@earendil-works/pi-tui": "1.3.0",
38
38
  "esbuild": "0.28.2",
39
39
  "typescript": "7.0.2"
40
40
  },