@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/channels/telegram/telegram.js

@@ -2,18 +2,19 @@
  * Telegram bot channel: verify the webhook secret token → decide via `route(update)` → run the turn → stream the
  * agent's reply back to the chat, ACK 200.
  */
-import { isAbsolute, join } from "node:path";
+import { join } from "node:path";
 import { log } from "../../log.js";
 import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { secretEquals } from "../secret.js";
 import { telegramTurnStream } from "./invoke-turn.js";
 import { collectAttachments, createContextBuffer } from "./context-buffer.js";
-import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, telegramStop, } from "./parse.js";
+import { attachmentSummary, defaultTelegramRoute, extractFiles, extractImages, fromLabel, messageText, ownFiles, ownImages, pickMessage, telegramEnvelope, telegramPlaceKey, telegramStop, } from "./parse.js";
+import { registerTelegramTransport } from "./shared-api.js";
 import { defaultErrorMessage, deliverTelegramAnswer, telegramReply } from "./preview.js";
 import { attachmentsDir } from "../kit/attachment-path.js";
-import { ensureStateHome } from "../kit/state.js";
 import { dispatchStop } from "../kit/stop-command.js";
+import { createTaskTracker } from "../kit/tasks.js";
 import { callApi, editMessageText, sendMessage } from "./telegram-api.js";
 import { createTurnRunner } from "../kit/turn-runner.js";
 import { discussionBlock } from "../kit/context-buffer.js";
