@ganju/utils 0.0.8 → 0.0.10

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];
@@ -622,8 +649,8 @@ const LLM_CATALOG: ReadonlyArray<{
 }> = [
   {
     provider: LLM_PROVIDER_GOOGLE,
-    model: 'gemini-3-flash-preview',
-    label: 'Gemini 3 Flash'
+    model: 'gemini-3.8-flash',
+    label: 'Gemini 3.8 Flash'
   },
   {
     provider: LLM_PROVIDER_GOOGLE,
@@ -632,13 +659,13 @@ const LLM_CATALOG: ReadonlyArray<{
   },
   {
     provider: LLM_PROVIDER_OPENAI,
-    model: 'gpt-4o-mini',
-    label: 'GPT-4o mini'
+    model: 'gpt-5.4-mini',
+    label: 'GPT-5.4 mini'
   },
   {
     provider: LLM_PROVIDER_OPENAI,
-    model: 'gpt-4o',
-    label: 'GPT-4o'
+    model: 'gpt-5.5',
+    label: 'GPT-5.5'
   },
   {
     provider: LLM_PROVIDER_ANTHROPIC,
@@ -647,16 +674,35 @@ const LLM_CATALOG: ReadonlyArray<{
   },
   {
     provider: LLM_PROVIDER_ANTHROPIC,
-    model: 'claude-sonnet-4-6',
-    label: 'Claude Sonnet 4.6'
+    model: 'claude-sonnet-5',
+    label: 'Claude Sonnet 5'
   },
   {
     provider: LLM_PROVIDER_ANTHROPIC,
-    model: 'claude-opus-4.7',
-    label: 'Claude Sonnet 4.7'
+    model: 'claude-opus-5',
+    label: 'Claude Opus 5'
   }
 ];
 
+// The picker's escape hatch. Anything that speaks the OpenAI chat-completions
+// protocol — a gateway, an aggregator, a self-hosted server — is reachable
+// without a catalog row: the customer supplies the model id and the base URL,
+// and the request goes out through the OpenAI adapter. Not a provider value, so
+// it can never reach the database; the dashboard translates it into
+// LLM_PROVIDER_OPENAI_COMPATIBLE on submit.
+const LLM_CATALOG_CUSTOM_KEY = 'custom';
+
+// Validation messages for an organization LLM's base URL. Constants rather than
+// inline strings because localizeZodIssue keys its translations on the exact
+// English text, so the two files have to name the same value. Both also carry a
+// word matchStatus recognises ("required", "must be"): the update path re-checks
+// the merged row and throws the message as a plain Error, and anything
+// unrecognised there becomes an opaque 500 instead of a 400.
+const LLM_BASE_URL_REQUIRED_MESSAGE =
+  'A base URL is required for an OpenAI-compatible model';
+const LLM_BASE_URL_INVALID_MESSAGE =
+  'Base URL must be a public https:// address';
+
 const LLM_SYSTEM_DEFAULT = 'SYSTEM_DEFAULT';
 
 const MAX_TOOL_LOOPS = 8;
@@ -831,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';
@@ -1188,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,
@@ -1977,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<
@@ -2016,7 +2086,8 @@ const PLAN_LIMITS: Record<
     includedToolCalls: 0,
     toolCallHardCap: 10_000,
     includedMessages: 100,
-    includedEmbeddedBytes: 5 * MB
+    includedEmbeddedBytes: 5 * MB,
+    autoSyncIntervals: []
   },
   PRO: {
     maxProjects: null,
@@ -2039,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,
@@ -2062,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
+    ]
   }
 };
 
@@ -2081,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';
@@ -2128,7 +2208,7 @@ const POLAR_SERVER_PRODUCTION = 'production' as 'production';
 const CONSENT_DOCUMENT_TERMS = 'terms' as 'terms';
 const CONSENT_DOCUMENT_PRIVACY = 'privacy' as 'privacy';
 const CONSENT_DOCUMENTS = [CONSENT_DOCUMENT_TERMS, CONSENT_DOCUMENT_PRIVACY];
