Çok yüzeyli operatör onayları

Bu tasarım #103505 numaralı kaydı takip eder. Süreç yerelindeki onay yetkisinin yerine Gateway'in sahip olduğu, SQLite destekli tek bir yaşam döngüsü getirir. Gateway'in sahip olduğu her exec veya plugin/araç onayı; tek bir kararlı kimlik, kimliği doğrulanmış tek bir Control UI rotası, atomik olarak ilk yanıtın kazandığı çözümleme ve kaynak ile üst oturum akışlarına yalnızca operatöre yönelik yansıtmalar alır.

Satır içi eylemler ve derin bağlantılar birlikte bulunur. Onay modu açma/kapatma seçeneği yoktur.

Hedefler

• Exec ve plugin/araç geçitleri için tek bir kalıcı onay nesnesi.
• Kararlı ${controlUiBasePath}/approve/{approvalId} rotası.
• Yetkili herhangi bir Control UI, yerel uygulama veya kanal yüzeyinden çözümleme.
• Eşzamanlı yüzeylerde atomik olarak ilk yanıtın kazanması davranışı.
• Aynı yeniden denemeler idempotenttir; çakışan geç yanıtlar kazananın üzerine yazamaz.
• Zaman aşımı, hatalı biçimlendirilmiş güvenilir kararlar, eksik rotalar, iptal ve yeniden başlatma durumlarında kapalı kalma.
• İstek ve terminal olayları kaynak oturuma ve ilgili tüm üst/orkestratör sahiplerine ulaşır.
• Kanallar türü belirlenmiş onay ve gezinme eylemleri alır; aktarım geri çağırma verileri kanala özel kalır.
• Mevcut exec/plugin Gateway yöntemleri, uygulamaları tek bir hizmette birleşirken uyumlu kalır.

Hedef dışı konular

• Engellenmiş araç yürütmesinin kendisini Gateway yeniden başlatmaları boyunca kalıcılaştırmak veya sürdürmek.
• Bir onay kimliğini veya URL'yi taşıyıcı kimlik bilgisi hâline getirmek.
• Onay istemlerini modelin görebildiği dökümlere eklemek veya üst aracıları uyandırmak.
• Onay politikasını, ürün komutlarını veya inceleyici yetkilendirmesini kanal pluginlerine taşımak.
• Onay durumunu kanal, cihaz veya üst öğe başına klonlamak.
• Terminal sonuçlarını kesinleştirmek için gereken durumlar dışında exec izin listelerini, plugin politika bileşimini veya allow-always kalıcılığını yeniden tasarlamak.
• Gateway'siz gömülü bir TUI'yi ilk aşamada uzaktan erişilebilir hâle getirmek. Yalnızca yerel kalır ve inceleyici bulunmadığında kapalı kalmalıdır.

Kullanıma sunma öncesi temel durum ve kanıt haritası

Bu tablo, #103505 açıldığındaki uygulama durumunu kaydeder. Aşağıdaki kullanıma sunma bölümleri, bu temel durumun üzerine kurulan kalıcı kayıt defteri, türü belirlenmiş eylemler, derin bağlantı sayfası ve yerel istemci aşamalarını izler.

Güncel temsili testler arasında src/gateway/exec-approval-manager.test.ts, src/gateway/server-methods/approval-shared.test.ts, src/agents/bash-tools.exec-gateway-approval.e2e.test.ts, extensions/telegram/src/approval-handler.runtime.test.ts ve ui/src/e2e/approval-flow.e2e.test.ts bulunur.

Plugin SDK, tek kanal/plugin sınırı olmaya devam eder. Onay çalışma zamanı ve sunum değişiklikleri, mevcut src/plugin-sdk/approval-*.ts ve src/plugin-sdk/interactive-runtime.ts alt yolları üzerinden dışa aktarılmalıdır; plugin üretim kodu Gateway iç bileşenlerini içe aktarmamalıdır.

Önceki çalışmalar

Omnigent, kullanışlı kullanıcı deneyimi ve hata semantiği sağlar:

• approval.py, ASK durumunu bekletir, politika başına zaman aşımı uygular ve yalnızca tam bir kabulü onay olarak değerlendirir.
• sessions.py, sunucu tarafındaki yerel düzenek geçidini ve üst öğelere istek/çözüm yansıtmasını içerir.
• ApprovePage.tsx, bağımsız mobil onay sayfasını sağlar.

Depolama iddiasını eleştirmeden kopyalamayın. Güncel etkin bekleyen durum _elicitation_registry.py içinde süreç yerelindedir ve kullanılmayan bekleyenler tablosu e3b1f2a4c9d7_drop_pending_tool_calls_table.py tarafından kaldırılır. OpenClaw bilinçli olarak daha ileri gider: SQLite yetkili kaynaktır ve her terminal geçişi bir veritabanı karşılaştırma-ve-ayarlama işlemidir.

Mimari ve sahiplik

Yaşam döngüsünün sahibi Gateway'dir:

