@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/channels/lark/onboard.d.ts

@@ -1,3 +1,4 @@
+import type { FeishuGroupBehavior, FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
 /**
  * Guided Lark-international onboarding. The intl cloud cannot complete the BOUND scan-to-create flow,
  * so a new/partial setup opens its unbound one-click launcher and collects one App-scoped credential
@@ -17,7 +18,7 @@ export interface LarkOnboardIO {
         hidden?: boolean;
     }): Promise<string | undefined>;
 }
-export interface LarkBootstrapResult {
+interface LarkBootstrapResult {
     /** Challenge-captured token: the PATCH also switched Subscription mode to webhook. */
     token?: string;
     /** Present only for a definitive config-route 404; tells the user why the manual path is active. */
@@ -26,14 +27,17 @@ export interface LarkBootstrapResult {
 export interface LarkOnboardOptions {
     /** Existing active .env values. A complete credential pair is reused (and still validated). */
     existing?: Readonly<Record<string, string | undefined>>;
+    ingress?: FeishuSubscriptionMode;
+    groupBehavior?: FeishuGroupBehavior;
     verifyCredentials(appId: string, appSecret: string): Promise<void>;
-    bootstrapWebhook(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
+    bootstrapWebhook?(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
 }
-export interface LarkOnboardCredentials extends Record<string, string> {
+export interface LarkOnboardCredentials {
     LARK_APP_ID: string;
     LARK_APP_SECRET: string;
-    LARK_VERIFICATION_TOKEN: string;
+    LARK_VERIFICATION_TOKEN?: string;
 }
 /** Open the stable app console and collect everything the runtime needs. Cancellation is a visible
  * failure: the scaffold remains and `add lark` is deliberately re-runnable to resume onboarding. */
 export declare function onboardLarkApp(io: LarkOnboardIO, opts: LarkOnboardOptions): Promise<LarkOnboardCredentials>;
+export {};

package/dist/channels/lark/onboard.js

@@ -39,7 +39,15 @@ export async function onboardLarkApp(io, opts) {
     const eventSecurityUrl = larkEventSecurityUrl(appId);
     io.note(`App ID / Secret verified. Opening Events & Callbacks → Security: ${eventSecurityUrl}`);
     io.openUrl(eventSecurityUrl);
+    if (opts.ingress === "websocket") {
+        io.note(opts.groupBehavior === "mentions"
+            ? "Choose long connection, subscribe im.message.receive_v1, then create + publish an app version. No Verification Token or Request URL is needed."
+            : "Choose long connection and subscribe im.message.receive_v1, but do not publish yet — context-aware group permission setup follows. No Verification Token or Request URL is needed.");
+        return { LARK_APP_ID: appId, LARK_APP_SECRET: appSecret };
+    }
     io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
+    if (!opts.bootstrapWebhook)
+        throw new Error("Lark webhook onboarding requires bootstrapWebhook");
     const bootstrap = await opts.bootstrapWebhook(appId, appSecret);
     if (bootstrap.token) {
         io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");

package/dist/channels/lark/scaffold/channel.ts

@@ -8,8 +8,10 @@ import { larkChannel } from "@fastagent-sh/fastagent/lark";
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
 //      card scope ("Create and update card" — the live preview streams through a card). To answer bare
-//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
-//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
+//      messages in threads the Agent takes part in, and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version. Add a
+//      message-read scope (e.g. `im:message:readonly`) too, so a thread's opening ask can carry the
+//      message it quotes; without it that quote degrades to a marker in the prompt.
 //   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
 //      .env; RECOMMENDED: set an Encrypt Key there and mirror it in LARK_ENCRYPT_KEY
 //   4. run `fastagent dev --tunnel`: it attempts to switch Subscription mode to webhook + register
@@ -21,18 +23,17 @@ export default larkChannel({
   appSecret: process.env.LARK_APP_SECRET ?? "",
   verificationToken: process.env.LARK_VERIFICATION_TOKEN ?? "", // authenticates inbound events
   encryptKey: process.env.LARK_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
-  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
-  // directMessageSession: "continuous",
-  // groupMessageSession: "continuous",
+  // No session modes: a chat is one session and a thread is another, and where the answer goes follows
+  // from that (docs/design/participant-model.md).
   // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
   // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
   // full details always go to the server log regardless.
   onError: (failed) => `⚠️ ${failed.details}`,
   // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
   // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultLarkRoute:
-  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
-  // threads. Other human group/thread discussion buffers until that place's next answered turn;
-  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // p2p chats always answer; groups answer on @this-bot, plus bare messages in a thread where the
+  // Agent takes part and exactly ONE human does. Other human group/thread discussion buffers until
+  // that place's next answered turn; @other-only messages buffer rather than triggering the Agent.
   // Override to customise explicit routing, reusing the export:
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },

package/dist/channels/lark/scaffold/lark-send.ts

@@ -6,7 +6,7 @@ import { defineTool, z } from "@fastagent-sh/fastagent";
 // context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
 // the target chat id. tools/ is auto-discovered.
 
-// Standalone copy of the channel transport's discipline: a timeout so a wedged connection can't hang
+// Embedded copy of the channel transport's discipline: a timeout so a wedged connection can't hang
 // the tool call (and the turn), named errors, and success gated on the body's own code===0.
 // Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
 // fail-fast beats a silently sleeping tool.
@@ -57,9 +57,11 @@ async function tenantToken(): Promise<string> {
 export default defineTool({
   description:
     "Send a message to a Lark chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. In a chat turn take chatId from the " +
-    "[lark: chat …] context line; in a scheduled/woken turn (no context line) the chat id must come " +
-    "from your instruction.",
+    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
+    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
+    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
+    "answer (it would post the message twice). chatId comes from the [lark: chat …] context line in a " +
+    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),

package/dist/channels/preview-kit.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Channel-neutral live-preview pieces shared by every messaging channel's preview renderer
+ * (telegram/preview.ts, feishu/preview.ts, slack/preview.ts): the turn-view REDUCER (the one
+ * event → view-state machine every renderer consumes), its line renderers, the terminal-failure
+ * shape a channel hands to its `onError`, the customer-facing wording for it, and the serialized
+ * single-writer pump. DELIVERY stays per-platform — message edits vs streaming cards vs chat.update,
+ * pacing constants, reveal timing, and terminal-write policies are real platform differences — but
+ * everything platform-independent lives here, so a new event type or a wording change lands in ONE
+ * place instead of one hunk per channel.
+ */
+import type { AgentEvent, Json } from "../agent.ts";
+/** A terminal failure, as a channel hands it to its `onError`. */
+export interface ChannelFailure {
+    details: string;
+    retryable: boolean;
+}
+/** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
+ *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").
+ *  The non-retryable branch keeps the "something went wrong" phrase deliberately — it is neutral (we only
+ *  know a boolean, never the specific limitation) and shared verbatim across channels. */
+export declare function defaultErrorMessage(failed: ChannelFailure): string;
+/** Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying`
+ *  event): neutral, no leaked internals — the reason stays in operator logs. */
+export declare const RETRY_NOTICE = "\u23F3 Temporary problem \u2014 retrying\u2026";
+/** The placeholder shown before any reasoning/tool/text arrives. */
+export declare const THINKING_PLACEHOLDER = "\uD83D\uDCAD Thinking\u2026";
+/** One tool call's line in the live view. */
+interface ToolLine {
+    label: string;
+    status: "running" | "ok" | "error";
+}
+/**
+ * The channel-neutral view STATE of one in-flight turn. Renderers own everything after this state:
+ * when to reveal the young answer (age vs timer), how to format (HTML / card markdown / mrkdwn),
+ * and how to deliver frames. Terminal events are deliberately NOT view state — completed/failed
+ * resolve the preview into a final write, which is each platform's terminal-write policy.
+ */
+export interface TurnView {
+    thinking: string;
+    tools: ToolLine[];
+    /** tool-call id → its line, for `tool_ended` status flips (bookkeeping; renderers read `tools`). */
+    toolById: Map<string, ToolLine>;
+    answer: string;
+    /** Arrival time of the first non-empty answer delta; age-based reveal policies read it. */
+    answerSince?: number;
+    /** An advisory retry backoff is in progress (closed again by any subsequent progress event). */
+    retrying: boolean;
+}
+export declare function createTurnView(): TurnView;
+/**
+ * Apply one event to the view state. Returns true when the view changed (the caller repaints).
+ * This is the ONE place the shared view rules live: tool labels are humanized with a compact arg
+ * summary, and any progress event closes an open retry notice (a stale "retrying" line must never
+ * outlive actual progress). Terminal events only close the notice — they are the caller's business.
+ */
+export declare function applyTurnEvent(view: TurnView, e: AgentEvent): boolean;
+/** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
+export declare function toolLines(view: TurnView): string;
+/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe.
+ *  Process, not the answer — renderers show it live only, never in the persisted final message. */
+export declare function thinkingLine(view: TurnView, maxTail: number): string;
+/**
+ * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one
+ * throttle window (`ageMs` — each platform passes its own pacing constant). The pump's leading-edge
+ * flush would otherwise turn the very first content delta (often a lone character or unbalanced
+ * markup) into its own frame — the short-reply flicker (placeholder → "O" → "OK."). Aging is
+ * anchored at delta ARRIVAL (`answerSince`, set by the reducer) so an in-flight write can't skew the
+ * clock, and there is deliberately NO timer at the boundary: a young answer surfaces on the next
+ * content-driven pass, so a turn completing within the window delivers the final answer only.
+ */
+export declare function revealedAnswer(view: TurnView, ageMs: number): string;
+/** Compose body parts (thinking/tools/retry/answer) into one frame: skip empties, blank-line joins. */
+export declare function composeTurnBody(parts: readonly string[]): string;
+/**
+ * The serialized live-preview writer shared by the edit/snapshot renderers (telegram, feishu).
+ * Events mark the view dirty; the pump repaints to the LATEST view with at most ONE write in
+ * flight, paced by `throttleMs`. One-in-flight is the whole point: concurrent writes can land out
+ * of order — an older frame over a newer one is the "shows 3-4 steps, blanks, re-fills" flicker —
+ * so a single writer keeps frames monotonic (and makes feishu's strictly-increasing card `sequence`
+ * correct by construction). NOT used by slack-classic: its pacing lives inside the flush (the 3s
+ * chat.update rate slot), not at the frame boundary.
+ */
+export interface PreviewPump {
+    /** Mark the view dirty and ensure the single writer runs (an in-flight write picks the new state
+     *  up on its next loop). Synchronous — callers never await a network write. */
+    touch(): void;
+    /** Stop the pump, cut an in-flight throttle short, and await any in-flight write — so the
+     *  caller's terminal write is strictly the LAST one (no stale frame landing after the answer). */
+    finish(): Promise<void>;
+}
+export declare function createPreviewPump(opts: {
+    /** Write the LATEST view. Best-effort — the terminal write is authoritative. */
+    flush: () => Promise<void>;
+    /** Pace + coalesce a burst into one write; finish() interrupts a throttle in progress. */
+    throttleMs: number;
+    /** Called for the FIRST failing flush only (the pump keeps running): a never-rendering preview
+     *  must be diagnosable, not silent — and not a log flood. */
+    onError: (error: unknown) => void;
+}): PreviewPump;
+/**
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
+ * rather than just `🔧 read`. Generic (a channel knows no tool schemas): show the salient value — the
+ * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ */
+export declare function summarizeToolArgs(args: Json): string;
+/**
+ * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool
+ * does rather than expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue",
+ * not "mcp__github__create_issue"). Deliberately generic and engine-neutral: it only reshapes the
+ * identifier string — it never invents semantics and never exposes arguments. An `mcp__server__tool`
+ * identifier becomes `server: tool`; any other identifier has its separators normalized to spaces and
+ * its first letter capitalized.
+ */
+export declare function humanizeToolName(name: string): string;
+export {};

package/dist/channels/preview-kit.js

@@ -0,0 +1,184 @@
+import { truncateCodePointPrefix, truncateCodePointSuffix } from "./text.js";
+/** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
+ *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").
+ *  The non-retryable branch keeps the "something went wrong" phrase deliberately — it is neutral (we only
+ *  know a boolean, never the specific limitation) and shared verbatim across channels. */
+export function defaultErrorMessage(failed) {
+    return failed.retryable
+        ? "⚠️ Temporary problem — please try again in a moment."
+        : "⚠️ Sorry, something went wrong. Try rephrasing, or check I have access to what you need.";
+}
+/** Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying`
+ *  event): neutral, no leaked internals — the reason stays in operator logs. */
+export const RETRY_NOTICE = "⏳ Temporary problem — retrying…";
+/** The placeholder shown before any reasoning/tool/text arrives. */
+export const THINKING_PLACEHOLDER = "💭 Thinking…";
+export function createTurnView() {
+    return { thinking: "", tools: [], toolById: new Map(), answer: "", retrying: false };
+}
+/**
+ * Apply one event to the view state. Returns true when the view changed (the caller repaints).
+ * This is the ONE place the shared view rules live: tool labels are humanized with a compact arg
+ * summary, and any progress event closes an open retry notice (a stale "retrying" line must never
+ * outlive actual progress). Terminal events only close the notice — they are the caller's business.
+ */
+export function applyTurnEvent(view, e) {
+    const closedRetry = view.retrying && e.type !== "retrying";
+    if (closedRetry)
+        view.retrying = false;
+    switch (e.type) {
+        case "text":
+            view.answer += e.delta;
+            if (view.answerSince === undefined && view.answer.trim() !== "")
+                view.answerSince = Date.now();
+            return true;
+        case "thinking":
+            view.thinking += e.delta;
+            return true;
+        case "tool_started": {
+            const arg = summarizeToolArgs(e.args);
+            const name = humanizeToolName(e.name);
+            const line = { label: arg ? `${name} ${arg}` : name, status: "running" };
+            view.tools.push(line);
+            view.toolById.set(e.id, line);
+            return true;
+        }
+        case "tool_ended": {
+            const line = view.toolById.get(e.id);
+            if (line)
+                line.status = e.isError ? "error" : "ok";
+            return true;
+        }
+        case "retrying":
+            view.retrying = true;
+            return true;
+        default:
+            return closedRetry;
+    }
+}
+const TOOL_MARK = { running: "…", ok: "✓", error: "✗" };
+/** The tool-activity block: one `🔧 label …/✓/✗` line per call, in call order. */
+export function toolLines(view) {
+    return view.tools.map((t) => `🔧 ${t.label} ${TOOL_MARK[t.status]}`).join("\n");
+}
+/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe.
+ *  Process, not the answer — renderers show it live only, never in the persisted final message. */
+export function thinkingLine(view, maxTail) {
+    const t = view.thinking.replace(/\s+/g, " ").trim();
+    return t === "" ? "" : `💭 ${truncateCodePointSuffix(t, maxTail)}`;
+}
+/**
+ * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one
+ * throttle window (`ageMs` — each platform passes its own pacing constant). The pump's leading-edge
+ * flush would otherwise turn the very first content delta (often a lone character or unbalanced
+ * markup) into its own frame — the short-reply flicker (placeholder → "O" → "OK."). Aging is
+ * anchored at delta ARRIVAL (`answerSince`, set by the reducer) so an in-flight write can't skew the
+ * clock, and there is deliberately NO timer at the boundary: a young answer surfaces on the next
+ * content-driven pass, so a turn completing within the window delivers the final answer only.
+ */
+export function revealedAnswer(view, ageMs) {
+    if (view.answer.trim() === "" || view.answerSince === undefined)
+        return "";
+    return Date.now() - view.answerSince >= ageMs ? view.answer : "";
+}
+/** Compose body parts (thinking/tools/retry/answer) into one frame: skip empties, blank-line joins. */
+export function composeTurnBody(parts) {
+    return parts
+        .filter((s) => s.trim() !== "")
+        .join("\n\n")
+        .trim();
+}
+export function createPreviewPump(opts) {
+    let dirty = false;
+    let pumping = false;
+    let stopped = false;
+    let errored = false;
+    let pumpDone;
+    let wakeThrottle; // set while mid-throttle; finish() cuts it short
+    const runPump = async () => {
+        pumping = true;
+        try {
+            while (dirty && !stopped) {
+                dirty = false;
+                try {
+                    await opts.flush();
+                }
+                catch (error) {
+                    if (!errored) {
+                        errored = true;
+                        opts.onError(error);
+                    }
+                }
+                if (dirty && !stopped) {
+                    await new Promise((resolve) => {
+                        const t = setTimeout(resolve, opts.throttleMs);
+                        wakeThrottle = () => {
+                            clearTimeout(t);
+                            resolve();
+                        };
+                    });
+                    wakeThrottle = undefined;
+                }
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    };
+    return {
+        touch() {
+            dirty = true;
+            if (!pumping)
+                pumpDone = runPump();
+        },
+        async finish() {
+            stopped = true;
+            wakeThrottle?.();
+            await pumpDone?.catch(() => { });
+        },
+    };
+}
+/** Max length (code points) of a tool's arg preview. Slack's native stream cannot be retracted, so
+ *  this is a disclosure bound, not only a layout one. */
+const TOOL_ARG_MAX = 48;
+/** Max length (code points) of a humanized tool label. */
+const TOOL_NAME_MAX = 80;
+/** One-line, truncated at code-point boundaries: collapse whitespace so a multi-line command/arg
+ *  stays on one line, and never tear a surrogate pair mid-emoji. */
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    return truncateCodePointPrefix(one, TOOL_ARG_MAX);
+}
+/**
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
+ * rather than just `🔧 read`. Generic (a channel knows no tool schemas): show the salient value — the
+ * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ */
+export function summarizeToolArgs(args) {
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return clip(String(args));
+    const values = Object.values(args);
+    const primary = values.find((v) => typeof v === "string" || typeof v === "number");
+    if (primary !== undefined)
+        return clip(String(primary));
+    return values.length > 0 ? clip(JSON.stringify(args)) : "";
+}
+/**
+ * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool
+ * does rather than expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue",
+ * not "mcp__github__create_issue"). Deliberately generic and engine-neutral: it only reshapes the
+ * identifier string — it never invents semantics and never exposes arguments. An `mcp__server__tool`
+ * identifier becomes `server: tool`; any other identifier has its separators normalized to spaces and
+ * its first letter capitalized.
+ */
+export function humanizeToolName(name) {
+    const normalize = (s) => s
+        .replace(/[_\-.]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const mcp = /^mcp__(.+?)__(.+)$/.exec(name);
+    const base = mcp ? `${normalize(mcp[1] ?? "")}: ${normalize(mcp[2] ?? "")}` : normalize(name);
+    const label = base.trim() || name.trim() || "Tool";
+    const capitalized = label.charAt(0).toUpperCase() + label.slice(1);
+    return truncateCodePointPrefix(capitalized, TOOL_NAME_MAX);
+}

package/dist/channels/seen.d.ts

@@ -0,0 +1,5 @@
+export interface SeenRing {
+    has(id: string): boolean;
+    add(id: string): void;
+}
+export declare function createSeenRing(path: string, label: string, cap?: number): SeenRing;

package/dist/channels/seen.js

@@ -0,0 +1,35 @@
+/** Best-effort bounded durable dedup ring, recorded only after the caller's pre-ACK side effect is durable. */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+export function createSeenRing(path, label, cap = 2000) {
+    const raw = loadStateFile(path);
+    const order = raw === undefined
+        ? []
+        : Array.isArray(raw) && raw.every((id) => typeof id === "string")
+            ? raw.slice(-cap)
+            : undefined;
+    if (order === undefined)
+        log.warn(`${label} unexpected shape in ${path} — starting with no seen ids`);
+    const values = order ?? [];
+    const ids = new Set(values);
+    return {
+        has: (id) => ids.has(id),
+        add(id) {
+            if (ids.has(id))
+                return;
+            ids.add(id);
+            values.push(id);
+            while (values.length > cap) {
+                const evicted = values.shift();
+                if (evicted !== undefined)
+                    ids.delete(evicted);
+            }
+            try {
+                saveStateFile(path, values);
+            }
+            catch (error) {
+                log.warn(`${label} seen-ring write failed (delivery dedup is in-memory until restart): ${String(error)}`);
+            }
+        },
+    };
+}

package/dist/channels/slack/bot-auth.d.ts

@@ -0,0 +1,15 @@
+export interface SlackBotTokenProviderOptions {
+    statePath: string;
+    botToken: string;
+    botRefreshToken?: string;
+    clientId?: string;
+    clientSecret?: string;
+    botTokenExpiresAt?: number;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+/** Latest local rotating credentials for `deploy --run`. The remote runtime still prefers its own
+ * durable volume; this overlay prevents a locally consumed refresh token from being redeployed. */
+export declare function readSlackBotAuthEnv(statePath: string): Record<string, string>;
+/** Resolve the current bot token, refreshing once per process when it approaches expiry. */
+export declare function createSlackBotTokenProvider(options: SlackBotTokenProviderOptions): () => Promise<string>;

package/dist/channels/slack/bot-auth.js

@@ -0,0 +1,146 @@
+/** Rotating Slack bot-token provider backed by owner-only channel state. */
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const REFRESH_EARLY_MS = 5 * 60_000;
+const REQUEST_TIMEOUT_MS = 30_000;
+function isState(value) {
+    const state = value;
+    return (typeof state === "object" &&
+        state !== null &&
+        state.version === 1 &&
+        typeof state.accessToken === "string" &&
+        typeof state.refreshToken === "string" &&
+        typeof state.expiresAt === "number");
+}
+function load(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Slack bot auth state ${path} is unreadable: ${String(error)}`, { cause: error });
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (!isState(value))
+            throw new Error("unexpected shape/version");
+        return value;
+    }
+    catch (error) {
+        // A stale env refresh token may already have been consumed. Never hide corrupt rotating state by
+        // falling back to it: recovery requires restoring the durable file or reinstalling the app.
+        throw new Error(`Slack bot auth state ${path} is invalid: ${String(error)}`, { cause: error });
+    }
+}
+function save(path, state) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify(state), { mode: 0o600 });
+        chmodSync(temp, 0o600);
+        renameSync(temp, path);
+        chmodSync(path, 0o600);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+}
+async function refreshSlackBotToken(input) {
+    const authorization = Buffer.from(`${input.clientId}:${input.clientSecret}`, "utf8").toString("base64");
+    let lastError;
+    // Slack keeps a short grace window for a just-consumed refresh token. One retry recovers the
+    // committed-but-response-lost boundary without creating an unbounded refresh loop.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const response = await input.fetch(`${input.apiBaseUrl}/oauth.v2.access`, {
+                method: "POST",
+                headers: {
+                    authorization: `Basic ${authorization}`,
+                    "content-type": "application/x-www-form-urlencoded",
+                },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: input.refreshToken,
+                }).toString(),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            const data = (await response.json().catch(() => ({})));
+            if (!response.ok ||
+                data.ok !== true ||
+                !data.access_token ||
+                !data.refresh_token ||
+                typeof data.expires_in !== "number") {
+                throw new Error(`Slack rejected bot-token refresh (HTTP ${response.status})`);
+            }
+            return {
+                version: 1,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                expiresAt: Date.now() + data.expires_in * 1_000,
+            };
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error("Slack bot-token rotation failed; restore credentials or reinstall the app", { cause: lastError });
+}
+/** Latest local rotating credentials for `deploy --run`. The remote runtime still prefers its own
+ * durable volume; this overlay prevents a locally consumed refresh token from being redeployed. */
+export function readSlackBotAuthEnv(statePath) {
+    const state = load(statePath);
+    return state
+        ? {
+            SLACK_BOT_TOKEN: state.accessToken,
+            SLACK_BOT_REFRESH_TOKEN: state.refreshToken,
+            SLACK_BOT_TOKEN_EXPIRES_AT: String(state.expiresAt),
+        }
+        : {};
+}
+/** Resolve the current bot token, refreshing once per process when it approaches expiry. */
+export function createSlackBotTokenProvider(options) {
+    const rotatingFields = [options.botRefreshToken, options.clientId, options.clientSecret, options.botTokenExpiresAt];
+    const rotating = rotatingFields.some((value) => value !== undefined);
+    if (rotating && rotatingFields.some((value) => value === undefined || value === "")) {
+        throw new Error("Slack token rotation requires botRefreshToken, clientId, clientSecret, and botTokenExpiresAt together");
+    }
+    if (rotating && (!Number.isFinite(options.botTokenExpiresAt) || options.botTokenExpiresAt <= 0)) {
+        throw new Error("Slack botTokenExpiresAt must be a positive epoch-millisecond value");
+    }
+    if (!rotating)
+        return async () => options.botToken;
+    const configured = {
+        version: 1,
+        accessToken: options.botToken,
+        refreshToken: options.botRefreshToken,
+        expiresAt: options.botTokenExpiresAt,
+    };
+    const persisted = load(options.statePath);
+    // Deploy may carry a newer pair from the owner machine onto an existing remote volume; ordinary
+    // restarts carry the original stale env and therefore keep the newer persisted pair.
+    let state = persisted && persisted.expiresAt >= configured.expiresAt ? persisted : configured;
+    let refreshing;
+    return async () => {
+        if (state.expiresAt > Date.now() + REFRESH_EARLY_MS)
+            return state.accessToken;
+        refreshing ??= refreshSlackBotToken({
+            refreshToken: state.refreshToken,
+            clientId: options.clientId,
+            clientSecret: options.clientSecret,
+            apiBaseUrl: (options.apiBaseUrl ?? "https://slack.com/api").replace(/\/$/, ""),
+            fetch: options.fetch ?? globalThis.fetch,
+        })
+            .then((next) => {
+            save(options.statePath, next);
+            state = next;
+        })
+            .finally(() => {
+            refreshing = undefined;
+        });
+        await refreshing;
+        return state.accessToken;
+    };
+}