feat(search): show the matching passage and the author on each result

A result's snippet is the window around the first query term, skipping
the header block an email carries, so the row shows why the document
matched; its meta line names the source, the person behind the document
from its author-like tag, and the date. The agent's citations carry the
author too.

Author: waleedlatif1

apps/sim/app/api/knowledge/search/route.ts

@@ -7,6 +7,7 @@ import {
 import { internalKnowledgeErrorPolicies } from '@/lib/knowledge/api/route-policies'
 import { knowledgeOperations } from '@/lib/knowledge/application/operations'
 import { searchKnowledge } from '@/lib/knowledge/application/search'
+import { sourceAuthor } from '@/lib/knowledge/search/author'
 
 export const POST = defineInternalJsonRoute({
   contract: searchWorkspaceKnowledgeContract,
@@ -37,6 +38,7 @@ export const POST = defineInternalJsonRoute({
           sourceUrl: result.sourceUrl,
           connectorType: result.connectorType,
           sourceModifiedAt: result.sourceModifiedAt?.toISOString() ?? null,
+          author: sourceAuthor(result.metadata),
           content: result.content,
           chunkIndex: result.chunkIndex,
           similarity: result.similarity,

apps/sim/app/workspace/[workspaceId]/home/components/knowledge-search-results/knowledge-search-results.tsx

@@ -3,6 +3,7 @@
 import { useMemo, useState } from 'react'
 import { Button, Chip } from '@sim/emcn'
 import type { WorkspaceKnowledgeSearchResult } from '@/lib/api/contracts/knowledge'
+import { matchSnippet } from '@/lib/knowledge/search/snippet'
 import { connectorDisplayName } from '@/lib/sim-search/connectors'
 import { SourceCard } from '@/app/workspace/[workspaceId]/home/components/message-content/components/source-card'
 import type { SourceTagData } from '@/app/workspace/[workspaceId]/home/components/message-content/components/special-tags'
@@ -18,8 +19,6 @@ const EMPTY_MEMBER_CONNECTORS: WorkspaceMemberConnector[] = []
 
 /** A search spans at most this many knowledge bases. */
 const MAX_SEARCHED_KNOWLEDGE_BASES = 20
-/** Characters of the matching chunk shown under a result. */
-const SNIPPET_LENGTH = 280
 /** Filters appear only once a list is long and mixed enough for them to help. */
 const FILTERS_MIN_RESULTS = 10
 const DAY_MS = 24 * 60 * 60 * 1000
@@ -31,11 +30,6 @@ const UPDATED_WINDOWS = [
 ] as const
 type UpdatedWindow = (typeof UPDATED_WINDOWS)[number]['id']
 
-function toSnippet(content: string): string {
-  const flat = content.replace(/\s+/g, ' ').trim()
-  return flat.length > SNIPPET_LENGTH ? `${flat.slice(0, SNIPPET_LENGTH).trimEnd()}…` : flat
-}
-
 /**
  * One card per document, keeping the best-ranked chunk of each: the list is
  * already in rank order, so the first chunk seen for a document is its best.
@@ -77,7 +71,7 @@ export function indexingSourceNames(
  * source app, or the knowledge base for an upload. A document without a
  * source URL cannot be opened.
  */
-function toSource(result: WorkspaceKnowledgeSearchResult): SourceTagData | null {
+function toSource(result: WorkspaceKnowledgeSearchResult, query: string): SourceTagData | null {
   if (!result.sourceUrl) return null
   return {
     url: result.sourceUrl,
@@ -86,7 +80,8 @@ function toSource(result: WorkspaceKnowledgeSearchResult): SourceTagData | null
       ? connectorDisplayName(result.connectorType)
       : result.knowledgeBaseName || undefined,
     connectorType: result.connectorType ?? undefined,
-    snippet: toSnippet(result.content),
+    snippet: matchSnippet(result.content, query),
+    author: result.author ?? undefined,
     updatedAt: result.sourceModifiedAt ?? undefined,
   }
 }
@@ -251,7 +246,7 @@ export function KnowledgeSearchResults({
       ) : (
         <div className='flex flex-col gap-0.5' onKeyDown={handleResultsKeyDown}>
           {visible.map((result) => {
-            const source = toSource(result)
+            const source = toSource(result, query)
             return source ? (
               <SourceCard
                 key={result.documentId}
@@ -270,7 +265,7 @@ export function KnowledgeSearchResults({
                   {result.knowledgeBaseName}
                 </p>
                 <p className='line-clamp-2 text-[var(--text-body)] text-small leading-snug'>
-                  {toSnippet(result.content)}
+                  {matchSnippet(result.content, query)}
                 </p>
               </div>
             )

apps/sim/app/workspace/[workspaceId]/home/components/message-content/components/source-card/source-card.tsx

@@ -129,9 +129,11 @@ export function SourceCard({ source, query, onSummarize }: SourceCardProps) {
     ? BRAND_ICON_BY_BASE_TYPE.get(source.connectorType)
     : undefined
   const updatedAt = parseUpdatedAt(source.updatedAt)
-  const meta = [sourceLabel(source), updatedAt ? `Updated ${formatDate(updatedAt)}` : null].filter(
-    (part): part is string => Boolean(part)
-  )
+  const meta = [
+    sourceLabel(source),
+    source.author?.trim() || null,
+    updatedAt ? formatDate(updatedAt) : null,
+  ].filter((part): part is string => Boolean(part))
 
   return (
     <div className='group/source not-prose flex items-start gap-3 rounded-md px-2 py-2 transition-colors focus-within:bg-[var(--surface-5)] hover-hover:bg-[var(--surface-5)]'>

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

@@ -347,6 +347,8 @@ export interface SourceTagData {
   snippet?: string
   /** When the source last changed the document, as an ISO timestamp. */
   updatedAt?: string
+  /** The person behind the document, as the source names them. */
+  author?: string
 }
 
 export type ContentSegment =
@@ -583,6 +585,7 @@ function isSourceTagData(value: unknown): value is SourceTagData {
   if (value.connectorType !== undefined && typeof value.connectorType !== 'string') return false
   if (value.snippet !== undefined && typeof value.snippet !== 'string') return false
   if (value.updatedAt !== undefined && typeof value.updatedAt !== 'string') return false
+  if (value.author !== undefined && typeof value.author !== 'string') return false
   return true
 }
 

apps/sim/lib/api/contracts/knowledge/search.ts

@@ -164,6 +164,8 @@ export const workspaceKnowledgeSearchResultSchema = z.object({
   sourceUrl: z.string().nullable(),
   connectorType: z.string().nullable(),
   sourceModifiedAt: z.string().nullable(),
+  /** The person behind the document, from its author-like tag; null when the source names none. */
+  author: z.string().nullable(),
   content: z.string(),
   chunkIndex: z.number(),
   similarity: z.number(),

apps/sim/lib/copilot/tools/server/knowledge/knowledge-base.ts

@@ -52,6 +52,7 @@ import {
   KNOWLEDGE_TAG_DISPLAY_NAME_MAX_LENGTH,
   MAX_KNOWLEDGE_BATCH_ITEMS,
 } from '@/lib/knowledge/constants'
+import { sourceAuthor } from '@/lib/knowledge/search/author'
 import { captureServerEvent } from '@/lib/posthog/server'
 import { projectResolvedSecretModelContent } from '@/executor/utils/resolved-secret-content-projection'
 
@@ -65,7 +66,7 @@ const DEFAULT_QUERY_TOP_K = 10
  * a source URL is quoted by name instead.
  */
 const KNOWLEDGE_CITATION_INSTRUCTION =
-  'Cite each result you use inline, right after the sentence it supports, as <source>{"url":<sourceUrl>,"title":<documentName>,"siteName":<knowledgeBaseName>,"connectorType":<connectorType>,"snippet":<the sentence or two of content you relied on>,"updatedAt":<sourceModifiedAt>}</source>; omit the tag for a result whose sourceUrl is null and name the document instead.'
+  'Cite each result you use inline, right after the sentence it supports, as <source>{"url":<sourceUrl>,"title":<documentName>,"siteName":<knowledgeBaseName>,"connectorType":<connectorType>,"snippet":<the sentence or two of content you relied on>,"updatedAt":<sourceModifiedAt>,"author":<author>}</source>; omit the tag for a result whose sourceUrl is null and name the document instead.'
 
 /**
  * Resolves an environment-variable reference passed as a connector API key.
@@ -468,6 +469,7 @@ export const knowledgeBaseServerTool: BaseServerTool<KnowledgeBaseArgs, Knowledg
                 documentName: result.documentName,
                 sourceUrl: result.sourceUrl,
                 sourceModifiedAt: result.sourceModifiedAt?.toISOString() ?? null,
+                author: sourceAuthor(result.metadata),
                 connectorType: result.connectorType,
                 content: result.content,
                 chunkIndex: result.chunkIndex,

apps/sim/lib/knowledge/search/author.test.ts

@@ -0,0 +1,23 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { sourceAuthor } from '@/lib/knowledge/search/author'
+
+describe('sourceAuthor', () => {
+  it('prefers the sender of an email and drops the address', () => {
+    expect(sourceAuthor({ From: '"Ada Lovelace" <ada@example.com>', Owner: 'Someone' })).toBe(
+      'Ada Lovelace'
+    )
+  })
+
+  it('falls through the author-like names in order', () => {
+    expect(sourceAuthor({ Assignee: 'Grace', Owner: 'Alan' })).toBe('Alan')
+    expect(sourceAuthor({ Reporter: 'Grace' })).toBe('Grace')
+  })
+
+  it('returns null when nothing names a person', () => {
+    expect(sourceAuthor({ From: '<only@example.com>', Status: 'Open' })).toBeNull()
+    expect(sourceAuthor({})).toBeNull()
+  })
+})

apps/sim/lib/knowledge/search/author.ts

@@ -0,0 +1,34 @@
+/**
+ * The tag names connectors give the person behind a document, in the order
+ * they are tried. Connectors were never asked to agree on a name, so the
+ * result's author is derived here rather than in each of them.
+ */
+const AUTHOR_TAG_NAMES = [
+  'From',
+  'Author',
+  'Sender',
+  'Owner',
+  'Organizer',
+  'Creator',
+  'Reporter',
+  'Assignee',
+] as const
+
+/**
+ * The person a search result shows beside its source: the first author-like
+ * tag the document carries, reduced to a display name when the connector
+ * stored an address form such as `Name <name@example.com>`.
+ */
+export function sourceAuthor(metadata: Record<string, unknown>): string | null {
+  for (const name of AUTHOR_TAG_NAMES) {
+    const value = metadata[name]
+    if (typeof value !== 'string') continue
+    const display = value
+      .replace(/<[^>]*>/g, '')
+      .trim()
+      .replace(/^"|"$/g, '')
+      .trim()
+    if (display) return display
+  }
+  return null
+}

apps/sim/lib/knowledge/search/snippet.test.ts

@@ -0,0 +1,59 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  matchSnippet,
+  SNIPPET_LENGTH,
+  snippetTerms,
+  stripLeadingHeaders,
+} from '@/lib/knowledge/search/snippet'
+
+const EMAIL = [
+  'Subject: Invoice #1010 is overdue',
+  'From: Support <support@example.com>',
+  'To: Someone <someone@example.com>',
+  'Messages: 1',
+  '',
+  `${'Thanks for your patience. '.repeat(12)}The Volvo order shipped on Monday and the tracking number follows. ${'More text here. '.repeat(20)}`,
+].join('\n')
+
+describe('stripLeadingHeaders', () => {
+  it('drops the header block a connector writes above an email body', () => {
+    expect(stripLeadingHeaders(EMAIL).startsWith('\nThanks for your patience.')).toBe(true)
+  })
+
+  it('leaves a document that does not start with headers alone', () => {
+    expect(stripLeadingHeaders('Plain prose: with a colon inside.')).toBe(
+      'Plain prose: with a colon inside.'
+    )
+  })
+})
+
+describe('snippetTerms', () => {
+  it('keeps distinct terms of three or more characters, longest first', () => {
+    expect(snippetTerms('the Volvo invoice is volvo')).toEqual(['invoice', 'Volvo', 'volvo', 'the'])
+    expect(snippetTerms(undefined)).toEqual([])
+  })
+})
+
+describe('matchSnippet', () => {
+  it('returns a short document whole, without its headers', () => {
+    expect(matchSnippet('Subject: Hi\nFrom: A\n\nShort body.', 'body')).toBe('Short body.')
+  })
+
+  it('windows around the first query term with ellipses on both sides', () => {
+    const snippet = matchSnippet(EMAIL, 'volvo')
+    expect(snippet.startsWith('…')).toBe(true)
+    expect(snippet.endsWith('…')).toBe(true)
+    expect(snippet).toContain('The Volvo order shipped')
+    expect(snippet).not.toContain('Subject:')
+    expect(snippet.length).toBeLessThanOrEqual(SNIPPET_LENGTH + 2)
+  })
+
+  it('falls back to the opening when no term appears in the chunk', () => {
+    const snippet = matchSnippet(EMAIL, 'unrelated')
+    expect(snippet.startsWith('Thanks for your patience.')).toBe(true)
+    expect(snippet.endsWith('…')).toBe(true)
+  })
+})

apps/sim/lib/knowledge/search/snippet.ts

@@ -0,0 +1,69 @@
+/** Characters of a document shown under a search result. */
+export const SNIPPET_LENGTH = 280
+/** Characters kept before the first match, so the hit sits in context rather than at the edge. */
+const LEAD_LENGTH = 90
+/** Query terms shorter than this are too common to anchor a snippet on. */
+const MIN_TERM_LENGTH = 3
+/** `Key: value` lines a connector writes above an email or ticket body. */
+const HEADER_LINE = /^[A-Z][A-Za-z-]{1,15}: .*$/
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The document text without the header block some connectors prefix (the
+ * `Subject:` / `From:` / `To:` lines of an email): the title already says
+ * what the subject is, and a snippet spent on the header never shows why the
+ * document matched.
+ */
+export function stripLeadingHeaders(content: string): string {
+  const lines = content.split('\n')
+  let index = 0
+  while (index < lines.length && HEADER_LINE.test(lines[index].trim())) index += 1
+  if (index === 0) return content
+  return lines.slice(index).join('\n')
+}
+
+/** The query's terms worth anchoring on, longest first so the most specific one wins. */
+export function snippetTerms(query: string | undefined): string[] {
+  return [
+    ...new Set(
+      (query ?? '')
+        .split(/\s+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= MIN_TERM_LENGTH)
+    ),
+  ].sort((a, b) => b.length - a.length)
+}
+
+/**
+ * The passage of a document a search result shows: a window around the first
+ * query term found, the way a search page shows why a document matched, and
+ * the document's opening when no term appears in this chunk. Whitespace is
+ * collapsed and the window is cut on word boundaries with ellipses where the
+ * text continues.
+ */
+export function matchSnippet(content: string, query?: string): string {
+  const flat = stripLeadingHeaders(content).replace(/\s+/g, ' ').trim()
+  if (flat.length <= SNIPPET_LENGTH) return flat
+
+  let start = 0
+  for (const term of snippetTerms(query)) {
+    const match = new RegExp(`\\b${escapeRegExp(term)}\\b`, 'i').exec(flat)
+    if (!match) continue
+    start = Math.max(0, match.index - LEAD_LENGTH)
+    break
+  }
+  if (start > 0) {
+    const boundary = flat.indexOf(' ', start)
+    if (boundary !== -1 && boundary - start < LEAD_LENGTH) start = boundary + 1
+  }
+  if (flat.length - start <= SNIPPET_LENGTH) {
+    return `${start > 0 ? '…' : ''}${flat.slice(start)}`
+  }
+  let end = start + SNIPPET_LENGTH
+  const lastSpace = flat.lastIndexOf(' ', end)
+  if (lastSpace > start + SNIPPET_LENGTH / 2) end = lastSpace
+  return `${start > 0 ? '…' : ''}${flat.slice(start, end).trimEnd()}…`
+}