The best way to control Claude Code, Codex and more from any computer or phone
fix(server): agents read a Linear issue once when given its link (#38425)
Co-authored-by: Grok 4.7 <noreply@x.ai>
Wout Stiens committed
Nov 18, 2026 at 04:52 UTC
b8b5affac42a8fd55d89214996c28afdb3c54ab1
3 files changed
+162
-60
apps/server/src/issue/IssueService.ts
+51
-35
@@ -38,6 +38,7 @@ import {
38
isStandaloneIssueTracker,
39
type IssueTrackerApi,
40
type StandaloneIssueTrackerApi,
41
+ type TrackerIssueDetail,
42
} from "@t3tools/source-control-core/server/IssueTracker";
43
import { parseUrl } from "@t3tools/shared/url";
44
@@ -164,13 +165,18 @@ export class IssueService extends Context.Service<
165
) => Effect.Effect<IssueScopeRef & { readonly host: string }, IssueError>;
166
/**
167
* Resolve through a matching project, preferring `preferredProjectId`; other scopes are read-only.
167
- * Standalone links must match the workspace in the issue's canonical URL from the connected tracker.
168
+ * Standalone links must match the workspace in the issue's canonical URL from the connected
169
+ * tracker; that read comes back as `issue`, so callers need not read it again.
170
*/
171
readonly resolveUrl: (
172
url: string,
173
preferredProjectId?: ProjectId,
174
) => Effect.Effect<
173
- IssueRef & { readonly host: string; readonly writable: boolean },
175
+ IssueRef & {
176
+ readonly host: string;
177
+ readonly writable: boolean;
178
+ readonly issue?: IssueDetail;
179
+ },
180
IssueError
181
>;
182
}
@@ -449,6 +455,20 @@ const make = Effect.gen(function* () {
455
};
456
});
457
458
+ const toDetail = (
459
+ project: SupportedProject & { readonly writable: boolean },
460
+ issue: TrackerIssueDetail,
461
+ ): IssueDetail => ({
462
+ ...issue,
463
+ tracker: project.tracker,
464
+ host: project.host,
465
+ scope: project.scope,
466
+ projectId: project.project.id,
467
+ projectTitle: project.project.title,
468
+ writable: project.writable,
469
+ capabilities: project.api.capabilities,
470
+ });
471
+
472
const detail: IssueService["Service"]["detail"] = (input) =>
473
requireProject(input).pipe(
474
Effect.flatMap((project) =>
@@ -461,16 +481,7 @@ const make = Effect.gen(function* () {
481
})
482
.pipe(
483
Effect.mapError(toIssueError("detail")),
464
- Effect.map((issue): IssueDetail => ({
465
- ...issue,
466
- tracker: project.tracker,
467
- host: project.host,
468
- scope: project.scope,
469
- projectId: project.project.id,
470
- projectTitle: project.project.title,
471
- writable: project.writable,
472
- capabilities: project.api.capabilities,
473
- })),
484
+ Effect.map((issue) => toDetail(project, issue)),
485
),
486
),
487
);
@@ -692,34 +703,39 @@ const make = Effect.gen(function* () {
703
if (lender === undefined) {
704
return yield* new IssueUnavailableError({ reason: "tracker-unsupported" });
705
}
695
- if (standalone !== null) {
696
- // Team keys repeat across workspaces; only the credential's canonical issue URL identifies one.
697
- const issue = yield* lender.api
698
- .getIssue({
699
- cwd: lender.project.workspaceRoot,
700
- host: lender.host,
701
- scope: link.scope,
702
- key: link.key,
703
- })
704
- .pipe(Effect.mapError(toIssueError("resolveUrl")));
705
- const canonicalUrl = parseUrl(issue.url);
706
- const canonical = canonicalUrl === null ? null : standalone.api.parseIssueUrl(canonicalUrl);
707
- if (canonical === null || canonical.workspace !== standalone.link.workspace) {
708
- return yield* new IssueOperationError({
709
- operation: "resolveUrl",
710
- reason: "not-found",
711
- detail: "This issue URL does not belong to the connected workspace.",
712
- });
713
- }
714
- }
715
- return {
706
+ const served = {
707
+ ...lender,
708
+ scope: own === undefined ? link.scope : lender.scope,
709
+ writable: own !== undefined,
710
+ };
711
+ const resolved = {
712
projectId: lender.project.id,
713
tracker: lender.tracker,
714
host: lender.host,
719
- scope: own === undefined ? link.scope : lender.scope,
715
+ scope: served.scope,
716
key: link.key,
721
- writable: own !== undefined,
717
+ writable: served.writable,
718
};
719
+ if (standalone === null) return resolved;
720
+ // Team keys repeat across workspaces; only the credential's canonical issue URL identifies one.
721
+ const issue = yield* lender.api
722
+ .getIssue({
723
+ cwd: lender.project.workspaceRoot,
724
+ host: lender.host,
725
+ scope: link.scope,
726
+ key: link.key,
727
+ })
728
+ .pipe(Effect.mapError(toIssueError("resolveUrl")));
729
+ const canonicalUrl = parseUrl(issue.url);
730
+ const canonical = canonicalUrl === null ? null : standalone.api.parseIssueUrl(canonicalUrl);
731
+ if (canonical === null || canonical.workspace !== standalone.link.workspace) {
732
+ return yield* new IssueOperationError({
733
+ operation: "resolveUrl",
734
+ reason: "not-found",
735
+ detail: "This issue URL does not belong to the connected workspace.",
736
+ });
737
+ }
738
+ return { ...resolved, issue: toDetail(served, issue) };
739
},
740
);
741
apps/server/src/mcp/toolkits/issues/handlers.test.ts
+103
-23
@@ -10,6 +10,10 @@ import {
10
SourceControlProviderKind,
11
} from "@t3tools/contracts";
12
import { describe, expect, it } from "@effect/vitest";
13
+import {
14
+ IssueTrackerError,
15
+ type StandaloneIssueTrackerApi,
16
+} from "@t3tools/source-control-core/server/IssueTracker";
17
import * as Effect from "effect/Effect";
18
import * as Layer from "effect/Layer";
19
import * as Option from "effect/Option";
@@ -18,10 +22,13 @@ import * as Stream from "effect/Stream";
22
import type { Tool } from "effect/ai";
23
24
import * as IssueService from "../../../issue/IssueService.ts";
25
+import * as IssueTrackerRegistry from "../../../issue/IssueTrackerRegistry.ts";
26
import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts";
27
import * as ThreadIssueService from "../../../orchestration-v2/ThreadIssueService.ts";
28
import { v2PullRequestThread } from "../../../orchestration-v2/testkit/pullRequestFixtures.ts";
29
+import * as IssueTrackerBindings from "../../../persistence/IssueTrackerBindings.ts";
30
import * as ProjectService from "../../../project/ProjectService.ts";
31
+import * as RepositoryIdentityResolver from "../../../project/RepositoryIdentityResolver.ts";
32
import * as McpInvocationContext from "../../McpInvocationContext.ts";
33
import * as McpToolAccess from "../../McpToolAccess.ts";
34
import * as McpToolAccessTestkit from "../../McpToolAccess.testkit.ts";
@@ -133,37 +140,41 @@ const detail: IssueDetail = {
140
linkedPullRequests: [],
141
};
142
143
+const projectLayer = Layer.mock(ProjectService.ProjectService)({
144
+ getShell: (id) => Effect.succeed(id === PROJECT_ID ? Option.some(project) : Option.none()),
145
+ listShells: () => Effect.succeed([project]),
146
+});
147
+
148
const makeHarness = Effect.fn("makeIssuesToolkitHarness")(function* (
149
issues: ReadonlyArray<ThreadIssueLink> = [],
150
+ issueLayer?: Layer.Layer<IssueService.IssueService>,
151
) {
152
const links = yield* Ref.make<ReadonlyArray<ThreadIssueService.LinkThreadIssueInput>>([]);
153
const layerDependencies = Layer.mergeAll(
141
- Layer.mock(ProjectService.ProjectService)({
142
- getShell: (id) => Effect.succeed(id === PROJECT_ID ? Option.some(project) : Option.none()),
143
- listShells: () => Effect.succeed([project]),
144
- }),
154
+ projectLayer,
155
Layer.mock(Orchestrator.OrchestratorV2)({
156
getThreadShell: (id) => Effect.succeed(id === THREAD_ID ? makeThread(issues) : null),
157
}),
148
- Layer.mock(IssueService.IssueService)({
149
- detail: () => Effect.succeed(detail),
150
- projectScope: (projectId) =>
151
- Effect.succeed({
152
- projectId,
153
- tracker: GITHUB,
154
- host: "github.com",
155
- scope: "t3tools/t3code",
156
- }),
157
- resolveUrl: (url) =>
158
- Effect.succeed({
159
- projectId: PROJECT_ID,
160
- tracker: GITHUB,
161
- host: "github.com",
162
- scope: "t3tools/t3code",
163
- key: url.split("/").at(-1)!,
164
- writable: true,
165
- }),
166
- }),
158
+ issueLayer ??
159
+ Layer.mock(IssueService.IssueService)({
160
+ detail: () => Effect.succeed(detail),
161
+ projectScope: (projectId) =>
162
+ Effect.succeed({
163
+ projectId,
164
+ tracker: GITHUB,
165
+ host: "github.com",
166
+ scope: "t3tools/t3code",
167
+ }),
168
+ resolveUrl: (url) =>
169
+ Effect.succeed({
170
+ projectId: PROJECT_ID,
171
+ tracker: GITHUB,
172
+ host: "github.com",
173
+ scope: "t3tools/t3code",
174
+ key: url.split("/").at(-1)!,
175
+ writable: true,
176
+ }),
177
+ }),
178
Layer.mock(ThreadIssueService.ThreadIssueService)({
179
link: (input) =>
180
Ref.update(links, (recorded) => [...recorded, input]).pipe(
@@ -198,6 +209,75 @@ const makeHarness = Effect.fn("makeIssuesToolkitHarness")(function* (
209
});
210
211
describe("issue toolkit handlers", () => {
212
+ it.effect("returns a Linear issue by URL with one issue read left before the rate limit", () =>
213
+ Effect.gen(function* () {
214
+ const tracker = IssueTrackerKind.make("linear");
215
+ const host = "linear.app";
216
+ const url = "https://linear.app/acme/issue/ENG-7/seven";
217
+ const readsLeft = yield* Ref.make(1);
218
+ const linear: StandaloneIssueTrackerApi = {
219
+ kind: tracker,
220
+ capabilities: detail.capabilities,
221
+ standalone: {
222
+ tracker,
223
+ displayName: "Linear",
224
+ host,
225
+ scopeNoun: "team",
226
+ credential: { label: "Personal API key", helpUrl: null },
227
+ },
228
+ parseIssueUrl: (link) =>
229
+ link.href === url ? { host, workspace: "acme", scope: "ENG", key: "ENG-7" } : null,
230
+ probeCredential: () => Effect.succeed({ account: "user", scopes: [] }),
231
+ getViewer: () => Effect.succeed("user"),
232
+ listIssues: () => Effect.succeed({ items: [], nextCursor: null }),
233
+ getComments: () => Effect.succeed({ comments: [], nextCursor: null }),
234
+ getIssue: ({ key }) =>
235
+ Ref.getAndUpdate(readsLeft, (left) => left - 1).pipe(
236
+ Effect.flatMap((left) =>
237
+ left > 0
238
+ ? Effect.succeed({
239
+ ...detail,
240
+ reactions: [],
241
+ key,
242
+ url,
243
+ displayKey: key,
244
+ body: "Repro steps",
245
+ })
246
+ : Effect.fail(
247
+ new IssueTrackerError({
248
+ tracker,
249
+ operation: "getIssue",
250
+ reason: "rate-limited",
251
+ detail: "Linear's rate limit was reached.",
252
+ }),
253
+ ),
254
+ ),
255
+ ),
256
+ };
257
+ const issueLayer = IssueService.layer.pipe(
258
+ Layer.provide(
259
+ Layer.mergeAll(
260
+ projectLayer,
261
+ Layer.mock(RepositoryIdentityResolver.RepositoryIdentityResolver)({}),
262
+ Layer.mock(IssueTrackerBindings.IssueTrackerBindingsRepository)({
263
+ list: Effect.succeed(new Map([[PROJECT_ID, { tracker, scope: "ENG" }]])),
264
+ }),
265
+ Layer.succeed(
266
+ IssueTrackerRegistry.IssueTrackerRegistry,
267
+ IssueTrackerRegistry.fromTrackers([linear]),
268
+ ),
269
+ ),
270
+ ),
271
+ );
272
+ const harness = yield* makeHarness([], issueLayer);
273
+ const result = yield* harness.call("read_issue", { url }).pipe(Effect.result);
274
+ expect(result).toMatchObject({
275
+ _tag: "Success",
276
+ success: { url, displayKey: "ENG-7", title: "Seven", body: "Repro steps" },
277
+ });
278
+ }),
279
+ );
280
+
281
it.effect("refuses a credential without the issues capability", () =>
282
Effect.gen(function* () {
283
const harness = yield* makeHarness();
apps/server/src/mcp/toolkits/issues/handlers.ts
+8
-2
@@ -1,5 +1,6 @@
1
import {
2
threadIssueKeysEqual,
3
+ type IssueDetail,
4
type IssueRef,
5
type OrchestrationV2ThreadShell,
6
type ProjectId,
@@ -31,6 +32,8 @@ 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. */
@@ -139,6 +142,9 @@ const make = Effect.gen(function* () {
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)
@@ -189,7 +195,7 @@ const make = Effect.gen(function* () {
195
read_issue: McpToolAccess.reads((input) =>
196
Effect.gen(function* () {
197
const target = yield* resolveTarget(input);
192
- const detail = yield* issues.detail(refOf(target));
198
+ const detail = yield* readIssue(target);
199
return {
200
...identityOf(target),
201
url: target.url ?? detail.url,
@@ -265,7 +271,7 @@ const make = Effect.gen(function* () {
271
projectId: input.projectId ?? thread.projectId,
272
});
273
// Reading the issue proves it exists and names it for the thread's row.
268
- const detail = yield* issues.detail(refOf(target));
274
+ const detail = yield* readIssue(target);
275
const url = target.url ?? detail.url;
276
const { alreadyLinked } = yield* threadIssues
277
.link({