allaboard 0.0.0-stage → 0.5.0

package/dist/chat/slack/attachments.js

@@ -0,0 +1,348 @@
+/**
+ * Files the owner attaches to a message: checked, downloaded, and handed to Claude.
+ *
+ * A message with files arrives as `subtype: file_share` with a `files` array (measured 2026-09-25,
+ * although Slack's reference page for the `file_share` message subtype, read 2026-09-25, calls it
+ * legacy and no longer served). An image Claude can read goes into the prompt as an image part, as
+ * an image pasted into the terminal does (Agent SDK "Streaming Input", read 2026-09-25); any other
+ * file is saved to a private folder and its path joins the prompt, as a file dropped into the
+ * terminal does. A file past a limit, or one that fails to download, stops the whole message: a
+ * prompt without its attachment would mislead Claude.
+ */
+import { lstatSync } from "node:fs";
+import { lstat, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { named, texts } from "../../core/port.js";
+import { getLogger } from "../../log.js";
+import { errorName } from "../../values.js";
+import { take } from "./reply/chars.js";
+import { mrkdwnEscape } from "./reply/escape.js";
+import * as slackTexts from "./texts.js";
+// Claude's vision limits (platform.claude.com, "Vision", read 2026-09-25): JPEG, PNG, GIF and
+// WebP, 10 MB base64-encoded per image through the API, 8000x8000 px.
+export const IMAGE_TYPES = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+]);
+export const IMAGE_LIMIT = 7_500_000; // bytes, whose base64 form is 10,000,000 characters
+export const IMAGE_SIDE = 8000;
+// Per message (the maintainer, 2026-09-25): images stay in the conversation and are sent again
+// at every turn, and a request is capped at 32 MB (Vision, read 2026-09-25).
+export const IMAGES_PER_MESSAGE = 5;
+export const IMAGES_LIMIT = 15 * 1024 * 1024;
+export const FILE_LIMIT = 100 * 1024 * 1024;
+// The files that are not images Claude receives (the maintainer, 2026-09-25: the most common
+// ones, those its Read tool opens): any text/* type, which covers source code, plus these.
+export const FILE_TYPES = new Set([
+    "application/pdf",
+    "application/json",
+    "application/xml",
+    "application/yaml",
+    "application/x-yaml",
+    "application/javascript",
+    "application/x-sh",
+    "application/sql",
+    "application/toml",
+    "application/x-ipynb+json",
+]);
+// Saved files outlive a restart, since the resumed conversation names them (the maintainer,
+// 2026-09-25).
+export const KEEP_SECONDS = 3 * 24 * 3600;
+// A file's URL receives the bot token: only Slack's own file host may have it.
+export const FILE_HOST = "files.slack.com";
+const ORIGIN_PROTOCOL = "https:";
+export const DOWNLOAD_TIMEOUT_MS = 120_000;
+export const logger = getLogger("allaboard.chat.slack.attachments");
+/** A file could not be downloaded or saved; the message says why, for the owner. */
+export class DownloadFailed extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DownloadFailed";
+    }
+}
+function field(file, key) {
+    return file[key];
+}
+/** A field that is a number or a numeric string, as a whole number; absent or false reads 0. */
+function integer(value) {
+    const number = Number(value || 0);
+    return Number.isFinite(number) ? Math.trunc(number) : 0;
+}
+/**
+ * A declared size in bytes: a finite non-negative integer, as a number or as ASCII digits, and an
+ * absent or false one is 0. Null for anything else: `"999_999_999"`, non-ASCII digits, a sign or
+ * padding are not what Slack writes, and a file of that kind is refused.
+ */
+function declaredSize(value) {
+    if (value === undefined || value === null || value === false || value === 0 || value === "") {
+        return 0;
+    }
+    if (typeof value === "number")
+        return Number.isInteger(value) && value > 0 ? value : null;
+    if (typeof value !== "string" || !/^[0-9]+$/.test(value))
+        return null;
+    const size = Number(value);
+    return Number.isFinite(size) ? size : null;
+}
+/** Python's `f"{size / (1024 * 1024):.1f}MB"`: a tie rounds to even, which `toFixed` does not. */
+function megabytes(size) {
+    const value = size / (1024 * 1024);
+    // `toFixed` switches to an exponent from 1e21; Python prints every digit of the double.
+    if (value >= 1e21)
+        return `${BigInt(value)}.0MB`;
+    // Only a quarter of a megabyte is both exact in binary and a tie at one decimal.
+    const quarters = value * 4;
+    if (Number.isInteger(quarters) && quarters % 2 !== 0) {
+        const down = Math.floor(value * 10);
+        const tenths = down % 2 === 0 ? down : down + 1;
+        return `${(tenths / 10).toFixed(1)}MB`;
+    }
+    return `${value.toFixed(1)}MB`;
+}
+/** The parts of an `https://files.slack.com/...` URL; null for any other host or scheme. */
+function slackFileUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    return url.protocol === ORIGIN_PROTOCOL && url.hostname === FILE_HOST ? url : null;
+}
+/** Why `file` cannot reach Claude, as the end of `UPLOAD_FAILED`; null when it can. */
+export function refusal(file, names) {
+    const access = field(file, "file_access");
+    if ((access === undefined ? "visible" : access) !== "visible")
+        return slackTexts.UPLOAD_NOT_SHARED;
+    if (slackFileUrl(String(field(file, "url_private_download") || "")) === null) {
+        return slackTexts.UPLOAD_NOT_SHARED;
+    }
+    const mimetype = String(field(file, "mimetype") || "");
+    const size = declaredSize(field(file, "size"));
+    if (size === null)
+        return slackTexts.UPLOAD_NOT_SHARED;
+    if (mimetype.startsWith("image/")) {
+        if (!IMAGE_TYPES.has(mimetype))
+            return texts.fill(named(slackTexts.UPLOAD_IMAGE_TYPE, names), { mimetype });
+        if (size > IMAGE_LIMIT) {
+            return texts.fill(named(slackTexts.UPLOAD_IMAGE_SIZE, names), {
+                size: megabytes(size),
+                limit: megabytes(IMAGE_LIMIT),
+            });
+        }
+        const width = field(file, "original_w");
+        const height = field(file, "original_h");
+        if (integer(width) > IMAGE_SIDE || integer(height) > IMAGE_SIDE) {
+            return texts.fill(named(slackTexts.UPLOAD_IMAGE_SIDE, names), {
+                width: String(width ?? "None"),
+                height: String(height ?? "None"),
+            });
+        }
+    }
+    else if (!(mimetype.startsWith("text/") || FILE_TYPES.has(mimetype))) {
+        return texts.fill(slackTexts.UPLOAD_FILE_TYPE, { mimetype: mimetype || "unknown" });
+    }
+    else if (size > FILE_LIMIT) {
+        return texts.fill(slackTexts.UPLOAD_FILE_SIZE, {
+            size: megabytes(size),
+            limit: megabytes(FILE_LIMIT),
+        });
+    }
+    return null;
+}
+/** Why the images of one message, together, cannot reach Claude; null when they can. */
+export function imagesRefusal(files, names) {
+    const images = files.filter(isImage);
+    if (images.length > IMAGES_PER_MESSAGE) {
+        return texts.fill(named(slackTexts.UPLOAD_TOO_MANY, names), {
+            count: images.length,
+            limit: IMAGES_PER_MESSAGE,
+        });
+    }
+    let total = 0;
+    for (const file of images) {
+        const size = declaredSize(field(file, "size"));
+        // `refusal` speaks for one file; the images together are told as a whole sentence.
+        if (size === null) {
+            const name = field(file, "name") || field(file, "id");
+            return texts.fill(named(slackTexts.UPLOAD_FAILED, names), {
+                name: mrkdwnEscape(String(name ?? "None")),
+                reason: slackTexts.UPLOAD_NOT_SHARED,
+            });
+        }
+        total += size;
+    }
+    if (total > IMAGES_LIMIT) {
+        return texts.fill(named(slackTexts.UPLOAD_TOO_HEAVY, names), {
+            size: megabytes(total),
+            limit: megabytes(IMAGES_LIMIT),
+        });
+    }
+    return null;
+}
+/** Whether Claude reads this file as an image. */
+export function isImage(file) {
+    const mimetype = field(file, "mimetype");
+    return typeof mimetype === "string" && IMAGE_TYPES.has(mimetype);
+}
+/** The most bytes `download` takes of this file. */
+export function limitFor(file) {
+    return isImage(file) ? IMAGE_LIMIT : FILE_LIMIT;
+}
+/** `Name: message (cause)`, at most 200 characters, so the owner sees why and not a class alone. */
+function failureDetail(error) {
+    if (!(error instanceof Error))
+        return take(String(error), 200);
+    // A timeout carries a sentence of the runtime's own; the name says it.
+    if (error.name === "TimeoutError")
+        return "TimeoutError";
+    let detail = error.message ? `${error.name}: ${error.message}` : error.name;
+    if (error.cause instanceof Error && error.cause.message)
+        detail += ` (${error.cause.message})`;
+    return take(detail, 200);
+}
+/**
+ * The file at `url`, fetched with the bot token (Slack's file object reference, read 2026-09-25);
+ * throws `DownloadFailed` past `limit` bytes or on any failure.
+ */
+export async function download(url, token, mimetype, limit, options = {}) {
+    const target = slackFileUrl(url);
+    if (target === null) {
+        // The token goes to Slack's file host alone, whoever calls this.
+        throw new DownloadFailed(`not a ${FILE_HOST} URL`);
+    }
+    const call = options.fetch ?? fetch;
+    const timeout = AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    try {
+        const response = await call(target.href, {
+            headers: { Authorization: `Bearer ${token}` },
+            // A redirect could carry the token to another host: none is followed.
+            redirect: "manual",
+            signal,
+        });
+        if (response.status === 302) {
+            // Measured 2026-09-25: Slack's answer when the token lacks the scope.
+            throw new DownloadFailed("HTTP 302: Slack redirects instead of sending the file when the app lacks the " +
+                "`files:read` scope");
+        }
+        if (response.status !== 200)
+            throw new DownloadFailed(`HTTP ${response.status}`);
+        const contentType = (response.headers.get("content-type") ?? "").split(";")[0]?.trim();
+        if (contentType?.toLowerCase() === "text/html" && mimetype !== "text/html") {
+            throw new DownloadFailed("Slack sent a web page instead of the file: the app may lack the `files:read` scope");
+        }
+        return await readBody(response, limit);
+    }
+    catch (error) {
+        if (error instanceof DownloadFailed || options.signal?.aborted)
+            throw error;
+        throw new DownloadFailed(failureDetail(error), { cause: error });
+    }
+}
+/** The body of `response`, cut off with a `DownloadFailed` as soon as it passes `limit`. */
+async function readBody(response, limit) {
+    if (response.body === null)
+        return new Uint8Array(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        chunks.push(value);
+        length += value.length;
+        if (length > limit) {
+            await reader.cancel().catch(() => undefined);
+            throw new DownloadFailed(`larger than ${megabytes(limit)}`);
+        }
+    }
+    return Buffer.concat(chunks);
+}
+/** `.name` of a Python `PurePath`: the last part, with `.` parts and empty parts dropped. */
+function lastPart(name) {
+    // Python's Path splits on `\` only on Windows, and so does this.
+    const parts = name.split(process.platform === "win32" ? /[\\/]/ : "/");
+    return parts.filter((part) => part !== "" && part !== ".").at(-1) ?? "";
+}
+/**
+ * The file's name in the uploads folder: its Slack id first, so names never collide, and only the
+ * last part of the name, so it cannot point elsewhere.
+ */
+export function savedName(file) {
+    const id = field(file, "id");
+    if (id === undefined || id === null)
+        throw new TypeError("a Slack file has an id");
+    const name = lastPart(String(field(file, "name") || ""));
+    return name !== "" && name !== "." && name !== ".." ? `${id}-${name}` : String(id);
+}
+/** The folder is a real directory of this user that no one else can open. */
+function isPrivate(folder) {
+    let info;
+    try {
+        info = lstatSync(folder);
+    }
+    catch {
+        return false;
+    }
+    if (!info.isDirectory())
+        return false;
+    // Windows has no owner id and no mode bits to read.
+    if (process.platform === "win32")
+        return true;
+    return info.uid === process.getuid?.() && (info.mode & 0o077) === 0;
+}
+/** Remove the saved files older than `KEEP_SECONDS`, from a folder only the owner can read. */
+export async function prepareUploads(folder, now = Date.now) {
+    await mkdir(folder, { mode: 0o700, recursive: true });
+    if (!isPrivate(folder)) {
+        // Never touched: `save` refuses to write there, and old files are not removed.
+        logger.warning(`the uploads folder ${folder} is not private: it is left untouched`);
+        return;
+    }
+    const cutoff = now() - KEEP_SECONDS * 1000;
+    for (const name of await readdir(folder)) {
+        const path = join(folder, name);
+        try {
+            if ((await lstat(path)).mtimeMs < cutoff)
+                await unlink(path);
+        }
+        catch {
+            // A file that vanished or cannot be removed stays for the next start.
+        }
+    }
+}
+/** Write `data` as the file's saved copy and return its path; the folder must be private. */
+export async function save(folder, file, data) {
+    // macOS may clean the temporary folder while the daemon runs.
+    await mkdir(folder, { mode: 0o700, recursive: true });
+    if (!isPrivate(folder)) {
+        throw new DownloadFailed(`could not be saved (the uploads folder ${folder} is not private)`);
+    }
+    const path = join(folder, savedName(file));
+    try {
+        await writeFile(path, data);
+    }
+    catch (error) {
+        throw new DownloadFailed(`could not be saved (${errorName(error)})`, { cause: error });
+    }
+    return path;
+}
+/** The owner's text with the saved files' paths; with images, one message of content parts. */
+export function promptFor(text, images, paths) {
+    if (paths.length > 0) {
+        const listed = paths.map((path) => `- ${path}`).join("\n");
+        text = text ? `${text}\n\nAttached files:\n${listed}` : `Attached files:\n${listed}`;
+    }
+    if (images.length === 0)
+        return text;
+    const parts = text ? [{ type: "text", text }] : [];
+    for (const { mediaType, data } of images) {
+        parts.push({ type: "image", mediaType, data: Buffer.from(data).toString("base64") });
+    }
+    return parts;
+}

