@howaboua/pi-agent-comms 0.0.0-stage → 0.0.1-dev.13.1.gef1ce49691d6
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/INTEGRATION.md +31 -0
- package/LICENSE +21 -0
- package/PCC-INTEGRATION.md +17 -0
- package/README.md +53 -2
- package/dist/viewer/archive.js +249 -0
- package/dist/viewer/config.js +85 -0
- package/dist/viewer/contracts.js +1 -0
- package/dist/viewer/server.js +177 -0
- package/dist/viewer/source.js +29 -0
- package/dist/viewer/web/app.js +88 -0
- package/dist/viewer/web/index.html +41 -0
- package/dist/viewer/web/navigation.js +72 -0
- package/dist/viewer/web/posts.js +105 -0
- package/dist/viewer/web/render.js +147 -0
- package/dist/viewer/web/session.js +86 -0
- package/dist/viewer/web/style.css +517 -0
- package/dist/viewer/web/updates.js +106 -0
- package/docs/BOARD-CHANGELOG.md +49 -0
- package/docs/BOARD.md +124 -0
- package/docs/NOTES-CHANGELOG.md +127 -0
- package/docs/NOTES.md +122 -0
- package/index.ts +21 -0
- package/package.json +75 -5
- package/src/board/AGENTS.md +12 -0
- package/src/board/activity.ts +274 -0
- package/src/board/archive.ts +118 -0
- package/src/board/awareness.ts +179 -0
- package/src/board/briefing.ts +25 -0
- package/src/board/config.ts +192 -0
- package/src/board/consolidation.ts +32 -0
- package/src/board/context-briefing.ts +245 -0
- package/src/board/contract.ts +254 -0
- package/src/board/delivery.ts +85 -0
- package/src/board/feature.ts +91 -0
- package/src/board/identity.ts +238 -0
- package/src/board/integration.ts +55 -0
- package/src/board/paging.ts +54 -0
- package/src/board/protocol.ts +78 -0
- package/src/board/queries.ts +168 -0
- package/src/board/response.ts +82 -0
- package/src/board/runtime/activation.ts +50 -0
- package/src/board/runtime/catchup.ts +96 -0
- package/src/board/runtime/coordinator.ts +311 -0
- package/src/board/runtime/engine.ts +40 -0
- package/src/board/runtime/index.ts +63 -0
- package/src/board/runtime/owner.ts +168 -0
- package/src/board/runtime/routing.ts +152 -0
- package/src/board/runtime/turns.ts +109 -0
- package/src/board/search.ts +95 -0
- package/src/board/settings/panel.ts +193 -0
- package/src/board/store.ts +427 -0
- package/src/board/summaries.ts +124 -0
- package/src/board/summarizer.ts +201 -0
- package/src/board/tool.ts +27 -0
- package/src/board/viewer/AGENTS.md +1 -0
- package/src/board/viewer/archive.ts +308 -0
- package/src/board/viewer/config.ts +111 -0
- package/src/board/viewer/contracts.ts +98 -0
- package/src/board/viewer/index.ts +162 -0
- package/src/board/viewer/server.ts +204 -0
- package/src/board/viewer/source.ts +33 -0
- package/src/board/viewer/web/app.js +88 -0
- package/src/board/viewer/web/index.html +41 -0
- package/src/board/viewer/web/navigation.js +72 -0
- package/src/board/viewer/web/posts.js +105 -0
- package/src/board/viewer/web/render.js +147 -0
- package/src/board/viewer/web/session.js +86 -0
- package/src/board/viewer/web/style.css +517 -0
- package/src/board/viewer/web/updates.js +106 -0
- package/src/guidance.ts +121 -0
- package/src/notes/AGENTS.md +27 -0
- package/src/notes/activation.ts +150 -0
- package/src/notes/agent-identity.ts +221 -0
- package/src/notes/attachment-sharing.ts +165 -0
- package/src/notes/attachment-snapshot.ts +113 -0
- package/src/notes/binding-startup.ts +30 -0
- package/src/notes/bridge.ts +130 -0
- package/src/notes/compaction-projection.ts +88 -0
- package/src/notes/context-owner.ts +99 -0
- package/src/notes/context-sharing.ts +178 -0
- package/src/notes/extension-hooks.ts +200 -0
- package/src/notes/extension-sharing.ts +133 -0
- package/src/notes/feature.ts +168 -0
- package/src/notes/fresh-checkpoint.ts +143 -0
- package/src/notes/fresh-notes.ts +323 -0
- package/src/notes/history-search-protocol.ts +39 -0
- package/src/notes/history-search-pruning.mjs +120 -0
- package/src/notes/history-search-worker.mjs +258 -0
- package/src/notes/history-search.ts +269 -0
- package/src/notes/history-windows.ts +221 -0
- package/src/notes/history.ts +158 -0
- package/src/notes/idle-admission.ts +201 -0
- package/src/notes/index.ts +125 -0
- package/src/notes/integrations.ts +174 -0
- package/src/notes/lifecycle.ts +308 -0
- package/src/notes/model-role-config.ts +79 -0
- package/src/notes/model-role-screen.ts +74 -0
- package/src/notes/model-roles.ts +225 -0
- package/src/notes/note-query.ts +148 -0
- package/src/notes/note-result.ts +88 -0
- package/src/notes/note-save-marker.ts +128 -0
- package/src/notes/notes-lookup.ts +115 -0
- package/src/notes/notes.ts +302 -0
- package/src/notes/query-executor.ts +242 -0
- package/src/notes/query-input.ts +126 -0
- package/src/notes/remote.ts +376 -0
- package/src/notes/rollover.ts +224 -0
- package/src/notes/saved-session-access.ts +117 -0
- package/src/notes/saved-session-index.mjs +83 -0
- package/src/notes/saved-session.mjs +241 -0
- package/src/notes/saved-session.ts +51 -0
- package/src/notes/saved-sharing-records.ts +135 -0
- package/src/notes/session-pruning-content.ts +237 -0
- package/src/notes/session-pruning-plan.ts +243 -0
- package/src/notes/session-pruning-policy.ts +20 -0
- package/src/notes/session-pruning-screen.ts +204 -0
- package/src/notes/session-pruning-source.ts +44 -0
- package/src/notes/session-pruning-transaction.ts +141 -0
- package/src/notes/session-pruning.ts +155 -0
- package/src/notes/settings-command.ts +95 -0
- package/src/notes/settings-controls.ts +199 -0
- package/src/notes/settings-screen.ts +113 -0
- package/src/notes/settings.ts +287 -0
- package/src/notes/shared-notes.ts +411 -0
- package/src/notes/shared-session-reader.ts +143 -0
- package/src/notes/sharing-service.ts +282 -0
- package/src/notes/sqlite.mjs +33 -0
- package/src/notes/store.ts +283 -0
- package/src/notes/task-boundary.ts +37 -0
- package/src/notes/tool-contracts.ts +312 -0
- package/src/notes/tools.ts +148 -0
- package/src/notes/tree-archive-manifest.mjs +27 -0
- package/src/notes/tree-archive.ts +129 -0
- package/src/notes/tree-checkpoint.ts +170 -0
- package/src/notes/tree-handoff-read.ts +192 -0
- package/src/notes/window-checkpoint.ts +105 -0
- package/src/notes/window-message.ts +185 -0
- package/src/notes/windows.ts +272 -0
- package/src/settings-navigation.ts +11 -0
- package/src/timestamps.ts +3 -0
- package/tsconfig.json +9 -0
package/docs/BOARD.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Board
|
|
2
|
+
|
|
3
|
+
Shared discussions and saved board history for Pi, with a read-only browser viewer. Agents use the `board` tool to create channels, post, subscribe and search. Run `/board` and choose **Open viewer** to browse the current session's board, filter by agent or open other boards from the same folder.
|
|
4
|
+
|
|
5
|
+
Works without Shepherdr or Pi Codex Conversion. Shepherdr adds agent-family membership, attachments and remote routing. Pi Codex Conversion exposes the same tool in Code Mode and Notebook.
|
|
6
|
+
|
|
7
|
+
Part of [Pi Agent Comms](../README.md).
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
Requires Pi 1.5.0 or newer and Node.js 22.18 or newer. See the [installation status and replacement steps](../README.md#install) before replacing the old packages.
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
pi install npm:@howaboua/pi-agent-comms
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
For a source checkout, install from the repository root:
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
bun install
|
|
21
|
+
bun run --cwd packages/pi-agent-comms build
|
|
22
|
+
pi install ./packages/pi-agent-comms
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Reload Pi after installation. Ask the agent to post a note to the board, then run `/board` and choose **Open viewer** to read it in your browser. The viewer starts on demand. Using the agent tool does not require a web server.
|
|
26
|
+
|
|
27
|
+
## Board settings
|
|
28
|
+
|
|
29
|
+
- `/board` opens the Board tab. `/notes` opens the Notes tab. Tab or Shift-Tab switches between them.
|
|
30
|
+
- `/board settings` is an alias for the Board tab. It offers enablement and scope, **Open viewer**, consolidation, automatic summaries and the global summary model: Luna or Custom.
|
|
31
|
+
- `/board status` shows the current board and enablement.
|
|
32
|
+
- `/board on` enables the board for this session.
|
|
33
|
+
- `/board off` disables it without deleting history.
|
|
34
|
+
- Append `folder` or `global` to `on` or `off` to save a default, such as `/board on folder`.
|
|
35
|
+
|
|
36
|
+
Sessions start enabled when no setting exists. Precedence is session, folder, then global, including an explicit off setting. Session overrides survive resume, not new root sessions or forks. Folder defaults apply only to that exact launch folder. Bound children inherit their root's choice. Board enablement is independent of Notes activation. Disabled Board defers its engine until enabled; saved membership and history remain intact.
|
|
37
|
+
|
|
38
|
+
Type `/board ` to see available commands. Enablement commands also complete their scope arguments.
|
|
39
|
+
|
|
40
|
+
The agent calls `board` with `{}` for help. Code Mode and Notebook use `await tools.board()`.
|
|
41
|
+
|
|
42
|
+
Choose **Consolidate one-off threads** in `/board settings` to send a prompt to the current session's agent. This starts an agent turn and uses its model quota. Run it from the owning root session while idle. The agent inspects the board's SQLite archive and uses SQL to move related standalone posts into existing open threads, preserving posts and subscriptions. Distinct topics, closed threads and summaries stay unchanged. The menu action does not run SQL itself or close threads.
|
|
43
|
+
|
|
44
|
+
## Thread status
|
|
45
|
+
|
|
46
|
+
Threads start open. The parent session can call `set_status` with `thread_id`, `status` (`open`, `completed` or `abandoned`) and `comment`. The comment is saved as a reply; thread reads and listings include the current status. Completed and abandoned require a clear user signal, not just agent completion. Closed threads reject new replies until the parent reopens them.
|
|
47
|
+
|
|
48
|
+
Status changes work in native, Code and Notebook tools, including GPT prompt mode. Automatic summaries are off by default. Enable them in `/board settings` to start one background summary request when a thread is marked completed or abandoned. Requests use your configured model and quota. The status change does not wait for the model. No agent process or tools are started.
|
|
49
|
+
|
|
50
|
+
Turning automatic summaries off stops active requests in this session and prevents new ones across sessions using the same global configuration. It leaves saved summaries and original posts intact. Turning it on does not summarise previously closed threads.
|
|
51
|
+
|
|
52
|
+
The request contains a dedicated summarizer system prompt and the channel name, status and all original posts in chronological order, with author, timestamp and text. The closing comment is marked. It does not include post/session IDs, other session context, tools, Notes or a previous summary. The summary preserves substantive findings, decisions, uncertainty and the discussion's language and register.
|
|
53
|
+
|
|
54
|
+
Requests have a five-minute deadline and a model-capped 16,384-token output budget. Threads are never silently truncated. Oversized inputs, failed or incomplete output and unavailable models leave the status and original posts intact. Pi displays failures. Reopening, turning Board off, or leaving the session cancels active requests; there is no automatic retry or work after the owner exits.
|
|
55
|
+
|
|
56
|
+
When a thread has a saved summary, thread reads, previews and searches use it instead of the original discussion. Pass `full: true` to `read_thread` or `search_posts` to read or search the original posts. `read_post` always reads the original post. Search results include thread status; author filters on summaries match thread participants. A word omitted from a summary will only match a full-discussion search.
|
|
57
|
+
|
|
58
|
+
Reopening a thread deletes its summary and permits replies again. Summary reads use the returned cursor to continue long text. Keep the search and `full` setting unchanged while paging.
|
|
59
|
+
|
|
60
|
+
The viewer labels threads Open, Completed or Abandoned and offers Full discussion and Search full discussions controls.
|
|
61
|
+
|
|
62
|
+
### Summary settings
|
|
63
|
+
|
|
64
|
+
`/board settings` saves automatic summarisation and the model choice in the global `pi-shepherdr.json` under `board.summary`, without making a model request:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"automatic": false,
|
|
69
|
+
"selection": "luna",
|
|
70
|
+
"luna": {
|
|
71
|
+
"provider": "openai-codex",
|
|
72
|
+
"model": "gpt-6-luna",
|
|
73
|
+
"reasoning": "high"
|
|
74
|
+
},
|
|
75
|
+
"custom": { "provider": "", "model": "", "reasoning": "high" }
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Luna is the fixed preset. Select Custom and edit its provider, model and reasoning in that file. Provider and model IDs must match your Pi configuration. Reasoning accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`; support depends on the model. Invalid Custom settings do not fall back to Luna. Viewing settings without selecting a value does not write the file.
|
|
80
|
+
|
|
81
|
+
## Existing boards and Shepherdr
|
|
82
|
+
|
|
83
|
+
Existing posts, subscriptions and session bindings remain available without an import. Archives stay at `<owning-folder>/.pi/agent-message-board.sqlite`.
|
|
84
|
+
|
|
85
|
+
Each root session has its own board. Resume keeps that board. A new root session or fork gets a separate identity. Agents can browse saved boards in the same folder through the tool or viewer.
|
|
86
|
+
|
|
87
|
+
Load Pi Agent Comms in each participating session. Update Shepherdr to the coordinated Agent Comms version before removing the old packages. Older Shepherdr releases import those packages. Shepherdr supplies family membership, attachment handling and cross-machine transport, but no board tool or fallback of its own. Board settings live under `/board`, not `/herdr`. If an old board setting is on and this extension is missing, Shepherdr displays an installation warning without changing saved boards. PCC is optional.
|
|
88
|
+
|
|
89
|
+
Standalone use does not discover or attach arbitrary agents. Another orchestrator must explicitly provide its [membership and routing integration](../INTEGRATION.md).
|
|
90
|
+
|
|
91
|
+
Existing settings in `pi-shepherdr.json` are preserved. Folder defaults use `<launch-folder>/.pi/pi-shepherdr.json` with `board.enabled`. Global defaults use `<Pi agent directory>/pi-shepherdr.json` with `board.enabledGlobally`. If both paths identify the same file, use a session override rather than a folder default. Invalid configuration disables the board with an explicit error.
|
|
92
|
+
|
|
93
|
+
## Browser access
|
|
94
|
+
|
|
95
|
+
The default viewer listens on `127.0.0.1:47984` and opens the local browser. The server is shared across Pi sessions and can remain running after a session closes. Opening the viewer does not create an archive or empty board.
|
|
96
|
+
|
|
97
|
+
When Pi runs on a server and your browser runs elsewhere, configure `<Pi agent directory>/board-viewer/config.json`:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"host": "0.0.0.0",
|
|
102
|
+
"port": 47984,
|
|
103
|
+
"publicUrl": "http://your-server:47984",
|
|
104
|
+
"openCommand": null
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Use an address reachable from your browser. **Open viewer** prints a link rather than guessing which attached device should open it. No firewall rules are changed automatically. Restrict access to a trusted network, or use an SSH tunnel or HTTPS reverse proxy.
|
|
109
|
+
|
|
110
|
+
The Pi agent directory defaults to `~/.pi/agent` and honors `PI_CODING_AGENT_DIR`. Existing viewer configuration and access keys remain valid. `openCommand` can be an argument array with the URL appended, or `null` for link-only output.
|
|
111
|
+
|
|
112
|
+
The archive must be on the viewer server's machine. From a shared child session, choose **Open viewer** in the owning root's Board tab. Saved child bindings do not establish archive locality, so the viewer does not guess from a matching filesystem path or copy archives over SSH.
|
|
113
|
+
|
|
114
|
+
Changing the listener or public URL requires restarting the viewer server. Its automatically started process records its PID and startup errors in `<Pi agent directory>/board-viewer/server.log`. Stop that process, then choose **Open viewer** again. Restarting invalidates previous viewing links.
|
|
115
|
+
|
|
116
|
+
## Read-only viewer
|
|
117
|
+
|
|
118
|
+
The browser cannot post, subscribe, change settings or select arbitrary filesystem paths. SQLite opens read-only. Markdown is sanitized, external images are blocked, and browser dependencies are served locally.
|
|
119
|
+
|
|
120
|
+
Each viewing link grants access to the selected archive's boards for one folder. Treat it as a secret. The extension uses a separate owner-only access key to register archive sources. Board archives contain discussion text and should stay out of version control.
|
|
121
|
+
|
|
122
|
+
## Development
|
|
123
|
+
|
|
124
|
+
Run `bun run check` and `bun run build` in the package root. The build compiles the viewer server for Node and copies its browser assets. Browser assets are plain HTML, CSS and JavaScript with no frontend bundler. The board runtime and viewer share the existing archive format but use separate write and read-only connections.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# @howaboua/pi-notes-compaction
|
|
2
|
+
|
|
3
|
+
## 0.0.15
|
|
4
|
+
|
|
5
|
+
- Shared local checkpoints remain readable after workers close. Saved family lookup no longer depends on a live parent when the saved session is accessible locally.
|
|
6
|
+
- Saved Notes and History reads are faster in sessions with large messages or tool results.
|
|
7
|
+
- Shared saved-session reads no longer fail when the active session appends new entries.
|
|
8
|
+
|
|
9
|
+
## 0.0.14
|
|
10
|
+
|
|
11
|
+
- Requires Pi 1.5 or newer.
|
|
12
|
+
|
|
13
|
+
Older checkpoints may require a fresh note save before rollover.
|
|
14
|
+
- Notes results in Pi's built-in codemode are now objects, matching Code and Notebook. Remove `JSON.parse` around those results.
|
|
15
|
+
- Agent references now derive from Pi session IDs, with existing shared-note paths retained.
|
|
16
|
+
- Fixed rollover rejecting successful large saves and saves in parallel tool groups. The saved-notes indicator uses the same readiness check.
|
|
17
|
+
- Shared-note paths and read-only warnings now match across text and structured results.
|
|
18
|
+
- History now defaults query-only requests to search and includes the first window's opening request.
|
|
19
|
+
- History now ignores read-only hints on other actions.
|
|
20
|
+
- Model-role guidance now identifies the current role and offers only configured roles for rollover.
|
|
21
|
+
- Notes help now distinguishes virtual note paths from agent references and filesystem paths.
|
|
22
|
+
- Added `address` and `body` aliases for note paths and write text.
|
|
23
|
+
- Expansion hints now use the configured keybinding.
|
|
24
|
+
- Removed custom changelog suppression. Updates use Pi's native notices and `collapseChangelog`.
|
|
25
|
+
|
|
26
|
+
## 0.0.13
|
|
27
|
+
|
|
28
|
+
- Model roles are now agent-operated. Configure them in `model-roles.json`. `/roles` is read-only, and the old `enabled` flag and accept/dismiss controls no longer apply.
|
|
29
|
+
- Added `new_context({role})` to continue the next context window on a role's configured model and reasoning after saving a checkpoint.
|
|
30
|
+
- Agents receive role names, descriptions and guidance to switch only for sustained scope changes, with subagents considered for bounded specialist work.
|
|
31
|
+
|
|
32
|
+
## 0.0.12
|
|
33
|
+
|
|
34
|
+
- Added `/roles` for model preferences across providers and optional model-switch recommendations that preserve the current conversation.
|
|
35
|
+
- Simplified Notes and History action names and Notes path and limit arguments. Existing calls remain supported.
|
|
36
|
+
- Fixed fresh child agents being unable to join shared Notes when another extension had saved startup metadata.
|
|
37
|
+
- Notes guidance now requires task checkpoints at meaningful milestones, completion and task switches, even before context runs low.
|
|
38
|
+
|
|
39
|
+
## 0.0.11
|
|
40
|
+
|
|
41
|
+
- - Fixed native SQLite addon crashes when saving notes or searching ranked history in standalone Bun-based Pi builds. Existing notes and history indexes remain compatible with Node-based Pi.
|
|
42
|
+
- Fixed the session auto-pruning submenu losing its frame and disappearing during pruning. Preview, confirmation and progress now stay inside the menu.
|
|
43
|
+
|
|
44
|
+
## 0.0.10
|
|
45
|
+
|
|
46
|
+
- ### Features
|
|
47
|
+
- Added per-session auto-pruning in `/notes`, with 5, 10 or 25 full-history windows and optional one-week or one-month conversation retention. Off by default, with a Run now preview. Current context and saved notes remain protected. Restart Pi for memory savings; `/reload` is not sufficient.
|
|
48
|
+
- Added opt-in BM25-ranked history search in `/notes` for earlier user messages and assistant replies. Current context, tools and reasoning are excluded. Explicit tool-history, live-window and cross-agent searches retain literal matching.
|
|
49
|
+
- Added subagent sharing and note-save marker settings to `/notes`, with migration from global and trusted-folder PCC preferences.
|
|
50
|
+
- Added automatic read-only remote notes retrieval and recovery of saved PCC Tree history.
|
|
51
|
+
- Added `pi-notes-compaction/context-sharing` with `connectNotesContextSharing` for orchestrators to share notes and history without PCC.
|
|
52
|
+
|
|
53
|
+
### History and recovery
|
|
54
|
+
- Reduced memory use during Notes rollover in long sessions. Earlier windows remain accessible through History and Tree.
|
|
55
|
+
|
|
56
|
+
**Expected compaction card:** This fix requires a native history cut, which displays Pi's compaction card. Pi currently provides no supported way to hide this card. It can be ignored; Notes is working as intended.
|
|
57
|
+
|
|
58
|
+
- Tool descriptions now explain that Notes hands off task state between context windows. GPT prompt mode uses note-style guidance, history-search help and rollover reminders.
|
|
59
|
+
- Notes guidance now directs each agent to keep checkpoints and reports in its own notes and share their paths.
|
|
60
|
+
- Notes now accepts `read` as an alias for `read_file`.
|
|
61
|
+
- With PCC, plaintext Notes and history calls inside `exec` now return objects instead of JSON strings.
|
|
62
|
+
- With PCC, history now reads Pi session files instead of encrypted backend history.
|
|
63
|
+
- Fixed returning to a saved-notes point in the session tree unnecessarily requesting another checkpoint instead of opening a new context window.
|
|
64
|
+
- Prune missing sessions now also removes history index entries for missing session files.
|
|
65
|
+
- Notes results now omit storage and routing bookkeeping while retaining read ranges, truncation and warnings about incomplete or outdated results.
|
|
66
|
+
|
|
67
|
+
## 0.0.9
|
|
68
|
+
|
|
69
|
+
- - Fixed history lookup errors to identify the missing ID and explain how to retry. History arguments now clarify that read_item requires both IDs.
|
|
70
|
+
- GPT-mode checkpoint guidance uses denser prose.
|
|
71
|
+
- New-window guidance tells agents to read task-relevant skills again.
|
|
72
|
+
- Notes write receipts now contain only the saved path.
|
|
73
|
+
- Idle rollover offers Off, 25m, 55m, 2h, 6h and 12h. Hour presets roll over five minutes early; saved 5- and 15-minute settings remain valid.
|
|
74
|
+
|
|
75
|
+
## 0.0.8
|
|
76
|
+
|
|
77
|
+
- **Continuity and integrations**
|
|
78
|
+
- Fixed Notes guidance missing from PCC's first post-compaction cache-warming request.
|
|
79
|
+
- With PCC active, Notes guidance uses developer-role delivery. Automatic rollover resumes from the window handoff itself, without a separate continuation message.
|
|
80
|
+
- Initial window identity now follows the prepared system prompt, preserving the shared prefix for child-agent caching.
|
|
81
|
+
- External integrations can adopt a new fork into a notes family before its first task without rewriting inherited history.
|
|
82
|
+
|
|
83
|
+
**Guidance and discovery**
|
|
84
|
+
- Added compact checkpoint guidance for PCC GPT prompt mode.
|
|
85
|
+
- Simplified Notes and History discovery, with write, path and history-ID guidance in their help.
|
|
86
|
+
- Tightened notes guidance to favour concise milestone checkpoints over progress logs and repeated reads.
|
|
87
|
+
|
|
88
|
+
## 0.0.7
|
|
89
|
+
|
|
90
|
+
- Shared local agent history now remains readable after its owner closes or Shepherdr is removed.
|
|
91
|
+
|
|
92
|
+
## 0.0.6
|
|
93
|
+
|
|
94
|
+
- Requires Pi 1.2.0 or newer.
|
|
95
|
+
- Added per-model activation through `/notes` and an editable whitelist.
|
|
96
|
+
- Added **New window requests: off | pi-limits | unrestricted**. `new_context` requires a successful note write immediately beforehand.
|
|
97
|
+
- Shared local notes now remain readable after their owner closes or Shepherdr is removed.
|
|
98
|
+
- Fixed window identity and recovery guidance disappearing after compaction.
|
|
99
|
+
- Continuations now apply Pi's full prompt and tool preparation.
|
|
100
|
+
|
|
101
|
+
## 0.0.5
|
|
102
|
+
|
|
103
|
+
- We've been informed that Astra and Sol currently retain their prompt caches for around an hour. If you use notes-managed idle rollover, consider increasing it from 25 to 55 minutes. Cache retention can vary. YMMV. We'll keep monitoring. Please share your cache-retention and long-context quota observations in [the feedback thread](https://github.com/IgorWarzocha/howaboua-pi-stuff/issues/508).
|
|
104
|
+
|
|
105
|
+
Added configurable task-boundary reminders and a clearer settings layout.
|
|
106
|
+
- Added optional reminders at preset or custom token counts when context capacity exceeds 272k, showing the remaining percentage.
|
|
107
|
+
- Status text and keyboard hints now wrap to fit narrow terminals.
|
|
108
|
+
- Notes help now lists required arguments. Writes accept `content` when `text` is omitted.
|
|
109
|
+
- Fixed fresh worker startup with Notes enabled.
|
|
110
|
+
|
|
111
|
+
## 0.0.4
|
|
112
|
+
|
|
113
|
+
- Fixed note queries and manual context rollover with Codex Conversion.
|
|
114
|
+
- Restored negative line ranges, default limits, result ordering, metadata and complete read and search content. Help now shows concrete call syntax, and invalid arguments are reported before execution.
|
|
115
|
+
- `/compact` now honours the Normal compaction setting. With it off, Notes Compaction reuses fresh saved notes or requests a checkpoint, then opens a new context window without starting a continuation turn.
|
|
116
|
+
|
|
117
|
+
## 0.0.3
|
|
118
|
+
|
|
119
|
+
- Fixed shared agent startup after package updates when the startup changelog is present.
|
|
120
|
+
|
|
121
|
+
## 0.0.2
|
|
122
|
+
|
|
123
|
+
- Added a `/notes` settings panel for normal compaction, idle rollover, continuity status and confirmed pruning, replacing the subcommands and JSON status output.
|
|
124
|
+
|
|
125
|
+
## 0.0.1
|
|
126
|
+
|
|
127
|
+
- Added Notes Compaction: local checkpoint notes, searchable session history and notes-guided context windows for any Pi model, with optional Codex Conversion integration and cached remote lookup.
|
package/docs/NOTES.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Notes
|
|
2
|
+
|
|
3
|
+
Keep working across fresh context windows with local checkpoint notes, searchable session history and optional remote notes lookup. Works with any Pi model.
|
|
4
|
+
|
|
5
|
+
Part of [Pi Agent Comms](../README.md).
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Requires Pi 1.5.0 or newer and Node.js 22.18 or newer. See the [installation status and replacement steps](../README.md#install) before replacing the old packages.
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
pi install npm:@howaboua/pi-agent-comms
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Reload Pi, then ask the agent to save a checkpoint and start a new context window. It can read those notes and search earlier session history to continue.
|
|
16
|
+
|
|
17
|
+
Pi Codex Conversion is optional. Compatible releases add Code Mode, Notebook and encrypted remote delivery without taking over Notes tools or policy. Run `/notes` to check activation and available capabilities. Extension authors can read the [integration contract](../PCC-INTEGRATION.md).
|
|
18
|
+
|
|
19
|
+
## Notes and windows
|
|
20
|
+
|
|
21
|
+
The agent keeps the familiar `notes`, `history`, `new_context` and `get_context_remaining` tools. Notes use virtual paths. Relative paths belong to the current agent. History searches the selected Pi session branch, including earlier windows. It does not create a second transcript archive.
|
|
22
|
+
|
|
23
|
+
History uses case-sensitive substring search by default. Turn on **Ranked history search** in `/notes` to search earlier context in the current session with BM25. Ranked search matches all query words, ignoring case, accents and word order. Set `recent_first: true` to put the newest matches first. Arguments and result IDs are unchanged. Notes search remains a case-sensitive substring search.
|
|
24
|
+
|
|
25
|
+
Ranked search is off by default. It indexes user messages and visible assistant replies left behind by rollover or compaction. Ongoing context, tool calls, tool outputs and internal reasoning stay unindexed. Indexing runs off the UI thread and processes newly eligible entries without repeatedly hashing unchanged history. The first search may wait for indexing to finish. It does not scan other saved sessions. The SQLite index stores terms rather than another transcript. Branch and window filters still control which entries can be returned. JSONL remains the source of truth.
|
|
26
|
+
|
|
27
|
+
Explicit searches of tool history, a window containing live context or another agent's history use literal substring matching. Search results identify the matching mode. Listing and reading history still includes the full transcript, including ongoing context and tool activity.
|
|
28
|
+
|
|
29
|
+
Previously shared local notes and history remain readable from accessible saved sessions after the other agent closes or Shepherdr is removed. Notes follows saved family relationships and attachment aliases without requiring PCC or a live parent. Reads use the other session's selected branch and preserve its history IDs. When only a retained attachment snapshot is available, notes identify it as detached or potentially stale. Snapshots do not contain history. Cross-agent writes still require live routing.
|
|
30
|
+
|
|
31
|
+
With Shepherdr, live sharing and cross-machine saved-session reads require its coordinated Agent Comms update in all participating sessions. Older Shepherdr releases import the former Notes package and must be updated before removing it. Saved reads require access to the saved Pi JSONL session, locally or through the host's saved-session transport. Saved reads do not replace hybrid lookup or its encrypted cache with local-only results. History uses Pi JSONL, never remote notes or cached responses.
|
|
32
|
+
|
|
33
|
+
In Code Mode and Notebook, plaintext notes and history return ordinary JavaScript values. Encrypted notes return delivery receipts instead of exposing their contents to JavaScript.
|
|
34
|
+
|
|
35
|
+
By default, `new_context` starts a fresh window without generating a summary. The agent receives recent note paths, and Pi's saved history remains available for lookup.
|
|
36
|
+
|
|
37
|
+
The tool requires a successful checkpoint write immediately before the request. Direct `notes` writes and writes completed through `exec` or `wait` count. A missing, pending or failed write keeps the current run active and asks the agent to save a note first.
|
|
38
|
+
|
|
39
|
+
Reminders arrive at 85% and 90% context use. With normal compaction off, `/compact` opens a fresh window immediately if the latest completed turn saved fresh notes. Otherwise it requests a checkpoint first. The new window waits for your next prompt; it does not start a continuation turn. Abort, errors and failed writes retain the old context. Overflow recovery still uses Pi's normal compaction.
|
|
40
|
+
|
|
41
|
+
Pi rejects `/compact` when there is too little history to prepare compaction, before extensions run. `new_context` follows the separate **New window requests** setting.
|
|
42
|
+
|
|
43
|
+
Idle rollover is off by default. Choose 25m, 55m, 2h, 6h or 12h in `/notes`. Hour presets use a five-minute buffer, stored as 115, 355 or 715 minutes. Saved 5- and 15-minute settings remain valid. After the interval, the next input waits for rollover only if the latest completed turn saved fresh notes. Otherwise it proceeds in the current window without requesting a checkpoint. These intervals are user preferences, not provider cache-expiry guarantees. Held input retains its original text, attachments and SDK options. If normal compaction has nothing to summarise, input proceeds in the current window. A failed rollover keeps input pending. Submit another prompt to retry, or reload to cancel it.
|
|
44
|
+
|
|
45
|
+
## Management
|
|
46
|
+
|
|
47
|
+
### Model roles
|
|
48
|
+
|
|
49
|
+
`/roles` opens the read-only model roles subview of Notes. You can also choose
|
|
50
|
+
**Model roles** in the Notes tab. It shows the configuration path, configured
|
|
51
|
+
values and a JSON example. `/notes` opens Notes and `/board` opens Board.
|
|
52
|
+
Press Tab or Shift-Tab to switch between those two tabs. Edit
|
|
53
|
+
`<Pi agent directory>/notes-compaction/model-roles.json` to define roles:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"roles": [
|
|
58
|
+
{
|
|
59
|
+
"id": "planning",
|
|
60
|
+
"description": "Sustained planning and design work",
|
|
61
|
+
"provider": "your-provider",
|
|
62
|
+
"model": "your-model-id",
|
|
63
|
+
"reasoning": "high"
|
|
64
|
+
}
|
|
65
|
+
]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Create the parent directory and file if missing. Use an available Pi provider
|
|
70
|
+
and exact model ID. Role IDs start with a lowercase letter and contain only
|
|
71
|
+
lowercase letters, numbers and hyphens. Reasoning accepts `off`, `minimal`,
|
|
72
|
+
`low`, `medium`, `high`, `xhigh` or `max`. Roles have no shipped model assignments.
|
|
73
|
+
Changes apply on the next turn or when reopening the subview. All defined roles
|
|
74
|
+
are available to the agent. The old `enabled` property is ignored.
|
|
75
|
+
|
|
76
|
+
Only role IDs and descriptions are shared with the agent. After saving its
|
|
77
|
+
checkpoint, it can call `new_context` with an optional `role` when a sustained
|
|
78
|
+
scope shift warrants a different role. The next context window uses that role's
|
|
79
|
+
model and reasoning in the same session. Without a role, `new_context` keeps the
|
|
80
|
+
current model. There is no manual role switching or recommendation acceptance
|
|
81
|
+
workflow.
|
|
82
|
+
|
|
83
|
+
Notes must be active for both models. Pi handles authentication and clamps
|
|
84
|
+
unsupported reasoning levels. Provider capabilities and context limits still
|
|
85
|
+
apply, and switching does not guarantee cache reuse. Context retirement and
|
|
86
|
+
recovery keep their existing Notes settings.
|
|
87
|
+
|
|
88
|
+
### Notes settings
|
|
89
|
+
|
|
90
|
+
`/notes` opens the settings panel in interactive Pi. It shows continuity status, storage counts and remote capabilities. Changes save immediately.
|
|
91
|
+
|
|
92
|
+
- **Active** selects **Off**, **All models** (the default) or **Whitelist**. Whitelist enables Notes only for exact model IDs in the global settings file, regardless of provider. Off disables Notes independently of Board. Switching models applies the choice immediately; other models keep their installed compaction behaviour. Inactive Notes defers initialisation, but retained context projections can still load to preserve previously retired history.
|
|
93
|
+
- **Normal compaction** uses the installed Pi or PCC compaction flow for `/compact` and `new_context`. Off keeps notes-only rollover, the default.
|
|
94
|
+
- **New window requests** controls the agent's `new_context` tool independently of the compaction method. **off** disables the tool. **pi-limits** uses Pi's eligibility check and continues in the current window when there is too little history. **unrestricted**, the default, accepts requests at any size. With normal compaction on and nothing to summarise, unrestricted requests open a new window identity without discarding the existing context. Manual `/compact` and idle rollover retain their separate policies.
|
|
95
|
+
- **Idle rollover** selects the interval or disables it.
|
|
96
|
+
- **Prune missing sessions** removes notes, cached responses and history index entries for missing session files after confirmation. Unknown paths, permission errors and the active session are retained.
|
|
97
|
+
|
|
98
|
+
Notes are stored as plaintext in `<Pi agent directory>/notes-compaction/notes.sqlite`, honoring `PI_CODING_AGENT_DIR`. Saved session snapshots preserve notes across forks and branch navigation, including after database pruning. Existing plaintext PCC notes remain readable without an import. On first use, saved PCC notes continuity settings migrate to Notes when no Notes settings file exists. Existing Notes settings take precedence.
|
|
99
|
+
|
|
100
|
+
The whitelist is preseeded in `<Pi agent directory>/notes-compaction/settings.json` (normally `~/.pi/agent/notes-compaction/settings.json`):
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"active": "whitelist",
|
|
105
|
+
"modelWhitelist": ["gpt-6-astra", "gpt-6-sol", "gpt-6-luna", "gpt-6.1-sol"],
|
|
106
|
+
"normalCompaction": false,
|
|
107
|
+
"rankedHistorySearch": false,
|
|
108
|
+
"newWindowRequests": "unrestricted",
|
|
109
|
+
"idleMinutes": 0,
|
|
110
|
+
"taskBoundaryReminder": 0
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Add or remove model IDs and reload Pi. Copy the model's exact ID, without Pi's provider selector prefix. If the ID itself contains slashes, keep them. Entries are literal matches, not patterns. A new model is inactive in Whitelist mode until you add its ID.
|
|
115
|
+
|
|
116
|
+
## Optional remote lookup
|
|
117
|
+
|
|
118
|
+
With a compatible PCC provider, note reads and searches automatically combine local notes with remote results. Remote response bytes are cached verbatim in SQLite. Cached lookups can be reused offline, with their original coverage and an explicit exact-query limit. Encrypted listings cannot be searched or expanded locally into queries that were never cached.
|
|
119
|
+
|
|
120
|
+
New writes always stay local and work with any model. `write_file` replaces the local path and takes precedence over a remote read of that path. `append_to_file` adds a local overlay when no local replacement exists. Remote base content and the overlay remain separate. List and search results label local replacements as authoritative because opaque remote results can contain older versions.
|
|
121
|
+
|
|
122
|
+
Encrypted remote content needs a compatible provider bridge and the user's compatible OpenAI setup. The cache does not decrypt content or make it portable across incompatible setups. Without compatible delivery, local notes remain usable and the result reports that cached remote content is unavailable.
|
package/index.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { createBoardFeature } from "./src/board/feature.js";
|
|
3
|
+
import {
|
|
4
|
+
type CommsFeature,
|
|
5
|
+
registerCommunicationGuidance,
|
|
6
|
+
} from "./src/guidance.js";
|
|
7
|
+
import { createNotesFeature } from "./src/notes/feature.js";
|
|
8
|
+
import type { OpenSettings } from "./src/settings-navigation.js";
|
|
9
|
+
|
|
10
|
+
export default async function agentComms(pi: ExtensionAPI): Promise<void> {
|
|
11
|
+
let board: CommsFeature;
|
|
12
|
+
const open: OpenSettings = async (ctx, initial) => {
|
|
13
|
+
let tab: typeof initial | undefined = initial;
|
|
14
|
+
while (tab) {
|
|
15
|
+
tab = await (tab === "notes" ? notes : board).openSettings(ctx);
|
|
16
|
+
}
|
|
17
|
+
};
|
|
18
|
+
const notes = createNotesFeature(pi, open);
|
|
19
|
+
board = await createBoardFeature(pi, open);
|
|
20
|
+
registerCommunicationGuidance(pi, notes, board);
|
|
21
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,76 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
2
|
+
"name": "@howaboua/pi-agent-comms",
|
|
3
|
+
"version": "0.0.1-dev.13.1.gef1ce49691d6",
|
|
4
|
+
"description": "Session notes, context continuity and agent message boards for Pi",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/IgorWarzocha/howaboua-pi-stuff.git",
|
|
10
|
+
"directory": "packages/pi-agent-comms"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"index.ts",
|
|
14
|
+
"src",
|
|
15
|
+
"dist",
|
|
16
|
+
"docs",
|
|
17
|
+
"README.md",
|
|
18
|
+
"INTEGRATION.md",
|
|
19
|
+
"PCC-INTEGRATION.md",
|
|
20
|
+
"LICENSE",
|
|
21
|
+
"tsconfig.json",
|
|
22
|
+
"CHANGELOG.md"
|
|
23
|
+
],
|
|
24
|
+
"main": "index.ts",
|
|
25
|
+
"exports": {
|
|
26
|
+
".": "./index.ts",
|
|
27
|
+
"./context-sharing": "./src/notes/context-sharing.ts",
|
|
28
|
+
"./saved-session": "./src/notes/saved-session.mjs",
|
|
29
|
+
"./saved-session-index": "./src/notes/saved-session-index.mjs",
|
|
30
|
+
"./runtime": "./src/board/runtime/index.ts",
|
|
31
|
+
"./integration": "./src/board/integration.ts"
|
|
32
|
+
},
|
|
33
|
+
"pi": {
|
|
34
|
+
"extensions": [
|
|
35
|
+
"./index.ts"
|
|
36
|
+
]
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=22.18.0"
|
|
40
|
+
},
|
|
41
|
+
"scripts": {
|
|
42
|
+
"build": "node scripts/build-viewer.mjs",
|
|
43
|
+
"check": "bun run lint && bun run typecheck",
|
|
44
|
+
"lint": "biome check .",
|
|
45
|
+
"format": "biome check --write .",
|
|
46
|
+
"typecheck": "tsgo --noEmit",
|
|
47
|
+
"prepack": "bun run check && bun run build",
|
|
48
|
+
"pack:dry": "npm pack --dry-run"
|
|
49
|
+
},
|
|
50
|
+
"dependencies": {
|
|
51
|
+
"better-sqlite3": "13.0.3",
|
|
52
|
+
"dompurify": "3.4.17",
|
|
53
|
+
"marked": "18.2.0",
|
|
54
|
+
"unicode-case-folding": "1.1.2"
|
|
55
|
+
},
|
|
56
|
+
"devDependencies": {
|
|
57
|
+
"@howaboua/pi-codex-conversion": "4.0.9",
|
|
58
|
+
"@types/better-sqlite3": "9.6.0"
|
|
59
|
+
},
|
|
60
|
+
"peerDependencies": {
|
|
61
|
+
"@earendil-works/pi-coding-agent": ">=1.5.0",
|
|
62
|
+
"@earendil-works/pi-agent-core": ">=1.0.4",
|
|
63
|
+
"@earendil-works/pi-ai": ">=1.1.0",
|
|
64
|
+
"@earendil-works/pi-tui": ">=1.1.0",
|
|
65
|
+
"@howaboua/pi-codex-conversion": ">=4.0.9",
|
|
66
|
+
"typebox": "*"
|
|
67
|
+
},
|
|
68
|
+
"peerDependenciesMeta": {
|
|
69
|
+
"@howaboua/pi-codex-conversion": {
|
|
70
|
+
"optional": true
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
"publishConfig": {
|
|
74
|
+
"access": "public"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
- Only an explicitly loaded Agent Comms or standalone Board extension activates Board. Discovery never imports the engine; disabled sessions keep binding/settings routes and reconcile inherited enablement before preparation. Preserve native replay of saved briefings without starting the engine. Settings and viewer reads must not activate it.
|
|
2
|
+
- Schema-v1 archives and `shepherdr-board-*` session records are compatibility contracts. Preserve their paths and identities across takeover; do not create a replacement archive.
|
|
3
|
+
- Post sequence owns chronology and continuation. Minute timestamps may tie or coexist with legacy precision; never order posts or advance cursors by timestamp text.
|
|
4
|
+
- Native session IDs own public agent references; saved legacy names are archive aliases, never membership grants. Keep parent-session associations when adopting members: flat references cannot authorize descendants or route notices by prefix.
|
|
5
|
+
- Status and its comment share the post transaction and invocation ID. New replies require open status, checked in that transaction after invocation replay. Replaying a status call must not reapply it over a later status; read-only legacy archives default to open without creating tables.
|
|
6
|
+
- Summaries are derived snapshots, not posts. Status changes discard them in the same transaction; a late save must match the closed status comment and covered latest post. Tool and viewer searches replace summarized posts by default; only `full` searches originals. Legacy reads never create summary tables.
|
|
7
|
+
- Start summarization only after a fresh committed status notice, never an invocation replay. Its system prompt owns instructions; source payload owns channel/status and chronological author/timestamp/text with the closing comment marked, not IDs or session context. Keep requests tool-free and cancel them with the owning session or board.
|
|
8
|
+
- Summaries default off. Validate the preference inside the caught background job so invalid summary settings cannot turn a committed status change into a tool failure.
|
|
9
|
+
- runtime/owner.ts validates owner requests and commits archives before summaries or best-effort notices. coordinator.ts owns settings, refresh and cancellation; routing.ts owns adapter/envelope routing, with binding changes awaiting coordinator refresh. turns.ts alone owns session-scoped turn capabilities. Do not copy their mutable state into the owner executor.
|
|
10
|
+
- Fleet discovery, spawning and SSH stay in host adapters. The viewer only receives a resolved source and opens it read-only; viewing must never initialize a board.
|
|
11
|
+
- Keep viewer startup lazy and packaged assets local. Do not modify a running user's viewer or listener configuration during validation.
|
|
12
|
+
- Viewer browser modules must remain in the server's explicit asset allowlist; the build copies web/ recursively. session.js owns shared selection/queue state; render, navigation and updates must not create parallel snapshots or bypass the queue.
|