@astrofoundry/pi-astro 0.23.2 → 0.25.0

package/README.md

@@ -57,7 +57,7 @@ pi                # launch; confirm [Extensions] lists astro-subagents, grimoire
 ## What's inside
 
 **Tools** (LLM-callable):
-- `subagent` - delegate a task to any agent, run several in parallel, or chain them (`{previous}` carries the prior output). Each agent runs in its own `pi` process with its own tool allowlist and skills; `/run <agent> -- <task>` does the same from the prompt, `/agents` lists what is available
+- `subagent` - delegate a task to any agent, run several in parallel, or chain them (`{previous}` carries the prior output). Each agent runs in its own `pi` process with its own tool allowlist and skills; `/run <agent> -- <task>` does the same from the prompt and saves the agent's session, `/run <agent> --continue -- <task>` resumes it, `/agents` lists what is available
 - `grimoire` - search indexed technical documentation via the grimoire CLI
 - `edit` - replaces pi's built-in with batch multi-file edits and Codex-style patch mode, preflight validation, atomic rollback
 - `gemini_image` - generate or edit images via Google Gemini native models and Imagen 4; cost-estimated confirmation before every call

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/commands.ts

@@ -1,7 +1,7 @@
 import type { Trigger } from "./config.ts";
 
 export type Command =
-    | { kind: "run"; specialist: string; task: string }
+    | { kind: "run"; specialist: string; task: string; fresh: boolean }
     | { kind: "help" }
     | { kind: "status" }
     | { kind: "config"; args: string[] }
@@ -34,15 +34,19 @@ export function parseCommand(content: string, context: CommandContext): Command
     if (word === "status") return { kind: "status" };
     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 (context.specialists.includes(named)) return runCommand(named, text.slice(first.length).trim());
+    if (context.specialists.length === 1) return runCommand(context.specialists[0], text);
     if (addressed) return { kind: "needs-prefix", specialists: [...context.specialists] };
     return { kind: "none" };
 }
 
+/** A task; a leading `new` asks for a fresh conversation instead of continuing the recent one. */
+function runCommand(specialist: string, text: string): Command {
+    const fresh = /^new(\s|$)/i.test(text);
+    const task = fresh ? text.replace(/^new\s*/i, "").trim() : text;
+    return task.length > 0 ? { kind: "run", specialist, task, fresh } : { kind: "help" };
+}
+
 /** Prompt paragraph appended for tasks that arrive from a chat channel. */
 export const CHANNEL_RULES = `## Channel rules
 
@@ -54,6 +58,7 @@ export function helpText(allowed: readonly string[], present: readonly string[],
     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.");
+    lines.push("A reply to my answer, or another task for the same specialist within 30 minutes, continues that conversation; start the task with `new` for a fresh one.");
     const commands = ["`help` this message", "`status` running tasks"];
     if (canConfig) commands.push("`config show`", "`config channel <#channel> <always|mention> <*|name,name>`", "`config access <specialist> add|remove <@user>`");
     lines.push(`Commands: ${commands.join(", ")}.`);

package/extensions/astro-discord/conversations.ts

