@vercel/factory 0.0.14 → 0.0.15

package/dist/code-review/eve-post-review.d.mts

@@ -0,0 +1,70 @@
+import { ChangeId, TaskId } from "../schema/id.mjs";
+import { RepositorySlug } from "../schema/repository.mjs";
+import { TaskState } from "../schema/task.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { CompletedReview, CompletedReviewFinding } from "./contracts.mjs";
+import { SubmittedPullRequestReview } from "../github.mjs";
+import { PublishedGitHubReview } from "./github-contracts.mjs";
+import { ToolContext, ToolDefinition } from "eve/tools";
+//#region src/code-review/eve-post-review.d.ts
+/** Change, repository, and Task capabilities required by the review publication tool. */
+type GitHubPostReviewToolStores = Pick<FactoryStores, "changes" | "repositories" | "tasks">;
+/** Configures GitHub access, publication, and durable review-reporting callbacks. */
+interface GitHubPostReviewToolOptions {
+  stores: GitHubPostReviewToolStores;
+  tokenForRepository: (repository: RepositorySlug) => Promise<string>;
+  publishReviews?: boolean;
+  onCompleted?: (completed: CompletedReview) => Promise<void>;
+  onPublished?: (published: PublishedGitHubReview) => Promise<void>;
+  fetch?: typeof globalThis.fetch;
+}
+/** Machine-readable reason a code review could not be recorded. */
+type GitHubPostReviewFailureCode = "task_not_found" | "task_kind_mismatch" | "task_not_running" | "change_not_found" | "change_not_reviewable" | "repository_not_found" | "stale_pull_request_head";
+/** Outcome returned after validating, recording, and optionally publishing a code review. */
+type GitHubPostReviewResult = {
+  readonly recorded: false;
+  readonly code: GitHubPostReviewFailureCode;
+  readonly reason: string;
+  readonly taskState?: TaskState;
+  readonly verdict?: never;
+  readonly published?: never;
+  readonly review?: never;
+} | {
+  readonly recorded: true;
+  readonly verdict: CompletedReview["verdict"];
+  readonly published: false;
+  readonly review?: never;
+  readonly taskState: "succeeded";
+} | {
+  readonly recorded: true;
+  readonly verdict: CompletedReview["verdict"];
+  readonly published: true;
+  readonly review: SubmittedPullRequestReview;
+  readonly taskState: "succeeded";
+};
+/** Inline review finding accepted before Factory assigns its stable fingerprint. */
+interface GitHubPostReviewCommentInput extends Pick<CompletedReviewFinding, "path" | "line" | "body"> {
+  key?: string;
+  title?: string;
+}
+/** Completed review supplied for validation, recording, and optional GitHub publication. */
+interface GitHubPostReviewInput {
+  taskId: TaskId;
+  changeId: ChangeId;
+  verdict: CompletedReview["verdict"];
+  headSha: string;
+  summary: string;
+  comments: readonly GitHubPostReviewCommentInput[];
+}
+/** Eve outcome tool that records and optionally publishes one completed code review. */
+interface GitHubPostReviewTool extends ToolDefinition<GitHubPostReviewInput, GitHubPostReviewResult> {
+  execute(input: GitHubPostReviewInput, ctx: ToolContext): Promise<GitHubPostReviewResult>;
+}
+/**
+ * Publish an independent review of an existing pull request and finish the
+ * review task without changing the pull request's factory lifecycle.
+ */
+declare function createGitHubPostReviewTool(input: GitHubPostReviewToolOptions): GitHubPostReviewTool;
+//#endregion
+export { GitHubPostReviewCommentInput, GitHubPostReviewFailureCode, GitHubPostReviewInput, GitHubPostReviewResult, GitHubPostReviewTool, GitHubPostReviewToolOptions, GitHubPostReviewToolStores, createGitHubPostReviewTool };
+//# sourceMappingURL=eve-post-review.d.mts.map

package/dist/code-review/eve-post-review.mjs

