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

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 (109) hide show
  1. package/README.md +101 -157
  2. package/dist/api.d.ts +2 -2
  3. package/dist/args.d.ts +2 -8
  4. package/dist/args.js +2 -25
  5. package/dist/cli.d.ts +2 -11
  6. package/dist/cli.js +6 -61
  7. package/dist/client.d.ts +8 -45
  8. package/dist/client.js +25 -424
  9. package/dist/command-log.d.ts +14 -4
  10. package/dist/command-log.js +37 -1
  11. package/dist/commands/ceiling.d.ts +0 -2
  12. package/dist/commands/ceiling.js +3 -4
  13. package/dist/commands/login.d.ts +25 -1
  14. package/dist/commands/login.js +75 -61
  15. package/dist/commands/policy.d.ts +6 -8
  16. package/dist/commands/policy.js +30 -49
  17. package/dist/commands/start.d.ts +2 -17
  18. package/dist/commands/start.js +13 -53
  19. package/dist/exec/docker-operations.d.ts +2 -2
  20. package/dist/exec/docker-operations.js +4 -2
  21. package/dist/exec/docker.d.ts +37 -122
  22. package/dist/exec/docker.js +72 -717
  23. package/dist/exec/instance-binding.d.ts +4 -4
  24. package/dist/exec/linux-agent.js +30 -0
  25. package/dist/exec/linux-operation-backend.d.ts +5 -0
  26. package/dist/exec/linux-operation-backend.js +3 -1
  27. package/dist/exec/linux-operation-worker.d.ts +9 -0
  28. package/dist/exec/linux-operation-worker.js +11 -2
  29. package/dist/exec/mac-read-policy.d.ts +58 -0
  30. package/dist/exec/mac-read-policy.js +104 -0
  31. package/dist/exec/mac-self-check.d.ts +6 -3
  32. package/dist/exec/mac-self-check.js +28 -5
  33. package/dist/exec/operation-worker.d.ts +21 -2
  34. package/dist/exec/operation-worker.js +164 -43
  35. package/dist/exec/sandbox-check.d.ts +10 -0
  36. package/dist/exec/sandbox-check.js +18 -0
  37. package/dist/exec/sandbox-messages.d.ts +3 -11
  38. package/dist/exec/sandbox-messages.js +3 -18
  39. package/dist/exec/shared.d.ts +24 -47
  40. package/dist/exec/shared.js +53 -165
  41. package/dist/exec/types.d.ts +2 -66
  42. package/dist/exec/types.js +1 -1
  43. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +71 -12
  44. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js +18 -4
  45. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +6 -0
  46. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +4 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/concepts.md +9 -4
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/channel.md +1 -1
  49. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md +2 -0
  50. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/sandbox.md +1 -1
  51. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/plugin-format.md +1 -1
  52. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.d.ts +11 -0
  53. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.js +1 -1
  54. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/channel.d.ts +37 -0
  55. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ctx.d.ts +47 -3
  56. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.d.ts +14 -0
  57. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.js +41 -0
  58. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +140 -20
  59. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +419 -14
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/file-preview.d.ts +22 -5
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +77 -13
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/http-access.d.ts +10 -0
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +2 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +2 -3
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +89 -5
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.js +103 -0
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.d.ts +3 -2
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +2 -2
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +4 -0
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.d.ts +1 -1
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.js +11 -0
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +25 -6
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  74. package/dist/owner-report.d.ts +2 -2
  75. package/dist/owner-report.js +2 -2
  76. package/dist/policy-store.d.ts +6 -10
  77. package/dist/policy-store.js +9 -23
  78. package/dist/policy.d.ts +3 -32
  79. package/dist/policy.js +4 -74
  80. package/dist/runtime-manifest.json +1 -1
  81. package/dist/server-ops.d.ts +18 -46
  82. package/dist/server-ops.js +134 -269
  83. package/dist/staged-connect.js +44 -7
  84. package/dist/staged-device.d.ts +4 -4
  85. package/dist/staged-device.js +3 -0
  86. package/dist/staged-session.d.ts +5 -5
  87. package/dist/staged-session.js +4 -4
  88. package/dist/state.js +3 -2
  89. package/package.json +2 -2
  90. package/dist/commands/mode.d.ts +0 -69
  91. package/dist/commands/mode.js +0 -133
  92. package/dist/exec/fs-helper.d.ts +0 -21
  93. package/dist/exec/fs-helper.js +0 -171
  94. package/dist/exec/host.d.ts +0 -61
  95. package/dist/exec/host.js +0 -203
  96. package/dist/exec/listing.d.ts +0 -35
  97. package/dist/exec/listing.js +0 -157
  98. package/dist/exec/os.d.ts +0 -162
  99. package/dist/exec/os.js +0 -616
  100. package/dist/exec/procs.d.ts +0 -11
  101. package/dist/exec/procs.js +0 -67
  102. package/dist/exec/reap.d.ts +0 -41
  103. package/dist/exec/reap.js +0 -89
  104. package/dist/exec/switch.d.ts +0 -107
  105. package/dist/exec/switch.js +0 -204
  106. package/dist/network.d.ts +0 -45
  107. package/dist/network.js +0 -154
  108. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.d.ts +0 -117
  109. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.js +0 -409
