DEV Community: BBT Indonesia

Cara membiarkan chat Claude mengusulkan perubahan kode GitNest yang kamu setujui di osFoundry

BBT — Sat, 07 Nov 2026 16:55:34 +0000

Di akhir panduan ini, percakapan Claude yang terhubung ke osFoundry bisa membaca repository GitNest, mencari di kodenya, dan menyiapkan perubahan: sebuah task, commit file, change set, retry check, atau pull request. Tidak ada yang terjadi saat Claude memintanya. Setiap aksi masuk sebagai usulan di "Needs your approval" (menunggu persetujuanmu) di osFoundry, lengkap dengan file, branch, dan commit persisnya di kartu, dan baru berjalan saat kamu klik Approve. Claude tidak punya tool yang menulis langsung ke repository.

Siapa mengerjakan apa

	Sisi Claude	Sisi osFoundry
Login	Akun Claude kamu, tidak berubah	Akun osFoundry kamu sudah menyetujui koneksi sekali
Yang bisa dilihat	Apa yang dikembalikan tool baca	Repository GitNest yang ditetapkan ke project tempat koneksi berada
Membaca kode	`search_gitnest_code`: potongan baris yang dibatasi	Tanpa file biner, tanpa isi file utuh, tanpa kredensial atau binding lokal
Mengubah kode	Tujuh tool `propose_gitnest_…`	Satu usulan per panggilan, menunggu kamu
Siapa yang menyetujui	Tidak ada di sisi Claude	Kamu, pemilik koneksi, selama masih punya peran di repository
Siapa yang menulis	Tidak ada	osFoundry menjalankan aksi yang disetujui, tercatat atas nama koneksi
Token provider	Tidak pernah dikirim	Akun GitHub/GitLab yang kamu tautkan hanya dipakai saat kamu menyetujui PR provider

Persiapan

1. Hubungkan chat sekali saja

Kalau chat Claude belum terhubung ke osFoundry, bagian ini adalah alur custom connector biasa: buat koneksi lewat ikon kunci → Connected, tambahkan alamat servernya di Claude sebagai custom connector, lalu setujui satu workspace. Anthropic menjelaskan sisi Claude di panduan custom connector miliknya. Sisa panduan ini mengasumsikan koneksi sudah menampilkan "Connected."

2. Masukkan repository ke sebuah project

Koneksi tidak pernah melihat repository GitNest dengan sendirinya. Repository harus termasuk dalam project tempat koneksi berada.

Buka repository di GitNest dan cari bagian Project. Teksnya berbunyi "Connected agents in this project can use approved GitNest read tools when their connection owner still has repository access." Hanya pemilik repository yang mendapat pemilih project; orang lain hanya melihat nama project sebagai teks biasa. Pilih project-nya. osFoundry mengonfirmasi dengan "Repository project updated."

3. Tambahkan koneksi ke project itu

Kembali ke ikon kunci → Connected, pilih koneksinya, dan di bawah Projects tambahkan ke project yang sama. Repository GitNest milik project itu ikut masuk, bersama Notes, knowledge base, dan konten tersinkron lainnya.

Buka Tools. "All supported tools are on by default", dan daftarnya menampilkan setiap tool dengan spasi sebagai pengganti garis bawah. Yang untuk GitNest adalah:

read gitnest repository        propose gitnest work
search gitnest code            propose gitnest change set
list gitnest work              propose gitnest server composition
read gitnest work              propose gitnest file import
list gitnest saved results     propose gitnest check rerun
list gitnest checks            propose gitnest native publication
                               propose gitnest provider publication

Contoh: Checklist Tools sebuah koneksi Claude, semuanya aktif secara default

Kalau kamu ingin Claude berhenti di commit dan tidak pernah menyiapkan pull request, hapus centang dua tool publication lalu klik Save tools. Bagaimanapun, usulan tetap butuh persetujuanmu. Menghapus centang hanya berarti Claude tidak bisa memintanya.

4. Minta lewat chat

Di percakapan Claude, aktifkan connector osFoundry dari menu + → Connectors lalu minta dengan bahasa biasa. Kalau kamu menambahkan server yang sama ke Claude Code dengan nama osfoundry, tool-nya muncul di sana sebagai mcp__osfoundry__propose_gitnest_file_import dan seterusnya.

Contoh jalannya

Nama tool dan nama argumen di bawah ini adalah yang didaftarkan server osFoundry di tools/list. Repository, prompt, ID, dan balasannya adalah konten contoh.

Contoh

Kamu: Di osFoundry, tambahkan CONTRIBUTING.md ke demo-api yang menjelaskan cara
      menjalankan test (pakai pytest di tests/), dan buka task prioritas rendah
      untuk menautkannya dari README.

Claude → list_granted_resources {}
       ← project "API" · repository GitNest "demo-api"
Claude → read_gitnest_repository {"repository_id": "…"}
       ← repository native, branch default main
Claude → search_gitnest_code {"repository_id": "…", "query": "pytest", "branch": "main"}
       ← pyproject.toml: [tool.pytest.ini_options] · tests/test_limits.py: import pytest
Claude → propose_gitnest_file_import {"repository_id": "…", "branch": "main",
           "message": "Add CONTRIBUTING.md with test instructions",
           "files": [{"path": "CONTRIBUTING.md", "content": "# Contributing\n…"}],
           "idempotency_key": "…"}
       ← usulan menunggu pemilik
Claude → propose_gitnest_work {"repository_id": "…",
           "title": "Link CONTRIBUTING.md from README", "priority": "low",
           "idempotency_key": "…"}
       ← usulan menunggu pemilik

Claude: Saya sudah menyiapkan dua usulan di osFoundry: satu commit yang menambahkan
        CONTRIBUTING.md ke main, dan satu task untuk menautkannya dari README.
        Belum ada yang di-commit. Keduanya menunggu persetujuanmu.

Di osFoundry, header menampilkan "Claude research proposes GitNest file changes", dan panel koneksi mencantumkan keduanya di bawah "Needs your approval". Kartu commit bertuliskan "Commit GitNest files in demo-api", lalu "Commit to branch: main", pesan commit, dan "Review all proposed files (1)" yang terlipat dan bisa dibuka untuk melihat CONTRIBUTING.md lengkap. Di bawahnya: "Expires …", Approve and create, Decline.

Contoh: Usulan publish GitNest di bawah Needs your approval

Prompt kedua, untuk change set yang sudah ada:

Contoh

Kamu: Change set rate-limit sudah hijau? Kalau integration gagal, ulangi,
      dan begitu lolos, siapkan sebagai pull request.

Claude → list_gitnest_work {"repository_id": "…", "kind": "changes"}
       ← "Rate-limit fix" · versi 3
Claude → list_gitnest_checks {"repository_id": "…", "change_set_id": "…"}
       ← commit tersusun 9c1e47a…: unit lolos · integration gagal (selesai)
Claude → propose_gitnest_check_rerun {"repository_id": "…", "change_set_id": "…",
           "check_name": "integration", "expected_change_set_version": 3,
           "expected_composition_oid": "9c1e47a…", "idempotency_key": "…"}
       ← usulan menunggu pemilik
  … kamu menyetujui retry, hasilnya lolos …
Claude → propose_gitnest_native_publication {"repository_id": "…", "change_set_id": "…",
           "expected_change_set_version": 3,
           "expected_composition_oid": "9c1e47a…", "idempotency_key": "…"}
       ← usulan menunggu pemilik

Perhatikan apa yang harus dikirim Claude. Retry dan publication sama-sama menyebut versi change set dan commit tersusun yang dilihat Claude. Kalau ada yang menyusun ulang change set sebelum kamu klik, versi atau commit yang akan kamu setujui sudah bukan yang ada di kartu, dan pengecekan ulang osFoundry saat persetujuan menolak menjalankannya.

Apa yang diminta setiap kartu untuk kamu setujui

Tool	Judul kartu	Tombol	Yang terjadi saat disetujui
`propose_gitnest_work`	Create GitNest work	Approve and create	Membuat Todo dan work item GitNest
`propose_gitnest_change_set`	Create GitNest draft change set	Approve and create	Membuat change set draft dari hasil run yang tersimpan. Tidak ada yang disusun atau dipublikasikan
`propose_gitnest_server_composition`	Compose GitNest change set	Approve and create	Menyusun change set di server setelah mengecek ulang versinya
`propose_gitnest_file_import`	Commit GitNest files	Approve and create	Meng-commit hingga 20 file UTF-8 (total 200 KB) ke branch yang tertera di kartu
`propose_gitnest_check_rerun`	Retry GitNest check	Approve retry	Memasukkan ulang satu check yang sudah selesai ke antrean untuk versi dan commit itu
`propose_gitnest_native_publication`	Publish GitNest pull request	Approve and publish	Membuat branch publication dan membuka pull request di repository native
`propose_gitnest_provider_publication`	Open a draft GitHub or GitLab pull request	Approve and publish	Push hanya branch change set tersebut dengan akun provider yang kamu tautkan dan membuka draft PR

Kartu yang merujuk ke change set memuat "Change set: … · expected version N", "Reviewed commit: …", dan tautan "Review change set before approving" yang membukanya di GitNest. Dua kartu publication masing-masing menambahkan satu baris tentang apa yang akan terjadi, misalnya "Approval creates a publication branch and opens a pull request in this native repository."

Di mana batasnya

Koneksi Claude tidak bisa menulis ke GitNest. Route tulis milik GitNest sendiri menolak akses dengan scope agen (denyAgentScope di route GitNest osFoundry), dan tool Connected tidak memanggilnya. Chat Claude hanya bisa mengajukan usulan, dan osFoundry sendiri yang menjalankan aksinya setelah kamu menyetujui, tercatat dengan koneksi sebagai sumbernya. Dengan begitu hanya ada satu jalur untuk setiap penulisan oleh agen, dan kamu bisa mengauditnya.

Persetujuan dicek ulang tepat saat kamu klik. osFoundry memeriksa lagi bahwa koneksi masih aktif, repository masih berada di project tempat koneksi bergabung, kamu masih memegang peran di repository, dan usulan belum kedaluwarsa. Untuk composition, retry, atau publication, osFoundry juga mengecek versi change set dan commit-nya, dan untuk publication juga kebijakan risiko repository, check wajib, dan branch tujuan. Usulan yang ditolak, kedaluwarsa, atau usang tidak akan berjalan. Setiap tool propose menerima idempotency_key, jadi panggilan yang diulang Claude setelah balasan terputus tidak dihitung sebagai permintaan kedua.

Tidak ada yang di-deploy di sini. Paling jauh, sebuah usulan sampai di pull request: PR native GitNest, atau draft PR di GitHub atau GitLab. Merge, dan apa pun yang dipicu merge, tetap di tanganmu di GitNest atau di provider.

