@vulcan-energy/mcp-helper 0.2.4 → 0.3.0

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.
@@ -1,4 +1,5 @@
1
- // Local MCP/CLI transport for the app's exact target preparation and workers.
1
+ // Local MCP/CLI transport: verified target bundles, and the app's target workers in Chrome.
2
+ // Preparation runs in Node (preparation.mjs); Chrome is needed only to run an engine.
2
3
  import { readFile, writeFile, mkdir, realpath, open, unlink, rename } from 'node:fs/promises';
3
4
  import { homedir } from 'node:os';
4
5
  import { createHash, randomUUID } from 'node:crypto';
@@ -8,12 +9,17 @@ import { fileURLToPath } from 'node:url';
8
9
 
9
10
  const hash = bytes => createHash('sha256').update(bytes).digest('hex');
10
11
  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/');
12
+ // As targets.ts:modelArtifacts: not source archives or notices, and not a pinned converter
13
+ // that is not also the runtime. The host converts with the package's own WASM.
14
+ const isModelArtifact = (manifest, path) => !path.startsWith('source/') && !path.startsWith('notices/')
15
+ && !([manifest.preparation?.javascript, manifest.preparation?.wasm].includes(path) && ![manifest.runtime?.javascript, manifest.runtime?.wasm].includes(path));
16
+ // Preparation reads only the pinned schema and defaults.
17
+ const isSelected = (manifest, path, preparationOnly) => preparationOnly
18
+ ? [manifest.preparation?.schema, manifest.preparation?.defaults].includes(path) : isModelArtifact(manifest, path);
13
19
  function assertArtifactPath(path) {
14
20
  if (!path || path.includes('\\') || path.startsWith('/') || path.split('/').some(part => !part || part === '..' || part === '.')) throw new Error('Invalid target artifact path');
15
21
  }