@@ -0,0 +1,115 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir } from "./config.ts";
+
+/** A later task for the same specialist in the same channel continues the conversation within this window. */
+export const CONVERSATION_IDLE_MS = 30 * 60 * 1000;
+/** Conversations quiet for longer are forgotten; their session files are pruned on the same schedule. */
+export const CONVERSATION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const REMEMBERED_ANSWERS = 50;
+
+export interface Conversation {
+    /** Pi session id of the child that holds this conversation. */
+    id: string;
+    /** When the conversation started or the specialist last answered. */
+    lastAt: number;
+    /** The bot's answer messages; a reply to any of them continues here. */
+    messageIds: string[];
+}
+
+export interface ConversationState {
+    /** One live conversation per `<channelId>:<specialist>`. */
+    conversations: Record<string, Conversation>;
+}
+
+export function conversationKey(channelId: string, specialist: string): string {
+    return `${channelId}:${specialist}`;
+}
+
+export function statePath(): string {
+    return join(configDir(), "conversations.json");
+}
+
+export function sessionsRoot(): string {
+    return join(configDir(), "sessions");
+}
+
+function isConversation(value: unknown): value is Conversation {
+    if (typeof value !== "object" || value === null) return false;
+    const c = value as Record<string, unknown>;
+    return typeof c.id === "string" && typeof c.lastAt === "number" && Array.isArray(c.messageIds) && c.messageIds.every((m) => typeof m === "string");
+}
+
+/** Reads the saved state; an unreadable or malformed file starts empty. */
+export function loadState(): ConversationState {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(readFileSync(statePath(), "utf-8"));
+    } catch {
+        return { conversations: {} };
+    }
+    const conversations: Record<string, Conversation> = {};
+    const source = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>).conversations : undefined;
+    if (typeof source === "object" && source !== null) {
+        for (const [key, value] of Object.entries(source as Record<string, unknown>)) if (isConversation(value)) conversations[key] = value;
+    }
+    return { conversations };
+}
+
+export function saveState(state: ConversationState): void {
+    const path = statePath();
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+
+/** A session id Pi accepts: specialist, UTC timestamp, random suffix. */
+export function newConversationId(specialist: string, now: number, random: () => string = () => randomBytes(3).toString("hex")): string {
+    const stamp = new Date(now).toISOString().replace(/\D/g, "").slice(0, 14);
+    return `${specialist}-${stamp}-${random()}`;
+}
+
+export interface ResolveInput {
+    channelId: string;
+    specialist: string;
+    /** Id of the message this one replies to, if any. */
+    repliedTo?: string;
+    /** The user asked for a fresh conversation. */
+    fresh: boolean;
+    now: number;
+}
+
+export interface ResolvedConversation {
+    key: string;
+    id: string;
+    resumed: boolean;
+}
+
+/** The conversation a task belongs to: the one it replies to, else the recent one, else a new one. */
+export function resolveConversation(state: ConversationState, input: ResolveInput, newId: () => string): ResolvedConversation {
+    const key = conversationKey(input.channelId, input.specialist);
+    const current = state.conversations[key];
+    if (!input.fresh && current) {
+        const repliesHere = input.repliedTo !== undefined && current.messageIds.includes(input.repliedTo);
+        if (repliesHere || input.now - current.lastAt < CONVERSATION_IDLE_MS) return { key, id: current.id, resumed: true };
+    }
+    return { key, id: newId(), resumed: false };
+}
+
+export function startConversation(state: ConversationState, key: string, id: string, now: number): ConversationState {
+    return { conversations: { ...state.conversations, [key]: { id, lastAt: now, messageIds: [] } } };
+}
+
+/** Remembers the bot's answer messages and refreshes the idle window. */
+export function recordAnswer(state: ConversationState, key: string, messageIds: string[], now: number): ConversationState {
+    const current = state.conversations[key];
+    if (!current) return state;
+    const merged = [...current.messageIds, ...messageIds].slice(-REMEMBERED_ANSWERS);
+    return { conversations: { ...state.conversations, [key]: { ...current, lastAt: now, messageIds: merged } } };
+}
+
+export function forgetStale(state: ConversationState, now: number): ConversationState {
+    const conversations = Object.fromEntries(Object.entries(state.conversations).filter(([, c]) => now - c.lastAt < CONVERSATION_MAX_AGE_MS));
+    return { conversations };
+}

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

@@ -11,6 +11,9 @@ 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";
+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";
@@ -89,20 +92,24 @@ describe("commands", () => {
     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("dns list the zones", many)).toEqual({ kind: "run", specialist: "dns", task: "list the zones", fresh: false });
+        expect(parseCommand(`<@${ID}> edge probe the front door`, many)).toEqual({ kind: "run", specialist: "edge", task: "probe the front door", fresh: false });
+        expect(parseCommand("!astro.dns zones", many)).toEqual({ kind: "run", specialist: "dns", task: "zones", fresh: false });
         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("dns new list the zones", many)).toEqual({ kind: "run", specialist: "dns", task: "list the zones", fresh: true });
+        expect(parseCommand("New what changed?", one)).toEqual({ kind: "run", specialist: "arcane", task: "what changed?", fresh: true });
+        expect(parseCommand("newer images?", one)).toEqual({ kind: "run", specialist: "arcane", task: "newer images?", fresh: false });
+        expect(parseCommand("dns new", many)).toEqual({ kind: "help" });
         expect(parseCommand("hello everyone", many)).toEqual({ kind: "none" });
         expect(parseCommand("", many)).toEqual({ kind: "none" });
     });
 
     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("list the projects", one)).toEqual({ kind: "run", specialist: "arcane", task: "list the projects", fresh: false });
+        expect(parseCommand("arcane list the projects", one)).toEqual({ kind: "run", specialist: "arcane", task: "list the projects", fresh: false });
         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" });
