@costgate/momentum-mcp 0.1.35 → 0.1.37

package/README.md

@@ -9,7 +9,7 @@ MOMENTUM_TOKEN=mom_agent_xxx \
 ```
 
 整条命令不用自己拼 —— 在 Momentum 的「设置 › Agent」里签发令牌时会直接给出，
-默认用 `@latest`，发新版不用改配置；想固定某一版时把 latest 换成版本号（当前是 0.1.35）。
+默认用 `@latest`，发新版不用改配置；想固定某一版时把 latest 换成版本号（当前是 0.1.37）。
 
 | 环境变量 | 必填 | 说明 |
 |---|---|---|
@@ -18,4 +18,4 @@ MOMENTUM_TOKEN=mom_agent_xxx \
 | `MOMENTUM_CF_ACCESS_CLIENT_ID` | 否 | 部署在 Cloudflare Access 后面时才需要 |
 | `MOMENTUM_CF_ACCESS_CLIENT_SECRET` | 否 | 同上 |
 
-版本 0.1.35。客户端和服务端版本不一致时，启动日志（stderr）会明确警告。
+版本 0.1.37。客户端和服务端版本不一致时，启动日志（stderr）会明确警告。

package/momentum-mcp.mjs

@@ -15339,7 +15339,7 @@ var allowErrorProps = SuperJSON.allowErrorProps;
 
 // src/version.ts
 var UNKNOWN = "unknown";
-var MCP_VERSION = true ? "0.1.35" : versionFromRepo();
+var MCP_VERSION = true ? "0.1.37" : versionFromRepo();
 var CLIENT_HEADER = `momentum-mcp/${MCP_VERSION}`;
 function compareVersions(a, b) {
   const parse4 = (v) => {
@@ -23877,7 +23877,100 @@ function defineTool(tool) {
 var text = (body) => ({
   content: [{ type: "text", text: body }]
 });
-var json = (value) => text(JSON.stringify(value));
+var json = (value) => {
+  const body = JSON.stringify(value);
+  const plain = JSON.parse(body);
+  return {
+    ...text(body),
+    structuredContent: plain !== null && typeof plain === "object" && !Array.isArray(plain) ? plain : { items: plain }
+  };
+};
+var TASK_PATH = (key) => `/t/${key}`;
+var APPROVALS_PATH = "/review";
+var LINKS_SCHEMA = external_exports.record(external_exports.string());
+var WRITE_OUTPUT = external_exports.object({
+  status: external_exports.enum(["executed", "pending_approval", "unchanged"]),
+  message: external_exports.string(),
+  proposalId: external_exports.string().optional(),
+  links: LINKS_SCHEMA.optional()
+}).passthrough();
+var STEP_SCHEMA = external_exports.object({ status: external_exports.enum(["executed", "pending_approval", "failed", "skipped"]), message: external_exports.string() }).passthrough();
+var FINISH_OUTPUT = external_exports.object({
+  status: external_exports.enum(["executed", "pending_approval", "partial"]),
+  message: external_exports.string(),
+  steps: external_exports.record(STEP_SCHEMA),
+  links: LINKS_SCHEMA.optional()
+}).passthrough();
+var TASK_FIELDS = { key: external_exports.string(), title: external_exports.string() };
+var CONTEXT_SCHEMA = external_exports.object({
+  ...TASK_FIELDS,
+  status: external_exports.object({ name: external_exports.string(), category: external_exports.string() }).passthrough(),
+  links: LINKS_SCHEMA.optional()
+}).passthrough();
+var BEGIN_OUTPUT = external_exports.object({
+  status: external_exports.enum(["executed", "pending_approval"]),
+  runId: external_exports.string().optional(),
+  claim: external_exports.object({ status: external_exports.string() }).passthrough().optional(),
+  context: CONTEXT_SCHEMA.optional(),
+  proposalId: external_exports.string().optional()
+}).passthrough();
+var PAGE_OUTPUT = external_exports.object({ items: external_exports.array(external_exports.unknown()) }).passthrough();
+var TASKS_OUTPUT = external_exports.object({ items: external_exports.array(external_exports.object(TASK_FIELDS).passthrough()) }).passthrough();
+var BROWSE_OUTCOME = external_exports.enum(["ok", "no_projects", "no_match", "project_unavailable", "failed"]);
+var BROWSE_OUTPUT = external_exports.object({
+  outcome: BROWSE_OUTCOME,
+  message: external_exports.string(),
+  items: external_exports.array(external_exports.unknown()),
+  nextOffset: external_exports.number().nullable()
+}).passthrough();
+var READ = { readOnlyHint: true, openWorldHint: false };
+var write = (destructiveHint, idempotentHint) => ({
+  readOnlyHint: false,
+  destructiveHint,
+  idempotentHint
+});
+var TOOL_META = {
+  // 只读查询 —— 客户端不该为它们弹确认
+  get_task_context: { annotations: READ, outputSchema: CONTEXT_SCHEMA },
+  get_task: { annotations: READ, outputSchema: CONTEXT_SCHEMA },
+  get_task_spec: { annotations: READ },
+  list_tasks: { annotations: READ, outputSchema: TASKS_OUTPUT },
+  browse_tasks: { annotations: READ, outputSchema: BROWSE_OUTPUT },
+  list_ready_tasks: { annotations: READ, outputSchema: TASKS_OUTPUT },
+  list_projects: { annotations: READ, outputSchema: PAGE_OUTPUT },
+  list_task_comments: { annotations: READ, outputSchema: PAGE_OUTPUT },
+  list_task_deliveries: { annotations: READ, outputSchema: PAGE_OUTPUT },
+  poll_events: { annotations: READ, outputSchema: PAGE_OUTPUT },
+  current_cycle: { annotations: READ },
+  whoami: { annotations: READ },
+  // 开工 / 收尾：重复调用沿用同一次运行、交付按 idempotency_key 去重
+  begin_task: { annotations: write(false, true), outputSchema: BEGIN_OUTPUT },
+  finish_task_work: { annotations: write(false, true), outputSchema: FINISH_OUTPUT },
+  // 追加型的写
+  create_task: { annotations: write(false, false), outputSchema: WRITE_OUTPUT },
+  comment_on_task: { annotations: write(false, false) },
+  ask_question: { annotations: write(false, false) },
+  answer_question: { annotations: write(false, false) },
+  add_task_relation: { annotations: write(false, false) },
+  update_task: { annotations: write(false, false) },
+  propose_digest: { annotations: write(false, false) },
+  submit_delivery: { annotations: write(false, true), outputSchema: WRITE_OUTPUT },
+  review_delivery: { annotations: write(false, false), outputSchema: WRITE_OUTPUT },
+  confirm_delivery: { annotations: write(false, false) },
+  start_run: { annotations: write(false, false) },
+  finish_run: { annotations: write(false, false) },
+  heartbeat_run: { annotations: write(false, true) },
+  claim_task: { annotations: write(false, true), outputSchema: WRITE_OUTPUT },
+  claim_next_task: { annotations: write(false, false), outputSchema: WRITE_OUTPUT },
+  // 改状态、挪位置、放手：改的是当前值，历史在事件流里留着
+  update_task_status: { annotations: write(false, true), outputSchema: WRITE_OUTPUT },
+  release_task: { annotations: write(false, false), outputSchema: WRITE_OUTPUT },
+  set_task_parent: { annotations: write(false, true) },
+  plan_task: { annotations: write(false, true) },
+  // 覆盖或删除已有内容：notes / refs 整份替换，关系直接移除
+  update_task_plan: { annotations: write(true, true) },
+  remove_task_relation: { annotations: write(true, false) }
+};
 var RECEIPT_KEYS = [
   "id",
   "key",
@@ -23915,30 +24008,28 @@ function compactReceipt(value) {
   );
   return Object.keys(receipt).length > 0 ? receipt : { ok: true };
 }
-function reportWrite(done, res) {
-  if (res.status === "proposed") {
-    return text(
-      [
-        `\u23F8 \u8FD9\u4E2A\u52A8\u4F5C\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C**\u5C1A\u672A\u751F\u6548**\u3002`,
-        `\u5DF2\u63D0\u4EA4\u63D0\u6848 ${res.proposalId}\uFF1A${res.summary}`,
-        `\u56E2\u961F\u6210\u5458\u5728 Momentum \u7684\u8BC4\u5BA1\u961F\u5217\u91CC\u63A5\u53D7\u4E4B\u540E\u624D\u4F1A\u771F\u6B63\u6267\u884C\u3002\u522B\u5047\u8BBE\u5B83\u5DF2\u7ECF\u5B8C\u6210\u3002`
-      ].join("\n")
-    );
-  }
-  return text(`\u2713 ${done}
-
-${JSON.stringify(compactReceipt(res.result))}`);
-}
+var unchanged = (message) => ({
+  ...text(message),
+  structuredContent: { status: "unchanged", message }
+});
 var RELATION_KIND = external_exports.enum(["blocks", "blocked_by", "relates", "duplicates"]);
 var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function matchStatus(candidates, wanted) {
   const needle = wanted.trim().toLowerCase();
   return candidates.find((s) => s.id === wanted) ?? candidates.find((s) => s.name.toLowerCase() === needle) ?? candidates.find((s) => s.category === needle) ?? candidates.find((s) => s.name.toLowerCase().includes(needle));
 }
+var NO_PROJECTS_MESSAGE = "\u8FD9\u4E2A Agent \u4E00\u4E2A\u9879\u76EE\u90FD\u8BBF\u95EE\u4E0D\u5230\u3002\u8BA9\u7BA1\u7406\u5458\u5728 Momentum \u7684 Agents \u9875\u52FE\u4E0A\u300C\u53EF\u8BBF\u95EE\u9879\u76EE\u300D\u6216\u6574\u4E2A Sector\uFF1B\u7528 whoami \u53EF\u4EE5\u770B\u5230\u5F53\u524D\u7684 grants.projects / grants.sectors\u3002";
+var BROWSE_DEFAULT_LIMIT = 20;
+var BROWSE_MAX_LIMIT = 50;
+var BROWSE_MAX_PROJECTS = 50;
+var STATUS_CATEGORIES = ["backlog", "unstarted", "started", "blocked", "review", "done", "canceled"];
 var WORK_TOOL_NAMES = /* @__PURE__ */ new Set([
   "begin_task",
   "finish_task_work",
   "get_task_context",
+  // 不知道任务编号时找活的入口（IMMO-221）：只读、有界、只回摘要。list_projects / list_tasks
+  // 仍在 full 档 —— 它们的 schema 更大，项目列表还带整段描述和冲刺配置
+  "browse_tasks",
   "get_task_spec",
   "list_task_comments",
   "list_task_deliveries",
@@ -23968,6 +24059,41 @@ function createTools(client, profile = "full", options = {}) {
   const meters = new RunMeters();
   const reported = options.hostReports ?? new HostReports(options.log);
   const readUsage = options.readUsage ?? hostUsageReader(process.env, { log: options.log, reported });
+  const appUrl = (options.appUrl ?? "").replace(/\/+$/, "");
+  function linksFor(taskKey, pending = false) {
+    return {
+      ...taskKey ? { task: `${appUrl}${TASK_PATH(taskKey)}` } : {},
+      ...pending ? { approvals: `${appUrl}${APPROVALS_PATH}` } : {}
+    };
+  }
+  function reportWrite(done, res, taskKey) {
+    if (res.status === "proposed") {
+      const links = linksFor(taskKey, true);
+      const message = [
+        `\u23F8 \u8FD9\u4E2A\u52A8\u4F5C\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C**\u5C1A\u672A\u751F\u6548**\u3002`,
+        `\u5DF2\u63D0\u4EA4\u63D0\u6848 ${res.proposalId}\uFF1A${res.summary}`,
+        `\u56E2\u961F\u6210\u5458\u5728 Momentum \u7684\u8BC4\u5BA1\u961F\u5217\u91CC\u63A5\u53D7\u4E4B\u540E\u624D\u4F1A\u771F\u6B63\u6267\u884C\u3002\u522B\u5047\u8BBE\u5B83\u5DF2\u7ECF\u5B8C\u6210\u3002`,
+        `\u6279\u51C6\u5165\u53E3\uFF1A${links.approvals}`
+      ].join("\n");
+      return {
+        ...text(message),
+        structuredContent: { status: "pending_approval", message, proposalId: res.proposalId, summary: res.summary, links }
+      };
+    }
+    const result = compactReceipt(res.result);
+    const key = taskKey ?? result?.key;
+    return {
+      ...text(`\u2713 ${done}
+
+${JSON.stringify(result)}`),
+      structuredContent: {
+        status: "executed",
+        message: done,
+        result: JSON.parse(JSON.stringify(result)),
+        links: linksFor(typeof key === "string" ? key : null)
+      }
+    };
+  }
   async function measured(runId) {
     const meter = meters.get(runId);
     if (!meter) return {};
@@ -23991,9 +24117,7 @@ function createTools(client, profile = "full", options = {}) {
       const only = projects[0];
       if (projects.length === 1 && only) return only;
       if (projects.length === 0) {
-        throw new Error(
-          "\u8FD9\u4E2A Agent \u4E00\u4E2A\u9879\u76EE\u90FD\u8BBF\u95EE\u4E0D\u5230\u3002\u8BA9\u7BA1\u7406\u5458\u5728 Momentum \u7684 Agents \u9875\u52FE\u4E0A\u300C\u53EF\u8BBF\u95EE\u9879\u76EE\u300D\u6216\u6574\u4E2A Sector\uFF1B\u7528 whoami \u53EF\u4EE5\u770B\u5230\u5F53\u524D\u7684 grants.projects / grants.sectors\u3002"
-        );
+        throw new Error(NO_PROJECTS_MESSAGE);
       }
       throw new Error(
         `\u6709 ${projects.length} \u4E2A\u9879\u76EE\uFF0C\u8BF7\u7528 project \u53C2\u6570\u6307\u5B9A\uFF1A${projects.map((p) => p.key).join(", ")}`
@@ -24127,13 +24251,22 @@ ${options2}`
       const statuses = await client.project.statuses.query({ projectId: task.projectId });
       const target = matchStatus(statuses, wanted);
       if (!target) {
-        return `\u26A0 \u72B6\u6001\u672A\u6539\uFF1A\u6CA1\u6709\u5339\u914D\u300C${wanted}\u300D\u7684\u5217\uFF08\u6709\uFF1A${statuses.map((s) => `${s.name}(${s.category})`).join(", ")}\uFF09`;
+        return {
+          status: "failed",
+          message: `\u26A0 \u72B6\u6001\u672A\u6539\uFF1A\u6CA1\u6709\u5339\u914D\u300C${wanted}\u300D\u7684\u5217\uFF08\u6709\uFF1A${statuses.map((s) => `${s.name}(${s.category})`).join(", ")}\uFF09`
+        };
       }