16
- export async function readVerifiedBundle(manifestPath, expectedHash) {
22
+ export async function readVerifiedBundle(manifestPath, expectedHash, { preparationOnly = false } = {}) {
17
23
  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
24
  const bytes = await readFile(manifestPath);
19
25
  if (hash(bytes) !== expectedHash) throw new Error('Target manifest hash mismatch');
@@ -23,7 +29,7 @@ export async function readVerifiedBundle(manifestPath, expectedHash) {
23
29
  const routes = new Map();
24
30
  for (const artifact of manifest.artifacts) {
25
31
  assertArtifactPath(artifact.path);
26
- if (!isModelArtifact(artifact.path)) continue;
32
+ if (!isSelected(manifest, artifact.path, preparationOnly)) continue;
27
33
  const file = await realpath(resolve(root, artifact.path));
28
34
  if (!file.startsWith(root + sep)) throw new Error('Target artifact escapes bundle directory');
29
35
  const contents = await readFile(file);
@@ -50,7 +56,7 @@ async function writeAtomic(file, bytes) {
50
56
  }
51
57
  // The largest released artifact is ~14 MB, so five minutes per request needs only ~50 kB/s.
52
58
  const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
53
- async function fetchBytes(fetcher, bundleId, url, timeoutMs) {
59
+ async function fetchBytes(fetcher, bundleId, url, timeoutMs, root) {
54
60
  let response, bytes;
55
61
  // The signal also bounds reading the body, so a stalled transfer cannot hold the workspace lock.
56
62
  const controller = new AbortController();
@@ -59,27 +65,28 @@ async function fetchBytes(fetcher, bundleId, url, timeoutMs) {
59
65
  response = await fetcher(url, { cache: 'no-store', signal: controller.signal });
60
66
  if (response.ok) bytes = Buffer.from(await response.arrayBuffer());
61
67
  } 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.`);
68
+ if (controller.signal.aborted) throw new Error(`HEM target ${bundleId} download timed out after ${timeoutMs / 1000} s: ${url} (cache: ${root}). Check your connection and retry, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
69
+ throw new Error(`Could not download HEM target ${bundleId} from ${url} into ${root} (${error.cause?.message ?? error.message}). This target is not in the cache yet. Check your connection, or supply target_manifest + target_manifest_sha256 for an offline bundle.`);
64
70
  } finally { clearTimeout(timer); }
65
- if (!response.ok) throw new Error(`HEM target download failed (${response.status}): ${url}`);
71
+ if (!response.ok) throw new Error(`HEM target download failed (${response.status}): ${url} (cache: ${root})`);
66
72
  return bytes;
67
73
  }
68
74
 
69
75
  /** 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 } = {}) {
76
+ // 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(bundleId, { cacheDir = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'vulcan/hem-targets'), fetch: fetcher = globalThis.fetch, pins, onProgress, timeoutMs = DOWNLOAD_TIMEOUT_MS, preparationOnly = false } = {}) {
71
78
  const expected = await releasePin(bundleId, pins);
72
79
  const root = join(cacheDir, bundleId);
73
80
  const manifestPath = join(root, 'manifest.json');
74
81
  const base = `${RELEASE_ORIGIN}/hem-targets/${bundleId}/`;
75
82
  let bytes = await readFile(manifestPath).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
76
83
  if (!bytes || hash(bytes) !== expected) {
77
- bytes = await fetchBytes(fetcher, bundleId, base + 'manifest.json', timeoutMs);
84
+ bytes = await fetchBytes(fetcher, bundleId, base + 'manifest.json', timeoutMs, root);
78
85
  if (hash(bytes) !== expected) throw new Error(`HEM target manifest hash mismatch: ${bundleId}`);
79
86
  await writeAtomic(manifestPath, bytes);
80
87
  }
81
88
  const manifest = JSON.parse(bytes);
82
- const artifacts = manifest.artifacts.filter(artifact => { assertArtifactPath(artifact.path); return isModelArtifact(artifact.path); });
89
+ const artifacts = manifest.artifacts.filter(artifact => { assertArtifactPath(artifact.path); return isSelected(manifest, artifact.path, preparationOnly); });
83
90
  const missing = [];
84
91
  const realRoot = await realpath(root);
85
92
  for (const artifact of artifacts) {
@@ -99,7 +106,7 @@ export async function resolveReleaseBundle(bundleId, { cacheDir = join(homedir()
99
106
  try {
100
107
  while (next < missing.length && !failed) {
101
108
  const artifact = missing[next++];
102
- const contents = await fetchBytes(fetcher, bundleId, base + artifact.path, timeoutMs);
109
+ const contents = await fetchBytes(fetcher, bundleId, base + artifact.path, timeoutMs, root);
103
110
  if (contents.length !== artifact.bytes || hash(contents) !== artifact.sha256) throw new Error(`Corrupt HEM target artifact ${artifact.path}; retry the download`);
104
111
  await writeAtomic(join(root, artifact.path), contents);
105
112
  completed += artifact.bytes;
@@ -112,12 +119,68 @@ export async function resolveReleaseBundle(bundleId, { cacheDir = join(homedir()
112
119
  return { manifestPath, manifestSha256: expected };
113
120
  }
114
121
 
122
+ /** The pinned runtime's panic hook writes `[WASM] PANIC…` lines to the console of its worker; the
123
+ * worker itself reports only the trap. Pass those lines to stderr so the CLI shows the engine's panic. */
124
+ export function forwardPanicLines(page, write = line => process.stderr.write(`${line}\n`)) {
125
+ page.on('console', message => { if (message.text().startsWith('[WASM] PANIC')) write(message.text()); });
126
+ }
127
+
128
+ /** The verified pinned schema and defaults of a supplied or released bundle, for preparation in Node. */
129
+ export async function readPreparationBundle(options, dependencies = {}) {
130
+ const located = options.manifestPath ? { manifestPath: options.manifestPath, manifestSha256: options.manifestSha256 }
131
+ : await resolveReleaseBundle(options.targetBundleId, { cacheDir: dependencies.cacheDir, fetch: dependencies.fetch, pins: dependencies.pins, preparationOnly: true });
132
+ const { manifest, routes } = await readVerifiedBundle(located.manifestPath, located.manifestSha256, { preparationOnly: true });
133
+ return { manifest, text: artifactText(manifest, routes) };
134
+ }
135
+
136
+ /** Reads workspace files for preparation; a path that leaves the workspace is refused. */
137
+ export async function workspaceReader(workspacePath) {
138
+ const workspace = await realpath(workspacePath);
139
+ return async path => {
140
+ if (typeof path !== 'string' || path.includes('\\')) throw new Error('Invalid workspace path');
141
+ const file = await realpath(resolve(workspace, path));
142
+ if (!file.startsWith(workspace + sep)) throw new Error('Target read escapes workspace');
143
+ return readFile(file, 'utf8');
144
+ };
145
+ }
146
+
147
+ /** The verified pinned artifact text of a bundle, as the browser's TargetAssets text. */
148
+ const artifactText = (manifest, routes) => async path => {
149
+ const bytes = routes.get(`/hem-targets/${manifest.bundleId}/${path}`);
150
+ if (!bytes) throw new Error(`Missing preparation content ${path}`);
151
+ return new TextDecoder().decode(bytes);
152
+ };
153
+
154
+ /** Prepares every scenario of a saved target batch in Node with the package's own WASM; no browser. */
155
+ async function prepareJobs(options, manifest, routes, onJob, dependencies) {
156
+ const [{ prepareBatch }, loader] = await Promise.all([import('./preparation.mjs'), dependencies.loadPackageWasm ? undefined : import('./wasm-loader.mjs')]);
157
+ const wasmRemedy = options.wasmRemedy ?? 'Reinstall the package.';
158
+ const wasm = await (dependencies.loadPackageWasm ?? loader.loadPackageWasm)(options.wasmDir, wasmRemedy);
159
+ return prepareBatch({ config: options.config, manifest, text: artifactText(manifest, routes), converter: { prepare_target_scenario: wasm.prepareTargetScenario },
160
+ versionInfo: wasm.versionInfo, wasmRemedy, configName: options.configName, jobId: options.jobId, startedAt: options.startedAt, onJob });
161
+ }
162
+
163
+ /** A batch's exact source, defaults, snippet and weather bytes, read in Node; its target must be the supplied or pinned one. */
164
+ export async function snapshotTarget(options, dependencies = {}) {
165
+ const { snapshotBatchTarget } = await import('./preparation.mjs');
166
+ const snapshot = await snapshotBatchTarget(options.config, await workspaceReader(options.workspace));
167
+ const expected = options.manifestPath
168
+ ? (await readVerifiedBundle(options.manifestPath, options.manifestSha256, { preparationOnly: true })).manifest.bundleId
169
+ : (await releasePin(options.targetBundleId, dependencies.pins), options.targetBundleId);
170
+ if (snapshot.targetBundleId !== expected) throw new Error('Batch source and supplied manifest target differ');
171
+ return snapshot;
172
+ }
173
+
174
+ /** `operation: 'snapshot'` captures a batch; otherwise runs one saved target batch: under the workspace lock, prepares it in Node, then runs the jobs in Chrome. */
115
175
  export async function runTargetBrowser(options, dependencies = {}) {
176
+ if (options.operation === 'snapshot') return snapshotTarget(options, dependencies);
177
+ if (options.operation !== undefined && options.operation !== 'batch') throw new Error(`Unknown target operation '${options.operation}'`);
116
178
  // A bundle id resolves only after the workspace lock, so a long first download is reported as batch progress.
117
179
  const bundleId = options.manifestPath ? undefined : options.targetBundleId;
118
180
  let manifest, routes;
119
181
  if (options.manifestPath) ({ manifest, routes } = await readVerifiedBundle(options.manifestPath, options.manifestSha256));
120
182
  else await releasePin(bundleId, dependencies.pins);
183
+ if (!options.config) throw new Error('Batch configuration required');
121
184
  const assets = new Map();
122
185
  const runtimeRoot = options.runtimeRoot ?? dirname(fileURLToPath(import.meta.url));
123
186
  for (const name of ['host.mjs', 'python-worker.mjs', 'rust-worker.mjs']) {
@@ -138,11 +201,6 @@ export async function runTargetBrowser(options, dependencies = {}) {
138
201
  if (!file.startsWith(workspace + sep)) throw new Error('Target file escapes workspace');
139
202
  return file;
140
203
  };
141
- const read = async path => {
142
- const file = await realpath(contained(path));
143
- if (!file.startsWith(workspace + sep)) throw new Error('Target read escapes workspace');
144
- return readFile(file, 'utf8');
145
- };
146
204
  const markers = new Map();
147
205
  const write = async (path, content) => {
148
206
  if (!path.startsWith('output/')) throw new Error('Target workers may only write workspace outputs');
@@ -167,7 +225,6 @@ export async function runTargetBrowser(options, dependencies = {}) {
167
225
  };
168
226
  let progressWrites = Promise.resolve();
169
227
  const progress = value => {
170
- if (options.operation !== 'batch') return Promise.resolve();
171
228
  // Download callbacks can overlap. Preserve ordering through the final status.
172
229
  // Status readers poll this file: write a new file and rename it over the old, so none sees it truncated.
173
230
  const file = `output/progress_${jobId}.json`;
@@ -203,6 +260,11 @@ export async function runTargetBrowser(options, dependencies = {}) {
203
260
  onProgress: (completed, total) => { void progress({ status: 'running', stage: 'download', completed, total }); } });
204
261
  ({ manifest, routes } = await readVerifiedBundle(resolved.manifestPath, resolved.manifestSha256));
205
262
  }
263
+ // ponytail: every prepared job is held in memory and served to the page at once; stream them if batches outgrow that.
264
+ const jobs = await (dependencies.prepareJobs ?? prepareJobs)({ ...options, jobId, startedAt }, manifest, routes,
265
+ // A signal during preparation stops it at the next scenario, as a signal during the run closes Chrome.
266
+ prepared => { if (interrupted) throw interrupted; return progress({ status: 'running', stage: 'prepare', completed: prepared }); }, dependencies);
267
+ assets.set('/prepared-jobs.json', Buffer.from(JSON.stringify(jobs)));
206
268
  for (const [route, bytes] of assets) routes.set(route, bytes);
207
269
  server = createServer((req, res) => {
208
270
  res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
@@ -220,8 +282,8 @@ export async function runTargetBrowser(options, dependencies = {}) {
220
282
  });
221
283
  if (interrupted) throw interrupted;
222
284
  const page = await browser.newPage();
285
+ forwardPanicLines(page);
223
286
  await page.route('**/*', route => route.request().url().startsWith(origin + '/') ? route.continue() : route.abort());
224
- await page.exposeFunction('targetCliRead', read);
225
287
  await page.exposeFunction('targetCliWrite', write);
226
288
  await page.exposeFunction('targetCliProgress', progress);
227
289
  await progress({ status: 'running', progress: 0 });
@@ -232,7 +294,7 @@ export async function runTargetBrowser(options, dependencies = {}) {
232
294
  const { run } = await import('/host.mjs');
233
295
  return { result: await run(request) };
234
296
  } catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
235
- }, { manifest, operation: options.operation, csv: options.csv, config: options.config, configName: options.configName, jobId, startedAt });
297
+ }, { manifest, jobsUrl: '/prepared-jobs.json', jobId });
236
298
  if (interrupted) throw interrupted;
237
299
  if ('error' in outcome) throw new Error(outcome.error);
238
300
  const { result } = outcome;