@@ -111,10 +118,10 @@ describe("commands", () => {
     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(`<@${ID}> dns list the zones`, mention)).toEqual({ kind: "run", specialist: "dns", task: "list the zones", fresh: false });
+        expect(parseCommand("dns list the zones", { ...mention, repliedToBot: true })).toEqual({ kind: "run", specialist: "dns", task: "list the zones", fresh: false });
         expect(parseCommand("anything", { ...one, trigger: "mention" })).toEqual({ kind: "none" });
-        expect(parseCommand(`<@${ID}> anything`, { ...one, trigger: "mention" })).toEqual({ kind: "run", specialist: "arcane", task: "anything" });
+        expect(parseCommand(`<@${ID}> anything`, { ...one, trigger: "mention" })).toEqual({ kind: "run", specialist: "arcane", task: "anything", fresh: false });
     });
 
     it("writes help and prefix texts", () => {
@@ -236,3 +243,81 @@ describe("approval server", () => {
         server.close();
     });
 });
+
+describe("conversations", () => {
+    const now = 1_800_000_000_000;
+    it("continues on a reply or within the idle window, otherwise starts fresh", () => {
+        let state = startConversation({ conversations: {} }, "1:dns", "dns-a", now);
+        state = recordAnswer(state, "1:dns", ["m1"], now);
+        const input = { channelId: "1", specialist: "dns", fresh: false, now: now + 60_000 };
+        expect(resolveConversation(state, input, () => "dns-b")).toEqual({ key: "1:dns", id: "dns-a", resumed: true });
+        expect(resolveConversation(state, { ...input, now: now + CONVERSATION_IDLE_MS + 1 }, () => "dns-b")).toEqual({ key: "1:dns", id: "dns-b", resumed: false });
+        expect(resolveConversation(state, { ...input, now: now + CONVERSATION_IDLE_MS + 1, repliedTo: "m1" }, () => "dns-b")).toEqual({ key: "1:dns", id: "dns-a", resumed: true });
+        expect(resolveConversation(state, { ...input, fresh: true }, () => "dns-b")).toEqual({ key: "1:dns", id: "dns-b", resumed: false });
+        expect(resolveConversation(state, { ...input, channelId: "2" }, () => "dns-b").resumed).toBe(false);
+        expect(recordAnswer(state, "missing", ["x"], now)).toBe(state);
+        expect(forgetStale(state, now + CONVERSATION_MAX_AGE_MS + 1).conversations).toEqual({});
+        expect(forgetStale(state, now + 1).conversations["1:dns"]).toBeDefined();
+    });
+
+    it("builds Pi-compatible ids and round-trips the state file", () => {
+        const id = newConversationId("security", Date.UTC(2026, 8, 16, 20, 55, 0), () => "abc123");
+        expect(id).toBe("security-20260916205500-abc123");
+        expect(id).toMatch(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/);
+        const dir = mkdtempSync(join(tmpdir(), "astro-conv-"));
+        process.env.ASTRO_DISCORD_DIR = dir;
+        try {
+            expect(loadState()).toEqual({ conversations: {} });
+            const state = recordAnswer(startConversation({ conversations: {} }, "1:dns", id, now), "1:dns", ["m1"], now);
+            saveState(state);
+            expect(loadState()).toEqual(state);
+            writeFileSync(join(dir, "conversations.json"), JSON.stringify({ conversations: { bad: { id: 1 }, ok: { id: "x", lastAt: 1, messageIds: [] } } }));
+            expect(Object.keys(loadState().conversations)).toEqual(["ok"]);
+        } finally {
+            delete process.env.ASTRO_DISCORD_DIR;
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});
+
+describe("quotes", () => {
+    it("flattens content, embeds, and attachments and appends them to the task", () => {
+        const alert = { content: "", embeds: [{ title: "Wazuh alert, level 12", description: "System running out of memory.", fields: [{ name: "agent", value: "arcane" }], footer: { text: "rule 5108" } }], attachments: [{ filename: "log.txt" }] };
+        expect(quoteText(alert)).toBe("Wazuh alert, level 12\nSystem running out of memory.\nagent: arcane\nrule 5108\nAttachments: log.txt");
+        expect(quoteText({ content: "x".repeat(5000) })).toHaveLength(4001);
+        expect(withQuotes("check this", [])).toBe("check this");
+        expect(withQuotes("check this", [{ label: "Forwarded message", message: { content: "" } }])).toBe("check this");
+        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,14 +1,19 @@
+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";
 import { type AgentConfig, defaultDirs, discoverAgents, resolveSkills } from "../astro-subagents/agents.ts";
-import { AGENT_ENV, type DispatchDefaults, type RunResult, childRemaining, currentDepth, finalOutput, isFailed, runAgent } from "../astro-subagents/child.ts";
+import { AGENT_ENV, type ChildSession, type DispatchDefaults, type RunResult, childRemaining, currentDepth, finalOutput, isFailed, runAgent } from "../astro-subagents/child.ts";
+import { pruneSessions, sessionDirFor } from "../astro-subagents/sessions.ts";
 import { ApprovalServer, type Ticket } from "./approvals.ts";
 import { chunkMessage } from "./chunk.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 { 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";
 
 const REACTION = { running: "⏳", waiting: "🔒", done: "✅", failed: "❌" } as const;
@@ -55,7 +60,11 @@ interface IncomingMessage {
     guild_id?: string;
     content?: string;
     author?: { id: string; bot?: boolean };
-    referenced_message?: { author?: { id: string } } | null;
+    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. */
+    message_snapshots?: { message: QuotedMessage }[];
 }
 
 interface ComponentInteraction {
@@ -75,6 +84,8 @@ interface ActiveTask {
     messageId: string;
     userId: string;
     startedAt: number;
+    conversation: ResolvedConversation;
+    images: ImageAttachment[];
 }
 
 function log(line: string): void {
@@ -105,6 +116,7 @@ class Bridge {
     private readonly active = new Map<string, ActiveTask>();
     private readonly approvalMessages = new Map<string, { channelId: string; messageId: string; userMessage: ActiveTask }>();
     private config: DiscordConfig;
+    private conversations: ConversationState;
     private botUserId = "";
     /** Thread id to parent channel id; null marks a plain channel. */
     private readonly parents = new Map<string, string | null>();
@@ -115,6 +127,7 @@ class Bridge {
         this.ctx = ctx;
         this.token = token;
         this.config = config;
+        this.conversations = loadState();
         this.rest = new DiscordRest(token);
         this.approvals = new ApprovalServer({ onTicket: (t) => void this.askApproval(t), onExpired: (t) => void this.expireApproval(t) }, config.approvalTimeoutMinutes * 60_000);
     }
@@ -220,12 +233,37 @@ class Bridge {
         if (!canUse(this.config, userId, command.specialist)) return;
         const agent = agents.find((a) => a.name === `astro.${command.specialist}`);
         if (!agent) return;
-        const task: ActiveTask = { specialist: command.specialist, channelId: message.channel_id, messageId: message.id, userId, startedAt: Date.now() };
+        const now = Date.now();
+        this.conversations = forgetStale(this.conversations, now);
+        const conversation = resolveConversation(
+            this.conversations,
+            { channelId: message.channel_id, specialist: command.specialist, repliedTo: message.referenced_message?.id, fresh: command.fresh, now },
+            () => newConversationId(command.specialist, now),
+        );
+        if (!conversation.resumed) this.conversations = startConversation(this.conversations, conversation.key, conversation.id, now);
+        saveState(this.conversations);
+        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, command.task, task)).catch((err) => log(`run failed: ${err instanceof Error ? err.message : String(err)}`));
+        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);
     }
 
+    /** Replied-to and forwarded messages to show the specialist; the bot's own answer only when the conversation holding it is not resumed. */
+    private quotesFor(message: IncomingMessage, resumed: boolean): Quote[] {
+        const quotes: Quote[] = [];
+        const replied = message.referenced_message;
+        if (replied) {
+            const mine = replied.author?.id === this.botUserId;
+            if (!mine) quotes.push({ label: `Replied-to message from ${replied.author?.username ?? replied.author?.id ?? "an unknown author"}`, message: replied });
+            else if (!resumed) quotes.push({ label: "My earlier answer, which this message replies to", message: replied });
+        }
+        for (const snapshot of message.message_snapshots ?? []) quotes.push({ label: "Forwarded message", message: snapshot.message });
+        return quotes;
+    }
+
     private async runTask(agent: AgentConfig, taskText: string, task: ActiveTask): Promise<void> {
         task.startedAt = Date.now();
         this.active.set(task.specialist, task);
@@ -238,7 +276,12 @@ class Bridge {
         await this.rest.triggerTyping(task.channelId).catch(() => undefined);
         const typing = setInterval(() => void this.rest.triggerTyping(task.channelId).catch(() => undefined), 8000);
         typing.unref();
-        log(`run astro.${task.specialist} for ${task.userId}: ${taskText.slice(0, 200)}`);
+        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(", ")}`);
@@ -255,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),
@@ -263,6 +307,7 @@ class Bridge {
                 // 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,
+                session,
                 onUpdate: (partial) => {
                     const progress = describeProgress(partial, seen);
                     seen = progress.seen;
@@ -283,29 +328,36 @@ 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);
-        await this.deliver(task, placeholder, `${failed ? "❌" : "✅"} **${task.specialist}**\n${output}`, attachment);
+        const answers = await this.deliver(task, placeholder, `${failed ? "❌" : "✅"} **${task.specialist}**\n${output}`, attachment);
+        this.conversations = recordAnswer(this.conversations, task.conversation.key, answers, Date.now());
+        saveState(this.conversations);
     }
 
-    /** Turns the "working" placeholder into the answer: edit it in place when it fits, otherwise replace it with chunks or an attachment. */
-    private async deliver(task: ActiveTask, placeholder: string | undefined, text: string, attachment?: string): Promise<void> {
+    /** Turns the "working" placeholder into the answer: edit it in place when it fits, otherwise replace it with chunks or an attachment. Returns the answer message ids. */
+    private async deliver(task: ActiveTask, placeholder: string | undefined, text: string, attachment?: string): Promise<string[]> {
         const oversized = attachment !== undefined || text.length > ATTACHMENT_THRESHOLD;
         if (oversized) {
             if (placeholder) await this.rest.deleteMessage(task.channelId, placeholder).catch(() => undefined);
             const file = attachment !== undefined ? { name: `astro-${task.specialist}-stderr-${Date.now()}.txt`, content: attachment } : { name: `astro-${task.specialist}-${Date.now()}.md`, content: text };
             const content = attachment !== undefined ? text.slice(0, 1900) : `${text.slice(0, 1200).trim()}\n… full answer attached (${text.length} characters).`;
-            await this.rest.createMessage(task.channelId, { content, replyTo: task.messageId, file });
-            return;
+            const posted = await this.rest.createMessage(task.channelId, { content, replyTo: task.messageId, file });
+            return [posted.id];
         }
         const chunks = chunkMessage(text);
         if (chunks.length === 0) chunks.push(text);
-        if (placeholder) await this.rest.editMessage(task.channelId, placeholder, chunks[0]).catch(() => undefined);
-        else await this.rest.createMessage(task.channelId, { content: chunks[0], replyTo: task.messageId });
+        const ids: string[] = [];
+        if (placeholder) {
+            await this.rest.editMessage(task.channelId, placeholder, chunks[0]).catch(() => undefined);
+            ids.push(placeholder);
+        } else ids.push((await this.rest.createMessage(task.channelId, { content: chunks[0], replyTo: task.messageId })).id);
         for (let i = 1; i < chunks.length; i++) {
-            await this.rest.createMessage(task.channelId, { content: chunks[i] });
+            ids.push((await this.rest.createMessage(task.channelId, { content: chunks[i] })).id);
         }
+        return ids;
     }
 
     private async askApproval(ticket: Ticket): Promise<void> {

package/extensions/astro-discord/quote.ts

@@ -0,0 +1,39 @@
+/** The parts of a Discord message worth quoting to a specialist. */
+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; url?: string; content_type?: string; size?: number }[];
+    author?: { id: string; username?: string; bot?: boolean };
+}
+
+const QUOTE_LIMIT = 4000;
+
+/** Plain text of a message: content, then each embed's texts, then attachment names. */
+export function quoteText(message: QuotedMessage): string {
+    const parts: string[] = [];
+    const content = message.content?.trim();
+    if (content) parts.push(content);
+    for (const embed of message.embeds ?? []) {
+        const lines = [embed.author?.name, embed.title, embed.description, ...(embed.fields ?? []).map((f) => `${f.name}: ${f.value}`), embed.footer?.text];
+        for (const line of lines) {
+            const text = line?.trim();
+            if (text) parts.push(text);
+        }
+    }
+    if (message.attachments && message.attachments.length > 0) parts.push(`Attachments: ${message.attachments.map((a) => a.filename).join(", ")}`);
+    const text = parts.join("\n");
+    return text.length > QUOTE_LIMIT ? `${text.slice(0, QUOTE_LIMIT)}…` : text;
+}
+
+export interface Quote {
+    label: string;
+    message: QuotedMessage;
+}
+
+/** The task with the replied-to and forwarded messages appended, so the specialist sees what "this" refers to. */
+export function withQuotes(task: string, quotes: readonly Quote[]): string {
+    const blocks = quotes.map((q) => ({ label: q.label, text: quoteText(q.message) })).filter((q) => q.text.length > 0);
+    if (blocks.length === 0) return task;
+    return `${task}\n\n${blocks.map((q) => `${q.label}:\n${q.text}`).join("\n\n")}`;
+}

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

@@ -67,6 +67,7 @@ describe("discovery", () => {
             bundledSkills: join(root, "pkg", "skills"),
             userAgents: join(root, "user", "agents"),
             userSkills: join(root, "user", "skills"),
+            sessions: join(root, "sessions"),
         };
         for (const d of Object.values(dirs)) mkdirSync(d, { recursive: true });
         writeFileSync(join(dirs.bundledAgents, "arcane.md"), "---\nname: arcane\ndescription: bundled\nskills: arcane\n---\nB");

package/extensions/astro-subagents/agents.ts

@@ -39,6 +39,8 @@ export interface AgentDirs {
     bundledSkills: string;
     userAgents: string;
     userSkills: string;
+    /** Root for saved `/run` sessions, one folder per agent. */
+    sessions: string;
 }
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -50,6 +52,7 @@ export function defaultDirs(): AgentDirs {
         bundledSkills: path.join(packageRoot, "skills"),
         userAgents: path.join(getAgentDir(), "agents"),
         userSkills: path.join(getAgentDir(), "skills"),
+        sessions: path.join(getAgentDir(), "subagent-sessions"),
     };
 }
 

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

@@ -56,6 +56,14 @@ describe("child arguments", () => {
     it("does not pass the parent's thinking level to an agent that pins its own model", () => {
         const pinned: AgentConfig = { ...agent, model: "m" };
         expect(buildChildArgs({ agent: pinned, task: "t", promptFile: null, defaults: { thinkingLevel: "high" } })).not.toContain("--thinking");
+        const saved = buildChildArgs({ agent: pinned, task: "t", promptFile: null, defaults: {}, session: { dir: "/s/x", continue: true } });
+        expect(saved.slice(0, 6)).toEqual(["--mode", "json", "-p", "--session-dir", "/s/x", "--continue"]);
+        expect(saved).not.toContain("--no-session");
+        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

@@ -71,16 +71,35 @@ export function composeSystemPrompt(agent: AgentConfig, skills: ResolvedSkill[],
     return parts.filter((p) => p.length > 0).join("\n\n");
 }
 
+/**
+ * Where the child keeps its conversation. Without one the child is ephemeral.
+ * `id` opens that exact session (created when missing); otherwise `continue`
+ * resumes the most recent session in `dir` started from the same working directory.
+ */
+export interface ChildSession {
+    dir: string;
+    continue?: boolean;
+    id?: string;
+}
+
 export interface ChildArgsInput {
     agent: AgentConfig;
     task: string;
     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, no session file. */
-export function buildChildArgs({ agent, task, promptFile, defaults }: ChildArgsInput): string[] {
-    const args = ["--mode", "json", "-p", "--no-session"];
+/** Arguments for the child `pi` process: print mode, JSON events, a session file only when asked. */
+export function buildChildArgs({ agent, task, promptFile, defaults, session, files }: ChildArgsInput): string[] {
+    const args = ["--mode", "json", "-p"];
+    if (session) {
+        args.push("--session-dir", session.dir);
+        if (session.id) args.push("--session-id", session.id);
+        else if (session.continue) args.push("--continue");
+    } else args.push("--no-session");
     const model = agent.model ?? defaults.model;
     if (model) args.push("--model", model);
     const thinking = agent.thinking ?? (agent.model ? undefined : defaults.thinkingLevel);
@@ -89,7 +108,7 @@ export function buildChildArgs({ agent, task, promptFile, defaults }: ChildArgsI
     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;
 }
 
@@ -182,6 +201,10 @@ export interface RunOptions {
     env?: Record<string, string>;
     /** Text appended to the system prompt, for example channel rules. */
     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> {
@@ -206,7 +229,8 @@ export async function runAgent(options: RunOptions): Promise<RunResult> {
         await fs.promises.writeFile(promptFile, prompt, { encoding: "utf-8", mode: 0o600 });
     }
     try {
-        const args = buildChildArgs({ agent, task, promptFile, defaults: options.defaults });
+        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, 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(),
     };
 }
 
@@ -46,6 +50,7 @@ describe("astro-subagents extension", () => {
             bundledSkills: join(root, "pkg", "skills"),
             userAgents: join(root, "user", "agents"),
             userSkills: join(root, "user", "skills"),
+            sessions: join(root, "sessions"),
         };
         for (const d of Object.values(dirs)) mkdirSync(d, { recursive: true });
         writeFileSync(join(dirs.bundledAgents, "arcane.md"), "---\nname: arcane\ndescription: Operates Arcane\n---\nB");
@@ -77,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 });
     });
 
@@ -92,8 +100,11 @@ describe("astro-subagents extension", () => {
     });
 
     it("parses /run arguments", () => {
-        expect(parseRunCommand("astro.arcane -- list projects")).toEqual({ agent: "astro.arcane", task: "list projects" });
-        expect(parseRunCommand("scout find auth code")).toEqual({ agent: "scout", task: "find auth code" });
+        expect(parseRunCommand("astro.arcane -- list projects")).toEqual({ agent: "astro.arcane", task: "list projects", continue: false });
+        expect(parseRunCommand("scout find auth code")).toEqual({ agent: "scout", task: "find auth code", continue: false });
+        expect(parseRunCommand("astro.security --continue -- do the next step")).toEqual({ agent: "astro.security", task: "do the next step", continue: true });
+        expect(parseRunCommand("astro.security --continue next")).toEqual({ agent: "astro.security", task: "next", continue: true });
+        expect(parseRunCommand("scout --continue")).toBeNull();
         expect(parseRunCommand("scout")).toBeNull();
         expect(pruneLegacyCopies(join(root, "missing"))).toEqual([]);
     });

package/extensions/astro-subagents/index.ts

@@ -3,9 +3,11 @@ 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 { childRemaining, currentDepth, type DispatchDefaults, finalOutput, isFailed, resultOutput, type RunResult, runAgent } from "./child.ts";
+import { type ChildSession, childRemaining, currentDepth, type DispatchDefaults, finalOutput, isFailed, resultOutput, type RunResult, runAgent } from "./child.ts";
+import { pruneSessions, sessionDirFor } from "./sessions.ts";
 import { renderCall, renderResult, type SubagentDetails } from "./render.ts";
 import { startTicker } from "./ticker.ts";
 
@@ -77,11 +79,25 @@ export function pruneLegacyCopies(userAgentsDir: string): string[] {
 }
 
 /** Parses `/run <agent> -- <task>` (the `--` is optional when the task has no leading dash). */
-export function parseRunCommand(input: string): { agent: string; task: string } | null {
+/** `/run <agent> [--continue] [--] <task>`; `--continue` resumes the agent's last saved session from this directory. */
+export function parseRunCommand(input: string): { agent: string; task: string; continue: boolean } | null {
     const trimmed = input.trim();
-    const match = /^(\S+)\s+(?:--\s+)?([\s\S]+)$/.exec(trimmed);
+    const match = /^(\S+)(\s+--continue)?\s+(?:--\s+)?([\s\S]+)$/.exec(trimmed);
     if (!match) return null;
-    return { agent: match[1], task: match[2].trim() };
+    const task = match[3].trim();
+    if (task === "--continue") return null;
+    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 {
@@ -105,6 +121,7 @@ export default function astroSubagents(pi: ExtensionAPI, options: GateOptions =
         step: number | undefined,
         signal: AbortSignal | undefined,
         onUpdate: ((r: RunResult) => void) | undefined,
+        session?: ChildSession,
     ): Promise<RunResult> {
         const agent = agents.find((a) => a.name === agentName);
         if (!agent) {
@@ -136,6 +153,7 @@ export default function astroSubagents(pi: ExtensionAPI, options: GateOptions =
             step,
             signal,
             onUpdate,
+            session,
         });
     }
 
@@ -259,8 +277,16 @@ 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 once: /run <agent> -- <task>",
+        description: "Run an agent: /run <agent> [--continue] -- <task>",
         handler: async (args, ctx) => {
             if (!canDelegate) {
                 ctx.ui.notify("subagents: this session may not delegate further (depth limit)", "warning");
@@ -268,18 +294,22 @@ export default function astroSubagents(pi: ExtensionAPI, options: GateOptions =
             }
             const parsed = parseRunCommand(args);
             if (!parsed) {
-                ctx.ui.notify("usage: /run <agent> -- <task>", "warning");
+                ctx.ui.notify("usage: /run <agent> [--continue] -- <task>", "warning");
                 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);
             const stopTicker = startTicker(ctx, runLabel(ctx, agents, parsed.agent));
             let result: RunResult;
             try {
-                result = await runOne(ctx, agents, parsed.agent, parsed.task, undefined, undefined, undefined, undefined);
+                result = await runOne(ctx, agents, parsed.agent, parsed.task, undefined, undefined, undefined, undefined, session);
             } finally {
                 stopTicker();
             }
-            const status = isFailed(result) ? "failed" : "done";
+            const status = `${isFailed(result) ? "failed" : "done"}${parsed.continue ? ", continued" : ""}`;
             if (isFailed(result)) ctx.ui.notify(`${parsed.agent} failed`, "warning");
             // No turn: the result joins the context for the next prompt without the parent model restating it.
             pi.sendMessage({ customType: "astro-subagents", content: `Result from /run ${parsed.agent} (${status}). Task: ${parsed.task}\n\n${resultOutput(result)}`, display: true }, { triggerTurn: false });

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

@@ -0,0 +1,32 @@
+import { mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { pruneSessions, sessionDirFor } from "./sessions.ts";
+
+describe("child sessions", () => {
+    let root: string;
+    beforeEach(() => {
+        root = mkdtempSync(join(tmpdir(), "astro-sessions-"));
+    });
+    afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+    it("names one directory per agent", () => {
+        expect(sessionDirFor("/s", "astro.security")).toBe("/s/astro.security");
+        expect(sessionDirFor("/s", "a b/c")).toBe("/s/a_b_c");
+    });
+
+    it("prunes old session files and leaves recent ones and other files", () => {
+        const now = 1_800_000_000_000;
+        const old = join(root, "old.jsonl");
+        const fresh = join(root, "fresh.jsonl");
+        const other = join(root, "notes.txt");
+        for (const f of [old, fresh, other]) writeFileSync(f, "x");
+        utimesSync(old, new Date(now - 8 * 86_400_000), new Date(now - 8 * 86_400_000));
+        utimesSync(other, new Date(now - 8 * 86_400_000), new Date(now - 8 * 86_400_000));
+        utimesSync(fresh, new Date(now - 60_000), new Date(now - 60_000));
+        expect(pruneSessions(root, 7 * 86_400_000, now)).toBe(1);
+        expect(readdirSync(root).sort()).toEqual(["fresh.jsonl", "notes.txt"]);
+        expect(pruneSessions(join(root, "missing"), 1, now)).toBe(0);
+    });
+});

package/extensions/astro-subagents/sessions.ts

@@ -0,0 +1,34 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Saved child sessions older than this are deleted before a run. */
+export const SESSION_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Directory holding one agent's saved child sessions. */
+export function sessionDirFor(root: string, agentName: string): string {
+    return path.join(root, agentName.replace(/[^\w.-]+/g, "_"));
+}
+
+/** Deletes session files not modified within `maxAgeMs`; a missing directory holds nothing to prune. */
+export function pruneSessions(dir: string, maxAgeMs = SESSION_MAX_AGE_MS, now = Date.now()): number {
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+        if (!name.endsWith(".jsonl")) continue;
+        const file = path.join(dir, name);
+        try {
+            if (now - fs.statSync(file).mtimeMs > maxAgeMs) {
+                fs.unlinkSync(file);
+                removed++;
+            }
+        } catch {
+            // The file vanished between readdir and stat; nothing left to prune.
+        }
+    }
+    return removed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.23.2",
+  "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

@@ -14,7 +14,7 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
 | `astro.proxmox` | Proxmox VE on Pulsar | API token: `guests`, `guest`, `get <path>`, `tasks`; `start`, `shutdown|reboot|stop --confirm`; snapshots create, delete, rollback; `set` of CPU, memory, options, network. Pulsar key: `host-status`, `host-journal`, `updates`, `guest-exec <vmid> <status|journal|df|updates>` |
 | `astro.inference` | llama.cpp on Nexus, Hermes on LXC 101, Europa health | `nexus-status|start|stop|restart|log|disk`; `hermes-status|journal|errors|restart|api-health|version|guest-status|snapshots`, `hermes-releases`, `hermes-upgrade --confirm`; `europa-health` |
 
-Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both from the bundled `astro-subagents` extension). Specialists may call each other once (`maxSubagentDepth: 1`). They run on `openai-codex/gpt-6-astra` with `xhigh` thinking, set by `model` and `thinking` in each `agents/<name>.md`; an agent without these fields inherits the caller's model and thinking. Each tool takes `args`, an array of strings; `["--help"]` lists the subcommands.
+Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both from the bundled `astro-subagents` extension). `/run` saves the specialist's session under `~/.pi/agent/subagent-sessions/<agent>/`; `/run astro.<name> --continue -- <task>` resumes the last one started from the same directory, so the specialist keeps what it saw. Sessions older than 7 days are deleted. Specialists may call each other once (`maxSubagentDepth: 1`). They run on `openai-codex/gpt-6-astra` with `xhigh` thinking, set by `model` and `thinking` in each `agents/<name>.md`; an agent without these fields inherits the caller's model and thinking. Each tool takes `args`, an array of strings; `["--help"]` lists the subcommands.
 
 ## How it is secured
 
@@ -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). 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`.