+      const column = { statusId: target.id, statusName: target.name, statusCategory: target.category };
       try {
         const res = await client.task.transition.mutate({ taskId: task.id, statusId: target.id });
         if (res.status === "proposed") {
           receipt.statusProposalId = res.proposalId;
-          return `\u23F8 \u79FB\u5230\u300C${target.name}\u300D\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C\u5C1A\u672A\u751F\u6548`;
+          return {
+            status: "pending_approval",
+            message: `\u23F8 \u79FB\u5230\u300C${target.name}\u300D\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C\u5C1A\u672A\u751F\u6548`,
+            proposalId: res.proposalId,
+            ...column
+          };
         }
       } catch (err) {
         if (!(errorCode(err) === "CONFLICT" && err instanceof Error && err.message.includes("\u72B6\u6001\u672A\u53D1\u751F\u53D8\u5316"))) {
@@ -24141,27 +24274,41 @@ ${options2}`
         }
       }
       receipt.status = target.name;
-      return `\u2713 \u4EFB\u52A1\u5728\u300C${target.name}\u300D`;
+      return { status: "executed", message: `\u2713 \u4EFB\u52A1\u5728\u300C${target.name}\u300D`, ...column };
     } catch (err) {
-      return `\u26A0 \u72B6\u6001\u672A\u6539\u3002${explain(err)}`;
+      return { status: "failed", message: `\u26A0 \u72B6\u6001\u672A\u6539\u3002${explain(err)}` };
     }
   }
   async function finishRunAfterDelivery(runId, input, receipt) {
-    if (!runId) return "\xB7 \u6CA1\u6709\u7ED3\u675F\u8FD0\u884C\uFF1A\u672C\u8FDB\u7A0B\u6CA1\u4E3A\u8FD9\u4EF6\u4EFB\u52A1\u5F00\u8FC7\u8FD0\u884C\uFF0C\u4E5F\u6CA1\u4F20 run_id";
+    if (!runId) {
+      return { status: "skipped", message: "\xB7 \u6CA1\u6709\u7ED3\u675F\u8FD0\u884C\uFF1A\u672C\u8FDB\u7A0B\u6CA1\u4E3A\u8FD9\u4EF6\u4EFB\u52A1\u5F00\u8FC7\u8FD0\u884C\uFF0C\u4E5F\u6CA1\u4F20 run_id" };
+    }
     try {
       const res = await client.run.finish.mutate({ runId, ...input, ...await measured(runId) });
-      if (res.status === "proposed") return "\u23F8 \u7ED3\u675F\u8FD0\u884C\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C\u5C1A\u672A\u751F\u6548\uFF1B\u672C\u8FDB\u7A0B\u4F1A\u7EE7\u7EED\u4E3A\u5B83\u5FC3\u8DF3";
+      if (res.status === "proposed") {
+        return {
+          status: "pending_approval",
+          message: "\u23F8 \u7ED3\u675F\u8FD0\u884C\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C\u5C1A\u672A\u751F\u6548\uFF1B\u672C\u8FDB\u7A0B\u4F1A\u7EE7\u7EED\u4E3A\u5B83\u5FC3\u8DF3",
+          proposalId: res.proposalId,
+          runId
+        };
+      }
       forgetRun(runId);
       Object.assign(receipt, { runId, runState: input.state });
       const { releasedClaimOn } = res.result;
-      return `\u2713 \u8FD0\u884C\u5DF2\u7ED3\u675F\uFF08${input.state}\uFF09${releasedClaimOn ? "\uFF0C\u9886\u53D6\u5DF2\u653E\u624B" : ""}`;
+      return {
+        status: "executed",
+        message: `\u2713 \u8FD0\u884C\u5DF2\u7ED3\u675F\uFF08${input.state}\uFF09${releasedClaimOn ? "\uFF0C\u9886\u53D6\u5DF2\u653E\u624B" : ""}`,
+        runId,
+        runState: input.state
+      };
     } catch (err) {
       if (errorCode(err) === "CONFLICT") {
         forgetRun(runId);
         receipt.runId = runId;
-        return "\u2713 \u8FD0\u884C\u6B64\u524D\u5DF2\u7ED3\u675F";
+        return { status: "executed", message: "\u2713 \u8FD0\u884C\u6B64\u524D\u5DF2\u7ED3\u675F", runId };
       }
-      return `\u26A0 \u8FD0\u884C\u672A\u7ED3\u675F\uFF0C\u53EF\u7A0D\u540E\u7528 finish_run \u5355\u72EC\u7ED3\u675F\u3002${explain(err)}`;
+      return { status: "failed", message: `\u26A0 \u8FD0\u884C\u672A\u7ED3\u675F\uFF0C\u53EF\u7A0D\u540E\u7528 finish_run \u5355\u72EC\u7ED3\u675F\u3002${explain(err)}`, runId };
     }
   }
   const cursorSchema = external_exports.object({ createdAt: external_exports.string().datetime(), id: external_exports.string().uuid() });
@@ -24182,13 +24329,19 @@ ${options2}`
             taskId: task.id,
             trigger: { source: "mcp", tool: "begin_task", note: args.note ?? null }
           });
