Dokümantasyon / Referans
Yerel API
ivralo serve, terminal kullanmayan istemciler için bu makinenin loopback adresinde yerel bir HTTP API çalıştırır: bir editör, bir script ya da Alertmanager. Her route, CLI'ın da yaptığı bir çağrıya karşılık gelir. Bu sayfada route'lar, akış biçimi, onaylar ve hatalar anlatılıyor.
Başlatmak
ivralo serve
Sunucu, başlattığınız çalışma alanında ön planda çalışır ve Ctrl+C ya da SIGTERM gelene kadar açık kalır. Kendini servis olarak kurmaz; sürekli açık kalmasını istiyorsanız kendi servis yöneticinizle çalıştırın. Kapandıktan sonra hiçbir port dinlenmez.
| Ayar | Değer |
|---|---|
| Adres | Yalnızca 127.0.0.1. Başka bir adrese bağlanmak için bir seçenek yoktur. |
| Port | --port, verilmezse IVRALO_API_PORT (61017). Port doluysa 1 ile çıkar. |
| Çalışma alanı | Başlatıldığı çalışma alanı; başkası değil. |
| Çıkış | Ctrl+C'den sonra 130, SIGTERM'den sonra 143. |
Başka bir makineden erişmek için ssh tüneli kullanın:
ssh -L 61017:127.0.0.1:61017 you@server
Token, sürüm ve çalışma alanı
GET /version dışındaki her istekte üç başlık bulunur:
| Başlık | Değer |
|---|---|
Authorization | Bearer ve ivralo ana dizininizdeki api-token dosyasındaki token. |
X-Ivralo-Api-Version | 2. Başka bir sürüm isteyen ya da sürüm belirtmeyen istek 409 ile reddedilir. |
X-Ivralo-Workspace | İsteğe bağlı. İstemcinin çalıştığı klasör; sunucununkinden farklıysa istek 409 ile reddedilir. |
Token dosyasını yalnızca sahibi okuyabilir. Dosyayı ivralo init --token ya da ilk ivralo serve oluşturur. ivralo serve --new-token token'ı yeniler; bu durumda bütün istemcilerin yeni token'ı alması gerekir. ivralo token'ı hiçbir zaman ekrana basmaz. Python worker'ı bu dosyayı adıyla okumayı reddeder; bu kesin bir sınır değil, bir korkuluktur.
Token kontrol edilmeden önce her istekte iki kontrol daha yapılır: istek bir loopback adresinden gelmelidir ve Host başlığı 127.0.0.1, localhost ya da [::1] olmalıdır. DNS rebinding kullanan bir web sayfası bu ikinci kontrolü atlatamaz. İkisi de geçmezse istek 403 ile reddedilir.
TOKEN=$(cat ~/ivralo/api-token)
curl -s http://127.0.0.1:61017/version
curl -s http://127.0.0.1:61017/health \
-H "Authorization: Bearer $TOKEN" -H "X-Ivralo-Api-Version: 2"
Route'lar
| Yöntem ve yol | Ne yapar | Karşılığı |
|---|---|---|
GET /version | ivralo'nun ve API'nin sürümü: {"ivralo": "…", "api": 2}. Token gerekmez. | |
GET /health | Çalışma alanı, model, veritabanının cevap verip vermediği, o an neyin çalıştığı ve bu sunucu açık kaldığı sürece hangi düzenlemelerin kabul edildiği. | |
POST /requests | Tek bir isteği çalıştırır ve akış olarak döndürür. | ivralo ask |
POST /requests/{id}/steer | Çalışan bir isteğe mesaj gönderir; mesaj bir sonraki araç sonucuyla birlikte modele ulaşır. | tur sırasında yazmak |
DELETE /requests/{id} | Çalışan bir isteği iptal eder. Akışı kapatmak da aynı işi görür. | Esc |
POST /approvals/{id} | Akışta istenen bir onayı cevaplar. | onay diyaloğu |
GET /sessions | Son oturumlar. ?limit= 1 ile 200 arası, varsayılan 20. | ivralo sessions |
GET /sessions/{id}/runs | Bir oturumun run'ları. ?limit= yukarıdaki gibi. | ivralo runs |
GET /runs/{run}/trace | Bir run'ın araç çağrıları. last kullanılırsa oturumu ?session= belirtir. | ivralo trace --json |
GET /changes | Her turun neyi değiştirdiği, en yeniden başlayarak. ?limit=, varsayılan 50. | ivralo changes --json |
GET /changes/{n}/diff | Bir değişikliğin diff'i; 1 en yenisidir. | /diff n |
POST /why | Bir iddianın nereden geldiği. | ivralo why --json |
GET /changesets | Bekleyen changeset'ler. | ivralo changeset list |
POST /changesets/{id}/land | Bir changeset'i çalışma ağacına uygular. | ivralo changeset land |
POST /changesets/{id}/drop | Bir changeset'i atar. | ivralo changeset drop |
POST /changesets/{id}/release | Artık çalışmayan bir turun bıraktığı işareti kaldırır; böylece changeset uygulanabilir ya da atılabilir. | ivralo changeset release |
POST /verify | Projenin kontrollerini çalıştırır ve sonucu akış olarak döndürür. | ivralo verify |
POST /incident | Bir kanıt paketini inceler ve raporu akış olarak döndürür. | ivralo incident --format json |
POST /alerts/alertmanager | Bir Alertmanager webhook'unu karşılar. | |
POST /alerts/pagerduty | Bir PagerDuty V3 webhook'unu karşılar. | |
GET /jobs | Bu çalışma alanının job'ları. | ivralo jobs |
GET /jobs/{id} | Tek bir job'un bütün ayrıntıları. | ivralo job |
POST /jobs/{id}/cancel | Bir job'u iptal eder. | ivralo cancel |
POST /jobs/{id}/resume | Bir job'u devam ettirir, akış olarak. | ivralo resume |
Alert route'ları Alert alımı sayfasında anlatılıyor.
İstek gövdeleri
Bütün gövdeler JSON nesnesidir.
| Route | Alan | Varsayılan | Anlamı |
|---|---|---|---|
POST /requests | text | zorunlu | İstek. |
images | [] | Eklenecek görsellerin yolları. | |
session | ortak oturum | İsteğin çalışacağı oturum. | |
attended | true | true ise ekip oturumdaki gibi kurulur: onay isteyen çağrılar akışta onay kaydına dönüşür. false ise ekip ivralo ask'teki gibi kurulur: hiçbir şey beklemez, onay isteyecek olan reddedilir. | |
plan | false | Önce bir plan çıkarır; plan bir plan onayına dönüşür. attended gerektirir. | |
changeset | ayardaki değer | auto düzenlemeleri hazırlar ve kontroller geçince uygular, keep hazırlar ama hiçbir zaman uygulamaz, off düzenlemelerin doğrudan yerinde yapılmasına izin verir. plan ile birlikte kullanılamaz. | |
trust | false | true klasörü güvenilir sayar; bu karar API üzerinden verilmiş olarak kaydedilir. | |
POST /requests/{id}/steer | text | zorunlu | Mesaj. |
POST /approvals/{id} | decision | zorunlu | confirm, reject ya da answer. |
scope | call | confirm ile: call, turn, edits ya da always. | |
note | boş | reject ile: bunun yerine ne yapılacağı. Model bu notu okur. | |
text | boş | answer ile: sorunun cevabı. | |
POST /why | claim | zorunlu | Bir sayı ya da bir ifade. |
run | last | Run. | |
session | ortak oturum | Oturum. | |
POST /verify | paths | git'e göre değişen dosyalar | Değişen dosyalar. |
scope | targeted | targeted ya da full. | |
attended | true | false ise onay isteyecek komutlar reddedilir. | |
trust | false | İsteklerdeki gibi. | |
POST /incident | bundle | incident/ | Kanıt paketi; çalışma alanında bir klasör. |
hosted | false | Bu run için makine dışında çalışan bir modelin kanıtı okumasına izin verir. Maskelemenin de açık olması gerekir. | |
session | yeni bir oturum | İncelemenin çalışacağı oturum. | |
attended | true | true ise Investigator'ın soruları onay kaydına dönüşür. | |
POST /jobs/{id}/resume | answer | yok | Bekleyen bir job için: approve, approve_job ya da reject. |
note | boş | reject ile. |
Akış
POST /requests, /verify, /incident ve /jobs/{id}/resume, application/x-ndjson biçiminde cevap verir: her satırda bir JSON nesnesi vardır ve her nesnede bir seq numarası ile bir kind bulunur.
{"seq":1,"kind":"accepted","request":"8f2c…"}
{"seq":2,"kind":"run","run_id":"…","session_id":"…"}
{"seq":3,"kind":"call_started","call":"…","agent":"Ivralo","tool":"read_file","args":{"path":"src/app.py"},…}
{"seq":4,"kind":"approval","approval":"a1…","type":"call","expires_in":1800,…,"answers":["confirm","reject"],"scopes":["call","turn","edits"]}
{"seq":5,"kind":"decided","approval":"a1…","decision":"confirm","scope":"call","by":"…"}
{"seq":9,"kind":"result","result":{"ok":true,"reply":"…","files":[…],…},"undelivered":[]}
Alanlar burada … ile kısaltıldı.
Akışta görülebilecek türler:
| Grup | Türler |
|---|---|
| Tur | run, call_started, call_completed, call_failed, reasoning, content, completed, run_failed, memory, context |
| Sunucu | accepted, approval, decided, steering, limit, heartbeat, step_started, step_ended, step_result, integrated, instance, say, reply, job, cancelled, error, result |
Akış result, error ya da cancelled ile biter. Bir isteğin result kaydında, result altında ivralo ask --format json'ın yazdırdığı nesnenin aynısı, undelivered altında da modele hiç ulaşmamış yönlendirme mesajları bulunur. Bir incelemenin sonucu {"kind":"result","incident":{…}} biçimindedir, bir doğrulamanınki verification alanını taşır, bir job'u devam ettirme işlemi ise bir job kaydıyla biter. 15 saniye hiçbir şey gelmezse bir heartbeat gönderilir; sunucu, bağlantısı kopan istemciyi de bu sayede fark eder.
Bütün metinler kaçışlı ASCII olarak yazılır. İçinde satır sonu ve kayda benzeyen bir şey bulunan bir cevap bile tek bir satırda, tek bir metin olarak gelir.
Onaylar
Bir çağrı için bir insanın onayı gerektiğinde akışa bir approval kaydı düşer ve run bekler. Ne tür bir onay olduğunu type söyler:
| Tür | Ne içerir | Cevaplar |
|---|---|---|
call | Tek bir araç çağrısı, ayrıntılarıyla; düzenlemeyse diff'iyle birlikte. | Listelenen kapsamlardan biriyle confirm ya da reject |
question | Bir ajanın size sorduğu soru. | answer ya da reject |
commands | /verify'ın çalıştıracağı ve onay isteyen komutlar. | confirm ya da reject |
plan | Çıkarılan bir plan. | confirm ya da reject |
integration | Bir coder'ın yaması, uygulanmadan önce. | confirm (kapsam call ya da edits) ya da reject |
Kapsamlar diyaloğun tuşlarına karşılık gelir: call y, turn a, edits s, always ise p'dir. Bir gönderimde yalnızca call sunulur. edits ile kabul edilen düzenlemeler, bu ivralo serve çalıştığı sürece kabul edilmiş sayılır.
curl -s -X POST http://127.0.0.1:61017/approvals/a1… \
-H "Authorization: Bearer $TOKEN" -H "X-Ivralo-Api-Version: 2" \
-d '{"decision": "reject", "note": "Yalnızca testi değiştir, handler kodunu değil."}'
Her istek için aynı anda tek bir onay açık olabilir. IVRALO_API_APPROVAL_TIMEOUT saniye (1800) içinde kimsenin cevaplamadığı bir onay reddedilir; model bunu açıklayan bir not okur.
Sınırlar
- Aynı anda tek iş. Aynı anda yalnızca bir istek, doğrulama, inceleme ya da job devamı çalışır. İkincisi, çalışan isteğin kimliğiyle birlikte 409 alır.
- Çalışma alanının lease'i. Bir istek çalışırken çalışma alanının job lease'ini tutar. Lease bir job'daysa istek, job bitene kadar 409 alır. Ayrıntılar Job'lar sayfasında.
- Güven. API istekleri varsayılan olarak başında kimse yokmuş gibi çalışır; bu yüzden kaydı olmayan bir klasör güvenilmez sayılır ve
IVRALO.md'deki tanımlar çalışmaz."trust": true, token sahibinin "evet" demesidir. - Job akışı. Bir job'u devam ettiren akışı iptal etmek job'u durdurmaz; job'u durdurmak için
POST /jobs/{id}/cancelkullanın.
Hatalar
Bir ret, tek cümlelik bir JSON nesnesidir, {"error": "…"}, ve token hakkında hiçbir şey söylemez.
| Durum | Ne zaman |
|---|---|
| 401 | Token yok ya da yanlış. |
| 403 | İstek loopback'ten gelmiyor ya da Host başlığı bir loopback adı değil. |
| 404 | Böyle bir istek, onay, run, changeset ya da job yok. |
| 409 | API sürümü yanlış ya da eksik; çalışma alanı farklı; başka bir iş çalışıyor; lease bir job'da; onay zaten verilmiş; changeset sizin kendi düzenlemelerinizin üzerine uygulanamıyor (gövdede iki taraf da listelenir); inceleme bir repo'nun dışında ya da izin verilmemiş barındırılan bir modelde başlatılamıyor. |
| 413 | Alert gövdesi 1 MiB'tan büyük. |
| 422 | Gövde JSON değil, bir alanın türü ya da değeri yanlış ya da onayın sunmadığı bir kapsam seçilmiş. |
| 503 | Veritabanı okunamadı. |
İstemciler
ivralo ask --via-api isteği çalışan sunucuya gönderir ve onay sorularını terminalinizde cevaplamanızı sağlar; sunucu ya da token yoksa ya da istek reddedilirse 2 ile çıkar. Herhangi bir HTTP istemcisi de aynı şekilde çalışır.