package/dist/chat/slack/bind.js

@@ -0,0 +1,67 @@
+/**
+ * `!bind` alone, as Slack shows it: one row per folder `src/core/folders.ts` found, a Bind button
+ * each.
+ */
+import { relative, sep } from "node:path";
+import { FOLDER_ROWS, fill, named, texts } from "../../core/port.js";
+import { compareCodePoints } from "../../text.js";
+import { contextBlock } from "./reply/blocks.js";
+import { shownAsWritten } from "./reply/escape.js";
+import * as slackTexts from "./texts.js";
+export const BIND_ACTION = "folder_bind";
+/** A path's components as `PurePosixPath` compares them: no empty or `.` part. */
+function parts(path) {
+    return path.split("/").filter((part) => part !== "" && part !== ".");
+}
+function samePath(a, b) {
+    const left = parts(a);
+    const right = parts(b);
+    return left.length === right.length && left.every((part, i) => part === right[i]);
+}
+/** Paths sort by components as Python sorts a `Path`, so `a/b` comes before `a-b`. */
+function comparePaths(a, b) {
+    const left = parts(a);
+    const right = parts(b);
+    for (let i = 0; i < Math.min(left.length, right.length); i += 1) {
+        const order = compareCodePoints(left[i], right[i]);
+        if (order !== 0)
+            return order;
+    }
+    return left.length - right.length;
+}
+function row(root, index, folder, current) {
+    const shown = relative(root, folder).split(sep).join("/") || ".";
+    const block = {
+        type: "section",
+        // An index, not the path: a block_id is capped at 255 characters.
+        block_id: `folder-${index}`,
+        text: {
+            type: "mrkdwn",
+            text: `\`${shownAsWritten(shown)}\`${current ? slackTexts.BIND_CURRENT : ""}`,
+        },
+    };
+    if (!current) {
+        block.accessory = {
+            type: "button",
+            action_id: BIND_ACTION,
+            value: shown,
+            text: { type: "plain_text", text: slackTexts.BIND_BUTTON },
+        };
+    }
+    return block;
+}
+/** The list: the first FOLDER_ROWS folders in path order, the channel's own marked. */
+export function bindBlocks(root, folders, current, names) {
+    const shown = folders.slice(0, FOLDER_ROWS).toSorted(comparePaths);
+    // The list's own lines are the daemon's notices, small and grey; the rows keep their button.
+    if (folders.length === 0) {
+        return [contextBlock(fill(named(texts.BIND_EMPTY, names), { root: shownAsWritten(root) }))];
+    }
+    return [
+        contextBlock(fill(named(texts.BIND_LIST, names), { root: shownAsWritten(root) })),
+        ...shown.map((folder, i) => row(root, i, folder, current !== null && samePath(folder, current))),
+        ...(folders.length > FOLDER_ROWS
+            ? [contextBlock(fill(slackTexts.BIND_MORE, { rows: FOLDER_ROWS }))]
+            : []),
+    ];
+}

