@agent-native/core 0.120.1 → 0.120.3

package/docs/content/extensions.mdx

@@ -223,7 +223,7 @@ Pattern across all of these: extensions are about **the moment** the user is in
 
 The simple path:
 
-1. **Click "New Extension"** in the sidebar (or just ask in chat).
+1. Open **Settings → Extensions** (or just ask in chat), then click **New Extension**.
 2. **Describe what you want in one sentence.** "A sticky-note pad for the contact I'm emailing." "A KPI box for trials started this week."
 3. **The agent writes it and it appears in your Extensions list, ready to use.**
 
@@ -617,9 +617,23 @@ Extensions are private to the user who created them by default. To share:
 
 Shared extensions have their own URLs and plug into the same share dialog as documents, decks, and dashboards. Slot installs are always personal — sharing an extension means others _can_ install it; it doesn't auto-pin it to their UI.
 
-## Extensions vs. editing the app code {#vs-app-code}
+## Should I use an extension or edit the app code? {#vs-app-code}
 
-The framework lets the agent edit the app's source code directly — components, routes, styles. So when should you reach for an extension instead?
+The framework lets the agent edit the app's source code directly — components,
+routes, styles, and business logic. Use this question when either path could
+solve the request:
+
+- **Start with an extension** for a self-contained, relatively one-off widget:
+  a custom visualization or interaction, a dashboard tile, a standalone
+  utility, or an add-on in an existing slot. It is fast, requires no source
+  change, build, or deploy, and can be private or shared.
+- **Use app code** for a core feature of the template, a change to native UI,
+  layout, routes, or business logic, or anything that should be reused broadly
+  across dashboards or users. If the host has no suitable slot or the request
+  needs a new slot, use code.
+- **Promote repeated extensions.** If people keep rebuilding the same
+  extension, or maintaining copies in many places would be worse than one
+  shared implementation, move it into app code as a reusable native feature.
 
 |                       | Extension                                         | App code edit                        |
 | --------------------- | ------------------------------------------------- | ------------------------------------ |
@@ -630,7 +644,12 @@ The framework lets the agent edit the app's source code directly — components,
 | **Scope**             | One user (or shared with org)                     | The entire product, every user       |
 | **Best for**          | Personal widgets, custom KPIs, per-team utilities | Core features that ship to all users |
 
-Rule of thumb: **if it's for one user or one team, it's an extension.** If every user of the template should get it, ship it as a real feature.
+Rule of thumb: **if an extension can solve the problem, generally start there.**
+Use code when the extension boundary does not fit or when broad reuse and
+product-wide availability justify a native implementation. For example, a
+one-off custom visualization on a dashboard is a good extension; a new pie,
+multi-bar, or line chart type that should be available across dashboards
+belongs in the template code.
 
 If what you actually need is a cached, refreshable data source for an existing chart or table — not a new interactive widget — see [Data Programs](/docs/data-programs) instead; it shares this page's sandbox and security posture but has no UI of its own.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.120.1",
