@peakflo/agent-harness 0.2.22-rc.1 → 0.2.24-rc.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.
@@ -42,11 +42,11 @@ const vendor_backends_1 = require("../vendor-backends");
42
42
  const version_1 = require("../version");
43
43
  exports.DEFAULT_CONTROL_PLANE = 'https://api.peakflo.ai';
44
44
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
45
- const HEALTH_PORTS = [7777, 7778, 7779, ...range(7790, 7799)];
46
- const PROXY_PORTS = range(7780, 7789);
47
45
  function range(from, to) {
48
46
  return Array.from({ length: to - from + 1 }, (_, index) => from + index);
49
47
  }
48
+ const HEALTH_PORTS = [7777, 7778, 7779, ...range(7790, 7799)];
49
+ const PROXY_PORTS = range(7780, 7789);
50
50
  /** Network text shown in a terminal: no control characters, bounded. */
51
51
  function printable(text) {
52
52
  // eslint-disable-next-line no-control-regex
@@ -73,11 +73,12 @@ exports.VENDOR_SETUP = {
73
73
  login: 'cursor-agent login'
74
74
  }
75
75
  };
76
- exports.CONNECT_USAGE = `Usage: pf-agent-harness connect <codex|claude-code|cursor> --connection <id> [--control-plane <url>]
76
+ const COMPUTER_BACKENDS = ['claude-code', 'codex', 'cursor', 'pi', 'opencode'];
77
+ exports.CONNECT_USAGE = `Usage: pf-agent-harness connect [codex|claude-code|cursor] [--all] [--ask] --connection <id> [--control-plane <url>]
77
78
 
