@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 887 lines 30.7 KB
Raw
1 import {
2 McpCapabilityUnavailableError,
3 OrchestratorMcpEnvironmentTarget,
4 OrchestratorMcpFailure,
5 PositiveInt,
6 PullRequestCheck,
7 PullRequestCommentKind,
8 PullRequestChecksState,
9 PullRequestInvolvement,
10 PullRequestListState,
11 PullRequestMergeability,
12 PullRequestMergeMethod,
13 PullRequestReviewVerdict,
14 PullRequestReviewDecision,
15 PullRequestReviewGuide,
16 PullRequestReviewGuideRun,
17 PullRequestState,
18 PullRequestUnavailableError,
19 PullRequestWatchUntil,
20 ThreadPullRequestLinkSource,
21 TrimmedNonEmptyString,
22 ThreadId,
23 } from "@t3tools/contracts";
24 import * as Schema from "effect/Schema";
25 import * as McpSchema from "effect/ai/McpSchema";
26 import * as Tool from "effect/ai/Tool";
27 import * as Toolkit from "effect/ai/Toolkit";
28
29 import * as McpInvocationContext from "../../McpInvocationContext.ts";
30 import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts";
31 import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
32 import * as GitManager from "../../../git/GitManager.ts";
33 import * as ProjectService from "../../../project/ProjectService.ts";
34 import * as PullRequestWatchService from "../../../pullRequest/PullRequestWatchService.ts";
35 import {
36 PullRequestUrlInvalidError,
37 PullRequestTargetIncompleteError,
38 PullRequestHostRequiredError,
39 PullRequestUrlUnavailableError,
40 } from "../../../pullRequest/pullRequestTarget.ts";
41 import * as PullRequestService from "../../../pullRequest/PullRequestService.ts";
42 import * as PullRequestReviewGuideService from "../../../pullRequest/PullRequestReviewGuideService.ts";
43
44 const dependencies = [
45 McpInvocationContext.McpInvocationContext,
46 ThreadManagementService.ThreadManagementService,
47 Orchestrator.OrchestratorV2,
48 ProjectService.ProjectService,
49 ];
50
51 const forgeDependencies = [...dependencies, PullRequestService.PullRequestService];
52
53 const guideDependencies = [
54 ...dependencies,
55 PullRequestReviewGuideService.PullRequestReviewGuideService,
56 ];
57
58 const watchDependencies = [...dependencies, PullRequestWatchService.PullRequestWatchService];
59
60 export const PullRequestTargetInput = Schema.Struct({
61 environmentId: OrchestratorMcpEnvironmentTarget,
62 threadId: Schema.optional(
63 ThreadId.annotate({
64 description: "Thread. Default: this thread.",
65 }),
66 ),
67 url: Schema.optional(TrimmedNonEmptyString),
68 repository: Schema.optional(
69 TrimmedNonEmptyString.annotate({
70 description: "With `number`, when no `url`.",
71 }),
72 ),
73 number: Schema.optional(
74 PositiveInt.annotate({
75 description: "With `repository`, when no `url`.",
76 }),
77 ),
78 host: Schema.optional(
79 TrimmedNonEmptyString.annotate({
80 description: "Default: this project's host.",
81 }),
82 ),
83 });
84 export type PullRequestTargetInput = typeof PullRequestTargetInput.Type;
85
86 export class PullRequestThreadRequiredError extends Schema.TaggedError<PullRequestThreadRequiredError>()(
87 "PullRequestThreadRequiredError",
88 {},
89 ) {
90 override get message(): string {
91 return "Pass threadId: this MCP client is not running inside a T3 thread.";
92 }
93 }
94
95 export class PullRequestLinkFailedError extends Schema.TaggedError<PullRequestLinkFailedError>()(
96 "PullRequestLinkFailedError",
97 { cause: Schema.Defect() },
98 ) {
99 override get message(): string {
100 return "Could not link the pull request.";
101 }
102 }
103
104 export class PullRequestUnlinkFailedError extends Schema.TaggedError<PullRequestUnlinkFailedError>()(
105 "PullRequestUnlinkFailedError",
106 { cause: Schema.Defect() },
107 ) {
108 override get message(): string {
109 return "Could not unlink the pull request.";
110 }
111 }
112
113 export class PullRequestListFailedError extends Schema.TaggedError<PullRequestListFailedError>()(
114 "PullRequestListFailedError",
115 { cause: Schema.Defect() },
116 ) {
117 override get message(): string {
118 return "Could not list the pull request.";
119 }
120 }
121
122 export class PullRequestProjectNotFoundError extends Schema.TaggedError<PullRequestProjectNotFoundError>()(
123 "PullRequestProjectNotFoundError",
124 { repository: Schema.String },
125 ) {
126 override get message(): string {
127 return `No project in this environment is a checkout of ${this.repository}, so its pull requests cannot be read here. Add one with t3_project_create.`;
128 }
129 }
130
131 export class PullRequestGuideFailedError extends Schema.TaggedError<PullRequestGuideFailedError>()(
132 "PullRequestGuideFailedError",
133 { detail: Schema.String, cause: Schema.optional(Schema.Defect()) },
134 ) {
135 override get message(): string {
136 return this.detail;
137 }
138 }
139
140 export class PullRequestForgeError extends Schema.TaggedError<PullRequestForgeError>()(
141 "PullRequestForgeError",
142 { detail: Schema.optional(Schema.String), cause: Schema.optional(Schema.Defect()) },
143 ) {
144 override get message(): string {
145 return this.detail ?? "Could not read this thread's project.";
146 }
147 }
148
149 export class PullRequestBranchHasNoneError extends Schema.TaggedError<PullRequestBranchHasNoneError>()(
150 "PullRequestBranchHasNoneError",
151 {},
152 ) {
153 override get message(): string {
154 return "This thread's branch has no known PR. Pass number, or open one with pull_request_create.";
155 }
156 }
157
158 export class PullRequestCursorInvalidError extends Schema.TaggedError<PullRequestCursorInvalidError>()(
159 "PullRequestCursorInvalidError",
160 {},
161 ) {
162 override get message(): string {
163 return "This cursor is not from this tool. Pass a nextCursor from its last result.";
164 }
165 }
166
167 export class PullRequestNothingToDoError extends Schema.TaggedError<PullRequestNothingToDoError>()(
168 "PullRequestNothingToDoError",
169 { detail: Schema.String },
170 ) {
171 override get message(): string {
172 return this.detail;
173 }
174 }
175
176 export const PullRequestToolError = Schema.Union([
177 OrchestratorMcpFailure,
178 McpCapabilityUnavailableError,
179 PullRequestUrlInvalidError,
180 PullRequestTargetIncompleteError,
181 PullRequestHostRequiredError,
182 PullRequestUrlUnavailableError,
183 PullRequestThreadRequiredError,
184 PullRequestLinkFailedError,
185 PullRequestUnlinkFailedError,
186 PullRequestListFailedError,
187 PullRequestWatchService.PullRequestWatchFailedError,
188 PullRequestUnavailableError,
189 PullRequestWatchService.PullRequestWatchFromSubagentError,
190 PullRequestProjectNotFoundError,
191 PullRequestGuideFailedError,
192 PullRequestForgeError,
193 PullRequestBranchHasNoneError,
194 PullRequestNothingToDoError,
195 PullRequestCursorInvalidError,
196 ]);
197 export type PullRequestToolError = typeof PullRequestToolError.Type;
198
199 const PullRequestIdentity = {
200 host: Schema.String,
201 repository: Schema.String,
202 number: Schema.Int,
203 url: Schema.String,
204 };
205
206 /** A delegated child's report is how its parent learns the PR, so the link result asks for it. */
207 export const CHILD_PULL_REQUEST_REPORT_NEXT =
208 "End your reply with: PR <full URL>, head <SHA>, checks and reviews <state>.";
209
210 export const LinkPullRequestResult = Schema.Struct({
211 ...PullRequestIdentity,
212 alreadyLinked: Schema.Boolean,
213 next: Schema.optional(Schema.String),
214 });
215 export type LinkPullRequestResult = typeof LinkPullRequestResult.Type;
216
217 const PullRequestNumbersByRepository = Schema.Array(
218 Schema.Struct({
219 host: Schema.String,
220 repository: Schema.String,
221 numbers: Schema.Array(Schema.Int),
222 }),
223 );
224
225 export const LinkPullRequestsResult = Schema.Struct({
226 linked: PullRequestNumbersByRepository,
227 alreadyLinked: PullRequestNumbersByRepository,
228 linkedCount: Schema.Int,
229 invalidUrls: Schema.optional(Schema.Array(Schema.String)),
230 next: Schema.optional(Schema.String),
231 });
232 export type LinkPullRequestsResult = typeof LinkPullRequestsResult.Type;
233
234 export const UnlinkPullRequestResult = Schema.Struct({
235 host: Schema.String,
236 repository: Schema.String,
237 number: Schema.Int,
238 wasLinked: Schema.Boolean,
239 });
240 export type UnlinkPullRequestResult = typeof UnlinkPullRequestResult.Type;
241
242 export const UnlinkPullRequestsResult = Schema.Struct({
243 unlinked: Schema.Array(
244 Schema.Struct({
245 host: Schema.String,
246 repository: Schema.String,
247 state: PullRequestState,
248 numbers: Schema.Array(Schema.Int),
249 }),
250 ),
251 unlinkedCount: Schema.Int,
252 remaining: Schema.Int,
253 });
254 export type UnlinkPullRequestsResult = typeof UnlinkPullRequestsResult.Type;
255
256 export const WatchPullRequestResult = Schema.Struct({
257 ...PullRequestIdentity,
258 watching: Schema.Boolean,
259 wasWatching: Schema.Boolean,
260 state: Schema.optional(
261 Schema.Literals(["merged", "closed"]).annotate({
262 description: "The PR already ended, so nothing was watched.",
263 }),
264 ),
265 next: Schema.optional(Schema.String),
266 });
267 export type WatchPullRequestResult = typeof WatchPullRequestResult.Type;
268
269 export const alreadyEndedWatchNext = (state: "merged" | "closed") =>
270 `This PR is already ${state}, so there is nothing to watch. Report that and end your turn.`;
271
272 export const ThreadPullRequestEntry = Schema.Struct({
273 ...PullRequestIdentity,
274 source: ThreadPullRequestLinkSource,
275 watching: Schema.Boolean,
276 state: Schema.NullOr(PullRequestState),
277 title: Schema.NullOr(Schema.String),
278 headBranch: Schema.NullOr(Schema.String),
279 baseBranch: Schema.NullOr(Schema.String),
280 isDraft: Schema.NullOr(Schema.Boolean),
281 stack: Schema.NullOr(
282 Schema.Struct({
283 kind: Schema.Literals(["native", "derived"]),
284 /** 1-based layer from the bottom; siblings share a layer. */
285 position: Schema.Int,
286 size: Schema.Int,
287 }),
288 ),
289 });
290 export type ThreadPullRequestEntry = typeof ThreadPullRequestEntry.Type;
291
292 export const ListThreadPullRequestsResult = Schema.Struct({
293 pullRequests: Schema.Array(ThreadPullRequestEntry),
294 chains: Schema.Array(
295 Schema.Struct({
296 kind: Schema.Literals(["native", "derived"]),
297 /** Bottom to top; each pull request comes before the ones built on it. */
298 numbers: Schema.Array(Schema.Int),
299 }),
300 ),
301 /** Pass as `cursor` for the next page; null on the last page. */
302 nextCursor: Schema.NullOr(Schema.String),
303 });
304 export type ListThreadPullRequestsResult = typeof ListThreadPullRequestsResult.Type;
305
306 const LinkPullRequestTool = Tool.make("link_pull_request", {
307 description:
308 "Link a PR to this thread. T3 shows its status and settles the thread on merge. For several PRs, use `link_pull_requests`.",
309 parameters: PullRequestTargetInput,
310 success: LinkPullRequestResult,
311 failure: PullRequestToolError,
312 dependencies,
313 })
314 .annotate(Tool.Title, "Link pull request to thread")
315 .annotate(Tool.Readonly, false)
316 .annotate(Tool.Destructive, false)
317 .annotate(Tool.Idempotent, true)
318 .annotate(Tool.OpenWorld, false);
319
320 const LinkPullRequestsTool = Tool.make("link_pull_requests", {
321 description:
322 "Link several PRs to a thread. Use it instead of one `link_pull_request` per PR. URLs that are not PRs come back in `invalidUrls`.",
323 parameters: Schema.Struct({
324 environmentId: OrchestratorMcpEnvironmentTarget,
325 threadId: Schema.optional(ThreadId.annotate({ description: "Thread. Default: this thread." })),
326 urls: Schema.Array(TrimmedNonEmptyString).check(Schema.isMinLength(1)),
327 }),
328 success: LinkPullRequestsResult,
329 failure: PullRequestToolError,
330 dependencies,
331 })
332 .annotate(Tool.Title, "Link pull requests to thread")
333 .annotate(Tool.Readonly, false)
334 .annotate(Tool.Destructive, false)
335 .annotate(Tool.Idempotent, true)
336 .annotate(Tool.OpenWorld, false);
337
338 const UnlinkPullRequestTool = Tool.make("unlink_pull_request", {
339 description:
340 "Remove a PR link from this thread. Succeeds with `wasLinked=false` when it was not linked.",
341 parameters: PullRequestTargetInput,
342 success: UnlinkPullRequestResult,
343 failure: PullRequestToolError,
344 dependencies,
345 })
346 .annotate(Tool.Title, "Unlink pull request from thread")
347 .annotate(Tool.Readonly, false)
348 .annotate(Tool.Destructive, true)
349 .annotate(Tool.Idempotent, true)
350 .annotate(Tool.OpenWorld, false);
351
352 const UnlinkPullRequestsTool = Tool.make("unlink_pull_requests", {
353 description:
354 "Unlink a thread's PRs whose last known state is in `states`. Use it instead of one `unlink_pull_request` per PR. PRs with no known state stay linked.",
355 parameters: Schema.Struct({
356 environmentId: OrchestratorMcpEnvironmentTarget,
357 threadId: Schema.optional(ThreadId.annotate({ description: "Thread. Default: this thread." })),
358 states: Schema.Array(PullRequestState).check(Schema.isMinLength(1)),
359 }),
360 success: UnlinkPullRequestsResult,
361 failure: PullRequestToolError,
362 dependencies,
363 })
364 .annotate(Tool.Title, "Unlink pull requests by state")
365 .annotate(Tool.Readonly, false)
366 .annotate(Tool.Destructive, true)
367 .annotate(Tool.Idempotent, true)
368 .annotate(Tool.OpenWorld, false);
369
370 const ListThreadPullRequestsTool = Tool.make("list_thread_pull_requests", {
371 description:
372 "List a thread's PRs, with last known state and stack order (bottom to top). Not an end-of-work check.",
373 parameters: Schema.Struct({
374 environmentId: OrchestratorMcpEnvironmentTarget,
375 threadId: Schema.optional(ThreadId.annotate({ description: "Thread. Default: this thread." })),
376 states: Schema.optional(Schema.Array(PullRequestState)),
377 cursor: Schema.optional(Schema.String),
378 }),
379 success: ListThreadPullRequestsResult,
380 failure: PullRequestToolError,
381 dependencies,
382 })
383 .annotate(Tool.Title, "List thread pull requests")
384 .annotate(Tool.Readonly, true)
385 .annotate(Tool.Destructive, false)
386 .annotate(Tool.Idempotent, true)
387 .annotate(Tool.OpenWorld, false);
388
389 const WatchPullRequestInput = Schema.Struct({
390 ...PullRequestTargetInput.fields,
391 until: Schema.optional(
392 PullRequestWatchUntil.annotate({
393 description:
394 'How long this thread stays working. Omit to keep the current value; a new watch starts at "checks". "checks": until checks finish, for a PR you hand to the user. "merged": until it merges, closes or is unwatched, when you act on it yourself, such as merging after approval.',
395 }),
396 ),
397 });
398
399 const WatchPullRequestTool = Tool.make("watch_pull_request", {
400 description:
401 "Watch an open PR for this thread, linking it if needed. T3 wakes you on failed checks, passed required checks, new comments or reviews, conflicts, and once on merge or close unless you did it via CLI. Handle old comments first; only new ones wake you. After this call, end your turn. The watch stays on: do not call this again on a wake. A wake is not a merge decision. Check readiness yourself.",
402 parameters: WatchPullRequestInput,
403 success: WatchPullRequestResult,
404 failure: PullRequestToolError,
405 dependencies: watchDependencies,
406 })
407 .annotate(Tool.Title, "Watch pull request")
408 .annotate(Tool.Readonly, false)
409 .annotate(Tool.Destructive, false)
410 .annotate(Tool.Idempotent, true)
411 .annotate(Tool.OpenWorld, false)
412 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenFromSubagents);
413
414 const UnwatchPullRequestTool = Tool.make("unwatch_pull_request", {
415 description: "Stop watching a PR for this thread. It stays linked.",
416 parameters: PullRequestTargetInput,
417 success: WatchPullRequestResult,
418 failure: PullRequestToolError,
419 dependencies: watchDependencies,
420 })
421 .annotate(Tool.Title, "Stop watching pull request")
422 .annotate(Tool.Readonly, false)
423 .annotate(Tool.Destructive, false)
424 .annotate(Tool.Idempotent, true)
425 .annotate(Tool.OpenWorld, false)
426 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenFromSubagents);
427
428 const GuideTarget = Schema.Struct({
429 url: PullRequestTargetInput.fields.url,
430 repository: PullRequestTargetInput.fields.repository,
431 number: PullRequestTargetInput.fields.number,
432 host: PullRequestTargetInput.fields.host,
433 });
434
435 const GuideOutcome = Schema.Struct({
436 ...PullRequestIdentity,
437 outcome: Schema.Literals(["started", "running", "failed"]).annotate({
438 description: "started: a run began. running: joined a run for this head. failed: see detail.",
439 }),
440 detail: Schema.NullOr(Schema.String),
441 });
442
443 export const WritePullRequestGuidesResult = Schema.Struct({
444 guides: Schema.Array(GuideOutcome),
445 });
446 export type WritePullRequestGuidesResult = typeof WritePullRequestGuidesResult.Type;
447
448 export const ReadPullRequestGuideResult = Schema.Struct({
449 ...PullRequestIdentity,
450 guide: Schema.NullOr(PullRequestReviewGuide),
451 run: Schema.NullOr(PullRequestReviewGuideRun),
452 currentHeadSha: Schema.NullOr(Schema.String),
453 stale: Schema.Boolean.annotate({
454 description: "True when the PR head moved after the guide was written.",
455 }),
456 });
457 export type ReadPullRequestGuideResult = typeof ReadPullRequestGuideResult.Type;
458
459 const WritePullRequestGuidesTool = Tool.make("write_pull_request_guides", {
460 description:
461 "Write review guides for up to 20 PRs (the tour in the PR Guide tab). Returns once runs start. Each run takes minutes in a temporary checkout. A run for the same head is joined. Read with `read_pull_request_guide`. Fails while guides are off.",
462 parameters: Schema.Struct({
463 environmentId: OrchestratorMcpEnvironmentTarget,
464 pullRequests: Schema.Array(GuideTarget).check(Schema.isMinLength(1), Schema.isMaxLength(20)),
465 }),
466 success: WritePullRequestGuidesResult,
467 failure: PullRequestToolError,
468 dependencies: guideDependencies,
469 })
470 .annotate(Tool.Title, "Write pull request guides")
471 .annotate(Tool.Readonly, false)
472 .annotate(Tool.Destructive, false)
473 .annotate(Tool.Idempotent, false)
474 .annotate(Tool.OpenWorld, true);
475
476 const ReadPullRequestGuideTool = Tool.make("read_pull_request_guide", {
477 description:
478 "Read a PR's stored review guide and run state. `guide` is null when none exists. Never starts a run.",
479 parameters: Schema.Struct({
480 environmentId: OrchestratorMcpEnvironmentTarget,
481 ...GuideTarget.fields,
482 }),
483 success: ReadPullRequestGuideResult,
484 failure: PullRequestToolError,
485 dependencies: guideDependencies,
486 })
487 .annotate(Tool.Title, "Read pull request guide")
488 .annotate(Tool.Readonly, true)
489 .annotate(Tool.Destructive, false)
490 .annotate(Tool.Idempotent, true)
491 .annotate(Tool.OpenWorld, true);
492
493 export const ThreadPullRequestInput = Schema.Struct({
494 environmentId: OrchestratorMcpEnvironmentTarget,
495 number: Schema.optional(PositiveInt.annotate({ description: "Default: the branch's PR." })),
496 repository: Schema.optional(TrimmedNonEmptyString),
497 });
498 export type ThreadPullRequestInput = typeof ThreadPullRequestInput.Type;
499
500 export const PullRequestReadSection = Schema.Literals([
501 "body",
502 "checks",
503 "threads",
504 "comments",
505 "diff",
506 ]);
507 export type PullRequestReadSection = typeof PullRequestReadSection.Type;
508
509 const ReadComment = Schema.Struct({
510 author: Schema.NullOr(Schema.String),
511 body: Schema.String,
512 createdAt: Schema.String,
513 });
514
515 export const ReadPullRequestResult = Schema.Struct({
516 ...PullRequestIdentity,
517 title: Schema.String,
518 state: PullRequestState,
519 isDraft: Schema.Boolean,
520 author: Schema.NullOr(Schema.String),
521 headBranch: Schema.String,
522 baseBranch: Schema.String,
523 headSha: Schema.NullOr(Schema.String),
524 mergeability: PullRequestMergeability,
525 behindBy: Schema.NullOr(Schema.Int),
526 autoMergeEnabled: Schema.NullOr(Schema.Boolean),
527 checks: Schema.Struct({
528 passed: Schema.Int,
529 pending: Schema.Int,
530 failed: Schema.Array(Schema.String),
531 incomplete: Schema.optional(Schema.Literal(true)).annotate({
532 description: "The host could not list some checks; checkRuns says which.",
533 }),
534 }),
535 unresolvedThreads: Schema.Int,
536 unresolvedThreadsTruncated: Schema.optional(Schema.Literal(true)).annotate({
537 description: "unresolvedThreads is a lower bound.",
538 }),
539 body: Schema.optional(Schema.String),
540 checkRuns: Schema.optional(Schema.Array(PullRequestCheck)),
541 conversation: Schema.optional(
542 Schema.Struct({
543 reviewThreads: Schema.optional(
544 Schema.Array(
545 Schema.Struct({
546 id: Schema.String,
547 path: Schema.String,
548 line: Schema.NullOr(Schema.Int),
549 isResolved: Schema.Boolean,
550 isOutdated: Schema.Boolean,
551 comments: Schema.Array(ReadComment),
552 moreComments: Schema.Boolean,
553 }),
554 ),
555 ),
556 comments: Schema.optional(
557 Schema.Array(
558 Schema.Struct({
559 ...ReadComment.fields,
560 id: Schema.String,
561 kind: PullRequestCommentKind,
562 path: Schema.NullOr(Schema.String),
563 reviewState: Schema.NullOr(Schema.String),
564 }),
565 ),
566 ),
567 truncated: Schema.Boolean,
568 nextCursor: Schema.NullOr(Schema.String),
569 }),
570 ),
571 diff: Schema.optional(
572 Schema.Struct({
573 patch: Schema.String,
574 truncated: Schema.Boolean,
575 nextCursor: Schema.NullOr(Schema.String),
576 }),
577 ),
578 });
579 export type ReadPullRequestResult = typeof ReadPullRequestResult.Type;
580
581 export const ListPullRequestsResult = Schema.Struct({
582 pullRequests: Schema.Array(
583 Schema.Struct({
584 number: Schema.Int,
585 title: Schema.String,
586 url: Schema.String,
587 author: Schema.NullOr(Schema.String),
588 headBranch: Schema.String,
589 baseBranch: Schema.String,
590 state: PullRequestState,
591 isDraft: Schema.Boolean,
592 reviewDecision: Schema.NullOr(PullRequestReviewDecision),
593 checksState: Schema.NullOr(PullRequestChecksState),
594 updatedAt: Schema.String,
595 }),
596 ),
597 truncated: Schema.Boolean,
598 nextCursor: Schema.NullOr(Schema.String),
599 });
600 export type ListPullRequestsResult = typeof ListPullRequestsResult.Type;
601
602 export const CreatePullRequestResult = Schema.Struct({
603 ...PullRequestIdentity,
604 created: Schema.Boolean.annotate({
605 description: "False when the branch already had an open PR.",
606 }),
607 next: Schema.optional(Schema.String),
608 });
609 export type CreatePullRequestResult = typeof CreatePullRequestResult.Type;
610
611 export const RespondToPullRequestResult = Schema.Struct({
612 ...PullRequestIdentity,
613 replied: Schema.Boolean,
614 resolved: Schema.NullOr(Schema.Boolean),
615 });
616 export type RespondToPullRequestResult = typeof RespondToPullRequestResult.Type;
617
618 export const MergePullRequestResult = Schema.Struct({
619 ...PullRequestIdentity,
620 state: PullRequestState.annotate({
621 description: "open while auto-merge or a merge queue waits for checks.",
622 }),
623 });
624 export type MergePullRequestResult = typeof MergePullRequestResult.Type;
625
626 const ReadPullRequestTool = Tool.make("pull_request_read", {
627 description: "Read a PR's state and check counts. `include` adds detail.",
628 parameters: Schema.Struct({
629 ...ThreadPullRequestInput.fields,
630 include: Schema.optional(
631 Schema.Array(PullRequestReadSection).annotate({
632 description: "threads: unresolved review threads.",
633 }),
634 ),
635 includeResolved: Schema.optional(Schema.Boolean),
636 cursor: Schema.optional(TrimmedNonEmptyString),
637 }),
638 success: ReadPullRequestResult,
639 failure: PullRequestToolError,
640 dependencies: forgeDependencies,
641 })
642 .annotate(Tool.Title, "Read pull request")
643 .annotate(Tool.Readonly, true)
644 .annotate(Tool.Destructive, false)
645 .annotate(Tool.Idempotent, true)
646 .annotate(Tool.OpenWorld, true)
647 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
648
649 const ListPullRequestsTool = Tool.make("pull_request_list", {
650 description: "List PRs in this thread's repository, recently updated first.",
651 parameters: Schema.Struct({
652 environmentId: OrchestratorMcpEnvironmentTarget,
653 state: Schema.optional(PullRequestListState.annotate({ description: "Default: open." })),
654 involvement: Schema.optional(PullRequestInvolvement),
655 query: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(200))),
656 limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 }))),
657 cursor: Schema.optional(TrimmedNonEmptyString),
658 }),
659 success: ListPullRequestsResult,
660 failure: PullRequestToolError,
661 dependencies: forgeDependencies,
662 })
663 .annotate(Tool.Title, "List pull requests")
664 .annotate(Tool.Readonly, true)
665 .annotate(Tool.Destructive, false)
666 .annotate(Tool.Idempotent, true)
667 .annotate(Tool.OpenWorld, true)
668 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
669
670 const CreatePullRequestTool = Tool.make("pull_request_create", {
671 description: "Push this thread's branch, then open its PR and link it, or return its open PR.",
672 parameters: Schema.Struct({
673 environmentId: OrchestratorMcpEnvironmentTarget,
674 title: TrimmedNonEmptyString,
675 body: Schema.String,
676 base: Schema.optional(TrimmedNonEmptyString),
677 draft: Schema.optional(Schema.Boolean),
678 }),
679 success: CreatePullRequestResult,
680 failure: PullRequestToolError,
681 dependencies: [...forgeDependencies, GitManager.GitManager],
682 })
683 .annotate(Tool.Title, "Create pull request")
684 .annotate(Tool.Readonly, false)
685 .annotate(Tool.Destructive, false)
686 .annotate(Tool.Idempotent, true)
687 .annotate(Tool.OpenWorld, true)
688 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
689
690 const UpdateNames = Schema.Array(TrimmedNonEmptyString).check(
691 Schema.isMinLength(1),
692 Schema.isMaxLength(25),
693 );
694
695 const UpdatePullRequestTool = Tool.make("pull_request_update", {
696 description:
697 "Edit a PR's title, body, labels, or reviewers, close or reopen it, or set ready (false: back to draft).",
698 parameters: Schema.Struct({
699 ...ThreadPullRequestInput.fields,
700 title: Schema.optional(TrimmedNonEmptyString),
701 body: Schema.optional(Schema.String),
702 ready: Schema.optional(Schema.Boolean),
703 state: Schema.optional(Schema.Literals(["open", "closed"])),
704 addLabels: Schema.optional(UpdateNames),
705 removeLabels: Schema.optional(UpdateNames),
706 requestReviewers: Schema.optional(
707 UpdateNames.annotate({ description: "Logins, or org/team for a team." }),
708 ),
709 }),
710 success: Schema.Struct(PullRequestIdentity),
711 failure: PullRequestToolError,
712 dependencies: forgeDependencies,
713 })
714 .annotate(Tool.Title, "Update pull request")
715 .annotate(Tool.Readonly, false)
716 .annotate(Tool.Destructive, false)
717 .annotate(Tool.Idempotent, true)
718 .annotate(Tool.OpenWorld, true)
719 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
720
721 const RespondToPullRequestTool = Tool.make("pull_request_respond", {
722 description:
723 "Reply to, resolve, or reopen a review thread. Without reviewThreadId, comment on the PR.",
724 parameters: Schema.Struct({
725 ...ThreadPullRequestInput.fields,
726 reviewThreadId: Schema.optional(TrimmedNonEmptyString),
727 body: Schema.optional(TrimmedNonEmptyString),
728 resolved: Schema.optional(Schema.Boolean),
729 }),
730 success: RespondToPullRequestResult,
731 failure: PullRequestToolError,
732 dependencies: forgeDependencies,
733 })
734 .annotate(Tool.Title, "Respond on pull request")
735 .annotate(Tool.Readonly, false)
736 .annotate(Tool.Destructive, false)
737 .annotate(Tool.Idempotent, false)
738 .annotate(Tool.OpenWorld, true)
739 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
740
741 export const ReviewLineComment = Schema.Struct({
742 path: TrimmedNonEmptyString,
743 line: PositiveInt,
744 startLine: Schema.optional(PositiveInt),
745 side: Schema.optional(
746 Schema.Literals(["new", "old"]).annotate({
747 description: "Default new. old: line numbers in the base, for removed lines.",
748 }),
749 ),
750 body: TrimmedNonEmptyString,
751 });
752 export type ReviewLineComment = typeof ReviewLineComment.Type;
753
754 const ReviewPullRequestTool = Tool.make("pull_request_review", {
755 description:
756 "Submit a review: approve, request changes, or comment, with optional line comments.",
757 parameters: Schema.Struct({
758 ...ThreadPullRequestInput.fields,
759 verdict: PullRequestReviewVerdict,
760 body: Schema.optional(Schema.String),
761 comments: Schema.optional(Schema.Array(ReviewLineComment).check(Schema.isMaxLength(50))),
762 }),
763 success: Schema.Struct(PullRequestIdentity),
764 failure: PullRequestToolError,
765 dependencies: forgeDependencies,
766 })
767 .annotate(Tool.Title, "Review pull request")
768 .annotate(Tool.Readonly, false)
769 .annotate(Tool.Destructive, false)
770 .annotate(Tool.Idempotent, false)
771 .annotate(Tool.OpenWorld, true)
772 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
773
774 const MergePullRequestTool = Tool.make("pull_request_merge", {
775 description:
776 "Merge a PR. Refuses if the head moved from expectedHeadSha (headSha in pull_request_read).",
777 parameters: Schema.Struct({
778 ...ThreadPullRequestInput.fields,
779 expectedHeadSha: TrimmedNonEmptyString,
780 method: Schema.optional(PullRequestMergeMethod),
781 auto: Schema.optional(
782 Schema.Boolean.annotate({
783 description: "Merge when required checks pass, including later pushes.",
784 }),
785 ),
786 stack: Schema.optional(
787 Schema.Boolean.annotate({
788 description: "Merge this PR and every open stack layer below it at once. Not with auto.",
789 }),
790 ),
791 }),
792 success: MergePullRequestResult,
793 failure: PullRequestToolError,
794 dependencies: forgeDependencies,
795 })
796 .annotate(Tool.Title, "Merge pull request")
797 .annotate(Tool.Readonly, false)
798 .annotate(Tool.Destructive, true)
799 .annotate(Tool.Idempotent, false)
800 .annotate(Tool.OpenWorld, true)
801 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
802
803 export const CheckLogsResult = Schema.Struct({
804 ...PullRequestIdentity,
805 checks: Schema.Array(
806 Schema.Struct({
807 name: Schema.String,
808 url: Schema.NullOr(Schema.String),
809 log: Schema.NullOr(Schema.String),
810 truncated: Schema.Boolean,
811 detail: Schema.NullOr(Schema.String),
812 }),
813 ),
814 });
815 export type CheckLogsResult = typeof CheckLogsResult.Type;
816
817 export const RerunChecksResult = Schema.Struct({
818 ...PullRequestIdentity,
819 checks: Schema.Array(
820 Schema.Struct({
821 name: Schema.String,
822 rerun: Schema.Boolean,
823 detail: Schema.NullOr(Schema.String),
824 }),
825 ),
826 });
827 export type RerunChecksResult = typeof RerunChecksResult.Type;
828
829 const CheckLogsTool = Tool.make("ci_logs", {
830 description: "Read the tail of a PR's failing check logs, or one named check's.",
831 parameters: Schema.Struct({
832 ...ThreadPullRequestInput.fields,
833 check: Schema.optional(TrimmedNonEmptyString),
834 tailLines: Schema.optional(
835 Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 2000 })).annotate({
836 description: "Default: 200.",
837 }),
838 ),
839 }),
840 success: CheckLogsResult,
841 failure: PullRequestToolError,
842 dependencies: forgeDependencies,
843 })
844 .annotate(Tool.Title, "Read CI logs")
845 .annotate(Tool.Readonly, true)
846 .annotate(Tool.Destructive, false)
847 .annotate(Tool.Idempotent, true)
848 .annotate(Tool.OpenWorld, true)
849 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
850
851 const RerunChecksTool = Tool.make("ci_rerun", {
852 description: "Re-run a PR's failing checks, or one named check.",
853 parameters: Schema.Struct({
854 ...ThreadPullRequestInput.fields,
855 check: Schema.optional(TrimmedNonEmptyString),
856 }),
857 success: RerunChecksResult,
858 failure: PullRequestToolError,
859 dependencies: forgeDependencies,
860 })
861 .annotate(Tool.Title, "Re-run CI")
862 .annotate(Tool.Readonly, false)
863 .annotate(Tool.Destructive, false)
864 .annotate(Tool.Idempotent, false)
865 .annotate(Tool.OpenWorld, true)
866 .annotate(McpSchema.EnabledWhen, McpInvocationContext.hiddenWithoutForge);
867
868 export const PullRequestsToolkit = Toolkit.make(
869 LinkPullRequestTool,
870 LinkPullRequestsTool,
871 UnlinkPullRequestTool,
872 UnlinkPullRequestsTool,
873 ListThreadPullRequestsTool,
874 WatchPullRequestTool,
875 UnwatchPullRequestTool,
876 WritePullRequestGuidesTool,
877 ReadPullRequestGuideTool,
878 ReadPullRequestTool,
879 ListPullRequestsTool,
880 CreatePullRequestTool,
881 UpdatePullRequestTool,
882 RespondToPullRequestTool,
883 ReviewPullRequestTool,
884 MergePullRequestTool,
885 CheckLogsTool,
886 RerunChecksTool,
887 );