transitions-refine 0.3.10 → 0.3.11

package/.agents/skills/refine-live/SKILL.md

@@ -1,11 +1,23 @@
 ---
 name: refine-live
-description: Become the live "Refine" agent for the Timeline Inspector. Use when the user runs `/refine live`, asks to "refine live", "go live", "answer refine jobs", or wants the timeline panel's Refine button (LLM mode), Accept button, or grouped scan to be backed by a real agent. Long-polls the local refine relay, reasons about each CSS transition with the transitions-dev skill, posts suggestions back to the browser panel, for "scan" jobs groups the page's transitions into components with open/close phases by reading the source, and for "apply" jobs writes the accepted timing changes into the user's source code.
+description: In-chat fallback for the Timeline Inspector Refine agent. Use when the user runs `/refine live`, asks to "refine live", "go live", or answer refine jobs — but ONLY when no persistent agent is wired (no `npx transitions-refine live`). Prefer `npx transitions-refine live` for run-and-forget (relay spawns agent per click, no idle credit burn). This skill long-polls the relay, posts suggestions, handles scan/apply jobs.
 ---
 
 # Refine Live
 
-Turn yourself into the LLM behind the Timeline Inspector's **Refine** button. While
+## Two modes
+
+**Persistent (recommended — run and forget)**  
+Run `npx transitions-refine live` from your project. The CLI starts the relay and wires `REFINE_AGENT_CMD` so the relay spawns your agent CLI **per Refine click**. No chat loop; idle = zero credit burn. Works hours later as long as the relay process keeps running. Stop with Ctrl-C (or `npx transitions-refine stop`).
+
+**In-chat loop (fallback — this skill)**  
+Run `/refine live` in Cursor/Claude/Codex when the relay is up but has **no** `REFINE_AGENT_CMD`. **You** become the poller via `GET /jobs/next`. The Agent tab stays available only while you keep polling — **each idle poll cycle consumes chat turns/credits**. Say "stop refine" to exit.
+
+Use the in-chat loop only when you cannot wire a persistent agent CLI.
+
+---
+
+Turn yourself into the LLM behind the Timeline Inspector's **Refine** button (**in-chat fallback mode**). While
 this loop runs, the panel's **LLM** tab is "available": each click sends one
 transition here, you reason about it, and your suggestions appear in the panel.
 
@@ -19,15 +31,28 @@ Browser (Refine, LLM tab) ──POST /jobs──► relay ──GET /jobs/next
                           ◄──GET /jobs/:id── relay ◄──POST /jobs/:id/result── YOU
 ```
 
-## The loop — stay live for the whole session
-
-**Keep polling continuously until the user explicitly stops you.** This is the
-only thing that keeps the panel's LLM tab "available", so do not give up on idle.
-A long stretch of `204` responses is *normal and expected* — it just means no one
-has clicked Refine yet. Re-poll immediately every time; never treat repeated
-`204`s as a reason to stop. The relay reports the agent as "available" for ~120s
-after your last poll, so as long as you keep looping you stay live and the user
-never has to re-run `/refine live`.
+## The loop — stay live, but don't burn credits forever
+
+Keep polling so the panel's LLM tab stays "available", but this loop costs chat
+turns/credits even while idle, so it is **not** truly run-and-forget — it has
+three exits, in priority order:
+
+1. **Relay stop signal (authoritative).** `GET /jobs/next` may return `200` with
+   `{"stop": true}`. The relay sends this when the user clicks **Stop** in the
+   panel, or automatically after ~10 min with no jobs. **Always honor it: stop
+   looping immediately**, tell the user the LLM tab will go unavailable and how to
+   resume (`/refine live`), and end your turn. Never re-poll after a stop signal.
+2. **The user says so** — "stop refine", "exit live", etc.
+3. **Your own idle backoff (safety net).** A long stretch of `204`s is normal —
+   it just means no one has clicked Refine yet — but to avoid spending credits on
+   a forgotten loop, **back off as idle grows** instead of hammering immediately:
+   re-poll right away for the first few empty cycles, then pause ~5s between polls,
+   and after ~10 min of unbroken idle stop on your own (same as the relay's
+   auto-stop) and tell the user how to resume. Any real job resets the backoff.
+
+The relay reports the agent as "available" for ~120s after your last poll, so
+short pauses keep you live. A successful job always resets idle, so an active
+session never backs off.
 
 1. **Claim the next job (long-poll).** This call blocks up to ~25s, then returns.
 
@@ -35,8 +60,12 @@ never has to re-run `/refine live`.
    curl -s http://localhost:7331/jobs/next
    ```
 
