@agent-native/core 0.107.0 → 0.107.1

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2288
-- template files: 6095
+- template files: 6113

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @agent-native/core
 
+## 0.107.1
+
+### Patch Changes
+
+- 8e0afec: Preserve chat continuation context after stale background workers and make Stop durable before a serverless run id exists.
+- 8e0afec: Offer the Figma REST API personal access token fallback when Figma MCP links are restricted.
+- 8e0afec: Add a practical guide for organization context, team roles, resource permissions, RBAC, and framework environment variables.
+- 8e0afec: Keep empty full-page chat navigation from automatically opening the AgentSidebar.
+- 8e0afec: Keep the share popover open while adding people and preserve unfinished invite emails when it is reopened.
+
 ## 0.107.0
 
 ### Minor Changes

package/corpus/core/docs/content/integrations.mdx

@@ -488,33 +488,33 @@ endpoint is reachable or cataloged, but a live provider authorization or tool
 session still needs to be completed. **Restricted** entries remain discoverable
 but need provider or administrator setup before a generic connection can work.
 
-| Integration                                                                                                                    | Connection mode        | Status                             | Endpoint                                  | Setup and notes                                                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| [Context7](https://context7.com/)                                                                                              | No auth                | Ready · verified                   | `https://mcp.context7.com/mcp`            | Fetch current library and framework docs.                                                                           |
-| [Sentry](https://docs.sentry.io/product/sentry-mcp/)                                                                           | Header / token         | Ready · preflight only             | `https://mcp.sentry.dev/mcp`              | Add a Sentry bearer token as the `Authorization` header.                                                            |
-| [Notion](https://developers.notion.com/guides/mcp/get-started-with-mcp)                                                        | OAuth                  | Ready · preflight only             | `https://mcp.notion.com/mcp`              | User OAuth; enterprise admins can audit or restrict MCP clients.                                                    |
-| [Semgrep](https://github.com/semgrep/mcp#readme)                                                                               | No auth                | Ready · preflight only             | `https://mcp.semgrep.ai/mcp`              | Scan code for security findings.                                                                                    |
-| [Linear](https://linear.app/docs/mcp)                                                                                          | OAuth                  | Ready · preflight only             | `https://mcp.linear.app/mcp`              | Authorize the workspace and issue permissions required by the workflow.                                             |
-| [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/)                                   | OAuth + provider setup | Restricted                         | `https://mcp.atlassian.com/v1/mcp/authv2` | Admins may need to trust the app origin and enable Rovo Read, Write, and Search permissions.                        |
-| [Supabase](https://www.builder.io/c/docs/fusion-connect-to-supabase)                                                           | OAuth                  | Ready · preflight only             | `https://mcp.supabase.com/mcp`            | Authorize the Supabase project and requested backend scopes.                                                        |
-| [Neon](https://www.builder.io/c/docs/fusion-connect-to-neon)                                                                   | OAuth                  | Ready · preflight only             | `https://mcp.neon.tech/sse`               | Authorize access to the serverless Postgres projects needed by the app.                                             |
-| [Stripe](https://docs.stripe.com/mcp)                                                                                          | OAuth                  | Ready · preflight only             | `https://mcp.stripe.com`                  | Review payment, customer, and subscription permissions before authorizing.                                          |
-| [Cloudflare](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/)               | OAuth                  | Ready · preflight only             | `https://mcp.cloudflare.com/mcp`          | Choose the narrowest Cloudflare server and review scopes.                                                           |
-| [GitLab](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)                                                      | OAuth + provider setup | Beta · restricted                  | `https://gitlab.com/api/v4/mcp`           | A top-level group admin, or the equivalent self-managed instance admin, must allow MCP.                             |
-| [Figma](https://developers.figma.com/docs/figma-mcp-server/)                                                                   | Manual setup           | Approved clients only · restricted | `https://mcp.figma.com/mcp`               | Figma only allows clients in its MCP Catalog; use the Figma OAuth connector for app-owned workflows until approved. |
-| [Canva](https://www.canva.dev/docs/mcp/)                                                                                       | Manual setup           | Approved domains · restricted      | `https://mcp.canva.com/mcp`               | Per-user OAuth; clients must allow Canva's canva.com and canva.ai domains and follow the current redirect setup.    |
-| [Vercel](https://vercel.com/docs/agent-resources/vercel-mcp)                                                                   | Manual setup           | Approved clients only · restricted | `https://mcp.vercel.com`                  | Vercel must list the client as approved before a generic connection will work.                                      |
-| [GitHub](https://github.com/github/github-mcp-server)                                                                          | Manual setup           | Provider setup · restricted        | `https://api.githubcopilot.com/mcp/`      | Use a registered OAuth app; organizations may also enforce OAuth App Access Policies.                               |
-| [Slack](https://docs.slack.dev/ai/slack-mcp-server/)                                                                           | Manual setup           | Approved clients only · restricted | `https://mcp.slack.com/mcp`               | Requires a fixed registered Slack app; dynamic client registration is not supported.                                |
-| [Asana](https://developers.asana.com/docs/integrating-with-asanas-mcp-server)                                                  | Manual setup           | Provider setup · restricted        | `https://mcp.asana.com/v2/mcp`            | Pre-register an Asana MCP OAuth app before connecting.                                                              |
-| [HubSpot](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server) | Manual setup           | Provider setup · restricted        | `https://mcp.hubspot.com`                 | Create a HubSpot MCP Auth App with PKCE; the existing HubSpot OAuth connector remains available to app actions.     |
-| [Intercom](https://developers.intercom.com/docs/guides/mcp)                                                                    | OAuth                  | Ready · preflight only             | `https://mcp.intercom.com/mcp`            | Available for US-hosted workspaces; confirm region and scopes during authorization.                                 |
-| [monday.com](https://developer.monday.com/api-reference/docs/build-on-monday-with-ai)                                          | OAuth                  | Ready · preflight only             | `https://mcp.monday.com/mcp`              | Choose the workspace and permissions to share during authorization.                                                 |
-| [Webflow](https://developers.webflow.com/mcp/reference/getting-started)                                                        | OAuth                  | Ready · preflight only             | `https://mcp.webflow.com/mcp`             | Designer capabilities may install Webflow's Bridge App; Data API access is separate.                                |
-| [PayPal](https://developer.paypal.com/ai-tools/mcp-server/)                                                                    | OAuth                  | Ready · preflight only             | `https://mcp.paypal.com/sse`              | Review merchant permissions before authorizing the remote server.                                                   |
-| [Box](https://developer.box.com/guides/box-mcp)                                                                                | Manual setup           | Beta · restricted                  | `https://mcp.box.com`                     | An administrator must enable Box MCP; custom clients also need credentials, a redirect URI, and approved scopes.    |
-| [Netlify](https://docs.netlify.com/build/build-with-ai/agent-setup-guides/agent-setup-overview/)                               | OAuth                  | Ready · preflight only             | `https://netlify-mcp.netlify.app/mcp`     | Review site and team permissions before completing OAuth.                                                           |
-| [Zapier MCP](https://help.zapier.com/hc/en-us/articles/36265392843917-Use-Zapier-MCP-with-your-client)                         | Header / token         | User-created server · restricted   | `https://mcp.zapier.com/api/v1/connect`   | Create the MCP server in Zapier, then paste its generated bearer token into the header field.                       |
+| Integration                                                                                                                    | Connection mode        | Status                             | Endpoint                                  | Setup and notes                                                                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Context7](https://context7.com/)                                                                                              | No auth                | Ready · verified                   | `https://mcp.context7.com/mcp`            | Fetch current library and framework docs.                                                                                                                                                                                         |
+| [Sentry](https://docs.sentry.io/product/sentry-mcp/)                                                                           | Header / token         | Ready · preflight only             | `https://mcp.sentry.dev/mcp`              | Add a Sentry bearer token as the `Authorization` header.                                                                                                                                                                          |
+| [Notion](https://developers.notion.com/guides/mcp/get-started-with-mcp)                                                        | OAuth                  | Ready · preflight only             | `https://mcp.notion.com/mcp`              | User OAuth; enterprise admins can audit or restrict MCP clients.                                                                                                                                                                  |
+| [Semgrep](https://github.com/semgrep/mcp#readme)                                                                               | No auth                | Ready · preflight only             | `https://mcp.semgrep.ai/mcp`              | Scan code for security findings.                                                                                                                                                                                                  |
+| [Linear](https://linear.app/docs/mcp)                                                                                          | OAuth                  | Ready · preflight only             | `https://mcp.linear.app/mcp`              | Authorize the workspace and issue permissions required by the workflow.                                                                                                                                                           |
+| [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/)                                   | OAuth + provider setup | Restricted                         | `https://mcp.atlassian.com/v1/mcp/authv2` | Admins may need to trust the app origin and enable Rovo Read, Write, and Search permissions.                                                                                                                                      |
+| [Supabase](https://www.builder.io/c/docs/fusion-connect-to-supabase)                                                           | OAuth                  | Ready · preflight only             | `https://mcp.supabase.com/mcp`            | Authorize the Supabase project and requested backend scopes.                                                                                                                                                                      |
+| [Neon](https://www.builder.io/c/docs/fusion-connect-to-neon)                                                                   | OAuth                  | Ready · preflight only             | `https://mcp.neon.tech/sse`               | Authorize access to the serverless Postgres projects needed by the app.                                                                                                                                                           |
+| [Stripe](https://docs.stripe.com/mcp)                                                                                          | OAuth                  | Ready · preflight only             | `https://mcp.stripe.com`                  | Review payment, customer, and subscription permissions before authorizing.                                                                                                                                                        |
+| [Cloudflare](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/)               | OAuth                  | Ready · preflight only             | `https://mcp.cloudflare.com/mcp`          | Choose the narrowest Cloudflare server and review scopes.                                                                                                                                                                         |
+| [GitLab](https://docs.gitlab.com/user/model_context_protocol/mcp_server/)                                                      | OAuth + provider setup | Beta · restricted                  | `https://gitlab.com/api/v4/mcp`           | A top-level group admin, or the equivalent self-managed instance admin, must allow MCP.                                                                                                                                           |
+| [Figma](https://developers.figma.com/docs/figma-mcp-server/)                                                                   | Manual setup           | Approved clients only · restricted | `https://mcp.figma.com/mcp`               | Figma only allows clients in its MCP Catalog. Use the [Figma REST API personal access token fallback](https://developers.figma.com/docs/rest-api/personal-access-tokens/) for file and node reads until Agent Native is approved. |
+| [Canva](https://www.canva.dev/docs/mcp/)                                                                                       | Manual setup           | Approved domains · restricted      | `https://mcp.canva.com/mcp`               | Per-user OAuth; clients must allow Canva's canva.com and canva.ai domains and follow the current redirect setup.                                                                                                                  |
+| [Vercel](https://vercel.com/docs/agent-resources/vercel-mcp)                                                                   | Manual setup           | Approved clients only · restricted | `https://mcp.vercel.com`                  | Vercel must list the client as approved before a generic connection will work.                                                                                                                                                    |
+| [GitHub](https://github.com/github/github-mcp-server)                                                                          | Manual setup           | Provider setup · restricted        | `https://api.githubcopilot.com/mcp/`      | Use a registered OAuth app; organizations may also enforce OAuth App Access Policies.                                                                                                                                             |
+| [Slack](https://docs.slack.dev/ai/slack-mcp-server/)                                                                           | Manual setup           | Approved clients only · restricted | `https://mcp.slack.com/mcp`               | Requires a fixed registered Slack app; dynamic client registration is not supported.                                                                                                                                              |
+| [Asana](https://developers.asana.com/docs/integrating-with-asanas-mcp-server)                                                  | Manual setup           | Provider setup · restricted        | `https://mcp.asana.com/v2/mcp`            | Pre-register an Asana MCP OAuth app before connecting.                                                                                                                                                                            |
+| [HubSpot](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/integrate-with-the-remote-hubspot-mcp-server) | Manual setup           | Provider setup · restricted        | `https://mcp.hubspot.com`                 | Create a HubSpot MCP Auth App with PKCE; the existing HubSpot OAuth connector remains available to app actions.                                                                                                                   |
+| [Intercom](https://developers.intercom.com/docs/guides/mcp)                                                                    | OAuth                  | Ready · preflight only             | `https://mcp.intercom.com/mcp`            | Available for US-hosted workspaces; confirm region and scopes during authorization.                                                                                                                                               |
+| [monday.com](https://developer.monday.com/api-reference/docs/build-on-monday-with-ai)                                          | OAuth                  | Ready · preflight only             | `https://mcp.monday.com/mcp`              | Choose the workspace and permissions to share during authorization.                                                                                                                                                               |
+| [Webflow](https://developers.webflow.com/mcp/reference/getting-started)                                                        | OAuth                  | Ready · preflight only             | `https://mcp.webflow.com/mcp`             | Designer capabilities may install Webflow's Bridge App; Data API access is separate.                                                                                                                                              |
+| [PayPal](https://developer.paypal.com/ai-tools/mcp-server/)                                                                    | OAuth                  | Ready · preflight only             | `https://mcp.paypal.com/sse`              | Review merchant permissions before authorizing the remote server.                                                                                                                                                                 |
+| [Box](https://developer.box.com/guides/box-mcp)                                                                                | Manual setup           | Beta · restricted                  | `https://mcp.box.com`                     | An administrator must enable Box MCP; custom clients also need credentials, a redirect URI, and approved scopes.                                                                                                                  |
+| [Netlify](https://docs.netlify.com/build/build-with-ai/agent-setup-guides/agent-setup-overview/)                               | OAuth                  | Ready · preflight only             | `https://netlify-mcp.netlify.app/mcp`     | Review site and team permissions before completing OAuth.                                                                                                                                                                         |
+| [Zapier MCP](https://help.zapier.com/hc/en-us/articles/36265392843917-Use-Zapier-MCP-with-your-client)                         | Header / token         | User-created server · restricted   | `https://mcp.zapier.com/api/v1/connect`   | Create the MCP server in Zapier, then paste its generated bearer token into the header field.                                                                                                                                     |
 
 ### Repeatable preflight verification
 

package/corpus/core/package.json

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

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

@@ -136,6 +136,8 @@ import {
   readLedgerEntry,
   clearLedgerForThread,
   insertRun,
+  isTurnAborted,
+  markRunAborted,
   updateRunHeartbeat,
   updateRunStatusIfRunning,
   setRunError,
@@ -7058,6 +7060,13 @@ export function createProductionAgentHandler(
     // slot and inserted the run row before dispatching, so re-claiming here
     // would falsely 409 against the row the foreground holds.
     if (threadId && !isBackgroundWorker) {
+      if (
+        typeof requestTurnId === "string" &&
+        requestTurnId &&
+        (await isTurnAborted(threadId, requestTurnId))
+      ) {
+        return { ok: true, stopped: true };
+      }
       const slot = await tryClaimRunSlot(threadId);
       if (!slot.claimed) {
         setResponseStatus(event, 409);
@@ -7186,6 +7195,16 @@ export function createProductionAgentHandler(
         );
       }
 
+      // Stop may land after the pre-claim check but before the durable row was
+      // inserted. Terminalize that row before it can be handed to a worker.
+      if (
+        backgroundRowInserted &&
+        (await isTurnAborted(effectiveThreadId, effectiveTurnId))
+      ) {
+        await markRunAborted(runId, "user");
+        return { ok: true, stopped: true };
+      }
+
       let dispatched = false;
       const backgroundDispatchPath = resolveAgentChatProcessRunDispatchPath();
       const expectsNetlifyBackgroundFunction =

package/corpus/core/src/agent/run-store.ts

@@ -42,6 +42,21 @@ export const RUN_STALE_MS = 15_000;
  */
 export const BACKGROUND_RUN_STALE_MS = 90_000;
 
+/**
+ * A row is `background` only while the platform may still be cold-starting the
+ * worker, so it needs the full 90s handoff allowance above. Once that worker
+ * atomically claims the row (`background-processing`), it has already proved
+ * it started and should be reaped sooner if both heartbeat and real progress
+ * stop. This keeps a silent post-claim worker death from holding the client
+ * for the entire cold-start window before the durable successor is created.
+ *
+ * A real long-running tool or nested agent call still sets `in_flight_since`,
+ * which grants the bounded `IN_FLIGHT_RUN_STALE_GRACE_MS` below. Healthy model
+ * work keeps the normal heartbeat moving every 1.5s, so this is only a faster
+ * recovery path for a worker that has genuinely gone silent.
+ */
+export const BACKGROUND_PROCESSING_RUN_STALE_MS = 45_000;
+
 export const STALE_RUN_ERROR_EVENT = {
   type: "error",
   error:
@@ -601,7 +616,7 @@ function backgroundAwareStaleCutoffSql(): string {
   // `CAST(? AS BIGINT)` is required: without it Postgres infers the param as
   // int4 from the int4 window literals, so the bound `Date.now()` ms epoch
   // overflows int4. The cast keeps the subtraction 64-bit; a no-op on SQLite.
-  return `(CAST(? AS BIGINT) - CASE WHEN dispatch_mode LIKE 'background%' THEN ${BACKGROUND_RUN_STALE_MS} ELSE ${RUN_STALE_MS} END)`;
+  return `(CAST(? AS BIGINT) - CASE WHEN dispatch_mode = 'background-processing' THEN ${BACKGROUND_PROCESSING_RUN_STALE_MS} WHEN dispatch_mode LIKE 'background%' THEN ${BACKGROUND_RUN_STALE_MS} ELSE ${RUN_STALE_MS} END)`;
 }
 
 function terminalRunEventExclusionSql(runIdColumn = "id"): string {
@@ -1358,6 +1373,21 @@ function generateRecoveryRunId(): string {
   return `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
+function staleRecoveryDispatchPayload(payload: string): string {
+  try {
+    const parsed = JSON.parse(payload);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return payload;
+    }
+    return JSON.stringify({
+      ...(parsed as Record<string, unknown>),
+      internalContinuation: true,
+    });
+  } catch {
+    return payload;
+  }
+}
+
 /**
  * FIX 3 (durable-background incident): when a stale-run reaper is about to
  * flip a BACKGROUND chat-turn run to errored/stale_run, attempt to keep the
@@ -1451,7 +1481,15 @@ async function attemptStaleRunRecovery(
   const now = Date.now();
   await db.execute({
     sql: `INSERT INTO agent_runs (id, thread_id, status, started_at, heartbeat_at, last_progress_at, turn_id, dispatch_mode, dispatch_payload) VALUES (?, ?, 'running', ?, ?, ?, ?, 'background', ?) ON CONFLICT (id) DO NOTHING`,
-    args: [successorRunId, threadId, now, now, now, turnId, payload],
+    args: [
+      successorRunId,
+      threadId,
+      now,
+      now,
+      now,
+      turnId,
+      staleRecoveryDispatchPayload(payload),
+    ],
   });
   return { outcome: "recovered", successorRunId, threadId, turnId };
 }
@@ -1759,6 +1797,64 @@ export async function markRunAborted(
   }
 }
 
+function turnAbortMarkerRunId(turnId: string): string {
+  return `turn-abort-${turnId}`;
+}
+
+/** Records Stop before a foreground request has created its real run row. */
+export async function markTurnAborted(
+  threadId: string,
+  turnId: string,
+  reason: string = "user",
+): Promise<void> {
+  await ensureRunTables();
+  const now = Date.now();
+  const client = getDbExec();
+  await client.execute({
+    sql: `INSERT INTO agent_runs (id, thread_id, status, abort_reason, started_at, completed_at, heartbeat_at, last_progress_at, turn_id, terminal_reason, dispatch_mode) VALUES (?, ?, 'aborted', ?, ?, ?, ?, ?, ?, ?, 'turn-abort') ON CONFLICT (id) DO NOTHING`,
+    args: [
+      turnAbortMarkerRunId(turnId),
+      threadId,
+      reason,
+      now,
+      now,
+      now,
+      now,
+      turnId,
+      `aborted:${reason}`,
+    ],
+  });
+  const { rows } = await client.execute({
+    sql: `SELECT id FROM agent_runs WHERE thread_id = ? AND turn_id = ? AND status = 'running'`,
+    args: [threadId, turnId],
+  });
+  const runIds = rows
+    .map((row) => String((row as { id?: unknown }).id ?? ""))
+    .filter(Boolean);
+  if (runIds.length === 0) return;
+  await client.execute({
+    sql: `UPDATE agent_runs SET status = 'aborted', abort_reason = ?, completed_at = ?, terminal_reason = ? WHERE thread_id = ? AND turn_id = ? AND status = 'running'`,
+    args: [reason, Date.now(), `aborted:${reason}`, threadId, turnId],
+  });
+  await Promise.all(
+    runIds.map((runId) =>
+      safeAppendTerminalRunEvent(runId, { type: "done" }, "mark-turn-aborted"),
+    ),
+  );
+}
+
+export async function isTurnAborted(
+  threadId: string,
+  turnId: string,
+): Promise<boolean> {
+  await ensureRunTables();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT id FROM agent_runs WHERE id = ? AND thread_id = ? AND status = 'aborted' LIMIT 1`,
+    args: [turnAbortMarkerRunId(turnId), threadId],
+  });
+  return rows.length > 0;
+}
+
 export async function isRunAborted(runId: string): Promise<boolean> {
   return (await getRunAbortState(runId)).aborted;
 }

package/corpus/core/src/client/AssistantChat.tsx

@@ -38,7 +38,9 @@ import React, {
 import type { ReasoningEffort } from "../shared/reasoning-effort.js";
 import {
   ACTIVE_RUN_STATE_EVENT,
+  clearPendingTurnIfMatches,
   clearActiveRunIfMatches,
+  getPendingTurn,
   getActiveRunActivityTool,
   getActiveRun,
   resolveReconnectAfterSeq,
@@ -4281,6 +4283,7 @@ const AssistantChatInner = forwardRef<
       }
       const activeRun = getActiveRun();
       const runIdToAbort = reconnectRunIdRef.current ?? activeRun?.runId;
+      const pendingTurn = threadId ? getPendingTurn(threadId) : null;
       userStoppedRunRef.current = {
         at: Date.now(),
         ...(runIdToAbort ? { runId: runIdToAbort } : {}),
@@ -4292,6 +4295,16 @@ const AssistantChatInner = forwardRef<
         fetch(`${apiUrl}/runs/${encodeURIComponent(runIdToAbort)}/abort`, {
           method: "POST",
         }).catch(() => {});
+      } else if (pendingTurn && threadId) {
+        clearPendingTurnIfMatches(threadId, pendingTurn.turnId);
+        fetch(
+          `${apiUrl}/runs/turn/${encodeURIComponent(pendingTurn.turnId)}/abort`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ threadId }),
+          },
+        ).catch(() => {});
       }
       if (isReconnecting) {
         reconnectAbortRef.current?.abort();

package/corpus/core/src/client/CommandMenu.tsx

@@ -72,6 +72,11 @@ export function openAgentSettings(
   const normalizedSection =
     typeof section === "string" ? section : section?.section;
 
+  const secretHash = normalizedSection?.replace(/^#/, "");
+  if (secretHash?.toLowerCase().startsWith("secrets:")) {
+    window.location.hash = `#${secretHash}`;
+  }
+
   openAgentSidebar();
   // Voice mode unmounts the chat surface while its dock is collapsed, so its
   // settings listener does not exist until opening the sidebar remounts it.

package/corpus/core/src/client/active-run-state.ts

@@ -1,4 +1,5 @@
 const STORAGE_KEY = "agent-chat-active-run";
+const PENDING_TURN_STORAGE_KEY = "agent-chat-pending-turn";
 export const ACTIVE_RUN_STATE_EVENT = "agent-chat:active-run-state-change";
 
 export interface ActiveRunState {
@@ -8,6 +9,11 @@ export interface ActiveRunState {
   activityTool?: string | null;
 }
 
+export interface PendingTurnState {
+  threadId: string;
+  turnId: string;
+}
+
 function notifyActiveRunStateChanged(state: ActiveRunState | null): void {
   if (
     typeof window === "undefined" ||
@@ -88,6 +94,34 @@ export function clearActiveRunIfMatches(threadId: string, runId: string): void {
   clearActiveRun();
 }
 
+export function setPendingTurn(state: PendingTurnState): void {
+  try {
+    sessionStorage.setItem(PENDING_TURN_STORAGE_KEY, JSON.stringify(state));
+  } catch {}
+}
+
+export function getPendingTurn(threadId: string): PendingTurnState | null {
+  try {
+    const raw = sessionStorage.getItem(PENDING_TURN_STORAGE_KEY);
+    if (!raw) return null;
+    const state = JSON.parse(raw) as PendingTurnState;
+    return state.threadId === threadId && state.turnId ? state : null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearPendingTurnIfMatches(
+  threadId: string,
+  turnId?: string,
+): void {
+  const state = getPendingTurn(threadId);
+  if (!state || (turnId && state.turnId !== turnId)) return;
+  try {
+    sessionStorage.removeItem(PENDING_TURN_STORAGE_KEY);
+  } catch {}
+}
+
 /** Resume reconnect SSE after the last seen event (0 = replay from the start). */
 export function resolveReconnectAfterSeq(
   threadId: string,

package/corpus/core/src/client/agent-chat-adapter.ts

@@ -11,9 +11,11 @@ import type {
 } from "../agent/types.js";
 import type { ReasoningEffort } from "../shared/reasoning-effort.js";
 import {
+  clearPendingTurnIfMatches,
   setActiveRun,
   updateActiveRunSeq,
   clearActiveRun,
+  setPendingTurn,
 } from "./active-run-state.js";
 import { captureError } from "./analytics.js";
 import { agentNativePath } from "./api-path.js";
@@ -1634,6 +1636,7 @@ export function createAgentChatAdapter(
       const content: ContentPart[] = [];
       const toolCallCounter = { value: 0 };
       const turnId = generateTurnId();
+      if (threadId) setPendingTurn({ threadId, turnId });
       let runId: string | null = null;
       let lastSeq = -1;
       const seenRunSeqs = new Map<string, number>();
@@ -3279,6 +3282,7 @@ export function createAgentChatAdapter(
               attemptedRunIds.push(runId);
             }
             if (runId && threadId) {
+              clearPendingTurnIfMatches(threadId, turnId);
               setActiveRun({ threadId, runId, lastSeq: -1 });
             }
 

package/corpus/core/src/client/resources/McpConnectionSuggestion.tsx

@@ -7,10 +7,12 @@ import {
 import { useEffect, useMemo, useState } from "react";
 
 import { agentNativePath } from "../api-path.js";
+import { openAgentSettings } from "../CommandMenu.js";
 import { useT } from "../i18n.js";
 import {
   buildMcpOAuthStartUrl,
   findMcpIntegrationForText,
+  getMcpIntegrationApiFallback,
   getDefaultMcpIntegrations,
   isMcpConnectionFailureText,
   type DefaultMcpIntegration,
@@ -67,6 +69,12 @@ function canStartOAuth(integration: DefaultMcpIntegration): boolean {
   );
 }
 
+function hasApiFallback(
+  apiFallback: DefaultMcpIntegration["apiFallback"] | null,
+): boolean {
+  return Boolean(apiFallback);
+}
+
 export function McpConnectionSuggestion({
   text,
   contextText = "",
@@ -96,6 +104,9 @@ export function McpConnectionSuggestion({
     textIntegration.id !== contextIntegration.id
       ? null
       : (textIntegration ?? contextIntegration);
+  const apiFallback = integration
+    ? getMcpIntegrationApiFallback(integration)
+    : null;
   const servers = useMemo(
     () => [
       ...(mcpServersQuery.data?.user ?? []),
@@ -122,6 +133,11 @@ export function McpConnectionSuggestion({
     if (!integration || connecting) return;
     setError(null);
 
+    if (apiFallback) {
+      openAgentSettings(`secrets:${apiFallback.secretKey}`);
+      return;
+    }
+
     if (canStartOAuth(integration)) {
       window.location.assign(
         agentNativePath(
@@ -163,12 +179,14 @@ export function McpConnectionSuggestion({
     setDialogOpen(true);
   };
 
-  const actionLabel = canStartOAuth(integration)
-    ? t("mcpIntegrations.connectWithOAuth")
-    : integration.availability === "client-restricted" ||
-        integration.availability === "provider-setup"
-      ? t("mcpIntegrations.viewSetup")
-      : t("mcpIntegrations.connect");
+  const actionLabel = hasApiFallback(apiFallback)
+    ? t("mcpIntegrations.useApiToken")
+    : canStartOAuth(integration)
+      ? t("mcpIntegrations.connectWithOAuth")
+      : integration.availability === "client-restricted" ||
+          integration.availability === "provider-setup"
+        ? t("mcpIntegrations.viewSetup")
+        : t("mcpIntegrations.connect");
 
   return (
     <>
@@ -194,7 +212,12 @@ export function McpConnectionSuggestion({
           )}
         </div>
         <span className="min-w-0 flex-1 leading-snug text-foreground">
-          {t("mcpIntegrations.connectSuggestion", { name: integration.name })}
+          {t(
+            hasApiFallback(apiFallback)
+              ? "mcpIntegrations.connectSuggestionWithApiToken"
+              : "mcpIntegrations.connectSuggestion",
+            { name: integration.name },
+          )}
         </span>
         <button
           type="button"
@@ -203,13 +226,20 @@ export function McpConnectionSuggestion({
           className="inline-flex shrink-0 items-center gap-1 rounded-md bg-primary px-2.5 py-1.5 text-[11px] font-medium text-primary-foreground hover:bg-primary/90 disabled:pointer-events-none disabled:opacity-60"
         >
           {connecting && <IconLoader2 className="h-3 w-3 animate-spin" />}
-          {!connecting && canStartOAuth(integration) && (
+          {!connecting &&
+            canStartOAuth(integration) &&
+            !hasApiFallback(apiFallback) && (
+              <IconPlugConnected className="h-3 w-3" />
+            )}
+          {!connecting && hasApiFallback(apiFallback) && (
             <IconPlugConnected className="h-3 w-3" />
           )}
           {actionLabel}
-          {!connecting && !canStartOAuth(integration) && (
-            <IconArrowUpRight className="h-3 w-3" />
-          )}
+          {!connecting &&
+            !canStartOAuth(integration) &&
+            !hasApiFallback(apiFallback) && (
+              <IconArrowUpRight className="h-3 w-3" />
+            )}
         </button>
         <button
           type="button"

package/corpus/core/src/client/resources/McpIntegrationDialog.tsx

@@ -9,6 +9,7 @@ import { useEffect, useMemo, useRef, useState } from "react";
 
 import { AgentAskPopover } from "../AgentAskPopover.js";
 import { agentNativePath } from "../api-path.js";
+import { openAgentSettings } from "../CommandMenu.js";
 import {
   Dialog,
   DialogContent,
@@ -27,6 +28,7 @@ import {
   buildMcpOAuthStartUrl,
   createMcpIntegrationFormDefaults,
   filterMcpIntegrations,
+  getMcpIntegrationApiFallback,
   getDefaultMcpIntegrations,
   isCustomMcpIntegrationEnabled,
   resolveMcpIntegrationScope,
@@ -445,6 +447,7 @@ export function McpIntegrationDialog({
               )}
               <div className="grid gap-3 sm:grid-cols-2">
                 {filteredIntegrations.map((integration) => {
+                  const apiFallback = getMcpIntegrationApiFallback(integration);
                   const connected = connectedUrls.has(
                     compareUrl(integration.url),
                   );
@@ -515,15 +518,30 @@ export function McpIntegrationDialog({
                             {t("mcpIntegrations.connected")}
                           </button>
                         ) : setupOnly ? (
-                          <a
-                            href={integration.docsUrl}
-                            target="_blank"
-                            rel="noopener noreferrer"
-                            className="inline-flex h-8 flex-1 items-center justify-center gap-1.5 rounded-md border border-border bg-background px-2.5 text-[12px] font-medium text-foreground hover:bg-accent"
-                          >
-                            {t("mcpIntegrations.viewSetup")}
-                            <IconExternalLink className="h-3.5 w-3.5" />
-                          </a>
+                          <>
+                            {apiFallback && (
+                              <button
+                                type="button"
+                                onClick={() =>
+                                  openAgentSettings(
+                                    `secrets:${apiFallback.secretKey}`,
+                                  )
+                                }
+                                className="inline-flex h-8 flex-1 items-center justify-center gap-1.5 rounded-md bg-primary px-2.5 text-[12px] font-medium text-primary-foreground hover:bg-primary/90"
+                              >
+                                {t("mcpIntegrations.useApiToken")}
+                              </button>
+                            )}
+                            <a
+                              href={integration.docsUrl}
+                              target="_blank"
+                              rel="noopener noreferrer"
+                              className="inline-flex h-8 flex-1 items-center justify-center gap-1.5 rounded-md border border-border bg-background px-2.5 text-[12px] font-medium text-foreground hover:bg-accent"
+                            >
+                              {t("mcpIntegrations.viewSetup")}
+                              <IconExternalLink className="h-3.5 w-3.5" />
+                            </a>
+                          </>
                         ) : (
                           <button
                             type="button"