@ganju/utils 0.0.10 → 0.0.12

package/dist/toolConfirmation.js

@@ -0,0 +1,239 @@
+"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.stableJson = exports.isSensitiveTool = 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;
+/**
+ * Whether a tool needs a yes before it runs, by the MCP defaults: read-only
+ * only if it says so, and a tool that changes things is destructive unless it
+ * says it isn't. So an unannotated custom or proxied tool is confirmed — the
+ * safe reading for an organization that asked to be asked.
+ */
+const isSensitiveTool = (annotations) => annotations?.readOnlyHint !== true && annotations?.destructiveHint !== false;
+exports.isSensitiveTool = isSensitiveTool;
+// JSON with keys sorted at every depth, so two argument objects that say the
+// same thing serialize the same whatever order the model emitted them in.
+const stableJson = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(exports.stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value)
+            .sort()
+            .map(key => `${JSON.stringify(key)}:${(0, exports.stableJson)(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+};
+exports.stableJson = stableJson;

package/dist/toolLint.d.ts

@@ -0,0 +1,35 @@
+export interface LintableTool {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: unknown;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+export declare const TOOL_LINT_RULES: readonly ["missing-description", "short-description", "no-usage-guidance", "missing-annotations", "undescribed-input", "overlapping-tools", "too-many-tools"];
+export type ToolLintRule = (typeof TOOL_LINT_RULES)[number];
+export interface ToolLintFinding {
+    rule: ToolLintRule;
+    tool?: string;
+    other?: string;
+    paths?: string[];
+    count?: number;
+    limit?: number;
+    message: string;
+}
+export interface ToolLintOptions {
+    others?: LintableTool[];
+    otherCount?: number;
+}
+export declare const TOOL_LINT_MIN_DESCRIPTION_LENGTH = 40;
+export declare const TOOL_LINT_MAX_TOOLS = 25;
+/**
+ * Check a set of tools for what makes them hard for a model to use. Findings
+ * come back in the order of `tools`, then the server-wide one.
+ */
+export declare const lintTools: (tools: LintableTool[], options?: ToolLintOptions) => ToolLintFinding[];
+//# sourceMappingURL=toolLint.d.ts.map

package/dist/toolLint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolLint.d.ts","sourceRoot":"","sources":["../src/toolLint.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,eAAe,+JAQlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IAGnB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAI9B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IAGxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAKnD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAuHtC;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,OAAO,YAAY,EAAE,EACrB,UAAS,eAAoB,KAC5B,eAAe,EA4EjB,CAAC"}

package/dist/toolLint.js

@@ -0,0 +1,211 @@
+"use strict";
+// Checks on how a tool presents itself to a model: the things that make a
+// model pick the wrong tool, pass the wrong arguments, or pay for tools it never
+// uses. Every finding is a warning — a tool that fails one still works, it is
+// just harder for a model to use well.
+//
+// One rule set, run in three places: `ganju build` (with `--strict` to fail on
+// any finding), the API when a custom-code version is created (returned beside
+// the version, with the artifact's other tools as context), and the dashboard's
+// function dialog while it is being filled in.
+//
+// The rule for this file: it imports nothing. The published CLI bundles it, and
+// anything it imported would ship inside the CLI with it (see cliConstants.ts).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintTools = exports.TOOL_LINT_MAX_TOOLS = exports.TOOL_LINT_MIN_DESCRIPTION_LENGTH = exports.TOOL_LINT_RULES = void 0;
+exports.TOOL_LINT_RULES = [
+    'missing-description',
+    'short-description',
+    'no-usage-guidance',
+    'missing-annotations',
+    'undescribed-input',
+    'overlapping-tools',
+    'too-many-tools'
+];
+// Shorter than this and a description rarely says both what a tool does and
+// when to call it.
+exports.TOOL_LINT_MIN_DESCRIPTION_LENGTH = 40;
+// Past this many tools every call carries a long list of schemas, and models
+// start choosing among them badly. A channel turn hard-caps its list at 40
+// (CHANNEL_MAX_TOOLS); this warns well before that.
+exports.TOOL_LINT_MAX_TOOLS = 25;
+// Two descriptions sharing at least this much of their vocabulary (Jaccard,
+// over content words) read as the same tool to a model.
+const DESCRIPTION_OVERLAP = 0.6;
+// Too few content words and two unrelated descriptions can share most of them.
+const MIN_OVERLAP_WORDS = 5;
+// Lowercased, accents off, so "Úsala cuando" and "usala cuando" are one text.
+const fold = (text) => text.toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
+// Wording that tells a model WHEN to call a tool rather than only what it does
+// — English, Spanish and Portuguese, the languages descriptions here are
+// written in. Loose on purpose: a false "says when" costs nothing, a false
+// "doesn't" nags someone whose description is fine.
+const USAGE_GUIDANCE = /\b(use|uses|using|call|calls|when|whenever|before|after|instead|only if|if the user|if you|for questions|usa|usala|usalo|usar|llama|llamala|llamar|cuando|antes de|despues de|en lugar de|si el usuario|quando|use-a|utilize|chame)\b/;
+const STOPWORDS = new Set([
+    'the',
+    'and',
+    'for',
+    'with',
+    'from',
+    'this',
+    'that',
+    'into',
+    'your',
+    'you',
+    'use',
+    'when',
+    'call',
+    'tool',
+    'returns',
+    'return',
+    'given',
+    'user',
+    'about',
+    'una',
+    'uno',
+    'los',
+    'las',
+    'del',
+    'con',
+    'por',
+    'para',
+    'que',
+    'este',
+    'esta',
+    'como',
+    'cuando',
+    'usa',
+    'herramienta',
+    'devuelve',
+    'usuario'
+]);
+const contentWords = (text) => new Set(fold(text)
+    .split(/[^a-z0-9]+/)
+    .filter(word => word.length >= 3 && !STOPWORDS.has(word)));
+// `lookupOrder`, `lookup-order` and `order_lookup` name the same thing.
+const nameTokens = (name) => name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .sort()
+    .join(' ');
+const jaccard = (a, b) => {
+    let shared = 0;
+    for (const word of a)
+        if (b.has(word))
+            shared++;
+    const union = a.size + b.size - shared;
+    return union === 0 ? 0 : shared / union;
+};
+const overlaps = (a, b) => {
+    if (nameTokens(a.name) === nameTokens(b.name))
+        return true;
+    const aWords = contentWords(a.description ?? '');
+    const bWords = contentWords(b.description ?? '');
+    if (aWords.size < MIN_OVERLAP_WORDS || bWords.size < MIN_OVERLAP_WORDS) {
+        return false;
+    }
+    return jaccard(aWords, bWords) >= DESCRIPTION_OVERLAP;
+};
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// Every property the model may fill in that doesn't say what it is for, down
+// through nested objects and arrays of objects.
+const undescribedPaths = (schema, prefix = '') => {
+    if (!isObject(schema))
+        return [];
+    const paths = [];
+    if (isObject(schema.properties)) {
+        for (const [key, property] of Object.entries(schema.properties)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (!isObject(property))
+                continue;
+            const description = property.description;
+            if (typeof description !== 'string' || !description.trim()) {
+                paths.push(path);
+            }
+            paths.push(...undescribedPaths(property, path));
+        }
+    }
+    if (isObject(schema.items)) {
+        paths.push(...undescribedPaths(schema.items, `${prefix}[]`));
+    }
+    return paths;
+};
+const quoted = (name) => `"${name}"`;
+/**
+ * Check a set of tools for what makes them hard for a model to use. Findings
+ * come back in the order of `tools`, then the server-wide one.
+ */
+const lintTools = (tools, options = {}) => {
+    const others = options.others ?? [];
+    const findings = [];
+    tools.forEach((tool, index) => {
+        const description = (tool.description ?? '').trim();
+        if (!description) {
+            findings.push({
+                rule: 'missing-description',
+                tool: tool.name,
+                message: `${quoted(tool.name)} has no description, so a model sees only its name when deciding whether to call it.`
+            });
+        }
+        else if (description.length < exports.TOOL_LINT_MIN_DESCRIPTION_LENGTH) {
+            findings.push({
+                rule: 'short-description',
+                tool: tool.name,
+                message: `${quoted(tool.name)} has a very short description. Say what it does and when to call it, in at least ${exports.TOOL_LINT_MIN_DESCRIPTION_LENGTH} characters.`
+            });
+        }
+        else if (!USAGE_GUIDANCE.test(fold(description))) {
+            findings.push({
+                rule: 'no-usage-guidance',
+                tool: tool.name,
+                message: `${quoted(tool.name)}'s description says what it does but not when to use it (e.g. "Use when the user asks about…").`
+            });
+        }
+        // Undeclared means "may change things" by the MCP defaults, so with the
+        // organization confirming sensitive actions every call asks first — a
+        // lookup included.
+        const hints = tool.annotations;
+        if (hints?.readOnlyHint === undefined &&
+            hints?.destructiveHint === undefined) {
+            findings.push({
+                rule: 'missing-annotations',
+                tool: tool.name,
+                message: `${quoted(tool.name)} declares no annotations, so it is treated as one that may change things and is confirmed before every call when the organization confirms sensitive actions. Set readOnlyHint: true if it only reads, or destructiveHint: false if its changes can be undone.`
+            });
+        }
+        const paths = undescribedPaths(tool.inputSchema);
+        if (paths.length > 0) {
+            findings.push({
+                rule: 'undescribed-input',
+                tool: tool.name,
+                paths,
+                message: `${quoted(tool.name)} has input properties with no description: ${paths.join(', ')}. A model has to guess what to pass.`
+            });
+        }
+        // Each pair once: against the tools after this one, then the rest of the
+        // server.
+        for (const other of [...tools.slice(index + 1), ...others]) {
+            if (other.name === tool.name || !overlaps(tool, other))
+                continue;
+            findings.push({
+                rule: 'overlapping-tools',
+                tool: tool.name,
+                other: other.name,
+                message: `${quoted(tool.name)} and ${quoted(other.name)} look alike in name or description, so a model may call one for the other. Make each description say what sets it apart.`
+            });
+        }
+    });
+    const count = tools.length + (options.otherCount ?? others.length);
+    if (count > exports.TOOL_LINT_MAX_TOOLS) {
+        findings.push({
+            rule: 'too-many-tools',
+            count,
+            limit: exports.TOOL_LINT_MAX_TOOLS,
+            message: `${count} tools are enabled on this server. Every one's schema is sent to the model on every call, and models choose worse past a few dozen — turn off the ones it doesn't need (more than ${exports.TOOL_LINT_MAX_TOOLS} is where this warns).`
+        });
+    }
+    return findings;
+};
+exports.lintTools = lintTools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganju/utils",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Shared constants, schemas and helpers for Ganju",
   "license": "Apache-2.0",
   "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",
