@agent-native/core 0.92.2 → 0.92.4

package/docs/content/locales/es-ES/server.mdx

@@ -129,6 +129,41 @@ Si tanto el UI como el agente necesitan hacer algo, defina una acción en lugar
 
 Utilice rutas `/api/*` personalizadas solo cuando necesite un protocolo en forma de ruta o un comportamiento binario/de transmisión. Ver [Actions](/docs/actions).
 
+### Aplicaciones solo API {#api-only-apps}
+
+No necesita un servidor Express solo porque la aplicación sea solo API. Una aplicación Agent Native ya incluye un servidor Nitro/H3, y `defineAction()` es la superficie API predeterminada. Defina las operaciones en `actions/`; el marco monta cada action en `/_agent-native/actions/<name>` con validación de esquema y contexto de solicitud.
+
+Use la opción `http` de la action para dar forma al acceso HTTP directo: las actions son `POST` de forma predeterminada, `http: { method: "GET" | "PUT" | "DELETE" }` cambia el verbo, y `http: false` deja una action fuera de HTTP. Use `server/routes/api/*` solo para necesidades con forma de ruta o protocolo: cargas de archivos, streaming/SSE, webhooks, devoluciones de llamada OAuth, páginas públicas o una forma REST externa que no pueda representarse limpiamente como una action. No cree rutas `/api/*` que principalmente envuelvan o reexporten actions.
+
+Para un endpoint de estado de solo lectura, manténgalo como una action:
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+Llámela directamente por HTTP:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+Para `POST` y otras actions de escritura, envíe un cuerpo JSON al mismo path de la action.
+
 ## Completación de texto de una sola vez {#complete-text}
 
 La mayor parte del trabajo de IA debe realizarse a través del chat del agente para que los usuarios puedan verlo, dirigirlo y auditarlo

package/docs/content/locales/fr-FR/server.mdx

@@ -129,6 +129,41 @@ Si le UI et l'agent doivent tous deux faire quelque chose, définissez une actio
 
 Utilisez des routes `/api/*` personnalisées uniquement lorsque vous avez besoin d'un protocole en forme de route ou d'un comportement binaire/streaming. Voir [Actions](/docs/actions).
 
+### Applications API uniquement {#api-only-apps}
+
+Vous n'avez pas besoin d'un serveur Express simplement parce que l'application expose uniquement une API. Une application Agent Native inclut déjà un serveur Nitro/H3, et `defineAction()` est la surface API par défaut. Définissez les opérations dans `actions/` ; le framework monte chaque action sur `/_agent-native/actions/<name>` avec validation de schéma et contexte de requête.
+
+Utilisez l'option `http` de l'action pour façonner l'accès HTTP direct : les actions sont en `POST` par défaut, `http: { method: "GET" | "PUT" | "DELETE" }` change le verbe, et `http: false` désactive l'endpoint HTTP d'une action. Utilisez `server/routes/api/*` uniquement pour les besoins en forme de route ou de protocole : téléversements de fichiers, streaming/SSE, webhooks, rappels OAuth, pages publiques, ou une forme REST externe qui ne peut pas être représentée proprement par une action. Ne créez pas de routes `/api/*` qui se contentent surtout d'envelopper ou de réexporter des actions.
+
+Pour un endpoint de statut en lecture seule, gardez-le comme une action :
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+Appelez-la directement via HTTP :
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+Pour `POST` et les autres actions d'écriture, envoyez un corps JSON au même chemin d'action.
+
 ## Achèvement du texte en une seule fois {#complete-text}
 
 La plupart des travaux d'IA doivent passer par le chat de l'agent afin que les utilisateurs puissent voir, piloter et auditer

package/docs/content/locales/hi-IN/server.mdx

