@ai-setting/roy-task-plugin 0.7.6 → 0.7.8

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

@@ -34,6 +34,30 @@ Create the task **before** doing the work. Pass:
 - `project_path`, `context` (JSON string: worktree_path / branch / type …)
 - `parent_task_id` when the tree said so
 
+#### ⚠️ Goals must be numbered sub-items
+`goals_and_expected_deliverables` **MUST** be written as **numbered
+sub-items** (编号子项) that can each be verified **one by one**
+(逐条验收) — for `type=normal` tasks:
+
+  1. 实现 X（含文件路径）
+  2. 测试 Y 覆盖 Z 场景（pass/fail 计数）
+  3. 文档 W 落盘到 <path>
+
+Why: the completion hook judges the goal **item by item** against the
+operation-record chain, using each sub-item as fine-grained evidence. A
+vague one-line goal (一句话模糊目标，如「做好 X」「完成调研」) gives the
+judge nothing to check and reliably triggers a completion hint.
+
+Reference the four atomic assertion forms when writing each sub-item:
+- **文件断言** (file assertion) — file exists / size / content grep
+- **进程断言** (process assertion) — command exit code / stdout match
+- **测试断言** (test assertion) — pass/fail counts, no NEW fail
+- **状态断言** (state assertion) — version number / HTTP 200 / status field
+
+For `type=longterm` / `type=cycle` tasks there is no per-item completion
+acceptance — for those, split goals into staged, individually checkable
+sub-items instead of one vague sentence.
+
 The tool returns a **numeric task id** — that number is your handle for the
 rest of the conversation.
 
@@ -68,12 +92,32 @@ transitions*: RED→GREEN, blocker found, decision made, review passed.
 ### 5. Close — `task_complete`
 Before completing:
 1. `task_get(task_id)` and re-read goal + delivery.
-2. Verify the goal and delivery actually match what you delivered. If they do
-   not, either extend the task (`task_update`) or say so honestly.
+2. **Accept the goal item-by-item** (按子项逐条验收): check **each** numbered
+   sub-item against the operation-record chain and the deliverable evidence.
+   If a sub-item is not met, either extend the task (`task_update`) or say
+   so honestly.
 3. Call `task_complete` with `deliverable_storage_path` — a locator for the
    work product: a file path, a git branch/worktree, a doc URL, a commit URL.
    The path is persisted into the task context and as an operation record.
 
+#### ⚠️ The completion hint is a verify duty, not a notification
+If the task context carries a `[TASK_COMPLETION_HINT]`, you **MUST** verify
+it (核实义务) — never ignore it (不允许无视). Re-read the task via
+`task_get`, then do **exactly one** of:
+- (a) the goal is **not** met → `task_update(task_id=<id>, status=todo)` to
+  reopen and continue the work; or
+- (b) the goal **is** met → `task_operation_create`
+  (milestone_type=decision) stating why the sub-items are actually met
+  (说明理由 — "state why").
+
+#### Several deliverables in one field
+`deliverable_storage_path` may name **multiple paths**, space-separated
+(`/tmp/report.md /tmp/diff.patch`) — the judge splits on whitespace as well
+as `,` `;` `、` and ` + `. A local path may also be written in its
+`file://` form (`file:///tmp/report.md`) — the scheme is stripped and the
+path kept. Declare **every** artefact you produced: a path left out reads as
+"not produced" and drags the task toward a false completion hint.
+
 `task_complete` cannot be used on `cycle` tasks (they are periodic by
 design) — use `task_update` to reset those.
 
@@ -94,6 +138,12 @@ configured with `persistence: "remote"`). Do not create side databases, do
 not maintain your own to-do list in files, and do not track work in chat only:
 if it is not in the task store, it is not tracked.
 
+## Style
+
+- Be direct and concrete; the user is reading task titles and milestones.
+- Report the task id and its state whenever you finish a step.
+- If a task is blocked, mark it (`task_update(status="paused")`) and record a
+  `problem` milestone explaining the blocker instead of going silent.
 ## Tool surface on Claude Code
 
 The `task_*` tools are served by the **`roy-task` MCP server** this runtime
