tmux-ide 2.6.0 → 2.6.1

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

@@ -0,0 +1,193 @@
+/**
+ * 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;
+}
+
+/**
+ * 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,192 @@
+/**
+ * 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;
+  return { id: m.id, commands: m.commands, states };
+}
+
+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();
+}

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

@@ -0,0 +1,184 @@
+/**
+ * Declarative detection manifests — a pure, data-driven rule engine.
+ *
+ * A manifest describes, per agent command (claude, codex, shell, …), the
+ * textual evidence that indicates a `blocked`/`working`/`done` state. The
+ * evaluator resolves matcher regions from a `PaneSnapshot`, tests them, and
+ * returns the first state (by precedence) whose rule matches. Everything here
+ * is pure and never throws — invalid regexes simply fail to match. The 4-state
+ * classifier layers `idle` + seen-tracking on top of this.
+ */
+import type { PaneSnapshot } from "./snapshot.ts";
+
+/** Which slice of a snapshot a matcher tests against. */
+export type Region = "bottom" | "text" | "title";
+
+/** A single evidence probe. Exactly one of `contains`/`regex` is required. */
+export interface Matcher {
+  /** Region to resolve (default `bottom`). */
+  region?: Region;
+  /** Substring test. */
+  contains?: string;
+  /** Regex source string (compiled safely; invalid → no match). */
+  regex?: string;
+  /** Case-insensitive contains/regex (default false). */
+  caseInsensitive?: boolean;
+}
+
+/** A boolean clause: `all` matchers AND-ed, `any` matchers OR-ed. */
+export interface Rule {
+  /** Every matcher must match. */
+  all?: Matcher[];
+  /** At least one matcher must match. */
+  any?: Matcher[];
+}
+
+/** Per-state rules. `idle` is the fallback and has no rule. */
+export interface StateRules {
+  blocked?: Rule;
+  working?: Rule;
+  done?: Rule;
+}
+
+/** A detection manifest for one or more pane commands. */
+export interface AgentManifest {
+  /** Stable manifest id. */
+  id: string;
+  /** Pane `current_command` names this manifest applies to. */
+  commands: string[];
+  /** Evidence rules per detectable state. */
+  states: StateRules;
+}
+
+/** The states a manifest can positively detect (idle is inferred elsewhere). */
+export type DetectedState = "blocked" | "working" | "done";
+
+/** Snapshot plus the optional pane title used by the `title` region. */
+type SnapshotWithTitle = PaneSnapshot & { title?: string };
+
+/** Precedence order — the first matching state wins. */
+const PRECEDENCE: DetectedState[] = ["blocked", "working", "done"];
+
+/** Resolve the text a matcher tests against, tolerating an absent title. */
+function resolveRegion(snapshot: SnapshotWithTitle, region: Region): string {
+  switch (region) {
+    case "text":
+      return snapshot.text;
+    case "title":
+      return snapshot.title ?? "";
+    case "bottom":
+    default:
+      return snapshot.bottomNonEmpty.join("\n");
+  }
+}
+
+/** Compile a regex safely — returns undefined on invalid source. */
+function safeRegex(source: string, caseInsensitive?: boolean): RegExp | undefined {
+  try {
+    return new RegExp(source, caseInsensitive ? "i" : "");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Test a single matcher against a snapshot. Pure — never throws.
+ * A matcher with neither `contains` nor `regex` never matches.
+ */
+export function matchMatcher(snapshot: SnapshotWithTitle, matcher: Matcher): boolean {
+  const haystack = resolveRegion(snapshot, matcher.region ?? "bottom");
+
+  if (matcher.contains !== undefined) {
+    if (matcher.caseInsensitive) {
+      return haystack.toLowerCase().includes(matcher.contains.toLowerCase());
+    }
+    return haystack.includes(matcher.contains);
+  }
+
+  if (matcher.regex !== undefined) {
+    const re = safeRegex(matcher.regex, matcher.caseInsensitive);
+    return re ? re.test(haystack) : false;
+  }
+
+  return false;
+}
+
+/**
+ * Test a rule: all present `all` matchers must match AND at least one present
+ * `any` matcher must match. An empty or absent rule never matches.
+ */
+export function matchRule(snapshot: SnapshotWithTitle, rule: Rule): boolean {
+  const hasAll = rule.all !== undefined && rule.all.length > 0;
+  const hasAny = rule.any !== undefined && rule.any.length > 0;
+  if (!hasAll && !hasAny) return false;
+
+  if (hasAll && !rule.all!.every((m) => matchMatcher(snapshot, m))) return false;
+  if (hasAny && !rule.any!.some((m) => matchMatcher(snapshot, m))) return false;
+
+  return true;
+}
+
+/**
+ * Evaluate a manifest against a snapshot in precedence order
+ * (blocked → working → done). Returns the first matching state, or
+ * `{ state: null }` when no rule matches. Detection is strict: blocked
+ * requires explicit evidence.
+ */
+export function evaluateManifest(
+  snapshot: SnapshotWithTitle,
+  manifest: AgentManifest,
+): { state: DetectedState | null; matched?: { state: DetectedState; matcher: Matcher } } {
+  for (const state of PRECEDENCE) {
+    const rule = manifest.states[state];
+    if (rule && matchRule(snapshot, rule)) {
+      const matcher = firstMatchingMatcher(snapshot, rule);
+      return matcher ? { state, matched: { state, matcher } } : { state };
+    }
+  }
+  return { state: null };
+}
+
+/** Find the first matcher in a rule that matched, for reporting. */
+function firstMatchingMatcher(snapshot: SnapshotWithTitle, rule: Rule): Matcher | undefined {
+  const matchers = [...(rule.all ?? []), ...(rule.any ?? [])];
+  return matchers.find((m) => matchMatcher(snapshot, m));
+}
+
+/**
+ * Debug helper — evaluate every state and report which matched, alongside the
+ * winning state (by precedence).
+ */
+export function explain(
+  snapshot: SnapshotWithTitle,
+  manifest: AgentManifest,
+): { state: DetectedState | null; checked: Array<{ state: DetectedState; matched: boolean }> } {
+  const checked = PRECEDENCE.map((state) => {
+    const rule = manifest.states[state];
+    return { state, matched: rule ? matchRule(snapshot, rule) : false };
+  });
+  const winner = checked.find((c) => c.matched);
+  return { state: winner ? winner.state : null, checked };
+}
+
+/**
+ * Pick the manifest whose `commands` best match a pane's current command.
+ * Prefers an exact (case-insensitive) match, then a substring match in either
+ * direction. Returns undefined when nothing applies.
+ */
+export function pickManifest(
+  command: string,
+  manifests: AgentManifest[],
+): AgentManifest | undefined {
+  const cmd = command.trim().toLowerCase();
+  if (cmd.length === 0) return undefined;
+
+  const exact = manifests.find((m) => m.commands.some((c) => c.toLowerCase() === cmd));
+  if (exact) return exact;
+
+  return manifests.find((m) =>
+    m.commands.some((c) => {
+      const name = c.toLowerCase();
+      return cmd.includes(name) || name.includes(cmd);
+    }),
+  );
+}