@vercel/factory 0.0.14 → 0.0.16

package/dist/presets/software-development/task-communication.mjs

@@ -0,0 +1,157 @@
+import { agentSessionIdSchema } from "../../schema/session.mjs";
+import { createTaskCommunicationReconciler } from "../../task-communication.mjs";
+import { z } from "zod";
+//#region src/presets/software-development/task-communication.ts
+const reviewOutputSchema = z.object({
+	verdict: z.enum([
+		"approve",
+		"request_changes",
+		"comment"
+	]),
+	findingCount: z.number().int().nonnegative(),
+	review: z.object({
+		url: z.url(),
+		state: z.string().optional()
+	}).optional()
+});
+/** Supplied Slack, GitHub, and API presentation for a task question. */
+function createSoftwareDevelopmentTaskCommunication(options = {}) {
+	const githubMention = options.githubMention ?? "@agent-factory";
+	if (githubMention.trim().length === 0) throw new Error("githubMention must not be empty");
+	const needsHumanReplyTo = options.needsHumanReplyTo;
+	function questionEvents(task) {
+		if (task.kind !== "question" || task.question === void 0) throw new Error(`Task ${task.id} has no question.`);
+		const reference = `Reference: ${task.id}`;
+		const session = task.replyTo.channel === "api" && agentSessionIdSchema.safeParse(task.replyTo.address);
+		const instructions = session && session.success ? `Open Factory session ${session.data}: factory-tui --config REPLACE_WITH_TUI_CONFIG.json --session ${session.data}\nReplace REPLACE_WITH_TUI_CONFIG.json with an authenticated TUI config for the factory that sent this notice. Review the current question before answering; this notice may be stale.` : task.replyTo.channel === "slack" ? "To answer, reply in the original Slack thread and mention the Factory app." : task.replyTo.channel === "github" && /^[^/]+\/[^/#]+(?:#|\/pull\/)[1-9][0-9]*$/u.test(task.replyTo.address) ? `To answer, comment on ${task.replyTo.address} starting with \`${githubMention}\`.` : `No Factory conversation link recorded. Reply destination: ${task.replyTo.channel} ${task.replyTo.address}. Ask an operator to locate the original conversation using the question reference; do not use approve or retry-intake to answer it.`;
+		const common = {
+			repositoryIds: task.repositoryIds,
+			taskId: task.id
+		};
+		const action = task.needsHumanAction ?? task.question.text;
+		const events = [{
+			...common,
+			eventId: `question:${task.id}:${task.attempt}`,
+			replyTo: task.replyTo,
+			outcome: "question",
+			data: {
+				question: `${reference}\n\n${instructions}\n\n${task.question.text}`,
+				options: task.question.options
+			}
+		}];
+		if (needsHumanReplyTo !== void 0) events.push({
+			...common,
+			eventId: `needs-human:${task.id}:${task.attempt}`,
+			replyTo: needsHumanReplyTo,
+			outcome: "needs_human",
+			data: {
+				requestedAction: action.length > 2e3 ? `${action.slice(0, 2e3)}…` : action,
+				message: `${reference}\nReply destination: ${task.replyTo.channel} ${task.replyTo.address}\n${instructions}\nReplies in this notification DM do not answer the question.`,
+				options: task.question.options,
+				questionAttempt: task.attempt,
+				...task.parentTaskId === void 0 ? {} : { parentTaskId: task.parentTaskId },
+				replyChannel: task.replyTo.channel,
+				replyAddress: task.replyTo.address
+			}
+		});
+		return events;
+	}
+	return {
+		questionEvents,
+		reconcile: createTaskCommunicationReconciler({
+			question: questionEvents,
+			async lifecycle({ stores, tasks, task, receipt }) {
+				if (receipt.state === "succeeded" && task.changeId !== void 0) {
+					if (task.work.route?.id !== "code-review" || task.work.route.version !== 1 || task.origin.operator === void 0) return [];
+					const output = reviewOutputSchema.parse(task.workResult?.output);
+					const change = await stores.changes.get(task.changeId);
+					if (change === null) throw new Error(`Review ${task.id} references a missing Change.`);
+					const findings = output.findingCount === 0 ? output.verdict === "request_changes" ? "Changes requested." : output.review?.state === "APPROVED" ? "Approved. No issues found." : "No issues found." : `${output.findingCount} finding${output.findingCount === 1 ? "" : "s"}.${output.verdict === "request_changes" ? " Changes requested." : ""}`;
+					const event = eventFor(task, receipt);
+					return [{
+						...event,
+						data: {
+							...event.data,
+							title: `Review complete for PR #${change.prNumber}`,
+							summary: findings,
+							url: output.review?.url ?? change.prUrl
+						}
+					}];
+				}
+				return [task.kind === "coordination" && (receipt.state === "succeeded" || receipt.state === "failed") ? await coordinationEvent(stores, tasks, task, receipt) : eventFor(task, receipt)];
+			}
+		})
+	};
+}
+function completionSummary(task, receipt) {
+	const output = task.workResult?.output;
+	const summary = [...typeof output === "object" && output !== null && !Array.isArray(output) ? ["summary" in output ? output.summary : void 0, "result" in output ? output.result : void 0] : [output], receipt.reason].find((value) => typeof value === "string" && value.trim().length > 0);
+	if (!summary) return "Completed. No result summary was recorded; open the chat for details.";
+	const text = summary.trim();
+	return text.length > 1e3 ? `${text.slice(0, 997)}…` : text;
+}
+function eventFor(task, receipt) {
+	const common = {
+		eventId: `task-lifecycle:${receipt.receiptId}`,
+		repositoryIds: task.repositoryIds,
+		taskId: task.id,
+		...task.changeId === void 0 ? {} : { changeId: task.changeId },
+		replyTo: task.replyTo
+	};
+	if (receipt.state === "dispatched" && receipt.phase === "retry") return {
+		...common,
+		outcome: "started",
+		data: { message: `Retry attempt ${receipt.attempt} started.${receipt.reason === void 0 ? "" : ` ${receipt.reason}`}` }
+	};
+	if (receipt.state === "failed") {
+		let prefix = "Work failed.";
+		if (receipt.reason?.startsWith("launch failed")) prefix = "Work failed to start.";
+		else if (receipt.phase === "retry") prefix = "Retries exhausted.";
+		return {
+			...common,
+			outcome: "failed",
+			data: { reason: `${prefix}${receipt.reason === void 0 ? "" : ` ${receipt.reason}`}` }
+		};
+	}
+	if (receipt.state === "cancelled") {
+		const prefix = receipt.phase === "approval" ? "Request rejected." : "Work cancelled.";
+		return {
+			...common,
+			outcome: "cancelled",
+			data: {
+				message: `${prefix}${receipt.reason === void 0 ? "" : ` ${receipt.reason}`}`,
+				...receipt.phase === "approval" ? { approvalDecision: true } : {}
+			}
+		};
+	}
+	if (receipt.state === "succeeded") return {
+		...common,
+		outcome: "succeeded",
+		data: {
+			summary: completionSummary(task, receipt),
+			output: task.workResult?.output
+		}
+	};
+	throw new Error(`Receipt ${receipt.receiptId} is not a communicable task lifecycle event.`);
+}
+async function coordinationEvent(stores, tasks, parent, receipt) {
+	const children = tasks.filter((task) => task.parentTaskId === parent.id);
+	const items = await Promise.all(children.map(async (child) => {
+		const repository = await stores.repositories.get(child.repositoryIds[0]);
+		const change = child.changeId === void 0 ? null : await stores.changes.get(child.changeId);
+		return `${repository?.slug ?? child.repositoryIds[0]}: ${change?.prUrl ?? child.state}`;
+	}));
+	const event = eventFor(parent, receipt);
+	return {
+		...event,
+		data: {
+			...event.data,
+			summary: receipt.state === "succeeded" ? "Coordinated work completed." : "Coordinated work failed in one or more repositories.",
+			items
+		}
+	};
+}
+//#endregion
+export { createSoftwareDevelopmentTaskCommunication };
+
+//# sourceMappingURL=task-communication.mjs.map

package/dist/presets/software-development/task-communication.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-communication.mjs","names":[],"sources":["../../../src/presets/software-development/task-communication.ts"],"sourcesContent":["import { z } from \"zod\";\nimport type { CommunicationEvent } from \"../../schema/communication\";\nimport type { ReplyTo } from \"../../schema/common\";\nimport type { Receipt } from \"../../schema/receipt\";\nimport type { Task } from \"../../schema/task\";\nimport { agentSessionIdSchema } from \"../../schema/session\";\nimport type { FactoryStores } from \"../../store/engine\";\nimport {\n  createTaskCommunicationReconciler,\n  type TaskCommunicationReconciler,\n} from \"../../task-communication\";\n\n/** Store capabilities required by supplied software-development communication projections. */\nexport type SoftwareDevelopmentTaskCommunicationStores = Pick<\n  FactoryStores,\n  \"changes\" | \"outbox\" | \"receipts\" | \"repositories\" | \"tasks\"\n>;\n\n/** Connector presentation settings for supplied software Task communications. */\nexport interface SoftwareDevelopmentTaskCommunicationOptions {\n  githubMention?: string;\n  /** Optional additional notification destination; omitted keeps questions in their original conversation. */\n  needsHumanReplyTo?: ReplyTo;\n}\n\n/** Supplied question projection and durable lifecycle communication reconciler. */\nexport interface SoftwareDevelopmentTaskCommunication {\n  questionEvents(task: Task): readonly CommunicationEvent[];\n  reconcile: TaskCommunicationReconciler<SoftwareDevelopmentTaskCommunicationStores>;\n}\n\nconst reviewOutputSchema = z.object({\n  verdict: z.enum([\"approve\", \"request_changes\", \"comment\"]),\n  findingCount: z.number().int().nonnegative(),\n  review: z.object({ url: z.url(), state: z.string().optional() }).optional(),\n});\n\n/** Supplied Slack, GitHub, and API presentation for a task question. */\nexport function createSoftwareDevelopmentTaskCommunication(\n  options: SoftwareDevelopmentTaskCommunicationOptions = {},\n): SoftwareDevelopmentTaskCommunication {\n  const githubMention = options.githubMention ?? \"@agent-factory\";\n  if (githubMention.trim().length === 0) throw new Error(\"githubMention must not be empty\");\n  const needsHumanReplyTo = options.needsHumanReplyTo;\n\n  function questionEvents(task: Task): readonly CommunicationEvent[] {\n    if (task.kind !== \"question\" || task.question === undefined)\n      throw new Error(`Task ${task.id} has no question.`);\n    const reference = `Reference: ${task.id}`;\n    const session =\n      task.replyTo.channel === \"api\" && agentSessionIdSchema.safeParse(task.replyTo.address);\n    const instructions =\n      session && session.success\n        ? `Open Factory session ${session.data}: factory-tui --config REPLACE_WITH_TUI_CONFIG.json --session ${session.data}\\nReplace REPLACE_WITH_TUI_CONFIG.json with an authenticated TUI config for the factory that sent this notice. Review the current question before answering; this notice may be stale.`\n        : task.replyTo.channel === \"slack\"\n          ? \"To answer, reply in the original Slack thread and mention the Factory app.\"\n          : task.replyTo.channel === \"github\" &&\n              /^[^/]+\\/[^/#]+(?:#|\\/pull\\/)[1-9][0-9]*$/u.test(task.replyTo.address)\n            ? `To answer, comment on ${task.replyTo.address} starting with \\`${githubMention}\\`.`\n            : `No Factory conversation link recorded. Reply destination: ${task.replyTo.channel} ${task.replyTo.address}. Ask an operator to locate the original conversation using the question reference; do not use approve or retry-intake to answer it.`;\n    const common = { repositoryIds: task.repositoryIds, taskId: task.id };\n    const action = task.needsHumanAction ?? task.question.text;\n    const events: CommunicationEvent[] = [\n      {\n        ...common,\n        eventId: `question:${task.id}:${task.attempt}`,\n        replyTo: task.replyTo,\n        outcome: \"question\",\n        data: {\n          question: `${reference}\\n\\n${instructions}\\n\\n${task.question.text}`,\n          options: task.question.options,\n        },\n      },\n    ];\n    if (needsHumanReplyTo !== undefined) {\n      events.push({\n        ...common,\n        eventId: `needs-human:${task.id}:${task.attempt}`,\n        replyTo: needsHumanReplyTo,\n        outcome: \"needs_human\",\n        data: {\n          requestedAction: action.length > 2000 ? `${action.slice(0, 2000)}…` : action,\n          message: `${reference}\\nReply destination: ${task.replyTo.channel} ${task.replyTo.address}\\n${instructions}\\nReplies in this notification DM do not answer the question.`,\n          options: task.question.options,\n          questionAttempt: task.attempt,\n          ...(task.parentTaskId === undefined ? {} : { parentTaskId: task.parentTaskId }),\n          replyChannel: task.replyTo.channel,\n          replyAddress: task.replyTo.address,\n        },\n      });\n    }\n    return events;\n  }\n\n  return {\n    questionEvents,\n    reconcile: createTaskCommunicationReconciler<SoftwareDevelopmentTaskCommunicationStores>({\n      question: questionEvents,\n      async lifecycle({ stores, tasks, task, receipt }) {\n        if (receipt.state === \"succeeded\" && task.changeId !== undefined) {\n          if (\n            task.work.route?.id !== \"code-review\" ||\n            task.work.route.version !== 1 ||\n            task.origin.operator === undefined\n          )\n            return [];\n          const output = reviewOutputSchema.parse(task.workResult?.output);\n          const change = await stores.changes.get(task.changeId);\n          if (change === null) throw new Error(`Review ${task.id} references a missing Change.`);\n          const findings =\n            output.findingCount === 0\n              ? output.verdict === \"request_changes\"\n                ? \"Changes requested.\"\n                : output.review?.state === \"APPROVED\"\n                  ? \"Approved. No issues found.\"\n                  : \"No issues found.\"\n              : `${output.findingCount} finding${output.findingCount === 1 ? \"\" : \"s\"}.${output.verdict === \"request_changes\" ? \" Changes requested.\" : \"\"}`;\n          const event = eventFor(task, receipt);\n          return [\n            {\n              ...event,\n              data: {\n                ...event.data,\n                title: `Review complete for PR #${change.prNumber}`,\n                summary: findings,\n                url: output.review?.url ?? change.prUrl,\n              },\n            },\n          ];\n        }\n        const event =\n          task.kind === \"coordination\" &&\n          (receipt.state === \"succeeded\" || receipt.state === \"failed\")\n            ? await coordinationEvent(stores, tasks, task, receipt)\n            : eventFor(task, receipt);\n        return [event];\n      },\n    }),\n  };\n}\n\nfunction completionSummary(task: Task, receipt: Receipt): string {\n  const output = task.workResult?.output;\n  const fields =\n    typeof output === \"object\" && output !== null && !Array.isArray(output)\n      ? [\n          \"summary\" in output ? output.summary : undefined,\n          \"result\" in output ? output.result : undefined,\n        ]\n      : [output];\n  const summary = [...fields, receipt.reason].find(\n    (value): value is string => typeof value === \"string\" && value.trim().length > 0,\n  );\n  if (!summary) return \"Completed. No result summary was recorded; open the chat for details.\";\n  const text = summary.trim();\n  return text.length > 1000 ? `${text.slice(0, 997)}…` : text;\n}\n\nfunction eventFor(task: Task, receipt: Receipt): CommunicationEvent {\n  const common = {\n    eventId: `task-lifecycle:${receipt.receiptId}`,\n    repositoryIds: task.repositoryIds,\n    taskId: task.id,\n    ...(task.changeId === undefined ? {} : { changeId: task.changeId }),\n    replyTo: task.replyTo,\n  };\n  if (receipt.state === \"dispatched\" && receipt.phase === \"retry\") {\n    return {\n      ...common,\n      outcome: \"started\",\n      data: {\n        message: `Retry attempt ${receipt.attempt} started.${receipt.reason === undefined ? \"\" : ` ${receipt.reason}`}`,\n      },\n    };\n  }\n  if (receipt.state === \"failed\") {\n    let prefix = \"Work failed.\";\n    if (receipt.reason?.startsWith(\"launch failed\")) prefix = \"Work failed to start.\";\n    else if (receipt.phase === \"retry\") prefix = \"Retries exhausted.\";\n    return {\n      ...common,\n      outcome: \"failed\",\n      data: { reason: `${prefix}${receipt.reason === undefined ? \"\" : ` ${receipt.reason}`}` },\n    };\n  }\n  if (receipt.state === \"cancelled\") {\n    const prefix = receipt.phase === \"approval\" ? \"Request rejected.\" : \"Work cancelled.\";\n    return {\n      ...common,\n      outcome: \"cancelled\",\n      data: {\n        message: `${prefix}${receipt.reason === undefined ? \"\" : ` ${receipt.reason}`}`,\n        ...(receipt.phase === \"approval\" ? { approvalDecision: true } : {}),\n      },\n    };\n  }\n  if (receipt.state === \"succeeded\") {\n    return {\n      ...common,\n      outcome: \"succeeded\",\n      data: {\n        summary: completionSummary(task, receipt),\n        output: task.workResult?.output,\n      },\n    };\n  }\n  throw new Error(`Receipt ${receipt.receiptId} is not a communicable task lifecycle event.`);\n}\n\nasync function coordinationEvent(\n  stores: SoftwareDevelopmentTaskCommunicationStores,\n  tasks: readonly Task[],\n  parent: Task,\n  receipt: Receipt,\n): Promise<CommunicationEvent> {\n  const children = tasks.filter((task) => task.parentTaskId === parent.id);\n  const items = await Promise.all(\n    children.map(async (child) => {\n      const repository = await stores.repositories.get(child.repositoryIds[0]!);\n      const change = child.changeId === undefined ? null : await stores.changes.get(child.changeId);\n      return `${repository?.slug ?? child.repositoryIds[0]}: ${change?.prUrl ?? child.state}`;\n    }),\n  );\n  const event = eventFor(parent, receipt);\n  return {\n    ...event,\n    data: {\n      ...event.data,\n      summary:\n        receipt.state === \"succeeded\"\n          ? \"Coordinated work completed.\"\n          : \"Coordinated work failed in one or more repositories.\",\n      items,\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/presets/software-development.d.mts

@@ -0,0 +1,10 @@
+/// <reference types="node" />
+import { formatDeepsecScanBrief } from "./software-development/deepsec-brief.mjs";
+import { SoftwareDevelopmentRecoveryOptions, SoftwareDevelopmentRecoveryStores, StartSoftwareDevelopmentRecovery, StartSoftwareDevelopmentRecoveryInput, createSoftwareDevelopmentRecoveryLaunchers } from "./software-development/recovery.mjs";
+import { defaultSoftwareDevelopmentApprovalPolicy } from "./software-development/approval.mjs";
+import { softwareDevelopmentFinishTaskPolicy } from "./software-development/finish-task-policy.mjs";
+import { softwareDevelopmentDelegationPolicy } from "./software-development/eve-delegation-policy.mjs";
+import { SoftwareDevelopmentTools, SoftwareDevelopmentToolsOptions, SoftwareDevelopmentToolsStores, createSoftwareDevelopmentTools } from "./software-development/eve.mjs";
+import { SoftwareDevelopmentTaskCommunication, SoftwareDevelopmentTaskCommunicationOptions, SoftwareDevelopmentTaskCommunicationStores, createSoftwareDevelopmentTaskCommunication } from "./software-development/task-communication.mjs";
+import { DispatchSoftwareDevelopmentWorkOptions, DispatchSoftwareDevelopmentWorkResult, SoftwareDevelopmentDispatchStores, dispatchSoftwareDevelopmentWork } from "./software-development/dispatch.mjs";
+export { type DispatchSoftwareDevelopmentWorkOptions, type DispatchSoftwareDevelopmentWorkResult, type SoftwareDevelopmentDispatchStores, type SoftwareDevelopmentRecoveryOptions, type SoftwareDevelopmentRecoveryStores, type SoftwareDevelopmentTaskCommunication, type SoftwareDevelopmentTaskCommunicationOptions, type SoftwareDevelopmentTaskCommunicationStores, type SoftwareDevelopmentTools, type SoftwareDevelopmentToolsOptions, type SoftwareDevelopmentToolsStores, type StartSoftwareDevelopmentRecovery, type StartSoftwareDevelopmentRecoveryInput, createSoftwareDevelopmentRecoveryLaunchers, createSoftwareDevelopmentTaskCommunication, createSoftwareDevelopmentTools, defaultSoftwareDevelopmentApprovalPolicy, dispatchSoftwareDevelopmentWork, formatDeepsecScanBrief, softwareDevelopmentDelegationPolicy, softwareDevelopmentFinishTaskPolicy };

package/dist/presets/software-development.mjs

@@ -0,0 +1,9 @@
+import { formatDeepsecScanBrief } from "./software-development/deepsec-brief.mjs";
+import { createSoftwareDevelopmentRecoveryLaunchers } from "./software-development/recovery.mjs";
+import { defaultSoftwareDevelopmentApprovalPolicy } from "./software-development/approval.mjs";
+import { softwareDevelopmentFinishTaskPolicy } from "./software-development/finish-task-policy.mjs";
+import { softwareDevelopmentDelegationPolicy } from "./software-development/eve-delegation-policy.mjs";
+import { createSoftwareDevelopmentTools } from "./software-development/eve.mjs";
+import { createSoftwareDevelopmentTaskCommunication } from "./software-development/task-communication.mjs";
+import { dispatchSoftwareDevelopmentWork } from "./software-development/dispatch.mjs";
+export { createSoftwareDevelopmentRecoveryLaunchers, createSoftwareDevelopmentTaskCommunication, createSoftwareDevelopmentTools, defaultSoftwareDevelopmentApprovalPolicy, dispatchSoftwareDevelopmentWork, formatDeepsecScanBrief, softwareDevelopmentDelegationPolicy, softwareDevelopmentFinishTaskPolicy };

package/dist/pull-requests/contracts.d.mts

@@ -0,0 +1,72 @@
+import { RepositoryId, TaskId } from "../schema/id.mjs";
+import { AgentSessionId } from "../schema/session.mjs";
+//#region src/pull-requests/contracts.d.ts
+/** Human-facing title and description for a new draft pull request. */
+interface OpenPullRequestInput {
+  title: string;
+  body: string;
+}
+/** Publication state requested when pushing the current committed checkpoint. */
+interface PushCheckpointInput {
+  /** Mark the pull request ready for review once this checkpoint lands. */
+  ready: boolean;
+}
+/** Pull-request identity and checkpoint details returned after publication. */
+interface PublishedPullRequest {
+  prNumber: number;
+  prUrl: string;
+  branch: string;
+  changedFiles: number;
+  draft: boolean;
+}
+/** Existing open pull request owned by a durable Task branch. */
+interface TaskPullRequest {
+  prNumber: number;
+  prUrl: string;
+  branch: string;
+}
+/** Open pull-request metadata used to detect work already in progress. */
+interface OpenPullRequest {
+  prNumber: number;
+  prUrl: string;
+  title: string;
+  author: string;
+  headBranch: string;
+  draft: boolean;
+}
+/** Durable Task or operator session that owns a publication branch. */
+type PullRequestPublicationOwner = TaskId | {
+  sessionId: AgentSessionId;
+};
+/** Task, repository, and pull request asserted before a workflow records a Change. */
+interface PullRequestPublicationGateInput {
+  taskId: TaskId;
+  repositoryId: RepositoryId;
+  prNumber: number;
+  prUrl: string;
+}
+/** Machine-readable reason a pull request failed the publication gate. */
+type PullRequestPublicationGateFailureCode = "repository_mismatch" | "task_not_found" | "change_not_found" | "linked_change_mismatch" | "repository_lookup_failed" | "authentication_failed" | "pull_request_not_found" | "pull_request_lookup_failed" | "pull_request_url_mismatch" | "pull_request_closed" | "pull_request_branch_mismatch" | "pull_request_draft";
+/** Successful validation that a pull request belongs to the supplied Task and Change. */
+interface PullRequestPublicationGateSuccess {
+  ok: true;
+}
+/** Bounded refusal from the pull-request publication gate. */
+interface PullRequestPublicationGateFailure {
+  ok: false;
+  code: PullRequestPublicationGateFailureCode;
+  reason: string;
+}
+/** Fail-closed result of validating a pull request against its owning Task and Change. */
+type PullRequestPublicationGateResult = PullRequestPublicationGateSuccess | PullRequestPublicationGateFailure;
+/** Metadata-only label mutation supported for a pull request. */
+type PullRequestLabelAction = "add" | "remove";
+/** Pull-request identity and resulting label set after a label mutation. */
+interface PullRequestLabelResult {
+  prNumber: number;
+  prUrl: string;
+  labels: readonly string[];
+}
+//#endregion
+export { OpenPullRequest, OpenPullRequestInput, PublishedPullRequest, PullRequestLabelAction, PullRequestLabelResult, PullRequestPublicationGateFailure, PullRequestPublicationGateFailureCode, PullRequestPublicationGateInput, PullRequestPublicationGateResult, PullRequestPublicationGateSuccess, PullRequestPublicationOwner, PushCheckpointInput, TaskPullRequest };
+//# sourceMappingURL=contracts.d.mts.map

package/dist/pull-requests/eve-fetch.d.mts

@@ -0,0 +1,57 @@
+import { FactoryStores } from "../store/engine.mjs";
+import { GitHubGitTransport } from "../github-transfer.mjs";
+import { z } from "zod";
+import { ToolContext, ToolDefinition } from "eve/tools";
+//#region src/pull-requests/eve-fetch.d.ts
+/** Change, repository, and Task capabilities required by the trusted pull-request fetch tool. */
+type GitHubFetchPullRequestToolStores = Pick<FactoryStores, "changes" | "repositories" | "tasks">;
+/** Validates the Change identity supplied to the trusted pull-request fetch tool. */
+declare const gitHubFetchPullRequestInputSchema: z.ZodObject<{
+  changeId: z.ZodType<`chg_${string}`, string, z.core.$ZodTypeInternals<`chg_${string}`, string>>;
+}, z.core.$strip>;
+/** Change identity supplied to the trusted pull-request fetch tool. */
+type GitHubFetchPullRequestInput = z.infer<typeof gitHubFetchPullRequestInputSchema>;
+/** Stores, Git credential boundary, and checkout used to construct a pull-request fetch tool. */
+interface GitHubFetchPullRequestToolOptions {
+  stores: GitHubFetchPullRequestToolStores;
+  /** Fetches Git objects outside the agent sandbox with read-only credentials. */
+  git: GitHubGitTransport;
+  /** Path of the checkout inside the sandbox. Defaults to `repo`. */
+  repoPath?: string;
+}
+/** Machine-readable reason a trusted pull-request fetch did not complete. */
+type GitHubFetchPullRequestFailureCode = "change_not_found" | "change_not_owned_by_task" | "change_not_reviewable" | "repository_not_found" | "repository_disabled" | "git_fetch_failed" | "merge_base_failed";
+/** Bounded refusal returned when a trusted pull-request fetch cannot complete. */
+interface GitHubFetchPullRequestFailure {
+  fetched: false;
+  code: GitHubFetchPullRequestFailureCode;
+  reason: string;
+}
+/** Exact pull-request revision and diff context produced by a trusted fetch. */
+interface GitHubFetchPullRequestSuccess {
+  fetched: true;
+  prNumber: number;
+  prUrl: string;
+  branch: string;
+  headSha: string;
+  baseBranch: string;
+  baseSha: string;
+  mergeBaseSha: string;
+  diffCommand: string;
+}
+/** The refusal or exact pull-request revision and diff context produced by a trusted fetch. */
+type GitHubFetchPullRequestResult = GitHubFetchPullRequestFailure | GitHubFetchPullRequestSuccess;
+/** Eve tool that fetches the exact pull-request revision linked to the current Task. */
+interface GitHubFetchPullRequestTool extends ToolDefinition<GitHubFetchPullRequestInput, GitHubFetchPullRequestResult> {
+  execute(input: GitHubFetchPullRequestInput, ctx: ToolContext): Promise<GitHubFetchPullRequestResult>;
+}
+/**
+ * Create the verifier's tool for fetching the change under review. The sandbox has no
+ * GitHub credential. A separate trusted transport fetches Git objects;
+ * only a credential-free bundle enters the agent sandbox. The pull request number and repository come from the
+ * change record, never from the agent.
+ */
+declare function createGitHubFetchPullRequestTool(input: GitHubFetchPullRequestToolOptions): GitHubFetchPullRequestTool;
+//#endregion
+export { GitHubFetchPullRequestFailure, GitHubFetchPullRequestFailureCode, GitHubFetchPullRequestInput, GitHubFetchPullRequestResult, GitHubFetchPullRequestSuccess, GitHubFetchPullRequestTool, GitHubFetchPullRequestToolOptions, GitHubFetchPullRequestToolStores, createGitHubFetchPullRequestTool, gitHubFetchPullRequestInputSchema };
+//# sourceMappingURL=eve-fetch.d.mts.map

package/dist/pull-requests/eve-fetch.mjs

@@ -0,0 +1,151 @@
+import { changeIdSchema } from "../schema/id.mjs";
+import { requireTaskIdForSession } from "../eve/task-session.mjs";
+import { requireTaskExecution } from "../eve/task-execution.mjs";
+import { fetchGitHubRefs, quoteShellArgument, runSandboxCommand } from "../github-transfer.mjs";
+import { z } from "zod";
+import { defineTool } from "eve/tools";
+//#region src/pull-requests/eve-fetch.ts
+/** Validates the Change identity supplied to the trusted pull-request fetch tool. */
+const gitHubFetchPullRequestInputSchema = z.object({ changeId: changeIdSchema.describe("The Change linked to your Task, returned by get_task.") });
+function authorizeTaskChange(task, change) {
+	if (task.changeId !== void 0 && task.changeId !== change.id) return {
+		fetched: false,
+		code: "change_not_owned_by_task",
+		reason: `change ${change.id} is not linked to task ${task.id}`
+	};
+	if (!task.repositoryIds.includes(change.repositoryId)) return {
+		fetched: false,
+		code: "change_not_owned_by_task",
+		reason: `change ${change.id} belongs to repository ${change.repositoryId}, outside task ${task.id}'s repository scope`
+	};
+	return null;
+}
+/**
+* Create the verifier's tool for fetching the change under review. The sandbox has no
+* GitHub credential. A separate trusted transport fetches Git objects;
+* only a credential-free bundle enters the agent sandbox. The pull request number and repository come from the
+* change record, never from the agent.
+*/
+function createGitHubFetchPullRequestTool(input) {
+	const { stores } = input;
+	const repoPath = input.repoPath ?? "repo";
+	return defineTool({
+		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: gitHubFetchPullRequestInputSchema,
+		async execute({ changeId }, ctx) {
+			const taskId = requireTaskIdForSession(ctx.session?.auth.initiator);
+			let task = await requireTaskExecution(stores, ctx, taskId);
+			const change = await stores.changes.get(changeId);
+			if (change === null) return {
+				fetched: false,
+				code: "change_not_found",
+				reason: `change ${changeId} does not exist`
+			};
+			const authorizationFailure = authorizeTaskChange(task, change);
+			if (authorizationFailure !== null) return authorizationFailure;
+			if (change.state !== "verifying" && change.state !== "ready") return {
+				fetched: false,
+				code: "change_not_reviewable",
+				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,
+				code: "repository_not_found",
+				reason: `repository ${change.repositoryId} does not exist`
+			};
+			if (!repository.enabled) return {
+				fetched: false,
+				code: "repository_disabled",
+				reason: `repository ${change.repositoryId} is disabled`
+			};
+			const sandbox = await ctx.getSandbox();
+			const currentChange = await stores.changes.get(changeId);
+			if (currentChange === null) return {
+				fetched: false,
+				code: "change_not_found",
+				reason: `change ${changeId} does not exist`
+			};
+			if (currentChange.state !== "verifying" && currentChange.state !== "ready") return {
+				fetched: false,
+				code: "change_not_reviewable",
+				reason: `change is ${currentChange.state}, not open for review; nothing to fetch`
+			};
+			const currentRepository = await stores.repositories.get(currentChange.repositoryId);
+			if (currentRepository === null) return {
+				fetched: false,
+				code: "repository_not_found",
+				reason: `repository ${currentChange.repositoryId} does not exist`
+			};
+			if (!currentRepository.enabled) return {
+				fetched: false,
+				code: "repository_disabled",
+				reason: `repository ${currentChange.repositoryId} is disabled`
+			};
+			task = await requireTaskExecution(stores, ctx, taskId);
+			const currentAuthorizationFailure = authorizeTaskChange(task, currentChange);
+			if (currentAuthorizationFailure !== null) return currentAuthorizationFailure;
+			const tracking = `refs/remotes/origin/pr-${currentChange.prNumber}`;
+			const baseTracking = `refs/remotes/origin/${currentRepository.defaultBranch}`;
+			const git = [
+				"git",
+				"-C",
+				repoPath
+			].map(quoteShellArgument).join(" ");
+			try {
+				await fetchGitHubRefs({
+					sandbox,
+					transport: input.git,
+					repository: currentRepository.slug,
+					refs: [{
+						remote: `refs/heads/${currentRepository.defaultBranch}`,
+						local: baseTracking
+					}, {
+						remote: `refs/pull/${currentChange.prNumber}/head`,
+						local: tracking
+					}],
+					repositoryPath: repoPath
+				});
+				await runSandboxCommand(sandbox, [
+					"git",
+					"-C",
+					repoPath,
+					"checkout",
+					"-B",
+					"pr",
+					tracking
+				]);
+			} catch (error) {
+				return {
+					fetched: false,
+					code: "git_fetch_failed",
+					reason: `git fetch of pull request ${currentChange.prNumber} failed: ${error instanceof Error ? error.message : "Git transfer failed"}`
+				};
+			}
+			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,
+				code: "merge_base_failed",
+				reason: `could not determine the pull request merge base: ${(mergeBase.stderr ?? "").trim()}`
+			};
+			const mergeBaseSha = mergeBase.stdout.trim();
+			return {
+				fetched: true,
+				prNumber: currentChange.prNumber,
+				prUrl: currentChange.prUrl,
+				branch: "pr",
+				headSha: head.stdout.trim(),
+				baseBranch: currentRepository.defaultBranch,
+				baseSha: base.stdout.trim(),
+				mergeBaseSha,
+				diffCommand: `${git} diff ${mergeBaseSha}..pr`
+			};
+		}
+	});
+}
+//#endregion
+export { createGitHubFetchPullRequestTool, gitHubFetchPullRequestInputSchema };
+
+//# sourceMappingURL=eve-fetch.mjs.map