1. Bir aracı, plugin kancası veya Node politikası, türe özgü bir istek ve süreç yerelinde yürütme bağlaması sağlar.
2. Gateway bunu doğrular ve inceleyici için arındırılmış bir yansıtma oluşturur.
3. Onay hizmeti bir kaynak/sahip hedef kitlesi hesaplar, kurallı satırı ekler ve ardından süreç içi bekleyiciyi kaydeder.
4. Kalıcı eklemeden sonra Gateway; mevcut onay olaylarını, oturum yansıtmalarını, kanal bildirimlerini ve yerel anlık bildirimi yayınlar.
5. Her yüzey aynı hizmet üzerinden çözümleme yapar.
6. Hizmet tek bir terminal geçişini kaydeder, çalışma zamanı bekleyicisini uyandırır ve terminal yansıtmalarını yayınlar.
7. Başarısız bir olay teslimatı, kaydedilmiş kararı hiçbir zaman geri almaz; istemciler approval.get veya liste yeniden oynatması aracılığıyla kurtarır.

Sahiplik sınırları:

• src/gateway/: onay hizmeti, yetkilendirme, RPC bağdaştırıcıları, URL oluşturma, bekleyici yaşam döngüsü ve olay yayınlama.
• src/state/: paylaşılan şema ve oluşturulan Kysely türleri.
• src/infra/: arındırılmış onay görünüm modelleri ve taşınabilir sunum oluşturma.
• src/agents/: döndürülen kararı isteme, bekleme ve uygulama; kalıcılık yoktur.
• src/channels/ ve extensions/*: türü belirlenmiş eylemleri işler, kanal kullanıcılarını yetkilendirir, özel geri çağırmaları kodlar ve teslim edilmiş denetimleri günceller.
• src/plugin-sdk/: yalnızca genel onay ve sunum sözleşmeleri.
• ui/: bağımsız sayfa ve mevcut kuyruk/kalıcı pencere istemcileri.

Süreç içi bekleyici bir bildirim mekanizmasıdır, yetkili kaynak değildir. Kayıt işlemi, isteği yayınlamadan önce satırı ekler ve bekleyiciyi eşzamanlı olarak kurar; böylece bir çözümleyici bu adımların arasına giremez. Daha sonraki her çözümleyici, bu bekleyiciyi sonuçlandırmadan önce SQLite üzerinden kayıt yapar.

Kalıcı kayıt

Paylaşılan durum veritabanına tek bir operator_approvals tablosu ekleyin.

Gerekli indeksler:

Hedef kitle dizileri küçük ve sınırlıdır. Oturuma göre filtrelenmiş yeniden oynatma, önce Kysely aracılığıyla görünür bekleyen satırları seçer, ardından sınırlı hedef kitle dizilerinin kodunu çözüp uygulama kodunda filtreler; dize eşleştirme veya ham SQL JSON sorguları kullanmaz.

Terminal satırlarını, src/audit/audit-event-store.ts içindeki meta veri denetim saklama süresiyle uyumlu olarak 30 gün tutun. Temizleme, yeni bir yapılandırma yüzeyi değil, sabit bir bakım politikasıdır. Veritabanı özel yerel kontrol düzlemi durumudur, ancak inceleyici API'leri depolanan isteğin veya çalışma zamanı bağlamasının tamamını hiçbir zaman açığa çıkarmamalıdır.

Durum makinesi ve karşılaştırıp ayarlama

Yalnızca şu geçişler geçerlidir:

• pending -> allowed: açık allow-once veya allow-always.
• pending -> denied: açık ret, güvenilir hatalı biçimlendirilmiş terminal hükmü veya teslimat rotasının olmaması.
• pending -> expired: yetkili son tarihe ulaşıldı.
• pending -> cancelled: çalıştırmanın durdurulması, düzgün kapatma veya yeniden başlatma sonrası sahipsiz yürütme kurtarma.

İzin verilmeyen her terminal durumunun etkin hükmü rettir.

Çözümleme, tek bir anlık SQLite işlemi ve şuna eşdeğer bir Kysely koşullu güncellemesi kullanır:

UPDATE operator_approvalsSET status = ?, decision = ?, terminal_reason = ?, resolved_at_ms = ?WHERE approval_id = ?  AND status = 'pending'  AND expires_at_ms > ?;

Güncelleme hiçbir satırı etkilemezse aynı işlem kaydı okur:

• Eksik veya yetkisiz: bulunamadı döndürün; varlığını açığa çıkarmayın.
• Hâlâ bekliyor ancak son tarihe ulaşıldı: karşılaştırıp expired olarak ayarlayın, ardından bu terminal satırını döndürün.
• Kaydedilen kararla aynı: kaydedilen kazananla eşgüçlü başarı döndürün.
• Farklı karar: birleşik API, kaydedilen kazananla birlikte applied: false döndürür; eski bağdaştırıcılar, yayımlanmış sözleşmelerinin gerektirdiği yerlerde APPROVAL_ALREADY_RESOLVED değerini korur.
• Herhangi bir terminal durumu: hiçbir zaman değiştirmeyin.

now == expires_at_ms süresi dolmuştur. Gateway zamanı yetkilidir.

allow-once yürütmesi, mevcut tam komut/sistem çalıştırma bağlamına bağlı olarak consumed_at_ms IS NULL üzerinde ikinci bir CAS kullanır. Onay satırı tüketimden sonra denetim kaydı olarak kalır.

Kimliği doğrulanamayan veya bir onayı tanımlayamayan hatalı biçimlendirilmiş HTTP/RPC girdisi değiştirilmeden reddedilir ve hiçbir zaman onay veremez. Bilinen bir onay için güvenilir bir düzenek/bekleyiciden alınan hatalı biçimlendirilmiş terminal hükmü denied durumuna geçer.

Gateway API

Türden bağımsız inceleyici yöntemleri ekleyin:

Başarılı bir CAS işleminden sonra kaydedilmiş izdüşümü hemen döndürün. Eski olaylar, kanal ileticileri ve push terminalleştiricileri azami gayretli takip işlemleridir; yavaş veya başarısız bir yüzey, kazanan yanıtı geciktirmemeli ya da geri almamalıdır.

Türe özgü istek doğrulaması exec.approval.request ve plugin.approval.request içinde kalır. Mevcut exec.approval.get/list/waitDecision/resolve ve plugin.approval.list/waitDecision/resolve, yayımlanmış Gateway API oldukları için kurallı hizmete yönelik protokol sınırı bağdaştırıcılarına dönüşür. Dahili çağıranlar aynı değişiklik kapsamında hizmete geçirilir.

İnceleyici izdüşümü etiketli bir birleşimdir:

type OperatorApproval = {  id: string;  status: OperatorApprovalStatus;  presentation:    | { kind: "exec"; commandText: string /* güvenli exec önizlemesi */ }    | { kind: "plugin"; title: string; description: string /* güvenli plugin önizlemesi */ };  // ortak yaşam döngüsü alanları};

