Persetujuan operator multi-permukaan

Desain ini melacak #103505. Desain ini menggantikan otoritas persetujuan lokal-proses dengan satu siklus hidup milik Gateway yang didukung SQLite. Setiap persetujuan eksekusi atau plugin/alat milik Gateway mendapatkan satu ID stabil, satu rute Control UI terautentikasi, resolusi atomik dengan jawaban pertama sebagai pemenang, serta proyeksi khusus operator ke aliran sesi sumber dan leluhurnya.

Tindakan sebaris dan tautan dalam digunakan berdampingan. Tidak ada pengalih mode persetujuan.

Tujuan

• Satu objek persetujuan persisten untuk gerbang eksekusi dan plugin/alat.
• Rute ${controlUiBasePath}/approve/{approvalId} yang stabil.
• Resolusi dari Control UI, aplikasi native, atau permukaan kanal mana pun yang diotorisasi.
• Perilaku atomik dengan jawaban pertama sebagai pemenang di seluruh permukaan yang berjalan bersamaan.
• Percobaan ulang identik yang idempoten; jawaban terlambat yang bertentangan tidak dapat menimpa pemenang.
• Batas waktu, putusan tepercaya yang salah format, rute yang hilang, pembatalan, dan mulai ulang semuanya gagal secara tertutup.
• Peristiwa permintaan dan terminal mencapai sesi sumber serta semua pemilik induk/orkestrator yang relevan.
• Kanal menerima tindakan persetujuan dan navigasi bertipe; data callback transportasi tetap privat bagi kanal.
• Metode Gateway untuk eksekusi/plugin yang sudah ada tetap kompatibel sementara implementasinya dikonvergensikan ke satu layanan.

Bukan tujuan

• Mempertahankan atau melanjutkan kembali eksekusi alat yang diblokir itu sendiri setelah Gateway dimulai ulang.
• Menjadikan ID atau URL persetujuan sebagai kredensial bearer.
• Menambahkan permintaan persetujuan ke transkrip yang terlihat oleh model atau membangunkan agen induk.
• Memindahkan kebijakan persetujuan, perintah produk, atau otorisasi peninjau ke Plugin kanal.
• Menggandakan status persetujuan per kanal, perangkat, atau leluhur.
• Mendesain ulang daftar izin eksekusi, komposisi kebijakan plugin, atau persistensi allow-always, kecuali jika diperlukan agar hasil terminal tidak ambigu.
• Membuat TUI tersemat tanpa Gateway dapat dijangkau dari jarak jauh pada tahap pertama. TUI tersebut tetap hanya lokal dan harus gagal secara tertutup ketika tidak ada peninjau.

Dasar acuan sebelum peluncuran dan peta bukti

Tabel ini mencatat status implementasi saat #103505 dibuka. Bagian peluncuran di bawah melacak registri persisten, tindakan bertipe, halaman tautan dalam, dan tahap klien native yang dibangun di atas dasar acuan tersebut.

Pengujian representatif saat ini mencakup 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, dan ui/src/e2e/approval-flow.e2e.test.ts.

SDK plugin tetap menjadi satu-satunya batas kanal/plugin. Perubahan runtime dan presentasi persetujuan harus diekspor melalui subjalur src/plugin-sdk/approval-*.ts dan src/plugin-sdk/interactive-runtime.ts yang sudah ada; kode produksi plugin tidak boleh mengimpor internal Gateway.

Implementasi terdahulu

Omnigent menyediakan semantik UX dan kegagalan yang berguna:

• approval.py menangguhkan ASK, menerapkan batas waktu per kebijakan, dan hanya memperlakukan penerimaan yang persis sebagai persetujuan.
• sessions.py berisi gerbang harness native sisi server serta proyeksi permintaan/resolusi leluhur.
• ApprovePage.tsx menyediakan halaman persetujuan seluler mandiri.

Jangan menyalin klaim penyimpanannya tanpa penilaian kritis. Status aktif yang tertunda saat ini bersifat lokal-proses di _elicitation_registry.py, dan tabel tertunda yang tidak digunakan dihapus oleh e3b1f2a4c9d7_drop_pending_tool_calls_table.py. OpenClaw sengaja melangkah lebih jauh: SQLite bersifat otoritatif dan setiap transisi terminal merupakan compare-and-set basis data.

Arsitektur dan kepemilikan

Gateway memiliki siklus hidup:

