@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.
- package/README.md +79 -0
- package/dist/activity.d.ts +31 -0
- package/dist/activity.js +62 -0
- package/dist/args.d.ts +18 -2
- package/dist/args.js +56 -8
- package/dist/cli.js +13 -2
- package/dist/commands/ceiling.js +22 -0
- package/dist/commands/keep-awake.d.ts +19 -0
- package/dist/commands/keep-awake.js +77 -0
- package/dist/commands/login.js +29 -16
- package/dist/commands/service.d.ts +3 -1
- package/dist/commands/service.js +35 -2
- package/dist/commands/start.d.ts +7 -0
- package/dist/commands/start.js +120 -1
- package/dist/commands/status.d.ts +8 -1
- package/dist/commands/status.js +50 -2
- package/dist/control/client.d.ts +12 -0
- package/dist/control/client.js +63 -0
- package/dist/control/protocol.d.ts +58 -0
- package/dist/control/protocol.js +16 -0
- package/dist/control/server.d.ts +28 -0
- package/dist/control/server.js +254 -0
- package/dist/exec/mac-operation-backend.d.ts +5 -0
- package/dist/exec/mac-operation-backend.js +26 -6
- package/dist/exec/native-helper-client.js +10 -2
- package/dist/exec/operation-supervisor.d.ts +30 -1
- package/dist/exec/operation-supervisor.js +60 -2
- package/dist/exec/operation-worker.js +3 -0
- package/dist/exec/transfer-timing.d.ts +16 -0
- package/dist/exec/transfer-timing.js +26 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/keep-awake.d.ts +39 -0
- package/dist/keep-awake.js +104 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +22 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +4 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/runtime-manifest.json +1 -1
- package/dist/server-ops.d.ts +3 -0
- package/dist/server-ops.js +33 -0
- package/dist/service/launchd.d.ts +2 -0
- package/dist/service/launchd.js +10 -4
- package/dist/service/manager.d.ts +2 -0
- package/dist/service/manager.js +16 -2
- package/dist/service/systemd.d.ts +2 -0
- package/dist/service/systemd.js +8 -2
- package/dist/staged-connect.d.ts +9 -0
- package/dist/staged-connect.js +24 -2
- package/dist/staged-device.js +6 -0
- package/dist/state.d.ts +9 -0
- package/dist/state.js +9 -1
- package/dist/wake.d.ts +23 -0
- package/dist/wake.js +29 -0
- package/package.json +2 -2
|
@@ -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
|
+
}
|
|
@@ -756,13 +756,31 @@ function request(o) {
|
|
|
756
756
|
validated.limits = { mode: "sandbox" };
|
|
757
757
|
// Reuse v2's pure value guards; inserted mode is never returned or used as authority.
|
|
758
758
|
parseLegacyDeviceFrame(JSON.stringify({ type: "req", id, op: native, args: validated, deadlineMs }), "kernel");
|
|
759
|
-
if (native === "writeFile" &&
|
|
760
|
-
(typeof a.dataB64 !== "string" ||
|
|
761
|
-
!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(a.dataB64)))
|
|
759
|
+
if (native === "writeFile" && (typeof a.dataB64 !== "string" || !isBase64(a.dataB64)))
|
|
762
760
|
throw new DeviceProtocolError("Invalid base64 payload");
|
|
763
761
|
}
|
|
764
762
|
return freeze({ type: "req", id, op: op, args: a, deadlineMs });
|
|
765
763
|
}
|
|
764
|
+
/**
|
|
765
|
+
* Padded standard base64: whole quartets of `A-Z a-z 0-9 + /`, the last one possibly ending in
|
|
766
|
+
* `=` or `==`. One linear pass: a regex with a repeated group exhausts the engine's backtracking
|
|
767
|
+
* stack on payloads of a few megabytes.
|
|
768
|
+
*/
|
|
769
|
+
function isBase64(value) {
|
|
770
|
+
if (value.length % 4 !== 0)
|
|
771
|
+
return false;
|
|
772
|
+
const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
|
|
773
|
+
for (let i = 0; i < value.length - padding; i++) {
|
|
774
|
+
const c = value.charCodeAt(i);
|
|
775
|
+
if (!((c >= 65 && c <= 90) ||
|
|
776
|
+
(c >= 97 && c <= 122) ||
|
|
777
|
+
(c >= 48 && c <= 57) ||
|
|
778
|
+
c === 43 ||
|
|
779
|
+
c === 47))
|
|
780
|
+
return false;
|
|
781
|
+
}
|
|
782
|
+
return true;
|
|
783
|
+
}
|
|
766
784
|
/** Strictly parses one protocol 3 frame; throws {@link DeviceProtocolError}. */
|
|
767
785
|
export function parseDeviceFrame(raw, from, maxFrameBytes) {
|
|
768
786
|
if (maxFrameBytes !== undefined &&
|
|
@@ -900,7 +918,7 @@ export function parseOperationResult(op, result, request) {
|
|
|
900
918
|
if (integer(o.offset) !== offset ||
|
|
901
919
|
typeof o.dataB64 !== "string" ||
|
|
902
920
|
o.dataB64.length > 87384 ||
|
|
903
|
-
|
|
921
|
+
!isBase64(o.dataB64))
|
|
904
922
|
throw new DeviceProtocolError("Invalid output range or base64");
|
|
905
923
|
const decoded = atob(o.dataB64);
|
|
906
924
|
if (btoa(decoded) !== o.dataB64 ||
|
|
@@ -41,9 +41,10 @@ export interface HookScope {
|
|
|
41
41
|
* `WebFetch` tool, `review` is the command-review classifier's call (`review` purpose, no run
|
|
42
42
|
* step; absent = no classifier), `suggestion` is the prompt suggestion side request after a
|
|
43
43
|
* completed web run (`runId` the run, `step` 0, `attempt` 1; a denial skips it and is recorded only
|
|
44
|
-
* in the audit log)
|
|
44
|
+
* in the audit log), `vision` is the call that reads an image for a model without vision, made by
|
|
45
|
+
* the `Read` tool (also for a pasted image, read by its `file_id`; the `vision` purpose's model).
|
|
45
46
|
*/
|
|
46
|
-
export type ModelCallPurpose = "step" | "compaction" | "title" | "web_fetch" | "review" | "image" | "suggestion";
|
|
47
|
+
export type ModelCallPurpose = "step" | "compaction" | "title" | "web_fetch" | "review" | "image" | "vision" | "suggestion";
|
|
47
48
|
/**
|
|
48
49
|
* What a reported or requested model call was for: the {@link ModelCallPurpose} values, or
|
|
49
50
|
* `embedding` for an embedding call an extension made through `ctx.models` (`usage.report`, and
|
|
@@ -91,7 +92,7 @@ export type HookModelRequest = Omit<ModelRequest, "messages"> & {
|
|
|
91
92
|
* denial skips the title and is recorded only in the audit log), once for each `WebFetch`
|
|
92
93
|
* extraction call (`purpose: "web_fetch"`) and once for each prompt suggestion call
|
|
93
94
|
* (`purpose: "suggestion"`, `step` 0, `attempt` 1; a denial skips the suggestion and is recorded
|
|
94
|
-
* only in the audit log).
|
|
95
|
+
* only in the audit log) and once for each vision call (`purpose: "vision"`).
|
|
95
96
|
* `request` is the request as sent, except that images and documents are placeholders
|
|
96
97
|
* ({@link HookMediaPlaceholder}): no media bytes, no attachment ids.
|
|
97
98
|
*/
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const SDK_VERSION = "0.1.0-rc.
|
|
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.
|
|
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";
|
|
@@ -69,7 +69,7 @@ export interface ModelInfo {
|
|
|
69
69
|
* Whether `document` blocks are accepted (default false). Images are governed by `vision`. When
|
|
70
70
|
* the model does not support them the kernel replaces media blocks with English text
|
|
71
71
|
* placeholders
|
|
72
|
-
* (e.g. `[Attached image "<name>" — this model cannot view images.]`; `text/*` documents are
|
|
72
|
+
* (e.g. `[Attached image "<name>" — this model cannot view images. Read with file_id <id> sends it to the organization's vision model, if one is set.]`; `text/*` documents are
|
|
73
73
|
* inlined as truncated text instead),
|
|
74
74
|
* and never sends the bytes to it.
|
|
75
75
|
*/
|
|
@@ -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
|
+
};
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shell environment (mobile layout spec §9, desktop client spec): the contract of the global a
|
|
3
|
+
* native shell injects as `window.capybaraShell`, only into the top frame of the deployment's
|
|
4
|
+
* origin. Types and the capability registry only; `capybara-hq/clients` implements it.
|
|
5
|
+
*/
|
|
6
|
+
export interface CapybaraShell {
|
|
7
|
+
/** The envelope version; bumped only on an incompatible change of this shape. */
|
|
8
|
+
readonly version: 1;
|
|
9
|
+
/** Which shell: drives nothing but the shell attributes. */
|
|
10
|
+
readonly kind: "desktop" | "mobile";
|
|
11
|
+
/** The operating system, for platform conventions only (traffic lights, back gesture). */
|
|
12
|
+
readonly platform: "macos" | "windows" | "linux" | "ios" | "android";
|
|
13
|
+
/** The shell's own version, for reports and diagnostics; never parsed for features. */
|
|
14
|
+
readonly shellVersion: string;
|
|
15
|
+
/**
|
|
16
|
+
* CSS px the shell's own chrome covers at each edge of the web view, beyond the OS safe areas
|
|
17
|
+
* (macOS traffic lights with `titleBarStyle: hiddenInset`, a native title bar overlay).
|
|
18
|
+
*/
|
|
19
|
+
readonly insets: {
|
|
20
|
+
top: number;
|
|
21
|
+
right: number;
|
|
22
|
+
bottom: number;
|
|
23
|
+
left: number;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* The rectangle the shell's window controls occupy over the web view, in CSS px from the web
|
|
27
|
+
* view's top-left corner (macOS traffic lights, a Windows caption-button overlay at the right);
|
|
28
|
+
* null when there are none or they are hidden (fullscreen). Modelled on Window Controls
|
|
29
|
+
* Overlay's `titlebar-area-*`. Optional: a shell without overlaid controls omits it.
|
|
30
|
+
*/
|
|
31
|
+
readonly controls?: {
|
|
32
|
+
x: number;
|
|
33
|
+
y: number;
|
|
34
|
+
width: number;
|
|
35
|
+
height: number;
|
|
36
|
+
} | null;
|
|
37
|
+
/** Capabilities by `name@major` (as extension points are named, `channel@1`). */
|
|
38
|
+
readonly capabilities: Readonly<Record<string, object>>;
|
|
39
|
+
/**
|
|
40
|
+
* Insets, controls or capabilities changed (fullscreen hides the traffic lights; a capability
|
|
41
|
+
* appears after load). Returns unsubscribe.
|
|
42
|
+
*/
|
|
43
|
+
on(event: "change", listener: () => void): () => void;
|
|
44
|
+
}
|
|
45
|
+
declare global {
|
|
46
|
+
interface Window {
|
|
47
|
+
capybaraShell?: CapybaraShell;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* The registry of capability names (mobile layout spec §9.2). A new capability is added here
|
|
52
|
+
* (key, owner) by the spec that defines it; the owner names the spec holding its functions.
|
|
53
|
+
*/
|
|
54
|
+
export declare const SHELL_CAPABILITIES: readonly {
|
|
55
|
+
key: string;
|
|
56
|
+
owner: string;
|
|
57
|
+
}[];
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shell environment (mobile layout spec §9, desktop client spec): the contract of the global a
|
|
3
|
+
* native shell injects as `window.capybaraShell`, only into the top frame of the deployment's
|
|
4
|
+
* origin. Types and the capability registry only; `capybara-hq/clients` implements it.
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* The registry of capability names (mobile layout spec §9.2). A new capability is added here
|
|
8
|
+
* (key, owner) by the spec that defines it; the owner names the spec holding its functions.
|
|
9
|
+
*/
|
|
10
|
+
export const SHELL_CAPABILITIES = [
|
|
11
|
+
{ key: "device@1", owner: "desktop client spec (2026-11-07-desktop-client-design.md)" },
|
|
12
|
+
{ key: "notify@1", owner: "desktop client spec (2026-11-07-desktop-client-design.md)" },
|
|
13
|
+
{ key: "openExternal@1", owner: "desktop client spec (2026-11-07-desktop-client-design.md)" },
|
|
14
|
+
{ key: "signIn@1", owner: "desktop client spec (2026-11-07-desktop-client-design.md), §6.5" },
|
|
15
|
+
{ key: "chrome@1", owner: "mobile layout spec (2026-11-19-mobile-layout-design.md)" },
|
|
16
|
+
];
|
|
@@ -3,6 +3,16 @@ export type UiSlotScope = "conversation" | "agent" | "org" | "platform" | "file"
|
|
|
3
3
|
export type UiSlotRole = "guest" | "member" | "admin" | "superAdmin";
|
|
4
4
|
/** Every slot id of the catalog, in catalog order (UI slots spec §3). */
|
|
5
5
|
export declare const UI_SLOT_IDS: readonly ["conversation.panel", "conversation.properties.section", "conversation.tool-result.card", "org.page", "file.preview", "agent.detail.section", "org.settings.section", "platform.page", "shell.brand", "shell.overlay", "conversation.empty", "conversation.composer.frame"];
|
|
6
|
+
/**
|
|
7
|
+
* What a slot (or a contribution) becomes on a compact screen (mobile layout spec §5.6): `kept` =
|
|
8
|
+
* rendered in its place, `drawer` = moved into a sheet or pushed page, `hidden` = not rendered.
|
|
9
|
+
* Order of narrowing: `kept` < `drawer` < `hidden`.
|
|
10
|
+
*/
|
|
11
|
+
export type CompactForm = "kept" | "drawer" | "hidden";
|
|
12
|
+
/** True when `v` is one of the three compact forms (used to validate manifests). */
|
|
13
|
+
export declare function isCompactForm(v: unknown): v is CompactForm;
|
|
14
|
+
/** A contribution may narrow its slot's compact form, never widen it. */
|
|
15
|
+
export declare function effectiveCompact(slot: CompactForm, contribution?: CompactForm): CompactForm;
|
|
6
16
|
export type UiSlotId = (typeof UI_SLOT_IDS)[number];
|
|
7
17
|
/** One slot of the catalog: where extension UI may go and what it receives (UI slots spec §3.1). */
|
|
8
18
|
export interface UiSlotSpec {
|
|
@@ -27,6 +37,8 @@ export interface UiSlotSpec {
|
|
|
27
37
|
args: readonly string[];
|
|
28
38
|
density: "dense" | "regular";
|
|
29
39
|
icon: "required" | "optional" | "none";
|
|
40
|
+
/** The slot's form on a compact screen (mobile layout spec §5.6). */
|
|
41
|
+
compact: CompactForm;
|
|
30
42
|
/** Built-in parts a contribution may be placed after; the first is the default. */
|
|
31
43
|
anchors?: readonly string[];
|
|
32
44
|
limits?: {
|
|
@@ -13,6 +13,17 @@ export const UI_SLOT_IDS = [
|
|
|
13
13
|
"conversation.empty",
|
|
14
14
|
"conversation.composer.frame",
|
|
15
15
|
];
|
|
16
|
+
const COMPACT_ORDER = ["kept", "drawer", "hidden"];
|
|
17
|
+
/** True when `v` is one of the three compact forms (used to validate manifests). */
|
|
18
|
+
export function isCompactForm(v) {
|
|
19
|
+
return typeof v === "string" && COMPACT_ORDER.includes(v);
|
|
20
|
+
}
|
|
21
|
+
/** A contribution may narrow its slot's compact form, never widen it. */
|
|
22
|
+
export function effectiveCompact(slot, contribution) {
|
|
23
|
+
if (contribution === undefined)
|
|
24
|
+
return slot;
|
|
25
|
+
return COMPACT_ORDER.indexOf(contribution) > COMPACT_ORDER.indexOf(slot) ? contribution : slot;
|
|
26
|
+
}
|
|
16
27
|
const SLOT_DATA = [
|
|
17
28
|
{
|
|
18
29
|
id: "conversation.panel",
|
|
@@ -25,6 +36,7 @@ const SLOT_DATA = [
|
|
|
25
36
|
args: ["conversationId", "item"],
|
|
26
37
|
density: "regular",
|
|
27
38
|
icon: "optional",
|
|
39
|
+
compact: "drawer",
|
|
28
40
|
description: {
|
|
29
41
|
en: "A panel beside the conversation, opened from the right area.",
|
|
30
42
|
zh: "对话旁的面板,从右侧区域打开。",
|
|
@@ -41,6 +53,7 @@ const SLOT_DATA = [
|
|
|
41
53
|
args: ["conversationId"],
|
|
42
54
|
density: "dense",
|
|
43
55
|
icon: "optional",
|
|
56
|
+
compact: "kept",
|
|
44
57
|
anchors: ["context", "files", "background"],
|
|
45
58
|
description: {
|
|
46
59
|
en: "A section in the conversation properties list.",
|
|
@@ -58,6 +71,7 @@ const SLOT_DATA = [
|
|
|
58
71
|
args: ["conversationId", "card"],
|
|
59
72
|
density: "regular",
|
|
60
73
|
icon: "optional",
|
|
74
|
+
compact: "kept",
|
|
61
75
|
description: {
|
|
62
76
|
en: "A card a tool result opens in the conversation.",
|
|
63
77
|
zh: "工具结果在对话中打开的卡片。",
|
|
@@ -74,6 +88,7 @@ const SLOT_DATA = [
|
|
|
74
88
|
args: [],
|
|
75
89
|
density: "regular",
|
|
76
90
|
icon: "optional",
|
|
91
|
+
compact: "kept",
|
|
77
92
|
description: {
|
|
78
93
|
en: "A full page in the organization navigation.",
|
|
79
94
|
zh: "组织导航中的完整页面。",
|
|
@@ -90,6 +105,7 @@ const SLOT_DATA = [
|
|
|
90
105
|
args: ["conversationId", "fileId"],
|
|
91
106
|
density: "regular",
|
|
92
107
|
icon: "optional",
|
|
108
|
+
compact: "kept",
|
|
93
109
|
description: {
|
|
94
110
|
en: "A previewer for a file of the conversation.",
|
|
95
111
|
zh: "对话中文件的预览器。",
|
|
@@ -106,6 +122,7 @@ const SLOT_DATA = [
|
|
|
106
122
|
args: ["agentId"],
|
|
107
123
|
density: "regular",
|
|
108
124
|
icon: "optional",
|
|
125
|
+
compact: "kept",
|
|
109
126
|
description: {
|
|
110
127
|
en: "A section on the detail page of an agent.",
|
|
111
128
|
zh: "智能体详情页中的一个分区。",
|
|
@@ -122,6 +139,7 @@ const SLOT_DATA = [
|
|
|
122
139
|
args: [],
|
|
123
140
|
density: "regular",
|
|
124
141
|
icon: "optional",
|
|
142
|
+
compact: "kept",
|
|
125
143
|
description: {
|
|
126
144
|
en: "A section on the organization settings page.",
|
|
127
145
|
zh: "组织设置页中的一个分区。",
|
|
@@ -138,6 +156,7 @@ const SLOT_DATA = [
|
|
|
138
156
|
args: [],
|
|
139
157
|
density: "regular",
|
|
140
158
|
icon: "optional",
|
|
159
|
+
compact: "kept",
|
|
141
160
|
description: {
|
|
142
161
|
en: "A full page in the platform administration.",
|
|
143
162
|
zh: "平台管理中的完整页面。",
|
|
@@ -156,6 +175,7 @@ const SLOT_DATA = [
|
|
|
156
175
|
args: [],
|
|
157
176
|
density: "regular",
|
|
158
177
|
icon: "none",
|
|
178
|
+
compact: "hidden",
|
|
159
179
|
description: {
|
|
160
180
|
en: "The brand row of the sidebar (the mark of the collapsed rail).",
|
|
161
181
|
zh: "侧边栏的品牌行(收起后的窄栏标记)。",
|
|
@@ -172,6 +192,7 @@ const SLOT_DATA = [
|
|
|
172
192
|
args: [],
|
|
173
193
|
density: "regular",
|
|
174
194
|
icon: "none",
|
|
195
|
+
compact: "kept",
|
|
175
196
|
limits: { maxShown: 4 },
|
|
176
197
|
description: {
|
|
177
198
|
en: "A full-viewport layer over the workspace shell.",
|
|
@@ -191,6 +212,7 @@ const SLOT_DATA = [
|
|
|
191
212
|
args: [],
|
|
192
213
|
density: "regular",
|
|
193
214
|
icon: "none",
|
|
215
|
+
compact: "kept",
|
|
194
216
|
description: {
|
|
195
217
|
en: "The hero of the new-conversation page.",
|
|
196
218
|
zh: "新对话页的主视觉区。",
|
|
@@ -209,6 +231,7 @@ const SLOT_DATA = [
|
|
|
209
231
|
args: [],
|
|
210
232
|
density: "regular",
|
|
211
233
|
icon: "none",
|
|
234
|
+
compact: "kept",
|
|
212
235
|
description: {
|
|
213
236
|
en: "The frame around the composer, on the new-conversation and conversation pages.",
|
|
214
237
|
zh: "新对话页与对话页中输入框外的边框。",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { Locale } from "./cards.js";
|
|
2
2
|
import { type FormAnswer, type InputForm } from "./tool.js";
|
|
3
|
-
import type { UiSlotId, UiSlotScope } from "./ui-slots.js";
|
|
3
|
+
import type { CompactForm, UiSlotId, UiSlotScope } from "./ui-slots.js";
|
|
4
4
|
/**
|
|
5
5
|
* Icons a contribution may use (design system icon names; `puzzle` is the default and is drawn as
|
|
6
6
|
* the design `extension` icon). The title-bar button of a panel shows it.
|
|
@@ -50,6 +50,11 @@ export interface UiContribution {
|
|
|
50
50
|
path?: string;
|
|
51
51
|
/** Icon from {@link UI_ICONS}; default `puzzle`. */
|
|
52
52
|
icon?: UiIcon;
|
|
53
|
+
/**
|
|
54
|
+
* The form on a compact screen; may only narrow the slot's own (`kept` -> `drawer` -> `hidden`),
|
|
55
|
+
* see `effectiveCompact`. Omitted = the slot's form.
|
|
56
|
+
*/
|
|
57
|
+
compact?: CompactForm;
|
|
53
58
|
}
|
|
54
59
|
/**
|
|
55
60
|
* Blocks of the render schema. Text is for humans and shown as is (the plugin decides the language
|