@ganju/utils 0.0.10 → 0.0.11

package/dist/toolConfirmation.js

@@ -0,0 +1,217 @@
+"use strict";
+// When an organization turns on "confirm sensitive actions", a channel bot that
+// wants to run a sensitive tool asks first, and the call runs only if the
+// participant's next message is a plain yes. These are the pieces of that rule
+// that aren't the runner's own bookkeeping.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatConfirmationSummary = exports.isConfirmationReply = exports.parseConfirmationButton = exports.confirmationButtonId = exports.confirmationButtonLabels = exports.languageFromPhoneNumber = exports.annotationsForEffect = exports.TOOL_EFFECTS = void 0;
+// What an owner says a tool they wrote does, in the words the dashboard asks
+// it in, and the MCP annotations each answer stands for: `read` only looks
+// things up, `write` changes things that can be undone, `sensitive` sends,
+// deletes, charges or can't be undone — the kind a confirming channel asks
+// about.
+exports.TOOL_EFFECTS = ['read', 'write', 'sensitive'];
+const annotationsForEffect = (effect) => effect === 'read'
+    ? { readOnlyHint: true, destructiveHint: false }
+    : effect === 'write'
+        ? { readOnlyHint: false, destructiveHint: false }
+        : { readOnlyHint: false, destructiveHint: true };
+exports.annotationsForEffect = annotationsForEffect;
+// Whole replies that mean yes, lowercased with accents and punctuation
+// removed. English, Spanish and Portuguese, the languages bots here answer in.
+const AFFIRMATIVE = new Set([
+    'y',
+    'yes',
+    'yeah',
+    'yep',
+    'yup',
+    'sure',
+    'ok',
+    'okay',
+    'confirm',
+    'confirmed',
+    'approve',
+    'approved',
+    'go',
+    'go ahead',
+    'do it',
+    'send',
+    'send it',
+    'proceed',
+    'yes please',
+    'yes send it',
+    'yes do it',
+    'yes go ahead',
+    'yes confirm',
+    'sure thing',
+    'go for it',
+    'sounds good',
+    'looks good',
+    'all good',
+    'correct',
+    'si hazlo',
+    'si adelante',
+    'si envialo ya',
+    'perfecto',
+    'correcto',
+    'esta bien',
+    'ok dale',
+    'ok envialo',
+    'si',
+    'sip',
+    'claro',
+    'dale',
+    'va',
+    'vale',
+    'listo',
+    'confirmo',
+    'confirmado',
+    'confirmar',
+    'adelante',
+    'hazlo',
+    'envialo',
+    'enviar',
+    'de acuerdo',
+    'si por favor',
+    'si claro',
+    'si dale',
+    'si envialo',
+    'si confirmo',
+    'sim',
+    'pode',
+    'pode enviar'
+]);
+const AFFIRMATIVE_EMOJI = new Set(['👍', '✅', '👌', '🆗']);
+// The Yes/No buttons offered under a confirmation question, in the
+// participant's language when the platform reports it. The labels are also
+// what a tap sends where a button is just a canned reply (Telegram's reply
+// keyboard), so "yes" must read as a yes to isConfirmationReply — and it does,
+// in every language here.
+const BUTTON_LABELS = {
+    en: { yes: '✅ Yes', no: '❌ No' },
+    es: { yes: '✅ Sí', no: '❌ No' },
+    pt: { yes: '✅ Sim', no: '❌ Não' }
+};
+// WhatsApp reports no locale, so a button's language comes from the calling
+// code of the participant's number: the Spanish- and Portuguese-speaking
+// countries, English otherwise. Longest prefix wins.
+const CALLING_CODE_LANGUAGE = {
+    '34': 'es',
+    '51': 'es',
+    '52': 'es',
+    '53': 'es',
+    '54': 'es',
+    '56': 'es',
+    '57': 'es',
+    '58': 'es',
+    '240': 'es',
+    '502': 'es',
+    '503': 'es',
+    '504': 'es',
+    '505': 'es',
+    '506': 'es',
+    '507': 'es',
+    '591': 'es',
+    '593': 'es',
+    '595': 'es',
+    '598': 'es',
+    '1787': 'es',
+    '1809': 'es',
+    '1829': 'es',
+    '1849': 'es',
+    '55': 'pt',
+    '238': 'pt',
+    '244': 'pt',
+    '245': 'pt',
+    '258': 'pt',
+    '351': 'pt'
+};
+const languageFromPhoneNumber = (phone) => {
+    const digits = phone.replace(/\D/g, '');
+    for (let length = 4; length >= 2; length--) {
+        const language = CALLING_CODE_LANGUAGE[digits.slice(0, length)];
+        if (language)
+            return language;
+    }
+    return null;
+};
+exports.languageFromPhoneNumber = languageFromPhoneNumber;
+const confirmationButtonLabels = (locale) => {
+    const language = (locale || '').toLowerCase().split(/[-_]/)[0];
+    return BUTTON_LABELS[language] ?? BUTTON_LABELS.en;
+};
+exports.confirmationButtonLabels = confirmationButtonLabels;
+// Where the platform sends back a button's id rather than its label (Discord,
+// WhatsApp), the id says which answer it is and who was asked: in a shared
+// channel everyone sees the buttons, and only that participant's tap counts.
+// The runner never sees the id — a tap reaches it as the text "yes" or "no".
+const CONFIRMATION_BUTTON_PREFIX = 'ganju-confirm';
+const confirmationButtonId = (answer, externalParticipantId) => `${CONFIRMATION_BUTTON_PREFIX}:${answer}:${externalParticipantId}`;
+exports.confirmationButtonId = confirmationButtonId;
+const parseConfirmationButton = (id) => {
+    const [prefix, answer, ...rest] = id.split(':');
+    const externalParticipantId = rest.join(':');
+    if (prefix !== CONFIRMATION_BUTTON_PREFIX || !externalParticipantId) {
+        return null;
+    }
+    if (answer !== 'yes' && answer !== 'no')
+        return null;
+    return { text: answer, externalParticipantId };
+};
+exports.parseConfirmationButton = parseConfirmationButton;
+const normalize = (text) => text
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9\s]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+/**
+ * Whether a reply confirms the pending action. Deliberately narrow: the whole
+ * message has to be a yes. "Yes, but send it to Ana instead" is not one — it
+ * asks for a different action, and running the original would do exactly
+ * what the person just said not to. Anything that isn't a clear yes cancels,
+ * so the worst a misread costs is asking again.
+ */
+const isConfirmationReply = (text) => {
+    const trimmed = text.trim();
+    if (AFFIRMATIVE_EMOJI.has(trimmed))
+        return true;
+    return AFFIRMATIVE.has(normalize(trimmed));
+};
+exports.isConfirmationReply = isConfirmationReply;
+// How much of each argument the summary shows, and how many arguments.
+const SUMMARY_VALUE_MAX = 200;
+const SUMMARY_ARGUMENTS_MAX = 10;
+const summaryValue = (value) => {
+    const text = typeof value === 'string'
+        ? value
+        : (JSON.stringify(value) ?? String(value));
+    // One line, and no backticks, so a value can neither fake another line of
+    // the summary nor break out of its code span into formatting or links.
+    const flat = text.replace(/\s+/g, ' ').replace(/`/g, "'").trim();
+    return flat.length > SUMMARY_VALUE_MAX
+        ? `${flat.slice(0, SUMMARY_VALUE_MAX)}…`
+        : flat;
+};
+/**
+ * What the held calls will do, written from the calls themselves and appended
+ * under the model's question. The model words the question, but a yes runs the
+ * stored calls — so the participant has to see those, not only the model's
+ * account of them, which a prompt injection earlier in the turn could have
+ * bent.
+ */
+const formatConfirmationSummary = (calls, titleOf) => calls
+    .map(call => {
+    const entries = Object.entries(call.arguments ?? {}).filter(([, value]) => value !== undefined && value !== null && value !== '');
+    const lines = entries
+        .slice(0, SUMMARY_ARGUMENTS_MAX)
+        .map(([key, value]) => `- ${key}: \`${summaryValue(value)}\``);
+    if (entries.length > SUMMARY_ARGUMENTS_MAX)
+        lines.push('- …');
+    // The hourglass says "not done yet" in every language, whatever the
+    // model's own words above it claim.
+    return [`⏳ **${titleOf(call.name)}**`, ...lines].join('\n');
+})
+    .join('\n\n');
+exports.formatConfirmationSummary = formatConfirmationSummary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganju/utils",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Shared constants, schemas and helpers for Ganju",
   "license": "Apache-2.0",
   "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",

