omp-vcc 0.1.0

package/extensions/vcc-core/sections.ts

@@ -0,0 +1,9 @@
+// @ts-nocheck
+export interface SectionData {
+  sessionGoal: string[];
+  outstandingContext: string[];
+  filesAndChanges: string[];
+  commits: string[];
+  userPreferences: string[];
+  briefTranscript: string;
+}

package/extensions/vcc-core/types.ts

@@ -0,0 +1,17 @@
+// @ts-nocheck
+import type { Message } from "@oh-my-pi/pi-ai";
+
+export type CompactionReason = "manual" | "threshold" | "overflow";
+
+export interface FileOps {
+  readFiles?: string[];
+  modifiedFiles?: string[];
+  createdFiles?: string[];
+}
+
+export type NormalizedBlock =
+  | { kind: "user"; text: string; sourceIndex?: number }
+  | { kind: "assistant"; text: string; sourceIndex?: number }
+  | { kind: "tool_call"; name: string; args: Record<string, unknown>; sourceIndex?: number }
+  | { kind: "tool_result"; name: string; text: string; sourceIndex?: number }
+  | { kind: "bash"; command: string; output: string; exitCode: number | undefined; sourceIndex?: number };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "omp-vcc",
+  "version": "0.1.0",
+  "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
+  "type": "module",
+  "keywords": [
+    "oh-my-pi",
+    "omp",
+    "plugin"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhulinchng/omp-vcc.git"
+  },
+  "files": [
+    "extensions",
+    "skills",
+    "commands",
+    "scripts",
+    "types.d.ts"
+  ],
+  "omp": {
+    "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
+    "extensions": [
+      "./extensions/main.ts"
+    ],
+    "commands": [
+      "./commands/omp-vcc.md",
+      "./commands/vcc-recall.md"
+    ],
+    "settings": {
+      "vccEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable VCC compaction interception (master switch)"
+      },
+      "overrideDefaultCompaction": {
+        "type": "boolean",
+        "default": true,
+        "description": "When true, omp-vcc handles all compactions (threshold/overflow/manual); when false, only /omp-vcc is handled"
+      },
+      "smartKeepTail": {
+        "type": "boolean",
+        "default": true,
+        "description": "Boost default keep:1 tail when small (5k→25k token window)"
+      },
+      "continueAfterThresholdCompact": {
+        "type": "boolean",
+        "default": true,
+        "description": "Auto-continue after threshold/overflow compaction"
+      },
+      "debug": {
+        "type": "boolean",
+        "default": false,
+        "description": "Write debug snapshot to /tmp/omp-vcc-debug.json"
+      }
+    }
+  },
+  "pi": {
+    "description": "Algorithmic VCC compaction for omp - fast lossless no-LLM",
+    "extensions": [
+      "./extensions/main.ts"
+    ],
+    "commands": [
+      "./commands/omp-vcc.md",
+      "./commands/vcc-recall.md"
+    ],
+    "settings": {
+      "vccEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable VCC compaction interception (master switch)"
+      },
+      "overrideDefaultCompaction": {
+        "type": "boolean",
+        "default": true,
+        "description": "When true, omp-vcc handles all compactions (threshold/overflow/manual); when false, only /omp-vcc is handled"
+      },
+      "smartKeepTail": {
+        "type": "boolean",
+        "default": true,
+        "description": "Boost default keep:1 tail when small (5k→25k token window)"
+      },
+      "continueAfterThresholdCompact": {
+        "type": "boolean",
+        "default": true,
+        "description": "Auto-continue after threshold/overflow compaction"
+      },
+      "debug": {
+        "type": "boolean",
+        "default": false,
+        "description": "Write debug snapshot to /tmp/omp-vcc-debug.json"
+      }
+    }
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test",
+    "smoke": "bun run scripts/smoke.ts",
+    "postuninstall": "node scripts/uninstall-reset.js || true",
+    "prepublishOnly": "npm run typecheck"
+  }
+}

package/scripts/smoke.ts

