@astrofoundry/pi-astro 0.22.3 → 0.23.0

package/extensions/astro-discord/admin.ts

@@ -0,0 +1,77 @@
+import { type ChannelSettings, type DiscordConfig, SNOWFLAKE, SPECIALIST } from "./config.ts";
+
+export interface AdminResult {
+    reply: string;
+    /** Present when the command changed the configuration. */
+    config?: DiscordConfig;
+}
+
+const USAGE = [
+    "config show",
+    "config channel <#channel> <always|mention> <*|name,name>",
+    "config channel <#channel> remove",
+    "config access <specialist> add|remove <@user>",
+].join("\n");
+
+function idOf(token: string | undefined, kind: "channel" | "user"): string | null {
+    if (token === undefined) return null;
+    const match = kind === "channel" ? /^<#(\d{17,20})>$/.exec(token) : /^<@!?(\d{17,20})>$/.exec(token);
+    const id = match ? match[1] : token;
+    return SNOWFLAKE.test(id) ? id : null;
+}
+
+export function describeConfig(config: DiscordConfig): string {
+    const channels = Object.entries(config.channels).map(([id, c]) => `• <#${id}>: ${c.trigger}, ${c.specialists === "*" ? "every specialist" : c.specialists.join(", ")}${id === config.adminChannelId ? " (admin)" : ""}`);
+    const access = Object.entries(config.access)
+        .filter(([, ids]) => ids.length > 0)
+        .map(([name, ids]) => `• ${name}: ${ids.map((id) => `<@${id}>`).join(", ")}`);
+    return [
+        "Channels:",
+        ...channels,
+        `Owners: ${config.owners.map((id) => `<@${id}>`).join(", ")}`,
+        access.length > 0 ? "Extra access:" : "Extra access: none",
+        ...access,
+        `Approval timeout: ${config.approvalTimeoutMinutes} min`,
+    ].join("\n");
+}
+
+/** Applies one owner `config` command to a copy of the configuration. */
+export function applyAdminCommand(config: DiscordConfig, args: readonly string[], configured: readonly string[]): AdminResult {
+    const [verb, ...rest] = args;
+    if (verb === undefined || verb === "show") return { reply: describeConfig(config) };
+    if (verb === "channel") {
+        const channelId = idOf(rest[0], "channel");
+        if (!channelId) return { reply: `channel id missing.\n${USAGE}` };
+        if (rest[1] === "remove") {
+            if (!(channelId in config.channels)) return { reply: `<#${channelId}> is not configured.` };
+            if (channelId === config.adminChannelId) return { reply: "The admin channel cannot be removed." };
+            const channels = { ...config.channels };
+            delete channels[channelId];
+            return { reply: `Removed <#${channelId}>.`, config: { ...config, channels } };
+        }
+        if (rest[1] !== "always" && rest[1] !== "mention") return { reply: `trigger must be always or mention.\n${USAGE}` };
+        const names = rest[2] === "*" ? "*" : (rest[2] ?? "").split(",").map((n) => n.trim()).filter(Boolean);
+        if (names !== "*") {
+            if (names.length === 0) return { reply: `specialists missing.\n${USAGE}` };
+            const unknown = names.filter((n) => !SPECIALIST.test(n) || !configured.includes(n));
+            if (unknown.length > 0) return { reply: `unknown specialist(s): ${unknown.join(", ")}. Configured: ${configured.join(", ")}.` };
+        }
+        const settings: ChannelSettings = { trigger: rest[1], specialists: names === "*" ? "*" : [...new Set(names)] };
+        const verbNow = channelId in config.channels ? "Updated" : "Added";
+        return {
+            reply: `${verbNow} <#${channelId}>: ${settings.trigger}, ${settings.specialists === "*" ? "every specialist" : settings.specialists.join(", ")}.`,
+            config: { ...config, channels: { ...config.channels, [channelId]: settings } },
+        };
+    }
+    if (verb === "access") {
+        const [name, action, who] = rest;
+        if (name === undefined || !configured.includes(name)) return { reply: `unknown specialist. Configured: ${configured.join(", ")}.` };
+        const userId = idOf(who, "user");
+        if ((action !== "add" && action !== "remove") || !userId) return { reply: USAGE };
+        const current = config.access[name] ?? [];
+        const next = action === "add" ? [...new Set([...current, userId])] : current.filter((id) => id !== userId);
+        if (next.length === current.length) return { reply: action === "add" ? `<@${userId}> already has ${name}.` : `<@${userId}> did not have ${name}.` };
+        return { reply: `${action === "add" ? "Granted" : "Revoked"} ${name} for <@${userId}>.`, config: { ...config, access: { ...config.access, [name]: next } } };
+    }
+    return { reply: USAGE };
+}

package/extensions/astro-discord/commands.ts

@@ -1,22 +1,46 @@
-export type Command = { kind: "run"; specialist: string; task: string } | { kind: "help" } | { kind: "status" } | { kind: "none" };
+import type { Trigger } from "./config.ts";
+
+export type Command =
+    | { kind: "run"; specialist: string; task: string }
+    | { kind: "help" }
+    | { kind: "status" }
+    | { kind: "config"; args: string[] }
+    | { kind: "needs-prefix"; specialists: string[] }
+    | { kind: "none" };
+
+export interface CommandContext {
+    botUserId: string;
+    /** Specialists present in this channel that the host has configured. */
+    specialists: readonly string[];
+    trigger: Trigger;
+    /** True when the message replies to one of the bot's messages. */
+    repliedToBot: boolean;
+}
 
 /**
- * `<specialist> <task>` or `@bot <specialist> <task>` in a watched channel.
- * `help` lists what the sender may use; `status` shows running tasks.
+ * Interprets one channel message. `mention` channels react only when addressed
+ * (bot mention or a reply to the bot). A channel with one specialist needs no
+ * prefix; with several, an addressed message without a prefix asks for one.
  */
