@pmndrs/pine 0.0.0-stage → 0.1.1

package/docs/references/mcp.md

@@ -0,0 +1,257 @@
+# MCP servers
+
+pi has MCP built in; pine decides which agent gets which server. Tools appear to the model as
+`mcp__<server>__<tool>`. Characters such as `-` in a server's name become `_` there: the server
+`home-link` offers `mcp__home_link__status`. Use the tool-name form in `approve`
+patterns; the server's own `taints` and `approve` settings apply either way.
+
+## Global and per agent
+
+Global servers go in `pine.json`:
+
+```json
+"mcp": {
+  "web":     { "pine": "web", "agents": ["scout"] },
+  "calendar": { "command": "npx", "args": ["-y", "some-calendar-mcp"], "env": { "TOKEN": "${CALENDAR_TOKEN}" } },
+  "docs":    { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }, "agents": ["main", "gonzo"] }
+}
+```
+
+Servers of one agent go in its `agent.json`:
+
+```json
+{ "mcp": { "library": { "command": "library-mcp", "args": ["--stdio"] } } }
+```
+
+Who gets what:
+
+| Setting | Effect |
+|---|---|
+| `agents` on a global server | Which agents get it. Default: all (`["*"]`). |
+| `globalMcp: true` in `agent.json` (default) | The agent gets every global server that includes it. |
+| `globalMcp: false` | No global servers. |
+| `globalMcp: ["web"]` | Exactly these global servers, whether or not their `agents` list names this agent. |
+| A server in `agent.json` with a global server's name | Replaces the global one for this agent (an entry with `"enabled": false` does not: the global server stays). |
+| `"enabled": false` | Switches a server off without deleting it. |
+
+`pine check` prints the resulting list per agent.
+
+## Adding a server
+
+Three ways, all ending in the same entry in `pine.json` (for everyone) or an `agent.json`:
+
+**Ask an agent.** "Connect this MCP server: https://mcp.example.com/mcp". The agent calls
+`add_mcp_server`; you get an approval dialog with the name, the URL and who gets it. Said just
+like that, it is for the conversation you are in: only that conversation has the server's
+tools, and the server is removed with the conversation (in an agent's main conversation it is
+the agent's, in all its conversations). Say "for you as an agent" to keep it for the agent from
+any conversation, and ask the **main agent** for "all agents": only it can add or remove a
+server for everyone. `remove_mcp_server` takes a server out again. See [setup.md](setup.md).
+If you allow it, the server is written to the configuration and its tools are there from your
+next message, without a restart. This works for remote servers (an https URL) only: a local
+server is a program that runs with your rights, and that stays something you add yourself. The
+question comes in every mode, bypass included, because it changes pine itself.
+
+Your yes makes it a server of yours: using it does not mark the conversation as having read
+outside content. It is written with `"approve": "tainted"`, which only matters after the
+conversation has read something from outside (a web page, say): from then on the server's tools
+that act ask each time, until you answer "Always here" in that dialog, which settles it for the
+conversation. Its
+read-only tools never ask. If the server itself returns other people's text (mail, tickets, a
+web search), add `"taints": true` to its entry; if you want no questions at all, remove
+`approve`.
+
+**From a shell.**
+
+```bash
+pine mcp add docs https://mcp.example.com/mcp
+```
+
+```bash
+pine mcp add library --agent gonzo -- /usr/local/bin/library-mcp --stdio
+```
+
+Options: `--agent <id>` (only that agent), `--taints`, `--approve always|tainted`,
+`--timeout <seconds>`, `--description "..."`, `--exposure direct|codemode|deferred|hidden`.
+`pine mcp list --offline` lists without connecting. A remote server needs an https URL (http only for
+`localhost`). If a daemon is running the change applies at once; otherwise at the next start.
+`pine mcp remove <name>` takes it out again (`--agent <id>` for one in an `agent.json`), and
+`pine mcp list` shows every server, who gets it, and whether it connects:
+
+```
+notes          needs sign-in    all: main
+               https://gateway.example/d/abc/mcp  [outside content]  [approval: tainted]
+web            connected        all: main
+               bundled: web  [outside content]
+```
+
+**By hand.** Edit the file as described below, run `pine check`, restart.
+
+## Signing in (OAuth)
+
+A remote server that answers "unauthorized" and supports OAuth needs you to sign in once:
+
+```bash
+pine mcp login notes
+```
+
+or `/mcp login notes` in the terminal UI. Your browser opens the server's sign-in page; when
+you approve, pine stores the tokens in `data/pi/mcp-auth.json` (closed to agents) and refreshes
+them on its own afterwards. Open conversations get the server's tools from their next message.
+`pine mcp logout <name>` deletes the tokens.
+
+The sign-in is pi's: it follows the server's OAuth metadata and registers itself as a client.
+For servers that need a pre-registered client or a particular client name, add an `oauth`
+block to the entry (`clientId`, `clientSecret`, `callbackPort`, `clientName`,
+`clientRegistration`); pi's `docs/mcp.md` describes each. A server that takes a fixed token
+instead needs no sign-in: put `"headers": { "Authorization": "Bearer ${TOKEN}" }` in the entry
+and the token in `.env`.
+
+## Server entries
+
+An entry has the shape of an `mcpServers` entry in pi's `mcp.json`:
+
+| Key | Meaning |
+|---|---|
+| `command`, `args`, `env`, `cwd` | A local server started as a child process (stdio). |
+| `url`, `headers` | A remote server (streamable HTTP). |
+| `exposure` | How tools reach the model. pine's default is `direct`: every tool is declared. `codemode` offers one scripting tool instead, `deferred` makes tools searchable, `hidden` hides them. Use `deferred` or `codemode` for servers with dozens of tools. |
+| `toolExposure` | Per-tool override, for example `{ "delete_*": "hidden" }`. |
+| `description` | One sentence for the model about what the server offers. |
+| `url` (remote servers) | Also decides where the `download` tool fetches from without asking: addresses on the same scheme, host and port. A server that hands out download links for its files on its own host works with it out of the box. |
+| `timeout` | Seconds one call to this server may take before the agent is told it timed out. Default 60. Raise it for a server with slow tools, e.g. `"timeout": 180`. |
+
+and the keys pine adds (besides `agents` and `enabled` from the table at the top):
+
+| Key | Meaning |
+|---|---|
+| `pine` | Use a server that ships with pine (`"web"`, `"browser"` or `"commands"`), configured through `options`. |
+| `session` | In an `agent.json` only, written by `add_mcp_server`: the one conversation the server was added for. Other conversations of the agent do not get it, and it is removed with that conversation. |
+| `taints` | `true` when the server returns content written by others (web pages, mail, tickets, chat). A session that calls it becomes tainted. Default `false`, `true` for the bundled `web` and `browser`. |
+| `approve` | `"always"`: every call needs your approval, each time (except in bypass mode, where nothing asks). `"tainted"`: once the session has seen outside content, the server's tools that act need approval (its read-only tools do not), and you can answer "always in this conversation"; use it for servers that change things or send things out. Default `"never"`. |
+
+Each session starts its own copy of a local server and stops it when the session closes. A
+local server is a normal process of yours: it is not sandboxed, and what it can reach, agents
+can reach through it. Give it the narrowest credentials that do the job.
+
+pi's `mcp.json` files are not read. The daemon gives pi a folder of its own (`data/pi`) and
+agent sessions load no MCP configuration file, so servers you set up for your own interactive
+pi do not appear in agents.
+
+## Bundled: web
+
+Search and page reading without a browser.
+
+```json
+"web": { "pine": "web", "options": { "braveApiKey": "${BRAVE_API_KEY:-}" }, "agents": ["scout"] }
+```
+
+| Tool | What it does |
+|---|---|
+| `mcp__web__search(query, count?)` | Web search. Uses the Brave Search API when `braveApiKey` is set, otherwise DuckDuckGo's HTML page (fine for light use; it may rate-limit). |
+| `mcp__web__fetch(url, max_chars?, start?)` | Fetches a page and returns its text. `start` continues a long page. |
+
+| Option | Default | Meaning |
+|---|---|---|
+| `braveApiKey` | none | Brave Search API key. |
+| `allowHosts` | all | Only these hosts (and their subdomains) can be fetched. Without `braveApiKey` the search is such a fetch too: add `duckduckgo.com`. |
+| `denyHosts` | none | These cannot. |
+| `allowPrivate` | `false` | Allow addresses on your own network. Leave it off. |
+| `maxBytes` | 2 MB | Cut-off for one response. |
+| `maxUrlLength` | 2000 | Longer URLs are refused, which limits how much can be smuggled out in one. |
+| `timeoutMs` | 20000 | Per request. |
+
+It only speaks http and https, follows redirects itself and checks every hop, and refuses
+loopback, private, link-local and similar addresses at the moment the connection is made. A page
+therefore cannot send an agent to your router, your NAS or pine's own control port. Results are
+wrapped in markers that say they are outside content, and the server is marked `taints`.
+
+Once you have agents with private files, move `web` and `browser` to a research agent that has
+nothing private in its workspace and let the others delegate to it.
+[security.md](security.md) explains why.
+
+## Bundled: commands
+
+Turns fixed commands into typed tools, so an agent that should "check the printer" does not
+need a shell for it.
+
+```json
+"tools": { "pine": "commands", "agents": ["house"], "options": { "commands": {
+  "printer_status": {
+    "description": "Current state of the Bambu printer as JSON",
+    "run": ["/opt/homebrew/bin/mosquitto_sub", "-h", "192.168.1.50", "-t", "device/{{serial}}/report", "-C", "1", "-W", "5"],
+    "params": { "serial": { "description": "Printer serial", "pattern": "[0-9A-Z]{15}" } },
+    "timeoutSec": 10
+  },
+  "disk_usage": { "description": "Free space on the data volume", "run": ["/bin/df", "-h", "/Volumes/data"] }
+} } }
+```
+
+| Key | Meaning |
+|---|---|
+| `description` | What the model reads. |
+| `run` | Program and arguments. `{{name}}` inserts a parameter. |
+| `params.<name>` | `type` (`string`, `number`, `boolean`), `description`, `enum`, `pattern` (must match the whole value), `default`, `required` (default true). |
+| `timeoutSec` | Default 30. |
+| `cwd`, `env` | Working folder (default: where the conversation's tools start: the agent's workspace, or the folder opened for the conversation) and extra environment. |
+| `sandbox` | `true` runs the command inside the agent's sandbox (the variant in which instruction files are read-only). It has no effect for an agent with `"sandbox": false` or on a platform without `sandbox-exec`. Default `false`: these are your commands, and most need the network. |
+| `maxOutput` | Characters of output returned. Default 30000. |
+
+Arguments are passed as a list, never through a shell: a parameter value of `x; rm -rf ~` is one
+harmless argument. A value that starts with `-` is refused unless the parameter is a number or
+has a `pattern` or `enum`, so the model cannot turn a value into an option. Constrain parameters
+with `pattern` or `enum` wherever you can.
+
+Mark a commands server `"approve": "tainted"` if any of its commands changes something.
+
+## Bundled: browser
+
+A real browser, for pages that need JavaScript, clicks, forms or a login. It is Microsoft's
+Playwright MCP server with a guard around it.
+
+```json
+"browser": { "pine": "browser", "options": { "headed": false } }
+```
+
+`pine init` downloads the browser itself; `pine browser-install` fetches it again after an update.
+
+The tools appear as `mcp__browser__browser_navigate`, `..._snapshot`, `..._click`, `..._type`,
+`..._fill_form`, `..._press_key`, `..._select_option`, `..._hover`, `..._wait_for`, `..._find`,
+`..._tabs`, `..._navigate_back`, `..._handle_dialog`, `..._close`. A page is read as a
+snapshot: a text outline in which every element has a reference the click and type tools take.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `headed` | `false` | Show the browser window, so you can watch. |
+| `profile` | none | A folder for a persistent profile: cookies and logins survive. Without it every session starts clean. |
+| `tools` | `"core"` | `"core"`: the fourteen tools above. `"all"`: everything Playwright offers that is not blocked. Or a list of names. |
+| `block` | `[]` | Further tool names to withhold. |
+| `allowHosts`, `denyHosts` | none | Limit where the browser may go. Subdomains are included. |
+| `allowPrivate` | `false` | Allow addresses on your own network. Leave it off. |
+| `browser` | `chromium` | `chrome` or `msedge` use an installed browser instead of Playwright's Chromium. |
+| `executablePath`, `viewport`, `caps`, `extraArgs` | | Passed on to Playwright MCP. |
+
+What the guard does:
+
+- **No local network.** Everything the browser requests goes through a proxy inside the guard,
+  which refuses loopback, private and link-local addresses, judged on the address it actually
+  connects to. A page cannot reach your router, your NAS, the model server or pine's control
+  port, whether by link, redirect, script or DNS trick. `file:` URLs are blocked by Playwright.
+- **No code on your machine.** `browser_run_code_unsafe` (runs code in the server process),
+  `browser_file_upload` and `browser_drop` (hand local files to a page) and `browser_install`
+  are removed from the tool list and refused if called, whatever `tools` says.
+- **One step at a time.** Calls a model issues in parallel are run one after another; a browser
+  has one page in front.
+- **Snapshots inline.** Playwright writes snapshots to files; the guard puts their content into
+  the tool result (cut at 24,000 characters; `browser_find` locates things on longer pages).
+
+A browser is the widest door for outside content: sessions that use it are tainted, and with a
+`profile` it is signed in as you wherever you signed in. Treat a persistent profile like a
+password; do not give it to an agent that also handles untrusted events.
+
+## Telegram, MQTT and other outputs
+
+Sending a Telegram message or an MQTT command is not an MCP server. Both are event sources
+that can also send, and an agent uses its `send` tool for them: the daemon already holds the
+connection, and the source decides who may be messaged and which topics may be written. See
+"Sending through a source" in [sources.md](sources.md).

