@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/dist/channels/kit/preview-kit.js

@@ -1,28 +1,21 @@
 import { truncateCodePointPrefix, truncateCodePointSuffix } from "./text.js";
-/** The customer-facing default: neutral, no leaked internals. Differentiate on retryability and always
- *  offer a next step (Slack agent-design: never leave the user with a dead-end "something went wrong").
- *  The non-retryable branch keeps the "something went wrong" phrase deliberately — it is neutral (we only
- *  know a boolean, never the specific limitation) and shared verbatim across channels. */
+/** The customer-facing default: neutral, no leaked internals. */
 export function defaultErrorMessage(failed) {
     return failed.retryable
         ? "⚠️ Temporary problem — please try again in a moment."
         : "⚠️ Sorry, something went wrong. Try rephrasing, or check I have access to what you need.";
 }
-/** Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying`
- *  event): neutral, no leaked internals — the reason stays in operator logs. */
+/**
+ * Customer-facing live-preview line for an engine-internal retry backoff (the advisory `retrying` event): neutral, no
+ * leaked internals — the reason stays in operator logs.
+ */
 export const RETRY_NOTICE = "⏳ Temporary problem — retrying…";
 /** The placeholder shown before any reasoning/tool/text arrives. */
 export const THINKING_PLACEHOLDER = "💭 Thinking…";
 export function createTurnView() {
     return { thinking: "", tools: [], toolById: new Map(), answer: "", retrying: false };
 }
