@amalgm/shell 0.1.164-preview.35467590405 → 0.1.164-preview.35469606489

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.
@@ -6,6 +6,8 @@ import { homedir as osHomedir, hostname, platform, release } from "node:os";
6
6
  import { join, resolve } from "node:path";
7
7
  import { admitRuntimeFormat } from './updates/store.js';
8
8
  import { serviceIdentity } from './service/registration.js';
9
+ import { RuntimeWireHost } from './runtime-wire-host.js';
10
+ import { readSyncMode, writeSyncMode, syncPausedError } from './sync-setting.js';
9
11
  import { buildRootManifest, approveMachineSetup, adoptMachineSetup, joinApprovedMachine, mergeRecordAuth, resumeMachine, resolveRuntimeBinding, runtimeBindingsMatch, runtimeBindingFromRecord, RUNTIME_IDENTITY_PATH, createRuntimeIdentity, runtimeRootSegments, resolveRuntimeEndpoint, scopedAmalgmDir, userMachineDir, } from "@amalgm/core/identity";
10
12
  import { StateRail } from "@amalgm/core/state";
11
13
  import { atomicJson, atomicJsonSet, ensurePrivateDir, readJson, } from "./filesystem.js";
@@ -45,6 +47,14 @@ export class MachineHost {
45
47
  ownership;
46
48
  selectedUserEmail;
47
49
  groundHost = null;
50
+ runtimeWire = null;
51
+ activeSyncMode = null;
52
+ syncPhase = 'stopped';
53
+ syncError;
54
+ syncStart = null;
55
+ syncChange = Promise.resolve();
56
+ createGround = null;
57
+ syncIdentity = null;
48
58
  /** Apps while a runtime holds it: the product that answers for `app`. */
49
59
  appsProduct = null;
50
60
  running = new Set();
@@ -164,27 +174,52 @@ export class MachineHost {
164
174
  throw Object.assign(new Error("machine tunnel credentials are missing"), { code: "tunnel_credentials_missing" });
165
175
  }
166
176
  await this.groundHost?.close();
167
- const { UserGroundHost } = await import("./user-ground-host.js");
168
- this.groundHost = new UserGroundHost({
169
- amalgmRoot: this.amalgmRoot,
170
- deviceId: identity.deviceId,
171
- tunnelUrl,
172
- tunnelToken,
177
+ this.groundHost = null;
178
+ await this.runtimeWire?.close();
179
+ this.runtimeWire = new RuntimeWireHost({
180
+ url: runtimeWireUrl(this.binding, this.options.appUrl, tunnelUrl, this.options.wireUrl),
181
+ token: tunnelToken,
173
182
  runtimeVersion: this.options.runtimeVersion,
174
- reserveWritableRoot: (path) => { this.ownership.reserve(path, identity.userEmail); },
175
- openWatch: this.options.openWatch,
176
- onWatchHealth: this.options.onWatchHealth,
177
- onDetectScan: this.options.onDetectScan,
178
- onApplyStage: this.options.onApplyStage,
179
- onApplyError: this.options.onApplyError,
180
- onWorkspaceAddStage: this.options.onWorkspaceAddStage,
181
- onFilesStage: this.stages.observe,
182
- filesTraceActive: () => this.stages.listening,
183
- // The products are selected when the runtime starts, after this
184
- // rail exists, so the owner of a construct type is asked per act.
185
- constructProduct: (type) => (type === "app" ? this.appsProduct : null),
186
- });
187
- return this.groundHost.port.converge(identity);
183
+ }, (error) => this.options.onWireError?.(error));
184
+ this.activeSyncMode = this.syncMode();
185
+ if (!existsSync(this.syncSettingFile()))
186
+ writeSyncMode(this.syncSettingFile(), this.activeSyncMode);
187
+ this.syncIdentity = identity;
188
+ this.createGround = async () => {
189
+ const { UserGroundHost } = await import("./user-ground-host.js");
190
+ return new UserGroundHost({
191
+ wire: this.runtimeWire.client,
192
+ amalgmRoot: this.amalgmRoot,
193
+ deviceId: identity.deviceId,
194
+ tunnelUrl,
195
+ tunnelToken,
196
+ runtimeVersion: this.options.runtimeVersion,
197
+ reserveWritableRoot: (path) => { this.ownership.reserve(path, identity.userEmail); },
198
+ openWatch: this.options.openWatch,
199
+ onWatchHealth: this.options.onWatchHealth,
200
+ onDetectScan: this.options.onDetectScan,
201
+ onApplyStage: this.options.onApplyStage,
202
+ onApplyError: this.options.onApplyError,
203
+ onWorkspaceAddStage: this.options.onWorkspaceAddStage,
204
+ onFilesStage: this.stages.observe,
205
+ filesTraceActive: () => this.stages.listening,
206
+ // The products are selected when the runtime starts, after this
207
+ // rail exists, so the owner of a construct type is asked per act.
208
+ constructProduct: (type) => (type === "app" ? this.appsProduct : null),
209
+ });
210
+ };
211
+ if (this.activeSyncMode === 'paused') {
212
+ this.syncPhase = 'paused';
213
+ return {
214
+ ...identity, localRoot: this.paths().userRoot, mode: 'paused',
215
+ cloudHead: null, entityCount: null, watcherRoots: 0, watching: false,
216
+ };
217
+ }
218
+ this.syncPhase = 'starting';
219
+ this.groundHost = await this.createGround();
220
+ const evidence = await this.groundHost.port.converge(identity);
221
+ this.syncPhase = 'enabled';
222
+ return evidence;
188
223
  },
