@fastagent-sh/fastagent 0.12.0 → 0.13.0

package/dist/channels/lark/onboard.js

@@ -0,0 +1,58 @@
+/**
+ * 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
+ * set; a complete existing ID/Secret pair resumes that App directly. Then optimistically run Feishu's
+ * webhook-mode + Verification-Token bootstrap against THIS app: a successful PATCH captures the token
+ * and flips Subscription mode; only a definitive config-route 404 falls back to the token the console
+ * displays + a manual mode switch. IO is injected so the workflow is testable without a terminal or
+ * browser.
+ */
+export const LARK_CONSOLE_URL = "https://open.larksuite.com/page/launcher?from=backend_oneclick";
+/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
+export function larkEventSecurityUrl(appId) {
+    return `https://open.larksuite.com/app/${encodeURIComponent(appId)}/event?tab=safe`;
+}
+function required(value, name) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        throw new Error(`${name} is required — re-run \`fastagent add lark\` to continue setup`);
+    return trimmed;
+}
+/** 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 async function onboardLarkApp(io, opts) {
+    const existingId = opts.existing?.LARK_APP_ID?.trim();
+    const existingSecret = opts.existing?.LARK_APP_SECRET?.trim();
+    const reuseExistingApp = Boolean(existingId && existingSecret);
+    // Credentials are one App-scoped set. Reuse only a COMPLETE ID/Secret pair; a partial pair starts a
+    // fresh launcher/input path, and its unrelated old Token must not be attached to the newly-entered App.
+    if (reuseExistingApp) {
+        io.note(`Reusing Lark app ${existingId}; opening its Events & Callbacks configuration directly.`);
+    }
+    else {
+        io.note(`Create the app on Lark's one-click launcher. Opening ${LARK_CONSOLE_URL}`);
+        io.openUrl(LARK_CONSOLE_URL);
+    }
+    const appId = required(reuseExistingApp ? existingId : await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID");
+    const appSecret = required(reuseExistingApp ? existingSecret : await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET");
+    await opts.verifyCredentials(appId, appSecret);
+    const eventSecurityUrl = larkEventSecurityUrl(appId);
+    io.note(`App ID / Secret verified. Opening Events & Callbacks → Security: ${eventSecurityUrl}`);
+    io.openUrl(eventSecurityUrl);
+    io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
+    const bootstrap = await opts.bootstrapWebhook(appId, appSecret);
+    if (bootstrap.token) {
+        io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");
+    }
+    else {
+        io.note(`${bootstrap.manualReason ?? "Automatic bootstrap unavailable."} Open Events & Callbacks → Encryption Strategy and copy the Verification Token. You must also switch Subscription mode to webhook when setting the Request URL.`);
+    }
+    const verificationToken = required(bootstrap.token ||
+        (reuseExistingApp ? opts.existing?.LARK_VERIFICATION_TOKEN?.trim() : undefined) ||
+        (await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN");
+    return {
+        LARK_APP_ID: appId,
+        LARK_APP_SECRET: appSecret,
+        LARK_VERIFICATION_TOKEN: verificationToken,
+    };
+}

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

@@ -0,0 +1,32 @@
+import { larkChannel } from "@fastagent-sh/fastagent/lark";
+
+// larkChannel is the branded compatibility adapter over fastagent's canonical Feishu engine, configured
+// with YOUR policy. fastagent discovers this file, mounts POST /lark, and pipes the agent + state home
+// to the adapter. Lark international (open.larksuite.com) only; a
+// Feishu tenant uses `fastagent add feishu` instead. Setup (developer console):
+//   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
+//   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)
+//   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
+//      the URL automatically. If this app returns a config-API 404, do both BY HAND in the console
+//      with the server running (the platform verifies https://your.host/lark with a challenge).
+//   5. create a version and publish the app (a tenant admin approves it), then add the bot to a chat
+export default larkChannel({
+  appId: process.env.LARK_APP_ID ?? "", // missing → fails at startup (no replies could be sent)
+  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
+  // 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 only on an @mention of this bot (matched by open_id, resolved at
+  // startup). Override to customise, 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

@@ -0,0 +1,87 @@
+import { defineTool, z } from "@fastagent-sh/fastagent";
+
+// Send a message to a Lark 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 [lark: 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.
+
+// Standalone 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.larksuite.com";
+
+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(`lark ${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(`lark ${path} failed: ${res.status} ${data.msg ?? "response was not the expected JSON"}`);
+  }
+  return data;
+}
+
+async function tenantToken(): Promise<string> {
+  const appId = process.env.LARK_APP_ID;
+  const appSecret = process.env.LARK_APP_SECRET;
+  if (!appId || !appSecret) throw new Error("LARK_APP_ID / LARK_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("lark tenant_access_token: response carried no token");
+  return token;
+}
+
+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.",
+  input: z.object({
+    chatId: z.string().describe("target chat id (oc_…)"),
+    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 }) {
+    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);
+    return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
+  },
+});

package/dist/channels/registration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SHARED: the webhook registrars' outcome. A registrar reports its own FACT; what to do about it (gate
+ * the deploy or not, and with what remediation) is the CALLER's policy — `deploy --run` gates on
+ * "failed", the tunnel (a long-running dev process) ignores the result entirely.
+ *
+ * - "registered": the platform accepted the webhook / event URL.
+ * - "manual": this run did not fail, but an operator-facing step remains (the registrar printed the
+ *   instructions). Two sub-states differ on re-runnability: credentials not configured (re-run after
+ *   setting .env DOES auto-register; on the deploy path this is pre-gated by missingSecrets and
+ *   unreachable) and a cloud without the config API (the Lark cloud-lag 404 — no re-run can ever
+ *   register it; the console is the only path).
+ * - "failed": this run ends with the webhook NOT registered, and acting + re-running can fix it
+ *   (health timeout, a permanent config error, exhausted retries).
+ */
+export type RegistrationOutcome = "registered" | "manual" | "failed";

