@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
@@ -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
- !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(o.dataB64))
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.36";
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.36";
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/plugin-sdk",
3
- "version": "0.1.0-rc.36",
3
+ "version": "0.1.0-rc.38",
4
4
  "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {