AgentHandle

Sandbox içinde çalışan bir AI agent (Claude vb.) ESP/Arduino/STM32 gibi USB'ye bağlı fiziksel cihazlara doğrudan erişemez — derleyemez, upload edemez, seri çıktıyı okuyamaz. AgentHandle bu boşluğu kapatan, kullanıcının makinesinde çalışan küçük bir Node.js CLI köprüsüdür.

Agent kodu değiştirir; AgentHandle değişikliği yakalar, derler, cihaza upload eder, seri portu dinler ve sonucu düz log dosyalarına yazar. Agent bu log dosyalarını okuyup durumu (derleme hatası mı, cihaz ne basıyor) değerlendirir ve iterasyona devam eder.

 ┌──────────┐   kod değişir   ┌──────────────┐   derle+upload   ┌─────────┐
 │  Agent   │ ───────────────▶│ AgentHandle  │ ────────────────▶│  Cihaz  │
 │ (Claude) │                 │  (--watch)   │◀──── serial ─────│ ESP/STM │
 └────┬─────┘                 └──────┬───────┘                  └─────────┘
      │   logs/build.log              │ yazar
      │   logs/serial.log  ◀──────────┘
      └── okur & değerlendirir

Kurulum

Global (önerilen)

agenthandle komutunu her yerden kullanmak için:

# Proje dizininden, kaynaktan global kurulum
npm install -g .

# (yayınlandıktan sonra)  npm install -g agenthandle

Kurulumdan sonra agenthandle komutu PATH'te olur. Doğrulamak için: agenthandle --help.

İpucu: npm install -g izin hatası verirse ya sudo npm install -g . kullan ya da yazılabilir bir prefix ayarla:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # .bashrc/.zshrc'ye ekle

Yerel (alternatif)

npm install          # chokidar bağımlılığını kurar
npm link             # 'agenthandle' komutunu global sembolik linkler
# veya doğrudan: node bin/agenthandle.js ...

Toolchain

Kullanacağın toolchain'in ayrıca makinede kurulu olması gerekir. Yerleşik destek: arduino-cli, platformio, esp-idf, stm32cubeide, cargo (Rust web/host), probe-rs (Rust embedded) — ya da custom ile herhangi bir araç.

# Arduino / ESP
arduino-cli core install esp32:esp32     # örnek: ESP32 board paketi

# STM32CubeIDE: STM32CubeIDE + STM32CubeProgrammer kurulu olmalı (ST'den)

# Rust: cargo zaten Rust kurulumuyla gelir. Embedded flash için ayrıca:
cargo install probe-rs-tools             # `probe-rs` CLI'ı sağlar

Hızlı başlangıç

# 1) Yeni bir proje dizininde örnek config + firmware oluştur
agenthandle init

# 2) agenthandle.config.json içindeki port / fqbn / sketch değerlerini düzenle

# 3a) Sürekli izleme modu — geliştirirken açık bırak
agenthandle --watch --port /dev/ttyUSB0

# 3b) Tek seferlik — agent için ideal: derle, upload, ~8sn serial yakala, çık
agenthandle --once --port /dev/ttyUSB0

CLI argümanları her zaman config dosyasını override eder.

Modlar

• --watch : Dosyaları izler. Her değişiklikte serial monitörü durdurur → derler → upload eder → monitörü yeniden başlatır. Ctrl+C'ye kadar çalışır.
• --once : Tek döngü çalıştırır, seri çıktıyı serial.captureMs (varsayılan 8000ms) boyunca yakalar ve çıkar. Agent'ın deterministik şekilde çağırması için tasarlandı.

Seçenekler

| Bayrak | Açıklama | |---|---| | --config <path> | Config dosyası yolu (varsayılan ./agenthandle.config.json) | | --toolchain <name> | arduino-cli | platformio | esp-idf | stm32cubeide | cargo | probe-rs | custom | | --port <port> | USB portu (/dev/ttyUSB0, COM5, ...) | | --baud <n> | Serial baud (varsayılan 115200) | | --sketch <path> | Proje/sketch dizini | | --fqbn <fqbn> | arduino-cli board, örn esp32:esp32:esp32 | | --build-log <path> | Build log yolu | | --serial-log <path> | Serial log yolu | | --no-serial | Serial monitörü kapat | | --help | Yardım |

Log dosyaları

Her döngüde sıfırlanan üç ayrı dosya (agent her zaman en güncel durumu görür):

