V48 Gate 3 (implementation-only): VercelSandboxHost — the sandbox implementation of the primitive Host

The second implementation of BitcodePipelineHost, sibling to InlineHost: same contract, sandbox mechanics. provisionRepository creates a sandbox with a git `source` (the Sandbox SDK clones the full working tree at the revision into /vercel/sandbox); the workspace lists files via `git ls-files` over runCommand, reads via readFileToBuffer (traversal-guarded), execs via runCommand, and disposes via session.stop. readWorkspaceSources bridges its checkout to {path, content}[] identically to the inline host — so the pipeline's source acquisition is host-agnostic.

Distinct from the existing VercelSandboxPipelineHost (the harness-plan/command runner); this is the source/filesystem primitive. 4 tests (capabilities, git-source provision + FS + traversal guard + readWorkspaceSources, runCommand); pipeline-hosts 6 suites/31 green; tsc clean.

Both implementations of the primitive Host now exist. Remaining: wire the deposit Setup to provision the full checkout through a Host + retire the API sample inventory (the prod-behavior-changing integration).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: geraldarthurdavis

packages/pipeline-hosts/src/__tests__/sandbox-host.test.ts

@@ -0,0 +1,96 @@
+import { VercelSandboxHost } from '../sandbox-host';
+import { readWorkspaceSources } from '../host';
+import type { SandboxCreateOptions, SandboxFactory, SandboxSession } from '../types';
+
+const FILES: Record<string, string> = {
+  'README.md': '# Demo',
+  'src/app.ts': 'export function main() {}',
+};
+
+function mockFactory() {
+  const createCalls: SandboxCreateOptions[] = [];
+  let stopped = false;
+  const session: SandboxSession = {
+    sandboxId: 'sbx-1',
+    status: 'running',
+    writeFiles: async () => {},
+    runCommand: (async (params: any) => {
+      if (params?.cmd === 'git' && params?.args?.includes('ls-files')) {
+        return { exitCode: 0, stdout: async () => Object.keys(FILES).join('\n'), stderr: async () => '' };
+      }
+      return { exitCode: 0, stdout: async () => 'ok', stderr: async () => '' };
+    }) as SandboxSession['runCommand'],
+    readFileToBuffer: async ({ path }: { path: string }) => {
+      const rel = path.replace('/vercel/sandbox/', '');
+      return FILES[rel] != null ? Buffer.from(FILES[rel]) : null;
+    },
+    stop: async () => {
+      stopped = true;
+      return undefined;
+    },
+  };
+  const sandboxFactory: SandboxFactory = {
+    create: async (options) => {
+      createCalls.push(options);
+      return session;
+    },
+  };
+  return { sandboxFactory, createCalls, isStopped: () => stopped };
+}
+
+describe('VercelSandboxHost (primitive Host implementation)', () => {
+  it('reports vercel-sandbox capabilities', () => {
+    const { sandboxFactory } = mockFactory();
+    const host = new VercelSandboxHost({ sandboxFactory });
+    expect(host.capabilities).toMatchObject({
+      hostKind: 'vercel-sandbox',
+      clone: true,
+      filesystem: true,
+      exec: true,
+      defaultWorkingDirectory: '/vercel/sandbox',
+    });
+  });
+
+  it('provisions via a git source and exposes the checkout filesystem', async () => {
+    const { sandboxFactory, createCalls, isStopped } = mockFactory();
+    const host = new VercelSandboxHost({ sandboxFactory });
+
+    const ws = await host.provisionRepository({
+      repositoryFullName: 'o/r',
+      url: 'https://github.com/o/r.git',
+      revision: 'abc123',
+      password: 'tok',
+    });
+
+    // The sandbox was created with a git source at the revision.
+    expect(createCalls).toHaveLength(1);
+    expect(createCalls[0].source).toMatchObject({
+      type: 'git',
+      url: 'https://github.com/o/r.git',
+      revision: 'abc123',
+      password: 'tok',
+    });
+    expect(ws.workspacePath).toBe('/vercel/sandbox');
+
+    // listFiles via git ls-files; readFile via readFileToBuffer.
+    expect((await ws.listFiles()).sort()).toEqual(['README.md', 'src/app.ts']);
+    expect(await ws.readFile('src/app.ts')).toBe('export function main() {}');
+    expect(await ws.readFile('../escape')).toBeNull(); // traversal guarded
+
+    // readWorkspaceSources bridges it identically to the inline host.
+    const sources = await readWorkspaceSources(ws, { paths: ['README.md'] });
+    expect(sources).toEqual([{ path: 'README.md', content: '# Demo' }]);
+
+    await ws.dispose();
+    expect(isStopped()).toBe(true);
+  });
+
+  it('runCommand surfaces exit code + output', async () => {
+    const { sandboxFactory } = mockFactory();
+    const host = new VercelSandboxHost({ sandboxFactory });
+    const ws = await host.provisionRepository({ repositoryFullName: 'o/r', url: 'https://github.com/o/r.git', revision: 'main' });
+    const result = await ws.runCommand('echo', ['hi']);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe('ok');
+  });
+});

packages/pipeline-hosts/src/index.ts