-          if (started.status === "proposed") return reportWrite("", started);
+          if (started.status === "proposed") return reportWrite("", started, task.key);
           runId = started.result.runId;
           trackRun(runId, task.id);
         }
         const claim = await claimForRun(task.id, runId);
         const context = await client.task.context.query({ taskId: task.id });
-        return json({ runId, claim, context });
+        return json({
+          status: "executed",
+          runId,
+          claim,
+          context,
+          links: linksFor(task.key, claim.status === "pending_approval")
+        });
       }
     }),
     defineTool({
@@ -24213,7 +24366,7 @@ ${options2}`
         const task = await resolveTaskRef(args.task);
         const runId = args.run_id ?? heartbeats.runFor(task.id);
         const receipt = { key: task.key };
-        const lines = [];
+        let delivery;
         const delivered = await client.task.submitDelivery.mutate({
           taskId: task.id,
           basedOnSpecVersion: args.based_on_spec_version,
@@ -24227,30 +24380,47 @@ ${options2}`
         });
         if (delivered.status === "proposed") {
           receipt.deliveryProposalId = delivered.proposalId;
-          lines.push(`\u23F8 \u4EA4\u4ED8\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C\u5C1A\u672A\u751F\u6548\uFF08\u63D0\u6848 ${delivered.proposalId}\uFF09`);
+          delivery = {
+            status: "pending_approval",
+            message: `\u23F8 \u4EA4\u4ED8\u9700\u8981\u4EBA\u5DE5\u6279\u51C6\uFF0C\u5C1A\u672A\u751F\u6548\uFF08\u63D0\u6848 ${delivered.proposalId}\uFF09`,
+            proposalId: delivered.proposalId
+          };
         } else {
           const d = delivered.result;
           Object.assign(receipt, { deliveryId: d.id, deliveryState: d.state }, d.outdated ? { outdated: true } : {});
-          lines.push(
-            d.replayed ? "\u2713 \u4EA4\u4ED8\u6B64\u524D\u5DF2\u63D0\u4EA4\uFF08\u6309 idempotency_key \u91CD\u653E\uFF0C\u6CA1\u6709\u91CD\u590D\u521B\u5EFA\uFF09" : "\u2713 \u4EA4\u4ED8\u5DF2\u63D0\u4EA4\uFF0C\u7B49\u5F85\u8BC4\u5BA1\uFF1B\u4EFB\u52A1\u4E0D\u4F1A\u56E0\u6B64\u5B8C\u6210"
-          );
-          if (d.outdated) lines.push("\u26A0 \u4EA4\u4ED8\u4F9D\u636E\u7684\u4E0D\u662F\u5F53\u524D\u8BF4\u660E\u7248\u672C\uFF0C\u5DF2\u6807\u8BB0 outdated");
+          delivery = {
+            status: "executed",
+            message: (d.replayed ? "\u2713 \u4EA4\u4ED8\u6B64\u524D\u5DF2\u63D0\u4EA4\uFF08\u6309 idempotency_key \u91CD\u653E\uFF0C\u6CA1\u6709\u91CD\u590D\u521B\u5EFA\uFF09" : "\u2713 \u4EA4\u4ED8\u5DF2\u63D0\u4EA4\uFF0C\u7B49\u5F85\u8BC4\u5BA1\uFF1B\u4EFB\u52A1\u4E0D\u4F1A\u56E0\u6B64\u5B8C\u6210") + (d.outdated ? "\n\u26A0 \u4EA4\u4ED8\u4F9D\u636E\u7684\u4E0D\u662F\u5F53\u524D\u8BF4\u660E\u7248\u672C\uFF0C\u5DF2\u6807\u8BB0 outdated" : ""),
+            deliveryId: d.id,
+            deliveryState: d.state,
+            replayed: d.replayed,
+            outdated: d.outdated
+          };
         }
