wolli 0.0.4 → 0.0.6

package/built-in/plugins/github/github-chat.ts

@@ -0,0 +1,216 @@
+/**
+ * GitHub chat routing, as one workflows file. It maps the transport's generic events onto
+ * per-conversation sessions and ships replies back as comments; the transport itself never
+ * touches a session.
+ *
+ *  - `inboundIssueComment` / `inboundReviewComment` bind each issue/PR conversation to its own
+ *    session by a `github:thread` tag and deliver an @mention as a followUp — gated on the
+ *    `mention` trigger and the self/bot/marker loop guard. The summoning comment gets an `eyes`
+ *    reaction as an acknowledgment, and when the mention is on a pull request the PR's source is
+ *    checked out (see `buildReviewTurn`) so the agent reviews real code with its own file tools.
+ *  - `auto` seeds a "review this PR" turn when a PR is opened/updated, gated on the `auto`
+ *    trigger and deduped on head SHA via a session tag so the same commits are reviewed once.
+ *  - `reply` ships the turn's final assistant text back as a comment on `agent_end`, riding the
+ *    producing session's `github:thread` tag, chunked to GitHub's comment size limit and tagged
+ *    with the loop-prevention marker.
+ */
+
+import { type WorkflowContext, wolli } from "wolli";
+import {
+	chunkComment,
+	extractMention,
+	GITHUB_COMMENT_MARKER,
+	isIgnoredInboundComment,
+	parseThreadTag,
+} from "./github-api.ts";
+import { reviewPaths } from "./github-workspace.ts";
+import github from "./index.ts";
+
+/**
+ * Check the pull request out under the agent workspace and return the review turn to send (plus the
+ * head SHA, which the caller records on the session so the review tool can anchor inline comments):
+ * the `lead` (the reviewer's actual ask), then where the working copy is and how to diff it. The
+ * agent reads and greps the real tree — nothing about the code is pasted into the prompt.
+ */
+async function buildReviewTurn(
+	ctx: WorkflowContext,
+	repo: string,
+	pullRequestNumber: number,
+	lead: string,
+): Promise<{ message: string; headSha: string }> {
+	const api = ctx.integration(github);
+	const [pr, filesResult] = await Promise.all([
+		api.getPullRequest({ repo, pullRequestNumber }) as Promise<{
+			title?: string;
+			body?: string;
+			head?: { sha?: string };
+			base?: { sha?: string };
+		} | null>,
+		api.listPullRequestFiles({ repo, pullRequestNumber }) as Promise<{
+			files?: Array<{ filename?: string }>;
+		} | null>,
+	]);
+
+	const headSha = pr?.head?.sha ?? "";
+	const baseSha = pr?.base?.sha ?? "";
+	const { absDir, relDir } = reviewPaths(ctx.agent.cwd, repo, pullRequestNumber);
+	await api.checkoutPullRequest({ repo, pullRequestNumber, destDir: absDir, headSha, baseSha });
+
+	const changed = (filesResult?.files ?? []).map((f) => `  ${f.filename ?? "?"}`).join("\n");
+	const body = (pr?.body ?? "").trim();
+
+	const message = [
+		lead,
+		"",
+		`Repository: ${repo}   Pull request #${pullRequestNumber}: ${pr?.title ?? ""}`.trimEnd(),
+		...(body ? [`Description: ${body.slice(0, 2000)}`] : []),
+		"",
+		`A read-only checkout of the head commit is at ${relDir} (relative to your working directory).`,
+		"You have the full source tree — read any file, and grep the tree to check for duplication or",
+		"to see how the changed code is used elsewhere.",
+		"",
+		`See exactly what changed:  git -C ${relDir} diff ${baseSha} ${headSha}`,
+		"",
+		"Files changed in this PR:",
+		changed || "  (none reported)",
+		"",
+		"Review for correctness, code duplication, and potential bugs. Leave each finding as an inline",
+		'comment on the exact line with the github_review tool (action "comment"), then submit your',
+		'verdict with action "submit" (REQUEST_CHANGES if there are real problems, otherwise COMMENT).',
+	].join("\n");
+	return { message, headSha };
+}
+
+/** Route an @mention comment into the conversation's session, if the mention trigger is enabled. */
+async function routeMention(
+	ctx: WorkflowContext,
+	comment: {
+		repo: string;
+		number: number;
+		body: string;
+		authorLogin: string;
+		authorType: string;
+		commentId: number;
+		subject: "issue_comment" | "pull_request_review_comment";
+		isPullRequest: boolean;
+	},
+): Promise<void> {
+	const { botLogin, triggers } = await ctx.integration(github).getSettings();
+	if (!triggers.includes("mention")) return;
+	if (isIgnoredInboundComment(comment.body, comment.authorLogin, comment.authorType, botLogin)) return;
+	const mention = extractMention(comment.body, botLogin);
+	if (!mention) return;
+
+	// Acknowledge on sight: drop an eyes reaction on the comment that summoned us. Non-fatal —
+	// a reaction failure must never stop the review from running.
+	try {
+		await ctx.integration(github).addReaction({
+			repo: comment.repo,
+			subject: comment.subject,
+			commentId: comment.commentId,
+			content: "eyes",
+		});
+	} catch (err) {
+		console.error("[github] could not add reaction:", err instanceof Error ? err.message : err);
+	}
+
+	const tag = { "github:thread": `${comment.repo}#${comment.number}` };
+	const [match] = await ctx.agent.findSessions(tag);
+	const session = match
+		? await ctx.agent.openSession(match.id)
+		: await ctx.agent.createSession({ setup: (s) => s.appendTags(tag) });
+
+	// On a PR, check the code out for the agent; on a plain issue, the comment text is the whole ask.
+	const text = mention.message || comment.body;
+	if (comment.isPullRequest) {
+		const { message, headSha } = await buildReviewTurn(ctx, comment.repo, comment.number, text);
+		// Record the head SHA so the github_review tool can anchor inline comments to this commit.
+		session.setTags({ "github:head-sha": headSha });
+		await session.sendUserMessage(message, { deliverAs: "followUp" });
+	} else {
+		// followUp queues behind a running turn instead of interrupting it.
+		await session.sendUserMessage(text, { deliverAs: "followUp" });
+	}
+}
+
+// evt is typed from the event schema
+export const inboundIssueComment = github.on("issue_comment", async (evt, ctx) => {
+	await routeMention(ctx, {
+		repo: evt.repo,
+		number: evt.issueNumber,
+		body: evt.body,
+		authorLogin: evt.authorLogin,
+		authorType: evt.authorType,
+		commentId: evt.commentId,
+		subject: "issue_comment",
+		isPullRequest: evt.isPullRequest,
+	});
+});
+
+export const inboundReviewComment = github.on("pull_request_review_comment", async (evt, ctx) => {
+	await routeMention(ctx, {
+		repo: evt.repo,
+		number: evt.pullRequestNumber,
+		body: evt.body,
+		authorLogin: evt.authorLogin,
+		authorType: evt.authorType,
+		commentId: evt.commentId,
+		subject: "pull_request_review_comment",
+		isPullRequest: true,
+	});
+});
+
+export const auto = github.on("pull_request", async (evt, ctx) => {
+	const { triggers } = await ctx.integration(github).getSettings();
+	if (!triggers.includes("auto")) return;
+	if (evt.draft) return;
+	if (!["opened", "synchronize", "reopened", "ready_for_review"].includes(evt.action)) return;
+
+	const tag = { "github:thread": `${evt.repo}#${evt.pullRequestNumber}` };
+	const [match] = await ctx.agent.findSessions(tag);
+	const session = match
+		? await ctx.agent.openSession(match.id)
+		: await ctx.agent.createSession({ setup: (s) => s.appendTags(tag) });
+
+	// Dedupe on head SHA via a session tag: the same commits are reviewed once, even if the
+	// transport re-emits the PR. Persist the marker before sending (at-most-once).
+	if (session.getTags()["github:reviewed-sha"] === evt.headSha) return;
+	session.setTags({ "github:reviewed-sha": evt.headSha });
+
+	const { message, headSha } = await buildReviewTurn(
+		ctx,
+		evt.repo,
+		evt.pullRequestNumber,
+		"A pull request was opened or updated for review.",
+	);
+	// Record the head SHA so the github_review tool can anchor inline comments to this commit.
+	session.setTags({ "github:head-sha": headSha });
+	await session.sendUserMessage(message, { deliverAs: "followUp" });
+});
+
+export const reply = wolli.on("agent_end", async (evt, ctx) => {
+	const tags = ctx.session.getTags();
+	const thread = tags["github:thread"];
+	if (!thread) return; // not a github-bound session
+	// The github_review tool posts a formal review and sets this flag; when it did, stand down so the
+	// summary is not also posted as a duplicate timeline comment. Clear it for the next turn.
+	if (tags["github:review-posted"] === "1") {
+		ctx.session.setTags({ "github:review-posted": "" });
+		return;
+	}
+	const { repo, number } = parseThreadTag(thread);
+
+	const text = evt.messages
+		.filter((m) => m.role === "assistant")
+		.at(-1)
+		?.content.filter((c) => c.type === "text")
+		.map((c) => c.text)
+		.join("")
+		.trim();
+	if (!text) return; // a pure tool-call turn sends nothing
+
+	// The marker rides the last chunk; combined with the bot-login check it prevents reply loops.
+	for (const body of chunkComment(`${text}\n\n${GITHUB_COMMENT_MARKER}`)) {
+		await ctx.integration(github).postComment({ repo, issueNumber: number, body });
+	}
+});

