@agent-native/core 0.149.6 → 0.151.0

package/docs/content/cross-app-sso.mdx

@@ -35,6 +35,11 @@ cookie**. Each separately hosted app still creates and owns its own local
 session. Dispatch proves the user's identity at the app's front door, and the
 app then continues with its normal local auth and access checks.
 
+The packaged Desktop Canary is deliberately more explicit: it never intercepts
+anonymous app sign-in navigation. The user chooses workspace sign-in in Desktop
+Settings for the active registered app; ordinary app sign-in remains the
+default path when that action is not chosen or the flag is unavailable.
+
 For a product walkthrough, record this exact sequence: sign in once in
 Dispatch, open two other hosted apps, show that neither asks for credentials,
 then sign out of one app and show that the other app's session is independent.
@@ -140,7 +145,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
     "in": "query",
     "type": "string",
     "required": true,
-    "description": "App callback URL. Validated against a strict allowlist (`*.agent-native.com` or localhost by default)."
+    "description": "App callback URL. Canonical apps must match an exact registered app ID, origin, and callback path; localhost is allowed for development."
   },
   {
     "name": "state",
@@ -156,7 +161,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
   },
   {
     "status": "400",
-    "description": "`redirect_uri` failed allowlist validation (cross-origin, scheme-relative `//host`, or unlisted suffix)."
+    "description": "`app` and `redirect_uri` failed allowlist validation (mismatched app, cross-origin, scheme-relative `//host`, or unlisted host)."
   }
 ]}>
 
@@ -183,7 +188,7 @@ The flow is a standard authorize → signed-token → callback redirect, with em
 
 ### Opting in {#opt-in}
 
-An app participates **only** when this environment variable is set on its deployment:
+An app's ordinary web sign-in participates **only** when this environment variable is set on its deployment:
 
 ```bash
 AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
@@ -197,10 +202,10 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
 The whole model rests on a few deliberately small guarantees:
 
 - **Short-lived signed token.** The identity assertion is an `A2A_SECRET`-signed JWT with a **≤ 2-minute** expiry and `scope: "identity"`. It authorizes a single sign-in and cannot be replayed for long or repurposed for API/A2A access.
-- **Strict `redirect_uri` allowlist.** Dispatch only ever redirects to `*.agent-native.com` or localhost by default. Arbitrary, scheme-relative (`//host`), and cross-origin redirect targets are rejected, so the authority can't be turned into an open-redirect or token-exfiltration oracle.
+- **Strict app-bound `redirect_uri` allowlist.** Every canonical app ID maps to one exact production origin and callback path; localhost remains available for development. Unknown subdomains, mismatched app IDs, arbitrary paths, scheme-relative (`//host`), and cross-origin targets are rejected, so the authority can't become a token-exfiltration oracle.
 - **Email-only join from a verified token.** The _only_ thing that crosses the trust boundary is the verified email in a signed token. The app does not accept a user id, role, org membership, or any privileged state from the wire — it derives everything locally from the matched account.
 - **Additive-only identity writes.** Linking either reuses an existing same-email account untouched or inserts a new one. No update, rename, repoint, or delete of identity rows ever happens on this path.
-- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset the entire feature is inert.
+- **Off by default.** With `AGENT_NATIVE_IDENTITY_HUB_URL` unset, ordinary browser federation is inert. The separately gated packaged Desktop path is described below.
 
 <Callout id="doc-block-18qhl3m" tone="success">
 
@@ -265,6 +270,31 @@ The just-in-time link is a single decision keyed entirely on the verified email:
 
 </Diagram>
 
+## Packaged Desktop workspace {#desktop-workspace}
+
+The signed Agent Native Desktop SSO Canary uses this same federation flow as the
+ordinary sign-in front door for canonical first-party apps. A dedicated
+Electron partition holds the Dispatch authority session; each target app still
+mints its own local session, and Desktop transfers only that app's allowlisted
+session cookie into its isolated `persist:app-<id>` partition. Custom,
+user-added, and third-party apps are excluded.
+
+Dispatch registers the default-off `desktop.workspace-sso` rollout flag. The
+flag controls whether Desktop may begin the ceremony; it does not authorize a
+user or weaken nonce, signature, origin, callback, app-binding, cookie,
+revocation, or credential-custody checks. With the flag Off or unavailable,
+Desktop leaves ordinary per-app sign-in, sign-out, and Settings unchanged.
+Canonical hosted apps recognize the packaged Desktop request without requiring
+`AGENT_NATIVE_IDENTITY_HUB_URL` on every deployment; ordinary web browsers and
+self-hosted apps still require that explicit configuration.
+Stable Desktop builds do not initialize the broker until a later release is
+separately approved.
+The Canary user-agent marker is an availability hint, not remote attestation;
+the server cannot infer code signature from HTTP. No authentication or
+authorization decision trusts it. Supervised acceptance therefore binds the
+tested client through the signed artifact's exact commit, manifest, hashes, and
+notarization evidence.
+
 ## Self-hosting {#self-hosting}
 
 Any Dispatch deployment can serve as the identity hub — you are not limited to `dispatch.agent-native.com`. Set `AGENT_NATIVE_IDENTITY_HUB_URL` on each client app to point at your Dispatch instance:
