@agent-native/core 0.101.11 → 0.101.12

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.101.12
+
+### Patch Changes
+
+- 2ff004e: Fix workspace-file resolution and run-code paging/routing edge cases. `contentFromWorkspaceFile` now resolves the same file the run-code `workspaceRead`/`workspaceWrite` bridge sees (bridge scope first, then Resources), and fails closed on a bridge read error instead of silently falling back to a possibly-different same-path Resources body. `workspaceRead` returns null instead of a silently truncated prefix when a later page fails, and the run-code bridge now returns a distinct "not registered" (404) error for unknown tools instead of a misleading read-only access error.
+
 ## 0.101.11
 
 ### Patch Changes

package/corpus/core/package.json

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

package/corpus/core/src/coding-tools/run-code.ts

@@ -740,8 +740,18 @@ function handleBridgeRequest(
 
   // Enforce allowlist.
   const entry = actions[toolName];
+  // Unknown/mistyped tool: report "not registered" (404) before the
+  // access-control branch below. Otherwise an undefined `entry` falls into the
+  // allowlist 403 and returns a misleading access error for a tool that simply
+  // does not exist. (Bridge-allowlisted tools always have an entry, so this
+  // cannot mask a legitimate allowlisted call.)
+  if (!entry) {
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: `Tool "${toolName}" is not registered.` }));
+    return;
+  }
   const isReadOnlyAction =
-    entry?.readOnly === true &&
+    entry.readOnly === true &&
     entry.agentTool !== false &&
     entry.toolCallable !== false;
   if (
@@ -749,21 +759,24 @@ function handleBridgeRequest(
     !extraTools.has(toolName) &&
     !isReadOnlyAction
   ) {
+    // A registered, agent-exposed action that isn't read-only is a mutation.
+    // (Unknown tools already returned 404 above, so `entry` is defined here.)
+    // Point the caller at the native tool path instead of leaving them to guess
+    // (the common trap: retrying create-extension/update-extension through
+    // appAction, which cannot work).
+    const isMutatingAction =
+      entry.agentTool !== false && entry.readOnly !== true;
     res.writeHead(403, { "Content-Type": "application/json" });
     res.end(
       JSON.stringify({
-        error: `Tool "${toolName}" is not an agent-exposed read-only action or sandbox bridge allowlisted tool.`,
+        error: isMutatingAction
+          ? `Tool "${toolName}" is a mutating action and cannot be called from run-code (appAction only exposes read-only actions). Call "${toolName}" directly as a native tool. For large content bodies, stage the content and pass "contentFromAttachment" instead of an inline string rather than routing it through run-code.`
+          : `Tool "${toolName}" is not an agent-exposed read-only action or sandbox bridge allowlisted tool.`,
       }),
     );
     return;
   }
 
-  if (!entry) {
-    res.writeHead(404, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: `Tool "${toolName}" is not registered.` }));
-    return;
-  }
-
   const toolArgs = parsed.args ?? {};
   usedTools.add(toolName);
   // Run the tool with the parent request context so auth/org/owner resolution
