@capybara-hq/device 0.1.0-rc.16 → 0.1.0-rc.18

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 (65) hide show
  1. package/README.md +79 -0
  2. package/dist/activity.d.ts +31 -0
  3. package/dist/activity.js +62 -0
  4. package/dist/args.d.ts +18 -2
  5. package/dist/args.js +56 -8
  6. package/dist/cli.js +13 -2
  7. package/dist/commands/ceiling.js +22 -0
  8. package/dist/commands/keep-awake.d.ts +19 -0
  9. package/dist/commands/keep-awake.js +77 -0
  10. package/dist/commands/login.js +29 -16
  11. package/dist/commands/service.d.ts +3 -1
  12. package/dist/commands/service.js +35 -2
  13. package/dist/commands/start.d.ts +7 -0
  14. package/dist/commands/start.js +120 -1
  15. package/dist/commands/status.d.ts +8 -1
  16. package/dist/commands/status.js +50 -2
  17. package/dist/control/client.d.ts +12 -0
  18. package/dist/control/client.js +63 -0
  19. package/dist/control/protocol.d.ts +58 -0
  20. package/dist/control/protocol.js +16 -0
  21. package/dist/control/server.d.ts +28 -0
  22. package/dist/control/server.js +254 -0
  23. package/dist/exec/mac-operation-backend.d.ts +5 -0
  24. package/dist/exec/mac-operation-backend.js +26 -6
  25. package/dist/exec/native-helper-client.js +10 -2
  26. package/dist/exec/operation-supervisor.d.ts +30 -1
  27. package/dist/exec/operation-supervisor.js +60 -2
  28. package/dist/exec/operation-worker.js +3 -0
  29. package/dist/exec/transfer-timing.d.ts +16 -0
  30. package/dist/exec/transfer-timing.js +26 -0
  31. package/dist/index.d.ts +2 -0
  32. package/dist/index.js +1 -0
  33. package/dist/keep-awake.d.ts +39 -0
  34. package/dist/keep-awake.js +104 -0
  35. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +22 -4
  36. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +4 -3
  37. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -1
  38. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -1
  39. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +1 -1
  40. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
  41. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
  42. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
  43. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
  44. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
  45. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
  46. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  49. package/dist/runtime-manifest.json +1 -1
  50. package/dist/server-ops.d.ts +3 -0
  51. package/dist/server-ops.js +33 -0
  52. package/dist/service/launchd.d.ts +2 -0
  53. package/dist/service/launchd.js +10 -4
  54. package/dist/service/manager.d.ts +2 -0
  55. package/dist/service/manager.js +16 -2
  56. package/dist/service/systemd.d.ts +2 -0
  57. package/dist/service/systemd.js +8 -2
  58. package/dist/staged-connect.d.ts +9 -0
  59. package/dist/staged-connect.js +24 -2
  60. package/dist/staged-device.js +6 -0
  61. package/dist/state.d.ts +9 -0
  62. package/dist/state.js +9 -1
  63. package/dist/wake.d.ts +23 -0
  64. package/dist/wake.js +29 -0
  65. package/package.json +2 -2
@@ -1,4 +1,5 @@
1
1
  import { type DeviceLocalPolicySummary, type DeviceOwnerCeiling, type DeviceResponse, type KernelRequest, type SandboxHandle } from "@capybara-hq/plugin-sdk";
2
+ import type { RunningOperations } from "./activity.js";
2
3
  import type { CommandLog } from "./command-log.js";
3
4
  import type { InstanceBinder } from "./exec/instance-binding.js";
4
5
  import type { MacOperationBackend } from "./exec/mac-operation-backend.js";
@@ -24,6 +25,8 @@ export interface StagedOwnerPolicy {
24
25
  reconcile: (signal: AbortSignal) => Promise<void>;
25
26
  /** The owner's local command log: operations and policy changes are recorded there. */
26
27
  log?: CommandLog;
28
+ /** The operations executing now, for the control socket's `running` op (never their command). */
29
+ running?: RunningOperations;
27
30
  }
