@firstpick/pi-package-webui 0.10.7 → 0.10.9

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.
Files changed (50) hide show
  1. package/DEVELOPMENT.md +95 -15
  2. package/README.md +1 -1
  3. package/TECHNICAL.md +6 -4
  4. package/bin/pi-webui-launcher.mjs +6 -3
  5. package/bin/pi-webui-native-update-guardian.mjs +37 -0
  6. package/bin/pi-webui-native-update-runner.mjs +148 -0
  7. package/bin/pi-webui-rpc-supervisor.mjs +85 -10
  8. package/bin/pi-webui-update-context.mjs +83 -0
  9. package/bin/pi-webui.mjs +537 -339
  10. package/lib/component-update-state.mjs +4 -4
  11. package/lib/rpc-supervisor-client.mjs +4 -0
  12. package/lib/rpc-supervisor-protocol.mjs +17 -4
  13. package/lib/update/coordination.mjs +207 -0
  14. package/lib/update/discovery.mjs +58 -0
  15. package/lib/update/migration.mjs +115 -0
  16. package/lib/update/native-jobs.mjs +215 -0
  17. package/lib/update/native-targets.mjs +81 -0
  18. package/lib/update/path-pi.mjs +76 -0
  19. package/lib/update/supervisor.mjs +50 -29
  20. package/lib/update/verification.mjs +18 -0
  21. package/lib/update-commands.mjs +17 -27
  22. package/package.json +2 -2
  23. package/public/app.js +170 -201
  24. package/public/index.html +5 -3
  25. package/public/styles.css +29 -1
  26. package/tests/browser/control-deck-component-updates.spec.mjs +90 -141
  27. package/tests/browser/update-reconnect.spec.mjs +37 -1
  28. package/tests/component-update-api-static.test.mjs +13 -11
  29. package/tests/control-deck-component-updates-static.test.mjs +25 -25
  30. package/tests/cwd-footer-reliability-static.test.mjs +4 -1
  31. package/tests/http-endpoints-harness.test.mjs +32 -9
  32. package/tests/mobile-static.test.mjs +9 -6
  33. package/tests/native-update-discovery.test.mjs +69 -0
  34. package/tests/native-update-lifecycle.test.mjs +92 -0
  35. package/tests/native-update-shell-survival.test.mjs +68 -0
  36. package/tests/native-update-verification.test.mjs +17 -0
  37. package/tests/rpc-supervisor-host.test.mjs +63 -1
  38. package/tests/rpc-supervisor-protocol.test.mjs +8 -0
  39. package/tests/run-all.mjs +6 -2
  40. package/tests/update-api-harness.test.mjs +57 -50
  41. package/tests/update-commands.test.mjs +29 -15
  42. package/tests/update-executor-process-tree-harness.test.mjs +84 -1
  43. package/tests/update-journal-harness.test.mjs +9 -1
  44. package/tests/update-lock-multiprocess-harness.test.mjs +60 -1
  45. package/tests/update-owners.test.mjs +32 -0
  46. package/tests/update-plan.test.mjs +110 -0
  47. package/tests/update-resolver.test.mjs +36 -0
  48. package/tests/update-supervisor-harness.test.mjs +74 -1
  49. package/tests/update-tab-restore-harness.test.mjs +9 -2
  50. package/bin/pi-webui-update-supervisor.mjs +0 -86
@@ -1,10 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  import { spawn } from "node:child_process";
3
- import { randomUUID } from "node:crypto";
3
+ import { createHash, randomUUID } from "node:crypto";
4
4
  import { createServer } from "node:net";
5
- import { rm, realpath } from "node:fs/promises";
5
+ import { lstat, readFile, rename, rm, realpath } from "node:fs/promises";
6
+ import path from "node:path";
6
7
  import { StringDecoder } from "node:string_decoder";
7
8
  import { terminateProcessTree } from "../lib/process-tree.mjs";
