symbio 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+Notable changes to Symbio. The format follows [Keep a Changelog](https://keepachangelog.com/), and
+versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0]
+
+- Installable with `npm install -g symbio`; brings its own OpenCode (pinned to 2.1.x).
+- Commands: `sym` (start in the background and open), `sym stop`, `sym status`, `sym open`,
+  `sym logs`, `sym doctor`, `sym run`.
+- The projects page points to Settings → Model providers when no provider is connected.
+
+- Costs include sub-agents (OpenCode's own subagents such as "explore"), under their own model.
+- Daily housekeeping: backups of Symbio's state (last 7 days), a check for work that exists only on
+  this machine and for helpers' build outputs; the human and core are told, core can push and clean
+  with the new `clean_build_outputs` tool, and Project settings → Storage & backups shows it all.
+
+- Long chats load in pages: the latest messages first, earlier ones when scrolling up.
+- The loop guard only counts conversation (not task or asset traffic), is configurable per project
+  (Settings → Team) and tells the human when it blocks.
+- Usage per agent and model, including cache reads, earlier sessions and stopped agents, with an
+  estimated cost from editable model prices (Settings → Model prices).
+- Rename helpers; the old name keeps working.
+- Free shared assets are granted automatically; core only decides on contention.
+- Fresh sessions for long-running agents (button, or automatically after each merged task), with
+  a handoff note; earlier sessions stay readable.
+- Leftover helper folders of removed projects are cleaned up at startup.
+- After an update, each project's coordinator is told what changed for the agents (a note, it
+  isn't woken up); the human sees the same list in Messages.
+
+## [0.1.0]
+
+First version.
+
+- Projects from any folder: inspection, git setup, onboarding of existing folders, project docs in
+  the project or private.
+- core (lead agent) that scopes, plans, delegates, reviews and merges; helpers in their own git
+  worktrees; stop and restart helpers.
+- Messages between agents that wake the recipient; shared assets with core as gatekeeper.
+- Plan approval and an animated kanban; *Needs you* inbox for questions, approvals and
+  permission requests; pause and resume.
+- GitHub and SSH connections with an encrypted vault and optional per-action approval.
+- Model providers managed from Settings; allowed models per project; per-agent model switching;
+  automatic model fallback.
+- Supervisor, watchdog, memory recycling and tool re-registration for reliability.
+- Safety rules for agents: no killing processes by name, no reading SSH keys or secrets, installs
+  need approval.
+- Security: a UI key on every API request, protection against cross-site requests and DNS
+  rebinding, OpenCode's password kept out of agent shells, hardened GitHub push/pull, SSH host key
+  pinning, approvals stored outside the project, symlink-safe paths, debug routes off by default.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinKzy
+
+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,201 @@
-# Temporary Holding Version
-
-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.
+# Symbio
+
+**Run a team of AI agents on your project, from your browser.**
+
+Symbio is a local web app that coordinates several [OpenCode](https://opencode.ai) agents working on
+the same folder. You talk to one lead agent, **core**. It works out the scope with you, proposes a
+plan, and hands the work to helper agents, each in its own copy of the project. The agents message
+each other directly, ask you when they need a decision, and you watch it all happen on a live board.
+
+It isn't tied to software. A project is just a folder and a goal: code, a book, research, a data
+cleanup, a set of documents. Symbio provides the machinery (messaging, isolation, coordination,
+safety); the agents decide how to organize the work.
+
+![core summarizing the plan it proposed for a travel guidebook](docs/images/chat.png)
+
+> **Built with AI.** Symbio was designed and written in collaboration with AI coding agents, and
+> it's meant to be worked on the same way. The documentation for agents (and for humans who want the
+> details) lives in [`docs/`](docs/README.md); [`AGENTS.md`](AGENTS.md) is the entry point for a coding
+> agent opening this repository.
+
+---
+
+## A quick tour
+
+These screenshots come from a real session. The project is a pocket travel guide, *Lisbon on a
+Budget*, run on free models: the conversations, plan and messages were produced by the agents, not
+mocked.
+
+**1. Start from a folder.** Pick an empty folder for something new, or an existing one for core to
+study first. Symbio can set up version history so helpers can work side by side.
+
+![New project dialog](docs/images/new-project.png)
+
+**2. Approve the plan.** After asking a couple of questions, core proposes a plan with
+dependencies and declares the shared assets. Nothing starts until you approve.
+
+![A proposed plan waiting for approval](docs/images/plan-proposed.png)
+
+**3. core delegates.** It creates a helper for the first task and gives it a precise brief. The
+helper works on its own branch; the shared `notes` folder is held by it until it's done.
+
+![The researcher helper receiving its task from core](docs/images/researcher.png)
+
+**4. Follow the work.** The board moves by itself as helpers pick up, finish and hand in tasks.
+
+![The plan board with a task in progress](docs/images/plan.png)
+
+**5. See every message.** Requests, asset grants, plan updates and Symbio's own notices, all in one
+place. Here Symbio was restarted mid-task, and it told the helper to pick up where it left off.
+
+![Messages between core, the helper, you and Symbio](docs/images/messages.png)
+
+## What it does
+
+- **One conversation, a whole team.** You chat with core. It asks what you want, studies an
+  existing folder before touching it, and proposes a plan of tasks for you to approve.
+- **Helpers that work in parallel without collisions.** Each helper gets its own git worktree and
+  branch. core reviews and merges their work. Helpers are only created when work can really run in
+  parallel; one helper is the default.
+- **Agents talk to each other.** Messages go straight from agent to agent through Symbio, and
+  delivering a message wakes the recipient. No copy-pasting between terminals.
+- **Shared assets with a gatekeeper.** Anything several agents could change (a file pattern, a
+  database, a spreadsheet) can be declared a *shared asset*. Agents request it from core, wait for
+  the grant and release it when done. Changes to an asset an agent wasn't granted are flagged at
+  merge.
+- **A live plan.** The Plan tab is an animated kanban that moves by itself as helpers pick up
+  tasks, ask for review and get merged.
+- **You stay in control.** Questions, plan approvals, permission requests (like installing
+  software) and deploy approvals collect in a **Needs you** inbox. Pause one team or everything at
+  once.
+- **Connections without exposing secrets.** Give agents a GitHub account or an SSH server. They
+  ask Symbio to push, call the API or deploy, and Symbio does it with credentials the agents never
+  see. Each connection can require your approval for every action.
+- **Resilient.** A supervisor restarts OpenCode if it crashes, a watchdog unsticks hung agents, and
+  when a model fails (quota, outage) the agent switches to the next allowed model and carries on.
+- **Safety rails.** Agents can't kill processes by name (which would take down your terminals and
+  editors), can't read your SSH keys or Symbio's secret store, and must ask before installing
+  software.
+
+## Requirements
+
+- **Node.js 22+**
+- **Git** (recommended): it isolates helpers from each other. Without git, helpers share the folder
+  and rely on shared-asset grants alone.
+- A model provider: OpenCode's own, or any you connect in Symbio's **Settings → Model providers**
+  (API key or browser sign-in).
+
+Symbio brings its own copy of [OpenCode](https://opencode.ai), pinned to a version it's tested
+with, and runs it privately. It shares your OpenCode configuration and provider logins, so
+providers you already use in OpenCode show up in Symbio too.
+
+Symbio has been developed and used on **Windows 11**. It's written to be cross-platform (macOS and
+Linux are expected to work), but those haven't been tested yet. Reports are welcome.
+
+## Getting started
+
+```sh
+npm install -g symbio
+sym                  # starts Symbio in the background and opens it in your browser
+```
+
+Symbio opens its page with a private key in the link (it also prints the link). The browser
+remembers the key, so after that `http://127.0.0.1:4310` is enough. The key stops other programs
+on your computer, including the agents, from using Symbio's API behind your back.
+
+| Command | |
+|---|---|
+| `sym` | Start Symbio in the background and open it (or just open it, if it's running). Closing the terminal doesn't stop it. |
+| `sym stop` | Stop Symbio. Agents that were working pick up where they left off on the next start. |
+| `sym status` | Whether it's running, OpenCode's state, and each project's agents. |
+| `sym open` | Open Symbio in the browser. |
+| `sym logs` | The last lines of the log (`~/.symbio/logs/symbio.log`). |
+| `sym doctor` | Check Node.js, git, OpenCode, the port and model providers. |
+| `sym run` | Run in the foreground, with the log in the terminal. |
+
+`symbio` works too, as the long name of `sym`. To run from a clone instead: `npm install`,
+`npm run build`, then `npm link` once to get the commands.
+
+## How to use it
+
+1. **Connect your models.** Open **Settings → Model providers** and check that the providers you
+   use are there. Add one with an API key or a browser sign-in, and remove the ones you don't use
+   so the model list stays short.
+2. **Create a project.** On the Projects page, click **New project**:
+   - **Folder:** browse for or paste a folder. An empty folder starts a new project; an existing
+     one is studied first. Symbio offers to set up git if the folder doesn't have it.
+   - **Setup:** choose where the project documentation goes (in the project, or private), and which
+     connections (GitHub, servers) the agents may use.
+   - **Models:** pick the models agents may use, and the one core runs on (the crown).
+3. **Talk to core.** Describe what you want. core asks questions, proposes a plan, and waits for
+   your approval in the **Plan** tab (it shows a *Review* badge).
+4. **Watch and steer.** Helpers appear in the sidebar as core creates them. Click any agent to read
+   its conversation or message it directly, change its model from its header, or stop and restart
+   it. The **Messages** tab shows all traffic between agents.
+5. **Answer what needs you.** Questions, approvals and permission requests show up in **Needs you**
+   (top right) and in the relevant chat.
+
+### Words used in the app
+
+| Term | Meaning |
+|---|---|
+| **core** | The project's lead agent. It plans, delegates, reviews and merges; it coordinates rather than doing the work itself. |
+| **Helper** | An agent core creates for a piece of work. It works in its own git worktree (branch `symbio/<name>`). |
+| **Shared asset** | Something more than one agent could change. Access goes through core: request, grant, release. |
+| **Connection** | A GitHub account or SSH server agents can use through Symbio, without ever seeing its credentials. |
+| **Allowed models** | The models a project's agents may run on. If one fails, agents fall back to the next. |
+
+## Where your data lives
+
+| Location | What |
+|---|---|
+| `~/.symbio/config.json` | The list of projects |
+| `~/.symbio/connections.json` | Connection settings (no secrets) |
+| `~/.symbio/secrets.enc` | Connection secrets, encrypted with a key kept in your OS credential store |
+| `~/.symbio/worktrees/` | Helpers' working copies |
+| `~/.symbio/backups/` | Daily backups of Symbio's state (the last 7 days) |
+| `<project>/.symbio/` | Project state: agents, plan, message log, shared assets (git-ignored automatically) |
+| `<project>/AGENTS.md`, `<project>/docs/` | Project documentation for agents (unless you chose *private*) |
+| OpenCode's database | The conversations themselves. Every agent is an OpenCode session, so you can also open one with `opencode -s <session-id>`. |
+
+Symbio never deletes your project files. Removing a project from Symbio only forgets it, and can
+optionally delete its `.symbio/` folder.
+
+## Configuration
+
+All optional, set as environment variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `SYMBIO_PORT` | `4310` | Port for the UI and API (bound to 127.0.0.1 only) |
+| `SYMBIO_HOME` | `~/.symbio` | Where Symbio keeps its global data |
+| `SYMBIO_NO_OPEN` | | Set to `1` to not open the browser on start (use the link Symbio prints) |
+| `SYMBIO_DEBUG` | | Set to `1` to enable the read-only OpenCode debug routes (for development) |
+| `SYMBIO_OPENCODE_BIN` | bundled | Path to an `opencode` executable to use instead of the bundled one |
+| `SYMBIO_STUCK_MINUTES` | `10` | Silence before the watchdog interrupts a working agent |
+| `SYMBIO_RECYCLE_MB` | `1500` | Restart OpenCode above this memory use once every agent is idle |
+| `SYMBIO_RECYCLE_HARD_MB` | `3000` | Restart OpenCode above this memory use regardless (agents resume) |
+
+## Status
+
+Symbio is young (version 0.1) and changing quickly. The core workflow works end to end: projects,
+core and helpers, messaging, plan and kanban, shared assets, connections, providers, and recovery.
+Planned next: npm packaging with first-run checks, an agent graph, and screenshots for agents so
+they can see what they build. See [docs/roadmap.md](docs/roadmap.md).
+
+## Documentation
+
+- [docs/](docs/README.md): architecture, the agent protocol, the OpenCode API notes, development
+  and security. Written for both people and coding agents.
+- [AGENTS.md](AGENTS.md): the short entry point for an AI agent working on this repository.
+- [CONTRIBUTING.md](CONTRIBUTING.md): how to set up, make changes and open a pull request.
+- [SECURITY.md](SECURITY.md): how to report a vulnerability.
+
+## Contributing
+
+Contributions are welcome, whether you write the code yourself or with an AI agent. Start with
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © LinKzy

package/bin/symbio.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// symbio / sym — start, stop and inspect the local Symbio server.
+//
+//   sym            start in the background (or just open it, if it's running) and open the browser
+//   sym stop       stop it (agents are left as they are and pick up on the next start)
+//   sym status     is it running? where? which version?
+//   sym open       open it in the browser
+//   sym logs       the last lines of its log
+//   sym doctor     check that everything Symbio needs is in place
+//   sym run        run in the foreground (for debugging)
+
+import { execFileSync, exec, spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+const PORT = Number(process.env.SYMBIO_PORT ?? 4310);
+const HOME = process.env.SYMBIO_HOME ?? path.join(os.homedir(), ".symbio");
+const LOG = path.join(HOME, "logs", "symbio.log");
+const BASE = `http://127.0.0.1:${PORT}`;
+const server = path.join(root, "dist", "server", "index.js");
+
+const token = () => {
+  try {
+    return readFileSync(path.join(HOME, "ui-token"), "utf8").trim();
+  } catch {
+    return "";
+  }
+};
+const link = () => `${BASE}/?token=${token()}`;
+
+async function api(method, p) {
+  const res = await fetch(BASE + p, { method, headers: { "x-symbio-token": token() }, signal: AbortSignal.timeout(3000) });
+  return { status: res.status, body: await res.json().catch(() => null) };
+}
+
+/** "running" (ours), "other" (something else on the port) or "stopped". */
+async function state() {
+  try {
+    const r = await api("GET", "/api/runtime");
+    if (r.status === 200 || (r.status === 401 && r.body?.code === "locked")) return "running";
+    return "other";
+  } catch {
+    return "stopped";
+  }
+}
+
+function openBrowser(url) {
+  if (process.env.SYMBIO_NO_OPEN === "1") return;
+  const cmd = process.platform === "win32" ? `start "" "${url}"` : process.platform === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+  exec(cmd, () => {});
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function start() {
+  const s = await state();
+  if (s === "running") {
+    console.log(`Symbio is running: ${link()}`);
+    openBrowser(link());
+    return;
+  }
+  if (s === "other") {
+    console.error(`Port ${PORT} is used by another program. Start Symbio on another port: SYMBIO_PORT=4320 sym`);
+    process.exit(1);
+  }
+  if (!existsSync(server)) {
+    console.error(`Symbio isn't built (${server} is missing). Run "npm run build" in ${root}.`);
+    process.exit(1);
+  }
+  mkdirSync(path.dirname(LOG), { recursive: true });
+  const out = openSync(LOG, "a");
+  // Detached, so closing this terminal doesn't stop Symbio (or the agents' work).
+  const child = spawn(process.execPath, [server], {
+    detached: true,
+    stdio: ["ignore", out, out],
+    windowsHide: true,
+    env: { ...process.env, SYMBIO_NO_OPEN: "1" },
+  });
+  child.unref();
+  process.stdout.write("Starting Symbio");
+  for (let i = 0; i < 60; i++) {
+    await sleep(1000);
+    if ((await state()) === "running") {
+      console.log(`\nSymbio is running: ${link()}\nStop it with "sym stop". Log: ${LOG}`);
+      openBrowser(link());
+      return;
+    }
+    process.stdout.write(".");
+  }
+  console.error(`\nSymbio didn't come up within a minute. See the log: ${LOG}`);
+  process.exit(1);
+}
+
+async function stop() {
+  if ((await state()) !== "running") return console.log("Symbio isn't running.");
+  await api("POST", "/api/shutdown").catch(() => {});
+  for (let i = 0; i < 30; i++) {
+    await sleep(500);
+    if ((await state()) === "stopped") return console.log("Symbio stopped. Agents that were working continue on the next start.");
+  }
+  console.error("Symbio didn't stop within 15 seconds.");
+  process.exit(1);
+}
+
+async function status() {
+  const s = await state();
+  console.log(`Symbio ${pkg.version} — ${s === "running" ? `running at ${BASE}` : s === "other" ? `port ${PORT} is used by another program` : "not running"}`);
+  if (s !== "running") return;
+  const runtime = (await api("GET", "/api/runtime")).body;
+  const projects = (await api("GET", "/api/projects")).body ?? [];
+  console.log(`OpenCode ${runtime?.version ?? "?"} (${runtime?.state ?? "?"}${runtime?.memoryMB ? `, ${runtime.memoryMB} MB` : ""})`);
+  for (const p of projects) {
+    const working = p.agents.filter((a) => a.status === "busy").length;
+    console.log(`- ${p.name}: ${p.agents.filter((a) => a.status !== "stopped").length} agents${working ? `, ${working} working` : ""}${p.paused ? " (paused)" : ""}`);
+  }
+}
+
+function logs() {
+  if (!existsSync(LOG)) return console.log(`No log yet (${LOG}).`);
+  const lines = readFileSync(LOG, "utf8").split(/\r?\n/);
+  console.log(lines.slice(-60).join("\n").replace(/token=[\w-]+/g, "token=…"));
+  console.log(`\n(${LOG})`);
+}
+
+async function doctor() {
+  let ok = true;
+  const check = (pass, label, fix) => {
+    console.log(`${pass ? "✔" : "✘"} ${label}${!pass && fix ? `\n    → ${fix}` : ""}`);
+    if (!pass) ok = false;
+  };
+  const [major] = process.versions.node.split(".").map(Number);
+  check(major >= 22, `Node.js ${process.versions.node}`, "Symbio needs Node.js 22 or newer: https://nodejs.org");
+  let gitVersion = "";
+  try {
+    gitVersion = execFileSync("git", ["--version"], { encoding: "utf8" }).trim();
+  } catch {}
+  check(!!gitVersion, gitVersion || "git", "Install git (https://git-scm.com) so helpers can work in parallel without conflicts.");
+  let oc = "";
+  try {
+    const { resolveOpencode } = await import(pathToFileURL(path.join(root, "dist", "server", "opencode", "runtime.js")).href);
+    const { command, args, shell } = resolveOpencode();
+    oc = `${execFileSync(command, [...args, "--version"], { encoding: "utf8", shell, timeout: 20_000 }).trim()} (${command})`;
+  } catch {}
+  check(!!oc, oc ? `OpenCode ${oc}` : "OpenCode", "Reinstall Symbio (npm i -g symbio): it brings its own OpenCode.");
+  const s = await state();
+  check(s !== "other", s === "running" ? `Symbio running at ${BASE}` : s === "stopped" ? `Port ${PORT} free` : `Port ${PORT}`, `Another program uses port ${PORT}; use SYMBIO_PORT.`);
+  if (s === "running") {
+    const providers = (await api("GET", "/api/providers").catch(() => ({ body: null }))).body;
+    const n = providers?.connected?.length ?? 0;
+    check(n > 0, `${n} model provider(s) connected`, "Open Symbio → Settings → Model providers and connect one.");
+  }
+  console.log(ok ? "\nAll good." : "\nFix the items marked ✘.");
+  if (!ok) process.exitCode = 1;
+}
+
+function help() {
+  console.log(`Symbio ${pkg.version} — run a team of AI agents on your project, from your browser.
+
+Usage: sym [command]
+
+  (none), start   start Symbio in the background and open it in the browser
+  stop            stop Symbio
+  status          show whether it's running, and its projects
+  open            open Symbio in the browser
+  logs            show the last lines of the log
+  doctor          check that everything Symbio needs is in place
+  run             run in the foreground (logs in this terminal)
+  --version       print the version
+
+Environment: SYMBIO_PORT (default 4310), SYMBIO_HOME (default ~/.symbio), SYMBIO_NO_OPEN=1.`);
+}
+
+const cmd = process.argv[2] ?? "start";
+switch (cmd) {
+  case "start":
+    await start();
+    break;
+  case "stop":
+    await stop();
+    break;
+  case "status":
+    await status();
+    break;
+  case "open":
+    if ((await state()) === "running") {
+      console.log(link());
+      openBrowser(link());
+    } else console.log('Symbio isn\'t running. Start it with "sym".');
+    break;
+  case "logs":
+    logs();
+    break;
+  case "doctor":
+    await doctor();
+    break;
+  case "run":
+    await import(pathToFileURL(server).href);
+    break;
+  case "-v":
+  case "--version":
+  case "version":
+    console.log(pkg.version);
+    break;
+  case "-h":
+  case "--help":
+  case "help":
+    help();
+    break;
+  default:
+    console.error(`Unknown command "${cmd}".\n`);
+    help();
+    process.exit(1);
+}