-const CONSENT_CURRENT_VERSION = '2026-08-31';
+const CONSENT_CURRENT_VERSION = '2026-09-10';
 
 const CONSENT_SOURCE_SIGNUP = 'signup' as 'signup';
 const CONSENT_SOURCE_REACCEPT = 'reaccept' as 'reaccept';
@@ -2263,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,
@@ -2457,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,
@@ -2506,6 +2595,9 @@ export const constants = {
   DEFAULT_LLM_MODEL,
   DEFAULT_LLM_SYSTEM_PROMPT,
   LLM_CATALOG,
+  LLM_CATALOG_CUSTOM_KEY,
+  LLM_BASE_URL_REQUIRED_MESSAGE,
+  LLM_BASE_URL_INVALID_MESSAGE,
   LLM_SYSTEM_DEFAULT,
   MAX_TOOL_LOOPS,
   CHANNEL_HISTORY_LIMIT,
@@ -2575,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 {
@@ -134,6 +139,11 @@ import type {
   ResolveAttachmentResult
 } from './attachment';
 import { ipv4InPrivateRange, isBlockedHost } from './ssrf';
+import {
+  requiresLlmBaseUrl,
+  isAllowedLlmBaseUrl,
+  llmBaseUrlIssue
+} from './llmBaseUrl';
 import { formatRelative } from './formatRelative';
 import { formatRelativeTime } from './formatRelativeTime';
 import { languageCookieDomain } from './languageCookieDomain';
@@ -181,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';
@@ -199,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';
@@ -286,6 +300,8 @@ export const utils = {
   oauthProviders,
   resolveAttachment,
   isExposedResource,
+  isSyncableResource,
+  resourceSyncProvider,
   describeVendorError,
   withDeadline,
   isDeadlineError,
@@ -297,6 +313,9 @@ export const utils = {
   projectPathIssue,
   ipv4InPrivateRange,
   isBlockedHost,
+  requiresLlmBaseUrl,
+  isAllowedLlmBaseUrl,
+  llmBaseUrlIssue,
   validateMessageVariables,
   formatRelative,
   formatRelativeTime,
@@ -329,6 +348,7 @@ export const utils = {
   prepareChunks,
   isEmbeddableMimeType,
   l2Normalize,
+  createResourceReranker,
   sleep,
   isRateLimitError,
   withRateLimitRetry,
@@ -336,6 +356,7 @@ export const utils = {
   getToolStatusMessage,
   resolveDebounceMs,
   channelBufferKey,
+  batchCommand,
   joinBufferedMessages,
   isResourceSourceEnabled,
   isDownloadableSource,
@@ -399,12 +420,14 @@ export type {
   ExtractedDocumentMetadata,
   ExtractedDocumentSource,
   RateLimitRetryOptions,
+  RerankAiBinding,
   QueueBatchLike,
   QueueMessageLike,
   ProcessQueueBatchHandlers,
   ChannelNotifier,
   ToolStatusEvent,
   BufferedChannelMessage,
+  BufferedChannelCommand,
   ChannelBufferEnvelope,
   ChannelBufferFlush,
   Source,
@@ -430,6 +453,8 @@ export type {
   ResolvedAttachment,
   ResolveAttachmentResult,
   ExposableResource,
+  SyncableResource,
+  ResourceSyncProvider,
   PlanLimitDetails,
   PlanLimits
 };

package/src/llmBaseUrl.ts

@@ -0,0 +1,65 @@
+import { constants } from './constants';
+import { isBlockedHost } from './ssrf';
+
+/**
+ * The rules an `organization_llm.base_url` has to satisfy, in one place.
+ *
+ * Two write paths need them and neither can see the whole picture alone: the
+ * create schema validates a complete payload, while an update is a partial, so
+ * the provider may arrive in the request and the base URL may only exist on the
+ * stored row. Keeping the rules here means the two can't drift into disagreeing
+ * about what a valid row is — the same reason every other write in this package
+ * goes through a shared validator rather than an inline check.
+ */
+
+/**
+ * Which providers need a base URL of their own.
+ *
+ * Every other provider has an endpoint baked into its SDK. `openai-compatible`
+ * has none: it is the escape hatch for services that merely speak the OpenAI
+ * protocol, so without a base URL the adapter would send the customer's key to
+ * `api.openai.com` and fail somewhere far from the form they typed it into.
+ */
+export const requiresLlmBaseUrl = (provider?: string | null): boolean =>
+  provider === constants.LLM_PROVIDER_OPENAI_COMPATIBLE;
+
+/**
+ * Whether a base URL is safe to send a request to.
+ *
+ * This is an outbound fetch target chosen by a customer, on a worker holding
+ * their decrypted API key, so it gets the same screening as every other
+ * caller-supplied URL: `https` only, because the key travels in a header, and
+ * no loopback, private or link-local host. The Workers runtime can't resolve
+ * DNS, so — as everywhere else `isBlockedHost` is used — this screens literal
+ * hosts and IPs and is not a defense against DNS rebinding.
+ */
+export const isAllowedLlmBaseUrl = (value: string): boolean => {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== 'https:') return false;
+  return !isBlockedHost(parsed.hostname);
+};
+
+/**
+ * Both rules against one provider/base-URL pair: the message to reject with, or
+ * `null` when the pair is acceptable. The messages are constants so
+ * `localizeZodIssue` can translate them, and both carry a word `matchStatus`
+ * recognises — the update path throws this as a plain Error rather than a
+ * ZodError, and an unrecognised message there answers 500 where it means 400.
+ */
+export const llmBaseUrlIssue = (
+  provider?: string | null,
+  baseUrl?: string | null
+): string | null => {
+  if (requiresLlmBaseUrl(provider) && !baseUrl) {
+    return constants.LLM_BASE_URL_REQUIRED_MESSAGE;
+  }
+  if (baseUrl && !isAllowedLlmBaseUrl(baseUrl)) {
+    return constants.LLM_BASE_URL_INVALID_MESSAGE;
+  }
+  return null;
+};

package/src/localizeZodIssue.ts

@@ -74,6 +74,12 @@ const CUSTOM_MESSAGES: Record<string, Record<string, string>> = {
   },
   [constants.CUSTOM_CODE_RESOURCE_FILE_TOO_LARGE_MESSAGE]: {
     es: `Los bytes del archivo superan el límite de ${constants.CUSTOM_CODE_MAX_RESOURCE_FILE_BYTES / (1024 * 1024)}MB`
+  },
+  [constants.LLM_BASE_URL_REQUIRED_MESSAGE]: {
+    es: 'Se requiere una URL base para un modelo compatible con OpenAI'
+  },
+  [constants.LLM_BASE_URL_INVALID_MESSAGE]: {
+    es: 'La URL base debe ser una dirección https:// pública'
   }
 };
 

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 
 import { constants } from './constants';
+import { isAllowedLlmBaseUrl, requiresLlmBaseUrl } from './llmBaseUrl';
 import { isReservedSlug, isValidSlugFormat } from './slug';
 import { isReservedToolName } from './reservedToolName';
 import { slugifyTitle } from './slugifyTitle';
@@ -572,11 +573,33 @@ const ORGANIZATION_LIST_LLM = z.object({
   organizationId: z.uuid()
 });
 
-const ORGANIZATION_CREATE_LLM = z.object({
+// The two rules live in `llmBaseUrl.ts`, because the update controller applies
+// them again to the merged row — the only place both halves are visible. Here
+// they are just the field validator and the cross-field check.
+const LLM_BASE_URL = z
+  .url()
+  .max(500)
+  .refine(isAllowedLlmBaseUrl, constants.LLM_BASE_URL_INVALID_MESSAGE);
+
+const BASE_URL_REQUIRED = {
+  message: constants.LLM_BASE_URL_REQUIRED_MESSAGE,
+  path: ['baseUrl']
+};
+
+const hasBaseUrlWhenRequired = (
+  provider: string | undefined,
+  baseUrl: unknown
+) => !requiresLlmBaseUrl(provider) || !!baseUrl;
+
+// The base-URL rule is a cross-field check, and zod cannot `.omit()` from a
+// schema that already carries one. So the shape stays a plain object — the
+// `_VIEW` variants below derive from it — and the refinement is applied last,
+// to each schema in turn, which also keeps the two in step.
+const ORGANIZATION_CREATE_LLM_SHAPE = z.object({
   name: z.string().min(1).max(200),
   provider: z.enum(constants.LLM_PROVIDERS),
   model: z.string().min(1).max(200),
-  baseUrl: z.url().optional().or(z.literal('')),
+  baseUrl: LLM_BASE_URL.optional().or(z.literal('')),
   apiKey: z.string().min(1).max(500),
   systemPrompt: z.string().max(10000).optional(),
   config: z.record(z.string(), z.any()).optional(),
@@ -584,12 +607,21 @@ const ORGANIZATION_CREATE_LLM = z.object({
   organizationId: z.uuid()
 });
 
-const ORGANIZATION_UPDATE_LLM = z.object({
+const ORGANIZATION_CREATE_LLM = ORGANIZATION_CREATE_LLM_SHAPE.refine(
+  v => hasBaseUrlWhenRequired(v.provider, v.baseUrl),
+  BASE_URL_REQUIRED
+);
+
+// An update is a partial: an omitted field keeps its stored value, so the
+// base-URL rule can only be checked here when the caller sends the provider and
+// the base URL together. The controller re-checks it against the merged row,
+// which is the only place both halves are known.
+const ORGANIZATION_UPDATE_LLM_SHAPE = z.object({
   llmId: z.uuid(),
   name: z.string().min(1).max(200).optional(),
   provider: z.enum(constants.LLM_PROVIDERS).optional(),
   model: z.string().min(1).max(200).optional(),
-  baseUrl: z.url().optional().or(z.literal('')).nullable(),
+  baseUrl: LLM_BASE_URL.optional().or(z.literal('')).nullable(),
   apiKey: z.string().min(1).max(500).optional(),
   systemPrompt: z.string().max(10000).optional().nullable(),
   config: z.record(z.string(), z.any()).optional().nullable(),
@@ -597,6 +629,21 @@ const ORGANIZATION_UPDATE_LLM = z.object({
   organizationId: z.uuid()
 });
 
+const refineUpdateBaseUrl = <
+  T extends z.ZodType<{ provider?: string; baseUrl?: unknown }>
+>(
+  schema: T
+) =>
+  schema.refine(
+    v =>
+      v.baseUrl === undefined || hasBaseUrlWhenRequired(v.provider, v.baseUrl),
+    BASE_URL_REQUIRED
+  );
+
+const ORGANIZATION_UPDATE_LLM = refineUpdateBaseUrl(
+  ORGANIZATION_UPDATE_LLM_SHAPE
+);
+
 const ORGANIZATION_REMOVE_LLM = z.object({
   llmId: z.uuid(),
   userId: z.uuid(),
@@ -649,16 +696,21 @@ const ACCESS_TOKEN_CREATE_VIEW = ACCESS_TOKEN_CREATE.omit({
   projectId: true
 });
 
-const ORGANIZATION_CREATE_LLM_VIEW = ORGANIZATION_CREATE_LLM.omit({
+const ORGANIZATION_CREATE_LLM_VIEW = ORGANIZATION_CREATE_LLM_SHAPE.omit({
   userId: true,
   organizationId: true
-});
+}).refine(
+  v => hasBaseUrlWhenRequired(v.provider, v.baseUrl),
+  BASE_URL_REQUIRED
+);
 
-const ORGANIZATION_UPDATE_LLM_VIEW = ORGANIZATION_UPDATE_LLM.omit({
-  llmId: true,
-  userId: true,
-  organizationId: true
-});
+const ORGANIZATION_UPDATE_LLM_VIEW = refineUpdateBaseUrl(
+  ORGANIZATION_UPDATE_LLM_SHAPE.omit({
+    llmId: true,
+    userId: true,
+    organizationId: true
+  })
+);
 
 // `channel.config` is an open bag, so this stays loose — it only pins down the
 // keys we actually read, and passes everything else through untouched.
@@ -1397,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(),
@@ -1573,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
       },
       {