-        lines.push(await moveAfterDelivery(task, args.status ?? "review", receipt));
-        lines.push(
-          await finishRunAfterDelivery(
-            runId,
-            {
-              state: args.run_state ?? "succeeded",
-              costUsd: args.cost_usd,
-              transcriptUrl: args.transcript_url
-            },
-            receipt
-          )
+        const transition = await moveAfterDelivery(task, args.status ?? "review", receipt);
+        const run2 = await finishRunAfterDelivery(
+          runId,
+          {
+            state: args.run_state ?? "succeeded",
+            costUsd: args.cost_usd,
+            transcriptUrl: args.transcript_url
+          },
+          receipt
         );
-        return text(`${lines.join("\n")}
+        const steps = [delivery, transition, run2];
+        const pending = steps.some((s) => s.status === "pending_approval");
+        const status = steps.some((s) => s.status === "failed" || s.status === "skipped") ? "partial" : pending ? "pending_approval" : "executed";
+        const links = linksFor(task.key, pending);
+        const message = [
+          ...steps.map((s) => s.message),
+          ...links.approvals ? [`\u6279\u51C6\u5165\u53E3\uFF1A${links.approvals}`] : []
+        ].join("\n");
+        return {
+          ...text(`${message}
 
-${JSON.stringify(receipt)}`);
+${JSON.stringify(receipt)}`),
+          structuredContent: { status, message, steps: { delivery, transition, run: run2 }, result: { ...receipt }, links }
+        };
       }
     }),
     defineTool({
@@ -24269,7 +24439,10 @@ ${JSON.stringify(receipt)}`);
           limit: args.limit
         });
         if (items.length === 0) {
-          return text("\u73B0\u5728\u6CA1\u6709\u53EF\u4EE5\u63A5\u7684\u6D3B\u3002\u53EF\u80FD\u662F\u90FD\u88AB\u9886\u8D70\u4E86\u3001\u4F9D\u8D56\u8FD8\u6CA1\u5B8C\u6210\uFF0C\u6216\u8005\u6709\u963B\u788D\u5F00\u5DE5\u7684\u95EE\u9898\u5728\u7B49\u4EBA\u56DE\u7B54\u3002");
+          return {
+            ...text("\u73B0\u5728\u6CA1\u6709\u53EF\u4EE5\u63A5\u7684\u6D3B\u3002\u53EF\u80FD\u662F\u90FD\u88AB\u9886\u8D70\u4E86\u3001\u4F9D\u8D56\u8FD8\u6CA1\u5B8C\u6210\uFF0C\u6216\u8005\u6709\u963B\u788D\u5F00\u5DE5\u7684\u95EE\u9898\u5728\u7B49\u4EBA\u56DE\u7B54\u3002"),
+            structuredContent: { items: [] }
+          };
         }
         return json(items);
       }
@@ -24301,7 +24474,7 @@ ${JSON.stringify(receipt)}`);
           );
         } catch (err) {
           if (err instanceof Error && err.message.includes("\u6CA1\u6709\u53EF\u63A5\u7684\u6D3B")) {
-            return text("\u73B0\u5728\u6CA1\u6709\u53EF\u4EE5\u63A5\u7684\u6D3B\uFF1A\u90FD\u88AB\u9886\u8D70\u4E86\u3001\u4F9D\u8D56\u6CA1\u7ED3\u6E05\uFF0C\u6216\u8005\u5728\u7B49\u4EBA\u56DE\u7B54\u963B\u788D\u5F00\u5DE5\u7684\u95EE\u9898\u3002");
+            return unchanged("\u73B0\u5728\u6CA1\u6709\u53EF\u4EE5\u63A5\u7684\u6D3B\uFF1A\u90FD\u88AB\u9886\u8D70\u4E86\u3001\u4F9D\u8D56\u6CA1\u7ED3\u6E05\uFF0C\u6216\u8005\u5728\u7B49\u4EBA\u56DE\u7B54\u963B\u788D\u5F00\u5DE5\u7684\u95EE\u9898\u3002");
           }
           if (err instanceof Error && err.message.includes("\u4E0D\u5C5E\u4E8E\u4EFB\u4F55\u9879\u76EE") && projects) {
             throw new Error(
@@ -24330,7 +24503,7 @@ ${JSON.stringify(receipt)}`);
         if (res.status === "executed" && args.run_id && heartbeats.has(args.run_id)) {
           heartbeats.track(args.run_id, task.id, true);
         }
-        return reportWrite(args.run_id ? `\u5DF2\u9886\u53D6 ${task.key}\uFF1B\u79DF\u7EA6\u968F\u8FD0\u884C\u81EA\u52A8\u7EED\u7EA6` : `\u5DF2\u9886\u53D6 ${task.key}`, res);
+        return reportWrite(args.run_id ? `\u5DF2\u9886\u53D6 ${task.key}\uFF1B\u79DF\u7EA6\u968F\u8FD0\u884C\u81EA\u52A8\u7EED\u7EA6` : `\u5DF2\u9886\u53D6 ${task.key}`, res, task.key);
       }
     }),
     defineTool({
@@ -24341,7 +24514,8 @@ ${JSON.stringify(receipt)}`);
         const task = await resolveTaskRef(args.task);
         return reportWrite(
           `\u5DF2\u91CA\u653E ${task.key}`,
-          await client.task.release.mutate({ taskId: task.id, reason: args.reason })
+          await client.task.release.mutate({ taskId: task.id, reason: args.reason }),
+          task.key
         );
       }
     }),