1. Agen, hook plugin, atau kebijakan node menyediakan permintaan khusus jenis dan pengikatan eksekusi lokal-proses.
2. Gateway memvalidasinya dan membangun proyeksi peninjau yang telah disanitasi.
3. Layanan persetujuan menghitung audiens sumber/pemilik, menyisipkan baris kanonis, lalu mendaftarkan penunggu dalam proses.
4. Setelah penyisipan persisten, Gateway menerbitkan peristiwa persetujuan yang sudah ada, proyeksi sesi, notifikasi kanal, dan push native.
5. Setiap permukaan melakukan resolusi melalui layanan yang sama.
6. Layanan melakukan commit atas satu transisi terminal, membangunkan penunggu runtime, dan menerbitkan proyeksi terminal.
7. Kegagalan pengiriman peristiwa tidak pernah membatalkan keputusan yang telah di-commit; klien melakukan pemulihan melalui approval.get atau pemutaran ulang daftar.

Batas kepemilikan:

• src/gateway/: layanan persetujuan, otorisasi, adaptor RPC, konstruksi URL, siklus hidup penunggu, dan penerbitan peristiwa.
• src/state/: skema bersama dan tipe Kysely yang dihasilkan.
• src/infra/: model tampilan persetujuan yang telah disanitasi dan konstruksi presentasi portabel.
• src/agents/: meminta, menunggu, dan menerapkan putusan yang dikembalikan; tanpa persistensi.
• src/channels/ dan extensions/*: merender tindakan bertipe, mengotorisasi pengguna kanal, mengodekan callback privat, dan memperbarui kontrol yang telah dikirimkan.
• src/plugin-sdk/: hanya kontrak persetujuan dan presentasi publik.
• ui/: halaman mandiri serta klien antrean/modal yang sudah ada.

Penunggu dalam proses adalah mekanisme notifikasi, bukan otoritas. Pendaftaran menyisipkan baris dan memasang penunggu secara sinkron sebelum menerbitkan permintaan, sehingga resolver tidak dapat menyela di antara kedua langkah tersebut. Setiap resolver berikutnya melakukan commit melalui SQLite sebelum menyelesaikan penunggu tersebut.

Catatan persisten

Tambahkan satu tabel operator_approvals ke basis data status bersama.

Indeks yang diperlukan:

Larik audiens berukuran kecil dan terbatas. Replay yang difilter berdasarkan sesi terlebih dahulu memilih baris tertunda yang terlihat melalui Kysely, lalu mendekode dan memfilter larik audiens terbatas dalam kode aplikasi; proses ini tidak menggunakan pencocokan string atau kueri JSON SQL mentah.

Simpan baris terminal selama 30 hari, selaras dengan retensi audit metadata di src/audit/audit-event-store.ts. Pemangkasan adalah kebijakan pemeliharaan tetap, bukan permukaan konfigurasi baru. Basis data merupakan status bidang kontrol lokal privat, tetapi API peninjau tidak boleh mengekspos seluruh permintaan tersimpan atau pengikatan runtime.

Mesin status dan bandingkan-dan-tetapkan

Hanya transisi berikut yang valid:

• pending -> allowed: allow-once atau allow-always eksplisit.
• pending -> denied: penolakan eksplisit, putusan terminal salah format yang tepercaya, atau tidak ada rute pengiriman.
• pending -> expired: tenggat waktu otoritatif tercapai.
• pending -> cancelled: pembatalan proses, penghentian tertib, atau pemulihan yatim setelah dimulai ulang.

Setiap status terminal yang tidak diizinkan memiliki putusan efektif berupa penolakan.

Penyelesaian menggunakan satu transaksi SQLite langsung dan pembaruan bersyarat Kysely yang setara dengan:

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

Jika pembaruan tidak memengaruhi baris apa pun, transaksi yang sama membaca catatan:

• Tidak ada atau tidak diotorisasi: kembalikan tidak ditemukan; jangan ungkap keberadaannya.
• Masih tertunda tetapi tenggat waktu tercapai: gunakan bandingkan-dan-tetapkan untuk mengubahnya menjadi expired, lalu kembalikan baris terminal tersebut.
• Keputusan tercatat yang sama: kembalikan keberhasilan idempoten beserta pemenang yang tercatat.
• Keputusan berbeda: API terpadu mengembalikan applied: false beserta pemenang yang tercatat; adaptor lama mempertahankan APPROVAL_ALREADY_RESOLVED jika diwajibkan oleh kontrak yang telah dirilis.
• Status terminal apa pun: jangan pernah memutasinya.

now == expires_at_ms telah kedaluwarsa. Waktu Gateway bersifat otoritatif.

Eksekusi allow-once menggunakan CAS kedua atas consumed_at_ms IS NULL, yang terikat pada konteks perintah/proses sistem persis yang sudah ada. Baris persetujuan tetap menjadi catatan audit setelah dikonsumsi.

Input HTTP/RPC salah format yang tidak dapat diautentikasi atau tidak dapat mengidentifikasi persetujuan ditolak tanpa mutasi dan tidak pernah dapat menyetujui. Putusan terminal salah format yang diterima dari harness/waiter tepercaya untuk persetujuan yang diketahui mengalihkan status menjadi denied.

API Gateway

Tambahkan metode peninjau yang tidak bergantung pada jenis:

Setelah CAS berhasil, segera kembalikan proyeksi yang telah dikomit. Peristiwa lama, penerus kanal, dan penentu terminal push merupakan tindak lanjut upaya terbaik; permukaan yang lambat atau gagal tidak boleh menunda atau melakukan rollback terhadap respons pemenang.

Validasi permintaan khusus jenis tetap berada di exec.approval.request dan plugin.approval.request. exec.approval.get/list/waitDecision/resolve dan plugin.approval.list/waitDecision/resolve yang ada menjadi adaptor batas protokol ke layanan kanonis karena keduanya merupakan API Gateway yang telah dirilis. Pemanggil internal bermigrasi ke layanan dalam perubahan yang sama.

Proyeksi peninjau adalah union bertag:

type OperatorApproval = {  id: string;  status: OperatorApprovalStatus;  presentation:    | { kind: "exec"; commandText: string /* pratinjau exec yang aman */ }    | { kind: "plugin"; title: string; description: string /* pratinjau plugin yang aman */ };  // bidang siklus hidup umum};

