@vercel/factory 0.0.3 → 0.0.5

package/dist/eve/index.mjs

@@ -0,0 +1,853 @@
+import { i as repositoryIdSchema, o as signalIdSchema, p as vocabularySchema, s as taskIdSchema, t as changeIdSchema } from "../id-DwCihQr4.mjs";
+import { S as findingFingerprint, b as requiresApproval, g as dispatchTask, p as levelSchema, s as taskQuestionSchema, u as changeEvidenceSchema, w as findingSchema, y as defaultApprovalPolicy } from "../task-Cj7Ei9Nh.mjs";
+import { answerReviewComment, readPullRequestHead, readReviewComment } from "../github.mjs";
+import { z } from "zod";
+import { defineHook } from "eve/hooks";
+import { defineTool } from "eve/tools";
+//#region src/eve/conflict.ts
+const gitShaSchema = z.string().regex(/^[0-9a-f]{40}$/);
+const gitBranchSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/).refine((value) => !value.includes(".."));
+const mergeConflictPayloadSchema = z.strictObject({
+	repository: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
+	prNumber: z.number().int().positive(),
+	prUrl: z.url(),
+	headBranch: gitBranchSchema.refine((value) => value.startsWith("factory/")),
+	headSha: gitShaSchema,
+	baseBranch: gitBranchSchema,
+	baseSha: gitShaSchema
+});
+function mergeConflictTools(stores, options) {
+	const repoPath = options.repoPath ?? "repo";
+	async function context(taskId) {
+		const task = await stores.tasks.get(taskId);
+		if (task === null) throw new Error(`task ${taskId} does not exist`);
+		if (task.kind !== "merge_conflict") throw new Error(`task ${taskId} is ${task.kind}, not merge_conflict`);
+		if (task.state !== "running") throw new Error(`task ${taskId} is ${task.state}, not running`);
+		if (task.origin.signalId === void 0) throw new Error(`task ${taskId} has no conflict signal`);
+		const signal = await stores.signals.get(task.origin.signalId);
+		if (signal === null || signal.source !== "github_merge_conflict") throw new Error(`task ${taskId} has no GitHub merge conflict signal`);
+		return {
+			task,
+			conflict: mergeConflictPayloadSchema.parse(signal.payload)
+		};
+	}
+	return {
+		fetch_merge_conflict: defineTool({
+			description: "Fetch the conflicted factory pull request and its current base, check out the PR head, and start the merge. Resolve every file returned in conflictedFiles, then test and commit the merge.",
+			inputSchema: z.object({ taskId: taskIdSchema }),
+			async execute({ taskId }, ctx) {
+				const { conflict } = await context(taskId);
+				const sandbox = await ctx.getSandbox();
+				const git = `git -C ${repoPath}`;
+				const headRef = `refs/remotes/origin/conflict-pr-${conflict.prNumber}`;
+				const baseRef = `refs/remotes/origin/conflict-base-${conflict.prNumber}`;
+				const fetch = await options.withCredential(sandbox, conflict.repository, `${git} fetch --depth 100 origin +refs/pull/${conflict.prNumber}/head:${headRef} +refs/heads/${conflict.baseBranch}:${baseRef}`);
+				if (typeof fetch.exitCode === "number" && fetch.exitCode !== 0) throw new Error(`could not fetch pull request: ${(fetch.stderr ?? "").trim()}`);
+				const [headSha, baseSha] = (await sandbox.run({ command: `${git} rev-parse ${headRef} && ${git} rev-parse ${baseRef}` })).stdout.trim().split("\n");
+				if (headSha !== conflict.headSha || baseSha !== conflict.baseSha) throw new Error("pull request or base changed while conflict resolution was starting; retry from a new task");
+				await sandbox.run({ command: `${git} checkout -B conflict-pr ${headRef}` });
+				const merge = await sandbox.run({ command: `${git} merge --no-commit --no-ff ${baseRef}` });
+				const conflictedFiles = (await sandbox.run({ command: `${git} diff --name-only --diff-filter=U` })).stdout.trim().split("\n").filter(Boolean);
+				if (conflictedFiles.length === 0) throw new Error(typeof merge.exitCode === "number" && merge.exitCode !== 0 ? `merge failed without file conflicts: ${(merge.stderr ?? "").trim()}` : "pull request no longer has merge conflicts");
+				return {
+					...conflict,
+					conflictedFiles
+				};
+			}
+		}),
+		publish_merge_resolution: defineTool({
+			description: "Publish a tested, committed conflict resolution to the existing pull request branch. Fails if the remote branch changed since this task started.",
+			inputSchema: z.object({
+				taskId: taskIdSchema,
+				summary: z.string().min(1).max(2e3)
+			}),
+			async execute({ taskId, summary }, ctx) {
+				const { conflict } = await context(taskId);
+				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 conflict resolution before publishing");
+				if ((await sandbox.run({ command: `${git} diff --name-only --diff-filter=U` })).stdout.trim() !== "") throw new Error("merge conflicts remain unresolved");
+				const push = await options.withCredential(sandbox, conflict.repository, `${git} push --force-with-lease=refs/heads/${conflict.headBranch}:${conflict.headSha} origin HEAD:refs/heads/${conflict.headBranch}`);
+				if (typeof push.exitCode === "number" && push.exitCode !== 0) throw new Error(`could not update pull request branch: ${(push.stderr ?? "").trim()}`);
+				await stores.tasks.transition(taskId, "verifying", { reason: summary });
+				await stores.tasks.transition(taskId, "succeeded", { reason: summary });
+				return {
+					updated: true,
+					prNumber: conflict.prNumber,
+					prUrl: conflict.prUrl
+				};
+			}
+		})
+	};
+}
+//#endregion
+//#region src/eve/finding.ts
+function isLostRaceError(error) {
+	return error instanceof Error && (error.name === "VersionConflictError" || error.name === "InvalidTransitionError");
+}
+/**
+* Turn one finding into a signal and a fix task. The fingerprint is the
+* signal's delivery id, so the same problem reported twice is a no-op. The
+* signal is accepted on the reporter's own verification (a human gate follows
+* when the approval policy says so), and the task carries the approval
+* decision from the moment it exists. Shared by record_finding and scanner
+* tools that record on the agent's behalf.
+*/
+async function recordFinding(stores, repositoryId, finding, options = {}) {
+	const source = options.source ?? "security_scan";
+	const policy = options.approval ?? defaultApprovalPolicy;
+	if (await stores.repositories.get(repositoryId) === null) return {
+		recorded: false,
+		reason: `repository ${repositoryId} does not exist`
+	};
+	const fingerprint = findingFingerprint(repositoryId, finding);
+	const signal = await stores.signals.create({
+		repositoryId,
+		source,
+		deliveryId: fingerprint,
+		replyTo: {
+			channel: "finding",
+			address: fingerprint
+		},
+		payload: finding
+	});
+	if (signal.outcome !== "pending") return {
+		recorded: false,
+		duplicate: true,
+		signalId: signal.id,
+		reason: `already recorded as ${signal.id}`
+	};
+	try {
+		await stores.signals.decide(signal.id, "accepted", {
+			detail: finding.priority,
+			reason: `${finding.tool ?? "scanner"} reported it, ${finding.verification.level} by ${finding.verification.method}`
+		});
+	} catch (error) {
+		if (isLostRaceError(error)) {
+			const current = await stores.signals.get(signal.id);
+			if (current !== null && current.outcome !== "pending") return {
+				recorded: false,
+				duplicate: true,
+				signalId: signal.id,
+				reason: `already recorded as ${signal.id}`
+			};
+		}
+		throw error;
+	}
+	const approval = requiresApproval(policy, {
+		source,
+		kind: "code_change",
+		priority: finding.priority
+	});
+	const task = await stores.tasks.create({
+		repositoryIds: [repositoryId],
+		kind: "code_change",
+		origin: { signalId: signal.id },
+		replyTo: signal.replyTo,
+		...approval ? { approval: "required" } : {}
+	});
+	return {
+		recorded: true,
+		signalId: signal.id,
+		taskId: task.id,
+		approval: approval ? "required" : "not_required"
+	};
+}
+/**
+* The scanner's outcome tool: turns one finding into a signal and a fix task
+* in a single deterministic step. The finding's fingerprint is the signal's
+* delivery id, so reporting the same problem twice is a no-op. The signal is
+* accepted on the reporter's own verification (a human gate follows when the
+* approval policy says so), and the task carries the approval decision from
+* the moment it exists.
+*/
+function recordFindingTool(stores, options = {}) {
+	return defineTool({
+		description: "Record one problem you found in the repository. Creates a fix task (which may wait for human approval) unless the same finding was already recorded. Report every finding separately; never batch.",
+		inputSchema: z.object({
+			repositoryId: repositoryIdSchema,
+			finding: findingSchema
+		}),
+		execute({ repositoryId, finding }) {
+			return recordFinding(stores, repositoryId, finding, options);
+		}
+	});
+}
+//#endregion
+//#region src/eve/deepsec.ts
+/** deepsec's exported finding shape, as far as we depend on it. */
+const deepsecFindingSchema = z.looseObject({
+	title: z.string().min(1),
+	description: z.string().min(1),
+	severity: z.string().min(1),
+	metadata: z.looseObject({
+		filePath: z.string().min(1).optional(),
+		lineNumbers: z.array(z.number().int().min(1)).optional(),
+		vulnSlug: z.string().min(1).optional(),
+		confidence: z.string().optional(),
+		runId: z.string().optional()
+	}).optional()
+});
+const deepsecExportSchema = z.union([z.array(deepsecFindingSchema), z.looseObject({ findings: z.array(deepsecFindingSchema) }).transform((value) => value.findings)]);
+const priorityBySeverity = {
+	CRITICAL: "P0",
+	HIGH: "P1",
+	MEDIUM: "P2",
+	HIGH_BUG: "P2",
+	BUG: "P3",
+	LOW: "P3"
+};
+/** Convert one deepsec finding into the factory's Finding. Pure; exported for tests. */
+function findingFromDeepsec(raw) {
+	const meta = raw.metadata ?? {};
+	const confidence = (meta.confidence ?? "").toLowerCase();
+	const line = meta.lineNumbers?.[0];
+	const endLine = meta.lineNumbers === void 0 ? void 0 : Math.max(...meta.lineNumbers);
+	return findingSchema.parse({
+		title: raw.title.replace(/^\[[A-Z_]+\]\s*/u, "").slice(0, 200),
+		body: raw.description.slice(0, 8e3),
+		...meta.filePath === void 0 ? {} : { path: meta.filePath.slice(0, 500) },
+		...line === void 0 ? {} : { line },
+		...endLine === void 0 || endLine === line ? {} : { endLine },
+		priority: priorityBySeverity[raw.severity.toUpperCase()] ?? "P3",
+		category: "security",
+		verification: {
+			level: confidence === "high" ? "supported" : "unverified",
+			method: "static_analysis",
+			summary: `deepsec ${meta.vulnSlug ?? "finding"} with ${confidence || "unknown"} confidence${meta.runId === void 0 ? "" : ` (run ${meta.runId})`}.`,
+			limitations: "AI-assisted static analysis of the checkout; not reproduced at runtime."
+		},
+		tool: "deepsec",
+		...meta.vulnSlug === void 0 ? {} : { ruleId: meta.vulnSlug }
+	});
+}
+const findingsPath = "/tmp/deepsec-findings.json";
+/** Parse "N file(s) with candidates" out of deepsec scan output; null when absent. */
+function candidateCount(output) {
+	const match = /(\d+)\s+file\(s\) with candidates/u.exec(output);
+	return match?.[1] === void 0 ? null : Number(match[1]);
+}
+/** The last few meaningful lines of a command's output, ANSI stripped, for a receipt. */
+function tail(output, lines = 4) {
+	return output.replaceAll(/\u001b\[[0-9;]*m/gu, "").split("\n").map((line) => line.trim()).filter((line) => line !== "").slice(-lines).join(" | ").slice(0, 600);
+}
+/**
+* Runs deepsec (vercel-labs/deepsec) against the sandbox checkout and records
+* what it finds through the same path as record_finding, so every deepsec
+* finding becomes a fix task subject to the approval policy. Trusted code
+* owns the command sequence and the credential; the agent chooses when to
+* scan and reports the outcome.
+*/
+function deepsecScanTool(stores, options) {
+	const repoPath = options.repoPath ?? "repo";
+	const workspace = options.workspacePath ?? "deepsec";
+	const version = options.version ?? "2.3.8";
+	const agent = options.agent ?? "claude";
+	const model = options.model ?? "claude-sonnet-4-6";
+	const thinkingLevel = options.thinkingLevel ?? "medium";
+	const concurrency = options.concurrency ?? 4;
+	const prefix = options.commandPrefix === void 0 ? [] : [options.commandPrefix];
+	const filesPerRun = options.filesPerRun ?? 40;
+	return defineTool({
+		description: "Run deepsec, the AI-powered vulnerability scanner, over the repository checkout and record every finding it reports as a fix task. Takes minutes. Call once per scan; then summarize the result.",
+		inputSchema: z.object({
+			repositoryId: repositoryIdSchema,
+			limit: z.number().int().min(1).max(500).optional().describe("Candidate files to investigate this run (default 40; deepsec resumes where it left off next time).")
+		}),
+		async execute({ repositoryId, limit }, ctx) {
+			const repository = await stores.repositories.get(repositoryId);
+			if (repository === null) return {
+				scanned: false,
+				reason: `repository ${repositoryId} does not exist`
+			};
+			const sandbox = await ctx.getSandbox();
+			const projectId = repository.slug.replace(/[^a-z0-9]+/gu, "-");
+			const startedAt = Date.now();
+			const phase = async (state, reason) => {
+				await stores.receipts.append({
+					repositoryIds: [repositoryId],
+					kind: "deepsec",
+					state,
+					phase: "security_scan",
+					reason: `${reason} (${Math.round((Date.now() - startedAt) / 1e3)}s in)`
+				});
+			};
+			await phase("started", `deepsec ${version} on ${repository.slug}, ${agent}/${model}`);
+			const prepare = await sandbox.run({ command: [
+				...prefix,
+				"set -e",
+				`if [ ! -f ${workspace}/deepsec.config.ts ]; then`,
+				`  npx -y deepsec@${version} init ./${workspace} ./${repoPath} --id ${projectId} --scaffold-only --headless --yes --skip-install`,
+				`  (cd ${workspace} && npm install --no-audit --no-fund --loglevel=error)`,
+				"fi",
+				`cd ${workspace}`,
+				`./node_modules/.bin/deepsec scan --project-id ${projectId}`
+			].join("\n") });
+			if (typeof prepare.exitCode === "number" && prepare.exitCode !== 0) {
+				const detail = (prepare.stderr ?? prepare.stdout).trim().slice(-1500);
+				await phase("failed", `scan phase failed: ${detail.slice(-300)}`);
+				return {
+					scanned: false,
+					reason: `deepsec scan failed: ${detail}`
+				};
+			}
+			const candidates = candidateCount(prepare.stdout);
+			await phase("scanned", `${candidates === null ? "scan output" : `${candidates} files with candidates`}: ${tail(`${prepare.stdout}\n${prepare.stderr ?? ""}`)}`);
+			const investigate = await options.withModelCredential(sandbox, [
+				...prefix,
+				"set -e",
+				`cd ${workspace}`,
+				`./node_modules/.bin/deepsec process --project-id ${projectId} --agent ${agent} --model ${model} --thinking-level ${thinkingLevel} --concurrency ${concurrency} --limit ${limit ?? filesPerRun}`,
+				`./node_modules/.bin/deepsec export --project-id ${projectId} --format json --out ${findingsPath}`
+			].join("\n"));
+			if (typeof investigate.exitCode === "number" && investigate.exitCode !== 0) {
+				const detail = (investigate.stderr ?? investigate.stdout).trim().slice(-1500);
+				await phase("failed", `process phase failed: ${detail.slice(-300)}`);
+				return {
+					scanned: false,
+					reason: `deepsec process failed: ${detail}`
+				};
+			}
+			const exported = await sandbox.run({ command: `cat ${findingsPath}` });
+			let parsed;
+			try {
+				parsed = JSON.parse(exported.stdout);
+			} catch {
+				return {
+					scanned: false,
+					reason: "deepsec export was not valid JSON"
+				};
+			}
+			const raw = deepsecExportSchema.safeParse(parsed);
+			if (!raw.success) return {
+				scanned: false,
+				reason: `deepsec export had an unexpected shape: ${raw.error.issues[0]?.message ?? "unknown"}`
+			};
+			const results = [];
+			for (const entry of raw.data) {
+				const finding = findingFromDeepsec(entry);
+				results.push({
+					finding,
+					result: await recordFinding(stores, repositoryId, finding, options)
+				});
+			}
+			const recorded = results.filter(({ result }) => result.recorded);
+			await phase("completed", `${results.length} findings, ${recorded.length} new. process output: ${tail(`${investigate.stdout}\n${investigate.stderr ?? ""}`, 6)}`);
+			return {
+				scanned: true,
+				tool: "deepsec",
+				found: results.length,
+				recorded: recorded.length,
+				duplicates: results.length - recorded.length,
+				awaitingApproval: recorded.filter(({ result }) => result.recorded && result.approval === "required").length,
+				findings: results.map(({ finding, result }) => ({
+					title: finding.title,
+					priority: finding.priority,
+					path: finding.path,
+					line: finding.line,
+					...result.recorded ? {
+						taskId: result.taskId,
+						approval: result.approval
+					} : { duplicate: true }
+				}))
+			};
+		}
+	});
+}
+//#endregion
+//#region src/eve/fetch.ts
+/**
+* The verifier's way in to the change under review. The sandbox has no
+* GitHub credential while the agent runs, so trusted code does the one fetch
+* the agent cannot: the pull request number and repository come from the
+* change record, never from the agent, and the credential is gone again
+* before control returns. Mirrors how publication reads commits out of the
+* sandbox instead of letting the agent push.
+*/
+function fetchPullRequestTool(stores, options) {
+	const repoPath = options.repoPath ?? "repo";
+	const depth = options.depth ?? 50;
+	return defineTool({
+		description: "Fetch the pull request under review into the checkout and check it out as the local branch `pr`. Call this after get_task, before inspecting or testing the change. Returns the PR number, URL, and the commit you are now on.",
+		inputSchema: z.object({ changeId: changeIdSchema.describe("The change under review, from your starting message.") }),
+		async execute({ changeId }, ctx) {
+			const change = await stores.changes.get(changeId);
+			if (change === null) return {
+				fetched: false,
+				reason: `change ${changeId} does not exist`
+			};
+			if (change.state !== "verifying" && change.state !== "ready") return {
+				fetched: false,
+				reason: `change is ${change.state}, not open for review; nothing to fetch`
+			};
+			const repository = await stores.repositories.get(change.repositoryId);
+			if (repository === null) return {
+				fetched: false,
+				reason: `repository ${change.repositoryId} does not exist`
+			};
+			const sandbox = await ctx.getSandbox();
+			const tracking = `refs/remotes/origin/pr-${change.prNumber}`;
+			const git = `git -C ${repoPath}`;
+			const result = await options.withCredential(sandbox, repository.slug, `${git} fetch --depth ${depth} origin +refs/pull/${change.prNumber}/head:${tracking} && ${git} checkout -B pr ${tracking}`);
+			if (typeof result.exitCode === "number" && result.exitCode !== 0) return {
+				fetched: false,
+				reason: `git fetch of pull request ${change.prNumber} failed: ${(result.stderr ?? "").trim()}`
+			};
+			const head = await sandbox.run({ command: `${git} rev-parse HEAD` });
+			return {
+				fetched: true,
+				prNumber: change.prNumber,
+				prUrl: change.prUrl,
+				branch: "pr",
+				headSha: head.stdout.trim()
+			};
+		}
+	});
+}
+//#endregion
+//#region src/eve/invoke.ts
+/**
+* A tool that lets one agent hand work to another, NMA-style: the caller
+* decides to invoke; trusted code owns the how. The handoff is recorded as a
+* factory task (single-winner dispatch, receipts), then a fresh session is
+* started on the target agent carrying only the task id — never the caller's
+* context. The session start is create-once on the task id, so a retried
+* tool call cannot start a second session.
+*/
+function invokeAgentTool(stores, options) {
+	const doFetch = options.fetch ?? fetch;
+	return defineTool({
+		description: `${options.description} Hands the work to a separate agent in a fresh session; you will not see its reasoning. Returns the handoff task id.`,
+		inputSchema: z.object({
+			repositoryIds: z.array(repositoryIdSchema).min(1),
+			parentTaskId: taskIdSchema.optional().describe("Your own task, when this work continues it."),
+			changeId: changeIdSchema.optional().describe("The change the target agent should work on."),
+			channel: z.string().min(1).describe("Reply connector, e.g. github."),
+			address: z.string().min(1).describe("Reply address, e.g. acme/web#41."),
+			brief: z.string().min(1).max(4e3).describe("What the target agent needs to know. Facts and references only, not your reasoning.")
+		}),
+		async execute(input) {
+			const task = await stores.tasks.create({
+				repositoryIds: input.repositoryIds,
+				kind: options.kind,
+				origin: input.parentTaskId === void 0 ? { operator: "factory" } : { parentTaskId: input.parentTaskId },
+				replyTo: {
+					channel: input.channel,
+					address: input.address
+				}
+			});
+			const running = await dispatchTask(stores, task.id, {
+				maxLaunchAttempts: 1,
+				launch: async (dispatched) => {
+					const headers = {
+						"content-type": "application/json",
+						...await options.headers?.()
+					};
+					const token = await options.token?.();
+					if (token !== void 0) headers.authorization = `Bearer ${token}`;
+					const message = [
+						`You are assigned factory task ${dispatched.id}.`,
+						input.changeId === void 0 ? null : `Change under review: ${input.changeId}.`,
+						`Reply address: ${input.channel} ${input.address}.`,
+						"",
+						input.brief,
+						"",
+						"Read the task with get_task first, do the work, and record the outcome with your factory tools."
+					].filter((line) => line !== null).join("\n");
+					const response = await doFetch(`${options.targetUrl()}/eve/v1/session`, {
+						method: "POST",
+						headers,
+						body: JSON.stringify({
+							message,
+							operationId: `factory-task:${dispatched.id}`
+						})
+					});
+					if (!response.ok) throw new Error(`target agent refused the session: ${response.status}`);
+				}
+			});
+			return {
+				taskId: running.id,
+				kind: running.kind,
+				state: running.state
+			};
+		}
+	});
+}
+//#endregion
+//#region src/eve/review.ts
+function reviewCommentTools(stores, options) {
+	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 }) {
+				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`);
+				return readReviewComment({
+					repository: repository.slug,
+					token: await options.tokenForRepository(repository.slug),
+					fetch: options.fetch,
+					commentId
+				});
+			}
+		}),
+		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 }) {
+				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`);
+				return answerReviewComment({
+					repository: repository.slug,
+					token: await options.tokenForRepository(repository.slug),
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId,
+					body
+				});
+			}
+		}),
+		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 }) {
+				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`);
+				return answerReviewComment({
+					repository: repository.slug,
+					token: await options.tokenForRepository(repository.slug),
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId,
+					body: `${summary}\n\n\`\`\`suggestion\n${replacement}\n\`\`\``
+				});
+			}
+		}),
+		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 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 (options.withCredential === void 0) throw new Error("applying review fixes is not configured");
+				const token = await options.tokenForRepository(repository.slug);
+				await readReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					commentId
+				});
+				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");
+				const push = await options.withCredential(sandbox, repository.slug, `${git} push --force-with-lease=refs/heads/${head.branch}:${head.sha} origin HEAD:refs/heads/${head.branch}`);
+				if (typeof push.exitCode === "number" && push.exitCode !== 0) throw new Error(`could not update pull request branch: ${(push.stderr ?? "").trim()}`);
+				const reply = await answerReviewComment({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber,
+					commentId,
+					body: summary
+				});
+				return {
+					updated: true,
+					prNumber: change.prNumber,
+					prUrl: change.prUrl,
+					reply
+				};
+			}
+		})
+	};
+}
+//#endregion
+//#region src/eve/verification.ts
+/**
+* The verifier's outcome tool. Writes evidence onto the change and moves it
+* to ready only when the verdict is pass; a failed verdict leaves the change
+* verifying with the evidence recorded, and the verification task itself
+* ends with a receipt either way. The change's own code_change task follows
+* the verdict too: succeeded on pass, failed on fail with the verifier's
+* summary as the reason, so the ledger never shows a verified-and-rejected fix
+* as still in progress. Fail closed: the agent cannot mark a change ready
+* without supplying every evidence field.
+*/
+function recordVerificationTool(stores) {
+	return defineTool({
+		description: "Record the outcome of a verification task: the evidence you gathered and whether the change passed. Pass moves the change to ready for human review; fail keeps it out of review.",
+		inputSchema: z.object({
+			taskId: taskIdSchema.describe("Your verification task."),
+			changeId: changeIdSchema.describe("The change you verified."),
+			verdict: z.enum(["pass", "fail"]),
+			evidence: changeEvidenceSchema,
+			confidence: levelSchema.describe("How certain you are in the verdict."),
+			summary: z.string().min(1).max(2e3).describe("What you checked and what you found.")
+		}),
+		async execute({ taskId, changeId, verdict, evidence, confidence, summary }) {
+			const change = await stores.changes.get(changeId);
+			if (change === null) return {
+				recorded: false,
+				reason: `change ${changeId} does not exist`
+			};
+			if (change.state !== "verifying") return {
+				recorded: false,
+				reason: `change is ${change.state}, not verifying; nothing to record`
+			};
+			const task = await stores.tasks.get(taskId);
+			if (task === null || task.kind !== "verification") return {
+				recorded: false,
+				reason: `${taskId} is not a verification task`
+			};
+			let updatedChange = change;
+			if (verdict === "pass") updatedChange = await stores.changes.transition(changeId, "ready", {
+				patch: {
+					evidence,
+					confidence
+				},
+				reason: summary
+			});
+			let finished;
+			if (verdict === "pass") {
+				await stores.tasks.transition(taskId, "verifying", { reason: summary });
+				finished = await stores.tasks.transition(taskId, "succeeded");
+			} else finished = await stores.tasks.transition(taskId, "failed", { reason: summary });
+			if (change.taskId !== void 0) {
+				if ((await stores.tasks.get(change.taskId))?.state === "verifying") await stores.tasks.transition(change.taskId, verdict === "pass" ? "succeeded" : "failed", verdict === "pass" ? {} : { reason: `verification failed: ${summary}` }).catch(() => void 0);
+			}
+			return {
+				recorded: true,
+				verdict,
+				changeState: updatedChange.state,
+				taskState: finished.state
+			};
+		}
+	});
+}
+//#endregion
+//#region src/eve/index.ts
+const decidedOutcomeSchema = z.enum([
+	"accepted",
+	"duplicate",
+	"unactionable",
+	"low_confidence",
+	"ignored"
+]);
+const recordChangeInputSchema = z.object({
+	taskId: taskIdSchema,
+	repositoryId: repositoryIdSchema,
+	prNumber: z.number().int().min(1),
+	prUrl: z.url(),
+	risk: levelSchema.describe("Blast radius of the change if it is wrong."),
+	confidence: levelSchema.describe("How certain you are the change is correct."),
+	summary: z.string().min(1).describe("One-sentence description of the change.")
+});
+/**
+* The factory's store operations wrapped as eve tools. Expose a tool to an
+* agent by re-exporting it from a file under agent/tools/, e.g.
+* `export default factoryTools(stores).get_task;`. Every write goes through
+* the engine, so agents inherit transition legality and receipts.
+*/
+function factoryTools(stores, options = {}) {
+	const recordChangeGate = options.recordChangeGate;
+	return {
+		get_task: defineTool({
+			description: "Read one factory task by id: its kind, state, repositories, origin, and results.",
+			inputSchema: z.object({ taskId: taskIdSchema }),
+			async execute({ taskId }) {
+				return await stores.tasks.get(taskId) ?? {
+					found: false,
+					taskId
+				};
+			}
+		}),
+		decide_signal: defineTool({
+			description: "Record the triage decision for a pending signal. A signal is decided exactly once.",
+			inputSchema: z.object({
+				signalId: signalIdSchema,
+				outcome: decidedOutcomeSchema,
+				reason: z.string().min(1).describe("Why this outcome was chosen."),
+				detail: z.string().min(1).optional().describe("Severity if accepted, or the duplicate-of signal id.")
+			}),
+			execute({ signalId, outcome, reason, detail }) {
+				return stores.signals.decide(signalId, outcome, {
+					reason,
+					detail
+				});
+			}
+		}),
+		record_change: defineTool({
+			description: "Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying.",
+			inputSchema: recordChangeInputSchema,
+			...recordChangeGate === void 0 ? {} : { approval: async ({ toolInput }) => {
+				const parsed = recordChangeInputSchema.safeParse(toolInput);
+				if (!parsed.success) return {
+					type: "denied",
+					reason: "record_change input is malformed; fix the arguments and retry"
+				};
+				const verdict = await recordChangeGate(parsed.data);
+				return verdict.ok ? "not-applicable" : {
+					type: "denied",
+					reason: verdict.reason
+				};
+			} },
+			async execute({ taskId, repositoryId, prNumber, prUrl, risk, confidence, summary }) {
+				const change = await stores.changes.create({
+					repositoryId,
+					taskId,
+					prNumber,
+					prUrl,
+					author: "factory",
+					risk,
+					confidence,
+					evidence: {
+						reproVerified: false,
+						testsAdded: 0,
+						checksGreen: false,
+						attackPassed: false,
+						scopeMatches: false
+					}
+				});
+				return {
+					change,
+					task: await stores.tasks.transition(taskId, "verifying", {
+						patch: { changeId: change.id },
+						reason: summary
+					})
+				};
+			}
+		}),
+		finish_task: defineTool({
+			description: "Mark your task finished with a summary, for task kinds that have no other outcome tool (for example a security_scan). Not for code_change or verification tasks: those end with record_change and record_verification.",
+			inputSchema: z.object({
+				taskId: taskIdSchema,
+				summary: z.string().min(1).max(4e3).describe("What you did and found, for the ledger.")
+			}),
+			async execute({ taskId, summary }) {
+				const task = await stores.tasks.get(taskId);
+				if (task === null) return {
+					finished: false,
+					reason: `${taskId} does not exist`
+				};
+				if (task.kind === "code_change" || task.kind === "verification") return {
+					finished: false,
+					reason: `${task.kind} tasks end with their own outcome tool`
+				};
+				if (task.state !== "running") return {
+					finished: false,
+					reason: `task is ${task.state}, not running`
+				};
+				await stores.tasks.transition(taskId, "verifying", { reason: summary });
+				return {
+					finished: true,
+					taskState: (await stores.tasks.transition(taskId, "succeeded", { reason: summary })).state
+				};
+			}
+		}),
+		report_blocked: defineTool({
+			description: "Mark a running task as needing a human because the work cannot continue without help.",
+			inputSchema: z.object({
+				taskId: taskIdSchema,
+				reason: z.string().min(1).describe("What is blocking, written for the human.")
+			}),
+			execute({ taskId, reason }) {
+				return stores.tasks.transition(taskId, "needs_human", { reason });
+			}
+		}),
+		ask_question: defineTool({
+			description: "Raise a question a human operator must answer. Creates a question task that waits for the answer.",
+			inputSchema: z.object({
+				repositoryIds: z.array(repositoryIdSchema).min(1),
+				parentTaskId: taskIdSchema.optional().describe("Task the answer unblocks, when there is one."),
+				channel: z.string().min(1).describe("Reply connector, e.g. github."),
+				address: z.string().min(1).describe("Reply address, e.g. acme/web#41."),
+				question: taskQuestionSchema.omit({
+					answer: true,
+					answeredBy: true
+				})
+			}),
+			async execute({ repositoryIds, parentTaskId, channel, address, question }) {
+				const task = await stores.tasks.create({
+					repositoryIds,
+					kind: "question",
+					origin: parentTaskId === void 0 ? { operator: "factory" } : { parentTaskId },
+					replyTo: {
+						channel,
+						address
+					},
+					question
+				});
+				return stores.tasks.transition(task.id, "needs_human");
+			}
+		}),
+		append_receipt: defineTool({
+			description: "Append one immutable audit receipt for an event worth remembering. Receipts can never be edited or deleted.",
+			inputSchema: z.object({
+				repositoryIds: z.array(repositoryIdSchema).min(1),
+				taskId: taskIdSchema.optional(),
+				changeId: changeIdSchema.optional(),
+				kind: vocabularySchema.describe("What the receipt is about, e.g. investigation."),
+				state: vocabularySchema.describe("What happened, e.g. flag_ramped."),
+				reason: z.string().min(1).max(2e3).optional(),
+				dedupeKey: z.string().min(1).optional().describe("Same key twice records one receipt instead of two.")
+			}),
+			execute(input) {
+				return stores.receipts.append(input);
+			}
+		})
+	};
+}
+/**
+* Observe-only eve hooks that keep the ledger honest about session outcomes.
+* Mount by re-exporting from agent/hooks/, e.g.
+* `export default factoryHooks(stores).factory;`.
+*
+* turn.completed: a turn that ends while its task is still running means the
+* agent finished talking without recording an outcome; the task moves to
+* needs_human instead of rotting. The task is found by the session's
+* channel address, which dispatch set from the task's replyTo.
+*/
+function factoryHooks(stores) {
+	return { factory: defineHook({ events: { async "turn.completed"(_event, ctx) {
+		const address = ctx.channel.continuationToken;
+		if (address === void 0) return;
+		const abandoned = (await stores.tasks.list()).filter((task) => task.state === "running" && task.replyTo.address === address);
+		for (const task of abandoned) await stores.tasks.transition(task.id, "needs_human", { reason: "agent turn ended without recording an outcome" }).catch(() => void 0);
+	} } }) };
+}
+//#endregion
+export { deepsecScanTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, mergeConflictPayloadSchema, mergeConflictTools, recordFinding, recordFindingTool, recordVerificationTool, reviewCommentTools };
+
+//# sourceMappingURL=index.mjs.map