package/dist/channels/registration.js

@@ -0,0 +1 @@
+export {};

package/dist/channels/{telegram/state.js → state.js}

@@ -3,7 +3,9 @@
  * cross-instance locking; two processes must not share a state dir). Small JSON files, written
  * atomically (tmp + rename), so a crash leaves the previous version on disk, never a torn file.
  * Writes are synchronous: the files are KB-sized and a write that completes BEFORE the webhook 200
- * is what makes the state actually durable (an ACKed update is never redelivered by Telegram).
+ * is what makes the state actually durable (an ACKed webhook delivery is not redelivered).
+ * Channel-neutral: every stateful channel (telegram, Feishu; Lark compatibility) derives its home from the ctx state root
+ * and persists through these three primitives.
  *
  * Failure split: a CORRUPT file (bad JSON) degrades visibly — log.warn + start empty — because channel
  * state is recoverable context, not worth refusing to boot over. An unreadable file (permissions, IO)
@@ -12,7 +14,7 @@
  */
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { log } from "../../log.js";
+import { log } from "../log.js";
 /** Create the state home and self-ignore it (`.gitignore="*"`): its contents (buffers, downloaded
  *  files) can carry chat content and must never be committable. The workspace opener already protects
  *  an in-tree state root; this local guard also covers direct embedders. `wx` never clobbers an
@@ -38,7 +40,7 @@ export function loadStateFile(path) {
         if (e.code === "ENOENT")
             return undefined; // first run — normal
         // Permissions/IO: an environment error — fail the boot loudly rather than run on invisible state.
-        throw new Error(`telegram state file ${path} is unreadable — fix permissions/disk and restart: ${String(e)}`, {
+        throw new Error(`channel state file ${path} is unreadable — fix permissions/disk and restart: ${String(e)}`, {
             cause: e,
         });
     }
@@ -46,7 +48,7 @@ export function loadStateFile(path) {
         return JSON.parse(raw);
     }
     catch (e) {
-        log.warn(`[telegram] corrupt state file ${path} — starting empty: ${String(e)}`);
+        log.warn(`[fastagent] corrupt state file ${path} — starting empty: ${String(e)}`);
         return undefined;
     }
 }

package/dist/channels/telegram/context-buffer.js

@@ -12,7 +12,7 @@
  * survives for the next answered turn (a whole-bucket delete would lose it).
  */
 import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "./state.js";
