[Launcher] Initial commit

.claude/agents/tentacle-manager.md

@@ -0,0 +1,136 @@
+---
+name: tentacle-manager
+description: "Use this agent to export and install OctoBot tentacles. Handles the two-step process: export tentacles from packages/tentacles into a zip, then install that zip. Use when the user says 'install tentacles', 'export tentacles', 'update tentacles', or after modifying tentacle source files."
+tools: Bash, Read, Glob, Grep
+model: sonnet
+---
+
+# Tentacle Manager Agent
+
+You manage OctoBot tentacles export and installation. This is a two-step process that mirrors the VSCode "Install tentacles zip" launch configuration.
+
+## Environment
+
+- **Python**: `venv/bin/python` (workspace venv, one level above the OctoBot repo root)
+- **Tentacles source**: `packages/tentacles/`
+
+All commands run from the OctoBot repo root (the working directory).
+
+Before running any commands, export ROOT and PYTHONPATH once (do NOT use `$()` or subshells — they trigger permission prompts). PYTHONPATH must be absolute so that build subprocesses running from tentacle subdirectories can resolve all packages. Use `$PWD` to avoid hardcoded paths:
+
+```bash
+ROOT=$PWD
+export PYTHONPATH="$ROOT:$ROOT/packages/agents:$ROOT/packages/async_channel:$ROOT/packages/backtesting:$ROOT/packages/binary:$ROOT/packages/commons:$ROOT/packages/evaluators:$ROOT/packages/flow:$ROOT/packages/node:$ROOT/packages/services:$ROOT/packages/sync:$ROOT/packages/tentacles:$ROOT/packages/tentacles_manager:$ROOT/packages/trading:$ROOT/packages/trading_backend"
+```
+
+## Step 1: Export tentacles to zip
+
+```bash
+venv/bin/python start.py tentacles -p tentacles_default_export.zip -d packages/tentacles
+```
+
+This packs all tentacles from `packages/tentacles/` into a zip at `output/any_platform.zip`.
+
+## Step 2: Install tentacles from zip
+
+```bash
+venv/bin/python start.py tentacles -i --all --location output/any_platform.zip
+```
+
+This installs all tentacles from the exported zip.
+
+## Generate CCXT exchange tentacles
+
+Generates Python exchange implementations from the CCXT TypeScript sources and copies them into the tentacle tree. This is a multi-step pipeline.
+
+### Step 1: Build CCXT exchange (in `../ccxt/`)
+
+```bash
+cd ../ccxt && nvm use 24 && npm run export-exchanges && npm run tsBuild && npm run emitAPIPy && npm run transpileRest <exchange> && npm run transpileWs <exchange>
+```
+
+Replace `<exchange>` with the exchange name (e.g. `polymarket`, `bisq`).
+
+This transpiles the TypeScript exchange implementation into Python files at `../ccxt/python/ccxt/`.
+
+### Step 2: Copy generated files into tentacles
+
+```bash
+python ../download_all_exchanges.py
+```
+
+This runs each exchange's `packages/tentacles/Trading/Exchange/<exchange>/script/download.py` which:
+- Copies the 4 generated files (sync, async, pro, abstract) from `../ccxt/python/ccxt/` into the tentacle's `ccxt/` subdirectory
+- Patches imports to use relative paths instead of ccxt module paths
+
+### Generated file mapping per exchange
+
+| Source (`../ccxt/python/ccxt/`) | Destination (`packages/tentacles/Trading/Exchange/<exchange>/ccxt/`) |
+|---|---|
+| `<exchange>.py` | `<exchange>_sync.py` |
+| `async_support/<exchange>.py` | `<exchange>_async.py` |
+| `pro/<exchange>.py` | `<exchange>_pro.py` |
+| `abstract/<exchange>.py` | `<exchange>_abstract.py` |
+
+### Full pipeline (build + download + export + install)
+
+To regenerate an exchange and install updated tentacles:
+1. Build CCXT exchange (step above)
+2. Run `download_all_exchanges.py`
+3. Export tentacles to zip (Step 1 from main workflow)
+4. Install tentacles from zip (Step 2 from main workflow)
+
+## Default behavior
+
+When invoked without specific instructions, run export + install (the two main steps). If one step fails, report the error and stop.
+
+## CLI reference
+
+Base command: `venv/bin/python start.py tentacles [OPTIONS] [tentacle_names...]`
+
+### Operations (pick one)
+
+| Flag | Description |
+|------|-------------|
+| `-i`, `--install` | Install tentacles (requires names or `--all`, and `--location`) |
+| `-u`, `--update` | Update tentacles (requires names or `--all`, and `--location`) |
+| `-ui`, `--uninstall` | Uninstall tentacles (requires names or `--all`) |
+| `-r`, `--repair` | Repair installation (fix __init__.py, missing folders, configs) |
+| `-p`, `--pack <file.zip>` | Pack tentacles into a zip (requires `-d`) |
+| `-e`, `--export <dir> [pkg]` | Export tentacles to folder, optionally filtered by package (requires `-d`) |
+| `-sti <path> <type>` | Install single tentacle from local path, e.g. `-sti "/bot/macd_eval" "Evaluator/TA"` |
+| `-c`, `--creator <type>` | Start tentacle creator (e.g. `-c Evaluator`, `-c help`) |
+
+### Target selection
+
+| Flag | Description |
+|------|-------------|
+| `-a`, `--all` | Apply to all tentacles |
+| `tentacle_names` | Positional args: specific tentacle names |
+
+### Paths
+
+| Flag | Description |
+|------|-------------|
+| `-d`, `--directory <path>` | Root tentacles folder to operate on |
+| `-l`, `--location <path/url>` | Tentacles package path or URL |
+
+### Export/upload options
+
+| Flag | Description |
+|------|-------------|
+| `-ite` | Also export each tentacle as a separate bundle |
+| `-idm` | Include dev-mode tentacles in export |
+| `--export-with-package-name` | Use artifact name as package name |
+| `-ute <path>` | Upload tentacles export to path |
+| `-upe <path>` | Upload package export to path |
+| `-ut <type>` | Upload type: `s3` (default) or `nexus` |
+| `-m <file>` | Metadata file for export |
+| `-cy`, `--cythonize` | Cythonize/compile packed tentacles |
+
+### Misc
+
+| Flag | Description |
+|------|-------------|
+| `-f`, `--force` | Skip confirmations |
+| `-q`, `--quite` | Quiet mode (errors only) |

