From 504a33b6fa0821ca62f32cc85a3f6acdb9f432d0 Mon Sep 17 00:00:00 2001 From: AsperforMias Date: Fri, 17 Jul 2026 02:20:21 +0800 Subject: [PATCH 1/4] fix(environment): verify package manager capabilities --- .containerignore | 3 + Containerfile | 21 +- environment-package-managers.json | 4 + package.json | 5 +- scripts/environment-package-manager-check.mjs | 194 ++++++++++++++++++ 5 files changed, 220 insertions(+), 7 deletions(-) create mode 100644 environment-package-managers.json create mode 100644 scripts/environment-package-manager-check.mjs diff --git a/.containerignore b/.containerignore index 28580b8..7345b1a 100644 --- a/.containerignore +++ b/.containerignore @@ -1,4 +1,7 @@ * !Containerfile +!environment-package-managers.json +!scripts/ +!scripts/environment-package-manager-check.mjs !dist/ !dist/driver.mjs diff --git a/Containerfile b/Containerfile index b330db3..73b2012 100644 --- a/Containerfile +++ b/Containerfile @@ -1,4 +1,4 @@ -FROM cloudflare/sandbox:0.12.3 +FROM cloudflare/sandbox:0.12.3@sha256:23f67e16131b780865a5fa5aa3c8607408a730105c248836409f4e02bb6bf042 # Keep the default base image version in sync with apps/api/package.json -> @cloudflare/sandbox. ARG CLAUDE_AGENT_SDK_VERSION=0.3.211 @@ -6,12 +6,21 @@ ARG ANTHROPIC_SDK_VERSION=0.111.0 ARG OPENAI_RUNTIME_VERSION=0.144.5 ARG OPENCODE_VERSION=1.18.4 -# Environment package setup invokes `pip`, so the runtime image must provide it. +# Install the Python runtime behind writable pip package declarations. RUN apt-get update \ - && apt-get install -y --no-install-recommends python3-pip python-is-python3 \ - && rm -rf /var/lib/apt/lists/* \ - && python --version \ - && pip --version + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + python3 \ + python3-pip \ + python-is-python3 \ + && rm -rf /var/lib/apt/lists/* + +COPY environment-package-managers.json /etc/mosoo/environment-package-managers.json +COPY scripts/environment-package-manager-check.mjs /usr/local/libexec/mosoo/environment-package-manager-check.mjs + +# Environment writes expose only package managers verified by this image. +# Check executables, parseable versions, and runtime aliases here so capability +# failures surface while building the image rather than during a user Run. +RUN node /usr/local/libexec/mosoo/environment-package-manager-check.mjs verify # Native agent CLIs pre-installed so the driver can spawn them via PATH. # Installed in a single npm invocation to keep the agent packages in one layer. diff --git a/environment-package-managers.json b/environment-package-managers.json new file mode 100644 index 0000000..dc049c8 --- /dev/null +++ b/environment-package-managers.json @@ -0,0 +1,4 @@ +{ + "schemaVersion": 1, + "managers": ["npm", "pip"] +} diff --git a/package.json b/package.json index 72cbace..61f0c15 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,9 @@ "files": [ "dist", "src", - "assets" + "assets", + "environment-package-managers.json", + "scripts/environment-package-manager-check.mjs" ], "type": "module", "types": "./dist/types/index.d.ts", @@ -84,6 +86,7 @@ "build": "vp run build:types && bun build src/bin/driver.ts --target bun --outfile dist/driver.mjs", "build:types": "rm -rf dist/types && vp exec tsc -p tsconfig.types.json", "build:image": "vp run build && buildah build -t agent-driver:local .", + "docker:smoke:environment": "docker run --rm --entrypoint node agent-driver:local /usr/local/libexec/mosoo/environment-package-manager-check.mjs smoke", "check": "vp check && vp run tc && vp run test && vp run build", "prepack": "vp run build" }, diff --git a/scripts/environment-package-manager-check.mjs b/scripts/environment-package-manager-check.mjs new file mode 100644 index 0000000..727e08d --- /dev/null +++ b/scripts/environment-package-manager-check.mjs @@ -0,0 +1,194 @@ +import { execFileSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +const mode = process.argv[2] ?? "smoke"; +const manifestPath = + process.env.MOSOO_ENVIRONMENT_PACKAGE_MANAGER_MANIFEST ?? + "/etc/mosoo/environment-package-managers.json"; +const SEMANTIC_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u; + +function fail(message) { + console.error(message); + process.exit(1); +} + +function readManifest() { + let manifest; + try { + manifest = JSON.parse(readFileSync(manifestPath, "utf8")); + } catch (error) { + fail( + `Invalid Environment package-manager manifest: ${ + error instanceof Error ? error.message : String(error) + }`, + ); + } + + if (manifest?.schemaVersion !== 1) { + fail("Invalid Environment package-manager manifest: schemaVersion must be 1"); + } + if (!Array.isArray(manifest.managers) || manifest.managers.length === 0) { + fail("Invalid Environment package-manager manifest: managers must be a non-empty array"); + } + + const seen = new Set(); + for (const manager of manifest.managers) { + if (typeof manager !== "string" || !/^[a-z][a-z0-9-]*$/.test(manager)) { + fail(`Invalid Environment package-manager manifest: invalid manager ${String(manager)}`); + } + if (seen.has(manager)) { + fail(`Invalid Environment package-manager manifest: duplicate manager ${manager}`); + } + seen.add(manager); + } + + return manifest.managers; +} + +function readCommandOutput(command, args, options = {}) { + try { + return execFileSync(command, args, { encoding: "utf8", ...options }).trim(); + } catch (error) { + fail(`${command} failed: ${error instanceof Error ? error.message : String(error)}`); + } +} + +function runCommand(command, args, options = {}) { + try { + execFileSync(command, args, { stdio: "inherit", ...options }); + } catch (error) { + fail(`${command} failed: ${error instanceof Error ? error.message : String(error)}`); + } +} + +function withTemporaryRoot(manager, callback) { + const root = mkdtempSync(join(tmpdir(), `mosoo-environment-${manager}-`)); + + try { + callback(root); + } finally { + rmSync(root, { force: true, recursive: true }); + } +} + +function assertExactVersion(tool, expected, actual) { + if (actual !== expected) { + fail(`${tool} version mismatch: expected ${expected}, got ${actual}`); + } +} + +function assertSemanticVersion(tool, version) { + if (!SEMANTIC_VERSION.test(version)) { + fail(`${tool} returned an invalid version: ${version || ""}`); + } + return version; +} + +function readSemanticVersion(tool, command, args, prefix = "") { + const output = readCommandOutput(command, args); + if (!output.startsWith(prefix)) { + fail(`${tool} returned an invalid version: ${output || ""}`); + } + return assertSemanticVersion(tool, output.slice(prefix.length)); +} + +function readPipVersion(tool, command, args) { + const output = readCommandOutput(command, args); + const match = /^pip (\S+) /u.exec(output); + return assertSemanticVersion(tool, match?.[1] ?? ""); +} + +function assertMatchingVersions(leftTool, leftVersion, rightTool, rightVersion) { + if (leftVersion !== rightVersion) { + fail(`${leftTool} and ${rightTool} versions do not match: ${leftVersion} != ${rightVersion}`); + } +} + +const managerChecks = new Map([ + [ + "npm", + { + verify() { + const nodeVersion = readSemanticVersion("node", "node", ["--version"], "v"); + const npmVersion = readSemanticVersion("npm", "npm", ["--version"]); + console.log(`Verified node ${nodeVersion} and npm ${npmVersion}.`); + }, + smoke() { + withTemporaryRoot("npm", (root) => { + const npmRoot = join(root, "npm"); + runCommand("npm", [ + "install", + "--prefix", + npmRoot, + "--no-audit", + "--no-fund", + "--save-exact", + "prettier@3.3.3", + ]); + assertExactVersion( + "prettier", + "3.3.3", + readCommandOutput(join(npmRoot, "node_modules", ".bin", "prettier"), ["--version"]), + ); + }); + }, + }, + ], + [ + "pip", + { + verify() { + const pythonVersion = readSemanticVersion("python", "python", ["--version"], "Python "); + const python3Version = readSemanticVersion("python3", "python3", ["--version"], "Python "); + assertMatchingVersions("python", pythonVersion, "python3", python3Version); + + const pipVersion = readPipVersion("pip", "pip", ["--version"]); + const modulePipVersion = readPipVersion("python -m pip", "python", [ + "-m", + "pip", + "--version", + ]); + assertMatchingVersions("pip", pipVersion, "python -m pip", modulePipVersion); + console.log(`Verified python ${pythonVersion} and pip ${pipVersion}.`); + }, + smoke() { + withTemporaryRoot("pip", (root) => { + const pipRoot = join(root, "python"); + runCommand("python", [ + "-m", + "pip", + "install", + "--disable-pip-version-check", + "--no-input", + "--ignore-installed", + "--prefix", + pipRoot, + "six==1.16.0", + ]); + const pythonSite = readCommandOutput("python", [ + "-c", + 'import sys,sysconfig; p=sys.argv[1]; print(sysconfig.get_path("purelib",vars={"base":p,"platbase":p}))', + pipRoot, + ]); + runCommand("python", ["-c", 'import six; assert six.__version__ == "1.16.0"'], { + env: { ...process.env, PYTHONPATH: pythonSite }, + }); + }); + }, + }, + ], +]); + +if (mode !== "verify" && mode !== "smoke") { + fail(`Unsupported Environment package-manager check mode: ${mode}`); +} + +for (const manager of readManifest()) { + const check = managerChecks.get(manager); + if (!check) { + fail(`Environment package manager has no ${mode} check: ${manager}`); + } + check[mode](); +} From c51636b1d468edf18b69afe1cc2e5cfd8af5de2c Mon Sep 17 00:00:00 2001 From: AsperforMias Date: Fri, 17 Jul 2026 02:20:48 +0800 Subject: [PATCH 2/4] test(environment): cover package manager capability contract --- tests/driver-artifact-contract.test.ts | 75 +++++++++++++++++++++++++- 1 file changed, 73 insertions(+), 2 deletions(-) diff --git a/tests/driver-artifact-contract.test.ts b/tests/driver-artifact-contract.test.ts index 5c5f6e9..a30b00d 100644 --- a/tests/driver-artifact-contract.test.ts +++ b/tests/driver-artifact-contract.test.ts @@ -33,6 +33,11 @@ interface DriverPackageJson { readonly version?: string; } +interface EnvironmentPackageManagerManifest { + readonly managers?: readonly string[]; + readonly schemaVersion?: number; +} + const PUBLIC_EXPORTS = [ ".", "./boot", @@ -54,6 +59,12 @@ function readDriverPackageJson(): DriverPackageJson { return JSON.parse(readText("../package.json")) as DriverPackageJson; } +function readEnvironmentPackageManagerManifest(): EnvironmentPackageManagerManifest { + return JSON.parse( + readText("../environment-package-managers.json"), + ) as EnvironmentPackageManagerManifest; +} + describe("driver artifact contract", () => { test("uses the public mosoo package identity", () => { const packageJson = readDriverPackageJson(); @@ -79,7 +90,15 @@ describe("driver artifact contract", () => { "agent-driver": "./dist/driver.mjs", }); expect(packageJson.types).toBe("./dist/types/index.d.ts"); - expect(packageJson.files).toEqual(["dist", "src", "assets"]); + expect(packageJson.files).toEqual( + expect.arrayContaining([ + "dist", + "src", + "assets", + "environment-package-managers.json", + "scripts/environment-package-manager-check.mjs", + ]), + ); expect(packageJson.files).not.toContain("tests/fixtures"); }); @@ -209,7 +228,59 @@ describe("driver artifact contract", () => { expect(imageIndex).toBeGreaterThan(liveIndex); }); - test("keeps the standalone package out of mosoo workspace dependencies", () => { + test("declares and verifies writable Environment package managers", () => { + const manifest = readEnvironmentPackageManagerManifest(); + const packageJson = readDriverPackageJson(); + const containerfile = readText("../Containerfile"); + const containerignore = readText("../.containerignore"); + const packageManagerCheck = readText("../scripts/environment-package-manager-check.mjs"); + + expect(manifest).toEqual({ + managers: ["npm", "pip"], + schemaVersion: 1, + }); + expect(containerfile).toContain( + "FROM cloudflare/sandbox:0.12.3@sha256:23f67e16131b780865a5fa5aa3c8607408a730105c248836409f4e02bb6bf042", + ); + expect(containerfile).not.toContain("EXPECTED_NODE_VERSION"); + expect(containerfile).not.toContain("EXPECTED_NPM_VERSION"); + expect(containerfile).not.toContain("EXPECTED_PYTHON_VERSION"); + expect(containerfile).not.toContain("EXPECTED_PIP_VERSION"); + expect(containerfile).not.toContain("ENV PIP_"); + expect(containerfile).not.toContain('sed -i "s|http://|https://|g"'); + expect(containerfile).toContain("python-is-python3"); + expect(containerfile).toContain( + "COPY environment-package-managers.json /etc/mosoo/environment-package-managers.json", + ); + expect(containerfile).toContain( + "COPY scripts/environment-package-manager-check.mjs /usr/local/libexec/mosoo/environment-package-manager-check.mjs", + ); + expect(containerfile).toContain( + "node /usr/local/libexec/mosoo/environment-package-manager-check.mjs verify", + ); + expect(containerfile).not.toContain('manifest.managers.join(",")'); + expect(containerignore).toContain("!environment-package-managers.json"); + expect(containerignore).toContain("!scripts/environment-package-manager-check.mjs"); + expect(packageManagerCheck).toContain("MOSOO_ENVIRONMENT_PACKAGE_MANAGER_MANIFEST"); + expect(packageManagerCheck).not.toContain("EXPECTED_NODE_VERSION"); + expect(packageManagerCheck).not.toContain("EXPECTED_NPM_VERSION"); + expect(packageManagerCheck).not.toContain("EXPECTED_PYTHON_VERSION"); + expect(packageManagerCheck).not.toContain("EXPECTED_PIP_VERSION"); + expect(packageManagerCheck).toContain( + 'readSemanticVersion("node", "node", ["--version"], "v")', + ); + expect(packageManagerCheck).toContain("assertMatchingVersions"); + expect(packageManagerCheck).toContain("prettier@3.3.3"); + expect(packageManagerCheck).toContain("six==1.16.0"); + expect(packageManagerCheck).toContain('readPipVersion("python -m pip", "python", ['); + expect(packageManagerCheck).toContain('"--prefix"'); + expect(packageManagerCheck).not.toContain('"-g"'); + expect(packageJson.scripts?.["docker:smoke:environment"]).toContain( + "/usr/local/libexec/mosoo/environment-package-manager-check.mjs smoke", + ); + }); + + test("keeps the standalone package out of Mosoo workspace dependencies", () => { const packageJson = readDriverPackageJson(); const deps = Object.keys(packageJson.dependencies ?? {}); const tsconfig = readText("../tsconfig.json"); From 32c56b316659d8a4cceacf87899afe20929209b4 Mon Sep 17 00:00:00 2001 From: AsperforMias Date: Fri, 17 Jul 2026 02:21:11 +0800 Subject: [PATCH 3/4] docs(environment): document package manager capability checks --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index aace195..b22e8ef 100644 --- a/README.md +++ b/README.md @@ -160,6 +160,8 @@ vp run clean `vp run build:image` uses Buildah to produce a local `agent-driver:local` OCI image and installs `dist/driver.mjs` on the image `PATH` as `agent-driver`. +The image contract in `environment-package-managers.json` exposes `npm` and `pip` to Mosoo Environment writes. The image build verifies that each tool is executable, reports a valid version, and resolves through coherent Python/pip aliases. `vp run docker:smoke:environment` installs and executes one pinned package through each manager using the same isolated-prefix mode as Mosoo Environment artifacts. + ## Boundaries - The Driver Kernel owns command dispatch, runtime event emission, provider lifecycle, permission flow, diagnostics, and host port contracts. @@ -174,6 +176,7 @@ vp run clean - `vp run check` - `vp run build:image` +- `vp run docker:smoke:environment` - no `@mosoo/*` runtime dependencies in `package.json` - public entries include typed exports - live artifact tests are gated by environment credentials From 2f070ba144bbf4621e07eb9dd0c4f189a123c5b6 Mon Sep 17 00:00:00 2001 From: AsperforMias Date: Fri, 17 Jul 2026 22:01:46 +0800 Subject: [PATCH 4/4] refactor(environment): narrow package manager contract scope --- Containerfile | 2 +- package.json | 4 +- tests/driver-artifact-contract.test.ts | 55 +------------------------- 3 files changed, 4 insertions(+), 57 deletions(-) diff --git a/Containerfile b/Containerfile index 73b2012..c3bfdb8 100644 --- a/Containerfile +++ b/Containerfile @@ -1,4 +1,4 @@ -FROM cloudflare/sandbox:0.12.3@sha256:23f67e16131b780865a5fa5aa3c8607408a730105c248836409f4e02bb6bf042 +FROM cloudflare/sandbox:0.12.3 # Keep the default base image version in sync with apps/api/package.json -> @cloudflare/sandbox. ARG CLAUDE_AGENT_SDK_VERSION=0.3.211 diff --git a/package.json b/package.json index 61f0c15..8bbde38 100644 --- a/package.json +++ b/package.json @@ -18,9 +18,7 @@ "files": [ "dist", "src", - "assets", - "environment-package-managers.json", - "scripts/environment-package-manager-check.mjs" + "assets" ], "type": "module", "types": "./dist/types/index.d.ts", diff --git a/tests/driver-artifact-contract.test.ts b/tests/driver-artifact-contract.test.ts index a30b00d..9d408bd 100644 --- a/tests/driver-artifact-contract.test.ts +++ b/tests/driver-artifact-contract.test.ts @@ -90,15 +90,7 @@ describe("driver artifact contract", () => { "agent-driver": "./dist/driver.mjs", }); expect(packageJson.types).toBe("./dist/types/index.d.ts"); - expect(packageJson.files).toEqual( - expect.arrayContaining([ - "dist", - "src", - "assets", - "environment-package-managers.json", - "scripts/environment-package-manager-check.mjs", - ]), - ); + expect(packageJson.files).toEqual(["dist", "src", "assets"]); expect(packageJson.files).not.toContain("tests/fixtures"); }); @@ -228,56 +220,13 @@ describe("driver artifact contract", () => { expect(imageIndex).toBeGreaterThan(liveIndex); }); - test("declares and verifies writable Environment package managers", () => { + test("declares writable Environment package managers", () => { const manifest = readEnvironmentPackageManagerManifest(); - const packageJson = readDriverPackageJson(); - const containerfile = readText("../Containerfile"); - const containerignore = readText("../.containerignore"); - const packageManagerCheck = readText("../scripts/environment-package-manager-check.mjs"); expect(manifest).toEqual({ managers: ["npm", "pip"], schemaVersion: 1, }); - expect(containerfile).toContain( - "FROM cloudflare/sandbox:0.12.3@sha256:23f67e16131b780865a5fa5aa3c8607408a730105c248836409f4e02bb6bf042", - ); - expect(containerfile).not.toContain("EXPECTED_NODE_VERSION"); - expect(containerfile).not.toContain("EXPECTED_NPM_VERSION"); - expect(containerfile).not.toContain("EXPECTED_PYTHON_VERSION"); - expect(containerfile).not.toContain("EXPECTED_PIP_VERSION"); - expect(containerfile).not.toContain("ENV PIP_"); - expect(containerfile).not.toContain('sed -i "s|http://|https://|g"'); - expect(containerfile).toContain("python-is-python3"); - expect(containerfile).toContain( - "COPY environment-package-managers.json /etc/mosoo/environment-package-managers.json", - ); - expect(containerfile).toContain( - "COPY scripts/environment-package-manager-check.mjs /usr/local/libexec/mosoo/environment-package-manager-check.mjs", - ); - expect(containerfile).toContain( - "node /usr/local/libexec/mosoo/environment-package-manager-check.mjs verify", - ); - expect(containerfile).not.toContain('manifest.managers.join(",")'); - expect(containerignore).toContain("!environment-package-managers.json"); - expect(containerignore).toContain("!scripts/environment-package-manager-check.mjs"); - expect(packageManagerCheck).toContain("MOSOO_ENVIRONMENT_PACKAGE_MANAGER_MANIFEST"); - expect(packageManagerCheck).not.toContain("EXPECTED_NODE_VERSION"); - expect(packageManagerCheck).not.toContain("EXPECTED_NPM_VERSION"); - expect(packageManagerCheck).not.toContain("EXPECTED_PYTHON_VERSION"); - expect(packageManagerCheck).not.toContain("EXPECTED_PIP_VERSION"); - expect(packageManagerCheck).toContain( - 'readSemanticVersion("node", "node", ["--version"], "v")', - ); - expect(packageManagerCheck).toContain("assertMatchingVersions"); - expect(packageManagerCheck).toContain("prettier@3.3.3"); - expect(packageManagerCheck).toContain("six==1.16.0"); - expect(packageManagerCheck).toContain('readPipVersion("python -m pip", "python", ['); - expect(packageManagerCheck).toContain('"--prefix"'); - expect(packageManagerCheck).not.toContain('"-g"'); - expect(packageJson.scripts?.["docker:smoke:environment"]).toContain( - "/usr/local/libexec/mosoo/environment-package-manager-check.mjs smoke", - ); }); test("keeps the standalone package out of Mosoo workspace dependencies", () => {