+  "version": "0.120.3",
   "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": {
@@ -390,7 +390,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.10.4"
+    "@agent-native/toolkit": "^0.10.5"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/agent/production-agent.ts

@@ -6401,6 +6401,10 @@ export async function chainServerDrivenContinuation(opts: {
         terminalEvent: run.events.at(-1)?.event,
       })
       .catch(() => {});
+    run.continuationTerminalEvent = {
+      type: "auto_continue",
+      reason: continuationReason,
+    };
   } catch (chainErr) {
     // Chain dispatch failed — fail loud so the held row goes terminal
     // instead of spinning. The reaper would also catch it, but this is

package/src/agent/run-manager.ts

@@ -41,6 +41,16 @@ export interface ActiveRun {
   subscribers: Set<(event: RunEvent) => void>;
   abort: AbortController;
   abortReason?: string;
+  /**
+   * Terminal event to emit when a server-driven continuation has been handed
+   * off successfully. The continuation runs outside this process, so the
+   * normal loop-level auto_continue event is not sent through this run's
+   * `send` callback.
+   */
+  continuationTerminalEvent?: Extract<
+    AgentChatEvent,
+    { type: "auto_continue" }
+  >;
   startedAt: number;
 }
 
@@ -954,7 +964,17 @@ export function startRun(
       //    /runs/active check while we wait for SQL writes to land.
       let completionError: unknown = null;
       let terminalPersistenceError: unknown = null;
-      const terminalEvent = pendingTerminalEvent?.event ?? null;
+      const resolveTerminalEventForCompletion = () => {
+        const continuationTerminalEvent = run.continuationTerminalEvent
+          ? {
+              seq: run.events.length,
+              event: run.continuationTerminalEvent,
+            }
+          : null;
+        return continuationTerminalEvent ?? pendingTerminalEvent;
+      };
+      let terminalEventForCompletion = resolveTerminalEventForCompletion();
+      let terminalEvent = terminalEventForCompletion?.event ?? null;
       if (
         onComplete &&
         !(run.status === "aborted" && run.abortReason === "no_progress")
@@ -966,12 +986,12 @@ export function startRun(
               ? "errored"
               : run.status;
           const completionRun: ActiveRun =
-            pendingTerminalEvent || completionStatus !== run.status
+            terminalEventForCompletion || completionStatus !== run.status
               ? {
                   ...run,
                   status: completionStatus,
-                  events: pendingTerminalEvent
-                    ? [...run.events, pendingTerminalEvent]
+                  events: terminalEventForCompletion
+                    ? [...run.events, terminalEventForCompletion]
                     : run.events,
                 }
               : run;
@@ -986,6 +1006,12 @@ export function startRun(
         }
       }
 
+      // Server-driven continuation is installed by onComplete after the
+      // successor has been dispatched. Resolve the terminal event again so
+      // this chunk emits auto_continue instead of a misleading done event.
+      terminalEventForCompletion = resolveTerminalEventForCompletion();
+      terminalEvent = terminalEventForCompletion?.event ?? null;
+
       // 2. Compute final status. If the completion callback threw, we'd
       //    rather mark the run errored than claim success with incomplete
       //    thread_data.
@@ -1022,18 +1048,18 @@ export function startRun(
         // re-stamp the seq at emit time (max-seq+1) just below.
         const terminalEvent: AgentChatEvent =
           finalStatus === "completed"
-            ? (pendingTerminalEvent?.event ?? { type: "done" })
-            : pendingTerminalEvent?.event.type === "error" ||
-                pendingTerminalEvent?.event.type === "missing_api_key"
-              ? pendingTerminalEvent.event
-              : pendingTerminalEvent?.event.type === "auto_continue"
+            ? (terminalEventForCompletion?.event ?? { type: "done" })
+            : terminalEventForCompletion?.event.type === "error" ||
+                terminalEventForCompletion?.event.type === "missing_api_key"
+              ? terminalEventForCompletion.event
+              : terminalEventForCompletion?.event.type === "auto_continue"
                 ? // The run was checkpointed at a soft-timeout/loop boundary and
                   // is recoverable: the partial turn is in agent_run_events and
                   // the continuation run will re-attempt the thread_data save.
                   // Even though the completion save failed (finalStatus stays
                   // "errored" for SQL/diagnostics), re-emit the auto_continue so
                   // the client resumes instead of seeing a dead chat.
-                  pendingTerminalEvent.event
+                  terminalEventForCompletion.event
                 : {
                     type: "error",
                     error: completionError

package/src/agent/types.ts

@@ -167,6 +167,7 @@ export interface AgentChatRequest {
     continuationReason?:
       | "run_timeout"
       | "loop_limit"
+      | "max_tokens"
       | "no_progress"
       | "stream_ended"
       | "gateway_timeout"
@@ -371,6 +372,7 @@ export type AgentChatEvent =
       reason:
         | "run_timeout"
         | "loop_limit"
+        | "max_tokens"
         | "no_progress"
         | "stream_ended"
         | "gateway_timeout"

package/src/cli/context-xray-local.ts

@@ -1933,7 +1933,7 @@ function renderHtml(sessions, args) {
   return "<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>Context X-Ray</title><style>" +
     "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap\");" +
     ":root{--background:0 0% 100%;--foreground:220 10% 10%;--card:0 0% 100%;--muted:220 10% 95%;--muted-foreground:220 5% 45%;--accent:220 10% 92%;--border:220 10% 90%;--ring:220 10% 55%;--destructive:0 84% 60%;--radius:.5rem;--shadow:0 1px 2px rgba(16,24,40,.06);}" +
-    "@media(prefers-color-scheme:dark){:root{--background:220 10% 7%;--foreground:220 8% 92%;--card:220 9% 9%;--muted:220 8% 15%;--muted-foreground:220 6% 64%;--accent:220 8% 17%;--border:220 8% 18%;--ring:220 8% 54%;--destructive:0 84% 60%;--shadow:none;}}" +
+    "@media(prefers-color-scheme:dark){:root{--background:220 10% 7%;--foreground:220 8% 92%;--card:220 9% 9%;--muted:220 8% 15%;--muted-foreground:220 6% 64%;--accent:220 8% 17%;--border:220 8% 18%;--ring:220 8% 54%;--destructive:0 91% 71%;--shadow:none;}}" +
     "*{box-sizing:border-box}html{background:hsl(var(--background))}body{margin:0;background:hsl(var(--background));color:hsl(var(--foreground));font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,\"Segoe UI\",sans-serif;font-feature-settings:\"cv02\",\"cv03\",\"cv04\",\"cv11\";line-height:1.45}button{font:inherit;color:inherit}main{max-width:1180px;margin:0 auto;padding:20px 18px 44px}.topbar{border-bottom:1px solid hsl(var(--border));background:hsl(var(--background));position:sticky;top:0;z-index:10}.topbar-inner{max-width:1180px;margin:0 auto;padding:14px 18px;display:flex;align-items:center;justify-content:space-between;gap:16px}.title-row{display:flex;align-items:center;gap:9px}.logo-dot{width:10px;height:10px;border-radius:999px;background:#38bdf8;box-shadow:0 0 0 4px rgba(56,189,248,.12)}h1{font-size:20px;line-height:1.1;margin:0;font-weight:650;letter-spacing:0}h2{font-size:15px;line-height:1.2;margin:0;font-weight:650}h3{font-size:14px;line-height:1.3;margin:0;font-weight:600}p{margin:0}.muted,.eyebrow,.meta,.empty{color:hsl(var(--muted-foreground))}.eyebrow{text-transform:uppercase;letter-spacing:.08em;font-size:11px;font-weight:650}.meta{font-size:12px}.tabs{display:inline-flex;align-items:center;gap:2px;border:1px solid hsl(var(--border));background:hsl(var(--muted)/.35);border-radius:8px;padding:2px}.tab{border:0;background:transparent;border-radius:6px;padding:6px 10px;font-size:12px;line-height:1.1;cursor:pointer}.tab:hover{background:hsl(var(--accent)/.5)}.tab.active{background:hsl(var(--background));box-shadow:var(--shadow)}.stats{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin:18px 0}.card{background:hsl(var(--card));border:1px solid hsl(var(--border));border-radius:8px;padding:14px;box-shadow:var(--shadow)}.stat-value{display:block;font-size:28px;line-height:1.1;font-weight:700;margin-top:6px}.panel{display:none}.panel.active{display:block}.grid{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(280px,.8fr);gap:14px;align-items:start}.grid.equal{grid-template-columns:repeat(2,minmax(0,1fr))}.section-head{display:flex;align-items:flex-start;justify-content:space-between;gap:10px;margin-bottom:12px}.bar{display:flex;overflow:hidden;height:10px;border-radius:999px;background:hsl(var(--muted));margin:10px 0 12px}.bar span{display:block;min-width:2px}.table{width:100%;border-collapse:collapse;font-size:12px}.table th{text-align:left;color:hsl(var(--muted-foreground));font-weight:600;border-bottom:1px solid hsl(var(--border));padding:7px 8px}.table td{border-bottom:1px solid hsl(var(--border));padding:8px;vertical-align:top}.table th:last-child,.table td:last-child{text-align:right}.row-button{width:100%;display:grid;grid-template-columns:minmax(0,1fr) 74px 70px;gap:10px;align-items:center;text-align:left;border:1px solid transparent;background:transparent;border-radius:6px;padding:8px;cursor:pointer}.row-button:hover,.row-button.active{border-color:hsl(var(--border));background:hsl(var(--accent)/.35)}.row-title{font-size:13px;font-weight:600;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.row-meta{font-size:12px;color:hsl(var(--muted-foreground));text-align:right}.badge-list{display:flex;flex-wrap:wrap;gap:6px}.badge{display:inline-flex;align-items:center;gap:5px;border:1px solid hsl(var(--border));border-radius:999px;padding:3px 7px;font-size:11px;background:hsl(var(--background));max-width:100%}.badge .dot{width:7px;height:7px;border-radius:999px;flex:0 0 auto}.tips{margin:0;padding-left:20px}.tips li{margin:0 0 8px}.detail{min-height:228px}.detail-list{display:grid;gap:8px;margin-top:10px}.sample{border:1px solid hsl(var(--border));border-radius:8px;padding:10px;background:hsl(var(--muted)/.22)}.sample-top{display:flex;justify-content:space-between;gap:10px;margin-bottom:5px;font-size:11px;color:hsl(var(--muted-foreground))}.sample p{font-size:12px;color:hsl(var(--foreground));overflow-wrap:anywhere}.session-card{border:1px solid hsl(var(--border));border-radius:8px;background:hsl(var(--card));margin-bottom:10px;overflow:hidden}.session-card summary{list-style:none;display:flex;justify-content:space-between;gap:14px;cursor:pointer;padding:13px 14px}.session-card summary::-webkit-details-marker{display:none}.session-body{border-top:1px solid hsl(var(--border));padding:12px 14px}.session-title{font-size:13px;font-weight:650;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.session-path{font-size:12px;color:hsl(var(--muted-foreground));margin-top:3px;overflow-wrap:anywhere}.token-big{font-size:20px;font-weight:700;white-space:nowrap}.mini-label{margin:10px 0 6px;font-size:11px;text-transform:uppercase;letter-spacing:.08em;font-weight:650;color:hsl(var(--muted-foreground))}.footer{margin-top:20px;color:hsl(var(--muted-foreground));font-size:12px}.hidden{display:none!important}@media(max-width:840px){.topbar-inner{align-items:flex-start;flex-direction:column}.stats,.grid,.grid.equal{grid-template-columns:1fr}.tabs{width:100%;overflow:auto}.tab{white-space:nowrap}.row-button{grid-template-columns:minmax(0,1fr) 64px 58px}.session-card summary{align-items:flex-start;flex-direction:column}}" +
     "</style></head><body><header class=\"topbar\"><div class=\"topbar-inner\"><div><div class=\"title-row\"><span class=\"logo-dot\"></span><h1>Context X-Ray</h1></div><p class=\"meta\">Generated " + escapeHtml(report.generatedLabel) + " · mode=" + escapeHtml(report.mode) + " · source=" + escapeHtml(report.source) + " · since=" + escapeHtml(report.since) + "</p></div><nav class=\"tabs\" aria-label=\"Report views\"><button class=\"tab active\" data-tab=\"overview\">Overview</button><button class=\"tab\" data-tab=\"tools\">Tool Calls</button><button class=\"tab\" data-tab=\"mcp\">MCP</button><button class=\"tab\" data-tab=\"metadata\">Metadata</button><button class=\"tab\" data-tab=\"sessions\">Sessions</button></nav></div></header><main><section class=\"stats\" id=\"stats\"></section><section class=\"panel active\" id=\"panel-overview\"></section><section class=\"panel\" id=\"panel-tools\"></section><section class=\"panel\" id=\"panel-mcp\"></section><section class=\"panel\" id=\"panel-metadata\"></section><section class=\"panel\" id=\"panel-sessions\"></section><p class=\"footer\">Reads local transcript and MCP config files only. No transcript content is uploaded.</p></main><script type=\"application/json\" id=\"xray-data\">" + jsonScript(report) + "</script><script>" +
     "(function(){var report=JSON.parse(document.getElementById('xray-data').textContent);var cats=['user','assistant','tool_call','tool_output','reasoning','instructions','attachment','metadata','other'];var labels={user:'User asks',assistant:'Assistant text',tool_call:'Tool calls',tool_output:'Tool output',reasoning:'Reasoning',instructions:'Instructions/context',attachment:'Attachments',metadata:'Metadata',other:'Other'};var colors={user:'#8ba8ff',assistant:'#55b982',tool_call:'#f0a85b',tool_output:'#e06b73',reasoning:'#a77be8',instructions:'#6ac3d5',attachment:'#d6a85a',metadata:'#9aa3ad',other:'#c3c8ce'};function esc(v){return String(v||'').replace(/[&<>\"']/g,function(ch){return {'&':'&amp;','<':'&lt;','>':'&gt;','\"':'&quot;',\"'\":'&#39;'}[ch];});}function fmt(n){n=Number(n)||0;if(n>=1000000)return(n/1000000).toFixed(1)+'m';if(n>=1000)return(n/1000).toFixed(1)+'k';return String(n);}function tok(chars){chars=Number(chars)||0;return chars>0?Math.max(1,Math.ceil(chars/4)):0;}function pc(part,total){return total>0?Math.max(0,Math.min(100,(part/total)*100)):0;}function totalCounter(counter){return Object.keys(counter||{}).reduce(function(sum,key){return sum+(Number(counter[key])||0);},0);}function bar(counter){var total=totalCounter(counter);if(!total)return'<div class=\"bar\"></div>';return'<div class=\"bar\">'+cats.map(function(cat){var value=counter[cat]||0;if(!value)return'';return'<span title=\"'+esc(labels[cat])+'\" style=\"width:'+Math.max(1,pc(value,total)).toFixed(2)+'%;background:'+colors[cat]+'\"></span>';}).join('')+'</div>';}function metric(label,value){return'<article class=\"card\"><div class=\"eyebrow\">'+esc(label)+'</div><span class=\"stat-value\">'+esc(value)+'</span></article>';}function tableRows(entries,kind){if(!entries||!entries.length)return'<tr><td>None detected</td><td></td></tr>';return entries.map(function(entry){var value=entry[1];var shown=kind==='chars'?fmt(tok(value)):(kind==='tokens'?fmt(value):String(value));return'<tr><td>'+esc(entry[0])+'</td><td>'+esc(shown)+'</td></tr>';}).join('');}function toolToken(name){var found=(report.toolTokens||[]).filter(function(entry){return entry[0]===name;})[0];return found?found[1]:0;}function renderStats(){var counts=report.sourceCounts||{};document.getElementById('stats').innerHTML=metric('Sessions',report.sessionCount)+metric('Observed/estimated tokens',fmt(report.totalTokens))+metric('Codex',counts.codex||0)+metric('Claude',counts.claude||0);}function renderOverview(){var categoryTotal=totalCounter(report.categories);var categoryRows=cats.map(function(cat){var chars=(report.categories||{})[cat]||0;if(!chars)return'';return'<tr><td><span class=\"badge\"><span class=\"dot\" style=\"background:'+colors[cat]+'\"></span>'+esc(labels[cat])+'</span></td><td>'+fmt(tok(chars))+'</td><td>'+pc(chars,categoryTotal).toFixed(0)+'%</td></tr>';}).join('');document.getElementById('panel-overview').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>Where The Context Is Going</h2><p class=\"meta\">Approximate contribution by transcript bucket.</p></div></div>'+bar(report.categories)+'<table class=\"table\"><tbody>'+categoryRows+'</tbody></table></section><section class=\"card\"><div class=\"section-head\"><div><h2>Warnings And Optimizations</h2><p class=\"meta\">Promptable changes you control.</p></div></div><ol class=\"tips\">'+(report.recommendations||[]).map(function(tip){return'<li>'+esc(tip)+'</li>';}).join('')+'</ol></section></div><div class=\"grid equal\" style=\"margin-top:14px\"><section class=\"card\"><h2>Top Paths</h2><table class=\"table\"><tbody>'+tableRows(report.paths,'count')+'</tbody></table></section><section class=\"card\"><h2>Metadata Types</h2><table class=\"table\"><tbody>'+tableRows(report.metadata,'chars')+'</tbody></table></section></div>';}function renderTools(){var rows=(report.tools||[]).map(function(entry,index){var name=entry[0];var count=entry[1];return'<button class=\"row-button'+(index===0?' active':'')+'\" data-tool=\"'+esc(name)+'\"><span><span class=\"row-title\">'+esc(name)+'</span><span class=\"meta\">Click to inspect sampled calls</span></span><span class=\"row-meta\">x'+count+'</span><span class=\"row-meta\">'+fmt(toolToken(name))+' tok</span></button>';}).join('')||'<div class=\"empty\">No tool calls detected in these sessions.</div>';document.getElementById('panel-tools').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>Tool Calls</h2><p class=\"meta\">Calls are clickable; samples are capped so the report stays light.</p></div></div><div>'+rows+'</div></section><aside class=\"card detail\" id=\"tool-detail\"></aside></div>';Array.prototype.forEach.call(document.querySelectorAll('[data-tool]'),function(btn){btn.addEventListener('click',function(){Array.prototype.forEach.call(document.querySelectorAll('[data-tool]'),function(item){item.classList.remove('active');});btn.classList.add('active');renderToolDetail(btn.getAttribute('data-tool'));});});if((report.tools||[]).length)renderToolDetail(report.tools[0][0]);else document.getElementById('tool-detail').innerHTML='<h2>Tool Detail</h2><p class=\"empty\">Nothing to inspect yet.</p>';}function renderToolDetail(name){var events=(report.toolEvents||[]).filter(function(event){return event.tool===name;}).slice(0,30);document.getElementById('tool-detail').innerHTML='<div class=\"section-head\"><div><h2>'+esc(name)+'</h2><p class=\"meta\">'+events.length+' sampled call'+(events.length===1?'':'s')+'</p></div></div><div class=\"detail-list\">'+(events.map(function(event){return'<article class=\"sample\"><div class=\"sample-top\"><span>'+esc(event.source)+' · '+esc(event.sessionTitle||event.sessionId)+'</span><span>'+fmt(event.tokens||0)+' tok</span></div><p>'+esc(event.preview||'No preview captured.')+'</p></article>';}).join('')||'<p class=\"empty\">No sampled call payloads for this tool.</p>')+'</div>';}function renderMcp(){var servers=report.mcpServers||[];var usage=report.mcpUsage||[];var configured=servers.map(function(server){return'<button class=\"row-button\" data-mcp=\"'+esc(server.name)+'\"><span><span class=\"row-title\">'+esc(server.name)+'</span><span class=\"meta\">'+esc(server.source)+' · '+esc(server.target)+'</span></span><span class=\"row-meta\">config</span><span class=\"row-meta\"></span></button>';}).join('')||'<div class=\"empty\">No MCP server config found in the common local config files.</div>';var detected=usage.map(function(entry,index){return'<button class=\"row-button'+(!servers.length&&index===0?' active':'')+'\" data-mcp=\"'+esc(entry[0])+'\"><span><span class=\"row-title\">'+esc(entry[0])+'</span><span class=\"meta\">Detected from mcp__server__tool style names</span></span><span class=\"row-meta\">x'+entry[1]+'</span><span class=\"row-meta\"></span></button>';}).join('')||'<div class=\"empty\">No MCP-prefixed tool calls detected in the selected sessions.</div>';document.getElementById('panel-mcp').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>MCP Servers</h2><p class=\"meta\">Configured locally plus inferred calls from transcripts.</p></div></div><div class=\"mini-label\">Configured</div>'+configured+'<div class=\"mini-label\">Detected usage</div>'+detected+'</section><aside class=\"card detail\" id=\"mcp-detail\"></aside></div>';Array.prototype.forEach.call(document.querySelectorAll('[data-mcp]'),function(btn){btn.addEventListener('click',function(){Array.prototype.forEach.call(document.querySelectorAll('[data-mcp]'),function(item){item.classList.remove('active');});btn.classList.add('active');renderMcpDetail(btn.getAttribute('data-mcp'));});});if(usage.length)renderMcpDetail(usage[0][0]);else if(servers.length)renderMcpDetail(servers[0].name);else document.getElementById('mcp-detail').innerHTML='<h2>MCP Detail</h2><p class=\"empty\">Install or run sessions with MCP tools to see usage here.</p>';}function renderMcpDetail(name){var server=(report.mcpServers||[]).filter(function(item){return item.name===name;})[0];var tools=(report.mcpTools||[]).filter(function(entry){return entry[0].indexOf(name+' / ')===0;});var events=(report.toolEvents||[]).filter(function(event){return event.mcpServer===name;}).slice(0,25);document.getElementById('mcp-detail').innerHTML='<div class=\"section-head\"><div><h2>'+esc(name)+'</h2><p class=\"meta\">'+(server?esc(server.source+' · '+server.target):'Detected from tool call names')+'</p></div></div><div class=\"mini-label\">Tools</div><table class=\"table\"><tbody>'+tableRows(tools,'count')+'</tbody></table><div class=\"mini-label\">Sample calls</div><div class=\"detail-list\">'+(events.map(function(event){return'<article class=\"sample\"><div class=\"sample-top\"><span>'+esc(event.mcpTool||event.tool)+'</span><span>'+fmt(event.tokens||0)+' tok</span></div><p>'+esc(event.preview||'No preview captured.')+'</p></article>';}).join('')||'<p class=\"empty\">No sampled MCP calls for this server in the selected sessions.</p>')+'</div>';}function renderMetadata(){var rows=(report.metadata||[]).map(function(entry,index){return'<button class=\"row-button'+(index===0?' active':'')+'\" data-meta=\"'+esc(entry[0])+'\"><span><span class=\"row-title\">'+esc(entry[0])+'</span><span class=\"meta\">Click to inspect sampled records</span></span><span class=\"row-meta\">'+fmt(tok(entry[1]))+' tok</span><span class=\"row-meta\">'+fmt(entry[1])+' ch</span></button>';}).join('')||'<div class=\"empty\">No metadata-heavy records detected.</div>';document.getElementById('panel-metadata').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>Metadata</h2><p class=\"meta\">Breakdown by transcript record type.</p></div></div>'+rows+'</section><aside class=\"card detail\" id=\"metadata-detail\"></aside></div>';Array.prototype.forEach.call(document.querySelectorAll('[data-meta]'),function(btn){btn.addEventListener('click',function(){Array.prototype.forEach.call(document.querySelectorAll('[data-meta]'),function(item){item.classList.remove('active');});btn.classList.add('active');renderMetadataDetail(btn.getAttribute('data-meta'));});});if((report.metadata||[]).length)renderMetadataDetail(report.metadata[0][0]);else document.getElementById('metadata-detail').innerHTML='<h2>Metadata Detail</h2><p class=\"empty\">Nothing to inspect yet.</p>';}function renderMetadataDetail(type){var events=(report.metadataEvents||[]).filter(function(event){return event.type===type;}).slice(0,30);document.getElementById('metadata-detail').innerHTML='<div class=\"section-head\"><div><h2>'+esc(type)+'</h2><p class=\"meta\">'+events.length+' sampled record'+(events.length===1?'':'s')+'</p></div></div><div class=\"detail-list\">'+(events.map(function(event){return'<article class=\"sample\"><div class=\"sample-top\"><span>'+esc(event.source)+' · '+esc(event.sessionTitle||event.sessionId)+'</span><span>'+fmt(event.tokens||0)+' tok</span></div><p>'+esc(event.preview||'No preview captured.')+'</p></article>';}).join('')||'<p class=\"empty\">No sampled records for this metadata type.</p>')+'</div>';}function renderSessions(){document.getElementById('panel-sessions').innerHTML=(report.sessions||[]).map(function(session,index){var catRows=Object.keys(session.categories||{}).sort(function(a,b){return session.categories[b]-session.categories[a];}).map(function(cat){var chars=session.categories[cat];return'<tr><td>'+esc(labels[cat]||cat)+'</td><td>'+fmt(tok(chars))+'</td><td>'+pc(chars,session.totalChars||0).toFixed(0)+'%</td></tr>';}).join('');var tools=(session.tools?Object.keys(session.tools):[]).sort(function(a,b){return session.tools[b]-session.tools[a];}).slice(0,8).map(function(name){return'<span class=\"badge\">'+esc(name)+' x'+session.tools[name]+'</span>';}).join('')||'<span class=\"empty\">none detected</span>';var paths=(session.paths?Object.keys(session.paths):[]).sort(function(a,b){return session.paths[b]-session.paths[a];}).slice(0,8).map(function(name){return'<span class=\"badge\">'+esc(name)+' x'+session.paths[name]+'</span>';}).join('')||'<span class=\"empty\">none detected</span>';return'<details class=\"session-card\"'+(index===0?' open':'')+'><summary><span><span class=\"eyebrow\">'+esc(session.source)+' · '+esc(session.updatedAt||'unknown time')+'</span><span class=\"session-title\">'+esc(session.title||session.sessionId)+'</span><span class=\"session-path\">'+esc(session.cwd||session.path)+'</span></span><span class=\"token-big\">'+fmt(session.tokens)+'</span></summary><div class=\"session-body\">'+bar(session.categories)+'<div class=\"grid equal\"><div><div class=\"mini-label\">Buckets</div><table class=\"table\"><tbody>'+catRows+'</tbody></table></div><div><div class=\"mini-label\">Frequent tools</div><div class=\"badge-list\">'+tools+'</div><div class=\"mini-label\">Repeated paths</div><div class=\"badge-list\">'+paths+'</div></div></div></div></details>';}).join('')||'<section class=\"card\"><p class=\"empty\">No matching sessions found.</p></section>';}function activate(name){Array.prototype.forEach.call(document.querySelectorAll('.tab'),function(tab){tab.classList.toggle('active',tab.getAttribute('data-tab')===name);});Array.prototype.forEach.call(document.querySelectorAll('.panel'),function(panel){panel.classList.toggle('active',panel.id==='panel-'+name);});if(location.hash!=='#'+name)history.replaceState(null,'','#'+name);}Array.prototype.forEach.call(document.querySelectorAll('.tab'),function(tab){tab.addEventListener('click',function(){activate(tab.getAttribute('data-tab'));});});renderStats();renderOverview();renderTools();renderMcp();renderMetadata();renderSessions();var initial=(location.hash||'#overview').slice(1);if(document.getElementById('panel-'+initial))activate(initial);})();" +

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import { fileURLToPath } from "url";
 import * as Sentry from "@sentry/node";
 
 import { resolveDeployPostBuildInvocation } from "./deploy-build.js";
+import { createCliTelemetry } from "./telemetry.js";
 
 // Resolve version once at module scope — used by both --version and --help
 let _version = "unknown";
@@ -170,6 +171,12 @@ const BUGS_URL = "https://github.com/BuilderIO/agent-native/issues";
 const command = process.argv[2];
 // Filter out bare "--" separators that pnpm inserts between its args and script args
 const args = process.argv.slice(3).filter((a) => a !== "--");
+const cliTelemetry = createCliTelemetry({
+  cli: "core",
+  cliVersion: _version,
+  command: command ?? "none",
+  interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+});
 
 function parseScaffoldArgs(argv: string[]): {
   name?: string;
@@ -203,25 +210,34 @@ function parseScaffoldArgs(argv: string[]): {
 // Track CLI usage (best-effort, non-blocking)
 function trackCli(event: string, props?: Record<string, unknown>): void {
   try {
-    void import("../tracking/registry.js")
-      .then((m) => m.track(event, { command, ...props }))
-      .catch(() => undefined);
-    void import("../tracking/providers.js")
-      .then((m) => m.registerBuiltinProviders())
-      .catch(() => undefined);
+    cliTelemetry.track(event, { command, ...props });
+  } catch {}
+}
+
+function captureCliException(
+  error: unknown,
+  context?: Parameters<typeof cliTelemetry.captureException>[1],
+): void {
+  try {
+    cliTelemetry.captureException(error, context);
   } catch {}
 }
 
+function flushTelemetryAndExit(code: number): void {
+  void Promise.allSettled([cliTelemetry.flush(), Sentry.flush(2000)]).finally(
+    () => process.exit(code),
+  );
+}
+
 // Global error handler — show feedback link on unhandled crashes
 process.on("uncaughtException", (err) => {
   console.error(`\n  Unexpected error: ${err.message}\n`);
   console.error(`  Report this bug: ${BUGS_URL}`);
   console.error(`  Send feedback:   ${FEEDBACK_URL}\n`);
   trackCli("cli.crash", { error: err.message });
+  captureCliException(err, { handled: false, tags: { source: "process" } });
   Sentry.captureException(err);
-  void Sentry.flush(2000)
-    .catch(() => undefined)
-    .finally(() => process.exit(1));
+  flushTelemetryAndExit(1);
 });
 
 process.on("unhandledRejection", (reason: any) => {
@@ -229,16 +245,18 @@ process.on("unhandledRejection", (reason: any) => {
   console.error(`  Report this bug: ${BUGS_URL}`);
   console.error(`  Send feedback:   ${FEEDBACK_URL}\n`);
   trackCli("cli.crash", { error: reason?.message ?? String(reason) });
+  captureCliException(reason, {
+    handled: false,
+    tags: { source: "unhandled-rejection" },
+  });
   Sentry.captureException(reason);
-  void Sentry.flush(2000)
-    .catch(() => undefined)
-    .finally(() => process.exit(1));
+  flushTelemetryAndExit(1);
 });
 
 // Surface a self-heal hint when an interrupted `npx @agent-native/core@latest ...`
 // leaves a half-extracted package in the npx cache and a follow-up run fails
 // to load one of our own sub-modules.
-function handleScaffoldImportError(err: any): never {
+function handleScaffoldImportError(err: any): void {
   const msg = err?.message ?? String(err);
   const looksLikeCorruptCache =
     err?.code === "ERR_MODULE_NOT_FOUND" ||
@@ -255,9 +273,12 @@ function handleScaffoldImportError(err: any): never {
     console.error(`\n  Failed to load the scaffolder: ${msg}\n`);
   }
   trackCli("cli.scaffold.import_error", { error: msg });
+  captureCliException(err, {
+    handled: false,
+    tags: { source: "scaffold-import" },
+  });
   Sentry.captureException(err);
-  Sentry.flush(2000).finally(() => process.exit(1));
-  throw err;
+  flushTelemetryAndExit(1);
 }
 
 function findBinUpwards(binName: string): string | undefined {
@@ -525,7 +546,17 @@ function runBuildStep(
           stage: "spawn",
         },
       });
-      Sentry.flush(2000).finally(() => process.exit(1));
+      captureCliException(err, {
+        handled: false,
+        tags: {
+          source: "build-step",
+          buildStep: opts.label,
+          ...(template ? { template } : {}),
+          ...(app ? { app } : {}),
+        },
+        extra: { stage: "spawn" },
+      });
+      flushTelemetryAndExit(1);
     });
 
     child.on("exit", (code, signal) => {
@@ -557,8 +588,18 @@ function runBuildStep(
           stdoutTail: stdoutBuf,
         },
       });
+      captureCliException(err, {
+        handled: false,
+        tags: {
+          source: "build-step",
+          buildStep: opts.label,
+          ...(template ? { template } : {}),
+          ...(app ? { app } : {}),
+        },
+        extra: { exitCode, signal: signal ?? null },
+      });
       // Don't throw — see comment on runBuildStep above.
-      Sentry.flush(2000).finally(() => process.exit(exitCode));
+      flushTelemetryAndExit(exitCode);
     });
   });
 }
@@ -690,8 +731,12 @@ switch (command) {
       // implies a programming error in the orchestration above. Capture
       // and exit so the global unhandledRejection handler doesn't double-
       // report with a generic title.
+      captureCliException(err, {
+        handled: false,
+        tags: { source: "orchestration" },
+      });
       Sentry.captureException(err);
-      Sentry.flush(2000).finally(() => process.exit(1));
+      flushTelemetryAndExit(1);
     });
     break;
   }

package/src/cli/skills.ts

@@ -4454,6 +4454,11 @@ export async function runSkills(
       error: error instanceof Error ? error.message : String(error),
       durationMs: Date.now() - startedAt,
     });
+    telemetry.captureException(error, {
+      handled: false,
+      tags: { source: "skills-command", command: parsed.command },
+      extra: { durationMs: Date.now() - startedAt },
+    });
     throw error;
   } finally {
     await telemetry.flush();

package/src/cli/telemetry.ts

@@ -38,9 +38,17 @@ export interface CliTelemetryOptions {
 
 export interface CliTelemetry {
   track(event: string, properties?: Record<string, unknown>): void;
+  captureException(error: unknown, context?: CliExceptionContext): void;
   flush(): Promise<void>;
 }
 
+export interface CliExceptionContext {
+  handled?: boolean;
+  level?: "fatal" | "error" | "warning" | "info" | "debug";
+  tags?: Record<string, string | number | boolean | null | undefined>;
+  extra?: Record<string, unknown>;
+}
+
 function resolvePublicKey(): string {
   const fromEnv = process.env.AGENT_NATIVE_ANALYTICS_PUBLIC_KEY?.trim();
   return fromEnv || EMBEDDED_PUBLIC_KEY;
@@ -60,6 +68,110 @@ function telemetryDisabled(): boolean {
   );
 }
 
+const MAX_EXCEPTION_MESSAGE_LENGTH = 1000;
+const MAX_EXCEPTION_STACK_LENGTH = 8000;
+const MAX_EXCEPTION_TAGS = 30;
+const MAX_EXCEPTION_EXTRA_KEYS = 30;
+const MAX_EXCEPTION_VALUE_LENGTH = 1000;
+const SECRET_RE = /\b(?:bearer|basic)\s+[^\s]+/gi;
+const SECRET_KEY_RE =
+  /(?:authorization|cookie|set[-_]?cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)/i;
+
+function redactExceptionText(value: string): string {
+  return value
+    .replace(SECRET_RE, (match) => `${match.split(/\s+/, 1)[0]} <redacted>`)
+    .replace(
+      /([A-Za-z0-9_$.-]*(?:authorization|cookie|token|secret|password|passwd|pwd|api[-_]?key|apikey|credential)[A-Za-z0-9_$.-]*\s*[:=]\s*)([^\s,;}]+)/gi,
+      "$1<redacted>",
+    );
+}
+
+function boundedExceptionText(value: unknown, max: number): string {
+  const text =
+    typeof value === "string" ? value : String(value ?? "Unknown error");
+  const safe = redactExceptionText(text);
+  return safe.length > max ? safe.slice(0, max) : safe;
+}
+
+function safeExceptionValue(value: unknown, depth = 2): unknown {
+  if (
+    value == null ||
+    typeof value === "boolean" ||
+    typeof value === "number"
+  ) {
+    return value;
+  }
+  if (typeof value === "string") {
+    return boundedExceptionText(value, MAX_EXCEPTION_VALUE_LENGTH);
+  }
+  if (depth <= 0)
+    return boundedExceptionText(value, MAX_EXCEPTION_VALUE_LENGTH);
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, 20)
+      .map((item) => safeExceptionValue(item, depth - 1));
+  }
+  if (typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (Object.keys(out).length >= MAX_EXCEPTION_EXTRA_KEYS) break;
+      const safeKey = boundedExceptionText(key, 100);
+      out[safeKey] = SECRET_KEY_RE.test(safeKey)
+        ? "<redacted>"
+        : safeExceptionValue(child, depth - 1);
+    }
+    return out;
+  }
+  return boundedExceptionText(value, MAX_EXCEPTION_VALUE_LENGTH);
+}
+
+function captureException(
+  error: unknown,
+  context: CliExceptionContext,
+  trackEvent: (event: string, properties?: Record<string, unknown>) => void,
+): void {
+  const exception =
+    error instanceof Error
+      ? {
+          type: boundedExceptionText(error.name || "Error", 200),
+          message: boundedExceptionText(
+            error.message || error.name || "Error",
+            MAX_EXCEPTION_MESSAGE_LENGTH,
+          ),
+          stack: error.stack
+            ? boundedExceptionText(error.stack, MAX_EXCEPTION_STACK_LENGTH)
+            : undefined,
+        }
+      : {
+          type: "Error",
+          message: boundedExceptionText(error, MAX_EXCEPTION_MESSAGE_LENGTH),
+          stack: undefined,
+        };
+  const tags: Record<string, string> = {};
+  for (const [key, value] of Object.entries(context.tags ?? {})) {
+    if (Object.keys(tags).length >= MAX_EXCEPTION_TAGS || value == null) break;
+    const safeKey = boundedExceptionText(key, 100);
+    tags[safeKey] = SECRET_KEY_RE.test(safeKey)
+      ? "<redacted>"
+      : boundedExceptionText(value, 200);
+  }
+  const extra = safeExceptionValue(context.extra);
+  trackEvent("$exception", {
+    app: "agent-native-cli",
+    template: "cli",
+    runtime: "cli",
+    source: "cli",
+    exceptionType: exception.type,
+    exceptionMessage: exception.message,
+    ...(exception.stack ? { exceptionStack: exception.stack } : {}),
+    handled: context.handled ?? false,
+    level: context.level ?? "error",
+    occurredAt: new Date().toISOString(),
+    ...(Object.keys(tags).length ? { exceptionTags: tags } : {}),
+    ...(extra && typeof extra === "object" ? { exceptionExtra: extra } : {}),
+  });
+}
+
 /**
  * Read (or lazily create) a stable per-machine install id, shared across both
  * skills CLIs so one developer counts once. Best-effort: an unwritable home
@@ -132,5 +244,10 @@ export function createCliTelemetry(options: CliTelemetryOptions): CliTelemetry {
     ]);
   }
 
-  return { track, flush };
+  return {
+    track,
+    captureException: (error, context = {}) =>
+      captureException(error, context, track),
+    flush,
+  };
 }

package/src/client/AgentPanel.tsx

@@ -2745,6 +2745,12 @@ export interface AgentSidebarProps {
    * page-level AgentChatSurface can morph into it on navigation.
    */
   chatViewTransition?: boolean;
