pi-mom-slack 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: one pi session per Slack thread, mentions, direct messages and thread follow-ups, attachments, `slack_upload` tool, reactions, `!stop`, `!status`, `!model`, `!help`, resume after restart.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Suau
+
+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

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# pi-mom-slack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run the [pi coding agent](https://github.com/earendil-works/pi-mono) in Slack. Mention it in a channel or write to it directly: each Slack thread gets its own pi session and its own working directory, kept across restarts.
+
+```sh
+npx pi-mom-slack
+```
+
+<p align="center"><img src="docs/screenshots/hero.jpg" alt="A request in #demo: 👀, then the thread with the status line, the uploaded primes.txt, the report, and ✅" width="85%"></p>
+
+Inspired by `mom`, the Slack bot removed from pi-mono on 30 April 2026. Not affiliated with Earendil.
+
+## What you get
+
+- **One pi session per thread.** Follow-ups in the thread keep the context, even after the bot restarts.
+- **Mentions, direct messages, and plain replies** in a thread the bot already answers.
+- **Files both ways.** Attachments land in the thread's working directory (images go to the model when it reads them); the agent sends files back with its `slack_upload` tool.
+- **Visible progress.** 👀 on your message, a status line updated as tools run, then ✅ or ⚠️.
+- **Commands:** `!stop`, `!status`, `!model`, `!help`.
+- **Robust by default.** A run cut by a restart resumes on its own (at most twice), a Slack connection that stays down makes the process exit for its supervisor to restart it, the startup message says why the bot restarted, the agent's shell never sees the Slack tokens or other credentials, and a second process on the same app is detected.
+- **Your pi, as configured.** Model, credentials and skills come from `~/.pi/agent/`, like `pi` in your terminal.
+
+## Setup (5 minutes)
+
+You need Node.js 22.19 or later, and pi set up on the machine that runs the bot: run `npx @earendil-works/pi-coding-agent` once and log in with `/login` (or set your provider's API key).
+
+### 1. Create the Slack app
+
+**[Create the app from the manifest](https://api.slack.com/apps?new_app=1&manifest_json=%7B%22display_information%22%3A%7B%22name%22%3A%22pi%22%2C%22description%22%3A%22pi%20coding%20agent%20in%20Slack%22%7D%2C%22features%22%3A%7B%22app_home%22%3A%7B%22home_tab_enabled%22%3Afalse%2C%22messages_tab_enabled%22%3Atrue%2C%22messages_tab_read_only_enabled%22%3Afalse%7D%2C%22bot_user%22%3A%7B%22display_name%22%3A%22pi%22%2C%22always_online%22%3Atrue%7D%7D%2C%22oauth_config%22%3A%7B%22scopes%22%3A%7B%22bot%22%3A%5B%22app_mentions%3Aread%22%2C%22chat%3Awrite%22%2C%22channels%3Ahistory%22%2C%22groups%3Ahistory%22%2C%22im%3Ahistory%22%2C%22im%3Aread%22%2C%22im%3Awrite%22%2C%22files%3Aread%22%2C%22files%3Awrite%22%2C%22reactions%3Awrite%22%2C%22users%3Aread%22%5D%7D%7D%2C%22settings%22%3A%7B%22event_subscriptions%22%3A%7B%22bot_events%22%3A%5B%22app_mention%22%2C%22message.channels%22%2C%22message.groups%22%2C%22message.im%22%5D%7D%2C%22interactivity%22%3A%7B%22is_enabled%22%3Afalse%7D%2C%22org_deploy_enabled%22%3Afalse%2C%22socket_mode_enabled%22%3Atrue%2C%22token_rotation_enabled%22%3Afalse%7D%7D)** (opens Slack with everything filled in), pick your workspace, click **Next**, review, and click **Create**.
+
+Or by hand: [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From a manifest** → paste [`manifest.json`](manifest.json).
+
+<p>
+  <img src="docs/screenshots/01-pick-workspace.jpg" alt="Create from a manifest: the JSON is already filled in; pick a workspace, then Next" width="49%">
+  <img src="docs/screenshots/02-review-app.jpg" alt="Review your app, then Create" width="38%">
+</p>
+
+### 2. Get the two tokens
+
+- **App token (`xapp-…`)**: **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes**, any name, scope `connections:write`.
+- **Bot token (`xoxb-…`)**: **Install App** → **Install to Workspace** → allow, then copy the **Bot User OAuth Token**.
+
+<details>
+<summary>Screenshots</summary>
+
+<img src="docs/screenshots/03-app-level-token.jpg" alt="Generate an app-level token with the connections:write scope" width="70%">
+
+<img src="docs/screenshots/04-install-app.jpg" alt="Install App page" width="70%">
+
+<img src="docs/screenshots/05-allow.jpg" alt="Allow the app in the workspace" width="70%">
+
+<img src="docs/screenshots/06-bot-token.jpg" alt="Bot User OAuth Token, masked" width="70%">
+
+</details>
+
+### 3. Find your Slack member ID
+
+In Slack: your profile → **⋯** → **Copy member ID** (it looks like `U012ABCDEF`). Only the IDs you list can talk to the bot.
+
+<details>
+<summary>Screenshot</summary>
+
+<img src="docs/screenshots/09-member-id.jpg" alt="Profile, More, Copy member ID" width="70%">
+
+</details>
+
+### 4. Run it
+
+Create a `.env` file where you run the bot:
+
+```sh
+SLACK_APP_TOKEN=xapp-…
+SLACK_BOT_TOKEN=xoxb-…
+PI_SLACK_ALLOWED_USERS=U012ABCDEF,U034GHIJKL
+```
+
+Then:
+
+```sh
+npx pi-mom-slack
+```
+
+The bot sends you a direct message when it is up. In a channel, invite it with `/invite @pi` (the name you gave the app; the screenshots use `pi-mom-demo`), then mention it: `@pi write a script that…`. In a direct message, just write.
+
+<details>
+<summary>Screenshots</summary>
+
+<img src="docs/screenshots/07-invite.jpg" alt="/invite in a channel" width="70%">
+
+<img src="docs/screenshots/08-added-to-channel.jpg" alt="The bot has joined #demo" width="70%">
+
+</details>
+
+<img src="docs/screenshots/10-startup-dm.jpg" alt="Startup message: pi-mom-slack is up. First start." width="70%">
+
+## Using it
+
+| You do | The bot |
+|---|---|
+| `@pi <request>` in a channel | starts a thread with its own pi session |
+| reply in that thread | continues the same session, no mention needed |
+| write to it directly | answers in a thread under your message; reply there to continue |
+| attach files | saves them in the thread's working directory under `files/` |
+| `!stop` | stops the current run |
+| `!status` | idle or running (who, for how long), model, working directory |
+| `!model` | lists the models you have credentials for |
+| `!model sonnet` | switches this thread's model (exact `provider/id` or a unique part of it) |
+| `!model default sonnet` | also changes pi's default model |
+| `!help` | lists the commands |
+
+<img src="docs/screenshots/12-server-report.jpg" alt="Running on a server: the agent writes a system report, uploads it to the thread and sums it up" width="40%">
+<img src="docs/screenshots/11-model.jpg" alt="!model lists the models pi has credentials for" width="40%">
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `SLACK_APP_TOKEN` | required | app-level token, `xapp-…` |
+| `SLACK_BOT_TOKEN` | required | bot token, `xoxb-…` |
+| `PI_SLACK_ALLOWED_USERS` | required | Slack member IDs, comma separated |
+| `PI_SLACK_DATA_DIR` | `~/.pi/slack` | thread working directories, run markers, state |
+| `PI_SLACK_ENV_FILE` | `./.env` | file read for the variables above |
+| `PI_SLACK_DEBUG` | | logs the type of each Slack event |
+| `PI_SLACK_SOCKET_DOWN_LIMIT_MS` | `180000` | if the Slack connection stays down this long, the process exits so a supervisor restarts it |
+
+Variables already set in the environment win over the file. Everything read from the file, plus any variable whose name looks like a credential (`TOKEN`, `SECRET`, `API_KEY`, `PASSWORD`…), is removed from the environment of the agent's shell. pi itself still reads your provider keys.
+
+The model, thinking level, skills and context files (`AGENTS.md`) come from pi's own configuration. pi extensions are not loaded, since many expect a terminal.
+
+## Running it as a service
+
+Keep **one** process per Slack app: Slack spreads events across connections at random, so a second process with the same tokens silently takes some messages. The bot warns you in a direct message when it sees more than one connection.
+
+On a server you reach over SSH, from the folder that holds your `.env`:
+
+```sh
+scripts/deploy-ssh.sh my-server        # sends this commit, builds, copies .env, starts a user systemd service
+ssh my-server journalctl --user -u pi-mom-slack -f
+```
+
+The server needs Node.js 22.19+, pi logged in, and linger for your user (`sudo loginctl enable-linger $USER`, once), so the service keeps running after you log out. It needs no GitHub access. Run the script again to update.
+
+Or write the user systemd unit yourself, for example:
+
+```ini
+# ~/.config/systemd/user/pi-mom-slack.service
+[Unit]
+Description=pi in Slack
+After=network-online.target
+
+[Service]
+WorkingDirectory=%h/pi-slack
+ExecStart=/usr/bin/env npx --yes pi-mom-slack@0.1.0
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+```sh
+systemctl --user enable --now pi-mom-slack
+sudo loginctl enable-linger $USER   # keep it running after logout
+```
+
+Pin the version and update it on purpose: the startup message lists what changed. `pi-mom-slack@latest` also works, but then every restart may run a release you have not read, including the automatic pi updates. Under systemd, `npx` must be on the unit's `PATH` (with nvm, set `Environment=PATH=…` to nvm's `bin` folder), or use `scripts/deploy-ssh.sh`, which does it for you.
+
+## Security
+
+The agent runs pi's tools, `bash` included, as the user running the bot, on that machine. Treat access to the bot like shell access: list only people you would give a shell to, and run it under a dedicated user or in a container if the machine holds anything sensitive. Removing credentials from the agent's shell prevents mistakes, not a determined agent.
+
+## Extending it
+
+The package is also a library. `createSlackBot` takes the same settings as the CLI, plus extension points:
+
+```ts
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { configFromEnv, createSlackBot } from "pi-mom-slack";
+
+const bot = createSlackBot({
+  ...configFromEnv(),              // tokens, allowed users, data dir (or pass them yourself)
+  systemNote: "You work for the data team. Answer in English.",
+  customTools: (thread) => [       // extra pi tools, built per thread
+    defineTool({
+      name: "deploy_preview",
+      label: "Deploy a preview",
+      description: "Deploy the working directory as a preview.",
+      parameters: Type.Object({}),
+      execute: async () => ({ content: [{ type: "text", text: await deploy(thread.workspace) }], details: {} }),
+    }),
+  ],
+  commands: {                      // !version in a thread
+    version: () => "build 42",
+  },
+  hooks: {
+    beforeRun: ({ text, user }) => text,           // return a string to change what the model receives
+    afterRun: ({ thread }, result, error) => {},   // after each run, successful or not
+    onStart: ({ reason }) => {},                   // once connected
+  },
+});
+
+await bot.start();
+// later: await bot.stop("SIGTERM");
+```
+
+`thread` gives `key`, `channel`, `threadTs`, `workspace`, and `post(text)` / `upload(file, name)` for the thread. A complete example: [`examples/custom-bot.ts`](examples/custom-bot.ts).
+
+## Staying current with pi
+
+A daily GitHub Action checks for a new pi release. When the tests pass with it, a new patch version of pi-mom-slack is published; when they fail, pi itself is asked to fix the code and the fix arrives as a pull request reviewed by a human. Nothing is published without green tests. See [`.github/workflows/release.yml`](.github/workflows/release.yml). For a fork: set the `OPENROUTER_API_KEY` secret (and optionally a `PI_MODEL` variable, `provider/model`), and configure npm trusted publishing for `release.yml`.
+
+## Development
+
+```sh
+npm install
+npm test        # no network: Slack is faked, pi runs against a local scripted model
+npm run check
+npm start       # runs src/cli.ts directly
+```
+
+## License
+
+MIT

package/dist/agent-env.d.ts

@@ -0,0 +1 @@
+export declare function scrubEnv(env: NodeJS.ProcessEnv, secretNames?: Iterable<string>): NodeJS.ProcessEnv;

package/dist/agent-env.js

@@ -0,0 +1,16 @@
+/**
+ * Environment given to the agent's shell. The bot's own secrets (everything read from the env file, the Slack tokens,
+ * and anything that looks like a credential) are removed, so a command run by the agent cannot use them by accident.
+ *
+ * This guards against mistakes, not against a hostile agent: the shell runs as the same user as the bot.
+ */
+const CREDENTIAL = /(TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL)/i;
+export function scrubEnv(env, secretNames = []) {
+    const out = { ...env };
+    for (const name of secretNames)
+        delete out[name];
+    for (const name of Object.keys(out))
+        if (CREDENTIAL.test(name))
+            delete out[name];
+    return out;
+}

package/dist/agent.d.ts

@@ -0,0 +1,59 @@
+import type { ImageContent } from "@earendil-works/pi-ai";
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+/** What tools, commands and hooks know about the thread they act in. */
+export interface ThreadInfo {
+    /** Filesystem-safe id of the thread: `<channel>-<ts>`. */
+    key: string;
+    channel: string;
+    threadTs: string;
+    /** The agent's working directory for this thread. */
+    workspace: string;
+    /** Posts a message in the thread. */
+    post(text: string): Promise<void>;
+    /** Uploads a file into the thread. */
+    upload(file: Buffer, filename: string, comment?: string): Promise<void>;
+}
+export interface RunResult {
+    text: string;
+    aborted: boolean;
+    tools: number;
+}
+export declare const DEFAULT_SYSTEM_NOTE: string;
+export declare const CONTINUE_PROMPT = "Continue: do what you just announced now, without stopping on an announcement. End with the short report (done, files, left).";
+/** A final reply that only announces work ("I'll now…", "Je vais…") instead of reporting it. */
+export declare function looksLikeAnnouncement(text: string): boolean;
+export declare function threadKey(channel: string, threadTs: string): string;
+export interface ThreadAgentsOptions {
+    dataDir: string;
+    systemNote?: string;
+    customTools?: (thread: ThreadInfo) => ToolDefinition[] | Promise<ToolDefinition[]>;
+    /** Variable names removed from the agent's shell, on top of credential-looking names. */
+    secretNames?: string[];
+}
+export declare class ThreadAgents {
+    private sessions;
+    private busy;
+    private processes;
+    private options;
+    constructor(options: ThreadAgentsOptions);
+    workspaceOf(key: string): string;
+    busyInfo(key: string): {
+        since: number;
+        user?: string;
+    } | undefined;
+    isBusy(key: string): boolean;
+    private session;
+    /** Runs one prompt to completion. The system note is added to the first message of a thread. */
+    run(thread: ThreadInfo, text: string, opts?: {
+        onTool?: (name: string) => void;
+        images?: ImageContent[];
+        user?: string;
+    }): Promise<RunResult>;
+    /** Model of the thread, for !status. */
+    modelLabel(thread: ThreadInfo): Promise<string>;
+    describeModels(thread: ThreadInfo): Promise<string>;
+    /** Switches the thread's model (kept in its session); with persist, also pi's default model. */
+    switchModel(thread: ThreadInfo, spec: string, persist: boolean): Promise<string>;
+    abort(key: string): Promise<boolean>;
+    disposeAll(): Promise<void>;
+}

package/dist/agent.js

@@ -0,0 +1,142 @@
+/**
+ * One pi session per Slack thread. Each thread gets its own working directory; pi persists the session and picks it
+ * up again after a restart (SessionManager.continueRecent), so a thread keeps its context.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createAgentSession, createBashToolDefinition, DefaultResourceLoader, getAgentDir, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { scrubEnv } from "./agent-env.js";
+import { formatModels, label, resolveModel } from "./models.js";
+import { RunProcesses } from "./run-processes.js";
+import { slackUploadTool } from "./upload-tool.js";
+export const DEFAULT_SYSTEM_NOTE = [
+    "You are pi, working for the team through Slack. Reply in the language of the user, directly and briefly. Slack renders *bold*, _italic_, `code` and ``` blocks, not Markdown headings or tables.",
+    "Your current working directory belongs to this Slack thread: create and edit your files here.",
+    "To share a file in the thread, use the slack_upload tool.",
+    "End with a short report: what is done, where the files are, what is left.",
+].join("\n");
+export const CONTINUE_PROMPT = "Continue: do what you just announced now, without stopping on an announcement. End with the short report (done, files, left).";
+/** A final reply that only announces work ("I'll now…", "Je vais…") instead of reporting it. */
+export function looksLikeAnnouncement(text) {
+    const t = text.trim();
+    if (!t || t.length > 600 || t.includes("?"))
+        return false;
+    const last = t.split(/(?<=[.!:…])\s+|\n+/).filter(Boolean).pop() ?? t;
+    return /\b(let me|i'll|i will|i'm going to|i am going to|now i|next,? i|je vais|je m'en occupe|je commence|je lance|je passe à|je m'y mets|allons-y)\b/i.test(last) || /:\s*$/.test(t);
+}
+export function threadKey(channel, threadTs) {
+    return `${channel}-${threadTs.replace(".", "_")}`;
+}
+const BUILTIN = ["read", "ls", "find", "grep", "bash", "edit", "write"];
+const MAX_CONTINUES = 2;
+export class ThreadAgents {
+    sessions = new Map();
+    busy = new Map();
+    processes = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    workspaceOf(key) {
+        return join(this.options.dataDir, "threads", key);
+    }
+    busyInfo(key) {
+        return this.busy.get(key);
+    }
+    isBusy(key) {
+        return this.busy.has(key);
+    }
+    session(thread) {
+        let s = this.sessions.get(thread.key);
+        if (!s) {
+            const cwd = thread.workspace;
+            mkdirSync(cwd, { recursive: true });
+            const processes = new RunProcesses();
+            this.processes.set(thread.key, processes);
+            const secretNames = this.options.secretNames ?? [];
+            s = (async () => {
+                const loader = new DefaultResourceLoader({ cwd, agentDir: getAgentDir(), noExtensions: true });
+                await loader.reload();
+                const bash = createBashToolDefinition(cwd, { operations: processes.operations(), spawnHook: (c) => ({ ...c, env: scrubEnv(c.env, secretNames) }) });
+                const extra = (await this.options.customTools?.(thread)) ?? [];
+                const customTools = [bash, slackUploadTool(cwd, thread.upload), ...extra];
+                const tools = [...new Set([...BUILTIN, ...customTools.map((t) => t.name)])];
+                const result = await createAgentSession({ cwd, resourceLoader: loader, tools, customTools, sessionManager: SessionManager.continueRecent(cwd) });
+                return result.session;
+            })();
+            s.catch(() => this.sessions.delete(thread.key));
+            this.sessions.set(thread.key, s);
+        }
+        return s;
+    }
+    /** Runs one prompt to completion. The system note is added to the first message of a thread. */
+    async run(thread, text, opts = {}) {
+        this.busy.set(thread.key, { since: Date.now(), user: opts.user });
+        let tools = 0;
+        let aborted = false;
+        let unsubscribe = () => { };
+        try {
+            const session = await this.session(thread);
+            const isFirst = session.messages.length === 0;
+            const note = this.options.systemNote ?? DEFAULT_SYSTEM_NOTE;
+            const prompt = [isFirst ? note : "", text].filter(Boolean).join("\n\n");
+            unsubscribe = session.subscribe((e) => {
+                if (e.type === "tool_execution_start") {
+                    tools += 1;
+                    opts.onTool?.(e.toolName);
+                }
+                if (e.type === "agent_settled")
+                    aborted = e.aborted;
+            });
+            const images = opts.images ?? [];
+            const readsImages = session.model?.input?.includes("image") ?? false;
+            const imageNote = images.length && !readsImages ? "\n\n(The current model does not read images: they are only saved in files/.)" : "";
+            await session.prompt(prompt + imageNote, readsImages && images.length ? { images } : undefined);
+            // Models sometimes end the turn on "I will now…": push the work through instead of leaving an announcement.
+            for (let i = 0; i < MAX_CONTINUES && !aborted && looksLikeAnnouncement(session.getLastAssistantText() ?? ""); i++) {
+                await session.prompt(CONTINUE_PROMPT);
+            }
+            return { text: session.getLastAssistantText() ?? "", aborted, tools };
+        }
+        finally {
+            this.processes.get(thread.key)?.cleanup();
+            unsubscribe();
+            this.busy.delete(thread.key);
+        }
+    }
+    /** Model of the thread, for !status. */
+    async modelLabel(thread) {
+        const session = await this.session(thread);
+        return session.model ? label(session.model) : "(pi default)";
+    }
+    async describeModels(thread) {
+        const session = await this.session(thread);
+        return formatModels(await session.modelRuntime.getAvailable(), session.model);
+    }
+    /** Switches the thread's model (kept in its session); with persist, also pi's default model. */
+    async switchModel(thread, spec, persist) {
+        if (this.busy.has(thread.key))
+            throw new Error("A run is in progress in this thread: switch after it, or `!stop` first.");
+        const session = await this.session(thread);
+        const found = resolveModel(spec, await session.modelRuntime.getAvailable());
+        if ("error" in found)
+            throw new Error(found.error);
+        await session.setModel(found.model, { persist });
+        return persist ? `Model of this thread and pi's default: \`${label(found.model)}\`.` : `Model of this thread: \`${label(found.model)}\`.`;
+    }
+    async abort(key) {
+        const s = this.sessions.get(key);
+        if (!s || !this.busy.has(key))
+            return false;
+        await (await s).abort();
+        return true;
+    }
+    async disposeAll() {
+        for (const s of this.sessions.values())
+            (await s.catch(() => null))?.dispose();
+        this.sessions.clear();
+        for (const p of this.processes.values())
+            p.cleanup();
+        this.processes.clear();
+    }
+}

package/dist/attachments.d.ts

@@ -0,0 +1,11 @@
+import type { ImageContent } from "@earendil-works/pi-ai";
+import type { SlackFile } from "./slack.ts";
+export declare const MAX_FILE: number;
+export interface Attachments {
+    /** Paths relative to the workspace. */
+    saved: string[];
+    images: ImageContent[];
+    errors: string[];
+}
+export declare function safeName(name: string, index: number): string;
+export declare function saveAttachments(files: SlackFile[], workspace: string, download: (url: string, maxBytes: number) => Promise<Buffer>, stamp?: number): Promise<Attachments>;

package/dist/attachments.js

@@ -0,0 +1,34 @@
+/**
+ * Slack attachments: every file is saved in the thread workspace (files/<stamp>/), so the agent can use it with its
+ * tools; images are also returned inline, for models that read images.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+export const MAX_FILE = 25 * 1024 * 1024;
+const MAX_IMAGE = 5 * 1024 * 1024;
+const IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+export function safeName(name, index) {
+    const clean = basename(name).replace(/[^\p{L}\p{N}._-]+/gu, "_").replace(/^\.+/, "") || "file";
+    return `${String(index + 1).padStart(2, "0")}-${clean}`.slice(0, 120);
+}
+export async function saveAttachments(files, workspace, download, stamp = Date.now()) {
+    const out = { saved: [], images: [], errors: [] };
+    if (files.length === 0)
+        return out;
+    const rel = join("files", String(stamp));
+    mkdirSync(join(workspace, rel), { recursive: true });
+    for (const [i, f] of files.entries()) {
+        try {
+            const buf = await download(f.url, MAX_FILE);
+            const path = join(rel, safeName(f.name, i));
+            writeFileSync(join(workspace, path), buf);
+            out.saved.push(path);
+            if (IMAGE_TYPES.has(f.mimetype) && buf.length <= MAX_IMAGE)
+                out.images.push({ type: "image", data: buf.toString("base64"), mimeType: f.mimetype });
+        }
+        catch (e) {
+            out.errors.push(`${f.name}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return out;
+}

package/dist/bot.d.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type RunResult, type ThreadInfo } from "./agent.ts";
+export interface CommandContext {
+    thread: ThreadInfo;
+    /** Text after the command name, trimmed. */
+    args: string;
+    user: string;
+    reply(text: string): Promise<void>;
+}
+/** A `!name` command. Returned text is posted in the thread. */
+export type Command = (ctx: CommandContext) => Promise<string | void> | string | void;
+export interface RunContext {
+    thread: ThreadInfo;
+    user: string;
+    /** Text given to the model (mentions resolved, attachments listed). */
+    text: string;
+    /** True when the run resumes after a restart. */
+    resumed: boolean;
+}
+export interface SlackBotHooks {
+    /** Before each run. Return a string to replace the text given to the model. */
+    beforeRun?: (ctx: RunContext) => Promise<string | void> | string | void;
+    /** After each run, successful or not (`error` is set when it failed). */
+    afterRun?: (ctx: RunContext, result: RunResult | undefined, error?: unknown) => Promise<void> | void;
+    /** Once connected to Slack. `reason` explains how the previous process ended. */
+    onStart?: (info: {
+        reason: string;
+        botUserId: string;
+    }) => Promise<void> | void;
+}
+export interface SlackBotOptions {
+    appToken: string;
+    botToken: string;
+    /** Slack member IDs allowed to talk to the bot. Required, never empty. */
+    allowedUsers: string[];
+    /** Root of thread workspaces, run markers and the state file. */
+    dataDir: string;
+    /** Added to the first message of every thread. Defaults to DEFAULT_SYSTEM_NOTE. */
+    systemNote?: string;
+    /** Extra pi tools, built for each thread. */
+    customTools?: (thread: ThreadInfo) => ToolDefinition[] | Promise<ToolDefinition[]>;
+    /** Extra `!name` commands (key without the "!"). Built-in commands win on a name clash. */
+    commands?: Record<string, Command>;
+    hooks?: SlackBotHooks;
+    /** Variable names removed from the agent's shell, on top of the Slack tokens and credential-looking names. */
+    secretNames?: string[];
+    /** Direct message to allowed users at startup (reason of the restart). Default true. */
+    notifyOnStart?: boolean;
+}
+export interface SlackBotHandle {
+    start(): Promise<void>;
+    /** Stops cleanly. `signal` is recorded in the state file for the next startup message. */
+    stop(signal?: string): Promise<void>;
+}
+export declare const RESUME_PROMPT = "Resume the work interrupted by the restart. Re-read the context and check the actual state before going on; say what is left if you cannot resume.";
+export declare function createSlackBot(options: SlackBotOptions): SlackBotHandle;
+/** Records a fatal error in the state file, so the next startup message explains it. */
+export declare function recordCrash(dataDir: string, err: unknown): void;