@fastagent-sh/fastagent 0.16.2 → 0.17.1

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/attach.d.ts

@@ -72,6 +72,24 @@ export interface AttachIo {
  * whole — the one case where "unknown" must not read as "off-path".
  */
 export declare function activePathSlice(entries: SessionEntry[], leafEntryId: string | undefined): SessionEntry[];
+/**
+ * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
+ * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
+ * differently:
+ *
+ * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
+ *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
+ *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
+ *   about to prove it names a real skill;
+ * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
+ * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
+ *   an intent the typo did not express.
+ *
+ * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
+ * printing them with a slash would invite the user straight back into this branch. Returns the
+ * promise for the remote half, so a caller (or a test) can await the second line.
+ */
+export declare function answerSlashInput(trimmed: string, control: Pick<SessionControl, "commands">, println: (line: string) => void): Promise<void>;
 /**
  * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
  * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager

package/dist/cli/commands/attach.js

@@ -185,7 +185,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
         // invoke) — give the human a corrective signal.
         log.warn(`[fastagent] no durable record for "${sessionArg}" yet — a new session, or a typo?`);
     }
-    log.info(`[fastagent] type to steer the active run; /abort to stop it; Ctrl+C to detach`);
+    log.info(`[fastagent] type to steer the active run; /abort to stop it; /commands to list what this agent defines; Ctrl+C to detach`);
     // stdin → the two planes: a line steers the ACTIVE run; with no run to join (no_active_run) it
     // falls back to STARTING one over the remote data plane (`POST /control/invoke`) — try-steer-
     // then-prompt avoids a state() pre-check race. Acceptance is not outcome: rejections print and
@@ -222,7 +222,7 @@ export async function runAttach(sessionArg, dirArg, opts) {
         // `/` is a reserved command prefix: a typo'd /aboort silently steering the model (injecting a
         // prompt when the user meant to STOP the run) is the dangerous direction of the ambiguity.
         if (trimmed.startsWith("/") && trimmed !== "/abort") {
-            console.log(`[unknown command ${trimmed} — /abort stops the run; a leading / is reserved]`);
+            void answerSlashInput(trimmed, control, (l) => console.log(l));
             return;
         }
         const command = trimmed === "/abort" ? { type: "abort" } : { type: "steer", prompt: { text: trimmed } };
@@ -449,6 +449,50 @@ export function activePathSlice(entries, leafEntryId) {
     }
     return entries.filter((e) => onPath.has(e.id));
 }
+/**
+ * Answer a RESERVED-SLASH line (anything starting with `/` that is not `/abort`). Two intents share
+ * the prefix — a mistyped control command and an attempt to invoke a name — and they are answered
+ * differently:
+ *
+ * - a mistyped slash gets the certain half NOW (a leading `/` is reserved here, whatever the token
+ *   turns out to be), because waiting on a remote read that can be slow or fail would leave the
+ *   input unanswered; it deliberately does not pre-judge the token as unknown — the read may be
+ *   about to prove it names a real skill;
+ * - `/commands` prints nothing first: its whole answer IS the read, and a placeholder is noise;
+ * - the enumeration answers `/commands` ONLY — dumping every skill at a mistyped `/aboort` answers
+ *   an intent the typo did not express.
+ *
+ * Names print BARE: this composer cannot expand `/name` (the data plane takes prompts as text), so
+ * printing them with a slash would invite the user straight back into this branch. Returns the
+ * promise for the remote half, so a caller (or a test) can await the second line.
+ */
+export async function answerSlashInput(trimmed, control, println) {
+    // The first WORD is the token: slash input naturally carries arguments (`/triage my inbox`), and
+    // taking the whole line would answer "names nothing" for a name the user did give.
+    const word = trimmed.slice(1).split(/\s+/)[0] ?? "";
+    const listing = word === "commands";
+    if (!listing)
+        println("[a leading / is reserved — /abort stops the run, /commands lists what this agent defines]");
+    let commands;
+    try {
+        commands = await control.commands();
+    }
+    catch (error) {
+        println(`[command list unavailable: ${error}]`);
+        return;
+    }
+    if (listing) {
+        // `description` is what makes a listing usable — a bare name tells the author nothing they did
+        // not already know from the directory.
+        const listed = commands.map((c) => (c.description ? `${c.name} — ${c.description}` : c.name));
+        println(listed.length ? `[this agent defines: ${listed.join("; ")}]` : "[this agent defines no names]");
+        return;
+    }
+    const hit = commands.find((c) => c.name === word);
+    println(hit
+        ? `[${hit.name} is a ${hit.source}${hit.description ? ` — ${hit.description}` : ""}; name it in a normal message, without the /]`
+        : `[/${word} names nothing this agent defines]`);
+}
 /**
  * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
  * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager

package/dist/cli/commands/dev.js

@@ -6,7 +6,7 @@
 import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
 import { loadDotEnv } from "../../env.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
@@ -91,5 +91,5 @@ function reportAgentsSkillsTools(a) {
     }
     reportToolCollisions(a.toolCollisions);
     reportModuleLoadFailures(a.toolFailures);
-    reportDefinitionWarnings(a.definition.collisions, a.definition.diagnostics);
+    reportFindingsIfChanged(a.definition.dir, a.definition);
 }

package/dist/cli/commands/info.js

@@ -6,7 +6,7 @@ import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModelSpec, reso
 import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { log } from "../../log.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
@@ -111,5 +111,5 @@ export async function runInfo(dirArg, opts) {
     reportModuleLoadFailures(sched.failures);
     if (tools.error)
         log.warn(`[fastagent] ${tools.error}`);
-    reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    reportFindingsIfChanged(definition.dir, definition);
 }

package/dist/cli/commands/start.js

@@ -9,7 +9,7 @@ import { loadDotEnv } from "../../env.js";
 import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
 import { resolveSecretsDir, workspaceHint } from "../../paths.js";
 import { isUnderDir } from "../../engines/pi/definition.js";
-import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { log, setLogLevel } from "../../log.js";
 import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.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";
@@ -80,7 +81,7 @@ export async function runStart(dirArg, opts) {
         log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
             `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
     }
-    reportDefinitionWarnings(definition.collisions, definition.diagnostics);
+    reportFindingsIfChanged(definition.dir, definition);
     // AgentCore Runtime posture (FASTAGENT_AGENTCORE=1, set by the generated deploy artifacts): the
     // adapter (POST /invocations + GET /ping) is the container's only reachable surface, and cron
     // slots arrive from the external clock through it — so no resident cron timers. In particular,
@@ -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/program.js

@@ -457,8 +457,8 @@ const logs = {
     name: "logs",
     summary: "find and tail a deployed host's application logs",
     description: "Find the CloudWatch log group for the AgentCore stack derived from dir, then run aws logs tail. " +
-        "The default Runtime source selects only [runtime-logs], so application stdout/stderr is not mixed " +
-        "with OTEL/spans in the same AWS log group; the forwarder source shows Lambda ingress transport logs.",
+        "The default Runtime source shows the agent process's own stdout/stderr; the forwarder source shows " +
+        "the Lambda ingress transport logs.",
     args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, DIR_ARG],
     flags: [
         { flags: "--source <source>", description: "agentcore log source: runtime (default) or forwarder" },

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