@fastagent-sh/fastagent 0.17.0 → 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

@@ -55,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.
@@ -75,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
@@ -113,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;
@@ -124,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);
             }
         }
@@ -134,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;
@@ -154,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.
@@ -218,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.

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

package/dist/channels/feishu/normalize.js

@@ -1,3 +1,62 @@
+/**
+ * Render one paragraph of tagged nodes to a line, collecting any resource it carries INTO the sink
+ * the caller supplies — or none, when the caller passes no sink.
+ *
+ * Shared by `post` and `interactive` because the platform hands both out in the same shape. Card-only
+ * shapes are handled here rather than in a second walker: `note` nests its own `elements`, and the
+ * widget tags (button/select/overflow/date_picker) carry their user-visible label in `text` or
+ * `placeholder` — a card is read for what it SAYS, so a label is content and an unlabelled control is
+ * nothing.
+ *
+ * The OPTIONAL sink is the whole reason this is a parameter rather than a return value: a card's
+ * resources are documented as unfetchable (see the card branch), so that caller renders the same
+ * `[image]` / `[video]` markers into the text while collecting nothing. The markers still tell the
+ * model what is there; what must not happen is a key entering the turn's PRIMARY inputs, which load
+ * fail-fast.
+ */
+function renderNodes(nodes, resources) {
+    if (!Array.isArray(nodes))
+        return "";
+    const parts = [];
+    for (const raw of nodes) {
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const node = raw;
+        if (node.tag === "at") {
+            parts.push(`@${nonEmptyString(node.user_name) ?? nonEmptyString(node.user_id) ?? "user"}`);
+        }
+        else if (node.tag === "a") {
+            parts.push(node.href ? `${nonEmptyString(node.text) ?? node.href} (${node.href})` : (node.text ?? ""));
+        }
+        else if (node.tag === "img") {
+            const key = nonEmptyString(node.image_key);
+            if (key)
+                resources?.push({ kind: "image", key });
+            parts.push("[image]");
+        }
+        else if (node.tag === "media") {
+            const key = nonEmptyString(node.file_key);
+            if (key)
+                resources?.push({ kind: "video", key, name: nonEmptyString(node.file_name) });
+            parts.push("[video]");
+        }
+        else if (node.tag === "code_block") {
+            parts.push(`\n\`\`\`${nonEmptyString(node.language)?.toLowerCase() ?? ""}\n${nonEmptyString(node.text) ?? ""}\n\`\`\`\n`);
+        }
+        else if (node.tag === "note") {
+            const nested = renderNodes(node.elements, resources);
+            if (nested)
+                parts.push(nested);
+        }
+        else if (nonEmptyString(node.text)) {
+            parts.push(node.text);
+        }
+        else if (nonEmptyString(node.placeholder)) {
+            parts.push(node.placeholder);
+        }
+    }
+    return parts.join("").trim();
+}
 function nonEmptyString(value) {
     return typeof value === "string" && value !== "" ? value : undefined;
 }
@@ -37,43 +96,49 @@ export function decodeFeishuContent(message) {
                 lines.push(title);
             const paragraphs = Array.isArray(content.content) ? content.content : [];
             for (const paragraph of paragraphs) {
-                if (!Array.isArray(paragraph))
-                    continue;
-                const parts = [];
-                for (const node of paragraph) {
-                    if (typeof node !== "object" || node === null)
-                        continue;
-                    if (node.tag === "at") {
-                        parts.push(`@${nonEmptyString(node.user_name) ?? nonEmptyString(node.user_id) ?? "user"}`);
-                    }
-                    else if (node.tag === "a") {
-                        parts.push(node.href ? `${nonEmptyString(node.text) ?? node.href} (${node.href})` : (node.text ?? ""));
-                    }
-                    else if (node.tag === "img") {
-                        const key = nonEmptyString(node.image_key);
-                        if (key)
-                            resources.push({ kind: "image", key });
-                        parts.push("[image]");
-                    }
-                    else if (node.tag === "media") {
-                        const key = nonEmptyString(node.file_key);
-                        if (key)
-                            resources.push({ kind: "video", key, name: nonEmptyString(node.file_name) });
-                        parts.push("[video]");
-                    }
-                    else if (node.tag === "code_block") {
-                        parts.push(`\n\`\`\`${nonEmptyString(node.language)?.toLowerCase() ?? ""}\n${nonEmptyString(node.text) ?? ""}\n\`\`\`\n`);
-                    }
-                    else if (nonEmptyString(node.text)) {
-                        parts.push(node.text);
-                    }
-                }
-                const line = parts.join("").trim();
+                const line = renderNodes(paragraph, resources);
                 if (line)
                     lines.push(line);
             }
             return { text: lines.join("\n"), resources };
         }
