tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/tui/compiled.ts

@@ -0,0 +1,121 @@
+/**
+ * Resolution for the TUI surfaces across BOTH distribution modes.
+ *
+ * Dev checkout: the surfaces are OpenTUI/Solid `.tsx` spawned by `bun` (the
+ * bunfig preload supplies the JSX transform). Installed via npm/pnpm/bun: there
+ * is no checkout and no `bun`, so we fall back to the compiled `tmux-ide-tui`
+ * binary (see scripts/build-tui.mjs) which bundles every surface behind a
+ * `<surface> [flags]` argv dispatcher and needs no runtime.
+ *
+ * Order is "checkout first, binary second": a dev machine that happens to have
+ * built the binary still uses its live `.tsx` sources. The binary is consulted
+ * only when the checkout sources or `bun` are missing. {@link findCompiledTui}
+ * probes the shipped/local compiled binary first, then a per-platform binary
+ * downloaded at runtime into `~/.tmux-ide/bin/` (see lib/tui-binary.ts).
+ *
+ * {@link resolveTuiLaunch} is a PURE decision (unit-tested); {@link findCompiledTui}
+ * and {@link isBunAvailable} are the thin io probes that feed it.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { findDownloadedTui } from "../lib/tui-binary.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export type TuiLaunch =
+  | { mode: "bun"; bin: "bun"; argv: string[] }
+  | { mode: "binary"; bin: string; argv: string[] }
+  | { mode: "unavailable"; reasons: string[] };
+
+export interface TuiResolveInput {
+  /** Dispatcher surface token: team | explorer | changes | preview | config | setup | sidebar. */
+  surface: string;
+  /** The checkout `.tsx` entry for this surface. */
+  scriptPath: string;
+  /** Surface flags (`--session=…`, `--dir=…`, `--theme=…`, …). */
+  args: string[];
+  /** Whether {@link scriptPath} exists (checkout present). */
+  checkoutExists: boolean;
+  /** Whether the `bun` runtime is on PATH. */
+  bunAvailable: boolean;
+  /** Absolute path to the compiled `tmux-ide-tui`, or null if not found. */
+  compiledBinary: string | null;
+}
+
+/**
+ * PURE — decide how to launch a surface. Bun-from-checkout wins when both are
+ * present (dev); the compiled binary is the installed fallback; otherwise the
+ * caller surfaces an actionable message built from `reasons`.
+ */
+export function resolveTuiLaunch(input: TuiResolveInput): TuiLaunch {
+  if (input.checkoutExists && input.bunAvailable) {
+    return { mode: "bun", bin: "bun", argv: [input.scriptPath, ...input.args] };
+  }
+  if (input.compiledBinary) {
+    return { mode: "binary", bin: input.compiledBinary, argv: [input.surface, ...input.args] };
+  }
+  const reasons: string[] = [];
+  if (!input.checkoutExists) {
+    reasons.push(
+      "the TUI widget sources are absent (reinstall tmux-ide — releases since v2.6.1 ship them)",
+    );
+  }
+  if (!input.bunAvailable) {
+    reasons.push("the `bun` runtime is not installed (https://bun.sh)");
+  }
+  reasons.push(
+    "no compiled `tmux-ide-tui` binary was found (build one with `pnpm build:tui`, download it with `tmux-ide update --tui-binary`, or reinstall a release that ships it)",
+  );
+  return { mode: "unavailable", reasons };
+}
+
+// Candidate locations for the compiled binary, relative to an anchor dir. The
+// installed tarball ships it at packages/daemon/dist/tui/tmux-ide-tui and the
+// bin is bin/cli.js, so a bin-anchored `../packages/daemon/dist/...` hits it;
+// the other rels cover unbundled daemon layouts and a co-located binary.
+const BINARY_RELS = [
+  "../packages/daemon/dist/tui/tmux-ide-tui",
+  "../../dist/tui/tmux-ide-tui",
+  "../dist/tui/tmux-ide-tui",
+  "dist/tui/tmux-ide-tui",
+  "tmux-ide-tui",
+];
+
+/**
+ * io — locate the compiled `tmux-ide-tui`. Honors `TMUX_IDE_TUI_BIN` (absolute
+ * override, e.g. for tests / custom installs), then probes bin- and
+ * module-relative candidates. Returns null when none exists.
+ */
+export function findCompiledTui(): string | null {
+  const override = process.env.TMUX_IDE_TUI_BIN;
+  if (override) return existsSync(override) ? override : null;
+
+  const anchors: string[] = [];
+  if (process.argv[1]) anchors.push(dirname(process.argv[1]));
+  anchors.push(__dirname);
+
+  for (const anchor of anchors) {
+    for (const rel of BINARY_RELS) {
+      const candidate = resolve(anchor, rel);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  // Last: a per-platform binary fetched at runtime by `tmux-ide update
+  // --tui-binary` into `~/.tmux-ide/bin/` — the fallback for an npm install with
+  // no bun and no shipped compiled binary. Version-stamped, so it only matches
+  // the running version (see lib/tui-binary.ts).
+  return findDownloadedTui();
+}
+
+/** io — is the `bun` runtime callable? */
+export function isBunAvailable(): boolean {
+  try {
+    execFileSync("bun", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/packages/daemon/src/tui/detect/classify.ts

@@ -0,0 +1,208 @@
+/**
+ * The 4-state agent classifier.
+ *
+ * Turns snapshot + manifest evidence into a final per-pane status. The
+ * instantaneous half (`classifyInstant`) is pure: it maps a single snapshot
+ * through a manifest to blocked/working/idle/unknown. The `done` state,
+ * however, is inherently cross-tick — an agent is "done" only when it WAS
+ * working and has since gone quiet without being viewed. That temporal logic
+ * lives in the small stateful `StatusTracker`, which layers `done` + seen
+ * acknowledgement on top of the instantaneous state.
+ */
+import type { AgentManifest } from "./manifest.ts";
+import { evaluateManifest, pickManifest } from "./manifest.ts";
+import { BUNDLED_MANIFESTS } from "./manifests.ts";
+import type { PaneSnapshot } from "./snapshot.ts";
+
+/** The final per-pane status surfaced to the TUI. */
+export type AgentStatus = "blocked" | "working" | "done" | "idle" | "unknown";
+
+/** The instantaneous status derivable from a single snapshot (no history). */
+export type InstantState = "blocked" | "working" | "idle" | "unknown";
+
+/**
+ * Working/blocked reports older than this are considered stale — the agent
+ * (or its hook) probably died mid-turn, so we fall back to screen scraping.
+ * Done/idle are terminal until the next event and never go stale.
+ */
+const AUTHORITY_STALE_SECONDS = 600;
+
+const AUTHORITY_STATES = new Set(["working", "blocked", "done", "idle"]);
+
+/**
+ * Parse an authoritative `@agent_state` pane option (`"<state>:<epoch>"`,
+ * written by lifecycle-hook integrations or any self-reporting agent).
+ * PURE — returns the reported status, or null when the value is absent,
+ * malformed, or stale (working/blocked past {@link AUTHORITY_STALE_SECONDS}).
+ * A fresh authority report OUTRANKS screen-manifest scraping.
+ */
+export function parseAuthority(raw: string | undefined, nowSec: number): AgentStatus | null {
+  if (!raw) return null;
+  const sep = raw.lastIndexOf(":");
+  if (sep === -1) return null;
+  const state = raw.slice(0, sep);
+  const epoch = Number(raw.slice(sep + 1));
+  if (!AUTHORITY_STATES.has(state) || !Number.isFinite(epoch)) return null;
+  if ((state === "working" || state === "blocked") && nowSec - epoch > AUTHORITY_STALE_SECONDS) {
+    return null;
+  }
+  return state as AgentStatus;
+}
+
+/**
+ * Extract the epoch STAMP from an `@agent_state` value (`"<state>:<epoch>"`) —
+ * the "since" timestamp of the reported state. PURE — returns the epoch, or
+ * null when the value is absent or its stamp isn't a finite number. Staleness
+ * is NOT considered here (that's {@link parseAuthority}'s job); callers pair
+ * this with a fresh `parseAuthority` result to surface a state's `since`.
+ */
+export function parseAuthorityEpoch(raw: string | undefined): number | null {
+  if (!raw) return null;
+  const sep = raw.lastIndexOf(":");
+  if (sep === -1) return null;
+  const epoch = Number(raw.slice(sep + 1));
+  return Number.isFinite(epoch) ? epoch : null;
+}
+
+/**
+ * Classify a single snapshot against a manifest — PURE, never throws.
+ *
+ * - no manifest → `"unknown"` (we can't reason about an unrecognized command)
+ * - manifest reports `blocked` → `"blocked"`
+ * - manifest reports `working` → `"working"`
+ * - manifest reports `done` or nothing → `"idle"`
+ *
+ * A manifest-detected `done` is deliberately collapsed to `idle` here; the
+ * real, cross-tick `done` is produced by {@link StatusTracker}.
+ */
+export function classifyInstant(
+  snapshot: PaneSnapshot & { title?: string },
+  manifest: AgentManifest | undefined,
+): InstantState {
+  if (!manifest) return "unknown";
+
+  const { state } = evaluateManifest(snapshot, manifest);
+  switch (state) {
+    case "blocked":
+      return "blocked";
+    case "working":
+      return "working";
+    // "done" (instantaneous) and null both fall through to idle.
+    default:
+      return "idle";
+  }
+}
+
+/**
+ * Convenience wrapper: pick the manifest for a pane command, then classify.
+ * Returns `"unknown"` when no manifest applies to the command.
+ */
+export function classifyPaneCommand(
+  snapshot: PaneSnapshot & { title?: string },
+  command: string,
+  manifests: AgentManifest[] = BUNDLED_MANIFESTS,
+): InstantState {
+  return classifyInstant(snapshot, pickManifest(command, manifests));
+}
+
+/** Per-pane bookkeeping the tracker keeps between ticks. */
+interface PaneState {
+  /** Whether the previous tick observed `working`. */
+  wasWorking: boolean;
+  /** A working→idle transition happened and hasn't been acknowledged. */
+  doneUnseen: boolean;
+}
+
+/**
+ * Stateful layer that adds `done` + seen-acknowledgement on top of the
+ * instantaneous state. Deterministic given its call sequence.
+ */
+export interface StatusTracker {
+  /**
+   * Fold a fresh instantaneous state into the pane's history and return the
+   * final status. `opts.seen` marks the pane as currently viewed/attached,
+   * which acknowledges (and suppresses) a pending `done`.
+   */
+  update(paneId: string, instant: InstantState, opts?: { seen?: boolean }): AgentStatus;
+  /** Acknowledge a pane — clears any pending `done`. */
+  markSeen(paneId: string): void;
+  /** Drop a pane's state entirely (e.g. its session closed). */
+  forget(paneId: string): void;
+}
+
+/**
+ * Create a {@link StatusTracker}.
+ *
+ * State transitions (given the previous tick's bookkeeping):
+ * - `working` → clear `doneUnseen`, remember working → `"working"`.
+ * - `blocked` → clear `doneUnseen` (blocked outranks a pending done) →
+ *   `"blocked"`.
+ * - `idle`:
+ *   - a working→idle transition sets `doneUnseen`.
+ *   - `doneUnseen` && not seen → `"done"`.
+ *   - otherwise → `"idle"`.
+ * - `unknown` → `"unknown"` (leaves `doneUnseen` untouched).
+ *
+ * `opts.seen === true` always clears `doneUnseen`, and downgrades a would-be
+ * `done` to `"idle"` — seeing a finished pane acknowledges it.
+ */
+export function createStatusTracker(): StatusTracker {
+  const states = new Map<string, PaneState>();
+
+  function get(paneId: string): PaneState {
+    let s = states.get(paneId);
+    if (!s) {
+      s = { wasWorking: false, doneUnseen: false };
+      states.set(paneId, s);
+    }
+    return s;
+  }
+
+  return {
+    update(paneId, instant, opts) {
+      const seen = opts?.seen === true;
+      const s = get(paneId);
+
+      switch (instant) {
+        case "working":
+          s.doneUnseen = false;
+          s.wasWorking = true;
+          return "working";
+
+        case "blocked":
+          s.doneUnseen = false;
+          s.wasWorking = false;
+          return "blocked";
+
+        case "idle": {
+          // A working→idle transition means the agent just finished.
+          if (s.wasWorking) s.doneUnseen = true;
+          s.wasWorking = false;
+
+          // Viewing the pane acknowledges any pending done.
+          if (seen) {
+            s.doneUnseen = false;
+            return "idle";
+          }
+          return s.doneUnseen ? "done" : "idle";
+        }
+
+        case "unknown":
+        default:
+          // Leave doneUnseen untouched; unknown is not a transition signal.
+          s.wasWorking = false;
+          if (seen) s.doneUnseen = false;
+          return "unknown";
+      }
+    },
+
+    markSeen(paneId) {
+      const s = states.get(paneId);
+      if (s) s.doneUnseen = false;
+    },
+
+    forget(paneId) {
+      states.delete(paneId);
+    },
+  };
+}

package/packages/daemon/src/tui/detect/manifest-loader.ts

@@ -0,0 +1,193 @@
+/**
+ * Manifest loading with user overrides.
+ *
+ * The bundled manifests (`manifests.ts`) cover the agents we ship tuning for.
+ * Users can add or replace tuning WITHOUT a code change by dropping JSON files
+ * in `~/.tmux-ide/agent-detection/` — one {@link AgentManifest} per file:
+ *
+ *   ~/.tmux-ide/agent-detection/my-agent.json
+ *   {
+ *     "id": "my-agent",
+ *     "commands": ["my-agent", "my-agent-cli"],
+ *     "states": {
+ *       "working": { "any": [{ "contains": "esc to interrupt", "caseInsensitive": true }] },
+ *       "blocked": { "any": [{ "contains": "(y/n)", "caseInsensitive": true }] }
+ *     }
+ *   }
+ *
+ * An override whose `id` matches a bundled manifest REPLACES it (so you can
+ * re-tune claude/codex); a new `id` is APPENDED. Invalid files are skipped with
+ * a one-time stderr warning — a typo in one override never breaks detection.
+ *
+ * Related: a per-pane `@agent_hint` tmux option (e.g.
+ * `tmux set-option -p @agent_hint claude`) forces a specific manifest for a
+ * pane, bypassing process-tree resolution — see `resolveAgentCommand`. That is
+ * the escape hatch for sandboxes/wrappers where the process tree is opaque.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { AgentManifest, Rule, StateRules } from "./manifest.ts";
+import { BUNDLED_MANIFESTS } from "./manifests.ts";
+
+/** Directory scanned for user override manifests. */
+export function overrideDir(): string {
+  return join(homedir(), ".tmux-ide", "agent-detection");
+}
+
+/**
+ * Light structural validator — enough to reject a malformed override without a
+ * full schema. Requires a non-empty `id`, a non-empty `commands: string[]`, and
+ * a `states` object whose present state rules are shaped `{ all?: [], any?: [] }`
+ * with matcher-like entries. PURE — never throws.
+ */
+export function validateManifestShape(value: unknown): value is AgentManifest {
+  if (typeof value !== "object" || value === null) return false;
+  const m = value as Record<string, unknown>;
+
+  if (typeof m.id !== "string" || m.id.trim().length === 0) return false;
+
+  if (!Array.isArray(m.commands) || m.commands.length === 0) return false;
+  if (!m.commands.every((c) => typeof c === "string" && c.length > 0)) return false;
+
+  if (typeof m.states !== "object" || m.states === null) return false;
+  const states = m.states as Record<string, unknown>;
+  for (const key of ["blocked", "working", "done"] as const) {
+    if (!(key in states)) continue;
+    if (!isRuleShape(states[key])) return false;
+  }
+  return true;
+}
+
+/** A rule is `{ all?: Matcher[]; any?: Matcher[] }` with matcher-shaped entries. */
+function isRuleShape(value: unknown): value is Rule {
+  if (typeof value !== "object" || value === null) return false;
+  const r = value as Record<string, unknown>;
+  for (const key of ["all", "any"] as const) {
+    if (!(key in r)) continue;
+    const arr = r[key];
+    if (!Array.isArray(arr) || !arr.every(isMatcherShape)) return false;
+  }
+  return true;
+}
+
+/** A matcher must carry a string `contains` or `regex` (the two probe forms). */
+function isMatcherShape(value: unknown): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const m = value as Record<string, unknown>;
+  return typeof m.contains === "string" || typeof m.regex === "string";
+}
+
+/**
+ * Merge bundled manifests with user overrides. PURE.
+ *
+ * - An override whose `id` matches a bundled manifest REPLACES that entry
+ *   in-place (position preserved, so pickManifest/tree priority is stable).
+ * - A later override with a not-yet-seen `id` is APPENDED (in encounter order).
+ * - Among overrides sharing an `id`, the LAST one wins.
+ */
+export function mergeManifests(
+  bundled: AgentManifest[],
+  overrides: AgentManifest[],
+): AgentManifest[] {
+  const byId = new Map<string, AgentManifest>();
+  for (const o of overrides) byId.set(o.id, o);
+
+  const result: AgentManifest[] = [];
+  const consumed = new Set<string>();
+
+  for (const b of bundled) {
+    const override = byId.get(b.id);
+    if (override) {
+      result.push(override);
+      consumed.add(b.id);
+    } else {
+      result.push(b);
+    }
+  }
+  // Append new ids in the order first encountered — but use the last-wins entry
+  // from `byId`, so a duplicate id still resolves to the final override.
+  for (const o of overrides) {
+    if (!consumed.has(o.id)) {
+      result.push(byId.get(o.id)!);
+      consumed.add(o.id);
+    }
+  }
+  return result;
+}
+
+/** Paths we have already warned about, so a bad override warns only once. */
+const warned = new Set<string>();
+
+/**
+ * Read and validate override manifests from `dir`. Thin io wrapper — a missing
+ * directory yields `[]`, and each invalid/malformed file is skipped with a
+ * one-time stderr warning. Never throws.
+ */
+export function readOverrideManifests(dir = overrideDir()): AgentManifest[] {
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    // Missing directory (the common case) → no overrides.
+    return [];
+  }
+
+  const overrides: AgentManifest[] = [];
+  for (const file of files.sort()) {
+    const path = join(dir, file);
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+      if (validateManifestShape(parsed)) {
+        overrides.push(normalizeStates(parsed));
+      } else {
+        warnOnce(path, "not a valid AgentManifest (need id, commands[], states)");
+      }
+    } catch (err) {
+      warnOnce(path, err instanceof Error ? err.message : String(err));
+    }
+  }
+  return overrides;
+}
+
+/** Drop unknown state keys — keep only blocked/working/done. */
+function normalizeStates(m: AgentManifest): AgentManifest {
+  const states: StateRules = {};
+  if (m.states.blocked) states.blocked = m.states.blocked;
+  if (m.states.working) states.working = m.states.working;
+  if (m.states.done) states.done = m.states.done;
+  const confidence = m.confidence === "tuned" ? "tuned" : "conservative";
+  return { id: m.id, commands: m.commands, states, confidence };
+}
+
+function warnOnce(path: string, reason: string): void {
+  if (warned.has(path)) return;
+  warned.add(path);
+  process.stderr.write(`tmux-ide: skipping agent-detection override ${path}: ${reason}\n`);
+}
+
+/**
+ * Load the full manifest set: bundled + user overrides, merged. Does io on
+ * every call — prefer {@link getManifests} for hot paths.
+ */
+export function loadManifests(): AgentManifest[] {
+  return mergeManifests(BUNDLED_MANIFESTS, readOverrideManifests());
+}
+
+/** Process-lifetime cache for the merged manifest set. */
+let cache: AgentManifest[] | undefined;
+
+/**
+ * Cached {@link loadManifests}. The override directory is read once per
+ * process; call {@link _resetForTests} to force a re-read.
+ */
+export function getManifests(): AgentManifest[] {
+  if (!cache) cache = loadManifests();
+  return cache;
+}
+
+/** Test hook: clear the cache and the one-time-warning ledger. */
+export function _resetForTests(): void {
+  cache = undefined;
+  warned.clear();
+}