@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/channels/http.js

@@ -12,9 +12,32 @@ import { Readable } from "node:stream";
 import { log } from "../log.js";
 import { readBodyCapped } from "./body.js";
 import { text, textHeaders } from "./respond.js";
-/** Request body cap (1 MiB). */
-const MAX_BODY_BYTES = 1 << 20;
+/** Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's
+ *  dispatch imports it), so the two caps cannot drift apart. */
+export const MAX_BODY_BYTES = 1 << 20;
 const encoder = new TextEncoder();
+/** SSE comment-heartbeat interval, shared by every SSE surface (the control events route imports
+ *  it, and the remote client sizes its dead-connection watchdog as a multiple of it). */
+export const SSE_HEARTBEAT_MS = 30_000;
+/** The emitting half of the heartbeat contract (the client watchdog is the other): starts the
+ *  `: ping` comment interval on an SSE stream controller and returns its stop function — ONE
+ *  implementation for every SSE surface, so the emission side cannot regress on one route while
+ *  the shared client watchdog keeps assuming it. Self-stops if the controller is already closed. */
+export function sseHeartbeat(controller) {
+    const encoder = new TextEncoder();
+    const timer = setInterval(() => {
+        try {
+            controller.enqueue(encoder.encode(": ping\n\n"));
+        }
+        catch {
+            clearInterval(timer);
+        }
+    }, SSE_HEARTBEAT_MS);
+    return () => clearInterval(timer);
+}
+/** A valid example request body for the invoke handler — lives HERE, next to the shape check it must
+ *  satisfy, so the CLI's "try it" hint can't drift from the protocol. */
+export const INVOKE_EXAMPLE_BODY = '{"session":"dev","text":"hello"}';
 /**
  * Fetch-shaped invoke handler. Mount it at any route in the host app; it accepts POST only.
  * Returns SSE (`text/event-stream`) with one `data:` line per AgentEvent.
@@ -37,19 +60,29 @@ export function createInvokeHandler(agent) {
         if (typeof session !== "string" || typeof promptText !== "string") {
             return text('need { "session": string, "text": string }\n', 400);
         }
+        // ^ the request shape INVOKE_EXAMPLE_BODY (below) must keep satisfying.
         // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
         // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
         const iterator = agent.invoke({ session }, { text: promptText })[Symbol.asyncIterator]();
+        // Heartbeats: a QUIET stream (a long tool call, no events) is normal here — remote consumers
+        // distinguish "quiet but alive" from a dead connection by byte arrival, so silence must not
+        // look identical to a black hole (SSE comments are ignored by spec-conforming parsers).
+        let stopHeartbeat = () => { };
         const stream = new ReadableStream({
+            start(controller) {
+                stopHeartbeat = sseHeartbeat(controller);
+            },
             async pull(controller) {
                 const { value, done } = await iterator.next();
                 if (done) {
+                    stopHeartbeat();
                     controller.close();
                     return;
                 }
                 controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
             },
             async cancel() {
+                stopHeartbeat();
                 await iterator.return?.();
             },
         });

package/dist/channels/invoke-turn-kit.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
+ * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
+ *
+ *   - {@link streamTurnWithBusyRetry}: the busy-retry loop around `agent.invoke`, with the
+ *     `onCompleted` durable-commit point;
+ *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
+ *     {@link missingAttachmentsNote}, {@link attributedFileName}.
+ *
+ * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
+ * message-scoped Feishu keys, Slack file objects) are real differences.
+ */
+import { type Agent, type AgentEvent, type Prompt } from "../agent.ts";
+/** How the busy-wait paces: retry the invoke every `delayMs` while the session's lease is held by an
+ *  EXTERNAL turn (a self-scheduled wake, a concurrent embedder invoke), up to `maxWaitMs` total. The
+ *  channel's own turns never collide (the turn-queue serializes per session), so a busy reject here is
+ *  always an outside holder — wait for it like a queued turn, instead of erroring at the user. */
+export interface BusyRetry {
+    delayMs: number;
+    maxWaitMs: number;
+}
+export declare const DEFAULT_BUSY_RETRY: BusyRetry;
+/**
+ * Stream one Agent turn with the shared busy-wait. `onCompleted` (if given) fires on the turn's
+ * `completed` event — the durable-commit point: only then does the turn provably live in the session,
+ * so a failure or crash at ANY earlier point leaves the caller's pre-ACK state (turn intent, context
+ * buffer) intact for replay/the next summon. The caller uses it to remove the turn intent AND commit
+ * the context buffer, in that order, so a crash between the two clears cannot replay a
+ * context-stripped turn.
+ *
+ * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
+ * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user
+ * sees the channel's "Thinking…" placeholder while waiting (the mirror of the scheduler deferring a
+ * wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a FIRST-event
+ * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
+ * is ever re-run.
+ */
+export declare function streamTurnWithBusyRetry(agent: Agent, session: string, prompt: Prompt, options: {
+    label: string;
+    onCompleted?: () => void;
+    busyRetry?: BusyRetry;
+}): AsyncIterable<AgentEvent>;
+/** What the attached-files manifest renders per file: display name, byte size, absolute local path. */
+export interface ManifestFile {
+    name: string;
+    size: number;
+    path: string;
+}
+/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
+ *  Empty input renders nothing. */
+export declare function attachedFilesManifest(files: readonly ManifestFile[]): string;
+/** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),
+ *  the way the fold attributes text lines. */
+export declare function attributedFileName(name: string, from: string, msg?: string | number): string;
+/** The manifest attributing background vision images folded in from the earlier discussion — images
+ *  carry no per-image label inline, so position ("appended after N primary") is the attribution.
+ *  Channels whose image refs carry no attribution (telegram) simply don't render one. */
+export declare function backgroundImagesManifest(primaryCount: number, refs: readonly {
+    from: string;
+    messageId: string;
+}[]): string;
+/** The prompt note counting EVERY background attachment the turn does not carry (load failures +
+ *  cap-skipped) — without it, the model holds fold references it silently cannot open and may
+ *  pretend it read them. Neutral wording (platforms differ on WHY: expired file_ids, deleted files). */
+export declare function missingAttachmentsNote(missing: number): string;

