allaboard 0.5.0 → 0.6.0

package/dist/chat/slack/module.js

@@ -6,16 +6,23 @@
  */
 import { createHash } from "node:crypto";
 import { ConfigError, } from "../../core/port.js";
+import { getLogger } from "../../log.js";
+import { setupGuide } from "../../version.js";
 import { ChatError } from "../seam.js";
 import { socketReceiver } from "./app/app.js";
 import { ChannelGuard } from "./app/guards.js";
 import { prepareUploads } from "./attachments.js";
 import { ThreadDeleter } from "./delete.js";
 import { Home } from "./home.js";
+import { slackSetup } from "./onboarding.js";
 import { repliesClient, sharedClient } from "./reply/clients.js";
 import { describe } from "./reply/errors.js";
 import { UpdateLimiter } from "./reply/limiter.js";
+import { RootEditor } from "./tag.js";
+import { SETUP_SLACK_APP } from "./texts.js";
 import { SlackChat } from "./thread.js";
+import { wrongKind } from "./tokens.js";
+export const logger = getLogger("allaboard.chat.slack.module");
 /**
  * The daemon's two Slack clients on one token (the retry policy is in `reply/clients.ts`): the
  * shared one for everything but a reply, and the one replies are written with.
@@ -35,10 +42,16 @@ export function authField(answer, key) {
     return value;
 }
 /**
- * What deletes a thread for the Home tab, when the owner's user token is configured. The token
- * must be the owner's own, in the bot's workspace: it deletes as whoever it belongs to.
+ * The client of the owner's user token with the token's scopes, or null when no token is
+ * configured. The token must be the owner's own, in the bot's workspace: what it writes is
+ * written as whoever it belongs to, so it is checked once here for everything that uses it (the
+ * thread deleter, the root editor). The scopes are read from the same `auth.test`: the Web API
+ * reference for `auth.test` lists none (read 2026-10-19), but `@slack/web-api` 8.2.0 types
+ * `WebAPICallResult.response_metadata.scopes` and fills it from the `X-OAuth-Scopes` header of
+ * every response (`WebClient.js`), and a user token's `auth.test` answered
+ * `identify,chat:write,pins:write` on a dev app on 2026-10-19.
  */
