@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/hi-IN/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "आवर्ती नौकरियाँ"
+description: "क्रोन-अनुसूचित संकेत एजेंट अपने आप चलाता है - दैनिक डाइजेस्ट, साप्ताहिक रिपोर्ट, प्रति घंटा मतदान।"
+---
+
+# आवर्ती नौकरियाँ
+
+एक **आवर्ती कार्य** एक संकेत है जो क्रॉन शेड्यूल पर चलता है। इस तरह से एजेंट अपने आप काम करता है: "हर सुबह 7 बजे मेरे रात भर के ईमेल को सारांशित करें," "हर सोमवार को पिछले सप्ताह के साइनअप नंबर Slack पर पोस्ट करें," "हर घंटे पुराने ड्राफ्ट के लिए स्वीप करें और उन्हें हटा दें।"
+
+आवर्ती नौकरियां एक घड़ी पर सक्रिय होती हैं। _घटनाओं_ पर प्रतिक्रिया करने के लिए (एक बुकिंग बनाई गई, एक ईमेल प्राप्त हुआ) - समान `jobs/` फ़ाइल प्रारूप और शर्तें - [Automations](/docs/automations) देखें।
+
+जॉब्स `jobs/<name>.md` पर [workspace](/docs/workspace) में रहते हैं - YAML फ्रंटमैटर के साथ सिर्फ एक Markdown फ़ाइल। कोई रजिस्ट्रेशन नहीं, कोई वायरिंग नहीं. फ़ाइल को अंदर छोड़ें और फ़्रेमवर्क उसे उठा लेता है।
+
+## एक नौकरी फ़ाइल {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+बस इतना ही। बॉडी एक प्रॉम्प्ट है जिसे एजेंट प्रत्येक निर्धारित फायरिंग पर चलाता है। एजेंट के पास इंटरैक्टिव चैट में मौजूद सभी समान टूल और वर्कस्पेस संदर्भ तक पहुंच होती है - actions, skills, मेमोरी, कनेक्टेड MCP सर्वर, सब-एजेंट।
+
+## फ्रंटमैटर {#frontmatter}
+
+| फ़ील्ड       | प्रकार                        | डिफ़ॉल्ट     | विवरण                                                                                                               |
+| ------------ | ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `schedule`   | क्रोन अभिव्यक्ति              | _(आवश्यक)_   | मानक 5-फ़ील्ड क्रोन। `"0 7 * * *"` = प्रतिदिन प्रातः 07:00 बजे; `"0 */4 * * *"` = हर 4 घंटे।                        |
+| `enabled`    | बूलियन                        | `true`       | कार्य को हटाए बिना रुकने के लिए `false` पर पलटें।                                                                   |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`  | `"creator"` नौकरी मालिक की पहचान और `ANTHROPIC_API_KEY` के साथ चलता है। `"shared"` संगठन की कुंजी का उपयोग करता है। |
+| `createdBy`  | ईमेल                          | _(ऑटो)_      | कार्यस्थान UI के माध्यम से या एजेंट द्वारा कार्य सृजित होने पर जनसंख्या।                                            |
+| `orgId`      | स्ट्रिंग                      | _(ऑटो)_      | संगठन का दायरा; निर्माता के सक्रिय संगठन से विरासत में मिला है।                                                     |
+| `lastRun`    | ISO टाइमस्टैम्प               | _(प्रबंधित)_ | प्रत्येक रन के बाद शेड्यूलर द्वारा लिखा गया।                                                                        |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(प्रबंधित)_ | नवीनतम परिणाम।                                                                                                      |
+| `lastError`  | स्ट्रिंग                      | _(प्रबंधित)_ | अंतिम रन विफल होने पर त्रुटि संदेश।                                                                                 |
+| `nextRun`    | ISO टाइमस्टैम्प               | _(प्रबंधित)_ | `schedule` से गणना; शेड्यूलर द्वारा यह तय करने के लिए उपयोग किया जाता है कि अगली बार कब फायर करना है।               |
+
+`last*` और `nextRun` फ़ील्ड शेड्यूलर द्वारा लिखे गए हैं। आप इतिहास देखने के लिए उन्हें पढ़ सकते हैं, लेकिन उन्हें हाथ से संपादित न करें - अगला रन ओवरराइट हो जाएगा।
+
+## क्रॉन सिंटैक्स {#cron}
+
+मानक 5-फ़ील्ड क्रोन (मिनट, घंटा, महीने का दिन, महीना, सप्ताह का दिन):
+
+| क्रॉन          | अर्थ                          |
+| -------------- | ----------------------------- |
+| `*/5 * * * *`  | हर 5 मिनट                     |
+| `0 * * * *`    | हर घंटे पर घंटे               |
+| `0 */4 * * *`  | हर 4 घंटे                     |
+| `0 7 * * *`    | हर दिन 07:00 बजे              |
+| `0 9 * * 1`    | प्रत्येक सोमवार प्रातः 09:00  |
+| `0 17 * * 1-5` | सप्ताह के दिनों में 17:00 बजे |
+| `0 0 1 * *`    | हर महीने का पहला दिन          |
+
+फ्रेमवर्क में क्रॉन स्ट्रिंग्स को सत्यापित और रेंडर करने के लिए क्रॉन यूटिलिटीज (`isValidCron()` और `describeCron()`) शामिल हैं, जिनका उपयोग आंतरिक रूप से संसाधन और शेड्यूलर परतों द्वारा किया जाता है।
+
+## नौकरी बनाना {#creating}
+
+### कार्यस्थान टैब से
+
+`+` → कार्यक्षेत्र पैनल में **निर्धारित कार्य**। प्रॉम्प्ट और शेड्यूल भरें. `jobs/<slug>.md` के रूप में सहेजता है और अगले मिलान टिक पर चलना शुरू कर देता है।
+
+### एजेंट से पूछकर
+
+> "एक निर्धारित कार्य बनाएं जिसमें हर सुबह 7 बजे मेरे अपठित ईमेल का सारांश हो।"
+
+एजेंट आपके लिए फ़ाइल लिखता है।
+
+### हाथ से
+
+फ्रेमवर्क के संसाधन APIs के माध्यम से `jobs/` में एक Markdown फ़ाइल ड्रॉप करें:
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## शेड्यूलर कैसे चलता है {#how-scheduler-runs}
+
+शेड्यूलर एक फ्रेमवर्क प्लगइन (आंतरिक `processRecurringJobs()` रूटीन) है जो इन-प्रोसेस चलता है: एक `setInterval` एजेंट चैट प्लगइन के अंदर, जहां भी सर्वर चल रहा है, हर 60 सेकंड में सक्रिय होता है (10 सेकंड की स्टार्टअप देरी के साथ)।
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## किसी कार्य को डिबग करना {#debugging}
+
+- कार्यस्थान में `jobs/<name>.md` खोलें - फ्रंटमैटर `lastRun`, `lastStatus`, `lastError`, `nextRun` दिखाता है।
+- **बिना प्रतीक्षा किए इसका परीक्षण करें:** कोई बलपूर्वक फायर करने वाला उपकरण नहीं है। मांग पर समान कार्य करने के लिए, या तो कार्य के संकेत को एजेंट चैट में पेस्ट करें और इसे वहां चलने दें, या अस्थायी रूप से शेड्यूल को अगले मिनट पर सेट करें ताकि शेड्यूलर इसे अगले टिक पर उठाए (फिर वास्तविक क्रॉन को पुनर्स्थापित करें)।
+- **इसे रोकें:** `enabled: false` को पलटें। फ़ाइल वहीं रुक जाती है, बस चलना बंद हो जाती है।
+
+## एजेंट टूल {#agent-tool}
+
+प्रत्येक टेम्पलेट में एक एकल `manage-jobs` टूल पंजीकृत है। `action` पैरामीटर ऑपरेशन का चयन करता है:
+
+| कार्रवाई | पैरामीटर                                                        | उद्देश्य                                                                    |
+| -------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `create` | `name`, `schedule`, `instructions` (आवश्यक); `scope`, `runAs`   | नया आवर्ती कार्य बनाएँ                                                      |
+| `list`   | `scope` (`personal`, `shared`, या सभी)                          | सभी नौकरियों को स्थिति के साथ सूचीबद्ध करें (शेड्यूल, सक्षम, अंतिम/अगला रन) |
+| `update` | `name` (आवश्यक); `schedule`, `instructions`, `enabled`, `runAs` | मौजूदा कार्य संपादित करें                                                   |
+| `delete` | `name` (आवश्यक)                                                 | कोई कार्य हटाएं — हमेशा पहले उपयोगकर्ता से पुष्टि करें                      |
+
+**व्यक्तिगत बनाम साझा दायरा।** प्रत्येक कार्य या तो व्यक्तिगत दायरे में रहता है (केवल निर्माता के रूप में चलता है और दिखाई देता है) या साझा/संगठन दायरे में रहता है (निर्माता की ओर से चलता है लेकिन संगठन के सदस्यों को दिखाई देता है)। `scope` और `runAs` पैरामीटर निर्माण के समय इसे नियंत्रित करते हैं। संगठन व्यवस्थापक किसी भी साझा कार्य को अद्यतन या हटा सकते हैं; गैर-व्यवस्थापक सदस्य केवल अपना प्रबंधन कर सकते हैं।
+
+## शेड्यूलिंग पैकेज से भिन्न {#vs-scheduling-package}
+
+आवर्ती नौकरियों को `@agent-native/scheduling` के साथ भ्रमित न करें:
+
+- **आवर्ती नौकरियां (यह पृष्ठ)** - क्रॉन-शेड्यूल _प्रॉम्प्ट_ एजेंट पृष्ठभूमि में चलता है। ढाँचा-स्तर। कार्यक्षेत्र में रहता है. किसी भी एजेंट-मूल ऐप पर चलता है।
+- **`@agent-native/scheduling`** - कैलेंडर/बुकिंग सुविधाओं (इवेंट प्रकार, उपलब्धता विंडो, बुकिंग) के निर्माण के लिए एक पुन: प्रयोज्य डोमेन पैकेज। `calendar` टेम्पलेट और कस्टम शेड्यूलिंग सतहों को शक्ति प्रदान करता है।
+
+आवर्ती कार्य हैं "मैं एजेंट को स्वयं कार्य करने के लिए कैसे बाध्य करूं?" शेड्यूलिंग पैकेज है "मैं एक कैलेंडर ऐप कैसे बनाऊं?" अलग-अलग चिंताएं.
+
+## आगे क्या है
+
+- [**Automations**](/docs/automations) - ईवेंट ट्रिगर और शर्तों को समान `jobs/` प्रारूप में जोड़ें
+- [**Workspace**](/docs/workspace) - जहां नौकरियां skills, मेमोरी और कस्टम एजेंटों के साथ रहती हैं
+- [**Actions**](/docs/actions) - वे उपकरण जिन्हें नौकरी के लिए जाना जाता है
+- [**Agent Teams**](/docs/agent-teams) - नौकरियां अक्सर समानांतर काम करने के लिए उप-एजेंटों को जन्म देती हैं

package/docs/content/locales/hi-IN/routing.md

@@ -0,0 +1,79 @@
+---
+title: "रूटिंग"
+description: "React राउटर v7 के साथ एजेंट-नेटिव ऐप्स के लिए फ़ाइल-आधारित रूटिंग - पेज, डायनामिक पैरामीटर और नेविगेशन।"
+---
+
+# रूटिंग
+
+एजेंट-नेटिव ऐप्स `@react-router/fs-routes` से `flatRoutes()` के माध्यम से फ़ाइल-आधारित रूटिंग के साथ **React राउटर v7** का उपयोग करते हैं। `app/routes/` में प्रत्येक फ़ाइल URL बन जाती है। टेम्प्लेट डॉट-नोटेशन कन्वेंशन का उपयोग करते हैं - डॉट्स एक फ़ाइल नाम के अंदर URL सेगमेंट को अलग करते हैं।
+
+## फ़ाइल-आधारित रूटिंग {#file-based-routing}
+
+### फ़ाइल → URL मैपिंग
+
+| फ़ाइल                 | URL                | नोट्स                                  |
+| --------------------- | ------------------ | -------------------------------------- |
+| `_index.tsx`          | `/`                | सूचकांक मार्ग                          |
+| `settings.tsx`        | `/settings`        | सरल पृष्ठ                              |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | डॉट = `/`, `$` = गतिशील पैरामीटर       |
+| `_app.tsx`            | (कोई URL खंड नहीं) | पाथलेस लेआउट - `_` के साथ उपसर्ग       |
+| `inbox/route.tsx`     | `/inbox`           | फ़ोल्डर फॉर्म - `route.tsx` इंडेक्स है |
+
+डायनेमिक पैरामीटर के लिए `$` के साथ एक सेगमेंट को उपसर्ग करें। इसे एक पथहीन लेआउट मार्ग (कोई URL खंड नहीं) बनाने के लिए `_` के साथ उपसर्ग करें। टेम्प्लेट `flatRoutes()` का उपयोग करते हैं - उपरोक्त डॉट-नोटेशन फ़ाइल प्राथमिक है; नेस्टेड-फ़ोल्डर फॉर्म `inbox/route.tsx` भी काम करता है।
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## एक नया पेज जोड़ना {#adding-a-page}
+
+फ़ाइल बनाएं और एक डिफ़ॉल्ट घटक निर्यात करें:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+बस इतना ही - React राउटर इसे स्वचालित रूप से उठाता है, पंजीकरण की आवश्यकता नहीं है।
+
+## गतिशील पैरामीटर {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## नेविगेशन {#navigation}
+
+क्लाइंट-साइड नेविगेशन के लिए `<Link>` और प्रोग्रामेटिक नेविगेशन के लिए `useNavigate()` का उपयोग करें:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## आगे क्या है
+
+- [**Client**](/docs/client) - एजेंट-मूल ब्राउज़र हुक और उपयोगिताएँ
+- [**Server**](/docs/server) - फ़ाइल-आधारित सर्वर रूट और `/_agent-native/` नेमस्पेस

package/docs/content/locales/hi-IN/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "एडेप्टर"
+description: "फ्रेमवर्क के दो एडेप्टर सीम: सैंडबॉक्स एडेप्टर बैकएंड को स्वैप करते हैं जो एजेंट के रन-कोड टूल को चलाता है, और CLI एडेप्टर एजेंट को कमांड-लाइन टूल्स तक संरचित पहुंच प्रदान करते हैं।"
+search: "एडेप्टर सैंडबॉक्स एडाप्टर सीएलआई एडाप्टर रन-कोड सैंडबॉक्सएडाप्टर क्लिएडाप्टर शेलक्लिएडाप्टर टिकाऊ रनर रिमोट सैंडबॉक्स एज सर्वर रहित चाइल्ड_प्रोसेस"
+---
+
+# एडेप्टर
+
+> **यह किसके लिए है:** मेजबान लेखक रनटाइम का विस्तार कर रहे हैं। ऐप डेवलपर शायद ही कभी
+> को इसकी आवश्यकता है - डिफ़ॉल्ट बॉक्स से बाहर काम करते हैं।
+
+Agent-Native में दो एडाप्टर सीम हैं जो एक संकीर्ण के पीछे चिंता का कारण बनते हैं,
+स्वैपेबल इंटरफ़ेस:
+
+- **सैंडबॉक्स एडाप्टर** एजेंट के `run-code` टूल को चलाने वाले बैकएंड को स्वैप करें -
+  डिफ़ॉल्ट रूप से एक स्थानीय चाइल्ड प्रक्रिया, या एक डॉकर/रिमोट/ड्यूरेबल रनर।
+- **CLI एडाप्टर** एजेंट को कमांड-लाइन टूल तक संरचित पहुंच प्रदान करते हैं
+  (`gh`, `ffmpeg`, `stripe`) खोज, उपलब्धता जांच और ए
+  सुसंगत परिणाम आकार।
+
+दोनों एक रनटाइम बाधा साझा करते हैं: वे Node.js सिस्टम बाइंडिंग पर भरोसा करते हैं और करते हैं
+एज/वर्कर रनटाइम पर नहीं चलता - [Edge and serverless](#edge-serverless) देखें।
+
+## मुझे कौन सा कोडिंग दस्तावेज़ चाहिए? {#which-doc}
+
+| आप चाहते हैं…                                                                      | उपयोग                                        |
+| ---------------------------------------------------------------------------------- | -------------------------------------------- |
+| एजेंट के **`run-code` टूल** को चलाने वाले बैकएंड को स्वैप करें                     | **सैंडबॉक्स एडाप्टर** (यह पृष्ठ)             |
+| एजेंट को कॉल करने के लिए एक CLI टूल (`gh`, `ffmpeg`) लपेटें                        | **CLI एडाप्टर** (यह पृष्ठ)                   |
+| एक Claude-कोड/Codex-शैली प्रस्तुत करें **कोडिंग कार्यक्षेत्र UI**                  | [Agent-Native Code UI](/docs/code-agents-ui) |
+| Claude कोड / Codex / Pi **एजेंट के रूप में** चलाएँ, अपने स्वयं के लूप + टूल के साथ | [Harness Agents](/docs/harness-agents)       |
+
+# सैंडबॉक्स एडाप्टर
+
+`run-code` उपकरण एक अलग वातावरण में एजेंट द्वारा आपूर्ति किए गए JavaScript को चलाता है। **सैंडबॉक्स एडाप्टर** उस टूल से _निष्पादन_ चिंता को दूर करता है ताकि बैकएंड को स्वैप किया जा सके - डिफ़ॉल्ट रूप से एक स्थानीय चाइल्ड प्रक्रिया, या डॉकर / रिमोट / टिकाऊ धावक - एजेंट लूप, `run-code.ts`, लोकलहोस्ट ब्रिज, एनवी स्क्रब, या आउटपुट फ़ॉर्मेटिंग को छुए बिना।
+
+## सीम क्यों {#why}
+
+डिफ़ॉल्ट बैकएंड एक लॉक-डाउन स्थानीय नोड चाइल्ड प्रक्रिया को जन्म देता है। यह होस्टिंग प्रक्रिया से घिरा है: होस्ट किए गए प्लेटफ़ॉर्म पर यह एजेंट लूप की सॉफ्ट निष्पादन सीमा (टाइमआउट/निरंतरता थ्रैश से पहले ~ 40s) साझा करता है। एक रिमोट या टिकाऊ एडाप्टर उस सीमा को पार करने का लीवर है - यह अनुरोध जीवनचक्र से स्वतंत्र रूप से पूरा करने के लिए बड़े डेटा कार्य चलाता है।
+
+अनुबंध को संकीर्ण रखने का मतलब है कि रिमोट एडॉप्टर को समान सुरक्षा स्थिति प्राप्त होती है। मूल प्रक्रिया हर चीज़ के स्वामित्व को गुप्त रखती है: यह सैंडबॉक्स मॉड्यूल बनाता है, लोकलहोस्ट ब्रिज चलाता है (जो अनुरोध संदर्भ रखता है और होस्ट अनुमति सूची + SSRF गार्ड लागू करता है), एनवी को स्क्रब करता है, और आउटपुट को प्रारूपित करता है। एक एडॉप्टर को केवल पहले से तैयार, **गैर-गुप्त** मॉड्यूल स्रोत प्लस संसाधन सीमाएँ प्राप्त होती हैं - यह इसे चलाने और stdout/stderr/exit स्थिति को कैप्चर करने के लिए पूरी तरह से जिम्मेदार है।
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## इंटरफ़ेस {#interface}
+
+सीम `packages/core/src/coding-tools/sandbox/` - `adapter.ts` (अनुबंध), `index.ts` (चयन: `getSandboxAdapter()` / `registerSandboxAdapter()`), और `local-child-process-adapter.ts` (डिफ़ॉल्ट) पर कोर में रहता है। इसे `run-code.ts` द्वारा पैकेज में वायर्ड किया गया है; एक होस्ट `index.ts` पंजीकरण सहायक के माध्यम से एक अलग बैकएंड में प्लग करता है (या, डॉकर बैकएंड के लिए, [blueprint](/docs/blueprint-installer) के माध्यम से जो इन फ़ाइलों को सीधे संपादित करता है)।
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+प्रत्येक बैकएंड `SandboxAdapter` लागू करता है:
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+अनुरोध और परिणाम जानबूझकर छोटे और अपारदर्शी हैं:
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## डिफ़ॉल्ट: `LocalChildProcessAdapter` {#default}
+
+बॉक्स से बाहर, `getSandboxAdapter()`, `LocalChildProcessAdapter` (`id: "local-child-process"`) लौटाता है। यह ऐतिहासिक `run-code` व्यवहार को बाइट-दर-बाइट संरक्षित करता है:
+
+- तैयार मॉड्यूल स्रोत एक ताजा अस्थायी डीआईआर में लिखा गया है।
+- बच्चा सैंडबॉक्स डीआईआर के अंदर `TMPDIR`/`TEMP`/`TMP` के साथ स्क्रब किए गए एनवी (कोई रहस्य नहीं) के साथ दौड़ता है।
+- जब नोड अनुमति मॉडल उपलब्ध होता है (`--permission`, या नोड 20 पर `--experimental-permission`), तो बच्चे को उसके अस्थायी डीआईआर, साथ ही चाइल्ड प्रक्रियाओं, श्रमिकों और मूल ऐडऑन के बाहर फ़ाइल सिस्टम पहुंच से वंचित कर दिया जाता है। आउटबाउंड नेटवर्क अनुमति मॉडल द्वारा अवरुद्ध नहीं है - लेकिन एनवी स्क्रब का मतलब है कि ऐसे अनुरोधों में कोई क्रेडेंशियल नहीं होता है, और सभी प्रमाणित कॉल पैरेंट के लूपबैक ब्रिज से गुज़रते हैं।
+- एक टाइमआउट `SIGTERM` भेजता है, फिर 2 सेकंड की छूट अवधि के बाद `SIGKILL` भेजता है।
+- टेम्प फ़ाइलों को चलाने के बाद सर्वोत्तम प्रयास से साफ़ किया जाता है।
+
+> [!WARNING]
+> डिफ़ॉल्ट एडाप्टर `node:child_process` का उपयोग करता है, जो एज/वर्कर रनटाइम पर मौजूद नहीं है। मानक Node.js वातावरण में `run-code` चलाएँ, या एक दूरस्थ एडाप्टर पंजीकृत करें - [Edge and serverless](#edge-serverless) देखें।
+
+## एडेप्टर का चयन करना {#selection}
+
+रिज़ॉल्यूशन ऑर्डर - एक स्पष्ट रूप से पंजीकृत एडाप्टर जीतता है; अन्यथा env var एक अंतर्निर्मित का चयन करता है; अन्यथा स्थानीय डिफ़ॉल्ट का उपयोग किया जाता है:
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` env var {#env}
+
+आईडी के आधार पर एक अंतर्निहित एडाप्टर का चयन करता है। वर्तमान में केवल `local` (डिफ़ॉल्ट) वायर्ड है; अज्ञात मान रन में विफल होने के बजाय स्थानीय स्तर पर वापस आ जाते हैं।
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+एक होस्ट प्रक्रिया सीम के `index.ts` के माध्यम से सभी बाद के `run-code` आमंत्रणों के लिए बैकएंड को ओवरराइड करती है - उदाहरण के लिए, एक दूरस्थ कंटेनर में प्रत्येक कॉल को चलाने के लिए:
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## टिकाऊ धावक के लिए सीम {#durable}
+
+यह इंटरफ़ेस जानबूझकर भविष्य के रिमोट/टिकाऊ सैंडबॉक्स के लिए सीम है। एक रिमोट या टिकाऊ एडॉप्टर (डॉकर, एक वर्सेल-सैंडबॉक्स-शैली धावक, या एक कतारबद्ध पृष्ठभूमि कार्यकर्ता) यह करेगा:
+
+1. आउट-ऑफ़-प्रोसेस रनटाइम के विरुद्ध `SandboxAdapter.run` लागू करें।
+2. लूपबैक ब्रिज को टनल करें (या प्रॉक्सी ब्रिज पैरेंट को वापस कॉल करता है)।
+3. बड़े डेटा जॉब्स को अनुरोध जीवनचक्र से स्वतंत्र रूप से पूरा होने दें - स्थानीय चाइल्ड-प्रोसेस एडॉप्टर को सीमित करने वाली होस्ट की गई ~40एस कोड-एक्ज़ीक्यूटिव सीमा से अधिक।
+
+इसे एक नए `AGENT_NATIVE_SANDBOX` मान (जैसे `remote`) और/या `registerSandboxAdapter()` के माध्यम से पंजीकृत करें। एजेंट लूप और `run-code.ts` कभी नहीं बदलते।
+
+> [!TIP]
+> `agent-native add sandbox docker` ब्लूप्रिंट इस सीम के विरुद्ध डॉकर एडाप्टर को लागू करने के लिए एक पूर्ण, स्व-निहित नुस्खा उत्सर्जित करता है। [Blueprint Installer](/docs/blueprint-installer) देखें.
+
+# CLI एडाप्टर
+
+अन्य एडाप्टर सीम एक एकल कमांड-लाइन टूल (`gh`, `ffmpeg`, `stripe`, `aws`) को लपेटता है ताकि एजेंट इसे खोज सके, जांच सके कि यह इंस्टॉल है या नहीं, और इसे लगातार stdout/stderr/exit-code परिणाम के साथ चला सकता है। प्रत्येक CLI एडाप्टर `CliAdapter` को लागू करता है:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+अधिकांश CLIs के लिए, `ShellCliAdapter` किसी भी बाइनरी को समझदार डिफ़ॉल्ट के साथ लपेटता है, और `CliRegistry` रनटाइम खोज के लिए एडेप्टर एकत्र करता है:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+एक CLI कॉल को क्रिया सतह पर उजागर करने के लिए उसे `defineAction` में लपेटें। `ShellCliAdapter` विकल्पों, कस्टम एडाप्टर और एक्शन-रैपिंग पैटर्न के लिए [CLI Adapters](/docs/cli-adapters) त्वरित संदर्भ देखें।
+
+## एज और सर्वर रहित {#edge-serverless}
+
+> [!WARNING]
+> दोनों एडाप्टर सीम Node.js सिस्टम बाइंडिंग पर निर्भर हैं। सैंडबॉक्स `LocalChildProcessAdapter` और CLI एडेप्टर (`ShellCliAdapter` और कस्टम एडेप्टर) `node:child_process` (`execFile` / `spawn`) का उपयोग करते हैं, जो क्लाउडफ्लेयर वर्कर्स या नेटलिफाई एज फ़ंक्शंस जैसे एज/वर्कर रनटाइम पर **मौजूद नहीं है**। यदि आप इन एज प्रीसेट पर सर्वर रूट तैनात करते हैं, तो इन एडेप्टर को निष्पादित करने से एक रनटाइम अपवाद उत्पन्न होता है। एक मानक Node.js वातावरण (पारंपरिक सर्वर कंटेनर या सर्वर रहित नोड फ़ंक्शंस) में एडाप्टर एंडपॉइंट और कार्य चलाएं - या, सैंडबॉक्स सीम के लिए, एक रिमोट एडाप्टर पंजीकृत करें जो प्रक्रिया से बाहर काम करता है।
+
+## आगे क्या है
+
+- [**CLI Adapters**](/docs/cli-adapters) - CLI सीम के लिए त्वरित संदर्भ
+- [**Blueprint Installer**](/docs/blueprint-installer) - `agent-native add sandbox docker` एक डॉकर-एडेप्टर रेसिपी प्रिंट करता है
+- [**Agent Teams**](/docs/agent-teams) - उप-एजेंटों को भारी काम सौंपना
+- [**Security**](/docs/security) - एनवी स्क्रब और ब्रिज अनुमति सूची आसन