@kurrent/kcap 0.11.13 → 0.11.15

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/README.md

@@ -79,7 +79,8 @@ Each hook pipes its JSON payload through the `kcap` CLI, which enriches it with
 - `validate-plan` / `kcap-validate-plan` — Verify that all planned items were completed
 - `disable` / `kcap-disable` — Stop recording and delete all server data for the current session
 - `hide` / `kcap-hide` — Hide the current session (owner-only visibility)
-- `review-flows` / `kcap-review-flows` — Run structured, iterative spec/code review loops
+- `review-flows` / `kcap-review-flows` — Run structured, iterative spec/code review loops; the reviewer vendor is chosen independently of the driver (pass a lowercase token like `claude`/`codex`/`cursor`)
+- `agent-flows` / `kcap-agent-flows` — Run structured multi-participant agent flows (catalog `definition_id` or an inline `definition_yaml`), each participant declaring its own vendor/model
 - `guided-tour` / `kcap-guided-tour` — Onboarding tour: what Capacitor has recorded for your team, then per-use-case tutorials (evals, session recall, PR review, analytics)
 
 In Claude they're invoked as `/kcap:recap`, `/kcap:errors`, `/kcap:guided-tour`, etc.

package/kcap/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 5
           }
         ]
@@ -26,7 +26,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 15
           }
         ]
@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 5,
             "async": true
           }
@@ -49,7 +49,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 5,
             "async": true
           }
@@ -61,7 +61,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 5
           }
         ]
@@ -72,7 +72,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 5
           }
         ]
@@ -83,7 +83,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "kcap hook --claude",
+            "command": "kcap hook --claude --no-update-check",
             "timeout": 36000
           }
         ]

package/kcap/skills/agent-flows/SKILL.md