+  /**
+   * Mark the initial panel mount as the destination of a page-to-sidebar chat
+   * handoff. This suppresses only the drawer's initial entry animation; normal
+   * sidebar open/close transitions remain enabled.
+   */
+  chatViewTransitionHandoff?: boolean;
   /** Namespace for persisted chat state. Use the same key as AgentChatHome. */
   storageKey?: string;
   /** Open the sidebar when a chat run is active or reconnects. */
@@ -2784,6 +2790,7 @@ export function AgentSidebar({
   animateMobile = true,
   animateDesktop = true,
   chatViewTransition = false,
+  chatViewTransitionHandoff = false,
   storageKey,
   openOnChatRunning = false,
   onFullscreenRequest,
@@ -3308,6 +3315,9 @@ export function AgentSidebar({
         data-agent-sidebar-position={position}
         data-agent-sidebar-state={panelOpen ? "open" : "closed"}
         data-agent-sidebar-resizing={isResizing ? "true" : undefined}
+        data-agent-sidebar-chat-handoff={
+          chatViewTransitionHandoff ? "true" : undefined
+        }
         style={
           chatViewTransition
             ? getAgentChatViewTransitionStyle(panelStyle)

package/src/client/CommandMenu.tsx

@@ -576,6 +576,14 @@ CommandMenu.Separator = CommandSeparator;
 
 // ─── Keyboard Hook ──────────────────────────────────────────────────────────
 
+export const COMMAND_MENU_OPEN_EVENT = "agent-native:open-command-menu";
+
+export function openCommandMenu() {
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(new Event(COMMAND_MENU_OPEN_EVENT));
+  }
+}
+
 /**
  * Hook to handle Cmd+K (or Ctrl+K) to open the command menu
  */
@@ -601,10 +609,14 @@ export function useCommandMenuShortcut(
         onOpen();
       }
     };
+    const handleOpenRequest = () => onOpen();
     const useCapture = Boolean(options.allowContentEditable);
     document.addEventListener("keydown", handleKeyDown, useCapture);
-    return () =>
+    window.addEventListener(COMMAND_MENU_OPEN_EVENT, handleOpenRequest);
+    return () => {
       document.removeEventListener("keydown", handleKeyDown, useCapture);
+      window.removeEventListener(COMMAND_MENU_OPEN_EVENT, handleOpenRequest);
+    };
   }, [onOpen, options.allowContentEditable]);
 }