@@ -275,7 +305,7 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
 
 **Redirect allowlist.** The hub (Dispatch) validates `redirect_uri` on the authorize endpoint before issuing a token. The allowlist is configured in `templates/dispatch/server/lib/identity-sso.ts`:
 
-- **Default:** `*.agent-native.com` and localhost only (the `DEFAULT_ALLOWED_HOST_SUFFIXES` constant).
+- **Default:** exact registered Agent Native app ID/origin pairs and localhost only (`CANONICAL_IDENTITY_SSO_APP_ORIGINS`).
 - **Extending it:** set the `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` environment variable on the Dispatch deployment with a comma-separated list of additional host suffixes:
 
   ```bash
@@ -283,11 +313,11 @@ AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
   IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
   ```
 
-  Each entry is normalized to a dot-prefixed suffix (`.yourcompany.com`), so a suffix check is both sufficient and the least footgun-prone — no per-app list to keep in sync. Entries that would match everything (empty or just `.`) are filtered out.
+  Each entry is normalized to a dot-prefixed suffix (`.yourcompany.com`). Entries that would match everything (empty or just `.`) are filtered out. The request must still provide a valid app ID and the exact `/_agent-native/identity/callback` path.
 
 - **Localhost** is always allowed for local development of client-side apps regardless of `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`.
 
