@agent-native/core 0.129.1 → 0.130.0

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1629
+- core files: 1635
 - toolkit files: 160
-- template files: 6870
+- template files: 6924

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @agent-native/core
 
+## 0.130.0
+
+### Minor Changes
+
+- 279e855: Add a first-class CLI flow for installing community-maintained Agent Native templates from public GitHub repositories, including app selection from community workspace repositories.
+- 279e855: Render compact data exports and durable workspace files as private downloads directly in agent chat.
+- 279e855: Point org members at their own workspace when they land on a different deployment.
+
+  Orgs can now record a `workspaceUrl` (Settings → Team, owner/admin). Members who
+  open a shared hosted app from the template catalog see a notice offering to take
+  them to their team's workspace instead of an app that looks empty, and the org
+  switcher shows which host they are currently on. Opt-in per org — nothing
+  changes for orgs that don't set it, and it offers a choice rather than
+  redirecting.
+
+### Patch Changes
+
+- 279e855: Let a browser explicitly sign out of the shared `AUTH_DISABLED` development account so preview users can choose a real account.
+- 279e855: Add comment author editing to the Clips template corpus.
+- 279e855: Retry transient SQLite locks while a fresh local app enables WAL during startup.
+- 279e855: Prevent frontend action calls from failing with 405 errors when a mutating action declares PUT or DELETE and the caller uses the default mutation transport.
+- 279e855: Prevent sketch wireframes from overflowing the browser call stack when layout measurements contain non-finite coordinates.
+- 279e855: Fix the chat client telling users "the agent connection kept failing" when a
+  turn was actually stopped by `MAX_TOTAL_TRANSIENT_CONTINUATIONS`, the
+  whole-turn ceiling on client re-POSTs of `auto_continue`. That cap only ever
+  binds turns that were making real progress the whole time, so blaming a
+  connection failure named the wrong cause. It now reports its own message:
+  the turn hit the limit on how many times it could be automatically
+  continued, and suggests retrying as a single, narrower request.
+- 279e855: Stop reporting `$ai_generation` token/cost figures as literal `0` when the
+  engine never returned a usage report — every run aborted for no-progress
+  before any provider response arrived was indistinguishable from a real
+  empty-input call, which made it impossible to size the input of failing
+  runs. `input_tokens`, `output_tokens`, `total_tokens`, `cache_read_tokens`,
+  `cache_write_tokens`, `cost_cents_x100`, `cost_usd`, and their `$ai_*`
+  equivalents are now omitted from the tracking event instead of coerced to
+  zero when the engine never reported usage. Also adds `time_to_first_token_ms`,
+  measuring elapsed time from run start to the first non-heartbeat engine
+  event, omitted (not zeroed) when no such event ever arrived.
+- 279e855: Emit an `agent_run_terminal` analytics event for every terminal agent run
+  (completed, errored, aborted, or truncated at a continuation boundary),
+  reusing the same best-effort `track()` seam that already carries
+  `$ai_generation` into `analytics_events`. Run cutoffs — budget exhaustion,
+  loop limits, aborts, and the `truncated` continuation status — were
+  previously visible only in each app's operational `agent_runs` table and
+  absent from analytics entirely. The event carries `run_id`, `thread_id`,
+  `turn_id`, `status`, `terminal_reason`, `error_code`, `error_detail`,
+  `dispatch_mode`, `abort_reason`, and `duration_ms`; `model`/`engine`/
+  `attempt_count` are forwarded through the new optional `StartRunOptions`
+  fields, now populated by every built-in `startRun` caller (main chat,
+  agent teams, harness runs, integration webhooks, the Google Docs poller,
+  and recurring jobs) with the resolved model actually sent to the engine —
+  never the raw client-requested one. `userId` is left unset everywhere: no
+  caller in this codebase has an opaque (non-email) user id available at its
+  `startRun` call site. Emission fires only after the run's terminal status
+  and thread_data are durably persisted, and a missing or failing tracking
+  provider can never affect the run.
+- 279e855: Keep a failed or stopped run visible on the turn it belongs to. The assistant
+  turn now carries a collapsed inline marker built from the persisted run-error
+  metadata (with the run duration when known), so the failure survives the next
+  prompt instead of only existing in the transient recovery banner. The banner
+  still owns the run it is showing, so the same failure is never announced twice.
+- 279e855: Default MCP connections to personal OAuth, keep personal MCP setup available to organization members, hide unusable organization controls, and honor app preset filters in ejected UIs.
+- 279e855: Prevent queued chat prompts from replaying after navigation or remounting the chat.
+- 279e855: Recover AI SDK provider network failures after its internal retry wrapper preserves the final transport error.
+- 279e855: Fix document bridge injection when page scripts contain closing-tag or dollar-sign literals.
+- 279e855: Correct the Dispatch setup docs to match the current workspace picker.
+- 279e855: Fix `/_agent-native/open` silently dropping a `Set-Cookie` staged during `getSession()` (e.g. `_session` query-param promotion) when it built a bare 302 `Response`, so an authenticated redirect could still leave the browser signed out. Export `redirectWithStagedCookies` so other routes can reuse the fix.
+- 279e855: Add `isLoopbackRequest` to the request context and a `getRequestIsLoopback()` reader. The action-route handler captures the real socket peer (via `getRequestIP` without `x-forwarded-for`, so headers cannot spoof it) while the h3 event is still in scope, letting code below the HTTP layer distinguish a local-dev caller from a remote one. Used by Design to let `/visual-edit` work without a login on a localhost-backed design while keeping remote viewers read-only.
+- Updated dependencies [279e855]
+  - @agent-native/toolkit@0.10.12
+
+## 0.129.2
+
+### Patch Changes
+
+- 21e33c7: Keep asynchronous `ask_app` task handles and exact polling arguments visible to MCP callers so they can retrieve the same cross-app task without resubmitting it.
+
 ## 0.129.1
 
 ### Patch Changes

