feat(copilot): save secret card descriptions

Author: Sg312

apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/special-tags/special-tags.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { createElement, lazy, Suspense, useEffect, useMemo, useState } from 'react'
+import { createElement, lazy, Suspense, useCallback, useEffect, useMemo, useState } from 'react'
 import {
   ArrowRight,
   Check,
@@ -61,7 +61,11 @@ import type {
 import { useServiceAccountConnectTarget } from '@/app/workspace/[workspaceId]/integrations/components/connect-service-account-modal/use-service-account-connect'
 import { useWorkspaceHostContext } from '@/app/workspace/[workspaceId]/providers/workspace-host-provider'
 import { useUserPermissionsContext } from '@/app/workspace/[workspaceId]/providers/workspace-permissions-provider'
-import { useWorkspaceCredential } from '@/hooks/queries/credentials'
+import {
+  useUpdateWorkspaceCredential,
+  useWorkspaceCredential,
+  useWorkspaceCredentials,
+} from '@/hooks/queries/credentials'
 import {
   usePersonalEnvironment,
   useSavePersonalEnvironment,
@@ -137,6 +141,12 @@ export interface CredentialItemData {
   name?: string
   /** Where a secret_input value is persisted. Defaults to "workspace". */
   scope?: SecretInputScope
+  /**
+   * What the secret is for (secret_input, workspace scope only), written by the
+   * agent that asked for it. Never shown or editable in the card — it exists so
+   * the saved secret carries its purpose into workspace settings.
+   */
+  description?: string
   /**
    * Existing credential to reconnect in place (service_account only). Present =
    * rotate the secret on this credential; absent = create a new one.
@@ -1751,6 +1761,63 @@ interface CredentialControlProps {
   onConnected?: () => void
 }
 
+/**
+ * Attaches the agent-authored descriptions to workspace secrets once their values
+ * are saved, reusing the credential update endpoint the secrets settings page
+ * calls. It runs after the value write because that write is what mints the
+ * credential row a description hangs on, and it is best-effort: the value is the
+ * point of the card, so a failed note never fails the save. Personal rows are
+ * skipped — their credential rows are per-workspace mirrors of one user-global
+ * secret, so no single row can own a description.
+ */
+function useWorkspaceSecretDescriptions(items: CredentialItemData[]) {
+  const { workspaceId } = useParams<{ workspaceId: string }>()
+  const describedByName = useMemo(() => {
+    const entries = new Map<string, string>()
+    for (const item of items) {
+      if (item.type !== 'secret_input' || item.scope === 'personal') continue
+      const name = item.name?.trim()
+      const description = item.description?.trim()
+      if (name && description) entries.set(name, description)
+    }
+    return entries
+  }, [items])
+
+  const credentialsQuery = useWorkspaceCredentials({
+    workspaceId,
+    type: 'env_workspace',
+    enabled: describedByName.size > 0,
+  })
+  const updateCredential = useUpdateWorkspaceCredential()
+  const refetchCredentials = credentialsQuery.refetch
+
+  return useCallback(
+    async (savedNames: string[]) => {
+      const pending = savedNames.filter((name) => describedByName.has(name))
+      if (pending.length === 0) return
+
+      try {
+        const { data } = await refetchCredentials()
+        const idByEnvKey = new Map((data ?? []).map((row) => [row.envKey, row.id]))
+        await Promise.all(
+          pending.map(async (name) => {
+            const credentialId = idByEnvKey.get(name)
+            if (!credentialId) return
+            await updateCredential.mutateAsync({
+              credentialId,
+              description: describedByName.get(name),
+            })
+          })
+        )
+      } catch {
+        // Swallowed deliberately: the secret is stored, and the card must not
+        // report failure over a missing note.
+      }
+    },
+    [describedByName, refetchCredentials, updateCredential.mutateAsync]
+  )
+}
+
 function SecretInputDisplay({ data, divided = false, onSaved }: CredentialControlProps) {
   const { workspaceId } = useParams<{ workspaceId: string }>()
   const secretName = (data.name ?? '').trim()
@@ -1765,6 +1832,7 @@ function SecretInputDisplay({ data, divided = false, onSaved }: CredentialContro
   const personalQuery = usePersonalEnvironment()
   const personalEnv = personalQuery.data
   const { canEdit } = useUserPermissionsContext()
+  const attachDescriptions = useWorkspaceSecretDescriptions(useMemo(() => [data], [data]))
 
   // Setting a workspace var needs write/admin (same gate as the secrets manager);
   // personal vars are the user's own, so any member may set them.
@@ -1790,6 +1858,7 @@ function SecretInputDisplay({ data, divided = false, onSaved }: CredentialContro
         await savePersonal.mutateAsync({ variables: merged })
       } else {
         await upsertWorkspace.mutateAsync({ workspaceId, variables: { [secretName]: value } })
+        await attachDescriptions([secretName])
       }
       setValue('')
       setSaved(true)
@@ -2361,6 +2430,7 @@ function CredentialInputCard({
   const upsertWorkspace = useUpsertWorkspaceEnvironment()
   const savePersonal = useSavePersonalEnvironment()
   const personalQuery = usePersonalEnvironment()
+  const attachDescriptions = useWorkspaceSecretDescriptions(data)
   const [secretDrafts, setSecretDrafts] = useState<Record<number, string>>({})
   const [savedSecretRows, setSavedSecretRows] = useState<Set<number>>(() => new Set())
   const [connectedIntegrationRows, setConnectedIntegrationRows] = useState<Set<number>>(
@@ -2519,6 +2589,8 @@ function CredentialInputCard({
       return false
     }
 
+    await attachDescriptions(Object.keys(workspaceVariables))
+
     const nextSavedSecretRows = new Set(savedSecretRows)
     for (const index of enteredSecretIndexes) nextSavedSecretRows.add(index)
     setSavedSecretRows(nextSavedSecretRows)

apps/sim/lib/copilot/generated/tool-catalog-v1.ts

@@ -4761,7 +4761,7 @@ export const SetEnvironmentVariables: ToolCatalogEntry = {
             description: {
               type: 'string',
               description:
-                'What the variable is for, as one short phrase a teammate reads at a glance — aim for under 80 characters, like "Stripe live key for the billing workflow". Not a sentence, and never a restatement of the name. Workspace scope only; sending it with scope personal is rejected, since a personal secret has no teammates to inform. Omit it on an existing variable to leave its current description untouched; send an empty string to clear one.',
+                'What the variable is for, in one short phrase — aim for under 80 characters, like "Stripe live key for the billing workflow". Not a sentence, and never a restatement of the name. Workspace scope only; sending it with scope personal is rejected. Omit it on an existing variable to leave its current description untouched; send an empty string to clear one.',
             },
             name: { type: 'string', description: 'Variable name' },
             value: { type: 'string', description: 'Variable value' },

apps/sim/lib/copilot/generated/tool-schemas-v1.ts

@@ -4602,7 +4602,7 @@ export const TOOL_RUNTIME_SCHEMAS: Record<string, ToolRuntimeSchemaEntry> = {
               description: {
                 type: 'string',
                 description:
-                  'What the variable is for, as one short phrase a teammate reads at a glance — aim for under 80 characters, like "Stripe live key for the billing workflow". Not a sentence, and never a restatement of the name. Workspace scope only; sending it with scope personal is rejected, since a personal secret has no teammates to inform. Omit it on an existing variable to leave its current description untouched; send an empty string to clear one.',
+                  'What the variable is for, in one short phrase — aim for under 80 characters, like "Stripe live key for the billing workflow". Not a sentence, and never a restatement of the name. Workspace scope only; sending it with scope personal is rejected. Omit it on an existing variable to leave its current description untouched; send an empty string to clear one.',
               },
               name: {
                 type: 'string',

apps/sim/lib/copilot/tools/server/user/set-environment-variables.ts

@@ -130,10 +130,10 @@ export const setEnvironmentVariablesServerTool: BaseServerTool<
 
     const normalized = normalizeVariables(variables || {})
     const descriptions = normalizeDescriptions(variables || {})
-    // Rejected rather than dropped, matching the secrets domain: an `env_personal`
-    // row is a per-workspace mirror of one user-global secret, so a description
-    // written there would exist in this workspace alone — and a personal secret
-    // has no teammates to inform.
+    // Rejected rather than dropped, matching `PUT /api/v2/secrets` and the domain
+    // layer: a personal secret's value is user-global, but its credential rows are
+    // per-workspace mirrors, so there is no single row to hold its description —
+    // one written here would exist in this workspace alone.
     if (scope === 'personal' && Object.keys(descriptions).length > 0) {
       throw new Error('description is only supported for a workspace secret')
     }

apps/sim/lib/copilot/vfs/serializers.ts

@@ -715,7 +715,7 @@ export function serializeCredentials(
     id?: string
     providerId: string
     displayName?: string | null
-    /** Teammate-facing note on a workspace secret, when one has been recorded. */
+    /** What a workspace secret is for, when one has been recorded. */
     description?: string | null
     role?: string | null
     scope: string | null

apps/sim/lib/credentials/environment.ts

@@ -217,7 +217,7 @@ interface AccessibleEnvCredential {
   type: 'env_workspace' | 'env_personal'
   envKey: string
   envOwnerUserId: string | null
-  /** Teammate-facing note. Always null on `env_personal`, which has no shared audience. */
+  /** Always null on `env_personal`: a mirror row cannot own a user-global secret's note. */
   description: string | null
   updatedAt: Date
 }