@@ -0,0 +1,183 @@
+import { changeIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { requireTaskExecution } from "../eve/task-execution.mjs";
+import { StalePullRequestHeadError, readPullRequestHead, submitPullRequestReview } from "../github.mjs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { defineTool } from "eve/tools";
+//#region src/code-review/eve-post-review.ts
+const reviewCommentSchema = z.strictObject({
+	key: z.string().min(1).max(80).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).optional().describe("Stable kebab-case identity for this defect and cause; keep it unchanged across reruns."),
+	title: z.string().min(1).max(200).optional().describe("Short finding title."),
+	path: z.string().min(1).max(500).describe("Repository-relative file path."),
+	line: z.number().int().min(1).describe("Line in the pull request's new version."),
+	body: z.string().min(1).max(5e3).describe("Markdown explaining the finding and a concrete fix.")
+});
+const reviewCommentsSchema = z.array(reviewCommentSchema).max(50).default([]).superRefine((comments, context) => {
+	const seen = /* @__PURE__ */ new Set();
+	comments.forEach((comment, index) => {
+		if (comment.key === void 0) return;
+		if (seen.has(comment.key)) context.addIssue({
+			code: "custom",
+			message: `duplicate finding key: ${comment.key}`,
+			path: [index, "key"]
+		});
+		seen.add(comment.key);
+	});
+}).readonly();
+/**
+* Publish an independent review of an existing pull request and finish the
+* review task without changing the pull request's factory lifecycle.
+*/
+function createGitHubPostReviewTool(input) {
+	const { stores, ...options } = input;
+	return defineTool({
+		description: "Record a completed code review and finish your code_review task. Results may be reported through completion callbacks instead of a GitHub review; use request_changes only for blocking findings.",
+		inputSchema: z.object({
+			taskId: taskIdSchema.describe("Your code_review task."),
+			changeId: changeIdSchema.describe("The pull request change from your starting message."),
+			verdict: z.enum([
+				"approve",
+				"request_changes",
+				"comment"
+			]),
+			headSha: z.string().regex(/^[0-9a-f]{40}$/).describe("Commit returned by fetch_pull_request."),
+			summary: z.string().min(1).max(5e3).describe("Markdown summary of what you reviewed and found."),
+			comments: reviewCommentsSchema
+		}),
+		async execute({ taskId, changeId, verdict, headSha, summary, comments }, ctx) {
+			const task = await requireTaskExecution(stores, ctx, taskId);
+			if (task.kind !== "code_review") return {
+				recorded: false,
+				code: "task_kind_mismatch",
+				reason: `${taskId} is not a code_review task`
+			};
+			if (task.state !== "running") return {
+				recorded: false,
+				code: "task_not_running",
+				reason: `task is ${task.state}, not running`
+			};
+			const change = await stores.changes.get(changeId);
+			if (change === null) return {
+				recorded: false,
+				code: "change_not_found",
+				reason: `change ${changeId} does not exist`
+			};
+			if (change.state !== "verifying" && change.state !== "ready") return {
+				recorded: false,
+				code: "change_not_reviewable",
+				reason: `change is ${change.state}, not open for review`
+			};
+			const repository = await stores.repositories.get(change.repositoryId);
+			if (repository === null) return {
+				recorded: false,
+				code: "repository_not_found",
+				reason: `repository ${change.repositoryId} does not exist`
+			};
+			if (task.changeId !== change.id || task.repositoryIds.length !== 1 || task.repositoryIds[0] !== repository.id) throw new Error("Authenticated review Task, Change, and repository must match");
+			const token = await options.tokenForRepository(repository.slug);
+			await requireTaskExecution(stores, ctx, taskId);
+			const completedComments = comments.map((comment) => {
+				const key = comment.key ?? legacyFindingKey(comment);
+				return {
+					...comment,
+					key,
+					title: comment.title ?? "Review finding",
+					fingerprint: createHash("sha256").update(`${repository.slug.toLowerCase()}#${change.prNumber}:${key}`).digest("hex")
+				};
+			});
+			const completed = {
+				taskId,
+				changeId,
+				repository: repository.slug,
+				pullRequestNumber: change.prNumber,
+				headSha,
+				verdict,
+				summary,
+				comments: completedComments
+			};
+			const publish = options.publishReviews !== false;
+			let review;
+			try {
+				if (publish) review = await submitPullRequestReview({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commitId: headSha,
+					event: verdict === "approve" ? "APPROVE" : verdict === "request_changes" ? "REQUEST_CHANGES" : "COMMENT",
+					body: summary,
+					comments: completedComments
+				});
+				else {
+					const head = await readPullRequestHead({
+						repository: repository.slug,
+						token,
+						fetch: options.fetch,
+						pullRequestNumber: change.prNumber
+					});
+					if (head.sha !== headSha) throw new StalePullRequestHeadError(headSha, head.sha);
+				}
+			} catch (error) {
+				if (!(error instanceof StalePullRequestHeadError)) throw error;
+				const resolved = await stores.tasks.transition(taskId, "cancelled", {
+					expectFrom: "running",
+					expectAttempt: task.attempt,
+					expectExecution: task.execution,
+					reason: `review superseded by newer commits: ${error.message}`
+				}).catch(() => null);
+				return {
+					recorded: false,
+					code: "stale_pull_request_head",
+					reason: error.message,
+					taskState: resolved?.state ?? (await stores.tasks.get(taskId).catch(() => null))?.state ?? task.state
+				};
+			}
+			await requireTaskExecution(stores, ctx, taskId);
+			if (review !== void 0) await options.onPublished?.({
+				...completed,
+				review
+			});
+			await requireTaskExecution(stores, ctx, taskId);
+			await options.onCompleted?.(completed);
+			await stores.tasks.transition(taskId, "verifying", {
+				expectFrom: "running",
+				expectAttempt: task.attempt,
+				expectExecution: task.execution,
+				reason: summary
+			});
+			await stores.tasks.transition(taskId, "succeeded", {
+				expectFrom: "verifying",
+				expectAttempt: task.attempt,
+				expectExecution: task.execution,
+				output: {
+					changeId,
+					headSha,
+					verdict,
+					summary,
+					findingCount: completedComments.length,
+					published: review !== void 0,
+					...review === void 0 ? {} : { review }
+				}
+			});
+			return review === void 0 ? {
+				recorded: true,
+				verdict,
+				published: false,
+				taskState: "succeeded"
+			} : {
+				recorded: true,
+				verdict,
+				published: true,
+				review,
+				taskState: "succeeded"
+			};
+		}
+	});
+}
+function legacyFindingKey(comment) {
+	return `legacy-${createHash("sha256").update(`${comment.path}:${comment.line}:${comment.body}`).digest("hex").slice(0, 24)}`;
+}
+//#endregion
+export { createGitHubPostReviewTool };
+
+//# sourceMappingURL=eve-post-review.mjs.map