Kararlı yol kalıcılaştırılmaz, türetilir. approval.get, urlPath döndürür; onaylı bir herkese açık kaynağı bilen yüzeyler ayrıca mutlak bir url alabilir. İnceleyici anlık görüntüleri kaynak ve hedef kitle oturum anahtarlarını içermez. Gateway, ayrı session.approval izdüşümü için bu yönlendirme anahtarlarını sunucu tarafında tutar.

Olaylar ve taşınabilir eylemler

PR 1, yayımlanmış olay adlarını, yükleri ve mevcut kayıt düzeyindeki alıcı filtrelerini korur:

• exec.approval.requested
• exec.approval.resolved
• plugin.approval.requested
• plugin.approval.resolved

Bu eski olaylar çalışma zamanı isteğinin tamamını içerebilir; bu nedenle onay kapsamındaki her istemciye dağıtılmamalıdır. PR 5, eski olay teslimatını genişletmek yerine arındırılmış yaşam döngüsü izdüşümü aracılığıyla etiketli yaşam döngüsü alanları (status, sourceSessionKey, urlPath, terminal meta verileri ve sunum düzeyinde bir kind) ekler.

Onay kapsamlı bir session.approval izdüşüm olayı ekleyin. Kurallı olayı kalıcı hedef kitle anahtarlarıyla bir kez yayımlayın; tam oturum aboneleri eşleşen her anahtar için aynı olayı alır:

• sessionKey: izdüşümü alan akış.
• sourceSessionKey: geçidi oluşturan alt/kaynak.
• phase: onay durumuna göre ayrıştırılmış pending \| terminal.
• bir güvenli OperatorApproval izdüşümü.

İstemciler sessions.messages.subscribe { key, agentId?, includeApprovals: true } ile katılım sağlar. Başarılı yanıt, abone olan istemcinin kayıt düzeyinde incelemeye de yetkili olduğu, tam olarak bu akış anahtarına ait en fazla 1.000 mevcut bekleyen onayı içeren bir approvalReplay ekler. truncated: false, filtrelenmiş yeniden oynatmayı yetkili kılar ve yeniden bağlanan istemciler yerel bekleyen kümelerini bununla değiştirir; truncated: true bir aşırı yük sinyalidir ve istemciler kurallı arama veya sonraki yaşam döngüsü olayları bunları sonuçlandırana kadar görülmemiş yerel girdileri korumalıdır. Yeniden oynatma sırasında keşfedilen daha sonraki kalıcı bir zaman aşımı, yeni anlık görüntü döndürülmeden önce terminal mezar taşlarını yalnızca abone olan, kayıt düzeyinde yetkilendirilmiş hedef kitlelere gönderir. operator.admin doğrudan katılım sağlayabilir; daha dar kapsamlı istemciler hem eşleştirilmiş bir cihaz kimliği hem de operator.approvals gerektirir. Oturum aboneliği tek başına hiçbir zaman onay görünürlüğü sağlamaz.

Olayı src/gateway/server-broadcast.ts içindeki operator.approvals altında kaydedin. İzdüşüm gözlemseldir: hiçbir zaman transkript satırları eklemez, sessions.changed yayınlamaz veya bir ajanı uyandırmaz.

src/interactive/payload.ts içindeki MessagePresentationAction öğesini genişletin:

type MessagePresentationAction =  | { type: "command"; command: string }  | { type: "callback"; value: string }  | {      type: "approval";      approvalId: string;      approvalKind: "exec" | "plugin";      decision: ExecApprovalDecision;    }  | { type: "url"; url: string }  | { type: "web-app"; url: string };

