@pmndre/pine 0.0.0-stage → 0.22.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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,394 @@
1
+ # Running pine
2
+
3
+ ## Requirements
4
+
5
+ - macOS or Linux. The agent sandbox is built on the system's own: `sandbox-exec` on macOS,
6
+ [bubblewrap](https://github.com/containers/bubblewrap) on Linux, which `pine init` installs
7
+ and sets up. Agents in `safe` and `manual` mode work in it; an agent in `auto` mode (the
8
+ main agent, as pine comes) needs none. Without a sandbox pine starts and works: agents
9
+ whose mode you did not choose work in `auto`, one you set to `safe` has no shell, and `pine check`
10
+ says why. See [security.md](security.md), "On Linux".
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
14
+ pasting a picture.
15
+ - Node 24 or newer. From a checkout Node runs the TypeScript sources directly; the npm package
16
+ holds them compiled.
17
+ - A model that supports tool calls: a hosted provider pi knows (sign in with `pine login`), or
18
+ your own model server with an OpenAI-compatible chat completions endpoint (add it with
19
+ `pine model add`).
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ npm install -g @pmndre/pine
25
+ ```
26
+
27
+ That puts the `pine` command on your PATH. The package holds pine compiled to JavaScript,
28
+ because Node does not run TypeScript from inside `node_modules`.
29
+
30
+ To work on pine itself, use a checkout instead. `bin/pine` runs the sources as they are and
31
+ installs the dependencies the first time; `npm link` puts that copy on your PATH:
32
+
33
+ ```bash
34
+ git clone https://github.com/pmndrs/pine ~/dev/pine
35
+ ```
36
+
37
+ ```bash
38
+ ~/dev/pine/bin/pine init
39
+ ```
40
+
41
+ ## First start
42
+
43
+ ```bash
44
+ pine init
45
+ ```
46
+
47
+ sets everything up in one step:
48
+
49
+ - From a fresh checkout, `bin/pine` first installs pine's dependencies (`npm install`), once.
50
+ - It copies the example home to `~/.pine`: one agent, `main`, with web search, the browser and,
51
+ on a Mac, app control ([computer.md](computer.md)), a `models.json`, an empty `.env`. Nothing
52
+ is overwritten if you run it again.
53
+ - On Linux it makes the sandbox work. If bubblewrap is missing it installs the package (apt,
54
+ dnf, yum, pacman, zypper or apk), and on Ubuntu 24.04 and later it writes and loads the
55
+ AppArmor rule bubblewrap needs there. It shows the commands first and asks once; they run
56
+ with `sudo`, which asks for your password itself. `pine init --yes` does not ask, for a
57
+ script or a container build. Where pine cannot do it (no `sudo`, a container without the
58
+ rights), it says what would; pine runs either way: until then agents whose mode you did
59
+ not choose work in `auto` mode, without a sandbox, and one you set to `safe` has no shell.
60
+ The same question covers the system libraries the browser needs, which a server or a
61
+ container image lacks (installed with apt, through Playwright).
62
+ - It downloads the Chromium build the bundled browser tools drive (about 600 MB, into
63
+ Playwright's cache). A second run finds it there and takes a moment. If the download fails,
64
+ everything else is set up and `pine init` can simply be run again.
65
+
66
+ ```bash
67
+ pine
68
+ ```
69
+
70
+ opens the terminal UI ([tui.md](tui.md)) and, since no daemon is running yet, starts one inside
71
+ it. That is the quickest way to try things. For a daemon that keeps running without a terminal:
72
+
73
+ ```bash
74
+ pine check
75
+ ```
76
+
77
+ ```bash
78
+ pine start
79
+ ```
80
+
81
+ and from another terminal `pine` (attaches to it) or
82
+ `pine send main "Say hello and list your tools."`.
83
+
84
+ ### Choosing a model
85
+
86
+ The example home uses `dev/claude-haiku`: an OpenAI-compatible endpoint whose answers come from
87
+ `claude -p`, so it needs Claude Code installed and signed in. The UI starts it on demand; for
88
+ `pine start`, run it yourself:
89
+
90
+ ```bash
91
+ pine dev-model
92
+ ```
93
+
94
+ Every model call starts a `claude` process: expect about five seconds per call and usage on
95
+ your Claude plan. It is for trying things out, not for a daemon that runs all day.
96
+
97
+ For a hosted provider, sign in once and pick a model:
98
+
99
+ ```bash
100
+ pine login opencode-go
101
+ ```
102
+
103
+ ```bash
104
+ pine login anthropic
105
+ ```
106
+
107
+ ```bash
108
+ pine login openai-codex
109
+ ```
110
+
111
+ The first asks for an API key (typed without echo); the other two open a browser sign-in for a
112
+ Claude or ChatGPT subscription. Credentials go to `~/.pine/auth.json` (mode 600). Then set
113
+ `defaults.model` in `pine.json`, for example `"opencode-go/deepseek-v4.1-flash"`, or switch in
114
+ the UI with `/model`. `pine login <unknown>` lists every provider pi knows.
115
+
116
+ ### With a model server of your own
117
+
118
+ llama.cpp, vLLM, LM Studio and anything else that speaks OpenAI's chat API is added by its
119
+ address, on this machine or another one:
120
+
121
+ ```bash
122
+ pine model add studio http://127.0.0.1:8080
123
+ ```
124
+
125
+ pine asks the server which models it has, how much context one request gets and whether it
126
+ reads pictures, and writes the entry into `models.json`. If the server wants a key (llama-server
127
+ started with `--api-key`), it asks you for it without showing it and keeps it in `.env`. A
128
+ running pine has the models at once; choose one with `/model studio/<model>`.
129
+
130
+ - `--context <tokens>` gives the context where the server does not say it (llama.cpp does).
131
+ - `--reasoning` or `--no-reasoning` overrides what the server says about a thinking model.
132
+ - For a thinking model on llama.cpp, pine also writes which thinking level is sent for each of
133
+ its own (`thinkingLevelMap`), from the levels the server says the model's chat template tells
134
+ apart. So "off" really turns thinking off, and a level the model does not know becomes the
135
+ next one up that it does know, not silently its default. See [configuration.md](configuration.md), "Thinking
136
+ levels".
137
+ - `pine model list` shows the servers with their models; `pine model remove <name>` takes one
138
+ out again, with its key, unless an agent still uses it.
139
+ - The main agent can do the same when you ask it to ([setup.md](setup.md), "Adding a model
140
+ server").
141
+
142
+ For llama.cpp, start the server with tool-call support:
143
+
144
+ ```bash
145
+ llama-server -m /path/to/model.gguf --jinja -c 65536 -np 2 --port 8080
146
+ ```
147
+
148
+ `-np` (parallel slots) should equal `limits.maxConcurrentRuns`. The context is shared between
149
+ slots, so each run gets `c / np` tokens; that is the number the server reports and pine writes
150
+ down. Add `--alias <name>` to give the model a plain name: without it the name is the path of
151
+ the model file.
152
+
153
+ ## In a container
154
+
155
+ A container needs nothing special:
156
+
157
+ ```bash
158
+ docker run -it -v pine:/root/.pine node:24 bash
159
+ ```
160
+
161
+ Inside, `npm install -g @pmndre/pine` and `pine init` as anywhere. `-v pine:/root/.pine`
162
+ keeps pine's home when the container is replaced. A container started like this cannot make
163
+ a sandbox, and need not: the container is the wall around pine, every agent whose mode you
164
+ did not choose works in `auto` mode inside it, and `pine check` says so. An agent you set to
165
+ `safe` has no shell there, and runs that events from outside start have none.
166
+
167
+ | In a container | Without the rights for a sandbox | With them |
168
+ |---|---|---|
169
+ | An agent whose mode you did not choose | Works in `auto` mode: no sandbox, the container's whole file system and network | The main agent in `auto`, the others in `safe`, as on any machine |
170
+ | An agent you set to `safe` | No shell; its file tools work | Works in its sandbox |
171
+ | A run that an event from outside started | No shell | Works in the sandbox |
172
+ | A `command` source | Is not run | Runs in the sandbox |
173
+
174
+ To have `safe` mode in a container, start it with the rights for a sandbox. They take away
175
+ most of what Docker itself protects:
176
+
177
+ ```bash
178
+ docker run -it --cap-add SYS_ADMIN --cap-add NET_ADMIN --security-opt seccomp=unconfined --security-opt apparmor=unconfined -v pine:/root/.pine node:24 bash
179
+ ```
180
+
181
+ `pine init` then installs bubblewrap and the browser's libraries, which the image does not
182
+ have, and names the flags if one is missing. What each flag is for, and the one more an
183
+ ordinary user in the container needs, is in [security.md](security.md), "On Linux".
184
+
185
+ ## Updating
186
+
187
+ ```bash
188
+ pine update
189
+ ```
190
+
191
+ brings pine itself up to date and fetches what the new version needs. What it does depends on
192
+ how pine got onto the machine, which `pine version` tells you:
193
+
194
+ | Installed | `pine update` |
195
+ |---|---|
196
+ | with `npm install -g` | Asks npm for the latest version. If there is one, installs it (`npm install -g @pmndre/pine@latest`). |
197
+ | as a checkout (`git clone`) | Fetches from the repository the checkout follows and moves it forward, then runs `npm install`. Only ever a fast-forward: if commits or changes of your own are in the way, nothing is changed and it says so. |
198
+ | as a dependency inside a project | Tells you the command to run in that project; that project decides its version. |
199
+
200
+ Afterwards it makes sure the browser the web tools drive matches the new version, which is a
201
+ download only when that version changed.
202
+
203
+ `pine update --check` changes nothing and says whether there is something newer.
204
+
205
+ A pine that is running keeps the old version until it is restarted: quit the terminal UI and
206
+ open it again, or restart the daemon (if it runs at login as a LaunchAgent:
207
+ `launchctl kickstart -k gui/$(id -u)/com.pine.daemon`).
208
+ Your home folder (`~/.pine`) is not touched by an update. When a new version adds something to
209
+ the example home, `pine init` copies the files you do not have yet and overwrites nothing.
210
+
211
+ ## Commands
212
+
213
+ What you type in a shell. Every command is the `pine` program with a word after it.
214
+
215
+ | Command | What it does |
216
+ |---|---|
217
+ | `pine`, `pine tui` | The terminal UI; starts a daemon inside if none is running |
218
+ | `pine .`, `pine <folder>` | The terminal UI with one more tab: a conversation of the main agent that works in that folder (the one from last time, if there is one). A first word that is a command stays a command. See [coding.md](coding.md) |
219
+ | `pine login <provider>`, `pine logout <provider>` | Sign in to a model provider. `--api-key` or `--oauth` force the kind of sign-in |
220
+ | `pine model add <name> <address>`, `pine model list`, `pine model remove <name>` | Add a model server of your own by its address, list them, take one out. `--context <tokens>`, `--reasoning`, `--no-reasoning` for what the server does not say. See "With a model server of your own" |
221
+ | `pine init [dir] [--yes]` | Set pine up: a home directory from the example, the browser its web tools drive and, on Linux, the sandbox (asks before running anything as administrator; `--yes` skips the question). Safe to run again |
222
+ | `pine update [--check]` | Bring pine up to date. `--check` only says whether there is something newer. See "Updating" |
223
+ | `pine version`, `pine --version` | Which version this is and how it is installed |
224
+ | `pine help`, `pine --help` | Prints the list of commands |
225
+ | `pine browser-install` | Fetch the browser again. `pine init` and `pine update` do this already |
226
+ | `pine check` | Validate the configuration; show each agent's workspace, model, tools, MCP servers; list security notes |
227
+ | `pine start` | Run the daemon in the foreground. Ctrl-C or SIGTERM stops it cleanly |
228
+ | `pine dev-model [--port 7464] [--model haiku]` | The `claude -p` model server |
229
+ | `pine status` | Running tasks, live sessions (and whether they are tainted), model slots |
230
+ | `pine agents` | Configured agents, as the daemon has them (JSON) |
231
+ | `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
+ | `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) |
234
+ | `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
+ | `pine send <agent> <text...>` | Give an agent a task as yourself and print the answer. `--session <key>`, `--no-wait` |
236
+ | `pine emit <topic> [json]` | Publish an event as yourself |
237
+ | `pine events` | The event log. `--topic <pattern>`, `--limit <n>` (30), `-f` to follow |
238
+ | `pine tasks` | Recent tasks. `--agent <id>`, `--status pending\|running\|done\|failed\|cancelled`, `--limit <n>` (20) |
239
+ | `pine task <id>` | One task in full |
240
+ | `pine cancel <id>` | Stop a task |
241
+ | `pine state [pattern]` | Shared state |
242
+ | `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 |
244
+ | `pine subscribe --global <source> [--note text] ...`, `pine unsubscribe --global <source>` | The same for every agent that can use the source |
245
+ | `pine approvals`, `pine approve <id> [--always]`, `pine deny <id>` | Answer approval requests; `--always` stops the question for the rest of that conversation |
246
+ | `pine reset <agent> [session]` | Start a conversation over; also clears its taint |
247
+ | `pine mode <agent> [auto\|safe\|manual\|bypass\|plan]` | Show or change an agent's mode. `auto`, `safe` and `manual` are saved in its `agent.json` and hold after a restart; `bypass` and `plan` hold until pine restarts. `auto` and `bypass` work without a sandbox, `safe` and `manual` in one. `plan`: the agent only looks and answers with a plan. See "Modes" in [security.md](security.md) |
248
+ | `pine mcp list` | MCP servers, who gets them (all agents, one agent, or one conversation of an agent), whether they connect. `--offline` lists without connecting |
249
+ | `pine skills` | Lists every skill: whom it is for (all agents, an agent, one conversation) and where it lies |
250
+ | `pine schedules` | Lists what is scheduled: for whom, when, and the task |
251
+ | `pine manual <words>`, `pine manual --read <id>` | Search this manual the way the agents do, or read one part of it in full (several ids with commas). Without words: the list of its parts |
252
+ | `pine mcp add <name> <url>`, `pine mcp add <name> -- <command...>` | Add a remote or a local server. `--agent <id>` for one agent; `--taints`, `--approve always\|tainted`, `--timeout <seconds>`, `--description <text>`, `--exposure <how>` as in [mcp.md](mcp.md) |
253
+ | `pine mcp remove <name> [--agent <id>]` | Remove a server from `pine.json`, or from that agent's `agent.json` |
254
+ | `pine mcp login <name>`, `pine mcp logout <name>` | Sign in to a remote server through the browser, or forget its tokens |
255
+
256
+ All take `--home <dir>`; the default is `$PINE_HOME` or `~/.pine`. The commands from `status`
257
+ down to `mode` talk to the running daemon over its control API on `127.0.0.1:7463`, using the
258
+ token in `data/http-token`. The `pine mcp` and `pine model` commands work on the files, and `add` and `remove`
259
+ also tell a running daemon, so the change applies at once. `pine schedules`, `pine skills`,
260
+ `pine check` and `pine manual` only read the files and need no daemon. `pine help` prints the
261
+ list.
262
+
263
+ ## Running at login
264
+
265
+ On macOS, [examples/launchd/com.pine.daemon.plist](../../examples/launchd/com.pine.daemon.plist)
266
+ is a LaunchAgent that starts pine at login and restarts it when it exits. Follow the three
267
+ steps at its top. Logs then go to `~/.pine/data/pine.log`.
268
+
269
+ On Linux, [examples/systemd/pine.service](../../examples/systemd/pine.service) is a systemd
270
+ user service that does the same. Follow the steps at its top. Logs go to the journal
271
+ (`journalctl --user -u pine`).
272
+
273
+ Both run as you, in your login session. To separate the agents from your files more
274
+ strongly, create a dedicated user, keep pine's home and the agents' workspaces there, and
275
+ install the service for that user.
276
+
277
+ ## The control API
278
+
279
+ For scripts and other programs. Every request needs `Authorization: Bearer <token>`; POST bodies
280
+ are JSON with `Content-Type: application/json`.
281
+
282
+ | Request | Purpose |
283
+ |---|---|
284
+ | `GET /health` | Liveness (no token) |
285
+ | `GET /status`, `/agents`, `/approvals` | As the CLI commands |
286
+ | `GET /models` | Models that have credentials, as `provider/id` |
287
+ | `GET /mcp` | Configured MCP servers |
288
+ | `POST /mcp` `{ name, server, agent? }` or `{ name, remove: true, agent? }` | Add or remove a server while the daemon runs |
289
+ | `POST /mcp/refresh` | Close idle sessions so they start again with the current servers |
290
+ | `POST /agents` `{ id, description, instructions, model?, tools? }`, `POST /agents/<id>/update` `{ description?, instructions?, model?, thinking?, mode?, tools?, delegates?, scope?, network?, read?, write?, forget? }`, `POST /agents/<id>/erase` `{ agent, keepFiles? }` | Create an agent, change its settings, or remove one with everything it has, while the daemon runs (`erase` repeats the id in `agent`: removing an agent is not done by a mistyped address). What `pine agent add`, `pine agent update` and `pine agent remove` call |
291
+ | `POST /models/refresh` | Read `models.json` and `.env` again, after a model server was added or removed in the files. `pine model add` and `pine model remove` call it |
292
+ | `GET /agents/<id>/sessions` | The agent's conversations: name, number of messages, last use, whether pinned or open in a tab, the folder opened for it, and when one will be removed by itself |
293
+ | `POST /agents/<id>/pin` `{ session, pinned? }` | Pin a conversation so that it is kept, or with `pinned: false` take the pin off |
294
+ | `POST /agents/<id>/rename` `{ session, to }` | Give a conversation another name; its history, pin, subscriptions and what was set up for it follow |
295
+ | `POST /agents/<id>/remove` `{ session }` | Remove a conversation for good, with its history and what was set up for it alone. Not the main one, and not while it is working |
296
+ | `GET /ui/tabs`, `POST /ui/tabs` `{ tabs, active, code?, notify? }` | The tabs the terminal UI has open (`tabs` is a list of `{ agent, session }`, 50 at most), whether its code pane was open (`code`) and whether it calls for attention with a bell (`notify`, set with `/notify`), kept so that it opens the same way next time. `code` and `notify` stay as they were when left out. A conversation that is open in a tab is not removed for being unused |
297
+ | `GET /agents/<id>/folder?session=`, `GET /agents/<id>/folders`, `POST /agents/<id>/folder` `{ session, folder }` | The folder a conversation works in; every conversation of the agent that has one; open a folder for a conversation (`folder: null` closes it). Refused for pine's home, pine's program and other agents' workspaces, and while the conversation is working |
298
+ | `GET /agents/<id>/goal?session=`, `POST /agents/<id>/goal` `{ session, objective }` or `{ session, action }` | Goal mode. `GET` returns `{ goal }` with the objective, `status` (`active`, `paused`, `met`, `blocked`, `limit`), the round, pine's note on what happened last and the judge's reason; no goal: `{}`. `objective` sets the conversation's goal and starts on it; `action` is `pause`, `resume` or `clear`. Every change is also an event on `agent/<id>/goal`. See "Goal mode" in [agents.md](agents.md) |
299
+ | `GET /agents/<id>/programs?session=`, `POST /agents/<id>/programs/stop` `{ session, id }` | What a conversation's commands left running (command, ports, how long), and stopping one of them. A command the agent started in the background is among them while it runs, with `background: true` and `output` (the file its output goes to). Only a program of that conversation can be stopped. |
300
+ | `GET /agents/<id>/view/changes?session=`, `/view/diff?session=&path=`, `/view/tree?session=&path=`, `/view/file?session=&path=`, `/view/find?session=&q=` | What the code pane shows of a conversation's folder (or of the agent's workspace): what git says changed, one file's diff, what is in a folder, a file's text, the files whose name fits a few letters. Read-only, and nothing outside that folder |
301
+ | `GET /agents/<id>/view/turn?session=`, `/view/turndiff?session=&path=` | What your last message in a conversation changed in its folder, which is what `/undo` would take back: `{ task, prompt, root, files, more, note? }` (at most 300 files; `note` says why there is nothing to show), and one file's diff over that message. While the message is still being worked on: what it has changed so far. See [coding.md](coding.md) |
302
+ | `POST /agents/<id>/model` `{ model }` | Switch an agent's model and save it in its `agent.json` |
303
+ | `GET /agents/<id>/todos?session=` | The list of steps the agent keeps in that conversation |
304
+ | `POST /agents/<id>/compact` `{ session? }` | Shorten a conversation: its earlier part becomes a summary. Queued like a message; answers with the task's id |
305
+ | `POST /agents/<id>/thinking` `{ level }` | Set an agent's reasoning level and save it in its `agent.json` |
306
+ | `POST /agents/<id>/mode` `{ mode, session?, anyway? }` | Switch an agent's mode (`auto`, `safe`, `manual`, `bypass` or `plan`). `auto`, `safe` and `manual` are saved and hold after a restart; `bypass` and `plan` hold until the daemon restarts. `anyway: true` with a `session` keeps bypass in force in that conversation although it has read outside content |
307
+ | `GET /tasks?agent=&session=&status=&limit=`, `GET /tasks/<id>` | Tasks |
308
+ | `GET /tasks/<id>/transcript` | What a task did, step by step: the text it was given, what it wrote, its tool calls with the start of each result. With `?full=1`: with the whole result of each call, up to 200 000 characters |
309
+ | `GET /events?topic=&after=&limit=` | Event log; `after=<id>` pages forward |
310
+ | `GET /events/stream?topic=` | Live events as server-sent events |
311
+ | `GET /state?key=` | Shared state |
312
+ | `POST /events` `{ topic, payload }` | Publish an event (as owner; `"trust": "untrusted"` to lower it) |
313
+ | `POST /agents/<id>/prompt` `{ prompt, session?, wait?, attachments?, whenBusy?, mentions? }` | Give a task. Waits for the result unless `wait` is false. With `"whenBusy": "steer"`, a message for a conversation that is working is given to that work instead of waiting behind it (the answer then carries `steered`, the id of that task). `mentions` lists files of the conversation's folder that the message points at with `@` (`"src/a.ts"`, `"src/a.ts#20-45"`); the agent is told to read them. `attachments` is a list of `{ name, data }` with base64 data, at most 10 files of 20 MB each; the files are saved to `inbox/` in the agent's workspace. With `"cancelOnDisconnect": true` the task is cancelled when the caller closes the connection while it waits |
314
+ | `POST /agents/<id>/reset` `{ session? }` | Reset a session. What it was subscribed to on its own ends too |
315
+ | `POST /agents/<id>/undo` `{ session? }`, `POST /agents/<id>/redo` `{ session? }` | Take back the owner's last message in a conversation, with the files it changed, or bring back what the last undo took. See [coding.md](coding.md) |
316
+ | `GET /media/tool/<id>` | A picture a tool returned. The ids are in the `images` field of `agent/<id>/tool` events and of transcript steps |
317
+ | `GET /tasks/<id>/images/<n>` | The n-th picture that came with a task (an attachment, a Telegram photo) |
318
+ | `GET /agents/<id>/image?path=&session=` | A picture, video or sound file in that agent's workspace or, with `session`, in the folder opened for that conversation. Anything that is not an image, video or sound file in there is "not found" |
319
+ | `POST /images/fetch` `{ url }` | Fetch a picture, video or sound from the web for display: https and public addresses only; pictures up to 20 MB, videos and sound up to 100 MB |
320
+ | `GET /sources`, `GET /agents/<id>/sources` | Event sources and their state; the ones that agent can subscribe to |
321
+ | `POST /agents/<id>/subscribe` `{ source, session?, note?, when?, throttle?, debounce?, separate? }`, `POST /agents/<id>/unsubscribe` `{ source, session? }` | Change an agent's subscriptions (written to its `agent.json`); `session` makes it one conversation's |
322
+ | `POST /subscribe` `{ source, note?, ... }`, `POST /unsubscribe` `{ source }` | The subscription of all agents (written to `pine.json`) |
323
+ | `POST /agents/<id>/close` `{ session }` | A conversation's tab was closed in a UI: ends what it was subscribed to on its own. The conversation itself is kept |
324
+ | `POST /tasks/<id>/cancel` | Cancel |
325
+ | `POST /approvals/<id>` `{ allow, always?, values? }` | Answer an approval. A request that lists `inputs` (a token, a password) is only allowed together with `values: { <name>: "..." }`; the terminal UI has a field for them. A question an agent asks with its `question` tool is such a request (`tool: "question"`, with the answers it offers in `choices`): answer it with `values: { "answer": "..." }`, or with `allow: false` for no answer |
326
+ | `POST /state` `{ key, value }` | Write state; `null` deletes |
327
+ | `POST /hook/<name>` | Webhook: a hook from `http.hooks` ([events.md](events.md)) or a running `webhook` source ([sources.md](sources.md)). No token; each has its own secret, unless a hook is declared `"open": true` |
328
+
329
+ ## Day to day
330
+
331
+ - **See what is happening:** `pine events -f` in a terminal. Add `--topic "agent/#"` for agent
332
+ activity only; tool calls appear live on `agent/<id>/tool`.
333
+ - **Why did it answer that?** `pine task <id>` shows the prompt as the agent received it, the
334
+ tools it called and the result. The full transcript is the newest `.jsonl` under
335
+ `~/.pine/agents/<id>/sessions/<session>/`.
336
+ - **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.
339
+ - **Change configuration:** edit `pine.json` or `agent.json`, run `pine check`, restart the
340
+ daemon. Queued tasks survive the restart. MCP servers, event sources, subscriptions and new
341
+ agents need neither an edit nor a restart: ask an agent ([setup.md](setup.md)), or use
342
+ `pine mcp add` and `pine subscribe`.
343
+ - **An agent is stuck:** `pine status`, then `pine cancel <id>`.
344
+ - **An agent keeps asking for approval:** it is in manual mode (`pine mode <agent> auto`, or
345
+ the mode in the bottom bar of the terminal UI), or the question names a tool on its `approve`
346
+ list. Sending something out also asks after a conversation has read outside content (it is
347
+ tainted): "Always here" in the dialog covers that tool for the conversation, and `/reset`
348
+ or `pine reset` starts a clean one.
349
+ - **Back up:** the home directory. `data/pine.db` holds events and tasks, `agents/*/sessions`
350
+ the conversations. Workspaces are wherever you put them.
351
+
352
+ ## Problems
353
+
354
+ | Symptom | Likely cause |
355
+ |---|---|
356
+ | `pine.json not found` | Wrong home. Pass `--home` or set `PINE_HOME`. |
357
+ | `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
+ | 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
+ | `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. |
360
+ | A task fails with 401 or "API key" | The provider's credential is missing or expired. `pine login <provider>` again. |
361
+ | 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
+ | 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. |
363
+ | The agent says macOS does not let pine operate apps, or take pictures of the screen | macOS has to be told once: System Settings > Privacy & Security > Accessibility (and Screen & System Audio Recording for pictures), switch on the terminal app pine runs in. See "What macOS has to be told, once" in [computer.md](computer.md). |
364
+ | The agent has no tools to click or type in apps | App control is for an agent that reaches your whole account, in your own conversations, on macOS. `pine check` says which under `apps`. See [computer.md](computer.md). |
365
+ | The UI says "reconnecting…" | The daemon it was attached to stopped. Start it again; the UI picks it up. |
366
+ | `no daemon answers on http://127.0.0.1:7463` | The daemon is not running, or `http.port` differs from what the CLI reads in this home. |
367
+ | A task fails with a connection error | The model server is down or `baseUrl` is wrong. `curl <baseUrl>/models` should answer. |
368
+ | A task fails after minutes with a timeout | The model stopped streaming (`limits.modelStreamIdleMs`) or took too long to start (`limits.modelHeadersTimeoutMs`); raise them for a slow model. |
369
+ | The agent stops after every step and asks whether it should go on | That is how a turn ends. Give the conversation a goal: `/goal <what should be reached>` in the terminal UI, and it is called again until a judge says the goal is met ("Goal mode" in [agents.md](agents.md)). |
370
+ | A goal is paused with "gave no verdict" | The judge did not answer in time (`limits.goalJudgeTimeout`) or not with MET, CONTINUE or BLOCKED. `/goal resume` goes on; if it happens often, give the judge a model that follows a format (`defaults.judge`). |
371
+ | The agent says a file is "not permitted" | It is outside what the agent reaches. The main agent works in `auto` mode and has your whole account; other agents work in `safe` mode, in a sandbox, and have their workspace (`mode`: `pine mode <agent> auto` gives another agent the account). pine's own home is closed to every agent in every mode. After outside content the main agent keeps that reach, except for files that are read as instructions (the `AGENTS.md` of the folder it works in, for example). You are asked when a call needs something outside (by pine, or by the agent with `request_access`); if you said no, pine does not ask again in that conversation. To open a folder for good, use `sandbox.read` / `sandbox.write`. |
372
+ | An approval `request_access` appears that the agent did not ask for | pine asked on the agent's behalf: a file tool or a shell command needed a file or folder outside the agent's sandbox, or the network. The first lines say what, the line `for:` which call. Yes holds for that conversation; no is remembered there. See "When a call needs something outside" in [security.md](security.md). |
373
+ | An agent says "No such file" for a folder in your home that exists (`~/Documents/scans`) | In the shell of an agent in the sandbox (`safe` or `manual` mode) `~` is its own private home (`sandbox/<id>/` in pine's home), not yours. pine catches this where the path is written out in the command, asks you for the folder in your home, and tells the agent to use the full path. Tell the agent the full path (`/Users/you/Documents/scans`) if it built the name some other way. |
374
+ | The agent cannot stop a program it started (`kill: Operation not permitted`) | In the sandbox (`safe` or `manual` mode) every command has a sandbox of its own and cannot signal what an earlier one started. The agent's `stop_program` tool works in every mode, and so does `■ stop` under Running in the code pane. |
375
+ | `git` complains about identity | In the sandbox (`safe` or `manual` mode) the agent's shell has its own empty home. Run `git config --global user.name ...` once through the agent, or set it per repository. |
376
+ | A command needs the network | `sandbox.network: true` for that agent, or better a `commands` tool for that one command. |
377
+ | Telegram bot does not react | `pine sources`: is the `telegram` source running, and is a conversation subscribed? A new bot waits to be paired: write to it, and type the code it sends you into the question in the terminal UI (`pine sources` says whom it listens to). Otherwise another program polls the same bot token. |
378
+ | An event arrives but no task starts | See "When nothing happens" in [events.md](events.md) for routes and in [sources.md](sources.md) for subscriptions. |
379
+ | The first answer after a pause is slow | The session was closed after `idleMs` and is being resumed; MCP servers start again. |
380
+
381
+ ## Coming from OpenClaw
382
+
383
+ | OpenClaw | pine |
384
+ |---|---|
385
+ | Agents in `openclaw.json` with `workspace-*` folders | One folder per agent under `agents/`; `workspace` points at the repository |
386
+ | 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 |
388
+ | `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 |
390
+ | Cron jobs | A schedule: ask the agent ("every morning at seven ..."), or write it under `schedules` with a `task` |
391
+ | 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
+ | `/hooks/*` mappings | A `webhook` source the agent subscribes to, or `http.hooks` plus a route |
393
+ | Managed extensions that watch something and message Telegram themselves | An event source the agent subscribes to (a folder, an FTP drop, MQTT), and the `send` tool for what it reports to you on Telegram. The agent then knows what happened |
394
+ | Skills | Skills, same format |
@@ -0,0 +1,195 @@
1
+ # How pine works
2
+
3
+ ## The picture
4
+
5
+ You talk to an agent, in the terminal UI or on Telegram. An agent is given four things, each by
6
+ asking it: two that wake it, and two that it uses while it works.
7
+
8
+ ```
9
+ you: terminal UI · Telegram
10
+ │
11
+ ▼
12
+ wake it ┌───────────┐ it uses
13
+ events ───────────────► │ │ ◄───────── MCP servers
14
+ Telegram · MQTT · FTP │ │ ◄───────── skills
15
+ webhooks · folders │ agent │
16
+ web addresses │ │
17
+ commands · etc │ │
18
+ schedules ────────────► │ │
19
+ repeating · once └─────┬─────┘
20
+ │ delegate ──► other agents
21
+ │ subagent ──► with distinct prompts, in parallel
22
+ ▼
23
+ answers · messages · actions
24
+ ```
25
+
26
+ | Given | What it is | Tools | More |
27
+ |---|---|---|---|
28
+ | Events | Something that happens elsewhere wakes the agent: a file arrives, a device reports, a web address changes, you write on Telegram | `add_source`, `subscribe`, `send` | [sources.md](sources.md) |
29
+ | Schedules | The time wakes the agent, with a task: at set times, every so often, or once | `add_schedule` | [events.md](events.md) |
30
+ | MCP servers | Tools from outside that the agent can call | `add_mcp_server` | [mcp.md](mcp.md) |
31
+ | Skills | How something is done, written down once | `add_skill` | [agents.md](agents.md) |
32
+
33
+ Each of the four is set up for the conversation it was asked for in, for the agent, or (by the
34
+ main agent only) for all agents. Only the main agent creates other agents and registers new
35
+ types of event source. What an agent has of each, and whom it is for, it asks a tool:
36
+ `sources`, `schedules`, `mcp_servers`, `skills`. See [setup.md](setup.md).
37
+
38
+ How pine itself works is not in an agent's prompt. An agent looks it up with its `manual`
39
+ tool, which searches these pages ([agents.md](agents.md)).
40
+
41
+ ## Inside the daemon
42
+
43
+ Underneath, everything is an event in one log, and three things turn events into work:
44
+ subscriptions, schedules with a task, and routes.
45
+
46
+ ```
47
+ what wakes an agent the daemon model server
48
+ ┌────────────────────────────────┐ ┌──────────────────────────────┐ ┌──────────────────┐
49
+ │ event sources │ │ event log (SQLite) │ │ llama-server or │
50
+ │ telegram a bot, long polling │──►│ topic · payload · trust │ │ any OpenAI-style │
51
+ │ mqtt a broker │ │ │ │ │ endpoint │
52
+ │ folder new, changed files │ │ ▼ │ └────────▲─────────┘
53
+ │ webhook calls from services │ │ subscriptions, schedules │ │
54
+ │ ftp uploads │ │ with a task, and routes │ │ model slots
55
+ │ http an address, polled │ │ when · debounce · throttle │ │ (priority queue)
56
+ │ command run again and again │ │ │ │ │
57
+ │ schedules cron · every · at │ │ │ │ │
58
+ └────────────────────────────────┘ │ ├─ set state │ │
59
+ ▲ │ ├─ publish event │ │
60
+ │ answers, and what │ ├─ one model call ────┼───────────────┤
61
+ │ agents send │ │ │ │
62
+ └────────────────────────┤ └─ agent task │ │
63
+ │ │ │ │
64
+ │ ┌─────────▼────────────┐ │ │
65
+ │ │ task queue (SQLite) │ │ │
66
+ │ │ one lane per session │ │ │
67
+ │ └─────────┬────────────┘ │ │
68
+ │ ┌─────────▼────────────┐ │ │
69
+ │ │ pi session │───┼───────────────┘
70
+ │ │ workspace, AGENTS.md│ │
71
+ │ │ tools, MCP, skills │ │
72
+ │ │ policy gate │ │
73
+ │ └──┬───────────────┬───┘ │
74
+ │ │ delegate │ subagent
75
+ │ ▼ ▼ │
76
+ │ other agents copies of itself
77
+ └──────────────────────────────┘
78
+ ```
79
+
80
+ ## Events
81
+
82
+ Everything that happens is an event. An event has:
83
+
84
+ | Field | Meaning |
85
+ |---|---|
86
+ | `id`, `ts` | Position in the log and time |
87
+ | `topic` | For example `source/telegram/message`, `source/house/message`, `agent/gonzo/done` |
88
+ | `source` | Who published it: `source:<name>` (`source:<name>@<agent>` for an agent's own source), `http`, `api`, `timer`, `route:<name>`, `router`, `agent:<id>`, `approvals`, `pine` |
89
+ | `payload` | Any JSON |
90
+ | `trust` | `owner` or `untrusted`; set by the publisher according to how the content arrived |
91
+ | `cause`, `hops` | The event that led to this one, and how many agent or route steps lie between it and an outside trigger |
92
+ | `reply` | Optional: the topic and fields an answer should be published with |
93
+
94
+ Events are stored in `data/pine.db` and pruned after `limits.eventRetentionDays`. A source can
95
+ report noisy telemetry without storing it.
96
+
97
+ Topics pine itself uses:
98
+
99
+ | Topic | Published when |
100
+ |---|---|
101
+ | `agent/<id>/started`, `agent/<id>/done`, `agent/<id>/failed` | A task starts or ends |
102
+ | `agent/<id>/tool` | A tool call starts or ends (live only, not stored) |
103
+ | `agent/<id>/todos` | The agent changed its list of steps (`items`, each with `text` and `status`; live only) |
104
+ | `agent/<id>/steered` | A message was given to a task that was already working (`task`), instead of becoming work of its own (live only) |
105
+ | `agent/<id>/goal` | The goal of a conversation was set, judged, paused, resumed or cleared (the goal with its `objective`, `status`, `round`, `note` and the judge's `reason`, and `event`: what just happened) |
106
+ | `agent/<id>/undone`, `agent/<id>/redone` | The owner took back their last message in a conversation, or brought it back (`session`, `message`, how many `tasks` and `files`) |
107
+ | `agent/<id>/delta`, `agent/<id>/thinking`, `agent/<id>/message` | Streamed answer text; what the model thinks (`phase: "start"`, then pieces of `text`, then `phase: "end"` with `ms`); the end of a model message with token counts (live only) |
108
+ | `state/<key>` | Shared state changes |
109
+ | `timer/<name>` | A schedule fires (`timer/<name>@<agent>` for an agent's own; `topic` on the schedule overrides it) |
110
+ | `source/<name>/<event>` | An event source reports something (`source/<name>@<agent>/<event>` for an agent's own source) |
111
+ | `out/source/<name>` | An answer on its way out through a source that can send |
112
+ | `hook/<name>` | A hook under `http.hooks` in `pine.json` was called (a `webhook` source reports `source/<name>/received` instead) |
113
+ | `approval/requested`, `approval/decided` | An approval is asked for or answered |
114
+ | `pine/started`, `pine/route-failed` | Daemon lifecycle and route errors |
115
+
116
+ Agents cannot publish on `agent/`, `approval/`, `pine/`, `state/` or `timer/`.
117
+
118
+ ## From event to work
119
+
120
+ Three things start work, and the first two need nothing written by hand:
121
+
122
+ - **A subscription.** An agent subscribes a conversation to an event source (a folder, an MQTT
123
+ device, a web address, a command, a webhook, an FTP drop, Telegram). Each event the source
124
+ reports arrives in that conversation as a message and starts a turn. A source that nobody is
125
+ subscribed to is not running, unless it has `"start": "always"`. See [sources.md](sources.md).
126
+ - **A schedule with a task.** When it is time, the agent is woken with the task, in the
127
+ conversation the schedule belongs to. See [events.md](events.md).
128
+ - **A route.** A rule you write in `pine.json`: it names topic patterns and what to do. It can
129
+ combine the first of these with one of the other two:
130
+ 1. **Rule.** Write shared state (`set`) or publish another event (`publish`). No model.
131
+ 2. **One model call** (`call`). No tools, no history: classify an image, summarise a reading.
132
+ The answer can be published as a new event.
133
+ 3. **Agent turn** (`agent`). A task in an agent's session with its tools.
134
+
135
+ Most events a route handles should stop at 1 or 2. See [events.md](events.md).
136
+
137
+ ## Tasks, sessions, slots
138
+
139
+ A task is a prompt for one agent in one session. Tasks for the same session run one after another;
140
+ different sessions run side by side, limited by `limits.maxConcurrentRuns` model slots. A run
141
+ that only waits (for a delegated task, for sub-agents, for an approval) gives its slot up
142
+ meanwhile, so a chain of agents works even with one slot. One exception to "one after
143
+ another": a message sent with `"whenBusy": "steer"`, as the terminal UI sends yours, is given
144
+ to the task that is working and read at its next step ([agents.md](agents.md), "Sessions").
145
+
146
+ A session is a pi `AgentSession`: the model loop, tool calls, compaction and retries are pi's.
147
+ Named sessions are stored as JSONL under `agents/<id>/sessions/<key>/` and survive restarts.
148
+ `"session": "new"` gives a fresh one that is closed when the task ends. A live session is
149
+ closed after `idleMs` without work and resumed from disk when needed. A named session other
150
+ than `main` that is not pinned, not open in a tab of the terminal UI, not subscribed to a
151
+ source and without a schedule of its own is removed after `limits.conversationDays` (7; `0`:
152
+ never) without a message. A run that an outside event started works in a session of its own,
153
+ `<name>~u`, so its history is never shared with yours.
154
+
155
+ When the daemon restarts, queued tasks run; a task that was running is marked failed
156
+ ("interrupted by a daemon restart") because its tool calls may already have had effects.
157
+ A shell command that an agent started in the background goes on without the daemon, and its
158
+ conversation is told how it ended when the daemon is back ([coding.md](coding.md)).
159
+
160
+ ## Answers
161
+
162
+ When a task ends, pine publishes `agent/<id>/done` or `agent/<id>/failed`. If the task has a
163
+ reply target, the final text is also published there, for example on `out/source/telegram` with
164
+ the chat id, and the Telegram source sends it. An agent that answers exactly `NO_REPLY` (or
165
+ `SILENT`) sends nothing, which is how routine checks stay quiet. A task that failed sends a
166
+ line saying so; a cancelled one sends nothing.
167
+
168
+ ## Agents working together
169
+
170
+ - `delegate` gives another agent a task. That agent runs it in its own workspace with its own
171
+ tools and sees only the task text. By default the caller waits for the answer; with
172
+ `wait: false` the answer arrives later as a message in the caller's session.
173
+ - `subagent` runs several copies of the same agent in parallel, each with its own task and an
174
+ empty context, and returns their final answers. It keeps large searches out of the caller's
175
+ context.
176
+ - Shared state (`state_get`, `state_set`) holds small facts such as `house/mode` that every agent
177
+ can read and that can be shown to an agent in every turn.
178
+ - `publish_event` lets an agent put an event on a topic you allowed, which routes then act on.
179
+ - `send` lets an agent reach out through a source that can send: a message to you on Telegram,
180
+ a command to a device over MQTT.
181
+
182
+ Loops are cut: a delegation chain cannot revisit an agent or exceed
183
+ `limits.maxDelegationDepth`, and events more than `limits.maxEventHops` steps away from an
184
+ outside trigger are not routed.
185
+
186
+ ## Trust
187
+
188
+ How content entered decides what it can do. See [security.md](security.md) for all of it.
189
+
190
+ | Content | Arrives as | Runs with |
191
+ |---|---|---|
192
+ | Your message in the terminal UI or from your paired Telegram account, `pine send`, a schedule (yours, or one an agent made at your wish) | `owner` | The agent's full tool set, in the named session |
193
+ | A webhook, an MQTT message, a new file, handled by a route | `untrusted` | The agent's `untrusted` profile (read-only tools by default), in a separate session |
194
+ | An event of a source a conversation is subscribed to | framed as data; taints that conversation unless the source is marked as yours | The conversation's own tool set, but sending information out needs your approval. With `"separate": true` on the subscription: as the row above |
195
+ | A web page, or the result of an MCP server marked `taints`, read during your own request | taints the session | Full tool set; from then on sending information out needs your approval |