28
31
  /**
29
32
  * The device's one operation dispatch (protocol 3): every request is parsed strictly first, so an
@@ -409,6 +409,17 @@ export async function serveOperationV3(backend, handle, request, signal, binder,
409
409
  ...(a.cwd === undefined ? {} : { cwd: a.cwd }),
410
410
  ...(a.env === undefined ? {} : { env: a.env }),
411
411
  };
412
+ // listed as running from here until its worker is gone (an exec: its answer; a background
413
+ // task: the backend reports its end, completion or kill); never the command
414
+ const entry = operationEntry(parsed.op, a, scope, null);
415
+ const running = owner?.running;
416
+ running?.begin({
417
+ tag: entry.tag ?? "",
418
+ conversationId: entry.actor?.conversationId || null,
419
+ accountId: entry.actor?.accountId || null,
420
+ isolation: entry.isolation ?? "restricted",
421
+ startedAt: new Date().toISOString(),
422
+ }, scope.operationId);
412
423
  try {
413
424
  result =
414
425
  parsed.op === "exec"
@@ -421,9 +432,14 @@ export async function serveOperationV3(backend, handle, request, signal, binder,
421
432
  });
422
433
  }
423
434
  catch (error) {
435
+ running?.endOperation(scope.operationId);
424
436
  note(owner?.log, operationEntry(parsed.op, a, scope, null, errorKind(sdk, error)));
425
437
  throw error;
426
438
  }
439
+ if (parsed.op === "exec")
440
+ running?.endOperation(scope.operationId);
441
+ else if (running)
442
+ await keepIfStillRunning(running, backend, handle, result, scope, signal);
427
443
  const exitCode = parsed.op === "exec" ? (result.exitCode ?? null) : null;
428
444
  note(owner?.log, operationEntry(parsed.op, a, scope, exitCode));
429
445
  }
@@ -490,6 +506,23 @@ export async function serveOperationV3(backend, handle, request, signal, binder,
490
506
  };
491
507
  }
492
508
  }
509
+ /**
510
+ * A started background task stays in the running operations only while it runs: one that already
511
+ * ended (a fast task, or a retried start of a finished one, whose worker end was reported before
512
+ * or never) leaves now. A status that cannot be read leaves it too: a list that misses a task is
513
+ * safer than one that keeps the machine busy for good.
514
+ */
515
+ async function keepIfStillRunning(running, backend, handle, ref, scope, signal) {
516
+ try {
517
+ const status = await backend.background.status(handle, ref, signal);
518
+ if (status.state === "running")
519
+ return;
520
+ }
521
+ catch {
522
+ // unreadable: not kept
523
+ }
524
+ running.endOperation(scope.operationId);
525
+ }
493
526
  /** The protocol error kind of an operation's failure. */
494
527
  function errorKind(sdk, error) {
495
528
  return sdk.isSandboxScopeDeniedError(error)
@@ -25,6 +25,8 @@ export declare function plistPath(home: string): string;
25
25
  export declare function plistContent(spec: ServiceSpec): string;
26
26
  /** The bin script a plist runs (the second `ProgramArguments` string), or undefined. */
27
27
  export declare function plistBinPath(content: string): string | undefined;
28
+ /** The node binary a plist runs (the first `ProgramArguments` string), or undefined. */
29
+ export declare function plistNodePath(content: string): string | undefined;
28
30
  export declare const SERVICE_LOG_MAX_BYTES: number;
29
31
  /** Keeps `service.log` from growing without bound: past 10 MiB it is copied to `.1` and emptied. */
30
32
  export declare function rotateServiceLog(stateDir: string, maxBytes?: number): void;
@@ -59,13 +59,19 @@ ${env}
59
59
  function unxml(s) {
60
60
  return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
61
61
  }
62
- /** The bin script a plist runs (the second `ProgramArguments` string), or undefined. */
63
- export function plistBinPath(content) {
62
+ function plistProgramArguments(content) {
64
63
  const args = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(content)?.[1];
65
64
  if (args === undefined)
66
65
  return undefined;
67
- const strings = [...args.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1] ?? ""));
68
- return strings[1];
66
+ return [...args.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1] ?? ""));
67
+ }
68
+ /** The bin script a plist runs (the second `ProgramArguments` string), or undefined. */
69
+ export function plistBinPath(content) {
70
+ return plistProgramArguments(content)?.[1];
71
+ }
72
+ /** The node binary a plist runs (the first `ProgramArguments` string), or undefined. */
73
+ export function plistNodePath(content) {
74
+ return plistProgramArguments(content)?.[0];
69
75
  }
70
76
  export const SERVICE_LOG_MAX_BYTES = 10 * 1024 * 1024;
71
77
  /** Keeps `service.log` from growing without bound: past 10 MiB it is copied to `.1` and emptied. */
