The best way to control Claude Code, Codex and more from any computer or phone
fix(server): agents can open Linear issues by URL (#37968)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Wout Stiens committed
Nov 17, 2026 at 10:43 UTC
d35ec21cdd029ce6f97fa963e9a3263662fb1320
5 files changed
+147
-12
apps/server/src/issue/IssueService.test.ts
+58
-1
@@ -37,7 +37,12 @@ function fakeStandaloneTracker(
37
...fakeTracker({
38
getViewer: () => Effect.succeed("usr_julius"),
39
getIssue: (input) =>
40
- Effect.succeed({ ...issue(input.key), displayKey: input.key, viewer: "usr_julius" }),
40
+ Effect.succeed({
41
+ ...issue(input.key),
42
+ url: `https://linear.app/acme/issue/${input.key}/canonical-title`,
43
+ displayKey: input.key,
44
+ viewer: "usr_julius",
45
+ }),
46
...overrides,
47
}),
48
kind: LINEAR,
@@ -48,6 +53,18 @@ function fakeStandaloneTracker(
53
scopeNoun: "team",
54
credential: { label: "Personal API key", helpUrl: null },
55
},
56
+ parseIssueUrl: (url) => {
57
+ const links = new Map([
58
+ ["https://linear.app/acme/issue/ENG-1/old-title", "acme"],
59
+ ["https://linear.app/acme/issue/ENG-1/issue-title", "acme"],
60
+ ["https://linear.app/acme/issue/ENG-1/canonical-title", "acme"],
61
+ ["https://linear.app/other-workspace/issue/ENG-1/old-title", "other-workspace"],
62
+ ]);
63
+ const workspace = links.get(url.href);
64
+ return workspace === undefined
65
+ ? null
66
+ : { host: "linear.app", workspace, scope: "ENG", key: "ENG-1" };
67
+ },
68
probeCredential: () => Effect.succeed({ account: "julius", scopes: [] }),
69
};
70
}
@@ -437,6 +454,31 @@ describe("IssueService", () => {
454
});
455
456
describe("IssueService with a standalone tracker", () => {
457
+ it.effect("rejects a URL from another workspace with the same team and issue key", () =>
458
+ Effect.gen(function* () {
459
+ const service = yield* makeService({
460
+ projects: [project({ id: "web" })],
461
+ trackers: [fakeStandaloneTracker()],
462
+ bindings: { web: { tracker: LINEAR, scope: "ENG" } },
463
+ });
464
+ expect(
465
+ yield* service.resolveUrl("https://linear.app/acme/issue/ENG-1/old-title"),
466
+ ).toMatchObject({ key: "ENG-1", writable: true });
467
+ const refused = yield* service
468
+ .resolveUrl("https://linear.app/other-workspace/issue/ENG-1/old-title")
469
+ .pipe(Effect.result);
470
+ expect(refused).toMatchObject({
471
+ _tag: "Failure",
472
+ failure: {
473
+ _tag: "IssueOperationError",
474
+ operation: "resolveUrl",
475
+ reason: "not-found",
476
+ detail: "This issue URL does not belong to the connected workspace.",
477
+ },
478
+ });
479
+ }),
480
+ );
481
+
482
it.effect("lists a bound project's standalone scope beside its git host and serves both", () =>
483
Effect.gen(function* () {
484
const listed: string[] = [];
@@ -490,6 +532,21 @@ describe("IssueService with a standalone tracker", () => {
532
}),
533
).toMatchObject({ host: "github.com", writable: true });
534
535
+ const resolved = yield* bound
536
+ .resolveUrl("https://linear.app/acme/issue/ENG-1/issue-title", "web" as ProjectId)
537
+ .pipe(Effect.result);
538
+ expect(resolved).toMatchObject({
539
+ _tag: "Success",
540
+ success: {
541
+ projectId: "web",
542
+ tracker: LINEAR,
543
+ host: "linear.app",
544
+ scope: "ENG",
545
+ key: "ENG-1",
546
+ writable: true,
547
+ },
548
+ });
549
+
550
// Unbound, the standalone scope is gone and its references are unsupported.
551
listed.length = 0;
552
const unbound = yield* makeService({ projects, trackers });
apps/server/src/issue/IssueService.ts
+45
-11
@@ -36,7 +36,9 @@ import {
36
IssueTrackerError,
37
isStandaloneIssueTracker,
38
type IssueTrackerApi,
39
+ type StandaloneIssueTrackerApi,
40
} from "@t3tools/source-control-core/server/IssueTracker";
41
+import { parseUrl } from "@t3tools/shared/url";
42
43
import * as IssueTrackerBindings from "../persistence/IssueTrackerBindings.ts";
44
import * as ProjectService from "../project/ProjectService.ts";
@@ -91,6 +93,16 @@ function resolveGitHostBinding(project: OrchestrationProjectShell): ProjectTrack
93
};
94
}
95
96
+function findStandaloneIssueUrl(trackers: ReadonlyArray<StandaloneIssueTrackerApi>, value: string) {
97
+ const url = parseUrl(value);
98
+ if (url === null) return null;
99
+ for (const api of trackers) {
100
+ const link = api.parseIssueUrl(url);
101
+ if (link !== null) return { api, tracker: api.kind, link };
102
+ }
103
+ return null;
104
+}
105
+
106
/** Lower case, so a scope keeps its cursor whichever project's spelling of it is read. */
107
function listCursorKey(host: string, scope: string): string {
108
return `${host} ${scope.toLowerCase()}`;
@@ -145,15 +157,14 @@ export class IssueService extends Context.Service<
157
readonly update: (input: IssueUpdateInput) => Effect.Effect<void, IssueError>;
158
readonly setState: (input: IssueSetStateInput) => Effect.Effect<void, IssueError>;
159
readonly react: (input: IssueReactionInput) => Effect.Effect<void, IssueError>;
148
- /**
149
- * The reference behind an issue URL: served by the project whose binding is that host and
150
- * scope, else read-only through any project on the same tracker and host. `preferredProjectId`
151
- * wins among equals, so a thread's own project serves its own issues.
152
- */
160
/** The tracker and container a project's own issues live in. */
161
readonly projectScope: (
162
projectId: ProjectId,
163
) => Effect.Effect<IssueScopeRef & { readonly host: string }, IssueError>;
164
+ /**
165
+ * Resolve through a matching project, preferring `preferredProjectId`; other scopes are read-only.
166
+ * Standalone links must match the workspace in the issue's canonical URL from the connected tracker.
167
+ */
168
readonly resolveUrl: (
169
url: string,
170
preferredProjectId?: ProjectId,
@@ -627,7 +638,12 @@ const make = Effect.gen(function* () {
638
639
const resolveUrl: IssueService["Service"]["resolveUrl"] = Effect.fn("IssueService.resolveUrl")(
640
function* (url, preferredProjectId) {
630
- const parsed = sourceControlDefinitions.parseIssueUrl(url);
641
+ const gitHost = sourceControlDefinitions.parseIssueUrl(url);
642
+ const standalone = gitHost === null ? findStandaloneIssueUrl(registry.standalone, url) : null;
643
+ const parsed =
644
+ gitHost === null
645
+ ? standalone
646
+ : { tracker: IssueTrackerKind.make(gitHost.definition.kind), link: gitHost.link };
647
if (parsed === null) {
648
return yield* new IssueOperationError({
649
operation: "resolveUrl",
@@ -635,24 +651,42 @@ const make = Effect.gen(function* () {
651
detail: "This is not a recognised issue URL.",
652
});
653
}
638
- const { definition, link } = parsed;
654
+ const { tracker, link } = parsed;
655
// A link names its server's port; a binding does only when its remote or web URL did.
656
const authority = new URL(url).host.toLowerCase();
657
const { supported } = yield* listProjects({ host: link.host, authority });
642
- const onHost = supported.filter(
643
- (project) => project.tracker === IssueTrackerKind.make(definition.kind),
644
- );
658
+ const onHost = supported.filter((project) => project.tracker === tracker);
659
const onAuthority = onHost.filter((project) => project.host === authority);
660
const onTracker = onAuthority.length > 0 ? onAuthority : onHost;
661
const preferFirst = (projects: ReadonlyArray<SupportedProject>) =>
662
projects.find((project) => project.project.id === preferredProjectId) ?? projects[0];
663
const own = preferFirst(
650
- onTracker.filter((project) => project.scope.toLowerCase() === link.scope),
664
+ onTracker.filter((project) => project.scope.toLowerCase() === link.scope.toLowerCase()),
665
);
666
const lender = own ?? preferFirst(onTracker);
667
if (lender === undefined) {
668
return yield* new IssueUnavailableError({ reason: "tracker-unsupported" });
669
}
670
+ if (standalone !== null) {
671
+ // Team keys repeat across workspaces; only the credential's canonical issue URL identifies one.
672
+ const issue = yield* lender.api
673
+ .getIssue({
674
+ cwd: lender.project.workspaceRoot,
675
+ host: lender.host,
676
+ scope: link.scope,
677
+ key: link.key,
678
+ })
679
+ .pipe(Effect.mapError(toIssueError("resolveUrl")));
680
+ const canonicalUrl = parseUrl(issue.url);
681
+ const canonical = canonicalUrl === null ? null : standalone.api.parseIssueUrl(canonicalUrl);
682
+ if (canonical === null || canonical.workspace !== standalone.link.workspace) {
683
+ return yield* new IssueOperationError({
684
+ operation: "resolveUrl",
685
+ reason: "not-found",
686
+ detail: "This issue URL does not belong to the connected workspace.",
687
+ });
688
+ }
689
+ }
690
return {
691
projectId: lender.project.id,
692
tracker: lender.tracker,
packages/issue-tracker-linear/src/server/LinearIssueTracker.test.ts
+34
@@ -127,6 +127,40 @@ function fakeLinear(
127
const target = { cwd: "/w/web", host: "linear.app", scope: "ENG" };
128
129
describe("LinearIssueTracker", () => {
130
+ it.effect("parses Linear issue links with their workspace and team", () =>
131
+ Effect.gen(function* () {
132
+ const api = yield* fakeLinear({}).tracker;
133
+ for (const suffix of ["", "/issue-title", "/old-title?view=all#comment"]) {
134
+ expect(api.parseIssueUrl(new URL(`https://linear.app/acme/issue/ENG-1${suffix}`))).toEqual({
135
+ host: "linear.app",
136
+ workspace: "acme",
137
+ scope: "ENG",
138
+ key: "ENG-1",
139
+ });
140
+ }
141
+ expect(
142
+ api.parseIssueUrl(new URL("https://linear.app/other-workspace/issue/ENG-1")),
143
+ ).toMatchObject({
144
+ workspace: "other-workspace",
145
+ key: "ENG-1",
146
+ });
147
+ for (const url of [
148
+ "http://linear.app/acme/issue/ENG-1",
149
+ "https://example.com/acme/issue/ENG-1",
150
+ "https://linear.app.example.com/acme/issue/ENG-1",
151
+ "https://linear.app:444/acme/issue/ENG-1",
152
+ "https://linear.app/acme/team/ENG-1",
153
+ "https://linear.app//issue/ENG-1",
154
+ "https://linear.app/acme/issue/",
155
+ "https://linear.app/acme/issue/ENG-0",
156
+ "https://linear.app/acme/issue/eng-1",
157
+ "https://linear.app/acme/issue/ENG-1extra",
158
+ ]) {
159
+ expect(api.parseIssueUrl(new URL(url)), url).toBeNull();
160
+ }
161
+ }),
162
+ );
163
+
164
it.effect("lists a team's issues as summaries keyed by identifier", () =>
165
Effect.gen(function* () {
166
const { tracker, requests } = fakeLinear({
packages/issue-tracker-linear/src/server/LinearIssueTracker.ts
+7
@@ -418,6 +418,13 @@ export const make: Effect.Effect<StandaloneIssueTrackerApi, never, LinearApi.Lin
418
kind: LinearApi.KIND,
419
capabilities: CAPABILITIES,
420
standalone: DESCRIPTOR,
421
+ parseIssueUrl: (url) => {
422
+ if (url.protocol !== "https:" || url.host.toLowerCase() !== DESCRIPTOR.host) return null;
423
+ const [, workspace, resource, key] = url.pathname.split("/");
424
+ if (!workspace || resource !== "issue" || key === undefined) return null;
425
+ const scope = /^([A-Z][A-Z0-9_]*)-[1-9][0-9]*$/.exec(key)?.[1];
426
+ return scope === undefined ? null : { host: DESCRIPTOR.host, workspace, scope, key };
427
+ },
428
429
probeCredential: (token) =>
430
linear.viewer(token).pipe(
packages/source-control-core/src/server/IssueTracker.ts
+3
@@ -26,6 +26,7 @@ import type {
26
StandaloneIssueTrackerDescriptor,
27
} from "@t3tools/contracts";
28
import { IssueTrackerKind as IssueTrackerKindSchema } from "@t3tools/contracts";
29
+import type { IssueLink } from "../shared/definition.ts";
30
31
/**
32
* The one failure shape every tracker reports, so the service can decide what a failure means
@@ -196,6 +197,8 @@ export interface IssueTrackerApi {
197
*/
198
export interface StandaloneIssueTrackerApi extends IssueTrackerApi {
199
readonly standalone: StandaloneIssueTrackerDescriptor;
200
+ /** Retains the workspace identity so canonical URLs can disambiguate repeated scope keys. */
201
+ readonly parseIssueUrl: (url: URL) => (IssueLink & { readonly workspace: string }) | null;
202
/**
203
* Who a credential signs in as and which scopes it reaches, asked of the tracker itself. Run on
204
* a credential before it is stored, and on the stored one to report connection status.