@stigmer/react 0.0.79 → 0.0.80

package/src/library/parse-resource-yaml.ts

@@ -9,8 +9,6 @@ import type {
   StdioServerConfigInput,
   HttpServerConfigInput,
   ToolApprovalPolicyInput,
-  EnvSpecInput,
-  EnvVarInput,
   ResourceRef,
 } from "@stigmer/sdk";
 import type { StigmerResourceKind } from "./detect-stigmer-resource";
@@ -47,7 +45,7 @@ export type ParsedResource =
  *
  * Handles the conversion from proto-style snake_case YAML field names to
  * the camelCase TypeScript SDK input types, including nested structures
- * like `mcp_server_usages`, `sub_agents`, and `env_spec`.
+ * like `mcp_server_usages`, `sub_agents`, and `env`.
  *
  * The `org` parameter **always overrides** `metadata.org` in the YAML.
  * This matches the UX intent of "Apply to [my-org]" — the user explicitly
@@ -207,7 +205,7 @@ function buildAgentInput(
     ...optionalField("mcpServerUsages", extractMcpServerUsages(spec)),
     ...optionalField("skillRefs", extractResourceRefs(spec, "skill_refs")),
     ...optionalField("subAgents", extractSubAgents(spec)),
-    ...optionalField("envSpec", extractEnvSpec(spec)),
+    ...optionalField("env", extractEnv(spec)),
   };
 }
 
@@ -333,7 +331,7 @@ function buildMcpServerInput(
       "pinnedToolApprovals",
       extractToolApprovalPolicy,
     ),
-    ...optionalField("envSpec", extractEnvSpec(spec)),
+    ...optionalField("env", extractEnv(spec)),
   };
 }
 
