@pmndrs/pine 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Henschel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
+    <img src="docs/images/logo-light.svg" alt="pine" width="360">
+  </picture>
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+<code>
++ OpenCode, inspired by its interactive TUI
++ OpenClaw automation, without the weight & complexity
++ PI coding agent for basic turns, auto compact and model providers
+-------------------------------------------------------------------
+= PINE
+</code>
+</div>
+<br/>
+
+This is a small daemon that runs AI agents. Yes, you've heard that before. Some things it does very differently:
+
+- **Letting agents react to external events**: chat, FTP, webhooks, MQTT, web addresses, schedules, etc. In a simple, modular way, and without configs. Agents can subscribe to any installed event source and react accordingly, or list available sources and unsubscribe. Event sources are simple to create, it's a \*.ts service with a schema. This allows you to create full automation workflows by just stating what you want: "watch my security cam, ring the alarm if someone enters while i'm away".
+- **No configs**: you tell the agent what you want. They operate through safe tool calls. Main agent can create other agents, global MCPs, event sources, skills, schedules, etc. Other agents can create these either for local conversations or their scope. No agent will touch or bypass into user config (where your tokens are).
+- **A CLI that feels new**. Like a desktop UI. Interactive tabs, buttons, scroll regions. Images and videos are actually shown, formats markdown. Drag and drop files with real thumbails - and yes it's running in your shell (all Kitty shells, GHOSTTY et al, with lower quality fallbacks for old terminals).
+- **All basics inbuilt**: computer use, tool calls, internet, browsing and operating live websites
+- **Coding assistance**: diffs, output files, git integration, current folders ...
+- **Orchestrating agents**, sub-agents, ... well, yes it does that. In an intuitive way. A pinned tab is a persistent agent. Create an agent, open a tab, rename it, tell it its basic instructions (these go into AGENTS.md), connect it to event sources, for instance Telegram if you want to chat abroad, pin it, close the tab if you want (you find it back in the running sessions), you're done.
+
+<br/>
+
+<table>
+  <tr>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/meme.png" width="100%" alt="pine searches the web, downloads a picture and shows it in the terminal"><br/>
+      <sub>Support for images</sub>
+    </td>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/video.gif" width="100%" alt="pine fetches a video from the web and plays it in the terminal"><br/>
+      <sub>Support for videos</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/drop.png" width="100%" alt="A picture dropped into the terminal, shown as a thumbnail, and the agent's answer about it"><br/>
+      <sub>Drag and drop</sub>
+    </td>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/watch.png" width="100%" alt="Asked to watch a folder, the agent sets up an event source; a file changes, it wakes up and shows the git diff"><br/>
+      <sub>Event sources (file watchers, ...)</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/tabs.png" width="100%" alt="Tabs for several agents and conversations, with the list of conversations: pinned ones stay, the others clean themselves up"><br/>
+      <sub>UI can be navigated by clicking</sub>
+    </td>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/flipper.png" width="100%" alt="pine drives a Flipper Zero through an MCP server"><br/>
+      <sub>Support for MCPs and skills</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/code.png" width="100%" alt="The code pane beside a conversation: the git diff of a file the agent just changed"><br/>
+      <sub>Code assistance</sub>
+    </td>
+    <td align="center" width="50%">
+      <br />
+      <img src="docs/images/folder.png" width="100%" alt="pine started in a project folder: the agent inspects it, and the folder menu lists the folders a conversation can work in"><br/>
+      <sub>Current folders</sub>
+    </td>
+  </tr>
+</table>
+
+<br/>
+
+```
+                  you:  terminal UI · Telegram
+                               │
+                               ▼
+ wake it                 ┌───────────┐            it uses
+ events ───────────────► │           │ ◄───────── MCP servers
+   Telegram · MQTT · FTP │           │ ◄───────── skills
+   webhooks · folders    │   agent   │
+   web addresses         │           │
+   commands · etc        │           │
+ schedules ────────────► │           │
+   repeating · once      └─────┬─────┘
+                               │  delegate ──► other agents
+                               │  subagent ──► with distinct prompts, in parallel
+                               ▼
+                 answers · messages · actions
+
+ Events, schedules, MCPs and skills can be set up by asking:
+ for the current conversation, agent scope, or globally
+ (main agent only) for all agents.
+```
+
+## Quick start
+
+Requires Node 24 or newer and macOS (for the sandbox).
+
+```bash
+npm install -g @pmndrs/pine
+```
+
+Sets everything up: the browser the web tools drive, and your user folder (`~/.pine`).
+
+```bash
+pine init
+```
+
+Checks the setup: validates the configuration, lists each agent with its model, tools and MCP
+servers, and prints security notes if something is open that should not be.
+
+```bash
+pine check
+```
+
+Opens the terminal UI. If no daemon is running, it starts one inside and stops it when you quit.
+
+```bash
+pine
+```
+
+Runs the daemon as a service, without the UI, so agents keep reacting to events with no terminal
+open. `pine` then attaches to it. To have it start at login, see
+[operations.md](docs/references/operations.md).
+
+```bash
+pine start
+```
+
+Connect your subscriptions, orlocal llm servers. Switch with `/model` in the UI:
+
+```bash
+pine login opencode-go
+```
+
+`pine login anthropic` and `pine login openai-codex` use a Claude or ChatGPT subscription; a
+local llama-server goes into `~/.pine/models.json`. See
+[operations.md](docs/references/operations.md) and [tui.md](docs/references/tui.md).
+
+To work on a project, start it in that folder. The agent gets that folder for the
+conversation, and `▤ code` (or `ctrl+g`) opens a pane with git changes and diffs, the files and
+the output of its tool calls ([coding.md](docs/references/coding.md)):
+
+```bash
+pine .
+```
+
+To get a newer version later, with whatever it needs:
+
+```bash
+pine update
+```
+
+## Documentation
+
+Start at [docs/SKILL.md](docs/SKILL.md); it indexes everything.
+
+| To do this                                                                              | Read                                                         |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Understand how the pieces fit                                                           | [overview.md](docs/references/overview.md)                   |
+| Use the terminal UI                                                                     | [tui.md](docs/references/tui.md)                             |
+| Work on a project: `pine .`, the code pane with git changes, files and tool output      | [coding.md](docs/references/coding.md)                       |
+| Install, run, use the CLI, run it as a service                                          | [operations.md](docs/references/operations.md)               |
+| Write `pine.json` and `agent.json`                                                      | [configuration.md](docs/references/configuration.md)         |
+| Let agents set things up by tool call instead of editing files                          | [setup.md](docs/references/setup.md)                         |
+| Set up agents, delegation and sub-agents                                                | [agents.md](docs/references/agents.md)                       |
+| Route events, schedules, model calls                                                    | [events.md](docs/references/events.md)                       |
+| Event sources: Telegram, folders, MQTT, web addresses, commands, webhooks, FTP          | [sources.md](docs/references/sources.md)                     |
+| MCP servers, web search, command tools                                                  | [mcp.md](docs/references/mcp.md)                             |
+| Know what is protected and what is not                                                  | [security.md](docs/references/security.md)                   |
+| Work on pine itself                                                                     | [AGENTS.md](AGENTS.md), [stack.md](docs/references/stack.md) |