package/dist/code-review/eve-post-review.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-post-review.mjs","names":[],"sources":["../../src/code-review/eve-post-review.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport type { CompletedReview, CompletedReviewFinding } from \"../code-review/contracts\";\nimport type { PublishedGitHubReview } from \"../code-review/github-contracts\";\nimport { requireTaskExecution } from \"../eve/task-execution\";\nimport {\n  readPullRequestHead,\n  StalePullRequestHeadError,\n  submitPullRequestReview,\n  type PullRequestReviewComment,\n  type SubmittedPullRequestReview,\n} from \"../github\";\nimport { changeIdSchema, taskIdSchema, type ChangeId, type TaskId } from \"../schema/id\";\nimport type { RepositorySlug } from \"../schema/repository\";\nimport type { TaskState } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\n\n/** Change, repository, and Task capabilities required by the review publication tool. */\nexport type GitHubPostReviewToolStores = Pick<FactoryStores, \"changes\" | \"repositories\" | \"tasks\">;\n\n/** Configures GitHub access, publication, and durable review-reporting callbacks. */\nexport interface GitHubPostReviewToolOptions {\n  stores: GitHubPostReviewToolStores;\n  tokenForRepository: (repository: RepositorySlug) => Promise<string>;\n  publishReviews?: boolean;\n  onCompleted?: (completed: CompletedReview) => Promise<void>;\n  onPublished?: (published: PublishedGitHubReview) => Promise<void>;\n  fetch?: typeof globalThis.fetch;\n}\n\n/** Machine-readable reason a code review could not be recorded. */\nexport type GitHubPostReviewFailureCode =\n  | \"task_not_found\"\n  | \"task_kind_mismatch\"\n  | \"task_not_running\"\n  | \"change_not_found\"\n  | \"change_not_reviewable\"\n  | \"repository_not_found\"\n  | \"stale_pull_request_head\";\n\n/** Outcome returned after validating, recording, and optionally publishing a code review. */\nexport type GitHubPostReviewResult =\n  | {\n      readonly recorded: false;\n      readonly code: GitHubPostReviewFailureCode;\n      readonly reason: string;\n      readonly taskState?: TaskState;\n      readonly verdict?: never;\n      readonly published?: never;\n      readonly review?: never;\n    }\n  | {\n      readonly recorded: true;\n      readonly verdict: CompletedReview[\"verdict\"];\n      readonly published: false;\n      readonly review?: never;\n      readonly taskState: \"succeeded\";\n    }\n  | {\n      readonly recorded: true;\n      readonly verdict: CompletedReview[\"verdict\"];\n      readonly published: true;\n      readonly review: SubmittedPullRequestReview;\n      readonly taskState: \"succeeded\";\n    };\n\n/** Inline review finding accepted before Factory assigns its stable fingerprint. */\nexport interface GitHubPostReviewCommentInput extends Pick<\n  CompletedReviewFinding,\n  \"path\" | \"line\" | \"body\"\n> {\n  key?: string;\n  title?: string;\n}\n\n/** Completed review supplied for validation, recording, and optional GitHub publication. */\nexport interface GitHubPostReviewInput {\n  taskId: TaskId;\n  changeId: ChangeId;\n  verdict: CompletedReview[\"verdict\"];\n  headSha: string;\n  summary: string;\n  comments: readonly GitHubPostReviewCommentInput[];\n}\n\n/** Eve outcome tool that records and optionally publishes one completed code review. */\nexport interface GitHubPostReviewTool extends ToolDefinition<\n  GitHubPostReviewInput,\n  GitHubPostReviewResult\n> {\n  execute(input: GitHubPostReviewInput, ctx: ToolContext): Promise<GitHubPostReviewResult>;\n}\n\nconst reviewCommentSchema = z.strictObject({\n  key: z\n    .string()\n    .min(1)\n    .max(80)\n    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)\n    .optional()\n    .describe(\n      \"Stable kebab-case identity for this defect and cause; keep it unchanged across reruns.\",\n    ),\n  title: z.string().min(1).max(200).optional().describe(\"Short finding title.\"),\n  path: z.string().min(1).max(500).describe(\"Repository-relative file path.\"),\n  line: z.number().int().min(1).describe(\"Line in the pull request's new version.\"),\n  body: z.string().min(1).max(5000).describe(\"Markdown explaining the finding and a concrete fix.\"),\n});\nconst reviewCommentsSchema = z\n  .array(reviewCommentSchema)\n  .max(50)\n  .default([])\n  .superRefine((comments, context) => {\n    const seen = new Set<string>();\n    comments.forEach((comment, index) => {\n      if (comment.key === undefined) return;\n      if (seen.has(comment.key)) {\n        context.addIssue({\n          code: \"custom\",\n          message: `duplicate finding key: ${comment.key}`,\n          path: [index, \"key\"],\n        });\n      }\n      seen.add(comment.key);\n    });\n  })\n  .readonly();\n\n/**\n * Publish an independent review of an existing pull request and finish the\n * review task without changing the pull request's factory lifecycle.\n */\nexport function createGitHubPostReviewTool(\n  input: GitHubPostReviewToolOptions,\n): GitHubPostReviewTool {\n  const { stores, ...options } = input;\n  return defineTool({\n    description:\n      \"Record a completed code review and finish your code_review task. Results may be reported through completion callbacks instead of a GitHub review; use request_changes only for blocking findings.\",\n    inputSchema: z.object({\n      taskId: taskIdSchema.describe(\"Your code_review task.\"),\n      changeId: changeIdSchema.describe(\"The pull request change from your starting message.\"),\n      verdict: z.enum([\"approve\", \"request_changes\", \"comment\"]),\n      headSha: z\n        .string()\n        .regex(/^[0-9a-f]{40}$/)\n        .describe(\"Commit returned by fetch_pull_request.\"),\n      summary: z\n        .string()\n        .min(1)\n        .max(5000)\n        .describe(\"Markdown summary of what you reviewed and found.\"),\n      comments: reviewCommentsSchema,\n    }),\n    async execute(\n      { taskId, changeId, verdict, headSha, summary, comments },\n      ctx,\n    ): Promise<GitHubPostReviewResult> {\n      const task = await requireTaskExecution(stores, ctx, taskId);\n      if (task.kind !== \"code_review\") {\n        return {\n          recorded: false as const,\n          code: \"task_kind_mismatch\",\n          reason: `${taskId} is not a code_review task`,\n        };\n      }\n      if (task.state !== \"running\") {\n        return {\n          recorded: false as const,\n          code: \"task_not_running\",\n          reason: `task is ${task.state}, not running`,\n        };\n      }\n\n      const change = await stores.changes.get(changeId);\n      if (change === null) {\n        return {\n          recorded: false as const,\n          code: \"change_not_found\",\n          reason: `change ${changeId} does not exist`,\n        };\n      }\n      if (change.state !== \"verifying\" && change.state !== \"ready\") {\n        return {\n          recorded: false as const,\n          code: \"change_not_reviewable\",\n          reason: `change is ${change.state}, not open for review`,\n        };\n      }\n      const repository = await stores.repositories.get(change.repositoryId);\n      if (repository === null) {\n        return {\n          recorded: false as const,\n          code: \"repository_not_found\",\n          reason: `repository ${change.repositoryId} does not exist`,\n        };\n      }\n      if (\n        task.changeId !== change.id ||\n        task.repositoryIds.length !== 1 ||\n        task.repositoryIds[0] !== repository.id\n      ) {\n        throw new Error(\"Authenticated review Task, Change, and repository must match\");\n      }\n\n      const token = await options.tokenForRepository(repository.slug);\n      await requireTaskExecution(stores, ctx, taskId);\n      const completedComments = comments.map((comment) => {\n        const key = comment.key ?? legacyFindingKey(comment);\n        return {\n          ...comment,\n          key,\n          title: comment.title ?? \"Review finding\",\n          fingerprint: createHash(\"sha256\")\n            .update(`${repository.slug.toLowerCase()}#${change.prNumber}:${key}`)\n            .digest(\"hex\"),\n        };\n      });\n      const completed = {\n        taskId,\n        changeId,\n        repository: repository.slug,\n        pullRequestNumber: change.prNumber,\n        headSha,\n        verdict,\n        summary,\n        comments: completedComments,\n      } satisfies CompletedReview;\n      const publish = options.publishReviews !== false;\n      let review: SubmittedPullRequestReview | undefined;\n      try {\n        if (publish) {\n          review = await submitPullRequestReview({\n            repository: repository.slug,\n            token,\n            fetch: options.fetch,\n            pullRequestNumber: change.prNumber,\n            commitId: headSha,\n            event:\n              verdict === \"approve\"\n                ? \"APPROVE\"\n                : verdict === \"request_changes\"\n                  ? \"REQUEST_CHANGES\"\n                  : \"COMMENT\",\n            body: summary,\n            comments: completedComments,\n          });\n        } else {\n          const head = await readPullRequestHead({\n            repository: repository.slug,\n            token,\n            fetch: options.fetch,\n            pullRequestNumber: change.prNumber,\n          });\n          if (head.sha !== headSha) {\n            throw new StalePullRequestHeadError(headSha, head.sha);\n          }\n        }\n      } catch (error) {\n        if (!(error instanceof StalePullRequestHeadError)) {\n          throw error;\n        }\n        // The reviewer refused a stale head: the change moved on while this\n        // review was in flight, so an identical retry against the same head\n        // can never succeed either. Resolve the task as superseded right\n        // here instead of leaving it running for the stall watchdog to\n        // eventually -- and misleadingly -- report as \"stalled\".\n        const resolved = await stores.tasks\n          .transition(taskId, \"cancelled\", {\n            expectFrom: \"running\",\n            expectAttempt: task.attempt,\n            expectExecution: task.execution,\n            reason: `review superseded by newer commits: ${error.message}`,\n          })\n          .catch(() => null);\n        return {\n          recorded: false as const,\n          code: \"stale_pull_request_head\",\n          reason: error.message,\n          taskState:\n            resolved?.state ??\n            (await stores.tasks.get(taskId).catch(() => null))?.state ??\n            task.state,\n        };\n      }\n      await requireTaskExecution(stores, ctx, taskId);\n      if (review !== undefined) await options.onPublished?.({ ...completed, review });\n      await requireTaskExecution(stores, ctx, taskId);\n      await options.onCompleted?.(completed);\n      await stores.tasks.transition(taskId, \"verifying\", {\n        expectFrom: \"running\",\n        expectAttempt: task.attempt,\n        expectExecution: task.execution,\n        reason: summary,\n      });\n      await stores.tasks.transition(taskId, \"succeeded\", {\n        expectFrom: \"verifying\",\n        expectAttempt: task.attempt,\n        expectExecution: task.execution,\n        output: {\n          changeId,\n          headSha,\n          verdict,\n          summary,\n          findingCount: completedComments.length,\n          published: review !== undefined,\n          ...(review === undefined ? {} : { review }),\n        },\n      });\n      return review === undefined\n        ? {\n            recorded: true,\n            verdict,\n            published: false,\n            taskState: \"succeeded\",\n          }\n        : {\n            recorded: true,\n            verdict,\n            published: true,\n            review,\n            taskState: \"succeeded\",\n          };\n    },\n  });\n}\n\nfunction legacyFindingKey(comment: PullRequestReviewComment): string {\n  const digest = createHash(\"sha256\")\n    .update(`${comment.path}:${comment.line}:${comment.body}`)\n    .digest(\"hex\")\n    .slice(0, 24);\n  return `legacy-${digest}`;\n}\n"],"mappings":"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"}

