@howaboua/pi-notes-compaction 0.0.8 → 0.0.10
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/CHANGELOG.md +31 -5
- package/PCC-INTEGRATION.md +7 -98
- package/README.md +22 -14
- package/package.json +7 -3
- package/src/activation.ts +152 -0
- package/src/agent-identity.ts +119 -0
- package/src/attachment-snapshot.ts +103 -0
- package/src/binding-startup.ts +30 -0
- package/src/bridge.ts +1 -43
- package/src/compaction-projection.ts +88 -0
- package/src/context-owner.ts +103 -0
- package/src/context-sharing.ts +144 -0
- package/src/extension-hooks.ts +198 -0
- package/src/extension-sharing.ts +118 -0
- package/src/fresh-checkpoint.ts +117 -0
- package/src/fresh-notes.ts +141 -26
- package/src/history-search-protocol.ts +39 -0
- package/src/history-search-pruning.mjs +120 -0
- package/src/history-search-worker.mjs +256 -0
- package/src/history-search.ts +269 -0
- package/src/history.ts +219 -48
- package/src/idle-admission.ts +201 -0
- package/src/index.ts +71 -401
- package/src/integrations.ts +159 -0
- package/src/lifecycle.ts +63 -448
- package/src/note-save-marker.ts +112 -0
- package/src/notes-lookup.ts +112 -0
- package/src/notes.ts +25 -30
- package/src/query-executor.ts +190 -0
- package/src/remote.ts +357 -0
- package/src/rollover.ts +212 -0
- package/src/saved-session.ts +44 -7
- package/src/session-pruning-content.ts +237 -0
- package/src/session-pruning-plan.ts +243 -0
- package/src/session-pruning-policy.ts +20 -0
- package/src/session-pruning-screen.ts +130 -0
- package/src/session-pruning-source.ts +44 -0
- package/src/session-pruning-transaction.ts +141 -0
- package/src/session-pruning.ts +142 -0
- package/src/settings-command.ts +77 -0
- package/src/settings-screen.ts +89 -20
- package/src/settings.ts +152 -15
- package/src/shared-notes.ts +37 -14
- package/src/sharing-service.ts +348 -0
- package/src/store.ts +31 -0
- package/src/task-boundary.ts +6 -1
- package/src/tool-contracts.ts +279 -0
- package/src/tools.ts +19 -556
- package/src/tree-archive.ts +149 -0
- package/src/tree-checkpoint.ts +170 -0
- package/src/tree-handoff-read.ts +192 -0
- package/src/window-checkpoint.ts +105 -0
- package/src/windows.ts +28 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,16 +1,45 @@
|
|
|
1
1
|
# @howaboua/pi-notes-compaction
|
|
2
2
|
|
|
3
|
+
## 0.0.10
|
|
4
|
+
|
|
5
|
+
- ### Features
|
|
6
|
+
- 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.
|
|
7
|
+
- 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.
|
|
8
|
+
- Added subagent sharing and note-save marker settings to `/notes`, with migration from global and trusted-folder PCC preferences.
|
|
9
|
+
- Added automatic read-only remote notes retrieval and recovery of saved PCC Tree history.
|
|
10
|
+
- Added `pi-notes-compaction/context-sharing` with `connectNotesContextSharing` for orchestrators to share notes and history without PCC.
|
|
11
|
+
|
|
12
|
+
### History and recovery
|
|
13
|
+
- Reduced memory use during Notes rollover in long sessions. Earlier windows remain accessible through History and Tree.
|
|
14
|
+
|
|
15
|
+
**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.
|
|
16
|
+
|
|
17
|
+
- 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.
|
|
18
|
+
- Notes guidance now directs each agent to keep checkpoints and reports in its own notes and share their paths.
|
|
19
|
+
- Notes now accepts `read` as an alias for `read_file`.
|
|
20
|
+
- With PCC, plaintext Notes and history calls inside `exec` now return objects instead of JSON strings.
|
|
21
|
+
- With PCC, history now reads Pi session files instead of encrypted backend history.
|
|
22
|
+
- Fixed returning to a saved-notes point in the session tree unnecessarily requesting another checkpoint instead of opening a new context window.
|
|
23
|
+
- Prune missing sessions now also removes history index entries for missing session files.
|
|
24
|
+
- Notes results now omit storage and routing bookkeeping while retaining read ranges, truncation and warnings about incomplete or outdated results.
|
|
25
|
+
|
|
26
|
+
## 0.0.9
|
|
27
|
+
|
|
28
|
+
- - Fixed history lookup errors to identify the missing ID and explain how to retry. History arguments now clarify that read_item requires both IDs.
|
|
29
|
+
- GPT-mode checkpoint guidance uses denser prose.
|
|
30
|
+
- New-window guidance tells agents to read task-relevant skills again.
|
|
31
|
+
- Notes write receipts now contain only the saved path.
|
|
32
|
+
- 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.
|
|
33
|
+
|
|
3
34
|
## 0.0.8
|
|
4
35
|
|
|
5
36
|
- **Continuity and integrations**
|
|
6
|
-
|
|
7
37
|
- Fixed Notes guidance missing from PCC's first post-compaction cache-warming request.
|
|
8
38
|
- With PCC active, Notes guidance uses developer-role delivery. Automatic rollover resumes from the window handoff itself, without a separate continuation message.
|
|
9
39
|
- Initial window identity now follows the prepared system prompt, preserving the shared prefix for child-agent caching.
|
|
10
40
|
- External integrations can adopt a new fork into a notes family before its first task without rewriting inherited history.
|
|
11
41
|
|
|
12
42
|
**Guidance and discovery**
|
|
13
|
-
|
|
14
43
|
- Added compact checkpoint guidance for PCC GPT prompt mode.
|
|
15
44
|
- Simplified Notes and History discovery, with write, path and history-ID guidance in their help.
|
|
16
45
|
- Tightened notes guidance to favour concise milestone checkpoints over progress logs and repeated reads.
|
|
@@ -22,7 +51,6 @@
|
|
|
22
51
|
## 0.0.6
|
|
23
52
|
|
|
24
53
|
- Requires Pi 1.2.0 or newer.
|
|
25
|
-
|
|
26
54
|
- Added per-model activation through `/notes` and an editable whitelist.
|
|
27
55
|
- Added **New window requests: off | pi-limits | unrestricted**. `new_context` requires a successful note write immediately beforehand.
|
|
28
56
|
- Shared local notes now remain readable after their owner closes or Shepherdr is removed.
|
|
@@ -34,7 +62,6 @@
|
|
|
34
62
|
- 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).
|
|
35
63
|
|
|
36
64
|
Added configurable task-boundary reminders and a clearer settings layout.
|
|
37
|
-
|
|
38
65
|
- Added optional reminders at preset or custom token counts when context capacity exceeds 272k, showing the remaining percentage.
|
|
39
66
|
- Status text and keyboard hints now wrap to fit narrow terminals.
|
|
40
67
|
- Notes help now lists required arguments. Writes accept `content` when `text` is omitted.
|
|
@@ -43,7 +70,6 @@
|
|
|
43
70
|
## 0.0.4
|
|
44
71
|
|
|
45
72
|
- Fixed note queries and manual context rollover with Codex Conversion.
|
|
46
|
-
|
|
47
73
|
- 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.
|
|
48
74
|
- `/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.
|
|
49
75
|
|
package/PCC-INTEGRATION.md
CHANGED
|
@@ -1,104 +1,13 @@
|
|
|
1
|
-
# PCC
|
|
1
|
+
# Optional PCC integration
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Notes owns its four tools, local storage, family sharing, checkpoint policy and context windows. PCC is optional. Without Notes, PCC provides ordinary Pi and native provider compaction without notes tools.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Notes uses PCC's public `code-mode`, `prompt-mode` and `developer-messages` exports. Code and Notebook defer notes/history discovery. `new_context` remains a sequential model-only tool, never a nested call. Freshness uses persisted Notes receipts and completed tool outcomes, including generic nested-call evidence through exec and wait.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Returned kickoff messages are annotated for developer-role delivery, not sent during preparation. Other models retain ordinary Pi custom messages. Context projection remains active for saved retirement boundaries even when Notes is disabled for the selected model.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Notes owns automatic read-only hybrid note retrieval and its response cache. History reads Pi JSONL sessions, without backend lookup or protected delivery. PCC supplies provider authentication and generic protected-output delivery for encrypted notes. `canDeliverProtectedOutput(pi, ctx)` checks the active delivery capability, not merely whether the PCC package is installed. JavaScript receives ordinary values for plaintext results and receipts for encrypted notes while compatible provider requests receive the original encrypted blocks. Neither package decrypts them locally. Cached data retains account and backend provenance.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
// PCC asks whether an external continuity owner is installed.
|
|
13
|
-
pi.events.emit("pi-notes-compaction:owner:v1", {
|
|
14
|
-
protocol: 1,
|
|
15
|
-
ctx, // current model, including before preparation and after model selection
|
|
16
|
-
projection(owner) { /* retain historical message and branch projection */ },
|
|
17
|
-
reply(owner) { /* retain the NotesOwner for this runtime */ }
|
|
18
|
-
})
|
|
11
|
+
The optional `pi-notes-compaction:owner:v1` discovery channel exposes Notes identity, sharing and projection to consumers such as Suggestions. It does not transfer tool registration or session authority. PCC may check this channel for Notes availability during upgrade admission. Normal turn context delivery uses ordinary Pi context hooks. Notes registers read-only branch projection through PCC's public `compaction` export for isolated consumers such as voice summarisation.
|
|
19
12
|
|
|
20
|
-
|
|
21
|
-
pi.events.on("pi-notes-compaction:bridge:v1", request => {
|
|
22
|
-
if (request.protocol === 1) request.reply(bridge)
|
|
23
|
-
})
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
Every extension finishes loading before `session_start`. Both sides must discover again at that boundary. PCC must check for the external owner before its first session initialization and before every activation-plan or tool rewrite. This works in either load order. No prefix edit, timer or module-global import is discovery.
|
|
27
|
-
|
|
28
|
-
Ownership is model-dependent. Notes replies only when enabled for the request's current model. If a context-bearing discovery gets no reply after takeover, PCC releases the external owner, resets its pending continuity state and restores its own four tool definitions through its original registration API. Reclaim on a matching model uses the same handoff below. Context-free loading discovery must not release an existing owner. The optional `projection` callback receives only message and branch projection regardless of activation, including when resuming on an excluded model. Historical Notes retirement boundaries remain effective when inactive, but Notes guidance and reminders are removed from model context.
|
|
29
|
-
|
|
30
|
-
`bridge.claim(owner)` returns either `{ claimed: false, reason }` or `{ claimed: true, registerTools }`. A success synchronously transfers continuity policy ownership. The callback `registerTools(tools, ctx)` registers the supplied four definitions **through PCC's own `pi.registerTool` API**, replacing PCC's existing definitions in place. The new extension does not register duplicate names when takeover succeeds. Pi cannot unregister tools. Hiding a legacy definition in another extension is not sufficient because registry precedence depends on extension order.
|
|
31
|
-
|
|
32
|
-
PCC may defer its legacy registrations until discovery, but it must still use the same PCC-owned registration callback on takeover. With no external owner, PCC retains all existing behavior. A failed claim must leave its legacy owner intact. Do not acknowledge a partial takeover.
|
|
33
|
-
|
|
34
|
-
## PCC owners that must yield
|
|
35
|
-
|
|
36
|
-
Add an explicit external-owner branch to `adapter/activation/runtime-plan.ts` and every continuity consumer. The external owner takes notes, history routing, context identities, reminders, manual checkpoint policy, idle input admission and window rollover. Disable PCC's corresponding Local, Tree and Remote policy owners, not its provider services.
|
|
37
|
-
|
|
38
|
-
Required boundaries in the current source:
|
|
39
|
-
|
|
40
|
-
- `context-management/tools.ts` and `extension/tools.ts`: replace the four tools through the registration callback. Active-tool and schema rewrites must preserve delegated definitions while Notes owns continuity. Consult optional `owner.allowsWindowRequests()` when selecting active tools. A false result hides `new_context` without removing its registration. Restore legacy routers only when Notes yields ownership.
|
|
41
|
-
- `extension/session-lifecycle.ts` and `extension/turn-lifecycle.ts`: skip legacy notes/window initialization, input holding, checkpoint admission, note freshness, reminders, settlement records and continuation scheduling. Leave PCC's prompt preparation, runtime synchronization, Notebook status, voice, quota and provider lifecycle active.
|
|
42
|
-
- `extension/compaction-lifecycle.ts`: consult `owner.allowsCompaction(reason)` before any compaction work. When false, return without work so the owner's hook can cancel and handle notes-only rollover, regardless of extension order. Skip legacy `contextWindows.prepareCompaction` and notes checkpoint overrides. When this extension allows normal compaction, run the unchanged installed PCC normal-compaction path. Overflow stays in the same window. Notebook checkpointing, native compaction, replay, transport reset and presentation remain PCC-owned.
|
|
43
|
-
- `context-management/window-manager.ts`, `window-request.ts` and native replay serializers: use `owner.identity(ctx)` and `owner.projectBranch(entries)` for the active window and retirement boundary. Preserve PCC request metadata and zero-based generation semantics. Do not recreate remote history-ingest requirements for local notes.
|
|
44
|
-
- PCC message preparation and `adapter/developer-messages.ts`: preserve `notes-compaction:window:v1` and `notes-compaction:checkpoint:v1` custom messages on every model. Compatible Responses routes may promote them to developer messages. Ordinary Pi conversion must retain them on other routes. Use `owner.projectMessages(messages)` before native replay/prewarm, without overwriting another extension's preparation.
|
|
45
|
-
- Settings UI: show notes continuity as externally managed. Preserve old PCC values for sessions without the external extension. Do not add another compaction setting to this extension.
|
|
46
|
-
|
|
47
|
-
Normal compaction output belongs exclusively to Pi and PCC. This package does not port V2, copy encrypted compaction checkpoints or persist its own compaction records.
|
|
48
|
-
|
|
49
|
-
`beforeWindow(ctx, signal?)` is optional. PCC can checkpoint Notebook and reset owned transport/window state there. It must fail before a new marker is appended if preparation fails. A rollover continuation is a settled custom-message kickoff through Pi 1.2’s complete `before_agent_start` chain. Checkpoint requests use custom kickoffs too; held user input retains its original `input` admission. The `pi-notes-compaction:custom-turn-admission:v1` event admits idle custom kickoffs before Pi reserves startup as busy, so rollover compaction can finish first.
|
|
50
|
-
|
|
51
|
-
## Code and Notebook
|
|
52
|
-
|
|
53
|
-
`configureTools(tools, ctx, contracts)` receives the delegated definitions and compact `notes` and `history` usage strings. Reuse PCC's existing `toNestedTool` and `registerCodeModeExtensionTools` machinery inside PCC:
|
|
54
|
-
|
|
55
|
-
- Defer notes/history schemas and full contracts through discovery. Keep them callable and discoverable in `ALL_TOOLS` without per-tool provider schemas or standing usage.
|
|
56
|
-
- Calls use ordinary query and text arguments, not encrypted model arguments.
|
|
57
|
-
- Plain local results remain ordinary JavaScript values. For results containing opaque remote responses, JavaScript gets a receipt and the model gets protected delivery.
|
|
58
|
-
- Preserve current-call and original-exec ancestry through `exec` and `wait`. Propagate the successful local note-write receipt to PCC's existing saved-note presentation if needed.
|
|
59
|
-
- Preserve `details.notesCompaction` on direct write results. Nested exec/wait must keep PCC's `contextNotesSaved` success or failure outcome, including a failed write after an earlier successful write. Checkpoint freshness requires completed write results, not receipt existence alone.
|
|
60
|
-
- `new_context` is `model-only`, sequential and **never nested**. Keep its native schema in Code and Notebook. Do not expose it through `tools` or execute a rollover under an exec cell.
|
|
61
|
-
|
|
62
|
-
Configuration is repeated on session start and model selection. It must be idempotent. Do not rewrite earlier tool calls or results.
|
|
63
|
-
|
|
64
|
-
## Remote response cache and provider projection
|
|
65
|
-
|
|
66
|
-
Optional `lookup(query, ctx, signal?)` handles read-only notes/history operations through PCC's existing authenticated backend. The query is `{ namespace: "notes" | "history", params }`. Paths sent to lookup are fully qualified virtual paths. Writes never go to the remote backend.
|
|
67
|
-
|
|
68
|
-
Return `CachedResponse[]`, with each element containing:
|
|
69
|
-
|
|
70
|
-
- `query`: the exact query whose result these bytes represent.
|
|
71
|
-
- `bytes`: the unchanged backend response bytes as `Uint8Array`.
|
|
72
|
-
- `source`: the existing backend/source identity needed to project the response.
|
|
73
|
-
- `encoding`: the response encoding, normally `application/json`.
|
|
74
|
-
- `fetchedAt`: the access timestamp in milliseconds.
|
|
75
|
-
- `coverage`: `complete`, `partial` or `unknown`. This describes that response, not the entire remote archive.
|
|
76
|
-
|
|
77
|
-
Return the requested response and any additional complete query responses already present on access. Do not fabricate plaintext file indexes from encrypted lists or searches. The new extension caches every returned response, then projects responses matching the requested query. A network failure reuses the newest cached exact-query response per source and labels it offline. Database or delivery failure remains a failure.
|
|
78
|
-
|
|
79
|
-
`canProject(ctx)` must return false when the active model cannot consume encrypted results. Without compatible projection, ciphertext stays cached and local data remains available.
|
|
80
|
-
|
|
81
|
-
`projectResult(result, responses, callId, ctx, signal?)` returns a fresh `AgentToolResult`. Decode only the response envelope to recover its original `encrypted_output` and useful plain attachment hint. Do not decrypt, concatenate ciphertext strings, invent an old call ID or reuse an old protected-delivery record. The provider boundary must emit the actual current tool call's function output as native blocks:
|
|
82
|
-
|
|
83
|
-
```ts
|
|
84
|
-
{
|
|
85
|
-
type: "function_call_output",
|
|
86
|
-
call_id: actualCurrentCallId,
|
|
87
|
-
output: [
|
|
88
|
-
{ type: "input_text", text: localResultAndCoverage },
|
|
89
|
-
{ type: "encrypted_content", encrypted_content: unchangedEncryptedOutput }
|
|
90
|
-
]
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
Multiple responses stay distinct blocks. Local append overlays stay labelled as overlays, not a decrypted merge. Local replacements supersede remote path reads. Opaque lists/searches can still describe old paths, so preserve the local-authority labels.
|
|
95
|
-
|
|
96
|
-
For direct calls, extend PCC's `codexHistoryNotes` extraction and Responses conversion to accept the fresh cache-backed result. For nested calls, use PCC's existing authenticated opaque capture and protocol-2 original-exec relay. Cache-backed responses need a new honest delivery envelope for the current call. Retain necessary existing source metadata, but do not add an account-binding, portability, export or key-management framework.
|
|
97
|
-
|
|
98
|
-
**Persistence boundary:** `Uint8Array` is only the in-process adapter type. Any bytes placed in persisted result details must be encoded explicitly, for example base64 with the declared encoding. JSON serialization of a typed array is not a supported cache or replay format. SQLite stores the original BLOB. PCC retains its existing serialized opaque-delivery format where possible.
|
|
99
|
-
|
|
100
|
-
Optional `agentName(ctx)` and `route(query, callId, ctx, signal?)` adapt existing PCC family identity and sharing routes. `route` returns `undefined` for current-agent requests. For another agent it returns the normal routed result, preserving that owner's freshness and delivery semantics. If routing is absent or unavailable, Notes can read previously shared local notes through persisted family relationships and attachment aliases. It follows recorded local session paths, never a directory scan. Saved identities also preserve agent names without PCC. Authentication, query and cancellation errors do not trigger this fallback. Cross-agent writes and history still require live routing.
|
|
101
|
-
|
|
102
|
-
## Validation required for the PCC patch
|
|
103
|
-
|
|
104
|
-
Use the real Pi registry in both extension orders. Check that only PCC owns the four delegated registrations and that its remaining prompt/tool rewrites retain them. Capture final provider schemas and instructions separately in normal, Code and Notebook modes. Exercise direct and original-exec cached opaque delivery, including `wait`, offline lookup, incompatible model selection and persisted replay. Run abort/error checkpoint paths and a later extension's preparation hook. Existing PCC alone must remain unchanged.
|
|
13
|
+
Pi owns session lifecycle. Notes decides when to request or cancel compaction. PCC implements the selected provider compaction method and respects context changes from extensions. Neither extension replaces another extension's preparation.
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Pi Notes Compaction
|
|
2
2
|
|
|
3
|
-
Keep working across fresh context windows with local checkpoint notes, searchable session history and optional remote lookup. Works with any Pi model.
|
|
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
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -12,13 +12,21 @@ pi install npm:@howaboua/pi-notes-compaction
|
|
|
12
12
|
|
|
13
13
|
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.
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
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).
|
|
16
16
|
|
|
17
17
|
## Notes and windows
|
|
18
18
|
|
|
19
19
|
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.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
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.
|
|
22
|
+
|
|
23
|
+
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.
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
Previously shared local notes and history remain readable after the other agent closes or Shepherdr is removed. Notes follows the saved family relationships and attachment aliases without requiring PCC. Reads use the other session's saved 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 their live routing service. History reads Pi JSONL sessions locally or through a live shared agent, including agents on another machine. Without live access, make the saved session available locally.
|
|
28
|
+
|
|
29
|
+
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.
|
|
22
30
|
|
|
23
31
|
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.
|
|
24
32
|
|
|
@@ -28,30 +36,30 @@ Reminders arrive at 85% and 90% context use. With normal compaction off, `/compa
|
|
|
28
36
|
|
|
29
37
|
Pi rejects `/compact` when there is too little history to prepare compaction, before extensions run. `new_context` follows the separate **New window requests** setting.
|
|
30
38
|
|
|
31
|
-
Idle rollover is off by default. Choose
|
|
39
|
+
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.
|
|
32
40
|
|
|
33
41
|
## Management
|
|
34
42
|
|
|
35
43
|
`/notes` opens the settings panel in interactive Pi. It shows continuity status, storage counts and remote capabilities. Changes save immediately.
|
|
36
|
-
|
|
37
44
|
- **Active** selects **All models** (the default) or **Whitelist**. Whitelist enables the extension only for exact model IDs in the global settings file, regardless of provider. Switching models applies the choice immediately; other models keep their installed compaction behaviour.
|
|
38
45
|
- **Normal compaction** uses the installed Pi or PCC compaction flow for `/compact` and `new_context`. Off keeps notes-only rollover, the default.
|
|
39
46
|
- **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.
|
|
40
47
|
- **Idle rollover** selects the interval or disables it.
|
|
41
|
-
- **Prune missing sessions** removes
|
|
48
|
+
- **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.
|
|
42
49
|
|
|
43
|
-
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.
|
|
50
|
+
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.
|
|
44
51
|
|
|
45
52
|
The whitelist is preseeded in `<Pi agent directory>/notes-compaction/settings.json` (normally `~/.pi/agent/notes-compaction/settings.json`):
|
|
46
53
|
|
|
47
54
|
```json
|
|
48
55
|
{
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
56
|
+
"active": "whitelist",
|
|
57
|
+
"modelWhitelist": ["gpt-6-astra", "gpt-6-sol", "gpt-6-luna", "gpt-6.1-sol"],
|
|
58
|
+
"normalCompaction": false,
|
|
59
|
+
"rankedHistorySearch": false,
|
|
60
|
+
"newWindowRequests": "unrestricted",
|
|
61
|
+
"idleMinutes": 0,
|
|
62
|
+
"taskBoundaryReminder": 0
|
|
55
63
|
}
|
|
56
64
|
```
|
|
57
65
|
|
|
@@ -59,7 +67,7 @@ Add or remove model IDs and reload Pi. Copy the model's exact ID, without Pi's p
|
|
|
59
67
|
|
|
60
68
|
## Optional remote lookup
|
|
61
69
|
|
|
62
|
-
With
|
|
70
|
+
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.
|
|
63
71
|
|
|
64
72
|
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.
|
|
65
73
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howaboua/pi-notes-compaction",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.10",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"better-sqlite3": "13.0.3"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
|
-
"@howaboua/pi-codex-conversion": "4.0.
|
|
42
|
+
"@howaboua/pi-codex-conversion": "4.0.5",
|
|
43
43
|
"@types/better-sqlite3": "9.6.0"
|
|
44
44
|
},
|
|
45
45
|
"peerDependencies": {
|
|
@@ -47,12 +47,16 @@
|
|
|
47
47
|
"@earendil-works/pi-agent-core": ">=1.0.4",
|
|
48
48
|
"@earendil-works/pi-ai": ">=1.0.4",
|
|
49
49
|
"@earendil-works/pi-tui": ">=1.0.4",
|
|
50
|
-
"@howaboua/pi-codex-conversion": ">=4.0.
|
|
50
|
+
"@howaboua/pi-codex-conversion": ">=4.0.5",
|
|
51
51
|
"typebox": "*"
|
|
52
52
|
},
|
|
53
53
|
"peerDependenciesMeta": {
|
|
54
54
|
"@howaboua/pi-codex-conversion": {
|
|
55
55
|
"optional": true
|
|
56
56
|
}
|
|
57
|
+
},
|
|
58
|
+
"exports": {
|
|
59
|
+
".": "./src/index.ts",
|
|
60
|
+
"./context-sharing": "./src/context-sharing.ts"
|
|
57
61
|
}
|
|
58
62
|
}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
import { join } from "node:path";
|
|
2
|
+
import type {
|
|
3
|
+
ExtensionAPI,
|
|
4
|
+
ExtensionContext,
|
|
5
|
+
} from "@earendil-works/pi-coding-agent";
|
|
6
|
+
import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
|
|
7
|
+
import { type NotesBridge, TOOL_NAMES } from "./bridge.js";
|
|
8
|
+
import { indexHistory } from "./history.js";
|
|
9
|
+
import type { HistorySearch } from "./history-search.js";
|
|
10
|
+
import type { NotesLifecycle } from "./lifecycle.js";
|
|
11
|
+
import { sessionRef } from "./notes.js";
|
|
12
|
+
import {
|
|
13
|
+
modelIsActive,
|
|
14
|
+
type NotesSettings,
|
|
15
|
+
readSettings,
|
|
16
|
+
writeSettings,
|
|
17
|
+
} from "./settings.js";
|
|
18
|
+
import type { NotesStore } from "./store.js";
|
|
19
|
+
|
|
20
|
+
export function createNotesActivation(
|
|
21
|
+
pi: ExtensionAPI,
|
|
22
|
+
store: NotesStore,
|
|
23
|
+
search: HistorySearch,
|
|
24
|
+
lifecycle: NotesLifecycle,
|
|
25
|
+
settingsPath: string,
|
|
26
|
+
refreshNested: () => void,
|
|
27
|
+
) {
|
|
28
|
+
let settings: NotesSettings;
|
|
29
|
+
let ready = false;
|
|
30
|
+
let unavailable: string | undefined;
|
|
31
|
+
function refreshActivation(ctx: ExtensionContext): void {
|
|
32
|
+
if (!ready || unavailable) return;
|
|
33
|
+
const active = modelIsActive(settings, ctx.model);
|
|
34
|
+
if (!active) {
|
|
35
|
+
if (lifecycle.active) lifecycle.reset(ctx);
|
|
36
|
+
lifecycle.active = false;
|
|
37
|
+
search.setSession(undefined);
|
|
38
|
+
pi.setActiveTools(
|
|
39
|
+
pi
|
|
40
|
+
.getActiveTools()
|
|
41
|
+
.filter((name) => !TOOL_NAMES.some((tool) => tool === name)),
|
|
42
|
+
);
|
|
43
|
+
refreshNested();
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
if (lifecycle.active) return;
|
|
47
|
+
try {
|
|
48
|
+
lifecycle.active = true;
|
|
49
|
+
configureTools();
|
|
50
|
+
store.updateFile(sessionRef(ctx));
|
|
51
|
+
refreshHistorySearch(ctx);
|
|
52
|
+
} catch (error) {
|
|
53
|
+
lifecycle.active = false;
|
|
54
|
+
unavailable = error instanceof Error ? error.message : String(error);
|
|
55
|
+
ctx.ui.notify(`Notes continuity inactive: ${unavailable}`, "warning");
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
function configureTools(): void {
|
|
59
|
+
const names = TOOL_NAMES.filter(
|
|
60
|
+
(name) => name !== "new_context" || lifecycle.newWindowRequests !== "off",
|
|
61
|
+
);
|
|
62
|
+
pi.setActiveTools([
|
|
63
|
+
...new Set([
|
|
64
|
+
...pi
|
|
65
|
+
.getActiveTools()
|
|
66
|
+
.filter((name) => !TOOL_NAMES.some((tool) => tool === name)),
|
|
67
|
+
...names,
|
|
68
|
+
]),
|
|
69
|
+
]);
|
|
70
|
+
refreshNested();
|
|
71
|
+
}
|
|
72
|
+
function refreshHistorySearch(ctx: ExtensionContext, update = false): void {
|
|
73
|
+
const sessionId =
|
|
74
|
+
lifecycle.active && settings.rankedHistorySearch
|
|
75
|
+
? ctx.sessionManager.getSessionId()
|
|
76
|
+
: undefined;
|
|
77
|
+
const changed = search.setSession(
|
|
78
|
+
sessionId,
|
|
79
|
+
ctx.sessionManager.getSessionFile(),
|
|
80
|
+
);
|
|
81
|
+
if (!sessionId || (!changed && !update)) return;
|
|
82
|
+
void indexHistory(
|
|
83
|
+
ctx.sessionManager.getBranch(),
|
|
84
|
+
sessionId,
|
|
85
|
+
search,
|
|
86
|
+
ctx.sessionManager.getEntries(),
|
|
87
|
+
).catch((error: unknown) => {
|
|
88
|
+
if (!search.isEnabled(sessionId)) return;
|
|
89
|
+
ctx.ui.notify(
|
|
90
|
+
error instanceof Error ? error.message : String(error),
|
|
91
|
+
"warning",
|
|
92
|
+
);
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
function applySettings(value: NotesSettings): void {
|
|
96
|
+
settings = value;
|
|
97
|
+
lifecycle.normalCompaction = value.normalCompaction;
|
|
98
|
+
lifecycle.newWindowRequests = value.newWindowRequests;
|
|
99
|
+
lifecycle.idleMinutes = value.idleMinutes;
|
|
100
|
+
lifecycle.taskBoundaryReminder = value.taskBoundaryReminder;
|
|
101
|
+
}
|
|
102
|
+
function start(ctx: ExtensionContext, family: NotesBridge): void {
|
|
103
|
+
search.setSession(undefined);
|
|
104
|
+
lifecycle.reset(ctx);
|
|
105
|
+
lifecycle.active = false;
|
|
106
|
+
ready = false;
|
|
107
|
+
unavailable = undefined;
|
|
108
|
+
try {
|
|
109
|
+
settings = readSettings(settingsPath, [
|
|
110
|
+
join(getAgentDir(), "pi-codex-conversion.json"),
|
|
111
|
+
...(ctx.isProjectTrusted()
|
|
112
|
+
? [join(ctx.cwd, CONFIG_DIR_NAME, "pi-codex-conversion.json")]
|
|
113
|
+
: []),
|
|
114
|
+
]);
|
|
115
|
+
writeSettings(settingsPath, settings);
|
|
116
|
+
applySettings(settings);
|
|
117
|
+
lifecycle.bridge = family;
|
|
118
|
+
ready = true;
|
|
119
|
+
|
|
120
|
+
refreshActivation(ctx);
|
|
121
|
+
} catch (error) {
|
|
122
|
+
unavailable = error instanceof Error ? error.message : String(error);
|
|
123
|
+
ctx.ui.notify(`Notes continuity inactive: ${unavailable}`, "warning");
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
function save(value: NotesSettings, ctx: ExtensionContext): void {
|
|
127
|
+
writeSettings(settingsPath, value);
|
|
128
|
+
applySettings(value);
|
|
129
|
+
refreshActivation(ctx);
|
|
130
|
+
refreshHistorySearch(ctx);
|
|
131
|
+
if (lifecycle.active) configureTools();
|
|
132
|
+
}
|
|
133
|
+
return {
|
|
134
|
+
start,
|
|
135
|
+
save,
|
|
136
|
+
refreshActivation,
|
|
137
|
+
refreshHistorySearch,
|
|
138
|
+
get settings() {
|
|
139
|
+
return settings;
|
|
140
|
+
},
|
|
141
|
+
get ready() {
|
|
142
|
+
return ready;
|
|
143
|
+
},
|
|
144
|
+
get unavailable() {
|
|
145
|
+
return unavailable;
|
|
146
|
+
},
|
|
147
|
+
get available() {
|
|
148
|
+
return ready && !unavailable;
|
|
149
|
+
},
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
export type NotesActivation = ReturnType<typeof createNotesActivation>;
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
|
|
3
|
+
export const CONTEXT_AGENT_ENTRY = "codex-context-agent";
|
|
4
|
+
const CONTEXT_BACKEND_ENTRY = "codex-context-backend";
|
|
5
|
+
|
|
6
|
+
export interface ContextAgentIdentity {
|
|
7
|
+
protocol: 1;
|
|
8
|
+
sessionId: string;
|
|
9
|
+
threadId: string;
|
|
10
|
+
agentName: string;
|
|
11
|
+
storage?: "remote" | "session";
|
|
12
|
+
accountScope?: string;
|
|
13
|
+
backendUrl?: string;
|
|
14
|
+
routing?: unknown;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export type ContextAgentBinding = Omit<
|
|
18
|
+
ContextAgentIdentity,
|
|
19
|
+
"threadId" | "storage"
|
|
20
|
+
> & {
|
|
21
|
+
storage: "remote" | "session";
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
export function parseContextAgentBinding(input: unknown): ContextAgentBinding {
|
|
25
|
+
const value = input as Partial<ContextAgentBinding> | undefined;
|
|
26
|
+
if (
|
|
27
|
+
value?.protocol !== 1 ||
|
|
28
|
+
typeof value.sessionId !== "string" ||
|
|
29
|
+
!value.sessionId ||
|
|
30
|
+
typeof value.agentName !== "string" ||
|
|
31
|
+
!/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(value.agentName) ||
|
|
32
|
+
(value.storage !== "remote" && value.storage !== "session") ||
|
|
33
|
+
(value.backendUrl !== undefined &&
|
|
34
|
+
(typeof value.backendUrl !== "string" || !value.backendUrl)) ||
|
|
35
|
+
(value.storage === "remote" &&
|
|
36
|
+
(typeof value.accountScope !== "string" ||
|
|
37
|
+
!/^[a-f0-9]{64}$/.test(value.accountScope)))
|
|
38
|
+
)
|
|
39
|
+
throw new Error("Invalid Codex context identity");
|
|
40
|
+
return {
|
|
41
|
+
protocol: 1,
|
|
42
|
+
sessionId: value.sessionId,
|
|
43
|
+
agentName: value.agentName,
|
|
44
|
+
storage: value.storage,
|
|
45
|
+
...(value.accountScope === undefined
|
|
46
|
+
? {}
|
|
47
|
+
: { accountScope: value.accountScope }),
|
|
48
|
+
...(value.backendUrl === undefined ? {} : { backendUrl: value.backendUrl }),
|
|
49
|
+
...(value.routing === undefined ? {} : { routing: value.routing }),
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function contextAgentIdentity(
|
|
54
|
+
ctx: Pick<ExtensionContext, "sessionManager">,
|
|
55
|
+
): ContextAgentIdentity {
|
|
56
|
+
const threadId = ctx.sessionManager.getSessionId();
|
|
57
|
+
let identity: ContextAgentIdentity | undefined;
|
|
58
|
+
// Identity belongs to the session, not its active branch. Forks get a new identity.
|
|
59
|
+
for (const entry of ctx.sessionManager.getEntries()) {
|
|
60
|
+
if (entry.type !== "custom" || entry.customType !== CONTEXT_AGENT_ENTRY)
|
|
61
|
+
continue;
|
|
62
|
+
const value = entry.data as Partial<ContextAgentIdentity> | undefined;
|
|
63
|
+
if (value?.threadId !== threadId) continue;
|
|
64
|
+
if (identity)
|
|
65
|
+
throw new Error("Conflicting persisted Codex context identities");
|
|
66
|
+
identity = { ...parseContextAgentBinding(value), threadId };
|
|
67
|
+
}
|
|
68
|
+
if (identity?.storage === "remote") {
|
|
69
|
+
for (const entry of ctx.sessionManager.getEntries()) {
|
|
70
|
+
if (entry.type !== "custom" || entry.customType !== CONTEXT_BACKEND_ENTRY)
|
|
71
|
+
continue;
|
|
72
|
+
const pin = entry.data as Partial<ContextAgentIdentity> | undefined;
|
|
73
|
+
if (pin?.threadId !== threadId) continue;
|
|
74
|
+
if (
|
|
75
|
+
pin.sessionId !== identity.sessionId ||
|
|
76
|
+
pin.agentName !== identity.agentName ||
|
|
77
|
+
pin.accountScope !== identity.accountScope ||
|
|
78
|
+
typeof pin.backendUrl !== "string" ||
|
|
79
|
+
!pin.backendUrl ||
|
|
80
|
+
(identity.backendUrl && identity.backendUrl !== pin.backendUrl)
|
|
81
|
+
)
|
|
82
|
+
throw new Error("Conflicting persisted Remote context backend");
|
|
83
|
+
identity.backendUrl = pin.backendUrl;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
return (
|
|
87
|
+
identity ?? {
|
|
88
|
+
protocol: 1,
|
|
89
|
+
sessionId: threadId,
|
|
90
|
+
threadId,
|
|
91
|
+
agentName: "/root",
|
|
92
|
+
}
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export function contextTargetAgent(
|
|
97
|
+
namespace: "history" | "notes",
|
|
98
|
+
params: Record<string, unknown>,
|
|
99
|
+
agentName: string,
|
|
100
|
+
): string {
|
|
101
|
+
const value =
|
|
102
|
+
namespace === "history"
|
|
103
|
+
? params["agent_name"]
|
|
104
|
+
: (params["path"] ?? params["prefix"] ?? params["path_prefix"]);
|
|
105
|
+
if (value === undefined || value === null || value === "") return agentName;
|
|
106
|
+
if (typeof value !== "string")
|
|
107
|
+
throw new Error("Context path must be a string");
|
|
108
|
+
if (namespace === "notes") {
|
|
109
|
+
if (!value.startsWith("/")) return agentName;
|
|
110
|
+
const match = /^(\/root(?:\/[a-zA-Z0-9_-]+)*?)\/notes(?:\/|$)/.exec(value);
|
|
111
|
+
if (!match)
|
|
112
|
+
throw new Error("Absolute note paths must use <agent>/notes[/path]");
|
|
113
|
+
return match[1]!;
|
|
114
|
+
}
|
|
115
|
+
const target = value.startsWith("/") ? value : `${agentName}/${value}`;
|
|
116
|
+
if (!/^\/root(?:\/[a-zA-Z0-9_-]+)*$/.test(target))
|
|
117
|
+
throw new Error("Invalid history agent name");
|
|
118
|
+
return target;
|
|
119
|
+
}
|