@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
|
@@ -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
|
|
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
|
|
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` (
|
|
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,
|
|
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`
|
|
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
|
-
|
|
367
|
-
|
|
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.
|
|
469
|
-
|
|
470
|
-
|
|
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.
|
|
514
|
-
|
|
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.
|
|
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
|
|
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
|
|
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.
|
|
832
|
-
|
|
833
|
-
|
|
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
|
package/docs/references/setup.md
CHANGED
|
@@ -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
|
|
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 `
|
|
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
|
-
|
|
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 |
|