ultimate-pi 0.4.0 → 0.4.1

package/.pi/PACKAGING.md

@@ -13,16 +13,17 @@ Aligned with [pi packages](https://github.com/badlogic/pi-mono/blob/main/package
 Pi does **not** define `scripts`, `agents`, or `providers` in the manifest.
 
 - **Harness scripts** → `.pi/scripts/` — run via `node` / `bash` and `$UP_PKG` (see `.pi/scripts/README.md`); do not require npm script aliases in consumer `package.json`
-- **Subagent agents** → `.pi/agents/**/*.md` on the installed package (`harness/planner`, `pi-pi/agent-expert`, …) via `harness-subagents.ts`; optional **project overrides** at the same relative path under `.pi/agents/`. Version drift: `.pi/harness/agents.manifest.json` (regenerate with `harness-agents-manifest.mjs --write`)
+- **Subagent agents** → `.pi/agents/**/*.md` (loaded by `@tintinweb/pi-subagents` from the **project** `.pi/agents/`; `/harness-setup` seeds them from the installed package)
 - **Providers** → install via `bundledDependencies` + user settings, not a separate manifest directory
 
 ## npm `files` allowlist
 
 We use an explicit allowlist (not the whole `.pi/` tree) so dev-only artifacts never ship:
 
-- No `.pi/harness/runs/`, local `model-router.json`, or `.web/` scrape artifacts
+- No `.pi/harness/runs/`, local `model-router.json`, or `firecrawl/.env`
 - Ship `.pi/settings.example.json`, not `.pi/settings.json` (dev checkout uses `".."` local package)
 - Include **`vendor/pi-model-router/`** ([`pi-model-router`](https://github.com/yeliu84/pi-model-router), MIT) — see repo [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md); refresh with `npm run vendor:sync-router`
+- Include **`vendor/pi-vcc/`** ([`pi-vcc`](https://github.com/sting8k/pi-vcc), MIT; inspired by [lllyasviel/VCC](https://github.com/lllyasviel/VCC)) — loaded via `.pi/extensions/ultimate-pi-vcc.ts`; refresh with `npm run vendor:sync-vcc`
 
 ## Settings
 

package/.pi/extensions/lib/harness-vcc-settings.ts

@@ -0,0 +1,50 @@
+/**
+ * ultimate-pi VCC configuration — env only (no config files).
+ *
+ * @see https://github.com/sting8k/pi-vcc (vendored algorithm)
+ * @see https://github.com/lllyasviel/VCC
+ */
+
+export interface PiVccSettings {
+	/** When true, VCC handles /compact, auto-threshold, and overflow compaction. */
+	overrideDefaultCompaction: boolean;
+	/** Write debug snapshot to /tmp/pi-vcc-debug.json on each compaction. */
+	debug: boolean;
+}
+
+const FALSE_VALUES = new Set(["false", "0", "off", "no"]);
+const TRUE_VALUES = new Set(["true", "1", "on", "yes"]);
+
+function parseHarnessBool(envName: string, defaultValue: boolean): boolean {
+	const raw = process.env[envName]?.trim().toLowerCase();
+	if (!raw) {
+		return defaultValue;
+	}
+	if (FALSE_VALUES.has(raw)) {
+		return false;
+	}
+	if (TRUE_VALUES.has(raw)) {
+		return true;
+	}
+	return defaultValue;
+}
+
+/** Whether VCC overrides Pi built-in LLM compaction (default: true). */
+export function resolveOverrideDefaultCompaction(): boolean {
+	return parseHarnessBool("HARNESS_VCC_COMPACTION", true);
+}
+
+/** Compaction debug snapshots (default: false). */
+export function resolveVccDebug(): boolean {
+	return parseHarnessBool("HARNESS_VCC_DEBUG", false);
+}
+
+export function loadSettings(): PiVccSettings {
+	return {
+		overrideDefaultCompaction: resolveOverrideDefaultCompaction(),
+		debug: resolveVccDebug(),
+	};
+}
+
+/** No-op — harness VCC does not scaffold or read JSON config files. */
+export function scaffoldSettings(): void {}

package/.pi/extensions/ultimate-pi-vcc.ts

@@ -0,0 +1,17 @@
+/**
+ * In-house VCC compaction for ultimate-pi.
+ *
+ * Vendored compaction core from [pi-vcc](https://github.com/sting8k/pi-vcc),
+ * inspired by [VCC](https://github.com/lllyasviel/VCC).
+ *
+ * Configuration is **env-only** (no JSON config files):
+ * - `HARNESS_VCC_COMPACTION` — default on; set `false` for Pi LLM compaction on /compact + auto-compact
+ * - `HARNESS_VCC_DEBUG` — set `true` to write `/tmp/pi-vcc-debug.json` on compaction
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import registerVcc from "../../vendor/pi-vcc/index.js";
+
+export default function ultimatePiVcc(pi: ExtensionAPI): void {
+	registerVcc(pi);
+}

package/.pi/harness/docs/adrs/0030-inhouse-vcc-compaction.md

@@ -0,0 +1,40 @@
+# ADR 0030: In-house VCC compaction (vendored pi-vcc)
+
+- **Status:** Accepted
+- **Date:** 2026-05-17
+- **Deciders:** ultimate-pi harness team
+
+## Context
+
+ultimate-pi depended on the npm package `@sting8k/pi-vcc` for deterministic, view-oriented session compaction (no LLM summarization call). We need that behavior by default for harness sessions, without an external package coupling, while preserving attribution to upstream [pi-vcc](https://github.com/sting8k/pi-vcc) and the conceptual [VCC](https://github.com/lllyasviel/VCC) work.
+
+## Decision
+
+1. Vendor [sting8k/pi-vcc](https://github.com/sting8k/pi-vcc) under `vendor/pi-vcc/` (refresh via `npm run vendor:sync-vcc`), following the same pattern as `vendor/pi-model-router`.
+2. Load compaction through [`.pi/extensions/ultimate-pi-vcc.ts`](../../../extensions/ultimate-pi-vcc.ts).
+3. Remove `@sting8k/pi-vcc` from `package.json` dependencies and from `.pi/settings*.json` `packages` arrays.
+4. **Configuration is env-only** — no JSON config files (`PI_VCC_CONFIG_PATH` and `.pi/pi-vcc-config.json` are not used).
+5. **Default:** `HARNESS_VCC_COMPACTION` unset → VCC overrides Pi built-in LLM compaction for `/compact`, auto-threshold, and overflow.
+6. **Opt-out:** `HARNESS_VCC_COMPACTION=false` (also `0` / `off`) uses Pi’s LLM compaction for those paths; explicit `/pi-vcc` still uses VCC.
+7. **Debug:** `HARNESS_VCC_DEBUG=true` writes `/tmp/pi-vcc-debug.json` on compaction (default off).
+8. Settings implementation: [`.pi/extensions/lib/harness-vcc-settings.ts`](../../../extensions/lib/harness-vcc-settings.ts).
+9. Compaction telemetry `details.compactor` is `ultimate-pi-vcc`.
+
+## Consequences
+
+### Positive
+
+- No runtime dependency on `@sting8k/pi-vcc` npm; vendored tree is pinned and patchable.
+- Harness-default compaction matches ADR intent (deterministic, recall-friendly summaries).
+- Operators can revert to LLM compaction per project via one env var.
+
+### Negative / trade-offs
+
+- Maintainer must run `vendor:sync-vcc` to pick up upstream pi-vcc fixes.
+- Vendored `loadSettings` re-exports harness env settings from `.pi/extensions/lib/` (couples vendor tree to ultimate-pi layout).
+
+## References
+
+- [THIRD_PARTY_NOTICES.md](../../../../THIRD_PARTY_NOTICES.md)
+- [vendor/pi-vcc/UPSTREAM_PIN.md](../../../../vendor/pi-vcc/UPSTREAM_PIN.md)
+- [`.env.example`](../../../../.env.example) — `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG`

package/.pi/harness/docs/adrs/README.md

@@ -15,6 +15,7 @@ Team-shared ADRs for the ultimate-pi harness live under `.pi/harness/docs/adrs/`
 | [0007](0007-interactive-drift-monitor.md) | Interactive drift monitor | Accepted |
 | [0008](0008-harness-posthog-telemetry.md) | Harness PostHog telemetry | Accepted |
 | [0009](0009-sentrux-rules-lifecycle.md) | Sentrux rules.toml lifecycle | Accepted |
+| [0030](0030-inhouse-vcc-compaction.md) | In-house VCC compaction (vendored pi-vcc) | Accepted |
 
 ## Template
 

package/.pi/prompts/harness-setup.md

@@ -343,7 +343,7 @@ Verify each package:
 | `@posthog/pi` | Analytics event capture | F0 |
 | `pi-lean-ctx` | Context runtime (read/bash/find/grep/MCP bridge) | F0 |
 | `harness-subagents` (bundled extension) | L4 sub-agent spawn, blackboard, package agents | P16 |
-| `@sting8k/pi-vcc` | VCC compaction / conversation memory | Shipped |
+| Vendored `pi-vcc` (`vendor/pi-vcc`, `.pi/extensions/ultimate-pi-vcc.ts`) | VCC compaction / `vcc_recall` — env-only: `HARNESS_VCC_COMPACTION` (default on), `HARNESS_VCC_DEBUG` | Shipped |
 | `pi-model-router` | Vendored (`vendor/`); activates after `.pi/model-router.json` exists | F0 |
 
 ## Step 3.5 — Model Router Configuration (Dynamic)
@@ -428,7 +428,7 @@ Rules:
 - Re-runs only add keys from `$UP_PKG/.pi/harness/env.harness.template` that are absent (managed block at EOF).
 - Ensure `.env` is gitignored (Step 4.1).
 
-Template keys (placeholders — user fills secrets): `HARNESS_TELEMETRY_ENABLED`, `HARNESS_WEB_*`, `PI_VCC_CONFIG_PATH`, plus commented optional PostHog / Graphify vars.
+Template keys (placeholders — user fills secrets): `HARNESS_TELEMETRY_ENABLED`, `HARNESS_WEB_*`, `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG`, plus commented optional PostHog / Graphify vars.
 
 ### 4.1 — .gitignore Entries
 

package/.pi/scripts/vendor-pi-vcc-settings.stub.ts

@@ -0,0 +1,8 @@
+/**
+ * ultimate-pi harness settings (env-only). Re-exported for vendored pi-vcc layout.
+ */
+export type { PiVccSettings } from "../../../../.pi/extensions/lib/harness-vcc-settings.js";
+export {
+	loadSettings,
+	scaffoldSettings,
+} from "../../../../.pi/extensions/lib/harness-vcc-settings.js";

package/.pi/scripts/vendor-sync-pi-vcc.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Re-fetch upstream pi-vcc and re-apply ultimate-pi patches.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+VEND="$ROOT/vendor/pi-vcc"
+SETTINGS_STUB="$ROOT/.pi/scripts/vendor-pi-vcc-settings.stub.ts"
+
+rm -rf "$VEND"
+git clone --depth 1 https://github.com/sting8k/pi-vcc.git "$VEND"
+COMMIT="$(git -C "$VEND" rev-parse HEAD)"
+rm -rf "$VEND/.git"
+
+# Env-only settings (no JSON config files)
+cp "$SETTINGS_STUB" "$VEND/src/core/settings.ts"
+
+# Drop config scaffolding on extension load
+sed -i '/scaffoldSettings/d' "$VEND/index.ts"
+sed -i '/import.*scaffoldSettings/d' "$VEND/index.ts"
+
+# Telemetry / compaction details label
+sed -i 's/compactor: "pi-vcc";/compactor: "pi-vcc" | "ultimate-pi-vcc";/' "$VEND/src/details.ts"
+sed -i 's/compactor: "pi-vcc"/compactor: "ultimate-pi-vcc"/' "$VEND/src/hooks/before-compact.ts"
+
+cat >"$VEND/UPSTREAM_PIN.md" <<EOF
+# Vendored \`pi-vcc\`
+
+- **Repository:** https://github.com/sting8k/pi-vcc
+- **Conceptual basis:** [lllyasviel/VCC](https://github.com/lllyasviel/VCC) (View-oriented Conversation Compiler)
+- **License:** MIT (see upstream repository)
+- **Pinned upstream commit:** \`$COMMIT\`
+- **Local changes:**
+  - \`src/core/settings.ts\` re-exports env-only [\`harness-vcc-settings\`](../../.pi/extensions/lib/harness-vcc-settings.ts) (\`HARNESS_VCC_COMPACTION\`, \`HARNESS_VCC_DEBUG\`)
+  - No \`scaffoldSettings\` / no \`PI_VCC_CONFIG_PATH\`
+  - Compaction \`details.compactor\` is \`ultimate-pi-vcc\`
+
+**Refresh upstream:** run \`npm run vendor:sync-vcc\` from ultimate-pi root.
+EOF
+
+rm -f "$VEND/package-lock.json"
+echo "✓ Vendor refreshed at $VEND (commit $COMMIT)"

package/.pi/settings.example.json

@@ -3,10 +3,5 @@
 		"enabled": true,
 		"maxRetries": 3
 	},
-	"packages": [
-		"npm:ultimate-pi",
-		"npm:@posthog/pi",
-		"npm:context-mode",
-		"npm:@sting8k/pi-vcc"
-	]
+	"packages": ["npm:ultimate-pi", "npm:@posthog/pi", "npm:context-mode"]
 }

package/CHANGELOG.md

@@ -2,17 +2,19 @@
 
 All notable changes to this project are documented in this file.
 
-## [v0.4.0] — 2026-05-16
+## [Unreleased]
 
-### ⚠️ Breaking Changes
-
-- **Firecrawl removed**: deleted self-hosted `firecrawl/` Docker stack and all `firecrawl*` agent skills. Web fetch/search now uses **`harness-web`** (Scrapling). Artifact dir is **`.web/`** (not `.firecrawl/`). Remove `FIRECRAWL_API_KEY` / `FIRECRAWL_API_URL`; use `uv tool install "scrapling[fetchers]"` and `scrapling install` per `/harness-setup`.
-- **Harness web CLI**: `python3 "$UP_PKG/.pi/scripts/harness-web.py" search|scrape|map|bulk-scrape` — see `.agents/skills/scrapling-web/SKILL.md`.
+## [v0.4.1] — 2026-05-17
 
 ### ✨ Features
 
-- **harness-web**: Scrapling-backed search (DuckDuckGo HTML SERP) and scrape (`StealthyFetcher` default; `--fast` for static HTTP). Modules under `.pi/scripts/harness_web/`.
-- **Harness subagents**: vendored harness-subagents extension and Sentrux bootstrap (`#125`).
+- **In-house VCC compaction:** vendored [pi-vcc](https://github.com/sting8k/pi-vcc) (inspired by [lllyasviel/VCC](https://github.com/lllyasviel/VCC)); removed `@sting8k/pi-vcc` npm dependency. Configuration is **env-only** (`HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG`) — no `PI_VCC_CONFIG_PATH` or JSON config files. VCC overrides `/compact` and auto-compaction by default; set `HARNESS_VCC_COMPACTION=false` for Pi LLM compaction. Refresh upstream: `npm run vendor:sync-vcc`.
+- **Harness subagents:** vendored harness-subagents extension with Sentrux bootstrap agent and related harness wiring.
+- **Harness web:** replace Firecrawl with Scrapling-based `harness-web` CLI for search and fetch.
+
+### 🔧 Chores
+
+- Format `.pi/settings.json` / `.pi/settings.example.json` and refresh `graphify-out` after VCC merge.
 
 ## [v0.3.1] — 2026-05-15
 

package/THIRD_PARTY_NOTICES.md

@@ -1,30 +1,16 @@
 # Third-party notices
 
-## Design references (not vendored)
-
-The in-house `ask_user` harness extension (`.pi/extensions/harness-ask-user.ts`) borrows **behavior and UX patterns only** from these projects. No code from them is bundled.
-
-| Project | License | Reference |
-|---------|---------|-----------|
-| [pi-ask-user](https://github.com/edlsh/pi-ask-user) | MIT | Overlay/inline modes, SelectList + Editor, custom renderCall/renderResult, headless fallback |
-| [@pi-unipi/ask-user](https://cdn.jsdelivr.net/npm/@pi-unipi/unipi@2.0.1/packages/ask-user/README.md) | (package docs) | Tool contract: `question`, `context`, `options`, `allowMultiple`, `allowFreeform` |
-| [rpiv-ask-user-question](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question) | MIT | Rich option rows, decision-handshake policy text, structured answer envelope |
-
-## @tintinweb/pi-subagents (vendored in harness-subagents)
-
-- **Project:** https://github.com/tintinweb/pi-subagents  
-- **Version pinned:** 0.7.3 (source vendored under `.pi/extensions/lib/harness-subagents/vendored/`)  
-- **License:** MIT  
-- **Notes:** Adapted for `@mariozechner/pi-coding-agent` in ultimate-pi `harness-subagents` extension. Agent discovery replaced with package-root recursive loader.
-
-## subagent-v2 reference (design only)
-
-- **Path:** `raw/references/subagents/extensions/subagent-v2/`  
-- **License:** Treat as third-party reference; not shipped in npm `files`. Blackboard, supervisor, and isolated session patterns were ported into `harness-subagents` without copying the earendil-works Pi stack.
-
 ## pi-model-router (vendored)
 
 - **Project:** https://github.com/yeliu84/pi-model-router  
 - **License:** MIT ([vendor/pi-model-router/LICENSE](vendor/pi-model-router/LICENSE))  
 - **Pinned revision:** See [vendor/pi-model-router/UPSTREAM_PIN.md](vendor/pi-model-router/UPSTREAM_PIN.md)  
 - ultimate-pi loads it from [`vendor/pi-model-router`](vendor/pi-model-router); import specifiers were adapted for `@mariozechner/pi-coding-agent` and related Pi packages.
+
+## pi-vcc (vendored)
+
+- **Project:** https://github.com/sting8k/pi-vcc  
+- **Conceptual basis:** https://github.com/lllyasviel/VCC (View-oriented Conversation Compiler)  
+- **License:** MIT (see upstream repository)  
+- **Pinned revision:** See [vendor/pi-vcc/UPSTREAM_PIN.md](vendor/pi-vcc/UPSTREAM_PIN.md)  
+- ultimate-pi loads it from [`vendor/pi-vcc`](vendor/pi-vcc) via [`.pi/extensions/ultimate-pi-vcc.ts`](.pi/extensions/ultimate-pi-vcc.ts). Harness configuration is env-only: `HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG` ([`.pi/extensions/lib/harness-vcc-settings.ts`](.pi/extensions/lib/harness-vcc-settings.ts)). Maintainer refresh: `npm run vendor:sync-vcc`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ultimate-pi",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"description": "Ultimate AI coding harness for pi.dev — extensible skills, Obsidian wiki knowledge layer, compressed context, deterministic output",
 	"keywords": [
 		"pi-package",
@@ -60,7 +60,6 @@
 		".pi/settings.example.json",
 		".pi/auto-commit.json",
 		".pi/mcp.json",
-		".pi/pi-vcc-config.json",
 		".pi/SYSTEM.md",
 		".pi/PACKAGING.md",
 		"AGENTS.md",
@@ -68,21 +67,24 @@
 		"CHANGELOG.md",
 		"README.md",
 		"THIRD_PARTY_NOTICES.md",
-		"vendor/pi-model-router"
+		"vendor/pi-model-router",
+		"vendor/pi-vcc"
 	],
 	"peerDependencies": {
 		"@mariozechner/pi-coding-agent": "*"
 	},
 	"scripts": {
-		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts",
+		"check:ts": "tsc --noEmit --target ES2023 --lib ES2023 --moduleResolution nodenext --module nodenext --skipLibCheck .pi/extensions/lib/harness-vcc-settings.ts .pi/extensions/dotenv-loader.ts .pi/extensions/lib/posthog-node.d.ts .pi/extensions/lib/harness-posthog.ts .pi/extensions/lib/harness-paths.ts .pi/extensions/pi-model-router-harness.ts .pi/extensions/provider-payload-sanitize.ts .pi/extensions/harness-telemetry.ts .pi/extensions/harness-ask-user.ts .pi/extensions/lib/ask-user/schema.ts .pi/extensions/lib/ask-user/types.ts .pi/extensions/lib/ask-user/validate.ts .pi/extensions/lib/ask-user/dialog.ts .pi/extensions/lib/ask-user/fallback.ts .pi/extensions/lib/ask-user/render.ts .pi/extensions/trace-recorder.ts .pi/extensions/observation-bus.ts .pi/extensions/drift-monitor.ts .pi/extensions/sentrux-rules-sync.ts .pi/extensions/custom-header.ts .pi/extensions/lib/harness-subagents/agent-loader.ts .pi/extensions/lib/harness-subagents/agent-parser.ts .pi/extensions/lib/harness-subagents/agent-manifest.ts .pi/extensions/lib/harness-subagents/blackboard.ts .pi/extensions/lib/harness-subagents/blackboard-tool.ts .pi/extensions/lib/harness-subagents/spawn-policy.ts .pi/extensions/lib/harness-subagents/types-blackboard.ts",
 		"vendor:sync-router": "bash .pi/scripts/vendor-sync-pi-model-router.sh",
+		"vendor:sync-vcc": "bash .pi/scripts/vendor-sync-pi-vcc.sh",
 		"release": "bash .pi/scripts/release.sh",
 		"lint": "biome check",
 		"lint:fix": "biome check --fix",
 		"format": "biome format --write",
 		"format:check": "biome format",
 		"prepare": "lefthook install",
-		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/sentrux-rules-sync.test.mjs",
+		"test": "node --test test/harness-verify.test.mjs test/harness-ask-user.test.mjs test/harness-subagents-loader.test.mjs test/sentrux-rules-sync.test.mjs && npx -y tsx --test test/harness-vcc-settings.test.ts",
+		"test:vcc": "npx -y tsx --test vendor/pi-vcc/tests/*.test.ts",
 		"harness:sentrux-bootstrap": "node .pi/scripts/harness-sentrux-bootstrap.mjs",
 		"harness:sentrux-sync": "node .pi/scripts/sentrux-rules-sync.mjs --force",
 		"test:integration": "npx -y tsx --test test/cursor-sdk-provider.integration.test.ts"
@@ -99,7 +101,6 @@
 	},
 	"dependencies": {
 		"@posthog/pi": "latest",
-		"@sting8k/pi-vcc": "^0.3.12",
 		"asciify-image": "^0.1.10",
 		"croner": "^9.0.0",
 		"jimp": "^1.6.1",

package/vendor/pi-vcc/README.md

@@ -0,0 +1,215 @@
+# pi-vcc
+
+[![npm](https://img.shields.io/npm/v/@sting8k/pi-vcc)](https://www.npmjs.com/package/@sting8k/pi-vcc)
+
+Algorithmic conversation compactor for [Pi](https://github.com/badlogic/pi-mono). No LLM calls — produces a brief transcript via extraction and formatting.
+
+Inspired by [VCC](https://github.com/lllyasviel/VCC) **(View-oriented Conversation Compiler)**.
+
+## Demo
+
+![pi-vcc demo](./demo.gif)
+
+## Why pi-vcc
+
+|  | Pi default | pi-vcc |
+|---|---|---|
+| **Method** | LLM-generated summary | Algorithmic extraction, no LLM |
+| **Determinism** | Non-deterministic, can hallucinate | Same input = same output, always |
+| **Token reduction** | Varies | 35-99% on real sessions (higher on longer sessions) |
+| **Compaction latency** | Waits for LLM call | 30-470ms, no API calls |
+| **History after compaction** | Gone — agent only sees summary | Active lineage searchable via `vcc_recall` (`scope:"all"` available) |
+| **Repeated compactions** | Each rewrite risks losing more | Sections merge and accumulate |
+| **Cost** | Burns tokens on summarization call | Zero — no API calls |
+| **Structure** | Free-form prose | Brief transcript + 4 semantic sections |
+
+### Real session metrics
+
+Measured on real session JSONLs under `~/.pi/agent/sessions` (chars = rendered message text).
+
+| Session | Messages | Before | After | Reduction | Time |
+|---|---|---|---|---|---|
+| Session A | 2,943 | 997,162 | 7,959 | 99.2% | 64ms |
+| Session B | 1,703 | 428,334 | 7,762 | 98.2% | 29ms |
+| Session C | 1,657 | 424,183 | 9,577 | 97.7% | 54ms |
+| Session D | 1,004 | 2,258,477 | 4,439 | 99.8% | 30ms |
+| Session E | 486 | 295,006 | 11,163 | 96.2% | 30ms |
+| Session F | 46 | 5,234 | 3,364 | 35.7% | 5ms |
+| Session G | 27 | 8,595 | 2,489 | 71.0% | 2ms |
+
+## Features
+
+- **No LLM** — purely algorithmic, zero extra API cost
+- **Brief transcript** — chronological conversation flow, each tool call collapsed to a one-liner with `(#N)` refs, text truncated to keep it compact
+- **5 semantic sections** — session goal, files & changes, commits, outstanding context, user preferences
+- **Bounded merge** — rolling sections re-capped after merge instead of growing unbounded
+- **Lossless recall** — `vcc_recall` reads raw session JSONL, so active-lineage history stays searchable across compactions
+- **Scoped recall** — default search is active lineage; use `scope:"all"` / `scope:all` to intentionally search across all lineages
+- **Regex search** — `vcc_recall` supports regex patterns (`hook|inject`, `fail.*build`) and OR-ranked multi-word queries
+- **Result ranking** — search results ranked by term relevance, rare terms weighted higher than common ones
+- **`/pi-vcc-recall`** — slash command to search history directly, results shown as collapsible message and auto-fed to agent as context
+- **Fallback cut** — still works when Pi core returns nothing to summarize
+- **`/pi-vcc`** — manual compaction on demand
+
+## Install
+
+```bash
+pi install npm:@sting8k/pi-vcc
+```
+
+Or from GitHub:
+
+```bash
+pi install https://github.com/sting8k/pi-vcc
+```
+
+Or try without installing:
+
+```bash
+pi -e https://github.com/sting8k/pi-vcc
+```
+
+## Usage
+
+Once installed, pi-vcc registers a `session_before_compact` hook.
+
+- Run `/pi-vcc` to trigger pi-vcc compaction manually.
+- By default, `/compact` and auto-threshold compactions still go through pi core (LLM-based). Set `overrideDefaultCompaction: true` in the config to let pi-vcc handle all compaction paths.
+- To search older active-lineage history after compaction, use `vcc_recall`.
+- To intentionally search across all lineages, pass `scope:"all"` to `vcc_recall` or run `/pi-vcc-recall <query> scope:all`.
+- To search and feed results to agent yourself, run `/pi-vcc-recall <query> [page:N]`.
+  - Tip: type `/recall` and Pi will autocomplete to `/pi-vcc-recall`.
+
+### How compaction works
+
+Pi splits the conversation at the **last user message**. Everything after — the **kept tail** — stays intact and untouched. pi-vcc only summarizes the older portion before that cut point.
+
+### Compacted message structure
+
+```
+[Session Goal]
+- Fix the authentication bug in login flow
+- [Scope change]
+- Also update the session token refresh logic
+
+[Files And Changes]
+- Modified: src/auth/session.ts
+- Created: tests/auth-refresh.test.ts
+
+[Commits]
+- a1b2c3d: fix(auth): refresh token after password reset
+
+[Outstanding Context]
+- lint check still failing on line 42
+
+[User Preferences]
+- Prefer Vietnamese responses
+- Always run tests before committing
+
+[user]
+Fix the auth bug, users can't log in after password reset
+
+[assistant]
+Root cause is a missing token refresh after password reset...
+* bash "bun test tests/auth.test.ts" (#12)
+* edit "src/auth/session.ts" (#14)
+* bash "bun test tests/auth.test.ts" (#16)
+...(28 earlier lines omitted)
+```
+
+Sections appear only when relevant — a session with no git commits won't have `[Commits]`.
+
+**Sections:**
+
+| Section | Description |
+|---|---|
+| `[Session Goal]` | Initial goal + scope changes (regex-based extraction) |
+| `[Files And Changes]` | Modified/created files from tool calls (capped, paths trimmed to common root) |
+| `[Commits]` | Git commits made during the session (last 8, hash + first line) |
+| `[Outstanding Context]` | Unresolved items — errors, pending questions |
+| `[User Preferences]` | Regex-extracted from user messages (`always`, `never`, `prefer`...) |
+| Brief transcript | Chronological conversation flow — rolling window of ~120 recent lines, tool calls collapsed to one-liners with `(#N)` refs |
+
+**Merge policy:**
+- `Session Goal`, `User Preferences`: concise sticky sections
+- `Outstanding Context`: fresh-only (replaced each compaction)
+- `Files And Changes`, `Commits`: unique union across compactions
+- Brief transcript: rolling window, older lines drop off
+
+## Recall (Lossless History)
+
+Pi's default compaction discards old messages permanently. After compaction, the agent only sees the summary.
+
+`vcc_recall` bypasses this by reading the raw session JSONL file directly. By default it searches only the active conversation lineage, regardless of how many compactions have happened. Use `scope:"all"` only when you intentionally want to include off-lineage branches.
+
+### Search
+
+Queries support **regex** and **multi-word OR logic** ranked by relevance:
+
+```
+vcc_recall({ query: "auth token" })                         // active-lineage OR search, ranked
+vcc_recall({ query: "auth token", page: 2 })                // paginated (5 results/page)
+vcc_recall({ query: "hook|inject" })                         // regex pattern
+vcc_recall({ query: "fail.*build" })                         // regex pattern
+vcc_recall({ query: "auth token", scope: "all" })           // search all lineages
+```
+
+Manual slash command:
+
+```
+/pi-vcc-recall auth token scope:all
+```
+
+### Browse
+
+Without a query, returns the last 25 entries as brief summaries:
+
+```
+vcc_recall()
+vcc_recall({ scope: "all" })  // browse recent entries across all lineages
+```
+
+### Expand
+
+Returns full untruncated content for specific indices found via search:
+
+```
+vcc_recall({ expand: [41, 42] })                 // active-lineage expand
+vcc_recall({ expand: [41, 42], scope: "all" })   // expand across all lineages
+```
+
+Typical workflow: **search → find relevant entry indices → expand those indices for full content**.
+
+> Some tool results are truncated by Pi core at save time. `expand` returns everything in the JSONL but can't recover what Pi already cut.
+
+## Pipeline
+
+1. **Normalize** — raw Pi messages → uniform blocks (user, assistant, tool_call, tool_result, thinking)
+2. **Filter noise** — strip system messages, empty blocks
+3. **Build sections** — extract goal, file paths, blockers, preferences
+4. **Brief transcript** — chronological conversation flow, tool calls collapsed to one-liners, text truncated
+5. **Format** — render into bracketed sections + transcript
+6. **Merge** — if previous summary exists: sticky sections merge, volatile sections replace, transcript rolls
+
+## Config
+
+Config lives at `~/.pi/agent/pi-vcc-config.json` (auto-scaffolded on first load with safe defaults):
+
+```json
+{
+  "overrideDefaultCompaction": false,
+  "debug": false
+}
+```
+
+- **`overrideDefaultCompaction`** *(default `false`)*: when `false`, pi-vcc only runs for `/pi-vcc`; `/compact` and auto-threshold compactions fall through to pi core. Set `true` to make pi-vcc handle all compaction paths.
+- **`debug`** *(default `false`)*: when `true`, each compaction writes detailed info to `/tmp/pi-vcc-debug.json` — message counts, cut boundary, summary preview, sections.
+
+## Related Work
+
+- [VCC](https://github.com/lllyasviel/VCC) — the original transcript-preserving conversation compiler
+- [Pi](https://github.com/badlogic/pi-mono) — the AI coding agent this extension is built for
+
+## License
+
+MIT

package/vendor/pi-vcc/UPSTREAM_PIN.md

@@ -0,0 +1,12 @@
+# Vendored `pi-vcc`
+
+- **Repository:** https://github.com/sting8k/pi-vcc
+- **Conceptual basis:** [lllyasviel/VCC](https://github.com/lllyasviel/VCC) (View-oriented Conversation Compiler)
+- **License:** MIT (see upstream repository)
+- **Pinned upstream commit:** `3e0b49e4ef605370e3dd92889e6b70502262cc28`
+- **Local changes:**
+  - `src/core/settings.ts` re-exports env-only [`.pi/extensions/lib/harness-vcc-settings.ts`](../../.pi/extensions/lib/harness-vcc-settings.ts) (`HARNESS_VCC_COMPACTION`, `HARNESS_VCC_DEBUG`)
+  - No `scaffoldSettings` / no `PI_VCC_CONFIG_PATH`
+  - Compaction `details.compactor` is `ultimate-pi-vcc`
+
+**Refresh upstream:** run `npm run vendor:sync-vcc` from ultimate-pi root.

package/vendor/pi-vcc/index.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerBeforeCompactHook } from "./src/hooks/before-compact";
+import { registerPiVccCommand } from "./src/commands/pi-vcc";
+import { registerVccRecallCommand } from "./src/commands/vcc-recall";
+import { registerRecallTool } from "./src/tools/recall";
+
+export default (pi: ExtensionAPI) => {
+  registerBeforeCompactHook(pi);
+  registerPiVccCommand(pi);
+  registerVccRecallCommand(pi);
+  registerRecallTool(pi);
+};

package/vendor/pi-vcc/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@sting8k/pi-vcc",
+  "version": "0.3.13",
+  "description": "Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls",
+  "main": "index.ts",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "vcc",
+    "compact",
+    "compaction"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sting8k/pi-vcc.git"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}