@@ -2,6 +2,7 @@ export * from './asset-pack-harness';
 export * from './distributed-execution-runtime-receipt';
 export * from './host';
 export * from './inline-host';
+export * from './sandbox-host';
 export * from './manifest';
 export * from './types';
 export * from './vercel-sandbox-host';

packages/pipeline-hosts/src/sandbox-host.ts

@@ -0,0 +1,132 @@
+/**
+ * VercelSandboxHost — the Vercel Sandbox implementation of the primitive Host
+ * (V48 Gate 3). The sibling of InlineHost: same `BitcodePipelineHost` contract,
+ * different mechanics.
+ *
+ * Provisions a repository by creating a sandbox with a git `source` (the Sandbox
+ * SDK clones the full working tree at the revision into the working directory), and
+ * exposes that checkout via the sandbox session — `git ls-files` over runCommand and
+ * `readFileToBuffer`. This is the durable, isolated host (prod); a serverless
+ * dispatching request hands off to it because it cannot itself clone.
+ *
+ * (Distinct from the existing `VercelSandboxPipelineHost`, which runs a full harness
+ * PLAN of commands + artifacts. This class is the source/filesystem primitive.)
+ */
+
+import type {
+  BitcodeHostCapabilities,
+  BitcodeHostRepositorySource,
+  BitcodeHostWorkspace,
+  BitcodePipelineHost,
+  HostCommandResult,
+} from './host';
+import type {
+  SandboxCommandResult,
+  SandboxCreateOptions,
+  SandboxFactory,
+  SandboxSession,
+  VercelSandboxRuntime,
+} from './types';
+
+const DEFAULT_WORKING_DIRECTORY = '/vercel/sandbox';
+
+async function readStream(result: SandboxCommandResult, stream: 'stdout' | 'stderr'): Promise<string> {
+  const reader = result[stream];
+  if (typeof reader === 'function') return reader.call(result);
+  if (typeof result.output === 'function') return result.output(stream);
+  return '';
+}
+
+function joinPosix(base: string, relative: string): string {
+  return `${base.replace(/\/+$/, '')}/${relative.replace(/^\/+/, '')}`;
+}
+
+export interface VercelSandboxHostOptions {
+  sandboxFactory: SandboxFactory;
+  workingDirectory?: string;
+  runtime?: VercelSandboxRuntime;
+  createOptions?: Partial<SandboxCreateOptions>;
+}
+
+class VercelSandboxWorkspace implements BitcodeHostWorkspace {
+  constructor(
+    private readonly session: SandboxSession,
+    readonly workspacePath: string,
+  ) {}
+
+  async listFiles(): Promise<string[]> {
+    const result = await this.session.runCommand({ cmd: 'git', args: ['ls-files'], cwd: this.workspacePath });
+    if (result.exitCode !== 0) return [];
+    const out = await readStream(result, 'stdout');
+    return out
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  async readFile(relativePath: string): Promise<string | null> {
+    // Defense-in-depth: never read outside the checkout.
+    if (relativePath.split('/').some((segment) => segment === '..')) return null;
+    const buffer = await this.session.readFileToBuffer({ path: joinPosix(this.workspacePath, relativePath) });
+    return buffer ? buffer.toString('utf8') : null;
+  }
+
+  async runCommand(cmd: string, args: string[] = []): Promise<HostCommandResult> {
+    const result = await this.session.runCommand({ cmd, args, cwd: this.workspacePath });
+    return {
+      exitCode: result.exitCode,
+      stdout: await readStream(result, 'stdout'),
+      stderr: await readStream(result, 'stderr'),
+    };
+  }
+
+  async dispose(): Promise<void> {
+    if (this.session.stop) {
+      try {
+        await this.session.stop({ blocking: true });
+      } catch {
+        // Best-effort; the sandbox is reclaimed regardless.
+      }
+    }
+  }
+}
+
+export class VercelSandboxHost implements BitcodePipelineHost {
+  private readonly sandboxFactory: SandboxFactory;
+  private readonly workingDirectory: string;
+  private readonly runtime?: VercelSandboxRuntime;
+  private readonly createOptions?: Partial<SandboxCreateOptions>;
+
+  constructor(options: VercelSandboxHostOptions) {
+    this.sandboxFactory = options.sandboxFactory;
+    this.workingDirectory = options.workingDirectory ?? DEFAULT_WORKING_DIRECTORY;
+    this.runtime = options.runtime;
+    this.createOptions = options.createOptions;
+  }
+
+  get capabilities(): BitcodeHostCapabilities {
+    return {
+      hostKind: 'vercel-sandbox',
+      clone: true,
+      filesystem: true,
+      exec: true,
+      ephemeralFilesystem: true,
+      defaultWorkingDirectory: this.workingDirectory,
+    };
+  }
+
+  async provisionRepository(source: BitcodeHostRepositorySource): Promise<BitcodeHostWorkspace> {
+    const session = await this.sandboxFactory.create({
+      ...this.createOptions,
+      runtime: this.runtime ?? this.createOptions?.runtime,
+      source: {
+        type: 'git',
+        url: source.url,
+        revision: source.revision,
+        username: source.username,
+        password: source.password,
+      },
+    });
+    return new VercelSandboxWorkspace(session, this.workingDirectory);
+  }
+}