@ai-setting/roy-task-plugin 0.7.2 → 0.7.3

package/dist/claude-plugin/agents/roy.md

@@ -1,7 +1,7 @@
 ---
 name: roy
 description: Roy — task-as-first-class-citizen agent. Uses the roy-agent task lifecycle (task_tree → task_create → task_update → task_operation_create → task_complete) so every piece of work is tracked in the local task store.
-tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, WebFetch, WebSearch
+tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite, WebFetch, WebSearch, mcp__roy-task__task_create, mcp__roy-task__task_update, mcp__roy-task__task_operation_create, mcp__roy-task__task_complete, mcp__roy-task__task_get, mcp__roy-task__task_list, mcp__roy-task__task_tree, mcp__roy-task__task_search
 model: inherit
 ---
 
@@ -89,23 +89,28 @@ if it is not in the task store, it is not tracked.
 
 ## Tool surface on Claude Code
 
-The lifecycle above is expressed through the `roy-agent tasks` CLI (run it with
-the `Bash` tool), because Claude Code does not yet expose the `task_*` tools
-natively. The mapping is 1:1 — same store, same ids, same semantics:
+The `task_*` tools are served by the **`roy-task` MCP server** this runtime
+loads. Call them directly:
 
-| lifecycle step | Claude Code command |
+| lifecycle step | tool |
 |---|---|
-| `task_tree(depth=1)` | `roy-agent tasks tree` |
-| `task_create` | `roy-agent tasks create "<title>" -d "<description>" -g "<goals>" -p high --project-path "<path>"` |
-| `task_update` | `roy-agent tasks update <id> --status active --progress 50 --current-status "…"` |
-| `task_operation_create` | `roy-agent tasks operations <id>` to read; record milestones via the CLI's update/ops surface |
-| `task_complete` | `roy-agent tasks complete <id> --deliverable "<path>"` |
-| `task_get` | `roy-agent tasks get <id>` |
-| `task_list` | `roy-agent tasks list` |
-| `task_search` | `roy-agent tasks search <keywords>` |
-
-Prefer `--json` (`-j`) when you need to parse ids. The task id printed by
-`create` is your handle for the rest of the turn.
+| `task_tree(depth=1)` | `mcp__roy-task__task_tree` |
+| `task_create` | `mcp__roy-task__task_create` |
+| `task_update` | `mcp__roy-task__task_update` |
+| `task_operation_create` | `mcp__roy-task__task_operation_create` |
+| `task_complete` | `mcp__roy-task__task_complete` |
+| `task_get` | `mcp__roy-task__task_get` |
+| `task_list` | `mcp__roy-task__task_list` |
+| `task_search` | `mcp__roy-task__task_search` |
+
+Same store, same ids, same semantics as the opencode tools — the daemon's
+progress card renders the task these tools create.
+
+⚠️ **Do not** shell out to the `roy-agent tasks` CLI as a substitute.
+Measured: it has no way to write a milestone (its `operations <id>` subcommand
+is a *reader*), and it targets a different database than this server. Use the
+MCP tools above; if they are genuinely unavailable, say so in your answer
+instead of silently skipping the lifecycle.
 
 ## Style
 

package/dist/claude-plugin/hooks/stop-check.mjs