Token provider Git kamu tidak pernah sampai ke Claude. PR provider memakai akun yang kamu tautkan di osFoundry, pada saat persetujuan, dan hanya push branch khusus milik change set itu, tidak pernah ref kamu yang lain.

Pembacaan sengaja dibatasi. search_gitnest_code mengembalikan potongan baris yang dibatasi, tidak pernah file biner atau file utuh. Pembacaan work, run, dan hasil tersimpan tidak menyertakan binding lokal dan kredensial. Untuk mengubah file yang sudah ada, tempel isi terbarunya ke chat supaya Claude bisa mengusulkan versi baru secara utuh. Menambah file baru bisa langsung dari potongan barisnya.

Selanjutnya

Coba penulisan terkecil dulu: minta Claude mengusulkan satu file baru saja, misalnya CONTRIBUTING.md, lalu buka kartunya dan bentangkan "Review all proposed files" sebelum kamu menyetujui. Cara GitNest sendiri menangani clone, push, dan access token ada di halaman fitur GitNest.

Kenapa osFoundry membuat Claude mengusulkan perubahan GitNest alih-alih langsung push?

BBT — Sat, 07 Nov 2026 16:46:32 +0000

Ini adalah tool yang dipakai chat Claude saat ingin memasukkan file ke repository GitNest lewat MCP connector osFoundry. Tool ini diambil dari tools/list publik milik endpoint live, di-fetch dengan curl pada 2026-11-06 (katalognya bisa dibaca tanpa token):

$ curl -s -X POST https://api.osfoundry.io/api/v1/external-mcp \
    -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

