@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/channels/feishu/register-webhook.js

@@ -7,20 +7,21 @@
  * Mechanism: the application-v7 config PATCH (`updateEventSubscription`) flips the app's event
  * subscription to webhook mode and points it at `<baseUrl>/<kind>`. Two properties make this the full
  * telegram-setWebhook parity: the platform applies a request-URL change IMMEDIATELY (no version
- * publish), and it VERIFIES the URL with a url_verification challenge during the PATCH — which is why
- * this waits for `<baseUrl>/health` to serve first (the same readiness race the telegram registrar
- * fixes). Requires the `application:application:patch` scope (field-tested: `self_manage` does NOT
- * cover this PATCH) — `add feishu` requests it at creation via addons; without it the PATCH fails
- * visibly and the manual console instruction is printed.
+ * publish), and it VERIFIES the URL with a url_verification challenge during the PATCH — which makes
+ * the PATCH its own readiness probe, retried below. (It used to poll `<baseUrl>/health` from here
+ * first; that asked whether THIS machine could reach a freshly minted hostname, which is routinely
+ * false for a minute or more while the platform reaches it fine — #421.) Requires the
+ * `application:application:patch` scope (field-tested: `self_manage` does NOT cover this PATCH) —
+ * `add feishu` requests it at creation via addons; without it the PATCH fails visibly and the manual
+ * console instruction is printed.
  *
  * CLOUD LAG: the application-v7 config API exists on open.feishu.cn but (as of 2026-07) is NOT
  * deployed on open.larksuite.com — the route 404s there. The registrar still attempts it (the day the
  * platform ships it, registration starts working with no change here) and names the real cause in the
  * fallback instead of blaming the app's scopes.
  */
-import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
-import { waitForHealth } from "../wait-health.js";
+import { retryWhile } from "../registration.js";
 import { cloudFor } from "./cloud.js";
 import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError } from "./feishu-api.js";
 export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
@@ -35,16 +36,6 @@ export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
         log.info(`[fastagent] ${kind}: set ${envPrefix}_APP_ID + ${envPrefix}_APP_SECRET in .env, then re-run to auto-register. Or ${manual}`);
         return "manual";
     }