Path stabil diturunkan, bukan dipersistenkan. approval.get mengembalikan urlPath; permukaan yang mengetahui origin publik yang disetujui juga dapat menerima url absolut. Snapshot peninjau menghilangkan kunci sesi sumber dan audiens. Gateway menyimpan kunci perutean tersebut di sisi server untuk proyeksi session.approval yang terpisah.

Peristiwa dan tindakan portabel

PR 1 mempertahankan nama peristiwa, payload, dan filter penerima tingkat catatan yang telah dirilis:

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

Peristiwa lama tersebut dapat berisi seluruh permintaan runtime, sehingga tidak boleh disebarkan ke setiap klien yang tercakup dalam persetujuan. PR 5 menambahkan bidang siklus hidup bertag (status, sourceSessionKey, urlPath, metadata terminal, dan kind tingkat presentasi) melalui proyeksi siklus hidup yang telah disanitasi, alih-alih memperluas pengiriman peristiwa lama.

Tambahkan peristiwa proyeksi session.approval yang tercakup dalam persetujuan. Publikasikan peristiwa kanonis satu kali dengan kunci audiens yang dipersistenkan; pelanggan sesi persis menerima peristiwa yang sama untuk setiap kunci yang cocok:

• sessionKey: stream yang menerima proyeksi.
• sourceSessionKey: turunan/sumber yang memicu gerbang.
• phase: pending \| terminal, didiskriminasi terhadap status persetujuan.
• satu proyeksi OperatorApproval yang aman.

Klien memilih ikut serta dengan sessions.messages.subscribe { key, agentId?, includeApprovals: true }. Respons yang berhasil menambahkan approvalReplay yang berisi hingga 1.000 persetujuan tertunda saat ini untuk kunci stream persis tersebut, yang juga diotorisasi pada tingkat catatan untuk ditinjau oleh klien pelanggan. truncated: false menjadikan replay terfilter bersifat otoritatif dan klien yang tersambung kembali mengganti kumpulan tertunda lokalnya dengan replay tersebut; truncated: true adalah sinyal beban berlebih dan klien harus mempertahankan entri lokal yang belum terlihat sampai pencarian kanonis atau peristiwa siklus hidup berikutnya menyelesaikannya. Waktu habis persisten yang ditemukan kemudian selama replay memancarkan tombstone terminal hanya kepada audiens pelanggan yang diotorisasi pada tingkat catatan sebelum snapshot baru dikembalikan. operator.admin dapat ikut serta secara langsung; klien yang lebih sempit memerlukan identitas perangkat berpasangan dan operator.approvals. Langganan sesi saja tidak pernah memberikan visibilitas persetujuan.

Daftarkan peristiwa di bawah operator.approvals dalam src/gateway/server-broadcast.ts. Proyeksi ini bersifat observasional: tidak pernah menambahkan baris transkrip, memancarkan sessions.changed, atau membangunkan agen.

Perluas MessagePresentationAction dalam src/interactive/payload.ts:

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 };

