@fastagent-sh/fastagent 0.15.0 → 0.16.0

package/dist/channels/agentcore.js

@@ -0,0 +1,260 @@
+/**
+ * AWS AgentCore Runtime adapter: serve fastagent's whole HTTP surface through the Runtime's service
+ * contract. AgentCore gives a container exactly TWO paths — `POST /invocations` (the only ingress,
+ * reached via the SigV4 `InvokeAgentRuntime` API) and `GET /ping` (health) — and no public URL, so
+ * the deployment fronts webhooks with a thin forwarder Lambda and delivers cron slots from
+ * EventBridge Scheduler; both arrive here as an ENVELOPE in the /invocations payload:
+ *
+ *  - `{ kind: "webhook", method, path, headers?, bodyB64? }` — a verbatim webhook request captured
+ *    by the forwarder. Reconstructed into a real `Request` and dispatched to the SAME channel routes
+ *    a direct deployment serves — signature verification (Telegram secret token, Feishu signatures)
+ *    runs unchanged inside the channel. The channel's HTTP response travels back INSIDE the
+ *    transport reply (`{ status, headers, bodyB64 }`, transport always 200): AgentCore folds a
+ *    container non-2xx into its own 424 RuntimeClientError, so riding the real status inside the
+ *    envelope is the only way the forwarder can re-emit it verbatim (a Feishu URL-verification
+ *    challenge needs the exact body + content-type back).
+ *  - `{ kind: "schedule-fire", name, slot }` — one cron instant from the external clock. Dispatched
+ *    to {@link fireScheduleOnce}-shaped `fire` with the slot as the idempotency key (EventBridge
+ *    delivery is at-least-once; a duplicate slot must not double-fire).
+ *  - `{ kind: "invoke", session, text }` — the programmatic data plane; streams the invoke back as
+ *    SSE (AgentCore's streaming response form), reusing the HTTP channel's handler wholesale.
+ *
+ * `/ping` reports `HealthyBusy` while process-wide background work is in flight (busy.ts) — webhook
+ * channels ACK fast and run turns fire-and-forget, and AgentCore ends an idle session, so without
+ * this signal a long turn would be killed mid-flight right after its ACK. `Healthy` when idle lets
+ * the platform reclaim the microVM (that idle-to-zero IS the point of this deployment).
+ */
+import { Buffer } from "node:buffer";
+import { timingSafeEqual } from "node:crypto";
+import { beginWork, onIdle } from "./busy.js";
+import { router } from "../host/node.js";
+import { log } from "../log.js";
+import { rememberWakeAlarmUrl } from "../schedule/wake-alarm.js";
+import { readBodyCapped } from "./body.js";
+import { createInvokeHandler } from "./http.js";
+import { text } from "./respond.js";
+import { MAX_ENVELOPE_BYTES, MAX_WEBHOOK_BODY_BYTES } from "./agentcore-limits.js";
+const unsnapshottedWarning = "[agentcore] this envelope carried no state-snapshot URLs — the state root is LOCAL ONLY and the " +
+    "platform erases it on the next deploy (redeploy with a current fastagent to restore durability)";
+const jsonHeaders = { "content-type": "application/json" };
+const json = (body, status) => new Response(`${JSON.stringify(body)}\n`, { status, headers: jsonHeaders });
+/** Compare an untrusted envelope secret without leaking a matching-prefix timing signal. */
+function secretMatches(actual, expected) {
+    if (typeof actual !== "string" || expected === undefined)
+        return false;
+    const actualBytes = Buffer.from(actual);
+    const expectedBytes = Buffer.from(expected);
+    return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+/**
+ * Build the AgentCore serving surface: `{ "POST /invocations", "GET /ping" }`. The caller merges it
+ * over its routes (collision-checked at the mount site, serve.ts) — the inner routes stay mounted
+ * too, which is harmless (AgentCore routes only /invocations and /ping into the container) and keeps
+ * a local `curl` debug surface.
+ */
+export function agentcoreRoutes(options) {
+    const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
+    const dispatch = router(routes);
+    const invokeHandler = createInvokeHandler(agent);
+    // Snapshot on the 0-in-flight edge: webhook channels ACK fast and finish the turn in the
+    // background, so "the request returned" is NOT when the state root settles.
+    if (stateSync)
+        onIdle(() => stateSync.save());
+    let warnedUnsnapshotted = false;
+    let stateReadyFired = false;
+    const handleInvocation = async (req) => {
+        const body = await readBodyCapped(req, MAX_ENVELOPE_BYTES);
+        if ("tooLarge" in body)
+            return text("envelope too large\n", 413);
+        let envelope;
+        try {
+            envelope = JSON.parse(body.text);
+        }
+        catch {
+            return text("invalid json\n", 400);
+        }
+        if (envelope === null || typeof envelope !== "object" || typeof envelope.kind !== "string") {
+            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint", ... }\n', 400);
+        }
+        // AUTHENTICATION BOUNDARY. `InvokeAgentRuntime` is an ordinary IAM action, so "reached this
+        // handler" proves nothing about the sender. Only an envelope carrying the shared secret is the
+        // forwarder's; anything else is the PUBLIC data plane, which may run exactly one kind (`invoke`)
+        // and may NOT carry internal fields — riding a `state` or `wake` URL on a public invoke would
+        // redirect the state snapshot (auth.json) or the alarm callback (the wake secret) to the caller.
+        // Internal fields are DROPPED rather than rejected: a public caller has no business knowing them.
+        const trusted = secretMatches(envelope.auth, ingressSecret);
+        if (!trusted) {
+            if (envelope.kind !== "invoke") {
+                log.warn(`[agentcore] rejected an unauthenticated "${envelope.kind}" envelope`);
+                return text("forbidden\n", 403);
+            }
+            envelope.wake = undefined;
+            envelope.state = undefined;
+        }
+        // The forwarder rides its public URL along on every envelope — persist it (write-if-changed) so
+        // the wake-alarm sink can call back. Written AFTER the restore below: a stale snapshot copy must
+        // not win over the URL this deployment is actually reachable at. A bad persist must not fail the turn.
+        const rememberUrl = () => {
+            if (typeof envelope.wake?.url !== "string")
+                return;
+            try {
+                rememberWakeAlarmUrl(stateRoot, envelope.wake.url);
+            }
+            catch (e) {
+                log.error(`[agentcore] could not persist the wake-alarm URL: ${String(e)}`);
+            }
+        };
+        // Cross-deploy state: the platform wipes /mnt/state on every version update, so the durable copy
+        // must be pulled back BEFORE anything reads it. A failed restore fails the request — serving an
+        // empty agent (and then snapshotting that emptiness over the good copy) is the worse outcome.
+        if (stateSync) {
+            if (envelope.state && typeof envelope.state.getUrl === "string" && typeof envelope.state.putUrl === "string") {
+                stateSync.use(envelope.state);
+            }
+            else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
+                // webhook/schedule-fire/wake-poke reach us ONLY through the forwarder, which always mints the
+                // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
+                // once per process (a direct `invoke` legitimately has none — its session storage is its own).
+                warnedUnsnapshotted = true;
+                log.warn(unsnapshottedWarning);
+            }
+            try {
+                await stateSync.ready();
+            }
+            catch (e) {
+                log.error(`[agentcore] state restore failed: ${String(e)}`);
+                return text(`state restore failed: ${String(e)}\n`, 503);
+            }
+        }
+        rememberUrl();
+        // The state root is authoritative only now — anything that must READ it at startup (the wake-alarm
+        // reconcile) runs here, once, rather than at boot against a mount the platform just wiped.
+        if (onStateReady && !stateReadyFired) {
+            stateReadyFired = true;
+            onStateReady();
+        }
+        switch (envelope.kind) {
+            case "webhook": {
+                const { method, path, query, headers, bodyB64 } = envelope;
+                if (typeof method !== "string" || typeof path !== "string" || !path.startsWith("/")) {
+                    return text('webhook envelope needs { "method": string, "path": "/..." }\n', 400);
+                }
+                if (typeof bodyB64 === "string" && Buffer.byteLength(bodyB64, "base64") > MAX_WEBHOOK_BODY_BYTES) {
+                    return json({
+                        status: 413,
+                        headers: { "content-type": "text/plain" },
+                        bodyB64: Buffer.from("payload too large\n").toString("base64"),
+                    }, 200);
+                }
+                const inner = new Request(`http://agentcore.local${path}${typeof query === "string" && query !== "" ? `?${query}` : ""}`, {
+                    method,
+                    headers: headers ?? {},
+                    body: typeof bodyB64 === "string" && method !== "GET" && method !== "HEAD"
+                        ? Buffer.from(bodyB64, "base64")
+                        : undefined,
+                });
+                const response = await dispatch(inner);
+                // Buffer the channel's ACK (webhook ACKs are small by design — the turn itself runs
+                // fire-and-forget) and ride it inside the transport reply, byte-exact.
+                const replyBody = Buffer.from(await response.arrayBuffer());
+                const replyHeaders = {};
+                response.headers.forEach((value, key) => {
+                    replyHeaders[key] = value;
+                });
+                const reply = {
+                    status: response.status,
+                    headers: replyHeaders,
+                    bodyB64: replyBody.toString("base64"),
+                };
+                return json(reply, 200);
+            }
+            case "schedule-fire": {
+                const { name, slot } = envelope;
+                if (typeof name !== "string" || typeof slot !== "string" || Number.isNaN(Date.parse(slot))) {
+                    return text('schedule-fire envelope needs { "name": string, "slot": ISO-date }\n', 400);
+                }
+                // No fire capability (no schedules in this definition) or an unknown name is deploy drift —
+                // an external clock rule outliving the schedule it fired for. 404 keeps it VISIBLE in the
+                // clock's logs (a 200 would silently absorb every future fire).
+                if (!fire)
+                    return text(`no schedules in this deployment (schedule-fire "${name}")\n`, 404);
+                // The whole agent turn runs inside this request — but the CALLER (the forwarder Lambda) may
+                // time out and drop the connection while the turn keeps running server-side. Count it as
+                // in-flight work so /ping holds the session (HealthyBusy) for the remainder.
+                const workDone = beginWork();
+                try {
+                    const outcome = await fire(name, new Date(slot));
+                    return json(outcome, 200);
+                }
+                catch (e) {
+                    if (e instanceof UnknownScheduleError)
+                        return text(`${e.message}\n`, 404);
+                    // A claim-state fault (unreadable/unwritable fires.json) — surface it as the request's
+                    // failure so the external clock's logs carry it (fail visibly, never a silent absorb).
+                    log.error(`[agentcore] schedule-fire ${name} failed: ${String(e)}`);
+                    return text(`schedule-fire failed: ${String(e)}\n`, 500);
+                }
+                finally {
+                    workDone();
+                }
+            }
+            case "checkpoint": {
+                // Deliberately does NOT wait for idle: the durable turn intent is persisted BEFORE the
+                // webhook ACK (turn-store.ts), so a flush right now already carries the interrupted turn —
+                // and blocking a deploy on a turn that may run for minutes would be the worse trade.
+                if (!stateSync)
+                    return json({ written: false, reason: "no state sync in this deployment" }, 200);
+                try {
+                    // The reply is the ONLY thing telling the operator whether an in-flight turn was
+                    // protected, so it reports what actually happened — `written: false` (nothing to write)
+                    // reads differently from `written: true`, and a failure is a failure.
+                    return json(await stateSync.checkpoint(), 200);
+                }
+                catch (e) {
+                    log.error(`[agentcore] checkpoint failed: ${String(e)}`);
+                    return text(`checkpoint failed: ${String(e)}\n`, 500);
+                }
+            }
+            case "wake-poke": {
+                // The poke's job is DONE by arriving: the invocation woke (or kept awake) the container, and
+                // the wake pump (boot drain + 30s poll) fires whatever is due. Nothing to dispatch.
+                return json({ ok: true }, 200);
+            }
+            case "invoke": {
+                // Reuse the HTTP channel's handler wholesale (SSE, cancellation, backpressure) by handing it
+                // the shape it already validates — one protocol, one implementation.
+                const inner = new Request("http://agentcore.local/invoke", {
+                    method: "POST",
+                    headers: jsonHeaders,
+                    body: JSON.stringify({ session: envelope.session, text: envelope.text }),
+                });
+                return invokeHandler(inner);
+            }
+            default:
+                return text(`unknown envelope kind "${envelope.kind}"\n`, 400);
+        }
+    };
+    // Settle-then-snapshot: when the envelope leaves nothing in flight, its writes are final now (a
+    // background turn instead reports through the idle edge above).
+    const invocations = async (req) => {
+        const response = await handleInvocation(req);
+        if (stateSync && !isBusy())
+            stateSync.save();
+        return response;
+    };
+    return {
+        "POST /invocations": invocations,
+        // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive
+        // (background turns in flight). No time_of_last_update — the platform tracks status changes
+        // itself, and a timestamp advancing every ping would defeat the idle timeout (their docs warn).
+        "GET /ping": () => json({ status: isBusy() ? "HealthyBusy" : "Healthy" }, 200),
+    };
+}
+/** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does
+ *  not have — the adapter maps it to 404 (deploy drift stays visible in the external clock's logs). */
+export class UnknownScheduleError extends Error {
+    constructor(name) {
+        super(`unknown schedule "${name}"`);
+        this.name = "UnknownScheduleError";
+    }
+}