-   - HTTP `204` / empty body → no work yet. Immediately call it again.
-   - HTTP `200` with JSON → a job. Shape:
+   - HTTP `204` / empty body → no work yet. Poll again, applying the idle
+     backoff above (immediate at first, then ~5s pauses, then stop after ~10 min).
+   - HTTP `200` with `{"stop": true}` → **the loop must end.** Stop polling, tell
+     the user the LLM tab is now unavailable and that `/refine live` resumes it,
+     and end your turn. Do not treat it as a job.
+   - HTTP `200` with a job JSON → work to do. Shape:
 
      ```json
      {
@@ -197,9 +226,10 @@ never has to re-run `/refine live`.
      -H 'Content-Type: application/json' -d '{"message":"…"}'
    ```
 
-5. **Go back to step 1.** Keep looping indefinitely. **Only stop when the user
-   explicitly tells you to** (e.g. "stop refine", "exit live"). Do not stop just
-   because it's been quiet — idle is the normal state between clicks. If you do
+5. **Go back to step 1.** Keep looping, but honor the three exits from
+   [the loop section](#the-loop--stay-live-but-dont-burn-credits-forever): a
+   `{"stop": true}` from the relay, the user telling you to stop, or your own idle
+   backoff/auto-stop after ~10 min quiet. A real job resets idle. Whenever you do
    stop, tell them the LLM tab will go unavailable and how to restart
    (`/refine live`).
 

package/README.md

@@ -29,27 +29,30 @@ npx transitions-refine stop
 
 1. injects one `<script type="module" src=".../inject.js">` into your page (it looks for `index.html`, `public/index.html`, … or pass `--page <path>`),
 2. drops the `refine-live` + `transitions-dev` skills into `.agents/skills/` (so the agent makes token-aware picks),
-3. starts the local relay (which serves the panel at `/inject.js`).
+3. **auto-wires an LLM backend** — it detects the agent hosting this run and points the relay at *its* CLI, so Refine uses the subscription you already have (Cursor → `cursor-agent`, Claude Code → `claude`, Codex → `codex`),
+4. starts the local relay (which serves the panel at `/inject.js`).
 
 Open your app — the panel is now on the page. Press Ctrl-C to stop the relay and remove the injected tag.
 
 ## LLM quality (recommended)
 
-The default answerer snaps each value to the nearest motion token. For *usage-aware* picks (a 300 ms modal close → `Quick` 150 ms, a dropdown open → `Fast` 250 ms), back the panel with an LLM. Two ways:
+The default answerer snaps each value to the nearest motion token. For *usage-aware* picks (a 300 ms modal close → `Quick` 150 ms, a dropdown open → `Fast` 250 ms), back the panel with an LLM.
+
+Plain `npx transitions-refine live` already does this when an agent CLI is available: it prefers the **host agent** so it bills your existing plan, persistently (no `/refine live` loop to keep alive). The CLI must be authenticated once — Cursor: run `cursor-agent` to log in (or set `CURSOR_API_KEY`); Claude Code: run `claude` to sign in; Codex: run `codex` to sign in (or set `CODEX_API_KEY`).
 
 ```bash
-# A) persistent: install/wire the Cursor CLI so the relay answers LLM jobs itself,
-#    per click, with no /refine live loop to keep alive (one-time CLI install)
-npx transitions-refine live --llm
-```
+# auto: use whichever agent hosts this run (cursor-agent / claude / codex)
+npx transitions-refine live
 
-After `--llm`, make sure the CLI is authenticated once: run `cursor-agent` to log in, or set `CURSOR_API_KEY`.
+# force a specific agent regardless of host
+npx transitions-refine live --agent claude   # cursor | claude | codex
 
-```
-# B) in-IDE agent: run this in your editor to become the answerer yourself
-/refine live
+# no agent on the machine? install the Cursor CLI as a fallback
+npx transitions-refine live --llm
 ```
 
+Resolution order: `REFINE_AGENT_CMD` (explicit) → `--agent <name>` → detected host agent → any installed agent → (with `--llm`) install cursor-agent. If none is available the panel falls back to the in-IDE loop — run `/refine live` in your editor to answer jobs yourself (works in Cursor, Claude Code, or Codex; stays live only while that session keeps polling).
+
 You can also point the relay at any one-shot agent CLI via `REFINE_AGENT_CMD` (the relay feeds it the prompt on stdin and reads a JSON result from stdout):
 
 ```bash
@@ -102,6 +105,30 @@ Endpoints: `POST /jobs` (refine, `kind: "apply"`, or `kind: "scan"`), `GET /jobs
 
 Refine suggestions stay as live overrides until you press **Accept**, which is the explicit step that writes them into your source.
 
-## License
-
-MIT
+## Terms & License
+
+> Full terms: https://transitions.dev/terms.html
+
+- **Beta software.** Refine is an early Beta. Features, commands, the panel, and
+  its behavior may change, regress, or be removed at any time without notice. No
+  guarantee of availability, stability, or fitness for any purpose.
+- **Your agent credits.** Refine triggers *your own* AI coding agent (Cursor,
+  Claude Code, Codex, …). Every Refine click and any `npx transitions-refine
+  live` / `/refine live` session consumes *your* provider's tokens/credits —
+  including while a live session sits idle and keeps polling. You are solely
+  responsible for that spend; this project is not liable for and will not
+  reimburse any credits, fees, or overages. Run `npx transitions-refine stop`
+  (or say `stop refine`) when you're done.
+- **The agent changes your code.** Accepting a suggestion writes changes into
+  your source files. Suggestions are AI-generated and may be wrong. Use version
+  control, review every change before committing, and keep backups. Use at your
+  own risk.
+- **No warranty.** The software is provided **"AS IS"**, without warranty of any
+  kind. To the maximum extent permitted by law, the authors are not liable for
+  any damages — direct, indirect, incidental, or consequential, including lost
+  work or lost credits — arising from its use.
+
+### MIT License
+
+MIT — Copyright (c) 2026 Jakub Antalik / Transitions.dev. See
+https://transitions.dev/terms.html for the full license text.

package/bin/cli.mjs

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
 // Refine — transitions.dev live tool.
 //
-//   npx transitions-refine live         # inject the panel + start the relay
-//   npx transitions-refine live --llm   # + install/wire cursor-agent (persistent LLM)
-//   npx transitions-refine stop          # remove the injected <script> tag
+//   npx transitions-refine live              # inject panel + relay; auto-wire your agent CLI
+//   npx transitions-refine live --agent claude   # force an agent: cursor | claude | codex
+//   npx transitions-refine live --llm        # install the Cursor CLI if no agent is found
+//   npx transitions-refine stop              # remove the injected <script> tag
 //
 // `live` sets up the timeline + Refine with no npm install and no source edits
 // of your own:
 //   1. injects one <script type="module" src=".../inject.js"> into your page
 //   2. drops the `refine-live` + `transitions-dev` skills (for token-aware picks)
-//   3. ensures an LLM backend:
-//        --llm  → installs/wires the Cursor CLI (cursor-agent) so the relay
-//                 answers LLM jobs itself, persistently (no /refine live loop).
-//        else   → falls back to /refine live (in-IDE agent) + deterministic.
+//   3. wires an LLM backend so the relay answers jobs itself, persistently (no
+//      /refine live loop). It prefers the agent HOSTING this run — Cursor →
+//      cursor-agent, Claude Code → claude, Codex → codex — so Refine uses the
+//      subscription you already have. Override with --agent <name> or by
+//      exporting REFINE_AGENT_CMD. With no agent available it falls back to the
+//      /refine live in-IDE loop (and --llm can install the Cursor CLI).
 //   4. starts the local refine relay (serves the panel at /inject.js).
 
 import { spawn, spawnSync } from "node:child_process";
@@ -48,6 +51,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === "--page" || a === "-p") args.page = argv[++i];
     else if (a === "--port") args.port = argv[++i];
