@vulcan-energy/mcp-helper 0.1.8 → 0.2.2

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.
@@ -0,0 +1,260 @@
1
+ // Local MCP/CLI transport for the app's exact target preparation and workers.
2
+ import { readFile, writeFile, mkdir, realpath, open, unlink, rename } from 'node:fs/promises';
3
+ import { homedir } from 'node:os';
4
+ import { createHash, randomUUID } from 'node:crypto';
5
+ import { createServer } from 'node:http';
6
+ import { dirname, resolve, join, relative, sep } from 'node:path';
7
+ import { fileURLToPath } from 'node:url';
8
+
9
+ const hash = bytes => createHash('sha256').update(bytes).digest('hex');
10
+ const RELEASE_ORIGIN = 'https://usevulcan.app';
11
+ // Source archives and notices stay in the published release; execution needs only model artifacts.
12
+ const isModelArtifact = path => !path.startsWith('source/') && !path.startsWith('notices/');
13
+ function assertArtifactPath(path) {
14
+ if (!path || path.includes('\\') || path.startsWith('/') || path.split('/').some(part => !part || part === '..' || part === '.')) throw new Error('Invalid target artifact path');
15
+ }
16
+ export async function readVerifiedBundle(manifestPath, expectedHash) {
17
+ if (!/^[a-f0-9]{64}$/.test(expectedHash ?? '')) throw new Error('Supply the exact target manifest SHA-256; local bundles are never inferred or upgraded.');
18
+ const bytes = await readFile(manifestPath);
19
+ if (hash(bytes) !== expectedHash) throw new Error('Target manifest hash mismatch');
20
+ const manifest = JSON.parse(bytes);
21
+ if (!/^[a-z0-9-]+$/.test(manifest.bundleId ?? '') || !Array.isArray(manifest.artifacts)) throw new Error('Invalid target manifest');
22
+ const root = await realpath(dirname(manifestPath));
23
+ const routes = new Map();
24
+ for (const artifact of manifest.artifacts) {
25
+ assertArtifactPath(artifact.path);
26
+ if (!isModelArtifact(artifact.path)) continue;
27
+ const file = await realpath(resolve(root, artifact.path));
28
+ if (!file.startsWith(root + sep)) throw new Error('Target artifact escapes bundle directory');
29
+ const contents = await readFile(file);
30
+ if (contents.length !== artifact.bytes || hash(contents) !== artifact.sha256) throw new Error(`Corrupt target artifact ${artifact.path}`);
31
+ routes.set(`/hem-targets/${manifest.bundleId}/${artifact.path}`, contents);
32
+ }
33
+ return { manifest, routes };
34
+ }
35
+
36
+ async function releasePin(bundleId, pins) {
37
+ if (!pins) {
38
+ try { pins = (await import('./release-manifests.mjs')).RELEASE_MANIFEST_HASHES; }
39
+ 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.'); }
40
+ }
41
+ const expected = /^[a-z0-9-]+$/.test(bundleId ?? '') && Object.hasOwn(pins, bundleId) && pins[bundleId];
42
+ 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`);
43
+ return expected;
44
+ }
45
+ async function writeAtomic(file, bytes) {
46
+ await mkdir(dirname(file), { recursive: true });
47
+ const temporary = `${file}.${randomUUID()}.tmp`;
48
+ await writeFile(temporary, bytes);
49
+ await rename(temporary, file);
50
+ }
51
+ // The largest released artifact is ~14 MB, so five minutes per request needs only ~50 kB/s.
52
+ const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
53
+ async function fetchBytes(fetcher, bundleId, url, timeoutMs) {
54
+ let response, bytes;
55
+ // The signal also bounds reading the body, so a stalled transfer cannot hold the workspace lock.
56
+ const controller = new AbortController();
57
+ const timer = setTimeout(() => controller.abort(new DOMException('timed out', 'TimeoutError')), timeoutMs);
58
+ try {
59
+ response = await fetcher(url, { cache: 'no-store', signal: controller.signal });
60
+ if (response.ok) bytes = Buffer.from(await response.arrayBuffer());
61
+ } catch (error) {
62
+ if (controller.signal.aborted) throw new Error(`HEM target ${bundleId} download timed out after ${timeoutMs / 1000} s: ${url}. Check your connection and retry, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
63
+ throw new Error(`Could not download HEM target ${bundleId} from ${url} (${error.cause?.message ?? error.message}). Check your connection, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
64
+ } finally { clearTimeout(timer); }
65
+ if (!response.ok) throw new Error(`HEM target download failed (${response.status}): ${url}`);
66
+ return bytes;
67
+ }
68
+
69
+ /** Resolve a released bundle into a local cache, verified against the pins compiled into this helper. */
70
+ export async function resolveReleaseBundle(bundleId, { cacheDir = join(homedir(), '.cache/vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS } = {}) {
71
+ const expected = await releasePin(bundleId, pins);
72
+ const root = join(cacheDir, bundleId);
73
+ const manifestPath = join(root, 'manifest.json');
74
+ const base = `${RELEASE_ORIGIN}/hem-targets/${bundleId}/`;
75
+ let bytes = await readFile(manifestPath).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
76
+ if (!bytes || hash(bytes) !== expected) {
77
+ bytes = await fetchBytes(fetcher, bundleId, base + 'manifest.json', timeoutMs);
78
+ if (hash(bytes) !== expected) throw new Error(`HEM target manifest hash mismatch: ${bundleId}`);
79
+ await writeAtomic(manifestPath, bytes);
80
+ }
81
+ const manifest = JSON.parse(bytes);
82
+ const artifacts = manifest.artifacts.filter(artifact => { assertArtifactPath(artifact.path); return isModelArtifact(artifact.path); });
83
+ const missing = [];
84
+ const realRoot = await realpath(root);
85
+ for (const artifact of artifacts) {
86
+ const file = join(root, artifact.path);
87
+ const real = await realpath(file).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
88
+ if (real && !real.startsWith(realRoot + sep)) throw new Error(`Cached artifact ${artifact.path} escapes the HEM target cache; delete ${root} and retry.`);
89
+ const existing = real && await readFile(real);
90
+ if (!existing || existing.length !== artifact.bytes || hash(existing) !== artifact.sha256) missing.push(artifact);
91
+ }
92
+ const total = missing.reduce((sum, artifact) => sum + artifact.bytes, 0);
93
+ let completed = 0;
94
+ let next = 0;
95
+ let failed = false;
96
+ // Four concurrent downloads, matching the app's TargetAssets.download. The first failure stops new
97
+ // requests and progress; settling every worker means nothing still runs once this throws.
98
+ const workers = await Promise.allSettled(Array.from({ length: Math.min(4, missing.length) }, async () => {
99
+ try {
100
+ while (next < missing.length && !failed) {
101
+ const artifact = missing[next++];
102
+ const contents = await fetchBytes(fetcher, bundleId, base + artifact.path, timeoutMs);
103
+ if (contents.length !== artifact.bytes || hash(contents) !== artifact.sha256) throw new Error(`Corrupt HEM target artifact ${artifact.path}; retry the download`);
104
+ await writeAtomic(join(root, artifact.path), contents);
105
+ completed += artifact.bytes;
106
+ if (!failed) onProgress?.(completed, total);
107
+ }
108
+ } catch (error) { failed = true; throw error; }
109
+ }));
110
+ const rejected = workers.find(worker => worker.status === 'rejected');
111
+ if (rejected) throw rejected.reason;
112
+ return { manifestPath, manifestSha256: expected };
113
+ }
114
+
115
+ export async function runTargetBrowser(options, dependencies = {}) {
116
+ // A bundle id resolves only after the workspace lock, so a long first download is reported as batch progress.
117
+ const bundleId = options.manifestPath ? undefined : options.targetBundleId;
118
+ let manifest, routes;
119
+ if (options.manifestPath) ({ manifest, routes } = await readVerifiedBundle(options.manifestPath, options.manifestSha256));
120
+ else await releasePin(bundleId, dependencies.pins);
121
+ const assets = new Map();
122
+ const runtimeRoot = options.runtimeRoot ?? dirname(fileURLToPath(import.meta.url));
123
+ for (const name of ['host.mjs', 'python-worker.mjs', 'rust-worker.mjs']) {
124
+ try { assets.set('/' + name, await readFile(join(runtimeRoot, name))); }
125
+ catch { throw new Error('Target browser assets are missing. Build the target CLI assets with node scripts/hem-targets/build-cli-runtime.mjs, or install a helper release that includes them.'); }
126
+ }
127
+ let chromium;
128
+ try { chromium = dependencies.chromium ?? (await import('playwright-core')).chromium; }
129
+ catch { throw new Error('Target execution needs playwright-core and installed Google Chrome. Install the supported MCP helper runtime dependencies.'); }
130
+ const workspace = await realpath(options.workspace);
131
+ const jobId = options.jobId ?? `target_${randomUUID()}`;
132
+ if (!/^[a-zA-Z0-9_-]+$/.test(jobId) || (options.configName && !/^[a-zA-Z0-9_. -]+$/.test(options.configName))) throw new Error('Invalid target job/config name');
133
+ const contained = path => {
134
+ if (typeof path !== 'string' || path.includes('\\')) throw new Error('Invalid workspace path');
135
+ const file = resolve(workspace, path);
136
+ if (!file.startsWith(workspace + sep)) throw new Error('Target file escapes workspace');
137
+ return file;
138
+ };
139
+ const read = async path => {
140
+ const file = await realpath(contained(path));
141
+ if (!file.startsWith(workspace + sep)) throw new Error('Target read escapes workspace');
142
+ return readFile(file, 'utf8');
143
+ };
144
+ const markers = new Map();
145
+ const write = async (path, content) => {
146
+ if (!path.startsWith('output/')) throw new Error('Target workers may only write workspace outputs');
147
+ const file = contained(path);
148
+ if (!file.startsWith(join(workspace, 'output') + sep)) throw new Error('Target output escapes workspace output directory');
149
+ const marker = path.endsWith('/target-run.json') ? JSON.parse(content) : undefined;
150
+ let directory = workspace;
151
+ for (const segment of relative(workspace, dirname(file)).split(sep)) {
152
+ directory = join(directory, segment);
153
+ await mkdir(directory).catch(error => { if (error.code !== 'EEXIST') throw error; });
154
+ if (await realpath(directory) !== directory) throw new Error('Target output directory is a symlink');
155
+ }
156
+ // Do not follow a pre-existing output symlink.
157
+ const handle = await open(file, 'wx').catch(async error => {
158
+ if (error.code !== 'EEXIST') throw error;
159
+ if (marker?.status === 'running' && !marker.archive) throw new Error('Target run archive already exists. Use a new job ID; saved runs are immutable.');
160
+ if (await realpath(file) !== file) throw new Error('Target output is a symlink');
161
+ return open(file, 'w');
162
+ });
163
+ try { await handle.writeFile(content); } finally { await handle.close(); }
164
+ if (marker) markers.set(path, marker);
165
+ };
166
+ let progressWrites = Promise.resolve();
167
+ const progress = value => {
168
+ if (options.operation !== 'batch') return Promise.resolve();
169
+ // Download callbacks can overlap. Preserve ordering through the final status.
170
+ progressWrites = progressWrites.catch(() => {}).then(() => write(`output/progress_${jobId}.json`, JSON.stringify({
171
+ job_id: jobId, config_name: options.configName, ...value, targetBundleId: manifest?.bundleId ?? bundleId,
172
+ status: ['completed', 'error'].includes(value.status) ? value.status : 'running',
173
+ percentage: value.progress ?? (value.total ? Math.round(value.completed / value.total * 100) : 0),
174
+ })));
175
+ return progressWrites;
176
+ };
177
+ const lockPath = join(workspace, '.hem-target-active');
178
+ let lock, browser, server, interrupted;
179
+ const interrupt = signal => {
180
+ interrupted = new Error(`Target operation interrupted by ${signal}`);
181
+ // Closing Chrome terminates its calculation worker and rejects pending evaluation.
182
+ void browser?.close().catch(() => {});
183
+ };
184
+ const onInterrupt = () => interrupt('SIGINT');
185
+ const onTerminate = () => interrupt('SIGTERM');
186
+ try {
187
+ lock = await open(lockPath, 'wx').catch(error => { if (error.code === 'EEXIST') throw new Error('A target operation already owns this workspace. Wait for it; after a crashed process, inspect and remove .hem-target-active explicitly.'); throw error; });
188
+ process.on('SIGINT', onInterrupt);
189
+ process.on('SIGTERM', onTerminate);
190
+ await lock.writeFile(JSON.stringify({ pid: process.pid, jobId, targetBundleId: manifest?.bundleId ?? bundleId }));
191
+ await progress({ status: 'running', progress: 0 });
192
+ dependencies.onStarted?.();
193
+ if (!manifest) {
194
+ const resolved = await resolveReleaseBundle(bundleId, { cacheDir: dependencies.cacheDir, fetch: dependencies.fetch, pins: dependencies.pins,
195
+ onProgress: (completed, total) => { void progress({ status: 'running', stage: 'download', completed, total }); } });
196
+ ({ manifest, routes } = await readVerifiedBundle(resolved.manifestPath, resolved.manifestSha256));
197
+ }
198
+ for (const [route, bytes] of assets) routes.set(route, bytes);
199
+ server = createServer((req, res) => {
200
+ res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
201
+ res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
202
+ if (req.url === '/') { res.setHeader('Content-Type', 'text/html'); res.end('<title>Local HEM target</title>'); return; }
203
+ const bytes = routes.get(req.url);
204
+ if (!bytes) { res.statusCode = 404; res.end('Unknown target artifact'); return; }
205
+ res.setHeader('Content-Type', /\.(mjs|js)$/.test(req.url) ? 'text/javascript' : req.url.endsWith('.wasm') ? 'application/wasm' : 'application/octet-stream');
206
+ res.end(bytes);
207
+ });
208
+ await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
209
+ const origin = `http://127.0.0.1:${server.address().port}`;
210
+ browser = await chromium.launch({ channel: 'chrome', headless: true }).catch(error => {
211
+ throw new Error(`Pinned HEM targets run in Google Chrome. Install Google Chrome and retry. (${error.message})`);
212
+ });
213
+ if (interrupted) throw interrupted;
214
+ const page = await browser.newPage();
215
+ await page.route('**/*', route => route.request().url().startsWith(origin + '/') ? route.continue() : route.abort());
216
+ await page.exposeFunction('targetCliRead', read);
217
+ await page.exposeFunction('targetCliWrite', write);
218
+ await page.exposeFunction('targetCliProgress', progress);
219
+ await progress({ status: 'running', progress: 0 });
220
+ await page.goto(origin);
221
+ const result = await page.evaluate(async request => {
222
+ const { run } = await import('/host.mjs');
223
+ return run(request);
224
+ }, { manifest, operation: options.operation, csv: options.csv, config: options.config, configName: options.configName, jobId });
225
+ if (interrupted) throw interrupted;
226
+ await progress({ status: 'completed', progress: 100, targetBundleId: manifest.bundleId });
227
+ return result;
228
+ } catch (caught) {
229
+ const error = interrupted ?? caught;
230
+ if (lock) {
231
+ for (const [path, marker] of markers) if (marker.status === 'running') await write(path, JSON.stringify({ ...marker, status: 'failed', error: String(error) })).catch(() => {});
232
+ await progress({ status: 'error', error: String(error) }).catch(() => {});
233
+ }
234
+ throw error;
235
+ } finally {
236
+ process.off('SIGINT', onInterrupt);
237
+ process.off('SIGTERM', onTerminate);
238
+ try { await browser?.close(); } finally {
239
+ if (server?.listening) await new Promise(resolve => server.close(resolve));
240
+ if (lock) { await lock.close(); await unlink(lockPath); }
241
+ }
242
+ }
243
+ }
244
+
245
+ // Detached batch entry. IPC acknowledges acquisition before the caller returns;
246
+ // status and errors thereafter live in the existing workspace progress files.
247
+ if (process.argv[2] === '--batch-child') {
248
+ process.once('message', async options => {
249
+ let started = false;
250
+ try {
251
+ await runTargetBrowser(options, { onStarted: () => {
252
+ started = true;
253
+ process.send?.({ started: true }, () => { process.disconnect?.(); });
254
+ } });
255
+ } catch (error) {
256
+ if (!started) process.send?.({ error: String(error) }, () => { process.disconnect?.(); });
257
+ process.exitCode = 1;
258
+ }
259
+ });
260
+ }