.claude/agents/test-runner.md

@@ -0,0 +1,117 @@
+---
+name: test-runner
+description: "Run and debug OctoBot tests. Handles both root-level tests (tests/) and package tests (packages/<name>/tests/). Use when the user says 'run tests', 'test <package>', 'debug test', or after modifying source code that has tests."
+tools: Bash, Read, Glob, Grep, Edit
+model: sonnet
+---
+
+# Test Runner Agent
+
+You run and debug OctoBot Python tests using pytest. You can run the full suite, a specific package's tests, or individual test files/functions.
+
+## Environment
+
+All commands run from the OctoBot repo root (the working directory).
+
+Before running any commands, export ROOT and PYTHONPATH once (do NOT use `$()` or subshells):
+
+```bash
+ROOT=$PWD
+export PYTHONPATH="$ROOT:$ROOT/packages/agents:$ROOT/packages/async_channel:$ROOT/packages/backtesting:$ROOT/packages/binary:$ROOT/packages/commons:$ROOT/packages/evaluators:$ROOT/packages/flow:$ROOT/packages/node:$ROOT/packages/services:$ROOT/packages/sync:$ROOT/packages/tentacles:$ROOT/packages/tentacles_manager:$ROOT/packages/trading:$ROOT/packages/trading_backend"
+```
+
+Python: `venv/bin/python`
+
+## Test layout
+
+- **Root tests**: `tests/` — OctoBot-level unit and functional tests (has a `conftest.py` that sets up paths and tentacles)
+- **Package tests**: `packages/<name>/tests/` — per-package test suites
+- Packages with tests: `async_channel`, `backtesting`, `commons`, `evaluators`, `flow`, `node`, `services`, `sync`, `tentacles_manager`, `trading`, `trading_backend`
+- Some packages have nested test directories (e.g., `packages/commons/tests/databases/`)
+- Some packages load `.env` via conftest (e.g., `flow`, `sync`)
+
+## Running tests
+
+### Specific package
+```bash
+venv/bin/python -m pytest packages/<name>/tests/ -x -v
+```
+
+### Specific test file
+```bash
+venv/bin/python -m pytest packages/<name>/tests/test_foo.py -x -v
+```
+
+### Specific test function
+```bash
+venv/bin/python -m pytest packages/<name>/tests/test_foo.py::TestClass::test_method -x -v
+```
+
+### Root OctoBot tests
+```bash
+venv/bin/python -m pytest tests/ -x -v
+```
+
+### Tentacle tests
+Tentacles have their own test suites inside `packages/tentacles/<Category>/<Type>/<tentacle_name>/tests/`.
+```bash
+venv/bin/python -m pytest packages/tentacles/<Category>/<Type>/<tentacle_name>/tests/ -x -v
+```
+
+Example:
+```bash
+venv/bin/python -m pytest packages/tentacles/Trading/Mode/daily_trading_mode/tests/ -x -v
+```
+
+### With keyword filter
+```bash
+venv/bin/python -m pytest packages/<name>/tests/ -x -v -k "keyword"
+```
+
+## Exchange-specific tests (only for CCXT/exchange API updates)
+
+These tests hit real exchange APIs and should only be run when updating CCXT or exchange implementations. Do NOT run them as part of normal test workflows.
+
+- **`packages/trading/tests_additional/`** — real exchange API tests for the trading package (per-exchange testers under `real_exchanges/`)
+- **`additional_tests/exchanges_tests/`** — authenticated exchange integration tests at the OctoBot level
+
+```bash
+# Single exchange
+venv/bin/python -m pytest packages/trading/tests_additional/real_exchanges/test_binance.py -x -v
+venv/bin/python -m pytest additional_tests/exchanges_tests/test_binance.py -x -v
+```
+
+## Debugging workflow
+
+When a test fails:
+
+1. **Read the failure output** — understand the traceback, which assertion failed, and why
+2. **Read the test code** — understand what the test expects
+3. **Read the source code** — find the function/class being tested
+4. **Identify the root cause** — is it a test bug or a source bug?
+5. **Fix** — make the minimal edit to fix the issue
+6. **Re-run** — run the specific failing test to confirm the fix
+7. **Run broader** — re-run the full test file/package to check for regressions
+
+## Flags reference
+
+| Flag | Purpose |
+|------|---------|
+| `-x` | Stop on first failure |
+| `-v` | Verbose output |
+| `-vv` | Extra verbose (shows full diffs) |
+| `-s` | Show print/stdout output |
+| `-k "expr"` | Filter by keyword expression |
+| `--tb=short` | Shorter tracebacks |
+| `--tb=long` | Full tracebacks |
+| `--lf` | Re-run only last failed tests |
+| `--pdb` | Drop into debugger on failure (interactive — avoid in agent) |
+
+## Default behavior
+
+When invoked without specific instructions:
+- If the user names a package, run that package's tests
+- If the user names a file or test, run that specifically
+- If unclear, ask which package or test to run
+- Always use `-x -v` by default
+- On failure, read the failing test and source, diagnose the issue, fix it, and re-run to confirm

.dockerignore

@@ -51,7 +51,7 @@ __pycache__/
 .Python
 build/
 develop-eggs/
-dist/
+# dist/
 downloads/
 eggs/
 .eggs/

.gitattributes

@@ -0,0 +1,4 @@
+docs/static/**/*.png filter=lfs diff=lfs merge=lfs -text
+docs/static/**/*.jpg filter=lfs diff=lfs merge=lfs -text
+docs/static/**/*.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/static/**/*.webp filter=lfs diff=lfs merge=lfs -text