@ganju/utils 0.0.9 → 0.0.11

package/src/constants.ts

@@ -278,6 +278,43 @@ 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;
+// How long a sync may stay PENDING before it counts as stuck rather than
+// running. A lost queue message or a job that exhausted its retries never
+// completes its root, and a root that stays PENDING would otherwise be skipped
+// by the hourly job and refused by "Sync now" forever. Twelve hours outlasts
+// any realistic wait: the crawl-page queue runs 5 at a time for every org, and
+// one hourly run can queue 50 sites — thousands of pages, hours of backlog. A
+// shorter window restarts syncs that are merely queued, re-fetching every page
+// into the same backlog; a longer one leaves a stuck daily source missing more
+// than one sync.
+const RESOURCE_SYNC_STALE_MS = 12 * 60 * 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];
@@ -731,6 +768,49 @@ const CHANNEL_DEBOUNCE_JOIN = '\n';
 const CHANNEL_DEBOUNCE_RETRY_MS = 5000;
 const CHANNEL_DEBOUNCE_MAX_ATTEMPTS = 3;
 
+// Confirming sensitive actions, for organizations that turn it on. A channel
+// bot that wants to run a tool annotated `destructiveHint` asks first, and the
+// call runs only if the participant's next message is a plain yes.
+//
+// How long the question stays open. An answer after that is read as a new
+// message, never as consent to something asked long ago.
+const TOOL_CONFIRMATION_TTL_MS = 30 * 60 * 1000;
+// The tool result the model gets instead of running the call. It is what makes
+// the model write the question — in the participant's language, naming what
+// the call would do — rather than claiming the action happened.
+// The call's exact arguments are listed under the model's question by the
+// runner, so the model only has to say what it is about to do.
+const TOOL_CONFIRMATION_REQUIRED_RESULT =
+  'Not run yet: this action needs the user to confirm it first. In one or ' +
+  'two sentences, tell them what it will do (who it goes to, what will be ' +
+  'changed or deleted) and ask them to answer yes to go ahead or no to ' +
+  'cancel — in their own language, never quoting English words at someone ' +
+  'writing in another one. The exact details are listed for them under your ' +
+  'message. It runs only if their next message is yes. Do not say it was done.';
+// Told to the model on every turn of an organization that confirms: the
+// asking is done for it, so it calls the tool when asked instead of asking
+// first itself — and calls every action a request needs in one step, since
+// the turn stops at the first held call and each later one would be a
+// question of its own.
+const TOOL_CONFIRMATION_SYSTEM_NOTE =
+  'Actions that send, change or delete something are confirmed with the ' +
+  'user by the system before they run. Ask for any detail you are missing, ' +
+  'but once you have what the action needs, call the tool — do not ask the ' +
+  'user to confirm it yourself; the system asks them and runs it on their ' +
+  'yes. When a request needs several such actions (say, delete an event ' +
+  'and create its replacement), call them all in the same step, so the ' +
+  'user confirms them together once.';
+// The system-prompt addition for the step that writes the question, with the
+// held actions' names in place of {{actions}}.
+const TOOL_CONFIRMATION_ASK_INSTRUCTION =
+  'IMPORTANT: these actions have NOT been done: {{actions}}. They are ' +
+  'waiting for the user to confirm them. Your reply must ask the user to ' +
+  'confirm, and must not say or suggest that they were done, nor describe ' +
+  'or make up any result from them.';
+// The question when the model wrote none, above the runner's own summary.
+const TOOL_CONFIRMATION_FALLBACK_QUESTION =
+  'Before I do this, please confirm. Reply yes to go ahead, or no to cancel.';
+
 const TELEGRAM_SECRET_HEADER = 'x-telegram-bot-api-secret-token';
 const TELEGRAM_API_BASE = 'https://api.telegram.org';
 const TELEGRAM_MESSAGE_LIMIT = 3500;
@@ -790,8 +870,12 @@ const DISCORD_TIMESTAMP_HEADER = 'x-signature-timestamp';
 // Interaction request types and response types (Discord API).
 const DISCORD_INTERACTION_TYPE_PING = 1;
 const DISCORD_INTERACTION_TYPE_APPLICATION_COMMAND = 2;
+// A tap on a message button — the Yes/No under a confirmation question.
+const DISCORD_INTERACTION_TYPE_MESSAGE_COMPONENT = 3;
 const DISCORD_INTERACTION_RESPONSE_PONG = 1;
 const DISCORD_INTERACTION_RESPONSE_DEFERRED = 5;