+import { loadStateFile, saveStateFile } from "../state.js";
 /** Char budget for the per-place buffer — bounds the cost of folding it into a prompt; when exceeded
  *  the OLDEST un-summoned messages are dropped (not a time window: a quiet group keeps its
  *  sparse-but-relevant lines, a busy burst is capped). */

package/dist/channels/telegram/register-webhook.d.ts

@@ -1,3 +1,4 @@
+import type { RegistrationOutcome } from "../registration.ts";
 /**
  * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Waits for the server to be
  * REACHABLE first — polling `<baseUrl>/health` — because Telegram VERIFIES the URL when you set it, and a
@@ -5,9 +6,11 @@
  * seconds after the deploy/tunnel command returns. Tracking real readiness (not a fixed timer) is what
  * fixes the race that made the first real deploy need a manual `setWebhook`. Missing tokens print the
  * manual instruction instead of failing. `opts` (timeouts) exist for tests; production uses the defaults.
+ *
+ * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
 export declare function registerTelegramWebhook(baseUrl: string, opts?: {
     readyTimeoutMs?: number;
     readyIntervalMs?: number;
     retryMs?: number;
-}): Promise<void>;
+}): Promise<RegistrationOutcome>;

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

@@ -5,6 +5,7 @@
  */
 import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
+import { waitForHealth } from "../wait-health.js";
 import { callApi } from "./telegram-api.js";
 /**
  * Register `<baseUrl>/telegram` as the bot's webhook (with the .env secret). Waits for the server to be
@@ -13,6 +14,8 @@ import { callApi } from "./telegram-api.js";
  * seconds after the deploy/tunnel command returns. Tracking real readiness (not a fixed timer) is what
  * fixes the race that made the first real deploy need a manual `setWebhook`. Missing tokens print the
  * manual instruction instead of failing. `opts` (timeouts) exist for tests; production uses the defaults.
+ *
+ * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
 export async function registerTelegramWebhook(baseUrl, opts = {}) {
     const botToken = process.env.TELEGRAM_BOT_TOKEN;
@@ -20,54 +23,42 @@ export async function registerTelegramWebhook(baseUrl, opts = {}) {
     const webhookUrl = `${baseUrl}/telegram`;
     if (!botToken || !secret) {
         log.info(`[fastagent] telegram: set TELEGRAM_BOT_TOKEN + TELEGRAM_SECRET_TOKEN in .env, then re-run to auto-register. Webhook URL: ${webhookUrl}`);
-        return;
+        return "manual";
     }
     // Align registration with the server actually serving. Don't setWebhook against a URL Telegram can't
     // yet reach — it would fail, and a fixed retry window guesses the readiness delay (the deploy race).
     log.info(`[fastagent] telegram: waiting for ${baseUrl} to be reachable before registering the webhook…`);
     const ready = await waitForHealth(`${baseUrl}/health`, opts.readyTimeoutMs ?? 120_000, opts.readyIntervalMs ?? 3_000);
     if (!ready) {
-        log.warn(`[fastagent] telegram: ${baseUrl}/health did not come up in time — the app may still be starting. ` +
+        // Terminal for this run (registration will not be retried) — error, not warn: the webhook is NOT
+        // registered and the operator must act. Same taxonomy as the permanent setWebhook failure below.
+        log.error(`[fastagent] telegram: ${baseUrl}/health did not come up in time — the app may still be starting. ` +
             `Register the webhook manually once it's up: curl "https://api.telegram.org/bot<token>/setWebhook" -d url=${webhookUrl} -d secret_token=<secret>`);
-        return;
+        return "failed";
     }
     // Reachable → register. A short retry backstops Telegram's resolver lagging /health by a moment; only
     // network-transient errors retry (a permanent "bad webhook" config error is reported, not retried).
+    let lastTransientError = "unknown transport error";
     for (let attempt = 0; attempt < 3; attempt++) {
         if (attempt > 0)
             await sleep(opts.retryMs ?? 2000);
         try {
             await callApi("https://api.telegram.org", botToken, "setWebhook", { url: webhookUrl, secret_token: secret });
             log.info(`[fastagent] telegram: webhook registered → ${webhookUrl}`);
-            return;
+            return "registered";
         }
         catch (e) {
             const error = String(e);
             if (!/resolve host|getaddrinfo|ENOTFOUND|fetch failed|ECONNRESET|timeout/i.test(error)) {
                 log.error(`[fastagent] telegram: setWebhook failed (${error}). Register manually with url=${webhookUrl}`);
-                return;
+                return "failed";
             }
+            lastTransientError = error;
         }
     }
-    log.warn(`[fastagent] telegram: setWebhook still failing after retries. Register manually with url=${webhookUrl}`);
-}
-/**
- * Poll `healthUrl` until it responds 200, or the timeout elapses. Any error (not routable yet, DNS not
- * settled, connection refused) is a "keep waiting", not a failure — that IS the readiness signal. Each
- * probe has its own short timeout so one slow attempt can't eat the whole budget.
- */
-async function waitForHealth(healthUrl, timeoutMs, intervalMs) {
-    const deadline = Date.now() + timeoutMs;
-    for (;;) {
-        try {
-            if ((await fetch(healthUrl, { signal: AbortSignal.timeout(5000) })).ok)
-                return true;
-        }
-        catch {
-            /* not routable yet — keep polling until the deadline */
-        }
-        if (Date.now() >= deadline)
-            return false;
-        await sleep(intervalMs);
-    }
+    // Exhausted retries end in the same state as a permanent error (webhook not registered, manual
+    // action required) — report at the same level.
+    log.error(`[fastagent] telegram: setWebhook still failing after retries (last error: ${lastTransientError}). ` +
+        `Register manually with url=${webhookUrl}`);
+    return "failed";
 }

