@agent-native/core 0.99.1 → 0.99.3

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2241
-- template files: 5539
+- template files: 5551

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @agent-native/core
 
+## 0.99.3
+
+### Patch Changes
+
+- 03cd25c: Document the `agent-native invoke` CLI usage and flags on the A2A protocol docs page, across all locales.
+
+## 0.99.2
+
+### Patch Changes
+
+- 34b4f29: Keep Demo mode browser-local so backend actions and agent/MCP results retain real access-scoped data.
+- 34b4f29: Fix 404s when client-side navigating from the dispatch shell into a mounted workspace sub-app's root route. React Router's `.data` loader-fetch convention (e.g. `/coach.data`) didn't match either deployment platform's per-app routing rules (`basePath` / `basePath/*`), so the request fell through to a bare 404 before reaching the app's own server, leaving the sub-app stuck retrying its own action/agent-chat calls afterward.
+- 34b4f29: Keep the latest reasoning thought expanded until a newer thought arrives, then animate the previous thought closed.
+- 34b4f29: Preserve native browser link behavior when opening embedded extensions in their full view.
+- 34b4f29: Keep chat composers editable while AI provider readiness is loading.
+- 34b4f29: Record framework-owned Design preview iframes in session replays with the same privacy masking as the host page.
+- 34b4f29: Remove the extension viewer's View / edit source button.
+- 34b4f29: Retry transient chat-thread database failures so completed agent responses are not surfaced as unsaved.
+
 ## 0.99.1
 
 ### Patch Changes

package/corpus/core/docs/content/a2a-protocol.mdx

@@ -392,6 +392,48 @@ app environment and pass the caller identity (`userEmail`) so outbound calls are
 signed as JWT bearer tokens. Use `apiKeyEnv` only for legacy external peers that
 expect a static bearer token. Use local actions instead of invoking yourself.
 
