@agent-native/core 0.98.0 → 0.98.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.98.0",
+  "version": "0.98.1",
   "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": {
@@ -269,7 +269,7 @@
     "@react-router/dev": "^8.1.0",
     "@react-router/fs-routes": "^8.1.0",
     "@resvg/resvg-js": "^2.6.2",
-    "@rrweb/record": "2.0.1",
+    "@rrweb/record": "2.1.0",
     "@sentry/browser": "10.60.0",
     "@sentry/node": "10.60.0",
     "@shadcn/react": "^0.2.0",

package/src/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/src/templates/workspace-core/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/src/templates/workspace-core/.agents/skills/secrets/SKILL.md

@@ -170,9 +170,13 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
 - Values are stored in `app_secrets` (created on-demand; no migration
   needed).
 - Encrypted at rest with AES-256-GCM. Key material is derived from
-  `SECRETS_ENCRYPTION_KEY` (preferred) or `BETTER_AUTH_SECRET` (fallback).
-  If neither is set, the framework uses a machine-local fallback and logs a
-  one-time warning — set `SECRETS_ENCRYPTION_KEY` in production.
+  `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set (for example,
+  `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
+  `BETTER_AUTH_SECRET`. App-scoped keys are useful when a local multi-app
+  workspace connects one app to its production database without replacing the
+  shared local authentication secret. If none is set, the framework uses a
+  machine-local fallback and logs a one-time warning — set stable key material
+  in production and in every runtime that reads the same encrypted data.
 
 ## Ad-hoc Keys
 

package/src/templates/workspace-core/.agents/skills/voice-transcription/SKILL.md

@@ -52,24 +52,54 @@ action before requesting microphone permission.
 - Starting voice mode collapses the chat into a persistent bottom-end speech
   orb. The orb stays visible above the chat even when the chat opens
   automatically. Clicking it shows or hides chat without ending the session;
-  ending the session is a separate, explicit control.
-- The orb's compact waveform must reflect actual microphone or assistant audio
-  activity. It is an audio-level indicator, not a decorative animation.
+  opening chat slides the orb clear of the sidebar. The progressively disclosed
+  controls contain only settings and the separate end-session action.
+- The orb's compact waveform stays visible for the full session and reflects
+  actual microphone or assistant audio activity. At silence it rests at its
+  baseline instead of turning into a loading spinner. While connecting, show a
+  distinct compact spinner; when the session becomes live, the assistant gives
+  one brief spoken greeting so readiness is unambiguous. Do not apply a
+  text-sized `max_output_tokens` cap to that audio greeting because audio tokens
+  can truncate it mid-sentence.
+- The orb settings cog opens in place without ending voice mode or navigating
+  away. Nested pickers must not dismiss the settings popover. Language and
+  intelligence update the active Realtime session; the microphone picker swaps
+  the live WebRTC input track and remembers the browser-local device choice;
+  an output-voice change updates immediately only before the assistant has
+  emitted audio and otherwise applies to the next conversation, matching the
+  Realtime API's voice immutability rule.
 - Semantic VAD keeps listening, starts responses automatically, and supports
   barge-in while the agent is speaking.
 - Function calls must cross the authenticated realtime tool bridge and enter
   `executeAgentToolCall`. Never call `ActionEntry.run` directly: that bypasses
   schema validation, approvals, audit/journal behavior, timeouts, redaction,
   and mutation refreshes.
-- Preserve the active browser-tab id in request context so `set-url`,
+- Preserve the active browser-tab id in request context so `set-url-path`,
   `set-search-params`, `view-screen`, and tab-scoped application state affect
-  the app the user is actually speaking to.
+  the app the user is actually speaking to. Realtime tool manifests are capped,
+  so prioritize `navigate`, `set-url-path`, `set-search-params`, and
+  `view-screen` before packing large template registries.
+- Keep `tool-search` in the initial Realtime manifest. A successful specific
+  search may expand the live session with matching action schemas, but the
+  server must derive those schemas from its own registry, bind authorization
+  to the authenticated voice session, and continue execution through
+  `executeAgentToolCall`. Treat `session.update.tools` as a full replacement:
+  preserve the pinned navigation/discovery tools, evict lower-priority entries
+  within the manifest cap, and wait for `session.updated` before asking the
+  model to continue with a newly discovered tool.
 - Do not persist audio or interim transcript deltas. Append completed user and
   assistant utterances as ordinary text messages to the exact chat thread
-  captured when the session starts. Ending voice mode opens that chat so the
-  user can continue over text. Store only compact lifecycle and latest context
-  at `application_state["realtime-voice-session"]`; delete it when the session
-  ends.
+  captured when the session starts. Input transcription completes
+  asynchronously from assistant generation, so reserve provider conversation
+  item order and publish only the contiguous completed sequence; never use
+  completion arrival time as chat order. Ending voice mode opens that chat so
+  the user can continue over text. Store only compact lifecycle and latest
+  context at `application_state["realtime-voice-session"]`; delete it when the
+  session ends.
+- Store the user-controlled language, intelligence, and output-voice choices at
+  `application_state["realtime-voice-prefs"]`. Keep this separate from
+  `voice-transcription-prefs`, which configures editable dictation rather than
+  the speech-to-speech session.
 - Missing-key failures should open Settings focused on the user-scoped
   `OPENAI_API_KEY` field. Never send, log, or echo the key to the browser.