Core membangun tindakan keputusan bertipe dan tautan Tinjau terpisah saat origin absolut Control UI yang disetujui tersedia. Kanal mengodekan tindakan persetujuan ke dalam format callback masing-masing dan mengirimkan penyelesaian ke layanan kanonis. Callback menggunakan ID kanonis yang persis jika muat; jika tidak, callback menggunakan resolution_ref digest lengkap unik milik baris tersebut. Referensi tersebut hanyalah kunci pencarian ringkas: autentikasi Gateway normal, otorisasi rekaman, jenis eksplisit, validasi keputusan yang diizinkan, rekonsiliasi tenggat, dan CAS jawaban pertama tetap berlaku. Kanal tidak boleh memotong ID, menguraikan prefiks hash, mengurai teks /approve, atau menyimpulkan jenis dari prefiks ID.

Pertahankan button.url, button.webApp, dan kontrol persetujuan berbasis perintah sebagai input kompatibilitas SDK plugin yang tidak digunakan lagi. Normalkan semuanya di batas SDK; migrasikan setiap pemanggil internal bawaan dalam PR yang sama. /approve {id} {decision} tetap menjadi fallback teks dan perintah CLI/obrolan, bukan kontrak semantik tombol.

Control UI

Rutenya adalah ${basePath}/approve/{approvalId}. ID adalah satu-satunya parameter jalur; identitas sesi sumber berasal dari rekaman.

Karena router saat ini memiliki rute statis persis dan menulis ulang jalur yang tidak dikenal ke Obrolan, deteksi deep link ini di ui/src/app/bootstrap.ts sebelum normalisasi rute biasa. Gunakan kembali penyiapan Gateway/autentikasi normal, tetapi render halaman persetujuan mandiri di luar shell bilah samping dan modal global.

Dokumen dimiliki oleh Gateway yang menyajikan URL-nya. Koneksi awalnya mengabaikan pilihan Gateway jarak jauh tersimpan milik aplikasi lengkap tanpa mengubah atau menyalin pengaturan pilihan tersebut; hanya autentikasi yang tetap dibatasi pada sesi untuk Gateway penyaji. Autentikasi native tepercaya atau override gatewayUrl yang dikonfirmasi secara terpisah dapat mengarahkannya ulang. Core mencadangkan namespace satu segmen /approve sebelum rute HTTP plugin dan deteksi ekstensi statis, termasuk ID yang berakhiran .json atau .js; saat penyajian Control UI dinonaktifkan, rute yang dicadangkan gagal secara tertutup dengan 404. Pertahankan halaman dalam bundel utama Control UI agar kegagalan chunk lazy tidak membiarkan keputusan keamanan terhenti pada indikator pemuatan.

Status halaman:

• memuat
• autentikasi diperlukan
• tertunda
• sedang menyelesaikan
• disetujui atau ditolak di sini
• diselesaikan di tempat lain
• kedaluwarsa
• dibatalkan
• dilarang/tidak ditemukan
• kesalahan koneksi dengan coba lagi

Halaman memanggil RPC Gateway, bukan API REST kedua tanpa autentikasi. Penyegaran browser membaca ulang status persisten. Halaman tidak pernah menempatkan kredensial Gateway dalam URL, kueri, atau fragmen.

Otorisasi dan privasi

URL adalah pencari lokasi, bukan otoritas. Penyelesaian memerlukan:

1. koneksi Gateway terautentikasi;
2. operator.approvals atau operator.admin;
3. otorisasi peninjau tingkat rekaman.

Aturan tingkat rekaman:

• operator.admin dapat meninjau.
• reviewer_device_ids bersifat otoritatif saat tersedia. Hanya perangkat operator.approvals tersanding yang tercantum yang dapat meninjau; perangkat peminta tidak memiliki akses implisit kecuali perangkat tersebut juga tercantum.
• Tanpa daftar peninjau eksplisit, perangkat operator.approvals tersanding yang meminta dapat meninjau rekamannya sendiri.
• Rekaman lama yang benar-benar tidak memiliki pengikatan peminta atau peninjau mempertahankan visibilitas luas bagi perangkat tersanding agar peningkatan tidak menelantarkan pekerjaan yang sudah tertunda.
• Runtime internal tanpa perangkat dapat menyelesaikan, tetapi tidak membaca, melalui koneksi runtime persetujuan yang dibatasi. Otoritas tersebut hanya berasal dari token runtime yang diautentikasi server; bidang publik approval.resolve tidak dapat membuatnya.
• Kepemilikan koneksi peminta aktif tetap valid untuk adaptor lama; kepemilikan tersebut tidak pernah disimpulkan dari nama klien yang cocok.
• Keanggotaan audiens hanya mengubah penyajian. Keanggotaan tersebut tidak pernah memperluas otorisasi.