package/built-in/plugins/github/github-review.ts

@@ -0,0 +1,102 @@
+/**
+ * GitHub review tool — lets the review agent post an actual pull-request review rather than a
+ * plain comment: inline notes anchored to diff lines (`action: "comment"`) and a formal verdict
+ * (`action: "submit"`). It drives the github integration's write actions, deriving the target PR
+ * and head commit from the session's `github:thread` / `github:head-sha` tags (set when the review
+ * turn is seeded), so the agent only supplies path/line/body.
+ *
+ * `submit` is capped to COMMENT / REQUEST_CHANGES — the reviewer never auto-approves. On submit it
+ * sets `github:review-posted` so the `agent_end` reply workflow stands down and does not also post
+ * the summary as a duplicate timeline comment.
+ */
+
+import { defineTool } from "wolli";
+import { Type } from "typebox";
+import { parseThreadTag } from "./github-api.ts";
+import github from "./index.ts";
+
+const ReviewParams = Type.Object({
+	action: Type.Union([Type.Literal("comment"), Type.Literal("submit")], {
+		description: "comment: leave an inline comment on a diff line. submit: submit the overall review verdict.",
+	}),
+	path: Type.Optional(Type.String({ description: "comment: file path, exactly as it appears in the PR." })),
+	line: Type.Optional(
+		Type.Number({ description: "comment: line number in the file to attach to. Must be a line this PR changed." }),
+	),
+	side: Type.Optional(
+		Type.Union([Type.Literal("LEFT"), Type.Literal("RIGHT")], {
+			description: "comment: RIGHT (the new version, default) or LEFT (the old version).",
+		}),
+	),
+	body: Type.Optional(Type.String({ description: "comment: the note. submit: the review summary (Markdown)." })),
+	event: Type.Optional(
+		Type.Union([Type.Literal("COMMENT"), Type.Literal("REQUEST_CHANGES")], {
+			description: "submit: COMMENT for a non-blocking review, REQUEST_CHANGES to block the merge.",
+		}),
+	),
+});
+
+function text(message: string, details: unknown) {
+	return { content: [{ type: "text" as const, text: message }], details };
+}
+
+export default defineTool({
+	name: "github_review",
+	label: "GitHub review",
+	description:
+		"Post a review on the pull request under review. action=comment leaves an inline comment on a specific file+line of the diff; action=submit submits the overall verdict (COMMENT or REQUEST_CHANGES) with a summary. The target PR is the current review session, so you only supply path/line/body — not the repo or PR number.",
+	promptSnippet: "github_review: leave inline PR review comments and submit a verdict (COMMENT / REQUEST_CHANGES).",
+	promptGuidelines: [
+		"When reviewing a pull request, leave each finding as an inline github_review comment on the exact changed line, then finish with one github_review submit — REQUEST_CHANGES if there are real problems, otherwise COMMENT.",
+	],
+	parameters: ReviewParams,
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const tags = ctx.session.getTags();
+		const thread = tags["github:thread"];
+		if (!thread) return text("Error: this is not a GitHub pull-request review session.", { error: "no thread" });
+
+		let repo: string;
+		let pullRequestNumber: number;
+		try {
+			({ repo, number: pullRequestNumber } = parseThreadTag(thread));
+		} catch (err) {
+			return text(`Error: ${err instanceof Error ? err.message : String(err)}`, { error: "bad thread tag" });
+		}
+
+		const gh = ctx.integration(github);
+		try {
+			if (params.action === "comment") {
+				if (!params.path || params.line === undefined || !params.body) {
+					return text("Error: path, line, and body are required for action=comment.", { error: "missing fields" });
+				}
+				const commitId = tags["github:head-sha"];
+				if (!commitId) {
+					return text("Error: the PR head commit is unknown, cannot anchor an inline comment.", { error: "no head sha" });
+				}
+				const result = await gh.createReviewComment({
+					repo,
+					pullRequestNumber,
+					body: params.body,
+					commitId,
+					path: params.path,
+					line: params.line,
+					side: params.side,
+				});
+				return text(`Left an inline comment on ${params.path}:${params.line}.`, result);
+			}
+
+			// action === "submit"
+			if (!params.event) {
+				return text("Error: event (COMMENT or REQUEST_CHANGES) is required for action=submit.", { error: "missing event" });
+			}
+			const result = await gh.submitReview({ repo, pullRequestNumber, event: params.event, body: params.body });
+			// Stand down the agent_end reply: the formal review is this turn's output, so it must not
+			// also be posted as a duplicate timeline comment.
+			ctx.session.setTags({ "github:review-posted": "1" });
+			return text(`Submitted a ${params.event} review on ${repo}#${pullRequestNumber}.`, result);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			return text(`Error: ${message}`, { error: message });
+		}
+	},
+});

