pi-cliffcompaction 0.1.0

package/lib/config.ts

@@ -0,0 +1,225 @@
+/**
+ * Compaction knobs. CLIFF_* env vars and an optional JSON file; the Pi
+ * extension also reads cliffcompaction.json from the host config dir.
+ *
+ * Names match the reference implementation (arxiv:2609.26779 / GitHub
+ * nguyenvuthientrang/cliffcompaction). Paper Algorithm 1 uses thought
+ * truncation of 300 and keep-recent K turn-pairs; the open-source defaults
+ * keep assistant text unlimited and keep_recent=3 assistant-step turns.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  asObject,
+  isBoolean,
+  isNumber,
+  type JsonObject,
+  type JsonValue,
+} from "./decode.ts";
+
+export type Config = {
+  enabled: boolean;
+  thresholdTokens: number;
+  keepRecent: number;
+  thoughtMaxChars: number;
+  cmdMaxChars: number;
+  resultMaxChars: number;
+  humanMaxChars: number;
+  keepThinking: boolean;
+  thinkingMaxChars: number;
+  shadow: boolean;
+  strict: boolean;
+  storeMaxEntries: number;
+  storeMaxBytes: number;
+};
+
+export const DEFAULT_CONFIG: Config = {
+  enabled: true,
+  thresholdTokens: 200_000,
+  keepRecent: 3,
+  thoughtMaxChars: 0,
+  cmdMaxChars: 150,
+  resultMaxChars: 500,
+  humanMaxChars: 20_000,
+  keepThinking: true,
+  thinkingMaxChars: 0,
+  shadow: false,
+  strict: false,
+  storeMaxEntries: 4096,
+  storeMaxBytes: 64 * 1024 * 1024,
+};
+
+export type ConfigPatch = Partial<Config>;
+
+function envRaw(name: string): string | undefined {
+  const value = process.env[name];
+
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return value;
+}
+
+function envInt(name: string, fallback: number): number {
+  const raw = envRaw(name);
+
+  if (raw === undefined) {
+    return fallback;
+  }
+
+  const n = Number.parseInt(raw, 10);
+
+  if (!Number.isFinite(n)) {
+    return fallback;
+  }
+
+  return n;
+}
+
+function envBool(name: string, fallback: boolean): boolean {
+  const raw = envRaw(name);
+
+  if (raw === undefined) {
+    return fallback;
+  }
+
+  const v = raw.trim().toLowerCase();
+
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+export function makeConfig(patch: ConfigPatch = {}): Config {
+  return {
+    enabled: patch.enabled ?? DEFAULT_CONFIG.enabled,
+    thresholdTokens: patch.thresholdTokens ?? DEFAULT_CONFIG.thresholdTokens,
+    keepRecent: patch.keepRecent ?? DEFAULT_CONFIG.keepRecent,
+    thoughtMaxChars: patch.thoughtMaxChars ?? DEFAULT_CONFIG.thoughtMaxChars,
+    cmdMaxChars: patch.cmdMaxChars ?? DEFAULT_CONFIG.cmdMaxChars,
+    resultMaxChars: patch.resultMaxChars ?? DEFAULT_CONFIG.resultMaxChars,
+    humanMaxChars: patch.humanMaxChars ?? DEFAULT_CONFIG.humanMaxChars,
+    keepThinking: patch.keepThinking ?? DEFAULT_CONFIG.keepThinking,
+    thinkingMaxChars: patch.thinkingMaxChars ?? DEFAULT_CONFIG.thinkingMaxChars,
+    shadow: patch.shadow ?? DEFAULT_CONFIG.shadow,
+    strict: patch.strict ?? DEFAULT_CONFIG.strict,
+    storeMaxEntries: patch.storeMaxEntries ?? DEFAULT_CONFIG.storeMaxEntries,
+    storeMaxBytes: patch.storeMaxBytes ?? DEFAULT_CONFIG.storeMaxBytes,
+  };
+}
+
+export function replaceConfig(cfg: Config, patch: ConfigPatch): Config {
+  return makeConfig({ ...cfg, ...patch });
+}
+
+function intField(obj: JsonObject, snake: string, camel: string, fallback: number): number {
+  const raw = obj[snake] ?? obj[camel];
+
+  if (isNumber(raw) && Number.isInteger(raw)) {
+    return raw;
+  }
+
+  return fallback;
+}
+
+function boolField(obj: JsonObject, snake: string, camel: string, fallback: boolean): boolean {
+  const raw = obj[snake] ?? obj[camel];
+
+  if (isBoolean(raw)) {
+    return raw;
+  }
+
+  return fallback;
+}
+
+/** Parse a JSON config object. Unknown keys ignored. */
+export function parseConfig(raw: JsonValue, base: Config = DEFAULT_CONFIG): Config {
+  const obj = asObject(raw);
+
+  if (obj === null) {
+    return base;
+  }
+
+  return makeConfig({
+    enabled: boolField(obj, "enabled", "enabled", base.enabled),
+    thresholdTokens: intField(obj, "threshold_tokens", "thresholdTokens", base.thresholdTokens),
+    keepRecent: intField(obj, "keep_recent", "keepRecent", base.keepRecent),
+    thoughtMaxChars: intField(obj, "thought_max_chars", "thoughtMaxChars", base.thoughtMaxChars),
+    cmdMaxChars: intField(obj, "cmd_max_chars", "cmdMaxChars", base.cmdMaxChars),
+    resultMaxChars: intField(obj, "result_max_chars", "resultMaxChars", base.resultMaxChars),
+    humanMaxChars: intField(obj, "human_max_chars", "humanMaxChars", base.humanMaxChars),
+    keepThinking: boolField(obj, "keep_thinking", "keepThinking", base.keepThinking),
+    thinkingMaxChars: intField(obj, "thinking_max_chars", "thinkingMaxChars", base.thinkingMaxChars),
+    shadow: boolField(obj, "shadow", "shadow", base.shadow),
+    strict: boolField(obj, "strict", "strict", base.strict),
+    storeMaxEntries: intField(obj, "store_max_entries", "storeMaxEntries", base.storeMaxEntries),
+    storeMaxBytes: intField(obj, "store_max_bytes", "storeMaxBytes", base.storeMaxBytes),
+  });
+}
+
+export function configFromEnv(base: Config = DEFAULT_CONFIG): Config {
+  return makeConfig({
+    enabled: envBool("CLIFF_ENABLED", base.enabled),
+    thresholdTokens: envInt("CLIFF_THRESHOLD_TOKENS", base.thresholdTokens),
+    keepRecent: envInt("CLIFF_KEEP_RECENT", base.keepRecent),
+    thoughtMaxChars: envInt("CLIFF_THOUGHT_MAX_CHARS", base.thoughtMaxChars),
+    cmdMaxChars: envInt("CLIFF_CMD_MAX_CHARS", base.cmdMaxChars),
+    resultMaxChars: envInt("CLIFF_RESULT_MAX_CHARS", base.resultMaxChars),
+    humanMaxChars: envInt("CLIFF_HUMAN_MAX_CHARS", base.humanMaxChars),
+    keepThinking: envBool("CLIFF_KEEP_THINKING", base.keepThinking),
+    thinkingMaxChars: envInt("CLIFF_THINKING_MAX_CHARS", base.thinkingMaxChars),
+    shadow: envBool("CLIFF_SHADOW", base.shadow),
+    strict: envBool("CLIFF_STRICT", base.strict),
+    storeMaxEntries: envInt("CLIFF_STORE_MAX_ENTRIES", base.storeMaxEntries),
+    storeMaxBytes: envInt("CLIFF_STORE_MAX_BYTES", base.storeMaxBytes),
+  });
+}
+
+export function defaultConfigPath(): string {
+  const explicit = envRaw("PI_CLIFF_CONFIG") ?? envRaw("OMP_CLIFF_CONFIG");
+
+  if (explicit) {
+    return explicit;
+  }
+
+  const home = homedir();
+  const piDir = envRaw("PI_CONFIG_DIR") ?? join(home, ".pi", "agent");
+  const ompDir = envRaw("OMP_CONFIG_DIR") ?? join(home, ".omp", "agent");
+  const piPath = join(piDir, "cliffcompaction.json");
+  const ompPath = join(ompDir, "cliffcompaction.json");
+
+  if (existsSync(piPath)) {
+    return piPath;
+  }
+
+  if (existsSync(ompPath)) {
+    return ompPath;
+  }
+
+  return piPath;
+}
+
+export function loadConfigFile(path: string): Config | null {
+  if (!existsSync(path)) {
+    return null;
+  }
+
+  try {
+    const text = readFileSync(path, "utf8");
+    const parsed: JsonValue = JSON.parse(text);
+
+    return parseConfig(parsed);
+  } catch {
+    return null;
+  }
+}
+
+/** File (if present) then CLIFF_* env overrides. */
+export function loadConfig(): Config {
+  const fromFile = loadConfigFile(defaultConfigPath());
+  const base = fromFile ?? DEFAULT_CONFIG;
+
+  return configFromEnv(base);
+}
+

