ये वे record channel tools हैं जो Codex CLI connection को osFoundry से मिलते हैं, जैसा public MCP endpoint उन्हें list करता है। इन्हें 2026-11-09 को बिना authentication वाले tools/list से fetch किया गया और यहाँ काम के fields तक छोटा किया गया:
{"name": "list_record_items",
"description": "List the schema and a bounded page of item previews from one granted record channel. Use read_record_item for the complete values.",
"inputSchema": {"required": ["record_channel_id"],
"properties": {"record_channel_id": {"type": "string"}, "before_id": {"type": "string"},
"limit": {"type": "integer", "minimum": 1, "maximum": 50}}},
"annotations": {"readOnlyHint": true}}
{"name": "read_record_item",
"description": "Read one item by ID from a granted record channel and return its current version.",
"inputSchema": {"required": ["record_channel_id", "item_id"]}}
{"name": "edit_record_item",
"description": "Update validated fields in one record item. Supply the version from read_record_item; concurrent changes are rejected.",
"inputSchema": {"required": ["record_channel_id", "item_id", "values", "expected_version", "idempotency_key"],
"properties": {"values": {"type": "object"}}},
"annotations": {"readOnlyHint": false, "destructiveHint": true},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
values को देखिए। यह {"type": "object"} है, और कुछ नहीं। Tool schema यह नहीं बता सकता कि किसी channel में कौन-सी keys हैं, उनमें से कौन-से Select fields हैं, या Points में क्या रखा जा सकता है, क्योंकि ये हर channel में अलग होते हैं और जब कोई Schema tab edit करता है तो बदल जाते हैं। Codex इन्हें सिर्फ एक जगह से जान सकता है: list tool के description की पहली line से, यानी schema page के साथ ही वापस आता है। इस post का बाकी हिस्सा एक rebuild पर मापता है कि इससे क्या मिलता है, और उन्हीं चार tools के दो और फैसलों को भी: offset की जगह before_id cursor, और लौटकर देखने के लिए एक event log।
Valid value क्या है?
Field types तय हैं। osFoundry frontend की packages/shared/src/types/record.ts फ़ाइल RecordChannelFieldType को 16 types के रूप में define करती है: text, number, date, boolean, email, phone, url, select, multi_select, currency, percentage, rating, relation, file, json और formula। हर field के साथ is_required, is_unique और एक type-specific config होता है: text के लिए max_length, number के लिए min/max, rating के लिए max_stars, दोनों select types के लिए options, formula के लिए expression।
Agents सबसे ज़्यादा Select पर अटकते हैं। एक option {value, label, color} होता है। Store value होती है, और लोग label देखते हैं। RecordDataGrid.tsx select cell को options.find((o) => o.value === params.value) से render करता है, और कुछ match न हो तो एक फीके chip पर String(params.value) दिखा देता है। तो अगर कोई ढीला check "In progress" को ऐसे field में जाने दे जिसकी value in_progress है, तो grid कुछ ऐसा दिखाएगा जो पढ़ने में सही लगे पर गलत हो: कोई रंग नहीं, और value के हिसाब से group या filter करने वाली हर चीज़ के लिए अदृश्य। जिस model ने सिर्फ grid के labels या किसी व्यक्ति का message देखा है, वह labels ही भेजेगा। किसी को तो मना करना होगा।
Rejection कैसा दिखना चाहिए?
osFoundry की record API fail हुई call का जवाब {ok: false, error: {message}} से देती है। Desktop app के in-app agents वाले अपने record tools (src-tauri/src/record_tools.rs) यह message बिना बदले model को दे देते हैं, और comment इसकी वजह बताता है: API का message "names the field that failed validation, which is usually enough for a self-correcting retry." इसका unit test उदाहरण के तौर पर values.status is not a valid option लेता है।
"Usually enough" को मापा जा सकता है। Rebuild rejection में detail के चार levels आज़माता है:
- terse:
{"error": "validation_failed"} - field: कौन-सी keys fail हुईं
- values: keys, कारण, और allowed option values या range
- labels: वही सब, साथ में हर option का label
यह रहा "values" level, run से जस का तस:
{"error": "validation_failed", "fields": [
{"key": "status", "message": "values.status must be one of the option values, got \"In progress\"",
"allowed": ["new", "triaged", "in_progress", "fixed", "wont_fix"]},
{"key": "owner", "message": "values.owner must be one of the option values, got \"Aiko\"",
"allowed": ["aiko", "mika", "ren"]},
{"key": "points", "message": "values.points must be between 0 and 13, got 20", "min": 0, "max": 13},
{"key": "due", "message": "values.due must be a date as YYYY-MM-DD, got \"Friday\""},
{"key": "age_days", "message": "values.age_days is a formula field and is computed, not written"}]}
ये strings rebuild की हैं। सिर्फ values.<key> वाली naming osFoundry जैसी है।
Rebuild
यहाँ कोई Codex binary नहीं चलता। record_store.py in-memory sqlite पर list_record_items, read_record_item, edit_record_item और poll_resource_events implement करता है, live वाले ही tool names, argument names और limits के साथ। Field types और config keys record.ts से आते हैं। Preview length (120 characters), results का shape और हर validation rule rebuild के अपने हैं। एक edit BEGIN IMMEDIATE के अंदर चलता है: idempotency lookup, version compare, validation, merge, version bump, event append, commit। कोई भी समस्या पूरे edit को roll back कर देती है।
triage.py एक scripted Codex है। यह 11 fields वाले bug tracker पर काम करता है (Example: ticket, title, description, status, owner, severity, points, area, due, reporter, age_days), हर run में 200 New items, seeds 1–5। हर item को किसी व्यक्ति के शब्दों में एक triage intent मिलता है: "In progress", "Aiko", "S2 Major" या सिर्फ "major", points {1, 2, 3, 5, 8, 13, 20} में से, due "Friday" या कोई ISO date, एक area। Agent या तो शब्दों को जैसे हैं वैसे भेजता है, या पहले schema के ज़रिए labels को values से match करके map करता है। Rejection मिलने पर वह उतना ठीक करता है जितना rejection ठीक करने देता है, जो ठीक नहीं कर सकता उसे छोड़ देता है, और उस field को किसी व्यक्ति के लिए flag कर देता है। वह किसी number को कभी clamp नहीं करता। Python 3.9.6, Apple M1।
क्या page में schema होने से फर्क पड़ता है?
1,000 items, हर एक में 6 intended fields:
| Agent ने schema पढ़ा | Rejection में क्या है | Save हुए fields (6,000 में से) | व्यक्ति के लिए बचे | हर item पर edit calls |
|---|---|---|---|---|
| नहीं | कुछ नहीं | 1,363 (22.7%) | 4,637 | 7.00 |
| नहीं | कौन-सा field | 1,363 (22.7%) | 4,637 | 2.00 |
| नहीं | field, कारण, allowed values | 5,361 (89.3%) | 639 | 2.00 |
| नहीं | field, कारण, values और labels | 5,857 (97.6%) | 143 | 2.00 |
| हाँ | कुछ नहीं | 5,857 (97.6%) | 143 | 1.86 |
| हाँ | कौन-सा field | 5,857 (97.6%) | 143 | 1.14 |
| हाँ | values, या values और labels | 5,857 (97.6%) | 143 | 1.14 |
97.6% ceiling है। बाकी 143 वे items हैं जहाँ व्यक्ति ने 20 points कहा और field 13 पर रुक जाता है। इन्हें refuse होना ही चाहिए, और हर row में ये refuse हुए।
जिस agent ने schema पढ़ा, वह rejection में चाहे जो लिखा हो, ceiling तक पहुँचा। उसका पहला edit सिर्फ उन 143 out-of-range points पर fail हुआ। Schema के बिना हर पहला edit fail हुआ: status, owner, severity और area labels थे, और आधी due dates "Friday" थीं। उसके बाद recovery पूरी तरह error पर निर्भर करती है। Allowed values के बिना "कौन-सा field" बेकार है: agent जानता है कि status गलत है पर यह नहीं कि सही क्या है, तो वह उसे छोड़ देता है। Labels के बिना allowed values से 89.3% मिलता है। 639 misses "Won't fix" बनाम wont_fix और "major" बनाम s2 हैं। इनमें से कोई भी value list से match नहीं हो सकता। Rejection में labels हों तो बिना schema वाला agent भी बराबरी पर आ जाता है, हर item पर एक extra call की कीमत पर। बिना schema के छोटे-से error ने agent को हर edit को छह one-field edits में तोड़ने पर मजबूर किया, हर item पर 7 calls, और फिर भी वह एक चौथाई से कम save कर पाया।
तो schema validation design का आधा हिस्सा है। Server पर check गलत values को रोकता है। हर page के साथ आने वाला schema पहली कोशिश को सही बनाता है। इस channel में इसकी कीमत हर page पर 1,705 bytes है, यानी 50 previews वाले 16.7 KiB page का करीब 10%।
Previews क्यों, और ज़्यादा से ज़्यादा 50 क्यों?
50 previews का एक page 16.7 KiB था। उन्हीं 50 items को पूरा पढ़ना 124.6 KiB था, क्योंकि यहाँ descriptions 300–4,000 characters के हैं। Triage के लिए preview काफी है यह चुनने के लिए कि क्या खोलना है: status, ticket, title की शुरुआत। Codex उन्हीं को खोलता है जिन्हें वह बदलने वाला है। Bounded page बड़े channel को context में बाढ़ लाने से भी रोकता है। Tool description "bounded" कहता है और schema maximum: 50 कहता है।
Offset की जगह before_id क्यों?
Codex पढ़ रहा होता है तब भी लोग bugs file करते रहते हैं। Rebuild 600 items को 50-50 करके, newest first, page करता है, और हर page के बाद channel बदलता है। पाँच runs:
| हर page के बाद बदलाव | Paging | Pages | Item reads | दो बार पढ़े गए | कभी नहीं दिखे |
|---|---|---|---|---|---|
| 2 नए bugs file हुए | offset | 65 | 3,120 | 120 | 0 |
| 2 नए bugs file हुए | before_id |
60 | 3,000 | 0 | 0 |
| पहले पढ़े 2 items delete हुए | offset | 60 | 2,890 | 0 | 110 |
| पहले पढ़े 2 items delete हुए | before_id |
60 | 3,000 | 0 | 0 |
ऊपर आने वाले नए items सब कुछ नीचे खिसका देते हैं, इसलिए offset pages overlap करते हैं और Codex कुछ items को दो बार triage करता है। पहले से पढ़ी गई चीज़ delete होने पर सब कुछ ऊपर खिसक जाता है, इसलिए अगला offset page उन items के आगे से शुरू होता है जिन्हें किसी ने पढ़ा ही नहीं। शुरू से अंत तक मौजूद रहे 110 bugs कभी दिखे ही नहीं। Cursor आखिरी पढ़े गए item का नाम लेता है, और कहीं और हुआ insert या delete उसे हिला नहीं सकता। Pass के दौरान file हुए items किसी page पर नहीं आते। Event log इसी के लिए है।
पिछले pass के बाद क्या बदला, यह Codex कैसे पता करता है?
400 items के एक pass के बाद लोगों ने 30 items edit किए, 12 file किए और 3 delete किए। इन 45 को ढूँढने के दो तरीके:
| Strategy | Calls | लौटा data | मिले |
|---|---|---|---|
| हर page फिर से list करें, versions compare करें | 9.0 | 135.8 KiB | 45 में से 45 |
stored sequence से poll_resource_events
|
1.0 | 4.6 KiB | 45 में से 45 |
Script assert करती है कि दोनों ने ठीक 45 ही ढूँढे। Polling की कीमत उतनी है जितना बदला। Re-listing की कीमत हर बार channel के size जितनी है। Runs के बीच रखने वाला state एक integer है, आखिरी sequence।
और version check?
संक्षेप में, क्योंकि यह वैसे ही काम करता है जैसे Notes और knowledge bases के लिए। 1,000 edits में, जहाँ एक व्यक्ति ने Codex के read और write के बीच हर 8 में से 1 item बदला, read से लिए version ने 131 conflicts दिए और व्यक्ति के 0 बदलाव overwrite किए। Write से ठीक पहले version दोबारा पढ़ने पर 0 conflicts आए और सभी 131 overwrite हो गए। Conflict के बाद scripted Codex दोबारा पढ़ता है, देखता है कि item पहले से in progress है, और सिर्फ severity जोड़ता है।
Validation की कीमत क्या है?
2,000 valid six-field edits, तीन runs: validation के साथ हर edit पर median 72.8–75.1 µs, validate() को stub करने पर 41.9–42.4 µs। फर्क schema query और transaction के अंदर per-field checks का है। कई seconds वाले model turn के सामने यह कुछ भी नहीं।
अगर आप इसे खुद wire up करें
- Schema को listing के साथ, हर page पर लौटाइए, किसी अलग call से नहीं जिसे agent छोड़ दे। मापा गया फर्क हर item पर एक rejected edit है।
- Rejection में allowed option values और उनके labels डालिए। सिर्फ field name से agent कुछ ठीक नहीं कर सकता।
- कोई भी field fail हो तो पूरा edit reject कीजिए, और बताइए कौन-से fields। Success report करने वाला partial save उस field को छिपा देता है जो agent ने गलत भरा।
- Server पर labels को कभी coerce या numbers को clamp मत कीजिए। "major" और "20 points" किसी व्यक्ति के लिए सवाल हैं, matcher के लिए नहीं।
- Stable ID पर cursor से paging कीजिए, और अगले run के लिए agent को event sequence दीजिए।
- जब तक ज़रूरत न हो, schema changes, creates और deletes को agent के tools से बाहर रखिए। Validation का मतलब तभी है जब agent field को चौड़ा न कर सके।
नीचे चलने वाले protocol की osFoundry की छोटी definition उसकी MCP glossary entry में है। जिस record channel screen से schema आता है, वह Records page पर है।
Top comments (0)