-export function parseCommand(content: string, botUserId: string, specialists: readonly string[]): Command {
-    let text = content.trim().replace(new RegExp(`^<@!?${botUserId}>\\s*`), "");
-    text = text.replace(/^[!/]/, "");
-    if (text.length === 0) return { kind: "none" };
+export function parseCommand(content: string, context: CommandContext): Command {
+    const mention = new RegExp(`^<@!?${context.botUserId}>\\s*`);
+    const addressed = mention.test(content.trim()) || context.repliedToBot;
+    const text = content.trim().replace(mention, "").replace(/^[!/]/, "").trim();
+    if (context.trigger === "mention" && !addressed) return { kind: "none" };
+    if (text.length === 0) return addressed ? { kind: "help" } : { kind: "none" };
     const [first, ...rest] = text.split(/\s+/);
     const word = first.toLowerCase();
     if (word === "help") return { kind: "help" };
     if (word === "status") return { kind: "status" };
-    const specialist = word.replace(/^astro\./, "");
-    if (!specialists.includes(specialist)) return { kind: "none" };
-    const task = text.slice(first.length).trim();
-    if (task.length === 0) return { kind: "none" };
-    return { kind: "run", specialist, task: rest.length > 0 ? task : "" };
+    if (word === "config") return { kind: "config", args: rest };
+    const named = word.replace(/^astro\./, "");
+    if (context.specialists.includes(named)) {
+        const task = text.slice(first.length).trim();
+        return task.length > 0 ? { kind: "run", specialist: named, task } : { kind: "help" };
+    }
+    if (context.specialists.length === 1) return { kind: "run", specialist: context.specialists[0], task: text };
+    if (addressed) return { kind: "needs-prefix", specialists: [...context.specialists] };
+    return { kind: "none" };
 }
 
 /** Prompt paragraph appended for tasks that arrive from a chat channel. */
@@ -24,13 +48,16 @@ export const CHANNEL_RULES = `## Channel rules
 
 This task arrived from a Discord channel and your answer is posted there. Answer in plain text under 1500 characters when possible, facts first, no headings. When the task is ambiguous (which guest, which record, which host), do not act: ask one precise question and stop. Risky calls may wait for an operator's approval; if the tool reports a denial or a missing answer, report it and stop.`;
 
-export function helpText(allowed: readonly string[], isOwner: boolean): string {
-    if (allowed.length === 0) return "You may not use any specialist here.";
-    const lines = [
-        "Send `<specialist> <task>` in this channel. Specialists you may use:",
-        ...allowed.map((name) => `• \`${name}\``),
-        "React ⏳ means running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `status` lists running tasks.",
-    ];
+export function helpText(allowed: readonly string[], present: readonly string[], isOwner: boolean, trigger: Trigger): string {
+    if (allowed.length === 0) return present.length === 0 ? "No specialist is present in this channel." : "You may not use the specialists present in this channel.";
+    const how = present.length === 1 ? `Every message${trigger === "mention" ? " that addresses me" : ""} here goes to \`${present[0]}\`.` : `Send \`<specialist> <task>\`${trigger === "mention" ? " after mentioning me" : ""}. Specialists you may use here:`;
+    const lines = [how];
+    if (present.length > 1) lines.push(...allowed.map((name) => `• \`${name}\``));
+    lines.push("Reactions: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `status` lists running tasks.");
     if (isOwner) lines.push("Owners approve risky calls with the buttons the bot posts and may use every specialist.");
     return lines.join("\n");
 }
+
+export function needsPrefixText(specialists: readonly string[]): string {
+    return `Several specialists live here; start your message with one of: ${specialists.map((s) => `\`${s}\``).join(", ")}.`;
+}

package/extensions/astro-discord/config.ts

@@ -1,15 +1,26 @@
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 /** Set to "1" on the headless Pi host that should connect to Discord. */
 export const ACTIVATION_ENV = "ASTRO_DISCORD";
 
+export type Trigger = "always" | "mention";
+
+export interface ChannelSettings {
+    /** `always`: every message that names a specialist (or any message when one specialist is present); `mention`: only when addressed. */
+    trigger: Trigger;
+    /** Specialists available in this channel: every configured one, or a list of short names. */
+    specialists: "*" | string[];
+}
+
 export interface DiscordConfig {
     applicationId: string;
     guildId: string;
-    /** Channels the bot reads; messages elsewhere are ignored. */
-    channelIds: string[];
+    /** Channels the bot reads, by id; messages elsewhere are ignored. Threads inherit their parent's entry. */
+    channels: Record<string, ChannelSettings>;
+    /** The one channel where owners may run `config` commands. */
+    adminChannelId: string;
     /** Users who may use every specialist and decide approvals. */
     owners: string[];
     /** Extra users per specialist name (without the astro. prefix). */
@@ -17,8 +28,8 @@ export interface DiscordConfig {
     approvalTimeoutMinutes: number;
 }
 
-const SNOWFLAKE = /^\d{17,20}$/;
-const SPECIALIST = /^[a-z][a-z0-9-]*$/;
+export const SNOWFLAKE = /^\d{17,20}$/;
+export const SPECIALIST = /^[a-z][a-z0-9-]*$/;
 
 export function configDir(): string {
     return process.env.ASTRO_DISCORD_DIR ?? join(homedir(), ".config", "astro-discord");
@@ -54,7 +65,18 @@ export function validateConfig(raw: unknown, errors: string[]): DiscordConfig |
     for (const key of ["applicationId", "guildId"]) {
         if (typeof r[key] !== "string" || !SNOWFLAKE.test(r[key] as string)) errors.push(`${key} must be a Discord id`);
     }
-    const channelIds = snowflakes(r.channelIds, "channelIds", errors);
+    const channels: Record<string, ChannelSettings> = {};
+    if (typeof r.channels !== "object" || r.channels === null || Array.isArray(r.channels) || Object.keys(r.channels).length === 0) {
+        errors.push("channels must be a non-empty object of channel id to settings");
+    } else {
+        for (const [id, raw] of Object.entries(r.channels as Record<string, unknown>)) {
+            if (!SNOWFLAKE.test(id)) errors.push(`channels: ${id} is not a Discord id`);
+            const settings = validateChannel(raw, `channels.${id}`, errors);
+            if (settings) channels[id] = settings;
+        }
+    }
+    if (typeof r.adminChannelId !== "string" || !SNOWFLAKE.test(r.adminChannelId)) errors.push("adminChannelId must be a Discord id");
+    else if (!(r.adminChannelId in channels) && errors.length === 0) errors.push("adminChannelId must be one of the configured channels");
     const owners = snowflakes(r.owners, "owners", errors);
     const access: Record<string, string[]> = {};
     if (r.access !== undefined) {
@@ -69,7 +91,44 @@ export function validateConfig(raw: unknown, errors: string[]): DiscordConfig |
     const timeout = r.approvalTimeoutMinutes;
     if (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout < 1 || timeout > 240) errors.push("approvalTimeoutMinutes must be an integer from 1 to 240");
     if (errors.length > 0) return null;
-    return { applicationId: r.applicationId as string, guildId: r.guildId as string, channelIds, owners, access, approvalTimeoutMinutes: timeout as number };
+    return {
+        applicationId: r.applicationId as string,
+        guildId: r.guildId as string,
+        channels,
+        adminChannelId: r.adminChannelId as string,
+        owners,
+        access,
+        approvalTimeoutMinutes: timeout as number,
+    };
+}
+
+export function validateChannel(raw: unknown, where: string, errors: string[]): ChannelSettings | null {
+    if (typeof raw !== "object" || raw === null) {
+        errors.push(`${where} must be an object`);
+        return null;
+    }
+    const r = raw as Record<string, unknown>;
+    if (r.trigger !== "always" && r.trigger !== "mention") errors.push(`${where}.trigger must be always or mention`);
+    let specialists: "*" | string[] = "*";
+    if (r.specialists !== "*") {
+        if (!Array.isArray(r.specialists) || r.specialists.length === 0 || !r.specialists.every((n) => typeof n === "string" && SPECIALIST.test(n))) {
+            errors.push(`${where}.specialists must be "*" or a non-empty list of specialist names`);
+        } else specialists = [...new Set(r.specialists as string[])];
+    }
+    return errors.length > 0 ? null : { trigger: r.trigger as Trigger, specialists };
+}
+
+/** Writes the configuration back atomically with owner-only permissions. */
+export function saveConfig(config: DiscordConfig): void {
+    const path = configPath();
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+
+/** Specialists present in a channel, intersected with the ones configured on this host. */
+export function channelSpecialists(settings: ChannelSettings, configured: readonly string[]): string[] {
+    return settings.specialists === "*" ? [...configured] : settings.specialists.filter((name) => configured.includes(name));
 }
 
 export function loadConfig(): { config: DiscordConfig | null; errors: string[] } {
@@ -102,7 +161,7 @@ export function canUse(config: DiscordConfig, userId: string, specialist: string
     return isOwner(config, userId) || (config.access[specialist] ?? []).includes(userId);
 }
 
-/** Specialists a user may address, from the runtime list of `astro.*` agents. */
+/** Specialists a user may address among those present, from the runtime list of `astro.*` agents. */
 export function allowedSpecialists(config: DiscordConfig, userId: string, available: readonly string[]): string[] {
     return available.filter((name) => canUse(config, userId, name));
 }

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

@@ -4,15 +4,18 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ApprovalServer, type Ticket } from "./approvals.ts";
 import { chunkMessage, fenceState } from "./chunk.ts";
-import { helpText, parseCommand } from "./commands.ts";
-import { allowedSpecialists, canUse, loadConfig, loadToken, validateConfig } from "./config.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 type { RunResult } from "../astro-subagents/child.ts";
+import { failureReply } from "./index.ts";
 import { DiscordRest } from "./rest.ts";
 
 const ID = "123456789012345678";
 const OTHER = "223456789012345678";
 const THIRD = "323456789012345678";
-const valid = { applicationId: ID, guildId: ID, channelIds: [ID], owners: [ID], access: { dns: [OTHER] }, approvalTimeoutMinutes: 30 };
+const valid = { applicationId: ID, guildId: ID, channels: { [ID]: { trigger: "always", specialists: "*" }, [OTHER]: { trigger: "mention", specialists: ["arcane"] } }, adminChannelId: ID, owners: [ID], access: { dns: [OTHER] }, approvalTimeoutMinutes: 30 };
 
 describe("config", () => {
     it("validates ids and shapes", () => {
@@ -20,7 +23,11 @@ describe("config", () => {
         expect(validateConfig(valid, errors)).toEqual(valid);
         expect(errors).toEqual([]);
         expect(validateConfig({ ...valid, guildId: "abc" }, errors)).toBeNull();
-        expect(validateConfig({ ...valid, channelIds: [] }, [])).toBeNull();
+        expect(validateConfig({ ...valid, channels: {} }, [])).toBeNull();
+        expect(validateConfig({ ...valid, channels: { [ID]: { trigger: "sometimes", specialists: "*" } } }, [])).toBeNull();
+        expect(validateConfig({ ...valid, adminChannelId: THIRD }, [])).toBeNull();
+        expect(channelSpecialists({ trigger: "always", specialists: "*" }, ["dns", "edge"])).toEqual(["dns", "edge"]);
+        expect(channelSpecialists({ trigger: "always", specialists: ["edge", "nope"] }, ["dns", "edge"])).toEqual(["edge"]);
         expect(validateConfig({ ...valid, access: { "Bad Name": [ID] } }, [])).toBeNull();
         expect(validateConfig({ ...valid, approvalTimeoutMinutes: 0 }, [])).toBeNull();
         expect(validateConfig({ ...valid, access: undefined }, [])).toMatchObject({ access: {} });
@@ -79,22 +86,67 @@ describe("chunk", () => {
 });
 
 describe("commands", () => {
-    const specialists = ["dns", "edge"];
-    it("parses specialist tasks, mentions, help, and status", () => {
-        expect(parseCommand("dns list the zones", ID, specialists)).toEqual({ kind: "run", specialist: "dns", task: "list the zones" });
-        expect(parseCommand(`<@${ID}> edge probe the front door`, ID, specialists)).toEqual({ kind: "run", specialist: "edge", task: "probe the front door" });
-        expect(parseCommand("!astro.dns zones", ID, specialists)).toEqual({ kind: "run", specialist: "dns", task: "zones" });
-        expect(parseCommand("help", ID, specialists)).toEqual({ kind: "help" });
-        expect(parseCommand("Status", ID, specialists)).toEqual({ kind: "status" });
-        expect(parseCommand("dns", ID, specialists)).toEqual({ kind: "none" });
-        expect(parseCommand("hello everyone", ID, specialists)).toEqual({ kind: "none" });
-        expect(parseCommand("", ID, specialists)).toEqual({ kind: "none" });
+    const many = { botUserId: ID, specialists: ["dns", "edge"], trigger: "always" as const, repliedToBot: false };
+    const one = { ...many, specialists: ["arcane"] };
+    it("parses prefixed tasks, mentions, help, status, and config", () => {
+        expect(parseCommand("dns list the zones", many)).toEqual({ kind: "run", specialist: "dns", task: "list the zones" });
+        expect(parseCommand(`<@${ID}> edge probe the front door`, many)).toEqual({ kind: "run", specialist: "edge", task: "probe the front door" });
+        expect(parseCommand("!astro.dns zones", many)).toEqual({ kind: "run", specialist: "dns", task: "zones" });
+        expect(parseCommand("help", many)).toEqual({ kind: "help" });
+        expect(parseCommand("Status", many)).toEqual({ kind: "status" });
+        expect(parseCommand("config channel <#1> mention dns", many)).toEqual({ kind: "config", args: ["channel", "<#1>", "mention", "dns"] });
+        expect(parseCommand("dns", many)).toEqual({ kind: "help" });
+        expect(parseCommand("hello everyone", many)).toEqual({ kind: "none" });
+        expect(parseCommand("", many)).toEqual({ kind: "none" });
     });
 
-    it("lists what a user may use", () => {
-        expect(helpText([], false)).toMatch(/may not/);
-        expect(helpText(["dns"], true)).toMatch(/`dns`/);
-        expect(helpText(["dns"], true)).toMatch(/Owners approve/);
+    it("needs no prefix with one specialist and asks for one when addressed with several", () => {
+        expect(parseCommand("list the projects", one)).toEqual({ kind: "run", specialist: "arcane", task: "list the projects" });
+        expect(parseCommand("arcane list the projects", one)).toEqual({ kind: "run", specialist: "arcane", task: "list the projects" });
+        expect(parseCommand(`<@${ID}> list the zones`, many)).toEqual({ kind: "needs-prefix", specialists: ["dns", "edge"] });
+        expect(parseCommand("list the zones", { ...many, repliedToBot: true })).toEqual({ kind: "needs-prefix", specialists: ["dns", "edge"] });
+        expect(parseCommand(`<@${ID}>`, many)).toEqual({ kind: "help" });
+    });
+
+    it("stays silent in mention channels unless addressed", () => {
+        const mention = { ...many, trigger: "mention" as const };
+        expect(parseCommand("dns list the zones", mention)).toEqual({ kind: "none" });
+        expect(parseCommand(`<@${ID}> dns list the zones`, mention)).toEqual({ kind: "run", specialist: "dns", task: "list the zones" });
+        expect(parseCommand("dns list the zones", { ...mention, repliedToBot: true })).toEqual({ kind: "run", specialist: "dns", task: "list the zones" });
+        expect(parseCommand("anything", { ...one, trigger: "mention" })).toEqual({ kind: "none" });
+        expect(parseCommand(`<@${ID}> anything`, { ...one, trigger: "mention" })).toEqual({ kind: "run", specialist: "arcane", task: "anything" });
+    });
+
+    it("writes help and prefix texts", () => {
+        expect(helpText([], [], false, "always")).toMatch(/No specialist/);
+        expect(helpText([], ["dns"], false, "always")).toMatch(/may not/);
+        expect(helpText(["arcane"], ["arcane"], false, "mention")).toMatch(/addresses me here goes to `arcane`/);
+        expect(helpText(["dns"], ["dns", "edge"], true, "always")).toMatch(/`dns`/);
+        expect(needsPrefixText(["dns", "edge"])).toMatch(/`dns`, `edge`/);
+    });
+});
+
+describe("admin commands", () => {
+    const config = validateConfig(valid, [])!;
+    const configured = ["dns", "edge", "arcane"];
+    it("shows, adds, updates, removes channels and grants access", () => {
+        expect(applyAdminCommand(config, ["show"], configured).reply).toContain(`<#${ID}>: always, every specialist (admin)`);
+        expect(describeConfig(config)).toContain(`dns: <@${OTHER}>`);
+        const added = applyAdminCommand(config, ["channel", `<#${THIRD}>`, "mention", "dns,edge"], configured);
+        expect(added.config?.channels[THIRD]).toEqual({ trigger: "mention", specialists: ["dns", "edge"] });
+        expect(added.reply).toMatch(/^Added/);
+        const updated = applyAdminCommand(added.config!, ["channel", THIRD, "always", "*"], configured);
+        expect(updated.config?.channels[THIRD]).toEqual({ trigger: "always", specialists: "*" });
+        expect(updated.reply).toMatch(/^Updated/);
+        expect(applyAdminCommand(config, ["channel", `<#${THIRD}>`, "mention", "nope"], configured).reply).toMatch(/unknown specialist/);
+        expect(applyAdminCommand(config, ["channel", `<#${ID}>`, "remove"], configured)).toEqual({ reply: "The admin channel cannot be removed." });
+        expect(applyAdminCommand(updated.config!, ["channel", `<#${THIRD}>`, "remove"], configured).config?.channels[THIRD]).toBeUndefined();
+        const granted = applyAdminCommand(config, ["access", "edge", "add", `<@${THIRD}>`], configured);
+        expect(granted.config?.access.edge).toEqual([THIRD]);
+        expect(applyAdminCommand(granted.config!, ["access", "edge", "add", THIRD], configured).config).toBeUndefined();
+        expect(applyAdminCommand(granted.config!, ["access", "edge", "remove", THIRD], configured).config?.access.edge).toEqual([]);
+        expect(applyAdminCommand(config, ["access", "nope", "add", THIRD], configured).reply).toMatch(/unknown specialist/);
+        expect(applyAdminCommand(config, ["bogus"], configured).reply).toMatch(/config show/);
     });
 });
 
