@drewpayment/mink 0.13.0-beta.1 → 0.13.0-beta.2

package/src/types/compression.ts

@@ -0,0 +1,29 @@
+// Tool-output compression types (spec 21). The decision/config types live in
+// src/core/compression.ts; these describe the reversible cache and the engine's
+// content-aware output.
+
+// What kind of tool output we detected, which selects the compressor and is
+// recorded on the ledger event for later analysis.
+export type ContentKind = "search" | "log" | "file" | "json" | "text";
+
+// One stored original, retrievable byte-exact via `mink retrieve <token>` until
+// it expires.
+export interface CompressionCacheEntry {
+  token: string;
+  createdAt: string;
+  expiresAt: string;
+  toolName: string;
+  contentKind: ContentKind;
+  content: string;
+  sizeBytes: number;
+}
+
+// The result of compressing one output. `compressed` is the body the model will
+// see (sans retrieval affordance, which the pipeline appends); `omittedNote`
+// summarises what was dropped. A compressor returns null when it has nothing
+// worth substituting.
+export interface CompressionResult {
+  kind: ContentKind;
+  compressed: string;
+  omittedNote: string;
+}

package/src/types/config.ts

@@ -18,6 +18,11 @@ export interface GlobalConfig {
   "cli.auto-update-schedule"?: string;
   "cli.auto-update-package-manager"?: string;
   "projects.identity"?: string;
+  "compression.enabled"?: string;
+  "compression.threshold-tokens"?: string;
+  "compression.min-savings-ratio"?: string;
+  "compression.holdout-fraction"?: string;
+  "compression.retention-hours"?: string;
 }
 
 export type ConfigKey = keyof GlobalConfig & string;
@@ -179,6 +184,41 @@ export const CONFIG_KEYS: ConfigKeyMeta[] = [
       "Project identity strategy: path-derived (legacy) or git-remote (stable across machines)",
     scope: "shared",
   },
+  {
+    key: "compression.enabled",
+    default: "false",
+    envVar: "MINK_COMPRESSION_ENABLED",
+    description: "Enable tool-output compression (spec 21). Off until inline compression ships.",
+    scope: "shared",
+  },
+  {
+    key: "compression.threshold-tokens",
+    default: "800",
+    envVar: "MINK_COMPRESSION_THRESHOLD_TOKENS",
+    description: "Minimum estimated token size before a tool output is eligible for compression",
+    scope: "shared",
+  },
+  {
+    key: "compression.min-savings-ratio",
+    default: "0.25",
+    envVar: "MINK_COMPRESSION_MIN_SAVINGS_RATIO",
+    description: "Discard a compression attempt unless it saves at least this fraction of tokens",
+    scope: "shared",
+  },
+  {
+    key: "compression.holdout-fraction",
+    default: "0.1",
+    envVar: "MINK_COMPRESSION_HOLDOUT_FRACTION",
+    description: "Fraction of eligible outputs left uncompressed as a measured control group",
+    scope: "shared",
+  },
+  {
+    key: "compression.retention-hours",
+    default: "168",
+    envVar: "MINK_COMPRESSION_RETENTION_HOURS",
+    description: "How long compressed originals stay retrievable before eviction",
+    scope: "shared",
+  },
 ];
 
 const VALID_KEYS = new Set<string>(CONFIG_KEYS.map((k) => k.key));

package/src/types/hook-input.ts

