@astrofoundry/pi-astro 0.21.2 → 0.22.0

package/extensions/astro-discord/gateway.ts

@@ -0,0 +1,212 @@
+/** GUILDS | GUILD_MESSAGES | MESSAGE_CONTENT (privileged, enabled in the developer portal). */
+export const INTENTS = (1 << 0) | (1 << 9) | (1 << 15);
+
+export interface GatewayPayload {
+    op: number;
+    d?: unknown;
+    s?: number | null;
+    t?: string | null;
+}
+
+export interface GatewayState {
+    sessionId: string | null;
+    resumeUrl: string | null;
+    seq: number | null;
+    heartbeatMs: number | null;
+    /** True until the heartbeat ACK arrives; two misses mean the socket is dead. */
+    awaitingAck: boolean;
+}
+
+export interface GatewayHandlers {
+    dispatch: (event: string, data: unknown) => void;
+    log: (line: string) => void;
+}
+
+export function initialState(): GatewayState {
+    return { sessionId: null, resumeUrl: null, seq: null, heartbeatMs: null, awaitingAck: false };
+}
+
+export type GatewayAction =
+    | { kind: "identify" }
+    | { kind: "resume" }
+    | { kind: "heartbeat"; interval: number }
+    | { kind: "heartbeat-now" }
+    | { kind: "reconnect"; resume: boolean }
+    | { kind: "none" };
+
+/**
+ * Pure reducer over gateway payloads: updates the session state and names
+ * the action the connection should take. Keeps the socket handling small.
+ */
+export function reduce(state: GatewayState, payload: GatewayPayload, handlers: GatewayHandlers): GatewayAction {
+    if (typeof payload.s === "number") state.seq = payload.s;
+    switch (payload.op) {
+        case 10: {
+            const hello = payload.d as { heartbeat_interval?: number };
+            state.heartbeatMs = typeof hello.heartbeat_interval === "number" ? hello.heartbeat_interval : 41_250;
+            return state.sessionId ? { kind: "resume" } : { kind: "identify" };
+        }
+        case 11:
+            state.awaitingAck = false;
+            return { kind: "none" };
+        case 1:
+            return { kind: "heartbeat-now" };
+        case 7:
+            return { kind: "reconnect", resume: true };
+        case 9:
+            return { kind: "reconnect", resume: payload.d === true };
+        case 0: {
+            if (payload.t === "READY") {
+                const ready = payload.d as { session_id?: string; resume_gateway_url?: string };
+                state.sessionId = ready.session_id ?? null;
+                state.resumeUrl = ready.resume_gateway_url ?? null;
+                handlers.log("gateway ready");
+            } else if (payload.t === "RESUMED") {
+                handlers.log("gateway resumed");
+            }
+            if (payload.t) handlers.dispatch(payload.t, payload.d);
+            return { kind: "none" };
+        }
+        default:
+            return { kind: "none" };
+    }
+}
+
+/** Close codes after which Discord says not to reconnect. */
+export const FATAL_CLOSE_CODES = new Set([4004, 4010, 4011, 4012, 4013, 4014]);
+
+export interface GatewayClientOptions {
+    token: string;
+    gatewayUrl: string;
+    handlers: GatewayHandlers;
+    intents?: number;
+    /** WebSocket constructor, injectable for tests. */
+    socketFactory?: (url: string) => WebSocket;
+}
+
+/**
+ * One gateway connection with heartbeat, identify, resume, and reconnect
+ * with backoff. `start()` returns once the first connection is attempted;
+ * `stop()` closes for good.
+ */
+export class GatewayClient {
+    private readonly state = initialState();
+    private socket: WebSocket | null = null;
+    private heartbeat: ReturnType<typeof setInterval> | null = null;
+    private stopped = false;
+    private attempts = 0;
+
+    constructor(private readonly options: GatewayClientOptions) {}
+
+    start(): void {
+        this.stopped = false;
+        this.connect(false);
+    }
+
+    stop(): void {
+        this.stopped = true;
+        this.clearHeartbeat();
+        this.socket?.close(1000);
+        this.socket = null;
+    }
+
+    private url(resume: boolean): string {
+        const base = resume && this.state.resumeUrl ? this.state.resumeUrl : this.options.gatewayUrl;
+        return `${base}${base.includes("?") ? "&" : "?"}v=10&encoding=json`;
+    }
+
+    private send(payload: GatewayPayload): void {
+        if (this.socket && this.socket.readyState === WebSocket.OPEN) this.socket.send(JSON.stringify(payload));
+    }
+
+    private clearHeartbeat(): void {
+        if (this.heartbeat) clearInterval(this.heartbeat);
+        this.heartbeat = null;
+    }
+
+    private connect(resume: boolean): void {
+        if (this.stopped) return;
+        if (!resume) {
+            this.state.sessionId = null;
+            this.state.seq = null;
+        }
+        const factory = this.options.socketFactory ?? ((url: string) => new WebSocket(url));
+        const socket = factory(this.url(resume));
+        this.socket = socket;
+        socket.addEventListener("message", (event: MessageEvent) => {
+            let payload: GatewayPayload;
+            try {
+                payload = JSON.parse(String(event.data)) as GatewayPayload;
+            } catch {
+                return;
+            }
+            this.act(reduce(this.state, payload, this.options.handlers));
+        });
+        socket.addEventListener("close", (event: CloseEvent) => {
+            this.clearHeartbeat();
+            if (this.stopped) return;
+            if (FATAL_CLOSE_CODES.has(event.code)) {
+                this.options.handlers.log(`gateway closed with fatal code ${event.code}: ${event.reason}; not reconnecting`);
+                this.stopped = true;
+                return;
+            }
+            this.options.handlers.log(`gateway closed (${event.code}); reconnecting`);
+            this.scheduleReconnect(true);
+        });
+        socket.addEventListener("error", () => {
+            this.options.handlers.log("gateway socket error");
+        });
+    }
+
+    private scheduleReconnect(resume: boolean): void {
+        if (this.stopped) return;
+        this.attempts++;
+        const delay = Math.min(60_000, 1000 * 2 ** Math.min(this.attempts, 6));
+        setTimeout(() => this.connect(resume && this.state.sessionId !== null), delay).unref();
+    }
+
+    private act(action: GatewayAction): void {
+        switch (action.kind) {
+            case "identify":
+                this.attempts = 0;
+                this.startHeartbeat();
+                this.send({
+                    op: 2,
+                    d: { token: this.options.token, intents: this.options.intents ?? INTENTS, properties: { os: process.platform, browser: "astro-discord", device: "astro-discord" } },
+                });
+                break;
+            case "resume":
+                this.attempts = 0;
+                this.startHeartbeat();
+                this.send({ op: 6, d: { token: this.options.token, session_id: this.state.sessionId, seq: this.state.seq } });
+                break;
+            case "heartbeat-now":
+                this.send({ op: 1, d: this.state.seq });
+                break;
+            case "reconnect":
+                this.clearHeartbeat();
+                this.socket?.close(4000);
+                if (!action.resume) this.state.sessionId = null;
+                this.scheduleReconnect(action.resume);
+                break;
+            default:
+                break;
+        }
+    }
+
+    private startHeartbeat(): void {
+        this.clearHeartbeat();
+        const interval = this.state.heartbeatMs ?? 41_250;
+        this.state.awaitingAck = false;
+        this.heartbeat = setInterval(() => {
+            if (this.state.awaitingAck) {
+                this.options.handlers.log("heartbeat not acknowledged; reconnecting");
+                this.act({ kind: "reconnect", resume: true });
+                return;
+            }
+            this.state.awaitingAck = true;
+            this.send({ op: 1, d: this.state.seq });
+        }, interval);
+        this.heartbeat.unref();
+    }
+}