@@ -147,6 +199,17 @@ describe("rest", () => {
     });
 });
 
+describe("failure reply", () => {
+    it("names the reason and keeps stderr as an attachment", () => {
+        const base: RunResult = { agent: "astro.dns", agentSource: "bundled", task: "t", exitCode: 1, messages: [], stderr: "", usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 } };
+        expect(failureReply({ ...base, errorMessage: "timed out after 30 min" })).toEqual({ text: "timed out after 30 min" });
+        expect(failureReply({ ...base, stderr: "noise\n" })).toEqual({ text: "the specialist process exited with code 1", attachment: "noise" });
+        expect(failureReply({ ...base, stopReason: "aborted" as RunResult["stopReason"] }).text).toBe("the run was stopped");
+        const withWords = failureReply({ ...base, messages: [{ role: "assistant", content: [{ type: "text", text: "I asked for approval." }] } as never] });
+        expect(withWords.text).toContain("Last words of the specialist:\nI asked for approval.");
+    });
+});
+
 describe("approval server", () => {
     it("creates tickets, reports decisions, expires, and rejects bad tokens", async () => {
         const tickets: Ticket[] = [];

package/extensions/astro-discord/index.ts

@@ -2,17 +2,52 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { loadConfig as loadSpecialists } from "../specialist-gate/config.ts";
 import { APPROVAL_TOKEN_ENV, APPROVAL_URL_ENV } from "../specialist-gate/index.ts";
 import { type AgentConfig, defaultDirs, discoverAgents, resolveSkills } from "../astro-subagents/agents.ts";
-import { type DispatchDefaults, childRemaining, currentDepth, isFailed, resultOutput, runAgent } from "../astro-subagents/child.ts";
+import { AGENT_ENV, type DispatchDefaults, type RunResult, childRemaining, currentDepth, finalOutput, isFailed, runAgent } from "../astro-subagents/child.ts";
 import { ApprovalServer, type Ticket } from "./approvals.ts";
 import { chunkMessage } from "./chunk.ts";
-import { CHANNEL_RULES, helpText, parseCommand } from "./commands.ts";
-import { ACTIVATION_ENV, type DiscordConfig, allowedSpecialists, canUse, isOwner, loadConfig, loadToken } from "./config.ts";
+import { applyAdminCommand } from "./admin.ts";
+import { CHANNEL_RULES, helpText, needsPrefixText, parseCommand } from "./commands.ts";
+import { ACTIVATION_ENV, type ChannelSettings, type DiscordConfig, allowedSpecialists, canUse, channelSpecialists, isOwner, loadConfig, loadToken, saveConfig } from "./config.ts";
 import { GatewayClient } from "./gateway.ts";
 import { DiscordRest, type MessageComponent } from "./rest.ts";
 
 const REACTION = { running: "⏳", waiting: "🔒", done: "✅", failed: "❌" } as const;
 /** Answers longer than this go as a file attachment with a short summary. */
 const ATTACHMENT_THRESHOLD = 6000;
+/** Upper bound for one specialist run started from chat; the wrappers' own timeouts are shorter. */
+const TASK_TIMEOUT_MINUTES = 30;
+
+interface ToolCallPart {
+    type?: string;
+    name?: string;
+    arguments?: unknown;
+}
+
+/** One log line per new message: tool calls with their arguments, tool results, and assistant text lengths. */
+function describeProgress(result: RunResult, seen: number): { lines: string[]; seen: number } {
+    const lines: string[] = [];
+    for (const message of result.messages.slice(seen)) {
+        if (message.role === "assistant") {
+            for (const part of message.content as ToolCallPart[]) {
+                if (part.type === "toolCall") lines.push(`tool ${part.name ?? "?"} ${JSON.stringify(part.arguments ?? {}).slice(0, 300)}`);
+                else if (part.type === "text") lines.push(`assistant text ${((part as { text?: string }).text ?? "").length} chars`);
+            }
+        } else if (message.role === "toolResult") {
+            const { toolName, isError } = message as { toolName?: string; isError?: boolean };
+            lines.push(`result ${toolName ?? "?"}${isError ? " (error)" : ""}`);
+        }
+    }
+    return { lines, seen: result.messages.length };
+}
+
+/** Reply for a failed run: the reason in one line, the specialist's last words if any, raw stderr only as an attachment. */
+export function failureReply(result: RunResult): { text: string; attachment?: string } {
+    const reason = result.errorMessage?.trim() || (result.stopReason === "aborted" ? "the run was stopped" : `the specialist process exited with code ${result.exitCode}`);
+    const lastWords = finalOutput(result.messages).trim();
+    const text = lastWords.length > 0 ? `${reason}\n\nLast words of the specialist:\n${lastWords}` : reason;
+    const stderr = result.stderr.trim();
+    return stderr.length > 0 ? { text, attachment: stderr } : { text };
+}
 
 interface IncomingMessage {
     id: string;
@@ -20,6 +55,7 @@ interface IncomingMessage {
     guild_id?: string;
     content?: string;
     author?: { id: string; bot?: boolean };
+    referenced_message?: { author?: { id: string } } | null;
 }
 
 interface ComponentInteraction {
@@ -70,6 +106,8 @@ class Bridge {
     private readonly approvalMessages = new Map<string, { channelId: string; messageId: string; userMessage: ActiveTask }>();
     private config: DiscordConfig;
     private botUserId = "";
+    /** Thread id to parent channel id; null marks a plain channel. */
+    private readonly parents = new Map<string, string | null>();
     private readonly ctx: ExtensionContext;
     private readonly token: string;
 
@@ -108,7 +146,7 @@ class Bridge {
             },
         });
         gateway.start();
-        log(`connected as ${me.username} (${me.id}); channels ${this.config.channelIds.join(", ")}; specialists ${this.specialists().names.join(", ")}`);
+        log(`connected as ${me.username} (${me.id}); channels ${Object.keys(this.config.channels).join(", ")}; specialists ${this.specialists().names.join(", ")}`);
     }
 
     private async dispatch(event: string, data: unknown): Promise<void> {
@@ -120,17 +158,54 @@ class Bridge {
         }
     }
 
+    /** Settings for a channel or, for a thread, of its parent channel; null when neither is configured. */
+    private async settingsFor(channelId: string): Promise<{ id: string; settings: ChannelSettings } | null> {
+        const direct = this.config.channels[channelId];
+        if (direct) return { id: channelId, settings: direct };
+        if (!this.parents.has(channelId)) {
+            try {
+                const channel = (await this.rest.channel(channelId)) as { parent_id?: string | null };
+                this.parents.set(channelId, channel.parent_id ?? null);
+            } catch {
+                this.parents.set(channelId, null);
+            }
+        }
+        const parent = this.parents.get(channelId);
+        const inherited = parent ? this.config.channels[parent] : undefined;
+        return parent && inherited ? { id: parent, settings: inherited } : null;
+    }
+
     private async onMessage(message: IncomingMessage): Promise<void> {
-        if (!message.author || message.author.bot || !this.config.channelIds.includes(message.channel_id)) return;
+        if (!message.author || message.author.bot) return;
         this.refreshConfig();
+        const channel = await this.settingsFor(message.channel_id);
+        if (!channel) return;
         const { names, agents } = this.specialists();
-        const command = parseCommand(message.content ?? "", this.botUserId, names);
-        if (command.kind === "none") return;
+        const present = channelSpecialists(channel.settings, names);
         const userId = message.author.id;
-        const allowed = allowedSpecialists(this.config, userId, names);
+        const command = parseCommand(message.content ?? "", {
+            botUserId: this.botUserId,
+            specialists: present,
+            trigger: channel.settings.trigger,
+            repliedToBot: message.referenced_message?.author?.id === this.botUserId,
+        });
+        if (command.kind === "none") return;
+        const allowed = allowedSpecialists(this.config, userId, present);
+        const owner = isOwner(this.config, userId);
+        if (command.kind === "config") {
+            if (!owner || channel.id !== this.config.adminChannelId) return;
+            const result = applyAdminCommand(this.config, command.args, names);
+            if (result.config) {
+                saveConfig(result.config);
+                this.config = result.config;
+                log(`config changed by ${userId}: ${command.args.join(" ")}`);
+            }
+            await this.rest.createMessage(message.channel_id, { content: result.reply, replyTo: message.id });
+            return;
+        }
         if (allowed.length === 0) return;
         if (command.kind === "help") {
-            await this.rest.createMessage(message.channel_id, { content: helpText(allowed, isOwner(this.config, userId)), replyTo: message.id });
+            await this.rest.createMessage(message.channel_id, { content: helpText(allowed, present, owner, channel.settings.trigger), replyTo: message.id });
             return;
         }
         if (command.kind === "status") {
@@ -138,6 +213,10 @@ class Bridge {
             await this.rest.createMessage(message.channel_id, { content: lines.length > 0 ? lines.join("\n") : "Nothing is running.", replyTo: message.id });
             return;
         }
+        if (command.kind === "needs-prefix") {
+            await this.rest.createMessage(message.channel_id, { content: needsPrefixText(allowed), replyTo: message.id });
+            return;
+        }
         if (!canUse(this.config, userId, command.specialist)) return;
         const agent = agents.find((a) => a.name === `astro.${command.specialist}`);
         if (!agent) return;
@@ -162,21 +241,35 @@ class Bridge {
         const { depth, remaining } = currentDepth();
         let failed = true;
         let output: string;
+        let attachment: string | undefined;
+        let seen = 0;
         try {
             const result = await runAgent({
-                agent,
+                agent: { ...agent, timeoutMinutes: agent.timeoutMinutes ?? TASK_TIMEOUT_MINUTES },
                 skills,
                 task: taskText,
                 cwd: process.cwd(),
                 depth,
                 remaining: childRemaining(remaining, agent),
                 defaults,
-                env: { [APPROVAL_URL_ENV]: this.approvals.url, [APPROVAL_TOKEN_ENV]: this.approvals.token, ASTRO_CHANNEL: "discord" },
+                // The child must not become a second Discord bridge.
+                env: { [ACTIVATION_ENV]: "0", [APPROVAL_URL_ENV]: this.approvals.url, [APPROVAL_TOKEN_ENV]: this.approvals.token, ASTRO_CHANNEL: "discord" },
                 extraSystemPrompt: CHANNEL_RULES,
+                onUpdate: (partial) => {
+                    const progress = describeProgress(partial, seen);
+                    seen = progress.seen;
+                    for (const line of progress.lines) log(`astro.${task.specialist}: ${line}`);
+                },
             });
             failed = isFailed(result);
-            output = resultOutput(result);
-            log(`astro.${task.specialist} ${failed ? "failed" : "done"} in ${Math.round((Date.now() - task.startedAt) / 1000)} s, ${result.usage.turns} turns, cost ${result.usage.cost.toFixed(4)}`);
+            if (failed) {
+                const reply = failureReply(result);
+                output = reply.text;
+                attachment = reply.attachment;
+            } else {
+                output = finalOutput(result.messages) || "(no output)";
+            }
+            log(`astro.${task.specialist} ${failed ? "failed" : "done"} in ${Math.round((Date.now() - task.startedAt) / 1000)} s, ${result.usage.turns} turns, ${result.usage.input + result.usage.output} tokens`);
         } catch (err) {
             output = err instanceof Error ? err.message : String(err);
         } finally {
@@ -184,10 +277,14 @@ class Bridge {
         }
         await this.rest.removeOwnReaction(task.channelId, task.messageId, REACTION.running).catch(() => undefined);
         await this.rest.addReaction(task.channelId, task.messageId, failed ? REACTION.failed : REACTION.done).catch(() => undefined);
-        await this.post(task, `${failed ? "❌" : "✅"} **${task.specialist}**\n${output}`);
+        await this.post(task, `${failed ? "❌" : "✅"} **${task.specialist}**\n${output}`, attachment);
     }
 
-    private async post(task: ActiveTask, text: string): Promise<void> {
+    private async post(task: ActiveTask, text: string, attachment?: string): Promise<void> {
+        if (attachment !== undefined) {
+            await this.rest.createMessage(task.channelId, { content: text.slice(0, 1900), replyTo: task.messageId, file: { name: `astro-${task.specialist}-stderr-${Date.now()}.txt`, content: attachment } });
+            return;
+        }
         if (text.length > ATTACHMENT_THRESHOLD) {
             const summary = `${text.slice(0, 1200).trim()}\n… full answer attached (${text.length} characters).`;
             await this.rest.createMessage(task.channelId, { content: summary, replyTo: task.messageId, file: { name: `astro-${task.specialist}-${Date.now()}.md`, content: text } });
@@ -252,7 +349,7 @@ class Bridge {
  * the headless LaunchAgent host sets; interactive sessions never connect.
  */
 export default function astroDiscord(pi: ExtensionAPI): void {
-    if (process.env[ACTIVATION_ENV] !== "1") return;
+    if (process.env[ACTIVATION_ENV] !== "1" || process.env[AGENT_ENV]) return;
     pi.on("session_start", async (_event, ctx: ExtensionContext) => {
         const loaded = loadConfig();
         if (!loaded.config) {

package/extensions/astro-discord/setup.ts

@@ -13,7 +13,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
-import { configDir, configPath, tokenPath, validateConfig } from "./config.ts";
+import { type ChannelSettings, configDir, configPath, tokenPath, validateConfig } from "./config.ts";
 import { DiscordRest } from "./rest.ts";
 
 const LABEL = "com.astrofoundry.astro-discord";
@@ -78,26 +78,64 @@ async function main(): Promise<void> {
         }
     }
 
-    let channelIds: string[];
+    const channels: Record<string, ChannelSettings> = {};
+    console.log("Channels. For each: its id, then how the bot listens (always, or only when mentioned), then which specialists live there.");
     for (;;) {
-        channelIds = await askIds("Channel ID(s) the bot listens in, comma separated: ", 1);
-        const names: string[] = [];
-        let ok = true;
-        for (const id of channelIds) {
-            try {
-                const channel = await rest.channel(id);
-                if (channel.guild_id !== guildId) {
-                    console.log(`  channel ${id} is not in that server`);
-                    ok = false;
-                } else names.push(`#${channel.name ?? id}`);
-            } catch (err) {
-                console.log(`  channel ${id}: ${err instanceof Error ? err.message : String(err)}`);
-                ok = false;
+        const raw = await ask(Object.keys(channels).length === 0 ? "Channel ID: " : "Another channel ID (Enter to finish): ");
+        if (raw.length === 0) {
+            if (Object.keys(channels).length > 0) break;
+            console.log("  at least one channel is needed");
+            continue;
+        }
+        if (!SNOWFLAKE.test(raw)) {
+            console.log("  not a Discord id");
+            continue;
+        }
+        try {
+            const channel = await rest.channel(raw);
+            if (channel.guild_id !== guildId) {
+                console.log(`  channel ${raw} is not in that server`);
+                continue;
             }
+            console.log(`  channel ok: #${channel.name ?? raw}`);
+        } catch (err) {
+            console.log(`  channel ${raw}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
         }
-        if (ok) {
-            console.log(`  channels ok: ${names.join(", ")}`);
-            break;
+        let trigger: "always" | "mention" = "always";
+        for (;;) {
+            const answer = (await ask("  trigger, always or mention [always]: ")).toLowerCase();
+            if (answer === "" || answer === "always") break;
+            if (answer === "mention") {
+                trigger = "mention";
+                break;
+            }
+            console.log("  always or mention");
+        }
+        let specialists: "*" | string[] = "*";
+        for (;;) {
+            const answer = await ask("  specialists, * for all or comma separated names (dns,edge,...) [*]: ");
+            if (answer === "" || answer === "*") break;
+            const names = answer.split(/[\s,]+/).filter(Boolean);
+            if (names.every((n) => /^[a-z][a-z0-9-]*$/.test(n))) {
+                specialists = [...new Set(names)];
+                break;
+            }
+            console.log("  lowercase names only");
+        }
+        channels[raw] = { trigger, specialists };
+    }
+    const channelIds = Object.keys(channels);
+    let adminChannelId = channelIds[0];
+    if (channelIds.length > 1) {
+        for (;;) {
+            const answer = await ask(`Admin channel for config commands [${channelIds[0]}]: `);
+            if (answer.length === 0) break;
+            if (channelIds.includes(answer)) {
+                adminChannelId = answer;
+                break;
+            }
+            console.log("  must be one of the channels above");
         }
     }
 
@@ -124,7 +162,7 @@ async function main(): Promise<void> {
     if (timeoutAnswer.length > 0) timeout = Number(timeoutAnswer);
 
     const errors: string[] = [];
-    const config = validateConfig({ applicationId, guildId, channelIds, owners, access, approvalTimeoutMinutes: timeout }, errors);
+    const config = validateConfig({ applicationId, guildId, channels, adminChannelId, owners, access, approvalTimeoutMinutes: timeout }, errors);
     if (!config) {
         console.error(`invalid configuration: ${errors.join("; ")}`);
         process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/specialists/README.md

@@ -105,8 +105,8 @@ Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller t
 
 The `astro-discord` extension gives Discord users access to the specialists from a channel. It runs in a headless Pi host on Cortex (LaunchAgent `com.astrofoundry.astro-discord`, user `cortex`), never in interactive sessions.
 
-- In a configured channel, `dns list the zones` or `@Cortex edge probe the front door` runs the specialist and posts the answer as a reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` lists what you may use; `status` lists running tasks. Long answers arrive as a `.md` attachment.
-- Access: `owners` may use every specialist and decide approvals; `access.<specialist>` lists extra users for that specialist; everyone else gets no reply. Edit `~/.config/astro-discord/config.json` on Cortex; changes apply to the next message.
+- Channels are configured one by one (`channels.<id>`): `trigger` is `always` (every message that names a specialist counts) or `mention` (only messages that start with `@Cortex` or reply to the bot); `specialists` is `*` or a list. A channel with one specialist needs no prefix: every message there is a task for it. In a channel with several, `dns list the zones` names the specialist; an addressed message without a name gets a reply asking for one. Threads inherit their parent channel's entry; unlisted channels are ignored. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows what you may use in that channel; `status` lists running tasks. Long answers arrive as a `.md` attachment.
+- Access: `owners` may use every specialist and decide approvals; `access.<specialist>` lists extra users for that specialist; everyone else gets no reply. Owners change the configuration from the admin channel (`adminChannelId`) without a shell: `config show`, `config channel <#channel> <always|mention> <*|dns,edge>`, `config channel <#channel> remove`, `config access <specialist> add|remove <@user>`; the bot writes `~/.config/astro-discord/config.json` on Cortex, which is also editable by hand and re-read on every message. Deny the bot's role View Channel on channels it must never read; that is the boundary the map cannot provide.
 - Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, Pomerium deploys, Arcane redeploys, service restarts) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action.
 - Setup, as `cortex`: `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 does not strip types inside `node_modules`, so the files are copied first) prompts for the bot token and the ids, checks each against Discord, and writes `~/.config/astro-discord/{token,config.json,run.sh}` and the LaunchAgent; it prints the `launchctl bootstrap` line. After a pi-astro update restart the bridge with `launchctl kickstart -k gui/$(id -u)/com.astrofoundry.astro-discord`. Log: `~/Library/Logs/astro-discord.log`.
 - Discord side: application `Cortex` with a bot, Message Content Intent enabled, invited with scopes `bot` and `applications.commands` and permissions View Channel, Send Messages, Attach Files, Read Message History, Add Reactions.