@agent-native/core 0.98.0 → 0.98.2

package/docs/content/pr-visual-recap.mdx

@@ -123,6 +123,53 @@ reference files the skill ships with. If your repo intentionally customizes and
 pins its committed `visual-recap` folder, set the repository variable
 `VISUAL_RECAP_SKILL_SOURCE=repo`.
 
+## Runner selection
+
+The workflow runs on GitHub-hosted `ubuntu-latest` runners by default. To use a
+different hosted runner or your own self-hosted runner, set the repository or
+organization variable `VISUAL_RECAP_RUNS_ON` to a valid JSON string or JSON
+array of runner labels:
+
+```text
+"ubuntu-latest"
+["self-hosted", "linux", "x64", "visual-recap"]
+```
+
+The JSON quotes are required. This setting selects the full `recap` job runner.
+To configure it during guided setup, pass the same JSON value to `--runs-on`,
+then validate the workflow and runner availability with `doctor`:
+
+```bash
+npx @agent-native/core@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
+npx @agent-native/core@latest recap doctor
+```
+
+The lightweight security gate defaults separately to GitHub-hosted
+`ubuntu-latest`. Repositories that disable GitHub-hosted runners can set
+`VISUAL_RECAP_GATE_RUNS_ON` to one **plain, single runner label** (not JSON), or
+pass `--gate-runs-on visual-recap-gate` during setup. The reusable workflow
+exposes the same value as its `gate-runs-on` input. This avoids parsing dynamic
+JSON before GitHub can schedule the gate. The custom label is selected only for
+same-repository PRs authored by an `OWNER`, `MEMBER`, or `COLLABORATOR`. Forks
+and all other authors are forced to GitHub-hosted `ubuntu-latest` before the job
+starts; in a self-hosted-only repository, those untrusted runs may remain
+unscheduled rather than touching a self-hosted machine.
+
+`recap doctor` rejects malformed or unsupported JSON and reports when GitHub
+does not expose an online runner matching every configured label. Runner
+registration, installation, upgrades, capacity, and maintenance remain your
+responsibility; Agent Native selects the labels but does not provide or operate
+the runner.
+
+**Security:** Prefer dedicated, ephemeral self-hosted runners. A custom gate
+runner receives only trusted same-repository PR events. The stock gate does not
+check out the PR tree; it evaluates the workflow logic and GitHub PR metadata.
+A persistent machine still retains process state across jobs, so do not share
+it with unrelated workloads. The workflow fails closed before dispatching any
+self-hosted gate or full recap job for untrusted public or fork PR authors. Do
+not weaken that boundary or route untrusted contributions to a persistent
+runner.
+
 ## Backend selection
 
 Choose which coding agent runs the skill with the `VISUAL_RECAP_AGENT` repository variable:
@@ -468,10 +515,12 @@ jobs:
       base-url: ${{ vars.VISUAL_RECAP_BASE_URL || '' }}
       reasoning: ${{ vars.VISUAL_RECAP_REASONING || '' }}
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
+      runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
+      gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
       # cli-version: "latest"  # pin to a specific @agent-native/core version
 ```
 
-The same secrets and variables described in [Secrets and variables](#secrets-and-variables) apply — set them in your repo settings the same way as for the copy variant.
+The same secrets and variables described in [Secrets and variables](#secrets-and-variables) apply — set them in your repo settings the same way as for the copy variant. The reusable caller forwards `VISUAL_RECAP_RUNS_ON` through its JSON `runs-on` input for the full recap job and `VISUAL_RECAP_GATE_RUNS_ON` through its plain-label `gate-runs-on` input for the metadata-only gate. The latter is used only for trusted same-repository authors; other PRs use GitHub-hosted `ubuntu-latest`. Omitting either input preserves its `ubuntu-latest` default.
 
 ### Installing via the CLI
 

package/docs/content/template-plan.mdx

@@ -304,7 +304,7 @@ npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --
 ```
 
 The bridge URL looks like
-`https://plan.agent-native.com/local-plans/<slug>?bridge=http://127.0.0.1:...`.
+`https://plan.agent-native.com/local-plans/local-<opaque-id>#bridge=http://127.0.0.1:...`.
 The page is the normal Plan viewer, but the browser fetches `plan.mdx`,
 `canvas.mdx`, `prototype.mdx`, `.plan-state.json`, and local image assets from
 the localhost bridge. Plan content is not written to the hosted database and is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.98.0",
+  "version": "0.98.2",
   "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.