@@ -118,10 +168,3 @@ 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
-
-- Be direct and concrete; the user is reading task titles and milestones.
-- Report the task id and its state whenever you finish a step.
-- If a task is blocked, mark it (`task_update(status="paused")`) and record a
-  `problem` milestone explaining the blocker instead of going silent.

package/dist/cli.js

@@ -444,33 +444,8 @@ class NdjsonAssembler {
   }
 }
 
-// ../../../packages/cli/src/daemon/runners/claude-agents.ts
-var CLAUDE_ROY_AGENT_NAME = "roy";
-var ROY_AGENT_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.";
-var ROY_TASK_MCP_SERVER = "roy-task";
-var ROY_TASK_MCP_TOOLS = Object.freeze([
-  "task_create",
-  "task_update",
-  "task_operation_create",
-  "task_complete",
-  "task_get",
-  "task_list",
-  "task_tree",
-  "task_search"
-].map((t) => `mcp__${ROY_TASK_MCP_SERVER}__${t}`));
-var CLAUDE_ROY_TOOLS = Object.freeze([
-  "Read",
-  "Write",
-  "Edit",
-  "Bash",
-  "Grep",
-  "Glob",
-  "TodoWrite",
-  "WebFetch",
-  "WebSearch",
-  ...ROY_TASK_MCP_TOOLS
-]);
-var CLAUDE_ROY_SYSTEM_PROMPT = `# Roy — task-first-class-citizen agent
+// ../agent/src/roy-prompt-core.ts
+var ROY_PROMPT_COMMON = `# Roy — task-first-class-citizen agent
 
 You are **Roy**, an agent whose defining rule is simple:
 
@@ -499,6 +474,30 @@ Create the task **before** doing the work. Pass:
 - \`project_path\`, \`context\` (JSON string: worktree_path / branch / type …)
 - \`parent_task_id\` when the tree said so
 
+#### ⚠️ Goals must be numbered sub-items
+\`goals_and_expected_deliverables\` **MUST** be written as **numbered
+sub-items** (编号子项) that can each be verified **one by one**
+(逐条验收) — for \`type=normal\` tasks:
+
+  1. 实现 X（含文件路径）
+  2. 测试 Y 覆盖 Z 场景（pass/fail 计数）
+  3. 文档 W 落盘到 <path>
+
+Why: the completion hook judges the goal **item by item** against the
+operation-record chain, using each sub-item as fine-grained evidence. A
+vague one-line goal (一句话模糊目标，如「做好 X」「完成调研」) gives the
+judge nothing to check and reliably triggers a completion hint.
+
+Reference the four atomic assertion forms when writing each sub-item:
+- **文件断言** (file assertion) — file exists / size / content grep
+- **进程断言** (process assertion) — command exit code / stdout match
+- **测试断言** (test assertion) — pass/fail counts, no NEW fail
+- **状态断言** (state assertion) — version number / HTTP 200 / status field
+
+For \`type=longterm\` / \`type=cycle\` tasks there is no per-item completion
+acceptance — for those, split goals into staged, individually checkable
+sub-items instead of one vague sentence.
+
 The tool returns a **numeric task id** — that number is your handle for the
 rest of the conversation.
 
@@ -533,12 +532,32 @@ transitions*: RED→GREEN, blocker found, decision made, review passed.
 ### 5. Close — \`task_complete\`
 Before completing:
 1. \`task_get(task_id)\` and re-read goal + delivery.
-2. Verify the goal and delivery actually match what you delivered. If they do
-   not, either extend the task (\`task_update\`) or say so honestly.
+2. **Accept the goal item-by-item** (按子项逐条验收): check **each** numbered
+   sub-item against the operation-record chain and the deliverable evidence.
+   If a sub-item is not met, either extend the task (\`task_update\`) or say
+   so honestly.
 3. Call \`task_complete\` with \`deliverable_storage_path\` — a locator for the
    work product: a file path, a git branch/worktree, a doc URL, a commit URL.
    The path is persisted into the task context and as an operation record.
 
+#### ⚠️ The completion hint is a verify duty, not a notification
+If the task context carries a \`[TASK_COMPLETION_HINT]\`, you **MUST** verify
+it (核实义务) — never ignore it (不允许无视). Re-read the task via
+\`task_get\`, then do **exactly one** of:
+- (a) the goal is **not** met → \`task_update(task_id=<id>, status=todo)\` to
+  reopen and continue the work; or
+- (b) the goal **is** met → \`task_operation_create\`
+  (milestone_type=decision) stating why the sub-items are actually met
+  (说明理由 — "state why").
+
+#### Several deliverables in one field
+\`deliverable_storage_path\` may name **multiple paths**, space-separated
+(\`/tmp/report.md /tmp/diff.patch\`) — the judge splits on whitespace as well
+as \`,\` \`;\` \`、\` and \` + \`. A local path may also be written in its
+\`file://\` form (\`file:///tmp/report.md\`) — the scheme is stripped and the
+path kept. Declare **every** artefact you produced: a path left out reads as
+"not produced" and drags the task toward a false completion hint.
+
 \`task_complete\` cannot be used on \`cycle\` tasks (they are periodic by
 design) — use \`task_update\` to reset those.
 
@@ -559,6 +578,13 @@ configured with \`persistence: "remote"\`). Do not create side databases, do
 not maintain your own to-do list in files, and do not track work in chat only:
 if it is not in the task store, it is not tracked.
 
+## Style
+
+- Be direct and concrete; the user is reading task titles and milestones.
+- Report the task id and its state whenever you finish a step.
+- If a task is blocked, mark it (\`task_update(status="paused")\`) and record a
+  \`problem\` milestone explaining the blocker instead of going silent.`;
+var ROY_PROMPT_CLAUDE_TAIL = `
 ## Tool surface on Claude Code
 
 The \`task_*\` tools are served by the **\`roy-task\` MCP server** this runtime
@@ -582,14 +608,35 @@ progress card renders the task these tools create.
 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.
+instead of silently skipping the lifecycle.`;
 
