@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
package/src/access.js ADDED
@@ -0,0 +1,438 @@
1
+ // What a command reaches for beyond its sandbox, and how the owner comes to be asked about it.
2
+ //
3
+ // The sandbox refuses inside the system. The program is told "Operation not permitted", or
4
+ // finds nothing where it looked, and reports that in words of its own: "No such file",
5
+ // "Could not resolve host", or nothing at all. An agent that reads those words has to guess
6
+ // that it was its sandbox, and has to think of asking; a small model does neither. So pine
7
+ // finds out itself, in two ways: before a command runs, from the paths its text names
8
+ // (`reaches`); and after it has run, on macOS, from the system's own reports of what the
9
+ // sandbox refused (`Denials`). Neither decides anything. What they find becomes a question to
10
+ // the owner (in src/agents.ts), and a yes becomes a grant like the one `request_access` gives,
11
+ // which the sandbox then enforces.
12
+ import { spawn } from "node:child_process";
13
+ import crypto from "node:crypto";
14
+ import fs from "node:fs";
15
+ import path from "node:path";
16
+ export const wantKey = (w) => `${w.kind}:${w.path ?? ""}`;
17
+ export const wantText = (w) => (w.kind === "network" ? "use the network" : `${w.kind === "write" ? "write" : "read"} ${w.path}`);
18
+ /**
19
+ * The shell that keeps the log reader: fixed text. It ends the reader when its own input closes,
20
+ * which is when pine is gone, however pine went.
21
+ */
22
+ const KEEP = '"$@" & pid=$!; trap "kill $pid 2>/dev/null" EXIT; cat > /dev/null';
23
+ /**
24
+ * The system's reports of what the sandbox refused, by command. macOS writes one to its log for
25
+ * every refusal, with a text the profile chose (`with message`): each command gets a text of its
26
+ * own, and pine reads the log for them. After a command pine makes one refusal itself (the mark)
27
+ * and waits until it sees that one, so "nothing was reported" is known and not assumed.
28
+ *
29
+ * Reading the log costs a few percent of a processor for as long as it goes on, whatever is
30
+ * asked of it. So the reader runs while commands run and a little longer (`idleMs`), and is
31
+ * started again, in some ten milliseconds, by the next command.
32
+ */
33
+ export class Denials {
34
+ log;
35
+ tools;
36
+ base = `pine-${crypto.randomBytes(6).toString("hex")}`;
37
+ n = 0;
38
+ child;
39
+ state = "idle";
40
+ starting;
41
+ starts = 0;
42
+ seen = new Map();
43
+ marks = new Map();
44
+ /** Commands that have a tag and have not been collected: while there is one, the reader stays. */
45
+ open = new Set();
46
+ idle;
47
+ idleMs;
48
+ constructor(log, tools, idleMs = 20_000) {
49
+ this.log = log;
50
+ this.tools = tools;
51
+ this.idleMs = idleMs;
52
+ }
53
+ /** Whether refusals are being read. Starts the reader on first use; false where there is none. */
54
+ ready() {
55
+ if (this.state === "ready")
56
+ return Promise.resolve(true);
57
+ if (this.state === "off")
58
+ return Promise.resolve(false);
59
+ this.starting ??= this.start().finally(() => {
60
+ this.starting = undefined;
61
+ });
62
+ return this.starting;
63
+ }
64
+ /** The text for the next command's profile. Every tag is given back with `collect` or `drop`. */
65
+ tag() {
66
+ const tag = `${this.base}:c:${++this.n}`;
67
+ this.open.add(tag);
68
+ clearTimeout(this.idle);
69
+ return tag;
70
+ }
71
+ /** What the sandbox refused the command with this tag. Call it once, after the command has ended. */
72
+ async collect(tag) {
73
+ if (this.state === "ready")
74
+ await this.mark(tag, 1500);
75
+ const got = this.seen.get(tag) ?? [];
76
+ this.drop(tag);
77
+ return got;
78
+ }
79
+ /** A command whose refusals nobody will ask for. */
80
+ drop(tag) {
81
+ this.seen.delete(tag);
82
+ this.open.delete(tag);
83
+ if (this.open.size || this.state !== "ready")
84
+ return;
85
+ clearTimeout(this.idle);
86
+ this.idle = setTimeout(() => {
87
+ if (this.open.size || this.state !== "ready")
88
+ return;
89
+ this.state = "idle";
90
+ this.end();
91
+ }, this.idleMs);
92
+ this.idle.unref?.();
93
+ }
94
+ stop() {
95
+ this.state = "off";
96
+ clearTimeout(this.idle);
97
+ this.end();
98
+ }
99
+ end() {
100
+ const child = this.child;
101
+ this.child = undefined;
102
+ child?.stdin?.end();
103
+ child?.kill();
104
+ for (const done of [...this.marks.values()])
105
+ done();
106
+ }
107
+ async start() {
108
+ const argv = this.tools.stream(`${this.base}:`);
109
+ if (!argv || this.starts >= 3) {
110
+ this.state = "off";
111
+ return false;
112
+ }
113
+ this.starts++;
114
+ let child;
115
+ try {
116
+ child = spawn("/bin/sh", ["-c", KEEP, "sh", ...argv], { stdio: ["pipe", "pipe", "ignore"] });
117
+ }
118
+ catch {
119
+ this.state = "off";
120
+ return false;
121
+ }
122
+ this.child = child;
123
+ let alive = true;
124
+ let buf = "";
125
+ child.stdin?.on("error", () => { });
126
+ child.stdout?.on("data", (d) => {
127
+ buf += d.toString("utf8");
128
+ for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
129
+ this.line(buf.slice(0, i));
130
+ buf = buf.slice(i + 1);
131
+ }
132
+ });
133
+ const gone = () => {
134
+ if (!alive)
135
+ return;
136
+ alive = false;
137
+ if (this.child === child) {
138
+ this.child = undefined;
139
+ // The reader can end for reasons of its own. The next command starts it again, a few times.
140
+ if (this.state === "ready")
141
+ this.state = "idle";
142
+ }
143
+ for (const done of [...this.marks.values()])
144
+ done();
145
+ };
146
+ child.on("error", gone);
147
+ child.on("close", gone);
148
+ // The reader says nothing when it has begun to read. A mark that comes back does.
149
+ for (let i = 0; i < 40 && alive && this.state === "idle"; i++) {
150
+ if (await this.mark("", 150)) {
151
+ this.state = "ready";
152
+ this.starts = 0;
153
+ return true;
154
+ }
155
+ }
156
+ if (this.state === "idle") {
157
+ this.state = "off";
158
+ this.log.info("the system's reports of what a sandbox refused cannot be read here; an agent whose command is refused something is told less about it");
159
+ }
160
+ if (this.child === child)
161
+ this.end();
162
+ return false;
163
+ }
164
+ /** Make one refusal and wait until it is reported: everything refused before it has been read by then. */
165
+ mark(about, ms) {
166
+ const tag = `${this.base}:m:${++this.n}`;
167
+ const argv = this.tools.mark(tag, about);
168
+ if (!argv)
169
+ return Promise.resolve(false);
170
+ return new Promise((resolve) => {
171
+ let over = false;
172
+ const done = (ok = false) => {
173
+ if (over)
174
+ return;
175
+ over = true;
176
+ clearTimeout(timer);
177
+ this.marks.delete(tag);
178
+ resolve(ok);
179
+ };
180
+ const timer = setTimeout(done, ms);
181
+ this.marks.set(tag, () => done(this.seen.delete(tag)));
182
+ try {
183
+ spawn(argv[0], argv.slice(1), { stdio: "ignore" }).on("error", () => done());
184
+ }
185
+ catch {
186
+ done();
187
+ }
188
+ });
189
+ }
190
+ line(line) {
191
+ if (!line.startsWith("{"))
192
+ return;
193
+ let message;
194
+ try {
195
+ message = JSON.parse(line).eventMessage;
196
+ }
197
+ catch {
198
+ return;
199
+ }
200
+ if (typeof message !== "string")
201
+ return;
202
+ const lines = message.trim().split("\n");
203
+ const tag = lines.at(-1).trim();
204
+ if (!tag.startsWith(`${this.base}:`))
205
+ return;
206
+ const m = /Sandbox: (.+?)\(\d+\) deny\(\d+\) (\S+)(?: (.*))?$/.exec(lines[0]);
207
+ if (this.seen.size > 500)
208
+ this.seen.delete(this.seen.keys().next().value);
209
+ const list = this.seen.get(tag) ?? [];
210
+ if (m && list.length < 400)
211
+ list.push({ process: m[1], op: m[2], target: (m[3] ?? "").trim() });
212
+ this.seen.set(tag, list);
213
+ this.marks.get(tag)?.();
214
+ }
215
+ }
216
+ const WRITES_ALL = new Set(["touch", "mkdir", "rm", "rmdir", "mv", "tee", "chmod", "chown", "truncate", "unzip"]);
217
+ const WRITES_LAST = new Set(["cp", "ln", "install", "rsync"]);
218
+ const WRAPPERS = new Set(["sudo", "env", "time", "nohup", "command", "exec", "nice"]);
219
+ /** A command line as simple commands of words. Quotes are taken off; what is substituted at run time is left as it is written. */
220
+ function words(command) {
221
+ const out = [[]];
222
+ let cur = "";
223
+ let has = false;
224
+ let redirect = false;
225
+ const push = () => {
226
+ if (has)
227
+ out.at(-1).push({ text: cur, redirect });
228
+ if (has)
229
+ redirect = false;
230
+ cur = "";
231
+ has = false;
232
+ };
233
+ for (let i = 0; i < command.length; i++) {
234
+ const ch = command[i];
235
+ if (ch === "'") {
236
+ const end = command.indexOf("'", i + 1);
237
+ cur += command.slice(i + 1, end < 0 ? command.length : end);
238
+ has = true;
239
+ i = end < 0 ? command.length : end;
240
+ }
241
+ else if (ch === '"') {
242
+ has = true;
243
+ for (i++; i < command.length && command[i] !== '"'; i++) {
244
+ if (command[i] === "\\" && i + 1 < command.length && '"\\$`'.includes(command[i + 1]))
245
+ i++;
246
+ cur += command[i];
247
+ }
248
+ }
249
+ else if (ch === "\\" && i + 1 < command.length) {
250
+ cur += command[++i];
251
+ has = true;
252
+ }
253
+ else if (ch === ">") {
254
+ // "2>" and "&>": what stands in front of the sign is not a word.
255
+ if (/^(\d*|&)$/.test(cur)) {
256
+ cur = "";
257
+ has = false;
258
+ }
259
+ else
260
+ push();
261
+ if (command[i + 1] === ">")
262
+ i++;
263
+ // ">&2" names no file.
264
+ redirect = command[i + 1] !== "&";
265
+ if (!redirect)
266
+ i++;
267
+ }
268
+ else if (ch === "<") {
269
+ push();
270
+ redirect = false;
271
+ }
272
+ else if (ch === ";" || ch === "|" || ch === "&" || ch === "(" || ch === ")" || ch === "\n") {
273
+ push();
274
+ redirect = false;
275
+ if (out.at(-1).length)
276
+ out.push([]);
277
+ }
278
+ else if (ch === " " || ch === "\t")
279
+ push();
280
+ else {
281
+ cur += ch;
282
+ has = true;
283
+ }
284
+ }
285
+ push();
286
+ return out.filter((c) => c.length);
287
+ }
288
+ /** The program each simple command of a command line starts, without its folder ("git", "npm"). Quoted text is not taken for a command. */
289
+ export function verbs(command) {
290
+ return words(command.length > 20_000 ? command.slice(0, 20_000) : command).map((simple) => {
291
+ const args = simple.filter((w) => !w.redirect);
292
+ let first = 0;
293
+ while (first < args.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(args[first].text) || WRAPPERS.has(args[first].text)))
294
+ first++;
295
+ return path.basename(args[first]?.text ?? "");
296
+ });
297
+ }
298
+ /**
299
+ * The paths a command line names that are written out: absolute ones, and ones in a home folder
300
+ * (~, $HOME). This is reading, not running: what a variable or a script holds is not seen, and
301
+ * need not be, because the sandbox decides what the command reaches. It is only how pine knows
302
+ * whom to ask before the command fails.
303
+ */
304
+ export function reaches(command, where) {
305
+ const out = [];
306
+ for (const simple of words(command.length > 20_000 ? command.slice(0, 20_000) : command)) {
307
+ const args = simple.filter((w) => !w.redirect);
308
+ let first = 0;
309
+ while (first < args.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(args[first].text) || WRAPPERS.has(args[first].text)))
310
+ first++;
311
+ const verb = path.basename(args[first]?.text ?? "");
312
+ const named = [];
313
+ for (const w of simple) {
314
+ if (!w.redirect && w === args[first])
315
+ continue;
316
+ // "--output=/a/b" names /a/b.
317
+ let text = w.redirect ? w.text : (/^--?[A-Za-z][\w-]*=(.+)$/.exec(w.text)?.[1] ?? w.text);
318
+ let home = false;
319
+ const tilde = /^(~|\$HOME|\$\{HOME\})(\/|$)/.exec(text);
320
+ if (tilde) {
321
+ home = true;
322
+ text = text.slice(tilde[1].length).replace(/^\//, "");
323
+ }
324
+ else if (text.startsWith("../") || text === "..")
325
+ text = path.join(where.cwd, text);
326
+ else if (!text.startsWith("/"))
327
+ continue;
328
+ // A pattern, or a name made at run time: the folder it is looked for in.
329
+ const parts = text.split("/");
330
+ const cut = parts.findIndex((p) => /[*?[{$`]/.test(p));
331
+ const rest = (cut < 0 ? parts : parts.slice(0, cut)).join("/");
332
+ if (!home && (rest === "" || rest === "/"))
333
+ continue;
334
+ const full = (home ? path.join(where.shellHome, rest) : path.normalize(rest)).replace(/(.)\/+$/, "$1");
335
+ if (full.startsWith("/dev/") || full === "/dev" || full.startsWith("/proc/"))
336
+ continue;
337
+ const reach = { path: full, write: w.redirect || WRITES_ALL.has(verb), text: w.text };
338
+ if (home)
339
+ reach.owner = path.join(where.ownerHome, rest).replace(/(.)\/+$/, "$1");
340
+ named.push({ reach, redirect: w.redirect });
341
+ }
342
+ // "cp a b" writes b: the last thing it is given, if that is one of the paths.
343
+ const target = WRITES_LAST.has(verb) ? args.slice(first + 1).filter((w) => !w.text.startsWith("-")).at(-1) : undefined;
344
+ const last = target ? named.find((x) => !x.redirect && x.reach.text === target.text) : undefined;
345
+ if (last)
346
+ last.reach.write = true;
347
+ out.push(...named.map((x) => x.reach));
348
+ }
349
+ // One entry a path; a write counts for the path.
350
+ const by = new Map();
351
+ for (const r of out) {
352
+ const had = by.get(r.path);
353
+ if (had)
354
+ had.write ||= r.write;
355
+ else
356
+ by.set(r.path, r);
357
+ }
358
+ return [...by.values()].slice(0, 40);
359
+ }
360
+ // ---- after a command has run ---------------------------------------------------------------------
361
+ /** Words a failed step leaves in the output of a command that still ended well ("... | tail", "... || true"). */
362
+ const FAILED = /\b(error|failed|failure|fatal|cannot|can't|could not|couldn't|unable to|not permitted|permission denied|denied|not found|no such file|no matching|timed out|unreachable|refused)\b/i;
363
+ export const looksFailed = (output) => FAILED.test(output);
364
+ const NOT_PERMITTED = /Operation not permitted|Permission denied|Read-only file system/;
365
+ /** What a program says when it has no network: it cannot look a name up, or cannot reach an address. */
366
+ const NO_NETWORK = /Could not resolve host|Couldn't resolve host|Temporary failure in name resolution|Name or service not known|nodename nor servname provided|No address associated with hostname|Network is unreachable|getaddrinfo (ENOTFOUND|EAI_AGAIN)|failed to lookup address|unable to resolve host|dial tcp: lookup |NameResolutionError|Failed to establish a new connection|ENETUNREACH/i;
367
+ /**
368
+ * Where the system reports nothing (Linux, or the reader is not running): what the output of a
369
+ * failed command says. Weaker than a report: a program that keeps quiet tells nothing.
370
+ */
371
+ export function fromOutput(output) {
372
+ const paths = new Set();
373
+ for (const line of output.split("\n")) {
374
+ if (!NOT_PERMITTED.test(line))
375
+ continue;
376
+ for (const m of line.matchAll(/(?:^|[\s'"`:=(])(\/[^\s'"`:,;()]+)/g))
377
+ paths.add(m[1].replace(/[.]+$/, ""));
378
+ }
379
+ return { paths: [...paths].slice(0, 20), network: NO_NETWORK.test(output) };
380
+ }
381
+ /** Refusals every command meets and none needs: the system's tracing and logging, asked for by its libraries. */
382
+ const NOISE_TARGET = /^\/dev\/|^path:\/dev\/|^com\.apple\.(diagnosticd|logd|system\.logger|analyticsd|system\.notification_center)$/;
383
+ /** The system's reports for one command, sorted: which paths, whether the network, which services. */
384
+ export function sortDenials(denials) {
385
+ const read = new Set();
386
+ const write = new Set();
387
+ const services = new Set();
388
+ let network = false;
389
+ for (const d of denials) {
390
+ if (NOISE_TARGET.test(d.target))
391
+ continue;
392
+ if (d.op.startsWith("network")) {
393
+ // A socket file is another program on this machine; the name lookup's is how every program
394
+ // finds an address. A socket on no port in particular is a program talking to itself.
395
+ if (d.target.endsWith("/mDNSResponder") || (!d.target.startsWith("/") && !(d.op === "network-bind" && /:0$/.test(d.target))))
396
+ network = true;
397
+ }
398
+ else if (d.op.startsWith("file-write") && d.target.startsWith("/"))
399
+ write.add(d.target);
400
+ else if (d.op.startsWith("file-read") && d.target.startsWith("/"))
401
+ read.add(d.target);
402
+ else if (d.op === "mach-lookup" && d.target)
403
+ services.add(d.target);
404
+ }
405
+ return { read: [...read].filter((p) => !write.has(p)), write: [...write], network, services: [...services] };
406
+ }
407
+ const isInside = (root, p) => p === root || p.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
408
+ /**
409
+ * Many refusals become few questions: a refused path that lies in something the command named is
410
+ * that thing, and several in one folder are the folder.
411
+ */
412
+ export function gather(paths, named) {
413
+ const out = new Set();
414
+ for (const p of paths)
415
+ out.add(named.filter((n) => isInside(n, p)).sort((a, b) => b.length - a.length)[0] ?? p);
416
+ const byParent = new Map();
417
+ for (const p of out)
418
+ byParent.set(path.dirname(p), [...(byParent.get(path.dirname(p)) ?? []), p]);
419
+ for (const [parent, list] of byParent) {
420
+ if (list.length < 3 || named.some((n) => list.includes(n)))
421
+ continue;
422
+ for (const p of list)
423
+ out.delete(p);
424
+ out.add(parent);
425
+ }
426
+ // What lies in something else that is asked for needs no line of its own.
427
+ return [...out].filter((p) => ![...out].some((o) => o !== p && isInside(o, p)));
428
+ }
429
+ /** Whether a path exists, as far as the daemon can tell without opening anything. */
430
+ export function there(p) {
431
+ try {
432
+ fs.lstatSync(p);
433
+ return true;
434
+ }
435
+ catch {
436
+ return false;
437
+ }
438
+ }
@@ -0,0 +1,75 @@
1
+ import { type Roots } from "./security.ts";
2
+ /**
3
+ * look: only reads. Never asked about.
4
+ * local: changes something inside the agent's own folders (or the folder opened for the conversation).
5
+ * reach: acts beyond them: a shell that reaches the account or the network, a file elsewhere, a download.
6
+ * send: tells somebody or something outside: a message, an event, a server's tool that acts, another agent that can.
7
+ * own: the agent's memory and instructions, which are read into every later conversation.
8
+ * critical: what makes other programs run or opens the account: shell startup files, keys, hooks; and destroying a lot at once.
9
+ * setup: changes pine itself. Such a tool asks the owner by its own rules.
10
+ */
11
+ export type ActionClass = "look" | "local" | "reach" | "send" | "own" | "critical" | "setup";
12
+ /** Tools that only look. */
13
+ export declare const LOOK_TOOLS: string[];
14
+ /** Tools that change pine's setup or ask for access. Each asks the owner where it matters, so the gate does not ask again. */
15
+ export declare const SETUP_TOOLS: string[];
16
+ /** Whether a file is one of the protected ones. */
17
+ export declare function isProtectedPath(p: string): boolean;
18
+ /**
19
+ * Whether a command line only looks. Deliberately narrow: anything that could write (a
20
+ * redirect, a substitution, an option that runs or deletes) is not one. A wrong "no" costs a
21
+ * question; a wrong "yes" would let an action through unseen.
22
+ */
23
+ export declare function readOnlyCommand(command: string): boolean;
24
+ /** Why a command line is critical, or undefined. Patterns, so they are a net and not a wall: what they catch is put to the owner. */
25
+ export declare function criticalCommand(command: string): string | undefined;
26
+ /**
27
+ * What a shell without a sandbox ("auto" and "bypass" mode) is refused because it is pine's own:
28
+ * pine's home (configuration, secrets, the other agents' folders), writing pine's program files,
29
+ * the pine program, and pine's control port. In a sandbox the operating system keeps these closed. Here it is this reading
30
+ * of the command line, so it is a net and not a wall: what a script or a variable holds is not
31
+ * seen, and a command that walks a whole folder is not followed into it.
32
+ */
33
+ export declare function pineOwn(command: string, o: {
34
+ home: string;
35
+ own: string[];
36
+ code: string;
37
+ cwd: string;
38
+ ownerHome: string;
39
+ port?: number;
40
+ }): string | undefined;
41
+ /** What an agent is told when `pineOwn` refuses a command. */
42
+ export declare const pineOwnRefusal: (why: string) => string;
43
+ export interface ActionContext {
44
+ roots: Roots;
45
+ /** What a relative path is relative to. */
46
+ cwd: string;
47
+ /** Whether this session's shell reaches beyond the agent's own folders: the account, the network, or no sandbox at all. */
48
+ shellReaches: boolean;
49
+ /** For a tool of an MCP server: whether the server says it only reads, and whether its acting tools are to be looked at. */
50
+ mcp?: {
51
+ readOnly: boolean;
52
+ watched: boolean;
53
+ };
54
+ /** For a tool of the bundled app control server: whether it only looks at an app. */
55
+ app?: {
56
+ look: boolean;
57
+ };
58
+ /** Whether the agent's configuration counts this tool as sending something out (`approveWhenTainted`). */
59
+ sends: boolean;
60
+ /** Whether the agent a task is handed to can send things out. */
61
+ canSendOut(agent: string): boolean;
62
+ /** Whether an address is one the agent can read anyway. */
63
+ reachable(url: unknown): boolean;
64
+ /** For a shell without a sandbox: why a command is critical because of what it names (pine's own program files), or undefined. */
65
+ names?(command: string): string | undefined;
66
+ }
67
+ export interface Action {
68
+ cls: ActionClass;
69
+ /** What makes it that class, when that needs saying. */
70
+ note?: string;
71
+ }
72
+ /** Sort a tool call into its class. The one place that knows. */
73
+ export declare function classify(tool: string, input: any, ctx: ActionContext): Action;
74
+ /** What an agent is told when it tries to act while its owner has it planning. */
75
+ export declare const PLAN_REFUSAL = "Not done: you are in plan mode. In plan mode you look, read, search and ask, and nothing is changed, run or sent. Do not try another way to do it. When you have seen enough, answer with your plan: what you would do, in which order, in which files, and what could go wrong. Your owner reads it and switches the mode when it is to be carried out.";