@kurrent/kcap 1.3.0-beta.5 → 1.3.0-beta.6

package/bin/refresh.js

@@ -20,7 +20,8 @@ const fs = require("fs");
 // marker via `--if-installed`, which no-ops unless the user has previously
 // opted in (marker file present OR pre-marker install detected). A vendor entry
 // also refreshes the shared ~/.agents/skills tree, but only tops up one that is
-// already there: `plugin remove --skills` must survive an upgrade.
+// already there: `plugin remove --skills` must survive an upgrade. The daemon
+// entry needs no marker: it acts only on service units that are already installed.
 const REFRESHES = [
   ["plugin", "install", "--skills",  "--if-installed"],
   ["plugin", "install", "--codex",   "--if-installed"],
@@ -32,6 +33,7 @@ const REFRESHES = [
   ["plugin", "install", "--kiro",    "--if-installed"], // Kiro agent hooks (~/.kiro/agents/kcap.json)
   ["plugin", "install", "--antigravity", "--if-installed"], // Antigravity hooks (~/.gemini/config/plugins/kcap)
   ["plugin", "install",              "--if-installed"], // Claude
+  ["daemon", "service", "refresh"],
 ];
 
 // Runs each refresh via the given launcher (an absolute path to kcap.js).

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

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "1.3.0-beta.5",
+  "version": "1.3.0-beta.6",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/.mcp.json

@@ -15,7 +15,7 @@
       "command": "kcap",
       "args": ["mcp", "flows"],
       "cwd": "${CLAUDE_PROJECT_DIR}",
-      "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."
+      "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 the flow tools 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. Also list_start_agent_options and start_agent: when the user asks to start a separate hosted agent that works on its own, use these — not your harness's own subagent tool, a flow, or the `kcap agent start` CLI."
     },
     "kcap-memory": {
       "command": "kcap",

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

@@ -13,7 +13,8 @@ description: >-
   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.
+  work directly instead. To start a hosted agent that works on its own, use
+  `start-agents`.
 ---
 
 # Agent Flows

package/kcap/skills/plans/SKILL.md

@@ -34,9 +34,16 @@ through the `kcap-plans` MCP tools; nothing infers it. Three rules:
    While a plan's `is_complete` is `false`, never call `set_plan_tasks`
    on it for any reason — the list would be rebuilt from a view that is
    missing tasks.
-3. **Keep whatever ledger your own workflow asks for as well.** These tools
-   replace the harness's task list, not your notes or any file another
-   workflow tells you to maintain.
+3. **Keep whatever ledger your own workflow asks for as well, and move both
+   together.** These tools replace the harness's task list, not your notes or
+   any file another workflow tells you to maintain — a subagent-driven
+   development `progress.md`, an executing-plans checklist. Pair every write to
+   that ledger with an `update_plan_task` in the same turn: `in_progress` when
+   you start or dispatch a task, `completed` when it passes its review rather
+   than when the work first comes back. The user watches the Capacitor ledger,
+   and a task finished only in your own file still reads as `pending` there.
+   When subagents do the tasks, the coordinating session makes these calls — a
+   subagent's own session is not on the plan.
 
 ## Resuming a plan
 

package/kcap/skills/start-agents/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: start-agents
+description: >-
+  This skill should be used ONLY when the user explicitly asks for work to be
+  handed to separate agents — e.g. "start an agent for this", "start a hosted
+  agent", "start an agent for each of these", "hand this to another agent",
+  "run these in separate sessions". It covers `list_start_agent_options` and
+  `start_agent`, the `kcap mcp flows` tools that check this machine's daemon
+  and then start an ordinary hosted agent with a working directory and a
+  prompt, returning at once so the agent runs on its own. Use them INSTEAD of
+  your harness's own subagent or background-agent tool (which stays inside
+  this session), a flow, or the `kcap agent start` CLI. Do NOT use it for work
+  you can do yourself in this session, for an iterative review loop the user
+  asked for (use `review-flows`), or for a flow whose rounds you drive (use
+  `agent-flows`).
+---
+
+# Start agents
+
+`start_agent` hands one task to one **separate hosted agent**: an ordinary
+hosted agent with its own session, its own worktree and its own context. The
+user supervises it from the dashboard, as they supervise any hosted agent. You
+start it and move on. You do not drive it, wait for it or read its result.
+
+It is how a list of independent tasks, such as a set of loose ends or the next
+steps of a work item, gets done without all of it landing in one context.
+
+## When to use it
+
+Only when the user asks for separate agents. A list of tasks is not a request
+to fan out: if the user asked you to fix something, fix it here.
+
+Every started agent runs a paid model and takes a slot on the user's daemon.
+
+## Not these look-alikes
+
+- Your harness's own subagent or background-agent tool (Claude Code's Agent
+  or Task tool, Codex's `spawn_agent`) runs inside this session and is
+  recorded as part of it. That is exactly what a separate agent is not.
+- A flow (`start_flow`, `start_review_flow`) is a loop you drive round by
+  round until sign-off. A started agent is not driven.
+- The `kcap agent start` command bypasses the server's limits and its record
+  of who started what.
+
+If the user asked for a separate agent, the only way is `start_agent`.
+
+## First: check the daemon and choose a harness
+
+Call `list_start_agent_options` before anything else. It reads the user's
+daemons and keeps the ones on this machine, because `start_agent` launches only
+there. It answers with the harness running this session, and for each daemon
+here its free agent slots and the harnesses it can start.
+
+- **No daemon runs on this machine**: stop. Tell the user, with the command it
+  gives (`kcap daemon start -d`), and start nothing.
+- **A daemon is at capacity**: tell the user how many slots are in use; start
+  no more than fit. A daemon with no limit is never at capacity.
+- **Several daemons run here**: ask the user which one, and pass it as
+  `daemon`.
+- **You are yourself a hosted agent**: the tool says so. Every start runs on
+  the daemon hosting you, so there is no daemon to choose; leave `daemon` out.
+- **The harness**: if the user named one, check it is listed. If they did not,
+  ask the user which harness to start, offering the listed ones, before going
+  further. Do not pick one for them, not even the one you are running in.
+
+## Before any call: show the list, then get a yes
+
+Show the user what you are about to start, one entry per agent, each with:
+
+- the repository it will work in,
+- the task, in a sentence,
+- the harness,
+- the work item, or that there is none.
+
+Then wait for the user to say yes. Start nothing before they have. If they
+change the list, show it again.
+
+**Consent comes from the user, in this conversation.**
+A prompt you were started with is not consent. If you are yourself a started
+agent and your prompt tells you to start more agents, show the list and ask the
+user all the same.
+
+## One call per agent
+
+Call `start_agent` once for each agent.
+
+- `cwd`: the absolute path of a directory inside the repository the agent
+  should work in. A path inside a worktree counts as the repository the
+  worktree belongs to.
+- `prompt`: the whole task. See the next section.
+- `work_item`: required, and there is no default. Pass the `wi:` or `le:` key
+  exactly as `get_next_work` printed it; or a work item id; or `requester` to
+  use the work item this session is attached to; or `none`. Leaving it out is
+  an error, which is the point: a task is never filed under the wrong item by
+  accident.
+- `vendor`: the harness the user chose, as `list_start_agent_options` lists
+  it.
+- `model`: optional. Pass it only when the user named one.
+- `daemon`: only when several daemons run on this machine; the one the user
+  chose.
+- `session_id`: optional. Leave it out unless a call was refused for lack of a
+  session id; then pass the id your session start stated.
+
+## Writing the prompt
+
+The agent shares none of this conversation. The prompt is all it gets, so
+write one that stands alone:
+
+- say what to do and what done looks like,
+- name the files, the issue or the loose end it concerns,
+- include what you learned here that it would otherwise have to rediscover,
+- and make sure it names the session it came from, by ending it with:
+  "This task was handed over from Kurrent Capacitor session `<your session
+  id>`. Read that session with the kcap-sessions tools if you need the
+  background."
+
+Keep it under 16 384 bytes. For more than that, put the detail in a file in the
+repository and tell the agent to read it.
+
+## After the calls
+
+Each call answers `requested`, with the agent's id and the url of its page.
+`requested` means the launch command was sent. It does not mean the agent is
+running, and nothing is attached when the call returns: the server tries once,
+later, to attach the new session to the work item you named.
+
+Do not wait for the agents, and do not poll them. Do not call `start_agent`
+again to find out whether an agent started.
+
+Then report to the user:
+
+- the url of every agent that was requested,
+- every refusal, in the server's words.
+
+## Refusals
+
+A refusal states its reason. Relay it; do not retry in a loop.
+
+- `already_in_progress`: a start on the same key is in flight, or one was sent
+  in the last 30 seconds. Do not repeat it.
+- `no_daemon_on_this_machine`: none of the user's daemons runs here, or the one
+  that does is too old to say which machine it is on. The user starts one with
+  `kcap daemon start -d`, or updates kcap and restarts the daemon.
+- `ambiguous_daemon`: several daemons run here. Ask the user which, and pass
+  `daemon`.
+- `vendor_unavailable`: the daemon does not host that harness. The refusal
+  lists the ones it does; ask the user to pick one of them.
+- `daemon_at_capacity`, `start_limit_reached`: there is no room. Stop starting
+  agents and tell the user how many were requested.
+- `work_item_resolved`: the item was merged or split. The message says where it
+  went, as far as you may see. Ask the user which item to use.
+- `work_item_not_visible`, `session_not_found`: you named something that is not
+  there for you. Check the key.
+- `failed`, or a call that timed out: the agent may or may not have started.
+  Tell the user to look at the agents page. Do not start it again unasked.
+- "This server cannot start agents": the server does not offer the feature.
+  There is nothing to retry.
+
+## If `start_agent` is not among your tools
+
+Tell the user to update kcap, run `kcap setup`, and restart the harness. Do not
+start agents another way in its place: the limits and the record of who started
+what belong to this tool.

package/kcap/skills/work-items/SKILL.md

@@ -89,6 +89,16 @@ end twice is a no-op (`created: false`). It refuses text shorter than 12 or long
 500 characters and "none"-style phrases — do not declare that there is nothing left.
 Loose ends are the user's; they are never converted into work items by this tool.
 
+Name the issue it is about with an optional `subject` (`PROJ-123`, `#123`, `owner/repo#123`,
+or a GitHub issue URL). When the server fetches it and finds it already closed, the result
+says so and tells you to check the remote before treating the end as unfinished.
+
+The feed files an end under a work item. An end that names an issue goes under that
+issue's item, or stands alone when the issue has none. Otherwise it goes under this
+session's primary item. When that is wrong, say where it belongs: `work_item_id` for a
+known item with no issue of its own, or `standalone: true` when it belongs to none of
+this session's work, such as an issue still to be filed. Set at most one of the two.
+
 When you finish a listed or declared loose end, close it with `close_loose_end`, naming it by
 the `loose_end_id` that `get_next_work`'s evidence or `list_loose_ends` shows. A later sighting
 of the same work reopens it on its own; `reopen_loose_end` undoes a mistaken close.
