local-context-manager 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to `local-context-manager` are documented here. Version numbers also mark the project milestones represented by the merged pull requests.
+
+## [0.3.0] - 2026-09-04
+
+This release completes the public, npm-distributed extension workflow.
+
+### Added
+
+- Beginner-first documentation portal published through GitHub Pages, covering the context problem, its impact on local-LLM workflows, installation, commands, configuration, privacy, and recovery.
+- Repeatable GitHub Pages deployment workflow for the `docs/` site.
+- npm package metadata for `local-context-manager`, including repository, homepage, issue tracker, public publish configuration, and a publish-time validation hook.
+- CI checks for typechecking, tests, builds, and npm package inspection.
+
+### Changed
+
+- Set the package and lockfile version to `0.3.0`.
+- Reduced the root README to a short installation and orientation page, with the GitHub Pages portal as the canonical beginner guide.
+
+## [0.2.0] - 2026-09-04
+
+Milestone delivered by [PR #2](https://github.com/SaehwanPark/local-context-manager/pull/2).
+
+### Added
+
+- Reviewed `/checkpoint-reset [reason]` workflow for completed semantic episodes.
+- Durable local checkpoint archives and minimal continuation capsules with parent-session linkage.
+- `request_context_reset` recommendation tool and `/context-checkpoints` listing command.
+- Lineage telemetry, checkpoint storage configuration, atomic persistence, and focused tests.
+
+### Safety
+
+- A model-facing reset request only recommends the reviewed command; it never writes a checkpoint or changes sessions by itself.
+- Generation, editing, approval, storage, and fresh-session failures preserve the active session.
+
+## [0.1.0] - 2026-09-04
+
+Initial extension milestone delivered by [PR #1](https://github.com/SaehwanPark/local-context-manager/pull/1).
+
+### Added
+
+- Layered global/project JSON configuration with validation, trust gating, and safe defaults.
+- Context telemetry and `/context-stats` reporting.
+- Guarded proactive native compaction with hysteresis, in-flight protection, cooldown, and Pi emergency-compaction fallback.
+- Conservative reduction of newly arriving oversized build, failure, search, diff, and generic tool results, with recoverable full-output paths.
+- Optional semantic compaction through `request_context_compaction` and `/compact-phase`.
+- Reviewed `/handoff <objective>` continuation prompts and fresh-session initialization.
+- Package metadata, examples, tests, and build/typecheck configuration.
+
+[0.3.0]: https://github.com/SaehwanPark/local-context-manager/releases/tag/v0.3.0
+[0.2.0]: https://github.com/SaehwanPark/local-context-manager/pull/2
+[0.1.0]: https://github.com/SaehwanPark/local-context-manager/pull/1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sae-Hwan Park
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# local-context-manager
+
+`local-context-manager` is a [Pi](https://github.com/earendil-works/pi) extension for long-running sessions, especially workflows using local models where large prompts can make prefill slower and context overflow more disruptive.
+
+## Start here
+
+The **[beginner documentation portal](https://saehwanpark.github.io/local-context-manager/)** explains the problem, why it matters, installation, first use, commands, configuration, privacy, and recovery. The portal is the canonical user guide; this README stays short so the same instructions work on GitHub and npm.
+
+## Install in Pi
+
+```bash
+pi install npm:local-context-manager
+```
+
+Start (or reload) Pi in your project, then try:
+
+```text
+/context-stats
+```
+
+The extension works with Pi's existing models and configuration. It does not install a model or change Pi's emergency compaction authority. To pin this release, use `npm:local-context-manager@0.3.0`.
+
+## What it adds
+
+- telemetry for context size, compaction, and reduced tool output;
+- guarded proactive compaction at safe idle boundaries;
+- conservative reduction of only new oversized tool results, with a recovery path;
+- intentional phase compaction with `/compact-phase`;
+- reviewed `/handoff` and `/checkpoint-reset` workflows for starting a fresh session without silently discarding important work.
+
+All session-changing workflows are reviewable. The extension does not automatically reset sessions or inject archived checkpoints into later prompts.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run build
+```
+
+See the [source repository](https://github.com/SaehwanPark/local-context-manager) and the [full changelog](CHANGELOG.md) for project history.
+
+## License
+
+MIT

package/examples/local-context-manager.json

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "softWarningTokens": 24000,
+  "compactThresholdTokens": 32000,
+  "hardCeilingTokens": 48000,
+  "keepRecentTokens": 10000,
+  "toolOutputReduction": true,
+  "semanticCompaction": true,
+  "handoff": true,
+  "checkpointReset": true,
+  "checkpointDirectory": null,
+  "debug": false
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "local-context-manager",
+  "version": "0.3.0",
+  "description": "A Pi extension for cache-friendly context control in long-running local-LLM workflows",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "local-llm", "context-management"],
+  "author": "Sae-Hwan Park",
+  "homepage": "https://saehwanpark.github.io/local-context-manager/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SaehwanPark/local-context-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SaehwanPark/local-context-manager/issues"
+  },
+  "license": "MIT",
+  "files": ["src", "examples", "README.md", "CHANGELOG.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.84.4 <1"
+  },
+  "dependencies": {
+    "typebox": "^1.3.7"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}