@pmndre/pine 0.22.1 → 0.33.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/changes.json +264 -0
- package/docs/SKILL.md +31 -7
- package/docs/references/agents.md +245 -21
- package/docs/references/coding.md +1 -1
- package/docs/references/computer.md +1 -1
- package/docs/references/configuration.md +14 -5
- package/docs/references/mcp.md +9 -0
- package/docs/references/operations.md +21 -10
- package/docs/references/overview.md +3 -1
- package/docs/references/security.md +83 -24
- package/docs/references/setup.md +55 -9
- package/docs/references/source-types.md +1418 -0
- package/docs/references/sources.md +333 -19
- package/docs/references/stack.md +1 -0
- package/docs/references/tui.md +86 -12
- package/examples/home/AGENTS.md +4 -0
- package/examples/home/TOOLS.md +5 -0
- package/examples/home/agents/main/workspace/AGENTS.md +1 -1
- package/examples/home/agents/main/workspace/TOOLS.md +5 -0
- package/mcp/browser.d.ts +6 -0
- package/mcp/browser.js +19 -0
- package/mcp/render.d.ts +1 -0
- package/mcp/render.js +237 -0
- package/package.json +6 -4
- package/src/actions.d.ts +6 -1
- package/src/actions.js +17 -4
- package/src/admin.d.ts +4 -0
- package/src/admin.js +25 -6
- package/src/agents.d.ts +167 -2
- package/src/agents.js +912 -45
- package/src/catalogue.d.ts +60 -0
- package/src/catalogue.js +791 -0
- package/src/cli.js +10 -7
- package/src/config.d.ts +53 -4
- package/src/config.js +30 -5
- package/src/goals.d.ts +1 -1
- package/src/goals.js +14 -1
- package/src/manual.js +24 -2
- package/src/mime.d.ts +78 -0
- package/src/mime.js +342 -0
- package/src/net.d.ts +11 -0
- package/src/net.js +29 -2
- package/src/pine.js +10 -1
- package/src/router.js +3 -3
- package/src/sandbox-linux.d.ts +3 -1
- package/src/sandbox-linux.js +5 -0
- package/src/security.d.ts +22 -6
- package/src/security.js +44 -13
- package/src/slots.d.ts +106 -0
- package/src/slots.js +250 -0
- package/src/source-types.d.ts +20 -0
- package/src/sources/calendar.d.ts +24 -0
- package/src/sources/calendar.js +265 -0
- package/src/sources/command.js +109 -4
- package/src/sources/discord.d.ts +4 -0
- package/src/sources/discord.js +298 -0
- package/src/sources/feed.d.ts +19 -0
- package/src/sources/feed.js +257 -0
- package/src/sources/http.js +154 -103
- package/src/sources/mail.d.ts +51 -0
- package/src/sources/mail.js +1013 -0
- package/src/sources/matrix.d.ts +4 -0
- package/src/sources/matrix.js +232 -0
- package/src/sources/modbus.d.ts +15 -0
- package/src/sources/modbus.js +240 -0
- package/src/sources/onvif.d.ts +35 -0
- package/src/sources/onvif.js +326 -0
- package/src/sources/presence.d.ts +80 -0
- package/src/sources/presence.js +480 -0
- package/src/sources/serial.d.ts +21 -0
- package/src/sources/serial.js +220 -0
- package/src/sources/slack.d.ts +16 -0
- package/src/sources/slack.js +1062 -0
- package/src/sources/smtp.d.ts +4 -0
- package/src/sources/smtp.js +360 -0
- package/src/sources/stream.d.ts +68 -0
- package/src/sources/stream.js +534 -0
- package/src/sources/syslog.d.ts +32 -0
- package/src/sources/syslog.js +243 -0
- package/src/sources/system.d.ts +14 -0
- package/src/sources/system.js +236 -0
- package/src/sources/system.swift +102 -0
- package/src/sources/telegram.js +34 -1
- package/src/sources.d.ts +41 -1
- package/src/sources.js +147 -24
- package/src/tools.d.ts +1 -1
- package/src/tools.js +304 -23
- package/src/tui/app.d.ts +35 -2
- package/src/tui/app.js +306 -43
- package/src/tui/levels.d.ts +68 -0
- package/src/tui/levels.js +273 -0
- package/src/tui/picture.d.ts +17 -1
- package/src/tui/picture.js +72 -5
- package/src/types.d.ts +3 -0
- package/src/update.d.ts +9 -1
- package/src/update.js +75 -3
- package/src/watching.d.ts +156 -0
- 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,
|
|
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
|
|
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 `
|
|
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 `
|
|
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`.
|
|
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 `
|
|
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.
|
|
365
|
-
|
|
366
|
-
|
|
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)` |
|
|
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. |
|
package/docs/references/stack.md
CHANGED
|
@@ -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
|
|