@fastagent-sh/fastagent 0.19.0 → 0.21.0

package/dist/channels/feishu/register-webhook.d.ts

@@ -1,9 +1,10 @@
-import type { RegistrationOutcome } from "../registration.ts";
+import { type RegistrationOutcome } from "../registration.ts";
 import { type FeishuCloudKind } from "./cloud.ts";
 /**
  * Register `<baseUrl>/<kind>` as the app's event Request URL (webhook mode). Missing credentials print
- * the manual instruction instead of failing. `opts` exist for tests: timeouts + `apiBase` (a fake
- * platform — production derives it from the kind).
+ * the manual instruction instead of failing. `opts` carries the attempt budget — `--tunnel` takes the
+ * default, `deploy --run` passes `DEPLOY_REGISTRATION_ATTEMPTS` (a host starts slower than a tunnel) —
+ * plus `apiBase`, which is a test's fake platform (production derives it from the kind).
  *
  * Reports its outcome as a {@link RegistrationOutcome} fact; gating policy belongs to the caller.
  */
@@ -12,8 +13,7 @@ interface FeishuManualRegistration {
     requestUrl: string;
 }
 export interface RegisterFeishuWebhookOptions {
-    readyTimeoutMs?: number;
-    readyIntervalMs?: number;
+    attempts?: number;
     retryMs?: number;
     apiBase?: string;
     /** Manual fallback after a definitive config error or exhausted retries. Local dev opens this App. */

package/dist/channels/feishu/register-webhook.js

@@ -7,20 +7,21 @@
  * Mechanism: the application-v7 config PATCH (`updateEventSubscription`) flips the app's event
  * subscription to webhook mode and points it at `<baseUrl>/<kind>`. Two properties make this the full
  * telegram-setWebhook parity: the platform applies a request-URL change IMMEDIATELY (no version
- * publish), and it VERIFIES the URL with a url_verification challenge during the PATCH — which is why
- * this waits for `<baseUrl>/health` to serve first (the same readiness race the telegram registrar
- * fixes). Requires the `application:application:patch` scope (field-tested: `self_manage` does NOT
- * cover this PATCH) — `add feishu` requests it at creation via addons; without it the PATCH fails
- * visibly and the manual console instruction is printed.
+ * publish), and it VERIFIES the URL with a url_verification challenge during the PATCH — which makes
+ * the PATCH its own readiness probe, retried below. (It used to poll `<baseUrl>/health` from here
+ * first; that asked whether THIS machine could reach a freshly minted hostname, which is routinely
+ * false for a minute or more while the platform reaches it fine — #421.) Requires the
+ * `application:application:patch` scope (field-tested: `self_manage` does NOT cover this PATCH) —
+ * `add feishu` requests it at creation via addons; without it the PATCH fails visibly and the manual
+ * console instruction is printed.
  *
  * CLOUD LAG: the application-v7 config API exists on open.feishu.cn but (as of 2026-07) is NOT
  * deployed on open.larksuite.com — the route 404s there. The registrar still attempts it (the day the
  * platform ships it, registration starts working with no change here) and names the real cause in the
  * fallback instead of blaming the app's scopes.
  */
-import { setTimeout as sleep } from "node:timers/promises";
 import { log } from "../../log.js";
-import { waitForHealth } from "../wait-health.js";
+import { retryWhile } from "../registration.js";
 import { cloudFor } from "./cloud.js";
 import { createFeishuApi, isFeishuConfigApiMissing, isTransientFeishuRegistrationError } from "./feishu-api.js";
 export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
@@ -35,16 +36,6 @@ export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
         log.info(`[fastagent] ${kind}: set ${envPrefix}_APP_ID + ${envPrefix}_APP_SECRET in .env, then re-run to auto-register. Or ${manual}`);
         return "manual";
     }