@@ -1534,12 +1547,52 @@ async function webRead(url, init = {}) {
 /**
  * Read a Resources-backed workspace file by path. Returns the file content as
  * a string, or null if not found.
- * Supports optional offset and maxChars for paging large files.
+ *
+ * By default this returns the WHOLE file: the underlying store caps a single
+ * read at 100k chars, so this auto-pages across chunks and concatenates them,
+ * so callers never get a silently truncated body. Pass an explicit \`offset\`
+ * or \`maxChars\` to take manual control of a single page instead.
  */
 async function workspaceRead(path, opts = {}) {
-  const parsed = await workspaceReadMeta(path, opts);
-  if (parsed && parsed.ok === false) return null;
-  return parsed && typeof parsed.content === "string" ? parsed.content : null;
+  // Explicit paging requested → single read, caller owns the window.
+  if (opts.offset !== undefined || opts.maxChars !== undefined) {
+    const parsed = await workspaceReadMeta(path, opts);
+    if (parsed && parsed.ok === false) return null;
+    return parsed && typeof parsed.content === "string" ? parsed.content : null;
+  }
+  // Default → assemble the full file by paging until the store reports no more.
+  let offset = 0;
+  let out = "";
+  let found = false;
+  let complete = false;
+  // Bounded loop (files cap at 2 MB / 100k-char reads) so a misbehaving store
+  // can never spin forever.
+  for (let i = 0; i < 512; i++) {
+    const parsed = await workspaceReadMeta(path, { offset, maxChars: 100000 });
+    // A failed/missing page aborts. If it failed before the first page we never
+    // found the file (return null below); if it failed part-way through a
+    // truncated read, complete stays false and we return null rather than a
+    // silently truncated body.
+    if (!parsed || parsed.ok === false) break;
+    found = true;
+    const chunk = typeof parsed.content === "string" ? parsed.content : "";
+    out += chunk;
+    if (!parsed.truncated) {
+      complete = true;
+      break;
+    }
+    const next =
+      typeof parsed.nextOffset === "number"
+        ? parsed.nextOffset
+        : offset + chunk.length;
+    if (next <= offset) break; // no forward progress; stop rather than loop
+    offset = next;
+  }
+  if (!found) return null;
+  // Only hand back a body we know is whole. A truncated read followed by a
+  // failed/stalled page would otherwise corrupt a large clone with a partial
+  // prefix and no error signal.
+  return complete ? out : null;
 }
 
 /**

package/corpus/core/src/extensions/actions.ts

@@ -3,8 +3,17 @@ import type { ActionRunContext } from "../action.js";
 import type { ActionEntry } from "../agent/production-agent.js";
 import type { AgentChatAttachment } from "../agent/types.js";
 import { writeAppState } from "../application-state/script-helpers.js";
-import { getRequestRunContext } from "../server/request-context.js";
+import { readResource } from "../resources/script-helpers.js";
+import {
+  getRequestOrgId,
+  getRequestRunContext,
+  getRequestUserEmail,
+} from "../server/request-context.js";
 import { resolveAccess } from "../sharing/access.js";
+import {
+  readWorkspaceFile,
+  type WorkspaceFilesScope,
+} from "../workspace-files/store.js";
 import type {
   ExtensionContentEdit,
   ExtensionLegacyPatch,
@@ -483,7 +492,7 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
     "create-extension": {
       tool: {
         description:
-          'Create a persisted sandboxed Alpine.js mini-app extension and render it inline in the chat. Use this when the user wants generated UI that should be saved, reusable, or visible in the Extensions view: extensions, widgets, dashboards, calculators, mini-apps, and reusable interactive utilities. For one-time chat-only UI, use render-inline-extension instead. The content must be a self-contained Alpine.js HTML body snippet that can use appAction(), appFetch(), dbQuery(), extensionFetch(), extensionData, agentNative.ui.output(value, opts?), and agentNative.chat.send()/sendToAgentChat(). Use appAction() for app data writes and extensionData for extension-owned persisted UI state; dbQuery() is for read-only inspection of known app SQL tables. Use agentNative.ui.output for passive current values from knobs, sliders, and selections; it writes application state at inline-ui:<extension id>:output, which the agent can read later with readAppState when the user says to use that value. Use agentNative.chat.send for visible submit/apply actions. Persist reusable user-edited state with extensionData: if the extension has checkboxes, todos, notes, filters, preferences, or any control whose value should survive reload/reopen, load that state on init and save changes with extensionData, usually at user scope, instead of keeping it only in Alpine state. IMPORTANT — hosting a pasted file: if the user pasted a large HTML/Alpine file (it appears in your context as an <attachment name="pasted-text-…"> block) and asked you to host it as-is, do NOT copy that file into `content`. Instead leave `content` empty and pass `contentFromAttachment` set to that attachment\'s name (or the literal "latest" for the most recent pasted block) — the server reads the file verbatim. Re-emitting a large pasted file as `content` regularly gets cut off mid-stream and stalls the turn. Prefer appAction(name, params) for app data and actions, including read actions mounted as GET; do not call template /api/* routes from appFetch because the extension bridge only allows framework /_agent-native/* paths. Parse JSON string action results before aggregating; use dbQuery() only for known existing SQL tables and never for writes. Keep the initial create-extension payload compact and working; for complex extensions, create a useful v1 first, then use focused update-extension edits for refinements rather than assembling one enormous initial tool input. For any non-trivial component (more than a couple of state fields, any methods, any string formatting, any branching) put the component in a <script> block via Alpine.data(\'name\', () => ({...})) and reference it with x-data="name" — do NOT cram methods, template literals, or branching logic into an inline x-data="{...}" attribute (HTML parser pitfalls cause ReferenceError failures). Define every variable referenced from x-text/x-show/x-if/x-for on the data object\'s initial state. If the extension\'s value depends on an LLM call, require a real key via \\${keys.OPENAI_API_KEY}/\\${keys.ANTHROPIC_API_KEY} (and tell the user to add it in the Dispatch Vault, or in app Settings → API Keys & Connections for standalone apps, if missing) or route the AI work to the agent chat — never ship a stubbed analysis step that renders a placeholder/boolean as the result.',
+          'Create a persisted sandboxed Alpine.js mini-app extension and render it inline in the chat. Use this when the user wants generated UI that should be saved, reusable, or visible in the Extensions view: extensions, widgets, dashboards, calculators, mini-apps, and reusable interactive utilities. For one-time chat-only UI, use render-inline-extension instead. The content must be a self-contained Alpine.js HTML body snippet that can use appAction(), appFetch(), dbQuery(), extensionFetch(), extensionData, agentNative.ui.output(value, opts?), and agentNative.chat.send()/sendToAgentChat(). Use appAction() for app data writes and extensionData for extension-owned persisted UI state; dbQuery() is for read-only inspection of known app SQL tables. Use agentNative.ui.output for passive current values from knobs, sliders, and selections; it writes application state at inline-ui:<extension id>:output, which the agent can read later with readAppState when the user says to use that value. Use agentNative.chat.send for visible submit/apply actions. Persist reusable user-edited state with extensionData: if the extension has checkboxes, todos, notes, filters, preferences, or any control whose value should survive reload/reopen, load that state on init and save changes with extensionData, usually at user scope, instead of keeping it only in Alpine state. IMPORTANT — hosting a pasted file: if the user pasted a large HTML/Alpine file (it appears in your context as an <attachment name="pasted-text-…"> block) and asked you to host it as-is, do NOT copy that file into `content`. Instead leave `content` empty and pass `contentFromAttachment` set to that attachment\'s name (or the literal "latest" for the most recent pasted block) — the server reads the file verbatim. Re-emitting a large pasted file as `content` regularly gets cut off mid-stream and stalls the turn. IMPORTANT — cloning a large extension that lives as a workspace resource (not a chat attachment): leave `content` empty and pass `contentFromWorkspaceFile` set to the resource path (e.g. "intuit-analytics-extension.html"); the server reads the full file. Do NOT try to reconstruct the body with run-code or route create-extension through run-code (mutating actions are not callable there). Prefer appAction(name, params) for app data and actions, including read actions mounted as GET; do not call template /api/* routes from appFetch because the extension bridge only allows framework /_agent-native/* paths. Parse JSON string action results before aggregating; use dbQuery() only for known existing SQL tables and never for writes. Keep the initial create-extension payload compact and working; for complex extensions, create a useful v1 first, then use focused update-extension edits for refinements rather than assembling one enormous initial tool input. For any non-trivial component (more than a couple of state fields, any methods, any string formatting, any branching) put the component in a <script> block via Alpine.data(\'name\', () => ({...})) and reference it with x-data="name" — do NOT cram methods, template literals, or branching logic into an inline x-data="{...}" attribute (HTML parser pitfalls cause ReferenceError failures). Define every variable referenced from x-text/x-show/x-if/x-for on the data object\'s initial state. If the extension\'s value depends on an LLM call, require a real key via \\${keys.OPENAI_API_KEY}/\\${keys.ANTHROPIC_API_KEY} (and tell the user to add it in the Dispatch Vault, or in app Settings → API Keys & Connections for standalone apps, if missing) or route the AI work to the agent chat — never ship a stubbed analysis step that renders a placeholder/boolean as the result.',
         parameters: {
           type: "object",
           properties: {
@@ -506,6 +515,11 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
               description:
                 'Host a pasted/attached file verbatim WITHOUT re-typing it. Set this to the name of an attachment on the current turn (e.g. "pasted-text-1718000000000-ab12cd.txt") or the literal "latest" for the most recent pasted block; the server resolves it into the extension content. Use this instead of `content` whenever the user pasted a large file to host — it avoids re-emitting thousands of tokens. When set, leave `content` empty.',
             },
+            contentFromWorkspaceFile: {
+              type: "string",
+              description:
+                'Host a workspace/shared resource file verbatim WITHOUT re-typing it. Set this to the resource path (e.g. "intuit-analytics-extension.html"); the server reads the full file and uses it as the extension content. Use this — NOT run-code or contentFromAttachment — when cloning a large extension body that already exists as a workspace resource. When set, leave `content` empty.',
+            },
             icon: {
               type: "string",
               description: "Optional icon name or short label.",
@@ -521,7 +535,7 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
       run: async (args, ctx) => {
         const name = String(args?.name ?? "").trim();
         if (!name) return "Error: name is required.";
-        const resolved = resolveExtensionContent(args, ctx);
+        const resolved = await resolveExtensionContentAsync(args, ctx);
         if ("error" in resolved) return resolved.error;
         const content = resolved.content.trim();
         if (!content) return "Error: content is required.";
@@ -553,9 +567,12 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
           } catch {
             // Non-fatal — agent can still mention the path in its reply.
           }
+          const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
           return {
             ok: true,
-            extension: { ...existing, path: existingPath },
+            // Compact summary (contentLength + contentHash, no full body). Echoing
+            // the whole HTML back is pure token waste — the agent just supplied it.
+            extension: await summarizeExtension(existing, hiddenIds, false),
             path: existingPath,
             next: `Extension was already created in this session (recovered from a connection retry). The user is being navigated to it — no further navigation tool calls needed.`,
           };
@@ -585,9 +602,12 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
           // Non-fatal — agent can still mention the path in its reply.
         }
 
+        const hiddenIds = await getHiddenExtensionIdsForCurrentUser();
         return {
           ok: true,
-          extension: { ...extension, path },
+          // Compact summary (contentLength + contentHash, no full body). Echoing
+          // the whole HTML back is pure token waste — the agent just supplied it.
+          extension: await summarizeExtension(extension, hiddenIds, false),
           path,
           next: `Created. The user is being navigated to the new extension automatically — no further navigation tool calls needed.`,
         };
@@ -624,6 +644,11 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
               description:
                 'Optional full replacement sourced from a pasted/attached file on the current turn, by attachment name (or the literal "latest" for the most recent pasted block). Use instead of `content` when replacing the whole body with a large pasted file so you do not have to re-type it. Ignored when `content` is provided.',
             },
+            contentFromWorkspaceFile: {
+              type: "string",
+              description:
+                'Optional full replacement sourced from a workspace/shared resource file, by resource path (e.g. "intuit-analytics-extension.html"). The server reads the full file and uses it as the replacement body. Use instead of `content` when replacing the whole body with a large file that exists as a workspace resource. Ignored when `content` is provided.',
+            },
             patches: {
               type: "string",
               description:
@@ -670,9 +695,10 @@ export function createExtensionActionEntries(): Record<string, ActionEntry> {
             : undefined;
         if (
           replacementContent === undefined &&
-          args?.contentFromAttachment !== undefined
+          (args?.contentFromAttachment !== undefined ||
+            args?.contentFromWorkspaceFile !== undefined)
         ) {
-          const resolved = resolveExtensionContent(args, ctx);
+          const resolved = await resolveExtensionContentAsync(args, ctx);
           if ("error" in resolved) return resolved.error;
           replacementContent = resolved.content;
         }
@@ -1320,6 +1346,114 @@ function resolveExtensionContent(
   return { content: resolved };
 }
 
+/**
+ * Resolve the workspace-files bridge scope exactly the way run-code's
+ * workspaceRead/workspaceWrite do: org-preferred (org → shared owner) with the
+ * requesting user's email as the solo fallback. Kept in lockstep with
+ * `resolveScope` in `workspace-files/tool.ts`.
+ */
+function workspaceFilesBridgeScope(): WorkspaceFilesScope | null {
+  const orgId = getRequestOrgId();
+  if (orgId) return { scope: "org", scopeId: orgId };
+  const email = getRequestUserEmail();
+  if (email) return { scope: "user", scopeId: email };
+  return null;
+}
+
+/**
+ * Read a workspace/shared/personal resource file's FULL content by path.
+ *
+ * Precedence (single, documented rule so this never silently resolves a
+ * different file than the agent inspected):
+ *   1. The run-code `workspace-files` bridge scope (org → shared owner, else the
+ *      user's email). This is the SAME owner/scope `workspaceRead` /
+ *      `workspaceWrite` use, so a body the agent staged via `workspaceWrite` is
+ *      resolved here verbatim — the two paths cannot diverge.
+ *   2. User-managed Resources (personal override → org/shared → workspace
+ *      default) as a fallback, for pre-built resources that were created in the
+ *      Resources panel rather than staged through the bridge.
+ *
+ * Unlike attachments, resource content is not capped/truncated on the way in, so
+ * this is the correct path for cloning a large extension body that already
+ * exists as a workspace resource (e.g. a per-customer dashboard).
+ */
+async function readWorkspaceFileContent(path: string): Promise<string | null> {
+  const trimmed = path.trim();
+  if (!trimmed) return null;
+  // 1) Bridge parity — resolve exactly the file workspaceRead/workspaceWrite see.
+  const bridgeScope = workspaceFilesBridgeScope();
+  if (bridgeScope) {
+    let bridgeFile: Awaited<ReturnType<typeof readWorkspaceFile>>;
+    try {
+      bridgeFile = await readWorkspaceFile(bridgeScope, trimmed);
+    } catch {
+      // A THROW here is a transient store error or invalid path — NOT a
+      // definitive "not found". Fail closed rather than silently hosting a
+      // possibly-different same-path Resources body than workspaceRead
+      // inspected. A retry re-runs this read cleanly.
+      return null;
+    }
+    // A null result means the file genuinely does not exist in the bridge scope;
+    // fall through to user-managed Resources for pre-built resource-panel files.
+    if (bridgeFile && typeof bridgeFile.content === "string") {
+      return bridgeFile.content;
+    }
+  }
+  // 2) Fallback — user-managed Resources by scope precedence.
+  for (const scope of ["personal", "shared", "workspace"] as const) {
+    try {
+      const content = await readResource(trimmed, { scope });
+      if (typeof content === "string") return content;
+    } catch {
+      // A given scope can throw (e.g. `personal` when no user identity is
+      // resolvable in this context). Don't let one scope abort the lookup —
+      // fall through and try the next one.
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the extension HTML body from (in priority order) inline `content`, a
+ * `contentFromWorkspaceFile` resource path, or a `contentFromAttachment` handle.
+ *
+ * The workspace-file path exists because a large extension body frequently lives
+ * as a workspace resource (not a chat attachment). Without it the model has no
+ * viable route — inline is too large to shuttle reliably, contentFromAttachment
+ * only sees chat attachments, and mutating actions cannot run from run-code — so
+ * it loops and the run aborts with no_progress.
+ */
+async function resolveExtensionContentAsync(
+  args: Record<string, string> | undefined,
+  ctx: ActionRunContext | undefined,
+): Promise<{ content: string } | { error: string }> {
+  const inline = args?.content !== undefined ? String(args.content) : undefined;
+  if (inline !== undefined && inline.trim().length > 0) {
+    return { content: inline };
+  }
+
+  const wsRef =
+    args?.contentFromWorkspaceFile !== undefined
+      ? String(args.contentFromWorkspaceFile).trim()
+      : "";
+  if (wsRef) {
+    const content = await readWorkspaceFileContent(wsRef);
+    if (content === null) {
+      return {
+        error: `Error: contentFromWorkspaceFile="${wsRef}" did not match any readable workspace/shared/personal resource file. Check the exact path (e.g. "intuit-analytics-extension.html"), or pass the HTML inline via content.`,
+      };
+    }
+    if (content.trim().length === 0) {
+      return {
+        error: `Error: workspace file "${wsRef}" is empty. Pass non-empty HTML inline via content, or point contentFromWorkspaceFile at a file with content.`,
+      };
+    }
+    return { content };
+  }
+
+  return resolveExtensionContent(args, ctx);
+}
+
 function coerceBoolean(value: unknown): boolean {
   return value === true || value === "true";
 }

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

@@ -143,6 +143,65 @@ Notes:
   "extension unavailable" message instead of the content. Share the extension to
   the same audience as the dashboard so all viewers can see it.
 
+## Cloning An Extension-Backed Dashboard (e.g. per-customer copies)
+
+When the user asks for a copy of an existing extension-backed dashboard for a
+different customer/org (for example "make an Intuit version of the Roku usage
+dashboard"), follow this playbook. Extension bodies are frequently tens of
+thousands of characters. The reliable path is to read+transform+write the body
+INSIDE `run-code` (where `workspaceRead` returns the full file) and then create
+from that written file — never by pulling the body into chat context first or
+re-typing it as a `content` argument.
+
+1. `get-sql-dashboard` with `includeConfig: true` on the source dashboard and
+   confirm the target panel is `chartType: "extension"`; grab its
+   `config.extensionId`.
+2. `get-extension` for that id with `forceContent: true` **exactly once**. Reuse
+   that body for the rest of the turn — a second same-run read intentionally
+   omits `content` and returns `contentOmitted` instead. That is not the content
+   disappearing; use the copy you already have. Do NOT try to re-fetch the body
+   with `run-code` (`appAction('get-extension')`) to page past a display
+   truncation — the same-run omit makes it return empty `content`, wasting turns.
+   If you need the full body again, read the workspace resource file (step 5) or
+   set `forceContent: true` on a single native `get-extension`.
+3. Change ONLY the small customer-specific static config (e.g. the
+   `ACCOUNT_USAGE_STATIC` block: company name, title, org-discovery filters,
+   messaging). Prefer a focused `update-extension` edit/patch over regenerating
+   the entire HTML.
+4. **Call `create-extension` / `update-extension` as native tools.** They are
+   mutating actions and are NOT callable from `run-code` / `appAction` (the
+   sandbox bridge only exposes read-only actions). Do not try to create or update
+   an extension from inside `run-code`.
+5. **If the source body already exists as a workspace/shared resource file**
+   (e.g. a pre-built `intuit-analytics-extension.html`), do the read AND the
+   customer swap in ONE `run-code` call, then create from the written file:
+   - Inside `run-code`: `const src = await workspaceRead('<source>.html')`
+     returns the WHOLE file (it auto-pages; there is no 50k cap here), do the
+     small string-replace on the static config block, then
+     `await workspaceWrite('<target>.html', modified)`.
+   - Then call `create-extension` (native) with
+     `contentFromWorkspaceFile: '<target>.html'` and leave `content` empty — the
+     server reads the full file verbatim.
+   Do NOT read the source body with the `resources` read tool (or `get-extension`)
+   first just to transform it: that display is capped and wastes a turn. And do
+   NOT re-emit an 80k+ char body as the `content` argument — it gets cut off
+   mid-stream. `contentFromAttachment` only sees files the user pasted into chat,
+   not workspace resources. `create-extension`/`update-extension` are mutating and
+   cannot run from `run-code`, so only the read+write+transform happens there.
+6. Finally `update-dashboard` to save a new dashboard embedding the new
+   extension panel (`chartType: "extension"`, `config.extensionId`), then
+   `navigate` to it.
+
+### Display truncation is cosmetic — do not chase the "missing" tail
+
+A tool result ending in `...[truncated — full result was N chars; only first
+50,000 shown]` (from the `resources` read tool or `get-extension`) means only the
+DISPLAYED text was capped. The file is intact. `run-code`'s `workspaceRead`
+returns the full N chars, and `contentFromWorkspaceFile` hosts the full file.
+Never read the same file twice or try to "page the rest" to recover the tail —
+that is the single biggest source of wasted turns on clone requests. Decide to
+clone, then go straight to the `run-code` read+transform+write path in step 5.
+
 ## Config Shape
 
 ```jsonc

package/corpus/templates/analytics/app/components/layout/NewDashboardDialog.tsx

@@ -14,10 +14,13 @@ import {
 
 const DASHBOARD_CONTEXT =
   "The user wants to create a new analytics dashboard. " +
-  "REAL_DATA_REQUIRED: before saving or answering, run at least one real data-source query action; `data-source-status`, `list-data-dictionary`, `update-dashboard`, and dry-run validation do not count as data queries. " +
+  "TEMPLATE FIRST — If the user names an existing dashboard as a template to clone/base this on, resolve its id first (use `list-sql-dashboards` if you only have a title), then call `get-sql-dashboard` with `includeConfig: true` immediately and inspect `panels[].chartType`. " +
+  'If any panel is `chartType: "extension"`, this is an extension-backed dashboard: call `get-extension` for that panel\'s `config.extensionId`, clone/adapt it with `create-extension` (apply the requested customer/org filters), then save a new dashboard via `update-dashboard` that embeds the new extension panel (`chartType: "extension"`, `config.extensionId`). Do not rebuild an extension template as guessed SQL/BigQuery panels. ' +
+  "LARGE EXTENSION CLONE — Extension bodies can be very large (tens of thousands of characters). Call `get-extension` with `forceContent: true` exactly ONCE and reuse that body; a second same-run read intentionally omits `content` (you'll see `contentOmitted`), so don't treat that as the content being gone. Call `create-extension` / `update-extension` as NATIVE tools — they are mutating actions and cannot be invoked from `run-code`/`appAction`. For customer-specific clones, change only the small static config block (e.g. `ACCOUNT_USAGE_STATIC`) and prefer a focused `update-extension` edit over regenerating the whole HTML. Never shovel the full body through `run-code` or chat; if you stage it in a workspace scratch file, read it back with `workspaceRead` (which returns the whole file). " +
+  "REAL_DATA_REQUIRED: before presenting numbers or authoring new SQL that invents tables/columns/filters, run at least one real data-source query action; `data-source-status`, `list-data-dictionary`, `get-sql-dashboard`, `get-extension`, `update-dashboard`, `mutate-dashboard`, and dry-run validation do not count as data queries. It is OK to inspect a template, clone an extension shell, ask one clarifying question (org id / account filter), or report an exact unavailable/error result without running a data query, as long as you do not invent metrics. " +
   "The `demo` source is reserved for the built-in Node Exporter demo and does not satisfy REAL_DATA_REQUIRED unless the user explicitly asks to work on that demo dashboard. " +
   "If no source can answer, report the exact unavailable/error result instead of saving a dashboard with guessed schema or metrics. " +
-  "Create a SQL-driven dashboard by calling the `update-dashboard` action with `dashboardId` and `config`. " +
+  "SQL PANELS — Only for native SQL dashboards (not template clones of an extension-backed dashboard): create a SQL-driven dashboard by calling the `update-dashboard` action with `dashboardId` and `config`. " +
   "The config shape is: { name: string, panels: [{ id, title, sql, source, chartType, width, tab?, config? }] }. " +
   "Each panel needs: id (unique string), title, sql (the query), source ('bigquery' | 'ga4' | 'amplitude' | 'first-party' | 'demo' | 'prometheus'), " +
   "chartType ('line' | 'area' | 'bar' | 'metric' | 'table' | 'pie'), width (1 or 2). " +

package/corpus/templates/analytics/server/lib/agent-chat-plan-mode.ts

@@ -16,23 +16,32 @@ export const INITIAL_TOOL_NAMES = [
   "list-analyses",
   "get-analysis",
   "save-analysis",
+  // Dashboard/extension INSPECTION stays on the initial surface so a
+  // template-clone request can resolve and inspect the source on the first
+  // turn. The MUTATING writers (update-dashboard, mutate-dashboard,
+  // create-extension, update-extension) are intentionally left off: the
+  // dashboard-construction final-response guard retries with
+  // `expandToolSurface: true` (see server/plugins/agent-chat.ts), which opens
+  // the full run registry exactly when a save is needed, and tool-search can
+  // surface them otherwise. This keeps the first-request surface under the
+  // 40-tool ceiling enforced by scripts/guard-agent-chat-context.ts.
   "get-sql-dashboard",
-  "mutate-dashboard",
+  "list-sql-dashboards",
+  "list-dashboard-templates",
+  "list-extensions",
+  "get-extension",
   "generate-chart",
   "query-agent-native-analytics",
   "bigquery",
   "search-bigquery-schema",
-  "bigquery-table-info",
   "provider-api-catalog",
   "provider-api-docs",
   "provider-api-request",
   "run-code",
   "get-code-execution",
   "provider-corpus-job",
-  "provider-corpus-jobs",
   "query-staged-dataset",
   "list-staged-datasets",
-  "delete-staged-dataset",
   "account-deep-dive",
   "hubspot-deals",
   "hubspot-records",

package/corpus/templates/analytics/server/lib/real-data-actions.ts

@@ -57,6 +57,25 @@ export const CORPUS_SOURCE_ACTIONS = new Set([
 
 export const CORPUS_REDUCTION_ACTIONS = new Set(["run-code"]);
 
+// Inspecting or cloning an existing dashboard/extension template is
+// construction progress, not a metric query. These do not satisfy
+// hasDataQueryAttempt, but they should stop the guard from steering a
+// template-clone turn into "connect a missing source". Deliberately limited
+// to read/inspection actions: update-dashboard/mutate-dashboard/
+// compose-dashboard/install-dashboard-template/create-extension/
+// update-extension can all author brand-new SQL or extension content, so
+// calling one of those alone is not proof the turn actually inspected a
+// template rather than inventing it from scratch. If the tool run also
+// includes one of these read actions, the bypass still applies even when an
+// authoring/save action ran alongside it.
+export const DASHBOARD_CONSTRUCTION_ACTIONS = new Set([
+  "get-sql-dashboard",
+  "list-sql-dashboards",
+  "list-dashboard-templates",
+  "list-extensions",
+  "get-extension",
+]);
+
 const RUN_CODE_BRIDGE_TOOLS_USED = /^bridgeToolsUsed:\s*(.+)$/im;
 
 const MCP_DATA_SOURCE_TOKENS = [
@@ -97,6 +116,41 @@ function isDataQueryActionName(name: string): boolean {
   return DATA_QUERY_ACTIONS.has(normalizeActionToolName(name));
 }
 
+function isDashboardConstructionActionName(name: string): boolean {
+  return DASHBOARD_CONSTRUCTION_ACTIONS.has(normalizeActionToolName(name));
+}
+
+// "Build/clone/template" language targeting a dashboard/extension/panel is
+// dashboard construction, distinct from an analytics-result question. Turns
+// like this may inspect and clone a template without running a metric query.
+const DASHBOARD_CONSTRUCTION_INTENT_TERMS =
+  /\b(build|create|make|clone|copy|duplicate|adapt|template|based (?:off|on)|using .{1,80}? as a template)\b/i;
+
+const DASHBOARD_CONSTRUCTION_TARGET_TERMS =
+  /\b(dashboard|extension|panel|widget)\b/i;
+
+export function looksLikeDashboardConstructionRequest(text: string): boolean {
+  const requestText = stripInjectedAnalyticsGuardContext(text);
+  const lower = requestText.toLowerCase();
+  if (!lower) return false;
+  const wantsBuild = DASHBOARD_CONSTRUCTION_INTENT_TERMS.test(lower);
+  const targetsDashboard =
+    DASHBOARD_CONSTRUCTION_TARGET_TERMS.test(lower) ||
+    lower.includes(REAL_DATA_REQUIRED_MARKER.toLowerCase());
+  return wantsBuild && targetsDashboard;
+}
+
+export function hasDashboardConstructionAttempt(
+  toolResults:
+    | Array<{ name?: string; isError?: boolean; content?: string }>
+    | undefined,
+): boolean {
+  return (toolResults ?? []).some((result) => {
+    if (result.isError) return false;
+    return isDashboardConstructionActionName(String(result.name ?? ""));
+  });
+}
+
 function isCorpusSourceActionName(name: string): boolean {
   return CORPUS_SOURCE_ACTIONS.has(normalizeActionToolName(name));
 }
@@ -253,7 +307,15 @@ export function looksLikeAnalyticsDataRequest(text: string): boolean {
 }
 
 const UNSUPPORTED_RESULT_CLAIM =
-  /(?:\b\d[\d,.]*(?:\.\d+)?\s*(?:%|percent|users?|customers?|accounts?|sessions?|events?|deals?|tickets?|issues?|calls?|messages?|signups?|pageviews?)\b|\$\s*\d|\b(?:data|query|results?)\s+(?:shows?|showed|indicates?|returned|found)\b|\b(?:i found|the top|the bottom|highest|lowest|increased|decreased|grew|declined|converted|churned|retained|averaged|total(?:ed)?|count(?:ed)?)\b)/i;
+  /(?:\b\d[\d,.]*(?:\.\d+)?\s*(?:%|percent|users?|customers?|accounts?|sessions?|events?|deals?|tickets?|issues?|calls?|messages?|signups?|pageviews?)\b|\$\s*\d|\b(?:zero|no|none)\s+(?:users?|customers?|accounts?|sessions?|events?|deals?|tickets?|issues?|calls?|messages?|signups?|pageviews?)\b|\b(?:data|query|results?)\s+(?:shows?|showed|indicates?|returned|found)\b|\b(?:i found|the top|the bottom|highest|lowest|increased|decreased|grew|declined|converted|churned|retained|averaged|total(?:ed)?|count(?:ed)?)\b)/i;
+
+// Reuse the same broad unsupported-result-claim vocabulary that gates
+// isSafeNoDataAnalyticsResponse so a dashboard-construction turn cannot
+// bypass the no-query fallback just by avoiding the narrower set of units a
+// dashboard-specific regex would otherwise miss (e.g. "signups", "accounts").
+export function draftClaimsAnalyticsMetrics(text: string): boolean {
+  return UNSUPPORTED_RESULT_CLAIM.test(String(text ?? "").trim());
+}
 
 export const GENERIC_NO_DATA_FALLBACK_MESSAGE =
   "I can't provide a grounded analytics result yet because no real data-source query ran successfully. Tell me which source to use or connect the missing source, and I'll run it before giving numbers or source-record conclusions.";

package/corpus/templates/analytics/server/plugins/agent-chat.ts

@@ -14,7 +14,9 @@ import {
 import { ANALYTICS_CONNECTOR_CATALOG } from "../lib/analytics-connector-catalog";
 import { credentialProviderConfigs } from "../lib/credential-keys";
 import {
+  draftClaimsAnalyticsMetrics,
   failedDataQueryAttemptMessage,
+  hasDashboardConstructionAttempt,
   hasExplicitPartialDisclosure,
   hasFailedCorpusWorkflowEvidence,
   hasDataQueryAttempt,
@@ -23,6 +25,7 @@ import {
   isSafeNoDataAnalyticsResponse,
   hasOverstatedCoverageConfidenceClaim,
   looksLikeCoverageSensitiveAnalyticsRequest,
+  looksLikeDashboardConstructionRequest,
   looksLikeStrongCoverageClaim,
   looksLikeAnalyticsDataRequest,
   needsCorpusWorkflowForCoverageSensitiveRequest,
@@ -522,6 +525,33 @@ export function realDataFinalGuard(
         "I can't make a confident exhaustive analytics claim yet because part of the source evidence was aborted, truncated, or still paginated. I need to recover the missing coverage or state the answer as partial with the inspected sample size.",
     };
   }
+  // Dashboard construction/template-clone turns may inspect and clone an
+  // existing dashboard/extension without running a metric query, as long as
+  // the draft does not invent numbers. Check this before the generic
+  // "no data query ran" fallback so a template-based extension clone is not
+  // treated the same as an unanswerable analytics-result question.
+  if (
+    looksLikeDashboardConstructionRequest(userText) &&
+    !draftClaimsAnalyticsMetrics(context.text)
+  ) {
+    if (
+      hasDashboardConstructionAttempt(context.toolResults) ||
+      isSafeNoDataAnalyticsResponse(context.text)
+    ) {
+      return null;
+    }
+    return {
+      retryMessage:
+        'This is a dashboard construction/template-clone request. Resolve the named template\'s id (use `list-sql-dashboards` if you only have a title) and call `get-sql-dashboard` with `includeConfig: true` first. If its panels are `chartType: "extension"`, use `get-extension` then `create-extension` to clone/adapt it, then `update-dashboard` to save the new dashboard. Do not invent SQL panels for an extension-backed template. Ask one clarifying filter question if needed. Only run a data-source query before presenting numbers or authoring invented SQL.',
+      fallbackMessage:
+        "I need to inspect the template dashboard (and its extension, if it uses one) before creating the new one. Tell me the template dashboard name, or confirm the org/account filter, and I'll clone it without inventing metrics.",
+      // list-sql-dashboards/list-dashboard-templates are on the initial
+      // surface, but expand anyway so a corrective retry can always reach
+      // the lookup/inspection tools this message asks for.
+      expandToolSurface: true,
+    };
+  }
+
   if (dataQueryAttempted) return null;
   if (isSafeNoDataAnalyticsResponse(context.text)) {
     if (firstPartySourceShouldBeTried) {