{"name": "propose_gitnest_file_import",
 "description": "Prepare up to 20 UTF-8 files (200 KB total) for a native GitNest repository branch. The owner reviews every file and approves the commit in osFoundry. Repository GitNest must be enabled.",
 "inputSchema": {"required": ["repository_id", "branch", "message", "files", "idempotency_key"],
   "properties": {
     "files": {"minItems": 1, "maxItems": 20,
               "items": {"properties": {"path": {"maxLength": 2048}, "content": {"maxLength": 100000}}}},
     "idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}}},
 "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

Perhatikan kata kerjanya. Tool ini "prepares", sedangkan owner yang "approves the commit". Call-nya sudah return sebelum ada apa pun yang menyentuh Git, dan tidak ada tool lain di connector ini yang menyentuh Git. idempotency_key wajib diisi, bukan opsional, dan punya panjang minimum, jadi client tidak bisa mengirim key kosong atau satu karakter lalu menyebutnya idempotent.

Sisa tulisan ini membahas kenapa bentuk seperti itu tepat untuk agent, dan apa yang harus dilakukan server supaya bentuk itu tetap jujur. Setelah itu, versi paling kecilnya dibangun ulang di atas repository Git sungguhan, lalu diukur apa yang rusak kalau beberapa bagiannya dihilangkan.

Apa yang dikunci oleh tujuh tool propose?

GitNest punya 13 tool di connector. Enam di antaranya hanya membaca: read_gitnest_repository, search_gitnest_code, list_gitnest_work, read_gitnest_work, list_gitnest_saved_results dan list_gitnest_checks. Tujuh sisanya diawali propose_. Field wajibnya menunjukkan apa yang dikunci masing-masing tool pada saat model memanggilnya:

Tool	`idempotency_key`	`expected_change_set_version`	`expected_composition_oid`	`openWorldHint`
`propose_gitnest_work`	wajib	tidak	tidak	false
`propose_gitnest_change_set`	wajib	tidak	tidak	false
`propose_gitnest_server_composition`	wajib	wajib	tidak	false
`propose_gitnest_file_import`	wajib	tidak	tidak	false
`propose_gitnest_check_rerun`	wajib	wajib	wajib	false
`propose_gitnest_native_publication`	wajib	wajib	wajib	true
`propose_gitnest_provider_publication`	wajib	wajib	wajib	true

Makin besar dampaknya, makin banyak yang dikunci. Sebuah task hanya mengunci key-nya. Composing mengunci versi change set yang dibaca model. Menjalankan ulang check atau memublikasikan pull request mengunci versi itu sekaligus commit hasil compose yang persis. Kedua tool publication ditandai openWorldHint: true, karena keduanya menghasilkan sesuatu di luar proposal store: sebuah pull request, dan untuk tool provider, sebuah branch yang di-push ke GitHub atau GitLab.

Di review card milik owner, kunci-kunci itu muncul sebagai teks: "Change set: … · expected version 3", "Reviewed commit: 9c1e47a…". Yang di-approve owner adalah versi dan commit itu, bukan apa pun yang kebetulan terbaru saat klik-nya sampai.

Kenapa tidak memberi agent token push saja?

Karena push diputuskan saat model mengeluarkannya, sedangkan proposal diputuskan saat seseorang dengan hak akses yang masih berlaku melihatnya.

Kode osFoundry menarik garis itu secara eksplisit. Route write GitNest dijaga oleh denyAgentScope, dan bridge Maestro di dalam aplikasi ke GitNest hanya mengizinkan read. Connected tools tidak mengakali itu dengan token browser pinjaman. Setiap proposal disimpan, ditampilkan ke owner koneksi, lalu dieksekusi oleh writer milik osFoundry sendiri setelah di-approve, dengan atribusi ke koneksi tersebut. Percakapan Claude tidak pernah memegang credential yang bisa menulis ke repository, dan tidak pernah melihat token GitHub atau GitLab milik owner. Publication ke provider hanya mem-push branch khusus milik change set, dengan lease absent-ref, dan tidak pernah me-mirror ref lain yang tidak terkait.

Harga dari pilihan itu adalah waktu. Jeda antara "proposed" dan "approved" adalah waktu manusia: beberapa menit, kadang sehari. Dalam jeda itu branch bergerak, seseorang meng-compose ulang change set, sebuah check selesai, owner kehilangan role di repository, koneksinya dicabut. Approval di osFoundry mengecek ulang koneksi, keanggotaan project, role repository owner saat ini, masa berlaku, dan untuk aksi change set juga versi dan commit yang persis, serta untuk publication juga risk policy dan check yang diwajibkan. "A declined, expired, or stale proposal must not execute" adalah satu baris di plan-nya.

Tinggal dua mode kegagalan, dan keduanya jadi bahan rebuild:

Dua approval terhadap base yang sama. Masing-masing terlihat baik-baik saja.
Retry setelah kegagalan parsial. Git sudah punya commit-nya, database belum tahu, lalu owner klik lagi.

Untuk yang kedua, plan osFoundry menjelaskan perbaikan yang sudah dirilis di Git service: file import mengirim proposal ID yang immutable sebagai idempotency key, dan service tersebut "updates the branch and replay marker atomically with compare-and-swap, so a database failure after the Git commit can be retried without another commit."

Rebuild-nya

Dua file, standard library ditambah git CLI (Apple Git 2.39.5), dijalankan di Mac Apple M1 yang sedang merender video untuk job lain juga:

server.py, 225 baris: endpoint JSON-RPC di atas bare Git repository dan sebuah file sqlite.
client.py, 203 baris: "Claude" yang di-script dan owner yang di-script.

Tidak ada binary Claude atau akun Claude yang terlibat. Client mengirim request tools/call yang sejenis dengan yang dikirim chat yang terhubung. Tool di rebuild ini adalah read_repo, propose_file_import dan read_proposal. Nama-nama itu buatan rebuild sendiri, dan tidak satu pun menulis ke Git. Owner memutuskan lewat route terpisah, /owner/decide, yang menjawab token agent dengan 403 agent_scope_denied. Itulah ide denyAgentScope dalam satu if.

Satu perbedaan yang disengaja: rebuild ini juga mengunci base commit pada file import (expected_base_oid, default-nya tip branch saat proposal dibuat). Schema propose_gitnest_file_import milik osFoundry tidak punya field seperti itu. Anggap bagian itu sebagai pilihan desain rebuild, bukan deskripsi osFoundry.

Intake proposal bersifat idempotent pada (connection, idempotency_key), dengan hash dari body, jadi key yang dipakai ulang dengan body berbeda menjadi error, bukan replay diam-diam:

c.execute("INSERT OR IGNORE INTO proposals (id,conn,idem_key,body_hash,branch,base_oid,files,"
          "message,status,created_at,expires_at) VALUES (?,?,?,?,?,?,?,?,'pending',?,?)", (...))
row = c.execute("SELECT * FROM proposals WHERE conn=? AND idem_key=?", (conn, key)).fetchone()
if row["body_hash"] != h:
    raise Conflict("idempotency_key_reused_with_different_body")

Approval membangun commit hanya dengan plumbing (read-tree ke index sementara, hash-object -w, update-index --cacheinfo, write-tree, commit-tree -p <base>). Tidak ada satu pun dari itu yang menggeser ref. Lalu satu transaksi menggeser branch hanya jika branch itu masih menunjuk ke base yang di-review, sekaligus membuat marker ref yang dinamai sesuai proposal:

tx = (f"start\nupdate refs/heads/{branch} {new} {base_oid}\n"
      f"create refs/proposals/{proposal_id} {new}\nprepare\ncommit\n")
git("update-ref", "--stdin", inp=tx)

update dengan old value adalah compare-and-swap. create gagal kalau ref-nya sudah ada. Git menerapkan keduanya atau tidak sama sekali. Sebelum membangun apa pun, approval mencari refs/proposals/<id>. Kalau ada, berarti percobaan sebelumnya sudah sampai ke Git, jadi approval mencatat commit itu dan mengembalikannya sebagai replay.

Apa yang dilihat Claude yang di-script

python3 client.py scenario, dengan UUID proposal dipersingkat. Baris expiry berasal dari server kedua yang dijalankan dengan TTL 0.3 s:

read_repo                          -> head 29a940e8  (1 commit)
propose A  README.md  key=readme-fix-0001 -> {"proposal_id": "96dcf05f-…", "status": "pending", "base_oid": "29a940e8"}
propose A  (retry, same key+body)  -> {"proposal_id": "96dcf05f-…", "status": "pending", "base_oid": "29a940e8", "replayed": true}
propose A' (same key, other body)  -> idempotency_key_reused_with_different_body
propose B  app.py     key=app-bump-0001   -> {"proposal_id": "c91824e3-…", "status": "pending", "base_oid": "29a940e8"}
decide A with the agent token      -> HTTP 403 {'error': 'agent_scope_denied'}
owner approves A                   -> HTTP 200 {"status": "executed", "commit": "f07b9fda"}  (2 commits)
owner approves B                   -> HTTP 200 {"status": "stale", "refused": true, "base_oid": "29a940e8", "branch_head": "f07b9fda"}  (2 commits)
propose B2 on new head f07b9fda    -> {"proposal_id": "bc3cedfc-…", "status": "pending", "base_oid": "f07b9fda"}
owner approves B2, crash before DB -> HTTP 500 {'error': 'injected: crash after git, before DB'}  (3 commits)
owner retries approval of B2       -> HTTP 200 {"status": "executed", "commit": "fb736eda", "replayed": true}  (3 commits)
owner clicks approve on A again    -> HTTP 200 {"status": "executed", "commit": "f07b9fda", "replayed": true}  (3 commits)
approve after decline              -> HTTP 200 {'status': 'declined', 'refused': True}  (3 commits)
approve after expiry (ttl 0.3 s)   -> HTTP 200 {'status': 'expired', 'refused': True}  (1 commit)

fb736ed Claude (conn-claude-research) | repo-owner | Bump app
f07b9fd Claude (conn-claude-research) | repo-owner | Pin install version
29a940e owner | owner | seed

B mengubah app.py dan A mengubah README.md, tapi B tetap ditolak. Itulah tafsiran ketat dari "owner me-review ini terhadap 29a940e8". Perbaikannya murah: client membaca head yang baru lalu mengusulkan lagi, dan itulah B2. Baris git log menunjukkan provenance yang ditulis store. Author-nya adalah koneksi, committer-nya adalah orang yang meng-approve, dan message-nya membawa trailer Proposal: <id> dan Approved-by:.

Apa yang rusak tanpa compare-and-swap?

--mode naive mempertahankan semuanya kecuali transaksi. Mode ini mengecek tip di Python, membangun commit, lalu menjalankan git update-ref refs/heads/main <new> tanpa old value dan tanpa marker. Server sama, client sama, layout repository sama.

Uji race: dua proposal berbeda di atas base yang sama, di-approve pada saat yang persis sama dari dua thread (threading.Barrier), 100 percobaan per run, dua run. Setelah setiap percobaan, client bertanya ke git merge-base --is-ancestor apakah setiap commit yang dilaporkan executed benar-benar ada di main.

Uji crash: approve dengan kegagalan yang disuntikkan setelah langkah Git dan sebelum update database, lalu approve lagi. 50 percobaan per run, dua run. Client menghitung commit di main sebelum dan sesudahnya.

Mode	Race: keduanya dilaporkan "executed"	Race: commit yang di-approve tidak ada di main	Crash, lalu retry
CAS + marker, run 1	0 / 100	0	50 × executed (replayed)
CAS + marker, run 2	0 / 100	0	50 × executed (replayed)
naive, run 1	100 / 100	100	50 × stale
naive, run 2	100 / 100	100	50 × stale

Race di mode naive gagal di setiap percobaan, bukan sesekali. Jendela antara "tip sama dengan base" dan "tulis ref" panjangnya empat proses git, puluhan milidetik, dan dua thread yang dilepas oleh barrier selalu sama-sama mendarat di dalamnya. Kedua approval mengembalikan executed beserta commit ID. Owner melihat dua hasil hijau, padahal salah satu dari dua commit itu tidak ada di history branch. Tidak ada error sama sekali. Dengan compare-and-swap, setiap percobaan berakhir dengan tepat satu proposal executed dan satu penolakan stale yang menyebutkan head baru.

Retry setelah crash di mode naive tidak menghasilkan commit ganda. Pengecekan base menangkapnya, karena branch sudah bergerak. Tapi tertangkapnya sebagai stale. Commit milik proposal itu sendiri ada di main, sementara store sekarang melaporkan proposal itu sebagai ditolak. Kalau pengecekan base dibuang supaya masalah itu hilang, retry akan menulis commit itu untuk kedua kalinya. Replay marker-lah yang membuat retry bisa bilang "ini sudah terjadi, ini commit-nya".

Berapa biayanya?

Waktu wall-clock per request dari client lewat HTTP loopback (urllib, koneksi baru setiap kali), n = 200 per operasi per run, dua run. Rentangnya dari run 1 ke run 2.

Operasi	CAS median	CAS p95	naive median	naive p95
propose (key baru)	4.42–4.44 ms	7.1–12.3 ms	4.08–4.66 ms	6.4–10.0 ms
propose (key sama, replay)	1.42–1.50 ms	3.3–4.5 ms	1.27–1.49 ms	2.4–4.1 ms
approve, dieksekusi	115–119 ms	199–257 ms	92–105 ms	130–193 ms
approve, ditolak sebagai stale	28–31 ms	52–70 ms	14–17 ms	24–34 ms
approve lagi, sudah dieksekusi	1.46–1.60 ms	3.4–4.7 ms	1.38–1.54 ms	2.6–4.2 ms

Hampir semuanya adalah spawn proses. Approval CAS yang dieksekusi menjalankan delapan proses git (lookup marker, lookup tip, read-tree, hash-object, update-index, write-tree, commit-tree, update-ref --stdin), yang naive enam. Penolakan stale berarti dua lookup dibanding satu. Dengan kira-kira 14 ms per proses git di mesin yang sedang sibuk ini, jalur aman ini menambah sekitar dua spawn, sekitar 15–25 ms, pada request yang toh menunggu klik manusia. Server yang me-link libgit2 alih-alih memanggil shell akan memangkas semua kolom ini. Selisih di antara keduanya akan tetap dua lookup itu.

Replay adalah jalur termurah di kedua tabel, cukup satu read sqlite. Client yang melakukan retry justru lebih murah bagi server dibanding request baru.

Kalau kamu mau merakitnya sendiri

Jangan beri agent tool write apa pun untuk repository, hanya propose_*, dan cek di route decide bahwa pemanggilnya bukan token agent. Jangan mengandalkan agent tidak menemukan route itu.
Kunci apa yang dilihat reviewer, versi dan commit, di dalam proposal, lalu bandingkan saat approval. Tolak dengan menyertakan head terbaru di response, supaya client bisa membaca ulang dan mengusulkan lagi.
Jadikan write ke Git sebagai satu transaksi ref: update branch dengan old value, ditambah marker create-only yang dinamai sesuai proposal. Cari marker itu sebelum membangun apa pun.
Wajibkan idempotency key dengan panjang minimum, simpan bersama hash dari body, dan tolak key yang dipakai ulang dengan body berbeda.
Tulis provenance ke dalam commit itu sendiri. Author-nya koneksi, committer-nya orang yang meng-approve, dan sebuah trailer membawa proposal ID. git log akan tetap menyimpannya meskipun database kamu sudah hilang.
Berhenti di pull request. Merge dan deploy adalah urusan pemilik repository, di layarnya sendiri.

Sisi GitNest dari semua ini, yaitu clone, push, dan access token, dijelaskan di halaman GitNest osFoundry. Connector-nya berbicara MCP biasa, jadi tool proposal yang sama juga bisa dipakai dari Claude Code atau host MCP lainnya.

Menjalankan Claude Code sebagai worker osFoundry dengan langganan Claude sendiri

BBT — Sat, 07 Nov 2026 16:29:04 +0000

Setelah setup ini selesai, role Worker di osFoundry dipegang oleh Claude Code. Saat sebuah langkah dalam plan sampai ke Worker, aplikasi desktop menjalankan claude di folder proyek kamu, dengan login langganan Claude milikmu sendiri. Claude Code mengedit file dengan tool-nya sendiri dan memanggil tool osFoundry, misalnya pencarian di catatan kamu, sebagai mcp__osfoundry__memory_search. Setiap panggilan itu muncul di chat osFoundry sebagai baris "Using …".

Siapa mengerjakan apa

	Claude Code	Aplikasi desktop osFoundry
Login	Langganan Claude kamu, disimpan oleh CLI setelah `/login`	Tidak pernah melihatnya. Menghapus `ANTHROPIC_API_KEY` dan variabel sejenis dari environment proses anak supaya run tidak beralih ke tagihan API
Biaya	Diambil dari langganan kamu	Mencatat run dengan biaya 0
File	Read, Edit, dan Bash miliknya sendiri, di dalam satu folder (`--add-dir`)	Memilih folder itu: yang paling baru di Local Folders
Tool osFoundry	Memanggilnya sebagai `mcp__osfoundry__<tool>`	Menyajikannya di port loopback khusus untuk run ini, dan mencocokkan setiap panggilan dengan allowlist
Persetujuan	Berjalan dengan `--permission-mode bypassPermissions` di foldernya	Setiap panggilan lewat bridge melewati gerbang persetujuan dan policy yang sama dengan panggilan tool dari model lain
Output	Teks akhir	Menjadi output role. Aktivitas tool ditampilkan sebagai baris progres

Setup

1. Instal Claude Code dan login sekali

Instal CLI sesuai dokumentasi Anthropic. Lalu login dari terminal:

$ claude
> /login

osFoundry mencari binary-nya di PATH, di ~/.claude/local, dan di dalam bundle ekstensi VS Code (~/.vscode/extensions/anthropic.claude-code-*/resources/native-binary/claude). Jadi Claude Code yang hanya terpasang lewat ekstensi VS Code juga tetap ketemu.

2. Aktifkan di External AI

Di aplikasi desktop, klik ikon kunci di header (API Keys (BYOK)), lalu buka tab External AI (AI eksternal). Baris Claude Code seharusnya terlihat seperti ini:

Claude Code   Installed                                  [Enabled]
/Users/you/.claude/local/claude
Model id: cli:claude (chat) · cli:claude:agent (autonomous)
[Verify sign-in]  [Sign in]

Contoh: Claude Code dan Codex di tab External AI

Klik Verify sign-in (cek login). Aplikasi menjalankan completion kecil lewat CLI dan menampilkan ✓ Signed in atau Needs sign-in. Sign in membuka Claude Code di jendela terminal dengan petunjuk "Type /login to sign in, then close this window."

Mungkin kamu melihat badge API key in env. Artinya ada variabel seperti ANTHROPIC_API_KEY yang terpasang di environment tempat osFoundry dijalankan. Aplikasi menghapusnya sebelum menjalankan claude, jadi run tetap memakai langganan kamu. Badge itu hanya pemberitahuan.

3. Berikan folder

Agent mode bekerja di direktori sungguhan. Tambahkan proyek kamu di Settings → Local Folders. Kalau ada beberapa, yang terakhir ditambahkan yang dipakai. Run yang dimulai dari surface Code memakai repository yang didaftarkan untuk run itu.

4. Pasang ke role

Buka tab Pipeline → Pipeline Roles. Di bagian Agents, pilih Worker lalu pilih cli:claude:agent dari grup External AI (subscription).

Kedua id itu adalah dua mode yang berbeda:

cli:claude:agent bersifat otonom. Claude Code punya tool-nya sendiri di folder kamu, ditambah tool osFoundry lewat bridge. Pakai untuk Worker, Researcher, Document Agent, dan role sejenis.
cli:claude adalah mode chat. CLI berjalan dengan --disallowedTools '*' dan tidak bisa memanggil apa pun. Cocok untuk role yang hanya teks seperti Titling atau Compaction. Kalau role yang butuh tool dipasang ke id ini, run gagal dengan pesan yang menyuruh kamu memakai cli:claude:agent.

Agent yang kamu buat di layar Agents juga bisa memakainya. Pemilih modelnya mencantumkannya di bawah CLI agents, dengan label "autonomous — runs in your local folder".

5. Apa yang sebenarnya dijalankan aplikasi

Untuk setiap run, osFoundry menyalakan MCP bridge baru, lalu menjalankan CLI kurang lebih seperti ini. Flag-nya diambil dari build_claude_command di src-tauri/src/providers/agent_cli.rs:

claude -p "<conversation>" \
  --output-format stream-json --verbose --include-partial-messages \
  --permission-mode bypassPermissions \
  --add-dir /Users/you/work/site \
  --mcp-config '{"mcpServers":{"osfoundry":{"type":"http",
      "url":"http://127.0.0.1:<port>/mcp",
      "headers":{"Authorization":"Bearer <per-run token>"},
      "timeout":120000}}}' \
  --strict-mcp-config \
  --append-system-prompt "<role prompt>"

