@stigmer/react 3.40.0 → 3.41.0

package/src/mcp-server/McpServerDetailView.tsx

@@ -263,9 +263,8 @@ export function McpServerDetailView({
   const handleOAuthSignIn = useCallback(async () => {
     if (!mcpServer?.metadata?.id) return;
 
-    const envKeys = Object.keys(mcpServer.spec?.env ?? {});
     try {
-      await oauth.startOAuth(mcpServer.metadata.id, activeOrg ?? org, envKeys);
+      await oauth.startOAuth(mcpServer.metadata.id, activeOrg ?? org);
       credentials.refetch();
       refetch();
     } catch {
@@ -305,9 +304,8 @@ export function McpServerDetailView({
       return;
     }
 
-    const envKeys = Object.keys(mcpServer.spec?.env ?? {});
     try {
-      await connection.connect(mcpServer.metadata.id, activeOrg ?? org, undefined, envKeys);
+      await connection.connect(mcpServer.metadata.id, activeOrg ?? org);
       // Discovery succeeded — retire the OAuth chain's stale
       // discovery-failure error so the banner doesn't outlive the state
       // it described.
@@ -330,9 +328,8 @@ export function McpServerDetailView({
         }
 
         if (mcpServer?.metadata?.id) {
-          const envKeys = Object.keys(mcpServer.spec?.env ?? {});
           const connectOrg = activeOrg ?? org;
-          await connection.connect(mcpServer.metadata.id, connectOrg, values, envKeys);
+          await connection.connect(mcpServer.metadata.id, connectOrg, values);
           refetch();
         }
 

package/src/mcp-server/McpServerPicker.tsx

@@ -428,11 +428,6 @@ export function McpServerPicker({
       (oauthStatus?.vendorApprovalStatus === VendorApprovalStatus.PENDING ||
         oauthStatus?.vendorApprovalStatus === VendorApprovalStatus.REJECTED);
 
-    // System env vars are only injected when the server declares them —
-    // the dialog and detail view pass these on every OAuth chain and
-    // bare connect; the picker must too.
-    const declaredEnvKeys = Object.keys(entry.mcpServer.spec?.env ?? {});
-
     // Scope the shared hooks' signals to the server they belong to.
     const isOwnOAuthAttempt = oauthAttemptKey === view.serverKey;
     const oauthError = isOwnOAuthAttempt ? oauth.error : null;
@@ -476,12 +471,7 @@ export function McpServerPicker({
                 // server-side. Retry bare discovery; never relaunch the
                 // popup (stigmer/stigmer#418).
                 try {
-                  await discovery.connect(
-                    serverId,
-                    connectOrg,
-                    undefined,
-                    declaredEnvKeys,
-                  );
+                  await discovery.connect(serverId, connectOrg);
                   // Discovery succeeded — retire the chain's stale
                   // failure and re-evaluate the entry so it resolves
                   // ready with the discovered tools.
@@ -494,7 +484,7 @@ export function McpServerPicker({
               }
 
               try {
-                await oauth.startOAuth(serverId, connectOrg, declaredEnvKeys);
+                await oauth.startOAuth(serverId, connectOrg);
                 setup.onServerAdded(ref);
               } catch {
                 // error state managed by oauth hook

package/src/mcp-server/McpToolSelector.tsx

@@ -178,7 +178,7 @@ export function McpToolSelector({
                     onChange={() => handleToggle(tool.name)}
                     disabled={disabled}
                     aria-describedby={descId}
-                    className="stg:mt-0.5 stg:size-3 stg:shrink-0 stg:accent-primary stg:disabled:pointer-events-none stg:disabled:opacity-50"
+                    className="stg:mt-0.5 stg:size-3 stg:shrink-0 stg:disabled:pointer-events-none stg:disabled:opacity-50"
                   />
                   <span className="stg:min-w-0 stg:flex-1">
                     <span className="stg:flex stg:items-center stg:gap-1.5">

package/src/mcp-server/useMcpServerConnect.ts

@@ -6,7 +6,6 @@ import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/
 import { ConnectInputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { connectAndWait, type EnvVarInput } from "@stigmer/sdk";
 import { useStigmer } from "../hooks.js";
-import { resolveDeclaredSystemEnvVars } from "../environment/systemEnvVars.js";
 import { toError } from "../internal/toError.js";
 
 /** Return value of {@link useMcpServerConnect}. */
@@ -22,23 +21,19 @@ export interface UseMcpServerConnectReturn {
    * survives browser transport limits. Backends without the lane fall
    * back to the blocking `connect` RPC transparently.
    *
-   * Platform system env vars (`STIGMER_SERVER_ADDRESS`,
-   * `STIGMER_API_KEY`) are injected only when the MCP server
-   * declares them in its `spec.env`. Pass `declaredEnvKeys` so the
-   * hook can determine which system vars the server actually needs.
-   * When omitted, no system vars are injected.
+   * Without `runtimeEnv`, the backend resolves the server's declared
+   * variables itself: OAuth tokens from the managed grant, the rest from
+   * the caller's personal environment. The platform's own keys are
+   * filled by the runner, never sent from here (`SYSTEM_ENV_VAR_KEYS`).
    *
-   * When `runtimeEnv` is provided, those values are merged on top
-   * (caller values win). The backend merges the result on top of
-   * the user's personal environment so saved credentials (e.g.,
-   * OAuth tokens) are still resolved.
+   * With `runtimeEnv`, the backend connects with exactly those values
+   * and resolves nothing else (stigmer/stigmer#1453), so pass it only
+   * for a one-time connect whose values the caller supplies whole.
    *
    * @param mcpServerId - System-generated ID of the MCP server (metadata.id).
    * @param org - The caller's active organization slug. Required for
    *   OAuth grant lookup and personal environment resolution.
-   * @param runtimeEnv - Optional additional environment variables.
-   * @param declaredEnvKeys - Keys from the server's `spec.env` declaration.
-   *   System vars are only injected when declared here.
+   * @param runtimeEnv - Optional one-time values for this connect.
    * @returns The updated McpServer with populated status.discovered_capabilities
    *          and status.tool_approvals.
    */
@@ -46,7 +41,6 @@ export interface UseMcpServerConnectReturn {
     mcpServerId: string,
     org: string,
     runtimeEnv?: Record<string, EnvVarInput>,
-    declaredEnvKeys?: readonly string[],
   ) => Promise<McpServer>;
   /** `true` while the connect operation is in flight (start through settle). */
   readonly isConnecting: boolean;
@@ -64,14 +58,9 @@ export interface UseMcpServerConnectReturn {
  * server's tools and resource templates, then classifies each tool's
  * approval policy via a structured-output LLM call.
  *
- * Platform system env vars (`STIGMER_SERVER_ADDRESS`,
- * `STIGMER_API_KEY`) are injected only when the target MCP server
- * declares them in `spec.env`. Pass the server's declared env keys
- * via `declaredEnvKeys` so the hook knows which system vars to
- * include. When not provided, no system vars are injected.
- *
- * Additional one-time credentials can be passed via `runtimeEnv`
- * and will override both system vars and personal env values.
+ * Saved credentials need nothing from the caller: the backend resolves
+ * them. One-time credentials ride `runtimeEnv` and replace that
+ * resolution for this connect.
  *
  * @example
  * ```tsx
@@ -80,15 +69,13 @@ export interface UseMcpServerConnectReturn {
  *
  * // Saved credentials: already in personal environment
  * async function handleConnectSaved() {
- *   const envKeys = Object.keys(mcpServer.spec?.env ?? {});
- *   await connect(mcpServer.metadata.id, undefined, envKeys);
+ *   await connect(mcpServer.metadata.id, org);
  *   refetch();
  * }
  *
  * // One-time use: pass credentials directly
  * async function handleConnectTemporary(values: Record<string, EnvVarInput>) {
- *   const envKeys = Object.keys(mcpServer.spec?.env ?? {});
- *   await connect(mcpServer.metadata.id, values, envKeys);
+ *   await connect(mcpServer.metadata.id, org, values);
  *   refetch();
  * }
  * ```
@@ -105,19 +92,13 @@ export function useMcpServerConnect(): UseMcpServerConnectReturn {
       mcpServerId: string,
       org: string,
       runtimeEnv?: Record<string, EnvVarInput>,
-      declaredEnvKeys?: readonly string[],
     ): Promise<McpServer> => {
       setIsConnecting(true);
       setError(null);
 
       try {
-        const systemEnv = declaredEnvKeys
-          ? await resolveDeclaredSystemEnvVars(stigmer, declaredEnvKeys)
-          : {};
-        const mergedEnv = { ...systemEnv, ...(runtimeEnv ?? {}) };
-
         const runtimeEnvMap: Record<string, { value: string; isSecret: boolean }> = {};
-        for (const [key, envInput] of Object.entries(mergedEnv)) {
+        for (const [key, envInput] of Object.entries(runtimeEnv ?? {})) {
           runtimeEnvMap[key] = {
             value: envInput.value,
             isSecret: envInput.isSecret ?? false,

package/src/mcp-server/useMcpServerOAuthConnect.ts

@@ -10,7 +10,6 @@ import {
   ConnectInputSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { useStigmer } from "../hooks.js";
-import { resolveDeclaredSystemEnvVars } from "../environment/systemEnvVars.js";
 import { toError } from "../internal/toError.js";
 import {
   openOAuthPopup,
@@ -81,11 +80,9 @@ export interface UseMcpServerOAuthConnectReturn {
    *
    * @param mcpServerId - System-generated ID (metadata.id) of the MCP server.
    * @param org - Organization context for token storage (caller's active org).
-   * @param declaredEnvKeys - Keys from the server's `spec.env` declaration.
-   *   System vars are only injected when declared here.
    * @returns The updated McpServer after tool discovery completes.
    */
-  readonly startOAuth: (mcpServerId: string, org: string, declaredEnvKeys?: readonly string[]) => Promise<McpServer>;
+  readonly startOAuth: (mcpServerId: string, org: string) => Promise<McpServer>;
   /** `true` while any phase of the OAuth flow is in progress. */
   readonly isInProgress: boolean;
   /** Current phase of the OAuth flow. */
@@ -182,7 +179,7 @@ export function useMcpServerOAuthConnect(): UseMcpServerOAuthConnectReturn {
   }, [advancePhase]);
 
   const startOAuth = useCallback(
-    async (mcpServerId: string, org: string, declaredEnvKeys?: readonly string[]): Promise<McpServer> => {
+    async (mcpServerId: string, org: string): Promise<McpServer> => {
       advancePhase("initiating");
       setError(null);
       setFailedPhase(null);
@@ -229,24 +226,11 @@ export function useMcpServerOAuthConnect(): UseMcpServerOAuthConnectReturn {
 
         advancePhase("connecting");
 
-        const systemEnv = declaredEnvKeys
-          ? await resolveDeclaredSystemEnvVars(stigmer, declaredEnvKeys)
-          : {};
-        const runtimeEnvMap: Record<string, { value: string; isSecret: boolean }> = {};
-        for (const [key, envInput] of Object.entries(systemEnv)) {
-          runtimeEnvMap[key] = {
-            value: envInput.value,
-            isSecret: envInput.isSecret ?? false,
-          };
-        }
-
-        const input = create(ConnectInputSchema, {
-          mcpServerId,
-          org,
-          ...(Object.keys(runtimeEnvMap).length > 0
-            ? { runtimeEnv: runtimeEnvMap }
-            : {}),
-        });
+        // No runtime env: the backend resolves the token this flow just
+        // stored from the managed grant, and every other declared variable
+        // from the caller's personal environment. A runtime env would
+        // replace that resolution whole (stigmer/stigmer#1453).
+        const input = create(ConnectInputSchema, { mcpServerId, org });
 
         // Async connect lane (stigmer/stigmer#425): startConnect + poll via
         // the SDK's shared protocol, so the discovery wait can outlive the

package/src/models/HarnessSelector.tsx

@@ -1,9 +1,7 @@
 "use client";
 
 import { useCallback, useRef, type KeyboardEvent } from "react";
-import { HARNESS_LABELS, type HarnessOption } from "./harness.js";
-
-const OPTIONS: readonly HarnessOption[] = ["native", "cursor"];
+import { HARNESS_LABELS, HARNESS_OPTIONS as OPTIONS, type HarnessOption } from "./harness.js";
 
 /** Props for {@link HarnessSelector}. */
 export interface HarnessSelectorProps {

package/src/models/ModelSelector.tsx

@@ -47,7 +47,7 @@ export interface ModelSelectorProps {
   readonly onHarnessChange?: (harness: HarnessOption) => void;
   /**
    * Restrict which harnesses appear in the dropdown.
-   * When omitted, shows all registered harnesses that have models in the registry.
+   * When omitted, shows every harness the platform runs ({@link HARNESS_OPTIONS}).
    */
   readonly availableHarnesses?: readonly HarnessOption[];
   /** Override the curated (featured) list for the current harness. */
@@ -218,12 +218,7 @@ export function ModelSelector({
   const searchRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLDivElement>(null);
 
-  const resolvedHarnesses = useMemo(() => {
-    if (availableHarnesses) return availableHarnesses;
-    // For now, show native and cursor (the two harnesses with models in the registry).
-    // Future harnesses will be added to the registry and appear here automatically.
-    return HARNESS_OPTIONS.filter((h) => h === "native" || h === "cursor");
-  }, [availableHarnesses]);
+  const resolvedHarnesses = availableHarnesses ?? HARNESS_OPTIONS;
 
   const selectedModel = (value ? getModel(value) : undefined) ?? defaultModel ?? undefined;
 

package/src/models/harness.ts

@@ -4,18 +4,33 @@ import { Harness } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
  * String literal alias for the proto {@link Harness} enum.
  *
  * Used on component props and hook options so platform builders
- * do not need to import proto enums to use the SDK.
- *
- * This union grows as new execution engines are integrated.
- * Each value must have a corresponding entry in {@link HARNESS_META}.
+ * do not need to import proto enums to use the SDK. Exactly the
+ * engines the platform runs; it grows only when the proto enum does.
+ */
+export type HarnessOption = "native" | "cursor";
+
+/**
+ * The proto {@link Harness} member for each option — the one table the
+ * option set is read from, so the SDK can never offer an engine the proto
+ * does not name (stigmer/stigmer#1143: four extra options once mapped
+ * silently to NATIVE). Listed in proto enum order.
+ */
+const HARNESS_BY_OPTION = {
+  native: Harness.NATIVE,
+  cursor: Harness.CURSOR,
+} as const satisfies Record<HarnessOption, Exclude<Harness, Harness.UNSPECIFIED>>;
+
+/**
+ * The reverse of {@link HARNESS_BY_OPTION}, keyed by every engine the proto
+ * names. Typed over the whole enum (minus UNSPECIFIED), so a member added
+ * to the proto is a compile error here until it has an option — and then
+ * in {@link HARNESS_BY_OPTION} and {@link HARNESS_META} until it has an
+ * entry in each.
  */
-export type HarnessOption =
-  | "native"
-  | "cursor"
-  | "copilot"
-  | "claude_code"
-  | "codex"
-  | "devin";
+const OPTION_BY_HARNESS: Readonly<Record<Exclude<Harness, Harness.UNSPECIFIED>, HarnessOption>> = {
+  [Harness.NATIVE]: "native",
+  [Harness.CURSOR]: "cursor",
+};
 
 /** Display metadata for a single harness. */
 export interface HarnessDisplayInfo {
@@ -34,10 +49,6 @@ export interface HarnessDisplayInfo {
 export const HARNESS_META: Readonly<Record<HarnessOption, HarnessDisplayInfo>> = {
   native: { label: "Stigmer", description: "Stigmer's native agent runtime" },
   cursor: { label: "Cursor", description: "Cursor IDE agent with codebase indexing" },
-  copilot: { label: "GitHub Copilot", description: "GitHub-native sub-agent orchestration" },
-  claude_code: { label: "Claude Agent SDK", description: "Anthropic's agent SDK with built-in tools" },
-  codex: { label: "OpenAI Codex", description: "Thread-based execution with structured output" },
-  devin: { label: "Devin", description: "Full autonomous engineer, session-based" },
 };
 
 /**
@@ -50,28 +61,24 @@ export const HARNESS_LABELS: Readonly<Record<HarnessOption, string>> = Object.fr
   Object.entries(HARNESS_META).map(([k, v]) => [k, v.label]),
 ) as Record<HarnessOption, string>;
 
-/** Ordered list of all registered harness IDs. */
-export const HARNESS_OPTIONS: readonly HarnessOption[] = [
-  "native",
-  "cursor",
-  "copilot",
-  "claude_code",
-  "codex",
-  "devin",
-];
+/** Ordered list of all registered harness IDs, in proto enum order. */
+export const HARNESS_OPTIONS: readonly HarnessOption[] = Object.keys(HARNESS_BY_OPTION) as HarnessOption[];
 
 /** Platform default — resolves to the native engine. */
 export const DEFAULT_HARNESS: HarnessOption = "native";
 
+/**
+ * Whether a string names a {@link HarnessOption} — the check for a value
+ * the SDK did not write itself (a stored preference, a URL parameter),
+ * which may name an engine this platform does not run.
+ */
+export function isHarnessOption(value: string): value is HarnessOption {
+  return Object.hasOwn(HARNESS_BY_OPTION, value);
+}
+
 /** Convert a {@link HarnessOption} string to the proto {@link Harness} enum. */
 export function toProtoHarness(h: HarnessOption): Harness {
-  switch (h) {
-    case "cursor":
-      return Harness.CURSOR;
-    case "native":
-    default:
-      return Harness.NATIVE;
-  }
+  return HARNESS_BY_OPTION[h];
 }
 
 /**
@@ -80,12 +87,7 @@ export function toProtoHarness(h: HarnessOption): Harness {
  * `UNSPECIFIED` and any unknown values map to `"native"`.
  */
 export function fromProtoHarness(h: Harness): HarnessOption {
-  switch (h) {
-    case Harness.CURSOR:
-      return "cursor";
-    case Harness.NATIVE:
-    case Harness.UNSPECIFIED:
-    default:
-      return "native";
-  }
+  // A wire value may be UNSPECIFIED, or an engine newer than this build.
+  const known: Partial<Record<Harness, HarnessOption>> = OPTION_BY_HARNESS;
+  return known[h] ?? DEFAULT_HARNESS;
 }

package/src/models/index.ts

@@ -9,7 +9,7 @@ export { ModelSelector } from "./ModelSelector.js";
 export type { ModelSelectorProps } from "./ModelSelector.js";
 export { HarnessSelector } from "./HarnessSelector.js";
 export type { HarnessSelectorProps } from "./HarnessSelector.js";
-export { DEFAULT_HARNESS, HARNESS_LABELS, HARNESS_META, HARNESS_OPTIONS, toProtoHarness, fromProtoHarness } from "./harness.js";
+export { DEFAULT_HARNESS, HARNESS_LABELS, HARNESS_META, HARNESS_OPTIONS, isHarnessOption, toProtoHarness, fromProtoHarness } from "./harness.js";
 export type { HarnessOption, HarnessDisplayInfo } from "./harness.js";
 export { FAST_SERVICE_TIER, toProtoServiceTier, fromProtoServiceTier } from "./service-tier.js";
 export type { ServiceTierOption } from "./service-tier.js";

package/src/organization/OrgPreferencesPanel.tsx

@@ -7,10 +7,19 @@ import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organizati
 import { useOrganization } from "./useOrganization.js";
 import { useUpdateOrganization } from "./useUpdateOrganization.js";
 import { useCheckPermission } from "../iam-policy/useCheckPermission.js";
+import { useServerInfo } from "../server-info.js";
 import { MemoryEnabledRow } from "../internal/MemoryEnabledRow.js";
 import { StandingContextField } from "../internal/StandingContextField.js";
 import { SpinnerIcon } from "../internal/SpinnerIcon.js";
 
+/** The memory row's copy where each member's own switch must also be on. */
+const MEMBER_CONSENT_MEMORY_HELPER_TEXT =
+  "Allow agents to remember confirmed facts about members of this organization. Each member must also turn memory on in their own account preferences; once a member has many memories, each conversation recalls their most relevant ones, shown on the execution. Changes apply immediately.";
+
+/** The memory row's copy on a server where this switch alone decides memory. */
+const ORG_ALONE_MEMORY_HELPER_TEXT =
+  "Allow agents to remember confirmed facts. On this server this switch alone decides memory; once there are many memories, each conversation recalls the most relevant ones, shown on the execution. Changes apply immediately.";
+
 /** Props for {@link OrgPreferencesPanel}. */
 export interface OrgPreferencesPanelProps {
   /** The ID of the organization whose preferences to display and edit. */
@@ -69,6 +78,15 @@ export function OrgPreferencesPanel({
     error: memoryFlagError,
   } = useUpdateOrganization();
 
+  // On a server that trusts every request, this switch alone decides memory:
+  // there is no person's switch to also turn on (the account panel says so
+  // in its place).
+  const { serverInfo } = useServerInfo();
+  const memoryHelperText =
+    serverInfo?.authenticationRequired === false
+      ? ORG_ALONE_MEMORY_HELPER_TEXT
+      : MEMBER_CONSENT_MEMORY_HELPER_TEXT;
+
   // Fail-open: OSS local mode has no IAM service, so editing stays
   // available there; cloud gets a genuine server verdict.
   const { allowed: canEdit } = useCheckPermission(
@@ -221,7 +239,7 @@ export function OrgPreferencesPanel({
         saving={isSavingMemoryFlag}
         readOnly={!canEdit}
         error={memoryFlagError}
-        helperText="Allow agents to remember confirmed facts about members of this organization. Each member must also turn memory on in their own account preferences; once a member has many memories, each conversation recalls their most relevant ones, shown on the execution. Changes apply immediately."
+        helperText={memoryHelperText}
       />
 
       {!canEdit && (

package/src/plugin/useMcpServerReadiness.ts

@@ -109,14 +109,14 @@ export function useMcpServerReadiness(
     oauth.clearError();
     // A sign-in that fails leaves the row on "Sign in" with the reason; one
     // that lands refetches so the row says "Signed in" from the grant.
-    void oauth.startOAuth(id, org, declaredVariables).then(
+    void oauth.startOAuth(id, org).then(
       () => {
         refetch();
         onSignedIn?.(id);
       },
       () => undefined,
     );
-  }, [kind, mcpServer, org, oauth.clearError, oauth.startOAuth, declaredVariables, refetch, onSignedIn]);
+  }, [kind, mcpServer, org, oauth.clearError, oauth.startOAuth, refetch, onSignedIn]);
 
   const error = useMemo(() => {
     if (readError) return readError;

package/src/provider-standing/ProviderStandingConsole.tsx

@@ -110,7 +110,7 @@ export function ProviderStandingConsole({ className }: ProviderStandingConsolePr
           completed a pass since this deployment came up.
         </p>
       ) : (
-        <ul className="stg:m-0 stg:grid stg:list-none stg:gap-2 stg:p-0 sm:stg:grid-cols-2">
+        <ul className="stg:m-0 stg:grid stg:list-none stg:gap-2 stg:p-0 stg:sm:grid-cols-2">
           {providers.map((entry) => (
             <StandingCard key={entry.provider} entry={entry} />
           ))}

package/src/provider.tsx

@@ -15,6 +15,7 @@ import { StigmerContext } from "./context.js";
 import { DeploymentModeContext } from "./deployment-mode.js";
 import { ExecutionTargetContext } from "./execution-target-context.js";
 import { ApprovalDefaultsContext } from "./approval-defaults-context.js";
+import { PublicBaseUrlContext } from "./public-base-url-context.js";
 import type { ApprovalDefaults } from "./approval-defaults-context.js";
 import type { ExecutionTargetOption } from "./session/execution-target.js";
 import type { RunnerAdapter } from "./runner-adapter.js";
@@ -121,6 +122,32 @@ export interface StigmerProviderProps {
    * ```
    */
   readonly approvalDefaults?: ApprovalDefaults;
+  /**
+   * The address the Stigmer API is reached at from outside this page, for
+   * the URLs the SDK shows a user to copy (the Slack and WhatsApp webhook
+   * URLs a channel app registers, and the platform client snippet in the
+   * Share dialog). A session's MCP servers get their
+   * `STIGMER_SERVER_ADDRESS` from the platform, never from this value.
+   *
+   * Omit it when the client's `baseUrl` is absolute: that address is used,
+   * exactly as before. Pass it when the client talks to the server through
+   * a relative `baseUrl` (a same-origin proxy), because the page's own
+   * origin need not be where Slack, Meta, a backend or a remote MCP server
+   * can reach the API. Without it, the copy surfaces say they do not know
+   * the server's public address and offer nothing to copy. Only an
+   * absolute `http(s)` URL is used.
+   *
+   * @example
+   * ```tsx
+   * // The browser reaches the API through the page's own origin
+   * const client = new Stigmer({ baseUrl: "/", getAccessToken });
+   *
+   * <StigmerProvider client={client} publicBaseUrl="https://api.example.com">
+   *   <App />
+   * </StigmerProvider>
+   * ```
+   */
+  readonly publicBaseUrl?: string;
   /**
    * Built-in theme preset to apply.
    *
@@ -288,6 +315,7 @@ export function StigmerProvider({
   executionTarget,
   runnerAdapter,
   approvalDefaults,
+  publicBaseUrl,
   preset,
   className,
   colorMode = "light",
@@ -310,32 +338,34 @@ export function StigmerProvider({
         <ExecutionTargetContext.Provider value={executionTarget}>
           <ApprovalDefaultsContext.Provider value={approvalDefaults}>
             <RunnerAdapterContext.Provider value={runnerAdapter ?? null}>
-              <ColorModeContext.Provider value={resolvedMode}>
-                <ModelRegistryContext.Provider value={registryState}>
-                  <TaskKindRegistryContext.Provider value={taskKindRegistryState}>
-                    <ReviewRendererContext.Provider value={reviewRenderers ?? EMPTY_REVIEW_RENDERERS}>
-                      <PortalContainerContext.Provider value={portalContainer}>
-                        {/*
-                          The in-tree scoping container. `data-stgm-root` is a
-                          stable public selector — the documented seam for hosts
-                          to style THIS element only (e.g. the fixed-height
-                          embedding recipe, #260). It must never be mirrored
-                          onto the portal container, whose own `data-stgm-portal`
-                          marker keeps host in-tree-only CSS away from the
-                          off-tree element.
-                        */}
-                        <div
-                          className={scope.className}
-                          data-stgm-root=""
-                          data-stgm-color-mode={scope.colorMode}
-                        >
-                          {children}
-                        </div>
-                      </PortalContainerContext.Provider>
-                    </ReviewRendererContext.Provider>
-                  </TaskKindRegistryContext.Provider>
-                </ModelRegistryContext.Provider>
-              </ColorModeContext.Provider>
+              <PublicBaseUrlContext.Provider value={publicBaseUrl}>
+                <ColorModeContext.Provider value={resolvedMode}>
+                  <ModelRegistryContext.Provider value={registryState}>
+                    <TaskKindRegistryContext.Provider value={taskKindRegistryState}>
+                      <ReviewRendererContext.Provider value={reviewRenderers ?? EMPTY_REVIEW_RENDERERS}>
+                        <PortalContainerContext.Provider value={portalContainer}>
+                          {/*
+                            The in-tree scoping container. `data-stgm-root` is a
+                            stable public selector — the documented seam for hosts
+                            to style THIS element only (e.g. the fixed-height
+                            embedding recipe, #260). It must never be mirrored
+                            onto the portal container, whose own `data-stgm-portal`
+                            marker keeps host in-tree-only CSS away from the
+                            off-tree element.
+                          */}
+                          <div
+                            className={scope.className}
+                            data-stgm-root=""
+                            data-stgm-color-mode={scope.colorMode}
+                          >
+                            {children}
+                          </div>
+                        </PortalContainerContext.Provider>
+                      </ReviewRendererContext.Provider>
+                    </TaskKindRegistryContext.Provider>
+                  </ModelRegistryContext.Provider>
+                </ColorModeContext.Provider>
+              </PublicBaseUrlContext.Provider>
             </RunnerAdapterContext.Provider>
           </ApprovalDefaultsContext.Provider>
         </ExecutionTargetContext.Provider>