@ganju/utils 0.0.9 → 0.0.10

package/src/chunking.ts

@@ -1,4 +1,5 @@
 import { constants } from './constants';
+import { decodeEntities } from './sanitize';
 
 import type {
   ExtractedDocument,
@@ -50,24 +51,140 @@ export const splitRecursive = (
   return chunks;
 };
 
-export const chunkText = (
+// Each piece keeps its `raw` text — the slice of the input it covers, without
+// the overlap borrowed from the piece before — so a caller can walk the input
+// in order without reading any of it twice.
+const chunkPieces = (
   text: string,
   options?: { targetChars?: number; overlapChars?: number }
-): string[] => {
+): Array<{ raw: string; content: string }> => {
   const target = options?.targetChars ?? constants.CHUNK_TARGET_CHARS;
   const overlap = options?.overlapChars ?? constants.CHUNK_OVERLAP_CHARS;
 
   const trimmed = text.trim();
   if (!trimmed) return [];
-  if (trimmed.length <= target) return [trimmed];
+  if (trimmed.length <= target) return [{ raw: trimmed, content: trimmed }];
 
   const rawChunks = splitRecursive(trimmed, target);
-  const withOverlap: string[] = [];
+  const pieces: Array<{ raw: string; content: string }> = [];
   for (let i = 0; i < rawChunks.length; i++) {
     const prev = i > 0 ? rawChunks[i - 1].slice(-overlap) : '';
-    withOverlap.push((prev ? prev + '\n' : '') + rawChunks[i]);
+    pieces.push({
+      raw: rawChunks[i],
+      content: (prev ? prev + '\n' : '') + rawChunks[i]
+    });
+  }
+  return pieces.filter(p => p.content.trim().length > 0);
+};
+
+export const chunkText = (
+  text: string,
+  options?: { targetChars?: number; overlapChars?: number }
+): string[] => chunkPieces(text, options).map(p => p.content);
+
+export type HeadingSyntax = 'markdown' | 'html';
+
+interface HeadingEvent {
+  offset: number;
+  level: number;
+  text: string;
+}
+
+const MARKDOWN_HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
+const MARKDOWN_FENCE = /^ {0,3}(```|~~~)/;
+const HTML_HEADING = /<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1\s*>/gi;
+const MAX_HEADING_CHARS = 120;
+
+const MARKDOWN_FILE_NAME = /\.(md|markdown|mdx)$/i;
+
+/**
+ * Which heading syntax a document is written in, or null when it has none we
+ * can trust. Plain text is left out on purpose: a line that happens to start
+ * with "# " there is as likely a comment or a list as a title.
+ */
+export const headingSyntaxFor = (input: {
+  mimeType?: string | null;
+  fileName?: string | null;
+  isWebPage?: boolean;
+}): HeadingSyntax | null => {
+  // Crawled pages are flattened to text with their headings written back as
+  // Markdown lines, whatever the page's own content type was.
+  if (input.isWebPage) return 'markdown';
+  if (input.mimeType === constants.MIMETYPE_TEXT_MARKDOWN) return 'markdown';
+  if (input.mimeType === constants.MIMETYPE_TEXT_HTML) return 'html';
+  if (input.fileName && MARKDOWN_FILE_NAME.test(input.fileName)) {
+    return 'markdown';
+  }
+  return null;
+};
+
+const cleanHeading = (text: string): string =>
+  text.replace(/\s+/g, ' ').trim().slice(0, MAX_HEADING_CHARS);
+
+const scanMarkdownHeadings = (
+  text: string,
+  state: { inFence: boolean }
+): HeadingEvent[] => {
+  const events: HeadingEvent[] = [];
+  let offset = 0;
+  for (const line of text.split('\n')) {
+    // A `#` inside a fenced block is a shell comment or a preprocessor line,
+    // not a title — and a fence can open in one chunk and close in the next.
+    if (MARKDOWN_FENCE.test(line)) {
+      state.inFence = !state.inFence;
+    } else if (!state.inFence) {
+      const match = MARKDOWN_HEADING.exec(line);
+      const heading = match ? cleanHeading(match[2]) : '';
+      if (match && heading) {
+        events.push({ offset, level: match[1].length, text: heading });
+      }
+    }
+    offset += line.length + 1;
   }
-  return withOverlap.filter(c => c.trim().length > 0);
+  return events;
+};
+
+const scanHtmlHeadings = (text: string): HeadingEvent[] =>
+  [...text.matchAll(HTML_HEADING)]
+    .map(match => ({
+      offset: match.index ?? 0,
+      level: Number(match[1]),
+      text: cleanHeading(decodeEntities(match[2].replace(/<[^>]*>/g, ' ')))
+    }))
+    .filter(event => event.text);
+
+/**
+ * Follows the heading hierarchy across a document's chunks, fed in order.
+ * Returns, for each chunk, the path of headings it sits under — the section a
+ * reader would be pointed to. A chunk that opens with a heading belongs to that
+ * heading; one that starts mid-section belongs to the section it continues,
+ * even when a later heading begins inside it.
+ */
+const createHeadingTracker = (syntax: HeadingSyntax) => {
+  let stack: Array<{ level: number; text: string }> = [];
+  const fence = { inFence: false };
+  const apply = (event: HeadingEvent) => {
+    stack = stack.filter(h => h.level < event.level);
+    stack.push({ level: event.level, text: event.text });
+  };
+
+  return (raw: string): string[] => {
+    const events =
+      syntax === 'markdown'
+        ? scanMarkdownHeadings(raw, fence)
+        : scanHtmlHeadings(raw);
+    const [first, ...rest] = events;
+    // Before a document's first heading there is no section to continue — only
+    // the metadata header, or the markup around an HTML body — so a chunk that
+    // holds the first heading belongs to it wherever in the chunk it falls.
+    const opensWithHeading =
+      first !== undefined &&
+      (stack.length === 0 || raw.slice(0, first.offset).trim() === '');
+    if (opensWithHeading) apply(first);
+    const path = stack.map(h => h.text);
+    for (const event of opensWithHeading ? rest : events) apply(event);
+    return path;
+  };
 };
 
 export const buildHeader = (input: {
@@ -87,9 +204,14 @@ export const buildHeader = (input: {
     .filter(Boolean)
     .join('\n');
 
-export interface ChunkMetadata extends ExtractedDocumentMetadata {
-  chunkIndexInPage: number;
-  chunksInPage: number;
+// Loose on purpose: a chunk of inline text has no extracted document behind it,
+// so only `headingPath` can be known about it.
+export interface ChunkMetadata extends Partial<ExtractedDocumentMetadata> {
+  chunkIndexInPage?: number;
+  chunksInPage?: number;
+  // The headings this chunk sits under, outermost first. Present only for
+  // Markdown and HTML, and only when the chunk is under at least one heading.
+  headingPath?: string[];
 }
 
 export interface PreparedChunk {
@@ -97,28 +219,43 @@ export interface PreparedChunk {
   metadata: ChunkMetadata | null;
 }
 
+const CONTROL_CHARS = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g;
+
 export const prepareChunks = (
   header: string,
   documents: ExtractedDocument[] | null,
   fallbackContent: string | null,
-  options?: { targetChars?: number; overlapChars?: number }
+  options?: {
+    targetChars?: number;
+    overlapChars?: number;
+    // The resource's own type and file name, which decide the heading syntax
+    // for inline content and for documents that don't carry their own.
+    mimeType?: string | null;
+    fileName?: string | null;
+  }
 ): PreparedChunk[] => {
   if (documents && documents.length > 0) {
     const out: PreparedChunk[] = [];
     documents.forEach((doc, docIndex) => {
-      const body = (doc.pageContent || '')
-        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
-        .trim();
+      const body = (doc.pageContent || '').replace(CONTROL_CHARS, '').trim();
       if (!body) return;
       const text = docIndex === 0 && header ? `${header}\n\n${body}` : body;
-      const pieces = chunkText(text, options);
+      const syntax = headingSyntaxFor({
+        mimeType: doc.metadata?.source?.mimeType ?? options?.mimeType,
+        fileName: doc.metadata?.source?.fileName ?? options?.fileName,
+        isWebPage: !!doc.metadata?.web
+      });
+      const headingPathOf = syntax ? createHeadingTracker(syntax) : null;
+      const pieces = chunkPieces(text, options);
       pieces.forEach((piece, pieceIndex) => {
+        const headingPath = headingPathOf?.(piece.raw) ?? [];
         out.push({
-          content: piece,
+          content: piece.content,
           metadata: {
             ...doc.metadata,
             chunkIndexInPage: pieceIndex,
-            chunksInPage: pieces.length
+            chunksInPage: pieces.length,
+            ...(headingPath.length > 0 ? { headingPath } : {})
           }
         });
       });
@@ -126,12 +263,18 @@ export const prepareChunks = (
     return out;
   }
 
-  const body = (fallbackContent || '')
-    .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '')
-    .trim();
+  const body = (fallbackContent || '').replace(CONTROL_CHARS, '').trim();
   const fullText = [header, body].filter(Boolean).join('\n\n');
-  return chunkText(fullText, options).map(content => ({
-    content,
-    metadata: null
-  }));
+  const syntax = headingSyntaxFor({
+    mimeType: options?.mimeType,
+    fileName: options?.fileName
+  });
+  const headingPathOf = syntax ? createHeadingTracker(syntax) : null;
+  return chunkPieces(fullText, options).map(piece => {
+    const headingPath = headingPathOf?.(piece.raw) ?? [];
+    return {
+      content: piece.content,
+      metadata: headingPath.length > 0 ? { headingPath } : null
+    };
+  });
 };

package/src/constants.ts

@@ -278,6 +278,33 @@ const RESOURCE_SOURCE_TYPES = [
   RESOURCE_SOURCE_TYPE_CUSTOM_CODE
 ];
 
+// How often a source that lives somewhere else — a crawled website, a Drive or
+// OneDrive folder, a file imported from either — is refreshed from it. Every
+// source is stored with an interval, weekly unless its owner changes it; the
+// hourly sync job only acts on it for a plan that includes automatic sync, so a
+// Free org's sources start syncing the moment it upgrades.
+const RESOURCE_SYNC_INTERVAL_OFF = 'off' as 'off';
+const RESOURCE_SYNC_INTERVAL_DAILY = 'daily' as 'daily';
+const RESOURCE_SYNC_INTERVAL_WEEKLY = 'weekly' as 'weekly';
+const RESOURCE_SYNC_INTERVALS = [
+  RESOURCE_SYNC_INTERVAL_OFF,
+  RESOURCE_SYNC_INTERVAL_DAILY,
+  RESOURCE_SYNC_INTERVAL_WEEKLY
+] as const;
+const RESOURCE_SYNC_INTERVAL_DEFAULT = RESOURCE_SYNC_INTERVAL_WEEKLY;
+const RESOURCE_SYNC_INTERVAL_MS = {
+  [RESOURCE_SYNC_INTERVAL_DAILY]: 24 * 60 * 60 * 1000,
+  [RESOURCE_SYNC_INTERVAL_WEEKLY]: 7 * 24 * 60 * 60 * 1000
+} as const;
+// Sources started per hourly run. A sync is cheap to start and expensive to
+// run — a website re-crawls every page — so the job works through a backlog
+// over several hours rather than launching all of it at once.
+const RESOURCE_SYNC_BATCH_SIZE = 50;
+// How soon a source can be synced by hand again. Manual sync is open to every
+// plan, and a website sync re-crawls every page, so it can't be a button to
+// press in a loop.
+const RESOURCE_SYNC_MANUAL_COOLDOWN_MS = 5 * 60 * 1000;
+
 const CRAWL_RENDERER_CHEERIO = 'cheerio' as 'cheerio';
 const CRAWL_RENDERER_PLAYWRIGHT = 'playwright' as 'playwright';
 const CRAWL_RENDERERS = [CRAWL_RENDERER_CHEERIO, CRAWL_RENDERER_PLAYWRIGHT];
@@ -850,6 +877,25 @@ const CHUNK_TARGET_CHARS = 2000;
 const CHUNK_OVERLAP_CHARS = 200;
 const EMBED_BATCH_SIZE = 96;
 
+// Hybrid resource search. Each ranker contributes its top candidates, and the
+// two lists are merged with reciprocal rank fusion: score = sum of 1/(k + rank).
+// Fusion reads ranks, never raw scores, so a cosine distance and a ts_rank never
+// have to be put on one scale. k = 60 is the constant from the original RRF
+// paper; it keeps one list's #1 from outweighing a chunk both lists agree on.
+const RESOURCE_SEARCH_CANDIDATES = 50;
+const RESOURCE_SEARCH_RRF_K = 60;
+// A query word found in more than 1 of every 10 chunks of the artifact is
+// dropped from the lexical query — never below 5 chunks, so a small artifact
+// keeps its words.
+const RESOURCE_SEARCH_COMMON_TERM_DIVISOR = 10;
+const RESOURCE_SEARCH_COMMON_TERM_MIN = 5;
+// Second stage, on wherever the Worker has an AI binding: the top fused
+// candidates are re-scored by a cross-encoder, which reads query and chunk
+// together instead of comparing two independently computed vectors. One model
+// call per search; a failure falls back to the fused order.
+const RESOURCE_SEARCH_RERANK_CANDIDATES = 30;
+const RESOURCE_SEARCH_RERANK_MODEL = '@cf/baai/bge-reranker-base';
+
 const RESOURCE_HANDLER_SLEEP_AFTER = '10m';
 
 const DOCS_URL = 'https://docs.ganju.ai';
@@ -1207,8 +1253,7 @@ const MCP_PROXY_TOOL_NAME_MAX = 64;
 //
 // The row's config holds only `activeVersionId` plus the egress/limit settings;
 // names and schemas live on the version. That's what keeps MCP boot off the
-// dispatcher — a slow or broken script must never break tools/list. See
-// docs/CUSTOM_TOOLS.md ("Boot contract").
+// dispatcher — a slow or broken script must never break tools/list.
 const TOOL_DEFINITION_KEY_CUSTOM_CODE = 'custom-code';
 
 // A version is uploaded as `draft`, becomes `published` when it is made active,
@@ -1996,6 +2041,12 @@ interface PlanLimits {
   // against). Not used for blocking.
   includedMessages: number;
   includedEmbeddedBytes: number;
+  // The intervals the hourly job will sync a source on. Empty = no automatic
+  // sync: the org can still sync a source by hand. Refreshing costs crawl or
+  // Drive fetches plus embeddings for whatever changed, all on our side.
+  autoSyncIntervals: ReadonlyArray<
+    typeof RESOURCE_SYNC_INTERVAL_DAILY | typeof RESOURCE_SYNC_INTERVAL_WEEKLY
+  >;
 }
 
 const PLAN_LIMITS: Record<
@@ -2035,7 +2086,8 @@ const PLAN_LIMITS: Record<
     includedToolCalls: 0,
     toolCallHardCap: 10_000,
     includedMessages: 100,
-    includedEmbeddedBytes: 5 * MB
+    includedEmbeddedBytes: 5 * MB,
+    autoSyncIntervals: []
   },
   PRO: {
     maxProjects: null,
@@ -2058,7 +2110,11 @@ const PLAN_LIMITS: Record<
     includedToolCalls: PRICING_INCLUDED_TOOL_CALLS,
     toolCallHardCap: PRICING_TOOL_CALL_HARD_CAP,
     includedMessages: PRICING_INCLUDED_MESSAGES,
-    includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB
+    includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB,
+    autoSyncIntervals: [
+      RESOURCE_SYNC_INTERVAL_DAILY,
+      RESOURCE_SYNC_INTERVAL_WEEKLY
+    ]
   },
   ENTERPRISE: {
     maxProjects: null,
@@ -2081,7 +2137,11 @@ const PLAN_LIMITS: Record<
     // contract; don't make one plan's abuse limit another plan's product limit.
     toolCallHardCap: null,
     includedMessages: PRICING_INCLUDED_MESSAGES,
-    includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB
+    includedEmbeddedBytes: PRICING_INCLUDED_EMBEDDED_GB * GB,
+    autoSyncIntervals: [
+      RESOURCE_SYNC_INTERVAL_DAILY,
+      RESOURCE_SYNC_INTERVAL_WEEKLY
+    ]
   }
 };
 
@@ -2100,6 +2160,7 @@ const PLAN_FEATURE_RAW_STORAGE = 'rawStorage' as 'rawStorage';
 const PLAN_FEATURE_EMBEDDED_STORAGE = 'embeddedStorage' as 'embeddedStorage';
 const PLAN_FEATURE_MESSAGE = 'message' as 'message';
 const PLAN_FEATURE_TOOL_CALL = 'toolCall' as 'toolCall';
+const PLAN_FEATURE_RESOURCE_SYNC = 'resourceSync' as 'resourceSync';
 
 // Stable code returned on a quota block so clients can branch on it (402).
 const PLAN_LIMIT_ERROR_CODE = 'PLAN_LIMIT_EXCEEDED';
@@ -2282,6 +2343,7 @@ export const constants = {
   PLAN_FEATURE_EMBEDDED_STORAGE,
   PLAN_FEATURE_MESSAGE,
   PLAN_FEATURE_TOOL_CALL,
+  PLAN_FEATURE_RESOURCE_SYNC,
   PLAN_LIMIT_ERROR_CODE,
   BILLING_METER_MESSAGES,
   BILLING_METER_SHARED_MESSAGES,
@@ -2476,6 +2538,14 @@ export const constants = {
   RESOURCE_SOURCE_TYPE_ONE_DRIVE_FOLDER,
   RESOURCE_SOURCE_TYPE_CUSTOM_CODE,
   RESOURCE_SOURCE_TYPES,
+  RESOURCE_SYNC_INTERVAL_OFF,
+  RESOURCE_SYNC_INTERVAL_DAILY,
+  RESOURCE_SYNC_INTERVAL_WEEKLY,
+  RESOURCE_SYNC_INTERVALS,
+  RESOURCE_SYNC_INTERVAL_DEFAULT,
+  RESOURCE_SYNC_INTERVAL_MS,
+  RESOURCE_SYNC_BATCH_SIZE,
+  RESOURCE_SYNC_MANUAL_COOLDOWN_MS,
   CRAWL_RENDERER_CHEERIO,
   CRAWL_RENDERER_PLAYWRIGHT,
   CRAWL_RENDERERS,
@@ -2597,6 +2667,12 @@ export const constants = {
   CHUNK_TARGET_CHARS,
   CHUNK_OVERLAP_CHARS,
   EMBED_BATCH_SIZE,
+  RESOURCE_SEARCH_CANDIDATES,
+  RESOURCE_SEARCH_RRF_K,
+  RESOURCE_SEARCH_COMMON_TERM_DIVISOR,
+  RESOURCE_SEARCH_COMMON_TERM_MIN,
+  RESOURCE_SEARCH_RERANK_CANDIDATES,
+  RESOURCE_SEARCH_RERANK_MODEL,
   RESOURCE_HANDLER_SLEEP_AFTER,
   DOCS_URL,
   BASE64_DATA_URI_RE,

package/src/index.ts

@@ -117,6 +117,11 @@ import type { OAuthProviderConfig } from './oauthProviders';
 import { resolveAttachment } from './attachment';
 import { isExposedResource } from './exposedResource';
 import type { ExposableResource } from './exposedResource';
+import { isSyncableResource, resourceSyncProvider } from './syncableResource';
+import type {
+  SyncableResource,
+  ResourceSyncProvider
+} from './syncableResource';
 import { describeVendorError } from './vendorError';
 import { withDeadline, isDeadlineError } from './deadline';
 import {
@@ -186,6 +191,8 @@ import {
 import type { Separator, ChunkMetadata, PreparedChunk } from './chunking';
 import { isEmbeddableMimeType } from './embeddable';
 import { l2Normalize } from './l2Normalize';
+import { createResourceReranker } from './resourceRerank';
+import type { RerankAiBinding } from './resourceRerank';
 import { sleep, isRateLimitError, withRateLimitRetry } from './retry';
 import type { RateLimitRetryOptions } from './retry';
 import { processQueueBatch } from './processQueueBatch';
@@ -204,10 +211,12 @@ import type { ChannelNotifier, ToolStatusEvent } from './channelNotifier';
 import {
   resolveDebounceMs,
   channelBufferKey,
-  joinBufferedMessages
+  joinBufferedMessages,
+  batchCommand
 } from './channelDebounce';
 import type {
   BufferedChannelMessage,
+  BufferedChannelCommand,
   ChannelBufferEnvelope,
   ChannelBufferFlush
 } from './channelDebounce';
@@ -291,6 +300,8 @@ export const utils = {
   oauthProviders,
   resolveAttachment,
   isExposedResource,
+  isSyncableResource,
+  resourceSyncProvider,
   describeVendorError,
   withDeadline,
   isDeadlineError,
@@ -337,6 +348,7 @@ export const utils = {
   prepareChunks,
   isEmbeddableMimeType,
   l2Normalize,
+  createResourceReranker,
   sleep,
   isRateLimitError,
   withRateLimitRetry,
@@ -344,6 +356,7 @@ export const utils = {
   getToolStatusMessage,
   resolveDebounceMs,
   channelBufferKey,
+  batchCommand,
   joinBufferedMessages,
   isResourceSourceEnabled,
   isDownloadableSource,
@@ -407,12 +420,14 @@ export type {
   ExtractedDocumentMetadata,
   ExtractedDocumentSource,
   RateLimitRetryOptions,
+  RerankAiBinding,
   QueueBatchLike,
   QueueMessageLike,
   ProcessQueueBatchHandlers,
   ChannelNotifier,
   ToolStatusEvent,
   BufferedChannelMessage,
+  BufferedChannelCommand,
   ChannelBufferEnvelope,
   ChannelBufferFlush,
   Source,
@@ -438,6 +453,8 @@ export type {
   ResolvedAttachment,
   ResolveAttachmentResult,
   ExposableResource,
+  SyncableResource,
+  ResourceSyncProvider,
   PlanLimitDetails,
   PlanLimits
 };

package/src/resourceRerank.ts

@@ -0,0 +1,54 @@
+import { constants } from './constants';
+import type { EnvSource } from './getEnv';
+
+// The slice of the Workers AI binding the reranker calls. Declared here rather
+// than imported so this package doesn't take a dependency on workers-types.
+export interface RerankAiBinding {
+  run(
+    model: string,
+    input: { query: string; contexts: Array<{ text: string }>; top_k?: number }
+  ): Promise<unknown>;
+}
+
+type RerankResponse = {
+  response?: Array<{ id?: number; score?: number }>;
+};
+
+/**
+ * The cross-encoder second stage for resource search, or undefined when the
+ * Worker has no `AI` binding — local dev without Workers AI keeps plain fusion.
+ *
+ * Returns one score per document, in input order. A response that doesn't
+ * cover every document returns null, which keeps the fused order — a partial
+ * ranking would silently drop the chunks it left out.
+ */
+export const createResourceReranker = (
+  source: EnvSource
+):
+  | ((query: string, documents: string[]) => Promise<number[] | null>)
+  | undefined => {
+  const ai = (source.env as { AI?: RerankAiBinding } | undefined)?.AI;
+  if (!ai) return undefined;
+
+  return async (query, documents) => {
+    const result = (await ai.run(constants.RESOURCE_SEARCH_RERANK_MODEL, {
+      query,
+      contexts: documents.map(text => ({ text })),
+      top_k: documents.length
+    })) as RerankResponse;
+
+    const scores: Array<number | undefined> = new Array(documents.length);
+    for (const item of result?.response ?? []) {
+      if (
+        typeof item.id === 'number' &&
+        typeof item.score === 'number' &&
+        item.id >= 0 &&
+        item.id < documents.length
+      ) {
+        scores[item.id] = item.score;
+      }
+    }
+    if (scores.some(score => score === undefined)) return null;
+    return scores as number[];
+  };
+};

package/src/schema.ts

@@ -1449,6 +1449,21 @@ const ARTIFACT_UPDATE_RESOURCE_SHOW_SOURCE = z.object({
   organizationId: z.uuid()
 });
 
+const ARTIFACT_UPDATE_RESOURCE_SYNC_INTERVAL = z.object({
+  resourceId: z.uuid(),
+  syncInterval: z.enum(constants.RESOURCE_SYNC_INTERVALS),
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
+const ARTIFACT_SYNC_RESOURCE = z.object({
+  resourceId: z.uuid(),
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid()
+});
+
 const ARTIFACT_GET = z.object({
   projectId: z.uuid(),
   userId: z.uuid(),
@@ -1625,6 +1640,8 @@ export const Schema = {
   CHANNEL_LIST_CONVERSATIONS,
   CHANNEL_LIST_MESSAGES,
   ARTIFACT_UPDATE_RESOURCE_SHOW_SOURCE,
+  ARTIFACT_UPDATE_RESOURCE_SYNC_INTERVAL,
+  ARTIFACT_SYNC_RESOURCE,
   HTTP_ENDPOINT_CONFIG,
   HTTP_ENDPOINT_CONFIG_WRITE,
   MCP_PROXY_CONFIG,

package/src/syncableResource.ts

@@ -0,0 +1,48 @@
+import { constants } from './constants';
+
+// Which resources are sync roots: the rows a sync starts from and records its
+// schedule on.
+//
+//  - a WEBSITE seed (the row with no parent) — a sync re-crawls the site;
+//  - a Drive/OneDrive folder — a sync walks it for new, changed and removed
+//    files;
+//  - a Drive/OneDrive file imported on its own — a sync re-fetches it when it
+//    changed.
+//
+// A page under a website or a file under a folder is not a root: its parent's
+// sync covers it. An uploaded file has nothing to sync from.
+export interface SyncableResource {
+  sourceType?: string | null;
+  parentResourceId?: string | null;
+  metadata?: unknown;
+}
+
+export type ResourceSyncProvider = 'website' | 'google-drive' | 'one-drive';
+
+export const resourceSyncProvider = (
+  resource: SyncableResource
+): ResourceSyncProvider | null => {
+  if (resource.parentResourceId) return null;
+  switch (resource.sourceType) {
+    case constants.RESOURCE_SOURCE_TYPE_WEBSITE:
+      return 'website';
+    case constants.RESOURCE_SOURCE_TYPE_GOOGLE_DRIVE_FOLDER:
+      return 'google-drive';
+    case constants.RESOURCE_SOURCE_TYPE_ONE_DRIVE_FOLDER:
+      return 'one-drive';
+    case constants.RESOURCE_SOURCE_TYPE_FILE: {
+      const meta =
+        resource.metadata && typeof resource.metadata === 'object'
+          ? (resource.metadata as Record<string, unknown>)
+          : null;
+      if (typeof meta?.driveFileId === 'string') return 'google-drive';
+      if (typeof meta?.oneDriveItemId === 'string') return 'one-drive';
+      return null;
+    }
+    default:
+      return null;
+  }
+};
+
+export const isSyncableResource = (resource: SyncableResource): boolean =>
+  resourceSyncProvider(resource) !== null;

package/src/toolCatalog.ts

@@ -469,7 +469,7 @@ export const TOOL_CATALOG = [
         key: 'search-resources',
         title: 'Search Resources',
         description:
-          'Find the resources most relevant to a question using semantic search.',
+          'Find the resources most relevant to a question, by meaning and by exact keywords.',
         requiredScopes: null
       },
       {