@@ -19,6 +19,10 @@ export interface PostToolUseInput {
     // Edit tool
     old_string?: string;
     new_string?: string;
+    // Read tool — present for ranged reads; their output is a slice, so we
+    // don't substitute a whole-file summary for them (spec 21 edge case).
+    offset?: number;
+    limit?: number;
   };
   // Legacy / older hook payload shape — kept for backward compatibility.
   tool_output?: {

package/src/types/token-ledger.ts

@@ -41,3 +41,36 @@ export interface TokenLedger {
   sessions: LedgerSession[];
   wasteFlags?: WasteFlag[];
 }
+
+// Tool-output compression measurement (spec 21).
+
+// What the caller supplies when recording a compression decision. `id` and
+// `createdAt` are generated when omitted. For a holdout arm, pass the original
+// output unchanged so `compressedTokens === originalTokens` and `holdout: true`.
+export interface CompressionEventInput {
+  toolName: string;
+  contentKind: string;
+  originalTokens: number;
+  compressedTokens: number;
+  holdout: boolean;
+  id?: string;
+  createdAt?: string;
+}
+
+export interface CompressionEvent {
+  id: string;
+  createdAt: string;
+  toolName: string;
+  contentKind: string;
+  originalTokens: number;
+  compressedTokens: number;
+  holdout: boolean;
+}
+
+export interface CompressionLifetime {
+  totalEvents: number;
+  totalHoldoutEvents: number;
+  totalOriginalTokens: number;
+  totalCompressedTokens: number;
+  totalMeasuredSavings: number;
+}

package/src/core/agent-detect.ts

@@ -1,88 +0,0 @@
-import { execSync } from "child_process";
-import { existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-
-// Supported host coding assistants Mink can attach to. Adding a new host is a
-// matter of appending an entry here plus an installer in init.ts.
-export type AgentId = "claude" | "pi";
-
-export interface AgentMeta {
-  id: AgentId;
-  label: string;
-  /** Project-local config directory that signals the host is used here. */
-  projectDir: string;
-  /** Per-user global config directory that signals the host is installed. */
-  globalDir: string;
-  /** Executable name to probe on PATH. */
-  bin: string;
-}
-
-export const AGENTS: AgentMeta[] = [
-  {
-    id: "claude",
-    label: "Claude Code",
-    projectDir: ".claude",
-    globalDir: join(homedir(), ".claude"),
-    bin: "claude",
-  },
-  {
-    id: "pi",
-    label: "Pi",
-    projectDir: ".pi",
-    globalDir: join(homedir(), ".pi"),
-    bin: "pi",
-  },
-];
-
-export interface AgentInfo extends AgentMeta {
-  detected: boolean;
-  /** Human-readable reasons the host was (or was not) detected. */
-  signals: string[];
-}
-
-function commandExists(bin: string): boolean {
-  try {
-    const probe = process.platform === "win32" ? `where ${bin}` : `command -v ${bin}`;
-    execSync(probe, { stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Inspect a single host's footprint relative to `cwd`. Detection is best-effort
- * and layered, strongest signal first: a project-local config directory is the
- * clearest sign the host is actually used here; a global config directory or a
- * binary on PATH only prove the host is installed somewhere.
- */
-export function detectAgent(meta: AgentMeta, cwd: string): AgentInfo {
-  const signals: string[] = [];
-  if (existsSync(join(cwd, meta.projectDir))) {
-    signals.push(`project config (${meta.projectDir}/)`);
-  }
-  if (existsSync(meta.globalDir)) {
-    signals.push("global config");
-  }
-  if (commandExists(meta.bin)) {
-    signals.push("on PATH");
-  }
-  return { ...meta, detected: signals.length > 0, signals };
-}
-
-export function detectAgents(cwd: string): AgentInfo[] {
-  return AGENTS.map((m) => detectAgent(m, cwd));
-}
-
-export function resolveTargetsFromFlag(flag: string): AgentId[] {
-  const normalized = flag.trim().toLowerCase();
-  if (normalized === "all") return AGENTS.map((a) => a.id);
-  const ids = normalized
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  const valid = AGENTS.map((a) => a.id) as string[];
-  const resolved = ids.filter((id): id is AgentId => valid.includes(id));
-  return resolved;
-}

package/src/core/agent-pi.ts

@@ -1,314 +0,0 @@
-import { join, resolve, dirname } from "path";
-import { existsSync, mkdirSync, copyFileSync, rmSync } from "fs";
-import { atomicWriteText } from "./fs-utils";
-
-// ── Paths ───────────────────────────────────────────────────────────────────
-// Pi auto-discovers extensions from `.pi/extensions/*.ts` and skills from
-// `.pi/skills/*/SKILL.md`, so simply writing these files wires Mink in — no
-// `.pi/settings.json` edit required, which keeps us from clobbering the user's
-// own Pi configuration.
-
-export function piExtensionPath(cwd: string): string {
-  return join(cwd, ".pi", "extensions", "mink.ts");
-}
-
-export function piGuidanceSkillPath(cwd: string): string {
-  return join(cwd, ".pi", "skills", "mink", "SKILL.md");
-}
-
-export function piNoteSkillPath(cwd: string): string {
-  return join(cwd, ".pi", "skills", "mink-note", "SKILL.md");
-}
-
-// ── Extension source ─────────────────────────────────────────────────────────
-
-/**
- * Generate the Pi adapter extension. Like the Claude hook wiring, the `mink`
- * invocation is templated: an installed package resolves the portable `mink`
- * bin shim (so a committed `.pi/` works across machines), while source-dev mode
- * falls back to `bun run <abs cli.ts>`.
- *
- * The adapter shells out to the same `mink` lifecycle commands every other host
- * uses, translating Pi's event/tool shapes into Mink's canonical payload. It is
- * deliberately defensive: it never throws into Pi, never blocks a tool, and
- * times out fast — matching the safety contract of the Claude hooks.
- */
-export function buildPiExtension(cliPath: string): string {
-  const isTsSource = cliPath.endsWith(".ts");
-  const cmd = isTsSource ? "bun" : "mink";
-  const baseArgs = isTsSource ? JSON.stringify(["run", cliPath]) : "[]";
-
-  return `// AUTO-GENERATED by \`mink init\`. Do not edit — re-run \`mink init\` to refresh.
-//
-// Mink adapter for the Pi coding agent. Routes Pi lifecycle and tool events
-// into the \`mink\` CLI so Pi shares the same ~/.mink state, file index, ledger,
-// and wiki as every other assistant wired to this project.
-//
-// Field shapes confirmed against pi source (earendil-works/pi,
-// packages/coding-agent): read params {path, offset, limit}; write {path,
-// content}; edit {path, edits:[{oldText,newText}]} (with legacy file_path /
-// top-level oldText,newText). tool_call/tool_result events expose toolName,
-// toolCallId, input; tool_result also exposes content (a content-block array),
-// details, isError. Advisories are surfaced by returning a modified result from
-// the tool_result handler — the documented mechanism. pi.exec has no stdin, so
-// the canonical payload is piped to \`mink\` via a spawned child process. Every
-// host-API access is defensive: the adapter never throws into Pi or blocks a
-// tool — a failure degrades to "no advisory".
-
-import { spawn } from "node:child_process";
-
-const MINK_CMD = ${JSON.stringify(cmd)};
-const MINK_BASE_ARGS = ${baseArgs};
-const TIMEOUT_MS = 5000;
-
-function runMink(sub, payload, cwd) {
-  return new Promise((res) => {
-    let done = false;
-    const finish = (out) => {
-      if (done) return;
-      done = true;
-      res(out);
-    };
-    try {
-      const child = spawn(MINK_CMD, [...MINK_BASE_ARGS, sub], {
-        cwd,
-        stdio: ["pipe", "ignore", "pipe"],
-      });
-      let stderr = "";
-      child.stderr?.on("data", (d) => {
-        stderr += d.toString();
-      });
-      child.on("error", () => finish(""));
-      child.on("close", () => finish(stderr.trim()));
-      const timer = setTimeout(() => {
-        try {
-          child.kill();
-        } catch {}
-        finish("");
-      }, TIMEOUT_MS);
-      timer.unref?.();
-      try {
-        child.stdin?.end(payload ? JSON.stringify(payload) : "");
-      } catch {}
-    } catch {
-      finish("");
-    }
-  });
-}
-
-// Pi's edit tool takes an array of { oldText, newText } replacements (legacy
-// inputs may put oldText/newText/new_string at the top level). Concatenate the
-// replacement text so Mink's write-enforcement sees everything being written.
-function editNewText(input) {
-  if (Array.isArray(input.edits)) {
-    return input.edits
-      .map((e) => e?.newText ?? e?.new_string ?? "")
-      .filter(Boolean)
-      .join("\\n");
-  }
-  return input.newText ?? input.new_string ?? input.replacement ?? "";
-}
-
-// Resolve Pi's tool name + arguments to Mink's canonical operation. Only the
-// three file operations matter; anything else returns null and is ignored.
-function toolInfo(event) {
-  const name = String(event?.toolName ?? event?.tool ?? event?.name ?? "").toLowerCase();
-  const input = event?.input ?? event?.arguments ?? {};
-  const filePath = input.path ?? input.file_path ?? input.filePath;
-  if (!filePath) return null;
-  if (name === "read") return { op: "read", filePath };
-  if (name === "write") return { op: "write", filePath, content: input.content ?? input.text ?? "" };
-  if (name === "edit") return { op: "edit", filePath, newString: editNewText(input) };
-  return null;
-}
-
-// A tool_result's content is an array of content blocks ({ type, text }); pull
-// the text out so Mink's post-read can estimate tokens from real content.
-function resultContent(event) {
-  const c = event?.content;
-  if (typeof c === "string") return c;
-  if (Array.isArray(c)) {
-    const text = c
-      .map((b) => (typeof b === "string" ? b : b?.text ?? ""))
-      .filter(Boolean)
-      .join("\\n");
-    return text || null;
-  }
-  return null;
-}
-
-function prePayload(info) {
-  if (info.op === "read")
-    return { sub: "pre-read", payload: { tool_name: "Read", tool_input: { file_path: info.filePath } } };
-  if (info.op === "write")
-    return {
-      sub: "pre-write",
-      payload: { tool_name: "Write", tool_input: { file_path: info.filePath, content: info.content } },
-    };
-  return {
-    sub: "pre-write",
-    payload: { tool_name: "Edit", tool_input: { file_path: info.filePath, new_string: info.newString } },
-  };
-}
-
-function postPayload(info, content) {
-  if (info.op === "read")
-    return {
-      sub: "post-read",
-      payload: {
-        tool_name: "Read",
-        tool_input: { file_path: info.filePath },
-        tool_output: content == null ? undefined : { content },
-      },
-    };
-  if (info.op === "write")
-    return {
-      sub: "post-write",
-      payload: { tool_name: "Write", tool_input: { file_path: info.filePath, content: info.content } },
-    };
-  return {
-    sub: "post-write",
-    payload: { tool_name: "Edit", tool_input: { file_path: info.filePath, new_string: info.newString } },
-  };
-}
-
-export default function (pi) {
-  const cwd = pi?.ctx?.cwd || process.cwd();
-  const pending = new Map();
-  const keyOf = (event) => event?.toolCallId ?? event?.id ?? event?.callId ?? "";
-
-  pi.on?.("session_start", (event) => {
-    // Skip hot-reloads so an extension reload mid-task doesn't reset the
-    // ephemeral session state; every genuinely new/resumed session starts fresh.
-    if (event?.reason === "reload") return;
-    void runMink("session-start", null, cwd);
-  });
-  pi.on?.("agent_end", () => {
-    void runMink("session-stop", null, cwd);
-  });
-  pi.on?.("session_shutdown", () => {
-    void runMink("session-stop", null, cwd);
-  });
-
-  pi.on?.("tool_call", async (event) => {
-    const info = toolInfo(event);
-    if (!info) return;
-    const { sub, payload } = prePayload(info);
-    const advisory = await runMink(sub, payload, cwd);
-    if (advisory) pending.set(keyOf(event), advisory);
-  });
-
-  pi.on?.("tool_result", async (event) => {
-    const info = toolInfo(event);
-    if (!info) return;
-    const { sub, payload } = postPayload(info, resultContent(event));
-    const post = await runMink(sub, payload, cwd);
-    const pre = pending.get(keyOf(event)) ?? "";
-    pending.delete(keyOf(event));
-    const advisory = [pre, post].filter(Boolean).join("\\n");
-    if (!advisory) return;
-
-    // Surface Mink's advisory into the model's context by appending a text
-    // block to the tool result — the parity of Claude feeding hook stderr back.
-    const base = Array.isArray(event.content)
-      ? event.content
-      : typeof event.content === "string"
-        ? [{ type: "text", text: event.content }]
-        : [];
-    return {
-      content: [...base, { type: "text", text: advisory }],
-      details: event.details,
-      isError: event.isError,
-    };
-  });
-}
-`;
-}
-
-// ── Guidance skill ───────────────────────────────────────────────────────────
-// Pi has no automatic project-rules file (CLAUDE.md / AGENTS.md equivalent), so
-// the guidance Mink gives the assistant is delivered as a Pi skill instead.
-
-const PI_GUIDANCE_SKILL = `---
-name: mink
-description: Mink context management is active in this project. Read this to understand how Mink memory, write enforcement, and note capture work under Pi.
----
-
-# Mink — context management for this project
-
-This project uses **Mink** (\`@drewpayment/mink\`) for cross-session context management.
-
-## How it works
-- Mink runs automatically through a Pi extension at \`.pi/extensions/mink.ts\` that hooks session start/stop and every read/edit/write tool call.
-- All state lives in \`~/.mink/\` on the user's machine — **not** in this repository. Do not create or write to any in-repo state directory (no \`.wolf/\`, \`.mink/\`, etc.).
-- Read intelligence, write enforcement, bug memory, and the token ledger are handled by the extension. You do not need to manually read or update any state files.
-- Mink shares one \`~/.mink/\` state across every assistant wired to this project, so history is unified whether the user runs Pi or another assistant.
-
-## When to act on Mink
-- If the user asks to "save a note", "remember this", "log this to my wiki", or similar, use the \`mink-note\` skill (\`/skill:mink-note\`) — it captures into the user's \`~/.mink/\` vault.
-- If the extension surfaces a learning, past bug, or repeat-read warning in context, treat that as authoritative project memory and follow it.
-- The \`mink dashboard\` and \`mink agent\` commands are user tools — do not invoke them on the user's behalf.
-`;
-
-function resolveSkillsSourceDir(): string {
-  // Walk up until we find a package root that contains skills/ — works from
-  // src/core/agent-pi.ts (dev) and dist/cli.js (installed), which sit at
-  // different depths relative to the package root.
-  let dir = dirname(new URL(import.meta.url).pathname);
-  while (true) {
-    if (existsSync(join(dir, "package.json")) && existsSync(join(dir, "skills"))) {
-      return join(dir, "skills");
-    }
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return resolve(dirname(new URL(import.meta.url).pathname), "../../skills");
-}
-
-export interface PiInstallResult {
-  extensionPath: string;
-  guidancePath: string;
-  notePath: string | null;
-}
-
-export function installPi(cwd: string, cliPath: string): PiInstallResult {
-  const extensionPath = piExtensionPath(cwd);
-  mkdirSync(dirname(extensionPath), { recursive: true });
-  atomicWriteText(extensionPath, buildPiExtension(cliPath));
-
-  const guidancePath = piGuidanceSkillPath(cwd);
-  mkdirSync(dirname(guidancePath), { recursive: true });
-  atomicWriteText(guidancePath, PI_GUIDANCE_SKILL);
-
-  // Mirror the note-capture skill into Pi's skill directory so the single
-  // source of truth (skills/mink-note) is reused rather than duplicated.
-  let notePath: string | null = null;
-  try {
-    const src = join(resolveSkillsSourceDir(), "mink-note", "SKILL.md");
-    if (existsSync(src)) {
-      notePath = piNoteSkillPath(cwd);
-      mkdirSync(dirname(notePath), { recursive: true });
-      copyFileSync(src, notePath);
-    }
-  } catch {
-    // Note skill is non-critical — the extension and guidance still work.
-    notePath = null;
-  }
-
-  return { extensionPath, guidancePath, notePath };
-}
-
-export function removePi(cwd: string): void {
-  for (const p of [
-    piExtensionPath(cwd),
-    join(cwd, ".pi", "skills", "mink"),
-    join(cwd, ".pi", "skills", "mink-note"),
-  ]) {
-    try {
-      rmSync(p, { recursive: true, force: true });
-    } catch {
-      // best-effort
-    }
-  }
-}

package/src/core/prompt.ts

@@ -1,27 +0,0 @@
-import { createInterface } from "readline";
-
-/**
- * Whether the current process can safely prompt the user. We require a real
- * interactive TTY on both stdin and stdout and honor the usual escape hatches
- * (CI, an explicit opt-out) so `mink init` never blocks a script or pipeline.
- */
-export function stdinIsInteractive(): boolean {
-  const stdin = process.stdin as NodeJS.ReadStream & { isTTY?: boolean };
-  const stdout = process.stdout as NodeJS.WriteStream & { isTTY?: boolean };
-  return (
-    Boolean(stdin.isTTY) &&
-    Boolean(stdout.isTTY) &&
-    process.env.MINK_NO_PROMPT !== "1" &&
-    !process.env.CI
-  );
-}
-
-export function ask(question: string): Promise<string> {
-  return new Promise((resolve) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer);
-    });
-  });
-}