@agent-native/core 0.122.4 → 0.123.1

package/corpus/core/docs/content/toolkit-editors-canvases.mdx

@@ -8,15 +8,39 @@ description: "Choose reusable editor and canvas surfaces without confusing Core
 Editors and canvases are related product surfaces, not one flagship feature.
 Choose the smallest reusable layer that matches the interaction your app owns.
 
+<WireframeBlock id="doc-block-toolkit-editors-canvases">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;padding:24px;display:flex;flex-direction:column;gap:14px'><div class='wf-card' style='display:flex;align-items:center;gap:6px;padding:8px 10px'><strong style='font-style:italic;width:22px;text-align:center'>I</strong><strong style='width:22px;text-align:center'>B</strong><span style='width:1px;height:16px;background:var(--wf-line)'></span><span class='wf-pill'>H1</span><span class='wf-pill'>H2</span><span style='width:1px;height:16px;background:var(--wf-line)'></span><span data-icon='mail'></span></div><main class='wf-card' style='display:flex;flex-direction:column;gap:10px;flex:1'><div style='display:flex;align-items:center;gap:8px'><span data-icon='dots'></span><h2 style='margin:0'>Q3 rollout plan</h2></div><div style='height:11px;width:92%;background:var(--wf-line);border-radius:4px'></div><div style='height:11px;width:78%;background:var(--wf-line);border-radius:4px'></div><div style='display:flex;align-items:center;gap:8px'><span data-icon='dots'></span><div class='wf-box' style='flex:1'>/&nbsp;&nbsp;<span class='wf-muted'>image, table, code block...</span></div></div><div style='height:11px;width:88%;background:var(--wf-line);border-radius:4px'></div></main></div>"
+    }
+  />
+</WireframeBlock>
+
 ## Ownership today
 
 | Surface             | Current owner and maturity                     | Use it when                                                                                                      |
 | ------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| Rich editor         | Toolkit, with Core compatibility re-exports    | You need portable rich editing, markdown, slash commands, images, drag handles, or collaboration reconciliation. |
+| Rich editor         | Toolkit-owned                                  | You need portable rich editing, markdown, slash commands, images, drag handles, or collaboration reconciliation. |
 | Blocks              | Core in this phase                             | You need registered, structured blocks and their runtime contract.                                               |
 | Design              | Template pattern plus reusable `design-tweaks` | You are building a Design-like workflow and can own its domain behavior.                                         |
 | Canvas presentation | Toolkit or app composition                     | You need reusable UI around an app-specific canvas model.                                                        |
 
+## Pieces {#pieces}
+
+| Piece                                                               | Purpose                                                                                                                                                    |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<SharedRichEditor>`                                                | The configurable rich editor: markdown in/out, optional Yjs collaboration, extension toggles. Renders its own bubble toolbar, slash menu, and drag handle. |
+| `<RichMarkdownEditor>`                                              | Backwards-compatible alias for `<SharedRichEditor>`.                                                                                                       |
+| `createSharedEditorExtensions()`                                    | The framework Tiptap schema and markdown dialects, for a fully custom editor shell.                                                                        |
+| `<SlashCommandMenu>` / `createImageSlashCommand()`                  | The shared slash-command UI and its image-insert command.                                                                                                  |
+| `<BubbleToolbar>` / `buildDefaultBubbleItems()`                     | The shared selection toolbar for marks, links, and custom inline actions.                                                                                  |
+| `<SharedImage>` / `createImageExtension()` / `pickAndInsertImage()` | Image node, extension factory, and upload-and-insert helper.                                                                                               |
+| `createCodeBlockNode()`                                             | Code block node with a language picker (`DEFAULT_CODE_LANGUAGES`).                                                                                         |
+| `<DragHandle>`                                                      | Per-block drag handle and reorder behavior.                                                                                                                |
+| `createRegistryBlockNode()` / `<RegistryBlockNodeView>`             | Registry-backed block nodes rendered inside the rich editor.                                                                                               |
+| `useCollabReconcile()`                                              | Binds a Yjs doc to markdown as the saved state.                                                                                                            |
+
 ## Choose deliberately
 
 Import the portable editor surface from `@agent-native/toolkit/editor`:
@@ -29,10 +53,44 @@ import {
 } from "@agent-native/toolkit/editor";
 ```
 