approval.get hanya mengekspos proyeksi peninjau yang telah disanitasi dan menghilangkan kunci perutean sumber/audiens internal. Peristiwa session.approval PR 5 membawa satu tujuan sessionKey miliknya beserta sourceSessionKey setelah Gateway menerapkan snapshot audiens persisten di sisi server. Peristiwa exec/plugin yang ada mempertahankan payload historis dan penerima terbatasnya hingga konsumen bermigrasi. Permintaan yang dapat dieksekusi, pengikatan perintah, dan kelanjutan hanya tetap berada dalam waiter lokal proses. Baris persisten berisi penyajian aman beserta metadata siklus hidup, perutean, dan audit; baris tersebut tidak pernah menyimpan nilai lingkungan mentah, kredensial, header autentikasi, atau data callback kanal.

Proyeksi audiens

Hitung audiens sekali sebelum penyisipan dan simpan snapshot yang terurut. Kepemilikan merupakan graf, bukan selalu satu rantai induk: sebuah anak dapat memiliki pengendali saat ini sekaligus peminta asli, dan pemilik tersebut dapat mengarah ke root yang berbeda.

Gunakan penelusuran breadth-first deterministik:

1. Isi awal antrean dengan kunci sesi sumber.
2. Untuk setiap kunci yang dikeluarkan dari antrean, baca baris registri subagen terbaru dan antrekan kedua sisi kepemilikan yang berbeda dalam urutan tetap: controllerSessionKey, lalu requesterSessionKey.
3. Saat baris registri yang dapat digunakan tersedia, jangan turut mengikuti garis keturunan entri sesi yang mungkin sudah usang setelah pengarahan. Jika tidak, antrekan satu sisi fallback saat ini parentSessionKey ?? spawnedBy.
4. Normalkan dan hapus duplikasi saat memasukkan ke antrean agar jalur pertama dan terpendek menang.
5. Berhenti pada 64 kunci unik; batas ukuran audiens ini juga membatasi kedalaman penelusuran.

Sumber registri adalah src/agents/subagent-registry-read.ts; bidang kepemilikan didefinisikan di src/agents/subagent-registry.types.ts. Bidang fallback sesi didefinisikan di src/config/sessions/types.ts.

Proyeksi permintaan dan terminal menggunakan audiens persisten yang sama meskipun kepemilikan fokus/pengendali berubah selama persetujuan tertunda. Ini menjamin pembersihan terminal untuk setiap aliran sesi audiens yang menerima proyeksi permintaan. Penyelesaian selalu menargetkan ID persetujuan sumber; sesi audiens tidak pernah menerima status persetujuan hasil kloning. Pembersihan pesan kanal yang diteruskan tetap menjadi tindak lanjut pencari lokasi pengiriman terpisah di bawah.

Jangan menulis pesan transkrip, menyuntikkan prompt sistem, memulai giliran pemilik, atau memancarkan sessions.changed semata-mata untuk persetujuan.

Konvergensi permukaan terkirim

Handler persetujuan native sudah mempertahankan entri pesan terkirimnya cukup lama untuk mengganti atau menonaktifkan kontrol aktif. Pesan persetujuan umum yang diteruskan saat ini membuang MessageReceipt, sehingga keputusan pada permukaan lain dapat membuat kontrol lamanya tampak masih tertunda. Tindak lanjut terpisah menutup celah tersebut dengan tabel anak operator_approval_deliveries dalam basis data status bersama.

Setiap baris menyimpan ID persetujuan, ID pengiriman unik, kanal/akun/rute persis, pencari lokasi pesan privat kanal yang dibatasi dan divalidasi JSON, stempel waktu pengiriman, serta status finalisasi. Baris tidak pernah menyimpan data callback, token keputusan, atau permintaan persetujuan mentah. Kanal memiliki pengodean pencari lokasi dan mutasi pesan; core memiliki status kanonis, pemilihan target, kebijakan percobaan ulang, dan teks terminal fallback.

Pendaftaran pengiriman dan penyelesaian terminal menangani kondisi balapan dengan aman:

