@firedrill-tools/slack 0.1.1

package/firedrill/tools/slack/lib/access.mjs

@@ -0,0 +1,138 @@
+// Bot-token shaped visibility, membership and archive rules. Every rule reads context.state; nothing is cached.
+import { SCAN_CAP, SCAN_STEP, membershipRowId } from "./ids.mjs";
+
+export function fail(context, code, message = code.toLowerCase()) {
+  return context.fail({ code, message });
+}
+
+/**
+ * Rows this synthetic workspace serves per namespace (users and conversations per workspace; members, messages and
+ * pins per conversation) unless the workspace row carries `limits`. A read that finds more rows than its bound fails
+ * with TOO_MANY_ROWS instead of returning the first N rows; pins.add refuses to exceed the pin bound (Slack's own limit
+ * is 100 pins per conversation).
+ */
+export const DEFAULT_LIMITS = { users: 1000, conversations: 1000, members: 1000, messages: 10000, pins: 100 };
+const LIMIT_OF_NAMESPACE = { users: "users", conversations: "conversations", memberships: "members", messages: "messages", pins: "pins" };
+
+export function limitsOf(context) {
+  const team = context.state.get("workspace", "team");
+  return { ...DEFAULT_LIMITS, ...(team !== null && team.limits !== undefined ? team.limits : {}) };
+}
+
+function boundOf(context, namespace) {
+  return Math.min(SCAN_CAP, limitsOf(context)[LIMIT_OF_NAMESPACE[namespace]] ?? SCAN_CAP);
+}
+
+/**
+ * Refuse, before anything is allocated or written, a set that would exceed its bound once stored (e.g. the memberships
+ * of a conversation conversations.open is about to create). A declared error rolls back every write of the operation,
+ * id counters included, so the message names the requested count and the workspace limit only, never an id the
+ * operation would have allocated.
+ */
+export function requireWithinBound(context, namespace, count, subject) {
+  const bound = boundOf(context, namespace);
+  if (count > bound) {
+    return fail(context, "TOO_MANY_ROWS", `${subject} (${count}) exceed the supported bound of ${bound} rows (workspace.limits.${LIMIT_OF_NAMESPACE[namespace]})`);
+  }
+  return count;
+}
+
+function tooManyRows(context, namespace, prefix, bound) {
+  const where = prefix === undefined ? namespace : `${namespace} in ${prefix.slice(0, -1)}`;
+  return fail(context, "TOO_MANY_ROWS", `${where} exceed the supported bound of ${bound} rows (workspace.limits.${LIMIT_OF_NAMESPACE[namespace]})`);
+}
+
+/**
+ * Every row of one namespace whose row id starts with `prefix` (or the whole namespace when no prefix is given), via
+ * bounded scans that read one row past the bound: more rows than the bound is an explicit TOO_MANY_ROWS, never a
+ * silently shortened list.
+ */
+export function prefixRows(context, namespace, prefix) {
+  const bound = boundOf(context, namespace);
+  const rows = [];
+  let after = prefix;
+  while (rows.length <= bound) {
+    const limit = Math.min(SCAN_STEP, bound + 1 - rows.length);
+    const batch = context.state.scan(namespace, { ...(after === undefined ? {} : { afterRowId: after }), limit });
+    for (const record of batch) {
+      if (prefix !== undefined && !record.rowId.startsWith(prefix)) return rows;
+      after = record.rowId;
+      rows.push(record.value);
+    }
+    if (batch.length < limit) break;
+  }
+  if (rows.length > bound) return tooManyRows(context, namespace, prefix, bound);
+  return rows;
+}
+
+/** Every row of a workspace-wide namespace (users, conversations), bounded like prefixRows. */
+export function allRows(context, namespace) {
+  return prefixRows(context, namespace, undefined);
+}
+
+/**
+ * The member a caller without a `userId` attribute acts as: the first active human member in `users` row-id order
+ * (deactivated and bot users skipped), so a fresh `firedrill tool add` actor is a member of the seeded workspace. The
+ * scan stops at the first match; a workspace without such a member yields null.
+ */
+function defaultMember(context) {
+  let after;
+  for (let scanned = 0; scanned < SCAN_CAP; scanned += SCAN_STEP) {
+    const batch = context.state.scan("users", { ...(after === undefined ? {} : { afterRowId: after }), limit: SCAN_STEP });
+    for (const record of batch) {
+      after = record.rowId;
+      const user = record.value;
+      if (user.deleted !== true && user.is_bot !== true) return user;
+    }
+    if (batch.length < SCAN_STEP) break;
+  }
+  return null;
+}
+
+/**
+ * The workspace member this actor acts as: `attributes.userId` when present (a token that resolves to no member is
+ * `invalid_auth`), otherwise the workspace's default member (see defaultMember).
+ */
+export function requireActor(context) {
+  const userId = context.actor.attributes.userId;
+  let user;
+  if (typeof userId === "string" && userId.length > 0) {
+    user = context.state.get("users", userId);
+    if (user === null || user.id !== userId) return fail(context, "INVALID_AUTH");
+  } else {
+    user = defaultMember(context);
+    if (user === null) return fail(context, "INVALID_AUTH", "invalid_auth: this workspace has no active human member to act as; set the actor attribute userId");
+  }
+  const teamId = context.actor.attributes.teamId;
+  if (typeof teamId === "string" && teamId.length > 0 && teamId !== user.team_id) return fail(context, "INVALID_AUTH");
+  return user;
+}
+
+export function isPublicChannel(conversation) {
+  return conversation.is_channel === true && conversation.is_private !== true;
+}
+
+export function isMember(context, channelId, userId) {
+  return context.state.get("memberships", membershipRowId(channelId, userId)) !== null;
+}
+
+/**
+ * A conversation the actor may know about: public channels always, private channels, IMs and group DMs
+ * only through membership. Anything else is indistinguishable from missing.
+ */
+export function visibleConversation(context, actorId, channelId) {
+  const conversation = typeof channelId === "string" && channelId.length > 0 ? context.state.get("conversations", channelId) : null;
+  if (conversation === null) return fail(context, "CHANNEL_NOT_FOUND");
+  if (isPublicChannel(conversation) || isMember(context, channelId, actorId)) return conversation;
+  return fail(context, "CHANNEL_NOT_FOUND");
+}
+
+export function requireMember(context, conversation, actorId) {
+  if (!isMember(context, conversation.id, actorId)) return fail(context, "NOT_IN_CHANNEL");
+  return conversation;
+}
+
+export function requireActive(context, conversation) {
+  if (conversation.is_archived === true) return fail(context, "IS_ARCHIVED");
+  return conversation;
+}

