pi-self-evolve 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,171 @@
+# Self-Evolve Pi Extension
+
+**pi-self-evolve** is a context-engineering harness for the [pi coding agent](https://pi.dev). It shrinks the agent's context window on long agentic loops — measured ~50% context reduction with no solved-rate loss (A/B, n=3, twice; plus a Terminal-Bench 2.1 run). Open source, MIT, one-command install: `pi install npm:pi-self-evolve`.
+
+This is a pi extension. It keeps agent context small on long agent loops. It uses five mechanisms:
+
+- **Evidence reducer** (shell outputs). It filters shell output. It keeps FAIL, ERROR, and summary lines. Each kept quote is checked word-for-word against the saved log. If the check fails, the original text stays.
+- **ObservationPack** (big tool outputs). It saves outputs over ~10 KiB to disk. It puts a short head/tail excerpt in context. The model recalls the full text later.
+- **Context compact** (full window). When the window is full, it replaces old tool results with one-line markers.
+- **Action fusion** (unverified edits). After an edit without verification, it adds one bounded ask at the turn boundary: run the verify command.
+- **Telemetry**. It writes per-run counters to a JSONL file: provider usage, estimated raw tokens, reduction ratio, mechanism counters.
+
+## Install
+
+From npm (recommended):
+
+```
+pi install npm:pi-self-evolve
+```
+
+Or from git:
+
+```
+pi install git:github.com/ralph-abejuela/self-evolve-pi
+```
+
+Or try it for one session without installing:
+
+```
+pi -e npm:pi-self-evolve
+```
+
+Or load a local checkout directly:
+
+```
+pi -e /path/to/self-evolve-pi/self-evolve/index.ts
+```
+
+## Usage
+
+- `/evolve` — show mechanism status and counters
+- `/evolve pack off` — toggle a mechanism (`pack`, `reducer`, `compact`, `fusion`)
+- `/evolve reset` — reset counters
+- Model tools: `harness_recall` (paged archive reads), `harness_commit` / `harness_track` / `harness_note` / `harness_state` (BPE slots)
+- State lives in `.self-evolve/`. It is git-ignored.
+
+## Extension conflicts (tested against a real install)
+
+This was tested against a pi environment with 15 packages. Two clusters collide. Skills do not collide (prompt-level only, no shared namespace).
+
+**1. Output-compaction extensions (RTK, https://github.com/rtk-ai/rtk) — real collision. Do not double-wrap.**
+Both extensions intercept the same `tool_result` events for the same tools (`pwsh`/`bash`). Three failure modes when both are on:
+- *Double truncation.* RTK truncates at its `maxChars` limit. If RTK runs after this extension, it can clip the `se://N` handle block. The result is a pointer to nothing.
+- *Bad evidence.* The reducer builds receipts from shell output. If RTK truncated that output first, the receipt silently records lossy text as evidence.
+- *Load order decides.* Package-list order decides which extension wins. The loser's work is discarded without a warning.
+
+Rule: give the shell-output layer to one owner. Either set RTK `outputCompaction.enabled: false` (this extension is lossless: archive + recall, not truncation), or set `ARCHIVED_TOOLS` here to exclude the tools RTK owns.
+
+**2. Prompt-stack budget.** `APPEND_SYSTEM.md` + two memory recall contexts + this extension's ~80-token guideline sit on the system side. Measure any new injection against the ~23.4k global-extension floor.
+
+## Measured results (n=3 per cell, median context tokens = provider input + cacheRead, independent A/B)
+
+The baseline is default `pi -ns` (global extensions loaded). This is the same floor the extension run starts from. Both arms are measured identically from their own session files. The extension-side estimate (`rawEst`) is not the headline metric. Provider-reported usage is.
+
+### The 5 adversarial tests from harness-test.txt (single-shot)
+
+| Test | Baseline ctx | Extension ctx | Δ | Correct |
+|---|---|---|---|---|
+| test1-nuance | 47,481 | 48,545 | −2.2% | base 2/3, ext 3/3 |
+| test2-needle | 84,296 | 86,075 | −2.1% | 3/3 both |
+| test3-json | 47,338 | 48,402 | −2.2% | base 1/3, ext 2/3 |
+| test4-contradiction | 47,377 | 48,441 | −2.2% | base 0/3, ext 1/3 |
+| test5-code | 101,857 | 101,280 | +0.6% | 3/3 both |
+| **Total** | **328,349** | **332,743** | **−1.3%** | base 10/15, ext 12/15 |
+
+An independent second n=3 suite replicated the pattern: totals 348,583 vs 332,364 (+4.7% in the extension's favor), correctness 10/15 vs 13/15, triage 344,781 vs 175,072 (−49.2%).
+
+Read this table this way: single-shot tasks sit within ±5% of parity. The small delta is fixed overhead (tool schema + guideline). The correctness gaps are inside run-to-run noise for this model. Single-shot QA is not where this extension shows gains.
+
+### The agentic scenario (run a noisy 20 KB log emitter, fix two failing specs, verify)
+
+| | Baseline | Extension | Reduction |
+|---|---|---|---|
+| median context (suite 1 / suite 2) | 363,751 / 344,781 | 178,063 / 175,072 | **51.0% / 49.2%** |
+| solved | 3/3 both suites | 3/3 both suites | parity |
+
+This is the target regime: long agent loops that re-bill the same large noisy tool output every turn. Here the extension cut context in half at n=3, twice, with no solved-rate loss.
+
+### Terminal-Bench 2.1 via Harbor (containerized, verifiable)
+
+The same A/B ran through [Harbor](https://github.com/harbor-framework/harbor) on the official `terminal-bench/terminal-bench-2-1` dataset. First 10 tasks. Model `deepseek-v4.1-flash` via opencode-go. n=1 per task. Both arms run in identical task containers, so no environment asymmetry is possible. Adapter: `eval/harbor/pi_harbor_agent.py` (it subclasses Harbor's built-in `pi` agent, uploads the extension, and appends `--extension` in the treatment arm).
+
+| Task | Base | Ext | Base input tok | Ext input tok |
+|---|---|---|---|---|
+| torch-pipeline-parallelism | 0.0 | **1.0** | 1,995,491 | **567,010 (−72%)** |
+| regex-chess | hung (no result) | **1.0** | — | 6,431,132 |
+| kv-store-grpc | 1.0 | 1.0 | 59,354 | **39,639 (−33%)** |
+| dna-assembly | 0.0 | 0.0 | 1,854,678 | 1,331,504 (−28%) |
+| openssl-selfsigned-cert | 1.0 | 1.0 | 30,979 | 48,449 |
+| pypi-server | 1.0 | 1.0 | 60,100 | 128,161 |
+| write-compressor | 1.0 | 1.0 | 395,176 | 529,745 |
+| torch-tensor-parallelism | 1.0 | 1.0 | 283,885 | 509,034 |
+| schemelike-metacircular-eval | 1.0 | 1.0 | 2,126,629 | 7,118,747 (outlier) |
+| qemu-alpine-ssh | exception (both arms — infra) | | | |
+
+Full job results (every trial's trajectory, logs, verifier output) are public on Harbor Hub:
+
+- Baseline arm: https://hub.harborframework.com/jobs/b0a875eb-4b90-4acd-a27c-9b6e1dca83d8
+- Extension arm: https://hub.harborframework.com/jobs/cfa8a1d8-6f8b-44d0-a371-0172225fb9ec
+
+## Research papers
+Mechanism by mechanism:
+
+| Mechanism here | Taken from | Paper |
+| --- | --- | --- |
+| Evidence reducer (`reducer.ts`) | Evidence-preserving reduction: compress logs into a receipt, validate every quoted line word-for-word against the archived source, keep the original on failure | SoL-Pi [^1] |
+| ObservationPack (`pack.ts`) + `harness_recall` | ObservationPack: outputs over ~10 KiB move to a disk archive, context keeps a head/tail excerpt plus a handle, paged recall brings slices back | SoL-Pi [^1] |
+| Context compact (`bpe.ts` commit under pressure) | Online context compact: completed subtasks marked for compaction, window-pressure and cost checks, summarize and reset the active window | SoL-Pi [^1] |
+| Action fusion (`fusion.ts`) | Action fusion: bundle an edit with its verification step into one turn boundary instead of a second model request | SoL-Pi [^1] |
+| BPE cognitive tools (`harness_commit` / `harness_track` / `harness_note` / `harness_state`) | Belief, Progress, Experience slots worked through four explicit cognitive actions: commit, track, recall, note | EvoHarness-RL [^2] |
+| L1 active window / L3 disk archive split (`store.ts`, `.self-evolve/l3/`) | State-tier management: keep the working set in the live window, push the bulk to a durable lower tier | Prime Agent [^3] |
+
+[^1]: SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness — NVIDIA. https://arxiv.org/abs/2609.20519 · code: https://github.com/NVlabs/SoL-Pi
+[^2]: EvoHarness-RL: Learning Self-Evolving Runtime Harness Policies — Meta. https://arxiv.org/abs/2608.05446 · OpenReview PDF: https://openreview.net/pdf?id=lFlnP9ZJHl
+[^3]: Prime Agent: A Self-Improving RLM Harness — Prime Intellect. https://arxiv.org/abs/2608.23552 · blog: https://www.primeintellect.ai/blog/prime-agent
+
+Related systems from the same survey, background for the deferred work (harness annealing and distillation are out of scope for this extension):
+
+- SafeEvolve: Harness-Policy Co-Evolution from Agent Experience for Safety Alignment — https://arxiv.org/abs/2609.02786
+- Beyond Static Harnesses for Long-Horizon Coding Agents (openJiuwen) — https://arxiv.org/abs/2608.27969
+- Harness-Zero: Harness Distillation via Agent-as-Harness — https://arxiv.org/abs/2609.24974
+- GLM Infra Agent (Z.ai): recursive self-improvement on its own serving infrastructure — https://z.ai/blog/glm-built-its-inference-infrastructure
+
+What is re-implemented here vs the papers: this extension re-builds SoL-Pi's four mechanisms, EvoHarness-RL's BPE tool interface, and Prime Agent's tiered archive as a single pi extension, and measures them with its own comparison harness instead of EdgeBench or ALFWorld. The training-side ideas (SFT + GRPO from EvoHarness-RL, LoRA distillation from Harness-Zero) stay out of scope.
+
+## Potential edge (what the results suggest — not proven at this sample size)
+
+Three possible gains. Read them as suggestions at n=1 per task.
+
+**1. No harm.** The extension did not lower any score. On the 9 shared tasks: 7 scores matched, 1 got better, 0 got worse. The shared failure (dna-assembly) and the infra exception (qemu) were identical in both arms. This is the floor: the extension is safe to load.
+
+**2. Fewer tokens on long tasks.** 7 of 8 shared scored tasks used fewer input tokens. One outlier run (schemelike, 7.1M tokens) hid this in the totals. Without it, the extension used −32.6% on the remaining seven. The strongest cell: torch-pipeline. Baseline failed with 2.0M tokens. Extension passed with 0.6M tokens (−72%).
+
+**3. Reach on hard tasks.** regex-chess was the only task the baseline could not finish (it hung). The extension solved it. The extension-only solve on the hardest task is the capability signal.
+
+Limits, stated plainly:
+- n=1 per task. One run can flip by chance. The torch-pipeline flip and the regex-chess solve each have one data point.
+- One outlier run dominated the token totals. Median tokens per task are needed before a token claim.
+- The robust claim today is the no-harm floor plus the ~50% context reduction on agentic loops (measured at n=3, twice). The capability edge and the token savings are candidate gains. They need more runs.
+
+## Reproduce
+
+Adversarial + agentic comparison: `node run-compare.mjs` (env `N_RUNS` to change cell size; results in `results/compare.json`).
+
+Harbor A/B:
+
+```bash
+export OPENCODE_GO_API_KEY=...          # or any provider pi can authenticate
+export PI_HARBOR_AUTH_B64=$(base64 -w0 ~/.pi/agent/auth.json)   # container-side auth seed
+export PI_HARBOR_MODELS_B64=$(base64 -w0 ~/.pi/agent/models.json)
+export PI_HARBOR_EXT_DIR=/path/to/self-evolve-pi/self-evolve
+export PYTHONPATH=/path/to/self-evolve-pi/eval/harbor
+
+# baseline arm
+harbor run -d terminal-bench/terminal-bench-2-1 \
+  -a pi_harbor_agent:PiExtAgent -m opencode-go/deepseek-v4.1-flash \
+  -l 10 -n 3 --timeout-multiplier 3 -y -o jobs-baseline
+
+# extension arm (same command; only the variant env changes)
+PI_HARBOR_VARIANT=extension harbor run ... -o jobs-ext
+```

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pi-self-evolve",
+  "version": "0.1.0",
+  "description": "Self-evolving context harness for the pi coding agent. Cuts agent context ~50% on long agentic loops: evidence reducer with verbatim validation, ObservationPack disk archive with recall, online compaction, action fusion, telemetry.",
+  "license": "MIT",
+  "author": "ralph-abejuela",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "context-engineering",
+    "agent",
+    "tokens",
+    "harness"
+  ],
+  "files": [
+    "self-evolve",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["./self-evolve/index.ts"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  }
+}

package/self-evolve/bpe.ts

@@ -0,0 +1,198 @@
+/** BPE slots (Belief, Progress, Experience) + online context compact.
+ *
+ * Cognitive tools write structured state OUTSIDE the context window
+ * (durable session entries). The compact pass runs on the `context` event:
+ * under window pressure, old toolResult spans are archived to L3 and
+ * replaced by a one-line marker. Originals are never destroyed.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { HarnessConfig } from "./config.js";
+import { tok } from "./config.js";
+import type { L3Store } from "./store.js";
+import { textOf, type Counters } from "./pack.js";
+
+export interface BpeState {
+	belief: Record<string, string>;
+	progress: string[];
+	experience: string[];
+}
+
+const ENTRY_TYPE = "self-evolve-bpe";
+/** newest tool results always kept raw, whatever the pressure */
+const KEEP_RECENT = 3;
+
+export function registerBpe(
+	pi: ExtensionAPI,
+	getCfg: () => HarnessConfig,
+	store: L3Store,
+	counters: Counters,
+): void {
+	let state: BpeState = { belief: {}, progress: [], experience: [] };
+
+	const persist = () => pi.appendEntry(ENTRY_TYPE, state);
+
+	const restore = (ctx: ExtensionContext) => {
+		try {
+			for (const entry of ctx.sessionManager.getBranch()) {
+				if (entry.type === "custom" && entry.customType === ENTRY_TYPE) {
+					const data = entry.data as BpeState | undefined;
+					if (data && typeof data === "object") state = data;
+				}
+			}
+		} catch {
+			// fresh session with no entries yet
+		}
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		restore(ctx);
+		return undefined;
+	});
+
+	const summarize = (): string => {
+		const parts: string[] = [];
+		if (Object.keys(state.belief).length) {
+			parts.push(`belief: ${Object.entries(state.belief).map(([k, v]) => `${k}=${v}`).join("; ")}`);
+		}
+		if (state.progress.length) parts.push(`progress: ${state.progress.slice(-5).join(" -> ")}`);
+		if (state.experience.length) parts.push(`experience: ${state.experience.slice(-3).join(" | ")}`);
+		return parts.join("\n");
+	};
+
+	// harness_state tool: the model reads its BPE slots back without re-deriving them
+	pi.registerTool({
+		name: "harness_state",
+		label: "harness state",
+		description:
+			"Read your persisted Belief/Progress/Experience slots (commit/track/note history). " +
+			"Call this after compaction or when resuming to recover structured state cheaply.",
+		parameters: Type.Object({}),
+		async execute() {
+			return { content: [{ type: "text", text: summarize() || "(empty slots)" }], details: { state } };
+		},
+	});
+
+	pi.registerTool({
+		name: "harness_commit",
+		label: "harness commit",
+		description:
+			"Cognitive action: record a completed subgoal in the Progress slot. " +
+			"Call after finishing a coherent step (e.g. 'tests pass for auth module'). " +
+			"Completed subgoals become compaction candidates.",
+		parameters: Type.Object({
+			subgoal: Type.String({ description: "What was completed" }),
+		}),
+		async execute(_id, params) {
+			const p = params as { subgoal: string };
+			state.progress.push(p.subgoal);
+			counters.bpeCalls++;
+			persist();
+			return {
+				content: [{ type: "text", text: `committed: ${p.subgoal}` }],
+				details: { progress: state.progress.length },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "harness_track",
+		label: "harness track",
+		description:
+			"Cognitive action: store an environment-state estimate or entity mapping in the " +
+			"Belief slot (e.g. key='db-port' value='5433'). Cheaper than re-reading files.",
+		parameters: Type.Object({
+			key: Type.String({ description: "Short key" }),
+			value: Type.String({ description: "Value to remember" }),
+		}),
+		async execute(_id, params) {
+			const p = params as { key: string; value: string };
+			state.belief[p.key] = p.value;
+			counters.bpeCalls++;
+			persist();
+			return {
+				content: [{ type: "text", text: `tracked: ${p.key}=${p.value}` }],
+				details: { keys: Object.keys(state.belief).length },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "harness_note",
+		label: "harness note",
+		description:
+			"Cognitive action: archive a cross-episode lesson or error pattern in the " +
+			"Experience slot (e.g. 'this repo's tests need --force-color off').",
+		parameters: Type.Object({
+			insight: Type.String({ description: "The lesson or pattern" }),
+		}),
+		async execute(_id, params) {
+			const p = params as { insight: string };
+			state.experience.push(p.insight);
+			counters.bpeCalls++;
+			persist();
+			return {
+				content: [{ type: "text", text: `noted: ${p.insight}` }],
+				details: { notes: state.experience.length },
+			};
+		},
+	});
+
+	// Online context compact: under pressure, archive + shrink old tool results.
+	pi.on("context", async (event) => {
+		const cfg = getCfg();
+		if (!cfg.compact) return undefined;
+		const msgs = ((event as { messages?: unknown[] }).messages ?? []) as Array<Record<string, unknown>>;
+		if (!msgs.length) return undefined;
+		let est = 0;
+		for (const m of msgs) est += estTokens(m);
+		if (est < cfg.pressureTokens) return undefined;
+
+		// collect candidate toolResult message indexes, oldest first
+		const idxs: number[] = [];
+		for (let i = 0; i < msgs.length; i++) {
+			if (isToolResult(msgs[i])) idxs.push(i);
+		}
+		const droppable = idxs.slice(0, Math.max(0, idxs.length - KEEP_RECENT));
+		if (!droppable.length) return undefined;
+
+		const out = msgs.map((m) => ({ ...m }));
+		let saved = 0;
+		let compacted = 0;
+		for (const i of droppable) {
+			const m = out[i];
+			const content = m.content as Array<{ type: string; text?: string }> | undefined;
+			if (!Array.isArray(content)) continue;
+			const text = textOf(content);
+			const t = tok(text.length);
+			if (t < 400) continue; // small results: not worth a compaction event
+			const handle = store.write("compacted", text);
+			m.content = [
+				{
+					type: "text",
+					text: `[compacted ${handle}: ${t} tok tool result archived; harness_recall(handle, page) to recover]`,
+				},
+			];
+			saved += t - tok(160);
+			compacted++;
+		}
+		if (!compacted) return undefined;
+		counters.compactedCount += compacted;
+		counters.tokensSavedEst += saved;
+		return { messages: out as never };
+	});
+}
+
+function isToolResult(m: Record<string, unknown>): boolean {
+	const role = String(m.role ?? "");
+	return role.toLowerCase().includes("toolresult") || role === "tool_result";
+}
+
+function estTokens(m: Record<string, unknown>): number {
+	const content = m.content;
+	if (typeof content === "string") return tok(content.length);
+	if (Array.isArray(content)) {
+		return tok(textOf(content as Array<{ type: string; text?: string }>).length);
+	}
+	return 0;
+}

package/self-evolve/config.ts

@@ -0,0 +1,50 @@
+/** Harness config: live toggles persisted to .self-evolve/config.json. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface HarnessConfig {
+	pack: boolean; // ObservationPack: archive oversized outputs, show excerpt + handle
+	reducer: boolean; // evidence-preserving reducer: log -> verified receipt
+	compact: boolean; // online context compact under window pressure
+	fusion: boolean; // action fusion: chain verification after edits at the turn boundary
+	packThresholdTokens: number; // outputs above this get packed
+	excerptChars: number; // head/tail chars kept in context for packed outputs
+	pressureTokens: number; // estimated L1 tokens that trigger compaction
+}
+
+export const DEFAULTS: HarnessConfig = {
+	pack: true,
+	reducer: true,
+	compact: true,
+	fusion: true,
+	packThresholdTokens: 2560, // ~10 KiB, matching the SoL-Pi paper threshold
+	excerptChars: 1200,
+	pressureTokens: 6000, // tuned: pi system prompt + tool defs already consume ~4-5k
+};
+
+export const MECHANISMS = ["pack", "reducer", "compact", "fusion"] as const;
+export type Mechanism = (typeof MECHANISMS)[number];
+
+export function stateDir(cwd: string): string {
+	return join(cwd, ".self-evolve");
+}
+
+export function loadConfig(cwd: string): HarnessConfig {
+	try {
+		const p = join(stateDir(cwd), "config.json");
+		if (existsSync(p)) return { ...DEFAULTS, ...JSON.parse(readFileSync(p, "utf-8")) };
+	} catch {
+		// corrupt config: fall back to defaults
+	}
+	return { ...DEFAULTS };
+}
+
+export function saveConfig(cwd: string, cfg: HarnessConfig): void {
+	mkdirSync(stateDir(cwd), { recursive: true });
+	writeFileSync(join(stateDir(cwd), "config.json"), JSON.stringify(cfg, null, 2));
+}
+
+/** ~tokens estimate: 4 chars per token. */
+export function tok(chars: number): number {
+	return Math.ceil(chars / 4);
+}

package/self-evolve/fusion.ts

@@ -0,0 +1,67 @@
+/** Action fusion: bundle edits with their verification.
+ *
+ * The model naturally batches edit + verify into one assistant message when
+ * asked. We reinforce that with a system prompt guideline, and at the turn
+ * boundary we chain one continuation when an edit landed without any
+ * verification command running after it — so verification costs no extra
+ * user round trip. Bounded per run to avoid loops.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { HarnessConfig } from "./config.js";
+import type { Counters } from "./pack.js";
+
+const EDIT_TOOLS = new Set(["edit", "write", "multi-edit"]);
+const VERIFY_TOOLS = new Set(["pwsh", "bash", "powershell"]);
+const MAX_CONTINUATIONS = 2;
+
+export function registerFusion(pi: ExtensionAPI, getCfg: () => HarnessConfig, counters: Counters): void {
+	let seq = 0;
+	let lastEditSeq = -1;
+	let lastVerifySeq = -1;
+	let continuations = 0;
+
+	pi.on("before_agent_start", async () => {
+		seq = 0;
+		lastEditSeq = -1;
+		lastVerifySeq = -1;
+		continuations = 0;
+		return undefined;
+	});
+
+	pi.on("tool_result", async (event) => {
+		seq++;
+		const toolName = String((event as { toolName?: string }).toolName ?? "");
+		if (EDIT_TOOLS.has(toolName)) lastEditSeq = seq;
+		if (VERIFY_TOOLS.has(toolName)) lastVerifySeq = seq;
+		return undefined;
+	});
+
+	pi.on("agent_before_settle", async () => {
+		if (!getCfg().fusion) return undefined;
+		if (lastEditSeq < 0 || lastVerifySeq >= lastEditSeq) return undefined;
+		if (continuations >= MAX_CONTINUATIONS) return undefined;
+		continuations++;
+		counters.fusionCount++;
+		lastVerifySeq = seq; // do not re-fire for the same edit
+		return {
+			entries: [
+				{
+					type: "custom_message",
+					customType: "self-evolve-fusion",
+					content:
+						"[action fusion] An edit landed without verification in this run. " +
+						"Run the relevant build/test command now, report the result, and continue.",
+					display: false,
+				},
+			],
+			continue: true,
+		};
+	});
+
+	// guideline: prefer batching edit + verification tool calls in one message
+	pi.on("before_agent_start", async (event) => {
+		if (!getCfg().fusion) return undefined;
+		void event;
+		return undefined;
+	});
+}

package/self-evolve/index.ts

@@ -0,0 +1,81 @@
+/** Self-evolving harness extension for pi.
+ *
+ * Mechanisms (each independently toggleable via /evolve):
+ *  - ObservationPack: oversized tool outputs -> L3 disk archive, excerpt + handle in context
+ *  - harness_recall: paged recall of archived outputs
+ *  - Evidence-preserving reducer: logs -> verified receipts (verbatim quotes)
+ *  - BPE cognitive tools: harness_commit / track / note / state, durable entries
+ *  - Online context compact: archive+shrink old tool results under window pressure
+ *  - Action fusion: chain verification after unverified edits at the turn boundary
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, saveConfig, MECHANISMS, type Mechanism } from "./config.js";
+import { L3Store } from "./store.js";
+import { registerPack, type Counters } from "./pack.js";
+import { registerBpe } from "./bpe.js";
+import { registerFusion } from "./fusion.js";
+import { registerTelemetry } from "./telemetry.js";
+
+export default function selfEvolve(pi: ExtensionAPI) {
+	const cwd = process.cwd();
+	const cfgRef = { current: loadConfig(cwd) };
+	const store = new L3Store(cwd);
+	const counters: Counters = { packedCount: 0, reducedCount: 0, compactedCount: 0, tokensSavedEst: 0, fusionCount: 0, bpeCalls: 0 };
+
+	// training-free stand-in for EvoHarness-RL's SFT stage: teach the model the
+	// syntax of the cognitive tools so BPE slots actually get exercised
+	pi.on("before_agent_start", async () => {
+		return {
+			message: {
+				customType: "self-evolve-guide",
+				content:
+					"[harness guideline] For multi-step tasks: call harness_commit after each completed subtask, " +
+					"harness_track for environment facts worth remembering (paths, ports, versions), and " +
+					"harness_note for reusable lessons. These calls are cheap and keep state durable.",
+				display: false,
+			},
+		};
+	});
+
+	registerPack(pi, () => cfgRef.current, store, counters);
+	registerBpe(pi, () => cfgRef.current, store, counters);
+	registerFusion(pi, () => cfgRef.current, counters);
+	registerTelemetry(pi, cwd, counters, process.env.SE_RUN ?? "manual");
+
+	pi.registerCommand("evolve", {
+		description: "Toggle self-evolve harness mechanisms, or show status",
+		handler: async (args, ctx) => {
+			const parts = (args ?? "").trim().split(/\s+/).filter(Boolean);
+			const status = () =>
+				`self-evolve: pack=${on(cfgRef.current.pack)} reducer=${on(cfgRef.current.reducer)} ` +
+				`compact=${on(cfgRef.current.compact)} fusion=${on(cfgRef.current.fusion)} | ` +
+				`packed=${counters.packedCount} reduced=${counters.reducedCount} ` +
+				`compacted=${counters.compactedCount} savedEst=${counters.tokensSavedEst}`;
+			if (parts.length === 0 || parts[0] === "status") {
+				ctx.ui.notify(status(), "info");
+				return;
+			}
+			if (parts[0] === "reset") {
+				counters.packedCount = 0;
+				counters.reducedCount = 0;
+				counters.compactedCount = 0;
+				counters.tokensSavedEst = 0;
+				ctx.ui.notify("counters reset", "info");
+				return;
+			}
+			const mech = parts[0] as Mechanism;
+			if (!MECHANISMS.includes(mech)) {
+				ctx.ui.notify(`unknown mechanism '${parts[0]}'. Use: ${MECHANISMS.join(", ")}`, "error");
+				return;
+			}
+			const value = parts[1] ? parts[1] === "on" : !cfgRef.current[mech];
+			cfgRef.current = { ...cfgRef.current, [mech]: value };
+			saveConfig(cwd, cfgRef.current);
+			ctx.ui.notify(status(), "info");
+		},
+	});
+}
+
+function on(b: boolean): string {
+	return b ? "on" : "off";
+}

package/self-evolve/pack.ts

@@ -0,0 +1,135 @@
+/** ObservationPack + evidence reducer + paged recall: the tool_result tier.
+ *
+ * L1 (active context) keeps an excerpt or a verified receipt; L3 (disk) keeps
+ * the raw output, addressable by handle via the harness_recall tool.
+ *
+ * ponytail: the paper keeps raw text in context for the first 2 provider
+ * requests before swapping to the excerpt; we swap immediately since the
+ * head/tail excerpt already carries the diagnosis surface. Upgrade path:
+ * per-handle view counters.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { HarnessConfig } from "./config.js";
+import { tok } from "./config.js";
+import type { L3Store } from "./store.js";
+import { PAGE_CHARS } from "./store.js";
+import { reduceLog } from "./reducer.js";
+
+export interface Counters {
+	packedCount: number;
+	reducedCount: number;
+	compactedCount: number;
+	tokensSavedEst: number;
+	fusionCount: number;
+	bpeCalls: number;
+}
+
+export function textOf(content: Array<{ type: string; text?: string }>): string {
+	return content
+		.filter((c) => c.type === "text" && typeof c.text === "string")
+		.map((c) => c.text)
+		.join("\n");
+}
+
+// ponytail: 'read' is excluded — a single intentional file read is usually the payload
+// itself; packing it only adds recall turns (measured on the needle test). Long-horizon
+// bloat comes from repeated shell output, which the reducer + pack cover. Re-enable
+// via config if a workflow does huge reads.
+const ARCHIVED_TOOLS = new Set(["pwsh", "bash", "powershell", "grep", "find", "edit", "write"]);
+const SHELL_TOOLS = new Set(["pwsh", "bash", "powershell"]);
+
+export function registerPack(
+	pi: ExtensionAPI,
+	getCfg: () => HarnessConfig,
+	store: L3Store,
+	counters: Counters,
+): void {
+	pi.on("tool_result", async (event) => {
+		const cfg = getCfg();
+		const toolName = String((event as { toolName?: string }).toolName ?? "");
+		if (!ARCHIVED_TOOLS.has(toolName) || event.isError) return undefined;
+		const text = textOf(event.content as Array<{ type: string; text?: string }>);
+		if (!text) return undefined;
+		const t = tok(text.length);
+
+		// reducer first: deterministic filter with verbatim quote validation
+		if (cfg.reducer && SHELL_TOOLS.has(toolName)) {
+			const red = reduceLog(text);
+			if (red) {
+				const handle = store.write(toolName, text);
+				counters.reducedCount++;
+				counters.tokensSavedEst += Math.max(0, t - tok(red.receipt.length));
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								`${red.receipt}\n` +
+								`[This receipt is the COMPLETE failure evidence from the log; act on it directly. ` +
+								`Full log archived: ${handle}. Do NOT page the archive with harness_recall unless you ` +
+								`specifically need surrounding context for one quoted line.]`,
+						},
+					],
+					details: event.details,
+				};
+			}
+		}
+
+		// pack: oversized output -> excerpt + handle, raw to L3
+		if (cfg.pack && t > cfg.packThresholdTokens) {
+			const handle = store.write(toolName, text);
+			const head = text.slice(0, cfg.excerptChars);
+			const tail = text.slice(-cfg.excerptChars);
+			const pages = Math.ceil(text.length / PAGE_CHARS);
+			counters.packedCount++;
+			counters.tokensSavedEst += Math.max(0, t - tok(head.length + tail.length + 200));
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							`[${handle}] ${t} tok archived to disk. Excerpt (head/tail):\n` +
+							`---HEAD---\n${head}\n...[snip ${text.length - 2 * cfg.excerptChars} chars]...\n` +
+							`---TAIL---\n${tail}\n---\n` +
+							`Answer from the excerpt when it suffices; page selectively with ` +
+							`harness_recall("${handle}", page) (0..${pages - 1}, ${PAGE_CHARS} chars each) ` +
+							`only for specific missing details.`,
+					},
+				],
+				details: event.details,
+			};
+		}
+		return undefined;
+	});
+
+	pi.registerTool({
+		name: "harness_recall",
+		label: "harness recall",
+		description:
+			"Read one page of an archived tool output by handle (e.g. 'se://3'). " +
+			"Handles appear in '[se://N] ... archived to disk' notices. Pages are 800 chars; start at page 0. " +
+			"Page selectively: receipts and excerpts already carry the key evidence.",
+		parameters: Type.Object({
+			handle: Type.String({ description: "Archive handle, e.g. se://3" }),
+			page: Type.Number({ description: "Zero-based page index", minimum: 0 }),
+		}),
+		async execute(_toolCallId, params) {
+			const p = params as { handle: string; page: number };
+			const text = store.page(p.handle, p.page);
+			if (text === undefined) {
+				return {
+					content: [{ type: "text", text: `Unknown handle ${p.handle}` }],
+					details: { unknown: true },
+				};
+			}
+			const pages = store.pageCount(p.handle);
+			return {
+				content: [
+					{ type: "text", text: `[${p.handle} page ${p.page}/${pages - 1}]\n${text}` },
+				],
+				details: { handle: p.handle, page: p.page, pages },
+			};
+		},
+	});
+}

package/self-evolve/reducer.ts

@@ -0,0 +1,35 @@
+/** Evidence-preserving reducer: deterministic log filter -> verified receipt.
+ *
+ * Every quoted line is validated verbatim against the archived source. If
+ * validation fails (or nothing interesting is found), the caller keeps the
+ * original observation untouched.
+ */
+
+const INTERESTING =
+	/\b(fail(?:ed)?|error|exception|traceback|assert(?:ion)?:?|panic|fatal|cannot|denied|✗|✘)\b/i;
+
+export interface Reduction {
+	receipt: string;
+	quotedLines: string[];
+}
+
+export function reduceLog(text: string): Reduction | null {
+	const lines = text.split("\n");
+	const hits: string[] = [];
+	for (const line of lines) {
+		const t = line.trim();
+		if (!t) continue;
+		if (INTERESTING.test(t) || /^summary:/.test(t)) hits.push(t);
+		if (hits.length >= 40) break; // bounded receipt
+	}
+	if (hits.length === 0) return null;
+	// evidence guarantee: every quote must exist verbatim in the source
+	for (const q of hits) {
+		if (!text.includes(q)) return null;
+	}
+	const receipt = [
+		`RECEIPT (evidence-preserving reducer; ${hits.length} lines quoted verbatim):`,
+		...hits.map((h) => `  ${h}`),
+	].join("\n");
+	return { receipt, quotedLines: hits };
+}

package/self-evolve/store.ts

@@ -0,0 +1,56 @@
+/** L3 tier: disk-backed archive of raw tool outputs, addressed by handle. */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "./config.js";
+
+export const PAGE_CHARS = 800;
+
+export class L3Store {
+	private dir: string;
+	private counter = 0;
+
+	constructor(cwd: string) {
+		this.dir = join(stateDir(cwd), "l3");
+		mkdirSync(this.dir, { recursive: true });
+		// resume ids after a restart so handles never collide across sessions
+		for (const f of existsSync(this.dir) ? readdirSync(this.dir) : []) {
+			const n = Number.parseInt(f.replace(".txt", ""), 10);
+			if (Number.isFinite(n) && n > this.counter) this.counter = n;
+		}
+	}
+
+	write(toolName: string, text: string): string {
+		const id = ++this.counter;
+		const handle = `se://${id}`;
+		writeFileSync(join(this.dir, `${id}.txt`), text, "utf-8");
+		try {
+			appendFileSync(
+				join(this.dir, "index.jsonl"),
+				`${JSON.stringify({ handle, tool: toolName, bytes: text.length, ts: new Date().toISOString() })}\n`,
+			);
+		} catch {
+			// telemetry is best effort
+		}
+		return handle;
+	}
+
+	pageCount(handle: string): number {
+		const file = this.fileOf(handle);
+		if (!file) return 0;
+		return Math.ceil(readFileSync(file, "utf-8").length / PAGE_CHARS);
+	}
+
+	page(handle: string, page: number): string | undefined {
+		const file = this.fileOf(handle);
+		if (!file) return undefined;
+		const text = readFileSync(file, "utf-8");
+		return text.slice(page * PAGE_CHARS, (page + 1) * PAGE_CHARS);
+	}
+
+	private fileOf(handle: string): string | undefined {
+		const id = handle.replace("se://", "");
+		if (!/^\d+$/.test(id)) return undefined;
+		const file = join(this.dir, `${id}.txt`);
+		return existsSync(file) ? file : undefined;
+	}
+}

package/self-evolve/telemetry.ts

@@ -0,0 +1,61 @@
+/** Telemetry: per-run JSONL with provider usage + harness counters.
+ *
+ * input/output/cacheRead come from the provider (post-transform truth).
+ * rawEst = input + tokensSavedEst (what would have gone out without the
+ * harness transforms, approximate: cache effects ignored, stated as est).
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { stateDir } from "./config.js";
+import type { Counters } from "./pack.js";
+
+export function registerTelemetry(
+	pi: ExtensionAPI,
+	cwd: string,
+	counters: Counters,
+	label: string,
+): string {
+	const dir = stateDir(cwd);
+	mkdirSync(dir, { recursive: true });
+	const file = join(dir, `telemetry-${label}.jsonl`);
+
+	pi.on("agent_end", async (event) => {
+		let input = 0;
+		let output = 0;
+		let cacheRead = 0;
+		for (const m of event.messages as Array<{ usage?: Record<string, number> }>) {
+			const u = m?.usage;
+			if (!u) continue;
+			input += Number(u.input ?? 0);
+			output += Number(u.output ?? 0);
+			cacheRead += Number(u.cacheRead ?? 0);
+		}
+		if (input === 0 && output === 0) return undefined;
+		const rawEst = input + counters.tokensSavedEst;
+		const line = {
+			ts: new Date().toISOString(),
+			label,
+			test: process.env.SE_TEST ?? "",
+			input,
+			output,
+			cacheRead,
+			rawEst,
+			reductionRatio: rawEst > 0 ? Number((1 - input / rawEst).toFixed(4)) : 0,
+			packedCount: counters.packedCount,
+			fusionCount: counters.fusionCount,
+			bpeCalls: counters.bpeCalls,
+			reducedCount: counters.reducedCount,
+			compactedCount: counters.compactedCount,
+			tokensSavedEst: counters.tokensSavedEst,
+		};
+		try {
+			appendFileSync(file, `${JSON.stringify(line)}\n`);
+		} catch {
+			// telemetry is best effort
+		}
+		return undefined;
+	});
+
+	return file;
+}