@@ -25,7 +26,7 @@ export { defaultTelegramRoute, telegramEnvelope, telegramStop };
 const MAX_UPDATE_BYTES = 1 << 20;
 /** Build a Telegram bot channel: policy options in, a {@link ChannelModule} out. */
 export function telegramChannel({ secretToken, botToken, route, onError, botUsername, apiBaseUrl = "https://api.telegram.org", }) {
-    return ({ agent, stateRoot, control }) => {
+    return ({ agent, sessionFor, recordedSession, stateDir: stateHome }) => {
         // 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)");
@@ -57,17 +58,17 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             log.warn("[telegram] bot token has no parseable bot id — reply-to-bot summon disabled until getMe resolves");
         }
         const decide = route ?? ((update) => defaultTelegramRoute(update, { botUsername: mentionName, botId }));
-        // The channel-state convention: this channel's durable home is `<stateRoot>/channels/telegram` (engine state at
-        // the root, channel state under `channels/<kind>/`).
-        if (!isAbsolute(stateRoot)) {
-            throw new Error(`telegramChannel requires an absolute ctx.stateRoot, got "${stateRoot}"`);
-        }
-        const stateHome = join(stateRoot, "channels", "telegram");
-        ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
         const buffer = createContextBuffer(join(stateHome, "buffers.json"));
+        // The send tool rides this channel's token, and what it sends lands in this buffer (shared-api.ts says why).
+        registerTelegramTransport({
+            apiBaseUrl,
+            botToken,
+            record: (placeKey, entry) => buffer.push(placeKey, entry),
+        });
         // 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.
         const store = createTurnStore(join(stateHome, "turns.json"));
+        const sideTasks = createTaskTracker("[telegram]");
         const targetOf = (r) => ({ chatId: r.chatId, threadId: r.threadId, replyTo: r.replyTo });
         // Tell the asker when a turn is dropped at the execution ceiling: the chain's end needs a signal, not just an
         // operator log line.
@@ -76,15 +77,15 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             const sent = r.previewId !== undefined
                 ? editMessageText(apiBaseUrl, botToken, targetOf(r), r.previewId, body, { html: false })
                 : sendMessage(apiBaseUrl, botToken, targetOf(r), body, { html: false }).then(() => { });
-            void sent.catch((e) => log.warn(`[telegram] could not notify a dropped turn (session=${r.session}): ${String(e)}`));
+            void sent.catch((e) => log.warn(`[telegram] could not notify a dropped turn (conversation=${r.conversation}): ${String(e)}`));
         };
         const runner = createTurnRunner({
             label: "[telegram]",
             store,
-            buffer,
+            discussion: buffer,
             toStored: ({ previewId: _live, ...intent }) => ({ ...intent, attempts: 0 }),
             fromStored: ({ attempts: _a, ...intent }) => ({ ...intent, previewId: undefined }),
-            bufferKey: (rec) => rec.placeKey,
+            discussionKey: (rec) => rec.placeKey,
             where: (rec) => `chat=${rec.chatId}${rec.threadId !== undefined ? ` thread=${rec.threadId}` : ""}`,
             // Queue feedback: when this session already has a turn running/queued, a silent wait reads as "the bot ignored
             // me" once the current turn runs long.
@@ -108,7 +109,11 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             notifyDropped,
             // `rec.previewId`: the ⏳ notice THIS process put up if the record waited behind another turn.
             deliverAnswer: (rec, answer) => portJoin(() => deliverTelegramAnswer(apiBaseUrl, botToken, targetOf(rec), answer, rec.previewId)),
-            execute: (rec, discussion, onAnswered) => telegramReply(telegramTurnStream(agent, rec.session, `${discussionBlock(discussion.text)}${rec.baseText}`, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: attachmentsDir(stateHome) }, {
+            execute: (rec, discussion, onAnswered) => telegramReply(telegramTurnStream(agent, {
+                session: () => sessionFor(rec.conversation),
+                key: rec.id,
+                text: `${discussionBlock(discussion.text)}${rec.baseText}`,
+            }, { api: apiBaseUrl, botToken, chatId: rec.chatId, filesDir: attachmentsDir(stateHome) }, {
                 primary: { imageFileIds: rec.imageFileIds, fileIds: rec.fileIds },
                 buffered: collectAttachments(discussion.consumed, {
                     files: new Set(rec.fileIds),
@@ -138,7 +143,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
             const m = pickMessage(update);
             if (!m)
                 return new Response(null, { status: 200 });
-            const placeKey = m.message_thread_id ? `${m.chat.id}:${m.message_thread_id}` : `${m.chat.id}`;
+            const placeKey = telegramPlaceKey(m.chat.id, m.message_thread_id);
             const r = decide(update);
             if (!r) {
                 // Not summoned: in a group, record the message so a later summon has the discussion (needs privacy off to be
@@ -164,17 +169,18 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 }
                 return new Response(null, { status: 200 });
             }
-            // Branded with the channel kind: session ids share one namespace across every channel of a deployment.
-            const session = r.session ?? `telegram:${placeKey}`;
+            const conversation = r.conversation ?? placeKey;
             const chatId = r.chatId ?? m.chat.id;
             // Reply to the summoning message in groups (threads the answer under the asker); a 1:1 DM needs no reply-quote.
             const threadId = r.threadId ?? m.message_thread_id;
             const sameTarget = String(chatId) === String(m.chat.id) && threadId === m.message_thread_id;
             const replyTo = m.chat.type !== "private" && sameTarget ? m.message_id : undefined;
             // Explicit user stop (`/stop`): a control action, never a turn — it must not queue behind the run it stops.
+            // `abort` waits until what it stopped has ended, so the update is acknowledged first.
             if (telegramStop(update, { botUsername: mentionName, botId })) {
-                const feedback = await dispatchStop(control, session, "[telegram]");
-                await sendMessage(apiBaseUrl, botToken, { chatId, threadId, replyTo }, feedback, { html: false }).catch((e) => log.warn(`[telegram] stop feedback failed: ${String(e)}`));
+                sideTasks.track(dispatchStop(agent, recordedSession(conversation), "[telegram]")
+                    .then((feedback) => sendMessage(apiBaseUrl, botToken, { chatId, threadId, replyTo }, 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);
@@ -184,7 +190,7 @@ export function telegramChannel({ secretToken, botToken, route, onError, botUser
                 // Everything the turn needs, as a plain record; persisted pre-ACK then run serially per session.
                 runner.submit({
                     id: `${update.update_id}`,
-                    session,
+                    conversation,
                     placeKey,
                     baseText,
                     chatId,

package/dist/channels/telegram/turn-store.js

@@ -13,7 +13,7 @@ function isStoredTurn(t) {
     const r = t;
     const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
     return (typeof r?.id === "string" &&
-        typeof r.session === "string" &&
+        typeof r.conversation === "string" &&
         typeof r.placeKey === "string" &&
         typeof r.baseText === "string" &&
         (typeof r.chatId === "string" || typeof r.chatId === "number") &&

package/dist/channels/{kit/turn-queue.d.ts → turn-queue.d.ts}

@@ -1,4 +1,4 @@
-/** Per-session FIFO execution. */
+/** Per-conversation FIFO execution. */
 import * as Effect from "effect/Effect";
 import type * as Scope from "effect/Scope";
 export interface TurnQueue<T> {
@@ -7,7 +7,7 @@ export interface TurnQueue<T> {
     idle(): Promise<void>;
 }
 export declare function createTurnQueue<T extends {
-    session: string;
+    conversation: string;
 }>(opts: {
     label: string;
     /** The queue diagnoses escaped failures and closes this turn's resources before its successor runs. */

package/dist/channels/{kit/turn-queue.js → turn-queue.js}

@@ -1,17 +1,17 @@
-/** Per-session FIFO execution. */
+/** Per-conversation FIFO execution. */
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
-import { log } from "../../log.js";
-import { beginWork } from "../busy.js";
-import { portError } from "../../effect-port.js";
+import { log } from "../log.js";
+import { beginWork } from "./busy.js";
+import { portError } from "../effect-port.js";
 export function createTurnQueue(opts) {
     const { label, run, onQueuedBehind } = opts;
     const chains = new Map();
     return {
         accept(rec) {
-            if (chains.has(rec.session))
+            if (chains.has(rec.conversation))
                 onQueuedBehind?.(rec);
-            const prev = chains.get(rec.session);
+            const prev = chains.get(rec.conversation);
             // Admission counts immediately, including while waiting behind another turn.
             const workDone = beginWork();
             const fiber = Effect.runFork(Effect.scoped(Effect.gen(function* () {
@@ -20,12 +20,12 @@ export function createTurnQueue(opts) {
                 if (prev)
                     yield* Fiber.await(prev);
                 yield* run(rec);
-            })).pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`${label} turn runner rejected (session=${rec.session}; own your error surface in run()): ${String(portError(cause))}`))), Effect.ensuring(Effect.sync(() => {
+            })).pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`${label} turn runner rejected (conversation=${rec.conversation}; own your error surface in run()): ${String(portError(cause))}`))), Effect.ensuring(Effect.sync(() => {
                 workDone();
-                if (chains.get(rec.session) === fiber)
-                    chains.delete(rec.session);
+                if (chains.get(rec.conversation) === fiber)
+                    chains.delete(rec.conversation);
             }))));
-            chains.set(rec.session, fiber);
+            chains.set(rec.conversation, fiber);
         },
         idle: () => Effect.runPromise(Effect.gen(function* () {
             // A finishing turn may enqueue more work.

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

@@ -1,20 +1,50 @@
-import { type FeishuGroupBehavior, type FeishuSubscriptionMode } from "../channels/feishu/setup-mode.ts";
+import { 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. */
+import type { DeclaredChannel } from "../channels/discover.ts";
+import { type Person } from "./person.ts";
+export interface AgentScopeCheck {
+    /** Safe to proceed to version publishing now; false means Permissions still needs console or admin work. */
     publishReady: boolean;
+    /** The scopes found missing; empty when the list could not be read (`publishReady` is false then). */
+    missing: string[];
 }
-export declare function configureGroupBehavior(input: {
+/**
+ * Check that the app holds what an app of this ingress needs ({@link feishuAppScopes}). A created app asks for them on
+ * its confirm page, and a tenant may still withhold some (its approval policy, or an app made by hand): those are
+ * NAMED, with what each one costs, and the console page that requests them is opened pre-filled. Nothing is requested
+ * through the config API — that needs a scope of its own, which a tenant can withhold just the same.
+ */
+export declare function checkAgentScopes(input: {
     kind: "feishu" | "lark";
     appId: string;
     apiBase: string;
-    api: Pick<FeishuApi, "listAppScopes" | "addAppScopes">;
-    behavior: FeishuGroupBehavior;
-    /** Whether the author chose the behavior (flag or prompt). */
-    explicit: boolean;
+    ingress: FeishuSubscriptionMode;
+    api: Pick<FeishuApi, "listAppScopes">;
     note?: (message: string) => void;
-    openUrl?: (url: string) => void;
-}): Promise<GroupBehaviorSetup>;
+    /** Who is sent to the console page that requests a missing permission. */
+    person?: Person;
+}): Promise<AgentScopeCheck>;
 /** Create or resume the platform app behind `add feishu` / `add lark`. */
-export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", ingress?: FeishuSubscriptionMode, groupBehavior?: GroupBehaviorChoice): Promise<Record<string, string> | undefined>;
+export declare function onboardFeishuCloudApp(target: string, kind: "feishu" | "lark", ingress: FeishuSubscriptionMode, 
+/** The command that continues an interrupted setup: the one that started it. */
+rerun?: string, 
+/** Who takes the steps only a person can: at this terminal, or a coding agent's person through a ticket. */
+person?: Person): Promise<Record<string, string> | undefined>;
+/**
+ * Lark's app credentials, which only the person can get, from the app they create in Lark's console: with no one at a
+ * terminal to type them, the report naming where they set them (the selected environment's file), when either is
+ * absent. `again` is the command that continues once they have.
+ */
+export declare function larkCredentialsNeeded(agentDir: string, again: string): Promise<{
+    json: Record<string, unknown>;
+    text: string[];
+} | undefined>;
+export declare function feishuAppSecretNames(kind: "feishu" | "lark", ingress: FeishuSubscriptionMode): string[];
+interface FeishuAppSetup {
+    kind: "feishu" | "lark";
+    ingress: FeishuSubscriptionMode;
+}
+export declare function unpreparedFeishuApps(channels: readonly DeclaredChannel[], values: ReadonlyMap<string, string>): FeishuAppSetup[];
+export declare function assertIndependentFeishuApps(agentDir: string, kinds: readonly ("feishu" | "lark")[], values: ReadonlyMap<string, string>): void;
+export declare function prepareFeishuApps(agentDir: string, apps: readonly FeishuAppSetup[], rerun: string, person: Person, onboard?: typeof onboardFeishuCloudApp): Promise<void>;
+export {};