@pmndre/pine 0.22.0 → 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
@@ -45,7 +45,7 @@ scans", or `pine unsubscribe main scans`.
45
45
  ```json
46
46
  "sources": {
47
47
  "<name>": {
48
- "type": "folder | mqtt | webhook | ftp | telegram | http | command",
48
+ "type": "folder | mqtt | webhook | ftp | telegram | http | command | feed | ...",
49
49
  "description": "one line, shown to agents and in listings",
50
50
  "...": "the options of the type, see below"
51
51
  }
@@ -54,7 +54,7 @@ scans", or `pine unsubscribe main scans`.
54
54
 
55
55
  | Key | Default | Meaning |
56
56
  |---|---|---|
57
- | `type` | | One of the built-in types below, or a type of your own registered under `sourceTypes` (see "A source type of your own"). Or `use` instead: the path of a module, for a one-off. |
57
+ | `type` | | One of the built-in types: the seven everyday ones below, and the ones in [source-types.md](source-types.md) (`feed`, `calendar`, `stream`, `mail`, `slack`, `matrix`, `discord`, `smtp`, `syslog`, `system`, `presence`, `modbus`, `serial`, `onvif`). Or a type of your own registered under `sourceTypes` (see "A source type of your own"). Or `use` instead: the path of a module, for a one-off. |
58
58
  | `description` | | What it reports. Agents choose what to subscribe to by this line, so write it for them. |
59
59
  | `agents` | all | In `pine.json` only: the agents that may subscribe, e.g. `["house"]`. |
60
60
  | `trust` | `"untrusted"` | Who its events speak for. See "Trust" below. |
@@ -82,6 +82,10 @@ but a schedule: [events.md](events.md), "Schedules".
82
82
 
83
83
  ## The built-in types
84
84
 
85
+ These are the seven everyday types. Fourteen more, for feeds, calendars, services that push,
86
+ mail, chat, devices and the computer itself, are in [source-types.md](source-types.md),
87
+ together with a table of which type reaches which service.
88
+
85
89
  ### folder
86
90
 
87
91
  A folder: reports every new or changed file once it has stopped growing.
@@ -173,7 +177,8 @@ scanners and other devices whose way of sending a file is "upload to FTP server"
173
177
 
174
178
  Event `upload`: `{ file, path, size, from, images? }`. `file` is the name the device gave it,
175
179
  `path` is where it lies now (`data/sources/<name>/files/`, or `data/sources/<name>@<agent>/files/`
176
- for an agent's own source).
180
+ for an agent's own source). A picture is shown to the agent with the event. A video or any
181
+ other file is not: the agent reads it from `path` (see "Files a source received").
177
182
 
178
183
  It speaks plain FTP, as these devices do, so the password crosses your network unencrypted. It
179
184
  only receives: nothing can be listed, read, changed or deleted through it, and every file lands
@@ -230,7 +235,8 @@ What makes it different from the other types:
230
235
  - **It speaks for you.** Telegram vouches for the account and you proved it is yours, so what
231
236
  it writes counts as your own words: full tools, no "outside content" mark. That is why
232
237
  pairing takes a code and why the set-up is always put to you.
233
- - **It can send.** The agent writes to you on its own with the `send` tool; see below.
238
+ - **It can send.** The agent writes to you on its own with the `send` tool, with a picture or
239
+ a video if it has one to show, and without a question to you; see below.
234
240
  - **Messages are not held back.** The ten-second pause between events that protects a model from
235
241
  a chatty device does not apply unless the subscription sets a `throttle` itself.
236
242
 
@@ -258,9 +264,15 @@ a status page, a device on your network that has a state page.
258
264
  | Option | Default | |
259
265
  |---|---|---|
260
266
  | `url` | | The address, `https://...` (`http://` for a device on the local network). |
261
- | `every` | `"5m"` | How often to look. At least `"30s"` when an agent sets it up. |
262
- | `path` | | For an answer in JSON: watch only this field, `"data.price"` or `"items.0.state"`. |
267
+ | `every` | `"5m"` | How often to look. At least `"30s"` when an agent sets it up, and at least `"2m"` with `render`. |
268
+ | `path` | | For an answer in JSON: watch only this field, `"data.price"` or `"items.0.state"`. `path`, `values`, `match` and `select` are four ways to say what counts in the answer; a source takes one of them. |
263
269
  | `match` | | For a page or text: watch only what this regular expression finds, its first group if it has one. It is looked for in what a reader of the page sees, then in the page's source. |
