From 0e2aa21c7af920212c12ace6548790b0e9c36173 Mon Sep 17 00:00:00 2001 From: HugoLopes45 Date: Fri, 13 Nov 2026 11:28:50 +0100 Subject: [PATCH] Add plain-language status, /context-kit panel and own settings file Users of any level can see and change cleanup settings without editing JSON: the footer says how full the context is and when cleanup starts, and /context-kit edits the main settings in plain words. Settings move to context-kit.json, with a schema for editors, and 0.3 settings move there automatically with the same behavior, including project settings merged over global ones. --- .github/ISSUE_TEMPLATE/bug.yml | 2 +- README.md | 418 ++++++------------------ context-kit.schema.json | 106 ++++++ extensions/index.ts | 244 ++++++++++++-- package-lock.json | 2 + package.json | 5 +- src/background.ts | 33 +- src/config.ts | 272 ++++++++++------ src/migrate.ts | 135 ++++++++ src/panel.ts | 89 ++++++ src/settings-file.ts | 153 +++++++++ src/status.ts | 41 +++ test/background.test.ts | 25 ++ test/config.test.ts | 209 +++++++++--- test/extension.test.ts | 569 +++++++++++++++++++++++++++------ test/migrate.test.ts | 141 ++++++++ test/panel.test.ts | 145 +++++++++ test/settings-file.test.ts | 192 +++++++++++ test/status.test.ts | 57 ++++ 19 files changed, 2250 insertions(+), 588 deletions(-) create mode 100644 context-kit.schema.json create mode 100644 src/migrate.ts create mode 100644 src/panel.ts create mode 100644 src/settings-file.ts create mode 100644 src/status.ts create mode 100644 test/migrate.test.ts create mode 100644 test/panel.test.ts create mode 100644 test/settings-file.test.ts create mode 100644 test/status.test.ts diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index e111b4f..727c459 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -10,7 +10,7 @@ body: id: versions attributes: label: Environment - description: Include the package, Pi, Node.js, operating system, and model versions, and your `contextKit` and `compaction` settings. + description: Include the package, Pi, Node.js, operating system, and model versions, your `context-kit.json` files, and your `compaction` settings. validations: required: true - type: textarea diff --git a/README.md b/README.md index 0f92e06..97eed3d 100644 --- a/README.md +++ b/README.md @@ -19,11 +19,12 @@ Restart Pi. That is all: the defaults work without configuration. Requirements: - **Nothing is deleted.** The session keeps the original text. The model searches and reads it again with the `recall` tool. - **Free where possible.** Replacing old reads, pruning and shaking do not call the model. - **Cache-friendly.** Context edits happen only above the threshold, in one batch. The provider's prompt cache breaks once per maintenance step, not at each turn. -- **Zero setup.** Install, restart, work. Tune it later if you want. +- **Zero setup.** Install, restart, work. By default, maintenance starts at 75% of the context window, which for most models is before Pi's own limit. +- **Visible.** The footer shows how full the context is and when cleanup starts. A notice tells you what was freed. Type `/context-kit` to change the main settings in a panel, without editing a file. ## What the model sees -Above the threshold, large old content becomes a one-line notice. The full text stays in the session. Example (the sizes and IDs are illustrative; the last notice appears only when shaking runs, see [`methodOrder`](#methodorder)): +Above the threshold, large old content becomes a one-line notice. The full text stays in the session. Example (the sizes and IDs are illustrative; the last notice appears only when shaking runs, see [`strategy`](#main-settings)): ```diff - @@ -91,28 +92,30 @@ To update, type `pi update npm:pi-context-kit` and restart Pi. To remove it, type `pi remove npm:pi-context-kit` and restart Pi. -## Recommended setup +## Use it -The default setup works without changes. By default, maintenance starts at the same time as Pi's compaction. -For large context windows, start maintenance earlier. This example starts at 150,000 tokens: +You do not need to configure anything. pi-context-kit shows its state in Pi's footer: -1. Open the file `~/.pi/agent/settings.json` in a text editor. `~` is your home folder. -2. Add the `contextKit` block inside the outer `{ }`. Put a comma between this block and the other settings. +| Footer | Meaning | +| --- | --- | +| `Context 62% · cleanup at 75%` | The context is 62% full. Cleanup starts at 75%. | +| `Context 70% · cleanup at 75% · writing summary` | A handoff note is being written in the background. `summary ready` means that it is ready. | +| `Context 25% · no automatic cleanup` | Pi's automatic compaction is off, so cleanup runs only when you type `/compact`. | +| `Context cleanup off` | You turned automatic cleanup off. | - ```json - { - "contextKit": { - "thresholdTokens": 150000 - } - } - ``` +After pi-context-kit shortens old outputs, Pi shows a notice, for example: `pi-context-kit freed 17% of the context (34k tokens). The agent can still look up what was removed.` -3. Save the file. -4. In Pi, type `/reload`, or restart Pi. +To change the settings, type `/context-kit` and press Enter. Select a line with the arrow keys and press Enter to change its value. The change is saved at once and applies from the next turn. Press Escape to close the panel. -If a value is incorrect, Pi shows a warning that starts with `pi-context-kit: invalid settings`. The incorrect value is ignored and its default is used. +| Panel line | Choices | Setting in the file | +| --- | --- | --- | +| Automatic cleanup | On, Off | `enabled` | +| Clean up when the context is | 50% to 90% full, At Pi's limit | `threshold` | +| Cleanup method | Summary notes (recommended), Trim first, Pi's summary | `strategy`: `"balanced"`, `"frugal"`, `"pi-summary"` | -To use a setting only in one project, put the same block in the file `.pi/settings.json` in that project folder. Project settings replace global settings. +The panel does not show the Cleanup method line when `advanced.methodOrder` is in the file, because that setting replaces the method. + +Outside the interactive mode, `/context-kit` shows the current settings in one line. ## How it works during a session @@ -134,7 +137,7 @@ To use a setting only in one project, put the same block in the file `.pi/settin | no v - Try each method in "methodOrder": handoff, shake, soft + Try each method of the strategy, for example: handoff, shake, soft ``` ### 1. Old file reads are replaced @@ -161,7 +164,7 @@ The newest 40,000 tokens of tool outputs always stay. pi-context-kit keeps this ### 4. Other methods, in order -If pruning is not sufficient, pi-context-kit tries the methods in `methodOrder`, one after the other: +If pruning is not sufficient, pi-context-kit tries the methods of the [strategy](#main-settings), one after the other: | Method | What it does | Uses the model? | | --- | --- | --- | @@ -195,298 +198,105 @@ Compaction is different: it replaces older context with a summary, including old ## Settings -This section lists every setting. Each setting has its allowed values, its default, and an example. - -### Where to put the settings +This section is for users who edit the settings file. The panel changes the three main settings; the file also has the advanced settings. -Put all settings in a `contextKit` block, in one of these files: +### The settings files | File | Applies to | | --- | --- | -| `~/.pi/agent/settings.json` | All your projects. `~` is your home folder. | -| `.pi/settings.json` in a project folder | Only this project. These values replace the values of the global file. | +| `~/.pi/agent/context-kit.json` | All your projects. `~` is your home folder. | +| `.pi/context-kit.json` in a project folder | Only this project, and only when you trust the project in Pi. Its values replace the values of the global file. | -You do not need to set all settings. A missing setting uses its default. -After a change, type `/reload` in Pi, or restart Pi. +You do not need to set all settings. A missing setting uses its default. pi-context-kit reads the files again at each turn, so you do not need to restart Pi. The panel writes to the project file when that file sets the setting, otherwise to the global file. -### All settings with their defaults - -This block sets every setting to its default. It has the same effect as no `contextKit` block. -Copy only the lines that you want to change. +Add the `$schema` line to get completion and checks in editors such as VS Code: ```json { - "contextKit": { - "enabled": true, - "thresholdTokens": -1, - "thresholdPercent": -1, - "methodOrder": ["handoff", "shake", "soft"], - "asyncEnabled": true, - "supersedeReads": true, - "progressRatio": 0.8, - "prune": { - "enabled": true, - "protectTokens": 40000, - "minSavings": 20000, - "minTokens": 50 - }, - "shake": { - "protectTokens": 16000, - "minSavings": 4000, - "blockMinTokens": 400 - } - } + "$schema": "https://unpkg.com/pi-context-kit/context-kit.schema.json", + "threshold": "70%", + "strategy": "frugal" } ``` -### Summary table +### Main settings -| Setting | Allowed values | Default | Short description | +| Setting | Allowed values | Default | What it does | | --- | --- | --- | --- | -| [`enabled`](#enabled) | `true`, `false` | `true` | Turns all maintenance on or off. | -| [`thresholdTokens`](#thresholdtokens) | `-1`, or a whole number above 0 | `-1` | Starts maintenance at this number of tokens. | -| [`thresholdPercent`](#thresholdpercent) | `-1`, or a number above 0, up to 100 | `-1` | Starts maintenance at this percentage of the context window. | -| [`methodOrder`](#methodorder) | A list of `"handoff"`, `"shake"`, `"soft"` | `["handoff", "shake", "soft"]` | The methods to try, and their order. | -| [`asyncEnabled`](#asyncenabled) | `true`, `false` | `true` | Prepares the handoff note in the background. | -| [`supersedeReads`](#supersedereads) | `true`, `false` | `true` | Replaces old copies of a file that was read again. | -| [`progressRatio`](#progressratio) | A number above 0, up to 1 | `0.8` | How small the context must become. | -| [`prune.enabled`](#pruneenabled) | `true`, `false` | `true` | Turns pruning of old tool outputs on or off. | -| [`prune.protectTokens`](#pruneprotecttokens) | A whole number, 0 or more | `40000` | The newest tool outputs that are never pruned. | -| [`prune.minSavings`](#pruneminsavings) | A whole number, 0 or more | `20000` | The minimum gain for pruning. | -| [`prune.minTokens`](#prunemintokens) | A whole number, 0 or more | `50` | Tool outputs smaller than this are never pruned. | -| [`shake.protectTokens`](#shakeprotecttokens) | A whole number, 0 or more | `16000` | The newest context that is never shaken. | -| [`shake.minSavings`](#shakeminsavings) | A whole number, 0 or more | `4000` | The minimum gain for shaking. | -| [`shake.blockMinTokens`](#shakeblockmintokens) | A whole number, 0 or more | `400` | Blocks smaller than this are never shaken. | - -"Whole number" means a number without decimals, for example `150000`. Do not put spaces, dots, or commas in numbers: write `150000`, not `150,000`. - -### When a setting is incorrect - -pi-context-kit checks each value. If a value is incorrect, Pi shows a warning, and the setting uses its default. The other settings still apply. - -Example: with `"thresholdTokens": "150000"` (a text in quotes, not a number), Pi shows: - -```text -pi-context-kit: invalid settings, defaults used (contextKit.thresholdTokens must be -1 or a positive integer). -``` +| `enabled` | `true`, `false` | `true` | `false` stops all maintenance and handoff notes. The `recall` tool stays available. | +| `threshold` | A whole number of tokens, a percentage such as `"75%"`, or `"pi"` | `"75%"` | Where maintenance starts. | +| `strategy` | `"balanced"`, `"frugal"`, `"pi-summary"` | `"balanced"` | What pi-context-kit does when pruning is not sufficient. | -A setting name with a spelling mistake also shows a warning, for example `contextKit.treshold is not a setting`. +**`threshold`.** A percentage applies to each model's context window, so `"75%"` is 150,000 tokens with a 200,000-token window and 750,000 tokens with a 1,000,000-token window. Decimals are allowed, for example `"72.5%"`. A number such as `150000` is the same for all models. Do not put spaces, dots or commas in a number of tokens. `"pi"` waits for Pi's own limit. pi-context-kit can start before Pi's limit, never after: if your value is larger, Pi's limit is used. See [Pi settings that also apply](#pi-settings-that-also-apply). -### `enabled` +**`strategy`.** -Turns all maintenance on or off. - -- `true` (default): pi-context-kit works as described in this document. -- `false`: pi-context-kit does nothing. Pi uses only its own summary. The `recall` tool stays available. - -```json -{ "contextKit": { "enabled": false } } -``` - -### `thresholdTokens` - -Maintenance starts when the context is larger than this number of tokens. - -- `-1` (default): use `thresholdPercent`. If `thresholdPercent` is also `-1`, use Pi's limit. -- A whole number above 0: start at this number of tokens. - -This setting has priority over `thresholdPercent`. -pi-context-kit can start before Pi's limit, never after. If your value is larger than Pi's limit, Pi's limit is used. See [Pi settings that also apply](#pi-settings-that-also-apply). - -Example: start at 150,000 tokens. - -```json -{ "contextKit": { "thresholdTokens": 150000 } } -``` - -| Model context window | Pi's limit (default reserve) | Threshold used | +| Strategy (panel name) | Above the threshold, after pruning | Background requests | | --- | --- | --- | -| 1,000,000 | 983,616 | 150,000 | -| 200,000 | 183,616 | 150,000 | -| 128,000 | 111,616 | 111,616 (Pi's limit is smaller) | - -### `thresholdPercent` - -Maintenance starts when the context is larger than this percentage of the model's context window. - -- `-1` (default): no percentage. If `thresholdTokens` is also `-1`, use Pi's limit. -- A number above 0, up to 100: start at this percentage. Decimals are allowed, for example `72.5`. Values above 99 are used as 99. +| `"balanced"` (Summary notes) | A handoff note. If the note fails, shake. Then Pi's summary. | Yes: the note is written before the threshold. | +| `"frugal"` (Trim first) | Shake, because it does not call the model. If that is not sufficient, a handoff note. Then Pi's summary. | No | +| `"pi-summary"` (Pi's summary) | Pi's summary. No handoff note, no shaking. | No | -pi-context-kit ignores this setting when `thresholdTokens` is not `-1`. +### Advanced settings -Example: start at 75% of the context window. +Put these settings in an `advanced` block. Most users never need them. ```json -{ "contextKit": { "thresholdPercent": 75 } } +{ + "advanced": { + "methodOrder": ["handoff", "shake", "soft"], + "background": true, + "supersedeReads": true, + "progressRatio": 0.8, + "prune": { "enabled": true, "protectTokens": 40000, "minSavings": 20000, "minTokens": 50 }, + "shake": { "protectTokens": 16000, "minSavings": 4000, "blockMinTokens": 400 } + } +} ``` -| Model context window | Threshold used | -| --- | --- | -| 1,000,000 | 750,000 | -| 200,000 | 150,000 | -| 128,000 | 96,000 | - -Use `thresholdPercent` if you use models with different context windows and you want the same proportion for all of them. Use `thresholdTokens` if you want the same number for all of them. - -### `methodOrder` - -The methods that pi-context-kit tries when pruning is not sufficient, in this order. - -Allowed values in the list: - -| Value | What it does | Calls the model? | +| Setting | Default | What it does | | --- | --- | --- | -| `"handoff"` | Replaces the old conversation with a handoff note. The newest messages stay. | Yes, the session model | -| `"shake"` | Replaces large old code blocks, XML blocks, and images with a short notice. | No | -| `"soft"` | Replaces the old conversation with Pi's summary. The newest messages stay. Stops the list. | Yes, the session model | -| `"remote"`, `"snapcompact"` | Accepted for oh-my-pi compatibility, but skipped. Pi does not have these methods. | No | - -Rules: - -- The order is important. pi-context-kit tries the first method, then the next one. -- `"soft"` ends the list. Methods after `"soft"` never run. -- If `"handoff"` is not in the list before `"soft"`, pi-context-kit writes no handoff note at all. This also applies to `/compact` and to background notes. Pi writes its own summary. -- If `"shake"` is not in the list before `"soft"`, nothing is shaken. -- A value that appears two times is used one time. -- An empty list `[]` is allowed. Then pi-context-kit only replaces old file reads and prunes old tool outputs. - -Common choices: - -| `methodOrder` | What happens above the threshold | -| --- | --- | -| `["handoff", "shake", "soft"]` (default) | Prune. Then a handoff note. If the note fails, shake. Then Pi's summary. | -| `["shake", "handoff", "soft"]` | Prune and shake together. If that is not sufficient, a handoff note. Then Pi's summary. | -| `["handoff", "soft"]` | Prune. Then a handoff note. Never shake. | -| `["shake", "soft"]` | Prune and shake. Then Pi's summary. No handoff note. | -| `["soft"]` | Prune. Then Pi's summary. | -| `[]` | Prune only. Pi writes its summary when the context reaches Pi's limit. | - -Example: try shaking first, because it does not call the model. - -```json -{ "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } } -``` - -### `asyncEnabled` - -Prepares the handoff note in the background, before the threshold. - -- `true` (default): the note starts one eighth of the threshold early, with a maximum of 32,000 tokens. If the note is ready at the threshold, compaction is fast. -- `false`: no background note. At the threshold, pi-context-kit writes a new note. Your work waits for this note. - -This setting has an effect only if `"handoff"` is in `methodOrder` before `"soft"`. - -Example: no background requests. - -```json -{ "contextKit": { "asyncEnabled": false } } -``` - -### `supersedeReads` - -Replaces the old copy of a file when the model reads the same file again. - -- `true` (default): the old copy becomes `[Superseded by a newer read of this file]`. -- `false`: all copies stay. +| `methodOrder` | From `strategy` | Replaces the method order of the strategy. Allowed values: `"handoff"`, `"shake"`, `"soft"`. Methods after `"soft"` never run. Without `"handoff"` before `"soft"`, no handoff note is written, also on `/compact`. An empty list `[]` only replaces old reads and prunes. | +| `background` | From `strategy` | `true` writes the handoff note in the background, one eighth of the threshold early (maximum 32,000 tokens). `false` writes it at the threshold, and your work waits for it. | +| `supersedeReads` | `true` | Replaces the old copy of a file that the model read again. | +| `progressRatio` | `0.8` | Each method must bring the context to this fraction of the threshold, otherwise its result is not used and the next method runs. Above 0, up to 1. | +| `prune.enabled` | `true` | `false` never prunes tool outputs. | +| `prune.protectTokens` | `40000` | The newest tool outputs, up to this number of tokens, are never pruned. | +| `prune.minSavings` | `20000` | Pruning occurs only if it removes at least this number of tokens. | +| `prune.minTokens` | `50` | Tool outputs smaller than this are never pruned. | +| `shake.protectTokens` | `16000` | The newest context, up to this number of tokens, is never shaken. Your own messages are never shaken. | +| `shake.minSavings` | `4000` | Shaking occurs only if it removes at least this number of tokens. | +| `shake.blockMinTokens` | `400` | Code and XML blocks smaller than this are never shaken. | -This works only above the threshold, together with pruning and shaking. - -```json -{ "contextKit": { "supersedeReads": false } } -``` - -### `progressRatio` - -How small the context must become after a method, as a fraction of the threshold. -If a method cannot make the context this small, pi-context-kit does not use its result and tries the next method. - -- `0.8` (default): the context must become 80% of the threshold or less. With a threshold of 150,000 tokens, this is 120,000 tokens. -- A smaller value, for example `0.6`, gives more free space after maintenance. But each method must remove more, so it fails more often. -- A larger value, for example `0.95`, makes each method succeed more easily. But maintenance can start again soon after. - -The value must be above 0 and not more than 1. - -```json -{ "contextKit": { "progressRatio": 0.7 } } -``` - -### `prune.enabled` - -Turns pruning on or off. Pruning replaces old tool outputs with a notice, for example `[Output pruned: about 5000 tokens. Call recall with entryId "abc123" to read it.]`. - -- `true` (default). -- `false`: tool outputs are never pruned. - -```json -{ "contextKit": { "prune": { "enabled": false } } } -``` - -### `prune.protectTokens` - -The newest tool outputs, up to this number of tokens, are never pruned. Thus the model keeps its most recent results. - -- `40000` (default). -- A larger value keeps more recent outputs, but removes less. - -```json -{ "contextKit": { "prune": { "protectTokens": 60000 } } } -``` - -### `prune.minSavings` - -Pruning occurs only if it removes at least this number of tokens. This prevents small changes with little gain. - -- `20000` (default). - -```json -{ "contextKit": { "prune": { "minSavings": 10000 } } } -``` - -### `prune.minTokens` - -Tool outputs smaller than this number of tokens are never pruned. A notice would not be much smaller than these outputs. - -- `50` (default). - -```json -{ "contextKit": { "prune": { "minTokens": 200 } } } -``` - -### `shake.protectTokens` - -The newest part of the context, up to this number of tokens, is never shaken. Your own messages are never shaken, also when they are old. - -- `16000` (default). - -```json -{ "contextKit": { "shake": { "protectTokens": 32000 } } } -``` - -### `shake.minSavings` - -Shaking occurs only if it removes at least this number of tokens. +### When a setting is incorrect -- `4000` (default). +pi-context-kit checks each value. If a value is incorrect, Pi shows a warning and the setting uses its default. The other settings still apply. Example: with `"threshold": "150000"` (a text in quotes, not a number), Pi shows: -```json -{ "contextKit": { "shake": { "minSavings": 8000 } } } +```text +pi-context-kit settings need attention: threshold must be a positive integer (tokens), a percentage such as "75%", or "pi" (default used). Type /context-kit to see them. ``` -### `shake.blockMinTokens` +Pi also warns about a setting name with a spelling mistake, a file that is not valid JSON, and settings that have no effect, for example `advanced.background` without a handoff note in the method order. -Code blocks and XML blocks smaller than this number of tokens are never shaken. +### Upgrade from 0.3 -- `400` (default). +You do not need to do anything. Version 0.4 reads its own file. At the first start, it copies the `contextKit` block of Pi's `settings.json` to `~/.pi/agent/context-kit.json` (and the block of a trusted project to `.pi/context-kit.json`), with the same behavior, and shows a notice once. The project file gets only the settings that the project block changed, because 0.3 used the global block for the others. It does not change Pi's `settings.json`; you can delete the `contextKit` block, which is no longer used. If `context-kit.json` already exists, nothing is copied. If you had no `contextKit` block, 0.4 starts maintenance at the new default of `"75%"`; to wait for Pi's limit as before, set `"threshold": "pi"`. The table shows how the values are converted. -```json -{ "contextKit": { "shake": { "blockMinTokens": 1000 } } } -``` - -There is no `shake.enabled` setting. To stop shaking, remove `"shake"` from `methodOrder`. +| 0.3 (`contextKit` in `settings.json`) | 0.4 (`context-kit.json`) | +| --- | --- | +| `thresholdTokens: 150000` | `threshold: 150000` | +| `thresholdPercent: 75` | `threshold: "75%"` | +| Both `thresholdTokens` and `thresholdPercent` | `threshold` with the number of tokens | +| No threshold (Pi's limit) | `threshold: "pi"`. The default for new users is `"75%"`. | +| `methodOrder: ["shake", "handoff", "soft"]` | `strategy: "frugal"`, with `advanced.background: true` unless `asyncEnabled` was `false` | +| `methodOrder: ["soft"]` | `strategy: "pi-summary"` | +| Other `methodOrder` values | `advanced.methodOrder`, without `"remote"` and `"snapcompact"`, which 0.3 already skipped. A list with an unknown method becomes the default order, as in 0.3. | +| `asyncEnabled` | `advanced.background`, when it differs from the strategy | +| `supersedeReads`, `progressRatio`, `prune`, `shake` | The same names in `advanced` | ### Pi settings that also apply -These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block, next to the `contextKit` block. +These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` block of Pi's `settings.json`. | Pi setting | Default | Effect on pi-context-kit | | --- | --- | --- | @@ -495,61 +305,29 @@ These settings belong to Pi, not to pi-context-kit. Put them in the `compaction` | `compaction.keepRecentTokens` | `20000` | After a handoff note, approximately this number of the newest tokens stays unchanged. | | `compaction.modelOverrides` | none | Changes `reserveTokens` and `keepRecentTokens` for one model. | -pi-context-kit has no setting per model. To start earlier for one model only, make Pi's limit smaller for this model with `compaction.modelOverrides`. pi-context-kit always starts at Pi's limit or before, so it also starts earlier for this model. - -Example: all models start at 150,000 tokens. One model with a 200,000-token window starts at 200,000 − 80,000 = 120,000 tokens. Replace `provider/model-id` with the ID of your model. - -```json -{ - "compaction": { - "modelOverrides": { - "provider/model-id": { "reserveTokens": 80000 } - } - }, - "contextKit": { - "thresholdTokens": 150000 - } -} -``` - -Pi also uses `reserveTokens` to limit the length of its own summary. See the Pi documentation about compaction. - -The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`. +pi-context-kit has no setting per model. To start earlier for one model only, make Pi's limit smaller for this model with `compaction.modelOverrides`, for example `{ "compaction": { "modelOverrides": { "provider/model-id": { "reserveTokens": 80000 } } } }`. With a 200,000-token window, this model then starts at 120,000 tokens at the latest. The model key must be the exact `provider/modelId`. To see the IDs, type `pi --list-models`. ## Recipes -| I want to... | Settings | +| I want to... | `context-kit.json` | | --- | --- | -| Start earlier with large models | `{ "contextKit": { "thresholdTokens": 150000 } }` | -| Use the same proportion for all models | `{ "contextKit": { "thresholdPercent": 75 } }` | -| Never write a handoff note | `{ "contextKit": { "methodOrder": ["shake", "soft"] } }` | -| Try the free method first, then a handoff note | `{ "contextKit": { "methodOrder": ["shake", "handoff", "soft"] } }` | -| Keep more recent tool outputs | `{ "contextKit": { "prune": { "protectTokens": 80000 } } }` | -| Keep all old file copies | `{ "contextKit": { "supersedeReads": false } }` | -| Use other settings in one project | Put the `contextKit` block in `.pi/settings.json` in that project. | -| Turn pi-context-kit off, but keep `recall` | `{ "contextKit": { "enabled": false } }` | - -To combine recipes, put all the settings in one `contextKit` block: - -```json -{ - "contextKit": { - "thresholdTokens": 150000, - "methodOrder": ["shake", "handoff", "soft"], - "prune": { "protectTokens": 80000 } - } -} -``` +| Start later, at Pi's own limit | `{ "threshold": "pi" }` | +| Start at the same number of tokens on all models | `{ "threshold": 150000 }` | +| Avoid model requests when possible | `{ "strategy": "frugal" }` | +| Never write a handoff note | `{ "advanced": { "methodOrder": ["shake", "soft"] } }` | +| Keep more recent tool outputs | `{ "advanced": { "prune": { "protectTokens": 80000 } } }` | +| Keep all old file copies | `{ "advanced": { "supersedeReads": false } }` | +| Turn pi-context-kit off, but keep `recall` | `{ "enabled": false }`, or `/context-kit` | ## Limits - **Pi still has its own limit.** Pi compacts when the context reaches the context window minus `compaction.reserveTokens` (default 16,384). pi-context-kit can only start earlier, not later. You set Pi's limit with `compaction.reserveTokens` and `compaction.modelOverrides`. - **A threshold is not a guarantee.** At the threshold, pi-context-kit tries to make the context smaller. If one tool output is very large, or the summary request fails, the methods can fail. Then Pi compacts at its own limit. - **Token counts are estimates.** pi-context-kit uses Pi's estimates. The real count of the provider can be different. -- **If Pi's compaction is off** (`compaction.enabled: false`), pi-context-kit changes the context only when you run `/compact`. Then it writes a handoff note, as with compaction on. `thresholdTokens` and `thresholdPercent` are ignored, because pi-context-kit edits the context automatically only at a threshold. +- **If Pi's compaction is off** (`compaction.enabled: false`), pi-context-kit changes the context only when you run `/compact`. Then it writes a handoff note, as with compaction on. `threshold` is ignored, because pi-context-kit edits the context automatically only at a threshold. - **Manual compaction and errors.** When you type `/compact`, when the context is too large for the model, or when Pi compacts before a turn, `shake` cannot run. pi-context-kit uses a ready handoff note, or Pi's summary. -- **`methodOrder` stops at `soft`.** The methods after `soft` do not run. -- **Subagents** use their own settings. They show no warnings, because they have no screen. +- **The method order stops at `soft`.** The methods after `soft` do not run. +- **Subagents** read the same settings files. They show no warnings and no status, because they have no screen. ## FAQ diff --git a/context-kit.schema.json b/context-kit.schema.json new file mode 100644 index 0000000..c934981 --- /dev/null +++ b/context-kit.schema.json @@ -0,0 +1,106 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://unpkg.com/pi-context-kit/context-kit.schema.json", + "title": "pi-context-kit settings", + "description": "~/.pi/agent/context-kit.json, or .pi/context-kit.json in a trusted project.", + "type": "object", + "additionalProperties": false, + "properties": { + "$schema": { "type": "string" }, + "enabled": { + "description": "false stops context maintenance and handoff notes. recall stays available.", + "type": "boolean", + "default": true + }, + "threshold": { + "description": "Where maintenance starts: a number of tokens, a share of the context window such as \"75%\", or \"pi\" for Pi's own compaction threshold.", + "default": "75%", + "oneOf": [ + { "type": "integer", "minimum": 1 }, + { "type": "string", "pattern": "^(0*100(\\.0+)?|0*[1-9]\\d?(\\.\\d+)?|0+\\.\\d*[1-9]\\d*)%$" }, + { "const": "pi" } + ] + }, + "strategy": { + "description": "balanced: handoff note written in the background, then shake, then Pi's summary. frugal: shake first, no background calls. pi-summary: Pi's summary only.", + "enum": ["balanced", "frugal", "pi-summary"], + "default": "balanced" + }, + "advanced": { + "type": "object", + "additionalProperties": false, + "properties": { + "methodOrder": { + "description": "Replaces the method order of the strategy. Methods after \"soft\" never run.", + "type": "array", + "items": { "enum": ["handoff", "shake", "soft"] } + }, + "background": { + "description": "Write the handoff note in the background before the threshold. The strategy sets the default.", + "type": "boolean" + }, + "supersedeReads": { + "description": "Replace an older read of a file that was read again.", + "type": "boolean", + "default": true + }, + "progressRatio": { + "description": "Each method must bring the context to this fraction of the threshold, or the next method runs.", + "type": "number", + "exclusiveMinimum": 0, + "maximum": 1, + "default": 0.8 + }, + "prune": { + "type": "object", + "additionalProperties": false, + "properties": { + "enabled": { "type": "boolean", "default": true }, + "protectTokens": { + "description": "The newest tool outputs, up to this many tokens, are never pruned.", + "type": "integer", + "minimum": 0, + "default": 40000 + }, + "minSavings": { + "description": "Prune only when this many tokens or more are removed.", + "type": "integer", + "minimum": 0, + "default": 20000 + }, + "minTokens": { + "description": "Tool outputs smaller than this are never pruned.", + "type": "integer", + "minimum": 0, + "default": 50 + } + } + }, + "shake": { + "type": "object", + "additionalProperties": false, + "properties": { + "protectTokens": { + "description": "The newest context, up to this many tokens, is never shaken.", + "type": "integer", + "minimum": 0, + "default": 16000 + }, + "minSavings": { + "description": "Shake only when this many tokens or more are removed.", + "type": "integer", + "minimum": 0, + "default": 4000 + }, + "blockMinTokens": { + "description": "Code and XML blocks smaller than this are never shaken.", + "type": "integer", + "minimum": 0, + "default": 400 + } + } + } + } + } + } +} diff --git a/extensions/index.ts b/extensions/index.ts index 6a85379..dab3a94 100644 --- a/extensions/index.ts +++ b/extensions/index.ts @@ -1,4 +1,6 @@ +import { existsSync } from "node:fs"; import { type Api, type Message, type Model } from "@earendil-works/pi-ai"; +import { Container, SettingsList, Text } from "@earendil-works/pi-tui"; import { Type } from "typebox"; import { convertToLlm, @@ -7,11 +9,14 @@ import { type ExtensionContext, findCutPoint, generateSummaryWithUsage, + getAgentDir, getLatestCompactionEntry, + getSettingsListTheme, type ProjectedSessionEntry, type SessionBeforeCompactEvent, type SessionEntry, SettingsManager, + type Theme, } from "@earendil-works/pi-coding-agent"; import { BackgroundHandoff, @@ -20,11 +25,12 @@ import { type Note, } from "../src/background.ts"; import { + before, type ContextKitConfig, - type Method, ownThreshold, readConfig, speculationLead, + writesHandoff, } from "../src/config.ts"; import { applyEdits, @@ -36,26 +42,48 @@ import { import { handoffSummary } from "../src/handoff.ts"; import { type MaintenancePlan, planMaintenance } from "../src/maintain.ts"; import { requestNote } from "../src/note.ts"; +import { migrateLegacy, migrateProject } from "../src/migrate.ts"; import { readEntry, searchEntries } from "../src/recall.ts"; +import { panelItems, settingValue, summaryText } from "../src/panel.ts"; +import { + createSettings, + loadSettings, + readSettingsFile, + saveSetting, + settingsPaths, +} from "../src/settings-file.ts"; +import { freedNotice, statusText } from "../src/status.ts"; // One closure per session: Pi and pi-subagents load the extension once per session in the same process. export default function contextKit(pi: ExtensionAPI): void { - const background = new BackgroundHandoff(); + /** The latest context, so a background note that finishes between turns updates the status. */ + let statusContext: ExtensionContext | undefined; + const background = new BackgroundHandoff(() => { + if (!statusContext) return; + try { + showStatus(statusContext); + } catch { + // Pi throws on a ctx of a replaced session, which has no footer left to update. + statusContext = undefined; + } + }); let reported = ""; /** The compaction epoch in which a threshold note failed, so it is not retried every turn. */ let failedEpoch: string | null | undefined; /** The same for Pi's summary at the extension's own threshold. */ let softFailedEpoch: string | null | undefined; - /** Reads `contextKit` from Pi's settings on each use, so `/reload` and project settings apply. */ + const paths = (ctx: ExtensionContext) => + settingsPaths(getAgentDir(), ctx.cwd, ctx.isProjectTrusted()); + + /** Reads the settings files on each use, so a change applies at the next turn. */ const settings = (ctx: ExtensionContext): ContextKitConfig => { - const { config, problems } = readConfig( - Reflect.get(pi.getSettings(), "contextKit"), - ); - const message = problems.join("; "); + const files = loadSettings(paths(ctx)); + const { config, problems } = readConfig(files.raw); + const message = [...files.problems, ...problems].join("; "); if (message && message !== reported) ctx.ui.notify( - `pi-context-kit: invalid settings, defaults used (${message}).`, + `pi-context-kit settings need attention: ${message}. Type /context-kit to see them.`, "warning", ); reported = message; @@ -93,6 +121,48 @@ export default function contextKit(pi: ExtensionAPI): void { const epoch = (branch: SessionEntry[]) => getLatestCompactionEntry(branch)?.id ?? null; + const statusOf = ( + ctx: ExtensionContext, + config: ContextKitConfig, + tokens: number, + ) => { + if (!config.enabled) return "Context cleanup off"; + const model = ctx.model; + if (!model || model.contextWindow <= 0) return undefined; + return statusText({ + tokens, + limit: threshold(model, config), + contextWindow: model.contextWindow, + note: background.noteState(epoch(ctx.sessionManager.getBranch())), + }); + }; + + function showStatus( + ctx: ExtensionContext, + config = settings(ctx), + tokens = liveTokens(ctx), + ) { + statusContext = ctx; + ctx.ui.setStatus("context-kit", statusOf(ctx, config, tokens)); + } + + /** Pi shows compactions but not context edits, so the user learns about them here. */ + const persist = (turn: Turn) => { + const output = persisted(turn.result, turn.limit); + // Both counts use the same estimate; Pi's usage count is not comparable. + const count = (edits: MaintenancePlan["edits"]) => + contextTokens(projectedMessages(applyEdits(turn.entries, edits))); + // Maintenance needs a model with a context window, so `window` is set whenever `output` is. + const window = turn.ctx.model?.contextWindow; + if (output && window) + turn.ctx.ui.notify( + freedNotice(count([]), count(turn.result.edits), window), + "info", + ); + showStatus(turn.ctx, turn.config, turn.result.tokens); + return output; + }; + const warn = ( ctx: ExtensionContext, error: unknown, @@ -227,7 +297,7 @@ export default function contextKit(pi: ExtensionAPI): void { messages: () => Message[], ) => { const { ctx, config, model, limit, result } = turn; - if (!config.asyncEnabled || !keptEntryId) return; + if (!config.background || !keptEntryId) return; if (result.tokens <= limit - speculationLead(limit)) return; if (result.tokens > limit) return; const budget = Math.floor( @@ -295,7 +365,7 @@ export default function contextKit(pi: ExtensionAPI): void { } } catch (error) { if (!signal.aborted) - warn(ctx, error, "The remaining methods in methodOrder are tried."); + warn(ctx, error, "The next methods of the strategy are tried."); } failedEpoch = current; return undefined; @@ -329,7 +399,10 @@ export default function contextKit(pi: ExtensionAPI): void { pi.on("turn_end", async (event, ctx) => { const config = settings(ctx); - if (!config.enabled) return undefined; + if (!config.enabled) { + showStatus(ctx, config); + return undefined; + } const branch = ctx.sessionManager.getBranch(); const current = epoch(branch); background.invalidate(current, branch); @@ -365,7 +438,7 @@ export default function contextKit(pi: ExtensionAPI): void { const handed = before(methods, "handoff", "soft") ? await handoffAtTurn(turn) : undefined; - if (handed === "waiting") return persisted(turn.result, limit); + if (handed === "waiting") return persist(turn); if (handed) return handed; if ( turn.result.tokens > limit && @@ -373,7 +446,7 @@ export default function contextKit(pi: ExtensionAPI): void { before(methods, "shake", "soft") ) turn.result = plan(true); - return (await softAtTurn(turn)) ?? persisted(turn.result, limit); + return (await softAtTurn(turn)) ?? persist(turn); }); const handoffBeforeCompact = async ( @@ -429,9 +502,132 @@ export default function contextKit(pi: ExtensionAPI): void { pi.on("session_tree", (_event, ctx) => { const branch = ctx.sessionManager.getBranch(); background.invalidate(epoch(branch), branch); + showStatus(ctx); + }); + /** Writes the 0.3 settings of each scope to its own file, unless that file exists. */ + const migrate = (ctx: ExtensionContext) => { + const { global, project } = paths(ctx); + const piSettings = SettingsManager.create(ctx.cwd, getAgentDir(), { + projectTrusted: ctx.isProjectTrusted(), + }); + // Pi reports its own unreadable settings. The project file depends on the global block, so + // neither moves until Pi reads both. + if (piSettings.drainErrors().length > 0) return; + const oldGlobal: unknown = Reflect.get( + piSettings.getGlobalSettings(), + "contextKit", + ); + const oldProject: unknown = Reflect.get( + piSettings.getProjectSettings(), + "contextKit", + ); + const scopes = [ + { old: oldGlobal, file: global, content: () => migrateLegacy(oldGlobal) }, + { + old: oldProject, + file: project, + // Runs after the global file is written, which the project file then overrides. + content: () => + migrateProject(oldGlobal, oldProject, readSettingsFile(global)), + }, + ]; + for (const { old, file, content } of scopes) { + if (old === undefined || !file) continue; + try { + if (!createSettings(file, content())) continue; + } catch (error) { + warn(ctx, error, "Defaults apply until it works.", `saving ${file}`); + // The project file depends on the global file, so both wait for the next start. + return; + } + ctx.ui.notify( + `pi-context-kit moved its settings to ${file}. The "contextKit" entry in Pi's settings.json is no longer used.`, + "info", + ); + } + }; + + pi.on("session_start", (_event, ctx) => { + migrate(ctx); + showStatus(ctx); + }); + // A compaction returned from turn_end emits no session_compact. + pi.on("agent_end", (_event, ctx) => showStatus(ctx)); + pi.on("session_compact", (_event, ctx) => { + background.cancel(); + showStatus(ctx); + }); + pi.on("session_shutdown", () => { + background.cancel(); + statusContext = undefined; + }); + + /** Returns whether the setting was saved. */ + const choose = (ctx: ExtensionContext, id: string, value: string) => { + try { + saveSetting(paths(ctx), id, settingValue(id, value)); + return true; + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + ctx.ui.notify(`pi-context-kit: ${message}`, "error"); + return false; + } finally { + showStatus(ctx); + } + }; + + const panelHeader = (ctx: ExtensionContext, theme: Theme) => { + const status = statusOf(ctx, settings(ctx), liveTokens(ctx)) ?? ""; + const { global, project } = paths(ctx); + const files = + project && existsSync(project) + ? `${global}, and for this project ${project}` + : global; + return `${theme.fg("accent", theme.bold("pi-context-kit"))} ${status}\n${theme.fg("dim", `Saved in ${files}`)}`; + }; + + pi.registerCommand("context-kit", { + description: "Show and change pi-context-kit settings", + handler: async (_args, ctx) => { + // The settings warning points here, so it shows again. + reported = ""; + const config = settings(ctx); + if (ctx.mode !== "tui") { + ctx.ui.notify(summaryText(config, paths(ctx).global), "info"); + return; + } + await ctx.ui.custom((tui, theme, _keybindings, done) => { + const items = panelItems(config); + const saved = new Map( + items.map((item) => [item.id, item.currentValue]), + ); + const header = new Text(panelHeader(ctx, theme)); + const list = new SettingsList( + items, + items.length, + getSettingsListTheme(), + (id, value) => { + // The list shows the new value before this runs. + if (choose(ctx, id, value)) saved.set(id, value); + else list.updateValue(id, saved.get(id) ?? value); + header.setText(panelHeader(ctx, theme)); + }, + () => done(undefined), + ); + const container = new Container(); + container.addChild(header); + container.addChild(list); + return { + render: (width: number) => container.render(width), + invalidate: () => container.invalidate(), + handleInput: (data: string) => { + list.handleInput(data); + tui.requestRender(); + }, + }; + }); + }, }); - pi.on("session_compact", () => background.cancel()); - pi.on("session_shutdown", () => background.cancel()); pi.registerTool({ name: "recall", @@ -519,7 +715,11 @@ function currentTokens( } function handoffEnabled(config: ContextKitConfig): boolean { - return config.enabled && before(config.methodOrder, "handoff", "soft"); + return config.enabled && writesHandoff(config.methodOrder); +} + +function liveTokens(ctx: ExtensionContext): number { + return ctx.getContextUsage()?.tokens ?? contextTokens(liveMessages(ctx)); } function liveMessages(ctx: ExtensionContext): Message[] { @@ -551,18 +751,6 @@ function fits( return Math.ceil(summary.length / 4) + kept <= limit * ratio; } -/** Soft ends the extension's strategy chain, even when other methods follow it. */ -function before(methods: readonly Method[], a: Method, b: Method): boolean { - const index = methods.indexOf(a); - const other = methods.indexOf(b); - const soft = methods.indexOf("soft"); - const stop = Math.min( - other >= 0 ? other : Number.POSITIVE_INFINITY, - soft >= 0 ? soft : Number.POSITIVE_INFINITY, - ); - return index >= 0 && index < stop; -} - /** Finds the retained boundary from model-visible entries, including prior compaction tails and edits. */ function recentStart( ctx: ExtensionContext, diff --git a/package-lock.json b/package-lock.json index e362c11..f103dea 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,6 +11,7 @@ "devDependencies": { "@earendil-works/pi-ai": "^1.5.2", "@earendil-works/pi-coding-agent": "^1.5.2", + "@earendil-works/pi-tui": "^1.5.2", "@types/node": "^26.6.4", "eslint": "^10.14.0", "typebox": "^1.3.27", @@ -23,6 +24,7 @@ "peerDependencies": { "@earendil-works/pi-ai": "*", "@earendil-works/pi-coding-agent": "*", + "@earendil-works/pi-tui": "*", "typebox": "*" } }, diff --git a/package.json b/package.json index 2f41372..e717469 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,8 @@ ], "files": [ "extensions", - "src" + "src", + "context-kit.schema.json" ], "engines": { "node": ">=22.19.0" @@ -48,11 +49,13 @@ "peerDependencies": { "@earendil-works/pi-ai": "*", "@earendil-works/pi-coding-agent": "*", + "@earendil-works/pi-tui": "*", "typebox": "*" }, "devDependencies": { "@earendil-works/pi-ai": "^1.5.2", "@earendil-works/pi-coding-agent": "^1.5.2", + "@earendil-works/pi-tui": "^1.5.2", "@types/node": "^26.6.4", "eslint": "^10.14.0", "typebox": "^1.3.27", diff --git a/src/background.ts b/src/background.ts index 50e42d5..23de0c1 100644 --- a/src/background.ts +++ b/src/background.ts @@ -18,11 +18,19 @@ interface Job { controller: AbortController; note: Promise; settled: boolean; + /** Whether the job settled with a note. */ + ready: boolean; } /** One speculative handoff note per compaction epoch, written while the agent keeps working. */ export class BackgroundHandoff { #job: Job | undefined; + readonly #onSettle: () => void; + + /** `onSettle` runs when the current job finishes, with or without a note. */ + constructor(onSettle: () => void = () => {}) { + this.#onSettle = onSettle; + } /** Starts a job unless one already ran in this epoch. */ start( @@ -39,10 +47,23 @@ export class BackgroundHandoff { if (!controller.signal.aborted) onError(error); return undefined; }) - .finally(() => { + .then((result) => { job.settled = true; + job.ready = result !== undefined; + return result; }); - const job: Job = { epoch, leafId, controller, note, settled: false }; + // Apart from `note`, so the listener cannot fail the note. The listener must not throw. + void note.then(() => { + if (this.#job === job) this.#onSettle(); + }); + const job: Job = { + epoch, + leafId, + controller, + note, + settled: false, + ready: false, + }; this.#job = job; return true; } @@ -52,6 +73,14 @@ export class BackgroundHandoff { return this.#job?.epoch === epoch && !this.#job.settled; } + /** The background note of this epoch, for the status line. */ + noteState(epoch: string | null): "writing" | "ready" | undefined { + const job = this.#job; + if (job?.epoch !== epoch) return undefined; + if (!job.settled) return "writing"; + return job.ready ? "ready" : undefined; + } + /** Returns a finished note only when it still covers a prefix of the branch. */ async takeReady( epoch: string | null, diff --git a/src/config.ts b/src/config.ts index 248c1d9..7128fac 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1,41 +1,53 @@ import type { PruneOptions } from "./prune.ts"; import type { ShakeOptions } from "./shake.ts"; +/** Where maintenance starts. `"pi"` leaves only Pi's own compaction threshold. */ +export type Threshold = { tokens: number } | { percent: number } | "pi"; + +/** + * `handoff`: compact with a note written by the session model. + * `shake`: elide large blocks and images from older messages, without a model call. + * `soft`: leave compaction to Pi's own summary. + */ +export type Method = "handoff" | "shake" | "soft"; + +/** Named method orders, so most users never edit `advanced.methodOrder`. */ +export type Strategy = "balanced" | "frugal" | "pi-summary"; + +export const STRATEGIES: Readonly< + Record +> = { + balanced: { methodOrder: ["handoff", "shake", "soft"], background: true }, + frugal: { methodOrder: ["shake", "handoff", "soft"], background: false }, + "pi-summary": { methodOrder: ["soft"], background: false }, +}; + export interface ContextKitConfig { /** Turns off maintenance and handoff compaction. `recall` stays available. */ enabled: boolean; - /** Compact above this many tokens. -1 uses `thresholdPercent`. Overrides `thresholdPercent`. */ - thresholdTokens: number; - /** Compact above this percentage of the context window. -1 uses Pi's threshold only. */ - thresholdPercent: number; + threshold: Threshold; + strategy: Strategy; /** What to try, in order, when the context stays above the threshold after pruning. */ methodOrder: Method[]; + /** `advanced.methodOrder` sets the method order, so `strategy` does not. */ + customOrder: boolean; + /** Write the handoff note in the background before the threshold. */ + background: boolean; /** Replace older reads of a file that was read again. */ supersedeReads: boolean; prune: PruneOptions & { enabled: boolean }; shake: ShakeOptions; /** Pruning and shaking must reach this fraction of the threshold, or compaction runs instead. */ progressRatio: number; - /** Write the handoff note in the background before the threshold. */ - asyncEnabled: boolean; } -/** - * `handoff`: compact with a note written by the session model. - * `shake`: elide large blocks and images from older messages, without a model call. - * `soft`: leave compaction to Pi's own summary. - */ -export type Method = "handoff" | "shake" | "soft"; - -const METHODS: readonly Method[] = ["handoff", "shake", "soft"]; -/** Methods that oh-my-pi offers and Pi lacks. They are skipped like methods that are unavailable. */ -const UNAVAILABLE: readonly unknown[] = ["remote", "snapcompact"]; - export const DEFAULT_CONFIG: ContextKitConfig = { enabled: true, - thresholdTokens: -1, - thresholdPercent: -1, - methodOrder: [...METHODS], + threshold: { percent: 75 }, + strategy: "balanced", + methodOrder: [...STRATEGIES.balanced.methodOrder], + customOrder: false, + background: STRATEGIES.balanced.background, supersedeReads: true, prune: { enabled: true, @@ -49,162 +61,224 @@ export const DEFAULT_CONFIG: ContextKitConfig = { blockMinTokens: 400, }, progressRatio: 0.8, - asyncEnabled: true, }; export interface ConfigResult { config: ContextKitConfig; - /** One message per invalid value. Each invalid value keeps its default. */ + /** One message per invalid value or ineffective combination. Each invalid value keeps its default. */ problems: string[]; } -type Check = { test: (value: unknown) => value is T; must: string }; +type Check = { read: (value: unknown) => T | undefined; must: string }; const boolean: Check = { - test: (value) => typeof value === "boolean", - must: "a boolean", + read: (value) => (typeof value === "boolean" ? value : undefined), + must: "true or false", }; const count: Check = { - test: (value): value is number => - Number.isSafeInteger(value) && Number(value) >= 0, - must: "a non-negative integer", + read: (value) => + Number.isSafeInteger(value) && Number(value) >= 0 + ? Number(value) + : undefined, + must: "a whole number, 0 or more", +}; +const ratio: Check = { + read: (value) => + typeof value === "number" && value > 0 && value <= 1 ? value : undefined, + must: "a number above 0, up to 1", }; -const tokens: Check = { - test: (value): value is number => - value === -1 || (Number.isSafeInteger(value) && Number(value) > 0), - must: "-1 or a positive integer", +const threshold: Check = { + read: parseThreshold, + must: 'a positive integer (tokens), a percentage such as "75%", or "pi"', }; -const percent: Check = { - test: (value): value is number => - value === -1 || (typeof value === "number" && value > 0 && value <= 100), - must: "-1 or a number in (0, 100]", +export const isStrategy = (value: unknown): value is Strategy => + value === "balanced" || value === "frugal" || value === "pi-summary"; +const strategy: Check = { + read: (value) => (isStrategy(value) ? value : undefined), + must: '"balanced", "frugal" or "pi-summary"', }; -const ratio: Check = { - test: (value): value is number => - typeof value === "number" && value > 0 && value <= 1, - must: "a number in (0, 1]", +export const isMethod = (value: unknown): value is Method => + value === "handoff" || value === "shake" || value === "soft"; +const methodOrder: Check = { + read: (value) => + Array.isArray(value) && value.every(isMethod) + ? [...new Set(value)] + : undefined, + must: 'a list of "handoff", "shake" and "soft"', }; -const isMethod = (value: unknown): value is Method => - METHODS.some((method) => method === value); -const methodOrder: Check = { - test: (value): value is unknown[] => - Array.isArray(value) && - value.every((method) => isMethod(method) || UNAVAILABLE.includes(method)), - must: 'an array of "handoff", "shake", "soft", "remote" or "snapcompact"', -}; +function parseThreshold(value: unknown): Threshold | undefined { + if (value === "pi") return "pi"; + if (Number.isSafeInteger(value) && Number(value) > 0) + return { tokens: Number(value) }; + const match = + typeof value === "string" ? /^(\d+(?:\.\d+)?)%$/.exec(value) : null; + const percent = Number(match?.[1]); + return percent > 0 && percent <= 100 ? { percent } : undefined; +} /** Reads the keys of one settings object and reports invalid or unknown keys. */ class Section { readonly #raw: Record; - readonly #path: string; + readonly #prefix: string; readonly #problems: string[]; readonly #known = new Set(); constructor(raw: unknown, path: string, problems: string[]) { - this.#path = path; + this.#prefix = path ? `${path}.` : ""; this.#problems = problems; + // Editors read `$schema` at the root of the file only. + if (!path) this.#known.add("$schema"); if (raw === undefined || isRecord(raw)) this.#raw = raw ?? {}; else { - problems.push(`${path} must be an object`); + problems.push( + `${path || "the settings"} must be an object (default used)`, + ); this.#raw = {}; } } + /** Whether the key holds a valid value, so the default was not used. */ + provides(key: string, check: Check): boolean { + return check.read(this.#raw[key]) !== undefined; + } + get(key: string, check: Check, fallback: T): T { this.#known.add(key); const value = this.#raw[key]; if (value === undefined) return fallback; - if (check.test(value)) return value; - this.#problems.push(`${this.#path}.${key} must be ${check.must}`); + const parsed = check.read(value); + if (parsed !== undefined) return parsed; + this.#problems.push( + `${this.#prefix}${key} must be ${check.must} (default used)`, + ); return fallback; } section(key: string): Section { this.#known.add(key); - return new Section(this.#raw[key], `${this.#path}.${key}`, this.#problems); + return new Section(this.#raw[key], `${this.#prefix}${key}`, this.#problems); } /** Reports keys that no `get` or `section` call read. Call it last. */ done(): void { for (const key of Object.keys(this.#raw)) if (!this.#known.has(key)) - this.#problems.push(`${this.#path}.${key} is not a setting`); + this.#problems.push(`${this.#prefix}${key} is not a setting`); } } -/** Validates the `contextKit` value of Pi's settings. */ +/** Validates the merged contents of the settings files. */ export function readConfig(raw: unknown): ConfigResult { const problems: string[] = []; const d = DEFAULT_CONFIG; - const root = new Section(raw, "contextKit", problems); + const root = new Section(raw, "", problems); const enabled = root.get("enabled", boolean, d.enabled); - const thresholdTokens = root.get( - "thresholdTokens", - tokens, - d.thresholdTokens, + const limit = root.get("threshold", threshold, d.threshold); + const named = root.get("strategy", strategy, d.strategy); + const a = root.section("advanced"); + const methods = a.get( + "methodOrder", + methodOrder, + STRATEGIES[named].methodOrder, ); - const thresholdPercent = root.get( - "thresholdPercent", - percent, - d.thresholdPercent, - ); - const methods = root.get("methodOrder", methodOrder, d.methodOrder); - const supersedeReads = root.get("supersedeReads", boolean, d.supersedeReads); - const progressRatio = root.get("progressRatio", ratio, d.progressRatio); - - const p = root.section("prune"); - const prune = { - enabled: p.get("enabled", boolean, d.prune.enabled), - protectTokens: p.get("protectTokens", count, d.prune.protectTokens), - minSavings: p.get("minSavings", count, d.prune.minSavings), - minTokens: p.get("minTokens", count, d.prune.minTokens), - }; - p.done(); - - const s = root.section("shake"); - const shake = { - protectTokens: s.get("protectTokens", count, d.shake.protectTokens), - minSavings: s.get("minSavings", count, d.shake.minSavings), - blockMinTokens: s.get("blockMinTokens", count, d.shake.blockMinTokens), - }; - s.done(); - - const asyncEnabled = root.get("asyncEnabled", boolean, d.asyncEnabled); + const background = a.get("background", boolean, STRATEGIES[named].background); + const supersedeReads = a.get("supersedeReads", boolean, d.supersedeReads); + const progressRatio = a.get("progressRatio", ratio, d.progressRatio); + const prune = readPrune(a.section("prune")); + const shake = readShake(a.section("shake")); + a.done(); root.done(); + const customOrder = a.provides("methodOrder", methodOrder); + if (root.provides("strategy", strategy) && customOrder) + problems.push( + `strategy "${named}" does not set the method order, because advanced.methodOrder replaces it`, + ); + if ( + customOrder && + a.provides("background", boolean) && + background && + !writesHandoff(methods) + ) + problems.push( + 'advanced.background has no effect, because "handoff" is not before "soft" in the method order', + ); + return { config: { enabled, - thresholdTokens, - thresholdPercent, - methodOrder: [...new Set(methods.filter(isMethod))], + threshold: limit, + strategy: named, + methodOrder: [...methods], + customOrder, + background, supersedeReads, prune, shake, progressRatio, - asyncEnabled, }, problems, }; } +function readPrune(p: Section): ContextKitConfig["prune"] { + const d = DEFAULT_CONFIG.prune; + const prune = { + enabled: p.get("enabled", boolean, d.enabled), + protectTokens: p.get("protectTokens", count, d.protectTokens), + minSavings: p.get("minSavings", count, d.minSavings), + minTokens: p.get("minTokens", count, d.minTokens), + }; + p.done(); + return prune; +} + +function readShake(s: Section): ShakeOptions { + const d = DEFAULT_CONFIG.shake; + const shake = { + protectTokens: s.get("protectTokens", count, d.protectTokens), + minSavings: s.get("minSavings", count, d.minSavings), + blockMinTokens: s.get("blockMinTokens", count, d.blockMinTokens), + }; + s.done(); + return shake; +} + export function isRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } +/** Soft ends the extension's strategy chain, even when other methods follow it. */ +export function before( + methods: readonly Method[], + a: Method, + b: Method, +): boolean { + const index = methods.indexOf(a); + const other = methods.indexOf(b); + const soft = methods.indexOf("soft"); + const stop = Math.min( + other >= 0 ? other : Number.POSITIVE_INFINITY, + soft >= 0 ? soft : Number.POSITIVE_INFINITY, + ); + return index >= 0 && index < stop; +} + +/** Whether the method order writes handoff notes at all. */ +export function writesHandoff(methods: readonly Method[]): boolean { + return before(methods, "handoff", "soft"); +} + /** The configured threshold for this context window, or +Infinity when only Pi's threshold applies. */ export function ownThreshold( config: ContextKitConfig, contextWindow: number, ): number { - if (config.thresholdTokens > 0) - return Math.min(contextWindow - 1, config.thresholdTokens); - if (config.thresholdPercent > 0) - return Math.floor( - (contextWindow * Math.min(99, config.thresholdPercent)) / 100, - ); - return Number.POSITIVE_INFINITY; + const value = config.threshold; + if (value === "pi") return Number.POSITIVE_INFINITY; + if ("tokens" in value) return Math.min(contextWindow - 1, value.tokens); + return Math.floor((contextWindow * Math.min(99, value.percent)) / 100); } /** diff --git a/src/migrate.ts b/src/migrate.ts new file mode 100644 index 0000000..5920357 --- /dev/null +++ b/src/migrate.ts @@ -0,0 +1,135 @@ +import { + isMethod, + isRecord, + isStrategy, + type Method, + STRATEGIES, + type Strategy, + writesHandoff, +} from "./config.ts"; +import { mergeSettings } from "./settings-file.ts"; + +const NAMES = Object.keys(STRATEGIES).filter(isStrategy); + +/** Keys 0.3 had at the top level that 0.4 keeps under `advanced`, unchanged. */ +const ADVANCED = ["supersedeReads", "progressRatio", "prune", "shake"]; + +/** + * Converts the 0.3 `contextKit` block of Pi's settings into the content of `context-kit.json` + * with the same behavior. An invalid threshold or method order is dropped, so its default applies, + * as in 0.3. Other values are copied, so the usual checks report an invalid one. + */ +export function migrateLegacy(legacy: unknown): Record { + const old = isRecord(legacy) ? legacy : {}; + const result: Record = {}; + if (typeof old.enabled === "boolean") result.enabled = old.enabled; + result.threshold = threshold(old); + const advanced = copyAdvanced(old); + const { strategy, order, background } = methods(old); + if (strategy && strategy !== "balanced") result.strategy = strategy; + if (!strategy) advanced.methodOrder = order; + if ( + writesHandoff(order) && + background !== STRATEGIES[strategy ?? "balanced"].background + ) + advanced.background = background; + return withAdvanced(result, advanced); +} + +/** + * Converts the 0.3 project block, which Pi merged over the global block. It writes only what the + * project block sets, with the values of the merged block, and overrides `globalFile` where that + * changes the method order or background. + */ +export function migrateProject( + globalLegacy: unknown, + projectLegacy: unknown, + globalFile: Record, +): Record { + const project = isRecord(projectLegacy) ? projectLegacy : {}; + const merged = mergeSettings( + isRecord(globalLegacy) ? globalLegacy : {}, + project, + ); + const result: Record = {}; + if (typeof project.enabled === "boolean") result.enabled = project.enabled; + if ("thresholdTokens" in project || "thresholdPercent" in project) + result.threshold = threshold(merged); + const advanced = copyAdvanced(project); + if ("methodOrder" in project || "asyncEnabled" in project) { + const over = projectMethods(merged, globalFile); + if (over.strategy) result.strategy = over.strategy; + Object.assign(advanced, over.advanced); + } + return withAdvanced(result, advanced); +} + +/** The method settings of the merged block, written so that they override `globalFile`. */ +function projectMethods( + merged: Record, + globalFile: Record, +): { strategy?: Strategy; advanced: Record } { + const { strategy, order, background } = methods(merged); + const globalAdvanced = isRecord(globalFile.advanced) + ? globalFile.advanced + : {}; + const advanced: Record = {}; + // false avoids the "no effect" warning for a global background that this order does not use. + if (writesHandoff(order) || "background" in globalAdvanced) + advanced.background = writesHandoff(order) && background; + if (strategy && !("methodOrder" in globalAdvanced)) + return { strategy, advanced }; + return { advanced: { methodOrder: order, ...advanced } }; +} + +/** The strategy with the same method order, if any, and the background setting of 0.3. */ +function methods(old: Record): { + strategy: Strategy | undefined; + order: Method[]; + background: boolean; +} { + const order = methodOrder(old.methodOrder); + return { + strategy: NAMES.find((name) => same(STRATEGIES[name].methodOrder, order)), + order, + background: typeof old.asyncEnabled === "boolean" ? old.asyncEnabled : true, + }; +} + +function copyAdvanced(old: Record): Record { + const advanced: Record = {}; + for (const key of ADVANCED) if (key in old) advanced[key] = old[key]; + return advanced; +} + +function withAdvanced( + result: Record, + advanced: Record, +): Record { + return Object.keys(advanced).length > 0 ? { ...result, advanced } : result; +} + +/** 0.3 used `thresholdTokens` when both thresholds were set. */ +function threshold(old: Record): number | string { + const tokens = old.thresholdTokens; + if (Number.isSafeInteger(tokens) && Number(tokens) > 0) return Number(tokens); + const percent = old.thresholdPercent; + if (typeof percent === "number" && percent > 0 && percent <= 100) + return `${percent}%`; + return "pi"; +} + +/** 0.3 skipped "remote" and "snapcompact", which 0.4 rejects, and used the default for other values. */ +function methodOrder(value: unknown): Method[] { + const known = Array.isArray(value) + ? value.filter((method) => method !== "remote" && method !== "snapcompact") + : undefined; + if (known?.every(isMethod)) return [...new Set(known)]; + return [...STRATEGIES.balanced.methodOrder]; +} + +function same(a: readonly Method[], b: readonly Method[]): boolean { + return ( + a.length === b.length && a.every((method, index) => method === b[index]) + ); +} diff --git a/src/panel.ts b/src/panel.ts new file mode 100644 index 0000000..3a9765e --- /dev/null +++ b/src/panel.ts @@ -0,0 +1,89 @@ +import { + type ContextKitConfig, + type Strategy, + type Threshold, +} from "./config.ts"; + +/** The `SettingItem` fields of `@earendil-works/pi-tui` that the panel uses. */ +export interface PanelItem { + id: "enabled" | "threshold" | "strategy"; + label: string; + description: string; + currentValue: string; + values: string[]; +} + +const PI_LIMIT = "At Pi's limit"; +const THRESHOLDS = [ + ...[50, 60, 70, 75, 80, 90].map((percent) => `${percent}% full`), + PI_LIMIT, +]; +const METHODS: Readonly> = { + balanced: "Summary notes (recommended)", + frugal: "Trim first", + "pi-summary": "Pi's summary", +}; + +/** The settings the `/context-kit` panel edits, in plain words. The rest stay in the file. */ +export function panelItems(config: ContextKitConfig): PanelItem[] { + const threshold = thresholdText(config.threshold); + const items: PanelItem[] = [ + { + id: "enabled", + label: "Automatic cleanup", + description: + "Makes room in a long conversation so the agent keeps working. Off leaves only Pi's own cleanup.", + currentValue: config.enabled ? "On" : "Off", + values: ["On", "Off"], + }, + { + id: "threshold", + label: "Clean up when the context is", + description: + "Lower keeps answers faster and cheaper. Higher keeps more detail. At Pi's limit waits as long as Pi does.", + currentValue: threshold, + values: THRESHOLDS.includes(threshold) + ? THRESHOLDS + : [threshold, ...THRESHOLDS], + }, + ]; + if (config.customOrder) return items; + items.push({ + id: "strategy", + label: "Cleanup method", + description: + "Summary notes: the agent writes notes ahead of time and they replace old messages. Trim first: shorten large old outputs, with no extra model call. Pi's summary: Pi's own summary.", + currentValue: METHODS[config.strategy], + values: Object.values(METHODS), + }); + return items; +} + +/** The JSON value to write for a panel choice. */ +export function settingValue(id: string, value: string): unknown { + if (id === "enabled") return value === "On"; + if (id === "strategy") + return Object.entries(METHODS).find(([, label]) => label === value)?.[0]; + if (value === PI_LIMIT) return "pi"; + const tokens = /^(\d+) tokens$/.exec(value); + return tokens ? Number(tokens[1]) : value.replace(/ full$/, ""); +} + +/** One line for modes without the panel. */ +export function summaryText(config: ContextKitConfig, file: string): string { + if (!config.enabled) + return `pi-context-kit: automatic cleanup off. Settings: ${file}`; + const at = + config.threshold === "pi" ? "Pi's limit" : thresholdText(config.threshold); + const method = config.customOrder + ? `custom methods (${config.methodOrder.join(", ") || "none"})` + : METHODS[config.strategy].replace(" (recommended)", "").toLowerCase(); + return `pi-context-kit: automatic cleanup at ${at}, with ${method}. Settings: ${file}`; +} + +function thresholdText(threshold: Threshold): string { + if (threshold === "pi") return PI_LIMIT; + return "tokens" in threshold + ? `${threshold.tokens} tokens` + : `${threshold.percent}% full`; +} diff --git a/src/settings-file.ts b/src/settings-file.ts new file mode 100644 index 0000000..0d73918 --- /dev/null +++ b/src/settings-file.ts @@ -0,0 +1,153 @@ +import { + chmodSync, + existsSync, + linkSync, + mkdirSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + statSync, + writeFileSync, +} from "node:fs"; +import { dirname, join } from "node:path"; +import { isRecord } from "./config.ts"; + +const FILE_NAME = "context-kit.json"; + +export interface SettingsPaths { + global: string; + /** Undefined in an untrusted project, as Pi does for its own project settings. */ + project: string | undefined; +} + +export function settingsPaths( + agentDir: string, + cwd: string, + trusted: boolean, +): SettingsPaths { + return { + global: join(agentDir, FILE_NAME), + project: trusted ? join(cwd, ".pi", FILE_NAME) : undefined, + }; +} + +/** Merges the global and project files. A file that cannot be read is reported and ignored. */ +export function loadSettings(paths: SettingsPaths): { + raw: Record; + problems: string[]; +} { + const problems: string[] = []; + let raw: Record = {}; + for (const path of [paths.global, paths.project]) { + if (!path) continue; + try { + raw = mergeSettings(raw, readSettingsFile(path)); + } catch (error) { + problems.push(`${errorMessage(error)}, file ignored`); + } + } + return { raw, problems }; +} + +/** Sets one top-level key and keeps the rest of the file. The file is replaced atomically. */ +export function updateSetting(path: string, key: string, value: unknown) { + const next = { ...readSettingsFile(path), [key]: value }; + // The rename replaces the target, so a symbolic link, for example to dotfiles, stays. + const target = existsSync(path) ? realpathSync(path) : path; + mkdirSync(dirname(target), { recursive: true }); + const temporary = `${target}.${process.pid}.tmp`; + try { + writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`); + if (existsSync(target)) chmodSync(temporary, statSync(target).mode); + renameSync(temporary, target); + } finally { + rmSync(temporary, { force: true }); + } +} + +/** Creates the file with this content. Returns false when the file exists, which it keeps. */ +export function createSettings( + path: string, + content: Record, +): boolean { + mkdirSync(dirname(path), { recursive: true }); + const temporary = `${path}.${process.pid}.tmp`; + try { + writeFileSync(temporary, `${JSON.stringify(content, null, 2)}\n`); + // The link appears complete or not at all, and fails when the file exists, so two Pi + // processes cannot both create it. + linkSync(temporary, path); + return true; + } catch (error) { + if (isRecord(error) && error.code === "EEXIST") return false; + throw error; + } finally { + rmSync(temporary, { force: true }); + } +} + +/** + * Writes the key where it takes effect: the project file when that file sets it, otherwise the + * global file. Returns the path written. + */ +export function saveSetting( + paths: SettingsPaths, + key: string, + value: unknown, +): string { + const path = + paths.project && readSettingsFile(paths.project)[key] !== undefined + ? paths.project + : paths.global; + updateSetting(path, key, value); + return path; +} + +/** The content of one settings file, `{}` when it does not exist. Throws when it is not a JSON object. */ +export function readSettingsFile(path: string): Record { + let text: string; + try { + text = readFileSync(path, "utf8"); + } catch (error) { + if (isRecord(error) && error.code === "ENOENT") return {}; + throw new Error(`${path} cannot be read (${errorMessage(error)})`); + } + let value: unknown; + try { + value = JSON.parse(text); + } catch (error) { + throw new Error(`${path} is not valid JSON (${errorMessage(error)})`); + } + if (!isRecord(value)) throw new Error(`${path} must contain a JSON object`); + return value; +} + +/** + * Merges `over` into `base` like Pi merges project settings over global ones: objects merge key by + * key; any other value, including a list, replaces the base value. + */ +export function mergeSettings( + base: Record, + over: Record, +): Record { + const result = { ...base }; + for (const [key, value] of Object.entries(over)) { + const current = result[key]; + // A plain assignment of "__proto__" would set the prototype instead of a key. + Object.defineProperty(result, key, { + value: + isRecord(current) && isRecord(value) + ? mergeSettings(current, value) + : value, + enumerable: true, + writable: true, + configurable: true, + }); + } + return result; +} + +function errorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} diff --git a/src/status.ts b/src/status.ts new file mode 100644 index 0000000..1078646 --- /dev/null +++ b/src/status.ts @@ -0,0 +1,41 @@ +const NOTE_LABEL = { + writing: "writing summary", + ready: "summary ready", +} as const; + +export interface StatusInput { + tokens: number; + /** Where compaction starts, or +Infinity when nothing compacts. */ + limit: number; + contextWindow: number; + note?: keyof typeof NOTE_LABEL; +} + +/** The footer text: context use and threshold as shares of the window, then the background note. */ +export function statusText(input: StatusInput): string { + const share = (tokens: number) => percent(tokens, input.contextWindow); + const limit = Number.isFinite(input.limit) + ? `cleanup at ${share(input.limit)}` + : "no automatic cleanup"; + const note = input.note ? ` · ${NOTE_LABEL[input.note]}` : ""; + return `Context ${share(input.tokens)} · ${limit}${note}`; +} + +/** The notice after context edits, which Pi does not show by itself. */ +export function freedNotice( + before: number, + after: number, + contextWindow: number, +): string { + const freed = before - after; + return `pi-context-kit freed ${percent(freed, contextWindow)} of the context (${tokenCount(freed)} tokens). The agent can still look up what was removed.`; +} + +/** Rounded down, so 100% means the window is full. */ +function percent(tokens: number, contextWindow: number): string { + return `${Math.floor((tokens * 100) / contextWindow)}%`; +} + +function tokenCount(tokens: number): string { + return tokens >= 1_000 ? `${Math.round(tokens / 1_000)}k` : String(tokens); +} diff --git a/test/background.test.ts b/test/background.test.ts index 72fc404..3a06781 100644 --- a/test/background.test.ts +++ b/test/background.test.ts @@ -37,6 +37,31 @@ describe("BackgroundHandoff", () => { expect(background.writing(null)).toBe(false); }); + it.each([ + ["ready", NOTE], + [undefined, undefined], + ])( + "reports the note as %s once it settles, and tells the listener", + async (state, note) => { + const settled = vi.fn(); + const background = new BackgroundHandoff(settled); + let finish = (_: typeof NOTE | undefined) => {}; + background.start( + null, + "leaf", + () => new Promise((resolve) => (finish = resolve)), + () => {}, + ); + expect(background.noteState(null)).toBe("writing"); + expect(background.noteState("other")).toBeUndefined(); + expect(settled).not.toHaveBeenCalled(); + finish(note); + await new Promise((resolve) => setImmediate(resolve)); + expect(background.noteState(null)).toBe(state); + expect(settled).toHaveBeenCalledTimes(1); + }, + ); + it("ignores a job from another epoch or branch", async () => { const t = new Transcript(); const background = new BackgroundHandoff(); diff --git a/test/config.test.ts b/test/config.test.ts index 4194736..41fb9b8 100644 --- a/test/config.test.ts +++ b/test/config.test.ts @@ -1,33 +1,77 @@ +import { readFileSync } from "node:fs"; import { describe, expect, it } from "vitest"; import { DEFAULT_CONFIG, + isRecord, ownThreshold, readConfig, speculationLead, } from "../src/config.ts"; describe("readConfig", () => { - it("uses the defaults when the key is absent", () => { + it("uses the defaults when the value is absent", () => { expect(readConfig(undefined)).toEqual({ config: DEFAULT_CONFIG, problems: [], }); + expect(DEFAULT_CONFIG.threshold).toEqual({ percent: 75 }); + expect(DEFAULT_CONFIG.strategy).toBe("balanced"); expect(DEFAULT_CONFIG.methodOrder).toEqual(["handoff", "shake", "soft"]); + expect(DEFAULT_CONFIG.background).toBe(true); }); - it("merges valid values over the defaults, including nested ones", () => { + it.each([ + [150_000, { tokens: 150_000 }], + ["60%", { percent: 60 }], + ["72.5%", { percent: 72.5 }], + ["pi", "pi"], + ])("reads threshold %j", (threshold, expected) => { + const { config, problems } = readConfig({ threshold }); + expect(problems).toEqual([]); + expect(config.threshold).toEqual(expected); + }); + + it.each([0, -1, 1.5, "150000", "0%", "101%", "75 %", "%", true])( + "rejects threshold %j", + (threshold) => { + const { config, problems } = readConfig({ threshold }); + expect(config.threshold).toEqual(DEFAULT_CONFIG.threshold); + expect(problems).toEqual([ + 'threshold must be a positive integer (tokens), a percentage such as "75%", or "pi" (default used)', + ]); + }, + ); + + it.each([ + ["balanced", ["handoff", "shake", "soft"], true], + ["frugal", ["shake", "handoff", "soft"], false], + ["pi-summary", ["soft"], false], + ])("maps strategy %s to its methods", (strategy, methodOrder, background) => { + const { config, problems } = readConfig({ strategy }); + expect(problems).toEqual([]); + expect(config.strategy).toBe(strategy); + expect(config.methodOrder).toEqual(methodOrder); + expect(config.background).toBe(background); + }); + + it("lets advanced settings replace the strategy and the tuning defaults", () => { const { config, problems } = readConfig({ enabled: false, - thresholdTokens: 150_000, - methodOrder: ["shake", "soft"], - prune: { enabled: false, protectTokens: 10_000 }, - shake: { minSavings: 1_000 }, - progressRatio: 0.5, + advanced: { + methodOrder: ["shake", "soft", "shake"], + background: false, + supersedeReads: false, + progressRatio: 0.5, + prune: { enabled: false, protectTokens: 10_000 }, + shake: { minSavings: 1_000 }, + }, }); expect(problems).toEqual([]); expect(config.enabled).toBe(false); - expect(config.thresholdTokens).toBe(150_000); expect(config.methodOrder).toEqual(["shake", "soft"]); + expect(config.background).toBe(false); + expect(config.supersedeReads).toBe(false); + expect(config.progressRatio).toBe(0.5); expect(config.prune).toEqual({ ...DEFAULT_CONFIG.prune, enabled: false, @@ -37,72 +81,98 @@ describe("readConfig", () => { ...DEFAULT_CONFIG.shake, minSavings: 1_000, }); - expect(config.progressRatio).toBe(0.5); }); - it("skips OMP methods that Pi lacks and duplicates, as unavailable methods", () => { + it("accepts the $schema key", () => { + expect(readConfig({ $schema: "./schema.json" }).problems).toEqual([]); + expect( + readConfig({ advanced: { $schema: "./schema.json" } }).problems, + ).toEqual(["advanced.$schema is not a setting"]); + }); + + it("warns when a strategy is set together with advanced.methodOrder", () => { const { config, problems } = readConfig({ - methodOrder: ["remote", "snapcompact", "soft", "handoff", "soft"], + strategy: "frugal", + advanced: { methodOrder: ["soft"] }, }); - expect(problems).toEqual([]); - expect(config.methodOrder).toEqual(["soft", "handoff"]); + expect(config.methodOrder).toEqual(["soft"]); + expect(problems).toEqual([ + 'strategy "frugal" does not set the method order, because advanced.methodOrder replaces it', + ]); + }); + + it("warns when a background note is requested without a handoff note", () => { + const { problems } = readConfig({ + advanced: { methodOrder: ["soft", "handoff"], background: true }, + }); + expect(problems).toEqual([ + 'advanced.background has no effect, because "handoff" is not before "soft" in the method order', + ]); + }); + + it("accepts a background setting that the chosen strategy does not use", () => { + // The panel changes the strategy and keeps advanced.background. + expect( + readConfig({ strategy: "pi-summary", advanced: { background: true } }) + .problems, + ).toEqual([]); }); it("reports each invalid value and keeps its default", () => { const { config, problems } = readConfig({ enabled: "yes", - thresholdTokens: 0, - thresholdPercent: 150, - methodOrder: ["handoff", "magic"], - progressRatio: 0, - prune: { minTokens: 1.5 }, - shake: "off", - unknown: 1, + strategy: "fast", + advanced: { + methodOrder: ["handoff", "remote"], + progressRatio: 0, + prune: { minTokens: 1.5 }, + shake: "off", + }, + thresholdTokens: 150_000, }); expect(config).toEqual(DEFAULT_CONFIG); expect(problems).toEqual([ - "contextKit.enabled must be a boolean", - "contextKit.thresholdTokens must be -1 or a positive integer", - "contextKit.thresholdPercent must be -1 or a number in (0, 100]", - 'contextKit.methodOrder must be an array of "handoff", "shake", "soft", "remote" or "snapcompact"', - "contextKit.progressRatio must be a number in (0, 1]", - "contextKit.prune.minTokens must be a non-negative integer", - "contextKit.shake must be an object", - "contextKit.unknown is not a setting", + "enabled must be true or false (default used)", + 'strategy must be "balanced", "frugal" or "pi-summary" (default used)', + 'advanced.methodOrder must be a list of "handoff", "shake" and "soft" (default used)', + "advanced.progressRatio must be a number above 0, up to 1 (default used)", + "advanced.prune.minTokens must be a whole number, 0 or more (default used)", + "advanced.shake must be an object (default used)", + "thresholdTokens is not a setting", ]); }); it("rejects a value that is not an object", () => { expect(readConfig(3)).toEqual({ config: DEFAULT_CONFIG, - problems: ["contextKit must be an object"], + problems: ["the settings must be an object (default used)"], }); }); }); describe("ownThreshold", () => { - it("is unset by default", () => { - expect(ownThreshold(DEFAULT_CONFIG, 200_000)).toBe( - Number.POSITIVE_INFINITY, - ); + it("takes a percentage of the context window by default", () => { + expect(ownThreshold(DEFAULT_CONFIG, 200_000)).toBe(150_000); }); - it("takes a percentage of the context window, below the whole window", () => { - const at = (thresholdPercent: number) => - ownThreshold({ ...DEFAULT_CONFIG, thresholdPercent }, 200_000); - expect(at(75)).toBe(150_000); - expect(at(100)).toBe(198_000); + it("caps a percentage below the whole window", () => { + expect( + ownThreshold({ ...DEFAULT_CONFIG, threshold: { percent: 100 } }, 200_000), + ).toBe(198_000); }); - it("prefers thresholdTokens over thresholdPercent, below the whole window", () => { - const at = (thresholdTokens: number) => - ownThreshold( - { ...DEFAULT_CONFIG, thresholdTokens, thresholdPercent: 75 }, - 200_000, - ); + it("caps tokens below the whole window", () => { + const at = (tokens: number) => + ownThreshold({ ...DEFAULT_CONFIG, threshold: { tokens } }, 200_000); expect(at(100_000)).toBe(100_000); expect(at(500_000)).toBe(199_999); }); + + it("leaves only Pi's threshold for pi", () => { + expect(ownThreshold({ ...DEFAULT_CONFIG, threshold: "pi" }, 200_000)).toBe( + Number.POSITIVE_INFINITY, + ); + }); }); describe("speculationLead", () => { @@ -114,3 +184,54 @@ describe("speculationLead", () => { expect(speculationLead(Number.POSITIVE_INFINITY)).toBe(0); }); }); + +describe("context-kit.schema.json", () => { + it("declares every setting with the defaults that readConfig uses", () => { + const schema: unknown = JSON.parse( + readFileSync( + new URL("../context-kit.schema.json", import.meta.url), + "utf8", + ), + ); + const defaults = (node: unknown): unknown => { + if (!isRecord(node)) return undefined; + if (isRecord(node.properties)) + return Object.fromEntries( + Object.entries(node.properties) + .map(([key, child]) => [key, defaults(child)]) + .filter(([, value]) => value !== undefined), + ); + return node.default; + }; + expect(readConfig(defaults(schema))).toEqual({ + config: DEFAULT_CONFIG, + problems: [], + }); + }); + + it.each([ + "75%", + "72.5%", + "100%", + "100.0%", + "0.5%", + "007%", + "0100%", + "0%", + "0.0%", + "100.5%", + "101%", + ".5%", + "75 %", + "%", + ])("matches readConfig for the threshold %s", (threshold) => { + const text = readFileSync( + new URL("../context-kit.schema.json", import.meta.url), + "utf8", + ); + const pattern = /"pattern": "(.+)"/.exec(text)?.[1]; + expect(pattern).toBeDefined(); + const valid = readConfig({ threshold }).problems.length === 0; + expect(new RegExp(JSON.parse(`"${pattern}"`)).test(threshold)).toBe(valid); + }); +}); diff --git a/test/extension.test.ts b/test/extension.test.ts index f0d8def..0335a2d 100644 --- a/test/extension.test.ts +++ b/test/extension.test.ts @@ -1,4 +1,11 @@ -import { mkdtempSync, writeFileSync } from "node:fs"; +import { + chmodSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + writeFileSync, +} from "node:fs"; import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { @@ -15,12 +22,13 @@ import { SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent"; -import { afterEach, describe, expect, it } from "vitest"; +import { afterEach, describe, expect, it, vi } from "vitest"; const sessions: { dispose(): void }[] = []; afterEach(() => { for (const session of sessions.splice(0)) session.dispose(); + vi.unstubAllEnvs(); }); async function start( @@ -29,11 +37,25 @@ async function start( compactionEnabled = true, contextKit?: unknown, keepRecentTokens = 1_000, + legacyContextKit?: unknown, ) { const agentDir = mkdtempSync(join(tmpdir(), "pi-context-kit-agent-")); const cwd = mkdtempSync(join(tmpdir(), "pi-context-kit-cwd-")); writeFileSync(join(cwd, "a.ts"), "export const a = 1;\n".repeat(200)); writeFileSync(join(cwd, "b.ts"), "export const b = 2;\n".repeat(1_000)); + // The extension finds its settings file through Pi's agent directory. + vi.stubEnv("PI_CODING_AGENT_DIR", agentDir); + if (contextKit !== undefined) + writeFileSync( + join(agentDir, "context-kit.json"), + JSON.stringify(contextKit), + ); + // 0.3 read its settings from Pi's settings file. + if (legacyContextKit !== undefined) + writeFileSync( + join(agentDir, "settings.json"), + JSON.stringify({ contextKit: legacyContextKit }), + ); const faux = fauxProvider({ models: [ { id: "faux-1", contextWindow, maxTokens: 4_096, reasoning: true }, @@ -47,7 +69,6 @@ async function start( reserveTokens: 1_000, keepRecentTokens, }, - contextKit, }; const settingsManager = SettingsManager.inMemory(settings); const modelRuntime = await ModelRuntime.create({ @@ -90,7 +111,7 @@ async function start( tools: ["read", "edit", "recall"], }); sessions.push(session); - return { session, faux, cwd }; + return { session, faux, cwd, agentDir }; } describe("pi-context-kit inside Pi", () => { @@ -118,6 +139,323 @@ describe("pi-context-kit inside Pi", () => { }, ); + it("tells the user about freed tokens and shows the threshold in the status", async () => { + const { session } = await start( + [ + fauxAssistantMessage(fauxToolCall("read", { path: "b.ts" })), + fauxAssistantMessage(fauxToolCall("read", { path: "b.ts" })), + fauxAssistantMessage("done"), + ], + 200_000, + true, + { threshold: 8_000, advanced: { methodOrder: [] } }, + ); + const notify = vi.fn(); + const setStatus = vi.fn(); + await session.bindExtensions({ + uiContext: { + ...session.extensionRunner.getUIContext(), + notify, + setStatus, + }, + }); + await session.prompt("Read b.ts twice"); + expect(notify.mock.calls).toEqual([ + [ + expect.stringMatching( + /^pi-context-kit freed \d+% of the context \(\d+k? tokens\)\. The agent can still look up what was removed\.$/, + ), + "info", + ], + ]); + expect(setStatus).toHaveBeenLastCalledWith( + "context-kit", + expect.stringMatching(/^Context [0-3]% · cleanup at 4%$/), + ); + }); + + it("states the settings with /context-kit outside the TUI", async () => { + const { session } = await start([], 200_000, true, { strategy: "frugal" }); + const notify = vi.fn(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + await session.prompt("/context-kit"); + expect(notify.mock.calls).toEqual([ + [ + expect.stringMatching( + /^pi-context-kit: automatic cleanup at 75% full, with trim first\. Settings: .+context-kit\.json$/, + ), + "info", + ], + ]); + }); + + it("moves the 0.3 settings of a trusted project to the project file", async () => { + const { session, cwd, agentDir } = await start([ + fauxAssistantMessage("done"), + ]); + mkdirSync(join(cwd, ".pi")); + writeFileSync( + join(cwd, ".pi", "settings.json"), + JSON.stringify({ contextKit: { methodOrder: ["soft"] } }), + ); + const notify = vi.fn(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + const file = join(cwd, ".pi", "context-kit.json"); + expect(notify.mock.calls).toEqual([ + [expect.stringContaining(`moved its settings to ${file}.`), "info"], + ]); + expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({ + strategy: "pi-summary", + }); + expect(existsSync(join(agentDir, "context-kit.json"))).toBe(false); + }); + + it("ignores the settings of a project that Pi does not trust", async () => { + const { session, cwd } = await start([fauxAssistantMessage("done")]); + mkdirSync(join(cwd, ".pi")); + writeFileSync( + join(cwd, ".pi", "settings.json"), + JSON.stringify({ contextKit: { methodOrder: ["soft"] } }), + ); + session.settingsManager.setProjectTrusted(false); + const notify = vi.fn(); + const setStatus = vi.fn(); + await session.bindExtensions({ + uiContext: { + ...session.extensionRunner.getUIContext(), + notify, + setStatus, + }, + }); + expect(notify).not.toHaveBeenCalled(); + expect(existsSync(join(cwd, ".pi", "context-kit.json"))).toBe(false); + writeFileSync( + join(cwd, ".pi", "context-kit.json"), + JSON.stringify({ enabled: false }), + ); + await session.prompt("Hi"); + expect(setStatus).toHaveBeenLastCalledWith( + "context-kit", + expect.stringMatching(/ · cleanup at 75%$/), + ); + }); + + it("warns when it cannot move the 0.3 settings and moves them at the next start", async () => { + const { session, agentDir, cwd } = await start( + [], + 200_000, + true, + undefined, + 1_000, + { thresholdTokens: 8_000 }, + ); + mkdirSync(join(cwd, ".pi")); + writeFileSync( + join(cwd, ".pi", "settings.json"), + JSON.stringify({ contextKit: { methodOrder: ["soft"] } }), + ); + const projectFile = join(cwd, ".pi", "context-kit.json"); + const notify = vi.fn(); + const file = join(agentDir, "context-kit.json"); + // A read-only file where the new file is written first makes the write fail once. + const temporary = `${file}.${process.pid}.tmp`; + writeFileSync(temporary, ""); + chmodSync(temporary, 0o444); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + expect(notify.mock.calls).toEqual([ + [ + expect.stringMatching( + new RegExp( + `saving ${file} failed .+Defaults apply until it works\\.`, + ), + ), + "warning", + ], + ]); + expect(existsSync(projectFile)).toBe(false); + notify.mockClear(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + expect(notify.mock.calls).toEqual([ + [expect.stringContaining(`moved its settings to ${file}.`), "info"], + [ + expect.stringContaining(`moved its settings to ${projectFile}.`), + "info", + ], + ]); + expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({ + threshold: 8_000, + }); + }); + + it("waits to move the 0.3 settings while Pi's settings cannot be read", async () => { + const { session, agentDir, cwd } = await start([]); + writeFileSync(join(agentDir, "settings.json"), "{ broken"); + mkdirSync(join(cwd, ".pi")); + writeFileSync( + join(cwd, ".pi", "settings.json"), + JSON.stringify({ contextKit: { methodOrder: ["soft"] } }), + ); + const projectFile = join(cwd, ".pi", "context-kit.json"); + const notify = vi.fn(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + expect(notify).not.toHaveBeenCalled(); + expect(existsSync(projectFile)).toBe(false); + writeFileSync(join(agentDir, "settings.json"), "{}"); + notify.mockClear(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + expect(notify.mock.calls).toEqual([ + [ + expect.stringContaining(`moved its settings to ${projectFile}.`), + "info", + ], + ]); + }); + + it("keeps the global 0.3 threshold for a project that did not set one", async () => { + const { session, cwd } = await start( + [fauxAssistantMessage("done")], + 200_000, + true, + undefined, + 1_000, + { thresholdPercent: 70 }, + ); + mkdirSync(join(cwd, ".pi")); + writeFileSync( + join(cwd, ".pi", "settings.json"), + JSON.stringify({ contextKit: { prune: { enabled: false } } }), + ); + const statuses: string[] = []; + const setStatus = (key: string, text: string | undefined) => { + if (key === "context-kit") statuses.push(text ?? ""); + }; + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), setStatus }, + }); + expect( + JSON.parse(readFileSync(join(cwd, ".pi", "context-kit.json"), "utf8")), + ).toEqual({ advanced: { prune: { enabled: false } } }); + expect(statuses.at(-1)).toMatch(/ · cleanup at 70%$/); + }); + + it("updates the status after a compaction at turn end", async () => { + // The last reply passes the threshold, so no later turn refreshes the status. + const main = [ + fauxAssistantMessage(fauxToolCall("read", { path: "b.ts" })), + fauxAssistantMessage("done ".repeat(5_000)), + ]; + const reply: FauxResponseStep = (context) => + JSON.stringify(context.messages.at(-1)).includes("handoff note") + ? fauxAssistantMessage("## Goal\nNote") + : (main.shift() ?? fauxAssistantMessage("extra")); + const { session } = await start(Array(8).fill(reply), 200_000, true, { + threshold: 10_000, + advanced: { + background: false, + supersedeReads: false, + prune: { enabled: false }, + }, + }); + const compacted = () => + session.sessionManager + .getBranch() + .some((entry) => entry.type === "compaction"); + const statuses: [string, boolean][] = []; + const setStatus = (key: string, text: string | undefined) => { + if (key === "context-kit") statuses.push([text ?? "", compacted()]); + }; + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), setStatus }, + }); + await session.prompt("Read b.ts and answer"); + expect( + session.sessionManager + .getBranch() + .filter((entry) => entry.type === "compaction"), + ).toHaveLength(1); + expect(main).toHaveLength(0); + expect(statuses.at(-1)).toEqual([ + expect.stringMatching(/^Context \d% · cleanup at 5%$/), + true, + ]); + }); + + it("reports an invalid settings file at start and again on /context-kit", async () => { + const { session, cwd } = await start([], 200_000, true, {}); + const file = join(cwd, ".pi", "context-kit.json"); + mkdirSync(join(cwd, ".pi")); + writeFileSync(file, "{ broken"); + const notify = vi.fn(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + await session.prompt("/context-kit"); + const warning = [ + expect.stringMatching( + /^pi-context-kit settings need attention: .+context-kit\.json is not valid JSON .+, file ignored\. Type \/context-kit to see them\.$/, + ), + "warning", + ]; + expect(notify.mock.calls).toEqual([ + warning, + warning, + [expect.stringMatching(/^pi-context-kit: automatic cleanup/), "info"], + ]); + }); + + it("moves 0.3 settings to context-kit.json once and keeps their behavior", async () => { + const { session, agentDir } = await start( + [fauxAssistantMessage("done"), fauxAssistantMessage("done")], + 200_000, + true, + undefined, + 1_000, + { thresholdTokens: 8_000, asyncEnabled: false }, + ); + const notify = vi.fn(); + const setStatus = vi.fn(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), notify }, + }); + await session.prompt("Hi"); + await session.bindExtensions({ + uiContext: { + ...session.extensionRunner.getUIContext(), + notify, + setStatus, + }, + }); + await session.prompt("Again"); + // 8,000 of 200,000 tokens. + expect(setStatus).toHaveBeenLastCalledWith( + "context-kit", + expect.stringMatching(/ · cleanup at 4%$/), + ); + const file = join(agentDir, "context-kit.json"); + expect(notify.mock.calls).toEqual([ + [ + `pi-context-kit moved its settings to ${file}. The "contextKit" entry in Pi's settings.json is no longer used.`, + "info", + ], + ]); + expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({ + threshold: 8_000, + advanced: { background: false }, + }); + }); + it("replaces an older read when that brings the context below the threshold", async () => { const { session } = await start( [ @@ -127,7 +465,7 @@ describe("pi-context-kit inside Pi", () => { ], 200_000, true, - { thresholdTokens: 8_000, methodOrder: [] }, + { threshold: 8_000, advanced: { methodOrder: [] } }, ); await session.prompt("Read b.ts twice"); const edits = session.sessionManager @@ -143,8 +481,8 @@ describe("pi-context-kit inside Pi", () => { [4, 1], [10, 0], ])( - "takes thresholdPercent %i as a share of the context window", - async (thresholdPercent, edits) => { + "takes threshold %i%% as a share of the context window", + async (percent, edits) => { const { session } = await start( [ fauxAssistantMessage(fauxToolCall("read", { path: "b.ts" })), @@ -153,7 +491,7 @@ describe("pi-context-kit inside Pi", () => { ], 200_000, true, - { thresholdPercent, methodOrder: [] }, + { threshold: `${percent}%`, advanced: { methodOrder: [] } }, ); await session.prompt("Read b.ts twice"); expect( @@ -174,7 +512,7 @@ describe("pi-context-kit inside Pi", () => { ], 200_000, true, - { thresholdTokens: 1_000, methodOrder: [] }, + { threshold: 1_000, advanced: { methodOrder: [] } }, ); await session.prompt("Read a.ts twice"); expect( @@ -264,10 +602,13 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 19_000, true, { - asyncEnabled: true, - supersedeReads: false, - prune: { enabled: false }, - progressRatio: 1, + threshold: "pi", + advanced: { + background: true, + supersedeReads: false, + prune: { enabled: false }, + progressRatio: 1, + }, }); await session.prompt("Read the file"); await new Promise((resolve) => setTimeout(resolve, 50)); @@ -318,9 +659,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 19_000, true, { - supersedeReads: false, - prune: { enabled: false }, - progressRatio: 1, + threshold: "pi", + advanced: { + supersedeReads: false, + prune: { enabled: false }, + progressRatio: 1, + }, }); await session.prompt("Read b.ts three times"); expect(noteSignal?.aborted).toBe(false); @@ -378,9 +722,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session, cwd } = await start(Array(12).fill(reply), 17_500, true, { - supersedeReads: false, - prune: { enabled: false }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: "pi", + advanced: { + supersedeReads: false, + prune: { enabled: false }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }); writeFileSync(join(cwd, "b.ts"), `${"b".repeat(19_000)}`); await session.prompt("Read b.ts four times"); @@ -413,7 +760,9 @@ describe("pi-context-kit inside Pi", () => { return next; }; // An 8,000-token threshold has a 1,000-token lead, not an 8,192-token floor. - const { session } = await start(Array(6).fill(reply), 9_000); + const { session } = await start(Array(6).fill(reply), 9_000, true, { + threshold: "pi", + }); await session.prompt("Read a.ts"); await session.prompt("Continue"); const live = @@ -439,7 +788,15 @@ describe("pi-context-kit inside Pi", () => { true, { enabled: false }, ); + const setStatus = vi.fn(); + await session.bindExtensions({ + uiContext: { ...session.extensionRunner.getUIContext(), setStatus }, + }); await session.prompt("Read a.ts twice"); + expect(setStatus).toHaveBeenLastCalledWith( + "context-kit", + "Context cleanup off", + ); expect( session.sessionManager .getBranch() @@ -461,7 +818,7 @@ describe("pi-context-kit inside Pi", () => { ], 200_000, true, - { methodOrder: ["soft", "handoff"] }, + { advanced: { methodOrder: ["soft", "handoff"] } }, ); await session.prompt("Hi"); await session.prompt("Again"); @@ -486,10 +843,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 200_000, true, { - thresholdTokens: 13_000, - asyncEnabled: false, - supersedeReads: false, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + background: false, + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt(`Read b.ts then a.ts. ${"history ".repeat(5_000)}`); const compactions = session.sessionManager @@ -522,10 +881,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 200_000, true, { - thresholdTokens: 13_000, - asyncEnabled: false, - supersedeReads: false, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + background: false, + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt(`Read b.ts then a.ts. ${"history ".repeat(5_000)}`); const compactions = session.sessionManager @@ -556,9 +917,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 15_000, true, { - asyncEnabled: false, - supersedeReads: false, - prune: { enabled: false }, + threshold: "pi", + advanced: { + background: false, + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt(`Read b.ts. ${"history ".repeat(4_500)}`); const compactions = session.sessionManager @@ -589,10 +953,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 200_000, true, { - thresholdTokens: 13_000, - asyncEnabled: true, - supersedeReads: false, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + background: true, + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt("Read b.ts three times"); expect(notes).toBe(1); @@ -637,9 +1003,8 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(12).fill(reply), 200_000, true, { - thresholdTokens: 12_000, - supersedeReads: false, - prune: { enabled: false }, + threshold: 12_000, + advanced: { supersedeReads: false, prune: { enabled: false } }, }); await session.prompt("Read b.ts twice, then a.ts"); expect(noteSignal?.aborted).toBe(false); @@ -683,9 +1048,8 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(12).fill(reply), 200_000, true, { - thresholdTokens: 12_000, - supersedeReads: false, - prune: { enabled: false }, + threshold: 12_000, + advanced: { supersedeReads: false, prune: { enabled: false } }, }); try { await session.prompt("Read b.ts twice, then a.ts"); @@ -726,11 +1090,13 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), contextWindow, true, { - thresholdTokens: 13_000, - methodOrder: order, - asyncEnabled: false, - supersedeReads: false, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + methodOrder: order, + background: false, + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt(`Read b.ts then a.ts. ${"history ".repeat(5_000)}`); expect( @@ -753,7 +1119,7 @@ describe("pi-context-kit inside Pi", () => { Array(4).fill(reply), 200_000, true, - { thresholdTokens: 13_000, methodOrder: ["soft"] }, + { threshold: 13_000, advanced: { methodOrder: ["soft"] } }, 50_000, ); await session.prompt("Hi"); @@ -787,10 +1153,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(6).fill(reply), 200_000, true, { - thresholdTokens: 13_000, - methodOrder: ["soft"], - supersedeReads: false, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + methodOrder: ["soft"], + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt("Hi"); const first = session.sessionManager @@ -826,10 +1194,12 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 200_000, true, { - thresholdTokens: 13_000, - methodOrder: ["soft"], - supersedeReads: false, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + methodOrder: ["soft"], + supersedeReads: false, + prune: { enabled: false }, + }, }); await session.prompt(`Read b.ts then a.ts. ${"history ".repeat(5_000)}`); expect(summaries).toBe(1); @@ -847,7 +1217,7 @@ describe("pi-context-kit inside Pi", () => { ], 40_000, true, - { asyncEnabled: false }, + { advanced: { background: false } }, ); await session.prompt(`Remember ${"history ".repeat(1_500)}`); await session.prompt("Continue"); @@ -871,7 +1241,7 @@ describe("pi-context-kit inside Pi", () => { ], 200_000, true, - { thresholdTokens: 4_000, asyncEnabled: false, progressRatio: 1 }, + { threshold: 4_000, advanced: { background: false, progressRatio: 1 } }, ); await session.prompt("Read a.ts then b.ts"); @@ -904,9 +1274,8 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(5).fill(reply), 200_000, true, { - thresholdTokens: 4_000, - asyncEnabled: false, - progressRatio: 1, + threshold: 4_000, + advanced: { background: false, progressRatio: 1 }, }); await session.prompt("Read b.ts then a.ts"); @@ -945,10 +1314,12 @@ describe("pi-context-kit inside Pi", () => { contextWindow, true, { - thresholdTokens: 18_000, - asyncEnabled: false, - prune: { enabled: false }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: 18_000, + advanced: { + background: false, + prune: { enabled: false }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }, ); await session.prompt("Generate the source"); @@ -980,11 +1351,13 @@ describe("pi-context-kit inside Pi", () => { 200_000, true, { - thresholdTokens: 8_000, - methodOrder: ["shake", "soft", "handoff"], - asyncEnabled: false, - prune: { enabled: false }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: 8_000, + advanced: { + methodOrder: ["shake", "soft", "handoff"], + background: false, + prune: { enabled: false }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }, ); await session.prompt("Inspect the file"); @@ -1010,10 +1383,12 @@ describe("pi-context-kit inside Pi", () => { 200_000, true, { - thresholdTokens: 8_000, - asyncEnabled: false, - prune: { protectTokens: 0, minSavings: 1, minTokens: 50 }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: 8_000, + advanced: { + background: false, + prune: { protectTokens: 0, minSavings: 1, minTokens: 50 }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }, ); await session.prompt("Read b.ts"); @@ -1048,10 +1423,12 @@ describe("pi-context-kit inside Pi", () => { 200_000, true, { - thresholdTokens: 11_000, - asyncEnabled: false, - prune: { enabled: false }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: 11_000, + advanced: { + background: false, + prune: { enabled: false }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }, ); await session.prompt("Read b.ts twice"); @@ -1082,11 +1459,13 @@ describe("pi-context-kit inside Pi", () => { 200_000, true, { - thresholdTokens: 8_000, - methodOrder: ["soft", "shake", "handoff"], - asyncEnabled: false, - prune: { enabled: false }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: 8_000, + advanced: { + methodOrder: ["soft", "shake", "handoff"], + background: false, + prune: { enabled: false }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }, ); await session.prompt("Inspect the file"); @@ -1127,11 +1506,13 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 200_000, true, { - thresholdTokens: 18_000, - methodOrder: [first, second, third], - asyncEnabled: false, - prune: { enabled: false }, - shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + threshold: 18_000, + advanced: { + methodOrder: [first, second, third], + background: false, + prune: { enabled: false }, + shake: { protectTokens: 0, minSavings: 1, blockMinTokens: 10 }, + }, }); await session.prompt("Generate the source"); await session.prompt("Read b.ts"); @@ -1185,10 +1566,12 @@ describe("pi-context-kit inside Pi", () => { 200_000, true, { - thresholdTokens: 13_000, - asyncEnabled: false, - progressRatio: 1, - prune: { enabled: false }, + threshold: 13_000, + advanced: { + background: false, + progressRatio: 1, + prune: { enabled: false }, + }, }, 8_000, ); @@ -1285,7 +1668,7 @@ describe("pi-context-kit inside Pi", () => { return next; }; const { session } = await start(Array(8).fill(reply), 200_000, true, { - asyncEnabled: false, + advanced: { background: false }, }); await session.prompt("Read a.ts"); const compactions = session.sessionManager diff --git a/test/migrate.test.ts b/test/migrate.test.ts new file mode 100644 index 0000000..ef6de7b --- /dev/null +++ b/test/migrate.test.ts @@ -0,0 +1,141 @@ +import { describe, expect, it } from "vitest"; +import { + type ContextKitConfig, + readConfig, + writesHandoff, +} from "../src/config.ts"; +import { migrateLegacy, migrateProject } from "../src/migrate.ts"; +import { mergeSettings } from "../src/settings-file.ts"; + +describe("migrateLegacy", () => { + it("keeps Pi's limit when 0.3 had no threshold", () => { + expect(migrateLegacy({})).toEqual({ threshold: "pi" }); + }); + + it.each([ + [{ thresholdTokens: 150_000 }, 150_000], + [{ thresholdPercent: 75 }, "75%"], + [{ thresholdTokens: -1, thresholdPercent: 62.5 }, "62.5%"], + [{ thresholdTokens: 120_000, thresholdPercent: 60 }, 120_000], + [{ thresholdTokens: "lots" }, "pi"], + ])("converts the threshold of %j", (legacy, threshold) => { + expect(migrateLegacy(legacy)).toEqual({ threshold }); + }); + + it.each([ + [{ methodOrder: ["handoff", "shake", "soft"] }, {}], + [ + { methodOrder: ["shake", "handoff", "soft"] }, + { strategy: "frugal", advanced: { background: true } }, + ], + [ + { methodOrder: ["shake", "handoff", "soft"], asyncEnabled: false }, + { strategy: "frugal" }, + ], + [{ methodOrder: ["soft"] }, { strategy: "pi-summary" }], + [{ asyncEnabled: false }, { advanced: { background: false } }], + [ + { methodOrder: ["remote", "handoff", "snapcompact", "soft"] }, + { advanced: { methodOrder: ["handoff", "soft"] } }, + ], + [ + { methodOrder: ["shake", "soft"], asyncEnabled: false }, + { advanced: { methodOrder: ["shake", "soft"] } }, + ], + [{ methodOrder: "handoff" }, {}], + [{ methodOrder: ["handoff", "magic"] }, {}], + [ + { methodOrder: ["shake", "remote", "shake"] }, + { advanced: { methodOrder: ["shake"] } }, + ], + ])("converts the methods of %j", (legacy, expected) => { + const migrated = migrateLegacy(legacy); + expect(migrated).toEqual({ threshold: "pi", ...expected }); + expect(readConfig(migrated).problems).toEqual([]); + }); + + it("keeps the other settings, the advanced ones under advanced", () => { + const prune = { enabled: false, protectTokens: 10_000 }; + const shake = { minSavings: 1_000 }; + expect( + migrateLegacy({ + enabled: false, + supersedeReads: false, + progressRatio: 0.5, + prune, + shake, + }), + ).toEqual({ + enabled: false, + threshold: "pi", + advanced: { supersedeReads: false, progressRatio: 0.5, prune, shake }, + }); + }); +}); + +describe("migrateProject", () => { + // 0.3 read the project block merged over the global block. The global block becomes the global file. + it.each([ + [ + { thresholdPercent: 70 }, + { prune: { enabled: false } }, + { advanced: { prune: { enabled: false } } }, + ], + [ + { thresholdTokens: 100_000 }, + { thresholdPercent: 60 }, + { threshold: 100_000 }, + ], + [ + {}, + { enabled: false, thresholdPercent: 60 }, + { enabled: false, threshold: "60%" }, + ], + [ + { asyncEnabled: false }, + { methodOrder: ["shake", "handoff", "soft"] }, + { strategy: "frugal", advanced: { background: false } }, + ], + [ + { methodOrder: ["soft"] }, + { methodOrder: ["handoff", "shake", "soft"] }, + { strategy: "balanced", advanced: { background: true } }, + ], + [ + { methodOrder: ["shake", "soft"] }, + { methodOrder: ["soft"] }, + { advanced: { methodOrder: ["soft"] } }, + ], + [ + { methodOrder: ["shake", "handoff", "soft"] }, + { methodOrder: ["soft"] }, + { strategy: "pi-summary", advanced: { background: false } }, + ], + [ + { asyncEnabled: false }, + { asyncEnabled: true }, + { strategy: "balanced", advanced: { background: true } }, + ], + ])("converts global %j with project %j", (global, project, expected) => { + const globalFile = migrateLegacy(global); + const migrated = migrateProject(global, project, globalFile); + expect(migrated).toEqual(expected); + const effective = readConfig(mergeSettings(globalFile, migrated)); + expect(effective.problems).toEqual([]); + expect(behavior(effective.config)).toEqual( + behavior( + readConfig(migrateLegacy(mergeSettings(global, project))).config, + ), + ); + }); +}); + +/** What decides the work done: `strategy` and `customOrder` only say where the method order comes from, and background needs a handoff. */ +function behavior({ + strategy: _strategy, + customOrder: _customOrder, + background, + ...rest +}: ContextKitConfig) { + return { ...rest, background: writesHandoff(rest.methodOrder) && background }; +} diff --git a/test/panel.test.ts b/test/panel.test.ts new file mode 100644 index 0000000..96225dc --- /dev/null +++ b/test/panel.test.ts @@ -0,0 +1,145 @@ +import { describe, expect, it } from "vitest"; +import { DEFAULT_CONFIG, readConfig } from "../src/config.ts"; +import { panelItems, settingValue, summaryText } from "../src/panel.ts"; + +describe("panelItems", () => { + it("shows the effective values in plain words with the choices to cycle through", () => { + expect( + panelItems(DEFAULT_CONFIG).map(({ id, label, currentValue, values }) => ({ + id, + label, + currentValue, + values, + })), + ).toEqual([ + { + id: "enabled", + label: "Automatic cleanup", + currentValue: "On", + values: ["On", "Off"], + }, + { + id: "threshold", + label: "Clean up when the context is", + currentValue: "75% full", + values: [ + "50% full", + "60% full", + "70% full", + "75% full", + "80% full", + "90% full", + "At Pi's limit", + ], + }, + { + id: "strategy", + label: "Cleanup method", + currentValue: "Summary notes (recommended)", + values: ["Summary notes (recommended)", "Trim first", "Pi's summary"], + }, + ]); + }); + + it("keeps a custom threshold among the choices", () => { + const tokens = panelItems({ + ...DEFAULT_CONFIG, + threshold: { tokens: 120_000 }, + })[1]; + expect(tokens?.currentValue).toBe("120000 tokens"); + expect(tokens?.values[0]).toBe("120000 tokens"); + expect(tokens?.values).toHaveLength(8); + const percent = panelItems({ + ...DEFAULT_CONFIG, + threshold: { percent: 72.5 }, + })[1]; + expect(percent?.values[0]).toBe("72.5% full"); + }); + + it("leaves the method to the file when advanced.methodOrder replaces it", () => { + // The order equals the balanced one, but a strategy chosen in the panel would not change it. + const { config } = readConfig({ + advanced: { methodOrder: ["handoff", "shake", "soft"] }, + }); + expect(panelItems(config).map((item) => item.id)).toEqual([ + "enabled", + "threshold", + ]); + }); + + it("describes each setting", () => { + for (const item of panelItems(DEFAULT_CONFIG)) + expect(item.description).toMatch(/\S/); + }); +}); + +describe("settingValue", () => { + it.each([ + ["enabled", "Off", false], + ["enabled", "On", true], + ["threshold", "80% full", "80%"], + ["threshold", "72.5% full", "72.5%"], + ["threshold", "120000 tokens", 120_000], + ["threshold", "At Pi's limit", "pi"], + ["strategy", "Summary notes (recommended)", "balanced"], + ["strategy", "Trim first", "frugal"], + ["strategy", "Pi's summary", "pi-summary"], + ])("writes %s %s as %j", (id, value, written) => { + expect(settingValue(id, value)).toEqual(written); + }); +}); + +describe("every panel choice", () => { + const configs = [ + DEFAULT_CONFIG, + readConfig({ threshold: 120_000 }).config, + readConfig({ threshold: "pi", enabled: false }).config, + ]; + const choices = configs.flatMap((config) => + panelItems(config).flatMap((item) => + item.values.map((value) => [item.id, value] as const), + ), + ); + it.each(choices)( + "saves %s %s as a valid setting that shows the same choice", + (id, value) => { + const { config, problems } = readConfig({ + [id]: settingValue(id, value), + }); + expect(problems).toEqual([]); + expect( + panelItems(config).find((item) => item.id === id)?.currentValue, + ).toBe(value); + }, + ); +}); + +describe("summaryText", () => { + it("states the effective settings and the file to edit", () => { + expect( + summaryText(DEFAULT_CONFIG, "/home/u/.pi/agent/context-kit.json"), + ).toBe( + "pi-context-kit: automatic cleanup at 75% full, with summary notes. Settings: /home/u/.pi/agent/context-kit.json", + ); + }); + + it("says when the cleanup is off", () => { + expect(summaryText({ ...DEFAULT_CONFIG, enabled: false }, "f.json")).toBe( + "pi-context-kit: automatic cleanup off. Settings: f.json", + ); + }); + + it("says when advanced.methodOrder replaces the method", () => { + expect( + summaryText( + readConfig({ + threshold: "pi", + advanced: { methodOrder: ["shake", "soft"] }, + }).config, + "f.json", + ), + ).toBe( + "pi-context-kit: automatic cleanup at Pi's limit, with custom methods (shake, soft). Settings: f.json", + ); + }); +}); diff --git a/test/settings-file.test.ts b/test/settings-file.test.ts new file mode 100644 index 0000000..acf68be --- /dev/null +++ b/test/settings-file.test.ts @@ -0,0 +1,192 @@ +import { + chmodSync, + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + statSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; +import { + createSettings, + loadSettings, + mergeSettings, + saveSetting, + settingsPaths, + updateSetting, +} from "../src/settings-file.ts"; + +function dirs() { + const agentDir = mkdtempSync(join(tmpdir(), "context-kit-agent-")); + const cwd = mkdtempSync(join(tmpdir(), "context-kit-cwd-")); + mkdirSync(join(cwd, ".pi")); + return { agentDir, cwd }; +} + +describe("settingsPaths", () => { + it("reads the project file only in a trusted project", () => { + const { agentDir, cwd } = dirs(); + expect(settingsPaths(agentDir, cwd, true)).toEqual({ + global: join(agentDir, "context-kit.json"), + project: join(cwd, ".pi", "context-kit.json"), + }); + expect(settingsPaths(agentDir, cwd, false)).toEqual({ + global: join(agentDir, "context-kit.json"), + project: undefined, + }); + }); +}); + +describe("loadSettings", () => { + it("returns nothing when no file exists", () => { + const { agentDir, cwd } = dirs(); + expect(loadSettings(settingsPaths(agentDir, cwd, true))).toEqual({ + raw: {}, + problems: [], + }); + }); + + it("merges the project file over the global file, key by key", () => { + const { agentDir, cwd } = dirs(); + const paths = settingsPaths(agentDir, cwd, true); + writeFileSync( + paths.global, + JSON.stringify({ + threshold: "60%", + advanced: { prune: { protectTokens: 1, minTokens: 2 } }, + }), + ); + writeFileSync( + paths.project ?? "", + JSON.stringify({ + strategy: "frugal", + advanced: { prune: { minTokens: 3 }, methodOrder: ["soft"] }, + }), + ); + expect(loadSettings(paths)).toEqual({ + raw: { + threshold: "60%", + strategy: "frugal", + advanced: { + prune: { protectTokens: 1, minTokens: 3 }, + methodOrder: ["soft"], + }, + }, + problems: [], + }); + }); + + it("reports a file that is not valid JSON and ignores it", () => { + const { agentDir, cwd } = dirs(); + const paths = settingsPaths(agentDir, cwd, true); + writeFileSync(paths.global, "{ threshold: 1 "); + writeFileSync(paths.project ?? "", JSON.stringify({ enabled: false })); + const { raw, problems } = loadSettings(paths); + expect(raw).toEqual({ enabled: false }); + expect(problems).toHaveLength(1); + expect(problems[0]).toMatch( + new RegExp(`^${paths.global} is not valid JSON \\(.+\\), file ignored$`), + ); + }); +}); + +describe("saveSetting", () => { + it("writes the global file unless the project file sets the key", () => { + const { agentDir, cwd } = dirs(); + const paths = settingsPaths(agentDir, cwd, true); + const project = paths.project ?? ""; + writeFileSync(project, JSON.stringify({ threshold: "60%" })); + expect(saveSetting(paths, "strategy", "frugal")).toBe(paths.global); + expect(saveSetting(paths, "threshold", "80%")).toBe(project); + expect(loadSettings(paths).raw).toEqual({ + strategy: "frugal", + threshold: "80%", + }); + }); +}); + +describe("updateSetting", () => { + it("creates the file and keeps other keys when it changes one", () => { + const { agentDir } = dirs(); + const file = join(agentDir, "nested", "context-kit.json"); + updateSetting(file, "threshold", "60%"); + updateSetting(file, "strategy", "frugal"); + updateSetting(file, "threshold", 120_000); + expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({ + threshold: 120_000, + strategy: "frugal", + }); + }); + + it("writes through a symbolic link and keeps the link", () => { + const { agentDir, cwd } = dirs(); + const target = join(cwd, "dotfiles.json"); + writeFileSync(target, JSON.stringify({ enabled: true })); + const link = join(agentDir, "context-kit.json"); + symlinkSync(target, link); + updateSetting(link, "enabled", false); + expect(lstatSync(link).isSymbolicLink()).toBe(true); + expect(JSON.parse(readFileSync(target, "utf8"))).toEqual({ + enabled: false, + }); + }); + + it("refuses to overwrite a file that is not valid JSON", () => { + const { agentDir } = dirs(); + const file = join(agentDir, "context-kit.json"); + writeFileSync(file, "{ broken"); + expect(() => updateSetting(file, "enabled", false)).toThrow( + /is not valid JSON/, + ); + expect(readFileSync(file, "utf8")).toBe("{ broken"); + }); + + it("keeps the permissions of the file", () => { + const { agentDir } = dirs(); + const file = join(agentDir, "context-kit.json"); + writeFileSync(file, "{}"); + chmodSync(file, 0o600); + updateSetting(file, "enabled", false); + expect(statSync(file).mode & 0o777).toBe(0o600); + }); + + it("leaves no temporary file when the write fails", () => { + const { agentDir } = dirs(); + const file = join(agentDir, "context-kit.json"); + writeFileSync(file, "{}"); + // A read-only file where the new content is written first makes the write fail. + const temporary = `${file}.${process.pid}.tmp`; + writeFileSync(temporary, ""); + chmodSync(temporary, 0o444); + expect(() => updateSetting(file, "enabled", false)).toThrow(); + expect(readdirSync(agentDir)).toEqual(["context-kit.json"]); + expect(readFileSync(file, "utf8")).toBe("{}"); + }); +}); + +describe("mergeSettings", () => { + it("keeps a __proto__ key as a setting, so the checks report it", () => { + const merged = mergeSettings( + {}, + JSON.parse('{"__proto__": {"enabled": false}}'), + ); + expect(Object.keys(merged)).toEqual(["__proto__"]); + expect(Reflect.get(merged, "enabled")).toBeUndefined(); + }); +}); + +describe("createSettings", () => { + it("creates the file and its folder, but keeps an existing file", () => { + const { cwd } = dirs(); + const file = join(cwd, "new", "context-kit.json"); + expect(createSettings(file, { threshold: "pi" })).toBe(true); + expect(createSettings(file, { threshold: 1 })).toBe(false); + expect(JSON.parse(readFileSync(file, "utf8"))).toEqual({ threshold: "pi" }); + expect(readdirSync(join(cwd, "new"))).toEqual(["context-kit.json"]); + }); +}); diff --git a/test/status.test.ts b/test/status.test.ts new file mode 100644 index 0000000..987db88 --- /dev/null +++ b/test/status.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from "vitest"; +import { freedNotice, statusText } from "../src/status.ts"; + +describe("statusText", () => { + it("shows the context use and the threshold as shares of the window", () => { + expect( + statusText({ tokens: 124_000, limit: 150_000, contextWindow: 200_000 }), + ).toBe("Context 62% · cleanup at 75%"); + }); + + it.each([ + ["writing", "Context 70% · cleanup at 75% · writing summary"], + ["ready", "Context 70% · cleanup at 75% · summary ready"], + ] as const)("adds the background note when it is %s", (note, text) => { + expect( + statusText({ + tokens: 140_000, + limit: 150_000, + contextWindow: 200_000, + note, + }), + ).toBe(text); + }); + + it("rounds down, so 100% means the window is full", () => { + expect( + statusText({ tokens: 199_999, limit: 199_999, contextWindow: 200_000 }), + ).toBe("Context 99% · cleanup at 99%"); + }); + + it("omits the threshold when nothing compacts", () => { + expect( + statusText({ + tokens: 50_000, + limit: Number.POSITIVE_INFINITY, + contextWindow: 200_000, + }), + ).toBe("Context 25% · no automatic cleanup"); + }); +}); + +describe("freedNotice", () => { + it.each([ + [ + 180_000, + 146_000, + "pi-context-kit freed 17% of the context (34k tokens). The agent can still look up what was removed.", + ], + [ + 10_000, + 9_400, + "pi-context-kit freed 0% of the context (600 tokens). The agent can still look up what was removed.", + ], + ])("states %i to %i as a share and in tokens", (before, after, text) => { + expect(freedNotice(before, after, 200_000)).toBe(text); + }); +});