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