patchcord 0.5.80 → 0.5.82

package/bin/patchcord.mjs

@@ -46,7 +46,7 @@ const PROJECT_MARKERS = [
   ".git", "package.json", "package-lock.json", "Cargo.toml", "go.mod", "go.sum",
   "pyproject.toml", "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
   "Gemfile", "composer.json", "mix.exs", "requirements.txt", "setup.py",
-  ".claude", ".codex", ".cursor", ".vscode", ".openclaw",
+  ".claude", ".codex", ".cursor", ".vscode", ".kimi", ".openclaw",
 ];
 
 function detectFolder(dir) {
@@ -97,8 +97,19 @@ if (cmd === "plugin-path") {
 // Supports all 12 installer targets: claude_code, codex, cursor, vscode,
 // opencode (per-project) + windsurf, gemini, zed, openclaw, antigravity,
 // cline, kimi (global). Each tool stores the bearer in its own shape.
-async function _resolveBearer() {
+function _kimiContextRequested(options = {}) {
+  const forceTool = (process.env.PATCHCORD_FORCE_TOOL || process.env.PATCHCORD_TOOL || "").toLowerCase();
+  return options.preferKimi === true
+    || forceTool === "kimi"
+    || Boolean(process.env.KIMI_CLI)
+    || Boolean(process.env.KIMI_SESSION_ID)
+    || Boolean(process.env.KIMI_CONFIG_FILE)
+    || Boolean(process.env.KIMI_MCP_CONFIG_FILE);
+}
+
+async function _resolveBearer(options = {}) {
   const { readFileSync } = await import("fs");
+  const preferKimi = _kimiContextRequested(options);
 
   // Strict JSON first; fall back to JSONC stripping for zed/gemini-style
   // settings (which allow // /* */ trailing commas). The fallback strips
@@ -188,15 +199,17 @@ async function _resolveBearer() {
   };
 
   // Per-project (walk up from cwd). First win.
-  const projectReaders = [
+  const kimiProjectReader = (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
+  const defaultProjectReaders = [
     (cwd) => readJsonAt(join(cwd, ".mcp.json"), ["mcpServers", "patchcord"], "claude_code"),
     (cwd) => readJsonAt(join(cwd, ".cursor", "mcp.json"), ["mcpServers", "patchcord"], "cursor"),
     (cwd) => readJsonAt(join(cwd, ".vscode", "mcp.json"), ["servers", "patchcord"], "vscode"),
     (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "patchcord"], "opencode"),
     (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml")),
-    // Kimi can be per-project via .kimi/mcp.json + --mcp-config-file
-    (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi"),
   ];
+  const projectReaders = preferKimi
+    ? [kimiProjectReader, ...defaultProjectReaders]
+    : [...defaultProjectReaders, kimiProjectReader];
   let dir = process.cwd();
   while (dir && dir !== "/") {
     for (const r of projectReaders) {
@@ -235,16 +248,18 @@ async function _resolveBearer() {
     );
   })();
 
-  const globalCandidates = [
+  const kimiGlobalReader = () => readJsonAt(join(HOME, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
+  const defaultGlobalCandidates = [
     () => readJsonAt(join(HOME, ".codeium", "windsurf", "mcp_config.json"), ["mcpServers", "patchcord"], "windsurf"),
     () => readJsonAt(join(HOME, ".gemini", "settings.json"), ["mcpServers", "patchcord"], "gemini"),
     () => readJsonAt(zedPath, ["context_servers", "patchcord"], "zed"),
     () => readJsonAt(join(HOME, ".openclaw", "openclaw.json"), ["mcp", "servers", "patchcord"], "openclaw"),
     () => readJsonAt(join(HOME, ".gemini", "antigravity", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity"),
     ...clinePaths.map((p) => () => readJsonAt(p, ["mcpServers", "patchcord"], "cline")),
-    // Global Kimi fallback (only if no per-project .kimi/mcp.json was found)
-    () => readJsonAt(join(HOME, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi"),
   ];
+  const globalCandidates = preferKimi
+    ? [kimiGlobalReader, ...defaultGlobalCandidates]
+    : [...defaultGlobalCandidates, kimiGlobalReader];
   for (const r of globalCandidates) {
     const found = r();
     if (found) return found;
@@ -1049,21 +1064,17 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     const kimiSubDir = join(HOME, ".kimi", "skills", "patchcord:subscribe");
     let kimiChanged = false;
 
-    if (!existsSync(kimiInboxDir)) {
-      mkdirSync(kimiInboxDir, { recursive: true });
-      cpSync(join(pluginRoot, "per-project-skills", "kimi", "inbox", "SKILL.md"), join(kimiInboxDir, "SKILL.md"));
-      kimiChanged = true;
-    }
-    if (!existsSync(kimiWaitDir)) {
-      mkdirSync(kimiWaitDir, { recursive: true });
-      cpSync(join(pluginRoot, "per-project-skills", "kimi", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
-      kimiChanged = true;
-    }
-    if (!existsSync(kimiSubDir)) {
-      mkdirSync(kimiSubDir, { recursive: true });
-      cpSync(join(pluginRoot, "per-project-skills", "kimi", "subscribe", "SKILL.md"), join(kimiSubDir, "SKILL.md"));
-      kimiChanged = true;
-    }
+    const installKimiSkill = (destDir, relSrc) => {
+      const src = join(pluginRoot, "per-project-skills", "kimi", relSrc, "SKILL.md");
+      const dest = join(destDir, "SKILL.md");
+      const changed = !existsSync(dest) || readFileSync(dest, "utf-8") !== readFileSync(src, "utf-8");
+      mkdirSync(destDir, { recursive: true });
+      copyFileSync(src, dest);
+      return changed;
+    };
+    kimiChanged = installKimiSkill(kimiInboxDir, "inbox") || kimiChanged;
+    kimiChanged = installKimiSkill(kimiWaitDir, "wait") || kimiChanged;
+    kimiChanged = installKimiSkill(kimiSubDir, "subscribe") || kimiChanged;
 
     // Install/update stop hook — fires after each Kimi turn to check inbox
     let hookChanged = false;
@@ -1085,8 +1096,29 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       const kept = segments.filter((seg, idx) => idx === 0 || !seg.includes("patchcord-stop-hook"));
       kimiConfig = kept.join("[[hooks]]").replace(/\n{3,}/g, "\n\n").trim();
 
-      // Append new hook
-      kimiConfig = kimiConfig.trimEnd() + `\n\n[[hooks]]\nevent = "Stop"\ncommand = "${kimiHookDest}"\ntimeout = 10\n`;
+      // Install session-start hook
+      const kimiSessionSrc = join(pluginRoot, "scripts", "kimi-session-start.sh");
+      const kimiSessionDest = join(HOME, ".kimi", "patchcord-session-start.sh");
+      if (existsSync(kimiSessionSrc)) {
+        copyFileSync(kimiSessionSrc, kimiSessionDest);
+        chmodSync(kimiSessionDest, 0o755);
+      }
+
+      // Remove existing patchcord session-start hook blocks
+      const segments2 = kimiConfig.split("[[hooks]]");
+      const kept2 = segments2.filter((seg, idx) => idx === 0 || !seg.includes("patchcord-session-start") && !seg.includes("patchcord-prompt-hook"));
+      kimiConfig = kept2.join("[[hooks]]").replace(/\n{3,}/g, "\n\n").trim();
+
+      // Remove the legacy UserPromptSubmit shim script if a prior install left it.
+      // Kimi displays stderr to the user but does not feed it to the LLM, so the
+      // shim never auto-executed anything — flow skills handle slash invocations.
+      const kimiPromptDest = join(HOME, ".kimi", "patchcord-prompt-hook.sh");
+      if (existsSync(kimiPromptDest)) {
+        try { rmSync(kimiPromptDest, { force: true }); } catch {}
+      }
+
+      // Append new hooks
+      kimiConfig = kimiConfig.trimEnd() + `\n\n[[hooks]]\nevent = "SessionStart"\ncommand = "${kimiSessionDest}"\ntimeout = 10\n\n[[hooks]]\nevent = "Stop"\ncommand = "${kimiHookDest}"\ntimeout = 10\n`;
 
       mkdirSync(dirname(kimiConfigPath), { recursive: true });
       writeFileSync(kimiConfigPath, kimiConfig);
@@ -1106,7 +1138,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
 
     const kimiParts = [];
     if (kimiChanged) kimiParts.push("skills");
-    if (hookChanged) kimiParts.push("stop hook");
+    if (hookChanged) kimiParts.push("hooks");
     if (subChanged) kimiParts.push("subscribe script");
     if (kimiParts.length > 0) {
       globalChanges.push(`Kimi CLI ${kimiParts.join(" + ")} installed`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.5.80",
+  "version": "0.5.82",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

package/per-project-skills/kimi/inbox/SKILL.md

@@ -1,153 +1,12 @@
 ---
 name: patchcord:inbox
-description: >
-  Cross-agent messaging for Kimi CLI via the Patchcord MCP server. Use when
-  the user mentions other agents, inbox state, sending messages, who's online,
-  or cross-machine coordination.
+description: Read Patchcord inbox and reply to messages
+type: flow
 ---
 
-# patchcord:inbox
-
-You are connected to Patchcord through the MCP server configured in
-`.kimi/mcp.json` inside your project directory. Kimi normally uses a global
-config, but Patchcord sets up **per-project agents** via `--mcp-config-file`.
-
-**Launch Kimi in project directories with `kimi-pc`** (not plain `kimi`).
-This wrapper auto-detects `.kimi/mcp.json` in the current project and loads
-the right agent identity.
-
-```bash
-# In any project with .kimi/mcp.json:
-kimi-pc
-
-# Falls back to global ~/.kimi/mcp.json if no project config found.
+```mermaid
+flowchart TD
+  A([BEGIN]) --> B[Call the inbox MCP tool. For each pending message: do the work it asks for, then call reply with the message_id and a concrete summary of what you did.]
+  B --> C[Use the Shell tool to run `patchcord subscribe --kimi 5` with run_in_background=true and timeout=86400 to re-arm the listener.]
+  C --> D([END])
 ```
-
-The installer automatically adds an alias to your `~/.bashrc` and `~/.zshrc`:
-```bash
-alias kimi-pc='kimi --mcp-config-file .kimi/mcp.json'
-```
-
-Reload your shell or run `source ~/.bashrc` (or `~/.zshrc`) to use it.
-
-## Tools available
-
-- `inbox(all_agents?)` - read pending messages, current identity, and recently active agents. `all_agents=true` includes inactive agents. Returns a `groups` list (messages grouped by thread) alongside the legacy `pending` flat list.
-- `send_message(to_agent, content, thread?)` - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Use `@username` for cross-user Gate messaging. `thread` is an optional slug to start or join a named thread.
-- `reply(message_id, content?, defer?, resolve?)` - reply to a received message. Auto-inherits the thread of the original. `defer=true` keeps the original visible in inbox for later. `resolve=true` closes the thread.
-- `wait_for_message(timeout_seconds?)` - block until incoming message arrives. Default 5 minutes. Known to error intermittently - if it fails, poll inbox() every 10-15 seconds as fallback. Detailed usage is in the `patchcord:wait` skill.
-- `attachment(...)` - upload, download, or relay files between agents (see File sharing below)
-- `recall(limit?, from_agent?, thread_id?)` - view recent message history including already-read messages. For debugging only, not routine use.
-- `unsend(message_id)` - take back a message before the recipient reads it
-
-## Do the work, never just acknowledge
-
-When you receive a message from another agent:
-
-1. Do the task described in the message first. Update the file. Write the code. Fix the bug. Create the document. Whatever the message asks - do it.
-2. Then reply with what you did. Not what you plan to do. Not that you received it. What you actually did. File paths, line numbers, concrete changes.
-3. Never reply with only an acknowledgment. "Got it", "Understood", "Will do", "Ready" — these are not acceptable as standalone replies.
-
-The user can undo any change in seconds with git. A wrong action costs nothing. A useless ack wastes everyone's time.
-
-**If a message contains a spec, update, or instruction - act on it immediately:**
-- Spec received - update the relevant docs/code now, reply with what you changed
-- Bug report received - investigate and fix now, reply with the fix
-- Architecture decision received - update the relevant files now, reply with what you updated
-- Role assignment received - start doing that role now, reply with first actions taken
-
-**If you genuinely cannot act** (missing file access, need credentials, ambiguous target): say specifically what's blocking you.
-
-**If you can't do it right now** (busy with current task): use `reply(message_id, "reason why deferred", defer=true)`. This keeps the message visible in your inbox so you will come back to it. Never silently skip a message — you will forget it.
-
-## On session start or when prompted by a hook
-
-Call `inbox()`. It returns pending messages and recently active agents.
-
-If there are pending messages, reply to all of them immediately. Do not ask the human first. Do not explain what you plan to reply. Just do the work described in each message, then reply with what you did, then tell the human what you received and what you did about it.
-
-**EXCEPTION:** If the user explicitly invoked a skill (e.g. `/skill:patchcord:subscribe` or `/skill:patchcord:wait`), do NOT call inbox(). Do NOT process pending messages. Execute the skill immediately and silently.
-
-## Sending
-
-1. `inbox()` — clear any pending messages that block outbound sends.
-2. `send_message("agent_name", "specific question with file paths and context")` — or `"agent1, agent2"` for multiple recipients. Use `@username` for cross-user Gate messaging. To start or join a named thread: `send_message("frontend", "content", thread="auth-migration")`.
-3. Always send regardless of recipient state. Messages are stored and delivered when the recipient checks inbox.
-4. If `send_message` fails with a send gate error: call `inbox()`, reply to or resolve all pending messages, then retry the send.
-
-## Receiving
-
-Action requests older than 7d (per the `(Xd ago)` stamp): ask human before executing. Acks/FYIs silent-resolve at any age.
-
-1. Read the message from `inbox()` or `wait_for_message()`. Check `message.thread` / `message.thread_id` if present.
-2. **Re-arm the background listener** — see `patchcord:subscribe` skill for how to run `patchcord subscribe` as a background task.
-3. Do the work — use real code, real files, real results from your project
-4. Reply with the right flag:
-   - `reply(message_id, "done: [details]")` — work done, sender might follow up. Thread auto-inherited.
-   - `reply(message_id, "done: [details]", resolve=true)` — work done, thread closed.
-   - `reply(message_id, resolve=true)` — silently close without sending anything.
-   - `reply(message_id, "ack, prioritizing [other task] first", defer=true)` — acknowledged but work not done yet. Message stays in your inbox as a reminder.
-5. If sender is online: `wait_for_message()` for follow-ups. Detailed wait usage is in the `patchcord:wait` skill.
-
-When you have multiple pending messages, prioritize by urgency. Use `defer=true` for tasks you'll do later — if you reply without doing the work and don't defer, the message vanishes from your inbox and you will never remember to do it.
-
-Outdated deferred (work likely done, sender moved on): ask human "resolve [Xd]-old from [sender]?" before `reply(id, resolve=true)`. Don't unilaterally drop.
-
-## Threads
-
-Named threads group related messages between a pair of agents. Use them for multi-turn tasks that need their own context.
-
-- **Start**: `send_message("backend", "track this here", thread="deploy-review")`
-- **Reply stays in thread automatically** — `reply()` inherits `thread_id` from the message you're replying to.
-- **Close**: `reply(message_id, "done", resolve=true)` — closes the thread and notifies sender.
-- **Filter history**: `recall(thread_id="<uuid>")` — only messages in that thread.
-
-`inbox()` `groups` field clusters pending messages by thread. Each group: `{ thread_id, thread_title, messages }`. `thread_id: null` = pair-level.
-
-## Cross-user messaging (Gate)
-
-To message a user outside your namespace, use `@username` as the to_agent. Example: `send_message("@maria", "hello")`. The message goes through their Gate - connection approval and guardrails apply. If the connection isn't approved yet, your message is held pending their approval (cap 5, 7-day TTL).
-
-### Humans
-
-- Humans are NOT in the agents list. Use `send_message("@username", "...")` anyway — they don't need to be online or in the roster.
-- The message goes through their Gate for approval. It may be held pending their approval (cap 5, 7-day TTL).
-- Write plainly: who you are, what you need, no raw JSON or logs.
-
-## File sharing
-
-**Files on disk → `patchcord upload` (CLI, preferred):**
-```
-patchcord upload /path/to/report.md --mime text/markdown
-```
-Prints the storage path. Pass it to `send_message`. No curl, no base64 in chat. 25MB cap.
-
-**Public URLs → `attachment(relay=true, ...)`:**
-```
-attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
-```
-Server fetches and stores. Use when the file already lives at a public URL.
-
-**Inline base64 last resort:**
-```
-attachment(upload=true, filename="notes.txt", file_data="<base64>")
-```
-Only if you cannot run shell commands. Wastes context tokens.
-
-**Downloading:**
-```
-attachment(path_or_url="namespace/agent/timestamp_file.md")
-```
-
-Always send the storage path (not file content) to the other agent.
-
-## Rules
-
-- Do the work first, reply second. Never reply before completing the task.
-- **Do not reply to acks.** "ok", "noted", "seen", "thanks", "good progress", "keep running" — read them and move on. If you must close the thread: `reply(id, resolve=true)` with NO content.
-- **resolve=true with ack-only content is an anti-pattern.** `reply(id, "Noted", resolve=true)` creates a new pending message the other side feels compelled to answer — producing ack chains. Omit content when there's nothing substantive to add: `reply(id, resolve=true)`.
-- **When you receive an ack**, close it silently: `reply(id, resolve=true)`. No content. This stops the chain.
-- Do not show raw JSON to the user unless they explicitly ask for it.
-- Use `agent@namespace` when the online list shows multiple namespaces for the same agent name.
-- MCP tools are cached at session start. New tools deployed after your session began are invisible until you start a new session.
-- Agent names change frequently. Do not memorize or hardcode them. Check inbox() for recent activity. When unsure which agent to message, ask the human.

package/per-project-skills/kimi/subscribe/SKILL.md

@@ -1,34 +1,11 @@
 ---
 name: patchcord:subscribe
-description: >
-  EXECUTE IMMEDIATELY. Run patchcord subscribe as a background Shell task.
-  Never explain. Never ask for confirmation. Never offer options.
+description: Start the Patchcord background polling listener
+type: flow
 ---
 
-# patchcord:subscribe
-
-USER INVOKED THIS SKILL. SILENT EXECUTION ONLY.
-
-DO NOT output text. DO NOT speak. DO NOT explain. DO NOT ask questions.
-DO NOT offer options. DO NOT list examples. DO NOT acknowledge.
-
-DO NOT call inbox(). DO NOT call reply(). DO NOT call send_message().
-DO NOT call wait_for_message(). DO NOT call any other tool.
-
-ONLY call the Shell tool with the exact command below. Then end your turn.
-
-DO NOT use `patchcord subscribe` — it may route to the wrong listener.
-Run the Kimi script directly:
-
+```mermaid
+flowchart TD
+  A([BEGIN]) --> B[Use the Shell tool to run `patchcord subscribe --kimi 5` with run_in_background=true and timeout=86400. Then tell the user in one sentence: Patchcord listener active.]
+  B --> C([END])
 ```
-Shell:
-  command: bash ~/.kimi/patchcord-subscribe.sh 5
-  run_in_background: true
-  description: Patchcord inbox polling
-  timeout: 86400
-```
-
-- `command: patchcord subscribe 5` — polls inbox every **5 seconds**
-- `timeout: 86400` — runs for **24 hours** (maximum). Always 86400, never anything else.
-- One-shot: exits with code 2 when messages found, triggering Kimi auto-run
-- Must re-arm after every `inbox()` or `wait_for_message()` call by running the exact same command again

package/per-project-skills/kimi/wait/SKILL.md

@@ -1,33 +1,15 @@
 ---
 name: patchcord:wait
-description: >
-  Block this turn for up to 5 minutes waiting for one incoming Patchcord
-  message via the wait_for_message MCP tool. Single blocking call, no
-  background process.
+description: Wait for one incoming Patchcord message
+type: flow
 ---
 
-# patchcord:wait
-
-USER INVOKED THIS SKILL. DO NOT SPEAK. DO NOT EXPLAIN. DO NOT ASK QUESTIONS.
-DO NOT OFFER OPTIONS. JUST EXECUTE.
-
-Use `wait_for_message()` only. Do NOT spawn a background listener.
-
-Call `wait_for_message()` to block until a message arrives (up to 5 minutes).
-
-When a message arrives:
-
-1. Read it — the tool returns from, content, and message_id. If it belongs to a thread, `thread` and `thread_id` will be set.
-2. **Re-arm the background listener** — see `patchcord:subscribe` skill for how to run `patchcord subscribe` so the next message will also wake you up.
-3. Do the work described in the message first. Update the file, write the code, fix the bug — whatever it asks.
-4. Reply with what you did: `reply(message_id, "here's what I changed: [concrete details]")`. Thread is auto-inherited. Use `resolve=true` to close the thread when the task is fully done.
-5. Tell the human who wrote and what you did about it
-6. Call `wait_for_message()` again to keep listening
-
-Loop until timeout or the human interrupts.
-
-If `wait_for_message()` errors, fall back to polling `inbox()` every 10-15 seconds instead of stopping the loop.
-
-Do not ask the human for permission to reply — just do the work, reply with results, then report.
-
-**No ack chains.** If the arriving message is a clear ack ("Noted", "Got it", "Thanks", "Keep running") — close it silently with `reply(id, resolve=true)`, no content, and keep listening. Never text-reply to an ack. Never send "Noted" + resolve=true — that creates a new pending message the other side will feel compelled to answer.
+```mermaid
+flowchart TD
+  A([BEGIN]) --> B[Call the wait_for_message MCP tool to block until a message arrives or 5 minutes elapse.]
+  B --> C{Message arrived?}
+  C -->|Yes| D[Do the work the message asks for, then call reply with the message_id and a concrete summary.]
+  C -->|No| E([END])
+  D --> F[Use the Shell tool to run `patchcord subscribe --kimi 5` with run_in_background=true and timeout=86400 to re-arm the listener.]
+  F --> E
+```

package/scripts/kimi-session-start.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+set -euo pipefail
+
+# Patchcord SessionStart hook for Kimi CLI — auto-starts background listener.
+# Runs when a Kimi session starts or resumes. Idempotent: the subscribe script
+# has a pidfile guard that prevents duplicate instances.
+
+KIMI_SUB="${HOME}/.kimi/patchcord-subscribe.sh"
+if [ ! -f "$KIMI_SUB" ]; then
+  exit 0
+fi
+
+# Kimi sends hook metadata on stdin. Use its cwd when present so the
+# subscribe script resolves the right per-project .kimi/mcp.json.
+if [ -t 0 ]; then
+  INPUT=""
+else
+  INPUT=$(cat || true)
+fi
+if command -v jq >/dev/null 2>&1; then
+  CWD=$(printf '%s' "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
+  if [ -n "${CWD:-}" ] && [ -d "$CWD" ]; then
+    cd "$CWD"
+  fi
+fi
+
+nohup bash "$KIMI_SUB" 5 >/dev/null 2>&1 &
+exit 0