herdr-turn-coordinator 0.1.0 → 0.1.2

package/README.md

@@ -2,13 +2,15 @@
 
 Run one interactive coding-agent turn in Herdr without spending parent-model tokens on status polling.
 
-The plugin keeps the downstream agent's native TUI, creates a dedicated visible pane, waits in a local supervisor process, reads the final output once, and leaves the pane open for human takeover.
+Works with every agent kind supported by your installed Herdr version, including Codex, Claude Code, Grok, Gemini CLI, Kimi, Cursor, OpenCode, and GitHub Copilot.
+
+The plugin keeps the downstream agent's native TUI, splits a dedicated pane without taking focus, waits in a local supervisor process, reads the final output once, and leaves the pane open for human takeover.
 
 ## Why
 
 `herdr agent prompt --wait` can report `agent_prompt_stalled` even when a prompt was delivered and the agent continues working. A parent model that recovers by repeatedly calling `agent get`, `agent read`, or `agent wait` pays for every observation as another model turn.
 
-Turn Coordinator moves that recovery loop into an ordinary local process. On a false stall it confirms delivery from a new visible prompt anchor or a recovered working state, then waits for lifecycle settlement. If only a 15-second pane-revision quiet period is available, it returns `unknown` for human takeover instead of guessing that the turn completed. It never resends the same prompt.
+Turn Coordinator moves that wait into a local process. On a false stall it checks for a new prompt on screen or a recovered `working` state, then waits. If it only sees 15 seconds of quiet pane output, it returns `unknown` for human takeover instead of declaring the turn done. It never resends the same prompt.
 
 ## Requirements
 
@@ -17,6 +19,22 @@ Turn Coordinator moves that recovery loop into an ordinary local process. On a f
 - macOS or Linux
 - A Herdr-supported interactive agent CLI
 
+## Supported AI CLIs
+
+`--kind` is passed directly to Herdr. Use the Herdr kind ID, not the product name.
+
+| Product | `--kind` | Product | `--kind` |
+| --- | --- | --- | --- |
+| Codex | `codex` | Claude Code | `claude` |
+| Grok | `grok` | Gemini CLI | `gemini` |
+| Kimi Code CLI | `kimi` | Cursor Agent CLI | `cursor` |
+| OpenCode | `opencode` | GitHub Copilot CLI | `copilot` |
+| Cline | `cline` | Kiro CLI | `kiro` |
+| Qwen Code | `qwen` | Qoder CLI | `qodercli` |
+| Amp | `amp` | Droid | `droid` |
+
+Any other kind accepted by your installed Herdr version also works, including kinds added after this plugin release. Availability and agent detection quality follow Herdr itself. The only extra agent-specific guard is Kimi's first-run folder-trust prompt.
+
 ## Install
 
 Recommended Herdr plugin installation:
@@ -28,26 +46,32 @@ herdr plugin log list --plugin karthuslorin.turn-coordinator --limit 1
 herdr-turn doctor
 ```
 
-Plugin actions are asynchronous. Confirm the install action log says `succeeded` before running `doctor`, and ensure `~/.local/bin` is on `PATH`.
+Plugin actions are asynchronous. Confirm the install action log says `succeeded` before running `doctor`. Plugin install puts `herdr-turn` in `~/.local/bin`, so ensure that directory is on `PATH`.
 
 Alternatively, install the CLI from npm:
 
 ```sh
-npm install --global herdr-turn-coordinator --registry=https://registry.npmjs.org/
+npm install --global herdr-turn-coordinator
 herdr-turn doctor
 ```
 
+Choose one installation method. An npm global install uses the npm prefix bin instead of `~/.local/bin`.
+
 ## Usage
 
-Start a new interactive agent in a dedicated visible pane:
+`herdr-turn run` and `herdr-turn prompt` must run from a pane inside Herdr (`HERDR_ENV=1`). `herdr-turn doctor` can run outside Herdr.
+
+Start a new interactive agent in a dedicated pane:
 
 ```sh
 herdr-turn run \
-  --kind kimi \
+  --kind codex \
   --name reviewer \
   --prompt "Review the current diff and report only actionable findings."
 ```
 
+For Claude Code, Grok, Gemini, or Kimi, use `--kind claude`, `--kind grok`, `--kind gemini`, or `--kind kimi`.
+
 Continue an existing settled agent:
 
 ```sh
