@pmndre/pine 0.22.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +2 -1
  2. package/changes.json +265 -0
  3. package/docs/SKILL.md +31 -7
  4. package/docs/references/agents.md +245 -21
  5. package/docs/references/coding.md +1 -1
  6. package/docs/references/computer.md +1 -1
  7. package/docs/references/configuration.md +14 -5
  8. package/docs/references/mcp.md +9 -0
  9. package/docs/references/operations.md +20 -9
  10. package/docs/references/overview.md +3 -1
  11. package/docs/references/security.md +83 -24
  12. package/docs/references/setup.md +55 -9
  13. package/docs/references/source-types.md +1418 -0
  14. package/docs/references/sources.md +333 -19
  15. package/docs/references/stack.md +1 -0
  16. package/docs/references/tui.md +86 -12
  17. package/examples/home/AGENTS.md +4 -0
  18. package/examples/home/TOOLS.md +5 -0
  19. package/examples/home/agents/main/workspace/AGENTS.md +1 -1
  20. package/examples/home/agents/main/workspace/TOOLS.md +5 -0
  21. package/mcp/browser.d.ts +6 -0
  22. package/mcp/browser.js +19 -0
  23. package/mcp/render.d.ts +1 -0
  24. package/mcp/render.js +237 -0
  25. package/package.json +3 -1
  26. package/src/actions.d.ts +6 -1
  27. package/src/actions.js +17 -4
  28. package/src/admin.d.ts +4 -0
  29. package/src/admin.js +25 -6
  30. package/src/agents.d.ts +167 -2
  31. package/src/agents.js +912 -45
  32. package/src/catalogue.d.ts +60 -0
  33. package/src/catalogue.js +791 -0
  34. package/src/cli.js +10 -7
  35. package/src/config.d.ts +53 -4
  36. package/src/config.js +30 -5
  37. package/src/goals.d.ts +1 -1
  38. package/src/goals.js +14 -1
  39. package/src/manual.js +24 -2
  40. package/src/mime.d.ts +78 -0
  41. package/src/mime.js +342 -0
  42. package/src/net.d.ts +11 -0
  43. package/src/net.js +29 -2
  44. package/src/pine.js +10 -1
  45. package/src/router.js +3 -3
  46. package/src/sandbox-linux.d.ts +3 -1
  47. package/src/sandbox-linux.js +5 -0
  48. package/src/security.d.ts +22 -6
  49. package/src/security.js +44 -13
  50. package/src/slots.d.ts +106 -0
  51. package/src/slots.js +250 -0
  52. package/src/source-types.d.ts +20 -0
  53. package/src/sources/calendar.d.ts +24 -0
  54. package/src/sources/calendar.js +265 -0
  55. package/src/sources/command.js +109 -4
  56. package/src/sources/discord.d.ts +4 -0
  57. package/src/sources/discord.js +298 -0
  58. package/src/sources/feed.d.ts +19 -0
  59. package/src/sources/feed.js +257 -0
  60. package/src/sources/http.js +154 -103
  61. package/src/sources/mail.d.ts +51 -0
  62. package/src/sources/mail.js +1013 -0
  63. package/src/sources/matrix.d.ts +4 -0
  64. package/src/sources/matrix.js +232 -0
  65. package/src/sources/modbus.d.ts +15 -0
  66. package/src/sources/modbus.js +240 -0
  67. package/src/sources/onvif.d.ts +35 -0
  68. package/src/sources/onvif.js +326 -0
  69. package/src/sources/presence.d.ts +80 -0
  70. package/src/sources/presence.js +480 -0
  71. package/src/sources/serial.d.ts +21 -0
  72. package/src/sources/serial.js +220 -0
  73. package/src/sources/slack.d.ts +16 -0
  74. package/src/sources/slack.js +1062 -0
  75. package/src/sources/smtp.d.ts +4 -0
  76. package/src/sources/smtp.js +360 -0
  77. package/src/sources/stream.d.ts +68 -0
  78. package/src/sources/stream.js +534 -0
  79. package/src/sources/syslog.d.ts +32 -0
  80. package/src/sources/syslog.js +243 -0
  81. package/src/sources/system.d.ts +14 -0
  82. package/src/sources/system.js +236 -0
  83. package/src/sources/system.swift +102 -0
  84. package/src/sources/telegram.js +34 -1
  85. package/src/sources.d.ts +41 -1
  86. package/src/sources.js +147 -24
  87. package/src/tools.d.ts +1 -1
  88. package/src/tools.js +304 -23
  89. package/src/tui/app.d.ts +35 -2
  90. package/src/tui/app.js +306 -43
  91. package/src/tui/levels.d.ts +68 -0
  92. package/src/tui/levels.js +273 -0
  93. package/src/tui/picture.d.ts +17 -1
  94. package/src/tui/picture.js +72 -5
  95. package/src/types.d.ts +3 -0
  96. package/src/update.d.ts +9 -1
  97. package/src/update.js +75 -3
  98. package/src/watching.d.ts +156 -0
  99. package/src/watching.js +609 -4
@@ -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 one file about you they are read into its prompt with every conversation:
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 put into `MEMORY.md` what it learns that matters later, at
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 two as stubs. A file that is missing is simply not
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 `USER.md` in their prompt but cannot open or change the file; they tell you
62
- when something belongs there. A conversation that has read outside content writes these files
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. `agents/<id>/AGENTS.md`, if you keep one: rules the agent cannot change.
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 `USER.md` from pine's home, then `MEMORY.md`. See "The files an agent keeps itself".
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, and the judge's call pushes the agent's
265
- conversation out of a model server's cache unless the judge has a model of its own
266
- (`defaults.judge`). Say in the objective how to tell that it is reached ("the tests pass",
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 same agent at once
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
- A sub-agent works under the permissions of the conversation that started it: access you granted
310
- there and your "always" answers apply to it, and what it is granted applies to the conversation.
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 × + ▤ code
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
- USER.md what all agents know about you; in every agent's prompt, kept by the main agent
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
- MEMORY.md what should outlive a talk ┘ (agents.md)
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
@@ -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: `![short caption](path)`, 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`, `pw-play`, `paplay` or `aplay` do as well. macOS plays
13
- sound with what it has); on Linux `xclip`, or on Wayland `wl-copy` and `wl-paste`, for copying a selection and
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.
@@ -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 all agents
338
- should know about you goes into `USER.md` in pine's home, which the main agent keeps.
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 three names in the agent's workspace, read into its prompt and written by the agent |
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
- | `IDENTITY.md`, `TOOLS.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 |
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.