@loomcycle/bridge-discord 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @loomcycle/bridge-discord
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Discord bot for a [loomcycle](https://github.com/denn-gubsky/loomcycle) interactive agent. People talk to the agent with slash commands. In a DM each person is their own loomcycle user, with their own runs, memory, history, budget and rate limit; a server channel is a loomcycle user of its own.
+
+- **Slash commands:** `/ask prompt:<text>` talks to the agent, `/new` starts over, `/stop` stops the current answer, `/help` lists them.
+- **Steering:** an `/ask` sent while the agent is working reaches it mid-turn.
+- **Questions and reviews** from the agent arrive as messages with buttons.
+- **Restarts lose nothing:** the next `/ask` continues the conversation, with the agent's full history.
+
+It is built on `@loomcycle/bridge-core`, which holds the per-user tokens, conversations and cards every bridge shares. Design: RFC EQ (Bridges) in the loomcycle document store.
+
+## What v1 does not do
+
+The bridge takes Discord **interactions over HTTP** only. It does not connect to the Gateway, so it never sees ordinary messages: people use `/ask`, in a server or in a DM. Free-text messages need the Gateway and are a later phase.
+
+## How it works
+
+```
+Discord ──HTTPS POST /discord/interactions──▶ bridge-discord ──private network──▶ loomcycle
+        ◀──── interaction webhooks, REST ─────┘
+```
+
+- **Only the bridge is public.** loomcycle stays on your private network.
+- **Every command is answered within Discord's 3 seconds** with a deferred response ("thinking…"). The agent's reply replaces it. A long reply continues in follow-up messages, 2,000 characters each.
+- **Replies travel back through the interaction.** Its token lasts 15 minutes. A turn that ends later is posted with the bot token as an ordinary channel message, which needs the bot in that channel.
+- **One interactive run per conversation:** per DM, and per server channel or thread.
+
+## Setup
+
+### 1. loomcycle
+
+Run loomcycle with authentication on and a persistent store. Then:
+
+1. Pick or define the agent the bot runs, for example the `chat` agent from `LOOMCYCLE_PRESETS=base,chat`.
+2. Mint the bridge's token, a tenant operator in the tenant the Discord users will live in:
+
+   ```bash
+   loomcycle operator-token create --name discord-bridge --tenant acme --subject discord-bridge --scopes substrate:tenant
+   ```
+
+   Or declare it in YAML as a principal (`principals:` with `scopes: [substrate:tenant]` and a `token_env`).
+
+### 2. The Discord application
+
+1. In the [Developer Portal](https://discord.com/developers/applications), create an application.
+2. **General Information:** copy the **Application ID** (`DISCORD_APPLICATION_ID`) and the **Public Key** (`DISCORD_PUBLIC_KEY`).
+3. **Bot:** reset and copy the token (`DISCORD_BOT_TOKEN`). The bot needs no privileged intents.
+4. **Installation:** keep **Guild Install** only. For the install link, add the scopes `bot` and `applications.commands`, and the bot permissions *Send Messages* and *View Channels*. Install it in your server.
+5. Start the bridge (below), then set **Interactions Endpoint URL** to `https://<bridge-host>/discord/interactions`. Discord checks the URL with a PING when you save it, so the bridge must be running and reachable; it also probes the endpoint with bad signatures from time to time.
+
+### 3. Run the bridge
+
+```bash
+npx @loomcycle/bridge-discord
+```
+
+With `DISCORD_BRIDGE_REGISTER_COMMANDS=1` the bridge registers its four commands when it starts:
+
+- **in each allowed server, as that server's commands.** They take effect at once and show only where the bot answers.
+- **globally, limited to the bot's DMs,** when DMs are on. Commands in DMs can only be global, and limiting them to DMs keeps a server from listing them twice.
+
+Registration replaces the application's commands in those places. The bridge owns its application's commands; use a separate application for anything else. It does not remove global commands when you turn DMs off later.
+
+### Configuration
+
+The shared settings, as every bridge reads them:
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `LOOMCYCLE_BASE_URL` | loomcycle's private URL | required |
+| `LOOMCYCLE_TOKEN` | The bridge's `substrate:tenant` token | required |
+| `BRIDGE_AGENT` | The loomcycle agent every conversation runs | required |
+| `BRIDGE_TOKEN_TTL_SECONDS` | Lifetime of a user's token | `43200` |
+| `BRIDGE_RATE_PER_MINUTE`, `BRIDGE_RATE_BURST` | Runs a user may start per minute, and the burst | `6`, `10` |
+| `BRIDGE_USER_ACCESS_MODE` | `isolated` (a user sees only their own data) or `tenant` | `isolated` |
+| `BRIDGE_IDLE_MINUTES` | End a conversation's run after this long without a message; the next message continues it | `1440` |
+| `BRIDGE_STORE` | `memory`, or `file:<path>` to survive restarts on one instance | `memory` |
+| `BRIDGE_DEV` | `1` turns signature verification off, for local testing only | unset |
+| `PORT` | Listen port | `8080` |
+
+Discord's:
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `DISCORD_APPLICATION_ID` | The application's id | required |
+| `DISCORD_PUBLIC_KEY` | The application's public key (64 hex characters) | required |
+| `DISCORD_BOT_TOKEN` | The bot's token | required |
+| `DISCORD_BRIDGE_ALLOWED_GUILDS` | Comma list of server ids the bot answers in | none |
+| `DISCORD_BRIDGE_ALLOW_DMS` | `1` lets anyone who can reach the bot use it in a DM | off |
+| `DISCORD_BRIDGE_TRUSTED_GUILDS` | Allowed servers whose members are trusted (see below) | none |
+| `DISCORD_BRIDGE_REGISTER_COMMANDS` | `1` registers the commands at start | off |
+| `DISCORD_BRIDGE_API_BASE_URL` | Discord's REST API (`https`, or `http` to localhost for a test fake) | `https://discord.com/api/v10` |
+
+**The bridge is closed by default.** It refuses to start unless `DISCORD_BRIDGE_ALLOWED_GUILDS` or `DISCORD_BRIDGE_ALLOW_DMS=1` opens something: anyone on the internet can reach a Discord bot, and every message it answers runs on your model keys. `DISCORD_BRIDGE_ALLOW_DMS=1` means exactly that, so pair it with the rate limit and loomcycle's token budgets.
+
+## Servers, channels and trust
+
+- **A server channel runs as itself, never as one of its members.** It is its own loomcycle user (`discord-conv-<hash>`), with its own memory and history. A thread is its own conversation and shares its parent channel's memory.
+- Every message reaches the agent labelled with the speaker's name.
+- The person who started the conversation answers the agent's question and review cards, and only they can `/new` or `/stop`.
+- **Trust.** A DM is trusted. In a server, what members write is **untrusted** unless the server is in `DISCORD_BRIDGE_TRUSTED_GUILDS`. The agent reads untrusted text as data, never as instructions, and it never reaches memory. An untrusted member can pick one of the agent's options, decline, approve or send back, but cannot type an answer to a question.
+- A server not on the list, a DM when DMs are off, and a group DM each get a private reply saying the bot isn't available there, and never reach loomcycle.
+
+## Questions and reviews
+
+- A question with options shows one button per option (up to six) and **Decline**.
+- A question without options asks to be answered with `/ask <your answer>`: a Discord message has no text field. The conversation owner's next `/ask` is taken as the answer.
+- A review shows **Approve** and **Send back**. To send it back with notes, press **Send back**, then `/ask` the notes. A feedback form on **Send back** is planned for v1.1.
+- A pressed card is replaced by its result, so it cannot be answered twice. A card from before a restart says it is no longer open.
+
+## Limits
+
+- **2,000 characters a message.** A longer answer arrives as several.
+- **A turn longer than 15 minutes** finishes with the bot token. In a DM, or in a channel the bot cannot post in, that last message can be lost: the bridge logs the refusal. Another `/ask` gives the bridge a fresh interaction to reply through.
+- **No streaming.** Without the Gateway there is no live message to grow; each turn arrives when it ends, with Discord's "thinking…" until then.
+- A `/stop` sent while the agent waits for its next message has nothing to stop; its reply settles after ten seconds.
+
+## Security
+
+- **Inbound:** every request's `X-Signature-Ed25519` is checked over the timestamp and the raw body with the application's public key, before the body is parsed. A timestamp more than five minutes off, and an interaction id already seen, are refused. A failed check is a bare `401`.
+- **Bots are dropped,** the bot itself included, before anything reaches loomcycle.
+- **Least privilege:** the bridge's own token never runs agents. A user's token is limited to one agent, every per-run override except `interactive` is locked, it is rate-limited, and it expires.
+- **Credentials stay in memory.** Interaction tokens are never written to the conversation store, so `BRIDGE_STORE=file:` holds no credential; after a restart, replies use the bot token until the next command. The bot token is sent only to Discord's REST API, never to an interaction webhook. Logs carry ids, never a token, message text or agent output.
+- **Output:** agent text can be steered by whoever writes in a channel, so nothing the bridge posts can ping anyone (`allowed_mentions` parses nothing, so `@everyone` and role mentions are inert), shows a link preview (`SUPPRESS_EMBEDS` on every message: Discord would fetch the link to build one, with no click, and hand its query string to whoever runs that server), or hides a link's target (a masked link `[label](url)` is rewritten as `label (<url>)`). Tool inputs and outputs are never sent.
+
+## As a library
+
+```ts
+import { createDiscordBridge, loadConfig } from "@loomcycle/bridge-discord";
+
+const bridge = createDiscordBridge(loadConfig(), { store: myRedisStore });
+await bridge.start();
+```
+
+`ConversationStore` is four methods (`get`, `put`, `delete`, `list`); implement it over Redis or Postgres to run several instances. Interaction tokens are per process, so with several instances a reply sent by an instance other than the one that took the command goes by the bot token: it arrives as a new channel message rather than an edit of the "thinking…" reply. v1 is meant to run as one instance per bot.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm test                          # unit and HTTP tests
+./test/integration/run.sh         # builds loomcycle from this repo and runs the CLI against it (Go required)
+```
+
+The integration run boots loomcycle on the mock provider, starts the built CLI against it with a fake Discord API on localhost, and posts signed interactions.
+
+For a real Discord test, expose the bridge with a tunnel and set it as the application's Interactions Endpoint URL.

package/dist/api.d.ts

@@ -0,0 +1,51 @@
+import type { Logger } from "@loomcycle/bridge-core";
+import type { MessageBody } from "./cards.js";
+export interface DiscordApiOptions {
+    baseUrl: string;
+    applicationId: string;
+    botToken: string;
+    log: Logger;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class DiscordApiError extends Error {
+    readonly status: number;
+    readonly route: string;
+    /** Discord's JSON error code (10062 "Unknown interaction", say), when sent. */
+    readonly code?: number | undefined;
+    constructor(status: number, route: string, 
+    /** Discord's JSON error code (10062 "Unknown interaction", say), when sent. */
+    code?: number | undefined);
+}
+/** Discord asks bot clients to identify themselves this way. */
+export declare const USER_AGENT = "DiscordBot (https://github.com/denn-gubsky/loomcycle, 0.1.0)";
+export interface CommandSpec {
+    name: string;
+    description: string;
+    type: 1;
+    contexts: number[];
+    integration_types: number[];
+    options?: Array<{
+        type: 3;
+        name: string;
+        description: string;
+        required: boolean;
+        max_length?: number;
+    }>;
+}
+export declare class DiscordApi {
+    private readonly opts;
+    private readonly fetch;
+    private readonly sleep;
+    constructor(opts: DiscordApiOptions);
+    editOriginal(interactionToken: string, body: MessageBody): Promise<unknown>;
+    followUp(interactionToken: string, body: MessageBody): Promise<unknown>;
+    createMessage(channelId: string, body: MessageBody): Promise<unknown>;
+    typing(channelId: string): Promise<unknown>;
+    /** putCommands replaces the application's commands: globally, or in one server. */
+    putCommands(commands: CommandSpec[], guildId?: string): Promise<unknown>;
+    private call;
+}
+/** retryAfterMs reads how long a 429 asks to wait: the body's retry_after
+ *  (seconds, fractional), else the Retry-After header (seconds). */
+export declare function retryAfterMs(body: unknown, header: string | null): number | undefined;

package/dist/api.js

@@ -0,0 +1,101 @@
+// Discord's REST API, the few calls the bridge makes, over fetch.
+//
+// Two kinds of credential: the interaction webhook routes are authorised by
+// the interaction token in their path and get no Authorization header; the
+// channel routes and command registration use the bot token. Neither is ever
+// put in a log line or an error: an error names the route's shape only.
+export class DiscordApiError extends Error {
+    status;
+    route;
+    code;
+    constructor(status, route, 
+    /** Discord's JSON error code (10062 "Unknown interaction", say), when sent. */
+    code) {
+        super(`discord ${route}: http ${status}`);
+        this.status = status;
+        this.route = route;
+        this.code = code;
+        this.name = "DiscordApiError";
+    }
+}
+/** Discord asks bot clients to identify themselves this way. */
+export const USER_AGENT = "DiscordBot (https://github.com/denn-gubsky/loomcycle, 0.1.0)";
+/** A 429 is waited out at most this many times, each wait at most this long. */
+const MAX_RETRIES = 3;
+const MAX_WAIT_MS = 30_000;
+export class DiscordApi {
+    opts;
+    fetch;
+    sleep;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetch = opts.fetch ?? globalThis.fetch;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    editOriginal(interactionToken, body) {
+        return this.call("PATCH", `/webhooks/${this.opts.applicationId}/${interactionToken}/messages/@original`, "PATCH webhooks/@original", body, false);
+    }
+    followUp(interactionToken, body) {
+        return this.call("POST", `/webhooks/${this.opts.applicationId}/${interactionToken}`, "POST webhooks/followup", body, false);
+    }
+    createMessage(channelId, body) {
+        return this.call("POST", `/channels/${channelId}/messages`, "POST channels/messages", body, true);
+    }
+    typing(channelId) {
+        return this.call("POST", `/channels/${channelId}/typing`, "POST channels/typing", undefined, true);
+    }
+    /** putCommands replaces the application's commands: globally, or in one server. */
+    putCommands(commands, guildId) {
+        const path = guildId
+            ? `/applications/${this.opts.applicationId}/guilds/${guildId}/commands`
+            : `/applications/${this.opts.applicationId}/commands`;
+        return this.call("PUT", path, guildId ? "PUT guild commands" : "PUT global commands", commands, true);
+    }
+    async call(method, path, route, body, bot) {
+        const headers = { "user-agent": USER_AGENT };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        if (bot)
+            headers.authorization = `Bot ${this.opts.botToken}`;
+        for (let attempt = 0;; attempt++) {
+            const res = await this.fetch(`${this.opts.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            const text = await res.text();
+            const json = parseJson(text);
+            if (res.status === 429 && attempt < MAX_RETRIES) {
+                const wait = retryAfterMs(json, res.headers.get("retry-after"));
+                if (wait !== undefined && wait <= MAX_WAIT_MS) {
+                    this.opts.log.warn("discord rate limited, waiting", { route, wait_ms: wait });
+                    await this.sleep(wait);
+                    continue;
+                }
+            }
+            if (!res.ok) {
+                const code = typeof json?.code === "number" ? json.code : undefined;
+                throw new DiscordApiError(res.status, route, code);
+            }
+            return json;
+        }
+    }
+}
+function parseJson(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** retryAfterMs reads how long a 429 asks to wait: the body's retry_after
+ *  (seconds, fractional), else the Retry-After header (seconds). */
+export function retryAfterMs(body, header) {
+    const fromBody = body?.retry_after;
+    const seconds = typeof fromBody === "number" ? fromBody : header !== null ? Number(header) : NaN;
+    return Number.isFinite(seconds) && seconds >= 0 ? Math.ceil(seconds * 1000) : undefined;
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/bridge.d.ts

@@ -0,0 +1,12 @@
+import { type Bridge, type BridgeOptions } from "@loomcycle/bridge-core";
+import type { DiscordConfig } from "./config.js";
+import { type DiscordRef } from "./port.js";
+export declare const MAX_MESSAGE_CHARS = 2000;
+export interface DiscordBridgeOptions extends BridgeOptions<DiscordRef> {
+    /** Override how Discord's API is called (tests, a proxy). */
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    /** How long a button press may take before it is acked and finished later. */
+    inlineCardMs?: number;
+}
+export declare function createDiscordBridge(cfg: DiscordConfig, opts?: DiscordBridgeOptions): Bridge<DiscordRef>;

package/dist/bridge.js

@@ -0,0 +1,41 @@
+// The Discord adapter on the shared core: interactions over HTTP, no Gateway.
+import { consoleLogger, createBridge } from "@loomcycle/bridge-core";
+import { DiscordApi } from "./api.js";
+import { registerCommands } from "./commands.js";
+import { interactionRoute } from "./interactions.js";
+import { DiscordPort } from "./port.js";
+import { publicKeyFromHex } from "./verify.js";
+export const MAX_MESSAGE_CHARS = 2000;
+export function createDiscordBridge(cfg, opts = {}) {
+    const log = opts.logger ?? consoleLogger;
+    const now = opts.now ?? Date.now;
+    const api = new DiscordApi({
+        baseUrl: cfg.apiBaseUrl,
+        applicationId: cfg.applicationId,
+        botToken: cfg.botToken,
+        log,
+        fetch: opts.fetch,
+        sleep: opts.sleep,
+    });
+    const port = new DiscordPort(api, log, { now });
+    const key = publicKeyFromHex(cfg.publicKey);
+    const adapter = {
+        platform: { name: "discord", label: "Discord" },
+        // Without the Gateway there is no message to edit as it grows, and each
+        // turn is one message per 2,000 characters.
+        capabilities: { streaming: "never", maxMessageChars: MAX_MESSAGE_CHARS },
+        port,
+        async start(ctx) {
+            await ctx.serve({
+                "POST /discord/interactions": interactionRoute({ cfg, key, port, api, router: ctx.router, log: ctx.log, now, inlineCardMs: opts.inlineCardMs }),
+            });
+            if (cfg.registerCommands)
+                await registerCommands(api, cfg, ctx.log);
+        },
+        async stop() {
+            port.stop();
+        },
+    };
+    return createBridge(cfg, adapter, { ...opts, logger: log });
+}
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAuD,MAAM,wBAAwB,CAAC;AAE1H,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAmB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAUtC,MAAM,UAAU,mBAAmB,CAAC,GAAkB,EAAE,OAA6B,EAAE;IACrF,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC;QACzB,OAAO,EAAE,GAAG,CAAC,UAAU;QACvB,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,GAAG;QACH,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAE5C,MAAM,OAAO,GAA8B;QACzC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE;QAC/C,wEAAwE;QACxE,4CAA4C;QAC5C,YAAY,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE;QACxE,IAAI;QACJ,KAAK,CAAC,KAAK,CAAC,GAAG;YACb,MAAM,GAAG,CAAC,KAAK,CAAC;gBACd,4BAA4B,EAAE,gBAAgB,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;aAChJ,CAAC,CAAC;YACH,IAAI,GAAG,CAAC,gBAAgB;gBAAE,MAAM,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QACtE,CAAC;QACD,KAAK,CAAC,IAAI;YACR,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;KACF,CAAC;IACF,OAAO,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;AAC9D,CAAC"}

package/dist/cards.d.ts

@@ -0,0 +1,42 @@
+import { type CanonicalCard } from "@loomcycle/bridge-core";
+export interface MessageBody {
+    content?: string;
+    components?: Array<{
+        type: 1;
+        components: Button[];
+    }>;
+    allowed_mentions: {
+        parse: string[];
+    };
+    flags: number;
+}
+interface Button {
+    type: 2;
+    style: number;
+    label: string;
+    custom_id: string;
+}
+export declare const CUSTOM_ID_PREFIX = "lc:";
+export declare const MAX_CUSTOM_ID = 100;
+export declare const MAX_CONTENT = 2000;
+export declare const NO_MENTIONS: {
+    parse: string[];
+};
+export declare const SUPPRESS_EMBEDS: number;
+export declare const FREE_TEXT_HINT = "Answer with `/ask` and your answer, or decline.";
+export declare function customIdOf(buttonId: string): string;
+/** parseCustomId returns the core's button id, or undefined when the button
+ *  is not one this bridge drew. */
+export declare function parseCustomId(customId: unknown): {
+    buttonId: string;
+} | undefined;
+/** neutraliseLinks rewrites each masked link as `label (<url>)`, so the shown
+ *  text holds the real target (the angle brackets also keep it from
+ *  unfurling). A `](` it cannot parse (a URL with parentheses, nested
+ *  brackets) gets a zero-width space, which breaks the link and shows it raw. */
+export declare function neutraliseLinks(text: string): string;
+/** textMessage is one short message: a line from the bridge, or a piece of
+ *  a turn already cut to size (neutralising may lengthen it, hence the clip). */
+export declare function textMessage(text: string): MessageBody;
+export declare function renderCard(card: CanonicalCard): MessageBody;
+export {};

package/dist/cards.js

@@ -0,0 +1,96 @@
+// The core's question and review cards as Discord messages: the text, and
+// rows of buttons whose custom_id is the core's short button id. Discord keeps
+// a button's custom_id to 100 characters, and the core looks the action up by
+// id, so the id is all a button carries.
+//
+// Every message the bridge posts carries agent-written text, which an
+// untrusted speaker can steer. So none of them pings anyone (allowed_mentions
+// parses nothing) and none shows a link preview: Discord fetches a link to
+// build its preview without anyone clicking, which would send the URL's query
+// string to whoever runs the server. SUPPRESS_EMBEDS also hides embeds the
+// bridge would build, so cards are plain content. And no masked link
+// (`[label](url)`) survives: Discord renders one in a bot's message, so the
+// agent could show one address and open another.
+import { VERB } from "@loomcycle/bridge-core";
+export const CUSTOM_ID_PREFIX = "lc:";
+export const MAX_CUSTOM_ID = 100;
+const MAX_LABEL = 80;
+export const MAX_CONTENT = 2000;
+const BUTTONS_PER_ROW = 5;
+const Style = { PRIMARY: 1, SECONDARY: 2, SUCCESS: 3, DANGER: 4 };
+export const NO_MENTIONS = { parse: [] };
+export const SUPPRESS_EMBEDS = 1 << 2;
+export const FREE_TEXT_HINT = "Answer with `/ask` and your answer, or decline.";
+export function customIdOf(buttonId) {
+    const id = `${CUSTOM_ID_PREFIX}${buttonId}`;
+    if (id.length > MAX_CUSTOM_ID)
+        throw new Error("button id too long for Discord");
+    return id;
+}
+/** parseCustomId returns the core's button id, or undefined when the button
+ *  is not one this bridge drew. */
+export function parseCustomId(customId) {
+    if (typeof customId !== "string")
+        return undefined;
+    const m = /^lc:([A-Za-z0-9_-]{1,64})$/.exec(customId);
+    return m ? { buttonId: m[1] } : undefined;
+}
+function clip(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+function rows(buttons) {
+    const out = [];
+    for (let i = 0; i < buttons.length; i += BUTTONS_PER_ROW)
+        out.push({ type: 1, components: buttons.slice(i, i + BUTTONS_PER_ROW) });
+    return out;
+}
+function button(b, style) {
+    return { type: 2, style, label: clip(b.label || "…", MAX_LABEL), custom_id: customIdOf(b.id) };
+}
+const MASKED_LINK = /\[([^[\]\n]*)\]\(\s*<?([^\s()<>]+)>?(?:\s+"[^"\n]*")?\s*\)/g;
+/** neutraliseLinks rewrites each masked link as `label (<url>)`, so the shown
+ *  text holds the real target (the angle brackets also keep it from
+ *  unfurling). A `](` it cannot parse (a URL with parentheses, nested
+ *  brackets) gets a zero-width space, which breaks the link and shows it raw. */
+export function neutraliseLinks(text) {
+    return text.replace(MASKED_LINK, (_, label, url) => `${label} (<${url}>)`).replace(/\]\(/g, "]\u200b(");
+}
+/** textMessage is one short message: a line from the bridge, or a piece of
+ *  a turn already cut to size (neutralising may lengthen it, hence the clip). */
+export function textMessage(text) {
+    return { content: clip(neutraliseLinks(text), MAX_CONTENT), allowed_mentions: NO_MENTIONS, flags: SUPPRESS_EMBEDS };
+}
+export function renderCard(card) {
+    switch (card.kind) {
+        case "result":
+            // Replaces a used card: the buttons go, so it cannot be answered twice.
+            return { ...textMessage(card.message), components: [] };
+        case "question": {
+            // A Discord message has no text field, so a free-text question is
+            // answered with the owner's next /ask; the core's "Send" button would
+            // only ever say "type an answer first".
+            const freeText = card.options.length === 0;
+            const buttons = card.buttons
+                .filter((b) => !(freeText && b.action.verb === VERB.answer))
+                .map((b) => button(b, b.action.verb === VERB.decline ? Style.SECONDARY : Style.PRIMARY));
+            const hint = freeText ? `\n\n${FREE_TEXT_HINT}` : "";
+            const text = neutraliseLinks([card.question || "The agent has a question.", card.context].filter(Boolean).join("\n\n"));
+            return {
+                content: `**Question**\n${clip(text, MAX_CONTENT - hint.length - 13)}${hint}`,
+                components: rows(buttons),
+                allowed_mentions: NO_MENTIONS,
+                flags: SUPPRESS_EMBEDS,
+            };
+        }
+        case "review": {
+            const buttons = card.buttons.map((b) => button(b, b.action.verb === VERB.approve ? Style.SUCCESS : Style.DANGER));
+            return {
+                content: `**Review**\nThe agent's answer is waiting for your review.${card.round ? ` Round ${card.round}.` : ""}`,
+                components: rows(buttons),
+                allowed_mentions: NO_MENTIONS,
+                flags: SUPPRESS_EMBEDS,
+            };
+        }
+    }
+}
+//# sourceMappingURL=cards.js.map

package/dist/cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.js","sourceRoot":"","sources":["../src/cards.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+EAA+E;AAC/E,8EAA8E;AAC9E,yCAAyC;AACzC,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,qEAAqE;AACrE,4EAA4E;AAC5E,iDAAiD;AAEjD,OAAO,EAAE,IAAI,EAAuC,MAAM,wBAAwB,CAAC;AAgBnF,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AACtC,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AACjC,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC;AAChC,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,KAAK,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAW,CAAC;AAE3E,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,KAAK,EAAE,EAAc,EAAE,CAAC;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAI,CAAC,CAAC;AAEtC,MAAM,CAAC,MAAM,cAAc,GAAG,iDAAiD,CAAC;AAEhF,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,MAAM,EAAE,GAAG,GAAG,gBAAgB,GAAG,QAAQ,EAAE,CAAC;IAC5C,IAAI,EAAE,CAAC,MAAM,GAAG,aAAa;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACjF,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;mCACmC;AACnC,MAAM,UAAU,aAAa,CAAC,QAAiB;IAC7C,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,CAAC,GAAG,4BAA4B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5C,CAAC;AAED,SAAS,IAAI,CAAC,CAAS,EAAE,GAAW;IAClC,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;AACzD,CAAC;AAED,SAAS,IAAI,CAAC,OAAiB;IAC7B,MAAM,GAAG,GAA2C,EAAE,CAAC;IACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,eAAe;QAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;IACnI,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,MAAM,CAAC,CAAa,EAAE,KAAa;IAC1C,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACjG,CAAC;AAED,MAAM,WAAW,GAAG,6DAA6D,CAAC;AAElF;;;iFAGiF;AACjF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,KAAa,EAAE,GAAW,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AAC1H,CAAC;AAED;iFACiF;AACjF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,EAAE,gBAAgB,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;AACtH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC5C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ;YACX,wEAAwE;YACxE,OAAO,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QAC1D,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,kEAAkE;YAClE,sEAAsE;YACtE,wCAAwC;YACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;YAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO;iBACzB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,CAAC;iBAC3D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAC3F,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,GAAG,eAAe,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,2BAA2B,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACxH,OAAO;gBACL,OAAO,EAAE,iBAAiB,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE;gBAC7E,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC;gBACzB,gBAAgB,EAAE,WAAW;gBAC7B,KAAK,EAAE,eAAe;aACvB,CAAC;QACJ,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;YAClH,OAAO;gBACL,OAAO,EAAE,6DAA6D,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACjH,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC;gBACzB,gBAAgB,EAAE,WAAW;gBAC7B,KAAK,EAAE,eAAe;aACvB,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "@loomcycle/bridge-core";
+import { createDiscordBridge } from "./bridge.js";
+import { loadConfig } from "./config.js";
+void runCli("discord-bridge", () => createDiscordBridge(loadConfig()));
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,KAAK,MAAM,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,mBAAmB,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC"}

package/dist/commands.d.ts

@@ -0,0 +1,10 @@
+import type { Logger } from "@loomcycle/bridge-core";
+import type { CommandSpec, DiscordApi } from "./api.js";
+import type { DiscordConfig } from "./config.js";
+export declare const MAX_PROMPT_CHARS = 4000;
+export declare const HELP_TEXT: string;
+export declare function commandSpecs(contexts: number[]): CommandSpec[];
+/** registerCommands replaces the application's commands in every allowed
+ *  server, and globally (DMs only) when DMs are on. The bridge owns the
+ *  application's commands: anything else registered there is replaced. */
+export declare function registerCommands(api: DiscordApi, cfg: Pick<DiscordConfig, "allowedGuilds" | "allowDms">, log: Logger): Promise<void>;

package/dist/commands.js

@@ -0,0 +1,46 @@
+// The slash commands, and registering them.
+//
+// In each allowed server they are registered as that server's commands: those
+// take effect at once and show only where the bot answers. Commands in DMs
+// can only be global, so with DMs on they are also registered globally,
+// limited to the bot's DMs, so a server never lists them twice.
+import { Context } from "./interaction.js";
+const GUILD_INSTALL = 0;
+export const MAX_PROMPT_CHARS = 4000;
+export const HELP_TEXT = [
+    "Commands:",
+    "- **/ask** `prompt`: talk to the agent. When it asks you a question without options, answer with /ask too.",
+    "- **/new**: start a new conversation (the agent forgets this one)",
+    "- **/stop**: stop the current answer",
+    "- **/help**: show this list",
+    "",
+    "In a server, everyone in a channel shares one conversation with the agent. The person who started it answers the agent's questions and can /new or /stop it.",
+].join("\n");
+export function commandSpecs(contexts) {
+    const base = { type: 1, contexts, integration_types: [GUILD_INSTALL] };
+    return [
+        {
+            ...base,
+            name: "ask",
+            description: "Talk to the agent",
+            options: [{ type: 3, name: "prompt", description: "What to say to the agent", required: true, max_length: MAX_PROMPT_CHARS }],
+        },
+        { ...base, name: "new", description: "Start a new conversation with the agent" },
+        { ...base, name: "stop", description: "Stop the agent's current answer" },
+        { ...base, name: "help", description: "Show what the bot can do" },
+    ];
+}
+/** registerCommands replaces the application's commands in every allowed
+ *  server, and globally (DMs only) when DMs are on. The bridge owns the
+ *  application's commands: anything else registered there is replaced. */
+export async function registerCommands(api, cfg, log) {
+    for (const guild of cfg.allowedGuilds) {
+        await api.putCommands(commandSpecs([Context.GUILD]), guild);
+        log.info("registered commands", { guild });
+    }
+    if (cfg.allowDms) {
+        await api.putCommands(commandSpecs([Context.BOT_DM]));
+        log.info("registered commands", { scope: "dm" });
+    }
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,wEAAwE;AACxE,gEAAgE;AAMhE,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAErC,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,WAAW;IACX,4GAA4G;IAC5G,mEAAmE;IACnE,sCAAsC;IACtC,6BAA6B;IAC7B,EAAE;IACF,8JAA8J;CAC/J,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,UAAU,YAAY,CAAC,QAAkB;IAC7C,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,CAAU,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,aAAa,CAAC,EAAE,CAAC;IAChF,OAAO;QACL;YACE,GAAG,IAAI;YACP,IAAI,EAAE,KAAK;YACX,WAAW,EAAE,mBAAmB;YAChC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0BAA0B,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC;SAC9H;QACD,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,yCAAyC,EAAE;QAChF,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,iCAAiC,EAAE;QACzE,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,0BAA0B,EAAE;KACnE,CAAC;AACJ,CAAC;AAED;;0EAE0E;AAC1E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAe,EAAE,GAAsD,EAAE,GAAW;IACzH,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACtC,MAAM,GAAG,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5D,GAAG,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,MAAM,GAAG,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACtD,GAAG,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import { type Env, type SharedConfig } from "@loomcycle/bridge-core";
+export interface DiscordConfig extends SharedConfig {
+    applicationId: string;
+    /** The application's Ed25519 public key, 32 bytes as hex. */
+    publicKey: string;
+    /** Sent only to Discord's REST API, never logged. */
+    botToken: string;
+    /** Servers the bot answers in. Every other server is refused. */
+    allowedGuilds: Set<string>;
+    /** Anyone who can reach the app may use it in a DM with the bot. */
+    allowDms: boolean;
+    /** Allowed servers whose speakers are trusted. Elsewhere in a server they are not. */
+    trustedGuilds: Set<string>;
+    /** Register the slash commands when the bridge starts. */
+    registerCommands: boolean;
+    /** Discord's REST base, without a trailing slash. */
+    apiBaseUrl: string;
+}
+export declare const DEFAULT_PORT = 8080;
+export declare const DEFAULT_API_BASE_URL = "https://discord.com/api/v10";
+export declare function isSnowflake(v: unknown): v is string;
+export declare function loadConfig(env?: Env): DiscordConfig;