@astrofoundry/pi-astro 0.30.0 → 0.32.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.
+- 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/discord.test.ts

@@ -7,7 +7,7 @@ import { chunkMessage, fenceState } from "./chunk.ts";
 import { applyAdminCommand, describeConfig } from "./admin.ts";
 import { helpText, needsPrefixText, parseCommand } from "./commands.ts";
 import { allowedSpecialists, canUse, channelSpecialists, loadConfig, loadToken, validateConfig } from "./config.ts";
-import { INTENTS, initialState, reduce } from "./gateway.ts";
+import { GatewayClient, INTENTS, initialState, reduce } from "./gateway.ts";
 import type { RunResult } from "../astro-subagents/child.ts";
 import { failureReply } from "./index.ts";
 import { DiscordRest } from "./rest.ts";
@@ -181,6 +181,85 @@ describe("gateway reducer", () => {
     });
 });
 
+class FakeSocket {
+    readyState = 1;
+    sent: { op: number; d?: unknown }[] = [];
+    closedWith: number | null = null;
+    private readonly listeners = new Map<string, ((event: unknown) => void)[]>();
+    addEventListener(type: string, fn: (event: unknown) => void): void {
+        this.listeners.set(type, [...(this.listeners.get(type) ?? []), fn]);
+    }
+    send(data: string): void {
+        this.sent.push(JSON.parse(data) as { op: number; d?: unknown });
+    }
+    close(code: number): void {
+        this.closedWith = code;
+    }
+    emit(payload: object): void {
+        for (const fn of this.listeners.get("message") ?? []) fn({ data: JSON.stringify(payload) });
+    }
+    emitClose(code: number): void {
+        this.readyState = 3;
+        for (const fn of this.listeners.get("close") ?? []) fn({ code, reason: "" });
+    }
+}
+
+describe("gateway client", () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+
+    function client() {
+        const sockets: FakeSocket[] = [];
+        const log = vi.fn();
+        const gateway = new GatewayClient({
+            token: "t",
+            gatewayUrl: "wss://gateway",
+            handlers: { dispatch: vi.fn(), log },
+            socketFactory: () => {
+                const socket = new FakeSocket();
+                sockets.push(socket);
+                return socket as unknown as WebSocket;
+            },
+        });
+        return { gateway, sockets, log };
+    }
+
+    it("opens exactly one new connection after a reconnect request, and the replaced socket's close changes nothing", () => {
+        const { gateway, sockets, log } = client();
+        gateway.start();
+        sockets[0].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        sockets[0].emit({ op: 0, t: "READY", s: 1, d: { session_id: "s1", resume_gateway_url: "wss://resume" } });
+        sockets[0].emit({ op: 7 });
+        expect(sockets[0].closedWith).toBe(4000);
+        sockets[0].emitClose(4000);
+        vi.advanceTimersByTime(5_000);
+        expect(sockets).toHaveLength(2);
+
+        sockets[1].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        expect(sockets[1].sent.at(-1)).toMatchObject({ op: 6, d: { session_id: "s1", seq: 1 } });
+        sockets[0].emitClose(1000);
+        sockets[0].emit({ op: 7 });
+        vi.advanceTimersByTime(1_000);
+        expect(sockets).toHaveLength(2);
+        expect(sockets[1].sent.at(-1)).toEqual({ op: 1, d: 1 });
+        expect(log).not.toHaveBeenCalledWith("gateway closed (1000); reconnecting");
+        gateway.stop();
+    });
+
+    it("reconnects and resumes once when the server closes the current socket", () => {
+        const { gateway, sockets } = client();
+        gateway.start();
+        sockets[0].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        sockets[0].emit({ op: 0, t: "READY", s: 3, d: { session_id: "s1", resume_gateway_url: "wss://resume" } });
+        sockets[0].emitClose(1000);
+        vi.advanceTimersByTime(5_000);
+        expect(sockets).toHaveLength(2);
+        sockets[1].emit({ op: 10, d: { heartbeat_interval: 1000 } });
+        expect(sockets[1].sent.at(-1)).toMatchObject({ op: 6, d: { session_id: "s1", seq: 3 } });
+        gateway.stop();
+    });
+});
+
 describe("rest", () => {
     it("sends JSON messages, multipart attachments, and retries once after 429", async () => {
         const calls: { url: string; init: RequestInit }[] = [];

package/extensions/astro-discord/gateway.ts

@@ -137,6 +137,7 @@ export class GatewayClient {
         const socket = factory(this.url(resume));
         this.socket = socket;
         socket.addEventListener("message", (event: MessageEvent) => {
+            if (this.socket !== socket) return;
             let payload: GatewayPayload;
             try {
                 payload = JSON.parse(String(event.data)) as GatewayPayload;
@@ -146,6 +147,9 @@ export class GatewayClient {
             this.act(reduce(this.state, payload, this.options.handlers));
         });
         socket.addEventListener("close", (event: CloseEvent) => {
+            // A socket already replaced by a reconnect must not stop the new one's heartbeat or start another connection.
+            if (this.socket !== socket) return;
+            this.socket = null;
             this.clearHeartbeat();
             if (this.stopped) return;
             if (FATAL_CLOSE_CODES.has(event.code)) {
@@ -186,12 +190,15 @@ export class GatewayClient {
             case "heartbeat-now":
                 this.send({ op: 1, d: this.state.seq });
                 break;
-            case "reconnect":
+            case "reconnect": {
+                const old = this.socket;
+                this.socket = null;
                 this.clearHeartbeat();
-                this.socket?.close(4000);
+                old?.close(4000);
                 if (!action.resume) this.state.sessionId = null;
                 this.scheduleReconnect(action.resume);
                 break;
+            }
             default:
                 break;
         }

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/);