189
224
  };
190
225
  const runtime = {
@@ -318,6 +353,7 @@ export class MachineHost {
318
353
  if (!deviceId) {
319
354
  return {
320
355
  binding: this.binding,
356
+ sync: 'enabled',
321
357
  wireComposed: this.wireComposed,
322
358
  user,
323
359
  deviceId: null,
@@ -361,6 +397,7 @@ export class MachineHost {
361
397
  : { published: false, running: false, pid: null, port: null };
362
398
  return {
363
399
  binding: this.binding,
400
+ sync: this.syncMode(),
364
401
  wireComposed: this.wireComposed,
365
402
  user,
366
403
  deviceId,
@@ -375,86 +412,95 @@ export class MachineHost {
375
412
  };
376
413
  }
377
414
  filesCommandPorts() {
415
+ this.assertSyncEnabled();
378
416
  if (!this.groundHost)
379
417
  throw new Error("Files commands require a resumed authenticated machine");
380
418
  return this.groundHost.filesCommandPorts();
381
419
  }
382
420
  /** Materialize through Live and prove the same runtime owns ongoing Watch. */
383
421
  async addWorkspace(workspaceId, destinationParent) {
422
+ this.assertSyncEnabled();
384
423
  if (!this.groundHost)
385
424
  throw new Error("add requires a running authenticated runtime");
386
- const started = performance.now();
387
- emitFilesStage(this.stages.observe, {
388
- primitive: "download", stage: "files-add", status: "started", workspaceId,
389
- });
390
- try {
391
- const { addFilesWorkspace } = await import("@amalgm/live/files");
392
- const added = await addFilesWorkspace(workspaceId, destinationParent, this.groundHost.filesCommandPorts().add);
393
- const result = { ...added, watch: this.groundHost.addedWorkspaceEvidence(added.workspaceId) };
425
+ const ground = this.groundHost;
426
+ return ground.operation(async () => {
427
+ const started = performance.now();
394
428
  emitFilesStage(this.stages.observe, {
395
- primitive: "download",
396
- stage: "files-add",
397
- status: "completed",
398
- workspaceId,
399
- durationMs: performance.now() - started,
429
+ primitive: "download", stage: "files-add", status: "started", workspaceId,
400
430
  });
401
- return result;
402
- }
403
- catch (error) {
404
- emitFilesStage(this.stages.observe, {
405
- primitive: "download",
406
- stage: "files-add",
407
- status: "failed",
408
- workspaceId,
409
- durationMs: performance.now() - started,
410
- });
411
- throw error;
412
- }
431
+ try {
432
+ const { addFilesWorkspace } = await import("@amalgm/live/files");
433
+ const added = await addFilesWorkspace(workspaceId, destinationParent, ground.filesCommandPorts().add);
434
+ const result = { ...added, watch: ground.addedWorkspaceEvidence(added.workspaceId) };
435
+ emitFilesStage(this.stages.observe, {
436
+ primitive: "download",
437
+ stage: "files-add",
438
+ status: "completed",
439
+ workspaceId,
440
+ durationMs: performance.now() - started,
441
+ });
442
+ return result;
443
+ }
444
+ catch (error) {
445
+ emitFilesStage(this.stages.observe, {
446
+ primitive: "download",
447
+ stage: "files-add",
448
+ status: "failed",
449
+ workspaceId,
450
+ durationMs: performance.now() - started,
451
+ });
452
+ throw error;
453
+ }
454
+ });
413
455
  }
414
456
  /** Route the complete user-visible register journey through Live's
415
457
  * declaration and this already-running Files owner. */
416
458
  async registerWorkspace(requestedPath) {
459
+ this.assertSyncEnabled();
417
460
  if (!this.groundHost)
418
461
  throw new Error("register requires a running authenticated runtime");
419
- const journeyStarted = performance.now();
420
- const declarationStarted = performance.now();
421
- emitFilesStage(this.stages.observe, {
422
- primitive: "register", stage: "files-register", status: "started", path: requestedPath,
423
- });
424
- emitFilesStage(this.stages.observe, {
425
- primitive: "register", stage: "durable-declaration", status: "started", path: requestedPath,
426
- });
427
- try {
428
- const declared = await (await import("@amalgm/live/files")).registerFilesWorkspace(requestedPath, this.groundHost.filesCommandPorts().register);
429
- emitFilesStage(this.stages.observe, {
430
- primitive: "register",
431
- stage: "durable-declaration",
432
- status: "completed",
433
- path: requestedPath,
434
- workspaceId: declared.workspaceId,
435
- durationMs: performance.now() - declarationStarted,
436
- });
437
- const completed = await this.groundHost.completeWorkspaceRegistration(declared.workspaceId);
462
+ const ground = this.groundHost;
463
+ return ground.operation(async () => {
464
+ const journeyStarted = performance.now();
465
+ const declarationStarted = performance.now();
438
466
  emitFilesStage(this.stages.observe, {
439
- primitive: "register",
440
- stage: "files-register",
441
- status: "completed",
442
- path: requestedPath,
443
- workspaceId: declared.workspaceId,
444
- durationMs: performance.now() - journeyStarted,
467
+ primitive: "register", stage: "files-register", status: "started", path: requestedPath,
445
468
  });
446
- return { ...declared, ...completed };
447
- }
448
- catch (error) {
449
469
  emitFilesStage(this.stages.observe, {
450
- primitive: "register",
451
- stage: "files-register",
452
- status: "failed",
453
- path: requestedPath,
454
- durationMs: performance.now() - journeyStarted,
470
+ primitive: "register", stage: "durable-declaration", status: "started", path: requestedPath,
455
471
  });
456
- throw error;
457
- }
472
+ try {
473
+ const declared = await (await import("@amalgm/live/files")).registerFilesWorkspace(requestedPath, ground.filesCommandPorts().register);
474
+ emitFilesStage(this.stages.observe, {
475
+ primitive: "register",
476
+ stage: "durable-declaration",
477
+ status: "completed",
478
+ path: requestedPath,
479
+ workspaceId: declared.workspaceId,
480
+ durationMs: performance.now() - declarationStarted,
481
+ });
482
+ const completed = await ground.completeWorkspaceRegistration(declared.workspaceId);
483
+ emitFilesStage(this.stages.observe, {
484
+ primitive: "register",
485
+ stage: "files-register",
486
+ status: "completed",
487
+ path: requestedPath,
488
+ workspaceId: declared.workspaceId,
489
+ durationMs: performance.now() - journeyStarted,
490
+ });
491
+ return { ...declared, ...completed };
492
+ }
493
+ catch (error) {
494
+ emitFilesStage(this.stages.observe, {
495
+ primitive: "register",
496
+ stage: "files-register",
497
+ status: "failed",
498
+ path: requestedPath,
499
+ durationMs: performance.now() - journeyStarted,
500
+ });
501
+ throw error;
502
+ }
503
+ });
458
504
  }
459
505
  /** Run one Files journey, returning its own stage ledger with the result
460
506
  * when the caller asked to be traced. The CLI process owns no Files
@@ -467,6 +513,7 @@ export class MachineHost {
467
513
  return { ...captured.result, stages: serializeStages(captured.stages) };
468
514
  }
469
515
  watchEvidence() {
516
+ this.assertSyncEnabled();
470
517
  if (!this.groundHost)
471
518
  throw new Error("Watch evidence requires a running authenticated runtime");
472
519
  return this.groundHost.watchEvidence();
@@ -494,12 +541,98 @@ export class MachineHost {
494
541
  this.ownership.close();
495
542
  }
496
543
  async drainRuntime(options = {}) {
544
+ await this.syncChange;
497
545
  const runtimes = [...this.running];
498
546
  this.running.clear();
499
- await this.groundHost?.close(options);
547
+ // A pause must never flush uploads or scan as a side effect of stopping.
548
+ const paused = this.activeSyncMode === 'paused' || this.syncPhase !== 'enabled'
549
+ || (this.groundHost && this.syncMode() === 'paused');
550
+ if (paused || options.catchUp === false)
551
+ await this.runtimeWire?.close();
552
+ await this.groundHost?.close(paused ? { catchUp: false } : options);
553
+ await this.syncStart;
500
554
  this.groundHost = null;
501
555
  for (const runtime of runtimes)
502
556
  await runtime.stop().catch(() => undefined);
557
+ await this.runtimeWire?.close();
558
+ this.runtimeWire = null;
559
+ this.createGround = null;
560
+ this.syncIdentity = null;
561
+ this.syncPhase = 'stopped';
562
+ }
563
+ syncSettingFile() { return join(this.paths().machineDir, 'sync.json'); }
564
+ syncMode() { return readSyncMode(this.syncSettingFile()); }
565
+ syncStatus() {
566
+ return { configured: this.syncMode(),
567
+ state: this.wireComposed ? this.syncPhase : 'unavailable',
568
+ ...(this.syncError ? { error: this.syncError } : {}) };
569
+ }
570
+ /** The single control point for CLI, API and future product policy. */
571
+ setSyncMode(mode) {
572
+ const change = this.syncChange.then(async () => {
573
+ writeSyncMode(this.syncSettingFile(), mode);
574
+ if (!this.createGround || !this.syncIdentity)
575
+ return this.syncStatus();
576
+ this.activeSyncMode = mode;
577
+ if (mode === 'paused') {
578
+ this.syncPhase = 'pausing';
579
+ try {
580
+ await this.groundHost?.close({ catchUp: false });
581
+ }
582
+ catch (error) {
583
+ this.syncError = error instanceof Error ? error.message : String(error);
584
+ this.syncPhase = 'failed';
585
+ return this.syncStatus();
586
+ }
587
+ await this.syncStart;
588
+ this.groundHost = null;
589
+ this.syncStart = null;
590
+ this.syncError = undefined;
591
+ this.syncPhase = 'paused';
592
+ }
593
+ else if (this.syncPhase !== 'starting' && this.syncPhase !== 'enabled') {
594
+ this.syncPhase = 'starting';
595
+ this.syncError = undefined;
596
+ let ground;
597
+ try {
598
+ await this.groundHost?.close({ catchUp: false });
599
+ ground = await this.createGround();
600
+ }
601
+ catch (error) {
602
+ this.syncError = error instanceof Error ? error.message : String(error);
603
+ this.syncPhase = 'failed';
604
+ return this.syncStatus();
605
+ }
606
+ this.groundHost = ground;
607
+ this.syncStart = ground.port.converge(this.syncIdentity).then(() => {
608
+ if (this.activeSyncMode === 'enabled')
609
+ this.syncPhase = 'enabled';
610
+ }, async (error) => {
611
+ // A requested pause owns shutdown; any other failure is contained
612
+ // in Files and leaves the runtime, its chat and its Wire untouched.
613
+ if (this.activeSyncMode === 'paused')
614
+ return;
615
+ try {
616
+ await ground.close({ catchUp: false });
617
+ this.groundHost = null;
618
+ }
619
+ catch (stopError) {
620
+ error = new AggregateError([error, stopError], 'Sync failed and could not finish stopping');
621
+ }
622
+ this.syncError = error instanceof Error ? error.message : String(error);
623
+ this.syncPhase = 'failed';
624
+ });
625
+ }
626
+ return this.syncStatus();
627
+ });
628
+ this.syncChange = change.then(() => undefined, () => undefined);
629
+ return change;
630
+ }
631
+ assertSyncEnabled() {
632
+ if ((this.activeSyncMode ?? this.syncMode()) === 'paused')
633
+ throw syncPausedError();
634
+ if (this.syncPhase !== 'enabled')
635
+ throw new Error(`Sync is ${this.syncPhase}${this.syncError ? `: ${this.syncError}` : '.'}`);
503
636
  }
504
637
  ensureInstallationRoot() {
505
638
  ensurePrivateDir(this.amalgmRoot);
@@ -748,10 +881,11 @@ export class MachineHost {
748
881
  ? new appsSdk.Apps({
749
882
  stateDir: join(serviceStateRoot, "apps"),
750
883
  recordConstruct: (change) => {
884
+ this.assertSyncEnabled();
751
885
  const ground = this.groundHost;
752
886
  if (!ground)
753
887
  throw new Error("Recording an app requires a converged runtime");
754
- return ground.recordConstruct({ entityType: "app", ...change });
888
+ return ground.operation(() => ground.recordConstruct({ entityType: "app", ...change }));
755
889
  },
756
890
  })
757
891
  : null;
@@ -811,6 +945,7 @@ export class MachineHost {
811
945
  // under a long-lived mount.
812
946
  const sharing = (await import("./sharing-host.js")).createSharingSurface({
813
947
  ports: () => {
948
+ this.assertSyncEnabled();
814
949
  if (!this.groundHost)
815
950
  throw new Error("Sharing requires a running authenticated runtime");
816
951
  return this.groundHost.sharingPorts({
@@ -905,6 +1040,14 @@ export class MachineHost {
905
1040
  exemptPrefixes: ["/chat/egress/"],
906
1041
  mounts: [
907
1042
  { prefix: RUNTIME_IDENTITY_PATH, handle: async () => runtimeIdentity },
1043
+ { prefix: '/sync', handle: async (body) => {
1044
+ const mode = body?.mode;
1045
+ if (mode === undefined)
1046
+ return this.syncStatus();
1047
+ if (mode !== 'paused' && mode !== 'enabled')
1048
+ throw new Error('Invalid sync mode');
1049
+ return this.setSyncMode(mode);
1050
+ } },
908
1051
  {
909
1052
  prefix: "/entities/register",
910
1053
  handle: (body) => this.journey(body, () => this.registerWorkspace(bodyText(body, "path"))),
@@ -989,8 +1132,8 @@ export class MachineHost {
989
1132
  });
990
1133
  let commandPublication = null;
991
1134
  try {
992
- if (this.wireComposed && !this.groundHost)
993
- throw new Error("Files must converge before the runtime starts");
1135
+ if (this.wireComposed && !this.runtimeWire)
1136
+ throw new Error('Authenticated Gateway transport is missing');
994
1137
  await new Promise((resolve, reject) => {
995
1138
  gateway.once("error", reject);
996
1139
  gateway.listen(this.options.runtimePort ?? 0, "127.0.0.1", () => resolve());
@@ -998,7 +1141,7 @@ export class MachineHost {
998
1141
  const address = gateway.address();
999
1142
  if (!address || typeof address === "string")
1000
1143
  throw new Error("runtime gateway did not bind a TCP port");
1001
- await this.groundHost?.activateRuntimeTunnel(address.port, runtimeToken);
1144
+ await this.runtimeWire?.start(address.port, runtimeToken);
1002
1145
  products?.runner.start();
1003
1146
  commandPublication = {
1004
1147
  instanceId: runtimeIdentity.instanceId,
@@ -1023,7 +1166,7 @@ export class MachineHost {
1023
1166
  this.running.delete(running);
1024
1167
  if (commandPublication)
1025
1168
  unpublishRuntimeCommands(commandPublication);
1026
- await this.groundHost?.stopRuntimeTunnel();
1169
+ this.runtimeWire?.client.configureRuntime({});
1027
1170
  const terminalsClosed = Promise.allSettled([pty.close()]);
1028
1171
  try {
1029
1172
  const closed = new Promise((resolve) => gateway.close(() => resolve()));
@@ -1053,7 +1196,7 @@ export class MachineHost {
1053
1196
  catch (error) {
1054
1197
  if (commandPublication)
1055
1198
  unpublishRuntimeCommands(commandPublication);
1056
- await this.groundHost?.stopRuntimeTunnel().catch(() => undefined);
1199
+ this.runtimeWire?.client.configureRuntime({});
1057
1200
  const terminalsClosed = Promise.allSettled([pty.close()]);
1058
1201
  for (const close of [
1059
1202
  async () => {