@@ -24394,7 +24568,7 @@ ${JSON.stringify(receipt)}`);
       inputSchema: { task: external_exports.string() },
       async handler(args) {
         const task = await resolveTaskRef(args.task);
-        return json(await client.task.context.query({ taskId: task.id }));
+        return json({ ...await client.task.context.query({ taskId: task.id }), links: linksFor(task.key) });
       }
     }),
     defineTool({
@@ -24413,7 +24587,7 @@ ${JSON.stringify(receipt)}`);
           notesMd: args.notes,
           verification: args.verification,
           refs: args.refs
-        }));
+        }), task.key);
       }
     }),
     defineTool({
@@ -24436,7 +24610,7 @@ ${JSON.stringify(receipt)}`);
           descriptionMd: args.description,
           acceptance: args.acceptance,
           changeSummary: args.change_summary
-        }));
+        }), task.key);
       }
     }),
     defineTool({
@@ -24500,7 +24674,7 @@ ${JSON.stringify(receipt)}`);
           results: args.results,
           remainingWork: args.remaining_work,
           handoff: args.handoff
-        }));
+        }), task.key);
       }
     }),
     defineTool({
@@ -24543,7 +24717,7 @@ ${JSON.stringify(receipt)}`);
           taskId: task.id,
           body: args.question,
           blocking: args.blocking ?? false
-        }));
+        }), task.key);
       }
     }),
     defineTool({
@@ -24594,7 +24768,7 @@ ${JSON.stringify(receipt)}`);
             acceptance: spec.acceptance,
             changeSummary: spec.change_summary
           } : void 0
