@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.
- package/LICENSE +21 -0
- package/README.md +226 -2
- package/bin/pine.js +27 -0
- package/docs/SKILL.md +234 -0
- package/docs/references/agents.md +454 -0
- package/docs/references/coding.md +311 -0
- package/docs/references/computer.md +212 -0
- package/docs/references/configuration.md +310 -0
- package/docs/references/events.md +267 -0
- package/docs/references/mcp.md +420 -0
- package/docs/references/operations.md +394 -0
- package/docs/references/overview.md +195 -0
- package/docs/references/security.md +896 -0
- package/docs/references/setup.md +385 -0
- package/docs/references/sources.md +772 -0
- package/docs/references/stack.md +121 -0
- package/docs/references/tui.md +575 -0
- package/examples/home/.env.example +7 -0
- package/examples/home/USER.md +4 -0
- package/examples/home/agents/main/agent.json +4 -0
- package/examples/home/agents/main/workspace/AGENTS.md +14 -0
- package/examples/home/agents/main/workspace/MEMORY.md +4 -0
- package/examples/home/agents/main/workspace/SOUL.md +4 -0
- package/examples/home/models.json +62 -0
- package/examples/home/pine.json +34 -0
- package/examples/home/skills/README.txt +7 -0
- package/examples/launchd/com.pine.daemon.plist +32 -0
- package/examples/systemd/pine.service +22 -0
- package/mcp/browser.d.ts +99 -0
- package/mcp/browser.js +496 -0
- package/mcp/commands.d.ts +20 -0
- package/mcp/commands.js +88 -0
- package/mcp/computer.d.ts +139 -0
- package/mcp/computer.js +698 -0
- package/mcp/computer.swift +989 -0
- package/mcp/lib.d.ts +23 -0
- package/mcp/lib.js +52 -0
- package/mcp/web.d.ts +6 -0
- package/mcp/web.js +140 -0
- package/package.json +32 -4
- package/src/access.d.ts +112 -0
- package/src/access.js +438 -0
- package/src/actions.d.ts +75 -0
- package/src/actions.js +167 -0
- package/src/admin.d.ts +167 -0
- package/src/admin.js +625 -0
- package/src/agent-admin.d.ts +24 -0
- package/src/agent-admin.js +55 -0
- package/src/agents.d.ts +540 -0
- package/src/agents.js +2776 -0
- package/src/background.d.ts +29 -0
- package/src/background.js +100 -0
- package/src/cli.d.ts +2 -0
- package/src/cli.js +777 -0
- package/src/computer.d.ts +30 -0
- package/src/computer.js +32 -0
- package/src/config.d.ts +396 -0
- package/src/config.js +549 -0
- package/src/dev/claude-model.d.ts +37 -0
- package/src/dev/claude-model.js +204 -0
- package/src/env-file.d.ts +4 -0
- package/src/env-file.js +40 -0
- package/src/goals.d.ts +133 -0
- package/src/goals.js +316 -0
- package/src/http.d.ts +46 -0
- package/src/http.js +509 -0
- package/src/limiter.d.ts +32 -0
- package/src/limiter.js +84 -0
- package/src/login.d.ts +23 -0
- package/src/login.js +130 -0
- package/src/manual.d.ts +61 -0
- package/src/manual.js +443 -0
- package/src/mcp-config.d.ts +49 -0
- package/src/mcp-config.js +182 -0
- package/src/models.d.ts +90 -0
- package/src/models.js +274 -0
- package/src/net.d.ts +50 -0
- package/src/net.js +150 -0
- package/src/pine.d.ts +32 -0
- package/src/pine.js +134 -0
- package/src/programs.d.ts +123 -0
- package/src/programs.js +412 -0
- package/src/router.d.ts +56 -0
- package/src/router.js +164 -0
- package/src/sandbox-fs.d.ts +34 -0
- package/src/sandbox-fs.js +186 -0
- package/src/sandbox-linux.d.ts +96 -0
- package/src/sandbox-linux.js +297 -0
- package/src/sandbox-setup.d.ts +70 -0
- package/src/sandbox-setup.js +216 -0
- package/src/security.d.ts +238 -0
- package/src/security.js +660 -0
- package/src/skills.d.ts +67 -0
- package/src/skills.js +163 -0
- package/src/snapshots.d.ts +68 -0
- package/src/snapshots.js +306 -0
- package/src/source-types.d.ts +61 -0
- package/src/source-types.js +1 -0
- package/src/sources/command.d.ts +4 -0
- package/src/sources/command.js +77 -0
- package/src/sources/folder.d.ts +6 -0
- package/src/sources/folder.js +116 -0
- package/src/sources/ftp.d.ts +4 -0
- package/src/sources/ftp.js +307 -0
- package/src/sources/http.d.ts +4 -0
- package/src/sources/http.js +201 -0
- package/src/sources/mqtt.d.ts +18 -0
- package/src/sources/mqtt.js +97 -0
- package/src/sources/telegram.d.ts +22 -0
- package/src/sources/telegram.js +283 -0
- package/src/sources/webhook.d.ts +4 -0
- package/src/sources/webhook.js +52 -0
- package/src/sources.d.ts +344 -0
- package/src/sources.js +966 -0
- package/src/store.d.ts +99 -0
- package/src/store.js +277 -0
- package/src/timers.d.ts +83 -0
- package/src/timers.js +318 -0
- package/src/tools.d.ts +11 -0
- package/src/tools.js +1297 -0
- package/src/tui/app.d.ts +305 -0
- package/src/tui/app.js +3195 -0
- package/src/tui/client.d.ts +236 -0
- package/src/tui/client.js +131 -0
- package/src/tui/code-pane.d.ts +68 -0
- package/src/tui/code-pane.js +535 -0
- package/src/tui/highlight.d.ts +8 -0
- package/src/tui/highlight.js +86 -0
- package/src/tui/picture.d.ts +206 -0
- package/src/tui/picture.js +801 -0
- package/src/tui/run.d.ts +8 -0
- package/src/tui/run.js +97 -0
- package/src/tui/theme.d.ts +32 -0
- package/src/tui/theme.js +128 -0
- package/src/tui/undo.d.ts +5 -0
- package/src/tui/undo.js +50 -0
- package/src/tui/voice.d.ts +49 -0
- package/src/tui/voice.js +155 -0
- package/src/tui/voice.swift +223 -0
- package/src/types.d.ts +139 -0
- package/src/types.js +1 -0
- package/src/undo.d.ts +224 -0
- package/src/undo.js +465 -0
- package/src/update.d.ts +35 -0
- package/src/update.js +130 -0
- package/src/util.d.ts +65 -0
- package/src/util.js +171 -0
- package/src/watching.d.ts +20 -0
- package/src/watching.js +68 -0
- package/src/workspace-view.d.ts +72 -0
- package/src/workspace-view.js +221 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Paul Henschel
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,227 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
|
|
4
|
+
<img src="docs/images/logo-light.svg" alt="pine" width="360">
|
|
5
|
+
</picture>
|
|
6
|
+
</h1>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
```bash
|
|
9
|
+
npm install -g @pmndre/pine
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
### PINE makes AI reactive
|
|
13
|
+
|
|
14
|
+
Most harnesses just do input chat: "Do this do that". And maybe a scheduler: "Do it tomorrow". In PINE agents react to any stimuli. From watching folders, commands, websites, ftp endpoints, webhooks, to any other event source. You can hook them up and let them react to and operate your physical devices in the house, or digital assets.
|
|
15
|
+
|
|
16
|
+
PINE of course also handles regular chat, coding, tasks and orchestration. Agents carry memory and so on. All the basic stuff is in there, too.
|
|
17
|
+
|
|
18
|
+
### Some design choices
|
|
19
|
+
|
|
20
|
+
- **Event-driven architecture:** Agents subscribe to events and react. An event source is just a `*.ts` service with a schema. Tell the agent what you want and they subscribe: "Watch ~/documents/scans, for every new file: extract summaries and payment details, if present"
|
|
21
|
+
- **No configs:** Tell the main agent what you want. It configures PINE, creates agents, MCPs, event sources, skills and schedules through administrative tool calls, never touches user config, never messes it up or breaks it.
|
|
22
|
+
- **Self-discovery:** A built-in BM25 manual tool lets agents look up any API or internal detail on demand, without carrying docs in context.
|
|
23
|
+
- **A CLI that feels like a desktop app:** Tabs, buttons, scroll regions, inline images and video, and drag-and-drop with thumbnails. Works in Kitty-protocol terminals like Ghostty, with fallbacks for older ones.
|
|
24
|
+
- **Built in:** Computer use (macOS), web browsing, coding tools, diffs and git, undo, plan mode and goals (`/goal` keeps an agent working until it is done).
|
|
25
|
+
- **Orchestration:** Agents can delegate, create sub-agents in parallel. A pinned tab simply persists an agent and its task. Name it, give it instructions, chat with it or subscribe it to events.
|
|
26
|
+
|
|
27
|
+
> [!IMPORTANT]
|
|
28
|
+
> pine runs on macOS and Linux; `pine init` sets up what it needs. Windows users can try [Docker](#docker). It remains open what exactly is necessary to make it run completely in Windows.
|
|
29
|
+
|
|
30
|
+
<br/>
|
|
31
|
+
|
|
32
|
+
<table>
|
|
33
|
+
<tr>
|
|
34
|
+
<td align="center" width="50%">
|
|
35
|
+
<br />
|
|
36
|
+
<img src="docs/images/meme.png" width="100%" alt="pine searches the web, downloads a picture and shows it in the terminal"><br/>
|
|
37
|
+
<sub>Support for images</sub>
|
|
38
|
+
</td>
|
|
39
|
+
<td align="center" width="50%">
|
|
40
|
+
<br />
|
|
41
|
+
<img src="docs/images/video.gif" width="100%" alt="pine fetches a video from the web and plays it in the terminal"><br/>
|
|
42
|
+
<sub>Support for videos</sub>
|
|
43
|
+
</td>
|
|
44
|
+
</tr>
|
|
45
|
+
<tr>
|
|
46
|
+
<td align="center" width="50%">
|
|
47
|
+
<br />
|
|
48
|
+
<img src="docs/images/drop.png" width="100%" alt="A picture dropped into the terminal, shown as a thumbnail, and the agent's answer about it"><br/>
|
|
49
|
+
<sub>Drag and drop</sub>
|
|
50
|
+
</td>
|
|
51
|
+
<td align="center" width="50%">
|
|
52
|
+
<br />
|
|
53
|
+
<img src="docs/images/watch.png" width="100%" alt="Asked to watch a folder, the agent sets up an event source; a file changes, it wakes up and shows the git diff"><br/>
|
|
54
|
+
<sub>Event sources (file watchers, ...)</sub>
|
|
55
|
+
</td>
|
|
56
|
+
</tr>
|
|
57
|
+
<tr>
|
|
58
|
+
<td align="center" width="50%">
|
|
59
|
+
<br />
|
|
60
|
+
<img src="docs/images/tabs.png" width="100%" alt="Tabs for several agents and conversations, with the list of conversations: pinned ones stay, the others clean themselves up"><br/>
|
|
61
|
+
<sub>UI can be navigated by clicking</sub>
|
|
62
|
+
</td>
|
|
63
|
+
<td align="center" width="50%">
|
|
64
|
+
<br />
|
|
65
|
+
<img src="docs/images/flipper.png" width="100%" alt="pine drives a Flipper Zero through an MCP server"><br/>
|
|
66
|
+
<sub>Support for MCPs and skills</sub>
|
|
67
|
+
</td>
|
|
68
|
+
</tr>
|
|
69
|
+
<tr>
|
|
70
|
+
<td align="center" width="50%">
|
|
71
|
+
<br />
|
|
72
|
+
<img src="docs/images/code.png" width="100%" alt="The code pane beside a conversation: the git diff of a file the agent just changed"><br/>
|
|
73
|
+
<sub>Code assistance</sub>
|
|
74
|
+
</td>
|
|
75
|
+
<td align="center" width="50%">
|
|
76
|
+
<br />
|
|
77
|
+
<img src="docs/images/folder.png" width="100%" alt="pine started in a project folder: the agent inspects it, and the folder menu lists the folders a conversation can work in"><br/>
|
|
78
|
+
<sub>Current folders</sub>
|
|
79
|
+
</td>
|
|
80
|
+
</tr>
|
|
81
|
+
</table>
|
|
82
|
+
|
|
83
|
+
<br/>
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
you: terminal UI · Telegram
|
|
87
|
+
│
|
|
88
|
+
▼
|
|
89
|
+
wake it ┌───────────┐ it uses
|
|
90
|
+
events ───────────────► │ │ ◄───────── MCP servers
|
|
91
|
+
Telegram · MQTT · FTP │ │ ◄───────── skills
|
|
92
|
+
webhooks · folders │ agent │
|
|
93
|
+
web addresses │ │
|
|
94
|
+
commands · etc * │ │
|
|
95
|
+
schedules ────────────► │ │
|
|
96
|
+
repeating · once └─────┬─────┘
|
|
97
|
+
│ delegate ──► other agents
|
|
98
|
+
│ subagent ──► with distinct prompts, in parallel
|
|
99
|
+
▼
|
|
100
|
+
answers · messages · actions
|
|
101
|
+
|
|
102
|
+
Events, schedules, MCPs and skills can be set up by asking:
|
|
103
|
+
for the current conversation, agent scope, or globally
|
|
104
|
+
(main agent only) for all agents.
|
|
105
|
+
|
|
106
|
+
* New event types that agents can subscribe to can be created easily.
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Quick start
|
|
110
|
+
|
|
111
|
+
Sets everything up: the browser the web tools drive, and your user folder (`~/.pine`). On Linux
|
|
112
|
+
also the sandbox that agents in `safe` mode work in; it shows what it would install and asks once.
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
pine init
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Checks the setup: validates the configuration, lists each agent with its model, tools and MCP
|
|
119
|
+
servers, and prints security notes if something is open that should not be.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
pine check
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Opens the terminal UI. If no daemon is running, it starts one inside and stops it when you quit.
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
pine
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Runs the daemon as a service, without the UI, so agents keep reacting to events with no terminal
|
|
132
|
+
open. `pine` then attaches to it. To have it start at login, see
|
|
133
|
+
[operations.md](docs/references/operations.md).
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
pine start
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Connect your subscriptions, or local llm servers. Switch with `/model` in the UI:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
pine login opencode-go
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`pine login anthropic` and `pine login openai-codex` use a Claude or ChatGPT subscription. A
|
|
146
|
+
model server of your own (llama.cpp, vLLM, LM Studio) is added by its address, with
|
|
147
|
+
`pine model add studio http://127.0.0.1:8080`, or by asking the main agent. See
|
|
148
|
+
[operations.md](docs/references/operations.md) and [tui.md](docs/references/tui.md).
|
|
149
|
+
|
|
150
|
+
To work on a project, start it in that folder. The agent gets that folder for the
|
|
151
|
+
conversation, and `▤ code` (or `ctrl+g`) opens a pane with git changes and diffs, the files and
|
|
152
|
+
the output of its tool calls. `/undo` takes your last message back, with the files it changed
|
|
153
|
+
([coding.md](docs/references/coding.md)):
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
pine .
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
To get a newer version later, with whatever it needs:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
pine update
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Docker
|
|
166
|
+
|
|
167
|
+
A container needs nothing special. It is the wall around pine, and the agents work inside it
|
|
168
|
+
without a sandbox of their own:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
docker run -it -v pine:/root/.pine node:24 bash
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`-v pine:/root/.pine` keeps pine's home (configuration, conversations) when the container is
|
|
175
|
+
replaced. Inside, it is the same as anywhere:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
npm install -g @pmndre/pine
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
pine init
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Every agent whose mode you did not choose then works in `auto` mode, and `pine check` says so.
|
|
186
|
+
The agents and pine's own secrets are in the same container; what keeps the two apart there is
|
|
187
|
+
described under "pine's own files without a sandbox" in
|
|
188
|
+
[docs/references/security.md](docs/references/security.md).
|
|
189
|
+
|
|
190
|
+
`safe` mode puts an agent into a sandbox of its own, as on a Mac. A container may only make
|
|
191
|
+
one when it is started with the rights for it, which take away most of what Docker itself
|
|
192
|
+
protects:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
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
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
| Part | What it is for |
|
|
199
|
+
| --- | --- |
|
|
200
|
+
| `--cap-add SYS_ADMIN` | lets the sandbox create its namespaces |
|
|
201
|
+
| `--cap-add NET_ADMIN` | lets a sandbox without network have its own loopback interface |
|
|
202
|
+
| `--security-opt seccomp=unconfined` | Docker's system call filter forbids the sandbox's change of root |
|
|
203
|
+
| `--security-opt apparmor=unconfined` | Docker's AppArmor profile forbids its mounts |
|
|
204
|
+
|
|
205
|
+
`pine init` installs what the image lacks (bubblewrap, the browser's system libraries) and says
|
|
206
|
+
so if a right is missing. With pine as an ordinary user in the container instead of root, add
|
|
207
|
+
`--security-opt systempaths=unconfined`. `--privileged` works in place of all of them.
|
|
208
|
+
|
|
209
|
+
## Documentation
|
|
210
|
+
|
|
211
|
+
Start at [docs/SKILL.md](docs/SKILL.md); it indexes everything.
|
|
212
|
+
|
|
213
|
+
| To do this | Read |
|
|
214
|
+
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
215
|
+
| Understand how the pieces fit | [overview.md](docs/references/overview.md) |
|
|
216
|
+
| Use the terminal UI | [tui.md](docs/references/tui.md) |
|
|
217
|
+
| Work on a project: `pine .`, the code pane with git changes, files and tool output, `/undo` | [coding.md](docs/references/coding.md) |
|
|
218
|
+
| Install, run, use the CLI, run it as a service | [operations.md](docs/references/operations.md) |
|
|
219
|
+
| Write `pine.json` and `agent.json` | [configuration.md](docs/references/configuration.md) |
|
|
220
|
+
| Let agents set things up by tool call instead of editing files | [setup.md](docs/references/setup.md) |
|
|
221
|
+
| Set up agents, delegation and sub-agents | [agents.md](docs/references/agents.md) |
|
|
222
|
+
| Route events, schedules, model calls | [events.md](docs/references/events.md) |
|
|
223
|
+
| Event sources: Telegram, folders, MQTT, web addresses, commands, webhooks, FTP | [sources.md](docs/references/sources.md) |
|
|
224
|
+
| MCP servers, web search, command tools | [mcp.md](docs/references/mcp.md) |
|
|
225
|
+
| Let an agent operate the apps on your Mac | [computer.md](docs/references/computer.md) |
|
|
226
|
+
| Know what is protected and what is not | [security.md](docs/references/security.md) |
|
|
227
|
+
| Work on pine itself | [AGENTS.md](AGENTS.md), [stack.md](docs/references/stack.md) |
|
package/bin/pine.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// pine's launcher. From a checkout it runs the TypeScript sources as they are; from an installed
|
|
3
|
+
// package it runs the compiled ones (Node does not run TypeScript from inside node_modules).
|
|
4
|
+
import { spawnSync } from "node:child_process";
|
|
5
|
+
import fs from "node:fs";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { fileURLToPath, pathToFileURL } from "node:url";
|
|
8
|
+
|
|
9
|
+
if (Number(process.versions.node.split(".")[0]) < 24) {
|
|
10
|
+
console.error(`pine needs Node 24 or newer (this is ${process.versions.node}): https://nodejs.org`);
|
|
11
|
+
process.exit(1);
|
|
12
|
+
}
|
|
13
|
+
// The real place of this file, also when it was started through the link npm puts on the PATH.
|
|
14
|
+
const root = path.resolve(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))), "..");
|
|
15
|
+
const source = path.join(root, "src", "cli.ts");
|
|
16
|
+
if (fs.existsSync(source)) {
|
|
17
|
+
// A fresh checkout: fetch what pine is built on, once, so that the first command just works.
|
|
18
|
+
if (!fs.existsSync(path.join(root, "node_modules", "@earendil-works", "pi-coding-agent"))) {
|
|
19
|
+
console.error("pine: installing its dependencies (once) ...");
|
|
20
|
+
const done = spawnSync("npm", ["install", "--no-audit", "--no-fund"], { cwd: root, stdio: ["ignore", 2, 2] });
|
|
21
|
+
if (done.status !== 0) {
|
|
22
|
+
console.error(`pine: npm install failed; run it in ${root} to see why`);
|
|
23
|
+
process.exit(1);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
await import(pathToFileURL(source).href);
|
|
27
|
+
} else await import(pathToFileURL(path.join(root, "src", "cli.js")).href);
|
package/docs/SKILL.md
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pine
|
|
3
|
+
description: Run, configure and extend pine, the event-driven multi-agent daemon built on the pi coding agent SDK. Use when setting up agents and their workspaces, subscribing agents to event sources (Telegram, folders, MQTT, webhooks, FTP uploads, web addresses, commands), scheduling what happens at a time, adding MCP servers and skills, routing events to agents, reaching agents on Telegram, delegating between agents, reviewing what is protected against prompt injection, or changing pine's code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# pine
|
|
7
|
+
|
|
8
|
+
pine (PI neural engine) is one process that hosts several pi agent sessions and an event log.
|
|
9
|
+
Event sources and schedules turn the outside world and the clock into events; subscriptions,
|
|
10
|
+
schedules and routes turn events into work; agents answer, act, hand tasks to each other, and
|
|
11
|
+
publish events of their own.
|
|
12
|
+
|
|
13
|
+
Three things to know before anything else:
|
|
14
|
+
|
|
15
|
+
1. **Configuration lives in a home directory**, by default `~/.pine`: `pine.json` (global),
|
|
16
|
+
`models.json` (pi's model file), `.env` (secrets), and one folder per agent under `agents/`.
|
|
17
|
+
2. **An agent is a folder**: `agents/<id>/agent.json` and a workspace. In the workspace lie the
|
|
18
|
+
files the agent keeps itself and that are read into its prompt: `AGENTS.md` (its purpose),
|
|
19
|
+
`SOUL.md` (who it is), `MEMORY.md` (its memory). `USER.md` in the home is what all agents
|
|
20
|
+
know about you. The workspace is wherever `workspace` points, for example a repository.
|
|
21
|
+
3. **Where content came from decides what it may do.** Your own messages get the agent's full
|
|
22
|
+
tool set. Anything else is data. An event from outside runs with a reduced tool set in a
|
|
23
|
+
separate session; an event from a source a conversation subscribed to arrives in that
|
|
24
|
+
conversation, framed as data, and marks it as having read outside content (unless the source
|
|
25
|
+
is marked as yours). Either way nothing is sent out without your approval.
|
|
26
|
+
|
|
27
|
+
## If you are an agent running inside pine
|
|
28
|
+
|
|
29
|
+
You search this manual with your `manual` tool: a search names the parts that fit with the
|
|
30
|
+
line that matched, and you then read the one or two parts you need. Search before you answer a
|
|
31
|
+
question about pine or say that something is not possible.
|
|
32
|
+
|
|
33
|
+
pine's configuration lives in its home folder (`~/.pine` unless your owner chose another),
|
|
34
|
+
which is closed to you on purpose: you never write those files. Four things you set up by
|
|
35
|
+
calling a tool, for the conversation you are in or for yourself as an agent
|
|
36
|
+
([references/setup.md](references/setup.md)): event sources and subscriptions, schedules,
|
|
37
|
+
MCP servers, and skills. The main agent administers pine, and the rest is its job, also by
|
|
38
|
+
tool call ([references/setup.md](references/setup.md), "The main agent administers pine"):
|
|
39
|
+
creating, changing and deleting one of the others with its folder, pine's settings, routes, and
|
|
40
|
+
anything that is for everyone or for somebody else. If that is you, use those tools and never
|
|
41
|
+
send your owner to the files; if not, send your owner to it.
|
|
42
|
+
For what has no tool (the control API, a secret):
|
|
43
|
+
|
|
44
|
+
1. Search the manual for it and read the part.
|
|
45
|
+
2. Tell your owner what to put where: usually a few lines of JSON in `pine.json` (for everyone)
|
|
46
|
+
or `agents/<your id>/agent.json` (for you), then `pine check`, then a restart of the daemon
|
|
47
|
+
(quitting and reopening the terminal UI restarts an embedded one).
|
|
48
|
+
3. Do not try to edit those files or work around the restriction. Say plainly that this is a
|
|
49
|
+
step for them.
|
|
50
|
+
|
|
51
|
+
One thing you can start yourself: when your owner asks you to install or connect an MCP
|
|
52
|
+
server, call `add_mcp_server` with a short name and either its https URL (a remote server) or,
|
|
53
|
+
for a local server, the line that starts it (`command`, for example
|
|
54
|
+
`npx -y @example/mcp@latest`, taken from the server's own documentation). Do not send your
|
|
55
|
+
owner to a terminal for this: adding it is your job, and they confirm it in a dialog. Leave
|
|
56
|
+
the scope out: the server is then for the conversation you are in (in your main conversation:
|
|
57
|
+
for you as an agent). Pass `scope: "agent"` only if they said it is for you in general, and, as
|
|
58
|
+
the main agent, `scope: "global"` only if they said "for all agents". They get a dialog and
|
|
59
|
+
confirm it. `remove_mcp_server` takes one out again. Do not probe the URL first; an
|
|
60
|
+
"unauthorized" answer only means the server wants a sign-in, which your owner does afterwards
|
|
61
|
+
with `/mcp login <name>` in the terminal UI or `pine mcp login <name>` in a shell. Tell them
|
|
62
|
+
that. You do not have a new server's tools in the turn in which you added it: end that turn,
|
|
63
|
+
and pine calls you again at once in the same conversation, with the tools in your list. Never
|
|
64
|
+
tell your owner to start a new chat for it. A local server runs where your commands run (in your
|
|
65
|
+
sandbox, or without one when you work in auto mode), with your home folder. If it needs a sign-in, its
|
|
66
|
+
documentation says how (often the same line with `login` at the end): run that with bash, give
|
|
67
|
+
your owner the link it prints, and wait until they are done.
|
|
68
|
+
|
|
69
|
+
Another: when your owner asks you to watch something or to react when something happens, call
|
|
70
|
+
your `sources` tool: it lists what you can subscribe to and what you are subscribed to (use it
|
|
71
|
+
too when your owner asks what you are watching). If one fits, subscribe to it with a note that
|
|
72
|
+
says what you are to do; whoever is subscribed is woken with that note whenever it reports
|
|
73
|
+
something. A subscription is for the conversation it is asked for in: that one is woken, and the
|
|
74
|
+
subscription goes when the conversation is closed, reset or removed. So leave the scope out.
|
|
75
|
+
Only when your owner says in so many words that it is for more do you pass one: agent (your
|
|
76
|
+
main conversation is woken instead, and it stays) or, if you are the main agent, global (all
|
|
77
|
+
agents); your owner is then asked to confirm. Do not pick a wider scope yourself; if you think
|
|
78
|
+
they want one, ask. You can end anything your own agent is subscribed to from any of its
|
|
79
|
+
conversations (`unsubscribe` with scope `agent` or `all`). If none fits,
|
|
80
|
+
set one up with `add_source` (a folder to watch, a web address or a command that is looked at
|
|
81
|
+
again and again, an MQTT device, a webhook, an FTP drop, Telegram); your owner confirms it where
|
|
82
|
+
that is needed. A password or token is never yours to handle: leave it out, and pine asks your
|
|
83
|
+
owner for it in a dialog. `remove_source` deletes one for good. Through a source that can send
|
|
84
|
+
(Telegram, MQTT) you reach out with `send`. Do not go looking in pine's home folder for what is
|
|
85
|
+
configured: `sources` tells you.
|
|
86
|
+
|
|
87
|
+
When your owner wants something done at a time ("every morning at seven", "remind me at five",
|
|
88
|
+
"in twenty minutes"), that is a schedule, not a source: call `add_schedule` with a name, the
|
|
89
|
+
task in your own words, and one of `cron`, `every`, `at` or `in`. When it is time you are woken
|
|
90
|
+
with the task. `schedules` lists what is scheduled, `remove_schedule` ends one.
|
|
91
|
+
|
|
92
|
+
When your owner wants you to remember how something is done ("make a skill for this"), call
|
|
93
|
+
`add_skill` with a name, a line on when to use it, and the steps. It is listed among your
|
|
94
|
+
skills from your next message on; `remove_skill` deletes it. A fact rather than a procedure
|
|
95
|
+
belongs into your `MEMORY.md` instead. In a conversation that has read outside content, a
|
|
96
|
+
skill is put to your owner first, with its instructions: write what you did and learned, not
|
|
97
|
+
orders.
|
|
98
|
+
|
|
99
|
+
When your owner asks for something in an app on their Mac that is neither a web page nor a
|
|
100
|
+
command (a note in Notes, a setting, a document in TextEdit, trying out an app they built), and
|
|
101
|
+
you have the tools whose names start with `mcp__computer__`, use them: `apps` lists what runs,
|
|
102
|
+
`app_open` opens an app, `app_snapshot` reads a window as text with a reference on every
|
|
103
|
+
control, `app_press` and `app_set_text` use a reference, `app_type` and `app_key` use the
|
|
104
|
+
keyboard. If you can see pictures, `app_screenshot`, `app_click`, `app_drag` and `app_scroll`
|
|
105
|
+
work by position in a picture. Your owner is asked once per app. If you do not have these
|
|
106
|
+
tools, you cannot get them by asking: say so ([references/computer.md](references/computer.md)
|
|
107
|
+
says who has them).
|
|
108
|
+
|
|
109
|
+
When a call comes back "not approved", it was put to your owner, and your owner said no. Do
|
|
110
|
+
not try another way to the same end: say what you wanted to do and why.
|
|
111
|
+
|
|
112
|
+
Schedules, skills, sources and servers follow the same rule: leave the scope out and it is for
|
|
113
|
+
the conversation you are in. What you have of each, you see with a tool, never in pine's files:
|
|
114
|
+
`sources`, `schedules`, `mcp_servers` and `skills` list what this conversation has, whom each
|
|
115
|
+
is for, and what only another conversation of yours has.
|
|
116
|
+
|
|
117
|
+
When you cannot go on without your owner's decision (which of two ways, which file), ask with
|
|
118
|
+
your `question` tool, with two to five short answers to pick from. For work with several steps,
|
|
119
|
+
keep a list with your `todo` tool; your owner sees it. A command that takes long or keeps
|
|
120
|
+
running (a server, a build, a watcher) you start with `background: true` on the shell tool, and
|
|
121
|
+
`stop_program` ends it ([references/coding.md](references/coding.md), "Commands in the
|
|
122
|
+
background"). When your owner wants you to work on until something is reached, tell them to
|
|
123
|
+
type `/goal` with what they want reached: only they can set a goal
|
|
124
|
+
([references/agents.md](references/agents.md), "Goal mode"). In plan mode you only look and
|
|
125
|
+
answer with a plan; your owner switches the mode when it is to be carried out.
|
|
126
|
+
|
|
127
|
+
If you are the main agent and your owner asks for a new agent, call `create_agent` with an id,
|
|
128
|
+
one line on what it is for, and its instructions written to the agent itself ("You are ..."):
|
|
129
|
+
its job, what it should and should not do, how it reports. Your owner confirms it, and the agent
|
|
130
|
+
exists at once. For a device or service that no existing type of source can watch, the main
|
|
131
|
+
agent can also write a new source type and register it with `add_source_type`
|
|
132
|
+
([references/sources.md](references/sources.md)); try the existing types first. A model server
|
|
133
|
+
of your owner's own (llama.cpp, vLLM, LM Studio) is the main agent's to add as well, with
|
|
134
|
+
`add_model_server` and the server's address; never ask for its key, pine asks your owner
|
|
135
|
+
([references/setup.md](references/setup.md), "Adding a model server").
|
|
136
|
+
|
|
137
|
+
Things you can do yourself: work in your workspace, keep notes there, use the tools you have,
|
|
138
|
+
hand work to the agents listed in your prompt, and write shared state under your own keys.
|
|
139
|
+
|
|
140
|
+
## Which file to read
|
|
141
|
+
|
|
142
|
+
| You want to | Read |
|
|
143
|
+
|---|---|
|
|
144
|
+
| See what an agent is given (events, schedules, MCP servers, skills) and how events, tasks and sessions fit together | [references/overview.md](references/overview.md) |
|
|
145
|
+
| Chat with agents in the terminal: tabs, slash commands (`/goal`, `/compact`, `/copy`, `/export`, `/undo`), keys, the five modes (auto, safe, manual, bypass, plan), approvals, an agent's questions and its list of steps, what a model thinks, pictures, switching models | [references/tui.md](references/tui.md) |
|
|
146
|
+
| Work on a project: `pine .`, a folder for a conversation, the code pane with git changes, files and tool output, what an agent left running, what it runs in the background, and taking a message back with `/undo` and `/redo` | [references/coding.md](references/coding.md) |
|
|
147
|
+
| Install it, start it, update it, use the CLI (every `pine` command), the control API for scripts, run it at login or in a container, find out why something did not happen | [references/operations.md](references/operations.md) |
|
|
148
|
+
| Look up a key in `pine.json`, `agent.json`, `models.json` or `.env` | [references/configuration.md](references/configuration.md) |
|
|
149
|
+
| Know what agents can set up by tool call, for whom, and what you are asked: event sources, MCP servers, skills, schedules, new agents, new source types, model servers; how an agent lists what it has; the table of pine's own tools (`question`, `todo`, `stop_program` and the rest) | [references/setup.md](references/setup.md) |
|
|
150
|
+
| Add an agent, give it a workspace, tools and a persona; skills; how agents look pine up (the `manual` tool); delegation, sub-agents, sessions, goal mode (`/goal`: working until an objective is met), shared state | [references/agents.md](references/agents.md) |
|
|
151
|
+
| Let an agent react to the outside world and reach out: Telegram, a watched folder, MQTT devices, a web address or a command that is looked at again and again, webhooks, FTP uploads from cameras; subscribing, unsubscribing, sending; a source type of your own | [references/sources.md](references/sources.md) |
|
|
152
|
+
| Have something done at a time (schedules); write rules for events yourself: set state, publish, single model calls, debounce | [references/events.md](references/events.md) |
|
|
153
|
+
| Add MCP servers globally, per agent or for one conversation; web search, page reading and the bundled browser (showing its window to log in yourself, local addresses); turn shell commands into tools | [references/mcp.md](references/mcp.md) |
|
|
154
|
+
| Operate the apps on a Mac: read a window, press, click, type; who may, what is asked, the grants macOS needs | [references/computer.md](references/computer.md) |
|
|
155
|
+
| Understand the defences against outside abuse and prompt injection, and their limits: the sandbox (macOS and Linux), what happens after outside content, the modes, approvals | [references/security.md](references/security.md) |
|
|
156
|
+
| Know the technology underneath and the pi behaviours pine works around; open points | [references/stack.md](references/stack.md) |
|
|
157
|
+
| Change pine's code | [../AGENTS.md](../AGENTS.md) |
|
|
158
|
+
|
|
159
|
+
## The shortest working setup
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
npm install -g @pmndre/pine
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
pine init
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
pine
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
One agent, `main`, with web search and a browser, and the terminal UI to talk to it. Everything
|
|
174
|
+
below is added on top of that when you need it.
|
|
175
|
+
|
|
176
|
+
`~/.pine/pine.json`:
|
|
177
|
+
|
|
178
|
+
```json
|
|
179
|
+
{
|
|
180
|
+
"main": "main",
|
|
181
|
+
"defaults": { "model": "dev/claude-haiku" }
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
(An excerpt. `pine init` also writes the web, browser and app control servers and the limits;
|
|
186
|
+
put the model you use where `dev/claude-haiku` stands. `dev/claude-haiku` answers through
|
|
187
|
+
`claude -p` and needs Claude Code installed and signed in; for another model see "Choosing a
|
|
188
|
+
model" in [references/operations.md](references/operations.md).)
|
|
189
|
+
|
|
190
|
+
Telegram as a second way in is set up by asking the main agent: "watch Telegram". The dialog
|
|
191
|
+
you confirm has a field for the bot's token; then you write to the bot and type the six-digit
|
|
192
|
+
code it sends you into pine. See [references/sources.md](references/sources.md).
|
|
193
|
+
|
|
194
|
+
`~/.pine/agents/gonzo/agent.json`, a second agent, a specialist the main agent can hand work to.
|
|
195
|
+
Create the folder; the workspace here is `~/dev/gonzo`, which must exist, and an `AGENTS.md` in
|
|
196
|
+
it says what the agent is for (without `workspace`, pine makes `agents/gonzo/workspace` itself).
|
|
197
|
+
Or ask the main agent to create one: it calls `create_agent`, and no restart is needed.
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"description": "Contract law; knows the case files",
|
|
202
|
+
"workspace": "~/dev/gonzo"
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
pine check
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
pine start
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
`main` sees `gonzo` in its list of agents and can call `delegate`. `pine events -f` shows everything as it happens.
|
|
215
|
+
|
|
216
|
+
## Vocabulary
|
|
217
|
+
|
|
218
|
+
| Term | Meaning |
|
|
219
|
+
|---|---|
|
|
220
|
+
| event | One record in the log: topic, payload, source, trust, cause |
|
|
221
|
+
| topic | Slash-separated name, matched with `+` (one level) and `#` (the rest) |
|
|
222
|
+
| route | A rule in `pine.json` that reacts to topics |
|
|
223
|
+
| source | A named thing that reports events from outside: a folder, an MQTT broker, a web address, a command, a webhook, an FTP drop, a Telegram bot. It runs only while something is subscribed to it (or always, with `"start": "always"`) |
|
|
224
|
+
| schedule | Something done at a time: at set times, every so often, or once. With a task it wakes an agent to do it |
|
|
225
|
+
| goal | An objective you give a conversation with `/goal`: the agent is called again, round after round, until a judge says it is met |
|
|
226
|
+
| subscription | A conversation of an agent listens to a source: each event arrives there as a message and wakes the agent |
|
|
227
|
+
| task | One piece of work for one agent; has a status, a result and statistics |
|
|
228
|
+
| session | A conversation of one agent with history. The manual also says "conversation". Named ones are kept until removed (unused ones after `limits.conversationDays`); `new` is one-off |
|
|
229
|
+
| owner | You. Content is "owner" only when it entered through a channel that authenticated you |
|
|
230
|
+
| untrusted | Everything else: data that may contain instructions it has no right to give |
|
|
231
|
+
| tainted | A session that has seen outside content (a web page, an MCP result, an untrusted task) |
|
|
232
|
+
| approval | Your yes or no to one tool call, asked in the terminal UI and over Telegram, or answered with `pine approve` |
|
|
233
|
+
| mode | How much an agent does without asking: `auto` (the default), `plan` (it only looks and answers with a plan), `manual` (every action waits for your yes), `bypass` (nothing waits) |
|
|
234
|
+
| extension | A pi extension: pi's own plug-in format, usable in pine sessions |
|