package/bin/pine.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// pine's launcher. From a checkout it runs the TypeScript sources as they are; from an installed
+// package it runs the compiled ones (Node does not run TypeScript from inside node_modules).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+if (Number(process.versions.node.split(".")[0]) < 24) {
+	console.error(`pine needs Node 24 or newer (this is ${process.versions.node}): https://nodejs.org`);
+	process.exit(1);
+}
+// The real place of this file, also when it was started through the link npm puts on the PATH.
+const root = path.resolve(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))), "..");
+const source = path.join(root, "src", "cli.ts");
+if (fs.existsSync(source)) {
+	// A fresh checkout: fetch what pine is built on, once, so that the first command just works.
+	if (!fs.existsSync(path.join(root, "node_modules", "@earendil-works", "pi-coding-agent"))) {
+		console.error("pine: installing its dependencies (once) ...");
+		const done = spawnSync("npm", ["install", "--no-audit", "--no-fund"], { cwd: root, stdio: ["ignore", 2, 2] });
+		if (done.status !== 0) {
+			console.error(`pine: npm install failed; run it in ${root} to see why`);
+			process.exit(1);
+		}
+	}
+	await import(pathToFileURL(source).href);
+} else await import(pathToFileURL(path.join(root, "src", "cli.js")).href);

package/docs/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: pine
+description: Run, configure and extend pine, the event-driven multi-agent daemon built on the pi coding agent SDK. Use when setting up agents and their workspaces, subscribing agents to event sources (Telegram, folders, MQTT, webhooks, FTP uploads, web addresses, commands), scheduling what happens at a time, adding MCP servers and skills, routing events to agents, reaching agents on Telegram, delegating between agents, reviewing what is protected against prompt injection, or changing pine's code.
+---
+
+# pine
+
+pine (PI neural engine) is one process that hosts several pi agent sessions and an event log.
+Event sources and schedules turn the outside world and the clock into events; subscriptions,
+schedules and routes turn events into work; agents answer, act, hand tasks to each other, and
+publish events of their own.
+
+Three things to know before anything else:
+
+1. **Configuration lives in a home directory**, by default `~/.pine`: `pine.json` (global),
+   `models.json` (pi's model file), `.env` (secrets), and one folder per agent under `agents/`.
+2. **An agent is a folder**: `agents/<id>/agent.json` and a workspace. In the workspace lie the
+   files the agent keeps itself and that are read into its prompt: `AGENTS.md` (its purpose),
+   `SOUL.md` (who it is), `MEMORY.md` (its memory). `USER.md` in the home is what all agents
+   know about you. The workspace is wherever `workspace` points, for example a repository.
+3. **Where content came from decides what it may do.** Your own messages get the agent's full
+   tool set. Anything else is data. An event from outside runs with a reduced tool set in a
+   separate session; an event from a source a conversation subscribed to arrives in that
+   conversation, framed as data, and marks it as having read outside content (unless the source
+   is marked as yours). Either way nothing is sent out without your approval.
+
+## If you are an agent running inside pine
+
+You search this manual with your `manual` tool: a search names the parts that fit with the
+line that matched, and you then read the one or two parts you need. Search before you answer a
+question about pine or say that something is not possible.
+
+pine's configuration lives in its home folder (`~/.pine` unless your owner chose another),
+which is closed to you on purpose: you never write those files. Four things you set up by
+calling a tool, for the conversation you are in or for yourself as an agent
+([references/setup.md](references/setup.md)): event sources and subscriptions, schedules,
+remote MCP servers, and skills. Creating agents, anything for all agents and new types of
+event source are the main agent's job; if you are not the main agent, send your owner to it.
+For everything else your owner asks about (a route, your built-in tools or model, the sandbox):
+
+1. Search the manual for it and read the part.
+2. Tell your owner what to put where: usually a few lines of JSON in `pine.json` (for everyone)
+   or `agents/<your id>/agent.json` (for you), then `pine check`, then a restart of the daemon
+   (quitting and reopening the terminal UI restarts an embedded one).
+3. Do not try to edit those files or work around the restriction. Say plainly that this is a
+   step for them.
+
+One thing you can start yourself: when your owner asks you to install or connect a remote MCP
+server and gives you its https URL, call `add_mcp_server` with a short name and that URL. Leave
+the scope out: the server is then for the conversation you are in (in your main conversation:
+for you as an agent). Pass `scope: "agent"` only if they said it is for you in general, and, as
+the main agent, `scope: "global"` only if they said "for all agents". They get a dialog and
+confirm it. `remove_mcp_server` takes one out again. Do not probe the URL first; an
+"unauthorized" answer only means the server wants a sign-in, which your owner does afterwards
+with `/mcp login <name>` in the terminal UI or `pine mcp login <name>` in a shell. Tell them
+that. A local server (a command to run) is theirs to add: `pine mcp add <name> -- <command>`.
+
+Another: when your owner asks you to watch something or to react when something happens, call
+your `sources` tool: it lists what you can subscribe to and what you are subscribed to (use it
+too when your owner asks what you are watching). If one fits, subscribe to it with a note that
+says what you are to do; whoever is subscribed is woken with that note whenever it reports
+something. A subscription is for the conversation it is asked for in: that one is woken, and the
+subscription goes when the conversation is closed, reset or removed. So leave the scope out.
+Only when your owner says in so many words that it is for more do you pass one: agent (your
+main conversation is woken instead, and it stays) or, if you are the main agent, global (all
+agents); your owner is then asked to confirm. Do not pick a wider scope yourself; if you think
+they want one, ask. You can end anything your own agent is subscribed to from any of its
+conversations (`unsubscribe` with scope `agent` or `all`). If none fits,
+set one up with `add_source` (a folder to watch, a web address or a command that is looked at
+again and again, an MQTT device, a webhook, an FTP drop, Telegram); your owner confirms it where
+that is needed. A password or token is never yours to handle: leave it out, and pine asks your
+owner for it in a dialog. `remove_source` deletes one for good. Through a source that can send
+(Telegram, MQTT) you reach out with `send`. Do not go looking in pine's home folder for what is
+configured: `sources` tells you.
+
+When your owner wants something done at a time ("every morning at seven", "remind me at five",
+"in twenty minutes"), that is a schedule, not a source: call `add_schedule` with a name, the
+task in your own words, and one of `cron`, `every`, `at` or `in`. When it is time you are woken
+with the task. `schedules` lists what is scheduled, `remove_schedule` ends one.
+
+When your owner wants you to remember how something is done ("make a skill for this"), call
+`add_skill` with a name, a line on when to use it, and the steps. It is listed among your
+skills from your next message on; `remove_skill` deletes it. A fact rather than a procedure
+belongs into your `MEMORY.md` instead. `add_skill` is refused in a conversation that has read
+outside content.
+
+Schedules, skills, sources and servers follow the same rule: leave the scope out and it is for
+the conversation you are in.
+
+If you are the main agent and your owner asks for a new agent, call `create_agent` with an id,
+one line on what it is for, and its instructions written to the agent itself ("You are ..."):
+its job, what it should and should not do, how it reports. Your owner confirms it, and the agent
+exists at once. For a device or service that no existing type of source can watch, the main
+agent can also write a new source type and register it with `add_source_type`
+([references/sources.md](references/sources.md)); try the existing types first.
+
+Things you can do yourself: work in your workspace, keep notes there, use the tools you have,
+hand work to the agents listed in your prompt, and write shared state under your own keys.
+
+## Which file to read
+
+| You want to | Read |
+|---|---|
+| See what an agent is given (events, schedules, MCP servers, skills) and how events, tasks and sessions fit together | [references/overview.md](references/overview.md) |
+| Chat with agents in the terminal: tabs, slash commands, approvals, switching models | [references/tui.md](references/tui.md) |
+| Work on a project: `pine .`, a folder for a conversation, the code pane with git changes, files and tool output | [references/coding.md](references/coding.md) |
+| Install it, start it, use the CLI, run it at login, find out why something did not happen | [references/operations.md](references/operations.md) |
+| Look up a key in `pine.json`, `agent.json`, `models.json` or `.env` | [references/configuration.md](references/configuration.md) |
+| Know what agents can set up by tool call, for whom, and what you are asked: event sources, MCP servers, skills, schedules, new agents, new source types | [references/setup.md](references/setup.md) |
+| Add an agent, give it a workspace, tools and a persona; skills; how agents look pine up (the `manual` tool); delegation, sub-agents, sessions, shared state | [references/agents.md](references/agents.md) |
+| Let an agent react to the outside world and reach out: Telegram, a watched folder, MQTT devices, a web address or a command that is looked at again and again, webhooks, FTP uploads from cameras; subscribing, unsubscribing, sending; a source type of your own | [references/sources.md](references/sources.md) |
+| Have something done at a time (schedules); write rules for events yourself: set state, publish, single model calls, debounce | [references/events.md](references/events.md) |
+| Add MCP servers globally or per agent; web search, page reading and the bundled browser; turn shell commands into tools | [references/mcp.md](references/mcp.md) |
+| Understand the defences against outside abuse and prompt injection, and their limits | [references/security.md](references/security.md) |
+| Know the technology underneath and the pi behaviours pine works around; open points | [references/stack.md](references/stack.md) |
+| Change pine's code | [../AGENTS.md](../AGENTS.md) |
+
+## The shortest working setup
+
+```bash
+npm install -g @pmndrs/pine
+```
+
+```bash
+pine init
+```
+
+```bash
+pine
+```
+
+One agent, `main`, with web search and a browser, and the terminal UI to talk to it. Everything
+below is added on top of that when you need it.
+
+`~/.pine/pine.json`:
+
+```json
+{
+  "main": "main",
+  "defaults": { "model": "dev/claude-haiku" }
+}
+```
+
+(An excerpt. `pine init` also writes the web and browser servers and the limits; put the model
+you use where `dev/claude-haiku` stands.)
+
+Telegram as a second way in is set up by asking the main agent: "watch Telegram". The dialog
+you confirm has a field for the bot's token; then you write to the bot and type the six-digit
+code it sends you into pine. See [references/sources.md](references/sources.md).
+
+`~/.pine/agents/gonzo/agent.json`, a second agent, a specialist the main agent can hand work to.
+Create the folder; the workspace here is `~/dev/gonzo`, which must exist, and an `AGENTS.md` in
+it says what the agent is for (without `workspace`, pine makes `agents/gonzo/workspace` itself).
+Or ask the main agent to create one: it calls `create_agent`, and no restart is needed.
+
+```json
+{
+  "description": "Contract law; knows the case files",
+  "workspace": "~/dev/gonzo"
+}
+```
+
+```bash
+pine check
+```
+
+```bash
+pine start
+```
+
+`main` sees `gonzo` in its list of agents and can call `delegate`. `pine events -f` shows everything as it happens.
+
+## Vocabulary
+
+| Term | Meaning |
+|---|---|
+| event | One record in the log: topic, payload, source, trust, cause |
+| topic | Slash-separated name, matched with `+` (one level) and `#` (the rest) |
+| route | A rule in `pine.json` that reacts to topics |
+| source | A named thing that reports events from outside: a folder, an MQTT broker, a web address, a command, a webhook, an FTP drop, a Telegram bot. It runs only while something is subscribed to it (or always, with `"start": "always"`) |
+| schedule | Something done at a time: at set times, every so often, or once. With a task it wakes an agent to do it |
+| subscription | A conversation of an agent listens to a source: each event arrives there as a message and wakes the agent |
+| task | One piece of work for one agent; has a status, a result and statistics |
+| session | A conversation of one agent with history. The manual also says "conversation". Named ones are kept until removed (unused ones after `limits.conversationDays`); `new` is one-off |
+| owner | You. Content is "owner" only when it entered through a channel that authenticated you |
+| untrusted | Everything else: data that may contain instructions it has no right to give |
+| tainted | A session that has seen outside content (a web page, an MCP result, an untrusted task) |
+| approval | Your yes or no to one tool call, asked in the terminal UI and over Telegram, or answered with `pine approve` |
+| extension | A pi extension: pi's own plug-in format, usable in pine sessions |