@agent-native/core 0.73.0 → 0.74.0

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1160
-- template files: 4022
+- template files: 4025

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @agent-native/core
 
+## 0.74.0
+
+### Minor Changes
+
+- 4a0d3c4: Durable background agent runs are robust again, and **on by default** for hosted apps.
+  - **Graceful inline fallback (the safety fix).** When the foreground turn can't
+    hand off to a background worker — the HMAC self-dispatch self-POST fails fast,
+    e.g. a connection error or a non-2xx returned within the settle window — the
+    agent-chat handler no longer breaks the chat with
+    `Failed to dispatch background run`. It now degrades to a normal synchronous
+    (inline) run, reusing the already-inserted run row. The run is claimed
+    atomically (`claimBackgroundRun`, a conditional `dispatch_mode: background →
+background-processing` UPDATE) before running inline, so the SQL atomic claim
+    is the single owner — a delayed background delivery that arrives afterward
+    loses the claim and no-ops, and the run can never double-execute. A dispatch
+    that _did_ land (so a worker already owns the run) still streams the worker's
+    events instead of running a second copy.
+  - **Default-on, safely.** `AGENT_CHAT_DURABLE_BACKGROUND` is now opt-out for
+    hosted apps: unset/empty/unknown counts as enabled; opt a specific app back
+    out with an explicit falsy value (`false`/`0`/`no`/`off`). The gate still
+    composes with the existing guards, so a run only goes durable when the runtime
+    is hosted/serverless **and** `A2A_SECRET` is configured — local dev and
+    unconfigured apps stay on the synchronous inline path unchanged. Default-on is
+    safe precisely because a failed dispatch degrades to a working inline run. The
+    Netlify 15-min `-background` function emit (`isDurableBackgroundDeployEnabled`)
+    remains opt-in until its path is separately verified; with it off, the
+    default-on baseline runs the worker through the standard function and
+    server-chains continuations.
+  - **More diagnosable dispatch errors.** Self-dispatch failures now log the
+    resolved base URL so a failure tied to which host the self-POST targets
+    (custom domain vs deploy URL) is visible in logs. The URL resolution order is
+    unchanged (it matches the working A2A/agent-teams self-dispatch paths).
+
+### Patch Changes
+
+- 4a0d3c4: Show numbered annotation markers in the annotated-code gutter, matching the diff
+  annotation affordance while preserving the hover popover behavior.
+- 4a0d3c4: Clarify Builder code-change handoff fallbacks when cloud agents are unavailable.
+
 ## 0.73.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.73.0",
+  "version": "0.74.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/agent/durable-background.ts

@@ -19,12 +19,20 @@
  * agent-chat handler must behave byte-for-byte like the current synchronous
  * path. The gate is true only when ALL of these hold:
  *   1. `AGENT_CHAT_DURABLE_BACKGROUND` env is not explicitly disabled. It is
