@vercel/factory 0.0.12 → 0.0.14

package/dist/eve/index.mjs

@@ -1,8 +1,11 @@
-import { i as repositoryIdSchema, o as signalIdSchema, p as vocabularySchema, s as taskIdSchema, t as changeIdSchema } from "../id-DwCihQr4.mjs";
-import { c as findingSchema, i as requiresApproval, o as findingFingerprint, r as defaultApprovalPolicy } from "../approval-DdvEKLiE.mjs";
-import { g as taskQuestionSchema, i as levelSchema, s as dispatchTask, t as changeEvidenceSchema } from "../change-CFNGXVqD.mjs";
+import { c as signalIdSchema, h as vocabularySchema, l as taskIdSchema, n as changeIdSchema, o as repositoryIdSchema } from "../id-BLIkCVue.mjs";
+import { l as taskQuestionSchema } from "../task-CcOyOJ3k.mjs";
+import { c as findingSchema, i as requiresApproval, o as findingFingerprint, r as defaultApprovalPolicy } from "../approval-JX2Px9IC.mjs";
+import { c as dispatchTask, i as levelSchema, t as changeEvidenceSchema } from "../change-D2U6v7Ek.mjs";
+import { t as createCoordination } from "../coordination-Cq08hb1l.mjs";
 import { answerReviewComment, readPullRequestHead, readReviewComment, submitPullRequestReview } from "../github.mjs";
 import { z } from "zod";
+import { createHash } from "node:crypto";
 import { defineHook } from "eve/hooks";
 import { defineTool } from "eve/tools";
 //#region src/eve/conflict.ts