package/dist/channels/invoke-turn-kit.js

@@ -0,0 +1,87 @@
+/**
+ * Shared pieces of the channels' invoke-turn modules (telegram/feishu/slack `invoke-turn.ts`) — the
+ * halves that are channel-independent, so a retry-policy or prompt-wording change lands ONCE:
+ *
+ *   - {@link streamTurnWithBusyRetry}: the busy-retry loop around `agent.invoke`, with the
+ *     `onCompleted` durable-commit point;
+ *   - the prompt-suffix wording: {@link attachedFilesManifest}, {@link backgroundImagesManifest},
+ *     {@link missingAttachmentsNote}, {@link attributedFileName}.
+ *
+ * Attachment RESOLUTION stays per channel — the platform resource models (Bot API file_ids,
+ * message-scoped Feishu keys, Slack file objects) are real differences.
+ */
+import { SESSION_BUSY_CODE } from "../agent.js";
+import { log } from "../log.js";
+// Each retry is a lease-check-level reject (tryAcquire runs before harness assembly) — waiting is nearly
+// free, and the loop exits within one delay of the holder finishing. So the cap is sized to outlast a
+// real tool-using wake turn (minutes), not to be short: 10 min. CEILING: a holder that runs longer than
+// this still surfaces the busy error to the user — the bound exists so a stuck lease can't hang a chat
+// turn forever.
+export const DEFAULT_BUSY_RETRY = { delayMs: 5_000, maxWaitMs: 600_000 };
+/**
+ * Stream one Agent turn with the shared busy-wait. `onCompleted` (if given) fires on the turn's
+ * `completed` event — the durable-commit point: only then does the turn provably live in the session,
+ * so a failure or crash at ANY earlier point leaves the caller's pre-ACK state (turn intent, context
+ * buffer) intact for replay/the next summon. The caller uses it to remove the turn intent AND commit
+ * the context buffer, in that order, so a crash between the two clears cannot replay a
+ * context-stripped turn.
+ *
+ * BUSY-WAIT: a `failed{code: session_busy}` FIRST event means an external turn holds this session's
+ * lease and OUR turn never started — replay-safe. Retry (bounded) instead of yielding it: the user
+ * sees the channel's "Thinking…" placeholder while waiting (the mirror of the scheduler deferring a
+ * wake INTO a busy session), and only an exhausted wait surfaces the busy failure. Only a FIRST-event
+ * busy retries — a fail-fast reject is the only shape the engine emits it in, so nothing that started
+ * is ever re-run.
+ */
+export async function* streamTurnWithBusyRetry(agent, session, prompt, options) {
+    const { label, onCompleted, busyRetry = DEFAULT_BUSY_RETRY } = options;
+    const deadline = Date.now() + busyRetry.maxWaitMs;
+    for (;;) {
+        let retryBusy = false;
+        let first = true;
+        for await (const e of agent.invoke({ session }, prompt)) {
+            if (first && e.type === "failed" && e.code === SESSION_BUSY_CODE && Date.now() + busyRetry.delayMs < deadline) {
+                retryBusy = true; // fail-fast reject — the stream ends after this event; wait and re-invoke
+                break;
+            }
+            first = false;
+            if (e.type === "completed")
+                onCompleted?.(); // the turn is durably in the session — commit point
+            yield e;
+        }
+        if (!retryBusy)
+            return;
+        log.info(`${label} session ${session} is busy (an external turn holds it) — retrying in ${busyRetry.delayMs}ms`);
+        await new Promise((r) => setTimeout(r, busyRetry.delayMs));
+    }
+}
+/** The downloaded-file manifest appended to the prompt — the agent reads the paths with its tools.
+ *  Empty input renders nothing. */
+export function attachedFilesManifest(files) {
+    return files.length
+        ? `\n\n[attached files — read them with your tools:\n${files.map((f) => `- ${f.name} (${f.size} bytes) → ${f.path}`).join("\n")}\n]`
+        : "";
+}
+/** Decorate a background file's display name with its attribution ("the file Bob sent" resolves),
+ *  the way the fold attributes text lines. */
+export function attributedFileName(name, from, msg) {
+    return `${name} (from ${from}${msg !== undefined ? `, msg ${msg}` : ""}, earlier discussion)`;
+}
+/** The manifest attributing background vision images folded in from the earlier discussion — images
+ *  carry no per-image label inline, so position ("appended after N primary") is the attribution.
+ *  Channels whose image refs carry no attribution (telegram) simply don't render one. */
+export function backgroundImagesManifest(primaryCount, refs) {
+    return refs.length
+        ? `\n\n[background vision images from earlier discussion — appended after ${primaryCount} primary image(s):\n${refs
+            .map((ref, index) => `- vision image ${primaryCount + index + 1}: from ${ref.from}, msg ${ref.messageId}`)
+            .join("\n")}\n]`
+        : "";
+}
+/** The prompt note counting EVERY background attachment the turn does not carry (load failures +
+ *  cap-skipped) — without it, the model holds fold references it silently cannot open and may
+ *  pretend it read them. Neutral wording (platforms differ on WHY: expired file_ids, deleted files). */
+export function missingAttachmentsNote(missing) {
+    return missing > 0
+        ? `\n[note: ${missing} attachment(s) from the earlier discussion are not loaded (no longer available, or older than the most recent few)]`
+        : "";
+}

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