Çekirdek, türü belirlenmiş karar eylemleri ve onaylanmış mutlak bir Control UI kaynağı mevcut olduğunda ayrı bir İncele bağlantısı oluşturur. Kanallar, bir onay eylemini kendi geri çağırma biçimlerinde kodlar ve çözümü kanonik hizmete gönderir. Geri çağırma, sığıyorsa tam kanonik kimliği; aksi takdirde satırın benzersiz tam özetli resolution_ref değerini kullanır. Başvuru yalnızca kompakt bir arama anahtarıdır: normal Gateway kimlik doğrulaması, kayıt yetkilendirmesi, açık tür, izin verilen karar doğrulaması, son tarih uzlaştırması ve ilk yanıt CAS işlemi uygulanmaya devam eder. Kanallar kimlikleri kısaltmamalı, karma öneklerini çözümlememeli, /approve metnini ayrıştırmamalı veya türü bir kimlik önekinden çıkarsamamalıdır.

button.url, button.webApp ve komut destekli onay denetimlerini, kullanımdan kaldırılmış plugin SDK uyumluluk girdileri olarak koruyun. Bunları SDK sınırında normalleştirin; paketlenmiş tüm dahili çağıranları aynı PR içinde taşıyın. /approve {id} {decision}, düğmenin anlamsal sözleşmesi değil, metin geri dönüşü ve CLI/sohbet komutu olarak kalır.

Control UI

Rota ${basePath}/approve/{approvalId} şeklindedir. Kimlik tek yol parametresidir; kaynak oturum kimliği kayıttan gelir.

Mevcut yönlendirici tam statik rotalara sahip olduğundan ve bilinmeyen yolları Chat'e yeniden yazdığından, bu derin bağlantıyı normal rota normalleştirmesinden önce ui/src/app/bootstrap.ts içinde algılayın. Normal Gateway/kimlik doğrulama kurulumunu yeniden kullanın ancak kenar çubuğu kabuğunun ve genel kalıcı iletişim kutusunun dışında bağımsız bir onay sayfası oluşturun.

Belgenin sahibi, URL'sini sunan Gateway'dir. İlk bağlantısı, tam uygulamanın kalıcı uzak Gateway seçimini, bu seçimin ayarlarını değiştirmeden veya kopyalamadan yok sayar; yalnızca kimlik doğrulama, hizmet veren Gateway oturumunun kapsamı içinde kalır. Güvenilir yerel kimlik doğrulama veya ayrıca onaylanmış bir gatewayUrl geçersiz kılması, hedefini değiştirebilir. Çekirdek, .json veya .js ile biten kimlikler de dahil olmak üzere, tek segmentli /approve ad alanını plugin HTTP rotalarından ve statik uzantı algılamasından önce ayırır; Control UI sunumu devre dışı bırakıldığında ayrılmış rota 404 ile güvenli biçimde başarısız olur. Başarısız bir geç yüklenen parçanın bir güvenlik kararını yükleme göstergesinde mahsur bırakmaması için sayfayı ana Control UI paketinde tutun.

Sayfa durumları:

• yükleniyor
• kimlik doğrulaması gerekli
• bekliyor
• çözümleniyor
• burada onaylandı veya reddedildi
• başka yerde çözümlendi
• süresi doldu
• iptal edildi
• yasak/bulunamadı
• yeniden deneme seçeneğiyle bağlantı hatası

Sayfa, kimliği doğrulanmamış ikinci bir REST API'yi değil Gateway RPC'yi çağırır. Tarayıcının yenilenmesi kalıcı durumu yeniden okur. Gateway kimlik bilgilerini hiçbir zaman URL'ye, sorguya veya parçaya yerleştirmez.

Yetkilendirme ve gizlilik

URL bir konum belirleyicidir, yetki değildir. Çözümleme için şunlar gerekir:

1. kimliği doğrulanmış Gateway bağlantısı;
2. operator.approvals veya operator.admin;
3. kayıt düzeyinde inceleyen yetkilendirmesi.

Kayıt düzeyi kuralları:

• operator.admin inceleyebilir.
• reviewer_device_ids mevcut olduğunda belirleyicidir. Yalnızca listelenmiş eşleştirilmiş bir operator.approvals cihazı inceleyebilir; istekte bulunan cihaz, ayrıca listelenmediği sürece örtük erişime sahip değildir.
• Açık bir inceleyen listesi yoksa istekte bulunan eşleştirilmiş operator.approvals cihazı kendi kaydını inceleyebilir.
• İstekte bulunan veya inceleyen bağlaması olmayan gerçekten eski kayıtlar, yükseltmelerin zaten bekleyen işleri mahsur bırakmaması için geniş eşleştirilmiş cihaz görünürlüğünü korur.
• Cihazsız dahili çalışma zamanları, kapsamlı onay çalışma zamanı bağlantısı üzerinden okuyamaz ancak çözümleyebilir. Bu yetki yalnızca sunucu tarafından kimliği doğrulanmış çalışma zamanı belirtecinden gelir; herkese açık approval.resolve alanları bunu oluşturamaz.
• Canlı istekte bulunan bağlantısının sahipliği eski bağdaştırıcılar için geçerli kalır; hiçbir zaman eşleşen bir istemci adından çıkarsanmaz.
• Hedef kitle üyeliği yalnızca sunumu değiştirir. Yetkilendirmeyi hiçbir zaman genişletmez.

