feat(copilot): expose sandbox capability catalog in VFS

Author: Sg312

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

@@ -2,6 +2,11 @@
  * @vitest-environment node
  */
 import { describe, expect, it } from 'vitest'
+import {
+  MAX_SANDBOX_CLI_TOOLS,
+  SANDBOX_CLI_TOOLS,
+  SANDBOX_SELECTABLE_CLI_TOOL_IDS,
+} from '@/lib/execution/remote-sandbox/cli-tools'
 import type { BlockConfig } from '@/blocks/types'
 import { hostedKeyEnabledWhen } from '@/tools/hosting'
 import type { ToolConfig } from '@/tools/types'
@@ -14,6 +19,7 @@ import {
   serializeIntegrationSchema,
   serializeKBMeta,
   serializeSandbox,
+  serializeSandboxCatalog,
   serializeTableMeta,
   serializeWorkflowMeta,
 } from './serializers'
@@ -155,6 +161,19 @@ describe('VFS metadata serializers', () => {
       cliTools: ['kubectl@1.36.3-r1'],
     })
   })
+
+  it('generates the sandbox capability reference from the authoritative CLI registry', () => {
+    const reference = serializeSandboxCatalog('prebuilt')
+
+    expect(reference).toContain('Active dependency strategy: `prebuilt`')
+    expect(reference).toContain(`accepts at most ${MAX_SANDBOX_CLI_TOOLS} exact pinned ids`)
+    for (const id of SANDBOX_SELECTABLE_CLI_TOOL_IDS) {
+      const tool = SANDBOX_CLI_TOOLS[id]
+      expect(reference).toContain(`\`${id}\``)
+      expect(reference).toContain(tool.label)
+      expect(reference).toContain(tool.description)
+    }
+  })
 })
 
 describe('entitlement-projected block schemas', () => {

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

@@ -6,6 +6,11 @@ import {
   getServiceAccountConnectNoun,
   getServiceAccountGatingBlockType,
 } from '@/lib/credentials/service-account-provider-ids'
+import {
+  MAX_SANDBOX_CLI_TOOLS,
+  SANDBOX_CLI_TOOLS,
+  SANDBOX_SELECTABLE_CLI_TOOL_IDS,
+} from '@/lib/execution/remote-sandbox/cli-tools'
 import { type FilterFieldType, getOperatorsForFieldType } from '@/lib/knowledge/filters/types'
 import { getServiceAccountProviderForProviderId } from '@/lib/oauth/utils'
 import { isSubBlockHidden } from '@/lib/workflows/subblocks/visibility'
@@ -1001,6 +1006,39 @@ export function serializeSandbox(sandbox: Sandbox, strategy: 'prebuilt' | 'runti
   )
 }
 
+/**
+ * Generate the authoritative Sim-sandbox capability reference exposed in VFS.
+ * The managed-CLI rows come directly from the same client-safe registry used by
+ * validation and the settings UI, so adding or upgrading a CLI updates agent
+ * discovery without a second hand-maintained list.
+ */
+export function serializeSandboxCatalog(strategy: 'prebuilt' | 'runtime'): string {
+  const rows = SANDBOX_SELECTABLE_CLI_TOOL_IDS.map((id) => {
+    const tool = SANDBOX_CLI_TOOLS[id]
+    const aliases = tool.searchTerms?.join(', ') || '(none)'
+    return `| \`${tool.id}\` | ${tool.label} | ${tool.category} | ${tool.description} | ${aliases} |`
+  })
+
+  return [
+    '# Sim Sandbox Capabilities',
+    '',
+    'This file is generated from the active Sim sandbox registry. Treat it as the authoritative catalog; do not guess or reuse managed CLI ids from memory.',
+    '',
+    `- Active dependency strategy: \`${strategy}\``,
+    '- Dependency languages: `javascript` installs npm packages; `python` installs PyPI packages. Shell execution may select either language.',
+    '- `systemPackages` accepts Debian package coordinates in `package[:architecture][=version]` form.',
+    `- \`cliTools\` accepts at most ${MAX_SANDBOX_CLI_TOOLS} exact pinned ids from the catalog below.`,
+    '- A Sim sandbox may combine language dependencies, Debian system packages, and managed CLIs.',
+    '',
+    '## Managed CLI catalog',
+    '',
+    '| Exact id | Name | Category | What it provides | Search terms / executables |',
+    '|----------|------|----------|------------------|----------------------------|',
+    ...rows,
+    '',
+  ].join('\n')
+}
+
 /**
  * Serialize an integration/tool schema for VFS components/integrations/{service}/{operation}.json
  */

apps/sim/lib/copilot/vfs/workspace-vfs.ts

@@ -84,6 +84,7 @@ import {
   serializeMcpServer,
   serializeRecentExecutions,
   serializeSandbox,
+  serializeSandboxCatalog,
   serializeSkill,
   serializeTableMeta,
   serializeTaskChat,
@@ -538,6 +539,7 @@ function getStaticComponentFiles(): Map<string, string> {
  *   tasks/{title}/session.md
  *   tasks/{title}/chat.json
  *   custom-tools/{name}.json
+ *   agent/sandboxes/README.md
  *   agent/sandboxes/{name}.json
  *   environment/credentials.json
  *   environment/api-keys.json
@@ -2179,6 +2181,7 @@ export class WorkspaceVFS {
     try {
       const sandboxes = await listWorkspaceSandboxes(workspaceId)
       const strategy = currentSandboxStrategy()
+      this.files.set('agent/sandboxes/README.md', serializeSandboxCatalog(strategy))
       for (const sandbox of sandboxes) {
         this.files.set(
           `agent/sandboxes/${sanitizeName(sandbox.name)}.json`,