-Without `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, a self-hosted Dispatch can only issue tokens to apps on `*.agent-native.com`. Set the env var on your Dispatch deployment to unlock other domains.
+Without `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES`, a self-hosted Dispatch can only issue tokens to the exact registered Agent Native app origins. Set the env var on your Dispatch deployment to unlock other domains.
 
 ## Canary rollout runbook {#canary-rollout}
 

package/docs/content/extensions.mdx

@@ -268,27 +268,27 @@ Everything from here through [Local File Extensions](#local-file-extensions) is
 
 Inside the iframe sandbox, every extension has these helpers on `window`:
 
-| Helper                                           | Purpose                                                   | Example                                                   |
-| ------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------- |
-| `appAction(name, params)`                        | Call any of the host template's actions, including writes | `appAction('list-emails', { view: 'inbox' })`             |
-| `appFetch(path, options)`                        | Call allowed framework endpoints under `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')` |
-| `dbQuery(sql, args)`                             | Read from SQL (auto-scoped to the user; never for writes) | `dbQuery('SELECT id, name FROM tools')`                   |
-| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions     | Prefer `appAction` for app data writes                    |
-| `extensionFetch(url, options)`                   | Hit external APIs through a secure proxy with secrets     | `extensionFetch('https://api.github.com/user')`           |
-| `extensionData.set(collection, id, data, opts?)` | Persist data per-extension (user / org scoping)           | `extensionData.set('notes', id, { text: '...' })`         |
-| `extensionData.list(collection, opts?)`          | List persisted items                                      | `extensionData.list('notes', { scope: 'all' })`           |
-| `extensionData.get(collection, id, opts?)`       | Get a single item                                         | `extensionData.get('notes', 'note-1')`                    |
-| `extensionData.remove(collection, id, opts?)`    | Delete a persisted item                                   | `extensionData.remove('notes', 'note-1')`                 |
-| `window.slotContext`                             | Read the page/chat context passed into this slot          | `window.slotContext?.contactEmail`                        |
-| `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state      | `agentNative.ui.output({ threshold })`                    |
-| `agentNative.chat.send(message, opts?)`          | Send a prompt or selected value back to the agent chat    | `agentNative.chat.send('Use Q2', { context: { q: 2 } })`  |
+| Helper                                           | Purpose                                                   | Example                                                                |
+| ------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `appAction(name, params)`                        | Call any of the host template's actions, including writes | `appAction('list-emails', { view: 'inbox' })`                          |
+| `appFetch(path, options)`                        | Call allowed framework endpoints under `/_agent-native/*` | `appFetch('/_agent-native/application-state/navigation')`              |
+| `dbQuery(sql, args)`                             | Read from SQL (auto-scoped to the user; never for writes) | `dbQuery('SELECT id, name FROM tools')`                                |
+| `dbExec(sql, args)`                              | Legacy trusted SQL writes for editor/admin extensions     | Prefer `appAction` for app data writes                                 |
+| `extensionFetch(url, options)`                   | Hit external APIs through a secure proxy with secrets     | `extensionFetch('https://api.github.com/user')`                        |
+| `extensionData.set(collection, id, data, opts?)` | Persist data per-extension (user / org scoping)           | `extensionData.set('notes', id, { text: '...' })`                      |
+| `extensionData.list(collection, opts?)`          | List persisted items                                      | `extensionData.list('notes', { scope: 'all' })`                        |
+| `extensionData.get(collection, id, opts?)`       | Get a single item                                         | `extensionData.get('notes', 'note-1')`                                 |
+| `extensionData.remove(collection, id, opts?)`    | Delete a persisted item                                   | `extensionData.remove('notes', 'note-1')`                              |
+| `window.slotContext`                             | Read the page/chat context passed into this slot          | `window.slotContext?.contactEmail`                                     |
+| `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state      | `agentNative.ui.output({ threshold })`                                 |
+| `agentNative.chat.send(message, opts?)`          | Send a prompt or selected value back to the agent chat    | `agentNative.chat.send('Use Q2', { submit: true, context: { q: 2 } })` |
 
 Three rules of thumb:
 
 - **Prefer `appAction` over raw SQL.** Actions are the template's official surface — they handle access control, scoping, and validation for you. `dbQuery` is read-only; `dbExec` remains for legacy trusted editor/admin extensions, but new app data writes should go through actions.
 - **Use `appAction` for template data.** Extension `appFetch` is limited to framework `/_agent-native/*` endpoints; template `/api/*` routes are blocked by the iframe bridge.
 - **Prefer `extensionData` over making new tables.** Each extension gets its own isolated key-value store. No schema, no migration. Set `{ scope: 'org' }` to share with the user's org, `'user'` (default) for private.
-- **Use `agentNative.ui.output` for inline control values the agent should read later.** It writes `inline-ui:<extensionId>:output` to application state; `agentNative.chat.send` is for visible submit/apply messages.
+- **Use `agentNative.ui.output` for inline control values the agent should read later.** It writes `inline-ui:<extensionId>:output` to application state; `agentNative.chat.send` is draft-only unless `{ submit: true }` is passed for a user-triggered submit/apply message. Never call it from polling, refresh, or error handlers.
 
 ```html
 <script>

package/docs/content/file-uploads.mdx

@@ -1,6 +1,6 @@
 ---
 title: "File Uploads"
-description: "Configure file upload storage — SQL fallback for dev, Builder.io or custom providers for production."
+description: "Configure durable file upload storage — Builder.io or custom object storage for production."
 ---
 
 # File Uploads
@@ -15,9 +15,9 @@ The provider resolution order is:
 
 1. **User-registered providers** — custom providers registered via `registerFileUploadProvider()`
 2. **Builder.io provider** — built-in, activates automatically when Builder.io is connected
-3. **SQL fallback** — stores files as base64 in the database (fine for dev, not for production)
+3. **No provider** — the upload is rejected and the chat renders a storage setup CTA; binary data is never persisted in SQL
 
-<Diagram id="doc-block-hq5uvx" title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup.">
+<Diagram id="doc-block-hq5uvx" title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. Without one, the upload fails closed so binary data is never persisted in SQL.">
 
 ```html
 <div class="diagram-upload">
@@ -47,8 +47,8 @@ The provider resolution order is:
     <div class="diagram-step">
       <span class="diagram-pill warn">3</span>
       <div class="diagram-node">
-        SQL fallback<br /><small class="diagram-muted"
-          >base64 in DB — dev only</small
+        No provider<br /><small class="diagram-muted"
+          >setup CTA — no binary persistence</small
         >
       </div>
     </div>
@@ -94,15 +94,13 @@ Dispatches to the first configured provider in resolution order. Check the activ
 
 </Endpoint>
 
-## Default: SQL Fallback {#sql-fallback}
+## Storage required for durable uploads {#storage-required}
 
-When no provider is configured, files are stored as base64 data in the SQL database via the resources system. This works out of the box for local development but is not recommended for production — large files bloat the database and there's no CDN.
-
-A one-time warning is logged when the fallback is used.
+When no provider is configured, `uploadFile()` returns `null` and the multipart route returns `503`. Chat attachments remain available only for the current request, the agent receives a storage setup hint, and the transcript stores a setup marker instead of the binary payload. This fail-closed behavior keeps SQL small and makes the missing configuration visible.
 
 ## Builder.io Hosting {#builder-hosting}
 
-When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Builder.io's free tier includes this managed storage. Files are served from a CDN with no configuration needed. This is the recommended production setup.
+When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Builder.io's free tier includes this managed storage. Files are served from a CDN with no configuration needed, and the durable URL is stored in the chat thread so later turns can reuse it. This is the recommended production setup.
 
 ## Custom Providers {#custom-providers}
 
@@ -159,7 +157,7 @@ interface FileUploadInput {
   data: Uint8Array | Buffer; // File contents
   filename?: string; // Original filename
   mimeType?: string; // MIME type, e.g. "image/png"
-  ownerEmail?: string; // For per-user scoping in fallback
+  ownerEmail?: string; // For request-scoped provider credentials
 }
 
 interface FileUploadResult {
@@ -183,7 +181,7 @@ const result = await uploadFile({
 if (result) {
   // Provider handled it — result.url is the public URL
 } else {
-  // No provider configured — handle SQL fallback yourself, or skip
+  // No provider configured — show the storage setup CTA, or skip
 }
 ```
 

package/docs/content/generative-ui.mdx

@@ -222,12 +222,17 @@ Generated UI can send a visible prompt or result back into the current app chat:
 `agentNative.chat.send(message, options)` is also available as
 `sendToAgentChat(message, options)`.
 
+For generated extensions, chat messages are draft-only unless `submit: true` is
+passed explicitly. Use that opt-in only from a user-triggered Apply or Submit
+action. Do not call either helper from polling, refresh, or error handlers; use
+`agentNative.ui.output` or application state for passive results.
+
 Options:
 
 | Option        | Default | Effect                                           |
 | ------------- | ------- | ------------------------------------------------ |
 | `context`     | none    | hidden context appended to the submitted message |
-| `submit`      | `true`  | `false` pre-fills/reviews instead of auto-submit |
+| `submit`      | `false` | `true` auto-submits; `false` pre-fills/reviews   |
 | `openSidebar` | `true`  | opens the agent sidebar when the message is sent |
 
 This is the same app chat bridge used by normal UI components, so generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.149.6",
+  "version": "0.151.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": {
@@ -414,7 +414,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.4",
-    "@agent-native/toolkit": "^0.13.9"
+    "@agent-native/toolkit": "^0.13.10"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/src/templates/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/src/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -168,10 +168,33 @@ Set `A2A_SECRET` (same value) on all apps that must verify each other's identity
 Each hosted `*.agent-native.com` app has its **own user store**, so "sign in once" is identity federation, not a shared cookie. **Dispatch is the identity authority.**
 
 - **Opt-in per app via one env var:** set `AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com` and the app shows a "Sign in with Agent-Native" option. **Unset = zero behavior change** — the whole path is dormant. Reversible at any time.
-- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Strict `redirect_uri` allowlist (`*.agent-native.com` + localhost). App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
+- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Canonical clients require an exact registered app ID, origin, and callback path; localhost remains available for development. App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
 - **Invariant (do not break):** identity rows are only ever **added** — never modified, renamed, or deleted. Enabling SSO logs users out, but they always log back into the **same email-matched account with data intact**. Email is the only thing that crosses the trust boundary; the app never trusts a user id, role, or org from the wire.
 - **Canary rollout:** deploy with the env unset everywhere (no-op) → set it on **one** app (mail) only → verify (logout → SSO → Dispatch → back to the same pre-existing account, data intact, direct logins still work) → expand app-by-app → rollback = unset the env on that app's deploy (instant, no data change).
 
+### Packaged Desktop workspace sign-in
+
+For canonical first-party hosted apps, the packaged Desktop SSO Canary may compose the same
+federation into one workspace sign-in. Dispatch owns the default-off
+`desktop.workspace-sso` availability flag; every app still owns its local
+session. The flag is never an auth or authorization boundary. Keep nonce,
+signature, exact origin/callback, authenticated-session, app-binding, cookie
+allowlist, revocation, and credential-custody checks unconditional. When the
+flag is Off or unreadable, Desktop must leave ordinary per-app sign-in, sign-out,
+and Settings unchanged. Never extend the broker to custom or third-party apps,
+and never expose cookies, identity tokens, or provider credentials through IPC.
+Canonical hosted apps recognize packaged Desktop requests without per-app
+identity-hub environment configuration. Ordinary browsers and self-hosted apps
+still require `AGENT_NATIVE_IDENTITY_HUB_URL`.
+Stable Desktop builds must not initialize the broker until a later release is
+separately approved.
+Treat the Canary user-agent marker only as an availability hint, never as
+remote attestation or an authentication boundary. Bind supervised acceptance
+to exact signed-artifact provenance.
+The Canary must not intercept anonymous app sign-in navigation. The user
+explicitly chooses workspace sign-in in Desktop Settings for the active
+registered app; ordinary app sign-in remains the default path.
+
 Full runbook + flow detail: [Cross-App SSO doc](/docs/cross-app-sso).
 
 ## Builder Browser Access

package/src/templates/workspace-core/.agents/skills/delegate-to-agent/SKILL.md

@@ -49,6 +49,34 @@ sendToAgentChat({
 });
 ```
 
+### Keep user text separate from injected context
+
+Treat the visible `message` as the user's request or the shortest clear
+description of an app-initiated operation. Put context the user did not type —
+IDs, URLs, filenames, current selection or screen state, serialized records,
+upload instructions, and bounded source excerpts — in the `context` field.
+`context` is model input carried through the agent turn; it is stripped from
+the rendered user message, so do not concatenate it into `message` with labels,
+blank-line sections, or `<context>` tags yourself.
+
+Use the related surface for each kind of supporting input:
+
+| Surface | Use for |
+| --- | --- |
+| `message` | User-authored intent or a concise app action description |
+| `context` | Derived metadata and bounded text needed to carry out that intent |
+| `setAgentChatContextItem` | Context staged for a later user-submitted prompt; keep it keyed so updates replace stale context |
+| `images`, `referenceImagePaths`, attachments | Binary or visual inputs; describe only the handling instructions in `context` |
+
+If an app builds a prompt from a form, selection, upload, or editor state, keep
+the visible message short and pass the assembled details as `context`. Preserve
+the user's actual freeform text in `message` when it is the request; do not
+restate it as metadata in `context` unless the agent needs a structured copy.
+
+This boundary applies to auto-submitted turns and prefills. A hidden context
+field is not a license to send unbounded records or secrets: cap excerpts,
+prefer stable IDs and URLs, and use an action or resource lookup for full data.
+
 **From the UI, in the background:**
 
 ```ts

package/src/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -129,8 +129,12 @@ Extensions have full access to app data via helpers injected into the iframe
   in chat, record passive control/selection output at
   `inline-ui:<extensionId>:output` in application state so the agent can read it
   later with `readAppState`.
-- `agentNative.chat.send(message, opts?)` — send a visible prompt or selected
-  value back into the current agent chat.
+- `agentNative.chat.send(message, opts?)` - send a visible prompt or selected
+  value back into the current agent chat. The extension bridge keeps messages
+  draft-only unless `opts.submit === true`; pass `{ submit: true }` only from a
+  user-triggered Apply or Submit action. Never call it from polling, refresh, or
+  error handlers; use application state or `agentNative.ui.output` for passive
+  results.
 
 For transient inline generative UI, `extensionData` is host-browser
 `localStorage`: the agent cannot read it, it does not sync across devices, it

package/src/templates/workspace-core/.agents/skills/extensions/references/api.md

@@ -137,7 +137,7 @@ await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
 | `extensionData.get(collection, id, opts?)`       | Get a single item by id                                  | `extensionData.get('todos', 'todo-1')`                                                                           |
 | `extensionData.remove(collection, id, opts?)`    | Delete an item                                           | `extensionData.remove('todos', 'todo-1')`                                                                        |
 | `agentNative.ui.output(value, opts?)`            | Record passive inline UI output in application state     | `agentNative.ui.output({ threshold })`                                                                           |
-| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { context: { q: 2 } })`                                                         |
+| `agentNative.chat.send(message, opts?)`          | Send a visible prompt or selected value back to chat     | `agentNative.chat.send('Use Q2', { submit: true, context: { q: 2 } })`                                           |
 
 ## Persisting Custom Data
 

package/src/templates/workspace-core/.agents/skills/generative-ui/SKILL.md

@@ -76,7 +76,9 @@ The stored payload includes `value`, `updatedAt`, `extensionId`, and
 
 Use `agentNative.chat.send(message, opts?)` or `sendToAgentChat(message, opts?)`
 for a visible Apply/Submit button that should send a prompt or selected value
-into the chat.
+into the chat. Pass `{ submit: true }` explicitly for that user-triggered
+action; extension messages are draft-only otherwise. Never call these helpers
+from polling, refresh, or error handlers.
 
 ## App Data And State