approval.get, yalnızca temizlenmiş inceleyen izdüşümünü sunar ve dahili kaynak/hedef kitle yönlendirme anahtarlarını dışarıda bırakır. PR 5 session.approval olayı, Gateway kalıcı hedef kitle anlık görüntüsünü sunucu tarafında uyguladıktan sonra tek hedefi olan sessionKey ile sourceSessionKey değerini taşır. Mevcut yürütme/plugin olayları, tüketiciler taşınana kadar geçmiş yüklerini ve kısıtlı alıcılarını korur. Yürütülebilir istek, komut bağlaması ve devam yalnızca işlem içi bekleyicide kalır. Kalıcı satır; güvenli sunumun yanı sıra yaşam döngüsü, yönlendirme ve denetim meta verilerini içerir; ham ortam değerlerini, kimlik bilgilerini, kimlik doğrulama başlıklarını veya kanal geri çağırma verilerini hiçbir zaman depolamaz.

Hedef kitle izdüşümü

Hedef kitleyi eklemeden önce bir kez hesaplayın ve sıralı anlık görüntüyü kalıcılaştırın. Sahiplik her zaman tek bir üst zincir değil, bir grafiktir: bir alt öğenin hem geçerli bir denetleyicisi hem de ilk istekte bulunanı olabilir ve bu sahipler farklı köklere ulaşabilir.

Belirlenimci bir genişlik öncelikli geçiş kullanın:

1. Kuyruğu kaynak oturum anahtarıyla başlatın.
2. Kuyruktan çıkarılan her anahtar için en son alt aracı kayıt defteri satırını okuyun ve iki farklı sahiplik kenarını sabit sırayla kuyruğa ekleyin: controllerSessionKey, ardından requesterSessionKey.
3. Kullanılabilir bir kayıt defteri satırı mevcut olduğunda, yönlendirmeden sonra güncelliğini yitirmiş olabilecek oturum girdisi soyunu ayrıca izlemeyin. Aksi takdirde tek geçerli geri dönüş kenarı olan parentSessionKey ?? spawnedBy değerini kuyruğa ekleyin.
4. İlk ve en kısa yolun kazanması için kuyruğa ekleme sırasında normalleştirin ve yinelenenleri kaldırın.
5. 64 benzersiz anahtarda durun; bu hedef kitle boyutu sınırı geçiş derinliğini de sınırlar.

Kayıt defteri kaynağı src/agents/subagent-registry-read.ts; sahiplik alanları src/agents/subagent-registry.types.ts içinde tanımlanır. Oturum geri dönüş alanları src/config/sessions/types.ts içinde tanımlanır.

İstek ve sonlandırma izdüşümleri, onay beklerken odak/denetleyici sahipliği değişse bile aynı kalıcı hedef kitleyi kullanır. Bu, istek izdüşümünü alan her hedef kitle oturumu akışı için sonlandırma temizliğini garanti eder. Çözümleme her zaman kaynak onay kimliğini hedefler; hedef kitle oturumları hiçbir zaman klonlanmış onay durumu almaz. İletilen kanal mesajı temizliği, aşağıdaki ayrı teslim konumu izleme işlemidir.

Yalnızca bir onay nedeniyle döküm mesajları yazmayın, sistem istemleri eklemeyin, sahip dönüşlerini başlatmayın veya sessions.changed yayınlamayın.

Teslim edilen yüzeylerin yakınsaması

Yerel onay işleyicileri, etkin denetimleri değiştirecek veya kaldıracak kadar uzun süre teslim edilen mesaj girdilerini zaten saklar. Genel iletilmiş onay mesajları şu anda MessageReceipt değerini attığından, başka bir yüzeydeki karar eski denetimlerinin hâlâ bekliyormuş gibi görünmesine neden olabilir. Ayrı bir izleme işlemi, paylaşılan durum veritabanındaki bir operator_approval_deliveries alt tablosuyla bu açığı kapatır.

Her satır; onay kimliğini, benzersiz teslim kimliğini, kanal/hesap/tam rotayı, sınırlandırılmış ve JSON ile doğrulanmış kanala özel mesaj konum belirleyicisini, teslim zaman damgalarını ve sonlandırma durumunu depolar. Geri çağırma verilerini, karar belirteçlerini veya ham onay isteklerini hiçbir zaman depolamaz. Konum belirleyici kodlama ve mesaj değişikliğinin sahibi kanaldır; kanonik durum, hedef seçimi, yeniden deneme politikası ve geri dönüş sonlandırma metninin sahibi çekirdektir.

Teslim kaydı ve sonlandırma çözümlemesi yarış durumlarını güvenli biçimde işler:

