edgecitadel 0.1.0__tar.gz

edgecitadel-0.1.0/.env.example

@@ -0,0 +1,32 @@
+NATS_TOKEN=change-me
+NATS_LEAF_USERNAME=change-me-leaf-user
+NATS_LEAF_PASSWORD=change-me-leaf-password
+OPENCLAW_TOKEN=change-me-scoped
+EDGECITADEL_ADMIN_TOKEN=change-me-admin
+# Set EC_ENABLE_MQTT=1 before running scripts/render-nats-conf.sh to
+# enable deploy-time MQTT ingress. Default off.
+EC_ENABLE_MQTT=0
+
+# Gemma adapter (Phase 2). See adapters/gemma/README.md.
+OLLAMA_HOST=localhost
+OLLAMA_PORT=11434
+# Default: gemma4:e2b (smallest "efficient" variant, ~2B params).
+# To switch, set OLLAMA_MODEL to one of:
+#   gemma4:e2b   — efficient 2B (default; lowest VRAM, fastest)
+#   gemma4:e4b   — efficient 4B (better reasoning, ~2× memory)
+#   gemma4:26b   — full 26B (Mac Mini-class hosts only)
+#   gemma4:31b   — full 31B (workstation/A100-class)
+# Pull first:  ollama pull <tag>
+OLLAMA_MODEL=gemma4:e2b
+OLLAMA_TIMEOUT_SEC=120
+
+# Watchdog adapter (Phase 3.1)
+# Override only for tests that can't wait the production thresholds.
+# Defaults: floor=20s, tolerance=5s, check cadence=5s.
+# WATCHDOG_THRESHOLD_FLOOR_SEC=2
+# WATCHDOG_TOLERANCE_SEC=1
+# WATCHDOG_CHECK_CADENCE_SEC=1
+
+# Phase 2.5 conversational memory (aggregator-owned SQLite + NATS API)
+# Override only for tests / staging. Default 30 days = 2592000 seconds.
+# MEMORY_RETENTION_SEC=2592000

