@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.
- package/README.md +101 -157
- package/dist/api.d.ts +2 -2
- package/dist/args.d.ts +2 -8
- package/dist/args.js +2 -25
- package/dist/cli.d.ts +2 -11
- package/dist/cli.js +6 -61
- package/dist/client.d.ts +8 -45
- package/dist/client.js +25 -424
- package/dist/command-log.d.ts +14 -4
- package/dist/command-log.js +37 -1
- package/dist/commands/ceiling.d.ts +0 -2
- package/dist/commands/ceiling.js +3 -4
- package/dist/commands/login.d.ts +25 -1
- package/dist/commands/login.js +75 -61
- package/dist/commands/policy.d.ts +6 -8
- package/dist/commands/policy.js +30 -49
- package/dist/commands/start.d.ts +2 -17
- package/dist/commands/start.js +13 -53
- package/dist/exec/docker-operations.d.ts +2 -2
- package/dist/exec/docker-operations.js +4 -2
- package/dist/exec/docker.d.ts +37 -122
- package/dist/exec/docker.js +72 -717
- package/dist/exec/instance-binding.d.ts +4 -4
- package/dist/exec/linux-agent.js +30 -0
- package/dist/exec/linux-operation-backend.d.ts +5 -0
- package/dist/exec/linux-operation-backend.js +3 -1
- package/dist/exec/linux-operation-worker.d.ts +9 -0
- package/dist/exec/linux-operation-worker.js +11 -2
- package/dist/exec/mac-read-policy.d.ts +58 -0
- package/dist/exec/mac-read-policy.js +104 -0
- package/dist/exec/mac-self-check.d.ts +6 -3
- package/dist/exec/mac-self-check.js +28 -5
- package/dist/exec/operation-worker.d.ts +21 -2
- package/dist/exec/operation-worker.js +164 -43
- package/dist/exec/sandbox-check.d.ts +10 -0
- package/dist/exec/sandbox-check.js +18 -0
- package/dist/exec/sandbox-messages.d.ts +3 -11
- package/dist/exec/sandbox-messages.js +3 -18
- package/dist/exec/shared.d.ts +24 -47
- package/dist/exec/shared.js +53 -165
- package/dist/exec/types.d.ts +2 -66
- package/dist/exec/types.js +1 -1
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +71 -12
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js +18 -4
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +6 -0
- package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +4 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/concepts.md +9 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/channel.md +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md +2 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/sandbox.md +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/plugin-format.md +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.d.ts +11 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.js +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/channel.d.ts +37 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ctx.d.ts +47 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.d.ts +14 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.js +41 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +140 -20
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +419 -14
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/file-preview.d.ts +22 -5
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +77 -13
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/http-access.d.ts +10 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +2 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +2 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +89 -5
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.js +103 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.d.ts +3 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +2 -2
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +4 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.d.ts +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.js +11 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +25 -6
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/owner-report.d.ts +2 -2
- package/dist/owner-report.js +2 -2
- package/dist/policy-store.d.ts +6 -10
- package/dist/policy-store.js +9 -23
- package/dist/policy.d.ts +3 -32
- package/dist/policy.js +4 -74
- package/dist/runtime-manifest.json +1 -1
- package/dist/server-ops.d.ts +18 -46
- package/dist/server-ops.js +134 -269
- package/dist/staged-connect.js +44 -7
- package/dist/staged-device.d.ts +4 -4
- package/dist/staged-device.js +3 -0
- package/dist/staged-session.d.ts +5 -5
- package/dist/staged-session.js +4 -4
- package/dist/state.js +3 -2
- package/package.json +2 -2
- package/dist/commands/mode.d.ts +0 -69
- package/dist/commands/mode.js +0 -133
- package/dist/exec/fs-helper.d.ts +0 -21
- package/dist/exec/fs-helper.js +0 -171
- package/dist/exec/host.d.ts +0 -61
- package/dist/exec/host.js +0 -203
- package/dist/exec/listing.d.ts +0 -35
- package/dist/exec/listing.js +0 -157
- package/dist/exec/os.d.ts +0 -162
- package/dist/exec/os.js +0 -616
- package/dist/exec/procs.d.ts +0 -11
- package/dist/exec/procs.js +0 -67
- package/dist/exec/reap.d.ts +0 -41
- package/dist/exec/reap.js +0 -89
- package/dist/exec/switch.d.ts +0 -107
- package/dist/exec/switch.js +0 -204
- package/dist/network.d.ts +0 -45
- package/dist/network.js +0 -154
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.d.ts +0 -117
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.js +0 -409
package/dist/exec/shared.js
CHANGED
|
@@ -1,12 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
4
|
-
import { validateSandboxPathShape } from "@capybara-hq/plugin-sdk";
|
|
5
|
-
import { DeviceOpError } from "./types.js";
|
|
1
|
+
import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { isAbsolute, join, normalize } from "node:path";
|
|
6
3
|
/** The file that marks a directory as a device directory this program has used. */
|
|
7
|
-
|
|
8
|
-
/** How long a finished command's output pipes may stay open (held by a background child). */
|
|
9
|
-
export const PIPE_GRACE_MS = 200;
|
|
4
|
+
const ROOT_MARKER = ".capybara-device";
|
|
10
5
|
export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
11
6
|
/** The roots of a device directory: `<dir>/workspace`, `<dir>/skills`, `<dir>/tmp`. */
|
|
12
7
|
export function osRoots(dir) {
|
|
@@ -29,6 +24,14 @@ export const TOOL_HOME_DIRS = [
|
|
|
29
24
|
["SDKMAN_DIR", ".sdkman"],
|
|
30
25
|
["RUSTUP_HOME", ".rustup"],
|
|
31
26
|
];
|
|
27
|
+
/**
|
|
28
|
+
* Single files in the home that hold a version manager's global pins, granted read only next to
|
|
29
|
+
* {@link TOOL_HOME_DIRS}: asdf's global `.tool-versions` (mise reads it too). The other managers
|
|
30
|
+
* keep their global version inside their data directory (pyenv and rbenv `version`, nvm
|
|
31
|
+
* `alias/default`, rustup `settings.toml`, mise `config.toml`); a per-project file such as
|
|
32
|
+
* `.nvmrc` is not global. Never a dotfile that could hold a secret.
|
|
33
|
+
*/
|
|
34
|
+
export const TOOL_HOME_FILES = [".tool-versions"];
|
|
32
35
|
function isDir(path) {
|
|
33
36
|
try {
|
|
34
37
|
return statSync(path).isDirectory();
|
|
@@ -68,6 +71,48 @@ export function toolHomeEnv(home, env = process.env) {
|
|
|
68
71
|
}
|
|
69
72
|
return out;
|
|
70
73
|
}
|
|
74
|
+
/**
|
|
75
|
+
* What a restricted exec on the host gets for its version managers: the {@link toolHomeEnv}
|
|
76
|
+
* variables of the device process (its real `home` and its own environment `env`), the canonical
|
|
77
|
+
* directories they name as read-only roots, and the global pin files ({@link TOOL_HOME_FILES})
|
|
78
|
+
* that exist as regular files, canonical, as read-only files. A directory is left out when it does
|
|
79
|
+
* not exist, is `/`, lies at or under an owner-denied path, or contains one (Landlock cannot hide
|
|
80
|
+
* a denied path inside a granted root); a file is left out when it, or the target of a link it
|
|
81
|
+
* is, lies at or under one. Nothing here is ever made writable. A command in the device's
|
|
82
|
+
* container uses none of this: its home is the image's.
|
|
83
|
+
*/
|
|
84
|
+
export function restrictedToolHomes(home, env, deniedReadRoots) {
|
|
85
|
+
const vars = toolHomeEnv(home, env);
|
|
86
|
+
const inside = (path, root) => root === "/" || path === root || path.startsWith(`${root}/`);
|
|
87
|
+
const denied = (paths, contains) => paths.some((p) => deniedReadRoots.some((d) => inside(p, d) || (contains && inside(d, p))));
|
|
88
|
+
const canonical = (path, kind) => {
|
|
89
|
+
try {
|
|
90
|
+
const real = realpathSync(path);
|
|
91
|
+
const info = statSync(real);
|
|
92
|
+
return (kind === "dir" ? info.isDirectory() : info.isFile()) ? real : undefined;
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
return undefined;
|
|
96
|
+
}
|
|
97
|
+
};
|
|
98
|
+
const readRoots = new Set();
|
|
99
|
+
for (const dir of Object.values(vars)) {
|
|
100
|
+
const path = normalize(dir).replace(/(.)\/+$/, "$1");
|
|
101
|
+
const real = canonical(path, "dir");
|
|
102
|
+
if (real === undefined || real === "/" || denied([path, real], true))
|
|
103
|
+
continue;
|
|
104
|
+
readRoots.add(real);
|
|
105
|
+
}
|
|
106
|
+
const readFiles = new Set();
|
|
107
|
+
for (const rel of TOOL_HOME_FILES) {
|
|
108
|
+
const path = join(home, rel);
|
|
109
|
+
const real = canonical(path, "file");
|
|
110
|
+
if (real === undefined || denied([path, real], false))
|
|
111
|
+
continue;
|
|
112
|
+
readFiles.add(real);
|
|
113
|
+
}
|
|
114
|
+
return { env: vars, readRoots: [...readRoots], readFiles: [...readFiles] };
|
|
115
|
+
}
|
|
71
116
|
/**
|
|
72
117
|
* The longest prefix of `b` that does not end inside a UTF-8 sequence (a cut buffer's tail is
|
|
73
118
|
* dropped instead of decoding to U+FFFD).
|
|
@@ -88,16 +133,6 @@ export function utf8Prefix(b) {
|
|
|
88
133
|
export function shellQuote(s) {
|
|
89
134
|
return `'${s.replaceAll("'", "'\\''")}'`;
|
|
90
135
|
}
|
|
91
|
-
export function isUnder(p, root) {
|
|
92
|
-
return p === root || p.startsWith(`${root}/`);
|
|
93
|
-
}
|
|
94
|
-
export function policyError(message) {
|
|
95
|
-
return new DeviceOpError("policy", message);
|
|
96
|
-
}
|
|
97
|
-
export function isMissing(e) {
|
|
98
|
-
const code = e.code;
|
|
99
|
-
return code === "ENOENT" || code === "ENOTDIR";
|
|
100
|
-
}
|
|
101
136
|
/** Captures stdout and stderr up to a combined byte budget; the rest is drained and dropped. */
|
|
102
137
|
export class OutputCap {
|
|
103
138
|
max;
|
|
@@ -169,150 +204,3 @@ export class RootGuard {
|
|
|
169
204
|
return "ok";
|
|
170
205
|
}
|
|
171
206
|
}
|
|
172
|
-
/**
|
|
173
|
-
* Host-side file access. In sandbox mode `path`s are confined to the three roots (real paths,
|
|
174
|
-
* symlinks resolved, refused when they leave a root); in auto mode any clean absolute path is
|
|
175
|
-
* accepted (shape checks only: absolute, no `..` segments, no control characters). Used for the
|
|
176
|
-
* skills root (commands can only read it, so nothing can race it) and by the host executor.
|
|
177
|
-
*/
|
|
178
|
-
export class HostFiles {
|
|
179
|
-
roots;
|
|
180
|
-
mode;
|
|
181
|
-
constructor(roots, mode) {
|
|
182
|
-
this.roots = roots;
|
|
183
|
-
this.mode = mode;
|
|
184
|
-
}
|
|
185
|
-
/**
|
|
186
|
-
* `path` made absolute and normalized; in sandbox mode refused unless it is lexically under a
|
|
187
|
-
* root, in auto mode accepted when its shape is clean.
|
|
188
|
-
*/
|
|
189
|
-
lexical(path) {
|
|
190
|
-
if (this.mode === "auto") {
|
|
191
|
-
const errors = validateSandboxPathShape(path);
|
|
192
|
-
if (errors.length > 0)
|
|
193
|
-
throw policyError(`${path}: ${errors.join("; ")}`);
|
|
194
|
-
return resolve(path);
|
|
195
|
-
}
|
|
196
|
-
if (!isAbsolute(path))
|
|
197
|
-
throw policyError(`${path} is not an absolute path`);
|
|
198
|
-
const p = resolve(path);
|
|
199
|
-
if (!this.rootList().some((r) => isUnder(p, r))) {
|
|
200
|
-
throw policyError(`${path} is outside the device's roots (${this.rootList().join(", ")})`);
|
|
201
|
-
}
|
|
202
|
-
return p;
|
|
203
|
-
}
|
|
204
|
-
/**
|
|
205
|
-
* The real path of an existing `path` (null when missing); in sandbox mode refused unless under
|
|
206
|
-
* a root after resolving links.
|
|
207
|
-
*/
|
|
208
|
-
async existing(path) {
|
|
209
|
-
const p = this.lexical(path);
|
|
210
|
-
let real;
|
|
211
|
-
try {
|
|
212
|
-
real = await realpath(p);
|
|
213
|
-
}
|
|
214
|
-
catch (e) {
|
|
215
|
-
if (isMissing(e))
|
|
216
|
-
return null;
|
|
217
|
-
throw e;
|
|
218
|
-
}
|
|
219
|
-
return this.checkReal(path, real);
|
|
220
|
-
}
|
|
221
|
-
/**
|
|
222
|
-
* The real path of an existing `path` (symlinks resolved); in sandbox mode refused unless under
|
|
223
|
-
* a root.
|
|
224
|
-
*/
|
|
225
|
-
async inside(path, what) {
|
|
226
|
-
const p = this.lexical(path);
|
|
227
|
-
let real;
|
|
228
|
-
try {
|
|
229
|
-
real = await realpath(p);
|
|
230
|
-
}
|
|
231
|
-
catch (e) {
|
|
232
|
-
if (isMissing(e))
|
|
233
|
-
throw new DeviceOpError("error", `${what} ${path} does not exist`);
|
|
234
|
-
throw e;
|
|
235
|
-
}
|
|
236
|
-
return this.checkReal(path, real);
|
|
237
|
-
}
|
|
238
|
-
async checkReal(path, real) {
|
|
239
|
-
if (this.mode === "auto")
|
|
240
|
-
return real;
|
|
241
|
-
const roots = await Promise.all(this.rootList().map((r) => realpath(r).catch(() => r)));
|
|
242
|
-
if (!roots.some((r) => isUnder(real, r))) {
|
|
243
|
-
throw policyError(`${path} resolves to ${real}, outside the device's roots`);
|
|
244
|
-
}
|
|
245
|
-
return real;
|
|
246
|
-
}
|
|
247
|
-
rootList() {
|
|
248
|
-
return [this.roots.workspace, this.roots.skills, this.roots.tmp];
|
|
249
|
-
}
|
|
250
|
-
async read(path, maxBytes) {
|
|
251
|
-
const real = await this.existing(path);
|
|
252
|
-
if (real === null)
|
|
253
|
-
return null;
|
|
254
|
-
const fh = await open(real, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
|
|
255
|
-
try {
|
|
256
|
-
const st = await fh.stat();
|
|
257
|
-
if (st.isDirectory())
|
|
258
|
-
return null;
|
|
259
|
-
if (!st.isFile())
|
|
260
|
-
throw policyError(`${path} is not a regular file`);
|
|
261
|
-
const want = Math.min(st.size, maxBytes);
|
|
262
|
-
const buf = Buffer.alloc(want);
|
|
263
|
-
let off = 0;
|
|
264
|
-
while (off < want) {
|
|
265
|
-
const { bytesRead } = await fh.read(buf, off, want - off, off);
|
|
266
|
-
if (bytesRead === 0)
|
|
267
|
-
break;
|
|
268
|
-
off += bytesRead;
|
|
269
|
-
}
|
|
270
|
-
return { data: buf.subarray(0, off), truncated: st.size > maxBytes };
|
|
271
|
-
}
|
|
272
|
-
finally {
|
|
273
|
-
await fh.close();
|
|
274
|
-
}
|
|
275
|
-
}
|
|
276
|
-
async stat(path) {
|
|
277
|
-
const real = await this.existing(path);
|
|
278
|
-
if (real === null)
|
|
279
|
-
return null;
|
|
280
|
-
const st = await lstat(real);
|
|
281
|
-
return { size: st.size, isDir: st.isDirectory() };
|
|
282
|
-
}
|
|
283
|
-
async write(path, data) {
|
|
284
|
-
const target = this.lexical(path);
|
|
285
|
-
const parent = dirname(target);
|
|
286
|
-
// Check the nearest existing ancestor before creating anything beneath it.
|
|
287
|
-
let ancestor = parent;
|
|
288
|
-
while (!existsSync(ancestor))
|
|
289
|
-
ancestor = dirname(ancestor);
|
|
290
|
-
await this.inside(ancestor, "path");
|
|
291
|
-
await mkdir(parent, { recursive: true });
|
|
292
|
-
const realParent = await this.inside(parent, "path");
|
|
293
|
-
let file = join(realParent, basename(target));
|
|
294
|
-
const st = await lstat(file).catch((e) => {
|
|
295
|
-
if (isMissing(e))
|
|
296
|
-
return null;
|
|
297
|
-
throw e;
|
|
298
|
-
});
|
|
299
|
-
if (st?.isSymbolicLink()) {
|
|
300
|
-
const real = await realpath(file).catch((e) => {
|
|
301
|
-
if (isMissing(e))
|
|
302
|
-
throw policyError(`${path} is a dangling symbolic link`);
|
|
303
|
-
throw e;
|
|
304
|
-
});
|
|
305
|
-
file = await this.inside(real, "path");
|
|
306
|
-
}
|
|
307
|
-
const fh = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_NONBLOCK | constants.O_NOFOLLOW, 0o644);
|
|
308
|
-
try {
|
|
309
|
-
if (!(await fh.stat()).isFile())
|
|
310
|
-
throw policyError(`${path} is not a regular file`);
|
|
311
|
-
await fh.truncate(0);
|
|
312
|
-
await fh.writeFile(data);
|
|
313
|
-
}
|
|
314
|
-
finally {
|
|
315
|
-
await fh.close();
|
|
316
|
-
}
|
|
317
|
-
}
|
|
318
|
-
}
|
package/dist/exec/types.d.ts
CHANGED
|
@@ -1,69 +1,5 @@
|
|
|
1
|
-
import type { DeviceErrorKind
|
|
2
|
-
|
|
3
|
-
/** How one command runs: in auto mode (no OS sandbox) or in the sandbox. */
|
|
4
|
-
export interface ExecMode {
|
|
5
|
-
mode: SandboxMode;
|
|
6
|
-
}
|
|
7
|
-
/** Hooks of one command. */
|
|
8
|
-
export interface ExecHooks {
|
|
9
|
-
/**
|
|
10
|
-
* Called synchronously right before the command is spawned, after everything the executor
|
|
11
|
-
* awaits; throwing refuses the command (nothing is spawned) with that error.
|
|
12
|
-
*/
|
|
13
|
-
beforeSpawn?: () => void;
|
|
14
|
-
}
|
|
15
|
-
/** What runs the operations on this machine: the OS sandbox / host (os) or a container (docker). */
|
|
16
|
-
export interface Executor {
|
|
17
|
-
readonly mode: "os" | "docker";
|
|
18
|
-
readonly roots: SandboxRoots;
|
|
19
|
-
/**
|
|
20
|
-
* Runs one command; `signal` aborting kills its whole process tree. An executor must not start
|
|
21
|
-
* work on an already-aborted signal (the kernel cancelled the request). `hooks` are honoured by
|
|
22
|
-
* the executor that runs commands without a sandbox; others may ignore them.
|
|
23
|
-
*/
|
|
24
|
-
exec(args: DeviceExecArgs, signal: AbortSignal, hooks?: ExecHooks): Promise<ExecResult>;
|
|
25
|
-
/** The file's bytes (at most `maxBytes`); null when it does not exist. The switching executor uses this request's mode, defaulting to sandbox. */
|
|
26
|
-
readFile(path: string, maxBytes: number, mode?: SandboxMode): Promise<{
|
|
27
|
-
data: Uint8Array;
|
|
28
|
-
truncated: boolean;
|
|
29
|
-
} | null>;
|
|
30
|
-
writeFile(path: string, data: Uint8Array): Promise<void>;
|
|
31
|
-
/** null when the path does not exist. */
|
|
32
|
-
stat(path: string, mode?: SandboxMode): Promise<{
|
|
33
|
-
size: number;
|
|
34
|
-
isDir: boolean;
|
|
35
|
-
} | null>;
|
|
36
|
-
/**
|
|
37
|
-
* Lists one directory as a device in `mode` reads (`SandboxProvider.list`'s semantics): `mode`
|
|
38
|
-
* is the request's own, `effectiveMode(policy, limits)` on the ceiling that came with it, never
|
|
39
|
-
* the latest command's decision. Auto mode reads with the owner's rights; sandbox mode through
|
|
40
|
-
* the sandboxed helper, the workspace only; a container device its workspace only, in either
|
|
41
|
-
* mode. A path the mode cannot reach throws a `policy` refusal. Works without the device
|
|
42
|
-
* directory (it is not called through `ensureRoot`). Optional: without it (and {@link scan})
|
|
43
|
-
* the device answers `list` and `scan` as unsupported.
|
|
44
|
-
*/
|
|
45
|
-
list?(mode: SandboxMode, path: string, limit: number, signal: AbortSignal): Promise<DeviceListResult>;
|
|
46
|
-
/** Looks for projects under `base` as a device in `mode` reads ({@link list}'s rules). */
|
|
47
|
-
scan?(mode: SandboxMode, base: string, signal: AbortSignal): Promise<DeviceScanResult>;
|
|
48
|
-
killTagged(tags: string[]): Promise<void>;
|
|
49
|
-
killAll(): Promise<void>;
|
|
50
|
-
/**
|
|
51
|
-
* Creates the device directory (and its marker file) on first use. "gone" when it existed
|
|
52
|
-
* before and has vanished; it is never recreated silently.
|
|
53
|
-
*/
|
|
54
|
-
ensureRoot(): Promise<"ok" | "gone">;
|
|
55
|
-
/**
|
|
56
|
-
* OS mode, an executor that can run without a sandbox: records an exec's limits, also of one
|
|
57
|
-
* the policy sent to the sandbox, so file writes follow the latest decision.
|
|
58
|
-
*/
|
|
59
|
-
noteLimits?(limits: DeviceExecArgs["limits"]): void;
|
|
60
|
-
/**
|
|
61
|
-
* OS mode, an executor that can run without a sandbox: runs one command as `how` (decided by
|
|
62
|
-
* the caller on `policy`, and logged by it) says, instead of deciding again in {@link exec}.
|
|
63
|
-
*/
|
|
64
|
-
execDecided?(args: DeviceExecArgs, signal: AbortSignal, how: ExecMode, policy: Policy): Promise<ExecResult>;
|
|
65
|
-
}
|
|
66
|
-
/** An executor failure with a protocol error kind (default `error`). */
|
|
1
|
+
import type { DeviceErrorKind } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
/** A device failure with a protocol error kind (default `error`). */
|
|
67
3
|
export declare class DeviceOpError extends Error {
|
|
68
4
|
readonly kind: DeviceErrorKind;
|
|
69
5
|
constructor(kind: DeviceErrorKind, message: string);
|
package/dist/exec/types.js
CHANGED
|
@@ -1,22 +1,57 @@
|
|
|
1
1
|
diff --git a/dist/sandbox/macos-sandbox-utils.js b/dist/sandbox/macos-sandbox-utils.js
|
|
2
|
-
index 0e598b612d84d24b09ec2ab0d7ccc9b009c9457b..
|
|
2
|
+
index 0e598b612d84d24b09ec2ab0d7ccc9b009c9457b..10c4bd0b6518f6b968a105b0ed70838bbd009da9 100644
|
|
3
3
|
--- a/dist/sandbox/macos-sandbox-utils.js
|
|
4
4
|
+++ b/dist/sandbox/macos-sandbox-utils.js
|
|
5
|
-
@@ -
|
|
5
|
+
@@ -220,6 +220,18 @@ function inBothSpellings(kind, entry) {
|
|
6
|
+
: { glob: false, path: canonical },
|
|
7
|
+
];
|
|
8
|
+
}
|
|
9
|
+
+/**
|
|
10
|
+
+ * capybara patch: the exact read allows, as given. Each must be an absolute, normalized path; it
|
|
11
|
+
+ * becomes a `(literal …)` filter, so a directory's entries can be listed but nothing below it
|
|
12
|
+
+ * is read, and a symbolic link can be followed or read but not its target.
|
|
13
|
+
+ */
|
|
14
|
+
+function exactReadAllows(paths) {
|
|
15
|
+
+ for (const p of paths ?? []) {
|
|
16
|
+
+ if (typeof p !== 'string' || !path.isAbsolute(p) || path.normalize(p) !== p || (p !== '/' && p.endsWith('/')) || p.includes('\0'))
|
|
17
|
+
+ throw new Error(`An exact read allow must be an absolute, normalized path: ${p}`);
|
|
18
|
+
+ }
|
|
19
|
+
+ return [...new Set(paths ?? [])];
|
|
20
|
+
+}
|
|
21
|
+
function resolveReadConfig(config, writeRoots,
|
|
22
|
+
/**
|
|
23
|
+
* Read denies the library resolved itself — the masked credential files,
|
|
24
|
+
@@ -244,6 +256,8 @@ libraryDenies) {
|
|
25
|
+
// the nested-deny re-emit matches by `path + '/'` prefix, which a
|
|
26
|
+
// preserved trailing slash would defeat ('<dir>//').
|
|
27
|
+
allows: callerEntries('allow', config.allowWithinDeny, config.literalAllowWithinDeny).flatMap(entry => inBothSpellings('allow', entry)),
|
|
28
|
+
+ // capybara patch: exact read allows, each one vnode, never the subtree below it
|
|
29
|
+
+ exactAllows: exactReadAllows(config.exactAllowWithinDeny),
|
|
30
|
+
writeRoots: [...writeRoots],
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
@@ -644,6 +658,9 @@ function generateReadRules(resolved, logTag) {
|
|
34
|
+
rules.push(...renderRule('deny', ['file-read*'], denyFilters, logTag));
|
|
35
|
+
// Re-allow specific paths within denied regions (allowWithinDeny takes precedence)
|
|
36
|
+
const allowFilters = new Set(resolved.allows.map(a => pathFilter(a)));
|
|
37
|
+
+ // capybara patch: exact allows join the allow block, so the late denies still win over them
|
|
38
|
+
+ for (const p of resolved.exactAllows ?? [])
|
|
39
|
+
+ allowFilters.add(`(literal ${escapePath(p)})`);
|
|
40
|
+
rules.push(...renderRule('allow', ['file-read*'], allowFilters, logTag));
|
|
41
|
+
// Denies the allow block would otherwise win over (last-match-wins) land
|
|
42
|
+
// here, after it. Must stay ahead of the file-read-metadata allow below.
|
|
43
|
+
@@ -745,6 +762,10 @@ function generateWriteRules(config, logTag, allowGitConfig, writeRoots) {
|
|
6
44
|
}
|
|
7
45
|
}
|
|
8
46
|
rules.push(...renderRule('deny', ['file-write-unlink', 'file-write-create'], moveFilters, logTag));
|
|
9
47
|
+ // capybara patch: ordered raw regex rules, last, so each decides over everything before it
|
|
10
|
-
+ // (raw #"…" strings: SBPL string escapes would change the regex; a quote cannot occur)
|
|
11
48
|
+ for (const rule of config.regexRules ?? []) {
|
|
12
|
-
+
|
|
13
|
-
+ throw new Error('A raw regex write rule cannot contain a double quote');
|
|
14
|
-
+ rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex #"${rule.regex}")`]), logTag));
|
|
49
|
+
+ rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex ${escapePath(rule.regex)})`]), logTag));
|
|
15
50
|
+ }
|
|
16
51
|
return rules;
|
|
17
52
|
}
|
|
18
53
|
/**
|
|
19
|
-
@@ -851,6 +
|
|
54
|
+
@@ -851,6 +872,8 @@ function generateSandboxProfile({ readConfig, libraryDenyEntries, writeConfig, h
|
|
20
55
|
' (sysctl-name "hw.logicalcpu")',
|
|
21
56
|
' (sysctl-name "hw.logicalcpu_max")',
|
|
22
57
|
' (sysctl-name "hw.machine")',
|
|
@@ -26,13 +61,19 @@ index 0e598b612d84d24b09ec2ab0d7ccc9b009c9457b..42f25ad99eb58d1024aa58f9b4a96d99
|
|
|
26
61
|
' (sysctl-name "hw.ncpu")',
|
|
27
62
|
' (sysctl-name "hw.nperflevels")',
|
|
28
63
|
diff --git a/dist/sandbox/sandbox-config.js b/dist/sandbox/sandbox-config.js
|
|
29
|
-
index 76b00b1dc82a2d42a451a9f58068cbbd5e68da75..
|
|
64
|
+
index 76b00b1dc82a2d42a451a9f58068cbbd5e68da75..25ea77fe4259ddeb8578262fffd2021c7c06aa0d 100644
|
|
30
65
|
--- a/dist/sandbox/sandbox-config.js
|
|
31
66
|
+++ b/dist/sandbox/sandbox-config.js
|
|
32
|
-
@@ -832,6 +832,
|
|
67
|
+
@@ -832,6 +832,22 @@ export const FilesystemConfigSchema = z.object({
|
|
33
68
|
.boolean()
|
|
34
69
|
.optional()
|
|
35
70
|
.describe('Allow writes to .git/config files (default: false). Enables git remote URL updates while keeping .git/hooks protected.'),
|
|
71
|
+
+ // capybara patch: exact read allows (macOS): absolute paths emitted as (literal …), never
|
|
72
|
+
+ // (subpath …), for directories whose entries a command may list or links it may follow
|
|
73
|
+
+ allowReadExact: z
|
|
74
|
+
+ .array(z.string())
|
|
75
|
+
+ .optional()
|
|
76
|
+
+ .describe('macOS only: absolute paths re-allowed for reading as exactly that path, not its subtree'),
|
|
36
77
|
+ // capybara patch: ordered raw SBPL regex write rules (macOS), emitted after every other
|
|
37
78
|
+ // write rule so they decide last (Seatbelt is last-match-wins for the same operations)
|
|
38
79
|
+ writeRegexRules: z
|
|
@@ -47,10 +88,19 @@ index 76b00b1dc82a2d42a451a9f58068cbbd5e68da75..784dac7f685068a85c3f95f9fe472dac
|
|
|
47
88
|
/**
|
|
48
89
|
* Configuration schema for ignoring specific sandbox violations
|
|
49
90
|
diff --git a/dist/sandbox/sandbox-manager.js b/dist/sandbox/sandbox-manager.js
|
|
50
|
-
index d475e55977bf54a2fe00a0c6aba38313761d55aa..
|
|
91
|
+
index d475e55977bf54a2fe00a0c6aba38313761d55aa..d60dab574bca5a1071e55dae7c597c6a2c86a4a6 100644
|
|
51
92
|
--- a/dist/sandbox/sandbox-manager.js
|
|
52
93
|
+++ b/dist/sandbox/sandbox-manager.js
|
|
53
|
-
@@ -
|
|
94
|
+
@@ -1493,6 +1493,8 @@ function getFsReadConfig() {
|
|
95
|
+
allowWithinDeny: allowPaths,
|
|
96
|
+
unlistableDenyDirs: [...unlistableDenyDirs],
|
|
97
|
+
...literalReadLists(config.filesystem.denyRead, config.filesystem.allowRead),
|
|
98
|
+
+ // capybara patch: exact read allows (macOS)
|
|
99
|
+
+ exactAllowWithinDeny: config.filesystem.allowReadExact ?? [],
|
|
100
|
+
};
|
|
101
|
+
}
|
|
102
|
+
function getFsWriteConfig() {
|
|
103
|
+
@@ -1516,6 +1518,8 @@ function getFsWriteConfig() {
|
|
54
104
|
allowOnly,
|
|
55
105
|
denyWithinAllow: denyPaths,
|
|
56
106
|
...literalWriteLists(config.filesystem.allowWrite, config.filesystem.denyWrite),
|
|
@@ -59,7 +109,7 @@ index d475e55977bf54a2fe00a0c6aba38313761d55aa..a9a1d4b42f983adabdbc3659b1910b3f
|
|
|
59
109
|
};
|
|
60
110
|
}
|
|
61
111
|
/**
|
|
62
|
-
@@ -1866,6 +
|
|
112
|
+
@@ -1866,6 +1870,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
|
|
63
113
|
config?.filesystem.denyWrite ??
|
|
64
114
|
[]),
|
|
65
115
|
...literalWriteLists(customConfig?.filesystem?.allowWrite ?? config?.filesystem.allowWrite, customConfig?.filesystem?.denyWrite ?? config?.filesystem.denyWrite),
|
|
@@ -68,3 +118,12 @@ index d475e55977bf54a2fe00a0c6aba38313761d55aa..a9a1d4b42f983adabdbc3659b1910b3f
|
|
|
68
118
|
};
|
|
69
119
|
// For a caller that never reads checkDependencies(), the CLI among them.
|
|
70
120
|
if (!ownInstallLogged) {
|
|
121
|
+
@@ -1917,6 +1923,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
|
|
122
|
+
...(ownAllowWithinDeny.length > 0 && { ownAllowWithinDeny }),
|
|
123
|
+
unlistableDenyDirs: [...unlistableDenyDirs],
|
|
124
|
+
...literalReadLists(customConfig?.filesystem?.denyRead ?? config?.filesystem.denyRead, customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead),
|
|
125
|
+
+ // capybara patch: exact read allows (macOS)
|
|
126
|
+
+ exactAllowWithinDeny: customConfig?.filesystem?.allowReadExact ?? config?.filesystem.allowReadExact ?? [],
|
|
127
|
+
};
|
|
128
|
+
}
|
|
129
|
+
// Nothing below walks, and what it waits for is not this thread.
|
|
@@ -220,6 +220,18 @@ function inBothSpellings(kind, entry) {
|
|
|
220
220
|
: { glob: false, path: canonical },
|
|
221
221
|
];
|
|
222
222
|
}
|
|
223
|
+
/**
|
|
224
|
+
* capybara patch: the exact read allows, as given. Each must be an absolute, normalized path; it
|
|
225
|
+
* becomes a `(literal …)` filter, so a directory's entries can be listed but nothing below it
|
|
226
|
+
* is read, and a symbolic link can be followed or read but not its target.
|
|
227
|
+
*/
|
|
228
|
+
function exactReadAllows(paths) {
|
|
229
|
+
for (const p of paths ?? []) {
|
|
230
|
+
if (typeof p !== 'string' || !path.isAbsolute(p) || path.normalize(p) !== p || (p !== '/' && p.endsWith('/')) || p.includes('\0'))
|
|
231
|
+
throw new Error(`An exact read allow must be an absolute, normalized path: ${p}`);
|
|
232
|
+
}
|
|
233
|
+
return [...new Set(paths ?? [])];
|
|
234
|
+
}
|
|
223
235
|
function resolveReadConfig(config, writeRoots,
|
|
224
236
|
/**
|
|
225
237
|
* Read denies the library resolved itself — the masked credential files,
|
|
@@ -244,6 +256,8 @@ libraryDenies) {
|
|
|
244
256
|
// the nested-deny re-emit matches by `path + '/'` prefix, which a
|
|
245
257
|
// preserved trailing slash would defeat ('<dir>//').
|
|
246
258
|
allows: callerEntries('allow', config.allowWithinDeny, config.literalAllowWithinDeny).flatMap(entry => inBothSpellings('allow', entry)),
|
|
259
|
+
// capybara patch: exact read allows, each one vnode, never the subtree below it
|
|
260
|
+
exactAllows: exactReadAllows(config.exactAllowWithinDeny),
|
|
247
261
|
writeRoots: [...writeRoots],
|
|
248
262
|
};
|
|
249
263
|
}
|
|
@@ -644,6 +658,9 @@ function generateReadRules(resolved, logTag) {
|
|
|
644
658
|
rules.push(...renderRule('deny', ['file-read*'], denyFilters, logTag));
|
|
645
659
|
// Re-allow specific paths within denied regions (allowWithinDeny takes precedence)
|
|
646
660
|
const allowFilters = new Set(resolved.allows.map(a => pathFilter(a)));
|
|
661
|
+
// capybara patch: exact allows join the allow block, so the late denies still win over them
|
|
662
|
+
for (const p of resolved.exactAllows ?? [])
|
|
663
|
+
allowFilters.add(`(literal ${escapePath(p)})`);
|
|
647
664
|
rules.push(...renderRule('allow', ['file-read*'], allowFilters, logTag));
|
|
648
665
|
// Denies the allow block would otherwise win over (last-match-wins) land
|
|
649
666
|
// here, after it. Must stay ahead of the file-read-metadata allow below.
|
|
@@ -746,11 +763,8 @@ function generateWriteRules(config, logTag, allowGitConfig, writeRoots) {
|
|
|
746
763
|
}
|
|
747
764
|
rules.push(...renderRule('deny', ['file-write-unlink', 'file-write-create'], moveFilters, logTag));
|
|
748
765
|
// capybara patch: ordered raw regex rules, last, so each decides over everything before it
|
|
749
|
-
// (raw #"…" strings: SBPL string escapes would change the regex; a quote cannot occur)
|
|
750
766
|
for (const rule of config.regexRules ?? []) {
|
|
751
|
-
|
|
752
|
-
throw new Error('A raw regex write rule cannot contain a double quote');
|
|
753
|
-
rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex #"${rule.regex}")`]), logTag));
|
|
767
|
+
rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex ${escapePath(rule.regex)})`]), logTag));
|
|
754
768
|
}
|
|
755
769
|
return rules;
|
|
756
770
|
}
|
|
@@ -832,6 +832,12 @@ export const FilesystemConfigSchema = z.object({
|
|
|
832
832
|
.boolean()
|
|
833
833
|
.optional()
|
|
834
834
|
.describe('Allow writes to .git/config files (default: false). Enables git remote URL updates while keeping .git/hooks protected.'),
|
|
835
|
+
// capybara patch: exact read allows (macOS): absolute paths emitted as (literal …), never
|
|
836
|
+
// (subpath …), for directories whose entries a command may list or links it may follow
|
|
837
|
+
allowReadExact: z
|
|
838
|
+
.array(z.string())
|
|
839
|
+
.optional()
|
|
840
|
+
.describe('macOS only: absolute paths re-allowed for reading as exactly that path, not its subtree'),
|
|
835
841
|
// capybara patch: ordered raw SBPL regex write rules (macOS), emitted after every other
|
|
836
842
|
// write rule so they decide last (Seatbelt is last-match-wins for the same operations)
|
|
837
843
|
writeRegexRules: z
|
|
@@ -1493,6 +1493,8 @@ function getFsReadConfig() {
|
|
|
1493
1493
|
allowWithinDeny: allowPaths,
|
|
1494
1494
|
unlistableDenyDirs: [...unlistableDenyDirs],
|
|
1495
1495
|
...literalReadLists(config.filesystem.denyRead, config.filesystem.allowRead),
|
|
1496
|
+
// capybara patch: exact read allows (macOS)
|
|
1497
|
+
exactAllowWithinDeny: config.filesystem.allowReadExact ?? [],
|
|
1496
1498
|
};
|
|
1497
1499
|
}
|
|
1498
1500
|
function getFsWriteConfig() {
|
|
@@ -1921,6 +1923,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
|
|
|
1921
1923
|
...(ownAllowWithinDeny.length > 0 && { ownAllowWithinDeny }),
|
|
1922
1924
|
unlistableDenyDirs: [...unlistableDenyDirs],
|
|
1923
1925
|
...literalReadLists(customConfig?.filesystem?.denyRead ?? config?.filesystem.denyRead, customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead),
|
|
1926
|
+
// capybara patch: exact read allows (macOS)
|
|
1927
|
+
exactAllowWithinDeny: customConfig?.filesystem?.allowReadExact ?? config?.filesystem.allowReadExact ?? [],
|
|
1924
1928
|
};
|
|
1925
1929
|
}
|
|
1926
1930
|
// Nothing below walks, and what it waits for is not this thread.
|
|
@@ -52,10 +52,15 @@ When a person cannot do something themselves (install a plugin that is not on in
|
|
|
52
52
|
approve extension permissions), they file a **request**. Org admins or the super admin decide it
|
|
53
53
|
on the web. Agents can file requests but never decide them.
|
|
54
54
|
|
|
55
|
-
##
|
|
56
|
-
|
|
57
|
-
Agents run commands and keep files
|
|
58
|
-
|
|
55
|
+
## Devices
|
|
56
|
+
|
|
57
|
+
Agents run commands and keep files on a **device**: one instance plus a file system that is kept
|
|
58
|
+
until the device is deleted. A device is a cloud sandbox (from the deployment's sandbox provider)
|
|
59
|
+
or a machine connected with `capybara-device`, and the conversations that use it share its files.
|
|
60
|
+
A device runs in one of two modes: auto (the environment's own capability) or sandbox (an OS
|
|
61
|
+
sandbox with an allowlist network). Skill files are read-only in the device's skills directory;
|
|
62
|
+
each conversation is told the device's directories, mode and network. Sandbox limits and the
|
|
63
|
+
cloud network are set per org by admins.
|
|
59
64
|
|
|
60
65
|
## What agents may not do
|
|
61
66
|
|
|
@@ -10,6 +10,6 @@
|
|
|
10
10
|
|
|
11
11
|
Contract: Channel (`channel.ts`)
|
|
12
12
|
|
|
13
|
-
Normalize inbound events (messageId, threadId, tenantId, the bot mention stripped) and acknowledge only after the kernel's `onEvent` resolves. Long connections are held only by the gateway role. Replies use the card spec (`validateChannelCard`).
|
|
13
|
+
Normalize inbound events (messageId, threadId, tenantId, the bot mention stripped) and acknowledge only after the kernel's `onEvent` resolves. Long connections are held only by the gateway role. Replies use the card spec (`validateChannelCard`). Files: implement the optional `sendFile` and declare `features.files` (the platform's bot limits); the kernel sends each conversation artifact as one message and falls back to a link line without it.
|
|
14
14
|
|
|
15
15
|
See `extensions` for the rules every extension follows.
|
package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md
CHANGED
|
@@ -12,4 +12,6 @@ Contract: FilePreviewProvider (`file-preview.ts`)
|
|
|
12
12
|
|
|
13
13
|
Declare which file types you can preview and render them through schema views or an approved embed. Enabled per org.
|
|
14
14
|
|
|
15
|
+
`render` args are a union on `source`: `"conversation"` (org, account, conversation) or `"share"` (org and share id; `file.id` is the share id; no account or conversation). A previewer that needs the conversation declines `source: "share"` by throwing; the kernel reports the failure and the share page falls to the next previewer. A share token is valid only for the `file.preview` slot, never for `/api`.
|
|
16
|
+
|
|
15
17
|
See `extensions` for the rules every extension follows.
|
|
@@ -10,6 +10,6 @@
|
|
|
10
10
|
|
|
11
11
|
Contract: SandboxProvider (`sandbox.ts`)
|
|
12
12
|
|
|
13
|
-
The kernel accepts only `sandbox@2`. A device is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours.
|
|
13
|
+
The kernel accepts only `sandbox@2`. A device is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours.
|
|
14
14
|
|
|
15
15
|
See `extensions` for the rules every extension follows.
|
|
@@ -59,7 +59,7 @@ Rules that the schema cannot show:
|
|
|
59
59
|
by `parseThemeFile` (schema `https://capybarahq.com/schemas/theme.v1.schema.json`).
|
|
60
60
|
- `setupGuides` (at most 8): `{ id, place, template? }`. Each guide is a Markdown document at
|
|
61
61
|
`guides/<id>.md` (English, required) and `guides/<id>.zh.md` (Chinese, optional), shown where a
|
|
62
|
-
person sets up what the plugin brings. `place` is `channel-connection` (
|
|
62
|
+
person sets up what the plugin brings. `place` is `channel-connection` (New channel and the channel
|
|
63
63
|
detail; the extension must provide `channel@1`; one per plugin) or `connector-template`
|
|
64
64
|
(`template` names one of the plugin's `connectors/<id>.json`; one per template). See "Setup
|
|
65
65
|
guides" below.
|
|
@@ -91,6 +91,17 @@ export declare function questionRenderableInline(form: InputForm, opts?: {
|
|
|
91
91
|
export declare function validateChannelCard(card: unknown): string[];
|
|
92
92
|
/** A UI locale. */
|
|
93
93
|
export type Locale = "zh" | "en";
|
|
94
|
+
/**
|
|
95
|
+
* Puts model-controllable values (approval title, call summary, question title, answer summary)
|
|
96
|
+
* into code, so that in the fallback text they do not turn into links, emphasis or HTML:
|
|
97
|
+
* single-line values use inline code, multi-line values a fenced code block (starting with a
|
|
98
|
+
* newline); the delimiters are always longer than the longest backtick run in the value (CommonMark
|
|
99
|
+
* 6.1 / 4.5).
|
|
100
|
+
* Code is chosen over backslash-escaping punctuation because code is the only form CommonMark / GFM
|
|
101
|
+
* guarantee to display content verbatim (a backslash does not stop GFM bare-URL
|
|
102
|
+
* autolinks, and channel converters treat backslashes inconsistently).
|
|
103
|
+
*/
|
|
104
|
+
export declare function asCode(s: string): string;
|
|
94
105
|
/** The hint line of a pending question card with `textReply`, as {@link renderCardAsText} writes it. */
|
|
95
106
|
export declare function questionTextReplyHint(mode: "plain" | "mention", locale: Locale): string;
|
|
96
107
|
/**
|
|
@@ -125,7 +125,7 @@ export function validateChannelCard(card) {
|
|
|
125
125
|
* guarantee to display content verbatim (a backslash does not stop GFM bare-URL
|
|
126
126
|
* autolinks, and channel converters treat backslashes inconsistently).
|
|
127
127
|
*/
|
|
128
|
-
function asCode(s) {
|
|
128
|
+
export function asCode(s) {
|
|
129
129
|
const v = s.replace(/\r\n?/g, "\n");
|
|
130
130
|
const longest = Math.max(0, ...[...v.matchAll(/`+/g)].map((m) => m[0].length));
|
|
131
131
|
if (v.includes("\n")) {
|