1. Bekleyen bir gönderim makbuzunu döndürdükten sonra teslim konum belirleyicisini ekleyin ve üst onay durumunu tek bir işlem içinde okuyun.
2. Üst öğe zaten sonlandırılmışsa geç teslimi beklemede bırakmak yerine hemen sonlandırılmasını zamanlayın.
3. Kaydedilen her sonlandırma geçişi, sonlandırılmamış tüm teslim satırlarını ayrıca zamanlar; bırakılabilir yayınlar tetikleyici değildir.
4. Bir kanal sonlandırıcısı replaced, retired veya unsupported bildirir. Değiştirildi durumu yinelenen sonlandırma mesajını engeller; kaldırıldı durumu mevcut sonlandırma izleme mesajını gönderir; desteklenmeme veya hata, onay CAS işlemini geri almadan geri dönüşü kullanır.
5. Başlangıç, tamamlanmamış teslimlere sahip sonlandırılmış onayları yeniden dener ve temizliği Gateway yeniden başlatmasına dayanıklı hâle getirir.

Bu taşıma yaşam döngüsü, bir oluşturucu veya modele yönelik mesaj eylemi değil, isteğe bağlı bir teslim bağdaştırıcısı kancasıdır. QQ C2C/grup mesajlarında şu anda düzenleme, silme veya klavye temizleme API'si yoktur; bu bağdaştırıcı desteklenmemeye devam eder ve taşıma bir değişiklik API'si edinene kadar yalnızca sonraki bir tıklamadan sonra kanonik gerçeği gösterebilir.

Yeniden başlatma, zaman aşımı ve rota semantiği

SQLite kalıcılığı, yürütmenin sürdürüleceği anlamına gelmez. Komut/araç bağlamaları güvenlik açısından hassas çalışma zamanı bilgileri içerebildiğinden ve sürdürülebilir bir iş sözleşmesi olmadığından bellekte kalır.

Gateway başlatıldığında:

• yeni bir çalışma zamanı dönemi oluşturun;
• eski dönemlerdeki bekleyen satırları atomik olarak gateway-restart nedeniyle cancelled durumuna geçirin;
• URL'lerinin ne olduğunu açıklayabilmesi için satırları koruyun;
• eksik bir çalışma zamanı bağlamasına karşı daha sonraki bir onayı hiçbir zaman yürütmeyin.

Zamanlayıcılar uyandırma iyileştirmeleridir. Son tarih yetkisi expires_at_ms içinde depolanır; okumalar, beklemeler ve çözümlemelerin tümü süre sonu uzlaştırmasını çalıştırır.

Nihai katı davranış:

• zaman aşımı -> expired, reddet;
• rota yok -> denied, reddet;
• çalıştırma iptali -> cancelled, reddet;
• hatalı biçimlendirilmiş güvenilir karar -> denied, reddet;
• yalnızca izin verilen açık bir izin kararı -> allowed.

Şu anda yayımlanmış yürütme davranışı bu sözleşmeyle hâlâ çelişmektedir:

• src/agents/bash-tools.exec-host-shared.ts, askFallback uygulayabilir.
• docs/tools/exec-approvals.md ve docs/cli/approvals.md bu yüzeyi belgeler.

Plugin onayları artık zaman aşımı ve hatalı biçimlendirilmiş kararlarda güvenli biçimde başarısız olur; eski timeoutBehavior alanı kabul edilmeye devam eder ancak yok sayılır. Yürütmenin katı semantiğine yönelik izleme işlemi; kodu, türleri, belgeleri, testleri ve değişiklik günlüğünü açık sahip/güvenlik incelemesiyle birlikte güncellemelidir. askFallback geçiş sırasında kapı öncesi politika seçimini açıklamaya devam edebilir ancak oluşturulmuş bekleyen bir kaydın zaman aşımını onaya dönüştürmemelidir.

Uyumluluk planı

• Eklemeli Gateway protokolü; protokol sürümü artırılmaz.
• Harici sınırda mevcut yürütme/plugin yöntemlerini ve olaylarını koruyun.
• plugin: önekleri dahil mevcut kimlikleri koruyun ancak önekleri tür bilgisi olarak kullanmayı bırakın.
• /approve metin komutu davranışını koruyun.
• Eski düğme URL/Web App alanlarını ve komut eylemlerini plugin SDK uyumluluk girdisi olarak koruyun; yeni çekirdek çıktısı türü belirlenmiştir.
• Paketlenmiş tüm kanalları ve dahili çağıranları aynı türü belirlenmiş eylem değişikliğinde taşıyın.
• Yeni URL/sayfa ve daha sonraki zaman aşımı davranışı değişikliği için bir değişiklik günlüğü girdisi ekleyin.
• Bir bilgi isteme modu ayarı eklemeyin.

Kullanıma sunma

PR 1: kalıcı yaşam döngüsü

• Bu tasarım notu.
• Paylaşılan SQLite şeması, Kysely oluşturma işlemi, depo ve 30 günlük budama.
• Gateway onay hizmeti, çalışma zamanı bekleyici köprüsü ve yeniden başlatma sahipsiz kayıt işleme.
• Birleştirilmiş approval.get/resolve.
• Yürütme/plugin yöntem bağdaştırıcıları.
• İlk yanıt kazanır, eşgüçlülük, süre sonu, yetkilendirme ve tüketim testleri.
• Henüz UI veya kanal davranışı değişikliği yok.