9
+ import { acknowledgeUpdateFence, assertEffectAdmission, effectLockForRoot, readSharedJob, registerUpdateParticipant, sharedUpdateRoot, unregisterUpdateParticipant } from "../lib/update/coordination.mjs";
8
10
  import {
9
11
  PI_RPC_JSONL_LINE_MAX_BYTES,
10
12
  RPC_SUPERVISOR_EVENT_RING_LIMIT,
@@ -38,6 +40,7 @@ const EMPTY_IDLE_GRACE_MS = 1_500;
38
40
  const CHILD_STOP_GRACE_MS = 3_000;
39
41
  const CHILD_STDIN_WRITE_TIMEOUT_MS = 2_000;
40
42
  const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
43
+ const READ_ONLY_RPC_COMMANDS = new Set(["get_state", "get_messages", "get_session_stats", "get_available_models", "get_commands"]);
41
44
 
42
45
  function requestIdForErrorFrame(frame) {
43
46
  return typeof frame?.requestId === "string" && REQUEST_ID_PATTERN.test(frame.requestId) ? frame.requestId : undefined;
@@ -103,6 +106,8 @@ class SupervisorHost {
103
106
  this.closing = false;
104
107
  this.idleTimer = null;
105
108
  this.persistQueue = Promise.resolve();
109
+ this.updateParticipant = null;
110
+ this.updateStateRoot = null;
106
111
  }
107
112
 
108
113
  async start() {
@@ -289,7 +294,9 @@ class SupervisorHost {
289
294
  this.sendError(client, request.requestId, Object.assign(new Error("RPC supervisor request dedupe capacity is occupied by unresolved work"), { code: "RPC_SUPERVISOR_DEDUPE_CAPACITY" }));
290
295
  return;
291
296
  }
292
- const entry = { settled: false, promise: null };
297
+ const mutating = !["ack", "prepare_handoff", "detach", "shutdown"].includes(request.type) &&
298
+ !(request.type === "command" && READ_ONLY_RPC_COMMANDS.has(request.command?.type));
299
+ const entry = { settled: false, promise: null, mutating };
293
300
  entry.promise = Promise.resolve().then(() => this.perform(request));
294
301
  entry.promise.then(() => { entry.settled = true; }, () => { entry.settled = true; });
295
302
  this.requests.set(request.requestId, entry);
@@ -297,23 +304,25 @@ class SupervisorHost {
297
304
  catch (error) { this.sendError(client, request.requestId, error); }
298
305
  }
299
306
 
300
- queueTabMutation(tabId, operation) {
307
+ queueTabMutation(tabId, operation, updateRestart = false) {
301
308
  const tab = this.requireTab(tabId);
302
309
  const previous = tab.mutationTail || Promise.resolve();
303
- const result = previous.catch(() => {}).then(() => {
310
+ const result = previous.catch(() => {}).then(async () => {
304
311
  if (this.tabs.get(tabId) !== tab) throw new Error(`Managed tab is no longer available: ${tabId}`);
312
+ if (this.updateParticipant && !updateRestart) await assertEffectAdmission(this.updateStateRoot, this.updateParticipant.canonicalRoots);
305
313
  return operation();
306
314
  });
307
315
  tab.mutationTail = result.catch(() => {});
308
316
  return result;
309
317
  }
310
318
 
311
- queueTabCommand(tabId, operation) {
319
+ queueTabCommand(tabId, operation, readOnly = false) {
312
320
  const tab = this.requireTab(tabId);
313
321
  const previous = tab.mutationTail || Promise.resolve();
314
322
  let response;
315
- const admission = previous.catch(() => {}).then(() => {
323
+ const admission = previous.catch(() => {}).then(async () => {
316
324
  if (this.tabs.get(tabId) !== tab) throw new Error(`Managed tab is no longer available: ${tabId}`);
325
+ if (this.updateParticipant && !readOnly) await assertEffectAdmission(this.updateStateRoot, this.updateParticipant.canonicalRoots);
317
326
  // command() registers the pending response and writes to stdin
318
327
  // synchronously before returning its response promise. Release the FIFO
319
328
  // barrier at that point so extension-ui writes and later bounded probes
@@ -325,16 +334,20 @@ class SupervisorHost {
325
334
  }
326
335
 
327
336
  async perform(request) {
337
+ // Enter the tab's FIFO before any asynchronous fence check. Otherwise a
338
+ // later replacement can overtake a write while both inspect the filesystem.
328
339
  switch (request.type) {
329
340
  case "create": return this.create(request);
330
341
  case "update": return this.queueTabMutation(request.tabId, () => this.update(request));
331
342
  case "replace": return this.queueTabMutation(request.tabId, () => this.replace(request));
343
+ case "replace_update": return this.queueTabMutation(request.tabId, () => this.replaceUnderUpdate(request), true);
332
344
  case "close": return this.queueTabMutation(request.tabId, () => this.closeTab(request.tabId));
333
345
  // Commands take a FIFO admission position, but their full response must
334
346
  // not hold the queue: prompts can wait for extension-ui writes. Metadata
335
347
  // refreshes can also arrive continuously, so chasing a moving tail would
336
348
  // starve get_state and leave a CWD PATCH permanently in progress.
337
- case "command": return this.queueTabCommand(request.tabId, () => this.command(request));
349
+ case "command": return this.queueTabCommand(request.tabId, () => this.command(request),
350
+ READ_ONLY_RPC_COMMANDS.has(request.command?.type));
338
351
  case "write": return this.queueTabMutation(request.tabId, () => this.write(request));
339
352
  case "ack": return { cursor: request.cursor };
340
353
  case "prepare_handoff": return { epoch: this.epoch, latestSeq: this.sequence.toString(), tabs: [...this.tabs.values()].map(tabSnapshot) };
@@ -349,9 +362,10 @@ class SupervisorHost {
349
362
  async create({ tabId, metadata, child }) {
350
363
  if (this.tabs.has(tabId)) throw new Error(`Managed tab already exists: ${tabId}`);
351
364
  if (this.tabs.size >= RPC_SUPERVISOR_TAB_LIMIT) throw new Error(`Managed tab limit is ${RPC_SUPERVISOR_TAB_LIMIT}`);
352
- const tab = { id: tabId, metadata, child: null, pending: new Map(), startedAt: new Date().toISOString(), mutationTail: Promise.resolve() };
365
+ const tab = { id: tabId, metadata, child: null, pending: new Map(), working: true, startedAt: new Date().toISOString(), mutationTail: Promise.resolve() };
353
366
  this.tabs.set(tabId, tab);
354
367
  try {
368
+ if (this.updateParticipant) await assertEffectAdmission(this.updateStateRoot, this.updateParticipant.canonicalRoots);
355
369
  const candidate = await this.spawnChildCandidate(child);
356
370
  this.commitChild(tab, candidate);
357
371
  } catch (error) {
@@ -379,6 +393,39 @@ class SupervisorHost {
379
393
  return tabSnapshot(tab);
380
394
  }
381
395
 
396
+ async replaceUnderUpdate(request) {
397
+ if (!this.updateParticipant || !this.updateStateRoot) throw new Error("Update restart requires a registered RPC owner.");
398
+ const { tabId, restart, metadata, child } = request;
399
+ const tab = this.requireTab(tabId);
400
+ if (!tabRunning(tab) || tab.working !== false || tab.pending.size > 0) throw new Error("Affected Pi tab is not verified idle.");
401
+ const effectRoot = await realpath(restart.effectRoot);
402
+ if (effectRoot !== restart.effectRoot || !this.updateParticipant.canonicalRoots.includes(effectRoot)) throw new Error("Unowned update effect root.");
403
+ const lock = await effectLockForRoot(this.updateStateRoot, effectRoot);
404
+ if (!lock || lock.token !== restart.lockToken || lock.transactionId !== restart.transactionId) throw new Error("Update fence identity changed.");
405
+ const job = await readSharedJob(this.updateStateRoot, restart.transactionId);
406
+ if (!job || job.phase !== "restart-authorized" || job.lock?.token !== lock.token ||
407
+ !job.verifiedTargets?.some((item) => item.effectRoot === effectRoot && item.status === "healthy")) {
408
+ throw new Error("No durable healthy completed update authorizes this Pi restart.");
409
+ }
410
+ const completed = JSON.parse(await readFile(path.join(job.jobDir, "complete.json"), "utf8"));
411
+ if (completed.transactionId !== restart.transactionId || !completed.receipts?.some((item) =>
412
+ (item.status === "changed" || item.status === "unchanged" && job.verifiedTargets.some((verified) =>
413
+ verified.id === item.id && verified.piChanged === true)) && job.verifiedTargets.some((verified) =>
414
+ verified.id === item.id && verified.effectRoot === effectRoot && verified.status === "healthy"))) {
415
+ throw new Error("Command completion evidence does not match the authorized restart.");
416
+ }
417
+ const markerPath = path.join(job.jobDir, "restarts", `${restart.nonce}.json`);
418
+ const usedPath = `${markerPath}.used`;
419
+ const marker = JSON.parse(await readFile(markerPath, "utf8"));
420
+ const requestDigest = createHash("sha256").update(JSON.stringify({ tabId, metadata, child })).digest("hex");
421
+ if (marker.tabId !== tabId || marker.transactionId !== restart.transactionId || marker.lockToken !== lock.token ||
422
+ marker.effectRoot !== effectRoot || marker.requestDigest !== requestDigest) throw new Error("Restart authorization does not bind this tab and replacement.");
423
+ try { await lstat(usedPath); throw new Error("Restart authorization was already used."); }
424
+ catch (error) { if (error.code !== "ENOENT") throw error; }
425
+ await rename(markerPath, usedPath);
426
+ return this.replace(request);
427
+ }
428
+
382
429
  async closeTab(tabId) {
383
430
  const tab = this.requireTab(tabId);
384
431
  await this.stopChild(tab, "close");
@@ -495,6 +542,11 @@ class SupervisorHost {
495
542
  clearTimeout(pending.timer);
496
543
  pending.resolve(payload);
497
544
  }
545
+ if (payload?.type === "agent_start" || payload?.type === "compaction_start") tab.working = true;
546
+ if (payload?.type === "agent_settled" || payload?.type === "compaction_end") tab.working = false;
547
+ if (payload?.type === "response" && payload.command === "get_state" && payload.success !== false) {
548
+ tab.working = payload.data?.isStreaming === true || payload.data?.isCompacting === true;
549
+ }
498
550
  this.emit(tab.id, payload);
499
551
  }
500
552
 
@@ -605,6 +657,7 @@ class SupervisorHost {
605
657
  for (const client of this.clients) client.socket.destroy();
606
658
  await new Promise((resolve) => this.server?.close(() => resolve()) || resolve());
607
659
  await removeSupervisorState(this.paths, { removeSocket: true, instanceId: this.instanceId }).catch(() => {});
660
+ if (this.updateParticipant) await unregisterUpdateParticipant(this.updateParticipant).catch(() => {});
608
661
  process.exit(0);
609
662
  }
610
663
  }
@@ -612,4 +665,26 @@ class SupervisorHost {
612
665
  const options = cliOptions(process.argv.slice(2));
613
666
  const paths = await supervisorPaths(options);
614
667
  const host = new SupervisorHost(paths);
615
- await host.start();
668
+ const effects = (() => {
669
+ try { return JSON.parse(process.env.PI_WEBUI_UPDATE_EFFECT_ROOTS || "[]"); } catch { return []; }
670
+ })();
671
+ if (Array.isArray(effects) && effects.length && effects.every((root) => typeof root === "string")) {
672
+ host.updateStateRoot = await sharedUpdateRoot();
673
+ host.updateParticipant = await registerUpdateParticipant(host.updateStateRoot, { kind: "rpc-supervisor", roots: effects });
674
+ setInterval(async () => {
675
+ try {
676
+ for (const effect of host.updateParticipant.canonicalRoots) {
677
+ const lock = await effectLockForRoot(host.updateStateRoot, effect);
678
+ if (!lock) continue;
679
+ const idle = ![...host.requests.values()].some((request) => request.mutating && !request.settled) &&
680
+ [...host.tabs.values()].every((tab) => tab.working === false && tab.pending.size === 0 && tab.child?.exitCode === null);
681
+ await acknowledgeUpdateFence(host.updateParticipant, { token: lock.token, effects: [effect] }, idle);
682
+ }
683
+ } catch (error) { console.warn(`Update admission acknowledgement failed: ${publicError(error)}`); }
684
+ }, 250).unref();
685
+ }
686
+ try { await host.start(); }
687
+ catch (error) {
688
+ if (host.updateParticipant) await unregisterUpdateParticipant(host.updateParticipant).catch(() => {});
689
+ throw error;
690
+ }
@@ -0,0 +1,83 @@
1
+ import { createHash } from "node:crypto";
2
+ import { readFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+
5
+ const WEBUI = "npm:@firstpick/pi-package-webui";
6
+ const ROUTING_KEYS = new Set([
7
+ "prefix", "registry", "userconfig", "globalconfig", "cache", "script-shell", "ignore-scripts",
8
+ "omit", "include", "engine-strict", "legacy-peer-deps", "workspaces", "location", "install-strategy", "node-options",
9
+ ]);
10
+ const ENV_KEYS = new Set(["path", "pathext", "pi_coding_agent_dir", "pi_webui_npm_bin", "npm_execpath", "home", "userprofile", "node_options"]);
11
+ const sha = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
12
+ const routingKey = (key) => ROUTING_KEYS.has(key) || /^@[a-z0-9._-]+:registry$/i.test(key);
13
+
14
+ function safeValue(value) {
15
+ const text = String(value ?? "");
16
+ return text.replace(/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, "$1[redacted]@");
17
+ }
18
+
19
+ function routingSettings(settings) {
20
+ const relevant = (Array.isArray(settings?.packages) ? settings.packages : [])
21
+ .map((entry) => typeof entry === "string" ? entry : entry?.source)
22
+ .filter((source) => typeof source === "string" && (source === WEBUI || source.startsWith(`${WEBUI}@`)))
23
+ .sort();
24
+ // Opaque npmCommand wrappers are refused by the planner; do not persist
25
+ // arguments that could contain credentials in a custom shell invocation.
26
+ return { webuiSources: relevant, hasCustomNpmCommand: Boolean(settings?.npmCommand) };
27
+ }
28
+
29
+ function routingNpmrc(text) {
30
+ const result = [];
31
+ for (const line of text.split(/\r?\n/)) {
32
+ const match = line.match(/^\s*([^=;#\s]+)\s*=\s*(.*?)\s*$/);
33
+ if (match && routingKey(match[1].toLowerCase())) result.push([match[1].toLowerCase(), safeValue(match[2])]);
34
+ }
35
+ return result.sort(([a], [b]) => a.localeCompare(b));
36
+ }
37
+
38
+ /** Build a nonsecret fingerprint of the routing inputs actually used by npm/Pi. */
39
+ export async function readUpdateContext({ env = process.env, settingsPath, npmConfigFiles = [] } = {}) {
40
+ const environment = Object.entries(env)
41
+ .filter(([name]) => {
42
+ const key = name.toLowerCase();
43
+ return ENV_KEYS.has(key) || key.startsWith("npm_config_") && routingKey(key.slice("npm_config_".length).replaceAll("_", "-"));
44
+ })
45
+ .map(([name, value]) => [name.toLowerCase(), safeValue(value)])
46
+ .sort(([a], [b]) => a.localeCompare(b));
47
+ let settings = {};
48
+ if (settingsPath) {
49
+ try { settings = JSON.parse(await readFile(settingsPath, "utf8")); }
50
+ catch (error) { if (error.code !== "ENOENT") throw error; }
51
+ }
52
+ const npmConfigs = [];
53
+ for (const filename of npmConfigFiles) {
54
+ if (!path.isAbsolute(filename)) throw new Error("npm configuration path is not absolute.");
55
+ let raw = "";
56
+ try { raw = await readFile(filename, "utf8"); }
57
+ catch (error) { if (error.code !== "ENOENT") throw error; }
58
+ npmConfigs.push([filename, routingNpmrc(raw)]);
59
+ }
60
+ return {
61
+ contextDigest: sha(environment),
62
+ settingsDigest: sha(routingSettings(settings)),
63
+ npmConfigDigest: sha(npmConfigs),
64
+ };
65
+ }
66
+
67
+ export function assertSafeNodeOptions(env) {
68
+ const value = env.NODE_OPTIONS || env.Node_Options || "";
69
+ if (value && !/^(?:--use-system-ca|--max-old-space-size=\d+)(?:\s+(?:--use-system-ca|--max-old-space-size=\d+))*$/.test(value)) {
70
+ throw new Error("NODE_OPTIONS can alter the confirmed CLI; run updates manually with this configuration.");
71
+ }
72
+ }
73
+
74
+ export function frozenUpdateEnvironment(source, agentDir) {
75
+ assertSafeNodeOptions(source);
76
+ const env = { ...source, PI_CODING_AGENT_DIR: agentDir };
77
+ // Bash reads BASH_ENV even with --noprofile/--norc. Never allow a startup
78
+ // script to reinterpret the bound argv, while leaving npm settings intact.
79
+ for (const key of Object.keys(env)) {
80
+ if (["bash_env", "env", "cdpath"].includes(key.toLowerCase())) delete env[key];
81
+ }
82
+ return env;
83
+ }