Skip to content

Commit 25ff158

Browse files
committed
feat(orchestration): add durable GitHub waitpoints
1 parent 5887de1 commit 25ff158

21 files changed

Lines changed: 2173 additions & 4 deletions
Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
import { assert, it } from "@effect/vitest";
2+
import * as Effect from "effect/Effect";
3+
import * as Layer from "effect/Layer";
4+
import * as Ref from "effect/Ref";
5+
6+
import * as GitHubCli from "../sourceControl/GitHubCli.ts";
7+
import * as GitHubPullRequestProbe from "./GitHubPullRequestProbe.ts";
8+
9+
const rawSnapshot = JSON.stringify({
10+
comments: [{ id: "comment-1", createdAt: "2026-07-30T11:08:34Z" }],
11+
headRefOid: "abc123",
12+
mergedAt: null,
13+
reviews: [{ id: "review-1", submittedAt: "2026-07-30T11:10:03Z", state: "COMMENTED" }],
14+
state: "OPEN",
15+
statusCheckRollup: [
16+
{ __typename: "CheckRun", name: "test", status: "COMPLETED", conclusion: "SUCCESS" },
17+
{ __typename: "StatusContext", context: "preview", state: "PENDING" },
18+
],
19+
updatedAt: "2026-07-30T11:16:04Z",
20+
url: "https://github.com/pingdotgg/t3code/pull/2829",
21+
});
22+
23+
it.effect("reads and normalizes the narrow GitHub pull-request watch snapshot", () =>
24+
Effect.gen(function* () {
25+
const calls = yield* Ref.make<ReadonlyArray<string>>([]);
26+
const gitHubCli = GitHubCli.GitHubCli.of({
27+
execute: (input: Parameters<GitHubCli.GitHubCli["Service"]["execute"]>[0]) =>
28+
Ref.update(calls, (current) => [...current, ...input.args]).pipe(
29+
Effect.as({ stdout: rawSnapshot, stderr: "", exitCode: 0 }),
30+
),
31+
} as unknown as GitHubCli.GitHubCli["Service"]);
32+
33+
const snapshot = yield* Effect.gen(function* () {
34+
const probe = yield* GitHubPullRequestProbe.GitHubPullRequestProbe;
35+
return yield* probe.get({
36+
cwd: "/tmp/project",
37+
repository: "pingdotgg/t3code",
38+
pullRequestNumber: 2829,
39+
});
40+
}).pipe(
41+
Effect.provide(
42+
GitHubPullRequestProbe.layer.pipe(
43+
Layer.provide(Layer.succeed(GitHubCli.GitHubCli, gitHubCli)),
44+
),
45+
),
46+
);
47+
48+
assert.deepStrictEqual(snapshot, {
49+
url: "https://github.com/pingdotgg/t3code/pull/2829",
50+
state: "open",
51+
headSha: "abc123",
52+
mergedAt: null,
53+
updatedAt: "2026-07-30T11:16:04.000Z",
54+
checks: [
55+
{ name: "test", status: "completed", conclusion: "success" },
56+
{ name: "preview", status: "pending", conclusion: null },
57+
],
58+
reviewActivity: [
59+
{ id: "comment-1", occurredAt: "2026-07-30T11:08:34.000Z" },
60+
{ id: "review-1", occurredAt: "2026-07-30T11:10:03.000Z" },
61+
],
62+
});
63+
assert.deepStrictEqual(yield* Ref.get(calls), [
64+
"pr",
65+
"view",
66+
"2829",
67+
"--repo",
68+
"pingdotgg/t3code",
69+
"--json",
70+
"headRefOid,state,mergedAt,updatedAt,statusCheckRollup,comments,reviews,url",
71+
]);
72+
}),
73+
);
74+
75+
it("wakes only when the selected GitHub condition changes", () => {
76+
const baseline: GitHubPullRequestProbe.GitHubPullRequestSnapshot = {
77+
url: "https://github.com/pingdotgg/t3code/pull/2829",
78+
state: "open",
79+
headSha: "abc123",
80+
mergedAt: null,
81+
updatedAt: "2026-07-30T11:16:04.000Z",
82+
checks: [{ name: "test", status: "pending", conclusion: null }],
83+
reviewActivity: [{ id: "review-1", occurredAt: "2026-07-30T11:10:03.000Z" }],
84+
};
85+
86+
assert.isFalse(
87+
GitHubPullRequestProbe.evaluateGitHubWaitpoint("checks_settled", baseline, baseline).satisfied,
88+
);
89+
assert.isTrue(
90+
GitHubPullRequestProbe.evaluateGitHubWaitpoint("checks_settled", baseline, {
91+
...baseline,
92+
checks: [{ name: "test", status: "completed", conclusion: "failure" }],
93+
}).satisfied,
94+
);
95+
assert.isTrue(
96+
GitHubPullRequestProbe.evaluateGitHubWaitpoint("new_review_activity", baseline, {
97+
...baseline,
98+
reviewActivity: [
99+
...baseline.reviewActivity,
100+
{ id: "comment-2", occurredAt: "2026-07-30T12:00:00.000Z" },
101+
],
102+
}).satisfied,
103+
);
104+
assert.isTrue(
105+
GitHubPullRequestProbe.evaluateGitHubWaitpoint("pull_request_closed", baseline, {
106+
...baseline,
107+
state: "merged",
108+
mergedAt: "2026-07-30T12:00:00.000Z",
109+
}).satisfied,
110+
);
111+
});
Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
import type { OrchestratorMcpGitHubWaitCondition } from "@t3tools/contracts";
2+
import * as Context from "effect/Context";
3+
import * as DateTime from "effect/DateTime";
4+
import * as Effect from "effect/Effect";
5+
import * as Layer from "effect/Layer";
6+
import * as Schema from "effect/Schema";
7+
8+
import * as GitHubCli from "../sourceControl/GitHubCli.ts";
9+
10+
const WATCH_FIELDS = "headRefOid,state,mergedAt,updatedAt,statusCheckRollup,comments,reviews,url";
11+
12+
const RawCheck = Schema.Struct({
13+
__typename: Schema.optional(Schema.String),
14+
name: Schema.optional(Schema.String),
15+
context: Schema.optional(Schema.String),
16+
status: Schema.optional(Schema.String),
17+
state: Schema.optional(Schema.String),
18+
conclusion: Schema.optional(Schema.NullOr(Schema.String)),
19+
});
20+
const RawReviewActivity = Schema.Struct({
21+
id: Schema.String,
22+
createdAt: Schema.optional(Schema.String),
23+
submittedAt: Schema.optional(Schema.String),
24+
});
25+
const RawSnapshot = Schema.Struct({
26+
comments: Schema.Array(RawReviewActivity),
27+
headRefOid: Schema.String,
28+
mergedAt: Schema.NullOr(Schema.String),
29+
reviews: Schema.Array(RawReviewActivity),
30+
state: Schema.String,
31+
statusCheckRollup: Schema.Array(RawCheck),
32+
updatedAt: Schema.String,
33+
url: Schema.String,
34+
});
35+
const decodeRawSnapshot = Schema.decodeUnknownEffect(Schema.fromJsonString(RawSnapshot));
36+
37+
export const GitHubPullRequestSnapshot = Schema.Struct({
38+
url: Schema.String,
39+
state: Schema.Literals(["open", "closed", "merged"]),
40+
headSha: Schema.String,
41+
mergedAt: Schema.NullOr(Schema.String),
42+
updatedAt: Schema.String,
43+
checks: Schema.Array(
44+
Schema.Struct({
45+
name: Schema.String,
46+
status: Schema.Literals(["pending", "completed"]),
47+
conclusion: Schema.NullOr(Schema.String),
48+
}),
49+
),
50+
reviewActivity: Schema.Array(
51+
Schema.Struct({
52+
id: Schema.String,
53+
occurredAt: Schema.String,
54+
}),
55+
),
56+
});
57+
export type GitHubPullRequestSnapshot = typeof GitHubPullRequestSnapshot.Type;
58+
59+
export class GitHubPullRequestProbeDecodeError extends Schema.TaggedErrorClass<GitHubPullRequestProbeDecodeError>()(
60+
"GitHubPullRequestProbeDecodeError",
61+
{
62+
repository: Schema.String,
63+
pullRequestNumber: Schema.Int,
64+
cause: Schema.Defect(),
65+
},
66+
) {
67+
override get message(): string {
68+
return `GitHub returned an invalid watch snapshot for ${this.repository}#${this.pullRequestNumber}.`;
69+
}
70+
}
71+
72+
export type GitHubPullRequestProbeError =
73+
| GitHubCli.GitHubCliError
74+
| GitHubPullRequestProbeDecodeError;
75+
76+
export interface GitHubPullRequestProbeInput {
77+
readonly cwd: string;
78+
readonly repository: string;
79+
readonly pullRequestNumber: number;
80+
}
81+
82+
export class GitHubPullRequestProbe extends Context.Service<
83+
GitHubPullRequestProbe,
84+
{
85+
readonly get: (
86+
input: GitHubPullRequestProbeInput,
87+
) => Effect.Effect<GitHubPullRequestSnapshot, GitHubPullRequestProbeError>;
88+
}
89+
>()("t3/github/GitHubPullRequestProbe") {}
90+
91+
function iso(value: string): string {
92+
return DateTime.formatIso(DateTime.makeUnsafe(value));
93+
}
94+
95+
function normalizeState(
96+
state: string,
97+
mergedAt: string | null,
98+
): GitHubPullRequestSnapshot["state"] {
99+
if (mergedAt !== null || state.toUpperCase() === "MERGED") return "merged";
100+
return state.toUpperCase() === "OPEN" ? "open" : "closed";
101+
}
102+
103+
function normalizeCheck(check: typeof RawCheck.Type): GitHubPullRequestSnapshot["checks"][number] {
104+
const rawStatus = (check.status ?? check.state ?? "PENDING").toUpperCase();
105+
const completed =
106+
rawStatus === "COMPLETED" ||
107+
rawStatus === "SUCCESS" ||
108+
rawStatus === "FAILURE" ||
109+
rawStatus === "ERROR";
110+
const conclusion =
111+
check.conclusion ?? (completed && rawStatus !== "COMPLETED" ? rawStatus : null);
112+
return {
113+
name: check.name ?? check.context ?? "GitHub check",
114+
status: completed ? "completed" : "pending",
115+
conclusion: conclusion?.toLowerCase() ?? null,
116+
};
117+
}
118+
119+
function normalizeActivity(
120+
activity: typeof RawReviewActivity.Type,
121+
): GitHubPullRequestSnapshot["reviewActivity"][number] | undefined {
122+
const occurredAt = activity.createdAt ?? activity.submittedAt;
123+
return occurredAt === undefined ? undefined : { id: activity.id, occurredAt: iso(occurredAt) };
124+
}
125+
126+
function normalizeSnapshot(raw: typeof RawSnapshot.Type): GitHubPullRequestSnapshot {
127+
const mergedAt = raw.mergedAt === null ? null : iso(raw.mergedAt);
128+
const reviewActivity = [...raw.comments, ...raw.reviews]
129+
.map(normalizeActivity)
130+
.filter((activity) => activity !== undefined)
131+
.sort(
132+
(left, right) =>
133+
left.occurredAt.localeCompare(right.occurredAt) || left.id.localeCompare(right.id),
134+
);
135+
return {
136+
url: raw.url,
137+
state: normalizeState(raw.state, mergedAt),
138+
headSha: raw.headRefOid,
139+
mergedAt,
140+
updatedAt: iso(raw.updatedAt),
141+
checks: raw.statusCheckRollup.map(normalizeCheck),
142+
reviewActivity,
143+
};
144+
}
145+
146+
export interface GitHubWaitpointEvaluation {
147+
readonly satisfied: boolean;
148+
readonly summary: string;
149+
}
150+
151+
export function evaluateGitHubWaitpoint(
152+
condition: OrchestratorMcpGitHubWaitCondition,
153+
baseline: GitHubPullRequestSnapshot,
154+
current: GitHubPullRequestSnapshot,
155+
): GitHubWaitpointEvaluation {
156+
switch (condition) {
157+
case "checks_settled": {
158+
const settled =
159+
current.checks.length > 0 && current.checks.every((check) => check.status === "completed");
160+
const failed = current.checks.filter(
161+
(check) =>
162+
check.conclusion !== null &&
163+
!["success", "skipped", "neutral"].includes(check.conclusion),
164+
).length;
165+
return {
166+
satisfied: settled,
167+
summary: settled
168+
? `${current.checks.length} checks settled (${failed} unsuccessful).`
169+
: `${current.checks.filter((check) => check.status === "pending").length} checks remain pending.`,
170+
};
171+
}
172+
case "new_review_activity": {
173+
const baselineIds = new Set(baseline.reviewActivity.map((activity) => activity.id));
174+
const added = current.reviewActivity.filter((activity) => !baselineIds.has(activity.id));
175+
return {
176+
satisfied: added.length > 0,
177+
summary:
178+
added.length > 0
179+
? `${added.length} new review or comment event${added.length === 1 ? "" : "s"}.`
180+
: "No new review or comment activity.",
181+
};
182+
}
183+
case "pull_request_closed":
184+
return {
185+
satisfied: current.state !== "open",
186+
summary:
187+
current.state === "merged"
188+
? "Pull request merged."
189+
: current.state === "closed"
190+
? "Pull request closed without merging."
191+
: "Pull request remains open.",
192+
};
193+
}
194+
}
195+
196+
export const layer = Layer.effect(
197+
GitHubPullRequestProbe,
198+
Effect.gen(function* () {
199+
const gitHubCli = yield* GitHubCli.GitHubCli;
200+
return GitHubPullRequestProbe.of({
201+
get: Effect.fn("GitHubPullRequestProbe.get")(function* (input) {
202+
const output = yield* gitHubCli.execute({
203+
cwd: input.cwd,
204+
args: [
205+
"pr",
206+
"view",
207+
String(input.pullRequestNumber),
208+
"--repo",
209+
input.repository,
210+
"--json",
211+
WATCH_FIELDS,
212+
],
213+
});
214+
const raw = yield* decodeRawSnapshot(output.stdout).pipe(
215+
Effect.mapError(
216+
(cause) =>
217+
new GitHubPullRequestProbeDecodeError({
218+
repository: input.repository,
219+
pullRequestNumber: input.pullRequestNumber,
220+
cause,
221+
}),
222+
),
223+
);
224+
return normalizeSnapshot(raw);
225+
}),
226+
});
227+
}),
228+
);

0 commit comments

Comments
 (0)