The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { |
| 2 | threadIssueKeysEqual, |
| 3 | type IssueDetail, |
| 4 | type IssueRef, |
| 5 | type OrchestrationV2ThreadShell, |
| 6 | type ProjectId, |
| 7 | type ThreadId, |
| 8 | } from "@t3tools/contracts"; |
| 9 | import * as Cause from "effect/Cause"; |
| 10 | import * as Effect from "effect/Effect"; |
| 11 | import * as Option from "effect/Option"; |
| 12 | |
| 13 | import * as IssueService from "../../../issue/IssueService.ts"; |
| 14 | import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts"; |
| 15 | import * as ThreadIssueService from "../../../orchestration-v2/ThreadIssueService.ts"; |
| 16 | import * as McpInvocationContext from "../../McpInvocationContext.ts"; |
| 17 | import * as McpToolAccess from "../../McpToolAccess.ts"; |
| 18 | import { |
| 19 | IssueLinkFailedError, |
| 20 | IssueProjectNotFoundError, |
| 21 | IssueProjectRequiredError, |
| 22 | IssuesToolkit, |
| 23 | IssueTargetIncompleteError, |
| 24 | type IssueTargetInput, |
| 25 | IssueThreadNotFoundError, |
| 26 | IssueThreadRequiredError, |
| 27 | type ListThreadIssuesResult, |
| 28 | } from "./tools.ts"; |
| 29 | |
| 30 | /** A resolved reference, with the host the link stores and whether it may be written. */ |
| 31 | interface ResolvedTarget extends IssueRef { |
| 32 | readonly host: string; |
| 33 | readonly url: string | null; |
| 34 | readonly writable: boolean; |
| 35 | /** Present when resolving the URL already read the issue. */ |
| 36 | readonly issue?: IssueDetail; |
| 37 | } |
| 38 | |
| 39 | /** What the tools report from a thread shell; exported so the shape is testable without a layer. */ |
| 40 | function listThreadIssues( |
| 41 | thread: Pick<OrchestrationV2ThreadShell, "issues">, |
| 42 | ): ListThreadIssuesResult { |
| 43 | return { |
| 44 | issues: (thread.issues ?? []).map((link) => ({ |
| 45 | projectId: link.projectId, |
| 46 | tracker: link.tracker, |
| 47 | host: link.host, |
| 48 | scope: link.scope, |
| 49 | key: link.key, |
| 50 | url: link.url, |
| 51 | source: link.source, |
| 52 | displayKey: link.displayKey, |
| 53 | title: link.title, |
| 54 | })), |
| 55 | }; |
| 56 | } |
| 57 | |
| 58 | const make = Effect.gen(function* () { |
| 59 | const engine = yield* Orchestrator.OrchestratorV2; |
| 60 | const issues = yield* IssueService.IssueService; |
| 61 | const threadIssues = yield* ThreadIssueService.ThreadIssueService; |
| 62 | |
| 63 | /** The caller's own thread, read when a tool defaults to it. */ |
| 64 | const callerThread = Effect.fn("IssuesToolkit.callerThread")(function* () { |
| 65 | const scope = yield* McpInvocationContext.requireMcpCapability("issues"); |
| 66 | return scope.thread === undefined |
| 67 | ? undefined |
| 68 | : yield* engine.getThreadShell(scope.thread.threadId).pipe( |
| 69 | Effect.orElseSucceed(() => null), |
| 70 | Effect.map((shell) => shell ?? undefined), |
| 71 | ); |
| 72 | }); |
| 73 | |
| 74 | const requireThread = Effect.fn("IssuesToolkit.requireThread")(function* ( |
| 75 | requested: ThreadId | undefined, |
| 76 | ) { |
| 77 | const scope = yield* McpInvocationContext.requireMcpCapability("issues"); |
| 78 | const threadId = requested ?? scope.thread?.threadId; |
| 79 | if (threadId === undefined) return yield* new IssueThreadRequiredError(); |
| 80 | const thread = yield* engine.getThreadShell(threadId).pipe( |
| 81 | Effect.map(Option.fromNullishOr), |
| 82 | Effect.mapError((cause) => new IssueLinkFailedError({ cause })), |
| 83 | ); |
| 84 | if (Option.isNone(thread) || thread.value.deletedAt !== null) { |
| 85 | return yield* new IssueThreadNotFoundError({ threadId }); |
| 86 | } |
| 87 | return thread.value; |
| 88 | }); |
| 89 | |
| 90 | /** Where a key-only reference is read: the named project's tracker, or the caller's thread's. */ |
| 91 | const requireProjectScope = Effect.fn("IssuesToolkit.requireProjectScope")(function* ( |
| 92 | requested: ProjectId | undefined, |
| 93 | ) { |
| 94 | // A named project skips the caller's thread, so the capability is checked here too. |
| 95 | yield* McpInvocationContext.requireMcpCapability("issues"); |
| 96 | const projectId = requested ?? (yield* callerThread())?.projectId; |
| 97 | if (projectId === undefined) return yield* new IssueProjectRequiredError(); |
| 98 | return yield* issues |
| 99 | .projectScope(projectId) |
| 100 | .pipe(Effect.mapError(() => new IssueProjectNotFoundError({ projectId }))); |
| 101 | }); |
| 102 | |
| 103 | /** |
| 104 | * Turns whichever shape the agent passed into one reference. A URL resolves through whichever |
| 105 | * project here is a checkout of its repository; a key is completed with the named project's |
| 106 | * binding, or the caller's thread's project. |
| 107 | */ |
| 108 | const resolveTarget = Effect.fn("IssuesToolkit.resolveTarget")(function* ( |
| 109 | input: IssueTargetInput, |
| 110 | ) { |
| 111 | yield* McpInvocationContext.requireMcpCapability("issues"); |
| 112 | if (input.url !== undefined) { |
| 113 | const preferred = input.projectId ?? (yield* callerThread())?.projectId; |
| 114 | const resolved = yield* issues.resolveUrl(input.url, preferred); |
| 115 | return { ...resolved, url: input.url } satisfies ResolvedTarget; |
| 116 | } |
| 117 | if (input.key === undefined) return yield* new IssueTargetIncompleteError(); |
| 118 | const scope = yield* requireProjectScope(input.projectId); |
| 119 | return { |
| 120 | ...scope, |
| 121 | key: input.key, |
| 122 | url: null, |
| 123 | writable: true, |
| 124 | } satisfies ResolvedTarget; |
| 125 | }); |
| 126 | |
| 127 | /** Without a URL when the issue was named by key and never read: an empty one is not reusable. */ |
| 128 | const identityOf = (target: ResolvedTarget) => ({ |
| 129 | projectId: target.projectId, |
| 130 | tracker: target.tracker, |
| 131 | host: target.host, |
| 132 | scope: target.scope, |
| 133 | key: target.key, |
| 134 | ...(target.url === null ? {} : { url: target.url }), |
| 135 | }); |
| 136 | |
| 137 | const refOf = (target: ResolvedTarget): IssueRef & { readonly host: string } => ({ |
| 138 | projectId: target.projectId, |
| 139 | tracker: target.tracker, |
| 140 | host: target.host, |
| 141 | scope: target.scope, |
| 142 | key: target.key, |
| 143 | }); |
| 144 | |
| 145 | const readIssue = (target: ResolvedTarget) => |
| 146 | target.issue === undefined ? issues.detail(refOf(target)) : Effect.succeed(target.issue); |
| 147 | |
| 148 | /** A link needs the issue's URL, which a key-only reference does not carry; one read fills it. */ |
| 149 | const linkFailure = <E>(cause: Cause.Cause<E>) => |
| 150 | Cause.hasInterruptsOnly(cause) |
| 151 | ? Effect.failCause(cause as Cause.Cause<never>) |
| 152 | : Effect.fail(new IssueLinkFailedError({ cause })); |
| 153 | |
| 154 | /** A tool that changes `threadId`, or the caller's own thread when it is omitted. */ |
| 155 | const writesThread = <P extends { readonly threadId?: ThreadId | undefined }, A, E, R>( |
| 156 | handle: (params: P) => Effect.Effect<A, E, R>, |
| 157 | ) => McpToolAccess.writesThreads((params: P) => [params.threadId], handle); |
| 158 | |
| 159 | return { |
| 160 | list_issues: McpToolAccess.reads((input) => |
| 161 | Effect.gen(function* () { |
| 162 | const { projectId } = yield* requireProjectScope(input.projectId); |
| 163 | const result = yield* issues.list({ |
| 164 | projectId, |
| 165 | state: input.state ?? "open", |
| 166 | ...(input.query === undefined ? {} : { query: input.query }), |
| 167 | ...(input.limit === undefined ? {} : { limit: input.limit }), |
| 168 | ...(input.cursors === undefined ? {} : { cursors: input.cursors }), |
| 169 | }); |
| 170 | return { |
| 171 | issues: result.entries.map((entry) => ({ |
| 172 | projectId: entry.projectId, |
| 173 | tracker: entry.tracker, |
| 174 | host: entry.host, |
| 175 | scope: entry.scope, |
| 176 | key: entry.key, |
| 177 | url: entry.url, |
| 178 | displayKey: entry.displayKey, |
| 179 | title: entry.title, |
| 180 | state: entry.state, |
| 181 | author: entry.author?.login ?? null, |
| 182 | assignees: entry.assignees.map((actor) => actor.login), |
| 183 | labels: entry.labels.map((label) => label.name), |
| 184 | updatedAt: entry.updatedAt, |
| 185 | commentCount: entry.commentCount, |
| 186 | })), |
| 187 | nextCursors: result.nextCursors, |
| 188 | errors: result.errors.map((error) => ({ |
| 189 | projectId: error.projectId, |
| 190 | message: error.message, |
| 191 | })), |
| 192 | }; |
| 193 | }), |
| 194 | ), |
| 195 | read_issue: McpToolAccess.reads((input) => |
| 196 | Effect.gen(function* () { |
| 197 | const target = yield* resolveTarget(input); |
| 198 | const detail = yield* readIssue(target); |
| 199 | return { |
| 200 | ...identityOf(target), |
| 201 | url: target.url ?? detail.url, |
| 202 | displayKey: detail.displayKey, |
| 203 | title: detail.title, |
| 204 | state: detail.state, |
| 205 | writable: detail.writable, |
| 206 | capabilities: detail.capabilities, |
| 207 | states: detail.states, |
| 208 | author: detail.author?.login ?? null, |
| 209 | assignees: detail.assignees.map((actor) => actor.login), |
| 210 | labels: detail.labels.map((label) => label.name), |
| 211 | createdAt: detail.createdAt, |
| 212 | updatedAt: detail.updatedAt, |
| 213 | closedAt: detail.closedAt, |
| 214 | body: detail.body, |
| 215 | comments: detail.comments.map((comment) => ({ |
| 216 | id: comment.id, |
| 217 | author: comment.author?.login ?? null, |
| 218 | body: comment.body, |
| 219 | createdAt: comment.createdAt, |
| 220 | })), |
| 221 | commentsTruncated: detail.commentsCursor !== null, |
| 222 | linkedPullRequests: detail.linkedPullRequests.map((pullRequest) => ({ |
| 223 | url: pullRequest.url, |
| 224 | title: pullRequest.title, |
| 225 | state: pullRequest.state, |
| 226 | closesIssue: pullRequest.closesIssue, |
| 227 | })), |
| 228 | }; |
| 229 | }), |
| 230 | ), |
| 231 | create_issue: McpToolAccess.writesWithCapability((input) => |
| 232 | Effect.gen(function* () { |
| 233 | const scope = yield* requireProjectScope(input.projectId); |
| 234 | const created = yield* issues.create({ |
| 235 | ...scope, |
| 236 | title: input.title, |
| 237 | body: input.body ?? "", |
| 238 | labels: input.labels ?? [], |
| 239 | assignees: input.assignees ?? [], |
| 240 | }); |
| 241 | return { |
| 242 | ...scope, |
| 243 | key: created.key, |
| 244 | url: created.url, |
| 245 | displayKey: created.displayKey, |
| 246 | }; |
| 247 | }), |
| 248 | ), |
| 249 | comment_on_issue: McpToolAccess.writesWithCapability((input) => |
| 250 | Effect.gen(function* () { |
| 251 | const target = yield* resolveTarget(input); |
| 252 | yield* issues.comment({ ...refOf(target), body: input.body }); |
| 253 | return identityOf(target); |
| 254 | }), |
| 255 | ), |
| 256 | set_issue_state: McpToolAccess.writesWithCapability((input) => |
| 257 | Effect.gen(function* () { |
| 258 | const target = yield* resolveTarget(input); |
| 259 | yield* issues.setState({ |
| 260 | ...refOf(target), |
| 261 | state: input.state, |
| 262 | }); |
| 263 | return identityOf(target); |
| 264 | }), |
| 265 | ), |
| 266 | link_issue: writesThread((input) => |
| 267 | Effect.gen(function* () { |
| 268 | const thread = yield* requireThread(input.threadId); |
| 269 | const target = yield* resolveTarget({ |
| 270 | ...input, |
| 271 | projectId: input.projectId ?? thread.projectId, |
| 272 | }); |
| 273 | // Reading the issue proves it exists and names it for the thread's row. |
| 274 | const detail = yield* readIssue(target); |
| 275 | const url = target.url ?? detail.url; |
| 276 | const { alreadyLinked } = yield* threadIssues |
| 277 | .link({ |
| 278 | threadId: thread.id, |
| 279 | ref: refOf(target), |
| 280 | url, |
| 281 | displayKey: detail.displayKey, |
| 282 | title: detail.title, |
| 283 | source: "agent", |
| 284 | }) |
| 285 | .pipe(Effect.catchCause(linkFailure)); |
| 286 | return { ...identityOf(target), url, alreadyLinked }; |
| 287 | }), |
| 288 | ), |
| 289 | unlink_issue: writesThread((input) => |
| 290 | Effect.gen(function* () { |
| 291 | const thread = yield* requireThread(input.threadId); |
| 292 | const target = yield* resolveTarget({ |
| 293 | ...input, |
| 294 | projectId: input.projectId ?? thread.projectId, |
| 295 | }); |
| 296 | const existing = (thread.issues ?? []).find((link) => threadIssueKeysEqual(link, target)); |
| 297 | if (existing === undefined) return { ...identityOf(target), wasLinked: false }; |
| 298 | const { wasLinked } = yield* threadIssues |
| 299 | .unlink({ threadId: thread.id, key: target }) |
| 300 | .pipe(Effect.catchCause(linkFailure)); |
| 301 | return { ...identityOf(target), url: existing.url, wasLinked }; |
| 302 | }), |
| 303 | ), |
| 304 | list_thread_issues: McpToolAccess.reads((input) => |
| 305 | requireThread(input.threadId).pipe(Effect.map(listThreadIssues)), |
| 306 | ), |
| 307 | } satisfies McpToolAccess.Handlers<typeof IssuesToolkit.tools>; |
| 308 | }); |
| 309 | |
| 310 | export const layer = McpToolAccess.toLayer(IssuesToolkit, make); |