@@ -389,35 +387,46 @@ function extractToolApprovalPolicy(
 // Shared extractors
 // ---------------------------------------------------------------------------
 
-function extractEnvSpec(
+function extractEnv(
   spec: Record<string, unknown>,
-): EnvSpecInput | undefined {
-  const envSpecRaw = spec.env_spec ?? spec.envSpec;
-  if (!isPlainObject(envSpecRaw)) return undefined;
+): Record<string, { isSecret?: boolean; description?: string; optional?: boolean }> | undefined {
+  // Support both new flat `env` and legacy nested `env_spec.data` / `envSpec.data`.
+  let envMap: Record<string, unknown> | undefined;
+
+  const envRaw = spec.env;
+  if (isPlainObject(envRaw)) {
+    envMap = envRaw;
+  } else {
+    const envSpecRaw = spec.env_spec ?? spec.envSpec;
+    if (isPlainObject(envSpecRaw)) {
+      const data = envSpecRaw.data ?? envSpecRaw.variables;
+      if (isPlainObject(data)) {
+        envMap = data;
+      }
+    }
+  }
 
-  // Proto uses `data` as the map field name; SDK uses `variables`.
-  const data = envSpecRaw.data ?? envSpecRaw.variables;
-  if (!isPlainObject(data)) return undefined;
+  if (!envMap) return undefined;
 
-  const variables: Record<string, EnvVarInput> = {};
+  const result: Record<string, { isSecret?: boolean; description?: string; optional?: boolean }> = {};
   let hasEntries = false;
 
-  for (const [key, val] of Object.entries(data)) {
+  for (const [key, val] of Object.entries(envMap)) {
     if (!isPlainObject(val)) continue;
 
-    const value = typeof val.value === "string" ? val.value : "";
     const isSecret = val.is_secret ?? val.isSecret;
     const description = val.description;
+    const optional = val.optional;
 
-    variables[key] = {
-      value,
+    result[key] = {
       ...(typeof isSecret === "boolean" && { isSecret }),
       ...(typeof description === "string" && { description }),
+      ...(typeof optional === "boolean" && { optional }),
     };
     hasEntries = true;
   }
 
-  return hasEntries ? { variables } : undefined;
+  return hasEntries ? result : undefined;
 }
 
 function extractResourceRef(raw: Record<string, unknown>): ResourceRef {

package/src/library/serialize-resource-yaml.ts

@@ -15,7 +15,7 @@ import type {
   ToolApprovalPolicy,
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import type { EnvironmentSpec } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 
 /**
  * Serializes a proto `Agent` into the canonical Stigmer YAML format.
@@ -147,10 +147,10 @@ function buildAgentSpec(
     result.sub_agents = spec.subAgents.map(serializeSubAgent);
   }
 
-  if (spec.envSpec) {
-    const envSpec = serializeEnvSpec(spec.envSpec);
-    if (envSpec) {
-      result.env_spec = envSpec;
+  if (hasEntries(spec.env)) {
+    const env = serializeEnv(spec.env);
+    if (env) {
+      result.env = env;
     }
   }
 
@@ -271,10 +271,10 @@ function buildMcpServerSpec(
       spec.pinnedToolApprovals.map(serializeToolApprovalPolicy);
   }
 
-  if (spec.envSpec) {
-    const envSpec = serializeEnvSpec(spec.envSpec);
-    if (envSpec) {
-      result.env_spec = envSpec;
+  if (hasEntries(spec.env)) {
+    const env = serializeEnv(spec.env);
+    if (env) {
+      result.env = env;
     }
   }
 
@@ -361,20 +361,17 @@ function serializeResourceRef(
   return result;
 }
 
-function serializeEnvSpec(
-  envSpec: EnvironmentSpec,
-): Record<string, unknown> | undefined {
-  if (!hasEntries(envSpec.data)) return undefined;
+function serializeEnv(
+  env: { [key: string]: EnvVarDeclaration },
+): Record<string, Record<string, unknown>> | undefined {
+  const keys = Object.keys(env);
+  if (keys.length === 0) return undefined;
 
-  const data: Record<string, Record<string, unknown>> = {};
+  const result: Record<string, Record<string, unknown>> = {};
 
-  for (const [key, val] of Object.entries(envSpec.data)) {
+  for (const [key, val] of Object.entries(env)) {
     const entry: Record<string, unknown> = {};
 
-    if (val.value) {
-      entry.value = val.value;
-    }
-
     if (val.isSecret) {
       entry.is_secret = val.isSecret;
     }
@@ -383,17 +380,13 @@ function serializeEnvSpec(
       entry.description = val.description;
     }
 
-    data[key] = entry;
-  }
-
-  const result: Record<string, unknown> = {};
+    if (val.optional) {
+      entry.optional = val.optional;
+    }
 
-  if (envSpec.description) {
-    result.description = envSpec.description;
+    result[key] = entry;
   }
 
-  result.data = data;
-
   return result;
 }
 

package/src/mcp-server/McpServerDetailView.tsx

@@ -10,7 +10,7 @@ import type {
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
 import type { ToolApprovalPolicy, McpServerSpec } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import { ValidationState } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
-import type { EnvironmentValue } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { useMcpServer } from "./useMcpServer";
 import { useMcpServerConnect } from "./useMcpServerConnect";
@@ -73,6 +73,13 @@ export interface McpServerDetailViewProps {
   readonly credentialPoolValues?: (
     key: string,
   ) => import("@stigmer/sdk").EnvVarInput | undefined;
+  /**
+   * The authenticated user's active organization slug.
+   * Used for OAuth token storage — tokens are stored in the user's personal
+   * environment within this org, not the MCP server's org.
+   * When omitted, falls back to the `org` prop (MCP server's org).
+   */
+  readonly activeOrg?: string;
   /** Additional CSS classes for the root container. */
   readonly className?: string;
 }
@@ -110,6 +117,7 @@ export function McpServerDetailView({
   defaultCapabilityTab = "tools",
   defaultShowCredentialForm = false,
   credentialPoolValues,
+  activeOrg,
   className,
 }: McpServerDetailViewProps) {
   const { mcpServer, isLoading, error, refetch } = useMcpServer(org, slug);
@@ -133,7 +141,7 @@ export function McpServerDetailView({
     if (!mcpServer?.metadata?.id) return;
 
     try {
-      await oauth.startOAuth(mcpServer.metadata.id, org);
+      await oauth.startOAuth(mcpServer.metadata.id, activeOrg ?? org);
       credentials.refetch();
       refetch();
     } catch {
@@ -258,9 +266,9 @@ export function McpServerDetailView({
         <ServerConfigSection serverType={spec.serverType} />
       )}
 
-      {spec?.envSpec && Object.keys(spec.envSpec.data).length > 0 && (
-        <EnvSpecSection
-          data={spec.envSpec.data}
+      {spec?.env && Object.keys(spec.env).length > 0 && (
+        <EnvSection
+          data={spec.env}
           oauthTargetEnvVar={credentials.oauthTargetEnvVar}
         />
       )}
@@ -278,6 +286,7 @@ export function McpServerDetailView({
           oauthPhase={oauth.phase}
           authMode={credentials.authMode}
           isOAuthConnected={credentials.isOAuthConnected}
+          accessTokenExpiresAt={credentials.accessTokenExpiresAt}
           tokenLifetimeHint={credentials.tokenLifetimeHint}
         />
 
@@ -346,6 +355,7 @@ function ConnectBar({
   oauthPhase,
   authMode,
   isOAuthConnected,
+  accessTokenExpiresAt,
   tokenLifetimeHint,
 }: {
   readonly isConnecting: boolean;
@@ -359,6 +369,7 @@ function ConnectBar({
   readonly oauthPhase: OAuthConnectPhase;
   readonly authMode: "manual" | "oauth";
   readonly isOAuthConnected: boolean;
+  readonly accessTokenExpiresAt: bigint;
   readonly tokenLifetimeHint: string | null;
 }) {
   const isOAuthBusy =
@@ -384,6 +395,8 @@ function ConnectBar({
 
   const statusText = (() => {
     if (authMode === "oauth" && isOAuthConnected) {
+      const expiryLabel = formatTokenExpiry(accessTokenExpiresAt);
+      if (expiryLabel) return `Tokens refresh automatically \u00B7 ${expiryLabel}`;
       const hint = tokenLifetimeHint && tokenLifetimeHint !== "never"
         ? ` \u00B7 Session lasts ~${tokenLifetimeHint}`
         : "";
@@ -480,6 +493,20 @@ function formatConnectionSummary(toolCount: number, policyCount: number): string
   return `${toolLabel}, ${policyLabel}`;
 }
 
+function formatTokenExpiry(expiresAtSeconds: bigint): string | null {
+  if (expiresAtSeconds === BigInt(0)) return null;
+  const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+  const remainingSeconds = expiresAtSeconds - nowSeconds;
+  if (remainingSeconds <= BigInt(0)) return "Token expired";
+  const minutes = Number(remainingSeconds / BigInt(60));
+  if (minutes < 1) return "Expires in <1 min";
+  if (minutes < 60) return `Expires in ${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `Expires in ${hours}h ${minutes % 60}m`;
+  const days = Math.floor(hours / 24);
+  return `Expires in ${days}d`;
+}
+
 // ---------------------------------------------------------------------------
 // Internal section components
 // ---------------------------------------------------------------------------
@@ -760,11 +787,11 @@ function ResourceTemplatesList({
   );
 }
 
-function EnvSpecSection({
+function EnvSection({
   data,
   oauthTargetEnvVar,
 }: {
-  readonly data: { [key: string]: EnvironmentValue };
+  readonly data: { [key: string]: EnvVarDeclaration };
   readonly oauthTargetEnvVar: string | null;
 }) {
   const entries = Object.entries(data).sort(([a], [b]) =>
@@ -789,6 +816,11 @@ function EnvSpecSection({
                   oauth
                 </span>
               )}
+              {env.optional && (
+                <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground/70">
+                  optional
+                </span>
+              )}
               {env.description && (
                 <span className="text-xs text-muted-foreground">
                   {env.description}

package/src/mcp-server/McpServerPicker.tsx

@@ -155,6 +155,13 @@ export interface McpServerPickerProps {
    * pre-populated.
    */
   readonly poolValues?: (key: string) => EnvVarInput | undefined;
+  /**
+   * The authenticated user's active organization slug.
+   * Used for OAuth token storage — tokens are stored in the user's personal
+   * environment within this org, not the MCP server's org.
+   * When omitted, falls back to the `org` prop.
+   */
+  readonly activeOrg?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -250,6 +257,7 @@ export function McpServerPicker({
   setup,
   initialServerKey,
   poolValues,
+  activeOrg,
 }: McpServerPickerProps) {
   const instanceId = useId();
   const listId = `${instanceId}-list`;
@@ -408,7 +416,7 @@ export function McpServerPicker({
           onSignIn: async () => {
             if (!entry.mcpServer.metadata?.id) return;
             try {
-              await oauth.startOAuth(entry.mcpServer.metadata.id, org);
+              await oauth.startOAuth(entry.mcpServer.metadata.id, activeOrg ?? org);
               setup.onServerAdded(ref);
             } catch {
               // error state managed by oauth hook

package/src/mcp-server/index.ts

@@ -19,6 +19,9 @@ export type {
 export { useMcpServer } from "./useMcpServer";
 export type { UseMcpServerReturn } from "./useMcpServer";
 
+export { useOAuthGrantStatus } from "./useOAuthGrantStatus";
+export type { UseOAuthGrantStatusReturn } from "./useOAuthGrantStatus";
+
 export { McpServerPicker } from "./McpServerPicker";
 export type {
   McpServerPickerProps,

package/src/mcp-server/mcpServerSetupReducer.ts

@@ -35,15 +35,15 @@ export function toServerKey(ref: ResourceRef): string {
  *
  * Phases:
  * - `"loading"` — Fetching the full `McpServer` resource (spec + status).
- * - `"needsSetup"` — The server has an `env_spec` with variables missing
- *   from the user's personal environment. The UI should present a
- *   credential collection form.
+ * - `"needsSetup"` — The server has `env` declarations with variables
+ *   missing from the user's personal environment. The UI should present
+ *   a credential collection form.
  * - `"submitting"` — Environment variables are being persisted (save path)
  *   or collected (one-time path). The UI should show a loading indicator
  *   on the submit button.
  * - `"ready"` — The server is fully configured and ready for session
  *   creation. Carries the effective `enabledTools` list. Covers both
- *   the "no env_spec needed" and "env vars resolved" cases.
+ *   the "no env needed" and "env vars resolved" cases.
  */
 export type McpServerSetupPhase =
   | {

package/src/mcp-server/useMcpServerCredentials.ts

@@ -4,9 +4,10 @@ import { useCallback, useMemo } from "react";
 import type { EnvVarInput } from "@stigmer/sdk";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { usePersonalEnvironment } from "../environment/usePersonalEnvironment";
-import { diffEnvSpec } from "../environment/diffEnvSpec";
+import { diffEnv } from "../environment/diffEnv";
 import { SYSTEM_ENV_VAR_KEYS } from "../environment/systemEnvVars";
 import type { EnvVarFormVariable } from "../environment/EnvVarForm";
+import { useOAuthGrantStatus } from "./useOAuthGrantStatus";
 
 /**
  * Credential acquisition mode for an MCP server.
@@ -34,37 +35,50 @@ export interface UseMcpServerCredentialsReturn {
    */
   readonly oauthTargetEnvVar: string | null;
   /**
-   * `true` when the OAuth-managed env var exists in the personal
-   * environment. Always `false` when `authMode` is `"manual"`.
+   * `true` when the user has an active OAuth grant for this server.
+   * Derived from the `getOAuthGrantStatus` API, not from personal
+   * environment key presence. Always `false` when `authMode` is `"manual"`.
    */
   readonly isOAuthConnected: boolean;
+  /**
+   * When the OAuth access token expires (Unix timestamp seconds).
+   * `BigInt(0)` when no grant exists, `authMode` is `"manual"`, or the token
+   * does not expire. Useful for showing actual expiry in the UI.
+   */
+  readonly accessTokenExpiresAt: bigint;
   /**
    * Informational hint about expected token lifetime, or `null`.
    * Sourced from `spec.auth.token_lifetime_hint`.
    */
   readonly tokenLifetimeHint: string | null;
   /**
-   * Variables required by the MCP server that are missing from the
-   * user's personal environment. Empty when all variables are present
-   * or the server has no `env_spec`.
+   * Required variables (non-optional) missing from the user's personal
+   * environment. Empty when all required variables are present, the
+   * server has no `env` declarations, or all declarations are optional.
    *
    * When `authMode` is `"oauth"`, the OAuth-managed `target_env_var`
    * is excluded from this list — it is acquired via the OAuth flow,
-   * not via a manual form. Only additional non-OAuth vars appear here.
+   * not via a manual form. Only additional non-OAuth required vars
+   * appear here.
+   *
+   * Optional env vars are never included — they are discoverable in
+   * the read-only EnvSection but do not block connect.
    *
    * Suitable as direct input to {@link EnvVarForm}.
    */
   readonly missingVariables: EnvVarFormVariable[];
   /**
-   * `true` when all required credentials are available — both
-   * OAuth-managed and manual variables. For OAuth servers this means
-   * the OAuth token is in the personal env AND any additional manual
-   * vars are also present.
+   * `true` when all required (non-optional) credentials are available
+   * — both OAuth-managed and manual variables. For OAuth servers this
+   * means the OAuth grant is connected AND any additional required
+   * manual vars are present in the personal environment.
+   *
+   * Servers whose env vars are all optional are always ready.
    */
   readonly isReady: boolean;
-  /** `true` while the personal environment is being fetched. */
+  /** `true` while the personal environment or grant status is being fetched. */
   readonly isLoading: boolean;
-  /** Error from the personal environment fetch, or `null`. */
+  /** Error from the personal environment or grant status fetch, or `null`. */
   readonly error: Error | null;
   /**
    * Save the provided credentials to the user's personal environment.
@@ -81,7 +95,7 @@ export interface UseMcpServerCredentialsReturn {
 
 /**
  * Checks the user's personal environment against an MCP server's
- * `env_spec` and provides a mechanism to save missing credentials.
+ * `env` declarations and provides a mechanism to save missing credentials.
  *
  * Designed for the discovery flow on the MCP server detail page:
  * before triggering discovery, the UI needs to ensure all required
@@ -90,10 +104,12 @@ export interface UseMcpServerCredentialsReturn {
  * them.
  *
  * **Auth-mode-aware**: when `spec.auth` is configured, the hook
- * identifies the OAuth-managed variable (`target_env_var`) and
- * excludes it from `missingVariables` — that variable is acquired
- * via {@link useMcpServerOAuthConnect}, not a manual form. Additional
- * non-OAuth vars still appear in `missingVariables` (mixed mode).
+ * composes {@link useOAuthGrantStatus} to determine whether the
+ * OAuth-managed variable (`target_env_var`) is connected via an
+ * active grant. The OAuth variable is excluded from `missingVariables`
+ * — it is acquired via {@link useMcpServerOAuthConnect}, not a manual
+ * form. Additional non-OAuth vars still appear in `missingVariables`
+ * (mixed mode).
  *
  * Unlike {@link useMcpServerSetup} which manages multi-server setup
  * for session creation, this hook is scoped to a single server and
@@ -134,32 +150,43 @@ export function useMcpServerCredentials(
   const oauthTargetEnvVar = auth?.targetEnvVar || null;
   const tokenLifetimeHint = auth?.tokenLifetimeHint || null;
 
+  const grantStatus = useOAuthGrantStatus(
+    authMode === "oauth" ? (mcpServer?.metadata?.id ?? null) : null,
+    authMode === "oauth" ? org : null,
+  );
+
+  const isOAuthConnected = authMode === "oauth" && grantStatus.connected;
+
   const existingKeys = useMemo(
     () => new Set(Object.keys(personalEnv.environment?.spec?.data ?? {})),
     [personalEnv.environment],
   );
 
-  const isOAuthConnected = authMode === "oauth"
-    && oauthTargetEnvVar !== null
-    && existingKeys.has(oauthTargetEnvVar);
-
   const allMissingVariables = useMemo(() => {
     if (!mcpServer) return [];
-    const envSpecData = mcpServer.spec?.envSpec?.data;
-    if (!envSpecData || Object.keys(envSpecData).length === 0) return [];
+    const envDeclarations = mcpServer.spec?.env;
+    if (!envDeclarations || Object.keys(envDeclarations).length === 0) return [];
 
-    return diffEnvSpec(envSpecData, existingKeys).filter(
+    return diffEnv(envDeclarations, existingKeys).filter(
       (v) => !SYSTEM_ENV_VAR_KEYS.has(v.key),
     );
   }, [mcpServer, existingKeys]);
 
+  const requiredMissing = useMemo(
+    () => allMissingVariables.filter((v) => !v.optional),
+    [allMissingVariables],
+  );
+
   const missingVariables = useMemo(() => {
-    if (!oauthTargetEnvVar) return allMissingVariables;
-    return allMissingVariables.filter((v) => v.key !== oauthTargetEnvVar);
-  }, [allMissingVariables, oauthTargetEnvVar]);
+    if (!oauthTargetEnvVar) return requiredMissing;
+    return requiredMissing.filter((v) => v.key !== oauthTargetEnvVar);
+  }, [requiredMissing, oauthTargetEnvVar]);
 
   const isReady =
-    !personalEnv.isLoading && allMissingVariables.length === 0;
+    !personalEnv.isLoading &&
+    !grantStatus.isLoading &&
+    missingVariables.length === 0 &&
+    (authMode === "manual" || isOAuthConnected);
 
   const saveCredentials = useCallback(
     async (values: Record<string, EnvVarInput>): Promise<void> => {
@@ -169,17 +196,23 @@ export function useMcpServerCredentials(
     [personalEnv],
   );
 
+  const refetch = useCallback(() => {
+    personalEnv.refetch();
+    grantStatus.refetch();
+  }, [personalEnv, grantStatus]);
+
   return {
     authMode,
     oauthTargetEnvVar,
     isOAuthConnected,
+    accessTokenExpiresAt: grantStatus.accessTokenExpiresAt,
     tokenLifetimeHint,
     missingVariables,
     isReady,
-    isLoading: personalEnv.isLoading,
-    error: personalEnv.error,
+    isLoading: personalEnv.isLoading || grantStatus.isLoading,
+    error: personalEnv.error ?? grantStatus.error,
     saveCredentials,
     isSaving: personalEnv.isMutating,
-    refetch: personalEnv.refetch,
+    refetch,
   };
 }