-        }));
+        }), task.key);
       }
     }),
     defineTool({
@@ -24616,6 +24790,84 @@ ${JSON.stringify(receipt)}`);
         });
       }
     }),
+    defineTool({
+      name: "browse_tasks",
+      description: "\u4E0D\u77E5\u9053\u7F16\u53F7\u65F6\u627E\u4EFB\u52A1\uFF1A\u53EA\u8BFB\u5217\u51FA\u53EF\u8BBF\u95EE\u4EFB\u52A1\u7684\u6458\u8981\uFF0C\u4E0D\u9886\u53D6\u3001\u4E0D\u5F00\u8FD0\u884C\uFF1B\u9009\u5B9A\u540E begin_task\u3002outcome\uFF1Ano_projects \u8981\u7BA1\u7406\u5458\u6388\u6743\u9879\u76EE\uFF0Cno_match \u653E\u5BBD\u6761\u4EF6\uFF0Cfailed \u53EF\u91CD\u8BD5\u3002nextOffset \u975E\u7A7A = \u6709\u4E0B\u4E00\u9875\u3002",
+      inputSchema: {
+        project: external_exports.string().optional().describe("key \u6216\u540D\u5B57\uFF0C\u4E0D\u4F20 = \u5168\u90E8"),
+        mine: external_exports.boolean().optional().describe("\u53EA\u770B\u6307\u6D3E\u7ED9\u6211\u7684"),
+        status: external_exports.array(external_exports.enum(STATUS_CATEGORIES)).optional().describe("\u72B6\u6001\u5927\u7C7B"),
+        query: external_exports.string().max(200).optional().describe("\u5173\u952E\u8BCD"),
+        // 上限写在这里而不是 describe 里：schema 的 maximum 模型看得见，也真的拦得住
+        limit: external_exports.number().int().min(1).max(BROWSE_MAX_LIMIT).optional(),
+        offset: external_exports.number().int().min(0).optional()
+      },
+      async handler(args) {
+        const limit = args.limit ?? BROWSE_DEFAULT_LIMIT;
+        const offset = args.offset ?? 0;
+        const stop = (outcome, message, isError2) => ({
+          ...text(message),
+          structuredContent: { outcome, message, items: [], nextOffset: null },
+          ...isError2 ? { isError: isError2 } : {}
+        });
+        const failed = (err) => stop("failed", `${explain(err)}
+
+\u8FD9\u662F\u8BFB\u53D6\u5931\u8D25\uFF0C\u4E0D\u4EE3\u8868\u6CA1\u6709\u4EFB\u52A1 \u2014\u2014 \u7A0D\u540E\u91CD\u8BD5\uFF1B\u53CD\u590D\u5931\u8D25\u518D\u68C0\u67E5\u7F51\u7EDC\u548C\u4EE4\u724C\u3002`, true);
+        let projects;
+        try {
+          projects = await client.project.list.query();
+        } catch (err) {
+          return failed(err);
+        }
+        if (projects.length === 0) return stop("no_projects", NO_PROJECTS_MESSAGE, false);
+        let project;
+        if (args.project) {
+          const ref = args.project;
+          project = projects.find(
+            (p) => p.id === ref || p.key.toLowerCase() === ref.toLowerCase() || p.name === ref
+          );
+          if (!project) {
+            return stop("project_unavailable", `\u5931\u8D25\uFF1A${(await missingProjectError(ref, projects)).message}`, true);
+          }
+        }
+        let rows;
+        try {
+          const assigneeId = args.mine ? (await client.viewer.me.query())?.actorId ?? void 0 : void 0;
+          rows = await client.task.list.query({
+            projectId: project?.id,
+            categories: args.status,
+            assigneeId,
+            query: args.query,
+            limit: limit + 1,
+            offset
+          });
+        } catch (err) {
+          return failed(err);
+        }
+        const page = rows.slice(0, limit);
+        const items = page.map((t) => ({
+          key: t.key,
+          title: t.title,
+          type: t.type,
+          priority: t.priority,
+          status: { name: t.status.name, category: t.status.category },
+          assignee: t.assignee ? { name: t.assignee.name, kind: t.assignee.kind } : null,
+          updatedAt: t.updatedAt
+        }));
+        const empty = items.length === 0;
+        return json({
+          outcome: empty ? "no_match" : "ok",
+          message: empty ? offset > 0 ? "\u8FD9\u4E00\u9875\u6CA1\u6709\u66F4\u591A\u4EFB\u52A1\u4E86\u3002" : "\u6CA1\u6709\u7B26\u5408\u6761\u4EF6\u7684\u4EFB\u52A1\u3002\u53EF\u4EE5\u53BB\u6389 mine / status / query / project \u4E2D\u7684\u6761\u4EF6\u518D\u8BD5\u3002" : `${items.length} \u6761\u4EFB\u52A1${rows.length > limit ? "\uFF0C\u8FD8\u6709\u4E0B\u4E00\u9875" : ""}\u3002`,
+          items,
+          nextOffset: rows.length > limit ? offset + limit : null,
+          // 第一页带上可选项目，客户端好做项目筛选；翻页时不重复
+          ...offset === 0 ? {
+            projects: projects.slice(0, BROWSE_MAX_PROJECTS).map((p) => ({ key: p.key, name: p.name })),
+            ...projects.length > BROWSE_MAX_PROJECTS ? { projectsTruncated: true } : {}
+          } : {}
+        });
+      }
+    }),
     defineTool({
       name: "list_projects",
       description: "\u5217\u51FA\u5F53\u524D\u7EC4\u7EC7\u91CC\u6211\u80FD\u8BBF\u95EE\u7684\u9879\u76EE\u3002\u8FD9\u91CC\u53EA\u6709\u6388\u6743\u7ED9\u672C Agent \u7684\u9879\u76EE \u2014\u2014 \u5C11\u4E86\u9884\u671F\u4E2D\u7684\u9879\u76EE\u5C31\u7528 whoami \u770B grants.projects / grants.sectors\uFF0C\u591A\u534A\u662F\u6CA1\u52FE\u4E0A\uFF08\u6216\u9879\u76EE\u5DF2\u79FB\u51FA\u6388\u6743\u7684 Sector\uFF09\uFF0C\u800C\u4E0D\u662F\u9879\u76EE\u4E0D\u5B58\u5728\u3002",
@@ -24688,7 +24940,8 @@ ${JSON.stringify(receipt)}`);
         task: external_exports.string().describe("\u4EFB\u52A1\u7F16\u53F7\uFF08\u5982 MOM-12\uFF09\u6216 uuid")
       },
       async handler(args) {
-        return json(await resolveTask(args.task));
+        const task = await resolveTask(args.task);
+        return json({ ...task, links: linksFor(task.key) });
       }
     }),
     defineTool({
@@ -24740,7 +24993,7 @@ ${JSON.stringify(receipt)}`);
         const task = await resolveTask(args.task);
         const parent = args.parent ? await resolveTask(args.parent) : null;
         if (task.parentId === parent?.id || !task.parentId && !parent) {
-          return text(`${task.key} \u5DF2\u7ECF\u5904\u4E8E\u8FD9\u4E2A\u5C42\u7EA7\uFF0C\u65E0\u9700\u6539\u52A8\u3002`);
+          return unchanged(`${task.key} \u5DF2\u7ECF\u5904\u4E8E\u8FD9\u4E2A\u5C42\u7EA7\uFF0C\u65E0\u9700\u6539\u52A8\u3002`);
         }
         const res = await client.task.reparent.mutate({
           taskId: task.id,
@@ -24748,7 +25001,8 @@ ${JSON.stringify(receipt)}`);
         });
         return reportWrite(
           parent ? `\u5DF2\u628A ${task.key} \u6302\u5230 ${parent.key} \u4E0B` : `\u5DF2\u628A ${task.key} \u63D0\u5347\u4E3A\u6839\u4EFB\u52A1`,
-          res
+          res,
+          task.key
         );
       }
     }),