- *      DEFAULT-ON: unset/empty counts as enabled; set it to a falsy value
- *      (`false`/`0`/`no`/`off`) to opt a specific app back out.
+ *      DEFAULT-ON: unset/empty/unknown counts as enabled; set it to a falsy
+ *      value (`false`/`0`/`no`/`off`) to opt a specific app back out.
  *   2. The runtime is hosted/serverless (local dev keeps the inline path so SSE
  *      stays a single live stream and no second function is needed).
  *   3. `A2A_SECRET` is configured (the HMAC handoff is required to authenticate
  *      the background dispatch; without it the dispatch can't be trusted).
+ *
+ * Default-on is safe because a *dispatch failure degrades to an inline run*: if
+ * the self-dispatch self-POST can't be delivered (fast connection error or
+ * fast non-2xx), the foreground handler runs the turn synchronously instead of
+ * erroring (see `production-agent.ts` — the inline fallback claims the run row
+ * atomically so a delayed delivery can never double-execute). So an app where
+ * durable dispatch happens to fail still gets a working chat, just without the
+ * 15-min budget.
  */
 import {
   hasConfiguredA2ASecret,
@@ -94,10 +102,12 @@ function isFlagEnabled(): boolean {
   // in sync with AGENT_CHAT_DURABLE_BACKGROUND_ENV.
   //
   // DEFAULT-ON: durable background runs are the desired behavior for every
-  // hosted app (verified in prod — long multi-step runs complete past the 40s
-  // soft-timeout with no thrash). So an unset flag means ON; an app opts OUT
-  // only with an explicit falsy value. This still composes with the hosted +
+  // hosted app. So an unset/empty/unknown flag means ON; an app opts OUT only
+  // with an explicit falsy value. This still composes with the hosted +
   // A2A_SECRET gates below, so non-hosted / unconfigured apps stay synchronous.
+  // Safety net: a failed dispatch degrades to a synchronous inline run (see
+  // production-agent.ts), so default-on cannot break chat even if the
+  // self-dispatch can't be delivered on a given app.
   const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
   if (raw == null) return true;
   const normalized = raw.trim().toLowerCase();

package/corpus/core/src/agent/production-agent.ts

@@ -4363,6 +4363,7 @@ export function createProductionAgentHandler(
     // change. With the flag OFF this whole branch is skipped and the inline
     // `startRun` path below runs exactly as before (byte-for-byte).
     if (dispatchToBackground) {
+      let backgroundRowInserted = false;
       try {
         // Insert the run row up front so /runs/active sees it immediately and
         // the slot stays held while the background function cold-starts. Mark
@@ -4370,6 +4371,7 @@ export function createProductionAgentHandler(
         await insertRun(runId, effectiveThreadId, effectiveTurnId, {
           dispatchMode: "background",
         });
+        backgroundRowInserted = true;
       } catch (err) {
         // A duplicate-PK collision means the row already exists (ret­ried POST);
         // any other failure means we can't safely hand off — fall back to the
@@ -4418,14 +4420,59 @@ export function createProductionAgentHandler(
         setResponseStatus(event, 500);
         return { error: "Failed to subscribe to background run" };
       }
-      // Dispatch failed before any worker could claim the run. Fail loud: flip
-      // the row terminal so the held slot is released (and any reconnect sees a
-      // terminal status instead of spinning), then 500 so the client can retry.
-      // We do NOT silently fall through to inline here — that risks a later,
-      // delayed background delivery double-executing the same runId.
-      await updateRunStatusIfRunning(runId, "errored").catch(() => {});
-      setResponseStatus(event, 500);
-      return { error: "Failed to dispatch background run" };
+
+      // ─── Dispatch failed → degrade to a normal synchronous (inline) run ────
+      // `fireInternalDispatch` throws ONLY when the self-POST failed *fast*
+      // (rejected the connection, or returned a non-2xx within the ~250ms settle
+      // race). The `_process-run` route verifies the HMAC token and validates
+      // the body BEFORE it ever reaches the SQL atomic claim, so a fast throw
+      // means NO background worker claimed this run — there is nothing to
+      // double-execute. Rather than break the chat with "Failed to dispatch
+      // background run", we run the turn inline (the same synchronous path the
+      // flag-off branch below takes), reusing the already-inserted run row.
+      //
+      // Safety against a (very improbable) delayed background delivery: claim the
+      // run atomically here via `claimBackgroundRun`, which flips the row's
+      // dispatch_mode `background → background-processing` in one conditional
+      // UPDATE. If a delayed dispatch DID land and a worker already won the
+      // claim, our claim returns false and we must NOT run inline (that would
+      // double-execute) — fall back to subscribing to the worker's run instead.
+      // The SQL atomic claim is the single source of truth for ownership, so at
+      // most one of {inline fallback, background worker} ever executes this run.
+      if (backgroundRowInserted) {
+        let claimedInline = false;
+        try {
+          claimedInline = await claimBackgroundRun(runId);
+        } catch (err) {
+          console.error(
+            "[agent-chat] inline-fallback claim failed:",
+            err instanceof Error ? err.message : err,
+          );
+        }
+        if (!claimedInline) {
+          // A background worker already owns this run (a delayed delivery landed
+          // after our fast throw). Stream its events instead of running a second
+          // copy. If we somehow can't subscribe, surface an error rather than
+          // risk a double-run.
+          const stream = subscribeToRun(runId, 0);
+          if (stream) {
+            setResponseHeader(event, "Content-Type", "text/event-stream");
+            setResponseHeader(event, "Cache-Control", "no-cache");
+            setResponseHeader(event, "Connection", "keep-alive");
+            setResponseHeader(event, "X-Run-Id", runId);
+            return stream;
+          }
+          await updateRunStatusIfRunning(runId, "errored").catch(() => {});
+          setResponseStatus(event, 500);
+          return { error: "Failed to dispatch background run" };
+        }
+        // We own the run. `startRun` (below) calls `insertRun` again, but its
+        // duplicate-PK collision is swallowed (`insertRun(...).catch(() => {})`),
+        // so the existing `background-processing` row is reused — no double row.
+      }
+      // Fall through to the inline `startRun` path below (the same one the
+      // flag-off branch uses). If the row was never inserted, `startRun` inserts
+      // it fresh; if it was, the claim above made us the sole owner.
     }
 
     const trackedProgressOwner =

package/corpus/core/src/client/ConnectBuilderCard.tsx

@@ -7,6 +7,9 @@ import { cn } from "./utils.js";
 import { agentNativePath } from "./api-path.js";
 
 const DESKTOP_DOWNLOAD_URL = "https://www.agent-native.com/download";
+const CODE_CHANGE_FALLBACK_DETAIL =
+  "Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.";
+const CODE_CHANGE_FALLBACK_TEXT = `This requires a code change. ${CODE_CHANGE_FALLBACK_DETAIL}`;
 
 function isLocalBrowserOutsideDesktop() {
   if (typeof window === "undefined" || typeof navigator === "undefined") {
@@ -200,7 +203,7 @@ export function ConnectBuilderCard({
   // so the render tree below stays flat.
   const connectedCapabilityText = builderEnabled
     ? "AI credits and cloud code changes are ready to use."
-    : "AI credits are ready to use. Builder Cloud Agents for code changes are not available for this workspace yet.";
+    : `AI credits are ready to use. ${CODE_CHANGE_FALLBACK_TEXT}`;
   let title: string;
   let subtitle: React.ReactNode;
   if (runResult) {
@@ -215,20 +218,17 @@ export function ConnectBuilderCard({
       </>
     );
   } else if (showWaitlist) {
-    title = waitlistJoined
-      ? "You're on the waitlist"
-      : "Builder Cloud Agents coming soon";
+    title = "This requires a code change";
     subtitle = waitlistJoined ? (
       <>
-        We'll let you know when Builder Cloud Agents are available for this
-        workspace.{" "}
+        You're on the waitlist. {CODE_CHANGE_FALLBACK_DETAIL}{" "}
         {localBrowser
           ? "Since this project is already running locally, open it in the desktop app for local coding tools or keep editing from your clone."
           : "You can still clone the project locally and use the desktop app for code changes."}
       </>
     ) : (
       <>
-        You don't have access to Builder Cloud Agents for this workspace yet.{" "}
+        {CODE_CHANGE_FALLBACK_DETAIL}{" "}
         {localBrowser
           ? "Since this project is already running locally, open it in the desktop app for local coding tools or keep editing from your clone."
           : "You can still clone the project locally and use the desktop app for code changes."}

package/corpus/core/src/client/NewWorkspaceAppFlow.tsx

@@ -294,7 +294,7 @@ export function NewWorkspaceAppFlow({
         } else {
           setStatusMessage(
             result?.message ||
-              "Builder app creation is coming soon here. Open this workspace in Builder to create an app from this prompt.",
+              "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.",
           );
         }
       }

package/corpus/core/src/client/blocks/library/AnnotatedCodeBlock.tsx

@@ -16,6 +16,7 @@ import {
   AnnotationHiddenStack,
   AnnotationHoverCard,
   AnnotationInlineOverlayStack,
+  AnnotationGutterMarker,
   anchorFromElements,
   buildLineMarkerMap,
   hasRailAnnotations,
@@ -42,9 +43,9 @@ import { DevInput, DevLabel, DevTextarea } from "./dev-doc-ui.js";
  * pairs, so it reads correctly in BOTH light and dark mode. Code lines render as
  * `<span>`s (never one `<pre>` per line) so they don't pick up document
  * code/pre chrome. Lives in core so any app can register the dev-doc block.
- * Each annotated range also gets a small sticky glowing indicator at the top
- * right of its first line, making the hover affordance visible without a note
- * column.
+ * Each annotated range also gets a numbered marker in the left gutter on the
+ * first line, matching the diff block's annotation affordance without adding a
+ * persistent note column.
  *
  * Editing is panel-driven (config-style, like the diff/HTML blocks): a monospace
  * code Textarea, filename/language Inputs, and add/remove-able annotation rows.
@@ -283,6 +284,7 @@ function AnnotatedCodeRead({
     );
     const rangeStartMarkers =
       markers?.filter((item) => item.range?.start === lineNo) ?? [];
+    const showMarkerColumn = hasAnnotations;
 
     const buildAnchorForItem = (
       item: ResolvedAnnotation<AnnotatedCodeAnnotation>,
@@ -373,14 +375,13 @@ function AnnotatedCodeRead({
         <span className="w-11 shrink-0 select-none px-3 text-right text-[11px] tabular-nums text-plan-muted/60">
           {lineNo}
         </span>
-        <span className="flex-1 whitespace-pre pr-4 text-plan-code-text">
-          {highlightedLines[lineNo - 1]}
-        </span>
-        {rangeStartMarkers.length > 0 && (
+        {showMarkerColumn && (
           <span
             aria-hidden
-            className="sticky right-0.5 z-10 ml-2 flex h-[22px] shrink-0 items-center gap-1 self-start pr-0.5"
-            data-annotated-code-marker-stack
+            className="flex w-6 shrink-0 select-none items-center justify-center gap-1 py-0"
+            data-annotated-code-marker-stack={
+              rangeStartMarkers.length > 0 ? "" : undefined
+            }
           >
             {rangeStartMarkers.map((item) => (
               <span
@@ -394,24 +395,35 @@ function AnnotatedCodeRead({
                     ) ?? event.currentTarget;
                   openAnnotation(item, row);
                 }}
-                className="group inline-flex size-3 cursor-pointer items-center justify-center rounded-full outline-none transition-transform hover:scale-110"
+                onClick={(event) => {
+                  event.stopPropagation();
+                  const row =
+                    event.currentTarget.closest<HTMLElement>(
+                      "[data-code-line]",
+                    ) ?? event.currentTarget;
+                  openAnnotation(item, row);
+                }}
+                className="inline-flex cursor-pointer outline-none transition-transform hover:scale-110"
               >
-                <span
-                  className={cn(
-                    "block rounded-full ring-1 transition-all duration-150",
-                    activeIndex === item.index
-                      ? "size-[6px] bg-yellow-300 ring-yellow-200 shadow-[0_0_0_3px_rgba(250,204,21,0.30),0_0_16px_rgba(250,204,21,0.92)] dark:bg-yellow-200 dark:ring-yellow-100/70 dark:shadow-[0_0_0_3px_rgba(253,224,71,0.26),0_0_16px_rgba(253,224,71,0.76)]"
-                      : "size-1 bg-yellow-300/95 ring-yellow-200/65 shadow-[0_0_0_2px_rgba(250,204,21,0.18),0_0_11px_rgba(250,204,21,0.56)] group-hover:size-[6px] group-hover:bg-yellow-300 group-hover:ring-yellow-200 group-hover:shadow-[0_0_0_3px_rgba(250,204,21,0.30),0_0_16px_rgba(250,204,21,0.90)] dark:bg-yellow-200/78 dark:ring-yellow-100/38 dark:shadow-[0_0_0_2px_rgba(253,224,71,0.16),0_0_11px_rgba(253,224,71,0.46)] dark:group-hover:bg-yellow-200 dark:group-hover:ring-yellow-100/68 dark:group-hover:shadow-[0_0_0_3px_rgba(253,224,71,0.26),0_0_16px_rgba(253,224,71,0.74)]",
-                  )}
+                <AnnotationGutterMarker
+                  marker={item.marker}
+                  active={
+                    activeIndex === item.index ||
+                    persistentAnnotationIndexes.has(item.index)
+                  }
                 />
               </span>
             ))}
           </span>
         )}
+        <span className="flex-1 whitespace-pre pr-4 text-plan-code-text">
+          {highlightedLines[lineNo - 1]}
+        </span>
         {overlayItems.length > 0 && (
           <AnnotationInlineOverlayStack
             items={overlayItems}
             ctx={ctx}
+            showMarker
             containerRef={codeRef}
             mode={showAnnotationOverlays ? "capture" : "margin"}
             side={showAnnotationOverlays ? "right" : annotationMarginSide}
@@ -503,7 +515,9 @@ function AnnotatedCodeRead({
           live in a visually-hidden stack (a11y + tests) and surface ONE at a
           time as an on-hover popover anchored to the right of the code. */}
       {codeSurface}
-      {hasAnnotations && <AnnotationHiddenStack items={resolved} ctx={ctx} />}
+      {hasAnnotations && (
+        <AnnotationHiddenStack items={resolved} ctx={ctx} showMarker />
+      )}
       {hasAnnotations &&
         !showAnnotationOverlays &&
         !activeItemIsPersistentlyVisible &&
@@ -513,6 +527,7 @@ function AnnotatedCodeRead({
             item={activeItem}
             anchor={hover.anchor}
             ctx={ctx}
+            showMarker
             preferredSide={annotationHoverSide}
             hoverFallbackSide={annotationHoverFallbackSide}
             onMouseEnter={hover.cancelClose}

package/corpus/core/src/client/blocks/library/annotation-rail.tsx

@@ -26,11 +26,10 @@ import type { BlockRenderContext } from "../types.js";
  *    into stable, marker-numbered, range-resolved records and a line→markers map.
  *  - `rangeLabel` — the human "Line 8" / "Lines 3–6" label.
  *  - `AnnotationGutterMarker` — the numbered amber pip placed on an annotated row
- *    (used by the diff grid; the annotated-code surface uses its own rail bar).
+ *    by both the diff grid and the annotated-code gutter.
  *  - `AnnotationNoteRail` — the responsive list of note cards with two-way hover.
- *    `showMarker` opts the diff block into a leading numbered pip on each card so
- *    a note can be matched to its `①`/`②` row marker; annotated-code omits it to
- *    keep its original card chrome.
+ *    `showMarker` opts blocks into a leading numbered pip on each card so a note
+ *    can be matched to its `①`/`②` row marker.
  *
  * `AnnotatedCodeBlock` annotates a single code surface; `DiffBlock` annotates a
  * before/after grid (each annotation also carries a `side`). The shared types

package/corpus/core/src/client/components/CodeRequiredDialog.tsx

@@ -12,6 +12,8 @@ import { trackEvent } from "../analytics.js";
 import { withBuilderConnectTrackingParams } from "../settings/useBuilderStatus.js";
 
 const DESKTOP_DOWNLOAD_URL = "https://www.agent-native.com/download";
+const CODE_CHANGE_FALLBACK_DETAIL =
+  "Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.";
 
 export interface CodeRequiredDialogProps {
   open: boolean;
@@ -219,15 +221,10 @@ export function CodeRequiredDialog({
                 <IconExternalLink size={24} />
               </div>
               <div style={s.optionText}>
-                <span style={s.optionTitle}>
-                  Builder Cloud Agents coming soon
-                </span>
-                <span style={s.optionDesc}>
-                  You don't have access yet. Use the desktop app or your local
-                  clone for this code change.
-                </span>
+                <span style={s.optionTitle}>This requires a code change</span>
+                <span style={s.optionDesc}>{CODE_CHANGE_FALLBACK_DETAIL}</span>
               </div>
-              <span style={s.badge}>Coming soon</span>
+              <span style={s.badge}>Code change</span>
             </div>
           ) : (
             <a

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -2039,7 +2039,7 @@ function createBuilderBrowserTool(deps: {
   const entries: Record<string, ActionEntry> = {
     "connect-builder": {
       tool: {
-        description: `Render a Builder.io card inline in the chat. Call this as the first step (no code exploration or planning needed) when the user asks to modify the APP'S OWN SOURCE CODE: add a feature, change the UI chrome, edit a React component, add a route, add an integration, fix a bug in the app itself, or anything else that requires source-file edits while in hosted/production mode. ${extensionRequestGuidance}Do NOT call this for content the app is meant to produce — creating a video, generating a design, drafting an email, building a slide deck, making a dashboard, etc. — those run through the app's own domain actions, not Builder. Do NOT mention 'click Send to Builder' in your response unless this card is already in the conversation. If Builder is connected and Builder Cloud Agents are available, the card shows a 'Send to Builder' button that hands the work off to Builder's cloud agent and returns a branch URL. If \`builderEnabled\` is false, the card shows a waitlist/local-dev fallback instead; never tell the user to enable Builder Cloud Agents in Builder org settings or beta settings, and do not claim the Builder card has everything, is pre-loaded for handoff, or can run the cloud agent. When you call this for a code-change request, pass the user's request verbatim as the \`prompt\` arg so the card can forward it to Builder unchanged when cloud agents are available.`,
+        description: `Render a Builder.io card inline in the chat. Call this as the first step (no code exploration or planning needed) when the user asks to modify the APP'S OWN SOURCE CODE: add a feature, change the UI chrome, edit a React component, add a route, add an integration, fix a bug in the app itself, or anything else that requires source-file edits while in hosted/production mode. ${extensionRequestGuidance}Do NOT call this for content the app is meant to produce — creating a video, generating a design, drafting an email, building a slide deck, making a dashboard, etc. — those run through the app's own domain actions, not Builder. Do NOT mention 'click Send to Builder' in your response unless this card is already in the conversation. The tool result includes \`builderEnabled\`; treat \`true\` as "Builder Cloud Agents can take the code-change handoff" and \`false\` as "this still needs a code change, but no Builder Cloud Agent can run here." If Builder is connected and Builder Cloud Agents are available, the card shows a 'Send to Builder' button that hands the work off to Builder's cloud agent and returns a branch URL. If \`builderEnabled\` is false, the card still renders but shows the code-change fallback: "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like." Never tell the user to enable Builder Cloud Agents in Builder org settings or beta settings, and do not claim the Builder card has everything, is pre-loaded for handoff, or can run the cloud agent when \`builderEnabled\` is false. When you call this for a code-change request, pass the user's request verbatim as the \`prompt\` arg so the card can forward it to Builder unchanged when cloud agents are available.`,
         parameters: {
           type: "object",
           properties: {
@@ -2920,7 +2920,7 @@ Do NOT add this offer for one-shot work: lookups (find Alice, what's the schema,
 
   builder: `### Connecting Builder.io
 
-When the user asks to connect Builder.io or you hit a "Builder not configured" error, call the \`connect-builder\` tool. It renders a one-click Connect card inline — do NOT write out multi-step setup instructions yourself. If Builder Cloud Agents are not available for this workspace, never send the user to Builder org settings or beta settings; use the card's waitlist/local-dev fallback.`,
+When the user asks to connect Builder.io or you hit a "Builder not configured" error, call the \`connect-builder\` tool. It renders a Connect/code-change card inline — do NOT write out multi-step setup instructions yourself. Inspect the returned \`builderEnabled\` flag: \`true\` means Builder Cloud Agents can take the code-change handoff, while \`false\` means this requires a code change and the user should edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like. If Builder Cloud Agents are not available for this workspace, never send the user to Builder org settings or beta settings.`,
 
   browser: `### Browser Automation
 
@@ -3108,14 +3108,14 @@ ${extensionConnectBuilderGuard}
 In Act mode, when the user asks you to change the UI, modify code, add a feature, fix a bug in the app itself, change styles, add a hook, create a component, add a route, add an integration, or anything else that requires editing source files — you MUST take exactly these steps, in order:
 
 1. Briefly acknowledge the user's specific request in their own terms — one short clause naming what they asked for (e.g. "Got it — wider subject lines in the email list."). Do NOT restate the request verbatim, do NOT add a generic preamble, and do NOT promise outcomes. Skip this step entirely if the user already knows you're handing off (e.g. they said "send this to Builder").
-2. Call the \`connect-builder\` tool, passing the user's full request verbatim as the \`prompt\` argument. This renders an inline card. If Builder is connected and \`builderEnabled\` is true, the card hands the prompt off to Builder's cloud agent on one click and returns a branch URL. If Builder is not connected, it shows the Connect Builder flow. If \`builderEnabled\` is false, it shows a waitlist/local-dev fallback instead of a cloud handoff.
-3. After the card renders, inspect the tool result and write one sentence that frames the next click around what the user just asked — not as a Builder pitch. Examples: "Click Send to Builder and it'll wire that up for you." / "Connect Builder once and it'll handle this and future changes." / "Builder Cloud Agents aren't available here yet — join the waitlist in the card, or use the Agent Native Desktop app for local code changes: https://www.agent-native.com/download." Do NOT say the card is pre-loaded, has everything, or lead with "Builder Cloud Agents are…" as if it were the headline.
+2. Call the \`connect-builder\` tool, passing the user's full request verbatim as the \`prompt\` argument. This renders an inline card. The returned \`builderEnabled\` flag is authoritative: \`true\` means Builder Cloud Agents can take the code-change handoff; \`false\` means this still requires a code change, but no Builder Cloud Agent can run from this workspace. If Builder is connected and \`builderEnabled\` is true, the card hands the prompt off to Builder's cloud agent on one click and returns a branch URL. If Builder is not connected and \`builderEnabled\` is true, it shows the Connect Builder flow. If \`builderEnabled\` is false, it still shows the card, but as a code-change fallback instead of a runnable cloud handoff.
+3. After the card renders, inspect the tool result and write one sentence that frames the next click around what the user just asked — not as a Builder pitch. If \`builderEnabled\` is true and the card can send, say something like "Click Send to Builder and it'll wire that up for you." If the user needs to connect first, say something like "Connect Builder once and it'll handle this and future changes." If \`builderEnabled\` is false, say: "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like." Do NOT say "click Send to Builder", mention a branch URL, say the card is pre-loaded, or imply a Builder Cloud Agent can run when \`builderEnabled\` is false.
 
-When \`builderEnabled\` is false, Builder Cloud Agents are not self-serve from Builder org settings. Do NOT tell the user to go to Builder org settings, beta features, "Cloud Agents", or "AI Agents" to enable them. The only allowed guidance is the card's waitlist/local-dev fallback: join the waitlist when the card offers it, use Agent Native Desktop, or edit from a local clone.
+When \`builderEnabled\` is false, Builder Cloud Agents are not self-serve from Builder org settings. Do NOT tell the user to go to Builder org settings, beta features, "Cloud Agents", or "AI Agents" to enable them. The only allowed guidance is the card's code-change fallback: edit locally, use Agent Native Desktop, or use Builder.io to edit this code in the cloud and continue customizing the app any way you like.
 
 **Act-mode handoff — do exactly this:** The moment a code change is requested, call \`connect-builder\` with the user's verbatim request, then write one sentence framing the next click. That is the whole job: Builder plans and edits in its own sandbox, so the planning, file-mapping, and code all happen there, not here. Keep your turn to the call plus that one sentence — skip code exploration, implementation plans, \`resources\` writes of specs, and sub-agents (they have no code-editing tools either). You don't need filesystem access to recommend Builder, so don't reach for it or list tools you lack.
 
-Builder Cloud Agents are the recommended path when available because they are one-click and run in the cloud. Local dev and the desktop app are the fallback when cloud agent access is waitlisted or unavailable.
+Builder Cloud Agents are the recommended path when \`builderEnabled\` is true because they are one-click and run in the cloud. Local dev, Agent Native Desktop, and Builder.io cloud editing are the fallback when \`builderEnabled\` is false.
 ${FRAMEWORK_CORE}`;
 
   const DEV_FRAMEWORK_PROMPT = `## Agent-Native Framework — Development Mode
@@ -3157,7 +3157,7 @@ ${extensionInstructionsCompact}
 
 ### Code Changes — Call \`connect-builder\`
 
-In Act mode, when a request genuinely needs a source-code edit (per the rules above), do this in order: (1) briefly acknowledge the user's specific ask in their own terms — one short clause, no preamble — then (2) call \`connect-builder\` with the user's request as the \`prompt\`, then (3) write one sentence framing the next click around what they asked for, not a Builder pitch. Do NOT write code, list files, make plans, or spawn sub-agents. Mention \`npx agent-native create <app-name>\`, Agent Native Desktop, or the waitlist card as the fallback when Builder Cloud Agents aren't available. Never tell users to enable Builder Cloud Agents from Builder org settings, beta features, "Cloud Agents", or "AI Agents"; they are not self-serve there.
+In Act mode, when a request genuinely needs a source-code edit (per the rules above), do this in order: (1) briefly acknowledge the user's specific ask in their own terms — one short clause, no preamble — then (2) call \`connect-builder\` with the user's request as the \`prompt\`, then (3) inspect \`builderEnabled\` in the result and write one sentence framing the next click around what they asked for, not a Builder pitch. When \`builderEnabled\` is true, Builder Cloud Agents can take the handoff; when \`builderEnabled\` is false, say this requires a code change and they can edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way they like. Do NOT write code, list files, make plans, or spawn sub-agents. Mention \`npx agent-native create <app-name>\`, Agent Native Desktop, or the code-change fallback when Builder Cloud Agents aren't available. Never tell users to enable Builder Cloud Agents from Builder org settings, beta features, "Cloud Agents", or "AI Agents"; they are not self-serve there.
 ${FRAMEWORK_CORE_COMPACT}`;
 
   const DEV_FRAMEWORK_PROMPT_COMPACT = `## Agent-Native Framework — Development Mode

package/corpus/core/src/server/self-dispatch.ts

@@ -150,7 +150,14 @@ export async function fireInternalDispatch(
     }
   });
   dispatchPromise.catch((err) => {
-    console.error(`[self-dispatch] dispatch to ${options.path} failed:`, err);
+    // Include the resolved base URL: a self-dispatch failure is almost always
+    // about *which* host we POST to (custom domain behind an edge/auth wall vs
+    // the deploy URL), and that is invisible from the error alone. Keeps prod
+    // logs diagnostic without changing the URL resolution order.
+    console.error(
+      `[self-dispatch] dispatch to ${options.path} (base ${baseUrl}) failed:`,
+      err,
+    );
   });
 
   const settleMs = options.settleMs ?? DEFAULT_DISPATCH_SETTLE_MS;

package/corpus/templates/analytics/actions/compose-dashboard.ts

@@ -7,10 +7,12 @@ import {
 import { z } from "zod";
 import { getDashboard, upsertDashboard } from "../server/lib/dashboards-store";
 import {
+  buildFirstPartyDashboardFilters,
   buildPanel,
   listMetricKeys,
   type ComposedPanel,
   type MetricWindow,
+  usesFirstPartyDashboardFilters,
 } from "../server/lib/first-party-metric-catalog";
 import { validateFirstPartyAnalyticsSql } from "../server/lib/first-party-analytics.js";
 import {
@@ -97,6 +99,32 @@ const metricSchema = z.union([
 
 const METRIC_KEYS = listMetricKeys();
 
+function filterId(filter: unknown): string | null {
+  if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+    return null;
+  }
+  const id = (filter as { id?: unknown }).id;
+  return typeof id === "string" && id.trim() ? id : null;
+}
+
+function withFirstPartyDashboardFilters(
+  config: Record<string, unknown>,
+): Record<string, unknown> {
+  const filters = Array.isArray(config.filters) ? [...config.filters] : [];
+  const existingIds = new Set(
+    filters
+      .map((filter) => filterId(filter))
+      .filter((id): id is string => id !== null),
+  );
+  for (const filter of buildFirstPartyDashboardFilters()) {
+    if (!existingIds.has(filter.id)) {
+      filters.push(filter);
+      existingIds.add(filter.id);
+    }
+  }
+  return { ...config, filters };
+}
+
 export default defineAction({
   description:
     "Build a large first-party analytics dashboard in ONE fast call: name the metrics you want and the SERVER generates the validated SQL + chart config for every panel. " +
@@ -249,6 +277,12 @@ export default defineAction({
       };
     }
 
+    if (
+      composedPanels.some((panel) => usesFirstPartyDashboardFilters(panel.sql))
+    ) {
+      finalConfig = withFirstPartyDashboardFilters(finalConfig);
+    }
+
     const panelCount = Array.isArray(finalConfig.panels)
       ? (finalConfig.panels as unknown[]).length
       : 0;

package/corpus/templates/analytics/actions/install-dashboard-template.ts

@@ -41,6 +41,49 @@ function uniqueConstraintMessage(err: unknown): boolean {
   return /unique|constraint|primary key/i.test(message);
 }
 
+function filterId(filter: unknown): string | null {
+  if (!filter || typeof filter !== "object" || Array.isArray(filter)) {
+    return null;
+  }
+  const id = (filter as { id?: unknown }).id;
+  return typeof id === "string" && id.trim() ? id : null;
+}
+
+function mergeMissingFilters(
+  targetConfig: Record<string, unknown>,
+  seedConfig: Record<string, unknown>,
+): { config: Record<string, unknown>; addedFilterIds: string[] } {
+  const seedFilters = Array.isArray(seedConfig.filters)
+    ? (seedConfig.filters as unknown[])
+    : [];
+  if (seedFilters.length === 0) {
+    return { config: targetConfig, addedFilterIds: [] };
+  }
+
+  const targetFilters = Array.isArray(targetConfig.filters)
+    ? [...targetConfig.filters]
+    : [];
+  const existingIds = new Set(
+    targetFilters
+      .map((filter) => filterId(filter))
+      .filter((id): id is string => id !== null),
+  );
+  const addedFilterIds: string[] = [];
+  for (const filter of seedFilters) {
+    const id = filterId(filter);
+    if (id && existingIds.has(id)) continue;
+    targetFilters.push(filter);
+    if (id) {
+      existingIds.add(id);
+      addedFilterIds.push(id);
+    }
+  }
+
+  return addedFilterIds.length > 0
+    ? { config: { ...targetConfig, filters: targetFilters }, addedFilterIds }
+    : { config: targetConfig, addedFilterIds };
+}
+
 export default defineAction({
   description:
     "Install a dashboard template from the Analytics catalog into the user's SQL-backed dashboards. Use list-dashboard-templates first when choosing a template. " +
@@ -125,7 +168,10 @@ export default defineAction({
           .filter((id): id is string => !!id),
       );
 
-      const seedConfig = cloneDashboardConfig(entry);
+      const seedConfig = cloneDashboardConfig(entry) as unknown as Record<
+        string,
+        unknown
+      >;
       const seedPanels = Array.isArray(seedConfig.panels)
         ? (seedConfig.panels as unknown as Array<Record<string, unknown>>)
         : [];
@@ -146,13 +192,15 @@ export default defineAction({
         }
       }
 
-      const mergedConfig: Record<string, unknown> = {
+      let mergedConfig: Record<string, unknown> = {
         ...targetConfig,
         panels: [...existingPanels, ...appended],
       };
+      const filterMerge = mergeMissingFilters(mergedConfig, seedConfig);
+      mergedConfig = filterMerge.config;
       const panelCount = (mergedConfig.panels as unknown[]).length;
 
-      if (appended.length > 0) {
+      if (appended.length > 0 || filterMerge.addedFilterIds.length > 0) {
         const saved = await upsertDashboard(
           targetId,
           target.kind,