跳到正文
DEV Community· BBT·· 10 天前AI 評分49

Claude Code 在 osFoundry Room 提交應用程式提案時,實際會傳送甚麼?

osFoundry Room में ऐप प्रपोज़ करते समय Claude Code असल में क्या भेजता है

AI 導讀

Claude Code 在 osFoundry 的雲端 Room 提交小型應用程式時,呼叫的是提案工具,而非直接建立 Room 應用程式。工具會傳送 Room ID、名稱、檔案及冪等鍵;伺服器另行檢查入口檔案和安全相對路徑。提案工具需要寫入權限,並標示為具破壞性,因此 Claude Code 會先徵求同意;Room 擁有人審閲並批准完整程式碼後,應用程式才會出現在啟動器。

正文

यह वह tool है जिसे Claude Code osFoundry के किसी क्लाउड Room में छोटा-सा ऐप डालने के लिए कॉल करता है, ठीक वैसे जैसे लाइव सर्वर इसे tools/list में दिखाता है (बिना token के fetch किया गया, सिर्फ़ काम के हिस्से रखे गए हैं):

{
  "name": "propose_room_snippet_app",
  "description": "Prepare a Room snippet with source files. It appears in the cloud Room launcher only after its owner reviews and approves the full code in osFoundry.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "room_id": {"type": "string"},
      "name": {"type": "string", "maxLength": 200},
      "files": {"type": "object", "additionalProperties": {"type": "string"}},
      "idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}
    },
    "required": ["room_id", "name", "files", "idempotency_key"],
    "additionalProperties": false
  },
  "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
  "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]
}

इसके साथ चार और Room tools हैं: read_room, list_room_apps (limit 1–50), read_room_app_status (इसे room_id और instance_id चाहिए) और propose_room_repo_app (इसमें files की जगह repository_id और version_id जाते हैं)। तीनों read tools osfoundry:read और readOnlyHint: true हैं। दोनों proposal tools osfoundry:write और destructiveHint: true हैं, और इसी वजह से Claude Code इन्हें कॉल करने से पहले पूछता है।

असली बात verb में है। यह tool Room में कुछ भी नहीं बनाता। यह एक proposal बनाता है, और उसे Room tab में बदलने का काम एक इंसान करता है। आगे देखेंगे: schema क्या लागू करता है और क्या सर्वर पर छोड़ देता है, एक proposal कितना भारी होता है, idempotency key ज़रूरी क्यों है, और client को किसी इंसान का इंतज़ार कैसे करना चाहिए। सब कुछ client की जगह एक Python stand-in से मापा गया, क्योंकि इस Mac पर कोई claude binary इंस्टॉल नहीं है।

Schema क्या पकड़ता है, और क्या सर्वर पर छोड़ देता है?

room_proto.py ऊपर वाले लाइव inputSchema (जिसे tools-list.json के रूप में सेव किया गया है) के ख़िलाफ़ jsonschema से calls को validate करता है। दो और नियम इस बात से आते हैं कि osFoundry snippet proposals को कैसे संभालता है। Room runtime का entry, src/App.tsx, मौजूद होना चाहिए। और हर path एक सुरक्षित relative path होना चाहिए। Script दोनों नियमों को schema के ऊपर लागू करता है:

$ uv run --with jsonschema --with tiktoken python3 room_proto.py
== validation ==
ok               PASS
no App.tsx       REJECT  rule: src/App.tsx missing
absolute path    REJECT  rule: unsafe path '/etc/hosts'
dot-dot path     REJECT  rule: unsafe path 'src/../../x.ts'
backslash path   REJECT  rule: unsafe path 'src\\x.ts'
name 201 chars   REJECT  schema: 'nnnn…' is too long
key 7 chars      REJECT  schema: 'abcdefg' is too short
extra field      REJECT  schema: Additional properties are not allowed ('visibility' was unexpected)
non-string file  REJECT  schema: {'a': 1} is not of type 'string'
caught by published schema: 4, needs server rule: 4

आधी ग़लत calls JSON Schema से निकल जाती हैं। files object के path keys को additionalProperties से सीमित नहीं किया जा सकता। इसके लिए pattern के साथ propertyNames चाहिए, और normalisation के बाद .. को रिजेक्ट करने वाला pattern जल्दी ही उलझा हुआ हो जाता है। इसलिए schema बस "strings का map" कहता है और keys की जाँच सर्वर करता है। हाँ, top level पर additionalProperties: false सच में काम आता है। जो model अपनी तरफ़ से "visibility": "public" गढ़ ले, उसे चुपचाप ignore हुए field की जगह schema error मिलता है।

अगर आप client बना रहे हैं, तो कॉल करने से पहले यही जाँच चलाइए। रिजेक्ट हुआ proposal एक round trip खाता है और, उससे भी बुरा, files दोबारा लिखने के output tokens।

एक proposal कितना बड़ा होता है?

इस walkthrough का ऐप एक standup timer है: src/App.tsx (63 lines) और src/styles.css (14 lines)।

