relays-sdk 0.0.0-stage → 0.2.0

package/relay-manifest.mjs

@@ -0,0 +1,291 @@
+
+const isObj = (x) => x && typeof x === "object" && !Array.isArray(x);
+const drop = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v != null));
+export const FEEDBACK_SECRET_PATTERNS = [
+  ["relay token or code", /\b(?:grk|rat|rrt|rmt|rac|rpi|ilk|frd|whsec|evl|ptk)_[A-Za-z0-9_-]{12,}/],
+  ["Stripe key", /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{12,}/],
+  ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/],
+  ["Slack token", /\bxox[abposr]-[A-Za-z0-9-]{10,}/],
+  ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["bearer token", /\bbearer\s+[A-Za-z0-9._~+/=-]{20,}/i],
+];
+export function feedbackSecretKind(message) {
+  if (typeof message !== "string") return null;
+  for (const [label, rx] of FEEDBACK_SECRET_PATTERNS) if (rx.test(message)) return label;
+  return null;
+}
+
+export const MANIFEST_VERSION = 1, MANIFEST_MAX_BYTES = 32768, MANIFEST_NOTE_MAX = 500;
+export const MANIFEST_KEYS = ["schema_version", "summary", "highlights", "can_do", "tools", "resources", "connectors", "skills", "wake_adapter", "limits", "can_help_with"];
+export const MANIFEST_SUMMARY_MAX = 500, MANIFEST_HIGHLIGHTS_MAX = 8, HIGHLIGHT_TEXT_MAX = 80, HIGHLIGHT_SERVICE_MAX = 64, HIGHLIGHT_KEYS = ["service", "text"];
+export const MANIFEST_CAPS = { tools: null, resources: null, connectors: null, skills: null };
+export const MANIFEST_MAX_DEPTH = 12;
+const depth = (v) => (v && typeof v === "object" && Object.keys(v).length ? 1 + Math.max(...Object.values(v).map(depth)) : 0);
+const ITEM_KEYS = { tools: ["name", "description"], resources: ["uri", "name", "description", "mimeType"], connectors: ["name", "description"], skills: ["id", "name", "description", "tags"] };
+const ITEM_MAX = { name: 64, description: 500, id: 64, mimeType: 100, uri: 500 };
+export const MANIFEST_LIMIT_INTS = ["rate_per_min", "max_concurrent_tasks", "daily_quota"];
+export const MANIFEST_WAKE_KINDS = ["webhook", "inbox_only", "claude_routine", "cursor_agent", "github_issue", "chatgpt_workspace_agent", "slack_mention", "discord_webhook", "telegram_bot", "a2a_push", "devin_session", "poll_only"];
+export const CAPABILITIES_ERRORS = {
+  manifest_invalid: "The manifest is invalid (see field).", manifest_contains_secret: "The manifest looks like it contains a credential (see kind and field); nothing was sent or stored.",
+  manifest_too_large: "The manifest is over the 32 KB cap (see limit).", manifest_not_found: "That bot has not shared a capability manifest yet.",
+  request_not_found: "No such capability request (unknown, or another bot's request_id).", bot_not_found: "No such bot (or you may not see its capabilities).",
+  capabilities_request_rate_limited: "Too many capability requests for this bot (10 per hour per requester); try again later.",
+  request_not_pending: "That capability request is no longer pending: it was already approved, denied or it expired (see request_status)." };
+
+export const CAPABILITY_REQUEST_STATUSES = ["pending", "approved", "denied", "expired"], CAPABILITY_ANSWERS = ["approved", "denied"], CAPABILITY_DELIVERY_STATUSES = ["pending", "delivered", "failed"];
+export const capabilityRequestStatus = (s) => (s === "answered" ? "approved" : s);
+
+export const noteSecretKind = (note) => (typeof note === "string" ? feedbackSecretKind(note.replace(CTRL_RE, "")) || urlSecretKind(note.replace(CTRL_RE, "")) : null);
+export const MANIFEST_TOOL_NAME_RE = /^[A-Za-z0-9_.-]{1,64}$/, CAPS_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const CTRL_RE = /[\x00-\x09\x0b-\x1f\x7f-\x9f]/g, URL_RE = /[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s"'<>]+/g, URI_RE = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s?#@/]*(?:\/[^\s?#]*)?$/;
+const CRED_PARAM_RE = /^(?:key|token|secret|sig|signature|password|auth|access_token|api_key|apikey|x-amz-.*)$/i, CRED_KEY_RE = /(?:token|secret|passw|api[_-]?key|authorization|headers?|credential|private[_-]?key|cookie)/i;
+export const cpLen = (s) => [...s].length, cpSlice = (s, n) => [...s].slice(0, n).join("");
+const EDGE_WS_RE = /^[ \t\n\r]+|[ \t\n\r]+$/g, trimWs = (s) => s.replace(EDGE_WS_RE, ""), inRange = (s, lo, hi) => { const n = cpLen(s); return n >= lo && n <= hi; };
+const jsonBytes = (x) => new TextEncoder().encode(JSON.stringify(x)).length;
+export const cleanManifest = (v) => typeof v === "string" ? v.replace(CTRL_RE, "") : Array.isArray(v) ? v.map(cleanManifest) : isObj(v) ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cleanManifest(x)])) : v;
+function* walkStrings(v, path) {
+  if (typeof v === "string") yield [path, v];
+  else if (Array.isArray(v)) for (let i = 0; i < v.length; i++) yield* walkStrings(v[i], `${path}[${i}]`);
+  else if (isObj(v)) for (const [k, x] of Object.entries(v)) yield* walkStrings(x, path ? `${path}.${k}` : k);
+}
+function* walkKeys(v, path) {
+  if (Array.isArray(v)) for (let i = 0; i < v.length; i++) yield* walkKeys(v[i], `${path}[${i}]`);
+  else if (isObj(v)) for (const [k, x] of Object.entries(v)) { const p = path ? `${path}.${k}` : k; yield [k, p]; yield* walkKeys(x, p); }
+}
+
+export function urlSecretKind(s) {
+  for (const u of s.match(URL_RE) || []) {
+    const rest = u.split("://").slice(1).join("://"), auth = rest.split(/[/?#]/, 1)[0];
+    if (auth.includes("@")) return "URL with credentials";
+    const qi = u.indexOf("?");
+    if (qi >= 0) for (const p of u.slice(qi + 1).split("#")[0].split(/[&;]/)) { if (!p) continue; let n = p.split("=")[0].replace(/\+/g, " "); try { n = decodeURIComponent(n); } catch {} if (CRED_PARAM_RE.test(n.trim())) return "URL with a credential in its query"; }
+  }
+  return null;
+}
+
+export function manifestSecret(manifest) {
+  for (const [k, p] of walkKeys(manifest, "")) if (CRED_KEY_RE.test(k)) return { kind: "credential-named key", field: p };
+  for (const [p, s] of walkStrings(manifest, "")) { const k = feedbackSecretKind(s) || urlSecretKind(s); if (k) return { kind: k, field: p }; }
+  return null;
+}
+
+export function manifestProblem(manifest) {
+  if (!isObj(manifest)) return { error: "manifest_invalid", field: "manifest" };
+  const m = cleanManifest(manifest), bad = (field) => ({ error: "manifest_invalid", field });
+  const s = manifestSecret(m); if (s) return { error: "manifest_contains_secret", ...s };
+  if (!Number.isInteger(m.schema_version) || m.schema_version !== MANIFEST_VERSION) return bad("schema_version");
+  for (const k of Object.keys(m)) if (!MANIFEST_KEYS.includes(k)) return bad(k);
+  if (m.highlights != null && m.can_do != null) return bad("can_do");
+  if (m.summary != null && (typeof m.summary !== "string" || !inRange(trimWs(m.summary), 1, MANIFEST_SUMMARY_MAX))) return bad("summary");
+  const hk = m.highlights != null ? "highlights" : m.can_do != null ? "can_do" : null;
+  if (hk) {
+    const h = m[hk]; if (!Array.isArray(h) || h.length > MANIFEST_HIGHLIGHTS_MAX) return bad(hk);
+    for (let i = 0; i < h.length; i++) {
+      const it = h[i], f = `${hk}[${i}]`;
+      if (typeof it === "string") { if (!inRange(trimWs(it), 1, HIGHLIGHT_TEXT_MAX)) return bad(f); continue; }
+      if (!isObj(it)) return bad(f);
+      for (const k of Object.keys(it)) if (!HIGHLIGHT_KEYS.includes(k)) return bad(`${f}.${k}`);
+      if (typeof it.text !== "string" || !inRange(trimWs(it.text), 1, HIGHLIGHT_TEXT_MAX)) return bad(f + ".text");
+      if (it.service != null && (typeof it.service !== "string" || !inRange(trimWs(it.service), 1, HIGHLIGHT_SERVICE_MAX))) return bad(f + ".service");
+    }
+  }
+  for (const sect of Object.keys(MANIFEST_CAPS)) {
+    const items = m[sect]; if (items == null) continue;
+    if (!Array.isArray(items)) return bad(sect);
+    for (let i = 0; i < items.length; i++) {
+      const it = items[i], f = `${sect}[${i}]`;
+      if (!isObj(it)) return bad(f);
+      if (depth(it) > MANIFEST_MAX_DEPTH - 2) return bad(f);
+      if (typeof it.name !== "string" || !it.name.trim()) return bad(f + ".name");
+      if (sect === "tools" && !MANIFEST_TOOL_NAME_RE.test(it.name)) return bad(f + ".name");
+      for (const k of ["name", "description", "id", "mimeType"]) if (k in it && (typeof it[k] !== "string" || cpLen(it[k]) > ITEM_MAX[k])) return bad(`${f}.${k}`);
+      if ("uri" in it && (typeof it.uri !== "string" || cpLen(it.uri) > 500 || !URI_RE.test(it.uri))) return bad(f + ".uri");
+      if ("tags" in it) {
+        const t = it.tags; if (!Array.isArray(t) || t.length > 10) return bad(f + ".tags");
+        for (let j = 0; j < t.length; j++) if (typeof t[j] !== "string" || cpLen(t[j]) < 1 || cpLen(t[j]) > 32) return bad(`${f}.tags[${j}]`);
+      }
+    }
+  }
+  const w = m.wake_adapter;
+  if (w != null) {
+    if (!isObj(w)) return bad("wake_adapter");
+    for (const k of Object.keys(w)) if (k !== "kind") return bad(`wake_adapter.${k}`);
+    if (!MANIFEST_WAKE_KINDS.includes(w.kind)) return bad("wake_adapter.kind");
+  }
+  const l = m.limits;
+  if (l != null) {
+    if (!isObj(l)) return bad("limits");
+    for (const [k, v] of Object.entries(l)) {
+      if (k === "text") { if (typeof v !== "string" || cpLen(v) > 500) return bad("limits.text"); }
+      else if (MANIFEST_LIMIT_INTS.includes(k)) { if (!Number.isInteger(v) || v < 0 || v > 2 ** 53) return bad(`limits.${k}`); }
+      else return bad(`limits.${k}`);
+    }
+  }
+  if (m.can_help_with != null && (typeof m.can_help_with !== "string" || cpLen(m.can_help_with) > 2000)) return bad("can_help_with");
+  if (jsonBytes(m) > MANIFEST_MAX_BYTES) return { error: "manifest_too_large", limit: MANIFEST_MAX_BYTES };
+  return null;
+}
+
+export function normalizeManifest(m) {
+  const out = { schema_version: m.schema_version }, hl = m.highlights ?? m.can_do;
+  if (m.summary != null) out.summary = trimWs(m.summary);
+  if (hl != null && hl.length) out.highlights = hl.map((it) => typeof it === "string" ? trimWs(it) : it.service != null ? { service: trimWs(it.service), text: trimWs(it.text) } : { text: trimWs(it.text) });
+  for (const [k, v] of Object.entries(m)) if (k !== "schema_version" && k !== "summary" && k !== "highlights" && k !== "can_do") out[k] = v;
+  return out;
+}
+
+export const capsHighlightsMode = (v) => { const t = v == null ? "" : String(v).trim().toLowerCase(); return ["0", "false", "off", "no"].includes(t) ? "0" : t === "auto" ? "auto" : "1"; };
+export const isHighlightsField = (f) => typeof f === "string" && (["summary", "highlights", "can_do"].includes(f) || f.startsWith("highlights[") || f.startsWith("can_do["));
+
+export function foldHighlights(m) {
+  const { summary, highlights, can_do, ...out } = m;
+  if (out.can_help_with == null) { const lines = [...(summary ? [summary] : []), ...(highlights || []).map((it) => "- " + (typeof it === "string" ? it : it.text))]; if (lines.length) out.can_help_with = cpSlice(lines.join("\n"), 2000); }
+  return out;
+}
+const unwrapList = (v, key) => { if (isObj(v)) { v = isObj(v.result) ? v.result : v; if (isObj(v)) v = v[key]; } return Array.isArray(v) ? v : null; };
+const trimStr = (s, mx, field, dropped) => { s = s.replace(CTRL_RE, ""); if (cpLen(s) > mx) { dropped.push({ field, reason: `trimmed to ${mx} chars` }); s = cpSlice(s, mx); } return s; };
+export const MANIFEST_FIT_STEPS = [160, 80, 40, 0];
+const SENT_END_RE = /[.!?](?=[ \t\n\r]|$)/, TAIL_RE = /[ \t\n\r,;:-]+$/;
+
+export function shortDescription(s, mx = 160) {
+  s = s.replace(EDGE_WS_RE, "").replace(/[ \t\n\r]+/g, " "); const m = SENT_END_RE.exec(s); if (m) s = s.slice(0, m.index + 1);
+  const a = [...s]; if (a.length <= mx) return s;
+  const c = a.slice(0, mx - 1), i = c.lastIndexOf(" "); if (i >= Math.floor(mx / 2)) c.length = i;
+  return c.join("").replace(TAIL_RE, "") + "…";
+}
+
+const SERVICE_TOKENS = [["GitHub", "github"], ["GitLab", "gitlab"], ["Cloudflare", "cloudflare wrangler"], ["Gmail", "gmail"], ["Google Calendar", "gcal calendar"], ["Google Drive", "gdrive drive"], ["Google Sheets", "gsheets sheets"], ["Notion", "notion"], ["Slack", "slack"], ["Discord", "discord"], ["Telegram", "telegram"],
+  ["Stripe", "stripe"], ["Linear", "linear"], ["Jira", "jira"], ["X", "x twitter tweet tweets"], ["Figma", "figma"], ["Vercel", "vercel"], ["AWS", "aws s3 ec2 lambda dynamodb"], ["ElevenLabs", "elevenlabs"], ["Grafana", "grafana"], ["Sentry", "sentry"], ["Airtable", "airtable"], ["HubSpot", "hubspot"],
+  ["Shopify", "shopify"], ["Asana", "asana"], ["Trello", "trello"], ["Dropbox", "dropbox"], ["Zoom", "zoom"], ["Twilio", "twilio"], ["Supabase", "supabase"], ["Docker", "docker"], ["Postgres", "postgres postgresql"]];
+const TOKEN_SERVICE = Object.fromEntries(SERVICE_TOKENS.flatMap(([n, t]) => t.split(" ").map((k) => [k, n])));
+export const RELAYS_SERVICE = "relays.bot", RELAYS_LINE = "Messages bots and works on projects in relays.bot", HIGHLIGHT_LINES_MAX = 8;
+const VERBS_READ = new Set("get list search read fetch query find view show lookup check describe browse".split(" ")), VERBS_SEND = new Set("send post reply comment".split(" ")),
+  VERBS_WRITE = new Set("create update send post add edit delete set write remove reply comment upload merge push close patch put submit move rename".split(" ")), VERBS_DEPLOY = new Set(["deploy", "deploys"]);
+const nameTokens = (n) => n.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+function serviceLine(name, v) {
+  if (name === RELAYS_SERVICE) return RELAYS_LINE;
+  const parts = [v.read && "reads", v.write && "writes", v.deploy && "deploys"].filter(Boolean), joined = parts.length > 1 ? parts.slice(0, -1).join(", ") + " and " + parts[parts.length - 1] : parts[0];
+  const line = !parts.length ? `uses ${name}` : v.deploy ? `${joined} to ${name}` : v.write && !v.read ? `${v.send ? "sends" : "writes"} to ${name}` : `${joined} ${name}`;
+  return line[0].toUpperCase() + line.slice(1);
+}
+const joinNames = (a) => a.length > 1 ? a.slice(0, -1).join(", ") + " and " + a[a.length - 1] : a[0];
+
+export function summarizeTools(tools) {
+  const lst = Array.isArray(tools) ? tools : unwrapList(tools, "tools") || [], groups = new Map();
+  for (const t of lst) {
+    const name = typeof t === "string" ? t : isObj(t) && typeof t.name === "string" ? t.name : null; if (!name) continue;
+    const toks = nameTokens(name), svc = toks.map((k) => TOKEN_SERVICE[k]).find(Boolean) || RELAYS_SERVICE;
+    if (!groups.has(svc)) groups.set(svc, { service: svc, n: 0, read: false, write: false, send: false, deploy: false });
+    const g = groups.get(svc); g.n++;
+    for (const k of toks) { if (VERBS_READ.has(k)) g.read = true; if (VERBS_WRITE.has(k)) g.write = true; if (VERBS_SEND.has(k)) g.send = true; if (VERBS_DEPLOY.has(k)) g.deploy = true; }
+  }
+  let gs = [...groups.values()]; if (!gs.length) return { summary: "", highlights: [] };
+  gs = [...gs.filter((g) => g.service !== RELAYS_SERVICE).map((g, i) => [g, i]).sort((a, b) => b[0].n - a[0].n || a[1] - b[1]).map(([g]) => g), ...gs.filter((g) => g.service === RELAYS_SERVICE)];
+  let other = 0; if (gs.length > HIGHLIGHT_LINES_MAX) { other = gs.slice(HIGHLIGHT_LINES_MAX - 1).reduce((a, g) => a + g.n, 0); gs = gs.slice(0, HIGHLIGHT_LINES_MAX - 1); }
+  const highlights = gs.map((g) => ({ service: g.service, text: serviceLine(g.service, g) }));
+  if (other) highlights.push({ text: `Other tools (${other})` });
+  return { summary: `This bot works with ${joinNames(gs.map((g) => g.service))}.` + (other ? " It has other tools too." : ""), highlights };
+}
+const cleanStr = (v) => trimWs(v.replace(CTRL_RE, ""));
+function buildSummary(v, dr) {
+  if (v == null) return null; if (typeof v !== "string") { dr.push({ field: "summary", reason: "not a string" }); return null; }
+  let s = cleanStr(v); if (!s) return null;
+  if (cpLen(s) > MANIFEST_SUMMARY_MAX) { dr.push({ field: "summary", reason: `trimmed to ${MANIFEST_SUMMARY_MAX} chars` }); s = trimWs(cpSlice(s, MANIFEST_SUMMARY_MAX)); }
+  return s;
+}
+function buildHighlights(v, dr) {
+  if (v == null) return null; if (!Array.isArray(v)) { dr.push({ field: "highlights", reason: "not a list" }); return null; }
+  const out = [];
+  v.forEach((it, i) => {
+    const f = `highlights[${i}]`; let text, svc;
+    if (typeof it === "string") text = it; else if (isObj(it)) { text = it.text; svc = it.service; } else { dr.push({ field: f, reason: "not a string or object" }); return; }
+    text = typeof text === "string" ? cleanStr(text) : ""; if (!text) { dr.push({ field: f, reason: "no text" }); return; }
+    if (out.length >= MANIFEST_HIGHLIGHTS_MAX) { dr.push({ field: f, reason: `over the ${MANIFEST_HIGHLIGHTS_MAX} item cap` }); return; }
+    if (cpLen(text) > HIGHLIGHT_TEXT_MAX) { dr.push({ field: isObj(it) ? f + ".text" : f, reason: `trimmed to ${HIGHLIGHT_TEXT_MAX} chars` }); text = trimWs(cpSlice(text, HIGHLIGHT_TEXT_MAX)); }
+    svc = typeof svc === "string" ? cleanStr(svc) : "";
+    if (cpLen(svc) > HIGHLIGHT_SERVICE_MAX) { dr.push({ field: f + ".service", reason: `trimmed to ${HIGHLIGHT_SERVICE_MAX} chars` }); svc = trimWs(cpSlice(svc, HIGHLIGHT_SERVICE_MAX)); }
+    out.push(svc ? { service: svc, text } : typeof it === "string" ? text : { text });
+  });
+  return out.length ? out : null;
+}
+export const MANIFEST_TOOLS_DETAIL = ["auto", "full", "compact", "names", "none"], TOOLS_COMPACT_DESC = 80;
+
+export function buildManifest({ tools, resources, connectors, skills, wakeKind, wake_kind, limits, canHelpWith, can_help_with, summary, highlights, can_do, canDo, toolsDetail, tools_detail, autoSummary, auto_summary } = {}) {
+  const dr = [], gen = [], m = { schema_version: MANIFEST_VERSION }, td = toolsDetail ?? tools_detail ?? "auto", auto = autoSummary ?? auto_summary ?? true;
+  if (!MANIFEST_TOOLS_DETAIL.includes(td)) throw new Error(`tools_detail must be one of ${MANIFEST_TOOLS_DETAIL.join(", ")}`);
+  for (const [sect, src] of [["tools", tools], ["resources", resources], ["connectors", connectors], ["skills", skills]]) {
+    if (src == null) continue;
+    const lst = unwrapList(src, sect);
+    if (!lst) { dr.push({ field: sect, reason: "not a list" }); continue; }
+    const out = [];
+    lst.forEach((it0, i) => {
+      const f = `${sect}[${i}]`; let it = it0;
+      if (typeof it === "string" && sect === "connectors") it = { name: it };
+      if (!isObj(it)) { dr.push({ field: f, reason: "not an object" }); return; }
+      const o = {};
+      for (const k of ITEM_KEYS[sect]) {
+        let v = it[k]; if (v == null) continue;
+        if (k === "tags") {
+          if (!Array.isArray(v)) continue;
+          let tags = v.map((x, j) => [x, j]).filter(([x]) => typeof x === "string" && x.trim()).map(([x, j]) => trimStr(x, 32, `${f}.tags[${j}]`, dr));
+          if (tags.length > 10) { dr.push({ field: f + ".tags", reason: "over the 10 tag cap" }); tags = tags.slice(0, 10); }
+          if (tags.length) o[k] = tags;
+        } else if (typeof v === "string") {
+          if (k === "uri" && /[?#]/.test(v)) { dr.push({ field: f + ".uri", reason: "query string / fragment removed" }); v = v.split(/[?#]/, 1)[0]; }
+          o[k] = trimStr(v, ITEM_MAX[k], `${f}.${k}`, dr);
+        }
+      }
+      if (sect === "skills" && !o.name && o.id) o.name = o.id;
+      if (!o.name && !(sect === "resources" && o.uri)) { dr.push({ field: f, reason: "no name" }); return; }
+      if (sect === "resources" && !o.name) o.name = cpSlice(o.uri, 64);
+      if (sect === "tools" && !MANIFEST_TOOL_NAME_RE.test(o.name)) { dr.push({ field: f, reason: "tool name is not [A-Za-z0-9_.-]{1,64}" }); return; }
+      out.push(o);
+    });
+    m[sect] = out;
+  }
+  const wk = wakeKind ?? wake_kind; if (wk != null) m.wake_adapter = { kind: wk };
+  if (limits != null) {
+    const lim = typeof limits === "string" ? { text: limits } : isObj(limits) ? limits : {}, lo = {};
+    for (const [k, v] of Object.entries(lim)) {
+      if (k === "text" && typeof v === "string") lo[k] = trimStr(v, 500, "limits.text", dr);
+      else if (MANIFEST_LIMIT_INTS.includes(k) && Number.isInteger(v)) lo[k] = v;
+      else dr.push({ field: `limits.${k}`, reason: "not a supported limit" });
+    }
+    m.limits = lo;
+  }
+  const ch = canHelpWith ?? can_help_with; if (ch != null) m.can_help_with = trimStr(String(ch), 2000, "can_help_with", dr);
+  const hl0 = highlights ?? can_do ?? canDo; if (highlights != null && (can_do ?? canDo) != null) dr.push({ field: "can_do", reason: "ignored: highlights was given" });
+  let sum = buildSummary(summary, dr), hl = buildHighlights(hl0, dr);
+  if (auto && (sum == null || hl == null) && m.tools?.length) {
+    const g = summarizeTools(m.tools);
+    if (sum == null && g.summary) { sum = g.summary; gen.push("summary"); }
+    if (hl == null && g.highlights.length) { hl = g.highlights; gen.push("highlights"); }
+  }
+  if (sum != null) m.summary = sum; if (hl != null) m.highlights = hl;
+  const detail = td === "auto" ? (sum != null || hl != null ? "compact" : "full") : td;
+  if (m.tools) {
+    if (detail === "none") delete m.tools;
+    else if (detail === "names") for (const o of m.tools) delete o.description;
+    else if (detail === "compact") for (const o of m.tools) if (o.description != null) o.description = shortDescription(o.description, TOOLS_COMPACT_DESC);
+  }
+  for (const mx of MANIFEST_FIT_STEPS) {
+    if (jsonBytes(m) <= MANIFEST_MAX_BYTES) break;
+    for (const sect of Object.keys(MANIFEST_CAPS)) {
+      let n = 0;
+      for (const o of m[sect] || []) {
+        const d = o.description; if (d == null) continue;
+        const nd = mx ? shortDescription(d, mx) : "";
+        if (nd !== d) { n++; if (nd) o.description = nd; else delete o.description; }
+      }
+      if (n) dr.push({ field: `${sect}[].description`, reason: mx ? `${n} shortened to the first sentence, at most ${mx} chars, to fit the 32 KB cap` : `${n} removed to fit the 32 KB cap` });
+    }
+  }
+  while (jsonBytes(m) > MANIFEST_MAX_BYTES) {
+    const lists = Object.keys(MANIFEST_CAPS).filter((s) => m[s]?.length); if (!lists.length) break;
+    const s = lists.reduce((a, b) => (jsonBytes(m[b]) > jsonBytes(m[a]) ? b : a)); m[s].pop(); dr.push({ field: `${s}[${m[s].length}]`, reason: "dropped to fit the 32 KB cap" });
+  }
+  const { schema_version, summary: s0, highlights: h0, ...rest } = m, out = { schema_version, ...(s0 != null ? { summary: s0 } : {}), ...(h0 != null ? { highlights: h0 } : {}), ...rest };
+  Object.defineProperty(out, "dropped", { value: dr, enumerable: false }); Object.defineProperty(out, "generated", { value: gen, enumerable: false });
+  return out;
+}

package/relay-webhook.mjs

@@ -0,0 +1,43 @@
+
+
+export const JOIN_RATE_LIMIT = 5;
+export const JOIN_WEBHOOK_HELP = "see /protocol: 'How a Grok Bot gets a webhook' (docs/connect-any-bot.md): a public https DNS name on port 443, 8443, 10000, 2053, 2083, 2087 or 2096 that answers the relays.webhook.verify ping";
+export const WEBHOOK_VERIFY_TYPE = "relays.webhook.verify";
+export const WEBHOOK_TEST_TYPE = "relays.webhook.test";
+export const WEBHOOK_VERIFY_HINT = "Your endpoint must answer the relay's relays.webhook.verify POST with 2xx within 5 s and no redirect, echoing {\"challenge\": <the challenge in the body>} (the join-time signing secret is not known to you yet, so answer before checking any signature); see isWebhookVerify / verifyChallengeResponse.";
+export const WEBHOOK_PORTS = ["", "443", "8443", "10000", "2053", "2083", "2087", "2096"];
+const WH_BAD_HOST = /(^|\.)(localhost|local|internal|intranet|lan|home|corp|arpa|test|example|invalid|onion)$|^example\.(com|net|org)$|\.example\.(com|net|org)$/;
+
+export function joinWebhookUrlProblem(url) {
+  if (typeof url !== "string") return "webhook_url must be a string";
+  url = url.trim(); if (url.length > 500) return "webhook_url too long";
+  let u; try { u = new URL(url); } catch { return "webhook_url is not a valid URL"; }
+  if (u.protocol !== "https:") return "webhook_url must be https";
+  if (u.username || u.password) return "webhook_url must not contain credentials";
+  if (!WEBHOOK_PORTS.includes(u.port)) return "webhook_url port must be 443, 8443, 10000, 2053, 2083, 2087 or 2096";
+  const h = u.hostname.toLowerCase();
+  if (h.startsWith("[")) return "webhook_url must not be an IP address";
+  const ls = h.split(".");
+  if (h.length > 253 || ls.length < 2 || !ls.every((l) => /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(l))) return "webhook_url host must be a public DNS name";
+  const tld = ls[ls.length - 1];
+  if (!(/^[a-z]{2,63}$/.test(tld) || /^xn--[a-z0-9-]{1,59}$/.test(tld))) return "webhook_url host must be a public DNS name";
+  if (WH_BAD_HOST.test(h)) return "webhook_url host is not publicly routable";
+  if (/(^|\.)(relays\.bot|cloudflareaccess\.com)$/.test(h)) return "webhook_url must not point at the relay itself";
+  return null;
+}
+
+export const joinWebhookProblem = (url) => (typeof url !== "string" || !url.trim()) ? "webhook_url is required (https URL that wakes your bot, e.g. a Grok Bot webhook routine)" : joinWebhookUrlProblem(url);
+const parseBody = (body) => { if (body && typeof body === "object" && !(body instanceof Uint8Array)) return body; try { const d = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body)); return d && typeof d === "object" && !Array.isArray(d) ? d : null; } catch { return null; } };
+
+export const isWebhookVerify = (body) => parseBody(body)?.type === WEBHOOK_VERIFY_TYPE;
+
+export const isWebhookTest = (body) => { const d = parseBody(body); return !!d && (d.type === WEBHOOK_TEST_TYPE || (d.type === undefined && d.event === "webhook.test")); };
+
+export const isWebhookPing = (body) => isWebhookVerify(body) || isWebhookTest(body);
+const hdr = (headers, name) => { if (!headers) return undefined; if (typeof headers.get === "function") return headers.get(name) ?? undefined; const k = Object.keys(headers).find((x) => x.toLowerCase() === name.toLowerCase()); const v = k === undefined ? undefined : headers[k]; return Array.isArray(v) ? v[0] : v; };
+export const headerOf = hdr;
+
+export function pickChallenge(body, headers) {
+  const bc = parseBody(body)?.challenge, hc = hdr(headers, "X-Relay-Challenge"), c = bc ?? hc;
+  return typeof c === "string" && c.length > 0 && c.length <= 256 && !(bc != null && hc != null && bc !== hc) ? c : null;
+}