package/dist/code-review/eve-review-comments.d.mts

@@ -0,0 +1,64 @@
+import { ChangeId } from "../schema/id.mjs";
+import { RepositorySlug } from "../schema/repository.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { GitHubGitTransport } from "../github-transfer.mjs";
+import { GitHubReviewComment } from "../github.mjs";
+import { ToolContext, ToolDefinition } from "eve/tools";
+//#region src/code-review/eve-review-comments.d.ts
+/** Task, Change, and repository capabilities required by the pull-request review-comment tools. */
+type GitHubReviewCommentToolsStores = Pick<FactoryStores, "changes" | "repositories" | "tasks">;
+/** Configures GitHub access and optional credentialed publication for review-comment tools. */
+interface GitHubReviewCommentToolsOptions {
+  stores: GitHubReviewCommentToolsStores;
+  tokenForRepository: (repository: RepositorySlug) => Promise<string>;
+  git?: GitHubGitTransport;
+  fetch?: typeof globalThis.fetch;
+  repoPath?: string;
+}
+/** Change and inline-comment identity accepted by the review-comment reader. */
+interface GitHubReadReviewCommentInput {
+  changeId: ChangeId;
+  commentId: number;
+}
+/** Reply content posted to one inline pull-request review comment. */
+interface GitHubAnswerReviewCommentInput extends GitHubReadReviewCommentInput {
+  body: string;
+}
+/** Medium-confidence suggested edit posted to one inline review comment. */
+interface GitHubSuggestReviewFixInput extends GitHubReadReviewCommentInput {
+  confidence: "medium";
+  replacement: string;
+  summary: string;
+}
+/** High-confidence committed edit published to one reviewed pull request. */
+interface GitHubApplyReviewFixInput extends GitHubReadReviewCommentInput {
+  confidence: "high";
+  summary: string;
+}
+/** Pull-request update and reply returned after publishing a committed review fix. */
+interface GitHubApplyReviewFixResult {
+  readonly updated: true;
+  readonly prNumber: number;
+  readonly prUrl: string;
+  readonly reply: GitHubReviewComment;
+}
+/** Tools for reading, answering, suggesting, and applying GitHub review comments. */
+interface GitHubReviewCommentTools {
+  readonly read_review_comment: ToolDefinition<GitHubReadReviewCommentInput, GitHubReviewComment> & {
+    execute(input: GitHubReadReviewCommentInput, ctx: ToolContext): Promise<GitHubReviewComment>;
+  };
+  readonly answer_review_comment: ToolDefinition<GitHubAnswerReviewCommentInput, GitHubReviewComment> & {
+    execute(input: GitHubAnswerReviewCommentInput, ctx: ToolContext): Promise<GitHubReviewComment>;
+  };
+  readonly suggest_review_fix: ToolDefinition<GitHubSuggestReviewFixInput, GitHubReviewComment> & {
+    execute(input: GitHubSuggestReviewFixInput, ctx: ToolContext): Promise<GitHubReviewComment>;
+  };
+  readonly apply_review_fix: ToolDefinition<GitHubApplyReviewFixInput, GitHubApplyReviewFixResult> & {
+    execute(input: GitHubApplyReviewFixInput, ctx: ToolContext): Promise<GitHubApplyReviewFixResult>;
+  };
+}
+/** Create tools for reading, answering, suggesting, and applying pull-request review fixes. */
+declare function createGitHubReviewCommentTools(input: GitHubReviewCommentToolsOptions): GitHubReviewCommentTools;
+//#endregion
+export { GitHubAnswerReviewCommentInput, GitHubApplyReviewFixInput, GitHubApplyReviewFixResult, GitHubReadReviewCommentInput, GitHubReviewCommentTools, GitHubReviewCommentToolsOptions, GitHubReviewCommentToolsStores, GitHubSuggestReviewFixInput, createGitHubReviewCommentTools };
+//# sourceMappingURL=eve-review-comments.d.mts.map

