@kurrent/kcap 0.9.0 → 0.9.2

package/bin/kcap.js

@@ -28,73 +28,98 @@ const PLATFORM_PACKAGES = {
   "win32-x64":         "@kurrent/kcap-win-x64",
 };
 
-const musl = process.platform === "linux" && isMusl() ? "-musl" : "";
-const platformKey = `${process.platform}${musl}-${process.arch}`;
-const packageName = PLATFORM_PACKAGES[platformKey];
-
-if (!packageName) {
-  console.error(`Unsupported platform: ${platformKey}`);
-  console.error(`Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`);
-  process.exit(1);
+// Resolves the npm dist-tag to install for `kcap update`, based on the
+// resolved channel reported by `kcap update --check`'s `install_tag` field.
+// Falls back to "latest" when the probe is missing, failed, or has no tag,
+// preserving today's default behavior.
+function resolveInstallSpec(info) {
+  const tag = info && typeof info.install_tag === "string" && info.install_tag
+    ? info.install_tag
+    : "latest";
+  return `@kurrent/kcap@${tag}`;
 }
 
-// Resolve the platform package
-let binaryDir;
-try {
-  binaryDir = path.dirname(require.resolve(`${packageName}/package.json`));
-} catch {
-  console.error(`Platform package ${packageName} is not installed.`);
-  console.error(`Try: npm install -g @kurrent/kcap`);
-  process.exit(1);
+// Builds the arg list for the `kcap update --check` probe, forwarding only
+// the channel-switch flags (`--beta`/`--stable`) from the user's `kcap update`
+// invocation. Nothing else is forwarded — the probe already supplies `--check`
+// and `--no-update-check` itself, so this is a controlled call.
+function probeArgs(updArgs) {
+  const channelFlags = (updArgs || []).filter((a) => a === "--beta" || a === "--stable");
+  return ["update", "--check", "--no-update-check", ...channelFlags];
 }
 
-const ext = process.platform === "win32" ? ".exe" : "";
-const binaryPath = path.join(binaryDir, "bin", `kcap${ext}`);
+// Everything below actually DOES something (resolves the binary, execs it,
+// runs the update flow), so it's guarded to only run when this file is
+// executed directly — not when `require()`d (e.g. by the test).
+if (require.main === module) {
+  const musl = process.platform === "linux" && isMusl() ? "-musl" : "";
+  const platformKey = `${process.platform}${musl}-${process.arch}`;
+  const packageName = PLATFORM_PACKAGES[platformKey];
+
+  if (!packageName) {
+    console.error(`Unsupported platform: ${platformKey}`);
+    console.error(`Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}`);
+    process.exit(1);
+  }
 
-if (!fs.existsSync(binaryPath)) {
-  console.error(`Binary not found at ${binaryPath}`);
-  process.exit(1);
-}
+  // Resolve the platform package
+  let binaryDir;
+  try {
+    binaryDir = path.dirname(require.resolve(`${packageName}/package.json`));
+  } catch {
+    console.error(`Platform package ${packageName} is not installed.`);
+    console.error(`Try: npm install -g @kurrent/kcap`);
+    process.exit(1);
+  }
 
-// Ensure the binary is executable (npm doesn't always preserve permissions)
-try {
-  fs.accessSync(binaryPath, fs.constants.X_OK);
-} catch {
-  try { fs.chmodSync(binaryPath, 0o755); } catch {}
-}
+  const ext = process.platform === "win32" ? ".exe" : "";
+  const binaryPath = path.join(binaryDir, "bin", `kcap${ext}`);
 
-// `kcap update` for npm-global installs is driven HERE, in the Node launcher,
-// not by the native binary. The OS locks an executable image for the whole
-// process lifetime but a script only during load — so by driving the upgrade
-// from this script (with the native binary not running) npm can overwrite the
-// binary even on Windows, with no temp-file/rename/detached-helper dance.
-// `--check` (JSON probe) and `--help` fall through to the native binary.
-{
-  const updArgs   = process.argv.slice(3);
-  const checkOnly = updArgs.includes("--check");
-  const wantsHelp = updArgs.some((a) => a === "--help" || a === "-h");
-  if (process.argv[2] === "update" && !checkOnly && !wantsHelp) {
-    runUpdate(binaryPath); // never returns
+  if (!fs.existsSync(binaryPath)) {
+    console.error(`Binary not found at ${binaryPath}`);
+    process.exit(1);
   }
-}
 
-// Exec the native binary, replacing this process
-try {
-  execFileSync(binaryPath, process.argv.slice(2), {
-    stdio: "inherit",
-    env: process.env,
-  });
-  process.exit(0);
-} catch (e) {
-  if (e.status !== null) {
-    process.exit(e.status);
+  // Ensure the binary is executable (npm doesn't always preserve permissions)
+  try {
+    fs.accessSync(binaryPath, fs.constants.X_OK);
+  } catch {
+    try { fs.chmodSync(binaryPath, 0o755); } catch {}
+  }
+
+  // `kcap update` for npm-global installs is driven HERE, in the Node launcher,
+  // not by the native binary. The OS locks an executable image for the whole
+  // process lifetime but a script only during load — so by driving the upgrade
+  // from this script (with the native binary not running) npm can overwrite the
+  // binary even on Windows, with no temp-file/rename/detached-helper dance.
+  // `--check` (JSON probe) and `--help` fall through to the native binary.
+  {
+    const updArgs   = process.argv.slice(3);
+    const checkOnly = updArgs.includes("--check");
+    const wantsHelp = updArgs.some((a) => a === "--help" || a === "-h");
+    if (process.argv[2] === "update" && !checkOnly && !wantsHelp) {
+      runUpdate(binaryPath, updArgs); // never returns
+    }
+  }
+
+  // Exec the native binary, replacing this process
+  try {
+    execFileSync(binaryPath, process.argv.slice(2), {
+      stdio: "inherit",
+      env: process.env,
+    });
+    process.exit(0);
+  } catch (e) {
+    if (e.status !== null) {
+      process.exit(e.status);
+    }
+    process.exit(1);
   }
-  process.exit(1);
 }
 
 // Performs `kcap update`: upgrade the global npm package, then refresh
 // user-scope skills/hooks. Always exits the process; never returns.
-function runUpdate(binaryPath) {
+function runUpdate(binaryPath, updArgs) {
   // On Windows, `npm` is a .cmd shim; Node refuses to spawn .cmd/.bat directly
   // (2024 command-injection fix), so route npm through a shell there. Our npm
   // args are static, so shell use is safe.
@@ -127,12 +152,13 @@ function runUpdate(binaryPath) {
   // child fully EXITS before we run npm, so the binary file is unlocked when
   // npm overwrites it (matters on Windows). `--no-update-check` keeps the
   // background nudge from racing onto stderr.
+  let info = null;
   try {
-    const out  = execFileSync(binaryPath, ["update", "--check", "--no-update-check"], { encoding: "utf8" });
+    const out  = execFileSync(binaryPath, probeArgs(updArgs), { encoding: "utf8" });
     // The probe prints one JSON line; take the last {...} line in case anything
     // else (e.g. a git-remote warning) landed on stdout first.
     const line = out.split(/\r?\n/).reverse().find((l) => l.trim().startsWith("{"));
-    const info = JSON.parse(line);
+    info = JSON.parse(line);
     // Only short-circuit when the probe is CONFIDENT we're up to date: `newer`
     // explicitly false AND a known current version. `newer: null` (version
     // unknown / check failed) falls through to the upgrade rather than stranding
@@ -177,7 +203,7 @@ function runUpdate(binaryPath) {
     process.exit(1);
   }
 
-  const res = spawnSync("npm", ["install", "-g", "@kurrent/kcap@latest"], {
+  const res = spawnSync("npm", ["install", "-g", resolveInstallSpec(info)], {
     stdio: "inherit",
     windowsHide: true,
     ...npmOpts,
@@ -211,3 +237,5 @@ function runUpdate(binaryPath) {
 
   process.exit(0);
 }
+
+module.exports = { resolveInstallSpec, probeArgs };

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

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

package/kcap/.mcp.json

@@ -14,7 +14,7 @@
       "command": "kcap",
       "args": ["mcp", "flows"],
       "cwd": "${CLAUDE_PROJECT_DIR}",
-      "description": "Structured AI review flows — start_review_flow, submit_review_round, get_review_flow_status, close_review_flow. Launches a SEPARATE hosted reviewer agent through your daemon and iterates to sign-off; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise). Use only when the user explicitly asks for a review flow / to submit for review — for an ordinary 'review my PR' or 'code review' request, review directly and do not call these tools."
+      "description": "Structured AI agent flows — start_review_flow, submit_review_round, get_review_flow_status, close_review_flow (review-specific) plus their generic equivalents start_flow, send_to_participant, get_flow_status, close_flow (any flow-definition catalog id). Launches a SEPARATE hosted participant agent through your daemon and iterates to sign-off; requires `kcap login` and a running daemon with this repo checked out (the tools are inert otherwise). Use only when the user explicitly asks for a review flow / agent flow / to submit for review — for an ordinary 'review my PR' or 'code review' request, review directly and do not call these tools."
     },
     "kcap-memory": {
       "command": "kcap",

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

@@ -0,0 +1,118 @@
+---
+name: agent-flows
+description: >-
+  This skill should be used ONLY when the user explicitly asks to run a
+  structured agent *flow* by name or definition id — e.g. "start a flow",
+  "run the code-review flow", "run the X flow", "use flow definition X",
+  "kick off an agent flow", or wants an iterative loop run by a separate
+  hosted participant agent that continues until sign-off. It covers the same
+  underlying tools as the `review-flows` skill (`start_review_flow` etc. are
+  aliases of the generic tools documented here) — use `review-flows` for the
+  two built-in review kinds (`spec-review`, `code-review`) and this skill for
+  any other flow definition, or when the user names a `definition_id`
+  explicitly. Do NOT use this skill (and do NOT call the flows MCP tools) for
+  an ordinary request such as "review my PR", "do X for me", or "check this
+  over" where the user just wants you to do the work yourself — perform that
+  work directly instead.
+---
+
+# Agent Flows
+
+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 per that definition's markers (e.g. `FINDINGS:` / `NO FINDINGS` for the review-style built-ins); you address the result and keep iterating until the definition's clean/complete signal. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
+
+## When NOT to use this skill / these tools
+
+These tools do **not** perform the work themselves — they hand it off to a separate hosted participant agent running a named flow definition. If the user simply asked *you* to do something in a normal session — e.g. "review my PR", "review this diff", "check this spec", "do X" — just do it yourself and report the result directly. Do **NOT** call `start_flow` / `send_to_participant` for an ordinary request; that would spin up a hosted agent the user did not ask for.
+
+Only start a flow when the user explicitly asks for a flow — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow.
+
+## Choosing the flow definition
+
+Once the user has explicitly opted into a flow (see above), pick the `definition_id`:
+
+- Spec or design document → `definition_id: "spec-review"` (built-in; same as `review-flows`' `spec-review` kind)
+- Code changes or a pull request → `definition_id: "code-review"` (built-in; same as `review-flows`' `code-review` kind)
+- Anything else → the definition id the user named, or one you look up in the server's flow-definition catalog at `/admin/flows`. If you're unsure which definition applies, ask the user rather than guessing.
+
+## If the flows MCP tools are not loaded
+
+If `start_flow` / `send_to_participant` are not among the tools available in this session, do NOT try to obtain them:
+
+- Do NOT run `kcap mcp flows` from a shell, do NOT handshake it over stdio/JSON-RPC, and do NOT edit any MCP configuration.
+- The absence is deliberate: hosted flow participants run with all MCP servers stripped, so a participant cannot start a nested flow.
+- If you were asked to do work and these tools are absent, you are most likely the hosted participant inside an existing flow. This skill does not apply to you — skip the workflow below entirely. Perform the requested work directly and end your final message with the definition's result markers (for the review-style built-ins, that's a final message starting with `FINDINGS:` followed by your findings, or `NO FINDINGS`; check any instructions you were given for a custom definition's actual markers). Your final message is captured automatically; no tool call is needed to deliver it.
+
+## Core rules
+
+1. **Start exactly one flow per user task.** Call `start_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID.
+2. **After receiving a non-clean result**, address it, then call `send_to_participant` with the same `flow_run_id` and the updated message.
+3. **Do NOT finish the user task while the flow has unresolved results.** Keep iterating until the definition's clean/complete signal.
+4. **Only call `close_flow` after the clean signal.** The run stays open until you explicitly close it — don't rely on it closing itself. Then report completion to the user.
+5. **If participant output is unclear or requires user input**, pause and ask the user before proceeding.
+6. **Never start a nested flow.** If you are the hosted participant (see above), do not call these tools yourself.
+7. **Single participant.** In Phase D every flow definition has exactly one participant, `reviewer`. `send_to_participant` with any other `participant` value is rejected by the server, which names the valid participant in its error.
+8. **For a code review flow (`definition_id: "code-review"`), do NOT ask the participant to run tests.** CI covers test execution; participant feedback is on correctness, design, and adherence to conventions.
+
+## Guardrail errors
+
+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 the participant agent has 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 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.
+
+## Workflow
+
+```
+start_flow(definition_id, target_kind, target_ref, target_title, context)
+  → participant returns a result per the definition's markers (e.g. FINDINGS: … | NO FINDINGS)
+
+if clean (e.g. NO FINDINGS):
+  close_flow(flow_run_id)
+  report completion to user
+  DONE
+
+if not clean (e.g. FINDINGS:):
+  address the result
+  send_to_participant(flow_run_id, participant="reviewer", message=…)
+    → repeat until clean
+  close_flow(flow_run_id)
+  report completion to user
+```
+
+## Tool reference
+
+| Tool | Required args | Optional args | When to call |
+|---|---|---|---|
+| `start_flow` | `definition_id` (e.g. `spec-review`, `code-review`, or a custom catalog id), `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) | `instructions`, `mode` (`context-only` — optional; by default, on the same machine, the participant's worktree is mirrored from your working tree including uncommitted changes, so it reads the actual source. 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` (Phase D flows have a single participant: `reviewer`), `message` | `instructions`, `async` (defaults to `true`) | After addressing a non-clean result. Pass the same `flow_run_id` and the updated message. |
+| `get_flow_status` | `flow_run_id` | — | Poll or check the current status of a flow run (running, waiting, completed, failed). |
+| `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)
+
+```
+# Step 1 — start (all five required args must be provided; on the same machine the participant sees
+# your working tree, uncommitted changes included — pass mode="context-only" to opt out)
+start_flow(
+  definition_id="code-review",
+  target_kind="branch",
+  target_ref="feature/add-null-check",
+  target_title="Add null check on user input",
+  context="Review the diff on this branch for correctness and adherence to project conventions."
+)
+# → returns flow_run_id, e.g. "flow_abc123"
+# → participant returns FINDINGS: missing null check on line 42
+
+# Step 2 — address findings, then send a follow-up to the reviewer participant
+send_to_participant(
+  flow_run_id="flow_abc123",
+  participant="reviewer",
+  message="Fixed null check on line 42. Updated diff attached."
+)
+
+# Step 3 — participant returns NO FINDINGS
+close_flow(flow_run_id="flow_abc123")
+# Report to user: flow complete, all findings resolved
+```

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

@@ -15,6 +15,8 @@ description: >-
 
 Use the `kcap mcp flows` MCP tools (`start_review_flow`, `submit_review_round`, …) to run a structured review **flow**: your work is submitted to a **separate, hosted reviewer** agent, which returns findings; you address them and keep iterating until the reviewer returns `NO FINDINGS`. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
 
+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.
+
 ## When NOT to use this skill / these tools
 
 These tools do **not** perform a review — they hand the work off to a separate hosted reviewer. If the user simply asked *you* to review something in a normal session — e.g. "review my PR", "review this diff", "code review this", "look over this spec" — just perform the review yourself and report your findings directly. Do **NOT** call `start_review_flow` / `submit_review_round` for an ordinary review request; that would spin up a hosted reviewer the user did not ask for.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,12 +14,12 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "0.9.0",
-    "@kurrent/kcap-linux-x64": "0.9.0",
-    "@kurrent/kcap-linux-arm64": "0.9.0",
-    "@kurrent/kcap-linux-musl-x64": "0.9.0",
-    "@kurrent/kcap-linux-musl-arm64": "0.9.0",
-    "@kurrent/kcap-win-x64": "0.9.0"
+    "@kurrent/kcap-darwin-arm64": "0.9.2",
+    "@kurrent/kcap-linux-x64": "0.9.2",
+    "@kurrent/kcap-linux-arm64": "0.9.2",
+    "@kurrent/kcap-linux-musl-x64": "0.9.2",
+    "@kurrent/kcap-linux-musl-arm64": "0.9.2",
+    "@kurrent/kcap-win-x64": "0.9.2"
   },
   "files": [
     "bin/",