@agent-native/core 0.92.2 → 0.92.4

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2153
-- template files: 5039
+- core files: 2154
+- template files: 5047

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @agent-native/core
 
+## 0.92.4
+
+### Patch Changes
+
+- 86697e9: Depend on `@agent-native/toolkit` via `workspace:^` instead of `workspace:*`. Publishing now pins a caret range (e.g. `^0.4.3`) rather than an exact version, so an app that scaffolds `@agent-native/toolkit@latest` separately can dedupe against it through normal semver resolution instead of installing two mismatched toolkit copies side by side (which crashed Vite with `"./collab-ui" is not exported`).
+
+## 0.92.3
+
+### Patch Changes
+
+- 0fee97b: Animate settings section cards open and closed with intrinsic height transitions.
+- 0fee97b: Document how to build API-only Agent Native apps with actions on the built-in Nitro/H3 server.
+- 0fee97b: Replay the real terminal error for completed agent runs on reconnect instead of replacing provider failures with stale-run messages, and stop heartbeat updates after a run leaves the running state.
+- 0fee97b: Allow signed embed sessions for Analytics dashboard deep links to authenticate after canonical `/dashboards/:id` redirects.
+- 0fee97b: Prevent stale stored awareness rows from resurrecting user or agent presence after a client explicitly leaves a collaborative document.
+- 0fee97b: Abort superseded chat reconnect readers and back off failed reattach attempts so repeated stale runs do not create client request storms.
+- 0fee97b: Harden chat stop and queued follow-up handling so interrupted tool calls settle cleanly, and flush Agent Native analytics immediately in serverless runtimes.
+- 0fee97b: Avoid CORS preflight storms for embedded framework polling by using query-token auth on safe `/_agent-native` GET requests.
+- 0fee97b: Deliver Agent Native Analytics tracking immediately in serverless runtimes so `http.response` health telemetry is not lost after the response finishes.
+- 0fee97b: Prevent in-flight tool call cards from flickering between newer and older states during reconnect, thread import, and retry clears.
+- 0fee97b: Make chat prompt submission update immediately and make Stop clear queued follow-ups and settle interrupted tool calls.
+- 0fee97b: Single-flight the agent run heartbeat write so a run holds at most one Neon connection for liveness. The 1.5s heartbeat timer previously fired a fresh write every tick regardless of whether the prior one was still in flight; under Neon pooler saturation (writes taking up to the ~8s DB timeout) this piled up ~5 concurrent heartbeat connections per run, adding to the connection-cap exhaustion that starves the heartbeat and gets the still-alive run false-reaped as stale. The abort and no-progress-backstop checks still run every tick.
+- 0fee97b: Normalize unsupported saved agent models to a supported version match or the engine default.
+- 0fee97b: Remove Grok Code Fast and Qwen3 Coder from the Builder gateway model picker.
+- 0fee97b: Treat Anthropic/Builder bare "Connection error." failures as retryable network interruptions, and stop mislabeling those failed runs as stale_run when the client reconnects past the real terminal event.
+- 0fee97b: Stop `useDbSync` from turning app-state navigation/selection churn into a client fetch storm. `app-state` change events (agent/UI navigation, selection, and the set-url/questions command channel) now only invalidate their own `["app-state"]` and command query keys — they no longer fan out into the broad `["action"]`, `["extension"]`, and `["tool"]` data-query invalidation. Only events that can actually change action/extension-backed data (action mutations, settings, extensions, collab, screen-refresh) refetch those prefixes.
+
+  During an active agent session the app mirrors navigation and selection into `application_state` continuously, and on serverless the poll fallback replays those writes back to the originating tab (the DB-scan path can't preserve `requestSource`, so `ignoreSource` can't filter them). Each replayed write previously refetched every action query at once, and that request storm exhausted the DB connection pool — which starved run heartbeat writes and surfaced downstream as `stale_run` chat errors. Real mutations that also write navigation state still refresh action queries because their `action` event rides in the same batch.
+
+- 0fee97b: Show streamed agent reasoning when gateways emit AI SDK-style reasoning deltas.
+- 0fee97b: Show raw tool call output in an auto-height popover with viewport-capped scrolling instead of a fixed-height dialog.
+
 ## 0.92.2
 
 ### Patch Changes

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

