Skip to content

Commit 42de9c2

Browse files
Jardo-51claude
andauthored
feat: link issue-tracker tickets to threads (#12)
* feat: link issue-tracker tickets to threads Threads can now carry links to the tickets they work on (Jira, Linear, GitHub/GitLab/Forgejo/Bitbucket issues, Azure DevOps work items, and any tracker whose URLs name a PROJ-123 style ID). A link is the ticket URL plus its displayed ID; no tracker is contacted. - Agents link tickets through new link_ticket / unlink_ticket / list_thread_tickets MCP tools, prompted by the runtime instructions. - Users link and unlink from the command palette's ticket dialog. - Tickets show beside the branch under the composer and on sidebar rows, with Settings toggles for the pull request and ticket sidebar badges. - Sidebar and command palette search match ticket IDs and URLs. Fork-only: events, commands and the capability carry a `j` marker, the projection lives in a `j_` table on the fork migration track, and tickets are attached to snapshot reads by a wrapper around the upstream query. Resolves #11. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(shared): keep an unknown tracker's ticket URL as given The generic KEY-123 fallback rebuilt the stored URL from the path up to the key, uppercased it, and dropped later segments and the query, so links on unknown hosts could open a different or broken page. It now derives only the label and keeps the URL minus the fragment. Addresses review comment from @Jardo-51 on packages/shared/src/threadTickets.ts:102. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(server): reject non-canonical ticket URLs in the decider Only the MCP handler and the web dialog canonicalized ticket URLs, so any other dispatcher could store a duplicate under a raw form or a non-http(s) URL that the badge hands to the OS. The decider now requires the canonical http(s) form on link. Unlink already requires the URL to be linked. Addresses review comment from @Jardo-51 on apps/server/src/orchestration/decider.ts:1165. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(web): ignore a hidden ticket ID when the URL names the ticket A key typed for an unrecognised URL stayed in state after a recognised URL was pasted over it, and relabelled that ticket while the key field was hidden. Addresses review comment from @Jardo-51 on apps/web/src/components/tickets/ThreadTicketsDialog.tsx:74. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(jardo): explain reverting a database that holds fork events Fork-only event types break a plain upstream server's replay, so the claim that reverting stays safe no longer held. The revert guidance now names fork events as the exception and gives the procedure to delete them first, with the reasons it is safe. Addresses review comment from @Jardo-51 on docs/jardo/forking-strategy.md:362. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(server): report a duplicate ticket link under its stored key link_ticket echoed the caller's key for an already-linked ticket, while the UI kept showing the key it was stored under. Addresses review comment from @Jardo-51 on apps/server/src/mcp/toolkits/tickets/handlers.ts:91. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * test(server): fix ticket test typings The decider rejection cases destructured a tuple into a possibly-undefined URL, and the toolkit harness widened its capability set to Set<string>. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(web): manage thread tickets by right-clicking a composer ticket The command palette was the only way to reach the tickets dialog once a ticket was linked. A right-click on a composer ticket badge now opens it, and the badge tooltip says so. Sidebar badges keep the row's own context menu, and the dialog is only mounted in the chat view. Addresses review comment from @Jardo-51 on apps/web/src/components/tickets/ThreadTicketBadge.tsx:77. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(client-runtime): label ticket MCP tools in the work log link_ticket, unlink_ticket and list_thread_tickets showed up as raw MCP tool names, unlike their pull request siblings. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(web): ticket badge sits on the sidebar row's baseline The ticket key was bare text in a display: contents span, so it took its line box from the control, which inherits the row's size. Beside a text-sm title (settled rows) it sat below the other meta text. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(web): pull request badge sits on the sidebar row's baseline Same cause as the ticket badge: the number was bare text in a display: contents span, so beside a text-sm title (settled rows) it took the row's line box and sat below the other meta text. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * Revise changelog for issue tracker link updates Updated the changelog to reflect changes in issue tracking links and added conflict notes. * Update CHANGELOG with new entries and fixes Added a section for fixed issues and updated the changelog with new entries. --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 40fc4b8 commit 42de9c2

45 files changed

Lines changed: 2169 additions & 10 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,7 @@ export const make = Effect.gen(function* () {
240240
threadPullRequests: true,
241241
pullRequestStackActions: true,
242242
threadPullRequestLinking: true,
243+
jThreadTickets: true,
243244
environmentIcon: true,
244245
projectCloneTracking: true,
245246
...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),

‎apps/server/src/mcp/McpHttpServer.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ import {
3232
} from "./toolkits/preview/tools.ts";
3333
import { PullRequestsToolkitHandlersLive } from "./toolkits/pullRequests/handlers.ts";
3434
import { PullRequestsToolkit } from "./toolkits/pullRequests/tools.ts";
35+
import { TicketsToolkitHandlersLive } from "./toolkits/tickets/handlers.ts";
36+
import { TicketsToolkit } from "./toolkits/tickets/tools.ts";
3537
import {
3638
DeviceScreenshotToolkitHandlersLive,
3739
DeviceStandardToolkitHandlersLive,
@@ -647,6 +649,10 @@ export const PullRequestsToolkitRegistrationLive = McpServer.toolkit(PullRequest
647649
Layer.provide(PullRequestsToolkitHandlersLive),
648650
);
649651

652+
export const TicketsToolkitRegistrationLive = McpServer.toolkit(TicketsToolkit).pipe(
653+
Layer.provide(TicketsToolkitHandlersLive),
654+
);
655+
650656
const DeviceStandardToolkitRegistrationLive = McpServer.toolkit(DeviceStandardToolkit).pipe(
651657
Layer.provide(DeviceStandardToolkitHandlersLive),
652658
);
@@ -670,5 +676,6 @@ const McpTransportLive = McpServer.layerHttp({
670676
export const layer = Layer.mergeAll(
671677
PreviewToolkitRegistrationLive,
672678
PullRequestsToolkitRegistrationLive,
679+
TicketsToolkitRegistrationLive,
673680
DeviceToolkitRegistrationLive,
674681
).pipe(Layer.provideMerge(McpTransportLive));
Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
import {
2+
EnvironmentId,
3+
ProjectId,
4+
ProviderInstanceId,
5+
ThreadId,
6+
type OrchestrationCommand,
7+
type OrchestrationThreadShell,
8+
} from "@t3tools/contracts";
9+
import { describe, expect, it } from "@effect/vitest";
10+
import * as Crypto from "effect/Crypto";
11+
import * as Effect from "effect/Effect";
12+
import * as Layer from "effect/Layer";
13+
import * as Option from "effect/Option";
14+
import * as Ref from "effect/Ref";
15+
import * as Stream from "effect/Stream";
16+
import type { Tool } from "effect/unstable/ai";
17+
18+
import { OrchestrationCommandInvariantError } from "../../../orchestration/Errors.ts";
19+
import {
20+
OrchestrationEngineService,
21+
type OrchestrationEngineShape,
22+
} from "../../../orchestration/Services/OrchestrationEngine.ts";
23+
import { ProjectionSnapshotQuery } from "../../../orchestration/Services/ProjectionSnapshotQuery.ts";
24+
import * as McpInvocationContext from "../../McpInvocationContext.ts";
25+
import { TicketsToolkitHandlersLive } from "./handlers.ts";
26+
import { TicketsToolkit } from "./tools.ts";
27+
28+
const THREAD_ID = ThreadId.make("thread-1");
29+
30+
const testCrypto = Crypto.make({
31+
randomBytes: (size) => new Uint8Array(size).fill(7),
32+
digest: (_algorithm, data) => Effect.succeed(data),
33+
});
34+
35+
const thread: OrchestrationThreadShell = {
36+
id: THREAD_ID,
37+
projectId: ProjectId.make("project-1"),
38+
title: "Thread",
39+
modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
40+
runtimeMode: "full-access",
41+
interactionMode: "default",
42+
branch: null,
43+
worktreePath: null,
44+
pullRequests: [],
45+
tickets: [
46+
{
47+
url: "https://linear.app/acme/issue/ENG-2",
48+
key: "ENG-2",
49+
source: "manual",
50+
linkedAt: "2026-08-10T00:00:00.000Z",
51+
},
52+
],
53+
latestTurn: null,
54+
createdAt: "2026-08-01T00:00:00.000Z",
55+
updatedAt: "2026-08-20T00:00:00.000Z",
56+
archivedAt: null,
57+
settledOverride: null,
58+
settledAt: null,
59+
session: null,
60+
latestUserMessageAt: null,
61+
hasPendingApprovals: false,
62+
hasPendingUserInput: false,
63+
hasActionableProposedPlan: false,
64+
};
65+
66+
const makeHarness = Effect.fn("makeTicketsToolkitHarness")(function* (
67+
reject: (command: OrchestrationCommand) => boolean = () => false,
68+
) {
69+
const commands = yield* Ref.make<ReadonlyArray<OrchestrationCommand>>([]);
70+
const dispatch: OrchestrationEngineShape["dispatch"] = (command) =>
71+
Effect.gen(function* () {
72+
if (reject(command)) {
73+
return yield* new OrchestrationCommandInvariantError({
74+
commandType: command.type,
75+
detail: "rejected",
76+
});
77+
}
78+
yield* Ref.update(commands, (recorded) => [...recorded, command]);
79+
return { sequence: 1 };
80+
});
81+
const dependencies = Layer.mergeAll(
82+
Layer.mock(ProjectionSnapshotQuery)({
83+
getThreadShellById: (threadId) =>
84+
Effect.succeed(threadId === THREAD_ID ? Option.some(thread) : Option.none()),
85+
}),
86+
Layer.mock(OrchestrationEngineService)({
87+
readEvents: () => Stream.empty,
88+
dispatch,
89+
streamDomainEvents: Stream.empty,
90+
latestSequence: Effect.succeed(0),
91+
}),
92+
Layer.succeed(Crypto.Crypto, testCrypto),
93+
);
94+
const toolkit = yield* TicketsToolkit.pipe(
95+
Effect.provide(TicketsToolkitHandlersLive.pipe(Layer.provide(dependencies))),
96+
);
97+
const call = <Name extends keyof typeof TicketsToolkit.tools>(
98+
name: Name,
99+
params: Parameters<typeof toolkit.handle<Name>>[1],
100+
) =>
101+
toolkit.handle(name, params).pipe(
102+
Stream.unwrap,
103+
Stream.runCollect,
104+
Effect.map(
105+
(chunk) => chunk.at(-1)!.result as Tool.Success<(typeof TicketsToolkit.tools)[Name]>,
106+
),
107+
Effect.provideService(McpInvocationContext.McpInvocationContext, {
108+
environmentId: EnvironmentId.make("environment-1"),
109+
threadId: THREAD_ID,
110+
providerSessionId: "provider-session-1",
111+
providerInstanceId: ProviderInstanceId.make("codex"),
112+
capabilities: new Set<McpInvocationContext.McpCapability>(["pull-requests"]),
113+
issuedAt: 1,
114+
}),
115+
Effect.provide(dependencies),
116+
);
117+
return { commands, call };
118+
});
119+
120+
describe("ticket toolkit handlers", () => {
121+
it.effect("links a recognised URL under its canonical form with source agent", () =>
122+
Effect.gen(function* () {
123+
const harness = yield* makeHarness();
124+
const result = yield* harness.call("link_ticket", {
125+
url: "https://acme.atlassian.net/browse/proj-7?focusedCommentId=3",
126+
});
127+
expect(result).toEqual({
128+
url: "https://acme.atlassian.net/browse/PROJ-7",
129+
key: "PROJ-7",
130+
alreadyLinked: false,
131+
});
132+
expect(yield* Ref.get(harness.commands)).toMatchObject([
133+
{
134+
type: "thread.j-ticket.link",
135+
threadId: THREAD_ID,
136+
url: "https://acme.atlassian.net/browse/PROJ-7",
137+
key: "PROJ-7",
138+
source: "agent",
139+
},
140+
]);
141+
}),
142+
);
143+
144+
it.effect("needs a key for a tracker it cannot read, and reports duplicates as linked", () =>
145+
Effect.gen(function* () {
146+
const harness = yield* makeHarness(() => true);
147+
const error = yield* harness
148+
.call("link_ticket", { url: "https://tracker.example/t/42" })
149+
.pipe(Effect.flip);
150+
expect(error).toMatchObject({ _tag: "TicketUrlInvalidError" });
151+
const result = yield* harness.call("link_ticket", {
152+
url: "https://tracker.example/t/42",
153+
key: "T-42",
154+
});
155+
expect(result).toEqual({
156+
url: "https://tracker.example/t/42",
157+
key: "T-42",
158+
alreadyLinked: true,
159+
});
160+
}),
161+
);
162+
163+
it.effect("reports an already linked ticket under the key it was stored with", () =>
164+
Effect.gen(function* () {
165+
const harness = yield* makeHarness(() => true);
166+
const result = yield* harness.call("link_ticket", {
167+
url: "https://linear.app/acme/issue/eng-2",
168+
key: "Login bug",
169+
});
170+
expect(result).toEqual({
171+
url: "https://linear.app/acme/issue/ENG-2",
172+
key: "ENG-2",
173+
alreadyLinked: true,
174+
});
175+
}),
176+
);
177+
178+
it.effect("unlinks by canonical URL and lists the thread's tickets", () =>
179+
Effect.gen(function* () {
180+
const harness = yield* makeHarness();
181+
const result = yield* harness.call("unlink_ticket", {
182+
url: "https://linear.app/acme/issue/eng-2/some-slug",
183+
});
184+
expect(result).toEqual({ url: "https://linear.app/acme/issue/ENG-2", wasLinked: true });
185+
expect(yield* harness.call("list_thread_tickets", {})).toEqual({
186+
tickets: [{ url: "https://linear.app/acme/issue/ENG-2", key: "ENG-2", source: "manual" }],
187+
});
188+
}),
189+
);
190+
});
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
import { CommandId, type OrchestrationThreadShell, type ThreadId } from "@t3tools/contracts";
2+
import { canonicalTicketUrl, resolveTicketReference } from "@t3tools/shared/threadTickets";
3+
import * as Cause from "effect/Cause";
4+
import * as Crypto from "effect/Crypto";
5+
import * as Effect from "effect/Effect";
6+
import * as Option from "effect/Option";
7+
8+
import * as OrchestrationEngine from "../../../orchestration/Services/OrchestrationEngine.ts";
9+
import * as ProjectionSnapshotQuery from "../../../orchestration/Services/ProjectionSnapshotQuery.ts";
10+
import * as McpInvocationContext from "../../McpInvocationContext.ts";
11+
import {
12+
type ListThreadTicketsResult,
13+
TicketLinkFailedError,
14+
TicketListFailedError,
15+
TicketsToolkit,
16+
TicketThreadNotFoundError,
17+
TicketUnlinkFailedError,
18+
TicketUrlInvalidError,
19+
} from "./tools.ts";
20+
21+
/** What list_thread_tickets reports from a thread shell. */
22+
export function listThreadTickets(
23+
thread: Pick<OrchestrationThreadShell, "tickets">,
24+
): ListThreadTicketsResult {
25+
return {
26+
tickets: (thread.tickets ?? []).map(({ url, key, source }) => ({ url, key, source })),
27+
};
28+
}
29+
30+
type Failure =
31+
| typeof TicketLinkFailedError
32+
| typeof TicketUnlinkFailedError
33+
| typeof TicketListFailedError;
34+
35+
const make = Effect.gen(function* () {
36+
const engine = yield* OrchestrationEngine.OrchestrationEngineService;
37+
const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
38+
const crypto = yield* Crypto.Crypto;
39+
40+
const commandId = (tag: string, threadId: ThreadId) =>
41+
crypto.randomUUIDv4.pipe(
42+
Effect.orDie,
43+
Effect.map((uuid) => CommandId.make(`server:${tag}:${threadId}:${uuid}`)),
44+
);
45+
46+
const requireThread = Effect.fn("TicketsToolkit.requireThread")(function* (Failure: Failure) {
47+
// Every agent session is granted thread linking under this capability; tickets ride on it.
48+
const scope = yield* McpInvocationContext.requireMcpCapability("pull-requests");
49+
const thread = yield* snapshots
50+
.getThreadShellById(scope.threadId)
51+
.pipe(Effect.mapError((cause) => new Failure({ cause })));
52+
if (Option.isNone(thread)) {
53+
return yield* new TicketThreadNotFoundError({ threadId: scope.threadId });
54+
}
55+
return thread.value;
56+
});
57+
58+
const dispatchFailure =
59+
(Failure: typeof TicketLinkFailedError | typeof TicketUnlinkFailedError) =>
60+
<E>(
61+
cause: Cause.Cause<E>,
62+
): Effect.Effect<never, TicketLinkFailedError | TicketUnlinkFailedError> =>
63+
Cause.hasInterruptsOnly(cause)
64+
? Effect.failCause(cause as Cause.Cause<never>)
65+
: Effect.fail(new Failure({ cause }));
66+
67+
return TicketsToolkit.of({
68+
link_ticket: (input) =>
69+
Effect.gen(function* () {
70+
const thread = yield* requireThread(TicketLinkFailedError);
71+
const ticket = resolveTicketReference(input);
72+
if (ticket === null) {
73+
return yield* new TicketUrlInvalidError({});
74+
}
75+
const alreadyLinked = yield* engine
76+
.dispatch({
77+
type: "thread.j-ticket.link",
78+
commandId: yield* commandId("mcp-ticket-link", thread.id),
79+
threadId: thread.id,
80+
url: ticket.url,
81+
key: ticket.key,
82+
source: "agent",
83+
})
84+
.pipe(
85+
Effect.as(false),
86+
// The decider rejects a second link of the same ticket; for the agent that is the
87+
// outcome it asked for, not an error.
88+
Effect.catchTags({ OrchestrationCommandInvariantError: () => Effect.succeed(true) }),
89+
Effect.catchCause(dispatchFailure(TicketLinkFailedError)),
90+
);
91+
// A duplicate keeps the label it was stored under, so report that one.
92+
const existing = alreadyLinked
93+
? (thread.tickets ?? []).find((entry) => entry.url === ticket.url)
94+
: undefined;
95+
return { url: ticket.url, key: existing?.key ?? ticket.key, alreadyLinked };
96+
}),
97+
unlink_ticket: (input) =>
98+
Effect.gen(function* () {
99+
const thread = yield* requireThread(TicketUnlinkFailedError);
100+
const url = canonicalTicketUrl(input.url);
101+
if (url === null) {
102+
return yield* new TicketUrlInvalidError({});
103+
}
104+
const wasLinked = yield* engine
105+
.dispatch({
106+
type: "thread.j-ticket.unlink",
107+
commandId: yield* commandId("mcp-ticket-unlink", thread.id),
108+
threadId: thread.id,
109+
url,
110+
})
111+
.pipe(
112+
Effect.as(true),
113+
Effect.catchTags({ OrchestrationCommandInvariantError: () => Effect.succeed(false) }),
114+
Effect.catchCause(dispatchFailure(TicketUnlinkFailedError)),
115+
);
116+
return { url, wasLinked };
117+
}),
118+
list_thread_tickets: () =>
119+
requireThread(TicketListFailedError).pipe(Effect.map(listThreadTickets)),
120+
});
121+
});
122+
123+
export const TicketsToolkitHandlersLive = TicketsToolkit.toLayer(make);

0 commit comments

Comments
 (0)