feat(secrets): let mship add secret descriptions (#6814)

* feat(copilot): support workspace secret descriptions

* feat(copilot): save secret card descriptions

* test(copilot): cover secret card descriptions

* fix(copilot): update secret descriptions without values

Author: Sg312

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

@@ -14,9 +14,11 @@ const {
   mockSendBrowserPanelAction,
   mockUpsertWorkspaceEnvironment,
   mockUseUserPermissionsContext,
+  mockUpdateWorkspaceCredential,
   mockUseWorkspaceCredential,
   mockUseWorkspaceCredentials,
 } = vi.hoisted(() => ({
+  mockUpdateWorkspaceCredential: vi.fn(async () => undefined),
   mockRefetchPersonalEnvironment: vi.fn(async () => ({ data: {} })),
   mockRefetchWorkspaceCredentials: vi.fn(async () => ({ data: [] })),
   mockIsBrowserAgentAvailable: vi.fn(() => false),
@@ -37,6 +39,7 @@ vi.mock('next/navigation', () => ({
 }))
 
 vi.mock('@/hooks/queries/credentials', () => ({
+  useUpdateWorkspaceCredential: () => ({ mutateAsync: mockUpdateWorkspaceCredential }),
   useWorkspaceCredential: mockUseWorkspaceCredential,
   useWorkspaceCredentials: mockUseWorkspaceCredentials,
 }))
@@ -1144,6 +1147,86 @@ describe('CredentialDisplay link tag', () => {
     act(() => root.unmount())
   })
 
+  it('attaches an agent-authored description after the secret value is saved', async () => {
+    mockUseUserPermissionsContext.mockReturnValue({ canEdit: true })
+    mockRefetchWorkspaceCredentials.mockResolvedValueOnce({
+      data: [{ id: 'cred-1', envKey: 'WORKSPACE_KEY' }],
+    })
+    const container = document.createElement('div')
+    const root = createRoot(container)
+    const data: CredentialItemData[] = [
+      {
+        type: 'secret_input',
+        name: 'WORKSPACE_KEY',
+        scope: 'workspace',
+        description: '  Stripe live key for billing  ',
+      },
+    ]
+
+    act(() => {
+      root.render(<SpecialTags segment={{ type: 'credential', data }} onOptionSelect={vi.fn()} />)
+    })
+
+    const input = container.querySelector('input')
+    act(() => {
+      if (!input) return
+      const valueSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value'
+      )?.set
+      valueSetter?.call(input, 'sk-live-123')
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+    const submitButton = Array.from(container.querySelectorAll('button')).find(
+      (button) => button.textContent === 'Submit'
+    )
+    await act(async () => submitButton?.click())
+
+    expect(mockUpsertWorkspaceEnvironment).toHaveBeenCalledWith({
+      workspaceId: 'workspace-1',
+      variables: { WORKSPACE_KEY: 'sk-live-123' },
+    })
+    // The description rides the credential row the value save just created, so
+    // the trimmed note lands without the user ever seeing the field.
+    expect(mockUpdateWorkspaceCredential).toHaveBeenCalledWith({
+      credentialId: 'cred-1',
+      description: 'Stripe live key for billing',
+    })
+    act(() => root.unmount())
+  })
+
+  it('leaves a personal secret undescribed', async () => {
+    mockUseUserPermissionsContext.mockReturnValue({ canEdit: true })
+    const container = document.createElement('div')
+    const root = createRoot(container)
+    const data: CredentialItemData[] = [
+      { type: 'secret_input', name: 'PERSONAL_KEY', scope: 'personal', description: 'my key' },
+    ]
+
+    act(() => {
+      root.render(<SpecialTags segment={{ type: 'credential', data }} onOptionSelect={vi.fn()} />)
+    })
+
+    const input = container.querySelector('input')
+    act(() => {
+      if (!input) return
+      const valueSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value'
+      )?.set
+      valueSetter?.call(input, 'personal-secret')
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+    const submitButton = Array.from(container.querySelectorAll('button')).find(
+      (button) => button.textContent === 'Submit'
+    )
+    await act(async () => submitButton?.click())
+
+    expect(mockSavePersonalEnvironment).toHaveBeenCalled()
+    expect(mockUpdateWorkspaceCredential).not.toHaveBeenCalled()
+    act(() => root.unmount())
+  })
+
   it('renders one status recap from a transcript submission', () => {
     const container = document.createElement('div')
     const root: Root = createRoot(container)

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

@@ -295,13 +295,25 @@ export const Browser: ToolCatalogEntry = {
   mode: 'async',
   parameters: {
     properties: {
+      sessionId: {
+        description:
+          'Reusable session ID returned by an earlier browser call in this chat. Supply it only on a later user message that continues the same browsing objective, and at most once per user message.',
+        type: 'string',
+      },
       task: {
         description:
-          'The web task to complete, in plain language (include the target site/URL if known).',
+          "Optional brief scoping instruction that the conversation does not already convey. Do not restate the user's request.",
+        type: 'string',
+      },
+      title: {
+        description:
+          "Required private orchestration label (3–8 words) for this Browser Agent session's stable objective. When resuming with sessionId, copy the registry title unchanged.",
+        maxLength: 120,
+        minLength: 1,
         type: 'string',
       },
     },
-    required: ['task'],
+    required: ['title'],
     type: 'object',
   },
   subagentId: 'browser',
@@ -1248,16 +1260,14 @@ export const Cp: ToolCatalogEntry = {
     properties: {
       destination: {
         type: 'string',
-        maxLength: 4096,
         description:
           'Target path under workflows/. An existing folder (or a path ending in "/") duplicates sources into it keeping their names; otherwise the last segment names the copy and the preceding segments are the target folder (created automatically when missing).',
       },
       sources: {
         type: 'array',
-        maxItems: 100,
         description:
           'Canonical workflow VFS paths to duplicate, e.g. ["workflows/My%20Workflow"]. Copy paths verbatim from glob/grep/read output.',
-        items: { type: 'string', maxLength: 4096 },
+        items: { type: 'string' },
       },
       toolTitle: {
         type: 'string',
@@ -3716,10 +3726,9 @@ export const Mkdir: ToolCatalogEntry = {
     properties: {
       paths: {
         type: 'array',
-        maxItems: 100,
         description:
           'Canonical folder VFS paths to create, e.g. ["files/Reports/2026"]. Missing parent segments are created automatically.',
-        items: { type: 'string', maxLength: 4096 },
+        items: { type: 'string' },
       },
       toolTitle: {
         type: 'string',
@@ -3742,16 +3751,14 @@ export const Mv: ToolCatalogEntry = {
     properties: {
       destination: {
         type: 'string',
-        maxLength: 4096,
         description:
           'Target path. A path ending in "/" (or naming an existing folder) moves sources into it keeping their names — always use the trailing "/" form when targeting a folder. Otherwise the last segment is the new name and the preceding segments are the target folder (created automatically when missing).',
       },
       sources: {
         type: 'array',
-        maxItems: 100,
         description:
           'Canonical VFS paths to move or rename, e.g. ["files/draft.md"]. All sources must share one category. Copy paths verbatim from glob/grep/read output.',
-        items: { type: 'string', maxLength: 4096 },
+        items: { type: 'string' },
       },
       toolTitle: {
         type: 'string',
@@ -4184,10 +4191,9 @@ export const Rm: ToolCatalogEntry = {
     properties: {
       paths: {
         type: 'array',
-        maxItems: 100,
         description:
           'Canonical VFS paths to delete, e.g. ["files/Reports/draft.md"]. Copy paths verbatim from glob/grep/read output. Paths from different categories may be mixed in one call.',
-        items: { type: 'string', maxLength: 4096 },
+        items: { type: 'string' },
       },
       toolTitle: {
         type: 'string',
@@ -4752,10 +4758,19 @@ export const SetEnvironmentVariables: ToolCatalogEntry = {
         items: {
           type: 'object',
           properties: {
+            description: {
+              type: 'string',
+              description:
+                '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. You may send it alone, without a value, to describe a secret that already exists.',
+            },
             name: { type: 'string', description: 'Variable name' },
-            value: { type: 'string', description: 'Variable value' },
+            value: {
+              type: 'string',
+              description:
+                "Variable value. Omit it to leave an existing variable's value untouched and change only its description — never invent or guess a value you were not given, which would overwrite the real secret.",
+            },
           },
-          required: ['name', 'value'],
+          required: ['name'],
         },
       },
     },