159 lines
7.7 KiB
Markdown
159 lines
7.7 KiB
Markdown
# Agentic OS — Documentation Draft (NOTES)
|
|
|
|
> FIRST DRAFT. This is a living scratch pad, not the finished manual.
|
|
> The structured reference lives in `docs/README.md` — keep that as the
|
|
> canonical doc and fold things from here into it as they mature.
|
|
> Last touched: 2026-07-27. Expect this section to grow fast.
|
|
|
|
## 1. What this is (one paragraph)
|
|
|
|
Agentic OS is a locally-hosted control plane for AI agents. A FastAPI
|
|
backend (`server.py`, ~2,800 lines) serves a vanilla-JS single-page
|
|
dashboard (`dashboard/`) plus a JSON REST API (`/api/*`). It coordinates
|
|
three built-in CLI agents — **opencode** (code/DevOps), **Hermes**
|
|
(memory/scheduling/coordination), **Gemini CLI** (research/analysis) — and
|
|
any number of **custom-registered agents**. Shared state is plain files
|
|
under `brain/`, `skills/`, `data/`, `scheduler/`. No external database.
|
|
|
|
## 2. How to run it (verified 2026-07-27)
|
|
|
|
```bash
|
|
cd ~/agentic-os
|
|
python3 server.py # reads port from data/settings.json (dashboard.port, default 8080)
|
|
# or
|
|
./start.sh # wrapper
|
|
# or
|
|
./start-agentic-os.sh # the supervised launcher (PID-tracked)
|
|
```
|
|
|
|
- Dashboard: http://127.0.0.1:8080
|
|
- API base: http://127.0.0.1:8080/api/
|
|
- Terminal WS: ws://127.0.0.1:8080/ws/terminal (in-app PTY, same port)
|
|
|
|
> The dashboard port is the SOLE source of truth and lives in
|
|
> `data/settings.json` (`dashboard.port`). `server.py`, the launcher
|
|
> scripts, and `scheduler/scheduler.py` all read it. Do NOT hardcode
|
|
> 8080/8081 anywhere — change it in one place only.
|
|
|
|
## 3. Mental model (the layers)
|
|
|
|
```
|
|
browser SPA (dashboard/*.html + pages/*.js)
|
|
│ fetch /api/* ▲ WebSocket /ws/terminal
|
|
▼
|
|
FastAPI backend (server.py)
|
|
├─ Agent Router ──► opencode / hermes / gemini / custom
|
|
├─ Memory (brain/ folder + Hermes SQLite FTS5)
|
|
├─ Skills Hub (skills/*/SKILL.md, eval.json, learnings.md)
|
|
├─ Scheduler (APScheduler jobs in scheduler/jobs/*.json)
|
|
├─ Kanban (tasks, dispatch to agents)
|
|
└─ Audit/Cost/Backups (append-only logs under data/)
|
|
```
|
|
|
|
Two scheduling systems coexist (be aware):
|
|
- **APScheduler** inside the OS — jobs in `scheduler/jobs/*.json`, loaded
|
|
by `scheduler/scheduler.py`.
|
|
- **Hermes cron** — managed via the Hermes `cronjob` tool, persistent
|
|
across restarts. Currently running: `brain-guardian-autoupdate`
|
|
(every 2h) which writes `brain/health-report.md`,
|
|
`brain/skill-usage.md`, `brain/github-activity.md`.
|
|
|
|
## 4. The dashboard pages (current)
|
|
|
|
Primary: Dashboard, AI Chat, Terminal.
|
|
Agents: Skills, Memory, Agent Health, Command Center (new), Smart Router.
|
|
Workflow: Kanban, Goals, Journal, Scheduler, Audit, Multi-Agent Run,
|
|
Session Replay, Agent Time, Agent Insights, Brain Search.
|
|
Management: Cost, Plugins, Backups, Prompts, Standards, Settings, Setup Wizard.
|
|
|
|
Each page is `dashboard/pages/<name>.js` exposing `render<Name>()`,
|
|
loaded on demand by `dashboard/app.js` (hash routing). Shared helpers
|
|
live in `dashboard/utils.js` (`navigate`, `showToast`, `escapeHtml`,
|
|
`statusColor`, `PAGE_TITLES`) and `dashboard/api.js` (the `api` client).
|
|
|
|
### New: Command Center (`#command-center`)
|
|
See the dedicated section in `docs/README.md`. In short: a command
|
|
console (`/help` `/status` `/run` `/wake` `/reset` `/clear` + free text)
|
|
that dispatches to the live agent registry via `/api/chat`, with real
|
|
agent-status, system-metric, and log/event panels. No mocked data.
|
|
|
|
## 5. API surface (the parts that matter most)
|
|
|
|
Full table is in `docs/README.md`. High-traffic ones:
|
|
|
|
| Group | Endpoints |
|
|
|-----------|------------|
|
|
| Agents | `GET /api/agents`, `POST /api/agents/register`, `DELETE /api/agents/{name}`, `GET /api/agents/health` |
|
|
| Chat | `POST /api/chat` ← Command Center `/run` lands here |
|
|
| Status | `GET /api/status` ← `{status, agents[], skills_count, uptime}` |
|
|
| Scheduler | `GET/POST/DELETE /api/scheduler/jobs` |
|
|
| Skills | `GET /api/skills`, `POST /api/skills/{name}/run`, `GET /api/skills/{name}/eval` |
|
|
| Brain | `GET/PUT /api/brain/{file}` |
|
|
| Agent Time| `GET /api/agent-time`, `POST /api/agent-time/recompute`, `GET /api/agent-time/skin` (Rainmeter) |
|
|
| Orchestrate| `POST /api/orchestrate` (fan-out + converge) |
|
|
|
|
Agent object shape (from `check_agent`):
|
|
`{ name, display_name, status: online|warning|offline, description, type, builtin }`
|
|
|
|
## 6. Agent registry
|
|
|
|
- Built-in agents: opencode, hermes, gemini (defined in `server.py`).
|
|
- Custom agents: `data/agent-registry.json` (register via UI → Agent
|
|
Health → + Add Agent, or `POST /api/agents/register`).
|
|
- Check types: `binary` (in PATH), `oauth_file`, `http` (health_url),
|
|
`custom` (check_command, run WITHOUT shell=True — injection-safe).
|
|
- Agent types: `cli` (subprocess, `{message}` substitution), `http`
|
|
(POST to api_url), `mcp` (stub — not implemented).
|
|
|
|
## 7. Memory (brain/)
|
|
|
|
- `brain/memory.md`, `brain/active-projects.md`, `brain/recent-decisions.md`,
|
|
`brain/business-brain.md` — read by agents at session start.
|
|
- `brain/journal/YYYY-MM-DD.md` — daily entries (Journal page).
|
|
- Centralized index: `brain-core/brain_index.py` (SQLite FTS5) over
|
|
brain notes + skill learnings + chat history. Query: `/api/brain-index/search`.
|
|
- `brain-guardian` (Hermes cron) keeps health/skill-usage/github reports fresh.
|
|
- A standalone `dashboard/serve_monitor.py` + `agent-time-monitor.html`
|
|
exist but are SUPERSEDED by the integrated Agent Time page on 8080.
|
|
Kept at user request; do not build new features on top of them.
|
|
|
|
## 8. Skills
|
|
|
|
`skills/<name>/` → `SKILL.md` (YAML frontmatter + body), `learnings.md`,
|
|
`eval.json`, `score-history.json`, `context/`. ~17 built-in. Run via
|
|
`POST /api/skills/{name}/run`. See `docs/README.md` "Skills" for the list.
|
|
|
|
## 9. Open items / what's next (grow this section)
|
|
|
|
> This is the section to extend in the near term. Mark done by striking through.
|
|
|
|
- [ ] **Command Center hardening** — `/run` is fire-and-forget to the
|
|
agent CLI; consider recording console runs into the audit trail and
|
|
surfacing a per-run job id in the Jobs panel.
|
|
- [ ] **MCP agent type** is a stub (`type: mcp` in registry schema but
|
|
`execute_agent_mcp` is minimal). Decide: implement or remove from UI.
|
|
- [ ] **Standalone monitor cleanup** — `dashboard/serve_monitor.py` and
|
|
`agent-time-monitor.html` are dead weight (superseded). User wants
|
|
them kept for now; revisit deletion later.
|
|
- [ ] **Docs drift** — `docs/README.md` still claims 17 skills / v1.3.0
|
|
and a couple of stale numbers; reconcile counts (Skills nav badge
|
|
showed 32 skill dirs on 2026-07-27 — investigate the discrepancy).
|
|
- [ ] **Graphify memory layer** — code graph works (`graphify . --code-only`);
|
|
memory-note graphing needs an LLM key (see `docs/GRAPHIFY_MEMORY.md`).
|
|
Expose graphify as a query tool (MCP/HTTP) if wanted.
|
|
- [ ] **Rainmeter HUD** — SystemMonitor + AgentTime skins deployed to the
|
|
Windows APieces folder; they read the live `/api/agent-time/skin`
|
|
endpoint. Tie version notes into this doc when changed.
|
|
- [ ] **The user said "more to do here very soon"** — leave room at the
|
|
top of this file; prepend new sections rather than burying them.
|
|
|
|
## 10. Conventions for contributors (this repo)
|
|
|
|
- One source of truth for config: `data/settings.json`.
|
|
- Plain files, no DB. Audit everything via `append_audit(...)`.
|
|
- Never `shell=True` with agent-supplied input (injection-safe `shlex`).
|
|
- Dashboard pages: add to `index.html` nav + `utils.js` `PAGE_TITLES` +
|
|
a `render<Name>()` in `pages/<name>.js`. Reuse `.cc-*` / existing
|
|
CSS vars; don't invent a second design language.
|
|
- Verify with the live server (it's usually up on 8080) before claiming done.
|