@vulcan-energy/mcp-helper 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/THIRD_PARTY_NOTICES.md +2 -2
- package/dist/bin/vulcan-mcp-helper.js +29 -29
- package/dist/hem-target-runtime/browser-adapter.mjs +20 -9
- package/dist/hem-target-runtime/host.mjs +112 -31
- package/dist/hem-target-runtime/preparation.mjs +20332 -13457
- package/dist/hem-target-runtime/python-worker.mjs +2885 -680
- package/dist/hem-target-runtime/release-manifests.mjs +32 -29
- package/dist/hem-target-runtime/rust-worker.mjs +2464 -39
- package/dist/server.js +26 -26
- package/package.json +1 -1
- package/wasm/wasm_version.json +9 -9
- package/wasm/wasm_wrapper.js +6 -6
- package/wasm/wasm_wrapper_bg.wasm +0 -0
|
@@ -9,13 +9,16 @@ import { fileURLToPath } from 'node:url';
|
|
|
9
9
|
|
|
10
10
|
const hash = bytes => createHash('sha256').update(bytes).digest('hex');
|
|
11
11
|
const RELEASE_ORIGIN = 'https://usevulcan.app';
|
|
12
|
+
// Catalogue ids: lower-case words joined by '-' or '.' (the EPC id carries its version, 0.13.2); never '..'.
|
|
13
|
+
const BUNDLE_ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
|
|
12
14
|
// As targets.ts:modelArtifacts: not source archives or notices, and not a pinned converter
|
|
13
15
|
// that is not also the runtime. The host converts with the package's own WASM.
|
|
14
16
|
const isModelArtifact = (manifest, path) => !path.startsWith('source/') && !path.startsWith('notices/')
|
|
15
17
|
&& !([manifest.preparation?.javascript, manifest.preparation?.wasm].includes(path) && ![manifest.runtime?.javascript, manifest.runtime?.wasm].includes(path));
|
|
16
|
-
// Preparation reads only the pinned schema and
|
|
18
|
+
// Preparation reads only the pinned schema, defaults and product data (targetPreparation.ts:preparationManifest).
|
|
17
19
|
const isSelected = (manifest, path, preparationOnly) => preparationOnly
|
|
18
|
-
? [manifest.preparation?.schema, manifest.preparation?.defaults].includes(path)
|
|
20
|
+
? [manifest.preparation?.schema, manifest.preparation?.defaults].includes(path) || (!!manifest.runtime?.data && path.startsWith(manifest.runtime.data))
|
|
21
|
+
: isModelArtifact(manifest, path);
|
|
19
22
|
function assertArtifactPath(path) {
|
|
20
23
|
if (!path || path.includes('\\') || path.startsWith('/') || path.split('/').some(part => !part || part === '..' || part === '.')) throw new Error('Invalid target artifact path');
|
|
21
24
|
}
|
|
@@ -24,7 +27,7 @@ export async function readVerifiedBundle(manifestPath, expectedHash, { preparati
|
|
|
24
27
|
const bytes = await readFile(manifestPath);
|
|
25
28
|
if (hash(bytes) !== expectedHash) throw new Error('Target manifest hash mismatch');
|
|
26
29
|
const manifest = JSON.parse(bytes);
|
|
27
|
-
if (
|
|
30
|
+
if (!BUNDLE_ID.test(manifest.bundleId ?? '') || !Array.isArray(manifest.artifacts)) throw new Error('Invalid target manifest');
|
|
28
31
|
const root = await realpath(dirname(manifestPath));
|
|
29
32
|
const routes = new Map();
|
|
30
33
|
for (const artifact of manifest.artifacts) {
|
|
@@ -39,12 +42,18 @@ export async function readVerifiedBundle(manifestPath, expectedHash, { preparati
|
|
|
39
42
|
return { manifest, routes };
|
|
40
43
|
}
|
|
41
44
|
|
|
45
|
+
async function releaseTables() {
|
|
46
|
+
try { return await import('./release-manifests.mjs'); }
|
|
47
|
+
catch { throw new Error('HEM target release pins are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
|
|
48
|
+
}
|
|
49
|
+
/** The target a saved pin runs on: the replacement of a retired pin (targets.ts RETIRED_HEM_TARGETS), else the pin. */
|
|
50
|
+
export async function currentBundleId(bundleId, retired) {
|
|
51
|
+
retired ??= (await releaseTables()).RETIRED_HEM_TARGETS;
|
|
52
|
+
return Object.hasOwn(retired, bundleId) ? retired[bundleId].replacement : bundleId;
|
|
53
|
+
}
|
|
42
54
|
async function releasePin(bundleId, pins) {
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
catch { throw new Error('HEM target release pins are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
|
|
46
|
-
}
|
|
47
|
-
const expected = /^[a-z0-9-]+$/.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
|
|
55
|
+
pins ??= (await releaseTables()).RELEASE_MANIFEST_HASHES;
|
|
56
|
+
const expected = BUNDLE_ID.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
|
|
48
57
|
if (!expected) throw new Error(`HEM target '${bundleId}' is not supported by this version; update @vulcan-energy/mcp-helper or @vulcan-energy/analyst, whichever you are running`);
|
|
49
58
|
return expected;
|
|
50
59
|
}
|
|
@@ -74,7 +83,9 @@ async function fetchBytes(fetcher, bundleId, url, timeoutMs, root) {
|
|
|
74
83
|
|
|
75
84
|
/** Resolve a released bundle into a local cache, verified against the pins compiled into this helper. */
|
|
76
85
|
// The user cache (XDG_CACHE_HOME, as other tools read it); a host whose home is read-only sets it.
|
|
77
|
-
export async function resolveReleaseBundle(
|
|
86
|
+
export async function resolveReleaseBundle(savedBundleId, { cacheDir = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, retired, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS, preparationOnly = false } = {}) {
|
|
87
|
+
// A test that supplies pins supplies the retired table with them, or none.
|
|
88
|
+
const bundleId = await currentBundleId(savedBundleId, retired ?? (pins ? {} : undefined));
|
|
78
89
|
const expected = await releasePin(bundleId, pins);
|
|
79
90
|
const root = join(cacheDir, bundleId);
|
|
80
91
|
const manifestPath = join(root, 'manifest.json');
|
|
@@ -1,15 +1,61 @@
|
|
|
1
1
|
// ../hem-target-runtime/src/hem/targets.ts
|
|
2
2
|
var WRAPPERS = {
|
|
3
3
|
fhs: {
|
|
4
|
+
/** Wire name the target preparation artifacts accept. */
|
|
4
5
|
profile: "fhs",
|
|
6
|
+
/** Community defaults template the family's bundles pin for preparation. */
|
|
7
|
+
preparationDefaults: "defaults_template.json",
|
|
8
|
+
/** Schema dialect the editor reads; separate from the wire profile. */
|
|
9
|
+
schemaMode: "fhs",
|
|
5
10
|
modes: ["actual", "actual-fee", "notional", "notional-fee"],
|
|
11
|
+
/** Modes of a scenario that selects no model wrapper. */
|
|
12
|
+
defaultModes: ["actual"],
|
|
6
13
|
scenarioModes: {
|
|
7
14
|
fhs_assumptions: ["actual"],
|
|
8
15
|
fhs_compliance: ["actual", "actual-fee", "notional", "notional-fee"]
|
|
9
16
|
},
|
|
10
|
-
|
|
17
|
+
/** The run-mode name users see, per scenario wrapper. */
|
|
18
|
+
scenarioLabels: { fhs_assumptions: "Single run", fhs_compliance: "Compliance" },
|
|
19
|
+
/** How the run's results are read; written to target-run.json. */
|
|
20
|
+
resultsKind: "fhs",
|
|
11
21
|
coreDistribution: "hem-core",
|
|
12
|
-
wrapperDistribution: "hem-fhs-wrapper"
|
|
22
|
+
wrapperDistribution: "hem-fhs-wrapper",
|
|
23
|
+
/** Further pinned distributions; each target pins their version and commit in `components`. */
|
|
24
|
+
componentDistributions: [],
|
|
25
|
+
/** Systems take HEM Database products, picked in the editor's product slots. */
|
|
26
|
+
hemDatabaseProducts: false,
|
|
27
|
+
/** The scenario wrapper an agent's single-model run uses when the caller names none. */
|
|
28
|
+
singleRunWrapper: "fhs_compliance",
|
|
29
|
+
/** Fabric from construction bands on an existing building (the editor's `constructionBands` rule). */
|
|
30
|
+
constructionBands: false,
|
|
31
|
+
/** A scenario may pick its own weather file. */
|
|
32
|
+
customWeather: true
|
|
33
|
+
},
|
|
34
|
+
epc: {
|
|
35
|
+
/** vulcan-model-transform `ModelProfile::Epc`. */
|
|
36
|
+
profile: "epc",
|
|
37
|
+
/** The shared template plus the HEM:EPC fields with no Vulcan source. */
|
|
38
|
+
preparationDefaults: "defaults_template_epc.json",
|
|
39
|
+
/** The full-input schema is a Core-shaped input (pydantic unions), not the FHS dialect. */
|
|
40
|
+
schemaMode: "core",
|
|
41
|
+
/** `quick` is the main EPC run only (upstream --skip-smart-metric --skip-fees-metric); `full` adds the smart and FEES runs. */
|
|
42
|
+
modes: ["quick", "full"],
|
|
43
|
+
defaultModes: ["quick"],
|
|
44
|
+
scenarioModes: {
|
|
45
|
+
epc_quick: ["quick"],
|
|
46
|
+
epc_full: ["full"]
|
|
47
|
+
},
|
|
48
|
+
scenarioLabels: { epc_quick: "Rating and energy", epc_full: "Full EPC" },
|
|
49
|
+
resultsKind: "epc",
|
|
50
|
+
coreDistribution: "hem-core",
|
|
51
|
+
wrapperDistribution: "hem-epc-wrapper",
|
|
52
|
+
componentDistributions: ["hem-epc-orchestrator", "hemie", "hem-db-client"],
|
|
53
|
+
hemDatabaseProducts: true,
|
|
54
|
+
singleRunWrapper: "epc_quick",
|
|
55
|
+
// An existing building converts to HEMIE, whose fabric is the age band and constructions.
|
|
56
|
+
constructionBands: true,
|
|
57
|
+
// The Orchestrator runs on its pinned weather (pythonTarget.ts).
|
|
58
|
+
customWeather: false
|
|
13
59
|
}
|
|
14
60
|
};
|
|
15
61
|
function targetWrapper(target) {
|
|
@@ -18,9 +64,29 @@ function targetWrapper(target) {
|
|
|
18
64
|
return wrapper;
|
|
19
65
|
}
|
|
20
66
|
var HEM_TARGETS = [
|
|
67
|
+
// The Rust a9 that ECaaS runs in production (epb-ecaas-api e1c090e, lambda/Cargo.lock). Its wrapper
|
|
68
|
+
// schema equals the Python a9 one, so it keeps that conversion profile's wire name. It is built
|
|
69
|
+
// with the carried patch set fhs-a9-schema-v1 (targetSchemaCorrections.ts); build and parity:
|
|
70
|
+
// docs/development/HEM_Rust_A9_Target.md.
|
|
71
|
+
{
|
|
72
|
+
id: "rust-fhs-a9-9e41af89-f2c2425f-v1",
|
|
73
|
+
label: "HEM:FHS 1.0.0a9",
|
|
74
|
+
runtime: "rust",
|
|
75
|
+
version: "1.0.0a9",
|
|
76
|
+
engineVersion: "1.0.0a9",
|
|
77
|
+
wrapperVersion: "1.0.0a9",
|
|
78
|
+
wrapper: "fhs",
|
|
79
|
+
engineCommit: "9e41af890cc62a1cec08957340231c3591956dac",
|
|
80
|
+
wrapperCommit: "f2c2425f00870e1611750bd2ac1be20132301e0d",
|
|
81
|
+
conversionProfile: "python_fhs_a9",
|
|
82
|
+
// Measured, example_semi_detached in wasm-browser-cli at load 13-19 (13 November): actual mode
|
|
83
|
+
// 5.9-9.0 s, all four modes 48.3-48.6 s (docs/development/HEM_Rust_A9_Target.md).
|
|
84
|
+
status: "provisional",
|
|
85
|
+
typicalRunMinutes: { fhs_assumptions: 0.15, fhs_compliance: 0.8 }
|
|
86
|
+
},
|
|
21
87
|
{
|
|
22
88
|
id: "rust-fhs-a7-62d3df70-c5ba2673-v1",
|
|
23
|
-
label: "
|
|
89
|
+
label: "HEM:FHS 1.0.0a7",
|
|
24
90
|
runtime: "rust",
|
|
25
91
|
version: "1.0.0a7",
|
|
26
92
|
engineVersion: "1.0.0a7",
|
|
@@ -28,36 +94,42 @@ var HEM_TARGETS = [
|
|
|
28
94
|
wrapper: "fhs",
|
|
29
95
|
engineCommit: "62d3df705690f33b3fc3e905c9971d4f3743bf2e",
|
|
30
96
|
wrapperCommit: "c5ba2673fbd886cfe4fb528f61b376bdf406ebbd",
|
|
31
|
-
conversionProfile: "current_rust_fhs"
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
wrapperVersion: "1.0.0a9",
|
|
40
|
-
wrapper: "fhs",
|
|
41
|
-
engineCommit: "918addad2f9ffbcd9c7a4ed73497d047210be2d2",
|
|
42
|
-
wrapperCommit: "b9b901382feb0e5d27f969532842250147fb4068",
|
|
43
|
-
conversionProfile: "python_fhs_a9"
|
|
44
|
-
},
|
|
97
|
+
conversionProfile: "current_rust_fhs",
|
|
98
|
+
// Actual mode: house_two_storey 7.4 s and 8.1 s through wasm-browser-cli at load 16-20 (13 November). Compliance not measured.
|
|
99
|
+
status: "legacy",
|
|
100
|
+
typicalRunMinutes: { fhs_assumptions: 0.12 }
|
|
101
|
+
}
|
|
102
|
+
];
|
|
103
|
+
var RECOMMENDED_HEM_TARGET = HEM_TARGETS[0].id;
|
|
104
|
+
var UNRELEASED_HEM_TARGETS = [
|
|
45
105
|
{
|
|
46
|
-
id: "python-
|
|
47
|
-
label: "
|
|
106
|
+
id: "python-epc-0.13.2-6367f1ec-18032feb-v1",
|
|
107
|
+
label: "HEM:EPC 0.13.2",
|
|
48
108
|
runtime: "python",
|
|
49
|
-
version: "
|
|
50
|
-
engineVersion: "
|
|
51
|
-
wrapperVersion: "
|
|
52
|
-
wrapper: "
|
|
53
|
-
engineCommit: "
|
|
54
|
-
wrapperCommit: "
|
|
55
|
-
conversionProfile: "
|
|
109
|
+
version: "0.13.2",
|
|
110
|
+
engineVersion: "2.0.0a4",
|
|
111
|
+
wrapperVersion: "0.13.2",
|
|
112
|
+
wrapper: "epc",
|
|
113
|
+
engineCommit: "6367f1ecb101c7f72a2006a921c732c790b0d338",
|
|
114
|
+
wrapperCommit: "18032feb59294b323fc28af4fb032d34bd44bf67",
|
|
115
|
+
conversionProfile: "epc_full_input_v1",
|
|
116
|
+
components: {
|
|
117
|
+
"hem-epc-orchestrator": { version: "0.13.2a0", commit: "993463233ad0c416e83c4de3b84889280d3c4619" },
|
|
118
|
+
hemie: { version: "0.18.1", commit: "2876e2ec1c7bad2b738c9c3b3685d86860a91f41" },
|
|
119
|
+
"hem-db-client": { version: "1.0.0a10", commit: "9eeb026dd52a612197b5552ca113d8121fa72679" }
|
|
120
|
+
},
|
|
121
|
+
// db-client/data/*.csv at the hem-db-client commit.
|
|
122
|
+
productDataSha256: "d0acf4ebf050e80f3dc576ffbb1295ebeb1176e9fd4a9ec1d151a9e8f4df7457",
|
|
123
|
+
// Quick, measured: house_two_storey 491-535 s in wasm-browser-cli (HEM_EPC_Integration_Plan.md, Status).
|
|
124
|
+
// Full, estimated: 35 min natively at the measured 2.4-2.6x browser ratio (same plan, Measured).
|
|
125
|
+
status: "provisional",
|
|
126
|
+
typicalRunMinutes: { epc_quick: 9, epc_full: 90 },
|
|
127
|
+
estimatedRunMinutes: ["epc_full"]
|
|
56
128
|
}
|
|
57
129
|
];
|
|
58
|
-
var
|
|
130
|
+
var findHemTarget = (id) => [...HEM_TARGETS, ...UNRELEASED_HEM_TARGETS].find((target) => target.id === id);
|
|
59
131
|
function resolveHemTarget(id) {
|
|
60
|
-
const target =
|
|
132
|
+
const target = findHemTarget(id);
|
|
61
133
|
if (!target) throw new Error(`HEM target '${id}' is unavailable. Select a supported target explicitly; saved runs are never upgraded automatically.`);
|
|
62
134
|
return target;
|
|
63
135
|
}
|
|
@@ -67,9 +139,11 @@ function modelArtifacts(manifest) {
|
|
|
67
139
|
return manifest.artifacts.filter((artifact) => !artifact.path.startsWith("source/") && !artifact.path.startsWith("notices/") && !converter.includes(artifact.path));
|
|
68
140
|
}
|
|
69
141
|
function validateTargetManifest(manifest, target) {
|
|
70
|
-
if (manifest.bundleId !== target.id || manifest.protocol !== 1 || manifest.engineCommit !== target.engineCommit || manifest.wrapperCommit !== target.wrapperCommit || manifest.conversionProfile !== target.conversionProfile) {
|
|
142
|
+
if (manifest.bundleId !== target.id || manifest.protocol !== 1 || manifest.engineCommit !== target.engineCommit || manifest.wrapperCommit !== target.wrapperCommit || manifest.conversionProfile !== target.conversionProfile || JSON.stringify(sortedComponents(manifest.components)) !== JSON.stringify(sortedComponents(target.components)) || manifest.productDataSha256 !== target.productDataSha256) {
|
|
71
143
|
throw new Error(`Target manifest identity mismatch for ${target.id}`);
|
|
72
144
|
}
|
|
145
|
+
const wrapper = targetWrapper(target);
|
|
146
|
+
if (JSON.stringify(Object.keys(target.components ?? {}).sort()) !== JSON.stringify([...wrapper.componentDistributions].sort())) throw new Error(`${target.id} must pin exactly the ${target.wrapper.toUpperCase()} component distributions`);
|
|
73
147
|
const paths = /* @__PURE__ */ new Set();
|
|
74
148
|
const sizesByHash = /* @__PURE__ */ new Map();
|
|
75
149
|
const isRelativePath = (path) => typeof path === "string" && /^[a-zA-Z0-9_./+-]+$/.test(path) && path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
|
|
@@ -86,7 +160,10 @@ function validateTargetManifest(manifest, target) {
|
|
|
86
160
|
if (path.startsWith("source/") || path.startsWith("notices/")) throw new Error(`Runtime/preparation cannot reference reserved source/notice material: ${path}`);
|
|
87
161
|
if (!paths.has(path)) throw new Error(`Target manifest is missing required artifact ${path}`);
|
|
88
162
|
}
|
|
89
|
-
if (!manifest.modes.length || new Set(manifest.modes).size !== manifest.modes.length || manifest.modes.some((mode) => !
|
|
163
|
+
if (!manifest.modes.length || new Set(manifest.modes).size !== manifest.modes.length || manifest.modes.some((mode) => !wrapper.modes.includes(mode))) throw new Error(`Unsupported or duplicate ${target.wrapper.toUpperCase()} calculation modes`);
|
|
164
|
+
const { data } = manifest.runtime;
|
|
165
|
+
if (!!data !== !!target.productDataSha256) throw new Error("Runtime product data and its pinned hash must be declared together");
|
|
166
|
+
if (data && (target.runtime !== "python" || data.startsWith("source/") || data.startsWith("notices/") || !data.endsWith("/") || !isRelativePath(data.slice(0, -1)) || !manifest.artifacts.some((artifact) => artifact.path.startsWith(data)))) throw new Error("Runtime product data must be a non-empty relative Python bundle directory ending in /");
|
|
90
167
|
if (target.runtime === "rust") {
|
|
91
168
|
if (!manifest.runtime.wasm) throw new Error("Rust target manifest is missing its runtime WASM artifact");
|
|
92
169
|
if (manifest.modes.some((mode) => mode !== "actual") && manifest.modes.length !== targetWrapper(target).modes.length) throw new Error("Rust target modes require actual alone or the complete compliance set");
|
|
@@ -98,11 +175,15 @@ function validateTargetManifest(manifest, target) {
|
|
|
98
175
|
for (const file of ["pyodide.asm.js", "pyodide.asm.wasm", "pyodide-lock.json", "python_stdlib.zip"]) {
|
|
99
176
|
if (!paths.has(`${index}${file}`)) throw new Error(`Python runtime is missing pinned artifact ${index}${file}`);
|
|
100
177
|
}
|
|
101
|
-
if (requiredVersions?.[
|
|
178
|
+
if (requiredVersions?.[wrapper.coreDistribution] !== target.engineVersion || requiredVersions?.[wrapper.wrapperDistribution] !== target.wrapperVersion) {
|
|
102
179
|
throw new Error(`Python runtime must pin matching engine ${target.engineVersion} and wrapper ${target.wrapperVersion} distributions`);
|
|
103
180
|
}
|
|
181
|
+
for (const [distribution, { version }] of Object.entries(target.components ?? {})) {
|
|
182
|
+
if (requiredVersions?.[distribution] !== version) throw new Error(`Python runtime must pin ${distribution} ${version}`);
|
|
183
|
+
}
|
|
104
184
|
}
|
|
105
185
|
}
|
|
186
|
+
var sortedComponents = (components) => Object.entries(components ?? {}).sort(([a], [b]) => a.localeCompare(b));
|
|
106
187
|
|
|
107
188
|
// ../hem-target-runtime/src/hem/targetAssets.ts
|
|
108
189
|
var CACHE = "vulcan-hem-artifacts-v1";
|