+        // A CARD, as the platform hands it BACK. What we send is an entity reference
+        // (`{type:"card",data:{card_id}}`, card.ts) whose text lives in cardkit — but a query API renders
+        // the card down to `title` + `elements` (paragraphs of the same tagged nodes as `post`), so the
+        // content is readable without a second remote call. This is the message type the agent's OWN
+        // answers are, so the case that matters is a user following up on one: without this branch a
+        // reply-referent that is the agent's own card decoded to the bare `[interactive message]` marker
+        // and the model was told its own answer was unreadable (field-observed).
+        //
+        // BOTH spellings on purpose: the platform's own docs disagree with themselves — the field table
+        // says `interactive` (what the receive EVENT carries) while the message-object example shows
+        // `"msg_type": "card"`. Matching one would leave the other silently on the default branch, which
+        // is exactly the symptom this fixes.
+        case "interactive":
+        case "card": {
+            const lines = [];
+            const title = nonEmptyString(content.title);
+            if (title)
+                lines.push(title);
+            const paragraphs = Array.isArray(content.elements) ? content.elements : [];
+            for (const paragraph of paragraphs) {
+                // NO resource sink, deliberately. The platform documents that a card's resources cannot be
+                // fetched at all: `im/v1/messages/:id/resources/:key` answers 234043 ("Unsupported message
+                // type") for a card message id, by stated limitation rather than by permission. Collecting a
+                // key here would hand the turn a PRIMARY input that is guaranteed to fail its fail-fast load
+                // — turning "the card reads as a marker" (the old behaviour) into "the whole turn errors",
+                // which is strictly worse than the gap this branch exists to close. The text still renders
+                // `[image]` / `[video]`, so the model knows what is there and that it does not have it.
+                //
+                // Tolerate both shapes: elements as paragraphs (array of arrays) and a flat element list.
+                const line = Array.isArray(paragraph) ? renderNodes(paragraph) : renderNodes([paragraph]);
+                if (line)
+                    lines.push(line);
+            }
+            // An unrenderable card (all controls, no labels) still says something by existing — keep the
+            // marker rather than returning empty, which reads as "the message was blank".
+            return { text: lines.length > 0 ? lines.join("\n") : `[${rawType} message]`, resources };
+        }
         case "image": {
             const key = nonEmptyString(content.image_key);
             if (key)

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

@@ -15,9 +15,10 @@ export type MountedFeishuPreview = {
     messageId: string;
 };
 /**
- * Mount one preview message: preferably a streaming card entity, with a static text message as the
- * visible fallback. Queue feedback and ordinary turn startup share this constructor so a queued card
- * has exactly the same shape the stream pump expects to take over later.
+ * Mount one preview message: preferably a streaming card entity (`initial` seeds the process element;
+ * the answer element starts empty), with a static text message as the visible fallback. Queue feedback
+ * and ordinary turn startup share this constructor so a queued card has exactly the same shape the
+ * stream pump expects to take over later.
  */
 export declare function mountFeishuPreview(api: FeishuApi, target: FeishuTarget, initial: string, label?: string): Promise<MountedFeishuPreview>;
 /** Settle an already-mounted queue preview without starting an Agent stream (the poison/defer paths).

package/dist/channels/feishu/preview.js

@@ -1,8 +1,10 @@
 /**
  * Canonical Feishu live-preview rendering (also reused by Lark compatibility). The preview is ONE
- * streaming CARD (create entity → mount it with a reply/send → stream full-text snapshots at its
- * markdown element with a strictly increasing `sequence`; the client renders the typewriter effect);
- * on completion the same card is settled in place with the final answer (streaming off). Streaming
+ * streaming CARD of TWO elements — the volatile `process` block and the append-only `answer` (see
+ * card.ts for why the split is the prefix-stability fix) — (create entity → mount it with a
+ * reply/send → stream full-text snapshots per element with a strictly increasing `sequence`; the
+ * client renders the typewriter effect); on completion the same card is settled in place with the
+ * final answer alone (streaming off). Streaming
  * updates ride the cardkit quota (50 QPS per app, 10 QPS per card entity, no edit ceiling) — NOT the
  * 5 QPS per-chat message quota or
  * the 20-edit cap on text messages, which is why the preview is a card and not an edited text message.
@@ -21,10 +23,10 @@
  */
 import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
-import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
+import { ANSWER_ELEMENT_ID, CARD_MARKDOWN_MAX_BYTES, PROCESS_ELEMENT_ID, cardEntityContent, finalCardJson, streamingCardJson, } from "./card.js";
 import { chunkFeishuText, isCardStreamingClosed } from "./feishu-api.js";
 import { RETRY_NOTICE, THINKING_PLACEHOLDER, applyTurnEvent, composeTurnBody, createPreviewPump, createTurnView, defaultErrorMessage, revealedAnswer, thinkingLine, toolLines, } from "../preview-kit.js";
-import { truncateUtf8 } from "../text.js";
+import { truncateCodePointPrefix, truncateUtf8 } from "../text.js";
 export { defaultErrorMessage };
 /** How often (ms) to push a live-preview snapshot; tool events still flush on the next loop. Cardkit
  *  allows 10 QPS per card entity (50 per app), but one snapshot a second reads smoothly (the client
@@ -33,12 +35,41 @@ export { defaultErrorMessage };
 const STREAM_THROTTLE_MS = 1000;
 /** How much of the (growing) reasoning to peek at in the live view — the most recent tail. */
 const THINKING_PREVIEW = 280;
-/** Cap a live view to the card budget, PREFIX-STABLE: the streaming client animates only when the old
- *  text is a prefix of the new, so an over-budget view freezes at its head rather than sliding a tail
- *  window (which would redraw the whole card every frame). The full answer still lands at settle. */
+/** Cap (code points) on the whole process block — thinking tail + tool lines + retry notice. It
+ *  redraws wholly on change anyway (it is volatile by nature), so over budget the newest COMPLETE
+ *  lines win (see tailLines). ≤1000 points is ≤4 KB UTF-8, which together with the answer's byte cap
+ *  stays inside the 30 KB entity budget. */
+const PROCESS_MAX_POINTS = 1000;
+/** Cap the live answer to the card budget, PREFIX-STABLE: the streaming client animates only when the
+ *  old text is a prefix of the new, so an over-budget answer freezes at its head rather than sliding a
+ *  tail window (which would re-type the element every frame). The full answer still lands at settle. */
 function capBytes(s, maxBytes) {
     return truncateUtf8(s, maxBytes);
 }
+/** Tail-select COMPLETE lines within a code-point budget — the process block's cap. The block's
+ *  lines are semantic units (a `🔧` tool call, the `💭` peek, the `⏳` notice): cutting mid-line
+ *  would orphan a marker or tear a label, so elision happens only at line boundaries, newest lines
+ *  kept, with a leading `…` line marking what was dropped. The in-line guard cannot trigger with the
+ *  bounded renderers (a thinking tail ≤ ~283 points, a tool line ≤ ~135) — it exists so a future
+ *  unbounded line degrades to a head-preserving cut instead of an empty block. */
+function tailLines(text, maxPoints) {
+    if (Array.from(text).length <= maxPoints)
+        return text;
+    const lines = text.split("\n");
+    const kept = [];
+    let used = 2; // the leading "…\n" elision marker
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i] ?? "";
+        const cost = Array.from(line).length + (kept.length > 0 ? 1 : 0); // +1 joining newline
+        if (used + cost > maxPoints)
+            break;
+        used += cost;
+        kept.unshift(line);
+    }
+    if (kept.length === 0)
+        return truncateCodePointPrefix(lines.at(-1) ?? "", maxPoints);
+    return `…\n${kept.join("\n")}`;
+}
 /**
  * The terminal-write POLICY: resolve the preview into `text`. One card → settle it in place (final
  * markdown, streaming off); an over-budget answer settles the card with its first chunk and sends the
@@ -90,9 +121,10 @@ async function finalize(api, target, preview, text, seq) {
     await api.sendText(target, text);
 }
 /**
- * Mount one preview message: preferably a streaming card entity, with a static text message as the
- * visible fallback. Queue feedback and ordinary turn startup share this constructor so a queued card
- * has exactly the same shape the stream pump expects to take over later.
+ * Mount one preview message: preferably a streaming card entity (`initial` seeds the process element;
+ * the answer element starts empty), with a static text message as the visible fallback. Queue feedback
+ * and ordinary turn startup share this constructor so a queued card has exactly the same shape the
+ * stream pump expects to take over later.
  */
 export async function mountFeishuPreview(api, target, initial, label = "[feishu]") {
     try {
@@ -151,17 +183,27 @@ export async function settleFeishuPreview(api, target, preview, text) {
  */
 export async function streamFeishuReply(events, api, target, formatError, initialPreview, label = "[feishu]") {
     // Event → view-state reduction is the shared machine (preview-kit); this renderer owns the reveal
-    // policy, the card-budget cap, and delivery below.
+    // policy, the card-budget caps, and delivery below. The card is TWO elements (card.ts): the process
+    // block's head changes every frame (sliding thinking tail, `…`→`✓` flips), so it must never share
+    // an element with the answer — the client would re-type the whole card from the divergence point
+    // once a second. Each view feeds its own element; only the changed one is written.
     const turn = createTurnView();
-    const view = () => {
+    const processView = () => {
         const v = composeTurnBody([
             thinkingLine(turn, THINKING_PREVIEW),
             toolLines(turn),
             turn.retrying ? RETRY_NOTICE : "",
-            revealedAnswer(turn, STREAM_THROTTLE_MS),
         ]);
-        return capBytes(v === "" ? THINKING_PLACEHOLDER : v, CARD_MARKDOWN_MAX_BYTES);
+        if (v !== "")
+            return tailLines(v, PROCESS_MAX_POINTS);
+        // No process content: the placeholder covers only the silence BEFORE the answer reveals — once
+        // the answer is streaming, an empty block goes (stays) empty; "Thinking…" pinned above a live
+        // answer would misstate the phase. The empty frame is a real write: it clears a mounted
+        // placeholder. (The block cannot otherwise flicker: thinking and tools only grow — only the
+        // retry notice toggles, and its empty state resolves through this same rule.)
+        return revealedAnswer(turn, STREAM_THROTTLE_MS).trim() === "" ? THINKING_PLACEHOLDER : "";
     };
+    const answerView = () => capBytes(revealedAnswer(turn, STREAM_THROTTLE_MS), CARD_MARKDOWN_MAX_BYTES);
     // The live preview is ONE message: either the queue card/text handed in by the wiring, or a preview
     // mounted lazily on this turn's first flush. `sequence` must increase strictly per card — the single-
     // writer pump guarantees it by construction. A queue card has had no updates yet, so sequence starts
@@ -172,22 +214,34 @@ export async function streamFeishuReply(events, api, target, formatError, initia
     const nextSeq = () => ++sequence;
     let streamDead = false; // the platform closed streaming (idle timeout) — freeze the live view
     let finalized = false; // a terminal write (completed/failed) ran — the finally skips its orphan cleanup
-    let lastSent = "";
+    let lastProcess = "";
+    let lastAnswer = "";
     const flushPreview = async () => {
-        const text = view();
+        const process = processView();
         if (!setupAttempted) {
             setupAttempted = true;
-            preview = await mountFeishuPreview(api, target, text, label);
-            lastSent = text;
+            // The mount seeds the process element with the current view; the answer element starts empty
+            // (card.ts), so the first answer snapshot is a clean prefix extension.
+            preview = await mountFeishuPreview(api, target, process, label);
+            lastProcess = process;
             return;
         }
         if (preview.kind !== "card" || streamDead)
             return; // text tier / dead stream: frozen until the terminal write
-        if (text === lastSent)
-            return; // skip an unchanged snapshot
-        lastSent = text;
         try {
-            await api.updateCardElement(preview.cardId, ANSWER_ELEMENT_ID, text, nextSeq());
+            // `last*` advances BEFORE each write: a frame that fails for a non-streaming reason is logged
+            // once (the pump's onError) and not re-sent until its content actually changes. An EMPTY
+            // process frame is written like any other — it is the placeholder being cleared (processView).
+            if (process !== lastProcess) {
+                lastProcess = process;
+                await api.updateCardElement(preview.cardId, PROCESS_ELEMENT_ID, process, nextSeq());
+            }
+            const answer = answerView();
+            // Never write an empty answer snapshot — the element is born empty and the answer only grows.
+            if (answer !== "" && answer !== lastAnswer) {
+                lastAnswer = answer;
+                await api.updateCardElement(preview.cardId, ANSWER_ELEMENT_ID, answer, nextSeq());
+            }
         }
         catch (e) {
             if (isCardStreamingClosed(e)) {

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

@@ -56,12 +56,15 @@ async function tenantToken(): Promise<string> {
 
 export default defineTool({
   description:
-    "Send a message to a Feishu chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
-    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
-    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
-    "answer (it would post the message twice). chatId comes from the [feishu: chat …] context line in a " +
-    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
+    "Send a message to a Feishu chat, OUTSIDE the normal reply path. Call it only for a turn NO " +
+    "channel is carrying — a scheduled or self-scheduled (wake) turn, whose plain reply goes " +
+    "nowhere — or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
+    "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
+    "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
+    "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
+    "or memory); the [feishu: chat …] context line only identifies the chat you are answering — the " +
+    "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
+    "`markdown` (rendered as a card: headings, bold, code blocks, links).",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),

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

@@ -56,12 +56,15 @@ async function tenantToken(): Promise<string> {
 
 export default defineTool({
   description:
-    "Send a message to a Lark chat: plain `text`, or `markdown` (rendered as a card — headings, " +
-    "bold, code blocks, links). Exactly one of the two. Use it for a turn NO channel is carrying — a " +
-    "scheduled or self-scheduled (wake) turn — or to reach a chat OTHER than the one you are " +
-    "answering. In a normal chat turn the channel already delivers your reply, so do NOT call this to " +
-    "answer (it would post the message twice). chatId comes from the [lark: chat …] context line in a " +
-    "chat turn; a scheduled/woken turn has no context line, so name the destination in your instruction.",
+    "Send a message to a Lark chat, OUTSIDE the normal reply path. Call it only for a turn NO " +
+    "channel is carrying — a scheduled or self-scheduled (wake) turn, whose plain reply goes " +
+    "nowhere — or to reach a chat OTHER than the one you are answering. In a normal chat turn the " +
+    "channel streams and delivers your reply itself, so do NOT call this to answer the current " +
+    "chat: it would post the message twice, outside the conversation thread. `chatId` (oc_…) names " +
+    "the DESTINATION and must come from your instructions (the asking message, the schedule prompt, " +
+    "or memory); the [lark: chat …] context line only identifies the chat you are answering — the " +
+    "one chat this tool must not target in a chat turn. Pass exactly ONE of `text` (plain) or " +
+    "`markdown` (rendered as a card: headings, bold, code blocks, links).",
   input: z.object({
     chatId: z.string().describe("target chat id (oc_…)"),
     text: z.string().optional().describe("plain text message to send"),

package/dist/cli/commands/start.js

@@ -18,6 +18,7 @@ import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { exists } from "../../paths.js";
 import { bindAddress } from "../../bind.js";
+import { parseRouteKey } from "../../host/node.js";
 import { failStartup, placementOrExit } from "../fail.js";
 import { assertTunnelBindable, maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules, } from "../serve.js";
 import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
@@ -89,13 +90,21 @@ export async function runStart(dirArg, opts) {
     const agentcore = process.env.FASTAGENT_AGENTCORE === "1";
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
-    const routed = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: !agentcore }).catch(failStartup);
+    // On AgentCore the channels are constructed LAZILY (mountAgentcore's lazyChannels, resolved on the
+    // first envelope after the state-snapshot restore): construction loads channel state and replays
+    // turn intent, and at boot the state mount is PRE-RESTORE — empty after every version update — so
+    // an eager build would cache that emptiness (thread participation, delivery dedup, pending turns)
+    // and then clobber the restored files with it. Everywhere else the state root is durable at boot,
+    // so channels mount eagerly and a broken channel fails startup.
+    const routed = agentcore
+        ? undefined
+        : await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: true }).catch(failStartup);
     // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
     // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
     const configured = config.http?.host;
     const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
     assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
-    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
+    const withControl = mountSessionControl(routed?.routes ?? {}, sessionControl, stateRoot, {
         tunnel: opts.tunnel ?? false,
         agent: traced,
         host,
@@ -126,17 +135,42 @@ export async function runStart(dirArg, opts) {
     });
     let routes = withControl.routes;
     if (agentcore) {
+        // The lazy channel surface the adapter resolves post-restore. Control routes ride along so a
+        // forwarder-relayed /control/* request dispatches the same as on a direct host. Long-connection
+        // channels cannot serve here — scale-to-zero severs a resident connection and nothing
+        // re-establishes it — so their presence is a configuration error, surfaced per envelope and by
+        // the deploy driver's health probe (there is no boot to fail on this host).
+        const lazyChannels = async () => {
+            const surface = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: false });
+            if (surface.longConnections.length > 0) {
+                throw new Error(`long-connection channel(s) ${surface.longConnections.map((c) => c.name).join(", ")} cannot serve on ` +
+                    `AgentCore (scale-to-zero severs resident connections) — use the channel's webhook form`);
+            }
+            // mountSessionControl's PATH-level collision rule, re-asserted here: with no channels at boot
+            // its own check ran against an empty base, and a spread merge would silently let control win —
+            // but a channel on /control/* is the same configuration error it is on every other host.
+            const controlPaths = new Set(Object.keys(withControl.routes).map((key) => parseRouteKey(key).path));
+            const collisions = Object.keys(surface.routes).filter((key) => controlPaths.has(parseRouteKey(key).path));
+            if (collisions.length > 0) {
+                throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control ` +
+                    `plane — rename the channel route or disable sessionControl in fastagent.config`);
+            }
+            return { ...surface.routes, ...withControl.routes };
+        };
         try {
-            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady });
+            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady, lazyChannels });
         }
         catch (e) {
             failStartup(e);
         }
         log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
     }
-    serve({ ...routed, routes }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
+    serve({
+        ...(routed ?? { longConnections: [], routeChannels: [], builtinInvoke: false, markReady() { } }),
+        routes,
+    }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
         withControl.announce(p);
-        maybeTunnel(agentDir, routed.routeChannels, p, opts.tunnel ?? false, stateRoot);
+        maybeTunnel(agentDir, routed?.routeChannels ?? [], p, opts.tunnel ?? false, stateRoot);
     });
     // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
     // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK

package/dist/cli/serve.d.ts

@@ -49,6 +49,10 @@ export declare function mountAgentcore(routes: Routes, options: {
     stateRoot: string;
     schedules: LoadedSchedule[];
     onStateReady?: () => void;
+    /** The serving path's LAZY channel surface: constructed by the adapter on the first envelope
+     *  AFTER the state-snapshot restore, never at boot (channels/agentcore.ts). When absent,
+     *  `routes` is the dispatch target — for wirings whose state root is already authoritative. */
+    lazyChannels?: () => Promise<Routes>;
 }): Routes;
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`

package/dist/cli/serve.js

@@ -151,9 +151,9 @@ export function mountSessionControl(routes, control, stateRoot, options = {}) {
  * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
  */
 export function mountAgentcore(routes, options) {
-    const { agent, stateRoot, schedules, onStateReady } = options;
+    const { agent, stateRoot, schedules, onStateReady, lazyChannels } = options;
     const mounted = agentcoreRoutes({
-        routes,
+        routes: lazyChannels ?? routes,
         agent,
         stateRoot,
         isBusy: () => activeWork() > 0,

package/dist/deploy/agentcore/plan.js

@@ -396,6 +396,23 @@ exports.handler = async (event, ctx) => {
     if (failed > 0) return { statusCode: 500, body: \`\${failed} alarm(s) failed\\n\` };
     return { statusCode: 200, body: "ok\\n" };
   }
+  // The deploy driver's probe (reserved path, ingress secret): wake the runtime through the SAME
+  // trusted envelope pipeline (state URLs included — a direct InvokeAgentRuntime call could not mint
+  // them, and would make the runtime construct against a pre-restore mount) and pass its structured
+  // transport-200 verdict back VERBATIM. The ordinary webhook path below folds a non-200 transport
+  // into an opaque 502, which would strip exactly the diagnostics the probe exists to carry — and it
+  // sits BEFORE the WEBHOOKS_ENABLED gate so schedule-only topologies (whose URLs refuse ordinary
+  // public traffic) are probeable too.
+  if (event.rawPath === "/__fastagent/probe") {
+    const req = JSON.parse(event.isBase64Encoded ? Buffer.from(event.body, "base64").toString() : event.body || "{}");
+    if (!process.env.INGRESS_SECRET || req.auth !== process.env.INGRESS_SECRET) return { statusCode: 403, body: "forbidden\\n" };
+    const r = await invoke({ kind: "probe" });
+    if (r.status !== 200) {
+      console.log(\`probe transport error \${r.status}: \${r.body}\`);
+      return { statusCode: 502, body: "upstream error\\n" };
+    }
+    return { statusCode: 200, headers: { "content-type": "application/json" }, body: r.body.toString() };
+  }
   // Enforce the advertised ORIGINAL-body ceiling before base64 adds another 4/3 inside the runtime
   // envelope. This also leaves deterministic room for headers/query/JSON under Lambda's 6 MB cap.
   const webhookBytes = event.body === undefined ? 0

package/dist/deploy/agentcore/run.d.ts

@@ -70,4 +70,10 @@ export declare function parseCheckpointReply(stdout: string): CheckpointReply |
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<AgentcoreRunOutcome>;
+export declare function deployAgentcoreRun(plan: AgentcoreRunPlan, aws: CliRunner, docker: CliRunner, log: (msg: string) => void, writeSecretFile: (content: string) => Promise<string>, writeForwarderZip: (bytes: Uint8Array) => Promise<string>, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>, 
+/** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
+probe?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<AgentcoreRunOutcome>;

package/dist/deploy/agentcore/run.js

@@ -3,6 +3,66 @@ import { createHash } from "node:crypto";
 import { Buffer } from "node:buffer";
 import { AUTH_SEED_CHUNK_SIZE, AUTH_SEED_MAX_CHUNKS, cfnParamName, forwarderSource, ingressSessionId, stateBucketName, } from "./plan.js";
 import { zipSingleFile } from "./zip.js";
+/** How long the post-deploy probe waits for the fresh session (image pull + microVM boot + snapshot
+ *  restore + channel construction) before gating with the last answer. */
+const PROBE_TIMEOUT_MS = 120_000;
+const PROBE_INTERVAL_MS = 3_000;
+/**
+ * Drive the forwarder's reserved `/__fastagent/probe` path until it answers, and read the runtime's
+ * STRUCTURED verdict. The path answers on every forwarder topology (a schedule-only URL refuses
+ * ordinary public traffic, so a plain `GET /health` would 404 there), and the verdict rides a
+ * transport-200 JSON body `{ ok, error? }` — the ordinary webhook relay folds a non-200 transport
+ * into an opaque 502, which would strip the very diagnostics this probe exists to carry.
+ *
+ * Outcome policy: `ok:true` verifies the deploy; `ok:false` gates IMMEDIATELY with the runtime's own
+ * error text (construction rejections are cached per session, so polling cannot change the answer);
+ * anything else (unroutable URL, forwarder 4xx/5xx, malformed body) is retried to the deadline —
+ * that budget's job is absorbing cold-start provisioning — and then gates with the last answer seen.
+ */
+async function probeRuntime(probeUrl, auth, fetchImpl, timeoutMs = PROBE_TIMEOUT_MS, intervalMs = PROBE_INTERVAL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    let last;
+    for (;;) {
+        try {
+            const res = await fetchImpl(probeUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ auth }),
+                signal: AbortSignal.timeout(65_000),
+            });
+            const bodyText = await res.text();
+            if (res.status === 200) {
+                let verdict;
+                try {
+                    verdict = JSON.parse(bodyText);
+                }
+                catch {
+                    /* malformed — fall through to retry with it as the last answer */
+                }
+                if (verdict?.ok === true)
+                    return { ok: true };
+                if (verdict?.ok === false) {
+                    const error = typeof verdict.error === "string" ? verdict.error : "unknown error";
+                    return { ok: false, gate: `the deployed runtime failed its probe: ${error} — fix and re-run` };
+                }
+            }
+            const firstLine = bodyText.trim().split("\n")[0] ?? "";
+            last = `${res.status}${firstLine ? ` ${firstLine}` : ""}`;
+        }
+        catch {
+            /* not routable yet (Function URL DNS, cold start) — keep polling until the deadline */
+        }
+        if (Date.now() >= deadline) {
+            return {
+                ok: false,
+                gate: last
+                    ? `the forwarder probe never verified the deployment (last answer: ${last}) — check the runtime logs and re-run`
+                    : "the forwarder URL never answered the probe — check the Function URL / runtime logs and re-run",
+            };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
 /** Stack outputs (`describe-stacks --query "Stacks[0].Outputs"`) → { OutputKey: OutputValue }. */
 export function parseStackOutputs(stdout) {
     try {
@@ -63,7 +123,9 @@ export function parseCheckpointReply(stdout) {
  * post-deploy webhook steps from the builder machine against the forwarder's Function URL. Every
  * gate is fail-visible; `writeSecretFile` is the caller's 0600-temp-file seam (see the header).
  */
-export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack) {
+export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile, writeForwarderZip, registerTelegram, registerFeishu, registerSlack, 
+/** Injected in tests; the probe itself stays inside the run so no deploy can skip it. */
+probe = {}) {
     const gate = (g) => ({ ok: false, gate: g });
     const stack = `fastagent-${plan.name}`;
     const repo = `fastagent/${plan.name}`;
@@ -359,19 +421,42 @@ export async function deployAgentcoreRun(plan, aws, docker, log, writeSecretFile
                 log("note: no ingress session to stop (first deploy, or already reclaimed)");
             }
             else {
-                log(`warn: could not stop the ingress session — an ACTIVE session may keep serving the PREVIOUS ` +
-                    `image until reclaimed (idle timeout / 8 h ceiling). Stop it manually: aws ${stopCommand.join(" ")}`);
+                // A GATE, not a warning: the probe below reaches the SAME fixed session id, so a session
+                // still running the previous image would answer it and the deploy would claim to have
+                // verified a serving path it never touched. Unable to guarantee the session is fresh =
+                // unable to verify = stop.
                 const firstLine = stderr.trim().split("\n")[0];
-                if (firstLine)
-                    log(`warn: ${firstLine}`);
+                return gate(`could not stop the ingress session — it may still be serving the PREVIOUS image, so the ` +
+                    `deploy cannot verify the new one${firstLine ? ` (${firstLine})` : ""}. ` +
+                    `Stop it manually (aws ${stopCommand.join(" ")}) and re-run`);
             }
         }
     }
+    // 8c. Every forwarder topology MUST carry the ForwarderUrl output — schedule-only and
+    //     selfSchedule-only deployments included, since the probe below is their only construction
+    //     check (there is no boot-time failStartup on this host). A missing output means an edited
+    //     template; skipping the probe silently would let such a deploy report success unverified.
+    //     Only a pure-invoke deployment (no forwarder) legitimately has no URL and nothing to probe.
+    //     `channels.length` is belt-and-braces: the planner derives needsForwarder FROM the channel
+    //     list, but this gate must not silently trust that invariant across callers.
+    if ((plan.needsForwarder || plan.channels.length > 0) && !url) {
+        return gate("this deployment needs the forwarder but the stack has no ForwarderUrl output — regenerate the " +
+            "template with --force");
+    }
+    // 8d. Warm + verify the NEW serving path end to end, BEFORE registration: the probe wakes a fresh
+    //     session on the new image through the forwarder's reserved path, which restores the state
+    //     snapshot and constructs the channels — construction is deferred to exactly that moment
+    //     (channels/agentcore.ts), so this is where a bad credential, a broken channels/ module, or an
+    //     unrestorable snapshot surfaces AT DEPLOY TIME with the runtime's own error text.
+    if (url) {
+        log("probing the deployed runtime (state restore + channel construction)…");
+        const verdict = await probeRuntime(`${url}/__fastagent/probe`, plan.secrets.FASTAGENT_INGRESS_SECRET ?? "", probe.fetchImpl ?? fetch, probe.timeoutMs, probe.intervalMs);
+        if (!verdict.ok)
+            return gate(verdict.gate);
+        log("runtime verified (state restored, channels constructed)");
+    }
     // 9. Post-deploy webhook registration — same registrar seam as every host, pointed at the
     //    forwarder's Function URL. Gate policy is the shared registration-gate kernel.
-    if (plan.channels.length > 0 && !url) {
-        return gate("channels are declared but the stack has no ForwarderUrl output — regenerate the template with --force");
-    }
     const reg = registrationGate(log, "re-run to retry registration (steps already done are skipped)");
     if (url) {
         if (plan.channels.includes("telegram")) {

package/dist/deploy/preflight.js

@@ -195,12 +195,17 @@ export async function preflightDeploy(input) {
         const rel = relative(workspace, p);
         return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? undefined : rel.split(sep).join("/");
     };
-    // The secrets DIR is the unit, not the two filenames we happen to know: an atomic-write temp beside
-    // auth.json, a second key file, an editor backup of `.env` — all of it must stay out of the image, and
-    // `resolveSecretsDir` says as much ("everything fastagent manages that must never leave the machine").
-    // The auth path adds an entry only when an override puts it OUTSIDE that dir. An external secrets dir
-    // (the deployed posture: a mounted volume) is outside the context — nothing to check, nothing to
-    // exclude.
+    // The secrets DIR is the unit of RESPONSIBILITY, but never the unit of the leak QUESTION below: the
+    // generated ignore excludes the dir's CONTENTS (`**/.secrets/**`) so its two value-free tracked
+    // scaffolds can be re-included, and a directory-level question reads that correct file as "not
+    // excluded" — the generator's own default output gated its own deploy (field-hit: a fresh
+    // kit-layout workspace without --force; --force skips checking our own file, which is why the
+    // combination stayed invisible). What leaks is a FILE, so files are what the gate asks about — see
+    // secretDirFiles below, which enumerates what is actually inside (an atomic-write temp beside
+    // auth.json, a second key file, an editor backup of `.env`: the dir-as-unit worry, covered per
+    // file). The auth path adds an entry only when an override puts it OUTSIDE that dir. An external
+    // secrets dir (the deployed posture: a mounted volume) is outside the context — nothing to check,
+    // nothing to exclude.
     const secretsRel = inContext(resolveSecretsDir(agentDir));
     const authRel = inContext(authPath);
     const authElsewhere = authRel !== undefined && (secretsRel === undefined || !authRel.startsWith(`${secretsRel}/`));
@@ -246,7 +251,29 @@ export async function preflightDeploy(input) {
             .map((n) => join(relDir, n).split(sep).join("/"));
     };
     const envFiles = (await Promise.all([...new Set(["", agentPrefix])].map(dotEnvFiles))).flat();
-    const leakCandidates = [...(await present(secretPaths)), ...envFiles];
+    // Everything ACTUALLY inside the secrets dir, minus the two tracked scaffolds the image ships on
+    // purpose (they carry no values; the generated ignore re-includes them by name). Existence is the
+    // enumeration itself — readdir lists exactly what could be baked — and a hand-written ignore that
+    // misses the dir now gates NAMING the leaking file, a better diagnostic than pointing at a
+    // directory. Recurses: a subdirectory inside .secrets is unusual but its files leak all the same.
+    const secretDirFiles = async (dirRel) => {
+        const entries = await readdir(join(workspace, dirRel), { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            if (entry.name === ".gitignore" || entry.name === ".env.example")
+                continue;
+            if (entry.isDirectory())
+                files.push(...(await secretDirFiles(`${dirRel}/${entry.name}`)));
+            else
+                files.push(`${dirRel}/${entry.name}`);
+        }
+        return files;
+    };
+    const leakCandidates = [
+        ...(secretsRel ? await secretDirFiles(secretsRel) : []),
+        ...(await present(authElsewhere && authRel !== undefined ? [authRel] : [])),
+        ...envFiles,
+    ];
     // Same existence rule: a node_modules that is not there cannot be uploaded.
     const depDirs = await present([...new Set([`${agentPrefix}node_modules`, "node_modules"])]);
     const machineryPaths = [...secretPaths, ...(stateRel ? [stateRel] : [])];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, Telegram, Slack, or behind any channel.",
   "keywords": [
     "agent",