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
| 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 | ); |