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

main
ts 310 lines 11.5 KB
Raw
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);