@@ -1,6 +1,6 @@
1
- import { type DeviceExecArgs, type DeviceListResult, type DeviceScanResult, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
- import type { Policy, SandboxMode } from "../state.js";
3
- import { type Executor } from "./types.js";
1
+ import { type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
+ import type { Policy } from "../state.js";
3
+ import type { OperationContainerHost } from "./docker-operations.js";
4
4
  /** The version of the published sandbox images this program runs commands in. */
5
5
  export declare const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
6
6
  export declare const SANDBOX_IMAGE = "ghcr.io/capybara-hq/capybara-sandbox:0.1.0-rc.5";
@@ -10,6 +10,15 @@ export declare const SANDBOX_IMAGE = "ghcr.io/capybara-hq/capybara-sandbox:0.1.0
10
10
  * Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
11
11
  */
12
12
  export declare function containerUser(platform?: NodeJS.Platform, uid?: number | undefined, gid?: number | undefined): string;
13
+ /**
14
+ * The container format. It is part of the run flags, so a container an older format made (a
15
+ * protocol 2 program's, which may hold its commands' leftovers and may run without a network) is
16
+ * recreated at its first use, once nothing holds it, never reused.
17
+ */
18
+ export declare const CONTAINER_FORMAT = 2;
19
+ export declare const CONTAINER_FORMAT_LABEL = "capybara.device.format";
20
+ /** The spec label of a container made with `runFlags`: a container made otherwise is recreated. */
21
+ export declare function containerSpec(runFlags: string[]): string;
13
22
  /** Container name of a device. */
14
23
  export declare function containerName(deviceId: string): string;
15
24
  /** Whether the docker CLI can reach a daemon, and why not. */
@@ -19,163 +28,69 @@ export declare function dockerAvailability(): Promise<{
19
28
  ok: false;
20
29
  reason: string;
21
30
  }>;
22
- export interface DockerExecutorOptions {
31
+ export interface DockerContainerOptions {
23
32
  /** The device directory (from login). */
24
33
  dir: string;
25
34
  deviceId: string;
26
35
  /**
27
- * The local policy now. The network decision reads it at each command; cpu and memory apply
28
- * when the container is next created (at the next command that finds it idle).
36
+ * The local policy now; cpu and memory apply when the container is next created (when an
37
+ * operation finds it idle with other flags). An unreadable policy refuses the operation.
29
38
  */
30
39
  policy: () => Policy;
31
40
  }
32
41
  /**
33
- * Runs every command with `docker exec` in one long-lived container of the published sandbox
34
- * image: the device directory's workspace, skills (read only) and tmp are mounted at
35
- * /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
36
- * (as the `sandbox` user, so a link a command plants resolves in the container and never on the
37
- * host); the skills directory, which commands cannot write, is accessed from the host with the
38
- * same real-path checks as the OS executor. Auto mode: the container on its default bridge, and
39
- * file operations reach any absolute path in the container. Sandbox mode: no network attached and
40
- * file operations stay in the mounted roots. Docker mode has no per-domain filter. A change of the
41
- * container's flags recreates it at the next command that finds it idle.
42
+ * The docker-mode device's one long-lived container of the published sandbox image: the device
43
+ * directory's workspace, skills (read only) and tmp are mounted at /workspace, /skills and /tmp.
44
+ * It hosts the permission operations (`docker-operations.ts`): each one holds the container
45
+ * through {@link operationContainer}, so it is never recreated under a running operation. A change
46
+ * of the container's flags recreates it at the next operation that finds it idle. Nothing here
47
+ * runs commands or kills processes: the operation backend owns its work and stops it exactly.
42
48
  */
43
- export declare class DockerExecutor implements Executor {
49
+ export declare class DockerContainer implements OperationContainerHost {
44
50
  private readonly opts;
45
- readonly mode: "docker";
46
51
  readonly roots: SandboxRoots;
47
52
  readonly name: string;
48
53
  private readonly dir;
49
54
  private readonly hostRoots;
50
- private readonly guard;
51
- private readonly hostFiles;
52
- /** Marks every process of this device's commands: `<dirKey>.<tag>`. */
53
- private readonly dirKey;
54
- private readonly running;
55
55
  private chain;
56
56
  private ready;
57
- /** The container has the default bridge (commands may reach the network). */
58
- private netOpen;
57
+ /** Operations holding the container now. */
59
58
  private inflight;
60
- private readonly queue;
61
- private pumping;
62
- private dirty;
63
- /** The limits of the latest command: the kernel's mode ceiling for file operations. */
64
- private lastLimits;
65
- /** When {@link lastLimits} came (file operations follow it only inside the window). */
66
- private lastLimitsAt;
67
59
  /** The spec hash of the container in use (set when it is created or reused). */
68
60
  private spec;
69
- constructor(opts: DockerExecutorOptions);
70
- ensureRoot(): Promise<"ok" | "gone">;
71
- markerOf(tag: string): string;
61
+ constructor(opts: DockerContainerOptions);
72
62
  private serial;
73
63
  private inspect;
74
64
  private wanted;
75
- /**
76
- * The mode file operations use now. File operations carry no limits and never pass command
77
- * review, so they use the sandboxed result before any exec and once the latest decision is stale
78
- * (the safe default for an organization whose ceiling is sandbox), else
79
- * `effectiveMode(policy, limits)`.
80
- */
81
- private modeNow;
82
65
  /** Every `docker run` flag of the container except its name and spec label. */
83
- private runArgs;
66
+ runFlags(): string[];
84
67
  /** A hash of the run flags: a container made with other flags is recreated. */
85
68
  private specHash;
86
- private hashOf;
87
69
  private matches;
88
70
  private mustDocker;
89
- /**
90
- * Creates the container, or reuses the existing one when it matches; call inside `serial`.
91
- * A file operation (`anySpec`) reuses any container that sees the directory: it needs no
92
- * particular flags, and before the first command the policy is not known yet. The next command
93
- * that finds it idle recreates it if its flags differ.
94
- */
71
+ /** Creates the container, or reuses the existing one when it matches; call inside `serial`. */
95
72
  private ensureContainer;
96
73
  /**
97
74
  * Whether a reused container's mounts still show this directory's roots: after the directory was
98
75
  * removed and recreated (`login` again), a Linux bind mount still holds the deleted one.
99
76
  */
100
77
  private seesHostRoots;
101
- private inspectNetworks;
102
- private setNet;
103
- /**
104
- * Waits until the container exists with the wanted network state and counts the caller as
105
- * running. Callers are served in arrival order: once one needs the other network state, later
106
- * callers for the current state queue behind it, so it is not starved.
107
- */
108
- private acquire;
109
- private pump;
110
- private dequeue;
111
- private drain;
112
- private release;
113
78
  /**
114
- * The container for one permission operation (protocol 3): running on its default bridge (Full
115
- * access is the container user's own network; restricted operations are mediated by the
116
- * launcher). The caller holds the container (it is not recreated) until it calls `release`,
117
- * once; an abort while waiting for it rejects.
79
+ * The container for one permission operation: running on its default bridge (Full access is
80
+ * the container user's own network; restricted operations are mediated by the launcher). The
81
+ * caller holds the
82
+ * container (it is not recreated) until it calls `release`, once; an abort while waiting for it
83
+ * rejects and holds nothing.
118
84
  */
119
85
  operationContainer(signal: AbortSignal): Promise<{
120
86
  name: string;
121
87
  user: string;
122
88
  release: () => void;
123
89
  }>;
124
- /** A docker-level failure that means the container vanished: the next call recreates it. */
125
- private noteFailure;
126
- exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
127
- private run;
128
- /**
129
- * `path` made absolute and normalized. Auto mode accepts any clean absolute path (the container
130
- * is the boundary); sandbox mode refuses anything outside the mounted roots.
131
- */
132
- private containerPath;
133
- /** The host path of a /skills path (the skills directory is mounted read only). */
134
- private skillsHostPath;
135
- private inSkills;
136
- /** Runs one file script in the container; `null` for a missing file. */
137
- private fileOp;
138
- private fileResult;
139
- readFile(path: string, maxBytes: number): Promise<{
140
- data: Uint8Array;
141
- truncated: boolean;
142
- } | null>;
143
- writeFile(path: string, data: Uint8Array): Promise<void>;
144
- stat(path: string): Promise<{
145
- size: number;
146
- isDir: boolean;
147
- } | null>;
148
- /**
149
- * `path` made absolute and normalized, refused unless it lies lexically under the container's
150
- * workspace: a container device offers its workspace only, in either mode (spec §4.2).
151
- */
152
- private workspacePath;
153
- /**
154
- * Whether the device directory is marked and holds all three roots. `list` and `scan` only
155
- * read: a removed root under a marked directory lost its files and is never recreated empty
156
- * (`ensureContainer` would create it), and an unmarked or vanished directory gets no roots either.
157
- */
158
- private rootsIntact;
159
- /**
160
- * Runs {@link LIST_SCRIPT} in the container (as the `sandbox` user, like the file operations):
161
- * links resolve in the container, so whatever a command there does to the workspace, the answer
162
- * shows only what the container itself can see, never the host behind the bind mount. A stopped
163
- * container is started first, as for the file operations.
164
- */
165
- private listOp;
166
- /** Lists a container workspace directory, read in the container, in either mode. */
167
- list(_mode: SandboxMode, path: string, limit: number, signal?: AbortSignal): Promise<DeviceListResult>;
168
- /** Scans a container workspace directory, read in the container ({@link list}'s rules). */
169
- scan(_mode: SandboxMode, base: string, signal?: AbortSignal): Promise<DeviceScanResult>;
170
- /** Kills the container processes of one marker (exact) or marker prefix. */
171
- private killScript;
172
- private killMarker;
173
- killTagged(tags: string[]): Promise<void>;
174
- killAll(): Promise<void>;
175
- /** Kills every process carrying this device's marker (also a previous run's). */
176
- killLeftovers(): Promise<void>;
177
- /** Kills every running command; the container stays for the next start. */
178
- dispose(): Promise<void>;
179
90
  }
180
- /** The Docker executor: checks the daemon and kills what a previous run left running. */
181
- export declare function createDockerExecutor(opts: DockerExecutorOptions): Promise<DockerExecutor>;
91
+ /**
92
+ * The docker-mode device's container host: checks the daemon. It kills nothing at startup (no
93
+ * marker reaper): work an earlier run left is the operation backend's, recovered and stopped
94
+ * exactly through its journal.
95
+ */
96
+ export declare function createDockerContainer(opts: DockerContainerOptions): Promise<DockerContainer>;