@capybara-hq/device 0.1.0-rc.17 → 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 (58) 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 +1 -0
  25. package/dist/exec/operation-supervisor.d.ts +6 -0
  26. package/dist/exec/operation-supervisor.js +10 -0
  27. package/dist/index.d.ts +2 -0
  28. package/dist/index.js +1 -0
  29. package/dist/keep-awake.d.ts +39 -0
  30. package/dist/keep-awake.js +104 -0
  31. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -1
  32. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -1
  33. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
  34. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
  35. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
  36. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
  37. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
  38. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
  39. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
  40. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
  41. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  42. package/dist/runtime-manifest.json +1 -1
  43. package/dist/server-ops.d.ts +3 -0
  44. package/dist/server-ops.js +33 -0
  45. package/dist/service/launchd.d.ts +2 -0
  46. package/dist/service/launchd.js +10 -4
  47. package/dist/service/manager.d.ts +2 -0
  48. package/dist/service/manager.js +16 -2
  49. package/dist/service/systemd.d.ts +2 -0
  50. package/dist/service/systemd.js +8 -2
  51. package/dist/staged-connect.d.ts +9 -0
  52. package/dist/staged-connect.js +24 -2
  53. package/dist/staged-device.js +6 -0
  54. package/dist/state.d.ts +9 -0
  55. package/dist/state.js +9 -1
  56. package/dist/wake.d.ts +23 -0
  57. package/dist/wake.js +29 -0
  58. package/package.json +2 -2
