@pmndre/pine 0.0.0-stage → 0.22.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 (151) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -2
  3. package/bin/pine.js +27 -0
  4. package/docs/SKILL.md +234 -0
  5. package/docs/references/agents.md +454 -0
  6. package/docs/references/coding.md +311 -0
  7. package/docs/references/computer.md +212 -0
  8. package/docs/references/configuration.md +310 -0
  9. package/docs/references/events.md +267 -0
  10. package/docs/references/mcp.md +420 -0
  11. package/docs/references/operations.md +394 -0
  12. package/docs/references/overview.md +195 -0
  13. package/docs/references/security.md +896 -0
  14. package/docs/references/setup.md +385 -0
  15. package/docs/references/sources.md +772 -0
  16. package/docs/references/stack.md +121 -0
  17. package/docs/references/tui.md +575 -0
  18. package/examples/home/.env.example +7 -0
  19. package/examples/home/USER.md +4 -0
  20. package/examples/home/agents/main/agent.json +4 -0
  21. package/examples/home/agents/main/workspace/AGENTS.md +14 -0
  22. package/examples/home/agents/main/workspace/MEMORY.md +4 -0
  23. package/examples/home/agents/main/workspace/SOUL.md +4 -0
  24. package/examples/home/models.json +62 -0
  25. package/examples/home/pine.json +34 -0
  26. package/examples/home/skills/README.txt +7 -0
  27. package/examples/launchd/com.pine.daemon.plist +32 -0
  28. package/examples/systemd/pine.service +22 -0
  29. package/mcp/browser.d.ts +99 -0
  30. package/mcp/browser.js +496 -0
  31. package/mcp/commands.d.ts +20 -0
  32. package/mcp/commands.js +88 -0
  33. package/mcp/computer.d.ts +139 -0
  34. package/mcp/computer.js +698 -0
  35. package/mcp/computer.swift +989 -0
  36. package/mcp/lib.d.ts +23 -0
  37. package/mcp/lib.js +52 -0
  38. package/mcp/web.d.ts +6 -0
  39. package/mcp/web.js +140 -0
  40. package/package.json +32 -4
  41. package/src/access.d.ts +112 -0
  42. package/src/access.js +438 -0
  43. package/src/actions.d.ts +75 -0
  44. package/src/actions.js +167 -0
  45. package/src/admin.d.ts +167 -0
  46. package/src/admin.js +625 -0
  47. package/src/agent-admin.d.ts +24 -0
  48. package/src/agent-admin.js +55 -0
  49. package/src/agents.d.ts +540 -0
  50. package/src/agents.js +2776 -0
  51. package/src/background.d.ts +29 -0
  52. package/src/background.js +100 -0
  53. package/src/cli.d.ts +2 -0
  54. package/src/cli.js +777 -0
  55. package/src/computer.d.ts +30 -0
  56. package/src/computer.js +32 -0
  57. package/src/config.d.ts +396 -0
  58. package/src/config.js +549 -0
  59. package/src/dev/claude-model.d.ts +37 -0
  60. package/src/dev/claude-model.js +204 -0
  61. package/src/env-file.d.ts +4 -0
  62. package/src/env-file.js +40 -0
  63. package/src/goals.d.ts +133 -0
  64. package/src/goals.js +316 -0
  65. package/src/http.d.ts +46 -0
  66. package/src/http.js +509 -0
  67. package/src/limiter.d.ts +32 -0
  68. package/src/limiter.js +84 -0
  69. package/src/login.d.ts +23 -0
  70. package/src/login.js +130 -0
  71. package/src/manual.d.ts +61 -0
  72. package/src/manual.js +443 -0
  73. package/src/mcp-config.d.ts +49 -0
  74. package/src/mcp-config.js +182 -0
  75. package/src/models.d.ts +90 -0
  76. package/src/models.js +274 -0
  77. package/src/net.d.ts +50 -0
  78. package/src/net.js +150 -0
  79. package/src/pine.d.ts +32 -0
  80. package/src/pine.js +134 -0
  81. package/src/programs.d.ts +123 -0
  82. package/src/programs.js +412 -0
  83. package/src/router.d.ts +56 -0
  84. package/src/router.js +164 -0
  85. package/src/sandbox-fs.d.ts +34 -0
  86. package/src/sandbox-fs.js +186 -0
  87. package/src/sandbox-linux.d.ts +96 -0
  88. package/src/sandbox-linux.js +297 -0
  89. package/src/sandbox-setup.d.ts +70 -0
  90. package/src/sandbox-setup.js +216 -0
  91. package/src/security.d.ts +238 -0
  92. package/src/security.js +660 -0
  93. package/src/skills.d.ts +67 -0
  94. package/src/skills.js +163 -0
  95. package/src/snapshots.d.ts +68 -0
  96. package/src/snapshots.js +306 -0
  97. package/src/source-types.d.ts +61 -0
  98. package/src/source-types.js +1 -0
  99. package/src/sources/command.d.ts +4 -0
  100. package/src/sources/command.js +77 -0
  101. package/src/sources/folder.d.ts +6 -0
  102. package/src/sources/folder.js +116 -0
  103. package/src/sources/ftp.d.ts +4 -0
  104. package/src/sources/ftp.js +307 -0
  105. package/src/sources/http.d.ts +4 -0
  106. package/src/sources/http.js +201 -0
  107. package/src/sources/mqtt.d.ts +18 -0
  108. package/src/sources/mqtt.js +97 -0
  109. package/src/sources/telegram.d.ts +22 -0
  110. package/src/sources/telegram.js +283 -0
  111. package/src/sources/webhook.d.ts +4 -0
  112. package/src/sources/webhook.js +52 -0
  113. package/src/sources.d.ts +344 -0
  114. package/src/sources.js +966 -0
  115. package/src/store.d.ts +99 -0
  116. package/src/store.js +277 -0
  117. package/src/timers.d.ts +83 -0
  118. package/src/timers.js +318 -0
  119. package/src/tools.d.ts +11 -0
  120. package/src/tools.js +1297 -0
  121. package/src/tui/app.d.ts +305 -0
  122. package/src/tui/app.js +3195 -0
  123. package/src/tui/client.d.ts +236 -0
  124. package/src/tui/client.js +131 -0
  125. package/src/tui/code-pane.d.ts +68 -0
  126. package/src/tui/code-pane.js +535 -0
  127. package/src/tui/highlight.d.ts +8 -0
  128. package/src/tui/highlight.js +86 -0
  129. package/src/tui/picture.d.ts +206 -0
  130. package/src/tui/picture.js +801 -0
  131. package/src/tui/run.d.ts +8 -0
  132. package/src/tui/run.js +97 -0
  133. package/src/tui/theme.d.ts +32 -0
  134. package/src/tui/theme.js +128 -0
  135. package/src/tui/undo.d.ts +5 -0
  136. package/src/tui/undo.js +50 -0
  137. package/src/tui/voice.d.ts +49 -0
  138. package/src/tui/voice.js +155 -0
  139. package/src/tui/voice.swift +223 -0
  140. package/src/types.d.ts +139 -0
  141. package/src/types.js +1 -0
  142. package/src/undo.d.ts +224 -0
  143. package/src/undo.js +465 -0
  144. package/src/update.d.ts +35 -0
  145. package/src/update.js +130 -0
  146. package/src/util.d.ts +65 -0
  147. package/src/util.js +171 -0
  148. package/src/watching.d.ts +20 -0
  149. package/src/watching.js +68 -0
  150. package/src/workspace-view.d.ts +72 -0
  151. package/src/workspace-view.js +221 -0
