@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,199 @@
+---
+title: "प्रगति"
+description: "लंबे समय से चल रहे एजेंट कार्यों के लिए लाइव प्रगति संकेत - प्रारंभ, अद्यतन, पूर्ण"
+---
+
+# प्रगति
+
+लंबे एजेंट कार्यों को स्पिनर के पीछे नहीं छिपाना चाहिए। `progress_runs` एजेंट को यह घोषणा करने का एक तरीका देता है _"मैं इस पर काम कर रहा हूं, मैंने 45% काम पूरा कर लिया है, यहां वर्तमान चरण है"_ - जिसे UI एक प्रतिशत बार के साथ फ्लोटिंग रन ट्रे के रूप में प्रस्तुत करता है।
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+चिंता को [notifications](/docs/notifications) से अलग करें: सूचनाएं एक बार सक्रिय होती हैं (_'X हुआ'_), प्रगति निरंतर स्थिति है (_'X 45% हो गया है'_)। दोनों लिखते हैं - `completeRun` और उसके बाद `notify(..., severity: "info")` उपयोगकर्ता को बताता है कि काम कब खत्म होगा, भले ही वे ट्रे नहीं देख रहे हों।
+
+## जीवनचक्र {#lifecycle}
+
+| स्थिति      | संक्रमण                           |
+| ----------- | --------------------------------- |
+| `running`   | प्रारंभिक - `startRun` द्वारा सेट |
+| `succeeded` | हैप्पी-पाथ टर्मिनल                |
+| `failed`    | त्रुटि टर्मिनल                    |
+| `cancelled` | उपयोगकर्ता ने व्यवधान डाला        |
+
+```an-diagram title="Run lifecycle" summary="startRun opens a running row; updateRunProgress patches it; completeRun moves it to one terminal status and stamps completed_at."
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+टर्मिनल स्थितियाँ `completed_at` सेट करती हैं। UI ट्रे केवल `running` पंक्तियाँ दिखाती है; पूर्ण पंक्तियाँ `action=list` प्रश्नों के लिए डेटाबेस में रहती हैं।
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+एक रन बनाएं. जेनरेट की गई आईडी के साथ पूरा `AgentRun` लौटाता है।
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+इवेंट बस पर `run.progress.started` उत्सर्जित करता है।
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+चल रहे रन के किसी भी फ़ील्ड को पैच करें। कोई भी छोड़ा गया फ़ील्ड अपरिवर्तित रहता है।
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+इवेंट बस पर `run.progress.updated` उत्सर्जित करता है। यदि रन मौजूद नहीं है या कॉलर के स्वामित्व में नहीं है, तो अद्यतन `AgentRun`, या `null` लौटाता है।
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+टर्मिनल स्थिति में संक्रमण। `succeeded` स्पष्ट रूप से `percent=100` सेट करता है।
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+टर्मिनल स्थिति के साथ `run.progress.updated` भी उत्सर्जित करता है।
+
+### लिस्टिंग {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+कोर-रूट्स प्लगइन द्वारा `/_agent-native/runs/*` पर माउंट किया गया। **HTTP पर केवल पढ़ने के लिए** - एजेंट टूल के माध्यम से लिखा जाता है क्योंकि एजेंट विहित लेखक है। सभी मार्ग स्वामी के दायरे वाले हैं।
+
+| विधि     | पथ                                |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="List active runs" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## UI घटक {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+इनलाइन हेडर विजेट - इसे नोटिफिकेशन बेल के बगल में माउंट करें। रन सक्रिय होने पर एक स्पिनर आइकन + काउंट बैज दिखाता है; क्लिक करने पर प्रति रन एक लाइव प्रतिशत बार के साथ एक ड्रॉपडाउन खुलता है। जब कोई सक्रिय रन न हो तो ट्रिगर को पूरी तरह छुपा देता है। प्रत्येक `pollMs` पर पोल `/_agent-native/runs?active=true` (डिफ़ॉल्ट 3 सेकंड)। शेडसीएन सिमेंटिक टोकन का उपयोग करता है, प्रकाश और अंधेरे विषयों को अनुकूलित करता है।
+
+## एजेंट टूल {#agent-tool}
+
+प्रत्येक टेम्पलेट में एक एकल `manage-progress` टूल पंजीकृत है। `action` पैरामीटर ऑपरेशन का चयन करता है:
+
+| कार्रवाई   | उद्देश्य                                                          |
+| ---------- | ----------------------------------------------------------------- |
+| `start`    | किसी लंबे कार्य के शीर्ष पर कॉल करें। एक रनआईडी लौटाता है।        |
+| `update`   | कार्य के दौरान समय-समय पर `percent` और/या `step` के साथ कॉल करें। |
+| `complete` | टर्मिनल - `succeeded`, `failed`, `cancelled` में से एक।           |
+| `list`     | हाल के रनों का निरीक्षण करें (`active=true` द्वारा फ़िल्टर करें)। |
+
+### दौड़ कब शुरू करें {#when-to-start}
+
+- किसी भी चीज़ के लिए उपयोग करें > ~5 सेकंड। बिना संदर्भ वाला एक स्पिनर जमे हुए महसूस करता है।
+- प्राकृतिक चौकियों पर अद्यतन करें, प्रत्येक पुनरावृत्ति पर नहीं। प्रत्येक 5-10% बहुत है।
+- **हमेशा** त्रुटि पथों सहित, `action=complete` के साथ `manage-progress` को कॉल करें। एक अनाथ `running` पंक्ति बिना पंक्ति से भी बदतर है।
+- पूरा होने पर `notify` के साथ युग्मित करें ताकि उपयोगकर्ता तब परिणाम देख सके जब वे सक्रिय रूप से ट्रे नहीं देख रहे हों।
+
+## इवेंट बस {#event-bus}
+
+[event bus](/docs/automations#event-bus) पर दो घटनाएँ उत्सर्जित होती हैं:
+
+| घटना                   | पेलोड                              |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+[Automations](/docs/automations) इनकी सदस्यता ले सकता है - उदाहरण के लिए, _"यदि एक दौड़ में 5 मिनट से अधिक समय लगता है, तो मुझे सूचित करें"_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## यह कैसे काम करता है {#internals}
+
+- **मालिक का दायरा** - प्रत्येक पंक्ति में एक `owner` कॉलम होता है; प्रत्येक क्वेरी इस पर फ़िल्टर होती है। उपयोगकर्ता केवल अपने स्वयं के रन देखते हैं।
+- **पोल एकीकरण** - प्रत्येक उत्परिवर्तन `recordChange()` को कॉल करता है इसलिए [`useDbSync`](/docs/client) का उपयोग करने वाले टेम्पलेट बिना किसी अतिरिक्त वायरिंग के स्वतः-अमान्य हो जाते हैं।
+- **तालिका का नाम** - फ्रेमवर्क में आंतरिक एजेंट-चैट टर्न जीवनचक्र ट्रैकिंग के लिए एक `agent_runs` तालिका भी है। दोनों चिंताओं को अलग रखने के लिए प्रोग्रेस प्रिमिटिव `progress_runs` का उपयोग करता है।
+- **प्रतिशत क्लैम्पिंग** - मानों को `[0, 100]` पर क्लैंप किया जाता है और लिखने पर एक पूर्णांक में पूर्णांकित किया जाता है।
+
+## आगे क्या है
+
+- [**Notifications**](/docs/notifications) - काम खत्म होने पर उपयोगकर्ता को बताने के लिए `manage-progress` (`action=complete`) के साथ जोड़ी बनाएं
+- [**Automations**](/docs/automations) - वॉचडॉग `run.progress.updated` के माध्यम से धीमी गति से चलता है
+- [**Client**](/docs/client) - वास्तविक समय कैश अमान्यकरण के लिए `useDbSync`

package/docs/content/locales/hi-IN/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "प्योर-एजेंट ऐप्स"
+description: "ऐप्स जहां एजेंट संपूर्ण उत्पाद है: ऐप-एजेंट लूप सामने का दरवाजा है, और UI केवल तब जोड़ा जाता है जब मनुष्यों को इसकी आवश्यकता होती है।"
+---
+
+# प्योर-एजेंट ऐप्स
+
+एक प्योर-एजेंट ऐप एजेंट-नेटिव का न्यूनतम अंत है: ऐप-एजेंट लूप
+उत्पाद, डैशबोर्ड नहीं। आप टर्मिनल, Slack, ईमेल, a
+निर्धारित नौकरी, अन्य एजेंट, या चैट - "मेरे अपठित ईमेल को संक्षेप में प्रस्तुत करें," "पोस्ट करें
+दैनिक मेट्रिक्स Slack के लिए" - और एजेंट कार्य करता है और जहां कहीं भी परिणाम लौटाता है
+के अंतर्गत आता है। यह अभी भी एक वास्तविक ऐप है: actions, सत्र, ऐप स्थिति, इतिहास,
+सेटिंग्स, क्रेडेंशियल और शेयर रिकॉर्ड सभी SQL में रहते हैं।
+
+```an-diagram title="The app-agent loop is the front door" summary="Many entry points reach one agent loop over SQL-backed actions and state; results return to wherever the request came from. UI is added only when humans need to supervise."
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · email</div><div class=\"diagram-pill\">Scheduled job</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">App-agent loop</span><small class=\"diagram-muted\">actions · sessions · app state in SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Result returns<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+जब कार्य पृष्ठभूमि में चलता है, तो इस आकृति तक पहुंचें, आउटपुट निकल जाता है
+ऐप, डोमेन वन-शॉट है, या आप प्रोटोटाइप कर रहे हैं। एजेंट को अभी भी UI —
+एक डैशबोर्ड नहीं, बल्कि मनुष्यों के लिए इसकी देखरेख, कॉन्फ़िगर और संचालन करने के लिए एक जगह -
+यही कारण है कि प्योर-एजेंट ऐप्स भी आमतौर पर अंतर्निहित चैट शेल को माउंट करते हैं।
+
+यह **बिना सिर** उत्पाद का आकार है। संपूर्ण निर्णय मार्गदर्शिका, क्या भेजा जाता है
+बॉक्स, मचान, रेपो एक्सेस और रन शेयरिंग अब एक ही स्थान पर रहते हैं:
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## आगे क्या है
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) - पूर्ण नेतृत्वहीन निर्णय मार्गदर्शिका और APIs
+- [**Getting Started**](/docs/getting-started) - पहले एक चैट ऐप या हेडलेस एजेंट बनाएं
+- [**Dispatch**](/docs/template-dispatch) - वर्कस्पेस टेम्पलेट जो एक बेहतरीन प्योर-एजेंट शुरुआती बिंदु है
+- [**Messaging the agent**](/docs/messaging) - उपयोगकर्ता वेब, Slack, टेलीग्राम, ईमेल पर एजेंट से कैसे बात करते हैं
+- [**Recurring Jobs**](/docs/recurring-jobs) - निर्धारित संकेत एजेंट अपने आप चलता है
+- [**Actions**](/docs/actions) - वे उपकरण जिन्हें आपका प्योर-एजेंट कॉल करेगा