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

main
ts 385 lines 12.5 KB
Raw
1 import {
2 IssueCapabilities,
3 IssueListState,
4 IssueOperationError,
5 IssueState,
6 IssueTrackerKind,
7 IssueUnavailableError,
8 McpCapabilityUnavailableError,
9 OrchestratorMcpFailure,
10 ProjectId,
11 ThreadId,
12 ThreadIssueLinkSource,
13 TrimmedNonEmptyString,
14 } from "@t3tools/contracts";
15 import * as Schema from "effect/Schema";
16 import * as Tool from "effect/ai/Tool";
17 import * as Toolkit from "effect/ai/Toolkit";
18
19 import * as IssueService from "../../../issue/IssueService.ts";
20 import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts";
21 import * as ThreadIssueService from "../../../orchestration-v2/ThreadIssueService.ts";
22 import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
23 import * as ProjectService from "../../../project/ProjectService.ts";
24 import * as McpInvocationContext from "../../McpInvocationContext.ts";
25
26 const dependencies = [
27 McpInvocationContext.McpInvocationContext,
28 ThreadManagementService.ThreadManagementService,
29 Orchestrator.OrchestratorV2,
30 ProjectService.ProjectService,
31 IssueService.IssueService,
32 ThreadIssueService.ThreadIssueService,
33 ];
34
35 /**
36 * Either the issue's URL, or its key within a project's tracker. A key alone is read through the
37 * project named, or the caller's own thread's project; a URL is read through whichever project
38 * here is a checkout of that repository, read-only when none is.
39 */
40 export const IssueTargetInput = Schema.Struct({
41 url: Schema.optional(
42 TrimmedNonEmptyString.annotate({
43 description: "The issue's web URL. Preferred when you have it.",
44 }),
45 ),
46 key: Schema.optional(
47 TrimmedNonEmptyString.annotate({
48 description: "The issue's key in the project's tracker, such as its number.",
49 }),
50 ),
51 projectId: Schema.optional(
52 ProjectId.annotate({
53 description: "Project whose tracker holds key. Defaults to this thread's project.",
54 }),
55 ),
56 });
57 export type IssueTargetInput = typeof IssueTargetInput.Type;
58
59 const ThreadTargetInput = Schema.Struct({
60 threadId: Schema.optional(
61 ThreadId.annotate({ description: "Thread to act on. Omit for this thread." }),
62 ),
63 });
64
65 export class IssueTargetIncompleteError extends Schema.TaggedError<IssueTargetIncompleteError>()(
66 "IssueTargetIncompleteError",
67 {},
68 ) {
69 override get message(): string {
70 return "Pass either url, or key (with projectId when not running inside a T3 thread).";
71 }
72 }
73
74 export class IssueProjectRequiredError extends Schema.TaggedError<IssueProjectRequiredError>()(
75 "IssueProjectRequiredError",
76 {},
77 ) {
78 override get message(): string {
79 return "Pass projectId: this MCP client is not running inside a T3 thread.";
80 }
81 }
82
83 export class IssueThreadRequiredError extends Schema.TaggedError<IssueThreadRequiredError>()(
84 "IssueThreadRequiredError",
85 {},
86 ) {
87 override get message(): string {
88 return "Pass threadId: this MCP client is not running inside a T3 thread.";
89 }
90 }
91
92 export class IssueThreadNotFoundError extends Schema.TaggedError<IssueThreadNotFoundError>()(
93 "IssueThreadNotFoundError",
94 { threadId: Schema.String },
95 ) {
96 override get message(): string {
97 return `Thread ${this.threadId} was not found.`;
98 }
99 }
100
101 export class IssueProjectNotFoundError extends Schema.TaggedError<IssueProjectNotFoundError>()(
102 "IssueProjectNotFoundError",
103 { projectId: Schema.String },
104 ) {
105 override get message(): string {
106 return `Project ${this.projectId} was not found or has no issue tracker.`;
107 }
108 }
109
110 export class IssueLinkFailedError extends Schema.TaggedError<IssueLinkFailedError>()(
111 "IssueLinkFailedError",
112 { cause: Schema.Defect() },
113 ) {
114 override get message(): string {
115 return "Could not change the issue link.";
116 }
117 }
118
119 export const IssueToolError = Schema.Union([
120 OrchestratorMcpFailure,
121 McpCapabilityUnavailableError,
122 IssueUnavailableError,
123 IssueOperationError,
124 IssueTargetIncompleteError,
125 IssueProjectRequiredError,
126 IssueThreadRequiredError,
127 IssueThreadNotFoundError,
128 IssueProjectNotFoundError,
129 IssueLinkFailedError,
130 ]);
131 export type IssueToolError = typeof IssueToolError.Type;
132
133 /** How a tool names an issue back: enough to pass to any other issue tool. */
134 const IssueKeyIdentity = {
135 projectId: ProjectId,
136 tracker: IssueTrackerKind,
137 host: Schema.String,
138 scope: Schema.String,
139 key: Schema.String,
140 };
141 const IssueIdentity = { ...IssueKeyIdentity, url: Schema.String };
142 /** A write named by key alone never read the issue, so it has no URL to hand back. */
143 const IssueIdentityAfterWrite = { ...IssueKeyIdentity, url: Schema.optional(Schema.String) };
144
145 export const IssueEntry = Schema.Struct({
146 ...IssueIdentity,
147 displayKey: Schema.String,
148 title: Schema.String,
149 state: IssueState,
150 author: Schema.NullOr(Schema.String),
151 assignees: Schema.Array(Schema.String),
152 labels: Schema.Array(Schema.String),
153 updatedAt: Schema.String,
154 commentCount: Schema.Int,
155 });
156 export type IssueEntry = typeof IssueEntry.Type;
157
158 export const ListIssuesResult = Schema.Struct({
159 issues: Schema.Array(IssueEntry),
160 /** Pass back as `cursors` to read the next slice of each scope that has one. */
161 nextCursors: Schema.Record(Schema.String, Schema.String),
162 errors: Schema.Array(Schema.Struct({ projectId: ProjectId, message: Schema.String })),
163 });
164 export type ListIssuesResult = typeof ListIssuesResult.Type;
165
166 export const ReadIssueResult = Schema.Struct({
167 ...IssueIdentity,
168 displayKey: Schema.String,
169 title: Schema.String,
170 state: IssueState,
171 /** False for an issue outside every project's own scope: it can be read, not changed. */
172 writable: Schema.Boolean,
173 capabilities: IssueCapabilities,
174 states: Schema.Array(IssueState),
175 author: Schema.NullOr(Schema.String),
176 assignees: Schema.Array(Schema.String),
177 labels: Schema.Array(Schema.String),
178 createdAt: Schema.String,
179 updatedAt: Schema.String,
180 closedAt: Schema.NullOr(Schema.String),
181 body: Schema.String,
182 comments: Schema.Array(
183 Schema.Struct({
184 id: Schema.String,
185 author: Schema.NullOr(Schema.String),
186 body: Schema.String,
187 createdAt: Schema.String,
188 }),
189 ),
190 /** Older comments exist beyond the page returned. */
191 commentsTruncated: Schema.Boolean,
192 linkedPullRequests: Schema.Array(
193 Schema.Struct({
194 url: Schema.String,
195 title: Schema.String,
196 state: Schema.String,
197 closesIssue: Schema.Boolean,
198 }),
199 ),
200 });
201 export type ReadIssueResult = typeof ReadIssueResult.Type;
202
203 export const CreateIssueResult = Schema.Struct({
204 ...IssueIdentity,
205 displayKey: Schema.String,
206 });
207 export type CreateIssueResult = typeof CreateIssueResult.Type;
208
209 export const IssueWriteResult = Schema.Struct({ ...IssueIdentityAfterWrite });
210
211 export const ThreadIssueEntry = Schema.Struct({
212 ...IssueIdentity,
213 source: ThreadIssueLinkSource,
214 /** As the tracker named the issue when it was linked; `read_issue` has its current state. */
215 displayKey: Schema.String,
216 title: Schema.String,
217 });
218 export type ThreadIssueEntry = typeof ThreadIssueEntry.Type;
219
220 export const LinkIssueResult = Schema.Struct({
221 ...IssueIdentity,
222 alreadyLinked: Schema.Boolean.annotate({
223 description: "True when the issue was linked to this thread before the call.",
224 }),
225 });
226 export type LinkIssueResult = typeof LinkIssueResult.Type;
227
228 export const UnlinkIssueResult = Schema.Struct({
229 ...IssueIdentityAfterWrite,
230 wasLinked: Schema.Boolean.annotate({
231 description: "False when the issue was not linked to this thread to begin with.",
232 }),
233 });
234 export type UnlinkIssueResult = typeof UnlinkIssueResult.Type;
235
236 export const ListThreadIssuesResult = Schema.Struct({
237 issues: Schema.Array(ThreadIssueEntry),
238 });
239 export type ListThreadIssuesResult = typeof ListThreadIssuesResult.Type;
240
241 const ListIssuesTool = Tool.make("list_issues", {
242 description:
243 "List issues in a project's tracker, newest updated first. Pass the returned nextCursors as cursors for the next page.",
244 parameters: Schema.Struct({
245 projectId: Schema.optional(
246 ProjectId.annotate({ description: "Defaults to this thread's project." }),
247 ),
248 state: Schema.optional(IssueListState.annotate({ description: "Defaults to open." })),
249 query: Schema.optional(
250 TrimmedNonEmptyString.check(Schema.isMaxLength(200)).annotate({
251 description: "Free text the tracker matches itself.",
252 }),
253 ),
254 limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 100 }))),
255 cursors: Schema.optional(Schema.Record(Schema.String, Schema.String)),
256 }),
257 success: ListIssuesResult,
258 failure: IssueToolError,
259 dependencies,
260 })
261 .annotate(Tool.Title, "List issues")
262 .annotate(Tool.Readonly, true)
263 .annotate(Tool.Destructive, false)
264 .annotate(Tool.Idempotent, true)
265 .annotate(Tool.OpenWorld, true);
266
267 const ReadIssueTool = Tool.make("read_issue", {
268 description:
269 "Read an issue: body, state, labels, assignees, recent comments and linked pull requests. Pass its url, or its key.",
270 parameters: IssueTargetInput,
271 success: ReadIssueResult,
272 failure: IssueToolError,
273 dependencies,
274 })
275 .annotate(Tool.Title, "Read issue")
276 .annotate(Tool.Readonly, true)
277 .annotate(Tool.Destructive, false)
278 .annotate(Tool.Idempotent, true)
279 .annotate(Tool.OpenWorld, true);
280
281 const CreateIssueTool = Tool.make("create_issue", {
282 description: "File an issue in a project's tracker.",
283 parameters: Schema.Struct({
284 projectId: Schema.optional(
285 ProjectId.annotate({ description: "Defaults to this thread's project." }),
286 ),
287 title: TrimmedNonEmptyString.check(Schema.isMaxLength(1024)),
288 body: Schema.optional(Schema.String.check(Schema.isMaxLength(65_536))),
289 labels: Schema.optional(Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(50))),
290 assignees: Schema.optional(Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(25))),
291 }),
292 success: CreateIssueResult,
293 failure: IssueToolError,
294 dependencies,
295 })
296 .annotate(Tool.Title, "Create issue")
297 .annotate(Tool.Readonly, false)
298 .annotate(Tool.Destructive, false)
299 .annotate(Tool.Idempotent, false)
300 .annotate(Tool.OpenWorld, true);
301
302 const CommentOnIssueTool = Tool.make("comment_on_issue", {
303 description: "Post a comment on an issue.",
304 parameters: Schema.Struct({
305 ...IssueTargetInput.fields,
306 body: Schema.String.check(Schema.isNonEmpty()).check(Schema.isMaxLength(65_536)),
307 }),
308 success: IssueWriteResult,
309 failure: IssueToolError,
310 dependencies,
311 })
312 .annotate(Tool.Title, "Comment on issue")
313 .annotate(Tool.Readonly, false)
314 .annotate(Tool.Destructive, false)
315 .annotate(Tool.Idempotent, false)
316 .annotate(Tool.OpenWorld, true);
317
318 const SetIssueStateTool = Tool.make("set_issue_state", {
319 description: "Move an issue to one of its states. read_issue lists them under states.",
320 parameters: Schema.Struct({
321 ...IssueTargetInput.fields,
322 state: TrimmedNonEmptyString.annotate({
323 description: "A state name from read_issue's states.",
324 }),
325 }),
326 success: IssueWriteResult,
327 failure: IssueToolError,
328 dependencies,
329 })
330 .annotate(Tool.Title, "Set issue state")
331 .annotate(Tool.Readonly, false)
332 .annotate(Tool.Destructive, false)
333 .annotate(Tool.Idempotent, true)
334 .annotate(Tool.OpenWorld, true);
335
336 const LinkIssueTool = Tool.make("link_issue", {
337 description:
338 "Link an issue to a thread so T3 Code shows it beside the thread. Link every issue you work on or file.",
339 parameters: Schema.Struct({ ...IssueTargetInput.fields, ...ThreadTargetInput.fields }),
340 success: LinkIssueResult,
341 failure: IssueToolError,
342 dependencies,
343 })
344 .annotate(Tool.Title, "Link issue to thread")
345 .annotate(Tool.Readonly, false)
346 .annotate(Tool.Destructive, false)
347 .annotate(Tool.Idempotent, true)
348 .annotate(Tool.OpenWorld, false);
349
350 const UnlinkIssueTool = Tool.make("unlink_issue", {
351 description: "Remove an issue link from a thread. The issue itself is not changed.",
352 parameters: Schema.Struct({ ...IssueTargetInput.fields, ...ThreadTargetInput.fields }),
353 success: UnlinkIssueResult,
354 failure: IssueToolError,
355 dependencies,
356 })
357 .annotate(Tool.Title, "Unlink issue from thread")
358 .annotate(Tool.Readonly, false)
359 .annotate(Tool.Destructive, true)
360 .annotate(Tool.Idempotent, true)
361 .annotate(Tool.OpenWorld, false);
362
363 const ListThreadIssuesTool = Tool.make("list_thread_issues", {
364 description: "List the issues linked to a thread.",
365 parameters: ThreadTargetInput,
366 success: ListThreadIssuesResult,
367 failure: IssueToolError,
368 dependencies,
369 })
370 .annotate(Tool.Title, "List thread issues")
371 .annotate(Tool.Readonly, true)
372 .annotate(Tool.Destructive, false)
373 .annotate(Tool.Idempotent, true)
374 .annotate(Tool.OpenWorld, false);
375
376 export const IssuesToolkit = Toolkit.make(
377 ListIssuesTool,
378 ReadIssueTool,
379 CreateIssueTool,
380 CommentOnIssueTool,
381 SetIssueStateTool,
382 LinkIssueTool,
383 UnlinkIssueTool,
384 ListThreadIssuesTool,
385 );