@kurrent/kcap 0.9.2 → 0.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/kcap/.claude-plugin/plugin.json +1 -1
  2. package/kcap/skills/agent-flows/SKILL.md +12 -7
  3. package/kcap/skills/review-flows/SKILL.md +20 -12
  4. package/package.json +7 -7
package/kcap/.claude-plugin/plugin.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "kcap",
3
- "version": "0.9.2",
3
+ "version": "0.9.4",
4
4
  "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
5
5
  }
package/kcap/skills/agent-flows/SKILL.md CHANGED
@@ -18,7 +18,7 @@ description: >-
18
18
 
19
19
  # Agent Flows
20
20
 
21
- 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.
21
+ 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.
22
22
 
23
23
  ## When NOT to use this skill / these tools
24
24
 
@@ -40,7 +40,7 @@ If `start_flow` / `send_to_participant` are not among the tools available in thi
40
40
 
41
41
  - Do NOT run `kcap mcp flows` from a shell, do NOT handshake it over stdio/JSON-RPC, and do NOT edit any MCP configuration.
42
42
  - The absence is deliberate: hosted flow participants run with all MCP servers stripped, so a participant cannot start a nested flow.
43
- - 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.
43
+ - 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, then deliver your result by calling the `submit_review_result` tool (from the injected `kcap-flow-result` server) exactly as the "Result contract" section of your prompt instructs, quoting its round token — `kind: "findings"` plus your result text, or `kind: "clean"`. The tool is the ONLY delivery channel: the server does not read your reply text, so result markers in your final message deliver nothing and the round would sit unresolved until its timeout. If the tool call fails, retry it.
44
44
 
45
45
  ## Core rules
46
46
 
@@ -52,6 +52,7 @@ If `start_flow` / `send_to_participant` are not among the tools available in thi
52
52
  6. **Never start a nested flow.** If you are the hosted participant (see above), do not call these tools yourself.
53
53
  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.
54
54
  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.
55
+ 9. **State where your changes live.** The participant's worktree is mirrored from the working tree you LAUNCHED from (your cwd's git root) — nothing else. If any part of the changeset lives elsewhere (another git worktree, another repository, a different machine) or is not in that tree, say so explicitly in `context`/`message` and inline the relevant diffs or file contents — or pass `mode: "context-only"` so the participant treats your context as the sole source of truth. The participant is instructed to flag referenced changes it cannot find in its worktree; incomplete context wastes a full round.
55
56
 
56
57
  ## Guardrail errors
57
58
 
@@ -61,19 +62,23 @@ The server enforces per-run budgets; watch for these in tool error responses:
61
62
  - **`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.
62
63
  - **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.
63
64
  - **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.
65
+ - **`400` starting `no_daemon_available:`** — no connected daemon has the repo checked out. Tell the user to run `kcap agent` on a machine with the repo cloned (or pass an explicit `daemon_name` + `repo_path`).
66
+ - **`400` starting `daemon_outdated:`** — the daemon's kcap is too old to host flow participants. Tell the user to update (`npm i -g @kurrent/kcap`) and restart `kcap agent`.
67
+ - **`400` starting `participant_unavailable:`** — the participant 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.
68
+ - **A round result of `unclear` whose text is exactly `participant_died` or `participant_stopped`** — the participant agent crashed or was stopped mid-round. The run stays open but has no live participant: close the flow and start a new one.
64
69
 
65
70
  ## Workflow
66
71
 
67
72
  ```
68
73
  start_flow(definition_id, target_kind, target_ref, target_title, context)
69
- → participant returns a result per the definition's markers (e.g. FINDINGS: … | NO FINDINGS)
74
+ → participant returns a result: kind findings (with the result text) | kind clean
70
75
 
71
- if clean (e.g. NO FINDINGS):
76
+ if clean:
72
77
  close_flow(flow_run_id)
73
78
  report completion to user
74
79
  DONE
75
80
 
76
- if not clean (e.g. FINDINGS:):
81
+ if findings:
77
82
  address the result
78
83
  send_to_participant(flow_run_id, participant="reviewer", message=…)
79
84
  → repeat until clean