package/lib/decode.ts

@@ -0,0 +1,103 @@
+/**
+ * Boundary decoders (anti-slop). JSON request bodies are untyped at the
+ * I/O edge; everything inside the engine consumes these predicates.
+ *
+ * Hot-path checks use constructor identity: JSON.parse and object
+ * literals never box primitives. Null-prototype objects still count as
+ * records (Object.create(null).constructor is undefined).
+ */
+
+export type JsonPrimitive = string | number | boolean | null;
+
+export type JsonArray = JsonValue[];
+
+export type JsonObject = { [key: string]: JsonValue };
+
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+
+export function isString(value: JsonValue | undefined | null): value is string {
+  return value !== null && value !== undefined && value.constructor === String;
+}
+
+export function isNumber(value: JsonValue | undefined | null): value is number {
+  return (
+    value !== null &&
+    value !== undefined &&
+    value.constructor === Number &&
+    Number.isFinite(value)
+  );
+}
+
+export function isBoolean(value: JsonValue | undefined | null): value is boolean {
+  return value !== null && value !== undefined && value.constructor === Boolean;
+}
+
+export function isNull(value: JsonValue | undefined | null): value is null {
+  return value === null;
+}
+
+export function isArray(value: JsonValue | undefined | null): value is JsonArray {
+  return Array.isArray(value);
+}
+
+export function isObject(value: JsonValue | undefined | null): value is JsonObject {
+  if (value === null || value === undefined || Array.isArray(value)) {
+    return false;
+  }
+
+  const ctor = value.constructor;
+
+  return ctor === Object || ctor === undefined;
+}
+
+export function isRecord(value: JsonValue | undefined | null): value is JsonObject {
+  return value !== null && isObject(value);
+}
+
+export function asString(value: JsonValue | undefined | null, fallback = ""): string {
+  if (isString(value)) {
+    return value;
+  }
+
+  return fallback;
+}
+
+export function asBoolean(value: JsonValue | undefined | null, fallback = false): boolean {
+  if (isBoolean(value)) {
+    return value;
+  }
+
+  return fallback;
+}
+
+export function asFiniteNumber(value: JsonValue | undefined | null, fallback: number): number {
+  if (isNumber(value)) {
+    return value;
+  }
+
+  return fallback;
+}
+
+export function asObject(value: JsonValue | undefined | null): JsonObject | null {
+  if (isRecord(value)) {
+    return value;
+  }
+
+  return null;
+}
+
+export function asArray(value: JsonValue | undefined | null): JsonArray {
+  if (isArray(value)) {
+    return value;
+  }
+
+  return [];
+}
+
+export function field(obj: JsonObject, key: string): JsonValue | undefined {
+  if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+    return undefined;
+  }
+
+  return obj[key];
+}