package/dist/channels/telegram/telegram.js

@@ -31,9 +31,9 @@ import { invokeTurn } from "./invoke-turn.js";
 import { collectAttachments, createContextBuffer } from "./context-buffer.js";
 import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
 import { defaultErrorMessage, streamReply } from "./preview.js";
-import { ensureStateHome } from "./state.js";
+import { ensureStateHome } from "../state.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
-import { createTurnQueue } from "./turn-queue.js";
+import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "./turn-store.js";
 // Re-export the public surface authored elsewhere, so `@fastagent-sh/fastagent/telegram` keeps one entry point.
 export { defaultTelegramRoute, telegramEnvelope };

package/dist/channels/telegram/turn-store.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
+ * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
+ * (../turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
+ * turn execution ceiling, the fail-closed attempt bump).
+ */
+import { type TurnStore } from "../turn-store.ts";
 /** An accepted turn's persisted intent — the SOURCE for the fields a runner needs to re-execute it
  *  (telegram.ts's PendingTurn derives from this, so a new execution field added here propagates and
  *  cannot silently drop from the persisted record). Minus the live `previewId` (a restart's queue
@@ -15,24 +22,4 @@ export interface StoredTurn {
     fileIds: string[];
     attempts: number;
 }
-export interface TurnStore {
-    /** Persist an accepted turn before the ACK. A failed write throws (→ webhook 500, Telegram redelivers). */
-    add(rec: StoredTurn): void;
-    /** Remove a finished turn. Post-ACK: a failed write is logged, never thrown (must not abort delivery). */
-    remove(id: string): void;
-    /** Every persisted turn a crash left behind, in ARRIVAL order, to re-enqueue on the next start. Read-
-     *  only — the ceiling is enforced per turn at `startAttempt`, so a never-run turn's budget is untouched
-     *  by a restart. Order matters: the queue rebuilds each session's FIFO chain from re-enqueue order. */
-    recover(): StoredTurn[];
-    /** Called when a turn is about to RUN (dequeued). Returns:
-     *   - "run": bumped its persisted execution count; go ahead.
-     *   - "exceeded": over `maxAttempts` starts without finishing (killed mid-run every time, whatever the
-     *     cause); the record is dropped and the runner notifies the asker.
-     *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
-     *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
-     *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
-     *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
-     *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
-    startAttempt(id: string, maxAttempts: number): "run" | "exceeded" | "defer";
-}
-export declare function createTurnStore(path: string): TurnStore;
+export declare function createTurnStore(path: string): TurnStore<StoredTurn>;

package/dist/channels/telegram/turn-store.js

@@ -1,52 +1,10 @@
 /**
- * Durable turn intent: the L1 half of durable execution (the L2 exactly-once / deterministic
- * step-replay layer is the K-axis backend — docs/design/core.md §11). Persists an accepted turn BEFORE
- * the webhook 200 (pre-ACK, like context-buffer) and removes it when the turn ENDS — the runner's
- * `finally`: a completed turn OR any caught error both remove it. Precisely, a completed turn's removal
- * fires at the `completed` event (the session is committed), which is BEFORE streamReply delivers the
- * answer to Telegram: so L1 recovers the ACKed-but-un-COMPLETED window, not un-DELIVERED. A crash in
- * that narrow tail (completed, session-committed, but the message not yet sent) leaves the answer in the
- * session history undelivered and is deliberately NOT replayed — replaying a session-committed turn
- * would double-append it; the asker re-asks (and sees the prior answer in history). L1's scope is the
- * INTERRUPTED-run window (the `finally` never runs); a caught error is NOT retried here — a `failed`
- * event already told the user, and a transport throw is dropped exactly like the pre-L1 in-memory queue
- * did (replaying it could double-send). Only an interrupted run leaves the record on disk — and
- * "interrupted" is not just a rare crash: `runStart` has no graceful drain (cli.ts), so a SIGTERM exits
- * mid-turn too, i.e. EVERY rolling deploy that catches an in-flight turn. Recovery re-enqueues it next start.
- *
- * This recovers the ACKed-but-unfinished window the in-memory turn-queue drops (turn-queue.ts). Weigh
- * the trade before trusting it: the alternative (dropping the turn) fails VISIBLY and self-corrects
- * (the turn vanished, the asker re-asks); replay's sharpest cost is the opposite — invisible. It is
- * at-least-once, not exactly-once:
- *   - PRIMARY cost: replay re-runs the WHOLE turn, so every external side effect happens AGAIN — re-sent
- *     messages, re-fired tool actions — and nobody may notice (unlike the visible loss it replaces).
- *     And the trigger is not rare (above): it fires on every deploy that interrupts an in-flight turn,
- *     not just on crashes. So "safe only if the turn's tools are idempotent" is a bar to judge against
- *     DEPLOY frequency: it holds for a Q&A bot, and is the gate for adding side-effecting tools. (A
- *     mid-stream interruption also leaves an orphan "💭 Thinking…" preview — cosmetic.)
- *   - The pre-ACK window overlaps Telegram redelivery: a crash AFTER the persist but BEFORE the 200
- *     means recovery replays the turn AND Telegram (never-ACKed) redelivers the same update — same
- *     update_id, but the queue does not dedup, so the turn can run twice. Exactly-once (a persisted
- *     delivery key) is L2.
- *
- * ponytail: at-least-once with a per-turn EXECUTION ceiling. A poison turn that deterministically
- * crashes the process would replay forever under a container restart policy. The counter is bumped at
- * `startAttempt` — when a turn is about to RUN, not per restart cycle — so it counts a turn's OWN
- * execution attempts: `recover()` re-enqueues every surviving turn without touching its count, and a
- * poison turn at a session's head is dropped on its own N+1th run WITHOUT penalizing the never-run turns
- * queued behind it (they keep their full budget and get their turn once the poison one is gone). On drop,
- * the runner notifies the asker (the chain's end must get a signal — a log line the user can't see isn't).
- * The bump is the ONE post-ACK write that fails CLOSED (not best-effort): if it can't be persisted the
- * turn is DEFERRED — skipped this cycle and left on disk to replay on the next start — rather than run
- * untracked, because an unpersisted count lets recover() re-run a poison turn every restart (the ceiling
- * would never advance on disk). It replays on the next START — a restart is required; disk recovery alone
- * does not re-run a deferred turn — and the asker is NOT told (a transient system degrade, not a user-
- * actionable failure — telling them "ask again" would double-answer on that replay).
- * Single-process, single-writer: same durability model as state.ts (crash-safe via atomic rename;
- * power-loss is best-effort — no fsync, consistent with the rest of the channel's state).
+ * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
+ * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
+ * (../turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
+ * turn execution ceiling, the fail-closed attempt bump).
  */
