@fastagent-sh/fastagent 0.16.2 → 0.17.1

package/dist/channels/agentcore.d.ts

@@ -54,6 +54,15 @@ export type AgentcoreEnvelope = {
  *  "channels with replay re-run it" true rather than aspirational. */
  | {
     kind: "checkpoint";
+}
+/** The deploy driver's post-deploy verification (relayed by the forwarder's reserved
+ *  `/__fastagent/probe` path, which answers on EVERY forwarder topology — schedule-only URLs
+ *  refuse ordinary public traffic). Runs restore + channel construction end to end and answers a
+ *  TRANSPORT-200 structured verdict `{ ok, error? }`: the ordinary webhook path folds a non-200
+ *  transport into an opaque 502 at the forwarder, which would strip exactly the diagnostics this
+ *  probe exists to carry. */
+ | {
+    kind: "probe";
 });
 /** The webhook envelope's reply: the channel's real HTTP response, ridden inside a transport-200
  *  body so the forwarder can re-emit it verbatim (see the module header on AgentCore's 424 folding). */
@@ -63,8 +72,13 @@ export interface WebhookReply {
     bodyB64: string;
 }
 export interface AgentcoreAdapterOptions {
-    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health). */
-    routes: Routes;
+    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health).
+     *  The serving path passes a LAZY factory: channel construction loads channel state and replays
+     *  durable turn intent, so on AgentCore it must not run until the state root is authoritative —
+     *  which happens at the first envelope's `stateSync.ready()` (the restore URLs only an envelope
+     *  carries), never at boot, where the mount is pre-restore (empty after every version update).
+     *  An eager `Routes` value remains supported for wirings whose state root is already durable. */
+    routes: Routes | (() => Promise<Routes> | Routes);
     agent: Agent;
     /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
     stateRoot: string;

package/dist/channels/agentcore.js