package/extensions/astro-discord/index.ts

@@ -0,0 +1,275 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig as loadSpecialists } from "../specialist-gate/config.ts";
+import { APPROVAL_TOKEN_ENV, APPROVAL_URL_ENV } from "../specialist-gate/index.ts";
+import { type AgentConfig, defaultDirs, discoverAgents, resolveSkills } from "../astro-subagents/agents.ts";
+import { type DispatchDefaults, childRemaining, currentDepth, isFailed, resultOutput, runAgent } from "../astro-subagents/child.ts";
+import { ApprovalServer, type Ticket } from "./approvals.ts";
+import { chunkMessage } from "./chunk.ts";
+import { CHANNEL_RULES, helpText, parseCommand } from "./commands.ts";
+import { ACTIVATION_ENV, type DiscordConfig, allowedSpecialists, canUse, isOwner, loadConfig, loadToken } from "./config.ts";
+import { GatewayClient } from "./gateway.ts";
+import { DiscordRest, type MessageComponent } from "./rest.ts";
+
+const REACTION = { running: "⏳", waiting: "🔒", done: "✅", failed: "❌" } as const;
+/** Answers longer than this go as a file attachment with a short summary. */
+const ATTACHMENT_THRESHOLD = 6000;
+
+interface IncomingMessage {
+    id: string;
+    channel_id: string;
+    guild_id?: string;
+    content?: string;
+    author?: { id: string; bot?: boolean };
+}
+
+interface ComponentInteraction {
+    id: string;
+    token: string;
+    type: number;
+    channel_id?: string;
+    message?: { id: string };
+    data?: { custom_id?: string; component_type?: number };
+    member?: { user?: { id: string } };
+    user?: { id: string };
+}
+
+interface ActiveTask {
+    specialist: string;
+    channelId: string;
+    messageId: string;
+    userId: string;
+    startedAt: number;
+}
+
+function log(line: string): void {
+    process.stderr.write(`[astro-discord ${new Date().toISOString()}] ${line}\n`);
+}
+
+function approvalButtons(ticketId: string, disabled = false): MessageComponent[] {
+    return [
+        {
+            type: 1,
+            components: [
+                { type: 2, style: 3, label: "Approve", custom_id: `apr:${ticketId}:approve`, disabled },
+                { type: 2, style: 4, label: "Deny", custom_id: `apr:${ticketId}:deny`, disabled },
+            ],
+        },
+    ];
+}
+
+function code(text: string): string {
+    return `\`${text.replace(/`/g, "'")}\``;
+}
+
+/** Bridge state for one headless Pi host connected to Discord. */
+class Bridge {
+    private readonly rest: DiscordRest;
+    private readonly approvals: ApprovalServer;
+    private readonly queues = new Map<string, Promise<void>>();
+    private readonly active = new Map<string, ActiveTask>();
+    private readonly approvalMessages = new Map<string, { channelId: string; messageId: string; userMessage: ActiveTask }>();
+    private config: DiscordConfig;
+    private botUserId = "";
+
+    constructor(
+        private readonly ctx: ExtensionContext,
+        config: DiscordConfig,
+        private readonly token: string,
+    ) {
+        this.config = config;
+        this.rest = new DiscordRest(token);
+        this.approvals = new ApprovalServer({ onTicket: (t) => void this.askApproval(t), onExpired: (t) => void this.expireApproval(t) }, config.approvalTimeoutMinutes * 60_000);
+    }
+
+    /** Specialists configured for this host, as short names. */
+    private specialists(): { names: string[]; agents: AgentConfig[] } {
+        const gate = loadSpecialists().config;
+        const agents = discoverAgents(process.cwd(), "user", defaultDirs()).agents;
+        const names = (gate?.specialists ?? []).map((s) => s.agent.replace(/^astro\./, "")).filter((short) => agents.some((a) => a.name === `astro.${short}`));
+        return { names, agents };
+    }
+
+    private refreshConfig(): void {
+        const loaded = loadConfig();
+        if (loaded.config) this.config = loaded.config;
+        else log(`config not reloaded: ${loaded.errors.join("; ")}`);
+    }
+
+    async start(): Promise<void> {
+        const me = await this.rest.currentUser();
+        this.botUserId = me.id;
+        await this.approvals.listen();
+        const gateway = new GatewayClient({
+            token: this.token,
+            gatewayUrl: await this.rest.gatewayUrl(),
+            handlers: {
+                dispatch: (event, data) => void this.dispatch(event, data),
+                log,
+            },
+        });
+        gateway.start();
+        log(`connected as ${me.username} (${me.id}); channels ${this.config.channelIds.join(", ")}; specialists ${this.specialists().names.join(", ")}`);
+    }
+
+    private async dispatch(event: string, data: unknown): Promise<void> {
+        try {
+            if (event === "MESSAGE_CREATE") await this.onMessage(data as IncomingMessage);
+            else if (event === "INTERACTION_CREATE") await this.onInteraction(data as ComponentInteraction);
+        } catch (err) {
+            log(`${event} failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+
+    private async onMessage(message: IncomingMessage): Promise<void> {
+        if (!message.author || message.author.bot || !this.config.channelIds.includes(message.channel_id)) return;
+        this.refreshConfig();
+        const { names, agents } = this.specialists();
+        const command = parseCommand(message.content ?? "", this.botUserId, names);
+        if (command.kind === "none") return;
+        const userId = message.author.id;
+        const allowed = allowedSpecialists(this.config, userId, names);
+        if (allowed.length === 0) return;
+        if (command.kind === "help") {
+            await this.rest.createMessage(message.channel_id, { content: helpText(allowed, isOwner(this.config, userId)), replyTo: message.id });
+            return;
+        }
+        if (command.kind === "status") {
+            const lines = [...this.active.values()].map((t) => `• ${t.specialist} for <@${t.userId}>, running ${Math.round((Date.now() - t.startedAt) / 1000)} s`);
+            await this.rest.createMessage(message.channel_id, { content: lines.length > 0 ? lines.join("\n") : "Nothing is running.", replyTo: message.id });
+            return;
+        }
+        if (!canUse(this.config, userId, command.specialist)) return;
+        const agent = agents.find((a) => a.name === `astro.${command.specialist}`);
+        if (!agent) return;
+        const task: ActiveTask = { specialist: command.specialist, channelId: message.channel_id, messageId: message.id, userId, startedAt: Date.now() };
+        const previous = this.queues.get(command.specialist) ?? Promise.resolve();
+        const next = previous.then(() => this.runTask(agent, command.task, task)).catch((err) => log(`run failed: ${err instanceof Error ? err.message : String(err)}`));
+        this.queues.set(command.specialist, next);
+    }
+
+    private async runTask(agent: AgentConfig, taskText: string, task: ActiveTask): Promise<void> {
+        task.startedAt = Date.now();
+        this.active.set(task.specialist, task);
+        await this.rest.addReaction(task.channelId, task.messageId, REACTION.running);
+        log(`run astro.${task.specialist} for ${task.userId}: ${taskText.slice(0, 200)}`);
+        const dirs = defaultDirs();
+        const { skills, missing } = resolveSkills(agent.skills, dirs);
+        if (missing.length > 0) log(`${agent.name}: skill(s) not found: ${missing.join(", ")}`);
+        const defaults: DispatchDefaults = {
+            model: this.ctx.model ? `${this.ctx.model.provider}/${this.ctx.model.id}` : undefined,
+            thinkingLevel: this.ctx.thinkingLevel,
+        };
+        const { depth, remaining } = currentDepth();
+        let failed = true;
+        let output: string;
+        try {
+            const result = await runAgent({
+                agent,
+                skills,
+                task: taskText,
+                cwd: process.cwd(),
+                depth,
+                remaining: childRemaining(remaining, agent),
+                defaults,
+                env: { [APPROVAL_URL_ENV]: this.approvals.url, [APPROVAL_TOKEN_ENV]: this.approvals.token, ASTRO_CHANNEL: "discord" },
+                extraSystemPrompt: CHANNEL_RULES,
+            });
+            failed = isFailed(result);
+            output = resultOutput(result);
+            log(`astro.${task.specialist} ${failed ? "failed" : "done"} in ${Math.round((Date.now() - task.startedAt) / 1000)} s, ${result.usage.turns} turns, cost ${result.usage.cost.toFixed(4)}`);
+        } catch (err) {
+            output = err instanceof Error ? err.message : String(err);
+        } finally {
+            this.active.delete(task.specialist);
+        }
+        await this.rest.removeOwnReaction(task.channelId, task.messageId, REACTION.running).catch(() => undefined);
+        await this.rest.addReaction(task.channelId, task.messageId, failed ? REACTION.failed : REACTION.done).catch(() => undefined);
+        await this.post(task, `${failed ? "❌" : "✅"} **${task.specialist}**\n${output}`);
+    }
+
+    private async post(task: ActiveTask, text: string): Promise<void> {
+        if (text.length > ATTACHMENT_THRESHOLD) {
+            const summary = `${text.slice(0, 1200).trim()}\n… full answer attached (${text.length} characters).`;
+            await this.rest.createMessage(task.channelId, { content: summary, replyTo: task.messageId, file: { name: `astro-${task.specialist}-${Date.now()}.md`, content: text } });
+            return;
+        }
+        const chunks = chunkMessage(text);
+        for (let i = 0; i < chunks.length; i++) {
+            await this.rest.createMessage(task.channelId, { content: chunks[i], replyTo: i === 0 ? task.messageId : undefined });
+        }
+    }
+
+    private async askApproval(ticket: Ticket): Promise<void> {
+        const short = ticket.agent.replace(/^astro\./, "");
+        const task = this.active.get(short);
+        if (!task) {
+            log(`approval ${ticket.id} for ${ticket.agent} has no active task; denying`);
+            this.approvals.decide(ticket.id, "deny", "bridge");
+            return;
+        }
+        await this.rest.addReaction(task.channelId, task.messageId, REACTION.waiting).catch(() => undefined);
+        const owners = this.config.owners.map((id) => `<@${id}>`).join(" ");
+        const content = `🔒 **${short}** wants to run ${code(ticket.args.join(" "))} for <@${task.userId}>. ${owners}: approve or deny within ${this.config.approvalTimeoutMinutes} min.`;
+        const posted = await this.rest.createMessage(task.channelId, { content, replyTo: task.messageId, components: approvalButtons(ticket.id) });
+        this.approvalMessages.set(ticket.id, { channelId: posted.channel_id, messageId: posted.id, userMessage: task });
+    }
+
+    private async expireApproval(ticket: Ticket): Promise<void> {
+        const posted = this.approvalMessages.get(ticket.id);
+        if (!posted) return;
+        this.approvalMessages.delete(ticket.id);
+        await this.rest.editMessage(posted.channelId, posted.messageId, `⌛ No decision within ${this.config.approvalTimeoutMinutes} min; ${code(ticket.args.join(" "))} was not run.`).catch(() => undefined);
+        await this.rest.removeOwnReaction(posted.userMessage.channelId, posted.userMessage.messageId, REACTION.waiting).catch(() => undefined);
+    }
+
+    private async onInteraction(interaction: ComponentInteraction): Promise<void> {
+        if (interaction.type !== 3) return;
+        const match = /^apr:([0-9a-f-]{36}):(approve|deny)$/.exec(interaction.data?.custom_id ?? "");
+        if (!match) return;
+        const userId = interaction.member?.user?.id ?? interaction.user?.id ?? "";
+        this.refreshConfig();
+        if (!isOwner(this.config, userId)) {
+            await this.rest.ephemeralReply(interaction.id, interaction.token, "Only owners decide approvals.");
+            return;
+        }
+        const decision = match[2] as "approve" | "deny";
+        const ticket = this.approvals.decide(match[1], decision, userId);
+        if (!ticket) {
+            await this.rest.ephemeralReply(interaction.id, interaction.token, "This request was already decided or has expired.");
+            return;
+        }
+        const posted = this.approvalMessages.get(ticket.id);
+        this.approvalMessages.delete(ticket.id);
+        const verdict = decision === "approve" ? `✅ Approved by <@${userId}>` : `⛔ Denied by <@${userId}>`;
+        await this.rest.updateInteractionMessage(interaction.id, interaction.token, `${verdict}: ${code(ticket.args.join(" "))}`);
+        if (posted) await this.rest.removeOwnReaction(posted.userMessage.channelId, posted.userMessage.messageId, REACTION.waiting).catch(() => undefined);
+        log(`approval ${ticket.id} ${decision} by ${userId}: ${ticket.args.join(" ")}`);
+    }
+}
+
+/**
+ * Discord bridge to the specialists. Inert unless ASTRO_DISCORD=1, which only
+ * the headless LaunchAgent host sets; interactive sessions never connect.
+ */
+export default function astroDiscord(pi: ExtensionAPI): void {
+    if (process.env[ACTIVATION_ENV] !== "1") return;
+    pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+        const loaded = loadConfig();
+        if (!loaded.config) {
+            for (const error of loaded.errors) log(`config error: ${error}`);
+            return;
+        }
+        let token: string;
+        try {
+            token = loadToken();
+        } catch (err) {
+            log(`token error: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        try {
+            await new Bridge(ctx, loaded.config, token).start();
+        } catch (err) {
+            log(`start failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/extensions/astro-discord/rest.ts

@@ -0,0 +1,102 @@
+export const API = "https://discord.com/api/v10";
+
+export interface MessageComponent {
+    type: number;
+    components?: MessageComponent[];
+    style?: number;
+    label?: string;
+    custom_id?: string;
+    disabled?: boolean;
+}
+
+export interface CreateMessage {
+    content: string;
+    replyTo?: string;
+    components?: MessageComponent[];
+    /** One optional text attachment. */
+    file?: { name: string; content: string };
+}
+
+export interface DiscordMessage {
+    id: string;
+    channel_id: string;
+}
+
+interface RateLimit {
+    retry_after?: number;
+}
+
+/**
+ * Minimal Discord REST client on `fetch`. Every call retries once after a
+ * 429 using the returned `retry_after`; anything else non-2xx throws.
+ */
+export class DiscordRest {
+    constructor(
+        private readonly token: string,
+        private readonly fetchImpl: typeof fetch = fetch,
+        private readonly base = API,
+    ) {}
+
+    private async call(method: string, path: string, body?: BodyInit, contentType?: string, attempt = 0): Promise<Response> {
+        const headers: Record<string, string> = { Authorization: `Bot ${this.token}`, "User-Agent": "DiscordBot (https://github.com/astrofoundry/pi-astro, astro-discord)" };
+        if (contentType) headers["Content-Type"] = contentType;
+        const response = await this.fetchImpl(`${this.base}${path}`, { method, headers, body });
+        if (response.status === 429 && attempt === 0) {
+            const limit = (await response.json().catch(() => ({}))) as RateLimit;
+            await new Promise((resolve) => setTimeout(resolve, Math.ceil((limit.retry_after ?? 1) * 1000)));
+            return this.call(method, path, body, contentType, 1);
+        }
+        if (!response.ok) throw new Error(`Discord ${method} ${path} answered ${response.status}: ${(await response.text()).slice(0, 300)}`);
+        return response;
+    }
+
+    async createMessage(channelId: string, message: CreateMessage): Promise<DiscordMessage> {
+        const payload: Record<string, unknown> = { content: message.content, allowed_mentions: { parse: [] } };
+        if (message.replyTo) payload.message_reference = { message_id: message.replyTo, fail_if_not_exists: false };
+        if (message.components) payload.components = message.components;
+        if (message.file) {
+            const form = new FormData();
+            payload.attachments = [{ id: 0, filename: message.file.name }];
+            form.append("payload_json", JSON.stringify(payload));
+            form.append("files[0]", new Blob([message.file.content], { type: "text/plain" }), message.file.name);
+            return (await this.call("POST", `/channels/${channelId}/messages`, form)).json() as Promise<DiscordMessage>;
+        }
+        return (await this.call("POST", `/channels/${channelId}/messages`, JSON.stringify(payload), "application/json")).json() as Promise<DiscordMessage>;
+    }
+
+    async editMessage(channelId: string, messageId: string, content: string, components: MessageComponent[] = []): Promise<void> {
+        await this.call("PATCH", `/channels/${channelId}/messages/${messageId}`, JSON.stringify({ content, components, allowed_mentions: { parse: [] } }), "application/json");
+    }
+
+    async addReaction(channelId: string, messageId: string, emoji: string): Promise<void> {
+        await this.call("PUT", `/channels/${channelId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/@me`);
+    }
+
+    async removeOwnReaction(channelId: string, messageId: string, emoji: string): Promise<void> {
+        await this.call("DELETE", `/channels/${channelId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/@me`);
+    }
+
+    /** Answers a component interaction by editing the message it came from (callback type 7). */
+    async updateInteractionMessage(interactionId: string, interactionToken: string, content: string, components: MessageComponent[] = []): Promise<void> {
+        await this.call("POST", `/interactions/${interactionId}/${interactionToken}/callback`, JSON.stringify({ type: 7, data: { content, components, allowed_mentions: { parse: [] } } }), "application/json");
+    }
+
+    /** Ephemeral reply to an interaction (callback type 4 with the EPHEMERAL flag). */
+    async ephemeralReply(interactionId: string, interactionToken: string, content: string): Promise<void> {
+        await this.call("POST", `/interactions/${interactionId}/${interactionToken}/callback`, JSON.stringify({ type: 4, data: { content, flags: 64, allowed_mentions: { parse: [] } } }), "application/json");
+    }
+
+    async gatewayUrl(): Promise<string> {
+        const data = (await (await this.call("GET", "/gateway/bot")).json()) as { url?: string };
+        if (typeof data.url !== "string") throw new Error("Discord did not return a gateway url");
+        return data.url;
+    }
+
+    async currentUser(): Promise<{ id: string; username: string }> {
+        return (await this.call("GET", "/users/@me")).json() as Promise<{ id: string; username: string }>;
+    }
+
+    async channel(channelId: string): Promise<{ id: string; name?: string; guild_id?: string; type: number }> {
+        return (await this.call("GET", `/channels/${channelId}`)).json() as Promise<{ id: string; name?: string; guild_id?: string; type: number }>;
+    }
+}