package/dist/code-review/eve-review-comments.mjs

@@ -0,0 +1,159 @@
+import { changeIdSchema } from "../schema/id.mjs";
+import { taskBindingForSession } from "../eve/task-session.mjs";
+import { requireTaskExecution } from "../eve/task-execution.mjs";
+import { pushGitHubHead } from "../github-transfer.mjs";
+import { answerReviewComment, readPullRequestHead, readReviewComment } from "../github.mjs";
+import { z } from "zod";
+import { defineTool } from "eve/tools";
+//#region src/code-review/eve-review-comments.ts
+async function authorizeReviewChange(stores, ctx, changeId) {
+	const taskId = taskBindingForSession(ctx.session?.auth?.initiator).taskId;
+	const task = await requireTaskExecution(stores, ctx, taskId);
+	const change = await stores.changes.get(changeId);
+	if (change === null) throw new Error(`change ${changeId} does not exist`);
+	if (change.state !== "verifying" && change.state !== "ready") throw new Error(`change is ${change.state}, not open for review`);
+	const repository = await stores.repositories.get(change.repositoryId);
+	if (repository === null) throw new Error(`repository ${change.repositoryId} does not exist`);
+	if (task.changeId !== change.id || task.repositoryIds.length !== 1 || task.repositoryIds[0] !== repository.id) throw new Error("Authenticated Task, Change, and repository must match");
+	return {
+		task,
+		change,
+		repository
+	};
+}
+async function requireCurrentExecution(stores, ctx, task) {
+	await requireTaskExecution(stores, ctx, task.id);
+}
+/** Create tools for reading, answering, suggesting, and applying pull-request review fixes. */
+function createGitHubReviewCommentTools(input) {
+	const { stores, ...options } = input;
+	const repoPath = options.repoPath ?? "repo";
+	const commentInputSchema = z.object({
+		changeId: changeIdSchema.describe("The change under review, from your starting message."),
+		commentId: z.number().int().positive().describe("The GitHub review comment id.")
+	});
+	return {
+		read_review_comment: defineTool({
+			description: "Read an inline review comment on a change under verification or ready for human review. By default this refuses to return comments from people without write access to the repository.",
+			inputSchema: commentInputSchema,
+			async execute({ changeId, commentId }, ctx) {
+				const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);
+				const token = await options.tokenForRepository(repository.slug);
+				await requireCurrentExecution(stores, ctx, task);
+				const comment = await readReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId
+				});
+				await requireCurrentExecution(stores, ctx, task);
+				return comment;
+			}
+		}),
+		answer_review_comment: defineTool({
+			description: "Reply to an inline review comment on a change under verification or ready for human review. Use for findings and low-confidence responses, not for a concrete medium- or high-confidence fix.",
+			inputSchema: commentInputSchema.extend({ body: z.string().min(1).max(5e3).describe("The Markdown reply to post.") }),
+			async execute({ changeId, commentId, body }, ctx) {
+				const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);
+				const token = await options.tokenForRepository(repository.slug);
+				await requireCurrentExecution(stores, ctx, task);
+				const reply = await answerReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId,
+					body
+				});
+				await requireCurrentExecution(stores, ctx, task);
+				return reply;
+			}
+		}),
+		suggest_review_fix: defineTool({
+			description: "Post a concrete, apply-able GitHub suggested change for a medium-confidence fix. The replacement must cover exactly the lines attached to the inline review comment.",
+			inputSchema: commentInputSchema.extend({
+				confidence: z.literal("medium"),
+				replacement: z.string().min(1).max(5e3).describe("Exact replacement text for the commented lines."),
+				summary: z.string().min(1).max(1e3).describe("A brief explanation of the suggested fix.")
+			}),
+			async execute({ changeId, commentId, replacement, summary }, ctx) {
+				const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);
+				const token = await options.tokenForRepository(repository.slug);
+				await requireCurrentExecution(stores, ctx, task);
+				const reply = await answerReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId,
+					body: `${summary}\n\n\`\`\`suggestion\n${replacement}\n\`\`\``
+				});
+				await requireCurrentExecution(stores, ctx, task);
+				return reply;
+			}
+		}),
+		apply_review_fix: defineTool({
+			description: "Publish a tested, committed high-confidence fix to the existing same-repository pull request branch. Fails if the checkout is dirty, the PR changed, or the PR comes from a fork.",
+			inputSchema: commentInputSchema.extend({
+				confidence: z.literal("high"),
+				summary: z.string().min(1).max(1e3).describe("What was fixed and verified.")
+			}),
+			async execute({ changeId, commentId, summary }, ctx) {
+				const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);
+				if (options.git === void 0) throw new Error("applying review fixes is not configured");
+				const token = await options.tokenForRepository(repository.slug);
+				await requireCurrentExecution(stores, ctx, task);
+				await readReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId
+				});
+				await requireCurrentExecution(stores, ctx, task);
+				const head = await readPullRequestHead({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber
+				});
+				if (head.repository !== repository.slug.toLowerCase()) throw new Error("cannot apply a fix to a pull request from a fork");
+				const sandbox = await ctx.getSandbox();
+				const git = `git -C ${repoPath}`;
+				if ((await sandbox.run({ command: `${git} status --porcelain` })).stdout.trim() !== "") throw new Error("commit the review fix before publishing");
+				if ((await sandbox.run({ command: `${git} merge-base --is-ancestor ${head.sha} HEAD` })).exitCode !== 0) throw new Error("pull request changed after it was fetched; fetch it again before applying the fix");
+				if ((await sandbox.run({ command: `${git} rev-parse HEAD` })).stdout.trim() === head.sha) throw new Error("no committed review fix to publish");
+				await requireCurrentExecution(stores, ctx, task);
+				await pushGitHubHead({
+					sandbox,
+					transport: options.git,
+					repository: repository.slug,
+					branch: head.branch,
+					expectedHead: head.sha,
+					repositoryPath: repoPath
+				});
+				await requireCurrentExecution(stores, ctx, task);
+				const reply = await answerReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId,
+					body: summary
+				});
+				await requireCurrentExecution(stores, ctx, task);
+				return {
+					updated: true,
+					prNumber: change.prNumber,
+					prUrl: change.prUrl,
+					reply
+				};
+			}
+		})
+	};
+}
+//#endregion
+export { createGitHubReviewCommentTools };
+
+//# sourceMappingURL=eve-review-comments.mjs.map