@@ -0,0 +1,116 @@
+// Smoke checks for @zhulinchng/omp-vcc — host-free, zero deps
+import extension from "../extensions/main.ts";
+import { buildOwnCut } from "../extensions/vcc-core/hook.ts";
+import { calibrateCharsPerToken } from "../extensions/vcc-core/core/token-estimate.ts";
+
+let failures = 0;
+function check(name: string, condition: boolean, detail = "") {
+  if (!condition) {
+    failures++;
+    console.error(`FAIL ${name}${detail ? ": " + detail : ""}`);
+  } else {
+    console.log(`ok ${name}`);
+  }
+}
+
+console.log("1. extension loads and registers");
+try {
+  const handlers = new Map<string, unknown>();
+  const tools: any[] = [];
+  const commands: any[] = [];
+  const chain: any = {
+    describe: () => chain,
+    optional: () => chain,
+  };
+  const mockZod: any = {
+    object: (s: any) => s,
+    string: () => chain,
+    number: () => chain,
+    boolean: () => chain,
+    enum: () => chain,
+    array: () => chain,
+  };
+  const mockPi: any = {
+    on: (event: string, handler: unknown) => handlers.set(event, handler),
+    registerTool: (tool: any) => tools.push(tool),
+    registerCommand: (name: string, opts: any) => commands.push({ name, opts }),
+    zod: mockZod,
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+  };
+
+  await (extension as any)(mockPi);
+
+  check(
+    "session_before_compact hooked",
+    handlers.has("session_before_compact"),
+  );
+  check("context hooked", handlers.has("context"));
+  check("session_compact hooked", handlers.has("session_compact"));
+  check(
+    "vcc_recall registered",
+    tools.some((t) => t.name === "vcc_recall"),
+  );
+  check(
+    "omp-vcc command registered",
+    commands.some((c) => c.name === "omp-vcc"),
+  );
+  check(
+    "vcc-recall command registered",
+    commands.some((c) => c.name === "vcc-recall"),
+  );
+  check(
+    "pi-vcc alias registered",
+    commands.some((c) => c.name === "pi-vcc"),
+  );
+} catch (e) {
+  check("extension loads", false, String(e));
+}
+
+console.log("2. vcc-core pipeline smoke");
+try {
+  const result = buildOwnCut(
+    [
+      {
+        id: "m1",
+        type: "message",
+        message: { role: "user", content: "hello" },
+      },
+      {
+        id: "m2",
+        type: "message",
+        message: { role: "assistant", content: [{ type: "text", text: "hi" }] },
+      },
+      {
+        id: "m3",
+        type: "message",
+        message: { role: "user", content: "world" },
+      },
+      {
+        id: "m4",
+        type: "message",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "reply" }],
+        },
+      },
+    ] as any,
+    1,
+  );
+  check("buildOwnCut ok", (result as any).ok === true);
+  const cal = calibrateCharsPerToken(1000, 250);
+  check("calibrateCharsPerToken", cal.charsPerToken === 4);
+} catch (e) {
+  check("vcc-core pipeline", false, String(e));
+}
+
+console.log(
+  failures === 0
+    ? "\nAll smoke checks passed."
+    : `\n${failures} smoke check(s) FAILED.`,
+);
+process.exitCode = failures === 0 ? 0 : 1;

package/scripts/uninstall-reset.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * postuninstall hook: reset ownership marker if this plugin owned global state.
+ * Generic postuninstall reset for ownership marker
+ * Marker: ~/.config/@zhulinchng/omp-vcc/.ownership.json with { state: "owned", previous: boolean }
+ */
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function resetOwnedQuiet(home) {
+  const markerPath = join(
+    home,
+    ".config",
+    "@zhulinchng/omp-vcc",
+    ".ownership.json",
+  );
+  const configPath = join(home, ".omp", "agent", "config.yml");
+  let marker;
+  try {
+    marker = JSON.parse(readFileSync(markerPath, "utf8"));
+  } catch {
+    return "no-marker";
+  }
+  const clearMarker = () => {
+    try {
+      rmSync(markerPath, { force: true });
+    } catch {}
+  };
+  if (marker?.state !== "owned") {
+    clearMarker();
+    return "not-owned";
+  }
+  let content;
+  try {
+    content = readFileSync(configPath, "utf8");
+  } catch {
+    clearMarker();
+    return "config-missing";
+  }
+  const lines = content.split("\n");
+  let inStartup = false;
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (/^startup:\s*$/.test(line)) inStartup = true;
+    else if (inStartup && /^[^ \t]/.test(line) && line.trim() !== "")
+      inStartup = false;
+    if (inStartup && /quiet:\s*true/.test(line)) {
+      lines[i] = line.replace("true", "false");
+      changed = true;
+      break;
+    }
+  }
+  if (changed) {
+    try {
+      writeFileSync(configPath, lines.join("\n"), "utf8");
+    } catch {
+      return "write-failed";
+    }
+  }
+  clearMarker();
+  return changed ? "restored" : "already-default";
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  const result = resetOwnedQuiet(homedir());
+  console.log(`uninstall-reset: ${result}`);
+}

package/skills/omp-vcc/SKILL.md