@@ -3,9 +3,10 @@
  * this module binds it to Lark's cloud profile and exposes natural Lark-branded public names. Lark's
  * weaker control-plane capabilities live in onboarding/registration, not in a fork of the turn engine.
  */
-import type { ChannelModule } from "../../host/node.ts";
-import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, defaultFeishuRoute } from "../feishu/feishu.ts";
+import type { ChannelModule, LongConnectionChannelModule } from "../../host/node.ts";
+import { type FeishuChannelOptions, type FeishuFailure, type FeishuMessage, type FeishuMessageEvent, type FeishuRoute, type FeishuWebSocketChannelOptions, defaultFeishuRoute } from "../feishu/feishu.ts";
 export type LarkChannelOptions = FeishuChannelOptions;
+export type LarkWebSocketChannelOptions = FeishuWebSocketChannelOptions;
 export type LarkFailure = FeishuFailure;
 export type LarkMessage = FeishuMessage;
 export type LarkMessageEvent = FeishuMessageEvent;
@@ -13,3 +14,4 @@ export type LarkRoute = FeishuRoute;
 export declare const defaultLarkRoute: typeof defaultFeishuRoute;
 export declare function larkEnvelope(event: LarkMessageEvent): string;
 export declare function larkChannel(opts: LarkChannelOptions): ChannelModule;
+export declare function larkWebSocketChannel(opts: LarkWebSocketChannelOptions): LongConnectionChannelModule;

package/dist/channels/lark/lark.js

@@ -1,5 +1,5 @@
 import { LARK_COMPAT_CLOUD } from "../feishu/cloud.js";
-import { buildFeishuChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
+import { buildFeishuChannel, buildFeishuWebSocketChannel, defaultFeishuRoute, } from "../feishu/feishu.js";
 import { cloudEnvelope } from "../feishu/parse.js";
 export const defaultLarkRoute = defaultFeishuRoute;
 export function larkEnvelope(event) {
@@ -8,3 +8,6 @@ export function larkEnvelope(event) {
 export function larkChannel(opts) {
     return buildFeishuChannel(LARK_COMPAT_CLOUD, opts, larkChannel.name);
 }
+export function larkWebSocketChannel(opts) {
+    return buildFeishuWebSocketChannel(LARK_COMPAT_CLOUD, opts, larkWebSocketChannel.name);
+}

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/preview-kit.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 } 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 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,183 @@
+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 in the live view. */
+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.
+ */
+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>;