Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(self-modification): configure production proposals (#2870)

prha8e3ccfcb3241
diff --git a/packages/eve/package.json b/packages/eve/package.json
index cfcf3acef..7bbc01144 100644
--- a/packages/eve/package.json
+++ b/packages/eve/package.json
@@ -420,6 +420,12 @@
"types": "./dist/src/setup/index.d.ts",
"import": "./dist/src/setup/index.js",
"default": "./dist/src/setup/index.js"
+ },
+ "./self-modification/config": {
+ "eve-source": "./src/self-modification/config.ts",
+ "types": "./dist/src/self-modification/config.d.ts",
+ "import": "./dist/src/self-modification/config.js",
+ "default": "./dist/src/self-modification/config.js"
}
},
"publishConfig": {
diff --git a/packages/eve/src/self-modification/config.test.ts b/packages/eve/src/self-modification/config.test.ts
new file mode 100644
index 000000000..cf882e4ec
--- /dev/null
+++ b/packages/eve/src/self-modification/config.test.ts
@@ -0,0 +1,143 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { resolveSelfModificationConfig } from "./config.js";
+import { resolveGitHubCredential } from "./credentials.js";
+import { resolveSelfModificationMode } from "./mode.js";
+
+afterEach(() => {
+ delete process.env.EVE_DEV;
+ delete process.env.EVE_SELF_MODIFICATION_GITHUB_TOKEN;
+ delete process.env.VERCEL_ENV;
+});
+
+const deployed = {
+ deployed: {
+ source: { git: { directory: "apps/weather", repository: "github.com/vercel/eve" } },
+ target: { branch: "main" },
+ credentials: { pat: true },
+ },
+} as const;
+
+describe("self-modification deployed configuration", () => {
+ it("resolves a repository-root application", () => {
+ expect(
+ resolveSelfModificationConfig({
+ deployed: {
+ ...deployed.deployed,
+ source: { git: { ...deployed.deployed.source.git, directory: "." } },
+ },
+ }),
+ ).toMatchObject({
+ deployed: {
+ directory: ".",
+ repository: { owner: "vercel", repo: "eve" },
+ targetBranch: "main",
+ },
+ });
+ });
+
+ it("requires opting into the self-hosted PAT exception", () => {
+ expect(resolveSelfModificationConfig(deployed)).toMatchObject({
+ localEnabled: true,
+ deployed: { credentials: { kind: "pat" } },
+ });
+ expect(() =>
+ resolveSelfModificationConfig({
+ deployed: { ...deployed.deployed, credentials: undefined },
+ }),
+ ).toThrow("must explicitly configure");
+ });
+
+ it("resolves a Vercel Connect connector only in Vercel Production", () => {
+ const config = resolveSelfModificationConfig({
+ deployed: {
+ ...deployed.deployed,
+ credentials: { vercelConnect: { connector: "github/selfmod-vercel-eve" } },
+ },
+ });
+ expect(resolveSelfModificationMode(config)).toBe("disabled");
+ process.env.VERCEL_ENV = "production";
+ expect(resolveSelfModificationMode(config)).toBe("deployed");
+ });
+
+ it.each(["", "/agent", "agent/../other", "agent//other", "agent\\other"])(
+ "rejects unsafe application directories: %s",
+ (directory) => {
+ expect(() =>
+ resolveSelfModificationConfig({
+ deployed: {
+ ...deployed.deployed,
+ source: { git: { ...deployed.deployed.source.git, directory } },
+ },
+ }),
+ ).toThrow("safe repository-relative");
+ },
+ );
+
+ it("requires complete deployed configuration", () => {
+ expect(() =>
+ resolveSelfModificationConfig({ deployed: { source: deployed.deployed.source } } as never),
+ ).toThrow("both source and target");
+ });
+
+ it("rejects ambiguous or malformed credential configuration", () => {
+ expect(() =>
+ resolveSelfModificationConfig({
+ deployed: {
+ ...deployed.deployed,
+ credentials: { pat: true, vercelConnect: { connector: "github/example" } },
+ },
+ }),
+ ).toThrow("exactly one");
+ expect(() =>
+ resolveSelfModificationConfig({
+ deployed: { ...deployed.deployed, credentials: { pat: false } as never },
+ }),
+ ).toThrow("pat must be true");
+ });
+
+ it.each([
+ [null, "configuration must be an object"],
+ [{ local: null }, "local must be an object"],
+ [
+ { deployed: { source: null, target: deployed.deployed.target } },
+ "deployed.source must be an object",
+ ],
+ [
+ { deployed: { source: {}, target: deployed.deployed.target } },
+ "deployed.source.git must be an object",
+ ],
+ [
+ { deployed: { source: deployed.deployed.source, target: null } },
+ "deployed.target must be an object",
+ ],
+ ])("rejects malformed nested configuration", (config, message) => {
+ expect(() => resolveSelfModificationConfig(config as never)).toThrow(message);
+ });
+
+ it("rejects a fully qualified target ref", () => {
+ expect(() =>
+ resolveSelfModificationConfig({
+ deployed: { ...deployed.deployed, target: { branch: "refs/heads/main" } },
+ }),
+ ).toThrow("must be a branch name");
+ });
+
+ it("activates deployed while keeping local editing local", () => {
+ const config = resolveSelfModificationConfig(deployed);
+ expect(resolveSelfModificationMode(config)).toBe("deployed");
+ process.env.EVE_DEV = "1";
+ expect(resolveSelfModificationMode(config)).toBe("local");
+ });
+
+ it("resolves the GitHub token for each capability", async () => {
+ process.env.EVE_SELF_MODIFICATION_GITHUB_TOKEN = " secret-token ";
+ const repository = resolveSelfModificationConfig(deployed).deployed!.repository;
+ await expect(resolveGitHubCredential({ capability: "checkout", repository })).resolves.toBe(
+ "secret-token",
+ );
+ await expect(resolveGitHubCredential({ capability: "publish", repository })).resolves.toBe(
+ "secret-token",
+ );
+ });
+});
diff --git a/packages/eve/src/self-modification/config.ts b/packages/eve/src/self-modification/config.ts
new file mode 100644
index 000000000..10d6dc9a9
--- /dev/null
+++ b/packages/eve/src/self-modification/config.ts
@@ -0,0 +1,173 @@
+import { assertGitRef, assertRepositoryPart } from "./identifiers.js";
+
+export interface SelfModificationConfig {
+ readonly local?: { readonly enabled?: boolean };
+ readonly deployed?: {
+ readonly source: {
+ readonly git: {
+ /** GitHub repository in github.com/owner/repository form. */
+ readonly repository: string;
+ /** Application directory relative to the repository root. */
+ readonly directory: string;
+ };
+ };
+ readonly target: { readonly branch: string };
+ readonly credentials?: {
+ /** Ephemeral, repository-scoped GitHub App credentials from Vercel Connect. */
+ readonly vercelConnect?: { readonly connector: string };
+ /**
+ * Self-hosted exception. Reads `EVE_SELF_MODIFICATION_GITHUB_TOKEN` from
+ * the trusted deployment environment; never injects it into the sandbox.
+ */
+ readonly pat?: true;
+ };
+ };
+}
+
+export interface ResolvedSelfModificationConfig {
+ readonly localEnabled: boolean;
+ readonly deployed?: ResolvedDeployedSelfModificationConfig;
+}
+
+export interface ResolvedDeployedSelfModificationConfig {
+ readonly credentials: ResolvedGitHubCredentials;
+ readonly directory: string;
+ readonly repository: GitHubRepository;
+ readonly targetBranch: string;
+}
+
+export type ResolvedGitHubCredentials =
+ | { readonly kind: "pat" }
+ | { readonly connector: string; readonly kind: "vercel-connect" };
+
+export interface GitHubRepository {
+ readonly owner: string;
+ readonly repo: string;
+}
+
+/** Defines the policy shared by the self-modification agent, sandbox, and extension. */
+export function defineSelfModificationConfig(
+ config: SelfModificationConfig = {},
+): SelfModificationConfig {
+ resolveSelfModificationConfig(config);
+ return config;
+}
+
+export function resolveSelfModificationConfig(
+ config: SelfModificationConfig = {},
+): ResolvedSelfModificationConfig {
+ if (!isRecord(config)) throw new Error("Self-modification configuration must be an object.");
+
+ const local = config.local;
+ if (local !== undefined && !isRecord(local)) {
+ throw new Error("Self-modification local must be an object.");
+ }
+ const localEnabled = local?.enabled ?? true;
+ if (typeof localEnabled !== "boolean") {
+ throw new Error("Self-modification local.enabled must be a boolean.");
+ }
+
+ const deployed = config.deployed;
+ if (deployed === undefined) return { localEnabled };
+ if (!isRecord(deployed)) throw new Error("Self-modification deployed must be an object.");
+ const { source, target, credentials } = deployed;
+ if (source === undefined || target === undefined) {
+ throw new Error("Self-modification deployed requires both source and target configuration.");
+ }
+ if (!isRecord(source)) throw new Error("Self-modification deployed.source must be an object.");
+ if (!isRecord(source.git)) {
+ throw new Error("Self-modification deployed.source.git must be an object.");
+ }
+ if (!isRecord(target)) throw new Error("Self-modification deployed.target must be an object.");
+
+ const { git } = source;
+ if (typeof git.repository !== "string" || typeof git.directory !== "string") {
+ throw new Error(
+ "Self-modification deployed.source.git.repository and deployed.source.git.directory must be strings.",
+ );
+ }
+ if (typeof target.branch !== "string") {
+ throw new Error("Self-modification deployed.target.branch must be a string.");
+ }
+ return {
+ deployed: {
+ credentials: parseCredentials(credentials),
+ directory: parseDirectory(git.directory),
+ repository: parseGitHubRepository(git.repository),
+ targetBranch: parseBranch(target.branch),
+ },
+ localEnabled,
+ };
+}
+
+function parseCredentials(value: unknown): ResolvedGitHubCredentials {
+ if (!isRecord(value)) {
+ throw new Error(
+ "Self-modification deployed.credentials must explicitly configure Vercel Connect or the self-hosted PAT exception.",
+ );
+ }
+ const hasConnect = value.vercelConnect !== undefined;
+ const hasPat = value.pat !== undefined;
+ if (hasConnect === hasPat) {
+ throw new Error(
+ "Self-modification deployed.credentials must configure exactly one of vercelConnect or pat.",
+ );
+ }
+ if (value.pat !== undefined) {
+ if (value.pat !== true) {
+ throw new Error("Self-modification deployed.credentials.pat must be true.");
+ }
+ return { kind: "pat" };
+ }
+ if (!isRecord(value.vercelConnect)) {
+ throw new Error("Self-modification deployed.credentials.vercelConnect must be an object.");
+ }
+ const connector = value.vercelConnect.connector;
+ if (typeof connector !== "string" || connector.trim().length === 0) {
+ throw new Error(
+ "Self-modification deployed.credentials.vercelConnect.connector must be a string.",
+ );
+ }
+ return { connector: connector.trim(), kind: "vercel-connect" };
+}
+
+function parseGitHubRepository(repository: string): GitHubRepository {
+ const match = /^github\.com\/([^/]+)\/([^/]+)$/u.exec(repository);
+ if (match?.[1] === undefined || match[2] === undefined) {
+ throw new Error(
+ "Self-modification deployed.source.git.repository must use github.com/owner/repo form.",
+ );
+ }
+ assertRepositoryPart(match[1], "repository owner");
+ assertRepositoryPart(match[2], "repository name");
+ return { owner: match[1], repo: match[2] };
+}
+
+function parseDirectory(directory: string): string {
+ if (
+ directory !== "." &&
+ (directory.length === 0 ||
+ directory.startsWith("/") ||
+ directory.includes("\\") ||
+ directory.split("/").some((part) => part === "" || part === "." || part === ".."))
+ ) {
+ throw new Error(
+ "Self-modification deployed.source.git.directory must be a safe repository-relative path.",
+ );
+ }
+ return directory;
+}
+
+function parseBranch(branch: string): string {
+ assertGitRef(branch, "target branch");
+ if (branch.startsWith("refs/")) {
+ throw new Error(
+ "Self-modification deployed.target.branch must be a branch name, not a full Git ref.",
+ );
+ }
+ return branch;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/packages/eve/src/self-modification/credentials.test.ts b/packages/eve/src/self-modification/credentials.test.ts
new file mode 100644
index 000000000..34b85f18d
--- /dev/null
+++ b/packages/eve/src/self-modification/credentials.test.ts
@@ -0,0 +1,44 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const getToken = vi.fn();
+vi.mock("@vercel/connect", () => ({ getToken }));
+
+import { createVercelConnectCredentialProvider } from "./credentials.js";
+
+afterEach(() => {
+ getToken.mockReset();
+ delete process.env.EVE_SELF_MODIFICATION_GITHUB_TOKEN;
+});
+
+describe("Vercel Connect GitHub credentials", () => {
+ it("requests a repository-bound checkout token", async () => {
+ getToken.mockResolvedValue("checkout-token");
+ await expect(
+ createVercelConnectCredentialProvider("github/selfmod-acme-agents").resolve({
+ capability: "checkout",
+ repository: { owner: "acme", repo: "agents" },
+ }),
+ ).resolves.toBe("checkout-token");
+ expect(getToken).toHaveBeenCalledWith("github/selfmod-acme-agents", {
+ authorizationDetails: [{ repositories: ["acme/agents"], type: "github_app_installation" }],
+ scopes: ["contents:read", "metadata:read"],
+ subject: { type: "app" },
+ });
+ });
+
+ it("requests publication scopes without falling back to a PAT", async () => {
+ process.env.EVE_SELF_MODIFICATION_GITHUB_TOKEN = "pat-that-must-not-be-read";
+ getToken.mockRejectedValue(new Error("not attached"));
+ await expect(
+ createVercelConnectCredentialProvider("github/selfmod-acme-agents").resolve({
+ capability: "publish",
+ repository: { owner: "acme", repo: "agents" },
+ }),
+ ).rejects.toThrow("Vercel Connect");
+ expect(getToken).toHaveBeenCalledWith("github/selfmod-acme-agents", {
+ authorizationDetails: [{ repositories: ["acme/agents"], type: "github_app_installation" }],
+ scopes: ["contents:write", "pull_requests:write", "metadata:read"],
+ subject: { type: "app" },
+ });
+ });
+});
diff --git a/packages/eve/src/self-modification/credentials.ts b/packages/eve/src/self-modification/credentials.ts
new file mode 100644
index 000000000..9f991ad59
--- /dev/null
+++ b/packages/eve/src/self-modification/credentials.ts
@@ -0,0 +1,90 @@
+import type { GitHubRepository, ResolvedGitHubCredentials } from "./config.js";
+
+export type GitHubCredentialCapability = "checkout" | "publish";
+
+export interface GitHubCredentialRequest {
+ readonly capability: GitHubCredentialCapability;
+ readonly repository: GitHubRepository;
+}
+
+export interface GitHubCredentialProvider {
+ resolve(request: GitHubCredentialRequest): Promise<string>;
+}
+
+interface VercelConnectModule {
+ getToken(
+ connector: string,
+ options: {
+ readonly authorizationDetails: readonly {
+ readonly repositories: readonly string[];
+ readonly type: "github_app_installation";
+ }[];
+ readonly scopes: readonly string[];
+ readonly subject: { readonly type: "app" };
+ },
+ ): Promise<string>;
+}
+
+export const SELF_MODIFICATION_GITHUB_TOKEN_ENV = "EVE_SELF_MODIFICATION_GITHUB_TOKEN";
+
+/** Checks PAT availability without returning the credential. */
+export function hasGitHubCredential(): boolean {
+ return (process.env[SELF_MODIFICATION_GITHUB_TOKEN_ENV]?.trim().length ?? 0) > 0;
+}
+
+/** Constructs the configured provider without resolving a credential. */
+export function createGitHubCredentialProvider(
+ credentials: ResolvedGitHubCredentials,
+): GitHubCredentialProvider {
+ return credentials.kind === "pat"
+ ? defaultGitHubCredentialProvider
+ : createVercelConnectCredentialProvider(credentials.connector);
+}
+
+/** Resolves a PAT GitHub credential without exposing it to authored code. */
+export async function resolveGitHubCredential(request: GitHubCredentialRequest): Promise<string> {
+ return defaultGitHubCredentialProvider.resolve(request);
+}
+
+export const defaultGitHubCredentialProvider: GitHubCredentialProvider = {
+ async resolve() {
+ const token = process.env[SELF_MODIFICATION_GITHUB_TOKEN_ENV];
+ if (token === undefined || token.trim().length === 0) {
+ throw new Error(
+ `Self-modification requires ${SELF_MODIFICATION_GITHUB_TOKEN_ENV} in the deployment environment.`,
+ );
+ }
+ return token.trim();
+ },
+};
+
+export function createVercelConnectCredentialProvider(connector: string): GitHubCredentialProvider {
+ return {
+ async resolve(request) {
+ try {
+ const moduleName: string = "@vercel/connect";
+ const { getToken } = (await import(moduleName)) as VercelConnectModule;
+ const token = await getToken(connector, {
+ authorizationDetails: [
+ {
+ type: "github_app_installation",
+ repositories: [`${request.repository.owner}/${request.repository.repo}`],
+ },
+ ],
+ scopes:
+ request.capability === "checkout"
+ ? ["contents:read", "metadata:read"]
+ : ["contents:write", "pull_requests:write", "metadata:read"],
+ subject: { type: "app" },
+ });
+ if (token.trim().length === 0) throw new Error("empty token");
+ return token;
+ } catch (error) {
+ throw new Error(
+ `Self-modification could not obtain a GitHub credential from Vercel Connect for ${connector}. Install and attach the configured GitHub connector to this Vercel project, install the managed GitHub App for the configured repository, then retry.`,
+ { cause: error },
+ );
+ }
+ },
+ };
+}
diff --git a/packages/eve/src/self-modification/identifiers.test.ts b/packages/eve/src/self-modification/identifiers.test.ts
new file mode 100644
index 000000000..a8ab9caae
--- /dev/null
+++ b/packages/eve/src/self-modification/identifiers.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+
+import { assertFullSha, assertGitRef, assertRepositoryPart } from "./identifiers.js";
+
+describe("Git identifiers", () => {
+ it("accepts deployment SHAs case-insensitively", () => {
+ expect(() => assertFullSha("A".repeat(40), "revision")).not.toThrow();
+ });
+
+ it("rejects unsafe repository parts", () => {
+ for (const value of [".", "..", "-owner", "owner/name"]) {
+ expect(() => assertRepositoryPart(value, "repository owner")).toThrow(/invalid/u);
+ }
+ });
+
+ it("rejects Git lock refs", () => {
+ expect(() => assertGitRef("main.lock")).toThrow(/valid Git ref/u);
+ expect(() => assertGitRef("heads/main.lock/next")).toThrow(/valid Git ref/u);
+ });
+});
diff --git a/packages/eve/src/self-modification/identifiers.ts b/packages/eve/src/self-modification/identifiers.ts
new file mode 100644
index 000000000..e387168f4
--- /dev/null
+++ b/packages/eve/src/self-modification/identifiers.ts
@@ -0,0 +1,30 @@
+import { isFullGitSha, isValidGitRef } from "#shared/git.js";
+
+export function assertFullSha(value: string, label: string): void {
+ if (!isFullGitSha(value)) {
+ throw new Error(`Self-modification ${label} must be a full Git SHA.`);
+ }
+}
+
+export function assertRepositoryPart(value: string, label: string): void {
+ if (
+ !/^[A-Za-z0-9_.-]+$/u.test(value) ||
+ value === "." ||
+ value === ".." ||
+ value.startsWith("-")
+ ) {
+ throw new Error(`Self-modification ${label} is invalid.`);
+ }
+}
+
+export function assertGitRef(value: string, label = "target branch"): void {
+ if (!isValidGitRef(value)) {
+ throw new Error(`Self-modification ${label} is not a valid Git ref.`);
+ }
+}
+
+export function assertOperationId(operationId: string): void {
+ if (operationId.length === 0 || operationId.length > 512) {
+ throw new Error("Self-modification operation id must contain 1–512 characters.");
+ }
+}
diff --git a/packages/eve/src/self-modification/mode.ts b/packages/eve/src/self-modification/mode.ts
new file mode 100644
index 000000000..4fb9e394e
--- /dev/null
+++ b/packages/eve/src/self-modification/mode.ts
@@ -0,0 +1,18 @@
+import type { ResolvedSelfModificationConfig } from "./config.js";
+
+export type SelfModificationMode = "local" | "disabled" | "deployed";
+
+/** Resolves the mutually exclusive local or deployed editing mode. */
+export function resolveSelfModificationMode(
+ config: ResolvedSelfModificationConfig,
+): SelfModificationMode {
+ if (process.env.EVE_DEV === "1") return config.localEnabled ? "local" : "disabled";
+ if (config.deployed === undefined) return "disabled";
+ if (
+ config.deployed.credentials.kind === "vercel-connect" &&
+ process.env.VERCEL_ENV !== "production"
+ ) {
+ return "disabled";
+ }
+ return "deployed";
+}
diff --git a/packages/eve/src/shared/git.ts b/packages/eve/src/shared/git.ts
new file mode 100644
index 000000000..5c87d16aa
--- /dev/null
+++ b/packages/eve/src/shared/git.ts
@@ -0,0 +1,40 @@
+import { Buffer } from "node:buffer";
+
+import type { SandboxNetworkPolicy } from "./sandbox-network-policy.js";
+
+/** Returns whether a value is a complete Git object SHA. */
+export function isFullGitSha(value: string): boolean {
+ return /^[a-f0-9]{40}$/iu.test(value);
+}
+
+/** Returns whether a value can safely be used as a Git ref. */
+export function isValidGitRef(value: string): boolean {
+ return !(
+ value.length === 0 ||
+ value.startsWith("-") ||
+ value.endsWith(".") ||
+ value.endsWith("/") ||
+ value.includes("..") ||
+ value.includes("//") ||
+ value.includes("@{") ||
+ value.includes("\\") ||
+ value.split("/").some((part) => part.length === 0 || part.endsWith(".lock")) ||
+ /[\x00-\x20~^:?*[]/u.test(value)
+ );
+}
+
+/** Builds the token-free HTTPS remote used by GitHub fetches. */
+export function gitHubRemoteUrl(input: { readonly owner: string; readonly repo: string }): string {
+ return `https://github.com/${input.owner}/${input.repo}.git`;
+}
+
+/**
+ * Brokers a GitHub installation token at the sandbox firewall without exposing
+ * it to the process running git. codeload.github.com is required for redirects
+ * from shallow fetches.
+ */
+export function gitHubGitBrokerNetworkPolicy(token: string): SandboxNetworkPolicy {
+ const authorization = `Basic ${Buffer.from(`x-access-token:${token}`).toString("base64")}`;
+ const rule = [{ transform: [{ headers: { Authorization: authorization } }] }];
+ return { allow: { "*": [], "github.com": rule, "codeload.github.com": rule } };
+}