-## Style
-
-- Be direct and concrete; the user is reading task titles and milestones.
-- Report the task id and its state whenever you finish a step.
-- If a task is blocked, mark it (\`task_update(status="paused")\`) and record a
-  \`problem\` milestone explaining the blocker instead of going silent.`;
+// ../../../packages/cli/src/daemon/runners/claude-agents.ts
+var CLAUDE_ROY_AGENT_NAME = "roy";
+var ROY_AGENT_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.";
+var ROY_TASK_MCP_SERVER = "roy-task";
+var ROY_TASK_MCP_TOOLS = Object.freeze([
+  "task_create",
+  "task_update",
+  "task_operation_create",
+  "task_complete",
+  "task_get",
+  "task_list",
+  "task_tree",
+  "task_search"
+].map((t) => `mcp__${ROY_TASK_MCP_SERVER}__${t}`));
+var CLAUDE_ROY_TOOLS = Object.freeze([
+  "Read",
+  "Write",
+  "Edit",
+  "Bash",
+  "Grep",
+  "Glob",
+  "TodoWrite",
+  "WebFetch",
+  "WebSearch",
+  ...ROY_TASK_MCP_TOOLS
+]);
+var CLAUDE_ROY_SYSTEM_PROMPT = ROY_PROMPT_COMMON + ROY_PROMPT_CLAUDE_TAIL;
 function buildClaudeAgentsJson(opts = {}) {
   const def = {
     description: opts.description ?? ROY_AGENT_DESCRIPTION,
@@ -961,13 +1008,17 @@ function resolveClaudePluginDir(roots, explicit) {
   }
   return;
 }
-function buildRoyTaskMcpConfig(pluginDir) {
+function buildRoyTaskMcpConfig(pluginDir, env) {
+  const server = {
+    command: process.execPath,
+    args: [join(pluginDir, "mcp", "roy-task-mcp-server.mjs")]
+  };
+  const clean = env ? Object.fromEntries(Object.entries(env).filter(([, v]) => v !== undefined && v !== "")) : {};
+  if (Object.keys(clean).length > 0)
+    server.env = clean;
   return JSON.stringify({
     mcpServers: {
-      "roy-task": {
-        command: process.execPath,
-        args: [join(pluginDir, "mcp", "roy-task-mcp-server.mjs")]
-      }
+      "roy-task": server
     }
   });
 }
@@ -995,8 +1046,8 @@ function makeClaudeRunner(opts = {}) {
   const agentsJson = opts.agentsJson ?? buildClaudeAgentsJson();
   const sessions = opts.sessions ?? createClaudeSessionRegistry();
   const pluginDir = opts.pluginDir ?? resolveClaudePluginDir([dirname(fileURLToPath(import.meta.url))]);
-  const mcpConfig = pluginDir ? buildRoyTaskMcpConfig(pluginDir) : undefined;
   return async function runAgent(input) {
+    const mcpConfig = pluginDir ? buildRoyTaskMcpConfig(pluginDir, input.mcpEnv) : undefined;
     const known = input.sessionId ? sessions.get(input.sessionId) : undefined;
     const args = buildClaudeArgs({
       prompt: input.prompt,
@@ -1105,7 +1156,7 @@ var CODEX_SANDBOX_MODES = Object.freeze([
 function isCodexSandboxMode(value) {
   return CODEX_SANDBOX_MODES.includes(value);
 }
-function buildRoyTaskCodexConfigArgs(pluginDir) {
+function buildRoyTaskCodexConfigArgs(pluginDir, env) {
   const args = [
     `-cmcp_servers.${ROY_TASK_MCP_SERVER}.command=${JSON.stringify(process.execPath)}`,
     `-cmcp_servers.${ROY_TASK_MCP_SERVER}.args=${JSON.stringify([
@@ -1113,12 +1164,12 @@ function buildRoyTaskCodexConfigArgs(pluginDir) {
     ])}`,
     `-cmcp_servers.${ROY_TASK_MCP_SERVER}.default_tools_approval_mode="approve"`
   ];
-  const envArg = buildMcpServerEnvArg();
+  const envArg = buildMcpServerEnvArg(env);
   if (envArg)
     args.push(envArg);
   return args;
 }
-function buildMcpServerEnvArg() {
+function buildMcpServerEnvArg(env) {
   const keys = [
     "ROY_TASK_NOTIFY_ENABLED",
     "ROY_TASK_NOTIFY_CHAT_ID",
@@ -1126,7 +1177,8 @@ function buildMcpServerEnvArg() {
   ];
   const pairs = [];
   for (const key of keys) {
-    const value = process.env[key];
+    const fromEnv = env ? env[key] : undefined;
+    const value = fromEnv ?? (env ? undefined : process.env[key]);
     if (!value)
       continue;
     const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
@@ -1166,8 +1218,8 @@ function makeCodexRunner(opts = {}) {
   const sandbox = opts.sandbox ?? "read-only";
   const sessions = opts.sessions ?? createCodexSessionRegistry();
   const pluginDir = opts.pluginDir ?? resolveClaudePluginDir([dirname2(fileURLToPath2(import.meta.url))]);
-  const mcpConfigArgs = pluginDir ? buildRoyTaskCodexConfigArgs(pluginDir) : undefined;
   return async function runAgent(input) {
+    const mcpConfigArgs = pluginDir ? buildRoyTaskCodexConfigArgs(pluginDir, input.mcpEnv) : undefined;
     const known = input.sessionId ? sessions.get(input.sessionId) : undefined;
     const args = known ? buildCodexResumeArgs(known, { prompt: input.prompt, model, sandbox, mcpConfigArgs }) : buildCodexArgs({ prompt: input.prompt, model, sandbox, mcpConfigArgs });
     const decoder = new CodexStreamDecoder;
@@ -1754,6 +1806,94 @@ function withTimeout(op, promise, ms) {
     });
   });
 }
+var ledgerStores = new Map;
+var ledgerInFlight;
+function ledgerPathKey() {
+  return process.env.ROY_AGENT_LARK_CARD_DB ?? "";
+}
+async function loadLedger() {
+  const key = ledgerPathKey();
+  if (ledgerStores.has(key))
+    return ledgerStores.get(key);
+  if (!ledgerInFlight) {
+    ledgerInFlight = (async () => {
+      try {
+        const mod = await import("@ai-setting/roy-agent-core/env/task/plugins");
+        if (typeof mod.createLarkCardStateStore !== "function") {
+          return;
+        }
+        const store2 = mod.createLarkCardStateStore();
+        ledgerStores.set(key, store2);
+        return store2;
+      } catch {
+        return;
+      } finally {
+        ledgerInFlight = undefined;
+      }
+    })();
+  }
+  const store = await ledgerInFlight;
+  ledgerStores.set(key, store);
+  return store;
+}
+function taskIdOf(meta) {
+  const id = meta?.id;
+  return typeof id === "number" ? id : undefined;
+}
+async function adoptExistingCard(input) {
+  const taskId = taskIdOf(input.meta);
+  if (taskId === undefined)
+    return;
+  try {
+    const store = await loadLedger();
+    if (!store)
+      return;
+    const record = store.get(taskId);
+    if (!record || !record.messageId)
+      return;
+    if (record.status === "closed")
+      return;
+    if (record.chatId !== input.chatId)
+      return;
+    return { messageId: record.messageId, pinned: record.pinned };
+  } catch {
+    return;
+  }
+}
+async function recordCardInLedger(input, res) {
+  const taskId = taskIdOf(input.meta);
+  if (taskId === undefined || !res.messageId)
+    return;
+  try {
+    const store = await loadLedger();
+    if (!store)
+      return;
+    const existing = store.get(taskId);
+    const now = Date.now();
+    store.upsert({
+      taskId,
+      messageId: res.messageId,
+      chatId: input.chatId,
+      profile: input.profile,
+      pinned: res.pinned,
+      status: "open",
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now
+    });
+  } catch {}
+}
+async function closeCardInLedger(input) {
+  const taskId = taskIdOf(input.meta);
+  if (taskId === undefined)
+    return;
+  try {
+    const store = await loadLedger();
+    if (!store)
+      return;
+    store.markClosed(taskId);
+    store.markPinned(taskId, false);
+  } catch {}
+}
 function createRoyAgentCardPort(options = {}) {
   const opTimeoutMs = options.opTimeoutMs ?? CARD_OP_TIMEOUT_MS;
   let notifier;
@@ -1783,13 +1923,18 @@ function createRoyAgentCardPort(options = {}) {
   return {
     enabled: true,
     async start(input) {
+      const adopted = await adoptExistingCard(input);
+      if (adopted)
+        return adopted;
       const n = await withTimeout("load", getNotifier(), opTimeoutMs);
-      return withTimeout("start", n.startTask({
+      const res = await withTimeout("start", n.startTask({
         chatId: input.chatId,
         profile: input.profile,
         meta: input.meta,
         milestones: input.milestones
       }), opTimeoutMs);
+      await recordCardInLedger(input, res);
+      return res;
     },
     async update(input) {
       const n = await withTimeout("load", getNotifier(), opTimeoutMs);
@@ -1815,6 +1960,7 @@ function createRoyAgentCardPort(options = {}) {
         finalStep: input.finalStep,
         progress: input.progress
       }), opTimeoutMs);
+      await closeCardInLedger(input);
     }
   };
 }
@@ -1875,6 +2021,52 @@ function normaliseMcpToolName(tool) {
   return tool;
 }
 
+// ../../../packages/cli/src/daemon/mcp-notify.ts
+var MCP_NOTIFY_ENV_KEYS = [
+  "ROY_TASK_NOTIFY_ENABLED",
+  "ROY_TASK_NOTIFY_CHAT_ID",
+  "ROY_TASK_NOTIFY_PROFILE"
+];
+function buildMcpNotifyEnv(destination, options = {}) {
+  const env = {};
+  if (!destination.chatId)
+    return env;
+  const enabled = options.enabled ?? true;
+  if (enabled)
+    env["ROY_TASK_NOTIFY_ENABLED"] = "1";
+  env["ROY_TASK_NOTIFY_CHAT_ID"] = destination.chatId;
+  if (destination.profile)
+    env["ROY_TASK_NOTIFY_PROFILE"] = destination.profile;
+  return env;
+}
+function notifyEnvFromDispatch(plan, options = {}) {
+  return buildMcpNotifyEnv({ chatId: plan.chatId, profile: plan.profile }, options);
+}
+function mergeNotifyEnv(base, notify) {
+  const merged = { ...base };
+  for (const key of MCP_NOTIFY_ENV_KEYS) {
+    if (notify[key] !== undefined)
+      merged[key] = notify[key];
+    else
+      delete merged[key];
+  }
+  if (merged["ROY_TASK_NOTIFY_PROFILE"] === undefined) {
+    const profile = base["ROY_TASK_NOTIFY_PROFILE"];
+    if (profile !== undefined)
+      merged["ROY_TASK_NOTIFY_PROFILE"] = profile;
+  }
+  return merged;
+}
+function processNotifyEnv() {
+  const env = {};
+  for (const key of MCP_NOTIFY_ENV_KEYS) {
+    const value = process.env[key];
+    if (value)
+      env[key] = value;
+  }
+  return env;
+}
+
 // ../../../packages/cli/src/daemon/dispatcher.ts
 function cardReport(handle) {
   const out = {};
@@ -1950,10 +2142,12 @@ class Dispatcher {
   deps;
   opts;
   deduper;
+  notifyOptions;
   constructor(deps, opts = {}) {
     this.deps = deps;
     this.opts = opts;
     this.deduper = deps.deduper ?? new Deduper;
+    this.notifyOptions = opts.notify ?? {};
   }
   get dedup() {
     return this.deduper;
@@ -2001,7 +2195,8 @@ class Dispatcher {
         prompt: plan.prompt,
         agent: plan.agent,
         sessionId: plan.sessionId,
-        onProgress
+        onProgress,
+        mcpEnv: mergeNotifyEnv(processNotifyEnv(), notifyEnvFromDispatch({ chatId, profile }, this.notifyOptions))
       }), (r) => r.error);
       const card = earlyCard ? await earlyCard : await this.trace("dispatch.openCard", () => this.openCard({
         chatId,
@@ -2606,7 +2801,7 @@ function makeCursorRunner(opts = {}) {
   let workspaceDir = opts.workspaceDir;
   if (!workspaceDir && pluginDir) {
     try {
-      workspaceDir = createCursorWorkspace(pluginDir, opts.mcpEnv ?? collectMcpNotifyEnv());
+      workspaceDir = createCursorWorkspace(pluginDir, collectMcpNotifyEnv());
     } catch {
       workspaceDir = undefined;
     }
@@ -2617,18 +2812,18 @@ function makeCursorRunner(opts = {}) {
     process.once("SIGINT", cleanup);
     process.once("SIGTERM", cleanup);
   }
-  const refreshMcpConfig = () => {
+  const refreshMcpConfig = (env) => {
     if (!workspaceDir || !pluginDir)
       return;
     if (opts.workspaceDir)
       return;
     try {
-      writeCursorMcpConfig(workspaceDir, pluginDir, opts.mcpEnv ?? collectMcpNotifyEnv());
+      writeCursorMcpConfig(workspaceDir, pluginDir, env ?? opts.mcpEnv ?? collectMcpNotifyEnv());
     } catch {}
   };
   const addDirs = opts.addDirs ?? [process.cwd()];
   return async function runAgent(input) {
-    refreshMcpConfig();
+    refreshMcpConfig(input.mcpEnv);
     const known = input.sessionId ? sessions.get(input.sessionId) : undefined;
     const args = buildCursorArgs({
       prompt: input.prompt,
@@ -3270,7 +3465,7 @@ function formatStatus(report) {
 }
 
 // ../../../packages/cli/src/main.ts
-var VERSION = "0.7.6";
+var VERSION = "0.7.8";
 async function main(argv) {
   const parsed = parseArgs(argv);
   switch (parsed.command) {