package/dist/code-review/eve-review-comments.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-review-comments.mjs","names":[],"sources":["../../src/code-review/eve-review-comments.ts"],"sourcesContent":["import { pushGitHubHead, type GitHubGitTransport } from \"../github-transfer\";\nimport {\n  answerReviewComment,\n  readPullRequestHead,\n  readReviewComment,\n  type GitHubReviewComment,\n} from \"../github\";\nimport { requireTaskExecution } from \"../eve/task-execution\";\nimport { taskBindingForSession } from \"../eve/task-session\";\nimport { changeIdSchema, type ChangeId } from \"../schema/id\";\nimport type { RepositorySlug } from \"../schema/repository\";\nimport type { Change } from \"../schema/change\";\nimport type { Repository } from \"../schema/repository\";\nimport type { Task } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\nimport { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\n\n/** Task, Change, and repository capabilities required by the pull-request review-comment tools. */\nexport type GitHubReviewCommentToolsStores = Pick<\n  FactoryStores,\n  \"changes\" | \"repositories\" | \"tasks\"\n>;\n\n/** Configures GitHub access and optional credentialed publication for review-comment tools. */\nexport interface GitHubReviewCommentToolsOptions {\n  stores: GitHubReviewCommentToolsStores;\n  tokenForRepository: (repository: RepositorySlug) => Promise<string>;\n  git?: GitHubGitTransport;\n  fetch?: typeof globalThis.fetch;\n  repoPath?: string;\n}\n\n/** Change and inline-comment identity accepted by the review-comment reader. */\nexport interface GitHubReadReviewCommentInput {\n  changeId: ChangeId;\n  commentId: number;\n}\n\n/** Reply content posted to one inline pull-request review comment. */\nexport interface GitHubAnswerReviewCommentInput extends GitHubReadReviewCommentInput {\n  body: string;\n}\n\n/** Medium-confidence suggested edit posted to one inline review comment. */\nexport interface GitHubSuggestReviewFixInput extends GitHubReadReviewCommentInput {\n  confidence: \"medium\";\n  replacement: string;\n  summary: string;\n}\n\n/** High-confidence committed edit published to one reviewed pull request. */\nexport interface GitHubApplyReviewFixInput extends GitHubReadReviewCommentInput {\n  confidence: \"high\";\n  summary: string;\n}\n\n/** Pull-request update and reply returned after publishing a committed review fix. */\nexport interface GitHubApplyReviewFixResult {\n  readonly updated: true;\n  readonly prNumber: number;\n  readonly prUrl: string;\n  readonly reply: GitHubReviewComment;\n}\n\n/** Tools for reading, answering, suggesting, and applying GitHub review comments. */\nexport interface GitHubReviewCommentTools {\n  readonly read_review_comment: ToolDefinition<\n    GitHubReadReviewCommentInput,\n    GitHubReviewComment\n  > & {\n    execute(input: GitHubReadReviewCommentInput, ctx: ToolContext): Promise<GitHubReviewComment>;\n  };\n  readonly answer_review_comment: ToolDefinition<\n    GitHubAnswerReviewCommentInput,\n    GitHubReviewComment\n  > & {\n    execute(input: GitHubAnswerReviewCommentInput, ctx: ToolContext): Promise<GitHubReviewComment>;\n  };\n  readonly suggest_review_fix: ToolDefinition<GitHubSuggestReviewFixInput, GitHubReviewComment> & {\n    execute(input: GitHubSuggestReviewFixInput, ctx: ToolContext): Promise<GitHubReviewComment>;\n  };\n  readonly apply_review_fix: ToolDefinition<\n    GitHubApplyReviewFixInput,\n    GitHubApplyReviewFixResult\n  > & {\n    execute(\n      input: GitHubApplyReviewFixInput,\n      ctx: ToolContext,\n    ): Promise<GitHubApplyReviewFixResult>;\n  };\n}\n\nasync function authorizeReviewChange(\n  stores: GitHubReviewCommentToolsStores,\n  ctx: ToolContext,\n  changeId: ChangeId,\n): Promise<{ task: Task; change: Change; repository: Repository }> {\n  const taskId = taskBindingForSession(ctx.session?.auth?.initiator).taskId;\n  const task = await requireTaskExecution(stores, ctx, taskId);\n  const change = await stores.changes.get(changeId);\n  if (change === null) throw new Error(`change ${changeId} does not exist`);\n  if (change.state !== \"verifying\" && change.state !== \"ready\") {\n    throw new Error(`change is ${change.state}, not open for review`);\n  }\n  const repository = await stores.repositories.get(change.repositoryId);\n  if (repository === null) throw new Error(`repository ${change.repositoryId} does not exist`);\n  if (\n    task.changeId !== change.id ||\n    task.repositoryIds.length !== 1 ||\n    task.repositoryIds[0] !== repository.id\n  ) {\n    throw new Error(\"Authenticated Task, Change, and repository must match\");\n  }\n  return { task, change, repository };\n}\n\nasync function requireCurrentExecution(\n  stores: GitHubReviewCommentToolsStores,\n  ctx: ToolContext,\n  task: Task,\n): Promise<void> {\n  await requireTaskExecution(stores, ctx, task.id);\n}\n\n/** Create tools for reading, answering, suggesting, and applying pull-request review fixes. */\nexport function createGitHubReviewCommentTools(\n  input: GitHubReviewCommentToolsOptions,\n): GitHubReviewCommentTools {\n  const { stores, ...options } = input;\n  const repoPath = options.repoPath ?? \"repo\";\n  const commentInputSchema = z.object({\n    changeId: changeIdSchema.describe(\"The change under review, from your starting message.\"),\n    commentId: z.number().int().positive().describe(\"The GitHub review comment id.\"),\n  });\n\n  return {\n    read_review_comment: defineTool({\n      description:\n        \"Read an inline review comment on a change under verification or ready for human review. By default this refuses to return comments from people without write access to the repository.\",\n      inputSchema: commentInputSchema,\n      async execute({ changeId, commentId }, ctx): Promise<GitHubReviewComment> {\n        const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);\n        const token = await options.tokenForRepository(repository.slug);\n        await requireCurrentExecution(stores, ctx, task);\n        const comment = await readReviewComment({\n          repository: repository.slug,\n          token,\n          fetch: options.fetch,\n          pullRequestNumber: change.prNumber,\n          commentId,\n        });\n        await requireCurrentExecution(stores, ctx, task);\n        return comment;\n      },\n    }),\n    answer_review_comment: defineTool({\n      description:\n        \"Reply to an inline review comment on a change under verification or ready for human review. Use for findings and low-confidence responses, not for a concrete medium- or high-confidence fix.\",\n      inputSchema: commentInputSchema.extend({\n        body: z.string().min(1).max(5000).describe(\"The Markdown reply to post.\"),\n      }),\n      async execute({ changeId, commentId, body }, ctx): Promise<GitHubReviewComment> {\n        const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);\n        const token = await options.tokenForRepository(repository.slug);\n        await requireCurrentExecution(stores, ctx, task);\n        const reply = await answerReviewComment({\n          repository: repository.slug,\n          token,\n          fetch: options.fetch,\n          pullRequestNumber: change.prNumber,\n          commentId,\n          body,\n        });\n        await requireCurrentExecution(stores, ctx, task);\n        return reply;\n      },\n    }),\n    suggest_review_fix: defineTool({\n      description:\n        \"Post a concrete, apply-able GitHub suggested change for a medium-confidence fix. The replacement must cover exactly the lines attached to the inline review comment.\",\n      inputSchema: commentInputSchema.extend({\n        confidence: z.literal(\"medium\"),\n        replacement: z\n          .string()\n          .min(1)\n          .max(5000)\n          .describe(\"Exact replacement text for the commented lines.\"),\n        summary: z.string().min(1).max(1000).describe(\"A brief explanation of the suggested fix.\"),\n      }),\n      async execute(\n        { changeId, commentId, replacement, summary },\n        ctx,\n      ): Promise<GitHubReviewComment> {\n        const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);\n        const token = await options.tokenForRepository(repository.slug);\n        await requireCurrentExecution(stores, ctx, task);\n        const reply = await answerReviewComment({\n          repository: repository.slug,\n          token,\n          fetch: options.fetch,\n          pullRequestNumber: change.prNumber,\n          commentId,\n          body: `${summary}\\n\\n\\`\\`\\`suggestion\\n${replacement}\\n\\`\\`\\``,\n        });\n        await requireCurrentExecution(stores, ctx, task);\n        return reply;\n      },\n    }),\n    apply_review_fix: defineTool({\n      description:\n        \"Publish a tested, committed high-confidence fix to the existing same-repository pull request branch. Fails if the checkout is dirty, the PR changed, or the PR comes from a fork.\",\n      inputSchema: commentInputSchema.extend({\n        confidence: z.literal(\"high\"),\n        summary: z.string().min(1).max(1000).describe(\"What was fixed and verified.\"),\n      }),\n      async execute({ changeId, commentId, summary }, ctx): Promise<GitHubApplyReviewFixResult> {\n        const { task, change, repository } = await authorizeReviewChange(stores, ctx, changeId);\n        if (options.git === undefined) {\n          throw new Error(\"applying review fixes is not configured\");\n        }\n        const token = await options.tokenForRepository(repository.slug);\n        await requireCurrentExecution(stores, ctx, task);\n        await readReviewComment({\n          repository: repository.slug,\n          token,\n          fetch: options.fetch,\n          pullRequestNumber: change.prNumber,\n          commentId,\n        });\n        await requireCurrentExecution(stores, ctx, task);\n        const head = await readPullRequestHead({\n          repository: repository.slug,\n          token,\n          fetch: options.fetch,\n          pullRequestNumber: change.prNumber,\n        });\n        if (head.repository !== repository.slug.toLowerCase()) {\n          throw new Error(\"cannot apply a fix to a pull request from a fork\");\n        }\n        const sandbox = await ctx.getSandbox();\n        const git = `git -C ${repoPath}`;\n        const clean = await sandbox.run({ command: `${git} status --porcelain` });\n        if (clean.stdout.trim() !== \"\") throw new Error(\"commit the review fix before publishing\");\n        const ancestor = await sandbox.run({\n          command: `${git} merge-base --is-ancestor ${head.sha} HEAD`,\n        });\n        if (ancestor.exitCode !== 0) {\n          throw new Error(\n            \"pull request changed after it was fetched; fetch it again before applying the fix\",\n          );\n        }\n        const localHead = await sandbox.run({ command: `${git} rev-parse HEAD` });\n        if (localHead.stdout.trim() === head.sha)\n          throw new Error(\"no committed review fix to publish\");\n        await requireCurrentExecution(stores, ctx, task);\n        await pushGitHubHead({\n          sandbox,\n          transport: options.git,\n          repository: repository.slug,\n          branch: head.branch,\n          expectedHead: head.sha,\n          repositoryPath: repoPath,\n        });\n        await requireCurrentExecution(stores, ctx, task);\n        const reply = await answerReviewComment({\n          repository: repository.slug,\n          token,\n          fetch: options.fetch,\n          pullRequestNumber: change.prNumber,\n          commentId,\n          body: summary,\n        });\n        await requireCurrentExecution(stores, ctx, task);\n        return { updated: true as const, prNumber: change.prNumber, prUrl: change.prUrl, reply };\n      },\n    }),\n  };\n}\n"],"mappings":"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"}