@@ -19,7 +19,8 @@
  *  - `{ 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
+ * `/ping` reports `HealthyBusy` (+ `time_of_last_update`, required — see the handler) 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).
@@ -54,7 +55,28 @@ function secretMatches(actual, expected) {
  */
 export function agentcoreRoutes(options) {
     const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
-    const dispatch = router(routes);
+    // Lazy channel construction (see AgentcoreAdapterOptions.routes) — resolved ONCE per process, on
+    // the first trusted envelope after the state root is authoritative, and the outcome is cached
+    // EITHER WAY. Success: the same resident channels a direct host keeps. Failure too: construction
+    // is an ACTIVATION with side effects — loadChannels builds every healthy channel (starting its
+    // queues and replaying durable turn intent) before reporting another module's failure — and there
+    // is no cleanup contract to unwind it, so re-running it per envelope could replay the same
+    // recovered turn concurrently. The first rejection is therefore the process's answer: every later
+    // envelope fails with the same message (visible each time), the retry boundary is a fresh session
+    // (which scale-to-zero provides naturally), and the deploy driver's probe catches deterministic
+    // failures at deploy time.
+    let dispatchP;
+    const resolveDispatch = () => {
+        if (!dispatchP) {
+            // The factory runs INSIDE the chain: a synchronous throw must land in the cached rejection,
+            // not escape before `dispatchP` is assigned (which would silently re-run the activation).
+            dispatchP = Promise.resolve()
+                .then(() => (typeof routes === "function" ? routes() : routes))
+                .then(router);
+            dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
+        }
+        return dispatchP;
+    };
     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.
@@ -74,7 +96,7 @@ export function agentcoreRoutes(options) {
             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);
+            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint" | "probe", ... }\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
@@ -112,7 +134,7 @@ export function agentcoreRoutes(options) {
                 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
+                // webhook/schedule-fire/wake-poke/probe reach us ONLY through the forwarder, which 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;
@@ -123,6 +145,11 @@ export function agentcoreRoutes(options) {
             }
             catch (e) {
                 log.error(`[agentcore] state restore failed: ${String(e)}`);
+                // The probe is the deploy driver's verification channel: its diagnostics must survive the
+                // forwarder, which folds a non-200 transport into an opaque 502 — so for it the failure
+                // rides a transport-200 structured verdict; every other kind keeps the plain 503.
+                if (envelope.kind === "probe")
+                    return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
                 return text(`state restore failed: ${String(e)}\n`, 503);
             }
         }
@@ -133,6 +160,26 @@ export function agentcoreRoutes(options) {
             stateReadyFired = true;
             onStateReady();
         }
+        // PROCESS INITIALIZATION, kind-independent: the (lazy) channels are constructed on the first
+        // trusted ingress after the state root became authoritative — whichever kind carries it, so a
+        // cold start woken by a schedule fire or an alarm poke still replays checkpointed turn intent.
+        // Two deliberate exceptions: `checkpoint` must push state even when a channel is broken, and a
+        // public `invoke` runs in its own isolated storage — constructing against THAT root would cache
+        // pre-restore emptiness for the ingress session. Failure policy is per kind below: webhook and
+        // wake-poke fail their request (503), the probe reports it structurally, and a schedule fire
+        // proceeds — cron does not consume channels, and letting an unrelated channel misconfiguration
+        // silence the clock would turn one fault into two (the error is logged here either way).
+        let constructionError;
+        let dispatch;
+        if (trusted && envelope.kind !== "checkpoint" && envelope.kind !== "invoke") {
+            try {
+                dispatch = await resolveDispatch();
+            }
+            catch (e) {
+                constructionError = String(e);
+                log.error(`[agentcore] channel construction failed: ${constructionError}`);
+            }
+        }
         switch (envelope.kind) {
             case "webhook": {
                 const { method, path, query, headers, bodyB64 } = envelope;
@@ -153,6 +200,10 @@ export function agentcoreRoutes(options) {
                         ? Buffer.from(bodyB64, "base64")
                         : undefined,
                 });
+                // A construction failure is the request's failure (503 through the forwarder, so the
+                // platform retries and the operator sees the message), never a silently-empty channel.
+                if (!dispatch)
+                    return text(`channel construction failed: ${constructionError ?? "unavailable"}\n`, 503);
                 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.
@@ -217,9 +268,21 @@ export function agentcoreRoutes(options) {
             }
             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.
+                // the wake pump (boot drain + 30s poll) fires whatever is due. Nothing to dispatch — the
+                // initialization above already resolved construction (replaying checkpointed turn intent),
+                // and its failure is this request's failure so the alarm's log line names it.
+                if (constructionError !== undefined)
+                    return text(`channel construction failed: ${constructionError}\n`, 503);
                 return json({ ok: true }, 200);
             }
+            case "probe": {
+                // The structured verdict (transport-200 — see the envelope doc): the deploy driver reads it
+                // through the forwarder's reserved path, so the error text survives the hop that turns any
+                // non-200 transport into an opaque 502.
+                return json(constructionError === undefined
+                    ? { ok: true }
+                    : { ok: false, error: `channel construction failed: ${constructionError}` }, 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.
@@ -242,12 +305,30 @@ export function agentcoreRoutes(options) {
             stateSync.save();
         return response;
     };
+    // The Runtime ping contract: Healthy = reclaimable, HealthyBusy = keep the session alive
+    // (background turns in flight). `time_of_last_update` is REQUIRED for the keep-alive to work,
+    // despite the contract documenting it as optional ("If you omit the field, the platform tracks
+    // status changes on its own"): measured on a live Runtime (us-east-1, 2026-08-04), the platform's
+    // idle measurement reads ONLY this field — with it omitted, a session polling every ~2s and
+    // receiving HealthyBusy 200s was still reclaimed at exactly IdleRuntimeSessionTimeout after the
+    // last InvokeAgentRuntime, mid-turn, 2s after the last HealthyBusy answer; with the field present
+    // the same turn survived 3.5× the idle timeout with zero invocations and completed. The value
+    // updates ONLY on a real status change: a timestamp advancing on every ping declares a perpetual
+    // status change, so the idle timeout never fires and dead-idle sessions live to MaxLifetime
+    // (quota exhaustion — the failure mode the contract's warning describes).
+    let lastStatus = "Healthy";
+    let lastTransition = Math.floor(Date.now() / 1000);
     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),
+        "GET /ping": () => {
+            const status = isBusy() ? "HealthyBusy" : "Healthy";
+            if (status !== lastStatus) {
+                lastTransition = Math.floor(Date.now() / 1000);
+                log.debug(`[agentcore] ping status: ${lastStatus} → ${status}`);
+                lastStatus = status;
+            }
+            return json({ status, time_of_last_update: lastTransition }, 200);
+        },
     };
 }
 /** Thrown by the mount-site `fire` binding when the envelope names a schedule this workspace does

package/dist/channels/control.d.ts

@@ -22,7 +22,7 @@ export interface ControlRoutesOptions {
     agent?: Agent;
 }
 /**
- * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
  * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
  */
 export declare function controlRoutes(control: SessionControl, options: ControlRoutesOptions): Routes;

package/dist/channels/control.js

@@ -84,7 +84,7 @@ function parseWireCommand(raw) {
     }
 }
 /**
- * Mount the control plane: `GET /control/capabilities|state|entries|events` + `POST
+ * Mount the control plane: `GET /control/capabilities|commands|state|entries|events` + `POST
  * /control/dispatch`, all bearer-authenticated. `events` streams SSE (`data: <WireEvent>` lines).
  */
 export function controlRoutes(control, options) {
@@ -111,6 +111,7 @@ export function controlRoutes(control, options) {
     return {
         ...(invokeHandler ? { "POST /control/invoke": guard((req) => invokeHandler(req)) } : {}),
         "GET /control/capabilities": guard(() => json(control.capabilities())),
+        "GET /control/commands": guard(async () => json(await control.commands())),
         "GET /control/state": guard(async (_req, url) => {
             const session = sessionParam(url);
             if (!session)

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

@@ -3,16 +3,24 @@
  * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
  * the card DSL is data-in → string-out and testable without the pump.
  *
- * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
- * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
- * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
- * element, `streaming_mode` off — one write flips content and mode together.
+ * The streaming card is TWO markdown elements: `process` (the volatile block — thinking tail, tool
+ * lines, retry notice) and `answer` (append-only). The pump PUTs full-text snapshots per element
+ * (feishu-api.ts `updateCardElement`) and the client renders the typewriter effect. The split is the
+ * prefix-stability rule made structural: the client animates an element's update only when the old
+ * text is a PREFIX of the new — otherwise it re-types everything after the first divergent character.
+ * The process block's head changes every frame (a sliding thinking tail, `…`→`✓` status flips), so
+ * sharing one element with the answer re-typed the whole card once a second; two elements confine the
+ * churn to the small process block and keep the answer's typewriter smooth. Settling replaces the
+ * whole entity (`updateCard`) with the answer element alone, `streaming_mode` off — one write flips
+ * content and mode together and drops the process block.
  *
  * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
  * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
  */
-/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+/** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export declare const ANSWER_ELEMENT_ID = "answer";
+/** The volatile process element's id (thinking tail + tool lines + retry notice; live-only). */
+export declare const PROCESS_ELEMENT_ID = "process";
 /** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
 export declare const CARD_MARKDOWN_MAX_BYTES: number;
 /**
@@ -23,10 +31,13 @@ export declare const CARD_MARKDOWN_MAX_BYTES: number;
  * emphasis/heading/list markers removed.
  */
 export declare function cardSummary(markdown: string): string;
-/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
-export declare function streamingCardJson(initial: string): string;
-/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
- *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+/** The live-preview card entity: streaming on, the process element seeded with the placeholder/queue
+ *  status and the answer element seeded EMPTY (the platform accepts an empty markdown element; it
+ *  renders zero-height until the first answer snapshot lands as a clean prefix extension of ""). */
+export declare function streamingCardJson(initialProcess: string): string;
+/** The settled card: final markdown alone (the process block was preview-only), streaming off (stops
+ *  the client's streaming affordance), plus the answer-derived summary so the chat list / notification
+ *  shows the reply, not "[Card]". */
 export declare function finalCardJson(markdown: string): string;
 /** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
 export declare function cardEntityContent(cardId: string): string;

package/dist/channels/feishu/card.js

@@ -3,17 +3,25 @@
  * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
  * the card DSL is data-in → string-out and testable without the pump.
  *
- * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
- * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
- * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
- * element, `streaming_mode` off — one write flips content and mode together.
+ * The streaming card is TWO markdown elements: `process` (the volatile block — thinking tail, tool
+ * lines, retry notice) and `answer` (append-only). The pump PUTs full-text snapshots per element
+ * (feishu-api.ts `updateCardElement`) and the client renders the typewriter effect. The split is the
+ * prefix-stability rule made structural: the client animates an element's update only when the old
+ * text is a PREFIX of the new — otherwise it re-types everything after the first divergent character.
+ * The process block's head changes every frame (a sliding thinking tail, `…`→`✓` status flips), so
+ * sharing one element with the answer re-typed the whole card once a second; two elements confine the
+ * churn to the small process block and keep the answer's typewriter smooth. Settling replaces the
+ * whole entity (`updateCard`) with the answer element alone, `streaming_mode` off — one write flips
+ * content and mode together and drops the process block.
  *
  * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
  * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
  */
 import { truncateCodePointPrefix } from "../text.js";
-/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+/** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export const ANSWER_ELEMENT_ID = "answer";
+/** The volatile process element's id (thinking tail + tool lines + retry notice; live-only). */
+export const PROCESS_ELEMENT_ID = "process";
 /** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
 export const CARD_MARKDOWN_MAX_BYTES = 20 * 1024;
 /** Character budget for the settled card's summary (the chat-list / push-notification preview). */
@@ -38,7 +46,7 @@ export function cardSummary(markdown) {
         .find((l) => l !== "") ?? "";
     return truncateCodePointPrefix(line, SUMMARY_MAX_CHARS);
 }
-function cardJson(markdown, streaming, summary) {
+function cardJson(elements, streaming, summary) {
     return JSON.stringify({
         schema: "2.0",
         config: {
@@ -48,17 +56,23 @@ function cardJson(markdown, streaming, summary) {
             // "[Generating…]") is better than any fixed text we could pin.
             ...(summary ? { summary: { content: summary } } : {}),
         },
-        body: { elements: [{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }] },
+        body: { elements },
     });
 }
-/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
-export function streamingCardJson(initial) {
-    return cardJson(initial, true);
+/** The live-preview card entity: streaming on, the process element seeded with the placeholder/queue
+ *  status and the answer element seeded EMPTY (the platform accepts an empty markdown element; it
+ *  renders zero-height until the first answer snapshot lands as a clean prefix extension of ""). */
+export function streamingCardJson(initialProcess) {
+    return cardJson([
+        { tag: "markdown", content: initialProcess, element_id: PROCESS_ELEMENT_ID },
+        { tag: "markdown", content: "", element_id: ANSWER_ELEMENT_ID },
+    ], true);
 }
-/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
- *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+/** The settled card: final markdown alone (the process block was preview-only), streaming off (stops
+ *  the client's streaming affordance), plus the answer-derived summary so the chat list / notification
+ *  shows the reply, not "[Card]". */
 export function finalCardJson(markdown) {
-    return cardJson(markdown, false, cardSummary(markdown));
+    return cardJson([{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }], false, cardSummary(markdown));
 }
 /** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
 export function cardEntityContent(cardId) {

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

@@ -65,7 +65,12 @@ export interface FeishuApi {
     editTextMessage(messageId: string, text: string): Promise<void>;
     /** Recall (delete) a message the bot sent. */
     deleteMessage(messageId: string): Promise<void>;
-    /** Fetch one message (the reply-referent path). Undefined when the API returns no item. */
+    /** Fetch one message (the reply-referent path). Undefined when the API returns no item.
+     *
+     *  `sender` is typed rather than `unknown` because the referent path READS it: an app-sent message
+     *  whose id is THIS app's is the agent's own, which the prompt must say instead of attributing it to
+     *  "user cli_…". The message object carries more (`parent_id`, `root_id`, `thread_id`); they stay
+     *  unnamed until something reads them — this type is the surface in use, not a mirror of the wire. */
     getMessage(messageId: string): Promise<{
         message_id?: string;
         msg_type?: string;
@@ -73,7 +78,11 @@ export interface FeishuApi {
             content?: string;
         };
         mentions?: unknown[];
-        sender?: unknown;
+        sender?: {
+            id?: string;
+            id_type?: string;
+            sender_type?: string;
+        };
     } | undefined>;
     /** Download a message resource (image/file bytes). Caps at {@link MAX_DOWNLOAD_BYTES}. */
     downloadResource(messageId: string, fileKey: string, type: "image" | "file"): Promise<{

package/dist/channels/feishu/feishu.js

@@ -14,7 +14,7 @@ import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { createSeenRing } from "../seen.js";
 import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome, removeRetiredStateFile } from "../state.js";
+import { ensureStateHome, loadStateFile, removeRetiredStateFile, saveStateFile } from "../state.js";
 import { dispatchStop, isStopText } from "../stop-command.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "../turn-store.js";
@@ -93,16 +93,45 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         }
         const formatError = onError ?? defaultErrorMessage;
         const api = createFeishuApi({ kind, baseUrl, appId, appSecret });
-        // One bot/v3/info at startup: the bot's open_id drives the default route's group @mention summon.
-        // Until it resolves (or if it fails), group summon stays off — fail-closed — while p2p works. A
-        // mention landing in that first moment is buffered as context rather than answered; it is folded
-        // into the next answered turn in that place, so the ask is delayed, never lost.
+        // One bot/v3/info per process refreshes the bot's own open_id — the identity the default route
+        // matches group @mentions against. The CACHED copy (bot.json, seeded synchronously once the state
+        // home exists below) is what makes the first envelope safe: this fetch is fire-and-forget, and
+        // under the AgentCore posture channel construction happens INSIDE the first envelope
+        // (channels/agentcore.ts lazy construction), so a network round trip can never beat that same
+        // envelope's own dispatch — without the seed, every cold start's FIRST group mention raced this
+        // fetch and lost (field-observed: an explicit @ buffered as bystander context). The open_id is a
+        // stable property of the app, so disk beats network; the only envelope a deployment ever serves
+        // without the file is its first one, which is the deploy driver's probe — it carries no mention.
+        // No identity at all (fresh dir, no cache, fetch pending/failed) keeps today's fail-closed
+        // behavior: unmatched mentions buffer as context — delayed, never lost.
         let botOpenId;
+        let persistBotIdentity = () => { }; // bound once the state home exists
+        let invalidateBotIdentity = () => { }; // likewise
         void api.botInfo().then((me) => {
-            botOpenId = me.openId;
-            if (!botOpenId)
-                log.warn(`${label} bot/v3/info returned no open_id — group @mention summon stays off`);
-        }, (e) => log.warn(`${label} bot/v3/info failed; group @mention summon stays off until restart: ${String(e)}`));
+            if (me.openId) {
+                if (botOpenId !== undefined && botOpenId !== me.openId) {
+                    log.info(`${label} bot open_id changed (${botOpenId} → ${me.openId}) — updating the cached identity`);
+                }
+                botOpenId = me.openId;
+                persistBotIdentity(me.openId);
+            }
+            else {
+                // The call SUCCEEDED and the platform reported no identity — an affirmative "there is no
+                // bot here" (capability off, app reconfigured), not transport weather. This is the one
+                // answer that must also INVALIDATE the cache: keeping a summon identity the platform just
+                // declined to confirm would quietly turn fail-closed into fail-open.
+                log.warn(botOpenId === undefined
+                    ? `${label} bot/v3/info returned no open_id — group @mention summon stays off`
+                    : `${label} bot/v3/info returned no open_id — cached identity cleared; group @mention summon stays off`);
+                botOpenId = undefined;
+                invalidateBotIdentity();
+            }
+        }, (e) => 
+        // A FAILED call is transport weather (network, rate limit): the platform said nothing about
+        // the identity, so a cached one keeps serving — the degradation this cache exists for.
+        log.warn(botOpenId === undefined
+            ? `${label} bot/v3/info failed; group @mention summon stays off until restart: ${String(e)}`
+            : `${label} bot/v3/info failed; running on the cached identity (bot.json): ${String(e)}`));
         void api.listAppScopes().then((scopes) => {
             const grantedScope = (name) => scopes.some((scope) => scope.name === name && scope.grantStatus === 1 && (scope.type === undefined || scope.type === "tenant"));
             if (grantedScope(FEISHU_GROUP_CONTEXT_SCOPE)) {
@@ -135,6 +164,51 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         // after the release following the participant model ships — by then no live deployment can still
         // be carrying the file. test/migration-deadline.test.ts fails when due.
         removeRetiredStateFile(stateHome, "owned-threads.json", label);
+        // The cached bot identity (rationale at the botInfo block above): seed synchronously — the
+        // factory runs to completion before any promise resolves, so botOpenId is still unset here and
+        // the seed is what the first envelope's dispatch sees. Refresh keeps the file current.
+        //
+        // BOUND TO THE APP: the state home is per channel KIND, and an operator can point kept state at
+        // a different app (a recreated app, a tenant migration). A cached identity from another app
+        // would make THIS bot treat mentions of the OLD bot as its own summons — identity impersonation,
+        // strictly worse than the race the cache removes — so the cache counts only when it names the
+        // current appId. A mismatch is not noise worth warning about: the next persist IS the migration.
+        const botFile = join(stateHome, "bot.json");
+        const storedBot = loadStateFile(botFile);
+        let cachedOpenId;
+        if (storedBot !== undefined) {
+            if (typeof storedBot.appId !== "string") {
+                log.warn(`${label} unexpected shape in ${botFile} — ignoring the cached bot identity`);
+            }
+            else if (storedBot.appId === appId && typeof storedBot.openId === "string") {
+                cachedOpenId = storedBot.openId;
+            }
+        }
+        botOpenId ??= cachedOpenId;
+        persistBotIdentity = (openId) => {
+            if (openId === cachedOpenId)
+                return;
+            cachedOpenId = openId;
+            try {
+                saveStateFile(botFile, { appId, openId });
+            }
+            catch (e) {
+                log.warn(`${label} could not persist the bot identity to ${botFile} — the next cold start races bot/v3/info again: ${String(e)}`);
+            }
+        };
+        invalidateBotIdentity = () => {
+            if (cachedOpenId === undefined)
+                return;
+            cachedOpenId = undefined;
+            try {
+                // `{ appId }` with no openId reads as "no cache" at the loader — the atomic write is reused
+                // instead of introducing a deletion path.
+                saveStateFile(botFile, { appId });
+            }
+            catch (e) {
+                log.warn(`${label} could not clear the cached bot identity ${botFile}: ${String(e)}`);
+            }
+        };
         const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
         /** This channel's place key for a thread (the shared store is key-agnostic). */
         // The SAME identity the session uses (`placeKey`) — a thread's place. Defining it twice would let a
@@ -241,7 +315,7 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                     files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
                 });
                 try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
+                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label, appId }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
                         // Drop intent first: a crash between these writes may re-fold answered context later,
                         // but can never replay this turn after its context was removed.
                         store.remove(rec.id);

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

@@ -21,6 +21,10 @@ export interface FeishuTurnTransport {
     chatId: string;
     filesDir: string;
     label: string;
+    /** THIS app's own id (`cli_…`) — the identity a fetched message's `sender.id` carries when the
+     *  sender is an app. Needed to tell the agent's OWN messages from any other bot's in the same chat:
+     *  `sender_type` alone says "some app", which is not the question the referent path asks. */
+    appId: string;
 }
 /** An attachment reference: the resource key inside its CARRYING message (the resource API addresses
  *  bytes by message_id + key, so the pair travels together through the turn record). */

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

@@ -2,9 +2,14 @@ import { log } from "../../log.js";
 import { DEFAULT_BUSY_RETRY, attachedFilesManifest, attributedFileName, backgroundImagesManifest, missingAttachmentsNote, streamTurnWithBusyRetry, } from "../invoke-turn-kit.js";
 import { parseContent } from "./parse.js";
 import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
-/** Appended to the prompt (not the system prompt): the channel renders the reply in a card, and the
- *  card's markdown element is the natural fit for LLM output — steer away from HTML/plain. */
-const MARKDOWN_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card.)";
+/** The per-turn REPLY CONTRACT, appended to the prompt (not the system prompt). Two halves, one
+ *  concept — what happens to the reply: its FORMAT (rendered in a card whose markdown element is the
+ *  natural fit for LLM output — steer away from HTML/plain) and its DELIVERY OWNERSHIP (the channel
+ *  itself delivers it; answering through a send TOOL instead is the observed failure — the channel
+ *  then settles an empty turn as "(no reply)" next to the tool's un-threaded duplicate). */
+const REPLY_INSTRUCTION = "\n\n(Format your reply in standard Markdown — it is rendered in a Feishu/Lark card. This reply is " +
+    "delivered to the current chat by the channel itself: do not call a send tool to answer the " +
+    "current chat.)";
 /**
  * Resolve a turn's inputs (module header): fetch the reply referent's content, then load every image
  * (vision) and file (disk). Primary failures throw; buffered resources degrade independently.
@@ -46,9 +51,30 @@ async function resolveTurnInputs(t, attachments) {
                 files.push({ msg: parentId, key: ref.key, name: ref.name });
             // getMessage's sender is `{ id, id_type, sender_type }` — a DIFFERENT shape from the event's
             // sender (`{ sender_id: { open_id } }`), so the label is built here, not via parse.senderLabel.
+            //
+            // OWN means THIS app, not "an app". A group can hold several bots, and `sender_type === "app"`
+            // is true for every one of them — matching on it alone would tell the model it wrote another
+            // bot's message. The identity to compare is the app id, because an app sender carries
+            // `id_type: "app_id"`: the cached bot open_id answers a different question (who was @mentioned)
+            // and would never match here. A missing or unexpected id fails CLOSED — labelled by id, never
+            // claimed as the agent's own.
+            const appSender = parent.sender?.sender_type === "app";
             const senderId = parent.sender?.id;
-            const from = senderId ? `user ${senderId}` : undefined;
+            const ownMessage = appSender && senderId === t.appId;
+            // An app is not a person: labelling another bot's message "user cli_…" is the same misattribution
+            // in a quieter form, so the noun follows the sender type.
+            const from = ownMessage ? "you, the agent" : senderId ? `${appSender ? "app" : "user"} ${senderId}` : undefined;
             referentBlock = `\n\n[replied-to message (msg ${parentId}${from ? `, from ${from}` : ""}): ${truncateCodePointPrefix(parsed.text, REFERENT_MAX_CODE_POINTS) || "(empty)"}]`;
+            // The chain STOPS here, at the one message the user pointed at. Walking further — to what that
+            // message was itself replying to — was built and removed: it reconstructs HISTORY out of reply
+            // pointers, and history is the session's job. That framing has no non-arbitrary answers (how
+            // many levels? what about the level above that? how is it deduplicated against what the session
+            // already holds? how does an IMAGE two levels up become prompt text at all?), and every one of
+            // those questions is a symptom of solving a session-layer problem in the prompt layer. The real
+            // gap it was papering over — a thread opened on a room answer starts with an EMPTY session while
+            // the room's session holds the exchange — belongs to memory inheritance (design/participant-
+            // model.md §8, rungs 3-4), where images and tool results come along for free because they are
+            // already in the history rather than being re-serialised into a prompt string.
         }
     }
     // Primary first and fail-fast: these are resources the current user explicitly pointed at.
@@ -117,6 +143,6 @@ export async function* invokeFeishuTurn(agent, session, text, transport, attachm
         yield { type: "failed", details: `could not load attachment: ${String(e)}`, retryable: true };
         return;
     }
-    const prompt = { text: `${text}${resolved.promptSuffix}${MARKDOWN_INSTRUCTION}`, images: resolved.images };
+    const prompt = { text: `${text}${resolved.promptSuffix}${REPLY_INSTRUCTION}`, images: resolved.images };
     yield* streamTurnWithBusyRetry(agent, session, prompt, { label: transport.label, onCompleted, busyRetry });
 }