@ai-agent-forge/agent-forge 0.85.0

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 { compare, valid } from \"semver\";\nimport { getAgentForgeUserAgent } from \"./agent-forge-user-agent.ts\";\nimport { fetchWithRetry } from \"./management-http.ts\";\n\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n/** Published npm name of the framework (D-075: workspace name differs from the publish name). */\nexport const EXPECTED_PACKAGE_NAME = \"@ai-agent-forge/agent-forge\";\n\nexport interface LatestRelease {\n\tversion: string;\n\tpackageName?: string;\n\tnote?: string;\n}\n\n/** Include useful errno details hidden behind Node's generic \"fetch failed\" error. */\nexport function formatVersionCheckError(error: unknown): string {\n\tconst rootMessage = error instanceof Error && error.message ? error.message : String(error);\n\tconst cause = error instanceof Error ? error.cause : undefined;\n\tconst causes = cause instanceof AggregateError ? cause.errors : cause === undefined ? [] : [cause];\n\tconst codes = causes\n\t\t.map((value) =>\n\t\t\ttypeof value === \"object\" && value !== null && \"code\" in value && typeof value.code === \"string\"\n\t\t\t\t? value.code\n\t\t\t\t: undefined,\n\t\t)\n\t\t.filter((code): code is string => code !== undefined);\n\n\tif (codes.length > 0) return `${rootMessage} (${[...new Set(codes)].join(\", \")})`;\n\tconst causeMessage = causes.find(\n\t\t(value): value is Error => value instanceof Error && Boolean(value.message),\n\t)?.message;\n\treturn causeMessage ? `${rootMessage} (cause: ${causeMessage})` : rootMessage;\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = valid(leftVersion.trim());\n\tconst right = valid(rightVersion.trim());\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\treturn compare(left, right);\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 getLatestRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number; retry?: boolean } = {},\n): Promise<LatestRelease | undefined> {\n\tif (process.env.AGENT_FORGE_OFFLINE) return undefined;\n\tconst versionCheckUrl = process.env.AGENT_FORGE_VERSION_CHECK_URL?.trim();\n\tif (!versionCheckUrl) return undefined;\n\n\tconst response = await fetchWithRetry(\n\t\tversionCheckUrl,\n\t\t{\n\t\t\theaders: {\n\t\t\t\t\"User-Agent\": getAgentForgeUserAgent(currentVersion),\n\t\t\t\taccept: \"application/json\",\n\t\t\t},\n\t\t},\n\t\t{\n\t\t\tmaxRetries: options.retry ? 2 : 0,\n\t\t\ttimeoutMs: options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS,\n\t\t},\n\t);\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as {\n\t\tpackageName?: unknown;\n\t\tversion?: unknown;\n\t\tnote?: unknown;\n\t};\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName =\n\t\ttypeof data.packageName === \"string\" && data.packageName.trim() ? data.packageName.trim() : undefined;\n\tif (packageName !== undefined && packageName !== EXPECTED_PACKAGE_NAME) {\n\t\tthrow new Error(\n\t\t\t`Version service returned an unexpected package name: ${packageName}. Expected ${EXPECTED_PACKAGE_NAME}.`,\n\t\t);\n\t}\n\tconst note = typeof data.note === \"string\" && data.note.trim() ? data.note.trim() : undefined;\n\treturn {\n\t\tversion: data.version.trim(),\n\t\tpackageName,\n\t\t...(note ? { note } : {}),\n\t};\n}\n\nexport async function getLatestVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number; retry?: boolean } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewVersion(currentVersion: string): Promise<LatestRelease | undefined> {\n\tif (process.env.AGENT_FORGE_SKIP_VERSION_CHECK) return undefined;\n\n\ttry {\n\t\tconst latestRelease = await getLatestRelease(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 = \".agent-forge-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 pi 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 = ".agent-forge-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 pi 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 = \".agent-forge-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 pi 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,348 @@
+# Compaction & Branch Summarization
+
+LLMs have limited context windows. When conversations grow too long, Pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+
+**Source files**:
+- [`src/core/compaction/compaction.ts`](../src/core/compaction/compaction.ts) - Auto-compaction logic
+- [`src/core/compaction/branch-summarization.ts`](../src/core/compaction/branch-summarization.ts) - Branch summarization
+- [`src/core/compaction/utils.ts`](../src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
+- [`src/core/session-manager.ts`](../src/core/session-manager.ts) - Entry types (`CompactionEntry`, `BranchSummaryEntry`)
+
+For TypeScript definitions in your project, inspect `node_modules/@agent-forge/agent-forge/dist/`.
+
+## Overview
+
+Pi 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 the same structured summary format and track file operations cumulatively. Compaction and branch-summary requests use fresh routing session IDs and, where supported by the provider, disable prompt-cache writes because these one-off prompts are unlikely to be reused.
+
+## Compaction
+
+### When It Triggers
+
+Auto-compaction triggers when:
+
+```
+contextTokens > contextWindow - reserveTokens
+```
+
+By default, `reserveTokens` is 16384 tokens (configurable in `~/.agent-forge/agent/settings.json` or `<project-dir>/.agent-forge/settings.json`). This leaves room for the LLM's response.
+
+During a multi-turn agent run, Pi checks this threshold after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Pi compacts inside the same agent run and resumes with the summary and retained messages. It skips this between-turn check when the completed tool batch terminates the run and no queued message requires another response. Pi also checks the threshold before a new user prompt and after a low-level agent run ends.
+
+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 `~/.agent-forge/agent/settings.json` or `<project-dir>/.agent-forge/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. **Rebuilds context**: Session rebuilds the context for the next request, 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. Pi 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, Pi 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-manager.ts`](../src/core/session-manager.ts):
+
+```typescript
+interface CompactionEntry<T = unknown> {
+  type: "compaction";
+  id: string;
+  parentId: string;
+  timestamp: number;
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  usage?: Usage;       // LLM usage that generated the summary
+  fromHook?: boolean;  // legacy field name, kept for session file compatibility
+  details?: T;         // implementation-specific data
+}
+
+// Default compaction uses this for details (from compaction.ts):
+interface CompactionDetails {
+  readFiles: string[];
+  modifiedFiles: string[];
+}
+```
+
+Plugins can store any JSON-serializable data in `details`. The default compaction tracks file operations, but custom compaction policies can use their own structure. Generated and policy-provided summaries store their LLM `usage` when available so session totals include summarization work.
+
+See [`prepareCompaction()`](../src/core/compaction/compaction.ts) and [`compact()`](../src/core/compaction/compaction.ts) for the implementation. For direct programmatic summarization, `generateSummary()` returns the summary text and `generateSummaryWithUsage()` returns `{ text, usage }`.
+
+## Branch Summarization
+
+### When It Triggers
+
+When you use `/tree` to navigate to a different branch, Pi 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
+    A ───┤
+         └─ E ─ F ─ [summary of B,C,D] (new leaf)
+```
+
+### Cumulative File Tracking
+
+Both compaction and branch summarization track files cumulatively. When generating a summary, pi extracts file operations from:
+- Tool calls in the messages being summarized
+- Previous compaction or branch summary `details` (if any)
+
+This means file tracking accumulates across multiple compactions or nested branch summaries, preserving the full history of read and modified files.
+
+### BranchSummaryEntry Structure
+
+Defined in [`session-manager.ts`](../src/core/session-manager.ts):
+
+```typescript
+interface BranchSummaryEntry<T = unknown> {
+  type: "branch_summary";
+  id: string;
+  parentId: string;
+  timestamp: number;
+  summary: string;
+  fromId: string;      // Entry we navigated from
+  usage?: Usage;       // LLM usage that generated the summary
+  fromHook?: boolean;  // legacy field name, kept for session file compatibility
+  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, plugins 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 format:
+
+```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 Compaction and Summarization via Capability Plugins
+
+Capability plugins can customize both compaction decisions and summaries by registering policies on the capability API. The types (`CompactionPolicy`, `BranchSummaryPolicy`) are exported from `@agent-forge/agent-forge`.
+
+### registerCompactionPolicy(name, policy)
+
+A `CompactionPolicy` decides when compaction runs and can produce the summary:
+
+- `decide(request)` — receives host-measured facts (`reason` (`"manual"`/`"threshold"`/`"overflow"`), `contextUsage`, `contextOverflow`, `canContinue`, ...), the policy owns the threshold decision. Returns `{ compact: boolean }` plus optional `retry` and `failureMessage`.
+- `summarize(request)` — optional; produces the summary as `{ summary, firstKeptEntryId, tokensBefore, usage?, details? }`. The request carries the summary `model` facts and a host-mediated `invocation` boundary for single-shot completions, so a policy can summarize with its own model flow without importing provider internals. The request also carries `customInstructions` (from `/compact <prompt>`) and the `preparation` object with the host-prepared compaction inputs.
+- `prepare?(request)` — optional hook over the host-prepared compaction inputs.
+
+```typescript
+import type { CapabilityAPI } from "@agent-forge/agent-forge";
+
+export default function (api: CapabilityAPI) {
+  api.registerCompactionPolicy("my-policy", {
+    decide: (request) => ({
+      compact: request.reason === "manual" || request.contextOverflow,
+    }),
+    summarize: async (request) => {
+      // preparation is host-owned and typed `unknown`; narrow the fields you need
+      const preparation = request.preparation as {
+        firstKeptEntryId: string;
+        tokensBefore: number;
+      };
+      const result = await request.invocation.invoke(
+        { version: 1, prompt: "Summarize this conversation", maxTokens: 1024 },
+        request.signal,
+      );
+      if (result.status !== "completed") {
+        throw new Error(result.error.message);
+      }
+      return {
+        summary: result.text,
+        firstKeptEntryId: preparation.firstKeptEntryId,
+        tokensBefore: preparation.tokensBefore,
+        usage: result.usage,
+      };
+    },
+  });
+}
+```
+
+Select a registered policy by name with the `compactionPolicyName` session option; otherwise the default policy runs.
+
+The `custom-compaction.ts` example that showed this pattern with a different model was removed together with the legacy ExtensionAPI (D-064); the removed file remains available in git history.
+
+### registerBranchSummaryPolicy(name, policy)
+
+A `BranchSummaryPolicy` customizes `/tree` branch summaries. `summarize(request)` receives the branch `entries`, summary `model` facts, and the same host-mediated `invocation` boundary, and returns `{ summary?, usage?, readFiles?, modifiedFiles?, aborted?, error? }`.
+
+### Failure outcomes
+
+When compaction fails or is aborted, the host retries according to the summarization retry loop; the failure surfaces through the normal event stream (`summarization_retry_*` events in RPC/JSON modes). There is no separate plugin-facing failure hook.
+
+## Settings
+
+Configure compaction in `~/.agent-forge/agent/settings.json` or `<project-dir>/.agent-forge/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`.

package/docs/containerization.md

@@ -0,0 +1,114 @@
+> **Note:** The gondolin example extension referenced by this guide was removed together with the legacy ExtensionAPI (D-064). The instructions below describe a setup that is no longer shipped in this repository; the removed files remain available in git history and the integration can be rebuilt as a capability plugin.
+
+# Containerization
+
+Agent Forge has `readonly` and `full-control` modes. Use an external isolation boundary when you need control over filesystem, process, network, or credential access beyond those modes.
+
+There are two general options. You can either
+1. run the whole `agent-forge` process inside an isolated environment, or
+2. run `agent-forge` on the host and route tool execution into an isolated environment.
+
+## Choose a pattern
+
+| Pattern | What is isolated | Best for | Notes |
+| --- | --- | --- | --- |
+| Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | Shipped as `examples/extensions/gondolin/` (removed with D-064; restore from git history if needed). |
+| Plain Docker | Whole `agent-forge` process in a local container | Simple local isolation | Provider API keys enter the container. |
+| OpenShell | Whole `agent-forge` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
+
+Plugins run wherever the `agent-forge` process runs. If you run the host process with a tool-routing plugin, other plugin tools still run on the host unless they also delegate their operations.
+
+## Gondolin
+
+[Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
+Use the `examples/extensions/gondolin/` extension when you want `agent-forge` on the host but all built-in tools routed into the VM. It was removed with D-064; restore it from git history if needed.
+
+Setup:
+
+```bash
+# The gondolin example was removed with D-064; restore it from git history before copying.
+cp -R packages/agent-forge/examples/extensions/gondolin ~/.agent-forge/agent/extensions/gondolin
+cd ~/.agent-forge/agent/extensions/gondolin
+npm install --ignore-scripts
+```
+
+Run from the project you want mounted:
+
+```bash
+cd /path/to/project
+agent-forge -e ~/.agent-forge/agent/extensions/gondolin
+```
+
+The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.
+User `!` commands are routed into the VM, as well.
+File changes under `/workspace` write through to the host.
+
+Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU (requires installation through your package manager).
+
+## Plain Docker
+
+Run the whole `agent-forge` process in Docker when you want the simplest local container boundary.
+
+`Dockerfile.agent-forge`:
+
+```dockerfile
+FROM node:24-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
+  && rm -rf /var/lib/apt/lists/*
+RUN npm install -g --ignore-scripts @ai-agent-forge/agent-forge
+
+WORKDIR /workspace
+ENTRYPOINT ["agent-forge"]
+```
+
+Build and run:
+
+```bash
+docker build -t agent-forge-sandbox -f Dockerfile.agent-forge .
+
+docker run --rm -it \
+  -e ANTHROPIC_API_KEY \
+  -v "$PWD:/workspace" \
+  -v agent-forge-agent-home:/root/.agent-forge/agent \
+  agent-forge-sandbox
+```
+
+The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example.
+
+Use a named volume for `/root/.agent-forge/agent` if you want container-local settings and sessions. Mounting your host `~/.agent-forge/agent` exposes host auth and session files to the container.
+
+## OpenShell
+
+Use [NVIDIA OpenShell](https://docs.nvidia.com/openshell/about/overview) when you want a policy-controlled sandbox with filesystem, process, network, credential, and inference controls.
+OpenShell can run sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway.
+
+Every sandbox requires an active gateway.
+Register and select one before creating a sandbox:
+
+```bash
+openshell gateway add <gateway-url> --name <name>
+openshell gateway select <name>
+```
+
+Launch `agent-forge` inside an OpenShell sandbox:
+
+```bash
+openshell sandbox create --name agent-forge-sandbox --from agent-forge -- agent-forge
+```
+
+In this pattern, the whole `agent-forge` process runs inside the sandbox.
+Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary.
+
+If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine.
+Clone the repository inside the sandbox or use OpenShell file transfer commands:
+
+```bash
+openshell sandbox upload agent-forge-sandbox ./repo /workspace
+openshell sandbox download agent-forge-sandbox /workspace/repo ./repo-out
+```
+
+OpenShell providers can keep raw model API keys outside the sandbox.
+When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream.
+Configure Agent Forge to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.

package/docs/development.md

@@ -0,0 +1,71 @@
+# Development
+
+See the repository [AGENTS.md](../../../AGENTS.md) for additional guidelines.
+
+## Setup
+
+```bash
+git clone https://github.com/agent-forge/agent-forge
+cd agent-forge
+npm install
+npm run build
+```
+
+Run from source:
+
+```bash
+/path/to/agent-forge/test.sh
+```
+
+The script can be run from any directory. Agent Forge keeps the caller's current working directory.
+
+## Forking / Rebranding
+
+Configure via `package.json`:
+
+```json
+{
+  "agentForgeConfig": {
+    "name": "agent-forge",
+    "configDir": ".agent-forge"
+  }
+}
+```
+
+Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
+
+## Path Resolution
+
+Three execution modes: npm install, standalone binary, tsx from source.
+
+**Always use `src/config.ts`** for package assets:
+
+```typescript
+import { getPackageDir, getThemeDir } from "./config.js";
+```
+
+Never use `__dirname` directly for package assets.
+
+## Debug Command
+
+`/debug` (hidden) writes debugging data under `~/.agent-forge/agent/`:
+- Rendered TUI lines with ANSI codes
+- Last messages sent to the LLM
+
+## Testing
+
+```bash
+./test.sh                         # Run non-LLM tests (no API keys needed)
+npm test                          # Run all tests
+npm test -- test/specific.test.ts # Run specific test
+```
+
+## Project Structure
+
+```
+packages/
+  ai/           # LLM provider abstraction
+  agent/        # Agent loop and message types  
+  tui/          # Terminal UI components
+  agent-forge/ # CLI and interactive mode
+```