@@ -24762,7 +25016,7 @@ ${JSON.stringify(receipt)}`);
       },
       async handler(args) {
         const { task, related, res } = await changeRelation("add", args);
-        return reportWrite(`\u5DF2\u4E3A ${task.key} \u548C ${related.key} \u6DFB\u52A0 ${args.kind} \u5173\u7CFB`, res);
+        return reportWrite(`\u5DF2\u4E3A ${task.key} \u548C ${related.key} \u6DFB\u52A0 ${args.kind} \u5173\u7CFB`, res, task.key);
       }
     }),
     defineTool({
@@ -24771,7 +25025,7 @@ ${JSON.stringify(receipt)}`);
       inputSchema: { task: external_exports.string(), related: external_exports.string(), kind: RELATION_KIND },
       async handler(args) {
         const { task, related, res } = await changeRelation("remove", args);
-        return reportWrite(`\u5DF2\u79FB\u9664 ${task.key} \u548C ${related.key} \u7684 ${args.kind} \u5173\u7CFB`, res);
+        return reportWrite(`\u5DF2\u79FB\u9664 ${task.key} \u548C ${related.key} \u7684 ${args.kind} \u5173\u7CFB`, res, task.key);
       }
     }),
     defineTool({
@@ -24793,7 +25047,7 @@ ${JSON.stringify(receipt)}`);
           );
         }
         if (target.id === task.status.id) {
-          return text(`\u4EFB\u52A1 ${task.key} \u5DF2\u7ECF\u5728\u300C${target.name}\u300D\uFF0C\u65E0\u9700\u6539\u52A8\u3002`);
+          return unchanged(`\u4EFB\u52A1 ${task.key} \u5DF2\u7ECF\u5728\u300C${target.name}\u300D\uFF0C\u65E0\u9700\u6539\u52A8\u3002`);
         }
         const res = await client.task.transition.mutate({
           taskId: task.id,
@@ -24801,7 +25055,8 @@ ${JSON.stringify(receipt)}`);
         });
         return reportWrite(
           `${task.key} \u5DF2\u4ECE\u300C${task.status.name}\u300D\u79FB\u5230\u300C${target.name}\u300D`,
-          res
+          res,
+          task.key
         );
       }
     }),
@@ -24818,7 +25073,7 @@ ${JSON.stringify(receipt)}`);
           taskId: task.id,
           body: { type: "text", text: args.body }
         });
-        return reportWrite(`\u5DF2\u5728 ${task.key} \u4E0B\u7559\u8A00`, res);
+        return reportWrite(`\u5DF2\u5728 ${task.key} \u4E0B\u7559\u8A00`, res, task.key);
       }
     }),
     defineTool({
@@ -24908,7 +25163,7 @@ ${JSON.stringify(receipt)}`);
         if (res.status === "executed") {
           trackRun(res.result.runId, task?.id ?? null);
         }