-/**
- * Apply one event to the view state. Returns true when the view changed (the caller repaints).
- * This is the ONE place the shared view rules live: tool labels are humanized with a compact arg
- * summary, and any progress event closes an open retry notice (a stale "retrying" line must never
- * outlive actual progress). Terminal events only close the notice — they are the caller's business.
- */
-export function applyTurnEvent(view, e) {
+export function applyTurnEvent(view, e, now = Date.now()) {
     const closedRetry = view.retrying && e.type !== "retrying";
     if (closedRetry)
         view.retrying = false;
@@ -30,7 +23,7 @@ export function applyTurnEvent(view, e) {
         case "text":
             view.answer += e.delta;
             if (view.answerSince === undefined && view.answer.trim() !== "")
-                view.answerSince = Date.now();
+                view.answerSince = now;
             return true;
         case "thinking":
             view.thinking += e.delta;
@@ -61,25 +54,19 @@ const TOOL_MARK = { running: "…", ok: "✓", error: "✗" };
 export function toolLines(view) {
     return view.tools.map((t) => `🔧 ${t.label} ${TOOL_MARK[t.status]}`).join("\n");
 }
-/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe.
- *  Process, not the answer — renderers show it live only, never in the persisted final message. */
+/** The reasoning peek: the most recent tail of the (growing) reasoning, one line, code-point safe. */
 export function thinkingLine(view, maxTail) {
     const t = view.thinking.replace(/\s+/g, " ").trim();
     return t === "" ? "" : `💭 ${truncateCodePointSuffix(t, maxTail)}`;
 }
 /**
- * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one
- * throttle window (`ageMs` — each platform passes its own pacing constant). The pump's leading-edge
- * flush would otherwise turn the very first content delta (often a lone character or unbalanced
- * markup) into its own frame — the short-reply flicker (placeholder → "O" → "OK."). Aging is
- * anchored at delta ARRIVAL (`answerSince`, set by the reducer) so an in-flight write can't skew the
- * clock, and there is deliberately NO timer at the boundary: a young answer surfaces on the next
- * content-driven pass, so a turn completing within the window delivers the final answer only.
+ * The shared answer-reveal policy: the answer stays hidden until its first delta has aged one throttle window (`ageMs`
+ * — each platform passes its own pacing constant).
  */
-export function revealedAnswer(view, ageMs) {
+export function revealedAnswer(view, ageMs, now = Date.now()) {
     if (view.answer.trim() === "" || view.answerSince === undefined)
         return "";
-    return Date.now() - view.answerSince >= ageMs ? view.answer : "";
+    return now - view.answerSince >= ageMs ? view.answer : "";
 }
 /** Compose body parts (thinking/tools/retry/answer) into one frame: skip empties, blank-line joins. */
 export function composeTurnBody(parts) {
@@ -88,71 +75,21 @@ export function composeTurnBody(parts) {
         .join("\n\n")
         .trim();
 }
-export function createPreviewPump(opts) {
-    let dirty = false;
-    let pumping = false;
-    let stopped = false;
-    let errored = false;
-    let pumpDone;
-    let wakeThrottle; // set while mid-throttle; finish() cuts it short
-    const runPump = async () => {
-        pumping = true;
-        try {
-            while (dirty && !stopped) {
-                dirty = false;
-                try {
-                    await opts.flush();
-                }
-                catch (error) {
-                    if (!errored) {
-                        errored = true;
-                        opts.onError(error);
-                    }
-                }
-                if (dirty && !stopped) {
-                    await new Promise((resolve) => {
-                        const t = setTimeout(resolve, opts.throttleMs);
-                        wakeThrottle = () => {
-                            clearTimeout(t);
-                            resolve();
-                        };
-                    });
-                    wakeThrottle = undefined;
-                }
-            }
-        }
-        finally {
-            pumping = false;
-        }
-    };
-    return {
-        touch() {
-            dirty = true;
-            if (!pumping)
-                pumpDone = runPump();
-        },
-        async finish() {
-            stopped = true;
-            wakeThrottle?.();
-            await pumpDone?.catch(() => { });
-        },
-    };
-}
-/** Max length (code points) of a tool's arg preview. Slack's native stream cannot be retracted, so
- *  this is a disclosure bound, not only a layout one. */
+/** Max length (code points) of a tool's arg preview. */
 const TOOL_ARG_MAX = 48;
 /** Max length (code points) of a humanized tool label. */
 const TOOL_NAME_MAX = 80;
-/** One-line, truncated at code-point boundaries: collapse whitespace so a multi-line command/arg
- *  stays on one line, and never tear a surrogate pair mid-emoji. */
+/**
+ * One-line, truncated at code-point boundaries: collapse whitespace so a multi-line command/arg stays on one line, and
+ * never tear a surrogate pair mid-emoji.
+ */
 function clip(s) {
     const one = s.replace(/\s+/g, " ").trim();
     return truncateCodePointPrefix(one, TOOL_ARG_MAX);
 }
 /**
- * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md`
- * rather than just `🔧 read`. Generic (a channel knows no tool schemas): show the salient value — the
- * first primitive field, conventionally the subject (path / command / query / url) — else compact JSON.
+ * A compact, human-readable preview of a tool call's args so the live view reads `🔧 read AGENTS.md` rather than just
+ * `🔧 read`.
  */
 export function summarizeToolArgs(args) {
     if (args === null || typeof args !== "object" || Array.isArray(args))
@@ -164,12 +101,9 @@ export function summarizeToolArgs(args) {
     return values.length > 0 ? clip(JSON.stringify(args)) : "";
 }
 /**
- * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool
- * does rather than expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue",
- * not "mcp__github__create_issue"). Deliberately generic and engine-neutral: it only reshapes the
- * identifier string — it never invents semantics and never exposes arguments. An `mcp__server__tool`
- * identifier becomes `server: tool`; any other identifier has its separators normalized to spaces and
- * its first letter capitalized.
+ * A plain-language label for a tool call, following Slack's agent-design guidance to name what a tool does rather than
+ * expose a raw identifier ("Create issue", not "create_issue"; "Github: create issue", not
+ * "mcp__github__create_issue").
  */
 export function humanizeToolName(name) {
     const normalize = (s) => s

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

@@ -1,12 +1,6 @@
+/** The replay window every signed webhook ingress needs. */
 /**
- * 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.
+ * 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).
  */
 export declare function signatureIsFresh(timestamp: string, maxAgeS: number, nowMs?: number): boolean;

package/dist/channels/kit/signature.js

@@ -1,13 +1,7 @@
+/** The replay window every signed webhook ingress needs. */
 /**
- * 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.
+ * 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).
  */
 export function signatureIsFresh(timestamp, maxAgeS, nowMs = Date.now()) {
     if (!/^\d+$/.test(timestamp))

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

@@ -1,6 +1,5 @@
 /** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export declare function ensureStateHome(dir: string): void;
-/** Returns `unknown` on purpose — no generic pretending otherwise: the file is an IO boundary, and the
- *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
+/** Returns `unknown` on purpose — no generic pretending otherwise. */
 export declare function loadStateFile(path: string): unknown;
 export declare function saveStateFile(path: string, value: unknown): void;

package/dist/channels/kit/state.js

@@ -1,16 +1,8 @@
 /**
- * Durable channel state for a SINGLE-PROCESS deployment (the supported production shape — no
- * cross-instance locking; two processes must not share a state dir). Small JSON files, written
- * atomically (tmp + rename), so a crash leaves the previous version on disk, never a torn file.
- * Writes are synchronous: the files are KB-sized and a write that completes BEFORE the transport ACK
- * is what makes the state actually durable (an ACKed delivery is not redelivered).
- * Channel-neutral: every stateful channel (Telegram, Feishu/Lark, Slack) derives its home from the ctx state root
- * and persists through these three primitives.
- *
- * Failure split: a CORRUPT file (bad JSON) degrades visibly — log.warn + start empty — because channel
- * state is recoverable context, not worth refusing to boot over. An unreadable file (permissions, IO)
- * is an ENVIRONMENT error the operator must fix: it throws, and construction fails loudly — booting
- * with silently-empty state would hide real data behind a config mistake.
+ * Durable channel state, with no cross-instance locking: every file here is keyed by CHANNEL KIND
+ * (`<stateRoot>/channels/<kind>/`), so what must not happen is two processes serving the SAME channel — which also
+ * means one ingress credential in two places, and no local guard can see that. Two processes serving different
+ * channels of one agent never touch the same file (docs/design/core.md, "the shipped file-backed implementations").
  */
 import { mkdirSync, readFileSync } from "node:fs";
 import { writeFileAtomic } from "../../atomic-write.js";
@@ -19,8 +11,7 @@ import { log } from "../../log.js";
 export function ensureStateHome(dir) {
     mkdirSync(dir, { recursive: true });
 }
-/** Returns `unknown` on purpose — no generic pretending otherwise: the file is an IO boundary, and the
- *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
+/** Returns `unknown` on purpose — no generic pretending otherwise. */
 export function loadStateFile(path) {
     let raw;
     try {

package/dist/channels/kit/stop-command.d.ts

@@ -1,6 +1,5 @@
 import { type SessionControl } from "../../session.ts";
 /** Bare stop word for summon-body matching (Slack/Feishu); Telegram uses its native `/stop` command. */
 export declare function isStopText(text: string): boolean;
-/** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;
- *  full details go to the operator log. */
+/** Dispatch `abort` for the session and map the outcome to the customer-facing line. */
 export declare function dispatchStop(control: SessionControl | undefined, session: string, label: string): Promise<string>;

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

@@ -1,10 +1,6 @@
 /**
- * SHARED user-facing stop command: the chat channels (telegram, feishu/lark, slack) map an explicit
- * "stop" ask onto the session control plane's `abort`. Policy decisions (design session-control.md
- * §15): the stop message is a CONTROL ACTION, never a turn (it must not queue behind the run it
- * stops); only the ACTIVE run is aborted — queued durable turns are independent asks and keep their
- * at-least-once floor; and the hub stays gated by `config.sessionControl`, so without it the command
- * degrades to a visible "not enabled" notice, never a silent ignore.
+ * SHARED user-facing stop command: the chat channels (telegram, feishu/lark, slack) map an explicit "stop" ask onto
+ * the session control plane's `abort`.
  */
 import { log } from "../../log.js";
 import { NO_ACTIVE_RUN_CODE } from "../../session.js";
@@ -14,9 +10,10 @@ export function isStopText(text) {
 }
 const STOPPED_NOTICE = "⏹ Stopped.";
 const NOTHING_RUNNING_NOTICE = "Nothing is running.";
-const STOP_UNAVAILABLE_NOTICE = "⚠️ Stop isn't enabled on this deployment (set sessionControl: true in fastagent.config).";
-/** Dispatch `abort` for the session and map the outcome to the customer-facing line. Never throws;
- *  full details go to the operator log. */
+// A serve always builds the hub, so this is only reachable when an embedder mounted a service without one — never by
+// a configuration an author can change, which is why it no longer names a setting to turn on.
+const STOP_UNAVAILABLE_NOTICE = "⚠️ Stop isn't available on this deployment.";
+/** Dispatch `abort` for the session and map the outcome to the customer-facing line. */
 export async function dispatchStop(control, session, label) {
     if (!control)
         return STOP_UNAVAILABLE_NOTICE;

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

@@ -1,5 +1,5 @@
 export interface TaskTracker {
-    /** Track one task. The caller keeps its own `.catch` — rejections must already be handled. */
+    /** Track already-started work. Rejections are logged without failing the drain. */
     track(task: Promise<unknown>): void;
     /** Resolves when every currently-tracked task has settled. */
     drain(): Promise<void>;

package/dist/channels/kit/tasks.js

@@ -1,31 +1,18 @@
-/**
- * SHARED fire-and-forget side-task tracking. Channels launch work off the request path (stop
- * feedback, DM welcomes) that must not block the transport ACK but MUST be drained on shutdown
- * (`turnsIdle`) — otherwise a reply in flight when the process exits is silently dropped. Error
- * handling stays with the caller: track() only guarantees the drain sees the task SETTLE, and settle
- * includes reject. A caller that handles its error on a separate branch (`p.catch(log); track(p)`)
- * still hands us a promise that rejects, and a drain that propagated it would fail the channel's whole
- * `turnsIdle` over one side task. A rejection that reaches us is logged — we
- * cannot tell a missing `.catch` from one on a separate branch, so the line is a visibility floor
- * rather than a diagnosis, and without it a dropped side task leaves no trace anywhere.
- */
+/** ACK-independent side-task tracking. Drains are observation hooks, not service shutdown. */
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import { portError, portJoin } from "../../effect-port.js";
 import { beginWork } from "../busy.js";
 import { log } from "../../log.js";
 export function createTaskTracker(label) {
     const tasks = new Set();
     return {
         track(task) {
-            tasks.add(task);
-            // Tracked side tasks count as process-wide in-flight work (busy.ts) — same signal the turn
-            // queue reports, read by serving surfaces that must not idle while background work runs.
             const workDone = beginWork();
-            void task
-                .finally(() => {
-                workDone();
-                tasks.delete(task);
-            })
-                .catch((error) => log.warn(`${label} side task rejected: ${String(error)}`));
+            const fiber = Effect.runFork(portJoin(() => task).pipe(Effect.asVoid, Effect.catchCause((cause) => Effect.sync(() => log.warn(`${label} side task rejected: ${String(portError(cause))}`))), Effect.ensuring(Effect.sync(workDone))));
+            tasks.add(fiber);
+            fiber.addObserver(() => tasks.delete(fiber));
         },
-        drain: () => Promise.allSettled(tasks).then(() => undefined),
+        drain: () => Effect.runPromise(Effect.asVoid(Fiber.awaitAll([...tasks]))),
     };
 }

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

@@ -1,19 +1,5 @@
-/** Pure Unicode-safe text slicing helpers shared by channel rendering paths (Feishu/Lark cards, the preview kit). JavaScript string
- * indexes are UTF-16 code units, so direct `slice()` can tear a surrogate pair and send replacement
- * characters after JSON/UTF-8 encoding. These helpers only cut at Unicode code-point boundaries. */
-/**
- * How much of a replied-to message is quoted back into a prompt.
- *
- * A referent is the exact text the asker is pointing AT, not a summary of it, so the bound is a
- * fidelity bound: it must clear the largest message a chat platform will accept (Telegram's 4096 is
- * the tightest of ours) or a perfectly legal message loses its tail and the agent answers about text
- * it cannot see — silently. Past that point it is only a guard against a pathological message on a
- * platform with no practical cap. One constant for every channel: the failure this replaces was two
- * channels picking their own number and drifting 14x apart.
- *
- * Distinct from a context-buffer line (see BUFFER_LINE_MAX_CHARS), which is a digest competing for a
- * shared budget — different job, different unit, must not share a number.
- */
+/** Pure Unicode-safe text slicing helpers shared by channel rendering paths (Feishu/Lark cards, the preview kit). */
+/** How much of a replied-to message is quoted back into a prompt. */
 export declare const REFERENT_MAX_CODE_POINTS = 4096;
 /** Take at most `maxPoints` Unicode code points from the start, without adding a marker. */
 export declare function codePointPrefix(text: string, maxPoints: number): string;

package/dist/channels/kit/text.js

@@ -1,19 +1,5 @@
-/** Pure Unicode-safe text slicing helpers shared by channel rendering paths (Feishu/Lark cards, the preview kit). JavaScript string
- * indexes are UTF-16 code units, so direct `slice()` can tear a surrogate pair and send replacement
- * characters after JSON/UTF-8 encoding. These helpers only cut at Unicode code-point boundaries. */
-/**
- * How much of a replied-to message is quoted back into a prompt.
- *
- * A referent is the exact text the asker is pointing AT, not a summary of it, so the bound is a
- * fidelity bound: it must clear the largest message a chat platform will accept (Telegram's 4096 is
- * the tightest of ours) or a perfectly legal message loses its tail and the agent answers about text
- * it cannot see — silently. Past that point it is only a guard against a pathological message on a
- * platform with no practical cap. One constant for every channel: the failure this replaces was two
- * channels picking their own number and drifting 14x apart.
- *
- * Distinct from a context-buffer line (see BUFFER_LINE_MAX_CHARS), which is a digest competing for a
- * shared budget — different job, different unit, must not share a number.
- */
+/** Pure Unicode-safe text slicing helpers shared by channel rendering paths (Feishu/Lark cards, the preview kit). */
+/** How much of a replied-to message is quoted back into a prompt. */
 export const REFERENT_MAX_CODE_POINTS = 4096;
 /** Take at most `maxPoints` Unicode code points from the start, without adding a marker. */
 export function codePointPrefix(text, maxPoints) {
@@ -27,29 +13,35 @@ export function codePointPrefix(text, maxPoints) {
     }
     return out.join("");
 }
-/** Ellipsize from the right while keeping the result within `maxPoints` Unicode code points. */
-export function truncateCodePointPrefix(text, maxPoints, marker = "…") {
+/**
+ * How much of `text` survives beside `marker`, or the finished answer when the marker alone decides it: nothing to
+ * cut, no room at all, or room for less than the marker. Both truncations answer those three the same way, so they
+ * are decided once.
+ */
+function budget(text, maxPoints, marker) {
     const points = Array.from(text);
     if (points.length <= maxPoints)
-        return text;
+        return { done: text };
     if (maxPoints <= 0)
-        return "";
+        return { done: "" };
     const markerPoints = Array.from(marker);
     if (markerPoints.length >= maxPoints)
-        return markerPoints.slice(0, maxPoints).join("");
-    return `${points.slice(0, maxPoints - markerPoints.length).join("")}${marker}`;
+        return { done: markerPoints.slice(0, maxPoints).join("") };
+    return { points, keep: maxPoints - markerPoints.length };
+}
+/** Ellipsize from the right while keeping the result within `maxPoints` Unicode code points. */
+export function truncateCodePointPrefix(text, maxPoints, marker = "…") {
+    const fit = budget(text, maxPoints, marker);
+    if ("done" in fit)
+        return fit.done;
+    return `${fit.points.slice(0, fit.keep).join("")}${marker}`;
 }
 /** Ellipsize from the left while keeping the result within `maxPoints` Unicode code points. */
 export function truncateCodePointSuffix(text, maxPoints, marker = "…") {
-    const points = Array.from(text);
-    if (points.length <= maxPoints)
-        return text;
-    if (maxPoints <= 0)
-        return "";
-    const markerPoints = Array.from(marker);
-    if (markerPoints.length >= maxPoints)
-        return markerPoints.slice(0, maxPoints).join("");
-    return `${marker}${points.slice(points.length - (maxPoints - markerPoints.length)).join("")}`;
+    const fit = budget(text, maxPoints, marker);
+    if ("done" in fit)
+        return fit.done;
+    return `${marker}${fit.points.slice(fit.points.length - fit.keep).join("")}`;
 }
 /** Largest code-point-aligned prefix whose UTF-8 encoding fits `maxBytes`. */
 export function utf8Prefix(text, maxBytes) {

package/dist/channels/kit/thread-participants.d.ts

@@ -1,25 +1,12 @@
 export interface ThreadParticipants {
     /**
-     * The participant model's summon rule (docs/design/participant-model.md §3): does a bare message in
-     * this thread address the agent? True where it takes part AND no second human has been heard. Lives
-     * here rather than in each channel because it is one rule over one store — `<= 1` is an easy edge to
-     * get wrong twice, and "a second human restores the mention requirement" must have one place to change.
+     * The participant model's summon rule (docs/design/participant-model.md §3): does a bare message in this thread
+     * address the agent?
      */
     admitsBareMessage(key: string): boolean;
-    /**
-     * Has the agent answered into this thread before — the "first answered turn" fact
-     * (participant-model.md §8), unlike {@link ThreadParticipants.admitsBareMessage} which also weighs
-     * the second-human rule. An evicted record answers false (this store is a cache — see the header),
-     * so gate a repeatable read on it, never a durable claim.
-     */
+    /** Has the agent answered into this thread before. */
     agentSpokeIn(key: string): boolean;
-    /**
-     * Merge in what was just heard. Idempotent; a failed write is a warning, never a failed delivery.
-     *
-     * The parameter only admits values the store can honour: observations accumulate, so `agentSpoke`
-     * can be set but never cleared and `humans` unions. Passing `false` would compile and do nothing,
-     * so the type refuses it — "never shed" is an invariant, not a convention.
-     */
+    /** `agentSpoke?: true` and not `boolean`: observations only ever accumulate, so there is no "un-speak" to pass. */
     merge(key: string, heard: {
         humans?: string[];
         agentSpoke?: true;

package/dist/channels/kit/thread-participants.js

@@ -1,45 +1,12 @@
 /**
- * SHARED: who the agent has HEARD in a group thread — the sole input to the participant model's summon
- * rule. **The derivation lives in docs/design/participant-model.md §3** (why the rule is defined over
- * observation rather than the thread's true membership, what the weaker claim costs in both
- * directions, and why recording is never gated on configuration). Repeating it here would mean two
- * copies to keep true; what follows is only what a caller of this module must not get wrong.
- *
- * - **The key MUST be the string the session uses.** A record here is a claim about that session's
- *   memory, so the two cannot be keyed independently — including the channel brand
- *   (`feishu:<chat>:<thread>`, `slack:<team>:<channel>:<thread_ts>`). This file is already per-channel
- *   and would not need the prefix, but SESSION ids share one namespace across every channel in a
- *   deployment, so dropping it would key participation to a session that is not the one that answered.
- * - **Write both halves under one condition**, and gate that condition on STRUCTURAL facts only (is
- *   this a group? a thread? a human speaking?) — never on configuration, which changes while records
- *   outlive the change.
- * - **Observations only accumulate.** Nothing here sheds: no platform signals that someone stopped
- *   taking part, and the error directions are not symmetric — over-counting humans makes the agent ask
- *   to be named, under-counting makes it speak into a crowd.
- * - Keyed by `thread_id`, never a reply-chain root: Feishu's `root_id` moves with the chain, so it
- *   cannot identify a side conversation at all.
+ * SHARED: who the agent has HEARD in a group thread — the sole input to the participant model's summon rule
+ * (docs/design/participant-model.md §3). The key MUST be the string the SESSION uses: a record here is a claim about
+ * that session's memory, so the two cannot be keyed independently.
  */
 import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "./state.js";
-/** Cap on remembered threads. Losing one costs a mention to re-enter that thread, so an unbounded file
- *  buys little — and a merge that carries new information rewrites the whole map synchronously, so the
- *  map's size is the cost of every such write. What keeps that bounded is that only NEW information
- *  writes at all (a repeat speaker, or any message once MAX_HUMANS is reached, returns before
- *  persisting), and that the map stays small enough for state.ts's premise to hold — these writes land
- *  synchronously on the acceptance path, so the whole file is the cost of each one. A thousand records
- *  is tens of KB, and the records that matter (threads the agent takes part in) are far fewer than
- *  that; the dominant traffic is bystanders, which is what the eviction policy below is aimed at.
- *
- *  Eviction prefers BYSTANDER threads — ones the agent has only listened to. They are written on the
- *  same path and vastly outnumber the rest (every thread in every visible channel), yet losing one
- *  costs nothing: the summon rule refuses a thread the agent has not spoken in anyway, so the record
- *  would have to be rebuilt by the mention that admits it. Evicting purely by age would let this
- *  traffic push out the threads the agent is actively serving, silently reverting them to
- *  mention-only. This is also what makes it safe to record threads no rule currently reads (those
- *  behind a custom route, or under a posture whose summon rule is off — see the header). */
 const MAX_THREADS = 1000;
-/** Cap on remembered humans per thread. The rule only asks "have I heard a second one?", so two is
- *  already the whole answer and anything beyond it is weight nothing reads. */
+/** Cap on remembered humans per thread. */
 const MAX_HUMANS = 2;
 function isStoredParticipation(value) {
     const record = value;
@@ -87,26 +54,13 @@ export function createThreadParticipants(path, label) {
             const unchanged = previous !== undefined &&
                 previous.agentSpoke === next.agentSpoke &&
                 previous.humans.length === next.humans.length;
-            // Re-insert so insertion order is "least recently TOUCHED first" — including when nothing
-            // changed. A thread in its steady state (the agent answers, the same person keeps talking) stops
-            // carrying new information and would otherwise never refresh its position again, leaving the
-            // thread being served right now at the head of the eviction order.
-            //
-            // PROCESS-LOCAL: a touch alone never writes, and such a thread has nothing left to write (it has
-            // reached MAX_HUMANS), so the refreshed order survives only until restart. That is the right
-            // trade for a cache — persisting recency would mean a whole-map write per message — and the
-            // consequence is bounded: after a restart, eviction order among participant threads is the order
-            // they last carried new information.
+            // Re-insert so insertion order is "least recently TOUCHED first" — including when nothing changed.
             records.delete(key);
             records.set(key, next);
             if (unchanged)
                 return;
             while (records.size > MAX_THREADS) {
-                // Oldest bystander first; only when every record is a thread the agent takes part in does age
-                // alone decide. NEVER the key just merged: it is the most recently touched record, so evicting
-                // it contradicts the recency policy re-established above — and worse, a channel that records a
-                // thread's humans and its own participation in two steps would then write the second half onto
-                // an empty record, producing "answered here, heard nobody" and a permanent bare-message admit.
+                // Oldest bystander first; only when every record is a thread the agent takes part in does age alone decide.
                 let evict;
                 for (const [candidate, record] of records) {
                     if (candidate === key)
@@ -125,9 +79,8 @@ export function createThreadParticipants(path, label) {
                 saveStateFile(path, Object.fromEntries(records));
             }
             catch (error) {
-                // Cache only: memory stays correct for this process, and the whole map is rewritten on the
-                // next successful merge — so a failed write costs durability only until then, and a thread
-                // whose record is lost simply needs a mention to re-enter.
+                // Cache only: memory stays correct for this process, and the whole map is rewritten on the next successful
+                // merge.
                 log.warn(`${label} could not persist thread participation ${path}: ${String(error)}`);
             }
         },

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

@@ -0,0 +1,26 @@
+/**
+ * The one thing a chat transport needs from its CALLER, and the one place that decision is written.
+ *
+ * How a platform SIGNALS a rate limit and how long it asks us to wait are real differences and stay
+ * in each `*-api.ts` (Telegram's `parameters.retry_after`, Slack's `retry-after` header, Feishu's
+ * `code`). WHETHER A WRITE IS WORTH WAITING FOR is not a platform difference at all: it is a fact
+ * about the write, and only the caller has it.
+ *
+ * A live-preview FRAME is a full snapshot — the next frame redraws it and the terminal write
+ * supersedes it — so absorbing a rate-limit backoff for one parks the answer, and every turn queued
+ * behind it, to deliver a view nobody needs (a single 429 on a preview edit can cost ~90 s on Telegram and
+ * Slack). Such a write passes
+ * {@link DROPPABLE_FRAME}: the frame is lost, the answer is not.
+ *
+ * NOT every write. A write whose content exists only in that call keeps the default budget —
+ * Telegram's placeholder `sendMessage` (every later frame needs its id), Slack's ordered
+ * `chat.appendStream` (each append carries its own content), any terminal/settle write.
+ */
+/** Per-call transport options, for the distinction a transport cannot make for itself. Readonly:
+ *  {@link DROPPABLE_FRAME} is one process-wide instance handed to three different transports. */
+export interface CallOptions {
+    /** Rate-limit attempts this call absorbs. Omitted = the transport's default budget. */
+    readonly retries?: number;
+}
+/** A write the next one supersedes: never wait out a rate limit for it. */
+export declare const DROPPABLE_FRAME: CallOptions;

package/dist/channels/kit/transport.js

@@ -0,0 +1,20 @@
+/**
+ * The one thing a chat transport needs from its CALLER, and the one place that decision is written.
+ *
+ * How a platform SIGNALS a rate limit and how long it asks us to wait are real differences and stay
+ * in each `*-api.ts` (Telegram's `parameters.retry_after`, Slack's `retry-after` header, Feishu's
+ * `code`). WHETHER A WRITE IS WORTH WAITING FOR is not a platform difference at all: it is a fact
+ * about the write, and only the caller has it.
+ *
+ * A live-preview FRAME is a full snapshot — the next frame redraws it and the terminal write
+ * supersedes it — so absorbing a rate-limit backoff for one parks the answer, and every turn queued
+ * behind it, to deliver a view nobody needs (a single 429 on a preview edit can cost ~90 s on Telegram and
+ * Slack). Such a write passes
+ * {@link DROPPABLE_FRAME}: the frame is lost, the answer is not.
+ *
+ * NOT every write. A write whose content exists only in that call keeps the default budget —
+ * Telegram's placeholder `sendMessage` (every later frame needs its id), Slack's ordered
+ * `chat.appendStream` (each append carries its own content), any terminal/settle write.
+ */
+/** A write the next one supersedes: never wait out a rate limit for it. */
+export const DROPPABLE_FRAME = { retries: 0 };