-Existing imports from `@agent-native/core/client` and
-`@agent-native/core/client/editor` continue to work as compatibility
-re-exports. Keep app-specific schemas, commands, persistence, upload actions,
-and registry adapters in your app or Core as appropriate.
+`<SharedRichEditor>` already wires the bubble toolbar, slash menu, and drag
+handle for you, so most apps only need it directly:
+
+```tsx
+import { SharedRichEditor } from "@agent-native/toolkit/editor";
+
+<SharedRichEditor
+  value={markdown}
+  onChange={setMarkdown}
+  placeholder="Write notes..."
+  features={{ tables: true, tasks: true, link: true }}
+/>;
+```
+
+Building a fully custom Tiptap surface instead of `<SharedRichEditor>`? Start
+from the shared schema and add only the pieces you need:
+
+```tsx
+import { useEditor, EditorContent } from "@tiptap/react";
+import { createSharedEditorExtensions } from "@agent-native/toolkit/editor";
+
+const editor = useEditor({
+  extensions: createSharedEditorExtensions({ features: { tables: true } }),
+});
+
+<EditorContent editor={editor} />;
+```
+
+The old `@agent-native/core/client` and `@agent-native/core/client/editor`
+import paths are deprecated tombstones, not compatibility re-exports:
+importing from them throws an actionable error naming
+`@agent-native/toolkit/editor` as the replacement (`RegistryBlockDataProvider`
+moved to `@agent-native/core/blocks`, `uploadEditorImage` to
+`@agent-native/core/client/uploads`). Run
+`npx @agent-native/core@latest upgrade --codemods` to rewrite old imports — see
+[Package Lifecycle](/docs/package-lifecycle#migration-manifests-and-tombstones).
+Keep app-specific schemas, commands, persistence, upload actions, and registry
+adapters in your app or Core as appropriate.
 
 Design is not a drop-in replacement for an editor or general canvas. The
 [Design template](/docs/template-design) demonstrates a complete product
@@ -47,9 +105,13 @@ which package currently owns the implementation. Register and render blocks
 through the Core contract so the agent and UI share the same structured
 vocabulary.
 
-## Related docs
+## What's next
 
-- [Toolkit overview](/docs/agent-native-toolkit) — the full catalog and ownership boundary.
-- [Component API](/docs/components) — public React exports and rich-editor compatibility details.
-- [Real-time collaboration](/docs/real-time-collaboration) — presence and collaborative editing foundations.
-- [Design template](/docs/template-design) — the Design product pattern.
+- [**Toolkit overview**](/docs/agent-native-toolkit) — the full catalog and ownership boundary.
+- [**Component API**](/docs/components) — the generated reference for every
+  public React export, including editor components.
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — presence and
+  collaborative editing foundations `useCollabReconcile()` builds on.
+- [**Design Template**](/docs/template-design) — the Design product pattern.
+- [**Package Lifecycle**](/docs/package-lifecycle) — deprecated import paths,
+  migration manifests, and the `upgrade --codemods` rewrite.

package/corpus/core/docs/content/toolkit-resources.mdx

@@ -33,6 +33,22 @@ for repo-backed content.
 
 ## Usage {#usage}
 
+Mount the complete panel when you want the whole browser/editor surface with
+no assembly required:
+
+```tsx
+import { ResourcesPanel } from "@agent-native/core/client/resources";
+
+<ResourcesPanel scope="personal" resourceFilter="files" />;
+```
+
+`showMcpServers`, `showOnlyRequestedScope`, `resourceTreeVariant`, and
+`mcpIntegrations` let an app hide the virtual MCP folder, lock the panel to one
+scope, render special collections as cards, or add app-owned remote MCP
+entries — all props are optional.
+
+Compose the tree and editor primitives yourself for custom chrome:
+
 ```tsx
 import {
   ResourceEditor,

package/corpus/core/docs/content/toolkit-settings.mdx

@@ -42,12 +42,12 @@ Every app should expose `/settings`. App-specific tabs can sit beside framework
 tabs; framework tabs should not be hidden in a second settings universe.
 
 ```tsx
+import { LanguagePicker } from "@agent-native/core/client/i18n";
 import {
-  LanguagePicker,
-} from "@agent-native/core/client/i18n"import {
   SettingsTabsPage,
   useAgentSettingsTabs,
-} from "@agent-native/core/client/settings"
+} from "@agent-native/core/client/settings";
+
 export default function SettingsRoute() {
   const agentSettingsTabs = useAgentSettingsTabs();
   return (

package/corpus/core/docs/content/toolkit-sharing.mdx

@@ -64,13 +64,11 @@ registerShareableResource({
 Render the standard controls where users decide access:
 
 ```tsx
-import {
-  ShareButton,
-} from "@agent-native/core/client/sharing"import {
-  VisibilityBadge,
-} from "@agent-native/toolkit/sharing"
-<VisibilityBadge visibility={dashboard.visibility} />
-<ShareButton resourceType="dashboard" resourceId={dashboard.id} />
+import { ShareButton } from "@agent-native/core/client/sharing";
+import { VisibilityBadge } from "@agent-native/toolkit/sharing";
+
+<VisibilityBadge visibility={dashboard.visibility} />;
+<ShareButton resourceType="dashboard" resourceId={dashboard.id} />;
 ```
 
 ## UX Standard {#ux-standard}

package/corpus/core/docs/content/using-your-agent.mdx

@@ -63,11 +63,22 @@ There's a simple through-line. The agent **sees** what you're looking at, you **
 
 </Diagram>
 
+This is what it looks like in practice: your app on one side, the agent docked next to it on the other, seeing the same screen you do.
+
+<WireframeBlock id="doc-block-usingagent1">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='min-height:520px;box-sizing:border-box;display:grid;grid-template-columns:1fr 300px;gap:16px;padding:24px'><main class='wf-card' style='display:flex;flex-direction:column;gap:10px'><div style='display:flex;align-items:center;gap:10px'><strong>Inbox</strong><span class='wf-pill'>12 unread</span></div><div class='wf-box'>Design review notes<br/><span class='wf-muted'>Ada Lovelace &middot; 9:14 AM</span></div><div class='wf-box' style='border-color:var(--wf-accent)'>Q3 renewal — action needed<br/><span class='wf-muted'>Selected &middot; 10:02 AM</span></div><div class='wf-box'>Weekly signups digest<br/><span class='wf-muted'>Automations &middot; 8:00 AM</span></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Agent</strong><div class='wf-box' style='align-self:flex-end;max-width:85%'>Summarize this and draft a reply. <span class='wf-pill'>@analytics</span></div><div class='wf-box' style='max-width:90%;background:var(--wf-accent-soft)'>Ada wants to move the renewal call. Draft below — send it?</div><div style='flex:1'></div><div class='wf-card' style='padding:10px;display:flex;align-items:center;gap:8px'><span class='wf-muted' style='flex:1'>Message the agent...</span><button>Voice</button></div></aside></div>"
+    }
+  />
+</WireframeBlock>
+
 ## It sees what you're looking at {#it-sees}
 
 The agent isn't blind to your screen. Open an email and it knows which thread. Select a chart and it knows which chart. Highlight a paragraph and it can act on just that range. That shared awareness is what lets you say "reply to this" or "summarize the selection" without spelling out the context every time.
 
-This works because the current navigation and selection live in `application_state` SQL, which the agent reads as part of its context. The agent can also drive that same state back — opening a view, selecting a row — so you watch it work in the real UI rather than in a transcript.
+This works because the app quietly keeps track of what view you're on and what you've selected, and shares that with the agent as part of its context. The agent can also drive that same state back — opening a view, selecting a row — so you watch it work in the real UI rather than in a transcript.
 
 <Callout id="doc-block-wljfsx" tone="info">
 
@@ -83,9 +94,18 @@ Most of the time you steer the agent by typing into the chat. Two things make th
 
 **Voice.** The composer has a microphone. Dictate a request instead of typing it, with provider options ranging from Builder's hosted transcription to bring-your-own-key to a browser fallback.
 
+A few examples of what that looks like in practice:
+
+| Type or say this                       | What happens                                                         |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| "Summarize this" (with a row selected) | Acts on exactly what you have open or highlighted — no re-explaining |
+| "@analytics pull last week's signups"  | Pulls in a specialist agent's answer before continuing your request  |
+| Click the mic and talk                 | Your words become the prompt — no typing needed                      |
+| "Reply to this and CC Ada"             | Drafts using the context it already has from what you're looking at  |
+
 ## You embed it {#you-embed-it}
 
-The agent isn't a separate app you tab over to. It ships as a handful of React components — a sidebar, a raw panel, and a `sendToAgentChat()` call — that you drop into any app. Render `<AgentSidebar>` to give every screen a toggleable agent, or wire a button to hand a specific task off to the chat instead of running a one-shot LLM call.
+The agent isn't a separate app you tab over to. Wherever you see a chat panel in an agent-native app, it can be docked next to any screen — toggle it open, and it's right there next to whatever you're working on. App builders can also wire a button to hand a specific task straight to the agent instead of building a one-off "AI" feature for it. If you're building the app rather than using it, see [Drop-in Agent](/docs/drop-in-agent) for the components that make this work.
 
 ## You can go UI-light {#ui-light}
 
@@ -101,5 +121,8 @@ When you and the agent are working on the same document, you don't take turns. W
 - [**Agent Mentions**](/docs/agent-mentions) — direct it with `@`-mentions
 - [**Voice Input**](/docs/voice-input) — direct it by speaking
 - [**Drop-in Agent**](/docs/drop-in-agent) — embed it in any React app
+- [**Native Chat UI**](/docs/native-chat-ui) — ask for a chart or table and get a real, interactive one in the reply
+- [**Generative UI**](/docs/generative-ui) — ask for sliders, a calculator, or a picker and the agent builds it inline
 - [**Automation-First Apps**](/docs/pure-agent-apps) — use no-browser apps for jobs, queues, scripts, and external agents
 - [**Real-Time Collaboration**](/docs/real-time-collaboration) — co-edit the same document together
+- [**Component API**](/docs/components) — the full building-block reference, for developers embedding the agent

package/corpus/core/docs/content/voice-input.mdx

@@ -77,7 +77,7 @@ The user sets their own key via the agent sidebar settings UI. It's stored as a
 
 ### Shared (for internal tools)
 
-Set `GEMINI_API_KEY`, `GROQ_API_KEY`, or `OPENAI_API_KEY` as an environment variable or in the `settings` table. Every user's transcription hits the shared key.
+Set `GEMINI_API_KEY`, `GROQ_API_KEY`, or `OPENAI_API_KEY` as an environment variable, or have a workspace admin add it in Settings → API Keys (stored as a shared, encrypted workspace secret). Every user's transcription hits the shared key.
 
 <Callout id="doc-block-1jgl027" tone="info">
 
@@ -85,6 +85,16 @@ Set `GEMINI_API_KEY`, `GROQ_API_KEY`, or `OPENAI_API_KEY` as an environment vari
 
 </Callout>
 
+## Realtime speech mode {#realtime-speech-mode}
+
+Beyond one-shot dictation, the composer also offers a live, hands-free conversation mode. When the mic opens, a popover lets you choose **Realtime speech** or **Editable dictation**. Realtime speech uses a connected Builder account automatically (same as dictation), or an `OPENAI_API_KEY` if Builder isn't connected — connects the browser to `gpt-realtime-2.1` over WebRTC. The chat collapses into a speech orb in the bottom-end corner; click the orb to show or hide chat without ending the conversation. The orb stays visible above the chat even if the chat opens automatically, and its compact waveform reacts to your voice and the assistant's voice.
+
+The speech model uses the same authenticated Agent Native tools as chat, so it can navigate the app and call actions while it talks. Approval-gated actions remain paused until you approve them. Only completed user and assistant text turns are appended to the original chat thread. Ending voice mode opens that chat so you can continue over text; audio and interim transcript fragments are never stored. A realtime session lasts at most 60 minutes.
+
+## For developers {#for-developers}
+
+The rest of this page is the transcription route's request/response contract and how to customize or replace it — useful if you're building a custom input surface or an on-prem provider, not required to use voice input day to day.
+
 ## The route {#route}
 
 <Endpoint id="doc-block-16oybs0" title="Voice transcription route" method="POST" path="/_agent-native/transcribe-voice" summary="Transcribe a recorded audio clip into prompt text" auth="Active session (Better Auth cookie). Same-origin only." params={[
@@ -123,12 +133,6 @@ The composer POSTs the recorded clip here; the route resolves a provider and ret
 
 You don't need to call this directly — the composer does. If you're building a custom input surface, first reuse the shared composer/voice client pieces from `@agent-native/core/client`. Treat this route as the low-level transport boundary for custom helpers that need to send multipart audio.
 
-## Realtime speech mode {#realtime-speech-mode}
-
-Beyond one-shot dictation, the composer also offers a live, hands-free conversation mode. When the mic opens, a popover lets you choose **Realtime speech** or **Editable dictation**. Realtime speech requires a user-scoped `OPENAI_API_KEY` and connects the browser to `gpt-realtime-2.1` over WebRTC. The chat collapses into a speech orb in the bottom-end corner; click the orb to show or hide chat without ending the conversation. The orb stays visible above the chat even if the chat opens automatically, and its compact waveform reacts to your voice and the assistant's voice.
-
-The speech model uses the same authenticated Agent Native tools as chat, so it can navigate the app and call actions while it talks. Approval-gated actions remain paused until you approve them. Only completed user and assistant text turns are appended to the original chat thread. Ending voice mode opens that chat so you can continue over text; audio and interim transcript fragments are never stored. A realtime session lasts at most 60 minutes.
-
 ## Customizing the provider {#customizing}
 
 The provider field is a plain application-state key, so the agent can change it on request (`"use the browser speech recognizer instead"`). If you're building a template with different requirements — say, an on-prem Whisper deployment — swap the route handler by registering your own `transcribe-voice` route before the framework mounts the default.

package/corpus/core/docs/content/what-is-agent-native.mdx

@@ -400,3 +400,4 @@ One action, many surfaces: the agent calls it as a tool, the UI calls it as a ty
 - [**Dispatch**](/docs/dispatch) — the workspace control plane: secrets vault, Slack/email inbox, cross-app delegation
 - [**Extensions**](/docs/extensions) — sandboxed mini-apps the agent creates instantly without code changes
 - [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>` into any React app
+- [**FAQ**](/docs/faq) — quick answers on cost, hosting, models, and templates

package/corpus/core/docs/content/workspace-connections.mdx

@@ -5,6 +5,12 @@ description: "Shared provider metadata, grants, and credential refs for connect-
 
 # Workspace Connections
 
+<Callout tone="info">
+
+**Developer page.** This page is for developers wiring an app to a shared, reusable provider connection. For the end-user catalog of connectable providers, see [Integrations](/docs/integrations).
+
+</Callout>
+
 Workspace connections are the framework primitive for reusable integration metadata. They make "connect once, grant apps, reuse credentials" possible without pretending every provider is fully generic.
 
 ## Quickstart {#quickstart}
@@ -255,17 +261,21 @@ if (workspaceConnectionProviderSupports("slack", "messages")) {
 
 The initial provider ids are:
 
-| Provider       | Capabilities                   | Common uses                    |
-| -------------- | ------------------------------ | ------------------------------ |
-| `slack`        | search, import, messages       | brain, dispatch, analytics     |
-| `github`       | search, import, code, docs     | brain, analytics, dispatch     |
-| `notion`       | search, import, docs           | brain, content, dispatch       |
-| `gmail`        | search, import, messages       | mail, brain, dispatch          |
-| `google_drive` | search, import, docs           | brain, content, slides         |
-| `hubspot`      | search, import, crm            | analytics, brain, mail         |
-| `granola`      | search, import, meetings, docs | brain, calendar, dispatch      |
-| `clips`        | search, import, meetings       | brain, clips                   |
-| `generic`      | search, import, docs           | custom webhooks and file drops |
+| Provider       | Capabilities                   | Common uses                                 |
+| -------------- | ------------------------------ | ------------------------------------------- |
+| `slack`        | search, import, messages       | brain, dispatch, analytics                  |
+| `github`       | search, import, code, docs     | brain, analytics, dispatch                  |
+| `figma`        | search, import, docs           | brain, design, slides, content              |
+| `notion`       | search, import, docs           | brain, content, dispatch                    |
+| `gmail`        | search, import, messages       | mail, brain, dispatch                       |
+| `google_drive` | search, import, docs           | brain, content, slides, dispatch, analytics |
+| `hubspot`      | search, import, crm            | analytics, brain, crm, mail, dispatch       |
+| `salesforce`   | search, import, crm            | analytics, brain, crm, dispatch             |
+| `jira`         | search, import, code, docs     | analytics, brain, dispatch (Jira Cloud)     |
+| `sentry`       | search, import, docs           | analytics, brain, dispatch                  |
+| `granola`      | search, import, meetings, docs | brain, calendar, dispatch                   |
+| `clips`        | search, import, meetings       | brain, clips                                |
+| `generic`      | search, import, docs           | custom webhooks and file drops              |
 
 Credential keys are names only, such as `SLACK_BOT_TOKEN` or `GITHUB_TOKEN`. Provider metadata must never include actual credential values.
 

package/corpus/core/docs/content/workspace-management.mdx

@@ -7,7 +7,7 @@ description: "Branching, CODEOWNERS, PR review, and how Dispatch handles runtime
 
 <Callout tone="info">
 
-**Which workspace doc?** This page covers **governance** — who reviews, approves, and owns what across many apps in one repo. For the agent customization layer (Agent Resources: `AGENTS.md`, memory, skills, custom agents) see [Agent Resources](/docs/agent-resources); for the deployment shape (one monorepo, many apps) see [Multi-App Workspaces](/docs/multi-app-workspace).
+**Developer page.** This page is for platform engineers setting up repo governance — branching, code review, CI. It covers **governance**: who reviews, approves, and owns what across many apps in one repo. For the agent customization layer (Agent Resources: `AGENTS.md`, memory, skills, custom agents) see [Agent Resources](/docs/agent-resources); for the deployment shape (one monorepo, many apps) see [Multi-App Workspaces](/docs/multi-app-workspace).
 
 </Callout>
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.122.4",
+  "version": "0.123.1",
   "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": {
@@ -341,13 +341,11 @@
     "@clack/prompts": "^1.4.0",
     "@codemirror/lang-sql": "^6.10.0",
     "@codemirror/theme-one-dark": "^6.1.3",
-    "@floating-ui/dom": "^1.7.6",
     "@libsql/client": "^0.15.0",
     "@modelcontextprotocol/ext-apps": "1.7.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "0.6.0",
     "@neondatabase/serverless": "^1.1.0",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
     "@radix-ui/react-popover": "catalog:",
     "@radix-ui/react-select": "catalog:",
     "@radix-ui/react-tooltip": "catalog:",

package/corpus/core/src/a2a/client.ts

@@ -277,10 +277,12 @@ export class A2AClient {
     throw lastError ?? new Error("No A2A endpoint candidates available");
   }
 
-  async getAgentCard(): Promise<AgentCard> {
+  async getAgentCard(options?: { timeoutMs?: number }): Promise<AgentCard> {
     const res = await ssrfSafeFetch(
       `${this.baseUrl}/.well-known/agent-card.json`,
-      {},
+      options?.timeoutMs
+        ? { signal: AbortSignal.timeout(options.timeoutMs) }
+        : {},
       { maxRedirects: 3, allowedPrivateOrigins: workspacePrivateOrigins() },
     );
     if (!res.ok) {

package/corpus/core/src/agent/action-warnings.ts

@@ -0,0 +1,103 @@
+/**
+ * Agent-visible warning channel.
+ *
+ * A risky operation deep inside an action's call stack (an org repoint, a
+ * second organization) has no way to reach the conversation: helpers like
+ * `setActiveOrgId(email, orgId, reason)` never receive the action's `ctx`, and
+ * `console.warn` reaches server logs nobody reads at decision time. That is how
+ * a roster migration repointed 21 accounts' active org, orphaned every vault
+ * credential synced under the previous one, and still reported success.
+ *
+ * `warnAgent()` writes onto the mutable per-run request context, which the agent
+ * loop already publishes across the action-invocation boundary. The loop drains
+ * it after each tool call and appends the warnings to that tool's result, so the
+ * model reads them in the same write that lands in the transcript and ledger.
+ *
+ * Storage is a module-private `WeakMap` keyed on the run object rather than a
+ * new `RequestRunContext` field: no edits to a type every surface depends on,
+ * and the per-run key gives the channel natural scoping (warnings from one run
+ * can never be suppressed by, or leak into, another).
+ */
+import {
+  getRequestRunContext,
+  type RequestRunContext,
+} from "../server/request-context.js";
+
+/**
+ * `critical` means the operation probably broke something the user must hear
+ * about now; `advisory` means worth mentioning, not worth alarming. Required so
+ * a caller cannot get a downgrade by omission.
+ */
+export type AgentWarningSeverity = "advisory" | "critical";
+
+export interface AgentWarning {
+  severity: AgentWarningSeverity;
+  /** Stable machine-readable class, e.g. `org-cross-org-repoint`. */
+  code: string;
+  /** One human sentence: what happened, the consequence, and the remedy. */
+  message: string;
+}
+
+const pendingWarnings = new WeakMap<RequestRunContext, AgentWarning[]>();
+
+function formatForConsole(warning: AgentWarning): string {
+  return `[agent-native][${warning.severity}:${warning.code}] ${warning.message}`;
+}
+
+/**
+ * Raise a warning for the agent to relay to the user. Safe to call from any
+ * depth inside an action; no `ctx` needed.
+ */
+export function warnAgent(warning: AgentWarning): void {
+  const run = getRequestRunContext();
+  if (!run) {
+    // No agent run to attach to (CLI, migration script, boot). A warning that
+    // reaches nobody is the exact failure this channel exists to fix, so the
+    // console stays the fallback home instead of the warning being dropped.
+    console.warn(formatForConsole(warning));
+    return;
+  }
+  const pending = pendingWarnings.get(run);
+  if (!pending) {
+    pendingWarnings.set(run, [warning]);
+    return;
+  }
+  // Dedupe only within what the next drain will emit: the same sentence twice in
+  // one tool result is noise, but the same warning from a later tool call is a
+  // second real operation the user still needs to hear about.
+  if (
+    pending.some(
+      (existing) =>
+        existing.code === warning.code && existing.message === warning.message,
+    )
+  ) {
+    return;
+  }
+  pending.push(warning);
+}
+
+/** Take and clear the warnings raised so far in the current run. */
+export function drainAgentWarnings(): AgentWarning[] {
+  const run = getRequestRunContext();
+  if (!run) return [];
+  const pending = pendingWarnings.get(run);
+  if (!pending || pending.length === 0) return [];
+  pendingWarnings.delete(run);
+  return pending;
+}
+
+/**
+ * Render drained warnings as tagged blocks for a tool result. Never called with
+ * an empty list by the loop, so an action that raises nothing leaves its result
+ * byte-identical.
+ */
+export function formatAgentWarningsForToolResult(
+  warnings: AgentWarning[],
+): string {
+  return warnings
+    .map(
+      (warning) =>
+        `<agent-warning severity="${warning.severity}" code="${warning.code}">\n${warning.message}\n</agent-warning>`,
+    )
+    .join("\n");
+}

package/corpus/core/src/agent/durable-background.ts

@@ -302,16 +302,53 @@ export function shouldUseBackgroundFunctionTimeoutForWorker(
 }
 
 export function backgroundRuntimeDiagnosticDetail(marker: unknown): string {
-  return [
+  const detail = [
     `markerExpected=${backgroundRunMarkerExpectsBackgroundRuntime(marker)}`,
     `runtimeDetected=${isInBackgroundFunctionRuntime()}`,
     `globalMarker=${(globalThis as Record<string, unknown>).__AGENT_NATIVE_BACKGROUND_RUNTIME__ === true}`,
     `lambdaNameEndsBackground=${typeof process.env.AWS_LAMBDA_FUNCTION_NAME === "string" && process.env.AWS_LAMBDA_FUNCTION_NAME.toLowerCase().endsWith("-background")}`,
     `forceEnv=${typeof process.env.AGENT_CHAT_FORCE_BACKGROUND_RUNTIME === "string" && process.env.AGENT_CHAT_FORCE_BACKGROUND_RUNTIME.trim().length > 0}`,
   ].join(" ");
+  reportMissingBackgroundFunctionOnce(marker, detail);
+  return detail;
 }
 
-function isFlagEnabled(): boolean {
+export const BACKGROUND_FUNCTION_UNREACHABLE_NOTICE_KEY =
+  "__AGENT_NATIVE_BACKGROUND_UNREACHABLE_NOTICE__";
+
+/**
+ * The foreground targeted the `-background` function's default url, yet this
+ * worker is NOT running in that function: the deploy is missing the artifact (or
+ * Netlify routed the url to the synchronous function). The turn still completes
+ * on the 40s-clamped path, so nothing else ever surfaces it — an app can lose
+ * the 15-min budget for its whole lifetime in silence (agent-native-plan did:
+ * zero background runs ever, every turn pinned to the ~60s wall). Announce it
+ * once per isolate; the same detail is already recorded on the run row by the
+ * caller, so this only adds the server-side signal a deploy owner can grep.
+ */
+function reportMissingBackgroundFunctionOnce(
+  marker: unknown,
+  detail: string,
+): void {
+  if (!backgroundRunMarkerExpectsBackgroundRuntime(marker)) return;
+  if (isInBackgroundFunctionRuntime()) return;
+  const scope = globalThis as Record<string, unknown>;
+  if (scope[BACKGROUND_FUNCTION_UNREACHABLE_NOTICE_KEY] === true) return;
+  scope[BACKGROUND_FUNCTION_UNREACHABLE_NOTICE_KEY] = true;
+  console.error(
+    `[agent-chat] durable background is enabled but the "${AGENT_BACKGROUND_FUNCTION_NAME}" ` +
+      "function is unreachable — this worker is running on the synchronous function " +
+      "with the 40s clamp instead of the 15-min budget. Check that the deploy emitted " +
+      `it (build log: "Emitted durable-background function"). ${detail}`,
+  );
+}
+
+/**
+ * Env flag parse, shared by the runtime gate and the deploy-time emit gates so
+ * they can never drift apart (they did: the workspace deploy copy defaulted ON
+ * while this one defaulted OFF).
+ */
+export function isDurableBackgroundFlagEnabled(): boolean {
   // Read the literal key (not `process.env[CONST]`) so guard:no-env-credentials
   // can statically verify it against the allowlisted `AGENT_*` prefix. Keep this
   // in sync with AGENT_CHAT_DURABLE_BACKGROUND_ENV.
@@ -337,7 +374,7 @@ function isFlagEnabled(): boolean {
   );
 }
 
-function isFlagExplicitlyDisabled(): boolean {
+export function isDurableBackgroundFlagExplicitlyDisabled(): boolean {
   const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
   if (raw == null) return false;
   const normalized = raw.trim().toLowerCase();
@@ -366,10 +403,10 @@ export function isAgentChatDurableBackgroundEnabled(options?: {
   // recreates the missing-background-function failure this gate is meant to
   // prevent.
   if (options?.appOptIn === false) return false;
-  const envOptIn = isFlagEnabled();
+  const envOptIn = isDurableBackgroundFlagEnabled();
   const workspaceAppOptIn =
     options?.appOptIn === true &&
-    !isFlagExplicitlyDisabled() &&
+    !isDurableBackgroundFlagExplicitlyDisabled() &&
     resolveWorkspaceBackgroundFunctionUrlPath() !== null;
   return (
     (envOptIn || workspaceAppOptIn) &&