1. Setelah pengiriman tertunda mengembalikan tanda terimanya, sisipkan pencari lokasi pengiriman dan baca status persetujuan induk dalam satu transaksi.
2. Jika induk sudah terminal, jadwalkan finalisasi segera alih-alih membiarkan pengiriman yang terlambat tetap tertunda.
3. Setiap transisi terminal yang di-commit secara terpisah menjadwalkan semua baris pengiriman yang belum difinalisasi; siaran yang dapat dibuang bukan pemicunya.
4. Terminalizer kanal melaporkan replaced, retired, atau unsupported. Penggantian mencegah pesan terminal duplikat; penonaktifan mengirim tindak lanjut terminal yang ada; kondisi tidak didukung atau kegagalan kembali ke fallback tanpa melakukan rollback CAS persetujuan.
5. Saat mulai, coba ulang persetujuan terminal dengan pengiriman yang belum selesai, sehingga pembersihan tahan terhadap mulai ulang Gateway.

Siklus hidup transportasi ini merupakan hook adaptor pengiriman opsional, bukan renderer atau tindakan pesan yang dihadapkan ke model. Pesan C2C/grup QQ saat ini tidak memiliki API edit, hapus, atau penghapusan keyboard; adaptor tersebut tetap tidak didukung dan hanya dapat menampilkan kebenaran kanonis setelah klik berikutnya hingga transportasi memperoleh API mutasi.

Semantik mulai ulang, batas waktu, dan rute

Persistensi SQLite tidak menyiratkan pelanjutan eksekusi. Pengikatan perintah/alat tetap berada dalam memori karena dapat berisi fakta runtime yang sensitif terhadap keamanan dan bukan kontrak pekerjaan yang dapat dilanjutkan.

Saat Gateway dimulai:

• buat epoch runtime baru;
• transisikan secara atomik baris tertunda dari epoch lama ke cancelled dengan alasan gateway-restart;
• pertahankan baris agar URL-nya menjelaskan apa yang terjadi;
• jangan pernah mengeksekusi persetujuan berikutnya terhadap pengikatan runtime yang hilang.

Timer merupakan pengoptimalan untuk membangunkan proses. Otoritas tenggat disimpan expires_at_ms; pembacaan, penantian, dan penyelesaian semuanya menjalankan rekonsiliasi kedaluwarsa.

Perilaku ketat final:

• batas waktu -> expired, tolak;
• tanpa rute -> denied, tolak;
• pembatalan proses -> cancelled, tolak;
• putusan tepercaya yang tidak valid -> denied, tolak;
• hanya keputusan izinkan eksplisit yang diizinkan -> allowed.

Perilaku exec yang dirilis saat ini masih bertentangan dengan kontrak ini:

• src/agents/bash-tools.exec-host-shared.ts dapat menerapkan askFallback.
• docs/tools/exec-approvals.md dan docs/cli/approvals.md mendokumentasikan permukaan tersebut.

Persetujuan plugin kini gagal secara tertutup pada batas waktu dan putusan yang tidak valid; bidang lama timeoutBehavior tetap diterima tetapi diabaikan. Tindak lanjut semantik ketat exec harus memperbarui kode, tipe, dokumentasi, pengujian, dan log perubahan secara bersamaan, dengan tinjauan pemilik/keamanan yang eksplisit. askFallback dapat terus menjelaskan pemilihan kebijakan pra-gerbang selama migrasi, tetapi tidak boleh mengubah batas waktu rekaman tertunda yang telah dibuat menjadi persetujuan.

Rencana kompatibilitas

• Protokol Gateway aditif; tidak ada peningkatan versi protokol.
• Pertahankan metode dan peristiwa exec/plugin yang ada pada batas eksternal.
• Pertahankan ID yang ada, termasuk prefiks plugin:, tetapi hentikan penggunaan prefiks sebagai informasi tipe.
• Pertahankan perilaku perintah teks /approve.
• Pertahankan bidang URL/Web App tombol lama dan tindakan perintah sebagai input kompatibilitas SDK plugin; output core baru bertipe.
• Migrasikan semua kanal bawaan dan pemanggil internal dalam perubahan tindakan bertipe yang sama.
• Tambahkan entri log perubahan untuk URL/halaman baru dan untuk perubahan perilaku batas waktu berikutnya.
• Jangan tambahkan pengaturan mode elisitasi.

Peluncuran

PR 1: siklus hidup persisten

• Catatan desain ini.
• Skema SQLite bersama, pembuatan Kysely, penyimpanan, dan pemangkasan 30 hari.
• Layanan persetujuan Gateway, jembatan waiter runtime, dan penanganan orphan saat mulai ulang.
• approval.get/resolve terpadu.
• Adaptor metode exec/plugin.
• Pengujian jawaban-pertama-menang, idempotensi, kedaluwarsa, otorisasi, dan konsumsi.
• Belum ada perubahan perilaku UI atau kanal.