@@ -0,0 +1,254 @@
1
+ import { chmodSync, lstatSync, statSync, unlinkSync } from "node:fs";
2
+ import { createConnection, createServer } from "node:net";
3
+ import { CONTROL_LINE_MAX_BYTES, CONTROL_OPS, CONTROL_PATH_MAX_BYTES, CONTROL_WRITE_MAX_BYTES, controlSocketPath, } from "./protocol.js";
4
+ /** How long the check for a live socket at the path waits for a connection. */
5
+ const PROBE_TIMEOUT_MS = 1000;
6
+ /** Owner-only peers: a handful of connections is plenty (the desktop app, a `status`). */
7
+ const MAX_CONNECTIONS = 32;
8
+ const mode = (st) => `0${(st.mode & 0o777).toString(8)}`;
9
+ /**
10
+ * Why no control socket can be made for this state directory, from what is visible without
11
+ * binding: a path over {@link CONTROL_PATH_MAX_BYTES}, or a state directory that is missing, not
12
+ * the user's or open to other users (the same owner and mode rule the credential file follows).
13
+ * Undefined when nothing is in the way. `status` uses it to explain a runner that does not answer.
14
+ */
15
+ export function controlUnavailableReason(stateDir) {
16
+ const path = controlSocketPath(stateDir);
17
+ const bytes = Buffer.byteLength(path);
18
+ if (bytes > CONTROL_PATH_MAX_BYTES) {
19
+ return (`the control socket path ${path} is ${bytes} bytes, longer than the ` +
20
+ `${CONTROL_PATH_MAX_BYTES} bytes a unix socket path may have; use a shorter XDG_CONFIG_HOME`);
21
+ }
22
+ let st;
23
+ try {
24
+ st = statSync(stateDir);
25
+ }
26
+ catch (e) {
27
+ return `the state directory ${stateDir} cannot be read (${e.message})`;
28
+ }
29
+ if (!st.isDirectory())
30
+ return `the state directory ${stateDir} is not a directory`;
31
+ const uid = process.getuid?.();
32
+ if (uid !== undefined && st.uid !== uid) {
33
+ return `the state directory ${stateDir} belongs to another user (uid ${st.uid})`;
34
+ }
35
+ if ((st.mode & 0o077) !== 0) {
36
+ return (`the state directory ${stateDir} has mode ${mode(st)}, open to other users; ` +
37
+ `run chmod 700 ${stateDir}`);
38
+ }
39
+ return undefined;
40
+ }
41
+ /** Whether something answers on the socket at `path`: "live", "stale" (nothing listens) or why not. */
42
+ function probe(path) {
43
+ return new Promise((resolve) => {
44
+ const sock = createConnection(path);
45
+ const done = (r) => {
46
+ clearTimeout(timer);
47
+ sock.destroy();
48
+ resolve(r);
49
+ };
50
+ const timer = setTimeout(() => done({ error: "it did not answer in time" }), PROBE_TIMEOUT_MS);
51
+ sock.once("connect", () => done("live"));
52
+ sock.once("error", (e) => done(e.code === "ECONNREFUSED" || e.code === "ENOENT" ? "stale" : { error: e.message }));
53
+ });
54
+ }
55
+ /**
56
+ * Clears the way for a socket at `path`: nothing there, or a stale socket of this user (nothing
57
+ * listens) that is removed. A live socket, a file that is not a socket or one of another user is
58
+ * never touched. Answers why not, or undefined when the path is free.
59
+ */
60
+ async function clearPath(path) {
61
+ let st;
62
+ try {
63
+ st = lstatSync(path);
64
+ }
65
+ catch {
66
+ return undefined;
67
+ }
68
+ if (!st.isSocket())
69
+ return `${path} exists and is not a socket; it was left alone`;
70
+ const uid = process.getuid?.();
71
+ if (uid !== undefined && st.uid !== uid)
72
+ return `${path} belongs to another user`;
73
+ const found = await probe(path);
74
+ if (found === "live")
75
+ return `another capybara-device already answers on ${path}`;
76
+ if (found !== "stale")
77
+ return `${path} cannot be checked (${found.error})`;
78
+ try {
79
+ // only the socket judged stale: a file replaced meanwhile is left alone
80
+ const now = lstatSync(path);
81
+ if (now.ino === st.ino && now.dev === st.dev)
82
+ unlinkSync(path);
83
+ }
84
+ catch {
85
+ // gone already
86
+ }
87
+ return undefined;
88
+ }
89
+ /** Binds `path` with the umask closed to group and others, so the socket is never wider than 0600. */
90
+ function listen(server, path) {
91
+ return new Promise((resolve, reject) => {
92
+ server.once("error", reject);
93
+ // the bind of a unix socket happens inside listen(), synchronously: the umask is restored
94
+ // right after it, never left closed across an await
95
+ const umask = process.umask(0o077);
96
+ try {
97
+ server.listen(path, () => {
98
+ server.off("error", reject);
99
+ resolve();
100
+ });
101
+ }
102
+ finally {
103
+ process.umask(umask);
104
+ }
105
+ });
106
+ }
107
+ /**
108
+ * Starts the control socket at `<stateDir>/control.sock` (mode 0600). Answers `{ unavailable }`
109
+ * with the reason instead when the socket cannot be made safely; the runner keeps serving then.
110
+ */
111
+ export async function startControlServer(opts) {
112
+ const path = controlSocketPath(opts.stateDir);
113
+ const blocked = controlUnavailableReason(opts.stateDir) ?? (await clearPath(path));
114
+ if (blocked !== undefined)
115
+ return { unavailable: blocked };
116
+ const sockets = new Set();
117
+ const subscribers = new Set();
118
+ const send = (sock, line) => {
119
+ if (sock.destroyed || !sock.writable)
120
+ return;
121
+ sock.write(`${JSON.stringify(line)}\n`);
122
+ // a peer that stopped reading (a subscriber above all) never pins memory here
123
+ if (sock.writableLength > CONTROL_WRITE_MAX_BYTES)
124
+ sock.destroy();
125
+ };
126
+ const failure = (id, code, message) => ({
127
+ id,
128
+ ok: false,
129
+ error: { code, message },
130
+ });
131
+ const fail = (sock, id, code, message) => send(sock, failure(id, code, message));
132
+ /** The answer to one request line; a subscribe also adds the connection to the subscribers. */
133
+ const respond = (sock, line) => {
134
+ let req;
135
+ try {
136
+ req = JSON.parse(line);
137
+ }
138
+ catch {
139
+ return failure(0, "bad_request", "The line is not JSON");
140
+ }
141
+ const r = (req !== null && typeof req === "object" ? req : {});
142
+ const id = typeof r.id === "number" && Number.isSafeInteger(r.id) && r.id > 0 ? r.id : 0;
143
+ if (id === 0)
144
+ return failure(0, "bad_request", 'The request needs "id", a positive integer');
145
+ if (typeof r.op !== "string" || !CONTROL_OPS.includes(r.op)) {
146
+ return failure(id, "unknown_op", `Unknown op; one of ${CONTROL_OPS.join(", ")}`);
147
+ }
148
+ const op = r.op;
149
+ try {
150
+ if (op === "status")
151
+ return { id, ok: true, result: opts.status() };
152
+ if (op === "running")
153
+ return { id, ok: true, result: opts.running() };
154
+ if (op === "subscribe") {
155
+ subscribers.add(sock);
156
+ return { id, ok: true, result: opts.status() };
157
+ }
158
+ if (op === "drain")
159
+ opts.drain();
160
+ else
161
+ opts.stop();
162
+ return { id, ok: true, result: null };
163
+ }
164
+ catch (e) {
165
+ return failure(id, "failed", e.message);
166
+ }
167
+ };
168
+ const answer = (sock, line) => send(sock, respond(sock, line));
169
+ const server = createServer((sock) => {
170
+ sockets.add(sock);
171
+ sock.setEncoding("utf8");
172
+ let buf = "";
173
+ let refused = false;
174
+ const overLong = () => {
175
+ refused = true;
176
+ buf = "";
177
+ fail(sock, 0, "bad_request", `A line is longer than ${CONTROL_LINE_MAX_BYTES} bytes`);
178
+ sock.end();
179
+ };
180
+ // one listener per connection: lines are answered in order
181
+ sock.on("data", (chunk) => {
182
+ if (refused)
183
+ return;
184
+ buf += chunk;
185
+ for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
186
+ const line = buf.slice(0, i);
187
+ buf = buf.slice(i + 1);
188
+ if (Buffer.byteLength(line) > CONTROL_LINE_MAX_BYTES)
189
+ return overLong();
190
+ if (line.trim() !== "")
191
+ answer(sock, line);
192
+ }
193
+ if (Buffer.byteLength(buf) > CONTROL_LINE_MAX_BYTES)
194
+ overLong();
195
+ });
196
+ sock.on("error", () => {
197
+ // a peer that went away: nothing to answer
198
+ });
199
+ sock.on("close", () => {
200
+ sockets.delete(sock);
201
+ subscribers.delete(sock);
202
+ });
203
+ });
204
+ server.maxConnections = MAX_CONNECTIONS;
205
+ try {
206
+ await listen(server, path);
207
+ }
208
+ catch (e) {
209
+ const err = e;
210
+ return {
211
+ unavailable: err.code === "EADDRINUSE"
212
+ ? `another capybara-device already answers on ${path}`
213
+ : `cannot listen on ${path} (${err.message})`,
214
+ };
215
+ }
216
+ let bound;
217
+ try {
218
+ chmodSync(path, 0o600);
219
+ bound = lstatSync(path);
220
+ }
221
+ catch (e) {
222
+ await new Promise((r) => server.close(() => r()));
223
+ return { unavailable: `cannot secure ${path} (${e.message})` };
224
+ }
225
+ server.on("error", () => {
226
+ // a failure after listening affects new connections only; the runner keeps serving
227
+ });
228
+ let closed;
229
+ return {
230
+ publish(s) {
231
+ for (const sock of subscribers)
232
+ send(sock, { event: "status", status: s });
233
+ },
234
+ close() {
235
+ closed ??= new Promise((resolve) => {
236
+ for (const sock of sockets)
237
+ sock.destroy();
238
+ server.close(() => {
239
+ try {
240
+ // only the socket this server bound: one another runner bound meanwhile stays
241
+ const now = lstatSync(path);
242
+ if (now.ino === bound.ino && now.dev === bound.dev)
243
+ unlinkSync(path);
244
+ }
245
+ catch {
246
+ // removed already (the listener's close unlinks it)
247
+ }
248
+ resolve();
249
+ });
250
+ });
251
+ return closed;
252
+ },
253
+ };
254
+ }
@@ -14,6 +14,11 @@ export interface MacOperationBackendOptions {
14
14
  */
15
15
  runtimeHash?: string;
16
16
  readOwnerCeiling: () => Promise<DeviceOwnerCeiling>;
17
+ /**
18
+ * Called when an operation's worker is gone (completed, killed, failed to launch): a background
19
+ * task long after its start answered. Feeds the control socket's running operations.
20
+ */
21
+ onOperationEnded?: (operationId: string) => void;
17
22
  }
