@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
@@ -99,13 +99,20 @@ In the sandbox, the same on both systems:
99
99
 
100
100
  | | |
101
101
  |---|---|
102
- | Can read | Its workspace, its private home, its skills, pine's manual (`docs/`), temp, and the system outside your home folder (programs, libraries) |
103
- | Can write | Its workspace, its private home (`sandbox/<id>/`, which is `$HOME` in its shell), temp. The main agent also `USER.md` in pine's home, and nothing else there |
102
+ | Can read | Its workspace, its private home, its skills, pine's manual (`docs/`), temp, the files its event sources received (see below), and the system outside your home folder (programs, libraries) |
103
+ | Can write | Its workspace, its private home (`sandbox/<id>/`, which is `$HOME` in its shell), temp. The main agent also the three files for all agents in pine's home (`AGENTS.md`, `TOOLS.md`, `USER.md`), and nothing else there |
104
104
  | Cannot read or write | Your home folder, pine's home (configuration, `.env`, database, other agents' folders), other agents' workspaces |
105
105
  | Cannot | Use the network (unless `sandbox.network` or you granted it to the conversation; the `download` tool is the exception described under Modes), signal or inspect other processes, or reach the services of your session: launching apps, AppleScript, the keychain or keyring, the clipboard, the session bus, the container daemon, an ssh agent |
106
106
  | Can compute on | macOS: the graphics chip and the neural engine, which the system's own recognition of text and pictures runs on (a Swift script that reads the text of a scanned page with Vision works). They compute; they reach no file, address or other program |
107
107
  | Environment | A handful of variables (`PATH`, `LANG`, ...). Nothing from the daemon's environment, no secrets. `HOME` is the private home. On macOS `CFFIXED_USER_HOME` names it too, so that Apple's libraries take the same home, and `CLANG_MODULE_CACHE_PATH` puts the compilers' cache of built modules into it (the first `swift` run of an agent builds them and takes a while) |
108
108
 
109
+ One part of pine's home is an agent's to read besides its own folders: the files its event
110
+ sources received (a camera's upload, a photo sent through Telegram), which lie in
111
+ `data/sources/<name>/`. An agent reads those of its own sources and of the sources it is
112
+ subscribed to, in every mode, and writes none of them; the rest of pine's data folder and the
113
+ files of other sources stay closed. See "Files a source received" in
114
+ [sources.md](sources.md).
115
+
109
116
  How the two systems say it differs. On macOS the sandbox gets a profile that starts from
110
117
  "deny everything" and allows what the table lists. On Linux the command is given a file
111
118
  system of its own: everything read-only, your home folder and pine's home as empty folders
@@ -202,8 +209,9 @@ switched off. Looking at a folder runs nothing from it.
202
209
  Consequences worth knowing:
203
210
 
204
211
  - An agent cannot change its own `agent.json`, its extensions or `pine.json`.
205
- It can change the files it is meant to keep: `AGENTS.md`, `SOUL.md` and `MEMORY.md` in its
206
- workspace, and for the main agent `USER.md` ([agents.md](agents.md)), until the session is
212
+ It can change the files it is meant to keep: `AGENTS.md`, `SOUL.md`, `TOOLS.md` and `MEMORY.md` in its
213
+ workspace, and for the main agent the files for all agents in pine's home (`AGENTS.md`,
214
+ `TOOLS.md`, `USER.md`; [agents.md](agents.md)), until the session is
207
215
  restricted; see layer 4. Rules it must never change go into `agents/<id>/AGENTS.md`, which
208
216
  is outside its reach.
209
217
  - In the sandbox `git`, `node`, `python`, `sed` and the like work. Tools that need files in
@@ -288,7 +296,7 @@ one, in `auto` and `bypass` mode, pine does it by reading what is about to run:
288
296
  | What | How it is kept closed |
289
297
  |---|---|
290
298
  | A file tool (`read`, `write`, `edit`, ...) on a path in pine's home, or writing one in pine's program | Refused by a check in the daemon |