@@ -0,0 +1,35 @@
+# omp-vcc Skill — VCC-Inspired Algorithmic Compaction
+
+> Lossless, transcript-preserving structured summaries — no LLM calls. Based on `sting8k/pi-vcc` (TypeScript) and `lllyasviel/VCC` (View-oriented Conversation Compiler, arXiv 2603.29678).
+
+## Philosophy
+
+- **Agent trace as structured document** (`user`, `assistant`, `thinking`, `tool_call/result`, `subagent`, compaction boundaries, harness directives). Like VCC's `V_full` identity view defines a line-number coordinate system; `V_ui` gives a one-line tool summary (`* Read "src/pets.py" (file.txt:18-20)`); `V_adapt(b, ρ)` projects via relevance predicate `ρ` (regex / BM25 / embedding / LLM) preserving turn headers, role tags, and `(f:s-e)` pointers.
+- **Fast, deterministic, lossless** — pure extraction, not LLM summarization. 30–470 ms, 35–99% context reduction, pointer invariant `V_ui → V_full[s:e]` holds structurally (SSA-like).
+- **Progressive disclosure** — brief transcript → ranked recall via `vcc_recall` (`ρ = regex→OR`) → drill-down `#N:path` resolves `(session.jsonl:s-e)` into the full view.
+
+## Pipeline
+
+Calibrated `charsPerToken` from `preparation.tokensBefore` (heuristic fallback 4) → Smart keep-tail (5 k → 25 k) → Build own cut (`firstKeptEntryId`, orphan recovery) → Token-budget tail rescue (`no_anchor` / `oversized_tail` ×2.5) → Normalize (IR lex: escaped JSON→`|` block, `digits→` strip, `<system-reminder>` filter, `TodoWrite`/`ToolSearch`/ANSI strip, `same message.id` merge, `queue-operation` discard, base64 image extract) → Filter noise → Build 5 sections (Session Goal, Files And Changes, Commits, Outstanding Context, User Preferences) → Ranked brief transcript (TF-IDF, `RANKED_BRIEF_BUDGET_TOKENS=1100` ceiling 2000, ~15 tok/block) → Format bracketed sections + separator `---` → Bounded merge (sticky dedup, volatile replace, transcript roll, 120-line cap).
+
+## Usage
+
+- **Auto**: threshold/overflow compaction intercepts `session_before_compact` when `overrideDefaultCompaction=true` (default). No LLM summary; token-budgeted.
+- **Manual**: `/omp-vcc [keep:N] [focus]` — e.g. `/omp-vcc keep:2 fix auth` keeps last 2 user turns. Also `/pi-vcc` alias.
+- **Recall**: `vcc_recall({query:"redis cache", scope:"all", page:1})` or `/vcc-recall hook|inject scope:all page:2`. Regex first, then TF-IDF OR fallback. `mode:'touched'` lists files, `#12:src/auth.ts` drills. 5 per page.
+
+## Configuration
+
+File `~/.omp/omp-vcc/config.json` (XDG-aware via `$OMP_DIR`/`$PI_CODING_AGENT_DIR`/`$OMP_VCC_CONFIG_PATH`, migrates legacy `~/.pi/agent/pi-vcc-config.json`). Manifest `omp.settings` also exposed: `vccEnabled`, `overrideDefaultCompaction`, `smartKeepTail`, `continueAfterThresholdCompact`, `debug` (`/tmp/omp-vcc-debug.json`).
+
+Optional native strategy: add `vcc` to `COMPACTION_METHOD_CHOICES` in `oh-my-pi` (see `docs/configuration.md#native-strategy`).
+
+## Verification
+
+`bunx tsc --noEmit` → `bun test` → `bun run smoke` → `omp plugin link` → `/omp-vcc keep:1` shows `[Session Goal]` toast `omp-vcc: kept 1/5 turns, ~2.1k tok`.
+
+## Related
+
+- VCC paper `arxiv:2603.29678` — three views, AppWorld evaluation (+1.1–4.2 pts, ½–⅔ tokens)
+- `sting8k/pi-vcc` `@0.7.0` — ported core `extensions/vcc-core/*` verbatim, imports adapted to `@oh-my-pi/*`
+- `lllyasviel/VCC` `VCC.py` — adaptive `SEP`, `match_lines`, transposed modalities

package/types.d.ts

