feat(knowledge): add connector tools and expand document metadata (#3452)

* feat(knowledge): add connector tools and expand document metadata

* fix(knowledge): address PR review feedback on new tools

* fix(knowledge): remove unused params from get_document transform

Author: waleedlatif1

apps/sim/app/api/knowledge/utils.ts

@@ -58,6 +58,8 @@ export interface DocumentData {
   boolean3?: boolean | null
   // Connector fields
   connectorId?: string | null
+  sourceUrl?: string | null
+  externalId?: string | null
 }
 
 export interface EmbeddingData {
@@ -287,6 +289,8 @@ export async function checkDocumentWriteAccess(
       boolean3: document.boolean3,
       // Connector fields
       connectorId: document.connectorId,
+      sourceUrl: document.sourceUrl,
+      externalId: document.externalId,
     })
     .from(document)
     .where(and(eq(document.id, documentId), isNull(document.deletedAt)))

apps/sim/blocks/blocks/knowledge.ts

@@ -10,7 +10,10 @@ export const KnowledgeBlock: BlockConfig = {
   bestPractices: `
   - Clarify which tags are available for the knowledge base to understand whether to use tag filters on a search.
   - Use List Documents to enumerate documents before operating on them.
+  - Use Get Document to retrieve full details including tags, connector metadata, and processing status.
   - Use List Chunks to inspect a document's contents before updating or deleting chunks.
+  - Use List Connectors to see which external sources are syncing documents into the knowledge base.
+  - Use Get Connector to check sync health and review recent sync logs.
   `,
   bgColor: '#00B0B0',
   icon: PackageSearchIcon,
@@ -24,13 +27,17 @@ export const KnowledgeBlock: BlockConfig = {
       options: [
         { label: 'Search', id: 'search' },
         { label: 'List Documents', id: 'list_documents' },
+        { label: 'Get Document', id: 'get_document' },
         { label: 'Create Document', id: 'create_document' },
         { label: 'Delete Document', id: 'delete_document' },
         { label: 'List Chunks', id: 'list_chunks' },
         { label: 'Upload Chunk', id: 'upload_chunk' },
         { label: 'Update Chunk', id: 'update_chunk' },
         { label: 'Delete Chunk', id: 'delete_chunk' },
         { label: 'List Tags', id: 'list_tags' },
+        { label: 'List Connectors', id: 'list_connectors' },
+        { label: 'Get Connector', id: 'get_connector' },
+        { label: 'Trigger Sync', id: 'trigger_sync' },
       ],
       value: () => 'search',
     },
@@ -125,7 +132,14 @@ export const KnowledgeBlock: BlockConfig = {
       mode: 'basic',
       condition: {
         field: 'operation',
-        value: ['upload_chunk', 'delete_document', 'list_chunks', 'update_chunk', 'delete_chunk'],
+        value: [
+          'get_document',
+          'upload_chunk',
+          'delete_document',
+          'list_chunks',
+          'update_chunk',
+          'delete_chunk',
+        ],
       },
     },
     // Document selector — advanced mode (manual ID input)
@@ -139,7 +153,14 @@ export const KnowledgeBlock: BlockConfig = {
       mode: 'advanced',
       condition: {
         field: 'operation',
-        value: ['upload_chunk', 'delete_document', 'list_chunks', 'update_chunk', 'delete_chunk'],
+        value: [
+          'get_document',
+          'upload_chunk',
+          'delete_document',
+          'list_chunks',
+          'update_chunk',
+          'delete_chunk',
+        ],
       },
     },
 
@@ -208,6 +229,16 @@ export const KnowledgeBlock: BlockConfig = {
       condition: { field: 'operation', value: 'update_chunk' },
     },
 
+    // --- Connector operations ---
+    {
+      id: 'connectorId',
+      title: 'Connector ID',
+      type: 'short-input',
+      placeholder: 'Enter connector ID',
+      required: true,
+      condition: { field: 'operation', value: ['get_connector', 'trigger_sync'] },
+    },
+
     // --- List Chunks ---
     {
       id: 'chunkSearch',
@@ -235,10 +266,14 @@ export const KnowledgeBlock: BlockConfig = {
       'knowledge_create_document',
       'knowledge_list_tags',
       'knowledge_list_documents',
+      'knowledge_get_document',
       'knowledge_delete_document',
       'knowledge_list_chunks',
       'knowledge_update_chunk',
       'knowledge_delete_chunk',
+      'knowledge_list_connectors',
+      'knowledge_get_connector',
+      'knowledge_trigger_sync',
     ],
     config: {
       tool: (params) => {
@@ -253,6 +288,8 @@ export const KnowledgeBlock: BlockConfig = {
             return 'knowledge_list_tags'
           case 'list_documents':
             return 'knowledge_list_documents'
+          case 'get_document':
+            return 'knowledge_get_document'
           case 'delete_document':
             return 'knowledge_delete_document'
           case 'list_chunks':
@@ -261,6 +298,12 @@ export const KnowledgeBlock: BlockConfig = {
             return 'knowledge_update_chunk'
           case 'delete_chunk':
             return 'knowledge_delete_chunk'
+          case 'list_connectors':
+            return 'knowledge_list_connectors'
+          case 'get_connector':
+            return 'knowledge_get_connector'
+          case 'trigger_sync':
+            return 'knowledge_trigger_sync'
           default:
             return 'knowledge_search'
         }
@@ -273,6 +316,7 @@ export const KnowledgeBlock: BlockConfig = {
         params.knowledgeBaseId = knowledgeBaseId
 
         const docOps = [
+          'get_document',
           'upload_chunk',
           'delete_document',
           'list_chunks',
@@ -296,6 +340,15 @@ export const KnowledgeBlock: BlockConfig = {
           params.chunkId = chunkId
         }
 
+        const connectorOps = ['get_connector', 'trigger_sync']
+        if (connectorOps.includes(params.operation)) {
+          const connectorId = params.connectorId ? String(params.connectorId).trim() : ''
+          if (!connectorId) {
+            throw new Error(`Connector ID is required for ${params.operation} operation`)
+          }
+          params.connectorId = connectorId
+        }
+
         // Map list_chunks sub-block fields to tool params
         if (params.operation === 'list_chunks') {
           if (params.chunkSearch) params.search = params.chunkSearch
@@ -329,6 +382,7 @@ export const KnowledgeBlock: BlockConfig = {
     documentTags: { type: 'string', description: 'Document tags' },
     chunkSearch: { type: 'string', description: 'Search filter for chunks' },
     chunkEnabledFilter: { type: 'string', description: 'Filter chunks by enabled status' },
+    connectorId: { type: 'string', description: 'Connector identifier' },
   },
   outputs: {
     results: { type: 'json', description: 'Search results' },

apps/sim/tools/knowledge/get_connector.ts

@@ -0,0 +1,119 @@
+import type { KnowledgeGetConnectorResponse } from '@/tools/knowledge/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const knowledgeGetConnectorTool: ToolConfig<any, KnowledgeGetConnectorResponse> = {
+  id: 'knowledge_get_connector',
+  name: 'Knowledge Get Connector',
+  description:
+    'Get detailed connector information including recent sync logs for monitoring sync health',
+  version: '1.0.0',
+
+  params: {
+    knowledgeBaseId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the knowledge base the connector belongs to',
+    },
+    connectorId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'ID of the connector to retrieve',
+    },
+  },
+
+  request: {
+    url: (params) =>
+      `/api/knowledge/${params.knowledgeBaseId}/connectors/${params.connectorId}`,
+    method: 'GET',
+    headers: () => ({
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response): Promise<KnowledgeGetConnectorResponse> => {
+    const result = await response.json()
+    const data = result.data || {}
+
+    return {
+      success: result.success ?? true,
+      output: {
+        connector: {
+          id: data.id,
+          connectorType: data.connectorType,
+          status: data.status,
+          syncIntervalMinutes: data.syncIntervalMinutes,
+          lastSyncAt: data.lastSyncAt ?? null,
+          lastSyncError: data.lastSyncError ?? null,
+          lastSyncDocCount: data.lastSyncDocCount ?? null,
+          nextSyncAt: data.nextSyncAt ?? null,
+          consecutiveFailures: data.consecutiveFailures ?? 0,
+          createdAt: data.createdAt ?? null,
+          updatedAt: data.updatedAt ?? null,
+        },
+        syncLogs: (data.syncLogs || []).map(
+          (log: {
+            id: string
+            status: string
+            startedAt: string | null
+            completedAt: string | null
+            docsAdded: number | null
+            docsUpdated: number | null
+            docsDeleted: number | null
+            docsUnchanged: number | null
+            errorMessage: string | null
+          }) => ({
+            id: log.id,
+            status: log.status,
+            startedAt: log.startedAt ?? null,
+            completedAt: log.completedAt ?? null,
+            docsAdded: log.docsAdded ?? null,
+            docsUpdated: log.docsUpdated ?? null,
+            docsDeleted: log.docsDeleted ?? null,
+            docsUnchanged: log.docsUnchanged ?? null,
+            errorMessage: log.errorMessage ?? null,
+          })
+        ),
+      },
+    }
+  },
+
+  outputs: {
+    connector: {
+      type: 'object',
+      description: 'Connector details',
+      properties: {
+        id: { type: 'string', description: 'Connector ID' },
+        connectorType: { type: 'string', description: 'Type of connector' },
+        status: { type: 'string', description: 'Connector status (active, paused, syncing)' },
+        syncIntervalMinutes: { type: 'number', description: 'Sync interval in minutes' },
+        lastSyncAt: { type: 'string', description: 'Timestamp of last sync' },
+        lastSyncError: { type: 'string', description: 'Error from last sync if failed' },
+        lastSyncDocCount: { type: 'number', description: 'Docs synced in last sync' },
+        nextSyncAt: { type: 'string', description: 'Next scheduled sync timestamp' },
+        consecutiveFailures: { type: 'number', description: 'Consecutive sync failures' },
+        createdAt: { type: 'string', description: 'Creation timestamp' },
+        updatedAt: { type: 'string', description: 'Last update timestamp' },
+      },
+    },
+    syncLogs: {
+      type: 'array',
+      description: 'Recent sync log entries',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Sync log ID' },
+          status: { type: 'string', description: 'Sync status' },
+          startedAt: { type: 'string', description: 'Sync start time' },
+          completedAt: { type: 'string', description: 'Sync completion time' },
+          docsAdded: { type: 'number', description: 'Documents added' },
+          docsUpdated: { type: 'number', description: 'Documents updated' },
+          docsDeleted: { type: 'number', description: 'Documents deleted' },
+          docsUnchanged: { type: 'number', description: 'Documents unchanged' },
+          errorMessage: { type: 'string', description: 'Error message if sync failed' },
+        },
+      },
+    },
+  },
+}