291
- | A shell command that names a path in pine's home: written out, with `~` or `$HOME`, or with `..` from where the shell starts | Not run |
299
+ | A shell command that names a path in pine's home: written out, with `~` or `$HOME`, or with `..` from where the shell starts | Not run. The files the agent's event sources received are the exception: a command that reads them runs, one that plainly writes or deletes them does not |
292
300
  | A shell command that plainly writes into pine's program files (a redirect, `touch`, `rm`, `cp` to it) | Not run |
293
301
  | A shell command that starts the `pine` program, or names pine's control port on this computer | Not run |
294
302
  | Any other shell command that names pine's program files and does more than look | Critical: you are asked, in every conversation (not in `bypass`) |
@@ -309,10 +317,20 @@ asking, with two exceptions, and both are a question to you:
309
317
  | The action | Examples | When you are asked |
310
318
  |---|---|---|
311
319
  | is critical | shell startup files, ssh keys, git hooks and a repository's configuration, launch agents; a force push, `git reset --hard`, `git clean -f`, `curl ... \| sh`, `sudo`, deleting a home folder | In every conversation, also one that has read nothing from outside |
312
- | sends something out | `send` (Telegram, MQTT), events, the acting tools of MCP servers marked `"approve": "tainted"`, a task for an agent that can send things out, `subscribe` | Once the conversation has read outside content |
320
+ | sends something out | `send` through a source that reaches somebody or something else (an MQTT device), events, the acting tools of MCP servers marked `"approve": "tainted"`, a task for an agent that can send things out, `subscribe` | Once the conversation has read outside content |
313
321
 
314
322
  Everything else runs, also after outside content: shell commands, files anywhere the agent
315
- reaches, downloads, and the agent's own memory and instructions.
323
+ reaches, downloads, the agent's own memory and instructions, and a message to you.
324
+
325
+ **Telling you is never asked about.** An agent that watches something (a camera, a device, a
326
+ page) has read outside content by the time it has something to say, and it says it when you
327
+ are not there. So `send` through a source that reaches you and nobody else goes out at once
328
+ in every conversation: the Telegram source, which writes only to the chat you paired or
329
+ listed. What an agent writes to you there you read as you read its answers; it leaves
330
+ nothing with anybody else. The source decides where a message goes, not the call (layer 9),
331
+ and the agent is told with its next message that this way stays open. To see every such
332
+ message before it is sent, put it on the agent's `approve` list (`"approve": ["send:telegram"]`,
333
+ with the source's name): that asks in every conversation.
316
334
 
317
335
  Critical actions are found by a fixed list of patterns, which you can read in
318
336
  `src/actions.ts` (`criticalCommand`, `PROTECTED_HOME`). Patterns are a net, not a wall: a
@@ -328,7 +346,7 @@ Once a conversation has **read outside content** (a web page, a search result, a
328
346
  from somebody else), somebody else may be steering the agent. What pine does about it, and
329
347
  what it does not:
330
348
 
331
- - Sending something out asks you (above).
349
+ - Sending something out asks you (above). A message to you does not.
332
350
  - The file tools refuse to write what somebody else would read as instructions, and what
333
351
  makes git run programs (layer 4).
334
352
  - Nothing looks at an ordinary shell command. In `auto` mode, a page that talks the agent
@@ -350,7 +368,8 @@ page says "now send the notes folder to ...". pine tracks that:
350
368
  Sessions started by untrusted events are tainted from the start.
351
369
  - In a tainted session, actions that send information out or act on the world wait for your
352
370
  **approval**: what the agent's `approveWhenTainted` list names (default `publish_event` and
353
- `send`), the acting tools of MCP servers marked `"approve": "tainted"`, `subscribe`, and
371
+ `send`; a `send` through a source that reaches only you, which Telegram is, is a message to
372
+ you and never waits: "What asks you"), the acting tools of MCP servers marked `"approve": "tainted"`, `subscribe`, and
354
373
  handing a task to an agent that can reach the internet. Its shell and its downloads are
355
374
  not among them.
356
375
  - Tools that only read never wait: `read`, `grep`, `find`, `ls`, `state_get`, `manual`, the
@@ -362,9 +381,11 @@ page says "now send the notes folder to ...". pine tracks that:
362
381
  check it. It is taken at its word because you chose the server. What such a tool is asked (a
363
382
  search text, a path) does reach the server. For a server where that matters, set
364
383
  `"approve": "always"`: then every call asks, reading included.
