xqo 3.0.0__tar.gz

xqo-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dudikkocak
+
+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.

xqo-3.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: xqo
+Version: 3.0.0
+Summary: xqo: a small, plugin-based HQ of Claude agents with a live dashboard and a 2D / 3D office
+Author: dudikkocak
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dudikkocak/xqo
+Project-URL: Issues, https://github.com/dudikkocak/xqo/issues
+Keywords: claude,agents,llm,orchestration,dashboard
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=2.2.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: httpx>=0.27
+Requires-Dist: claude-agent-sdk>=0.2.170
+Provides-Extra: sqlite
+Requires-Dist: xqo-sqlite==3.0.0; extra == "sqlite"
+Provides-Extra: postgres
+Requires-Dist: xqo-postgres==3.0.0; extra == "postgres"
+Provides-Extra: docker
+Requires-Dist: xqo-docker==3.0.0; extra == "docker"
+Provides-Extra: all
+Requires-Dist: xqo-sqlite==3.0.0; extra == "all"
+Requires-Dist: xqo-postgres==3.0.0; extra == "all"
+Requires-Dist: xqo-docker==3.0.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# xqo
+
+A small, plugin-based HQ of Claude agents: agents take tasks, hand work to each other by skill, run code in a
+sandbox and ask you when they need a decision, all on a live dashboard with a 2D / 3D office view.
+
+The `xqo` package is the **core** (agents, safety, dashboard), the **office** plugin and the **Claude Agent SDK**,
+with events stored in **jsonl**. Everything else is a plugin package you install when you need it:
+
+| Package | Adds |
+|---|---|
+| `xqo-schedules` | cron / every / at tasks |
+| `xqo-feeds` | system, logs, files, journald, docker and push feeds that wake agents (needs schedules) |
+| `xqo-channels` | Telegram, WhatsApp, Instagram, X, Threads, Gmail, SMS |
+| `xqo-peering` | other HQs through an exchange folder or HTTP |
+| `xqo-toolchains` | Node / Go / Rust / .NET setup for `run_code` |
+| `xqo-docker` | the Docker sandbox backend for `run_code` |
+| `xqo-agency` | `xqo agency`: import agents from agency-agents |
+| `xqo-sqlite`, `xqo-postgres` | other event stores |
+
+`pip install "xqo[all]"` installs every plugin. The plugin packages are being published one by one; until a
+package is out, its feature is not available.
+
+A plugin that is not installed is a **warning**, never an error (also with `"strict": true`): its config keys
+(`schedules`, `channels`, `feeds`, `feed_rules`, `peering`) are ignored, the warning names the `pip install`
+command, and the HQ starts. A `"storage"` backend or a `"sandbox"` backend that is not installed still stops
+startup with the reason: events in another store are never silently shown as empty, and code never runs without
+the isolation you asked for.
+
+## Quick start
+
+```bash
+pip install xqo                    # core + office + Claude Agent SDK (mcp comes with it)
+xqo init                           # writes a starter agents.json (+ departments/)
+xqo agents.json                    # = xqo --config agents.json serve  ->  http://127.0.0.1:8000
+xqo --mock --config agents.json serve   # offline, scripted model: no API key needed
+```
+
+A basic HQ (one office, 2D office only, no Docker, Claude Agent SDK by default, Anthropic / OpenAI APIs where an
+agent asks for them) is in [examples/basic/agents.json](examples/basic/agents.json):
+
+```bash
+xqo examples/basic/agents.json check   # loads it, lists the plugins and the missing environment variables
+xqo examples/basic/agents.json         # serve
+```
+
+Docker (Linux / macOS / WSL2: `./docker-startup.sh`, Windows: `docker-startup.bat`): [docs/DOCKER.md](docs/DOCKER.md),
+Claude Agent SDK sign-in in Docker: [docs/CLAUDE-SDK.md](docs/CLAUDE-SDK.md).
+
+## Core and plugins
+
+| Core (always there) | Plugins (`xqo/plugins/`) |
+|---|---|
+| message bus, event log (jsonl), replay & fork | **office**: `/office`, 2D and/or 3D, editor *(on by default)* |
+| agent loops: Claude Agent SDK (default), Anthropic API, OpenAI-compatible, Ollama | |
+| workspaces, versions, git, attachments, notes | |
+| chat, attention (requests + alerts, one inbox), reports | |
+| departments, grants, skills, network grants, limits, budgets | |
+| sandbox with the `local` backend (Python venvs), MCP hub | |
+| dashboard, task lifecycle (archive + trash), limits, backup, drain, check | |
+
+Turning plugins off:
+
+```json
+"plugins": {"disable": ["office"], "strict": false}
+```
+
+`/api/plugins` (and `/api/health`, `xqo check`, the `serve` banner) lists every plugin as **active**,
+**inactive** (not configured), **disabled**, **missing** (not installed, or its module can't be imported; a
+warning) or **failed** with the reason. A failed plugin's routes, tools and
+dashboard buttons disappear; startup goes on. `"strict": true`, `XQO_STRICT=1` and `xqo check` turn plugin
+errors back into startup errors. Security settings (grants, network grants, limits, departments) are core and
+always fail closed.
+
+Writing a plugin (its own pip package, importing only `xqo.api`), a storage or sandbox backend or dashboard UI:
+see [PLUGINS.md](PLUGINS.md).
+
+## Judged fit (optional)
+
+Skill match stays the free first filter. With `"offer_judge": {"enabled": true, "model": "claude-haiku-5-5"}` a small model is asked only when two or more offers **tie** or the task is **large** (`large_chars`, default 2000), and it only affects who gets the handover. Prompt caching (shared prefix) and an in-memory fit cache (`cache_ttl`) keep the cost down; any failure falls back to the free ranking. Details: [docs/REFERENCE.md](docs/REFERENCE.md) (Departments → Judged fit).
+
+## Storage
+
+Events go to `logs/events.jsonl`, one line per event (`"storage": {"backend": "jsonl", "path": "events.jsonl"}`;
+`path` is optional and relative to `logs/`). `xqo-sqlite` and `xqo-postgres` add `"backend": "sqlite"` and
+`"backend": "postgres"`.
+
+- Every task is restored at startup, whatever its age; only the recent 5000 events are kept in memory for the
+  live views (older events load on demand, e.g. a task's full history or `/api/tasks?roots=true&limit=50&offset=50`).
+- A backend that is not installed, or can't open, stops startup with the reason. `XQO_STORAGE` overrides
+  `"backend"` for one run.
+
+## Docs
+
+- [docs/REFERENCE.md](docs/REFERENCE.md): every feature in detail (commands are `xqo …`)
+- [docs/SETUP.md](docs/SETUP.md), [docs/OPERATIONS.md](docs/OPERATIONS.md): install, upgrade, backup

xqo-3.0.0/README.md

@@ -0,0 +1,95 @@
+# xqo
+
+A small, plugin-based HQ of Claude agents: agents take tasks, hand work to each other by skill, run code in a
+sandbox and ask you when they need a decision, all on a live dashboard with a 2D / 3D office view.
+
+The `xqo` package is the **core** (agents, safety, dashboard), the **office** plugin and the **Claude Agent SDK**,
+with events stored in **jsonl**. Everything else is a plugin package you install when you need it:
+
+| Package | Adds |
+|---|---|
+| `xqo-schedules` | cron / every / at tasks |
+| `xqo-feeds` | system, logs, files, journald, docker and push feeds that wake agents (needs schedules) |
+| `xqo-channels` | Telegram, WhatsApp, Instagram, X, Threads, Gmail, SMS |
+| `xqo-peering` | other HQs through an exchange folder or HTTP |
+| `xqo-toolchains` | Node / Go / Rust / .NET setup for `run_code` |
+| `xqo-docker` | the Docker sandbox backend for `run_code` |
+| `xqo-agency` | `xqo agency`: import agents from agency-agents |
+| `xqo-sqlite`, `xqo-postgres` | other event stores |
+
+`pip install "xqo[all]"` installs every plugin. The plugin packages are being published one by one; until a
+package is out, its feature is not available.
+
+A plugin that is not installed is a **warning**, never an error (also with `"strict": true`): its config keys
+(`schedules`, `channels`, `feeds`, `feed_rules`, `peering`) are ignored, the warning names the `pip install`
+command, and the HQ starts. A `"storage"` backend or a `"sandbox"` backend that is not installed still stops
+startup with the reason: events in another store are never silently shown as empty, and code never runs without
+the isolation you asked for.
+
+## Quick start
+
+```bash
+pip install xqo                    # core + office + Claude Agent SDK (mcp comes with it)
+xqo init                           # writes a starter agents.json (+ departments/)
+xqo agents.json                    # = xqo --config agents.json serve  ->  http://127.0.0.1:8000
+xqo --mock --config agents.json serve   # offline, scripted model: no API key needed
+```
+
+A basic HQ (one office, 2D office only, no Docker, Claude Agent SDK by default, Anthropic / OpenAI APIs where an
+agent asks for them) is in [examples/basic/agents.json](examples/basic/agents.json):
+
+```bash
+xqo examples/basic/agents.json check   # loads it, lists the plugins and the missing environment variables
+xqo examples/basic/agents.json         # serve
+```
+
+Docker (Linux / macOS / WSL2: `./docker-startup.sh`, Windows: `docker-startup.bat`): [docs/DOCKER.md](docs/DOCKER.md),
+Claude Agent SDK sign-in in Docker: [docs/CLAUDE-SDK.md](docs/CLAUDE-SDK.md).
+
+## Core and plugins
+
+| Core (always there) | Plugins (`xqo/plugins/`) |
+|---|---|
+| message bus, event log (jsonl), replay & fork | **office**: `/office`, 2D and/or 3D, editor *(on by default)* |
+| agent loops: Claude Agent SDK (default), Anthropic API, OpenAI-compatible, Ollama | |
+| workspaces, versions, git, attachments, notes | |
+| chat, attention (requests + alerts, one inbox), reports | |
+| departments, grants, skills, network grants, limits, budgets | |
+| sandbox with the `local` backend (Python venvs), MCP hub | |
+| dashboard, task lifecycle (archive + trash), limits, backup, drain, check | |
+
+Turning plugins off:
+
+```json
+"plugins": {"disable": ["office"], "strict": false}
+```
+
+`/api/plugins` (and `/api/health`, `xqo check`, the `serve` banner) lists every plugin as **active**,
+**inactive** (not configured), **disabled**, **missing** (not installed, or its module can't be imported; a
+warning) or **failed** with the reason. A failed plugin's routes, tools and
+dashboard buttons disappear; startup goes on. `"strict": true`, `XQO_STRICT=1` and `xqo check` turn plugin
+errors back into startup errors. Security settings (grants, network grants, limits, departments) are core and
+always fail closed.
+
+Writing a plugin (its own pip package, importing only `xqo.api`), a storage or sandbox backend or dashboard UI:
+see [PLUGINS.md](PLUGINS.md).
+
+## Judged fit (optional)
+
+Skill match stays the free first filter. With `"offer_judge": {"enabled": true, "model": "claude-haiku-5-5"}` a small model is asked only when two or more offers **tie** or the task is **large** (`large_chars`, default 2000), and it only affects who gets the handover. Prompt caching (shared prefix) and an in-memory fit cache (`cache_ttl`) keep the cost down; any failure falls back to the free ranking. Details: [docs/REFERENCE.md](docs/REFERENCE.md) (Departments → Judged fit).
+
+## Storage
+
+Events go to `logs/events.jsonl`, one line per event (`"storage": {"backend": "jsonl", "path": "events.jsonl"}`;
+`path` is optional and relative to `logs/`). `xqo-sqlite` and `xqo-postgres` add `"backend": "sqlite"` and
+`"backend": "postgres"`.
+
+- Every task is restored at startup, whatever its age; only the recent 5000 events are kept in memory for the
+  live views (older events load on demand, e.g. a task's full history or `/api/tasks?roots=true&limit=50&offset=50`).
+- A backend that is not installed, or can't open, stops startup with the reason. `XQO_STORAGE` overrides
+  `"backend"` for one run.
+
+## Docs
+
+- [docs/REFERENCE.md](docs/REFERENCE.md): every feature in detail (commands are `xqo …`)
+- [docs/SETUP.md](docs/SETUP.md), [docs/OPERATIONS.md](docs/OPERATIONS.md): install, upgrade, backup

xqo-3.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xqo"
+dynamic = ["version"]
+description = "xqo: a small, plugin-based HQ of Claude agents with a live dashboard and a 2D / 3D office"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "dudikkocak"}]
+keywords = ["claude", "agents", "llm", "orchestration", "dashboard"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "anthropic>=2.2.0",
+  "fastapi>=0.110",
+  "uvicorn>=0.29",
+  "httpx>=0.27",
+  "claude-agent-sdk>=0.2.170",   # agents run as Claude Code sessions; also brings the mcp package
+]
+
+[project.optional-dependencies]
+# One extra per plugin package, pinned to this release (all = every xqo-* plugin); more come with each phase.
+sqlite = ["xqo-sqlite==3.0.0"]
+postgres = ["xqo-postgres==3.0.0"]
+docker = ["xqo-docker==3.0.0"]
+all = ["xqo-sqlite==3.0.0", "xqo-postgres==3.0.0", "xqo-docker==3.0.0"]
+dev = ["pytest>=8", "pytest-timeout>=2.3", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/dudikkocak/xqo"
+Issues = "https://github.com/dudikkocak/xqo/issues"
+
+[project.scripts]
+xqo = "xqo.__main__:main"
+
+[tool.setuptools]
+packages = {find = {include = ["xqo*"]}}
+
+[tool.setuptools.dynamic]
+version = {attr = "xqo.__version__"}
+
+[tool.setuptools.package-data]
+xqo = ["static/*", "static/js/*", "static/vendor/*", "static/vendor/fonts/*", "default_agents.json", "default_departments/*", "plugins/office/static/*", "plugins/office/static/office/*/*", "plugins/office/static/office3d/*", "plugins/office/static/office3d/*/*", "plugins/office/static/office3d/*/*/*", "plugins/office/static/vendor/miniverse/*", "plugins/office/static/vendor/three/*", "plugins/office/static/vendor/three/addons/*/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 60

xqo-3.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xqo-3.0.0/tests/test_alerts.py

@@ -0,0 +1,129 @@
+"""Attention alerts: questions, errors, finished root tasks and auto-answered questions stay until dealt with."""
+import asyncio
+from types import SimpleNamespace as NS
+
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+from xqo.agent import Agent
+from xqo.artifacts import ArtifactStore
+from xqo.bus import MessageBus
+from xqo.config import build
+from xqo.models import Event, Task
+from xqo.web import create_app
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def text(t):
+    return NS(content=[NS(type="text", text=t)], stop_reason="end_turn", usage=None, model="m")
+
+
+def tool(name, **inp):
+    return NS(content=[NS(type="tool_use", id=f"t_{name}", name=name, input=inp)],
+              stop_reason="tool_use", usage=None, model="m")
+
+
+class Script:
+    def __init__(self, fn):
+        self.fn = fn
+
+    async def create(self, *, messages, **_):
+        return self.fn(sum(1 for m in messages if m["role"] == "assistant"), messages)
+
+
+def make(tmp_path, fn, timeout=0.2):
+    store = ArtifactStore(tmp_path / "art")
+    b = MessageBus(tmp_path / "ev.jsonl")
+    b.artifacts = store
+    b.attention.timeout = timeout
+    b.register(Agent("a", ["x"], "sys", Script(fn), store))
+    return b
+
+
+def asker(turn, msgs):
+    if turn == 0:
+        return tool("ask_user", question="Deploy?", reason="approval", options=["yes", "no"], default="no")
+    return text("ok")
+
+
+def test_finished_root_task_alerts_until_dismissed(tmp_path):
+    b = make(tmp_path, lambda turn, m: text("done!"))
+    t = asyncio.run(b.submit("go"))
+    al = b.attention.alerts_pending()
+    assert [a.kind for a in al] == ["done"] and al[0].agent == "a" and al[0].root_id == t.id
+    assert b.attention.by_agent() == {"a": {"count": 1, "kinds": ["done"]}}
+    assert b.attention.ack() == [al[0].id] and not b.attention.alerts_pending()
+    # survives a restart: the dismissal is logged too
+    assert not MessageBus(tmp_path / "ev.jsonl").attention.alerts_pending()
+
+
+def test_alerts_survive_a_restart(tmp_path):
+    b = make(tmp_path, lambda turn, m: text("done!"))
+    asyncio.run(b.submit("go"))
+    assert [a.kind for a in MessageBus(tmp_path / "ev.jsonl").attention.alerts_pending()] == ["done"]
+
+
+def test_auto_confirmed_question_keeps_alerting(tmp_path):
+    b = make(tmp_path, asker)
+    asyncio.run(b.submit("go"))
+    kinds = sorted(a.kind for a in b.attention.alerts_pending())
+    assert kinds == ["auto_confirmed", "done"]
+    auto = next(a for a in b.attention.alerts_pending() if a.kind == "auto_confirmed")
+    assert "'no' was taken" in auto.text
+
+
+def test_answered_question_clears_its_alert(tmp_path):
+    b = make(tmp_path, asker, timeout=30)
+
+    async def go():
+        job = asyncio.create_task(b.submit("go"))
+        while not b.attention.pending():
+            await asyncio.sleep(0.01)
+        assert [a.kind for a in b.attention.alerts_pending()] == ["attention"]
+        assert b.attention.ack() == []  # an open question stays until it is answered
+        b.attention.resolve(b.attention.pending()[0].id, "yes")
+        return await job
+
+    asyncio.run(go())
+    assert [a.kind for a in b.attention.alerts_pending()] == ["done"]
+
+
+def test_errors_alert_and_subtasks_do_not_alert_when_done(tmp_path):
+    b = MessageBus(tmp_path / "ev.jsonl")
+    b.tasks["t1"] = Task("p", "a", id="t1", root_id="t1")
+    b.tasks["t2"] = Task("p", "b", parent_id="t1", id="t2", root_id="t1")
+    b.emit(Event("error", "a", "user", "t1", None, "Boom"))
+    b.emit(Event("done", "b", "a", "t2", "t1", "sub done", {"status": "done"}))  # a sub-task: no alert
+    al = b.attention.alerts_pending()
+    assert [a.kind for a in al] == ["error"] and al[0].text == "Boom"
+
+
+def test_cancelled_tasks_and_unattended_runs_do_not_alert(tmp_path):
+    b = MessageBus(tmp_path / "ev.jsonl")
+    b.emit(Event("done", "a", "user", "t1", None, "Cancelled", {"status": "cancelled"}))
+    assert not b.attention.alerts_pending()
+    b.emit(Event("attention_requested", "a", "user", "t1", None, "q?", {"id": "att_1", "timeout": 0, "agent": "a"}))
+    assert not b.attention.alerts_pending()
+
+
+def test_deleting_or_reopening_a_task_clears_its_alerts(tmp_path):
+    b = MessageBus(tmp_path / "ev.jsonl")
+    b.emit(Event("done", "a", "user", "t1", None, "ok", {"status": "done"}))
+    b.emit(Event("error", "a", "user", "t2", None, "bad"))
+    b.emit(Event("task_reopened", "user", None, "t1", None, ""))
+    b.emit(Event("task_deleted", "user", None, "t2", None, ""))
+    assert not b.attention.alerts_pending()
+
+
+def test_api(tmp_path):
+    b = build(ROOT / "agents.json", tmp_path / "art", str(tmp_path / "ev.jsonl"), mock=True)
+    name = next(iter(b.agents))
+    b.emit(Event("done", name, "user", "t1", None, "ok", {"status": "done"}))
+    with TestClient(create_app(b)) as c:
+        r = c.get("/api/alerts").json()
+        assert [a["kind"] for a in r["items"]] == ["done"] and r["by_agent"][name]["count"] == 1
+        assert next(a for a in c.get("/api/agents").json() if a["name"] == name)["alerts"]["count"] == 1
+        assert c.post("/api/alerts/ack", json={"agent": name}).json()["acked"] == [r["items"][0]["id"]]
+        assert c.get("/api/alerts").json()["items"] == []