@withbuddi/buddi 0.1.0-pre.15 → 0.1.0-pre.17

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,352 @@
+# buddi
+
+<img src="packages/web/public/mascot/core.png" alt="The Buddi Blob, buddi's mascot" width="160" align="right">
+
+buddi is a personal agent platform you run on your own machine. An agent is a
+markdown file: a front matter that names the tools it may call, and a body that
+is its persona. Agents get real access: your mail, your files, a browser of
+their own, commands on the machine. They reach you on a dashboard in your
+browser and on Telegram. They also work while you are away: scheduled
+missions, watchers that speak only when something is wrong, reminders they set
+themselves. Anything consequential waits for your approval, as a card you
+approve or reject.
+
+Everything stays on your machine, in a private Postgres. The one thing that
+leaves is each agent's prompt, sent to the AI provider that agent's file names.
+So one line in one file decides which company sees that agent's conversations.
+Secrets live in a vault the agents can use but never see.
+
+The first agent is called buddi. It wears the Buddi Blob.
+
+---
+
+## Install
+
+You need Node 22 or newer. Nothing else: no Docker, no pnpm, no build step.
+
+```sh
+npm install -g @withbuddi/buddi
+buddi
+```
+
+The first `buddi` does five things, one line each in the terminal, and asks
+nothing:
+
+1. creates the data directory,
+2. sets up a private Postgres inside it, on a loopback port, with a password
+   only the vault holds,
+3. writes the few settings the service needs to start,
+4. installs the background service and starts it: a launchd agent on macOS, a
+   systemd user unit on Linux,
+5. opens the setup wizard in your browser.
+
+Every later `buddi` opens the dashboard. The link it prints is a sign-in link
+good for five minutes; run `buddi` or `buddi dashboard` again for a new one.
+
+The dashboard listens on `127.0.0.1:4317`. To use another port:
+
+```sh
+BUDDI_WEB_PORT=4417 buddi
+```
+
+**The browser.** The agents' own browser needs a browser binary, and the
+package ships none. If Google Chrome is installed, buddi uses it. If not, the
+wizard offers to fetch Chromium (about 150 MB), or you can run
+`buddi browser install` at any time.
+
+**Telegram.** The wizard can pair your phone: you ask @BotFather for a bot,
+paste the token, and scan the QR code it draws. `buddi telegram pair` does the
+same from a terminal.
+
+**On Linux.** There is no OS keychain, so secrets go in an encrypted file vault
+in the data directory, opened by a key stored beside it (`vault-key`, mode
+600). Anyone who can read your data directory can open the vault; a backup is
+different, it is sealed with your passphrase. On a server with no display the
+agents' browser runs headless. The systemd user unit stops when you log out
+unless you run this once:
+
+```sh
+loginctl enable-linger $USER
+```
+
+**Pre-releases.** Until 0.1 is out, releases are published under the `next`
+tag:
+
+```sh
+npm install -g @withbuddi/buddi@next
+```
+
+The full install story, including what is not built yet, is
+[docs/install.md](docs/install.md).
+
+---
+
+## The first ten minutes
+
+**The wizard.** buddi asks four things, one at a time, in a chat thread:
+
+1. **Your name**, so the agents know what to call you.
+2. **Your clock**, taken from the browser; confirm it or pick another. This is
+   what every agent means by "today".
+3. **A brain**: the AI your assistant thinks with. An API key from Anthropic
+   or OpenAI; Ollama running on this computer; Ollama Cloud or another
+   OpenAI-compatible service, with an address and a key; or Claude, with your
+   Claude subscription, where this build enables it. buddi tests it with one
+   small call before moving on.
+4. **Your assistant**: a name (buddi by default), a face (the Buddi Blob, or
+   another mascot or an emoji), and a persona you can keep or rewrite.
+
+Between the brain and the assistant, buddi checks the browser and fetches one
+if it has to. Then the assistant speaks first, in the same thread, and offers
+to reach you on your phone. Every answer keeps a "change" link, and a reload
+resumes where you were. [docs/onboarding.md](docs/onboarding.md) is the full
+script.
+
+**The first chat.** A few things to try:
+
+- "What can you do?" It answers from the tools its file grants it.
+- "Remind me to call the bank tomorrow at 10." A reminder it sets itself, and
+  you can see it on the Reminders page.
+- "Take a screenshot of example.com." It opens its own browser, asks you
+  first, and shows the page on the canvas beside the chat.
+- Drop a PDF or a CSV on the chat and ask about it.
+- "Every Friday at 6, send me a recap of the week." A mission, on a schedule.
+
+**A mailbox.** In Settings → Email, add an account with its address and an app
+password. buddi then proposes a Mail agent (@mail) that triages new mail in
+the background. Accept it with **Create @mail**; until you do, mail is fetched
+and threaded but nobody reads it. Sending always stops at an approval card
+that shows the full message. [docs/email.md](docs/email.md) has the rest.
+
+**More agents.** Agent Father (@father) makes and changes agents. Say what you
+want one to do; it interviews you, proposes the file and the tools it should
+have, and writes it once you approve.
+
+---
+
+## How it works
+
+**Agents are files.** One folder per agent, with an `agent.md` in it. The
+front matter says which tools the agent may call; nothing else is callable,
+and no conversation can grant more. The body is the persona, in plain
+markdown. The provider and model are a line in the same file, and the
+dashboard's Agents page edits them for you.
+
+```markdown
+---
+id: ledger
+handle: ledger
+name: Ledger
+description: Tracks my accounts and answers "can I afford this?".
+provider: anthropic
+model: claude-sonnet-5
+tools: [finance.*, memory.*, reminder.*]
+---
+
+You are my finance advisor. There is exactly one owner: the person you are
+talking to. Today is {{today}}.
+```
+
+**Tools and plugins.** The core has no tools; every capability is a plugin.
+Built in: `system`, `email`, `memory`, `artifacts`, `web`, `browser`, `host`,
+`reminder`, `schedule`, `goal`, `learning` and `canvas`. Installable from npm,
+on the Plugins page or with `buddi plugins install`: `finance`, `developer`
+and `image`. Installing a plugin shows everything it brings first: each tool
+and whether it runs without asking, the database schema it will own, what it
+runs on a timer, and the hosts it talks to. Nothing happens until you approve.
+[docs/plugins.md](docs/plugins.md) is the guide to writing one.
+
+**Approvals.** Every tool has a tier. Anything that is not safe to run on its
+own, such as sending mail, running a command or acting in a browser, stops the
+run and shows a card with exactly what will happen. You approve or reject it
+on the dashboard or on Telegram. Unknown tools, bad arguments and missing
+configuration never run. [ARCHITECTURE.md](ARCHITECTURE.md) has the model.
+
+**Missions and watchers.** A mission is scheduled work. A watcher checks
+something on an interval and produces findings; core decides whether a finding
+is worth waking you for. An unattended run stays quiet unless it has something
+to say, and when background work keeps failing you hear about it once, in
+plain words. Goals add a target with a date: buddi checks it hourly and wakes
+the agent that holds it when you drift ([docs/goals.md](docs/goals.md)).
+
+**Groups.** A group is one persistent conversation with a team of agents. A
+coordinator decides who works on each request, and you get one answer.
+[docs/groups.md](docs/groups.md).
+
+**Files.** What you send the agents and what they produce sit in one library,
+the Files page, with the conversation each came from.
+[docs/files.md](docs/files.md).
+
+**Memory and learning.** Agents keep notes about you, with where each came
+from, scoped per agent. Learning goes one step further: buddi proposes a
+skill, a mail rule or a change to an agent's file, and nothing is kept until
+you keep it. A weekly digest lists what is waiting.
+[docs/learning.md](docs/learning.md).
+
+**Owner secrets.** Your passwords, API tokens and one-time codes go in
+Settings → Keys and secrets. An agent can have one filled into a login form,
+typed, or sent as a header, after an approval card that names where it goes.
+There is no way to read a value back, and values are scrubbed from anything an
+agent sees. [docs/owner-secrets.md](docs/owner-secrets.md).
+
+**The canvas.** The dashboard opens on a conversation, with a canvas beside
+it. What a run looked at is drawn there: a table, a chart, a document, a web
+page, an approval with its full envelope. It fills in live, and works the same
+for a mission that ran at 6am. [docs/browser.md](docs/browser.md) covers the
+browser views on it.
+
+**Claude Code.** `buddi mcp` runs buddi as an MCP server over stdio. Reads
+answer at once; every write becomes an approval card; `buddi.ask` talks to an
+agent. [docs/mcp.md](docs/mcp.md).
+
+```sh
+claude mcp add -s user buddi -- buddi mcp
+```
+
+---
+
+## Where your data lives and what leaves the machine
+
+Everything buddi owns sits in one data directory:
+
+| Platform | Data directory |
+| --- | --- |
+| macOS | `~/Library/Application Support/buddi` |
+| Linux | `$XDG_DATA_HOME/buddi`, else `~/.local/share/buddi` |
+
+`BUDDI_DATA_DIR` moves it. Inside are the Postgres cluster, your agents and
+skills, the files library, logs and backups. Nothing is written outside it
+except the service unit and, on macOS, the keychain entries.
+
+**Secrets** go in the vault: the macOS keychain, or the encrypted file vault on
+Linux. No command, page or tool prints one back.
+
+**Backups** hold the database, your agents and your files, and never a secret.
+They are encrypted with a six-word passphrase that only you keep. Turn on the
+nightly schedule in Settings → Backup, or with
+`buddi backup schedule install`.
+
+**What leaves.** Each agent's conversation, including what its tools returned,
+goes to the provider its file names, and nowhere else. A model is never
+switched for you, and delegating to another agent uses that agent's provider.
+Besides that, buddi makes two kinds of outbound call: a version check against
+the npm registry once a day, which you can turn off in Settings, and a plugin
+install when you ask for one. The dashboard loads nothing from the internet.
+There is no telemetry.
+
+[docs/operations.md](docs/operations.md) has the details: what an archive
+contains, the passphrase, restoring, and recovery.
+
+---
+
+## Everyday commands
+
+Most of this is on the dashboard. From a terminal:
+
+| Command | What it does |
+| --- | --- |
+| `buddi` | open the dashboard (the first run sets everything up) |
+| `buddi doctor` | check every moving part and say what is wrong |
+| `buddi service status` | is the background service running? `restart`, `logs`, `stop` too |
+| `buddi dashboard` | a five-minute sign-in link to the dashboard |
+| `buddi upgrade` | back up, install the new version, migrate, restart |
+| `buddi backup create --encrypt` | one archive now, sealed with your passphrase |
+| `buddi browser install` | download Chromium for the agents' browser |
+| `buddi agents` | every agent, its engine, and whether it can run |
+| `buddi chat` | talk to the default agent in the terminal |
+| `buddi ask "…"` | one question, one answer, then exit |
+| `buddi telegram pair` | a QR code that pairs a phone |
+| `buddi reminders` | what the agents have put on the clock |
+| `buddi plugins list` | what is installed |
+| `buddi mcp` | buddi as an MCP server, for Claude Code |
+
+`buddi help` prints them all. `buddi status` is `buddi doctor` under another
+name.
+
+---
+
+## Development
+
+The developer checkout runs the same code against a Postgres in Docker. You
+need git, Node 22 or newer, pnpm 11 and Docker.
+
+```sh
+git clone https://github.com/withbuddi/buddi && cd buddi
+./scripts/install.sh      # checks the tools, then pnpm install, build, link
+buddi init                # the terminal wizard: .env, database, service
+pnpm test
+```
+
+`./scripts/install.sh` runs `pnpm install`, `pnpm -r build` and
+`pnpm run link`, which puts a global `buddi` on your PATH that points at this
+checkout. `buddi init` is interactive and idempotent; `buddi init --yes` asks
+nothing. It starts the Postgres container, applies migrations, installs the
+service and opens the same wizard in the browser.
+
+Commands you will meet in a checkout:
+
+```sh
+buddi db up               # start the Postgres container after a reboot
+buddi db secure           # give it a generated password, kept in the vault
+buddi migrate             # apply core and plugin migrations
+buddi serve               # the gateway and scheduler in the foreground
+buddi vault set NAME      # put a secret in the vault (prompts, hidden)
+buddi plugins dev ../my-plugin
+buddi missions list
+buddi jobs --state failed
+buddi pause               # stop claiming work; running jobs finish
+buddi resume              # start claiming again
+buddi nudges status
+```
+
+To try the packaged install without touching your machine, `pnpm release:trial`
+builds the tarball, puts it in a Docker image and starts it on a fresh volume.
+`pnpm release:pack` builds only the tarball.
+
+**Layout.** Under `packages/`:
+
+- `core`: domain, database, event log, queue, the tool registry and the plugin
+  contract. It never imports a tool.
+- `runtime`: the agent loop and the provider adapters.
+- `gateway`: the surfaces (dashboard server, Telegram, terminal) and the
+  scheduler.
+- `web`: the dashboard, React and Vite, built to static files.
+- `cli`: the `buddi` binary for a checkout.
+- `install`: the packaged launcher, the supervisor and the bundled Postgres.
+- `extension`: the Chrome extension for the "Your browser" mode.
+- `tools/*`: the built-in plugins (artifacts, browser, email, host, memory,
+  web).
+
+The domain plugins (finance, developer, image) live in a separate repository,
+`buddi-plugins`, and install like any other plugin.
+
+**CI and releases.** A push to `main` runs the quick lane: four parallel jobs
+(web, gateway, typecheck, the rest), without a database. The full gate, with
+Postgres, runs on pull requests, nightly, on demand and before every release.
+A tag `v<version>` runs the gate, builds the tarball, publishes it to npm
+(pre-release versions under `next`, others under `latest`) and creates the
+GitHub release.
+
+Read next: [ARCHITECTURE.md](ARCHITECTURE.md) for the design,
+[docs/plugins.md](docs/plugins.md) to write a plugin, and
+[docs/README.md](docs/README.md) for the index of everything else. The roadmap
+is kept outside this repository.
+
+---
+
+## Status
+
+buddi is a 0.1 pre-release. macOS is the reference platform. Linux works and
+is in trial: the file vault, the bundled Postgres and the systemd user unit
+are built, and fixes land as the trial finds them. Windows is not supported
+yet. Native computer control (operating your own apps) is macOS-only. Signing
+in with a Claude subscription and ChatGPT accounts through Codex are
+experiments, off unless enabled
+([docs/anthropic-oauth.md](docs/anthropic-oauth.md),
+[docs/codex-accounts.md](docs/codex-accounts.md)). Host commands are approved,
+not sandboxed ([docs/host-execution.md](docs/host-execution.md)). Nothing an
+agent says is financial, legal or medical advice.
+
+## License
+
+[Apache License 2.0](LICENSE). Copyright 2026 withbuddi.