package/corpus/core/docs/content/cloneable-saas.mdx

@@ -35,6 +35,120 @@ Don't want a domain app? Use [Chat](/docs/template-chat) when you want a basic a
 
 See the full catalog under [Apps](/apps), or jump straight to one — for example, [Dispatch](/docs/template-dispatch) is a great place to start if you want a workspace-style app.
 
+## Community templates {#community-templates}
+
+The named templates in the CLI picker are **first-party**: Agent Native
+maintains, tests, documents, and releases them with the framework. A
+**community template** is maintained and versioned by its repository owner. It
+can use the same framework surface, but a community listing is not an
+endorsement or a promise of support from Agent Native.
+
+Run `create`, choose **Community template**, and paste a plain public GitHub
+repository URL:
+
+```bash
+https://github.com/owner/repo
+```
+
+If the repository root is a single Agent Native app, the CLI installs it
+directly without another picker. If the repository is an Agent Native workspace,
+the CLI discovers valid direct children of `apps/*`, excludes `dispatch`, and
+asks which app to install.
+
+A non-empty `agent-native.workspaceCore` marker makes the repository a
+workspace even when its root package also depends on `@agent-native/core`; a
+malformed marker is rejected.
+
+Pass the same plain URL to `--template` for scripts, or use the shorter
+`community:` form. Pin a branch, tag, or commit after `#` when you want a
+reproducible starting point. Without a ref, the CLI tries `main`, then `master`:
+
+```bash
+npx @agent-native/core@latest create my-app --template community:owner/repo#v1.2.0
+npx @agent-native/core@latest create my-app --template https://github.com/owner/repo#v1.2.0
+```
+
+For a workspace repository, make the source-app choice non-interactive with
+`?app=<app-name>`. The selector comes before the optional `#ref`. Keep the
+whole value quoted because shells such as zsh treat `?` as a glob:
+
+```bash
+npx @agent-native/core@latest create my-app --template 'community:owner/repo?app=analytics#v1.2.0'
+npx @agent-native/core@latest create my-app --template 'https://github.com/owner/repo?app=analytics#v1.2.0'
+```
+
+Outside a workspace, `create` makes the selected source app standalone. To add
+it to an existing workspace, pass the community repository explicitly because
+the `add-app` picker lists first-party templates only. Omit `?app` to choose
+from the source workspace interactively, or include it for a scriptable install:
+
+```bash
+npx @agent-native/core@latest add-app my-app --template community:owner/repo#v1.2.0
+npx @agent-native/core@latest add-app my-app --template 'community:owner/repo?app=analytics#v1.2.0'
+```
+
+Only public GitHub repositories are accepted. Private repositories, non-GitHub
+hosts, GitHub tree or subdirectory URLs, and nested app paths are not supported.
+A root app must have a readable `package.json` that lists
+`@agent-native/core` in `dependencies`, `devDependencies`, or
+`peerDependencies`. In a workspace repository, each selectable source app must
+meet the same requirement directly under `apps/<app-name>/`; `dispatch` is
+never selectable.
+
+Community workspace apps must be portable leaves, not arbitrary monorepo
+slices:
+
+- default `catalog:` dependency references are resolved from the source
+  repository's root `pnpm-workspace.yaml`; named catalog references are not
+  supported;
+- `workspace:*` references to `@agent-native/core`, `@agent-native/dispatch`,
+  and `@agent-native/toolkit` are rewritten to published versions. Other
+  sibling workspace packages are not copied, so publish them and use a concrete
+  version instead;
+- the source `workspaceCore` dependency is removed. Canonical inherited
+  workspace auth and agent-chat plugins are detached for a standalone install
+  or rebound to the destination workspace. Any other import of the source
+  `workspaceCore` package fails clearly; move that code into the app or publish
+  it as a concrete dependency.
+
+Keep the rest of each complete app with its `package.json`: `agent-native.json`
+when used, source, actions, agent instructions, and database setup. A
+catalog-ready repository should also include:
+
+- a license and a maintainer or support link;
+- a README with setup steps, required environment variables, and the exact CLI
+  command;
+- an `.env.example` containing placeholders only, with no secrets, customer
+  data, runtime databases, or generated build output;
+- a working install, development command, typecheck, and tests appropriate to
+  the template.
+
+The installer records the resolved `source` and `ref` under
+`agent-native.communityTemplate` in the installed app's `package.json`. Apps
+selected from a workspace repository also record the source app as
+`agent-native.communityTemplate.app`. `agent-native template sync` remains
+first-party-only; review a newer upstream ref and merge its changes yourself
+when updating a community template.
+
+See [Creating Templates](/docs/creating-templates) for the full app, action,
+state, security, and publishing checklist.
+
+> **Review community code before installing dependencies or running it.**
+> Community templates are downloaded from third-party repositories; Agent
+> Native does not sandbox, audit, or maintain them. The CLI downloads source
+> only; it does not install dependencies or run template scripts. Inspect the
+> source, license, dependencies, and package install scripts, and prefer a
+> pinned trusted ref.
+
+A hosted demo is optional. If you provide one, make it a public try-it link and
+document any sign-in, seed-data, or provider requirements. The repository
+remains the install source of truth, and the repository owner remains
+responsible for both the template and demo.
+
+Want to be listed? [Submit a community template](https://github.com/BuilderIO/agent-native/issues/new?template=community-template.yml)
+with the repository URL, a one-sentence description, maintainer and license
+details, the tested CLI command, and an optional hosted demo URL.
+
 ## What you get out of the box {#what-you-get}
 
 Every example app ships with the parts that normally take months to build:

package/corpus/core/docs/content/creating-templates.mdx

@@ -501,12 +501,38 @@ Before sharing:
 4. Document required env vars and onboarding steps.
 5. Include examples or seed rows through additive migrations, not tracked runtime data files.
 
-Community templates can be created from a GitHub repo:
+Community templates install directly from a public GitHub repository. Put the
+Agent Native app at the repository root:
 
 ```bash
-npx @agent-native/core@latest create my-app --template github:user/repo
+npx @agent-native/core@latest create my-app --template community:owner/repo
 ```
 
+Add `#branch`, `#tag`, or `#commit` when you want people to install a specific
+revision:
+
+```bash
+npx @agent-native/core@latest create my-app --template community:owner/repo#v1.0.0
+```
+
+The CLI downloads the source only. It does not install dependencies or run the
+template's scripts. Community templates are third-party code, so review the
+repository, license, dependencies, and install scripts before running
+`pnpm install`.
+
+To be listed in the community catalog, include:
+
+- A focused, complete Agent Native app at the repository root.
+- A public repository with a license and a README that covers setup, required
+  environment variables, and what the template does.
+- A root `package.json` that depends on `@agent-native/core`.
+- Passing typechecks and tests.
+- Optionally, a hosted version people can try and a representative screenshot.
+
+[Submit a community template](https://github.com/BuilderIO/agent-native/issues/new?template=community-template.yml)
+when the repository is ready. Community listings stay separate from the
+smaller first-party catalog and remain maintained by their authors.
+
 ## Contributing to the framework monorepo {#contributing}
 
 ### Test unpublished framework changes {#test-unpublished-framework-changes}

package/corpus/core/docs/content/syncing-template-changes.mdx

@@ -11,6 +11,13 @@ description: "agent-native template pulls later upstream first-party template ch
 
 `agent-native template` is the missing half. It re-fetches the template at a newer version, re-applies the exact transforms `create` applied, and merges the result into your app file by file.
 
+Community templates are intentionally outside this sync flow. Their
+`agent-native.communityTemplate` metadata records where the installed source
+came from, but it is not first-party scaffold provenance and `agent-native
+template sync` will not pull from that repository. Install a pinned community
+ref when you need a stable starting point, then review and port later upstream
+changes manually.
+
 ## Quick start {#quick-start}
 
 ```bash

package/corpus/core/docs/content/template-clips-developers.mdx

@@ -64,7 +64,7 @@ For local development, run the web app with `pnpm dev` and point the desktop tra
 
 **Chrome extension.** The Agent-Native Clips Chrome extension listing is `https://chromewebstore.google.com/detail/baoipacpchggcdigagnajakiidcgcffn`. If you host your own Clips server, keep the Chrome extension option hidden until your Web Store listing is live. Set `VITE_CLIPS_CHROME_EXTENSION_ENABLED=1` after approval to show the extension beside desktop-app download prompts. Set `VITE_CLIPS_CHROME_EXTENSION_URL` only if you need to override the default listing URL. See [Capturing Everywhere](/docs/template-clips-capture-everywhere#browser-logs-with-the-chrome-extension) for what the extension captures.
 
-**Embedded bug reports.** Clips can be embedded into an existing product as a lightweight bug-report launcher. The embedded page collects issue metadata, opens the real recorder in a top-level browser window (browser media capture requires a top-level user gesture), and posts a completion message back to the host product when the recording is saved.
+**Embedded bug reports.** Clips can be embedded into an existing product as a lightweight bug-report launcher. The embedded page collects issue metadata, opens the real recorder in a top-level browser window (browser media capture requires a top-level user gesture), and relays a completion message back to the host product when the recording is saved.
 
 Use `/bug-report` as the iframe URL. The page accepts either plain query parameters or the `bugReport*`-prefixed parameters that the recorder stores:
 
@@ -76,18 +76,25 @@ Use `/bug-report` as the iframe URL. The page accepts either plain query paramet
 ></iframe>
 ```
 
-Supported metadata fields are `projectId`, `title`, `description`, `severity` (`low`, `normal`, `high`, `urgent`), `sourceUrl`, `pageTitle`, `appVersion`, `environment`, `reporterEmail`, `reporterName`, `reporterId`, `metadata` (JSON object), and `returnUrl`. The recorder redirects to `/bug-report/done` after upload and sends this browser message to `window.opener` and the parent frame:
+If the host product already has its own launcher UI, it can open `/record` directly with `bugReport=1`, `intent=bug-report`, `mode=screen`, `surface=browser`, and the same fields prefixed with `bugReport`, such as `bugReportProjectId` and `bugReportReturnUrl`.
+
+Supported metadata fields are `projectId`, `title`, `description`, `severity` (`low`, `normal`, `high`, `urgent`), `sourceUrl`, `pageTitle`, `appVersion`, `environment`, `reporterEmail`, `reporterName`, `reporterId`, `metadata` (JSON object), and `returnUrl`. Keep query metadata small and avoid secrets, customer data, and other sensitive values. The recorder redirects to `/bug-report/done` after upload and sends this browser message to `window.opener`; the `/bug-report` iframe relays the same message to its parent:
 
 ```js
 window.addEventListener("message", (event) => {
+  if (event.origin !== "https://clips.example.com") return;
   if (event.data?.type !== "agent-native.clips.bug-report.submitted") return;
-  console.log(event.data.recordingId, event.data.recordingUrl);
+  if (event.data.agentAccessStatus === "ready") {
+    console.log(event.data.agentContextUrl, event.data.agentAccessExpiresAt);
+  }
 });
 ```
 
-Bug-report recordings default to workspace visibility instead of public visibility. The saved `recording_bug_reports` sidecar includes the redacted host metadata, while the recording itself remains the canonical media/transcript resource. URLs have credentials, fragments, and query values removed before storage, and the browser-diagnostics pipeline still omits request/response bodies, headers, and cookies.
+Always validate both `event.origin` and `event.source` in the host. The completion payload includes `recordingId`, `recordingUrl`, `embedUrl`, `agentShareUrl`, `agentContextUrl`, `agentAccessExpiresAt`, and an explicit `agentAccessStatus` of `ready` or `unavailable`. When access is ready, `agentContextUrl` is a temporary, scoped URL that lets an agent read recording metadata, timestamped transcript segments, recommended frames and frame URLs, and browser diagnostics without receiving the user's workspace session. Normal agent links expire after two hours; embedded bug-report completions use a seven-day scoped link so asynchronous support tickets can be triaged. Treat an unavailable or expired link as an access failure, not an empty recording. `embedUrl` remains subject to the recording's normal viewer access.
+
+Bug-report recordings default to workspace visibility instead of public visibility. The saved `recording_bug_reports` sidecar includes the redacted host metadata, while the recording itself remains the canonical media/transcript resource. URLs have credentials, fragments, and query values removed before storage, and the browser-diagnostics pipeline still omits request/response bodies, headers, and cookies. A popup recording only sees diagnostics emitted inside the Clips window. Use the Chrome extension or attach diagnostics from the host product separately when the agent needs console and network context from the source tab.
 
-This first version assumes the reporter can sign in to the Clips workspace that owns the recording. A fully anonymous customer intake should add a signed intake token that can create, upload, and finalize a recording without granting broad recording access; do not expose the existing owner-scoped upload endpoints directly to anonymous users.
+This pilot requires the reporter to already have an active session in the Clips workspace that owns the recording. The current cross-origin popup cannot preserve its completion channel through a first-time sign-in redirect, so users should sign in to Clips in a separate tab before launching it. A fully anonymous customer-support intake should add a signed intake token that can create, upload, and finalize a recording without granting broad recording access; do not expose the existing owner-scoped upload endpoints directly to anonymous users.
 
 ## Data model
 

package/corpus/core/docs/content/template-dispatch-developers.mdx

@@ -56,7 +56,7 @@ Server plugins register each connected channel's webhook (Slack, Microsoft Teams
 
 ```bash
 npx @agent-native/core@latest create my-platform
-# pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
+# Dispatch is included automatically. Deselect Chat for Dispatch only, or select domain apps to scaffold alongside it
 ```
 
 If you prefer to name the template directly instead of using the picker:

package/corpus/core/docs/content/template-dispatch.mdx

@@ -121,7 +121,7 @@ Live demo: [dispatch.agent-native.com](https://dispatch.agent-native.com).
 
 ```bash
 npx @agent-native/core@latest create my-platform
-# pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
+# Dispatch is included automatically. Deselect Chat for Dispatch only, or select domain apps to scaffold alongside it
 ```
 
 Dispatch is almost always scaffolded into a workspace alongside the apps it coordinates — a control plane with nothing to coordinate is just an empty inbox. See [Getting started](/docs/getting-started) for installing dependencies, running the dev server, and creating your first account.

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.129.1",
+  "version": "0.130.0",
   "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/action-ui.ts

@@ -3,6 +3,7 @@ export const ACTION_CHAT_UI_DATA_CHART_RENDERER = "core.data-chart";
 export const ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER = "core.data-insights";
 export const ACTION_CHAT_UI_DATA_WIDGET_RENDERER = "core.data-widget";
 export const ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER = "core.inline-extension";
+export const ACTION_CHAT_UI_WORKSPACE_FILE_RENDERER = "core.workspace-file";
 
 export interface ActionChatUIConfig {
   /**

package/corpus/core/src/action.ts

@@ -176,7 +176,11 @@ export function isAgentActionStopError(
 
 /** HTTP exposure config for an action. */
 export interface ActionHttpConfig {
-  /** HTTP method. Default: "POST". Use "GET" for read-only actions. */
+  /**
+   * Method required from direct HTTP callers. Default: "POST". Use "GET" for
+   * read-only actions. Browser action clients use the framework's frontend
+   * mutation transport and do not need to repeat this method.
+   */
   method?: "GET" | "POST" | "PUT" | "DELETE";
   /** Override route path under /_agent-native/actions/. Default: action filename. */
   path?: string;

package/corpus/core/src/agent/engine/ai-sdk-engine.ts

@@ -498,22 +498,32 @@ class AISDKEngine implements AgentEngine {
       yield bufferedStop ?? { type: "stop", reason: "end_turn" };
     } catch (err: any) {
       const timedOut = firstEventAbort.didTimeout();
+      // AI SDK wraps exhausted retries in RetryError and keeps the final
+      // APICallError on `lastError`. Read classification fields from that
+      // provider error so the retry wrapper does not erase transport status.
+      const providerError =
+        err?.lastError instanceof Error ? err.lastError : err;
       // Surface structured fields from AI SDK's APICallError so
       // isRetryableError can check statusCode/providerRetryable directly
       // rather than keyword-matching the message string.
       const statusCode: number | undefined =
-        typeof err?.statusCode === "number" ? err.statusCode : undefined;
-      const rawMessage: string = err?.message ?? String(err);
+        typeof providerError?.statusCode === "number"
+          ? providerError.statusCode
+          : undefined;
+      const rawMessage: string =
+        providerError?.message ?? String(providerError);
       // Classify on the bare message — the recorded `errorMessage` carries the
       // cause chain, which is where the real transport failure lives.
       const errorMessage = describeErrorWithCauses(err);
+      const normalizedRawMessage = rawMessage.trim().toLowerCase();
       const isConnectionError =
         !timedOut &&
         statusCode === undefined &&
-        rawMessage.trim().toLowerCase() === "connection error.";
+        (normalizedRawMessage === "connection error." ||
+          normalizedRawMessage.startsWith("cannot connect to api:"));
       const providerRetryable: boolean | undefined =
-        typeof err?.isRetryable === "boolean"
-          ? err.isRetryable
+        typeof providerError?.isRetryable === "boolean"
+          ? providerError.isRetryable
           : isConnectionError || timedOut
             ? true
             : undefined;

package/corpus/core/src/agent/harness/runner.ts

@@ -157,6 +157,11 @@ export function startAgentHarnessRun(
     {
       ...(opts.runOptions ?? {}),
       turnId: opts.turnId ?? opts.runOptions?.turnId,
+      // A harness adapter (e.g. Claude Code, Codex) owns its own model
+      // selection internally and does not expose it here, so `model` is
+      // left for the caller to supply via `runOptions` if it knows one.
+      // `ownerEmail` is PII and is never passed as `userId`.
+      engineName: opts.runOptions?.engineName ?? opts.adapter.name,
     },
   );
 }

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

@@ -958,6 +958,7 @@ export interface ProductionAgentOptions {
     threadId: string | undefined;
     message: string;
     attachments?: AgentChatAttachment[];
+    queuedMessageId?: string;
   }) => void | Promise<void>;
   /**
    * Optional per-template request normalizer. Runs after owner resolution and
@@ -2021,6 +2022,21 @@ export interface AgentLoopUsage {
   cacheReadTokens: number;
   cacheWriteTokens: number;
   model: string;
+  /**
+   * True once the engine reported at least one real `usage` event for this
+   * run. The token fields above start at 0 and are only ever incremented —
+   * when this is not true, those zeros are placeholders for "never
+   * reported", not a measured empty usage, and callers must not treat them
+   * as real counts.
+   */
+  usageReported?: boolean;
+  /**
+   * Wall-clock epoch ms of the first non-heartbeat engine-stream event seen
+   * across this run (all retries/continuations). Undefined means no event
+   * ever arrived — e.g. the run was killed for silence before the model
+   * produced anything.
+   */
+  firstEngineEventAtMs?: number;
 }
 
 export interface AgentLoopToolCallSummary {
@@ -4230,6 +4246,7 @@ export async function runAgentLoop(opts: {
             if (event.type !== "gateway-heartbeat") {
               hasReceivedFirstEngineEvent = true;
               lastModelStreamProgressAt = Date.now();
+              usage.firstEngineEventAtMs ??= lastModelStreamProgressAt;
             }
             // In-loop processor seam (stream hook). Each chunk is offered to every
             // processor's `processOutputStream` before the loop handles it. A
@@ -4343,6 +4360,7 @@ export async function runAgentLoop(opts: {
               usage.outputTokens += eventUsage.outputTokens;
               usage.cacheReadTokens += eventUsage.cacheReadTokens;
               usage.cacheWriteTokens += eventUsage.cacheWriteTokens;
+              usage.usageReported = true;
               opts.onUsage?.(eventUsage);
             } else if (event.type === "stop") {
               terminalStopReason = event.reason;
@@ -5959,6 +5977,10 @@ export async function runAgentLoopWithMainChatInternalContinuations(
     usage.cacheReadTokens += next.cacheReadTokens;
     usage.cacheWriteTokens += next.cacheWriteTokens;
     usage.model = next.model;
+    if (next.usageReported) usage.usageReported = true;
+    // Keep the earliest attempt's first event — a later continuation
+    // attempt starting fresh must not overwrite genuine first-token timing.
+    usage.firstEngineEventAtMs ??= next.firstEngineEventAtMs;
   };
 
   const budgetStartedAt = opts.budgetStartedAt ?? Date.now();
@@ -7113,6 +7135,7 @@ export function createProductionAgentHandler(
       threadId,
       attachments,
       displayMessage,
+      queuedMessageId,
       internalContinuation,
       turnId: requestTurnId,
       model: requestModel,
@@ -8054,6 +8077,9 @@ export function createProductionAgentHandler(
         threadId,
         message: messageToPersist,
         attachments: requestAttachments,
+        ...(typeof queuedMessageId === "string" && queuedMessageId.trim()
+          ? { queuedMessageId: queuedMessageId.trim() }
+          : {}),
       });
     }
 
@@ -9024,6 +9050,13 @@ export function createProductionAgentHandler(
         dispatchMode: foregroundSelfChainEligible
           ? "foreground-self-chain"
           : "foreground",
+        // Resolved AFTER stored-model/experiment overrides — the same value
+        // actually sent to the engine, not the raw client-requested model.
+        // No userId here: `ownerEmail` is the only identity known at this
+        // scope and is PII (email), which the terminal event must not carry.
+        model: effectiveModel,
+        engineName: engine.name,
+        attemptCount: backgroundContinuationCount,
       },
     );
 

package/corpus/core/src/agent/run-loop-with-resume.ts

@@ -239,6 +239,11 @@ export async function runAgentLoopDirectWithSoftTimeout(
     usage.cacheReadTokens += next.cacheReadTokens;
     usage.cacheWriteTokens += next.cacheWriteTokens;
     usage.model = next.model;
+    // Without these, a retry that never got a usage report merges its zeros
+    // over an earlier attempt's real numbers, and telemetry reports an
+    // unmeasured run as a measured empty one.
+    if (next.usageReported) usage.usageReported = true;
+    usage.firstEngineEventAtMs ??= next.firstEngineEventAtMs;
   };
 
   const localTurnEvents: AgentChatEvent[] = [];