@@ -27,6 +27,8 @@ export interface ManagerState {
27
27
  export declare function managerState(where: ServiceWhere, run: RunSystem): ManagerState;
28
28
  /** The bin script the installed service file runs, or undefined (no file, or unreadable). */
29
29
  export declare function serviceBinPath(where: ServiceWhere): string | undefined;
30
+ /** The node binary the installed service file runs, or undefined (no file, or unreadable). */
31
+ export declare function serviceNodePath(where: ServiceWhere): string | undefined;
30
32
  /**
31
33
  * The version of the package at `binPath` (`<package>/bin/capybara-device.mjs`), read from its
32
34
  * `package.json`: what a restart of the service would run. Undefined when it cannot be read.
@@ -2,8 +2,8 @@ import { execFileSync } from "node:child_process";
2
2
  import { readFileSync } from "node:fs";
3
3
  import { dirname, join } from "node:path";
4
4
  import { hasLoginService } from "./installed.js";
5
- import { LAUNCHD_LABEL, plistBinPath, plistPath } from "./launchd.js";
6
- import { SYSTEMD_UNIT, unitBinPath, unitPath } from "./systemd.js";
5
+ import { LAUNCHD_LABEL, plistBinPath, plistNodePath, plistPath } from "./launchd.js";
6
+ import { SYSTEMD_UNIT, unitBinPath, unitNodePath, unitPath } from "./systemd.js";
7
7
  export function defaultRunSystem(cmd, args) {
8
8
  return execFileSync(cmd, args, { stdio: "pipe", encoding: "utf8" });
9
9
  }
@@ -62,6 +62,20 @@ export function serviceBinPath(where) {
62
62
  return undefined;
63
63
  }
64
64
  }
65
+ /** The node binary the installed service file runs, or undefined (no file, or unreadable). */
66
+ export function serviceNodePath(where) {
67
+ if (!hasLoginService(where.home, where.platform))
68
+ return undefined;
69
+ try {
70
+ if (where.platform === "darwin") {
71
+ return plistNodePath(readFileSync(plistPath(where.home), "utf8"));
72
+ }
73
+ return unitNodePath(readFileSync(unitPath(where.home), "utf8"));
74
+ }
75
+ catch {
76
+ return undefined;
77
+ }
78
+ }
65
79
  /**
66
80
  * The version of the package at `binPath` (`<package>/bin/capybara-device.mjs`), read from its
67
81
  * `package.json`: what a restart of the service would run. Undefined when it cannot be read.
@@ -5,3 +5,5 @@ export declare function unitPath(home: string): string;
5
5
  export declare function unitContent(spec: ServiceSpec): string;
6
6
  /** The bin script a unit runs (the second word of `ExecStart`), or undefined. */
7
7
  export declare function unitBinPath(content: string): string | undefined;
8
+ /** The node binary a unit runs (the first `ExecStart` word), or undefined. */
9
+ export declare function unitNodePath(content: string): string | undefined;
@@ -28,9 +28,15 @@ WantedBy=default.target
28
28
  }
29
29
  /** The bin script a unit runs (the second word of `ExecStart`), or undefined. */
30
30
  export function unitBinPath(content) {
31
+ return unitExecWords(content)?.[1];
32
+ }
33
+ /** The node binary a unit runs (the first `ExecStart` word), or undefined. */
34
+ export function unitNodePath(content) {
35
+ return unitExecWords(content)?.[0];
36
+ }
37
+ function unitExecWords(content) {
31
38
  const line = /^ExecStart=(.*)$/m.exec(content)?.[1];
32
39
  if (line === undefined)
33
40
  return undefined;
34
- const words = [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? "").replace(/\\(.)/g, "$1").replaceAll("%%", "%"));
35
- return words[1];
41
+ return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => (m[1] ?? "").replace(/\\(.)/g, "$1").replaceAll("%%", "%"));
36
42
  }
@@ -1,4 +1,5 @@
1
1
  import { type Connection } from "./client.js";
2
+ import type { LiveStatus } from "./control/protocol.js";
2
3
  import { type StagedDevice } from "./staged-device.js";
3
4
  import type { Credential } from "./state.js";
4
5
  /** Printed when the machine credential changed under a running program. */
@@ -25,6 +26,14 @@ export interface StagedConnectOptions {
25
26
  * with exit 1, so the service manager (or the owner) starts it again with the new credential.
26
27
  */
27
28
  credential?: () => Credential | undefined;
29
+ /**
30
+ * The connection state for the local control socket: online once a socket opened, offline with
31
+ * the reason after it failed or closed, draining (for good) once a drain began.
32
+ */
33
+ onState?: (s: {
34
+ connection: LiveStatus["connection"];
35
+ reason?: string;
36
+ }) => void;
28
37
  }