-import { log } from "../../log.js";
-import { loadStateFile, saveStateFile } from "./state.js";
+import { createTurnStore as createGenericTurnStore } from "../turn-store.js";
 /** State files are an IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file
  *  (warn + empty), not flow in as trusted data (mirrors context-buffer's isBufferEntry). */
 function isStoredTurn(t) {
@@ -64,87 +22,10 @@ function isStoredTurn(t) {
         typeof r.attempts === "number");
 }
 export function createTurnStore(path) {
-    const load = () => {
-        const raw = loadStateFile(path);
-        if (raw === undefined)
-            return new Map();
-        if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.values(raw).every(isStoredTurn)) {
-            return new Map(Object.entries(raw));
-        }
-        log.warn(`[telegram] unexpected shape in ${path} — starting with no pending turns`);
-        return new Map();
-    };
-    const turns = load();
-    const persist = () => saveStateFile(path, Object.fromEntries(turns));
-    // Post-ACK writes (remove, startAttempt) must not abort a turn: log a failed write, never throw.
-    const persistBestEffort = (what) => {
-        try {
-            persist();
-        }
-        catch (e) {
-            log.error(`[telegram] turn-store ${what} write failed post-ACK: ${String(e)}`);
-        }
-    };
-    return {
-        add(rec) {
-            // Idempotent on re-add: a redelivery (pre-ACK crash → never-ACKed update replayed) re-submits an id
-            // already in the store. Skip it — the intent is already durable, and overwriting would RESET this
-            // turn's execution count, handing a poison turn a fresh ceiling budget.
-            if (turns.has(rec.id))
-                return;
-            turns.set(rec.id, rec);
-            try {
-                persist(); // pre-ACK: a throw becomes the webhook's 500 and Telegram redelivers
-            }
-            catch (e) {
-                // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom
-                // entry makes the redelivery's `add` short-circuit on `turns.has` — running the turn with its
-                // intent never persisted, defeating this module — and gets flushed later by an unrelated persist.
-                turns.delete(rec.id);
-                throw e;
-            }
-        },
-        remove(id) {
-            if (turns.delete(id))
-                persistBestEffort("remove (a restart may replay an answered turn)");
-        },
-        recover() {
-            // Arrival order, so the queue rebuilds each session's FIFO chain correctly. Ids are Telegram
-            // update_ids — monotonic — so numeric id order IS arrival order; sort on it explicitly rather than
-            // lean on JS object-key enumeration happening to survive the load's JSON round-trip.
-            return [...turns.values()].sort((a, b) => Number(a.id) - Number(b.id));
-        },
-        startAttempt(id, maxAttempts) {
-            const rec = turns.get(id);
-            if (!rec)
-                return "run"; // no record — run untracked (a redelivery double-run whose first run removed it)
-            const attempts = rec.attempts + 1;
-            if (attempts > maxAttempts) {
-                // State the fact, not a cause the counter can't prove: a turn killed mid-run every time bumps
-                // this whether IT poisoned the process or a deploy/OOM took it down each time.
-                log.error(`[telegram] dropping turn ${id} after starting ${rec.attempts} time(s) without finishing ` +
-                    `(session=${rec.session}) — it may be crashing the process, or was killed mid-run each time; notifying the asker`);
-                turns.delete(id);
-                persistBestEffort("drop");
-                return "exceeded";
-            }
-            turns.set(id, { ...rec, attempts });
-            try {
-                persist();
-            }
-            catch (e) {
-                // The bump MUST be durable, unlike remove/drop: if it isn't, a restart's recover() reads the old
-                // count and RE-RUNS this turn — a poison turn would re-execute forever (the ceiling never advances
-                // on disk). Fail closed: roll the memory bump back (match disk) and DEFER — the record stays on
-                // disk with its old count and replays on the next start (a restart is required; disk recovery
-                // alone won't re-run it). Not a drop: under disk failure the removal couldn't persist anyway.
-                // The runner skips silently (no notify).
-                turns.set(id, rec);
-                log.error(`[telegram] cannot persist turn ${id}'s attempt count — deferring it to the next start rather ` +
-                    `than run it untracked (session=${rec.session}): ${String(e)}`);
-                return "defer";
-            }
-            return "run";
-        },
-    };
+    return createGenericTurnStore(path, {
+        label: "[telegram]",
+        isRecord: isStoredTurn,
+        // Ids are Telegram update_ids — monotonic — so numeric id order IS arrival order.
+        order: (a, b) => Number(a.id) - Number(b.id),
+    });
 }