package/docs/references/operations.md

@@ -0,0 +1,280 @@
+# Running pine
+
+## Requirements
+
+- macOS (the sandbox uses `sandbox-exec`). pine starts elsewhere, but withholds the shell tool.
+- Node 24 or newer. From a checkout Node runs the TypeScript sources directly; the npm package
+  holds them compiled.
+- A model that supports tool calls: a hosted provider pi knows (sign in with `pine login`), or
+  your own model server with an OpenAI-compatible chat completions endpoint.
+
+## Install
+
+```bash
+npm install -g @pmndrs/pine
+```
+
+That puts the `pine` command on your PATH. The package holds pine compiled to JavaScript,
+because Node does not run TypeScript from inside `node_modules`.
+
+To work on pine itself, use a checkout instead. `bin/pine` runs the sources as they are and
+installs the dependencies the first time; `npm link` puts that copy on your PATH:
+
+```bash
+git clone https://github.com/pmndrs/pine ~/dev/pine
+```
+
+```bash
+~/dev/pine/bin/pine init
+```
+
+## First start
+
+```bash
+pine init
+```
+
+sets everything up in one step:
+
+- From a fresh checkout, `bin/pine` first installs pine's dependencies (`npm install`), once.
+- It copies the example home to `~/.pine`: one agent, `main`, with web search and the browser, a
+  `models.json`, an empty `.env`. Nothing is overwritten if you run it again.
+- It downloads the Chromium build the bundled browser tools drive (about 600 MB, into
+  Playwright's cache). A second run finds it there and takes a moment. If the download fails,
+  everything else is set up and `pine init` can simply be run again.
+
+```bash
+pine
+```
+
+opens the terminal UI ([tui.md](tui.md)) and, since no daemon is running yet, starts one inside
+it. That is the quickest way to try things. For a daemon that keeps running without a terminal:
+
+```bash
+pine check
+```
+
+```bash
+pine start
+```
+
+and from another terminal `pine` (attaches to it) or
+`pine send main "Say hello and list your tools."`.
+
+### Choosing a model
+
+The example home uses `dev/claude-haiku`: an OpenAI-compatible endpoint whose answers come from
+`claude -p`, so it needs Claude Code installed and signed in. The UI starts it on demand; for
+`pine start`, run it yourself:
+
+```bash
+pine dev-model
+```
+
+Every model call starts a `claude` process: expect about five seconds per call and usage on
+your Claude plan. It is for trying things out, not for a daemon that runs all day.
+
+For a hosted provider, sign in once and pick a model:
+
+```bash
+pine login opencode-go
+```
+
+```bash
+pine login anthropic
+```
+
+```bash
+pine login openai-codex
+```
+
+The first asks for an API key (typed without echo); the other two open a browser sign-in for a
+Claude or ChatGPT subscription. Credentials go to `~/.pine/auth.json` (mode 600). Then set
+`defaults.model` in `pine.json`, for example `"opencode-go/deepseek-v4.1-flash"`, or switch in
+the UI with `/model`. `pine login <unknown>` lists every provider pi knows.
+
+### With llama.cpp
+
+Start the server with tool-call support and a context that matches `models.json`:
+
+```bash
+llama-server -m /path/to/model.gguf --jinja -c 65536 -np 2 --port 8080
+```
+
+`-np` (parallel slots) should equal `limits.maxConcurrentRuns`. The context is shared between
+slots, so each run gets `c / np` tokens; put that number into `contextWindow`.
+
+## Updating
+
+```bash
+pine update
+```
+
+brings pine itself up to date and fetches what the new version needs. What it does depends on
+how pine got onto the machine, which `pine version` tells you:
+
+| Installed | `pine update` |
+|---|---|
+| with `npm install -g` | Asks npm for the latest version. If there is one, installs it (`npm install -g @pmndrs/pine@latest`). |
+| as a checkout (`git clone`) | Fetches from the repository the checkout follows and moves it forward, then runs `npm install`. Only ever a fast-forward: if commits or changes of your own are in the way, nothing is changed and it says so. |
+| as a dependency inside a project | Tells you the command to run in that project; that project decides its version. |
+
+Afterwards it makes sure the browser the web tools drive matches the new version, which is a
+download only when that version changed.
+
+`pine update --check` changes nothing and says whether there is something newer.
+
+A pine that is running keeps the old version until it is restarted: quit the terminal UI and
+open it again, or restart the daemon (if it runs at login as a LaunchAgent:
+`launchctl kickstart -k gui/$(id -u)/com.pine.daemon`).
+Your home folder (`~/.pine`) is not touched by an update. When a new version adds something to
+the example home, `pine init` copies the files you do not have yet and overwrites nothing.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pine`, `pine tui` | The terminal UI; starts a daemon inside if none is running |
+| `pine .`, `pine <folder>` | The terminal UI with one more tab: a conversation of the main agent that works in that folder (the one from last time, if there is one). A first word that is a command stays a command. See [coding.md](coding.md) |
+| `pine login <provider>`, `pine logout <provider>` | Sign in to a model provider. `--api-key` or `--oauth` force the kind of sign-in |
+| `pine init [dir]` | Set pine up: a home directory from the example and the browser its web tools drive. Safe to run again |
+| `pine update [--check]` | Bring pine up to date. `--check` only says whether there is something newer. See "Updating" |
+| `pine version` | Which version this is and how it is installed |
+| `pine browser-install` | Fetch the browser again. `pine init` and `pine update` do this already |
+| `pine check` | Validate the configuration; show each agent's workspace, model, tools, MCP servers; list security notes |
+| `pine start` | Run the daemon in the foreground. Ctrl-C or SIGTERM stops it cleanly |
+| `pine dev-model [--port 7464] [--model haiku]` | The `claude -p` model server |
+| `pine status` | Running tasks, live sessions (and whether they are tainted), model slots |
+| `pine agents` | Configured agents |
+| `pine send <agent> <text...>` | Give an agent a task as yourself and print the answer. `--session <key>`, `--no-wait` |
+| `pine emit <topic> [json]` | Publish an event as yourself |
+| `pine events` | The event log. `--topic <pattern>`, `--limit <n>`, `-f` to follow |
+| `pine tasks` | Recent tasks. `--agent <id>`, `--status pending\|running\|done\|failed\|cancelled` |
+| `pine task <id>` | One task in full |
+| `pine cancel <id>` | Stop a task |
+| `pine state [pattern]` | Shared state |
+| `pine sources` | Lists the event sources: running or idle, who is subscribed, last event; for one that polls (`http`, `command`), when it last looked or since when that fails |
+| `pine subscribe <agent> <source> [--session name] [--note text] [--throttle 5m] [--when json] [--separate]`, `pine unsubscribe <agent> <source> [--session name]` | Wake an agent on a source's events (with `--session`: only that conversation), or stop that |
+| `pine subscribe --global <source> [--note text] ...`, `pine unsubscribe --global <source>` | The same for every agent that can use the source |
+| `pine approvals`, `pine approve <id> [--always]`, `pine deny <id>` | Answer approval requests; `--always` stops the question for the rest of that conversation |
+| `pine reset <agent> [session]` | Start a conversation over; also clears its taint |
+| `pine mode <agent> [manual\|auto\|bypass]` | Show or change an agent's mode until the daemon restarts |
+| `pine mcp list` | MCP servers, who gets them, whether they connect |
+| `pine skills` | Lists every skill: whom it is for (all agents, an agent, one conversation) and where it lies |
+| `pine schedules` | Lists what is scheduled: for whom, when, and the task |
+| `pine manual <words>`, `pine manual --read <id>` | Search this manual the way the agents do, or read one part of it in full |
+| `pine mcp add <name> <url>`, `pine mcp add <name> -- <command...>` | Add a remote or a local server. `--agent <id>` for one agent |
+| `pine mcp remove <name> [--agent <id>]` | Remove a server from `pine.json`, or from that agent's `agent.json` |
+| `pine mcp login <name>`, `pine mcp logout <name>` | Sign in to a remote server through the browser, or forget its tokens |
+
+All take `--home <dir>`; the default is `$PINE_HOME` or `~/.pine`. The commands from `status`
+down to `mode` talk to the running daemon over its control API on `127.0.0.1:7463`, using the
+token in `data/http-token`. The `pine mcp` commands work on the files, and `add` and `remove`
+also tell a running daemon, so the change applies at once. `pine help` prints the list.
+
+## Running at login
+
+[examples/launchd/com.pine.daemon.plist](../../examples/launchd/com.pine.daemon.plist) is a
+LaunchAgent that starts pine at login and restarts it when it exits. Follow the three steps at
+its top. Logs then go to `~/.pine/data/pine.log`.
+
+A LaunchAgent runs as you, in your login session. To separate the agents from your files more
+strongly, create a dedicated macOS user, keep pine's home and the agents' workspaces there, and
+install the plist for that user.
+
+## The control API
+
+For scripts and other programs. Every request needs `Authorization: Bearer <token>`; POST bodies
+are JSON with `Content-Type: application/json`.
+
+| Request | Purpose |
+|---|---|
+| `GET /health` | Liveness (no token) |
+| `GET /status`, `/agents`, `/approvals` | As the CLI commands |
+| `GET /models` | Models that have credentials, as `provider/id` |
+| `GET /mcp` | Configured MCP servers |
+| `POST /mcp` `{ name, server, agent? }` or `{ name, remove: true, agent? }` | Add or remove a server while the daemon runs |
+| `POST /mcp/refresh` | Close idle sessions so they start again with the current servers |
+| `GET /agents/<id>/sessions` | The agent's conversations: name, number of messages, last use, whether pinned or open in a tab, and when one will be removed by itself |
+| `POST /agents/<id>/pin` `{ session, pinned? }` | Pin a conversation so that it is kept, or with `pinned: false` take the pin off |
+| `POST /agents/<id>/rename` `{ session, to }` | Give a conversation another name; its history, pin, subscriptions and what was set up for it follow |
+| `POST /agents/<id>/remove` `{ session }` | Remove a conversation for good, with its history and what was set up for it alone. Not the main one, and not while it is working |
+| `GET /ui/tabs`, `POST /ui/tabs` `{ tabs, active, code? }` | The tabs the terminal UI has open (`tabs` is a list of `{ agent, session }`) and whether its code pane was open, kept so that it opens the same way next time |
+| `GET /agents/<id>/folder?session=`, `GET /agents/<id>/folders`, `POST /agents/<id>/folder` `{ session, folder }` | The folder a conversation works in; every conversation of the agent that has one; open a folder for a conversation (`folder: null` closes it). Refused for pine's home, pine's program and other agents' workspaces, and while the conversation is working |
+| `GET /agents/<id>/view/changes?session=`, `/view/diff?session=&path=`, `/view/tree?session=&path=`, `/view/file?session=&path=` | What the code pane shows of a conversation's folder (or of the agent's workspace): what git says changed, one file's diff, what is in a folder, a file's text. Read-only, and nothing outside that folder |
+| `POST /agents/<id>/model` `{ model }` | Switch an agent's model and save it in its `agent.json` |
+| `POST /agents/<id>/thinking` `{ level }` | Set an agent's reasoning level and save it in its `agent.json` |
+| `POST /agents/<id>/mode` `{ mode, session?, anyway? }` | Switch an agent's mode until the daemon restarts. `anyway: true` with a `session` keeps bypass in force in that conversation although it has read outside content |
+| `GET /tasks?agent=&session=&status=&limit=`, `GET /tasks/<id>` | Tasks |
+| `GET /tasks/<id>/transcript` | What a task did, step by step: the text it was given, what it wrote, its tool calls with the start of each result. With `?full=1`: with the whole result of each call, up to 200 000 characters |
+| `GET /events?topic=&after=&limit=` | Event log; `after=<id>` pages forward |
+| `GET /events/stream?topic=` | Live events as server-sent events |
+| `GET /state?key=` | Shared state |
+| `POST /events` `{ topic, payload }` | Publish an event (as owner; `"trust": "untrusted"` to lower it) |
+| `POST /agents/<id>/prompt` `{ prompt, session?, wait?, attachments? }` | Give a task. Waits for the result unless `wait` is false. `attachments` is a list of `{ name, data }` with base64 data; the files are saved to `inbox/` in the agent's workspace |
+| `POST /agents/<id>/reset` `{ session? }` | Reset a session. What it was subscribed to on its own ends too |
+| `GET /media/tool/<id>` | A picture a tool returned. The ids are in the `images` field of `agent/<id>/tool` events and of transcript steps |
+| `GET /tasks/<id>/images/<n>` | The n-th picture that came with a task (an attachment, a Telegram photo) |
+| `GET /agents/<id>/image?path=&session=` | A picture or video file in that agent's workspace or, with `session`, in the folder opened for that conversation. Anything that is not an image or video file in there is "not found" |
+| `POST /images/fetch` `{ url }` | Fetch a picture or video from the web for display: https and public addresses only; pictures up to 20 MB, videos up to 100 MB |
+| `GET /sources`, `GET /agents/<id>/sources` | Event sources and their state; the ones that agent can subscribe to |
+| `POST /agents/<id>/subscribe` `{ source, session?, note?, when?, throttle?, debounce?, separate? }`, `POST /agents/<id>/unsubscribe` `{ source, session? }` | Change an agent's subscriptions (written to its `agent.json`); `session` makes it one conversation's |
+| `POST /subscribe` `{ source, note?, ... }`, `POST /unsubscribe` `{ source }` | The subscription of all agents (written to `pine.json`) |
+| `POST /agents/<id>/close` `{ session }` | A conversation's tab was closed in a UI: ends what it was subscribed to on its own. The conversation itself is kept |
+| `POST /tasks/<id>/cancel` | Cancel |
+| `POST /approvals/<id>` `{ allow, always?, values? }` | Answer an approval. A request that lists `inputs` (a token, a password) is only allowed together with `values: { <name>: "..." }`; the terminal UI has a field for them |
+| `POST /state` `{ key, value }` | Write state; `null` deletes |
+| `POST /hook/<name>` | Webhook: a hook from `http.hooks` ([events.md](events.md)) or a running `webhook` source ([sources.md](sources.md)). No token; each has its own secret, unless a hook is declared `"open": true` |
+
+## Day to day
+
+- **See what is happening:** `pine events -f` in a terminal. Add `--topic "agent/#"` for agent
+  activity only; tool calls appear live on `agent/<id>/tool`.
+- **Why did it answer that?** `pine task <id>` shows the prompt as the agent received it, the
+  tools it called and the result. The full transcript is the newest `.jsonl` under
+  `~/.pine/agents/<id>/sessions/<session>/`.
+- **Change instructions:** tell the agent ("from now on ..."); it writes that into `AGENTS.md` in
+  its workspace. Or edit the file yourself. Either applies to the next message. What all agents
+  should know about you goes into `USER.md` in pine's home, which the main agent keeps.
+- **Change configuration:** edit `pine.json` or `agent.json`, run `pine check`, restart the
+  daemon. Queued tasks survive the restart. MCP servers, event sources, subscriptions and new
+  agents need neither an edit nor a restart: ask an agent ([setup.md](setup.md)), or use
+  `pine mcp add` and `pine subscribe`.
+- **An agent is stuck:** `pine status`, then `pine cancel <id>`.
+- **An agent keeps asking for approval:** its session is tainted. `/reset` or `pine reset`.
+- **Back up:** the home directory. `data/pine.db` holds events and tasks, `agents/*/sessions`
+  the conversations. Workspaces are wherever you put them.
+
+## Problems
+
+| Symptom | Likely cause |
+|---|---|
+| `pine.json not found` | Wrong home. Pass `--home` or set `PINE_HOME`. |
+| `model "x/y" is not defined in models.json` | `defaults.model` or an agent's `model` does not match `provider/id`. `/model` in the UI lists what is available. |
+| A task fails with 401 or "API key" | The provider's credential is missing or expired. `pine login <provider>` again. |
+| The browser tools fail with "Executable doesn't exist" | Run `pine init` again (or `pine browser-install`): the browser is missing or pine was updated to a newer one. |
+| The UI says "reconnecting…" | The daemon it was attached to stopped. Start it again; the UI picks it up. |
+| `no daemon answers on http://127.0.0.1:7463` | The daemon is not running, or `http.port` differs from what the CLI reads in this home. |
+| A task fails with a connection error | The model server is down or `baseUrl` is wrong. `curl <baseUrl>/models` should answer. |
+| A task fails after minutes with a timeout | The model stopped streaming (`limits.modelStreamIdleMs`) or took too long to start (`limits.modelHeadersTimeoutMs`); raise them for a slow model. |
+| The agent says a file is "not permitted" | It is outside the workspace. In `auto` mode it can ask you with `request_access`; to open a folder for good, use `sandbox.read` / `sandbox.write`. |
+| `git` complains about identity | The agent's shell has its own empty home. Run `git config --global user.name ...` once through the agent, or set it per repository. |
+| A command needs the network | `sandbox.network: true` for that agent, or better a `commands` tool for that one command. |
+| Telegram bot does not react | `pine sources`: is the `telegram` source running, and is a conversation subscribed? A new bot waits to be paired: write to it, and type the code it sends you into the question in the terminal UI (`pine sources` says whom it listens to). Otherwise another program polls the same bot token. |
+| An event arrives but no task starts | See "When nothing happens" in [events.md](events.md) for routes and in [sources.md](sources.md) for subscriptions. |
+| The first answer after a pause is slow | The session was closed after `idleMs` and is being resumed; MCP servers start again. |
+
+## Coming from OpenClaw
+
+| OpenClaw | pine |
+|---|---|
+| Agents in `openclaw.json` with `workspace-*` folders | One folder per agent under `agents/`; `workspace` points at the repository |
+| Telegram `bindings` | A `telegram` source the agent sets up when you ask it to, and is subscribed to |
+| `SOUL.md`, `AGENTS.md`, `MEMORY.md` | The same three names in the agent's workspace, read into its prompt and written by the agent |
+| `USER.md` | One `USER.md` in pine's home for all agents, kept by the main agent |
+| `IDENTITY.md`, `TOOLS.md`, daily memory files | Not read by pine. Fold what matters into `SOUL.md`, `AGENTS.md` or `MEMORY.md`; other notes are ordinary files in the workspace |
+| Cron jobs | A schedule: ask the agent ("every morning at seven ..."), or write it under `schedules` with a `task` |
+| Heartbeat | Usually not needed: an event source wakes the agent when something happens, and looking again and again (`http`, `command`) costs no model turn. For a real one, a schedule with `every` whose task ends in "reply NO_REPLY if nothing needs attention" |
+| `/hooks/*` mappings | A `webhook` source the agent subscribes to, or `http.hooks` plus a route |
+| Managed extensions that watch something and message Telegram themselves | An event source the agent subscribes to (a folder, an FTP drop, MQTT), and the `send` tool for what it reports to you on Telegram. The agent then knows what happened |
+| Skills | Skills, same format |