@@ -20,6 +20,10 @@ description: >-
 
 Use the `kcap mcp flows` MCP tools (`start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
 
+## Long rounds are normal
+
+`round_timeout` is an **inactivity** bound, not a wall-clock cap: a round only fails for taking too long if the participant goes genuinely quiet for that whole stretch — an actively-working participant can legitimately run a round for a long time. If a status check (or `start_flow`/`send_to_participant`) returns the benign "Flow still running" text, that is an expected outcome on a long round, not a problem — re-enter the wait with `get_flow_status(flow_run_id, wait: true)`, which blocks (via bounded, internally-retried checks — never a raw long-poll) until the round finishes or roughly 8 minutes pass, then call it again if it's still running. A round result of **`unclear` now genuinely means the participant went dead or silent** (no activity for the whole inactivity bound, or it crashed/was stopped) — it is no longer a symptom of a merely slow participant; see the `participant_unreachable` and `participant_died`/`participant_stopped` guardrail entries below.
+
 ## Role-surface safety gate
 
 Classify the session before any flow action. Flow-starting tools without a reviewer result contract
@@ -68,7 +72,7 @@ explicitly ask you to proceed with whatever vendor the definition or saved prefe
 Canonical reviewer aliases for reserved review flows: Claude / Claude Code → `claude`; Codex /
 OpenAI Codex → `codex`; Cursor / cursor-agent → `cursor`; GitHub Copilot / Copilot CLI → `copilot`;
 Gemini / Gemini CLI → `gemini`; Kiro / Kiro CLI → `kiro`; Pi → `pi`; OpenCode → `opencode`;
-Antigravity / agy → `agy`. Normalize only names bound to the reviewer role, honor negation and
+Antigravity / agy → `antigravity`. Normalize only names bound to the reviewer role, honor negation and
 positive contrast, and ask rather than guessing when two reviewer candidates remain.
 
 For the reserved `spec-review`/`code-review` aliases only, `start_flow` also accepts a top-level
@@ -153,11 +157,11 @@ The server enforces per-run budgets; watch for these in tool error responses:
 
 - **`400` containing `max_rounds (N) reached for this run — close the flow.`** — the run is still **open**, it's just hit its round cap. Stop submitting further rounds, summarize what you have, and call `close_flow`.
 - **`400` containing `budget_exceeded: …`** — the run has **already failed** and all participant agents have stopped. Report this to the user; do NOT retry and do NOT call `close_flow` — closing a failed run overwrites the failure status in the read model (the projector flips `failed` → `closed`), hiding what went wrong.
-- **A round that exceeds the definition's `round_timeout`** lands as a terminal **`unclear`** round, with the timeout explained in its result text — if you check round status programmatically, look for `unclear` and read the text for the timeout reason. The run itself stays open — you may submit another round to that role or close the flow.
+- **A round whose participant goes inactive for the definition's `round_timeout`** (an inactivity bound, not a wall-clock cap — an actively-working participant can run well past it) lands as a terminal **`unclear`** round, with the reason explained in its result text — if you check round status programmatically, look for `unclear` and read the text. This means the participant genuinely went dead or silent, not merely slow. The run itself stays open — you may submit another round to that role (it relaunches automatically, see the `participant_died`/`participant_stopped` entry below) or close the flow.
 - **Idle runs are auto-reaped** after the definition's `idle_ttl` (server default 24h). Don't rely on this — always call `close_flow` yourself once you're done, whether the outcome was clean or you're abandoning the task.
 - **`400` starting `no_daemon_available:`** — no connected daemon has the repo checked out. Relay the server's remediation verbatim, then act on the part you can: run `kcap daemon start -d` on a machine with the repo cloned (add `--name <new-name>` if the account already runs a daemon elsewhere), or get the repo cloned on a machine that already runs one. **You cannot redirect the flow at another daemon or checkout** — these tools expose no daemon or repo-path parameter. If the server's text suggests passing `daemon_name` / `repo_path`, ignore that part: do not invent those arguments, and do not retry unchanged.
 - **`400` starting `daemon_outdated:`** — the daemon's kcap is too old to host flow participants. Relay the server error's remediation verbatim — it names the outdated daemon; the fix: update kcap (`npm i -g @kurrent/kcap`), then `kcap daemon restart --name <its-name>` (works for detached and service-managed daemons alike — a raw `daemon stop` deliberately refuses a service-managed one; `kcap daemon status` lists names, and `--when-idle` defers the restart if the daemon is busy).
-- **`400` containing `participant_unreachable`** — that role's agent is in an ambiguous liveness state (its daemon disconnected or is restarting), so the server won't guess whether it's still alive rather than risk a duplicate launch. Retry the send shortly, or ask the user to stop the participant (dashboard/API) and then re-send to force a fresh relaunch.
+- **`409` containing `participant_unreachable`** — that role's agent is in an ambiguous liveness state (its daemon disconnected or is restarting) or a possibly-live prior agent was spotted and the server is refusing to relaunch until its absence is proven, so it won't guess whether it's still alive rather than risk a duplicate launch. This is retryable — do not close the flow. Retry the send shortly; the server relaunches automatically once absence is proven, or ask the user to stop the participant (dashboard/API) and then re-send to force a fresh relaunch.
 - **Reserved-alias reviewer-model errors** (only when you passed `model`): `reviewer_model_protocol_required` — the server/daemon doesn't support a model override yet; drop `model` and retry, or tell the user to update. `reviewer_model_unavailable` — no resolver for that vendor recognizes the model; ask for a different one or drop the override. `model_vendor_mismatch` — the model belongs to a different vendor than the one selected; ask the user which vendor they meant. `reviewer_model_safe_settlement_required` — the server can't safely reapply this model on a heal/relaunch; close the flow and start a new one. `reviewer_model_unpriceable` — the model has no resolvable pricing to budget-check; ask for a differently-named/priced model.
 - **A round result of `unclear` whose text is exactly `participant_died` or `participant_stopped`** — that role's agent crashed or was stopped mid-round. The run stays **open**: address the same role again with `send_to_participant` and it relaunches automatically — the fresh agent has **no memory of prior rounds**, so restate any context it needs in your message; its earlier spend still counts against the run budget. No need to close and restart the flow. Other roles are unaffected and remain addressable in the meantime.
 
@@ -212,7 +216,7 @@ report completion to user
 |---|---|---|---|
 | `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
 | `send_to_participant` | `flow_run_id`, `participant` (role name declared in the flow definition's `participants` map; single-participant definitions use `reviewer` — an unknown role is rejected, naming the valid ones), `message` | `instructions`, `async` (defaults to `true`) | After addressing a non-clean result for that role, or to launch a role for the first time. Pass the same `flow_run_id`, the role's name, and the updated message. |
-| `get_flow_status` | `flow_run_id` | — | Poll or check the current status of a flow run (running, waiting, completed, failed). |
+| `get_flow_status` | `flow_run_id` | `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 8 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow run (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself. |
 | `close_flow` | `flow_run_id` | — | Only after the definition's clean signal — or when abandoning the task early; the run otherwise stays open until closed. |
 
 ## Example (custom definition)

package/kcap/skills/review-flows/SKILL.md

@@ -17,6 +17,10 @@ Use the `kcap mcp flows` MCP tools (`start_review_flow`, `submit_review_round`,
 
 These four tools are aliases of the generic flow tools (`start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) — see the `agent-flows` skill for non-review flows.
 
+## Long rounds are normal
+
+`round_timeout` is an **inactivity** bound, not a wall-clock cap: a round only fails for taking too long if the reviewer goes genuinely quiet for that whole stretch — an actively-working reviewer can legitimately run a round for a long time. If a status check (or a `submit_review_round`/`start_review_flow` call) returns the benign "Flow still running" text, that is an expected outcome on a long round, not a problem — re-enter the wait with `get_review_flow_status(flow_run_id, wait: true)`, which blocks (via bounded, internally-retried checks — never a raw long-poll) until the round finishes or roughly 8 minutes pass, then call it again if it's still running. A round result of **`unclear` now genuinely means the reviewer went dead or silent** (no activity for the whole inactivity bound, or it crashed/was stopped) — it is no longer a symptom of a merely slow reviewer, so treat it as a liveness problem (see the `participant_unreachable` and `participant_died`/`participant_stopped` entries below), not as "the review is taking a while."
+
 ## Role-surface safety gate
 
 Classify the session before any flow action:
@@ -56,7 +60,7 @@ candidates remain after negation, ask the user to choose; never guess.
 
 Canonical reviewer aliases: Claude / Claude Code → `claude`; Codex / OpenAI Codex → `codex`;
 Cursor / cursor-agent → `cursor`; GitHub Copilot / Copilot CLI → `copilot`; Gemini / Gemini CLI →
-`gemini`; Kiro / Kiro CLI → `kiro`; Pi → `pi`; OpenCode → `opencode`; Antigravity / agy → `agy`.
+`gemini`; Kiro / Kiro CLI → `kiro`; Pi → `pi`; OpenCode → `opencode`; Antigravity / agy → `antigravity`.
 Normalize only the reviewer-role mention. Positive contrast (for example, “from Codex, ask Claude”)
 selects Claude; negated names are removed; two remaining reviewer candidates are ambiguous.
 
@@ -143,8 +147,8 @@ After applying the role-surface safety gate, if `start_review_flow` / `submit_re
 - **`reviewer_vendor_unresolvable`** — returned from `submit_review_round` on a legacy in-flight run whose pinned definition lost its vendor and has no recorded assignment; close the flow and start a new one.
 - **`client_upgrade_required`, `flow_client_protocol_required`, or `flow_client_protocol_unsupported`** — update kcap; reserved review aliases fail closed on stale clients.
 - **`reserved_review_alias_shape`** — an admin changed a reserved alias to an invalid participant shape; restore exactly one participant named `reviewer`.
-- **`400` starting `participant_unavailable:`** — the reviewer agent died and automatic relaunch is not available yet. Close this flow and start a new one, carrying your context forward; re-submitting will keep failing.
-- **A round result of `unclear` whose text is exactly `participant_died` or `participant_stopped`** — the reviewer agent crashed or was stopped mid-round. The run stays open but has no live reviewer: close the flow and start a new one.
+- **`409` containing `participant_unreachable`** — the reviewer's liveness is ambiguous right now: either its daemon disconnected/is restarting, or the server positively spotted a possibly-live prior agent and is refusing to relaunch until its absence is proven (never launching a duplicate reviewer beside a possibly-live one). This is retryable — **do not close the flow.** Submit the round again shortly with `submit_review_round`; the server relaunches the reviewer automatically once absence is proven (via the daemon reconnecting/reporting, or the agent's death being confirmed). If it keeps failing across many retries, that points at the daemon itself needing attention, not at the flow needing to be restarted — ask the user to check daemon status, or stop the reviewer (dashboard/API) to force a fresh relaunch.
+- **A round result of `unclear` whose text is exactly `participant_died` or `participant_stopped`** — the reviewer crashed or was stopped mid-round. The run stays open: submit another round with `submit_review_round` and it relaunches automatically — the fresh reviewer has **no memory of prior rounds**, so restate any context it needs in your updated context; its earlier spend still counts against the run budget. No need to close and restart the flow.
 
 ## Workflow
 
@@ -171,7 +175,7 @@ if findings:
 |---|---|---|---|
 | `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (explicit reviewer model override — REQUIRES `vendor`; only pass it when the user named a model), `instructions`, `mode` (`context-only` — optional) | Once, at the start of a review task. |
 | `submit_review_round` | `flow_run_id`, `context` | `instructions` | After addressing findings. Pass the same `flow_run_id` and the updated context. |
-| `get_review_flow_status` | `flow_run_id` | — | Poll or check the current status of a flow (running, waiting, completed, failed). |
+| `get_review_flow_status` | `flow_run_id` | `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 8 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself. |
 | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `clean`. |
 
 ## Example (code review)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,17 +14,17 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "0.11.13",
-    "@kurrent/kcap-linux-arm64": "0.11.13",
-    "@kurrent/kcap-linux-musl-arm64": "0.11.13",
-    "@kurrent/kcap-linux-musl-x64": "0.11.13",
-    "@kurrent/kcap-linux-x64": "0.11.13",
-    "@kurrent/kcap-win-x64": "0.11.13"
+    "@kurrent/kcap-darwin-arm64": "0.11.15",
+    "@kurrent/kcap-linux-arm64": "0.11.15",
+    "@kurrent/kcap-linux-musl-arm64": "0.11.15",
+    "@kurrent/kcap-linux-musl-x64": "0.11.15",
+    "@kurrent/kcap-linux-x64": "0.11.15",
+    "@kurrent/kcap-win-x64": "0.11.15"
   },
   "files": [
     "bin/",
     "kcap/"
   ],
-  "kcapReleaseCommit": "c0875f27a85c1bd6c3ad6594cf593338ad18f9be",
-  "kcapReleaseTag": "v0.11.13"
+  "kcapReleaseCommit": "b3a8a54f8b91c49e0d284caddcd44704c9e687fd",
+  "kcapReleaseTag": "v0.11.15"
 }