@@ -103,7 +108,7 @@ start_flow(
103
108
  context="Review the diff on this branch for correctness and adherence to project conventions."
104
109
  )
105
110
  # → returns flow_run_id, e.g. "flow_abc123"
106
- # → participant returns FINDINGS: missing null check on line 42
111
+ # → participant returns kind findings: missing null check on line 42
107
112
 
108
113
  # Step 2 — address findings, then send a follow-up to the reviewer participant
109
114
  send_to_participant(
@@ -112,7 +117,7 @@ send_to_participant(
112
117
  message="Fixed null check on line 42. Updated diff attached."
113
118
  )
114
119
 
115
- # Step 3 — participant returns NO FINDINGS
120
+ # Step 3 — participant returns kind clean
116
121
  close_flow(flow_run_id="flow_abc123")
117
122
  # Report to user: flow complete, all findings resolved
118
123
  ```
package/kcap/skills/review-flows/SKILL.md CHANGED
@@ -13,7 +13,7 @@ description: >-
13
13
 
14
14
  # Review Flows
15
15
 
16
- 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.
16
+ 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 a result (`findings` with the findings text, or `clean`); you address findings and keep iterating until the reviewer returns `clean`. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
17
17
 
18
18
  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.
19
19
 
@@ -36,32 +36,40 @@ If `start_review_flow` / `submit_review_round` are not among the tools available
36
36
 
37
37
  - Do NOT run `kcap mcp flows` from a shell, do NOT handshake it over stdio/JSON-RPC, and do NOT edit any MCP configuration.
38
38
  - The absence is deliberate: hosted review-flow reviewers run with all MCP servers stripped, so a reviewer cannot start a nested flow.
39
- - If you were asked to review a spec, design, or code and these tools are absent, you are most likely the hosted reviewer inside an existing flow. This skill does not apply to you — skip the workflow below entirely. Perform the requested review directly and end with a final message that starts with `FINDINGS:` (followed by your findings) or `NO FINDINGS`. Your final message is captured automatically; no tool call is needed to deliver it.
39
+ - If you were asked to review a spec, design, or code and these tools are absent, you are most likely the hosted reviewer inside an existing flow. This skill does not apply to you — skip the workflow below entirely. Perform the requested review directly, then deliver your result by calling the `submit_review_result` tool (from the injected `kcap-flow-result` server) exactly as the "Result contract" section of your prompt instructs, quoting its round token — `kind: "findings"` plus your findings text, or `kind: "clean"`. The tool is the ONLY delivery channel: the server does not read your reply text, so ending with `FINDINGS:`/`NO FINDINGS` markers delivers nothing and the round would sit unresolved until its timeout. If the tool call fails, retry it.
40
40
 
41
41
  ## Core rules
42
42
 
43
43
  1. **Start exactly one flow per user task.** Call `start_review_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID.
44
- 2. **After receiving `FINDINGS:`**, address every finding, then call `submit_review_round` with the updated context and the same `flow_run_id`.
45
- 3. **Do NOT finish the user task while the flow has unresolved findings.** Keep iterating until the reviewer returns `NO FINDINGS`.
46
- 4. **Only call `close_review_flow` after `NO FINDINGS`.** Then report completion to the user.
44
+ 2. **After receiving a `findings` result**, address every finding, then call `submit_review_round` with the updated context and the same `flow_run_id`.
45
+ 3. **Do NOT finish the user task while the flow has unresolved findings.** Keep iterating until the reviewer returns `clean`.
46
+ 4. **Only call `close_review_flow` after a `clean` result.** Then report completion to the user.
47
47
  5. **If reviewer output is unclear or requires user input**, pause and ask the user before proceeding.
48
48
  6. **For code review, do NOT ask the reviewer to run tests.** CI covers test execution; reviewer feedback is on correctness, design, and adherence to conventions.
49
+ 7. **State where your changes live.** The reviewer's worktree is mirrored from the working tree you LAUNCHED from (your cwd's git root) — nothing else. If any part of the changeset lives elsewhere (another git worktree, another repository, a different machine) or is not in that tree, say so explicitly in `context` and inline the relevant diffs or file contents — or pass `mode: "context-only"` so the reviewer treats your context as the sole source of truth. The reviewer is instructed to flag referenced changes it cannot find in its worktree; incomplete context wastes a full round.
50
+
51
+ ## Server errors to act on
52
+
53
+ - **`400` starting `no_daemon_available:`** — no connected daemon has the repo checked out. Tell the user to run `kcap agent` on a machine with the repo cloned (or pass an explicit `daemon_name` + `repo_path`).
54
+ - **`400` starting `daemon_outdated:`** — the daemon's kcap is too old to host flow participants. Tell the user to update (`npm i -g @kurrent/kcap`) and restart `kcap agent`.
55
+ - **`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.
56
+ - **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.
49
57
 
50
58
  ## Workflow
51
59
 
52
60
  ```