edgecitadel-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Node
+node_modules/
+frontend/dist/
+.vite/
+
+# Data
+data/*.db
+data/*.sqlite
+data/research/
+!data/.gitkeep
+nats/data/
+
+# Claude Code local settings
+.claude/.claude/
+.claude/settings.local.json
+.claude/*.local.md
+CLAUDE.local.md
+
+# Environment
+.env
+.env.local
+.env.production
+
+# OpenClaw client config (contains secrets)
+openclaw-client/openclaw.conf
+openclaw-client/agent.env
+openclaw-client/node_modules/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+test-artifacts/
+e2e/test-results/
+e2e/playwright-report/
+tmp/e2e/
+tmp/operator-evidence*/
+
+# Raw video (keep only final mp4/gif)
+docs/demo-raw.webm
+
+# Docker
+*.log
+
+# Git worktrees
+.worktrees/
+
+# Superpowers — keep all brainstorm/spec/plan artifacts local-only.
+# Visual companion mockups:
+.superpowers/
+# Design specs and implementation plans (per-developer working artifacts):
+docs/superpowers/
+adapters/*/agent.env
+
+# Phase 5: deploy script's runtime log files (the deploy script writes timestamped logs)
+deploy/*.log
+
+# Operator note: scheduled tasks lock from claude harness
+.claude/scheduled_tasks.lock
+
+# Frontend dev-only configs (developer working artifacts; not part of the
+# canonical vite config). e.g. vite.config.prodproxy.js — points the local
+# dev server at a remote aggregator for ad-hoc verification.
+frontend/vite.config.*.js
+!frontend/vite.config.js
+
+# E2E manual probes — one-off browser-driven scripts that target real
+# (often production) data. Not part of the regular Playwright suite.
+e2e/scripts/

edgecitadel-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: edgecitadel
+Version: 0.1.0
+Summary: Create, join, and operate an EdgeCitadel agent network
+Project-URL: Homepage, https://github.com/zhonghaozhan/EdgeCitadel
+Project-URL: Repository, https://github.com/zhonghaozhan/EdgeCitadel
+Author: EdgeCitadel contributors
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# EdgeCitadel
+
+EdgeCitadel connects AI Agents across a Core and enrolled Edge hosts. It runs
+complete Managed Agents such as Gemma and Home Assistant adapters, and connects
+active Pi, Claude Code, and Codex sessions through their native plugin systems.
+
+## Install
+
+Choose one method:
+
+```bash
+pip install edgecitadel
+# or
+brew install edgecitadel
+```
+
+Verify it with `edgecitadel --version`.
+
+## Create a Core
+
+Start Docker, then choose a hostname or IP that Edge hosts can reach:
+
+```bash
+edgecitadel create --host core.example.internal
+edgecitadel doctor
+```
+
+The command checks local requirements and prints the dashboard URL.
+
+## Join an Edge
+
+Create a one-time invitation on the Core:
+
+```bash
+edgecitadel invite --node-id studio-macmini --host core.example.internal
+```
+
+Run the returned `edgecitadel join` command on the Edge. The default
+`single-client` mode connects the EdgeCitadel service directly to Core NATS:
+
+```bash
+edgecitadel join 'ecjoin://...'
+```
+
+Use `nats_leaf` when Agents on this host must keep communicating while the Core
+connection is unavailable:
+
+```bash
+brew install nats-server  # macOS; use your system package manager elsewhere
+edgecitadel join 'ecjoin://...' --messaging-mode nats_leaf
+```
+
+In both modes, Agent integrations talk to the host-local EdgeCitadel service.
+Only `nats_leaf` needs a local NATS server; it is the durable local message bus
+and maintains the outbound Leaf connection to Core.
+
+## Install a Managed Agent
+
+Managed Agents are complete runtimes operated by EdgeCitadel:
+
+```bash
+edgecitadel agent install gemma
+edgecitadel agent list
+edgecitadel agent status edgecitadel.gemma
+```
+
+Home Assistant is installed the same way after its URL, token, and allowlist are
+configured. EdgeCitadel operates the adapter and never installs or removes Home
+Assistant itself. See the [Gemma guide](plugins/gemma/README.md) and
+[Home Assistant guide](plugins/homeassistant/README.md).
+
+## Connect an existing Agent
+
+These plugins add Agent discovery, delegation, inbox, task-state, trace, and
+diagnostic tools to an active host session. They do not start the host in the
+background, and EdgeCitadel does not pass NATS credentials through the plugin
+protocol.
+
+```bash
+# Pi
+pi install "$(edgecitadel connector path pi)"
+
+# Claude Code
+claude plugin marketplace add "$(edgecitadel connector path claude-code)"
+claude plugin install edgecitadel@edgecitadel
+
+# Codex
+codex plugin marketplace add "$(edgecitadel connector path codex)"
+codex plugin add edgecitadel@edgecitadel
+```
+
+Start a new host session, then use its `edgecitadel_*` tools. Inspect active
+connections with `edgecitadel connector list` and `edgecitadel connector status
+<connector-id>`.
+
+## Operate
+
+```bash
+edgecitadel status
+edgecitadel doctor
+edgecitadel service status
+edgecitadel task list --connector-id <connector-id>
+edgecitadel trace list --connector-id <connector-id>
+```
+
+Stop a Core without deleting its data with `edgecitadel down`.
+
+## Upgrade or uninstall
+
+Use the package manager that installed EdgeCitadel:
+
+```bash
+pip install --upgrade edgecitadel
+pip uninstall edgecitadel
+
+brew upgrade edgecitadel
+brew uninstall edgecitadel
+```
+
+Before uninstalling an Edge, run `edgecitadel service stop`; in `nats_leaf`
+mode also run `edgecitadel messaging stop`. Uninstall preserves local state in
+`~/.edgecitadel`.
+
+More detail: [onboarding and troubleshooting](docs/onboarding.md) and
+[contributing](CONTRIBUTING.md).
+
+## License
+
+MIT

edgecitadel-0.1.0/README.md

@@ -0,0 +1,129 @@
+# EdgeCitadel
+
+EdgeCitadel connects AI Agents across a Core and enrolled Edge hosts. It runs
+complete Managed Agents such as Gemma and Home Assistant adapters, and connects
+active Pi, Claude Code, and Codex sessions through their native plugin systems.
+
+## Install
+
+Choose one method:
+
+```bash
+pip install edgecitadel
+# or
+brew install edgecitadel
+```
+
+Verify it with `edgecitadel --version`.
+
+## Create a Core
+
+Start Docker, then choose a hostname or IP that Edge hosts can reach:
+
+```bash
+edgecitadel create --host core.example.internal
+edgecitadel doctor
+```
+
+The command checks local requirements and prints the dashboard URL.
+
+## Join an Edge
+
+Create a one-time invitation on the Core:
+
+```bash
+edgecitadel invite --node-id studio-macmini --host core.example.internal
+```
+
+Run the returned `edgecitadel join` command on the Edge. The default
+`single-client` mode connects the EdgeCitadel service directly to Core NATS:
+
+```bash
+edgecitadel join 'ecjoin://...'
+```
+
+Use `nats_leaf` when Agents on this host must keep communicating while the Core
+connection is unavailable:
+
+```bash
+brew install nats-server  # macOS; use your system package manager elsewhere
+edgecitadel join 'ecjoin://...' --messaging-mode nats_leaf
+```
+
+In both modes, Agent integrations talk to the host-local EdgeCitadel service.
+Only `nats_leaf` needs a local NATS server; it is the durable local message bus
+and maintains the outbound Leaf connection to Core.
+
+## Install a Managed Agent
+
+Managed Agents are complete runtimes operated by EdgeCitadel:
+
+```bash
+edgecitadel agent install gemma
+edgecitadel agent list
+edgecitadel agent status edgecitadel.gemma
+```
+
+Home Assistant is installed the same way after its URL, token, and allowlist are
+configured. EdgeCitadel operates the adapter and never installs or removes Home
+Assistant itself. See the [Gemma guide](plugins/gemma/README.md) and
+[Home Assistant guide](plugins/homeassistant/README.md).
+
+## Connect an existing Agent
+
+These plugins add Agent discovery, delegation, inbox, task-state, trace, and
+diagnostic tools to an active host session. They do not start the host in the
+background, and EdgeCitadel does not pass NATS credentials through the plugin
+protocol.
+
+```bash
+# Pi
+pi install "$(edgecitadel connector path pi)"
+
+# Claude Code
+claude plugin marketplace add "$(edgecitadel connector path claude-code)"
+claude plugin install edgecitadel@edgecitadel
+
+# Codex
+codex plugin marketplace add "$(edgecitadel connector path codex)"
+codex plugin add edgecitadel@edgecitadel
+```
+
+Start a new host session, then use its `edgecitadel_*` tools. Inspect active
+connections with `edgecitadel connector list` and `edgecitadel connector status
+<connector-id>`.
+
+## Operate
+
+```bash
+edgecitadel status
+edgecitadel doctor
+edgecitadel service status
+edgecitadel task list --connector-id <connector-id>
+edgecitadel trace list --connector-id <connector-id>
+```
+
+Stop a Core without deleting its data with `edgecitadel down`.
+
+## Upgrade or uninstall
+
+Use the package manager that installed EdgeCitadel:
+
+```bash
+pip install --upgrade edgecitadel
+pip uninstall edgecitadel
+
+brew upgrade edgecitadel
+brew uninstall edgecitadel
+```
+
+Before uninstalling an Edge, run `edgecitadel service stop`; in `nats_leaf`
+mode also run `edgecitadel messaging stop`. Uninstall preserves local state in
+`~/.edgecitadel`.
+
+More detail: [onboarding and troubleshooting](docs/onboarding.md) and
+[contributing](CONTRIBUTING.md).
+
+## License
+
+MIT

edgecitadel-0.1.0/aggregator/CLAUDE.md

@@ -0,0 +1,25 @@
+# Aggregator Guide
+
+## Scope
+
+- This directory contains the FastAPI backend, NATS integration, and SQLite persistence layer.
+- Primary entrypoints are `main.py`, `aggregator.py`, `database.py`, and `models.py`.
+
+## Local Rules
+
+- Keep changes consistent with the current lightweight structure: direct modules, no ORM, sync SQLite access.
+- Preserve the subject naming and transport assumptions already documented in the code and repo docs.
+- Avoid incidental refactors across unrelated endpoints, parsers, and DB helpers.
+- When backend changes alter API shape, message schema, or runtime assumptions, update the relevant docs and call out any required frontend or e2e follow-up.
+
+## Commands
+
+- Install contributor deps: `pip install -r requirements-dev.txt`
+- Run dev server: `uvicorn main:app --host 0.0.0.0 --port 8000 --reload`
+- Syntax check: `python3 -m py_compile *.py`
+
+## Validation
+
+- For Python changes, run `python3 -m py_compile *.py`.
+- For backend behavior changes, prefer a stack-backed smoke check in addition to syntax validation when the environment is available.
+- If behavior depends on NATS or Docker services, mention any runtime checks you could not execute.

edgecitadel-0.1.0/aggregator/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+WORKDIR /app/aggregator
+COPY plugin-toolkit/ /app/plugin-toolkit/
+COPY aggregator/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt -e /app/plugin-toolkit
+WORKDIR /app
+COPY aggregator/ ./aggregator/
+COPY schemas/ ./schemas/
+COPY scripts/__init__.py ./scripts/__init__.py
+COPY scripts/research/__init__.py ./scripts/research/__init__.py
+COPY scripts/research/lab_config.py ./scripts/research/lab_config.py
+CMD ["uvicorn", "aggregator.main:app", "--host", "0.0.0.0", "--port", "8000"]