package/dist/pull-requests/eve-fetch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"eve-fetch.mjs","names":[],"sources":["../../src/pull-requests/eve-fetch.ts"],"sourcesContent":["import {\n  fetchGitHubRefs,\n  quoteShellArgument,\n  runSandboxCommand,\n  type GitHubGitTransport,\n} from \"../github-transfer\";\nimport { defineTool, type ToolContext, type ToolDefinition } from \"eve/tools\";\nimport { z } from \"zod\";\nimport { changeIdSchema } from \"../schema/id\";\nimport type { Change } from \"../schema/change\";\nimport type { Task } from \"../schema/task\";\nimport type { FactoryStores } from \"../store/engine\";\nimport { requireTaskExecution } from \"../eve/task-execution\";\nimport { requireTaskIdForSession } from \"../eve/task-session\";\n\n/** Change, repository, and Task capabilities required by the trusted pull-request fetch tool. */\nexport type GitHubFetchPullRequestToolStores = Pick<\n  FactoryStores,\n  \"changes\" | \"repositories\" | \"tasks\"\n>;\n\n/** Validates the Change identity supplied to the trusted pull-request fetch tool. */\nexport const gitHubFetchPullRequestInputSchema = z.object({\n  changeId: changeIdSchema.describe(\"The Change linked to your Task, returned by get_task.\"),\n});\n\n/** Change identity supplied to the trusted pull-request fetch tool. */\nexport type GitHubFetchPullRequestInput = z.infer<typeof gitHubFetchPullRequestInputSchema>;\n\n/** Stores, Git credential boundary, and checkout used to construct a pull-request fetch tool. */\nexport interface GitHubFetchPullRequestToolOptions {\n  stores: GitHubFetchPullRequestToolStores;\n  /** Fetches Git objects outside the agent sandbox with read-only credentials. */\n  git: GitHubGitTransport;\n  /** Path of the checkout inside the sandbox. Defaults to `repo`. */\n  repoPath?: string;\n}\n\n/** Machine-readable reason a trusted pull-request fetch did not complete. */\nexport type GitHubFetchPullRequestFailureCode =\n  | \"change_not_found\"\n  | \"change_not_owned_by_task\"\n  | \"change_not_reviewable\"\n  | \"repository_not_found\"\n  | \"repository_disabled\"\n  | \"git_fetch_failed\"\n  | \"merge_base_failed\";\n\n/** Bounded refusal returned when a trusted pull-request fetch cannot complete. */\nexport interface GitHubFetchPullRequestFailure {\n  fetched: false;\n  code: GitHubFetchPullRequestFailureCode;\n  reason: string;\n}\n\n/** Exact pull-request revision and diff context produced by a trusted fetch. */\nexport interface GitHubFetchPullRequestSuccess {\n  fetched: true;\n  prNumber: number;\n  prUrl: string;\n  branch: string;\n  headSha: string;\n  baseBranch: string;\n  baseSha: string;\n  mergeBaseSha: string;\n  diffCommand: string;\n}\n\n/** The refusal or exact pull-request revision and diff context produced by a trusted fetch. */\nexport type GitHubFetchPullRequestResult =\n  | GitHubFetchPullRequestFailure\n  | GitHubFetchPullRequestSuccess;\n\n/** Eve tool that fetches the exact pull-request revision linked to the current Task. */\nexport interface GitHubFetchPullRequestTool extends ToolDefinition<\n  GitHubFetchPullRequestInput,\n  GitHubFetchPullRequestResult\n> {\n  execute(\n    input: GitHubFetchPullRequestInput,\n    ctx: ToolContext,\n  ): Promise<GitHubFetchPullRequestResult>;\n}\n\nfunction authorizeTaskChange(task: Task, change: Change): GitHubFetchPullRequestFailure | null {\n  if (task.changeId !== undefined && task.changeId !== change.id) {\n    return {\n      fetched: false,\n      code: \"change_not_owned_by_task\",\n      reason: `change ${change.id} is not linked to task ${task.id}`,\n    };\n  }\n  if (!task.repositoryIds.includes(change.repositoryId)) {\n    return {\n      fetched: false,\n      code: \"change_not_owned_by_task\",\n      reason: `change ${change.id} belongs to repository ${change.repositoryId}, outside task ${task.id}'s repository scope`,\n    };\n  }\n  return null;\n}\n\n/**\n * Create the verifier's tool for fetching the change under review. The sandbox has no\n * GitHub credential. A separate trusted transport fetches Git objects;\n * only a credential-free bundle enters the agent sandbox. The pull request number and repository come from the\n * change record, never from the agent.\n */\nexport function createGitHubFetchPullRequestTool(\n  input: GitHubFetchPullRequestToolOptions,\n): GitHubFetchPullRequestTool {\n  const { stores } = input;\n  const repoPath = input.repoPath ?? \"repo\";\n  return defineTool({\n    description:\n      \"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.\",\n    inputSchema: gitHubFetchPullRequestInputSchema,\n    async execute({ changeId }, ctx): Promise<GitHubFetchPullRequestResult> {\n      const taskId = requireTaskIdForSession(ctx.session?.auth.initiator);\n      let task = await requireTaskExecution(stores, ctx, taskId);\n      const change = await stores.changes.get(changeId);\n      if (change === null) {\n        return {\n          fetched: false,\n          code: \"change_not_found\",\n          reason: `change ${changeId} does not exist`,\n        };\n      }\n      const authorizationFailure = authorizeTaskChange(task, change);\n      if (authorizationFailure !== null) return authorizationFailure;\n      if (change.state !== \"verifying\" && change.state !== \"ready\") {\n        return {\n          fetched: false,\n          code: \"change_not_reviewable\",\n          reason: `change is ${change.state}, not open for review; nothing to fetch`,\n        };\n      }\n      const repository = await stores.repositories.get(change.repositoryId);\n      if (repository === null) {\n        return {\n          fetched: false,\n          code: \"repository_not_found\",\n          reason: `repository ${change.repositoryId} does not exist`,\n        };\n      }\n      if (!repository.enabled) {\n        return {\n          fetched: false,\n          code: \"repository_disabled\",\n          reason: `repository ${change.repositoryId} is disabled`,\n        };\n      }\n\n      // Fetch into a remote-tracking ref (never the checked-out branch, which\n      // git refuses to update), then move the local `pr` branch onto it so a\n      // repeated call picks up a force-pushed head.\n      const sandbox = await ctx.getSandbox();\n      const currentChange = await stores.changes.get(changeId);\n      if (currentChange === null) {\n        return {\n          fetched: false,\n          code: \"change_not_found\",\n          reason: `change ${changeId} does not exist`,\n        };\n      }\n      if (currentChange.state !== \"verifying\" && currentChange.state !== \"ready\") {\n        return {\n          fetched: false,\n          code: \"change_not_reviewable\",\n          reason: `change is ${currentChange.state}, not open for review; nothing to fetch`,\n        };\n      }\n      const currentRepository = await stores.repositories.get(currentChange.repositoryId);\n      if (currentRepository === null) {\n        return {\n          fetched: false,\n          code: \"repository_not_found\",\n          reason: `repository ${currentChange.repositoryId} does not exist`,\n        };\n      }\n      if (!currentRepository.enabled) {\n        return {\n          fetched: false,\n          code: \"repository_disabled\",\n          reason: `repository ${currentChange.repositoryId} is disabled`,\n        };\n      }\n      task = await requireTaskExecution(stores, ctx, taskId);\n      const currentAuthorizationFailure = authorizeTaskChange(task, currentChange);\n      if (currentAuthorizationFailure !== null) return currentAuthorizationFailure;\n      const tracking = `refs/remotes/origin/pr-${currentChange.prNumber}`;\n      const baseTracking = `refs/remotes/origin/${currentRepository.defaultBranch}`;\n      const git = [\"git\", \"-C\", repoPath].map(quoteShellArgument).join(\" \");\n      try {\n        await fetchGitHubRefs({\n          sandbox,\n          transport: input.git,\n          repository: currentRepository.slug,\n          refs: [\n            { remote: `refs/heads/${currentRepository.defaultBranch}`, local: baseTracking },\n            { remote: `refs/pull/${currentChange.prNumber}/head`, local: tracking },\n          ],\n          repositoryPath: repoPath,\n        });\n        await runSandboxCommand(sandbox, [\"git\", \"-C\", repoPath, \"checkout\", \"-B\", \"pr\", tracking]);\n      } catch (error) {\n        return {\n          fetched: false,\n          code: \"git_fetch_failed\",\n          reason: `git fetch of pull request ${currentChange.prNumber} failed: ${error instanceof Error ? error.message : \"Git transfer failed\"}`,\n        };\n      }\n\n      const head = await sandbox.run({ command: `${git} rev-parse HEAD` });\n      const base = await sandbox.run({ command: `${git} rev-parse ${baseTracking}` });\n      const mergeBase = await sandbox.run({ command: `${git} merge-base ${baseTracking} pr` });\n      if (typeof mergeBase.exitCode === \"number\" && mergeBase.exitCode !== 0) {\n        return {\n          fetched: false,\n          code: \"merge_base_failed\",\n          reason: `could not determine the pull request merge base: ${(mergeBase.stderr ?? \"\").trim()}`,\n        };\n      }\n      const mergeBaseSha = mergeBase.stdout.trim();\n      return {\n        fetched: true,\n        prNumber: currentChange.prNumber,\n        prUrl: currentChange.prUrl,\n        branch: \"pr\",\n        headSha: head.stdout.trim(),\n        baseBranch: currentRepository.defaultBranch,\n        baseSha: base.stdout.trim(),\n        mergeBaseSha,\n        diffCommand: `${git} diff ${mergeBaseSha}..pr`,\n      };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/pull-requests/github-label-manager.d.mts

@@ -0,0 +1,27 @@
+import { TaskId } from "../schema/id.mjs";
+import { Repository } from "../schema/repository.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { PullRequestLabelAction, PullRequestLabelResult } from "./contracts.mjs";
+import { GitHubPullRequestPublisher, GitHubPullRequestPublisherOptions } from "./github-publisher.mjs";
+//#region src/pull-requests/github-label-manager.d.ts
+/** Task and Change authority required to mutate labels on an owned pull request. */
+interface GitHubPullRequestLabelManagerOptions extends GitHubPullRequestPublisherOptions {
+  stores: Pick<FactoryStores, "tasks" | "changes">;
+  requireTaskPullRequest?: GitHubPullRequestPublisher["requireTaskPullRequest"];
+}
+/** Task-owned pull request and label mutation to apply. */
+interface ManageGitHubPullRequestLabelInput {
+  repository: Repository;
+  taskId: TaskId;
+  action: PullRequestLabelAction;
+  label: string;
+}
+/** Task-aware label operation constrained to the workflow's owned pull request. */
+interface GitHubPullRequestLabelManager {
+  managePullRequestLabel(input: ManageGitHubPullRequestLabelInput): Promise<PullRequestLabelResult>;
+}
+/** Create task-aware label operations for pull requests owned by the supplied software workflow. */
+declare function createGitHubPullRequestLabelManager(options: GitHubPullRequestLabelManagerOptions): GitHubPullRequestLabelManager;
+//#endregion
+export { GitHubPullRequestLabelManager, GitHubPullRequestLabelManagerOptions, ManageGitHubPullRequestLabelInput, createGitHubPullRequestLabelManager };
+//# sourceMappingURL=github-label-manager.d.mts.map

package/dist/pull-requests/github-label-manager.mjs

@@ -0,0 +1,40 @@
+import { addLabel, removeLabel } from "../github.mjs";
+import { createGitHubPullRequestPublisher } from "./github-publisher.mjs";
+//#region src/pull-requests/github-label-manager.ts
+/** Create task-aware label operations for pull requests owned by the supplied software workflow. */
+function createGitHubPullRequestLabelManager(options) {
+	const requireTaskPullRequest = options.requireTaskPullRequest ?? createGitHubPullRequestPublisher(options).requireTaskPullRequest;
+	async function managePullRequestLabel(input) {
+		const task = await options.stores.tasks.get(input.taskId);
+		if (task === null) throw new Error(`task ${input.taskId} does not exist`);
+		if (task.repositoryIds.length !== 1 || task.repositoryIds[0] !== input.repository.id) throw new Error(`task ${input.taskId} does not identify repository ${input.repository.id}`);
+		const change = task.changeId === void 0 ? null : await options.stores.changes.get(task.changeId);
+		if (task.changeId !== void 0 && change === null) throw new Error(`change ${task.changeId} linked to task ${input.taskId} does not exist`);
+		if (change !== null && (change.repositoryId !== input.repository.id || change.state !== "verifying" && change.state !== "ready")) throw new Error(`change ${change.id} is not an open pull request in repository ${input.repository.id}`);
+		const pull = change === null ? await requireTaskPullRequest({
+			repository: input.repository,
+			taskId: input.taskId
+		}) : {
+			prNumber: change.prNumber,
+			prUrl: change.prUrl
+		};
+		const token = await options.tokenForRepository(input.repository.slug);
+		const labels = await (input.action === "add" ? addLabel : removeLabel)({
+			repository: input.repository.slug,
+			token,
+			fetch: options.fetch,
+			pullRequestNumber: pull.prNumber,
+			label: input.label
+		});
+		return {
+			prNumber: pull.prNumber,
+			prUrl: pull.prUrl,
+			labels
+		};
+	}
+	return Object.freeze({ managePullRequestLabel });
+}
+//#endregion
+export { createGitHubPullRequestLabelManager };
+
+//# sourceMappingURL=github-label-manager.mjs.map

package/dist/pull-requests/github-label-manager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-label-manager.mjs","names":[],"sources":["../../src/pull-requests/github-label-manager.ts"],"sourcesContent":["import { addLabel, removeLabel } from \"../github\";\nimport type { TaskId } from \"../schema/id\";\nimport type { Repository } from \"../schema/repository\";\nimport type { FactoryStores } from \"../store/engine\";\nimport type { PullRequestLabelAction, PullRequestLabelResult } from \"./contracts\";\nimport {\n  createGitHubPullRequestPublisher,\n  type GitHubPullRequestPublisher,\n  type GitHubPullRequestPublisherOptions,\n} from \"./github-publisher\";\n\n/** Task and Change authority required to mutate labels on an owned pull request. */\nexport interface GitHubPullRequestLabelManagerOptions extends GitHubPullRequestPublisherOptions {\n  stores: Pick<FactoryStores, \"tasks\" | \"changes\">;\n  requireTaskPullRequest?: GitHubPullRequestPublisher[\"requireTaskPullRequest\"];\n}\n\n/** Task-owned pull request and label mutation to apply. */\nexport interface ManageGitHubPullRequestLabelInput {\n  repository: Repository;\n  taskId: TaskId;\n  action: PullRequestLabelAction;\n  label: string;\n}\n\n/** Task-aware label operation constrained to the workflow's owned pull request. */\nexport interface GitHubPullRequestLabelManager {\n  managePullRequestLabel(input: ManageGitHubPullRequestLabelInput): Promise<PullRequestLabelResult>;\n}\n\n/** Create task-aware label operations for pull requests owned by the supplied software workflow. */\nexport function createGitHubPullRequestLabelManager(\n  options: GitHubPullRequestLabelManagerOptions,\n): GitHubPullRequestLabelManager {\n  const requireTaskPullRequest =\n    options.requireTaskPullRequest ??\n    createGitHubPullRequestPublisher(options).requireTaskPullRequest;\n\n  async function managePullRequestLabel(\n    input: ManageGitHubPullRequestLabelInput,\n  ): Promise<PullRequestLabelResult> {\n    const task = await options.stores.tasks.get(input.taskId);\n    if (task === null) throw new Error(`task ${input.taskId} does not exist`);\n    if (task.repositoryIds.length !== 1 || task.repositoryIds[0] !== input.repository.id) {\n      throw new Error(`task ${input.taskId} does not identify repository ${input.repository.id}`);\n    }\n    const change =\n      task.changeId === undefined ? null : await options.stores.changes.get(task.changeId);\n    if (task.changeId !== undefined && change === null) {\n      throw new Error(`change ${task.changeId} linked to task ${input.taskId} does not exist`);\n    }\n    if (\n      change !== null &&\n      (change.repositoryId !== input.repository.id ||\n        (change.state !== \"verifying\" && change.state !== \"ready\"))\n    ) {\n      throw new Error(\n        `change ${change.id} is not an open pull request in repository ${input.repository.id}`,\n      );\n    }\n    const pull =\n      change === null\n        ? await requireTaskPullRequest({ repository: input.repository, taskId: input.taskId })\n        : { prNumber: change.prNumber, prUrl: change.prUrl };\n    const token = await options.tokenForRepository(input.repository.slug);\n    const labels = await (input.action === \"add\" ? addLabel : removeLabel)({\n      repository: input.repository.slug,\n      token,\n      fetch: options.fetch,\n      pullRequestNumber: pull.prNumber,\n      label: input.label,\n    });\n    return { prNumber: pull.prNumber, prUrl: pull.prUrl, labels };\n  }\n\n  return Object.freeze({ managePullRequestLabel });\n}\n"],"mappings":";;;;AA+BA,SAAgB,oCACd,SAC+B;CAC/B,MAAM,yBACJ,QAAQ,0BACR,iCAAiC,OAAO,CAAC,CAAC;CAE5C,eAAe,uBACb,OACiC;EACjC,MAAM,OAAO,MAAM,QAAQ,OAAO,MAAM,IAAI,MAAM,MAAM;EACxD,IAAI,SAAS,MAAM,MAAM,IAAI,MAAM,QAAQ,MAAM,OAAO,gBAAgB;EACxE,IAAI,KAAK,cAAc,WAAW,KAAK,KAAK,cAAc,OAAO,MAAM,WAAW,IAChF,MAAM,IAAI,MAAM,QAAQ,MAAM,OAAO,gCAAgC,MAAM,WAAW,IAAI;EAE5F,MAAM,SACJ,KAAK,aAAa,KAAA,IAAY,OAAO,MAAM,QAAQ,OAAO,QAAQ,IAAI,KAAK,QAAQ;EACrF,IAAI,KAAK,aAAa,KAAA,KAAa,WAAW,MAC5C,MAAM,IAAI,MAAM,UAAU,KAAK,SAAS,kBAAkB,MAAM,OAAO,gBAAgB;EAEzF,IACE,WAAW,SACV,OAAO,iBAAiB,MAAM,WAAW,MACvC,OAAO,UAAU,eAAe,OAAO,UAAU,UAEpD,MAAM,IAAI,MACR,UAAU,OAAO,GAAG,6CAA6C,MAAM,WAAW,IACpF;EAEF,MAAM,OACJ,WAAW,OACP,MAAM,uBAAuB;GAAE,YAAY,MAAM;GAAY,QAAQ,MAAM;EAAO,CAAC,IACnF;GAAE,UAAU,OAAO;GAAU,OAAO,OAAO;EAAM;EACvD,MAAM,QAAQ,MAAM,QAAQ,mBAAmB,MAAM,WAAW,IAAI;EACpE,MAAM,SAAS,OAAO,MAAM,WAAW,QAAQ,WAAW,YAAA,CAAa;GACrE,YAAY,MAAM,WAAW;GAC7B;GACA,OAAO,QAAQ;GACf,mBAAmB,KAAK;GACxB,OAAO,MAAM;EACf,CAAC;EACD,OAAO;GAAE,UAAU,KAAK;GAAU,OAAO,KAAK;GAAO;EAAO;CAC9D;CAEA,OAAO,OAAO,OAAO,EAAE,uBAAuB,CAAC;AACjD"}