--strict-mcp-config menjaga server MCP global atau proyek milikmu sendiri tetap di luar run ini. Hanya server osfoundry yang terpasang. Port dan token selalu baru di setiap run, dan listener ditutup begitu prosesnya selesai.

Contoh run sungguhan

Contoh. Catatan dan repository-nya adalah konten demo.

Kamu (chat Maestro, Worker = cli:claude:agent)
  Cari di catatanku kapan review anggaran Q4, lalu tambahkan ke TODO.md.

Panggilan tool Claude Code
  mcp__osfoundry__memory_search  {"query": "review anggaran Q4"}
    → "Review anggaran Q4: Kam 14:00."
  Read   TODO.md
  Edit   TODO.md   (+ "- [ ] Siapkan angka untuk review anggaran Q4 (Kam 14:00)")

Baris progres osFoundry
  Using memory_search — {"query":"review anggaran Q4"}
  Using Read — {"file_path":"TODO.md"}
  Using Edit — {"file_path":"TODO.md", …}

Jawaban
  "Siapkan angka untuk review anggaran Q4 (Kam 14:00)" sudah ditambahkan ke TODO.md.
  Waktunya diambil dari catatan kamu "Review anggaran Q4: Kam 14:00."

Prefiks mcp__osfoundry__ adalah cara Claude Code menamai tool dari server bernama osfoundry. osFoundry membuangnya di baris progres, jadi memory_search terbaca sama seperti saat memakai model API.

Di mana batasnya

Bridge menawarkan daftar yang pendek dan tetap. Isinya tool read-only seperti memory_search, web_search, extract_content, code_search, todo_list, transcribe dan tool baca cloud_*, ditambah orkestrasi (spawn_fleet, graph_run, loop_run), layar live, dan tool Canvas. read_file, write_file, dan execute_command sengaja tidak dimasukkan. Claude Code sudah punya versi tool itu yang terbatas pada foldernya, dan executor kedua tanpa batas lewat MCP bisa menjangkau di luar --add-dir.

Allowlist ditegakkan oleh bridge, bukan oleh flag CLI. Run dalam mode bypassPermissions tidak menghormati --allowedTools, jadi osFoundry tidak mengirimkannya. Panggilan ke tool apa pun di luar daftar run mendapat error JSON-RPC: "tool '…' is not available to this agent".

Workspace dan channel dikunci saat bridge dimulai. Panggilan tool tidak bisa mengalihkan dirinya ke workspace lain lewat argumennya.

Penulisan ke layar atau ke editor Canvas (ui_agent_act, tool tulis Canvas) selalu meminta izin kamu dulu, sama seperti dengan model API. Run yang tidak sedang diawasi siapa pun, misalnya agent yang menjawab mention di channel, menolak tool yang butuh persetujuan alih-alih menunggu klik yang tidak akan datang.

File kamu tidak pernah melewati osFoundry. Claude Code membaca dan mengeditnya langsung, dan trafiknya menuju Anthropic dengan login kamu sendiri, sama seperti di terminal.

Langkah berikutnya adalah memasang cli:claude:agent juga ke role Researcher, di samping Worker, lalu menjalankan satu task yang diorkestrasi. Halaman Pipeline roles mencantumkan semua role yang bisa kamu serahkan kepadanya, dan Local Folders menjelaskan cara folder kerja dipilih.

Cara osFoundry menemukan sesi Claude Code dan Codex kamu di disk, dibuat ulang dengan Python

BBT — Sat, 07 Nov 2026 15:43:01 +0000

~/.claude/projects/-Users-alex-code-shop-api/c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58.jsonl
~/.claude/projects/-Users-alex-code-shop-api/c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58/subagents/agent-<id>.jsonl
~/.codex/state_5.sqlite                      -> table threads (id, rollout_path, cwd, git_branch, title, …)
~/.codex/sessions/2026/11/04/rollout-2026-11-04T10-00-00-<thread id>.jsonl

$ claude --resume c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58
$ codex resume 019a2f1c-7d0e-7b31-9c4e-5a1f0e2d8b63

Hanya itu kontrak antara CLI dan sebuah session picker. Claude Code dan Codex masing-masing menyimpan sesinya sebagai file biasa di folder home kamu, dan masing-masing menerima sebuah id untuk melanjutkan satu sesi. Layar External agents di aplikasi desktop osFoundry adalah pembaca yang berjalan di atas file-file itu (Rust, runtime/session_inventory.rs dan runtime/external_sessions.rs). Layar ini menampilkan sesi dari dua belas aplikasi, mencocokkan pencarian dengan judul, folder, branch, aplikasi, dan id, lalu menjalankan perintah resume yang tepat di terminal.

Di bawah ini bagian Claude Code dan Codex dari fitur itu, dibuat ulang sebagai skrip Python 150 baris dan dijalankan pada folder sesi asli di Mac tempat tulisan ini dibuat. Tidak ada isi transkrip yang ditampilkan di mana pun dalam tulisan ini. Setiap angka adalah jumlah, ukuran, atau waktu.

Seperti apa satu sesi Claude Code di disk?

Satu file JSONL per sesi, dinamai dengan id sesi, di dalam folder yang dinamai sesuai direktori kerja. Nama foldernya adalah path absolut dengan setiap karakter yang bukan huruf atau angka diganti -:

re.sub(r"[^A-Za-z0-9]", "-", cwd)   # /Users/alex/code/shop-api -> -Users-alex-code-shop-api

Dicek terhadap 40 transkrip di mesin ini: 40 dari 40 folder sesuai aturan itu. Aturannya lossy (my.app dan my-app bentrok, begitu juga / dan .), jadi jangan pernah men-decode nama folder. Baca cwd dari record-nya.

Sub-agent (Explore dan kawan-kawan dari tool Task) menulis transkripnya sendiri di <session id>/subagents/agent-<id>.jsonl. Di sini ada 129. Itu bukan sesi yang akan di-resume orang, dan osFoundry melewati setiap file yang stem-nya diawali agent-.

Setiap baris adalah satu record dengan sebuah type. Menghitung type di 400 baris pertama dari masing-masing 40 file:

type	record	key yang penting untuk index
assistant	4,060	`requestedModel`, `effort`, `gitBranch`, `message.model`
attachment	3,197	`cwd`, `gitBranch`
user	2,469	`cwd`, `gitBranch`, `permissionMode`, `isSidechain`, `message.content`, `entrypoint`
custom-title	922	`customTitle`
agent-name	827	`agentName`
system, mode, queue-operation, file-history-, api-request, …	2,000+	tidak diperlukan

Record percakapan (user, assistant, attachment, system) semuanya membawa sessionId, cwd, gitBranch, timestamp, dan version. message.content bisa berupa string atau list of blocks; di baris-baris itu tipe block-nya adalah tool_result 2,261, tool_use 2,223, thinking 1,224, dan text 754. Judul berasal dari record custom-title atau, pada build yang menulisnya, record ai-title dengan aiTitle. Di sini semua file punya custom-title dan tidak ada yang punya ai-title, jadi baca keduanya.

Kenapa tidak parse semua file saja?

Karena ukurannya besar. Ke-40 transkrip level atas di sini totalnya 19.4 GB. Median file-nya 168 MB, yang terbesar 2.07 GB, dan persentil ke-90 1.94 GB.

Men-stream file median lewat json.loads baris per baris butuh 0.61 s (11,558 baris, sekitar 279 MB/s di Mac Apple Silicon, dengan page cache yang sudah hangat). Dengan kecepatan itu, parse penuh untuk semua 40 file akan makan sekitar 70 s, bahkan sebelum ada yang ditampilkan.

Data yang dibutuhkan sebuah daftar ada di kedua ujung file. Diukur pada semua 40 file:

record pertama yang punya cwd paling lambat ada di baris 2 (median 2)
gitBranch pertama dan record user pertama: paling lambat baris 2
record judul ada di dalam 512 KiB terakhir pada 40 dari 40 file
tidak ada baris di 80 baris pertama yang lebih dari 256 KiB

Jadi index membaca 80 baris pertama dan 512 KiB terakhir. Itu juga yang dilakukan osFoundry: HEAD_LINES = 80 dengan batas 256 KiB per baris di session_inventory.rs, dan SETTINGS_TAIL = 512 * 1024 di external_sessions.rs, yang dibaca untuk model, effort, mode approval, dan branch terbaru. Membaca head dan tail dari semua 40 file butuh 86 ms.

HEAD_LINES, LINE_CAP, TAIL_BYTES = 80, 256 * 1024, 512 * 1024


def head(p, n=HEAD_LINES):
    out = []
    with open(p, "rb") as f:
        for _ in range(n):
            line = f.readline(LINE_CAP + 1)
            if not line:
                break
            if len(line) > LINE_CAP:          # a pasted file or image: skip the rest of it
                while line and not line.endswith(b"\n"):
                    line = f.readline(1 << 20)
                continue
            out.append(line)
    return out


def tail(p, nbytes=TAIL_BYTES):
    with open(p, "rb") as f:
        f.seek(0, 2)
        size = f.tell()
        f.seek(max(0, size - nbytes))
        lines = f.read().split(b"\n")
    return lines[1:] if size > nbytes else lines   # first piece is a cut line