+// Edits the message the tapped button is on, in the same response.
+const DISCORD_INTERACTION_RESPONSE_UPDATE_MESSAGE = 7;
 // Channel types we map to conversation scopes: DM (1) / group DM (3) = private;
 // everything else (guild text channels, threads) = channel.
 const DISCORD_CHANNEL_TYPE_DM = 1;
@@ -820,6 +904,8 @@ const WHATSAPP_API_BASE = 'https://graph.facebook.com';
 const WHATSAPP_API_VERSION = 'v25.0';
 // A WhatsApp text message body caps at 4096 chars; we chunk a bit under that.
 const WHATSAPP_MESSAGE_LIMIT = 4000;
+// The body of an interactive (reply-button) message holds at most this much.
+const WHATSAPP_INTERACTIVE_BODY_LIMIT = 1024;
 const WHATSAPP_SIGNATURE_HEADER = 'x-hub-signature-256';
 const WHATSAPP_SIGNATURE_PREFIX = 'sha256=';
 // GET-handshake query params + the expected hub.mode value.
@@ -850,6 +936,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 +1312,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 +2100,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 +2145,8 @@ const PLAN_LIMITS: Record<
     includedToolCalls: 0,
     toolCallHardCap: 10_000,
     includedMessages: 100,
-    includedEmbeddedBytes: 5 * MB
+    includedEmbeddedBytes: 5 * MB,
+    autoSyncIntervals: []
   },
   PRO: {
     maxProjects: null,
@@ -2058,7 +2169,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 +2196,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 +2219,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 +2402,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 +2597,15 @@ 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,
+  RESOURCE_SYNC_STALE_MS,
   CRAWL_RENDERER_CHEERIO,
   CRAWL_RENDERER_PLAYWRIGHT,
   CRAWL_RENDERERS,
@@ -2534,6 +2664,11 @@ export const constants = {
   SHARED_KEY_HISTORY_LIMIT,
   SHARED_KEY_MAX_TOOL_LOOPS,
   CHANNEL_MAX_TOOLS,
+  TOOL_CONFIRMATION_TTL_MS,
+  TOOL_CONFIRMATION_REQUIRED_RESULT,
+  TOOL_CONFIRMATION_FALLBACK_QUESTION,
+  TOOL_CONFIRMATION_ASK_INSTRUCTION,
+  TOOL_CONFIRMATION_SYSTEM_NOTE,
   CHANNEL_DEBOUNCE_DEFAULT_MS,
   CHANNEL_DEBOUNCE_MIN_MS,
   CHANNEL_DEBOUNCE_MAX_MS,
@@ -2566,8 +2701,10 @@ export const constants = {
   DISCORD_TIMESTAMP_HEADER,
   DISCORD_INTERACTION_TYPE_PING,
   DISCORD_INTERACTION_TYPE_APPLICATION_COMMAND,
+  DISCORD_INTERACTION_TYPE_MESSAGE_COMPONENT,
   DISCORD_INTERACTION_RESPONSE_PONG,
   DISCORD_INTERACTION_RESPONSE_DEFERRED,
+  DISCORD_INTERACTION_RESPONSE_UPDATE_MESSAGE,
   DISCORD_CHANNEL_TYPE_DM,
   DISCORD_CHANNEL_TYPE_GROUP_DM,
   DISCORD_GATEWAY_OP_DISPATCH,
@@ -2582,6 +2719,7 @@ export const constants = {
   WHATSAPP_API_BASE,
   WHATSAPP_API_VERSION,
   WHATSAPP_MESSAGE_LIMIT,
+  WHATSAPP_INTERACTIVE_BODY_LIMIT,
   WHATSAPP_SIGNATURE_HEADER,
   WHATSAPP_SIGNATURE_PREFIX,
   WHATSAPP_HUB_MODE_PARAM,
@@ -2597,6 +2735,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,15 @@ import type { OAuthProviderConfig } from './oauthProviders';
 import { resolveAttachment } from './attachment';
 import { isExposedResource } from './exposedResource';
 import type { ExposableResource } from './exposedResource';
+import {
+  isSyncableResource,
+  isResourceSyncInProgress,
+  resourceSyncProvider
+} from './syncableResource';
+import type {
+  SyncableResource,
+  ResourceSyncProvider
+} from './syncableResource';
 import { describeVendorError } from './vendorError';
 import { withDeadline, isDeadlineError } from './deadline';
 import {
@@ -164,6 +173,7 @@ import type {
   CatalogGroup,
   CatalogTool,
   CatalogToolDescriptor,
+  ToolAnnotations,
   ToolGroupKey,
   ToolKey
 } from './toolCatalog';
@@ -186,6 +196,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,13 +216,30 @@ import type { ChannelNotifier, ToolStatusEvent } from './channelNotifier';
 import {
   resolveDebounceMs,
   channelBufferKey,
-  joinBufferedMessages
+  joinBufferedMessages,
+  batchCommand
 } from './channelDebounce';
 import type {
   BufferedChannelMessage,
+  BufferedChannelCommand,
   ChannelBufferEnvelope,
   ChannelBufferFlush
 } from './channelDebounce';
+import {
+  isConfirmationReply,
+  confirmationButtonLabels,
+  confirmationButtonId,
+  parseConfirmationButton,
+  languageFromPhoneNumber,
+  formatConfirmationSummary,
+  annotationsForEffect,
+  TOOL_EFFECTS
+} from './toolConfirmation';
+import type {
+  PendingToolConfirmation,
+  PendingToolConfirmations,
+  ToolEffect
+} from './toolConfirmation';
 import {
   isResourceSourceEnabled,
   isDownloadableSource,
@@ -291,6 +320,9 @@ export const utils = {
   oauthProviders,
   resolveAttachment,
   isExposedResource,
+  isSyncableResource,
+  isResourceSyncInProgress,
+  resourceSyncProvider,
   describeVendorError,
   withDeadline,
   isDeadlineError,
@@ -337,6 +369,7 @@ export const utils = {
   prepareChunks,
   isEmbeddableMimeType,
   l2Normalize,
+  createResourceReranker,
   sleep,
   isRateLimitError,
   withRateLimitRetry,
@@ -344,7 +377,16 @@ export const utils = {
   getToolStatusMessage,
   resolveDebounceMs,
   channelBufferKey,
+  batchCommand,
   joinBufferedMessages,
+  isConfirmationReply,
+  confirmationButtonLabels,
+  confirmationButtonId,
+  parseConfirmationButton,
+  languageFromPhoneNumber,
+  formatConfirmationSummary,
+  annotationsForEffect,
+  TOOL_EFFECTS,
   isResourceSourceEnabled,
   isDownloadableSource,
   safeHostname,
@@ -373,6 +415,10 @@ export type {
   CatalogGroup,
   CatalogTool,
   CatalogToolDescriptor,
+  ToolAnnotations,
+  PendingToolConfirmation,
+  PendingToolConfirmations,
+  ToolEffect,
   ToolGroupKey,
   ToolKey,
   CalendarConfigField,
@@ -407,12 +453,14 @@ export type {
   ExtractedDocumentMetadata,
   ExtractedDocumentSource,
   RateLimitRetryOptions,
+  RerankAiBinding,
   QueueBatchLike,
   QueueMessageLike,
   ProcessQueueBatchHandlers,
   ChannelNotifier,
   ToolStatusEvent,
   BufferedChannelMessage,
+  BufferedChannelCommand,
   ChannelBufferEnvelope,
   ChannelBufferFlush,
   Source,
@@ -438,6 +486,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

@@ -5,6 +5,7 @@ import { isAllowedLlmBaseUrl, requiresLlmBaseUrl } from './llmBaseUrl';
 import { isReservedSlug, isValidSlugFormat } from './slug';
 import { isReservedToolName } from './reservedToolName';
 import { slugifyTitle } from './slugifyTitle';
+import { TOOL_EFFECTS } from './toolConfirmation';
 
 // A prompt title becomes a slash command; it must not collide with a command
 // the channel runner handles itself (e.g. `/link`).
@@ -43,11 +44,20 @@ const ORGANIZATION_CREATE_VIEW = z.object({
   projectDescription: z.string().max(500)
 });
 
-const ORGANIZATION_UPDATE = z.object({
-  id: z.uuid(),
-  userId: z.uuid(),
-  name: z.string().min(3).max(100)
-});
+// Each setting is saved on its own — the name from its form, the switches the
+// moment they're flipped — so every field is optional, but not all at once.
+const ORGANIZATION_UPDATE = z
+  .object({
+    id: z.uuid(),
+    userId: z.uuid(),
+    name: z.string().min(3).max(100).optional(),
+    requireToolConfirmation: z.boolean().optional()
+  })
+  .refine(
+    value =>
+      value.name !== undefined || value.requireToolConfirmation !== undefined,
+    { message: 'Nothing to update' }
+  );
 
 const ORGANIZATION_GET = z.object({
   id: z.uuid(),
@@ -851,6 +861,12 @@ const HTTP_ENDPOINT_CONFIG = z
         contentType: constants.HTTP_ENDPOINT_RESPONSE_CONTENT_TYPE_AUTO,
         maxBytes: constants.HTTP_ENDPOINT_DEFAULT_MAX_BYTES
       }),
+    // What the endpoint does, as its owner says (`read`, `write` or
+    // `sensitive`). Absent means the method decides: GET and HEAD read,
+    // anything else is sensitive — right for most, but a POST that only
+    // searches needs its owner to say so, or a confirming channel asks
+    // before every search.
+    effect: z.enum(TOOL_EFFECTS).optional(),
     // Auth — credentials referenced by id, never inlined.
     auth: HTTP_ENDPOINT_AUTH.default({
       kind: constants.HTTP_ENDPOINT_AUTH_KIND_NONE
@@ -1056,6 +1072,19 @@ const CUSTOM_CODE_CONFIG_WRITE = CUSTOM_CODE_CONFIG.superRefine((cfg, ctx) => {
 // that version registering, and the owner would see tools quietly disappear with
 // only a log line to explain it. Reservation belongs to the manifest below,
 // which is the write path.
+// MCP tool annotations as a tool's author declares them — every hint optional,
+// with the spec's own defaults for what is left out. The channel runner reads
+// them to decide what to confirm, so a tool that doesn't say it is read-only
+// is treated as one that may change things.
+const TOOL_ANNOTATIONS = z
+  .object({
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional()
+  })
+  .strict();
+
 const CUSTOM_CODE_TOOL = z.object({
   name: z
     .string()
@@ -1068,7 +1097,8 @@ const CUSTOM_CODE_TOOL = z.object({
   title: z.string().min(1).max(200).optional(),
   description: z.string().max(2000).optional(),
   inputSchema: SCHEMA_DEFINITION.default({ type: 'object', properties: {} }),
-  outputSchema: SCHEMA_DEFINITION.optional()
+  outputSchema: SCHEMA_DEFINITION.optional(),
+  annotations: TOOL_ANNOTATIONS.optional()
 });
 
 // The manifest a `ganju deploy` (or the dashboard) uploads alongside a bundle.
@@ -1449,6 +1479,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,12 +1670,15 @@ 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,
   CUSTOM_CODE_CONFIG,
   CUSTOM_CODE_CONFIG_WRITE,
   CUSTOM_CODE_TOOL,
+  TOOL_ANNOTATIONS,
   CUSTOM_CODE_MANIFEST,
   ARTIFACT_CUSTOM_CODE_CREATE_VERSION,
   ARTIFACT_CUSTOM_CODE_UPLOAD_BUNDLE,
@@ -1690,6 +1738,10 @@ export interface McpProxyDiscoveredTool {
   title?: string;
   description?: string;
   inputSchema: unknown;
+  // The remote's own annotations, passed through at registration. Absent on
+  // discoveries made before they were recorded — the tool then counts as one
+  // that may change things until the server is discovered again.
+  annotations?: z.infer<typeof TOOL_ANNOTATIONS>;
 }
 
 // One remote resource discovered from a proxied MCP server. Identified by uri;

package/src/syncableResource.ts

@@ -0,0 +1,68 @@
+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;
+
+// Whether a sync root is still genuinely syncing: PENDING, and started within
+// RESOURCE_SYNC_STALE_MS. Past that, a PENDING root is stuck — a job was lost
+// or gave up — and may be synced again, which re-queues whatever it left
+// unfinished. A root that never synced counts from its creation, so a first
+// import that stalled recovers too.
+export const isResourceSyncInProgress = (
+  resource: {
+    status: string;
+    syncStartedAt?: Date | string | null;
+    createdAt: Date | string;
+  },
+  now: number = Date.now()
+): boolean => {
+  if (resource.status !== constants.STATUS_PENDING) return false;
+  const startedAt = new Date(
+    resource.syncStartedAt ?? resource.createdAt
+  ).getTime();
+  return now - startedAt < constants.RESOURCE_SYNC_STALE_MS;
+};