@agent-native/core-corpus 0.203.0 → 0.203.1-nightly-20261007183952

package/corpus/README.md

@@ -32,4 +32,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core-corpus/corpu
 
 ## Generated Counts
 
-- template files: 11315
+- template files: 11341

package/corpus/templates/analytics/.agents/skills/actions/SKILL.md

@@ -107,6 +107,31 @@ An action that hands control back to the user (question form, intake dialog) set
 
 Reach for `outputSchema` (validate the return), `_agentImages` (attach images the agent can see), `authorize` (gate who may call it), or `needsApproval` (require human sign-off per call) only when the action needs that guarantee — examples in `references/action-fields.md`.
 
+### Write receipts
+
+A write action that can check its own effect returns a plain-object result with a reserved `_receipt`, so the final answer is reconciled with what the write did, not with the model's reading of a JSON string that may be truncated:
+
+```ts
+import type { WriteReceipt } from "@agent-native/core/action";
+
+const _receipt: WriteReceipt = {
+  changed: true,
+  verified: false,
+  summary: "Saved; panel 3 returned no rows.",
+  checks: [{ id: "panel-3", ok: false, detail: "0 rows" }],
+};
+return { id, _receipt };
+```
+
+`verified` is `true` (the effect was observed), `false` (checked and did not hold), or `"unverified"` (could not be checked); `checks` and `warnings` are optional. The agent loop reads the receipt before the result is stringified and truncated (summary 200 chars, 8 checks, 5 warnings):
+
+- `verified: false` or `changed: false` forces one honest-reconciliation retry per turn: the model must say what the receipt shows and may not call the change visible or working. If the retry is spent, the answer is prefixed with the receipt block.
+- `verified: "unverified"` only prefixes that note; no retry.
+- A receipt that is present but malformed counts as `unverified`, never clean. `changed: false` also records the call as `completedSideEffect: false`.
+- Set `subject` (the stable target, such as a dashboard id) so a later `changed: true, verified: true` receipt for the same subject can supersede an earlier flagged one in the same turn. When the earlier receipt had failing or unverified `checks`, the later receipts (from this action or another that writes the same subject) must carry an `ok: true` check with the same `id` for each; a receipt without checks never clears one that had them. A flagged receipt with no failing checks is superseded only by the same action. Receipts without a `subject` are never superseded.
+
+A receipt is not an error channel. A write that did not achieve the requested state throws (`fail()`); return `changed: false` only for a benign no-op, such as the record already being in the requested state.
+
 ## Frontend Hooks
 
 Import from focused `@agent-native/core/client/*` entry points; the broad

package/corpus/templates/analytics/.agents/skills/adhoc-analysis/SKILL.md

@@ -98,6 +98,18 @@ Don't just dump raw data. Synthesize findings:
 - Make the evidence trail explicit enough to audit: source(s), time window,
   filters, sample size or row count, join/match method, caveats/gaps, and
   recommended next action when useful.
+- Unstructured source records (Pylon tickets, Jira issues, Gong calls and
+  transcripts, Slack messages) are valid evidence: code them for themes, mention
+  counts, sentiment, and objections, state the inspected sample size, and do not
+  imply unsupported statistical certainty.
+- The words all, total, or exact do not by themselves call for cross-source
+  validation when one structured query fully covers the requested source and
+  filters.
+- If the user challenges coverage, asks why more records were not included, or
+  asks for the updated answer, rerun the source query or revise from the
+  corrected cohort and put the updated answer in the response. Do not claim a
+  dashboard was revised unless the revised answer is saved with
+  `update-dashboard` or `mutate-dashboard`.
 
 ### Step 4: Generate Charts (when useful)
 

package/corpus/templates/analytics/.agents/skills/admin-surfaces/SKILL.md

@@ -1,10 +1,7 @@
 ---
 name: admin-surfaces
 description: >-
-  The /agents admin home for Analytics: fleet feature-flag control plane,
-  dashboard usage audit, and connected-app database admin. Use when an admin
-  asks about feature flags/rollouts, dashboard usage stats, or connecting
-  another agent-native app's database.
+  Use when an admin asks about feature flags and rollouts, dashboard usage stats, or connecting another app's database (the /agents admin home for Analytics).
 ---
 
 # Admin Surfaces (`/agents`)

package/corpus/templates/analytics/.agents/skills/analysis-workspace/SKILL.md

@@ -1,10 +1,7 @@
 ---
 name: analysis-workspace
 description: >-
-  How to use Resources-backed workspace files for large-scale multi-source
-  analyses: scratch/ temporary staging, chunked batch processing with per-item
-  memos, run-code aggregation, saveToFile for big API pulls, and synthesizing
-  across files that exceed one context window.
+  Large analyses and file delivery: scratch staging, chunked batches, run-code aggregation, CSV/XLSX exports. Use when work exceeds one context window or the user wants a file.
 ---
 
 # Analysis Workspace
