@pmndre/pine 0.22.1 → 0.33.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 (99) hide show
  1. package/README.md +2 -1
  2. package/changes.json +265 -0
  3. package/docs/SKILL.md +31 -7
  4. package/docs/references/agents.md +245 -21
  5. package/docs/references/coding.md +1 -1
  6. package/docs/references/computer.md +1 -1
  7. package/docs/references/configuration.md +14 -5
  8. package/docs/references/mcp.md +9 -0
  9. package/docs/references/operations.md +20 -9
  10. package/docs/references/overview.md +3 -1
  11. package/docs/references/security.md +83 -24
  12. package/docs/references/setup.md +55 -9
  13. package/docs/references/source-types.md +1418 -0
  14. package/docs/references/sources.md +333 -19
  15. package/docs/references/stack.md +1 -0
  16. package/docs/references/tui.md +86 -12
  17. package/examples/home/AGENTS.md +4 -0
  18. package/examples/home/TOOLS.md +5 -0
  19. package/examples/home/agents/main/workspace/AGENTS.md +1 -1
  20. package/examples/home/agents/main/workspace/TOOLS.md +5 -0
  21. package/mcp/browser.d.ts +6 -0
  22. package/mcp/browser.js +19 -0
  23. package/mcp/render.d.ts +1 -0
  24. package/mcp/render.js +237 -0
  25. package/package.json +3 -1
  26. package/src/actions.d.ts +6 -1
  27. package/src/actions.js +17 -4
  28. package/src/admin.d.ts +4 -0
  29. package/src/admin.js +25 -6
  30. package/src/agents.d.ts +167 -2
  31. package/src/agents.js +912 -45
  32. package/src/catalogue.d.ts +60 -0
  33. package/src/catalogue.js +791 -0
  34. package/src/cli.js +10 -7
  35. package/src/config.d.ts +53 -4
  36. package/src/config.js +30 -5
  37. package/src/goals.d.ts +1 -1
  38. package/src/goals.js +14 -1
  39. package/src/manual.js +24 -2
  40. package/src/mime.d.ts +78 -0
  41. package/src/mime.js +342 -0
  42. package/src/net.d.ts +11 -0
  43. package/src/net.js +29 -2
  44. package/src/pine.js +10 -1
  45. package/src/router.js +3 -3
  46. package/src/sandbox-linux.d.ts +3 -1
  47. package/src/sandbox-linux.js +5 -0
  48. package/src/security.d.ts +22 -6
  49. package/src/security.js +44 -13
  50. package/src/slots.d.ts +106 -0
  51. package/src/slots.js +250 -0
  52. package/src/source-types.d.ts +20 -0
  53. package/src/sources/calendar.d.ts +24 -0
  54. package/src/sources/calendar.js +265 -0
  55. package/src/sources/command.js +109 -4
  56. package/src/sources/discord.d.ts +4 -0
  57. package/src/sources/discord.js +298 -0
  58. package/src/sources/feed.d.ts +19 -0
  59. package/src/sources/feed.js +257 -0
  60. package/src/sources/http.js +154 -103
  61. package/src/sources/mail.d.ts +51 -0
  62. package/src/sources/mail.js +1013 -0
  63. package/src/sources/matrix.d.ts +4 -0
  64. package/src/sources/matrix.js +232 -0
  65. package/src/sources/modbus.d.ts +15 -0
  66. package/src/sources/modbus.js +240 -0
  67. package/src/sources/onvif.d.ts +35 -0
  68. package/src/sources/onvif.js +326 -0
  69. package/src/sources/presence.d.ts +80 -0
  70. package/src/sources/presence.js +480 -0
  71. package/src/sources/serial.d.ts +21 -0
  72. package/src/sources/serial.js +220 -0
  73. package/src/sources/slack.d.ts +16 -0
  74. package/src/sources/slack.js +1062 -0
  75. package/src/sources/smtp.d.ts +4 -0
  76. package/src/sources/smtp.js +360 -0
  77. package/src/sources/stream.d.ts +68 -0
  78. package/src/sources/stream.js +534 -0
  79. package/src/sources/syslog.d.ts +32 -0
  80. package/src/sources/syslog.js +243 -0
  81. package/src/sources/system.d.ts +14 -0
  82. package/src/sources/system.js +236 -0
  83. package/src/sources/system.swift +102 -0
  84. package/src/sources/telegram.js +34 -1
  85. package/src/sources.d.ts +41 -1
  86. package/src/sources.js +147 -24
  87. package/src/tools.d.ts +1 -1
  88. package/src/tools.js +304 -23
  89. package/src/tui/app.d.ts +35 -2
  90. package/src/tui/app.js +306 -43
  91. package/src/tui/levels.d.ts +68 -0
  92. package/src/tui/levels.js +273 -0
  93. package/src/tui/picture.d.ts +17 -1
  94. package/src/tui/picture.js +72 -5
  95. package/src/types.d.ts +3 -0
  96. package/src/update.d.ts +9 -1
  97. package/src/update.js +75 -3
  98. package/src/watching.d.ts +156 -0
  99. package/src/watching.js +609 -4
