@open-everywhere/provider-slack 0.1.5 → 0.3.0

package/agent/channels/slack-approval-card.ts

@@ -1,275 +0,0 @@
-// THE SLACK RETURN LEG FOR A BRIDGED APPROVAL CARD (OPE-1720) — what makes the button the unified
-// post arm now renders actually settle the approval it names.
-//
-// WHY THIS EXISTS RATHER THAN EVE'S OWN HITL ROUTE. eve's Slack channel has an interactivity seam for
-// its own `eve_input:` cards, and `slack-input-response.ts` is OE's admission on it. That seam cannot
-// serve this card, and the reason is structural rather than a not-yet: eve's own handler stores the
-// card it minted in the SLACK channel's state (`defaults.js` writes `state.pendingApprovalCards`) and
-// resolves the click against that channel's session address. A DM seat's parked request lives on the
-// UNIFIED window — another channel, another session, another state bag — so a click on a card OE
-// posted there has nothing for eve's route to resolve. It is OE's card, so it is OE's click.
-//
-// 🔴 THE SAME ADMISSION, THOUGH. `admitInputResponse` (core approvals/input-response-floor.ts) is the
-// ONE decision both HITL answer doors take, and `ingressSpendGate` with door `"answer"` is the same
-// spend floor `admitSlackInputResponse` consults FIRST for the same reason: a tap RESUMES a parked
-// turn, which is a decision to spend more on a scope nobody asked whether it could afford. This
-// module adds no floor of its own — it resolves the click, asks those two, and delivers.
-//
-// 🔴 A REFUSAL LEAVES THE CARD LIVE. Nothing here consumes a row on any outcome but a delivered
-// answer: the approval stays parked, the card stays tappable for somebody who may answer it, and the
-// question stays answerable IN WORDS through the text leg (`question-bridge.ts`), which is untouched.
-// That is the same "a refusal is not a drop" posture the text leg holds.
-
-import {
-  admitInputResponse,
-  APPROVAL_BUTTON_LABELS,
-  APPROVAL_CARD_REFUSED_AUDIT_ACTION as CORE_APPROVAL_CARD_REFUSED_AUDIT_ACTION,
-  APPROVAL_CARD_SETTLED_AUDIT_ACTION as CORE_APPROVAL_CARD_SETTLED_AUDIT_ACTION,
-  auditApprovalCardTap,
-  deploymentOrg,
-  forgetApprovalCardTicket,
-  forgetBridgedQuestion,
-  getOperationalStore,
-  ingressSpendGate,
-  parseApprovalClickId,
-  readBridgedQuestion,
-  readApprovalCardTicket,
-  resolveApprovalCardClick,
-  resolvePartition,
-  unifiedThreadRef,
-  SLACK_SPEND_BADGES,
-  type ApprovalCardRespondFn,
-  type BindableContext,
-} from "@open-everywhere/core/agent/adapter-api.js";
-import { slackClickerIsGuest, slackForm } from "./slack-events.js";
-
-const log = (m: string): void => console.log(`[open-everywhere:slack] approval card: ${m}`);
-
-/** The `input_response.routed` sibling for a tap: an approval settled through a BUTTON rather than a
- *  typed reply. RE-EXPORTED FROM CORE, never re-spelled here — one action name for every surface, so
- *  a scorer that joins on the row cannot under-count one of them (OPE-1856). */
-export const APPROVAL_CARD_SETTLED_AUDIT_ACTION = CORE_APPROVAL_CARD_SETTLED_AUDIT_ACTION;
-/** A verified tap that settled nothing, carrying WHICH refusal it was. Core-owned, as above. */
-export const APPROVAL_CARD_REFUSED_AUDIT_ACTION = CORE_APPROVAL_CARD_REFUSED_AUDIT_ACTION;
-
-/** The settle delivery this leg needs. CORE-OWNED and bound by the front route through
- *  `approvalCardRespondVia(args.attachSession)` — re-exported here, never re-spelled, so the address
- *  the answer takes cannot drift per surface (OPE-1863). */
-export type ApprovalRespondFn = ApprovalCardRespondFn;
-
-/** What one verified tap did, for the front route's log line. Never thrown — this endpoint answers a
- *  person who is waiting, so every path returns. */
-export interface ApprovalCardClickOutcome {
-  readonly handled: boolean;
-  readonly reason: string;
-  /** A line to show the tapper alone, or undefined when the outcome needs no note. */
-  readonly notice?: string;
-}
-
-/** The `block_actions` fields this leg reads, narrowed so nothing here needs Slack's own types. */
-interface ParsedApprovalClick {
-  readonly actionId: string;
-  readonly channelId: string;
-  readonly userId: string;
-  readonly teamId?: string;
-}
-
-/**
- * Read the one `oe_input:` action out of a verified `block_actions` payload. `undefined` when the
- * payload is not one of ours or is missing a field the decision needs — the front route then leaves
- * it alone rather than half-handling it.
- *
- * THE FIRST `oe_input:` ACTION WINS and the rest are ignored: Slack sends one action per click, and a
- * payload carrying two of ours is not a shape this host mints.
- */
-export function parseSlackApprovalClick(payload: unknown): ParsedApprovalClick | undefined {
-  if (typeof payload !== "object" || payload === null) return undefined;
-  const p = payload as Record<string, unknown>;
-  if (!Array.isArray(p.actions)) return undefined;
-  let actionId: string | undefined;
-  for (const a of p.actions as readonly unknown[]) {
-    const id = typeof a === "object" && a !== null ? (a as Record<string, unknown>).action_id : undefined;
-    if (typeof id === "string" && parseApprovalClickId(id) !== undefined) {
-      actionId = id;
-      break;
-    }
-  }
-  if (actionId === undefined) return undefined;
-  const channel = typeof p.channel === "object" && p.channel !== null ? (p.channel as Record<string, unknown>).id : undefined;
-  const user = typeof p.user === "object" && p.user !== null ? (p.user as Record<string, unknown>).id : undefined;
-  const team = typeof p.team === "object" && p.team !== null ? (p.team as Record<string, unknown>).id : undefined;
-  if (typeof channel !== "string" || channel.length === 0) return undefined;
-  if (typeof user !== "string" || user.length === 0) return undefined;
-  return { actionId, channelId: channel, userId: user, ...(typeof team === "string" && team.length > 0 ? { teamId: team } : {}) };
-}
-
-/** The bindable a partition resolve needs from a raw interactivity payload. The team id is the ONE
- *  attribute that matters here, and it is read off the wire rather than through a placeholder — the
- *  same reading, and the same reason, as `slackAuthTeamId` in slack-input-response.ts. */
-function bindableForClick(click: ParsedApprovalClick): BindableContext {
-  return {
-    channel: { kind: "slack" },
-    session: { auth: { current: { attributes: { ...(click.teamId ? { team_id: click.teamId } : {}), channel_id: click.channelId } } } },
-  } as unknown as BindableContext;
-}
-
-/**
- * The host copy that rides the delivered answer's `text` — the LABEL THIS DEPLOYMENT PUT ON THE
- * BUTTON, read back out of the same allowlist that minted it, so the transcript says what the person
- * actually chose. A tap carries no words, and writing the person's prose for them is not an option.
- * The fallback capitalises the eve-minted option id, which can only be reached by a row written
- * before an id left the allowlist; the DECISION is never this value, because eve settles on
- * `optionId` alone.
- */
-function approvalAnswerText(optionId: string): string {
-  return APPROVAL_BUTTON_LABELS.get(optionId.toLowerCase())?.label ?? optionId.charAt(0).toUpperCase() + optionId.slice(1);
-}
-
-/** Show the tapper alone why nothing happened. EPHEMERAL, never a message in the room: the card is
- *  still live for somebody who may answer it, and a public "you may not answer" note tells the room
- *  nothing it needs. Best-effort — a failed notice never changes the verdict. */
-async function notifyTapper(channelId: string, userId: string, text: string): Promise<void> {
-  try {
-    await slackForm("chat.postEphemeral", new URLSearchParams({ channel: channelId, user: userId, text }).toString());
-  } catch (err) {
-    log(`refusal notice failed to post: ${String(err)}`);
-  }
-}
-
-/**
- * Handle one verified `oe_input:` click: resolve it, admit it, deliver the answer to eve, consume the
- * rows. NEVER THROWS — the front route has already 200'd the interaction, and an unhandled throw here
- * would only lose the log line.
- *
- * 🔴 THE ANSWER TEXT IS HOST COPY, and it must be. A tap carries no words, so a transcript that read
- * the button as the person's own prose would be inventing their words. What rides is the host label
- * this deployment put on that button (`Approve` / `Cancel`), which is what the person actually chose,
- * and the `optionId` beside it is what eve settles on — `resolveApprovalOutcome` reads `optionId`
- * ALONE, so the text is transcript only and never the decision.
- *
- * 🔴 CONSUME-ONCE, AND BOTH ROWS. The ticket goes so a second tap on the same card cannot answer a
- * request eve has already settled; the outstanding-question row goes so the room's NEXT message is an
- * ordinary wake again rather than a second answer to a settled request. Both happen only after eve
- * accepted the delivery, exactly as the text leg orders them.
- *
- * THE LIMIT OF THAT, stated rather than implied: the read and the delete are not one atomic step, and
- * the delete runs only AFTER `respond` returns, so anything arriving while the first tap is still in
- * flight resolves against rows that are both still present. Two such deliveries each spend an
- * admission, each call `respond`, and each can write a settled audit row — so one approval can read
- * as decided by two taps. It is not a second DECISION: both had to be admitted and both had to name
- * an option the request offered, and eve's own resolution refuses the second delivery for a request
- * it already settled. A delivery that arrives after the first settle RETURNED is the covered case —
- * the ticket is gone and it resolves `no-ticket`.
- *
- * 🔴 A SECOND DELIVERY IS MOST LIKELY TO BE SLACK'S OWN, NOT A SECOND PERSON, and this handler does
- * not ack until the settle returns. Slack expects an interactivity endpoint to answer within about
- * three seconds; what it does past that — show the tapper a connection error, redeliver, or both —
- * is VENDOR BEHAVIOUR THIS TREE HAS NOT MEASURED, so do not read the bound above as covering it.
- * Acking first and settling in the background would remove the delay and widen exactly the window
- * this paragraph describes; the ordering here takes the narrower window instead. Whoever measures
- * the real behaviour should revisit that trade, with the measurement written down.
- */
-export async function handleSlackApprovalCardClick(payload: unknown, respond: ApprovalRespondFn): Promise<ApprovalCardClickOutcome> {
-  // 🔴 HOISTED OUT OF THE `try` SO THE `catch` CAN STAMP ITS ROW (OPE-1856). A throw anywhere below
-  // — including from the partition resolve itself — must still leave a row saying this deployment
-  // took a tap and settled nothing; core's auditor accepts an absent partition for that case.
-  let tapper = "";
-  let auditPartition: ReturnType<typeof resolvePartition> | undefined;
-  try {
-    const click = parseSlackApprovalClick(payload);
-    if (click === undefined) return { handled: false, reason: "not an oe_input: click" };
-    const parsed = parseApprovalClickId(click.actionId);
-    if (parsed === undefined) return { handled: false, reason: "oe_input: action id did not parse" };
-    tapper = click.userId;
-    const org = deploymentOrg();
-    const store = getOperationalStore();
-    const partition = resolvePartition(bindableForClick(click));
-    auditPartition = partition;
-    // THE SPEND GATE FIRST, ahead of the identity admission — the same order and the same reason
-    // `admitSlackInputResponse` takes: over budget outranks identity, and a decline must not spend a
-    // roster lookup. Its refusal copy is its own; a decline here leaves the request PENDING.
-    const spend = await ingressSpendGate({
-      bindable: bindableForClick(click),
-      door: "answer",
-      principalId: click.userId,
-      workspaceRef: click.teamId ?? null,
-      badges: SLACK_SPEND_BADGES,
-      post: async (text) => {
-        await notifyTapper(click.channelId, click.userId, text);
-      },
-    });
-    if (spend === "declined") {
-      // AUDITED, not only logged (OPE-1856): a decline is this deployment refusing a person's tap,
-      // and a refusal nobody can count is indistinguishable from a tap that never arrived.
-      await auditApprovalCardTap({ platform: "slack", principalId: click.userId, partition, outcome: { kind: "refused", reason: "spend-declined" } });
-      log(`tap declined by the spend gate — the approval stays parked`);
-      return { handled: true, reason: "spend-declined" };
-    }
-    // The room the tap came from, in the SAME vocabulary the card's ticket stored — derived through
-    // core's own codec rather than spelled here, so the two sides cannot drift on the key's shape.
-    const containerKey = unifiedThreadRef({ platform: "slack", channelId: click.channelId }).channelKey;
-    const routing = await resolveApprovalCardClick(
-      { ticket: parsed.ticket, optionId: parsed.optionId, containerKey },
-      {
-        read: (ticket) => readApprovalCardTicket(store, org, ticket),
-        // The join with the TEXT leg — see the dep's own note. Fail-CLOSED on an unreadable row: a
-        // store this leg cannot read cannot say the request is still parked, and settling on that
-        // guess is the one direction that spends a governed decision twice.
-        stillOutstanding: async (bareToken, requestId) => {
-          const outstanding = await readBridgedQuestion(store, org, bareToken).catch(() => undefined);
-          return outstanding?.requestId === requestId;
-        },
-        admit: async () => {
-          // Leg B, the same positive guest verdict both other clicker floors use, and inert on an
-          // unreadable probe (`undefined` never refuses).
-          const answererIsGuest = await slackClickerIsGuest(click.userId, click.teamId).catch(() => undefined);
-          const verdict = await admitInputResponse({
-            org: partition.org,
-            platform: partition.platform,
-            workspace: partition.workspace,
-            surface: partition.surface,
-            surfaceKey: partition.surfaceKey,
-            principalId: click.userId,
-            responses: 1,
-            ...(answererIsGuest === undefined ? {} : { answererIsGuest }),
-          });
-          return { ok: verdict.ok, floor: verdict.ok ? verdict.floor : "", notice: verdict.ok ? "" : verdict.notice };
-        },
-      },
-    );
-    if (routing.kind === "refuse") {
-      await auditApprovalCardTap({ platform: "slack", principalId: click.userId, partition, outcome: { kind: "refused", reason: routing.reason } });
-      if (routing.notice !== undefined) await notifyTapper(click.channelId, click.userId, routing.notice);
-      log(`tap settled nothing (${routing.reason}) — the approval stays parked and answerable in words`);
-      return { handled: true, reason: routing.reason, ...(routing.notice ? { notice: routing.notice } : {}) };
-    }
-    const label = approvalAnswerText(routing.optionId);
-    // 🔴 DELIVERED BY SESSION ID, never by the window token (OPE-1863): a continuation token is
-    // channel-local, and this route is the SLACK channel's, so `from(bareToken)` here named a
-    // session that never existed and the settle threw into the catch below. The token's job is the
-    // outstanding-question row on the two lines that follow.
-    await respond(routing.sessionId, { requestId: routing.requestId, optionId: routing.optionId, text: label });
-    // CONSUME-ONCE, and only now that eve accepted the delivery. A throw above skips both, which
-    // leaves the card tappable and the question answerable — the safe direction.
-    await forgetApprovalCardTicket(store, org, parsed.ticket);
-    await forgetBridgedQuestion(store, org, routing.bareToken);
-    await auditApprovalCardTap({
-      platform: "slack",
-      principalId: click.userId,
-      partition,
-      outcome: { kind: "settled", requestId: routing.requestId, optionId: routing.optionId, floor: routing.floor },
-    });
-    log(`tap settled ${routing.requestId} as "${routing.optionId}" (floor ${routing.floor})`);
-    return { handled: true, reason: "settled" };
-  } catch (err) {
-    // The approval is still parked and the card is still tappable, so the honest outcome is to say so
-    // and leave both rows in place. Never a throw: this runs after the interaction was acknowledged.
-    // AUDITED, not only logged (OPE-1856): ship #212's S-EVE-CARD leg could not say whether its tap
-    // had been refused or had thrown, because neither arm left a row. `auditApprovalCardTap` never
-    // throws, so this cannot turn a failed tap into a failed response.
-    await auditApprovalCardTap({ platform: "slack", principalId: tapper, ...(auditPartition === undefined ? {} : { partition: auditPartition }), outcome: { kind: "refused", reason: "error" } });
-    log(`tap failed (${(err as Error)?.message ?? String(err)}) — nothing was settled, the approval stays parked`);
-    return { handled: true, reason: "error" };
-  }
-}
-