@fastagent-sh/fastagent 0.15.0 → 0.16.1

package/dist/channels/slack/slack.d.ts

@@ -1,7 +1,6 @@
 import type { ChannelModule } from "../../host/node.ts";
 import { type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRoute, defaultSlackRoute, slackEnvelope } from "./parse.ts";
 import { type SlackFailure, type SlackRendering } from "./preview.ts";
-import { type SlackTaskDisplayMode } from "./slack-api.ts";
 export { defaultSlackRoute, slackEnvelope };
 export type { SlackEventEnvelope, SlackFailure, SlackFile, SlackMessageEvent, SlackRendering, SlackRoute };
 export interface SlackChannelOptions {
@@ -14,25 +13,19 @@ export interface SlackChannelOptions {
     clientId?: string;
     clientSecret?: string;
     botTokenExpiresAt?: number;
-    /** Direct-message policy. `threaded` (default) gives every top-level DM its own session/thread;
-     * `continuous` keeps one linear session per DM channel. */
-    directMessageSession?: "continuous" | "threaded";
-    /** Group-message context + delivery policy. `threaded` (default) gives every top-level summon its
-     * own session/thread; `continuous` keeps one session for channel-top-level turns while preserving
-     * existing Slack threads as separate root sessions. */
-    groupMessageSession?: "continuous" | "threaded";
-    /** `context` (default) admits bare replies in managed group threads and buffers unsummoned group
-     * discussion. `mentions` answers only app_mention plus DMs for an explicit least-privilege setup. */
+    /** `context` (default) subscribes to group message streams, which is what lets the channel HEAR a
+     * thread: bare replies are then admitted by the participation rule (design/participant-model.md §3),
+     * and other discussion is buffered. `mentions` answers only app_mention plus DMs for an explicit
+     * least-privilege setup. */
     groupBehavior?: "context" | "mentions";
-    /** `native` (default) uses Slack Agent streams/tasks for threaded replies. `classic` retains the
-     * compatibility renderer based on one rate-limited edited message. A top-level target selected by an
-     * explicit continuous/custom policy necessarily uses the classic renderer because Slack streams
-     * require a parent user message. */
+    /** `native` (default) uses Slack Agent streams for threaded replies. Its inline tool traces carry a
+     * bounded summary of each call's first argument and cannot be retracted, so they stay in the
+     * delivered message beside the answer. `classic` retains the compatibility renderer based on one
+     * rate-limited edited message, which settles into the answer alone. A top-level target necessarily
+     * uses the classic renderer, because Slack streams require a parent user message; a custom route
+     * reaches one either by returning `threadTs: null` or by redirecting to another channel without
+     * naming a thread. */
     rendering?: SlackRendering;
-    /** Native task-card layout (`chat.startStream` `task_display_mode`): `plan` (default) groups steps
-     * under a single collapsible heading, `timeline` lists each step sequentially, `dense` collapses
-     * consecutive tool calls into one summarized card. Applies to the native renderer only. */
-    taskDisplay?: SlackTaskDisplayMode;
     /** Optional footer for successful Agent replies. Omitted or `false` sends no repetitive disclaimer. */
     aiDisclaimer?: string | false;
     /** First-run direct-message welcome, sent once when a user first opens the DM (`app_home_opened`,
@@ -46,7 +39,7 @@ export interface SlackChannelOptions {
         processing?: string;
         completed?: string;
     };
-    /** Custom route policy. Providing it disables the default managed-thread/context admission policy. */
+    /** Custom route policy. Providing it disables the default participant-model thread/context admission policy. */
     route?: (envelope: SlackEventEnvelope) => SlackRoute | null;
     /** Customer-facing failure formatter; full details always remain in operator logs. */
     onError?: (failure: SlackFailure) => string | undefined;
@@ -55,4 +48,4 @@ export interface SlackChannelOptions {
 }
 /** Verify Slack's v0 HMAC over the exact raw body and reject timestamps outside the replay window. */
 export declare function verifySlackSignature(signingSecret: string, timestamp: string, signature: string, rawBody: string, nowMs?: number): boolean;
-export declare function slackChannel({ botToken, signingSecret, botRefreshToken, clientId, clientSecret, botTokenExpiresAt, directMessageSession, groupMessageSession, groupBehavior, rendering, taskDisplay, aiDisclaimer, welcome, reactionAck, route, onError, apiBaseUrl, }: SlackChannelOptions): ChannelModule;
+export declare function slackChannel(options: SlackChannelOptions): ChannelModule;

package/dist/channels/slack/slack.js

@@ -5,8 +5,9 @@ import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { createSeenRing } from "../seen.js";
+import { createThreadParticipants } from "../thread-participants.js";
 import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome } from "../state.js";
+import { ensureStateHome, removeRetiredStateFile } from "../state.js";
 import { dispatchStop, isStopText } from "../stop-command.js";
 import { codePointPrefix } from "../text.js";
 import { createTurnQueue } from "../turn-queue.js";
@@ -14,8 +15,7 @@ import { createTurnStore } from "../turn-store.js";
 import { createSlackBotTokenProvider } from "./bot-auth.js";
 import { collectSlackBufferedFiles, createSlackContextBuffer } from "./context-buffer.js";
 import { invokeSlackTurn } from "./invoke-turn.js";
-import { createOwnedSlackThreads } from "./owned-threads.js";
-import { defaultSlackRoute, isSlackDirectMessage, isSlackGroupMessage, isSlackHumanMessage, slackBufferText, slackEnvelope, slackFileIds, slackMessageText, slackPlaceKey, slackSenderLabel, slackTeamId, } from "./parse.js";
+import { defaultSlackRoute, isSlackDirectMessage, isSlackGroupMessage, hasSlackMention, hasSlackUserMention, isSlackHumanMessage, mentionsSlackUser, stripSlackMentions, slackBufferText, slackEnvelope, slackFileIds, slackMessageText, slackPlaceKey, slackSenderLabel, slackTeamId, } from "./parse.js";
 import { defaultErrorMessage, settleSlackPreview, streamSlackReply, } from "./preview.js";
 import { resolveReactionEmojis, startSlackReaction } from "./reaction.js";
 import { createSlackApi } from "./slack-api.js";
@@ -61,12 +61,16 @@ function messageRefOf(turnId) {
     const parts = turnId.split(":");
     return parts.length === 3 && parts[1] && parts[2] ? { channelId: parts[1], ts: parts[2] } : undefined;
 }
-export function slackChannel({ botToken, signingSecret, botRefreshToken, clientId, clientSecret, botTokenExpiresAt, directMessageSession = "threaded", groupMessageSession = "threaded", groupBehavior = "context", rendering = "native", taskDisplay = "plan", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", }) {
-    if (!["continuous", "threaded"].includes(directMessageSession)) {
-        throw new Error('slackChannel directMessageSession must be "continuous" or "threaded"');
-    }
-    if (!["continuous", "threaded"].includes(groupMessageSession)) {
-        throw new Error('slackChannel groupMessageSession must be "continuous" or "threaded"');
+export function slackChannel(options) {
+    const { botToken, signingSecret, botRefreshToken, clientId, clientSecret, botTokenExpiresAt, groupBehavior = "context", rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
+    // The participant model derives placement instead of selecting it: Slack has no quote primitive, so
+    // answering in place means answering in a thread on the ask, whichever renderer draws it. An
+    // upgraded workspace still passing one of the removed modes would otherwise start fine and silently
+    // get a different placement AND a different memory boundary.
+    const removedModes = ["directMessageSession", "groupMessageSession"].filter((name) => options[name] !== undefined);
+    if (removedModes.length > 0) {
+        throw new Error(`slackChannel no longer accepts ${removedModes.join(" / ")}: an answer goes in a thread on the ask, and ` +
+            "that thread is the session — see docs/design/participant-model.md");
     }
     if (!["context", "mentions"].includes(groupBehavior)) {
         throw new Error('slackChannel groupBehavior must be "context" or "mentions"');
@@ -74,9 +78,6 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
     if (!["native", "classic"].includes(rendering)) {
         throw new Error('slackChannel rendering must be "native" or "classic"');
     }
-    if (!["timeline", "plan", "dense"].includes(taskDisplay)) {
-        throw new Error('slackChannel taskDisplay must be "timeline", "plan", or "dense"');
-    }
     if (welcome !== false && typeof welcome !== "string") {
         throw new Error("slackChannel welcome must be a string or false");
     }
@@ -134,7 +135,16 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
             });
         };
         const seen = createSeenRing(join(stateHome, "seen.json"), label);
-        const ownedThreads = createOwnedSlackThreads(join(stateHome, "owned-threads.json"), label);
+        const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
+        /** A thread's participation is keyed by the SESSION it describes — "the agent answered here" is a
+         *  claim about a memory, so the two must not be re-keyable independently. What keeps the claim true
+         *  under a custom route is the `routed.session === undefined` condition on the write, not the
+         *  absence of a route: a route that supplies its own session records nothing here. */
+        const threadKey = (teamId, channelId, threadTs) => `slack:${teamId}:${channelId}:${threadTs}`;
+        // The participant model replaced the owned-thread index (a cache, so nothing is lost). REMOVE THIS
+        // after the release following the participant model ships — by then no live deployment can still
+        // be carrying the file. test/migration-deadline.test.ts fails when due.
+        removeRetiredStateFile(stateHome, "owned-threads.json", label);
         const welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
         const buffer = createSlackContextBuffer(join(stateHome, "buffers.json"), label);
         const store = createTurnStore(join(stateHome, "turns.json"), {
@@ -220,7 +230,6 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
                         initialPreviewTs: turn.previewTs,
                         threadTitle: turn.threadTitle,
                         disclaimer: aiDisclaimer,
-                        taskDisplay,
                         label,
                     });
                     log.info(`${label} turn done: turn=${turn.id} session=${turn.session} (${Date.now() - startedAt}ms)`);
@@ -254,6 +263,9 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
         let seq = recovered.reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
         for (const { attempts: _attempts, ...intent } of recovered)
             submit({ ...intent }, false);
+        // Acceptance touches no network, so it stays synchronous inside Slack's ACK window and the
+        // delivery dedup ring alone is enough — there is no await for a duplicate delivery to race
+        // through. The minutes-long Agent turn remains fire-and-forget.
         const acceptEvent = (envelope) => {
             const event = envelope.event;
             if (!isSlackHumanMessage(event))
@@ -274,24 +286,44 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
             const direct = isSlackDirectMessage(event);
             const rootTs = event.thread_ts ?? event.ts;
             const bufferKey = slackPlaceKey(teamId, event);
-            const threadedGroup = group && groupMessageSession === "threaded";
-            const managedContinuation = groupBehavior === "context" &&
-                route === undefined &&
-                threadedGroup &&
-                event.thread_ts !== undefined &&
-                ownedThreads.has(teamId, event.channel, event.thread_ts);
+            // Listening is not speaking: every message the channel can see refines who takes part in its
+            // thread, whether or not it is answered. Humans only — a bot's own posts are recorded where they
+            // are known — this channel answering.
+            // Structural facts only, never `groupBehavior` or `route` — see thread-participants.ts. Slack
+            // adds no delta of its own here; its summon rule is the only consumer.
+            if (group && event.thread_ts !== undefined) {
+                threadParticipants.merge(threadKey(teamId, event.channel, event.thread_ts), { humans: [event.user] });
+            }
             let routed = decide(envelope);
-            const hasUserMention = /<@[A-Z0-9]+>/i.test(event.text ?? "");
-            const structurallyMentionsBot = botUserId !== undefined && (event.text ?? "").includes(`<@${botUserId}>`);
+            // Two different questions (see parse.ts). `addressesSomeone` is the "@-mentions only other people
+            // is discussion, never an ask" guard (§3) and counts broadcasts and user groups too;
+            // `mightBeTheBot` gates the identity-window deferral below, where only a USER mention qualifies.
+            const addressesSomeone = hasSlackMention(event.text ?? "");
+            const mightBeTheBot = hasSlackUserMention(event.text ?? "");
+            const structurallyMentionsBot = botUserId !== undefined && mentionsSlackUser(event.text ?? "", botUserId);
             // app_mention and message.* subscriptions can overlap. If message.* arrives first, structural bot
             // identity routes it now; while auth.test is still unresolved, defer any mentioned message rather
             // than buffer+dedup it and accidentally suppress the later app_mention callback.
             if (!routed && route === undefined && group && event.type === "message" && structurallyMentionsBot)
                 routed = {};
-            if (!routed && managedContinuation && event.type !== "app_mention")
+            // The participant model's thread rule (§3): a bare message reaches the agent while it takes part
+            // and has not heard a second human. Note the ORDER — the mention guard below runs first and is
+            // structural: it reads who THIS message addresses, which is the one thing an observation-only
+            // store cannot know about someone it has never heard.
+            if (!routed &&
+                groupBehavior === "context" &&
+                route === undefined &&
+                group &&
+                event.thread_ts !== undefined &&
+                event.type !== "app_mention" &&
+                // Mentioning only other people is targeted discussion, never an ask (§3) — the same guard
+                // Feishu applies with `hasMentions`.
+                !addressesSomeone &&
+                threadParticipants.admitsBareMessage(threadKey(teamId, event.channel, event.thread_ts))) {
                 routed = {};
+            }
             if (!routed) {
-                if (route === undefined && group && botUserId === undefined && hasUserMention)
+                if (route === undefined && group && botUserId === undefined && mightBeTheBot)
                     return;
                 if (groupBehavior === "context" && route === undefined && group) {
                     const body = slackBufferText(slackMessageText(event));
@@ -312,22 +344,17 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
             }
             const targetChannel = routed.channelId ?? event.channel;
             const sameChannel = targetChannel === event.channel;
-            const defaultThread = group
-                ? (event.thread_ts ?? (groupMessageSession === "threaded" ? event.ts : undefined))
-                : (event.thread_ts ?? (directMessageSession === "threaded" ? event.ts : undefined));
+            // Answer where asked (participant model §4). Slack has no quote primitive, so the only way to
+            // attach an answer to its question is a thread on it — which then IS the place, and carries the
+            // memory (§5). Native streaming additionally REQUIRES a thread, but the shape does not depend on
+            // the renderer: `classic` attaches its answer the same way.
+            const defaultThread = event.thread_ts ?? event.ts;
             const threadTs = routed.threadTs === null ? undefined : (routed.threadTs ?? (sameChannel ? defaultThread : undefined));
-            const continuousTopLevel = event.thread_ts === undefined;
-            const defaultSession = direct
-                ? directMessageSession === "continuous" && continuousTopLevel
-                    ? `slack:${teamId}:${event.channel}`
-                    : `slack:${teamId}:${event.channel}:${rootTs}`
-                : groupMessageSession === "continuous" && continuousTopLevel
-                    ? `slack:${teamId}:${event.channel}`
-                    : `slack:${teamId}:${event.channel}:${rootTs}`;
+            const defaultSession = threadKey(teamId, event.channel, rootTs);
             // Explicit user stop: a control action, never a turn — it must not queue behind the run it
             // stops. Match the bare word after stripping the bot mention; record the logical id so a Slack
             // redelivery doesn't double-abort or double-notify.
-            if (isStopText((event.text ?? "").replace(/<@[A-Z0-9]+>/gi, " "))) {
+            if (isStopText(stripSlackMentions(event.text ?? ""))) {
                 seen.add(logicalId);
                 const target = { channelId: event.channel, threadTs: event.thread_ts };
                 sideTasks.track(dispatchStop(control, routed.session ?? defaultSession, label)
@@ -340,21 +367,8 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
             if (!baseText.trim() && fileIds.length === 0)
                 return;
             const threadTitle = direct && event.thread_ts === undefined
-                ? codePointPrefix(slackMessageText(event)
-                    .replace(/<@[A-Z0-9]+>/gi, "")
-                    .replace(/\s+/g, " ")
-                    .trim(), 80)
+                ? codePointPrefix(stripSlackMentions(slackMessageText(event), "").replace(/\s+/g, " ").trim(), 80)
                 : undefined;
-            // Match Feishu/Lark ownership in context mode: only a top-level summon that creates an
-            // Agent-managed thread owns the root. Mentioning the Agent inside an existing human thread
-            // answers once without adopting it; mention-only mode never consumes ownership state.
-            if (groupBehavior === "context" &&
-                route === undefined &&
-                threadedGroup &&
-                event.thread_ts === undefined &&
-                sameChannel) {
-                ownedThreads.add(teamId, event.channel, rootTs);
-            }
             submit({
                 id: logicalId,
                 seq: ++seq,
@@ -368,6 +382,37 @@ export function slackChannel({ botToken, signingSecret, botRefreshToken, clientI
                 threadTitle: threadTitle || undefined,
                 fileIds,
             }, true);
+            // Answering inside a GROUP thread makes the agent a participant of it, which is what lets the
+            // NEXT bare message address it without a mention.
+            //
+            // `group` excludes DMs, whose `threadTs` is always defined (the answer opens its assistant
+            // thread) and which no rule could ever read — safe because it is structural: a channel never
+            // becomes a DM.
+            //
+            // The two `routed` conditions keep the record describing what it claims. `session` undefined: the
+            // flag asserts "the agent answered into THIS thread's session", so a route supplying its own
+            // would record participation in a memory that never held the turn. `threadTs` undefined: a route
+            // can send the answer to a DIFFERENT thread, where the asker never spoke — recording them there
+            // would invent a participant. Feishu carries the same two conditions for the same reasons.
+            //
+            // Recorded only once the intent is durable: `submit` can throw, and a redelivery must still see
+            // the thread as the agent has actually left it.
+            if (group &&
+                threadTs !== undefined &&
+                sameChannel &&
+                routed.session === undefined &&
+                routed.threadTs === undefined) {
+                // The ASKER counts as heard in this thread too, and both halves are written together so the
+                // record can never say "the agent takes part and nobody has spoken". When the ask is top
+                // level, the answer is what CREATES the thread, so the observation above never ran for it (no
+                // `thread_ts` on the ask) — without this, a thread whose root is a human would not count them,
+                // and a stranger's first bare reply would read as a two-party exchange. `event.user` is
+                // guaranteed here (isSlackHumanMessage). Idempotent when the ask was already in the thread.
+                threadParticipants.merge(threadKey(teamId, event.channel, threadTs), {
+                    agentSpoke: true,
+                    humans: [event.user],
+                });
+            }
         };
         // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle.
         const sideTasks = createTaskTracker();

package/dist/channels/state.d.ts

@@ -1,9 +1,16 @@
-/** Create the state home and self-ignore it (`.gitignore="*"`): its contents (buffers, downloaded
- *  files) can carry chat content and must never be committable. The workspace opener already protects
- *  an in-tree state root; this local guard also covers direct embedders. `wx` never clobbers an
- *  operator's own file. */
+/** 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). */
 export declare function loadStateFile(path: string): unknown;
 export declare function saveStateFile(path: string, value: unknown): void;
+/**
+ * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
+ * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
+ * whose loss changes behaviour needs a migration, not a delete.
+ *
+ * Shared because a retired file is usually retired in every channel at once: one best-effort
+ * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
+ * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
+ */
+export declare function removeRetiredStateFile(stateHome: string, name: string, label: string): void;

package/dist/channels/state.js

@@ -12,22 +12,12 @@
  * 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.
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { log } from "../log.js";
-/** Create the state home and self-ignore it (`.gitignore="*"`): its contents (buffers, downloaded
- *  files) can carry chat content and must never be committable. The workspace opener already protects
- *  an in-tree state root; this local guard also covers direct embedders. `wx` never clobbers an
- *  operator's own file. */
+/** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
 export function ensureStateHome(dir) {
     mkdirSync(dir, { recursive: true });
-    try {
-        writeFileSync(join(dir, ".gitignore"), "*\n", { flag: "wx" });
-    }
-    catch (e) {
-        if (e.code !== "EEXIST")
-            throw e;
-    }
 }
 /** 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). */
@@ -58,3 +48,20 @@ export function saveStateFile(path, value) {
     writeFileSync(tmp, JSON.stringify(value));
     renameSync(tmp, path);
 }
+/**
+ * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
+ * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
+ * whose loss changes behaviour needs a migration, not a delete.
+ *
+ * Shared because a retired file is usually retired in every channel at once: one best-effort
+ * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
+ * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
+ */
+export function removeRetiredStateFile(stateHome, name, label) {
+    try {
+        rmSync(join(stateHome, name), { force: true });
+    }
+    catch (error) {
+        log.debug(`${label} could not remove the obsolete ${name}: ${String(error)}`);
+    }
+}

package/dist/channels/tasks.d.ts

@@ -1,9 +1,3 @@
-/**
- * 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.
- */
 export interface TaskTracker {
     /** Track one task. The caller keeps its own `.catch` — rejections must already be handled. */
     track(task: Promise<unknown>): void;

package/dist/channels/tasks.js

@@ -1,9 +1,24 @@
+/**
+ * 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.
+ */
+import { beginWork } from "./busy.js";
 export function createTaskTracker() {
     const tasks = new Set();
     return {
         track(task) {
             tasks.add(task);
-            void task.finally(() => tasks.delete(task)).catch(() => { }); // the caller's chain owns the error
+            // 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(() => { }); // the caller's chain owns the error
         },
         drain: () => Promise.all(tasks).then(() => undefined),
     };

package/dist/channels/telegram/parse.d.ts

@@ -1,10 +1,3 @@
-/**
- * Telegram protocol parsing — PURE: message field extraction, the prompt envelope, and the summon/route
- * policy. The defining invariant is purity: no state, no IO, no Bot API calls — plain data-in → data-out.
- * In telegram.ts's pipeline (verify → decide via `route` → run the turn → stream reply), this is the
- * "decide" and prompt-building half; telegram.ts wires it in and owns the stateful lifecycle. Kept
- * separate so this layer tests as plain functions and reads without the factory's noise.
- */
 /** A Telegram message (the common subset; `[k]` keeps the rest reachable without a types dependency). */
 export interface TelegramMessage {
     message_id: number;

package/dist/channels/telegram/parse.js

@@ -5,6 +5,8 @@
  * "decide" and prompt-building half; telegram.ts wires it in and owns the stateful lifecycle. Kept
  * separate so this layer tests as plain functions and reads without the factory's noise.
  */
+import { BUFFER_LINE_MAX_CHARS } from "../context-buffer.js";
+import { REFERENT_MAX_CODE_POINTS, truncateCodePointPrefix } from "../text.js";
 /** The actionable message in an update (a fresh message or channel post). Edits (`edited_message` /
  *  `edited_channel_post`) are deliberately NOT actionable: answering them re-answers every typo fix (a
  *  duplicate reply per edit), so an edited message changes nothing — the standard bot behavior. The
@@ -62,7 +64,7 @@ function bodyOf(m) {
 }
 /** A one-line, length-capped rendering of a message's content for the context buffer. */
 export function messageText(m) {
-    return (bodyOf(m) ?? "").replace(/\s+/g, " ").trim().slice(0, 280);
+    return truncateCodePointPrefix((bodyOf(m) ?? "").replace(/\s+/g, " ").trim(), BUFFER_LINE_MAX_CHARS);
 }
 /**
  * The default base prompt: a context envelope (chat/thread/sender + a group note + reply) then the
@@ -88,7 +90,7 @@ export function telegramEnvelope(m) {
     const isGroup = m.chat.type === "group" || m.chat.type === "supergroup";
     const scope = isGroup ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
     const replyTo = r
-        ? `\n[in reply to ${fromLabel(r.from) ?? `msg ${r.message_id}`} (msg ${r.message_id}): ${(bodyOf(r) ?? "(empty)").slice(0, 280)}]`
+        ? `\n[in reply to ${fromLabel(r.from) ?? `msg ${r.message_id}`} (msg ${r.message_id}): ${truncateCodePointPrefix(bodyOf(r) ?? "(empty)", REFERENT_MAX_CODE_POINTS)}]`
         : "";
     const parts = [bodyOf(m) ?? ""];
     if (m.location)

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

@@ -26,7 +26,7 @@ function splitPlain(text: string): string[] {
   return parts;
 }
 
-// Standalone copy of the channel transport's discipline: an upload timeout so a wedged connection
+// Embedded copy of the channel transport's discipline: an upload timeout so a wedged connection
 // can't hang the tool call (and the turn), named errors, and success gated on the body's own ok.
 // Deliberately NO 429 retry — a tool error goes back to the agent, which can decide to retry;
 // fail-fast beats a silently sleeping tool.
@@ -60,8 +60,11 @@ export default defineTool({
   description:
     "Send to a Telegram chat: a text message (`text` — long text is split into multiple messages " +
     "automatically), or a local file (`path` — a document, or a photo if it is an image). Exactly one " +
-    "of text/path. In a chat turn take chatId from the [telegram: chat …] context line; in a " +
-    "scheduled/woken turn (no context line) the chat id must come from your instruction.",
+    "of text/path. 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 send it twice). chatId comes " +
+    "from the [telegram: chat …] context line in a chat turn; a scheduled/woken turn has no context " +
+    "line, so name the destination in your instruction.",
   input: z.object({
     chatId: z.union([z.string(), z.number()]).describe("target chat id"),
     text: z.string().optional().describe("message text to send"),

package/dist/channels/telegram/telegram.js

@@ -109,7 +109,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             throw new Error(`telegramChannel requires an absolute ctx.stateRoot, got "${stateRoot}"`);
         }
         const stateHome = join(stateRoot, "channels", "telegram");
-        ensureStateHome(stateHome); // create + self-ignore — buffers/files may carry chat content
+        ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
         const buffer = createContextBuffer(join(stateHome, "buffers.json"));
         // Durable turn intent (L1): persist an accepted turn pre-ACK, remove it when the turn ends; a crash
         // leaves it for replay on the next start. See turn-store.ts for the at-least-once semantics.

package/dist/channels/text.d.ts

@@ -1,6 +1,20 @@
 /** 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.
+ */
+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;
 /** Ellipsize from the right while keeping the result within `maxPoints` Unicode code points. */

package/dist/channels/text.js

@@ -1,6 +1,20 @@
 /** 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.
+ */
+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) {
     if (maxPoints <= 0)

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

@@ -0,0 +1,21 @@
+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.
+     */
+    admitsBareMessage(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.
+     */
+    merge(key: string, heard: {
+        humans?: string[];
+        agentSpoke?: true;
+    }): void;
+}
+export declare function createThreadParticipants(path: string, label: string): ThreadParticipants;