29
38
  /**
30
39
  * Connects a staged (protocol 3) program and serves it until told to stop (permission activation
@@ -46,6 +46,17 @@ export function connectStaged(device, opts = {}) {
46
46
  let exitAfterStop;
47
47
  let session;
48
48
  let state = device.states.for(started);
49
+ /** Reports the connection state; a drain is final, so later socket changes are not reported. */
50
+ const setState = (connection, reason) => {
51
+ if (draining && connection !== "draining")
52
+ return;
53
+ try {
54
+ opts.onState?.({ connection, ...(reason !== undefined && { reason }) });
55
+ }
56
+ catch {
57
+ // an observer never affects the connection
58
+ }
59
+ };
49
60
  const endSession = (end) => {
50
61
  const s = session;
51
62
  session = undefined;
@@ -146,6 +157,8 @@ export function connectStaged(device, opts = {}) {
146
157
  let policyCheck;
147
158
  let opened = false;
148
159
  let answered = false;
160
+ // why this socket failed, for the offline state its close reports
161
+ let failure;
149
162
  const heard = () => {
150
163
  clearTimeout(liveness);
151
164
  liveness = setTimeout(() => sock.terminate(), livenessMs);
@@ -154,6 +167,7 @@ export function connectStaged(device, opts = {}) {
154
167
  sock.on("message", heard);
155
168
  sock.on("open", () => {
156
169
  opened = true;
170
+ setState("online");
157
171
  heard();
158
172
  stable = setTimeout(() => {
159
173
  attempt = 0;
@@ -214,14 +228,17 @@ export function connectStaged(device, opts = {}) {
214
228
  }
215
229
  res.resume();
216
230
  sock.terminate();
231
+ failure = `Connecting to ${cred.connectUrl} failed: HTTP ${status}.`;
217
232
  if (status === 401)
218
233
  return endSession({ exit: 0, message: DISCONNECTED_MESSAGE });
219
234
  reportFailure(`Connecting to ${cred.connectUrl} failed: HTTP ${status}.`);
220
235
  endSession({ reconnect: true });
221
236
  });
222
237
  sock.on("error", (e) => {
223
- if (!opened && !answered && !stopping)
224
- reportFailure(`Cannot reach ${cred.connectUrl}: ${e.message}.`);
238
+ if (!opened && !answered && !stopping) {
239
+ failure = `Cannot reach ${cred.connectUrl}: ${e.message}.`;
240
+ reportFailure(failure);
241
+ }
225
242
  });
226
243
  sock.on("close", (code, reason) => {
227
244
  clearTimeout(liveness);
@@ -229,6 +246,10 @@ export function connectStaged(device, opts = {}) {
229
246
  clearInterval(policyCheck);
230
247
  if (ws === sock)
231
248
  ws = undefined;
249
+ if (!stopping && !exitAfterStop) {
250
+ const why = reason.toString("utf8");
251
+ setState("offline", failure ?? `The connection closed (${code}${why === "" ? "" : ` ${why}`}).`);
252
+ }
232
253
  if (exitAfterStop)
233
254
  return endSession(exitAfterStop);
234
255
  if (code === 4002)
@@ -281,6 +302,7 @@ export function connectStaged(device, opts = {}) {
281
302
  drain() {
282
303
  if (draining)
283
304
  return;
305
+ setState("draining");
284
306
  draining = true;
285
307
  // no new admission at once; ends when the requests and the owned work settled
286
308
  void drainStagedSession(state, device.drainTarget(), new AbortController().signal)
@@ -1,6 +1,7 @@
1
1
  import { homedir } from "node:os";
2
2
  import { resolve } from "node:path";
3
3
  import { DEFAULT_SANDBOX_ROOTS, FileSystemGoneError, SandboxPermissionUnsupportedError, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
4
+ import { RunningOperations } from "./activity.js";
4
5
  import { CommandLog } from "./command-log.js";
5
6
  import { credentialIdentity, InstanceBinder } from "./exec/instance-binding.js";
6
7
  import { readStrictOwnerCeiling } from "./exec/operation-types.js";
@@ -98,6 +99,8 @@ export function createStagedDevice(o) {
98
99
  const { verifyInstalledRuntime } = await import("./exec/runtime-manifest.js");
99
100
  return verifyInstalledRuntime(environment, undefined, { stageIn: stateDir });
100
101
  };
102
+ // the operations executing now, for the local control socket
103
+ const running = new RunningOperations();
101
104
  const createBackend = async (_generation, binding) => {
102
105
  const runtimeHash = binding.runtimeIdentity.runtimeHash;
103
106
  const options = {
@@ -109,6 +112,8 @@ export function createStagedDevice(o) {
109
112
  // restricted launches run only the sealed runtime this binding attested
110
113
  runtimeHash,
111
114
  readOwnerCeiling,
115
+ // a background task stays in the running operations until its worker is gone
116
+ onOperationEnded: (operationId) => running.endOperation(operationId),
112
117
  };
113
118
  const deps = o.backendDependencies ?? {};
114
119
  if (mode === "docker") {
@@ -149,6 +154,7 @@ export function createStagedDevice(o) {
149
154
  store: policy,
150
155
  // operations and policy changes are recorded in the owner's local command log
151
156
  log: new CommandLog(stateDir),
157
+ running,
152
158
  report: () => issueOwnerReport({ stateDir, deviceId: cred.deviceId, dir: cred.dir, home }),
153
159
  reconcile: async (signal) => {
154
160
  await binder.current()?.backend.reconcileOwnerCeiling(signal);
package/dist/state.d.ts CHANGED
@@ -32,6 +32,13 @@ export interface OwnerCeilingPolicy {
32
32
  }
33
33
  /** The persisted local policy format (`version: 2`). */
34
34
  export declare const POLICY_VERSION = 2;
35
+ /**
36
+ * When the program keeps this computer awake: never, only while operations run, or the whole
37
+ * time it is connected to the deployment.
38
+ */
39
+ export type KeepAwakeMode = "off" | "while-busy" | "connected";
40
+ export declare const KEEP_AWAKE_MODES: readonly KeepAwakeMode[];
41
+ export declare const isKeepAwakeMode: (v: unknown) => v is KeepAwakeMode;
35
42
  /** Local limits the person sets for this machine. */
36
43
  export interface Policy {
37
44
  allowedDomains: string[];
@@ -40,6 +47,8 @@ export interface Policy {
40
47
  memoryMb: number | null;
41
48
  /** The owner ceiling. The kernel's `limits.mode` and the org ceiling only narrow it. */
42
49
  ownerCeiling: OwnerCeilingPolicy;
50
+ /** Keep-awake (spec §9.7); absent in a file means the default. */
51
+ keepAwake: KeepAwakeMode;
43
52
  }
44
53
  /** The exact old `mode: auto` ceiling. */
45
54
  export declare const FULL_OWNER_CEILING: OwnerCeilingPolicy;
package/dist/state.js CHANGED
@@ -4,6 +4,8 @@ import { homedir } from "node:os";
4
4
  import { join } from "node:path";
5
5
  /** The persisted local policy format (`version: 2`). */
6
6
  export const POLICY_VERSION = 2;
7
+ export const KEEP_AWAKE_MODES = ["off", "while-busy", "connected"];
8
+ export const isKeepAwakeMode = (v) => typeof v === "string" && KEEP_AWAKE_MODES.includes(v);
7
9
  /** The exact old `mode: auto` ceiling. */
8
10
  export const FULL_OWNER_CEILING = Object.freeze({
9
11
  fullAccess: true,
@@ -35,6 +37,7 @@ export const DEFAULT_POLICY = {
35
37
  // A new setup's owner ceiling (B-14): no Full access, restricted work in the workspace. An old
36
38
  // policy file still converts exactly from its `mode` (convertPolicyFile).
37
39
  ownerCeiling: { ...SANDBOX_OWNER_CEILING },
40
+ keepAwake: "while-busy",
38
41
  };
39
42
  /** `$XDG_CONFIG_HOME/capybara-device`, or `~/.config/capybara-device`. */
40
43
  export function stateDir(env = process.env, home = homedir()) {
@@ -204,7 +207,11 @@ export function readPolicyFile(dir) {
204
207
  cpu: o.cpu === undefined ? null : o.cpu,
205
208
  memoryMb: o.memoryMb === undefined ? null : o.memoryMb,
206
209
  ownerCeiling,
210
+ keepAwake: o.keepAwake === undefined ? DEFAULT_POLICY.keepAwake : o.keepAwake,
207
211
  };
212
+ if (!isKeepAwakeMode(policy.keepAwake)) {
213
+ throw bad("keepAwake", '"off", "while-busy" or "connected"');
214
+ }
208
215
  if (!isStringList(policy.allowedDomains))
209
216
  throw bad("allowedDomains", "a list of strings");
210
217
  if (!isStringList(policy.allowCredentials))
@@ -223,7 +230,7 @@ export function readPolicyFile(dir) {
223
230
  /** Writes policy.json atomically (owner-only); `extra` are unknown keys to keep (never legacy ones). */
224
231
  export function writePolicy(dir, policy, extra = {}) {
225
232
  const kept = Object.fromEntries(Object.entries(extra).filter(([k]) => !LEGACY_POLICY_KEYS.includes(k)));
226
- const { allowedDomains, allowCredentials, cpu, memoryMb, ownerCeiling } = policy;
233
+ const { allowedDomains, allowCredentials, cpu, memoryMb, ownerCeiling, keepAwake } = policy;
227
234
  const body = {
228
235
  ...kept,
229
236
  version: POLICY_VERSION,
@@ -235,6 +242,7 @@ export function writePolicy(dir, policy, extra = {}) {
235
242
  fullAccess: ownerCeiling.fullAccess,
236
243
  restrictedProjectReach: ownerCeiling.restrictedProjectReach,
237
244
  },
245
+ keepAwake,
238
246
  };
239
247
  writePrivate(policyPath(dir), `${JSON.stringify(body, null, 2)}\n`);
240
248
  }
package/dist/wake.d.ts ADDED
@@ -0,0 +1,23 @@
1
+ /** Wall-clock time that passed beyond the monotonic clock's before a check counts as a wake. */
2
+ export declare const WAKE_THRESHOLD_MS = 30000;
3
+ export interface WakeDetectorOptions {
4
+ /** Wall clock, ms since the epoch (default `Date.now`). */
5
+ now?: () => number;
6
+ /** A clock that stops while the computer sleeps (default `performance.now`). */
7
+ monotonic?: () => number;
8
+ thresholdMs?: number;
9
+ }
10
+ /**
11
+ * Notices the computer woke from sleep: the monotonic clock does not advance while it sleeps, the
12
+ * wall clock does, so a wall-clock advance well beyond the monotonic one between two checks is a
13
+ * wake. Call {@link check} regularly; it answers the wake time (ISO 8601) once per wake.
14
+ */
15
+ export declare class WakeDetector {
16
+ private readonly now;
17
+ private readonly monotonic;
18
+ private readonly thresholdMs;
19
+ private lastWall;
20
+ private lastMono;
21
+ constructor(o?: WakeDetectorOptions);
22
+ check(): string | undefined;
23
+ }
package/dist/wake.js ADDED
@@ -0,0 +1,29 @@
1
+ /** Wall-clock time that passed beyond the monotonic clock's before a check counts as a wake. */
2
+ export const WAKE_THRESHOLD_MS = 30_000;
3
+ /**
4
+ * Notices the computer woke from sleep: the monotonic clock does not advance while it sleeps, the
5
+ * wall clock does, so a wall-clock advance well beyond the monotonic one between two checks is a
6
+ * wake. Call {@link check} regularly; it answers the wake time (ISO 8601) once per wake.
7
+ */
8
+ export class WakeDetector {
9
+ now;
10
+ monotonic;
11
+ thresholdMs;
12
+ lastWall;
13
+ lastMono;
14
+ constructor(o = {}) {
15
+ this.now = o.now ?? Date.now;
16
+ this.monotonic = o.monotonic ?? (() => performance.now());
17
+ this.thresholdMs = o.thresholdMs ?? WAKE_THRESHOLD_MS;
18
+ this.lastWall = this.now();
19
+ this.lastMono = this.monotonic();
20
+ }
21
+ check() {
22
+ const wall = this.now();
23
+ const mono = this.monotonic();
24
+ const slept = wall - this.lastWall - (mono - this.lastMono);
25
+ this.lastWall = wall;
26
+ this.lastMono = mono;
27
+ return slept > this.thresholdMs ? new Date(wall).toISOString() : undefined;
28
+ }
29
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/device",
3
- "version": "0.1.0-rc.16",
3
+ "version": "0.1.0-rc.18",
4
4
  "description": "capybara-device: connects a laptop or server to a Capybara deployment as a device",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -41,7 +41,7 @@
41
41
  "@types/ws": "^8.5.13",
42
42
  "esbuild": "0.28.2",
43
43
  "ws": "^8.18.0",
44
- "@capybara-hq/plugin-sdk": "^0.1.0-rc.36"
44
+ "@capybara-hq/plugin-sdk": "^0.1.0-rc.38"
45
45
  },
46
46
  "scripts": {
47
47
  "build": "tsc -b"