@astrofoundry/pi-astro 0.24.0 → 0.25.0

package/extensions/astro-discord/attachments.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { QuotedMessage } from "./quote.ts";
+
+/** An image on a Discord message, by its CDN url. */
+export interface ImageAttachment {
+    filename: string;
+    url: string;
+    contentType: string;
+    size: number;
+}
+
+export const MAX_IMAGES = 4;
+export const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+
+/** Image attachments of the message and of the messages it quotes, oldest quote first, within the count and size limits. */
+export function imageAttachments(messages: readonly QuotedMessage[]): ImageAttachment[] {
+    const images: ImageAttachment[] = [];
+    for (const message of messages) {
+        for (const a of message.attachments ?? []) {
+            if (!a.url || !a.content_type?.startsWith("image/") || (a.size ?? 0) > MAX_IMAGE_BYTES) continue;
+            images.push({ filename: a.filename, url: a.url, contentType: a.content_type, size: a.size ?? 0 });
+        }
+    }
+    return images.slice(0, MAX_IMAGES);
+}
+
+export interface DownloadedImages {
+    dir: string;
+    files: string[];
+    failed: string[];
+}
+
+/** Saves the images to a private temp directory, named by an index and a hash so filenames from Discord never reach the file system. */
+export async function downloadImages(images: readonly ImageAttachment[], fetchImpl: typeof fetch = fetch): Promise<DownloadedImages> {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "astro-discord-images-"));
+    const files: string[] = [];
+    const failed: string[] = [];
+    for (const [index, image] of images.entries()) {
+        try {
+            const response = await fetchImpl(image.url);
+            if (!response.ok) throw new Error(`HTTP ${response.status}`);
+            const bytes = Buffer.from(await response.arrayBuffer());
+            if (bytes.length > MAX_IMAGE_BYTES) throw new Error("larger than the limit");
+            const name = `${index + 1}-${createHash("sha256").update(image.url).digest("hex").slice(0, 12)}${path.extname(image.filename).toLowerCase().replace(/[^.a-z0-9]/g, "")}`;
+            const file = path.join(dir, name);
+            await fs.writeFile(file, bytes, { mode: 0o600 });
+            files.push(file);
+        } catch {
+            failed.push(image.filename);
+        }
+    }
+    return { dir, files, failed };
+}
+
+/** Task text telling the specialist which images travel with it and which could not be fetched. */
+export function describeImages(task: string, images: readonly ImageAttachment[], failed: readonly string[]): string {
+    const lines: string[] = [];
+    const fetched = images.filter((i) => !failed.includes(i.filename));
+    if (fetched.length > 0) lines.push(`Images attached to the message, included with this task: ${fetched.map((i) => i.filename).join(", ")}.`);
+    if (failed.length > 0) lines.push(`Images that could not be fetched: ${failed.join(", ")}.`);
+    return lines.length === 0 ? task : `${task}\n\n${lines.join("\n")}`;
+}

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

@@ -13,6 +13,7 @@ import { failureReply } from "./index.ts";
 import { DiscordRest } from "./rest.ts";
 import { CONVERSATION_IDLE_MS, CONVERSATION_MAX_AGE_MS, forgetStale, loadState, newConversationId, recordAnswer, resolveConversation, saveState, startConversation } from "./conversations.ts";
 import { quoteText, withQuotes } from "./quote.ts";
+import { MAX_IMAGE_BYTES, describeImages, downloadImages, imageAttachments } from "./attachments.ts";
 
 const ID = "123456789012345678";
 const OTHER = "223456789012345678";
@@ -289,3 +290,34 @@ describe("quotes", () => {
         expect(withQuotes("check this", [{ label: "Forwarded message", message: alert }])).toMatch(/^check this\n\nForwarded message:\nWazuh alert/);
     });
 });