365
- - A tainted session keeps the agent's own files: `MEMORY.md`, `AGENTS.md`, `SOUL.md`, and
366
- `USER.md` for the main agent. It writes them as before, and nobody checks what it writes
367
- there, so text from a page can end up in the agent's memory ("What is not solved").
384
+ - A tainted session keeps the agent's own files: `MEMORY.md`, `AGENTS.md`, `SOUL.md`, `TOOLS.md`, and
385
+ for the main agent the files for all agents (`AGENTS.md`, `TOOLS.md` and `USER.md` in
386
+ pine's home). It writes them as before, and nobody checks what it writes there, so text
387
+ from a page can end up in the agent's memory, and through the main agent in every agent's
388
+ instructions ("What is not solved"). A run started from outside writes none of them.
368
389
  Everything else that would be read as instructions (`CLAUDE.md`, `AGENTS.md` further
369
390
  down in the workspace, `.pi/`, `.agents/`, the instruction files of a folder opened for the
370
391
  conversation) is refused, with no question: by the file tools in every mode, and for shell
@@ -465,9 +486,13 @@ never in a run started from outside. See [computer.md](computer.md).
465
486
 
466
487
  **Sub-agents share their conversation's permissions.** A sub-agent is a copy of the agent doing
467
488
  part of the conversation's job, so it works under what you allowed there: the access you
468
- granted, your "always" answers, and your answer on whether the conversation keeps your account. It works the other way too: what a sub-agent asks for and
469
- gets holds for the conversation and its other sub-agents, so you are asked once, not once per
470
- copy. Nothing is widened by this: a sub-agent inherits the conversation's outside-content mark
489
+ granted, your "always" answers, and your answer on whether the conversation keeps your account.
490
+ A sub-agent never asks you anything itself: it works unattended, often several at once, and a
491
+ question would leave it waiting. Where you would be asked, it is refused and told to say in its
492
+ answer what it needed, and the conversation that started it asks you, once. The model a
493
+ sub-agent runs on can be another one than the agent's (`model` of `subagent`); nothing of the
494
+ above depends on the model, and a run started by an outside event chooses none. Nothing is
495
+ widened by this: a sub-agent inherits the conversation's outside-content mark
471
496
  as well, and another conversation of the same agent, or a run started by an outside event, has
472
497
  none of it. An agent that a task is *delegated* to is a different agent with its own sandbox and
473
498
  its own permissions.
@@ -510,8 +535,9 @@ the workspace, byte for byte, and reports size and SHA-256.
510
535
  out the moment it is displayed.
511
536
  - Picture files are decoded by macOS's `sips` (on Linux by `ffmpeg`) and videos by `ffmpeg`, both started without
512
537
  network access and without write access outside the temp folder, because the bytes can come
513
- from anywhere. "Open in player" hands the file to the system's player, which has no such
514
- limits; it only happens on your click.
538
+ from anywhere. A sound file is decoded the same way for the bars its line shows (by `ffmpeg`,
539
+ or macOS's `afconvert`), and played by a player that is confined like them. "Open in player"
540
+ hands the file to the system's player, which has no such limits; it only happens on your click.
515
541
  - Pictures a tool returned are kept in `data/media/tool` (mode 600) for as long as the event
516
542
  log reaches back (`limits.eventRetentionDays`).
517
543
 
@@ -546,6 +572,31 @@ safe:
546
572
  - The `ftp` type only receives, needs a password, writes under names of its own choosing into
547
573
  its own folder, and can be limited to client addresses. The `webhook` type needs a secret
548
574
  unless it is set up with `"open": true`, which the dialog spells out.
575
+ - The other types that listen on a port do the same: `smtp` (mail from devices) only
576
+ receives, relays nothing, and needs a password or a list of client addresses; `syslog` has
577
+ no login in its protocol, so without a list of sender addresses (`allow`) the dialog says
578
+ that anyone on the network can write lines, and `pine check` says so afterwards.
579
+ - A type that connects out (`feed`, `calendar`, `stream`, `mail`, `slack`, `matrix`,
580
+ `discord`, `http`) reaches the address you confirmed and no other: a public name that one
581
+ day leads into your network is refused, a redirect to another host is not followed, and a
582
+ token goes only to the host it was given for. An address a camera hands back (`onvif`) is
583
+ used for its path only.
584
+ - What people write is never taken for your words. A mail's sender line can be forged and a
585
+ channel is read by others, so `mail`, `smtp`, `slack`, `matrix` and `discord` report
586
+ outside content, whoever the message says it is from. Do not give such a source
587
+ `"trust": "owner"`; `pine check` names every source that has it.
588
+ - A source that can also send (`mail`, `slack`, `matrix`, `discord`, `mqtt`) sends only to
589
+ the addresses, channels, rooms or topics on its own list, checked by the type itself. Such a
590
+ send is asked about after outside content like any other way of sending something out.
591
+ - A look of an `http` source with `render` is made by pine's browser, started for that one
592
+ look and closed after it. It runs behind the same guard as the browser tools (your network
593
+ and this computer are closed to the page and to everything it loads, except the one local
594
+ address you confirmed), has no tools, keeps no cookies, and is handed no token. The page's
595
+ own scripts run in it, which the dialog says.
596
+ - A command that is followed (`command` with `follow`) runs in the agent's sandbox like one
597
+ that is run again and again, and ends with its source. On Linux it is refused.
598
+ - The `system` type starts one helper program, built by pine from its own source into pine's
599
+ data folder; no option of a source names a program for the daemon to run.
549
600
  - A subscription has a throttle (10 s unless you change it), so a device that reports every
550
601
  second cannot keep a model busy.
551
602
 
@@ -568,7 +619,12 @@ What no mode opens:
568
619
  change before it is made, notes where it gives an agent more (the account, the network,
569
620
  bypass mode), reads the configuration back through the loader and undoes what
570
621
  does not load, and is refused outright, without a question to you, in a conversation that
571
- has read outside content. What it does for another agent (`agent` on the tools for sources,
622
+ has read outside content. It also lists, reads, pins, renames and removes conversations, its
623
+ own and other agents' (`conversations`, `read_conversation`, `set_conversation`,
624
+ `remove_conversation`): what another agent's tools returned is never shown to it, a
625
+ conversation that holds outside content marks the one that reads it, the two that change
626
+ something are refused after outside content, and a removal is always yours to confirm.
627
+ What it does for another agent (`agent` on the tools for sources,
572
628
  servers, skills and schedules) is carried out by that agent's own tool under that agent's
573
629
  rules, and taking something away from another agent asks you every time. Only the main agent can set anything up for all agents. Runs with the reduced
574
630
  tool set (layer 2) have none of these tools, and a proposal from a conversation that has read
@@ -764,7 +820,8 @@ calls for it, so it is guarded like the instruction files:
764
820
 
765
821
  Whatever asks, the Telegram source sends only to your own chat, and the MQTT source publishes
766
822
  only to topics on its `publish` list. In a conversation that has read outside content, the
767
- `send` tool asks you first. An agent's `publish` list names the topics it
823
+ `send` tool asks you first for a source that acts on something (MQTT), and not for one that
824
+ only writes to you (Telegram). An agent's `publish` list names the topics it
768
825
  may use at all. Agents cannot publish on pine's own topics (`agent/`, `approval/`, `pine/`,
769
826
  `state/`, `timer/`).
770
827
 
@@ -826,11 +883,13 @@ itself can be fooled by a page, but it has nothing to give away and cannot act.
826
883
  run programs (a `CLAUDE.md` in a repository, a hook): the file tools refuse that, and
827
884
  nothing looks at a shell command that does it, unless it names a hook or a repository's
828
885
  configuration, which asks you. For an agent that reads the web, `safe` mode is the wall.
829
- - **Memory after outside content.** An agent writes its own `MEMORY.md`, `AGENTS.md` and
830
- `SOUL.md` also in a conversation that has read outside content, unchecked. What a page
831
- talks it into writing there is read in every later conversation. Look into those files
832
- now and then; rules it must never change go into `agents/<id>/AGENTS.md`, which it cannot
833
- write.
886
+ - **Memory after outside content.** An agent writes its own `MEMORY.md`, `AGENTS.md`,
887
+ `SOUL.md` and `TOOLS.md` also in a conversation that has read outside content, unchecked. What a page
888
+ talks it into writing there is read in every later conversation. The main agent writes
889
+ the files for all agents the same way (`AGENTS.md`, `TOOLS.md` and `USER.md` in pine's
890
+ home), and what it is talked into writing there is read by every agent. Look into those
891
+ files now and then; rules it must never change go into `agents/<id>/AGENTS.md`, which it
892
+ cannot write.
834
893
  - **A model server reads what it is sent.** Whoever runs a server you add (`pine model add`,
835
894
  `add_model_server`) sees every conversation of the agents that use its models: your messages,
836
895
  the files they read, the results of their tools. Over plain `http` so does anyone on the
@@ -42,7 +42,8 @@ called `main`, or else the first one. It is pine's administrator: what you want
42
42
  pine, you ask it for, and it does it with tools that check what they are given, instead of
43
43
  you or an agent editing files. See "The main agent administers pine" below. The other agents do not have `create_agent`,
44
44
  `update_agent`, `remove_agent`, `agents`, `settings`, `set_setting`, `routes`, `add_route`,
45
- `remove_route`, `add_source_type`, `remove_source_type`, `add_model_server` or `remove_model_server`,
45
+ `remove_route`, `add_source_type`, `remove_source_type`, `add_model_server`, `remove_model_server`,
46
+ `conversations`, `read_conversation`, `set_conversation` or `remove_conversation`,
46
47
  and they are refused when they ask for the global scope. Their instructions tell them who can do it, so
47
48
  an agent you ask for something that is not its to do sends you to the main agent instead of
48
49
  trying.
@@ -92,7 +93,7 @@ otherwise skipped are asked too (ending a subscription: in manual mode only).
92
93
 
93
94
  In plan mode nothing is set up: every tool that adds, removes, subscribes or sends is refused
94
95
  there without a question, and the agent says what it would set up. The tools that only list
95
- (`sources`, `schedules`, `mcp_servers`, `skills`) work in every mode and are never asked about.
96
+ (`sources`, `schedules`, `mcp_servers`, `skills`, `models`) work in every mode and are never asked about.
96
97
 
97
98
  In a conversation that has read outside content two things are stricter, because what they
98
99
  write is read back as instructions or runs as a program. `add_skill` is put to you first,
@@ -115,6 +116,7 @@ by a guess and never by looking for a file.
115
116
  |---|---|
116
117
  | MCP servers: which are connected, which the agent has | `mcp_servers` |
117
118
  | Skills: what the agent knows how to do | `skills` |
119
+ | Models: which are set up, and which one the agent runs on | `models` |
118
120
  | Events: sources, and who is subscribed and woken | `sources` |
119
121
  | Schedules: what happens at set times | `schedules` |
120
122
 
@@ -127,8 +129,8 @@ Which model the agent runs on is told to it with your message, so it needs no to
127
129
  | **Events** | |
128
130
  | `sources` | Lists the event sources this conversation can use and who is subscribed. |
129
131
  | `add_source` `name` `type` `description` [`options`] [`scope`] [`note`] [`throttle`] [`own`] [`ask`] | Sets up a source; with a note it subscribes at once. `options` is an object with the options of the chosen type ([sources.md](sources.md)). `own: true` marks it as your own device or folder, whose events are trusted. `ask` names secret options that you are to type into the dialog. |
130
- | `subscribe` `source` [`scope`] [`note`] [`when`] [`throttle`], `unsubscribe` `source` [`scope`] | Starts or ends being woken by a source. For `unsubscribe` the scope can also be `all`: everything the agent has on that source. |
131
- | `send` `source` [`text`] [`data`] | Sends something out through a source that can send (Telegram, MQTT). |
132
+ | `subscribe` `source` [`scope`] [`note`] [`when`] [`throttle`] [`fresh`], `unsubscribe` `source` [`scope`] | Starts or ends being woken by a source. `fresh`: every event is handled in a conversation of its own, started empty, for a source that reports all day ([sources.md](sources.md), "A fresh conversation for every event"). For `unsubscribe` the scope can also be `all`: everything the agent has on that source. |
133
+ | `send` `source` [`text`] [`file`] [`data`] | Sends something out through a source that can send (Telegram, MQTT). `file`: a picture, video or sound file of the agent's workspace to go with a Telegram message. A message to you through Telegram is never held back for approval. |
132
134
  | `remove_source` `name` | Stops a source, unsubscribes everyone from it and deletes it. For a watched folder, the read access that came with it goes too. |
133
135
  | `add_source_type` `name` `file`, `remove_source_type` `name` | Main agent only. Registers a module the agent wrote as a new type of source, or takes one out. |
134
136
  | **Schedules** | |
@@ -141,7 +143,7 @@ Which model the agent runs on is told to it with your message, so it needs no to
141
143
  | `remove_mcp_server` `name` | Takes a server out again. A server that belongs to another conversation is removed there, or with that conversation. |
142
144
  | **Asking, and keeping track** | |
143
145
  | `question` `question` [`choices`] | Asks your owner one question when you cannot go on without their decision, with two to six short answers to pick from (the one you recommend first). They pick one in a dialog, or on Telegram with a button, or answer in their own words; you get the answer back as the tool's result. No answer is said plainly: go on with a reasonable assumption and say which. It changes nothing, so it also works in plan mode. Not for permission to act (that is asked by itself), and not there in a run your owner did not start |
144
- | `todo` `items` | Your own list of the steps of a task that has several. Send the whole list every time, each step with a status: `pending`, `in_progress` (one at a time) or `done`. Your owner sees it in the conversation and in the status line ("step 2 of 5"), and with their next message you are shown what is still open, so you can pick the work up where it stood. It belongs to the conversation and goes when that is reset. An empty list clears it. At most 30 steps. Not there in a run your owner did not start |
146
+ | `todo` `items` | Your own list of the steps of a task that has several. Send the whole list every time, each step with a status: `pending`, `in_progress` (one at a time) or `done`. Your owner sees it in the conversation and in the status line ("step 2 of 5"), and with their next message you are shown what is still open, so you can pick the work up where it stood. Send it again each time a step is done and once more before your final answer; when it has not changed for six tool calls while steps are open, a line in a tool's answer reminds you. It belongs to the conversation and goes when that is reset. An empty list clears it. At most 30 steps. Not there in a run your owner did not start |
145
147
  | **Programs** | |
146
148
  | `stop_program` [`id`] | Stops a program that one of the conversation's commands left running, such as a development server, or one the agent started in the background (`background: true`). Without `id` it lists them. Never asks: it only ends what the agent started. Only an agent with `bash` has it. See [coding.md](coding.md). |
147
149
  | **Skills** | |
@@ -156,7 +158,8 @@ Which model the agent runs on is told to it with your message, so it needs no to
156
158
  | **Not setup: the other tools pine gives an agent** | |
157
159
  | `request_access` [`path`] [`write`] [`network`] `reason` | Asks you for access the conversation does not have: a file or folder outside the workspace (`path`; with `write: true` also to change it), or the network from the shell (`network: true`). You decide; a yes holds for the conversation until it is reset or pine restarts. pine's home is never granted. An agent does not have to call it: when a file tool or a shell command needs something outside, pine asks you the same question itself. See "When a call needs something outside" and "Modes" in [security.md](security.md). |
158
160
  | `delegate` `agent` `task` [`wait`] [`thread`] | Hands a task to another agent and gets its answer. Only there when the agent's `delegates` list is not empty. See [agents.md](agents.md). |
159
- | `subagent` `tasks` | Runs several copies of the agent side by side, one task each, and returns their answers. See [agents.md](agents.md). |
161
+ | `subagent` `tasks` [`model`] [`thinking`] | Runs several copies of the agent side by side, one task each, and returns their answers. With `model` the copies run on another model than the agent's, with `thinking` at another reasoning level. They never ask you anything. See [agents.md](agents.md), "Sub-agents". |
162
+ | `models` | Lists the models that are set up, as `provider/model`, with what each can do (see pictures, reason) and which one is the agent's own. This is how an agent answers "which models are there", and where it finds what `subagent` takes as `model`. |
160
163
  | `download` `url` `path` | Fetches a file from a web address into the workspace, byte for byte. It is how an agent gets a file that a remote MCP server made: by the link in the tool's answer, never by a file path from it. See "Downloads" in [security.md](security.md) and "Files and pictures from a remote server" in [mcp.md](mcp.md). |
161
164
  | `publish_event` `topic` [`text`] [`data`] | Publishes an event on a topic of the agent's `publish` list. Without that list the tool is not there. See [events.md](events.md). |
162
165
  | `state_get` `key`, `state_set` `key` `value` | Read and write shared state, within `state.read` and `state.write`. See "Shared state" in [agents.md](agents.md). |
@@ -208,6 +211,7 @@ agents/books/
208
211
  workspace/
209
212
  AGENTS.md the instructions; the new agent can change them itself from then on
210
213
  SOUL.md a stub
214
+ TOOLS.md a stub
211
215
  MEMORY.md a stub
212
216
  ```
213
217
 
@@ -231,6 +235,7 @@ agent, not a pine that does not start.
231
235
  | Types of event source, model servers | `add_source_type`, `remove_source_type`, `add_model_server`, `remove_model_server` |
232
236
  | pine's settings | `settings` (list), `set_setting` |
233
237
  | Routes: rules of your own in pine.json | `routes` (list), `add_route`, `remove_route` |
238
+ | Conversations: your tabs, and each agent's list of them | `conversations` (list), `read_conversation`, `set_conversation`, `remove_conversation` |
234
239
 
235
240
  The ones only it has:
236
241
 
@@ -254,19 +259,21 @@ agent (`remove_source`, `remove_mcp_server`, `remove_skill`, `remove_schedule`,
254
259
  asks you every time, and the question says that the main agent asks.
255
260
 
256
261
  **Not from a conversation that has read outside content.** `update_agent`, `remove_agent`,
257
- `set_setting`, `add_route` and `remove_route` are refused there without a question to you: a web page that says "remove the
262
+ `set_setting`, `add_route`, `remove_route`, `set_conversation` and `remove_conversation` are refused there without a question to you: a web page that says "remove the
258
263
  agent" must not get as far as your approval dialog. A new
259
264
  conversation, or `/reset`, does it.
260
265
 
261
266
  ## Changing and removing an agent
262
267
 
263
- `update_agent` changes what is given and leaves the rest:
268
+ Tell the main agent what to change about another agent ("give the books agent another model",
269
+ "let it read my Documents folder"): `update_agent` changes what is given and leaves the rest:
264
270
 
265
271
  | Value | What it is |
266
272
  |---|---|
267
273
  | `description` | One line on what the agent is for |
268
274
  | `instructions` | The whole new text of its `AGENTS.md`. It replaces the file, so the main agent reads the present text first (`agents` with `id`) |
269
275
  | `soul` | The whole new text of its `SOUL.md`: who it is, its character and tone. It replaces the file the same way. This is what the main agent uses when you speak of an agent's personality or how it should sound |
276
+ | `tooling` | The whole new text of its own `TOOLS.md`: tooling defaults and preferences for it alone. It replaces the file the same way; empty takes them back |
270
277
  | `model`, `thinking` | Its model (`"default"` for pine's default) and how much it reasons |
271
278
  | `mode` | `auto` (no sandbox: its shell and file tools reach your whole account and the network), `safe` (in the sandbox: its own folders), `manual` (in the sandbox, every action waits), `bypass`, `plan`, or `default` for what pine gives an agent that names none. This is also how far its shell and file tools reach |
272
279
  | `tools` | Its built-in tools, all of them: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` |
@@ -321,15 +328,54 @@ to go (`reply`), `whenBusy`, `priority` and `key` are not offered by the tool: w
321
328
  `pine.json`. Like the other administration tools, the two that change something are refused in
322
329
  a conversation that has read outside content.
323
330
 
331
+ ## Conversations and tabs
332
+
333
+ "Which conversations are there?", "what did the books agent say about the invoice?", "pin
334
+ that one", "open it in a tab", "close the tab", "remove the old ones": the main agent does
335
+ these with four tools. They work on your own conversations with it and on those of every other
336
+ agent, and they do what the list of conversations in the terminal UI does for your own hand
337
+ ([tui.md](tui.md)): the same pin, the same rename, the same removal.
338
+
339
+ | Tool | Does |
340
+ |---|---|
341
+ | `conversations` [`agent`] | Lists the conversations of every agent, or of one: for each whether it is pinned, open in a tab, working, how many messages it has, when it was last used, when it is removed by itself, and whether it has read outside content. Asks nobody. |
342
+ | `read_conversation` `name` [`agent`] [`last`] [`before`] | What was said in a conversation: the messages it was given and the answers, numbered, the newest last. `last` is how many (10, at most 30), `before` a number to read further back from. Of the tools an answer used it shows which and on what, never what they returned. Asks nobody. |
343
+ | `set_conversation` `name` [`agent`] [`pinned`] [`tab`] [`rename`] | Changes only what is given. `pinned`: keep it however long it is unused, or take the pin off. `tab`: open a tab on it, or close its tab. `rename`: its new name; history, pin, tab and subscriptions go with it. A name that is new with `tab: true` opens a new, empty conversation. |
344
+ | `remove_conversation` `name` [`agent`] | Removes a conversation for good: what was said in it, its tab, its pin, and what was set up for it alone (subscriptions, event sources, MCP servers, schedules, skills). You see what goes and confirm it, every time. |
345
+
346
+ What holds for them:
347
+
348
+ - **A tab the agent opens never takes your place.** It appears behind the tab you are in,
349
+ marked as new. A terminal UI that is running follows at once; one that is started later
350
+ opens with it.
351
+ - **Closing a tab does what closing it yourself does.** What that conversation was subscribed
352
+ to on its own ends, and the conversation stays in the list. Where a subscription would end,
353
+ you are asked first.
354
+ - **Reading is not a way around another agent's sandbox.** What another agent's tools returned
355
+ (its files, the pages it read) is not shown, only that a tool was used and on what.
356
+ - **Outside content stays outside content.** If the conversation that is read has read
357
+ outside content, or is the one outside content started (its name ends in `~u`), the
358
+ conversation that reads it counts as having read outside content from then on
359
+ ([security.md](security.md)). The list says which ones these are.
360
+ - **Not for the conversation the agent is in, and not for `main`.** The main agent cannot
361
+ close, rename or remove the conversation it is working in, and no agent's `main` conversation
362
+ is removed or renamed: `/close`, `/rename` and `/reset` are yours.
363
+ - **A conversation's folder and its goal stay yours.** No tool sets them.
364
+ - **Putting work into a conversation is not done here.** `set_conversation` opens an empty
365
+ tab; what is to be done in it you say there.
366
+
324
367
  ## pine's settings
325
368
 
326
369
  `settings` lists what `set_setting` can change, with what is in force:
327
370
 
328
371
  | Setting | What it is |
329
372
  |---|---|
330
- | `defaults.model`, `defaults.thinking`, `defaults.mode` | What an agent gets that does not say otherwise: model, reasoning, mode (and with the mode, how far it reaches) |
373
+ | `defaults.model`, `defaults.thinking`, `defaults.mode` | What an agent gets that does not say otherwise: model, reasoning, mode (and with the mode, how far it reaches). A rule or a preference for all agents (how to behave, a default for a tool) is not a setting: the main agent writes it into `AGENTS.md` or `TOOLS.md` in pine's home ([agents.md](agents.md), "What holds for all agents") |
331
374
  | `defaults.bashTimeoutSec`, `defaults.taskTimeoutSec` | Seconds a shell call and a task may run. From the next start |
332
375
  | `limits.maxConcurrentRuns` | How many agents work at the same time. From the next start |
376
+ | `defaults.catalogue` | How tools are declared to the model: `families` (grouped, short) or `full` (every tool by itself). From the next start. See [agents.md](agents.md), "How tools are declared" |
377
+ | `limits.warmSlots` | Whether the idle slots of a llama.cpp model server are filled in the background, so that a new conversation starts at once |
378
+ | `limits.slotPages` | How many conversations beyond the model server's slots are kept in files there and read back, instead of being read again by the model |
333
379
  | `limits.maxDelegationDepth`, `limits.maxDownloadMb` | How often a task is handed on, and the largest download |
334
380
  | `defaults.judge` | The model of the judge of goal mode. Not set: the agent's own |
335
381
  | `security.askAccess` | Whether pine asks you itself when a call needs something outside the sandbox |