@ganju/utils 0.0.10 → 0.0.12

package/src/toolConfirmation.ts

@@ -0,0 +1,291 @@
+// 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.
+
+// A call waiting on the participant's answer, stored on the conversation. The
+// exact calls the model made are kept, so what runs after a yes is what the
+// question described — the model never gets to re-derive the arguments.
+export interface PendingToolConfirmation {
+  // Claimed by id, so a re-sent batch can't run the same calls twice.
+  id: string;
+  // Only the participant who was asked can answer — in a group, anyone else's
+  // message leaves the question open.
+  participantId: string;
+  createdAt: string;
+  calls: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+}
+
+// What a conversation holds: one open question per participant, keyed by
+// participant id, so in a group one person's question never replaces
+// another's.
+export type PendingToolConfirmations = Record<string, PendingToolConfirmation>;
+
+// 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.
+export const TOOL_EFFECTS = ['read', 'write', 'sensitive'] as const;
+
+export type ToolEffect = (typeof TOOL_EFFECTS)[number];
+
+export const annotationsForEffect = (
+  effect: ToolEffect
+): { readOnlyHint: boolean; destructiveHint: boolean } =>
+  effect === 'read'
+    ? { readOnlyHint: true, destructiveHint: false }
+    : effect === 'write'
+      ? { readOnlyHint: false, destructiveHint: false }
+      : { readOnlyHint: false, destructiveHint: true };
+
+// 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: Record<string, { yes: string; no: string }> = {
+  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: Record<string, string> = {
+  '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'
+};
+
+export const languageFromPhoneNumber = (phone: string): string | null => {
+  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;
+};
+
+export const confirmationButtonLabels = (
+  locale?: string | null
+): { yes: string; no: string } => {
+  const language = (locale || '').toLowerCase().split(/[-_]/)[0];
+  return BUTTON_LABELS[language] ?? BUTTON_LABELS.en;
+};
+
+// 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';
+
+export const confirmationButtonId = (
+  answer: 'yes' | 'no',
+  externalParticipantId: string
+): string => `${CONFIRMATION_BUTTON_PREFIX}:${answer}:${externalParticipantId}`;
+
+export const parseConfirmationButton = (
+  id: string
+): { text: 'yes' | 'no'; externalParticipantId: string } | null => {
+  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 };
+};
+
+const normalize = (text: string): string =>
+  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.
+ */
+export const isConfirmationReply = (text: string): boolean => {
+  const trimmed = text.trim();
+  if (AFFIRMATIVE_EMOJI.has(trimmed)) return true;
+  return AFFIRMATIVE.has(normalize(trimmed));
+};
+
+// 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: unknown): string => {
+  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.
+ */
+export const formatConfirmationSummary = (
+  calls: Array<{ name: string; arguments: Record<string, unknown> }>,
+  titleOf: (name: string) => string
+): string =>
+  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');
+
+/**
+ * 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.
+ */
+export const isSensitiveTool = (
+  annotations:
+    | { readOnlyHint?: boolean; destructiveHint?: boolean }
+    | null
+    | undefined
+): boolean =>
+  annotations?.readOnlyHint !== true && annotations?.destructiveHint !== false;
+
+// 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.
+export const stableJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map(
+        key =>
+          `${JSON.stringify(key)}:${stableJson((value as Record<string, unknown>)[key])}`
+      )
+      .join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+};

package/src/toolLint.ts

@@ -0,0 +1,277 @@
+// 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).
+
+// The shape all three callers can produce: a manifest entry, an http-endpoint's
+// config, a proxied tool from discovery, a catalog tool.
+export interface LintableTool {
+  name: string;
+  title?: string;
+  description?: string;
+  inputSchema?: unknown;
+  annotations?: {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+  };
+}
+
+export const TOOL_LINT_RULES = [
+  'missing-description',
+  'short-description',
+  'no-usage-guidance',
+  'missing-annotations',
+  'undescribed-input',
+  'overlapping-tools',
+  'too-many-tools'
+] as const;
+
+export type ToolLintRule = (typeof TOOL_LINT_RULES)[number];
+
+export interface ToolLintFinding {
+  rule: ToolLintRule;
+  // The tool the finding is about. Absent only for `too-many-tools`, which is
+  // about the server as a whole.
+  tool?: string;
+  // `overlapping-tools`: the tool it is confused with.
+  other?: string;
+  // `undescribed-input`: the properties with no description, as dotted paths.
+  paths?: string[];
+  // `too-many-tools`: how many are enabled, and the number past which it warns.
+  count?: number;
+  limit?: number;
+  // The same finding in English, for the CLI and the API. The dashboard builds
+  // its own from the fields above, in the reader's language.
+  message: string;
+}
+
+export interface ToolLintOptions {
+  // The other tools on the same server — natives, http endpoints, proxied
+  // tools. They are checked against for overlap and counted, but never
+  // reported on themselves: the author of these tools can't change them.
+  others?: LintableTool[];
+  // How many tools the server exposes beside `tools`, when `others` doesn't
+  // list them all. Defaults to `others.length`.
+  otherCount?: number;
+}
+
+// Shorter than this and a description rarely says both what a tool does and
+// when to call it.
+export const 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.
+export const 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: string): string =>
+  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: string): Set<string> =>
+  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: string): string =>
+  name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .sort()
+    .join(' ');
+
+const jaccard = (a: Set<string>, b: Set<string>): number => {
+  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: LintableTool, b: LintableTool): boolean => {
+  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: unknown): value is Record<string, unknown> =>
+  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: unknown, prefix = ''): string[] => {
+  if (!isObject(schema)) return [];
+  const paths: string[] = [];
+  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: string) => `"${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.
+ */
+export const lintTools = (
+  tools: LintableTool[],
+  options: ToolLintOptions = {}
+): ToolLintFinding[] => {
+  const others = options.others ?? [];
+  const findings: ToolLintFinding[] = [];
+
+  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 < 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 ${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 > TOOL_LINT_MAX_TOOLS) {
+    findings.push({
+      rule: 'too-many-tools',
+      count,
+      limit: 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 ${TOOL_LINT_MAX_TOOLS} is where this warns).`
+    });
+  }
+
+  return findings;
+};