-    // Align registration with the server actually serving: the PATCH triggers the platform's
-    // url_verification challenge against requestUrl — registering before /health serves would fail.
-    log.info(`[fastagent] ${kind}: waiting for ${baseUrl} to be reachable before registering the event URL…`);
-    const ready = await waitForHealth(`${baseUrl}/health`, opts.readyTimeoutMs ?? 120_000, opts.readyIntervalMs ?? 3_000);
-    if (!ready) {
-        // Terminal for this run (registration will not be retried) — error, not warn: the event URL is NOT
-        // registered and the operator must act. Same taxonomy as the permanent PATCH failure below.
-        log.error(`[fastagent] ${kind}: ${baseUrl}/health did not come up in time — the app may still be starting. ${manual}`);
-        return "failed";
-    }
     const api = createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret });
     const consoleUrl = `${apiBase}/app/${encodeURIComponent(appId)}/event`;
     const versionUrl = `${apiBase}/app/${encodeURIComponent(appId)}/version`;
@@ -61,46 +52,41 @@ export async function registerFeishuWebhook(baseUrl, kind, opts = {}) {
             log.warn(`[fastagent] ${kind}: could not open Events & Callbacks: ${String(callbackError)}`);
         }
     };
-    // Reachable → register. The PATCH is the real probe (same lesson as the token bootstrap): the
-    // platform verifies request_url with a challenge DURING the call, and a fresh tunnel's edge can be
-    // reachable from here while the platform's own path still lags — its 210042 "request_url validation
-    // failed" is therefore retried with backoff, alongside transient network errors. Only a permanent
-    // config error (missing scope, app under review, the intl 404) is reported once with the manual path.
-    const attempts = 8;
-    for (let attempt = 0; attempt < attempts; attempt++) {
-        if (attempt > 0)
-            await sleep(opts.retryMs ?? 10_000);
-        try {
-            await api.updateEventSubscription(appId, { subscriptionType: "webhook", requestUrl });
-            log.info(`[fastagent] ${kind}: event Request URL registered → ${requestUrl}`);
-            // Field-tested: a URL change applies immediately, but the MODE flip (the template's long
-            // connection → webhook) only takes effect when a version is published — the dispatcher serves
-            // the published snapshot, and version publishing has no open API. One console click, once.
-            log.info(`[fastagent] ${kind}: if messages do not arrive, publish a version (one click, prompted) — the switch to webhook mode takes effect on publish: ${versionUrl}`);
-            return "registered";
-        }
-        catch (e) {
-            // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is
-            // live on open.feishu.cn but not yet on open.larksuite.com. Name that — "check your scopes"
-            // would send the operator hunting for a problem they cannot fix.
-            if (isFeishuConfigApiMissing(e)) {
-                log.warn(`[fastagent] ${kind}: this cloud (${apiBase}) returned HTTP 404 for the app-config API — ` +
-                    `manual registration is required`);
-                manualRegistration();
-                return "manual"; // that cloud has no config API — the manual path is the norm there
-            }
-            if (!isTransientFeishuRegistrationError(e)) {
-                log.error(`[fastagent] ${kind}: could not register the event URL (${String(e)}). ` +
-                    `The app may lack the "application:application:patch" scope (console → Permissions) or be under review; manual registration is available below.`);
-                manualRegistration();
-                return "failed";
-            }
+    // The PATCH is the probe (same lesson as the token bootstrap): the platform verifies request_url
+    // with a challenge DURING the call, so its 210042 "request_url validation failed" is the readiness
+    // signal and is retried with backoff, alongside transient network errors. Only a permanent config
+    // error (missing scope, app under review, the intl 404) is reported once with the manual path.
+    try {
+        await retryWhile(() => api.updateEventSubscription(appId, { subscriptionType: "webhook", requestUrl }), isTransientFeishuRegistrationError, {
+            attempts: opts.attempts,
+            retryMs: opts.retryMs,
+            onRetry: ({ attempt, attempts }) => log.info(`[fastagent] ${kind}: the platform cannot verify ${requestUrl} yet (attempt ${attempt}/${attempts}); retrying…`),
+        });
+        log.info(`[fastagent] ${kind}: event Request URL registered → ${requestUrl}`);
+        // Field-tested: a URL change applies immediately, but the MODE flip (the template's long
+        // connection → webhook) only takes effect when a version is published — the dispatcher serves
+        // the published snapshot, and version publishing has no open API. One console click, once.
+        log.info(`[fastagent] ${kind}: if messages do not arrive, publish a version (one click, prompted) — the switch to webhook mode takes effect on publish: ${versionUrl}`);
+        return "registered";
+    }
+    catch (e) {
+        // A 404 on the config route is the CLOUD lagging, not this app's configuration: the v7 API is
+        // live on open.feishu.cn but not yet on open.larksuite.com. Name that — "check your scopes"
+        // would send the operator hunting for a problem they cannot fix. It stays WARN: on that cloud the
+        // manual path is the known norm, not an exceptional failure.
+        if (isFeishuConfigApiMissing(e)) {
+            log.warn(`[fastagent] ${kind}: this cloud (${apiBase}) returned HTTP 404 for the app-config API — ` +
+                `manual registration is required`);
+            manualRegistration();
+            return "manual"; // that cloud has no config API — the manual path is the norm there
         }
+        // Exhausted retries end in the same state as a permanent config error (event URL not registered,
+        // manual action required) — report at the same level.
+        log.error(isTransientFeishuRegistrationError(e)
+            ? `[fastagent] ${kind}: the platform could not verify ${requestUrl} after retries — manual registration is required`
+            : `[fastagent] ${kind}: could not register the event URL (${String(e)}). ` +
+                `The app may lack the "application:application:patch" scope (console → Permissions) or be under review; manual registration is available below.`);
+        manualRegistration();
+        return "failed";
     }
-    // Exhausted retries end in the same state as a permanent error (event URL not registered, manual
-    // action required) — report at the same level. The cloud-lag 404 above stays warn: on that cloud the
-    // manual path is the known norm, not an exceptional failure.
-    log.error(`[fastagent] ${kind}: registration still failing after retries — manual registration is required`);
-    manualRegistration();
-    return "failed";
 }

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

@@ -1,58 +1,8 @@
 import { defineTool, z } from "@fastagent-sh/fastagent";
+import { feishuTransport } from "@fastagent-sh/fastagent/feishu";
 
-// Send a message to a Feishu chat. In a CHAT turn the channel delivers the reply itself — this
-// tool is for turns NO channel is carrying: a scheduled turn (schedules/<name>.ts) or a self-scheduled
-// wake-up, whose plain reply is not delivered anywhere. The chatId comes from the [feishu: chat …]
-// context line in a chat turn; a scheduled turn has no such line, so the schedule's prompt must name
-// the target chat id. tools/ is auto-discovered.
-
-// Embedded copy of the channel transport's discipline: a timeout so a wedged connection can't hang
-// the tool call (and the turn), named errors, and success gated on the body's own code===0.
-// Deliberately NO rate-limit retry — a tool error goes back to the agent, which can decide to retry;
-// fail-fast beats a silently sleeping tool.
-const BASE = "https://open.feishu.cn";
-
-async function callApi(path: string, body: unknown, token?: string): Promise<Record<string, unknown>> {
-  let res: Response;
-  let raw: string;
-  try {
-    res = await fetch(`${BASE}${path}`, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-        ...(token ? { authorization: `Bearer ${token}` } : {}),
-      },
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(30_000),
-    });
-    raw = await res.text();
-  } catch (e) {
-    throw new Error(`feishu ${path}: ${String(e)}`, { cause: e });
-  }
-  let data: { code?: number; msg?: string; [k: string]: unknown };
-  try {
-    data = JSON.parse(raw) as typeof data;
-  } catch {
-    data = {};
-  }
-  if (!res.ok || data.code !== 0) {
-    throw new Error(`feishu ${path} failed: ${res.status} ${data.msg ?? "response was not the expected JSON"}`);
-  }
-  return data;
-}
-
-async function tenantToken(): Promise<string> {
-  const appId = process.env.FEISHU_APP_ID;
-  const appSecret = process.env.FEISHU_APP_SECRET;
-  if (!appId || !appSecret) throw new Error("FEISHU_APP_ID / FEISHU_APP_SECRET are not set");
-  const data = await callApi("/open-apis/auth/v3/tenant_access_token/internal", {
-    app_id: appId,
-    app_secret: appSecret,
-  });
-  const token = data.tenant_access_token;
-  if (typeof token !== "string") throw new Error("feishu tenant_access_token: response carried no token");
-  return token;
-}
+// Proactive delivery uses the mounted channel's credentials, gateway and token cache. With no
+// channel mounted (fire/invoke/tool), it reads FEISHU_APP_ID / FEISHU_APP_SECRET from the environment.
 
 export default defineTool({
   description:
@@ -70,23 +20,18 @@ export default defineTool({
     text: z.string().optional().describe("plain text message to send"),
     markdown: z.string().optional().describe("markdown to send as a card"),
   }),
-  async execute({ chatId, text, markdown }) {
+  async execute({ chatId, text, markdown }, ctx) {
     if ((text === undefined) === (markdown === undefined)) {
       throw new Error("pass exactly one of `text` (plain) or `markdown` (a card)");
     }
-    const token = await tenantToken();
-    const msg =
-      text !== undefined
-        ? { msg_type: "text", content: JSON.stringify({ text }) }
-        : {
-            msg_type: "interactive",
-            // An inline static card: one markdown element, no entity/streaming machinery needed here.
-            content: JSON.stringify({
-              schema: "2.0",
-              body: { elements: [{ tag: "markdown", content: markdown }] },
-            }),
-          };
-    await callApi(`/open-apis/im/v1/messages?receive_id_type=chat_id`, { receive_id: chatId, ...msg }, token);
+    const api = feishuTransport(ctx.cwd);
+    if (text !== undefined) await api.sendText({ chatId }, text);
+    else {
+      await api.sendMessage(chatId, "interactive", JSON.stringify({
+        schema: "2.0",
+        body: { elements: [{ tag: "markdown", content: markdown }] },
+      }));
+    }
     return `sent ${text !== undefined ? "message" : "card"} to chat ${chatId}`;
   },
 });

package/dist/channels/feishu/setup-mode.d.ts

@@ -4,6 +4,36 @@ export type FeishuSubscriptionMode = "webhook" | "websocket";
  * runtime remains capability-driven because the platform, not channel source, decides which events
  * are delivered. */
 export type FeishuGroupBehavior = "context" | "mentions";
+/**
+ * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and
+ * adding a scope to the app draft during context-aware group setup.
+ *
+ * Requested at creation for BOTH ingress modes, though only webhook uses it on day one. A WebSocket
+ * app that later wants webhook delivery cannot acquire it in passing: changing mode is a migration
+ * the CLI deliberately refuses to perform (`resolveIngress`), so the app would have to be recreated
+ * or the scope added by hand in the console after a failed PATCH. It is not a data scope — it reads
+ * and writes this app's own configuration — so carrying it costs an app nothing and keeps the one
+ * door open that the alternative nails shut.
+ */
+export declare const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
+/** The one event an agent app cannot serve without: an inbound message. */
+export declare const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
+/**
+ * What a created app carries on top of the platform's agent template, for EITHER ingress — the
+ * `addons` merged onto the confirm page. Here rather than inline at the call site because it is a
+ * policy decision (which capabilities an app is born with), and the CLI layer that requests it is
+ * terminal wiring with no seam to test through.
+ */
+export declare function feishuAppAddons(): {
+    scopes: {
+        tenant: string[];
+    };
+    events: {
+        items: {
+            tenant: string[];
+        };
+    };
+};
 /** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
 export declare const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
 /** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).

package/dist/channels/feishu/setup-mode.js

@@ -1,3 +1,29 @@
+/**
+ * Configuring THIS app: what every v7 config PATCH needs — registering a webhook Request URL, and
+ * adding a scope to the app draft during context-aware group setup.
+ *
+ * Requested at creation for BOTH ingress modes, though only webhook uses it on day one. A WebSocket
+ * app that later wants webhook delivery cannot acquire it in passing: changing mode is a migration
+ * the CLI deliberately refuses to perform (`resolveIngress`), so the app would have to be recreated
+ * or the scope added by hand in the console after a failed PATCH. It is not a data scope — it reads
+ * and writes this app's own configuration — so carrying it costs an app nothing and keeps the one
+ * door open that the alternative nails shut.
+ */
+export const FEISHU_APP_CONFIG_SCOPE = "application:application:patch";
+/** The one event an agent app cannot serve without: an inbound message. */
+export const FEISHU_MESSAGE_RECEIVE_EVENT = "im.message.receive_v1";
+/**
+ * What a created app carries on top of the platform's agent template, for EITHER ingress — the
+ * `addons` merged onto the confirm page. Here rather than inline at the call site because it is a
+ * policy decision (which capabilities an app is born with), and the CLI layer that requests it is
+ * terminal wiring with no seam to test through.
+ */
+export function feishuAppAddons() {
+    return {
+        scopes: { tenant: [FEISHU_APP_CONFIG_SCOPE] },
+        events: { items: { tenant: [FEISHU_MESSAGE_RECEIVE_EVENT] } },
+    };
+}
 /** The sensitive tenant scope behind both bare replies in the agent's threads and group context buffering. */
 export const FEISHU_GROUP_CONTEXT_SCOPE = "im:message.group_msg";
 /** Reading a QUOTED message by id, so an ask carries what it replies to (participant-model.md §8).

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

@@ -0,0 +1,10 @@
+import { type FeishuCloudKind } from "./cloud.ts";
+import { type FeishuApi } from "./feishu-api.ts";
+/** The delivery methods a proactive sender needs. */
+export type FeishuTransport = Pick<FeishuApi, "sendText" | "sendMessage">;
+/** A remount replaces the transport; separate clouds can share one agent state root. */
+export declare function registerFeishuApi(stateRoot: string, kind: FeishuCloudKind, api: FeishuApi): void;
+/** Resolve the Feishu transport for a tool's workspace (`ctx.cwd`). */
+export declare function feishuTransport(cwd: string): FeishuTransport;
+/** Resolve the Lark transport for a tool's workspace (`ctx.cwd`). */
+export declare function larkTransport(cwd: string): FeishuTransport;

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

@@ -0,0 +1,38 @@
+/** The mounted channel and proactive tools share credentials, token cache, gateway and retry policy. */
+import { findAgentDir, resolveStateRoot } from "../../paths.js";
+import { cloudFor } from "./cloud.js";
+import { createFeishuApi } from "./feishu-api.js";
+const byKind = {
+    feishu: new Map(),
+    lark: new Map(),
+};
+/** A remount replaces the transport; separate clouds can share one agent state root. */
+export function registerFeishuApi(stateRoot, kind, api) {
+    byKind[kind].set(stateRoot, api);
+}
+function cloudTransport(cwd, kind) {
+    // Embedded senders may use a bare definition directory or an independent workspace.
+    const stateRoot = resolveStateRoot(findAgentDir(cwd) ?? cwd);
+    const transports = byKind[kind];
+    let api = transports.get(stateRoot);
+    if (!api) {
+        // fire/invoke/tool do not mount channels, so their credentials come from the agent's environment.
+        const { apiBase, envPrefix } = cloudFor(kind);
+        const appId = process.env[`${envPrefix}_APP_ID`];
+        const appSecret = process.env[`${envPrefix}_APP_SECRET`];
+        if (!appId || !appSecret) {
+            throw new Error(`${envPrefix}_APP_ID / ${envPrefix}_APP_SECRET are not set and no ${kind} channel is mounted`);
+        }
+        api = createFeishuApi({ kind, baseUrl: apiBase, appId, appSecret });
+        transports.set(stateRoot, api);
+    }
+    return api;
+}
+/** Resolve the Feishu transport for a tool's workspace (`ctx.cwd`). */
+export function feishuTransport(cwd) {
+    return cloudTransport(cwd, "feishu");
+}
+/** Resolve the Lark transport for a tool's workspace (`ctx.cwd`). */
+export function larkTransport(cwd) {
+    return cloudTransport(cwd, "lark");
+}

package/dist/channels/http.d.ts

@@ -13,14 +13,6 @@ import type { Agent } from "../agent.ts";
 /** Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's
  *  dispatch imports it), so the two caps cannot drift apart. */
 export declare const MAX_BODY_BYTES: number;
-/** SSE comment-heartbeat interval, shared by every SSE surface (the control events route imports
- *  it, and the remote client sizes its dead-connection watchdog as a multiple of it). */
-export declare const SSE_HEARTBEAT_MS = 30000;
-/** The emitting half of the heartbeat contract (the client watchdog is the other): starts the
- *  `: ping` comment interval on an SSE stream controller and returns its stop function — ONE
- *  implementation for every SSE surface, so the emission side cannot regress on one route while
- *  the shared client watchdog keeps assuming it. Self-stops if the controller is already closed. */
-export declare function sseHeartbeat(controller: ReadableStreamDefaultController<Uint8Array>): () => void;
 /** A valid example request body for the invoke handler — lives HERE, next to the shape check it must
  *  satisfy, so the CLI's "try it" hint can't drift from the protocol. */
 export declare const INVOKE_EXAMPLE_BODY = "{\"session\":\"dev\",\"text\":\"hello\"}";

package/dist/channels/http.js

@@ -1,28 +1,9 @@
 import { readBodyCapped } from "./body.js";
 import { text } from "./respond.js";
+import { sseResponse } from "./sse.js";
 /** Request body cap (1 MiB) — shared by every Prompt-bearing wire surface (the control plane's
  *  dispatch imports it), so the two caps cannot drift apart. */
 export const MAX_BODY_BYTES = 1 << 20;
-const encoder = new TextEncoder();
-/** SSE comment-heartbeat interval, shared by every SSE surface (the control events route imports
- *  it, and the remote client sizes its dead-connection watchdog as a multiple of it). */
-export const SSE_HEARTBEAT_MS = 30_000;
-/** The emitting half of the heartbeat contract (the client watchdog is the other): starts the
- *  `: ping` comment interval on an SSE stream controller and returns its stop function — ONE
- *  implementation for every SSE surface, so the emission side cannot regress on one route while
- *  the shared client watchdog keeps assuming it. Self-stops if the controller is already closed. */
-export function sseHeartbeat(controller) {
-    const encoder = new TextEncoder();
-    const timer = setInterval(() => {
-        try {
-            controller.enqueue(encoder.encode(": ping\n\n"));
-        }
-        catch {
-            clearInterval(timer);
-        }
-    }, SSE_HEARTBEAT_MS);
-    return () => clearInterval(timer);
-}
 /** A valid example request body for the invoke handler — lives HERE, next to the shape check it must
  *  satisfy, so the CLI's "try it" hint can't drift from the protocol. */
 export const INVOKE_EXAMPLE_BODY = '{"session":"dev","text":"hello"}';
@@ -48,7 +29,7 @@ export function createInvokeHandler(agent) {
         if (typeof session !== "string" || typeof promptText !== "string") {
             return text('need { "session": string, "text": string }\n', 400);
         }
-        // ^ the request shape INVOKE_EXAMPLE_BODY (below) must keep satisfying.
+        // INVOKE_EXAMPLE_BODY must keep satisfying this request shape.
         // The OPTIONAL lineage extension (Scope): malformed values are a 400, not a silent drop — a
         // caller that sent them meant them.
         if (parentSession !== undefined && typeof parentSession !== "string") {
@@ -57,43 +38,10 @@ export function createInvokeHandler(agent) {
         if (branchHints !== undefined && !(Array.isArray(branchHints) && branchHints.every((h) => typeof h === "string"))) {
             return text('"branchHints" must be an array of strings\n', 400);
         }
-        // Take the iterator explicitly so the stream's cancel() (consumer disconnect) can return() it and
-        // run invoke's cancellation cleanup (SPEC MUST 3). pull = backpressure: the next event is produced on demand.
-        const iterator = agent
-            .invoke({
+        return sseResponse(agent.invoke({
             session,
             ...(parentSession !== undefined ? { parentSession } : {}),
             ...(branchHints !== undefined ? { branchHints } : {}),
-        }, { text: promptText })[Symbol.asyncIterator]();
-        // Heartbeats: a QUIET stream (a long tool call, no events) is normal here — remote consumers
-        // distinguish "quiet but alive" from a dead connection by byte arrival, so silence must not
-        // look identical to a black hole (SSE comments are ignored by spec-conforming parsers).
-        let stopHeartbeat = () => { };
-        const stream = new ReadableStream({
-            start(controller) {
-                stopHeartbeat = sseHeartbeat(controller);
-            },
-            async pull(controller) {
-                const { value, done } = await iterator.next();
-                if (done) {
-                    stopHeartbeat();
-                    controller.close();
-                    return;
-                }
-                controller.enqueue(encoder.encode(`data: ${JSON.stringify(value)}\n\n`));
-            },
-            async cancel() {
-                stopHeartbeat();
-                await iterator.return?.();
-            },
-        });
-        return new Response(stream, {
-            status: 200,
-            headers: {
-                "content-type": "text/event-stream",
-                "cache-control": "no-cache",
-                connection: "keep-alive",
-            },
-        });
+        }, { text: promptText }));
     };
 }

package/dist/channels/kit/attachment-path.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Attachment destination for one conversation. Never rejects an id — but the path it returns is not
+ * promised to be one the filesystem accepts: percent-encoding spends up to 9 bytes per character, so
+ * an id of ~29 CJK characters exceeds a 255-byte `NAME_MAX` and the caller's `mkdir` fails with
+ * `ENAMETOOLONG`. Left to fail there rather than truncated here: a digest suffix would buy a length
+ * no platform id approaches, at the cost of the readability this encoding exists to keep.
+ */
+export declare function attachmentPath(filesDir: string, conversationId: string | number, fileName: string): {
+    dir: string;
+    name: string;
+    path: string;
+};

package/dist/channels/kit/attachment-path.js

@@ -0,0 +1,43 @@
+/**
+ * Where an inbound attachment lands: `<filesDir>/<conversation>/<file>`.
+ *
+ * Both halves come from outside the channel, and they are NOT the same question:
+ *
+ * - The conversation is an id, and turning an arbitrary caller id into a storage name is a job this
+ *   repo already answers by ENCODING it, never by rejecting it (`piSessionId` in
+ *   engines/pi/session-store.ts, same shape: a character whitelist under a fixed prefix). An id is
+ *   the caller's — a route returning `../..` gets an odd directory, not a failed turn, because the
+ *   place to notice that id is broken is the reply it cannot deliver, not the disk.
+ * - The file name is not an id: it is read by a human and by the model, in a path this puts into the
+ *   prompt. Encoding it would cost that, so it is reduced instead — losing the odd character rather
+ *   than the readability. A leading dot survives: `.gitignore` is a name, not an escape, and nothing
+ *   lists this directory, so hiding is not a property anyone here depends on.
+ *
+ * The encoding makes containment structural rather than checked: `encodeURIComponent` emits no path
+ * separator (`/` → `%2F`, `\` → `%5C`, `:` → `%3A`), and the prefix leaves no way to spell `.`, `..`
+ * or the empty string.
+ *
+ * It is lossless for a well-formed id, so `a/b` and `a_b` are different places. Two exceptions, both
+ * outside what a platform hands over: ids differing only in malformed UTF-16 (see the substitution
+ * below), and ids differing only in case on a case-insensitive filesystem.
+ */
+import { resolve, sep } from "node:path";
+/**
+ * Attachment destination for one conversation. Never rejects an id — but the path it returns is not
+ * promised to be one the filesystem accepts: percent-encoding spends up to 9 bytes per character, so
+ * an id of ~29 CJK characters exceeds a 255-byte `NAME_MAX` and the caller's `mkdir` fails with
+ * `ENAMETOOLONG`. Left to fail there rather than truncated here: a digest suffix would buy a length
+ * no platform id approaches, at the cost of the readability this encoding exists to keep.
+ */
+export function attachmentPath(filesDir, conversationId, fileName) {
+    // A lone surrogate makes `encodeURIComponent` throw `URIError`, and this function rejecting an id
+    // is the one thing it must not do — a permanent bad id would surface as a retryable turn failure.
+    // The `u` flag matches by code point, so a valid pair (an emoji in a route's id) is left alone.
+    const id = String(conversationId).replace(/\p{Surrogate}/gu, "\uFFFD");
+    const dir = resolve(filesDir, `c-${encodeURIComponent(id)}`);
+    // The name keeps its own check because it is NOT encoded: separators go, and `resolve` settles
+    // whether what is left (`..`, a Windows `D:foo`) still lands in `dir`.
+    const cleaned = fileName.replace(/[/\\]/g, "_");
+    const name = resolve(dir, cleaned).startsWith(dir + sep) ? cleaned : "file";
+    return { dir, name, path: resolve(dir, name) };
+}

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

@@ -9,6 +9,15 @@ export declare const BUFFER_LINE_MAX_CHARS = 280;
  *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
  *  each channel's attachment collector caps against this. */
 export declare const BUFFER_ATTACH_MAX = 3;
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
+ * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
+ * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
+ *
+ * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
+ * different claim about a different place, not this block with another name.
+ */
+export declare function discussionBlock(text: string): string;
 export interface ContextBuffer<E> {
     /** Record an un-summoned message. Persists BEFORE returning (pre-ACK; see the module header). */
     push(placeKey: string, entry: E): void;

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

@@ -39,6 +39,17 @@ export const BUFFER_LINE_MAX_CHARS = 280;
  *  note, so the model never sees an attachment reference it silently cannot open. Shared policy:
  *  each channel's attachment collector caps against this. */
 export const BUFFER_ATTACH_MAX = 3;
+/**
+ * The folded discussion as it reaches the model — the prompt block, or nothing when the buffer is
+ * empty. One renderer for every channel: what the agent is told about un-summoned discussion should
+ * not depend on which chat platform delivered it, and three copies of the literal is how that drifts.
+ *
+ * A channel that folds a SECOND source (feishu's originating room) labels that one itself — it is a
+ * different claim about a different place, not this block with another name.
+ */
+export function discussionBlock(text) {
+    return text ? `[recent group discussion:\n${text}\n]\n\n` : "";
+}
 export function createContextBuffer(options) {
     const { path, label, isEntry, line } = options;
     const load = () => {

package/dist/channels/kit/signature.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The replay window every signed webhook ingress needs. A signature covers its timestamp but proves
+ * nothing about it, so without a window a captured body plus its signed headers replays forever.
+ * The window LENGTH is the caller's: it is set by the platform's own redelivery schedule, not by us.
+ */
+/**
+ * Whether a Unix-SECONDS timestamp header is within `maxAgeS` of now, in either direction (a clock
+ * ahead of ours is as suspect as one behind). Non-numeric is not fresh: the header is part of the
+ * signed material, so a value the signature commits to but this cannot read is a reason to refuse,
+ * not to wave through.
+ */
+export declare function signatureIsFresh(timestamp: string, maxAgeS: number, nowMs?: number): boolean;

package/dist/channels/kit/signature.js

@@ -0,0 +1,17 @@
+/**
+ * The replay window every signed webhook ingress needs. A signature covers its timestamp but proves
+ * nothing about it, so without a window a captured body plus its signed headers replays forever.
+ * The window LENGTH is the caller's: it is set by the platform's own redelivery schedule, not by us.
+ */
+/**
+ * Whether a Unix-SECONDS timestamp header is within `maxAgeS` of now, in either direction (a clock
+ * ahead of ours is as suspect as one behind). Non-numeric is not fresh: the header is part of the
+ * signed material, so a value the signature commits to but this cannot read is a reason to refuse,
+ * not to wave through.
+ */
+export function signatureIsFresh(timestamp, maxAgeS, nowMs = Date.now()) {
+    if (!/^\d+$/.test(timestamp))
+        return false;
+    const seconds = Number(timestamp);
+    return Number.isSafeInteger(seconds) && Math.abs(Math.floor(nowMs / 1000) - seconds) <= maxAgeS;
+}

package/dist/channels/kit/stop-command.js

@@ -21,16 +21,16 @@ export async function dispatchStop(control, session, label) {
     if (!control)
         return STOP_UNAVAILABLE_NOTICE;
     try {
-        const result = await control.dispatch(session, { type: "abort" });
+        const result = await control.sessions.get(session).abort();
         if (result.ok)
             return STOPPED_NOTICE;
         if (result.error.code === NO_ACTIVE_RUN_CODE)
             return NOTHING_RUNNING_NOTICE;
-        log.warn(`${label} stop dispatch rejected for ${session}: ${result.error.code} — ${result.error.message}`);
+        log.warn(`${label} stop rejected for ${session}: ${result.error.code} — ${result.error.message}`);
         return `⚠️ Could not stop (${result.error.code}).`;
     }
     catch (error) {
-        log.warn(`${label} stop dispatch failed for ${session}: ${String(error)}`);
+        log.warn(`${label} stop failed for ${session}: ${String(error)}`);
         return "⚠️ Could not stop — see the server logs.";
     }
 }

package/dist/channels/kit/tasks.d.ts

@@ -4,4 +4,4 @@ export interface TaskTracker {
     /** Resolves when every currently-tracked task has settled. */
     drain(): Promise<void>;
 }
-export declare function createTaskTracker(): TaskTracker;
+export declare function createTaskTracker(label: string): TaskTracker;