feat(mcp): unlink every PR in given states with one call

apps/server/src/mcp/toolkits/pullRequests/handlers.test.ts

@@ -517,6 +517,39 @@ describe("pull request toolkit handlers", () => {
     }),
   );
 
+  it.effect("unlinks every visible pull request in the given states in one call", () =>
+    Effect.gen(function* () {
+      const withState = (number: number, state: "open" | "closed" | "merged") => {
+        const link = makeLink(number, { headBranch: `branch-${number}` });
+        return { ...link, snapshot: { ...link.snapshot!, state } };
+      };
+      const harness = yield* makeHarness({
+        thread: makeThread([
+          withState(1, "merged"),
+          withState(2, "open"),
+          withState(3, "closed"),
+          makeLink(4),
+          { ...withState(5, "merged"), source: "stack-dismissed" },
+        ]),
+      });
+      const result = yield* harness.call("unlink_pull_requests", {
+        states: ["closed", "merged"],
+      });
+      expect(result).toEqual({
+        unlinked: [
+          { host: "github.com", repository: "t3tools/t3code", state: "merged", numbers: [1] },
+          { host: "github.com", repository: "t3tools/t3code", state: "closed", numbers: [3] },
+        ],
+        unlinkedCount: 2,
+        remaining: 2,
+      });
+      expect(yield* Ref.get(harness.commands)).toMatchObject([
+        { type: "thread.pull-request.unlink", number: 1 },
+        { type: "thread.pull-request.unlink", number: 3 },
+      ]);
+    }),
+  );
+
   it("reports an older Forgejo link's HTTP port when listing thread links", () => {
     const result = listThreadPullRequests(
       makeThread([

apps/server/src/mcp/toolkits/pullRequests/handlers.ts

@@ -426,6 +426,42 @@ const make = Effect.gen(function* () {
         };
       }),
     ),
+    unlink_pull_requests: writesThread((input) =>
+      Effect.gen(function* () {
+        const thread = yield* requireThread(PullRequestUnlinkFailedError, input.threadId);
+        const visible = visibleThreadPullRequests(threadPullRequestsOf(thread));
+        const matching = visible.flatMap((link) => {
+          const state = link.snapshot?.state;
+          return state !== undefined && input.states.includes(state)
+            ? [{ ...normalizeThreadPullRequestKey(link), state }]
+            : [];
+        });
+        yield* Effect.forEach(matching, ({ host, repository, number }) =>
+          Effect.gen(function* () {
+            yield* engine.dispatch({
+              type: "thread.pull-request.unlink",
+              commandId: yield* commandId("mcp-pr-unlink", thread.id),
+              threadId: thread.id,
+              host,
+              repository,
+              number,
+            });
+          }).pipe(Effect.catchCause(dispatchFailure(PullRequestUnlinkFailedError))),
+        );
+        // Numbers grouped by repository and state keep a large batch's result small.
+        const groups = Map.groupBy(matching, (pr) => `${pr.host}/${pr.repository}/${pr.state}`);
+        return {
+          unlinked: [...groups.values()].map((prs) => ({
+            host: prs[0]!.host,
+            repository: prs[0]!.repository,
+            state: prs[0]!.state,
+            numbers: prs.map((pr) => pr.number),
+          })),
+          unlinkedCount: matching.length,
+          remaining: visible.length - matching.length,
+        };
+      }),
+    ),
     list_thread_pull_requests: McpToolAccess.reads((input) =>
       requireThread(PullRequestListFailedError, input.threadId).pipe(
         Effect.map(listThreadPullRequests),

apps/server/src/mcp/toolkits/pullRequests/tools.ts

@@ -231,6 +231,20 @@ export const UnlinkPullRequestResult = Schema.Struct({
 });
 export type UnlinkPullRequestResult = typeof UnlinkPullRequestResult.Type;
 
+export const UnlinkPullRequestsResult = Schema.Struct({
+  unlinked: Schema.Array(
+    Schema.Struct({
+      host: Schema.String,
+      repository: Schema.String,
+      state: PullRequestState,
+      numbers: Schema.Array(Schema.Int),
+    }),
+  ),
+  unlinkedCount: Schema.Int,
+  remaining: Schema.Int,
+});
+export type UnlinkPullRequestsResult = typeof UnlinkPullRequestsResult.Type;
+
 export const WatchPullRequestResult = Schema.Struct({
   ...PullRequestIdentity,
   watching: Schema.Boolean,
@@ -297,6 +311,24 @@ const UnlinkPullRequestTool = Tool.make("unlink_pull_request", {
   .annotate(Tool.Idempotent, true)
   .annotate(Tool.OpenWorld, false);
 
+const UnlinkPullRequestsTool = Tool.make("unlink_pull_requests", {
+  description:
+    "Unlink every PR on a thread whose last known state (as `list_thread_pull_requests` shows) is in `states`, in one call. Use it instead of one `unlink_pull_request` per PR. PRs with no known state stay linked.",
+  parameters: Schema.Struct({
+    environmentId: OrchestratorMcpEnvironmentTarget,
+    threadId: Schema.optional(ThreadId.annotate({ description: "Thread. Default: this thread." })),
+    states: Schema.Array(PullRequestState).check(Schema.isMinLength(1)),
+  }),
+  success: UnlinkPullRequestsResult,
+  failure: PullRequestToolError,
+  dependencies,
+})
+  .annotate(Tool.Title, "Unlink pull requests by state")
+  .annotate(Tool.Readonly, false)
+  .annotate(Tool.Destructive, true)
+  .annotate(Tool.Idempotent, true)
+  .annotate(Tool.OpenWorld, false);
+
 const ListThreadPullRequestsTool = Tool.make("list_thread_pull_requests", {
   description:
     "List PRs linked to a thread, with last known state and stack order (bottom to top). Call only when you need that list. Never as an end-of-work check.",
@@ -411,6 +443,7 @@ const ReadPullRequestGuideTool = Tool.make("read_pull_request_guide", {
 export const PullRequestsToolkit = Toolkit.make(
   LinkPullRequestTool,
   UnlinkPullRequestTool,
+  UnlinkPullRequestsTool,
   ListThreadPullRequestsTool,
   WatchPullRequestTool,
   UnwatchPullRequestTool,

apps/server/src/provider/agentContextBudget.json

@@ -1,5 +1,5 @@
 {
   "claudeSystemAppendBytes": 5129,
   "codexAdditionalContextBytes": 6859,
-  "mcpToolListJsonBytes": 46109
+  "mcpToolListJsonBytes": 46596
 }

evals/mcp-tool-use/run.test.ts

@@ -116,6 +116,7 @@ it("passes a good run and names every rule a bad run breaks", () => {
     textMust: ["t3-thread://v2/"],
     textMustNot: ["Paste .*token"],
     linked: ["~/pull/124"],
+    linkedNumbers: [124],
   };
   const good: SampleRun = {
     calls: [
@@ -158,6 +159,7 @@ it("passes a good run and names every rule a bad run breaks", () => {
     "textMust /t3-thread://v2//",
     "textMustNot /Paste .*token/",
     "linked ~/pull/124",
+    "linkedNumbers",
   ]);
 });
 

evals/mcp-tool-use/run.ts

@@ -35,7 +35,12 @@ import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
 import { taskPrompt } from "../../apps/server/src/mcp/delegatedTaskModes.ts";
 import * as McpInvocationContext from "../../apps/server/src/mcp/McpInvocationContext.ts";
 import { advertisedJsonSchema } from "../../apps/server/src/mcp/advertisedJsonSchema.ts";
-import { EnvironmentId, ORCHESTRATOR_MCP_RUNNING_TASK_NEXT, ThreadId } from "@t3tools/contracts";
+import {
+  EnvironmentId,
+  ORCHESTRATOR_MCP_RUNNING_TASK_NEXT,
+  PullRequestState,
+  ThreadId,
+} from "@t3tools/contracts";
 import { projectComposerContextForProvider } from "@t3tools/shared/composerContextReferences";
 import { formatThreadLink } from "@t3tools/shared/threadLinks";
 import { buildCodexAdditionalContext } from "../../apps/server/src/provider/CodexDeveloperInstructions.ts";
@@ -166,6 +171,8 @@ const McpToolUseExpect = Schema.Struct({
   textMustNot: Schema.optional(Schema.Array(Schema.String)),
   /** Each entry matches a PR URL linked at the end, as `args` values match. */
   linked: Schema.optional(Schema.Array(Schema.String)),
+  /** The PR numbers linked at the end, exactly. */
+  linkedNumbers: Schema.optional(Schema.Array(Schema.Number)),
   /** Device manager checks: child briefs, simulator UI over the shell, failures, recordings. */
   device: Schema.optional(DeviceExpect),
 });
@@ -210,6 +217,12 @@ const McpToolUseWorld = Schema.StructWithRest(
     deviceInvalidCapture: Schema.optional(Schema.Boolean),
     /** Devices another thread's agent-device session holds, by device id: that thread's id. */
     deviceOwners: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    /** PRs already linked to the thread, with the state T3 last saw. */
+    linkedPullRequests: Schema.optional(
+      Schema.Array(
+        Schema.Struct({ number: Schema.Number, state: PullRequestState, title: Schema.String }),
+      ),
+    ),
   }),
   Rest,
 );
@@ -731,11 +744,16 @@ export const makeSample = (testCase: McpToolUseCase, base: Base): Sample => {
   const prior = testCase.setup.priorTurns ?? [];
   const priorCalls = prior.flatMap((turn) => turn.toolCalls ?? []);
   const repo = testCase.setup.world?.repo ?? "acme/app";
-  const urls = priorCalls.flatMap((call) =>
-    ["link_pull_request", "watch_pull_request"].includes(call.tool) && isRecord(call.input)
-      ? [pullRequest(repo, call.input).url]
-      : [],
-  );
+  const urls = [
+    ...(testCase.setup.world?.linkedPullRequests ?? []).map(
+      ({ number }) => pullRequest(repo, { number }).url,
+    ),
+    ...priorCalls.flatMap((call) =>
+      ["link_pull_request", "watch_pull_request"].includes(call.tool) && isRecord(call.input)
+        ? [pullRequest(repo, call.input).url]
+        : [],
+    ),
+  ];
   const taskNumbers = [...valueText(prior).matchAll(/task-(\d+)/g)].map((match) =>
     Number(match[1]),
   );
@@ -952,6 +970,15 @@ const pullRequest = (repo: string, input: Readonly<Record<string, unknown>>) =>
   };
 };
 
+/** A linked PR as `list_thread_pull_requests` shows it. Links made in the sample are open. */
+const linkedEntry = (sample: Sample, url: string) => {
+  const pr = pullRequest(sample.repo, { url });
+  const seeded = sample.testCase.setup.world?.linkedPullRequests?.find(
+    ({ number }) => number === pr.number && pr.repository === sample.repo,
+  );
+  return { ...pr, state: seeded?.state ?? "open", title: seeded?.title ?? null };
+};
+
 /** A believable T3 result for a tool the case does not mock. */
 const t3Default = (sample: Sample, name: string, input: Readonly<Record<string, unknown>>) => {
   const pr = () => pullRequest(sample.repo, input);
@@ -1006,6 +1033,24 @@ const t3Default = (sample: Sample, name: string, input: Readonly<Record<string,
     }
     case "unlink_pull_request":
       return { ...pr(), wasLinked: sample.linked.delete(pr().url) };
+    case "unlink_pull_requests": {
+      const states = Array.isArray(input.states) ? input.states : [];
+      const unlinked = [...sample.linked]
+        .map((url) => linkedEntry(sample, url))
+        .filter((entry) => states.includes(entry.state));
+      for (const { url } of unlinked) sample.linked.delete(url);
+      const groups = Map.groupBy(unlinked, (entry) => `${entry.repository}/${entry.state}`);
+      return {
+        unlinked: [...groups.values()].map((entries) => ({
+          host: "github.com",
+          repository: entries[0]!.repository,
+          state: entries[0]!.state,
+          numbers: entries.map((entry) => entry.number),
+        })),
+        unlinkedCount: unlinked.length,
+        remaining: sample.linked.size,
+      };
+    }
     case "watch_pull_request":
       sample.linked.add(pr().url);
       return { ...pr(), watching: true, wasWatching: false };
@@ -1014,10 +1059,9 @@ const t3Default = (sample: Sample, name: string, input: Readonly<Record<string,
     case "list_thread_pull_requests":
       return {
         pullRequests: [...sample.linked].map((url) => ({
-          ...pullRequest(sample.repo, { url }),
+          ...linkedEntry(sample, url),
           source: "agent",
           watching: false,
-          state: "open",
         })),
         chains: [],
       };
@@ -1403,6 +1447,11 @@ export const gradeSample = (expect: McpToolUseCase["expect"], run: SampleRun) =>
   for (const p of expect.textMustNot ?? []) add(`textMustNot /${p}/`, !test(p, run.text));
   const isLinked = (url: string) => (run.linked ?? []).some((at) => matches(url, at));
   for (const url of expect.linked ?? []) add(`linked ${url}`, isLinked(url));
+  if (expect.linkedNumbers !== undefined) {
+    const numbers = (run.linked ?? []).map((url) => Number(/(\d+)\/?$/.exec(url)?.[1]));
+    const exact = valueText(numbers.toSorted((a, b) => a - b));
+    add("linkedNumbers", exact === valueText(expect.linkedNumbers.toSorted((a, b) => a - b)));
+  }
   checks.push(...gradeDevice(expect.device, run));
   return checks;
 };

packages/client-runtime/src/t3ToolSummary.test.ts

@@ -35,6 +35,15 @@ describe("summarizeT3ToolCalls", () => {
     ).toBe("Sent 2 messages to 1 thread");
   });
 
+  it("counts the pull requests a batch unlink removed", () => {
+    const batch = completed({ states: ["merged"] }, { unlinkedCount: 2 });
+    expect(summarizeT3ToolCalls("unlink-pr", [batch, completed({ number: 3 })]).label).toBe(
+      "Unlinked 3 pull requests",
+    );
+    const uncounted = completed({ states: ["merged"] }, { isError: false });
+    expect(summarizeT3ToolCalls("unlink-pr", [uncounted]).label).toBe("Unlinked pull requests");
+  });
+
   it("excludes failed and unfinished sends even if the provider reports completed", () => {
     const calls: T3ToolSummaryCall[] = [
       completed({ threadId: "success" }, { messageId: "ok", threadId: "success" }),

packages/client-runtime/src/t3ToolSummary.ts

@@ -391,9 +391,19 @@ export function summarizeT3ToolCalls(
     case "link-pr":
       label = phrase("Linked", "link", quantity(selected.length, "pull request"));
       break;
-    case "unlink-pr":
-      label = phrase("Unlinked", "unlink", quantity(selected.length, "pull request"));
+    case "unlink-pr": {
+      let count = 0;
+      let countKnown = true;
+      for (const call of selected) {
+        if (typeof call.output?.unlinkedCount === "number") count += call.output.unlinkedCount;
+        // A batch result too large to compact loses its count, so the label drops the number.
+        else if (Array.isArray(call.input?.states)) countKnown = false;
+        else count += 1;
+      }
+      const object = countKnown ? quantity(count, "pull request") : "pull requests";
+      label = phrase("Unlinked", "unlink", object);
       break;
+    }
     case "watch-pr":
       label = phrase("Watching", "watch", quantity(selected.length, "pull request"));
       break;

packages/shared/src/t3McpToolPresentation.ts

@@ -99,6 +99,11 @@ const T3_MCP_TOOLS: Readonly<Record<string, T3McpToolDefinition>> = {
     "unlink-pr",
     "pull-request",
   ),
+  unlink_pull_requests: tool(
+    ["Unlink", "Unlinking", "Unlinked", "pull requests by state"],
+    "unlink-pr",
+    "pull-request",
+  ),
   list_thread_pull_requests: tool(
     ["Check", "Checking", "Checked", "linked pull requests"],
     "list-prs",

packages/shared/src/toolOutput.test.ts

@@ -29,11 +29,14 @@ describe("compactDynamicToolOutput", () => {
       scheduledTaskId: "scheduled-1",
       status: "failed",
       summary: "A child failed; the tool itself succeeded.",
+      unlinked: [{ repository: "acme/app", state: "merged", numbers: [1] }],
+      unlinkedCount: 1,
     };
     expect(compactDynamicToolOutput(output)).toEqual({
       thread: { threadId: "thread-1" },
       taskId: "task-1",
       scheduledTaskId: "scheduled-1",
+      unlinkedCount: 1,
     });
     expect(output.thread.messages).toEqual(["Private message"]);
   });

packages/shared/src/toolOutput.ts

@@ -43,6 +43,7 @@ interface CompactToolOutput {
   [MCP_APP_OUTPUT_KEY]?: McpAppReference;
   thread?: { threadId: string };
   threads?: Array<{ threadId?: string; status?: "rolled_back" }>;
+  unlinkedCount?: number;
 }
 
 function readResult(value: unknown, budget: ResultReadBudget, depth = 0): ResultEnvelope {
@@ -123,6 +124,8 @@ export function compactDynamicToolOutput(value: unknown): CompactToolOutput | un
       if (id !== undefined) output[key] = id;
     }
     if (data.status === "rolled_back") output.status = "rolled_back";
+    if (typeof data.unlinkedCount === "number" && Number.isSafeInteger(data.unlinkedCount))
+      output.unlinkedCount = data.unlinkedCount;
     const htmlRender = readHtmlRenderReference(data.htmlRender);
     if (htmlRender !== undefined) output.htmlRender = htmlRender;
     const mcpApp = readMcpAppReference(data[MCP_APP_OUTPUT_KEY]);