npm - @agent-native/core - Versions diffs - 0.70.0 → 0.70.1 - Mend

@agent-native/core 0.70.0 → 0.70.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (167) hide show

package/corpus/core/src/mcp/oauth-route.ts CHANGED Viewed

@@ -423,15 +423,23 @@ function redirectWithOAuthError(params: {
   return redirect(url.toString());
 }
-function redirectWithCode(params: {
+function buildCodeRedirectUrl(params: {
   redirectUri: string;
   code: string;
   state?: string;
-}): Response {
+}): string {
   const url = new URL(params.redirectUri);
   url.searchParams.set("code", params.code);
   if (params.state) url.searchParams.set("state", params.state);
-  return redirect(url.toString());
+  return url.toString();
+}
+function redirectWithCode(params: {
+  redirectUri: string;
+  code: string;
+  state?: string;
+}): Response {
+  return redirect(buildCodeRedirectUrl(params));
 }
 function codeChallengeForVerifier(verifier: string): string {
@@ -530,6 +538,19 @@ function isValidCodeVerifier(value: unknown): value is string {
   );
 }
+// Shared styling for the browser-facing OAuth pages (consent + post-authorize
+// confirmation) so they read as one coherent dark surface.
+const OAUTH_PAGE_BASE_STYLE = `
+  :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #09090b; color: #f4f4f5; }
+  body { min-height: 100vh; display: grid; place-items: center; margin: 0; padding: 24px; }
+  main { width: min(520px, 100%); border: 1px solid #27272a; border-radius: 8px; background: #111113; padding: 24px; box-shadow: 0 24px 80px rgba(0,0,0,.35); }
+  h1 { font-size: 22px; line-height: 1.2; margin: 0 0 10px; }
+  p { color: #a1a1aa; line-height: 1.5; margin: 0 0 18px; }
+  .actions { display: flex; gap: 10px; justify-content: flex-end; }
+  button, .btn { border: 0; border-radius: 6px; padding: 10px 14px; font: inherit; font-weight: 650; cursor: pointer; text-decoration: none; display: inline-block; }
+  .primary { background: #f4f4f5; color: #09090b; }
+  .secondary { background: #27272a; color: #f4f4f5; }`;
 function renderConsentPage(params: {
   appName: string;
   email: string;
@@ -552,18 +573,9 @@ function renderConsentPage(params: {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Authorize ${escapeHtml(params.appName)}</title>
-<style>
-  :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #09090b; color: #f4f4f5; }
-  body { min-height: 100vh; display: grid; place-items: center; margin: 0; padding: 24px; }
-  main { width: min(520px, 100%); border: 1px solid #27272a; border-radius: 8px; background: #111113; padding: 24px; box-shadow: 0 24px 80px rgba(0,0,0,.35); }
-  h1 { font-size: 22px; line-height: 1.2; margin: 0 0 10px; }
-  p { color: #a1a1aa; line-height: 1.5; margin: 0 0 18px; }
+<style>${OAUTH_PAGE_BASE_STYLE}
   ul { margin: 0 0 22px; padding-left: 22px; color: #d4d4d8; }
   code { color: #67e8f9; }
-  .actions { display: flex; gap: 10px; justify-content: flex-end; }
-  button { border: 0; border-radius: 6px; padding: 10px 14px; font-weight: 650; cursor: pointer; }
-  .primary { background: #f4f4f5; color: #09090b; }
-  .secondary { background: #27272a; color: #f4f4f5; }
 </style>
 </head>
 <body>
@@ -583,6 +595,61 @@ function renderConsentPage(params: {
 </html>`;
 }
+// Shown after the user approves a native/desktop client (cursor://, vscode://, …)
+// whose redirect is a private-use scheme. A bare 302 to a custom scheme hands the
+// code to the OS app but leaves the browser tab dangling on a blank/error page, so
+// we render a friendly confirmation that also re-fires the deep link (so the client
+// still receives the code) and tells the user they can return to their agent.
+function renderAuthorizedPage(params: {
+  appName: string;
+  clientName: string | null;
+  redirectUrl: string;
+}): string {
+  const friendlyClient = params.clientName?.trim() || null;
+  const returnTarget = friendlyClient ?? "your agent";
+  const openLabel = friendlyClient
+    ? `Open ${escapeHtml(friendlyClient)}`
+    : "Return to your agent";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Authorized</title>
+<style>${OAUTH_PAGE_BASE_STYLE}
+  main.success { text-align: center; }
+  .check { width: 56px; height: 56px; margin: 4px auto 16px; display: grid; place-items: center; border-radius: 999px; background: rgba(34,197,94,.12); }
+  .check svg { width: 30px; height: 30px; }
+  .success .actions { justify-content: center; margin-top: 4px; }
+  .hint { color: #71717a; font-size: 13px; margin: 18px 0 0; }
+</style>
+</head>
+<body>
+<main class="success">
+  <div class="check">
+    <svg viewBox="0 0 24 24" fill="none" stroke="#22c55e" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <path d="M20 6 9 17l-5-5"></path>
+    </svg>
+  </div>
+  <h1>You're all set</h1>
+  <p>${escapeHtml(params.appName)} has authorized ${escapeHtml(returnTarget)}. You can return to ${escapeHtml(returnTarget)} to continue.</p>
+  <div class="actions">
+    <a class="btn primary" id="return-link" href="${escapeHtml(params.redirectUrl)}">${openLabel}</a>
+  </div>
+  <p class="hint">You can close this tab.</p>
+</main>
+<script>
+  (function () {
+    var link = document.getElementById("return-link");
+    if (link && link.href) {
+      try { window.location.href = link.href; } catch (e) {}
+    }
+  })();
+</script>
+</body>
+</html>`;
+}
 async function resolveOrgDomain(
   orgId: string | undefined,
 ): Promise<string | undefined> {
@@ -744,6 +811,35 @@ async function handleAuthorize(
     scope,
     resource,
   });
+  // Native/desktop clients register a private-use scheme (cursor://, vscode://, …).
+  // A 302 to that scheme opens the app but leaves the browser tab dangling, so we
+  // render a friendly confirmation page that re-fires the deep link instead. For
+  // https/loopback callbacks the client (or its local server) renders its own page,
+  // so keep the standard redirect there.
+  let isDeepLinkRedirect = false;
+  try {
+    const protocol = new URL(redirectUri).protocol;
+    isDeepLinkRedirect =
+      protocol !== "http:" &&
+      protocol !== "https:" &&
+      isPrivateUseRedirectScheme(protocol);
+  } catch {
+    isDeepLinkRedirect = false;
+  }
+  if (isDeepLinkRedirect) {
+    return html(
+      renderAuthorizedPage({
+        appName: options.appName || options.appId || "Agent Native",
+        clientName: client.clientName ?? null,
+        redirectUrl: buildCodeRedirectUrl({
+          redirectUri,
+          state,
+          code: code.code,
+        }),
+      }),
+    );
+  }
   return redirectWithCode({ redirectUri, state, code: code.code });
 }

package/corpus/core/src/server/core-routes-plugin.ts CHANGED Viewed

@@ -32,6 +32,7 @@ import {
   MCP_EMBED_CORS_ALLOW_HEADERS,
   shouldAllowMcpEmbedCredentials,
 } from "../shared/mcp-embed-headers.js";
+import { captureError } from "./capture-error.js";
 import { handleMcpConnect } from "../mcp/connect-route.js";
 import {
   handleMcpOAuth,
@@ -3161,6 +3162,83 @@ export function createCoreRoutesPlugin(
           `${P}/embed/start`,
           createEmbedStartRouteHandler({ getExistingSession: getSession }),
         );
+        // POST /_agent-native/mcp/embed-error — telemetry sink for MCP App
+        // embed shells. The shell runs in a sandboxed, opaque-origin iframe
+        // (Codex, Cursor, ChatGPT, Claude) with no session cookie or CSRF
+        // token, so this endpoint is intentionally unauthenticated and
+        // CORS-open to the SAME sandbox origins as /embed/start. It forwards a
+        // small, bounded diagnostic payload to Sentry via captureError so we
+        // can see *why* an inline embed failed (handshake timeout, transplant
+        // fetch status/CORS, auth, CSP) per host. Best-effort: always 204,
+        // never throws, body capped, no client-trusted identity.
+        getH3App(nitroApp).use(
+          `${P}/mcp/embed-error`,
+          defineEventHandler(async (event: H3Event) => {
+            const origin = getHeader(event, "origin");
+            if (origin && isMcpEmbedCorsOrigin(origin)) {
+              setResponseHeader(event, "Access-Control-Allow-Origin", origin);
+              setResponseHeader(event, "Vary", "Origin");
+              setResponseHeader(
+                event,
+                "Access-Control-Allow-Methods",
+                "POST,OPTIONS",
+              );
+              setResponseHeader(
+                event,
+                "Access-Control-Allow-Headers",
+                MCP_EMBED_CORS_ALLOW_HEADERS,
+              );
+            }
+            const method = getMethod(event);
+            if (method === "OPTIONS") {
+              setResponseStatus(event, 204);
+              return "";
+            }
+            if (method !== "POST") {
+              setResponseStatus(event, 405);
+              return { error: "Method not allowed" };
+            }
+            const body = await readBody(event).catch(() => undefined);
+            const rec =
+              body && typeof body === "object" && !Array.isArray(body)
+                ? (body as Record<string, unknown>)
+                : {};
+            const str = (value: unknown, max: number): string | undefined =>
+              typeof value === "string" && value
+                ? value.slice(0, max)
+                : undefined;
+            const message = str(rec.message, 500) ?? "MCP embed failed";
+            try {
+              captureError(new Error(message), {
+                route: `${P}/mcp/embed-error`,
+                method: "POST",
+                userAgent:
+                  str(rec.userAgent, 300) ?? getHeader(event, "user-agent"),
+                tags: {
+                  source: "mcp-embed-shell",
+                  embed_stage: str(rec.stage, 60),
+                  embed_render_mode: str(rec.renderMode, 40),
+                  embed_host: str(rec.host, 160),
+                  embed_bridge: str(rec.bridge, 40),
+                },
+                extra: {
+                  embedUrl: str(rec.url, 600),
+                  httpStatus:
+                    typeof rec.status === "number"
+                      ? rec.status
+                      : str(rec.status, 40),
+                  detail: str(rec.detail, 1200),
+                  origin,
+                },
+              });
+            } catch {
+              // Observability must never throw back into the request path.
+            }
+            setResponseStatus(event, 204);
+            return "";
+          }),
+        );
       }
       if (!options.disableAppState) {

package/corpus/core/src/server/onboarding-html.ts CHANGED Viewed

@@ -1191,6 +1191,7 @@ ${
       }
     }
     function __anFinishOAuthExchange(ret, flowId, sessionToken) {
+      __anGoogleSignInInFlight = false;
       if (__anIsBuilderPreview()) {
         if (sessionToken) {
           __anSetOAuthDebug('OAuth exchange redeemed; applying session bridge to embedded app', flowId);
@@ -1361,6 +1362,8 @@ ${identitySsoScript}
     }
     var __anOAuthPollTimer = null;
     var __anOAuthPollCount = 0;
+    var __anGoogleSignInInFlight = false;
+    var __anGoogleRecoverBound = false;
     function __anNewOAuthFlowId() {
       try {
         if (window.crypto && typeof window.crypto.randomUUID === 'function') {
@@ -1401,6 +1404,34 @@ ${identitySsoScript}
       err.textContent = message;
       err.classList.add('show');
       btn.disabled = false;
+      __anGoogleSignInInFlight = false;
+    }
+    function __anRecoverGoogleSignInAfterReturn() {
+      // The user left for the Google sign-in window and came back. If the flow
+      // never completed (e.g. they closed the window to switch profiles), the
+      // button is stuck disabled with no error path firing for up to 5 minutes.
+      // Re-enable it so they can retry. Wait briefly first so a genuinely
+      // in-flight exchange can still finish and navigate without a flicker.
+      if (!__anGoogleSignInInFlight) return;
+      setTimeout(function() {
+        if (!__anGoogleSignInInFlight) return;
+        var btn = document.getElementById('google-btn');
+        if (!btn || !btn.disabled) return;
+        if (__anOAuthPollTimer) {
+          clearInterval(__anOAuthPollTimer);
+          __anOAuthPollTimer = null;
+        }
+        btn.disabled = false;
+        __anGoogleSignInInFlight = false;
+      }, 1200);
+    }
+    function __anBindGoogleRecover() {
+      if (__anGoogleRecoverBound) return;
+      __anGoogleRecoverBound = true;
+      window.addEventListener('focus', __anRecoverGoogleSignInAfterReturn);
+      document.addEventListener('visibilitychange', function() {
+        if (document.visibilityState === 'visible') __anRecoverGoogleSignInAfterReturn();
+      });
     }
     function __anHandlePopupOAuthFailure(ret, btn, err, flowId, redirectReason, builderFrameMessage) {
       if (__anIsBuilderPreview() && __anIsInFrame()) {
@@ -2013,6 +2044,8 @@ ${
     var err = document.getElementById('google-err');
     var ret = __anGetReturnPath();
     btn.disabled = true;
+    __anGoogleSignInInFlight = true;
+    __anBindGoogleRecover();
     err.classList.remove('show');
     if (__anResolveAuthFlow() === 'popup') {
       __anStartPopupOAuth(ret, btn, err);
@@ -2037,11 +2070,13 @@ ${
         err.textContent = data.message || 'Google OAuth is not configured.';
         err.classList.add('show');
         btn.disabled = false;
+        __anGoogleSignInInFlight = false;
       }
     } catch (e) {
       err.textContent = 'Failed to connect. Please try again.';
       err.classList.add('show');
       btn.disabled = false;
+      __anGoogleSignInInFlight = false;
     }
   }`
     : ""

package/corpus/core/src/templates/workspace-core/.agents/skills/reliable-mutations/SKILL.md ADDED Viewed

@@ -0,0 +1,72 @@
+---
+name: reliable-mutations
+description: >-
+  How the agent must perform writes so they actually persist under the hosted
+  ~40s run budget. Use whenever you create, update, delete, or batch-write app
+  data — especially "do this for many items" loops, or any task where the user
+  expects N things to end up saved.
+---
+# Reliable Mutations
+## Rule
+Make a change in **one atomic call** when the action supports it, then **verify
+the persisted end state and report concrete proof** (counts/ids). Never drive a
+multi-step change by looping many small writes, and never report success from a
+tool ✓ alone.
+## Why
+Hosted agent runs have a ~40s soft budget (it exists to hand off cleanly under
+the upstream gateway/function walls — it is correct and is not raisable; see the
+durable-agent-runs design doc). When you loop many sequential writes inside one
+turn, the budget can cut you off mid-loop. The run resumes in a new chunk, but
+the resume often re-does earlier steps instead of advancing, so the loop churns
+and the *saved* result ends up partial — or empty — even though each individual
+tool call appeared to succeed. The user gets told "done" while the data says
+otherwise. One atomic call commits or fails as a unit; verification turns a
+hopeful ✓ into a fact.
+## How
+1. **Prefer a single atomic call.** If an action accepts the whole set (add
+   many, set all, bulk update), pass the full batch in one call so it commits
+   atomically. Check the action surface for a batch/plural form before reaching
+   for a loop.
+2. **Do not loop many small writes under the run budget.** A sequence of N
+   per-item writes in one turn will race the ~40s cutoff and can leave partial
+   or no state. If no batch action exists, that is a gap in the action layer —
+   add or extend an action that accepts the batch (see the `actions` skill)
+   rather than papering over it with a loop.
+3. **Verify the end state after writing.** Re-read the data (a list/read action,
+   a count query) and confirm the result matches intent — the right number of
+   rows, the expected ids/fields. Do this before you tell the user it worked.
+4. **Report proof-of-done, not vibes.** State concrete evidence: "saved 12 of 12
+   panels (ids …)" or "updated 5 rows". Do not infer success from the presence
+   of a tool ✓ on an individual call.
+5. **On a time-budget cutoff, fail loud.** If the turn is cut before the change
+   is fully committed and verified, say so explicitly and report what *did*
+   persist (M of N) and what remains. Never round a partial or unverified write
+   up to "done".
+## Don't
+- Don't loop `for each item: write(item)` for a large set in a single hosted
+  turn.
+- Don't claim completion because every tool call returned ✓ — a ✓ on an aborted
+  chunk does not mean the row was committed.
+- Don't silently shrink the scope ("I added a few of them") and present it as the
+  finished task.
+- Don't try to "fix" this by asking for a longer run timeout — the budget is
+  correct; restructure the write instead.
+## Related
+- `actions` — define or extend a batch/atomic action when only per-item writes
+  exist.
+- `storing-data` — where app data lives and how reads/writes are scoped.
+- `performance` — avoid query waterfalls when verifying end state.
+- Design doc: `packages/core/docs/design/durable-agent-runs.md` — the real
+  ceiling fix (checkpointed and durable runs); this skill is the agent-facing
+  mitigation that reduces how often the ceiling is hit.

package/corpus/templates/analytics/.agents/skills/dashboard-management/SKILL.md CHANGED Viewed

@@ -174,6 +174,28 @@ pnpm action update-dashboard --dashboardId weekly-metrics --config '<full json>'
 After a mutation, navigate to the dashboard if the user is elsewhere. The app syncs through the framework's polling/query invalidation path.
+## Reliable Bulk Edits
+This is the dashboard-specific application of the framework-wide `reliable-mutations` skill — read that for the general rule (one atomic write, verify end state, report proof-of-done).
+Hosted agent runs have a **~40s budget**. Many sequential `update-dashboard` calls (one per panel, plus schema-discovery calls) will blow that budget and leave the dashboard in a partial state — earlier inserts looked like they succeeded (✓), but nothing actually persisted. Avoid this:
+- **Batch ALL changes into ONE `update-dashboard` call.** A single `update-dashboard` is atomic: it applies every op to an in-memory config, validates all panel SQL, then upserts once. Never loop the action.
+  - To add N panels, pass N ops in one call: `ops: [{op:"insert", path:"/panels/-", value:<panel>}, … ]` (`/panels/-` appends to the end).
+  - The `ops` format needs no discovery: each op is `{ op, path, from?, value? }`, `op ∈ set | replace | remove | insert | move | move-before`, and `path` is a JSON Pointer (e.g. `/panels/3`, `/panels/3/title`, `/name`).
+- **To add a shipped template's panels, prefer `install-dashboard-template` with `mergePanels: true`** and the existing `dashboardId`. It appends only the template panels whose id is not already present (preserving existing panels and order) in one atomic save — you don't author each panel yourself.
+- **Always verify the returned proof-of-done and report it.** `update-dashboard` returns `panelCount`, `appliedOps`, and a `summary` string; `install-dashboard-template --mergePanels` returns `addedPanelIds`, `skippedExistingIds`, and `panelCount`. Tell the user the resulting panel count instead of assuming success.
+```bash
+# Add several panels in ONE atomic call (never one call per panel)
+pnpm action update-dashboard --dashboardId weekly-metrics \
+  --ops '[{"op":"insert","path":"/panels/-","value":{"id":"p1","title":"A","source":"first-party","chartType":"metric","width":1,"sql":"SELECT COUNT(*) AS value FROM analytics_events"}},
+          {"op":"insert","path":"/panels/-","value":{"id":"p2","title":"B","source":"first-party","chartType":"metric","width":1,"sql":"SELECT COUNT(DISTINCT user_id) AS value FROM analytics_events"}}]'
+# Append a template's panels to an existing dashboard in one call
+pnpm action install-dashboard-template --templateId skills-cli-funnel --dashboardId weekly-metrics --mergePanels true
+```
 ## Archiving vs deleting
 Dashboards have a soft-delete state. The default user-facing destructive action is **Archive** (recoverable). Hard delete still exists, but lives behind a "Delete permanently" confirm in both the page header and the sidebar dropdown — and in the agent surface, behind the older `delete-dashboard` action. Archived rows stay in the `dashboards` table with `archived_at` set, are hidden from the default sidebar list, and remain accessible by id (so deep links in chat history keep working) until explicitly purged.

package/corpus/templates/analytics/AGENTS.md CHANGED Viewed

@@ -87,7 +87,14 @@ details live in `.agents/skills/`.
   `id`, category, data sources, panel count, and installed dashboard IDs.
 - `install-dashboard-template` installs a catalog template into normal
   SQL-backed dashboards. Required: `templateId`. Optional: `dashboardId`,
-  `name`, `overwrite`, and `forceNew`.
+  `name`, `overwrite`, `forceNew`, and `mergePanels`.
+- To add a template's panels to an existing dashboard, call
+  `install-dashboard-template` with `mergePanels: true` and the existing
+  `dashboardId`. It appends only the template panels whose id is not already
+  present (preserving existing panels and order) in one atomic save and returns
+  `{ addedPanelIds, skippedExistingIds, panelCount }`. Prefer this over looping
+  `update-dashboard` to add many panels — sequential calls time out on the ~40s
+  hosted run budget.
 - Node Exporter ships as `node-exporter-macos` for Darwin/Homebrew
   `node_exporter` scrapes and `node-exporter-full` for the Linux-focused
   Grafana 1860 revision 45 full dashboard converted into native Analytics

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

@@ -43,7 +43,8 @@ function uniqueConstraintMessage(err: unknown): boolean {
 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.",
+    "Install a dashboard template from the Analytics catalog into the user's SQL-backed dashboards. Use list-dashboard-templates first when choosing a template. " +
+    "To ADD a template's panels to an EXISTING dashboard in ONE call (the preferred way to bulk-add panels), pass `mergePanels: true` with the `dashboardId` of the existing dashboard: it appends every template panel whose id is not already present, preserves all existing panels and their order, and saves once. This avoids looping update-dashboard, which times out on the ~40s hosted run budget.",
   schema: z.object({
     templateId: z
       .string()
@@ -52,7 +53,7 @@ export default defineAction({
       .string()
       .optional()
       .describe(
-        "Optional dashboard id to write. Omit to reuse an existing installed copy or create a unique id.",
+        "Optional dashboard id to write. Omit to reuse an existing installed copy or create a unique id. Required when mergePanels is true.",
       ),
     name: z
       .string()
@@ -70,6 +71,12 @@ export default defineAction({
       .describe(
         "If true, create another copy even when this template is installed.",
       ),
+    mergePanels: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true AND a dashboard already exists at dashboardId, APPEND this template's panels (only the ones whose id is not already present) to the existing dashboard in one atomic save, preserving all existing panels and their order. Returns { addedPanelIds, skippedExistingIds, panelCount }. Non-destructive; does not change overwrite/forceNew behavior.",
+      ),
   }),
   mcpApp: {
     compactCatalog: true,
@@ -90,6 +97,94 @@ export default defineAction({
     if (!entry)
       throw new Error(`Unknown dashboard template: ${args.templateId}`);
+    // Append/merge mode: add this template's panels to an existing dashboard
+    // in ONE atomic save instead of looping update-dashboard (which times out
+    // on the ~40s hosted run budget). Non-destructive: existing panels and
+    // their order are preserved; only template panels with a new id are added.
+    if (args.mergePanels) {
+      const targetId = args.dashboardId?.trim();
+      if (!targetId) {
+        throw new Error(
+          "mergePanels=true requires dashboardId (the existing dashboard to append the template's panels to).",
+        );
+      }
+      const target = await getDashboard(targetId, ctx);
+      if (!target) {
+        throw new Error(
+          `Dashboard "${targetId}" not found (or you don't have access). mergePanels appends to an existing dashboard — install the template normally first, or omit mergePanels to create a new copy.`,
+        );
+      }
+      const targetConfig = target.config as Record<string, unknown>;
+      const existingPanels = Array.isArray(targetConfig.panels)
+        ? (targetConfig.panels as Array<Record<string, unknown>>)
+        : [];
+      const existingIds = new Set(
+        existingPanels
+          .map((panel) => (typeof panel?.id === "string" ? panel.id : null))
+          .filter((id): id is string => !!id),
+      );
+      const seedConfig = cloneDashboardConfig(entry);
+      const seedPanels = Array.isArray(seedConfig.panels)
+        ? (seedConfig.panels as unknown as Array<Record<string, unknown>>)
+        : [];
+      const addedPanelIds: string[] = [];
+      const skippedExistingIds: string[] = [];
+      const appended: Array<Record<string, unknown>> = [];
+      for (const panel of seedPanels) {
+        const id = typeof panel?.id === "string" ? panel.id : null;
+        if (id && existingIds.has(id)) {
+          skippedExistingIds.push(id);
+          continue;
+        }
+        appended.push(panel);
+        if (id) {
+          addedPanelIds.push(id);
+          existingIds.add(id);
+        }
+      }
+      const mergedConfig: Record<string, unknown> = {
+        ...targetConfig,
+        panels: [...existingPanels, ...appended],
+      };
+      const panelCount = (mergedConfig.panels as unknown[]).length;
+      if (appended.length > 0) {
+        const saved = await upsertDashboard(
+          targetId,
+          target.kind,
+          mergedConfig,
+          ctx,
+        );
+        await syncToCollab(targetId, mergedConfig);
+        targetConfig.name = saved.title;
+      }
+      return {
+        templateId: entry.id,
+        templateName: entry.name,
+        dashboardId: targetId,
+        name: target.title,
+        merged: true,
+        addedPanelIds,
+        skippedExistingIds,
+        panelCount,
+        urlPath: `/dashboards/${targetId}`,
+        deepLink: buildDeepLink({
+          app: "analytics",
+          view: "adhoc",
+          params: { dashboardId: targetId },
+        }),
+        message:
+          appended.length > 0
+            ? `Added ${addedPanelIds.length} panel(s) from "${entry.name}" to "${target.title}"; ${skippedExistingIds.length} already present. Dashboard now has ${panelCount} panel(s).`
+            : `No new panels to add from "${entry.name}" — all ${skippedExistingIds.length} template panel id(s) already present. Dashboard has ${panelCount} panel(s).`,
+      };
+    }
     const installed = (await listDashboardCatalog(ctx)).find(
       (template) => template.id === entry.id,
     );