PR 2: tindakan bertipe dan callback kanal

• Tindakan persetujuan, URL, dan Web App bertipe.
• Builder presentasi inti dan ekspor SDK plugin.
• Pengodean callback privat-transport dengan jenis pemilik eksplisit.
• Referensi callback berukuran tetap yang tahan lama untuk ID kanonis yang melampaui batas transport.
• Migrasi kanal bawaan agar tidak lagi menggunakan inferensi teks perintah dan ID persetujuan.
• Kebenaran jawaban pertama yang kanonis pada permukaan yang diklik dan pembaruan terminal native aktif dengan upaya terbaik; terminalisasi pesan kanal yang tahan lama tetap menjadi tindak lanjut.
• Pengujian SDK dan kanal bawaan.

PR 3: deep link Control UI

• Halaman persetujuan terautentikasi mandiri dan perutean startup yang memperhitungkan path dasar.
• Pengikatan Gateway penyaji tanpa mengubah pilihan jarak jauh tersimpan milik operator.
• Namespace HTTP persetujuan milik inti, termasuk ID yang menyerupai aset.
• Payload URL yang dibuat oleh Gateway dan polling status tertunda hingga event siklus hidup tersedia.
• Bukti untuk lebar perangkat seluler, koneksi ulang, jawaban yang bersaing, pemuatan ulang, dan path yang dipasang.

PR 4: klien native

• Permukaan peninjauan iOS dan Android menggunakan approval.get/resolve yang memperhitungkan jenis; watchOS meneruskan prompt dan keputusan yang aman bagi peninjau melalui iPhone yang dipasangkan.
• Watch menawarkan keputusan exec yang didukung oleh kontrak relay ringkasnya: izinkan sekali dan tolak.
• Kebenaran terminal jawaban pertama yang kanonis menggantikan status keputusan yang dicoba secara lokal.
• Pengakuan penyelesaian yang hilang atau ambigu membekukan kontrol hingga pembacaan balik kanonis.
• Instans Gateway v4 yang telah dirilis sebelumnya mempertahankan peninjauan exec melalui fallback metode lama yang terbatas; status terminal lintas permukaan yang dipertahankan memerlukan metode terpadu.
• Peringatan bagi peninjau dan konteks pemilik tetap terlihat di iPhone, Watch, dan Android.
• Bukti unit, build, dan platform native.

PR 5: propagasi siklus hidup leluhur

• Pengiriman tertunda/terminal session.approval dari snapshot audiens yang dipersistenkan di PR 1.
• Langganan sesi yang tepat, pemutaran ulang saat koneksi ulang, dan tombstone terminal tanpa mutasi transkrip atau membangunkan agen.
• Callback siklus hidup berjalan setelah insert/CAS yang tahan lama dan tidak pernah menjadi otoritas persetujuan.
• Bukti subagen bertingkat dan koneksi ulang.

PR 6: perilaku gagal-tertutup

• Migrasikan node-invoke-plugin-policy.ts dan broker plugin tertanam agar tidak lagi memiliki otoritas duplikat.
• Semantik ketat untuk batas waktu, data cacat, tanpa rute, pengikatan, dan konsumsi sekali-izinkan.
• Deprekasikan pengaturan batas waktu permisif yang telah dirilis tanpa mematuhinya setelah permintaan tertunda.
• Bukti persaingan multi-permukaan dan injeksi kegagalan.

Tindak lanjut: pembersihan pesan jarak jauh yang tahan lama

• Persistenkan pencari lokasi pengiriman yang diteruskan dan terminalisasi setiap pesan kanal yang telah dikirim setelah mulai ulang.
• Pisahkan siklus hidup transport ini dari otoritas persetujuan kanonis dan tindakan presentasi bertipe.

Pengujian

Cakupan terfokus yang diwajibkan:

