Blob और artifact स्टोरेज आर्किटेक्चर

यह दस्तावेज़ बताता है कि coding-agent बड़े/बाइनरी पेलोड को सेशन JSONL के बाहर कैसे स्टोर करता है, ट्रंकेटेड टूल आउटपुट कैसे पर्सिस्ट किया जाता है, और आंतरिक URL (artifact://, agent://) स्टोर किए गए डेटा में कैसे रिज़ॉल्व होते हैं।

दो स्टोरेज सिस्टम क्यों मौजूद हैं

रनटाइम विभिन्न डेटा आकारों के लिए दो अलग-अलग पर्सिस्टेंस मैकेनिज़्म का उपयोग करता है:

Content-addressed blobs (blob:sha256:<hash>): ग्लोबल, बाइनरी-ओरिएंटेड स्टोरेज जो पर्सिस्टेड सेशन एंट्रीज़ से बड़े इमेज base64 पेलोड को एक्सटर्नलाइज़ करने के लिए उपयोग किया जाता है।
सेशन-स्कोप्ड artifacts (<sessionFile-without-.jsonl>/ के अंतर्गत फ़ाइलें): पूर्ण टूल आउटपुट और सबएजेंट आउटपुट के लिए प्रति-सेशन टेक्स्ट फ़ाइलें।

ये जानबूझकर अलग हैं:

blob स्टोरेज कंटेंट हैश द्वारा डीडुप्लिकेशन और स्थिर संदर्भों को ऑप्टिमाइज़ करता है,
artifact स्टोरेज append-only सेशन टूलिंग और ह्यूमन/टूल रिट्रीवल को लोकल ID द्वारा ऑप्टिमाइज़ करता है।

स्टोरेज सीमाएँ और ऑन-डिस्क लेआउट

Blob स्टोर सीमा (ग्लोबल)

SessionManager BlobStore(getBlobsDir()) बनाता है, इसलिए blob फ़ाइलें एक साझा ग्लोबल blob डायरेक्टरी में रहती हैं (सेशन फ़ोल्डर में नहीं)।

Blob फ़ाइल नामकरण:

फ़ाइल पथ: <blobsDir>/<sha256-hex>
कोई एक्सटेंशन नहीं
एंट्रीज़ में स्टोर किया गया संदर्भ स्ट्रिंग: blob:sha256:<sha256-hex>

निहितार्थ:

सेशनों में समान बाइनरी कंटेंट उसी हैश/पथ पर रिज़ॉल्व होता है,
कंटेंट स्तर पर राइट्स इडेम्पोटेंट हैं,
blobs किसी भी व्यक्तिगत सेशन फ़ाइल से अधिक समय तक जीवित रह सकते हैं।

Artifact सीमा (सेशन-लोकल)

ArtifactManager सेशन फ़ाइल पथ से artifact डायरेक्टरी प्राप्त करता है:

सेशन फ़ाइल: .../<timestamp>_<sessionId>.jsonl
artifacts डायरेक्टरी: .../<timestamp>_<sessionId>/ (.jsonl हटाकर)

Artifact प्रकार इस डायरेक्टरी को साझा करते हैं:

ट्रंकेटेड टूल आउटपुट फ़ाइलें: <numericId>.<toolType>.log (artifact:// के लिए)
सबएजेंट आउटपुट फ़ाइलें: <outputId>.md (agent:// के लिए)

ID और नाम आवंटन योजनाएँ

Blob ID: कंटेंट हैश

BlobStore.put() रॉ बाइनरी बाइट्स पर SHA-256 कम्प्यूट करता है और लौटाता है:

hash: हेक्स डाइजेस्ट,
path: <blobsDir>/<hash>,
ref: blob:sha256:<hash>।

कोई सेशन-लोकल काउंटर उपयोग नहीं किया जाता।

Artifact ID: सेशन-लोकल मोनोटोनिक इंटीजर

ArtifactManager पहले उपयोग पर मौजूदा *.log artifact फ़ाइलों को स्कैन करता है ताकि अधिकतम मौजूदा न्यूमेरिक ID मिले और nextId = max + 1 सेट करे।

आवंटन व्यवहार:

फ़ाइल फ़ॉर्मेट: {id}.{toolType}.log
ID अनुक्रमिक स्ट्रिंग हैं ("0", "1", …)
रिज़्यूम मौजूदा artifacts को ओवरराइट नहीं करता क्योंकि स्कैन आवंटन से पहले होता है।

यदि artifact डायरेक्टरी गायब है, तो स्कैनिंग खाली सूची देती है और आवंटन 0 से शुरू होता है।

एजेंट आउटपुट ID (`agent://`)

AgentOutputManager सबएजेंट आउटपुट के लिए ID <index>-<requestedId> के रूप में आवंटित करता है (वैकल्पिक रूप से पैरेंट प्रीफ़िक्स के अंतर्गत नेस्टेड, जैसे 0-Parent.1-Child)। यह रिज़्यूम पर अगले इंडेक्स से जारी रखने के लिए इनिशियलाइज़ेशन पर मौजूदा .md फ़ाइलों को स्कैन करता है।

पर्सिस्टेंस डेटाफ़्लो

1) सेशन एंट्री पर्सिस्टेंस रीराइट पथ

सेशन एंट्रीज़ लिखे जाने से पहले (#rewriteFile / इंक्रीमेंटल पर्सिस्ट), SessionManager prepareEntryForPersistence() (truncateForPersistence के माध्यम से) कॉल करता है।

मुख्य व्यवहार:

बड़ी स्ट्रिंग ट्रंकेशन: ओवरसाइज़्ड स्ट्रिंग्स को काटा जाता है और "[Session persistence truncated large content]" सफ़िक्स किया जाता है।
ट्रांसिएंट फ़ील्ड स्ट्रिपिंग: partialJson और jsonlEvents पर्सिस्टेड एंट्रीज़ से हटा दिए जाते हैं।
इमेज एक्सटर्नलाइज़ेशन blobs में:
- केवल content ऐरे में इमेज ब्लॉक्स पर लागू होता है,
- केवल जब data पहले से blob ref नहीं है,
- केवल जब base64 लंबाई कम से कम थ्रेशोल्ड (BLOB_EXTERNALIZE_THRESHOLD = 1024) है,
- इनलाइन base64 को blob:sha256:<hash> से बदलता है।

यह सेशन JSONL को कॉम्पैक्ट रखता है जबकि रिकवरेबिलिटी बनाए रखता है।

2) सेशन लोड रीहाइड्रेशन पथ

सेशन खोलते समय (setSessionFile), माइग्रेशन के बाद, SessionManager resolveBlobRefsInEntries() चलाता है।

प्रत्येक message/custom-message इमेज ब्लॉक के लिए जिसमें blob:sha256:<hash> है:

blob स्टोर से blob बाइट्स पढ़ता है,
बाइट्स को वापस base64 में कनवर्ट करता है,
रनटाइम कंज़्यूमर्स के लिए इन-मेमोरी एंट्री को इनलाइन base64 में म्यूटेट करता है।

यदि blob गायब है:

resolveImageData() चेतावनी लॉग करता है,
मूल ref स्ट्रिंग अपरिवर्तित लौटाता है,
लोड जारी रहता है (कोई हार्ड क्रैश नहीं)।

3) टूल आउटपुट स्पिल/ट्रंकेशन पथ

OutputSink bash/python/ssh और संबंधित एक्ज़ीक्यूटर्स में स्ट्रीमिंग आउटपुट को पावर करता है।

व्यवहार:

प्रत्येक चंक को सैनिटाइज़ किया जाता है और इन-मेमोरी टेल बफ़र में जोड़ा जाता है।
जब इन-मेमोरी बाइट्स स्पिल थ्रेशोल्ड (DEFAULT_MAX_BYTES, 50KB) से अधिक हो जाते हैं, तो सिंक आउटपुट को ट्रंकेटेड मार्क करता है।
यदि artifact पथ उपलब्ध है, तो सिंक एक फ़ाइल राइटर खोलता है और लिखता है:
- मौजूदा बफ़र्ड कंटेंट एक बार,
- सभी बाद के चंक।
इन-मेमोरी बफ़र हमेशा डिस्प्ले के लिए टेल विंडो तक ट्रिम किया जाता है।
dump() artifactId सहित सारांश लौटाता है केवल जब फ़ाइल सिंक सफलतापूर्वक बनाया गया हो।

व्यावहारिक प्रभाव:

UI/टूल रिटर्न ट्रंकेटेड टेल दिखाता है,
पूर्ण आउटपुट artifact फ़ाइल में संरक्षित है और artifact://<id> के रूप में संदर्भित है।

यदि फ़ाइल सिंक निर्माण विफल होता है (I/O एरर, मिसिंग पथ, आदि), तो सिंक चुपचाप केवल इन-मेमोरी ट्रंकेशन पर फ़ॉलबैक करता है; पूर्ण आउटपुट पर्सिस्ट नहीं होता।

URL एक्सेस मॉडल

`blob:` संदर्भ

blob:sha256:<hash> सेशन एंट्री पेलोड के अंदर एक पर्सिस्टेंस संदर्भ है, राउटर द्वारा हैंडल किया जाने वाला आंतरिक URL स्कीम नहीं। रिज़ॉल्यूशन सेशन लोड के दौरान SessionManager द्वारा किया जाता है।

`artifact://<id>`

ArtifactProtocolHandler द्वारा हैंडल किया जाता है:

सक्रिय सेशन artifact डायरेक्टरी की आवश्यकता है,
ID न्यूमेरिक होना चाहिए,
फ़ाइलनाम प्रीफ़िक्स <id>. मैच करके रिज़ॉल्व करता है,
मैच की गई .log फ़ाइल से रॉ टेक्स्ट (text/plain) लौटाता है,
गायब होने पर, एरर में उपलब्ध artifact ID की सूची शामिल होती है।

गायब डायरेक्टरी का व्यवहार:

यदि artifacts डायरेक्टरी मौजूद नहीं है, तो No artifacts directory found थ्रो करता है।

`agent://<id>`

AgentProtocolHandler द्वारा <artifactsDir>/<id>.md पर हैंडल किया जाता है:

सादा फ़ॉर्म मार्कडाउन टेक्स्ट लौटाता है,
/path या ?q= फ़ॉर्म JSON एक्सट्रैक्शन करते हैं,
path और query एक्सट्रैक्शन को संयोजित नहीं किया जा सकता,
यदि एक्सट्रैक्शन अनुरोधित है, तो फ़ाइल कंटेंट को JSON के रूप में पार्स होना चाहिए।

गायब डायरेक्टरी का व्यवहार:

No artifacts directory found थ्रो करता है।

गायब आउटपुट का व्यवहार:

मौजूदा .md फ़ाइलों से उपलब्ध ID के साथ Not found: <id> थ्रो करता है।

Read टूल एकीकरण:

read नॉन-एक्सट्रैक्शन आंतरिक URL रीड्स के लिए offset/limit पेजिनेशन का समर्थन करता है,
जब agent:// एक्सट्रैक्शन उपयोग किया जाता है तो offset/limit को अस्वीकार करता है।

रिज़्यूम, फ़ोर्क, और मूव सिमेंटिक्स

रिज़्यूम

ArtifactManager पहले आवंटन पर मौजूदा {id}.*.log फ़ाइलों को स्कैन करता है और नंबरिंग जारी रखता है।
AgentOutputManager मौजूदा .md आउटपुट ID को स्कैन करता है और नंबरिंग जारी रखता है।
SessionManager लोड पर blob refs को base64 में रीहाइड्रेट करता है।

फ़ोर्क

SessionManager.fork() नई सेशन ID और parentSession लिंक के साथ एक नई सेशन फ़ाइल बनाता है, फिर पुरानी/नई फ़ाइल पथ लौटाता है। Artifact कॉपीइंग AgentSession.fork() द्वारा हैंडल की जाती है:

पुरानी artifact डायरेक्टरी को नई artifact डायरेक्टरी में रिकर्सिव कॉपी का प्रयास करता है,
गायब पुरानी डायरेक्टरी सहन की जाती है,
नॉन-ENOENT कॉपी एरर चेतावनी के रूप में लॉग किए जाते हैं और फ़ोर्क फिर भी पूरा होता है।

फ़ोर्क के बाद ID निहितार्थ:

यदि कॉपी सफल हुई, तो नए सेशन में artifact काउंटर अधिकतम कॉपी किए गए ID के बाद से जारी रहते हैं,
यदि कॉपी विफल/स्किप हुई, तो नए सेशन artifact ID 0 से शुरू होते हैं।

फ़ोर्क के बाद blob निहितार्थ:

blobs ग्लोबल और content-addressed हैं, इसलिए blob डायरेक्टरी कॉपी की आवश्यकता नहीं है।

नए cwd में मूव

SessionManager.moveTo() सेशन फ़ाइल और artifact डायरेक्टरी दोनों को नई डिफ़ॉल्ट सेशन डायरेक्टरी में रीनेम करता है, यदि बाद का कोई चरण विफल होता है तो रोलबैक लॉजिक के साथ। यह सेशन स्कोप को स्थानांतरित करते हुए artifact पहचान को संरक्षित करता है।

विफलता हैंडलिंग और फ़ॉलबैक पथ

मामला	व्यवहार
रीहाइड्रेशन के दौरान Blob फ़ाइल गायब	चेतावनी और `blob:sha256:` ref स्ट्रिंग इन-मेमोरी रखें
`BlobStore.get` के माध्यम से Blob रीड ENOENT	`null` लौटाता है
Artifact डायरेक्टरी गायब (`ArtifactManager.listFiles`)	खाली सूची लौटाता है (आवंटन नए सिरे से शुरू हो सकता है)
Artifact डायरेक्टरी गायब (`artifact://` / `agent://`)	स्पष्ट `No artifacts directory found` थ्रो करता है
Artifact ID नहीं मिला	उपलब्ध ID सूची के साथ थ्रो करता है
OutputSink artifact राइटर इनिट विफल	केवल टेल-ओनली ट्रंकेशन के साथ जारी रहता है (कोई पूर्ण-आउटपुट artifact नहीं)
कोई सेशन फ़ाइल नहीं (कुछ टास्क पथ)	टास्क टूल सबएजेंट आउटपुट के लिए अस्थायी artifacts डायरेक्टरी पर फ़ॉलबैक करता है

बाइनरी blob एक्सटर्नलाइज़ेशन बनाम टेक्स्ट-आउटपुट artifacts

Blob एक्सटर्नलाइज़ेशन पर्सिस्टेड सेशन एंट्री कंटेंट के अंदर बाइनरी इमेज पेलोड के लिए है; यह JSONL में इनलाइन base64 को स्थिर कंटेंट refs से बदलता है।
Artifacts एक्ज़ीक्यूशन आउटपुट और सबएजेंट आउटपुट के लिए सादी टेक्स्ट फ़ाइलें हैं; ये आंतरिक URL के माध्यम से सेशन-लोकल ID द्वारा एड्रेसेबल हैं।

दोनों सिस्टम केवल अप्रत्यक्ष रूप से इंटरसेक्ट करते हैं (दोनों सेशन JSONL ब्लोट को कम करते हैं) लेकिन उनकी पहचान, जीवनकाल, और रिट्रीवल पथ अलग-अलग हैं।

कार्यान्वयन फ़ाइलें

src/session/blob-store.ts — blob संदर्भ फ़ॉर्मेट, हैशिंग, put/get, externalize/resolve हेल्पर्स।
src/session/artifacts.ts — सेशन artifact डायरेक्टरी मॉडल और न्यूमेरिक artifact ID आवंटन।
src/session/streaming-output.ts — OutputSink ट्रंकेशन/स्पिल-टू-फ़ाइल व्यवहार और सारांश मेटाडेटा।
src/session/session-manager.ts — पर्सिस्टेंस ट्रांसफ़ॉर्म, लोड पर blob रीहाइड्रेशन, सेशन फ़ोर्क/मूव इंटरैक्शन।
src/session/agent-session.ts — इंटरैक्टिव फ़ोर्क के दौरान artifact डायरेक्टरी कॉपी।
src/tools/output-utils.ts — टूल artifact मैनेजर बूटस्ट्रैप और प्रति-टूल artifact पथ आवंटन।
src/internal-urls/artifact-protocol.ts — artifact:// रिज़ॉल्वर।
src/internal-urls/agent-protocol.ts — agent:// रिज़ॉल्वर + JSON एक्सट्रैक्शन।
src/sdk.ts — आंतरिक URL राउटर वायरिंग और artifacts-dir रिज़ॉल्वर।
src/task/output-manager.ts — agent:// के लिए सेशन-स्कोप्ड एजेंट आउटपुट ID आवंटन।
src/task/executor.ts — सबएजेंट आउटपुट artifact राइट्स (<id>.md) और अस्थायी artifact डायरेक्टरी फ़ॉलबैक।