readline yang dibatasi itu penting. Satu giliran user yang berisi gambar yang di-paste adalah satu baris berukuran beberapa megabyte, dan for line in f biasa akan menarik semuanya ke memori hanya untuk dibuang.

Field apa saja yang benar-benar dibutuhkan picker?

Lima, ditambah waktu: aplikasi, id, folder, branch, judul. Head memberikan cwd, gitBranch pertama, dan judul cadangan dari pesan user asli yang pertama (bukan sidechain, dan bukan yang diawali <, karena begitulah wrapper command dan hook dimulai). Tail menimpanya dengan judul dan branch terbaru, karena sesi yang panjang sering bertahan lebih lama dari branch tempat ia dimulai.

def claude_sessions():
    for proj in sorted((CLAUDE / "projects").glob("*/")):
        for p in proj.glob("*.jsonl"):
            if p.stem.startswith("agent-"):           # sub-agent transcript, not resumable
                continue
            st = p.stat()
            cwd = branch = title = None
            for v in records(head(p)):
                cwd = cwd or v.get("cwd")
                branch = branch or (v.get("gitBranch") or None)
                if title is None and v.get("type") == "user" and not v.get("isSidechain"):
                    t = (first_text((v.get("message") or {}).get("content")) or "").strip()
                    if t and not t.startswith("<"):
                        title = t[:80]
                if cwd and branch and title:
                    break
            for v in records(tail(p)):                 # newest wins: titles, branch moves
                for k in ("customTitle", "aiTitle"):
                    if v.get(k):
                        title = v[k][:100]
                branch = v.get("gitBranch") or branch
            yield {"app": "claude-code", "id": p.stem, "cwd": cwd, "branch": branch,
                   "title": title, "mtime": int(st.st_mtime * 1000), "bytes": st.st_size}

records() adalah json.loads per baris dengan baris rusak dilewati (baris pertama dari pembacaan tail terpotong di tengah). first_text() mengembalikan isi yang berupa string, atau block text pertama. Waktu terakhir dipakai diambil dari mtime file, yang juga dipakai osFoundry untuk pengurutan.

Di mana Codex menyimpan data yang sama?

Codex menulis satu rollout per sesi di bawah pohon folder berdasarkan tanggal, ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<thread id>.jsonl, dan menyimpan yang diarsipkan di ~/.codex/archived_sessions/. Di sini: 10 rollout (28.5 MB) dan 2 yang diarsipkan. Baris pertama setiap rollout adalah record session_meta yang payload-nya berisi id, cwd, originator, source, cli_version, model_provider, timestamp dan, di beberapa build, git.branch. Sisanya adalah record event_msg, response_item (dengan tipe payload message, function_call, function_call_output, reasoning, custom_tool_call, …), turn_context, dan compacted.

Codex juga menyimpan index, jadi kamu sama sekali tidak perlu membuka rollout. ~/.codex/state_<n>.sqlite punya tabel threads; di sini file-nya state_5.sqlite dengan 43 kolom dan 12 baris, termasuk id, rollout_path, cwd, git_branch, title, model, reasoning_effort, approval_mode, sandbox_policy, source, archived, dan updated_at_ms. Bisa ada lebih dari satu file state_<n>; codex_state_db di osFoundry mengambil n tertinggi, dan skripnya juga begitu. Baris yang source-nya berupa objek JSON adalah thread sub-agent; lewati saja.

def codex_sessions():
    db = codex_db()
    if db:
        con = sqlite3.connect(f"file:{db}?mode=ro&immutable=1", uri=True)
        q = ("SELECT id, cwd, git_branch, title, COALESCE(updated_at_ms, updated_at*1000), source "
             "FROM threads ORDER BY 5 DESC LIMIT 300")
        for id_, cwd, br, title, ms, source in con.execute(q):
            if (source or "").startswith("{"):        # sub-agent thread
                continue
            yield {"app": "codex", "id": id_, "cwd": cwd, "branch": br,
                   "title": (title or "")[:100] or None, "mtime": ms or 0, "bytes": None}
        return
    for p in (CODEX / "sessions").glob("*/*/*/rollout-*.jsonl"):
        v = next(records(head(p, 1)), {})
        if v.get("type") != "session_meta":
            continue
        pl = v.get("payload", {})
        yield {"app": "codex", "id": pl.get("id"), "cwd": pl.get("cwd"),
               "branch": (pl.get("git") or {}).get("branch"), "title": None,
               "mtime": int(p.stat().st_mtime * 1000), "bytes": p.stat().st_size}

Satu hal yang butuh percobaan kedua: membuka database hanya dengan ?mode=ro gagal di sini dengan unable to open database file. Menambahkan immutable=1 berhasil. Immutable memberi tahu SQLite bahwa file tidak akan berubah selama dibuka, jadi SQLite melewati lock dan file -shm; itu aman untuk index berupa snapshot, dan artinya kamu bisa membaca database yang sedang dibuka oleh aplikasinya. osFoundry membuka index Codex dengan SQLITE_OPEN_READ_ONLY, dan memakai open dengan immutable=1 untuk database yang mungkin sedang dibuka aplikasi lain untuk menulis.

Seberapa cepat di folder sungguhan?

$ python3 sessidx.py build          # four runs, same Mac, real ~/.claude and ~/.codex
52 sessions  claude 154 ms  codex 3 ms
52 sessions  claude 80 ms  codex 2 ms
52 sessions  claude 83 ms  codex 2 ms
52 sessions  claude 107 ms  codex 4 ms

52 sesi (40 Claude Code, 12 Codex), semuanya punya folder dan judul, dan ke-40 sesi Claude Code punya branch. Run pertama adalah yang paling dingin; sisanya sudah hangat. File index-nya 11,480 byte. Dibandingkan parse penuh 70 s, 80 sampai 150 ms adalah beda antara daftar yang langsung terbuka dan daftar yang menampilkan spinner.

Pencarian lalu cukup berupa tes substring pada lima field, sama dengan yang dipakai matchesQuery milik osFoundry di lib/external-sessions.ts:

def matches(r, q):
    q = q.strip().lower()
    return not q or any(q in str(v).lower() for v in (r["title"], r["cwd"], r["branch"], r["app"], r["id"]) if v)

Pada home palsu yang dibuat dengan struktur yang sama (data contoh, bukan sesi asli):

$ SESSIDX_HOME=./fx python3 sessidx.py find checkout
codex       019a2f1c  test/checkout-e2e    -
claude-code c5e1a7b2  fix/checkout-retry   Fix double charge on checkout retry
$ SESSIDX_HOME=./fx python3 sessidx.py resume c5e1
cd /Users/alex/code/shop-api && claude --resume c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58

Mencari di dalam teks pesan berarti membaca 19.4 GB itu, atau membangun full-text index dari semua yang pernah kamu paste ke agent. Mencari berdasarkan folder dan branch menemukan sesi lewat nama proyek, dan memang itu yang biasanya kamu ingat.

Apa yang ditambahkan oleh resume yang aman?

Mencetak claude --resume <id> itu bagian yang gampang. Yang ditambahkan osFoundry di sekitarnya (plan_command dan launch plan di external_sessions.rs, plus pengecekan yang dilakukan layar sebelum membuka terminal) layak ditiru:

Jalankan di folder yang tercatat, dan tolak kalau folder itu sudah tidak ada, alih-alih melanjutkan di tempat lain.
Bandingkan branch yang tercatat dengan git -C <cwd> rev-parse --abbrev-ref HEAD. Kalau berbeda, beri tahu dan tanyakan; jangan pernah checkout.
Bawa model (--model, di Codex -m) dan effort (--effort, di Codex -c model_reasoning_effort="…").
Bawa mode approval yang tercatat hanya kalau setidaknya seketat default CLI. Untuk Claude Code itu default atau plan; untuk Codex, approval untrusted atau on-request, sandbox read-only atau workspace-write. Yang lebih longgar ditahan, kecuali orangnya memilih untuk mengaktifkannya pada peluncuran itu saja.

sessidx.py lengkapnya terdiri dari tiga bagian di atas plus sekitar 30 baris kode perekat (override env untuk folder home, output JSON, subcommand find dan resume). Tidak ada binary claude atau codex di Mac yang dipakai di sini, jadi baris resume-nya dicetak, bukan dijalankan.

Kalau kamu mau membuatnya sendiri

Perlakukan file-file itu sebagai API: hanya baca, jangan pernah menulis di sebelahnya, dan jangan pernah membuka file auth milik CLI untuk mengambil nama akun.
Baca head dan tail, bukan seluruh transkrip. Batasi panjang baris supaya satu gambar yang di-paste tidak memakan memori sebesar ukurannya.
Ambil cwd dari record, bukan dari nama folder yang di-escape.
Utamakan state_<n>.sqlite milik Codex (n tertinggi) daripada menelusuri pohon tanggal, dan buka dalam mode immutable kalau aplikasinya mungkin sedang memegangnya.
Jangan masukkan transkrip sub-agent (agent-*.jsonl, thread dengan source JSON) ke daftar; tidak ada yang me-resume-nya secara langsung.
Tentukan di awal apa saja yang boleh diubah oleh resume. Default yang aman: folder ya, model ya, approval yang lebih longgar hanya kalau diminta, branch tidak pernah.

Tampilan Sessions untuk agent milik osFoundry sendiri bekerja dari sumber yang berbeda; penjelasannya ada di halaman sesi agent osFoundry.

Cara membiarkan chat Claude mengedit Notes osFoundry tanpa menimpa editan rekan kerja

BBT — Sat, 07 Nov 2026 15:21:00 +0000

Di akhir panduan ini, percakapan Claude membaca rentang sel dari tab Sheet di salah satu Notes osFoundry Anda, menulis ulang tab teks di Note yang sama, dan menambahkan tab Slides baru, sementara seseorang terus mengetik di Note itu. Setiap penulisan menyebutkan ID tab yang tepat dan versi Note yang terakhir dibaca Claude. Jika orang tersebut menyimpan sesuatu di sela-selanya, osFoundry menolak penulisan Claude, dan Claude membaca ulang sebelum mencoba lagi. Tidak ada editan siapa pun yang hilang.

Siapa mengerjakan apa

	Sisi Claude	Sisi osFoundry
Login	Akun Claude Anda, tidak berubah	Koneksi yang Anda setujui untuk satu workspace
Note mana	Claude memilihnya dari daftar yang diberikan server	Hanya Notes di project yang sudah ditambahi koneksi tersebut
Tab mana	Claude harus mengirim `tab_id` yang tepat	`list_note_tabs` mengembalikan setiap instance tab, termasuk dua Sheet dengan tipe yang sama
Konflik	Claude membaca ulang dan mengulang perubahannya	Penulisan membawa `expected_version`; versi usang ditolak, bukan digabung
Percobaan ulang	Claude boleh mengirim ulang panggilan yang sama	`idempotency_key` yang sama mengembalikan hasil pertama alih-alih menulis dua kali
Persetujuan	Prompt izin tool milik Claude sendiri sebelum setiap penulisan	Hak edit Anda saat ini pada Note itu, dicek di setiap panggilan

