@cortexkit/aft-pi 0.14.0

package/dist/index.js

@@ -0,0 +1,2294 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/index.ts
+import { createRequire as createRequire3 } from "node:module";
+import { homedir as homedir5 } from "node:os";
+import { join as join8 } from "node:path";
+
+// src/shared/status.ts
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+function readString(value, fallback = "") {
+  return typeof value === "string" ? value : fallback;
+}
+function readNullableString(value) {
+  return typeof value === "string" ? value : null;
+}
+function readBoolean(value, fallback = false) {
+  return typeof value === "boolean" ? value : fallback;
+}
+function readNumber(value, fallback = 0) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function formatFlag(enabled) {
+  return enabled ? "enabled" : "disabled";
+}
+function formatCount(value) {
+  return value == null ? "—" : value.toLocaleString("en-US");
+}
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0)
+    return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= 1024 && unitIndex < units.length - 1) {
+    value /= 1024;
+    unitIndex++;
+  }
+  const decimals = value >= 10 || unitIndex === 0 ? 0 : 1;
+  return `${value.toFixed(decimals)} ${units[unitIndex]}`;
+}
+function coerceAftStatus(response) {
+  const features = asRecord(response.features);
+  const searchIndex = asRecord(response.search_index);
+  const semanticIndex = asRecord(response.semantic_index);
+  const semanticConfig = {
+    ...asRecord(response.semantic),
+    ...asRecord(response.semantic_config)
+  };
+  const disk = asRecord(response.disk);
+  const symbolCache = asRecord(response.symbol_cache);
+  return {
+    version: readString(response.version, "unknown"),
+    project_root: readNullableString(response.project_root),
+    features: {
+      format_on_edit: readBoolean(features.format_on_edit),
+      validate_on_edit: readString(features.validate_on_edit, "off"),
+      restrict_to_project_root: readBoolean(features.restrict_to_project_root),
+      experimental_search_index: readBoolean(features.experimental_search_index),
+      experimental_semantic_search: readBoolean(features.experimental_semantic_search)
+    },
+    search_index: {
+      status: readString(searchIndex.status, "unknown"),
+      files: readOptionalNumber(searchIndex.files),
+      trigrams: readOptionalNumber(searchIndex.trigrams)
+    },
+    semantic_index: {
+      status: readString(semanticIndex.status, "unknown"),
+      backend: readNullableString(semanticIndex.backend ?? semanticConfig.backend),
+      model: readNullableString(semanticIndex.model ?? semanticConfig.model),
+      stage: readNullableString(semanticIndex.stage),
+      files: readOptionalNumber(semanticIndex.files),
+      entries_done: readOptionalNumber(semanticIndex.entries_done),
+      entries_total: readOptionalNumber(semanticIndex.entries_total),
+      entries: readOptionalNumber(semanticIndex.entries),
+      dimension: readOptionalNumber(semanticIndex.dimension),
+      error: readNullableString(semanticIndex.error)
+    },
+    disk: {
+      storage_dir: readNullableString(disk.storage_dir),
+      trigram_disk_bytes: readNumber(disk.trigram_disk_bytes),
+      semantic_disk_bytes: readNumber(disk.semantic_disk_bytes)
+    },
+    lsp_servers: readNumber(response.lsp_servers),
+    symbol_cache: {
+      local_entries: readNumber(symbolCache.local_entries),
+      warm_entries: readNumber(symbolCache.warm_entries)
+    },
+    storage_dir: readNullableString(response.storage_dir)
+  };
+}
+function formatStatusDialogMessage(status) {
+  const lines = [
+    `AFT version: ${status.version}`,
+    `Project root: ${status.project_root ?? "(not configured)"}`,
+    "",
+    "Enabled features",
+    `- format_on_edit: ${formatFlag(status.features.format_on_edit)}`,
+    `- experimental_search_index: ${formatFlag(status.features.experimental_search_index)}`,
+    `- experimental_semantic_search: ${formatFlag(status.features.experimental_semantic_search)}`,
+    "",
+    "Search index",
+    `- status: ${status.search_index.status}`,
+    `- files: ${formatCount(status.search_index.files)}`,
+    `- trigrams: ${formatCount(status.search_index.trigrams)}`,
+    "",
+    "Semantic index",
+    `- status: ${status.semantic_index.status}`,
+    `- entries: ${formatCount(status.semantic_index.entries)}`
+  ];
+  if (status.semantic_index.backend) {
+    lines.push(`- backend: ${status.semantic_index.backend}`);
+  }
+  if (status.semantic_index.model) {
+    lines.push(`- model: ${status.semantic_index.model}`);
+  }
+  if (status.semantic_index.dimension != null) {
+    lines.push(`- dimension: ${formatCount(status.semantic_index.dimension)}`);
+  }
+  lines.push("", "Disk usage", `- trigram index: ${formatBytes(status.disk.trigram_disk_bytes)}`, `- semantic index: ${formatBytes(status.disk.semantic_disk_bytes)}`, "", "Runtime", `- LSP servers: ${formatCount(status.lsp_servers)}`, `- symbol cache: ${formatCount(status.symbol_cache.local_entries)} local / ${formatCount(status.symbol_cache.warm_entries)} warm`);
+  if (status.storage_dir ?? status.disk.storage_dir) {
+    lines.push(`- storage dir: ${status.storage_dir ?? status.disk.storage_dir}`);
+  }
+  if (status.semantic_index.stage) {
+    lines.push("", "Semantic stage", status.semantic_index.stage);
+  }
+  if (status.semantic_index.files != null) {
+    lines.push(`- semantic files: ${formatCount(status.semantic_index.files)}`);
+  }
+  if (status.semantic_index.entries_done != null || status.semantic_index.entries_total != null) {
+    lines.push(`- semantic progress: ${formatCount(status.semantic_index.entries_done ?? null)} / ${formatCount(status.semantic_index.entries_total ?? null)}`);
+  }
+  if (status.semantic_index.error) {
+    lines.push("", "Semantic error", status.semantic_index.error);
+  }
+  return lines.join(`
+`);
+}
+
+// src/tools/_shared.ts
+function bridgeFor(ctx, cwd) {
+  return ctx.pool.getBridge(cwd);
+}
+async function callBridge(bridge, command, params = {}) {
+  const response = await bridge.send(command, params);
+  if (response.success === false) {
+    const message = typeof response.message === "string" && response.message.length > 0 ? response.message : `${command} failed`;
+    throw new Error(message);
+  }
+  return response;
+}
+function textResult(text, details) {
+  return {
+    content: [{ type: "text", text }],
+    details
+  };
+}
+
+// src/commands/aft-status.ts
+function registerStatusCommand(pi, ctx) {
+  pi.registerCommand("aft-status", {
+    description: "Show AFT plugin status (search/semantic indexes, LSP, storage)",
+    handler: async (_args, extCtx) => {
+      try {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "status");
+        const snapshot = coerceAftStatus(response);
+        const text = formatStatusDialogMessage(snapshot);
+        if (extCtx.hasUI) {
+          await extCtx.ui.input("AFT Status", text);
+        } else {
+          extCtx.ui.notify(text, "info");
+        }
+      } catch (err) {
+        const message = `AFT status failed: ${err instanceof Error ? err.message : String(err)}`;
+        if (extCtx.hasUI) {
+          extCtx.ui.notify(message, "error");
+        } else {
+          console.error(`[aft-plugin] ${message}`);
+        }
+      }
+    }
+  });
+}
+
+// src/config.ts
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as join2 } from "node:path";
+
+// src/logger.ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+var TAG = "[aft-pi]";
+var logFile = path.join(os.tmpdir(), "aft-pi.log");
+var useStderr = process.env.AFT_LOG_STDERR === "1";
+var buffer = [];
+var flushTimer = null;
+var FLUSH_INTERVAL_MS = 500;
+var BUFFER_SIZE_LIMIT = 50;
+function flush() {
+  if (buffer.length === 0)
+    return;
+  const data = buffer.join("");
+  buffer = [];
+  try {
+    if (useStderr) {
+      process.stderr.write(data);
+    } else {
+      fs.appendFileSync(logFile, data);
+    }
+  } catch {}
+}
+function scheduleFlush() {
+  if (flushTimer)
+    return;
+  flushTimer = setTimeout(() => {
+    flushTimer = null;
+    flush();
+  }, FLUSH_INTERVAL_MS);
+  if (flushTimer && typeof flushTimer === "object" && "unref" in flushTimer) {
+    flushTimer.unref();
+  }
+}
+function write(level, message, data) {
+  try {
+    const timestamp = new Date().toISOString();
+    const serialized = data === undefined ? "" : ` ${JSON.stringify(data)}`;
+    const line = `[${timestamp}] ${level} ${TAG} ${message}${serialized}
+`;
+    if (useStderr) {
+      process.stderr.write(line);
+      return;
+    }
+    buffer.push(line);
+    if (buffer.length >= BUFFER_SIZE_LIMIT) {
+      flush();
+    } else {
+      scheduleFlush();
+    }
+  } catch {}
+}
+function log(message, data) {
+  write("INFO", message, data);
+}
+function warn(message, data) {
+  write("WARN", message, data);
+}
+function error(message, data) {
+  write("ERROR", message, data);
+}
+function getLogFilePath() {
+  return logFile;
+}
+
+// src/config.ts
+function stripJsonc(input) {
+  let result = "";
+  let i = 0;
+  const n = input.length;
+  let inString = false;
+  let stringChar = "";
+  while (i < n) {
+    const ch = input[i];
+    const next = input[i + 1];
+    if (inString) {
+      result += ch;
+      if (ch === "\\" && i + 1 < n) {
+        result += input[i + 1];
+        i += 2;
+        continue;
+      }
+      if (ch === stringChar)
+        inString = false;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringChar = ch;
+      result += ch;
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      while (i < n && input[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(input[i] === "*" && input[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    result += ch;
+    i++;
+  }
+  return result.replace(/,(\s*[}\]])/g, "$1");
+}
+function detectConfigFile(basePath) {
+  const jsoncPath = `${basePath}.jsonc`;
+  const jsonPath = `${basePath}.json`;
+  if (existsSync(jsoncPath))
+    return { format: "jsonc", path: jsoncPath };
+  if (existsSync(jsonPath))
+    return { format: "json", path: jsonPath };
+  return { format: "none", path: jsonPath };
+}
+function loadConfigFromPath(configPath) {
+  try {
+    if (!existsSync(configPath))
+      return null;
+    const content = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(stripJsonc(content));
+    log(`Config loaded from ${configPath}`);
+    return parsed;
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    error(`Error loading config from ${configPath}: ${errorMsg}`);
+    return null;
+  }
+}
+function mergeSemanticConfig(base, override) {
+  const projectSafe = {};
+  if (override?.model !== undefined)
+    projectSafe.model = override.model;
+  if (override?.timeout_ms !== undefined)
+    projectSafe.timeout_ms = override.timeout_ms;
+  if (override?.max_batch_size !== undefined)
+    projectSafe.max_batch_size = override.max_batch_size;
+  const semantic = { ...base, ...projectSafe };
+  if (Object.values(semantic).every((v) => v === undefined))
+    return;
+  return Object.fromEntries(Object.entries(semantic).filter(([, v]) => v !== undefined));
+}
+function mergeConfigs(base, override) {
+  const disabledTools = [...base.disabled_tools ?? [], ...override.disabled_tools ?? []];
+  const formatter = { ...base.formatter, ...override.formatter };
+  const checker = { ...base.checker, ...override.checker };
+  const semantic = mergeSemanticConfig(base.semantic, override.semantic);
+  const { semantic: _stripSemantic, ...safeOverride } = override;
+  return {
+    ...base,
+    ...safeOverride,
+    ...Object.keys(formatter).length > 0 ? { formatter } : {},
+    ...Object.keys(checker).length > 0 ? { checker } : {},
+    semantic,
+    ...disabledTools.length > 0 ? { disabled_tools: [...new Set(disabledTools)] } : {}
+  };
+}
+function getGlobalPiDir() {
+  return join2(homedir(), ".pi", "agent");
+}
+function loadAftConfig(projectDirectory) {
+  const userBasePath = join2(getGlobalPiDir(), "aft");
+  const userDetected = detectConfigFile(userBasePath);
+  const userConfigPath = userDetected.format !== "none" ? userDetected.path : `${userBasePath}.json`;
+  const projectBasePath = join2(projectDirectory, ".pi", "aft");
+  const projectDetected = detectConfigFile(projectBasePath);
+  const projectConfigPath = projectDetected.format !== "none" ? projectDetected.path : `${projectBasePath}.json`;
+  let config = loadConfigFromPath(userConfigPath) ?? {};
+  const projectConfig = loadConfigFromPath(projectConfigPath);
+  if (projectConfig) {
+    if (projectConfig.semantic?.backend !== undefined || projectConfig.semantic?.base_url !== undefined || projectConfig.semantic?.api_key_env !== undefined) {
+      warn("Ignoring semantic.backend/base_url/api_key_env from project config (security: use user config for external backends)");
+    }
+    config = mergeConfigs(config, projectConfig);
+  }
+  return config;
+}
+
+// src/onnx-runtime.ts
+import { chmodSync, existsSync as existsSync2, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { join as join3 } from "node:path";
+var ORT_VERSION = "1.24.4";
+var ORT_REPO = "microsoft/onnxruntime";
+var ORT_PLATFORM_MAP = {
+  darwin: {
+    arm64: {
+      assetName: `onnxruntime-osx-arm64-${ORT_VERSION}`,
+      libName: "libonnxruntime.dylib",
+      archiveType: "tgz"
+    }
+  },
+  linux: {
+    x64: {
+      assetName: `onnxruntime-linux-x64-${ORT_VERSION}`,
+      libName: "libonnxruntime.so",
+      archiveType: "tgz"
+    },
+    arm64: {
+      assetName: `onnxruntime-linux-aarch64-${ORT_VERSION}`,
+      libName: "libonnxruntime.so",
+      archiveType: "tgz"
+    }
+  },
+  win32: {
+    x64: {
+      assetName: `onnxruntime-win-x64-${ORT_VERSION}`,
+      libName: "onnxruntime.dll",
+      archiveType: "zip"
+    },
+    arm64: {
+      assetName: `onnxruntime-win-arm64-${ORT_VERSION}`,
+      libName: "onnxruntime.dll",
+      archiveType: "zip"
+    }
+  }
+};
+function getPlatformInfo() {
+  const platformMap = ORT_PLATFORM_MAP[process.platform];
+  if (!platformMap)
+    return null;
+  return platformMap[process.arch] || null;
+}
+function getManualInstallHint() {
+  if (process.platform === "darwin" && process.arch === "x64") {
+    return "brew install onnxruntime";
+  }
+  if (process.platform === "linux") {
+    return "apt install libonnxruntime or download from https://github.com/microsoft/onnxruntime/releases";
+  }
+  return "Download from https://github.com/microsoft/onnxruntime/releases";
+}
+async function ensureOnnxRuntime(storageDir) {
+  const info = getPlatformInfo();
+  const ortDir = join3(storageDir, "onnxruntime", ORT_VERSION);
+  const libPath = join3(ortDir, info?.libName ?? "libonnxruntime.dylib");
+  if (existsSync2(libPath)) {
+    log(`ONNX Runtime found at ${ortDir}`);
+    return ortDir;
+  }
+  const systemPath = findSystemOnnxRuntime(info?.libName);
+  if (systemPath) {
+    log(`ONNX Runtime found at system path: ${systemPath}`);
+    return systemPath;
+  }
+  if (!info) {
+    warn(`ONNX Runtime auto-download not available for ${process.platform}/${process.arch}. Install manually: ${getManualInstallHint()}`);
+    return null;
+  }
+  return downloadOnnxRuntime(info, ortDir);
+}
+function findSystemOnnxRuntime(libName) {
+  if (!libName)
+    return null;
+  const searchPaths = [];
+  if (process.platform === "darwin") {
+    searchPaths.push("/opt/homebrew/lib", "/usr/local/lib");
+  } else if (process.platform === "linux") {
+    searchPaths.push("/usr/lib", "/usr/lib/x86_64-linux-gnu", "/usr/lib/aarch64-linux-gnu", "/usr/local/lib");
+  }
+  for (const dir of searchPaths) {
+    if (existsSync2(join3(dir, libName))) {
+      return dir;
+    }
+  }
+  return null;
+}
+async function downloadOnnxRuntime(info, targetDir) {
+  const url = `https://github.com/${ORT_REPO}/releases/download/v${ORT_VERSION}/${info.assetName}.${info.archiveType === "tgz" ? "tgz" : "zip"}`;
+  log(`Downloading ONNX Runtime v${ORT_VERSION} for ${process.platform}/${process.arch}...`);
+  try {
+    const tmpDir = `${targetDir}.tmp.${process.pid}`;
+    mkdirSync(tmpDir, { recursive: true });
+    const archivePath = join3(tmpDir, `onnxruntime.${info.archiveType}`);
+    const { execSync: execSyncDl } = await import("node:child_process");
+    execSyncDl(`curl -fsSL "${url}" -o "${archivePath}"`, {
+      stdio: "pipe",
+      timeout: 120000
+    });
+    if (info.archiveType === "tgz") {
+      const { execSync } = await import("node:child_process");
+      execSync(`tar xzf "${archivePath}" -C "${tmpDir}"`, { stdio: "pipe" });
+    } else {
+      await extractZipArchive(archivePath, tmpDir);
+    }
+    const extractedDir = join3(tmpDir, info.assetName, "lib");
+    if (!existsSync2(extractedDir)) {
+      throw new Error(`Expected directory not found: ${extractedDir}`);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    const libFiles = readdirSync(extractedDir).filter((f) => f.startsWith("libonnxruntime") || f.startsWith("onnxruntime"));
+    const { lstatSync, symlinkSync, readlinkSync, copyFileSync: cpFile } = await import("node:fs");
+    const realFiles = [];
+    const symlinks = [];
+    for (const libFile of libFiles) {
+      const src = join3(extractedDir, libFile);
+      try {
+        const stat = lstatSync(src);
+        log(`ORT extract: ${libFile} — isSymlink=${stat.isSymbolicLink()}, isFile=${stat.isFile()}, size=${stat.size}`);
+        if (stat.isSymbolicLink()) {
+          symlinks.push({ name: libFile, target: readlinkSync(src) });
+        } else {
+          realFiles.push(libFile);
+        }
+      } catch (e) {
+        log(`ORT extract: ${libFile} — stat failed: ${e}`);
+        realFiles.push(libFile);
+      }
+    }
+    for (const libFile of realFiles) {
+      const src = join3(extractedDir, libFile);
+      const dst = join3(targetDir, libFile);
+      try {
+        cpFile(src, dst);
+        if (process.platform !== "win32") {
+          chmodSync(dst, 493);
+        }
+      } catch (copyErr) {
+        log(`ORT extract: failed to copy ${libFile}: ${copyErr}`);
+      }
+    }
+    for (const link of symlinks) {
+      const dst = join3(targetDir, link.name);
+      try {
+        unlinkSync(dst);
+      } catch {}
+      symlinkSync(link.target, dst);
+    }
+    const { rmSync } = await import("node:fs");
+    rmSync(tmpDir, { recursive: true, force: true });
+    log(`ONNX Runtime v${ORT_VERSION} installed to ${targetDir}`);
+    return targetDir;
+  } catch (err) {
+    error(`Failed to download ONNX Runtime: ${err}`);
+    try {
+      const { rmSync } = await import("node:fs");
+      rmSync(`${targetDir}.tmp.${process.pid}`, { recursive: true, force: true });
+    } catch {}
+    return null;
+  }
+}
+async function extractZipArchive(archivePath, destinationDir) {
+  const { execFileSync } = await import("node:child_process");
+  if (process.platform === "win32") {
+    let powershellError;
+    try {
+      execFileSync("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-Command",
+        "& { Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force }",
+        archivePath,
+        destinationDir
+      ], { stdio: "pipe", timeout: 120000 });
+      return;
+    } catch (err) {
+      powershellError = err;
+      warn(`PowerShell Expand-Archive failed, falling back to cmd/tar: ${String(err)}`);
+    }
+    try {
+      execFileSync("cmd.exe", ["/d", "/s", "/c", `tar -xf "${archivePath}" -C "${destinationDir}"`], { stdio: "pipe", timeout: 120000 });
+      return;
+    } catch (cmdError) {
+      throw new Error(`ZIP extraction failed via PowerShell and cmd/tar. PowerShell: ${String(powershellError)} | cmd/tar: ${String(cmdError)}`);
+    }
+  }
+  execFileSync("unzip", ["-q", archivePath, "-d", destinationDir], {
+    stdio: "pipe",
+    timeout: 120000
+  });
+}
+
+// src/bridge.ts
+import { spawn } from "node:child_process";
+import { homedir as homedir2 } from "node:os";
+import { join as join4 } from "node:path";
+var DEFAULT_BRIDGE_TIMEOUT_MS = 30000;
+var SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS = 5000;
+function compareSemver(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0;i < 3; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0)
+      return diff;
+  }
+  return 0;
+}
+function clampSemanticTimeout(configOverrides, bridgeTimeoutMs) {
+  const semantic = configOverrides.semantic;
+  if (!semantic || typeof semantic !== "object" || Array.isArray(semantic)) {
+    return configOverrides;
+  }
+  const timeoutMs = semantic.timeout_ms;
+  if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+    return configOverrides;
+  }
+  const maxSemanticTimeoutMs = bridgeTimeoutMs > SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS ? bridgeTimeoutMs - SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS : Math.max(1, bridgeTimeoutMs - 1);
+  if (timeoutMs <= maxSemanticTimeoutMs) {
+    return configOverrides;
+  }
+  warn(`semantic.timeout_ms=${timeoutMs} exceeds bridge timeout budget; clamping to ${maxSemanticTimeoutMs}ms (bridge timeout: ${bridgeTimeoutMs}ms)`);
+  return {
+    ...configOverrides,
+    semantic: {
+      ...semantic,
+      timeout_ms: maxSemanticTimeoutMs
+    }
+  };
+}
+
+class BinaryBridge {
+  static RESTART_RESET_MS = 5 * 60 * 1000;
+  static STDERR_TAIL_MAX = 20;
+  binaryPath;
+  cwd;
+  process = null;
+  pending = new Map;
+  nextId = 1;
+  stdoutBuffer = "";
+  stderrTail = [];
+  _restartCount = 0;
+  _shuttingDown = false;
+  timeoutMs;
+  maxRestarts;
+  configured = false;
+  _configurePromise = null;
+  configOverrides;
+  minVersion;
+  onVersionMismatch;
+  restartResetTimer = null;
+  constructor(binaryPath, cwd, options, configOverrides) {
+    this.binaryPath = binaryPath;
+    this.cwd = cwd;
+    this.timeoutMs = options?.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS;
+    this.maxRestarts = options?.maxRestarts ?? 3;
+    this.configOverrides = clampSemanticTimeout(configOverrides ?? {}, this.timeoutMs);
+    this.minVersion = options?.minVersion;
+    this.onVersionMismatch = options?.onVersionMismatch;
+  }
+  get restartCount() {
+    return this._restartCount;
+  }
+  isAlive() {
+    return this.process !== null && this.process.exitCode === null && !this.process.killed;
+  }
+  async send(command, params = {}) {
+    if (this._shuttingDown) {
+      throw new Error(`[aft-pi] Bridge is shutting down, cannot send "${command}"`);
+    }
+    this.ensureSpawned();
+    if (!this.configured) {
+      if (command !== "configure" && command !== "version") {
+        if (!this._configurePromise) {
+          this._configurePromise = (async () => {
+            try {
+              const configResult = await this.send("configure", {
+                project_root: this.cwd,
+                ...this.configOverrides
+              });
+              if (configResult.success === false) {
+                throw new Error(`[aft-pi] Configure failed: ${configResult.message ?? "unknown error"}`);
+              }
+              await this.checkVersion();
+              if (!this.isAlive()) {
+                throw new Error(`[aft-pi] Bridge died during version check. Check logs: ${getLogFilePath()}`);
+              }
+              this.configured = true;
+            } finally {
+              this._configurePromise = null;
+            }
+          })();
+        }
+        await this._configurePromise;
+      }
+    }
+    const id = String(this.nextId++);
+    const request = { id, command, ...params };
+    const line = `${JSON.stringify(request)}
+`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        warn(`Request "${command}" (id=${id}) timed out after ${this.timeoutMs}ms — restarting bridge`);
+        reject(new Error(`[aft-pi] Request "${command}" (id=${id}) timed out after ${this.timeoutMs}ms`));
+        this.handleTimeout();
+      }, this.timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      if (!this.process?.stdin?.writable) {
+        this.pending.delete(id);
+        clearTimeout(timer);
+        reject(new Error(`[aft-pi] stdin not writable for command "${command}"`));
+        return;
+      }
+      this.process.stdin.write(line, (err) => {
+        if (err) {
+          const entry = this.pending.get(id);
+          if (entry) {
+            this.pending.delete(id);
+            clearTimeout(entry.timer);
+            entry.reject(new Error(`[aft-pi] Failed to write to stdin: ${err.message}`));
+          }
+        }
+      });
+    });
+  }
+  async shutdown() {
+    this._shuttingDown = true;
+    this.clearRestartResetTimer();
+    this.rejectAllPending(new Error("[aft-pi] Bridge shutting down"));
+    if (this.process) {
+      const proc = this.process;
+      this.process = null;
+      return new Promise((resolve) => {
+        const forceKillTimer = setTimeout(() => {
+          proc.kill("SIGKILL");
+          resolve();
+        }, 5000);
+        proc.once("exit", () => {
+          clearTimeout(forceKillTimer);
+          log("Process exited during shutdown");
+          resolve();
+        });
+        proc.kill("SIGTERM");
+      });
+    }
+  }
+  async checkVersion() {
+    if (!this.minVersion)
+      return;
+    try {
+      const resp = await this.send("version");
+      const binaryVersion = resp.version;
+      if (!binaryVersion) {
+        log("Binary did not report a version — skipping version check");
+        return;
+      }
+      log(`Binary version: ${binaryVersion}`);
+      if (compareSemver(binaryVersion, this.minVersion) < 0) {
+        warn(`Binary version ${binaryVersion} is older than required ${this.minVersion}`);
+        this.onVersionMismatch?.(binaryVersion, this.minVersion);
+      }
+    } catch (err) {
+      warn(`Version check failed: ${err.message}`);
+    }
+  }
+  ensureSpawned() {
+    if (this.isAlive())
+      return;
+    this.spawnProcess();
+  }
+  spawnProcess() {
+    log(`Spawning binary: ${this.binaryPath} (cwd: ${this.cwd})`);
+    const semantic = this.configOverrides.semantic;
+    const semanticBackend = (() => {
+      if (semantic && typeof semantic === "object" && !Array.isArray(semantic)) {
+        const candidate = semantic.backend;
+        return typeof candidate === "string" ? candidate : undefined;
+      }
+      return;
+    })();
+    const useFastembedBackend = semanticBackend === undefined || semanticBackend === "fastembed" || semanticBackend === "";
+    const ortDir = typeof this.configOverrides._ort_dylib_dir === "string" && useFastembedBackend ? this.configOverrides._ort_dylib_dir : null;
+    const ortLibraryPath = ortDir == null ? null : join4(ortDir, process.platform === "win32" ? "onnxruntime.dll" : process.platform === "darwin" ? "libonnxruntime.dylib" : "libonnxruntime.so");
+    const envPath = process.platform === "win32" && ortDir ? `${ortDir};${process.env.PATH ?? ""}` : process.env.PATH;
+    const env = {
+      ...process.env,
+      ...envPath ? { PATH: envPath } : {}
+    };
+    if (useFastembedBackend) {
+      env.FASTEMBED_CACHE_DIR = process.env.FASTEMBED_CACHE_DIR || (typeof this.configOverrides.storage_dir === "string" ? join4(this.configOverrides.storage_dir, "semantic", "models") : join4(homedir2() || "", ".cache", "fastembed"));
+      if (ortLibraryPath) {
+        env.ORT_DYLIB_PATH = ortLibraryPath;
+      }
+    }
+    const child = spawn(this.binaryPath, [], {
+      cwd: this.cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+      env
+    });
+    child.stdout?.on("data", (chunk) => {
+      this.onStdoutData(chunk.toString("utf-8"));
+    });
+    child.stderr?.on("data", (chunk) => {
+      const lines = chunk.toString("utf-8").trimEnd().split(`
+`);
+      for (const line of lines) {
+        if (!line)
+          continue;
+        const stripped = line.replace(/^\[aft\]\s*/, "");
+        log(`[aft] ${stripped}`);
+        this.pushStderrLine(stripped);
+      }
+    });
+    child.on("error", (err) => {
+      error(`Process error: ${err.message}${this.formatStderrTail()}`);
+      this.handleCrash();
+    });
+    child.on("exit", (code, signal) => {
+      if (this._shuttingDown)
+        return;
+      log(`Process exited: code=${code}, signal=${signal}`);
+      if (signal === "SIGTERM" || signal === "SIGKILL" || signal === "SIGHUP" || signal === "SIGINT") {
+        this.process = null;
+        this.configured = false;
+        this.clearRestartResetTimer();
+        this.rejectAllPending(new Error(`[aft-pi] Binary killed by ${signal}`));
+        return;
+      }
+      this.handleCrash();
+    });
+    this.process = child;
+    this.stdoutBuffer = "";
+    this.stderrTail = [];
+  }
+  pushStderrLine(line) {
+    this.stderrTail.push(line);
+    if (this.stderrTail.length > BinaryBridge.STDERR_TAIL_MAX) {
+      this.stderrTail.shift();
+    }
+  }
+  formatStderrTail() {
+    if (this.stderrTail.length === 0)
+      return "";
+    const tail = this.stderrTail.join(`
+  `);
+    return `
+  --- last ${this.stderrTail.length} stderr lines ---
+  ${tail}`;
+  }
+  onStdoutData(data) {
+    this.stdoutBuffer += data;
+    let newlineIdx;
+    while ((newlineIdx = this.stdoutBuffer.indexOf(`
+`)) !== -1) {
+      const line = this.stdoutBuffer.slice(0, newlineIdx).trim();
+      this.stdoutBuffer = this.stdoutBuffer.slice(newlineIdx + 1);
+      if (!line)
+        continue;
+      try {
+        const response = JSON.parse(line);
+        const id = response.id;
+        if (id && this.pending.has(id)) {
+          const entry = this.pending.get(id);
+          if (!entry)
+            continue;
+          this.pending.delete(id);
+          clearTimeout(entry.timer);
+          this.scheduleRestartCountReset();
+          entry.resolve(response);
+        }
+      } catch (_err) {
+        warn(`Failed to parse stdout line: ${line}`);
+      }
+    }
+  }
+  handleTimeout() {
+    if (this.process) {
+      this.process.kill("SIGKILL");
+      this.process = null;
+    }
+    this.clearRestartResetTimer();
+    this.configured = false;
+    const tail = this.formatStderrTail();
+    this.stderrTail = [];
+    this.rejectAllPending(new Error(`[aft-pi] Bridge restarted after timeout${tail}`));
+  }
+  handleCrash() {
+    this.process = null;
+    this.clearRestartResetTimer();
+    this.configured = false;
+    const tail = this.formatStderrTail();
+    this.rejectAllPending(new Error(`[aft-pi] Binary crashed (restarts: ${this._restartCount})${tail}`));
+    if (this._restartCount < this.maxRestarts) {
+      const delay = 100 * 2 ** this._restartCount;
+      this._restartCount++;
+      log(`Auto-restart #${this._restartCount} in ${delay}ms`);
+      setTimeout(() => {
+        if (!this._shuttingDown && !this.isAlive()) {
+          try {
+            this.spawnProcess();
+          } catch (err) {
+            error(`Failed to restart: ${err.message}`);
+          }
+        }
+      }, delay);
+    } else {
+      error(`Max restarts (${this.maxRestarts}) reached, giving up. Logs: ${getLogFilePath()}${tail}`);
+    }
+  }
+  rejectAllPending(error2) {
+    for (const [_id, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(error2);
+    }
+    this.pending.clear();
+  }
+  scheduleRestartCountReset() {
+    this.clearRestartResetTimer();
+    this.restartResetTimer = setTimeout(() => {
+      this._restartCount = 0;
+      this.restartResetTimer = null;
+    }, BinaryBridge.RESTART_RESET_MS);
+  }
+  clearRestartResetTimer() {
+    if (this.restartResetTimer) {
+      clearTimeout(this.restartResetTimer);
+      this.restartResetTimer = null;
+    }
+  }
+}
+
+// src/pool.ts
+var DEFAULT_IDLE_TIMEOUT_MS = Infinity;
+var DEFAULT_MAX_POOL_SIZE = 4;
+var CLEANUP_INTERVAL_MS = 60 * 1000;
+
+class BridgePool {
+  bridges = new Map;
+  binaryPath;
+  maxPoolSize;
+  idleTimeoutMs;
+  bridgeOptions;
+  configOverrides;
+  cleanupTimer = null;
+  constructor(binaryPath, options = {}, configOverrides = {}) {
+    this.binaryPath = binaryPath;
+    this.maxPoolSize = options.maxPoolSize ?? DEFAULT_MAX_POOL_SIZE;
+    this.idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    this.bridgeOptions = {
+      timeoutMs: options.timeoutMs,
+      maxRestarts: options.maxRestarts,
+      minVersion: options.minVersion,
+      onVersionMismatch: options.onVersionMismatch
+    };
+    this.configOverrides = configOverrides;
+    if (Number.isFinite(this.idleTimeoutMs)) {
+      this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+      this.cleanupTimer.unref();
+    }
+  }
+  getAnyActiveBridge(_directory) {
+    for (const [, entry] of this.bridges) {
+      if (entry.bridge.isAlive()) {
+        entry.lastUsed = Date.now();
+        return entry.bridge;
+      }
+    }
+    return null;
+  }
+  getBridge(directory) {
+    const key = directory.replace(/\/+$/, "");
+    const existing = this.bridges.get(key);
+    if (existing) {
+      existing.lastUsed = Date.now();
+      return existing.bridge;
+    }
+    if (this.bridges.size >= this.maxPoolSize) {
+      this.evictLRU();
+    }
+    const bridge = new BinaryBridge(this.binaryPath, key, this.bridgeOptions, this.configOverrides);
+    this.bridges.set(key, { bridge, lastUsed: Date.now() });
+    return bridge;
+  }
+  cleanup() {
+    const now = Date.now();
+    for (const [dir, entry] of this.bridges) {
+      if (now - entry.lastUsed > this.idleTimeoutMs) {
+        entry.bridge.shutdown().catch((err) => error("cleanup shutdown failed:", err));
+        this.bridges.delete(dir);
+      }
+    }
+  }
+  evictLRU() {
+    let oldestDir = null;
+    let oldestTime = Infinity;
+    for (const [dir, entry] of this.bridges) {
+      if (entry.lastUsed < oldestTime) {
+        oldestTime = entry.lastUsed;
+        oldestDir = dir;
+      }
+    }
+    if (oldestDir) {
+      const entry = this.bridges.get(oldestDir);
+      entry?.bridge.shutdown().catch((err) => error("eviction shutdown failed:", err));
+      this.bridges.delete(oldestDir);
+    }
+  }
+  async shutdown() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    const shutdowns = Array.from(this.bridges.values()).map((e) => e.bridge.shutdown());
+    this.bridges.clear();
+    await Promise.allSettled(shutdowns);
+  }
+  async replaceBinary(newPath) {
+    this.binaryPath = newPath;
+    for (const [, entry] of this.bridges) {
+      try {
+        entry.bridge.shutdown();
+      } catch {}
+    }
+    this.bridges.clear();
+    log(`Binary path updated to ${newPath}. All bridges cleared.`);
+  }
+  get size() {
+    return this.bridges.size;
+  }
+}
+
+// src/resolver.ts
+import { execSync, spawnSync } from "node:child_process";
+import { chmodSync as chmodSync3, copyFileSync, existsSync as existsSync4, mkdirSync as mkdirSync3, renameSync } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { homedir as homedir4 } from "node:os";
+import { join as join6 } from "node:path";
+
+// src/downloader.ts
+import { chmodSync as chmodSync2, existsSync as existsSync3, mkdirSync as mkdirSync2, unlinkSync as unlinkSync2 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join5 } from "node:path";
+
+// src/platform.ts
+var PLATFORM_ARCH_MAP = {
+  darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
+  linux: { arm64: "linux-arm64", x64: "linux-x64" },
+  win32: { x64: "win32-x64" }
+};
+var PLATFORM_ASSET_MAP = {
+  "darwin-arm64": "aft-darwin-arm64",
+  "darwin-x64": "aft-darwin-x64",
+  "linux-arm64": "aft-linux-arm64",
+  "linux-x64": "aft-linux-x64",
+  "win32-x64": "aft-win32-x64.exe"
+};
+
+// src/downloader.ts
+var REPO = "cortexkit/aft";
+function getCacheDir() {
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA || process.env.APPDATA;
+    const base2 = localAppData || join5(homedir3(), "AppData", "Local");
+    return join5(base2, "aft", "bin");
+  }
+  const base = process.env.XDG_CACHE_HOME || join5(homedir3(), ".cache");
+  return join5(base, "aft", "bin");
+}
+function getBinaryName() {
+  return process.platform === "win32" ? "aft.exe" : "aft";
+}
+function getCachedBinaryPath(version) {
+  if (!version)
+    return null;
+  const binaryPath = join5(getCacheDir(), version, getBinaryName());
+  return existsSync3(binaryPath) ? binaryPath : null;
+}
+async function downloadBinary(version) {
+  const platformKey = `${process.platform}-${process.arch}`;
+  const assetName = PLATFORM_ASSET_MAP[platformKey];
+  if (!assetName) {
+    error(`Unsupported platform: ${platformKey}`);
+    return null;
+  }
+  const tag = version ?? await fetchLatestTag();
+  if (!tag) {
+    error("Could not determine latest release version.");
+    return null;
+  }
+  const versionedCacheDir = join5(getCacheDir(), tag);
+  const binaryName = getBinaryName();
+  const binaryPath = join5(versionedCacheDir, binaryName);
+  if (existsSync3(binaryPath)) {
+    return binaryPath;
+  }
+  const downloadUrl = `https://github.com/${REPO}/releases/download/${tag}/${assetName}`;
+  const checksumUrl = `https://github.com/${REPO}/releases/download/${tag}/checksums.sha256`;
+  log(`Downloading AFT binary (${tag}) for ${platformKey}...`);
+  try {
+    if (!existsSync3(versionedCacheDir)) {
+      mkdirSync2(versionedCacheDir, { recursive: true });
+    }
+    const [binaryResponse, checksumResponse] = await Promise.all([
+      fetch(downloadUrl, { redirect: "follow" }),
+      fetch(checksumUrl, { redirect: "follow" })
+    ]);
+    if (!binaryResponse.ok) {
+      throw new Error(`HTTP ${binaryResponse.status}: ${binaryResponse.statusText} (${downloadUrl})`);
+    }
+    const arrayBuffer = await binaryResponse.arrayBuffer();
+    if (!checksumResponse.ok) {
+      warn(`Checksum verification failed: no checksums.sha256 found for ${tag}. ` + "Binary download aborted for security reasons.");
+      return null;
+    }
+    const checksumText = await checksumResponse.text();
+    const expectedHash = parseChecksumForAsset(checksumText, assetName);
+    if (!expectedHash) {
+      warn(`Checksum verification failed: checksums.sha256 found but no entry for ${assetName}. ` + "Binary download aborted for security reasons.");
+      return null;
+    }
+    const { createHash } = await import("node:crypto");
+    const actualHash = createHash("sha256").update(Buffer.from(arrayBuffer)).digest("hex");
+    if (actualHash !== expectedHash) {
+      throw new Error(`Checksum mismatch for ${assetName}: expected ${expectedHash}, got ${actualHash}. The binary may have been tampered with.`);
+    }
+    log(`Checksum verified (SHA-256: ${actualHash.slice(0, 16)}...)`);
+    const tmpPath = `${binaryPath}.tmp`;
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(tmpPath, Buffer.from(arrayBuffer));
+    if (process.platform !== "win32") {
+      chmodSync2(tmpPath, 493);
+    }
+    const { renameSync } = await import("node:fs");
+    renameSync(tmpPath, binaryPath);
+    log(`AFT binary ready at ${binaryPath}`);
+    return binaryPath;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    error(`Failed to download AFT binary: ${msg}`);
+    const tmpPath = `${binaryPath}.tmp`;
+    if (existsSync3(tmpPath)) {
+      try {
+        unlinkSync2(tmpPath);
+      } catch {}
+    }
+    return null;
+  }
+}
+async function ensureBinary(version) {
+  if (version) {
+    const versionCached = getCachedBinaryPath(version);
+    if (versionCached) {
+      log(`Found cached binary for ${version}: ${versionCached}`);
+      return versionCached;
+    }
+    log(`No cached binary for ${version}, downloading...`);
+    return downloadBinary(version);
+  }
+  const legacyCached = getCachedBinaryPath();
+  if (legacyCached) {
+    log(`Found cached binary: ${legacyCached}`);
+    return legacyCached;
+  }
+  log("No cached binary found, downloading latest...");
+  return downloadBinary();
+}
+function parseChecksumForAsset(checksumText, assetName) {
+  for (const line of checksumText.split(`
+`)) {
+    const trimmed = line.trim();
+    if (!trimmed)
+      continue;
+    const match = trimmed.match(/^([0-9a-f]{64})\s+(.+)$/);
+    if (match && match[2] === assetName) {
+      return match[1];
+    }
+  }
+  return null;
+}
+async function fetchLatestTag() {
+  try {
+    const response = await fetch(`https://api.github.com/repos/${REPO}/releases/latest`, {
+      headers: { Accept: "application/vnd.github.v3+json" }
+    });
+    if (!response.ok)
+      return null;
+    const data = await response.json();
+    return data.tag_name ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// src/resolver.ts
+function copyToVersionedCache(npmBinaryPath) {
+  try {
+    const result = spawnSync(npmBinaryPath, ["--version"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000
+    });
+    const rawVersion = result.stdout?.trim();
+    if (!rawVersion)
+      return null;
+    const version = rawVersion.replace(/^aft\s+/, "");
+    const tag = version.startsWith("v") ? version : `v${version}`;
+    const cacheDir = getCacheDir();
+    const versionedDir = join6(cacheDir, tag);
+    const ext = process.platform === "win32" ? ".exe" : "";
+    const cachedPath = join6(versionedDir, `aft${ext}`);
+    if (existsSync4(cachedPath))
+      return cachedPath;
+    mkdirSync3(versionedDir, { recursive: true });
+    const tmpPath = `${cachedPath}.tmp`;
+    copyFileSync(npmBinaryPath, tmpPath);
+    if (process.platform !== "win32") {
+      chmodSync3(tmpPath, 493);
+    }
+    renameSync(tmpPath, cachedPath);
+    log(`Copied npm binary to versioned cache: ${cachedPath}`);
+    return cachedPath;
+  } catch (err) {
+    warn(`Failed to copy binary to cache: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+function platformKey(platform = process.platform, arch = process.arch) {
+  const archMap = PLATFORM_ARCH_MAP[platform];
+  if (!archMap) {
+    throw new Error(`Unsupported platform: ${platform} (arch: ${arch}). ` + `Supported platforms: ${Object.keys(PLATFORM_ARCH_MAP).join(", ")}`);
+  }
+  const key = archMap[arch];
+  if (!key) {
+    throw new Error(`Unsupported architecture: ${arch} on platform ${platform}. ` + `Supported architectures for ${platform}: ${Object.keys(archMap).join(", ")}`);
+  }
+  return key;
+}
+function findBinarySync() {
+  const ext = process.platform === "win32" ? ".exe" : "";
+  const pluginVersion = (() => {
+    try {
+      const req = createRequire2(import.meta.url);
+      return `v${req("../package.json").version}`;
+    } catch {
+      return null;
+    }
+  })();
+  if (pluginVersion) {
+    const versionCached = getCachedBinaryPath(pluginVersion);
+    if (versionCached)
+      return versionCached;
+  }
+  try {
+    const key = platformKey();
+    const packageBin = `@cortexkit/aft-${key}/bin/aft${ext}`;
+    const req = createRequire2(import.meta.url);
+    const resolved = req.resolve(packageBin);
+    if (existsSync4(resolved)) {
+      const copied = copyToVersionedCache(resolved);
+      return copied ?? resolved;
+    }
+  } catch {}
+  try {
+    const whichCmd = process.platform === "win32" ? "where aft" : "which aft";
+    const result = execSync(whichCmd, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    if (result)
+      return result;
+  } catch {}
+  const cargoPath = join6(homedir4(), ".cargo", "bin", `aft${ext}`);
+  if (existsSync4(cargoPath))
+    return cargoPath;
+  return null;
+}
+async function findBinary() {
+  const syncResult = findBinarySync();
+  if (syncResult) {
+    log(`Resolved binary: ${syncResult}`);
+    return syncResult;
+  }
+  log("Binary not found locally, attempting auto-download...");
+  const downloaded = await ensureBinary();
+  if (downloaded)
+    return downloaded;
+  throw new Error([
+    "Could not find the `aft` binary.",
+    "",
+    "Attempted sources:",
+    "  - Cache directory (~/.cache/aft/bin/)",
+    "  - npm platform package (@cortexkit/aft-<platform>)",
+    "  - PATH lookup (which aft)",
+    "  - ~/.cargo/bin/aft",
+    "  - Auto-download from GitHub releases (failed)",
+    "",
+    "Install it using one of these methods:",
+    "  npm install @cortexkit/aft-pi              # installs platform-specific binary via npm",
+    "  cargo install agent-file-tools             # from crates.io",
+    "",
+    "Or add the aft directory to your PATH."
+  ].join(`
+`));
+}
+
+// src/shutdown-hooks.ts
+var GLOBAL_KEY = "__aftPiShutdownHooks__";
+function getState() {
+  const g = globalThis;
+  if (!g[GLOBAL_KEY]) {
+    g[GLOBAL_KEY] = { cleanups: new Set, installed: false };
+  }
+  return g[GLOBAL_KEY];
+}
+var shuttingDown = false;
+async function runCleanups(reason) {
+  if (shuttingDown)
+    return;
+  shuttingDown = true;
+  const state = getState();
+  if (state.cleanups.size === 0)
+    return;
+  log(`Shutdown triggered by ${reason} — running ${state.cleanups.size} cleanup(s)`);
+  const cleanups = Array.from(state.cleanups);
+  state.cleanups.clear();
+  await Promise.allSettled(cleanups.map(async (fn) => {
+    try {
+      await fn();
+    } catch (err) {
+      log(`Cleanup error: ${err.message}`);
+    }
+  }));
+}
+function installProcessHandlers() {
+  const state = getState();
+  if (state.installed)
+    return;
+  state.installed = true;
+  const signals = ["SIGTERM", "SIGINT", "SIGHUP"];
+  for (const sig of signals) {
+    process.on(sig, () => {
+      runCleanups(sig);
+    });
+  }
+  process.on("beforeExit", () => {
+    runCleanups("beforeExit");
+  });
+}
+function registerShutdownCleanup(fn) {
+  installProcessHandlers();
+  const state = getState();
+  state.cleanups.add(fn);
+  return () => {
+    state.cleanups.delete(fn);
+  };
+}
+
+// src/tools/ast.ts
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+var AstLang = StringEnum(["typescript", "tsx", "javascript", "python", "rust", "go"], {
+  description: "Target language"
+});
+var SearchParams = Type.Object({
+  pattern: Type.String({
+    description: "AST pattern with meta-variables (`$VAR` matches one node, `$$$` matches many). Must be a complete AST node."
+  }),
+  lang: AstLang,
+  paths: Type.Optional(Type.Array(Type.String(), { description: "Paths to search (default: ['.'])" })),
+  globs: Type.Optional(Type.Array(Type.String(), { description: "Include/exclude globs (prefix `!` to exclude)" })),
+  contextLines: Type.Optional(Type.Number({ description: "Number of context lines around each match" }))
+});
+var ReplaceParams = Type.Object({
+  pattern: Type.String({ description: "AST pattern with meta-variables" }),
+  rewrite: Type.String({ description: "Replacement pattern, can reference $VAR from pattern" }),
+  lang: AstLang,
+  paths: Type.Optional(Type.Array(Type.String(), { description: "Paths (default: ['.'])" })),
+  globs: Type.Optional(Type.Array(Type.String(), { description: "Include/exclude globs" })),
+  dryRun: Type.Optional(Type.Boolean({ description: "Preview without applying (default: false)" }))
+});
+function registerAstTools(pi, ctx, surface) {
+  if (surface.astSearch) {
+    pi.registerTool({
+      name: "ast_grep_search",
+      label: "ast search",
+      description: "Search code patterns across the filesystem using AST-aware matching. Use `$VAR` to match a single AST node, `$$$` for multiple. Pattern must be a complete, valid code fragment (include braces, params, etc.).",
+      parameters: SearchParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const req = {
+          pattern: params.pattern,
+          lang: params.lang
+        };
+        if (params.paths !== undefined)
+          req.paths = params.paths;
+        if (params.globs !== undefined)
+          req.globs = params.globs;
+        if (params.contextLines !== undefined)
+          req.context_lines = params.contextLines;
+        const response = await callBridge(bridge, "ast_search", req);
+        return textResult(response.text ?? JSON.stringify(response));
+      }
+    });
+  }
+  if (surface.astReplace) {
+    pi.registerTool({
+      name: "ast_grep_replace",
+      label: "ast replace",
+      description: "Replace code patterns across the filesystem with AST-aware rewriting. Applies by default — pass `dryRun: true` to preview. Use meta-variables in `rewrite` to preserve captured content from the pattern.",
+      parameters: ReplaceParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const req = {
+          pattern: params.pattern,
+          rewrite: params.rewrite,
+          lang: params.lang
+        };
+        if (params.paths !== undefined)
+          req.paths = params.paths;
+        if (params.globs !== undefined)
+          req.globs = params.globs;
+        req.dry_run = params.dryRun === true;
+        const response = await callBridge(bridge, "ast_replace", req);
+        return textResult(response.text ?? JSON.stringify(response));
+      }
+    });
+  }
+}
+
+// src/tools/conflicts.ts
+import { Type as Type2 } from "@sinclair/typebox";
+var ConflictsParams = Type2.Object({});
+function registerConflictsTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_conflicts",
+    label: "conflicts",
+    description: "Show all git merge conflicts across the repository — returns line-numbered conflict regions with context for every conflicted file in a single call.",
+    parameters: ConflictsParams,
+    async execute(_toolCallId, _params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const response = await callBridge(bridge, "git_conflicts");
+      return textResult(response.text ?? JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/fs.ts
+import { Type as Type3 } from "@sinclair/typebox";
+var DeleteParams = Type3.Object({
+  filePath: Type3.String({ description: "Path to file to delete" })
+});
+var MoveParams = Type3.Object({
+  filePath: Type3.String({ description: "Source file path to move" }),
+  destination: Type3.String({ description: "Destination file path" })
+});
+function registerFsTools(pi, ctx, surface) {
+  if (surface.delete) {
+    pi.registerTool({
+      name: "aft_delete",
+      label: "delete",
+      description: "Delete a file with backup. The file content is backed up before deletion — use `aft_safety undo` to recover.",
+      parameters: DeleteParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "delete_file", { file: params.filePath });
+        return textResult(`Deleted ${params.filePath}`, response);
+      }
+    });
+  }
+  if (surface.move) {
+    pi.registerTool({
+      name: "aft_move",
+      label: "move",
+      description: "Move or rename a file with backup. Creates parent directories for the destination automatically. This operates on files at the OS level — to relocate a code symbol between files, use `aft_refactor` with op='move' instead.",
+      parameters: MoveParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "move_file", {
+          file: params.filePath,
+          destination: params.destination
+        });
+        return textResult(`Moved ${params.filePath} → ${params.destination}`, response);
+      }
+    });
+  }
+}
+
+// src/tools/hoisted.ts
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Type as Type4 } from "@sinclair/typebox";
+var ReadParams = Type4.Object({
+  path: Type4.String({ description: "Path to the file to read (relative or absolute)" }),
+  offset: Type4.Optional(Type4.Number({ description: "Line number to start reading from (1-indexed)" })),
+  limit: Type4.Optional(Type4.Number({ description: "Maximum number of lines to read" }))
+});
+var WriteParams = Type4.Object({
+  filePath: Type4.String({
+    description: "Path to the file to write (absolute or project-relative)"
+  }),
+  content: Type4.String({ description: "Full file contents to write" })
+});
+var EditParams = Type4.Object({
+  filePath: Type4.String({ description: "Path to the file to edit" }),
+  oldString: Type4.Optional(Type4.String({ description: "Text to find (exact match, fuzzy fallback)" })),
+  newString: Type4.Optional(Type4.String({ description: "Replacement text (omit to delete match)" })),
+  replaceAll: Type4.Optional(Type4.Boolean({ description: "Replace every occurrence" })),
+  occurrence: Type4.Optional(Type4.Number({ description: "0-indexed occurrence when multiple matches exist" }))
+});
+var GrepParams = Type4.Object({
+  pattern: Type4.String({ description: "Regex pattern to search for" }),
+  path: Type4.Optional(Type4.String({ description: "Path scope (file or directory)" })),
+  include: Type4.Optional(Type4.String({ description: "Glob filter for included files (e.g. '*.ts,*.tsx')" })),
+  caseSensitive: Type4.Optional(Type4.Boolean({ description: "Case-sensitive matching" })),
+  contextLines: Type4.Optional(Type4.Number({ description: "Lines of context before/after each match" }))
+});
+function registerHoistedTools(pi, ctx, surface) {
+  if (surface.hoistRead) {
+    pi.registerTool({
+      name: "read",
+      label: "read",
+      description: "Read file contents with line numbers. Backed by AFT's indexed Rust reader — faster than the built-in `read` on large repos and correctly handles images/PDFs as attachments.",
+      parameters: ReadParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const req = { file: params.path };
+        if (params.offset !== undefined) {
+          req.start_line = params.offset;
+          if (params.limit !== undefined) {
+            req.end_line = params.offset + params.limit - 1;
+          }
+        } else if (params.limit !== undefined) {
+          req.end_line = params.limit;
+        }
+        const response = await callBridge(bridge, "read", req);
+        if (Array.isArray(response.entries)) {
+          return textResult(response.entries.join(`
+`));
+        }
+        const text = response.content ?? "";
+        return textResult(text);
+      }
+    });
+  }
+  if (surface.hoistWrite) {
+    pi.registerTool({
+      name: "write",
+      label: "write",
+      description: "Write a file atomically with per-file backup, optional auto-format, and inline LSP diagnostics. Parent directories are created automatically. Overwrites existing files.",
+      parameters: WriteParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const response = await callBridge(bridge, "write", {
+          file: params.filePath,
+          content: params.content
+        });
+        const diffAdd = response.diff?.additions ?? 0;
+        const diffDel = response.diff?.deletions ?? 0;
+        const diagnostics = response.lsp_diagnostics;
+        let summary = `Wrote ${params.filePath} (+${diffAdd}/-${diffDel})`;
+        if (diagnostics && diagnostics.length > 0) {
+          summary += `
+
+LSP diagnostics:
+${JSON.stringify(diagnostics, null, 2)}`;
+        }
+        return textResult(summary, {
+          filePath: params.filePath,
+          additions: diffAdd,
+          deletions: diffDel,
+          diagnostics
+        });
+      }
+    });
+  }
+  if (surface.hoistEdit) {
+    pi.registerTool({
+      name: "edit",
+      label: "edit",
+      description: "Find-and-replace edit with progressive fuzzy matching (handles whitespace and Unicode drift). Returns an error if multiple matches are found — use `occurrence` to select one, or `replaceAll: true` to replace all. Always returns inline LSP diagnostics for the edited file.",
+      parameters: EditParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const req = {
+          file: params.filePath,
+          match: params.oldString ?? "",
+          replacement: params.newString ?? ""
+        };
+        if (params.replaceAll === true)
+          req.replace_all = true;
+        if (params.occurrence !== undefined)
+          req.occurrence = params.occurrence;
+        const response = await callBridge(bridge, "edit_match", req);
+        const diff = response.diff;
+        const diffAdd = diff?.additions ?? 0;
+        const diffDel = diff?.deletions ?? 0;
+        const replacements = response.replacements;
+        const diagnostics = response.lsp_diagnostics;
+        let summary = `Edited ${params.filePath} (+${diffAdd}/-${diffDel}, ${replacements ?? 1} replacement${replacements === 1 ? "" : "s"})`;
+        if (diagnostics && diagnostics.length > 0) {
+          summary += `
+
+LSP diagnostics:
+${JSON.stringify(diagnostics, null, 2)}`;
+        }
+        return textResult(summary, {
+          filePath: params.filePath,
+          additions: diffAdd,
+          deletions: diffDel,
+          replacements,
+          diagnostics
+        });
+      }
+    });
+  }
+  if (surface.hoistGrep) {
+    pi.registerTool({
+      name: "grep",
+      label: "grep",
+      description: "Search for a regex pattern across files. Uses AFT's trigram index inside the project root for fast repeated queries, and falls back to ripgrep for paths outside the project root.",
+      parameters: GrepParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const req = { pattern: params.pattern };
+        if (params.path)
+          req.path = await resolvePathArg(extCtx.cwd, params.path);
+        if (params.include)
+          req.include = splitIncludeGlobs(params.include);
+        if (params.caseSensitive !== undefined)
+          req.case_sensitive = params.caseSensitive;
+        if (params.contextLines !== undefined)
+          req.context_lines = params.contextLines;
+        const response = await callBridge(bridge, "grep", req);
+        const text = response.text ?? "";
+        return textResult(text);
+      }
+    });
+  }
+}
+async function resolvePathArg(cwd, path2) {
+  const abs = resolve(cwd, path2);
+  try {
+    await stat(abs);
+    return abs;
+  } catch {
+    return path2;
+  }
+}
+function splitIncludeGlobs(include) {
+  return include.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+// src/tools/imports.ts
+import { StringEnum as StringEnum2 } from "@mariozechner/pi-ai";
+import { Type as Type5 } from "@sinclair/typebox";
+var ImportParams = Type5.Object({
+  op: StringEnum2(["add", "remove", "organize"], { description: "Import operation" }),
+  filePath: Type5.String({ description: "Path to the file" }),
+  module: Type5.Optional(Type5.String({ description: "Module path (required for add/remove), e.g. 'react', './utils'" })),
+  names: Type5.Optional(Type5.Array(Type5.String(), { description: "Named imports to add, e.g. ['useState']" })),
+  defaultImport: Type5.Optional(Type5.String({ description: "Default import name (e.g. 'React')" })),
+  removeName: Type5.Optional(Type5.String({ description: "Named import to remove; omit to remove entire import" })),
+  typeOnly: Type5.Optional(Type5.Boolean({ description: "Type-only import (TS only)" })),
+  dryRun: Type5.Optional(Type5.Boolean({ description: "Preview without writing" })),
+  validate: Type5.Optional(StringEnum2(["syntax", "full"], {
+    description: "Post-edit validation level (default: syntax)"
+  }))
+});
+function registerImportTools(pi, ctx) {
+  pi.registerTool({
+    name: "aft_import",
+    label: "import",
+    description: "Language-aware import management. Supports TS, JS, TSX, Python, Rust, Go. Ops: `add` (auto-groups stdlib/external/internal, deduplicates), `remove` (pass `removeName` for single name or omit to remove entire import), `organize` (re-sort + deduplicate).",
+    parameters: ImportParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      if ((params.op === "add" || params.op === "remove") && !params.module) {
+        throw new Error(`op='${params.op}' requires 'module'`);
+      }
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const commandMap = {
+        add: "add_import",
+        remove: "remove_import",
+        organize: "organize_imports"
+      };
+      const req = { file: params.filePath };
+      if (params.module !== undefined)
+        req.module = params.module;
+      if (params.names !== undefined)
+        req.names = params.names;
+      if (params.defaultImport !== undefined)
+        req.default_import = params.defaultImport;
+      if (params.removeName !== undefined)
+        req.name = params.removeName;
+      if (params.typeOnly !== undefined)
+        req.type_only = params.typeOnly;
+      if (params.dryRun !== undefined)
+        req.dry_run = params.dryRun;
+      if (params.validate !== undefined)
+        req.validate = params.validate;
+      const response = await callBridge(bridge, commandMap[params.op], req);
+      return textResult(JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/lsp.ts
+import { StringEnum as StringEnum3 } from "@mariozechner/pi-ai";
+import { Type as Type6 } from "@sinclair/typebox";
+var LspDiagnosticsParams = Type6.Object({
+  filePath: Type6.Optional(Type6.String({ description: "File to get diagnostics for (mutually exclusive with directory)" })),
+  directory: Type6.Optional(Type6.String({
+    description: "Directory to get diagnostics for (mutually exclusive with filePath)"
+  })),
+  severity: Type6.Optional(StringEnum3(["error", "warning", "information", "hint", "all"], {
+    description: "Filter by severity (default: all)"
+  })),
+  waitMs: Type6.Optional(Type6.Number({
+    description: "Wait N ms for fresh diagnostics (max 10000, default: 0)"
+  }))
+});
+function registerLspTools(pi, ctx) {
+  pi.registerTool({
+    name: "lsp_diagnostics",
+    label: "lsp diagnostics",
+    description: "Get errors, warnings, hints from a language server. Provide `filePath` for a single file, `directory` for all files under a path, or omit both for all tracked files.",
+    parameters: LspDiagnosticsParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const hasFile = typeof params.filePath === "string" && params.filePath.length > 0;
+      const hasDir = typeof params.directory === "string" && params.directory.length > 0;
+      if (hasFile && hasDir) {
+        throw new Error("'filePath' and 'directory' are mutually exclusive — provide one or neither");
+      }
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const req = {};
+      if (hasFile)
+        req.file = params.filePath;
+      if (hasDir)
+        req.directory = params.directory;
+      if (params.severity !== undefined)
+        req.severity = params.severity;
+      if (params.waitMs !== undefined)
+        req.wait_ms = params.waitMs;
+      const response = await callBridge(bridge, "lsp_diagnostics", req);
+      return textResult(JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/navigate.ts
+import { StringEnum as StringEnum4 } from "@mariozechner/pi-ai";
+import { Type as Type7 } from "@sinclair/typebox";
+var NavigateParams = Type7.Object({
+  op: StringEnum4(["call_tree", "callers", "trace_to", "impact", "trace_data"], {
+    description: "Navigation operation"
+  }),
+  filePath: Type7.String({ description: "Source file containing the symbol" }),
+  symbol: Type7.String({ description: "Name of the symbol to analyze" }),
+  depth: Type7.Optional(Type7.Number({ description: "Max traversal depth" })),
+  expression: Type7.Optional(Type7.String({ description: "Expression to track (required for trace_data)" }))
+});
+function registerNavigateTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_navigate",
+    label: "navigate",
+    description: "Navigate code structure across files using call graph analysis. All ops require both `filePath` and `symbol`. Use `call_tree` for what a function calls, `callers` for call sites, `trace_to` for entry points, `impact` for blast radius, `trace_data` to follow a value.",
+    parameters: NavigateParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      if (params.op === "trace_data" && !params.expression) {
+        throw new Error("op='trace_data' requires an `expression`");
+      }
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const req = {
+        op: params.op,
+        file: params.filePath,
+        symbol: params.symbol
+      };
+      if (params.depth !== undefined)
+        req.depth = params.depth;
+      if (params.expression !== undefined)
+        req.expression = params.expression;
+      const response = await callBridge(bridge, params.op, req);
+      return textResult(JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/reading.ts
+import { stat as stat2 } from "node:fs/promises";
+import { resolve as resolve2 } from "node:path";
+import { Type as Type8 } from "@sinclair/typebox";
+
+// src/shared/discover-files.ts
+import { readdir } from "node:fs/promises";
+import { extname, join as join7 } from "node:path";
+var OUTLINE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".rs",
+  ".go",
+  ".py",
+  ".rb",
+  ".c",
+  ".cpp",
+  ".h",
+  ".hpp",
+  ".cs",
+  ".java",
+  ".kt",
+  ".scala",
+  ".swift",
+  ".lua",
+  ".ex",
+  ".exs",
+  ".hs",
+  ".sol",
+  ".nix",
+  ".md",
+  ".mdx",
+  ".css",
+  ".html",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".sh",
+  ".bash",
+  ".zsh"
+]);
+var SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  "target",
+  "__pycache__",
+  ".venv",
+  "venv",
+  "vendor",
+  ".turbo",
+  "coverage",
+  ".nyc_output",
+  ".cache"
+]);
+async function discoverSourceFiles(dir, maxFiles = 200) {
+  const files = [];
+  async function walk(current) {
+    if (files.length >= maxFiles)
+      return;
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (files.length >= maxFiles)
+        return;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+          await walk(join7(current, entry.name));
+        }
+      } else if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase();
+        if (OUTLINE_EXTENSIONS.has(ext)) {
+          files.push(join7(current, entry.name));
+        }
+      }
+    }
+  }
+  await walk(dir);
+  files.sort();
+  return files;
+}
+
+// src/tools/reading.ts
+var OutlineParams = Type8.Object({
+  filePath: Type8.Optional(Type8.String({
+    description: "Path to a single file to outline. Directories are auto-detected."
+  })),
+  files: Type8.Optional(Type8.Array(Type8.String(), { description: "Array of file paths to outline in one call" })),
+  directory: Type8.Optional(Type8.String({ description: "Directory to outline recursively (200 file cap)" }))
+});
+var ZoomParams = Type8.Object({
+  filePath: Type8.String({ description: "Path to file (absolute or project-relative)" }),
+  symbol: Type8.Optional(Type8.String({ description: "Symbol name (function/class/type) or Markdown heading" })),
+  symbols: Type8.Optional(Type8.Array(Type8.String(), { description: "Multiple symbols — returns array of matches" })),
+  contextLines: Type8.Optional(Type8.Number({ description: "Lines of context before/after (default: 3)" }))
+});
+function registerReadingTools(pi, ctx, surface) {
+  if (surface.outline) {
+    pi.registerTool({
+      name: "aft_outline",
+      label: "outline",
+      description: "Structural outline of source code or Markdown. For code, returns symbols (functions, classes, types) with line ranges. For Markdown/HTML, returns heading hierarchy. Use this to explore structure before reading specific sections with aft_zoom.\n\nProvide exactly ONE of: `filePath`, `files`, or `directory`.",
+      parameters: OutlineParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        const hasFilePath = typeof params.filePath === "string" && params.filePath.length > 0;
+        const hasFiles = Array.isArray(params.files) && params.files.length > 0;
+        const hasDirectory = typeof params.directory === "string" && params.directory.length > 0;
+        const provided = [hasFilePath, hasFiles, hasDirectory].filter(Boolean).length;
+        if (provided === 0) {
+          throw new Error("Provide exactly one of 'filePath', 'files', or 'directory'");
+        }
+        if (provided > 1) {
+          throw new Error("Provide exactly ONE of 'filePath', 'files', or 'directory' — not multiple");
+        }
+        let dirArg = hasDirectory ? params.directory : undefined;
+        if (!dirArg && hasFilePath) {
+          try {
+            const resolved = resolve2(extCtx.cwd, params.filePath);
+            const st = await stat2(resolved);
+            if (st.isDirectory())
+              dirArg = params.filePath;
+          } catch {}
+        }
+        if (dirArg) {
+          const dirPath = resolve2(extCtx.cwd, dirArg);
+          const files = await discoverSourceFiles(dirPath);
+          if (files.length === 0) {
+            return textResult(`No source files found under ${dirArg}`);
+          }
+          const response2 = await callBridge(bridge, "outline", { files });
+          return textResult(response2.text ?? "");
+        }
+        if (hasFiles) {
+          const response2 = await callBridge(bridge, "outline", { files: params.files });
+          return textResult(response2.text ?? "");
+        }
+        const response = await callBridge(bridge, "outline", { file: params.filePath });
+        return textResult(response.text ?? "");
+      }
+    });
+  }
+  if (surface.zoom) {
+    pi.registerTool({
+      name: "aft_zoom",
+      label: "zoom",
+      description: "Inspect a code symbol or Markdown/HTML section. For code, returns the full source of the symbol with call-graph annotations (calls/called-by). Pass `symbols` for batched lookups.",
+      parameters: ZoomParams,
+      async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+        const bridge = bridgeFor(ctx, extCtx.cwd);
+        if (Array.isArray(params.symbols) && params.symbols.length > 0) {
+          const results = await Promise.all(params.symbols.map((sym) => {
+            const req2 = { file: params.filePath, symbol: sym };
+            if (params.contextLines !== undefined)
+              req2.context_lines = params.contextLines;
+            return bridge.send("zoom", req2);
+          }));
+          return textResult(JSON.stringify(results, null, 2));
+        }
+        const req = { file: params.filePath };
+        if (params.symbol)
+          req.symbol = params.symbol;
+        if (params.contextLines !== undefined)
+          req.context_lines = params.contextLines;
+        const response = await callBridge(bridge, "zoom", req);
+        return textResult(JSON.stringify(response, null, 2));
+      }
+    });
+  }
+}
+
+// src/tools/refactor.ts
+import { StringEnum as StringEnum5 } from "@mariozechner/pi-ai";
+import { Type as Type9 } from "@sinclair/typebox";
+var RefactorParams = Type9.Object({
+  op: StringEnum5(["move", "extract", "inline"], { description: "Refactoring operation" }),
+  filePath: Type9.String({ description: "Source file" }),
+  symbol: Type9.Optional(Type9.String({ description: "Symbol name (for move, inline)" })),
+  destination: Type9.Optional(Type9.String({ description: "Target file (for move)" })),
+  scope: Type9.Optional(Type9.String({ description: "Disambiguation scope for move op" })),
+  name: Type9.Optional(Type9.String({ description: "New function name (for extract)" })),
+  startLine: Type9.Optional(Type9.Number({ description: "1-based start line (for extract)" })),
+  endLine: Type9.Optional(Type9.Number({ description: "1-based end line, inclusive (for extract)" })),
+  callSiteLine: Type9.Optional(Type9.Number({ description: "1-based call site line (for inline)" })),
+  dryRun: Type9.Optional(Type9.Boolean({ description: "Preview as diff" }))
+});
+function registerRefactorTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_refactor",
+    label: "refactor",
+    description: "Workspace-wide refactoring that updates imports and references across files. `move` relocates a top-level symbol (only top-level exports); `extract` pulls a line range into a new function; `inline` replaces a call site with the function body.",
+    parameters: RefactorParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const commandMap = {
+        move: "move_symbol",
+        extract: "extract_function",
+        inline: "inline_symbol"
+      };
+      const req = { file: params.filePath };
+      if (params.symbol !== undefined)
+        req.symbol = params.symbol;
+      if (params.destination !== undefined)
+        req.destination = params.destination;
+      if (params.scope !== undefined)
+        req.scope = params.scope;
+      if (params.name !== undefined)
+        req.name = params.name;
+      if (params.startLine !== undefined)
+        req.start_line = params.startLine;
+      if (params.endLine !== undefined) {
+        req.end_line = params.op === "extract" ? params.endLine + 1 : params.endLine;
+      }
+      if (params.callSiteLine !== undefined)
+        req.call_site_line = params.callSiteLine;
+      if (params.dryRun !== undefined)
+        req.dry_run = params.dryRun;
+      const response = await callBridge(bridge, commandMap[params.op], req);
+      return textResult(JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/safety.ts
+import { StringEnum as StringEnum6 } from "@mariozechner/pi-ai";
+import { Type as Type10 } from "@sinclair/typebox";
+var SafetyParams = Type10.Object({
+  op: StringEnum6(["undo", "history", "checkpoint", "restore", "list"], {
+    description: "Safety operation"
+  }),
+  filePath: Type10.Optional(Type10.String({ description: "File path (required for undo, history)" })),
+  name: Type10.Optional(Type10.String({ description: "Checkpoint name (required for checkpoint, restore)" })),
+  files: Type10.Optional(Type10.Array(Type10.String(), {
+    description: "Specific files for checkpoint (optional, defaults to all tracked)"
+  }))
+});
+function registerSafetyTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_safety",
+    label: "safety",
+    description: "File safety and recovery operations. Ops: `undo` (pop latest snapshot for a file — irreversible), `history` (list snapshots for a file), `checkpoint` (save named snapshot), `restore` (restore named checkpoint), `list` (list checkpoints). Per-file undo stack is capped at 20.",
+    parameters: SafetyParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      if ((params.op === "undo" || params.op === "history") && !params.filePath) {
+        throw new Error(`op='${params.op}' requires 'filePath'`);
+      }
+      if ((params.op === "checkpoint" || params.op === "restore") && !params.name) {
+        throw new Error(`op='${params.op}' requires 'name'`);
+      }
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const commandMap = {
+        undo: "undo",
+        history: "edit_history",
+        checkpoint: "checkpoint",
+        restore: "restore_checkpoint",
+        list: "list_checkpoints"
+      };
+      const req = {};
+      if (params.filePath)
+        req.file = params.filePath;
+      if (params.name)
+        req.name = params.name;
+      if (params.files)
+        req.files = params.files;
+      const response = await callBridge(bridge, commandMap[params.op], req);
+      return textResult(JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/semantic.ts
+import { Type as Type11 } from "@sinclair/typebox";
+var SearchParams2 = Type11.Object({
+  query: Type11.String({ description: "Natural-language description of the code to find" }),
+  topK: Type11.Optional(Type11.Number({ description: "Maximum number of results (default: 10, max: 100)" }))
+});
+function registerSemanticTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_search",
+    label: "semantic search",
+    description: "Search code by meaning using semantic similarity. Use when you don't know the exact name or text — describe what you're looking for in natural language and get the most relevant symbols, functions, and types.",
+    parameters: SearchParams2,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const req = { query: params.query };
+      if (params.topK !== undefined)
+        req.top_k = params.topK;
+      const response = await callBridge(bridge, "semantic_search", req);
+      return textResult(response.text ?? JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/tools/structure.ts
+import { StringEnum as StringEnum7 } from "@mariozechner/pi-ai";
+import { Type as Type12 } from "@sinclair/typebox";
+var TransformParams = Type12.Object({
+  op: StringEnum7(["add_member", "add_derive", "wrap_try_catch", "add_decorator", "add_struct_tags"], { description: "Transformation operation" }),
+  filePath: Type12.String({ description: "Path to the source file" }),
+  container: Type12.Optional(Type12.String({ description: "Class/struct/impl name for add_member" })),
+  code: Type12.Optional(Type12.String({ description: "Member code to insert (add_member)" })),
+  target: Type12.Optional(Type12.String({ description: "Target symbol name" })),
+  derives: Type12.Optional(Type12.Array(Type12.String(), { description: "Derive macro names (add_derive)" })),
+  catchBody: Type12.Optional(Type12.String({ description: "Catch block body (wrap_try_catch, default: 'throw error;')" })),
+  decorator: Type12.Optional(Type12.String({ description: "Decorator text without @ (add_decorator)" })),
+  field: Type12.Optional(Type12.String({ description: "Struct field name (add_struct_tags)" })),
+  tag: Type12.Optional(Type12.String({ description: "Tag key (add_struct_tags)" })),
+  value: Type12.Optional(Type12.String({ description: "Tag value (add_struct_tags)" })),
+  position: Type12.Optional(Type12.String({
+    description: "Position hint: 'first', 'last' (default), 'before:name', 'after:name' for add_member"
+  })),
+  dryRun: Type12.Optional(Type12.Boolean({ description: "Preview without modifying" })),
+  validate: Type12.Optional(StringEnum7(["syntax", "full"], {
+    description: "Validation level (default: syntax)"
+  }))
+});
+function registerStructureTool(pi, ctx) {
+  pi.registerTool({
+    name: "aft_transform",
+    label: "transform",
+    description: "Scope-aware structural code transformations with correct indentation. See parameter descriptions for per-op requirements.",
+    parameters: TransformParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      const bridge = bridgeFor(ctx, extCtx.cwd);
+      const req = { file: params.filePath };
+      if (params.container !== undefined)
+        req.scope = params.container;
+      if (params.code !== undefined)
+        req.code = params.code;
+      if (params.target !== undefined)
+        req.target = params.target;
+      if (params.derives !== undefined)
+        req.derives = params.derives;
+      if (params.catchBody !== undefined)
+        req.catch_body = params.catchBody;
+      if (params.decorator !== undefined)
+        req.decorator = params.decorator;
+      if (params.field !== undefined)
+        req.field = params.field;
+      if (params.tag !== undefined)
+        req.tag = params.tag;
+      if (params.value !== undefined)
+        req.value = params.value;
+      if (params.position !== undefined)
+        req.position = params.position;
+      if (params.dryRun !== undefined)
+        req.dry_run = params.dryRun;
+      if (params.validate !== undefined)
+        req.validate = params.validate;
+      const response = await callBridge(bridge, params.op, req);
+      return textResult(JSON.stringify(response, null, 2));
+    }
+  });
+}
+
+// src/index.ts
+var PLUGIN_VERSION = (() => {
+  try {
+    const req = createRequire3(import.meta.url);
+    return req("../package.json").version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+function resolveStorageDir() {
+  return join8(homedir5(), ".pi", "agent", "aft");
+}
+function resolveToolSurface(config) {
+  const surface = config.tool_surface ?? "recommended";
+  const disabled = new Set(config.disabled_tools ?? []);
+  const ok = (name) => !disabled.has(name);
+  if (surface === "minimal") {
+    return {
+      hoistRead: false,
+      hoistWrite: false,
+      hoistEdit: false,
+      hoistGrep: false,
+      outline: ok("aft_outline"),
+      zoom: ok("aft_zoom"),
+      semantic: false,
+      navigate: false,
+      conflicts: false,
+      importTool: false,
+      safety: ok("aft_safety"),
+      delete: false,
+      move: false,
+      astSearch: false,
+      astReplace: false,
+      lspDiagnostics: false,
+      structure: false,
+      refactor: false
+    };
+  }
+  const base = {
+    hoistRead: ok("read"),
+    hoistWrite: ok("write"),
+    hoistEdit: ok("edit"),
+    hoistGrep: ok("grep") && config.experimental_search_index === true,
+    outline: ok("aft_outline"),
+    zoom: ok("aft_zoom"),
+    semantic: ok("aft_search") && config.experimental_semantic_search === true,
+    navigate: false,
+    conflicts: ok("aft_conflicts"),
+    importTool: ok("aft_import"),
+    safety: ok("aft_safety"),
+    delete: false,
+    move: false,
+    astSearch: ok("ast_grep_search"),
+    astReplace: ok("ast_grep_replace"),
+    lspDiagnostics: ok("lsp_diagnostics"),
+    structure: false,
+    refactor: false
+  };
+  if (surface === "all") {
+    return {
+      ...base,
+      navigate: ok("aft_navigate"),
+      delete: ok("aft_delete"),
+      move: ok("aft_move"),
+      structure: ok("aft_transform"),
+      refactor: ok("aft_refactor")
+    };
+  }
+  return base;
+}
+async function src_default(pi) {
+  log(`AFT extension loading (plugin v${PLUGIN_VERSION})`);
+  let binaryPath;
+  try {
+    binaryPath = await findBinary();
+  } catch (err) {
+    warn(`Failed to resolve AFT binary: ${err instanceof Error ? err.message : String(err)}. ` + "Tools will not be registered.");
+    return;
+  }
+  const config = loadAftConfig(process.cwd());
+  const storageDir = resolveStorageDir();
+  let ortDylibDir = null;
+  if (config.experimental_semantic_search) {
+    try {
+      ortDylibDir = await ensureOnnxRuntime(storageDir);
+      if (!ortDylibDir) {
+        warn(`ONNX Runtime unavailable. Semantic search will be disabled. Install manually: ${getManualInstallHint()}`);
+      }
+    } catch (err) {
+      warn(`Failed to prepare ONNX Runtime: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const configOverrides = {
+    ...config,
+    storage_dir: storageDir
+  };
+  if (ortDylibDir) {
+    configOverrides._ort_dylib_dir = ortDylibDir;
+  }
+  const pool = new BridgePool(binaryPath, { minVersion: PLUGIN_VERSION }, configOverrides);
+  const ctx = { pool, config, storageDir };
+  const surface = resolveToolSurface(config);
+  registerHoistedTools(pi, ctx, surface);
+  if (surface.outline || surface.zoom) {
+    registerReadingTools(pi, ctx, surface);
+  }
+  if (surface.semantic) {
+    registerSemanticTool(pi, ctx);
+  }
+  if (surface.navigate) {
+    registerNavigateTool(pi, ctx);
+  }
+  if (surface.conflicts) {
+    registerConflictsTool(pi, ctx);
+  }
+  if (surface.importTool) {
+    registerImportTools(pi, ctx);
+  }
+  if (surface.safety) {
+    registerSafetyTool(pi, ctx);
+  }
+  if (surface.astSearch || surface.astReplace) {
+    registerAstTools(pi, ctx, surface);
+  }
+  if (surface.delete || surface.move) {
+    registerFsTools(pi, ctx, surface);
+  }
+  if (surface.lspDiagnostics) {
+    registerLspTools(pi, ctx);
+  }
+  if (surface.structure) {
+    registerStructureTool(pi, ctx);
+  }
+  if (surface.refactor) {
+    registerRefactorTool(pi, ctx);
+  }
+  registerStatusCommand(pi, ctx);
+  pi.on("session_shutdown", async () => {
+    try {
+      await pool.shutdown();
+      log("Bridge pool shut down");
+    } catch (err) {
+      warn(`Error during bridge shutdown: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  });
+  registerShutdownCleanup(async () => {
+    try {
+      await pool.shutdown();
+    } catch (err) {
+      warn(`Error during process shutdown: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  });
+  log(`AFT extension ready (surface=${config.tool_surface ?? "recommended"})`);
+}
+export {
+  src_default as default
+};