270
+ | `select` | | For a page: watch only the text of the first element this CSS selector matches, `".product .price"` or `"#stock > span"`. With `render` it is any selector a browser reads. |
271
+ | `attr` | | With `select`: the value of this attribute of the element instead of its text, `"content"` for a meta tag, `"data-price"`. |
272
+ | `render` | `false` | `true` for a page that a script fills in after loading: every look opens the page in pine's browser, without a window, and takes what a reader sees then. See "A page that a script fills in". Not together with `path`, `values`, `method`, `body`, `headers`, `token` or `tokenHeader`. |
273
+ | `values` | | For an answer in JSON: several fields at once, each under a name of your own: `{ "price": "data.price", "stock": "data.stock.count" }`. Twenty at most. |
274
+ | `method` | `"GET"` | `"POST"` for an address that is asked by sending something. Nothing else: a source only looks. |
275
+ | `body` | | With `POST`: what to send, as text. Sent as JSON when it is JSON. Not for secrets. |
264
276
  | `headers` | | Headers to send, `{ "accept": "application/json" }`. Not for secrets. |
265
277
  | `token` | | An access token or key, sent as `Authorization: Bearer <token>`. Kept in `.env`. |
266
278
  | `tokenHeader` | | Send the token as this header instead, as it is: `"x-api-key"`, `"cookie"`. |
@@ -268,15 +280,185 @@ a status page, a device on your network that has a state page.
268
280
 
269
281
  | Event | | |
270
282
  |---|---|---|
271
- | `changed` | `{ url, value, previous }` | With `path` or `match`: the value now and before. |
283
+ | `changed` | `{ url, value, previous, number?, previousNumber? }` | With `path`, `match` or `select`: the value now and before. |
284
+ | `changed` | `{ url, values, previous, changed }` | With `values`: all the fields now and before, and the names of those that differ. |
272
285
  | `changed` | `{ url, added, removed, more? }` | Without: the lines that are new and the lines that are gone, up to 30 of each. |
273
286
  | `down` | `{ url, error, looks }` | After three failed looks in a row, once. |
274
287
  | `up` | `{ url }` | When it answers again. |
275
288
 
276
- Without `path` or `match` the whole answer counts. For a page that is its text as a reader
289
+ Without `path`, `values`, `match` or `select` the whole answer counts. For a page that is its text as a reader
277
290
  sees it: scripts, styles and markup are left out, so a counter in a script does not report a
278
291
  change at every look. A page that shows the time still does; give it a `match`.
279
292
 