PR 2: türü belirlenmiş eylemler ve kanal geri çağırmaları

• Türü belirlenmiş onay, URL ve Web App eylemleri.
• Çekirdek sunum oluşturucuları ve plugin SDK dışa aktarımları.
• Açık sahip türüyle taşıma katmanına özel geri çağırma kodlaması.
• Taşıma sınırlarını aşan kanonik kimlikler için kalıcı, sabit boyutlu geri çağırma başvuruları.
• Paketlenmiş kanalların komut metni ve onay kimliği çıkarımından uzaklaştırılması.
• Tıklanan yüzeyde kanonik ilk yanıt doğrusu ve mümkün olan en iyi şekilde etkin yerel terminal güncellemeleri; kalıcı kanal iletisi terminalleştirmesi sonraki çalışma olarak kalır.
• SDK ve paketlenmiş kanal testleri.

PR 3: Control UI derin bağlantısı

• Bağımsız, kimliği doğrulanmış onay sayfası ve temel yolu dikkate alan başlangıç yönlendirmesi.
• Operatörün kaydedilmiş uzak seçimini değiştirmeden hizmet sunan Gateway'e bağlanma.
• Varlık benzeri kimlikler dâhil, çekirdeğin sahip olduğu onay HTTP ad alanı.
• Gateway tarafından oluşturulan URL yükü ve yaşam döngüsü olayları kullanıma sunulana kadar bekleyen durumun yoklanması.
• Mobil genişlik, yeniden bağlanma, birbiriyle yarışan yanıtlar, yeniden yükleme ve bağlı yol kanıtı.

PR 4: yerel istemciler

• iOS ve Android inceleme yüzeyleri türe duyarlı approval.get/resolve kullanır; watchOS, inceleyici açısından güvenli istemleri ve kararları eşleştirilmiş iPhone üzerinden aktarır.
• Watch, kompakt aktarma sözleşmesinin desteklediği yürütme kararlarını sunar: bir kez izin ver ve reddet.
• Kanonik ilk yanıt terminal doğrusu, yerel denenmiş karar durumunun yerini alır.
• Kaybolan veya belirsiz çözümleme alındıları, kanonik geri okuma gerçekleşene kadar denetimleri dondurur.
• Daha önce yayımlanmış Gateway v4 örnekleri, dar kapsamlı bir eski yöntem geri dönüşü üzerinden yürütme incelemesini korur; yüzeyler arasında korunan terminal durumu, birleştirilmiş yöntemleri gerektirir.
• İnceleyici uyarıları ve sahip bağlamı iPhone, Watch ve Android genelinde görünür kalır.
• Yerel birim, derleme ve platform kanıtı.

PR 5: üst öğe yaşam döngüsü yayılımı

• PR 1'de kalıcılaştırılan hedef kitle anlık görüntüsünden session.approval bekleyen/terminal teslimatı.
• Transkript değişikliği veya ajan uyandırması olmadan tam oturum aboneliği, yeniden bağlanma tekrarı ve terminal mezar taşları.
• Yaşam döngüsü geri çağırmaları kalıcı ekleme/CAS işleminden sonra çalışır ve hiçbir zaman onay yetkisi hâline gelmez.
• İç içe alt ajan ve yeniden bağlanma kanıtı.

PR 6: kapalı başarısızlık davranışı

• node-invoke-plugin-policy.ts ve gömülü plugin aracısını yinelenen yetkiden uzaklaştırın.
• Katı zaman aşımı, hatalı biçim, rota yokluğu, bağlama ve bir kez izin verme tüketim semantiği.
• Bir istek beklemeye alındıktan sonra bunlara uymadan, yayımlanmış izin verici zaman aşımı ayarlarını kullanımdan kaldırın.
• Çok yüzeyli çekişme ve hata ekleme kanıtı.

Sonraki çalışma: kalıcı uzak ileti temizliği

• İletilen teslimat konumlandırıcılarını kalıcılaştırın ve yeniden başlatmadan sonra teslim edilen her kanal iletisini terminalleştirin.
• Bu taşıma yaşam döngüsünü kanonik onay yetkisinden ve türü belirlenmiş sunum eylemlerinden ayrı tutun.

Testler

Gerekli odaklanmış kapsam:

• SQLite'ın yeniden açılması, bekleyen ve terminal projeksiyonlarını korur.
• Eşzamanlı iki çözümleyici tam olarak bir CAS kazananı üretir.
• Aynı kararın yeniden denenmesi eşgüçlü biçimde başarılı olur; çelişen yeniden deneme kaydedilmiş kazananı döndürür.
• Son tarihte veya sonrasında çözümleme, onay veremez.
• allow-once, terminal denetim durumunu silmeden tam olarak bir kez tüketilebilir.
• Başlangıç, daha eski çalışma zamanı dönemlerini iptal eder.
• Yetkisiz arama ve çözümleme, kaydın varlığını açığa çıkarmaz.
• Açık inceleyici izin listesi ve genel eşleştirilmiş operator.approvals davranışı.
• Yürütme ve plugin eski yöntemleri aynı depoyu paylaşır.
• Gateway istek/listeleme/getirme/çözümleme şemaları ve eklemeli olay yükleri.
• Türü belirlenmiş eylem normalleştirmesi, geri dönüşlü işleme, SDK dışa aktarımları ve paketlenmiş kanal geçişleri.
• Telegram geri çağırma kodlaması, taşıma katmanına özel veriler içerir ve komut dizesi çıkarımı içermez.
• Doğrudan alt öğe, dallanmış denetleyici/isteyen sahipleri, iç içe sahipler, yeniden atama, oturum alanı geri dönüşü, döngü ve hedef kitle boyutu üst sınırı.
• İstenen ve terminal hedef kitle dizileri aynıdır.
• Sahip projeksiyonları transkript değişikliğine veya ajan uyandırmasına neden olmaz.
• Control UI rotası / konumunda ve yapılandırılmış bir temel yolda çalışır; yenileme, bekleyen veya terminal doğrusunu gösterir.
• Eşzamanlı Control UI ve Telegram yanıtları bir kazanan, kaybeden tarafta ise "başka yerde çözümlendi" ifadesini gösterir.
• Yerel onay tanımlayıcıları ve Gateway sahip tanımlayıcıları, yönlendirme ve uzlaştırma boyunca tam UTF-8 baytlarını korur.
• Yerel RPC ailesi uzlaşması, kabul edilen her Gateway rotası için tek bir kanonik veya eski aileyi sabitler ve kullanımdan sonra hiçbir zaman sessizce alt sürüme geçmez.
• Kaybolan yerel çözümleme alındıları, kanonik geri okumaya kadar eylemleri dondurur; başarısız geri okuma bir kazanan uyduramaz veya Watch yenilemesini alındılayamaz.
• Watch anlık görüntü isteği korelasyonu yalnızca tam olarak eşleştirilmiş Gateway sahibi ve tamamlanmış kanonik iPhone geri okuması için kabul edilir.
• Mobil genişlikte bir onay sayfası, Telegram eylem temizliği ve Android, iPhone ve Watch arasında bir bekleme/çözümleme/geç kalan kaybeden gidiş dönüşü dâhil olmak üzere Testbox/Crabbox üzerinden kullanıcı yolu kanıtı.

Gözlemlenebilirlik

Onay kimliği, tür, kaynak oturum anahtarı, durum, neden ve gecikme süresini içeren yapılandırılmış, içeriksiz geçiş günlükleri yayınlayın. Önizlemeyi veya ham bağlamayı hiçbir zaman günlüğe kaydetmeyin.

Şunları izleyin:

• türe göre istenen sayısı;
• tür/durum/nedene göre terminal sayısı;
• bekleyen göstergesi;
• istekten terminale gecikme süresi;
• çözümleme yarışı sonuçları: kazanan, eşgüçlü yeniden deneme, çakışma, süresi dolmuş;
• teslimat rotası sayısı ve rota yokluğu retleri;
• başlangıçta yetim kalanların iptalleri;
• hedef kitle boyutu.

Daha sonraki olay teslimatı başarısız olsa bile kaydedilmiş bir geçiş başarılıdır. Yaşam döngüsü aboneleri, PR 5 tekrarı ve kanonik arama yoluyla kurtarılır. Kalıcı kanal iletisi terminalleştirmesi, yukarıdaki ayrı sonraki çalışma olarak kalır.

Açık kararlar

1. Haricen erişilebilen Control UI kaynağı. Her anlık görüntü, kararlı göreli urlPath taşır. Mutlak URL yalnızca Gateway erişimi başarıyla sağlandıktan sonra önbelleğe alınmış bir Tailscale Serve/Funnel konumundan duyurulabilir; allowedOrigins, istek Host üstbilgileri, gateway.remote.url ve yalnızca görüntüleme amaçlı geri döngü/LAN adayları kanonik kaynaklar değildir. Telegram, başlangıç hazırlığı boyunca onay yolunu korumak için kimliği doğrulanmış Mini App sarmalayıcısını kullanabilir. Ayrı olarak incelenmiş açık bir genel URL sözleşmesi bulunana kadar rastgele ters proxy'ler yalnızca göreli kalır. Bir kanalın kaynağı tahmin etmesine hiçbir zaman izin vermeyin.
2. Yürütme katı zaman aşımı uyumluluk geçişi. Plugin onay zaman aşımları artık kapalı biçimde başarısız olur ve timeoutBehavior kullanımdan kaldırılmıştır. Kalan yayımlanmış askFallback sözleşmesinin, bekleyen bir istek zaman aşımına uğradıktan sonra yürütmeye yetki vermeyi durdurmasından önce açık sahip/güvenlik incelemesi, değişiklik günlüğü, belgeler ve bir geçiş/kullanımdan kaldırma kararı gerekir.
3. Gateway'siz gömülü mod. Öneri: başlangıçta yalnızca yerel tutun, ardından bir Gateway mevcut olduğunda bunu kanonik hizmetin istemcisi hâline getirin. Hiçbir sunucunun çözümleyemeyeceği bir derin bağlantıyı duyurmayın.