package/dist/channels/{telegram/turn-queue.js → turn-queue.js}

@@ -4,13 +4,13 @@
  * is the corruption floor beneath this; this adds the group-UX queue (a second summon waits its turn
  * instead of colliding on the lease and being dropped as "busy").
  *
- * Channel-neutral (records are opaque beyond a `session` key); it lives in the telegram directory
- * because that is its only consumer today. Durability is layered ON TOP by the caller: turn-store.ts
+ * Channel-neutral (records are opaque beyond a `session` key), shared by the stateful chat channels
+ * (telegram, Feishu; Lark reuses Feishu). Durability is layered ON TOP by the caller: turn-store.ts
  * persists an accepted turn's intent pre-ACK and replays a crash-surviving one on the next start (L1,
  * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
  * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
  */
-import { log } from "../../log.js";
+import { log } from "../log.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
     // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of

package/dist/channels/turn-store.d.ts

@@ -0,0 +1,42 @@
+/** What every persisted turn record carries regardless of channel: identity, the session whose FIFO
+ *  chain it runs on, and how many times it has STARTED executing without finishing (0 until its first
+ *  run; bumped at each `startAttempt`). The channel's record type extends this with everything its
+ *  runner needs to re-execute the turn — a new execution field added there propagates into the
+ *  persisted record by construction. */
+export interface TurnRecordBase {
+    id: string;
+    session: string;
+    attempts: number;
+}
+export interface TurnStore<T extends TurnRecordBase> {
+    /** Persist an accepted turn before the ACK. A failed write throws (→ webhook 500, the platform redelivers). */
+    add(rec: T): void;
+    /** Remove a finished turn. Post-ACK: a failed write is logged, never thrown (must not abort delivery). */
+    remove(id: string): void;
+    /** Every persisted turn a crash left behind, in ARRIVAL order (the channel's `order`), to re-enqueue
+     *  on the next start. Read-only — the ceiling is enforced per turn at `startAttempt`, so a never-run
+     *  turn's budget is untouched by a restart. Order matters: the queue rebuilds each session's FIFO
+     *  chain from re-enqueue order. */
+    recover(): T[];
+    /** Called when a turn is about to RUN (dequeued). Returns:
+     *   - "run": bumped its persisted execution count; go ahead.
+     *   - "exceeded": over `maxAttempts` starts without finishing (killed mid-run every time, whatever the
+     *     cause); the record is dropped and the runner notifies the asker.
+     *   - "defer": the bump could not be persisted — skip this cycle (fail closed: an unpersisted count
+     *     would let a poison turn re-run forever); the record stays on disk and replays on the next start
+     *     (a restart is required — disk recovery alone does not re-run it). The runner does NOT notify.
+     *  An id with no record returns "run" (untracked): a completed turn's `remove` cleared it, so the
+     *  redelivery-double-run tail (see the header's pre-ACK window) lands here. */
+    startAttempt(id: string, maxAttempts: number): "run" | "exceeded" | "defer";
+}
+export interface TurnStoreOptions<T extends TurnRecordBase> {
+    /** Log prefix naming the consumer (e.g. "[telegram]") — the store itself is channel-neutral. */
+    label: string;
+    /** Shape validation at the IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt
+     *  file (warn + empty), not flow in as trusted data. */
+    isRecord: (t: unknown) => t is T;
+    /** Arrival order for {@link TurnStore.recover} — the channel knows what its ids/fields encode
+     *  (telegram: numeric update_id; lark: an explicit per-record seq). */
+    order: (a: T, b: T) => number;
+}
+export declare function createTurnStore<T extends TurnRecordBase>(path: string, opts: TurnStoreOptions<T>): TurnStore<T>;