18
23
  export type MacOperationBackend = Required<Pick<SandboxProvider, "permissionSupport" | "operation" | "browse" | "prepare" | "revokeOperation" | "background">> & {
19
24
  forExecution(authority: LocalExecAuthority): Pick<MacOperationBackend, "operation" | "background">;
@@ -77,6 +77,7 @@ export async function createLocalOperationBackend(options, dependencies, host) {
77
77
  ...(dependencies.now ? { now: dependencies.now } : {}),
78
78
  ...(host.startWorker ? { start: host.startWorker } : {}),
79
79
  ...(host.reapOrphan ? { reapOrphan: host.reapOrphan } : {}),
80
+ ...(options.onOperationEnded ? { onLiveEnded: options.onOperationEnded } : {}),
80
81
  onLiveChanged: (live) => {
81
82
  if (live && !stopWatch) {
82
83
  if (dependencies.watch)
@@ -47,6 +47,11 @@ export interface SupervisorOptions {
47
47
  now?: () => number;
48
48
  start?: (request: MacWorkerRequest, signal: AbortSignal) => Promise<MacWorkerHandle>;
49
49
  onLiveChanged?: (live: boolean) => void;
50
+ /**
51
+ * Called once each live worker (an exec, or a background task long after its start answered)
52
+ * is gone: completed, killed or failed to launch. Never throws into the supervisor.
53
+ */
54
+ onLiveEnded?: (operationId: string) => void;
50
55
  pythonPath?: string;
51
56
  outputBarrier?: (name: string) => Promise<void>;
52
57
  beforePersist?: () => void;
@@ -140,6 +145,7 @@ export declare class MacOperationSupervisor {
140
145
  * The owner watcher runs while anything is owned: a live worker, a faulted collector's owner or
141
146
  * an exact cancellation still settling (an idle socket or a disconnect does not end it).
142
147
  */
148
+ private liveEnded;
143
149
  private notifyOwned;
144
150
  ownership(): SupervisorOwnership;
145
151
  /** Starts a graceful drain: no new admission from now on, for the rest of this process. */
@@ -628,6 +628,7 @@ export class MacOperationSupervisor {
628
628
  await spool?.close();
629
629
  signal.removeEventListener("abort", abort);
630
630
  this.live.delete(entry.ref.operationId);
631
+ this.liveEnded(entry.ref.operationId);
631
632
  this.notifyOwned();
632
633
  })
633
634
  .catch((error) => {
@@ -652,6 +653,7 @@ export class MacOperationSupervisor {
652
653
  });
653
654
  reject(error);
654
655
  this.live.delete(entry.ref.operationId);
656
+ this.liveEnded(entry.ref.operationId);
655
657
  this.notifyOwned();
656
658
  throw error;
657
659
  }
@@ -920,6 +922,14 @@ export class MacOperationSupervisor {
920
922
  * The owner watcher runs while anything is owned: a live worker, a faulted collector's owner or
921
923
  * an exact cancellation still settling (an idle socket or a disconnect does not end it).
922
924
  */
925
+ liveEnded(operationId) {
926
+ try {
927
+ this.options.onLiveEnded?.(operationId);
928
+ }
929
+ catch {
930
+ // an observer never affects the supervisor
931
+ }
932
+ }
923
933
  notifyOwned() {
924
934
  this.options.onLiveChanged?.(this.live.size > 0 || this.faultOwners.size > 0 || this.cancellations.size > 0);
925
935
  }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ export type { RunningOperation } from "./activity.js";
1
2
  export { type Command, parseCommandLine } from "./args.js";
2
3
  export { runCli } from "./cli.js";
4
+ export { type ControlEvent, type ControlRequest, type ControlResponse, controlSocketPath, type LiveStatus, } from "./control/protocol.js";
3
5
  export { type Credential, type Policy, type SandboxMode, stateDir } from "./state.js";
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
1
  export { parseCommandLine } from "./args.js";
2
2
  export { runCli } from "./cli.js";
3
+ export { controlSocketPath, } from "./control/protocol.js";
3
4
  export { stateDir } from "./state.js";
@@ -0,0 +1,39 @@
1
+ import { spawn as nodeSpawn } from "node:child_process";
2
+ import type { KeepAwakeMode } from "./state.js";
3
+ /** The assertion holders (decision 4): macOS ties it to the runner's pid, Linux to `sleep`. */
4
+ export declare function holderCommand(platform: NodeJS.Platform, pid: number): {
5
+ command: string;
6
+ args: string[];
7
+ } | undefined;
8
+ export interface KeepAwakeOptions {
9
+ platform: NodeJS.Platform;
10
+ /** The runner's pid (macOS `caffeinate -w` ends the assertion when it exits). */
11
+ pid: number;
12
+ spawn?: typeof nodeSpawn;
13
+ }
14
+ /**
15
+ * Holds an OS idle-sleep assertion through a child process while the mode asks for it: the whole
16
+ * time connected (`connected`), or while operations run (`while-busy`). A holder that cannot start
17
+ * or ends early is reported as `unavailable` with the reason; nothing pretends it is held.
18
+ */
19
+ export declare class KeepAwake {
20
+ private readonly o;
21
+ private readonly spawnFn;
22
+ private holder;
23
+ private unavailable;
24
+ private mode;
25
+ constructor(o: KeepAwakeOptions);
26
+ update(i: {
27
+ mode: KeepAwakeMode;
28
+ connected: boolean;
29
+ busy: boolean;
30
+ }): void;
31
+ state(): {
32
+ mode: KeepAwakeMode;
33
+ held: boolean;
34
+ unavailable?: string;
35
+ };
36
+ dispose(): void;
37
+ private acquire;
38
+ private release;
39
+ }
@@ -0,0 +1,104 @@
1
+ import { spawn as nodeSpawn } from "node:child_process";
2
+ /** The assertion holders (decision 4): macOS ties it to the runner's pid, Linux to `sleep`. */
3
+ export function holderCommand(platform, pid) {
4
+ if (platform === "darwin")
5
+ return { command: "/usr/bin/caffeinate", args: ["-i", "-w", String(pid)] };
6
+ if (platform === "linux") {
7
+ return {
8
+ command: "systemd-inhibit",
9
+ args: [
10
+ "--what=idle:sleep",
11
+ "--mode=block",
12
+ "--who=capybara-device",
13
+ "--why=Capybara device is serving",
14
+ "sleep",
15
+ "infinity",
16
+ ],
17
+ };
18
+ }
19
+ return undefined;
20
+ }
21
+ /**
22
+ * Holds an OS idle-sleep assertion through a child process while the mode asks for it: the whole
23
+ * time connected (`connected`), or while operations run (`while-busy`). A holder that cannot start
24
+ * or ends early is reported as `unavailable` with the reason; nothing pretends it is held.
25
+ */
26
+ export class KeepAwake {
27
+ o;
28
+ spawnFn;
29
+ holder;
30
+ unavailable;
31
+ mode = "off";
32
+ constructor(o) {
33
+ this.o = o;
34
+ this.spawnFn = o.spawn ?? nodeSpawn;
35
+ }
36
+ update(i) {
37
+ // a new mode is a new request: it may try again after a failure
38
+ if (i.mode !== this.mode)
39
+ this.unavailable = undefined;
40
+ this.mode = i.mode;
41
+ const want = (i.mode === "connected" && i.connected) || (i.mode === "while-busy" && i.busy);
42
+ if (!want) {
43
+ this.release();
44
+ // a failure is about an attempt; once nothing is wanted there is nothing to report
45
+ this.unavailable = undefined;
46
+ return;
47
+ }
48
+ if (this.holder !== undefined)
49
+ return;
50
+ // a holder that failed is not started again (every refresh would spawn and fail again, and
51
+ // the status would flap) until nothing is wanted for a while or the mode changes
52
+ if (this.unavailable !== undefined)
53
+ return;
54
+ this.acquire();
55
+ }
56
+ state() {
57
+ return {
58
+ mode: this.mode,
59
+ held: this.holder !== undefined,
60
+ ...(this.unavailable !== undefined && { unavailable: this.unavailable }),
61
+ };
62
+ }
63
+ dispose() {
64
+ this.release();
65
+ }
66
+ acquire() {
67
+ const cmd = holderCommand(this.o.platform, this.o.pid);
68
+ if (cmd === undefined) {
69
+ this.unavailable = `keep-awake is not supported on ${this.o.platform}`;
70
+ return;
71
+ }
72
+ let child;
73
+ try {
74
+ child = this.spawnFn(cmd.command, cmd.args, { stdio: "ignore" });
75
+ }
76
+ catch (e) {
77
+ this.unavailable = `cannot start ${cmd.command}: ${e.message}`;
78
+ return;
79
+ }
80
+ this.unavailable = undefined;
81
+ this.holder = child;
82
+ const gone = (why) => {
83
+ // only this holder: a newer one is not affected by an old one's late event
84
+ if (this.holder !== child)
85
+ return;
86
+ this.holder = undefined;
87
+ this.unavailable = why;
88
+ };
89
+ child.on("error", (e) => gone(`cannot run ${cmd.command}: ${e.message}`));
90
+ child.on("exit", (code, signal) => gone(`${cmd.command} ended (${signal ?? `exit ${code}`})`));
91
+ }
92
+ release() {
93
+ const h = this.holder;
94
+ this.holder = undefined;
95
+ if (h === undefined)
96
+ return;
97
+ try {
98
+ h.kill();
99
+ }
100
+ catch {
101
+ // already gone
102
+ }
103
+ }
104
+ }
@@ -1,4 +1,4 @@
1
- export declare const SDK_VERSION = "0.1.0-rc.37";
1
+ export declare const SDK_VERSION = "0.1.0-rc.38";
2
2
  export * from "./agent-template.js";
3
3
  export * from "./bootstrap.js";
4
4
  export * from "./cards.js";
@@ -37,6 +37,8 @@ export * from "./setup-check.js";
37
37
  export * from "./setup-guide.js";
38
38
  export { type ParsedSetupGuide, parseSetupGuide, type SetupGuideCheckLine, type SetupGuideCodeBlock, type SetupGuideParseIssue, type SetupGuideSection, } from "./setup-guide-parse.js";
39
39
  export * from "./setup-guide-render.js";
40
+ export * from "./shell-capabilities.js";
41
+ export * from "./shell-environment.js";
40
42
  export * from "./skill.js";
41
43
  export * from "./skill-invocation.js";
42
44
  export * from "./storage.js";
@@ -1,4 +1,4 @@
1
- export const SDK_VERSION = "0.1.0-rc.37";
1
+ export const SDK_VERSION = "0.1.0-rc.38";
2
2
  export * from "./agent-template.js";
3
3
  export * from "./bootstrap.js";
4
4
  export * from "./cards.js";
@@ -37,6 +37,8 @@ export * from "./setup-check.js";
37
37
  export * from "./setup-guide.js";
38
38
  export { parseSetupGuide, } from "./setup-guide-parse.js";
39
39
  export * from "./setup-guide-render.js";
40
+ export * from "./shell-capabilities.js";
41
+ export * from "./shell-environment.js";
40
42
  export * from "./skill.js";
41
43
  export * from "./skill-invocation.js";
42
44
  export * from "./storage.js";
@@ -2,7 +2,7 @@ import { POLICY_HOOKS } from "./hooks.js";
2
2
  import { HTTP_ACCESS } from "./http-access.js";
3
3
  import { SETUP_CHECK_ID_RE, SETUP_CHECK_LIMITS } from "./setup-check.js";
4
4
  import { UI_ICONS } from "./ui.js";
5
- import { parseSlotRef, uiSlot } from "./ui-slots.js";
5
+ import { isCompactForm, parseSlotRef, uiSlot } from "./ui-slots.js";
6
6
  /** Hook mount points (a closed list, see the overall design 2.4). */
7
7
  export const HOOK_MOUNT_POINTS = [
8
8
  "session.start",
@@ -273,6 +273,8 @@ export function validateUiContributions(ui, permissions) {
273
273
  errs.push(`ui "${id}" kind must be view, embed or component`);
274
274
  return;
275
275
  }
276
+ if (c.compact !== undefined && !isCompactForm(c.compact))
277
+ errs.push(`ui "${id}" compact must be one of kept, drawer, hidden`);
276
278
  if (c.icon !== undefined && !UI_ICONS.includes(c.icon))
277
279
  errs.push(`ui "${id}" icon must be one of ${UI_ICONS.join(", ")}`);
278
280
  // the slot checks describe only the catalog's version: another version is left to
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Desktop shell capabilities (desktop client spec §8): the shapes of the objects a desktop shell
3
+ * puts in `window.capybaraShell.capabilities` under the keys of `SHELL_CAPABILITY_KEYS`. Types and
4
+ * key constants only; `capybara-hq/clients` implements them. A rejected call carries
5
+ * `{ code: ShellCallError }`.
6
+ */
7
+ /** Capability keys, `name@major`; each value is a key of `SHELL_CAPABILITIES`. */
8
+ export declare const SHELL_CAPABILITY_KEYS: {
9
+ readonly device: "device@1";
10
+ readonly notify: "notify@1";
11
+ readonly openExternal: "openExternal@1";
12
+ readonly signIn: "signIn@1";
13
+ };
14
+ export type KeepAwakeMode = "off" | "while-busy" | "connected";
15
+ export type DeviceConnection = "starting" | "online" | "offline" | "draining" | "stopped";
16
+ /** What this machine is to the deployment the shell shows. */
17
+ export type ThisMachineStatus = {
18
+ state: "not_connected";
19
+ } | {
20
+ state: "connected_elsewhere";
21
+ origin: string;
22
+ } | {
23
+ state: "connected";
24
+ deviceId: string;
25
+ orgId: string;
26
+ mode: "os" | "docker";
27
+ connection: DeviceConnection;
28
+ offlineReason?: string;
29
+ serviceInstalled: boolean;
30
+ keepAwake: {
31
+ mode: KeepAwakeMode;
32
+ held: boolean;
33
+ unavailable?: string;
34
+ };
35
+ lastWakeAt?: string;
36
+ };
37
+ /** One operation running on this machine for the deployment. */
38
+ export interface RunningOperationView {
39
+ tag: string;
40
+ conversationId: string | null;
41
+ accountId: string | null;
42
+ isolation: "restricted" | "full";
43
+ startedAt: string;
44
+ }
45
+ /** The `code` of a rejected shell call. */
46
+ export type ShellCallError = "busy" | "no_activation" | "cancelled" | "failed";
47
+ /** `device@1`: connect this machine to the deployment as a device. */
48
+ export interface DeviceCapabilityV1 {
49
+ status(): Promise<ThisMachineStatus>;
50
+ onStatus(listener: (s: ThisMachineStatus) => void): () => void;
51
+ running(): Promise<RunningOperationView[]>;
52
+ connect(input: {
53
+ orgId: string;
54
+ deviceId?: string;
55
+ }): Promise<"connected" | "cancelled">;
56
+ pause(): Promise<void>;
57
+ resume(): Promise<"resumed" | "cancelled">;
58
+ disconnect(): Promise<void>;
59
+ requestCeiling(input: {
60
+ fullAccess: boolean;
61
+ projectReach: "workspace" | "os-user";
62
+ }): Promise<"applied" | "cancelled">;
63
+ setKeepAwake(mode: KeepAwakeMode): Promise<"applied" | "cancelled">;
64
+ }
65
+ /** `notify@1`: a native notification; `path` is the in-app path opened on click. */
66
+ export interface NotifyCapabilityV1 {
67
+ notify(input: {
68
+ title: string;
69
+ body: string;
70
+ path?: string;
71
+ }): Promise<void>;
72
+ }
73
+ /** `openExternal@1`: open a URL in the system browser. */
74
+ export interface OpenExternalCapabilityV1 {
75
+ open(url: string): Promise<void>;
76
+ }
77
+ /** `signIn@1`: sign in through the system browser (desktop client spec §6.5). */
78
+ export interface SignInCapabilityV1 {
79
+ start(): Promise<"signedIn" | "cancelled">;
80
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Desktop shell capabilities (desktop client spec §8): the shapes of the objects a desktop shell
3
+ * puts in `window.capybaraShell.capabilities` under the keys of `SHELL_CAPABILITY_KEYS`. Types and
4
+ * key constants only; `capybara-hq/clients` implements them. A rejected call carries
5
+ * `{ code: ShellCallError }`.
6
+ */
7
+ /** Capability keys, `name@major`; each value is a key of `SHELL_CAPABILITIES`. */
8
+ export const SHELL_CAPABILITY_KEYS = {
9
+ device: "device@1",
10
+ notify: "notify@1",
11
+ openExternal: "openExternal@1",
12
+ signIn: "signIn@1",
13
+ };