pi-discord-bot 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,352 @@
+# pi-discord-bot
+
+A small Discord harness built around Pi primitives.
+
+It keeps Pi as the agent core and adds a Discord transport layer with:
+- one runner per conversation
+- append-only session/log files
+- Discord-native embeds, buttons, and select menus
+- approval-gated Discord admin actions
+- systemd-friendly local operation
+
+## Architecture
+
+This project does **not** reimplement Pi’s core agent loop.
+It uses:
+- `@mariozechner/pi-agent-core` `Agent`
+- `@mariozechner/pi-coding-agent` `AgentSession`
+- `SessionManager`
+- `SettingsManager`
+- `AuthStorage`
+- `ModelRegistry`
+
+Main files:
+- `src/main.ts` — startup and command routing
+- `src/discord.ts` — Discord transport and interaction handling
+- `src/discord-ui.ts` — embed/card builders and Discord UI helpers
+- `src/agent.ts` — Pi runner/session wiring
+- `src/agent-models.ts` — model resolution helpers
+- `src/agent-tree.ts` — session tree formatting/browser helpers
+- `src/context.ts` — sync `log.jsonl` into Pi session state
+- `src/store.ts` — log + attachment persistence
+
+## Features
+
+- DM support
+- guild support with mention gating for normal chat
+- text commands like `/tree` in chat
+- Discord slash commands
+- model picker cards
+- scoped model selector cards
+- settings card
+- session tree browser card
+- approval cards for destructive / mutating actions
+- detail threads in guilds for verbose output
+- reactions for progress:
+  - `🤔` thinking/working
+  - `🧑‍💻` tool activity
+- long-message chunking
+- image attachment support
+- file attachment download + local-path handoff to Pi tools
+
+## Commands
+
+Supported command surface:
+- `/help`
+- `/new`
+- `/name <name>`
+- `/session`
+- `/tree`
+- `/tree <entryId>`
+- `/model`
+- `/model <provider/model-or-search>`
+- `/scoped-models`
+- `/scoped-models <pattern[,pattern...]>`
+- `/scoped-models clear`
+- `/settings`
+- `/compact [instructions]`
+- `/reload`
+- `/login [provider]`
+- `/logout [provider]`
+- `/stop`
+
+Unsupported in Discord:
+- `/resume`
+- `/fork`
+- `/copy`
+- `/export`
+- `/share`
+- `/hotkeys`
+- `/changelog`
+- `/quit`
+- `/exit`
+
+## Install
+
+### Use as a Pi package skill
+
+From npm:
+
+```bash
+pi install npm:pi-discord-bot
+```
+
+From a local source checkout:
+
+```bash
+pi install /absolute/path/to/pi-discord-bot
+```
+
+Then start Pi and use:
+
+```text
+/skill:pi-discord-bot
+```
+
+See also:
+- `docs/using-skill-in-pi.md`
+
+### Develop or run from source
+
+```bash
+npm install
+```
+
+## Run locally
+
+By default, the runtime workspace is **outside the repo**:
+
+```text
+$XDG_STATE_HOME/pi-discord-bot/agent
+```
+
+or, if `XDG_STATE_HOME` is unset:
+
+```text
+~/.local/state/pi-discord-bot/agent
+```
+
+Run with the default external workspace:
+
+```bash
+export DISCORD_TOKEN=...
+npx tsx src/main.ts
+```
+
+Or override it explicitly:
+
+```bash
+PI_DISCORD_BOT_WORKDIR=/absolute/path/to/pi-discord-bot-agent npx tsx src/main.ts
+```
+
+Or:
+
+```bash
+npm run build
+npm start
+```
+
+## Auth and model selection
+
+Do **not** hardcode model choices in the bot.
+This project uses Pi shared auth/settings/default model flow.
+
+The bot reads model availability from Pi’s model registry and lets you choose with Discord UI.
+
+## Discord setup
+
+Create a Discord application and bot, then enable:
+- **Message Content Intent**
+
+Recommended scopes:
+- `bot`
+- `applications.commands`
+
+Recommended bot permissions:
+- View Channels
+- Send Messages
+- Send Messages in Threads
+- Create Public Threads
+- Create Private Threads
+- Read Message History
+- Attach Files
+- Use Slash Commands
+- Manage Channels
+  - needed if you want channel/category/thread admin tools to work
+
+## Policy file
+
+Create the runtime policy file in the external workspace:
+
+```bash
+mkdir -p ~/.local/state/pi-discord-bot/agent
+cp discord-policy.example.json ~/.local/state/pi-discord-bot/agent/discord-policy.json
+```
+
+Or, if using a custom workspace path:
+
+```bash
+mkdir -p "$PI_DISCORD_BOT_WORKDIR"
+cp discord-policy.example.json "$PI_DISCORD_BOT_WORKDIR/discord-policy.json"
+```
+
+Example:
+
+```json
+{
+  "allowDMs": true,
+  "guildIds": ["123456789012345678"],
+  "channelIds": ["234567890123456789"],
+  "mentionMode": "mention-only",
+  "slashCommands": {
+    "enabled": true
+  }
+}
+```
+
+Notes:
+- omit `guildIds` to allow all guilds
+- omit `channelIds` to allow all channels
+- `mentionMode: "mention-only"` means normal non-command guild chat must mention the bot
+- text commands beginning with `/` are accepted without mentioning the bot
+- slash commands can be registered globally or to a guild via policy/env
+
+## Attachments
+
+Normal Discord message attachments are handled like this:
+- images (`png`, `jpg`, `jpeg`, `gif`, `webp`) are passed to Pi as image input
+- other files are downloaded into the conversation `attachments/` directory and their local paths are added to the prompt so Pi tools can inspect them
+
+Slash-command attachments are not currently wired.
+
+## Runtime layout
+
+Default runtime root:
+
+```text
+~/.local/state/pi-discord-bot/agent/
+```
+
+Layout:
+
+```text
+agent/
+  discord-policy.json
+  MEMORY.md
+  skills/
+  guild:123:channel:456/
+    MEMORY.md
+    log.jsonl
+    context.jsonl
+    attachments/
+    scratch/
+    skills/
+  dm:999/
+    ...
+```
+
+## Operator env/config guide
+
+For operator-focused configuration, especially if you already use Pi CLI / TUI on the same machine, see:
+
+- `docs/operator-env-config.md`
+- `docs/using-skill-in-pi.md`
+- `docs/publishing-checklist.md`
+- `docs/github-release-flow.md`
+
+Those guides explain:
+- how to install the package into Pi from npm or source
+- how to use `/skill:pi-discord-bot`
+- `~/.config/pi-discord-bot.env`
+- Pi shared auth/settings expectations
+- workspace `discord-policy.json`
+- systemd usage
+- troubleshooting for operators
+
+## systemd
+
+A user service file is included:
+- `pi-discord-bot.service`
+
+Typical setup:
+
+```bash
+mkdir -p ~/.config/systemd/user ~/.config
+cp pi-discord-bot.service ~/.config/systemd/user/
+cp pi-discord-bot.env.example ~/.config/pi-discord-bot.env
+$EDITOR ~/.config/pi-discord-bot.env
+systemctl --user daemon-reload
+systemctl --user enable --now pi-discord-bot.service
+```
+
+Useful commands:
+
+```bash
+systemctl --user status pi-discord-bot.service
+journalctl --user -u pi-discord-bot.service -f
+systemctl --user restart pi-discord-bot.service
+```
+
+## Troubleshooting
+
+### Slash command updated in code but not in Discord
+If you register commands globally, Discord may take time to refresh the slash-command UI.
+The bot may already support the command even if the Discord slash menu has not updated yet.
+
+What you can do:
+- wait for Discord to refresh global commands
+- reopen/refresh the Discord client
+- use a text command like `/tree` directly in chat while waiting
+
+### Text command vs slash command
+There are two ways to invoke commands:
+- **slash command UI**: `/tree`, `/model`, etc. from Discord command picker
+- **plain text command message**: a normal message beginning with `/`
+
+In guilds:
+- normal non-command chat still follows mention gating
+- plain text commands beginning with `/` are accepted without mentioning the bot
+
+### Attachments
+Current attachment behavior:
+- normal message image attachments are passed as image input
+- normal message non-image files are downloaded and exposed as local files for Pi tools
+- slash-command attachments are **not** currently supported
+
+### Admin tools do not work
+Make sure the bot has the required Discord permissions for the action.
+For server structure mutations, you usually need:
+- View Channels
+- Send Messages
+- Read Message History
+- Use Slash Commands
+- Manage Channels
+- Create Public Threads
+- Create Private Threads
+
+## Debugging notes
+The bot logs useful runtime events through the service log, including:
+- startup and slash command registration
+- skipped messages due to policy
+- backfill activity
+- queue/update warnings
+
+Use:
+
+```bash
+journalctl --user -u pi-discord-bot.service -f
+```
+
+## Security / hygiene
+
+Runtime conversation data is stored under the external workspace directory (by default `~/.local/state/pi-discord-bot/agent/`) and may contain:
+- user messages
+- assistant outputs
+- attachment metadata
+- local file paths
+- tool results
+
+Treat the workspace directory as private runtime state.
+Do not commit or share it.
+
+The repo includes a `.gitignore` that excludes runtime state and build artifacts.

