@agent-native/core 0.106.2 → 0.107.0

package/corpus/core/docs/content/locales/zh-TW/mcp-protocol.mdx

@@ -232,6 +232,12 @@ Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `
 請使用這些引數呼叫 `ask_app_status`，直到任務進入終止狀態。Dispatch 應用程式自有的
 `ask_app` 使用相同的持久任務與狀態合約，並在提交與輪詢時都會檢查所選應用程式的授權。
 
+若有界的暫時狀態讀取無法使用，`ask_app_status` 可傳回
+`status: "unknown"`、`statusRead: "unavailable"`、`retryable: true`、原始的
+`app` 與 `taskId`，以及 `pollAfterMs` / `poll`。這表示狀態讀取無法使用，並不表示
+持久任務失敗。請以完全相同的 `app` 與 `taskId` 重試 `ask_app_status`；切勿為了復原而
+重新提交 `ask_app`，因為提交可能重複工作。永久性的驗證、找不到與通訊協定錯誤仍然是錯誤。
+
 ## 驗證 {#authentication}
 
 MCP 端點支援標準遠端 MCP OAuth 以及現有的不記名權杖後備：

package/corpus/core/docs/content/mcp-clients.mdx

@@ -7,6 +7,10 @@ description: "Connect your agent-native app to local MCP servers (claude-in-chro
 
 **This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Server](/docs/mcp-protocol) (which makes your app an MCP _server_). Note the dual use of "client" here: this page is about your app acting as an MCP client of _other_ servers — a different sense from an "MCP host" like Claude or Cursor connecting to your app (see [MCP Server](/docs/mcp-protocol) for that direction).
 
+**Looking for the provider list first?** See the [Integrations Directory](/docs/integrations)
+for the self-hosted catalog wall, connection modes, setup links, and current
+restricted-provider notes.
+
 | If you want to…                                              | Read                                     |
 | ------------------------------------------------------------ | ---------------------------------------- |
 | Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
@@ -272,7 +276,16 @@ export default {
 ```
 
 Preset ids are `context7`, `sentry`, `notion`, `semgrep`, `linear`,
-`atlassian`, `supabase`, `neon`, and `stripe`.
+`atlassian`, `supabase`, `neon`, `stripe`, `cloudflare`, `gitlab`, `figma`,
+`vercel`, `github`, `slack`, `asana`, `hubspot`, `intercom`, `monday`,
+`webflow`, `paypal`, `box`, `netlify`, and `zapier`.
+
+The directory distinguishes endpoints that support the framework's generic
+OAuth flow from providers that require a vendor-approved client or a
+pre-registered OAuth application. The latter stay visible for discovery and
+link to their official setup instructions, but do not show a misleading
+one-click connect button. Provider restrictions change over time, so verify
+the vendor setup note before enabling one in a production catalog.
 
 ### Atlassian / Jira
 
@@ -319,6 +332,43 @@ Adds and removes hot-reload into the running MCP manager — no process restart,
 
 HTTPS URLs are accepted everywhere; plain `http://` is only allowed for `localhost` during development. Optional auth goes in as a Bearer token that's sent via `Authorization: Bearer …` on every request. OAuth-only providers, including Atlassian Rovo MCP, require the provider's OAuth flow instead of a static header.
 
+### Use connected MCP and OAuth provider data in extensions
+
+Extensions run in a sandboxed iframe and never receive connector URLs, OAuth
+client secrets, access tokens, or refresh tokens. They can call the same
+request-scoped action surface as the host app through the injected helpers:
+
+```html
+<div
+  x-data="{ tools: [] }"
+  x-init="
+  agentNative.mcp.listTools().then(result => tools = result)
+"
+>
+  <template x-for="tool in tools" :key="tool.serverId + ':' + tool.name">
+    <p x-text="tool.title || tool.name"></p>
+  </template>
+</div>
+```
+
+To invoke a tool after inspecting its contract, use
+`agentNative.mcp.callTool(serverId, toolName, arguments)`. For regular OAuth
+provider connectors used by Analytics, Dispatch, Mail, Content, Calendar, and
+other templates, use `agentNative.providerApi.catalog(...)` and
+`agentNative.providerApi.docs(...)` to discover the granted provider API. Raw
+`provider-api-request` is intentionally host/agent-only: exposing arbitrary
+method/path requests to shared extensions would make an extension an
+authenticated write proxy. Extensions should use `agentNative.mcp.callTool(...)`
+or a purpose-built app action for bounded provider operations. The discovery
+helpers are also available under `agentNative.connectors.mcp` and
+`agentNative.connectors.providerApi`.
+
+Local-file extensions must explicitly allow `list-mcp-tools`,
+`call-mcp-tool`, and any explicitly supported provider action they use in
+`extension.json`.
+Database-backed extensions use the existing extension role and action gates.
+Never pass a raw bearer token or arbitrary provider URL from extension code.
+
 Under the hood these servers are persisted in the framework's `settings` table under the key `u:<email>:mcp-servers-remote` (Personal) or `o:<orgId>:mcp-servers-remote` (Team) and merged with `mcp.config.json` on startup.
 
 ### HTTP endpoints