@@ -98,6 +95,9 @@ Inside `run-code`, use the workspace helper functions:
   CSV control. For a durable CSV, use `run-code` with `workspaceWrite` in a
   normal Resources folder, then call `show-workspace-file` with that path. If
   `run-code` is not available, discover it once with tool search.
+- Deliver a requested CSV, Markdown, or other file in the same chat turn. Write
+  only verified successful data to a non-scratch workspace path, never an error
+  or failed response, and never finish with only a path or filename.
 - For an explicit `.xlsx` request, call `docs-search` once for `xlsx export`
   and follow the returned workflow. The QuickJS `run-code` sandbox has no Node
   imports; do not try to load `xlsx` or `exceljs` there.

package/corpus/templates/analytics/.agents/skills/bigquery/SKILL.md

@@ -1,9 +1,7 @@
 ---
 name: bigquery
 description: >-
-  Query the configured BigQuery warehouse for analytics data. Use when the user
-  asks for warehouse SQL, BigQuery tables, Amplitude-in-BigQuery events, or a
-  metric/table that the data dictionary says lives in BigQuery.
+  Query the BigQuery warehouse. Use for warehouse SQL, BigQuery tables, Amplitude-in-BigQuery events, or a metric the data dictionary says lives in BigQuery.
 ---
 
 # BigQuery

package/corpus/templates/analytics/.agents/skills/creative-context/SKILL.md

@@ -1,10 +1,7 @@
 ---
 name: creative-context
 description: >-
-  Reuse approved dashboards and creative context while respecting named
-  contexts, immutable packs, provenance, and opt-out state. Use when building
-  or refining a dashboard, or when the user references saved or approved
-  context.
+  Reuse approved dashboards and creative context (named contexts, packs, provenance, opt-out). Use when building or refining a dashboard or citing saved context.
 scope: both
 requires-lab: creative-context.library
 metadata:

package/corpus/templates/analytics/.agents/skills/cross-source-analysis/SKILL.md

@@ -1,9 +1,7 @@
 ---
 name: cross-source-analysis
 description: >-
-  Use when an analytics question spans multiple data sources (e.g. warehouse
-  events + CRM + support + first-party) and you must stitch identities, remove
-  duplicates, and produce one consolidated answer with per-source provenance.
+  Use when a question spans multiple sources (warehouse + CRM + support + first-party): stitch identities, remove duplicates, give one answer with per-source provenance.
 ---
 
 # Cross-Source Analysis

