Skip to content

Commit b07bd70

Browse files
refactor(mcp): the guide service says whether it started a run
The write tool inferred "joined" from a read before generate; the service now reports it directly, so the handler only maps the result. A guide read failure keeps its cause. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 03e33a8 commit b07bd70

5 files changed

Lines changed: 37 additions & 44 deletions

File tree

‎apps/server/src/mcp/toolkits/pullRequests/handlers.test.ts‎

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -144,9 +144,10 @@ interface HarnessOptions {
144144
/** What the guide service answers for a pull request it is asked to write. */
145145
readonly generate?: (
146146
input: PullRequestRef,
147-
) => Effect.Effect<PullRequestReviewGuideResult, PullRequestOperationError>;
148-
/** A run already going when the tool asks, which a write joins. */
149-
readonly running?: PullRequestReviewGuideResult["run"];
147+
) => Effect.Effect<
148+
PullRequestReviewGuideResult & { started: boolean },
149+
PullRequestOperationError
150+
>;
150151
}
151152

152153
const NO_GUIDE: PullRequestReviewGuideResult = { guide: null, run: null, currentHeadSha: "head-1" };
@@ -176,7 +177,7 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
176177
listShells: () => Effect.succeed(options.projects ?? (project ? [project] : [])),
177178
}),
178179
Layer.mock(PullRequestReviewGuideService.PullRequestReviewGuideService)({
179-
get: () => Effect.succeed({ ...NO_GUIDE, run: options.running ?? null }),
180+
get: () => Effect.succeed(NO_GUIDE),
180181
generate: (input) =>
181182
Ref.update(guideRequests, (recorded) => [...recorded, input]).pipe(
182183
Effect.andThen(
@@ -188,6 +189,7 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
188189
headSha: "head-1",
189190
startedAt: "2026-10-11T00:00:00.000Z",
190191
},
192+
started: true,
191193
}),
192194
),
193195
),
@@ -642,6 +644,7 @@ describe("pull request guide tools", () => {
642644
headSha: "head-1",
643645
startedAt: "2026-10-11T00:00:00.000Z",
644646
},
647+
started: true,
645648
}),
646649
});
647650
const result = yield* harness.call("write_pull_request_guides", {
@@ -674,10 +677,15 @@ describe("pull request guide tools", () => {
674677
}),
675678
);
676679

677-
it.effect("joins a run already going rather than reporting a new one", () =>
680+
it.effect("reports a run the service joined as running, not as a new one", () =>
678681
Effect.gen(function* () {
679682
const harness = yield* makeHarness({
680-
running: { _tag: "Running", headSha: "head-1", startedAt: "2026-10-11T00:00:00.000Z" },
683+
generate: () =>
684+
Effect.succeed({
685+
...NO_GUIDE,
686+
run: { _tag: "Running", headSha: "head-1", startedAt: "2026-10-11T00:00:00.000Z" },
687+
started: false,
688+
}),
681689
});
682690
const result = yield* harness.call("write_pull_request_guides", {
683691
pullRequests: [{ repository: "t3tools/t3code", number: 4 }],
@@ -686,18 +694,6 @@ describe("pull request guide tools", () => {
686694
}),
687695
);
688696

689-
it.effect("reports a run for a new head as started, not as the older run it replaced", () =>
690-
Effect.gen(function* () {
691-
const harness = yield* makeHarness({
692-
running: { _tag: "Running", headSha: "head-old", startedAt: "2026-10-11T00:00:00.000Z" },
693-
});
694-
const result = yield* harness.call("write_pull_request_guides", {
695-
pullRequests: [{ repository: "t3tools/t3code", number: 6 }],
696-
});
697-
expect(result.guides.map((guide) => guide.outcome)).toEqual(["started"]);
698-
}),
699-
);
700-
701697
it.effect("finds an Azure DevOps checkout for a pull request named by its full path", () =>
702698
Effect.gen(function* () {
703699
const azure = {

‎apps/server/src/mcp/toolkits/pullRequests/handlers.ts‎

Lines changed: 11 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -470,21 +470,10 @@ const make = Effect.gen(function* () {
470470
}).message,
471471
};
472472
}
473-
const reference = guideReference(entry.project, entry.target);
474-
// Generate returns the run it started, or the one for this head it joined. The same
475-
// run before and after means it joined; a run for a new head is a new start.
476-
const before = yield* reviewGuides.get(reference).pipe(Effect.option);
477-
const previous = Option.isSome(before) ? before.value.run : null;
478-
return yield* reviewGuides.generate(reference).pipe(
473+
return yield* reviewGuides.generate(guideReference(entry.project, entry.target)).pipe(
479474
Effect.map((result) => ({
480475
...identity,
481-
outcome:
482-
previous?._tag === "Running" &&
483-
result.run?._tag === "Running" &&
484-
previous.headSha === result.run.headSha &&
485-
previous.startedAt === result.run.startedAt
486-
? ("running" as const)
487-
: ("started" as const),
476+
outcome: result.started ? ("started" as const) : ("running" as const),
488477
detail: null,
489478
})),
490479
Effect.catch((error) =>
@@ -512,13 +501,15 @@ const make = Effect.gen(function* () {
512501
repository: entry?.target.repository ?? input.repository ?? "",
513502
});
514503
}
515-
const result = yield* reviewGuides
516-
.get(guideReference(entry.project, entry.target))
517-
.pipe(
518-
Effect.mapError(
519-
(error) => new PullRequestGuideFailedError({ detail: guideFailureDetail(error) }),
520-
),
521-
);
504+
const result = yield* reviewGuides.get(guideReference(entry.project, entry.target)).pipe(
505+
Effect.mapError(
506+
(error) =>
507+
new PullRequestGuideFailedError({
508+
detail: guideFailureDetail(error),
509+
cause: error,
510+
}),
511+
),
512+
);
522513
return {
523514
host: entry.target.host,
524515
repository: entry.target.repository,

‎apps/server/src/mcp/toolkits/pullRequests/tools.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ export class PullRequestProjectNotFoundError extends Schema.TaggedError<PullRequ
181181

182182
export class PullRequestGuideFailedError extends Schema.TaggedError<PullRequestGuideFailedError>()(
183183
"PullRequestGuideFailedError",
184-
{ detail: Schema.String },
184+
{ detail: Schema.String, cause: Schema.optional(Schema.Defect()) },
185185
) {
186186
override get message(): string {
187187
return this.detail;

‎apps/server/src/pullRequest/PullRequestReviewGuideService.test.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,7 @@ it.layer(layerBase, { excludeTestServices: true })("PullRequestReviewGuideServic
303303
const started = yield* service.generate(reference);
304304
assert.strictEqual(started.run?._tag, "Running");
305305
assert.strictEqual(started.guide, null);
306+
assert.isTrue(started.started);
306307

307308
// A run that fails before reaching the model reports why rather than leaving this waiting.
308309
const failedRun = service.get(reference).pipe(
@@ -329,7 +330,8 @@ it.layer(layerBase, { excludeTestServices: true })("PullRequestReviewGuideServic
329330

330331
// A second press while running joins the run instead of starting another.
331332
const joined = yield* service.generate(reference);
332-
assert.strictEqual(joined.run?._tag, "Running");
333+
assert.strictEqual(joined.run, started.run);
334+
assert.isFalse(joined.started);
333335

334336
yield* Deferred.succeed(finish, undefined);
335337
yield* Deferred.await(stored);

‎apps/server/src/pullRequest/PullRequestReviewGuideService.ts‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,11 +62,15 @@ export class PullRequestReviewGuideService extends Context.Service<
6262
/**
6363
* Start writing a guide for the current head and return once it is under way. Joins a run
6464
* already going for that head. A stored guide stays readable until the new one replaces it,
65-
* so a reader can rewrite one after changing the guide model or instructions.
65+
* so a reader can rewrite one after changing the guide model or instructions. `started` says
66+
* whether this call began the run or joined one already going.
6667
*/
6768
readonly generate: (
6869
input: PullRequestRef,
69-
) => Effect.Effect<PullRequestReviewGuideResult, PullRequestService.PullRequestError>;
70+
) => Effect.Effect<
71+
PullRequestReviewGuideResult & { readonly started: boolean },
72+
PullRequestService.PullRequestError
73+
>;
7074
}
7175
>()("t3/pullRequest/PullRequestReviewGuideService") {}
7276

@@ -439,7 +443,7 @@ const make = Effect.gen(function* () {
439443
),
440444
),
441445
);
442-
if (claimed !== running) return { guide: stored, run: claimed, currentHeadSha };
446+
if (claimed !== running) return { guide: stored, run: claimed, currentHeadSha, started: false };
443447

444448
// The run is identified by its own Running value: a later claim replaces it, and from then
445449
// on this run's completion leaves the newer run's state and guide alone.
@@ -475,7 +479,7 @@ const make = Effect.gen(function* () {
475479
),
476480
Effect.forkIn(serviceScope),
477481
);
478-
return { guide: stored, run: running, currentHeadSha };
482+
return { guide: stored, run: running, currentHeadSha, started: true };
479483
});
480484

481485
return PullRequestReviewGuideService.of({ get, generate });

0 commit comments

Comments
 (0)