Persiapan

Konektornya sama dengan yang dari pengaturan custom connector Claude (ikon kunci → Connected → Add assistant, lalu tambahkan https://api.osfoundry.io/api/v1/external-mcp di Claude). Langkah-langkah di bawah mengasumsikan koneksi itu sudah ada dan sudah ditambahkan ke sebuah project.

1. Masukkan Note ke project yang terhubung

Buka Note, buka panel kanannya, lalu masuk ke Config → Settings. Kolom Project menampilkan "Add to project" (tambahkan ke project) kalau Note belum punya project. Pilih project tempat koneksi Claude berada.

Note yang hanya ada di perangkat ini tidak punya salinan di cloud, jadi koneksi tidak bisa melihatnya. Note harus sudah tersinkron ke workspace Anda.

2. Pastikan tool Note aktif

Di ikon kunci → Connected, pilih koneksi Claude lalu lihat Tools. Semua tool yang didukung aktif secara default. Untuk panduan ini, tool berikut harus tetap dicentang:

read   list_note_tabs   read_note_tab   read_sheet_range   list_note_attachments
write  edit_note_tab    create_note_tab add_note_source

Contoh: Daftar centang Tools pada koneksi Claude, semuanya aktif secara default

Untuk membuat chat hanya-baca sementara waktu, hapus centang tiga tool write lalu klik Save tools. Membaca tetap berfungsi.

3. Cek sebentar hak edit Anda

Penulisan Claude berjalan dengan hak orang yang menyetujui koneksi, dan dicek ulang di setiap panggilan. Jika Anda hanya bisa melihat Note, edit_note_tab ditolak meskipun tool-nya aktif. Buka tab Access di Note kalau ragu.

4. Minta dengan menyebut nama tab

Di chat Claude yang konektor osFoundry-nya aktif, sebutkan nama Note dan tab-nya. Claude sendiri yang mengubah nama menjadi ID tab, tetapi "sheet Owners" lebih tidak ambigu daripada "tabelnya".

Di osFoundry, buka Note "Q3 launch". Baca A1:D12 di sheet Owners,
tulis ulang tab Brief supaya setiap item terbuka punya penanggung jawab dari sheet itu,
lalu tambahkan tab Slides "Launch status" dengan satu slide per penanggung jawab.

Contoh eksekusi nyata

Isi Note dan jawaban Claude adalah data contoh. Nama tool dan nama argumen sama persis dengan yang didaftarkan server produksi di tools/list. Di Claude Code, tool yang sama muncul sebagai mcp__osfoundry__list_note_tabs dan seterusnya.

Contoh

Claude → list_note_tabs {"note_id": "…"}
       ← version "…41.118Z"
         tab: Brief (note), Owners (sheet), Owners archive (sheet)
Claude → read_sheet_range {"note_id": "…", "tab_id": "<Owners>",
                           "start_row": 0, "start_col": 0,
                           "row_count": 12, "col_count": 4}
       ← 12 × 4 nilai
Claude → read_note_tab {"note_id": "…", "tab_id": "<Brief>"}
       ← teks, version "…41.118Z"
Claude → edit_note_tab {"note_id": "…", "tab_id": "<Brief>",
                        "operation": "replace_text", "text": "…",
                        "expected_version": "…41.118Z",
                        "idempotency_key": "brief-owners-1"}
       [Claude meminta Anda mengizinkan panggilan tool ini → Allow]
       ← ditolak: Note berubah setelah versi itu

         (sementara itu, Mika menambahkan "press kit" ke tab Brief di osFoundry)

Claude → read_note_tab {"note_id": "…", "tab_id": "<Brief>"}
       ← teks kini memuat "press kit", version "…07.502Z"
Claude → edit_note_tab {... "text": "… press kit — owner: Mika …",
                        "expected_version": "…07.502Z",
                        "idempotency_key": "brief-owners-2"}
       ← tersimpan, version "…19.044Z"
Claude → create_note_tab {"note_id": "…", "tab_type": "slides",
                          "label": "Launch status",
                          "slides": [{"title": "Aiko"}, {"title": "Mika"}, …],
                          "expected_version": "…19.044Z",
                          "idempotency_key": "launch-status-deck"}
       ← ID tab baru "<Launch status>"

Claude: Brief sekarang mencantumkan penanggung jawab untuk semua 9 item terbuka,
        termasuk "press kit", yang ditambahkan Mika saat saya mengedit. Tab
        Launch status yang baru punya satu slide per penanggung jawab.

Ada tiga hal yang terjadi yang tidak terlihat di chat biasa. Claude membaca rentang Sheet, bukan seluruh workbook. read_sheet_range mengembalikan paling banyak 100 kali 100 sel, jadi Sheet yang besar tidak membanjiri percakapan. Editan pertama memang sengaja gagal: versi Claude lebih lama daripada simpanan Mika. Claude tidak mengirim ulang teks lamanya dengan versi baru. Claude membaca ulang tab itu dan menulis Brief yang berisi perubahannya sekaligus baris dari Mika. Panggilan create membawa key-nya sendiri, jadi kalau balasannya hilang dan Claude memanggil lagi, osFoundry akan mengembalikan tab Launch status yang sama alih-alih membuat tab kedua.

Tab Owners archive adalah alasan ID tab itu penting. Satu Note bisa berisi beberapa tab Sheet atau Slides, dan nama atau tipe saja tidak menunjuk satu tab tertentu. Setiap panggilan edit_note_tab membutuhkan ID yang dikembalikan oleh list_note_tabs.

Di mana batasnya

Penulisan usang ditolak, tidak pernah digabung. osFoundry tidak mencoba menggabungkan teks Claude dengan teks orang tersebut di server, karena replace_text yang berisi teks lengkap tidak punya cara yang andal untuk tahu versi paragraf mana yang Anda maksud. Yang tahu maksudnya adalah agen, jadi agenlah yang mengulang perubahan di atas isi yang ada sekarang. Simpanan orang itu sendiri dari aplikasi desktop juga dijaga dengan cara yang sama. Sebuah simpanan membawa revisi tempat ia mulai, dan jika Note berubah di bawahnya, aplikasi menyimpan editan orang itu sebagai draf lokal dan menandai konflik sinkronisasi alih-alih menimpa perubahan Claude.

Versi itu milik Note. Anda mengambilnya dari list_note_tabs sebelum membuat tab dan dari read_note_tab sebelum mengedit tab. Ketika orang tersebut mengedit tab mana pun di Note, penulisan Claude berikutnya harus membaca ulang, meskipun menyasar tab lain. Pembacaan tambahan itu murah, dan memastikan Claude tidak pernah menulis berdasarkan gambaran Note yang sudah usang.

Membuat tab hanya menambah. create_note_tab membuat tab Slides dan Sheet, dan tidak bisa mengganti isi tab yang sudah ada. Setiap operasi edit cocok untuk satu jenis tab: replace_text untuk tab Note dan Markdown, slide_add dan slides_add_outline untuk Slides, sheet_set_range untuk sel Sheet yang tepat, replace_tab_data untuk tab konten lain yang didukung.

File tetap berupa metadata. list_note_attachments menampilkan Files dan Sources dari sebuah Note, tetapi tidak mengembalikan isi file maupun link unduhan. Link yang ditempel di chat bisa diteruskan ke mana saja, dan tetap berfungsi setelah koneksi dicabut. Claude bisa menambahkan sitasi dengan add_note_source, yang menerima URL HTTP atau HTTPS, versi Note, dan sebuah key, sama seperti penulisan lainnya.

Memindahkan Note memutus akses di panggilan berikutnya. Pindahkan ke project yang tidak ada di koneksi, hapus project dari koneksi, atau klik Revoke connection, dan pembacaan Claude berikutnya ditolak. Token yang diterbitkan sebelumnya tidak membuat akses tetap terbuka.

Selanjutnya

Minta Claude mengubah rentang Owners menjadi briefing lima slide di tab Slides baru, lalu edit sendiri satu judul slide saat Claude bekerja. Anda akan melihat penulisan yang ditolak dan pembacaan ulangnya di panggilan tool. Bagaimana tab Slides berdampingan dengan bagian lain dari Note ada di halaman Note Slides.

Cara menghubungkan chat Claude ke proyek osFoundry kamu dengan custom connector

BBT — Sat, 07 Nov 2026 13:47:56 +0000

Setelah mengikuti langkah-langkah ini, percakapan Claude biasa di claude.ai bisa membuka Notes, knowledge base, dan Records di salah satu proyek osFoundry kamu, menjawab berdasarkan isinya, dan memposting di channel diskusi proyek itu. Dengan persetujuanmu, chat itu juga bisa mengeditnya. Kamu tetap login ke Claude seperti biasa. Di setiap panggilan tool, osFoundry yang memutuskan apa saja yang boleh disentuh chat itu, dan setiap panggilan tercatat di osFoundry pada Recent activity milik koneksi tersebut. ChatGPT terhubung dengan cara yang sama, memakai alamat server yang sama.

Siapa mengerjakan apa

	Sisi Claude	Sisi osFoundry
Login	Akun Claude kamu, tidak berubah	Akun osFoundry kamu menyetujui koneksi sekali, untuk satu workspace
Yang menjalankan model	Claude, di chat yang sudah kamu pakai	Tidak ada. Di jalur ini tidak ada model dan tidak ada provider key
Tempat tool dijalankan	Claude mengirim panggilan tool	`api.osfoundry.io` menjalankannya dan mengecek akses lebih dulu
Yang bisa dijangkau	Apa pun yang dikembalikan server	Proyek yang kamu tambahkan koneksinya, plus channel tempat kamu mengundangnya
Persetujuan	Prompt izin tool milik Claude sendiri	Perubahan GitNest dan Room menunggu di "Needs your approval"
Tempat data tinggal	Jawaban ada di chat Claude kamu	Notes, record, dan artikel tetap di osFoundry. Item yang hanya lokal tidak pernah keluar dari perangkat

Setup

1. Buat koneksi di osFoundry

Di osFoundry, klik ikon kunci di header dan buka tab Connected. Panelnya berjudul "Connected agents" dan menampilkan workspace yang sedang kamu buka. Di bawah "Connect in three steps":

Assistant: pilih Claude
Display name: nama apa saja yang nanti mudah kamu kenali, misalnya Claude research
Klik Add assistant (tambah asisten)

Koneksi baru menampilkan "Setup pending. This assistant cannot read or change anything yet." Salin Server address dengan tombol Copy di sebelahnya:

https://api.osfoundry.io/api/v1/external-mcp

Contoh: Tab Connected setelah Add assistant, dengan alamat server dan koneksi yang masih pending

2. Tambahkan ke Claude sebagai custom connector

Di Claude, buka Customize → Connectors lalu tambahkan custom connector dengan URL tersebut. Di paket Team atau Enterprise, owner organisasi menambahkannya lebih dulu di Organization settings → Connectors, lalu setiap anggota menghubungkan sendiri. Langkah-langkah dari Anthropic untuk remote MCP connector ada di panduan custom connector Claude.

Saat kamu klik Connect, Claude menemukan halaman login osFoundry dengan sendirinya. Kamu tidak perlu menempelkan client ID atau key.

3. Setujui satu workspace

Browser kamu akan membuka https://osfoundry.io/external-assistant-authorize, halaman berjudul "Connect an agent". Halaman ini menampilkan client asisten dan host tujuan kembalinya, lalu meminta:

Workspace to connect: satu workspace. Workspace kedua butuh koneksi sendiri.
Requested capabilities, dalam bahasa sederhana: "Read supported resources in projects you add", "Change supported resources where you have edit access", "Run sessions where you grant a runner role".
Connection: pilih "Use pending: Claude research" supaya tersambung ke koneksi dari langkah 1, atau biarkan "Create a new connection".
Centang "I approve connecting this assistant to ", lalu Connect.

Kamu akan dikembalikan ke Claude. Koneksinya sudah aktif tapi belum bisa melihat apa pun. Koneksi baru dimulai dengan nol proyek.

4. Tambahkan ke proyek

Kembali ke ikon kunci → Connected, pilih koneksinya. Sekarang tertulis "Connected." Di Projects, pilih proyek lalu klik Add to project.

Contoh: Koneksi yang sudah ditambahkan ke proyek, dengan chat yang tertaut di bawahnya

Ini memberi akses ke konten tersinkron yang didukung di proyek itu: Notes, knowledge base, channel Record, Room cloud, repositori GitNest yang ditugaskan ke proyek, dan channel diskusi proyek. Konten yang kamu tambahkan ke proyek nanti juga ikut. Channel Message biasa terpisah. Gunakan Message channels → Choose a Message channel → Invite untuk setiap channel yang perlu dibaca dan dibalas oleh chat.

Bagian Tools menulis "All supported tools are on by default." Hapus centang tool yang tidak ingin kamu berikan ke koneksi ini lalu klik Save tools.

Contoh: Checklist Tools pada koneksi Claude, semuanya aktif secara default

5. Aktifkan di chat

Di percakapan Claude, buka menu + → Connectors lalu aktifkan connector osFoundry. Setelah itu, minta saja dengan bahasa biasa.

Contoh jalannya

Prompt dan jawaban di bawah adalah konten contoh dari proyek demo. Nama tool dan nama argumennya persis seperti yang diumumkan server live di tools/list. Di claude.ai, panggilan-panggilan ini muncul di bawah nama connector. Kalau kamu menambahkan URL yang sama ke Claude Code dengan nama osfoundry, tool yang sama muncul sebagai mcp__osfoundry__list_project_resources dan seterusnya.

Contoh

Kamu: Pakai osFoundry, apa saja yang masih terbuka di checklist peluncuran Q3?
      Cek KB support kalau ada yang bertentangan, lalu tandai
      record "pricing page" sebagai Ready.

Claude → list_granted_resources {}
       ← 1 proyek terhubung: "Launch Q3" (workspace)
Claude → list_project_resources {"project_id": "…", "resource_type": "note", "search": "checklist"}
       ← Note "Q3 launch checklist"
Claude → list_note_tabs {"note_id": "…"}
       ← tab: Note (teks), Sheet "Owners"
Claude → read_note_tab {"note_id": "…", "tab_id": "…"}
       ← 9 item, 3 belum dicentang
Claude → search_knowledge_base {"knowledge_base_id": "…", "query": "refund window"}
       ← artikel "Refund policy" (diperbarui 2 hari lalu)
Claude → read_record_item {"record_channel_id": "…", "item_id": "…"}
       ← "pricing page", status Draft, version …
Claude → edit_record_item {"record_channel_id": "…", "item_id": "…",
                           "values": {"status": "Ready"},
                           "expected_version": "…", "idempotency_key": "…"}
       [Claude meminta izinmu untuk panggilan tool ini → Allow]
       ← tersimpan, version baru …

Claude: Ada tiga item yang masih terbuka: tanggal embargo pers,
        terjemahan FAQ, dan baris refund di pricing page.
        Checklist menyebut 14 hari; artikel KB "Refund policy"
        menyebut 30. Record pricing page sudah saya tandai Ready.

Dua detail di transkrip itu memang disengaja. edit_record_item butuh version yang dikembalikan read_record_item, jadi record yang berubah di antara keduanya akan ditolak, bukan ditimpa. idempotency_key yang diulang mengembalikan hasil pertama, jadi panggilan yang di-retry tidak menulis dua kali.

Di mana batasnya

osFoundry tidak bisa membuka chat Claude kamu. Koneksi MCP membuat Claude bisa memanggil tool osFoundry saat Claude memutuskan perlu. osFoundry tidak punya API ke arah sebaliknya untuk menampilkan daftar, membaca, atau memulai percakapan pribadi. Tool yang menautkan chat ke proyek (link_current_chat) menerima label yang dilaporkan chat itu tentang dirinya sendiri, dan osFoundry memperlakukannya sebagai petunjuk routing, bukan identitas yang terverifikasi. Karena alasan yang sama, Claude tidak menerima notifikasi latar belakang dari osFoundry. Claude baru bertindak ketika kamu membuka percakapan dan meminta.

Data yang hanya lokal tetap lokal. Server sendiri menyatakannya di balasan initialize: "Local-only data is unavailable to cloud clients." Room lokal, sesi Graph lokal, dan konten yang tidak pernah tersinkron tidak terlihat oleh koneksi. Berbagi sesi Graph desktop adalah switch terpisah di tab yang sama, dan aplikasi desktop harus terbuka dan dalam keadaan login.

Akses dicek di setiap panggilan, bukan di setiap login. Setiap panggilan dicocokkan dengan status koneksi, workspace-nya, keanggotaan proyek saat ini, proyek tempat item itu berada saat itu, dan peranmu sendiri pada item tersebut. Pindahkan Note ke proyek lain, keluarkan proyeknya, atau klik Revoke connection, dan panggilan berikutnya akan ditolak. Edit juga mensyaratkan kamu, orang yang menyetujui koneksi, masih punya hak edit.

Sebagian penulisan berubah menjadi usulan. Pekerjaan GitNest, change set, impor file, pull request, dan instalasi aplikasi di Room melewati tool propose_…. Semuanya menunggu di tab Connected pada "Needs your approval", tempat kamu melihat repositori atau Room tujuan dan file-filenya sebelum memilih Approve atau Decline. Claude tidak pernah menerima token Git provider kamu atau nilai rahasia apa pun.

Channel Message perlu undangan. Menjadi bagian dari proyek hanya membuka channel diskusi proyek itu. Channel lain butuh Invite secara eksplisit, dan channel privat harus diundang oleh owner-nya.

Selanjutnya

Tambahkan knowledge base ke proyek yang sama, lalu ajukan ke Claude pertanyaan yang biasanya kamu jawab dari sana, misalnya "Apa kata KB kita soal refund, sertakan nama artikelnya?". search_knowledge_base mengembalikan ID artikel dan kapan terakhir diperbarui, jadi kamu bisa mengecek sumbernya. Cara knowledge base di osFoundry disusun ada di halaman knowledge base.

Bagaimana custom connector Claude menemukan server OAuth osFoundry, dan kenapa akses dicek di setiap panggilan?

BBT — Fri, 06 Nov 2026 10:45:59 +0000

Ini yang diterima client MCP remote saat memanggil tool osFoundry tanpa token. Request-nya dikirim dengan curl dari sebuah Mac di Tokyo pada 2026-11-06:

$ curl -s -D - -X POST https://api.osfoundry.io/api/v1/external-mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
         "params":{"name":"list_project_resources","arguments":{}}}'

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"