+
+describe("image attachments", () => {
+    const png = { filename: "alert.png", url: "https://cdn.example/alert.png", content_type: "image/png", size: 1000 };
+    const image = { filename: png.filename, url: png.url, contentType: png.content_type, size: png.size };
+    it("keeps images within the limits, in message order", () => {
+        const big = { ...png, filename: "big.png", size: MAX_IMAGE_BYTES + 1 };
+        const text = { filename: "log.txt", url: "https://cdn.example/log.txt", content_type: "text/plain", size: 10 };
+        const many = Array.from({ length: 6 }, (_, i) => ({ ...png, filename: `${i}.png` }));
+        expect(imageAttachments([{ attachments: [text, big, png] }, { attachments: [{ ...png, filename: "quoted.jpg" }] }]).map((i) => i.filename)).toEqual(["alert.png", "quoted.jpg"]);
+        expect(imageAttachments([{ attachments: many }])).toHaveLength(4);
+        expect(imageAttachments([{}])).toEqual([]);
+    });
+
+    it("downloads to a private temp dir and reports failures", async () => {
+        const fetchImpl = vi.fn(async (url: string | URL | Request) => {
+            const u = String(url);
+            if (u.endsWith("missing.png")) return new Response("nope", { status: 404 });
+            return new Response(new Uint8Array([137, 80, 78, 71]), { status: 200 });
+        }) as unknown as typeof fetch;
+        const result = await downloadImages([image, { ...image, filename: "missing.png", url: "https://cdn.example/missing.png" }], fetchImpl);
+        try {
+            expect(result.files).toHaveLength(1);
+            expect(result.files[0]).toMatch(/\/1-[0-9a-f]{12}\.png$/);
+            expect(result.failed).toEqual(["missing.png"]);
+            expect(describeImages("check this", [image, { ...image, filename: "missing.png" }], result.failed)).toBe("check this\n\nImages attached to the message, included with this task: alert.png.\nImages that could not be fetched: missing.png.");
+            expect(describeImages("check this", [], [])).toBe("check this");
+        } finally {
+            rmSync(result.dir, { recursive: true, force: true });
+        }
+    });
+});

package/extensions/astro-discord/index.ts

@@ -1,3 +1,4 @@
+import { promises as fs } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig as loadSpecialists } from "../specialist-gate/config.ts";
 import { APPROVAL_TOKEN_ENV, APPROVAL_URL_ENV } from "../specialist-gate/index.ts";
@@ -10,6 +11,7 @@ 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 { type ConversationState, type ResolvedConversation, forgetStale, loadState, newConversationId, recordAnswer, resolveConversation, saveState, sessionsRoot, startConversation } from "./conversations.ts";
+import { describeImages, downloadImages, type ImageAttachment, imageAttachments } from "./attachments.ts";
 import { GatewayClient } from "./gateway.ts";
 import { type Quote, type QuotedMessage, withQuotes } from "./quote.ts";
 import { DiscordRest, type MessageComponent } from "./rest.ts";