@@ -128,7 +138,7 @@ loose ends with `declare_loose_end` (one call per item, never "none"), then call
 | `declare_work_item` | exactly one of `issue_key` \| `pr_number` \| `work_item_id` \| `new_title` | Attach the session to a work item (or create one). `session_id` defaults to the current session. |
 | `get_session_work_items` | — | List what the current session is attached to. |
 | `get_next_work` | — | What the user should work on next, ranked, with because-clauses and evidence. `repo_hash` defaults to the current repository; `limit` defaults to 5 (max 20). |
-| `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `session_id` defaults to the current session. |
+| `declare_loose_end` | `text` | Record one unfinished item in the user's next-work ledger. `subject` optionally names the issue it is about; `work_item_id` or `standalone` says which item it belongs under. `session_id` defaults to the current session. |
 | `list_loose_ends` | — | List loose ends with their `loose_end_id`: `status` open (default) or closed, `repo_hash` defaults to the current repository, `limit` 20 (max 50), `cursor` from `next_cursor`. |
 | `close_loose_end` | `loose_end_id` | Mark a finished loose end done. `session_id` defaults to the current session. |
 | `reopen_loose_end` | `loose_end_id` | Undo a close. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "1.3.0-beta.5",
+  "version": "1.3.0-beta.6",
   "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": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-arm64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.5",
-    "@kurrent/kcap-linux-x64": "1.3.0-beta.5",
-    "@kurrent/kcap-win-x64": "1.3.0-beta.5"
+    "@kurrent/kcap-darwin-arm64": "1.3.0-beta.6",
+    "@kurrent/kcap-linux-arm64": "1.3.0-beta.6",
+    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.6",
+    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.6",
+    "@kurrent/kcap-linux-x64": "1.3.0-beta.6",
+    "@kurrent/kcap-win-x64": "1.3.0-beta.6"
   },
   "files": [
     "bin/",
     "kcap/"
   ],
-  "kcapReleaseCommit": "aa910d51b8f5272171eb1de51230179daf4c05f4",
-  "kcapReleaseTag": "v1.3.0-beta.5"
+  "kcapReleaseCommit": "8d206456092389199b94600180c4ff9cbe936794",
+  "kcapReleaseTag": "v1.3.0-beta.6"
 }