@@ -0,0 +1,454 @@
1
+ # Agents
2
+
3
+ An agent is a folder under `agents/` in pine's home. The folder name is its id (lowercase
4
+ letters, digits, `-`, `_`, starting with a letter or digit; `create_agent` wants a letter first
5
+ and 2 to 31 characters).
6
+
7
+ ```
8
+ agents/gonzo/
9
+ agent.json settings (see configuration.md); {} is enough
10
+ workspace/ where it works, and the files it keeps itself:
11
+ AGENTS.md its purpose and how it works
12
+ SOUL.md who it is: character and tone
13
+ MEMORY.md what should outlive a conversation
14
+ skills/ its own skills, one folder each; the agent adds them with add_skill
15
+ conversations/ what was set up for one conversation alone (its skills); made when needed
16
+ extensions/ optional: its own pi extensions
17
+ AGENTS.md optional: rules of yours that the agent cannot change
18
+ ```
19
+
20
+ ## Creating an agent
21
+
22
+ Ask the main agent ("create an agent that keeps my books"): it calls `create_agent`, you confirm
23
+ 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
+ without a restart. Only the main agent has this tool; the
26
+ others tell you to ask it. See [setup.md](setup.md).
27
+
28
+ By hand: make the folder with an `agent.json` (`{}` is enough) and a `workspace/AGENTS.md`,
29
+ run `pine check`, and restart.
30
+
31
+ To change an agent later (its model, its tools, its reach, a folder it may use, its
32
+ instructions) or to remove it, ask the main agent as well: `update_agent` and `remove_agent`,
33
+ described in [setup.md](setup.md) under "Changing and removing an agent". Nobody has to edit
34
+ `agent.json` or delete a folder by hand.
35
+
36
+ ## The files an agent keeps itself
37
+
38
+ 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
+
41
+ | File | Holds | Who writes it |
42
+ |---|---|---|
43
+ | `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
+ | `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`) |
45
+ | `workspace/MEMORY.md` | What matters beyond a conversation: decisions, facts, preferences, open ends | The agent |
46
+ | `USER.md` in pine's home | What every agent knows about you. One file for all agents | The main agent, and you |
47
+ | `agents/<id>/AGENTS.md` | Optional. Rules of yours that the agent reads and cannot change | You |
48
+
49
+ 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
51
+ once and briefly, and to tidy its memory when it has grown long (merge, drop what no longer
52
+ holds, move details into other files and leave a pointer). When `MEMORY.md` passes about 6 000
53
+ characters, pine reminds the agent, because all of it is read with every message.
54
+
55
+ `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
57
+ loaded, and the agent creates it when it has something to put there. A change applies from the
58
+ agent's next message on. Only these names (and a `CLAUDE.md`), at the top of the workspace, are
59
+ read; anything else the agent keeps there is its own notes, which it reads when it needs them.
60
+
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)).
64
+
65
+ An existing home from before this layout keeps working: `agents/<id>/AGENTS.md` is still read.
66
+ To hand the instructions over to the agent, move that file to `agents/<id>/workspace/AGENTS.md`;
67
+ `pine init` adds the stubs that are missing and leaves your file where it is.
68
+
69
+ ## What an agent sees
70
+
71
+ Its system prompt is put together from, in this order:
72
+
73
+ 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
75
+ never by writing its files (which of them it has, and that creating agents and anything for
76
+ all agents is the main agent's job), that what it has been given it asks a tool and never
77
+ looks for in files (`sources`, `mcp_servers`, `skills`, `schedules`), that for everything
78
+ else it should explain the steps to its owner, and that text from tools, files and the web
79
+ 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.
81
+ 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".
83
+ After them the instruction files of a folder opened for the conversation, and any files in
84
+ `context`.
85
+ 4. Its skills: one line each; the agent reads a skill's file when it needs it. This manual is
86
+ not among them: the agent searches it with its `manual` tool (see below). An agent asked
87
+ for another model or a route looks it up and tells you what to put into which file; an
88
+ event source, a schedule, an MCP server or a skill it sets up itself by tool call
89
+ ([setup.md](setup.md)).
90
+ 5. A `<pine>` block: who the agent is, which agents it can delegate to, which MCP servers it
91
+ has. It only changes when the configuration does.
92
+
93
+ To show you a picture, an agent writes `![caption](path)` in its answer, with a file from its
94
+ workspace. The terminal UI draws it (see [tui.md](tui.md)); pine's base prompt tells every agent
95
+ this. A picture from the web it downloads first and then shows the file. A video file is shown
96
+ the same way and can be played in the conversation, and so is a sound file (`![caption](hello.wav)`;
97
+ wav, mp3, m4a, ogg or flac): the terminal UI plays it, see [tui.md](tui.md). The agent is told
98
+ not to play a sound with a command of its own (`afplay`), which you could neither pause nor see. A picture that a tool returned (a
99
+ screenshot, an image an MCP server made) is drawn where the tool ran, and the agent is told not
100
+ to show it a second time.
101
+
102
+ Nothing in the system prompt changes from one turn to the next. That is deliberate: a model
103
+ server keeps what it has already read (the prompt cache) only as long as the beginning of the
104
+ prompt is identical, and on a local model a miss means reading the whole conversation again
105
+ before the first word of the answer. What does change, pine puts in front of your message
106
+ instead, in a `<pine-note>`: the local time and date, the mode, the model the agent runs on
107
+ (as `provider/id` with its name from `models.json`, so that an agent asked which model it is
108
+ says that one and does not guess), the folder opened for the
109
+ conversation, whether its shell has network access, the programs its commands left running,
110
+ the steps of its `todo` list that are still open, that its browser is a window on your screen
111
+ which you use too, a reminder when `MEMORY.md` has grown
112
+ long, the shared state listed in `state.inject`, and whether the session has to be careful
113
+ with outside content. The note is only added when something other than the time of day has
114
+ changed since the last one. Text that arrives from elsewhere cannot fake a note; the tag is
115
+ rewritten on the way in.
116
+
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
+ The details of how pine works are not in the prompt; they are in this manual, which the agent
121
+ searches when a question calls for it. That keeps the prompt short for small models.
122
+
123
+ ### The manual tool
124
+
125
+ Every agent has a `manual` tool (not in a run that an outside event started). It holds the
126
+ whole of this manual, cut into small parts: one
127
+ for each heading, and one for each row of a table that describes a named thing (a
128
+ configuration key, a tool, a command, an option).
129
+
130
+ | Call | Answers with |
131
+ |---|---|
132
+ | `manual` `search: "<a few words>"` | The parts that fit best, each with its id and the sentence that matched. Several queries can be given at once, one thing each. |
133
+ | `manual` `read: "<id of a part>"` | That part in full; several ids at once. A long part comes in pages (the id with `@2`, `@3`). |
134
+ | `manual` with neither | The list of the manual's parts. |
135
+
136
+ A search is by words, not by exact wording. Words an agent or you would use and the manual
137
+ does not ("cron job", "reminder", "permission", "watcher") find the manual's own words through
138
+ a list of synonyms. A source type that was registered in this installation is found as well,
139
+ with its options. When nothing matches, the answer says so and suggests other words; it never
140
+ says that pine cannot do something.
141
+
142
+ `pine manual <words>` is the same search in a shell (without the source types registered in
143
+ an installation), and `pine manual --read <id>` reads a part: a quick way to see what an agent
144
+ would find. One call takes up to 6 queries and reads up to 8 parts.
145
+
146
+ Nothing from your own home folder leaks in: pi would normally also pick up `~/.agents/skills`
147
+ and instruction files in the folders above the workspace; pine filters those out. Edits to the
148
+ instruction files take effect on the agent's next task.
149
+
150
+ ## Workspaces
151
+
152
+ Point `workspace` at the folder the agent should work in, typically an existing repository:
153
+
154
+ ```json
155
+ { "description": "The house: contracts, utilities, solar", "workspace": "~/dev/house" }
156
+ ```
157
+
158
+ The agent's shell and file tools can read and write there and nowhere else in your home. Each
159
+ agent also has a private home folder (`sandbox/<id>/`), which is what `~` means inside its
160
+ shell. Agents cannot read each other's workspaces; they talk through `delegate`.
161
+
162
+ Two agents may share a workspace if you give them the same path. They can then overwrite each
163
+ other's files.
164
+
165
+ A single conversation can work somewhere else without any of this: `pine <folder>`, or the
166
+ folder in the bottom bar of the terminal UI, opens a folder of yours for that one conversation.
167
+ Its tools then start there and may change what is in it, and the folder's `AGENTS.md` (or
168
+ `CLAUDE.md`) applies next to the agent's own. See [coding.md](coding.md).
169
+
170
+ ## Sessions
171
+
172
+ A session is one conversation with history.
173
+
174
+ | You pass | What happens |
175
+ |---|---|
176
+ | nothing | The agent's `main` session: one long conversation, compacted by pi when it fills up |
177
+ | a name, for example `tg-123456` or `case-okapi` | A separate named conversation |
178
+ | `new` | A fresh conversation for that one task; it is not continued |
179
+
180
+ Routes pick the session with `"session"`, the CLI with `--session`. What you write on Telegram
181
+ arrives in the conversation that subscribed to the Telegram source. Runs started by untrusted
182
+ events use a twin of the session with `~u` appended,
183
+ so they never see or extend your own conversation.
184
+
185
+ Tasks for one session queue up. With `"whenBusy": "steer"` on a route, a new message is instead
186
+ shown to the agent in the middle of what it is doing: it reads it at its next step. The terminal
187
+ UI sends your own messages this way (`alt+enter` makes one wait its turn). A steered message
188
+ that the work did not get to read, because it ended or was stopped first, is answered next as
189
+ work of its own.
190
+
191
+ `pine reset <agent> [session]` (or `/reset` in the terminal UI) starts a session
192
+ over. The old history is kept on disk next to it with a `.reset-<time>` suffix for
193
+ `limits.eventRetentionDays`. What the conversation was subscribed to on its own ends with the
194
+ reset.
195
+
196
+ A named conversation does not stay for ever. One that is not an agent's `main`, not pinned, not
197
+ open in a tab of the terminal UI, not subscribed to an event source and without a schedule of
198
+ its own is removed with its history after `limits.conversationDays` (7) without a message. That holds for every named
199
+ conversation: one you opened in the terminal UI, a delegation thread's, one a route names. Pin the ones to keep (`/pin`, or the list of
200
+ conversations in the terminal UI; see [tui.md](tui.md)), or set `limits.conversationDays` to
201
+ `0` to keep them all. Everything that was set up for one conversation alone goes with it: its
202
+ event sources and subscriptions, schedules, MCP servers and skills ([setup.md](setup.md)).
203
+
204
+ ## Goal mode
205
+
206
+ Normally an agent ends its turn and waits for your next message, also when the work is not
207
+ finished: "the first part is done, shall I go on?". With a goal it keeps working by itself.
208
+ You say once what should be reached, and pine calls the agent again each time it ends a turn,
209
+ until the objective is met:
210
+
211
+ ```
212
+ /goal all tests in ~/dev/shop pass and the README says how to run them
213
+ ```
214
+
215
+ That is typed in the terminal UI, in the conversation that should do the work. The objective
216
+ is sent as your message, and from then on:
217
+
218
+ 1. The agent works and ends its turn, as always. That is one **round**.
219
+ 2. pine asks a **judge** one question: is the objective met? The judge is a short model call
220
+ without tools. It is shown your objective and the agent's last answer, and replies with one
221
+ word and one line of reason.
222
+ 3. `CONTINUE`: the agent is called again in the same conversation, with your objective and the
223
+ note that it is not met yet. `MET`: the goal is done. `BLOCKED`: the agent needs something
224
+ only you can give (a decision, a sign-in, an approval that was refused), and the goal stops
225
+ until you have answered and typed `/goal resume`.
226
+
227
+ The conversation shows a line for each verdict with the judge's reason, and the status line
228
+ shows the round the goal is in.
229
+
230
+ | Command | What it does |
231
+ |---|---|
232
+ | `/goal <objective>` | Sets the goal of this conversation and starts on it. A goal that was there is replaced. At most 2000 characters: put details into a file and name the file. |
233
+ | `/goal` | Shows the goal and where it stands: the round, the last verdict and its reason. |
234
+ | `/goal pause` | No further rounds. A round that is running ends by itself; `esc` stops it at once. |
235
+ | `/goal resume` | Goes on with a goal that stopped: paused, blocked, at its limit, or called met too early. |
236
+ | `/goal clear` | Takes the goal off the conversation. |
237
+
238
+ A goal stops by itself, and says why, in these cases:
239
+
240
+ | What happened | What the goal does |
241
+ |---|---|
242
+ | The judge says "met" | It is done. `/goal resume` if you do not agree. |
243
+ | The judge says "blocked" | It stops. Answer what the agent asked, then `/goal resume`. |
244
+ | The judge gave no verdict (it did not answer in time, or not with one of the three words) | It is paused. No verdict never counts as "go on". |
245
+ | It has had its rounds | It stops after `limits.goalRounds` rounds (20). `/goal resume` gives it as many again. |
246
+ | Several rounds in a row ended "not met" without a single tool call | It is paused after `limits.goalIdleRounds` such rounds (3): the agent is going in circles. |
247
+ | You wrote a message of your own in the conversation, typed or through Telegram | It is paused, so that your message is not overruled by the next round. |
248
+ | You stopped the agent (esc, `/stop`), or a round failed | It is paused. |
249
+ | pine was stopped or restarted | It is paused. The goal itself is kept; nothing goes on unseen after a restart. |
250
+ | The conversation was reset or removed | The goal is gone with it. |
251
+
252
+ A goal belongs to one conversation and is kept in pine's store, so it is still there after a
253
+ restart. Only you set one: there is no tool for it, so an agent cannot give itself a goal, more
254
+ rounds, or a different objective. If your owner asks you, as an agent, to "keep going until it
255
+ is done", tell them to type `/goal` with what they want reached. Other programs use
256
+ `POST /agents/<id>/goal` of the control API ([operations.md](operations.md)).
257
+
258
+ The judge uses the model in `defaults.judge` if one is set, else the agent's own, and the
259
+ time limit `limits.goalJudgeTimeout`. It only decides
260
+ whether the agent is called again. What the agent may do in a round is decided as in any other
261
+ task, by its mode and the approvals ([security.md](security.md), "A goal goes on
262
+ in your name").
263
+
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",
267
+ "the file exists and has all twelve entries"): the judge sees only the agent's answer, not the
268
+ files.
269
+
270
+ ## Handing work to another agent
271
+
272
+ The `delegate` tool exists for an agent when its `delegates` list is not empty. The main agent
273
+ (`"main"` in `pine.json`) may delegate to everyone by default.
274
+
275
+ ```json
276
+ { "delegates": ["gonzo", "scout"] }
277
+ ```
278
+
279
+ What the model sees:
280
+
281
+ ```
282
+ delegate(agent, task, wait?, thread?)
283
+ ```
284
+
285
+ - The other agent gets only the task text, prefixed with who sent it. It runs in its own
286
+ workspace with its own tools and instructions.
287
+ - By default the caller waits and gets the answer as the tool's result.
288
+ - `wait: false` returns at once; the answer arrives later as a new message in the caller's
289
+ session.
290
+ - Each delegation starts the other agent fresh. `thread: "okapi"` instead continues a named
291
+ conversation with it, so it remembers earlier tasks of that thread.
292
+ - An agent already waiting further up the chain cannot be called again, and chains stop at
293
+ `limits.maxDelegationDepth`. The model gets an error it can act on.
294
+
295
+ Write `description` for the delegating model: it is the only thing it knows about the other
296
+ agent. "Contract law; knows the case files in its workspace" works;
297
+ "Gonzo" does not.
298
+
299
+ ## Sub-agents
300
+
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).
303
+ Each copy has the agent's workspace, instructions and tools but an empty conversation, cannot
304
+ delegate or spawn further, and returns only its final answer. Use it for searches and checks
305
+ that would otherwise fill the context:
306
+
307
+ > Find every clause about notice periods in `contracts/`. Use sub-agents, one per file.
308
+
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.
311
+ It has the agent's MCP servers (unless `subagents.mcp` is `false`) and all its tools, or the
312
+ ones listed in `subagents.tools`.
313
+
314
+ Sub-agents count against the model slots. With fewer slots than sub-agents they queue; nothing
315
+ deadlocks, because the waiting parent lends out its own slot.
316
+
317
+ A sub-agent is a task like any other, with its own number and its own session, and its work can
318
+ be looked at while it runs and afterwards:
319
+
320
+ - In the terminal UI, the conversation shows a line when one starts and when it answers. A click
321
+ on either opens a tab with what it was given, what it thought and wrote, and every tool call
322
+ with the start of its result. `/task <id>` opens the same tab; the agent list (click the agent
323
+ name in the bottom bar) lists the ones this conversation started.
324
+ - `pine tasks` lists them, `pine task <id>` shows the task and its result, and
325
+ `GET /tasks/<id>/transcript` on the control API returns the steps.
326
+ - The session file itself stays in `agents/<id>/sessions/_tasks/<task id>/`.
327
+
328
+ The same works for a task that was delegated to another agent.
329
+
330
+ ## Shared state
331
+
332
+ Small facts that several agents and routes need: who is home, the mode of the house, the state
333
+ of the printer.
334
+
335
+ - Routes write it: `"set": { "house/mode": "{{payload.value}}" }`.
336
+ - Agents read it with `state_get` and write it with `state_set`, within `state.read` and
337
+ `state.write`.
338
+ - `state.inject` shows keys to an agent in every turn, always current, without growing the
339
+ conversation:
340
+
341
+ ```json
342
+ { "state": { "inject": ["house/#"], "write": ["house/#"] } }
343
+ ```
344
+
345
+ State values are shown to agents as facts, not as instructions, and are cut to 200 characters.
346
+ Do not route untrusted text into a key that agents see.
347
+
348
+ ## What an agent's answer does
349
+
350
+ - The final text of a task is its result. If the task has a reply target, it is sent there.
351
+ - `NO_REPLY` (or `SILENT`) as the whole answer sends nothing.
352
+ - A failed task (model error, timeout) sends "`<agent>` could not finish: ..." to the reply
353
+ target, so you are not left waiting. A cancelled task sends nothing.
354
+
355
+ ## pi extensions
356
+
357
+ Any pi extension works in pine sessions. One that adds a line to every system prompt:
358
+
359
+ ```ts
360
+ // ~/.pine/agents/gonzo/extensions/citations.ts
361
+ export default function (pi) {
362
+ pi.on("before_agent_start", async (event) => ({ systemPrompt: `${event.systemPrompt}\n\nCite the paragraph for every legal claim.` }));
363
+ }
364
+ ```
365
+
366
+ Files in `agents/<id>/extensions/` are found automatically; list others under `extensions`.
367
+ pi's extension guide is in `node_modules/@earendil-works/pi-coding-agent/docs/extensions.md`.
368
+ Things that need a terminal UI (dialogs, widgets) have no effect in the daemon.
369
+
370
+ `.pi/extensions/` in a workspace is deliberately not loaded; see `trustWorkspace` in
371
+ [configuration.md](configuration.md).
372
+
373
+ ## Skills
374
+
375
+ A skill is a folder with a `SKILL.md` that starts with a name and a description:
376
+
377
+ ```markdown
378
+ ---
379
+ name: inverter
380
+ description: Read and interpret the inverter's daily export. Use for questions about solar yield.
381
+ ---
382
+
383
+ 1. The exports are in `data/inverter/YYYY-MM.csv` ...
384
+ ```
385
+
386
+ The agent sees the description in its system prompt and reads the file when the task calls for
387
+ it. Files the instructions refer to (a script, a template) lie beside the `SKILL.md`.
388
+
389
+ ### Ask the agent
390
+
391
+ > Remember how to do this: make a skill for filing invoices.
392
+
393
+ That is how something gets written down as a skill: the agent calls `add_skill` with a name,
394
+ the description and the instructions, and optionally a folder of its workspace whose files go
395
+ along. pine writes the skill; the agent has it from its
396
+ next message on. Asking again under the same name replaces it, and `remove_skill` deletes it.
397
+
398
+ Like an event source or an MCP server, a skill is for the conversation it was asked for in,
399
+ for the agent, or for all agents ([setup.md](setup.md)):
400
+
401
+ | Said | Who gets it | You are asked |
402
+ |---|---|---|
403
+ | "make a skill for this" in a side conversation | That conversation; it goes when the conversation is removed | No |
404
+ | the same in the agent's main conversation, or "for you as an agent" | Every conversation of that agent | Only from a side conversation |
405
+ | "for all agents" | Every agent. Only the main agent can do this | Yes |
406
+
407
+ A name is used once among everything that would stand beside the skill, so no conversation
408
+ ever has two skills of one name.
409
+
410
+ A skill is part of what an agent is told, like its `AGENTS.md`. It is therefore written by
411
+ pine, in pine's home where the agent reads but does not write. From a conversation that has
412
+ read outside content it is not written unseen: it is put to you first, with its
413
+ instructions. What is a fact and not a way of
414
+ doing something belongs into the agent's `MEMORY.md`.
415
+
416
+ ### Put it there yourself
417
+
418
+ A folder with a `SKILL.md` in one of these places is a skill, with no entry anywhere:
419
+
420
+ | Folder | For |
421
+ |---|---|
422
+ | `~/.pine/skills/<name>/` | all agents |
423
+ | `~/.pine/agents/<id>/skills/<name>/` | that agent |
424
+
425
+ What lies in these two folders an agent can also replace (`add_skill` under the same name) and
426
+ remove (`remove_skill`), whoever put it there.
427
+
428
+ A skill that lies somewhere else is named under `skills` in `pine.json` (for all) or in an
429
+ `agent.json` (for that agent). Agents can use those and cannot replace or remove them.
430
+
431
+ A skill's name is lowercase letters, digits and single hyphens, at most 64 characters; `pine`
432
+ is taken. The description may have 1024 characters, the instructions 40 000. Files that go
433
+ along: at most 200 and 4 MB together, real files only (a link is refused).
434
+
435
+ `pine skills` lists every skill, whom it is for and where it lies. An agent lists its own with
436
+ its `skills` tool: the skills the conversation has, whom each is for, and those that only
437
+ another conversation of the same agent has ([setup.md](setup.md), "What an agent has").
438
+
439
+ ## Checking on agents
440
+
441
+ ```bash
442
+ pine status
443
+ ```
444
+
445
+ ```bash
446
+ pine tasks --agent gonzo
447
+ ```
448
+
449
+ ```bash
450
+ pine events --topic "agent/#" -f
451
+ ```
452
+
453
+ `pine task <id>` shows one task in full: prompt, result, error, trust, and statistics (turns,
454
+ tokens, which tools it called, how long it took).