293
+ #### One element of a page
294
+
295
+ `match` finds a value by the text around it; `select` finds it by where it stands in the page,
296
+ which holds better when the words around a price change with the language or the season:
297
+
298
+ ```json
299
+ "fridge": { "type": "http", "url": "https://shop.example/fridge-3000", "select": ".product-detail .price", "every": "30m", "description": "the price of the fridge" }
300
+ ```
301
+
302
+ A selector is made of tags (`span`), ids (`#total`), classes (`.price`), attributes (`[itemprop]`,
303
+ `[itemprop=price]`, also `~=`, `^=`, `$=`, `*=`), put together (`span.price`, `li.item.sale`) and
304
+ nested with a space (somewhere inside) or `>` (directly inside); a comma separates alternatives.
305
+ Nothing with a colon (`:first-child`, `:not(...)`) and no `+` or `~`: such a selector is refused
306
+ with what it takes instead. The first element in the page that matches counts. Many shops also
307
+ state the price for machines, which changes less often than the layout:
308
+
309
+ ```json
310
+ "fridge": { "type": "http", "url": "https://shop.example/fridge-3000", "select": "meta[property=product:price:amount]", "attr": "content" }
311
+ ```
312
+
313
+ The page is read as the server sends it. What a script fills in after loading is not
314
+ there: for such a page set `render`, or watch the address the script itself asks (see "A
315
+ page that a script fills in").
316
+
317
+ #### A page that a script fills in
318
+
319
+ Many pages arrive almost empty, and a script of the page then fetches the price or the state
320
+ and writes it in. A plain look reads the page as the server sends it, so it finds the
321
+ placeholder ("loading", an empty element, nothing at all) and never the value. With `render`
322
+ the look is made by a browser:
323
+
324
+ > The price on https://shop.example/fridge-3000 only shows up after the page has loaded. Watch
325
+ > it and tell me when it drops.
326
+
327
+ ```json
328
+ "fridge": { "type": "http", "url": "https://shop.example/fridge-3000", "render": true, "select": ".product-detail .price", "every": "30m", "description": "the price of the fridge" }
329
+ ```
330
+
331
+ At every look pine starts its browser (the one the browser tools use, which `pine init` and
332
+ `pine browser-install` fetch), without a window and with an empty profile, opens the address,
333
+ waits until the page has loaded and then until it has stopped asking for things (five seconds
334
+ at most), and takes what a reader sees. Then the browser is closed. What counts is chosen as
335
+ without `render`:
336
+
337
+ | With | What counts |
338
+ |---|---|
339
+ | `select` | The text of the first element the selector matches, as the browser shows it. The browser reads the selector, so everything CSS has works: `li:nth-child(2) .price`, `.offer:not(.sold-out)`, `h1 + p`. No element matches: the value is `null`. |
340
+ | `select` and `attr` | The value of that attribute of the element. |
341
+ | `match` | What the regular expression finds in the text a reader sees. The page's source is not looked at. |
342
+ | neither | The whole text of the page, line by line; an event names the lines that are new and gone. |
343
+
344
+ The events are the same, and an amount arrives as `number` as described below.
345
+
346
+ **What it costs.** A plain look is one request and takes a moment. A rendered look starts a
347
+ browser, runs the page's scripts and loads everything the page loads: a second or two and a
348
+ few hundred megabytes of memory while it lasts, at every look. So:
349
+
350
+ - `every` is at least `"2m"` when an agent sets the source up.
351
+ - Two browsers run at a time, for all sources together. A look that finds them busy waits.
352
+ - A look may take 45 seconds. After that it is ended and counts as failed.
353
+ - There is no "nothing new" answer (see below): the page is loaded in full each time.
354
+
355
+ **When the plain look is the better choice.** A script that fills a page in gets the value
356
+ from somewhere, usually an address that answers JSON. If you can find it (the network tab of
357
+ your browser's developer tools shows what the page asks), watch that address without `render`
358
+ and with `path`: it is faster, it can be asked every 30 seconds, a number arrives as a number,
359
+ it can take a `token`, and it does not break when the shop changes its layout. Use `render`
360
+ when there is no such address, when it cannot be asked from outside the page, or when what you
361
+ want is what the page shows.
362
+
363
+ **What does not go with it.** A set-up with one of these and `render` is refused, with the
364
+ reason:
365
+
366
+ | Option | Why not |
367
+ |---|---|
368
+ | `path`, `values` | They read an answer in JSON. There is no page to render. Leave `render` out. |
369
+ | `method`, `body` | A rendered page is asked the way a reader's browser asks it. |
370
+ | `headers`, `token`, `tokenHeader` | The browser would send them with every request the page makes, to every address the page loads from. So a page behind a login cannot be watched this way. |
371
+ | `local: true` | See below: a name that has to be looked up is not opened on your network. |
372
+
373
+ **What the page can reach.** The page's own scripts run in that browser, as they would in
374
+ yours, and the dialog you confirm says so. What they can reach is narrower than in yours:
375
+
376
+ - Every connection of that browser goes through the same guard as the browser tools'
377
+ ([security.md](security.md)). The public internet is reachable. Your own network and this
378
+ computer are not: not for the page, and not for anything the page loads or its scripts ask.
379
+ - One exception, which is the page itself: an address that says by itself that it is local
380
+ (`localhost`, a `.local` name, an IP address in a private range) is opened, and the browser
381
+ then reaches exactly that host and port and nothing else on your network. The dialog names
382
+ it.
383
+ - A name that only turns out to be local when it is looked up (`nas.home`, `ha.lan`) is not
384
+ opened with `render`, also not with `local: true`: what such a name points at can change,
385
+ and a page's scripts would run there. Give the device by its IP address.
386
+ - pine's own control port is never opened.
387
+ - The look counts only if the browser ends up on the host that was set up. A page that sends
388
+ it on to another host is a failed look that names the host.
389
+ - The browser keeps nothing from one look to the next (no cookies, no logins), downloads
390
+ nothing, and grants the page no permission (camera, location, notifications). A window the
391
+ page opens is closed.
392
+
393
+ What such a source reports is outside content, like everything an `http` source reports.
394
+
395
+ **When a look fails.** A failed look is retried with a growing pause, and `pine sources` shows
396
+ since when it fails and why; after three in a row the source reports `down`, and `up` when the
397
+ page opens again.
398
+
399
+ | The status says | What it means |
400
+ |---|---|
401
+ | `pine's browser is not installed on this computer` | Type `pine browser-install` into a terminal. `pine init` and `pine update` do it too. |
402
+ | `the page did not finish loading within 45 s` | The page is slow, or never finishes. |
403
+ | `"select" is not a CSS selector the browser can read` | The selector has a mistake in it. |
404
+ | `it sends on to <host>, which is not the address that was confirmed` | The page moved. Set the source up with the address it leads to, if that is the right one. |
405
+ | `<host> leads to an address on your own network` | The name points into your network. With `render` only an address that says so itself is opened there. |
406
+ | `it answered 403` (or another number) | The site turned the browser away. Some sites do that to a browser without a window. |
407
+ | `the browser could not load it (...)` | No connection, an invalid certificate, or the like; the words in brackets are the browser's. |
408
+
409
+ `found nothing with the selector` is not a failed look: the page opened and no element matched.
410
+ If the value is there in your own browser, the selector is wrong, or the page fills the
411
+ element in later than the look waits.
412
+
413
+ #### An amount as a number
414
+
415
+ A value that reads as a number or an amount, and nothing else, also arrives as `number` (and
416
+ the one before as `previousNumber`), so that a subscription can compare it:
417
+
418
+ ```json
419
+ "subscribe": [{ "source": "fridge", "when": { "payload.number": { "lt": 500 } }, "note": "Tell me: the fridge is under 500 now." }]
420
+ ```
421
+
422
+ | The value | `number` |
423
+ |---|---|
424
+ | `12.5`, `"12.5"`, `"12,5"`, `"87 %"`, `"-3,5 °C"`, `"3 GB"` | 12.5, 12.5, 12.5, 87, -3.5, 3 |
425
+ | `"$1,299.00"`, `"1.299,00 €"`, `"1 299,00 kr"`, `"1'299.50"` | 1299, 1299, 1299, 1299.5 |
426
+ | `"1,299"`, `"1.299"` | 1299 and 1.299: as a program writes numbers |
427
+ | `"1.299 €"`, `"1,299 €"` | 1299 and 1.299: next to `€`, `zł`, `kr` or `Kč` a dot groups thousands and a comma is the decimal point |
428
+ | `"1.2.3"`, `"12:30"`, `"2026-05-01"`, `"about 5"`, `"sold out"` | none |
429
+
430
+ The one case that can be read two ways is a single separator followed by exactly three digits,
431
+ and the last two rows are how it is decided. Where that is not what the page means, take the
432
+ digits apart with `match` (`"([0-9]+)[.,][0-9]{3} "`) and compare the text.
433
+
434
+ #### Several fields, and an address that is asked with POST
435
+
436
+ ```json
437
+ "fridge": {
438
+ "type": "http", "url": "https://shop.example/graphql", "method": "POST",
439
+ "body": "{\"query\": \"{ product(id: 7) { price stock { count } } }\"}",
440
+ "values": { "price": "data.product.price", "stock": "data.product.stock.count" },
441
+ "every": "30m", "description": "price and stock of the fridge"
442
+ }
443
+ ```
444
+
445
+ One event says which of the fields changed: `{ "values": { "price": 479, "stock": 3 },
446
+ "previous": { "price": 499, "stock": 3 }, "changed": ["price"] }`. A field that is not in the
447
+ answer is `null`. Since these are the values of the JSON itself, numbers are numbers and
448
+ `when` compares them directly: `{ "payload.values.stock": { "gt": 0 } }`.
449
+
450
+ A `POST` is for asking, and what it sends is shown to you in full before the source is set up:
451
+ a source repeats it on a clock, with nobody there.
452
+
453
+ #### Nothing new
454
+
455
+ An address that names a version of its answer (`ETag`, `Last-Modified`) is asked "anything new
456
+ since?" from the second look on, and answers with one line when there is not. That is a look
457
+ like any other, only cheaper for both sides. `feed` and `calendar` ask the same way. A look
458
+ with `render` loads the page in full every time.
459
+
460
+ #### Which addresses it asks
461
+
280
462
  An address on your own network or this computer is said to be one in the dialog you confirm.
281
463
  Any other address has to stay on the public internet: if its name one day leads into your
282
464
  network, the look fails and says so instead of fetching from there.
@@ -288,12 +470,17 @@ it is stored and shown like the rest of the address.
288
470
 
289
471
  Refused when it is set up: a user name or password in the address, `path` and `match`
290
472
  together, and a header that carries a secret (`authorization`, `cookie`), which belongs into
291
- `token`. One look may take 20 seconds and follow five redirects.
473
+ `token`. Also more than one of `path`, `values`, `match` and `select`; `attr` without
474
+ `select`; a selector that cannot be read; a `method` other than `GET` and `POST`; a `body`
475
+ without `POST` or longer than 20000 characters; `values` that are empty, more than twenty, or
476
+ under a name that is not a plain word. One look may take 20 seconds and follow five redirects.
292
477
 
293
478
  ### command
294
479
 
295
480
  A command that is run again and again. For what only a command can tell: free disk space, a
296
481
  build, a branch that moved, the end of a log, whether a machine answers.
482
+ A command that keeps running and prints a line whenever something happens is followed instead
483
+ of run again and again: see "Following a command that keeps running" below.
297
484
 
298
485
  > Tell me when the disk is more than 90% full.
299
486
 
@@ -324,10 +511,64 @@ time is a failed look (see below), not an event. `timeout` is at least `"1s"`, a
324
511
  line of more than 2000 characters is refused (put it into a script). If the agent's sandbox is
325
512
  switched off, the command runs without one, as its shell does.
326
513
 
514
+ #### Following a command that keeps running
515
+
516
+ Some commands tell by themselves when something happens: `tail -F` a log, `log stream`,
517
+ `docker events`, `kubectl get pods -w`, the client of a broker or a database. With `follow`
518
+ the command is started once and kept running, and every line it prints is an event as it
519
+ comes. This is the type for every protocol that has a command line client and no source type
520
+ of its own.
521
+
522
+ > Tell me when the backup log says ERROR.
523
+
524
+ ```json
525
+ "backup": { "type": "command", "run": "tail -n 0 -F ~/Library/Logs/backup.log", "follow": true, "match": "ERROR (.*)", "description": "errors in the backup log" }
526
+ ```
527
+
528
+ | Option | Default | |
529
+ |---|---|---|
530
+ | `follow` | `false` | `true`: start the command once, keep it running, report each line it prints. `every` and `timeout` are not used then. |
531
+ | `perMinute` | `30` | With `follow`: report at most this many lines a minute. The rest are counted, and the next line that is reported carries the count as `dropped`. |
532
+ | `match` | | With `follow`: only lines in which this regular expression finds something. Its first group is the line's `value`. |
533
+
534
+ | Event | | |
535
+ |---|---|---|
536
+ | `line` | `{ command, line, value?, dropped? }` | One line the command printed. `value` is what `match` found, or the parsed line when it is JSON. |
537
+ | `ended` | `{ command, code?, error?, ran }` | The command ended (`ran`: after how many seconds, `error`: the end of what it wrote as errors). It is started again, after a pause that grows while it keeps ending at once. A command that ends the moment it is started is reported once, not at every try. |
538
+
539
+ | What to follow | `run` |
540
+ |---|---|
541
+ | A log file | `tail -n 0 -F /path/app.log` (`-n 0`: only what is written from now on; `-F`: also after the file was rotated) |
542
+ | The Mac's own log | `log stream --style ndjson --predicate 'subsystem == "com.apple.TimeMachine"'` |
543
+ | Docker | `docker events --format '{{json .}}'` |
544
+ | Kubernetes | `kubectl get pods -w -o json`, `kubectl get events -w` |
545
+ | systemd's journal, on another machine | `ssh nas journalctl -f -p warning -o json` |
546
+ | PostgreSQL `LISTEN` | a few lines of script around a client library that print each notification as a line |
547
+ | Redis | `redis-cli --raw subscribe alerts` |
548
+ | NATS, Kafka, RabbitMQ | `nats sub 'orders.>'`, `kcat -C -b broker -t topic -o end`, `amqp-consume -q queue cat` |
549
+ | A folder on another machine | `ssh nas inotifywait -m -e close_write /volume1/scans` |
550
+
551
+ A line is cleaned of the colour codes a terminal would act on and cut at 2000 characters; a
552
+ line that is JSON also arrives parsed, so a subscription's `when` can look into it
553
+ (`{"payload.value.status": "die"}` for a container that stopped).
554
+
555
+ The command runs in the same sandbox as one that is run again and again: the agent's own, as
556
+ in `safe` mode. That is why most of the examples above need something from you first: the log
557
+ file has to be readable by the agent (`sandbox.read`), and a client that talks to the network
558
+ needs `sandbox.network`. The dialog shows the command line, and that it will keep running.
559
+
560
+ On Linux `follow` is refused. The sandbox there cannot forbid a running command to make a file
561
+ that is read as instructions; pine takes such a file away after a command has ended, and a
562
+ followed command does not end. Run it again and again instead (`every`, with a `match`), or
563
+ have the command's lines sent to a `syslog` or `webhook` source.
564
+
565
+ When the source stops (the last subscriber left, or pine stops), the command and everything
566
+ it started is ended with it.
567
+
327
568
  ### Looking again and again
328
569
 
329
- `http` and `command` cannot be told when something happens; they go and look. Three things
330
- hold for every source that does:
570
+ `http`, `command`, `feed`, `calendar`, `modbus` and `presence` cannot be told when something
571
+ happens; they go and look. Three things hold for every source that does:
331
572
 
332
573
  - **The first look is the starting point.** Setting a source up reports nothing. Only what is
333
574
  different at a later look does.
@@ -354,16 +595,44 @@ tool says which can and what each takes:
354
595
 
355
596
  | Type | Sending does | The agent passes |
356
597
  |---|---|---|
357
- | `telegram` | A message to you, in your chat with the bot | `text` |
598
+ | `telegram` | A message to you, in your chat with the bot, with a picture, a video or a sound file if the agent has one to show | `text`, and optionally `file`: the path of a picture, video or sound file in its workspace |
358
599
  | `mqtt` | A message to a topic on the source's `publish` list, to act on a device | `data`: `{ "topic": "lamp/set", "message": "on" }`, optionally with `retain` and `qos` |
359
600
 
360
601
  > When the print is done, tell me on Telegram and switch the enclosure light off.
361
602
 
362
603
  Where things may go is the source's to decide, not the agent's: Telegram sends to your chat and
363
604
  nowhere else, MQTT only to the topics you listed. An answer to a message that came in through
364
- Telegram is sent back by itself; `send` is for what the agent says unasked. In a conversation
365
- that has read outside content, `send` asks you first
366
- ([security.md](security.md), "What asks you").
605
+ Telegram is sent back by itself; `send` is for what the agent says unasked.
606
+
607
+ ### A picture or a video with the message
608
+
609
+ > When the camera sees somebody at the door, send me the picture on Telegram.
610
+
611
+ `send` takes a `file` next to the `text`: the path of a picture (jpg, png, webp, gif), a video
612
+ (mp4, mov, webm) or a sound file in the agent's workspace. Through Telegram the picture or the
613
+ video arrives in your chat with the text under it as its caption; a text longer than a caption
614
+ may be (1024 characters) is sent first, by itself. A picture up to 10 MB is shown as a photo, a
615
+ larger one comes as a file, and Telegram takes up to 50 MB from a bot: a long clip the agent
616
+ scales down first (`ffmpeg -i clip.mp4 -vf scale=960:-2 -an small.mp4`). A file a source
617
+ received (a camera's upload) lies outside the workspace: the agent copies it, or the frame it
618
+ took from it, into its workspace and sends that. Only a picture, video or sound file is sent
619
+ this way, and only from the workspace. A source that takes no file (MQTT) says so.
620
+
621
+ ### Telling you needs no approval
622
+
623
+ An agent that watches a camera, a device or a page messages you when you are not there, and
624
+ by then it has read outside content: the upload, the reading, the page. A message to you is
625
+ still never held back for your approval. `send` through Telegram goes out at once, in every
626
+ conversation and in a run that an event woke, with nobody at the keyboard. That is what lets
627
+ an agent alert you unattended: "tell me on Telegram when somebody is at the door" works
628
+ without a yes for each message.
629
+
630
+ What makes this safe is the source, not the agent: the Telegram source writes to the chat you
631
+ paired or listed and refuses every other recipient, so a message leaves nothing with anybody
632
+ but you. `send` through a source that acts on something (MQTT) does ask you first in a
633
+ conversation that has read outside content ([security.md](security.md), "What asks you").
634
+ To approve each message yourself all the same, put `"send:telegram"` (with the source's name)
635
+ on the agent's `approve` list.
367
636
 
368
637
  A [route](events.md) can send the same way: `"reply": { "topic": "out/source/telegram@main" }`
369
638
  puts an agent's answer on Telegram, and an event published on `out/source/<name>` goes out
@@ -388,6 +657,27 @@ the agent. Several scopes can be on at once (a side conversation and the agent,
388
657
  gets its own turn. An agent whose main conversation has an entry of its own is not woken a
389
658
  second time by a global one.
390
659
 
660
+ ### A fresh conversation for every event
661
+
662
+ > Watch the camera. Judge every clip by itself, in a fresh conversation each time.
663
+
664
+ A source that reports all day (a camera, a sensor, a busy folder) would fill one conversation
665
+ with hundreds of events: it grows, it is shortened again and again, and what an early event
666
+ said colours how a late one is read. An agent can be woken differently: with `fresh` on its
667
+ `subscribe` tool (`"session": "new"` in the configuration, `--fresh` on `pine subscribe`),
668
+ every event starts a conversation of its own. It holds the agent's instruction files, the note
669
+ and that one event, and it is closed when the agent has answered.
670
+
671
+ - It is the agent that listens this way, not one conversation: the agent scope, asked for in
672
+ its main conversation without a question, from a side conversation with one. As an agent it
673
+ listens in one place: asking for the main conversation ends the fresh one, and the other way round.
674
+ - Nothing of one event is there in the next. What the agent has to know between them (what
675
+ it saw an hour ago, what you told it) it keeps in files in its workspace and reads when it
676
+ is woken; say so in its instructions. Its `MEMORY.md` is in every such conversation as in any other.
677
+ - Its main conversation stays for you: what you write on Telegram arrives there, and it is
678
+ not marked as having read outside content by what the source reports.
679
+ - Several events can be worked on at once, up to `limits.maxConcurrentRuns`.
680
+
391
681
  "Closed" means: its tab is closed in the terminal UI, it is reset (`/reset`, `pine reset`), or
392
682
  it is removed from the agent's list of conversations. Quitting the UI closes nothing: the same
393
683
  tabs open again next time, and what they listen to carries on in between. A conversation that
@@ -400,7 +690,7 @@ Every agent has these tools for it:
400
690
  | Tool | |
401
691
  |---|---|
402
692
  | `sources` | Lists the sources it can use and what is subscribed: this conversation, the agent, all agents, its other conversations. "What are you subscribed to?" always has an answer. |
403
- | `subscribe`, `unsubscribe` | For a source that exists. |
693
+ | `subscribe`, `unsubscribe` | For a source that exists. With `fresh: true` on `subscribe` the agent is woken in a new conversation for every event instead of its main one. |
404
694
  | `add_source` | Sets up a new source and, when it is given a note on what to do, subscribes to it in the same step: "watch my project folder", "tell me when the price drops", "listen to the printer". It then runs at once, without a restart. Without a note the source is only set up. |
405
695
  | `remove_source` | Deletes a source for good, with its subscriptions. |
406
696
  | `add_source_type`, `remove_source_type` | Only the main agent: brings a new kind of source into pine, or takes it out. See "A source type of your own". |
@@ -554,7 +844,7 @@ The same key in `pine.json` is the global scope.
554
844
  | `when` | | Only events that match. Same filter as in [routes](events.md): keys are paths such as `payload.file`, values are compared, or `{ "regex": ... }`, `{ "gt": ... }`, `{ "in": [...] }`. |
555
845
  | `throttle` | `"10s"` | After one event, ignore the source for this long. Protects the model from a chatty device; `"0s"` turns it off. |
556
846
  | `debounce` | | Wait for this long without a new event, then handle only the last one. |
557
- | `session` | `main` (`on-<source>` with `separate`) | The conversation that listens. Leaving it out is the agent scope. |
847
+ | `session` | `main` (`on-<source>` with `separate`) | The conversation that listens. Leaving it out is the agent scope. `"new"`: a fresh conversation for every event, closed when it is answered ("A fresh conversation for every event"). |
558
848
  | `separate` | `false` | `true`: do not deliver into a conversation of yours, but into one of its own (`on-<source>`), with the reduced tool set for sources that are not yours. See "Trust". |
559
849
  | `prompt` | | Replaces the standard text for the event. Templates as in routes: `{{payload.file}}`. |
560
850
 
@@ -583,6 +873,27 @@ reported, followed by the agent's answer; if no tab has that conversation open,
583
873
  when you are not looking, the agent uses its `send` tool with a source that can send, Telegram for example: say so in the note
584
874
  or in its `AGENTS.md`.
585
875
 
876
+ ### Files a source received
877
+
878
+ A camera uploads a picture or a video clip, a scanner a PDF, you send a photo through
879
+ Telegram. A source that receives files (`ftp`, `telegram`) keeps them in a folder of its own
880
+ in pine's data folder, `data/sources/<name>/`, and the event says where the file lies (`path`).
881
+ An agent can open and read the files of its own sources and of every source it is subscribed
882
+ to: with `read`, and in its shell (`cp`, `ffmpeg`, a script). The folder a `folder` source
883
+ watches is read the same way.
884
+
885
+ It reads these files and does not change or delete them: pine keeps them and removes them when
886
+ their time is up (`keepDays`). To change a file, the agent copies it into its workspace and
887
+ works on the copy. Everything else in pine's data folder stays closed, and so do the uploads
888
+ of a source the agent is not subscribed to: access to those is blocked. When the subscription
889
+ ends, the access ends with it.
890
+
891
+ Only a picture is shown to the model together with the event (jpg, png, webp, gif, under
892
+ 10 MB). A video clip, a sound file or a PDF is not shown: the event carries its `path`, and
893
+ the agent opens the file itself. To look at a video it takes single pictures out of the clip
894
+ in its workspace, for example `ffmpeg -i <path> -vf fps=1 frames/%03d.jpg` where `ffmpeg` is
895
+ installed, and looks at those with `read`.
896
+
586
897
  ## Trust
587
898
 
588
899
  What a source reports is **outside content** unless the source is yours: a file name, a web
@@ -592,7 +903,8 @@ An event is therefore handed to the agent framed as data (see above), and the co
592
903
  arrives in is marked as having read outside content, exactly as after the agent read a web
593
904
  page there. From then on the usual rules of [security.md](security.md) apply in that
594
905
  conversation: actions that send information out ask you before they run,
595
- and bypass mode is paused.
906
+ and bypass mode is paused. Telling you is not among them: the agent still reaches you through
907
+ Telegram without a question ("Sending through a source").
596
908
 
597
909
  `"trust": "owner"` on a source says: this is my own device, and nobody else can make it say
598
910
  things. Its events then leave no mark. Use it for a
@@ -713,6 +1025,8 @@ it will do in a dialog that has a field for the token, which goes into `.env`. I
713
1025
  | `options` | The options as a JSON schema of an object. Give every property a `description`. `"secret": true` on a property keeps its value in `.env` and out of the configuration. With `"additionalProperties": false` an option that does not exist is refused instead of ignored. An option cannot be called like a setting every source has (`type`, `use`, `description`, `agents`, `trust`, `start`, `enabled`, `session`). |
714
1026
  | `talks` | Optional, `true`: what it reports is somebody writing to the agent, so report only `message` events. The event's `text` reaches the agent as a message, the answer goes back through the source, and the default throttle does not apply. |
715
1027
  | `sends` | Optional. One line for the agent on what sending through it does and what to pass. With it the agent's `send` tool offers the source. |
1028
+ | `files` | Optional, `true`: it can send a file along. `onSend` is then handed `file` (`{ name, mime, bytes }`) when the agent named one: a picture, video or sound file of its workspace, read by pine. |
1029
+ | `toOwner` | Optional, `true`: what it sends reaches the owner and nobody else, and the type's own code sees to that. Sending through it is then a message to the owner, which is not asked about after outside content. Never for a type that can reach anybody else or act on a device. |
716
1030
  | `plan(options, setup)` | Optional. Returns `{ options, does, opens, read?, tell?, owner? }` (`owner: true`: the source itself makes sure who is on the other end, so what it reports counts as your own words; you are told before you confirm): the options as they are to be stored, what the source will do in plain words (shown in your dialog), whether it reaches something new (then you are asked), a folder the agent should be able to read, and what the agent should pass on to you afterwards. Throw for what cannot work. Without `plan`, a set-up is always put to you. `setup` has the source's `name` and `key` (`name`, or `name@agent` for an agent's own), the `agent` and its `workspace`, pine's `home`, `resolve(path)`, `random(bytes)` and `envName(option)`. |
717
1031
 
718
1032
  A type without a `type` export still works in the configuration, but agents cannot set one up
@@ -735,7 +1049,7 @@ The start function gets a `source` object:
735
1049
  | `exec(command, opts?)` | Run a shell command in the sandbox of the agent the source belongs to (the main agent for a source of all agents). Returns `{ code, output, truncated }`; throws when it cannot start or takes longer than `opts.timeoutMs` (30 s). |
736
1050
  | `kv.get`, `kv.set` | Private storage that survives restarts. |
737
1051
  | `dataDir` | A folder of its own. |
738
- | `media(dir)` | Image files in this folder may be shown to a model when an event lists them in `images: [{ path, mimeType }]`. |
1052
+ | `media(dir)` | The source keeps the files it received in this folder. Image files in it may be shown to a model when an event lists them in `images: [{ path, mimeType }]`, and the agents that have the source or are subscribed to it can read the folder, and not write it. |
739
1053
  | `secret(value)` | Keep this value out of events and messages. |
740
1054
  | `http(handler)` | Receive `POST /hook/<name>`; throw `refuse(401, "...")` (exported from `sources.ts`) to turn a request away. |
741
1055
  | `onStop(fn)` | Called when the last subscriber leaves or the daemon stops. Close everything here. |
@@ -18,6 +18,7 @@
18
18
  | `swiftc` | App control on macOS | `mcp/computer.swift`, the helper that reads windows and sends clicks and keys, is compiled on the Mac it runs on the first time it is needed, and kept in pine's home. Needs Apple's command line developer tools (`xcode-select --install`). See [computer.md](computer.md). |
19
19
  | `sips`, `ffmpeg` | Pictures and video in the terminal UI | Convert what is shown: `sips` on macOS; `ffmpeg`, if installed, for video and on Linux. Both run confined, without network. |
20
20
  | `osascript`; `ffplay`, `mpv`, `pw-play`, `paplay`, `aplay` | Sound in the terminal UI | Plays a sound file an answer points at: on macOS the system's audio player (AVFoundation, through a script `osascript` runs), on Linux the first of the others that is installed. Runs confined, without network. A pause ends the player and play starts one from that place; `pw-play`, `paplay` and `aplay` cannot start in the middle and are held instead (SIGSTOP). |
21
+ | `ffmpeg`, `afconvert` | The bars of a sound in the terminal UI | The bars beside a playing sound are its levels, which pine works out from the file before it plays (`src/tui/levels.ts`; no library). A wav file is read as it is; any other kind is decoded first, by `ffmpeg` if installed, on macOS also by the system's `afconvert`. Both run confined, without network. Without either, only wav files have bars. |
21
22
  | `typebox` | Tool parameter schemas | The same library pi uses. |
22
23
  | `claude -p` | Development model | Optional; used by `pine dev-model`, by the terminal UI when the home's model is `dev/...` (the example home), and by the live tests. |
23
24