@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,310 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
Everything pine needs is in its home directory: `~/.pine` by default, or `$PINE_HOME`, or
|
|
4
|
+
`--home <dir>` on the command line.
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
~/.pine/
|
|
8
|
+
pine.json global settings, routes, schedules, global MCP servers and event sources
|
|
9
|
+
models.json optional: your own model servers, in pi's format
|
|
10
|
+
.env secrets, referenced from the JSON files as ${NAME}
|
|
11
|
+
auth.json provider credentials, written by `pine login`
|
|
12
|
+
USER.md what all agents know about you; in every agent's prompt, kept by the main agent
|
|
13
|
+
agents/
|
|
14
|
+
main/
|
|
15
|
+
agent.json this agent's settings
|
|
16
|
+
workspace/ its working folder, unless agent.json points elsewhere
|
|
17
|
+
AGENTS.md its purpose and how it works ┐ read into its prompt,
|
|
18
|
+
SOUL.md who it is │ written by the agent itself
|
|
19
|
+
MEMORY.md what should outlive a talk ┘ (agents.md)
|
|
20
|
+
AGENTS.md optional: rules of yours the agent cannot change
|
|
21
|
+
skills/ skills only this agent has
|
|
22
|
+
conversations/ what was set up for one conversation alone (its skills); made when needed
|
|
23
|
+
extensions/ pi extensions only this agent loads
|
|
24
|
+
sessions/ conversation history (written by pine)
|
|
25
|
+
skills/ skills for all agents; no entry needed (the main agent adds them with add_skill)
|
|
26
|
+
sources/ source types the main agent registered (pine's own copies)
|
|
27
|
+
sandbox/ per-agent private home and generated sandbox profiles (written by pine)
|
|
28
|
+
data/ event log, task queue, media, control token, files of event sources, the folder
|
|
29
|
+
states kept for undo, what is known of commands in the background, the
|
|
30
|
+
helper of app control (written by pine; closed to agents)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`pine check` validates names, references, paths, models and the entries of sources and
|
|
34
|
+
schedules, prints what each agent ends up with, and lists anything that
|
|
35
|
+
weakens the defences. Problems are reported together, each with the file it is in.
|
|
36
|
+
|
|
37
|
+
Paths in `pine.json` are relative to the home directory; paths in `agent.json` are relative to
|
|
38
|
+
that agent's folder. `~` works in both.
|
|
39
|
+
|
|
40
|
+
## Secrets
|
|
41
|
+
|
|
42
|
+
Write `${NAME}` or `${NAME:-fallback}` anywhere in a string in `pine.json` or `agent.json`.
|
|
43
|
+
Values come from `<home>/.env` first, then from the environment of the daemon. A missing
|
|
44
|
+
variable without a fallback is a configuration error.
|
|
45
|
+
|
|
46
|
+
`.env` is read by pine only. Its values are not exported to the daemon's environment, so
|
|
47
|
+
agent shells and MCP servers do not inherit them; they are also removed from events, messages
|
|
48
|
+
and log lines if they ever appear there (values of 8 characters or more). Keep the file at
|
|
49
|
+
mode 600 (`pine init` sets that).
|
|
50
|
+
|
|
51
|
+
pine writes to `.env` itself in one case: when an agent sets up an event source that has a
|
|
52
|
+
password or secret, the value is stored there as `PINE_SOURCE_<NAME>_<AGENT>_<OPTION>` (without
|
|
53
|
+
the agent for a source of all agents), and the configuration holds only the `${...}` reference.
|
|
54
|
+
Removing the source removes the entry. See [sources.md](sources.md).
|
|
55
|
+
|
|
56
|
+
The key of a model server of your own goes there too, as `PINE_MODEL_<NAME>_API_KEY` when pine
|
|
57
|
+
asked you for it (`pine model add`, `add_model_server`); `models.json` names it as `"apiKey":
|
|
58
|
+
"$NAME"`, see [models.json](#modelsjson).
|
|
59
|
+
|
|
60
|
+
## pine.json
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"main": "main",
|
|
65
|
+
"logLevel": "info",
|
|
66
|
+
"defaults": { "model": "local/deepseek-v4.1-flash", "thinking": "off" },
|
|
67
|
+
"limits": { "maxConcurrentRuns": 2 },
|
|
68
|
+
"security": { "approvalTimeout": "5m" },
|
|
69
|
+
"http": { "host": "127.0.0.1", "port": 7463, "hooks": {} },
|
|
70
|
+
"mcp": {},
|
|
71
|
+
"sources": {},
|
|
72
|
+
"sourceTypes": {},
|
|
73
|
+
"subscribe": [],
|
|
74
|
+
"extensions": [],
|
|
75
|
+
"skills": [],
|
|
76
|
+
"routes": [],
|
|
77
|
+
"schedules": []
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
| Key | Default | Meaning |
|
|
82
|
+
|---|---|---|
|
|
83
|
+
| `main` | none | Id of the main agent. It may delegate to every other agent unless its `agent.json` says otherwise, and it is the only one that can create agents and set things up for all agents ([setup.md](setup.md)). Without this key, the agent called `main` (or else the first one) has those setup rights, but nobody delegates by default. |
|
|
84
|
+
| `logLevel` | `info` | `debug`, `info`, `warn`, `error`, `silent`. Logs go to stderr; a daemon started inside the terminal UI logs to `data/pine.log`. |
|
|
85
|
+
| `dataDir` | `data` | Where the database, media and control token live. |
|
|
86
|
+
| `defaults.model` | none | `provider/model-id` from `models.json`: the model of every agent whose `agent.json` names none. There is no built-in fallback: an agent with neither is a configuration error, which `pine check` and the start of pine report. |
|
|
87
|
+
| `defaults.judge` | not set | The model of the judge of goal mode (`/goal`), as `provider/model-id`. Not set: the agent's own model. A second, small model keeps the judge's call from pushing the agent's conversation out of a model server's cache. See "Goal mode" in [agents.md](agents.md). |
|
|
88
|
+
| `defaults.thinking` | `off` | Reasoning level for models that can reason: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
|
|
89
|
+
| `defaults.mode` | not set | The mode of every agent that names none: `auto`, `safe`, `manual`, `bypass` or `plan` (see `mode` below). Not set: `auto` for the main agent, `safe` for all others. Set it to `safe` to keep every agent, the main one too, in its sandbox. See "Modes" in [security.md](security.md). |
|
|
90
|
+
| `defaults.bashTimeoutSec` | `900` | Longest a shell command may run (15 minutes: a build, an install). The model cannot raise it. A server or another program that should keep running, and whatever needs longer, is started in the background, which is not held to it ([coding.md](coding.md)). |
|
|
91
|
+
| `defaults.taskTimeoutSec` | `7200` | Longest a task may run before it is aborted (two hours). |
|
|
92
|
+
| `defaults.idleMs` | `15m` | A live session without work is closed after this (and resumed from disk later). |
|
|
93
|
+
| `defaults.settings` | `{}` | pi settings applied to every agent, for example `{ "compaction": { "reserveTokens": 8000 } }`. They are put on top of pi's own settings files and stay in force when pi reads those files again. |
|
|
94
|
+
| `limits.maxConcurrentRuns` | `2` | Model slots: how many runs talk to the model server at once. Match it to the server's parallel slots. |
|
|
95
|
+
| `limits.maxDelegationDepth` | `3` | How deep a chain of delegations may go. |
|
|
96
|
+
| `limits.maxDownloadMb` | `200` | Largest file the `download` tool fetches. |
|
|
97
|
+
| `limits.maxEventHops` | `8` | Events further than this from an outside trigger are not routed. |
|
|
98
|
+
| `limits.maxQueuedPerAgent` | `50` | New tasks are refused when an agent has this many waiting. |
|
|
99
|
+
| `limits.maxEventChars` | `20000` | Longest text of an untrusted event in a prompt (at least 1000). Your own messages and delegated tasks are cut at ten times this. |
|
|
100
|
+
| `limits.modelHeadersTimeoutMs` | `10m` | How long the model server may take to start answering. |
|
|
101
|
+
| `limits.modelStreamIdleMs` | `5m` | How long a started answer may go silent before the request is dropped. |
|
|
102
|
+
| `limits.eventRetentionDays` | `30` | Older events are deleted, and so are the copies kept of conversations that were reset. |
|
|
103
|
+
| `limits.conversationDays` | `7` | A conversation in which nothing was said for this long is removed with its history, unless it is an agent's main conversation, pinned, open in a tab, subscribed to an event source, or has a schedule of its own. `0`: never. |
|
|
104
|
+
| `limits.goalRounds` | `20` | Goal mode (`/goal`): how many rounds a goal gets before it stops and waits for `/goal resume`, which gives it as many again. A round is a whole turn of the agent with all its tool calls, so twenty are hours on a local model. See "Goal mode" in [agents.md](agents.md). |
|
|
105
|
+
| `limits.goalIdleRounds` | `3` | Goal mode: after this many rounds in a row that the judge called "not met" and in which the agent made no tool call, the goal is paused: the agent is going in circles. `0`: never. |
|
|
106
|
+
| `limits.goalJudgeTimeout` | `90s` | Goal mode: how long the judge may take to answer. When it takes longer, that counts as no verdict, and the goal is paused. |
|
|
107
|
+
| `security.approvalTimeout` | `5m` | An unanswered approval request counts as "no" after this. |
|
|
108
|
+
| `security.taint` | `session` | How long a session stays tainted: until reset (`session`), until the task ends (`run`), or never (`off`). See [security.md](security.md). |
|
|
109
|
+
| `security.taintTools` | `[]` | Tool name globs whose results count as outside content, besides MCP servers marked `taints`. |
|
|
110
|
+
| `security.bypassWhenTainted` | `false` | Keep bypass mode in force in a session that has read outside content. Off, bypass is paused in such a session, and the agent works as in `auto` mode. |
|
|
111
|
+
| `security.askAccess` | `true` | pine asks you itself when a call of an agent in the sandbox (`safe` or `manual` mode) needs a file or folder outside it, or the network: before a file tool or a shell command that names it, and on macOS after a command the sandbox refused something. `false`: you are only asked when the agent calls `request_access`. See "When a call needs something outside" in [security.md](security.md). |
|
|
112
|
+
| `http` | on, loopback, port 7463 | Control API and webhooks. `false` turns it off (the CLI's client commands then do not work). |
|
|
113
|
+
| `http.host`, `http.port` | `127.0.0.1`, `7463` | Where the control API listens. Anything but loopback is reported by `pine check`. |
|
|
114
|
+
| `http.token` | generated | Bearer token of the control API. When unset, pine generates one into `data/http-token`. |
|
|
115
|
+
| `http.hooks.<name>` | none | A webhook at `POST /hook/<name>`: `{ "secret": "...", "topic": "hook/<name>" }`, or `"open": true` instead of a secret to accept anyone who can reach the port. See [events.md](events.md). For a webhook an agent subscribes to, use a `webhook` source instead. |
|
|
116
|
+
| `mcp` | `{}` | Global MCP servers. See [mcp.md](mcp.md). |
|
|
117
|
+
| `sources` | `{}` | Event sources every agent can subscribe to. See [sources.md](sources.md). |
|
|
118
|
+
| `sourceTypes` | `{}` | Source types of your own: a name and the module that implements it, e.g. `{ "doorbell": "./sources/doorbell.ts" }`. The module says which options it takes, and agents can then set up sources of that type by tool call. The main agent adds entries here with `add_source_type`, pointing at the copy pine keeps in `sources/` of its home. |
|
|
119
|
+
| `subscribe` | `[]` | Subscriptions for all agents: every agent that can use the source is woken in its main conversation. |
|
|
120
|
+
| `extensions` | `[]` | Paths of pi extensions loaded into every agent's sessions. |
|
|
121
|
+
| `skills` | `[]` | Further folders of skills for every agent, for skills that lie outside pine's home. Not needed for `skills/` in pine's home: what is there is for every agent without an entry, and so is what the main agent adds with `add_skill`. Agents cannot replace or remove a skill that is named here. |
|
|
122
|
+
| `routes` | `[]` | See [events.md](events.md). |
|
|
123
|
+
| `schedules` | `[]` | What happens at a time. One with a `task` wakes every agent with it; one without only publishes an event. The main agent adds entries with `add_schedule`. See [events.md](events.md). |
|
|
124
|
+
|
|
125
|
+
Three things that older setups had are configuration errors now, each reported with what to
|
|
126
|
+
write instead: a `plugins` list that is not empty, an event source of `"type": "timer"`
|
|
127
|
+
(that is a schedule), and one of `security.review`, `security.reviewer`,
|
|
128
|
+
`security.reviewTimeout` or `security.rules` (pine has no reviewer any more: take the entry
|
|
129
|
+
out).
|
|
130
|
+
|
|
131
|
+
Durations are a number of milliseconds or a string such as `"90s"`, `"15m"`, `"2h"`, `"1d"`.
|
|
132
|
+
|
|
133
|
+
## agent.json
|
|
134
|
+
|
|
135
|
+
Every key is optional; `{}` is a valid agent.
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"description": "Contract law; knows the case files",
|
|
140
|
+
"workspace": "~/dev/gonzo",
|
|
141
|
+
"model": "local/deepseek-v4.1-flash",
|
|
142
|
+
"tools": ["read", "bash", "edit", "write", "grep", "find", "ls"],
|
|
143
|
+
"mcp": { "library": { "command": "library-mcp" } },
|
|
144
|
+
"globalMcp": ["web"],
|
|
145
|
+
"delegates": [],
|
|
146
|
+
"subagents": { "maxParallel": 3 },
|
|
147
|
+
"sandbox": { "network": false, "read": ["~/Documents/law-library"] }
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Identity and model
|
|
152
|
+
|
|
153
|
+
| Key | Default | Meaning |
|
|
154
|
+
|---|---|---|
|
|
155
|
+
| `description` | empty | One line other agents see when they choose whom to delegate to. Write it for them. |
|
|
156
|
+
| `workspace` | `agents/<id>/workspace` | The agent's working folder. `AGENTS.md`, `SOUL.md` and `MEMORY.md` at its top are the agent's instructions and are loaded into its prompt. Must exist when you set it. |
|
|
157
|
+
| `context` | `[]` | Further instruction files to load into the system prompt. |
|
|
158
|
+
| `model`, `thinking` | from `defaults` | Per-agent model and thinking level. |
|
|
159
|
+
| `settings` | from `defaults.settings` | pi settings for this agent, key by key on top of `defaults.settings`. `agents/<id>/settings.json` is honoured as well; where both set a key, the one here counts. |
|
|
160
|
+
| `taskTimeoutSec`, `idleMs` | from `defaults` | Per-agent overrides. |
|
|
161
|
+
|
|
162
|
+
### Tools and extensions
|
|
163
|
+
|
|
164
|
+
| Key | Default | Meaning |
|
|
165
|
+
|---|---|---|
|
|
166
|
+
| `tools` | `read`, `bash`, `edit`, `write` | Which of pi's built-in tools the agent gets: any of `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. |
|
|
167
|
+
| `mcp` | `{}` | MCP servers only this agent has. An entry with the name of a global server replaces it for this agent. An entry with `"session": "<conversation>"` was added for that conversation alone and is removed with it ([setup.md](setup.md)). |
|
|
168
|
+
| `globalMcp` | `true` | `true`: every global server that includes this agent. `false`: none. A list of names: exactly those. |
|
|
169
|
+
| `sources` | `{}` | Event sources only this agent can subscribe to. An entry with `"session": "<conversation>"` was set up for that conversation alone and is removed with it. See [sources.md](sources.md). |
|
|
170
|
+
| `subscribe` | `[]` | What this agent is subscribed to: a list of names, an object with `note`, `when`, `throttle`, `debounce`, `separate`, `prompt` per source, or a list of entries with `source` and, for one conversation only, `session`. The agent's `subscribe` tool and `pine subscribe` write here. Every key is in [sources.md](sources.md), "In the configuration". |
|
|
171
|
+
| `schedules` | `[]` | What this agent does at set times: `{ "name", "cron" or "every" or "at", "task" }`, with `"session": "<conversation>"` for one conversation. The agent adds entries with `add_schedule`. See [events.md](events.md). |
|
|
172
|
+
| `extensions`, `skills` | `[]` | Further pi extension files and skill folders for this agent. Its own `skills/` folder needs no entry. |
|
|
173
|
+
| `bashTimeoutSec` | from `defaults` | Longest shell command. |
|
|
174
|
+
| `bashDeny` | `[]` | Regular expressions; a shell command matching one is refused. A convenience, not a boundary: the sandbox is the boundary. |
|
|
175
|
+
|
|
176
|
+
### Working with other agents
|
|
177
|
+
|
|
178
|
+
| Key | Default | Meaning |
|
|
179
|
+
|---|---|---|
|
|
180
|
+
| `delegates` | `["*"]` for the agent that `main` in `pine.json` names, else `[]` | Agents this one may hand tasks to. |
|
|
181
|
+
| `subagents` | on, 4 in parallel | `false`, or `{ "maxParallel": 4, "tools": [...], "mcp": true }`. `tools` narrows what sub-agents get. |
|
|
182
|
+
| `publish` | `[]` | Topic patterns the `publish_event` tool may publish on. Empty: the agent has no such tool. |
|
|
183
|
+
| `state.read` | `["#"]` | State keys the agent may read. |
|
|
184
|
+
| `state.write` | `["agent/<id>/#"]` | State keys the agent may write. |
|
|
185
|
+
| `state.inject` | `[]` | State keys shown to the agent in every turn. |
|
|
186
|
+
|
|
187
|
+
### Containment
|
|
188
|
+
|
|
189
|
+
| Key | Default | Meaning |
|
|
190
|
+
|---|---|---|
|
|
191
|
+
| `mode` | `auto` for the main agent, `safe` for others (or `defaults.mode`) | How much the agent does without asking, and whether its shell and file tools run in a sandbox. `auto`: no sandbox; your whole user account and the network, like you at your terminal, with your home folder and environment; a critical action asks you, and after outside content so does sending something out. `safe`: in the sandbox; its own folders and what you grant, and the same questions. `manual`: in the sandbox, and every action waits for approval. `bypass`: no sandbox, and never asks. `plan`: looks, reads and asks, changes nothing, and answers with a plan. pine's home stays closed in every mode. See "Modes" and "The whole account" in [security.md](security.md). |
|
|
192
|
+
| `sandbox.network` | `false` | Shell commands may use the network: the internet and your local network, ports of this machine included. See [security.md](security.md), "On Linux", for what that means for socket files. |
|
|
193
|
+
| `sandbox.read`, `sandbox.write` | `[]` | Further folders the agent may read / write, besides its workspace. |
|
|
194
|
+
| `sandbox.sharedTmp` | `true` | Allow `/tmp` and the user's temp folder. |
|
|
195
|
+
| `sandbox.env` | `{}` | Extra environment variables for the agent's shell. Do not put secrets here; the agent can read them. |
|
|
196
|
+
| `trustWorkspace` | `false` | `true` lets pi load `.pi/extensions`, `.pi/settings.json` and skills from the workspace. That is code execution inside the daemon for whoever can write there, the agent included. |
|
|
197
|
+
| `approve` | `[]` | Tool calls that always need your approval: `"tool"` or `"tool:argument-glob"`, for example `"bash:*git push*"`. |
|
|
198
|
+
| `approveWhenTainted` | `["publish_event", "send"]` | Tool calls that count as sending something out. Once the session has seen outside content they need your approval. |
|
|
199
|
+
| `untrusted` | read-only profile | What a run started by an untrusted event may use: `{ "tools": ["read","grep","find","ls"], "mcp": [], "delegates": [], "publish": [], "stateWrite": false, "subagents": false }`. `false` refuses such runs. |
|
|
200
|
+
|
|
201
|
+
## models.json
|
|
202
|
+
|
|
203
|
+
This is pi's own file; pine passes it through. It is only needed for model servers of your own:
|
|
204
|
+
pi already knows the hosted providers (OpenCode, Anthropic, OpenAI and many more), and
|
|
205
|
+
`pine login <provider>` supplies their credentials. `pine init` writes two providers: `dev`
|
|
206
|
+
(Claude through `claude -p`, served by `pine dev-model`; the example's `defaults.model` is
|
|
207
|
+
`dev/claude-haiku`) and `local` for llama.cpp.
|
|
208
|
+
|
|
209
|
+
You do not have to write an entry yourself: `pine model add <name> <address>` asks the server
|
|
210
|
+
what it serves and writes it ([operations.md](operations.md), "With a model server of your
|
|
211
|
+
own"), and the main agent does the same with `add_model_server` ([setup.md](setup.md)). What
|
|
212
|
+
they write looks like the `local` entry:
|
|
213
|
+
|
|
214
|
+
```json
|
|
215
|
+
{
|
|
216
|
+
"providers": {
|
|
217
|
+
"local": {
|
|
218
|
+
"name": "llama-server",
|
|
219
|
+
"baseUrl": "http://127.0.0.1:8080/v1",
|
|
220
|
+
"api": "openai-completions",
|
|
221
|
+
"apiKey": "none",
|
|
222
|
+
"models": [
|
|
223
|
+
{
|
|
224
|
+
"id": "deepseek-v4.1-flash",
|
|
225
|
+
"contextWindow": 65536,
|
|
226
|
+
"maxTokens": 8192,
|
|
227
|
+
"input": ["text"],
|
|
228
|
+
"reasoning": true,
|
|
229
|
+
"cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
|
|
230
|
+
"compat": { "supportsStore": false, "supportsDeveloperRole": false, "maxTokensField": "max_tokens", "thinkingFormat": "deepseek" }
|
|
231
|
+
}
|
|
232
|
+
]
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
- Refer to a model as `provider/id`, here `local/deepseek-v4.1-flash`.
|
|
239
|
+
- `contextWindow` must match what the server was started with (`-c`), or compaction triggers at
|
|
240
|
+
the wrong time.
|
|
241
|
+
- Add `"image"` to `input` only for a model that accepts images; agents then receive the
|
|
242
|
+
pictures that Telegram and watched folders deliver.
|
|
243
|
+
- The `compat` flags stop pi from sending fields a plain llama-server may reject. They have not
|
|
244
|
+
been verified against a real llama-server yet; see [stack.md](stack.md).
|
|
245
|
+
- pi's documentation for this file is in
|
|
246
|
+
`node_modules/@earendil-works/pi-coding-agent/docs/models-configuration.md`.
|
|
247
|
+
|
|
248
|
+
### Thinking levels
|
|
249
|
+
|
|
250
|
+
pine's reasoning levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`
|
|
251
|
+
(`/reasoning` in the terminal UI, `thinking` in `agent.json`). A model on a server of your own
|
|
252
|
+
rarely knows all of them. A chat template answers a level it does not know with its own
|
|
253
|
+
default, which is often its highest, and without an entry for `off` nothing is sent at all, so
|
|
254
|
+
thinking stays on.
|
|
255
|
+
|
|
256
|
+
For llama.cpp, `pine model add` and `add_model_server` settle this from what the server
|
|
257
|
+
reports (`chat_template_caps` in `/props`: whether the template takes a level, and which levels
|
|
258
|
+
it tells apart). They write, for a model whose template knows `low` and `medium`:
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
"reasoning": true,
|
|
262
|
+
"thinkingLevelMap": { "off": "none", "minimal": "low", "low": "low", "medium": "medium" },
|
|
263
|
+
"compat": { "thinkingFormat": "openai", "supportsReasoningEffort": true, ... }
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
- `"thinkingFormat": "openai"` makes pi send the level as `reasoning_effort`, which is the
|
|
267
|
+
field llama.cpp hands to the chat template. Formats that only send thinking on or off (such
|
|
268
|
+
as `qwen-chat-template`) lose the level.
|
|
269
|
+
- `off` is sent as `none`, which is how llama.cpp turns thinking off.
|
|
270
|
+
- A level the template knows is sent as it is. One it does not know is sent as the next level
|
|
271
|
+
up that it does know, so you never get less thinking than you asked for: with `low`,
|
|
272
|
+
`medium` and `xhigh`, pine's `high` is sent as `xhigh`.
|
|
273
|
+
- A level above everything the template knows has no entry. pi lowers `xhigh` and `max` to
|
|
274
|
+
the highest level there is; `high` is sent as it is, and the template answers with its own
|
|
275
|
+
default.
|
|
276
|
+
|
|
277
|
+
For a server that does not report this (vLLM, LM Studio), `--reasoning` only marks the model as
|
|
278
|
+
thinking; write a `thinkingLevelMap` by hand if its levels differ.
|
|
279
|
+
|
|
280
|
+
### A server that wants a key
|
|
281
|
+
|
|
282
|
+
A model server that was started with a key (llama-server with `--api-key`, a server behind a
|
|
283
|
+
proxy) gets it from `.env`. `pine model add` and `add_model_server` do this themselves: they
|
|
284
|
+
ask you for the key and store it as `PINE_MODEL_<NAME>_API_KEY`. By hand, name it in
|
|
285
|
+
`models.json` and put the value into `<home>/.env`:
|
|
286
|
+
|
|
287
|
+
```json
|
|
288
|
+
"studio": {
|
|
289
|
+
"baseUrl": "http://100.64.0.7:8080/v1",
|
|
290
|
+
"api": "openai-completions",
|
|
291
|
+
"apiKey": "$STUDIO_API_KEY",
|
|
292
|
+
"models": [ ... ]
|
|
293
|
+
}
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
```
|
|
297
|
+
STUDIO_API_KEY=...
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
- `$NAME` and `${NAME}` both work; `$$` is a dollar sign. This is pi's way of writing it, which
|
|
301
|
+
is why there is no `${NAME:-fallback}` here.
|
|
302
|
+
- pine fills the key in when it starts and gives it to pi in memory. It is not written to a
|
|
303
|
+
file and not put into the daemon's environment, so agent shells and MCP servers never see it.
|
|
304
|
+
A change to `.env` takes effect with the next start.
|
|
305
|
+
- A name that is neither in `.env` nor in the daemon's environment does not stop pine: the
|
|
306
|
+
provider's models are missing from `/model`, the log says which name is missing when pine
|
|
307
|
+
starts, and `pine check` lists it under "Model notes".
|
|
308
|
+
- Only `apiKey` is filled in from `.env`. A `$NAME` in `headers` is read by pi from the
|
|
309
|
+
daemon's environment; `pine check` says so when a header names an `.env` entry.
|
|
310
|
+
- `"apiKey": "none"` (or any text without a `$`) is sent as it is, for a server without a key.
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
# Events, routes and schedules
|
|
2
|
+
|
|
3
|
+
> To let an agent react to a folder, a device or a web request, you usually do not need this
|
|
4
|
+
> page: ask it, or configure a [source](sources.md) and have the agent subscribe. To have it do
|
|
5
|
+
> something at a time, ask it too: see "Schedules" below. Routes are for rules of your own:
|
|
6
|
+
> setting state, chaining events, single model calls.
|
|
7
|
+
|
|
8
|
+
## Topics
|
|
9
|
+
|
|
10
|
+
A topic is a slash-separated name. Patterns use `+` for exactly one level and `#` for the rest:
|
|
11
|
+
|
|
12
|
+
| Pattern | Matches |
|
|
13
|
+
|---|---|
|
|
14
|
+
| `cam/front/motion` | only that topic |
|
|
15
|
+
| `cam/+/motion` | `cam/front/motion`, `cam/back/motion` |
|
|
16
|
+
| `source/#` | everything below `source`, and `source` itself |
|
|
17
|
+
| `#` | everything |
|
|
18
|
+
|
|
19
|
+
Where events come from:
|
|
20
|
+
|
|
21
|
+
| Source | Topics | Trust |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| Webhook `POST /hook/<name>` | `hook/<name>` (or the hook's `topic`) | untrusted |
|
|
24
|
+
| Event sources ([sources.md](sources.md)) | `source/<name>/<event>`, or `source/<name>@<agent>/<event>` for an agent's own | untrusted; owner for a source whose entry says `"trust": "owner"` (`add_source` writes that for `telegram`, whose account you pair) |
|
|
25
|
+
| `pine emit`, `POST /events` | whatever you name | owner |
|
|
26
|
+
| Schedules | `timer/<name>`, or `timer/<name>@<agent>` for an agent's own | owner |
|
|
27
|
+
| Agents (`publish_event`) | topics in the agent's `publish` list | owner, or untrusted if the run was restricted |
|
|
28
|
+
| pine | `agent/...`, `state/...`, `approval/...`, `pine/...` | untrusted |
|
|
29
|
+
|
|
30
|
+
Watch them:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pine events -f
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pine events --topic "source/#" --limit 50
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Routes
|
|
41
|
+
|
|
42
|
+
A route is an entry in `routes` in `pine.json`. You can write it there yourself, or ask the main
|
|
43
|
+
agent: it lists, adds and removes routes with `routes`, `add_route` and `remove_route`
|
|
44
|
+
([setup.md](setup.md), "Routes"), checked and without a restart.
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"name": "front-door",
|
|
49
|
+
"on": "source/house/message",
|
|
50
|
+
"when": { "payload.topic": "house/door/front", "payload.value.open": true, "state.house/mode": "away" },
|
|
51
|
+
"throttleMs": "5m",
|
|
52
|
+
"agent": "house",
|
|
53
|
+
"prompt": "The front door was opened at {{time}} while the house is in away mode.",
|
|
54
|
+
"session": "new",
|
|
55
|
+
"reply": { "topic": "out/source/telegram" }
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Here `house` is an `mqtt` source and `telegram` a `telegram` source, both in `pine.json`
|
|
60
|
+
([sources.md](sources.md)). For a source an agent set up for itself the topic carries the
|
|
61
|
+
agent's name: `out/source/telegram@main`.
|
|
62
|
+
A route does not subscribe to anything, so a source it relies on needs `"start": "always"`
|
|
63
|
+
unless a conversation is subscribed to it anyway.
|
|
64
|
+
|
|
65
|
+
| Key | Meaning |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `name` | For logs and errors. Default `route<n>`. |
|
|
68
|
+
| `on` | A topic pattern or a list of them. |
|
|
69
|
+
| `when` | A filter; every entry must hold. See below. |
|
|
70
|
+
| `debounceMs` | Wait until no matching event has arrived for this long, then handle the last one. For bursts (a camera uploading five images). |
|
|
71
|
+
| `throttleMs` | Handle one event, then ignore matching ones for this long. For repeating alarms. |
|
|
72
|
+
| `key` | Template for what counts as "the same" for debounce and throttle. Default `{{topic}}`. |
|
|
73
|
+
| `set` | Write shared state: `{ "house/mode": "{{payload.value}}" }`. `null`, or a value that is exactly one `{{path}}` that finds nothing, deletes the key. |
|
|
74
|
+
| `publish` | Publish another event: `{ "topic": "...", "payload": {...} }`. Without `payload` the original payload is passed on; after a `call` it is `{ "text": <the answer>, "of": <the original payload> }`. |
|
|
75
|
+
| `call` | One model call: `{ "prompt": "...", "system": "...", "model": "provider/id" }`. Its answer is `{{result}}`. |
|
|
76
|
+
| `agent` | Give an agent a task. |
|
|
77
|
+
| `prompt` | The task text. Default: the payload's `text`, or the payload as JSON. |
|
|
78
|
+
| `session` | Session key template. Default `main`. `new` for one-off work. |
|
|
79
|
+
| `whenBusy` | `queue` (default): the task waits until the conversation is free. `steer`: if the conversation is working, the text is given to that work, which reads it at its next step; if that work ends first, it is done next as a task of its own. See "Sessions" in [agents.md](agents.md). |
|
|
80
|
+
| `priority` | Higher runs first when model slots are scarce. Default 10 for owner events, 0 otherwise. |
|
|
81
|
+
| `reply` | Where the agent's answer goes: `{ "topic": "...", "payload": {...} }`. Default: the event's own reply target. `false`: nowhere. |
|
|
82
|
+
| `trust` | Override the event's trust. `"owner"` gives events on this route the agent's full tool set: only for sources nobody else can write to. `pine check` lists such routes. |
|
|
83
|
+
|
|
84
|
+
A route needs at least one of `set`, `publish`, `call`, `agent`. They run in the order `set`,
|
|
85
|
+
`call`, `publish`, `agent`, so one route can classify with `call` and pass the result on with
|
|
86
|
+
`publish`. `call` and `agent` cannot be in the same route: publish the result and let a second
|
|
87
|
+
route start the agent, as in the example below.
|
|
88
|
+
|
|
89
|
+
### Templates
|
|
90
|
+
|
|
91
|
+
`{{path}}` is replaced in `prompt`, `session`, `key`, `set`, `publish`, `reply` and `call`.
|
|
92
|
+
|
|
93
|
+
| Path | Value |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `payload`, `payload.a.b` | The event's payload or a field of it |
|
|
96
|
+
| `topic`, `source`, `id`, `ts`, `time` | Event fields; `time` is local, `YYYY-MM-DD HH:MM:SS` |
|
|
97
|
+
| `state.<key>` | Shared state, for example `{{state.house/mode}}` |
|
|
98
|
+
| `result` | The answer of the route's `call` |
|
|
99
|
+
|
|
100
|
+
A value that is exactly one `{{path}}` keeps its type (a number stays a number); inside longer
|
|
101
|
+
text, objects become JSON and missing values become empty.
|
|
102
|
+
|
|
103
|
+
### Filters
|
|
104
|
+
|
|
105
|
+
`when` maps a path to a value (equality) or to conditions:
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"payload.value.temperature": { "gt": 30 },
|
|
110
|
+
"payload.value.room": { "in": ["kitchen", "boiler"] },
|
|
111
|
+
"payload.text": { "regex": "^alarm", "flags": "i" },
|
|
112
|
+
"state.house/mode": { "ne": "home" },
|
|
113
|
+
"payload.value.battery": { "exists": true }
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Conditions: `eq`, `ne`, `in`, `gt`, `gte`, `lt`, `lte`, `exists`, `contains`, `regex` (with
|
|
118
|
+
optional `flags`).
|
|
119
|
+
|
|
120
|
+
### The cheapest handler that is enough
|
|
121
|
+
|
|
122
|
+
A full agent turn costs seconds of model time. Most events do not need one.
|
|
123
|
+
|
|
124
|
+
```json
|
|
125
|
+
[
|
|
126
|
+
{ "on": "source/house/message", "when": { "payload.topic": "house/mode" }, "set": { "house/mode": "{{payload.value}}" } },
|
|
127
|
+
|
|
128
|
+
{ "on": "source/cam/added",
|
|
129
|
+
"debounceMs": "4s",
|
|
130
|
+
"call": { "system": "You look at one camera image. Answer in one line: PERSON, VEHICLE, ANIMAL or NOTHING, then a short description.",
|
|
131
|
+
"prompt": "Camera file {{payload.file}}" },
|
|
132
|
+
"publish": { "topic": "cam/classified", "payload": { "file": "{{payload.file}}", "verdict": "{{result}}" } } },
|
|
133
|
+
|
|
134
|
+
{ "on": "cam/classified",
|
|
135
|
+
"when": { "payload.verdict": { "regex": "^(PERSON|VEHICLE)" }, "state.house/mode": "away" },
|
|
136
|
+
"agent": "house", "session": "new",
|
|
137
|
+
"prompt": "Camera saw: {{payload.verdict}} ({{payload.file}}). The house is in away mode.",
|
|
138
|
+
"reply": { "topic": "out/source/telegram" } }
|
|
139
|
+
]
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The first route never calls the model. The second makes one call per burst of images (a `call`
|
|
143
|
+
receives the event's images if the model accepts them). Only a person or a vehicle while nobody
|
|
144
|
+
is home reaches an agent.
|
|
145
|
+
|
|
146
|
+
Text from untrusted events is prefixed for the agent with a line saying where it came from and
|
|
147
|
+
that it is data, and is cut at `limits.maxEventChars`. That line is a courtesy; the protection
|
|
148
|
+
is that the run has fewer tools (see [security.md](security.md)).
|
|
149
|
+
|
|
150
|
+
## Schedules
|
|
151
|
+
|
|
152
|
+
A schedule is something that happens because of the time: again and again, or once. It is the
|
|
153
|
+
fourth thing an agent can be given by asking, next to event sources, MCP servers and skills,
|
|
154
|
+
and it has the same three scopes ([setup.md](setup.md)).
|
|
155
|
+
|
|
156
|
+
### Ask the agent
|
|
157
|
+
|
|
158
|
+
> Every weekday at seven, check my mail and tell me on Telegram what matters.
|
|
159
|
+
|
|
160
|
+
> Remind me at five to call the dentist.
|
|
161
|
+
|
|
162
|
+
> In twenty minutes, look whether the build is through.
|
|
163
|
+
|
|
164
|
+
The agent calls its `add_schedule` tool with a name, the time and the task in its own words:
|
|
165
|
+
`cron` for set times ("every weekday at six in the evening" is `"0 18 * * 1-5"`), `every` for an
|
|
166
|
+
interval, `at` or `in` for a reminder that happens once. When it is time, it is woken with that
|
|
167
|
+
task, also when you are not there, and does it. What it starts
|
|
168
|
+
counts as your wish: the agent has its usual tools, and nothing is marked as outside content.
|
|
169
|
+
|
|
170
|
+
| Said | Who is woken | You are asked |
|
|
171
|
+
|---|---|---|
|
|
172
|
+
| in a side conversation | That conversation; the schedule goes when the conversation is removed | No |
|
|
173
|
+
| in the agent's main conversation, or "as an agent" | The agent's main conversation | Only from a side conversation |
|
|
174
|
+
| "all agents" | Every agent, each in its main conversation. Only the main agent can do this | Yes |
|
|
175
|
+
|
|
176
|
+
In a conversation that has read outside content you are asked in every case, and the dialog
|
|
177
|
+
shows the task: what a web page says must not become something that is done every hour.
|
|
178
|
+
|
|
179
|
+
| Tool | |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `schedules` | What is scheduled for this agent, in which conversation, and when each is next due. |
|
|
182
|
+
| `add_schedule` `name` `task` + one of `cron`, `every`, `at`, `in` [`scope`] | Schedules it. `cron`: set times; `every`: an interval, at least a minute; `at`: once, at a local time (`2026-12-24 17:00`); `in`: once, after this long (`20m`). |
|
|
183
|
+
| `remove_schedule` `name` | Ends one. This conversation's own goes without a question. |
|
|
184
|
+
|
|
185
|
+
A schedule that happens once removes itself when it has fired. A one-off, or a `cron` schedule
|
|
186
|
+
with a task, that was due while pine was not running is done once when pine starts again (a
|
|
187
|
+
`cron` time only if it lies no more than seven days back), and the agent is told that it comes
|
|
188
|
+
late. An `every` schedule simply starts counting again. `pine
|
|
189
|
+
schedules` lists everything that is scheduled.
|
|
190
|
+
|
|
191
|
+
A name is unique among all schedules; a task has at most 4000 characters; an interval an agent
|
|
192
|
+
sets is at least a minute; a time in the past is refused. In manual mode you are asked for
|
|
193
|
+
every `add_schedule` and `remove_schedule`.
|
|
194
|
+
|
|
195
|
+
### In the files
|
|
196
|
+
|
|
197
|
+
```json
|
|
198
|
+
"schedules": [
|
|
199
|
+
{ "name": "brief", "cron": "30 7 * * 1-5", "task": "Prepare the morning brief and send it to me on Telegram." },
|
|
200
|
+
{ "name": "dentist", "at": "2026-11-12T17:00", "task": "Remind me to call the dentist." },
|
|
201
|
+
{ "name": "printer-check", "every": "10m" }
|
|
202
|
+
]
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
In an `agent.json` this is that agent's schedule (add `"session": "<conversation>"` for one
|
|
206
|
+
conversation, otherwise its main one). In `pine.json` a schedule with a task wakes every
|
|
207
|
+
agent; one without a task only publishes an event.
|
|
208
|
+
|
|
209
|
+
| Key | Meaning |
|
|
210
|
+
|---|---|
|
|
211
|
+
| `name` | Required. Starts with a lowercase letter, then lowercase letters, digits, `-` and `_`; 40 characters at most. The event is published on `timer/<name>` (`timer/<name>@<agent>` for an agent's own) unless `topic` says otherwise. |
|
|
212
|
+
| `cron` | Five fields, local time: minute, hour, day of month, month, day of week (0 or 7 is Sunday). Lists, ranges and steps work: `*/15 8-18 * * 1-5`. |
|
|
213
|
+
| `every` | A fixed interval instead. |
|
|
214
|
+
| `at` | Once, at this local time. The entry is removed when it has fired. If pine was not running at that time, it fires when pine starts again, and the agent is told that it comes late. |
|
|
215
|
+
| `task` | What the agent is to do. Required in an `agent.json`. |
|
|
216
|
+
| `topic` | The topic the event is published on, instead of `timer/<name>`. |
|
|
217
|
+
| `session` | In an `agent.json`: the conversation that is woken. Default: the main one. |
|
|
218
|
+
| `payload` | Fields added to the event's payload (`name` and `scheduled` are always there; `late` when it comes late, `task` when it has one). |
|
|
219
|
+
| `catchUp` | For `cron`: fire once at startup if a time passed while the daemon was down (in the last seven days), marked as late. Default: `true` with a task, `false` without. (`at` always catches up; `every` never does.) |
|
|
220
|
+
|
|
221
|
+
### Schedules and routes
|
|
222
|
+
|
|
223
|
+
Every schedule also publishes an event, trusted as yours, so a route can act on it. For a
|
|
224
|
+
schedule without a task that is all it does:
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
{ "on": "timer/printer-check", "call": { "prompt": "..." } }
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
A route is the way to do something other than an agent's turn at a time: set state, publish,
|
|
231
|
+
or one model call without tools. For "wake the agent and let it do this", give the schedule a
|
|
232
|
+
task instead; no route is needed.
|
|
233
|
+
|
|
234
|
+
## Webhooks
|
|
235
|
+
|
|
236
|
+
```json
|
|
237
|
+
"http": { "hooks": { "doorbell": { "secret": "${DOORBELL_SECRET}" } } }
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
`POST http://127.0.0.1:7463/hook/doorbell` then publishes `hook/doorbell` with the request body
|
|
241
|
+
as payload (parsed JSON, or `{ "text": ... }`). The caller proves itself with either
|
|
242
|
+
|
|
243
|
+
- `Authorization: Bearer <secret>`, or
|
|
244
|
+
- an HMAC-SHA256 of the body with the secret, hex-encoded, in `X-Hub-Signature-256: sha256=<hex>`
|
|
245
|
+
(the GitHub convention) or `X-Signature`.
|
|
246
|
+
|
|
247
|
+
A hook needs a secret; `"open": true` instead of a secret accepts anyone who can reach the port
|
|
248
|
+
and is reported by `pine check`. Unknown hook names get 404. Each hook accepts at most 120
|
|
249
|
+
requests a minute and bodies up to 1 MB. Webhook events are untrusted even when the signature
|
|
250
|
+
is right: the signature says who sent it, not that its content is safe to obey.
|
|
251
|
+
|
|
252
|
+
To receive webhooks from outside your network, put a tunnel or reverse proxy in front and
|
|
253
|
+
forward only `/hook/`.
|
|
254
|
+
|
|
255
|
+
A hook here only publishes an event; a route decides what happens. For a webhook that wakes an
|
|
256
|
+
agent directly, use a source of type `webhook` ([sources.md](sources.md)): it answers under
|
|
257
|
+
`/hook/` too, while an agent is subscribed. A hook in `http.hooks` with the same name comes
|
|
258
|
+
first.
|
|
259
|
+
|
|
260
|
+
## When nothing happens
|
|
261
|
+
|
|
262
|
+
1. `pine events --topic "<pattern>"`: did the event arrive, and on which topic?
|
|
263
|
+
2. `pine tasks`: was a task created? `pine task <id>` shows its prompt, result and error.
|
|
264
|
+
3. `pine events --topic "pine/#"`: `pine/route-failed` carries the reason a route could not act,
|
|
265
|
+
for example an agent that refuses untrusted events or a full queue.
|
|
266
|
+
4. Daemon log (stderr): a line `dropped ... after N hops` means a loop was cut.
|
|
267
|
+
5. A filter that never matches is usually a wrong path: look at the real payload in step 1.
|