package/discord-policy.example.json

@@ -0,0 +1,10 @@
+{
+  "allowDMs": true,
+  "guildIds": ["123456789012345678"],
+  "channelIds": ["234567890123456789"],
+  "mentionMode": "mention-only",
+  "slashCommands": {
+    "enabled": true,
+    "guildId": "123456789012345678"
+  }
+}

package/dist/agent-models.js

@@ -0,0 +1,81 @@
+export function resolveInitialModel(modelRegistry, settingsManager) {
+    const available = modelRegistry.getAvailable();
+    const all = modelRegistry.getAll();
+    const savedProvider = settingsManager.getDefaultProvider();
+    const savedModelId = settingsManager.getDefaultModel();
+    const saved = savedProvider && savedModelId ? modelRegistry.find(savedProvider, savedModelId) : undefined;
+    return saved ?? available[0] ?? all[0] ?? (() => {
+        throw new Error("No models available in Pi model registry");
+    })();
+}
+export function findModelByReference(modelRegistry, reference) {
+    const query = reference.trim().toLowerCase();
+    if (!query)
+        return { error: "Missing model reference." };
+    const models = modelRegistry.getAvailable();
+    if (models.length === 0)
+        return { error: "No available models. Authenticate with Pi first." };
+    const exact = models.find((model) => `${model.provider}/${model.id}`.toLowerCase() === query || model.id.toLowerCase() === query);
+    if (exact)
+        return { model: exact };
+    const partial = models.filter((model) => `${model.provider}/${model.id}`.toLowerCase().includes(query) || model.id.toLowerCase().includes(query));
+    if (partial.length === 1)
+        return { model: partial[0] };
+    if (partial.length === 0)
+        return { error: `No available model matches \`${reference}\`.` };
+    return {
+        error: `Model reference is ambiguous. Matches: ${partial.slice(0, 8).map((model) => `\`${model.provider}/${model.id}\``).join(", ")}`,
+    };
+}
+export function formatModel(model) {
+    return model ? `${model.provider}/${model.id}` : "(no model selected)";
+}
+export function modelSortKey(model) {
+    const providerPriority = model.provider === "openai-codex"
+        ? 0
+        : model.provider === "anthropic"
+            ? 1
+            : model.provider === "openai"
+                ? 2
+                : 3;
+    return [providerPriority, `${model.provider}/${model.id}`.toLowerCase()];
+}
+function wildcardToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`, "i");
+}
+export function resolveScopedModels(modelRegistry, patterns) {
+    const available = modelRegistry.getAvailable();
+    const resolved = [];
+    const seen = new Set();
+    for (const raw of patterns) {
+        const pattern = raw.trim();
+        if (!pattern)
+            continue;
+        const exact = available.filter((model) => `${model.provider}/${model.id}`.toLowerCase() === pattern.toLowerCase() || model.id.toLowerCase() === pattern.toLowerCase());
+        const regex = wildcardToRegExp(pattern.includes("/") ? pattern : `*${pattern}*`);
+        const matches = exact.length > 0
+            ? exact
+            : available.filter((model) => regex.test(`${model.provider}/${model.id}`) || regex.test(model.id));
+        for (const model of matches) {
+            const key = `${model.provider}/${model.id}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            resolved.push({ model });
+        }
+    }
+    return resolved;
+}
+export function imageMimeType(path) {
+    const ext = path.split(".").pop()?.toLowerCase();
+    if (ext === "png")
+        return "image/png";
+    if (ext === "jpg" || ext === "jpeg")
+        return "image/jpeg";
+    if (ext === "gif")
+        return "image/gif";
+    if (ext === "webp")
+        return "image/webp";
+    return undefined;
+}

package/dist/agent-models.test.js

@@ -0,0 +1,40 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findModelByReference, formatModel, imageMimeType, modelSortKey, resolveScopedModels } from "./agent-models.js";
+const models = [
+    { provider: "anthropic", id: "claude-sonnet" },
+    { provider: "openai-codex", id: "gpt-5.4" },
+    { provider: "openai", id: "gpt-4.1" },
+];
+const registry = {
+    getAvailable: () => models,
+};
+test("findModelByReference resolves exact provider/model", () => {
+    const result = findModelByReference(registry, "openai-codex/gpt-5.4");
+    assert.equal(result.model?.provider, "openai-codex");
+    assert.equal(result.model?.id, "gpt-5.4");
+});
+test("findModelByReference reports ambiguity", () => {
+    const result = findModelByReference(registry, "gpt");
+    assert.match(result.error ?? "", /ambiguous/i);
+});
+test("resolveScopedModels supports wildcard matching", () => {
+    const result = resolveScopedModels(registry, ["openai*"]);
+    assert.deepEqual(result.map((item) => `${item.model.provider}/${item.model.id}`), [
+        "openai-codex/gpt-5.4",
+        "openai/gpt-4.1",
+    ]);
+});
+test("modelSortKey prioritizes openai-codex first", () => {
+    const sorted = [...models].sort((a, b) => {
+        const [ap, ak] = modelSortKey(a);
+        const [bp, bk] = modelSortKey(b);
+        return ap - bp || ak.localeCompare(bk);
+    });
+    assert.equal(sorted[0].provider, "openai-codex");
+});
+test("formatModel and imageMimeType behave as expected", () => {
+    assert.equal(formatModel({ provider: "openai", id: "gpt-4.1" }), "openai/gpt-4.1");
+    assert.equal(imageMimeType("image.png"), "image/png");
+    assert.equal(imageMimeType("doc.txt"), undefined);
+});

package/dist/agent-prompt.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadSkillsFromDir } from "@mariozechner/pi-coding-agent";
+export function getMemory(conversationDir) {
+    const parts = [];
+    for (const path of [join(conversationDir, "..", "MEMORY.md"), join(conversationDir, "MEMORY.md")]) {
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, "utf-8").trim();
+        if (text)
+            parts.push(text);
+    }
+    return parts.join("\n\n") || "(no memory yet)";
+}
+export function loadDiscordSkills(conversationDir) {
+    const map = new Map();
+    for (const dir of [join(conversationDir, "..", "skills"), join(conversationDir, "skills")]) {
+        for (const skill of loadSkillsFromDir({ dir, source: dir.includes("/skills") ? "workspace" : "channel" }).skills) {
+            map.set(skill.name, skill);
+        }
+    }
+    return [...map.values()];
+}
+export function buildAppendSystemPrompt(workspaceDir, conversationKey, memory) {
+    return `## Surface
+- You are replying through a Discord harness.
+- Keep the main reply readable.
+- Put verbose tool details in thread replies when the harness chooses to.
+
+## Workspace
+${workspaceDir}/
+├── MEMORY.md
+├── skills/
+└── ${conversationKey}/
+    ├── MEMORY.md
+    ├── log.jsonl
+    ├── context.jsonl
+    ├── attachments/
+    ├── scratch/
+    └── skills/
+
+## Memory
+${memory}
+
+## Conversation history
+- log.jsonl is the long-term, searchable source of truth.
+- context.jsonl is your active agent context.
+- Older history may be outside context; inspect log.jsonl if needed.
+
+## Extra tools
+- attach: upload a generated local file back to Discord.
+- discord_list_channels: list guild channels visible to the bot.
+- discord_resolve_channel: resolve a guild channel/category by name or ID.
+- discord_resolve_member: resolve a guild member by username, display name, or ID.
+- discord_resolve_role: resolve a guild role by name or ID.
+- discord_create_channel: create a guild text channel after approval.
+- discord_create_private_channel: create a private guild text channel after approval, optionally allowing extra members or roles.
+- discord_create_category: create a category after approval.
+- discord_rename_channel: rename a guild channel after approval.
+- discord_move_channel: move a guild channel into or out of a category after approval.
+- discord_delete_channel: delete a guild channel after approval.
+- discord_create_thread: create a thread in the current guild channel after approval.
+- discord_rename_thread: rename a thread after approval.
+- discord_archive_thread: archive or unarchive a thread after approval.
+- Use files in the conversation scratch directory for working files.
+- Use \`attach\` to upload a generated file back to Discord.
+- For Discord admin actions, confirm intent, prefer safe defaults, and use approval before creating or renaming channels or threads.`;
+}

package/dist/agent-runner.js

@@ -0,0 +1,101 @@
+import { readFileSync, existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { imageMimeType } from "./agent-models.js";
+import * as log from "./log.js";
+import { syncLogToSessionManager } from "./context.js";
+function truncate(text, max = 1800) {
+    return text.length <= max ? text : `${text.slice(0, max - 3)}...`;
+}
+function codeBlock(text, language = "") {
+    const suffix = language ? language : "";
+    return `\`\`\`${suffix}\n${text}\n\`\`\``;
+}
+function formatToolResult(params) {
+    const status = params.isError ? "✗" : "✓";
+    const title = params.label && params.label !== params.toolName ? `${status} ${params.toolName} — ${params.label}` : `${status} ${params.toolName}`;
+    const resultObj = params.result;
+    const textSummary = Array.isArray(resultObj?.content) ? resultObj.content.filter((item) => item?.type === "text" && typeof item.text === "string").map((item) => item.text).join("\n") : "";
+    if (!params.isError) {
+        return textSummary.trim() ? `**${title}** · ${(params.durationMs / 1000).toFixed(1)}s\n\n${truncate(textSummary, 1200)}` : `**${title}** · ${(params.durationMs / 1000).toFixed(1)}s`;
+    }
+    return [`**${title}** · ${(params.durationMs / 1000).toFixed(1)}s`, "", "**Args**", codeBlock(params.argsText, "json"), "", "**Result**", codeBlock(params.resultText, "json")].join("\n");
+}
+export function wireSessionUpdates(session, runState) {
+    const enqueue = (fn) => {
+        runState.queue = runState.queue.then(fn).catch((err) => {
+            log.warn("discord update failed", err instanceof Error ? err.message : String(err));
+        });
+    };
+    session.subscribe((event) => {
+        if (!runState.ctx)
+            return;
+        const ctx = runState.ctx;
+        if (event.type === "tool_execution_start") {
+            const args = event.args;
+            runState.pendingTools.set(event.toolCallId, { toolName: event.toolName, label: args.label ?? event.toolName, args: event.args, startedAt: Date.now() });
+            enqueue(() => ctx.setToolActive(true));
+        }
+        if (event.type === "tool_execution_end") {
+            const pending = runState.pendingTools.get(event.toolCallId);
+            runState.pendingTools.delete(event.toolCallId);
+            const durationMs = pending ? Date.now() - pending.startedAt : 0;
+            const argsText = pending?.args ? truncate(JSON.stringify(pending.args, null, 2), 1200) : "{}";
+            const resultText = truncate(JSON.stringify(event.result, null, 2), 1800);
+            enqueue(() => ctx.setToolActive(false));
+            if (event.isError) {
+                const reply = formatToolResult({ toolName: event.toolName, label: pending?.label, durationMs, argsText, resultText, isError: event.isError, result: event.result });
+                enqueue(() => ctx.respondInThread(reply));
+                enqueue(() => ctx.respond(`Error: ${truncate(resultText, 200)}`, false));
+            }
+        }
+        if (event.type === "message_end" && event.message.role === "assistant") {
+            const assistant = event.message;
+            if (assistant.stopReason)
+                runState.stopReason = assistant.stopReason;
+            if (assistant.errorMessage)
+                runState.errorMessage = assistant.errorMessage;
+            const text = assistant.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+            if (text.trim()) {
+                enqueue(async () => {
+                    await ctx.setWorking(false);
+                    await ctx.replaceMessage(text);
+                });
+            }
+        }
+    });
+}
+export async function runAgentTurn(params) {
+    const { ctx, conversationDir, scratchDir, sessionManager, agent, session, runState } = params;
+    await mkdir(scratchDir, { recursive: true });
+    await mkdir(conversationDir, { recursive: true });
+    syncLogToSessionManager(sessionManager, conversationDir, ctx.message.messageId);
+    agent.state.messages = sessionManager.buildSessionContext().messages;
+    session.setActiveToolsByName(session.getActiveToolNames());
+    runState.ctx = ctx;
+    runState.stopReason = "stop";
+    runState.errorMessage = undefined;
+    runState.pendingTools.clear();
+    const imageAttachments = [];
+    const otherAttachments = [];
+    for (const attachment of ctx.message.attachments) {
+        const mimeType = imageMimeType(attachment.local);
+        if (mimeType && existsSync(attachment.local)) {
+            imageAttachments.push({ type: "image", mimeType, data: readFileSync(attachment.local).toString("base64") });
+        }
+        else {
+            otherAttachments.push(attachment.local);
+        }
+    }
+    let prompt = `[${ctx.message.userName}]: ${ctx.message.text}`;
+    if (otherAttachments.length > 0)
+        prompt += `\n\n<discord_attachments>\n${otherAttachments.join("\n")}\n</discord_attachments>`;
+    await ctx.setTyping(true);
+    await ctx.setWorking(true);
+    await session.prompt(prompt, imageAttachments.length > 0 ? { images: imageAttachments } : undefined);
+    await runState.queue;
+    await ctx.setTyping(false);
+    await ctx.setWorking(false);
+    const result = { stopReason: runState.stopReason, errorMessage: runState.errorMessage };
+    runState.ctx = null;
+    return result;
+}