@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
|
@@ -10,6 +10,7 @@ agents/gonzo/
|
|
|
10
10
|
workspace/ where it works, and the files it keeps itself:
|
|
11
11
|
AGENTS.md its purpose and how it works
|
|
12
12
|
SOUL.md who it is: character and tone
|
|
13
|
+
TOOLS.md how it uses its tools, on top of the TOOLS.md for all agents
|
|
13
14
|
MEMORY.md what should outlive a conversation
|
|
14
15
|
skills/ its own skills, one folder each; the agent adds them with add_skill
|
|
15
16
|
conversations/ what was set up for one conversation alone (its skills); made when needed
|
|
@@ -21,7 +22,7 @@ agents/gonzo/
|
|
|
21
22
|
|
|
22
23
|
Ask the main agent ("create an agent that keeps my books"): it calls `create_agent`, you confirm
|
|
23
24
|
what it proposes, and the folder above is made with `agent.json` and a workspace that holds its
|
|
24
|
-
instructions (`AGENTS.md`) and stubs of `SOUL.md` and `MEMORY.md`. The agent exists at once,
|
|
25
|
+
instructions (`AGENTS.md`) and stubs of `SOUL.md`, `TOOLS.md` and `MEMORY.md`. The agent exists at once,
|
|
25
26
|
without a restart. Only the main agent has this tool; the
|
|
26
27
|
others tell you to ask it. See [setup.md](setup.md).
|
|
27
28
|
|
|
@@ -36,31 +37,82 @@ described in [setup.md](setup.md) under "Changing and removing an agent". Nobody
|
|
|
36
37
|
## The files an agent keeps itself
|
|
37
38
|
|
|
38
39
|
An agent's instructions are files in its workspace, and the agent can write them. Together
|
|
39
|
-
with
|
|
40
|
+
with the files for all agents they are read into its prompt with every conversation:
|
|
40
41
|
|
|
41
42
|
| File | Holds | Who writes it |
|
|
42
43
|
|---|---|---|
|
|
43
44
|
| `workspace/AGENTS.md` | Its purpose and how it works. You shape it by telling the agent ("your purpose is ...", "from now on answer in tables") | The agent, and you |
|
|
44
45
|
| `workspace/SOUL.md` | Who it is: character and tone | The agent, and you. For another agent, the main agent: tell it how that agent should be or sound, and it replaces the file with `update_agent` (`soul`) |
|
|
46
|
+
| `workspace/TOOLS.md` | How it uses its tools: its own defaults and preferences for them, and technical or functional details of its work. It adds to the `TOOLS.md` for all agents, and where the two differ, the agent's own counts for it. It can be empty | The agent, and you. For another agent, the main agent, with `update_agent` (`tooling`) |
|
|
45
47
|
| `workspace/MEMORY.md` | What matters beyond a conversation: decisions, facts, preferences, open ends | The agent |
|
|
48
|
+
| `AGENTS.md` in pine's home | Traits and behaviour for all agents: how every agent is to be and to act. See "What holds for all agents" | The main agent, and you |
|
|
49
|
+
| `TOOLS.md` in pine's home | Tooling for all agents: defaults and preferences for the tools, and other technical or functional details of your setup. Every agent reads it, before its own `TOOLS.md` | The main agent, and you |
|
|
46
50
|
| `USER.md` in pine's home | What every agent knows about you. One file for all agents | The main agent, and you |
|
|
47
51
|
| `agents/<id>/AGENTS.md` | Optional. Rules of yours that the agent reads and cannot change | You |
|
|
48
52
|
|
|
49
53
|
Every agent is told what these files are for: to write into `AGENTS.md` what you say it is for
|
|
50
|
-
or how you want things done, to
|
|
54
|
+
or how you want things done, to keep in `TOOLS.md` its own defaults and preferences for its
|
|
55
|
+
tools (a tool is anything it works with: a skill, an MCP server, a shell command, a schedule,
|
|
56
|
+
an event source), to put into `MEMORY.md` what it learns that matters later, at
|
|
51
57
|
once and briefly, and to tidy its memory when it has grown long (merge, drop what no longer
|
|
52
58
|
holds, move details into other files and leave a pointer). When `MEMORY.md` passes about 6 000
|
|
53
59
|
characters, pine reminds the agent, because all of it is read with every message.
|
|
54
60
|
|
|
55
61
|
`pine init` starts them as short stubs; `create_agent` writes the instructions it was given
|
|
56
|
-
into `AGENTS.md` and starts the other
|
|
62
|
+
into `AGENTS.md` and starts the other three as stubs. A file that is missing is simply not
|
|
57
63
|
loaded, and the agent creates it when it has something to put there. A change applies from the
|
|
58
64
|
agent's next message on. Only these names (and a `CLAUDE.md`), at the top of the workspace, are
|
|
59
65
|
read; anything else the agent keeps there is its own notes, which it reads when it needs them.
|
|
66
|
+
Every file that is read as instructions, and from where, is listed under "Every file that is
|
|
67
|
+
read as instructions" below.
|
|
60
68
|
|
|
61
|
-
Other agents get
|
|
62
|
-
when something belongs there. A conversation that has read outside content
|
|
63
|
-
as before, without a question ([security.md](security.md)).
|
|
69
|
+
Other agents get the three files of pine's home in their prompt but cannot open or change
|
|
70
|
+
them; they tell you when something belongs there. A conversation that has read outside content
|
|
71
|
+
writes these files as before, without a question ([security.md](security.md)).
|
|
72
|
+
|
|
73
|
+
### What holds for all agents
|
|
74
|
+
|
|
75
|
+
A rule, a preference or a default that is to hold for every agent is not a setting: tell the
|
|
76
|
+
main agent, and it writes it into one of three files in pine's home. These are pine's global
|
|
77
|
+
instruction files: a global `AGENTS.md`, a global `TOOLS.md` and `USER.md`. They are put into
|
|
78
|
+
every agent's prompt, and only the main agent (and you) can change them.
|
|
79
|
+
|
|
80
|
+
| File | What goes into it | For example |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| `AGENTS.md` (in pine's home) | Traits and behaviour: how every agent is to be and to act | "Answer in English." "Ask before you delete anything." |
|
|
83
|
+
| `TOOLS.md` (in pine's home) | Tooling: defaults and preferences for the tools, and other technical or functional details of your setup. A tool is anything an agent works with: a skill, an MCP server, a shell command, a schedule, an event source | "Search with ripgrep." "Reports go to the NAS." "Speak fast, with a female voice." |
|
|
84
|
+
| `USER.md` (in pine's home) | What every agent knows about you | Your name, what you do, how you like to be answered |
|
|
85
|
+
|
|
86
|
+
### Where a default or a preference goes
|
|
87
|
+
|
|
88
|
+
You do not have to say where to write a default or a preference: say it, and say whom it is
|
|
89
|
+
for when it is not for everybody. The main agent keeps both kinds of file and is told to tell
|
|
90
|
+
them apart:
|
|
91
|
+
|
|
92
|
+
| You say to the main agent | It writes it into |
|
|
93
|
+
|---|---|
|
|
94
|
+
| A default or a preference for a tool, and nothing about whom it is for ("search with ripgrep by default", "speak with the fast voice") | `TOOLS.md` in pine's home: it is for all agents |
|
|
95
|
+
| The same, "for you alone" | Its own `workspace/TOOLS.md` |
|
|
96
|
+
| The same, "for the books agent" | That agent's `workspace/TOOLS.md`, with `update_agent` (`tooling`); you confirm it |
|
|
97
|
+
| How to be or to behave, "for all agents" ("every agent answers in English") | `AGENTS.md` in pine's home |
|
|
98
|
+
| How to be or to behave, and nothing about whom it is for | Its own `workspace/AGENTS.md` |
|
|
99
|
+
|
|
100
|
+
Any other agent writes what you tell it into its own files, and tells you to ask the main
|
|
101
|
+
agent when you mean all agents.
|
|
102
|
+
|
|
103
|
+
`AGENTS.md` and `TOOLS.md` exist twice for every agent: the one in pine's home, for all
|
|
104
|
+
agents, and the one in its own workspace. Both are read, the one for all agents first, and the
|
|
105
|
+
agent's own says what is different or more for it ("this agent answers in German", "this
|
|
106
|
+
agent searches with grep"); where the two differ, its own counts for that agent. What only one
|
|
107
|
+
agent should know or do goes into that agent's files, not into the ones for all.
|
|
108
|
+
|
|
109
|
+
`pine init` starts the three as short stubs, and a home from before gets the ones it lacks
|
|
110
|
+
when pine starts. A stub nobody has written into is left out of the prompt where tools are
|
|
111
|
+
declared as families. A line added to one reaches a conversation that has already begun in
|
|
112
|
+
the note in front of its next message, named as "for all agents"; a line that was changed or
|
|
113
|
+
removed has every conversation take its instructions anew. What agents run on and how far
|
|
114
|
+
they reach is not text but a setting, which the main agent changes with `set_setting`
|
|
115
|
+
([setup.md](setup.md)).
|
|
64
116
|
|
|
65
117
|
An existing home from before this layout keeps working: `agents/<id>/AGENTS.md` is still read.
|
|
66
118
|
To hand the instructions over to the agent, move that file to `agents/<id>/workspace/AGENTS.md`;
|
|
@@ -71,17 +123,42 @@ To hand the instructions over to the agent, move that file to `agents/<id>/works
|
|
|
71
123
|
Its system prompt is put together from, in this order:
|
|
72
124
|
|
|
73
125
|
1. pine's base prompt: that it is an agent in pine working for its owner, how to use its file
|
|
74
|
-
tools, how far its shell and file tools reach (its workspace in `safe` and `manual` mode, the owner's account in `auto` and `bypass`: `mode`), that pine's setup is changed through tools and
|
|
126
|
+
tools, that the web is looked up with its web tools and not with `curl` in the shell, how far its shell and file tools reach (its workspace in `safe` and `manual` mode, the owner's account in `auto` and `bypass`: `mode`), that pine's setup is changed through tools and
|
|
75
127
|
never by writing its files (which of them it has, and that creating agents and anything for
|
|
76
128
|
all agents is the main agent's job), that what it has been given it asks a tool and never
|
|
77
129
|
looks for in files (`sources`, `mcp_servers`, `skills`, `schedules`), that for everything
|
|
78
130
|
else it should explain the steps to its owner, and that text from tools, files and the web
|
|
79
131
|
is information, never a command. An `agents/<id>/SYSTEM.md` replaces this text.
|
|
80
|
-
2. `
|
|
132
|
+
2. `AGENTS.md` from pine's home, traits and behaviour for all agents, then `agents/<id>/AGENTS.md`, if
|
|
133
|
+
you keep one: rules the agent cannot change.
|
|
81
134
|
3. The files it keeps itself, from its workspace: `AGENTS.md` (also `CLAUDE.md`), `SOUL.md`,
|
|
82
|
-
then `
|
|
135
|
+
then `TOOLS.md` from pine's home and its own `TOOLS.md`, then `USER.md` from pine's home,
|
|
136
|
+
then `MEMORY.md`. See "The files an agent keeps itself".
|
|
83
137
|
After them the instruction files of a folder opened for the conversation, and any files in
|
|
84
|
-
`context`.
|
|
138
|
+
`context`. All of them are in the table below.
|
|
139
|
+
|
|
140
|
+
### Every file that is read as instructions
|
|
141
|
+
|
|
142
|
+
In the order they enter the prompt. A file that does not exist is left out.
|
|
143
|
+
|
|
144
|
+
| File | Where | What it is | Who writes it |
|
|
145
|
+
|---|---|---|---|
|
|
146
|
+
| `SYSTEM.md` | `agents/<id>/` | Optional. Replaces pine's base prompt for this agent | You |
|
|
147
|
+
| `AGENTS.md` (for all agents) | pine's home | Traits and behaviour for every agent | The main agent, and you |
|
|
148
|
+
| `AGENTS.md` (your rules for one agent) | `agents/<id>/` | Optional. Rules the agent reads and cannot change | You |
|
|
149
|
+
| `AGENTS.md` (the agent's own) | its workspace | Its purpose and how it works | The agent, and you; the main agent with `update_agent` (`instructions`) |
|
|
150
|
+
| `CLAUDE.md` | its workspace | Optional. Read like its `AGENTS.md`, for a workspace that is a repository with one | You |
|
|
151
|
+
| `SOUL.md` | its workspace | Who it is: character and tone | The agent, and you; the main agent with `update_agent` (`soul`) |
|
|
152
|
+
| `TOOLS.md` (for all agents) | pine's home | Tooling defaults and preferences for every agent | The main agent, and you |
|
|
153
|
+
| `TOOLS.md` (the agent's own) | its workspace | Its own tooling defaults and preferences, on top of the ones for all agents | The agent, and you; the main agent with `update_agent` (`tooling`) |
|
|
154
|
+
| `USER.md` | pine's home | What every agent knows about you | The main agent, and you |
|
|
155
|
+
| `MEMORY.md` | its workspace | What should outlive a conversation | The agent |
|
|
156
|
+
| `AGENTS.md`, `CLAUDE.md` of an opened folder | the folder you opened for a conversation | The project's instructions, for that conversation ([coding.md](coding.md)) | You, or whoever keeps the project |
|
|
157
|
+
| Files named in `context` | anywhere you point `agent.json` at | Further instruction files of yours | You |
|
|
158
|
+
| `SKILL.md` | a skill's folder | Not read into the prompt: one line per skill is, and the agent reads the file when it uses the skill | `add_skill`, or you |
|
|
159
|
+
|
|
160
|
+
No other markdown file is read by itself. `IDENTITY.md`, `HEARTBEAT.md`, daily notes and
|
|
161
|
+
whatever else lies in a workspace are the agent's own files, which it opens when it needs them.
|
|
85
162
|
4. Its skills: one line each; the agent reads a skill's file when it needs it. This manual is
|
|
86
163
|
not among them: the agent searches it with its `manual` tool (see below). An agent asked
|
|
87
164
|
for another model or a route looks it up and tells you what to put into which file; an
|
|
@@ -114,12 +191,130 @@ with outside content. The note is only added when something other than the time
|
|
|
114
191
|
changed since the last one. Text that arrives from elsewhere cannot fake a note; the tag is
|
|
115
192
|
rewritten on the way in.
|
|
116
193
|
|
|
117
|
-
The bottom bar of the terminal UI shows `cache N%` after an answer: the share of the input the
|
|
118
|
-
model server took from its cache. In a running conversation it should be above 90%.
|
|
119
|
-
|
|
120
194
|
The details of how pine works are not in the prompt; they are in this manual, which the agent
|
|
121
195
|
searches when a question calls for it. That keeps the prompt short for small models.
|
|
122
196
|
|
|
197
|
+
### How tools are declared
|
|
198
|
+
|
|
199
|
+
Every tool an agent has is declared to the model with each request: its name, what it does and
|
|
200
|
+
what it takes. The main agent has about eighty tools, and declared one by one they are about
|
|
201
|
+
25 000 tokens, which a local model reads before the first word of a new conversation. So pine
|
|
202
|
+
declares them in **families** (`catalogue`), which is about 11 500:
|
|
203
|
+
|
|
204
|
+
- What nearly every task uses is declared by itself, with a short description: `read`, `bash`,
|
|
205
|
+
`edit`, `write`, `grep`, `find`, `ls`, `download`, `delegate`, `subagent`, `todo`,
|
|
206
|
+
`question`, `manual`, and the two web tools.
|
|
207
|
+
- Everything else is grouped. A family is one declared tool that takes an `action` and the
|
|
208
|
+
arguments of that action, and its description has one line for each action.
|
|
209
|
+
- The lists are one tool of their own, `pine_list`, which takes one or several in `what`.
|
|
210
|
+
|
|
211
|
+
| Family | Its actions |
|
|
212
|
+
|---|---|
|
|
213
|
+
| `pine_list` | What there is: `sources`, `schedules`, `mcp_servers`, `skills`, and for the main agent `agents`, `settings`, `routes`, `conversations`. `what` takes several at once (`["sources", "schedules"]`) |
|
|
214
|
+
| `pine_sources` | `subscribe`, `unsubscribe`, `add_source`, `send`, `remove_source`, `publish_event`, and for the main agent `add_source_type`, `remove_source_type` |
|
|
215
|
+
| `pine_schedules` | `add_schedule`, `remove_schedule` |
|
|
216
|
+
| `pine_mcp` | `add_mcp_server`, `remove_mcp_server`, and the three tools for a server's resources |
|
|
217
|
+
| `pine_skills` | `add_skill`, `remove_skill` |
|
|
218
|
+
| `pine_agents` | The main agent's: `create_agent`, `update_agent`, `remove_agent` |
|
|
219
|
+
| `pine_settings` | The main agent's: `set_setting`, `add_route`, `remove_route`, `add_model_server`, `remove_model_server` |
|
|
220
|
+
| `pine_other` | `request_access`, `stop_program`, `state_get`, `state_set` |
|
|
221
|
+
| `pine_conversations` | The main agent's: `read_conversation`, `set_conversation`, `remove_conversation` |
|
|
222
|
+
| One for each MCP server, named after the server (`browser`, `media`, `home_link`) | The server's tools under their own names (`browser_navigate`, `browser_click`) |
|
|
223
|
+
|
|
224
|
+
An action has the name its tool has everywhere in this manual. Where the manual says "call
|
|
225
|
+
`add_source`", an agent with families calls `pine_sources` with `action: "add_source"` and the
|
|
226
|
+
same arguments; a list, "call `sources`" in the manual, is `pine_list` with
|
|
227
|
+
`what: ["sources"]`; a tool of an MCP server, `mcp__browser__browser_navigate` in the manual, is
|
|
228
|
+
`browser` with `action: "browser_navigate"`. Nothing else is different. The call is carried
|
|
229
|
+
out by the tool that is meant, so modes, approvals, an `approve` or `deny` list, plan mode and
|
|
230
|
+
the rules after outside content all see `add_source` or `mcp__browser__browser_navigate`, and
|
|
231
|
+
so does the terminal UI.
|
|
232
|
+
|
|
233
|
+
| Name | What it is |
|
|
234
|
+
|---|---|
|
|
235
|
+
| `catalogue` | In `agent.json`: `families` or `full`, for that agent. Not set: `defaults.catalogue`. |
|
|
236
|
+
| `defaults.catalogue` | In `pine.json`: how the tools of every agent that names nothing are declared. `families` (the default): grouped, as above. `full`: every tool by itself with its whole description, as before; about two and a half times as much to read at the start of a conversation. The main agent changes it with `set_setting`; it holds from the next start of pine. |
|
|
237
|
+
| `find_tools` | A tool every agent with families has. `names`: actions or a whole family. Answers with everything about them: each argument, its limits, examples. For the rare case that the line in the family is not enough. |
|
|
238
|
+
|
|
239
|
+
What keeps a short declaration from costing calls:
|
|
240
|
+
|
|
241
|
+
- The arguments of a family are typed, with the values an argument can take listed, so a model
|
|
242
|
+
server that holds a model to the declared arguments (llama.cpp does) cannot be given an
|
|
243
|
+
argument that does not exist.
|
|
244
|
+
- A call that is nearly right is carried out as meant: a name with capitals or spaces becomes
|
|
245
|
+
the name it stands for, a number or a list written as text is read as one, `path` for a
|
|
246
|
+
folder source's `dir`, a setting named by its last word, an action asked of the wrong family
|
|
247
|
+
(a list asked of the family it belongs to in spirit, `pine_schedules` with `schedules`).
|
|
248
|
+
- A call with wrong arguments comes back with the whole description of that action, so the
|
|
249
|
+
next call is right.
|
|
250
|
+
|
|
251
|
+
A run that an outside event started is declared its few tools as before, each by itself.
|
|
252
|
+
An `agents/<id>/SYSTEM.md` and a list in `tools` work with either setting.
|
|
253
|
+
|
|
254
|
+
### What the model server keeps
|
|
255
|
+
|
|
256
|
+
A model server keeps what it has read of a request, and reads only what is new in the next one,
|
|
257
|
+
as long as the next one begins the same. On a local model that is the difference between an
|
|
258
|
+
answer that starts at once and one that starts after the whole conversation was read again.
|
|
259
|
+
With families, pine builds every request so that its beginning does not change:
|
|
260
|
+
|
|
261
|
+
| Part of the request | Stays the same |
|
|
262
|
+
|---|---|
|
|
263
|
+
| The tools | Always in one order and with fixed wording, for every conversation of the agent. Nothing in a description names what changes (which agents there are, which sources): that is in the note. |
|
|
264
|
+
| The system prompt | pine's own text only, the same for every conversation of the agent, today and after a restart. |
|
|
265
|
+
| The instruction files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `MEMORY.md`, those for all agents in pine's home, a folder's) | They open the conversation as a first message of their own, in `<instructions>`, as they were when the conversation began. What is added to one later, the agent is told once, in the note in front of the next message ("New in your MEMORY.md since this conversation began"). A `MEMORY.md` that was rewritten (tidied, lines dropped) is told the same way, as it now reads. A file of rules that lost or changed lines (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, one of the files for all agents), or a memory longer than 8 000 characters, is taken anew, so that a rule that was taken back is not in front of the model: that conversation is read again once, the tools and pine's text before it are not. |
|
|
266
|
+
| What changes (agents to hand work to, event sources to subscribe to, the time) | In the `<pine-note>` in front of a message, only when it changed. |
|
|
267
|
+
|
|
268
|
+
So a line the agent writes into `MEMORY.md`, an agent that is created or removed, a schedule,
|
|
269
|
+
a new MCP server for another conversation, and a restart of pine all cost nothing: the next
|
|
270
|
+
message is read on top of what the server has. What still costs a reading is what truly is
|
|
271
|
+
new: the first conversation after the model was loaded, a tool that was added to this
|
|
272
|
+
conversation, and a conversation that was compacted.
|
|
273
|
+
|
|
274
|
+
A llama.cpp server keeps one conversation in each of its slots (`-np`). pine asks the server
|
|
275
|
+
how many it has and names the slot with each request (`id_slot`):
|
|
276
|
+
|
|
277
|
+
- A conversation goes back to the slot it was in, also after a restart of pine.
|
|
278
|
+
- One that has none takes a slot pine filled for it (below), else an empty one, else the slot
|
|
279
|
+
that is cheapest to read again. It never takes a slot in which a request is under way.
|
|
280
|
+
- A run started from outside is named a slot too, so that it does not take yours.
|
|
281
|
+
- Another client of the same server (a second pine, another program) has its conversations in
|
|
282
|
+
slots too. pine asks the server what its slots hold (`/slots`) before it chooses one: a slot
|
|
283
|
+
with somebody else's conversation is not taken for empty and not filled in the background,
|
|
284
|
+
and when no slot is empty the smaller conversation goes, whoever's it is. Two clients on one
|
|
285
|
+
server still share its slots: what one of them pushes out, the other reads again.
|
|
286
|
+
- When the server has kept nothing of a long conversation, it was started anew; pine then
|
|
287
|
+
takes its other slots for empty as well.
|
|
288
|
+
|
|
289
|
+
Another kind of server is never sent a slot.
|
|
290
|
+
|
|
291
|
+
| Setting | Default | Meaning |
|
|
292
|
+
|---|---|---|
|
|
293
|
+
| `limits.warmSlots` | `true` | Filling idle slots. When pine has left a llama.cpp server alone for a moment, it has each slot that holds nothing read what a conversation of the agent that used the server last begins with: its tools, pine's text, its instruction files as they are now. The next new conversation of that agent, and a sub-agent, is given such a slot and has only its own message to be read. One slot at a time, only while no agent is at work with that model, and never when the model is not loaded (so it is never what loads a model). A filled slot is filled again when the instruction files changed. `false` turns it off. The main agent changes it with `set_setting`, at once. |
|
|
294
|
+
| `limits.warmAfterMs` | `3000` | How long the model server has to have been left alone before a slot is filled, in milliseconds. |
|
|
295
|
+
| `limits.slotPages` | `6` | More conversations than slots. A conversation whose slot another one takes is first written into a file of the model server, and read back from it when it comes again: that takes about as long as copying the file, not as long as reading the conversation. So conversations beyond the server's slots keep what was read of them, also across a restart of the server. Needs a llama.cpp server that was started with a folder for it (`--slot-save-path <folder>`); one that has none says so once and is not asked again. This many files are kept for each model server, with fixed names (`pine-<id>-<n>.bin`), used again and again; a conversation of 10 000 tokens is about a gigabyte on a large model. A sub-agent's conversation is not kept. `0` turns it off. |
|
|
296
|
+
|
|
297
|
+
A sub-agent is declared exactly the tools and the text its conversation is declared, also the
|
|
298
|
+
ones that are not its to use (`subagent`, `delegate`, what only a conversation sets up): asked
|
|
299
|
+
for one of those it is told "You are a sub-agent: this is not yours to do." That way a
|
|
300
|
+
sub-agent begins with what the model server has read already, and only its task is new.
|
|
301
|
+
|
|
302
|
+
What pine cannot help:
|
|
303
|
+
|
|
304
|
+
- A server that is stopped and started again (a scheduler that makes room for another model)
|
|
305
|
+
has read nothing. llama.cpp can save a slot and bring it back (`--slot-save-path`); a
|
|
306
|
+
scheduler has to do that around the stop.
|
|
307
|
+
- With more conversations than the server has slots, one of them leaves its slot. With a
|
|
308
|
+
folder for the server's slots (`limits.slotPages`) it is read back from a file; without one
|
|
309
|
+
it is read again by the model. Either way, give the server at least as many slots as
|
|
310
|
+
`limits.maxConcurrentRuns`, and one more if sub-agents are used a lot.
|
|
311
|
+
- A model that cannot go back part of the way in what it has read (llama.cpp says "forcing
|
|
312
|
+
full prompt re-processing" in its log) reads a conversation from its beginning when it was
|
|
313
|
+
pushed out of its slot. Slots are what prevents that.
|
|
314
|
+
|
|
315
|
+
The bottom bar of the terminal UI shows `cache N%` after an answer: the share of the input the
|
|
316
|
+
model server took from its cache. In a running conversation it should be above 90%.
|
|
317
|
+
|
|
123
318
|
### The manual tool
|
|
124
319
|
|
|
125
320
|
Every agent has a `manual` tool (not in a run that an outside event started). It holds the
|
|
@@ -261,9 +456,10 @@ whether the agent is called again. What the agent may do in a round is decided a
|
|
|
261
456
|
task, by its mode and the approvals ([security.md](security.md), "A goal goes on
|
|
262
457
|
in your name").
|
|
263
458
|
|
|
264
|
-
On a local model each round costs a full turn
|
|
265
|
-
|
|
266
|
-
|
|
459
|
+
On a local model each round costs a full turn. On a llama.cpp server with two slots or more
|
|
460
|
+
the judge's call is given a slot of its own, so the agent's conversation stays where the
|
|
461
|
+
server has it; on a server with one slot the call pushes the conversation out, unless the
|
|
462
|
+
judge has a model of its own (`defaults.judge`). Say in the objective how to tell that it is reached ("the tests pass",
|
|
267
463
|
"the file exists and has all twelve entries"): the judge sees only the agent's answer, not the
|
|
268
464
|
files.
|
|
269
465
|
|
|
@@ -298,19 +494,47 @@ agent. "Contract law; knows the case files in its workspace" works;
|
|
|
298
494
|
|
|
299
495
|
## Sub-agents
|
|
300
496
|
|
|
301
|
-
`subagent(tasks: string[])` runs up to `subagents.maxParallel` copies of the
|
|
302
|
-
(4 unless the agent's `agent.json` says otherwise).
|
|
497
|
+
`subagent(tasks: string[], model?, thinking?)` runs up to `subagents.maxParallel` copies of the
|
|
498
|
+
same agent at once (4 unless the agent's `agent.json` says otherwise).
|
|
303
499
|
Each copy has the agent's workspace, instructions and tools but an empty conversation, cannot
|
|
304
500
|
delegate or spawn further, and returns only its final answer. Use it for searches and checks
|
|
305
501
|
that would otherwise fill the context:
|
|
306
502
|
|
|
307
503
|
> Find every clause about notice periods in `contracts/`. Use sub-agents, one per file.
|
|
308
504
|
|
|
309
|
-
|
|
310
|
-
|
|
505
|
+
| Argument | What it does |
|
|
506
|
+
|---|---|
|
|
507
|
+
| `tasks` | One task per sub-agent. A sub-agent sees nothing of the conversation, so each task says everything it needs: what to do, which files (by their path), what to answer. |
|
|
508
|
+
| `model` | Another model for these sub-agents than the agent's own, as `provider/model` (the id alone is enough where only one model has it). For work another model does better: one that sees pictures, a small fast one for many simple checks, a large one for a hard part. The `models` tool lists what there is. Left out: the agent's own model. |
|
|
509
|
+
| `thinking` | How much these sub-agents reason: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. A model that cannot reason ignores it. Left out: the agent's own level. |
|
|
510
|
+
|
|
511
|
+
A sub-agent on another model is still the same agent: the same workspace, files, tools,
|
|
512
|
+
instructions and permissions. Only the model that reads and answers is another one. So a file is
|
|
513
|
+
handed to it by its path, also a picture or a file an event source received
|
|
514
|
+
([sources.md](sources.md), "Files a source received"): the sub-agent opens it with `read`, and a
|
|
515
|
+
model that sees pictures is shown it. A video or a sound file is not shown to any model; the
|
|
516
|
+
sub-agent turns a video into pictures first, as the agent itself would.
|
|
517
|
+
|
|
518
|
+
> Have a sub-agent on local/nemo look at the camera clip and describe who is in the garden.
|
|
519
|
+
|
|
520
|
+
The model of the conversation itself does not change this way: that is `update_agent` of the
|
|
521
|
+
main agent, `/model` in the terminal UI or `pine agent update`. A run that an outside event
|
|
522
|
+
started has sub-agents only where its `untrusted` profile allows them, and they run on the
|
|
523
|
+
agent's own model: such a run chooses none.
|
|
524
|
+
|
|
525
|
+
A sub-agent works under the permissions of the conversation that started it: the access you
|
|
526
|
+
granted there, your "always" answers and the conversation's folder apply to it. It never waits
|
|
527
|
+
for you. Where you would be asked (a critical action, a path outside what the conversation has,
|
|
528
|
+
a question), the sub-agent is refused and told to say in its answer what it needed, and the
|
|
529
|
+
conversation that started it can ask you. So allow what sub-agents will need before they start
|
|
530
|
+
(`request_access` in the conversation). In manual mode, where every action waits for your
|
|
531
|
+
go-ahead, a sub-agent only reads, unless you answered "always" for a tool there.
|
|
311
532
|
It has the agent's MCP servers (unless `subagents.mcp` is `false`) and all its tools, or the
|
|
312
533
|
ones listed in `subagents.tools`.
|
|
313
534
|
|
|
535
|
+
A sub-agent is declared the same tools and text as its conversation, so that the model server
|
|
536
|
+
has read its beginning already ("What the model server keeps").
|
|
537
|
+
|
|
314
538
|
Sub-agents count against the model slots. With fewer slots than sub-agents they queue; nothing
|
|
315
539
|
deadlocks, because the waiting parent lends out its own slot.
|
|
316
540
|
|
|
@@ -67,7 +67,7 @@ when no folder is open. In a terminal of 100 columns or more it takes half the w
|
|
|
67
67
|
96 columns); in a narrower one it takes the place of the conversation until it is closed.
|
|
68
68
|
|
|
69
69
|
```
|
|
70
|
-
pine 1 main × 2 main·shop × +
|
|
70
|
+
pine 1 ★ main × 2 main·shop × + ▤ code
|
|
71
71
|
───────────────────────────────────────────────────────────────────────────────────────────
|
|
72
72
|
make the total include shipping │ Changes Files Output Running ↻ ×
|
|
73
73
|
│ main · 2 changed · ~/dev/shop
|
|
@@ -27,7 +27,7 @@ who may operate apps, and who may not.
|
|
|
27
27
|
| Another agent whose mode is `auto` or `bypass`, in a conversation with its owner | Yes, the same way |
|
|
28
28
|
| An agent that works in its sandbox: `safe` or `manual` mode (every agent but the main one, unless configured otherwise) | No. The tools are not in its list. Operating apps is acting with the owner's whole account, which such an agent does not have |
|
|
29
29
|
| A run that an event from outside started (a mail, a webhook, a message from somebody else) | Never, whatever the agent's `untrusted` profile lists |
|
|
30
|
-
| Sub-agents of a conversation that has it | Yes, when the agent's `subagents.mcp` is on; they share the conversation's answers |
|
|
30
|
+
| Sub-agents of a conversation that has it | Yes, when the agent's `subagents.mcp` is on; they share the conversation's answers, and ask for no app themselves |
|
|
31
31
|
|
|
32
32
|
An agent without the tools cannot get them by asking: `request_access` does not give app
|
|
33
33
|
control. The owner gives it by putting the agent in `auto` mode (`/mode auto`, or `mode` in
|
|
@@ -9,15 +9,19 @@ Everything pine needs is in its home directory: `~/.pine` by default, or `$PINE_
|
|
|
9
9
|
models.json optional: your own model servers, in pi's format
|
|
10
10
|
.env secrets, referenced from the JSON files as ${NAME}
|
|
11
11
|
auth.json provider credentials, written by `pine login`
|
|
12
|
-
|
|
12
|
+
AGENTS.md traits and behaviour for all agents ┐ in every agent's prompt,
|
|
13
|
+
TOOLS.md tooling defaults and preferences │ kept by the main agent
|
|
14
|
+
USER.md what all agents know about you ┘ (agents.md)
|
|
13
15
|
agents/
|
|
14
16
|
main/
|
|
15
17
|
agent.json this agent's settings
|
|
16
18
|
workspace/ its working folder, unless agent.json points elsewhere
|
|
17
19
|
AGENTS.md its purpose and how it works ┐ read into its prompt,
|
|
18
20
|
SOUL.md who it is │ written by the agent itself
|
|
19
|
-
|
|
21
|
+
TOOLS.md how it uses its tools │ (agents.md)
|
|
22
|
+
MEMORY.md what should outlive a talk ┘
|
|
20
23
|
AGENTS.md optional: rules of yours the agent cannot change
|
|
24
|
+
SYSTEM.md optional: replaces pine's base prompt for this agent
|
|
21
25
|
skills/ skills only this agent has
|
|
22
26
|
conversations/ what was set up for one conversation alone (its skills); made when needed
|
|
23
27
|
extensions/ pi extensions only this agent loads
|
|
@@ -85,6 +89,7 @@ asked you for it (`pine model add`, `add_model_server`); `models.json` names it
|
|
|
85
89
|
| `dataDir` | `data` | Where the database, media and control token live. |
|
|
86
90
|
| `defaults.model` | none | `provider/model-id` from `models.json`: the model of every agent whose `agent.json` names none. There is no built-in fallback: an agent with neither is a configuration error, which `pine check` and the start of pine report. |
|
|
87
91
|
| `defaults.judge` | not set | The model of the judge of goal mode (`/goal`), as `provider/model-id`. Not set: the agent's own model. A second, small model keeps the judge's call from pushing the agent's conversation out of a model server's cache. See "Goal mode" in [agents.md](agents.md). |
|
|
92
|
+
| `defaults.catalogue` | `families` | How tools are declared to the model, for every agent that names nothing: `families` (grouped, a short line for each tool; about 11 500 tokens for the main agent) or `full` (every tool by itself with its whole description; about 25 000). See [agents.md](agents.md), "How tools are declared". |
|
|
88
93
|
| `defaults.thinking` | `off` | Reasoning level for models that can reason: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
|
|
89
94
|
| `defaults.mode` | not set | The mode of every agent that names none: `auto`, `safe`, `manual`, `bypass` or `plan` (see `mode` below). Not set: `auto` for the main agent, `safe` for all others. Set it to `safe` to keep every agent, the main one too, in its sandbox. See "Modes" in [security.md](security.md). |
|
|
90
95
|
| `defaults.bashTimeoutSec` | `900` | Longest a shell command may run (15 minutes: a build, an install). The model cannot raise it. A server or another program that should keep running, and whatever needs longer, is started in the background, which is not held to it ([coding.md](coding.md)). |
|
|
@@ -92,6 +97,9 @@ asked you for it (`pine model add`, `add_model_server`); `models.json` names it
|
|
|
92
97
|
| `defaults.idleMs` | `15m` | A live session without work is closed after this (and resumed from disk later). |
|
|
93
98
|
| `defaults.settings` | `{}` | pi settings applied to every agent, for example `{ "compaction": { "reserveTokens": 8000 } }`. They are put on top of pi's own settings files and stay in force when pi reads those files again. |
|
|
94
99
|
| `limits.maxConcurrentRuns` | `2` | Model slots: how many runs talk to the model server at once. Match it to the server's parallel slots. |
|
|
100
|
+
| `limits.warmSlots` | `true` | Whether pine has the idle slots of a llama.cpp model server read, in the background, what a conversation of the agent that used it last begins with, so that a new conversation or a sub-agent starts at once. See [agents.md](agents.md), "What the model server keeps". |
|
|
101
|
+
| `limits.warmAfterMs` | `3000` | How long the model server has to have been left alone before an idle slot is filled, in milliseconds. |
|
|
102
|
+
| `limits.slotPages` | `6` | How many conversations that had to leave their slot on a llama.cpp model server are kept in files there and read back when they come again. Needs a server started with `--slot-save-path`. `0`: none. See [agents.md](agents.md), "What the model server keeps". |
|
|
95
103
|
| `limits.maxDelegationDepth` | `3` | How deep a chain of delegations may go. |
|
|
96
104
|
| `limits.maxDownloadMb` | `200` | Largest file the `download` tool fetches. |
|
|
97
105
|
| `limits.maxEventHops` | `8` | Events further than this from an outside trigger are not routed. |
|
|
@@ -153,9 +161,10 @@ Every key is optional; `{}` is a valid agent.
|
|
|
153
161
|
| Key | Default | Meaning |
|
|
154
162
|
|---|---|---|
|
|
155
163
|
| `description` | empty | One line other agents see when they choose whom to delegate to. Write it for them. |
|
|
156
|
-
| `workspace` | `agents/<id>/workspace` | The agent's working folder. `AGENTS.md`, `SOUL.md` and `MEMORY.md` at its top are the agent's instructions and are loaded into its prompt. Must exist when you set it. |
|
|
164
|
+
| `workspace` | `agents/<id>/workspace` | The agent's working folder. `AGENTS.md`, `SOUL.md`, `TOOLS.md` and `MEMORY.md` at its top are the agent's instructions and are loaded into its prompt. Must exist when you set it. |
|
|
157
165
|
| `context` | `[]` | Further instruction files to load into the system prompt. |
|
|
158
166
|
| `model`, `thinking` | from `defaults` | Per-agent model and thinking level. |
|
|
167
|
+
| `catalogue` | from `defaults.catalogue` | How this agent's tools are declared to the model: `families` or `full`. See [agents.md](agents.md), "How tools are declared". |
|
|
159
168
|
| `settings` | from `defaults.settings` | pi settings for this agent, key by key on top of `defaults.settings`. `agents/<id>/settings.json` is honoured as well; where both set a key, the one here counts. |
|
|
160
169
|
| `taskTimeoutSec`, `idleMs` | from `defaults` | Per-agent overrides. |
|
|
161
170
|
|
|
@@ -178,7 +187,7 @@ Every key is optional; `{}` is a valid agent.
|
|
|
178
187
|
| Key | Default | Meaning |
|
|
179
188
|
|---|---|---|
|
|
180
189
|
| `delegates` | `["*"]` for the agent that `main` in `pine.json` names, else `[]` | Agents this one may hand tasks to. |
|
|
181
|
-
| `subagents` | on, 4 in parallel | `false`, or `{ "maxParallel": 4, "tools": [...], "mcp": true }`. `tools` narrows what sub-agents get. |
|
|
190
|
+
| `subagents` | on, 4 in parallel | `false`, or `{ "maxParallel": 4, "tools": [...], "mcp": true }`. `tools` narrows what sub-agents get. Which model they run on, the agent says call by call (`model` of `subagent`); without it, the agent's own. |
|
|
182
191
|
| `publish` | `[]` | Topic patterns the `publish_event` tool may publish on. Empty: the agent has no such tool. |
|
|
183
192
|
| `state.read` | `["#"]` | State keys the agent may read. |
|
|
184
193
|
| `state.write` | `["agent/<id>/#"]` | State keys the agent may write. |
|
|
@@ -195,7 +204,7 @@ Every key is optional; `{}` is a valid agent.
|
|
|
195
204
|
| `sandbox.env` | `{}` | Extra environment variables for the agent's shell. Do not put secrets here; the agent can read them. |
|
|
196
205
|
| `trustWorkspace` | `false` | `true` lets pi load `.pi/extensions`, `.pi/settings.json` and skills from the workspace. That is code execution inside the daemon for whoever can write there, the agent included. |
|
|
197
206
|
| `approve` | `[]` | Tool calls that always need your approval: `"tool"` or `"tool:argument-glob"`, for example `"bash:*git push*"`. |
|
|
198
|
-
| `approveWhenTainted` | `["publish_event", "send"]` | Tool calls that count as sending something out. Once the session has seen outside content they need your approval. |
|
|
207
|
+
| `approveWhenTainted` | `["publish_event", "send"]` | Tool calls that count as sending something out. Once the session has seen outside content they need your approval. A `send` through a source that reaches only you (Telegram) is a message to you and is never asked about this way; to see those first, name it in `approve` (`"send:telegram"`). |
|
|
199
208
|
| `untrusted` | read-only profile | What a run started by an untrusted event may use: `{ "tools": ["read","grep","find","ls"], "mcp": [], "delegates": [], "publish": [], "stateWrite": false, "subagents": false }`. `false` refuses such runs. |
|
|
200
209
|
|
|
201
210
|
## models.json
|
package/docs/references/mcp.md
CHANGED
|
@@ -206,6 +206,10 @@ reached over the network, that can be another computer, and three things follow:
|
|
|
206
206
|
cannot send it anywhere else. Any other address on the server is fetched without the key, and
|
|
207
207
|
a server that wants it answers HTTP 401: the agent calls the tool again and downloads the
|
|
208
208
|
link it gets. After a `/reset` or a restart of pine the links given before count no longer.
|
|
209
|
+
- **The `download` tool says how the file is shown.** When what it saved is a picture, a video
|
|
210
|
+
or a sound (by the name it was saved under), its answer ends with the line to write into the
|
|
211
|
+
reply: ``, with the `!` in front. A server's own words for the next step
|
|
212
|
+
("play it", "attach it") do not say how, and a plain link `[..](..)` shows and plays nothing.
|
|
209
213
|
|
|
210
214
|
A server of your own that returns its files' paths is better off returning only a name and a
|
|
211
215
|
link: a path is of use to nobody who is not on the same computer.
|
|
@@ -350,6 +354,11 @@ What the guard does:
|
|
|
350
354
|
server or pine's control port, whether by link, redirect, script or DNS trick. The one
|
|
351
355
|
exception is an address you allowed for a conversation ("Local addresses" below). `file:`
|
|
352
356
|
URLs are blocked by Playwright.
|
|
357
|
+
- **No road around the proxy.** A proxy carries what a browser asks it to carry, and a browser
|
|
358
|
+
can also send things without asking: WebRTC (what video calls use) opens connections of its
|
|
359
|
+
own, and so does the newer web transport over QUIC. Both are switched off outside the proxy,
|
|
360
|
+
and the browser looks no names up itself. A page that uses WebRTC still loads; a call that
|
|
361
|
+
needs a direct connection between two computers does not come about.
|
|
353
362
|
- **No code on your machine.** `browser_run_code_unsafe` (runs code in the server process),
|
|
354
363
|
`browser_file_upload` and `browser_drop` (hand local files to a page), `browser_install`, and
|
|
355
364
|
`browser_storage_state` and `browser_set_storage_state` (write and read a file of cookies)
|
|
@@ -9,8 +9,9 @@
|
|
|
9
9
|
whose mode you did not choose work in `auto`, one you set to `safe` has no shell, and `pine check`
|
|
10
10
|
says why. See [security.md](security.md), "On Linux".
|
|
11
11
|
- Optional: `ffmpeg` for videos in the terminal UI (on Linux also for pictures other than
|
|
12
|
-
png, and its `ffplay` for sound; `mpv`,
|
|
13
|
-
|
|
12
|
+
png, for the bars of a sound that is not a wav file, and its `ffplay` for sound; `mpv`,
|
|
13
|
+
`pw-play`, `paplay` or `aplay` do as well. macOS plays sound and draws its bars with what it
|
|
14
|
+
has); on Linux `xclip`, or on Wayland `wl-copy` and `wl-paste`, for copying a selection and
|
|
14
15
|
pasting a picture.
|
|
15
16
|
- Node 24 or newer. From a checkout Node runs the TypeScript sources directly; the npm package
|
|
16
17
|
holds them compiled.
|
|
@@ -31,7 +32,7 @@ To work on pine itself, use a checkout instead. `bin/pine` runs the sources as t
|
|
|
31
32
|
installs the dependencies the first time; `npm link` puts that copy on your PATH:
|
|
32
33
|
|
|
33
34
|
```bash
|
|
34
|
-
git clone https://github.com/
|
|
35
|
+
git clone https://github.com/pmndre/pine ~/dev/pine
|
|
35
36
|
```
|
|
36
37
|
|
|
37
38
|
```bash
|
|
@@ -200,6 +201,10 @@ how pine got onto the machine, which `pine version` tells you:
|
|
|
200
201
|
Afterwards it makes sure the browser the web tools drive matches the new version, which is a
|
|
201
202
|
download only when that version changed.
|
|
202
203
|
|
|
204
|
+
When it is done it says what changed, as a list: every version between the one you had and
|
|
205
|
+
the one you have now, the newest first, with a line for each change under it (after a
|
|
206
|
+
checkout was moved forward, a line for every commit that came). The list travels with the package, so nothing is fetched for it.
|
|
207
|
+
|
|
203
208
|
`pine update --check` changes nothing and says whether there is something newer.
|
|
204
209
|
|
|
205
210
|
A pine that is running keeps the old version until it is restarted: quit the terminal UI and
|
|
@@ -230,7 +235,7 @@ What you type in a shell. Every command is the `pine` program with a word after
|
|
|
230
235
|
| `pine agents` | Configured agents, as the daemon has them (JSON) |
|
|
231
236
|
| `pine agent list` | The agents, readable: what each is for, model, reasoning, mode, reach, and what it has (conversations, sources, MCP servers, schedules, skills, routes that wake it, files in its workspace). Read from the files; needs no daemon |
|
|
232
237
|
| `pine agent add <id> --description "..." [--instructions "..."] [--instructions-file <file>] [--model provider/model] [--tools read,bash,...]` | Create an agent, as `create_agent` does: its folder with `agent.json` and a workspace with its instructions. Without instructions it starts from its description. A running daemon has it at once; without one it is there at the next start |
|
|
233
|
-
| `pine agent update <id> [--description ...] [--instructions ... \| --instructions-file <file>] [--soul ... \| --soul-file <file>] [--model ...\|default] [--thinking ...] [--mode auto\|safe\|manual\|bypass\|plan\|default] [--tools read,bash,...] [--delegates id,id\|*] [--network \| --no-network] [--read /p,/p] [--write /p] [--forget /p]` | Change an agent's settings, as `update_agent` does: give only what changes, the rest stays. It holds from the agent's next message on. A running daemon applies it at once; without one the files are changed and it is there at the next start, except a model change, which needs the daemon (it checks the model exists) |
|
|
238
|
+
| `pine agent update <id> [--description ...] [--instructions ... \| --instructions-file <file>] [--soul ... \| --soul-file <file>] [--tooling ... \| --tooling-file <file>] [--model ...\|default] [--thinking ...] [--mode auto\|safe\|manual\|bypass\|plan\|default] [--tools read,bash,...] [--delegates id,id\|*] [--network \| --no-network] [--read /p,/p] [--write /p] [--forget /p]` | Change an agent's settings, as `update_agent` does: give only what changes, the rest stays. It holds from the agent's next message on. A running daemon applies it at once; without one the files are changed and it is there at the next start, except a model change, which needs the daemon (it checks the model exists) |
|
|
234
239
|
| `pine agent remove <id> [--keep-files] [--yes]` | Remove an agent and everything it has, so that nothing of it is left: conversations, sources, schedules, servers, skills, the routes that wake it, what pine stored under its name, its folder and its private home. It lists what goes and asks before it deletes; `--yes` answers for a script. `--keep-files` moves the folder to `removed/` in pine's home instead of deleting it. Through a running daemon when there is one, in the files when not. See "Changing and removing an agent" in [setup.md](setup.md) |
|
|
235
240
|
| `pine send <agent> <text...>` | Give an agent a task as yourself and print the answer. `--session <key>`, `--no-wait` |
|
|
236
241
|
| `pine emit <topic> [json]` | Publish an event as yourself |
|
|
@@ -240,7 +245,7 @@ What you type in a shell. Every command is the `pine` program with a word after
|
|
|
240
245
|
| `pine cancel <id>` | Stop a task |
|
|
241
246
|
| `pine state [pattern]` | Shared state |
|
|
242
247
|
| `pine sources` | Lists the event sources: running or idle, who is subscribed, last event; for one that polls (`http`, `command`), when it last looked or since when that fails |
|
|
243
|
-
| `pine subscribe <agent> <source> [--session name] [--note text] [--throttle 5m] [--when json] [--separate]`, `pine unsubscribe <agent> <source> [--session name]` | Wake an agent on a source's events (with `--session`: only that conversation), or stop that |
|
|
248
|
+
| `pine subscribe <agent> <source> [--session name \| --fresh] [--note text] [--throttle 5m] [--when json] [--separate]`, `pine unsubscribe <agent> <source> [--session name]` | Wake an agent on a source's events (with `--session`: only that conversation), or stop that |
|
|
244
249
|
| `pine subscribe --global <source> [--note text] ...`, `pine unsubscribe --global <source>` | The same for every agent that can use the source |
|
|
245
250
|
| `pine approvals`, `pine approve <id> [--always]`, `pine deny <id>` | Answer approval requests; `--always` stops the question for the rest of that conversation |
|
|
246
251
|
| `pine reset <agent> [session]` | Start a conversation over; also clears its taint |
|
|
@@ -334,8 +339,10 @@ are JSON with `Content-Type: application/json`.
|
|
|
334
339
|
tools it called and the result. The full transcript is the newest `.jsonl` under
|
|
335
340
|
`~/.pine/agents/<id>/sessions/<session>/`.
|
|
336
341
|
- **Change instructions:** tell the agent ("from now on ..."); it writes that into `AGENTS.md` in
|
|
337
|
-
its workspace. Or edit the file yourself. Either applies to the next message. What
|
|
338
|
-
|
|
342
|
+
its workspace. Or edit the file yourself. Either applies to the next message. What is to
|
|
343
|
+
hold for all agents, tell the main agent: it keeps three files in pine's home that every
|
|
344
|
+
agent reads, `AGENTS.md` (traits and behaviour), `TOOLS.md` (defaults and preferences for
|
|
345
|
+
the tools) and `USER.md` (what agents know about you).
|
|
339
346
|
- **Change configuration:** edit `pine.json` or `agent.json`, run `pine check`, restart the
|
|
340
347
|
daemon. Queued tasks survive the restart. MCP servers, event sources, subscriptions and new
|
|
341
348
|
agents need neither an edit nor a restart: ask an agent ([setup.md](setup.md)), or use
|
|
@@ -345,7 +352,8 @@ are JSON with `Content-Type: application/json`.
|
|
|
345
352
|
the mode in the bottom bar of the terminal UI), or the question names a tool on its `approve`
|
|
346
353
|
list. Sending something out also asks after a conversation has read outside content (it is
|
|
347
354
|
tainted): "Always here" in the dialog covers that tool for the conversation, and `/reset`
|
|
348
|
-
or `pine reset` starts a clean one.
|
|
355
|
+
or `pine reset` starts a clean one. A message to you through Telegram is not among what
|
|
356
|
+
asks: an agent that watches something tells you without anybody at the keyboard.
|
|
349
357
|
- **Back up:** the home directory. `data/pine.db` holds events and tasks, `agents/*/sessions`
|
|
350
358
|
the conversations. Workspaces are wherever you put them.
|
|
351
359
|
|
|
@@ -357,6 +365,8 @@ are JSON with `Content-Type: application/json`.
|
|
|
357
365
|
| `model "x/y" is not defined in models.json` | `defaults.model` or an agent's `model` does not match `provider/id`. `/model` in the UI lists what is available. |
|
|
358
366
|
| A model of your own server is missing from `/model` | The server wants a key and `models.json` names one that is not in `.env`. `pine check` lists it under "Model notes"; add the line to `.env` and restart, or remove the server and add it again with `pine model add`. |
|
|
359
367
|
| `pine model add` says "no model server answers" | Nothing listens at that address, or it is not reachable from this machine (a firewall, a VPN that is off). `curl <address>/v1/models` shows what the server says. |
|
|
368
|
+
| An answer starts late: the model reads the whole conversation again after you were in another tab or conversation, or after a restart | The model server has kept nothing of the conversation. With a llama.cpp server pine keeps each conversation in a slot of its own; give the server enough slots (`-np`), and a folder for them (`--slot-save-path`), so that a conversation that has to leave its slot is read back from a file (`limits.slotPages`). A scheduler that stops and starts the model makes it forget everything unless it saves the slots. See [agents.md](agents.md), "What the model server keeps". |
|
|
369
|
+
| The first message of a new conversation takes long, and the tools take too many tokens of the prompt | The model reads every tool's declaration first. `defaults.catalogue` `families` (the default) declares them grouped and short; `limits.warmSlots` has an idle slot read that beginning ahead of time. See [agents.md](agents.md), "How tools are declared". |
|
|
360
370
|
| A task fails with 401 or "API key" | The provider's credential is missing or expired. `pine login <provider>` again. |
|
|
361
371
|
| The browser tools fail with "Executable doesn't exist" | Run `pine init` again (or `pine browser-install`): the browser is missing or pine was updated to a newer one. |
|
|
362
372
|
| The browser cannot open `localhost` or a page says "not reachable from the browser" | Local addresses need your yes. The agent opens the address with `browser_navigate` and you are asked; see "Local addresses" in [mcp.md](mcp.md). A server the agent started itself also needs network access for its shell. |
|
|
@@ -384,9 +394,10 @@ are JSON with `Content-Type: application/json`.
|
|
|
384
394
|
|---|---|
|
|
385
395
|
| Agents in `openclaw.json` with `workspace-*` folders | One folder per agent under `agents/`; `workspace` points at the repository |
|
|
386
396
|
| Telegram `bindings` | A `telegram` source the agent sets up when you ask it to, and is subscribed to |
|
|
387
|
-
| `SOUL.md`, `AGENTS.md`, `MEMORY.md` | The same
|
|
397
|
+
| `SOUL.md`, `AGENTS.md`, `TOOLS.md`, `MEMORY.md` | The same four names in the agent's workspace, read into its prompt and written by the agent |
|
|
388
398
|
| `USER.md` | One `USER.md` in pine's home for all agents, kept by the main agent |
|
|
389
|
-
| `
|
|
399
|
+
| One `TOOLS.md` or `AGENTS.md` copied into every workspace | A `TOOLS.md` and an `AGENTS.md` in pine's home for all agents, kept by the main agent and read by every agent before its own |
|
|
400
|
+
| `IDENTITY.md`, `HEARTBEAT.md`, daily memory files | Not read by pine. Fold what matters into `SOUL.md`, `AGENTS.md` or `MEMORY.md`; other notes are ordinary files in the workspace |
|
|
390
401
|
| Cron jobs | A schedule: ask the agent ("every morning at seven ..."), or write it under `schedules` with a `task` |
|
|
391
402
|
| Heartbeat | Usually not needed: an event source wakes the agent when something happens, and looking again and again (`http`, `command`) costs no model turn. For a real one, a schedule with `every` whose task ends in "reply NO_REPLY if nothing needs attention" |
|
|
392
403
|
| `/hooks/*` mappings | A `webhook` source the agent subscribes to, or `http.hooks` plus a route |
|
|
@@ -112,6 +112,7 @@ Topics pine itself uses:
|
|
|
112
112
|
| `hook/<name>` | A hook under `http.hooks` in `pine.json` was called (a `webhook` source reports `source/<name>/received` instead) |
|
|
113
113
|
| `approval/requested`, `approval/decided` | An approval is asked for or answered |
|
|
114
114
|
| `pine/started`, `pine/route-failed` | Daemon lifecycle and route errors |
|
|
115
|
+
| `pine/conversation` | The main agent changed a conversation (`open`, `close`, `rename`, `remove`, `pin`), so that a terminal UI's tabs follow. Not kept in the event log |
|
|
115
116
|
|
|
116
117
|
Agents cannot publish on `agent/`, `approval/`, `pine/`, `state/` or `timer/`.
|
|
117
118
|
|
|
@@ -172,7 +173,8 @@ line saying so; a cancelled one sends nothing.
|
|
|
172
173
|
`wait: false` the answer arrives later as a message in the caller's session.
|
|
173
174
|
- `subagent` runs several copies of the same agent in parallel, each with its own task and an
|
|
174
175
|
empty context, and returns their final answers. It keeps large searches out of the caller's
|
|
175
|
-
context.
|
|
176
|
+
context. The copies can run on another model than the agent's own (`model`) and reason more
|
|
177
|
+
or less (`thinking`).
|
|
176
178
|
- Shared state (`state_get`, `state_set`) holds small facts such as `house/mode` that every agent
|
|
177
179
|
can read and that can be shown to an agent in every turn.
|
|
178
180
|
- `publish_event` lets an agent put an event on a topic you allowed, which routes then act on.
|