@reserendipity/dsh-superagent 0.0.0-stage → 0.1.0

package/lib/github-watch.js

@@ -0,0 +1,836 @@
+import { c as key, n as sourceContext, o as sameName, t as health } from "./host-BIWKSB5j.js";
+import { E as CliError, O as validItems, i as pollThreads$1, l as GithubAccountsSchema, n as cursorAt, o as KV, r as pause, t as POLL_HORIZON_MS } from "./poll-Bm5EYA2c.js";
+import { c as object, i as boolean, o as looseObject, p as unknown, r as array, s as number, u as string } from "./schemas-MhNERx8d.js";
+import { C as issueTrigger, S as githubPage, _ as SOURCE, a as pullsOf, b as commentTrigger, c as ciFact, d as githubThreadContext, f as pullChecks, g as IssueSchema, h as CommentSchema$1, l as ciFailures, n as observePull, o as readPull, s as ciCounts, u as ciSummary, v as branchCiTrigger, w as pullTrigger, x as githubAddress, y as ciTrigger } from "./github-pull-DRiuuSs8.js";
+//#region src/sources/github-channel.ts
+/** GitHub outbound channel: posts issue/PR comments and review thread replies under the agent account. */
+const CommentSchema = looseObject({
+	id: number(),
+	body: string().nullish(),
+	in_reply_to_id: number().nullish(),
+	user: looseObject({ login: string() }).nullish()
+});
+/** True when an issue is permanently deleted (410) or locked (403); 404 is retried because it can indicate temporary permission loss on a private repo. */
+const gone = (error) => error instanceof CliError && (error.code === 410 || error.code === 403 && /locked/i.test(error.message));
+const missing = (error) => error instanceof CliError && (error.code === 404 || error.code === 410);
+/** Posts a comment or review-thread reply with an embedded HTML marker so retries do not create duplicate comments. */
+async function sendGithub(host, message) {
+	const { commands } = host;
+	const { repository, github } = commands.deployment;
+	const number = Number(message.channel.address.number);
+	if (!number) throw new Error("Missing GitHub reply target");
+	try {
+		const address = githubAddress(message.channel.address.url ?? "", repository);
+		let rootId;
+		if (address?.pr && address.discussion && address.number === number) {
+			const source = await commands.api(CommentSchema, `pulls/comments/${address.discussion}`).catch((error) => {
+				if (missing(error)) return void 0;
+				throw error;
+			});
+			rootId = source ? source.in_reply_to_id ?? source.id : void 0;
+		}
+		const path = rootId === void 0 ? `issues/${number}/comments` : `pulls/${number}/comments`;
+		const marker = `<!-- dsh-superagent:${message.id} -->`;
+		const mine = (comment) => sameName(comment.user?.login ?? "", github.login) && (rootId === void 0 || comment.in_reply_to_id === rootId) && (comment.body ?? "").includes(marker);
+		if ((await commands.pages(CommentSchema, path)).some(mine)) return "sent";
+		const target = rootId === void 0 ? path : `${path}/${rootId}/replies`;
+		await commands.api(unknown(), target, "--method", "POST", "-f", `body=${message.text}\n\n${marker}`);
+		return "sent";
+	} catch (error) {
+		if (gone(error)) return "gone";
+		throw error;
+	}
+}
+function githubLink(address, links) {
+	const number = address.number ?? "";
+	const review = !!links.repository && !!githubAddress(address.url ?? "", links.repository)?.discussion;
+	return {
+		url: address.url ?? (links.repository ? githubPage(links.repository, Number(number)) : ""),
+		label: review ? {
+			zh: `GitHub #${number} 的 review 讨论`,
+			en: `Review discussion on GitHub #${number}`
+		} : {
+			zh: `GitHub #${number}`,
+			en: `GitHub #${number}`
+		}
+	};
+}
+//#endregion
+//#region src/sources/github.ts
+/** A notification of the agent account; `subject.url` is the API address of its Issue or PR. */
+const NotificationSchema = looseObject({
+	repository: looseObject({ full_name: string() }),
+	subject: looseObject({ url: string().nullish() })
+});
+const GithubConfigSchema = GithubAccountsSchema.extend({
+	pollSeconds: number().int().min(60).max(3600).default(60),
+	failuresBeforeError: number().int().min(1).max(20).default(3),
+	observeIssues: boolean().default(false),
+	observePulls: boolean().default(false),
+	observeComments: boolean().default(false),
+	observeCi: boolean().default(false)
+}).strict();
+const OBSERVED = {
+	issues: "observeIssues",
+	pulls: "observePulls",
+	comments: "observeComments",
+	ci: "observeCi"
+};
+function scopeOf(meta) {
+	if (meta.ci === true) return typeof meta.branch === "string" ? "ci" : void 0;
+	if (meta.kind === "issue") return "issues";
+	if (meta.kind === "pull") return "pulls";
+	return meta.kind === "conversation" || meta.kind === "inline" || meta.kind === "review" ? "comments" : void 0;
+}
+const githubKind = {
+	kind: SOURCE,
+	title: {
+		zh: "GitHub",
+		en: "GitHub"
+	},
+	description: {
+		zh: "智能体的 GitHub 账号；接收仓库里发给它的通知、已订阅 Issue 与 PR 的讨论、CI 状态变化和 PR 合并关闭。",
+		en: "The agent's GitHub accounts; receives notifications to it in the repository, discussion on subscribed Issues and PRs, CI changes, and PR merge or close."
+	},
+	schema: GithubConfigSchema,
+	fields: [
+		{
+			key: "repository",
+			type: "text",
+			pattern: "[A-Za-z0-9_.\\-]+/[A-Za-z0-9_.\\-]+",
+			label: {
+				zh: "监听的仓库",
+				en: "Repository"
+			},
+			hint: {
+				zh: "写作 owner/name。这个来源接收这个仓库的通知和讨论；保存时检查智能体账号能否推送到它，然后重启 dsh-superagent。",
+				en: "Written owner/name. This Source receives the repository's notifications and discussion; saving checks that the agent account can push to it, then restarts dsh-superagent."
+			}
+		},
+		{
+			key: "cli",
+			type: "text",
+			label: {
+				zh: "智能体的 GitHub CLI",
+				en: "Agent GitHub CLI"
+			},
+			hint: {
+				zh: "命令名或绝对路径，通常是用 GH_CONFIG_DIR 登录智能体账号的 gh 包装脚本。智能体以它登录的账号行事，执行器以 gh 调用它。保存时检查它登录的账号能否推送到仓库，然后重启 dsh-superagent。",
+				en: "A command name or absolute path, usually a gh wrapper signed in to the agent account through GH_CONFIG_DIR. The agent acts as the account it is signed in to, and the Executor calls it as gh. Saving checks that this account can push to the repository, then restarts dsh-superagent."
+			}
+		},
+		{
+			key: "pollSeconds",
+			type: "number",
+			advanced: true,
+			min: 60,
+			max: 3600,
+			label: {
+				zh: "轮询间隔 / 秒",
+				en: "Polling interval / seconds"
+			},
+			hint: {
+				zh: "GitHub 要求更长间隔时以 GitHub 为准。",
+				en: "A longer interval requested by GitHub wins."
+			}
+		},
+		{
+			key: "failuresBeforeError",
+			type: "number",
+			advanced: true,
+			min: 1,
+			max: 20,
+			label: {
+				zh: "连续失败几次后报告异常",
+				en: "Failed polls before reporting an error"
+			},
+			hint: {
+				zh: "单次网络中断会在下一次轮询时自动重试，不必报告。",
+				en: "A single network interruption is retried on the next poll and need not be reported."
+			}
+		},
+		{
+			key: "observeIssues",
+			type: "switch",
+			label: {
+				zh: "接收仓库里的新 Issue",
+				en: "Receive new Issues in the repository"
+			},
+			hint: {
+				zh: "打开后，没有 @ 智能体的新 Issue 也会收到，由策略的接收表决定是否成为候选。从打开的时候开始，不读以前的。",
+				en: "New Issues that do not mention the agent are received too, and the Policy's admission table decides whether they become candidates. Starts when switched on; earlier ones are not read."
+			}
+		},
+		{
+			key: "observePulls",
+			type: "switch",
+			label: {
+				zh: "接收仓库里的新 PR",
+				en: "Receive new pull requests in the repository"
+			},
+			hint: {
+				zh: "打开后，没有 @ 智能体的新 PR 也会收到，由策略的接收表决定是否成为候选。",
+				en: "New pull requests that do not mention the agent are received too, and the Policy's admission table decides whether they become candidates."
+			}
+		},
+		{
+			key: "observeComments",
+			type: "switch",
+			label: {
+				zh: "接收仓库里的评论",
+				en: "Receive comments in the repository"
+			},
+			hint: {
+				zh: "打开后，Issue 和 PR 上没有 @ 智能体的评论和代码评论也会收到，由策略的接收表决定是否成为候选。",
+				en: "Comments and review comments on Issues and PRs that do not mention the agent are received too, and the Policy's admission table decides whether they become candidates."
+			}
+		},
+		{
+			key: "observeCi",
+			type: "switch",
+			label: {
+				zh: "接收默认分支的 CI",
+				en: "Receive the default branch's CI"
+			},
+			hint: {
+				zh: "打开后，默认分支的 CI 失败和恢复会收到，由策略的接收表决定是否成为候选。",
+				en: "Failures of the default branch's CI, and its recovery, are received, and the Policy's admission table decides whether they become candidates."
+			}
+		}
+	],
+	scope: ({ meta }, config) => {
+		const row = scopeOf(meta);
+		return {
+			listened: true,
+			observed: row !== void 0 && config[OBSERVED[row]],
+			...row ? { row } : {}
+		};
+	},
+	health: ["github"],
+	channel: {
+		send: sendGithub,
+		link: githubLink
+	},
+	threadContext: githubThreadContext,
+	find: (query) => {
+		const number = (/^#?(\d+)$/.exec(query.trim()) ?? /github\.com\/[^/]+\/[^/]+\/(?:pull|issues)\/(\d+)/.exec(query))?.[1];
+		return {
+			threads: number ? [`${SOURCE}:${number}`] : [],
+			terms: []
+		};
+	},
+	policy: {
+		schema: object({
+			allowed: array(object({ id: string().regex(/^[A-Za-z0-9-]+$/) }).strict()).default([]),
+			bots: array(object({ id: string().regex(/^[A-Za-z0-9-]+(\[bot\])?$/) }).strict()).optional()
+		}).strict(),
+		fields: [{
+			key: "allowed",
+			type: "rows",
+			label: {
+				zh: "能发起工作的 GitHub 账号",
+				en: "GitHub accounts that may originate work"
+			},
+			columns: [{
+				key: "id",
+				type: "text",
+				label: {
+					zh: "账号",
+					en: "Account"
+				},
+				pattern: "[A-Za-z0-9\\-]+"
+			}]
+		}, {
+			key: "bots",
+			type: "rows",
+			label: {
+				zh: "评论可以成为候选的机器人",
+				en: "Bots whose comments may become candidates"
+			},
+			hint: {
+				zh: "名单里的机器人账号（例如 dependabot[bot]）的评论在来源收到时成为推断的候选，交给评估：评论 @ 了智能体，或者打开了“接收仓库里的评论”。它们不能发起明确的请求，也不能停止工单；其他机器人的评论不接收。",
+				en: "A comment of a bot account on this list, such as dependabot[bot], becomes an inferred candidate for an assessment when the Source receives it: when it mentions the agent, or with Receive comments in the repository on. Such a comment never makes an explicit request or stops a ticket; other bots' comments are not admitted."
+			},
+			columns: [{
+				key: "id",
+				type: "text",
+				label: {
+					zh: "账号",
+					en: "Account"
+				},
+				pattern: "[A-Za-z0-9\\-]+(\\[bot\\])?"
+			}]
+		}],
+		explicit: {
+			zh: "名单里的账号在 Issue 或评论里 @ 智能体的账号。",
+			en: "An account on the list mentions the agent's account in an Issue or a comment."
+		},
+		rows(stored) {
+			const config = GithubConfigSchema.partial().parse(stored);
+			const note = (observed) => observed ? {
+				zh: "全部",
+				en: "All"
+			} : {
+				zh: "仅 @",
+				en: "@ only"
+			};
+			const row = (id, label) => ({
+				id,
+				label,
+				note: note(config[OBSERVED[id]]),
+				cells: {
+					listedUnaddressed: !!config[OBSERVED[id]],
+					unlistedAddressed: true,
+					unlistedUnaddressed: !!config[OBSERVED[id]]
+				}
+			});
+			return [
+				row("issues", {
+					zh: "新 Issue",
+					en: "New Issues"
+				}),
+				row("pulls", {
+					zh: "新 PR",
+					en: "New pull requests"
+				}),
+				row("comments", {
+					zh: "评论",
+					en: "Comments"
+				}),
+				{
+					id: "ci",
+					label: {
+						zh: "默认分支的 CI",
+						en: "Default branch CI"
+					},
+					note: config.observeCi ? {
+						zh: "接收",
+						en: "Received"
+					} : {
+						zh: "不接收",
+						en: "Not received"
+					},
+					cells: {
+						listedUnaddressed: false,
+						unlistedAddressed: false,
+						unlistedUnaddressed: !!config.observeCi
+					}
+				}
+			];
+		}
+	},
+	environment: {
+		variables: [
+			{
+				key: "DSH_SUPERAGENT_GITHUB_REPOSITORY",
+				description: {
+					zh: "这个来源监听的仓库，owner/name。智能体在这里开的 PR，分支最后一段是 DSH_SUPERAGENT_NAME 时（例如 agent/$DSH_SUPERAGENT_NAME）会关联到工单",
+					en: "The repository this Source watches, as owner/name. A PR the agent opens here from a branch whose last path segment is DSH_SUPERAGENT_NAME (for example agent/$DSH_SUPERAGENT_NAME) binds to the ticket"
+				}
+			},
+			{
+				key: "DSH_SUPERAGENT_GITHUB_ACCOUNT",
+				description: {
+					zh: "智能体的 GitHub 账号；gh 以它登录，除自动合并外的 GitHub 操作都用 gh，不用其他账号或凭据",
+					en: "The agent's GitHub account. gh is signed in to it; use gh for every GitHub operation except auto-merge, and never another account or credential"
+				}
+			},
+			{
+				key: "DSH_SUPERAGENT_GITHUB_COMMIT_EMAIL",
+				description: {
+					zh: "智能体账号的提交邮箱。这里的 git 没有身份：按提示词写明的作者提交，没有写明时用智能体账号和这个邮箱",
+					en: "Commit email of the agent's account. git has no identity here: commit as the author these instructions name, or as the agent's account with this email when they name none"
+				}
+			},
+			{
+				key: "DSH_SUPERAGENT_GITHUB_NUMBER",
+				description: {
+					zh: "接下工单的 Issue 或 PR 编号；工单不是从 GitHub 来的时为空",
+					en: "Number of the Issue or PR that started the ticket; empty when the ticket did not start on GitHub"
+				}
+			},
+			{
+				key: "DSH_SUPERAGENT_GITHUB_PR_HEAD",
+				description: {
+					zh: "接下工单的 PR 的 head 引用 refs/pull/<编号>/head；不是 PR 时为空",
+					en: "Head ref refs/pull/<number>/head of the PR that started the ticket; empty when it was not a PR"
+				}
+			}
+		],
+		values: ({ deployment, trigger }) => {
+			const number = trigger?.threads[0]?.source === "github" ? Number(trigger.meta.number) || 0 : 0;
+			return {
+				DSH_SUPERAGENT_GITHUB_REPOSITORY: deployment.repository,
+				DSH_SUPERAGENT_GITHUB_ACCOUNT: deployment.github.login,
+				DSH_SUPERAGENT_GITHUB_COMMIT_EMAIL: deployment.github.noreply,
+				DSH_SUPERAGENT_GITHUB_NUMBER: number ? String(number) : "",
+				DSH_SUPERAGENT_GITHUB_PR_HEAD: number && trigger?.meta.isPr === true ? `refs/pull/${number}/head` : ""
+			};
+		}
+	},
+	facts: (deployment) => deployment ? { cli: {
+		zh: `当前账号 @${deployment.github.login}`,
+		en: `Current account @${deployment.github.login}`
+	} } : {}
+};
+const name = "dsh-superagent-github";
+const inject = ["orchestrator"];
+function apply(ctx) {
+	ctx.effect(() => ctx.orchestrator.sources.register(githubKind), "github: source kind");
+	ctx.effect(() => {
+		const controller = new AbortController();
+		const running = ctx.orchestrator.sources.instances().filter((instance) => instance.kind === githubKind.kind && instance.installed).map((instance) => {
+			const source = sourceContext(ctx.orchestrator, githubKind, instance.id);
+			return watch(source, controller.signal).catch((error) => {
+				source.report("github", {
+					state: "error",
+					detail: String(error)
+				});
+			});
+		});
+		return async () => {
+			controller.abort();
+			await Promise.all(running);
+		};
+	});
+}
+/** Returns an error health once `failures` consecutive polls fail, or undefined so a single network interruption stays quiet. */
+function pollFailure(failures, threshold, error) {
+	return failures >= threshold ? health("error", "pollFailures", {
+		count: String(failures),
+		error: String(error)
+	}) : void 0;
+}
+async function watch(ctx, signal) {
+	let interval = 60;
+	let failures = 0;
+	await ctx.ready;
+	while (!ctx.configured()) {
+		if (signal.aborted) return;
+		ctx.report("github", health("paused", "setupPending"));
+		await pause(1e3, signal);
+	}
+	while (!signal.aborted) {
+		const config = ctx.config(SOURCE);
+		try {
+			if (config) interval = await pollRound(ctx, signal);
+			else ctx.report("github", health("paused", "sourceOff"));
+			failures = 0;
+		} catch (error) {
+			failures += 1;
+			const failed = pollFailure(failures, config?.failuresBeforeError ?? 1, error);
+			if (!signal.aborted && failed) ctx.report("github", failed);
+		}
+		await pause(Math.max(interval, ctx.config("github")?.pollSeconds ?? 60) * 1e3, signal);
+	}
+}
+const newRound = (signal) => ({
+	started: (/* @__PURE__ */ new Date()).toISOString(),
+	signal,
+	pulls: /* @__PURE__ */ new Map(),
+	read: /* @__PURE__ */ new Set(),
+	failures: [],
+	dropped: [],
+	abandoned: [],
+	tally: { skipped: 0 }
+});
+const stopped = (ctx, round) => !!round.signal?.aborted || !ctx.config("github");
+const RETRY_WINDOW_MS = 864e5;
+/** True when GitHub returns HTTP 410 (Gone); HTTP 404 is retried because it can indicate revoked access to a private repository. */
+const deleted = (error) => error instanceof CliError && error.code === 410;
+/** Records a failed read on the Thread and in the round; deleted (410) or abandoned (24h+) threads do not fail the round. */
+function failed(ctx, round, number, error, abandoned = false) {
+	if (deleted(error)) round.dropped.push(number);
+	else if (abandoned) round.abandoned.push(number);
+	else round.failures.push(`#${number}: ${String(error)}`);
+	ctx.threads.patch(`github:${number}`, { pollError: String(error) });
+}
+function included(raw) {
+	const split = raw.search(/\r?\n\r?\n/);
+	if (split < 0) throw new Error("GitHub returned no HTTP headers");
+	return {
+		headers: raw.slice(0, split),
+		body: raw.slice(split).trim()
+	};
+}
+const ListedSchema = CommentSchema$1.extend({
+	issue_url: string().nullish(),
+	pull_request_url: string().nullish()
+});
+/** Repository-wide event streams; GitHub's `/issues` endpoint includes PRs, and `/issues/comments` covers issue and PR conversation comments (excluding inline review comments). */
+const STREAMS = [
+	{
+		id: "issues",
+		observed: (config) => config.observeIssues || config.observePulls,
+		path: "issues?state=all"
+	},
+	{
+		id: "comments",
+		observed: (config) => config.observeComments,
+		path: "issues/comments?"
+	},
+	{
+		id: "review-comments",
+		observed: (config) => config.observeComments,
+		path: "pulls/comments?"
+	}
+];
+/** Polls repository-wide streams (new Issues/PRs, comments, default-branch CI); each stream reads from when it was switched on, resets when switched off, and fails independently. */
+async function pollRepository(ctx, round) {
+	const config = ctx.config(SOURCE);
+	if (!config) return;
+	for (const stream of STREAMS) {
+		if (stopped(ctx, round)) return;
+		if (!stream.observed(config)) {
+			ctx.state.set(KV.github.stream(stream.id), void 0);
+			continue;
+		}
+		try {
+			await readStream(ctx, round, stream.id, stream.path, config);
+		} catch (error) {
+			if (!stopped(ctx, round)) round.failures.push(`${stream.id}: ${String(error)}`);
+		}
+	}
+	if (!config.observeCi) {
+		const seen = ctx.state.get(KV.github.branchCi);
+		ctx.state.set(KV.github.branchCi, seen && { revision: seen.revision });
+		return;
+	}
+	try {
+		await pollBranchCi(ctx, round);
+	} catch (error) {
+		if (!stopped(ctx, round)) round.failures.push(`default branch CI: ${String(error)}`);
+	}
+}
+/**
+* Polls one repository-wide event stream (oldest first) since its cursor and steps the cursor to five seconds before the
+* newest item (`cursorAt`), relying on Trigger ID deduplication so repeated messages are no-ops. While the cursor stays
+* unchanged (including when clamped to the hourly horizon), sending the last page's ETag makes an unchanged list return
+* HTTP 304 and cost no rate limit. Items from before their kind was switched on or beyond the horizon are ignored.
+*/
+async function readStream(ctx, round, id, path, config) {
+	const name = KV.github.stream(id);
+	const stored = ctx.state.get(name);
+	const kinds = id === "issues" ? [...config.observeIssues ? ["issues"] : [], ...config.observePulls ? ["pulls"] : []] : ["comments"];
+	const before = typeof stored?.started === "object" ? stored.started : {};
+	const started = Object.fromEntries(kinds.map((kind) => [kind, before[kind] ?? round.started]));
+	const horizon = Math.floor((Date.parse(round.started) - POLL_HORIZON_MS) / 36e5) * 36e5;
+	const since = new Date(Math.max(Date.parse(stored?.since ?? round.started), horizon)).toISOString();
+	const conditional = stored?.etag && stored.since === since ? ["-H", `If-None-Match: ${stored.etag}`] : [];
+	let raw;
+	const listed = `${path}&sort=updated&direction=asc&per_page=100&since=${encodeURIComponent(since)}`;
+	try {
+		raw = await ctx.commands.withSignal(round.signal).api(listed, "--include", ...conditional);
+	} catch (error) {
+		if (error instanceof CliError && error.code === 304) return;
+		throw error;
+	}
+	const { headers, body } = included(raw);
+	const items = validItems(ListedSchema, array(unknown()).parse(JSON.parse(body)), round.tally);
+	const { login } = ctx.deployment.github;
+	const fresh = (at, kind) => kind in started && Date.parse(at ?? "") >= Math.max(Date.parse(started[kind]), horizon);
+	for (const item of items) {
+		if (stopped(ctx, round)) throw new Error("The GitHub Source stopped during the poll");
+		if (sameName(item.user.login, login)) continue;
+		if (id === "issues") {
+			const issue = IssueSchema.safeParse(item);
+			const pr = issue.success && !!issue.data.pull_request;
+			if (!issue.success || !fresh(issue.data.created_at, pr ? "pulls" : "issues")) continue;
+			await ctx.receive(pr ? pullTrigger(issue.data, login) : issueTrigger(issue.data, login));
+			nameThread(ctx, issue.data.number, issue.data.title);
+			continue;
+		}
+		const number = Number(/\/(?:issues|pulls)\/(\d+)$/.exec((id === "comments" ? item.issue_url : item.pull_request_url) ?? "")?.[1]);
+		if (!number || !fresh(item.updated_at ?? item.created_at, "comments")) continue;
+		const ref = {
+			number,
+			isPr: id === "review-comments" || /\/pull\//.test(item.html_url ?? ""),
+			...item.html_url ? { url: item.html_url } : {}
+		};
+		const trigger = commentTrigger(item, ref, id === "comments" ? "conversation" : "inline", login);
+		if (trigger.text) await ctx.receive(trigger);
+	}
+	const newest = Math.max(...items.map((item) => Date.parse(item.updated_at ?? "")).filter(Number.isFinite));
+	const moved = Number.isFinite(newest) ? cursorAt(new Date(newest).toISOString()) : since;
+	const next = Date.parse(moved) > Date.parse(since) ? moved : since;
+	const etag = /^etag:\s*(.+)$/im.exec(headers)?.[1]?.trim();
+	ctx.state.set(name, {
+		since: next,
+		started,
+		...etag && next === since ? { etag } : {}
+	});
+}
+/** Polls default-branch CI checks, emitting a trigger only when the set of failing checks changes after the initial baseline. */
+async function pollBranchCi(ctx, round) {
+	const commands = ctx.commands.withSignal(round.signal);
+	const { default_branch: branch } = await commands.api(looseObject({ default_branch: string() }), "");
+	const head = await commands.api(looseObject({ sha: string() }), `commits/${encodeURIComponent(branch)}`);
+	const snapshot = await pullChecks(commands, head.sha, round.tally);
+	const previous = ctx.state.get(KV.github.branchCi);
+	const known = previous?.branch === branch ? previous.failures : void 0;
+	const failures = ciFailures(snapshot);
+	const counts = ciCounts(snapshot);
+	const now = failures.length || !counts.running ? failures : known ?? [];
+	let revision = previous?.revision ?? 0;
+	if (known && JSON.stringify(now) !== JSON.stringify(known)) {
+		revision += 1;
+		const summary = ciSummary(snapshot, branch, `github/commits/${head.sha}/checks`);
+		const url = `https://github.com/${ctx.deployment.repository}/commit/${head.sha}`;
+		await ctx.receive(branchCiTrigger(branch, head.sha, revision, summary, url));
+		ctx.threads.describe(`github:ci:${branch}`, {
+			label: `CI on ${branch}`,
+			facts: { ci: ciFact(counts) }
+		});
+	}
+	ctx.state.set(KV.github.branchCi, {
+		branch,
+		failures: now,
+		revision
+	});
+}
+/**
+* One polling round: notifications, then observed repository streams, then the PRs of open tickets with their CI, then
+* subscribed Threads. Each step and each Issue, PR, or Thread fails independently so all steps run before the round fails.
+* Other read failures (including 404) fail the round toward the error threshold, whereas deleted (410) or abandoned
+* (24h+) threads are recorded only on the thread and in health detail.
+* @returns the polling interval requested by GitHub, in seconds.
+*/
+async function pollRound(ctx, signal) {
+	const round = newRound(signal);
+	const notified = await pollNotifications(ctx, round).then((value) => ({ value }), (error) => ({ error }));
+	await pollRepository(ctx, round);
+	await pollTicketPulls(ctx, signal, round);
+	await pollThreads(ctx, signal, round);
+	if ("error" in notified) throw notified.error;
+	const { count, interval } = notified.value;
+	if (signal?.aborted) return interval;
+	if (round.failures.length) throw new Error(`${round.failures.length} GitHub reads failed: ${round.failures.slice(0, 3).join("; ")}`);
+	const named = (numbers) => [...new Set(numbers)].sort((a, b) => a - b).map((number) => `#${number}`).join(", ");
+	const dropped = (round.dropped.length ? `; deleted on GitHub: ${named(round.dropped)}` : "") + (round.abandoned.length ? `; dropped after their reads kept failing: ${named(round.abandoned)}` : "") + (round.tally.skipped ? `; ${round.tally.skipped} unreadable items skipped` : "");
+	ctx.report("github", {
+		state: "ready",
+		detail: `${count} notifications; next poll ≥ ${interval}s${dropped}`,
+		at: round.started
+	});
+	return interval;
+}
+/** Reads notifications since the cursor and each Issue or PR they name, advancing the cursor atomically with the retry map for failed reads; deleted (410) Issues are dropped once their error is recorded. */
+async function pollNotifications(ctx, round) {
+	const { state } = ctx;
+	const commands = ctx.commands.withSignal(round.signal);
+	const since = state.get(KV.github.since) ?? round.started;
+	if (state.get(KV.github.since) === void 0) state.set(KV.github.since, since);
+	const { repository } = ctx.deployment;
+	const path = `notifications?all=true&per_page=50&since=${encodeURIComponent(since)}`;
+	const raw = await commands.api(path, "--include");
+	const split = raw.search(/\r?\n\r?\n/);
+	if (split < 0) throw new Error("GitHub returned no HTTP headers");
+	const headers = raw.slice(0, split);
+	const body = raw.slice(split).trim();
+	const asked = Number(/x-poll-interval:\s*(\d+)/i.exec(headers)?.[1] ?? 60);
+	const interval = Math.max(60, Number.isFinite(asked) ? asked : 60);
+	const notifications = /rel="next"/.test(headers) ? await commands.pages(NotificationSchema, path, round.tally) : validItems(NotificationSchema, array(unknown()).parse(JSON.parse(body)), round.tally);
+	const retries = { ...state.get(KV.github.retries) };
+	const items = new Map(Object.entries(retries).map(([number, retry]) => [Number(number), retry]));
+	for (const notification of notifications.reverse()) {
+		if (!sameName(notification.repository.full_name, repository)) continue;
+		const address = githubAddress(notification.subject.url ?? "", repository);
+		if (!address || address.discussion || items.has(address.number)) continue;
+		const { number, pr } = address;
+		items.set(number, {
+			since: [state.get(KV.github.cursor(number)) ?? since, since].sort().at(-1),
+			pr
+		});
+	}
+	for (const [number, item] of items) {
+		if (stopped(ctx, round)) return {
+			count: notifications.length,
+			interval
+		};
+		round.read.add(number);
+		try {
+			await readNotified(ctx, round, number, item);
+			delete retries[number];
+		} catch (error) {
+			if (stopped(ctx, round)) return {
+				count: notifications.length,
+				interval
+			};
+			const retry = {
+				...item,
+				failedAt: item.failedAt ?? round.started,
+				attempts: (item.attempts ?? 0) + 1
+			};
+			const abandoned = Date.parse(round.started) - Date.parse(retry.failedAt) >= RETRY_WINDOW_MS;
+			failed(ctx, round, number, error, abandoned);
+			if (!deleted(error) && !abandoned) {
+				retries[number] = retry;
+				continue;
+			}
+			delete retries[number];
+		}
+	}
+	ctx.atomic(() => {
+		state.set(KV.github.since, cursorAt(round.started));
+		state.set(KV.github.retries, retries);
+	});
+	return {
+		count: notifications.length,
+		interval
+	};
+}
+async function readNotified(ctx, round, number, item) {
+	const { since } = item;
+	let isPr = item.pr;
+	if (!isPr) {
+		const issue = await ctx.commands.withSignal(round.signal).api(IssueSchema, `issues/${number}`);
+		isPr = !!issue.pull_request;
+		if (!isPr) {
+			const { login } = ctx.deployment.github;
+			if (Date.parse(issue.created_at) >= Date.parse(since) && !sameName(issue.user.login, login)) await ctx.receive(issueTrigger(issue, login));
+			await intakeComments(ctx, {
+				number,
+				isPr: false,
+				url: issue.html_url
+			}, since, round);
+			nameThread(ctx, number, issue.title);
+		}
+	}
+	if (isPr) {
+		const pr = await pull(ctx, round, number);
+		const { login } = ctx.deployment.github;
+		if (pr.created_at && Date.parse(pr.created_at) >= Date.parse(since) && !sameName(pr.user.login, login)) {
+			const opened = {
+				number,
+				title: pr.title ?? "",
+				body: pr.body,
+				user: pr.user,
+				created_at: pr.created_at,
+				html_url: pr.html_url
+			};
+			await ctx.receive(pullTrigger(opened, login));
+		}
+		await intakeComments(ctx, {
+			number,
+			isPr: true,
+			url: pr.html_url,
+			prAuthor: pr.user.login
+		}, since, round);
+		if (pr.title) nameThread(ctx, number, pr.title);
+	}
+	ctx.state.set(KV.github.cursor(number), cursorAt(round.started));
+	ctx.threads.patch(`github:${number}`, { pollError: void 0 });
+}
+/** Reads and observes a PR at most once per polling round. */
+function pull(ctx, round, number) {
+	let read = round.pulls.get(number);
+	if (!read) {
+		read = readPull(ctx, number, round.signal).then(async (pr) => {
+			await observePull(ctx, pr);
+			return pr;
+		});
+		round.pulls.set(number, read);
+	}
+	return read;
+}
+async function intakeComments(ctx, ref, since, round) {
+	const commands = ctx.commands.withSignal(round.signal);
+	const { login } = ctx.deployment.github;
+	const kinds = ref.isPr ? [
+		"conversation",
+		"inline",
+		"review"
+	] : ["conversation"];
+	for (const kind of kinds) {
+		const suffix = `&since=${encodeURIComponent(since)}`;
+		const path = kind === "conversation" ? `issues/${ref.number}/comments?per_page=100${suffix}` : kind === "inline" ? `pulls/${ref.number}/comments?per_page=100${suffix}` : `pulls/${ref.number}/reviews?per_page=100`;
+		const comments = await commands.pages(CommentSchema$1, path, round.tally);
+		for (const comment of comments) {
+			if (stopped(ctx, round)) throw new Error("The GitHub Source stopped during the poll");
+			const timestamp = Date.parse(comment.updated_at ?? comment.submitted_at ?? comment.created_at ?? "");
+			if (!Number.isFinite(timestamp) || timestamp < Date.parse(since)) continue;
+			if (sameName(comment.user.login, login)) continue;
+			const trigger = commentTrigger(comment, ref, kind, login);
+			if (trigger.text) await ctx.receive(trigger);
+		}
+	}
+}
+async function pollTicketPulls(ctx, signal, round = newRound(signal)) {
+	const numbers = [...new Set(ctx.tickets.open().flatMap((ticket) => pullsOf(ticket, true)))];
+	for (const number of numbers) {
+		if (stopped(ctx, round)) return;
+		try {
+			const pr = await pull(ctx, round, number);
+			if (pr.state !== "closed" && !pr.merged) await pollChecks(ctx, round, number, pr);
+		} catch (error) {
+			if (!stopped(ctx, round)) failed(ctx, round, number, error);
+		}
+	}
+}
+/** Polls a PR's CI checks; only changes after the first baseline observation become Triggers. */
+async function pollChecks(ctx, round, number, pr) {
+	const snapshot = await pullChecks(ctx.commands.withSignal(round.signal), pr.head.sha, round.tally);
+	const fingerprint = key(JSON.stringify(snapshot));
+	const previous = ctx.state.get(KV.github.ci(number));
+	if (previous?.fingerprint === fingerprint) return;
+	const revision = previous ? previous.revision + 1 : 0;
+	if (previous) await ctx.receive(ciTrigger(pr, revision, ciSummary(snapshot, `PR #${number}`, `github/pulls/${number}/checks`)));
+	ctx.state.set(KV.github.ci(number), {
+		fingerprint,
+		revision
+	});
+	ctx.threads.describe(`github:${number}`, { facts: { ci: ciFact(ciCounts(snapshot)) } });
+}
+function nameThread(ctx, number, title) {
+	ctx.threads.patch(`github:${number}`, { title });
+	ctx.threads.describe(`github:${number}`, {
+		label: `#${number} ${title}`,
+		facts: { number: { value: `#${number}` } }
+	});
+}
+/** Polls subscribed Issue and PR Threads not already read in this round; a deleted (410) Issue is still polled within the horizon (costing one read) and does not fail the round. */
+async function pollThreads(ctx, signal, round = newRound(signal)) {
+	await pollThreads$1(ctx, SOURCE, () => stopped(ctx, round), async (thread) => {
+		try {
+			await pollThread(ctx, round, thread);
+		} catch (error) {
+			if (stopped(ctx, round)) throw error;
+			if (deleted(error)) round.dropped.push(Number(thread.ref.id));
+			else round.failures.push(`${thread.key}: ${String(error)}`);
+			throw error;
+		}
+	}, (thread) => round.read.has(Number(thread.ref.id)));
+}
+async function pollThread(ctx, round, thread) {
+	if (thread.ref.id.startsWith("ci:")) return;
+	const number = Number(thread.ref.id);
+	if (!number) throw new Error("Subscribed thread has no GitHub issue or PR number");
+	round.read.add(number);
+	if (typeof thread.meta.isPr !== "boolean" || typeof thread.meta.title !== "string") {
+		const issue = await ctx.commands.withSignal(round.signal).api(IssueSchema, `issues/${number}`);
+		ctx.threads.patch(thread.key, {
+			number,
+			isPr: !!issue.pull_request,
+			url: issue.html_url
+		});
+		if (issue.title) nameThread(ctx, number, issue.title);
+		thread = ctx.threads.get(thread.key) ?? thread;
+	}
+	const checkpoint = KV.github.cursor(number);
+	const since = ctx.state.get(checkpoint) ?? thread.createdAt;
+	if (thread.meta.isPr === true) {
+		const pr = await pull(ctx, round, number);
+		await intakeComments(ctx, {
+			number,
+			isPr: true,
+			url: pr.html_url,
+			prAuthor: pr.user.login
+		}, since, round);
+	} else await intakeComments(ctx, {
+		number,
+		isPr: false
+	}, since, round);
+	ctx.state.set(checkpoint, cursorAt(round.started));
+}
+//#endregion
+export { apply, commentTrigger, githubKind, inject, name, pollFailure, pollRound, pollThreads, pollTicketPulls };