@ithousecall/chat 0.0.0-stage → 0.2.1

package/dist/chat/googlechat.js

@@ -0,0 +1,329 @@
+import { chat } from "@googleapis/chat";
+import { GoogleAuth, OAuth2Client } from "google-auth-library";
+import { z } from "zod";
+import { escapeHtml } from "../format.js";
+import { approvalArgs, decisionText, messageRef, } from "./adapter.js";
+import { fetchCapped } from "./download.js";
+import { toGoogleChat } from "./markdown.js";
+/** The thread ID of a DM's top level: one conversation per DM, answered without a thread. */
+export const DM_TOP_LEVEL = "dm";
+const User = z.object({ name: z.string(), displayName: z.string().optional(), type: z.string().optional() });
+const Space = z.object({
+    name: z.string(),
+    type: z.string().optional(),
+    spaceType: z.string().optional(),
+    singleUserBotDm: z.boolean().optional(),
+});
+/** Uploaded files have an `attachmentDataRef`; Drive files have none and are not downloaded. */
+const ChatAttachment = z.object({
+    contentName: z.string().optional(),
+    contentType: z.string().optional(),
+    attachmentDataRef: z.object({ resourceName: z.string().optional() }).optional(),
+});
+const Message = z.object({
+    name: z.string(),
+    attachment: z.array(ChatAttachment).optional(),
+    text: z.string().optional(),
+    argumentText: z.string().optional(),
+    createTime: z.string(),
+    sender: User,
+    thread: z.object({ name: z.string() }).optional(),
+    space: Space.optional(),
+    annotations: z.array(z.object({ type: z.string(), userMention: z.object({ user: User }).optional() })).optional(),
+});
+const Parameters = z.object({ approvalId: z.string(), decision: z.enum(["approve", "deny"]) });
+/** Chat API apps receive `type` + `message`/`common`; Workspace add-on Chat apps receive `chat` + `commonEventObject`. */
+const Event = z.object({
+    type: z.string().optional(),
+    space: Space.optional(),
+    message: Message.optional(),
+    user: User.optional(),
+    common: z.object({ parameters: z.record(z.string(), z.string()).optional() }).optional(),
+    commonEventObject: z.object({ parameters: z.record(z.string(), z.string()).optional() }).optional(),
+    chat: z
+        .object({
+        user: User.optional(),
+        messagePayload: z.object({ space: Space, message: Message }).optional(),
+        buttonClickedPayload: z.object({ space: Space, message: Message }).optional(),
+    })
+        .optional(),
+});
+function chatUser(user) {
+    return user.displayName === undefined ? { id: user.name } : { id: user.name, name: user.displayName };
+}
+function isDirectSpace(space) {
+    return space.type === "DM" || space.spaceType === "DIRECT_MESSAGE" || space.singleUserBotDm === true;
+}
+function normalizeGoogleChatMessage(message, space) {
+    if (message.sender.type === "BOT")
+        return undefined;
+    const isDirect = isDirectSpace(space);
+    return {
+        platform: "googlechat",
+        spaceId: space.name,
+        threadId: isDirect ? DM_TOP_LEVEL : (message.thread?.name ?? message.name),
+        messageId: message.name,
+        user: chatUser(message.sender),
+        text: (message.argumentText ?? message.text ?? "").trim(),
+        attachments: (message.attachment ?? []).map((attachment) => ({
+            name: attachment.contentName ?? "file",
+            mimeType: attachment.contentType ?? "application/octet-stream",
+            source: attachment.attachmentDataRef?.resourceName ?? "",
+        })),
+        isDirect,
+        mentionsBot: (message.annotations ?? []).some((annotation) => annotation.type === "USER_MENTION" && annotation.userMention?.user.type === "BOT"),
+        cursor: message.createTime,
+    };
+}
+function decision(parameters, user) {
+    const parsed = Parameters.safeParse(parameters);
+    if (!parsed.success || user === undefined)
+        return undefined;
+    return { approvalId: parsed.data.approvalId, decision: parsed.data.decision, user: chatUser(user) };
+}
+export function normalizeGoogleChatEvent(body) {
+    const parsed = Event.safeParse(body);
+    if (!parsed.success)
+        return { kind: "ignored" };
+    const event = parsed.data;
+    const addOn = event.chat;
+    let message;
+    let approval;
+    if (addOn?.messagePayload !== undefined) {
+        message = normalizeGoogleChatMessage(addOn.messagePayload.message, addOn.messagePayload.space);
+    }
+    else if (addOn?.buttonClickedPayload !== undefined) {
+        approval = decision(event.commonEventObject?.parameters, addOn.user);
+    }
+    else if (event.type === "MESSAGE" && event.message !== undefined) {
+        const space = event.space ?? event.message.space;
+        message = space === undefined ? undefined : normalizeGoogleChatMessage(event.message, space);
+    }
+    else if (event.type === "CARD_CLICKED") {
+        approval = decision(event.common?.parameters, event.user);
+    }
+    if (message !== undefined)
+        return { kind: "message", message };
+    if (approval !== undefined)
+        return { kind: "approval", decision: approval, addOn: addOn !== undefined };
+    return { kind: "ignored" };
+}
+const CHAT_ISSUER = "chat@system.gserviceaccount.com";
+const CHAT_CERTS = `https://www.googleapis.com/service_accounts/v1/metadata/x509/${CHAT_ISSUER}`;
+const GOOGLE_CERTS = "https://www.googleapis.com/oauth2/v1/certs";
+const GOOGLE_ISSUERS = ["accounts.google.com", "https://accounts.google.com"];
+const CERTS_TTL_MS = 60 * 60_000;
+function cachedCertificates() {
+    const cache = new Map();
+    return (url) => {
+        const hit = cache.get(url);
+        if (hit !== undefined && Date.now() - hit.at < CERTS_TTL_MS)
+            return hit.certs;
+        const certs = fetch(url).then(async (response) => {
+            if (!response.ok)
+                throw new Error(`${url} answered ${response.status}`);
+            return (await response.json());
+        });
+        certs.catch(() => cache.delete(url));
+        cache.set(url, { at: Date.now(), certs });
+        return certs;
+    };
+}
+/**
+ * Accepts only this project's requests: a Chat API app with the "Project Number" authentication audience gets a JWT
+ * from Chat for the project number; a Workspace add-on Chat app gets a Google ID token for the endpoint URL from the
+ * project's own add-on service agent.
+ */
+export function googleTokenVerifier(projectNumber, endpointUrl, certificates = cachedCertificates()) {
+    const client = new OAuth2Client();
+    const addOnAgent = `service-${projectNumber}@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`;
+    return async (authorization) => {
+        const token = /^Bearer (.+)$/.exec(authorization ?? "")?.[1];
+        if (token === undefined)
+            return false;
+        try {
+            await client.verifySignedJwtWithCertsAsync(token, await certificates(CHAT_CERTS), projectNumber, [CHAT_ISSUER]);
+            return true;
+        }
+        catch { }
+        try {
+            const ticket = await client.verifySignedJwtWithCertsAsync(token, await certificates(GOOGLE_CERTS), endpointUrl, GOOGLE_ISSUERS);
+            const payload = ticket.getPayload();
+            return payload?.email_verified === true && payload.email === addOnAgent;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+/** The synchronous answer to a click: a decided card becomes its outcome, any other click gets a reply. */
+function clickResponse(feedback, addOn) {
+    const message = feedback.counted ? { text: feedback.text, cardsV2: [] } : { text: feedback.text };
+    if (addOn) {
+        const action = feedback.counted ? "updateMessageAction" : "createMessageAction";
+        return { hostAppDataAction: { chatDataAction: { [action]: { message } } } };
+    }
+    return { actionResponse: { type: feedback.counted ? "UPDATE_MESSAGE" : "NEW_MESSAGE" }, ...message };
+}
+/**
+ * Listing messages needs chat.app.messages.readonly, which an admin must grant, so it has its own client and posting
+ * keeps working without it.
+ */
+export function googleChatApi(keyFile) {
+    const auth = (scope) => new GoogleAuth({ keyFile, scopes: [`https://www.googleapis.com/auth/${scope}`] });
+    const botAuth = auth("chat.bot");
+    const bot = chat({ version: "v1", auth: botAuth });
+    const reader = chat({ version: "v1", auth: auth("chat.app.messages.readonly") });
+    return {
+        create: async (parent, requestBody, threaded) => {
+            const { data } = await bot.spaces.messages.create({
+                parent,
+                requestBody,
+                ...(threaded ? { messageReplyOption: "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD" } : {}),
+            });
+            if (!data.name)
+                throw new Error("Google Chat returned no message name");
+            return data.name;
+        },
+        patch: async (name, requestBody, updateMask) => {
+            await bot.spaces.messages.patch({ name, updateMask, requestBody });
+        },
+        remove: async (name) => {
+            await bot.spaces.messages.delete({ name });
+        },
+        list: async (parent, filter) => (await reader.spaces.messages.list({ parent, filter, orderBy: "createTime asc", pageSize: 100 })).data.messages ??
+            [],
+        download: async (resourceName, signal) => {
+            const segments = resourceName.split("/");
+            if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+                throw new Error(`not an attachment resource name: ${resourceName}`);
+            }
+            const token = await botAuth.getAccessToken();
+            if (token === null || token === undefined)
+                throw new Error("Google gave no access token");
+            const path = segments.map(encodeURIComponent).join("/");
+            return fetchCapped(`https://chat.googleapis.com/v1/media/${path}?alt=media`, {
+                headers: { authorization: `Bearer ${token}` },
+                signal,
+            });
+        },
+    };
+}
+function approvalCard(prompt, endpointUrl) {
+    const button = (text, choice) => ({
+        text,
+        onClick: {
+            action: {
+                function: endpointUrl,
+                parameters: [
+                    { key: "approvalId", value: prompt.approvalId },
+                    { key: "decision", value: choice },
+                ],
+            },
+        },
+    });
+    return {
+        cardId: `approval-${prompt.approvalId}`,
+        card: {
+            header: { title: "Approval needed", subtitle: prompt.tool },
+            sections: [
+                {
+                    widgets: [
+                        { textParagraph: { text: escapeHtml(prompt.summary) } },
+                        { textParagraph: { text: escapeHtml(approvalArgs(prompt)) } },
+                        {
+                            textParagraph: {
+                                text: `Only ${escapeHtml(prompt.requester.name ?? prompt.requester.id)} can approve or deny.`,
+                            },
+                        },
+                        { buttonList: { buttons: [button("Approve", "approve"), button("Deny", "deny")] } },
+                    ],
+                },
+            ],
+        },
+    };
+}
+/** Google Chat as an HTTP endpoint app: Google posts events to `endpointUrl`; replies go out through the Chat API. */
+export class GoogleChatAdapter {
+    platform = "googlechat";
+    maxMessageLength = 4000;
+    #http;
+    #endpointUrl;
+    #api;
+    #verify;
+    #historyUnavailable = false;
+    constructor(http, endpointUrl, api, verify) {
+        this.#http = http;
+        this.#endpointUrl = endpointUrl;
+        this.#api = api;
+        this.#verify = verify;
+    }
+    async start(handlers) {
+        this.#http.post(new URL(this.#endpointUrl).pathname, async (c) => {
+            if (!(await this.#verify(c.req.header("authorization"))))
+                return c.json({ error: "unauthorized" }, 401);
+            const event = normalizeGoogleChatEvent(await c.req.json().catch(() => undefined));
+            switch (event.kind) {
+                case "message":
+                    void handlers.onMessage(event.message);
+                    return c.json({});
+                case "approval":
+                    return c.json(clickResponse(await handlers.onApproval(event.decision), event.addOn));
+                case "ignored":
+                    return c.json({});
+                default:
+                    throw new Error(`unknown Google Chat event ${JSON.stringify(event)}`);
+            }
+        });
+    }
+    async stop() { }
+    async post(thread, markdown) {
+        const threaded = thread.threadId !== DM_TOP_LEVEL;
+        const message = { text: toGoogleChat(markdown), ...(threaded ? { thread: { name: thread.threadId } } : {}) };
+        return messageRef(thread, await this.#api.create(thread.spaceId, message, threaded));
+    }
+    async update(ref, markdown) {
+        await this.#api.patch(ref.messageId, { text: toGoogleChat(markdown) }, "text");
+    }
+    async remove(ref) {
+        await this.#api.remove(ref.messageId);
+    }
+    async postApproval(thread, prompt) {
+        const threaded = thread.threadId !== DM_TOP_LEVEL;
+        const message = {
+            text: `Approval needed: ${prompt.summary}`,
+            cardsV2: [approvalCard(prompt, this.#endpointUrl)],
+            ...(threaded ? { thread: { name: thread.threadId } } : {}),
+        };
+        return messageRef(thread, await this.#api.create(thread.spaceId, message, threaded));
+    }
+    async resolveApprovalMessage(ref, prompt, outcome, by) {
+        await this.#api.patch(ref.messageId, { text: decisionText(prompt, outcome, by), cardsV2: [] }, "text,cardsV2");
+    }
+    async download(attachment, signal) {
+        if (attachment.source === "")
+            throw new Error("Google Drive files are not downloaded");
+        return this.#api.download(attachment.source, signal);
+    }
+    async fetchThread(thread, after) {
+        if (this.#historyUnavailable)
+            return [];
+        const filters = [
+            ...(thread.threadId === DM_TOP_LEVEL ? [] : [`thread.name = ${thread.threadId}`]),
+            ...(after === undefined ? [] : [`createTime > "${after}"`]),
+        ];
+        try {
+            const listed = await this.#api.list(thread.spaceId, filters.join(" AND "));
+            const space = { name: thread.spaceId, ...(thread.threadId === DM_TOP_LEVEL ? { type: "DM" } : {}) };
+            return listed.flatMap((item) => {
+                const message = Message.safeParse(item);
+                return message.success ? (normalizeGoogleChatMessage(message.data, space) ?? []) : [];
+            });
+        }
+        catch (error) {
+            this.#historyUnavailable = true;
+            console.error("[googlechat] cannot read thread history; continuing without it", error);
+            return [];
+        }
+    }
+}

package/dist/chat/http.d.ts

@@ -0,0 +1,9 @@
+import { Hono } from "hono";
+/** The one public port that Teams (`/api/messages`) and Google Chat (`/googlechat`) share. */
+export declare class HttpServer {
+    #private;
+    readonly app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    constructor();
+    start(port: number): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/chat/http.js

@@ -0,0 +1,21 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+/** The one public port that Teams (`/api/messages`) and Google Chat (`/googlechat`) share. */
+export class HttpServer {
+    app = new Hono();
+    #server;
+    constructor() {
+        this.app.get("/healthz", (c) => c.text("ok"));
+    }
+    async start(port) {
+        await new Promise((resolve) => {
+            this.#server = serve({ fetch: this.app.fetch, port }, () => resolve());
+        });
+    }
+    async stop() {
+        const server = this.#server;
+        if (server === undefined)
+            return;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+}

package/dist/chat/markdown.d.ts

@@ -0,0 +1,4 @@
+/** Model Markdown to Slack mrkdwn. */
+export declare function toSlack(markdown: string): string;
+/** Model Markdown to Google Chat text formatting, which uses the same markers as Slack without HTML escaping. */
+export declare function toGoogleChat(markdown: string): string;

package/dist/chat/markdown.js

@@ -0,0 +1,28 @@
+import { escapeHtml } from "../format.js";
+const BOLD = "\u0001";
+/** Code spans and fenced blocks pass through untouched; everything else goes through `transform`. */
+function outsideCode(markdown, transform) {
+    return markdown
+        .split(/(```[\s\S]*?```|`[^`\n]+`)/)
+        .map((part, index) => (index % 2 === 1 ? part : transform(part)))
+        .join("");
+}
+function convert(text, escape) {
+    const escaped = escape ? escapeHtml(text) : text;
+    return escaped
+        .replaceAll(/^#{1,6}[ \t]+(.+?)[ \t]*#*[ \t]*$/gm, `${BOLD}$1${BOLD}`)
+        .replaceAll(/\*\*(.+?)\*\*|__(.+?)__/g, (_match, star, underscore) => `${BOLD}${star ?? underscore}${BOLD}`)
+        .replaceAll(/(?<![*\w])\*(?![\s*])(.+?)(?<![\s*])\*(?![*\w])/g, "_$1_")
+        .replaceAll(/^([ \t]*)[-*+][ \t]+/gm, "$1• ")
+        .replaceAll(/~~(.+?)~~/g, "~$1~")
+        .replaceAll(/!?\[([^\]]+)\]\(([^)\s]+)\)/g, "<$2|$1>")
+        .replaceAll(BOLD, "*");
+}
+/** Model Markdown to Slack mrkdwn. */
+export function toSlack(markdown) {
+    return outsideCode(markdown, (text) => convert(text, true));
+}
+/** Model Markdown to Google Chat text formatting, which uses the same markers as Slack without HTML escaping. */
+export function toGoogleChat(markdown) {
+    return outsideCode(markdown, (text) => convert(text, false));
+}

package/dist/chat/slack.d.ts

@@ -0,0 +1,55 @@
+import { type AdapterHandlers, type ApprovalDecision, type ApprovalOutcome, type ApprovalPrompt, type Attachment, type ChatAdapter, type ChatUser, type InboundMessage, type MessageRef, type ThreadRef } from "./adapter.ts";
+/** The fields housecall reads from Slack message and app_mention events and from history results. */
+type SlackMessage = {
+    ts?: string | undefined;
+    thread_ts?: string | undefined;
+    user?: string | undefined;
+    bot_id?: string | undefined;
+    subtype?: string | undefined;
+    text?: string | undefined;
+    files?: readonly SlackFile[] | undefined;
+};
+/** The fields housecall reads from a Slack file object. */
+type SlackFile = {
+    name?: string | null | undefined;
+    title?: string | null | undefined;
+    mimetype?: string | undefined;
+    size?: number | undefined;
+    url_private_download?: string | undefined;
+};
+/** The fields housecall reads from a block_actions payload. */
+type SlackAction = {
+    user: {
+        id: string;
+    };
+    actions: {
+        action_id?: string;
+        value?: string;
+    }[];
+    channel?: {
+        id: string;
+    } | undefined;
+    message?: {
+        ts: string;
+        thread_ts?: string | undefined;
+    } | undefined;
+};
+export declare function normalizeSlackMessage(message: SlackMessage, channel: string, isDirect: boolean, botUserId: string): InboundMessage | undefined;
+export declare function normalizeSlackAction(action: SlackAction): ApprovalDecision | undefined;
+/** Slack over Socket Mode: no public URL. Every message gets its own thread; DMs need no mention. */
+export declare class SlackAdapter implements ChatAdapter {
+    #private;
+    readonly platform = "slack";
+    readonly maxMessageLength = 3900;
+    constructor(botToken: string, appToken: string);
+    start(handlers: AdapterHandlers): Promise<void>;
+    stop(): Promise<void>;
+    post(thread: ThreadRef, markdown: string): Promise<MessageRef>;
+    update(ref: MessageRef, markdown: string): Promise<void>;
+    remove(ref: MessageRef): Promise<void>;
+    postApproval(thread: ThreadRef, prompt: ApprovalPrompt): Promise<MessageRef>;
+    resolveApprovalMessage(ref: MessageRef, prompt: ApprovalPrompt, outcome: ApprovalOutcome, by?: ChatUser): Promise<void>;
+    download(attachment: Attachment, signal: AbortSignal): Promise<Uint8Array>;
+    fetchThread(thread: ThreadRef, after: string | undefined): Promise<InboundMessage[]>;
+}
+export {};

package/dist/chat/slack.js

@@ -0,0 +1,197 @@
+import { App, LogLevel } from "@slack/bolt";
+import { escapeHtml } from "../format.js";
+import { approvalArgs, decisionText, messageRef, } from "./adapter.js";
+import { fetchCapped } from "./download.js";
+import { toSlack } from "./markdown.js";
+const APPROVE = "housecall_approve";
+const DENY = "housecall_deny";
+const FILES_HOST = "files.slack.com";
+/** Slack Connect files without access and deleted files carry no download URL and are left out. */
+function slackAttachments(files) {
+    return files.flatMap((file) => {
+        const url = file.url_private_download;
+        if (url === undefined || !URL.canParse(url) || new URL(url).host !== FILES_HOST)
+            return [];
+        return [
+            {
+                name: file.name ?? file.title ?? "file",
+                mimeType: file.mimetype ?? "application/octet-stream",
+                ...(file.size === undefined ? {} : { size: file.size }),
+                source: url,
+            },
+        ];
+    });
+}
+function slackUser(id) {
+    return { id, name: `<@${id}>` };
+}
+export function normalizeSlackMessage(message, channel, isDirect, botUserId) {
+    const { ts, user } = message;
+    const human = message.subtype === undefined || message.subtype === "file_share" || message.subtype === "thread_broadcast";
+    if (!human || message.bot_id !== undefined || ts === undefined || user === undefined || user === botUserId) {
+        return undefined;
+    }
+    const raw = message.text ?? "";
+    const mention = `<@${botUserId}>`;
+    return {
+        platform: "slack",
+        spaceId: channel,
+        threadId: message.thread_ts ?? ts,
+        messageId: ts,
+        user: slackUser(user),
+        text: raw.replaceAll(mention, "").trim(),
+        attachments: slackAttachments(message.files ?? []),
+        isDirect,
+        mentionsBot: raw.includes(mention),
+        cursor: ts,
+    };
+}
+export function normalizeSlackAction(action) {
+    const clicked = action.actions[0];
+    if (clicked?.value === undefined)
+        return undefined;
+    const decision = clicked.action_id === APPROVE ? "approve" : clicked.action_id === DENY ? "deny" : undefined;
+    return decision === undefined ? undefined : { approvalId: clicked.value, decision, user: slackUser(action.user.id) };
+}
+function approvalBlocks(prompt) {
+    return [
+        { type: "section", text: { type: "mrkdwn", text: `*Approval needed:* ${escapeHtml(prompt.summary)}` } },
+        {
+            type: "context",
+            elements: [
+                { type: "mrkdwn", text: `\`${prompt.tool}\` ${escapeHtml(approvalArgs(prompt))}` },
+                { type: "mrkdwn", text: `Only <@${prompt.requester.id}> can approve or deny.` },
+            ],
+        },
+        {
+            type: "actions",
+            elements: [
+                {
+                    type: "button",
+                    action_id: APPROVE,
+                    style: "primary",
+                    text: { type: "plain_text", text: "Approve" },
+                    value: prompt.approvalId,
+                },
+                {
+                    type: "button",
+                    action_id: DENY,
+                    style: "danger",
+                    text: { type: "plain_text", text: "Deny" },
+                    value: prompt.approvalId,
+                },
+            ],
+        },
+    ];
+}
+const isDirectChannel = (channel) => channel.startsWith("D");
+/** Slack over Socket Mode: no public URL. Every message gets its own thread; DMs need no mention. */
+export class SlackAdapter {
+    platform = "slack";
+    maxMessageLength = 3900;
+    #app;
+    #botToken;
+    #botUserId = "";
+    constructor(botToken, appToken) {
+        this.#botToken = botToken;
+        this.#app = new App({
+            token: botToken,
+            appToken,
+            socketMode: true,
+            logLevel: LogLevel.WARN,
+            deferInitialization: true,
+        });
+    }
+    async start(handlers) {
+        await this.#app.init();
+        const auth = await this.#app.client.auth.test();
+        this.#botUserId = auth.user_id ?? "";
+        const handle = async (message) => {
+            if (message !== undefined)
+                await handlers.onMessage(message);
+        };
+        this.#app.event("app_mention", async ({ event }) => {
+            await handle(normalizeSlackMessage(event, event.channel, false, this.#botUserId));
+        });
+        this.#app.message(async ({ message }) => {
+            if (message.channel_type !== "im")
+                return;
+            await handle(normalizeSlackMessage(message, message.channel, true, this.#botUserId));
+        });
+        this.#app.action({ type: "block_actions" }, async ({ ack, body }) => {
+            await ack();
+            const action = body;
+            const decision = normalizeSlackAction(action);
+            if (decision === undefined)
+                return;
+            const feedback = await handlers.onApproval(decision);
+            if (feedback.counted || action.channel === undefined)
+                return;
+            const threadTs = action.message?.thread_ts ?? action.message?.ts;
+            await this.#app.client.chat.postEphemeral({
+                channel: action.channel.id,
+                user: decision.user.id,
+                text: feedback.text,
+                ...(threadTs === undefined ? {} : { thread_ts: threadTs }),
+            });
+        });
+        await this.#app.start();
+    }
+    async stop() {
+        await this.#app.stop();
+    }
+    async post(thread, markdown) {
+        const posted = await this.#app.client.chat.postMessage({
+            channel: thread.spaceId,
+            text: toSlack(markdown),
+            thread_ts: thread.threadId,
+        });
+        if (posted.ts === undefined)
+            throw new Error("Slack returned no ts for a posted message");
+        return messageRef(thread, posted.ts);
+    }
+    async update(ref, markdown) {
+        await this.#app.client.chat.update({ channel: ref.spaceId, ts: ref.messageId, text: toSlack(markdown) });
+    }
+    async remove(ref) {
+        await this.#app.client.chat.delete({ channel: ref.spaceId, ts: ref.messageId });
+    }
+    async postApproval(thread, prompt) {
+        const posted = await this.#app.client.chat.postMessage({
+            channel: thread.spaceId,
+            text: `Approval needed: ${prompt.summary}`,
+            blocks: approvalBlocks(prompt),
+            thread_ts: thread.threadId,
+        });
+        if (posted.ts === undefined)
+            throw new Error("Slack returned no ts for an approval prompt");
+        return messageRef(thread, posted.ts);
+    }
+    async resolveApprovalMessage(ref, prompt, outcome, by) {
+        const text = decisionText({ ...prompt, summary: escapeHtml(prompt.summary) }, outcome, by);
+        await this.#app.client.chat.update({
+            channel: ref.spaceId,
+            ts: ref.messageId,
+            text,
+            blocks: [{ type: "section", text: { type: "mrkdwn", text } }],
+        });
+    }
+    async download(attachment, signal) {
+        if (new URL(attachment.source).host !== FILES_HOST)
+            throw new Error(`not a Slack file URL: ${attachment.source}`);
+        return fetchCapped(attachment.source, { headers: { authorization: `Bearer ${this.#botToken}` }, signal });
+    }
+    async fetchThread(thread, after) {
+        const isDirect = isDirectChannel(thread.spaceId);
+        const page = await this.#app.client.conversations.replies({
+            channel: thread.spaceId,
+            ts: thread.threadId,
+            limit: 200,
+            ...(after === undefined ? {} : { oldest: after }),
+        });
+        return (page.messages ?? [])
+            .flatMap((message) => normalizeSlackMessage(message, thread.spaceId, isDirect, this.#botUserId) ?? [])
+            .filter((message) => after === undefined || message.cursor > after)
+            .sort((a, b) => a.cursor.localeCompare(b.cursor));
+    }
+}