@fastagent-sh/fastagent 0.14.0 → 0.16.0

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

@@ -32,6 +32,7 @@ import { collectAttachments, createContextBuffer } from "./context-buffer.js";
 import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, } from "./parse.js";
 import { defaultErrorMessage, streamReply } from "./preview.js";
 import { ensureStateHome } from "../state.js";
+import { dispatchStop } from "../stop-command.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "./turn-store.js";
@@ -67,15 +68,14 @@ function tokenMatches(header, secret) {
  * share the first's turn-store/context-buffer. One telegram instance per workspace (single-process).
  */
 export function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl = "https://api.telegram.org", }) {
-    // Both are mandatory: an unset secret_token would accept forged updates (the endpoint is public);
-    // the bot token is required to send the reply. Fail at construction (startup), not silently.
-    if (!secretToken) {
-        throw new Error("telegramChannel requires a non-empty secretToken (the webhook secret_token; an unset one accepts forged updates)");
-    }
-    if (!botToken) {
-        throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
-    }
-    return ({ agent, stateRoot }) => {
+    return ({ agent, stateRoot, control }) => {
+        // Validate at activation so deploy may inspect the module shape before secrets are provisioned.
+        if (!secretToken) {
+            throw new Error("telegramChannel requires a non-empty secretToken (the webhook secret_token; an unset one accepts forged updates)");
+        }
+        if (!botToken) {
+            throw new Error("telegramChannel requires a non-empty botToken (used to send the agent's reply)");
+        }
         const formatError = onError ?? defaultErrorMessage;
         // One getMe at startup: the bot's @username (for the default route's group @mention summon, only when
         // not supplied) and the group-privacy flag — privacy mode off is required to receive the un-summoned
@@ -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.
@@ -323,6 +323,20 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 // that explicitly returns the same chat/thread still quotes.
                 const threadId = r.threadId ?? m.message_thread_id;
                 const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
+                // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the
+                // run it stops. `/stop@otherbot` is not ours; a bare `/stop` always is. Awaited before the ACK:
+                // dispatch + one sendMessage is fast, and a delivery failure logs instead of failing the webhook.
+                const stopMatch = /^\/stop(?:@([A-Za-z0-9_]+))?$/i.exec(messageText(m).trim());
+                if (stopMatch && (!stopMatch[1] || stopMatch[1].toLowerCase() === mentionName?.toLowerCase())) {
+                    const feedback = await dispatchStop(control, session, "[telegram]");
+                    const target = {
+                        chatId,
+                        threadId,
+                        replyTo: m.chat.type !== "private" && sameTarget ? m.message_id : undefined,
+                    };
+                    await sendMessage(apiBaseUrl, botToken, target, feedback, { html: false }).catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`));
+                    return new Response(null, { status: 200 });
+                }
                 const baseText = r.text ?? telegramEnvelope(m);
                 const imageFileIds = extractImages(m);
                 const fileIds = extractFiles(m);

package/dist/channels/{feishu/text.d.ts → text.d.ts}

@@ -1,6 +1,20 @@
-/** Pure Unicode-safe text slicing helpers shared by Feishu/Lark rendering paths. JavaScript string
+/** 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/{feishu/text.js → text.js}

@@ -1,6 +1,20 @@
-/** Pure Unicode-safe text slicing helpers shared by Feishu/Lark rendering paths. JavaScript string
+/** 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;

package/dist/channels/thread-participants.js

@@ -0,0 +1,132 @@
+/**
+ * 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.
+ */
+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. */
+const MAX_HUMANS = 2;
+function isStoredParticipation(value) {
+    const record = value;
+    return (Array.isArray(record?.humans) &&
+        record.humans.every((human) => typeof human === "string") &&
+        typeof record.agentSpoke === "boolean");
+}
+export function createThreadParticipants(path, label) {
+    const raw = loadStateFile(path);
+    const records = new Map();
+    if (raw !== undefined) {
+        if (typeof raw === "object" &&
+            raw !== null &&
+            !Array.isArray(raw) &&
+            Object.values(raw).every(isStoredParticipation)) {
+            for (const [key, record] of Object.entries(raw)) {
+                records.set(key, { humans: record.humans, agentSpoke: record.agentSpoke });
+            }
+        }
+        else {
+            log.warn(`${label} unexpected shape in ${path} — starting with no thread participation`);
+        }
+    }
+    return {
+        admitsBareMessage(key) {
+            const heard = records.get(key);
+            return heard?.agentSpoke === true && heard.humans.length <= 1;
+        },
+        merge(key, heard) {
+            const previous = records.get(key);
+            const humans = new Set(previous?.humans ?? []);
+            for (const human of heard.humans ?? []) {
+                if (humans.size >= MAX_HUMANS)
+                    break;
+                humans.add(human);
+            }
+            const next = {
+                humans: [...humans],
+                agentSpoke: (previous?.agentSpoke ?? false) || (heard.agentSpoke ?? false),
+            };
+            // `humans` starts from `previous` and only grows, so equal size IS set equality here.
+            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.
+            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.
+                let evict;
+                for (const [candidate, record] of records) {
+                    if (candidate === key)
+                        continue;
+                    if (!record.agentSpoke) {
+                        evict = candidate;
+                        break;
+                    }
+                    evict ??= candidate;
+                }
+                if (evict === undefined)
+                    break;
+                records.delete(evict);
+            }
+            try {
+                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.
+                log.warn(`${label} could not persist thread participation ${path}: ${String(error)}`);
+            }
+        },
+    };
+}

package/dist/channels/turn-queue.js

@@ -5,12 +5,13 @@
  * instead of colliding on the lease and being dropped as "busy").
  *
  * Channel-neutral (records are opaque beyond a `session` key), shared by the stateful chat channels
- * (telegram, Feishu; Lark reuses Feishu). Durability is layered ON TOP by the caller: turn-store.ts
+ * (Telegram, Feishu/Lark, Slack). Durability is layered ON TOP by the caller: turn-store.ts
  * persists an accepted turn's intent pre-ACK and replays a crash-surviving one on the next start (L1,
  * process-crash recovery, at-least-once). Exactly-once / deterministic step-replay (L2) is the K-axis
  * backend — an external queue with distributed locking (SPEC §11) — not this in-memory queue.
  */
 import { log } from "../log.js";
+import { beginWork } from "./busy.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
     // Per-session serial chains: a second turn for the same session waits its turn (FIFO) instead of
@@ -20,6 +21,11 @@ export function createTurnQueue(opts) {
         accept(rec) {
             if (chains.has(rec.session))
                 onQueuedBehind?.(rec);
+            // Process-wide busy signal (busy.ts): an accepted turn counts as in-flight work from acceptance
+            // until its run settles — serving surfaces that must not idle mid-turn (the AgentCore adapter's
+            // /ping) read it. Counted here, not in run(), so a QUEUED turn (accepted, waiting on the chain)
+            // already reads as busy.
+            const workDone = beginWork();
             const prev = chains.get(rec.session) ?? Promise.resolve();
             const task = async () => {
                 try {
@@ -32,6 +38,7 @@ export function createTurnQueue(opts) {
             const next = prev.then(task, task); // run after this session's previous turn, in arrival order
             chains.set(rec.session, next);
             void next.finally(() => {
+                workDone();
                 if (chains.get(rec.session) === next)
                     chains.delete(rec.session); // drop the entry when drained
             });

package/dist/channels/turn-store.d.ts

@@ -9,7 +9,7 @@ export interface TurnRecordBase {
     attempts: number;
 }
 export interface TurnStore<T extends TurnRecordBase> {
-    /** Persist an accepted turn before the ACK. A failed write throws (→ webhook 500, the platform redelivers). */
+    /** Persist an accepted turn before the ACK. A failed write throws (→ HTTP response / WS ACK 500, so the platform redelivers). */
     add(rec: T): void;
     /** Remove a finished turn. Post-ACK: a failed write is logged, never thrown (must not abort delivery). */
     remove(id: string): void;

package/dist/channels/turn-store.js

@@ -31,8 +31,7 @@
  *
  * Channel-neutral, generic over the record shape: the channel supplies its own record type (everything
  * its runner needs to re-execute the turn), the shape validator (state files are an IO boundary), the
- * arrival ordering for recovery, and its log label. telegram/turn-store.ts and the Feishu channel are the
- * two consumers.
+ * arrival ordering for recovery, and its log label. Telegram, Feishu/Lark, and Slack consume it.
  *
  * ponytail: at-least-once with a per-turn EXECUTION ceiling. A poison turn that deterministically
  * crashes the process would replay forever under a container restart policy. The counter is bumped at
@@ -84,7 +83,7 @@ export function createTurnStore(path, opts) {
                 return;
             turns.set(rec.id, rec);
             try {
-                persist(); // pre-ACK: a throw becomes the webhook's 500 and the platform redelivers
+                persist(); // pre-ACK: the transport maps this throw to HTTP/WS 500, so the platform redelivers
             }
             catch (e) {
                 // Roll the memory back so it matches disk (mirrors context-buffer.push): otherwise the phantom

package/dist/cli/add-feishu.d.ts

@@ -0,0 +1,30 @@
+import { type FeishuGroupBehavior, type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
+import { type FeishuApi } from "../channels/feishu/feishu-api.ts";
+import { type GroupBehaviorChoice } from "../scaffold/add-channel.ts";
+export interface GroupBehaviorSetup {
+    /** Safe to proceed to version publishing now; false means Permissions still needs manual/admin work. */
+    publishReady: boolean;
+}
+export declare function configureGroupBehavior(input: {
+    kind: "feishu" | "lark";
+    appId: string;
+    apiBase: string;
+    api: Pick<FeishuApi, "listAppScopes" | "addAppScopes">;
+    behavior: FeishuGroupBehavior;
+    /** Whether the author chose the behavior (flag or prompt). A defaulted "context" inspects and
+     * reports only — it must never PATCH the sensitive scope into the app draft. */
+    explicit: boolean;
+    note?: (message: string) => void;
+    openUrl?: (url: string) => void;
+}): Promise<GroupBehaviorSetup>;
+/**
+ * Create or resume the platform app behind `add feishu` / `add lark`. `target` is the AGENT DIR;
+ * credentials land in its `.env` — whose real path is {@link dotEnvPath}, printed rather than spelled,
+ * because `FASTAGENT_SECRETS_DIR` moves it and a hardcoded `.secrets/.env` would name a file this run
+ * did not write. Returns credentials for the
+ * caller's generic .env write (the guided Lark path), or undefined when nothing remains to write —
+ * the feishu path persists its own two credential stages internally (the App ID/Secret boundary is
+ * irreversible and must not wait for the caller). Throws on refusal (a non-interactive lark run);
+ * the caller surfaces that as a startup failure.
+ */
+export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehaviorChoice): Promise<Record<string, string> | undefined>;