package/firedrill/tools/slack/lib/budget.mjs

@@ -0,0 +1,67 @@
+// Response byte budget. The HTTP layer refuses route responses over 1 MiB, so every list and read sizes its page by the
+// UTF-8 bytes of the encoded JSON body as well as by count. Bytes are computed from code points (no Buffer), because
+// String#length counts UTF-16 code units and undercounts CJK and emoji text by up to three times.
+
+/** Body bytes a list or read may produce unless the workspace row lowers it (workspace.limits.response_bytes). */
+export const RESPONSE_BYTES = 900000;
+
+/** UTF-8 byte length of a string, computed from its code points (lone surrogates count as U+FFFD, 3 bytes). */
+export function utf8Bytes(text) {
+  let bytes = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const unit = text.charCodeAt(index);
+    if (unit < 0x80) bytes += 1;
+    else if (unit < 0x800) bytes += 2;
+    else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < text.length) {
+      const next = text.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** UTF-8 bytes of the compact JSON encoding of a value (the shape the route sends). */
+export function jsonBytes(value) {
+  return utf8Bytes(JSON.stringify(value));
+}
+
+/**
+ * How many leading `items` fit in a body whose envelope (with an empty list) is `envelopeBytes`, given at most `limit`
+ * items. Each admitted item adds its own bytes plus one comma after the first. Returns 0 when the first item alone does
+ * not fit; the caller answers its declared error instead of an empty or oversized page.
+ */
+export function fitCount(items, limit, envelopeBytes, budget, sizeOf) {
+  let used = envelopeBytes;
+  let count = 0;
+  const cap = Math.min(limit, items.length);
+  while (count < cap) {
+    const next = sizeOf(items[count]) + (count === 0 ? 0 : 1);
+    if (used + next > budget) break;
+    used += next;
+    count += 1;
+  }
+  return count;
+}
+
+/**
+ * Largest page size k ≤ `perPage` for which every page of k consecutive items (search's page arithmetic) fits the
+ * budget. Sizes are measured once; each candidate is checked with a prefix sum, so the cost is items × candidates.
+ * Returns 0 when a single item alone exceeds the budget.
+ */
+export function uniformPageSize(sizes, perPage, envelopeBytes, budget) {
+  if (sizes.length === 0) return perPage;
+  const prefix = [0];
+  for (const size of sizes) prefix.push(prefix[prefix.length - 1] + size);
+  for (let size = perPage; size >= 1; size -= 1) {
+    let fits = true;
+    for (let start = 0; start < sizes.length && fits; start += size) {
+      const end = Math.min(start + size, sizes.length);
+      fits = envelopeBytes + prefix[end] - prefix[start] + (end - start - 1) <= budget;
+    }
+    if (fits) return size;
+  }
+  return 0;
+}

package/firedrill/tools/slack/lib/ids.mjs

@@ -0,0 +1,146 @@
+// Identifier, timestamp and cursor rendering shared by the behavior module, the HTTP codecs and the
+// conformance data. Pure and deterministic: no Node built-ins, no wall clock, no randomness.
+
+/** Bounded state scans: rows are read in steps and never beyond the cap. */
+export const SCAN_STEP = 1000;
+export const SCAN_CAP = 10000;
+
+/** Slack message timestamps look like "1789376400.000301": epoch seconds, a dot, six digits. */
+export const TS_PATTERN = /^[0-9]{10}\.[0-9]{6}$/;
+
+export function pad6(value) {
+  return String(value).padStart(6, "0");
+}
+
+/** The most message timestamps one virtual second can hold: the fraction is exactly six digits. */
+export const MAX_TS_SEQUENCE = 999_999;
+
+/** Render a `ts` from virtual epoch seconds and the per-workspace message sequence. */
+export function renderTs(seconds, sequence) {
+  return `${String(seconds).padStart(10, "0")}.${pad6(sequence)}`;
+}
+
+export function isTs(value) {
+  return typeof value === "string" && TS_PATTERN.test(value);
+}
+
+/** `oldest`/`latest` arguments: a full ts or plain epoch seconds (optionally with a fraction). */
+export function isTsLike(value) {
+  return typeof value === "string" && /^[0-9]{1,10}(?:\.[0-9]{1,6})?$/.test(value);
+}
+
+export function tsNumber(value) {
+  return Number(value);
+}
+
+export function tsSeconds(ts) {
+  return Number(ts.slice(0, 10));
+}
+
+/** Two well-formed ts values compare as strings because seconds are fixed-width. */
+export function compareTs(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** Generated conversation ids: "C" or "D" followed by a zero-padded base-36 sequence (11 characters). */
+export function conversationId(prefix, sequence) {
+  return `${prefix}${sequence.toString(36).toUpperCase().padStart(10, "0")}`;
+}
+
+export function messageRowId(channel, ts) {
+  return `${channel}:${ts}`;
+}
+
+export function membershipRowId(channel, user) {
+  return `${channel}:${user}`;
+}
+
+export function pinRowId(channel, ts) {
+  return `${channel}:${ts}`;
+}
+
+/** Slack-style permalink built from the workspace url stored in data; it resolves nowhere. */
+export function permalink(workspaceUrl, channel, ts) {
+  return `${workspaceUrl}archives/${channel}/p${ts.replace(".", "")}`;
+}
+
+/** Wire error strings are the lower-snake spelling of the declared code (CHANNEL_NOT_FOUND → channel_not_found). */
+export function lowerSnake(code) {
+  return String(code).toLowerCase();
+}
+
+/**
+ * UTC calendar day (YYYY-MM-DD) of an epoch-seconds value, computed arithmetically (Howard Hinnant's
+ * civil-from-days) so the search date modifiers never touch the host Date implementation.
+ */
+export function isoDay(seconds) {
+  const days = Math.floor(seconds / 86400);
+  const z = days + 719468;
+  const era = Math.floor(z / 146097);
+  const dayOfEra = z - era * 146097;
+  const yearOfEra = Math.floor((dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365);
+  const dayOfYear = dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+  const monthIndex = Math.floor((5 * dayOfYear + 2) / 153);
+  const day = dayOfYear - Math.floor((153 * monthIndex + 2) / 5) + 1;
+  const month = monthIndex < 10 ? monthIndex + 3 : monthIndex - 9;
+  const year = yearOfEra + era * 400 + (month <= 2 ? 1 : 0);
+  return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** base64url without padding, ASCII input only (cursors contain ids, digits, dots and colons). */
+export function base64url(text) {
+  let output = "";
+  let index = 0;
+  while (index < text.length) {
+    const first = text.charCodeAt(index++);
+    const second = index < text.length ? text.charCodeAt(index++) : undefined;
+    const third = index < text.length ? text.charCodeAt(index++) : undefined;
+    if (first > 127 || (second !== undefined && second > 127) || (third !== undefined && third > 127)) {
+      throw new TypeError("cursor text must be ASCII");
+    }
+    output += ALPHABET[first >> 2];
+    output += ALPHABET[((first & 3) << 4) | ((second ?? 0) >> 4)];
+    if (second !== undefined) output += ALPHABET[((second & 15) << 2) | ((third ?? 0) >> 6)];
+    if (third !== undefined) output += ALPHABET[third & 63];
+  }
+  return output;
+}
+
+/** Inverse of base64url; returns null for anything that is not well-formed ASCII base64url. */
+export function fromBase64url(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length % 4 === 1 || /[^A-Za-z0-9_-]/.test(value)) {
+    return null;
+  }
+  let bits = 0;
+  let buffer = 0;
+  let output = "";
+  for (const character of value) {
+    buffer = (buffer << 6) | ALPHABET.indexOf(character);
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      const code = (buffer >> bits) & 255;
+      if (code > 127) return null;
+      output += String.fromCharCode(code);
+    }
+  }
+  return output;
+}
+
+/** Cursors mirror Slack's opaque-but-decodable shape: base64url("<kind>:<value>"). */
+export function encodeCursor(kind, value) {
+  return base64url(`${kind}:${value}`);
+}
+
+/** Decode a cursor of the expected kind; null when malformed or of another kind. */
+export function decodeCursor(cursor, kind) {
+  const text = fromBase64url(cursor);
+  if (text === null) return null;
+  const separator = text.indexOf(":");
+  if (separator <= 0) return null;
+  if (text.slice(0, separator) !== kind) return null;
+  const value = text.slice(separator + 1);
+  return value.length > 0 ? value : null;
+}

package/firedrill/tools/slack/lib/search.mjs

@@ -0,0 +1,172 @@
+// search.messages query grammar: whitespace-separated terms, "quoted phrases", -negation and a documented
+// modifier subset. Pure functions; the behavior module supplies the environment (handles, membership, pins).
+import { isoDay, tsSeconds } from "./ids.mjs";
+
+export class SearchError extends Error {}
+
+const MODIFIER = /^(-?)([a-z_]+):(.*)$/s;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const MONTH = /^\d{4}-\d{2}$/;
+
+/** Split on whitespace while keeping double-quoted phrases together. */
+function tokenize(query) {
+  const tokens = [];
+  let current = "";
+  let quoted = false;
+  for (const character of query) {
+    if (character === '"') {
+      quoted = !quoted;
+      current += character;
+      continue;
+    }
+    if (!quoted && /\s/.test(character)) {
+      if (current.length > 0) tokens.push(current);
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  if (current.length > 0) tokens.push(current);
+  return tokens;
+}
+
+function unquote(value) {
+  return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}
+
+/**
+ * Parse a query into bare terms and modifiers. Throws SearchError for modifiers outside the subset,
+ * which the handler reports as INVALID_ARGUMENTS (Slack would treat them as text; documented deviation).
+ */
+export function parseQuery(query) {
+  const terms = [];
+  const modifiers = [];
+  for (const token of tokenize(query)) {
+    const match = token.startsWith('"') ? null : MODIFIER.exec(token);
+    if (match === null) {
+      const negate = token.startsWith("-") && token.length > 1 && !token.startsWith('-"');
+      const raw = negate ? token.slice(1) : token.startsWith('-"') ? token.slice(1) : token;
+      const text = unquote(raw).toLowerCase();
+      if (text.length > 0) terms.push({ text, negate: negate || token.startsWith('-"'), phrase: raw.startsWith('"') });
+      continue;
+    }
+    const negate = match[1] === "-";
+    const op = match[2];
+    const value = unquote(match[3]);
+    switch (op) {
+      case "in":
+      case "from": {
+        if (value.length === 0) throw new SearchError(`Search modifier "${op}:" needs a value`);
+        modifiers.push({ op, value, negate });
+        break;
+      }
+      case "is": {
+        if (value !== "thread") throw new SearchError(`Unsupported search modifier "is:${value}"`);
+        modifiers.push({ op, value, negate });
+        break;
+      }
+      case "has": {
+        const emoji = /^:([a-z0-9_+-]{1,100}):$/.exec(value);
+        if (value === "pin" || value === "reaction") modifiers.push({ op, value, negate });
+        else if (emoji !== null) modifiers.push({ op: "has-emoji", value: emoji[1], negate });
+        else throw new SearchError(`Unsupported search modifier "has:${value}"`);
+        break;
+      }
+      case "before":
+      case "after":
+      case "on": {
+        if (!DAY.test(value)) throw new SearchError(`Search modifier "${op}:" needs a YYYY-MM-DD date`);
+        modifiers.push({ op, value, negate });
+        break;
+      }
+      case "during": {
+        if (!MONTH.test(value)) throw new SearchError(`Search modifier "during:" needs a YYYY-MM month`);
+        modifiers.push({ op, value, negate });
+        break;
+      }
+      default:
+        throw new SearchError(`Unsupported search modifier "${op}:"`);
+    }
+  }
+  return { terms, modifiers };
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Does `message` match the parsed query? Returns null for no match, otherwise a deterministic integer score:
+ * 10 per matching bare term, +5 when the term is a whole word, +1 when the message is a thread parent or plain post.
+ *
+ * `env`: { conversation, actorId, authorHandle(userId) → handle|null, partnerHandle(conversation) → handle|null,
+ *          isPinned(message) → boolean }
+ */
+export function scoreMessage(parsed, message, env) {
+  const text = String(message.text ?? "");
+  const lower = text.toLowerCase();
+  let score = 0;
+  for (const term of parsed.terms) {
+    const present = lower.includes(term.text);
+    if (term.negate ? present : !present) return null;
+    if (!term.negate) {
+      score += 10;
+      if (new RegExp(`(^|[^a-z0-9_])${escapeRegExp(term.text)}($|[^a-z0-9_])`, "i").test(text)) score += 5;
+    }
+  }
+  for (const modifier of parsed.modifiers) {
+    let matched;
+    switch (modifier.op) {
+      case "in":
+        matched = conversationMatches(env.conversation, modifier.value, env);
+        break;
+      case "from":
+        matched = authorMatches(message, modifier.value, env);
+        break;
+      case "is":
+        matched = typeof message.thread_ts === "string";
+        break;
+      case "has":
+        matched = modifier.value === "pin" ? env.isPinned(message) : Array.isArray(message.reactions) && message.reactions.length > 0;
+        break;
+      case "has-emoji":
+        matched = Array.isArray(message.reactions) && message.reactions.some((reaction) => reaction.name === modifier.value);
+        break;
+      case "before":
+        matched = isoDay(tsSeconds(message.ts)) < modifier.value;
+        break;
+      case "after":
+        matched = isoDay(tsSeconds(message.ts)) > modifier.value;
+        break;
+      case "on":
+        matched = isoDay(tsSeconds(message.ts)) === modifier.value;
+        break;
+      case "during":
+        matched = isoDay(tsSeconds(message.ts)).startsWith(`${modifier.value}-`);
+        break;
+      default:
+        matched = false;
+    }
+    if (modifier.negate ? matched : !matched) return null;
+  }
+  const isReply = typeof message.thread_ts === "string" && message.thread_ts !== message.ts;
+  return score + (isReply ? 0 : 1);
+}
+
+function conversationMatches(conversation, value, env) {
+  const channelRef = /^<#([A-Z0-9]+)(?:\|[^>]*)?>$/.exec(value);
+  if (channelRef !== null) return conversation.id === channelRef[1];
+  if (value.startsWith("@")) {
+    return conversation.is_im === true && env.partnerHandle(conversation) === value.slice(1).toLowerCase();
+  }
+  const name = value.startsWith("#") ? value.slice(1) : value;
+  return conversation.id === name || conversation.name === name.toLowerCase();
+}
+
+function authorMatches(message, value, env) {
+  if (value === "me") return message.user === env.actorId;
+  const userRef = /^<@([A-Z0-9]+)(?:\|[^>]*)?>$/.exec(value);
+  if (userRef !== null) return message.user === userRef[1];
+  const handle = (value.startsWith("@") ? value.slice(1) : value).toLowerCase();
+  return message.user === handle || env.authorHandle(message.user) === handle;
+}

package/firedrill/tools/slack/lib/wire.mjs

@@ -0,0 +1,144 @@
+// Slack Web API wire helpers: query/form parameters → typed arguments, and the `{ ok: false, error }` envelope.
+// Pure functions with no state access, so the HTTP codecs can use them.
+import { lowerSnake } from "./ids.mjs";
+
+/** Seconds a rate-limited client should wait; sent as `Retry-After` with every 429. */
+export const RETRY_AFTER_SECONDS = "30";
+
+/**
+ * Parameters of a Slack call: the query string on GET; on POST an `application/x-www-form-urlencoded` body (the SDK
+ * convention, also assumed when no content type is sent) or an `application/json` object body, as the Web API accepts
+ * both with a bearer token. Routes declare the body as raw text so this codec can tell the two apart itself. Every
+ * value is normalised to the form shape (name → list of strings; JSON arrays and objects re-encoded as JSON text), so
+ * the typed readers below work the same for both encodings.
+ */
+export function params(request) {
+  if (request.method === "GET") return request.query;
+  const body = request.body ?? {};
+  if (body.kind === "form") return body.value;
+  if (body.kind !== "text" || typeof body.value !== "string") return Object.create(null);
+  const type = mediaType(last(request.headers?.["content-type"]));
+  if (type === "application/json" || type.endsWith("+json")) return jsonParams(body.value);
+  if (type === "" || type === "application/x-www-form-urlencoded") return formParams(body.value);
+  throw new TypeError("request content type must be application/x-www-form-urlencoded or application/json");
+}
+
+function mediaType(header) {
+  return typeof header === "string" ? header.split(";", 1)[0].trim().toLowerCase() : "";
+}
+
+function formParams(text) {
+  const form = Object.create(null);
+  for (const [name, value] of new URLSearchParams(text)) {
+    if (form[name] === undefined) form[name] = [];
+    form[name].push(value);
+  }
+  return form;
+}
+
+/** A JSON body must be an object (Slack: invalid_json / json_not_object); values become form strings. */
+function jsonParams(text) {
+  if (text.trim().length === 0) return Object.create(null);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new TypeError("request body must be valid JSON (Slack: invalid_json)");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new TypeError("request body must be a JSON object (Slack: json_not_object)");
+  }
+  const form = Object.create(null);
+  for (const [name, value] of Object.entries(parsed)) {
+    if (value === null || value === undefined) continue;
+    form[name] = [typeof value === "object" ? jsonText(name, value) : String(value)];
+  }
+  return form;
+}
+
+function jsonText(name, value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    throw new TypeError(`${name} nests too deeply`);
+  }
+}
+
+/** Slack keeps the last value of a repeated parameter. */
+function last(values) {
+  return values === undefined || values.length === 0 ? undefined : values[values.length - 1];
+}
+
+export function str(source, name) {
+  return last(source[name]);
+}
+
+export function int(source, name) {
+  const value = last(source[name]);
+  if (value === undefined) return undefined;
+  if (!/^-?[0-9]{1,9}$/.test(value)) throw new TypeError(`${name} must be an integer`);
+  return Number(value);
+}
+
+export function bool(source, name) {
+  const value = last(source[name]);
+  if (value === undefined) return undefined;
+  if (value === "true" || value === "1") return true;
+  if (value === "false" || value === "0") return false;
+  throw new TypeError(`${name} must be true, false, 1 or 0`);
+}
+
+/** `blocks`/`attachments` travel as a JSON string inside the form, exactly as the official SDKs send them. */
+export function json(source, name) {
+  const value = last(source[name]);
+  if (value === undefined) return undefined;
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new TypeError(`${name} must be a JSON string`);
+  }
+}
+
+/** Drop undefined values so the arguments object validates against the input schema. */
+export function defined(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}
+
+/** Mutations accept an optional X-Firedrill-Idempotency-Key header (Slack clients never send one). */
+export function operationInput(request, args) {
+  const key = last(request.headers["x-firedrill-idempotency-key"]);
+  return key === undefined || key.length === 0 ? { arguments: args } : { arguments: args, idempotencyKey: key };
+}
+
+/**
+ * Slack-shaped error body for every non-ok outcome. Status codes are framework-owned (declared per route);
+ * real Slack answers HTTP 200 with ok:false for most of these, which this Tool cannot reproduce.
+ */
+export function slackError(invocation, outcome) {
+  const error = outcome.error ?? {};
+  const message = typeof error.message === "string" ? error.message : "";
+  if (outcome.status === "denied") {
+    const needed = `${invocation.operation.packageId}.${invocation.operation.operationId}`;
+    return {
+      headers: {},
+      body: { kind: "json", value: { ok: false, error: "missing_scope", needed, provided: "" } },
+    };
+  }
+  if (outcome.status === "unsupported") {
+    return { headers: {}, body: { kind: "json", value: { ok: false, error: "unknown_method" } } };
+  }
+  if (outcome.status === "invalid") {
+    return {
+      headers: {},
+      body: {
+        kind: "json",
+        value: { ok: false, error: "invalid_arguments", response_metadata: { messages: [message || "invalid arguments"] } },
+      },
+    };
+  }
+  const code = String(error.code ?? "").replace(/^tool\./, "");
+  const wire = code.length > 0 ? lowerSnake(code) : "internal_error";
+  const value = { ok: false, error: wire };
+  if (message.length > 0 && message !== wire) value.response_metadata = { messages: [message] };
+  return { headers: wire === "ratelimited" ? { "retry-after": RETRY_AFTER_SECONDS } : {}, body: { kind: "json", value } };
+}