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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 } };+}