@pinet/model-aware-compaction 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Porcellini
+
+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,55 @@
+# @pinet/model-aware-compaction
+
+A Pi extension that triggers proactive compaction at different active-context token limits for different models. It adapts Pi's shipped `trigger-compact.ts` example to multi-model and subagent workloads.
+
+## Install
+
+```bash
+pi install npm:@pinet/model-aware-compaction
+```
+
+For local development from a clone of this repository, load the source directly:
+
+```bash
+pi --extension /path/to/extensions/model-aware-compaction/index.ts
+```
+
+## Configure
+
+The extension is disabled by default. Add this to project `.pi/settings.json` or global `~/.pi/agent/settings.json`:
+
+```json
+{
+  "model-aware-compaction": {
+    "enabled": true,
+    "rules": [
+      { "model": "openai/gpt-5-mini", "activeContextTokens": 100000 },
+      { "model": "anthropic/claude-sonnet-4-6", "activeContextTokens": 100000 },
+      { "model": "example-proxy/*", "activeContextTokens": 136000 }
+    ],
+    "customInstructions": "Preserve decisions, files changed, validation results, and next steps.",
+    "debug": false
+  }
+}
+```
+
+Rules are evaluated in order. `*` wildcards are supported, such as `example-proxy/*`.
+
+## Behavior
+
+After each `turn_end`, the extension reads `ctx.getContextUsage()` and the active `ctx.model`. When usage first exceeds the matching rule's `activeContextTokens`, it calls `ctx.compact()`. It prevents duplicate calls while compaction is in flight and re-arms after usage drops below the threshold, the model changes, a session starts, or compaction fails.
+
+Run `/model-aware-compaction-status` to inspect the active model, usage, matched threshold, state, and loaded rules.
+
+## Limitation
+
+Pi's extension API makes `ctx.compact()` fire-and-forget. This package is therefore proactive best effort, not an atomic `compact-before-next-provider-request` barrier. Debug logs make trigger/completion/failure visible so that race behavior can be measured. Upstream model-specific settings or an awaitable/deferred compaction seam would provide a stronger guarantee.
+
+## Development
+
+```bash
+pnpm --filter @pinet/model-aware-compaction lint
+pnpm --filter @pinet/model-aware-compaction typecheck
+pnpm --filter @pinet/model-aware-compaction test
+pnpm --filter @pinet/model-aware-compaction build
+```

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+import type { CompactionRule } from "./helpers.js";
+export declare const SETTINGS_KEY = "model-aware-compaction";
+export interface ModelAwareCompactionConfig {
+    enabled?: boolean;
+    rules?: Array<{
+        model?: string;
+        activeContextTokens?: number;
+    }>;
+    customInstructions?: string;
+    debug?: boolean;
+}
+export interface ResolvedConfig {
+    enabled: boolean;
+    rules: CompactionRule[];
+    customInstructions?: string;
+    debug: boolean;
+    sourcePath: string | null;
+}
+export declare function resolveConfig(raw?: ModelAwareCompactionConfig | null, sourcePath?: string | null): ResolvedConfig;
+export declare function loadConfig(cwd?: string, agentDir?: string): ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,53 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { join } from "node:path";
+export const SETTINGS_KEY = "model-aware-compaction";
+const DEFAULT_RULES = [
+    { model: "openai/gpt-5-mini", activeContextTokens: 100_000 },
+    { model: "anthropic/claude-sonnet-4-6", activeContextTokens: 100_000 },
+];
+function parseSettings(path) {
+    if (!fs.existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path, "utf8"));
+        const value = parsed[SETTINGS_KEY];
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return null;
+        return { raw: value, sourcePath: `${path}#${SETTINGS_KEY}` };
+    }
+    catch (error) {
+        console.error(`[${SETTINGS_KEY}] Failed to parse ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+export function resolveConfig(raw, sourcePath = null) {
+    const configured = Array.isArray(raw?.rules)
+        ? raw.rules.flatMap((rule) => {
+            const model = typeof rule.model === "string" ? rule.model.trim() : "";
+            const tokens = rule.activeContextTokens;
+            return model && typeof tokens === "number" && Number.isInteger(tokens) && tokens > 0
+                ? [{ model, activeContextTokens: tokens }]
+                : [];
+        })
+        : [];
+    const customInstructions = typeof raw?.customInstructions === "string" && raw.customInstructions.trim()
+        ? raw.customInstructions.trim()
+        : undefined;
+    return {
+        enabled: raw?.enabled === true,
+        rules: configured.length > 0 ? configured : DEFAULT_RULES,
+        customInstructions,
+        debug: raw?.debug === true,
+        sourcePath,
+    };
+}
+export function loadConfig(cwd = process.cwd(), agentDir = join(os.homedir(), ".pi", "agent")) {
+    const project = parseSettings(join(cwd, ".pi", "settings.json"));
+    if (project)
+        return resolveConfig(project.raw, project.sourcePath);
+    const global = parseSettings(join(agentDir, "settings.json"));
+    if (global)
+        return resolveConfig(global.raw, global.sourcePath);
+    return resolveConfig();
+}

package/dist/helpers.d.ts

@@ -0,0 +1,25 @@
+export interface ModelIdentity {
+    provider?: string;
+    id?: string;
+}
+export interface CompactionRule {
+    model: string;
+    activeContextTokens: number;
+}
+export interface CompactionDecision {
+    modelKey: string | null;
+    limit: number | null;
+    shouldCompact: boolean;
+    reason: "disabled" | "unknown-model" | "no-rule" | "usage-unavailable" | "below-limit" | "already-triggered" | "in-flight" | "over-limit";
+}
+export declare function modelKey(model: ModelIdentity | undefined): string | null;
+export declare function matchesModel(pattern: string, key: string): boolean;
+export declare function limitForModel(rules: CompactionRule[], key: string): number | null;
+export declare function decideCompaction(input: {
+    enabled: boolean;
+    model: ModelIdentity | undefined;
+    tokens: number | null | undefined;
+    rules: CompactionRule[];
+    inFlight: boolean;
+    triggeredModelKey: string | null;
+}): CompactionDecision;

package/dist/helpers.js

@@ -0,0 +1,38 @@
+export function modelKey(model) {
+    const provider = model?.provider?.trim().toLowerCase();
+    const id = model?.id?.trim().toLowerCase();
+    if (!provider || !id)
+        return null;
+    const normalizedId = id.startsWith(`${provider}/`) ? id.slice(provider.length + 1) : id;
+    return `${provider}/${normalizedId}`;
+}
+export function matchesModel(pattern, key) {
+    const normalized = pattern.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    const escaped = normalized.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+    return new RegExp(`^${escaped}$`).test(key);
+}
+export function limitForModel(rules, key) {
+    return rules.find((rule) => matchesModel(rule.model, key))?.activeContextTokens ?? null;
+}
+export function decideCompaction(input) {
+    const key = modelKey(input.model);
+    if (!input.enabled)
+        return { modelKey: key, limit: null, shouldCompact: false, reason: "disabled" };
+    if (!key)
+        return { modelKey: null, limit: null, shouldCompact: false, reason: "unknown-model" };
+    const limit = limitForModel(input.rules, key);
+    if (limit === null)
+        return { modelKey: key, limit: null, shouldCompact: false, reason: "no-rule" };
+    if (input.tokens === null || input.tokens === undefined || !Number.isFinite(input.tokens)) {
+        return { modelKey: key, limit, shouldCompact: false, reason: "usage-unavailable" };
+    }
+    if (input.tokens <= limit)
+        return { modelKey: key, limit, shouldCompact: false, reason: "below-limit" };
+    if (input.inFlight)
+        return { modelKey: key, limit, shouldCompact: false, reason: "in-flight" };
+    if (input.triggeredModelKey === key)
+        return { modelKey: key, limit, shouldCompact: false, reason: "already-triggered" };
+    return { modelKey: key, limit, shouldCompact: true, reason: "over-limit" };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function modelAwareCompaction(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,87 @@
+import { loadConfig } from "./config.js";
+import { decideCompaction, modelKey } from "./helpers.js";
+const LOG_PREFIX = "[model-aware-compaction]";
+export default function modelAwareCompaction(pi) {
+    const api = pi;
+    let inFlight = false;
+    let triggeredModelKey = null;
+    const rearm = () => {
+        triggeredModelKey = null;
+    };
+    pi.on("session_start", rearm);
+    pi.on("model_select", rearm);
+    pi.on("turn_end", (_event, rawCtx) => {
+        const ctx = rawCtx;
+        const config = loadConfig(ctx.cwd);
+        const usage = ctx.getContextUsage?.();
+        const decision = decideCompaction({
+            enabled: config.enabled,
+            model: ctx.model,
+            tokens: usage?.tokens,
+            rules: config.rules,
+            inFlight,
+            triggeredModelKey,
+        });
+        if (decision.reason === "below-limit" && triggeredModelKey === decision.modelKey) {
+            triggeredModelKey = null;
+        }
+        if (!decision.shouldCompact || !ctx.compact || !decision.modelKey || decision.limit === null)
+            return;
+        inFlight = true;
+        triggeredModelKey = decision.modelKey;
+        const details = `model=${decision.modelKey} tokens=${usage?.tokens ?? "unknown"} limit=${decision.limit}`;
+        if (config.debug) {
+            console.error(`${LOG_PREFIX} triggered ${details}`);
+            if (ctx.hasUI)
+                ctx.ui.notify(`Model-aware compaction started (${details})`, "info");
+        }
+        ctx.compact({
+            customInstructions: config.customInstructions,
+            onComplete: () => {
+                inFlight = false;
+                if (config.debug) {
+                    console.error(`${LOG_PREFIX} completed ${details}`);
+                    if (ctx.hasUI)
+                        ctx.ui.notify(`Model-aware compaction completed (${details})`, "info");
+                }
+            },
+            onError: (error) => {
+                inFlight = false;
+                triggeredModelKey = null;
+                console.error(`${LOG_PREFIX} failed ${details}: ${error.message}`);
+                if (config.debug && ctx.hasUI)
+                    ctx.ui.notify(`Model-aware compaction failed: ${error.message}`, "error");
+            },
+        });
+    });
+    pi.registerCommand("model-aware-compaction-status", {
+        description: "Show model-aware proactive compaction status",
+        handler: async (_args, rawCtx) => {
+            const ctx = rawCtx;
+            const config = loadConfig(ctx.cwd);
+            const key = modelKey(ctx.model);
+            const usage = ctx.getContextUsage?.();
+            const decision = decideCompaction({
+                enabled: config.enabled,
+                model: ctx.model,
+                tokens: usage?.tokens,
+                rules: config.rules,
+                inFlight,
+                triggeredModelKey,
+            });
+            const lines = [
+                "**Model-aware compaction**",
+                "",
+                `- enabled: ${config.enabled ? "yes" : "no"}`,
+                `- current model: ${key ?? "unknown"}`,
+                `- current tokens: ${usage?.tokens ?? "unknown"}`,
+                `- matched limit: ${decision.limit ?? "none"}`,
+                `- state: ${inFlight ? "compacting" : decision.reason}`,
+                `- config: ${config.sourcePath ?? "defaults (disabled)"}`,
+                "- rules:",
+                ...config.rules.map((rule) => `  - ${rule.model}: ${rule.activeContextTokens}`),
+            ];
+            api.sendMessage({ customType: "model-aware-compaction.status", content: lines.join("\n"), display: true }, { triggerTurn: false });
+        },
+    });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@pinet/model-aware-compaction",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Pi extension for proactive model-aware context compaction thresholds",
+  "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gugu91/extensions.git",
+    "directory": "model-aware-compaction"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist/"
+  ],
+  "keywords": [
+    "pi-package",
+    "compaction",
+    "context-window"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "node ../scripts/build-package.mjs",
+    "prepack": "pnpm run build",
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.74.0"
+  }
+}