+    else if (a === "--agent") args.agent = argv[++i];
     else if (a.startsWith("--")) args[a.slice(2)] = true;
     else args._.push(a);
   }
@@ -111,17 +115,68 @@ function dropSkill(name) {
   return existed ? "updated" : true;
 }
 
-// ── agent CLI (for the persistent LLM path) ──────────────────────────────────
-// The relay spawns `REFINE_AGENT_CMD` per job. We point it at cursor-agent so
-// LLM Refine works without a live `/refine live` loop. The binary may not be on
-// the non-interactive PATH, so we probe known install locations and use an
-// absolute path when wiring it up.
-const AGENT_BIN_CANDIDATES = [
-  "cursor-agent",
-  join(HOME, ".local/bin/cursor-agent"),
-  join(HOME, ".cursor/bin/cursor-agent"),
+// ── agent CLIs (for the persistent LLM path) ─────────────────────────────────
+// The relay answers LLM jobs by spawning REFINE_AGENT_CMD per job (stdin =
+// prompt, stdout = JSON). To bill against the account the user ALREADY pays for,
+// we detect which agent is hosting this run and wire ITS CLI: a Claude Code user
+// gets `claude`, a Codex user gets `codex`, a Cursor user gets `cursor-agent`.
+// Detection is by each host's env markers; override with --agent <name> or by
+// exporting REFINE_AGENT_CMD yourself.
+const envHasPrefix = (p) => Object.keys(process.env).some((k) => k.startsWith(p));
+
+const AGENTS = [
+  {
+    key: "cursor",
+    label: "Cursor",
+    // Cursor's agent terminal exports CURSOR_AGENT.
+    host: () => Boolean(process.env.CURSOR_AGENT),
+    bins: [
+      "cursor-agent",
+      join(HOME, ".local/bin/cursor-agent"),
+      join(HOME, ".cursor/bin/cursor-agent"),
+    ],
+    // -p = headless/stdin, --force = auto-allow tool calls. The relay also
+    // auto-appends -p/--trust/--force for cursor-agent; we wire them up front so
+    // the printed command is the real one.
+    cmd: (bin) => `${bin} -p --force`,
+    canInstall: true,
+    auth: "run `cursor-agent` once to log in, or set CURSOR_API_KEY",
+  },
+  {
+    key: "claude",
+    label: "Claude Code",
+    // Claude Code exports CLAUDECODE=1 (+ CLAUDE_CODE_*) in its tools/terminals.
+    host: () => Boolean(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT),
+    bins: [
+      "claude",
+      join(HOME, ".claude/local/claude"),
+      join(HOME, ".local/bin/claude"),
+    ],
+    // -p = headless print (prompt on stdin); skip-permissions so apply jobs can
+    // edit files without an interactive approval prompt.
+    cmd: (bin) => `${bin} -p --dangerously-skip-permissions`,
+    canInstall: false,
+    auth: "run `claude` once to sign in",
+  },
+  {
+    key: "codex",
+    label: "Codex",
+    // Codex exec exports CODEX_SANDBOX (+ CODEX_* friends) in its sandbox.
+    host: () => Boolean(process.env.CODEX_SANDBOX) || envHasPrefix("CODEX_"),
+    bins: ["codex", join(HOME, ".local/bin/codex")],
+    // `codex exec -` reads the prompt on stdin; workspace-write so apply jobs can
+    // edit files; skip-git-repo-check so a non-git project root doesn't error out.
+    cmd: (bin) => `${bin} exec --sandbox workspace-write --skip-git-repo-check -`,
+    canInstall: false,
+    auth: "run `codex` once to sign in, or set CODEX_API_KEY",
+  },
 ];
 
+// Host-detection precedence. Claude/Codex export very specific markers; check
+// them BEFORE Cursor so a Claude Code or Codex session launched from inside a
+// Cursor terminal (which still carries CURSOR_*) is not mis-wired to cursor-agent.
+const HOST_PRECEDENCE = ["claude", "codex", "cursor"];
+
 function isRunnable(bin) {
   try {
     return spawnSync(bin, ["--version"], { stdio: "ignore" }).status === 0;
@@ -130,11 +185,20 @@ function isRunnable(bin) {
   }
 }
 
-function findAgentBin() {
-  return AGENT_BIN_CANDIDATES.find(isRunnable) || null;
+function findBin(agent) {
+  return agent.bins.find(isRunnable) || null;
+}
+
+function detectHostAgent() {
+  for (const key of HOST_PRECEDENCE) {
+    const a = AGENTS.find((x) => x.key === key);
+    if (a && a.host()) return a;
+  }
+  return null;
 }
 
-function installAgentCli() {
+// Install the Cursor CLI (the only agent we can fetch non-interactively).
+function installCursorCli() {
   log("• installing the Cursor CLI (cursor-agent) — one-time…");
   const r =
     process.platform === "win32"
@@ -147,15 +211,53 @@ function installAgentCli() {
           stdio: "inherit",
         });
   if (r.status !== 0) log("! the installer exited non-zero — see its output above.");
-  return findAgentBin();
+  return findBin(AGENTS[0]);
 }
 
-// Returns an absolute-ish command string to put in REFINE_AGENT_CMD, or null.
-function ensureAgentCli({ autoInstall }) {
-  const bin = findAgentBin();
-  if (bin) return bin;
-  if (!autoInstall) return null;
-  return installAgentCli();
+// Decide which agent CLI the relay should spawn. Returns either
+//   { cmd, agent, source }          → wire this command (persistent LLM), or
+//   { cmd:null, agent?, reason }    → couldn't wire; caller prints guidance.
+// Precedence: explicit REFINE_AGENT_CMD → --agent <key> → host agent (same
+// subscription) → any installed agent → (with --llm) install cursor-agent.
+function resolveAgent({ wantLlm, forceKey }) {
+  if (process.env.REFINE_AGENT_CMD) {
+    return { cmd: process.env.REFINE_AGENT_CMD, source: "env" };
+  }
+
+  let target = null;
+  if (forceKey) {
+    target = AGENTS.find((a) => a.key === forceKey) || null;
+    if (!target) {
+      return { cmd: null, reason: `unknown --agent "${forceKey}" (use cursor | claude | codex)` };
+    }
+  }
+  if (!target) target = detectHostAgent();
+
+  if (target) {
+    let bin = findBin(target);
+    if (!bin && target.canInstall && wantLlm) bin = installCursorCli();
+    if (bin) return { cmd: target.cmd(bin), agent: target, source: forceKey ? "forced" : "host" };
+    return {
+      cmd: null,
+      agent: target,
+      reason:
+        `detected ${target.label} but its CLI isn't on PATH` +
+        (target.canInstall ? " — re-run with --llm to install it" : ` — install the ${target.label} CLI first`),
+    };
+  }
+
+  // No host detected (plain terminal): use any installed agent, in list order.
+  for (const a of AGENTS) {
+    const bin = findBin(a);
+    if (bin) return { cmd: a.cmd(bin), agent: a, source: "scan" };
+  }
+
+  // Nothing installed: only cursor-agent can be fetched non-interactively.
+  if (wantLlm) {
+    const bin = installCursorCli();
+    if (bin) return { cmd: AGENTS[0].cmd(bin), agent: AGENTS[0], source: "install" };
+  }
+  return { cmd: null, reason: "no agent CLI found" };
 }
 
 function log(msg) {
@@ -186,26 +288,28 @@ function cmdLive(args) {
     else if (r === "exists") log(`✓ ${name} skill already present (v${PKG_VERSION})`);
   }
 
-  // 2.5) ensure an agent CLI so the relay can answer LLM jobs itself — this is
-  //      the persistent path (no `/refine live` loop to keep alive). Installing
-  //      fetches a system binary, so it only happens with explicit opt-in via
-  //      `--llm`. If REFINE_AGENT_CMD is already set we respect it as-is.
+  // 2.5) wire an agent CLI so the relay can answer LLM jobs itself — the
+  //      persistent path (no `/refine live` loop to keep alive). We prefer the
+  //      agent hosting this run so Refine bills the subscription the user already
+  //      has. REFINE_AGENT_CMD (if set) always wins; --agent forces a choice.
   const wantLlm = Boolean(args.llm);
+  const forceKey = typeof args.agent === "string" ? args.agent : null;
   const env = { ...process.env, REFINE_RELAY_PORT: port };
-  let agentBin = null;
-  if (process.env.REFINE_AGENT_CMD) {
-    log(`✓ using REFINE_AGENT_CMD from environment: ${process.env.REFINE_AGENT_CMD}`);
-  } else {
-    agentBin = ensureAgentCli({ autoInstall: wantLlm });
-    if (agentBin) {
-      // Absolute path: the relay spawns via `sh -c`, whose PATH may not include
-      // the CLI's install dir (e.g. ~/.local/bin). `-p` = headless print mode;
-      // `--force` clears the workspace-trust / tool-approval prompts that would
-      // otherwise hang a non-interactive spawn.
-      const cmd = `${agentBin} -p --force`;
-      env.REFINE_AGENT_CMD = cmd;
-      log(`✓ LLM path wired: relay will spawn  ${cmd}`);
+  const resolved = resolveAgent({ wantLlm, forceKey });
+  if (resolved.cmd) {
+    env.REFINE_AGENT_CMD = resolved.cmd;
+    if (resolved.source === "env") {
+      log(`✓ using REFINE_AGENT_CMD from environment: ${resolved.cmd}`);
+    } else {
+      const via =
+        resolved.source === "host" ? `detected ${resolved.agent.label}`
+        : resolved.source === "forced" ? `forced ${resolved.agent.label}`
+        : resolved.source === "scan" ? `found ${resolved.agent.label}`
+        : `installed ${resolved.agent.label}`;
+      log(`✓ LLM path wired (${via}): relay will spawn  ${resolved.cmd}`);
     }
+  } else if (resolved.reason) {
+    log(`• LLM not wired — ${resolved.reason}.`);
   }
 
   // 3) start the relay (foreground; Ctrl-C stops it + reverts the injection)
@@ -215,6 +319,7 @@ function cmdLive(args) {
   });
 
   const llmWired = Boolean(env.REFINE_AGENT_CMD);
+  const authHint = resolved.agent && resolved.agent.auth;
   log("");
   log("Next:");
   log("  1. Open your app — the timeline panel is now on the page.");
@@ -222,17 +327,12 @@ function cmdLive(args) {
   if (llmWired) {
     log("  3. LLM suggestions are ON — the relay runs the agent CLI per click,");
     log("     so you never have to run /refine live.");
-    log("     One-time: make sure the CLI is authenticated —");
-    log("       run `cursor-agent` once to log in, or set CURSOR_API_KEY.");
-  } else if (wantLlm) {
-    log("  3. LLM was requested but cursor-agent isn't available (install failed).");
-    log("     Install it manually, then re-run:");
-    log("       curl https://cursor.com/install -fsS | bash");
-    log("     …or run /refine live in your editor for the in-IDE-agent path.");
+    if (authHint) log(`     One-time: make sure the CLI is authenticated — ${authHint}.`);
   } else {
-    log("  3. For persistent LLM (no /refine live needed), re-run with --llm");
-    log("     (installs the Cursor CLI once). Or run /refine live in your editor");
-    log("     to use the in-IDE agent.");
+    log("  3. No agent CLI wired, so LLM features need a live answerer. Either:");
+    log("     • run /refine live in your editor (Cursor / Claude Code / Codex), or");
+    log("     • re-run with --llm to install the Cursor CLI, or");
+    log("     • export REFINE_AGENT_CMD='<your agent CLI>' and re-run.");
   }
   log("");
   log("Press Ctrl-C to stop the relay and remove the injected tag.");
@@ -274,12 +374,21 @@ function main() {
   if (cmd === "live") return cmdLive(args);
   if (cmd === "stop") return cmdStop(args);
   log("Refine — transitions.dev live tool");
-  log("  npx transitions-refine live         # inject panel + start relay");
-  log("  npx transitions-refine live --llm   # + install/wire cursor-agent for persistent LLM");
-  log("  npx transitions-refine stop         # remove the injected tag");
+  log("  npx transitions-refine live                 # inject panel + relay; auto-wire your agent CLI");
+  log("  npx transitions-refine live --agent claude  # force an agent: cursor | claude | codex");
+  log("  npx transitions-refine live --llm           # install the Cursor CLI if no agent is found");
+  log("  npx transitions-refine stop                 # remove the injected tag");
   log("");
-  log("Options: --page <html>  --port <n>  --llm (enable persistent LLM via the Cursor CLI)");
+  log("Options: --page <html>  --port <n>  --agent <cursor|claude|codex>  --llm");
+  log("It prefers the agent hosting this run (Cursor/Claude Code/Codex) so Refine uses");
+  log("the subscription you already have. Or set REFINE_AGENT_CMD to wire any CLI.");
   process.exit(cmd ? 1 : 0);
 }
 
-main();
+// Run only when invoked as the CLI entry (npx / node bin/cli.mjs), so tests can
+// import the resolver helpers without triggering a live run.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}
+
+export { AGENTS, HOST_PRECEDENCE, detectHostAgent, resolveAgent, findBin };