feat(core): add request-scoped action surfaces

.changeset/request-action-surfaces.md

@@ -0,0 +1,5 @@
+---
+"@agent-native/core": minor
+---
+
+Add request-scoped action allowlists for interactive agent chat.

packages/core/docs/content/agent-surfaces.mdx

@@ -167,6 +167,36 @@ React widget, use [Generative UI](/docs/generative-ui): it renders sandboxed
 Alpine/Tailwind UI inline, can read app state and slot context, and can send
 selected values back to chat.
 
+### Request-scoped action surfaces
+
+Use `resolveActionSurface` when the selected agent or thread must expose only a
+server-authorized subset of native actions. The callback runs for every
+interactive chat request after `prepareRequest`. Returned names form a hard
+allowlist for that request: omitted actions are absent from provider schemas,
+the execution registry, plan-mode preloading, and `tool-search` discovery.
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+An empty list exposes no native actions. Unknown names fail the request instead
+of widening access. Every allowed action is loaded directly on the first model
+request; include `tool-search` explicitly only when discovery inside the
+already-authorized catalog is wanted. The callback scopes interactive agent
+chat only—it does not change HTTP, MCP, A2A, job, or trigger exposure. Default
+framework guidance and spawned sub-agents inherit the same surface. Trusted
+shell tools are automatically reduced to the request-filtered sandbox because
+an unrestricted shell cannot enforce a hard action boundary.
+
 ## Native inline UI {#native-inline-ui}
 
 Use this when your actions return structured data — a list of records, a chart dataset, a status summary — that should render as a real UI component inside the chat thread rather than a plain text description. You define a `chatUI` renderer on the action, and Agent-Native renders it as a first-party React component: no iframes, no separate rendering path.

packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx

@@ -166,6 +166,35 @@ React محدد مسبقًا، استخدم [واجهة المستخدم التو
 Alpine/Tailwind المحمية مضمّنةً، ويمكنها قراءة حالة التطبيق وسياق الفتحة، وإرسال
 القيم المحددة مرة أخرى إلى المحادثة.
 
+### واجهات إجراءات على مستوى الطلب
+
+استخدم `resolveActionSurface` عندما يجب أن يعرض الوكيل أو سلسلة المحادثة
+المحددة مجموعة فرعية فقط من الإجراءات الأصلية التي اعتمدها الخادم. يُشغّل
+الاستدعاء لكل طلب محادثة تفاعلي بعد `prepareRequest`. تشكّل الأسماء المعادة
+قائمة سماح صارمة: لا تظهر الإجراءات المحذوفة في مخططات المزوّد أو سجل التنفيذ
+أو التحميل المسبق لوضع Plan أو نتائج بحث `tool-search`.
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+لا تعرض القائمة الفارغة أي إجراءات أصلية. تؤدي الأسماء غير المعروفة إلى فشل
+الطلب بدلاً من توسيع الوصول. تُحمّل جميع الإجراءات المسموح بها مباشرة في أول
+طلب للنموذج؛ أضف `tool-search` صراحةً فقط للبحث داخل الفهرس المعتمد مسبقاً.
+يقيّد الاستدعاء محادثة الوكيل التفاعلية فقط ولا يغيّر HTTP أو MCP أو A2A أو
+المهام أو المشغلات. ترث إرشادات الإطار الافتراضية والوكلاء الفرعيون المشغّلون
+السطح نفسه. تُخفّض أدوات shell الموثوقة تلقائياً إلى sandbox المصفّى حسب الطلب،
+لأن shell غير المقيّد لا يمكنه فرض حد صارم للإجراءات.
+
 ## واجهة مستخدم مضمّنة أصلية {#native-inline-ui}
 
 استخدم هذا عندما تُرجع إجراءاتك بيانات منظمة — قائمة سجلات، أو مجموعة بيانات مخطط، أو ملخص حالة — يجب أن تُعرض كمكوّن واجهة مستخدم حقيقي داخل خيط المحادثة بدلاً من وصف نصي بسيط. تُعرّف مُصيِّر `chatUI` على الإجراء، ويُعرضه Agent-Native كمكوّن React من الدرجة الأولى: بدون iframes، بدون مسار عرض منفصل.

packages/core/docs/content/locales/de-DE/agent-surfaces.mdx

@@ -168,6 +168,39 @@ React-Widgets benötigt, verwenden Sie [Generative UI](/docs/generative-ui): Es
 Alpine/Tailwind-UI inline, kann App-Zustand und Slot-Kontext lesen und ausgewählte Werte an den Chat
 zurückschicken.
 
+### Request-bezogene Action-Oberflächen
+
+Verwende `resolveActionSurface`, wenn der ausgewählte Agent oder Thread nur
+eine serverseitig autorisierte Teilmenge nativer Actions sehen darf. Der
+Callback läuft für jede interaktive Chat-Anfrage nach `prepareRequest`. Die
+zurückgegebenen Namen bilden eine harte Allowlist: Nicht enthaltene Actions
+fehlen in Provider-Schemas, Ausführungs-Registry, Plan-Modus-Vorladung und der
+Suche über `tool-search`.
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+Eine leere Liste stellt keine nativen Actions bereit. Unbekannte Namen lassen
+die Anfrage fehlschlagen, statt den Zugriff zu erweitern. Alle erlaubten
+Actions werden direkt mit der ersten Modellanfrage geladen; `tool-search` wird
+nur ausdrücklich hinzugefügt, wenn Suche innerhalb des bereits autorisierten
+Katalogs gewünscht ist. Der Callback begrenzt ausschließlich den interaktiven
+Agentenchat, nicht HTTP, MCP, A2A, Jobs oder Trigger. In der lokalen Entwicklung
+übernehmen Standard-Framework-Hinweise und gestartete Sub-Agenten dieselbe
+Oberfläche. Vertrauenswürdige Shell-Tools werden automatisch auf die
+anfragegefilterte Sandbox reduziert, da eine unbeschränkte Shell keine harte
+Action-Grenze durchsetzen kann.
+
 ## Native Inline-UI {#native-inline-ui}
 
 Verwenden Sie diese, wenn Ihre Aktionen strukturierte Daten zurückgeben — eine Liste von Einträgen, einen Diagramm-Datensatz, eine Statuszusammenfassung — die als echte UI-Komponente im Chat-Thread gerendert werden sollen, anstatt als reine Textbeschreibung. Sie definieren einen `chatUI`-Renderer auf der Aktion, und Agent-Native rendert ihn als First-Party-React-Komponente: keine iFrames, kein separater Rendering-Pfad.

packages/core/docs/content/locales/es-ES/agent-surfaces.mdx

@@ -170,6 +170,39 @@ widget React predefinido, usa [Generative UI](/docs/generative-ui): renderiza in
 aislada en línea, puede leer el estado de la aplicación y el contexto del slot, y puede enviar
 los valores seleccionados de vuelta al chat.
 
+### Superficies de acciones por solicitud
+
+Usa `resolveActionSurface` cuando el agente o hilo seleccionado deba exponer
+solo un subconjunto de acciones nativas autorizado por el servidor. El callback
+se ejecuta en cada solicitud de chat interactivo después de `prepareRequest`.
+Los nombres devueltos forman una lista permitida estricta: las acciones omitidas
+no aparecen en los esquemas del proveedor, el registro de ejecución, la
+precarga del modo Plan ni la búsqueda de `tool-search`.
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+Una lista vacía no expone acciones nativas. Los nombres desconocidos hacen
+fallar la solicitud en vez de ampliar el acceso. Todas las acciones permitidas
+se cargan directamente en la primera solicitud al modelo; incluye
+`tool-search` de forma explícita solo si deseas descubrir herramientas dentro
+del catálogo ya autorizado. El callback solo limita el chat interactivo, no
+HTTP, MCP, A2A, jobs ni triggers. En desarrollo local, usa acciones nativas y
+las instrucciones predeterminadas del framework y los subagentes iniciados
+heredan la misma superficie. Las herramientas shell de confianza se reducen
+automáticamente al sandbox filtrado por solicitud, porque una shell sin
+restricciones no puede imponer una frontera estricta de acciones.
+
 ## Interfaz de usuario nativa integrada {#native-inline-ui}
 
 Úsala cuando tus acciones devuelvan datos estructurados — una lista de registros, un conjunto de datos de gráfico, un resumen de estado — que deban renderizarse como un componente de interfaz de usuario real dentro del hilo de chat en lugar de una descripción de texto simple. Defines un renderizador `chatUI` en la acción, y Agent-Native lo renderiza como un componente React de primera clase: sin iframes, sin ruta de renderizado separada.

packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx

@@ -169,6 +169,38 @@ widget React prédéfini, utilisez [Generative UI](/docs/generative-ui) : il aff
 dans un bac à sable intégré, peut lire l'état de l'application et le contexte de l'emplacement, et peut renvoyer
 les valeurs sélectionnées vers le chat.
 
+### Surfaces d’actions limitées à la requête
+
+Utilisez `resolveActionSurface` lorsque l’agent ou le fil sélectionné ne doit
+exposer qu’un sous-ensemble d’actions natives autorisé par le serveur. Le
+callback s’exécute pour chaque requête de chat interactif après
+`prepareRequest`. Les noms retournés forment une liste d’autorisation stricte :
+les actions omises sont absentes des schémas du fournisseur, du registre
+d’exécution, du préchargement du mode Plan et de la recherche `tool-search`.
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+Une liste vide n’expose aucune action native. Un nom inconnu fait échouer la
+requête au lieu d’élargir l’accès. Toutes les actions autorisées sont chargées
+dès la première requête au modèle ; ajoutez explicitement `tool-search`
+uniquement pour rechercher dans le catalogue déjà autorisé. Le callback limite
+seulement le chat interactif, pas HTTP, MCP, A2A, les jobs ou les triggers. En
+outre, les consignes par défaut du framework et les sous-agents lancés héritent
+de la même surface. Les outils shell de confiance sont automatiquement ramenés
+au bac à sable filtré par requête, car un shell sans restriction ne peut pas
+appliquer une frontière d’actions stricte.
+
 ## Interface utilisateur native intégrée {#native-inline-ui}
 
 Utilisez cette surface lorsque vos actions renvoient des données structurées — une liste d'enregistrements, un jeu de données de graphique, un résumé d'état — qui doivent s'afficher en tant que vrai composant d'interface dans le fil de chat plutôt qu'une simple description textuelle. Vous définissez un renderer `chatUI` sur l'action, et Agent-Native l'affiche en tant que composant React de premier niveau : pas d'iframe, pas de chemin de rendu séparé.

packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx

@@ -156,6 +156,36 @@ export function ProjectChat({ threadId }: { threadId: string }) {
 
 Actions स्पष्ट native widget results वापस कर सकते हैं ताकि chat आउटपुट केवल टेक्स्ट न हो। Tables, charts, और typed product cards iframes के बिना chat में first-party React components के रूप में रेंडर होते हैं। [Native Chat UI](/docs/native-chat-ui) देखें। जब एजेंट को पूर्वनिर्धारित React widget के बजाय arbitrary generated controls की आवश्यकता हो, तो [Generative UI](/docs/generative-ui) का उपयोग करें: यह sandboxed Alpine/Tailwind UI इनलाइन रेंडर करता है, app state और slot context पढ़ सकता है, और चुने गए values को chat में वापस भेज सकता है।
 
+### अनुरोध-स्कोप वाली action surfaces
+
+जब चुने गए Agent या thread को केवल server द्वारा अधिकृत native actions का
+subset दिखाना हो, तब `resolveActionSurface` का उपयोग करें। callback हर
+interactive chat request पर `prepareRequest` के बाद चलता है। लौटाए गए नाम एक
+सख्त allowlist बनाते हैं: छोड़े गए actions provider schemas, execution
+registry, Plan mode preload और `tool-search` खोज में उपलब्ध नहीं होते।
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+खाली सूची कोई native action उपलब्ध नहीं कराती। अज्ञात नाम access बढ़ाने के
+बजाय request को fail करते हैं। सभी अनुमत actions पहली model request पर सीधे
+लोड होते हैं; पहले से अधिकृत catalog में खोज चाहिए तभी `tool-search` को साफ़
+तौर पर शामिल करें। callback केवल interactive Agent chat को सीमित करता है,
+HTTP, MCP, A2A, jobs या triggers को नहीं। default framework guidance और शुरू
+किए गए sub-agents वही surface inherit करते हैं। trusted shell tools अपने-आप
+request-filtered sandbox तक सीमित हो जाते हैं, क्योंकि unrestricted shell
+सख्त action boundary लागू नहीं कर सकता।
+
 ## Native inline UI {#native-inline-ui}
 
 इसका उपयोग तब करें जब आपके actions structured data वापस करते हैं — records की एक list, एक chart dataset, एक status summary — जो plain text विवरण के बजाय chat thread के अंदर एक वास्तविक UI component के रूप में रेंडर होनी चाहिए। आप action पर एक `chatUI` renderer परिभाषित करते हैं, और Agent-Native इसे एक first-party React component के रूप में रेंडर करता है: कोई iframes नहीं, कोई अलग rendering path नहीं।

packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx

@@ -158,6 +158,38 @@ export function ProjectChat({ threadId }: { threadId: string }) {
 
 アクションは明示的なネイティブウィジェット結果を返せるため、チャットの出力はテキストだけではありません。テーブル、チャート、型付きプロダクトカードは、iframeなしでチャット内のファーストパーティReactコンポーネントとしてレンダリングされます。[Native Chat UI](/docs/native-chat-ui) を参照してください。エージェントが事前定義されたReactウィジェットの代わりに任意の生成コントロールを必要とする場合は、[Generative UI](/docs/generative-ui) を使用してください。これはサンドボックス化されたAlpine/Tailwind UIをインラインでレンダリングし、アプリの状態とスロットコンテキストを読み取り、選択した値をチャットに送り返すことができます。
 
+### リクエスト単位のアクションサーフェス
+
+選択されたエージェントまたはスレッドに、サーバーで承認された
+ネイティブアクションだけを公開する場合は `resolveActionSurface` を
+使用します。コールバックは各インタラクティブチャットリクエストで
+`prepareRequest` の後に実行されます。返された名前が厳格な許可リストに
+なり、省略されたアクションはプロバイダースキーマ、実行レジストリ、
+Plan モードのプリロード、`tool-search` の検索結果に含まれません。
+
+```ts
+createAgentChatPlugin({
+  actions,
+  nativeActionsInDev: true,
+  resolveActionSurface: async ({ threadId, availableActionNames }) => ({
+    allowedActionNames: await loadAllowedActions(
+      threadId,
+      availableActionNames,
+    ),
+  }),
+});
+```
+
+空のリストではネイティブアクションは公開されません。不明な名前は
+アクセスを広げず、リクエストを失敗させます。許可されたアクションは
+最初のモデルリクエストですべて直接読み込まれます。承認済みカタログ内で
+検索したい場合だけ `tool-search` を明示的に追加してください。この
+コールバックが制限するのはインタラクティブチャットだけで、HTTP、MCP、
+A2A、ジョブ、トリガーには影響しません。既定のフレームワークガイダンスと
+起動したサブエージェントも同じサーフェスを継承します。無制限の shell では
+厳格なアクション境界を強制できないため、trusted shell ツールはリクエストで
+フィルタされた sandbox に自動的に制限されます。
+
 ## ネイティブインラインUI {#native-inline-ui}
 
 アクションが構造化データ（レコードのリスト、チャートデータセット、ステータスサマリーなど）を返し、プレーンテキストの説明ではなく、チャットスレッド内の実際のUIコンポーネントとしてレンダリングする必要がある場合に使用してください。アクションに `chatUI` レンダラーを定義すると、Agent-Native はそれをファーストパーティのReactコンポーネントとしてレンダリングします。iframeも別のレンダリングパスも不要です。