AGENTS.md · TencentCloud/Octop

Sections

1. 1. Collaboration principles
2. 2. What this is
3. 3. Tech stack
4. 4. Package layout
5. 5. Module boundaries
6. 6. Run commands
7. 7. Key patterns
8. 8. Do not
9. 9. Where to look
10. 10. Change workflow
11. 11. Communication

First lines (shown under the repo's MIT license)

# AGENTS.md

Navigation guide for AI coding agents working in this repository.

## 1. Collaboration principles

> Favor caution over speed; trivial tasks may relax these rules. These principles complement [§10 Change workflow](#10-change-workflow) and [§11 Communication](#11-communication).

### Think before writing

- State assumptions up front; ask when unsure — do not guess.
- When multiple interpretations exist, list them and let the user choose — do not pick silently.
- Suggest simpler approaches when they exist; push back when appropriate.
- Stop when blocked; name exactly what is unclear.

### Simplicity first

- Write the minimum code that solves the problem; no unrequested features, abstractions, or config knobs.
- Do not add defensive error handling for scenarios that cannot realistically happen.
- Trim the diff when it grows unnecessarily large.

### Surgical edits

- Touch only lines directly related to the task; do not opportunistically "clean up" nearby code, comments, or formatting.
- Do not refactor working code or unify style just because it differs from yours.
- Unrelated dead code: mention it, do not delete it proactively.
- Remove orphan imports, variables, and functions **you** introduced.

### Verifiable outcomes

- Turn tasks into verifiable goals (what to test, which command proves success).
- For multi-step work, sketch a short plan: `step → verify: …`
- Before saying "done", provide verification evidence; the default ship bar is **`make all` green** (see [§6 Run commands](#6-run-commands), [§10 Change workflow](#10-change-workflow)).

## 2. What this is

**Octop** — self-hosted AI assistant platform (multi-user, multi-agent).
One Python wheel: FastAPI backend + React dashboard + Click CLI.
No external queue. No required services beyond an LLM provider.

## 3. Tech stack

| Layer | Technology |
|-------|-----------|
| Language | Python 3.12+ |
| Web framework | FastAPI + uvicorn |
| Async runtime | asyncio (no threads except `run_in_executor`) |
| Database | SQLite via sync `sqlite3` (WAL) **or** PostgreSQL via `psycopg` / `psycopg_pool` |
| LLM runtime | `octop-harness` (LangGraph) |
| Gateway | `octop-gateway` |
| Frontend | React 18 + TypeScript + Vite |
| Package manager | uv — always `uv run pytest`, never bare `pytest` |
| API docs UI | Scalar (`scalar-fastapi`) at `/api/docs` |

## 4. Package layout

High-level tree — see [§5 Module boundaries](#5-module-boundaries) for what each folder owns and what it may import.

```
Octop (`octop/` workspace directory)     Python package root (`src/octop/`)
  config.py
  launch.py                   composition root: OctopServer + FastAPI + uvicorn
  i18n/                       locale JSON bundles + tr() + domain helpers
  infra/                      domain core (agents, DB, gateway, …)
  api/                        HTTP adapters (FastAPI)
  cli/                        Click commands
  dashboard/                  built SPA artifact — do NOT edit

dashboard/                    frontend source (Vite) — edit here
docs/                         human-written reference (e.g. `api.md`)
tests/                        pytest (`unit/`, `integration/`)
```

## 5. Module boundaries

**Rule of thumb:** dependencies flow **inward** — transport layers call domain; domain never calls HTTP/CLI. Within `infra/`, leaf modules (`utils/`, `db/repos/`, `errors.py`) stay free of higher-level orchestration.

### Layer overview

```
dashboard/ ──HTTP──► api/ ──► infra/ ──► infra/utils/, octop.config
cli/ ──► launch.py ──► api/ + infra/
```

| Layer | Role | May import | Must NOT import |
|-------|------|------------|-----------------|
| `octop.config` | Env-based `OctopConfig` | stdlib, pydantic | `infra/`, `api/`, `cli/`, `launch.py` |
| `octop.i18n` | Locale JSON + `tr()` + per-namespace helpers | `infra/utils/locale`, stdlib | `api/`, `cli/`, `dashboard/` |
| `octop.launch` | Wire `OctopServer`, `build_app`, uvicorn for `octop run` | `infra/`, `api/` | business logic; must not be imported by `infra/` |
| `infra/utils/` | Pure helpers (paths, ulid, env files, Ollama) | stdlib, third-party | any other `infra/*` domain code |
| `infra/db/repos/` | One repo per table — SQL only | `infra/db/_base`, `infra/utils/` | `agents/`, `gateway/`, `api/`, orchestration |
| `infra/` (domain) | Business logic & orchestration | `infra/utils/`, `infra/db/`, `octop.config`, peer `infra/*` subpackages, `infra/errors`, `infra/metrics` | `api/`, `cli/`, `launch.py`, `dashboard/` |
| `api/` | HTTP: routing, auth, SSE, OpenAPI | `infra/`, `octop.config`, sibling `api/*` | `cli/`, `launch.py`; no business rules that belong in `infra/` |
| `cli/` | Terminal UX | `infra/`, `octop.config`, `launch.py`, sibling `cli/*` | `api/`; domain logic duplicated from `infra/` |
| `dashboard/` | React UI | `dashboard/src/api` → backend over HTTP | Python packages; no direct DB or `infra/` access |

**Hard bans**

- `infra/` → `api/`, `cli/`, or `launch.py`.
- `api/` → `cli/` or `launch.py`.
- `cli/` → `api/` (use `launch.py` for `octop run` instead).
- `infra/db/repos/` → any non-DB `infra` package.
- `infra/utils/` → any non-utils `infra` package.
- Routers/helpers in `api/routers/` must stay thin: validate HTTP, call `infra/`, map errors — not new domain rules.

### `infra/` subpackages

| Path | Owns | Typical importers |
|------|------|-------------------|
| `infra/agents/` | Agent registry (`manager.py`), harness runtime, providers, settings (`settings/`), workspace paths (`workspace/`), threads helpers (`threads/`), security, persona/MBTI, experts, plugins, teams, memory | `server.py`, `gateway/`, `api/routers/agents.py` |
| `infra/backend/` | Workspace storage adapter, resolver, remote probe (COS/S3/…) | `agents/`, `api/routers/workspace*.py` |
| `infra/connectors/` | Connector catalog, OAuth, MCP gateway, credential crypto | `api/routers/connectors.py`, `internal_mcp.py`, `agents/manager.py` (MCP assembly) |
| `infra/control/` | Host control surfaces: `browser/`, `desktop/`, `mobile/` | `api/routers/browser/`, `desktop/`, `mobile/` |
| `infra/cron/` | Cron jobs, triggers, agent tool hooks | `server.py`, `api/routers/cron.py` |
| `infra/db/` | `SqlitePool`, migrations, `RepoBundle` / `SharedServices` in `services.py` | all domain code needing persistence |
| `infra/gateway/` | IM ingress (`processor.py`), threads, slash commands (`slash/`), bot setup (`bot_creators/`) | `server.py`, `api/routers/chat.py`, `channels.py` |
| `infra/history/` | Versioned message archive, trajectory, turn projection (`projection.py`) | `gateway/`, `api/routers/chat`, `cron/`, `agents/teams` |
| `infra/setup/` | First-run wizard, system service install, TLS / Let's Encrypt | `server.py`, `launch.py`, `api/routers/setup.py`, `api/routers/tls.py` |
| `infra/skills/` | Skill packages, SkillHub HTTP client (`skillhub_market`, `skillhub_common`) | `api/routers/skills.py`, `agents/experts` |
| `infra/users/` | Users, roles, password hashing, `UserManager` | `server.py`, `api/routers/auth.py`, `users.py` |
| `infra/errors.py` | `OctopError`, `ErrorCode` — shared exception types | everywhere in `infra/` and `api/` |
| `infra/metrics.py` | In-process counters (`METRICS`) | lazy-import inside hot paths |
| `infra/server.py` | `OctopServer.start()` — wires infra singletons | `launch.py`, `api/app.py` |

### `launch.py`

| Path | Owns | Must NOT |
|------|------|----------|
| `launch.py` | `run_foreground` / `run_foreground_blocking` — boot `OctopServer`, serve via uvicorn + `build_app`, clean shutdown | HTTP routes, SQL, CLI argument parsing |

Only `launch.py` may import both `infra/server` and `api/app` in the same module.

### `api/` layout

| Path | Owns | Must NOT own |
|------|------|--------------|
| `api/app.py` | FastAPI factory, router registration, static dashboard mount | domain rules, SQL |
| `api/deps.py` | JWT extraction, `current_user`, `get_server` | agent lifecycle, cron logic |
| `api/middleware/` | JWT gate, setup lockdown | business validation beyond auth/setup |
| `api/openapi_meta.py` | Scalar tags, API intro text | route handlers |
| `api/errors.py` | Map `OctopError` → HTTP status + JSON | new error semantics (add to `infra/errors.py`) |
| `api/routers/` | One resource per module; Pydantic request/response models | persistence, harness calls — delegate to `infra/` |
| `api/routers/browser/` | Browser session/stream/harness HTTP surface | Playwright logic (stays in harness or helpers here only as glue) |

### `cli/` layout

| Path | Owns |
|------|------|
| `cli/main.py` | Click entry, command registration |
| `cli/*_cmd.py` | User-facing subcommands |
| `cli/support/db.py` | Offline DB (`open_cli_services`) |
| `cli/support/offline_ops.py` | Local CRUD via repos (thin wrappers) |
| `cli/support/embedded_ops.py` | Short-lived `OctopServer` for runtime ops |
| `cli/support/acting.py` | Resolve `--user` / pinned defaults / agent owner |
| `cli/support/ctx.py` | Root `--user` / `--agent` / `--json` resolution |
| `cli/support/state.py` | Pinned `default_user` / `default_agent` in `cli_state.json` |
| `cli/run_cmd.py` | `octop run` — delegates to `launch.run_foreground_blocking` |
| `cli/init_cmd.py`, `cli/backup_cmd.py` | Local DB bootstrap / backup via `infra/db` |

**CLI transport layers** (pick one per command; domain rules live in `infra/`, not duplicated in `cli/`):