@@ -125,6 +125,41 @@ export default defineEventHandler(() => ({
 
 कस्टम `/api/*` रूट का उपयोग केवल तभी करें जब आपको रूट-आकार वाले प्रोटोकॉल या बाइनरी/स्ट्रीमिंग व्यवहार की आवश्यकता हो। [Actions](/docs/actions) देखें.
 
+### केवल API ऐप्स {#api-only-apps}
+
+सिर्फ इसलिए कि ऐप केवल API है, आपको Express सर्वर की आवश्यकता नहीं है। Agent Native ऐप में पहले से Nitro/H3 सर्वर शामिल होता है, और `defineAction()` डिफ़ॉल्ट API सतह है। संचालन को `actions/` में परिभाषित करें; फ़्रेमवर्क हर action को schema validation और request context के साथ `/_agent-native/actions/<name>` पर माउंट करता है।
+
+सीधे HTTP access का आकार देने के लिए action के `http` विकल्प का उपयोग करें: actions डिफ़ॉल्ट रूप से `POST` होते हैं, `http: { method: "GET" | "PUT" | "DELETE" }` verb बदलता है, और `http: false` action को HTTP से हटा देता है। `server/routes/api/*` का उपयोग केवल route-shaped या protocol चिंताओं के लिए करें: file uploads, streaming/SSE, webhooks, OAuth callbacks, public pages, या ऐसा external REST shape जिसे action के रूप में साफ़ तरीके से व्यक्त नहीं किया जा सकता। ऐसे `/api/*` routes न बनाएं जो अधिकतर actions को wrap या re-export करते हों।
+
+रीड-ओनली status endpoint के लिए, इसे action ही रखें:
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+इसे सीधे HTTP पर कॉल करें:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+`POST` और अन्य write actions के लिए, उसी action path पर JSON body भेजें.
+
 ## एक-शॉट पाठ समापन {#complete-text}
 
 अधिकांश AI कार्य एजेंट चैट के माध्यम से होना चाहिए ताकि उपयोगकर्ता देख सकें, संचालन कर सकें और ऑडिट कर सकें

package/docs/content/locales/ja-JP/server.mdx

@@ -129,6 +129,41 @@ UI とエージェントの両方が何かを行う必要がある場合は、
 
 カスタム `/api/*` ルートは、ルート形式のプロトコルまたはバイナリ/ストリーミング動作が必要な場合にのみ使用してください。 [Actions](/docs/actions) を参照してください。
 
+### API 専用アプリ {#api-only-apps}
+
+アプリが API 専用だからといって、Express サーバーは必要ありません。Agent Native アプリには Nitro/H3 サーバーがすでに含まれており、`defineAction()` がデフォルトの API サーフェスです。操作は `actions/` に定義します。フレームワークは、各 action をスキーマ検証とリクエスト コンテキスト付きで `/_agent-native/actions/<name>` にマウントします。
+
+直接 HTTP アクセスの形は action の `http` オプションで調整します。actions はデフォルトで `POST`、`http: { method: "GET" | "PUT" | "DELETE" }` でメソッドを変更し、`http: false` で action を HTTP から外します。`server/routes/api/*` は、ファイル アップロード、ストリーミング/SSE、webhooks、OAuth コールバック、パブリック ページ、または action としてきれいに表せない外部向け REST 形状など、ルート形式またはプロトコル上の関心事にだけ使用してください。主に actions をラップまたは再エクスポートする `/api/*` ルートは作成しないでください。
+
+読み取り専用の status endpoint は action として保持します:
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+HTTP で直接呼び出します:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+`POST` とその他の書き込み actions では、同じ action path に JSON body を送信します。
+
 ## ワンショットテキスト補完 {#complete-text}
 
 ユーザーが確認、操作、監査できるように、ほとんどの AI 作業はエージェント チャットを経由する必要があります

package/docs/content/locales/ko-KR/server.mdx

@@ -127,6 +127,41 @@ UI와 에이전트가 모두 작업을 수행해야 하는 경우 사용자 지
 
 경로 형태의 프로토콜이나 바이너리/스트리밍 동작이 필요한 경우에만 사용자 지정 `/api/*` 경로를 사용하세요. [Actions](/docs/actions)를 참조하세요.
 
+### API 전용 앱 {#api-only-apps}
+
+앱이 API 전용이라고 해서 Express 서버가 필요한 것은 아닙니다. Agent Native 앱에는 이미 Nitro/H3 서버가 포함되어 있으며, `defineAction()`이 기본 API 표면입니다. 작업은 `actions/`에 정의하세요. 프레임워크는 각 action을 schema validation 및 request context와 함께 `/_agent-native/actions/<name>`에 마운트합니다.
+
+직접 HTTP access의 형태는 action의 `http` 옵션으로 조정합니다. actions는 기본적으로 `POST`이고, `http: { method: "GET" | "PUT" | "DELETE" }`는 verb를 변경하며, `http: false`는 action을 HTTP에서 제외합니다. `server/routes/api/*`는 file uploads, streaming/SSE, webhooks, OAuth callbacks, public pages 또는 action으로 깔끔하게 표현할 수 없는 external REST shape처럼 route-shaped 또는 protocol 관련 요구에만 사용하세요. 주로 actions를 감싸거나 다시 내보내는 `/api/*` 경로는 만들지 마세요.
+
+읽기 전용 상태 endpoint는 action으로 유지하세요:
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+HTTP로 직접 호출합니다:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+`POST` 및 기타 쓰기 actions는 같은 action path로 JSON body를 보냅니다.
+
 ## 원샷 텍스트 완성 {#complete-text}
 
 대부분의 AI 작업은 사용자가 보고, 조종하고, 감사할 수 있도록 에이전트 채팅을 거쳐야 합니다.

package/docs/content/locales/pt-BR/server.mdx

@@ -129,6 +129,41 @@ Se o UI e o agente precisarem fazer algo, defina uma ação em vez de uma rota A
 
 Use rotas `/api/*` personalizadas somente quando precisar de um protocolo em formato de rota ou comportamento binário/streaming. Consulte [Actions](/docs/actions).
 
+### Aplicativos somente API {#api-only-apps}
+
+Você não precisa de um servidor Express só porque o aplicativo é somente API. Um aplicativo Agent Native já vem com um servidor Nitro/H3, e `defineAction()` é a superfície API padrão. Defina operações em `actions/`; a estrutura monta cada action em `/_agent-native/actions/<name>` com validação de schema e contexto de solicitação.
+
+Use a opção `http` da action para moldar o acesso HTTP direto: actions são `POST` por padrão, `http: { method: "GET" | "PUT" | "DELETE" }` altera o verbo, e `http: false` remove uma action do HTTP. Use `server/routes/api/*` apenas para necessidades com formato de rota ou protocolo: uploads de arquivos, streaming/SSE, webhooks, callbacks OAuth, páginas públicas ou uma forma REST externa que não possa ser representada claramente como uma action. Não crie rotas `/api/*` que principalmente encapsulem ou reexportem actions.
+
+Para um endpoint de status somente leitura, mantenha-o como uma action:
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+Chame diretamente via HTTP:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+Para `POST` e outras actions de escrita, envie um corpo JSON para o mesmo caminho da action.
+
 ## Completamento de texto único {#complete-text}
 
 A maior parte do trabalho de IA deve passar pelo chat do agente para que os usuários possam ver, orientar e auditar

package/docs/content/locales/zh-CN/server.mdx

@@ -125,6 +125,41 @@ export default defineEventHandler(() => ({
 
 仅当您需要路由型协议或二进制/流行为时才使用自定义 `/api/*` 路由。参见[Actions](/docs/actions)。
 
+### 仅 API 应用 {#api-only-apps}
+
+应用仅提供 API 并不意味着需要 Express 服务器。Agent Native 应用已经自带 Nitro/H3 服务器，`defineAction()` 是默认的 API 表面。将操作定义在 `actions/` 中；框架会把每个 action 挂载到 `/_agent-native/actions/<name>`，并带有 schema 验证和请求上下文。
+
+使用 action 的 `http` 选项来调整直接 HTTP 访问方式：actions 默认是 `POST`，`http: { method: "GET" | "PUT" | "DELETE" }` 会更改动词，`http: false` 会关闭该 action 的 HTTP 端点。只有在处理路由形状或协议问题时才使用 `server/routes/api/*`：文件上传、流式传输/SSE、webhooks、OAuth 回调、公共页面，或无法干净表示为 action 的外部 REST 形状。不要创建主要只是包装或重新导出 actions 的 `/api/*` 路由。
+
+对于只读状态 endpoint，请保持为 action：
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+直接通过 HTTP 调用：
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+对于 `POST` 和其他写入 actions，请将 JSON body 发送到相同的 action path。
+
 ## 一次性文本完成 {#complete-text}
 
 大多数人工智能工作应通过代理聊天进行，以便用户可以查看、引导和审核

package/docs/content/locales/zh-TW/server.mdx

@@ -125,6 +125,41 @@ export default defineEventHandler(() => ({
 
 僅當您需要路由型協議或二進制/流行為時才使用自訂 `/api/*` 路由。參見[Actions](/docs/actions)。
 
+### 僅 API 應用程式 {#api-only-apps}
+
+應用程式僅提供 API 並不表示需要 Express 伺服器。Agent Native 應用程式已經內建 Nitro/H3 伺服器，`defineAction()` 是預設的 API 表面。將操作定義在 `actions/` 中；框架會將每個 action 掛載到 `/_agent-native/actions/<name>`，並包含 schema 驗證和請求脈絡。
+
+使用 action 的 `http` 選項來調整直接 HTTP 存取方式：actions 預設是 `POST`，`http: { method: "GET" | "PUT" | "DELETE" }` 會變更動詞，`http: false` 會關閉該 action 的 HTTP 端點。只有在處理路由形狀或協議問題時才使用 `server/routes/api/*`：檔案上傳、串流/SSE、webhooks、OAuth 回呼、公開頁面，或無法乾淨表示為 action 的外部 REST 形狀。不要建立主要只是包裝或重新匯出 actions 的 `/api/*` 路由。
+
+對於唯讀狀態 endpoint，請保持為 action：
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+直接透過 HTTP 呼叫：
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+對於 `POST` 和其他寫入 actions，請將 JSON body 傳送到相同的 action path。
+
 ## 一次性文字完成 {#complete-text}
 
 大多數人工智慧工作應透過代理聊天進行，以便使用者可以檢視、引導和審核

package/docs/content/server.mdx

@@ -129,6 +129,41 @@ If the UI and agent both need to do something, define an action instead of a cus
 
 Use custom `/api/*` routes only when you need a route-shaped protocol or binary/streaming behavior. See [Actions](/docs/actions).
 
+### API-Only Apps {#api-only-apps}
+
+You do not need an Express server just because the app is API-only. An agent-native app already ships with a Nitro/H3 server, and `defineAction()` is the default API surface. Define operations in `actions/`; the framework mounts each action at `/_agent-native/actions/<name>` with schema validation and request context.
+
+Use the action `http` option to shape direct HTTP access: actions are `POST` by default, `http: { method: "GET" | "PUT" | "DELETE" }` changes the verb, and `http: false` keeps an action off HTTP. Reach for `server/routes/api/*` only for route-shaped or protocol concerns: file uploads, streaming/SSE, webhooks, OAuth callbacks, public pages, or an external REST shape that cannot be represented cleanly as an action. Do not create `/api/*` routes that mostly wrap or re-export actions.
+
+For a read-only status endpoint, keep it as an action:
+
+```ts
+// actions/get-status.ts
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return API service status",
+  schema: z.object({
+    service: z.string().optional(),
+  }),
+  http: { method: "GET" },
+  run: async ({ service }) => ({
+    ok: true,
+    service: service ?? "api",
+    checkedAt: new Date().toISOString(),
+  }),
+});
+```
+
+Call it directly over HTTP:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+For `POST` and other write actions, send a JSON body to the same action path.
+
 ## One-Shot Text Completion {#complete-text}
 
 Most AI work should go through the agent chat so users can see, steer, and audit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.92.2",
+  "version": "0.92.4",
   "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": {
@@ -315,7 +315,7 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "0.4.4"
+    "@agent-native/toolkit": "^0.4.4"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",