{"jsonrpc":"2.0","id":3,"result":{"isError":true,
  "content":[{"type":"text","text":"Authentication required"}],
  "_meta":{"mcp/www_authenticate":["Bearer resource_metadata=\"https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp\", ..."]}}}

Satu header itu sudah cukup bagi custom connector Claude, atau koneksi MCP di developer mode ChatGPT, untuk menemukan halaman login. Pengguna cukup menempelkan URL-nya. Semua yang ada di bawah berasal dari request tanpa autentikasi ke endpoint live, ditambah rebuild kecil dalam Python yang dijalankan secara lokal untuk mengukur bagian yang tidak bisa diperlihatkan curl: apa yang terjadi pada akses setelah login.

Apa yang dilihat client sebelum punya token?

Tiga panggilan, tiga jawaban berbeda:

Request	Status	Yang dikembalikan
`initialize`	200	protokol `2025-06-18`, server `osfoundry 0.1.0`, plus instruksi
`tools/list`	200	59 tool, 45,368 byte
`tools/call`	401	`WWW-Authenticate` yang menunjuk ke resource metadata
`GET` ke endpoint	405	tidak ada stream SSE lewat GET

Handshake dan katalog tool bersifat publik. Hanya pemanggilan tool yang butuh token. Dengan begitu host bisa menunjukkan ke pengguna tool apa saja yang ada sebelum siapa pun login. Tidak ada data pengguna di katalog, dan string instructions di initialize bersifat umum:

Use list_granted_resources first. Every Note edit must use the exact tab ID.
Local-only data is unavailable to cloud clients.

Setiap tool di tools/list mendeklarasikan scope OAuth yang dibutuhkannya dan apakah tool itu hanya membaca:

{"name": "edit_record_item",
 "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

Dari 59 tool: 30 butuh osfoundry:read dan ditandai readOnlyHint: true, 26 butuh osfoundry:write, dan 3 butuh osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Host bisa memakai readOnlyHint untuk menentukan panggilan mana yang perlu prompt persetujuan.

Ke mana 401 itu mengarahkannya?

resource_metadata mengikuti RFC 9728 (OAuth Protected Resource Metadata). Suffix well-known diletakkan tepat setelah host, lalu path resource ditambahkan di belakangnya. Suffix itu tidak ditempel di ujung URL resource:

GET /.well-known/oauth-protected-resource/api/v1/external-mcp   200
GET /.well-known/oauth-protected-resource                       200 (same document)
GET /api/v1/external-mcp/.well-known/oauth-protected-resource   404

{"resource": "https://api.osfoundry.io/api/v1/external-mcp",
 "authorization_servers": ["https://api.osfoundry.io"],
 "scopes_supported": ["osfoundry:read", "osfoundry:write", "osfoundry:run", "osfoundry:models"]}

Kalau kamu membuat client sendiri, 404 itu adalah kesalahan pertama yang akan kamu buat. Ambil URL dari header, jangan menyusunnya sendiri.

Apa kata authorization server tentang dirinya?

/.well-known/oauth-authorization-server (RFC 8414):

{"issuer": "https://api.osfoundry.io",
 "authorization_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/authorize",
 "token_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/token",
 "registration_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/register",
 "grant_types_supported": ["authorization_code", "refresh_token"],
 "token_endpoint_auth_methods_supported": ["none"],
 "code_challenge_methods_supported": ["S256"],
 "authorization_response_iss_parameter_supported": true}

Baca ini sebagai rangkaian keputusan. Ada registration_endpoint, jadi host bisa mendaftarkan dirinya sendiri (dynamic client registration) dan pengguna tidak pernah berurusan dengan client ID. Autentikasi token-nya none, jadi host adalah public client tanpa client secret, dan PKCE dengan S256 yang mengikat code ke client yang memintanya. iss di authorization response mencegah salah tukar saat sebuah host berbicara dengan beberapa authorization server.

Langkah authorize mengarahkan browser ke halaman consent osFoundry, https://osfoundry.io/external-assistant-authorize. Di sana pengguna memilih tepat satu workspace dan mencentang "I approve connecting this assistant to …" (saya menyetujui asisten ini dihubungkan ke …). Persetujuan itu hanya menyebut satu workspace, tidak lebih. Koneksi baru belum punya project. Owner menambahkannya belakangan di aplikasi (key icon → Connected → Add to project).

Kenapa scope saja tidak cukup?

Scope ditetapkan saat token diterbitkan. osfoundry:write menyatakan bahwa koneksi boleh melakukan aksi tulis. Scope itu tidak menyebut Note yang mana, dan tidak bisa tahu bahwa Note tersebut dipindahkan ke project lain sepuluh menit lalu. Catatan desain osFoundry mendaftar apa saja yang dibaca ulang di setiap panggilan: status koneksi, workspace, keanggotaan project, project dan ACL resource saat ini, keanggotaan channel atau role di session, tool-nya, dan scope OAuth. Orang yang menyetujui koneksi juga harus masih punya hak edit atas item tersebut. Penghapusan atau pemindahan "langsung berlaku".

Alternatifnya adalah memasukkan daftar project ke dalam token, atau ke cache yang di-key oleh token, lalu memercayainya sampai kedaluwarsa. Itu lebih murah untuk ditulis. Rebuild di bawah mengimplementasikan keduanya supaya perbedaan perilakunya bisa diukur.

Rebuild-nya

Tidak ada binary Claude yang terlibat. client.py berperan sebagai host dan server.py sebagai server MCP. Keduanya hanya memakai standard library, sekitar 280 baris jika digabung, dan dijalankan di Python 3.9.6 pada Apple M1. Server-nya mengimplementasikan initialize, tools/list, dan tools/call lewat JSON-RPC di atas HTTP biasa, dua dokumen well-known, /authorize (halaman consent otomatis disetujui untuk satu workspace), dan /token dengan PKCE S256. Beberapa route /admin/* menggantikan klik owner di tab Connected.

Pengecekan yang berjalan sebelum setiap tool:

def access(token_info, tool, note_id):
    if TOOL_SCOPE[tool] not in token_info["scopes"]:
        return "insufficient_scope"
    if CHECK == "token_only":                     # design B: trust issue-time state
        ok = note_id is None or NOTES[note_id]["project"] in token_info["projects_at_issue"]
        return None if ok else "not_in_project"
    conn = CONNECTIONS.get(token_info["connection"])
    if not conn or conn["status"] != "active":
        return "connection_revoked"
    if note_id is None:
        return None
    note = NOTES.get(note_id)
    if not note or note["workspace"] != conn["workspace"]:
        return "not_found"
    if (token_info["connection"], note["project"]) not in PROJECT_MEMBERS:
        return "not_in_project"
    return None

Client mulai tanpa token. Ia memanggil sebuah tool, menerima 401, mem-parse resource_metadata dari WWW-Authenticate, mengambil kedua dokumen metadata, menjalankan authorize dan token dengan PKCE verifier baru, lalu menjalankan skenarionya:

$ CHECK=per_call python3 server.py &  python3 client.py 8767
discovery: first call -> 401, metadata /.well-known/oauth-protected-resource/mcp, 5 round trips, 11.3 ms
1 fresh connection, no project yet           200 OK   []
2 after owner adds project A                 200 OK   ["note-a1"]
3 read note in A                             200 OK   "Q3 launch checklist"
4 read note in B (never added)               200 DENY not_in_project
5 write with a read-only token               403 DENY insufficient_scope
6 write with read+write token                200 OK   "saved"
7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 DENY not_in_project
9 same read after revoke                     200 DENY connection_revoked

Client yang sama terhadap CHECK=token_only. Di sini token membawa daftar project dari refresh terakhirnya:

7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 OK   "Q3 launch checklist v2"
9 same read after revoke                     200 OK   "Q3 launch checklist v2"

Langkah 1–7 identik. Langkah 7 tetap ditolak di desain token-only karena project milik note dicek secara live. Desain token-only hanya jadi basi untuk fakta yang disimpan di dalam token. Langkah 8 dan 9 adalah yang penting bagi owner: mereka sudah menghapus project, lalu mencabut koneksi, tapi chat tetap bisa membaca. Di desain token-only, kondisi itu bertahan sampai token kedaluwarsa, yaitu expires_in: 3600 di rebuild ini.

Penolakan terbagi di dua lapisan. Scope yang kurang adalah kegagalan di level protokol: 403 dengan error="insufficient_scope" dan scope yang dibutuhkan di WWW-Authenticate, sehingga host bisa meminta lebih. Semua yang berkaitan dengan item mana yang terlibat adalah hasil tool biasa dengan isError: true. Otorisasi ulang tidak akan memperbaikinya, jadi tidak ada gunanya menyuruh host mencoba lagi.

Berapa biaya pengecekan di setiap panggilan?

Diukur dengan time.perf_counter_ns() di sekitar access() di dalam server, 1,000 panggilan per run (500 diizinkan, 500 ditolak), di Mac yang juga sedang menjalankan job lain:

	median access()	p99 access()	median tool call loopback
cek per panggilan, 6 run	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
token-only, 3 run	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 run)

Di memori, pengecekan ulang tenggelam di noise panggilan HTTP loopback. Server sungguhan melakukan query database, bukan sekadar cek keanggotaan set, jadi biayanya lebih tinggi. Rebuild ini tidak bisa mengukurnya, jadi tidak ada angka yang diberikan. Sebagai gambaran, perjalanan jaringan ke endpoint live dari Tokyo sekitar 500 ms sampai 800 ms per request dengan urllib dan koneksi TLS baru setiap kali (masing-masing n=10: median initialize 790 ms, tools/list 816 ms, tools/call yang 401 565 ms, tiap dokumen metadata sekitar 520–530 ms). Waktu sebuah connector tidak habis di pengecekan akses.

Discovery-nya sendiri butuh 5 round trip HTTP secara lokal: 401, resource metadata, server metadata, authorize, token. Itu memakan 7.5–13.4 ms dalam tujuh run dan 34 ms sekali saat Mac sedang sibuk. Terhadap server live, tiga leg GET/POST yang bisa dilakukan tanpa kredensial totalnya kira-kira 1.6 s dari cold start. Leg authorize toh menunggu manusia.

Kenapa Claude bisa memanggil osFoundry, tapi osFoundry tidak bisa membuka chat Claude kamu?

Di setup ini, host-lah yang memanggil. Host membuka koneksi, mengambil daftar tool, dan memutuskan kapan memanggil salah satunya. Server menjawab. Tidak ada apa pun di setup ini yang memberi server akses ke percakapan milik host. Rencana osFoundry menuliskannya di tabel kapabilitasnya: membuka atau mendaftar chat pribadi ChatGPT/Claude sembarang adalah "No", dengan keterangan "No general host API is provided for this".

Hal itu membentuk tool-nya. Dengan link_current_chat, chat itu sendiri yang membuat link dari dalam chat. Label-nya dilaporkan sendiri oleh chat, dan osFoundry memakainya untuk routing, bukan sebagai identitas. Pekerjaan yang ditugaskan ke chat Claude yang ter-link menunggu sampai pengguna membuka chat itu dan memintanya untuk mengecek. ChatGPT punya MCP Events untuk chat yang berlangganan, dan rencana osFoundry memperlakukannya sebagai fitur khusus host tersebut.

Sisi server memegang semua keputusan soal data, karena hanya sisi itu yang tahu kondisi terkini sebuah project. Sisi host memegang semua keputusan soal kapan bertindak dan apakah perlu bertanya ke pengguna. Pengecekan per panggilan inilah yang membuat server tetap benar ketika kedua sisi itu tidak lagi sinkron.

Kalau kamu memasangnya sendiri

Taruh resource_metadata di WWW-Authenticate milik respons 401 dan sajikan RFC 9728 di /.well-known/oauth-protected-resource/<resource path>. Client yang menyusun URL sendiri bisa salah. Header itu menyelamatkan setiap client dari kesalahan tersebut.
Tentukan apa yang publik sebelum login. osFoundry membuka initialize dan tools/list dan menjaga tools/call. Kalau deskripsi tool kamu membocorkan sesuatu tentang tenant, jaga juga tools/list.
Deklarasikan scope dan readOnlyHint per tool. Host bisa membangun prompt persetujuan dari situ, dan 403 insufficient_scope memberi host sesuatu yang konkret untuk diminta ulang.
Buat token tetap kecil: siapa, koneksi mana, scope apa. Baca ulang workspace, keanggotaan project, project milik resource, dan role terkini orang yang menyetujui di setiap panggilan, supaya pencabutan dan "pindah ke project lain" langsung berlaku di panggilan berikutnya.
Kembalikan penolakan resource sebagai hasil tool, bukan sebagai 401/403. Token yang berbeda tidak akan memperbaiki "Note ini ada di project B".
Buat operasi tulis membawa expected_version dan idempotency key. Host melakukan retry, dan model mengulang panggilan.

Sisi MCP dari spesifikasinya ada di halaman otorisasi MCP. Definisi singkat versi osFoundry ada di entri glosariumnya tentang MCP.