@@ -56,7 +80,19 @@ herdr-turn prompt \
   --prompt "Now summarize the top three risks."
 ```
 
-Both commands print one JSON result. The created pane stays open and the agent remains fully interactive.
+Both commands block until the turn settles or the timeout expires, then print one JSON object. The default timeout is 300000 ms. The created pane stays open and the agent remains fully interactive.
+
+```json
+{
+  "ok": true,
+  "pane_id": "w1:p2",
+  "agent_name": "reviewer",
+  "agent_status": "idle",
+  "text": "..."
+}
+```
+
+On `ok: false`, a non-zero exit, or a status other than `idle`/`done`, stop for human takeover instead of polling Herdr from model turns.
 
 ## Suggested agent instruction
 
@@ -68,8 +104,9 @@ then consume its single final JSON result. Do not poll Herdr from model turns.
 
 ## Behavior
 
-- Preserves the native interactive TUI; it never substitutes `kimi -p`, `grok --single`, or another batch mode.
+- Preserves each agent's native interactive TUI by using `herdr agent start`; it never substitutes a batch or non-interactive mode.
 - Rejects prompts to agents reported as `working`, `blocked`, or `unknown`.
+- Leaves Kimi's first-run folder-trust prompt untouched for manual confirmation.
 - Uses Herdr's native blocking wait first.
 - On `agent_prompt_stalled`, falls back only after a revision advance plus a new prompt anchor or a recovered `working` state.
 - Uses native lifecycle waiting once Herdr reports `working`; otherwise a local 15-second revision-quiet heuristic returns `unknown` without declaring success.
@@ -78,7 +115,7 @@ then consume its single final JSON result. Do not poll Herdr from model turns.
 
 ## Local A/B result
 
-One parent-Codex-to-Kimi review task produced the following result on macOS with Herdr 0.8.0:
+One parent-Codex-to-Kimi review task on macOS with Herdr 0.8.0 (`n=1`) produced the following result:
 
 | Metric | Before | With plugin | Change |
 | --- | ---: | ---: | ---: |
@@ -87,17 +124,19 @@ One parent-Codex-to-Kimi review task produced the following result on macOS with
 | Output tokens | 2,950 | 1,638 | -44.5% |
 | Wall time | 108 s | 62 s | -42.6% |
 
-This is a single local comparison, not a universal performance guarantee.
+Before the plugin, the parent recovered a false stall by polling Herdr. With the plugin, it made one blocking call. This is a single local comparison, not a universal performance guarantee, and it does not measure other agent pairings.
 
-## Check
+## Tests
 
 ```sh
 python3 -m unittest -v
 ```
 
+`npm test` runs the same command.
+
 ## Scope
 
-This plugin coordinates interactive Herdr agents. Outside Herdr, use the downstream CLI's normal blocking non-interactive mode. It does not modify Herdr, replace agent TUIs, or require an npm package.
+This plugin coordinates interactive Herdr agents. Outside Herdr, use the downstream CLI's normal blocking non-interactive mode. It does not modify Herdr or replace agent TUIs. Plugin installation does not need npm; the npm package is an alternative way to install the same `herdr-turn` CLI.
 
 ## Uninstall
 
@@ -110,7 +149,7 @@ herdr plugin uninstall karthuslorin.turn-coordinator
 For an npm installation:
 
 ```sh
-npm uninstall --global herdr-turn-coordinator --registry=https://registry.npmjs.org/
+npm uninstall --global herdr-turn-coordinator
 ```
 
 ## License

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "karthuslorin.turn-coordinator"
 name = "Turn Coordinator"
-version = "0.1.0"
+version = "0.1.2"
 min_herdr_version = "0.8.0"
 description = "Run one interactive agent turn without model-driven polling"
 platforms = ["macos", "linux"]

package/herdr_turn.py

@@ -87,6 +87,13 @@ def contains_new_prompt(before, after, prompt):
     return False
 
 
+def requires_manual_setup(text):
+    text = " ".join(text.lower().split())
+    return "trust this folder?" in text and (
+        "don't trust" in text or "enable project mcp servers" in text
+    )
+
+
 def wait_for_quiet(target, pane_id, delivered_revision, timeout):
     deadline = time.monotonic() + max(0, timeout - 5000) / 1000
     revision = delivered_revision
@@ -120,6 +127,10 @@ def wait_for_quiet(target, pane_id, delivered_revision, timeout):
 
 def submit(target, prompt, timeout, lines, baseline_revision):
     before = call("agent", "read", target, "--source", "visible")
+    if before.returncode:
+        fail("agent_preflight_read_failed", detail=payload(before))
+    if requires_manual_setup(before.stdout):
+        fail("agent_requires_manual_setup", target=target)
     result = call("agent", "prompt", target, prompt, "--wait", "--timeout", str(timeout))
     if result.returncode:
         state = call("agent", "get", target)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-turn-coordinator",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Preserve interactive Herdr agent TUIs without model-driven status polling",
   "license": "MIT",
   "author": "KarthusLorin",