@@ -129,6 +129,41 @@ export default defineEventHandler(() => ({
 
 استخدم مسارات `/api/*` المخصصة فقط عندما تحتاج إلى بروتوكول على شكل مسار أو سلوك ثنائي/دفق. انظر [Actions](/docs/actions).
 
+### تطبيقات API فقط {#api-only-apps}
+
+لا تحتاج إلى خادم Express لمجرد أن التطبيق مخصص للـ API فقط. يتضمن تطبيق Agent Native بالفعل خادم Nitro/H3، و`defineAction()` هو سطح API الافتراضي. عرّف العمليات في `actions/`؛ يقوم إطار العمل بتركيب كل action على `/_agent-native/actions/<name>` مع التحقق من schema وسياق الطلب.
+
+استخدم خيار `http` في action لتشكيل الوصول المباشر عبر HTTP: تكون actions افتراضيًا `POST`، ويغيّر `http: { method: "GET" | "PUT" | "DELETE" }` الفعل، ويجعل `http: false` الـ action غير متاحة عبر HTTP. استخدم `server/routes/api/*` فقط للمخاوف التي لها شكل مسار أو بروتوكول: تحميل الملفات، streaming/SSE، webhooks، استدعاءات OAuth، الصفحات العامة، أو شكل REST خارجي لا يمكن تمثيله بوضوح كـ action. لا تنشئ مسارات `/api/*` تقوم غالبًا بتغليف actions أو إعادة تصديرها.
+
+لإنشاء 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 إلى مسار action نفسه.
+
 ## إكمال النص بلقطة واحدة {#complete-text}
 
 يجب أن تتم معظم أعمال الذكاء الاصطناعي من خلال دردشة الوكيل حتى يتمكن المستخدمون من الرؤية والتوجيه والتدقيق

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

@@ -127,6 +127,41 @@ Wenn UI und Agent beide etwas tun müssen, definieren Sie eine Aktion anstelle e
 
 Verwenden Sie benutzerdefinierte `/api/*`-Routen nur, wenn Sie ein routenförmiges Protokoll oder Binär-/Streaming-Verhalten benötigen. Siehe [Actions](/docs/actions).
 
+### API-only Apps {#api-only-apps}
+
+Sie benötigen keinen Express-Server, nur weil die App nur eine API bereitstellt. Eine Agent Native-App bringt bereits einen Nitro/H3-Server mit, und `defineAction()` ist die standardmäßige API-Oberfläche. Definieren Sie Operationen in `actions/`; das Framework stellt jede action unter `/_agent-native/actions/<name>` mit Schemavalidierung und Anforderungskontext bereit.
+
+Verwenden Sie die `http`-Option der action, um direkten HTTP-Zugriff zu formen: actions sind standardmäßig `POST`, `http: { method: "GET" | "PUT" | "DELETE" }` ändert das Verb, und `http: false` nimmt eine action aus HTTP heraus. Greifen Sie nur für routenförmige oder protokollbezogene Anliegen zu `server/routes/api/*`: Datei-Uploads, Streaming/SSE, webhooks, OAuth-Rückrufe, öffentliche Seiten oder eine externe REST-Form, die sich nicht sauber als action darstellen lässt. Erstellen Sie keine `/api/*`-Routen, die hauptsächlich actions umhüllen oder re-exportieren.
+
+Für einen schreibgeschützten Status-endpoint behalten Sie ihn als action bei:
+
+```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(),
+  }),
+});
+```
+
+Rufen Sie ihn direkt über HTTP auf:
+
+```http
+GET /_agent-native/actions/get-status?service=billing
+```
+
+Für `POST` und andere schreibende actions senden Sie einen JSON-body an denselben action-path.
+
 ## One-Shot-Textvervollständigung {#complete-text}
 
 Der Großteil der KI-Arbeit sollte über den Agenten-Chat erfolgen, damit Benutzer sehen, steuern und prüfen können

package/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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/corpus/core/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": {
@@ -235,7 +235,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agent-native/toolkit": "workspace:*",
+    "@agent-native/toolkit": "workspace:^",
     "@amplitude/analytics-browser": "^2.41.1",
     "@anthropic-ai/sdk": "^0.90.0",
     "@anthropic-ai/tokenizer": "0.0.4",

package/corpus/core/src/agent/engine/ai-sdk-engine.ts

@@ -401,21 +401,29 @@ class AISDKEngine implements AgentEngine {
       // rather than keyword-matching the message string.
       const statusCode: number | undefined =
         typeof err?.statusCode === "number" ? err.statusCode : undefined;
+      const errorMessage = err?.message ?? String(err);
+      const isConnectionError =
+        statusCode === undefined &&
+        String(errorMessage).trim().toLowerCase() === "connection error.";
       const providerRetryable: boolean | undefined =
-        typeof err?.isRetryable === "boolean" ? err.isRetryable : undefined;
+        typeof err?.isRetryable === "boolean"
+          ? err.isRetryable
+          : isConnectionError
+            ? true
+            : undefined;
       if (statusCode === 401) {
         await recordProviderCredentialAuthFailure({
           key: PROVIDER_ENV_VARS[this.provider][0],
           value: this.apiKey,
           status: statusCode,
           code: "http_401",
-          message: err?.message ?? String(err),
+          message: errorMessage,
         });
       }
       yield {
         type: "stop",
         reason: "error",
-        error: err?.message ?? String(err),
+        error: errorMessage,
         // Tag every known status with `http_<status>` (not just 401) so a
         // rate limit surfaces as `http_429`. The structured statusCode
         // already drives turn-level retries, but the run-level continuation
@@ -423,7 +431,9 @@ class AISDKEngine implements AgentEngine {
         // auto-resume too — matching the Builder gateway path.
         ...(statusCode !== undefined
           ? { errorCode: `http_${statusCode}`, statusCode }
-          : {}),
+          : isConnectionError
+            ? { errorCode: "provider_network_error" }
+            : {}),
         ...(providerRetryable !== undefined ? { providerRetryable } : {}),
       };
       throw err;

package/corpus/core/src/agent/engine/anthropic-engine.ts

@@ -232,19 +232,26 @@ class AnthropicEngine implements AgentEngine {
           : typeof err?.statusCode === "number"
             ? err.statusCode
             : undefined;
+      const errorMessage = err?.message ?? String(err);
+      // Anthropic SDK APIConnectionError defaults to "Connection error." with
+      // no HTTP status. Tag it so in-run retries and run-level resume treat
+      // the failure as a transient network interruption.
+      const isConnectionError =
+        statusCode === undefined &&
+        String(errorMessage).trim().toLowerCase() === "connection error.";
       if (statusCode === 401) {
         await recordProviderCredentialAuthFailure({
           key: "ANTHROPIC_API_KEY",
           value: this.apiKey,
           status: statusCode,
           code: "http_401",
-          message: err?.message ?? String(err),
+          message: errorMessage,
         });
       }
       yield {
         type: "stop",
         reason: "error",
-        error: err?.message ?? String(err),
+        error: errorMessage,
         // Forward the provider HTTP status for EVERY known status, not just
         // 401. The Anthropic SDK reports empty-body failures as a bare
         // "429 status code (no body)" message, so without a structured
@@ -255,7 +262,12 @@ class AnthropicEngine implements AgentEngine {
         // continuation logic auto-resume a rate-limited turn.
         ...(statusCode !== undefined
           ? { errorCode: `http_${statusCode}`, statusCode }
-          : {}),
+          : isConnectionError
+            ? {
+                errorCode: "provider_network_error",
+                providerRetryable: true,
+              }
+            : {}),
       };
       throw err;
     }