@fastagent-sh/fastagent 0.12.1 → 0.14.0

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>;

package/dist/channels/turn-store.js

@@ -0,0 +1,139 @@
+/**
+ * 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 the telegram 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 the reply reaches
+ * the chat platform: 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 webhook redelivery: a crash AFTER the persist but BEFORE the 200
+ *     means recovery replays the turn AND the platform (never-ACKed) redelivers the same event — same
+ *     id, and unless the channel dedups accepted ids, the turn can run twice. Exactly-once (a persisted
+ *     delivery key) is L2.
+ *
+ * Channel-neutral, generic over the record shape: the channel supplies its own record type (everything
+ * its runner needs to re-execute the turn), the shape validator (state files are an IO boundary), the
+ * arrival ordering for recovery, and its log label. telegram/turn-store.ts and the Feishu channel are the
+ * two consumers.
+ *
+ * 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).
+ */
+import { log } from "../log.js";
+import { loadStateFile, saveStateFile } from "./state.js";
+export function createTurnStore(path, opts) {
+    const { label, isRecord, order } = opts;
+    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(isRecord)) {
+            return new Map(Object.entries(raw));
+        }
+        log.warn(`${label} 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(`${label} turn-store ${what} write failed post-ACK: ${String(e)}`);
+        }
+    };
+    return {
+        add(rec) {
+            // Idempotent on re-add: a redelivery (pre-ACK crash → never-ACKed event 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 the platform 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() {
+            // The channel's arrival order, applied explicitly rather than leaning on JS object-key enumeration
+            // happening to survive the load's JSON round-trip.
+            return [...turns.values()].sort(order);
+        },
+        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(`${label} 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(`${label} 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";
+        },
+    };
+}

package/dist/channels/wait-health.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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.
+ */
+export declare function waitForHealth(healthUrl: string, timeoutMs: number, intervalMs: number): Promise<boolean>;

package/dist/channels/wait-health.js

@@ -0,0 +1,27 @@
+/**
+ * Readiness probe shared by the webhook registrars (telegram setWebhook, lark config PATCH): both
+ * platforms VERIFY the URL at registration time, and a fresh deploy's container or a fresh tunnel's
+ * DNS is not routable for some seconds — registering before the server actually serves would fail.
+ * Tracking real readiness (not a fixed timer) is what fixes that race.
+ */
+import { setTimeout as sleep } from "node:timers/promises";
+/**
+ * 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.
+ */
+export 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);
+    }
+}

package/dist/cli/commands/add.d.ts

@@ -0,0 +1,9 @@
+import { type ChannelKind } from "../../scaffold/add-channel.ts";
+/** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
+export declare function runAddChannel(channelKind: ChannelKind, dirArg: string, opts: {
+    createApp?: boolean;
+}): Promise<void>;
+/** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
+export declare function runAddSkill(source: string | undefined, dirArg: string, opts: {
+    update?: boolean;
+}): Promise<void>;