@@ -0,0 +1,114 @@
+// Ambient types for dual omp/pi compatibility — zero-build TS loading
+// Import specifier is rewritten by host (legacy-pi-compat.ts) for Pi.
+// This file enables tsc --noEmit without a build step and satisfies imports
+// from generated extensions/tools/hooks without installing the host package.
+declare module "@oh-my-pi/pi-coding-agent" {
+  export interface ExtensionContext {
+    logger: { info(...args: unknown[]): void; warn(...args: unknown[]): void; error(...args: unknown[]): void; debug(...args: unknown[]): void };
+    ui: { notify(msg: string, level?: string): void; setWidget?: unknown; setHeader?: unknown; [key: string]: unknown };
+    cwd: string;
+    mode?: string;
+    hasUI?: boolean;
+    sessionManager: {
+      getSessionFile(): string | undefined;
+      getBranch(fromId?: string): any[];
+      getEntries(): any[];
+    };
+    compact(instructionsOrOptions?: string | any): Promise<void>;
+    sendMessage?: any;
+    sendUserMessage?: any;
+    [key: string]: unknown;
+  }
+  export interface ExtensionCommandContext extends ExtensionContext {
+    compact(instructionsOrOptions?: string | any): Promise<void>;
+  }
+  export interface ExtensionAPI {
+    registerTool(tool: unknown): void;
+    registerCommand(name: string, opts: unknown): void;
+    on(event: string, handler: (event: unknown, ctx: ExtensionContext) => unknown): void;
+    zod: {
+      object(shape: Record<string, unknown>): any;
+      string(): any;
+      number(): any;
+      boolean(): any;
+      enum(values: string[]): any;
+      array(item: unknown): any;
+      optional(item: unknown): any;
+    };
+    arktype: unknown;
+    typebox: unknown;
+    ui?: unknown;
+    logger: { info(...args: unknown[]): void; warn(...args: unknown[]): void; error(...args: unknown[]): void; debug(...args: unknown[]): void };
+    cwd: string;
+    hasUI: boolean;
+    getFlag(name: string): unknown;
+    sendMessage?(message: unknown, options?: unknown): void;
+    sendUserMessage?(content: unknown, options?: unknown): void | Promise<void>;
+    [key: string]: unknown;
+  }
+  export type HookFactory = (pi: ExtensionAPI) => void | Promise<void>;
+  export type CustomToolFactory = (pi: { zod: ExtensionAPI["zod"] }) => unknown;
+  export const zod: ExtensionAPI["zod"];
+  export function convertToLlm(messages: any[]): any[];
+}
+
+declare module "@oh-my-pi/pi-coding-agent/session/messages" {
+  export function convertToLlm(messages: any[]): any[];
+  export const USER_INTERRUPT_LABEL: string;
+  export const SILENT_ABORT_MARKER: string;
+  export type CustomMessage<T = unknown> = any;
+}
+
+declare module "@oh-my-pi/pi-ai" {
+  export type Message = any;
+  export type TextContent = any;
+  export type ImageContent = any;
+  export type ToolCallContent = any;
+}
+
+declare module "@earendil-works/pi-coding-agent" {
+  export * from "@oh-my-pi/pi-coding-agent";
+}
+declare module "@earendil-works/pi-coding-agent/session/messages" {
+  export * from "@oh-my-pi/pi-coding-agent/session/messages";
+}
+declare module "@earendil-works/pi-ai" {
+  export * from "@oh-my-pi/pi-ai";
+}
+declare module "@mariozechner/pi-coding-agent" {
+  export * from "@oh-my-pi/pi-coding-agent";
+}
+declare module "@mariozechner/pi-ai" {
+  export * from "@oh-my-pi/pi-ai";
+}
+
+// Node shims for smoke/tests without @types/node
+declare const process: { exitCode?: number; argv: string[]; exit(code?: number): never; env: Record<string, string | undefined> };
+declare module "node:test" {
+  export function describe(name: string, fn: () => void): void;
+  export function it(name: string, fn: () => unknown): void;
+  export const assert: { ok(value: unknown, msg?: string): void; equal(a: unknown, b: unknown, msg?: string): void; deepEqual(a: unknown, b: unknown, msg?: string): void };
+}
+declare module "node:fs" {
+  export function readFileSync(path: string, encoding: string): string;
+  export function writeFileSync(path: string, data: string, encoding?: string): void;
+  export function rmSync(path: string, opts?: unknown): void;
+  export function mkdtempSync(prefix: string): string;
+  export function mkdirSync(path: string, opts?: unknown): void;
+  export function existsSync(path: string): boolean;
+}
+declare module "node:os" {
+  export function homedir(): string;
+  export function tmpdir(): string;
+}
+declare module "node:path" {
+  export function join(...parts: string[]): string;
+  export function resolve(...parts: string[]): string;
+  export function dirname(path: string): string;
+}
+declare module "node:url" {
+  export function pathToFileURL(path: string): { href: string };
+}
+declare module "node:module" {
+  export function createRequire(filename: string): (id: string) => any;
+}