package/src/constants.ts

@@ -304,6 +304,16 @@ const RESOURCE_SYNC_BATCH_SIZE = 50;
 // 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';
@@ -758,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;
@@ -817,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;
@@ -847,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.
@@ -2546,6 +2605,7 @@ export const constants = {
   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,
@@ -2604,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,
@@ -2636,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,
@@ -2652,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,

package/src/index.ts

@@ -117,7 +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 {
+  isSyncableResource,
+  isResourceSyncInProgress,
+  resourceSyncProvider
+} from './syncableResource';
 import type {
   SyncableResource,
   ResourceSyncProvider
@@ -169,6 +173,7 @@ import type {
   CatalogGroup,
   CatalogTool,
   CatalogToolDescriptor,
+  ToolAnnotations,
   ToolGroupKey,
   ToolKey
 } from './toolCatalog';
@@ -220,6 +225,21 @@ import type {
   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,
@@ -301,6 +321,7 @@ export const utils = {
   resolveAttachment,
   isExposedResource,
   isSyncableResource,
+  isResourceSyncInProgress,
   resourceSyncProvider,
   describeVendorError,
   withDeadline,
@@ -358,6 +379,14 @@ export const utils = {
   channelBufferKey,
   batchCommand,
   joinBufferedMessages,
+  isConfirmationReply,
+  confirmationButtonLabels,
+  confirmationButtonId,
+  parseConfirmationButton,
+  languageFromPhoneNumber,
+  formatConfirmationSummary,
+  annotationsForEffect,
+  TOOL_EFFECTS,
   isResourceSourceEnabled,
   isDownloadableSource,
   safeHostname,
@@ -386,6 +415,10 @@ export type {
   CatalogGroup,
   CatalogTool,
   CatalogToolDescriptor,
+  ToolAnnotations,
+  PendingToolConfirmation,
+  PendingToolConfirmations,
+  ToolEffect,
   ToolGroupKey,
   ToolKey,
   CalendarConfigField,

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.
@@ -1648,6 +1678,7 @@ export const Schema = {
   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,
@@ -1707,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

@@ -46,3 +46,23 @@ export const resourceSyncProvider = (
 
 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;
+};