@vercel/factory 0.0.13 → 0.0.15

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 type { CommunicationEvent } from \"../../schema/communication\";\nimport type { ReplyTo } from \"../../schema/common\";\nimport type { Receipt } from \"../../schema/receipt\";\nimport type { Task } from \"../../schema/task\";\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  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\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    channel: \"slack\",\n    address: \"owner\",\n  };\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 instructions =\n      task.replyTo.channel === \"slack\"\n        ? \"To answer, reply in this thread and mention the Factory app.\"\n        : task.replyTo.channel === \"github\" && task.replyTo.address.includes(\"#\")\n          ? `To answer, comment on this issue starting with \\`${githubMention}\\`.`\n          : \"Answer in the original conversation.\";\n    const common = { repositoryIds: task.repositoryIds, taskId: task.id };\n    const action = task.needsHumanAction ?? task.question.text;\n    const apiInstructions =\n      task.replyTo.channel === \"api\"\n        ? `\\nOpen session ${task.replyTo.address} in your Factory client to answer.${/^ses_[a-z0-9]{6,64}$/u.test(task.replyTo.address) ? ` In Factory TUI: factory-tui --session ${task.replyTo.address}` : \"\"}`\n        : \"\";\n    return [\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        ...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}\\nOpen the original conversation to answer.${apiInstructions}\\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  }\n\n  return {\n    questionEvents,\n    reconcile: createTaskCommunicationReconciler<SoftwareDevelopmentTaskCommunicationStores>({\n      question: questionEvents,\n      async lifecycle({ stores, tasks, task, receipt }) {\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 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: receipt.reason ?? \"The task completed successfully.\",\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,9 @@
+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"}

package/dist/pull-requests/github-publisher.d.mts

@@ -0,0 +1,53 @@
+import { TaskId } from "../schema/id.mjs";
+import { Repository, RepositorySlug } from "../schema/repository.mjs";
+import { Change } from "../schema/change.mjs";
+import { FactoryStores } from "../store/engine.mjs";
+import { OpenPullRequestInput, PublishedPullRequest, PullRequestPublicationGateInput, PullRequestPublicationGateResult, PullRequestPublicationOwner, PushCheckpointInput, TaskPullRequest } from "./contracts.mjs";
+import { GitHubPublicationClient, GitHubPublicationClientOptions, SandboxGit } from "../github-publication.mjs";
+//#region src/pull-requests/github-publisher.d.ts
+/** Repository credential and client factories required by software publication. */
+interface GitHubPullRequestPublisherOptions {
+  tokenForRepository(repositorySlug: RepositorySlug): Promise<string>;
+  fetch?: typeof globalThis.fetch;
+  createClient?: (options: GitHubPublicationClientOptions) => GitHubPublicationClient;
+}
+/** Task- and session-aware operations for idempotent GitHub pull-request publication. */
+interface GitHubPullRequestPublisher {
+  requireTaskPullRequest(input: RequireTaskPullRequestInput): Promise<TaskPullRequest>;
+  openPullRequest(input: PublishGitHubPullRequestInput): Promise<PublishedPullRequest>;
+  pushCheckpoint(input: PushGitHubCheckpointInput): Promise<PublishedPullRequest>;
+}
+/** Repository and Task whose owned pull request must already exist. */
+interface RequireTaskPullRequestInput {
+  repository: Repository;
+  taskId: TaskId;
+}
+/** Sandbox checkout and publication request used to open a GitHub pull request. */
+interface PublishGitHubPullRequestInput {
+  sandbox: SandboxGit;
+  repository: Repository;
+  owner: PullRequestPublicationOwner;
+  pullRequest: OpenPullRequestInput;
+}
+/** Sandbox checkout and optional linked Change used to publish a checkpoint. */
+interface PushGitHubCheckpointInput {
+  sandbox: SandboxGit;
+  repository: Repository;
+  owner: PullRequestPublicationOwner;
+  checkpoint: PushCheckpointInput;
+  linkedChange?: Pick<Change, "prNumber" | "prUrl">;
+}
+/** Supplied software workflow for safe Task- and session-owned GitHub publication. */
+declare function createGitHubPullRequestPublisher(options: GitHubPullRequestPublisherOptions): GitHubPullRequestPublisher;
+/** Store and repository lookup dependencies for the pull-request publication gate. */
+interface GitHubPullRequestPublicationGateOptions extends GitHubPullRequestPublisherOptions {
+  stores: Pick<FactoryStores, "tasks" | "changes">;
+  repositoryForTask(taskId: TaskId): Promise<Repository>;
+}
+/** Validates that one pull request belongs to its exact GitHub Task and Change context. */
+type GitHubPullRequestPublicationGate = (input: PullRequestPublicationGateInput) => Promise<PullRequestPublicationGateResult>;
+/** Fail-closed gate for the pull request a supplied code-change workflow records. */
+declare function createGitHubPullRequestPublicationGate(options: GitHubPullRequestPublicationGateOptions): GitHubPullRequestPublicationGate;
+//#endregion
+export { GitHubPullRequestPublicationGate, GitHubPullRequestPublicationGateOptions, GitHubPullRequestPublisher, GitHubPullRequestPublisherOptions, PublishGitHubPullRequestInput, PushGitHubCheckpointInput, RequireTaskPullRequestInput, createGitHubPullRequestPublicationGate, createGitHubPullRequestPublisher };
+//# sourceMappingURL=github-publisher.d.mts.map