Octopal AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/octopal/ contains the main Python package: CLI, channels, gateway, memory, policy, providers, Octo runtime, scheduler, WhatsApp/Telegram integrations, workers, and shared utilities.
• webapp/ holds the Vite-based dashboard frontend. src/ contains app code and dist/ contains built assets.
• tests/ contains the pytest suite for CLI, dashboard, runtime, worker orchestration, memory, and channel behavior.
• scripts/ contains setup and maintenance helpers such as bootstrap, repository-hosted install scripts (octopal.sh, octopal.ps1), and worker-template sync utilities.
• docker/ contains container assets, including the worker image Dockerfile.
• data/ is runtime state storage for SQLite, metrics, auth state, and logs; avoid committing generated contents.
• workspace/ is the default Octo/worker workspace and scratch area.
• workspace_templates/ contains bootstrap content copied into new workspaces.
• docs/ stores additional project documentation.

Build, Test, and Development Commands

• uv sync installs the project and the cross-platform CPU-only ONNX semantic-memory runtime without PyTorch; the pinned local model bundle downloads and validates on first runtime start.
• python -m venv .venv and pip install -e .[dev] are the non-uv editable setup path.
• uv run octopal configure runs the interactive configuration wizard and bootstraps missing workspace files.
• uv run octopal config show [--reveal-secrets] prints the effective config for inspection, and uv run octopal config migrate writes the current .env-backed settings into config.json.
• uv run octopal start starts Octopal in background mode.
• uv run octopal start --foreground runs the Octo and gateway in the foreground.
• uv run octopal stop, uv run octopal restart, and uv run octopal status manage the local runtime.
• uv run octopal update applies the latest release update flow for an existing install.
• uv run octopal logs prints data/logs/octopal.log, and uv run octopal logs --follow tails it.
• uv run octopal gateway starts the FastAPI gateway directly.
• uv run octopal dashboard --once prints one dashboard snapshot; uv run octopal dashboard --watch runs the live terminal dashboard; uv run octopal dashboard --json emits a machine-readable snapshot; --compact and --last <N> tune terminal output.
• uv run octopal workers list shows registered workers, their current status, and the current task when available.
• uv run octopal audit list [--limit <N>] lists recent audit events, and uv run octopal audit show <event-id> prints one audit event in detail.
• uv run octopal episodes list [--worker-run-id <id>] [--limit <N>] [--json] and uv run octopal episodes show <episode-id> [--json] inspect metadata-only execution evidence. --reveal-evidence explicitly decrypts raw content, uv run octopal episodes erase-evidence <episode-id> [--yes] securely deletes only the encrypted raw payload, and uv run octopal episodes purge-storage retries a blocked WAL purge without deleting live evidence.
• uv run octopal connector status [--json] checks connector authorization/readiness after connector setup flows; uv run octopal connector auth <name> and uv run octopal connector disconnect <name> [--forget-credentials] handle CLI-based connector auth maintenance.
• uv run octopal sync-worker-templates --overwrite refreshes default worker templates into workspace/workers.
• uv run octopal memory stats and uv run octopal memory cleanup [--keep-days <days>] [--keep-count <count>] [--dry-run] cover common memory maintenance. uv run octopal memory proposals list [--state <state>] [--json] and show <proposal-id> [--json] inspect provenance-bearing canon proposals; promote <proposal-id> [--yes] activates one, while deprecate <proposal-id> [--yes] rolls back its active canon content. uv run octopal memory recipes propose <definition.json> [--include-matching] records an episode-backed candidate; context <recipe-id> --json exports bounded benchmark context, evaluate <recipe-id> <baseline.json> <candidate.json> records held-out evidence, and list, show, promote <recipe-id> --yes, and deprecate <recipe-id> --yes manage its explicit lifecycle.
• uv run octopal whatsapp install-bridge, uv run octopal whatsapp link [--timeout <seconds>], uv run octopal whatsapp status, and uv run octopal whatsapp logout manage the WhatsApp bridge lifecycle.
• uv run octopal tools resolve [--profile <name>] [--preset all|octo] [--blocked|--available-only] [--json] explains which tools are available and why others are blocked.
• uv run octopal skill list [--json], uv run octopal skill install <source>, uv run octopal skill update <skill-id>, uv run octopal skill verify <skill-id>, uv run octopal skill enable <skill-id>, uv run octopal skill disable <skill-id>, uv run octopal skill trust <skill-id> [--force], uv run octopal skill untrust <skill-id>, uv run octopal skill prepare-env <skill-id>, uv run octopal skill remove-env <skill-id>, and uv run octopal skill remove <skill-id> cover the installed skill workflow.
• uv run octopal build-worker-image --tag octopal-worker:latest builds the Docker worker image.
• uv run pytest runs the test suite.
• uv run ruff check ., uv run black --check ., and uv run mypy are the configured lint/format/type-check commands.
• npm install and npm run build from webapp/ build the dashboard bundle manually when needed.
• uv run python scripts/benchmark_web_backends.py --backends basic,markdown_new,webclaw,browser --webclaw-binary <path> --repeat 3 --output data/web-backend-benchmark.json compares web extraction backends without starting an Octopal runtime.
• uv run python scripts/worker_bench.py --suite <suite.json> --workspace workspace_templates --mode live --config <test-config.json> --preflight-only validates provider budgets, read-only tools, credentials, and per-run isolation without making provider or tool calls. Remove --preflight-only only for a manually approved bounded live run.
• uv run python scripts/worker_bench.py --suite <suite.json> --mode replay --replay-dir <artifacts-dir> [--baseline <result.json>] --out <result.json> grades saved worker JSONL offline; baseline mode exits non-zero only for outcome regressions. Live suites must explicitly declare provider/model, strict thinking, LLM-call and tool-call caps, token/cost ceilings, and current model pricing.
• uv run python scripts/tool_call_bench.py --suite <suite.json> --config <test-config.json> --preflight-only [--out <result.json>] validates a zero-execution tool-argument benchmark. Remove --preflight-only only for a bounded live run; suites are capped at three single-attempt model calls and artifacts retain no prompts or arguments.
• uv run octopal adaptation cluster <bench-result.json>, uv run octopal adaptation propose <definition.json>, uv run octopal adaptation context <candidate-id>, and uv run octopal adaptation evaluate <candidate-id> <baseline.json> <candidate.json> cover the offline adaptation workflow. promote <candidate-id> --yes and rollback <candidate-id> --yes update only the approved registry version; runtime prompts, tools, routes, and recipes remain untouched. bandit-readiness reports why online routing is still disabled.