@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,385 @@
1
+ # Changing the setup: tool calls, not files
2
+
3
+ pine's configuration is a few small JSON files, and they stay small because agents never write
4
+ them. In every mode, bypass included, pine's home folder is closed to an agent's shell and file
5
+ tools. What an agent may set up, it sets up by calling a tool. The tool checks what it is given,
6
+ asks you where that matters, and writes exactly the lines that are needed; when the thing is
7
+ removed, those lines go again and nothing is left behind (no empty lists, no stale access).
8
+
9
+ Four things reach an agent from outside its conversation, and all four are set up the same
10
+ way, with the same three scopes:
11
+
12
+ - **Events**: what happens elsewhere wakes the agent ([sources.md](sources.md)).
13
+ - **Schedules**: the time wakes the agent, with a task ([events.md](events.md)).
14
+ - **MCP servers**: tools the agent can call ([mcp.md](mcp.md)).
15
+ - **Skills**: how something is done, written down once ([agents.md](agents.md)).
16
+
17
+ The main agent can set each of them up for one conversation, for itself, or for all agents.
18
+ Every other agent can do so for one conversation or for itself.
19
+
20
+ You can still edit the files yourself, and the `pine` command changes them for you. This page
21
+ is about what agents can do.
22
+
23
+ ## Who can set up what
24
+
25
+ | What | For one conversation | For the agent | For all agents |
26
+ |---|---|---|---|
27
+ | An event source (folder, MQTT, web address, command, webhook, FTP, Telegram) | any agent (`add_source`) | any agent, when you say so | **only the main agent** |
28
+ | A subscription to a source | any agent (`subscribe`) | any agent, when you say so | **only the main agent** |
29
+ | A schedule | any agent (`add_schedule`) | any agent, when you say so | **only the main agent** |
30
+ | An MCP server, remote or local | any agent (`add_mcp_server`) | any agent, when you say so | **only the main agent** |
31
+ | A skill | any agent (`add_skill`) | any agent, when you say so | **only the main agent** |
32
+ | A new agent | | | **only the main agent** (`create_agent`) |
33
+ | Changing an agent, removing an agent | | | **only the main agent** (`update_agent`, `remove_agent`), you confirm every time |
34
+ | pine's settings | | | **only the main agent** (`set_setting`), you confirm every time |
35
+ | A route (a rule of your own) | | | **only the main agent** (`add_route`, `remove_route`), you confirm every time |
36
+ | Any of the first five rows, for another agent | | **only the main agent** (the same tools, with `agent`) | |
37
+ | A new type of event source (a program) | | | **only the main agent** (`add_source_type`), you confirm every time |
38
+ | A model server of your own (llama.cpp, vLLM, LM Studio, ...) | | | **only the main agent** (`add_model_server`), you confirm every time |
39
+
40
+ The main agent is the one `pine.json` names with `"main"`; without that entry it is the agent
41
+ called `main`, or else the first one. It is pine's administrator: what you want changed about
42
+ pine, you ask it for, and it does it with tools that check what they are given, instead of
43
+ you or an agent editing files. See "The main agent administers pine" below. The other agents do not have `create_agent`,
44
+ `update_agent`, `remove_agent`, `agents`, `settings`, `set_setting`, `routes`, `add_route`,
45
+ `remove_route`, `add_source_type`, `remove_source_type`, `add_model_server` or `remove_model_server`,
46
+ and they are refused when they ask for the global scope. Their instructions tell them who can do it, so
47
+ an agent you ask for something that is not its to do sends you to the main agent instead of
48
+ trying.
49
+
50
+ ## Three scopes
51
+
52
+ | Scope | Who gets it | It lasts |
53
+ |---|---|---|
54
+ | **conversation** (`local`, the default) | The conversation it was asked for in, and the sub-agents that conversation starts. Other conversations of the same agent do not see it. | Until that conversation is removed (by you, or by itself when unused; see [tui.md](tui.md)). Subscriptions also end when its tab is closed or it is reset. |
55
+ | **agent** | Every conversation of that agent. A subscription wakes its main conversation. | Until it is removed. |
56
+ | **global** | Every agent. | Until the main agent or you remove it. |
57
+
58
+ When a conversation is removed, everything that was set up for it alone is removed with it:
59
+ its event sources and subscriptions, its schedules, its MCP servers and its skills. When it is
60
+ renamed, all of that follows it to the new name. What was set up for the agent or for all
61
+ agents is not touched by either.
62
+
63
+ "Connect this server", "watch that folder", "subscribe to it", "remind me at five", "make a
64
+ skill for this", said in any conversation, means that conversation. An agent passes a wider scope only when you say so in so many words ("for
65
+ you as an agent", "always"; "for all agents"). In an agent's main conversation there is no
66
+ difference between the first two: the main conversation is the agent.
67
+
68
+ ## What you are asked
69
+
70
+ | An agent wants to | You are asked |
71
+ |---|---|
72
+ | Add an MCP server | Always, in every mode. The dialog names the server, its URL or its command, and who gets it. For a command it also says what the program will reach. |
73
+ | Add a source that opens something new (a folder outside its workspace, a broker, a port), is to be trusted as yours, or is for all agents | Yes, with what it will do in plain words. A folder inside its own workspace is not asked about. |
74
+ | Subscribe the conversation it is in | No. |
75
+ | Subscribe the agent as such from another conversation, or all agents | Yes. Deny it if you meant this conversation only. |
76
+ | End a subscription of its own agent | No. |
77
+ | Schedule something for the conversation it is in, or for itself from its main conversation | No. |
78
+ | Schedule something for the agent from another conversation, or for all agents | Yes, with the times and the task. |
79
+ | Add or replace a skill for the conversation it is in, or for itself from its main conversation | No. Its instructions are its own to write, as its `AGENTS.md` is. |
80
+ | Add or replace a skill for the agent from another conversation, or for all agents | Yes. The dialog shows the description and the instructions. |
81
+ | Remove a server, a source, a schedule or a skill that is the conversation's own | No. |
82
+ | Remove a server, a source, a schedule or a skill of the agent (from another conversation than its main one) or of all agents | Yes. |
83
+ | Create an agent | Always. The dialog shows its id, description, model, tools and instructions. |
84
+ | Register a new type of event source | Always, in every mode. The dialog says that it is a program, how long it is, what it imports and where the file is. |
85
+ | Take a source type out again | Yes. |
86
+ | End a subscription for all agents | No (the main agent only). |
87
+ | Add a model server | Always, in every mode: the address before any request goes there, and in a second dialog its key if it wants one. See "Adding a model server". |
88
+ | Remove a model server | Yes. |
89
+
90
+ In manual mode, and in a conversation that has read outside content, the questions that are
91
+ otherwise skipped are asked too (ending a subscription: in manual mode only).
92
+
93
+ In plan mode nothing is set up: every tool that adds, removes, subscribes or sends is refused
94
+ there without a question, and the agent says what it would set up. The tools that only list
95
+ (`sources`, `schedules`, `mcp_servers`, `skills`) work in every mode and are never asked about.
96
+
97
+ In a conversation that has read outside content two things are stricter, because what they
98
+ write is read back as instructions or runs as a program. `add_skill` is put to you first,
99
+ with its instructions ([security.md](security.md), "Skills are instructions").
100
+ `add_source_type` and `add_model_server` are refused: start a new conversation for it.
101
+
102
+ Runs with the reduced tool set, which outside events start through a route or a subscription
103
+ marked `separate`, have none of these tools, and neither have sub-agents.
104
+
105
+ ## What an agent has
106
+
107
+ An agent cannot read pine's configuration: the files are closed to it. What it has been given
108
+ it asks a tool, one for each kind of thing. Each of these lists what the conversation has, whom
109
+ each thing is for (this conversation, the agent, all agents), and what only another
110
+ conversation of the same agent has. So "which MCP servers do you have", "which skills do you
111
+ have", "what are you subscribed to" and "what is scheduled" are answered by a tool call, never
112
+ by a guess and never by looking for a file.
113
+
114
+ | What you ask about | The tool that lists it |
115
+ |---|---|
116
+ | MCP servers: which are connected, which the agent has | `mcp_servers` |
117
+ | Skills: what the agent knows how to do | `skills` |
118
+ | Events: sources, and who is subscribed and woken | `sources` |
119
+ | Schedules: what happens at set times | `schedules` |
120
+
121
+ Which model the agent runs on is told to it with your message, so it needs no tool for that.
122
+
123
+ ## The tools
124
+
125
+ | Tool | Does |
126
+ |---|---|
127
+ | **Events** | |
128
+ | `sources` | Lists the event sources this conversation can use and who is subscribed. |
129
+ | `add_source` `name` `type` `description` [`options`] [`scope`] [`note`] [`throttle`] [`own`] [`ask`] | Sets up a source; with a note it subscribes at once. `options` is an object with the options of the chosen type ([sources.md](sources.md)). `own: true` marks it as your own device or folder, whose events are trusted. `ask` names secret options that you are to type into the dialog. |
130
+ | `subscribe` `source` [`scope`] [`note`] [`when`] [`throttle`], `unsubscribe` `source` [`scope`] | Starts or ends being woken by a source. For `unsubscribe` the scope can also be `all`: everything the agent has on that source. |
131
+ | `send` `source` [`text`] [`data`] | Sends something out through a source that can send (Telegram, MQTT). |
132
+ | `remove_source` `name` | Stops a source, unsubscribes everyone from it and deletes it. For a watched folder, the read access that came with it goes too. |
133
+ | `add_source_type` `name` `file`, `remove_source_type` `name` | Main agent only. Registers a module the agent wrote as a new type of source, or takes one out. |
134
+ | **Schedules** | |
135
+ | `schedules` | Lists what is scheduled for the agent and when each is next due. |
136
+ | `add_schedule` `name` `task` + one of `cron`, `every`, `at`, `in` [`scope`] | Does the task at set times, every so often, or once. One that happens once removes itself. |
137
+ | `remove_schedule` `name` | Ends a schedule. |
138
+ | **MCP servers** | |
139
+ | `mcp_servers` | Lists the MCP servers this conversation has: whom each is for (this conversation, the agent, all agents) and whether its tools are in the agent's tool list (connected) or missing (it did not start, or it needs a sign-in). It also names servers that only another conversation of the agent has, which this one cannot use. This is how an agent answers "which MCP servers do you have": the configuration files are closed to it. |
140
+ | `add_mcp_server` `name` `url` or `command` [`secrets`] [`description`] [`scope`] | Proposes an MCP server: a remote one by its https `url`, or a local one by the line that starts it (one program with its arguments, nothing else). A local one runs inside the sandbox of the agent that uses it. `secrets` names the keys it needs; you type them into the dialog. A name can be used once. One exception: a server that only one conversation of the agent has is made the agent's by adding it again under its name with `scope: "agent"`, from that conversation or from another; you are asked, the new entry takes the place of the old one, and then all the agent's conversations have it. See [mcp.md](mcp.md). |
141
+ | `remove_mcp_server` `name` | Takes a server out again. A server that belongs to another conversation is removed there, or with that conversation. |
142
+ | **Asking, and keeping track** | |
143
+ | `question` `question` [`choices`] | Asks your owner one question when you cannot go on without their decision, with two to six short answers to pick from (the one you recommend first). They pick one in a dialog, or on Telegram with a button, or answer in their own words; you get the answer back as the tool's result. No answer is said plainly: go on with a reasonable assumption and say which. It changes nothing, so it also works in plan mode. Not for permission to act (that is asked by itself), and not there in a run your owner did not start |
144
+ | `todo` `items` | Your own list of the steps of a task that has several. Send the whole list every time, each step with a status: `pending`, `in_progress` (one at a time) or `done`. Your owner sees it in the conversation and in the status line ("step 2 of 5"), and with their next message you are shown what is still open, so you can pick the work up where it stood. It belongs to the conversation and goes when that is reset. An empty list clears it. At most 30 steps. Not there in a run your owner did not start |
145
+ | **Programs** | |
146
+ | `stop_program` [`id`] | Stops a program that one of the conversation's commands left running, such as a development server, or one the agent started in the background (`background: true`). Without `id` it lists them. Never asks: it only ends what the agent started. Only an agent with `bash` has it. See [coding.md](coding.md). |
147
+ | **Skills** | |
148
+ | `skills` | Lists the skills this conversation has and whom each is for (this conversation, the agent, all agents), and names skills that only another conversation of the agent has. This is how an agent answers "which skills do you have". |
149
+ | `add_skill` `name` `description` `instructions` [`files`] [`scope`] | Writes a skill; the same name in the same place replaces it. `files` is a folder in the agent's workspace whose contents go along. |
150
+ | `remove_skill` `name` | Deletes a skill in pine's own skill folders (`skills/`, `agents/<id>/skills/`, a conversation's), also one you put there by hand. A skill in a folder named under `skills` in a configuration file is yours to remove. |
151
+ | **Agents** | |
152
+ | `create_agent` `id` `description` `instructions` [`model`] [`tools`] | Main agent only. See below. Changing and removing one, and pine's settings: "The main agent administers pine". |
153
+ | **Model servers** | |
154
+ | `add_model_server` `name` `url` [`context`] | Main agent only. Adds a model server of your own by its address; pine asks the server for its models. See "Adding a model server". |
155
+ | `remove_model_server` `name` | Main agent only. Takes one out again, with the key pine keeps for it. Refused while an agent, the default or the judge of goals (`defaults.judge`) uses one of its models. You are asked. |
156
+ | **Not setup: the other tools pine gives an agent** | |
157
+ | `request_access` [`path`] [`write`] [`network`] `reason` | Asks you for access the conversation does not have: a file or folder outside the workspace (`path`; with `write: true` also to change it), or the network from the shell (`network: true`). You decide; a yes holds for the conversation until it is reset or pine restarts. pine's home is never granted. An agent does not have to call it: when a file tool or a shell command needs something outside, pine asks you the same question itself. See "When a call needs something outside" and "Modes" in [security.md](security.md). |
158
+ | `delegate` `agent` `task` [`wait`] [`thread`] | Hands a task to another agent and gets its answer. Only there when the agent's `delegates` list is not empty. See [agents.md](agents.md). |
159
+ | `subagent` `tasks` | Runs several copies of the agent side by side, one task each, and returns their answers. See [agents.md](agents.md). |
160
+ | `download` `url` `path` | Fetches a file from a web address into the workspace, byte for byte. It is how an agent gets a file that a remote MCP server made: by the link in the tool's answer, never by a file path from it. See "Downloads" in [security.md](security.md) and "Files and pictures from a remote server" in [mcp.md](mcp.md). |
161
+ | `publish_event` `topic` [`text`] [`data`] | Publishes an event on a topic of the agent's `publish` list. Without that list the tool is not there. See [events.md](events.md). |
162
+ | `state_get` `key`, `state_set` `key` `value` | Read and write shared state, within `state.read` and `state.write`. See "Shared state" in [agents.md](agents.md). |
163
+ | `manual` [`search`] [`read`] | Searches and reads this manual. See "The manual tool" in [agents.md](agents.md). |
164
+
165
+ The built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) are chosen with
166
+ `tools` in `agent.json`; the shell tool's `background` is described in [coding.md](coding.md).
167
+ The tools of MCP servers are in [mcp.md](mcp.md). A run that an outside event started has
168
+ `state_get` and what its `untrusted` profile lists, and none of the others.
169
+
170
+ Everything takes effect without a restart. An agent has new MCP tools and new skills from its
171
+ next message on, in the same conversation. After `add_mcp_server` that next message is pine's
172
+ own: the agent is called again at once and goes on with the new tools.
173
+
174
+ ## Adding a model server
175
+
176
+ Tell the main agent: "add my llama server at http://100.64.0.7:8080 as studio". It calls
177
+ `add_model_server` with the name and the address, and then:
178
+
179
+ 1. You are shown the address and confirm it. This is asked every time, in every mode: an agent
180
+ that is given one of the server's models sends its whole conversation there. Until you say
181
+ yes, no request goes to that address.
182
+ 2. pine asks the server which models it has, how much context one request gets, whether it
183
+ reads pictures and, for a model that thinks, which thinking levels it knows (from
184
+ llama.cpp's `/props`; other servers say less).
185
+ 3. If the server wants a key, a second dialog asks you to type it. It goes into `.env` as
186
+ `PINE_MODEL_<NAME>_API_KEY`; the agent and its model never see it. A key the server does not
187
+ accept is not kept.
188
+ 4. The entry is written to `models.json`, and the models are there at once: choose one with
189
+ `/model studio/<model>`, or have the main agent give it to a new agent.
190
+
191
+ Where a server does not say how much context its models get, the agent is told so and asks you
192
+ for the number. The name cannot be one a provider already has (`anthropic`, `openai`, ...), so
193
+ no stored key can be pointed at another address. You can do the same yourself with
194
+ `pine model add <name> <address>` ([operations.md](operations.md)); what is written is described
195
+ in [configuration.md](configuration.md), "models.json".
196
+
197
+ ## Creating an agent
198
+
199
+ Ask the main agent: "create an agent that keeps my books". It calls `create_agent` with an id,
200
+ one line on what the agent is for, its instructions, and optionally a model and a list of
201
+ built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`; all of them by default).
202
+ What cannot work (a bad id, a name that is taken, an unknown tool or model) is said before you
203
+ are asked anything. After your yes:
204
+
205
+ ```
206
+ agents/books/
207
+ agent.json { "description": "...", "tools": [...] } and "model" if one was named
208
+ workspace/
209
+ AGENTS.md the instructions; the new agent can change them itself from then on
210
+ SOUL.md a stub
211
+ MEMORY.md a stub
212
+ ```
213
+
214
+ Nothing else is written into `agent.json`; every other setting is pine's default. The agent
215
+ exists at once: it is in the terminal UI's agent list (`/agent books`), `pine send books ...`
216
+ reaches it, and the main agent can hand it work with `delegate`. It starts with no MCP servers
217
+ and no event sources of its own, and sets those up itself when you ask it to.
218
+
219
+ ## The main agent administers pine
220
+
221
+ The point of pine is that nobody has to edit its configuration, you included. The main agent
222
+ is the administrator: it has tools for everything that can be set up, each tool takes a few
223
+ named values and checks them, what it writes is read back through the same loader pine starts
224
+ with, and a change that does not load is undone. So a wrong value is an error message to the
225
+ agent, not a pine that does not start.
226
+
227
+ | What | Tools of the main agent |
228
+ |---|---|
229
+ | Agents | `agents` (list), `create_agent`, `update_agent`, `remove_agent` |
230
+ | What an agent has: event sources, subscriptions, MCP servers, skills, schedules | The tools every agent has for itself, with `agent` for another agent, and with `scope: "global"` for all agents |
231
+ | Types of event source, model servers | `add_source_type`, `remove_source_type`, `add_model_server`, `remove_model_server` |
232
+ | pine's settings | `settings` (list), `set_setting` |
233
+ | Routes: rules of your own in pine.json | `routes` (list), `add_route`, `remove_route` |
234
+
235
+ The ones only it has:
236
+
237
+ | Tool | Does |
238
+ |---|---|
239
+ | `agents` [`id`] | Lists the agents: what each is for, its model, reasoning, mode and reach, and what it has (conversations, event sources, MCP servers, schedules, skills, files in its workspace). With `id`, one agent in full, with its workspace and its instructions. Asks nobody. |
240
+ | `update_agent` `id` [`description`] [`instructions`] [`model`] [`thinking`] [`mode`] [`tools`] [`delegates`] [`scope`] [`network`] [`read`] [`write`] [`forget`] | Changes an agent's settings; only what is given changes. You see the change line by line and confirm it. See "Changing and removing an agent". |
241
+ | `remove_agent` `id` [`keep_files`] | Removes an agent for good, with everything it has. You see what goes and confirm it. See "Changing and removing an agent". |
242
+ | `settings` | Lists the settings it can change, with what is in force and what each means. Asks nobody. |
243
+ | `set_setting` `key` `value` | Changes one setting in `pine.json`; `"default"` takes the entry out. You see the old and the new value and confirm. See "pine's settings". |
244
+ | `agent`, `conversation` (parameters) | Every tool under event sources, MCP servers, skills and schedules above takes `agent`: the call is then done for that agent, as if it had made it in its main conversation. With `conversation`, for one of its conversations. See "The main agent administers pine". |
245
+
246
+ **For another agent.** "Add a schedule for books: every Monday at eight, sum up the week" is
247
+ one call of the main agent: `add_schedule` with `agent: "books"`. It is carried out by that
248
+ agent's own tool, under that agent's own rules, as if the agent had been asked in its main
249
+ conversation: the same checks, the same questions to you, the same entry in its `agent.json`.
250
+ The listing tools (`sources`, `mcp_servers`, `skills`, `schedules`) take `agent` too, which is
251
+ how the main agent sees what another agent has. Something that only one conversation of an
252
+ agent has is reached with `conversation` and its name. Taking something away from another
253
+ agent (`remove_source`, `remove_mcp_server`, `remove_skill`, `remove_schedule`, `unsubscribe`)
254
+ asks you every time, and the question says that the main agent asks.
255
+
256
+ **Not from a conversation that has read outside content.** `update_agent`, `remove_agent`,
257
+ `set_setting`, `add_route` and `remove_route` are refused there without a question to you: a web page that says "remove the
258
+ agent" must not get as far as your approval dialog. A new
259
+ conversation, or `/reset`, does it.
260
+
261
+ ## Changing and removing an agent
262
+
263
+ `update_agent` changes what is given and leaves the rest:
264
+
265
+ | Value | What it is |
266
+ |---|---|
267
+ | `description` | One line on what the agent is for |
268
+ | `instructions` | The whole new text of its `AGENTS.md`. It replaces the file, so the main agent reads the present text first (`agents` with `id`) |
269
+ | `soul` | The whole new text of its `SOUL.md`: who it is, its character and tone. It replaces the file the same way. This is what the main agent uses when you speak of an agent's personality or how it should sound |
270
+ | `model`, `thinking` | Its model (`"default"` for pine's default) and how much it reasons |
271
+ | `mode` | `auto` (no sandbox: its shell and file tools reach your whole account and the network), `safe` (in the sandbox: its own folders), `manual` (in the sandbox, every action waits), `bypass`, `plan`, or `default` for what pine gives an agent that names none. This is also how far its shell and file tools reach |
272
+ | `tools` | Its built-in tools, all of them: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` |
273
+ | `delegates` | The agents it may hand work to, all of them; `*` is every agent |
274
+ | `network` | Whether its shell may use the network when it works in the sandbox |
275
+ | `read`, `write`, `forget` | Folders outside its workspace that it may read, or read and change, from now on; and folders to take away again. This is how a folder is opened for an agent for good |
276
+
277
+ You see every line of the change before it is made, with a note where it gives the agent more
278
+ (the account, the network, bypass mode). It holds from the agent's next message on. pine's own
279
+ folder, pine's code and another agent's workspace are refused as folders. `pine agent update
280
+ <id>` does the same from a shell, each value a flag (`--model`, `--tools`, `--scope`, ...); a
281
+ model change needs a running daemon, which checks the model exists ([operations.md](operations.md)).
282
+
283
+ `remove_agent` takes an agent out of pine, and nothing of it is left. You are shown what goes
284
+ with it: its conversations, event sources, MCP servers, schedules, skills, the routes that wake
285
+ it, and how many files lie in its workspace. After your yes:
286
+
287
+ - its work is stopped, and each conversation, source, schedule, server and skill is removed the
288
+ way it would be removed one by one (a source stops, its secrets leave `.env`);
289
+ - the routes in `pine.json` that wake it are taken out, and they stop at once;
290
+ - the lists that name it are corrected: other agents' `delegates`, a server or source of all
291
+ agents that was only for some;
292
+ - what pine stored under its name goes: its tasks, the outside-content marks and answers of
293
+ its conversations, pins and open tabs, the recorded states of its folders, what its sources
294
+ kept;
295
+ - its folder `agents/<id>` (workspace, conversations, skills) and its private home
296
+ `sandbox/<id>` are deleted.
297
+
298
+ An agent of the same name made later starts from nothing. With `keep_files` the folder alone
299
+ is not deleted but moved to `removed/<id>-<time>` in pine's home, where nothing reads it. One
300
+ thing is left as it is: a workspace that you put outside pine's home, which is your folder.
301
+ What stays in any case is the past: the event log and pine's log name the agent where it
302
+ acted. The main agent cannot remove itself. `pine agent remove <id>` does the same from a
303
+ shell, with or without a running daemon ([operations.md](operations.md)).
304
+
305
+ ## Routes
306
+
307
+ A route is a rule of your own in `pine.json`: when an event arrives, and a condition holds,
308
+ write shared state, ask a model once, publish another event, or wake an agent
309
+ ([events.md](events.md)). Most wishes need none, because a subscription is a route pine makes
310
+ for you. The main agent has three tools for the ones you do want:
311
+
312
+ | Tool | Does |
313
+ |---|---|
314
+ | `routes` | Lists the routes: what each listens to, its condition, and what it does. Asks nobody. |
315
+ | `add_route` `name` `on` [`when`] [`agent` `prompt` `session`] [`set`] [`publish_topic` `publish_payload`] [`call_prompt` `call_system` `call_model`] [`throttle`] [`debounce`] [`trust`] | Adds a route. Each value is checked (a name that is free, an agent and a model that exist, JSON where JSON is wanted, a time, at least one thing to do, no topic that only pine publishes on). You see it line by line and confirm, and it acts from then on, without a restart. |
316
+ | `remove_route` `name` | Takes one out. You confirm; it stops at once. To change a route, remove it and add it again. |
317
+
318
+ `trust: "owner"` makes every event on the route count as your own words, which gives whoever
319
+ can cause such an event the agent's full tools. The question to you says so. Where a reply is
320
+ to go (`reply`), `whenBusy`, `priority` and `key` are not offered by the tool: write those in
321
+ `pine.json`. Like the other administration tools, the two that change something are refused in
322
+ a conversation that has read outside content.
323
+
324
+ ## pine's settings
325
+
326
+ `settings` lists what `set_setting` can change, with what is in force:
327
+
328
+ | Setting | What it is |
329
+ |---|---|
330
+ | `defaults.model`, `defaults.thinking`, `defaults.mode` | What an agent gets that does not say otherwise: model, reasoning, mode (and with the mode, how far it reaches) |
331
+ | `defaults.bashTimeoutSec`, `defaults.taskTimeoutSec` | Seconds a shell call and a task may run. From the next start |
332
+ | `limits.maxConcurrentRuns` | How many agents work at the same time. From the next start |
333
+ | `limits.maxDelegationDepth`, `limits.maxDownloadMb` | How often a task is handed on, and the largest download |
334
+ | `defaults.judge` | The model of the judge of goal mode. Not set: the agent's own |
335
+ | `security.askAccess` | Whether pine asks you itself when a call needs something outside the sandbox |
336
+ | `security.taint`, `security.bypassWhenTainted`, `security.approvalTimeout` | How long outside content counts, whether bypass survives it, and how long a question to you waits (from the next start) |
337
+
338
+ A value is checked for what it has to be (a model that exists, one of a few words, a number in
339
+ a range, a time), you see the old and the new value, and where the new one gives something up
340
+ the question says so. `"default"` as the value takes the entry out of `pine.json`. Most
341
+ settings hold at once; the ones marked hold from the next start of pine, and the agent tells
342
+ you so. Not settable by any agent: the control API (address, port, token) and secrets.
343
+
344
+ ## What is written
345
+
346
+ These are the only entries the tools make. A thing made for one conversation carries that
347
+ conversation's name as `session`, which is how pine knows whose it is and when to remove it.
348
+
349
+ ```jsonc
350
+ // agents/main/agent.json after: a server and a schedule for the agent, a source and a subscription for the conversation "taxes"
351
+ {
352
+ "description": "Your main agent",
353
+ "mcp": { "notes": { "url": "https://mcp.example.com/mcp", "approve": "tainted" } },
354
+ "sources": { "scans": { "type": "folder", "description": "what the scanner saves", "session": "taxes", "dir": "/Users/me/Scans" } },
355
+ "sandbox": { "read": ["/Users/me/Scans"] },
356
+ "subscribe": [{ "source": "scans", "note": "Say which document arrived.", "session": "taxes" }],
357
+ "schedules": [{ "name": "brief", "cron": "30 7 * * 1-5", "task": "Prepare the morning brief." }]
358
+ }
359
+ ```
360
+
361
+ Remove the conversation "taxes" and the source, the subscription and the read access are gone;
362
+ the file is as it was before, with the server and the schedule left. Rename the conversation and the entries
363
+ follow its new name.
364
+
365
+ A skill needs no entry at all. Where its folder lies says whom it is for:
366
+
367
+ ```
368
+ ~/.pine/
369
+ skills/<name>/ all agents
370
+ agents/<id>/skills/<name>/ that agent
371
+ agents/<id>/conversations/<session>/skills/<name>/ that one conversation
372
+ ```
373
+
374
+ Each holds a `SKILL.md` and the files that went along. Agents read these folders and cannot
375
+ write them; pine writes them when `add_skill` is called. Removing a skill deletes its folder,
376
+ and the folders above it that it leaves empty. `pine skills` lists every skill with whom it is
377
+ for.
378
+
379
+ ## What stays yours
380
+
381
+ The control API and its token, secrets in `.env`, a route's `reply`, local MCP servers that are to run
382
+ outside an agent's sandbox, the options of a server once it is added, and source types you
383
+ write yourself: these are changed in the files or with the `pine` command, and most need a
384
+ restart. Everything else the main agent changes for you. See [configuration.md](configuration.md),
385
+ [agents.md](agents.md), [mcp.md](mcp.md) and [sources.md](sources.md).