@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/github-workspace.js

@@ -0,0 +1,537 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubWorkspaceProvider = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_http_1 = require("node:http");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const github_command_guards_1 = require("./github-command-guards");
+const github_proxy_1 = require("./github-proxy");
+const github_proxy_certificates_1 = require("./github-proxy-certificates");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const DEFAULT_PROXY_PORT = 7780;
+const LINK_SECRET_FILE = '.github-proxy-link-secret';
+const WIP_PUSH_FAILED_FILE = '.worktree-wip-push-failed';
+const WIP_COMMIT_MESSAGE = 'chore(agent): wip — uncommitted at turn end';
+/** Bare clone plus one worktree per session, adapted from 20x. */
+class GitHubWorkspaceProvider {
+    options;
+    sessions = new Map();
+    gitEnvironment;
+    server = null;
+    port = null;
+    serverStart = null;
+    linkSecret = null;
+    caCertificatePath = null;
+    restartNotedSessions = new Set();
+    restoredWorktreeNotes = new Map();
+    preparedWorktrees = new Map();
+    directHosts = new Set();
+    constructor(options) {
+        this.options = options;
+        // Capture PATH before harness.start prepends the agent-facing guard bin.
+        // These control-plane-owned clone/worktree commands use the original Git;
+        // only backend shells should traverse the defense-in-depth launcher.
+        this.gitEnvironment = { ...process.env };
+        for (const key of Object.keys(this.gitEnvironment)) {
+            if (key.startsWith('GIT_') || key.startsWith('GH_')) {
+                delete this.gitEnvironment[key];
+            }
+        }
+        this.gitEnvironment.GIT_TERMINAL_PROMPT = '0';
+        this.rememberDirectUrls(options.directUrls ?? []);
+    }
+    rememberDirectUrls(urls) {
+        for (const value of urls) {
+            if (!value)
+                continue;
+            try {
+                this.directHosts.add(new URL(value).hostname.toLowerCase());
+            }
+            catch {
+                /* The component that owns an invalid URL reports it. */
+            }
+        }
+    }
+    runGit(args, options = {}) {
+        const { environment, ...execOptions } = options;
+        return execFileAsync('git', args, {
+            ...execOptions,
+            env: { ...this.gitEnvironment, ...environment }
+        });
+    }
+    /**
+     * A harness crash must not erase or recreate a session checkout. Accept an
+     * existing path only when Git proves that it is the exact worktree this
+     * provider would have created: same canonical root, same bare repository,
+     * and same per-session branch. Anything else fails closed.
+     */
+    async canReuseWorktree(bare, worktree, branch) {
+        let entry;
+        try {
+            entry = await (0, promises_1.lstat)(worktree);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+            throw new Error(`Existing repository workspace is not a directory: ${worktree}`);
+        }
+        try {
+            const [topLevel, commonDir, currentBranch] = await Promise.all([
+                this.runGit(['rev-parse', '--show-toplevel'], { cwd: worktree }),
+                this.runGit(['rev-parse', '--git-common-dir'], { cwd: worktree }),
+                this.runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], {
+                    cwd: worktree
+                })
+            ]);
+            const [expectedWorktree, actualWorktree, expectedBare, actualBare] = await Promise.all([
+                (0, promises_1.realpath)(worktree),
+                (0, promises_1.realpath)((0, node_path_1.resolve)(worktree, topLevel.stdout.trim())),
+                (0, promises_1.realpath)(bare),
+                (0, promises_1.realpath)((0, node_path_1.resolve)(worktree, commonDir.stdout.trim()))
+            ]);
+            if (actualWorktree !== expectedWorktree ||
+                actualBare !== expectedBare ||
+                currentBranch.stdout.trim() !== branch) {
+                throw new Error('repository or branch does not match');
+            }
+            return true;
+        }
+        catch (error) {
+            throw new Error(`Existing repository workspace cannot be reused safely: ${worktree}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async dirtyFileCount(worktree) {
+        const status = await this.runGit(['status', '--porcelain=v1', '-z'], {
+            cwd: worktree,
+            maxBuffer: 10 * 1024 * 1024
+        });
+        return status.stdout.split('\0').filter(Boolean).length;
+    }
+    async worktreesForSession(sessionId) {
+        const prepared = this.preparedWorktrees.get(sessionId);
+        if (prepared)
+            return prepared;
+        const root = this.sessionPath(sessionId);
+        let entries;
+        try {
+            entries = await (0, promises_1.readdir)(root, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const worktrees = [];
+        try {
+            await this.runGit(['rev-parse', '--is-inside-work-tree'], { cwd: root });
+            worktrees.push(root);
+        }
+        catch {
+            /* Repository-mode session roots contain child worktrees instead. */
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.isSymbolicLink())
+                continue;
+            const candidate = (0, node_path_1.join)(root, entry.name);
+            try {
+                await this.runGit(['rev-parse', '--is-inside-work-tree'], {
+                    cwd: candidate
+                });
+                worktrees.push(candidate);
+            }
+            catch {
+                /* An ordinary session child directory is not a Git worktree. */
+            }
+        }
+        return worktrees;
+    }
+    failedPushMarker(sessionId) {
+        return (0, node_path_1.join)(this.sessionPath(sessionId), WIP_PUSH_FAILED_FILE);
+    }
+    async readFailedPushes(sessionId) {
+        try {
+            const value = JSON.parse(await (0, promises_1.readFile)(this.failedPushMarker(sessionId), 'utf8'));
+            return new Set(Array.isArray(value)
+                ? value.filter((entry) => typeof entry === 'string')
+                : []);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return new Set();
+            throw error;
+        }
+    }
+    async writeFailedPushes(sessionId, failures) {
+        const marker = this.failedPushMarker(sessionId);
+        if (failures.size === 0) {
+            await (0, promises_1.unlink)(marker).catch((error) => {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            });
+            return;
+        }
+        await (0, promises_1.writeFile)(marker, `${JSON.stringify([...failures].sort())}\n`, {
+            mode: 0o600
+        });
+        await (0, promises_1.chmod)(marker, 0o600);
+    }
+    setCredential(sessionId, credential) {
+        const existing = this.sessions.get(sessionId);
+        this.sessions.set(sessionId, {
+            sessionId,
+            sentinel: existing?.sentinel ?? `pfgh_${this.sentinelFor(sessionId)}`,
+            credential
+        });
+    }
+    loadOrCreateLinkSecret() {
+        (0, node_fs_1.mkdirSync)(this.options.root, { recursive: true, mode: 0o700 });
+        const path = (0, node_path_1.join)((0, node_path_1.resolve)(this.options.root), LINK_SECRET_FILE);
+        let descriptor = null;
+        try {
+            descriptor = (0, node_fs_1.openSync)(path, 'wx', 0o600);
+            (0, node_fs_1.writeFileSync)(descriptor, (0, node_crypto_1.randomBytes)(32));
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        finally {
+            if (descriptor !== null)
+                (0, node_fs_1.closeSync)(descriptor);
+        }
+        (0, node_fs_1.chmodSync)(path, 0o600);
+        const secret = (0, node_fs_1.readFileSync)(path);
+        if (secret.length !== 32) {
+            throw new Error(`Invalid GitHub proxy link secret at ${path}.`);
+        }
+        return secret;
+    }
+    sentinelFor(sessionId) {
+        this.linkSecret ??= this.loadOrCreateLinkSecret();
+        return (0, node_crypto_1.createHmac)('sha256', this.linkSecret)
+            .update(sessionId)
+            .digest('hex');
+    }
+    clearCredential(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    sessionPath(sessionId) {
+        if (!/^[A-Za-z0-9._-]+$/.test(sessionId) ||
+            ['.', '..'].includes(sessionId)) {
+            throw new Error(`Unusable session id for a workspace path: ${JSON.stringify(sessionId)}`);
+        }
+        const root = (0, node_path_1.resolve)(this.options.root);
+        const path = (0, node_path_1.resolve)((0, node_path_1.join)(root, sessionId));
+        if (!path.startsWith(root + '/'))
+            throw new Error('Workspace path escaped the root.');
+        return path;
+    }
+    async ensureServer() {
+        if (this.port !== null)
+            return this.port;
+        if (this.serverStart)
+            return this.serverStart;
+        this.serverStart = this.startServer();
+        try {
+            return await this.serverStart;
+        }
+        finally {
+            this.serverStart = null;
+        }
+    }
+    async startServer() {
+        const server = (this.options.createServer ?? node_http_1.createServer)((_request, response) => {
+            response.writeHead(400, { 'content-type': 'text/plain' });
+            response.end('This endpoint is an HTTPS CONNECT proxy.\n');
+        });
+        const certificates = await (0, github_proxy_certificates_1.createGitHubProxyCertificates)(this.options.root);
+        this.caCertificatePath = certificates.caCertificatePath;
+        new github_proxy_1.GitHubTlsProxy(server, {
+            certificates,
+            logger: this.options.logger,
+            isDirectHostAllowed: (hostname) => this.directHosts.has(hostname),
+            findSession: (sentinel) => [...this.sessions.values()].find((entry) => entry.sentinel === sentinel)
+        });
+        const listen = (port) => new Promise((resolvePromise, reject) => {
+            const onError = (error) => reject(error);
+            server.once('error', onError);
+            server.listen(port, '127.0.0.1', () => {
+                server.off('error', onError);
+                resolvePromise();
+            });
+        });
+        const preferredPort = this.options.port ?? DEFAULT_PROXY_PORT;
+        try {
+            await listen(preferredPort);
+        }
+        catch (error) {
+            if (preferredPort === 0 ||
+                error.code !== 'EADDRINUSE') {
+                throw error;
+            }
+            (this.options.logger ?? console).warn(`[GitHubWorkspace] GitHub proxy port ${preferredPort} is in use; ` +
+                `using a kernel-assigned loopback port instead: ${error instanceof Error ? error.message : String(error)}`);
+            await listen(0);
+        }
+        const address = server.address();
+        if (!address || typeof address === 'string') {
+            server.close();
+            throw new Error('GitHub proxy did not bind.');
+        }
+        this.server = server;
+        this.port = address.port;
+        return this.port;
+    }
+    async prepare(request) {
+        const sessionRoot = this.sessionPath(request.sessionId);
+        await (0, promises_1.mkdir)(sessionRoot, { recursive: true, mode: 0o700 });
+        await (0, promises_1.chmod)(sessionRoot, 0o700);
+        if (request.mode === 'scratch')
+            return sessionRoot;
+        if (request.refusalReason)
+            throw new Error(request.refusalReason);
+        const session = this.sessions.get(request.sessionId);
+        if (!session || !request.repositories?.length) {
+            throw new Error('GitHub repository workspace has no in-memory credential.');
+        }
+        await this.ensureServer();
+        const helper = '!gh auth git-credential';
+        const ghConfig = (0, node_path_1.join)(sessionRoot, '.gh');
+        await (0, promises_1.mkdir)(ghConfig, { recursive: true, mode: 0o700 });
+        await (0, promises_1.chmod)(ghConfig, 0o700);
+        const gitNetworkEnvironment = this.getEnvironment(request.sessionId);
+        const repositoriesRoot = (0, node_path_1.join)((0, node_path_1.resolve)(this.options.root), '.repositories');
+        await (0, promises_1.mkdir)(repositoriesRoot, { recursive: true, mode: 0o700 });
+        const worktrees = [];
+        let reusedWorktree = false;
+        for (const repository of request.repositories) {
+            const [owner, name] = repository.fullName.split('/');
+            const bare = (0, node_path_1.join)(repositoriesRoot, `${owner}--${name}.git`);
+            const worktree = (0, node_path_1.join)(sessionRoot, name);
+            // The empty value resets every inherited/global helper. Without it, Git
+            // can pass the installation token to a desktop keychain helper on the
+            // approval phase even though this helper itself never writes a token.
+            const gitArgs = [
+                '-c',
+                'credential.helper=',
+                '-c',
+                `credential.helper=${helper}`
+            ];
+            try {
+                await this.runGit(['rev-parse', '--is-bare-repository'], {
+                    cwd: bare
+                });
+            }
+            catch {
+                await this.runGit([...gitArgs, 'clone', '--bare', repository.cloneUrl, bare], {
+                    timeout: 10 * 60_000,
+                    maxBuffer: 10 * 1024 * 1024,
+                    environment: gitNetworkEnvironment
+                });
+                await this.runGit([
+                    'config',
+                    'remote.origin.fetch',
+                    '+refs/heads/*:refs/remotes/origin/*'
+                ], { cwd: bare });
+            }
+            await this.runGit([...gitArgs, 'fetch', 'origin', '+refs/heads/*:refs/remotes/origin/*'], {
+                cwd: bare,
+                timeout: 10 * 60_000,
+                maxBuffer: 10 * 1024 * 1024,
+                environment: gitNetworkEnvironment
+            });
+            await this.runGit(['worktree', 'prune'], { cwd: bare });
+            const branch = `agent/${request.sessionId}`;
+            const reuse = await this.canReuseWorktree(bare, worktree, branch);
+            if (!reuse) {
+                try {
+                    await this.runGit(['worktree', 'add', worktree, branch], {
+                        cwd: bare
+                    });
+                }
+                catch {
+                    await this.runGit([
+                        'worktree',
+                        'add',
+                        '-b',
+                        branch,
+                        worktree,
+                        `origin/${repository.defaultBranch}`
+                    ], { cwd: bare });
+                }
+            }
+            else {
+                reusedWorktree = true;
+            }
+            worktrees.push(worktree);
+            await this.runGit(['config', '--unset-all', 'credential.helper'], {
+                cwd: worktree
+            }).catch(() => undefined);
+            await this.runGit(['config', '--add', 'credential.helper', ''], {
+                cwd: worktree
+            });
+            await this.runGit(['config', '--add', 'credential.helper', helper], {
+                cwd: worktree
+            });
+            // Hooks must be per worktree; a shared bare-repo hook would overwrite
+            // another session's allowed destination when sessions overlap.
+            await this.runGit(['config', 'extensions.worktreeConfig', 'true'], {
+                cwd: bare
+            });
+            await this.runGit(['config', '--worktree', 'core.bare', 'false'], {
+                cwd: worktree
+            });
+            const hooks = (0, node_path_1.join)(sessionRoot, '.github-hooks', name);
+            await (0, github_command_guards_1.installPushGuard)(hooks, request.sessionId, repository.defaultBranch, repository.cloneUrl);
+            await this.runGit(['config', '--worktree', 'core.hooksPath', hooks], {
+                cwd: worktree
+            });
+            request.onRepositoryStatus?.({
+                fullName: repository.fullName,
+                status: 'checkedOut'
+            });
+        }
+        this.preparedWorktrees.set(request.sessionId, worktrees);
+        if (reusedWorktree) {
+            let dirtyFiles = 0;
+            for (const worktree of worktrees) {
+                dirtyFiles += await this.dirtyFileCount(worktree);
+            }
+            this.restoredWorktreeNotes.set(request.sessionId, dirtyFiles === 0
+                ? 'Workspace restored; the repository worktree is clean.'
+                : `Workspace restored; ${dirtyFiles} ${dirtyFiles === 1 ? 'file' : 'files'} with uncommitted changes ${dirtyFiles === 1 ? 'is' : 'are'} still here.`);
+        }
+        const instructions = [
+            '# GitHub repository access',
+            '',
+            'Each repository is a child directory. Commit and push only the agent/<session-id> branch.',
+            'GitHub is reachable through a local proxy; use gh and git as usual. The token in GH_TOKEN is a session sentinel that works only inside this sandbox. Merges and pushes outside agent/<session-id> are refused.',
+            ''
+        ].join('\n');
+        await (0, promises_1.writeFile)((0, node_path_1.join)(sessionRoot, 'AGENTS.md'), instructions, {
+            mode: 0o600
+        });
+        return sessionRoot;
+    }
+    getEnvironment(sessionId, directUrls = []) {
+        const session = this.sessions.get(sessionId);
+        if (!session || this.port === null || !this.caCertificatePath)
+            return {};
+        this.rememberDirectUrls(directUrls);
+        const noProxy = new Set(['127.0.0.1', 'localhost', ...this.directHosts]);
+        const proxy = `http://127.0.0.1:${this.port}`;
+        const bypass = [...noProxy].join(',');
+        return {
+            // Git's libcurl on the Debian sandbox reads the lowercase form. With
+            // uppercase only, public clones appeared to work anonymously while a
+            // private clone sent the sentinel directly to GitHub and failed with
+            // "Invalid username or token". Keep both forms: Go-based gh uses the
+            // uppercase convention and native Git uses the lowercase convention.
+            HTTPS_PROXY: proxy,
+            https_proxy: proxy,
+            NO_PROXY: bypass,
+            no_proxy: bypass,
+            SSL_CERT_FILE: this.caCertificatePath,
+            GIT_SSL_CAINFO: this.caCertificatePath,
+            CURL_CA_BUNDLE: this.caCertificatePath,
+            NODE_EXTRA_CA_CERTS: this.caCertificatePath,
+            GH_TOKEN: session.sentinel,
+            GH_CONFIG_DIR: (0, node_path_1.join)(this.sessionPath(sessionId), '.gh')
+        };
+    }
+    takeTurnNote(sessionId) {
+        if (this.restartNotedSessions.has(sessionId))
+            return null;
+        if (!this.sessions.has(sessionId) || this.port === null)
+            return null;
+        this.restartNotedSessions.add(sessionId);
+        const restored = this.restoredWorktreeNotes.get(sessionId);
+        return [
+            'Harness restarted; GitHub access is through the local proxy — use gh/git as usual.',
+            restored
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    async preserveAtTurnEnd(sessionId) {
+        const worktrees = await this.worktreesForSession(sessionId);
+        const failures = await this.readFailedPushes(sessionId);
+        const branch = `agent/${sessionId}`;
+        for (const worktree of worktrees) {
+            const name = worktree.slice(worktree.lastIndexOf('/') + 1);
+            try {
+                const dirtyFiles = await this.dirtyFileCount(worktree);
+                if (dirtyFiles > 0) {
+                    await this.runGit(['add', '--all'], { cwd: worktree });
+                    await this.runGit([
+                        '-c',
+                        'user.name=Peakflo Agent',
+                        '-c',
+                        'user.email=agent@peakflo.bot',
+                        'commit',
+                        '-m',
+                        WIP_COMMIT_MESSAGE
+                    ], { cwd: worktree, maxBuffer: 10 * 1024 * 1024 });
+                }
+                if (dirtyFiles > 0 || failures.has(name)) {
+                    await this.runGit(['push', 'origin', `HEAD:refs/heads/${branch}`], {
+                        cwd: worktree,
+                        timeout: 10 * 60_000,
+                        maxBuffer: 10 * 1024 * 1024,
+                        environment: this.getEnvironment(sessionId)
+                    });
+                    failures.delete(name);
+                }
+            }
+            catch (error) {
+                failures.add(name);
+                (this.options.logger ?? console).warn(`[GitHubWorkspace] worktree-wip-push-failed sessionId=${sessionId} ` +
+                    `repository=${name} error=${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        await this.writeFailedPushes(sessionId, failures);
+        return failures.size === 0;
+    }
+    async release(sessionId, options = {}) {
+        const failedPushes = await this.readFailedPushes(sessionId);
+        if (failedPushes.size > 0) {
+            (this.options.logger ?? console).warn(`[GitHubWorkspace] worktree-release-refused-unpushed-wip ` +
+                `sessionId=${sessionId} repositories=${[...failedPushes].join(',')}`);
+            return false;
+        }
+        const worktrees = await this.worktreesForSession(sessionId);
+        let dirtyFiles = 0;
+        for (const worktree of worktrees) {
+            dirtyFiles += await this.dirtyFileCount(worktree);
+        }
+        if (dirtyFiles > 0 && !options.force) {
+            (this.options.logger ?? console).warn(`[GitHubWorkspace] worktree-release-refused-dirty ` +
+                `sessionId=${sessionId} dirtyFiles=${dirtyFiles}`);
+            return false;
+        }
+        await (0, promises_1.rm)(this.sessionPath(sessionId), { recursive: true, force: true });
+        this.preparedWorktrees.delete(sessionId);
+        this.restoredWorktreeNotes.delete(sessionId);
+        this.restartNotedSessions.delete(sessionId);
+        this.clearCredential(sessionId);
+        return true;
+    }
+    async stop() {
+        if (!this.server)
+            return;
+        await new Promise((resolvePromise) => this.server?.close(() => resolvePromise()));
+        this.server = null;
+        this.port = null;
+        this.serverStart = null;
+        this.sessions.clear();
+        this.caCertificatePath = null;
+    }
+}
+exports.GitHubWorkspaceProvider = GitHubWorkspaceProvider;