@@ -53,6 +53,11 @@
       "import": "./dist/cliConstants.js",
       "require": "./dist/cliConstants.js"
     },
+    "./toolLint": {
+      "types": "./dist/toolLint.d.ts",
+      "import": "./dist/toolLint.js",
+      "require": "./dist/toolLint.js"
+    },
     "./sdkConstants": {
       "types": "./dist/sdkConstants.d.ts",
       "import": "./dist/sdkConstants.js",

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,59 @@ 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.';
+// For MCP clients, whose chat the server can't see: a sensitive call without a
+// valid confirmation isn't run, and the model is told to ask the user and call
+// again with a token that binds the second call to these exact arguments.
+// How long that token stays good, and the argument that carries it.
+const MCP_TOOL_CONFIRMATION_TTL_MS = 10 * 60 * 1000;
+const MCP_TOOL_CONFIRMATION_ARG = 'confirmation';
+const MCP_TOOL_CONFIRMATION_ARG_DESCRIPTION =
+  "Leave out on the first call. This action needs the user's yes: the " +
+  'first call returns a token; after the user says yes, call again with the ' +
+  'same arguments and that token here.';
+// 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 +880,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 +914,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 +2615,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 +2674,14 @@ 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,
+  MCP_TOOL_CONFIRMATION_TTL_MS,
+  MCP_TOOL_CONFIRMATION_ARG,
+  MCP_TOOL_CONFIRMATION_ARG_DESCRIPTION,
   CHANNEL_DEBOUNCE_DEFAULT_MS,
   CHANNEL_DEBOUNCE_MIN_MS,
   CHANNEL_DEBOUNCE_MAX_MS,
@@ -2636,8 +2714,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 +2732,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,