-export async function deleter(userToken, slack, identity, state, sessions, names, clients = CLIENTS) {
+export async function ownerClient(userToken, identity, clients = CLIENTS) {
     if (userToken === null)
         return null;
     const owner = clients.owner(userToken);
@@ -47,6 +60,36 @@ export async function deleter(userToken, slack, identity, state, sessions, names
         authField(who, "team_id") !== identity.teamId) {
         throw new ConfigError("SLACK_USER_TOKEN must be the owner's own token, in the bot's workspace");
     }
+    return { client: owner, scopes: who.response_metadata?.scopes ?? null };
+}
+/** The scope `!tag` and `!untag` need beyond what the Home tab's Delete does (`chat:write`). */
+export const PINS_SCOPE = "pins:write";
+/**
+ * Whether the owner's token can pin, which `!tag` needs and a title does not. A token made before
+ * the manifest asked for `pins:write` has the Delete's scope alone: tags are then not offered,
+ * with one line saying why, and Delete and titles keep working. A token whose scopes Slack did
+ * not report is not trusted with tags either.
+ */
+export function canTag(owner) {
+    if (owner === null)
+        return false;
+    if (owner.scopes === null) {
+        logger.warning(`Slack lists no scopes for SLACK_USER_TOKEN, so !tag and !untag are not offered: reinstall the app with the user scope ${PINS_SCOPE} (see ${setupGuide(SETUP_SLACK_APP)})`);
+        return false;
+    }
+    if (!owner.scopes.includes(PINS_SCOPE)) {
+        logger.warning(`SLACK_USER_TOKEN lacks the scope ${PINS_SCOPE}, so !tag is not offered until the app is reinstalled with that scope (see ${setupGuide(SETUP_SLACK_APP)})`);
+        return false;
+    }
+    return true;
+}
+/**
+ * What deletes a thread for the Home tab and for `!delete-thread`, when the owner has a client of
+ * their own.
+ */
+export function deleter(owner, slack, identity, state, sessions, names) {
+    if (owner === null)
+        return null;
     return new ThreadDeleter(slack, owner, {
         botUserId: identity.botUserId,
         ownerUserId: identity.ownerUserId,
@@ -73,22 +116,21 @@ function variable(context, name) {
 }
 /** The shape of each token, checked before Slack is called: a swapped pair is told at once. */
 function checkTokens(context) {
-    if (!variable(context, "SLACK_BOT_TOKEN").startsWith("xoxb-")) {
-        throw new ConfigError("SLACK_BOT_TOKEN must be the Bot User OAuth Token (xoxb-...)");
-    }
-    if (!variable(context, "SLACK_APP_TOKEN").startsWith("xapp-")) {
-        throw new ConfigError("SLACK_APP_TOKEN must be the app-level token (xapp-...)");
-    }
+    const wrong = wrongKind("SLACK_BOT_TOKEN", variable(context, "SLACK_BOT_TOKEN")) ??
+        wrongKind("SLACK_APP_TOKEN", variable(context, "SLACK_APP_TOKEN"));
+    if (wrong !== null)
+        throw new ConfigError(wrong);
     const userToken = context.variables.SLACK_USER_TOKEN;
-    if (userToken !== undefined && !userToken.startsWith("xoxp-")) {
-        throw new ConfigError("SLACK_USER_TOKEN must be the User OAuth Token (xoxp-...)");
-    }
+    const wrongUser = userToken === undefined ? null : wrongKind("SLACK_USER_TOKEN", userToken);
+    if (wrongUser !== null)
+        throw new ConfigError(wrongUser);
 }
 /** The registry's entry for Slack. */
 export function slackChat(options = {}) {
     return {
         required: ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN", "SLACK_OWNER_USER_ID"],
         optional: ["SLACK_USER_TOKEN"],
+        setup: (instance) => slackSetup(instance, options.probe),
         async build(context) {
             checkTokens(context);
             try {
@@ -129,10 +171,13 @@ async function assemble(options, context) {
     // The provider is made last, from these parts; they ask it for the names when they show a
     // line, which is after the core exists.
     const names = () => chat.names();
-    const threadDeleter = await deleter(context.variables.SLACK_USER_TOKEN ?? null, slack, identity, state, {
+    const owner = await ownerClient(context.variables.SLACK_USER_TOKEN ?? null, identity, clients);
+    // One editor serves tags and titles, so their edits of a root queue behind one another.
+    const roots = owner === null ? null : new RootEditor(slack, owner.client);
+    const threadDeleter = deleter(owner?.client ?? null, slack, identity, state, {
         release: (channelId, threadId) => context.core().sessions.release(channelId, threadId),
         free: (channelId, threadId) => context.core().sessions.free(channelId, threadId),
-    }, names, clients);
+    }, names);
     const home = new Home(slack, {
         ownerUserId: identity.ownerUserId,
         teamId: identity.teamId,
@@ -144,6 +189,7 @@ async function assemble(options, context) {
             clean: (channelId) => threadDeleter.clean(channelId),
         }),
         update: () => context.core().updates?.line() ?? null,
+        cleanup: () => context.core().cleanup ?? null,
         clock: context.clock,
     });
     const uploads = options.uploads ?? context.scratchDir;
@@ -156,11 +202,15 @@ async function assemble(options, context) {
         clock: context.clock,
         steady: context.steady,
         agent: () => context.core().agent,
+        ...(roots !== null && { roots, canTag: canTag(owner) }),
         app: {
             core: () => context.core(),
             config: { botToken, allowedRoot: context.allowedRoot },
             guard: new ChannelGuard(slack, identity),
             home,
+            ...(threadDeleter !== null && {
+                deleteThread: (channelId, threadId) => threadDeleter.delete(channelId, threadId),
+            }),
             uploads,
             receiver: (options.receiver ?? socketReceiver)(appToken),
             appKey: appTokenKey(appToken),

package/dist/chat/slack/onboarding.js

@@ -0,0 +1,159 @@
+/**
+ * What `allaboard setup` asks for Slack: the link that creates the app from the package's manifest,
+ * the three tokens, each checked with Slack as it is pasted, and the owner's member ID. The core
+ * runs the flow (`core/wizard.ts`); this file holds the questions and what a Slack answer means.
+ *
+ * A token is checked with the one call that needs no scope (Slack's method reference, read
+ * 2026-10-18): `auth.test` for the bot and user tokens, `apps.connections.open` for the app-level
+ * token, the only method documented for it. The latter only asks for a WebSocket URL; nothing
+ * here connects to it.
+ */
+import { readFileSync } from "node:fs";
+import { WebAPIPlatformError, WebClient } from "@slack/web-api";
+import { silentLogger } from "./quiet-logger.js";
+import { REQUEST_TIMEOUT_MS, SENT_ONCE } from "./reply/clients.js";
+import { describe } from "./reply/errors.js";
+import { wrongKind } from "./tokens.js";
+/** The longest name Slack takes for an app (manifest reference, read 2026-10-17). */
+export const APP_NAME_LIMIT = 35;
+/** A client that sends each call once and logs nothing: the answer or the error is all there is. */
+function probeClient(token) {
+    return new WebClient(token, {
+        ...SENT_ONCE,
+        timeout: REQUEST_TIMEOUT_MS,
+        logger: silentLogger(),
+    });
+}
+const MANIFEST = new URL("../../../slack-app-manifest.json", import.meta.url);
+/**
+ * The package's manifest as the JSON that `api.slack.com/apps?new_app=1` takes, named for
+ * `instance`: a named instance's app and bot are called `allaboard-<name>`, the app's name cut to
+ * `APP_NAME_LIMIT`. `cut` says whether it was.
+ */
+export function manifestOf(instance) {
+    const manifest = JSON.parse(readFileSync(MANIFEST, "utf8"));
+    let cut = false;
+    if (instance.name !== null) {
+        const name = `${manifest.display_information.name}-${instance.name}`;
+        cut = name.length > APP_NAME_LIMIT;
+        manifest.display_information.name = name.slice(0, APP_NAME_LIMIT);
+        manifest.features.bot_user.display_name = name;
+    }
+    return { json: JSON.stringify(manifest), cut };
+}
+/** The link that opens Slack's "create an app" page with `manifest` filled in. */
+export function creationLink(manifestJson) {
+    return `https://api.slack.com/apps?new_app=1&manifest_json=${encodeURIComponent(manifestJson)}`;
+}
+const MEMBER_ID = /^[UW][A-Z0-9]{7,}$/;
+/** What Slack's refusal code means for the owner pasting a token. */
+function refusalOf(variable, code) {
+    switch (code) {
+        case "invalid_auth":
+        case "not_authed":
+            return `Slack does not accept this ${variable}: check you copied all of it.`;
+        case "token_revoked":
+        case "token_expired":
+        case "account_inactive":
+            return `Slack says this token is no longer valid (${code}): create a new one.`;
+        case "not_allowed_token_type":
+            return `Slack says this is not the kind of token ${variable} takes (${code}).`;
+        default:
+            return `Slack refused this token (${code}).`;
+    }
+}
+/** Runs `call`; a refusal sentence when Slack refused the token or could not be reached. */
+async function answered(variable, call) {
+    try {
+        return { answer: await call() };
+    }
+    catch (error) {
+        if (error instanceof WebAPIPlatformError) {
+            return { refusal: refusalOf(variable, String(error.data.error)) };
+        }
+        return {
+            refusal: `Could not reach Slack (${describe(error)}): check the connection and try again.`,
+        };
+    }
+}
+/** The questions of the Slack setup for `instance`; `probe` makes the client for a token. */
+export function slackSetup(instance, probe = probeClient) {
+    const { json, cut } = manifestOf(instance);
+    // What the bot token turned out to be, which the user token is held against.
+    let teamId = null;
+    const bot = {
+        variable: "SLACK_BOT_TOKEN",
+        message: "Bot token (xoxb-…, OAuth & Permissions):",
+        secret: true,
+        optional: false,
+        async check(token) {
+            const wrong = wrongKind("SLACK_BOT_TOKEN", token);
+            if (wrong !== null)
+                return { refusal: wrong };
+            const result = await answered("SLACK_BOT_TOKEN", () => probe(token).auth.test());
+            if ("refusal" in result)
+                return result;
+            teamId = result.answer.team_id ?? null;
+            return { note: `workspace "${result.answer.team}", bot "${result.answer.user}"` };
+        },
+    };
+    const app = {
+        variable: "SLACK_APP_TOKEN",
+        message: "App-level token (xapp-…, Basic Information > App-Level Tokens):",
+        secret: true,
+        optional: false,
+        async check(token) {
+            const wrong = wrongKind("SLACK_APP_TOKEN", token);
+            if (wrong !== null)
+                return { refusal: wrong };
+            const result = await answered("SLACK_APP_TOKEN", () => probe(token).apps.connections.open());
+            return "refusal" in result ? result : {};
+        },
+    };
+    const user = {
+        variable: "SLACK_USER_TOKEN",
+        message: "User token (xoxp-…, optional, Enter to skip):",
+        secret: true,
+        optional: true,
+        sets: ["SLACK_OWNER_USER_ID"],
+        async check(token) {
+            const wrong = wrongKind("SLACK_USER_TOKEN", token);
+            if (wrong !== null)
+                return { refusal: wrong };
+            const result = await answered("SLACK_USER_TOKEN", () => probe(token).auth.test());
+            if ("refusal" in result)
+                return result;
+            const { user_id: userId, team_id: owners } = result.answer;
+            if (userId === undefined || owners === undefined) {
+                return { refusal: "Slack did not say whose token this is." };
+            }
+            // The Home tab deletes under this token's name: it must be the owner's, in the bot's workspace.
+            if (owners !== teamId) {
+                return { refusal: "This token belongs to another workspace than the bot token." };
+            }
+            return { note: `you are ${userId}`, set: { SLACK_OWNER_USER_ID: userId } };
+        },
+    };
+    const owner = {
+        variable: "SLACK_OWNER_USER_ID",
+        message: "Your Slack member ID (Profile > ⋮ > Copy member ID):",
+        secret: false,
+        optional: false,
+        check: async (id) => MEMBER_ID.test(id)
+            ? {}
+            : {
+                refusal: "A member ID is a U or W followed by capital letters and digits, such as U012AB3CD.",
+            },
+    };
+    return {
+        intro: [
+            "1. Create the Slack app. Open this link, pick your workspace and confirm:",
+            `   ${creationLink(json)}`,
+            ...(cut
+                ? [`   (The app's name is cut to Slack's limit of ${APP_NAME_LIMIT} characters.)`]
+                : []),
+            "   Then install the app to the workspace (Install App in the sidebar).",
+        ],
+        questions: [bot, app, user, owner],
+    };
+}

package/dist/chat/slack/reply/blocks.js

@@ -5,7 +5,7 @@
  * `@slack/types` 3.2.0 declares them as `MarkdownBlock`, `ContextBlock`, `DividerBlock`,
  * `TaskCardBlock`, `ContainerBlock`, `RichTextBlock` and the chunks of `AnyChunk`.
  */
-import { NESTED, STOPPED, shownPreview } from "../../../core/port.js";
+import { formatDuration, NESTED, STOPPED, shownPreview } from "../../../core/port.js";
 import { RECORD_MARK } from "../texts.js";
 import { at, lastNewline, len, take } from "./chars.js";
 import { shownAsWritten } from "./escape.js";
@@ -27,6 +27,9 @@ export const BANNER_LIMIT = 300;
 // A task card's details and output are text of a rich text element; a context block's text
 // holds at most 3,000 characters.
 export const CARD_TEXT_LIMIT = 2_900;
+// A line of the list of what still runs, or its step: seven tasks of two such lines and an
+// agent's duration and count of calls stay under CARD_TEXT_LIMIT.
+const CARD_LINE_LIMIT = 200;
 export const CARD_TITLE_LIMIT = 150;
 // The list of what still runs: its card's id (a tool call's id never has this form), and how many
 // lines it draws before `+N more`. With the footer it stays inside the margins MESSAGE_LIMIT
@@ -339,18 +342,31 @@ export function cardBlock(update) {
     }
     return block;
 }
+/**
+ * A task's line, and under it the step of an agent that has made a call. How long the agent has
+ * run as `now` (on the steady clock) reads it, worded as a task's end line words its duration, and
+ * its count of calls end the agent's line, not the step's: they are the agent's.
+ */
+function runningRows(line, now) {
+    if (line.agent === null)
+        return take(line.text, CARD_LINE_LIMIT);
+    const { since, calls, step } = line.agent;
+    const count = `${calls} ${calls === 1 ? "call" : "calls"}`;
+    const text = take(line.text, CARD_LINE_LIMIT);
+    return `${text} · ${formatDuration(now - since)} · ${count}\n  ⎿ ${take(step, CARD_LINE_LIMIT)}`;
+}
 /**
  * The card of the list of what still runs: one `task_card` that keeps its `block_id` for its whole
  * life, since Slack leaves a card with a fixed id open across an edit (measured 2026-10-12,
- * desktop). Past `RUNNING_LIST_LINES` lines the rest is told as `+N more`.
+ * desktop). Past `RUNNING_LIST_LINES` tasks the rest is told as `+N more`; an agent's step is part
+ * of its task's entry. `now` is the steady clock's reading, against which an agent's start is
+ * measured.
  */
-export function runningListBlock(running) {
-    const lines = running.lines.length > RUNNING_LIST_LINES
-        ? [
-            ...running.lines.slice(0, RUNNING_LIST_LINES),
-            `+${running.lines.length - RUNNING_LIST_LINES} more`,
-        ]
-        : running.lines;
+export function runningListBlock(running, now) {
+    const rows = running.lines.slice(0, RUNNING_LIST_LINES).map((line) => runningRows(line, now));
+    if (running.lines.length > RUNNING_LIST_LINES) {
+        rows.push(`+${running.lines.length - RUNNING_LIST_LINES} more`);
+    }
     const block = {
         type: "task_card",
         block_id: RUNNING_LIST_ID,
@@ -358,8 +374,8 @@ export function runningListBlock(running) {
         title: take(running.title, CARD_TITLE_LIMIT),
         status: "in_progress",
     };
-    if (lines.length > 0)
-        block.details = richText(take(lines.join("\n"), CARD_TEXT_LIMIT));
+    if (rows.length > 0)
+        block.details = richText(take(rows.join("\n"), CARD_TEXT_LIMIT));
     return block;
 }
 /** Whether the block is the list of what still runs. */

package/dist/chat/slack/reply/sinks.js

@@ -975,7 +975,9 @@ export class ReplySink {
         // The list only from what the places handed this reply once it rests: a reply whose end is on
         // its way would draw a second card beside the one its holder still shows.
         const list = this.resting ? this.assigned : null;
-        return list === null ? this.footerBlocks() : [runningListBlock(list), ...this.footerBlocks()];
+        return list === null
+            ? this.footerBlocks()
+            : [runningListBlock(list, this.steady.time()), ...this.footerBlocks()];
     }
     /**
      * What a message shows under its body: only the reply's last, when the footer rode on its