package/dist/chat/slack/channel.js

@@ -0,0 +1,67 @@
+import { getLogger } from "../../log.js";
+import { bindBlocks } from "./bind.js";
+import { crossing, deliver, deliverNotice, rewriteAsNotice } from "./notice.js";
+import { split } from "./reply/blocks.js";
+import { describe } from "./reply/errors.js";
+import { resumeBlocks } from "./resume.js";
+import { updateBlocks } from "./update.js";
+export const logger = getLogger("allaboard.chat.slack.channel");
+export class SlackChannel {
+    #channel;
+    #parts;
+    constructor(channel, parts) {
+        this.#channel = channel;
+        this.#parts = parts;
+    }
+    async notice(text) {
+        if (this.#parts.stopped.aborted)
+            return null;
+        const { slack, ownerUserId } = this.#parts;
+        return crossing(() => deliverNotice(slack, ownerUserId, { channel: this.#channel, threadTs: null }, text, {
+            ephemeral: false,
+        }));
+    }
+    async say(markdown) {
+        const { slack, ownerUserId, stopped } = this.#parts;
+        for (const chunk of split(markdown)) {
+            if (stopped.aborted)
+                return;
+            await crossing(() => deliver(slack, ownerUserId, { channel: this.#channel, threadTs: null }, chunk, [{ type: "markdown", text: chunk }], { ephemeral: false }));
+        }
+    }
+    async offer(list, title) {
+        const { slack, ownerUserId, clock, stopped, names } = this.#parts;
+        if (stopped.aborted)
+            return;
+        const blocks = list.type === "folders"
+            ? bindBlocks(list.root, [...list.folders], list.bound, names())
+            : list.type === "update"
+                ? updateBlocks(list, title)
+                : resumeBlocks(list.folder, list.sessions, list.held, new Date(clock.time() * 1000), list.thread.thread);
+        await crossing(() => deliver(slack, ownerUserId, { channel: this.#channel, threadTs: null }, title, blocks, {
+            ephemeral: false,
+        }));
+    }
+    async withdraw(list) {
+        try {
+            await this.#parts.slack.chat.delete({ channel: this.#channel, ts: list });
+            return true;
+        }
+        catch (error) {
+            logger.warning(`could not delete a list in ${this.#channel}: ${describe(error)}`);
+            return false;
+        }
+    }
+    async rewrite(list, text) {
+        await rewriteAsNotice(this.#parts.slack, this.#parts.limiter, this.#channel, list, text);
+    }
+    /** Slack's "Only visible to you": an ephemeral message in the channel, for the owner. */
+    async tell(text) {
+        if (this.#parts.stopped.aborted)
+            return;
+        const { slack, ownerUserId } = this.#parts;
+        await crossing(() => deliverNotice(slack, ownerUserId, { channel: this.#channel, threadTs: null }, text, {
+            ephemeral: true,
+        }));
+    }
+}

package/dist/chat/slack/channels.js

@@ -0,0 +1,43 @@
+/** What the daemon asks Slack about the channels it is bound to, and the threads in them. */
+import { ChatError } from "../seam.js";
+import { THREAD_NOT_FOUND } from "./delete.js";
+import { describe } from "./reply/errors.js";
+const CHANNEL_NOT_FOUND = "channel_not_found";
+/**
+ * What the cleanup asks about a bound channel: `conversations.info`. Only `channel_not_found` is
+ * an answer that the channel is gone; any other failure crosses as a `ChatError` named by
+ * Slack's code, which the cleanup logs as no answer.
+ */
+export function channelLookup(slack) {
+    return async (channelId) => {
+        try {
+            await slack.conversations.info({ channel: channelId });
+            return "there";
+        }
+        catch (error) {
+            const code = describe(error);
+            if (code === CHANNEL_NOT_FOUND)
+                return "gone";
+            throw new ChatError(code, { cause: error });
+        }
+    };
+}
+/**
+ * What the cleanup asks about a thread: `conversations.replies` on its root with `limit=1`, which
+ * a deleted root answers with `thread_not_found` (measured 2026-10-01, see `home.ts`). Only that
+ * code says the thread is gone; any other failure crosses as a `ChatError` named by Slack's code.
+ */
+export function threadLookup(slack) {
+    return async (ref) => {
+        try {
+            await slack.conversations.replies({ channel: ref.channel, ts: ref.thread, limit: 1 });
+            return "there";
+        }
+        catch (error) {
+            const code = describe(error);
+            if (code === THREAD_NOT_FOUND)
+                return "gone";
+            throw new ChatError(code, { cause: error });
+        }
+    };
+}