@greppleai/grip 0.0.0-stage → 0.0.1

package/dist/utils/version-check.js

@@ -0,0 +1,91 @@
+import { PACKAGE_NAME } from "../config.js";
+import { getGripUserAgent } from "./grip-user-agent.js";
+const LATEST_VERSION_URL = `https://registry.npmjs.org/${PACKAGE_NAME.replace("/", "%2f")}`;
+const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;
+function isTruthyEnvFlag(value) {
+    if (value === undefined)
+        return false;
+    return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+function parsePackageVersion(version) {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        major: Number.parseInt(match[1], 10),
+        minor: Number.parseInt(match[2], 10),
+        patch: Number.parseInt(match[3], 10),
+        prerelease: match[4],
+    };
+}
+export function comparePackageVersions(leftVersion, rightVersion) {
+    const left = parsePackageVersion(leftVersion);
+    const right = parsePackageVersion(rightVersion);
+    if (!left || !right) {
+        return undefined;
+    }
+    if (left.major !== right.major)
+        return left.major - right.major;
+    if (left.minor !== right.minor)
+        return left.minor - right.minor;
+    if (left.patch !== right.patch)
+        return left.patch - right.patch;
+    if (left.prerelease === right.prerelease)
+        return 0;
+    if (!left.prerelease)
+        return 1;
+    if (!right.prerelease)
+        return -1;
+    return left.prerelease.localeCompare(right.prerelease);
+}
+export function isNewerPackageVersion(candidateVersion, currentVersion) {
+    const comparison = comparePackageVersions(candidateVersion, currentVersion);
+    if (comparison !== undefined) {
+        return comparison > 0;
+    }
+    return candidateVersion.trim() !== currentVersion.trim();
+}
+export async function getLatestGripRelease(currentVersion, options = {}) {
+    if (isTruthyEnvFlag(process.env.GRIP_SKIP_VERSION_CHECK) || isTruthyEnvFlag(process.env.GRIP_OFFLINE))
+        return undefined;
+    const response = await fetch(LATEST_VERSION_URL, {
+        headers: {
+            "User-Agent": getGripUserAgent(currentVersion),
+            accept: "application/json",
+        },
+        signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        return undefined;
+    const data = (await response.json());
+    const version = typeof data["dist-tags"]?.latest === "string" && data["dist-tags"].latest.trim()
+        ? data["dist-tags"].latest.trim()
+        : typeof data.version === "string" && data.version.trim()
+            ? data.version.trim()
+            : undefined;
+    if (!version) {
+        return undefined;
+    }
+    const note = typeof data.note === "string" && data.note.trim() ? data.note.trim() : undefined;
+    return {
+        version,
+        ...(note ? { note } : {}),
+    };
+}
+export async function getLatestGripVersion(currentVersion, options = {}) {
+    return (await getLatestGripRelease(currentVersion, options))?.version;
+}
+export async function checkForNewGripVersion(currentVersion) {
+    try {
+        const latestRelease = await getLatestGripRelease(currentVersion);
+        if (latestRelease && isNewerPackageVersion(latestRelease.version, currentVersion)) {
+            return latestRelease;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=version-check.js.map

package/dist/utils/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { PACKAGE_NAME } from \"../config.ts\";\nimport { getGripUserAgent } from \"./grip-user-agent.ts\";\n\nconst LATEST_VERSION_URL = `https://registry.npmjs.org/${PACKAGE_NAME.replace(\"/\", \"%2f\")}`;\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\nexport interface LatestGripRelease {\n\tversion: string;\n\tnote?: string;\n}\n\ninterface GripVersionCheckOptions {\n\ttimeoutMs?: number;\n}\ninterface NpmRegistryDistributionTags {\n\tlatest?: unknown;\n}\n\ninterface NpmRegistryPackageMetadata {\n\t\"dist-tags\"?: NpmRegistryDistributionTags;\n\tnote?: unknown;\n\tversion?: unknown;\n}\n\ninterface ParsedVersion {\n\tmajor: number;\n\tminor: number;\n\tpatch: number;\n\tprerelease?: string;\n}\n\nfunction isTruthyEnvFlag(value: string | undefined): boolean {\n\tif (value === undefined) return false;\n\treturn [\"1\", \"true\", \"yes\", \"on\"].includes(value.trim().toLowerCase());\n}\n\nfunction parsePackageVersion(version: string): ParsedVersion | undefined {\n\tconst match = version.trim().match(/^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+.*)?$/);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tmajor: Number.parseInt(match[1], 10),\n\t\tminor: Number.parseInt(match[2], 10),\n\t\tpatch: Number.parseInt(match[3], 10),\n\t\tprerelease: match[4],\n\t};\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = parsePackageVersion(leftVersion);\n\tconst right = parsePackageVersion(rightVersion);\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\n\tif (left.major !== right.major) return left.major - right.major;\n\tif (left.minor !== right.minor) return left.minor - right.minor;\n\tif (left.patch !== right.patch) return left.patch - right.patch;\n\tif (left.prerelease === right.prerelease) return 0;\n\tif (!left.prerelease) return 1;\n\tif (!right.prerelease) return -1;\n\treturn left.prerelease.localeCompare(right.prerelease);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestGripRelease(\n\tcurrentVersion: string,\n\toptions: GripVersionCheckOptions = {},\n): Promise<LatestGripRelease | undefined> {\n\tif (isTruthyEnvFlag(process.env.GRIP_SKIP_VERSION_CHECK) || isTruthyEnvFlag(process.env.GRIP_OFFLINE))\n\t\treturn undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getGripUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as NpmRegistryPackageMetadata;\n\tconst version =\n\t\ttypeof data[\"dist-tags\"]?.latest === \"string\" && data[\"dist-tags\"].latest.trim()\n\t\t\t? data[\"dist-tags\"].latest.trim()\n\t\t\t: typeof data.version === \"string\" && data.version.trim()\n\t\t\t\t? data.version.trim()\n\t\t\t\t: undefined;\n\tif (!version) {\n\t\treturn undefined;\n\t}\n\tconst note = typeof data.note === \"string\" && data.note.trim() ? data.note.trim() : undefined;\n\treturn {\n\t\tversion,\n\t\t...(note ? { note } : {}),\n\t};\n}\n\nexport async function getLatestGripVersion(\n\tcurrentVersion: string,\n\toptions: GripVersionCheckOptions = {},\n): Promise<string | undefined> {\n\treturn (await getLatestGripRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewGripVersion(currentVersion: string): Promise<LatestGripRelease | undefined> {\n\ttry {\n\t\tconst latestRelease = await getLatestGripRelease(currentVersion);\n\t\tif (latestRelease && isNewerPackageVersion(latestRelease.version, currentVersion)) {\n\t\t\treturn latestRelease;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/utils/windows-self-update.d.ts

@@ -0,0 +1,3 @@
+export declare function cleanupWindowsSelfUpdateQuarantine(packageDir: string): void;
+export declare function quarantineWindowsNativeDependencies(packageDir: string): void;
+//# sourceMappingURL=windows-self-update.d.ts.map

package/dist/utils/windows-self-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-self-update.d.ts","sourceRoot":"","sources":["../../src/utils/windows-self-update.ts"],"names":[],"mappings":"AAiDA,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAU3E;AAED,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAsB5E","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from \"node:fs\";\nimport { basename, dirname, join, relative, resolve, toNamespacedPath } from \"node:path\";\nimport { getCwdRelativePath } from \"./paths.ts\";\n\nconst QUARANTINE_DIR_NAME = \".grip-native-quarantine\";\n\nfunction normalizePath(path: string): string {\n\treturn toNamespacedPath(resolve(path));\n}\n\nfunction getQuarantineRoot(packageDir: string): string | undefined {\n\tlet current = resolve(packageDir);\n\twhile (true) {\n\t\tif (basename(current).toLowerCase() === \"node_modules\") {\n\t\t\treturn join(current, QUARANTINE_DIR_NAME);\n\t\t}\n\t\tconst parent = dirname(current);\n\t\tif (parent === current) {\n\t\t\treturn undefined;\n\t\t}\n\t\tcurrent = parent;\n\t}\n}\n\nfunction getLoadedSharedObjectsInPackageDir(packageDir: string): string[] {\n\tconst sharedObjects = (process.report.getReport() as { sharedObjects?: unknown }).sharedObjects;\n\tif (!Array.isArray(sharedObjects)) {\n\t\treturn [];\n\t}\n\n\tconst root = normalizePath(packageDir).toLowerCase();\n\tconst seen = new Set<string>();\n\tconst loadedFiles: string[] = [];\n\tfor (const value of sharedObjects) {\n\t\tif (typeof value !== \"string\") {\n\t\t\tcontinue;\n\t\t}\n\t\tconst filePath = normalizePath(value);\n\t\tconst comparisonPath = filePath.toLowerCase();\n\t\tif (getCwdRelativePath(comparisonPath, root) === undefined || seen.has(comparisonPath)) {\n\t\t\tcontinue;\n\t\t}\n\t\tseen.add(comparisonPath);\n\t\tloadedFiles.push(filePath);\n\t}\n\treturn loadedFiles;\n}\n\nexport function cleanupWindowsSelfUpdateQuarantine(packageDir: string): void {\n\tconst quarantineRoot = getQuarantineRoot(packageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\ttry {\n\t\trmSync(quarantineRoot, { recursive: true, force: true });\n\t} catch {\n\t\t// A previous grip process may still be exiting and holding a native addon.\n\t}\n}\n\nexport function quarantineWindowsNativeDependencies(packageDir: string): void {\n\tconst resolvedPackageDir = normalizePath(packageDir);\n\tconst quarantineRoot = getQuarantineRoot(resolvedPackageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\n\tconst loadedFiles = getLoadedSharedObjectsInPackageDir(resolvedPackageDir);\n\tif (loadedFiles.length === 0) {\n\t\treturn;\n\t}\n\n\tconst quarantineRunDir = join(quarantineRoot, `${Date.now()}-${process.pid}-${randomUUID()}`);\n\tfor (const loadedFile of loadedFiles) {\n\t\tif (!existsSync(loadedFile)) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst quarantinePath = join(quarantineRunDir, relative(resolvedPackageDir, loadedFile));\n\t\tmkdirSync(dirname(quarantinePath), { recursive: true });\n\t\trenameSync(loadedFile, quarantinePath);\n\t\tcopyFileSync(quarantinePath, loadedFile);\n\t}\n}\n"]}

package/dist/utils/windows-self-update.js

@@ -0,0 +1,77 @@
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, toNamespacedPath } from "node:path";
+import { getCwdRelativePath } from "./paths.js";
+const QUARANTINE_DIR_NAME = ".grip-native-quarantine";
+function normalizePath(path) {
+    return toNamespacedPath(resolve(path));
+}
+function getQuarantineRoot(packageDir) {
+    let current = resolve(packageDir);
+    while (true) {
+        if (basename(current).toLowerCase() === "node_modules") {
+            return join(current, QUARANTINE_DIR_NAME);
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+function getLoadedSharedObjectsInPackageDir(packageDir) {
+    const sharedObjects = process.report.getReport().sharedObjects;
+    if (!Array.isArray(sharedObjects)) {
+        return [];
+    }
+    const root = normalizePath(packageDir).toLowerCase();
+    const seen = new Set();
+    const loadedFiles = [];
+    for (const value of sharedObjects) {
+        if (typeof value !== "string") {
+            continue;
+        }
+        const filePath = normalizePath(value);
+        const comparisonPath = filePath.toLowerCase();
+        if (getCwdRelativePath(comparisonPath, root) === undefined || seen.has(comparisonPath)) {
+            continue;
+        }
+        seen.add(comparisonPath);
+        loadedFiles.push(filePath);
+    }
+    return loadedFiles;
+}
+export function cleanupWindowsSelfUpdateQuarantine(packageDir) {
+    const quarantineRoot = getQuarantineRoot(packageDir);
+    if (!quarantineRoot) {
+        return;
+    }
+    try {
+        rmSync(quarantineRoot, { recursive: true, force: true });
+    }
+    catch {
+        // A previous grip process may still be exiting and holding a native addon.
+    }
+}
+export function quarantineWindowsNativeDependencies(packageDir) {
+    const resolvedPackageDir = normalizePath(packageDir);
+    const quarantineRoot = getQuarantineRoot(resolvedPackageDir);
+    if (!quarantineRoot) {
+        return;
+    }
+    const loadedFiles = getLoadedSharedObjectsInPackageDir(resolvedPackageDir);
+    if (loadedFiles.length === 0) {
+        return;
+    }
+    const quarantineRunDir = join(quarantineRoot, `${Date.now()}-${process.pid}-${randomUUID()}`);
+    for (const loadedFile of loadedFiles) {
+        if (!existsSync(loadedFile)) {
+            continue;
+        }
+        const quarantinePath = join(quarantineRunDir, relative(resolvedPackageDir, loadedFile));
+        mkdirSync(dirname(quarantinePath), { recursive: true });
+        renameSync(loadedFile, quarantinePath);
+        copyFileSync(quarantinePath, loadedFile);
+    }
+}
+//# sourceMappingURL=windows-self-update.js.map

package/dist/utils/windows-self-update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-self-update.js","sourceRoot":"","sources":["../../src/utils/windows-self-update.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from \"node:fs\";\nimport { basename, dirname, join, relative, resolve, toNamespacedPath } from \"node:path\";\nimport { getCwdRelativePath } from \"./paths.ts\";\n\nconst QUARANTINE_DIR_NAME = \".grip-native-quarantine\";\n\nfunction normalizePath(path: string): string {\n\treturn toNamespacedPath(resolve(path));\n}\n\nfunction getQuarantineRoot(packageDir: string): string | undefined {\n\tlet current = resolve(packageDir);\n\twhile (true) {\n\t\tif (basename(current).toLowerCase() === \"node_modules\") {\n\t\t\treturn join(current, QUARANTINE_DIR_NAME);\n\t\t}\n\t\tconst parent = dirname(current);\n\t\tif (parent === current) {\n\t\t\treturn undefined;\n\t\t}\n\t\tcurrent = parent;\n\t}\n}\n\nfunction getLoadedSharedObjectsInPackageDir(packageDir: string): string[] {\n\tconst sharedObjects = (process.report.getReport() as { sharedObjects?: unknown }).sharedObjects;\n\tif (!Array.isArray(sharedObjects)) {\n\t\treturn [];\n\t}\n\n\tconst root = normalizePath(packageDir).toLowerCase();\n\tconst seen = new Set<string>();\n\tconst loadedFiles: string[] = [];\n\tfor (const value of sharedObjects) {\n\t\tif (typeof value !== \"string\") {\n\t\t\tcontinue;\n\t\t}\n\t\tconst filePath = normalizePath(value);\n\t\tconst comparisonPath = filePath.toLowerCase();\n\t\tif (getCwdRelativePath(comparisonPath, root) === undefined || seen.has(comparisonPath)) {\n\t\t\tcontinue;\n\t\t}\n\t\tseen.add(comparisonPath);\n\t\tloadedFiles.push(filePath);\n\t}\n\treturn loadedFiles;\n}\n\nexport function cleanupWindowsSelfUpdateQuarantine(packageDir: string): void {\n\tconst quarantineRoot = getQuarantineRoot(packageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\ttry {\n\t\trmSync(quarantineRoot, { recursive: true, force: true });\n\t} catch {\n\t\t// A previous grip process may still be exiting and holding a native addon.\n\t}\n}\n\nexport function quarantineWindowsNativeDependencies(packageDir: string): void {\n\tconst resolvedPackageDir = normalizePath(packageDir);\n\tconst quarantineRoot = getQuarantineRoot(resolvedPackageDir);\n\tif (!quarantineRoot) {\n\t\treturn;\n\t}\n\n\tconst loadedFiles = getLoadedSharedObjectsInPackageDir(resolvedPackageDir);\n\tif (loadedFiles.length === 0) {\n\t\treturn;\n\t}\n\n\tconst quarantineRunDir = join(quarantineRoot, `${Date.now()}-${process.pid}-${randomUUID()}`);\n\tfor (const loadedFile of loadedFiles) {\n\t\tif (!existsSync(loadedFile)) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst quarantinePath = join(quarantineRunDir, relative(resolvedPackageDir, loadedFile));\n\t\tmkdirSync(dirname(quarantinePath), { recursive: true });\n\t\trenameSync(loadedFile, quarantinePath);\n\t\tcopyFileSync(quarantinePath, loadedFile);\n\t}\n}\n"]}

package/docs/compaction.md

@@ -0,0 +1,408 @@
+# Compaction & Branch Summarization
+
+LLMs have limited context windows. When conversations grow too long, Grip uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+
+**Source files** (this checkout; upstream repository links are not Grip destinations):
+- [`compaction.ts`](../src/core/compaction/compaction.ts) - Auto-compaction logic
+- [`branch-summarization.ts`](../src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`utils.ts`](../src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
+- [`session/types.ts`](../src/core/session/types.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+- [`extensions/types.ts`](../src/core/extensions/types.ts) - Extension event types
+
+For TypeScript definitions in your project, inspect `node_modules/@greppleai/grip/dist/` after installing that package from a verified source.
+
+## Overview
+
+Grip has two summarization mechanisms:
+
+| Mechanism | Trigger | Purpose |
+|-----------|---------|---------|
+| Compaction | Context exceeds threshold, or `/compact` | Summarize old messages to free up context |
+| Branch summarization | `/tree` navigation | Preserve context when switching branches |
+
+Both use structured summaries. Branch summarization tracks file operations; default compaction does not append file lists.
+
+### Agent-initiated range compression
+
+Agent-initiated compression is **disabled by default**. Use `/context-compression on` for the current session, or `GRIP_CONTEXT_COMPRESSION=1` for all agents started in that environment. `/context-compression off` disables the tool and cancels any in-flight detector request. Without arguments, the command reports status. Session toggles survive `/reload` but do not change future-session defaults. Explicit tool allowlists and no-tools modes remain authoritative. Automatic compaction and `/compact` are unchanged.
+
+The built-in `compress_context` tool lets the agent replace at least two messages in the active conversation with its own summary, independently of automatic or manual compaction. Pass `startEntryId` and `summary` to replace from that entry through the last entry **before the current user request**, or add an inclusive `endEntryId` to replace an earlier bounded range and retain later messages. The triggering user request, assistant tool call, and brief completion result stay visible after the summary. The tool call must be the only call in its assistant message; the replacement takes effect after its result is recorded. A bounded range must include complete tool-call/result groups.
+
+When `compress_context` is active, the provider also receives model-only context metadata after each user message and after each completed batch of tool results. It gives persisted user, assistant tool-call, and tool-result entry IDs, **not** a context percentage; tool-result IDs are for lookup, not compression cut points. These notices are not shown in the TUI or saved to session history, and tool-result batches remain contiguous for provider compatibility. Choose a user or assistant cut point from this metadata. `session_search` defaults to entries in the current model context; use `scope: "branch"` or `scope: "all"` to retrieve older history for reference, but replaced or archived IDs are not valid cut points. The primary agent is prompted to consider compression when a task changes, an investigation or implementation slice finishes, or validation has completed and older raw logs are no longer needed—not at a context-percentage threshold.
+Grip appends a `compress_context` custom message with an explicit inclusive `startEntryId`/`endEntryId` replacement range. The JSONL remains append-only: context reconstruction projects the summary at the selected range, removes its original entries from model context, and preserves the later entries and their IDs in order without replaying them. A range may include the latest standard compaction summary and its retained messages; the projection respects their model-visible order. The TUI replaces the selected transcript range with a green `[compress_context]` summary and refreshes the context-utilization footer. The originals remain accessible through `session_entry_get` or `session_search` with `scope: "branch"` or `scope: "all"`; only context-scope search excludes them. Compression cannot start at a tool result or split a tool call from its results. Preserve important user instructions, decisions, and current file state in the summary.
+
+### Optional background compression detection
+
+Background detection is **disabled by default**, even with a saved model selection. Use `/compress-detection-model` to choose a separate, preferably inexpensive model and enable detection (and compression) for the current session. `/compress-detection-model provider/model-id` selects one directly; `/compress-detection-model clear` clears the saved model and disables detection. Selection is saved in `compressionDetectionModel` in global settings and does not switch the primary agent's model.
+
+Use `/compress-detection on` to enable detection with the saved model for this session, or `/compress-detection off` to disable it without clearing the selection or disabling compression. Without arguments, the command reports status. Set `GRIP_CONTEXT_COMPRESSION_DETECTION=1` to enable detection and compression for all agents started in that environment; a configured `compressionDetectionModel` is still required. `GRIP_CONTEXT_COMPRESSION=1` alone does not enable detection. With no model selection, Grip makes **no detection requests**.
+
+At turn boundaries, a rise of at least five context percentage points **after context reaches 15%**, or ten new incoming messages (user messages and tool results, not assistant responses) since the previous check schedules a detector request, whichever happens first. The ten-message trigger also works below 15% or when context usage is unknown. After compression, the percentage trigger starts from the rebuilt context rather than zero; if usage is temporarily unknown, the first available post-compaction reading becomes the baseline. The primary agent waits for the check, read-only session lookups, and any corrective request before continuing to its next model request. A new model request also waits if a detector check from the previous run is still in flight; aborting the agent releases that wait. If context grows while a request is in flight, Grip coalesces the latest observation and rechecks before the agent proceeds. The detector receives the primary agent's system prompt as reference data, the full active conversation in message order (including complete tool results and multimodal content), current active entry IDs, and the **single current context percentage in its final question** (or `unknown` if unavailable). Messages are not excerpted or truncated by the detector; choose a model with a context window and input modalities large enough for the active session. It can use `session_search` and `session_entry_get` to verify facts and cut points, with a shared limit of four read-only calls across the initial decision and corrective retry. Tool results are capped at 8,000 characters for the detector; other tools (including file mutation and `compress_context`) are not available. Detector tool calls and results are not added to the main session history.
+It is asked for an urgency score from 0–100 (priority for the next safe checkpoint, **not** confidence) and a verdict such as `CONTINUE urgency=12%`, `COMPRESS urgency=85%`, or `COMPRESS startEntryId endEntryId urgency=85%` to suggest an inclusive bounded range. Verdicts without a score are accepted if the model omits one; invalid scores over 100 are rejected. If it answers `COMPRESS` without IDs or suggests an invalid or stale range, Grip gives it the validation reason and current branch IDs for one corrective model request. An unsuccessful retry keeps a range-free `COMPRESS` advisory, retaining the original urgency when available. During an active run, a `COMPRESS` verdict is queued as a steering message for the next turn; if the run has already ended or the agent is waiting to start its first request, its advisory is attached to the next model request instead. The advisory includes the scored urgency when available, but never the measured context percentage. These messages are model-visible but not saved to session history. Suggested IDs are checked again against the current branch before delivery and are **not** executed automatically. The agent decides when and what to compress. Detection and corrective requests consume tokens on the chosen model.
+The footer's `D<keep>/<compress> C<n>` indicators show successful detector `CONTINUE` and `COMPRESS` verdicts across the entire session file, followed by the number of completed `compress_context` operations (including archived branches; replayed records count once). Failed, canceled, and invalid detector responses are excluded from verdict counts; detector counts remain visible after disabling detection and do not reset on context compaction or reload. Detector provider responses (model, stop reason, reported catalog cost) and accepted verdicts (including optional urgency and validated suggested range IDs) are persisted as `compression_detection_event` custom entries. These records do not enter the primary model context; replayed records count once. `total ↑… ↓… R… W…` reports **cumulative provider-reported primary-model usage**, persisted as context-excluded ledger checkpoints across branch changes; replayed copies do not count again. Existing sessions bootstrap primary-model usage from their stored responses, but detector activity before these records were introduced cannot be recovered. `ctx ~N/window (P%)` estimates only the **current active context**, which can shrink after compression. `catalog $X (sub)` is a hypothetical catalog price on a subscription, not an additional charge. `(detect est $X total)` separately reports cumulative persisted detector catalog cost, including invalid verdicts; canceled requests without a response cannot contribute reported cost. `/session` also shows lifetime primary-model totals.
+
+### Compression economics estimates
+
+Before presenting a valid suggested range, Grip estimates its token reduction assuming a summary one quarter the size of the selected content, and gives an approximate number of future requests needed to break even at the primary model's catalog rates. The one-time estimate budgets summary output and its first input, plus a possible cache-miss premium on the **model-visible suffix after the replaced range that was already sent to the model** (including the triggering user request). The new compression tool call and result were not previously cached and are excluded from this premium. The prefix before the range remains unchanged and is not charged a miss. A cache miss is estimated at the ordinary input rate rather than the cache-write rate: automatic caching providers such as OpenAI report newly processed tokens as input, not separate cache writes. The detector also receives the primary model's catalog rates as reference. The agent still decides whether the context is safe to summarize.
+
+After `compress_context`, Grip persists context-excluded economics entries on the active branch. The footer shows `~<tokens> fewer cumulative` across overlapping compressions, and estimated remaining cost `to break even` until subsequent primary-model requests cover the one-time estimate; only then does it show estimated **net** avoided cost. While recovery remains, `(cache ~N/new ~M turns)` compares estimated catch-up requests at the current model's cached-read and uncached input catalog rates; `?` means that rate is unavailable. Replayed responses and responses using a different model are not counted; standard compaction ends accrual for earlier summaries, although past estimates remain in the ledger. Replacing a prior compression summary ends its individual future accrual but retains its historical estimate. Branching away removes the compression economics ledger from the active branch, not the cumulative usage ledger. These are **counterfactual estimates**, not measured savings: token counts use a chars/4 heuristic, cache hits, TTL, pricing, and future requests are uncertain, and subscriptions do not imply cash savings. The session's billed assistant usage includes provider responses across archived branches once, excluding replayed copies; detector cost remains separate.
+
+## Compaction
+
+### When It Triggers
+
+Auto-compaction triggers when:
+
+```
+contextTokens > contextWindow - reserveTokens
+```
+
+By default, `reserveTokens` is 16384 tokens (configurable in `~/.grip/agent/settings.json` or `<project-dir>/.grip/settings.json`). This leaves room for the LLM's response.
+
+You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
+
+### How It Works
+
+1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.grip/agent/settings.json` or `<project-dir>/.grip/settings.json`) is reached
+2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
+3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
+4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
+5. **Reload**: Session reloads, using summary + messages from `firstKeptEntryId` onwards
+
+```
+Before compaction:
+
+  entry:  0     1     2     3      4     5     6      7      8     9
+        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
+                └────────┬───────┘ └──────────────┬──────────────┘
+               messagesToSummarize            kept messages
+                                   ↑
+                          firstKeptEntryId (entry 4)
+
+After compaction (new entry appended):
+
+  entry:  0     1     2     3      4     5     6      7      8     9     10
+        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
+        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
+        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
+               └──────────┬──────┘ └──────────────────────┬───────────────────┘
+                 not sent to LLM                    sent to LLM
+                                                         ↑
+                                              starts from firstKeptEntryId
+
+What the LLM sees:
+
+  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
+  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
+  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
+       ↑         ↑      └─────────────────┬────────────────┘
+    prompt   from cmp          messages from firstKeptEntryId
+```
+
+On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Grip also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
+
+### Split Turns
+
+A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. Normally, compaction cuts at turn boundaries.
+
+When a single turn exceeds `keepRecentTokens`, the cut point lands mid-turn at an assistant message. This is a "split turn":
+
+```
+Split turn (one huge turn exceeds budget):
+
+  entry:  0     1     2      3     4      5      6     7      8
+        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
+        │ hdr │ usr │ ass │ tool │ ass │ tool │ tool │ ass │ tool │
+        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴──────┘
+                ↑                                     ↑
+         turnStartIndex = 1                  firstKeptEntryId = 7
+                │                                     │
+                └──── turnPrefixMessages (1-6) ───────┘
+                                                      └── kept (7-8)
+
+  isSplitTurn = true
+  messagesToSummarize = []  (no complete turns before)
+  turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
+```
+
+For split turns, Grip generates two summaries and merges them:
+1. **History summary**: Previous context (if any)
+2. **Turn prefix summary**: The early part of the split turn
+
+### Cut Point Rules
+
+Valid cut points are:
+- User messages
+- Assistant messages
+- BashExecution messages
+- Custom messages (custom_message, branch_summary)
+
+Never cut at tool results (they must stay with their tool call).
+
+### CompactionEntry Structure
+
+Defined in [`session/types.ts`](../src/core/session/types.ts):
+
+```typescript
+interface CompactionEntry<T = unknown> {
+  type: "compaction";
+  id: string;
+  parentId: string;
+  timestamp: number;
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
+  details?: T;         // implementation-specific data
+}
+```
+
+Extensions can store any JSON-serializable data in `details`. Default compaction does not populate this field.
+
+See [`prepareCompaction()`](../src/core/compaction/compaction.ts) and [`compact()`](../src/core/compaction/compaction.ts) for the implementation.
+
+## Branch Summarization
+
+### When It Triggers
+
+When you use `/tree` to navigate to a different branch, Grip offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
+
+### How It Works
+
+1. **Find common ancestor**: Deepest node shared by old and new positions
+2. **Collect entries**: Walk from old leaf back to common ancestor
+3. **Prepare with budget**: Include messages up to token budget (newest first)
+4. **Generate summary**: Call LLM with structured format
+5. **Append entry**: Save `BranchSummaryEntry` at navigation point
+
+```
+Tree before navigation:
+
+         ┌─ B ─ C ─ D (old leaf, being abandoned)
+    A ───┤
+         └─ E ─ F (target)
+
+Common ancestor: A
+Entries to summarize: B, C, D
+
+After navigation with summary:
+
+         ┌─ B ─ C ─ D ─ [summary of B,C,D]
+    A ───┤
+         └─ E ─ F (new leaf)
+```
+
+### Cumulative File Tracking
+
+Branch summarization tracks files cumulatively from tool calls in the messages being summarized and previous branch or legacy compaction `details` (if any). Default compaction no longer stores or appends file lists.
+
+### BranchSummaryEntry Structure
+
+Defined in [`session/types.ts`](../src/core/session/types.ts):
+
+```typescript
+interface BranchSummaryEntry<T = unknown> {
+  type: "branch_summary";
+  id: string;
+  parentId: string;
+  timestamp: number;
+  summary: string;
+  fromId: string;      // Entry we navigated from
+  fromHook?: boolean;  // true if provided by extension (legacy field name)
+  details?: T;         // implementation-specific data
+}
+
+// Default branch summarization uses this for details (from branch-summarization.ts):
+interface BranchSummaryDetails {
+  readFiles: string[];
+  modifiedFiles: string[];
+}
+```
+
+Same as compaction, extensions can store custom data in `details`.
+
+See [`collectEntriesForBranchSummary()`](../src/core/compaction/branch-summarization.ts), [`prepareBranchEntries()`](../src/core/compaction/branch-summarization.ts), and [`generateBranchSummary()`](../src/core/compaction/branch-summarization.ts) for the implementation.
+
+## Summary Format
+
+Both compaction and branch summarization use the same structured sections. Branch summarization can also append file lists:
+
+```markdown
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+- [Requirements mentioned by user]
+
+## Progress
+### Done
+- [x] [Completed tasks]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues, if any]
+
+## Key Decisions
+- **[Decision]**: [Rationale]
+
+## Next Steps
+1. [What should happen next]
+
+## Critical Context
+- [Data needed to continue]
+
+<read-files>
+path/to/file1.ts
+path/to/file2.ts
+</read-files>
+
+<modified-files>
+path/to/changed.ts
+</modified-files>
+```
+
+### Message Serialization
+
+Before summarization, messages are serialized to text via [`serializeConversation()`](../src/core/compaction/utils.ts):
+
+```
+[User]: What they said
+[Assistant thinking]: Internal reasoning
+[Assistant]: Response text
+[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
+[Tool result]: Output from tool
+```
+
+This prevents the model from treating it as a conversation to continue.
+
+Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from `read` and `bash`) are typically the largest contributors to context size.
+
+## Custom Summarization via Extensions
+
+Extensions can intercept and customize both compaction and branch summarization. See [`extensions/types.ts`](../src/core/extensions/types.ts) for event type definitions.
+
+### session_before_compact
+
+Fired before auto-compaction or `/compact`. Can cancel or provide custom summary. See `SessionBeforeCompactEvent` and `CompactionPreparation` in the types file.
+
+```typescript
+grip.on("session_before_compact", async (event, ctx) => {
+  const { preparation, branchEntries, customInstructions, signal } = event;
+
+  // preparation.messagesToSummarize - messages to summarize
+  // preparation.turnPrefixMessages - split turn prefix (if isSplitTurn)
+  // preparation.previousSummary - previous compaction summary
+  // preparation.tokensBefore - context tokens before compaction
+  // preparation.firstKeptEntryId - where kept messages start
+  // preparation.settings - compaction settings
+
+  // branchEntries - all entries on current branch (for custom state)
+  // signal - AbortSignal (pass to LLM calls)
+
+  // Cancel:
+  return { cancel: true };
+
+  // Custom summary:
+  return {
+    compaction: {
+      summary: "Your summary...",
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+      details: { /* custom data */ },
+    }
+  };
+});
+```
+
+#### Converting Messages to Text
+
+To generate a summary with your own model, convert messages to text using `serializeConversation`:
+
+```typescript
+import { convertToLlm, serializeConversation } from "@greppleai/grip";
+
+grip.on("session_before_compact", async (event, ctx) => {
+  const { preparation } = event;
+  
+  // Convert AgentMessage[] to Message[], then serialize to text
+  const conversationText = serializeConversation(
+    convertToLlm(preparation.messagesToSummarize)
+  );
+  // Returns:
+  // [User]: message text
+  // [Assistant thinking]: thinking content
+  // [Assistant]: response text
+  // [Assistant tool calls]: read(path="..."); bash(command="...")
+  // [Tool result]: output text
+
+  // Now send to your model for summarization
+  const summary = await myModel.summarize(conversationText);
+  
+  return {
+    compaction: {
+      summary,
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+    }
+  };
+});
+```
+
+See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a complete example using a different model.
+
+### session_before_tree
+
+Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
+
+```typescript
+grip.on("session_before_tree", async (event, ctx) => {
+  const { preparation, signal } = event;
+
+  // preparation.targetId - where we're navigating to
+  // preparation.oldLeafId - current position (being abandoned)
+  // preparation.commonAncestorId - shared ancestor
+  // preparation.entriesToSummarize - entries that would be summarized
+  // preparation.userWantsSummary - whether user chose to summarize
+
+  // Cancel navigation entirely:
+  return { cancel: true };
+
+  // Provide custom summary (only used if userWantsSummary is true):
+  if (preparation.userWantsSummary) {
+    return {
+      summary: {
+        summary: "Your summary...",
+        details: { /* custom data */ },
+      }
+    };
+  }
+});
+```
+
+See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
+
+## Settings
+
+Configure compaction in `~/.grip/agent/settings.json` or `<project-dir>/.grip/settings.json`:
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Enable auto-compaction |
+| `reserveTokens` | `16384` | Tokens to reserve for LLM response |
+| `keepRecentTokens` | `20000` | Recent tokens to keep (not summarized) |
+
+Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.