package/dist/channels/busy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
+ * fire-and-forget on this process's event loop (host/node.ts) — so "is this process busy?" is not
+ * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
+ * task-tracker side tasks) report here; a serving surface that must stay alive while background
+ * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.
+ *
+ * Deliberately a counter, not a registry: consumers need only "any work in flight?"; keeping the
+ * module dependency-free lets both channel primitives import it without cycles.
+ */
+/**
+ * Mark one unit of background work as started. Returns its completion callback — idempotent, so a
+ * caller may safely settle it from multiple cleanup paths (finally + catch) without double-counting.
+ */
+export declare function beginWork(): () => void;
+/**
+ * Subscribe to the 0-in-flight edge: the moment the process finishes its last background turn.
+ * Returns an unsubscribe. Used by the AgentCore adapter to push its state snapshot exactly when the
+ * state root has settled and before the platform may reclaim the idle microVM.
+ */
+export declare function onIdle(listener: () => void): () => void;
+/** How many units of background work are currently in flight (0 = idle). */
+export declare function activeWork(): number;

package/dist/channels/busy.js

@@ -0,0 +1,53 @@
+/**
+ * SHARED process-wide in-flight work signal. Channels ACK a webhook fast and run the turn
+ * fire-and-forget on this process's event loop (host/node.ts) — so "is this process busy?" is not
+ * derivable from open HTTP requests. The two shared execution primitives (turn-queue chains,
+ * task-tracker side tasks) report here; a serving surface that must stay alive while background
+ * work runs (the AgentCore adapter's /ping → HealthyBusy) reads it.
+ *
+ * Deliberately a counter, not a registry: consumers need only "any work in flight?"; keeping the
+ * module dependency-free lets both channel primitives import it without cycles.
+ */
+let inFlight = 0;
+const idleListeners = new Set();
+/**
+ * Mark one unit of background work as started. Returns its completion callback — idempotent, so a
+ * caller may safely settle it from multiple cleanup paths (finally + catch) without double-counting.
+ */
+export function beginWork() {
+    inFlight += 1;
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        inFlight -= 1;
+        if (inFlight > 0)
+            return;
+        for (const listener of idleListeners) {
+            // A listener fault must not corrupt the counter or starve the others (this runs inside a
+            // channel's `finally`): report and carry on.
+            try {
+                listener();
+            }
+            catch (e) {
+                console.error(`[fastagent] idle listener failed: ${String(e)}`);
+            }
+        }
+    };
+}
+/**
+ * Subscribe to the 0-in-flight edge: the moment the process finishes its last background turn.
+ * Returns an unsubscribe. Used by the AgentCore adapter to push its state snapshot exactly when the
+ * state root has settled and before the platform may reclaim the idle microVM.
+ */
+export function onIdle(listener) {
+    idleListeners.add(listener);
+    return () => {
+        idleListeners.delete(listener);
+    };
+}
+/** How many units of background work are currently in flight (0 = idle). */
+export function activeWork() {
+    return inFlight;
+}