package/built-in/plugins/github/github-workspace.ts

@@ -0,0 +1,84 @@
+/**
+ * Host-side git plumbing for the review checkout.
+ *
+ * Unlike `github-api.ts` this module is NOT host-free: it shells out to the `git` CLI and writes
+ * under the agent home dir. Its job is to put a pull request's full source tree on disk where the
+ * review agent's native `read`/`grep`/`bash` tools can see it, so the agent reviews real code
+ * instead of a diff pasted into its prompt.
+ *
+ * Two safety properties this file is responsible for:
+ *  - The App installation token is passed to `git` only on the argv of a single `fetch` (in the
+ *    daemon process), never written to disk and never stored as a remote — so it cannot be
+ *    recovered from `.git/config` by the agent.
+ *  - No remote is configured on the checkout, so there is no push target: the working copy is
+ *    read-only as far as the agent is concerned. (A bash-capable agent could still add a remote
+ *    and push with the host's ambient credentials; a hard guarantee needs a network-jailed
+ *    sandbox. This removes the footgun, not the determined path.)
+ *
+ * The checkout lives under `workspace/` (a subdir of the agent home) because that is the one
+ * location visible to the agent's tools across every backend: host, the srt write-jail (rooted
+ * at the agent home), and the docker bind-mount (the agent home mounted at the identical path).
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Absolute and cwd-relative paths of a PR's review checkout, under the agent's `workspace/`. */
+export function reviewPaths(
+	agentCwd: string,
+	repo: string,
+	pullRequestNumber: number,
+): { absDir: string; relDir: string } {
+	const slug = `${repo.replace("/", "__")}__${pullRequestNumber}`;
+	const relDir = join("workspace", "reviews", slug);
+	return { absDir: join(agentCwd, relDir), relDir };
+}
+
+/**
+ * Run one git command as an argv array (no shell, so nothing in the args is interpolated). The
+ * error carries only the subcommand (`args[0]`) and stderr — never the full args — so a token
+ * passed in a fetch URL cannot leak into a thrown/logged error.
+ */
+function runGit(args: string[], cwd: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const child = spawn("git", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
+		let stderr = "";
+		child.stderr?.on("data", (chunk) => {
+			stderr += String(chunk);
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) resolve();
+			else reject(new Error(`git ${args[0]} exited ${code}: ${stderr.trim().slice(0, 500)}`));
+		});
+	});
+}
+
+/**
+ * Check out `headSha` (detached, depth 1) at `destDir`, with `baseSha` fetched alongside it so the
+ * agent can `git diff <base> <head>`. Initializes the dir on first use and refreshes it in place on
+ * later turns. The tokenized URL is passed only to the `fetch` and is never stored as a remote.
+ */
+export async function checkout(opts: {
+	destDir: string;
+	repo: string;
+	token: string;
+	headSha: string;
+	baseSha: string;
+}): Promise<void> {
+	const { destDir, repo, token, headSha, baseSha } = opts;
+	if (!headSha) throw new Error("checkout: missing head sha");
+	const tokenUrl = `https://x-access-token:${token}@github.com/${repo}.git`;
+	const shas = baseSha && baseSha !== headSha ? [headSha, baseSha] : [headSha];
+
+	if (!existsSync(join(destDir, ".git"))) {
+		await mkdir(destDir, { recursive: true });
+		await runGit(["init", "-q"], destDir);
+	}
+	await runGit(["fetch", "--depth", "1", tokenUrl, ...shas], destDir);
+	await runGit(["checkout", "-q", "--detach", headSha], destDir);
+	await runGit(["reset", "--hard", "-q", headSha], destDir);
+	await runGit(["clean", "-fdxq"], destDir);
+}