53
61
  start_review_flow(kind, target_kind, target_ref, target_title, context)
54
- → reviewer returns FINDINGS: … | NO FINDINGS
62
+ → reviewer returns a result: findings (with the findings text) | clean
55
63
 
56
- if NO FINDINGS:
64
+ if clean:
57
65
  close_review_flow(flow_run_id)
58
66
  report completion to user
59
67
  DONE
60
68
 
61
- if FINDINGS:
69
+ if findings:
62
70
  address each finding
63
71
  submit_review_round(flow_run_id, updated_context)
64
- → repeat until NO FINDINGS
72
+ → repeat until clean
65
73
  close_review_flow(flow_run_id)
66
74
  report completion to user
67
75
  ```
@@ -73,7 +81,7 @@ if FINDINGS:
73
81
  | `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) | `instructions`, `mode` (`context-only` — optional; by default, on the same machine, the reviewer'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 review task. |
74
82
  | `submit_review_round` | `flow_run_id`, `context` | `instructions` | After addressing findings. Pass the same `flow_run_id` and the updated context. |
75
83
  | `get_review_flow_status` | `flow_run_id` | — | Poll or check the current status of a flow (running, waiting, completed, failed). |
76
- | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `NO FINDINGS`. |
84
+ | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `clean`. |
77
85
 
78
86
  ## Example (code review)
79
87
 
@@ -88,7 +96,7 @@ start_review_flow(
88
96
  context="Review the diff on this branch for correctness and adherence to project conventions."
89
97
  )
90
98
  # → returns flow_run_id, e.g. "flow_abc123"
91
- # → reviewer returns FINDINGS: missing null check on line 42
99
+ # → reviewer returns kind findings: missing null check on line 42
92
100
 
93
101
  # Step 2 — address findings, then re-submit
94
102
  submit_review_round(
@@ -96,7 +104,7 @@ submit_review_round(
96
104
  context="Fixed null check on line 42. Updated diff attached."
97
105
  )
98
106
 
99
- # Step 3 — reviewer returns NO FINDINGS
107
+ # Step 3 — reviewer returns kind clean
100
108
  close_review_flow(flow_run_id="flow_abc123")
101
109
  # Report to user: review complete, all findings resolved
102
110
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kurrent/kcap",
3
- "version": "0.9.2",
3
+ "version": "0.9.4",
4
4
  "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "repository": {
@@ -14,12 +14,12 @@
14
14
  "postinstall": "node bin/postinstall.js"
15
15
  },
16
16
  "optionalDependencies": {
17
- "@kurrent/kcap-darwin-arm64": "0.9.2",
18
- "@kurrent/kcap-linux-x64": "0.9.2",
19
- "@kurrent/kcap-linux-arm64": "0.9.2",
20
- "@kurrent/kcap-linux-musl-x64": "0.9.2",
21
- "@kurrent/kcap-linux-musl-arm64": "0.9.2",
22
- "@kurrent/kcap-win-x64": "0.9.2"
17
+ "@kurrent/kcap-darwin-arm64": "0.9.4",
18
+ "@kurrent/kcap-linux-x64": "0.9.4",
19
+ "@kurrent/kcap-linux-arm64": "0.9.4",
20
+ "@kurrent/kcap-linux-musl-x64": "0.9.4",
21
+ "@kurrent/kcap-linux-musl-arm64": "0.9.4",
22
+ "@kurrent/kcap-win-x64": "0.9.4"
23
23
  },
24
24
  "files": [
25
25
  "bin/",