• logs/build.log — çalıştırılan komutlar, derleyici/upload çıktısı ve sonda durum satırı:
  • === STATUS: SUCCESS ===
  • === STATUS: COMPILE_FAILED (code N) ===
  • === STATUS: UPLOAD_FAILED (code N) ===
• logs/serial.log — upload sonrası cihazın (veya cargo toolchain'inde çalışan sürecin) seri/stdout çıktısı.
• logs/test.log — agenthandle test veya "test" fazı çalıştığında yazılır:
  • === STATUS: TEST_PASSED ===
  • === STATUS: TEST_FAILED (code N) ===

Rust projeleri (cargo / probe-rs)

İki farklı Rust senaryosu için iki toolchain var.

cargo — web/host Rust projeleri (server, CLI, vb.)

Fiziksel port/cihaz yok; port belirtmen gerekmez. Üç faz şu şekilde eşlenir:

• compile → cargo build
• upload → cargo test (flash yerine bir "deploy kapısı": testler geçmeden cargo run başlamaz)
• monitor → cargo run (uzun ömürlü süreç; stdout/stderr serial.log'a akar)

{
  "toolchain": "cargo",
  "sketch": "./my-web-service",
  "logs": { "build": "./logs/build.log", "serial": "./logs/serial.log", "test": "./logs/test.log" }
}

agenthandle --watch --toolchain cargo --sketch ./my-web-service

Önemli: build.log'da UPLOAD_FAILED gördüğünde bu bir flash/port hatası değil, cargo test başarısız oldu demektir — komut satırı ($ cargo test ...) bunu gösterir.

probe-rs — embedded Rust (MCU'ya flash)

chip zorunlu (probe-rs'in probe/MCU seçimi için). port gerekmez.

• compile → cargo build (varsa --target, --release)
• upload → probe-rs download --chip <chip> <binary>
• monitor → probe-rs attach --chip <chip> <binary> (RTT çıktısı)

{
  "toolchain": "probe-rs",
  "sketch": "./firmware-rs",
  "chip": "STM32F103C8",
  "target": "thumbv7m-none-eabi",
  "release": true
}

agenthandle --watch --toolchain probe-rs --sketch ./firmware-rs --chip STM32F103C8

Board'da ayrıca bir UART/serial hattı üzerinden log basılıyorsa (RTT değil), monitor'u commands.monitor ile yerleşik serial okuyucuya veya başka bir araca yönlendirebilirsin.

Bağımsız test fazı: agenthandle test

Her iki Rust toolchain'i de cargo test'i ayrıca bağımsız bir faz olarak sağlar — tam build+run döngüsünü beklemeden hızlı bir test çalıştırması için:

agenthandle test --toolchain cargo --sketch ./my-web-service

Sonuç logs/test.log'a yazılır; port/fqbn gibi flash gereksinimleri aranmaz. Diğer toolchain'lerde (arduino-cli, platformio, ...) test fazı tanımlı değildir — kullanmak istersen commands.test veya --test-cmd ile bir komut tanımlaman gerekir.

STM32CubeIDE projeleri

STM32CubeIDE projeleri için yerleşik toolchain hazır: headless build (STM32CubeIDE CLI) + flash (STM32CubeProgrammer CLI) + yerleşik serial monitör (bağımlılıksız).

{
  "toolchain": "stm32cubeide",
  "port": "/dev/ttyACM0",
  "baud": 115200,
  "sketch": "/path/to/MyProject",
  "buildConfig": "Debug",
  "interface": "SWD",
  "logs": { "build": "./logs/build.log", "serial": "./logs/serial.log" }
}

agenthandle --watch --toolchain stm32cubeide --port /dev/ttyACM0 \
  --project /path/to/MyProject --build-config Debug

Üretilen komutlar:

# derleme (headless managed build)
stm32cubeide --launcher.suppressErrors -nosplash \
  -application org.eclipse.cdt.managedbuilder.core.headlessbuild \
  -data <workspace> -import <project> -build <projectName>/<buildConfig>

# flash
STM32_Programmer_CLI -c port=SWD -w <project>/<buildConfig>/<projectName>.elf -rst

Ayarlanabilir alanlar (hepsinin varsayılanı var): project (varsayılan sketch), projectName (dizin adı), buildConfig (Debug), workspace (otomatik türetilir), binary (<proj>/<config>/<ad>.elf), ide, programmer, interface (SWD/JTAG).

Araç yolları: stm32cubeide ve STM32_Programmer_CLI PATH'te değilse ide ve programmer ile tam yolu ver. macOS'ta IDE genelde /Applications/STM32CubeIDE.app/Contents/MacOS/stm32cubeide altındadır.

Serial monitör: Linux/macOS'ta yerleşik okuyucu portu stty ile ayarlayıp okur — ek araç gerekmez. Windows'ta commands.monitor / --monitor-cmd ile bir araç tanımla (örn. pyserial-miniterm {port} {baud}).

Telegram bildirimleri

Build/upload sonucunu (başarılı / derleme hatası / upload hatası) telefonuna Telegram mesajı olarak gönderir. Bağımlılıksız (Node https).

Kurulum:

1. @BotFather ile bir bot oluştur, token'ı al.
2. Botuna bir mesaj at, sonra https://api.telegram.org/bot<TOKEN>/getUpdates çıktısındaki chat.id değerini al.
3. Token'ı config'e koymak yerine env değişkeninde tutman önerilir:

export AGENTHANDLE_TELEGRAM_TOKEN="123456:ABC..."
export AGENTHANDLE_TELEGRAM_CHAT_ID="987654321"
agenthandle test-telegram            # kurulumu doğrula
agenthandle --watch --port /dev/ttyUSB0 --notify-telegram

Config ile ince ayar:

{
  "notify": {
    "telegram": {
      "enabled": true,
      "on": ["success", "compile_failed", "upload_failed"],
      "includeSerial": false
    }
  }
}

Hata bildirimlerine build.log'un son satırları, includeSerial: true ise başarıda serial.log kuyruğu eklenir.

İki yönlü sohbet köprüsü (TelegramMessages.txt)

AgentHandle, bir dosya ile Telegram arasında iki yönlü köprü kurabilir:

• Dosya → Telegram: TelegramMessages.txt'ye yeni bir satır eklenince (örn. agent yazar) o satır sana Telegram'dan iletilir.
• Telegram → Dosya: Sen Telegram'dan mesaj yazınca dosyaya [user] ... olarak eklenir; böylece agent senin cevabını okuyabilir.

# Tek başına köprü
agenthandle bridge

# veya watch ile birlikte
agenthandle --watch --port /dev/ttyUSB0 --notify-telegram --bridge

[user] ile başlayan satırlar Telegram'dan geldiği için tekrar Telegram'a iletilmez (döngü koruması). Köprü başladığında dosyadaki mevcut geçmiş iletilmez; yalnızca yeni eklenenler gider. Dosya yolu: notify.telegram.bridge.file veya --telegram-file.

Herhangi bir aracı sürme (custom komutlar)

AgentHandle sadece üç hazır toolchain ile sınırlı değil — komutların kendisi parametredir. commands ile herhangi bir derleme/upload/monitör aracını (make, cmake, avrdude, openocd, st-flash, dfu-util, bir shell script, ...) kod değiştirmeden sürebilirsin. commands tanımlandığında ilgili faz için seçili toolchain'i override eder.

Config ile:

{
  "toolchain": "custom",
  "port": "/dev/ttyACM0",
  "baud": 115200,
  "sketch": "./fw",
  "vars": { "addr": "0x08000000", "bin": "build/fw.bin" },
  "commands": {
    "compile": ["make", "-C", "{sketch}"],
    "upload":  ["st-flash", "write", "{bin}", "{addr}"],
    "monitor": ["pyserial-miniterm", "{port}", "{baud}"]
  }
}

CLI ile (hızlı override):

agenthandle --once --port /dev/ttyACM0 \
  --compile-cmd "make" \
  --upload-cmd  "st-flash write build/fw.bin 0x8000000" \
  --monitor-cmd "pyserial-miniterm {port} {baud}"

Placeholder'lar

{port} {baud} {fqbn} {sketch} {buildDir} her zaman vardır. vars altına koyduğun her anahtar da {key} (veya {vars.key}) olarak kullanılabilir. Komut şablonu dizi (önerilen, tırnak derdi yok) veya string olabilir.

Sadece bir fazı override etmek istersen named toolchain'i tutup yalnız o fazı commands'a koyabilirsin. Örn toolchain: "arduino-cli" + sadece commands.upload ile özel flasher.

Yerleşik toolchain ekleme

Sık kullanılan bir toolchain'i hazır hale getirmek istersen src/toolchains.js içindeki REGISTRY'ye compile / upload / monitor döndüren yeni bir adapter ekle. platformio ve esp-idf için iskelet hazır; arduino-cli tam implemente.

Notlar

• Tek harici bağımlılık: chokidar (dosya izleme). Kurulu değilse fs.watch fallback'ine düşer.
• Serial monitör portu tuttuğu için upload'tan önce otomatik durdurulur, sonra yeniden başlatılır.