package/corpus/templates/analytics/.agents/skills/custom-blocks/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: custom-blocks
+description: >-
+  Create, embed, clone, or repair a Custom Block (extension panel). Use for a bespoke visualization native panels cannot draw, or to fix or copy an extension-backed dashboard.
+---
+
+# Custom Blocks
+
+Analytics has one user-facing artifact type: dashboards. Build with native
+dashboard panels and Data Programs first. A sandboxed extension embedded in a
+dashboard is presented to users as a Custom Block, not as a separate Analytics
+artifact.
+
+Use native chart, table, metric, section, funnel, heatmap, callout, filter, and
+layout capabilities whenever they can represent the request faithfully.
+Reusable ROI, engagement, cross-sell, and win/loss dashboards compose these
+native panels around real SQL or Data Program results. Use a Data Program when
+the durable need is reusable fetching, transformation, or computed data that
+native panels can render. Dual-axis charts are native (`config.rightYKeys`),
+never an extension. Do not create a Custom Block merely because a request says
+custom, asks for a dashboard, or would take more effort with native components.
+
+## When To Create One
+
+Create a Custom Block only when the user explicitly asks for a genuinely
+bespoke or one-off visualization or interaction, the native dashboard model
+cannot represent it faithfully, and its intended scope is this dashboard.
+
+- Create it with `create-extension`, immediately embed it as a
+  `chartType: "extension"` panel with `config.extensionId`, and set
+  `config.customBlock` to `{ authoredBy: "agent", intent: "one-off", scope: "dashboard", nativeGapReason: "custom-visualization" | "custom-interaction" | "custom-layout" | "other" }`.
+  Choose the narrow categorical reason; never put prompt text, customer data, or
+  other free text in this metadata.
+- Use the host theme CSS variables and match the dashboard typography, card
+  spacing, and density so the sandboxed content reads as an agent-authored patch
+  to Analytics instead of a foreign mini-app. Describe it as a sandboxed,
+  agent-authored dashboard patch.
+- Never leave it standalone or direct the user to an Extensions page.
+- A Custom Block is a fast runtime patch, not the durable destination for
+  reusable product behavior. If the request should work across dashboards or
+  users, changes app chrome or business logic, adds a reusable chart type, needs
+  native accessibility/export/governance, or explicitly asks for app code, a PR,
+  or a native feature, call `connect-builder` with the request verbatim instead
+  of creating a Custom Block. If scope is ambiguous, ask whether the user wants a
+  one-off block for this dashboard or a reusable app feature.
+- When the user chooses Promote to app code, preserve the existing Custom Block
+  and pass its dashboard id, panel id, extension id, and requested native
+  placement through `connect-builder`; do not delete or replace the block until
+  the native implementation is reviewed and deployed.
+- Legacy analyses and existing extension-backed dashboards remain readable and
+  editable for compatibility.
+
+An explicit request to build one authorizes every non-destructive step in the
+same turn: query or scaffold, seed extension data (`extension-data-set`), save,
+embed, and `navigate`. Do not leave an empty shell or ask whether to proceed.
+
+## Extension Data Boundary
+
+Code inside a Custom Block runs in an iframe and may call only actions that are
+HTTP-mounted and intended for `appAction`. Use the canonical `bigquery` action
+for warehouse SQL; never call `query-agent-native-analytics`,
+`bigquery-table-info`, or another `http: false` agent-only action from extension
+code. For first-party Analytics data, prefer a native `source: "first-party"`
+panel, or query it as the agent and seed the extension data store.
+
+## Embedding An Extension As A Panel
+
+Use `chartType: "extension"` to add an extension box alongside normal SQL
+charts. The panel skips `source` and `sql`. For ordinary requests such as "put
+X in this dashboard," save the author-selected extension id in
+`config.extensionId`. This makes the selection part of the shared dashboard and
+keeps the widget present in scheduled report captures:
+
+```jsonc
+{
+  "id": "pipeline-widget",
+  "title": "Pipeline Widget",
+  "chartType": "extension",
+  "width": 3,
+  "config": { "extensionId": "extension-123" },
+}
+```
+
+Direct embeds receive the dashboard id, name, description, current filters, and
+panel context. Embedding does not grant extension access, so share the
+extension with the dashboard audience (`share-resource --resourceType
+extension ...`); otherwise viewers see an "extension unavailable" placeholder.
+
+Use a stable `config.extensionSlotId` only when the user explicitly wants each
+viewer to choose or install their own widget:
+
+```text
+analytics.dashboard.<dashboard-id>.panel.<panel-id>
+```
+
+Create or choose the extension, call `add-extension-slot-target` with the
+extension id and slot id, then call `install-extension` with the same values.
+The dashboard panel is shared, while the installed extension is per-user. Empty
+slots show the normal install affordance instead of a broken iframe.
+
+```jsonc
+{
+  "id": "pipeline-widget",
+  "title": "Pipeline Widget",
+  "chartType": "extension",
+  "width": 3,
+  "config": {
+    "extensionSlotId": "analytics.dashboard.weekly-metrics.panel.pipeline-widget",
+  },
+}
+```
+
+- Both direct and slot-backed extensions receive dashboard and panel context.
+- Installs and extension access are per viewer. Slot installs are per-user
+  preferences, so different viewers can see different widgets and scheduled
+  reports running as a service identity may show an empty slot. This is why
+  slots are opt-in rather than the default.
+- Inspect an existing Custom Block through the `get-sql-dashboard` panel
+  summaries (`extensionId`, `extensionSlotId`).
+
+## Cloning A Direct-Extension 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` on the source dashboard (pass the extension panel's id in
+   `panelIds`) and confirm the target panel is a `chartType: "extension"` panel
+   with `config.extensionId`; grab that extension id. For a slot-backed panel,
+   clone the dashboard panel with a new stable `extensionSlotId`, then target
+   and install the desired extension into that slot instead of using this
+   body-copy playbook.
+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 save a new dashboard embedding the new extension panel
+   (`chartType: "extension"`, `config.extensionId`) with `update-dashboard`, then
+   `navigate` to it.
+
+## Repairing An Existing Extension-Backed Dashboard
+
+When the user asks to fix data loading in an existing or migrated
+extension-backed dashboard, treat the current extension body as user-authored
+design. Read the dashboard config and extension once, identify the smallest
+data-loading seam, and call `update-extension` with exactly `id`,
+`operation="edit"`, and a `payloadJson` string containing focused
+`patches`/`edits` that change only that seam. Never send empty placeholder
+fields. Preserve the existing layout, CSS, copy, and interactions. Do not send a
+reconstructed full `content` body for a data-only repair.
+
+A request that combines a visual rewrite (compacting, removing sections,
+renaming, changing padding) with a data repair is a broad rewrite: after
+inspecting the current extension, use `operation="replace"` with the complete
+replacement in `payloadJson`. If a focused edit fails, inspect the current body
+and change the target rather than retrying the same arguments.
+
+### 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.