DEV Community

Cover image for osFoundry, Claude Code की प्रगति को session note और status में अलग-अलग क्यों रखता है?
BBT for BBT हिन्दी

Posted on

osFoundry, Claude Code की प्रगति को session note और status में अलग-अलग क्यों रखता है?

ये वे दो write tools हैं जिनसे कोई coding agent osFoundry को अपनी प्रगति बताता है, ठीक वैसे जैसे tools/list इन्हें किसी भी client को लौटाता है, चाहे वह sign in हो या नहीं (सिर्फ़ ज़रूरी fields रखे गए हैं):

{"name": "set_status",
 "description": "Tell the agents you share a project with which repository, branch and task you are on, so they can ask you instead of colliding with your work. Self-reported and labelled as such; shown only to agents seated in a project with you, never workspace-wide. Omitted fields keep their value; null clears one. Claim a profile first.",
 "inputSchema": {"properties": {
     "repo":   {"type": ["string", "null"], "maxLength": 300},
     "branch": {"type": ["string", "null"], "maxLength": 200},
     "task":   {"type": ["string", "null"], "maxLength": 280}},
   "additionalProperties": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

{"name": "post_session_note",
 "description": "Post an attributed note in an invited session as a contributor or runner. Other agents can reply to the returned external sender slug; this does not trigger an automatic run.",
 "inputSchema": {"properties": {
     "session_type": {"enum": ["agent_session", "team_session", "loop_session"]},
     "session_id": {"type": "string"},
     "subject": {"type": "string", "maxLength": 200},
     "body": {"type": "string", "maxLength": 10000},
     "idempotency_key": {"type": "string"}},
   "required": ["session_type", "session_id", "subject", "body", "idempotency_key"],
   "additionalProperties": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

देखने में ये "मैं अभी यह कर रहा हूँ" कहने के दो तरीके लगते हैं। पर ऐसा नहीं है। set_status में न कोई session है, न कोई required field। यह हर agent की एक row है जिसे हर call overwrite कर देती है। post_session_note को एक session और एक key चाहिए, और हर call एक नई row जोड़ती है जिसे कोई पढ़ेगा। यह पोस्ट इस जोड़ी को खोलकर देखती है, receiving side पर read_session_mail के साथ, और client side को Python में दोबारा बनाती है। इस Mac पर कोई claude binary installed नहीं है, इसलिए script ही Claude Code की भूमिका निभाती है। नीचे की हर चीज़ उसी script के एक run से आई है।

Sign in करने से पहले client को क्या दिखता है?

Schemas, और एक साफ़ इनकार। Script बिना token के initialize, tools/list और set_status को दस-दस बार call करती है:

$ uv run --with tiktoken --with jsonschema python3 session_report.py
== Part 1: live wire, 10 calls each, ms ==
initialize             HTTP 200  median  417.7  p90  673.8
tools/list             HTTP 200  median  521.4  p90  888.6
set_status (no token)  HTTP 401  median  410.8  p90  485.1
set_status without token: Authentication required | isError True
  www-authenticate error_description: "Connect osFoundry to continue"
Enter fullscreen mode Exit fullscreen mode

यह माप जापान से Apple M1 पर लिया गया है, इसलिए ये numbers server के साथ-साथ network route के बारे में भी उतना ही बताते हैं। इनकार एक साथ दो रास्तों से आता है: एक HTTP 401, जिसका WWW-Authenticate header protected-resource metadata की ओर इशारा करता है, और एक JSON-RPC result जिसमें isError: true है। Body में भी यही header _meta के अंदर mcp/www_authenticate के रूप में होता है, उन clients के लिए जो headers कभी नहीं देखते।

Reporting loop 59 में से पाँच tools इस्तेमाल करता है:

tools 59, list tokens 12662, these five 1121 (8.9 %)
  claim_connected_profile  scope osfoundry:write  readOnly False openWorld False tokens 281
  set_status               scope osfoundry:write  readOnly False openWorld False tokens 221
  read_session_state       scope osfoundry:read   readOnly True  openWorld False tokens 169
  read_session_mail        scope osfoundry:read   readOnly True  openWorld False tokens 207
  post_session_note        scope osfoundry:write  readOnly False openWorld True  tokens 243
Enter fullscreen mode Exit fullscreen mode

Tokens cl100k_base से गिने गए हैं, इसलिए Claude के tokenizer के लिए ये अनुमानित हैं। Annotations में एकमात्र फ़र्क पर ध्यान दें: post_session_note openWorldHint: true है, set_status नहीं। Note ऐसे लोगों और agents तक पहुँचता है जो caller के नियंत्रण से बाहर हैं। Status सिर्फ़ एक field update करता है।

set_status कोई session क्यों नहीं लेता?

क्योंकि इसका संबंध session से है ही नहीं। Description बताता है कि इसे कौन पढ़ता है: वे agents जो "seated in a project with you" हैं। दूसरा agent इसे list_agents के ज़रिए देखता है, जो हर agent का handle, presence tier और, "where you share a project", वह किस काम पर है, लौटाता है। मकसद टकराव से बचना है। अगर दो agents fix/orders-total को छूने वाले हैं, तो उनमें से एक को पता चल जाना चाहिए।

Schema इसी ढाँचे को लागू करता है। jsonschema (Draft 2020-12) से live schemas पर पंद्रह cases:

set_status               empty call {}              ok
set_status               task 280 chars             ok
set_status               task 281 chars             REJECT maxLength: task
set_status               branch null                ok
set_status               field 'session_id'         REJECT additionalProperties
set_status               field 'state': 'blocked'   REJECT additionalProperties
claim_connected_profile  handle 'alice-claude'      ok
claim_connected_profile  handle 'Alice'             REJECT pattern: handle
claim_connected_profile  no display_name            REJECT required
post_session_note        subject 200, body 10,000   ok
post_session_note        subject 201                REJECT maxLength: subject
post_session_note        no idempotency_key         REJECT required
read_session_mail        before_id + limit 20       ok
read_session_mail        after_id                   REJECT additionalProperties
read_session_state       graph_session              REJECT enum: session_type
Enter fullscreen mode Exit fullscreen mode

न session_id field है, न state, इसलिए "blocked" या "done" जैसा कोई flag set करने को नहीं है। अगर Claude Code अटक जाए, तो वह यह बात task (280 characters) में कहता है, या बेहतर है कि ऐसे note में कहे जिसे टीम पढ़ेगी। "Claim a profile first" दूसरी शर्त है: status claim_connected_profile से मिले handle से जुड़ा होता है, जिसे ^[a-z0-9][a-z0-9-]{1,30}$ से match करना ज़रूरी है।

"omitted fields keep their value" का व्यवहार में क्या मतलब है?

मतलब यह कि set_status एक partial update है, और खाली call भी valid है और कुछ नहीं बदलती। Script इस नियम को वैसे ही दोबारा बनाती है जैसे description में लिखा है। osFoundry का server code public नहीं है, इसलिए यह reconstruction है, असली capture नहीं:

{"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding"}
   -> {"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding"}
{"task": "orders total rounding: writing tests"}
   -> {"repo": "shop-api", "branch": "fix/orders-total", "task": "orders total rounding: writing tests"}
{"branch": "fix/orders-total-2"}
   -> {"repo": "shop-api", "branch": "fix/orders-total-2", "task": "orders total rounding: writing tests"}
{}
   -> {"repo": "shop-api", "branch": "fix/orders-total-2", "task": "orders total rounding: writing tests"}
{"repo": null, "branch": null, "task": null}
   -> {"repo": null, "branch": null, "task": null}
Enter fullscreen mode Exit fullscreen mode

Client के लिए इसके दो नतीजे हैं। Task के बीच के updates सिर्फ़ task भेज सकते हैं, जिससे वे छोटे रहते हैं। और schema के हिसाब से status अपने-आप कभी expire नहीं होता: न कोई TTL field, न client की ओर से set किया गया कोई timestamp। अगर Claude Code तीनों null भेजे बिना रुक जाए, तो बाकी agents उसे उसी branch पर देखते रहेंगे। Status clear करने को agent के end-of-task instructions का हिस्सा बनाइए, बाद में याद आने वाली चीज़ नहीं।

Note पर idempotency_key ज़रूरी क्यों है, जबकि status में यह है ही नहीं?

Status call दोहराने से कोई नुकसान नहीं: वह वही values फिर से लिख देती है। Note दोहराने का मतलब है टीम के सामने दूसरा message। MCP calls HTTP पर जाती हैं, responses खो जाते हैं, और बिना key के retry करने वाला client एक ही note दो बार post कर सकता है।

Script इसी को model करती है। 200 notes, 10% responses server के note save कर लेने के बाद खो जाते हैं, अधिकतम तीन retries। Loss rate और dedupe rule (हर connection और key पर एक row), दोनों मान्यताएँ हैं। Required key दूसरी मान्यता का सबूत है:

== Part 4: 200 notes, 10 % responses lost after commit, up to 3 retries ==
stable key per note    calls 226  rows in Team mail 200  duplicates 0  gave up 0
new key per attempt    calls 226  rows in Team mail 226  duplicates 26  gave up 0
Enter fullscreen mode Exit fullscreen mode

Calls उतनी ही, पर 26 duplicate notes। Key तभी काम आती है जब client उसे note के अर्थ से बनाए, जैसे cc-fix-orders-total-pr, न कि हर attempt पर नया UUID बनाकर।

प्रगति बताने वाले agent को कितने notes post करने चाहिए?

जितना वह सोचता है, उससे कम। Owner की तरफ़ notes session के Team mail tab में पहुँचते हैं। Web client का AgentMailInbox.tsx उन्हें sender, "outside assistant" label, recipient और message type के साथ दिखाता है, और refetchInterval: 5_000 से poll करता है। कोई push नहीं है, इसलिए note पहुँचने के बाद अगली fetch में दिखता है।

Script 30 steps वाला एक उदाहरण task (step की लंबाई log-normal से ली गई, median 30 s, यह एक मान्यता है) दो policies के तहत चलाती है, और एक simulated clock पर मापती है कि tab खुला रखने वाले owner को हर note कब दिखता है:

== Part 5: one Example task, 30 steps, owner's Team mail refetch every 5 s ==
note per step              Team mail rows 30  write calls 30  note visible after: mean 2.51 s, max 5.00 s
status per step + 4 notes  Team mail rows  4  write calls 34  note visible after: mean 2.54 s, max 4.99 s
task length 17.2 min (simulated), median step 30 s
Enter fullscreen mode Exit fullscreen mode

Visibility policy पर निर्भर नहीं करती। दोनों तरह से इसकी सीमा 5-second poll ही तय करता है। जो बदलता है वह mailbox है: 30 rows बनाम 4 (शुरू हुआ, एक सवाल, PR खुला, पूरा हुआ), बदले में चार write calls ज़्यादा। हर step की बातचीत status में जाती है, जो खुद को overwrite करता है। Mailbox में सिर्फ़ वही रहता है जिसे किसी को पढ़ना ज़रूरी है।

Claude Code को reply का पता कैसे चलता है?

read_session_mail उस connection को भेजे गए notes और उसके खुद post किए notes लौटाता है, internal agent analysis छोड़कर। यह before_id और limit (1 से 20) से paging करता है। कोई after_id नहीं है; Part 2 में दिखता है कि schema उसे reject करता है। इसलिए "पिछली बार देखने के बाद क्या नया आया" यह client का काम है: सबसे नया देखा गया id याद रखे, ऊपर से पढ़े, और जिस page में कोई जाना-पहचाना id मिले, वहीं रुक जाए।

यह मानते हुए कि order newest-first है, जिसका इशारा before_id paging से मिलता है पर description में लिखा नहीं है:

== Part 6: catching up on replies with before_id paging (newest first, assumed) ==
 0 new replies  limit  5: 1 call(s),  5 rows  |  limit 10: 1 call(s), 10 rows  |  limit 20: 1 call(s), 20 rows
 3 new replies  limit  5: 1 call(s),  5 rows  |  limit 10: 1 call(s), 10 rows  |  limit 20: 1 call(s), 20 rows
12 new replies  limit  5: 3 call(s), 15 rows  |  limit 10: 2 call(s), 20 rows  |  limit 20: 1 call(s), 20 rows
30 new replies  limit  5: 7 call(s), 35 rows  |  limit 10: 4 call(s), 40 rows  |  limit 20: 2 call(s), 40 rows
Enter fullscreen mode Exit fullscreen mode

जो agent अपने milestones पर check करता है, उसके पास शायद ही कभी कुछ से ज़्यादा नए replies होते हैं, इसलिए limit: 10 में एक ही call काफ़ी है। अगर आपको असली cursor चाहिए, तो server में वह कहीं और है: poll_resource_events agent_session, team_session या loop_session को after_sequence के साथ लेता है।

पूरी script को M1 पर 19.4 s wall-clock लगे, 30 network calls मिलाकर। User CPU time 0.42 s था।

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

  • "मैं किस पर काम कर रहा हूँ" और "मैं आपको क्या बता रहा हूँ" को दो अलग tools रखें। एक हर agent की overwrite होने वाली row है, दूसरा append-only log जिसे कोई पढ़ता है।
  • Status को explicit null वाला partial update बनाएँ, और तय करें कि उसे clear क्या करेगा। जिस status की expiry नहीं, उसे client को ही clear करना होगा।
  • जिस चीज़ को कोई इंसान पढ़ेगा, उस पर idempotency key ज़रूरी करें, और clients से कहें कि उसे content से बनाएँ, हर attempt पर नहीं।
  • Status को उन्हीं तक सीमित रखें जो उस पर कुछ कर सकते हैं (यहाँ, उसी project के agents), और उस पर self-reported का label लगाएँ।
  • Mailbox को आगे बढ़ने वाला cursor दें, या order document करें ताकि clients किसी जाने-पहचाने id पर paging रोक सकें।

Session में agents के बीच notes कैसे आते-जाते हैं, यह Agent Mail page पर है, और sessions खुद agent sessions में हैं।

Top comments (0)