78
- Copy this command from Agents → "Connect your own agent" in Spaces (or
79
+ Copy this command from Agents → "Connect this computer" in Spaces (or
79
80
  "Reconnect" on your machine there). It approves this computer
80
- in your browser, connects the agent as your personal agent, and keeps it
81
+ in your browser, connects all usable personal agents, and keeps the runner
81
82
  running in the background.`;
82
83
  function flag(argv, name) {
83
84
  const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
@@ -111,25 +112,37 @@ function parseConnectArgs(argv, env = {}) {
111
112
  '--connection',
112
113
  '--control-plane',
113
114
  '--app-url',
114
- '--no-browser'
115
+ '--no-browser',
116
+ '--all',
117
+ '--ask'
115
118
  ]);
116
- for (let index = 1; index < argv.length; index += 1) {
119
+ for (let index = argv[0]?.startsWith('--') ? 0 : 1; index < argv.length; index += 1) {
117
120
  const name = argv[index].split('=')[0];
121
+ if (['--no-browser', '--all', '--ask'].includes(name) &&
122
+ argv[index].includes('='))
123
+ throw new ConnectError(`Use ${name} without a value.`);
118
124
  if (!known.has(name))
119
125
  throw new ConnectError(`Unknown option: ${name}\n\n${exports.CONNECT_USAGE}`);
120
- if (name !== '--no-browser' && !argv[index].includes('='))
126
+ if (!['--no-browser', '--all', '--ask'].includes(name) &&
127
+ !argv[index].includes('='))
121
128
  index += 1;
122
129
  }
123
- const vendor = argv[0];
124
- if (!vendor || !(0, vendor_backends_1.isVendorBackend)(vendor))
125
- throw new ConnectError(`Choose codex, claude-code, or cursor.\n\n${exports.CONNECT_USAGE}`);
130
+ const vendor = !argv[0] || argv[0].startsWith('--') ? 'computer' : argv[0];
131
+ if (vendor !== 'computer' && !(0, vendor_backends_1.isVendorBackend)(vendor))
132
+ throw new ConnectError(`Omit the vendor to connect this computer, or choose codex, claude-code, or cursor.\n\n${exports.CONNECT_USAGE}`);
133
+ if (vendor !== 'computer' &&
134
+ (argv.includes('--all') || argv.includes('--ask')))
135
+ throw new ConnectError('Use connect --all or connect --ask without a vendor.');
126
136
  // `--token` is refused on purpose: this command never takes a secret.
127
137
  const connection = flag(argv, 'connection');
128
138
  if (!connection || !UUID.test(connection))
129
- throw new ConnectError(`Copy the command from Agents → "Connect your own agent" in Spaces: it includes --connection <id>.\n\n${exports.CONNECT_USAGE}`);
139
+ throw new ConnectError(`Copy the command from Agents → "Connect this computer" in Spaces: it includes --connection <id>.\n\n${exports.CONNECT_USAGE}`);
130
140
  const appUrl = flag(argv, 'app-url') ?? env.PF_APP_URL;
131
141
  return {
132
142
  vendor,
143
+ ...(vendor === 'computer'
144
+ ? { all: true, askFirst: argv.includes('--ask') }
145
+ : {}),
133
146
  connection,
134
147
  controlPlane: checkUrl(flag(argv, 'control-plane') ??
135
148
  env.PF_CONTROL_PLANE_URL ??
@@ -162,7 +175,11 @@ async function choosePorts(vendor, deps) {
162
175
  return { healthPort: priorHealth, proxyPort: priorProxy };
163
176
  // Ports other services of ours were given, even if they are stopped now.
164
177
  const reserved = new Set();
165
- for (const other of [undefined, 'codex', 'claude-code', 'cursor']) {
178
+ for (const other of [
179
+ undefined,
180
+ ...vendor_backends_1.VENDOR_BACKENDS,
181
+ ...(deps.installedInstances?.() ?? [])
182
+ ]) {
166
183
  if (other === vendor)
167
184
  continue;
168
185
  const args = deps.installedStartArgs(other);
@@ -202,28 +219,114 @@ async function postJson(fetchImpl, url, body) {
202
219
  const json = (await response.json().catch(() => ({})));
203
220
  return { status: response.status, json };
204
221
  }
205
- async function runConnect(args, deps) {
222
+ function computerRoot(home, controlPlane) {
223
+ return (0, node_path_1.join)(home, '.pf-agent-harness', 'connect', 'computer', (0, node_crypto_1.createHash)('sha256').update(controlPlane).digest('hex').slice(0, 16));
224
+ }
225
+ function logComputerResult(deps, added, report) {
226
+ for (const name of added.filter((name) => COMPUTER_BACKENDS.includes(name)))
227
+ deps.log(`✓ Added ${name}.`);
228
+ for (const item of report.filter((h) => !added.includes(h.name))) {
229
+ const help = (0, vendor_backends_1.isVendorBackend)(item.name)
230
+ ? exports.VENDOR_SETUP[item.name]
231
+ : {
232
+ install: item.name === 'pi'
233
+ ? 'npm install -g @mariozechner/pi-coding-agent'
234
+ : 'npm install -g opencode-ai',
235
+ login: item.name === 'pi'
236
+ ? 'Open pi and choose a model provider.'
237
+ : 'Open opencode and configure a model provider.'
238
+ };
239
+ const reason = item.transient
240
+ ? 'check timed out. The runner retries while idle; open Machines for the result.'
241
+ : !item.installed
242
+ ? `not installed. ${help.install}`
243
+ : !item.usable
244
+ ? `${item.reason ? printable(item.reason) : 'not signed in.'} ${help.login}`
245
+ : !item.runnable
246
+ ? 'runner support is unavailable. Reinstall the runner.'
247
+ : 'not ready. Check Machines for the next discovery result.';
248
+ deps.log(`— Skipped ${item.name}: ${reason}`);
249
+ }
250
+ }
251
+ async function runConnectInner(args, deps) {
206
252
  const { vendor, connection, controlPlane } = args;
207
- const setup = exports.VENDOR_SETUP[vendor];
253
+ const setup = vendor === 'computer' ? { label: 'this computer' } : exports.VENDOR_SETUP[vendor];
254
+ const root = computerRoot(deps.home, controlPlane);
255
+ const receiptPath = (0, node_path_1.join)(root, `${connection}.json`);
256
+ if (vendor === 'computer' && (0, node_fs_1.existsSync)(receiptPath)) {
257
+ let prior;
258
+ try {
259
+ prior = JSON.parse((0, node_fs_1.readFileSync)(receiptPath, 'utf8'));
260
+ if (!prior ||
261
+ typeof prior !== 'object' ||
262
+ typeof prior.scope !== 'string' ||
263
+ typeof prior.company !== 'string' ||
264
+ !Array.isArray(prior.added) ||
265
+ !prior.added.every((name) => COMPUTER_BACKENDS.includes(name)) ||
266
+ !Array.isArray(prior.report) ||
267
+ !prior.report.every((item) => item &&
268
+ COMPUTER_BACKENDS.includes(item.name) &&
269
+ ['installed', 'usable', 'runnable'].every((key) => typeof item[key] ===
270
+ 'boolean') &&
271
+ (item.reason === undefined || typeof item.reason === 'string') &&
272
+ (item.transient === undefined ||
273
+ typeof item.transient === 'boolean')) ||
274
+ (prior.startArgs !== undefined &&
275
+ (!Array.isArray(prior.startArgs) ||
276
+ !prior.startArgs.every((arg) => typeof arg === 'string'))))
277
+ throw new Error('Invalid saved connection');
278
+ }
279
+ catch {
280
+ throw new ConnectError('The saved connection is damaged. Get a new command from Spaces.');
281
+ }
282
+ if (!/^[a-f0-9]{24}$/.test(prior.scope) ||
283
+ prior.all !== args.all ||
284
+ prior.askFirst !== args.askFirst)
285
+ throw new ConnectError('Get a new connection command from Spaces to change the connection options.');
286
+ const workspaceRoot = (0, node_path_1.join)(root, prior.scope, 'workspaces');
287
+ if (!new credential_store_1.FileCredentialStore(workspaceRoot).load())
288
+ throw new ConnectError('This connection has no saved runner credential. Get a new command from Spaces.');
289
+ const instance = `computer-${prior.scope}`;
290
+ const startArgs = deps.installedStartArgs(instance) ?? prior.startArgs;
291
+ const healthPort = argNumber(startArgs ?? null, '--health-port');
292
+ if (!startArgs || !healthPort)
293
+ throw new ConnectError('The saved service settings are missing. Get a new command from Spaces.');
294
+ if (!(await deps.waitForHealth(healthPort))) {
295
+ await deps.installService(instance, startArgs, deps.stableInstall());
296
+ if (!(await deps.waitForHealth(healthPort)))
297
+ throw new ConnectError('The saved connection could not resume. Get a new command from Spaces.');
298
+ }
299
+ deps.log(`✓ This computer is already connected to ${printable(prior.company)}. No new runner or token was created.`);
300
+ if (args.all) {
301
+ if (prior.summaryKnown === false)
302
+ deps.log('Agent setup is pending. Open Machines to confirm the result.');
303
+ else
304
+ logComputerResult(deps, prior.added, prior.report);
305
+ }
306
+ return;
307
+ }
208
308
  const log = deps.log;
209
309
  if (deps.platform !== 'darwin' && deps.platform !== 'linux')
210
310
  throw new ConnectError('connect needs macOS or Linux. On Windows, open Agents → "Connect your own agent" in Spaces and use "Ask my agent to do it instead".');
211
311
  const machine = machineName(deps.hostname());
212
312
  log(`Connecting ${setup.label} on ${machine}…`);
213
313
  /* 1. The vendor CLI must be installed and signed in. */
214
- const check = await deps.checkVendor(vendor);
215
- if (!check.installed)
216
- throw new ConnectError(`${setup.label} is not installed on this computer.\n` +
217
- ` Install it: ${setup.install}\n` +
218
- ` Sign in: ${setup.login}\n` +
219
- 'Then run this command again.');
220
- if (!check.usable && !check.transient)
221
- throw new ConnectError(`${setup.label} is installed but not signed in.\n` +
222
- ` Sign in: ${setup.login}\n` +
223
- 'Then run this command again.');
224
- log(check.usable
225
- ? `✓ ${setup.label} is installed and signed in.`
226
- : `! ${setup.label} is installed; its sign-in check is slow and will be retried in the background.`);
314
+ if (vendor !== 'computer') {
315
+ const vendorSetup = exports.VENDOR_SETUP[vendor];
316
+ const check = await deps.checkVendor(vendor);
317
+ if (!check.installed)
318
+ throw new ConnectError(`${setup.label} is not installed on this computer.\n` +
319
+ ` Install it: ${vendorSetup.install}\n` +
320
+ ` Sign in: ${vendorSetup.login}\n` +
321
+ 'Then run this command again.');
322
+ if (!check.usable && !check.transient)
323
+ throw new ConnectError(`${setup.label} is installed but not signed in.\n` +
324
+ ` Sign in: ${vendorSetup.login}\n` +
325
+ 'Then run this command again.');
326
+ log(check.usable
327
+ ? `✓ ${setup.label} is installed and signed in.`
328
+ : `! ${setup.label} is installed; its sign-in check is slow and will be retried in the background.`);
329
+ }
227
330
  /* 2. Browser approval, bound to this process by `state` and PKCE. */
228
331
  const verifier = (0, node_crypto_1.randomBytes)(32).toString('base64url');
229
332
  const challenge = (0, node_crypto_1.createHash)('sha256')
@@ -242,7 +345,10 @@ async function runConnect(args, deps) {
242
345
  machine,
243
346
  port: String(port),
244
347
  state: callback.state,
245
- challenge
348
+ challenge,
349
+ ...(vendor === 'computer'
350
+ ? { all: args.all ? '1' : '0', ask: args.askFirst ? '1' : '0' }
351
+ : {})
246
352
  });
247
353
  const approvalUrl = `${appOrigin}/connect-computer?${query.toString()}`;
248
354
  log('');
@@ -269,13 +375,41 @@ async function runConnect(args, deps) {
269
375
  ? printable(exchange.json.error)
270
376
  : `The approval could not be used (${exchange.status}). Open Agents → "Connect your own agent" in Spaces (or "Reconnect" on this machine) to get a new command.`);
271
377
  const company = typeof exchange.json.companyName === 'string'
272
- ? exchange.json.companyName
378
+ ? printable(exchange.json.companyName)
273
379
  : 'your company';
274
380
  log(`✓ Approved for ${company}.`);
275
381
  /* 4. Enrol: a personal runner for this vendor only. */
276
- const workspaceRoot = (0, node_path_1.join)(deps.home, '.pf-agent-harness', 'connect', vendor, 'workspaces');
277
- const ports = await choosePorts(vendor, deps);
278
- await deps.register({ controlPlane, enrolmentToken, vendor, workspaceRoot });
382
+ const identity = `${exchange.json.tenantId}:${exchange.json.ownerUserId}`;
383
+ if (vendor === 'computer' &&
384
+ (!UUID.test(String(exchange.json.tenantId)) ||
385
+ !UUID.test(String(exchange.json.ownerUserId))))
386
+ throw new ConnectError('The approval did not identify the account. Get a new command from Spaces.');
387
+ const scope = (0, node_crypto_1.createHash)('sha256')
388
+ .update(`${controlPlane}:${identity}`)
389
+ .digest('hex')
390
+ .slice(0, 24);
391
+ const instance = vendor === 'computer' ? `computer-${scope}` : vendor;
392
+ const workspaceRoot = vendor === 'computer'
393
+ ? (0, node_path_1.join)(root, scope, 'workspaces')
394
+ : (0, node_path_1.join)(deps.home, '.pf-agent-harness', 'connect', vendor, 'workspaces');
395
+ let computerId;
396
+ if (vendor === 'computer') {
397
+ const idPath = (0, node_path_1.join)(root, 'computer-id');
398
+ computerId = (0, node_fs_1.existsSync)(idPath)
399
+ ? (0, node_fs_1.readFileSync)(idPath, 'utf8').trim()
400
+ : (0, node_crypto_1.randomUUID)();
401
+ if (!UUID.test(computerId))
402
+ throw new ConnectError('The saved computer identity is invalid. Contact support.');
403
+ (0, node_fs_1.writeFileSync)(idPath, computerId, { mode: 0o600 });
404
+ }
405
+ const ports = await choosePorts(instance, deps);
406
+ const registration = await deps.register({
407
+ controlPlane,
408
+ enrolmentToken,
409
+ vendor,
410
+ workspaceRoot,
411
+ ...(computerId ? { computerId } : {})
412
+ });
279
413
  log('✓ This computer is registered as your personal runner.');
280
414
  /* 5. Background service, started from the saved credential. */
281
415
  log('Setting up the background service…');
@@ -289,7 +423,7 @@ async function runConnect(args, deps) {
289
423
  '--runtime',
290
424
  'desktop',
291
425
  '--vendor-harnesses',
292
- vendor,
426
+ vendor === 'computer' ? vendor_backends_1.VENDOR_BACKENDS.join(',') : vendor,
293
427
  '--workspace-root',
294
428
  workspaceRoot,
295
429
  '--health-port',
@@ -297,14 +431,76 @@ async function runConnect(args, deps) {
297
431
  '--github-proxy-port',
298
432
  String(ports.proxyPort)
299
433
  ];
300
- await deps.installService(vendor, startArgs, paths);
434
+ if (vendor === 'computer')
435
+ (0, node_fs_1.writeFileSync)(receiptPath, JSON.stringify({
436
+ scope,
437
+ company,
438
+ all: args.all,
439
+ askFirst: args.askFirst,
440
+ added: registration.connectedBackends ?? [],
441
+ summaryKnown: registration.connectedBackends !== undefined,
442
+ report: registration.report ?? [],
443
+ startArgs
444
+ }), { mode: 0o600 });
445
+ await deps.installService(instance, startArgs, paths);
301
446
  log('✓ Background service installed. It starts when you log in.');
302
447
  const healthy = await deps.waitForHealth(ports.healthPort);
303
448
  if (!healthy)
304
- log(`! The service has not answered yet (it may still be starting, or a local port was taken). Check it with: npx @peakflo/agent-harness service status --vendor ${vendor}`);
449
+ log(`! The service has not answered yet (it may still be starting, or a local port was taken). Check it with: npx @peakflo/agent-harness service status --vendor ${instance}`);
450
+ if (!healthy && vendor === 'computer')
451
+ throw new ConnectError('The runner is registered, but its service has not started. Run this same command again to repair it.');
452
+ if (vendor === 'computer' && args.all) {
453
+ if (registration.connectedBackends === undefined)
454
+ log('Agent setup is pending. Open Machines to confirm the result.');
455
+ else
456
+ logComputerResult(deps, registration.connectedBackends, registration.report ?? []);
457
+ }
305
458
  log('');
306
459
  log(`✓ ${setup.label} is connected to ${company} on ${machine}. Return to Spaces.`);
307
460
  }
461
+ async function runConnect(args, deps) {
462
+ if (args.vendor !== 'computer')
463
+ return runConnectInner(args, deps);
464
+ const root = computerRoot(deps.home, args.controlPlane);
465
+ (0, node_fs_1.mkdirSync)(root, { recursive: true, mode: 0o700 });
466
+ const lock = (0, node_path_1.join)(root, 'connecting.lock');
467
+ try {
468
+ (0, node_fs_1.mkdirSync)(lock, { mode: 0o700 });
469
+ }
470
+ catch {
471
+ let stale = false;
472
+ try {
473
+ const pid = Number((0, node_fs_1.readFileSync)((0, node_path_1.join)(lock, 'pid'), 'utf8'));
474
+ if (Number.isSafeInteger(pid) && pid > 0) {
475
+ try {
476
+ process.kill(pid, 0);
477
+ }
478
+ catch (error) {
479
+ stale = error.code === 'ESRCH';
480
+ }
481
+ }
482
+ }
483
+ catch {
484
+ /* A command may still be writing its lock. Do not steal it. */
485
+ }
486
+ if (!stale)
487
+ throw new ConnectError('A computer connection is already running. Finish it in the other terminal.');
488
+ (0, node_fs_1.rmSync)(lock, { recursive: true, force: true });
489
+ try {
490
+ (0, node_fs_1.mkdirSync)(lock, { mode: 0o700 });
491
+ }
492
+ catch {
493
+ throw new ConnectError('A computer connection is already running.');
494
+ }
495
+ }
496
+ (0, node_fs_1.writeFileSync)((0, node_path_1.join)(lock, 'pid'), String(process.pid), { mode: 0o600 });
497
+ try {
498
+ await runConnectInner(args, deps);
499
+ }
500
+ finally {
501
+ (0, node_fs_1.rmSync)(lock, { recursive: true, force: true });
502
+ }
503
+ }
308
504
  /* -------------------------------------------------------------------------- */
309
505
  /* Real dependencies */
310
506
  /* -------------------------------------------------------------------------- */
@@ -346,11 +542,35 @@ function defaultConnectDeps(context) {
346
542
  };
347
543
  },
348
544
  createCallback: () => new approval_callback_1.ApprovalCallback(),
349
- register: async ({ controlPlane, enrolmentToken, vendor, workspaceRoot }) => {
545
+ register: async ({ controlPlane, enrolmentToken, vendor, workspaceRoot, computerId }) => {
350
546
  const capabilities = await (0, capabilities_1.probeCapabilities)({
351
547
  maxConcurrentSessions: 10
352
548
  });
353
- capabilities.vendorHarnesses = [vendor];
549
+ capabilities.vendorHarnesses =
550
+ vendor === 'computer' ? [...vendor_backends_1.VENDOR_BACKENDS] : [vendor];
551
+ let report = [];
552
+ if (vendor === 'computer') {
553
+ Object.assign(capabilities, { computerId });
554
+ report = await (0, harness_discovery_1.discoverHarnesses)({
555
+ runnableBackends: COMPUTER_BACKENDS
556
+ });
557
+ for (const h of report) {
558
+ if (h.installed &&
559
+ h.usable &&
560
+ (0, vendor_backends_1.isVendorBackend)(h.name) &&
561
+ !(0, vendor_backends_1.vendorBackendBlocker)(h.name, 'desktop') &&
562
+ !capabilities.backends.some((b) => b.name === h.name))
563
+ capabilities.backends.push({
564
+ name: h.name,
565
+ version: h.version ?? null
566
+ });
567
+ h.runnable =
568
+ h.installed &&
569
+ h.usable &&
570
+ capabilities.backends.some((b) => b.name === h.name);
571
+ }
572
+ capabilities.harnesses = report;
573
+ }
354
574
  const client = new control_plane_1.ControlPlaneClient(controlPlane);
355
575
  const response = await client.register({
356
576
  enrolmentToken,
@@ -368,9 +588,30 @@ function defaultConnectDeps(context) {
368
588
  credentialExpiresAt: response.credentialExpiresAt ?? null,
369
589
  savedAt: new Date().toISOString()
370
590
  });
371
- return { runnerId };
591
+ return {
592
+ runnerId,
593
+ connectedBackends: response.connectedBackends,
594
+ report: report.map(({ name, installed, usable, runnable, transient, reason }) => ({
595
+ name,
596
+ installed,
597
+ usable,
598
+ runnable,
599
+ transient,
600
+ reason
601
+ }))
602
+ };
372
603
  },
373
604
  installedStartArgs: (instance) => manager(instance).installedStartArgs(),
605
+ installedInstances: () => {
606
+ try {
607
+ return (0, node_fs_1.readdirSync)((0, node_path_1.join)(home, '.pf-agent-harness'))
608
+ .filter((name) => /^service-computer-[a-f0-9]{24}\.json$/.test(name))
609
+ .map((name) => name.slice('service-'.length, -'.json'.length));
610
+ }
611
+ catch {
612
+ return [];
613
+ }
614
+ },
374
615
  portOccupied: portInUse,
375
616
  stableInstall: () => {
376
617
  const inNpxCache = context.cliPath.includes('/_npx/') ||
@@ -96,8 +96,9 @@ export declare function isProtocolSupported(peerProtocolVersion: unknown, floor?
96
96
  * ingest and must exit rather than hammer a control plane that will never
97
97
  * serve them.
98
98
  *
99
- * 401 IS FINAL, AND THAT IS DELIBERATE — a harness must NOT try to rotate its
100
- * way out of one. Rotation is authenticated with the CURRENT credential, so a
99
+ * 401 IS FINAL, AND THAT IS DELIBERATE — a harness must NOT loop trying to
100
+ * rotate its way out of one. (It makes ONE rotation attempt on a heartbeat 401,
101
+ * in case the credential is only skewed, then stops.) Rotation is authenticated with the CURRENT credential, so a
101
102
  * credential that has already expired cannot rotate itself; a harness that
102
103
  * tried would loop between two routes that can only both fail. `rotateAfter`
103
104
  * is the mechanism: rotate on schedule, comfortably before expiry, and treat
package/dist/contract.js CHANGED
@@ -115,8 +115,9 @@ function isProtocolSupported(peerProtocolVersion, floor = exports.MIN_SUPPORTED_
115
115
  * ingest and must exit rather than hammer a control plane that will never
116
116
  * serve them.
117
117
  *
118
- * 401 IS FINAL, AND THAT IS DELIBERATE — a harness must NOT try to rotate its
119
- * way out of one. Rotation is authenticated with the CURRENT credential, so a
118
+ * 401 IS FINAL, AND THAT IS DELIBERATE — a harness must NOT loop trying to
119
+ * rotate its way out of one. (It makes ONE rotation attempt on a heartbeat 401,
120
+ * in case the credential is only skewed, then stops.) Rotation is authenticated with the CURRENT credential, so a
120
121
  * credential that has already expired cannot rotate itself; a harness that
121
122
  * tried would loop between two routes that can only both fail. `rotateAfter`
122
123
  * is the mechanism: rotate on schedule, comfortably before expiry, and treat
@@ -47,6 +47,12 @@ export interface StoredCredential {
47
47
  credential: string;
48
48
  /** ISO 8601, or null when the control plane returned no expiry. */
49
49
  credentialExpiresAt: string | null;
50
+ /**
51
+ * ISO 8601. When the control plane wants this credential rotated. Persisted
52
+ * so a restart can resume the schedule instead of waiting for a fresh
53
+ * registration (which a stored-credential start never has).
54
+ */
55
+ rotateAfter?: string | null;
50
56
  /** ISO 8601. When this row was written, for operator diagnostics. */
51
57
  savedAt: string;
52
58
  }
package/dist/harness.d.ts CHANGED
@@ -51,7 +51,7 @@ export declare class VersionRefusedError extends Error {
51
51
  }
52
52
  /** A service cannot re-enrol without a new one-time token from a user. */
53
53
  export declare class StoredCredentialUnavailableError extends Error {
54
- constructor();
54
+ constructor(reason?: string);
55
55
  }
56
56
  /** The sandbox supervisor, not the harness, owns package installation. */
57
57
  export declare class UpgradeRequestedError extends Error {
@@ -243,6 +243,13 @@ export declare class Harness {
243
243
  private lastHeartbeatAt;
244
244
  private lastHeartbeatError;
245
245
  private consecutiveHeartbeatFailures;
246
+ /**
247
+ * True while the harness drains ONLY because heartbeats failed ("presumed
248
+ * offline"). It is not a drain the control plane asked for, so it ends on
249
+ * the first heartbeat that gets through, and the lease loop waits instead of
250
+ * exiting.
251
+ */
252
+ private offlineDraining;
246
253
  private stopping;
247
254
  /** Releases this Harness's reference to the process-wide generic wrappers. */
248
255
  private releaseGitHubGuard;
@@ -338,6 +345,16 @@ export declare class Harness {
338
345
  * will surface that.
339
346
  */
340
347
  private rotateCredential;
348
+ /**
349
+ * The control plane answered 401/403 to the runner credential.
350
+ *
351
+ * Try ONE rotation first: a credential that is merely close to the edge (a
352
+ * clock skew, a heartbeat that raced the expiry) may still rotate. If it
353
+ * cannot, the credential is gone. A service has no token to enrol with, so
354
+ * retrying would loop for ever. Stop with a message that says what to do and
355
+ * a non-zero exit so launchd and systemd show a failure.
356
+ */
357
+ private handleCredentialRejected;
341
358
  /**
342
359
  * Re-probe the model catalogue.
343
360
  *