@pmndre/pine 0.0.0-stage → 0.22.0

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 (151) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -2
  3. package/bin/pine.js +27 -0
  4. package/docs/SKILL.md +234 -0
  5. package/docs/references/agents.md +454 -0
  6. package/docs/references/coding.md +311 -0
  7. package/docs/references/computer.md +212 -0
  8. package/docs/references/configuration.md +310 -0
  9. package/docs/references/events.md +267 -0
  10. package/docs/references/mcp.md +420 -0
  11. package/docs/references/operations.md +394 -0
  12. package/docs/references/overview.md +195 -0
  13. package/docs/references/security.md +896 -0
  14. package/docs/references/setup.md +385 -0
  15. package/docs/references/sources.md +772 -0
  16. package/docs/references/stack.md +121 -0
  17. package/docs/references/tui.md +575 -0
  18. package/examples/home/.env.example +7 -0
  19. package/examples/home/USER.md +4 -0
  20. package/examples/home/agents/main/agent.json +4 -0
  21. package/examples/home/agents/main/workspace/AGENTS.md +14 -0
  22. package/examples/home/agents/main/workspace/MEMORY.md +4 -0
  23. package/examples/home/agents/main/workspace/SOUL.md +4 -0
  24. package/examples/home/models.json +62 -0
  25. package/examples/home/pine.json +34 -0
  26. package/examples/home/skills/README.txt +7 -0
  27. package/examples/launchd/com.pine.daemon.plist +32 -0
  28. package/examples/systemd/pine.service +22 -0
  29. package/mcp/browser.d.ts +99 -0
  30. package/mcp/browser.js +496 -0
  31. package/mcp/commands.d.ts +20 -0
  32. package/mcp/commands.js +88 -0
  33. package/mcp/computer.d.ts +139 -0
  34. package/mcp/computer.js +698 -0
  35. package/mcp/computer.swift +989 -0
  36. package/mcp/lib.d.ts +23 -0
  37. package/mcp/lib.js +52 -0
  38. package/mcp/web.d.ts +6 -0
  39. package/mcp/web.js +140 -0
  40. package/package.json +32 -4
  41. package/src/access.d.ts +112 -0
  42. package/src/access.js +438 -0
  43. package/src/actions.d.ts +75 -0
  44. package/src/actions.js +167 -0
  45. package/src/admin.d.ts +167 -0
  46. package/src/admin.js +625 -0
  47. package/src/agent-admin.d.ts +24 -0
  48. package/src/agent-admin.js +55 -0
  49. package/src/agents.d.ts +540 -0
  50. package/src/agents.js +2776 -0
  51. package/src/background.d.ts +29 -0
  52. package/src/background.js +100 -0
  53. package/src/cli.d.ts +2 -0
  54. package/src/cli.js +777 -0
  55. package/src/computer.d.ts +30 -0
  56. package/src/computer.js +32 -0
  57. package/src/config.d.ts +396 -0
  58. package/src/config.js +549 -0
  59. package/src/dev/claude-model.d.ts +37 -0
  60. package/src/dev/claude-model.js +204 -0
  61. package/src/env-file.d.ts +4 -0
  62. package/src/env-file.js +40 -0
  63. package/src/goals.d.ts +133 -0
  64. package/src/goals.js +316 -0
  65. package/src/http.d.ts +46 -0
  66. package/src/http.js +509 -0
  67. package/src/limiter.d.ts +32 -0
  68. package/src/limiter.js +84 -0
  69. package/src/login.d.ts +23 -0
  70. package/src/login.js +130 -0
  71. package/src/manual.d.ts +61 -0
  72. package/src/manual.js +443 -0
  73. package/src/mcp-config.d.ts +49 -0
  74. package/src/mcp-config.js +182 -0
  75. package/src/models.d.ts +90 -0
  76. package/src/models.js +274 -0
  77. package/src/net.d.ts +50 -0
  78. package/src/net.js +150 -0
  79. package/src/pine.d.ts +32 -0
  80. package/src/pine.js +134 -0
  81. package/src/programs.d.ts +123 -0
  82. package/src/programs.js +412 -0
  83. package/src/router.d.ts +56 -0
  84. package/src/router.js +164 -0
  85. package/src/sandbox-fs.d.ts +34 -0
  86. package/src/sandbox-fs.js +186 -0
  87. package/src/sandbox-linux.d.ts +96 -0
  88. package/src/sandbox-linux.js +297 -0
  89. package/src/sandbox-setup.d.ts +70 -0
  90. package/src/sandbox-setup.js +216 -0
  91. package/src/security.d.ts +238 -0
  92. package/src/security.js +660 -0
  93. package/src/skills.d.ts +67 -0
  94. package/src/skills.js +163 -0
  95. package/src/snapshots.d.ts +68 -0
  96. package/src/snapshots.js +306 -0
  97. package/src/source-types.d.ts +61 -0
  98. package/src/source-types.js +1 -0
  99. package/src/sources/command.d.ts +4 -0
  100. package/src/sources/command.js +77 -0
  101. package/src/sources/folder.d.ts +6 -0
  102. package/src/sources/folder.js +116 -0
  103. package/src/sources/ftp.d.ts +4 -0
  104. package/src/sources/ftp.js +307 -0
  105. package/src/sources/http.d.ts +4 -0
  106. package/src/sources/http.js +201 -0
  107. package/src/sources/mqtt.d.ts +18 -0
  108. package/src/sources/mqtt.js +97 -0
  109. package/src/sources/telegram.d.ts +22 -0
  110. package/src/sources/telegram.js +283 -0
  111. package/src/sources/webhook.d.ts +4 -0
  112. package/src/sources/webhook.js +52 -0
  113. package/src/sources.d.ts +344 -0
  114. package/src/sources.js +966 -0
  115. package/src/store.d.ts +99 -0
  116. package/src/store.js +277 -0
  117. package/src/timers.d.ts +83 -0
  118. package/src/timers.js +318 -0
  119. package/src/tools.d.ts +11 -0
  120. package/src/tools.js +1297 -0
  121. package/src/tui/app.d.ts +305 -0
  122. package/src/tui/app.js +3195 -0
  123. package/src/tui/client.d.ts +236 -0
  124. package/src/tui/client.js +131 -0
  125. package/src/tui/code-pane.d.ts +68 -0
  126. package/src/tui/code-pane.js +535 -0
  127. package/src/tui/highlight.d.ts +8 -0
  128. package/src/tui/highlight.js +86 -0
  129. package/src/tui/picture.d.ts +206 -0
  130. package/src/tui/picture.js +801 -0
  131. package/src/tui/run.d.ts +8 -0
  132. package/src/tui/run.js +97 -0
  133. package/src/tui/theme.d.ts +32 -0
  134. package/src/tui/theme.js +128 -0
  135. package/src/tui/undo.d.ts +5 -0
  136. package/src/tui/undo.js +50 -0
  137. package/src/tui/voice.d.ts +49 -0
  138. package/src/tui/voice.js +155 -0
  139. package/src/tui/voice.swift +223 -0
  140. package/src/types.d.ts +139 -0
  141. package/src/types.js +1 -0
  142. package/src/undo.d.ts +224 -0
  143. package/src/undo.js +465 -0
  144. package/src/update.d.ts +35 -0
  145. package/src/update.js +130 -0
  146. package/src/util.d.ts +65 -0
  147. package/src/util.js +171 -0
  148. package/src/watching.d.ts +20 -0
  149. package/src/watching.js +68 -0
  150. package/src/workspace-view.d.ts +72 -0
  151. package/src/workspace-view.js +221 -0