package/src/sources.d.ts CHANGED
@@ -29,6 +29,8 @@ export interface SourceApi {
29
29
  options: Record<string, any>;
30
30
  /** Folder that relative paths in the options are meant from. */
31
31
  base: string;
32
+ /** The port of pine's own control API, if it has one. */
33
+ controlPort?: number;
32
34
  /** A folder of its own for whatever it has to keep (received files, for example). */
33
35
  dataDir: string;
34
36
  log: Logger;
@@ -119,6 +121,21 @@ export interface SourceApi {
119
121
  output: string;
120
122
  truncated: boolean;
121
123
  }>;
124
+ /**
125
+ * Start a command that keeps running and get what it prints, line by line, as it comes: for
126
+ * `tail -F`, `log stream`, `docker events`. It runs with the same rights as `exec`. Resolves when
127
+ * the command has ended, with its exit code and the end of what it wrote as errors; rejects
128
+ * when it cannot be started. It is stopped with the source, or by `signal`.
129
+ *
130
+ * Not on Linux: what its sandbox cannot forbid there (making a file that is read as
131
+ * instructions) is taken away after a command, and a command that runs on has no "after".
132
+ */
133
+ follow(command: string, onLine: (line: string) => void, opts?: {
134
+ signal?: AbortSignal;
135
+ }): Promise<{
136
+ code: number;
137
+ error: string;
138
+ }>;
122
139
  /** Private storage that survives restarts. */
123
140
  kv: {
124
141
  get<T = unknown>(key: string): T | undefined;
@@ -159,6 +176,12 @@ export interface SourceInfo {
159
176
  };
160
177
  events: number;
161
178
  }
179
+ /** The settings every source has, whatever its type. A type's options cannot have these names. */
180
+ /**
181
+ * The conversation name that stands for "a new one for every event": the agent is woken in a conversation of its
182
+ * own, started empty and closed when it has answered, so that a source that reports all day does not pile up in one.
183
+ */
184
+ export declare const FRESH = "new";
162
185
  export declare class SourceHost {
163
186
  private cfg;
164
187
  private bus;
@@ -177,7 +200,8 @@ export declare class SourceHost {
177
200
  private offOut?;
178
201
  private approvals?;
179
202
  private globalRoutes;
180
- mediaRoots: string[];
203
+ /** Where each running source keeps the files it received (`media`), by the source's key. */
204
+ private media;
181
205
  /** Every source type there is: pine's own and the ones pine.json registers. `type` is what the module says about itself. */
182
206
  private types;
183
207
  constructor(deps: {
@@ -192,6 +216,14 @@ export declare class SourceHost {
192
216
  });
193
217
  /** Every configured source with its key: global ones by name, an agent's own as name@agent. */
194
218
  private all;
219
+ /** Every folder a running source keeps received files in: where an event's picture may lie. */
220
+ get mediaRoots(): string[];
221
+ /**
222
+ * The folders of received files that are an agent's to read: those of its own sources and of
223
+ * the sources one of its conversations, or a subscription for all agents, subscribes it to.
224
+ * Another agent's source is never among them: nobody else can be subscribed to it.
225
+ */
226
+ filesFor(agentId: string): string[];
195
227
  private subscribersOf;
196
228
  /** The agents a subscription for everyone reaches: those that can use the source and have no entry of their own for their main conversation. */
197
229
  private reached;
@@ -253,8 +285,12 @@ export declare class SourceHost {
253
285
  private route;
254
286
  private ensure;
255
287
  private launch;
288
+ /** A source's shell command, started the way the shell of the agent it belongs to would start it. Throws when it cannot be. */
289
+ private shell;
256
290
  /** A source's shell command, run the way the shell of the agent it belongs to would run it. */
257
291
  private exec;
292
+ /** A source's command that keeps running: what it prints is handed on line by line until it ends or is stopped. */
293
+ private follow;
258
294
  private halt;
259
295
  /**
260
296
  * The sources an agent can send through, with what sending does. A global one or its own;
@@ -264,7 +300,11 @@ export declare class SourceHost {
264
300
  name: string;
265
301
  type: string;
266
302
  sends: string;
303
+ toOwner: boolean;
304
+ files: boolean;
267
305
  }>;
306
+ /** Whether sending through this source reaches the owner and nobody else. The source's type says so, never the call. */
307
+ tellsOwner(agentId: string, name: string, session?: string): boolean;
268
308
  /** Send something out through a source, started if it is not running. Throws with the source's own reason if it refuses. */
269
309
  send(agentId: string, name: string, message: Record<string, any>, session?: string): Promise<string>;
270
310
  /** The handler for POST /hook/<key>, if a running source takes web requests under that name. */
package/src/sources.js CHANGED
@@ -7,6 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
7
7
  return path;
8
8
  };
9
9
  import { spawn } from "node:child_process";
10
+ import { StringDecoder } from "node:string_decoder";
10
11
  import fs from "node:fs";
11
12
  import path from "node:path";
12
13
  import { pathToFileURL } from "node:url";
@@ -17,7 +18,7 @@ import { Value } from "typebox/value";
17
18
  import { parseEnv } from "node:util";
18
19
  import { setEnv, unsetEnv } from "./env-file.js";
19
20
  import { editJson } from "./mcp-config.js";
20
- import { realish, bin, rootsFor, sandboxArgv, sandboxAvailable, sandboxGuard, shellEnv } from "./security.js";
21
+ import { realish, bin, rootsFor, sandboxArgv, sandboxAvailable, sandboxGuard, sandboxKind, shellEnv } from "./security.js";
21
22
  import { errText, parseDuration, resolvePath } from "./util.js";
22
23
  /** What pine's .env holds, read when asked: an entry the owner just added counts at once. */
23
24
  function envFile(home) {
@@ -33,9 +34,16 @@ export function refuse(status, message) {
33
34
  return Object.assign(new Error(message), { status });
34
35
  }
35
36
  /** The settings every source has, whatever its type. A type's options cannot have these names. */
37
+ /**
38
+ * The conversation name that stands for "a new one for every event": the agent is woken in a conversation of its
39
+ * own, started empty and closed when it has answered, so that a source that reports all day does not pile up in one.
40
+ */
41
+ export const FRESH = "new";
36
42
  const RESERVED_OPTIONS = ["type", "use", "description", "agents", "trust", "start", "enabled", "session"];
37
43
  /** The longest pause between two looks of a source whose looks keep failing (or its own interval, if that is longer). */
38
44
  const POLL_BACKOFF_MAX = 15 * 60_000;
45
+ /** The longest line a followed command hands on. */
46
+ const FOLLOW_LINE = 4000;
39
47
  const clock = (ts) => new Date(ts).toTimeString().slice(0, 8);
40
48
  /** Where the answers to a source's events are published; the source host passes them to the source. */
41
49
  const outTopic = (key) => `out/source/${key}`;
@@ -57,7 +65,8 @@ export class SourceHost {
57
65
  offOut;
58
66
  approvals;
59
67
  globalRoutes = [];
60
- mediaRoots = [];
68
+ /** Where each running source keeps the files it received (`media`), by the source's key. */
69
+ media = new Map();
61
70
  /** Every source type there is: pine's own and the ones pine.json registers. `type` is what the module says about itself. */
62
71
  types = new Map();
63
72
  constructor(deps) {
@@ -77,8 +86,29 @@ export class SourceHost {
77
86
  ...Object.values(this.cfg.agents).flatMap((a) => Object.entries(a.sources).map(([name, source]) => ({ key: `${name}@${a.id}`, name, scope: a.id, source }))),
78
87
  ];
79
88
  }
89
+ /** Every folder a running source keeps received files in: where an event's picture may lie. */
90
+ get mediaRoots() {
91
+ return [...this.media.values()].flat();
92
+ }
93
+ /**
94
+ * The folders of received files that are an agent's to read: those of its own sources and of
95
+ * the sources one of its conversations, or a subscription for all agents, subscribes it to.
96
+ * Another agent's source is never among them: nobody else can be subscribed to it.
97
+ */
98
+ filesFor(agentId) {
99
+ const agent = this.cfg.agents[agentId];
100
+ if (!agent)
101
+ return [];
102
+ const keys = new Set(Object.keys(agent.sources).map((name) => `${name}@${agentId}`));
103
+ for (const sub of [...agent.subscribe, ...this.cfg.subscribe]) {
104
+ const found = sourceFor(this.cfg, agentId, sub.source);
105
+ if (found)
106
+ keys.add(found.key);
107
+ }
108
+ return [...keys].flatMap((key) => this.media.get(key) ?? []);
109
+ }
80
110
  subscribersOf(key) {
81
- const own = Object.values(this.cfg.agents).flatMap((a) => a.subscribe.filter((sub) => sourceFor(this.cfg, a.id, sub.source)?.key === key).map((sub) => (sub.session === "main" ? a.id : `${a.id}/${sub.session}`)));
111
+ const own = Object.values(this.cfg.agents).flatMap((a) => a.subscribe.filter((sub) => sourceFor(this.cfg, a.id, sub.source)?.key === key).map((sub) => (sub.session === "main" ? a.id : sub.session === FRESH ? `${a.id} (a fresh conversation for every event)` : `${a.id}/${sub.session}`)));
82
112
  return this.cfg.subscribe.some((sub) => sub.source === key) ? ["all agents", ...own] : own;
83
113
  }
84
114
  /** The agents a subscription for everyone reaches: those that can use the source and have no entry of their own for their main conversation. */
@@ -244,7 +274,9 @@ export class SourceHost {
244
274
  for (const k of secretKeys)
245
275
  if (options[k] === "" || options[k] === null)
246
276
  delete options[k];
247
- const needs = secretKeys.filter((k) => options[k] === undefined && (ask.includes(k) || (type.options.required ?? []).includes(k))).map((k) => ({ name: k, label: `${k}: ${props[k].description ?? "a secret"}` }));
277
+ // (Required by the schema, named by the agent, or needed with these very options, which the type says.)
278
+ const wanted = type.needs?.(options) ?? [];
279
+ const needs = secretKeys.filter((k) => options[k] === undefined && (ask.includes(k) || (type.options.required ?? []).includes(k) || wanted.includes(k))).map((k) => ({ name: k, label: `${k}: ${props[k].description ?? "a secret"}` }));
248
280
  // One that is in pine's .env already is given by name; its value is looked up here, for the type to check, and never shown.
249
281
  const refs = {};
250
282
  for (const k of secretKeys) {
@@ -278,6 +310,7 @@ export class SourceHost {
278
310
  agent: agent.id,
279
311
  workspace: agent.workspace,
280
312
  home: this.cfg.home,
313
+ controlPort: this.cfg.http?.port,
281
314
  resolve: (p) => realish(p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : path.isAbsolute(p) ? p : path.join(agent.workspace, p)),
282
315
  random: (bytes) => crypto.randomBytes(bytes).toString("base64url"),
283
316
  envName: (option) => this.envName(name, forAll ? undefined : agent.id, option),
@@ -352,6 +385,8 @@ export class SourceHost {
352
385
  agent: agentId,
353
386
  session: sub.session,
354
387
  prompt: sub.prompt,
388
+ // A report about a message (a mail, a line in a channel) is shown whole: who wrote it and where is not in its text.
389
+ whole: Boolean(type && !type.talks),
355
390
  preface: `[You are subscribed to the event source "${name}" (${what}), and it has just reported the event below.${sub.note ? ` Your note for this subscription: ${sub.note}` : " Act on it as your instructions say."} If nothing needs doing, say so in one line.]`,
356
391
  label: `${name}: {{topic}}`,
357
392
  ...talk,
@@ -395,12 +430,16 @@ export class SourceHost {
395
430
  const dataDir = path.join(this.cfg.dataDir, "sources", key.replace(/[^A-Za-z0-9_@.-]/g, "_"));
396
431
  fs.mkdirSync(dataDir, { recursive: true, mode: 0o700 });
397
432
  const run = { stops: [] };
433
+ // Aborted when the source stops: what it left running (a followed command) ends with it.
434
+ const ended = new AbortController();
435
+ run.stops.push(() => ended.abort());
398
436
  const prefix = `source:${key}:`;
399
437
  const api = {
400
438
  name,
401
439
  key,
402
440
  options: source.options,
403
441
  base: source.base,
442
+ controlPort: this.cfg.http?.port,
404
443
  dataDir,
405
444
  log: this.log.child(key),
406
445
  emit: (event, payload, opts) => {
@@ -476,9 +515,10 @@ export class SourceHost {
476
515
  return before ? { previous: before.value } : undefined;
477
516
  },
478
517
  exec: (command, opts) => this.exec(key, command, opts),
518
+ follow: (command, onLine, opts) => this.follow(key, command, onLine, opts?.signal ? AbortSignal.any([opts.signal, ended.signal]) : ended.signal),
479
519
  kv: { get: (k) => this.kv.get(prefix + k), set: (k, v) => this.kv.set(prefix + k, v) },
480
520
  secret: (value) => this.redactor.add([value]),
481
- media: (dir) => void this.mediaRoots.push(realish(dir)),
521
+ media: (dir) => void this.media.set(key, [...new Set([...(this.media.get(key) ?? []), realish(dir)])]),
482
522
  http: (handler) => {
483
523
  if (!this.httpEnabled)
484
524
  throw new Error("this source receives web requests, which needs the control API (\"http\" in pine.json) to be on");
@@ -492,42 +532,58 @@ export class SourceHost {
492
532
  catch (e) {
493
533
  for (const fn of run.stops.reverse())
494
534
  await Promise.resolve(fn()).catch(() => { });
535
+ this.media.delete(key);
495
536
  throw e;
496
537
  }
497
538
  this.running.set(key, run);
498
539
  this.log.info(`source ${key} started`);
499
540
  }
500
- /** A source's shell command, run the way the shell of the agent it belongs to would run it. */
501
- exec(key, command, opts = {}) {
541
+ /** A source's shell command, started the way the shell of the agent it belongs to would start it. Throws when it cannot be. */
542
+ shell(key, command) {
502
543
  const agent = this.cfg.agents[key.includes("@") ? key.slice(key.lastIndexOf("@") + 1) : mainAgentId(this.cfg)];
503
544
  if (!agent)
504
- return Promise.reject(new Error("the agent this source belongs to is gone"));
545
+ throw new Error("the agent this source belongs to is gone");
505
546
  const roots = rootsFor(this.cfg, agent);
506
547
  // Where the agent's own shell is withheld because nothing could confine it, a source's command is not run either.
507
548
  if (!sandboxAvailable())
508
- return Promise.reject(new Error("there is no sandbox on this platform to run the command in, so it is not run"));
549
+ throw new Error("there is no sandbox on this platform to run the command in, so it is not run");
509
550
  // The variant of a run that has read outside content: what is read into the agent's prompt stays as it is.
510
551
  const argv = [...sandboxArgv(this.cfg, agent, roots, "restricted"), bin("bash"), "-c", command];
511
552
  // On Linux a protected file that did not exist cannot be forbidden, only taken away again.
512
553
  const guard = sandboxGuard(roots, "restricted");
554
+ const child = spawn(argv[0], argv.slice(1), { cwd: roots.workspace, env: shellEnv(agent, roots, {}), stdio: ["ignore", "pipe", "pipe"], detached: true });
555
+ // The whole group: a command that started others must not leave them behind.
556
+ const kill = () => {
557
+ try {
558
+ process.kill(-child.pid, "SIGKILL");
559
+ }
560
+ catch {
561
+ child.kill("SIGKILL");
562
+ }
563
+ };
564
+ return { child, guard, kill };
565
+ }
566
+ /** A source's shell command, run the way the shell of the agent it belongs to would run it. */
567
+ exec(key, command, opts = {}) {
513
568
  const max = opts.maxBytes ?? 256 * 1024;
514
569
  const timeoutMs = opts.timeoutMs ?? 30_000;
515
570
  return new Promise((resolve, reject) => {
516
571
  if (opts.signal?.aborted)
517
572
  return reject(new Error("stopped"));
518
- const child = spawn(argv[0], argv.slice(1), { cwd: roots.workspace, env: shellEnv(agent, roots, {}), stdio: ["ignore", "pipe", "pipe"], detached: true });
573
+ let sh;
574
+ try {
575
+ sh = this.shell(key, command);
576
+ }
577
+ catch (e) {
578
+ return reject(e);
579
+ }
580
+ const { child, guard } = sh;
519
581
  const chunks = [];
520
582
  let size = 0;
521
583
  let why = "";
522
- // The whole group: a command that started others must not leave them behind.
523
584
  const kill = (reason) => {
524
585
  why ||= reason;
525
- try {
526
- process.kill(-child.pid, "SIGKILL");
527
- }
528
- catch {
529
- child.kill("SIGKILL");
530
- }
586
+ sh.kill();
531
587
  };
532
588
  const take = (d) => {
533
589
  if (size < max)
@@ -555,12 +611,67 @@ export class SourceHost {
555
611
  });
556
612
  });
557
613
  }
614
+ /** A source's command that keeps running: what it prints is handed on line by line until it ends or is stopped. */
615
+ follow(key, command, onLine, signal) {
616
+ return new Promise((resolve, reject) => {
617
+ // Rule of the house: where the sandbox only cleans up after a command, a command without an end is not started.
618
+ if (sandboxKind() === "linux")
619
+ return reject(new Error("a command cannot be followed on Linux: its sandbox takes away what a command must not leave behind only after the command, and this one would not end. Run it again and again instead (without \"follow\")"));
620
+ if (signal.aborted)
621
+ return reject(new Error("stopped"));
622
+ let sh;
623
+ try {
624
+ sh = this.shell(key, command);
625
+ }
626
+ catch (e) {
627
+ return reject(e);
628
+ }
629
+ const { child, kill } = sh;
630
+ const text = new StringDecoder("utf8");
631
+ let rest = "";
632
+ const hand = (line) => {
633
+ // One line's trouble (a handler that throws) must not end the command.
634
+ try {
635
+ if (line.trim())
636
+ onLine(line.slice(0, FOLLOW_LINE));
637
+ }
638
+ catch (e) {
639
+ this.log.warn(`source ${key} failed on a line`, errText(e));
640
+ }
641
+ };
642
+ child.stdout.on("data", (d) => {
643
+ rest += text.write(d);
644
+ for (let at = rest.indexOf("\n"); at >= 0; at = rest.indexOf("\n")) {
645
+ hand(rest.slice(0, at).replace(/\r$/, ""));
646
+ rest = rest.slice(at + 1);
647
+ }
648
+ // A line that never ends is handed on in pieces, not kept.
649
+ if (rest.length > FOLLOW_LINE * 4) {
650
+ hand(rest);
651
+ rest = "";
652
+ }
653
+ });
654
+ let error = "";
655
+ child.stderr.on("data", (d) => (error = (error + d.toString("utf8")).slice(-2000)));
656
+ signal.addEventListener("abort", kill, { once: true });
657
+ child.on("error", (e) => (signal.removeEventListener("abort", kill), reject(new Error(`could not be started: ${errText(e)}`))));
658
+ child.on("close", (code) => {
659
+ signal.removeEventListener("abort", kill);
660
+ if (rest)
661
+ hand(rest);
662
+ if (signal.aborted)
663
+ return reject(new Error("stopped"));
664
+ resolve({ code: code ?? 1, error: error.trim() });
665
+ });
666
+ });
667
+ }
558
668
  async halt(key) {
559
669
  const run = this.running.get(key);
560
670
  if (!run)
561
671
  return;
562
672
  this.running.delete(key);
563
673
  this.statuses.delete(key);
674
+ this.media.delete(key);
564
675
  for (const fn of run.stops.reverse()) {
565
676
  try {
566
677
  await fn();
@@ -577,10 +688,14 @@ export class SourceHost {
577
688
  */
578
689
  senders(agentId, session = "main") {
579
690
  return this.available(agentId, session).flatMap((s) => {
580
- const sends = this.types.get(s.type)?.type?.sends;
581
- return sends ? [{ name: s.name, type: s.type, sends }] : [];
691
+ const type = this.types.get(s.type)?.type;
692
+ return type?.sends ? [{ name: s.name, type: s.type, sends: type.sends, toOwner: type.toOwner === true, files: type.files === true }] : [];
582
693
  });
583
694
  }
695
+ /** Whether sending through this source reaches the owner and nobody else. The source's type says so, never the call. */
696
+ tellsOwner(agentId, name, session = "main") {
697
+ return this.senders(agentId, session).some((s) => s.name === name && s.toOwner);
698
+ }
584
699
  /** Send something out through a source, started if it is not running. Throws with the source's own reason if it refuses. */
585
700
  async send(agentId, name, message, session = "main") {
586
701
  if (!this.senders(agentId, session).some((s) => s.name === name))
@@ -645,9 +760,10 @@ export class SourceHost {
645
760
  type: found.source.type ?? "custom",
646
761
  description: found.source.description,
647
762
  local: session === "main" ? undefined : subs.find((x) => x.session === session),
648
- agent: subs.find((x) => x.session === "main"),
763
+ // The agent as such listens in its main conversation, or (FRESH) in a new one for every event.
764
+ agent: subs.find((x) => x.session === "main") ?? subs.find((x) => x.session === FRESH),
649
765
  global: found.scope === "global" ? this.cfg.subscribe.find((x) => x.source === name) : undefined,
650
- elsewhere: subs.filter((x) => x.session !== session && x.session !== "main").map((x) => x.session),
766
+ elsewhere: subs.filter((x) => x.session !== session && x.session !== "main" && x.session !== FRESH).map((x) => x.session),
651
767
  },
652
768
  ];
653
769
  });
@@ -665,7 +781,11 @@ export class SourceHost {
665
781
  throw new Error(`unknown agent "${agentId}"`);
666
782
  if (!/^[a-z][a-z0-9_-]{0,39}$/.test(name))
667
783
  throw new Error(`"${name}" is not a usable source name: lowercase letters, digits, - and _, starting with a letter`);
668
- if (this.cfg.sources[name] || Object.values(this.cfg.agents).some((a) => a.sources[name]))
784
+ const other = Object.values(this.cfg.agents).find((a) => a.id !== agentId && a.sources[name]);
785
+ // Another agent's source cannot be subscribed to: saying so would send the caller down a road that ends at a refusal.
786
+ if (other)
787
+ throw new Error(`a source named "${name}" exists already, as a source of the agent ${other.id}, which only ${other.id} can be subscribed to. ${agentId ? `For ${agentId}` : "For this one"}: pick another name, or remove that one first (remove_source) if it was meant for ${agentId ?? "everyone"}`);
788
+ if (this.cfg.sources[name] || agent?.sources[name])
669
789
  throw new Error(`a source named "${name}" exists already; pick another name, or subscribe to that one`);
670
790
  const file = agent ? path.join(agent.dir, "agent.json") : path.join(this.cfg.home, "pine.json");
671
791
  const before = fs.readFileSync(file, "utf8");
@@ -815,8 +935,11 @@ export class SourceHost {
815
935
  if (!agent)
816
936
  throw new Error(`unknown agent "${agentId}"`);
817
937
  const found = sourceFor(this.cfg, agentId, name);
818
- if (!found)
819
- throw new Error(`"${name}" is not an event source ${agentId} can use. Available: ${this.available(agentId).map((s) => s.name).join(", ") || "none"}`);
938
+ if (!found) {
939
+ // A source set up for one agent, asked for on behalf of another: say whose it is and what to do instead.
940
+ const whose = Object.values(this.cfg.agents).find((a) => a.id !== agentId && a.sources[name]);
941
+ throw new Error(`"${name}" is not an event source ${agentId} can use. Available: ${this.available(agentId).map((s) => s.name).join(", ") || "none"}${whose ? `. "${name}" is a source of the agent ${whose.id}, and a source belongs to the agent it was set up for. For ${agentId} to be woken by it: remove it (remove_source) and set it up for ${agentId} (add_source with "agent": "${agentId}" and a note)` : ""}`);
942
+ }
820
943
  if (!found.source.enabled)
821
944
  throw new Error(`the source "${name}" is disabled in the configuration`);
822
945
  const clean = this.clean(name, raw);
package/src/tools.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { type AgentConfig } from "./config.ts";
2
- import type { AgentManager, Live, Profile } from "./agents.ts";
2
+ import { type AgentManager, type Live, type Profile } from "./agents.ts";
3
3
  /**
4
4
  * The tools that are about what an agent has: event sources and subscriptions, MCP servers,
5
5
  * schedules, skills. The main agent calls each of them for another agent too (see the end of pineTools).