package/lib/dialects/anthropic.ts

@@ -0,0 +1,364 @@
+/**
+ * Anthropic Messages API dialect.
+ *
+ * - `system` is a top-level request field, not a message.
+ * - Tool results are user-role messages whose content blocks are typed
+ *   tool_result; human prompts are user-role with text blocks.
+ * - cache_control is excluded from the canonical digest.
+ */
+
+import type { Config } from "../config.ts";
+import {
+  asArray,
+  asBoolean,
+  asObject,
+  asString,
+  isArray,
+  isRecord,
+  isString,
+  type JsonArray,
+  type JsonObject,
+  type JsonValue,
+} from "../decode.ts";
+import { digestBytes, digestObj } from "../hashing.ts";
+import { canonicalJson } from "../json.ts";
+import {
+  makeDialect,
+  startsWithSummaryHeader,
+  stripTaskNotifications,
+  truncate,
+  type Dialect,
+} from "./base.ts";
+
+function resultText(content: JsonValue | undefined): string {
+  if (isString(content)) {
+    return content;
+  }
+
+  if (isArray(content)) {
+    const parts: string[] = [];
+
+    for (const p of content) {
+      if (isRecord(p) && asString(p.type) === "text") {
+        parts.push(asString(p.text));
+      } else if (isString(p)) {
+        parts.push(p);
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  if (content === undefined || content === null) {
+    return "";
+  }
+
+  return String(content);
+}
+
+function canonBlock(block: JsonObject): JsonArray {
+  const t = asString(block.type);
+
+  if (t === "text") {
+    return ["text", asString(block.text)];
+  }
+
+  if (t === "tool_use") {
+    return ["tool_use", asString(block.id), asString(block.name), canonicalJson(block.input ?? {})];
+  }
+
+  if (t === "tool_result") {
+    return [
+      "tool_result",
+      asString(block.tool_use_id),
+      resultText(block.content),
+      asBoolean(block.is_error, false),
+    ];
+  }
+
+  if (t === "thinking") {
+    return ["thinking", asString(block.thinking)];
+  }
+
+  if (t === "redacted_thinking") {
+    return ["redacted_thinking", asString(block.data)];
+  }
+
+  if (t === "image" || t === "document") {
+    const src = asObject(block.source) ?? {};
+    const payload = asString(src.data) || asString(src.url);
+    const h = digestBytes(payload);
+
+    return [t, asString(src.type), h];
+  }
+
+  const reduced: JsonObject = {};
+
+  for (const key of Object.keys(block)) {
+    if (key !== "cache_control") {
+      reduced[key] = block[key];
+    }
+  }
+
+  return ["other", canonicalJson(reduced)];
+}
+
+export function digestMessage(msg: JsonObject): string {
+  const content = msg.content;
+  let blocks: JsonArray = [];
+
+  if (isString(content)) {
+    blocks = [["text", content]];
+  } else if (isArray(content)) {
+    const out: JsonArray = [];
+
+    for (const b of content) {
+      if (isRecord(b)) {
+        out.push(canonBlock(b));
+      }
+    }
+
+    blocks = out;
+  }
+
+  return digestObj([asString(msg.role), blocks]);
+}
+
+export function isAssistant(msg: JsonObject): boolean {
+  return asString(msg.role) === "assistant";
+}
+
+function contentStartsWithHeader(content: JsonValue | undefined): boolean {
+  if (isString(content)) {
+    return startsWithSummaryHeader(content);
+  }
+
+  if (isArray(content)) {
+    for (const b of content) {
+      if (isRecord(b) && asString(b.type) === "text") {
+        return startsWithSummaryHeader(asString(b.text));
+      }
+    }
+  }
+
+  return false;
+}
+
+export function isSummaryMessage(msg: JsonObject): boolean {
+  if (asString(msg.role) !== "user") {
+    return false;
+  }
+
+  return contentStartsWithHeader(msg.content);
+}
+
+export function sessionKey(body: JsonObject): string | null {
+  const meta = asObject(body.metadata);
+
+  if (meta === null) {
+    return null;
+  }
+
+  const raw = meta.user_id;
+
+  if (!isString(raw) || !raw.startsWith("{")) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    const obj = asObject(parsed);
+
+    if (obj === null) {
+      return null;
+    }
+
+    const sid = obj.session_id;
+
+    if (isString(sid) && sid) {
+      return sid;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function summarizeAssistant(msg: JsonObject, cfg: Config): string[] {
+  const content = msg.content;
+  const texts: string[] = [];
+  const thinkings: string[] = [];
+  const sigs: string[] = [];
+
+  if (isString(content)) {
+    texts.push(content);
+  } else if (isArray(content)) {
+    for (const b of content) {
+      if (!isRecord(b)) {
+        continue;
+      }
+
+      const t = asString(b.type);
+
+      if (t === "text") {
+        texts.push(asString(b.text));
+      } else if (t === "thinking") {
+        if (cfg.keepThinking) {
+          thinkings.push(asString(b.thinking));
+        }
+      } else if (t === "tool_use") {
+        const args = canonicalJson(b.input ?? {});
+        sigs.push("[" + asString(b.name, "?") + "] " + truncate(args, cfg.cmdMaxChars));
+      }
+    }
+  }
+
+  const lines: string[] = [];
+  const thinkingParts: string[] = [];
+
+  for (const x of thinkings) {
+    if (x.trim()) {
+      thinkingParts.push(x);
+    }
+  }
+
+  const thinking = truncate(thinkingParts.join("\n").trim(), cfg.thinkingMaxChars);
+
+  if (thinking) {
+    lines.push("thinking: " + thinking);
+  }
+
+  const thoughtParts: string[] = [];
+
+  for (const t of texts) {
+    if (t.trim()) {
+      thoughtParts.push(t);
+    }
+  }
+
+  const thought = truncate(thoughtParts.join("\n").trim(), cfg.thoughtMaxChars);
+
+  if (thought) {
+    lines.push("assistant: " + thought);
+  }
+
+  if (sigs.length > 0) {
+    lines.push(sigs.join("\n"));
+  }
+
+  return lines.length > 0 ? [lines.join("\n")] : [];
+}
+
+function summarizeUser(msg: JsonObject, cfg: Config): string[] {
+  const parts: string[] = [];
+  const content = msg.content;
+
+  if (isString(content)) {
+    if (startsWithSummaryHeader(content)) {
+      return [];
+    }
+
+    const text = stripTaskNotifications(content);
+
+    if (text.trim()) {
+      parts.push("user: " + truncate(text.trim(), cfg.humanMaxChars));
+    }
+
+    return parts;
+  }
+
+  if (!isArray(content)) {
+    return parts;
+  }
+
+  for (const b of content) {
+    if (!isRecord(b)) {
+      continue;
+    }
+
+    const t = asString(b.type);
+
+    if (t === "text") {
+      let text = asString(b.text);
+
+      if (startsWithSummaryHeader(text)) {
+        continue;
+      }
+
+      text = stripTaskNotifications(text);
+
+      if (!text.trim()) {
+        continue;
+      }
+
+      parts.push("user: " + truncate(text.trim(), cfg.humanMaxChars));
+    } else if (t === "tool_result") {
+      const text = resultText(b.content).trim();
+
+      if (text && text.length <= cfg.resultMaxChars) {
+        parts.push("result: " + text);
+      }
+    }
+  }
+
+  return parts;
+}
+
+export function summarizeMessage(msg: JsonObject, cfg: Config): string[] {
+  if (isAssistant(msg)) {
+    return summarizeAssistant(msg, cfg);
+  }
+
+  if (asString(msg.role) === "user") {
+    return summarizeUser(msg, cfg);
+  }
+
+  if (asString(msg.role) === "system") {
+    const content = msg.content;
+    let text = "";
+
+    if (isString(content)) {
+      text = content;
+    } else {
+      const bits: string[] = [];
+
+      for (const b of asArray(content)) {
+        if (isRecord(b) && asString(b.type) === "text") {
+          bits.push(asString(b.text));
+        }
+      }
+
+      text = bits.join("\n");
+    }
+
+    text = text.trim();
+
+    if (text) {
+      return ["system: " + truncate(text, cfg.humanMaxChars)];
+    }
+
+    return [];
+  }
+
+  return [];
+}
+
+function isSystem(msg: JsonObject): boolean {
+  return asString(msg.role) === "system";
+}
+
+export function userMessage(text: string): JsonObject {
+  return { role: "user", content: text };
+}
+
+export const DIALECT: Dialect = makeDialect({
+  name: "anthropic",
+  digestMessage,
+  isAssistant,
+  summarizeMessage,
+  userMessage,
+  isSummaryMessage,
+  sessionKey,
+  trimFromHead: isSystem,
+});