• Pembukaan ulang SQLite mempertahankan proyeksi tertunda dan terminal.
• Dua penyelesai konkuren menghasilkan tepat satu pemenang CAS.
• Percobaan ulang dengan keputusan yang sama berhasil secara idempoten; percobaan ulang yang bertentangan mengembalikan pemenang yang tercatat.
• Penyelesaian pada atau setelah tenggat tidak dapat menyetujui.
• allow-once dapat dikonsumsi tepat sekali tanpa menghapus status audit terminal.
• Startup membatalkan epoch runtime yang lebih lama.
• Pencarian dan penyelesaian tanpa otorisasi tidak mengungkap keberadaan catatan.
• Daftar izin peninjau eksplisit dan perilaku umum operator.approvals yang dipasangkan.
• Metode lama exec dan plugin menggunakan penyimpanan yang sama.
• Skema permintaan/daftar/ambil/selesaikan Gateway dan payload event aditif.
• Normalisasi tindakan bertipe, rendering fallback, ekspor SDK, dan peralihan kanal bawaan.
• Pengodean callback Telegram memuat data privat-transport dan tidak mengandung inferensi string perintah.
• Anak langsung, pemilik pengontrol/peminta bercabang, pemilik bertingkat, penetapan ulang, fallback kolom sesi, siklus, dan batas ukuran audiens.
• Array audiens yang diminta dan terminal identik.
• Proyeksi pemilik tidak menyebabkan mutasi transkrip atau membangunkan agen.
• Rute Control UI berfungsi di / dan path dasar yang dikonfigurasi; penyegaran menampilkan kebenaran tertunda atau terminal.
• Jawaban Control UI dan Telegram secara simultan menampilkan satu pemenang dan "diselesaikan di tempat lain" pada pihak yang kalah.
• Pengidentifikasi persetujuan native dan pengidentifikasi pemilik Gateway mempertahankan byte UTF-8 yang persis sama selama perutean dan rekonsiliasi.
• Negosiasi keluarga RPC native menetapkan satu keluarga kanonis atau lama per rute Gateway yang diterima dan tidak pernah menurunkan versi secara diam-diam setelah digunakan.
• Pengakuan penyelesaian native yang hilang membekukan tindakan hingga pembacaan balik kanonis; pembacaan balik yang gagal tidak dapat mengarang pemenang atau mengakui penyegaran Watch.
• Korelasi permintaan snapshot Watch hanya diterima untuk pemilik Gateway pasangan yang tepat dan pembacaan balik iPhone kanonis yang telah selesai.
• Bukti jalur pengguna melalui Testbox/Crabbox, termasuk halaman persetujuan selebar perangkat seluler, pembersihan tindakan Telegram, dan satu perjalanan pulang-pergi tertunda/selesaikan/pihak-kalah-terlambat di Android, iPhone, dan Watch.

Observabilitas

Emisikan log transisi terstruktur tanpa konten dengan ID persetujuan, jenis, kunci sesi sumber, status, alasan, dan latensi. Jangan pernah mencatat pratinjau atau pengikatan mentah.

Lacak:

• jumlah permintaan berdasarkan jenis;
• jumlah terminal berdasarkan jenis/status/alasan;
• pengukur tertunda;
• latensi permintaan-ke-terminal;
• hasil persaingan penyelesaian: pemenang, percobaan ulang idempoten, konflik, kedaluwarsa;
• jumlah rute pengiriman dan penolakan tanpa rute;
• pembatalan yatim saat startup;
• ukuran audiens.

Transisi yang telah di-commit dianggap berhasil meskipun pengiriman event setelahnya gagal. Pelanggan siklus hidup memulihkan melalui pemutaran ulang PR 5 dan pencarian kanonis. Terminalisasi pesan kanal yang tahan lama tetap menjadi tindak lanjut terpisah di atas.

Keputusan terbuka

1. Origin Control UI yang dapat dijangkau secara eksternal. Setiap snapshot membawa urlPath relatif yang stabil. URL absolut hanya boleh dipublikasikan dari lokasi Tailscale Serve/Funnel yang di-cache setelah eksposur Gateway berhasil; allowedOrigins, header Host permintaan, gateway.remote.url, dan kandidat loopback/LAN khusus tampilan bukanlah origin kanonis. Telegram dapat menggunakan wrapper Mini App terautentikasinya untuk mempertahankan path persetujuan melalui bootstrap. Proxy balik arbitrer tetap hanya relatif hingga tersedia kontrak URL publik eksplisit yang ditinjau secara terpisah. Jangan pernah membiarkan kanal menebak origin.
2. Transisi kompatibilitas batas waktu ketat exec. Batas waktu persetujuan plugin kini gagal secara tertutup dan timeoutBehavior telah dideprekasi. Kontrak askFallback yang masih dirilis memerlukan peninjauan eksplisit oleh pemilik/keamanan, changelog, dokumentasi, serta keputusan migrasi/deprekasi sebelum berhenti mengotorisasi eksekusi setelah permintaan tertunda mencapai batas waktu.
3. Mode tertanam tanpa Gateway. Rekomendasi: pertahankan hanya lokal pada awalnya, lalu jadikan sebagai klien layanan kanonis ketika Gateway tersedia. Jangan publikasikan deep link yang tidak dapat diselesaikan oleh server mana pun.