@astrofoundry/pi-astro 0.30.0 → 0.31.0

package/README.md

@@ -1,6 +1,6 @@
 # @astrofoundry/pi-astro
 
-Personal customizations for the [pi coding agent](https://github.com/earendil-works/pi): 25 subagents (8 general-purpose, 8 Flourish-pipeline, 9 homelab specialists) run by the bundled `astro-subagents` extension, a `grimoire` docs tool, a `caveman` compressed-output toggle, an `astro-footer` status bar, 14 skills, and an `astro` theme.
+Personal customizations for the [pi coding agent](https://github.com/earendil-works/pi): 26 subagents (8 general-purpose, 8 Flourish-pipeline, 10 homelab specialists) run by the bundled `astro-subagents` extension, a `grimoire` docs tool, a `caveman` compressed-output toggle, an `astro-footer` status bar, 15 skills, and an `astro` theme.
 
 ## Full setup
 
@@ -68,8 +68,8 @@ pi                # launch; confirm [Extensions] lists astro-subagents, grimoire
 - `multi-edit` - registers the enhanced `edit` tool
 - `gemini-image` - registers `gemini_image` tool (requires a Gemini API key; prompts and saves on first use)
 - `security-guard` - blocks/prompts destructive bash commands and sensitive file access; configure at `~/.pi/agent/security-guard.json` (example written on first run); `/security-guard status|reload|test`
-- `astro-discord` - Discord access to the specialists: in the configured channels, `<specialist> <task>` runs `astro.<specialist>` and posts the answer as a reply (⏳ running, 🔒 waiting for an owner's approval of a risky call, ✅ done, ❌ failed). Owners may use every specialist and approve risky calls with buttons; other users only the specialists listed for them; everyone else is ignored. Inert unless the headless host sets `ASTRO_DISCORD=1`; setup with `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node refuses to strip types inside `node_modules`, hence the copy), which prompts for the bot token and ids, checks them against Discord, and writes the LaunchAgent. See [specialists/README.md](specialists/README.md#discord).
-- `specialist-gate` - gives each specialist agent (`astro.arcane`, `astro.identity`, `astro.network`, `astro.dns`, `astro.edge`, `astro.security`, `astro.backup`, `astro.proxmox`, `astro.inference`) its single tool, which runs the matching CLI wrapper as a dedicated macOS user through `sudo`, and blocks every other agent from calling those CLIs or reading their credentials. Inactive until the host has `~/.pi/agent/specialists.json`. `/specialists` prints the status. Host setup is described in [specialists/README.md](specialists/README.md).
+- `astro-discord` - Discord access to the specialists: in the configured channels, `<specialist> <task>` runs `astro.<specialist>` and posts the answer as a reply (⏳ running, 🔒 waiting for an owner's approval of a risky call, ✅ done, ❌ failed). Owners may use every specialist and approve risky calls with buttons; other users only the specialists listed for them; everyone else is ignored. Where the `media` specialist is present, `/trending`, `/search`, and `/downloads` answer without a model, with an Add button beside each title. Inert unless the headless host sets `ASTRO_DISCORD=1`; setup with `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node refuses to strip types inside `node_modules`, hence the copy), which prompts for the bot token and ids, checks them against Discord, and writes the LaunchAgent. See [specialists/README.md](specialists/README.md#discord).
+- `specialist-gate` - gives each specialist agent (`astro.arcane`, `astro.identity`, `astro.network`, `astro.dns`, `astro.edge`, `astro.security`, `astro.backup`, `astro.proxmox`, `astro.inference`, `astro.media`) its single tool, which runs the matching CLI wrapper as a dedicated macOS user through `sudo`, and blocks every other agent from calling those CLIs or reading their credentials. Inactive until the host has `~/.pi/agent/specialists.json`. `/specialists` prints the status. Host setup is described in [specialists/README.md](specialists/README.md).
 - `notify-on-stop` - runs a shell command when the agent finishes a turn (sound, voice, desktop notification). **Default: off.** Enable with `/notify on` (state persists in `~/.pi/agent/notify-on-stop.json`); disable with `/notify off`. macOS default command: plays the Glass system sound and speaks "Agent done" via `say` using the **`Samantha (Enhanced)`** voice. Linux default: `notify-send "pi" "Agent done"`. Override the voice with `PI_STOP_NOTIFY_VOICE=<voice-name>` (macOS only; e.g. `Alex`, `Karen`, `Daniel (Enhanced)`). Replace the full command with `PI_STOP_NOTIFY='afplay /System/Library/Sounds/Glass.aiff && say "Done"'`. Hard-kill (overrides `/notify on`) with `PI_STOP_NOTIFY_OFF=1`. Commands: `/notify [on|off|status|test]`. See [extensions/notify-on-stop/README.md](extensions/notify-on-stop/README.md) for full details.
   - **macOS voice install (required once for the default):** open **System Settings, Accessibility, Spoken Content, System Voice, Manage Voices...**, expand **English**, check **Samantha (Enhanced)**, click **Done** to download (~500 MB to 1 GB). Verify with `say -v "Samantha (Enhanced)" hi`. If the voice is missing, `say` errors silently and you'll only hear the Glass sound.
 - `vscode-image` - only active inside VS Code's integrated terminal (`TERM_PROGRAM=vscode`). Switches pi-tui's image output to the **Kitty graphics protocol** so images returned by tools like `gemini_image` render as real pixels instead of the `[Image: ...]` text fallback. **Requires enabling `Terminal > Integrated: Enable Images` in VS Code settings** (off by default); restart the integrated terminal after flipping it. Disable with `PI_VSCODE_IMAGE_OFF=1`. `/vscode-image` prints current status.
@@ -80,11 +80,11 @@ pi                # launch; confirm [Extensions] lists astro-subagents, grimoire
 
 **Bundled subagents** (call them as `astro.<name>`):
 - General-purpose: `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
-- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi reads and firewall policies, FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health)
+- Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi reads and firewall policies, FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Hermes gateways and upgrades, Europa health), `media` (trendarr: trending titles, Radarr and Sonarr adds, SABnzbd pause)
 - Flourish pipeline: `flourish-input-vision` (image to spec), `flourish-input-narrative` (text to spec), `flourish-input-codebase` (HTML to spec), `flourish-architect` (spec to plan), `flourish-template-developer` (plan to SDK template, needs `@flourish/sdk`), `flourish-example-builder` (template to realistic example), `flourish-preview-runner` (multi-breakpoint preview + screenshots, needs `@flourish/sdk`), `flourish-reviewer` (audit)
 
 **Skills** (loadable via `/skill:<name>`):
-- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`, `flourish-chart-spec`, `arcane`, `identity`, `network`, `dns`, `edge`, `security`, `backup`, `proxmox`, `inference` (the last nine are injected into their specialist agents)
+- `playwright-cli`, `postman-cli`, `raycast-script-creator`, `caveman`, `flourish-chart-spec`, `arcane`, `identity`, `network`, `dns`, `edge`, `security`, `backup`, `proxmox`, `inference`, `media` (the last ten are injected into their specialist agents)
 
 **Theme:**
 - `astro` - dark, gold accent, GitHub-dark-inspired

package/agents/media.md

@@ -0,0 +1,24 @@
+---
+name: media
+description: Manages the movie and series library through the media tool (trendarr), covering weekly trending with IMDb ratings, title search, adds to Radarr and Sonarr, and the SABnzbd queue pause state. Use for what is trending, adding a movie or series by name, and pausing or resuming downloads.
+tools: read, media, subagent
+skills: media
+systemPromptMode: replace
+inheritProjectContext: false
+inheritSkills: false
+maxSubagentDepth: 1
+model: openai-codex/gpt-6-astra
+thinking: xhigh
+---
+You are the media specialist. The `media` tool, which runs the `trendarr` CLI, is your only way to reach TMDB, OMDb, Radarr, Sonarr, and SABnzbd. You have no shell, no web, and no file access; if a task needs anything else, say so and stop.
+
+Rules:
+
+- Search before you add, and add only IMDb IDs that a `search` or `trending` result returned in this conversation. Never invent or guess an ID.
+- Resolve the title with the rules in the skill. A named film or series with one clear match: add it without asking. Ask one short question only when several plausible works remain and the choice changes what gets added.
+- Movies go to `add-movies`, series to `add-series`; batch independent IDs in one call.
+- Success needs an explicit `added` or `already_exists` in `results`; `already_exists` means it was already there, not newly added. Report every ID of a batch.
+- Pause or resume downloads only when the task asks for it, then report the returned state. Adding never implies a queue change.
+- Keep replies short: canonical title and year, outcome, and the SABnzbd state an add returned. Mention `/trending` and `/search` when the user would rather click Add buttons.
+- Library settings, quality profiles, Radarr and Sonarr configuration, and deletions are operator tasks; say so and stop.
+- Delegate through `subagent` only to another specialist (`astro.arcane` for the media containers on the Arcane VM) and only for that specialist's own area.

package/extensions/astro-discord/commands.ts

@@ -59,6 +59,7 @@ export function helpText(allowed: readonly string[], present: readonly string[],
     if (present.length > 1) lines.push(...allowed.map((name) => `• \`${name}\``));
     lines.push("Reactions: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed.");
     lines.push("A reply to my answer, or another task for the same specialist within 30 minutes, continues that conversation; start the task with `new` for a fresh one.");
+    if (allowed.includes("media")) lines.push("Slash commands `/trending`, `/search`, and `/downloads` answer directly, without the agent; an Add button adds that title at once.");
     const commands = ["`help` this message", "`status` running tasks"];
     if (canConfig) commands.push("`config show`", "`config channel <#channel> <always|mention> <*|name,name>`", "`config access <specialist> add|remove <@user>`");
     lines.push(`Commands: ${commands.join(", ")}.`);

package/extensions/astro-discord/index.ts

@@ -15,6 +15,7 @@ import { type ConversationState, type ResolvedConversation, forgetStale, loadSta
 import { describeImages, downloadImages, type ImageAttachment, imageAttachments } from "./attachments.ts";
 import { failureMessage, formatDailyReport, isDue, readReportState, writeReportState } from "./daily-report.ts";
 import { GatewayClient } from "./gateway.ts";
+import { type CommandOption, IS_COMPONENTS_V2, KeyedQueue, MEDIA, MEDIA_COMMANDS, type MediaKind, type Outcome, addOutcome, applyOutcome, commandArgs, hasActiveButton, listMessage, mediaAccess, mediaPointer, parseAddButton, parseAddReport, parseMediaList, parseQueueState, queueLine } from "./media.ts";
 import { cancelledApprovalText, interruptedTaskText, readOpenWork, type OpenWork, type StopReason, writeOpenWork } from "./open-work.ts";
 import { type Quote, type QuotedMessage, withQuotes } from "./quote.ts";
 import { DiscordRest, type MessageComponent } from "./rest.ts";
@@ -70,17 +71,31 @@ interface IncomingMessage {
     message_snapshots?: { message: QuotedMessage }[];
 }
 
-interface ComponentInteraction {
+/** A slash command (type 2) or a component click (type 3) as the gateway delivers it. */
+interface Interaction {
     id: string;
     token: string;
     type: number;
     channel_id?: string;
-    message?: { id: string };
-    data?: { custom_id?: string; component_type?: number };
+    message?: { id: string; components?: MessageComponent[] };
+    data?: { custom_id?: string; component_type?: number; name?: string; options?: CommandOption[] };
     member?: { user?: { id: string } };
     user?: { id: string };
 }
 
+/** A media command or Add click still running; the token lets a shutdown answer it. */
+interface MediaRun {
+    channelId: string;
+    token: string;
+    kind: "command" | "add";
+}
+
+/** Media list messages whose buttons changed, newest last; older ones fall back to the clicked message's own state. */
+const MEDIA_MESSAGE_CACHE = 100;
+/** Upper bound for one media wrapper call from Discord; a single add or list takes seconds. */
+const MEDIA_TIMEOUT_MS = 3 * 60_000;
+const EPHEMERAL = 64;
+
 interface ActiveTask {
     specialist: string;
     channelId: string;
@@ -123,6 +138,9 @@ class Bridge {
     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 readonly mediaRuns = new Map<string, MediaRun>();
+    private readonly mediaClicks = new KeyedQueue();
+    private readonly mediaMessages = new Map<string, MessageComponent[]>();
     private gateway: GatewayClient | undefined;
     private stopping = false;
     private reportRunning = false;
@@ -162,7 +180,10 @@ class Bridge {
     private openWork(): OpenWork {
         return {
             since: this.since,
-            tasks: [...this.active.values()].map((t) => ({ specialist: t.specialist, channelId: t.channelId, messageId: t.messageId, ...(t.placeholder ? { placeholderId: t.placeholder } : {}) })),
+            tasks: [
+                ...[...this.active.values()].map((t) => ({ specialist: t.specialist, channelId: t.channelId, messageId: t.messageId, ...(t.placeholder ? { placeholderId: t.placeholder } : {}) })),
+                ...[...this.mediaRuns.values()].map((r) => ({ specialist: MEDIA, channelId: r.channelId })),
+            ],
             approvals: [...this.approvalMessages.entries()].map(([ticketId, a]) => ({ ticketId, channelId: a.channelId, messageId: a.messageId, userChannelId: a.userMessage.channelId, userMessageId: a.userMessage.messageId })),
         };
     }
@@ -185,11 +206,13 @@ class Bridge {
         }
         for (const t of work.tasks) {
             const text = interruptedTaskText(t.specialist, reason);
-            edits.push((t.placeholderId ? this.rest.editMessage(t.channelId, t.placeholderId, text) : this.rest.createMessage(t.channelId, { content: text, replyTo: t.messageId })).catch(() => undefined));
+            edits.push((t.placeholderId ? this.rest.editMessage(t.channelId, t.placeholderId, text) : this.rest.createMessage(t.channelId, { content: text, ...(t.messageId ? { replyTo: t.messageId } : {}) })).catch(() => undefined));
+            const messageId = t.messageId;
+            if (!messageId) continue;
             edits.push(
                 this.rest
-                    .removeOwnReaction(t.channelId, t.messageId, REACTION.running)
-                    .then(() => this.rest.addReaction(t.channelId, t.messageId, REACTION.failed))
+                    .removeOwnReaction(t.channelId, messageId, REACTION.running)
+                    .then(() => this.rest.addReaction(t.channelId, messageId, REACTION.failed))
                     .catch(() => undefined),
             );
         }
@@ -205,7 +228,9 @@ class Bridge {
         const work = this.openWork();
         for (const task of this.active.values()) task.abort?.abort();
         if (work.tasks.length > 0 || work.approvals.length > 0) log(`shutdown: cancelling ${work.approvals.length} approval(s), interrupting ${work.tasks.length} task(s)`);
-        await this.closeOpen(work, "restart");
+        // Media runs are answered through their own interaction instead of a new channel message.
+        const answers = [...this.mediaRuns.values()].map((r) => this.answerInterruptedMedia(r).catch(() => undefined));
+        await Promise.all([this.closeOpen({ ...work, tasks: work.tasks.filter((t) => t.messageId !== undefined) }, "restart"), ...answers]);
         this.approvals.close();
         writeOpenWork({ since: this.since, tasks: [], approvals: [] });
     }
@@ -230,6 +255,7 @@ class Bridge {
         });
         gateway.start();
         this.gateway = gateway;
+        void this.registerMediaCommands();
         // Checked every minute; the report itself decides whether today's is due.
         this.reportTimer = setInterval(() => void this.maybeDailyReport(), 60_000);
         this.reportTimer.unref();
@@ -240,7 +266,7 @@ class Bridge {
     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);
+            else if (event === "INTERACTION_CREATE") await this.onInteraction(data as Interaction);
         } catch (err) {
             log(`${event} failed: ${err instanceof Error ? err.message : String(err)}`);
         }
@@ -349,11 +375,7 @@ class Bridge {
             log(`daily report ${date}: running arcane update-report`);
             let message: { content: string; attachment?: string };
             try {
-                const stdout = await new Promise<string>((resolve, reject) =>
-                    execFile("/usr/bin/sudo", ["-n", "-u", gate.user, "-H", gate.entry, "arcane", "--caller", "daily-report", "--", "update-report"], { timeout: 15 * 60_000, maxBuffer: 20 * 1024 * 1024 }, (err, out, errOut) =>
-                        err ? reject(new Error(errOut.trim() || err.message)) : resolve(out),
-                    ),
-                );
+                const stdout = await this.runEntry("arcane", "daily-report", ["update-report"], 15 * 60_000);
                 message = formatDailyReport(JSON.parse(stdout), settings.timeZone);
             } catch (err) {
                 log(`daily report ${date}: check failed: ${err instanceof Error ? err.message.slice(0, 500) : String(err)}`);
@@ -374,6 +396,143 @@ class Bridge {
         }
     }
 
+    /** Runs one specialist wrapper through the sudo entry point, without a model; rejects with the wrapper's stderr. */
+    private runEntry(service: string, caller: string, args: string[], timeoutMs: number): Promise<string> {
+        const gate = loadSpecialists().config;
+        if (!gate) return Promise.reject(new Error("specialists.json is missing"));
+        return new Promise<string>((resolve, reject) =>
+            execFile("/usr/bin/sudo", ["-n", "-u", gate.user, "-H", gate.entry, service, "--caller", caller, "--", ...args], { timeout: timeoutMs, maxBuffer: 20 * 1024 * 1024 }, (err, out, errOut) =>
+                err ? reject(new Error(errOut.trim() || err.message)) : resolve(out),
+            ),
+        );
+    }
+
+    /** Registers `/trending`, `/search`, `/downloads` when the media specialist is configured on this host. */
+    private async registerMediaCommands(): Promise<void> {
+        if (!this.specialists().names.includes(MEDIA)) return;
+        try {
+            await this.rest.overwriteGlobalCommands(this.config.applicationId, MEDIA_COMMANDS);
+            log(`media: registered ${MEDIA_COMMANDS.map((c) => `/${c.name}`).join(", ")}`);
+        } catch (err) {
+            log(`media: command registration failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+
+    private async answerInterruptedMedia(run: MediaRun): Promise<void> {
+        const text = interruptedTaskText(MEDIA, "restart");
+        if (run.kind === "command") await this.rest.editOriginal(this.config.applicationId, run.token, { content: text });
+        else await this.rest.followUp(this.config.applicationId, run.token, { content: text, flags: EPHEMERAL });
+    }
+
+    /** Whether the user may run media commands where the interaction came from; answers privately when not. */
+    private async mediaAllowed(interaction: Interaction, userId: string): Promise<boolean> {
+        this.refreshConfig();
+        const names = this.specialists().names;
+        const channel = interaction.channel_id ? await this.settingsFor(interaction.channel_id) : null;
+        const access = mediaAccess(this.config, channel?.settings ?? null, names, userId);
+        if (access === "ok") return true;
+        await this.rest.ephemeralReply(interaction.id, interaction.token, access === "channel" ? mediaPointer(this.config, names) : "You may not use the media specialist.");
+        return false;
+    }
+
+    private trackMedia(interaction: Interaction, kind: MediaRun["kind"]): void {
+        this.mediaRuns.set(interaction.id, { channelId: interaction.channel_id ?? "", token: interaction.token, kind });
+        this.saveOpenWork();
+    }
+
+    private untrackMedia(interaction: Interaction): void {
+        if (this.stopping) return;
+        this.mediaRuns.delete(interaction.id);
+        this.saveOpenWork();
+    }
+
+    /** `/trending`, `/search`, `/downloads`: the wrapper's JSON straight to Discord, no model in between. */
+    private async onMediaCommand(interaction: Interaction): Promise<void> {
+        const name = interaction.data?.name ?? "";
+        const command = commandArgs(name, interaction.data?.options ?? []);
+        if (!command) return;
+        const userId = interaction.member?.user?.id ?? interaction.user?.id ?? "";
+        if (this.stopping) {
+            await this.rest.ephemeralReply(interaction.id, interaction.token, "The bridge is restarting; try again in a minute.");
+            return;
+        }
+        if (!(await this.mediaAllowed(interaction, userId))) return;
+        await this.rest.deferReply(interaction.id, interaction.token);
+        this.trackMedia(interaction, "command");
+        log(`media /${name} for ${userId}: ${command.args.join(" ")}`);
+        const app = this.config.applicationId;
+        try {
+            const output: unknown = JSON.parse(await this.runEntry(MEDIA, `discord-${userId}`, command.args, MEDIA_TIMEOUT_MS));
+            if (command.view === "downloads") {
+                const paused = parseQueueState(output);
+                if (paused === null) throw new Error("the media wrapper returned no queue state");
+                await this.rest.editOriginal(app, interaction.token, { content: queueLine(paused) });
+                return;
+            }
+            const list = parseMediaList(output);
+            if (!list) throw new Error("the media wrapper returned no list");
+            const kinds: MediaKind[] = command.only === "movies" ? ["movie"] : command.only === "series" ? ["series"] : ["movie", "series"];
+            const query = command.view === "search" ? command.query : undefined;
+            const messages = kinds.map((kind, i) => listMessage(kind, kind === "movie" ? list.movies : list.series, command.view, query, i === kinds.length - 1 ? list.warnings : []));
+            await this.rest.editOriginal(app, interaction.token, { content: null, flags: IS_COMPONENTS_V2, components: messages[0] });
+            for (const components of messages.slice(1)) await this.rest.followUp(app, interaction.token, { flags: IS_COMPONENTS_V2, components });
+        } catch (err) {
+            const reason = (err instanceof Error ? err.message : String(err)).split("\n")[0].slice(0, 300);
+            log(`media /${name} failed: ${reason}`);
+            await this.rest.editOriginal(app, interaction.token, { content: `❌ /${name} failed: ${reason}` }).catch(() => undefined);
+        } finally {
+            this.untrackMedia(interaction);
+        }
+    }
+
+    private rememberMediaMessage(messageId: string, components: MessageComponent[]): void {
+        this.mediaMessages.delete(messageId);
+        this.mediaMessages.set(messageId, components);
+        while (this.mediaMessages.size > MEDIA_MESSAGE_CACHE) this.mediaMessages.delete(this.mediaMessages.keys().next().value as string);
+    }
+
+    /**
+     * An Add click: one add for that ID, then only that button changes to the
+     * outcome. Clicks on one message run in order, each from the state the last
+     * one left, so a double click adds once and no edit overwrites another.
+     */
+    private async onMediaButton(interaction: Interaction, customId: string): Promise<void> {
+        const target = parseAddButton(customId);
+        const message = interaction.message;
+        if (!target || !message) {
+            await this.rest.ephemeralReply(interaction.id, interaction.token, "This button is no longer active.");
+            return;
+        }
+        const userId = interaction.member?.user?.id ?? interaction.user?.id ?? "";
+        if (this.stopping) {
+            await this.rest.ephemeralReply(interaction.id, interaction.token, "The bridge is restarting; try again in a minute.");
+            return;
+        }
+        if (!(await this.mediaAllowed(interaction, userId))) return;
+        await this.rest.deferUpdate(interaction.id, interaction.token);
+        this.trackMedia(interaction, "add");
+        const app = this.config.applicationId;
+        await this.mediaClicks
+            .run(message.id, async () => {
+                const current = this.mediaMessages.get(message.id) ?? message.components ?? [];
+                if (!hasActiveButton(current, customId)) return;
+                let outcome: Outcome;
+                try {
+                    const stdout = await this.runEntry(MEDIA, `discord-${userId}`, [target.kind === "movie" ? "add-movies" : "add-series", target.imdbId], MEDIA_TIMEOUT_MS);
+                    outcome = addOutcome(parseAddReport(JSON.parse(stdout)), target.kind, target.imdbId);
+                } catch (err) {
+                    outcome = addOutcome(null, target.kind, target.imdbId, (err instanceof Error ? err.message : String(err)).split("\n")[0].slice(0, 300));
+                }
+                const next = applyOutcome(current, customId, outcome);
+                await this.rest.editOriginal(app, interaction.token, { components: next });
+                this.rememberMediaMessage(message.id, next);
+                log(`media add ${target.imdbId} for ${userId}: ${outcome.label}`);
+                if (outcome.note) await this.rest.followUp(app, interaction.token, { content: outcome.note, flags: EPHEMERAL });
+            })
+            .catch((err) => log(`media add ${target.imdbId} failed: ${err instanceof Error ? err.message : String(err)}`))
+            .finally(() => this.untrackMedia(interaction));
+    }
+
     /** Replied-to and forwarded messages to show the specialist; a bot message only when the resumed conversation does not already hold it. */
     private quotesFor(message: IncomingMessage, inContext: (id: string) => boolean): Quote[] {
         const quotes: Quote[] = [];
@@ -518,9 +677,18 @@ class Bridge {
         await this.rest.removeOwnReaction(posted.userMessage.channelId, posted.userMessage.messageId, REACTION.waiting).catch(() => undefined);
     }
 
-    private async onInteraction(interaction: ComponentInteraction): Promise<void> {
+    private async onInteraction(interaction: Interaction): Promise<void> {
+        if (interaction.type === 2) {
+            await this.onMediaCommand(interaction);
+            return;
+        }
         if (interaction.type !== 3) return;
-        const match = /^apr:([0-9a-f-]{36}):(approve|deny)$/.exec(interaction.data?.custom_id ?? "");
+        const customId = interaction.data?.custom_id ?? "";
+        if (customId.startsWith("media:")) {
+            await this.onMediaButton(interaction, customId);
+            return;
+        }
+        const match = /^apr:([0-9a-f-]{36}):(approve|deny)$/.exec(customId);
         if (!match) return;
         const userId = interaction.member?.user?.id ?? interaction.user?.id ?? "";
         this.refreshConfig();

package/extensions/astro-discord/lifecycle.test.ts

@@ -28,6 +28,13 @@ describe("open work record", () => {
         expect(readOpenWork()).toBeNull();
     });
 
+    it("records a slash command or button click, which has no user message", () => {
+        const work = { since: "t", tasks: [{ specialist: "media", channelId: "1" }], approvals: [] };
+        writeOpenWork(work);
+        expect(existsSync(busyPath())).toBe(true);
+        expect(readOpenWork()).toEqual(work);
+    });
+
     it("says why an approval was cancelled and a task interrupted", () => {
         expect(cancelledApprovalText("restart")).toMatch(/bridge restarted before a decision, so nothing was run/);
         expect(cancelledApprovalText("crash")).toMatch(/stopped unexpectedly/);

package/extensions/astro-discord/media.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, it, vi } from "vitest";
+import { helpText } from "./commands.ts";
+import { validateConfig } from "./config.ts";
+import {
+    IS_COMPONENTS_V2,
+    KeyedQueue,
+    LIST_ENTRIES,
+    MEDIA_COMMANDS,
+    type MediaEntry,
+    addOutcome,
+    applyOutcome,
+    commandArgs,
+    countComponents,
+    entryButton,
+    entryLine,
+    hasActiveButton,
+    listMessage,
+    mediaAccess,
+    mediaPointer,
+    parseAddButton,
+    parseAddReport,
+    parseMediaList,
+    parseQueueState,
+    queueLine,
+} from "./media.ts";
+import { DiscordRest, type MessageComponent } from "./rest.ts";
+
+const OWNER = "123456789012345678";
+const FRIEND = "223456789012345678";
+const STRANGER = "323456789012345678";
+const MEDIA_CHANNEL = "423456789012345678";
+const ADMIN_CHANNEL = "523456789012345678";
+const OTHER_CHANNEL = "623456789012345678";
+
+function entry(rank: number, extra: Partial<MediaEntry> = {}): MediaEntry {
+    return { rank, title: `Title ${rank}`, year: 2026, imdb_rating: "7.1", imdb_id: `tt${1000 + rank}`, in_library: false, popularity: 100.4, ...extra };
+}
+
+describe("media slash commands", () => {
+    it("declares valid commands", () => {
+        for (const command of MEDIA_COMMANDS) {
+            expect(command.name).toMatch(/^[-_\p{L}\p{N}]{1,32}$/u);
+            expect(command.name).toBe(command.name.toLowerCase());
+            expect(command.description.length).toBeLessThanOrEqual(100);
+            const required = command.options.map((o) => "required" in o && o.required === true);
+            expect(required.indexOf(false) === -1 || required.lastIndexOf(true) < required.indexOf(false)).toBe(true);
+            for (const option of command.options) {
+                expect(option.name).toMatch(/^[-_\p{L}\p{N}]{1,32}$/u);
+                expect(option.description.length).toBeLessThanOrEqual(100);
+            }
+        }
+    });
+
+    it("maps options to wrapper arguments", () => {
+        expect(commandArgs("trending", [])).toEqual({ view: "trending", args: ["trending", "--max-entries", "10"] });
+        expect(commandArgs("trending", [{ name: "type", type: 3, value: "series" }, { name: "min_rating", type: 10, value: 0 }, { name: "count", type: 4, value: 5 }])).toEqual({
+            view: "trending",
+            args: ["trending", "--max-entries", "5", "--type", "series", "--min-rating", "0"],
+            only: "series",
+        });
+        expect(commandArgs("trending", [{ name: "count", type: 4, value: 50 }])?.args).toEqual(["trending", "--max-entries", "10"]);
+        expect(commandArgs("search", [{ name: "title", type: 3, value: "  dune " }])).toEqual({ view: "search", args: ["search", "dune", "--max-entries", "10"], query: "dune" });
+        expect(commandArgs("search", [{ name: "title", type: 3, value: "  " }])).toBeNull();
+        expect(commandArgs("downloads", [{ name: "action", type: 3, value: "pause" }])).toEqual({ view: "downloads", args: ["sabnzbd", "pause"] });
+        expect(commandArgs("downloads", [{ name: "action", type: 3, value: "delete" }])).toBeNull();
+        expect(commandArgs("ban", [])).toBeNull();
+    });
+
+    it("reads the wrapper's JSON defensively", () => {
+        expect(parseMediaList({ movies: [entry(1)], series: [], warnings: ["Radarr unreachable", 3] })).toEqual({ movies: [entry(1)], series: [], warnings: ["Radarr unreachable"] });
+        expect(parseMediaList({ movies: [{ rank: "1" }], series: [] })).toBeNull();
+        expect(parseMediaList({ results: [] })).toBeNull();
+        expect(parseAddReport({ results: [{ imdb_id: "tt1", title: "X", status: "added", detail: null }, { bad: 1 }], sabnzbd_paused: true })).toEqual({ results: [{ imdb_id: "tt1", title: "X", status: "added", detail: null }], sabnzbd_paused: true });
+        expect(parseAddReport({ results: [], sabnzbd_paused: "no" })).toEqual({ results: [], sabnzbd_paused: null });
+        expect(parseAddReport(null)).toBeNull();
+        expect(parseQueueState({ sabnzbd_paused: false })).toBe(false);
+        expect(parseQueueState({})).toBeNull();
+        expect(queueLine(true)).toBe("SABnzbd paused: yes");
+    });
+});
+
+describe("media list layout", () => {
+    it("writes trendarr's Discord line without the library flag", () => {
+        expect(entryLine(entry(1, { title: "Hope", imdb_rating: "6.9", popularity: 367.6, imdb_id: "tt1" }), "trending")).toBe("1. [Hope (2026)](<https://www.imdb.com/title/tt1/>) — 6.9 · 🔥368");
+        expect(entryLine(entry(2, { title: "Masterplan", imdb_rating: null, popularity: 222 }), "trending")).toBe("2. [Masterplan (2026)](<https://www.imdb.com/title/tt1002/>) — 🔥222");
+        expect(entryLine(entry(3, { title: "A*B_[x]", year: null, imdb_id: null }), "search")).toBe("3. A\\*B\\_\\[x\\] — 7.1");
+        expect(entryLine(entry(4, { imdb_rating: null }), "search")).toBe("4. [Title 4 (2026)](<https://www.imdb.com/title/tt1004/>)");
+    });
+
+    it("puts an Add, In library, or No IMDb ID button beside each entry", () => {
+        expect(entryButton("movie", entry(1))).toEqual({ type: 2, style: 1, label: "Add", custom_id: "media:add:movie:tt1001:1" });
+        expect(entryButton("series", entry(2, { in_library: null }))).toMatchObject({ label: "Add", custom_id: "media:add:series:tt1002:2" });
+        expect(entryButton("movie", entry(3, { in_library: true }))).toMatchObject({ label: "In library", disabled: true, custom_id: "media:lib:movie:tt1003:3" });
+        expect(entryButton("movie", entry(4, { imdb_id: null }))).toMatchObject({ label: "No IMDb ID", disabled: true });
+        expect(entryButton("movie", entry(5, { imdb_id: "nm123" }))).toMatchObject({ label: "No IMDb ID", disabled: true });
+    });
+
+    it("builds one message per list within Discord's limits", () => {
+        const many = Array.from({ length: 14 }, (_, i) => entry(i + 1));
+        const message = listMessage("movie", many, "trending", undefined, ["Radarr unreachable — in_library unknown"]);
+        expect(message[0]).toEqual({ type: 10, content: "**🎬 Movies** · trending this week" });
+        expect(message.filter((c) => c.type === 9)).toHaveLength(LIST_ENTRIES);
+        expect(countComponents(message)).toBe(1 + LIST_ENTRIES * 3 + 1);
+        expect(countComponents(message)).toBeLessThanOrEqual(40);
+        expect(message.at(-1)).toEqual({ type: 10, content: "-# ⚠️ Radarr unreachable — in_library unknown" });
+        const ids = message.flatMap((c) => (c.accessory?.custom_id ? [c.accessory.custom_id] : []));
+        expect(new Set(ids).size).toBe(ids.length);
+        expect(ids.every((id) => id.length <= 100)).toBe(true);
+        expect(listMessage("series", [], "search", "x_y", [])).toEqual([{ type: 10, content: "**📺 Series** · search “x\\_y”" }, { type: 10, content: "_none_" }]);
+        expect(IS_COMPONENTS_V2).toBe(32768);
+    });
+});
+
+describe("media add buttons", () => {
+    const message: MessageComponent[] = [
+        { type: 10, id: 1, content: "**🎬 Movies** · trending this week" },
+        { type: 9, id: 2, components: [{ type: 10, id: 3, content: "1. Hope" }], accessory: { type: 2, id: 4, style: 1, label: "Add", custom_id: "media:add:movie:tt1:1" } },
+        { type: 9, id: 5, components: [{ type: 10, id: 6, content: "2. Other" }], accessory: { type: 2, id: 7, style: 1, label: "Add", custom_id: "media:add:movie:tt2:2" } },
+    ];
+
+    it("parses only Add buttons", () => {
+        expect(parseAddButton("media:add:movie:tt1:1")).toEqual({ kind: "movie", imdbId: "tt1" });
+        expect(parseAddButton("media:add:series:tt0903747:10")).toEqual({ kind: "series", imdbId: "tt0903747" });
+        expect(parseAddButton("media:done:movie:tt1:1")).toBeNull();
+        expect(parseAddButton("media:add:movie:tt1;rm:1")).toBeNull();
+        expect(parseAddButton("media:add:music:tt1:1")).toBeNull();
+    });
+
+    it("turns each add result into a button state and a private note", () => {
+        const report = (status: string, paused: boolean | null = false, detail: string | null = null) => ({ results: [{ imdb_id: "tt1", title: "Hope", status, detail }], sabnzbd_paused: paused });
+        expect(addOutcome(report("added"), "movie", "tt1")).toEqual({ label: "Added", style: 3, disabled: true });
+        expect(addOutcome(report("added", true), "movie", "tt1").note).toMatch(/downloads are paused/);
+        expect(addOutcome(report("already_exists"), "movie", "tt1")).toEqual({ label: "In library", style: 2, disabled: true });
+        expect(addOutcome(report("not_found"), "series", "tt1")).toMatchObject({ label: "Not found", disabled: true, note: expect.stringMatching(/Sonarr/) });
+        expect(addOutcome(report("error", false, "quality profile missing"), "movie", "tt1")).toMatchObject({ label: "Retry", disabled: false, note: "Not added: quality profile missing." });
+        expect(addOutcome({ results: [], sabnzbd_paused: null }, "movie", "tt1")).toMatchObject({ label: "Retry", disabled: false, note: "Not added: no result for this ID." });
+        expect(addOutcome(null, "movie", "tt1", "media: secret RADARR_API_KEY for media is missing")).toMatchObject({ label: "Retry", disabled: false, note: expect.stringMatching(/RADARR_API_KEY/) });
+    });
+
+    it("replaces only the clicked button and keeps component ids", () => {
+        expect(hasActiveButton(message, "media:add:movie:tt1:1")).toBe(true);
+        const next = applyOutcome(message, "media:add:movie:tt1:1", { label: "Added", style: 3, disabled: true });
+        expect(next[1].accessory).toEqual({ type: 2, id: 4, style: 3, label: "Added", custom_id: "media:done:movie:tt1:1", disabled: true });
+        expect(next[2]).toEqual(message[2]);
+        expect(next[0]).toEqual(message[0]);
+        expect(hasActiveButton(next, "media:add:movie:tt1:1")).toBe(false);
+        expect(hasActiveButton(next, "media:add:movie:tt2:2")).toBe(true);
+        const retry = applyOutcome(message, "media:add:movie:tt2:2", { label: "Retry", style: 4, disabled: false });
+        expect(retry[2].accessory).toMatchObject({ label: "Retry", custom_id: "media:add:movie:tt2:2", disabled: false });
+        expect(hasActiveButton(retry, "media:add:movie:tt2:2")).toBe(true);
+        expect(message[1].accessory?.label).toBe("Add");
+    });
+});
+
+describe("media access", () => {
+    const config = validateConfig(
+        {
+            applicationId: OWNER,
+            guildId: OWNER,
+            channels: { [ADMIN_CHANNEL]: { trigger: "always", specialists: "*" }, [MEDIA_CHANNEL]: { trigger: "always", specialists: ["media"] }, [OTHER_CHANNEL]: { trigger: "always", specialists: ["arcane"] } },
+            adminChannelId: ADMIN_CHANNEL,
+            owners: [OWNER],
+            access: { media: [FRIEND] },
+            approvalTimeoutMinutes: 30,
+        },
+        [],
+    )!;
+    const names = ["arcane", "media"];
+
+    it("answers owners and access.media users in channels with the media specialist", () => {
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], names, OWNER)).toBe("ok");
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], names, FRIEND)).toBe("ok");
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], names, STRANGER)).toBe("user");
+        expect(mediaAccess(config, config.channels[OTHER_CHANNEL], names, OWNER)).toBe("channel");
+        expect(mediaAccess(config, null, names, OWNER)).toBe("channel");
+        expect(mediaAccess(config, config.channels[MEDIA_CHANNEL], ["arcane"], OWNER)).toBe("channel");
+        expect(mediaPointer(config, names)).toBe(`Media commands answer in <#${ADMIN_CHANNEL}>, <#${MEDIA_CHANNEL}>.`);
+        expect(mediaPointer(config, ["arcane"])).toBe("No channel has the media specialist yet.");
+    });
+
+    it("mentions the slash commands in help where media may be used", () => {
+        expect(helpText(["media"], ["media"], false, "always", false)).toContain("/trending");
+        expect(helpText(["arcane"], ["arcane"], true, "always", false)).not.toContain("/trending");
+    });
+});
+
+describe("keyed queue", () => {
+    it("runs tasks of one key in order and keeps going after a failure", async () => {
+        const queue = new KeyedQueue();
+        const order: string[] = [];
+        let release: () => void = () => undefined;
+        const gate = new Promise<void>((resolve) => {
+            release = resolve;
+        });
+        const first = queue.run("m1", async () => {
+            await gate;
+            order.push("first");
+            throw new Error("boom");
+        });
+        const second = queue.run("m1", async () => {
+            order.push("second");
+        });
+        const other = queue.run("m2", async () => {
+            order.push("other");
+        });
+        await other;
+        expect(order).toEqual(["other"]);
+        release();
+        await expect(first).rejects.toThrow("boom");
+        await second;
+        expect(order).toEqual(["other", "first", "second"]);
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(queue.size).toBe(0);
+    });
+});
+
+describe("media rest calls", () => {
+    it("defers, edits the original response, follows up, and registers commands", async () => {
+        const calls: { url: string; init: RequestInit }[] = [];
+        const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+            calls.push({ url: String(url), init: init ?? {} });
+            return new Response(JSON.stringify({ id: "m1", channel_id: "c1" }), { status: 200 });
+        }) as unknown as typeof fetch;
+        const rest = new DiscordRest("tok", fetchImpl);
+        await rest.deferReply("i1", "t1");
+        await rest.deferUpdate("i2", "t2");
+        await rest.editOriginal("app", "t1", { content: null, flags: IS_COMPONENTS_V2, components: [{ type: 10, content: "x" }] });
+        await rest.followUp("app", "t1", { content: "note", flags: 64 });
+        await rest.overwriteGlobalCommands("app", MEDIA_COMMANDS);
+        expect(calls.map((c) => `${c.init.method} ${c.url}`)).toEqual([
+            "POST https://discord.com/api/v10/interactions/i1/t1/callback",
+            "POST https://discord.com/api/v10/interactions/i2/t2/callback",
+            "PATCH https://discord.com/api/v10/webhooks/app/t1/messages/@original",
+            "POST https://discord.com/api/v10/webhooks/app/t1",
+            "PUT https://discord.com/api/v10/applications/app/commands",
+        ]);
+        expect(JSON.parse(calls[0].init.body as string)).toEqual({ type: 5 });
+        expect(JSON.parse(calls[1].init.body as string)).toEqual({ type: 6 });
+        expect(JSON.parse(calls[2].init.body as string)).toEqual({ content: null, flags: 32768, components: [{ type: 10, content: "x" }], allowed_mentions: { parse: [] } });
+        expect(JSON.parse(calls[3].init.body as string)).toEqual({ content: "note", flags: 64, allowed_mentions: { parse: [] } });
+        expect((JSON.parse(calls[4].init.body as string) as { name: string }[]).map((c) => c.name)).toEqual(["trending", "search", "downloads"]);
+    });
+});