diff --git a/packages/plugins/sandbox-providers/modal/README.md b/packages/plugins/sandbox-providers/modal/README.md new file mode 100644 index 00000000..b3966004 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/README.md @@ -0,0 +1,77 @@ +# `@paperclipai/plugin-modal` + +First-party Modal sandbox provider plugin for Paperclip. + +Like the other sandbox-provider packages in this repo, it lives inside the Paperclip monorepo but is intentionally excluded from the root `pnpm` workspace and shaped to publish and install like a standalone npm package. That lets operators install it from the Plugins page by package name without introducing root lockfile churn for Modal's SDK dependencies. + +## Install + +From a Paperclip instance, install: + +```text +@paperclipai/plugin-modal +``` + +The host plugin installer runs `npm install` into the managed plugin directory, so the `modal` SDK dependency is pulled in during installation. + +## Runtime support note + +Modal's official JS SDK README pins support to **Node 22 or later**. Paperclip's repo baseline is currently `node >= 20`; empirically `modal@0.7.4` imports and operates against the Modal API under Node 20, so the plugin runs there today, but the vendor support contract is Node 22+. The plugin logs a startup warning when it detects Node `< 22`. Operators who can pin their Paperclip runtime to Node 22+ should do so; treat Node-20 usage as best-effort until the host bumps its baseline. + +The empirical Node 20 compatibility check is recorded in [PAPA-352](/PAPA/issues/PAPA-352). + +## Configuration + +Configure Modal from `Company Settings -> Environments`, not from the plugin's instance settings page. + +| Field | Required | Description | +| --- | --- | --- | +| `appName` | yes | Modal App name. The plugin calls `modal.apps.fromName(appName, { createIfMissing: true })`, so the App is created on first acquire if it does not already exist. | +| `image` | yes | Container image passed to `modal.images.fromRegistry()`, e.g. `python:3.13` or `node:20`. | +| `tokenId` / `tokenSecret` | yes | Modal auth tokens. Both must be provided together. Paperclip stores pasted values as company secrets. The plugin worker runs in a child process that does not inherit host env vars, so `MODAL_TOKEN_ID` / `MODAL_TOKEN_SECRET` set on the Paperclip server are **not** read by the plugin — provide the tokens in this form. | +| `environment` | no | Optional Modal environment name. Falls back to the SDK profile default. | +| `workdir` | no | Remote working directory inside the sandbox. Defaults to `/workspace/paperclip`. | +| `sandboxTimeoutMs` | no | Maximum sandbox lifetime in milliseconds. Must be a positive multiple of `1000` between `1000` and `86_400_000` (24 hours). Defaults to `3_600_000` (1 hour). | +| `idleTimeoutMs` | no | Optional idle timeout in milliseconds. Modal terminates the sandbox if no exec is active for this duration. Must be a positive multiple of `1000`. | +| `execTimeoutMs` | no | Default per-exec timeout in milliseconds when the caller does not pass one. Must be a positive multiple of `1000`. Defaults to `300_000` (5 minutes). | +| `blockNetwork` | no | Block all egress network access. | +| `cidrAllowlist` | no | List of CIDRs the sandbox may reach. Cannot be combined with `blockNetwork`. | +| `reuseLease` | no | When `true`, the sandbox is detached (not terminated) on release and reattached by id later. Defaults to `false`. | + +### Reuse semantics + +Modal does **not** expose a separate pause/resume primitive for sandboxes — there is no equivalent to e2b's `pause()`. The plugin implements `reuseLease` as follows: + +- **`reuseLease: false` (default)**: On release the sandbox is `terminate()`d. Subsequent runs create a new sandbox. +- **`reuseLease: true`**: On release the plugin calls `sandbox.detach()`. The sandbox keeps running on Modal until its configured `sandboxTimeoutMs` or `idleTimeoutMs` elapses. The next acquire/resume reconnects via `modal.sandboxes.fromId(providerLeaseId)`. If the sandbox has expired, `fromId` raises `NotFoundError` and the plugin reports the lease as expired so Paperclip reacquires. + +Because there is no real pause, **`reuseLease: true` keeps billing running** until the sandbox or idle timeout cuts it off. Tune `idleTimeoutMs` to a value that matches your reuse window. + +## Local development + +```bash +cd packages/plugins/sandbox-providers/modal +pnpm install --ignore-workspace --no-lockfile +pnpm build +pnpm test +pnpm typecheck +``` + +These commands assume the repo root has already been installed once so the local `@paperclipai/plugin-sdk` workspace package is available to the compiler during development. + +## Operator verification + +1. Provision Modal credentials in your Modal account (`modal token new`) or use a service account. +2. Install the plugin from the Paperclip Plugins page. +3. In `Company Settings -> Environments`, add a new Modal sandbox environment with at least `appName`, `image`, `tokenId`, and `tokenSecret`. +4. Run the environment **Probe** action. A success result confirms auth, app creation, image pull, and `exec` round-trip. +5. Run at least one Paperclip task with a remote-managed adapter (for example `claude_local`) bound to that environment. The adapter should provision the sandbox, run commands in it, and clean it up. + +Full end-to-end manual QA is tracked separately in [PAPA-354](/PAPA/issues/PAPA-354). + +## Package layout + +- `src/manifest.ts` declares the sandbox-provider driver metadata +- `src/plugin.ts` implements the environment lifecycle hooks +- `src/worker.ts` boots the plugin under the host worker runtime +- `paperclipPlugin.manifest` and `paperclipPlugin.worker` point the host at the built plugin entrypoints in `dist/` diff --git a/packages/plugins/sandbox-providers/modal/package.json b/packages/plugins/sandbox-providers/modal/package.json new file mode 100644 index 00000000..e3d62639 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/package.json @@ -0,0 +1,61 @@ +{ + "name": "@paperclipai/plugin-modal", + "version": "0.1.0", + "description": "Modal sandbox provider plugin for Paperclip environments", + "license": "MIT", + "homepage": "https://github.com/paperclipai/paperclip", + "bugs": { + "url": "https://github.com/paperclipai/paperclip/issues" + }, + "repository": { + "type": "git", + "url": "https://github.com/paperclipai/paperclip", + "directory": "packages/plugins/sandbox-providers/modal" + }, + "type": "module", + "exports": { + ".": "./src/index.ts" + }, + "publishConfig": { + "access": "public", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "main": "./dist/index.js", + "types": "./dist/index.d.ts" + }, + "files": [ + "dist" + ], + "paperclipPlugin": { + "manifest": "./dist/manifest.js", + "worker": "./dist/worker.js" + }, + "keywords": [ + "paperclip", + "plugin", + "sandbox", + "modal" + ], + "scripts": { + "postinstall": "node ../../../../scripts/link-plugin-dev-sdk.mjs", + "prebuild": "pnpm -C ../../../.. --filter @paperclipai/plugin-sdk ensure-build-deps", + "build": "rm -rf dist && tsc", + "clean": "rm -rf dist", + "typecheck": "pnpm -C ../../../.. --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit", + "test": "vitest run --config vitest.config.ts", + "prepack": "rm -f package.dev.json && cp package.json package.dev.json && node ../../../../scripts/generate-plugin-package-json.mjs", + "postpack": "if [ -f package.dev.json ]; then mv package.dev.json package.json; fi" + }, + "dependencies": { + "modal": "^0.7.4" + }, + "devDependencies": { + "@types/node": "^24.6.0", + "typescript": "^5.7.3", + "vitest": "^3.2.4" + } +} diff --git a/packages/plugins/sandbox-providers/modal/src/index.ts b/packages/plugins/sandbox-providers/modal/src/index.ts new file mode 100644 index 00000000..f7ce1cc1 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/src/index.ts @@ -0,0 +1,2 @@ +export { default as manifest } from "./manifest.js"; +export { default as plugin } from "./plugin.js"; diff --git a/packages/plugins/sandbox-providers/modal/src/manifest.ts b/packages/plugins/sandbox-providers/modal/src/manifest.ts new file mode 100644 index 00000000..bd694622 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/src/manifest.ts @@ -0,0 +1,101 @@ +import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk"; + +const PLUGIN_ID = "paperclip.modal-sandbox-provider"; +const PLUGIN_VERSION = "0.1.0"; + +const manifest: PaperclipPluginManifestV1 = { + id: PLUGIN_ID, + apiVersion: 1, + version: PLUGIN_VERSION, + displayName: "Modal Sandbox Provider", + description: + "First-party sandbox provider plugin that provisions Modal sandboxes as Paperclip execution environments.", + author: "Paperclip", + categories: ["automation"], + capabilities: ["environment.drivers.register"], + entrypoints: { + worker: "./dist/worker.js", + }, + environmentDrivers: [ + { + driverKey: "modal", + kind: "sandbox_provider", + displayName: "Modal Sandbox", + description: + "Provisions Modal sandboxes with configurable image, app, auth, timeouts, and network controls.", + configSchema: { + type: "object", + required: ["appName", "image"], + properties: { + appName: { + type: "string", + description: + "Modal App name used as the parent for sandboxes. The plugin calls `modal.apps.fromName(appName, { createIfMissing: true })`, so the App is created on first acquire if it does not already exist.", + }, + image: { + type: "string", + description: + "Container image reference passed to `modal.images.fromRegistry()`, e.g. `python:3.13` or `node:20`.", + }, + tokenId: { + type: "string", + format: "secret-ref", + description: + "Modal token ID. Paste a token or an existing Paperclip secret reference; saved environments store pasted values as company secrets. Required.", + }, + tokenSecret: { + type: "string", + format: "secret-ref", + description: "Modal token secret paired with tokenId. Required.", + }, + environment: { + type: "string", + description: + "Optional Modal environment name. Falls back to the SDK profile default.", + }, + workdir: { + type: "string", + description: "Remote working directory inside the sandbox.", + default: "/workspace/paperclip", + }, + sandboxTimeoutMs: { + type: "number", + description: + "Maximum sandbox lifetime in milliseconds. Must be a positive multiple of 1000 between 1000 and 86400000 (24 hours).", + default: 3_600_000, + }, + idleTimeoutMs: { + type: "number", + description: + "Optional idle timeout in milliseconds. When set, Modal terminates the sandbox if no exec is active for this duration. Must be a positive multiple of 1000.", + }, + execTimeoutMs: { + type: "number", + description: + "Default per-exec timeout in milliseconds when the caller does not provide one. Must be a positive multiple of 1000.", + default: 300_000, + }, + blockNetwork: { + type: "boolean", + description: "Whether to block all egress network access from the sandbox.", + default: false, + }, + cidrAllowlist: { + type: "array", + items: { type: "string" }, + description: + "Optional list of CIDRs the sandbox is allowed to reach. Cannot be combined with blockNetwork.", + }, + reuseLease: { + type: "boolean", + description: + "When true, the sandbox is detached (not terminated) on release and resumed by id later. Reuse relies on Modal's sandbox lifetime and idle timeout because Modal has no separate pause primitive.", + default: false, + }, + }, + }, + }, + ], +}; + +export default manifest; diff --git a/packages/plugins/sandbox-providers/modal/src/plugin.test.ts b/packages/plugins/sandbox-providers/modal/src/plugin.test.ts new file mode 100644 index 00000000..b45536fa --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/src/plugin.test.ts @@ -0,0 +1,703 @@ +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const { MockNotFoundError, MockTimeoutError, MockSandboxTimeoutError } = vi.hoisted(() => { + class MockNotFoundError extends Error {} + class MockTimeoutError extends Error {} + class MockSandboxTimeoutError extends Error {} + return { MockNotFoundError, MockTimeoutError, MockSandboxTimeoutError }; +}); + +const mockAppFromName = vi.hoisted(() => vi.fn()); +const mockImageFromRegistry = vi.hoisted(() => vi.fn(() => ({ kind: "image" }))); +const mockSandboxesCreate = vi.hoisted(() => vi.fn()); +const mockSandboxesFromId = vi.hoisted(() => vi.fn()); +const mockClientClose = vi.hoisted(() => vi.fn()); + +vi.mock("modal", () => ({ + ModalClient: class MockModalClient { + apps = { fromName: mockAppFromName }; + images = { fromRegistry: mockImageFromRegistry }; + sandboxes = { create: mockSandboxesCreate, fromId: mockSandboxesFromId }; + close = mockClientClose; + constructor(_params?: unknown) {} + }, + NotFoundError: MockNotFoundError, + TimeoutError: MockTimeoutError, + SandboxTimeoutError: MockSandboxTimeoutError, +})); + +import plugin from "./plugin.js"; + +interface FakeSandboxOverrides { + id?: string; + execImpl?: (argv: string[], params?: unknown) => Promise; +} + +interface FakeProcess { + stdout: { readText: () => Promise }; + stderr: { readText: () => Promise }; + wait: () => Promise; +} + +function makeFakeProcess(input: { + exitCode?: number; + stdout?: string; + stderr?: string; + throwOnWait?: unknown; +}): FakeProcess { + return { + stdout: { readText: vi.fn().mockResolvedValue(input.stdout ?? "") }, + stderr: { readText: vi.fn().mockResolvedValue(input.stderr ?? "") }, + wait: vi.fn().mockImplementation(async () => { + if (input.throwOnWait) throw input.throwOnWait; + return input.exitCode ?? 0; + }), + }; +} + +function createFakeSandbox(overrides: FakeSandboxOverrides = {}) { + const execCalls: Array<{ argv: string[]; params?: unknown }> = []; + const defaultExec = async (_argv: string[], _params?: unknown): Promise => + makeFakeProcess({ exitCode: 0, stdout: "paperclip-probe" }); + const exec = vi.fn().mockImplementation(async (argv: string[], params?: unknown) => { + execCalls.push({ argv, params }); + return overrides.execImpl ? overrides.execImpl(argv, params) : defaultExec(argv, params); + }); + const openedFiles: Array<{ path: string; mode: string; written: Uint8Array | null }> = []; + const sandbox = { + sandboxId: overrides.id ?? "sb-123", + exec, + execCalls, + openedFiles, + setTags: vi.fn().mockResolvedValue(undefined), + terminate: vi.fn().mockResolvedValue(undefined), + detach: vi.fn(), + poll: vi.fn().mockResolvedValue(null), + open: vi.fn().mockImplementation(async (path: string, mode: string) => { + const entry: { path: string; mode: string; written: Uint8Array | null } = { + path, + mode, + written: null, + }; + openedFiles.push(entry); + return { + write: vi.fn().mockImplementation(async (data: Uint8Array) => { + entry.written = data; + }), + flush: vi.fn().mockResolvedValue(undefined), + close: vi.fn().mockResolvedValue(undefined), + }; + }), + }; + return sandbox; +} + +type FakeSandbox = ReturnType; + +const baseAcquireParams = { + driverKey: "modal", + companyId: "company-1", + environmentId: "env-1", + runId: "run-1", +}; + +const baseConfig = { + appName: "paperclip-app", + image: "node:20", + sandboxTimeoutMs: 3_600_000, + execTimeoutMs: 300_000, + reuseLease: false, +}; + +const baseConfigWithTokens = { + ...baseConfig, + tokenId: "config-id", + tokenSecret: "config-secret", +}; + +beforeEach(() => { + mockAppFromName.mockReset(); + mockImageFromRegistry.mockReset(); + mockImageFromRegistry.mockReturnValue({ kind: "image" }); + mockSandboxesCreate.mockReset(); + mockSandboxesFromId.mockReset(); + mockClientClose.mockReset(); + vi.restoreAllMocks(); + delete process.env.MODAL_TOKEN_ID; + delete process.env.MODAL_TOKEN_SECRET; +}); + +describe("Modal sandbox provider plugin", () => { + it("declares environment lifecycle handlers", async () => { + expect(await plugin.definition.onHealth?.()).toEqual({ + status: "ok", + message: "Modal sandbox provider plugin healthy", + }); + expect(plugin.definition.onEnvironmentAcquireLease).toBeTypeOf("function"); + expect(plugin.definition.onEnvironmentExecute).toBeTypeOf("function"); + expect(plugin.definition.onEnvironmentReleaseLease).toBeTypeOf("function"); + expect(plugin.definition.onEnvironmentResumeLease).toBeTypeOf("function"); + }); + + it("normalizes config when both tokens are provided", async () => { + const result = await plugin.definition.onEnvironmentValidateConfig?.({ + driverKey: "modal", + config: { + appName: " app-1 ", + image: " node:20 ", + tokenId: " token-id ", + tokenSecret: " token-secret ", + environment: " main ", + workdir: " /srv/work ", + sandboxTimeoutMs: "1800000", + idleTimeoutMs: "60000", + execTimeoutMs: "120000", + reuseLease: true, + blockNetwork: false, + cidrAllowlist: ["10.0.0.0/8"], + }, + }); + + expect(result).toEqual({ + ok: true, + normalizedConfig: { + appName: "app-1", + image: "node:20", + tokenId: "token-id", + tokenSecret: "token-secret", + environment: "main", + workdir: "/srv/work", + sandboxTimeoutMs: 1_800_000, + idleTimeoutMs: 60_000, + execTimeoutMs: 120_000, + blockNetwork: false, + cidrAllowlist: ["10.0.0.0/8"], + reuseLease: true, + }, + }); + }); + + it("ignores host MODAL_TOKEN_* env vars (plugin worker does not inherit them)", async () => { + process.env.MODAL_TOKEN_ID = "host-id"; + process.env.MODAL_TOKEN_SECRET = "host-secret"; + + const result = await plugin.definition.onEnvironmentValidateConfig?.({ + driverKey: "modal", + config: { ...baseConfig }, + }); + + expect(result).toEqual({ + ok: false, + errors: ["Modal sandbox environments require tokenId and tokenSecret."], + }); + }); + + it("rejects invalid config", async () => { + const result = await plugin.definition.onEnvironmentValidateConfig?.({ + driverKey: "modal", + config: { + appName: "", + image: "", + sandboxTimeoutMs: 1500, + idleTimeoutMs: 1500, + execTimeoutMs: 0, + blockNetwork: true, + cidrAllowlist: ["1.2.3.4/32"], + tokenId: "only-id", + }, + }); + + expect(result).toEqual({ + ok: false, + errors: [ + "Modal sandbox environments require an appName.", + "Modal sandbox environments require an image reference.", + "sandboxTimeoutMs must be a positive multiple of 1000 between 1000 and 86400000.", + "idleTimeoutMs must be a positive multiple of 1000 when provided.", + "execTimeoutMs must be a positive multiple of 1000.", + "cidrAllowlist cannot be combined with blockNetwork.", + "tokenId and tokenSecret must both be provided when either is set.", + ], + }); + }); + + it("requires both tokens in config", async () => { + const result = await plugin.definition.onEnvironmentValidateConfig?.({ + driverKey: "modal", + config: { ...baseConfig }, + }); + expect(result).toEqual({ + ok: false, + errors: ["Modal sandbox environments require tokenId and tokenSecret."], + }); + }); + + it("probes by creating, executing, and terminating a sandbox", async () => { + const sandbox = createFakeSandbox(); + mockAppFromName.mockResolvedValue({ appId: "ap-1" }); + mockSandboxesCreate.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentProbe?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: { ...baseConfig, workdir: "/srv/work" }, + }); + + expect(mockAppFromName).toHaveBeenCalledWith("paperclip-app", { + createIfMissing: true, + environment: undefined, + }); + expect(mockImageFromRegistry).toHaveBeenCalledWith("node:20"); + expect(sandbox.setTags).toHaveBeenCalledWith(expect.objectContaining({ + "paperclip-provider": "modal", + "paperclip-company-id": "c-1", + })); + // First exec is the mkdir for the workspace, second is the probe command. + expect(sandbox.execCalls[0]?.argv).toEqual([ + "sh", + "-lc", + "mkdir -p '/srv/work'", + ]); + expect(sandbox.execCalls[1]?.argv).toEqual([ + "sh", + "-lc", + "printf paperclip-probe", + ]); + expect(sandbox.terminate).toHaveBeenCalled(); + expect(mockClientClose).toHaveBeenCalled(); + expect(result).toMatchObject({ + ok: true, + metadata: { + provider: "modal", + sandboxId: "sb-123", + remoteCwd: "/srv/work", + reuseLease: false, + }, + }); + }); + + it("returns a failure probe result when the probe command exits non-zero", async () => { + const sandbox = createFakeSandbox({ + execImpl: async (argv: string[]) => { + if (argv[2] === "printf paperclip-probe") { + return makeFakeProcess({ exitCode: 7, stdout: "boom" }); + } + return makeFakeProcess({ exitCode: 0 }); + }, + }); + mockAppFromName.mockResolvedValue({ appId: "ap-1" }); + mockSandboxesCreate.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentProbe?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + }); + + expect(result?.ok).toBe(false); + expect(sandbox.terminate).toHaveBeenCalled(); + }); + + it("closes the Modal client when probe fails before sandbox creation", async () => { + mockAppFromName.mockRejectedValue(new Error("app lookup failed")); + + const result = await plugin.definition.onEnvironmentProbe?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + }); + + expect(result).toMatchObject({ + ok: false, + summary: "Modal sandbox probe failed.", + metadata: expect.objectContaining({ + error: "app lookup failed", + }), + }); + expect(mockClientClose).toHaveBeenCalledTimes(1); + }); + + it("acquires a lease, applies tags, and ensures the workspace directory", async () => { + const sandbox = createFakeSandbox({ id: "sb-acquire" }); + mockAppFromName.mockResolvedValue({ appId: "ap-1" }); + mockSandboxesCreate.mockResolvedValue(sandbox); + + const lease = await plugin.definition.onEnvironmentAcquireLease?.({ + ...baseAcquireParams, + config: { ...baseConfig, reuseLease: true, workdir: "/srv/work" }, + }); + + expect(lease).toEqual({ + providerLeaseId: "sb-acquire", + metadata: expect.objectContaining({ + provider: "modal", + sandboxId: "sb-acquire", + remoteCwd: "/srv/work", + reuseLease: true, + resumedLease: false, + }), + }); + expect(sandbox.setTags).toHaveBeenCalledWith(expect.objectContaining({ + "paperclip-run-id": "run-1", + "paperclip-reuse-lease": "true", + })); + expect(sandbox.execCalls[0]?.argv).toEqual(["sh", "-lc", "mkdir -p '/srv/work'"]); + }); + + it("terminates the sandbox if acquire workspace setup throws", async () => { + const sandbox = createFakeSandbox({ + execImpl: async (argv: string[]) => { + if (argv[2]?.startsWith("mkdir -p")) { + return makeFakeProcess({ throwOnWait: new Error("mkdir failed") }); + } + return makeFakeProcess({ exitCode: 0 }); + }, + }); + mockAppFromName.mockResolvedValue({ appId: "ap-1" }); + mockSandboxesCreate.mockResolvedValue(sandbox); + + await expect( + plugin.definition.onEnvironmentAcquireLease?.({ + ...baseAcquireParams, + config: baseConfig, + }), + ).rejects.toThrow("mkdir failed"); + expect(sandbox.terminate).toHaveBeenCalledTimes(1); + }); + + it("fails acquire when workspace creation exits non-zero", async () => { + const sandbox = createFakeSandbox({ + execImpl: async (argv: string[]) => { + if (argv[2]?.startsWith("mkdir -p")) { + return makeFakeProcess({ exitCode: 17 }); + } + return makeFakeProcess({ exitCode: 0 }); + }, + }); + mockAppFromName.mockResolvedValue({ appId: "ap-1" }); + mockSandboxesCreate.mockResolvedValue(sandbox); + + await expect( + plugin.definition.onEnvironmentAcquireLease?.({ + ...baseAcquireParams, + config: baseConfig, + }), + ).rejects.toThrow( + "Failed to create remote workspace directory '/workspace/paperclip': mkdir exited with code 17", + ); + expect(sandbox.terminate).toHaveBeenCalledTimes(1); + }); + + it("closes the Modal client when acquire fails before sandbox creation", async () => { + mockAppFromName.mockRejectedValue(new Error("app lookup failed")); + + await expect( + plugin.definition.onEnvironmentAcquireLease?.({ + ...baseAcquireParams, + config: baseConfig, + }), + ).rejects.toThrow("app lookup failed"); + expect(mockClientClose).toHaveBeenCalledTimes(1); + }); + + it("treats missing leases as expired on resume", async () => { + mockSandboxesFromId.mockRejectedValue(new MockNotFoundError("gone")); + + const lease = await plugin.definition.onEnvironmentResumeLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-missing", + config: { ...baseConfig, reuseLease: true }, + }); + expect(lease).toEqual({ providerLeaseId: null, metadata: { expired: true } }); + }); + + it("resumes a reusable lease by reconnecting via fromId", async () => { + const sandbox = createFakeSandbox({ id: "sb-resume" }); + mockSandboxesFromId.mockResolvedValue(sandbox); + + const lease = await plugin.definition.onEnvironmentResumeLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-resume", + config: { ...baseConfig, reuseLease: true }, + }); + + expect(lease).toEqual({ + providerLeaseId: "sb-resume", + metadata: expect.objectContaining({ + provider: "modal", + sandboxId: "sb-resume", + resumedLease: true, + reuseLease: true, + }), + }); + }); + + it("detaches the sandbox if resumed workspace setup fails", async () => { + const sandbox = createFakeSandbox({ + id: "sb-resume", + execImpl: async (argv: string[]) => { + if (argv[2]?.startsWith("mkdir -p")) { + return makeFakeProcess({ throwOnWait: new Error("mkdir failed") }); + } + return makeFakeProcess({ exitCode: 0 }); + }, + }); + mockSandboxesFromId.mockResolvedValue(sandbox); + + await expect( + plugin.definition.onEnvironmentResumeLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-resume", + config: { ...baseConfig, reuseLease: true }, + }), + ).rejects.toThrow("mkdir failed"); + expect(sandbox.detach).toHaveBeenCalledTimes(1); + }); + + it("detaches reusable leases and terminates ephemeral leases on release", async () => { + const reusable = createFakeSandbox({ id: "sb-reuse" }); + const ephemeral = createFakeSandbox({ id: "sb-ephem" }); + mockSandboxesFromId.mockResolvedValueOnce(reusable).mockResolvedValueOnce(ephemeral); + + await plugin.definition.onEnvironmentReleaseLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-reuse", + config: { ...baseConfig, reuseLease: true }, + }); + await plugin.definition.onEnvironmentReleaseLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-ephem", + config: { ...baseConfig, reuseLease: false }, + }); + + expect(reusable.detach).toHaveBeenCalled(); + expect(reusable.terminate).not.toHaveBeenCalled(); + expect(ephemeral.terminate).toHaveBeenCalled(); + expect(ephemeral.detach).not.toHaveBeenCalled(); + }); + + it("destroys leases by terminating, ignoring missing sandboxes", async () => { + const sandbox = createFakeSandbox({ id: "sb-destroy" }); + mockSandboxesFromId.mockResolvedValueOnce(sandbox); + + await plugin.definition.onEnvironmentDestroyLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-destroy", + config: baseConfig, + }); + expect(sandbox.terminate).toHaveBeenCalled(); + + mockSandboxesFromId.mockRejectedValueOnce(new MockNotFoundError("missing")); + await expect( + plugin.definition.onEnvironmentDestroyLease?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + providerLeaseId: "sb-missing", + config: baseConfig, + }), + ).resolves.toBeUndefined(); + }); + + it("realizes the workspace using the lease metadata cwd when available", async () => { + const sandbox = createFakeSandbox({ id: "sb-real" }); + mockSandboxesFromId.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentRealizeWorkspace?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { + providerLeaseId: "sb-real", + metadata: { remoteCwd: "/srv/from-metadata" }, + }, + workspace: { localPath: "/local", remotePath: "/remote" }, + }); + + expect(sandbox.execCalls[0]?.argv).toEqual([ + "sh", + "-lc", + "mkdir -p '/srv/from-metadata'", + ]); + expect(result).toEqual({ + cwd: "/srv/from-metadata", + metadata: { provider: "modal", remoteCwd: "/srv/from-metadata" }, + }); + }); + + it("executes commands with a login-shell wrapper that injects env after profile sourcing", async () => { + const sandbox = createFakeSandbox({ + execImpl: async (argv: string[]) => + makeFakeProcess({ + exitCode: 5, + stdout: "stdout-output", + stderr: "stderr-output", + }), + }); + mockSandboxesFromId.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentExecute?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { providerLeaseId: "sb-exec", metadata: {} }, + command: "printf", + args: ["hello"], + cwd: "/srv/work", + env: { FOO: "bar" }, + timeoutMs: 12_000, + }); + + expect(sandbox.execCalls).toHaveLength(1); + const call = sandbox.execCalls[0]!; + expect(call.argv[0]).toBe("sh"); + expect(call.argv[1]).toBe("-lc"); + const script = call.argv[2]!; + expect(script).toMatch(/\/etc\/profile/); + expect(script).toMatch(/cd '\/srv\/work'/); + expect(script).toMatch(/&& exec env FOO='bar' 'printf' 'hello'$/); + expect(call.params).toMatchObject({ + timeoutMs: 12_000, + stdout: "pipe", + stderr: "pipe", + }); + expect(result).toEqual({ + exitCode: 5, + timedOut: false, + stdout: "stdout-output", + stderr: "stderr-output", + }); + }); + + it("stages stdin in the sandbox filesystem when execution needs redirected input", async () => { + const sandbox = createFakeSandbox(); + mockSandboxesFromId.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentExecute?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { providerLeaseId: "sb-exec", metadata: {} }, + command: "cat", + args: [], + stdin: "input payload", + cwd: "/srv/work", + }); + + expect(sandbox.openedFiles).toHaveLength(1); + expect(sandbox.openedFiles[0]?.path).toMatch(/^\/tmp\/paperclip-stdin-/); + expect(sandbox.openedFiles[0]?.mode).toBe("w"); + expect(sandbox.openedFiles[0]?.written).not.toBeNull(); + expect(new TextDecoder().decode(sandbox.openedFiles[0]!.written!)).toBe("input payload"); + + // First exec is the user command; second is the rm cleanup. + const userCall = sandbox.execCalls[0]!; + expect(userCall.argv[2]).toMatch(/&& exec 'cat' < '\/tmp\/paperclip-stdin-/); + const cleanupCall = sandbox.execCalls[1]!; + expect(cleanupCall.argv[2]).toMatch(/^rm -f '\/tmp\/paperclip-stdin-/); + expect(result?.exitCode).toBe(0); + }); + + it("rejects invalid shell env keys before execution", async () => { + const sandbox = createFakeSandbox(); + mockSandboxesFromId.mockResolvedValue(sandbox); + + await expect( + plugin.definition.onEnvironmentExecute?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { providerLeaseId: "sb-exec", metadata: {} }, + command: "printf", + args: ["hello"], + env: { "BAD-KEY": "v" }, + }), + ).rejects.toThrow("Invalid sandbox environment variable key: BAD-KEY"); + expect(sandbox.execCalls).toHaveLength(0); + }); + + it("returns an error result when execute is called for an expired sandbox lease", async () => { + mockSandboxesFromId.mockRejectedValue(new MockNotFoundError("gone")); + + const result = await plugin.definition.onEnvironmentExecute?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { providerLeaseId: "sb-expired", metadata: {} }, + command: "printf", + args: ["hello"], + }); + + expect(result).toEqual({ + exitCode: 1, + timedOut: false, + stdout: "", + stderr: "Modal sandbox lease is no longer available.\n", + }); + }); + + it("returns a timedOut result when Modal raises a TimeoutError during exec", async () => { + const sandbox = createFakeSandbox({ + execImpl: async () => + makeFakeProcess({ throwOnWait: new MockTimeoutError("exec timed out") }), + }); + mockSandboxesFromId.mockResolvedValue(sandbox); + + const result = await plugin.definition.onEnvironmentExecute?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { providerLeaseId: "sb-exec", metadata: {} }, + command: "sleep", + args: ["60"], + cwd: "/srv/work", + timeoutMs: 5_000, + }); + + expect(result).toEqual({ + exitCode: null, + timedOut: true, + stdout: "", + stderr: "exec timed out\n", + }); + }); + + it("returns an error result when execute is called without a provider lease id", async () => { + const result = await plugin.definition.onEnvironmentExecute?.({ + driverKey: "modal", + companyId: "c-1", + environmentId: "e-1", + config: baseConfig, + lease: { providerLeaseId: null, metadata: {} }, + command: "printf", + args: ["hello"], + }); + expect(result).toEqual({ + exitCode: 1, + timedOut: false, + stdout: "", + stderr: "No provider lease ID available for execution.", + }); + }); +}); diff --git a/packages/plugins/sandbox-providers/modal/src/plugin.ts b/packages/plugins/sandbox-providers/modal/src/plugin.ts new file mode 100644 index 00000000..2a3fbffb --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/src/plugin.ts @@ -0,0 +1,660 @@ +import { + ModalClient, + NotFoundError, + SandboxTimeoutError, + TimeoutError, + type App, + type ContainerProcess, + type Sandbox, + type SandboxCreateParams, +} from "modal"; +import { definePlugin } from "@paperclipai/plugin-sdk"; +import type { + PluginEnvironmentAcquireLeaseParams, + PluginEnvironmentDestroyLeaseParams, + PluginEnvironmentExecuteParams, + PluginEnvironmentExecuteResult, + PluginEnvironmentLease, + PluginEnvironmentProbeParams, + PluginEnvironmentProbeResult, + PluginEnvironmentRealizeWorkspaceParams, + PluginEnvironmentRealizeWorkspaceResult, + PluginEnvironmentReleaseLeaseParams, + PluginEnvironmentResumeLeaseParams, + PluginEnvironmentValidateConfigParams, + PluginEnvironmentValidationResult, +} from "@paperclipai/plugin-sdk"; + +const DEFAULT_WORKDIR = "/workspace/paperclip"; +const DEFAULT_SANDBOX_TIMEOUT_MS = 3_600_000; +const DEFAULT_EXEC_TIMEOUT_MS = 300_000; +const MAX_SANDBOX_TIMEOUT_MS = 86_400_000; + +interface ModalDriverConfig { + appName: string; + image: string; + tokenId: string | null; + tokenSecret: string | null; + environment: string | null; + workdir: string; + sandboxTimeoutMs: number; + idleTimeoutMs: number | null; + execTimeoutMs: number; + blockNetwork: boolean; + cidrAllowlist: string[] | null; + reuseLease: boolean; +} + +function parseOptionalString(value: unknown): string | null { + return typeof value === "string" && value.trim().length > 0 ? value.trim() : null; +} + +function parseOptionalNumber(value: unknown): number | null { + if (value == null || value === "") return null; + const parsed = Number(value); + return Number.isFinite(parsed) ? parsed : null; +} + +function parseStringArray(value: unknown): string[] | null { + if (!Array.isArray(value)) return null; + const trimmed = value + .filter((entry): entry is string => typeof entry === "string") + .map((entry) => entry.trim()) + .filter((entry) => entry.length > 0); + return trimmed.length > 0 ? trimmed : null; +} + +export function parseDriverConfig(raw: Record): ModalDriverConfig { + const sandboxTimeoutMsRaw = parseOptionalNumber(raw.sandboxTimeoutMs); + const execTimeoutMsRaw = parseOptionalNumber(raw.execTimeoutMs); + const idleTimeoutMsRaw = parseOptionalNumber(raw.idleTimeoutMs); + return { + appName: parseOptionalString(raw.appName) ?? "", + image: parseOptionalString(raw.image) ?? "", + tokenId: parseOptionalString(raw.tokenId), + tokenSecret: parseOptionalString(raw.tokenSecret), + environment: parseOptionalString(raw.environment), + workdir: parseOptionalString(raw.workdir) ?? DEFAULT_WORKDIR, + sandboxTimeoutMs: + sandboxTimeoutMsRaw != null ? Math.trunc(sandboxTimeoutMsRaw) : DEFAULT_SANDBOX_TIMEOUT_MS, + idleTimeoutMs: idleTimeoutMsRaw != null ? Math.trunc(idleTimeoutMsRaw) : null, + execTimeoutMs: + execTimeoutMsRaw != null ? Math.trunc(execTimeoutMsRaw) : DEFAULT_EXEC_TIMEOUT_MS, + blockNetwork: raw.blockNetwork === true, + cidrAllowlist: parseStringArray(raw.cidrAllowlist), + reuseLease: raw.reuseLease === true, + }; +} + +function isMultipleOf1000(value: number): boolean { + return value > 0 && value % 1000 === 0; +} + +function resolveAuth(config: ModalDriverConfig): { tokenId: string; tokenSecret: string } | null { + // The plugin worker runs in a child process that does not inherit host env + // vars (see PluginWorkerManager.spawnProcess), so MODAL_TOKEN_ID / + // MODAL_TOKEN_SECRET cannot be read here. Credentials must come from the + // environment config, which Paperclip stores as company secrets. + const tokenId = config.tokenId ?? ""; + const tokenSecret = config.tokenSecret ?? ""; + if (!tokenId && !tokenSecret) return null; + if (!tokenId || !tokenSecret) { + throw new Error("Modal sandbox environments require both tokenId and tokenSecret to be configured."); + } + return { tokenId, tokenSecret }; +} + +function createModalClient(config: ModalDriverConfig): ModalClient { + const auth = resolveAuth(config); + const params: ConstructorParameters[0] = {}; + if (auth) { + params.tokenId = auth.tokenId; + params.tokenSecret = auth.tokenSecret; + } + if (config.environment) { + params.environment = config.environment; + } + return new ModalClient(params); +} + +async function resolveApp(client: ModalClient, config: ModalDriverConfig): Promise { + return await client.apps.fromName(config.appName, { + createIfMissing: true, + environment: config.environment ?? undefined, + }); +} + +function buildSandboxCreateParams(input: { + config: ModalDriverConfig; + tags: Record; +}): SandboxCreateParams { + const params: SandboxCreateParams = { + workdir: input.config.workdir, + timeoutMs: input.config.sandboxTimeoutMs, + blockNetwork: input.config.blockNetwork, + }; + if (input.config.idleTimeoutMs != null) { + params.idleTimeoutMs = input.config.idleTimeoutMs; + } + if (input.config.cidrAllowlist && input.config.cidrAllowlist.length > 0) { + params.cidrAllowlist = input.config.cidrAllowlist; + } + // Modal sandboxes accept tag metadata via setTags after creation; the create + // RPC does not take tags directly. We pass them through input so the caller + // can apply them after `create` resolves. + void input.tags; + return params; +} + +function buildSandboxTags(input: { + companyId: string; + environmentId: string; + runId?: string; + reuseLease: boolean; +}): Record { + return { + "paperclip-provider": "modal", + "paperclip-company-id": input.companyId, + "paperclip-environment-id": input.environmentId, + "paperclip-reuse-lease": input.reuseLease ? "true" : "false", + ...(input.runId ? { "paperclip-run-id": input.runId } : {}), + }; +} + +async function createSandboxFor( + client: ModalClient, + app: App, + config: ModalDriverConfig, + tags: Record, +): Promise { + const image = client.images.fromRegistry(config.image); + const params = buildSandboxCreateParams({ config, tags }); + const sandbox = await client.sandboxes.create(app, image, params); + try { + await sandbox.setTags(tags); + } catch (error) { + // setTags is best-effort metadata; surface but do not block lease creation. + console.warn(`Failed to set tags on Modal sandbox ${sandbox.sandboxId}: ${formatErrorMessage(error)}`); + } + return sandbox; +} + +function leaseMetadata(input: { + config: ModalDriverConfig; + sandbox: Sandbox; + remoteCwd: string; + resumedLease: boolean; +}) { + return { + provider: "modal", + shellCommand: "sh", + sandboxId: input.sandbox.sandboxId, + appName: input.config.appName, + image: input.config.image, + sandboxTimeoutMs: input.config.sandboxTimeoutMs, + idleTimeoutMs: input.config.idleTimeoutMs, + reuseLease: input.config.reuseLease, + remoteCwd: input.remoteCwd, + resumedLease: input.resumedLease, + }; +} + +function formatErrorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} + +function shellQuote(value: string): string { + return `'${value.replace(/'/g, `'"'"'`)}'`; +} + +function isValidShellEnvKey(value: string): boolean { + return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value); +} + +// Modal's `sandbox.exec` takes an argv array and bypasses the shell entirely, +// so adapter probes that rely on PATH mutations from /etc/profile or ~/.bashrc +// do not work without an explicit login shell. Mirroring the Daytona / E2B +// providers, wrap the user command in a `sh -lc` script that sources common +// login profiles plus nvm before invoking it. Env is set after profile sourcing +// so caller env wins; stdin is staged to a temp file and shell-redirected so +// fast-failing commands do not race a streaming stdin writer. +function buildLoginShellScript(input: { + command: string; + args: string[]; + cwd?: string; + env?: Record; + stdinPath?: string; +}): string { + const env = input.env ?? {}; + for (const key of Object.keys(env)) { + if (!isValidShellEnvKey(key)) { + throw new Error(`Invalid sandbox environment variable key: ${key}`); + } + } + const envArgs = Object.entries(env) + .filter((entry): entry is [string, string] => typeof entry[1] === "string") + .map(([key, value]) => `${key}=${shellQuote(value)}`); + const commandParts = [shellQuote(input.command), ...input.args.map(shellQuote)].join(" "); + const redirected = input.stdinPath + ? `${commandParts} < ${shellQuote(input.stdinPath)}` + : commandParts; + const finalLine = envArgs.length > 0 ? `exec env ${envArgs.join(" ")} ${redirected}` : `exec ${redirected}`; + const lines = [ + 'if [ -f /etc/profile ]; then . /etc/profile >/dev/null 2>&1 || true; fi', + 'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi', + 'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; elif [ -f "$HOME/.bashrc" ]; then . "$HOME/.bashrc" >/dev/null 2>&1 || true; fi', + 'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi', + 'export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"', + '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" >/dev/null 2>&1 || true', + ]; + if (input.cwd) { + lines.push(`cd ${shellQuote(input.cwd)}`); + } + lines.push(finalLine); + return lines.join(" && "); +} + +async function ensureRemoteWorkspace(sandbox: Sandbox, remoteCwd: string): Promise { + // Use a one-shot exec to mkdir -p; Modal does not expose a direct + // filesystem mkdir helper and creating a file via `open()` does not create + // intermediate directories. + const proc = await sandbox.exec(["sh", "-lc", `mkdir -p ${shellQuote(remoteCwd)}`]); + const exitCode = await proc.wait(); + if (exitCode !== 0) { + throw new Error( + `Failed to create remote workspace directory '${remoteCwd}': mkdir exited with code ${exitCode}`, + ); + } +} + +async function stageStdin(sandbox: Sandbox, stdin: string, remotePath: string): Promise { + const file = await sandbox.open(remotePath, "w"); + try { + await file.write(new TextEncoder().encode(stdin)); + await file.flush(); + } finally { + await file.close().catch(() => undefined); + } +} + +async function deleteStdinPath(sandbox: Sandbox, remotePath: string): Promise { + // Best-effort cleanup of the staged stdin file. We swallow errors because + // it is fine for the file to outlive the sandbox if it is going to be + // terminated, and a missing rm tool would otherwise mask the real result. + try { + const proc = await sandbox.exec(["sh", "-lc", `rm -f ${shellQuote(remotePath)}`]); + await proc.wait(); + } catch { + // ignore + } +} + +async function readProcessStreams( + proc: ContainerProcess, +): Promise<{ stdout: string; stderr: string; exitCode: number }> { + const [stdout, stderr, exitCode] = await Promise.all([ + proc.stdout.readText(), + proc.stderr.readText(), + proc.wait(), + ]); + return { stdout, stderr, exitCode }; +} + +function isModalNotFound(error: unknown): boolean { + return error instanceof NotFoundError; +} + +async function getSandboxOrNull( + client: ModalClient, + providerLeaseId: string, +): Promise { + try { + return await client.sandboxes.fromId(providerLeaseId); + } catch (error) { + if (isModalNotFound(error)) return null; + throw error; + } +} + +function warnIfUnsupportedNode(logger: { warn: (msg: string) => void } | undefined): void { + const major = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10); + if (Number.isFinite(major) && major < 22) { + const message = `Modal sandbox provider is running on Node ${process.versions.node}; Modal officially supports Node 22+. The plugin will attempt to operate but vendor support is not guaranteed below Node 22.`; + logger?.warn(message); + } +} + +function leaseRemoteCwd(metadata: Record | undefined, fallback: string): string { + if (metadata && typeof metadata.remoteCwd === "string" && metadata.remoteCwd.trim().length > 0) { + return metadata.remoteCwd.trim(); + } + return fallback; +} + +const plugin = definePlugin({ + async setup(ctx) { + warnIfUnsupportedNode(ctx.logger); + ctx.logger.info("Modal sandbox provider plugin ready"); + }, + + async onHealth() { + return { status: "ok", message: "Modal sandbox provider plugin healthy" }; + }, + + async onEnvironmentValidateConfig( + params: PluginEnvironmentValidateConfigParams, + ): Promise { + const config = parseDriverConfig(params.config); + const errors: string[] = []; + + if (!config.appName) { + errors.push("Modal sandbox environments require an appName."); + } + if (!config.image) { + errors.push("Modal sandbox environments require an image reference."); + } + if ( + config.sandboxTimeoutMs < 1000 || + config.sandboxTimeoutMs > MAX_SANDBOX_TIMEOUT_MS || + !isMultipleOf1000(config.sandboxTimeoutMs) + ) { + errors.push( + "sandboxTimeoutMs must be a positive multiple of 1000 between 1000 and 86400000.", + ); + } + if ( + config.idleTimeoutMs != null && + (config.idleTimeoutMs < 1000 || !isMultipleOf1000(config.idleTimeoutMs)) + ) { + errors.push("idleTimeoutMs must be a positive multiple of 1000 when provided."); + } + if (config.execTimeoutMs < 1000 || !isMultipleOf1000(config.execTimeoutMs)) { + errors.push("execTimeoutMs must be a positive multiple of 1000."); + } + if (config.blockNetwork && config.cidrAllowlist && config.cidrAllowlist.length > 0) { + errors.push("cidrAllowlist cannot be combined with blockNetwork."); + } + const hasTokenId = Boolean(config.tokenId); + const hasTokenSecret = Boolean(config.tokenSecret); + if (hasTokenId !== hasTokenSecret) { + errors.push("tokenId and tokenSecret must both be provided when either is set."); + } else if (!hasTokenId) { + errors.push("Modal sandbox environments require tokenId and tokenSecret."); + } + + if (errors.length > 0) { + return { ok: false, errors }; + } + return { ok: true, normalizedConfig: { ...config } }; + }, + + async onEnvironmentProbe( + params: PluginEnvironmentProbeParams, + ): Promise { + const config = parseDriverConfig(params.config); + const tags = buildSandboxTags({ + companyId: params.companyId, + environmentId: params.environmentId, + reuseLease: false, + }); + const client = createModalClient(config); + try { + const app = await resolveApp(client, config); + const sandbox = await createSandboxFor(client, app, config, tags); + try { + await ensureRemoteWorkspace(sandbox, config.workdir); + const proc = await sandbox.exec(["sh", "-lc", "printf paperclip-probe"]); + const { stdout, exitCode } = await readProcessStreams(proc); + if (exitCode !== 0 || stdout.trim() !== "paperclip-probe") { + return { + ok: false, + summary: `Modal sandbox probe failed: exit ${exitCode}, stdout=${JSON.stringify(stdout)}`, + metadata: { + provider: "modal", + sandboxId: sandbox.sandboxId, + appName: config.appName, + image: config.image, + }, + }; + } + return { + ok: true, + summary: `Connected to Modal sandbox in app ${config.appName}.`, + metadata: { + provider: "modal", + sandboxId: sandbox.sandboxId, + appName: config.appName, + image: config.image, + workdir: config.workdir, + sandboxTimeoutMs: config.sandboxTimeoutMs, + idleTimeoutMs: config.idleTimeoutMs, + reuseLease: config.reuseLease, + remoteCwd: config.workdir, + }, + }; + } finally { + await sandbox.terminate().catch(() => undefined); + } + } catch (error) { + return { + ok: false, + summary: "Modal sandbox probe failed.", + metadata: { + provider: "modal", + appName: config.appName, + image: config.image, + reuseLease: config.reuseLease, + error: formatErrorMessage(error), + }, + }; + } finally { + client.close(); + } + }, + + async onEnvironmentAcquireLease( + params: PluginEnvironmentAcquireLeaseParams, + ): Promise { + const config = parseDriverConfig(params.config); + const client = createModalClient(config); + try { + const app = await resolveApp(client, config); + const tags = buildSandboxTags({ + companyId: params.companyId, + environmentId: params.environmentId, + runId: params.runId, + reuseLease: config.reuseLease, + }); + const sandbox = await createSandboxFor(client, app, config, tags); + try { + await ensureRemoteWorkspace(sandbox, config.workdir); + return { + providerLeaseId: sandbox.sandboxId, + metadata: leaseMetadata({ + config, + sandbox, + remoteCwd: config.workdir, + resumedLease: false, + }), + }; + } catch (error) { + await sandbox.terminate().catch(() => undefined); + throw error; + } + } finally { + // Keep the client open for the lease lifetime is unnecessary; subsequent + // calls construct their own client. Close the local handle to free + // grpc resources. + client.close(); + } + }, + + async onEnvironmentResumeLease( + params: PluginEnvironmentResumeLeaseParams, + ): Promise { + const config = parseDriverConfig(params.config); + const client = createModalClient(config); + try { + const sandbox = await getSandboxOrNull(client, params.providerLeaseId); + if (!sandbox) { + return { providerLeaseId: null, metadata: { expired: true } }; + } + try { + await ensureRemoteWorkspace(sandbox, config.workdir); + return { + providerLeaseId: sandbox.sandboxId, + metadata: leaseMetadata({ config, sandbox, remoteCwd: config.workdir, resumedLease: true }), + }; + } catch (error) { + // If we just resumed and workspace setup blew up, treat as a lease + // failure rather than silently terminating the user's reusable + // sandbox. Detach so the sandbox is not killed for a transient setup + // error. + void sandbox.detach(); + throw error; + } + } finally { + client.close(); + } + }, + + async onEnvironmentReleaseLease( + params: PluginEnvironmentReleaseLeaseParams, + ): Promise { + if (!params.providerLeaseId) return; + const config = parseDriverConfig(params.config); + const client = createModalClient(config); + try { + const sandbox = await getSandboxOrNull(client, params.providerLeaseId); + if (!sandbox) return; + if (config.reuseLease) { + // Modal has no separate pause primitive. Detaching releases the local + // grpc connection but leaves the sandbox running on Modal until its + // configured sandboxTimeoutMs or idleTimeoutMs expires. The next + // acquire/resume reconnects via sandboxes.fromId(providerLeaseId). + void sandbox.detach(); + return; + } + await sandbox.terminate(); + } finally { + client.close(); + } + }, + + async onEnvironmentDestroyLease( + params: PluginEnvironmentDestroyLeaseParams, + ): Promise { + if (!params.providerLeaseId) return; + const config = parseDriverConfig(params.config); + const client = createModalClient(config); + try { + const sandbox = await getSandboxOrNull(client, params.providerLeaseId); + if (!sandbox) return; + await sandbox.terminate(); + } finally { + client.close(); + } + }, + + async onEnvironmentRealizeWorkspace( + params: PluginEnvironmentRealizeWorkspaceParams, + ): Promise { + const config = parseDriverConfig(params.config); + const fallback = + params.workspace.remotePath ?? + params.workspace.localPath ?? + config.workdir; + const remoteCwd = leaseRemoteCwd(params.lease.metadata, fallback); + if (params.lease.providerLeaseId) { + const client = createModalClient(config); + try { + const sandbox = await getSandboxOrNull(client, params.lease.providerLeaseId); + if (sandbox) { + await ensureRemoteWorkspace(sandbox, remoteCwd); + } + } finally { + client.close(); + } + } + return { + cwd: remoteCwd, + metadata: { provider: "modal", remoteCwd }, + }; + }, + + async onEnvironmentExecute( + params: PluginEnvironmentExecuteParams, + ): Promise { + if (!params.lease.providerLeaseId) { + return { + exitCode: 1, + timedOut: false, + stdout: "", + stderr: "No provider lease ID available for execution.", + }; + } + const config = parseDriverConfig(params.config); + const client = createModalClient(config); + const callerTimeoutMs = + params.timeoutMs != null && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0 + ? Math.max(1000, Math.trunc(params.timeoutMs / 1000) * 1000) + : config.execTimeoutMs; + + try { + const sandbox = await getSandboxOrNull(client, params.lease.providerLeaseId); + if (!sandbox) { + return { + exitCode: 1, + timedOut: false, + stdout: "", + stderr: "Modal sandbox lease is no longer available.\n", + }; + } + const stdinPath = params.stdin != null + ? `/tmp/paperclip-stdin-${Date.now()}-${Math.random().toString(36).slice(2, 10)}` + : null; + try { + if (stdinPath && params.stdin != null) { + await stageStdin(sandbox, params.stdin, stdinPath); + } + const script = buildLoginShellScript({ + command: params.command, + args: params.args ?? [], + cwd: params.cwd ?? config.workdir, + env: params.env, + stdinPath: stdinPath ?? undefined, + }); + const proc = await sandbox.exec(["sh", "-lc", script], { + timeoutMs: callerTimeoutMs, + stdout: "pipe", + stderr: "pipe", + }); + const { stdout, stderr, exitCode } = await readProcessStreams(proc); + return { + exitCode, + timedOut: false, + stdout, + stderr, + }; + } catch (error) { + if (error instanceof TimeoutError || error instanceof SandboxTimeoutError) { + return { + exitCode: null, + timedOut: true, + stdout: "", + stderr: `${formatErrorMessage(error)}\n`, + }; + } + throw error; + } finally { + if (stdinPath) { + await deleteStdinPath(sandbox, stdinPath); + } + } + } finally { + client.close(); + } + }, +}); + +export default plugin; diff --git a/packages/plugins/sandbox-providers/modal/src/worker.ts b/packages/plugins/sandbox-providers/modal/src/worker.ts new file mode 100644 index 00000000..1e156024 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/src/worker.ts @@ -0,0 +1,5 @@ +import { runWorker } from "@paperclipai/plugin-sdk"; +import plugin from "./plugin.js"; + +export default plugin; +runWorker(plugin, import.meta.url); diff --git a/packages/plugins/sandbox-providers/modal/tsconfig.json b/packages/plugins/sandbox-providers/modal/tsconfig.json new file mode 100644 index 00000000..000e3293 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../../tsconfig.json", + "compilerOptions": { + "outDir": "dist", + "rootDir": "src", + "lib": ["ES2023"], + "types": ["node"] + }, + "include": ["src"], + "exclude": ["src/**/*.test.ts"] +} diff --git a/packages/plugins/sandbox-providers/modal/vitest.config.ts b/packages/plugins/sandbox-providers/modal/vitest.config.ts new file mode 100644 index 00000000..ce36a742 --- /dev/null +++ b/packages/plugins/sandbox-providers/modal/vitest.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + include: ["src/**/*.test.ts"], + environment: "node", + }, +}); diff --git a/scripts/release-package-manifest.json b/scripts/release-package-manifest.json index 026bb467..f5122cbd 100644 --- a/scripts/release-package-manifest.json +++ b/scripts/release-package-manifest.json @@ -114,6 +114,11 @@ "name": "@paperclipai/plugin-e2b", "publishFromCi": true }, + { + "dir": "packages/plugins/sandbox-providers/modal", + "name": "@paperclipai/plugin-modal", + "publishFromCi": false + }, { "dir": "ui", "name": "@paperclipai/ui",