@@ -0,0 +1,216 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import fs from "node:fs";
3
+ import { createRequire } from "node:module";
4
+ import os from "node:os";
5
+ import path from "node:path";
6
+ import { containerFlags, inContainer, sandboxFound, sandboxMissing, sandboxRecheck } from "./security.js";
7
+ export const PROFILE_FILE = "/etc/apparmor.d/bwrap";
8
+ /** The rule that lets bubblewrap make the user namespaces its sandboxes consist of. */
9
+ export const profileFor = (bwrap) => `# Written by pine init. It lets bubblewrap, which pine's sandbox is built on, create user namespaces.
10
+ abi <abi/4.0>,
11
+ include <tunables/global>
12
+
13
+ profile bwrap ${bwrap} flags=(unconfined) {
14
+ userns,
15
+ }
16
+ `;
17
+ const INSTALL = [
18
+ ["apt-get", ["apt-get", "install", "-y", "bubblewrap"]],
19
+ ["dnf", ["dnf", "install", "-y", "bubblewrap"]],
20
+ ["yum", ["yum", "install", "-y", "bubblewrap"]],
21
+ ["pacman", ["pacman", "-S", "--noconfirm", "--needed", "bubblewrap"]],
22
+ ["zypper", ["zypper", "--non-interactive", "install", "bubblewrap"]],
23
+ ["apk", ["apk", "add", "bubblewrap"]],
24
+ ];
25
+ const boxed = (root) => `This is a container that was started without the rights a sandbox needs, and they cannot be given from inside. pine works here all the same: agents whose mode you did not choose work in auto mode, and the container is the wall around them. To have safe mode in a container, start it with:\n docker run ${containerFlags(root)} ...`;
26
+ /** What has to be done on this machine for the sandbox to work. */
27
+ export function sandboxPlan(m) {
28
+ if (m.works)
29
+ return { ok: true, why: "", steps: [] };
30
+ const steps = [];
31
+ const missing = [];
32
+ let cannot;
33
+ if (!m.bwrap) {
34
+ missing.push("bubblewrap is not installed");
35
+ const manager = INSTALL.find(([program]) => m.has(program));
36
+ if (!manager)
37
+ cannot = "pine does not know this system's package manager. Install the package bubblewrap (the program is bwrap), then run pine init again.";
38
+ else {
39
+ if (manager[0] === "apt-get" && m.aptEmpty)
40
+ steps.push({ says: "fetch the list of packages", argv: ["apt-get", "update"] });
41
+ steps.push({ says: "install bubblewrap", argv: manager[1] });
42
+ }
43
+ }
44
+ // AppArmor belongs to the host: inside a container there is nothing to load a rule into.
45
+ if (m.apparmor && !m.container) {
46
+ missing.push(m.bwrap ? "AppArmor keeps bubblewrap from making a sandbox" : "this system also needs an AppArmor rule for it");
47
+ if (!m.has("apparmor_parser"))
48
+ cannot ??= `AppArmor restricts user namespaces here, and apparmor_parser, which loads a rule that allows them, is missing. Install the package apparmor, then run pine init again.`;
49
+ else {
50
+ if (!m.profile)
51
+ steps.push({ says: `write ${PROFILE_FILE}, the rule that lets bubblewrap make sandboxes`, argv: ["install", "-m", "0644", "{file}", PROFILE_FILE], content: profileFor(m.bwrap ?? "/usr/bin/bwrap") });
52
+ steps.push({ says: "load that rule", argv: ["apparmor_parser", "-r", PROFILE_FILE] });
53
+ }
54
+ }
55
+ else if (m.bwrap) {
56
+ // It is installed and nothing pine can change stands in its way.
57
+ missing.push(`bubblewrap cannot make a sandbox here${m.said ? ` ("${m.said}")` : ""}`);
58
+ cannot = m.container ? boxed(m.root) : "Ordinary users may not create user namespaces on this system. Its administrator can allow them (often: sysctl kernel.unprivileged_userns_clone=1).";
59
+ }
60
+ if (!cannot && steps.length && !m.root && !m.has("sudo"))
61
+ cannot = `This needs an administrator, and there is no sudo here. As root, run:\n${steps.map((s) => ` ${shown(s)}`).join("\n")}`;
62
+ return { ok: false, why: missing.join("; "), steps: cannot ? [] : steps, cannot };
63
+ }
64
+ /**
65
+ * What the browser needs, when it lacks system libraries. Playwright, whose browser it is, knows
66
+ * the packages; it installs them with apt, so only where apt is.
67
+ */
68
+ export function browserPlan(m, cli = playwrightCli()) {
69
+ if (!m.browserLacks.length)
70
+ return undefined;
71
+ const lacks = `${m.browserLacks.length} system ${m.browserLacks.length === 1 ? "library" : "libraries"} (${m.browserLacks.slice(0, 4).join(", ")}${m.browserLacks.length > 4 ? ", ..." : ""})`;
72
+ if (!m.has("apt-get"))
73
+ return { cannot: `The browser the web tools drive lacks ${lacks}. pine installs them only where apt is; here they come from this system's package manager. Web search and page reading work without the browser.` };
74
+ if (!m.root && !m.has("sudo"))
75
+ return { cannot: `The browser the web tools drive lacks ${lacks}, and installing them needs an administrator. As root: npx playwright install-deps chromium` };
76
+ return { step: { says: `install the ${lacks} the browser of the web tools lacks (apt-get, through Playwright)`, argv: [process.execPath, cli, "install-deps", "chromium"], elevates: true } };
77
+ }
78
+ /** Playwright's own command, of the copy pine ships with. */
79
+ function playwrightCli() {
80
+ return path.join(path.dirname(createRequire(import.meta.url).resolve("playwright-core")), "cli.js");
81
+ }
82
+ /** A step as the owner reads it. */
83
+ export const shown = (step, root = true) => (step.content || step.elevates ? step.says : `${root ? "" : "sudo "}${step.argv.join(" ")}`);
84
+ /** The libraries the downloaded browser does not find, by what the system's loader says. */
85
+ function browserLacks() {
86
+ const dir = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(os.homedir(), ".cache", "ms-playwright");
87
+ const programs = [];
88
+ const visit = (d, depth) => {
89
+ let entries = [];
90
+ try {
91
+ entries = fs.readdirSync(d, { withFileTypes: true });
92
+ }
93
+ catch {
94
+ return;
95
+ }
96
+ for (const e of entries) {
97
+ if (e.isDirectory() && depth < 2 && (depth > 0 || e.name.startsWith("chromium")))
98
+ visit(path.join(d, e.name), depth + 1);
99
+ else if (e.isFile() && ["chrome", "chrome-headless-shell", "headless_shell"].includes(e.name))
100
+ programs.push(path.join(d, e.name));
101
+ }
102
+ };
103
+ visit(dir, 0);
104
+ const lacks = new Set();
105
+ for (const program of programs) {
106
+ const out = spawnSync("ldd", [program], { encoding: "utf8", timeout: 10_000 }).stdout ?? "";
107
+ for (const m of out.matchAll(/^\s*(\S+) => not found/gm))
108
+ lacks.add(m[1]);
109
+ }
110
+ return [...lacks].sort();
111
+ }
112
+ /** This machine, looked at. */
113
+ export function lookAtMachine() {
114
+ sandboxRecheck();
115
+ const found = sandboxFound();
116
+ const dirs = [...new Set([...(process.env.PATH ?? "").split(":").filter((d) => path.isAbsolute(d)), "/usr/sbin", "/usr/bin", "/sbin", "/bin", "/usr/local/bin"])];
117
+ const reads = (file) => {
118
+ try {
119
+ return fs.readFileSync(file, "utf8");
120
+ }
121
+ catch {
122
+ return "";
123
+ }
124
+ };
125
+ return {
126
+ bwrap: found.bwrap || undefined,
127
+ works: found.works,
128
+ said: found.said || undefined,
129
+ apparmor: reads("/proc/sys/kernel/apparmor_restrict_unprivileged_userns").trim() === "1",
130
+ profile: fs.existsSync(PROFILE_FILE),
131
+ has: (program) => dirs.some((d) => fs.existsSync(path.join(d, program))),
132
+ root: process.getuid?.() === 0,
133
+ container: inContainer(),
134
+ browserLacks: browserLacks(),
135
+ aptEmpty: !(() => {
136
+ try {
137
+ return fs.readdirSync("/var/lib/apt/lists").some((f) => f.endsWith("_Packages") || f.endsWith("_Packages.lz4"));
138
+ }
139
+ catch {
140
+ return false;
141
+ }
142
+ })(),
143
+ };
144
+ }
145
+ /** Run a step as an administrator. sudo asks for the password itself; pine never sees it. */
146
+ function runStep(step, root) {
147
+ let dir;
148
+ try {
149
+ let argv = step.argv;
150
+ if (step.content !== undefined) {
151
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), "pine-setup-"));
152
+ const file = path.join(dir, "file");
153
+ fs.writeFileSync(file, step.content, { mode: 0o644 });
154
+ argv = argv.map((a) => (a === "{file}" ? file : a));
155
+ }
156
+ const full = root || step.elevates ? argv : ["sudo", ...argv];
157
+ return spawnSync(full[0], full.slice(1), { stdio: "inherit" }).status ?? 1;
158
+ }
159
+ finally {
160
+ if (dir)
161
+ fs.rmSync(dir, { recursive: true, force: true });
162
+ }
163
+ }
164
+ /**
165
+ * Make the sandbox work on this Linux machine and give the browser its libraries, or say
166
+ * plainly why not. Returns whether the sandbox works afterwards. pine runs either way; without
167
+ * a sandbox agents get no shell.
168
+ */
169
+ export async function setUpSandbox(io) {
170
+ const look = io.machine ?? lookAtMachine;
171
+ const run = io.run ?? runStep;
172
+ const machine = look();
173
+ const plan = sandboxPlan(machine);
174
+ const web = browserPlan(machine);
175
+ if (plan.ok && !web) {
176
+ io.out("\nThe sandbox agents run their commands in works.");
177
+ return true;
178
+ }
179
+ const noShell = "Until then pine runs, but agents get no shell.";
180
+ io.out(plan.ok ? "\nThe sandbox agents run their commands in works." : `\nThe sandbox agents run their commands in does not work yet: ${plan.why}.`);
181
+ if (plan.cannot)
182
+ io.out(`${plan.cannot}\n${noShell}`);
183
+ if (web?.cannot)
184
+ io.out(web.cannot);
185
+ const steps = [...plan.steps, ...(web?.step ? [web.step] : [])];
186
+ if (!steps.length)
187
+ return plan.ok;
188
+ if (web?.step)
189
+ io.out("The browser the web tools drive cannot start yet: it lacks system libraries.");
190
+ io.out(`pine can set ${steps.length === 1 ? "this" : "it"} up. It would ${machine.root ? "run" : "run as administrator (sudo asks for your password)"}:\n${steps.map((s) => ` ${shown(s, machine.root)}`).join("\n")}`);
191
+ const go = io.yes ? true : await io.confirm("Set it up now?");
192
+ if (!go) {
193
+ io.out(`${go === undefined ? "Nobody is here to say yes" : "Not set up"}. Run "pine init --yes" to do it, or pine init again in a terminal.${plan.ok ? "" : ` ${noShell}`}`);
194
+ return plan.ok;
195
+ }
196
+ for (const step of steps) {
197
+ const status = run(step, machine.root);
198
+ if (status !== 0) {
199
+ io.out(`\nThat did not work (${shown(step, machine.root)} ended with ${status}). Nothing else was changed.${plan.ok ? "" : ` ${noShell}`}`);
200
+ return plan.ok;
201
+ }
202
+ }
203
+ const after = look();
204
+ if (web?.step)
205
+ io.out(after.browserLacks.length ? `The browser still lacks ${after.browserLacks.join(", ")}.` : "The browser has what it needs now.");
206
+ if (plan.ok)
207
+ return true;
208
+ if (after.works) {
209
+ io.out("The sandbox works now.");
210
+ return true;
211
+ }
212
+ // Installed, and still nothing: what stands in the way is not pine's to change.
213
+ const second = sandboxPlan(after);
214
+ io.out(`\nIt is set up, but a sandbox still cannot be made: ${second.cannot ?? (sandboxMissing() || second.why)}\n${noShell}`);
215
+ return false;
216
+ }
@@ -0,0 +1,238 @@
1
+ import { type AgentConfig, type Level, type PineConfig } from "./config.ts";
2
+ import type { DenialTools } from "./access.ts";
3
+ import { Guard } from "./sandbox-linux.ts";
4
+ import type { Bus } from "./store.ts";
5
+ import { type Logger } from "./util.ts";
6
+ /** realpath of the deepest existing ancestor, plus the part that does not exist yet. Defeats symlink escapes. */
7
+ export declare function realish(p: string): string;
8
+ export declare const isInside: (root: string, p: string) => boolean;
9
+ export interface Roots {
10
+ workspace: string;
11
+ /** Private HOME and TMPDIR of the agent's shell commands. */
12
+ sandboxHome: string;
13
+ /** pine's home directory: off limits except for the parts listed in ownedRead / ownedWrite. */
14
+ home: string;
15
+ read: string[];
16
+ write: string[];
17
+ /** The agent's own roots, without the shared temp directories. */
18
+ ownedRead: string[];
19
+ ownedWrite: string[];
20
+ /**
21
+ * Where this session's shell and file tools start. The agent's workspace, or the folder the
22
+ * owner opened for the conversation, which is then readable and writable like the workspace.
23
+ */
24
+ cwd: string;
25
+ /** The folder the owner opened for the conversation, if any. Its instruction files are guarded like the workspace's. */
26
+ folder?: string;
27
+ /** USER.md in pine's home: what all agents know about the owner. Only the main agent may write it. */
28
+ userFile: string;
29
+ /**
30
+ * The owner let this conversation change the agent's own files (MEMORY.md, AGENTS.md, SOUL.md,
31
+ * and USER.md for the main agent) although it has read outside content.
32
+ */
33
+ ownOpen?: boolean;
34
+ /** Read access is refused here even when a broader rule would allow it. */
35
+ secrets: string[];
36
+ /** Workspaces of the other agents. Agents exchange information through delegation, not through each other's files. */
37
+ others: string[];
38
+ }
39
+ export declare function rootsFor(cfg: PineConfig, agent: AgentConfig): Roots;
40
+ /**
41
+ * How far a call reaches.
42
+ * normal: the agent's own folders, inside the sandbox ("safe" and "manual").
43
+ * restricted: the same, and its instruction files are read-only (the run has handled outside content).
44
+ * open: no sandbox: the whole user account ("auto" and "bypass", in a conversation of the
45
+ * owner's). pine's home and pine's own code stay closed, by the checks in this file
46
+ * and in actions.ts, not by the operating system.
47
+ * open-restricted: the same reach, in a conversation that has read outside content. The file
48
+ * tools do not write what is read into the agent's prompt.
49
+ */
50
+ export type SandboxVariant = "normal" | "restricted" | "open" | "open-restricted";
51
+ export declare const isOpen: (v: SandboxVariant | boolean) => v is "open" | "open-restricted";
52
+ /** The two variants a sandbox is made for. `true` is "restricted", `false` "normal". */
53
+ export type Boxed = "normal" | "restricted" | boolean;
54
+ /** Why a file tool may not touch `target`, or undefined when it may. */
55
+ /**
56
+ * "~" in a path a model gave a file tool: the owner's home folder, in every scope. pi's read,
57
+ * write and edit take it that way, so the check and the other file tools must as well, or a
58
+ * path would be judged as one file and opened as another. (An agent in the workspace scope
59
+ * reaches its own private home by its full path.)
60
+ */
61
+ export declare function tilde(target: string): string;
62
+ export declare function checkPath(roots: Roots, kind: "read" | "write", given: string, cwd: string, variant: SandboxVariant | boolean): string | undefined;
63
+ /** Whether the owner can give a conversation this path at all: not pine's own files, not another agent's. What `request_access` refuses. */
64
+ export declare function grantable(roots: Roots, kind: "read" | "write", p: string): boolean;
65
+ /**
66
+ * The path a file tool is refused only because it lies outside what the agent was given: the
67
+ * owner can be asked for exactly that. Undefined when the path is fine, or closed for another reason.
68
+ */
69
+ export declare function outsidePath(roots: Roots, kind: "read" | "write", given: string, cwd: string, variant: SandboxVariant | boolean): string | undefined;
70
+ /**
71
+ * Whether the sandbox of an agent that works in its own folders refuses its shell this path: it
72
+ * reads everything except the owner's home, and writes only what it was given. (The file tools
73
+ * are judged by `checkPath`, which is stricter about reading.)
74
+ */
75
+ export declare function shellRefuses(roots: Roots, kind: "read" | "write", p: string): boolean;
76
+ /**
77
+ * What to ask the owner for when a command needs `p`. On Linux a path that does not exist yet
78
+ * cannot be mounted, so a file that is still to be made is asked for as the folder it goes into.
79
+ */
80
+ export declare function grantPath(p: string): string;
81
+ export declare function isInstructionPath(workspace: string, p: string): boolean;
82
+ /** Whether a path is one of the files that are read into the agent's prompt from its workspace, or the owner's file in pine's home. */
83
+ export declare function isOwnFile(roots: Roots, p: string): boolean;
84
+ /** The files an agent keeps itself: its memory and instructions at the top of its workspace, and for the main agent what is known about the owner. */
85
+ export declare function ownFiles(roots: Roots): string[];
86
+ /** The own file a path given to a file tool means, if it means one. */
87
+ export declare function ownFileOf(roots: Roots, given: string, cwd: string): string | undefined;
88
+ /** Whether a path in one of the agent's folders is a repository's hooks or configuration, or the repository's own folder. */
89
+ export declare function isGitRunPath(root: string, p: string): boolean;
90
+ /**
91
+ * macOS sandbox profile for everything an agent does on the file system: its shell commands and
92
+ * its file tools. Nothing is allowed unless a rule here allows it; for file rules the last match wins.
93
+ *
94
+ * Allowed: running programs, reading outside the user's home, writing in the agent's own folders
95
+ * and temp. Not allowed: the user's home, pine's home (secrets, configuration, other agents),
96
+ * other processes (signals, their arguments and environment), launching apps, AppleScript,
97
+ * the keychain, the clipboard, and the network unless the agent's configuration turns it on.
98
+ */
99
+ export declare function sandboxProfile(_cfg: PineConfig, agent: AgentConfig, roots: Roots, variant: Boxed, network?: boolean, tag?: string): string;
100
+ /** Where a system program lies on this machine: the same few folders on macOS and Linux, never the agent's PATH. */
101
+ export declare function bin(name: string): string;
102
+ /**
103
+ * The rights a container has to be started with for a sandbox to work inside it: to create
104
+ * namespaces, to give a sandbox without network its loopback interface, and past Docker's own
105
+ * system call filter and AppArmor profile, which forbid the mounts. An ordinary user in the
106
+ * container needs one more, to mount the sandbox's own /proc. (Each was tried by leaving it out.)
107
+ */
108
+ export declare const containerFlags: (root?: boolean) => string;
109
+ /** Whether pine runs inside a container (Docker, Podman, Kubernetes). */
110
+ export declare function inContainer(): boolean;
111
+ /**
112
+ * Which sandbox this machine has: Apple's sandbox-exec on macOS, bubblewrap on Linux. On Linux
113
+ * it is tried once, because bubblewrap can be installed and still not be allowed to work (a
114
+ * system that has switched off user namespaces for ordinary users, some containers).
115
+ */
116
+ export declare function sandboxKind(): "macos" | "linux" | undefined;
117
+ /**
118
+ * What the try on Linux found, for setting the sandbox up (src/sandbox-setup.ts): where bwrap
119
+ * is, whether it could make a sandbox, what it said when not, and whether AppArmor is why.
120
+ */
121
+ export declare function sandboxFound(): {
122
+ bwrap: string;
123
+ works: boolean;
124
+ said: string;
125
+ apparmor: boolean;
126
+ };
127
+ /** Look again: something that was missing may have been installed since. */
128
+ export declare function sandboxRecheck(): void;
129
+ export declare const sandboxAvailable: () => boolean;
130
+ /**
131
+ * The level an agent works at. "safe" needs a sandbox. On a machine that has none (a container,
132
+ * usually, which is then the wall around all of pine), an agent whose mode nobody chose works
133
+ * in "auto" instead. One that was set to "safe" stays there and gets no shell: what somebody
134
+ * asked for is not widened silently.
135
+ */
136
+ export declare function levelOf(agent: AgentConfig): Level;
137
+ /** Why this machine has no sandbox, in words for the owner. */
138
+ export declare const sandboxMissing: () => string;
139
+ /**
140
+ * What to put in front of a command so that it runs with an agent's limits: the same rules on
141
+ * both systems, said to Apple's sandbox as a profile and to bubblewrap as mounts. Made anew for
142
+ * every command, because on Linux what exists at that moment is part of it.
143
+ */
144
+ export declare function sandboxArgv(cfg: PineConfig, agent: AgentConfig, roots: Roots, variant: Boxed, network?: boolean, tag?: string): string[];
145
+ /**
146
+ * How pine reads what the macOS sandbox refused (src/access.ts): the system's log, for reports
147
+ * that carry a text of pine's, and a refusal pine makes itself to know that it has read up to
148
+ * now. Linux reports nothing of the kind.
149
+ */
150
+ export declare function denialTools(): DenialTools;
151
+ /**
152
+ * On Linux, mounts cannot forbid making a file of a protected name. Take this before a command
153
+ * in the restricted variant and call `restore` after it: what the command made although it may
154
+ * not is removed again. On macOS the profile forbids it outright and there is nothing to do.
155
+ */
156
+ export declare function sandboxGuard(roots: Roots, variant: SandboxVariant | boolean): Guard | undefined;
157
+ /**
158
+ * What to put in front of a helper that works on things from anywhere (git looking at a folder,
159
+ * a picture converter): it may read, write only in `write`, and has no network. Undefined where
160
+ * there is no sandbox.
161
+ */
162
+ export declare function helperArgv(write?: string[]): string[] | undefined;
163
+ /**
164
+ * Environment for an agent's shell: nothing from the daemon except what a shell needs, and a
165
+ * home of its own. With the whole account (`wide`) it is the owner's own home and environment,
166
+ * so that git, ssh, npm and the owner's toolchains behave as in their terminal; what looks like
167
+ * a credential by its name is still left out, and so is what belongs to the daemon.
168
+ */
169
+ export declare function shellEnv(agent: AgentConfig, roots: Roots, sessionEnv: NodeJS.ProcessEnv, wide?: boolean): NodeJS.ProcessEnv;
170
+ export declare const shq: (s: string) => string;
171
+ /** Glob with `*` only, anchored. */
172
+ export declare function globMatch(pattern: string, value: string): boolean;
173
+ /** "tool" or "tool:argument-glob". The argument is the command, topic, agent or path the call is about. */
174
+ export declare function matchesToolPattern(patterns: readonly string[], tool: string, subject: string): boolean;
175
+ /** The part of a tool call a person needs to see to judge it. */
176
+ export declare function toolSubject(tool: string, input: any): string;
177
+ export interface ApprovalRequest {
178
+ id: string;
179
+ agent: string;
180
+ task: number;
181
+ /** The task at the top of the delegation tree this request belongs to. */
182
+ root?: number;
183
+ tool: string;
184
+ summary: string;
185
+ why: string;
186
+ expires: number;
187
+ /** What "always" would cover for the rest of the conversation, e.g. "all home-link tools". Absent: the question is asked every time. */
188
+ remember?: string;
189
+ /** What a plain yes already covers, when that is more than this one call ("this conversation"): the dialog then says so, and not "once". */
190
+ holds?: string;
191
+ /**
192
+ * Values only the owner has and that must not pass through a model: a password, a token. The
193
+ * owner types them where the question is shown. A yes without them is not a yes.
194
+ */
195
+ inputs?: Array<{
196
+ name: string;
197
+ label: string;
198
+ secret?: boolean;
199
+ }>;
200
+ /**
201
+ * A question of the agent's rather than a permission: answers to pick from. The one that is
202
+ * picked, or the owner's own words, comes back as the input `answer`.
203
+ */
204
+ choices?: string[];
205
+ }
206
+ export interface ApprovalDecision {
207
+ allow: boolean;
208
+ by: string;
209
+ /** Allowed, and not to be asked again in this conversation. */
210
+ always?: boolean;
211
+ /** What the owner typed for the request's `inputs`. Never published as an event. */
212
+ values?: Record<string, string>;
213
+ }
214
+ /** Human-in-the-loop gate. Requests are events; anything that can reach the owner may answer them. */
215
+ export declare class Approvals {
216
+ private bus;
217
+ private log;
218
+ private timeoutMs;
219
+ private open;
220
+ constructor(bus: Bus, log: Logger, timeoutMs: number);
221
+ request(r: Omit<ApprovalRequest, "id" | "expires">, signal?: AbortSignal): Promise<ApprovalDecision>;
222
+ /** The fields of an open request that a yes has to come with and that `values` does not have. */
223
+ missing(id: string, values?: Record<string, string>): string[];
224
+ /** Returns false when the id is unknown or already answered, or when a yes lacks what the request asks the owner to type. */
225
+ decide(id: string, allow: boolean, by: string, always?: boolean, values?: Record<string, string>): boolean;
226
+ pending(): ApprovalRequest[];
227
+ denyAll(by: string): void;
228
+ }
229
+ /** Replaces known secret values in text that leaves the daemon. */
230
+ export declare class Redactor {
231
+ private secrets;
232
+ add(values: Iterable<string | undefined>): void;
233
+ text(s: string): string;
234
+ deep<T>(v: T): T;
235
+ }
236
+ export declare const timingSafeEqual: (a: string, b: string) => boolean;
237
+ /** Things about a configuration that weaken its defences. Shown by `pine check` and at startup. */
238
+ export declare function audit(cfg: PineConfig): string[];