-        return reportWrite("\u5DF2\u5F00\u59CB\u8BB0\u5F55\u672C\u6B21\u8FD0\u884C\uFF1B\u672C\u8FDB\u7A0B\u4F1A\u81EA\u52A8\u5FC3\u8DF3\u7EED\u7EA6", res);
+        return reportWrite("\u5DF2\u5F00\u59CB\u8BB0\u5F55\u672C\u6B21\u8FD0\u884C\uFF1B\u672C\u8FDB\u7A0B\u4F1A\u81EA\u52A8\u5FC3\u8DF3\u7EED\u7EA6", res, task?.key);
       }
     }),
     defineTool({
@@ -24944,24 +25199,31 @@ ${JSON.stringify(receipt)}`);
     })
   ];
   const selected = profile === "work" ? tools.filter((tool) => WORK_TOOL_NAMES.has(tool.name)) : tools;
-  return selected.map((tool) => ({
-    ...tool,
-    handler: async (args, meta) => {
-      reported.record(meta);
-      const argBytes = byteLength(JSON.stringify(args ?? {}));
-      const charged = meters.beginCall(argBytes);
-      let result;
-      try {
-        result = await tool.handler(args);
-      } catch (err) {
-        result = { content: [{ type: "text", text: explain(err) }], isError: true };
+  return selected.map((tool) => {
+    const meta = TOOL_META[tool.name];
+    if (!meta) throw new Error(`\u5DE5\u5177 ${tool.name} \u6CA1\u6709\u767B\u8BB0\u8BFB\u5199\u6CE8\u89E3\uFF08TOOL_META\uFF09`);
+    return wrap({ ...tool, ...meta });
+  });
+  function wrap(tool) {
+    return {
+      ...tool,
+      handler: async (args, meta) => {
+        reported.record(meta);
+        const argBytes = byteLength(JSON.stringify(args ?? {}));
+        const charged = meters.beginCall(argBytes);
+        let result;
+        try {
+          result = await tool.handler(args);
+        } catch (err) {
+          result = { content: [{ type: "text", text: explain(err) }], isError: true };
+        }
+        const notices = heartbeats.drainNotices();
+        const final = notices.length === 0 ? result : { ...result, content: [...result.content, { type: "text", text: notices.join("\n") }] };
+        meters.endCall(charged, argBytes, final.content.reduce((n, c) => n + byteLength(c.text), 0));
+        return final;
       }
-      const notices = heartbeats.drainNotices();
-      const final = notices.length === 0 ? result : { ...result, content: [...result.content, { type: "text", text: notices.join("\n") }] };
-      meters.endCall(charged, argBytes, final.content.reduce((n, c) => n + byteLength(c.text), 0));
-      return final;
-    }
-  }));
+    };
+  }
 }
 function planLimitOf(err) {
   const data = err?.data;
@@ -25008,6 +25270,7 @@ var SERVER_INSTRUCTIONS = [
   "Momentum \u662F\u8FD9\u4E2A\u56E2\u961F\u7684\u9879\u76EE\u7BA1\u7406\u7CFB\u7EDF\uFF0C\u4EBA\u548C Agent \u7684\u5DE5\u4F5C\u90FD\u8BB0\u5728\u8FD9\u91CC\u3002",
   "\u62FF\u5230\u4EFB\u52A1\u7F16\u53F7\u5C31\u76F4\u63A5 begin_task\uFF1A\u89E3\u6790\u3001\u5F00\u8FD0\u884C\u3001\u9886\u53D6\u3001\u8BFB\u7D27\u51D1\u4E0A\u4E0B\u6587\u4E00\u6B65\u5B8C\u6210\uFF0C",
   "\u4E0D\u5FC5\u5148 whoami / list_tasks / get_task\u3002\u5FC3\u8DF3\u7531\u672C\u8FDB\u7A0B\u81EA\u52A8\u5B8C\u6210\uFF0C\u4E0D\u7528\u624B\u52A8\u7EED\u7EA6\u3002",
+  "\u4E0D\u77E5\u9053\u7F16\u53F7\u65F6\u7528 browse_tasks \u627E\uFF08\u53EA\u8BFB\uFF0C\u4E0D\u9886\u53D6\uFF09\uFF1B\u9009\u5B9A\u540E\u518D begin_task\u3002",
   "\u505A\u5B8C\u8C03 finish_task_work\uFF1A\u4E00\u6B21\u63D0\u4EA4\u4EA4\u4ED8\u3001\u79FB\u5230\u8BC4\u5BA1\u3001\u7ED3\u675F\u8FD0\u884C\u5E76\u5982\u5B9E\u4E0A\u62A5\u6210\u672C\u3002",
   "\u8FDB\u5C55\u548C\u5361\u70B9\u7528 comment_on_task \u5199\u4E0B\u6765\uFF0C\u5199\u77ED\uFF1A\u5148\u7ED3\u8BBA\u3001\u518D\u8981\u70B9\uFF0C\u5173\u952E\u8282\u70B9\u4E00\u6761\u5C31\u591F\u3002",
   "\u7F3A\u4FE1\u606F\u5148\u770B\u7528\u6237\u5728\u4E0D\u5728\uFF1A\u6B63\u548C\u4F60\u5BF9\u8BDD\u5C31\u76F4\u63A5\u95EE\u7528\u6237\uFF1B\u7528\u6237\u7B54\u4E0D\u4E86\u3001\u8981\u56E2\u961F\u62CD\u677F\u7684\u624D\u7528 ask_question\u3002",
@@ -25030,7 +25293,14 @@ function createMcpServer(client, profile = "work", options = {}) {
   for (const tool of createTools(client, profile, options)) {
     server.registerTool(
       tool.name,
-      { description: tool.description, inputSchema: tool.inputSchema },
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        // 注解让客户端知道哪些是只读查询（不必弹确认）；outputSchema 让它能校验并渲染
+        // structuredContent，而不是从文本里猜（IMMO-222）
+        annotations: tool.annotations,
+        ...tool.outputSchema ? { outputSchema: tool.outputSchema } : {}
+      },
       // SDK 会先按 inputSchema 校验再调进来，这里的形状转换是安全的。
       // extra._meta 是请求 params._meta，宿主可以在里面上报用量（IMMO-215）
       (args, extra) => tool.handler(args, extra._meta)
@@ -25087,7 +25357,8 @@ async function main() {
     log(`  \u26A0 MOMENTUM_TOOL_PROFILE=${configuredProfile} \u65E0\u6548\uFF0C\u4F7F\u7528 work\uFF08\u53EF\u9009\uFF1Awork / full\uFF09`);
   }
   const profile = configuredProfile === "full" ? "full" : "work";
-  const server = createMcpServer(client, profile, { log });
+  const appUrl = process.env.MOMENTUM_APP_URL || url;
+  const server = createMcpServer(client, profile, { log, appUrl });
   await server.connect(new StdioServerTransport());
   await greet(url);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@costgate/momentum-mcp",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Momentum MCP Server —— 把 Momentum 的任务、领取与交付接进任意 MCP 客户端",
   "type": "module",
   "bin": {