@@ -176,7 +176,13 @@ async function main() {
 
   let backend;
   try {
-    const server = createServer(process.env.ROY_TASK_DB_PATH || defaultTaskDbPath());
+    // Task #4692: createServer is async (it loads core's hook modules before
+    // the first request can fire them). Without the await, `server` is a
+    // Promise and `server.backend` is undefined — the open-task check would
+    // silently degrade to "approve" and the Stop discipline would die.
+    const server = await createServer(
+      process.env.ROY_TASK_DB_PATH || defaultTaskDbPath(),
+    );
     // The server owns the store; the backend is what the hook needs.
     backend = server.backend;
   } catch (err) {

package/dist/claude-plugin/mcp/bridge.mjs

@@ -1,38 +1,16 @@
 /**
  * Bridge: roy's task store + roy's MCP server, wired together.
  *
- * ## What this file used to be
+ * A thin adapter (Task #4619): store location + binding to roy's
+ * semantics + transport. Every semantic decision lives in core, once.
+ * (Before #4619 this was 482 lines of raw SQL re-implementing roy.)
  *
- * Before Task #4619 this was a **second implementation** of roy's task
- * semantics: 482 lines that created its own `task` / `task_operation`
- * schema and implemented every tool as raw SQL — `taskTree` (BFS +
- * `pruneDepth`), `taskCreate`, `taskGet`, `taskList` (COUNT for `total`),
- * `taskUpdate`, `taskOperationCreate`, `taskComplete`, `taskSearch` — with
- * **zero** imports from `@ai-setting/roy-agent-core`.
+ * Task #4692 adds a fourth, opt-in responsibility: firing core's
+ * `LarkCliTaskNotifyHook` around each tool call (see
+ * `task-notify-hooks.mjs`) so `task_create` opens a Feishu card,
+ * `task_update` patches it, `task_complete` closes it.
  *
- * That was the same defect review #4371 found on the opencode side (an
- * 869-line `facade.ts`), except it hid inside a `.mjs` file, so the reviews
- * that counted TypeScript lines never saw it.
- *
- * ## What it is now
- *
- * A thin adapter with exactly three responsibilities:
- *
- * 1. **where** the store lives (roy-agent's own `tasks.db`, not the
- *    plugin's private one — otherwise Claude would create tasks the
- *    progress card can never see);
- * 2. **binding** that store to roy's semantics (`TaskStoreBackend` +
- *    `createSQLiteTaskPort`, both from core);
- * 3. **transport** — handing core's MCP server the bytes.
- *
- * Every semantic decision (tree shape, depth, `total`, deliverable
- * merging, milestone filtering, search filters) lives in core, once.
- *
- * ## Runtime
- *
- * Plain node (`#!/usr/bin/env node` in the server entry) — hence core's
- * `node:sqlite` support (no native `better-sqlite3` needed) and core's
- * `createCompatibleDatabase` compat shim.
+ * Plain node runtime — core's `node:sqlite` (no native better-sqlite3).
  */
 
 import { createTaskMcpServer } from "@ai-setting/roy-agent-core/env/task/mcp";
@@ -43,6 +21,7 @@ import {
 import { SQLiteTaskStore } from "@ai-setting/roy-agent-core/env/task/storage";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { createNotifyDispatcher } from "./task-notify-hooks.mjs";
 
 /** Raised when a tool call cannot be served. */
 export class BridgeError extends Error {
@@ -62,11 +41,15 @@ export function defaultTaskDbPath() {
 /**
  * Build the MCP server over roy's own task store.
  *
- * This is the whole "binding" the plugin does: core's `SQLiteTaskStore` →
- * core's `createSQLiteTaskPort` → core's `TaskStoreBackend` (the semantics)
- * → core's `createTaskMcpServer` (the transport-agnostic JSON-RPC surface).
+ * Task #4692: when `ROY_TASK_NOTIFY_ENABLED=1`, the same core hook the
+ * act pipeline uses is registered on `globalHookManager`, and every tool
+ * call runs inside the injected EnvContext — so `task_create` now opens
+ * a card in Feishu, `task_update` patches it, `task_complete` closes it.
+ *
+ * @param {string} dbPath task store path
+ * @param {{ cardNotifier?: object }} deps test seams (fake notifier)
  */
-export function createServer(dbPath = defaultTaskDbPath()) {
+export async function createServer(dbPath = defaultTaskDbPath(), deps = {}) {
   const store = new SQLiteTaskStore(dbPath);
   const backend = new TaskStoreBackend(createSQLiteTaskPort(store));
   const server = createTaskMcpServer(backend, {
@@ -74,10 +57,20 @@ export function createServer(dbPath = defaultTaskDbPath()) {
     version: "1.0.0",
     sessionId: process.env.ROY_TASK_SESSION_ID || "claude-mcp",
   });
+
+  // Task #4692: fire the task:after.* hooks around every tool call. The
+  // wiring lives in task-notify-hooks.mjs; core owns the hook itself.
+  const notify = await createNotifyDispatcher({ backend, deps });
+  const callToolWithHooks = async (name, args = {}) => {
+    const result = await server.callTool(name, args);
+    await notify.fire(name, args, result);
+    return result;
+  };
+
   // The hooks (stop-check) need the *backend*, not the MCP surface: they
   // ask "is there an open task?" — a task-semantics question, answered by
   // core's backend, not by the JSON-RPC layer.
-  return { ...server, backend, store };
+  return { ...server, backend, store, callTool: callToolWithHooks };
 }
 
 /**
@@ -93,6 +86,8 @@ export async function callTool(server, name, args = {}) {
     throw new BridgeError("tools/call requires a tool name");
   }
   try {
+    // Task #4692: `createServer` wraps callTool with the hook firing;
+    // a bare core server (no wrapper) still works.
     return await server.callTool(name, args);
   } catch (err) {
     if (err instanceof BridgeError) throw err;

package/dist/claude-plugin/mcp/roy-task-mcp-server.mjs

@@ -83,7 +83,11 @@ setStdoutStrictMode(true);
  * the same server answered perfectly over a hand-rolled pipe.
  */
 function send(message) {
-  process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+  return new Promise((resolve) => {
+    const ok = process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", ...message })}\n`);
+    if (ok) resolve();
+    else process.stdout.once("drain", resolve);
+  });
 }
 
 function sendResult(id, result) {
@@ -246,11 +250,14 @@ const SERVER_INFO = { name: SERVER_NAME, version: SERVER_VERSION };
 const SERVER_CAPABILITIES = { tools: { listChanged: false } };
 
 /** Read newline-delimited JSON-RPC from stdin and answer on stdout. */
-export function main() {
+export async function main() {
+  const pending = new Set();
   const dbPath = process.env.ROY_TASK_DB_PATH || defaultTaskDbPath();
   let server;
   try {
-    server = createServer(dbPath);
+    // Task #4692: createServer is async (it loads core's hook modules
+    // before the first request can fire them).
+    server = await createServer(dbPath);
   } catch (err) {
     process.stderr.write(
       `roy-task mcp server: cannot open task store at ${dbPath}: ${err && err.message}\n`,
@@ -277,9 +284,9 @@ export function main() {
       return;
     }
 
-    Promise.resolve(handleRequest(request, server))
-      .then((response) => {
-        if (response) send(response);
+    const done = Promise.resolve(handleRequest(request, server))
+      .then(async (response) => {
+        if (response) await send(response);
       })
       .catch((err) => {
         sendError(
@@ -288,9 +295,26 @@ export function main() {
           err && err.message ? err.message : String(err),
         );
       });
+    pending.add(done);
+    done.finally(() => pending.delete(done));
   });
 
-  rl.on("close", () => {
+  // Task #4666: stdin EOF must not race the last response out.
+  //
+  // `process.exit(0)` from a `close` handler runs while big tool
+  // responses (a 45 KB `task_list` over the real DB) are still in
+  // node's stdout buffer — the client then sees a truncated JSON
+  // line (measured: `Unterminated string ... at position 50539`).
+  // Wait for every in-flight request to finish writing *and* for
+  // stdout to drain before exiting.
+  rl.on("close", async () => {
+    while (pending.size > 0) {
+      await Promise.all([...pending]);
+    }
+    await new Promise((resolve) => {
+      if (process.stdout.writableLength === 0) resolve();
+      else process.stdout.once("drain", resolve);
+    });
     process.exit(0);
   });
 }

package/dist/claude-plugin/mcp/task-notify-hooks.mjs

@@ -0,0 +1,303 @@
+/**
+ * Task #4692 — the MCP server's task:after.* hook wiring.
+ *
+ * ## What this file is
+ *
+ * The "install core's Feishu card hooks into the MCP server
+ * process" half of the bridge. Kept in its own module so
+ * `bridge.mjs` stays a thin adapter (the < 140-line guard in
+ * `claude-bridge-thin.test.ts` pins that).
+ *
+ * Everything semantic lives in core: the hook
+ * (`LarkCliTaskNotifyHook`), the card renderer
+ * (`LarkCardPatchNotifier`), the card state store, the hook
+ * manager and the ALS EnvContext. This module only wires them —
+ * the user's architecture: "飞书插件机制就在roy-agent上，mcp server
+ * 就复用就好呀".
+ *
+ * ## The three pieces
+ *
+ * 1. **opt-in** — `notifyEnabled()`: off unless
+ *    `ROY_TASK_NOTIFY_ENABLED=1` (existing deployments see zero
+ *    change);
+ * 2. **destination** — `buildNotifyEnvContext()`: the hook reads
+ *    the card's chat from the ALS EnvContext
+ *    (`replyChannel.chatId/profile`), which is empty inside the
+ *    MCP server process, so it is injected from
+ *    `ROY_TASK_NOTIFY_CHAT_ID` / `ROY_TASK_NOTIFY_PROFILE` (env,
+ *    because the server inherits the daemon's env — no argv
+ *    changes, no TOML escaping);
+ * 3. **firing** — `hookPointsForTool()` + `buildHookData()`:
+ *    map a completed tool call to the hook point(s) it implies,
+ *    with context data shaped exactly like `TaskComponent`'s
+ *    (the hook reads `task` / `changes` / `operation`).
+ */
+
+/**
+ * Should the MCP server install the Feishu card hooks?
+ */
+export function notifyEnabled() {
+  const v = process.env.ROY_TASK_NOTIFY_ENABLED;
+  return v === "1" || v === "true";
+}
+
+/**
+ * The EnvContext the hooks read for the card's destination.
+ *
+ * When no chat id is configured the context carries no
+ * replyChannel and the hook falls back to the task's own
+ * per-task group (same rule as the act pipeline).
+ */
+export function buildNotifyEnvContext(contextMod) {
+  const chatId = process.env.ROY_TASK_NOTIFY_CHAT_ID;
+  const profile = process.env.ROY_TASK_NOTIFY_PROFILE;
+  return contextMod.createEnvContext({
+    envEvent: { source: "lark", type: "mcp-server" },
+    sourceId: "roy-task-mcp",
+    userId: "mcp-agent",
+    ...(chatId ? { replyChannel: { type: "lark", chatId, profile } } : {}),
+  });
+}
+
+/**
+ * Map a tool call to the hook point(s) it semantically completed.
+ */
+export function hookPointsForTool(name) {
+  switch (name) {
+    case "task_create":
+      return ["task:after.create"];
+    case "task_update":
+      return ["task:after.update"];
+    case "task_complete":
+      return ["task:after.complete"];
+    case "task_operation_create":
+      return ["task:operation:after.create"];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Install the core `LarkCliTaskNotifyHook` on the global hook manager.
+ *
+ * @returns the installed hook, or null when notify is disabled.
+ */
+export async function installTaskNotifyHooks({ hookMod, pluginsMod, cardNotifier }) {
+  if (!notifyEnabled()) return null;
+  const hook = pluginsMod.createLarkCliTaskNotifyHook({
+    ...(cardNotifier ? { cardNotifier } : {}),
+  });
+  for (const hp of [
+    "task:after.create",
+    "task:after.update",
+    "task:after.complete",
+    "task:operation:after.create",
+  ]) {
+    // Idempotent: a second createServer() in the same process must not
+    // stack another copy of the hook (DS CV MINOR-5). The hook manager
+    // keys hooks by name, so removing the previous one first keeps the
+    // registration count at exactly 1.
+    hookMod.globalHookManager.unregister(hp, hook.name);
+    hookMod.globalHookManager.register(hp, hook);
+  }
+  return hook;
+}
+
+/**
+ * How long the card hooks may take before the tool call stops waiting.
+ *
+ * The same deadline the daemon's own card port uses (15s): a stuck
+ * lark-cli (network hang, profile permission prompt) must never make an
+ * MCP tool call hang forever — the agent would see "the tool never
+ * returns" (DS CV MAJOR-4).
+ */
+const HOOK_DEADLINE_MS = 15_000;
+
+/** Resolve `promise`, or give up after `ms` (the caller swallows the rejection). */
+function withDeadline(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`hook deadline exceeded (${ms}ms)`)),
+        ms,
+      );
+      // Never keep the process alive for the timer.
+      if (typeof timer.unref === "function") timer.unref();
+    }),
+  ]);
+}
+
+/**
+ * Build the notifier that fires the task:after.* hooks around tool calls.
+ *
+ * Returns a no-op dispatcher when the notify env is unset, so the caller
+ * can always use one code path.
+ *
+ * @param {{ backend: object, deps: { cardNotifier?: object } }} input
+ */
+export async function createNotifyDispatcher({ backend, deps = {} }) {
+  if (!notifyEnabled()) {
+    return { fire: async () => {} };
+  }
+  const [hookMod, pluginsMod, contextMod] = await Promise.all([
+    import("@ai-setting/roy-agent-core/env/hook"),
+    import("@ai-setting/roy-agent-core/env/task/plugins"),
+    import("@ai-setting/roy-agent-core/env/context"),
+  ]);
+  const notifyHook = await installTaskNotifyHooks({
+    hookMod,
+    pluginsMod,
+    ...(deps.cardNotifier ? { cardNotifier: deps.cardNotifier } : {}),
+  });
+  const envCtx = buildNotifyEnvContext(contextMod);
+
+  /**
+   * Read the task the tool just touched, so the card shows the REAL
+   * fields (priority / type / project_path / goals) instead of values
+   * guessed from the call arguments (DS CV MAJOR-3).
+   */
+  const readTask = async (name, args, result) => {
+    const id =
+      name === "task_create"
+        ? taskIdFromResult(result)
+        : typeof args.id === "number"
+          ? args.id
+          : Number(args.task_id) || taskIdFromResult(result);
+    if (!id) return undefined;
+    try {
+      return (await backend.getTask(id)) ?? undefined;
+    } catch {
+      return undefined;
+    }
+  };
+
+  return {
+    async fire(name, args, result) {
+      const points = hookPointsForTool(name);
+      if (!notifyHook || !envCtx || points.length === 0) return;
+      try {
+        const task = await readTask(name, args, result);
+        await withDeadline(
+          contextMod.runWithEnvContextAsync(envCtx, async () => {
+            for (const hp of points) {
+              // globalHookManager.execute isolates hook errors
+              // (safeExecute), so a broken lark-cli can never fail
+              // the tool call.
+              await hookMod.globalHookManager.execute(
+                hp,
+                buildHookData(name, args, result, task),
+                {},
+              );
+            }
+          }),
+          HOOK_DEADLINE_MS,
+        );
+      } catch {
+        // Hook failure never breaks the tool call.
+      }
+    },
+  };
+}
+
+/** "Task created successfully: #42 - title" → 42. */
+export function taskIdFromResult(result) {
+  const m = typeof result === "string" ? /#(\d+)/.exec(result) : null;
+  return m ? Number(m[1]) : 0;
+}
+
+function str(v) {
+  return v === undefined || v === null ? "" : String(v);
+}
+
+function sessionId() {
+  return process.env.ROY_TASK_SESSION_ID || "claude-mcp";
+}
+
+/**
+ * Build the hook context data for a completed tool call.
+ *
+ * The card hook reads `task` / `changes` / `operation` from
+ * `ctx.data`; the tool result is a human string, so the data is
+ * rebuilt from the call's own arguments (the same values the
+ * backend just persisted).
+ */
+export function buildHookData(name, args, result, task) {
+  switch (name) {
+    case "task_create":
+      return {
+        // The REAL task, read back from the store (DS CV MAJOR-3: building
+        // it from the call arguments faked priority/type/project_path, and
+        // the card then showed those wrong values).
+        task: task ?? fallbackTask(taskIdFromResult(result), args),
+        sessionId: sessionId(),
+        tagService: undefined,
+      };
+    case "task_update":
+    case "task_complete": {
+      const changes =
+        name === "task_complete"
+          ? { status: "completed", progress: 100 }
+          : {
+              ...(args.status !== undefined ? { status: str(args.status) } : {}),
+              ...(args.progress !== undefined ? { progress: args.progress } : {}),
+              ...(args.current_status !== undefined
+                ? { current_status: str(args.current_status) }
+                : {}),
+              ...(args.title !== undefined ? { title: str(args.title) } : {}),
+              ...(args.description !== undefined
+                ? { description: str(args.description) }
+                : {}),
+            };
+      return {
+        task: task ?? fallbackTask(taskIdFromResult(result), args),
+        changes,
+        ...(name === "task_complete"
+          ? { terminalStatus: "completed", sessionId: sessionId() }
+          : {}),
+        tagService: undefined,
+      };
+    }
+    case "task_operation_create":
+      return {
+        operation: {
+          id: 0,
+          taskId: typeof args.task_id === "number" ? args.task_id : Number(args.task_id) || 0,
+          sessionId: sessionId(),
+          milestoneType: str(args.milestone_type ?? args.action_type ?? "progress"),
+          milestoneTitle: str(args.milestone_title ?? args.action_title ?? ""),
+          milestoneDescription: str(args.milestone_description ?? args.action_description ?? ""),
+          processDescription: str(args.process_description ?? ""),
+          timestamp: new Date().toISOString(),
+        },
+      };
+    default:
+      return {};
+  }
+}
+
+/**
+ * The last-resort task shape, used only when the store could not be read.
+ *
+ * Every field is left empty rather than faked: core's `mergeTaskMeta`
+ * skips empty strings, so an empty field keeps the card's original value
+ * instead of overwriting it with a lie (DS CV MAJOR-3).
+ */
+function fallbackTask(id, args) {
+  return {
+    id,
+    title: str(args.title ?? ""),
+    description: "",
+    status: "",
+    priority: "",
+    type: "",
+    progress: 0,
+    current_status: "",
+    goals_and_expected_deliverables: "",
+    parent_task_id: args.parent_task_id,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    project_path: "",
+    context: str(args.context),
+  };
+}