+## CLI: agent-native invoke {#cli-invoke}
+
+`agent-native invoke` is a thin CLI wrapper over the same resolve-and-call primitive as `agentNative.invoke()`. Use it to trigger an app's agent from a shell script, a CI job, a cron entry, or any external system that can shell out — the CLI equivalent of posting to `/_agent-native/a2a` by hand.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# Resolve "analytics" in the workspace registry and wait for the reply
+agent-native invoke analytics "Summarize signups by source this month"
+
+# Call a deployed app directly by URL, reading the bearer token from env
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# Force one blocking message/send instead of the default async+poll
+agent-native invoke analytics "Quick lookup" --sync
+
+# Machine-readable output for scripting
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Description                                                               |
+| ------------------------- | ------------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | Target agent (alias for the positional `<app-or-url>`)                    |
+| `--message <text>`        | Prompt (alias for the positional `"prompt"`)                              |
+| `--api-key-env <name>`    | Read the bearer token from an environment variable                        |
+| `--api-key <token>`       | Bearer token value, passed inline                                         |
+| `--context-id <id>`       | A2A `contextId`, to continue an existing task's conversation              |
+| `--self-app-id <id>`      | Current app id, used for self-call prevention                             |
+| `--self-url <url>`        | Current app URL, used for self-call prevention                            |
+| `--timeout-ms <n>`        | Async polling timeout                                                     |
+| `--poll-interval-ms <n>`  | Async polling interval                                                    |
+| `--sync`                  | Use one blocking `message/send` request instead of the async+poll default |
+| `--no-hint`               | Send the prompt as-is, without the cross-app invocation hint              |
+| `--json`                  | Print target metadata and response text as JSON                           |
+
+Like `callAgent()`, the CLI defaults to async + poll (`invokeAgent` → `callAgent` under the hood), which is the safe choice against hosted/serverless targets — see [Serverless webhook and gateway timeouts](#json-rpc-methods) above. Pass `--sync` only when you know the target isn't behind a gateway with a short execution limit.
+
+The target resolves the same way as `agentNative.invoke()`: by workspace app id, by app name, or by a full URL — so the same command works against a sibling app in a multi-app workspace or an arbitrary A2A peer elsewhere.
+
 ## Task lifecycle {#task-lifecycle}
 
 Each message creates a task that moves through these states:

package/corpus/core/docs/content/locales/ar-SA/a2a-protocol.mdx

@@ -384,6 +384,48 @@ console.log(`Called ${result.target.name}: ${result.responseText}`);
 تم التوقيع عليها كرموز حاملة JWT. استخدم `apiKeyEnv` فقط للأقران الخارجيين القدامى الذين
 توقع رمزًا مميزًا لحامل ثابت. استخدم actions المحلي بدلاً من استدعاء نفسك.
 
+## واجهة سطر الأوامر: agent-native invoke {#cli-invoke}
+
+`agent-native invoke` عبارة عن غلاف رفيع لواجهة سطر الأوامر فوق نفس بدائية الحل والاستدعاء التي تستخدمها `agentNative.invoke()`. استخدمه لتشغيل وكيل أحد التطبيقات من نص برمجي في shell، أو مهمة CI، أو إدخال cron، أو أي نظام خارجي يمكنه تنفيذ أوامر shell — وهو المكافئ عبر سطر الأوامر لإرسال طلب POST يدويًا إلى `/_agent-native/a2a`.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# حلّ "analytics" في سجل مساحة العمل وانتظر الرد
+agent-native invoke analytics "Summarize signups by source this month"
+
+# استدعِ تطبيقًا منشورًا مباشرةً عبر عنوان URL، مع قراءة رمز الحامل من متغير بيئة
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# فرض طلب message/send حاجز واحد بدلاً من الوضع الافتراضي async+poll
+agent-native invoke analytics "Quick lookup" --sync
+
+# إخراج قابل للقراءة الآلية للبرمجة النصية
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | الوصف                                                                    |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `--agent <id\|name\|url>` | الوكيل المستهدف (اسم بديل للوسيطة الموضعية `<app-or-url>`)               |
+| `--message <text>`        | الطلب النصي (اسم بديل للوسيطة الموضعية `"prompt"`)                       |
+| `--api-key-env <name>`    | قراءة رمز الحامل (bearer token) من متغير بيئة                            |
+| `--api-key <token>`       | قيمة رمز الحامل، مُمرَّرة مباشرة                                         |
+| `--context-id <id>`       | `contextId` الخاص بـ A2A، لمتابعة محادثة مهمة موجودة بالفعل              |
+| `--self-app-id <id>`      | معرف التطبيق الحالي، يُستخدم لمنع الاستدعاء الذاتي                       |
+| `--self-url <url>`        | عنوان URL للتطبيق الحالي، يُستخدم لمنع الاستدعاء الذاتي                  |
+| `--timeout-ms <n>`        | مهلة الاستطلاع (polling) غير المتزامن                                    |
+| `--poll-interval-ms <n>`  | فاصل الاستطلاع غير المتزامن                                              |
+| `--sync`                  | استخدام طلب `message/send` حاجب واحد بدلاً من الوضع الافتراضي async+poll |
+| `--no-hint`               | إرسال الطلب النصي كما هو، دون تلميح الاستدعاء بين التطبيقات              |
+| `--json`                  | طباعة بيانات الهدف الوصفية ونص الاستجابة بصيغة JSON                      |
+
+مثل `callAgent()`، تعتمد واجهة سطر الأوامر افتراضيًا على async + poll (`invokeAgent` ← `callAgent` تحت الغطاء)، وهو الخيار الآمن عند استهداف بيئات مستضافة/serverless — انظر [مهلات بوابة الويب هوك وبوابة العبور بلا خادم](#json-rpc-methods) أعلاه. استخدم `--sync` فقط عندما تكون متأكدًا أن الهدف ليس خلف بوابة ذات مهلة تنفيذ قصيرة.
+
+يتم حل الهدف بنفس طريقة `agentNative.invoke()`: عبر معرف تطبيق مساحة العمل، أو اسم التطبيق، أو عنوان URL كامل — لذا يعمل نفس الأمر مع تطبيق شقيق في مساحة عمل متعددة التطبيقات أو مع أي نظير A2A تعسفي في مكان آخر.
+
 ## دورة حياة المهمة {#task-lifecycle}
 
 تنشئ كل رسالة مهمة تنتقل عبر هذه الحالات:

package/corpus/core/docs/content/locales/de-DE/a2a-protocol.mdx

@@ -386,6 +386,48 @@ App-Umgebung und übergeben Sie die Anruferidentität (`userEmail`), sodass ausg
 signiert als JWT-Inhaber-Token. Verwenden Sie `apiKeyEnv` nur für ältere externe Peers, die
 erwarten Sie ein statisches Inhabertoken. Verwenden Sie lokales actions, anstatt sich selbst aufzurufen.
 
+## CLI: agent-native invoke {#cli-invoke}
+
+`agent-native invoke` ist ein schlanker CLI-Wrapper über dieselbe Resolve-and-Call-Primitive wie `agentNative.invoke()`. Verwenden Sie es, um den Agenten einer App aus einem Shell-Skript, einem CI-Job, einem Cron-Eintrag oder einem beliebigen externen System auszulösen, das Befehle ausführen kann — das CLI-Äquivalent zum manuellen Posten an `/_agent-native/a2a`.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# "analytics" in der Workspace-Registry auflösen und auf die Antwort warten
+agent-native invoke analytics "Summarize signups by source this month"
+
+# Eine bereitgestellte App direkt per URL aufrufen und das Bearer-Token aus der Umgebung lesen
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# Eine einzelne blockierende message/send-Anfrage erzwingen statt des standardmäßigen Async+Poll
+agent-native invoke analytics "Quick lookup" --sync
+
+# Maschinenlesbare Ausgabe für Skripting
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Beschreibung                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| `--agent <id\|name\|url>` | Ziel-Agent (Alias für das positionelle `<app-or-url>`)                               |
+| `--message <text>`        | Prompt (Alias für das positionelle `"prompt"`)                                       |
+| `--api-key-env <name>`    | Liest das Bearer-Token aus einer Umgebungsvariable                                   |
+| `--api-key <token>`       | Bearer-Token-Wert, inline übergeben                                                  |
+| `--context-id <id>`       | A2A-`contextId`, um die Konversation einer bestehenden Aufgabe fortzusetzen          |
+| `--self-app-id <id>`      | Aktuelle App-ID, verwendet zur Selbstaufruf-Vermeidung                               |
+| `--self-url <url>`        | Aktuelle App-URL, verwendet zur Selbstaufruf-Vermeidung                              |
+| `--timeout-ms <n>`        | Timeout für Async-Polling                                                            |
+| `--poll-interval-ms <n>`  | Intervall für Async-Polling                                                          |
+| `--sync`                  | Eine blockierende `message/send`-Anfrage anstelle des Async+Poll-Standards verwenden |
+| `--no-hint`               | Den Prompt unverändert senden, ohne den App-übergreifenden Aufruf-Hinweis            |
+| `--json`                  | Zielmetadaten und Antworttext als JSON ausgeben                                      |
+
+Wie `callAgent()` verwendet die CLI standardmäßig Async + Poll (`invokeAgent` → `callAgent` unter der Haube), was die sichere Wahl gegenüber gehosteten/serverlosen Zielen ist — siehe [Serverless-Webhook- und Gateway-Timeouts](#json-rpc-methods) oben. Übergeben Sie `--sync` nur, wenn Sie wissen, dass sich das Ziel nicht hinter einem Gateway mit kurzem Ausführungslimit befindet.
+
+Das Ziel wird auf die gleiche Weise aufgelöst wie bei `agentNative.invoke()`: über die Workspace-App-ID, den App-Namen oder eine vollständige URL — sodass derselbe Befehl sowohl gegen eine Geschwister-App in einem Multi-App-Workspace als auch gegen einen beliebigen A2A-Peer anderswo funktioniert.
+
 ## Aufgabenlebenszyklus {#task-lifecycle}
 
 Jede Nachricht erstellt eine Aufgabe, die diese Zustände durchläuft:

package/corpus/core/docs/content/locales/es-ES/a2a-protocol.mdx

@@ -386,6 +386,48 @@ entorno de la aplicación y pasar la identidad de la persona que llama (`userEma
 firmado como tokens al portador JWT. Utilice `apiKeyEnv` solo para pares externos heredados que
 espera un token de portador estático. Utilice actions local en lugar de invocarse a sí mismo.
 
+## CLI: agent-native invoke {#cli-invoke}
+
+`agent-native invoke` es un envoltorio de CLI ligero sobre la misma primitiva de resolución e invocación que `agentNative.invoke()`. Úselo para activar el agente de una aplicación desde un script de shell, un job de CI, una entrada de cron, o cualquier sistema externo que pueda ejecutar comandos — el equivalente en CLI de hacer un POST manual a `/_agent-native/a2a`.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# Resuelve "analytics" en el registro del espacio de trabajo y espera la respuesta
+agent-native invoke analytics "Summarize signups by source this month"
+
+# Llama directamente a una aplicación desplegada por URL, leyendo el token de portador desde una variable de entorno
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# Fuerza un único message/send bloqueante en lugar del valor predeterminado async+poll
+agent-native invoke analytics "Quick lookup" --sync
+
+# Salida legible por máquina para scripting
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Description                                                                                    |
+| ------------------------- | ---------------------------------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | Agente de destino (alias del argumento posicional `<app-or-url>`)                              |
+| `--message <text>`        | Prompt (alias del argumento posicional `"prompt"`)                                             |
+| `--api-key-env <name>`    | Lee el token de portador desde una variable de entorno                                         |
+| `--api-key <token>`       | Valor del token de portador, pasado en línea                                                   |
+| `--context-id <id>`       | `contextId` de A2A, para continuar la conversación de una tarea existente                      |
+| `--self-app-id <id>`      | ID de la aplicación actual, usado para prevenir autoinvocación                                 |
+| `--self-url <url>`        | URL de la aplicación actual, usada para prevenir autoinvocación                                |
+| `--timeout-ms <n>`        | Tiempo de espera del sondeo asíncrono                                                          |
+| `--poll-interval-ms <n>`  | Intervalo de sondeo asíncrono                                                                  |
+| `--sync`                  | Usa una única solicitud `message/send` bloqueante en lugar del valor predeterminado async+poll |
+| `--no-hint`               | Envía el prompt tal cual, sin la sugerencia de invocación entre aplicaciones                   |
+| `--json`                  | Imprime los metadatos del destino y el texto de respuesta como JSON                            |
+
+Al igual que `callAgent()`, la CLI usa de forma predeterminada async + poll (`invokeAgent` → `callAgent` internamente), que es la opción segura frente a destinos alojados/serverless — vea [Tiempos de espera de webhooks y gateways serverless](#json-rpc-methods) más arriba. Pase `--sync` solo cuando sepa que el destino no está detrás de un gateway con un límite de ejecución corto.
+
+El destino se resuelve de la misma manera que `agentNative.invoke()`: por ID de aplicación del espacio de trabajo, por nombre de aplicación, o por una URL completa — así que el mismo comando funciona contra una aplicación hermana en un espacio de trabajo multiaplicación o contra un par A2A arbitrario en otro lugar.
+
 ## Ciclo de vida de la tarea {#task-lifecycle}
 
 Cada mensaje crea una tarea que pasa por estos estados:

package/corpus/core/docs/content/locales/fr-FR/a2a-protocol.mdx

@@ -384,6 +384,48 @@ environnement d'application et transmettre l'identité de l'appelant (`userEmail
 signé en tant que jetons au porteur JWT. Utilisez `apiKeyEnv` uniquement pour les anciens homologues externes qui
 attendez-vous à un jeton de porteur statique. Utilisez actions local au lieu de vous invoquer.
 
+## CLI : agent-native invoke {#cli-invoke}
+
+`agent-native invoke` est un mince wrapper CLI au-dessus de la même primitive de résolution et d'appel que `agentNative.invoke()`. Utilisez-la pour déclencher l'agent d'une application depuis un script shell, un job CI, une entrée cron, ou tout système externe capable de lancer une commande shell — l'équivalent CLI d'un POST manuel vers `/_agent-native/a2a`.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# Résoudre "analytics" dans le registre de l'espace de travail et attendre la réponse
+agent-native invoke analytics "Summarize signups by source this month"
+
+# Appeler une application déployée directement par URL, en lisant le jeton au porteur depuis l'environnement
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# Forcer un seul message/send bloquant au lieu du mode async+poll par défaut
+agent-native invoke analytics "Quick lookup" --sync
+
+# Sortie exploitable par machine pour le scripting
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Description                                                                              |
+| ------------------------- | ---------------------------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | Agent cible (alias de l'argument positionnel `<app-or-url>`)                             |
+| `--message <text>`        | Prompt (alias de l'argument positionnel `"prompt"`)                                      |
+| `--api-key-env <name>`    | Lit le jeton au porteur depuis une variable d'environnement                              |
+| `--api-key <token>`       | Valeur du jeton au porteur, passée directement                                           |
+| `--context-id <id>`       | `contextId` A2A, pour poursuivre la conversation d'une tâche existante                   |
+| `--self-app-id <id>`      | Identifiant de l'application courante, utilisé pour éviter les auto-appels               |
+| `--self-url <url>`        | URL de l'application courante, utilisée pour éviter les auto-appels                      |
+| `--timeout-ms <n>`        | Délai d'expiration du polling asynchrone                                                 |
+| `--poll-interval-ms <n>`  | Intervalle de polling asynchrone                                                         |
+| `--sync`                  | Utilise une seule requête `message/send` bloquante au lieu du mode async+poll par défaut |
+| `--no-hint`               | Envoie le prompt tel quel, sans l'indice d'invocation inter-application                  |
+| `--json`                  | Affiche les métadonnées de la cible et le texte de la réponse au format JSON             |
+
+Comme `callAgent()`, la CLI utilise par défaut le mode async + poll (`invokeAgent` → `callAgent` en interne), ce qui est le choix sûr face à des cibles hébergées/serverless — voir [Délais d'expiration des webhooks et passerelles serverless](#json-rpc-methods) ci-dessus. Ne passez `--sync` que lorsque vous savez que la cible n'est pas derrière une passerelle avec une limite d'exécution courte.
+
+La cible se résout de la même manière que `agentNative.invoke()` : par identifiant d'application de l'espace de travail, par nom d'application, ou par une URL complète — la même commande fonctionne donc aussi bien contre une application sœur dans un espace de travail multi-applications que contre un pair A2A arbitraire ailleurs.
+
 ## Cycle de vie des tâches {#task-lifecycle}
 
 Chaque message crée une tâche qui passe par ces états :

package/corpus/core/docs/content/locales/hi-IN/a2a-protocol.mdx

@@ -384,6 +384,48 @@ dataset, or workflow. In production agent-native apps, set `A2A_SECRET` in each
 JWT वाहक टोकन के रूप में हस्ताक्षरित। `apiKeyEnv` का उपयोग केवल विरासती बाहरी समकक्षों के लिए करें
 एक स्थिर वाहक टोकन की अपेक्षा करें। स्वयं का आह्वान करने के बजाय स्थानीय actions का उपयोग करें।
 
+## सीएलआई: agent-native invoke {#cli-invoke}
+
+`agent-native invoke`, `agentNative.invoke()` के समान resolve-and-call primitive पर एक हल्का CLI wrapper है। इसका उपयोग किसी शेल स्क्रिप्ट, CI job, cron entry, या किसी भी बाहरी सिस्टम से किसी ऐप के एजेंट को ट्रिगर करने के लिए करें जो shell out कर सकता है — यह हाथ से `/_agent-native/a2a` पर पोस्ट करने के बराबर है।
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# वर्कस्पेस रजिस्ट्री में "analytics" को resolve करें और जवाब की प्रतीक्षा करें
+agent-native invoke analytics "Summarize signups by source this month"
+
+# किसी डिप्लॉय किए गए ऐप को सीधे URL से कॉल करें, bearer token env से पढ़ते हुए
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# डिफ़ॉल्ट async+poll के बजाय एक ब्लॉकिंग message/send को बाध्य करें
+agent-native invoke analytics "Quick lookup" --sync
+
+# स्क्रिप्टिंग के लिए मशीन-रीडेबल आउटपुट
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | विवरण                                                                        |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | लक्ष्य एजेंट (positional `<app-or-url>` का alias)                            |
+| `--message <text>`        | प्रॉम्प्ट (positional `"prompt"` का alias)                                   |
+| `--api-key-env <name>`    | एक environment variable से bearer token पढ़ें                                |
+| `--api-key <token>`       | Bearer token मान, inline पास किया गया                                        |
+| `--context-id <id>`       | A2A `contextId`, किसी मौजूदा task की बातचीत जारी रखने के लिए                 |
+| `--self-app-id <id>`      | वर्तमान app id, self-call रोकथाम के लिए उपयोग की जाती है                     |
+| `--self-url <url>`        | वर्तमान app URL, self-call रोकथाम के लिए उपयोग की जाती है                    |
+| `--timeout-ms <n>`        | Async polling timeout                                                        |
+| `--poll-interval-ms <n>`  | Async polling interval                                                       |
+| `--sync`                  | डिफ़ॉल्ट async+poll के बजाय एक blocking `message/send` request का उपयोग करें |
+| `--no-hint`               | प्रॉम्प्ट को cross-app invocation hint के बिना, ज्यों का त्यों भेजें         |
+| `--json`                  | Target metadata और response text को JSON के रूप में प्रिंट करें              |
+
+`callAgent()` की तरह, CLI डिफ़ॉल्ट रूप से async + poll (`invokeAgent` → अंदरूनी रूप से `callAgent`) का उपयोग करती है, जो hosted/serverless targets के विरुद्ध सुरक्षित विकल्प है — ऊपर [Serverless webhook and gateway timeouts](#json-rpc-methods) देखें। `--sync` का उपयोग तभी करें जब आप जानते हों कि लक्ष्य किसी छोटी execution limit वाले gateway के पीछे नहीं है।
+
+लक्ष्य वैसे ही resolve होता है जैसे `agentNative.invoke()` में होता है: workspace app id से, app name से, या पूरे URL से — इसलिए यही कमांड एक multi-app workspace में किसी sibling app के विरुद्ध या कहीं और किसी मनमाने A2A peer के विरुद्ध भी काम करता है।
+
 ## कार्य जीवनचक्र {#task-lifecycle}
 
 प्रत्येक संदेश एक कार्य बनाता है जो इन स्थितियों से होकर गुजरता है:

package/corpus/core/docs/content/locales/ja-JP/a2a-protocol.mdx

@@ -384,6 +384,48 @@ console.log(`Called ${result.target.name}: ${result.responseText}`);
 JWT ベアラー トークンとして署名されています。 `apiKeyEnv` は、
 静的なベアラー トークンが必要です。自分自身を呼び出す代わりに、ローカルの actions を使用してください。
 
+## CLI: agent-native invoke {#cli-invoke}
+
+`agent-native invoke` は、`agentNative.invoke()` と同じ解決・呼び出しプリミティブを薄くラップした CLI です。シェル スクリプト、CI ジョブ、cron エントリ、またはシェルアウトできる任意の外部システムからアプリのエージェントをトリガーするために使用します。手動で `/_agent-native/a2a` に POST するのと同等の CLI 版です。
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# ワークスペース レジストリで "analytics" を解決し、応答を待つ
+agent-native invoke analytics "Summarize signups by source this month"
+
+# デプロイ済みアプリを URL で直接呼び出し、環境変数からベアラー トークンを読み取る
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# デフォルトの async+poll の代わりに、ブロッキングの message/send を1回だけ強制する
+agent-native invoke analytics "Quick lookup" --sync
+
+# スクリプト用の機械可読な出力
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Description                                                                         |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | 対象のエージェント（位置引数 `<app-or-url>` のエイリアス）                          |
+| `--message <text>`        | プロンプト（位置引数 `"prompt"` のエイリアス）                                      |
+| `--api-key-env <name>`    | 環境変数からベアラー トークンを読み取る                                             |
+| `--api-key <token>`       | ベアラー トークンの値をインラインで渡す                                             |
+| `--context-id <id>`       | A2A の `contextId`。既存タスクの会話を継続するために使用                            |
+| `--self-app-id <id>`      | 自己呼び出し防止に使われる、現在のアプリ id                                         |
+| `--self-url <url>`        | 自己呼び出し防止に使われる、現在のアプリ URL                                        |
+| `--timeout-ms <n>`        | 非同期ポーリングのタイムアウト                                                      |
+| `--poll-interval-ms <n>`  | 非同期ポーリングの間隔                                                              |
+| `--sync`                  | デフォルトの async+poll の代わりに、ブロッキングの `message/send` を1回だけ使用する |
+| `--no-hint`               | クロスアプリ呼び出しのヒントを付けずに、プロンプトをそのまま送信する                |
+| `--json`                  | ターゲットのメタデータと応答テキストを JSON として出力する                          |
+
+`callAgent()` と同様に、この CLI もデフォルトで async + poll を使用します（内部的には `invokeAgent` → `callAgent`）。これはホスト型/サーバーレスのターゲットに対して安全な選択です。上記の [サーバーレスの Webhook とゲートウェイのタイムアウト](#json-rpc-methods) を参照してください。ターゲットが短い実行時間制限のあるゲートウェイの背後にないとわかっている場合にのみ `--sync` を渡してください。
+
+ターゲットは `agentNative.invoke()` と同じ方法で解決されます: ワークスペースのアプリ id、アプリ名、または完全な URL のいずれかです。そのため、同じコマンドがマルチアプリ ワークスペース内の兄弟アプリに対しても、どこか別の場所にある任意の A2A ピアに対しても機能します。
+
 ## タスクのライフサイクル {#task-lifecycle}
 
 各メッセージは、次の状態を通過するタスクを作成します。

package/corpus/core/docs/content/locales/ko-KR/a2a-protocol.mdx

@@ -384,6 +384,48 @@ console.log(`Called ${result.target.name}: ${result.responseText}`);
 JWT 전달자 토큰으로 서명되었습니다. 다음과 같은 레거시 외부 피어에만 `apiKeyEnv`를 사용하세요.
 정적 전달자 토큰이 필요합니다. 자신을 호출하는 대신 로컬 actions를 사용하세요.
 
+## CLI: agent-native invoke {#cli-invoke}
+
+`agent-native invoke`는 `agentNative.invoke()`와 동일한 확인 후 호출(resolve-and-call) 기본 로직을 감싼 얇은 CLI 래퍼입니다. 셸 스크립트, CI 작업, cron 항목, 또는 셸 아웃이 가능한 다른 외부 시스템에서 앱의 에이전트를 트리거할 때 사용하세요 — `/_agent-native/a2a`에 직접 POST하는 것과 동일한 CLI 방식입니다.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# 작업공간 레지스트리에서 "analytics"를 확인하고 응답을 기다립니다
+agent-native invoke analytics "Summarize signups by source this month"
+
+# 배포된 앱을 URL로 직접 호출하고, 환경 변수에서 전달자 토큰을 읽습니다
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# 기본값인 async+poll 대신 블로킹 message/send 하나만 강제로 사용합니다
+agent-native invoke analytics "Quick lookup" --sync
+
+# 스크립팅을 위한 기계 판독 가능한 출력
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| 옵션                      | 설명                                                                  |
+| ------------------------- | --------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | 대상 에이전트 (위치 인수 `<app-or-url>`의 별칭)                       |
+| `--message <text>`        | 프롬프트 (위치 인수 `"prompt"`의 별칭)                                |
+| `--api-key-env <name>`    | 환경 변수에서 전달자 토큰을 읽습니다                                  |
+| `--api-key <token>`       | 전달자 토큰 값을 인라인으로 전달합니다                                |
+| `--context-id <id>`       | 기존 작업의 대화를 이어가기 위한 A2A `contextId`                      |
+| `--self-app-id <id>`      | 자체 호출 방지에 사용되는 현재 앱 id                                  |
+| `--self-url <url>`        | 자체 호출 방지에 사용되는 현재 앱 URL                                 |
+| `--timeout-ms <n>`        | 비동기 폴링 타임아웃                                                  |
+| `--poll-interval-ms <n>`  | 비동기 폴링 간격                                                      |
+| `--sync`                  | 기본값인 async+poll 대신 블로킹 `message/send` 요청 하나를 사용합니다 |
+| `--no-hint`               | 크로스 앱 호출 힌트 없이 프롬프트를 그대로 전송합니다                 |
+| `--json`                  | 대상 메타데이터와 응답 텍스트를 JSON으로 출력합니다                   |
+
+`callAgent()`와 마찬가지로 CLI는 기본적으로 async + poll을 사용하며(내부적으로 `invokeAgent` → `callAgent`), 이는 호스팅/서버리스 대상에 대한 안전한 선택입니다 — 위의 [서버리스 웹훅 및 게이트웨이 타임아웃](#json-rpc-methods)을 참조하세요. 대상이 짧은 실행 제한이 있는 게이트웨이 뒤에 있지 않다는 것을 알 때만 `--sync`를 전달하세요.
+
+대상은 `agentNative.invoke()`와 동일한 방식으로 확인됩니다. 작업공간 앱 id, 앱 이름, 또는 전체 URL로 확인되므로 동일한 명령이 멀티 앱 작업공간의 형제 앱이나 다른 곳의 임의의 A2A 피어 모두에 대해 작동합니다.
+
 ## 작업 수명 주기 {#task-lifecycle}
 
 각 메시지는 다음 상태를 거쳐 이동하는 작업을 생성합니다.

package/corpus/core/docs/content/locales/pt-BR/a2a-protocol.mdx

@@ -386,6 +386,48 @@ ambiente do aplicativo e passe a identidade do chamador (`userEmail`) para que a
 assinado como tokens ao portador JWT. Use `apiKeyEnv` apenas para pares externos legados que
 espera um token de portador estático. Use actions local em vez de invocar você mesmo.
 
+## CLI: agent-native invoke {#cli-invoke}
+
+`agent-native invoke` é um wrapper de CLI simples sobre a mesma primitiva de resolver-e-chamar usada por `agentNative.invoke()`. Use-o para acionar o agente de um aplicativo a partir de um script de shell, um job de CI, uma entrada de cron ou qualquer sistema externo que possa executar comandos de shell — o equivalente em CLI de postar manualmente em `/_agent-native/a2a`.
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# Resolve "analytics" no registro do espaço de trabalho e aguarda a resposta
+agent-native invoke analytics "Summarize signups by source this month"
+
+# Chama um aplicativo implantado diretamente por URL, lendo o token de portador a partir de uma variável de ambiente
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# Força uma única mensagem/envio bloqueante em vez do padrão assíncrono+polling
+agent-native invoke analytics "Quick lookup" --sync
+
+# Saída legível por máquina para uso em scripts
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Description                                                                            |
+| ------------------------- | -------------------------------------------------------------------------------------- |
+| `--agent <id\|name\|url>` | Agente de destino (alias para o argumento posicional `<app-or-url>`)                   |
+| `--message <text>`        | Prompt (alias para o argumento posicional `"prompt"`)                                  |
+| `--api-key-env <name>`    | Lê o token de portador a partir de uma variável de ambiente                            |
+| `--api-key <token>`       | Valor do token de portador, passado diretamente                                        |
+| `--context-id <id>`       | `contextId` do A2A, para continuar a conversa de uma tarefa existente                  |
+| `--self-app-id <id>`      | ID do aplicativo atual, usado para evitar autochamadas                                 |
+| `--self-url <url>`        | URL do aplicativo atual, usada para evitar autochamadas                                |
+| `--timeout-ms <n>`        | Tempo limite do polling assíncrono                                                     |
+| `--poll-interval-ms <n>`  | Intervalo do polling assíncrono                                                        |
+| `--sync`                  | Usa uma única requisição `message/send` bloqueante em vez do padrão assíncrono+polling |
+| `--no-hint`               | Envia o prompt como está, sem a dica de invocação entre aplicativos                    |
+| `--json`                  | Imprime os metadados do destino e o texto da resposta como JSON                        |
+
+Assim como `callAgent()`, a CLI usa por padrão o modo assíncrono + polling (`invokeAgent` → `callAgent` internamente), que é a escolha segura contra destinos hospedados/serverless — veja [Tempos limite de webhook e gateway serverless](#json-rpc-methods) acima. Passe `--sync` somente quando você souber que o destino não está atrás de um gateway com um limite de execução curto.
+
+O destino é resolvido da mesma forma que em `agentNative.invoke()`: pelo ID do aplicativo no espaço de trabalho, pelo nome do aplicativo ou por uma URL completa — assim, o mesmo comando funciona tanto contra um aplicativo irmão em um espaço de trabalho com múltiplos aplicativos quanto contra um par A2A arbitrário em outro lugar.
+
 ## Ciclo de vida da tarefa {#task-lifecycle}
 
 Cada mensagem cria uma tarefa que passa por estes estados:

package/corpus/core/docs/content/locales/zh-CN/a2a-protocol.mdx

@@ -384,6 +384,48 @@ console.log(`Called ${result.target.name}: ${result.responseText}`);
 签名为 JWT 不记名代币。仅将 `apiKeyEnv` 用于旧版外部对等点
 需要静态不记名令牌。使用本地actions而不是自己调用。
 
+## CLI：agent-native invoke {#cli-invoke}
+
+`agent-native invoke` 是对与 `agentNative.invoke()` 相同的解析并调用原语的一层轻量 CLI 包装。用它可以从 shell 脚本、CI 任务、cron 条目或任何能够执行 shell 命令的外部系统触发某个应用的代理——相当于手动向 `/_agent-native/a2a` 发送 POST 请求的命令行等价形式。
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# 在工作区注册表中解析 "analytics" 并等待回复
+agent-native invoke analytics "Summarize signups by source this month"
+
+# 通过 URL 直接调用一个已部署的应用，从环境变量中读取 bearer token
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# 强制使用一次阻塞式 message/send，而不是默认的异步+轮询方式
+agent-native invoke analytics "Quick lookup" --sync
+
+# 输出机器可读的结果，便于脚本处理
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| Option                    | Description                                                 |
+| ------------------------- | ----------------------------------------------------------- |
+| `--agent <id\|name\|url>` | 目标代理（是位置参数 `<app-or-url>` 的别名）                |
+| `--message <text>`        | 提示词（是位置参数 `"prompt"` 的别名）                      |
+| `--api-key-env <name>`    | 从环境变量中读取 bearer token                               |
+| `--api-key <token>`       | 直接内联传入的 bearer token 值                              |
+| `--context-id <id>`       | A2A 的 `contextId`，用于延续已有任务的对话                  |
+| `--self-app-id <id>`      | 当前应用 id，用于防止自我调用                               |
+| `--self-url <url>`        | 当前应用 URL，用于防止自我调用                              |
+| `--timeout-ms <n>`        | 异步轮询超时时间                                            |
+| `--poll-interval-ms <n>`  | 异步轮询间隔                                                |
+| `--sync`                  | 使用一次阻塞式 `message/send` 请求，而非默认的异步+轮询方式 |
+| `--no-hint`               | 原样发送提示词，不附加跨应用调用提示                        |
+| `--json`                  | 以 JSON 形式打印目标元数据和响应文本                        |
+
+与 `callAgent()` 一样，该 CLI 默认使用异步+轮询方式（底层是 `invokeAgent` → `callAgent`），这是针对托管/无服务器目标的安全选择——参见上文的[无服务器 webhook 与网关超时](#json-rpc-methods)。只有在确定目标不在执行时间受限的网关之后时，才传入 `--sync`。
+
+目标的解析方式与 `agentNative.invoke()` 相同：通过工作区应用 id、应用名称，或完整 URL——因此同一条命令既适用于多应用工作区中的同级应用，也适用于其他地方任意的 A2A 对等端。
+
 ## 任务生命周期 {#task-lifecycle}
 
 每条消息都会创建一个在以下状态之间移动的任务：

package/corpus/core/docs/content/locales/zh-TW/a2a-protocol.mdx

@@ -384,6 +384,48 @@ console.log(`Called ${result.target.name}: ${result.responseText}`);
 簽名為 JWT 不記名代幣。僅將 `apiKeyEnv` 用於舊版外部對等點
 需要靜態不記名權杖。使用本機actions而不是自己呼叫。
 
+## CLI：agent-native invoke {#cli-invoke}
+
+`agent-native invoke` 是一個薄的 CLI 包裝器，架構在與 `agentNative.invoke()` 相同的解析並呼叫的基本操作之上。使用它可以從 shell 腳本、CI 工作、cron 項目，或任何可以執行外部指令的系統觸發應用程式的代理——相當於手動向 `/_agent-native/a2a` 發送 POST 請求的 CLI 版本。
+
+```bash
+agent-native invoke <app-or-url> "prompt" [options]
+```
+
+```bash
+# 在工作區註冊表中解析 "analytics" 並等待回覆
+agent-native invoke analytics "Summarize signups by source this month"
+
+# 直接透過 URL 呼叫已部署的應用程式，從環境變數讀取不記名權杖
+agent-native invoke https://analytics.example.com "How many signups last week?" \
+  --api-key-env ANALYTICS_A2A_KEY
+
+# 強制使用一次阻塞式 message/send，而非預設的非同步+輪詢
+agent-native invoke analytics "Quick lookup" --sync
+
+# 為腳本編寫提供機器可讀輸出
+agent-native invoke analytics "Summarize signups" --json
+```
+
+| 選項                      | 描述                                                      |
+| ------------------------- | --------------------------------------------------------- |
+| `--agent <id\|name\|url>` | 目標代理（位置參數 `<app-or-url>` 的別名）                |
+| `--message <text>`        | 提示（位置參數 `"prompt"` 的別名）                        |
+| `--api-key-env <name>`    | 從環境變數讀取不記名權杖                                  |
+| `--api-key <token>`       | 直接內嵌傳入的不記名權杖值                                |
+| `--context-id <id>`       | A2A `contextId`，用於延續現有工作的對話                   |
+| `--self-app-id <id>`      | 目前應用程式 ID，用於防止自我呼叫                         |
+| `--self-url <url>`        | 目前應用程式 URL，用於防止自我呼叫                        |
+| `--timeout-ms <n>`        | 非同步輪詢逾時時間                                        |
+| `--poll-interval-ms <n>`  | 非同步輪詢間隔                                            |
+| `--sync`                  | 使用一次阻塞式 `message/send` 請求，取代預設的非同步+輪詢 |
+| `--no-hint`               | 按原樣傳送提示，不加入跨應用程式呼叫提示                  |
+| `--json`                  | 以 JSON 格式輸出目標中繼資料與回應文字                    |
+
+與 `callAgent()` 一樣，此 CLI 預設使用非同步+輪詢（底層是 `invokeAgent` → `callAgent`），這是針對託管/無伺服器目標的安全選擇——請參閱上方的[無伺服器 webhook 與閘道逾時](#json-rpc-methods)。只有在確定目標不在具有短執行限制的閘道之後時，才傳入 `--sync`。
+
+目標的解析方式與 `agentNative.invoke()` 相同：透過工作區應用程式 ID、應用程式名稱，或完整 URL——因此同一指令在多應用程式工作區中的同級應用程式，或其他地方的任意 A2A 對等點上都能運作。
+
 ## 工作生命週期 {#task-lifecycle}
 
 每條訊息都會建立一個在以下狀態之間移動的工作：

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.99.1",
+  "version": "0.99.3",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {