@astrofoundry/pi-astro 0.21.2 → 0.22.0

package/extensions/astro-discord/setup.ts

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup for the Discord bridge. Run on the host that will hold
+ * the bot, as the user that runs Pi:
+ *   node --disable-warning=ExperimentalWarning <package>/extensions/astro-discord/setup.ts
+ * Prompts for the bot token and Discord ids, checks each against the API,
+ * writes ~/.config/astro-discord/{token,config.json} (0600), the LaunchAgent,
+ * and prints the commands to start it. Imports nothing from Pi on purpose.
+ */
+import { execFileSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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 { DiscordRest } from "./rest.ts";
+
+const LABEL = "com.astrofoundry.astro-discord";
+const SNOWFLAKE = /^\d{17,20}$/;
+
+class MutableOutput extends Writable {
+    muted = false;
+    _write(chunk: Buffer, _encoding: BufferEncoding, callback: () => void): void {
+        if (!this.muted) process.stdout.write(chunk);
+        callback();
+    }
+}
+
+async function main(): Promise<void> {
+    const output = new MutableOutput();
+    const rl = createInterface({ input: process.stdin, output, terminal: true });
+    const ask = async (question: string, hidden = false): Promise<string> => {
+        output.muted = false;
+        process.stdout.write(question);
+        output.muted = hidden;
+        const answer = await rl.question("");
+        output.muted = false;
+        if (hidden) process.stdout.write("\n");
+        return answer.trim();
+    };
+    const askIds = async (question: string, min: number): Promise<string[]> => {
+        for (;;) {
+            const ids = (await ask(question)).split(/[\s,]+/).filter(Boolean);
+            if (ids.length >= min && ids.every((id) => SNOWFLAKE.test(id))) return ids;
+            console.log(`  need ${min === 0 ? "" : "at least one "}Discord id${min > 1 ? "s" : ""} (17 to 20 digits, comma separated)`);
+        }
+    };
+
+    console.log("astro-discord setup. Nothing is written before every value has been checked.\n");
+    const existing = existsSync(tokenPath()) ? readFileSync(tokenPath(), "utf-8").trim() : "";
+    let token = await ask(existing ? "Bot token (Enter keeps the stored one): " : "Bot token (Developer Portal, Bot, Reset Token): ", true);
+    if (token.length === 0 && existing) token = existing;
+    const rest = new DiscordRest(token);
+    const me = await rest.currentUser();
+    console.log(`  token ok: bot ${me.username} (${me.id})`);
+
+    let applicationId: string;
+    for (;;) {
+        applicationId = await ask("Application ID (General Information): ");
+        if (SNOWFLAKE.test(applicationId)) break;
+        console.log("  not a Discord id");
+    }
+
+    let guildId: string;
+    for (;;) {
+        guildId = (await askIds("Server ID (right-click the server, Copy Server ID): ", 1))[0];
+        try {
+            const guild = (await (await fetch(`https://discord.com/api/v10/guilds/${guildId}`, { headers: { Authorization: `Bot ${token}` } })).json()) as { name?: string; message?: string };
+            if (guild.name) {
+                console.log(`  server ok: ${guild.name}`);
+                break;
+            }
+            console.log(`  Discord says: ${guild.message ?? "unknown server"}; is the bot invited there?`);
+        } catch (err) {
+            console.log(`  check failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+
+    let channelIds: string[];
+    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;
+            }
+        }
+        if (ok) {
+            console.log(`  channels ok: ${names.join(", ")}`);
+            break;
+        }
+    }
+
+    const owners = await askIds("Owner user ID(s), may use every specialist and approve risky calls: ", 1);
+    for (const id of owners) {
+        const user = (await (await fetch(`https://discord.com/api/v10/users/${id}`, { headers: { Authorization: `Bot ${token}` } })).json()) as { username?: string };
+        console.log(`  owner ${id}: ${user.username ?? "unknown user"}`);
+    }
+
+    const access: Record<string, string[]> = {};
+    console.log("Extra users per specialist (Enter on an empty specialist name to finish):");
+    for (;;) {
+        const name = await ask("  specialist name (dns, edge, ...): ");
+        if (name.length === 0) break;
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            console.log("  lowercase name only");
+            continue;
+        }
+        access[name] = await askIds(`  user id(s) allowed to use ${name}: `, 1);
+    }
+
+    let timeout = 30;
+    const timeoutAnswer = await ask("Approval timeout in minutes [30]: ");
+    if (timeoutAnswer.length > 0) timeout = Number(timeoutAnswer);
+
+    const errors: string[] = [];
+    const config = validateConfig({ applicationId, guildId, channelIds, owners, access, approvalTimeoutMinutes: timeout }, errors);
+    if (!config) {
+        console.error(`invalid configuration: ${errors.join("; ")}`);
+        process.exit(2);
+    }
+
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    chmodSync(configDir(), 0o700);
+    writeFileSync(tokenPath(), `${token}\n`, { mode: 0o600 });
+    chmodSync(tokenPath(), 0o600);
+    writeFileSync(configPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(configPath(), 0o600);
+
+    const pi = execFileSync("/bin/sh", ["-c", "command -v pi"], { encoding: "utf-8", env: { ...process.env, PATH: `${process.env.PATH ?? ""}:/opt/homebrew/bin:${homedir()}/.local/bin` } }).trim();
+    const runScript = join(configDir(), "run.sh");
+    const logFile = join(homedir(), "Library", "Logs", "astro-discord.log");
+    writeFileSync(
+        runScript,
+        `#!/bin/sh\n# Headless Pi host for the Discord bridge. Pi's RPC mode exits when stdin closes, so a pipe keeps it open.\nexport PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/bin:/bin"\nexport ASTRO_DISCORD=1\ncd "$HOME"\ntail -f /dev/null | exec ${pi} --mode rpc --no-session\n`,
+        { mode: 0o700 },
+    );
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array><string>/bin/sh</string><string>${runScript}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${logFile}</string>
+  <key>StandardErrorPath</key><string>${logFile}</string>
+</dict>
+</plist>
+`;
+    const plistPath = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+    mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+    writeFileSync(plistPath, plist, { mode: 0o644 });
+    rl.close();
+
+    console.log(`\nwrote ${tokenPath()}, ${configPath()}, ${runScript}, ${plistPath}`);
+    console.log("Start or restart the bridge:");
+    console.log(`  launchctl bootout gui/$(id -u)/${LABEL} 2>/dev/null; launchctl bootstrap gui/$(id -u) ${plistPath}`);
+    console.log(`Log: tail -f ${logFile}`);
+    console.log(`In Discord, in one of the channels: help`);
+}
+
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/extensions/astro-subagents/child.ts

@@ -64,9 +64,10 @@ export function childRemaining(parentRemaining: number, agent: AgentConfig): num
     return agent.maxSubagentDepth === undefined ? inherited : Math.min(inherited, agent.maxSubagentDepth);
 }
 
-export function composeSystemPrompt(agent: AgentConfig, skills: ResolvedSkill[]): string {
+export function composeSystemPrompt(agent: AgentConfig, skills: ResolvedSkill[], extra?: string): string {
     const parts = [agent.systemPrompt];
     for (const skill of skills) parts.push(`## Skill: ${skill.name}\n\n${skill.body}`);
+    if (extra) parts.push(extra);
     return parts.filter((p) => p.length > 0).join("\n\n");
 }
 
@@ -177,6 +178,10 @@ export interface RunOptions {
     signal?: AbortSignal;
     onUpdate?: (result: RunResult) => void;
     invocation?: (args: string[]) => Invocation;
+    /** Extra variables for the child process, for example an approval endpoint. */
+    env?: Record<string, string>;
+    /** Text appended to the system prompt, for example channel rules. */
+    extraSystemPrompt?: string;
 }
 
 export async function runAgent(options: RunOptions): Promise<RunResult> {
@@ -192,7 +197,7 @@ export async function runAgent(options: RunOptions): Promise<RunResult> {
         model: agent.model ?? options.defaults.model,
         step: options.step,
     };
-    const prompt = composeSystemPrompt(agent, options.skills);
+    const prompt = composeSystemPrompt(agent, options.skills, options.extraSystemPrompt);
     let tmpDir: string | null = null;
     let promptFile: string | null = null;
     if (prompt.length > 0) {
@@ -203,7 +208,7 @@ export async function runAgent(options: RunOptions): Promise<RunResult> {
     try {
         const args = buildChildArgs({ agent, task, promptFile, defaults: options.defaults });
         const invocation = (options.invocation ?? piInvocation)(args);
-        const env = buildChildEnv(agent, options.depth, options.remaining);
+        const env = buildChildEnv(agent, options.depth, options.remaining, { ...process.env, ...options.env });
         let aborted = false;
         const exitCode = await new Promise<number>((resolve) => {
             // Own process group so a kill reaches the child's own tool processes, not only pi itself.

package/extensions/specialist-gate/approvals.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from "vitest";
+import { isRisky, requestApproval } from "./index.ts";
+
+describe("approvals", () => {
+    it("marks interrupting and destructive calls as risky", () => {
+        expect(isRisky("edge", ["vps", "reboot", "--confirm"])).toBe(true);
+        expect(isRisky("edge", ["vps", "status"])).toBe(false);
+        expect(isRisky("edge", ["vps", "deploy-nginx"])).toBe(true);
+        expect(isRisky("dns", ["technitium", "primary", "zones"])).toBe(false);
+        expect(isRisky("dns", ["technitium", "primary", "record-delete", "z", "d", "A", "ipAddress=1.1.1.1"])).toBe(true);
+        expect(isRisky("dns", ["cloudflare", "record-add", "37pla.net", "{}"])).toBe(true);
+        expect(isRisky("identity", ["zitadel", "GET", "/v2/users"])).toBe(false);
+        expect(isRisky("identity", ["zitadel", "DELETE", "/v2/users/1"])).toBe(true);
+        expect(isRisky("identity", ["dmz", "deploy-config"])).toBe(true);
+        expect(isRisky("arcane", ["projects", "list"])).toBe(false);
+        expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(true);
+        expect(isRisky("arcane", ["gitops", "sync", "arcane", "--yes"])).toBe(true);
+        expect(isRisky("proxmox", ["guests"])).toBe(false);
+        expect(isRisky("proxmox", ["set", "107", "memory=768"])).toBe(true);
+        expect(isRisky("proxmox", ["shutdown", "107", "--confirm"])).toBe(true);
+        expect(isRisky("security", ["decisions"])).toBe(false);
+        expect(isRisky("inference", ["hermes-restart", "api"])).toBe(true);
+        expect(isRisky("backup", ["restic-snapshots"])).toBe(false);
+        expect(isRisky("backup", ["vzdump-run", "107"])).toBe(true);
+    });
+
+    it("creates a ticket and polls until decided", async () => {
+        const seen: string[] = [];
+        let polls = 0;
+        const fetchImpl = vi.fn(async (url: string | URL | Request, init?: RequestInit) => {
+            seen.push(`${init?.method ?? "GET"} ${String(url)}`);
+            if (init?.method === "POST") {
+                expect(JSON.parse(init.body as string)).toEqual({ agent: "astro.edge", service: "edge", args: ["vps", "reboot", "--confirm"] });
+                return new Response(JSON.stringify({ id: "t1" }), { status: 201 });
+            }
+            polls++;
+            return new Response(JSON.stringify({ id: "t1", decision: polls < 3 ? null : "deny" }), { status: 200 });
+        }) as unknown as typeof fetch;
+        const decision = await requestApproval("http://127.0.0.1:1", "tok", { agent: "astro.edge", service: "edge", args: ["vps", "reboot", "--confirm"] }, undefined, 5, fetchImpl);
+        expect(decision).toBe("deny");
+        expect(seen[0]).toBe("POST http://127.0.0.1:1/approvals");
+        expect(seen[1]).toBe("GET http://127.0.0.1:1/approvals/t1");
+        expect(polls).toBe(3);
+        const failing = vi.fn(async () => new Response("no", { status: 500 })) as unknown as typeof fetch;
+        await expect(requestApproval("http://127.0.0.1:1", "tok", { agent: "a", service: "s", args: [] }, undefined, 5, failing)).rejects.toThrow(/500/);
+    });
+});

package/extensions/specialist-gate/index.ts

@@ -10,6 +10,83 @@ export const CHILD_AGENT_ENV = AGENT_ENV;
 const DEFAULT_USER = "specialist";
 const FIXED_COMMAND_MARKERS = ["specialist-cli", "arcane-cli"];
 
+/** Set by a chat bridge (astro-discord) on the specialist child: where to ask an operator before a risky call. */
+export const APPROVAL_URL_ENV = "ASTRO_APPROVAL_URL";
+export const APPROVAL_TOKEN_ENV = "ASTRO_APPROVAL_TOKEN";
+
+/**
+ * Calls that interrupt a service, delete data, or change live configuration.
+ * Anything carrying `--confirm` is risky by construction; these patterns add
+ * the writes that do not need `--confirm` in a terminal session.
+ */
+export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
+    arcane: [
+        /^(projects|stacks)\s+(up|down|redeploy|restart|stop|delete|remove|rm|destroy|upgrade)\b/,
+        /^containers\s+(stop|restart|kill|remove|rm|delete)\b/,
+        /^(images|volumes|networks)\s+(prune|remove|rm|delete)\b/,
+        /^system\s+(prune|upgrade)\b/,
+        /^gitops\s+(sync|delete|update|import)\b/,
+    ],
+    identity: [/^zitadel\s+(DELETE|POST|PUT|PATCH)\b/, /^dmz\s+(deploy-config|pomerium-restart|render|lego-renew)\b/],
+    network: [/^unifi\s+policy-(create|update|delete)\b/],
+    dns: [/^technitium\s+primary\s+(zone-create|zone-delete|record-add|record-update|record-delete)\b/, /^cloudflare\s+record-(add|update|delete)\b/],
+    edge: [/^vps\s+deploy-nginx\b/],
+    backup: [/^(vzdump-run|host-backup-run|arcane-backup-run|gcs-run|restic-check-run|restic-restore|restore-clean)\b/],
+    proxmox: [/^(set|snapshot-create|start)\b/],
+    inference: [/^(nexus-restart|nexus-start|hermes-restart)\b/],
+};
+
+export function isRisky(service: string, args: readonly string[]): boolean {
+    if (args.includes("--confirm")) return true;
+    const joined = args.join(" ");
+    return (RISKY[service] ?? []).some((pattern) => pattern.test(joined));
+}
+
+export type Decision = "approve" | "deny" | "timeout";
+
+export interface ApprovalRequest {
+    agent: string;
+    service: string;
+    args: readonly string[];
+}
+
+interface Ticket {
+    id?: unknown;
+}
+
+interface TicketState {
+    decision?: unknown;
+}
+
+/**
+ * Asks the bridge for an operator decision: POST creates a ticket, then the
+ * ticket is polled until it is decided. Polling keeps every HTTP call short.
+ */
+export async function requestApproval(url: string, token: string, request: ApprovalRequest, signal?: AbortSignal, pollMs = 5000, fetchImpl: typeof fetch = fetch): Promise<Decision> {
+    const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    const created = await fetchImpl(`${url}/approvals`, { method: "POST", headers, body: JSON.stringify(request), signal });
+    if (!created.ok) throw new Error(`approval endpoint answered ${created.status}`);
+    const ticket = (await created.json()) as Ticket;
+    if (typeof ticket.id !== "string") throw new Error("approval endpoint returned no ticket id");
+    for (;;) {
+        await new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(resolve, pollMs);
+            signal?.addEventListener(
+                "abort",
+                () => {
+                    clearTimeout(timer);
+                    reject(new Error("aborted while waiting for approval"));
+                },
+                { once: true },
+            );
+        });
+        const response = await fetchImpl(`${url}/approvals/${ticket.id}`, { headers, signal });
+        if (!response.ok) throw new Error(`approval endpoint answered ${response.status}`);
+        const state = (await response.json()) as TicketState;
+        if (state.decision === "approve" || state.decision === "deny" || state.decision === "timeout") return state.decision;
+    }
+}
+
 export interface Guard {
     user: string;
     commandMarkers: string[];
@@ -103,6 +180,13 @@ function registerSpecialistTool(pi: ExtensionAPI, config: SpecialistsConfig, ent
         ],
         parameters: params,
         async execute(_toolCallId, input, signal) {
+            const approvalUrl = process.env[APPROVAL_URL_ENV];
+            if (approvalUrl && isRisky(entry.service, input.args)) {
+                const decision = await requestApproval(approvalUrl, process.env[APPROVAL_TOKEN_ENV] ?? "", { agent: entry.agent, service: entry.service, args: input.args }, signal);
+                if (decision !== "approve") {
+                    throw new Error(`${entry.service}: the operator ${decision === "deny" ? "denied" : "did not answer the approval request for"} \`${input.args.join(" ")}\`. Report this and stop.`);
+                }
+            }
             const result = await pi.exec("sudo", entryArgs(config, entry, input.args), {
                 signal,
                 timeout: entry.timeoutMs,

package/package.json

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

package/specialists/AGENTS.md

@@ -67,6 +67,10 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 6. Host: note fields, `provision`, config file, `specialists.json` entry, target entry script. Document the fields in the homelab `03-cortex-macmini/ROTATION.md` and host facts in `03-cortex-macmini/README.md`.
 7. README in this folder: table row and setup step; root `README.md`: the agent and skill lists.
 
+## Chat bridges
+
+`extensions/astro-discord/` runs specialists for Discord messages through `runAgent` and passes `ASTRO_APPROVAL_URL`/`ASTRO_APPROVAL_TOKEN` to the child. The gate consults `RISKY` in `extensions/specialist-gate/index.ts` and blocks on a ticket until an owner decides; keep `RISKY` in step with the wrappers when a new interrupting or destructive command appears (every `--confirm` command is covered by construction).
+
 ## Next
 
-All nine specialists exist; `network` writes firewall policies and `identity` deploys Pomerium routes. Open: Europa scheduled-task control for `inference` (needs Europa on to test Windows OpenSSH forced commands), then Discord access to the specialists, then the Astrogate route.
+All nine specialists exist; `network` writes firewall policies, `identity` deploys Pomerium routes, and Discord access is live. Open: Europa scheduled-task control for `inference` (needs Europa on to test Windows OpenSSH forced commands), then the Astrogate route.

package/specialists/README.md

@@ -101,6 +101,16 @@ Host: Cortex (macOS, Homebrew `node`, `bw`, `jq`, `gcloud-cli` with `python@3.14
 
 Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller test -- projects list` prints JSON; the same for `identity -- dmz status`, `network -- unifi sites`, `dns -- technitium primary zones`, `edge -- vps status`, `security -- attention`, `backup -- vzdump-tasks`, `proxmox -- guests`, `inference -- nexus-status`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session.
 
+## Discord
+
+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.
+- 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`: `node --disable-warning=ExperimentalWarning ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/setup.ts` 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.
+
 ## Rotation and operations
 
 Rotation steps for every field live in the homelab repository, `03-cortex-macmini/ROTATION.md`. After any change in Vaultwarden run `specialist-cli provision`. Host state and the sudo rules are documented in `03-cortex-macmini/README.md`; the forced-command scripts are tracked under `02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`, `02-pulsar-proxmox/observability/system/`, `02-pulsar-proxmox/hermes/system/`, `host/` of the `astronaute77/arcane` repository, `04-nexus-macstudio/system/`, and `00-frontdoor-vps/system/`.