@@ -369,9 +372,21 @@ 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.") }),
+		description: "Fetch the pull request and the repository's current default branch, then check out the pull request as local branch `pr`. Call this after get_task, before inspecting or testing the change. Returns an exact diff command based on their merge base; use it instead of origin/HEAD.",
+		inputSchema: z.object({ changeId: changeIdSchema.describe("The Change linked to your Task, returned by get_task.") }),
 		async execute({ changeId }, ctx) {
+			const boundTaskId = taskIdSchema.safeParse(ctx.session?.auth.initiator?.attributes.factoryTaskId);
+			if (boundTaskId.success) {
+				const task = await stores.tasks.get(boundTaskId.data);
+				if (task === null) return {
+					fetched: false,
+					reason: `task ${boundTaskId.data} does not exist`
+				};
+				if (task.changeId !== void 0 && task.changeId !== changeId) return {
+					fetched: false,
+					reason: `change ${changeId} is not linked to task ${boundTaskId.data}`
+				};
+			}
 			const change = await stores.changes.get(changeId);
 			if (change === null) return {
 				fetched: false,
@@ -388,19 +403,31 @@ function fetchPullRequestTool(stores, options) {
 			};
 			const sandbox = await ctx.getSandbox();
 			const tracking = `refs/remotes/origin/pr-${change.prNumber}`;
+			const baseTracking = `refs/remotes/origin/${repository.defaultBranch}`;
 			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}`);
+			const result = await options.withCredential(sandbox, repository.slug, `${git} fetch --depth ${depth} origin +refs/heads/${repository.defaultBranch}:${baseTracking} +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` });
+			const base = await sandbox.run({ command: `${git} rev-parse ${baseTracking}` });
+			const mergeBase = await sandbox.run({ command: `${git} merge-base ${baseTracking} pr` });
+			if (typeof mergeBase.exitCode === "number" && mergeBase.exitCode !== 0) return {
+				fetched: false,
+				reason: `could not determine the pull request merge base: ${(mergeBase.stderr ?? "").trim()}`
+			};
+			const mergeBaseSha = mergeBase.stdout.trim();
 			return {
 				fetched: true,
 				prNumber: change.prNumber,
 				prUrl: change.prUrl,
 				branch: "pr",
-				headSha: head.stdout.trim()
+				headSha: head.stdout.trim(),
+				baseBranch: repository.defaultBranch,
+				baseSha: base.stdout.trim(),
+				mergeBaseSha,
+				diffCommand: `${git} diff ${mergeBaseSha}..pr`
 			};
 		}
 	});
@@ -439,6 +466,7 @@ function invokeAgentTool(stores, options) {
 			});
 			const running = await dispatchTask(stores, task.id, {
 				maxLaunchAttempts: 1,
+				budget: options.budget?.(),
 				launch: async (dispatched) => {
 					const headers = {
 						"content-type": "application/json",
@@ -474,20 +502,156 @@ function invokeAgentTool(stores, options) {
 		}
 	});
 }
+/**
+* Give a conversational agent one bounded delegation surface backed by the
+* application's route registry. The caller selects a declared route; trusted
+* code owns task creation, budget enforcement, and the fresh target session.
+*/
+function delegateAgentTool(stores, options) {
+	const doFetch = options.fetch ?? fetch;
+	const routeSummary = options.routes.routes.map((route) => `${route.id}: ${route.description}`).join("\n");
+	return defineTool({
+		description: "Delegate durable work to one registered specialist. Select only a listed route; the specialist runs independently and reports its result through Factory.\n" + routeSummary,
+		inputSchema: z.object({
+			routeId: z.string().min(1).describe("One route id listed in this tool's description."),
+			repositoryIds: z.array(repositoryIdSchema).min(1),
+			signalId: signalIdSchema.optional().describe("Pending external signal this delegation accepts."),
+			parentTaskId: taskIdSchema.optional().describe("Existing task this work continues."),
+			changeId: changeIdSchema.optional().describe("Existing change the specialist should inspect."),
+			channel: z.string().min(1).describe("Originating conversation channel."),
+			address: z.string().min(1).describe("Originating conversation reply address."),
+			brief: z.string().min(1).max(4e3).describe("Facts and desired outcome, without hidden reasoning.")
+		}),
+		async execute(input, ctx) {
+			const route = options.routes.get(input.routeId);
+			if (route === void 0) throw new Error(`Unknown agent route ${input.routeId}.`);
+			const replyTo = {
+				channel: input.channel,
+				address: input.address
+			};
+			const attributes = ctx.session.auth.initiator?.attributes;
+			const repositoryAttribute = attributes?.factoryRepositoryIds;
+			const boundRepositoryIds = typeof repositoryAttribute === "string" ? repositoryAttribute.split(",").filter(Boolean) : repositoryAttribute;
+			if (boundRepositoryIds !== void 0 && (boundRepositoryIds.length !== input.repositoryIds.length || boundRepositoryIds.some((id) => !input.repositoryIds.includes(id)))) throw new Error("Delegation repositories do not match the connector-authenticated context.");
+			if (attributes?.factoryReplyChannel !== void 0 && attributes.factoryReplyChannel !== replyTo.channel || attributes?.factoryReplyAddress !== void 0 && attributes.factoryReplyAddress !== replyTo.address) throw new Error("Delegation reply address does not match the authenticated conversation.");
+			for (const repositoryId of input.repositoryIds) {
+				const repository = await stores.repositories.get(repositoryId);
+				if (repository === null || !repository.enabled) throw new Error(`Repository ${repositoryId} is not enabled in this factory.`);
+			}
+			const boundChange = changeIdSchema.safeParse(attributes?.factoryChangeId);
+			if (attributes?.factoryChangeId !== void 0 && !boundChange.success) throw new Error("Connector-authenticated change context is invalid.");
+			if (input.changeId !== void 0 && boundChange.success && input.changeId !== boundChange.data) throw new Error("Delegated change does not match the connector-authenticated context.");
+			const changeId = input.changeId ?? (boundChange.success ? boundChange.data : void 0);
+			if (changeId !== void 0) {
+				if (input.repositoryIds.length !== 1) throw new Error("Delegating work on an existing Change requires exactly one repository.");
+				const change = await stores.changes.get(changeId);
+				if (change === null || change.repositoryId !== input.repositoryIds[0] || change.state !== "verifying" && change.state !== "ready") throw new Error(`Change ${changeId} is not an open pull request in the selected repository.`);
+			}
+			if (input.signalId !== void 0) {
+				const signal = await stores.signals.get(input.signalId);
+				if (signal === null) throw new Error(`Signal ${input.signalId} does not exist.`);
+				if (!input.repositoryIds.includes(signal.repositoryId) || signal.replyTo.channel !== replyTo.channel || signal.replyTo.address !== replyTo.address) throw new Error("Delegation does not match the signal's authenticated repository and reply address.");
+				if (signal.outcome === "pending") await stores.signals.decide(signal.id, "accepted", { reason: `Foreman selected ${route.id}.` });
+				else if (signal.outcome !== "accepted") throw new Error(`Signal ${signal.id} is already ${signal.outcome}.`);
+			}
+			const operator = ctx.session.auth.initiator?.principalId ?? "foreman";
+			if (route.taskKind === "code_change" && input.repositoryIds.length > 1) {
+				const [first, second, ...rest] = input.repositoryIds;
+				if (first === void 0 || second === void 0) throw new Error("Coordination requires two repositories.");
+				const coordination = await createCoordination(stores, {
+					repositoryIds: [
+						first,
+						second,
+						...rest
+					],
+					replyTo,
+					...input.signalId === void 0 ? {} : { dedupeKey: `route:${input.signalId}:${route.id}` },
+					...input.signalId === void 0 ? { operator } : { signalId: input.signalId }
+				});
+				await Promise.all(coordination.children.filter((child) => child.state === "queued").map((child) => dispatchRouteTask(stores, options, doFetch, route, child, changeId, input.brief)));
+				return {
+					taskId: coordination.parent.id,
+					childTaskIds: coordination.children.map(({ id }) => id),
+					routeId: route.id,
+					agent: route.agent,
+					state: coordination.parent.state
+				};
+			}
+			const task = await stores.tasks.create({
+				repositoryIds: input.repositoryIds,
+				kind: route.taskKind,
+				origin: input.signalId !== void 0 ? { signalId: input.signalId } : input.parentTaskId !== void 0 ? { parentTaskId: input.parentTaskId } : { operator },
+				replyTo,
+				changeId,
+				...input.signalId === void 0 ? {} : { dedupeKey: `route:${input.signalId}:${route.id}` }
+			});
+			const running = task.state === "queued" ? await dispatchRouteTask(stores, options, doFetch, route, task, changeId, input.brief) : task;
+			return {
+				taskId: running.id,
+				routeId: route.id,
+				agent: route.agent,
+				state: running.state
+			};
+		}
+	});
+}
+async function dispatchRouteTask(stores, options, doFetch, route, task, changeId, brief) {
+	return dispatchTask(stores, task.id, {
+		maxLaunchAttempts: 1,
+		budget: options.budget?.(route),
+		launch: async (dispatched) => {
+			const headers = {
+				"content-type": "application/json",
+				...await options.headers?.(dispatched, route)
+			};
+			const token = await options.token?.(route);
+			if (token !== void 0) headers.authorization = `Bearer ${token}`;
+			const message = [
+				`You are assigned factory task ${dispatched.id} through route ${route.id}.`,
+				changeId === void 0 ? null : `Change under review: ${changeId}.`,
+				brief,
+				"Read the task first and return exactly one bounded Factory outcome."
+			].filter((line) => line !== null).join("\n\n");
+			const response = await doFetch(`${options.targetUrl(route)}/eve/v1/session`, {
+				method: "POST",
+				headers,
+				body: JSON.stringify({
+					message,
+					operationId: `factory-task:${dispatched.id}`
+				})
+			});
+			if (!response.ok) throw new Error(`${route.agent} refused the session: ${response.status}`);
+		}
+	});
+}
 //#endregion
 //#region src/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);
+	});
+});
 /**
 * Publish an independent review of an existing pull request and finish the
 * review task without changing the pull request's factory lifecycle.
 */
 function postReviewTool(stores, options) {
 	return defineTool({
-		description: "Publish a completed code review to the existing pull request and finish your code_review task. Use request_changes only for blocking findings.",
+		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."),
@@ -498,7 +662,7 @@ function postReviewTool(stores, options) {
 			]),
 			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: z.array(reviewCommentSchema).max(50).default([])
+			comments: reviewCommentsSchema
 		}),
 		async execute({ taskId, changeId, verdict, headSha, summary, comments }) {
 			const task = await stores.tasks.get(taskId);
@@ -524,36 +688,68 @@ function postReviewTool(stores, options) {
 				recorded: false,
 				reason: `repository ${change.repositoryId} does not exist`
 			};
-			const review = await submitPullRequestReview({
-				repository: repository.slug,
-				token: await options.tokenForRepository(repository.slug),
-				fetch: options.fetch,
-				pullRequestNumber: change.prNumber,
-				commitId: headSha,
-				event: verdict === "approve" ? "APPROVE" : verdict === "request_changes" ? "REQUEST_CHANGES" : "COMMENT",
-				body: summary,
-				comments
+			const token = await options.tokenForRepository(repository.slug);
+			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")
+				};
 			});
-			await options.onPublished?.({
+			const completed = {
 				taskId,
 				changeId,
 				repository: repository.slug,
+				pullRequestNumber: change.prNumber,
 				headSha,
 				verdict,
 				summary,
-				comments,
-				review
-			});
+				comments: completedComments
+			};
+			const publish = options.publishReviews !== false;
+			let review;
+			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
+				});
+				await options.onPublished?.({
+					...completed,
+					review
+				});
+			} else {
+				const head = await readPullRequestHead({
+					repository: repository.slug,
+					token,
+					fetch: options.fetch,
+					pullRequestNumber: change.prNumber
+				});
+				if (head.sha !== headSha) throw new Error(`pull request changed after review: expected ${headSha}, found ${head.sha}`);
+			}
+			await options.onCompleted?.(completed);
 			await stores.tasks.transition(taskId, "verifying", { reason: summary });
+			const finished = await stores.tasks.transition(taskId, "succeeded");
 			return {
 				recorded: true,
 				verdict,
-				review,
-				taskState: (await stores.tasks.transition(taskId, "succeeded")).state
+				published: review !== void 0,
+				...review === void 0 ? {} : { review },
+				taskState: finished.state
 			};
 		}
 	});
 }
+function legacyFindingKey(comment) {
+	return `legacy-${createHash("sha256").update(`${comment.path}:${comment.line}:${comment.body}`).digest("hex").slice(0, 24)}`;
+}
 //#endregion
 //#region src/eve/review.ts
 function reviewCommentTools(stores, options) {
@@ -686,7 +882,7 @@ function reviewCommentTools(stores, options) {
 * as still in progress. Fail closed: the agent cannot mark a change ready
 * without supplying every evidence field.
 */
-function recordVerificationTool(stores) {
+function recordVerificationTool(stores, options = {}) {
 	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({
@@ -703,9 +899,9 @@ function recordVerificationTool(stores) {
 				recorded: false,
 				reason: `change ${changeId} does not exist`
 			};
-			if (change.state !== "verifying") return {
+			if (change.state !== "verifying" && change.state !== "ready") return {
 				recorded: false,
-				reason: `change is ${change.state}, not verifying; nothing to record`
+				reason: `change is ${change.state}, not open for verification; nothing to record`
 			};
 			const task = await stores.tasks.get(taskId);
 			if (task === null || task.kind !== "verification") return {
@@ -713,21 +909,29 @@ function recordVerificationTool(stores) {
 				reason: `${taskId} is not a verification task`
 			};
 			let updatedChange = change;
-			if (verdict === "pass") updatedChange = await stores.changes.transition(changeId, "ready", {
+			if (verdict === "pass" && change.state === "verifying") updatedChange = await stores.changes.transition(changeId, "ready", {
 				patch: {
 					evidence,
 					confidence
 				},
 				reason: summary
 			});
+			else if (verdict === "fail" && change.state === "ready") updatedChange = await stores.changes.transition(changeId, "verifying", { 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);
+			const sourceTaskId = task.origin.parentTaskId ?? change.taskId;
+			if (sourceTaskId !== void 0) {
+				if ((await stores.tasks.get(sourceTaskId))?.state === "verifying") await stores.tasks.transition(sourceTaskId, verdict === "pass" ? "succeeded" : "failed", verdict === "pass" ? {} : { reason: `verification failed: ${summary}` }).catch(() => void 0);
 			}
+			await options.presentResult?.({
+				taskId,
+				changeId,
+				verdict,
+				summary
+			});
 			return {
 				recorded: true,
 				verdict,
@@ -755,6 +959,28 @@ const recordChangeInputSchema = z.object({
 	confidence: levelSchema.describe("How certain you are the change is correct."),
 	summary: z.string().min(1).describe("One-sentence description of the change.")
 });
+async function createAndPresentQuestion(stores, parent, question, presentQuestion) {
+	const task = await stores.tasks.create({
+		repositoryIds: parent.repositoryIds,
+		kind: "question",
+		origin: { parentTaskId: parent.id },
+		replyTo: parent.replyTo,
+		question
+	});
+	const waiting = await stores.tasks.transition(task.id, "needs_human");
+	try {
+		if (parent.state === "running") await stores.tasks.transition(parent.id, "needs_human", {
+			reason: `waiting for answer to question ${waiting.id}`,
+			questionTaskId: waiting.id
+		});
+		await presentQuestion(waiting);
+	} catch (error) {
+		if ((await stores.tasks.get(parent.id))?.state === "needs_human") await stores.tasks.transition(parent.id, "queued", { reason: `delivery of question ${waiting.id} failed` });
+		if ((await stores.tasks.get(waiting.id))?.state === "needs_human") await stores.tasks.transition(waiting.id, "cancelled", { reason: "question delivery failed" });
+		throw error;
+	}
+	return waiting;
+}
 /**
 * 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.
@@ -763,6 +989,7 @@ const recordChangeInputSchema = z.object({
 */
 function factoryTools(stores, options = {}) {
 	const recordChangeGate = options.recordChangeGate;
+	const verification = options.verification ?? "required";
 	return {
 		get_task: defineTool({
 			description: "Read one factory task by id: its kind, state, repositories, origin, and results.",
@@ -790,7 +1017,7 @@ function factoryTools(stores, options = {}) {
 			}
 		}),
 		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.",
+			description: verification === "required" ? "Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying." : "Record the pull request produced for a code_change task. Creates the change and marks it ready for human review without independent verification.",
 			inputSchema: recordChangeInputSchema,
 			...recordChangeGate === void 0 ? {} : { approval: async ({ toolInput }) => {
 				const parsed = recordChangeInputSchema.safeParse(toolInput);
@@ -805,28 +1032,51 @@ function factoryTools(stores, options = {}) {
 				};
 			} },
 			async execute({ taskId, repositoryId, prNumber, prUrl, risk, confidence, summary }) {
-				const change = await stores.changes.create({
-					repositoryId,
+				const currentTask = await stores.tasks.get(taskId);
+				if (currentTask === null) throw new Error(`task ${taskId} does not exist`);
+				if (currentTask.state !== "running" && currentTask.state !== "verifying" && currentTask.state !== "succeeded") throw new Error(`task ${taskId} is ${currentTask.state}, not running`);
+				const linkedChange = currentTask.changeId === void 0 ? void 0 : await stores.changes.get(currentTask.changeId);
+				if (currentTask.changeId !== void 0 && linkedChange === null) throw new Error(`change ${currentTask.changeId} does not exist`);
+				let change = linkedChange ?? (await stores.changes.list()).find((candidate) => candidate.taskId === taskId);
+				if (change === void 0) {
+					if (currentTask.state !== "running") throw new Error(`task ${taskId} has no recorded change`);
+					change = await stores.changes.create({
+						repositoryId,
+						taskId,
+						prNumber,
+						prUrl,
+						author: "factory",
+						risk,
+						confidence,
+						evidence: {
+							reproVerified: false,
+							testsAdded: 0,
+							checksGreen: false,
+							attackPassed: false,
+							scopeMatches: false
+						}
+					});
+				}
+				if (currentTask.state === "running") await options.presentChange?.({
 					taskId,
-					prNumber,
-					prUrl,
-					author: "factory",
-					risk,
-					confidence,
-					evidence: {
-						reproVerified: false,
-						testsAdded: 0,
-						checksGreen: false,
-						attackPassed: false,
-						scopeMatches: false
-					}
+					changeId: change.id,
+					verification,
+					summary
 				});
+				let task = currentTask;
+				if (task.state === "running") task = await stores.tasks.transition(taskId, "verifying", {
+					patch: { changeId: change.id },
+					reason: summary
+				});
+				if (verification === "required") return {
+					change,
+					task
+				};
+				if (change.state === "verifying") change = await stores.changes.transition(change.id, "ready", { reason: "independent verification is not configured" });
+				if (task.state === "verifying") task = await stores.tasks.transition(taskId, "succeeded", { reason: "change recorded for human review without independent verification" });
 				return {
 					change,
-					task: await stores.tasks.transition(taskId, "verifying", {
-						patch: { changeId: change.id },
-						reason: summary
-					})
+					task
 				};
 			}
 		}),
@@ -857,40 +1107,42 @@ function factoryTools(stores, options = {}) {
 				};
 			}
 		}),
-		report_blocked: defineTool({
-			description: "Mark a running task as needing a human because the work cannot continue without help.",
+		request_human_input: defineTool({
+			description: "Request human input or action and pause your task until the human replies. The parent task determines the repositories and reply destination.",
 			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."),
+				parentTaskId: taskIdSchema.describe("Your running task, which the answer will unblock."),
 				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
+			async execute({ parentTaskId, question }) {
+				if (options.presentQuestion === void 0) throw new Error("request_human_input requires a configured question presenter.");
+				const parent = await stores.tasks.get(parentTaskId);
+				if (parent === null) throw new Error(`Parent task ${parentTaskId} does not exist.`);
+				if (parent.state !== "running" && parent.state !== "needs_human") throw new Error(`Parent task ${parentTaskId} is ${parent.state}, not running.`);
+				return createAndPresentQuestion(stores, parent, question, options.presentQuestion);
+			}
+		}),
+		answer_question: defineTool({
+			description: "Record the authenticated user's answer to a waiting question and requeue the parent specialist task. A blocked parent task id is also accepted and resolves its persisted QuestionTask id.",
+			inputSchema: z.object({
+				questionTaskId: taskIdSchema,
+				answer: z.string().min(1).max(4e3)
+			}),
+			async execute({ questionTaskId, answer }, ctx) {
+				const requestedTask = await stores.tasks.get(questionTaskId);
+				const resolvedQuestionTaskId = requestedTask?.kind === "question" ? requestedTask.id : requestedTask?.questionTaskId;
+				const questionTask = resolvedQuestionTaskId === void 0 ? null : await stores.tasks.get(resolvedQuestionTaskId);
+				if (questionTask === null || questionTask.kind !== "question" || questionTask.question === void 0) throw new Error(`Question task ${questionTaskId} does not exist.`);
+				const attributes = ctx.session.auth.initiator?.attributes;
+				if (attributes?.factoryReplyChannel !== questionTask.replyTo.channel || attributes.factoryReplyAddress !== questionTask.replyTo.address) throw new Error("Question reply does not match the authenticated conversation.");
+				const answeredBy = ctx.session.auth.initiator?.principalId ?? "operator";
+				return stores.tasks.answerQuestion({
+					questionTaskId: questionTask.id,
+					answer,
+					answeredBy
 				});
-				return stores.tasks.transition(task.id, "needs_human");
 			}
 		}),
 		append_receipt: defineTool({
@@ -910,25 +1162,62 @@ function factoryTools(stores, options = {}) {
 		})
 	};
 }
+const terminalTaskStates = /* @__PURE__ */ new Set([
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
 /**
 * 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;`.
+* `export default factoryHooks(stores, { presentQuestion }).factory;`.
+*
+* step.completed: records the step's tokens and AI Gateway cost on the bound
+* task. Delivery is at least once; recordUsage dedupes by (turnId, stepIndex).
 *
-* 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.
+* turn.completed: settles the bound task's recorded usage if the task is
+* already terminal (the sweep handles tasks that end later), then moves any
+* still-running task at this session's reply address behind a surfaced human
+* question, because the agent finished talking without recording an outcome.
+*
+* Every store call is swallowed: a hook throw fails the turn.
 */
-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);
-	} } }) };
+function factoryHooks(stores, options) {
+	const taskIdAttribute = options.taskIdAttribute ?? "factoryTaskId";
+	function boundTaskId(ctx) {
+		const parsed = taskIdSchema.safeParse(ctx.session.auth.initiator?.attributes[taskIdAttribute]);
+		return parsed.success ? parsed.data : void 0;
+	}
+	async function settleIfTerminal(taskId) {
+		const task = await stores.tasks.get(taskId);
+		if (task?.usage === void 0 || task.settledUsd !== void 0 || !terminalTaskStates.has(task.state)) return;
+		await stores.tasks.settle(task.id, { totalUsd: task.usage.costUsd }, { reason: "measured usage settled at turn end" });
+	}
+	return { factory: defineHook({ events: {
+		async "step.completed"(event, ctx) {
+			const taskId = boundTaskId(ctx);
+			const usage = event.data.usage;
+			if (taskId === void 0 || usage === void 0) return;
+			await stores.tasks.recordUsage(taskId, {
+				turnId: event.data.turnId,
+				stepIndex: event.data.stepIndex,
+				...usage
+			}).catch(() => void 0);
+		},
+		async "turn.completed"(_event, ctx) {
+			const taskId = boundTaskId(ctx);
+			if (taskId !== void 0) await settleIfTerminal(taskId).catch(() => void 0);
+			const address = ctx.channel.continuationToken;
+			if (address === void 0) return;
+			const abandoned = (await stores.tasks.list().catch(() => [])).filter((task) => task.state === "running" && task.replyTo.address === address);
+			for (const task of abandoned) await createAndPresentQuestion(stores, task, {
+				text: "The worker stopped without recording an outcome. Please review the task and reply when Factory should retry it.",
+				options: ["Retry the task"]
+			}, options.presentQuestion).catch(() => void 0);
+		}
+	} }) };
 }
 //#endregion
-export { deepsecScanTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, mergeConflictPayloadSchema, mergeConflictTools, postReviewTool, recordFinding, recordFindingTool, recordVerificationTool, reviewCommentTools };
+export { deepsecScanTool, delegateAgentTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, mergeConflictPayloadSchema, mergeConflictTools, postReviewTool, recordFinding, recordFindingTool, recordVerificationTool, reviewCommentTools };
 
 //# sourceMappingURL=index.mjs.map