== size ==
src/App.tsx        2021 B   63 lines    583 tok
src/styles.css     1046 B   14 lines    399 tok
source bytes 3067, envelope bytes 3431, escape+frame overhead 11.9%
argument tokens (cl100k) 1141
   2 files: envelope    4463 B,   1394 tok
   6 files: envelope   12919 B,   4078 tok
  21 files: envelope   44639 B,  14143 tok
tools/list 45368 B for 59 tools; the 5 room tools 3482 B (939 tok)

JSON-RPC envelope raw source पर 11.9% जोड़ता है, ज़्यादातर escaped newlines और quotes की वजह से। लेकिन असली cost यह नहीं है। files का हर byte model output है: Claude Code पहले file लिखता है और फिर उसे tool argument के रूप में दोबारा लिखता है। दो files वाला proposal लगभग 1,100 tokens के arguments का होता है। एक ही component को दोहराकर बनाया गया 21 files वाला ऐप 14,143 का। Tokens tiktoken cl100k_base से गिने गए हैं, जो OpenAI का tokenizer है, इसलिए इन्हें अनुमानित मानिए।

Schema files के लिए कोई byte cap प्रकाशित नहीं करता। व्यवहार में सीमा reviewer तय करता है। Approval card हर file को "Review all proposed files (N)" के नीचे पूरा दिखाता है, हर file अपने अलग scroll box में। कोई भी card पर 21 files नहीं पढ़ता। इतने बड़े किसी भी ऐप के लिए propose_room_repo_app बेहतर है: यह उसी project की किसी GitNest repository के pinned version की ओर इशारा करता है, और card कोड पेस्ट करने की बजाय "Review repository code before approving" का लिंक देता है।

Review gate क्या गारंटी देता है?

Tool description साफ़ कहता है: snippet "appears in the cloud Room launcher only after its owner reviews and approves the full code"। Room में launcher ऐप्स की tab bar है। Card पर लिखा होता है "Approval makes this code available in the Room app launcher. Review the files before approving."। "Approve and create" tab जोड़ देता है। "Decline" उसे हटा देता है। Pending proposal को Room members खोल नहीं सकते, इसलिए बिना review हुआ snippet कभी किसी के session में नहीं चलता।

इससे retry की समस्या client के सिर आ जाती है। HTTP पर MCP में ऐसा हो सकता है कि सर्वर काम कर चुका हो और response खो जाए। अगर client फिर नई key के साथ retry करे, तो owner को एक ऐप के लिए दो cards मिलते हैं। room_proto.py इसे एक in-memory सर्वर से मॉडल करता है जो proposals को key के हिसाब से स्टोर करता है, 1,000 proposals और हर response के खोने की 5% संभावना के साथ:

== review gate, 1000 proposals, 5% lost responses ==
random   calls 1074  owner cards 1074  duplicates 74  in launcher before approval 0
content  calls 1057  owner cards 1000  duplicates 0  in launcher before approval 0

हर कोशिश पर नया UUID लेने से 1,074 में से 74 cards duplicates होते हैं, जिन्हें owner को पहचानकर decline करना पड़ता है। Content से बनी key, "snip-" + sha256(room_id, name, files)[:32], के साथ retry उसी key को लेकर जाता है और duplicates की गिनती 0 रहती है। Files में जानबूझकर किया गया बदलाव नई key और नया card बनाता है, जो ठीक वही है जो आप चाहते हैं। Schema का 8 characters का minimum "1" जैसी keys को बाहर रखता है। दोनों runs में approval से पहले कुछ भी launcher तक नहीं पहुँचा। यह हिस्सा सर्वर की ज़िम्मेदारी है, client की नहीं।

Claude Code को owner का इंतज़ार कैसे करना चाहिए?

initialize सिर्फ़ "capabilities": {"tools": {"listChanged": false}} लौटाता है, और कुछ नहीं। "आपका proposal approve हो गया" जैसा कोई push नहीं है। Client के पास तीन विकल्प हैं। वह user से कह सकता है कि approve करने के बाद बता दें, वह read_room_app_status को poll कर सकता है (या list_room_apps को, जब तक नया instance न दिखे), या वह Room के लिए poll_resource_events को resume कर सकता है, जो resource_type: "room" स्वीकार करता है। Token के बिना मैंने यह verify नहीं किया कि approval वहाँ कौन-से events लिखता है, इसलिए simulation status को poll करता है।

Input है इंसान का review time। Script इसे log-normal distribution से लेता है, जिसका median 6 मिनट है और budget एक घंटा। यह एक अनुमान है, माप नहीं, लेकिन इसका आकार (ज़्यादातर लोग कुछ मिनटों में जवाब देते हैं, कुछ आधा घंटा लेते हैं) वास्तविकता के क़रीब है:

== polling while the owner reviews (n=2000, median review 6 min, 1 h budget) ==
review delay p50 357s  p95 1816s
fixed 5s                   calls mean  111.8  lag p50   2.4s  p95    4.7s  gave up 14
fixed 30s                  calls mean   19.0  lag p50  14.5s  p95   28.4s  gave up 14
backoff 5s x1.5 cap 120s   calls mean   10.8  lag p50  47.0s  p95  111.0s  gave up 14
backoff 10s x2 cap 300s    calls mean    6.1  lag p50 105.2s  p95  273.8s  gave up 14