package/corpus/core/docs/content/mcp-protocol.mdx

@@ -244,6 +244,14 @@ Call `ask_app_status` with those arguments until the task reaches a terminal
 state. Dispatch's app-owned `ask_app` uses the same durable task and status
 contract, with the selected-app grant checked on both submission and polling.
 
+If a bounded transient status read is unavailable, `ask_app_status` can return
+`status: "unknown"`, `statusRead: "unavailable"`, `retryable: true`, the
+original `app` and `taskId`, and `pollAfterMs` / `poll`. This means the status
+read is unavailable—not that the durable task failed. Retry `ask_app_status`
+with that exact `app` and `taskId`; never resubmit `ask_app` to recover, because
+submission can duplicate work. Permanent authentication, not-found, and
+protocol failures remain errors.
+
 ## Authentication {#authentication}
 
 The MCP endpoint supports standard remote MCP OAuth plus the existing bearer-token fallback:

package/corpus/core/docs/content/organizations-teams-permissions.mdx

@@ -0,0 +1,413 @@
+---
+title: "Organizations, Teams & Permissions"
+description: "A practical guide to organization context, team roles, resource sharing, RBAC, and the environment variables used by Agent Native apps."
+---
+
+# Organizations, Teams & Permissions
+
+If you are building an app for more than one person, start here. Agent Native
+has several scopes that are easy to conflate:
+
+| Scope            | What it identifies                                                   | Where it appears                                        |
+| ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------- |
+| **User**         | The signed-in person                                                 | `session.email`, `ctx.userEmail`                        |
+| **Organization** | The team or tenant the person is currently using                     | `session.orgId`, `session.orgRole`, `ctx.orgId`         |
+| **Resource**     | A document, dashboard, design, or other app row                      | `owner_email`, `org_id`, `visibility`, and share grants |
+| **Workspace**    | A deployment shape containing multiple apps and shared configuration | `AGENT_NATIVE_WORKSPACE`, shared `.env`, app base paths |
+
+An organization is the team boundary for application data. A workspace is a
+deployment and customization concept; it is not a replacement for an
+organization and it does not grant access to application rows by itself.
+
+## The access model in one minute
+
+The framework resolves a request in this order:
+
+1. Authentication identifies the user.
+2. The org module resolves the user's active organization and membership role.
+3. SQL and resource access helpers scope reads and writes to that identity.
+
+```text
+Better Auth session
+  -> active organization: orgId + orgRole
+  -> request context: userEmail + orgId
+  -> scoped SQL / resource access
+```
+
+The same context is used by the UI, actions, custom server routes, and the
+agent. Hiding a button in React is useful UX, but it is not authorization. The
+server-side action or access guard must enforce the rule.
+
+## Organizations and teams
+
+Every scaffold includes the framework's own `org/` module. It is backed by
+`organizations`, `org_members`, and `org_invitations`; it is not Better Auth's
+organization plugin. The built-in flow supports:
+
+- Creating an organization. The creator becomes the `owner`.
+- Inviting people as `member` or `admin` and accepting invitations.
+- Switching the active organization when a user belongs to more than one.
+- Joining by an allowed email domain when the organization enables that policy.
+- Renaming an organization, managing members, and managing cross-app A2A
+  settings from the team surface.
+
+The framework mounts the server surface under `/_agent-native/org/*`. The main
+routes are:
+
+| Route                                            | Purpose                                                      |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| `GET /_agent-native/org/me`                      | Active org, memberships, pending invites, and domain matches |
+| `POST /_agent-native/org`                        | Create an organization                                       |
+| `PATCH /_agent-native/org`                       | Rename the active organization                               |
+| `PUT /_agent-native/org/switch`                  | Switch the active organization                               |
+| `GET /_agent-native/org/members`                 | List members in the active organization                      |
+| `DELETE /_agent-native/org/members/:email`       | Remove a member                                              |
+| `PUT /_agent-native/org/members/:email/role`     | Change a member's role                                       |
+| `POST /_agent-native/org/invitations`            | Invite one or more people                                    |
+| `POST /_agent-native/org/invitations/:id/accept` | Accept an invitation                                         |
+| `POST /_agent-native/org/join-by-domain`         | Join an organization matched by email domain                 |
+| `PUT /_agent-native/org/domain`                  | Set or clear the allowed email domain                        |
+| `PUT /_agent-native/org/a2a-secret`              | Set or regenerate the active org's A2A secret                |
+
+Use the shared UI and hooks instead of recreating this flow in each app:
+
+```tsx
+import {
+  OrgSwitcher,
+  RequireActiveOrg,
+  TeamPage,
+  useOrgRole,
+} from "@agent-native/core/client/org-team";
+
+export function AppShell() {
+  return <OrgSwitcher />;
+}
+
+export function TeamSettings() {
+  return (
+    <RequireActiveOrg>
+      <TeamPage />
+    </RequireActiveOrg>
+  );
+}
+
+export function InviteButton() {
+  const { canInviteMembers } = useOrgRole();
+  return canInviteMembers ? <button>Invite members</button> : null;
+}
+```
+
+On the server, import the org helpers from `@agent-native/core/org-team`.
+`getOrgContext(event)` returns the resolved `{ email, orgId, orgName, role }`.
+For actions, the second `run` argument is the simpler path for the identity
+needed by most app code:
+
+```ts
+export default defineAction({
+  description: "Create a project in the active organization.",
+  schema: z.object({ name: z.string().min(1) }),
+  run: async ({ name }, ctx) => {
+    if (!ctx?.userEmail) throw new Error("Authentication required");
+
+    await db.insert(projects).values({
+      id: crypto.randomUUID(),
+      name,
+      ownerEmail: ctx.userEmail,
+      orgId: ctx.orgId,
+    });
+
+    return { ok: true };
+  },
+});
+```
+
+The active organization is selected from the user's memberships. For a user
+with several memberships, the framework honors the `active-org-id` user
+setting. If a signed-in user has no membership, the framework creates a
+personal organization by default. Set `AUTO_CREATE_DEFAULT_ORG=0` when an app
+must require an explicit invite or organization-creation step.
+
+## Organization roles (membership RBAC)
+
+Organization roles answer: **what may this person do to the team itself?**
+
+| Role     | Meaning                          | Typical capabilities                                                                                                                                                                                |
+| -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`  | Full control of the organization | Manage the organization, members, admins, domain policy, and org-level A2A settings                                                                                                                 |
+| `admin`  | Team administrator               | Invite/remove members and manage ordinary member roles; admins cannot change the owner's role, only the owner manages admin-to-admin transitions, and the shared client domain helper is owner-only |
+| `member` | Regular team member              | Use resources that the app shares with the organization; cannot manage membership                                                                                                                   |
+
+The shared role helpers are deliberately small and composable:
+
+```ts
+import {
+  canInviteOrgMembers,
+  canManageOrg,
+  canManageOrgDomain,
+  orgRoleAtLeast,
+} from "@agent-native/core/org-team";
+
+if (!orgRoleAtLeast(role, "admin")) {
+  throw new Error("Organization admin role required");
+}
+```
+
+The same helpers are available from
+`@agent-native/core/client/org-team` for presentation logic. Treat those
+client checks as progressive disclosure only; repeat the authorization check
+in the server action or route that changes org state.
+
+## Resource permissions (sharing RBAC)
+
+Organization roles and resource roles are different systems:
+
+- **Organization role** controls team administration.
+- **Resource role** controls access to one document, dashboard, or other
+  shareable row.
+
+Shareable resources use three layers together:
+
+1. `owner_email` identifies the creator.
+2. `org_id` and `visibility` define the resource's tenant and coarse visibility.
+3. A companion shares table grants a user or organization `viewer`, `editor`,
+   or `admin` access.
+
+| Resource role | Access                         |
+| ------------- | ------------------------------ |
+| `viewer`      | Read                           |
+| `editor`      | Read and write                 |
+| `admin`       | Read, write, and manage shares |
+
+`admin` on a resource does not transfer ownership. The resource owner remains
+separate from every share grant.
+
+For new tenant-aware tables, use `ownableColumns()` and the access helpers:
+
+```ts
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  ...ownableColumns(), // owner_email + org_id + visibility
+});
+
+const visibleProjects = await db
+  .select()
+  .from(projects)
+  .where(accessFilter(projects, projectShares));
+
+await assertAccess("project", projectId, "editor");
+```
+
+Use these helpers consistently:
+
+- `accessFilter(table, sharesTable)` for list/read queries.
+- `resolveAccess(resourceType, resourceId)` when the action needs to inspect
+  the effective access role.
+- `assertAccess(resourceType, resourceId, minRole)` at the top of a write or
+  single-record action.
+
+The framework's SQL agent tools are scoped as well, but direct Drizzle queries
+in actions and custom routes still need the access helpers. Run
+`pnpm action db-check-scoping` and `pnpm guards` while developing to catch
+missing ownership or unscoped query paths.
+
+## Environment variables: what belongs where
+
+Environment variables configure the deployment. They are not a database for
+user or team state.
+
+| Store                           | Use it for                                                                                              | Do not use it for                                                         |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Server/deploy environment       | One value shared by the whole app instance, such as `DATABASE_URL`, auth signing keys, or an A2A secret | A user's API key or a team's mutable setting                              |
+| `VITE_*` build-time environment | Non-secret values that must be embedded in browser code                                                 | Secrets; anything with `VITE_` can be public                              |
+| Encrypted credential/vault APIs | Per-user and per-organization provider keys, OAuth tokens, and app secrets                              | Deployment bootstrapping that must exist before the database is available |
+| SQL application state/settings  | App state, preferences, and references                                                                  | Raw credentials, tokens, or large file payloads                           |
+
+For local development, put deploy-level values in a gitignored `.env`. In a
+workspace, the root `.env` is shared by apps and `apps/<name>/.env` overrides it
+for that app. Never commit real values.
+
+## How environment files are loaded {#env-loading}
+
+There is not one central environment schema. The effective contract is split
+between dotenv loading, Vite's browser exposure, secret registration, and the
+feature that consumes each value. For the framework's dotenv loader, the
+effective precedence is:
+
+1. Values already present in the shell.
+2. The app's `.env.local`.
+3. The app's `.env`.
+4. The workspace root `.env.local`.
+5. The workspace root `.env`.
+
+Workspace files only fill keys the app has not already defined. This lets a
+workspace keep shared defaults in one place while an app or shell overrides a
+value deliberately. `VITE_*` values are an additional build-time contract:
+Vite embeds them in browser code, so treat every `VITE_*` value as public even
+when it came from a private `.env` file.
+
+## Framework environment variables
+
+There is no single useful list of every environment variable in an app: each
+template and provider adds its own integration settings. The table below is the
+framework-level set developers most often need. Feature-specific variables stay
+on the page for the feature that owns them.
+
+### Database and public URL
+
+| Variable                                                  | What it does                                                                                                                      |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `APP_NAME`                                                | Names the current app and enables prefixed lookups such as `MAIL_DATABASE_URL` when the app name is `mail`.                       |
+| `DATABASE_URL`                                            | Persistent SQL connection. Unset uses local SQLite; `pglite:./data/pglite` opts into local Postgres semantics.                    |
+| `DATABASE_AUTH_TOKEN`                                     | Separate auth token for providers such as Turso/libSQL.                                                                           |
+| `<APP_NAME>_DATABASE_URL`                                 | Per-app database override in a multi-app workspace; it wins over `DATABASE_URL` and `NETLIFY_DATABASE_URL`.                       |
+| `<APP_NAME>_DATABASE_AUTH_TOKEN`                          | Per-app auth-token override; it wins over `DATABASE_AUTH_TOKEN` and `NETLIFY_DATABASE_AUTH_TOKEN`.                                |
+| `NETLIFY_DATABASE_URL`                                    | Netlify-managed database fallback when no app-prefixed or generic `DATABASE_URL` is set.                                          |
+| `NETLIFY_DATABASE_AUTH_TOKEN`                             | Netlify-managed database auth-token fallback.                                                                                     |
+| `<APP_NAME>_DATABASE_URL_UNPOOLED`                        | Per-app direct connection used for migrations where the provider exposes a pooled and unpooled endpoint.                          |
+| `DATABASE_URL_UNPOOLED` / `NETLIFY_DATABASE_URL_UNPOOLED` | Generic or Netlify direct migration connection fallback. The app-prefixed value wins when present.                                |
+| `ALLOW_DRIZZLE_PUSH_ON_NEON`                              | Set to `1` only for an intentional local schema push against Neon. Do not set it in CI or production.                             |
+| `APP_URL`                                                 | Canonical app/workspace origin used for generated links and callbacks.                                                            |
+| `WORKSPACE_OAUTH_ORIGIN` / `VITE_WORKSPACE_OAUTH_ORIGIN`  | Workspace OAuth origin, used when the workspace gateway and app origin differ.                                                    |
+| `BETTER_AUTH_URL` / `VITE_BETTER_AUTH_URL`                | Explicit public auth origin for session and OAuth URL construction; `APP_URL` and request/platform origins can provide fallbacks. |
+| `WEBHOOK_BASE_URL`                                        | Optional callback origin when webhook self-callbacks should use a stable custom domain instead of the deploy preview URL.         |
+| `URL` / `DEPLOY_URL` / `DEPLOY_PRIME_URL`                 | Platform-provided public URL fallbacks, especially for Netlify previews and deploys.                                              |
+| `VERCEL_PROJECT_PRODUCTION_URL` / `VERCEL_URL`            | Vercel's production and deployment-hostname fallbacks.                                                                            |
+| `PORT`                                                    | Node server port.                                                                                                                 |
+| `APP_BASE_PATH` / `VITE_APP_BASE_PATH`                    | Mounts an app under a path such as `/mail`; the `VITE_*` form preserves that path in browser code.                                |
+| `NITRO_PRESET`                                            | Selects the deployment/build target, such as `netlify`, `vercel`, or `cloudflare_pages`.                                          |
+
+### Authentication, cookies, and org defaults
+
+| Variable                                | What it does                                                                                                |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`                    | Production session-signing secret and fallback key material. Generate a fresh 32+ character value.          |
+| `OAUTH_STATE_SECRET`                    | Dedicated HMAC key for OAuth state envelopes; falls back to `BETTER_AUTH_SECRET` when unset.                |
+| `SECRETS_ENCRYPTION_KEY`                | AES-256-GCM key for encrypted credentials and vault rows; falls back to `BETTER_AUTH_SECRET`.               |
+| `AUTH_DISABLED`                         | Local/demo escape hatch that makes every request one shared user. Never use it with real production users.  |
+| `AUTH_SKIP_EMAIL_VERIFICATION`          | Set to `1` for QA/preview signup without email verification.                                                |
+| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Set to `1` to disable localhost's automatic throwaway account.                                              |
+| `AUTH_MODE`                             | Controls CLI/agent identity resolution such as `pnpm action`; it is not a browser login bypass.             |
+| `COOKIE_DOMAIN`                         | Shares cookies across same-database subdomains when explicitly configured.                                  |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | Set to `1` with `COOKIE_DOMAIN` when intentionally sharing one auth database across first-party subdomains. |
+| `AGENT_NATIVE_WORKSPACE`                | Enables the shared workspace session realm for a multi-app workspace.                                       |
+| `VITE_AGENT_NATIVE_WORKSPACE`           | Build-time/browser equivalent of `AGENT_NATIVE_WORKSPACE`.                                                  |
+| `AUTO_CREATE_DEFAULT_ORG`               | Defaults to enabled; set to `0` to stop creating a personal organization for users with no membership.      |
+
+### OAuth providers
+
+| Variable                                                    | What it does                                                                               |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` | Preferred low-scope Google OAuth client for signing users in.                              |
+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`                 | Google OAuth fallback and client credentials for Google API integrations such as Calendar. |
+| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`                 | Enable GitHub sign-in.                                                                     |
+| `GOOGLE_AUTH_MODE`                                          | Chooses Google sign-in UX: `auto`, `popup`, or `redirect`; defaults to `auto`.             |
+
+### Agent providers and runtime
+
+| Variable                       | What it does                                                                                             |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `AGENT_ENGINE`                 | Explicitly selects the agent engine, for example a built-in provider or `codex-cli`.                     |
+| `AGENT_ENGINE_PREFER_BYO_KEY`  | Set to `true` to prefer a user's stored provider key over the managed Builder engine.                    |
+| `ANTHROPIC_API_KEY`            | Deploy-level Anthropic fallback for the agent. In multi-tenant hosted apps, prefer per-user credentials. |
+| `OPENAI_API_KEY`               | Deploy-level OpenAI provider key.                                                                        |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Deploy-level Google Gemini provider key.                                                                 |
+| `OPENROUTER_API_KEY`           | Deploy-level OpenRouter provider key.                                                                    |
+| `GROQ_API_KEY`                 | Deploy-level Groq provider key.                                                                          |
+| `MISTRAL_API_KEY`              | Deploy-level Mistral provider key.                                                                       |
+| `COHERE_API_KEY`               | Deploy-level Cohere provider key.                                                                        |
+| `AGENT_MAX_ITERATIONS`         | Default maximum agent loop iterations; app settings can override it where supported.                     |
+| `AGENT_MAX_OUTPUT_TOKENS`      | Default output-token limit for the agent.                                                                |
+| `AGENT_PROD_CODE_EXECUTION`    | Production code execution mode: `off`, `sandboxed`, or `trusted`. The default is `off`.                  |
+
+### Optional framework integrations
+
+These values enable optional capabilities. When a user or organization has a
+scoped credential in the app's secret or credential settings, that scoped value
+can take precedence over the deploy environment.
+
+| Variable                                                                        | What it does                                                                                                                                    |
+| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BRAVE_SEARCH_API_KEY` / `TAVILY_API_KEY` / `EXA_API_KEY` / `FIRECRAWL_API_KEY` | Enable the corresponding web-search BYOK provider. The search tool tries configured providers before the managed Builder fallback.              |
+| `GITHUB_TOKEN`                                                                  | Workspace-level GitHub API fallback for repository and PR operations.                                                                           |
+| `RESEND_API_KEY`                                                                | Enables Resend email delivery.                                                                                                                  |
+| `SENDGRID_API_KEY` / `EMAIL_FROM`                                               | Enables SendGrid email delivery and supplies its sender address. Production email requires Resend or SendGrid; SendGrid also requires a sender. |
+| `SENTRY_SERVER_DSN` / `SENTRY_CLIENT_DSN` / `SENTRY_DSN`                        | Optional Sentry error reporting for Nitro, browser, or both. No DSN means that surface is disabled.                                             |
+| `VITE_SENTRY_CLIENT_DSN`                                                        | Build-time browser Sentry DSN; runtime `SENTRY_CLIENT_DSN` or shared `SENTRY_DSN` can also configure SSR apps.                                  |
+| `SENTRY_ENVIRONMENT` / `SENTRY_SERVER_TRACES_SAMPLE_RATE`                       | Label Sentry events and opt into server performance traces (`0`–`1`; default `0`).                                                              |
+| `POSTHOG_API_KEY` / `POSTHOG_HOST`                                              | Configure PostHog tracking and its optional host.                                                                                               |
+| `MIXPANEL_TOKEN` / `AMPLITUDE_API_KEY`                                          | Configure Mixpanel or Amplitude tracking.                                                                                                       |
+| `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` / `VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY`  | Public write key for first-party analytics ingestion; the `VITE_*` form is for browser builds.                                                  |
+| `AGENT_NATIVE_ANALYTICS_ENDPOINT` / `VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT`      | Override the first-party analytics ingestion endpoint for server or browser events.                                                             |
+| `TRACKING_WEBHOOK_URL` / `TRACKING_WEBHOOK_AUTH`                                | Send tracking events to a webhook and optionally provide its `Authorization` header value.                                                      |
+| `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS`                                        | Set to `1` only for local development while configuring webhook signing secrets. Never set it in production.                                    |
+
+Template-specific variables belong with the template that owns the feature and
+its `.env.example` or feature docs. Start with [Messaging](/docs/messaging),
+[Tracking](/docs/tracking), [Observability](/docs/observability), or the
+template's development guide when a variable is not in this framework-level
+map.
+
+### MCP, A2A, and CLI identity
+
+| Variable                     | What it does                                                                                                                |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `A2A_SECRET`                 | Shared signing secret for production cross-app A2A and queued integration dispatch. Use the same value across sibling apps. |
+| `ACCESS_TOKEN`               | One static bearer fallback for MCP clients that cannot use OAuth. It is not browser authentication.                         |
+| `ACCESS_TOKENS`              | Comma-separated static bearer fallbacks for MCP clients.                                                                    |
+| `MCP_OAUTH_ACCESS_TOKEN_TTL` | Lifetime for MCP OAuth access tokens; defaults to `30d`.                                                                    |
+| `AGENT_USER_EMAIL`           | CLI-only user identity fallback when no request context exists. It does not impersonate browser requests.                   |
+| `AGENT_USER_NAME`            | CLI-only display-name fallback.                                                                                             |
+| `AGENT_ORG_ID`               | CLI-only active-org fallback when no request context exists. It does not override a browser session.                        |
+| `AGENT_USER_TIMEZONE`        | CLI/agent timezone fallback.                                                                                                |
+
+`A2A_SECRET` is deployment-wide signing material. The organization-level
+`organizations.a2a_secret` is a separate, UI-managed secret used when an org
+delegates between separately deployed apps by organization domain. Do not copy
+the org-level secret into `.env`; manage it from the organization settings
+surface.
+
+### Workspace route visibility
+
+These are generated automatically by the workspace deploy/dev commands in most
+projects. Configure them directly only when you are building the workspace
+runtime yourself:
+
+| Variable                                     | What it does                                                       |
+| -------------------------------------------- | ------------------------------------------------------------------ |
+| `AGENT_NATIVE_WORKSPACE_APP_ID`              | Identifies the current app inside a multi-app workspace.           |
+| `AGENT_NATIVE_WORKSPACE_APP_AUDIENCE`        | Sets the app audience, usually `internal` or `public`.             |
+| `AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS`    | JSON array of public route prefixes.                               |
+| `AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS` | JSON array of route prefixes that remain authenticated.            |
+| `WORKSPACE_ORG_NAME`                         | Optional organization name used by workspace bootstrap tooling.    |
+| `WORKSPACE_ORG_DOMAIN`                       | Optional allowed email domain used by workspace bootstrap tooling. |
+| `WORKSPACE_OWNER_EMAIL`                      | Optional owner identity used by workspace bootstrap tooling.       |
+
+## A practical setup sequence
+
+For a new team app, configure in this order:
+
+1. Set `DATABASE_URL` if the app will be shared or deployed.
+2. Set `BETTER_AUTH_SECRET` and an explicit public URL such as `APP_URL` or
+   `BETTER_AUTH_URL` before production.
+3. Render `OrgSwitcher` and `TeamPage` from the shared org/team kit.
+4. Add `...ownableColumns()` to tenant-aware tables.
+5. Use `ctx.orgId` when creating rows and `accessFilter` / `assertAccess` when
+   reading or mutating them.
+6. Put provider credentials in the encrypted credential/vault surface when
+   they vary by user or organization; keep env keys for deploy-level defaults.
+7. Add `A2A_SECRET` to every production app that delegates to a sibling app or
+   processes signed integration tasks.
+
+## Related docs
+
+- [**Authentication**](/docs/authentication) — sessions, OAuth, cookies, and auth flags
+- [**Multi-Tenancy**](/docs/multi-tenancy) — org switching and tenant isolation
+- [**Security — Data Scoping**](/docs/security#data-scoping) — SQL scoping and access guards
+- [**Sharing & Privacy**](/docs/sharing) — resource visibility and share roles
+- [**Database**](/docs/database) — schema and connection details
+- [**Deployment**](/docs/deployment#environment-variables) — production and provider environment
+- [**Org & Team Kit**](/docs/toolkit-org-team) — reusable UI components and hooks

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.106.2",
+  "version": "0.107.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/client/AssistantChat.tsx

@@ -172,6 +172,7 @@ import {
   useGuidedQuestionFlow,
 } from "./guided-questions.js";
 import { useT } from "./i18n.js";
+import { McpConnectionSuggestion } from "./resources/McpConnectionSuggestion.js";
 import {
   AgentAutoContinueSignal,
   type ContentPart,
@@ -2239,6 +2240,14 @@ const AssistantChatInner = forwardRef<
   // (unsupported format, size cap, body-size rejection, drop errors).
   // Cleared on the next message send.
   const [composerError, setComposerError] = useState<string | null>(null);
+  const [composerText, setComposerText] = useState("");
+  const handleComposerTextChange = useCallback(
+    (text: string) => {
+      setComposerText(text);
+      onComposerTextChange?.(text);
+    },
+    [onComposerTextChange],
+  );
   const dropDepthRef = useRef(0);
   const handleChatDragEnter = useCallback((e: React.DragEvent) => {
     if (!Array.from(e.dataTransfer?.types ?? []).includes("Files")) return;
@@ -5382,6 +5391,9 @@ const AssistantChatInner = forwardRef<
                 </MessageScrollerProvider>
 
                 {showComposerSlot ? composerSlot : null}
+                {isActiveComposer && (
+                  <McpConnectionSuggestion text={composerText} />
+                )}
                 {showCenteredEmptyThreadFooterSlot ? (
                   <div className="agent-thread-footer-slot agent-thread-footer-slot--centered-empty">
                     {resolvedThreadFooterSlot}
@@ -5488,7 +5500,7 @@ const AssistantChatInner = forwardRef<
                             focusRef={tiptapRef}
                             onTextChange={
                               isActiveComposer
-                                ? onComposerTextChange
+                                ? handleComposerTextChange
                                 : undefined
                             }
                             disabled={isComposerDisabled}

package/corpus/core/src/client/chat/message-components.tsx

@@ -62,6 +62,7 @@ import {
 import { isPastedTextAttachmentName } from "../composer/pasted-text.js";
 import { PastedTextChip } from "../composer/PastedTextChip.js";
 import { ThumbsFeedback } from "../observability/ThumbsFeedback.js";
+import { McpConnectionSuggestion } from "../resources/McpConnectionSuggestion.js";
 import type { ContentPart } from "../sse-event-processor.js";
 import { cn } from "../utils.js";
 import {
@@ -819,6 +820,37 @@ function assistantMessageStatusIsTerminal(message: {
   return statusType === "complete" || statusType === "incomplete";
 }
 
+function messageTextFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .flatMap((part) => {
+      if (!part || typeof part !== "object") return [];
+      const record = part as {
+        type?: unknown;
+        text?: unknown;
+        result?: unknown;
+      };
+      const values: string[] = [];
+      if (typeof record.text === "string") values.push(record.text);
+      if (record.type === "tool-call" && typeof record.result === "string") {
+        values.push(record.result);
+      }
+      return values;
+    })
+    .join("\n");
+}
+
+function latestUserMessageText(messages: readonly unknown[]): string {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!message || typeof message !== "object") continue;
+    const record = message as { role?: unknown; content?: unknown };
+    if (record.role === "user") return messageTextFromContent(record.content);
+  }
+  return "";
+}
+
 export function assistantMessageHasUnresolvedTool(content: unknown): boolean {
   if (!Array.isArray(content)) return false;
   return content.some((part): boolean => {
@@ -946,6 +978,8 @@ export function AssistantMessage() {
     thread.messages[thread.messages.length - 1].id === msg.id;
   const hasRenderableContent = assistantMessageHasRenderableContent(msg);
   const hasUnresolvedTool = assistantMessageHasUnresolvedTool(msg.content);
+  const responseConnectionText = messageTextFromContent(msg.content);
+  const responseConnectionContext = latestUserMessageText(thread.messages);
   const isComplete = shouldShowAssistantMessageFooter({
     isLast,
     chatRunning,
@@ -1104,6 +1138,13 @@ export function AssistantMessage() {
         {isComplete && hasCodeAgentTools && msgContent && (
           <FilesChangedSummary parts={msgContent} />
         )}
+        {isComplete && isLast && (
+          <McpConnectionSuggestion
+            text={responseConnectionText}
+            contextText={responseConnectionContext}
+            variant="response"
+          />
+        )}
         {isLast && hasUnresolvedTool && !chatRunning && (
           <RunningActivityStatus label="Thinking" />
         )}