@@ -58,6 +60,7 @@ interface IncomingMessage {
     guild_id?: string;
     content?: string;
     author?: { id: string; bot?: boolean };
+    attachments?: QuotedMessage["attachments"];
     /** The message this one replies to; Discord resolves it on every reply event. */
     referenced_message?: QuotedMessage | null;
     /** Copies of forwarded messages, without their authors. */
@@ -82,6 +85,7 @@ interface ActiveTask {
     userId: string;
     startedAt: number;
     conversation: ResolvedConversation;
+    images: ImageAttachment[];
 }
 
 function log(line: string): void {
@@ -238,8 +242,10 @@ class Bridge {
         );
         if (!conversation.resumed) this.conversations = startConversation(this.conversations, conversation.key, conversation.id, now);
         saveState(this.conversations);
-        const task: ActiveTask = { specialist: command.specialist, channelId: message.channel_id, messageId: message.id, userId, startedAt: now, conversation };
-        const taskText = withQuotes(command.task, this.quotesFor(message, conversation.resumed));
+        const quotes = this.quotesFor(message, conversation.resumed);
+        const images = imageAttachments([message, ...quotes.map((q) => q.message)]);
+        const task: ActiveTask = { specialist: command.specialist, channelId: message.channel_id, messageId: message.id, userId, startedAt: now, conversation, images };
+        const taskText = withQuotes(command.task, quotes);
         const previous = this.queues.get(command.specialist) ?? Promise.resolve();
         const next = previous.then(() => this.runTask(agent, taskText, task)).catch((err) => log(`run failed: ${err instanceof Error ? err.message : String(err)}`));
         this.queues.set(command.specialist, next);
@@ -273,6 +279,9 @@ class Bridge {
         log(`run astro.${task.specialist} for ${task.userId} (${task.conversation.resumed ? "continuing" : "new conversation"} ${task.conversation.id}): ${taskText.slice(0, 200)}`);
         const session: ChildSession = { dir: sessionDirFor(sessionsRoot(), task.specialist), id: task.conversation.id };
         pruneSessions(session.dir);
+        const images = task.images.length > 0 ? await downloadImages(task.images) : undefined;
+        if (images && images.failed.length > 0) log(`astro.${task.specialist}: could not fetch ${images.failed.join(", ")}`);
+        const prompt = images ? describeImages(taskText, task.images, images.failed) : taskText;
         const dirs = defaultDirs();
         const { skills, missing } = resolveSkills(agent.skills, dirs);
         if (missing.length > 0) log(`${agent.name}: skill(s) not found: ${missing.join(", ")}`);
@@ -289,7 +298,8 @@ class Bridge {
             const result = await runAgent({
                 agent: { ...agent, timeoutMinutes: agent.timeoutMinutes ?? TASK_TIMEOUT_MINUTES },
                 skills,
-                task: taskText,
+                task: prompt,
+                files: images?.files,
                 cwd: process.cwd(),
                 depth,
                 remaining: childRemaining(remaining, agent),
@@ -318,6 +328,7 @@ class Bridge {
         } finally {
             clearInterval(typing);
             this.active.delete(task.specialist);
+            if (images) await fs.rm(images.dir, { recursive: true, force: true }).catch(() => undefined);
         }
         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);

package/extensions/astro-discord/quote.ts

@@ -3,7 +3,7 @@ export interface QuotedMessage {
     id?: string;
     content?: string;
     embeds?: { title?: string; description?: string; fields?: { name: string; value: string }[]; footer?: { text: string }; author?: { name?: string } }[];
-    attachments?: { filename: string }[];
+    attachments?: { filename: string; url?: string; content_type?: string; size?: number }[];
     author?: { id: string; username?: string; bot?: boolean };
 }
 

package/extensions/astro-subagents/child.test.ts

@@ -62,6 +62,8 @@ describe("child arguments", () => {
         const exact = buildChildArgs({ agent: pinned, task: "t", promptFile: null, defaults: {}, session: { dir: "/s/x", id: "dns-1", continue: true } });
         expect(exact.slice(3, 7)).toEqual(["--session-dir", "/s/x", "--session-id", "dns-1"]);
         expect(exact).not.toContain("--continue");
+        const withFiles = buildChildArgs({ agent: pinned, task: "t", promptFile: null, defaults: {}, files: ["/tmp/a.png", "/tmp/b.png"] });
+        expect(withFiles.slice(-4)).toEqual(["--", "@/tmp/a.png", "@/tmp/b.png", "Task: t"]);
     });
 
     it("inlines skills after the agent prompt", () => {

package/extensions/astro-subagents/child.ts

@@ -88,10 +88,12 @@ export interface ChildArgsInput {
     promptFile: string | null;
     defaults: DispatchDefaults;
     session?: ChildSession;
+    /** Local files passed as `@file` prompt inputs; Pi attaches images by content type. */
+    files?: string[];
 }
 
 /** Arguments for the child `pi` process: print mode, JSON events, a session file only when asked. */
-export function buildChildArgs({ agent, task, promptFile, defaults, session }: ChildArgsInput): string[] {
+export function buildChildArgs({ agent, task, promptFile, defaults, session, files }: ChildArgsInput): string[] {
     const args = ["--mode", "json", "-p"];
     if (session) {
         args.push("--session-dir", session.dir);
@@ -106,7 +108,7 @@ export function buildChildArgs({ agent, task, promptFile, defaults, session }: C
     if (!agent.inheritProjectContext) args.push("--no-context-files");
     if (!agent.inheritSkills) args.push("--no-skills");
     if (promptFile) args.push(agent.systemPromptMode === "append" ? "--append-system-prompt" : "--system-prompt", promptFile);
-    args.push("--", `Task: ${task}`);
+    args.push("--", ...(files ?? []).map((file) => `@${file}`), `Task: ${task}`);
     return args;
 }
 
@@ -201,6 +203,8 @@ export interface RunOptions {
     extraSystemPrompt?: string;
     /** Saved conversation to continue or start; omitted for a one-off run. */
     session?: ChildSession;
+    /** Local files (images) attached to the task. */
+    files?: string[];
 }
 
 export async function runAgent(options: RunOptions): Promise<RunResult> {
@@ -226,7 +230,7 @@ export async function runAgent(options: RunOptions): Promise<RunResult> {
     }
     try {
         if (options.session) await fs.promises.mkdir(options.session.dir, { recursive: true, mode: 0o700 });
-        const args = buildChildArgs({ agent, task, promptFile, defaults: options.defaults, session: options.session });
+        const args = buildChildArgs({ agent, task, promptFile, defaults: options.defaults, session: options.session, files: options.files });
         const invocation = (options.invocation ?? piInvocation)(args);
         const env = buildChildEnv(agent, options.depth, options.remaining, { ...process.env, ...options.env });
         let aborted = false;

package/extensions/astro-subagents/index.test.ts

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { AgentDirs } from "./agents.ts";
 import { DEPTH_ENV, REMAINING_ENV } from "./child.ts";
-import astroSubagents, { parseRunCommand, pruneLegacyCopies } from "./index.ts";
+import astroSubagents, { parseRunCommand, pruneLegacyCopies, runEntryText } from "./index.ts";
 
 type Handler = (event: Record<string, unknown>, ctx: unknown) => Promise<unknown>;
 
@@ -16,6 +16,8 @@ interface CapturedPi {
     registerCommand: (name: string, opts: { handler: (args: string, ctx: unknown) => Promise<void> | void }) => void;
     on: (event: string, handler: Handler) => void;
     sendMessage: ReturnType<typeof vi.fn>;
+    appendEntry: ReturnType<typeof vi.fn>;
+    registerEntryRenderer: ReturnType<typeof vi.fn>;
 }
 
 function makePi(): CapturedPi {
@@ -32,6 +34,8 @@ function makePi(): CapturedPi {
             handlers[event] = handler;
         },
         sendMessage: vi.fn(),
+        appendEntry: vi.fn(),
+        registerEntryRenderer: vi.fn(),
     };
 }
 
@@ -78,6 +82,9 @@ describe("astro-subagents extension", () => {
         const ctx = { ui: { notify: vi.fn(), setStatus }, hasUI: true, cwd: root, model: { provider: "openai-codex", id: "gpt-6-astra" } };
         await pi.commands.get("run")?.handler("astro.nobody -- x", ctx);
         expect(setStatus).toHaveBeenCalledWith("subagent", expect.stringContaining("astro.nobody on openai-codex/gpt-6-astra"));
+        expect(pi.appendEntry).toHaveBeenCalledWith("astro-subagents-run", { agent: "astro.nobody", task: "x", continue: false });
+        expect(pi.registerEntryRenderer).toHaveBeenCalledWith("astro-subagents-run", expect.any(Function));
+        expect(runEntryText({ agent: "astro.dns", task: "zones", continue: true })).toBe("/run astro.dns --continue -- zones");
         expect(pi.sendMessage).toHaveBeenCalledWith(expect.objectContaining({ customType: "astro-subagents", content: expect.stringContaining("Unknown agent") }), { triggerTurn: false });
     });
 

package/extensions/astro-subagents/index.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
 import { type AgentConfig, type AgentDirs, type AgentScope, BUNDLED_NAMESPACE, defaultDirs, discoverAgents, formatAgentList, resolveSkills } from "./agents.ts";
 import { type ChildSession, childRemaining, currentDepth, type DispatchDefaults, finalOutput, isFailed, resultOutput, type RunResult, runAgent } from "./child.ts";
@@ -88,6 +89,17 @@ export function parseRunCommand(input: string): { agent: string; task: string; c
     return { agent: match[1], task, continue: match[2] !== undefined };
 }
 
+/** Transcript entry for a `/run` invocation; shown to the user, never sent to the model. */
+export interface RunEntry {
+    agent: string;
+    task: string;
+    continue: boolean;
+}
+
+export function runEntryText(entry: RunEntry): string {
+    return `/run ${entry.agent}${entry.continue ? " --continue" : ""} -- ${entry.task}`;
+}
+
 export interface GateOptions {
     dirs?: AgentDirs;
     env?: NodeJS.ProcessEnv;
@@ -265,6 +277,14 @@ export default function astroSubagents(pi: ExtensionAPI, options: GateOptions =
                 return { content: [{ type: "text", text: finalOutput(result.messages) || "(no output)" }], details: details("single", [result]) };
     }
 
+    // Slash commands are not echoed in the transcript; show the invocation the way a user message looks.
+    pi.registerEntryRenderer<RunEntry>("astro-subagents-run", (entry, _options, theme) => {
+        if (!entry.data) return undefined;
+        const box = new Box(1, 0, (text) => theme.bg("userMessageBg", text));
+        box.addChild(new Text(theme.fg("userMessageText", runEntryText(entry.data)), 0, 0));
+        return box;
+    });
+
     pi.registerCommand("run", {
         description: "Run an agent: /run <agent> [--continue] -- <task>",
         handler: async (args, ctx) => {
@@ -278,6 +298,7 @@ export default function astroSubagents(pi: ExtensionAPI, options: GateOptions =
                 return;
             }
             const agents = listAgents(ctx.cwd, "user").agents;
+            pi.appendEntry<RunEntry>("astro-subagents-run", { agent: parsed.agent, task: parsed.task, continue: parsed.continue });
             // Every /run saves its session so a later --continue can pick the conversation up.
             const session: ChildSession = { dir: sessionDirFor(dirs.sessions, parsed.agent), continue: parsed.continue };
             pruneSessions(session.dir);

package/package.json

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

package/specialists/README.md

@@ -105,7 +105,7 @@ 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.
 
-- 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. The bot replies at once with "<specialist> is working on your task" and shows the typing indicator until the answer replaces that reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows the specialists you may use in that channel and the commands (`status` lists running tasks; owners in the admin channel also see the `config` commands). Each channel and specialist has one conversation: a reply to the bot's answer, or another task for that specialist within 30 minutes, continues it with everything the specialist saw before; otherwise a new one starts, and a task beginning with `new` forces that. Replied-to and forwarded messages (text, embeds, attachment names) travel with the task, so "check this" on a forwarded alert works. Sessions live under `~/.config/astro-discord/sessions/<specialist>/` and are deleted after 7 days. Long answers arrive as a `.md` attachment.
+- 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. The bot replies at once with "<specialist> is working on your task" and shows the typing indicator until the answer replaces that reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows the specialists you may use in that channel and the commands (`status` lists running tasks; owners in the admin channel also see the `config` commands). Each channel and specialist has one conversation: a reply to the bot's answer, or another task for that specialist within 30 minutes, continues it with everything the specialist saw before; otherwise a new one starts, and a task beginning with `new` forces that. Replied-to and forwarded messages (text, embeds, attachment names) travel with the task, so "check this" on a forwarded alert works. Image attachments on the message or on what it quotes (up to 4, 8 MiB each) are downloaded and passed to the specialist, which sees them; other file types are named only. Sessions live under `~/.config/astro-discord/sessions/<specialist>/` and are deleted after 7 days. 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`.