package/dist/code-review/github-contracts.d.mts

@@ -0,0 +1,10 @@
+import { CompletedReview } from "./contracts.mjs";
+import { SubmittedPullRequestReview } from "../github.mjs";
+//#region src/code-review/github-contracts.d.ts
+/** A completed review together with the GitHub review created from it. */
+interface PublishedGitHubReview extends CompletedReview {
+  review: SubmittedPullRequestReview;
+}
+//#endregion
+export { PublishedGitHubReview };
+//# sourceMappingURL=github-contracts.d.mts.map

package/dist/code-review/github-reporter.d.mts

@@ -0,0 +1,44 @@
+import { TaskId } from "../schema/id.mjs";
+import { RepositorySlug } from "../schema/repository.mjs";
+import { Task } from "../schema/task.mjs";
+import { DateClock } from "../schema/common.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { CompletedReview } from "./contracts.mjs";
+import { StartReviewCheckInput } from "./preparation.mjs";
+//#region src/code-review/github-reporter.d.ts
+/** Storage, credentials, and presentation settings for GitHub review reporting. */
+interface GitHubReviewReporterOptions {
+  stores: Pick<FactoryStores, "taskEffects" | "changes" | "repositories">;
+  tokenForRepository(repositorySlug: RepositorySlug): Promise<string>;
+  fetch?: typeof globalThis.fetch;
+  checkName?: string;
+  summaryHeading?: string;
+  now?: DateClock;
+}
+/** Check-run and pull-request summary lifecycle for supplied code reviews. */
+interface GitHubReviewReporter {
+  startReviewCheck(input: StartReviewCheckInput): Promise<void>;
+  completeReviewCheck(review: CompletedReview): Promise<void>;
+  reconcileReviewChecks(input: ReconcileReviewChecksInput): Promise<ReconcileReviewChecksResult>;
+}
+/** Bounded rotating-page controls for abandoned review-check recovery. */
+interface ReconcileReviewChecksOptions {
+  batchSize?: number;
+  /** Stable page selector; defaults to the current five-minute recovery window. */
+  candidatePage?: number;
+  now?: DateClock;
+}
+/** Review Tasks and bounded recovery controls for one reconciliation pass. */
+interface ReconcileReviewChecksInput extends ReconcileReviewChecksOptions {
+  tasks: readonly Task[];
+}
+/** Review Tasks whose check effects were concluded or durably resolved in one pass. */
+interface ReconcileReviewChecksResult {
+  concluded: readonly TaskId[];
+  stamped: readonly TaskId[];
+}
+/** Create the supplied GitHub check-run and pull-request summary reporter for code reviews. */
+declare function createGitHubReviewReporter(options: GitHubReviewReporterOptions): GitHubReviewReporter;
+//#endregion
+export { GitHubReviewReporter, GitHubReviewReporterOptions, ReconcileReviewChecksInput, ReconcileReviewChecksOptions, ReconcileReviewChecksResult, createGitHubReviewReporter };
+//# sourceMappingURL=github-reporter.d.mts.map