-    // Align registration with the server actually serving: the PATCH triggers the platform's
-    // url_verification challenge against requestUrl — registering before /health serves would fail.
-    log.info(`[fastagent] ${kind}: waiting for ${baseUrl} to be reachable before registering the event URL…`);
-    const ready = await waitForHealth(`${baseUrl}/health`, opts.readyTimeoutMs ?? 120_000, opts.readyIntervalMs ?? 3_000);
-    if (!ready) {
-        // Terminal for this run (registration will not be retried) — error, not warn: the event URL is NOT
-        // registered and the operator must act. Same taxonomy as the permanent PATCH failure below.
-        log.error(`[fastagent] ${kind}: ${baseUrl}/health did not come up in time — the app may still be starting. ${manual}`);
-        return "failed";
-    }
     const api = createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret });
     const consoleUrl = `${apiBase}/app/${encodeURIComponent(appId)}/event`;
     const versionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/version`;
@@ -61,46 +52,41 @@ export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
             log.warn(`[fastagent] ${kind}: could not open Events & Callbacks: ${String(callbackError)}`);
         }
     };
-    // Reachable → register. The PATCH is the real probe (same lesson as the token bootstrap): the
-    // platform verifies request_url with a challenge DURING the call, and a fresh tunnel's edge can be
-    // reachable from here while the platform's own path still lags — its 210042 "request_url validation
-    // failed" is therefore retried with backoff, alongside transient network errors. Only a permanent
-    // config error (missing scope, app under review, the intl 404) is reported once with the manual path.
-    const attempts = 8;
-    for (let attempt = 0; attempt < attempts; attempt++) {
-        if (attempt > 0)
-            await sleep(opts.retryMs ?? 10_000);
-        try {
-            await api.updateEventSubscription(appId, { subscriptionType: "webhook", requestUrl });
-            log.info(`[fastagent] ${kind}: event Request URL registered → ${requestUrl}`);
-            // Field-tested: a URL change applies immediately, but the MODE flip (the template's long
-            // connection → webhook) only takes effect when a version is published — the dispatcher serves
-            // the published snapshot, and version publishing has no open API. One console click, once.
-            log.info(`[fastagent] ${kind}: if messages do not arrive, publish a version (one click, prompted) — the switch to webhook mode takes effect on publish: ${versionUrl}`);
-            return "registered";
-        }
-        catch (e) {
-            // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is
-            // live on open.feishu.cn but not yet on open.larksuite.com. Name that — "check your scopes"
-            // would send the operator hunting for a problem they cannot fix.
-            if (isFeishuConfigApiMissing(e)) {
-                log.warn(`[fastagent] ${kind}: this cloud (${apiBase}) returned HTTP 404 for the app-config API — ` +
-                    `manual registration is required`);
-                manualRegistration();
-                return "manual"; // that cloud has no config API — the manual path is the norm there
-            }
-            if (!isTransientFeishuRegistrationError(e)) {
-                log.error(`[fastagent] ${kind}: could not register the event URL (${String(e)}). ` +
-                    `The app may lack the "application:application:patch" scope (console → Permissions) or be under review; manual registration is available below.`);
-                manualRegistration();
-                return "failed";
-            }
+    // The PATCH is the probe (same lesson as the token bootstrap): the platform verifies request_url
+    // with a challenge DURING the call, so its 210042 "request_url validation failed" is the readiness
+    // signal and is retried with backoff, alongside transient network errors. Only a permanent config
+    // error (missing scope, app under review, the intl 404) is reported once with the manual path.
+    try {
+        await retryWhile(() => api.updateEventSubscription(appId, { subscriptionType: "webhook", requestUrl }), isTransientFeishuRegistrationError, {
+            attempts: opts.attempts,
+            retryMs: opts.retryMs,
+            onRetry: ({ attempt, attempts }) => log.info(`[fastagent] ${kind}: the platform cannot verify ${requestUrl} yet (attempt ${attempt}/${attempts}); retrying…`),
+        });
+        log.info(`[fastagent] ${kind}: event Request URL registered → ${requestUrl}`);
+        // Field-tested: a URL change applies immediately, but the MODE flip (the template's long
+        // connection → webhook) only takes effect when a version is published — the dispatcher serves
+        // the published snapshot, and version publishing has no open API. One console click, once.
+        log.info(`[fastagent] ${kind}: if messages do not arrive, publish a version (one click, prompted) — the switch to webhook mode takes effect on publish: ${versionUrl}`);
+        return "registered";
+    }
+    catch (e) {
+        // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is
+        // live on open.feishu.cn but not yet on open.larksuite.com. Name that — "check your scopes"
+        // would send the operator hunting for a problem they cannot fix. It stays WARN: on that cloud the
+        // manual path is the known norm, not an exceptional failure.
+        if (isFeishuConfigApiMissing(e)) {
+            log.warn(`[fastagent] ${kind}: this cloud (${apiBase}) returned HTTP 404 for the app-config API — ` +
+                `manual registration is required`);
+            manualRegistration();
+            return "manual"; // that cloud has no config API — the manual path is the norm there
         }
+        // Exhausted retries end in the same state as a permanent config error (event URL not registered,
+        // manual action required) — report at the same level.
+        log.error(isTransientFeishuRegistrationError(e)
+            ? `[fastagent] ${kind}: the platform could not verify ${requestUrl} after retries — manual registration is required`
+            : `[fastagent] ${kind}: could not register the event URL (${String(e)}). ` +
+                `The app may lack the "application:application:patch" scope (console → Permissions) or be under review; manual registration is available below.`);
+        manualRegistration();
+        return "failed";
     }
-    // Exhausted retries end in the same state as a permanent error (event URL not registered, manual
-    // action required) — report at the same level. The cloud-lag 404 above stays warn: on that cloud the
-    // manual path is the known norm, not an exceptional failure.
-    log.error(`[fastagent] ${kind}: registration still failing after retries — manual registration is required`);
-    manualRegistration();
-    return "failed";
 }

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

@@ -1,58 +1,8 @@
 import { defineTool, z } from "@fastagent-sh/fastagent";
+import { feishuTransport } from "@fastagent-sh/fastagent/feishu";
 
-// Send a message to a Feishu chat. In a CHAT turn the channel delivers the reply itself — this
-// tool is for turns NO channel is carrying: a scheduled turn (schedules/<name>.ts) or a self-scheduled
-// wake-up, whose plain reply is not delivered anywhere. The chatId comes from the [feishu: chat …]
-// 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.
-
-// 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.
-const BASE = "https://open.feishu.cn";
-
-async function callApi(path: string, body: unknown, token?: string): Promise<Record<string, unknown>> {
-  let res: Response;
-  let raw: string;
-  try {
-    res = await fetch(`${BASE}${path}`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-        ...(token ? { authorization: `Bearer ${token}` } : {}),
-      },
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(30_000),
-    });
-    raw = await res.text();
-  } catch (e) {
-    throw new Error(`feishu ${path}: ${String(e)}`, { cause: e });
-  }
-  let data: { code?: number; msg?: string; [k: string]: unknown };
-  try {
-    data = JSON.parse(raw) as typeof data;
-  } catch {
-    data = {};
-  }
-  if (!res.ok || data.code !== 0) {
-    throw new Error(`feishu ${path} failed: ${res.status} ${data.msg ?? "response was not the expected JSON"}`);
-  }
-  return data;
-}
-
-async function tenantToken(): Promise<string> {
-  const appId = process.env.FEISHU_APP_ID;
-  const appSecret = process.env.FEISHU_APP_SECRET;
-  if (!appId || !appSecret) throw new Error("FEISHU_APP_ID / FEISHU_APP_SECRET are not set");
-  const data = await callApi("/open-apis/auth/v3/tenant_access_token/internal", {
-    app_id: appId,
-    app_secret: appSecret,
-  });
-  const token = data.tenant_access_token;
-  if (typeof token !== "string") throw new Error("feishu tenant_access_token: response carried no token");
-  return token;
-}
+// Proactive delivery uses the mounted channel's credentials, gateway and token cache. With no
+// channel mounted (fire/invoke/tool), it reads FEISHU_APP_ID / FEISHU_APP_SECRET from the environment.
 
 export default defineTool({
   description:
@@ -70,23 +20,18 @@ export default defineTool({
     text: z.string().optional().describe("plain text message to send"),
     markdown: z.string().optional().describe("markdown to send as a card"),
   }),
-  async execute({ chatId, text, markdown }) {
+  async execute({ chatId, text, markdown }, ctx) {
     if ((text === undefined) === (markdown === undefined)) {
       throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
     }
-    const token = await tenantToken();
-    const msg =
-      text !== undefined
-        ? { msg_type: "text", content: JSON.stringify({ text }) }
-        : {
-            msg_type: "interactive",
-            // An inline static card: one markdown element, no entity/streaming machinery needed here.
-            content: JSON.stringify({
-              schema: "2.0",
-              body: { elements: [{ tag: "markdown", content: markdown }] },
-            }),
-          };
-    await callApi(`/open-apis/im/v1/messages?receive_id_type=chat_id`, { receive_id: chatId, ...msg }, token);
+    const api = feishuTransport(ctx.cwd);
+    if (text !== undefined) await api.sendText({ chatId }, text);
+    else {
+      await api.sendMessage(chatId, "interactive", JSON.stringify({
+        schema: "2.0",
+        body: { elements: [{ tag: "markdown", content: markdown }] },
+      }));
+    }
     return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
   },
 });

package/dist/channels/feishu/setup-mode.d.ts

@@ -4,6 +4,36 @@ export type FeishuSubscriptionMode = "webhook" | "websocket";
  * runtime remains capability-driven because the platform, not channel source, decides which events
  * are delivered. */
 export type FeishuGroupBehavior = "context" | "mentions";
+/**
+ * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and
+ * adding a scope to the app draft during context-aware group setup.
+ *
+ * Requested at creation for BOTH ingress modes, though only webhook uses it on day one. A WebSocket
+ * app that later wants webhook delivery cannot acquire it in passing: changing mode is a migration
+ * the CLI deliberately refuses to perform (`resolveIngress`), so the app would have to be recreated
+ * or the scope added by hand in the console after a failed PATCH. It is not a data scope — it reads
+ * and writes this app's own configuration — so carrying it costs an app nothing and keeps the one
+ * door open that the alternative nails shut.
+ */
+export declare const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
+/** The one event an agent app cannot serve without: an inbound message. */
+export declare const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
+/**
+ * What a created app carries on top of the platform's agent template, for EITHER ingress — the
+ * `addons` merged onto the confirm page. Here rather than inline at the call site because it is a
+ * policy decision (which capabilities an app is born with), and the CLI layer that requests it is
+ * terminal wiring with no seam to test through.
+ */
+export declare function feishuAppAddons(): {
+    scopes: {
+        tenant: string[];
+    };
+    events: {
+        items: {
+            tenant: string[];
+        };
+    };
+};
 /** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
 export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
 /** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).

package/dist/channels/feishu/setup-mode.js

@@ -1,3 +1,29 @@
+/**
+ * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and
+ * adding a scope to the app draft during context-aware group setup.
+ *
+ * Requested at creation for BOTH ingress modes, though only webhook uses it on day one. A WebSocket
+ * app that later wants webhook delivery cannot acquire it in passing: changing mode is a migration
+ * the CLI deliberately refuses to perform (`resolveIngress`), so the app would have to be recreated
+ * or the scope added by hand in the console after a failed PATCH. It is not a data scope — it reads
+ * and writes this app's own configuration — so carrying it costs an app nothing and keeps the one
+ * door open that the alternative nails shut.
+ */
+export const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
+/** The one event an agent app cannot serve without: an inbound message. */
+export const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
+/**
+ * What a created app carries on top of the platform's agent template, for EITHER ingress — the
+ * `addons` merged onto the confirm page. Here rather than inline at the call site because it is a
+ * policy decision (which capabilities an app is born with), and the CLI layer that requests it is
+ * terminal wiring with no seam to test through.
+ */
+export function feishuAppAddons() {
+    return {
+        scopes: { tenant: [FEISHU_APP_CONFIG_SCOPE] },
+        events: { items: { tenant: [FEISHU_MESSAGE_RECEIVE_EVENT] } },
+    };
+}
 /** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
 export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
 /** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).

package/dist/channels/feishu/shared-api.d.ts

@@ -0,0 +1,10 @@
+import { type FeishuCloudKind } from "./cloud.ts";
+import { type FeishuApi } from "./feishu-api.ts";
+/** The delivery methods a proactive sender needs. */
+export type FeishuTransport = Pick<FeishuApi, "sendText" | "sendMessage">;
+/** A remount replaces the transport; separate clouds can share one agent state root. */
+export declare function registerFeishuApi(stateRoot: string, kind: FeishuCloudKind, api: FeishuApi): void;
+/** Resolve the Feishu transport for a tool's workspace (`ctx.cwd`). */
+export declare function feishuTransport(cwd: string): FeishuTransport;
+/** Resolve the Lark transport for a tool's workspace (`ctx.cwd`). */
+export declare function larkTransport(cwd: string): FeishuTransport;

package/dist/channels/feishu/shared-api.js

@@ -0,0 +1,38 @@
+/** The mounted channel and proactive tools share credentials, token cache, gateway and retry policy. */
+import { findAgentDir, resolveStateRoot } from "../../paths.js";
+import { cloudFor } from "./cloud.js";
+import { createFeishuApi } from "./feishu-api.js";
+const byKind = {
+    feishu: new Map(),
+    lark: new Map(),
+};
+/** A remount replaces the transport; separate clouds can share one agent state root. */
+export function registerFeishuApi(stateRoot, kind, api) {
+    byKind[kind].set(stateRoot, api);
+}
+function cloudTransport(cwd, kind) {
+    // Embedded senders may use a bare definition directory or an independent workspace.
+    const stateRoot = resolveStateRoot(findAgentDir(cwd) ?? cwd);
+    const transports = byKind[kind];
+    let api = transports.get(stateRoot);
+    if (!api) {
+        // fire/invoke/tool do not mount channels, so their credentials come from the agent's environment.
+        const { apiBase, envPrefix } = cloudFor(kind);
+        const appId = process.env[`${envPrefix}_APP_ID`];
+        const appSecret = process.env[`${envPrefix}_APP_SECRET`];
+        if (!appId || !appSecret) {
+            throw new Error(`${envPrefix}_APP_ID / ${envPrefix}_APP_SECRET are not set and no ${kind} channel is mounted`);
+        }
+        api = createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret });
+        transports.set(stateRoot, api);
+    }
+    return api;
+}
+/** Resolve the Feishu transport for a tool's workspace (`ctx.cwd`). */
+export function feishuTransport(cwd) {
+    return cloudTransport(cwd, "feishu");
+}
+/** Resolve the Lark transport for a tool's workspace (`ctx.cwd`). */
+export function larkTransport(cwd) {
+    return cloudTransport(cwd, "lark");
+}

package/dist/channels/http.d.ts

@@ -13,14 +13,6 @@ import type { Agent } from "../agent.ts";
 /** 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 declare const MAX_BODY_BYTES: number;
-/** 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 declare const SSE_HEARTBEAT_MS = 30000;
-/** 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 declare function sseHeartbeat(controller: ReadableStreamDefaultController<Uint8Array>): () => void;
 /** 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 declare const INVOKE_EXAMPLE_BODY = "{\"session\":\"dev\",\"text\":\"hello\"}";

package/dist/channels/http.js

@@ -1,28 +1,9 @@
 import { readBodyCapped } from "./body.js";
 import { text } from "./respond.js";
+import { sseResponse } from "./sse.js";
 /** 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"}';
@@ -48,7 +29,7 @@ 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.
+        // INVOKE_EXAMPLE_BODY must keep satisfying this request shape.
         // The OPTIONAL lineage extension (Scope): malformed values are a 400, not a silent drop — a
         // caller that sent them meant them.
         if (parentSession !== undefined && typeof parentSession !== "string") {
@@ -57,43 +38,10 @@ export function createInvokeHandler(agent) {
         if (branchHints !== undefined && !(Array.isArray(branchHints) && branchHints.every((h) => typeof h === "string"))) {
             return text('"branchHints" must be an array of strings\n', 400);
         }
-        // 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({
+        return sseResponse(agent.invoke({
             session,
             ...(parentSession !== undefined ? { parentSession } : {}),
             ...(branchHints !== undefined ? { branchHints } : {}),
-        }, { 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?.();
-            },
-        });
-        return new Response(stream, {
-            status: 200,
-            headers: {
-                "content-type": "text/event-stream",
-                "cache-control": "no-cache",
-                connection: "keep-alive",
-            },
-        });
+        }, { text: promptText }));
     };
 }

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

@@ -0,0 +1,59 @@
+import type { ContextBuffer } from "./context-buffer.ts";
+import { type TurnRecordBase, type TurnStore } from "./turn-store.ts";
+/** A pending turn is the persisted intent minus its attempt count, plus live-only fields the
+ *  channel adds (a notice's message id) — never persisted, reconstructed fresh on replay. */
+export type PendingBase<S extends TurnRecordBase> = Omit<S, "attempts">;
+export interface TurnRunnerOptions<R extends PendingBase<S>, S extends TurnRecordBase, E> {
+    label: string;
+    store: TurnStore<S>;
+    buffer: ContextBuffer<E>;
+    /** Delivery dedup by platform id, recorded post-persist (Slack, Feishu). */
+    seen?: {
+        add(id: string): void;
+    };
+    /** The persisted intent for a pending turn — drops the live-only fields. */
+    toStored(rec: R): S;
+    /** A recovered intent as a pending turn — live-only fields start absent. */
+    fromStored(stored: S): R;
+    /** The context-buffer bucket this turn folds. */
+    bufferKey(rec: R): string;
+    /** The place, for the lifecycle log line (`chat=… thread=…`). */
+    where(rec: R): string;
+    /** Queue feedback when a turn is scheduled BEHIND an active one. Returns what the runner awaits at
+     *  dequeue (so the turn reliably takes the notice over instead of racing it) and, optionally, how
+     *  to cancel a notice that has not fired yet. `done` may reject — posting the notice is a platform
+     *  call — and the runner logs that and runs the turn anyway. */
+    onQueuedBehind?(rec: R): {
+        done: Promise<void>;
+        cancel?: () => void;
+    };
+    /** Runs before the attempt is counted. Answer false to leave the intent untouched for a later run
+     *  (Slack: its transport is known to be down, so an Agent turn now would have nowhere to answer). */
+    beforeRun?(rec: R): Promise<boolean>;
+    /** The attempt could not be recorded (disk failure): a restart replays the turn, so say so on any
+     *  notice it holds rather than leaving it pinned at "Queued". */
+    onDeferred(rec: R): void;
+    /** The turn started the ceiling's worth of times without finishing: tell the asker. */
+    notifyDropped(rec: R): void;
+    /** Run the turn. `onCompleted` is the durable-commit point (the turn's `completed` event): it drops
+     *  the intent and commits the folded discussion, in that order. A throw is logged as the turn's
+     *  failure; the intent is dropped either way. */
+    execute(rec: R, discussion: {
+        text: string;
+        consumed: E[];
+    }, onCompleted: () => void): Promise<void>;
+}
+export interface TurnRunner<R, S> {
+    /** Accept a turn: persist its intent (pre-ACK — a failed write throws so the platform redelivers),
+     *  record the delivery id, enqueue. Recovery re-enqueues without re-persisting. */
+    submit(rec: R, persist: boolean): void;
+    /** Re-enqueue the turns a prior crash left mid-flight; returns them so a channel can continue its
+     *  arrival counter. */
+    recover(): S[];
+    /** Resolve once no turn is in flight — the test/observability seam. */
+    idle(): Promise<void>;
+}
+export declare function createTurnRunner<R extends PendingBase<S> & {
+    id: string;
+    session: string;
+}, S extends TurnRecordBase, E>(options: TurnRunnerOptions<R, S, E>): TurnRunner<R, S>;

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

@@ -0,0 +1,84 @@
+/**
+ * The durable-turn LIFECYCLE the stateful chat channels share, over the kit's parts: accept
+ * (persist pre-ACK, dedup, enqueue) → dequeue (settle the queue notice, count the attempt against
+ * the poison ceiling, fold the buffered discussion) → execute → end (log, drop the intent). Telegram,
+ * Slack and Feishu each wrote this out; the copies had already drifted in small ways that were not
+ * decisions (which one deletes its notice on defer, which one logs the duration on failure).
+ *
+ * What stays with the platform is everything that names a platform object: how a queue notice is
+ * mounted and taken over, what the prompt looks like, how attachments resolve, what a dropped turn
+ * says and where. Those arrive as hooks; the ORDER they run in is this module's.
+ */
+import { log } from "../../log.js";
+import { createTurnQueue } from "./turn-queue.js";
+import { commitAnsweredTurn } from "./turn-store.js";
+export function createTurnRunner(options) {
+    const { label, store, buffer, seen, onQueuedBehind } = options;
+    const notices = new Map();
+    const queue = createTurnQueue({
+        label,
+        onQueuedBehind: onQueuedBehind && ((rec) => notices.set(rec.id, onQueuedBehind(rec))),
+        run: async (rec) => {
+            // Runs at DEQUEUE time (serialized). The queue wait is over: cancel a notice that has not
+            // fired, then settle so the turn's preview handle is final — in the common path this await is
+            // instant. BEFORE the ceiling check so a dropped or deferred turn can take the notice over too.
+            const notice = notices.get(rec.id);
+            notice?.cancel?.();
+            // The notice is the PLATFORM's feedback, not the turn: a failed post must not throw out of the
+            // run, which would leak the persisted intent (removed only below) into a replay that burns an
+            // attempt against the ceiling. Logged, then the turn proceeds without its handle.
+            await notice?.done.catch((error) => log.warn(`${label} queue notice failed: turn=${rec.id} session=${rec.session}: ${String(error)}`));
+            notices.delete(rec.id);
+            if (options.beforeRun && !(await options.beforeRun(rec)))
+                return;
+            const decision = store.startAttempt(rec.id);
+            if (decision === "exceeded") {
+                options.notifyDropped(rec);
+                return;
+            }
+            if (decision === "defer") {
+                options.onDeferred(rec);
+                return;
+            }
+            const startedAt = Date.now();
+            log.info(`${label} turn start: turn=${rec.id} session=${rec.session} ${options.where(rec)}`);
+            // Snapshot the discussion at dequeue; commit only this snapshot on `completed`, so a message
+            // arriving while the turn runs stays buffered for the next answered turn.
+            const bufferKey = options.bufferKey(rec);
+            const discussion = buffer.peek(bufferKey);
+            try {
+                await options.execute(rec, discussion, () => commitAnsweredTurn(store, buffer, { id: rec.id, bufferKey, consumed: discussion.consumed }));
+                log.info(`${label} turn done: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms)`);
+            }
+            catch (error) {
+                log.error(`${label} turn failed: turn=${rec.id} session=${rec.session} (${Date.now() - startedAt}ms): ${String(error)}`);
+            }
+            finally {
+                // Fallback removal for the caught-error paths (a `failed` event or a transport throw): those
+                // never reach the completed hook. Idempotent. Only an INTERRUPTED run (this finally never
+                // runs — a crash or SIGTERM deploy) leaves the record for replay; a transport throw is
+                // dropped, not retried (safe retry needs an L2 delivery key).
+                store.remove(rec.id);
+            }
+        },
+    });
+    const submit = (rec, persist) => {
+        if (persist) {
+            store.add(options.toStored(rec)); // pre-ACK: a failed write throws → 500 → redelivery
+            seen?.add(rec.id); // post-persist — recording first could turn a failed write into silent loss
+        }
+        queue.accept(rec);
+    };
+    return {
+        submit,
+        recover() {
+            const recovered = store.recover();
+            if (recovered.length > 0)
+                log.info(`${label} recovering ${recovered.length} unfinished turn(s) from a prior run`);
+            for (const stored of recovered)
+                submit(options.fromStored(stored), false);
+            return recovered;
+        },
+        idle: () => queue.idle(),
+    };
+}