हर 5 सेकंड पर poll करने से approval 5 s के भीतर पकड़ में आ जाता है, पर हर proposal पर 112 calls लगती हैं, और हर call tool output पर खर्च हुआ एक model turn है। 30 सेकंड का fixed interval 19 calls लेता है, और सबसे बुरे केस में 28 सेकंड की देरी। 2 मिनट की cap वाला backoff इसे 11 calls तक ले आता है, और p95 lag 111 s होता है। 2,000 में से 14 reviews एक घंटे से ज़्यादा चले, और हर strategy ने उन पर बराबर हार मानी। Interactive session के लिए सबसे सस्ता सही जवाब है शून्य calls: turn को "approve it under Connected → Needs your approval and tell me" (Connected → Needs your approval में approve करके मुझे बताइए) के साथ ख़त्म करें, फिर एक list_room_apps call करें। Polling तभी फ़ायदेमंद है जब बीच में Claude Code के पास कोई और काम हो।

अंदाज़ा लगाने के लिए असली round trips: जापान में इस Mac से लाइव endpoint तक हर तरह की दस-दस unauthenticated calls।

$ python3 probe.py
initialize                       HTTP 200     308 B  median    680 ms  min   358  max   968
tools/list                       HTTP 200   45368 B  median    687 ms  min   429  max  1253
tools/call read_room (no token)  HTTP 401     337 B  median    559 ms  min   427  max   847
  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"

लगभग 0.6 s प्रति call। यानी 5 सेकंड का loop अपना दसवाँ हिस्सा नेटवर्क पर बिताता है, और हर call पर एक model turn इससे कहीं ज़्यादा महँगा पड़ता है।

Snippet के लिए "build state" का क्या मतलब है?

read_room_app_status "the safe launcher and latest build state of one app" लौटाता है, बिना config, files, logs या secrets के। Snippet का कोई server build नहीं होता। Room उसकी files वहीं compile करता है जहाँ tab खोला जाता है: desktop app में Sucrase के साथ sandboxed iframe में, और browser में Sandpack sandbox में। Repository वाला रास्ता भी pinned है, और उसका approval card कहता है "This path does not build or deploy a bundle."। दोनों तरह के proposals में इंतज़ार launcher entry का करना है। Build state तभी दिखता है जब कोई tab को deploy करता है, और वह osFoundry में होता है।

यह local Room तक क्यों नहीं पहुँच सकता?

read_room कहता है "Local Rooms are unavailable", और initialize में सामान्य नियम है: "Local-only data is unavailable to cloud clients."। Local Room desktop app के अपने database में रहता है और कभी sync नहीं होता। MCP endpoint एक cloud service है जिसके पास workspace-scoped OAuth token है, और उसके पास किसी ख़ास laptop तक पहुँचने का कोई रास्ता नहीं है। वहाँ तक पहुँचने के लिए desktop app द्वारा चलाया जाने वाला relay चाहिए: हर device और project के लिए अलग से enable, online/offline state और commands की allowlist के साथ। Tool surface इसके उलट होने का दिखावा नहीं करता। यही सीमा snippet के अंदर के data पर भी लागू होती है। उसका SDK storage tab इस्तेमाल करने वाले व्यक्ति के device पर ही रहता है, और कोई भी read tool database content नहीं लौटाता।

अगर आप इसे ख़ुद जोड़ रहे हैं

  • Schema प्रकाशित करने के बाद भी path keys को सर्वर पर validate करें। JSON Schema "strings का map" बता सकता है, पर "सुरक्षित relative path" नहीं, और इस test में आधी ग़लत calls path की समस्याएँ थीं।
  • Idempotency key को content से बनाएँ, attempt से नहीं। तब खोए हुए responses की कोई क़ीमत नहीं लगती, और असली edit को फिर भी अपना card मिलता है।
  • Size limit reviewer के ध्यान के हिसाब से तय होने दें। अगर card हर file दिखाता है, तो snippets को कुछ ही files तक रखें और बड़े ऐप्स को pinned repository version के रूप में भेजें।
  • Default रूप से agent से किसी इंसान के लिए poll न करवाएँ। उसे turn ख़त्म करने दें और user के लौटने पर एक बार status पढ़ने दें, और backoff तभी इस्तेमाल करें जब उसके पास कोई और काम हो।
  • Read-back को पतला रखें। Identity और launcher state लौटाएँ, कभी config या app data नहीं, ताकि status checks लोगों के स्टोर किए गए data को पढ़ने का ज़रिया न बन जाएँ।
  • Tool description में साफ़ लिखें कि क्या पहुँच से बाहर है ("Local Rooms are unavailable"), ताकि model retry करने की बजाय user को बता दे।

Tab bar और settings के साथ Room वाला हिस्सा Room page पर है। Protocol के बारे में सामान्य जानकारी के लिए MCP glossary entry देखें।

來源:DEV Community · dev.to