package/dist/channels/context-buffer.d.ts

@@ -1,3 +1,8 @@
+/** Per-message bound INSIDE that budget. The fold is a digest of many messages competing for one
+ *  allowance, so the job here is fairness, not fidelity: one rambler must not price out everyone who
+ *  spoke after them. 280 against 4000 keeps at least ~14 messages in a full buffer. A referent — the
+ *  single message the asker points at — is the opposite job and takes REFERENT_MAX_CODE_POINTS. */
+export declare const BUFFER_LINE_MAX_CHARS = 280;
 /** How many buffered files and images (each, most recent first) a summon pulls in with the folded
  *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
  *  group posting many attachments between summons. Skipped ones must be counted into the prompt

package/dist/channels/context-buffer.js

@@ -28,6 +28,11 @@ import { loadStateFile, saveStateFile } from "./state.js";
  *  sparse-but-relevant lines, a busy burst is capped). The `line` renderer is the eviction cost
  *  basis: the budget must price what the fold actually renders, or it would systematically overrun. */
 const BUFFER_MAX_CHARS = 4000;
+/** Per-message bound INSIDE that budget. The fold is a digest of many messages competing for one
+ *  allowance, so the job here is fairness, not fidelity: one rambler must not price out everyone who
+ *  spoke after them. 280 against 4000 keeps at least ~14 messages in a full buffer. A referent — the
+ *  single message the asker points at — is the opposite job and takes REFERENT_MAX_CODE_POINTS. */
+export const BUFFER_LINE_MAX_CHARS = 280;
 /** How many buffered files and images (each, most recent first) a summon pulls in with the folded
  *  discussion — bounds the latency/token cost of "summarize the file from earlier" against a chatty
  *  group posting many attachments between summons. Skipped ones must be counted into the prompt

package/dist/channels/feishu/context-buffer.d.ts

@@ -1,9 +1,3 @@
-/**
- * Feishu/Lark's half of the shared context buffer (mechanics + consume protocol:
- * ../context-buffer.ts): the entry shape, its fold-line rendering, place-key derivation, and
- * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
- * concrete thread root) and folded into the next answered turn in that place.
- */
 import { type ContextBuffer } from "../context-buffer.ts";
 import type { NormalizedFeishuMessage } from "./model.ts";
 export interface FeishuBufferedResource {
@@ -23,8 +17,19 @@ export interface FeishuBufferEntry {
 export interface FeishuBufferedRef extends FeishuBufferedResource {
     from: string;
 }
-/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
-export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "rootId" | "threadId">): string;
+/**
+ * The place a message belongs to: the main chat, or a thread within it. Keyed by `thread_id`, the
+ * platform's own identity for a side conversation — NOT `root_id`, which tracks the reply chain and
+ * can differ between messages of one thread (which would split a thread's context across buckets).
+ * A quoted reply outside a thread carries a root but is main-chat discussion, so it buckets there.
+ *
+ * Its own namespace, deliberately: this names a BUCKET of undelivered text, while `parse.ts`'s
+ * `placeKey` names a SESSION. Nothing here claims anything about that session — unlike thread
+ * participation, which asserts "the agent answered into this memory" and is therefore keyed by the
+ * session itself. Re-keying either one leaves the other correct, and converging them now would strand
+ * live buckets for no gain (Slack keeps its own shape for the same reason).
+ */
+export declare function feishuBufferPlaceKey(conversation: Pick<NormalizedFeishuMessage["conversation"], "chatId" | "threadId">): string;
 /** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
 export declare function feishuBufferText(text: string): string;
 /**

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

@@ -4,21 +4,34 @@
  * buffered-resource selection. Entries are bucketed by conversation place (main chat, or one
  * concrete thread root) and folded into the next answered turn in that place.
  */
-import { BUFFER_ATTACH_MAX, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
+import { log } from "../../log.js";
+import { BUFFER_ATTACH_MAX, BUFFER_LINE_MAX_CHARS, createContextBuffer as createGenericContextBuffer, } from "../context-buffer.js";
+import { loadStateFile, saveStateFile } from "../state.js";
+import { truncateCodePointPrefix } from "../text.js";
 function bufferLine(entry) {
     const meta = [`msg ${entry.messageId}`, entry.replyTo ? `reply to msg ${entry.replyTo}` : undefined]
         .filter(Boolean)
         .join(", ");
     return `${entry.sender} (${meta}): ${entry.body}`;
 }
-/** Main-chat discussion stays in the chat bucket; a topic uses its stable root id (thread id fallback). */
+/**
+ * The place a message belongs to: the main chat, or a thread within it. Keyed by `thread_id`, the
+ * platform's own identity for a side conversation — NOT `root_id`, which tracks the reply chain and
+ * can differ between messages of one thread (which would split a thread's context across buckets).
+ * A quoted reply outside a thread carries a root but is main-chat discussion, so it buckets there.
+ *
+ * Its own namespace, deliberately: this names a BUCKET of undelivered text, while `parse.ts`'s
+ * `placeKey` names a SESSION. Nothing here claims anything about that session — unlike thread
+ * participation, which asserts "the agent answered into this memory" and is therefore keyed by the
+ * session itself. Re-keying either one leaves the other correct, and converging them now would strand
+ * live buckets for no gain (Slack keeps its own shape for the same reason).
+ */
 export function feishuBufferPlaceKey(conversation) {
-    const topic = conversation.rootId ?? conversation.threadId;
-    return topic ? `${conversation.chatId}:root:${topic}` : conversation.chatId;
+    return conversation.threadId ? `${conversation.chatId}:thread:${conversation.threadId}` : conversation.chatId;
 }
 /** One-line, bounded background text. Resource-only messages already carry a visible decoder marker. */
 export function feishuBufferText(text) {
-    return text.replace(/\s+/g, " ").trim().slice(0, 280);
+    return truncateCodePointPrefix(text.replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
 }
 function resourceIdentity(resource) {
     return `${resource.messageId}\u0000${resource.key}`;
@@ -67,6 +80,47 @@ function isEntry(value) {
         resources(entry.files) &&
         resources(entry.images));
 }
+/**
+ * Buckets from the pre-participant-model keying (`<chat>:root:<root_id>`) can never be produced again —
+ * a place is `<chat>` or `<chat>:thread:<thread_id>` — so nothing could ever fold or clear them, and
+ * they would hold chat content on disk forever. Dropped here, before the buffer loads, so the shared
+ * kernel never learns about a key shape one channel retired.
+ *
+ * TWO one-time losses, both accepted and both logged by count. (1) The retired shape covered every
+ * thread bucket and every main-chat quoted-reply bucket, so buffered discussion in threads does not
+ * survive the upgrade — it becomes unreachable BECAUSE of the re-keying, not before it. (2)
+ * `turns.json` persists each in-flight turn's `bufferKey` verbatim and this runs before turn recovery,
+ * so a turn spanning the upgrade finds its bucket already gone. Sparing referenced keys would couple
+ * the buffer to the turn store to protect a single upgrade, and would not help (1) at all.
+ *
+ * PERMANENT, unlike the `owned-threads.json` cleanup it otherwise resembles. That one leaves an inert
+ * orphan file, so deleting it a release later is free; this one is what stops user chat content
+ * lingering, and a deployment that skips from before the model to well after it would never run an
+ * expired version of this code. The standing cost is one key scan at load, and nothing when no retired
+ * key is present.
+ */
+function dropRetiredBuckets(path, label) {
+    const raw = loadStateFile(path);
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return;
+    const live = Object.entries(raw).filter(([placeKey]) => !placeKey.includes(":root:"));
+    const dropped = Object.keys(raw).length - live.length;
+    if (dropped === 0)
+        return;
+    log.info(`${label} dropped ${dropped} context bucket(s) with a retired key shape`);
+    try {
+        saveStateFile(path, Object.fromEntries(live));
+    }
+    catch (error) {
+        log.warn(`${label} could not rewrite ${path} after dropping retired buckets: ${String(error)}`);
+    }
+}
 export function createFeishuContextBuffer(path, label) {
-    return createGenericContextBuffer({ path, label, isEntry, line: bufferLine });
+    dropRetiredBuckets(path, label);
+    return createGenericContextBuffer({
+        path,
+        label,
+        isEntry,
+        line: bufferLine,
+    });
 }

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

@@ -236,7 +236,10 @@ export function createFeishuApi(opts) {
             await call("deleteMessage", "DELETE", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`);
         },
         async getMessage(messageId) {
-            const data = await call("getMessage", "GET", `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`);
+            const data = await call("getMessage", "GET", 
+            // Pin the id type: callers match mentions/sender against open_ids, so the response's id shape
+            // must not depend on the platform's default staying open_id.
+            `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}?user_id_type=open_id`);
             return data.data?.items?.[0];
         },
         async downloadResource(messageId, fileKey, type) {

package/dist/channels/feishu/feishu.d.ts

@@ -10,16 +10,6 @@ interface FeishuChannelBaseOptions {
     appId: string;
     /** App Secret (same page) — drives both ingress authentication and outbound API calls. */
     appSecret: string;
-    /** Direct-message context + delivery policy. `threaded` (default) gives every top-level p2p message
-     * its own session, creates a platform thread for the answer, and routes later thread messages back
-     * by root message id. `continuous` keeps one session per p2p chat and sends ordinary unquoted replies. */
-    directMessageSession?: "continuous" | "threaded";
-    /** Group-message context + delivery policy. `threaded` (default) gives every top-level summoned
-     * message its own session and platform thread; later bare user messages in that managed thread answer
-     * in the same root session, while @other-only discussion buffers. `continuous` preserves the legacy
-     * chat/topic sessions (`chat_id` / `chat_id:thread_id`). Buffering and bare continuations require
-     * `im:message.group_msg`. */
-    groupMessageSession?: "continuous" | "threaded";
     /** Policy: whether/where to answer an event (return null to ignore). Defaults to {@link defaultFeishuRoute}. */
     route?: (event: FeishuMessageEvent) => FeishuRoute | null;
     /** Customer-facing failure text for the chat (the dev-facing full `details` always go to the operator
@@ -30,8 +20,6 @@ interface FeishuChannelBaseOptions {
      *  `https://open.feishu.cn`; Lark factories default to `https://open.larksuite.com`. Named to match
      *  the other channels (telegram/slack). */
     apiBaseUrl?: string;
-    /** @deprecated Alias of {@link apiBaseUrl}; kept for existing feishu/lark channel files. */
-    baseUrl?: string;
     /** How long (ms) a turn waits before its reply-quoted "⏳ Queued" card mounts. Defaults to 0
      *  (immediate); the same card is later taken over by the live preview/final answer. */
     queueNoticeDelayMs?: number;