@fastagent-sh/fastagent 0.24.4 → 0.25.0

package/dist/channels/context.js

@@ -0,0 +1,35 @@
+/**
+ * What a channel is handed when it is mounted (channel.ts): the Agent, a directory of its own, the sessions its
+ * conversations talk in, and its turns. Every mount builds a channel's context here, so a channel file, a first-party
+ * channel and a test mount the same way.
+ */
+import { isAbsolute, join } from "node:path";
+import { conversationSessions, forkedSession } from "../conversation-sessions.js";
+import * as Effect from "effect/Effect";
+import { portError, portJoin } from "../effect-port.js";
+import { log } from "../log.js";
+import { ensureStateHome } from "../state-file.js";
+import { createTurnQueue } from "./turn-queue.js";
+/** The context of the channel `name` (its file's name under `src/channels/`), its state under `stateRoot`. */
+export function channelContext(agent, stateRoot, name) {
+    if (!isAbsolute(stateRoot))
+        throw new Error(`a channel's state root must be absolute, got "${stateRoot}"`);
+    const stateDir = join(stateRoot, "channels", name);
+    ensureStateHome(stateDir);
+    const sessions = conversationSessions(join(stateDir, "sessions.json"));
+    const turns = createTurnQueue({
+        label: `[${name}]`,
+        // The channel's own failure surface: `turn` promises a failed one goes to the log, said as the author wrote it.
+        run: ({ conversation, work }) => portJoin(work).pipe(Effect.catchCause((cause) => Effect.sync(() => log.error(`[${name}] turn failed (place=${conversation}): ${String(portError(cause))}`)))),
+    });
+    return {
+        agent,
+        stateDir,
+        sessionFor: (key, options) => {
+            const forkFrom = options?.forkFrom;
+            return sessions.of(key, agent, forkFrom === undefined ? undefined : async () => forkedSession(agent, await forkFrom()));
+        },
+        recordedSession: (key) => sessions.get(key),
+        turn: (place, work) => turns.accept({ conversation: place, work }),
+    };
+}

package/dist/channels/discover.d.ts

@@ -1,16 +1,18 @@
-import type { ChannelContext, LongConnection, Routes } from "../channel.ts";
-import { type ModuleLoadFailure } from "../loader.ts";
-import { type DeclaredSecret } from "../declared-secrets.ts";
-/** A dropped route: two channels claim the same key. */
-export interface ChannelCollision {
-    route: string;
-    source: string;
-}
+/**
+ * A definition's channels, mounted: each route channel's routes, and each long connection bound to its context. The
+ * modules are what the definition built (`BuiltDefinition.channels`); a channel's shape is checked there, by
+ * {@link channelModuleProblem}, and its routes here, where it is first called.
+ */
+import type { Agent } from "../agent-api.ts";
+import type { ChannelModule, LongConnection, LongConnectionChannelModule, Routes } from "../channel.ts";
+export type AnyChannelModule = ChannelModule | LongConnectionChannelModule;
 /** A long-connection module bound to the same context route factories receive. */
 export interface LoadedLongConnectionChannel {
     name: string;
     connect(signal: AbortSignal): LongConnection;
 }
+/** Why `value` is not a channel module: a route channel's `(ctx) => Routes`, or a long connection's object. */
+export declare function channelModuleProblem(value: unknown): string | undefined;
 /** HOW A CHANNEL IS REACHED — the authored structural fact, and the ONE shape it travels in. */
 export type ChannelIngress = "webhook" | "long-connection";
 /** One channel a directory declares, with the ingress its module shape says it has. */
@@ -20,18 +22,14 @@ export interface DeclaredChannel {
 }
 /** Declared channels from basenames that share one ingress. */
 export declare function declaredChannels(names: readonly string[], ingress?: ChannelIngress): DeclaredChannel[];
-/** Import channel files without mounting route factories or opening connections. */
-export declare function inspectChannels(dir: string): Promise<{
-    channels: DeclaredChannel[];
-    /** What each channel declared through {@link defineChannel}, BY CHANNEL NAME — the only way a
-     *  CUSTOM channel's credentials can reach a deploy, since nothing else here can name them. */
-    secrets: Map<string, DeclaredSecret[]>;
-    failures: ModuleLoadFailure[];
-}>;
-export declare function loadChannels(dir: string, ctx: ChannelContext): Promise<{
+/** How a channel module is reached: its routes, or the connection it opens. */
+export declare function channelIngress(module: AnyChannelModule): ChannelIngress;
+/**
+ * Mount the channels, each with its own context (context.ts): every route of every route channel (two claiming one
+ * route is refused), and the connections.
+ */
+export declare function mountChannels(modules: ReadonlyMap<string, AnyChannelModule>, agent: Agent, stateRoot: string): {
     routes: Routes;
     longConnections: LoadedLongConnectionChannel[];
     routeChannels: string[];
-    collisions: ChannelCollision[];
-    failures: ModuleLoadFailure[];
-}>;
+};

package/dist/channels/discover.js

@@ -1,50 +1,25 @@
-/** Channel discovery (the N axis, filesystem form). */
-import { isAbsolute, join } from "node:path";
-import { assertRouteKey, routeKeysConflict } from "./serve.js";
-import { loadModuleDir } from "../loader.js";
-import { readSecretDeclaration } from "../declared-secrets.js";
-import { gateSecrets } from "../secrets-gate.js";
-import { assertInsideAgentDir } from "../paths.js";
+import { channelContext } from "./context.js";
+import { assertRouteKey, routeKeysConflict } from "./router.js";
 function longConnectionModule(value) {
     return value !== null && typeof value === "object" && typeof value.connect === "function";
 }
-function validateLongConnectionModule(value, label) {
-    if (typeof value.name !== "string" || value.name.trim() === "") {
-        throw new Error(`${label}: long-connection channel name must be a non-empty string`);
-    }
+/** Why `value` is not a channel module: a route channel's `(ctx) => Routes`, or a long connection's object. */
+export function channelModuleProblem(value) {
+    if (typeof value === "function")
+        return undefined;
+    if (!longConnectionModule(value))
+        return "must default-export (ctx) => Routes or { name, connect(ctx, signal) }";
+    return typeof value.name === "string" && value.name.trim() !== ""
+        ? undefined
+        : "long-connection channel name must be a non-empty string";
 }
 /** Declared channels from basenames that share one ingress. */
 export function declaredChannels(names, ingress = "webhook") {
     return names.map((name) => ({ name, ingress }));
 }
-/** Import channel files without mounting route factories or opening connections. */
-export async function inspectChannels(dir) {
-    await assertInsideAgentDir(dir, "channels");
-    const { modules, failures } = await loadModuleDir(join(dir, "channels"));
-    const channels = [];
-    const secrets = new Map();
-    for (const { name, label, file, mod } of modules) {
-        try {
-            const declaration = readSecretDeclaration(mod.default, label);
-            if (declaration.error !== undefined)
-                throw new Error(declaration.error);
-            if (typeof mod.default === "function") {
-                channels.push({ name, ingress: "webhook" });
-            }
-            else if (longConnectionModule(mod.default)) {
-                validateLongConnectionModule(mod.default, label);
-                channels.push({ name, ingress: "long-connection" });
-            }
-            else {
-                throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
-            }
-            secrets.set(name, declaration.secrets);
-        }
-        catch (error) {
-            failures.push({ label, file, message: error.message });
-        }
-    }
-    return { channels, secrets, failures };
+/** How a channel module is reached: its routes, or the connection it opens. */
+export function channelIngress(module) {
+    return typeof module === "function" ? "webhook" : "long-connection";
 }
 function validateRoutes(value, label) {
     if (value === null || typeof value !== "object" || value instanceof Map) {
@@ -62,71 +37,38 @@ function validateRoutes(value, label) {
     }
     return routes;
 }
-export async function loadChannels(dir, ctx) {
-    if (!isAbsolute(ctx.stateRoot)) {
-        throw new Error(`ChannelContext.stateRoot must be absolute, got "${ctx.stateRoot}"`);
-    }
-    await assertInsideAgentDir(dir, "channels");
-    const { modules, failures } = await loadModuleDir(join(dir, "channels"));
+/**
+ * Mount the channels, each with its own context (context.ts): every route of every route channel (two claiming one
+ * route is refused), and the connections.
+ */
+export function mountChannels(modules, agent, stateRoot) {
     const routes = {};
+    const owners = new Map();
     const longConnections = [];
     const routeChannels = [];
-    const collisions = [];
-    // Collected from the channels that actually MOUNTED, GATED at the end of the function: this is a
-    // serving path, so an unset declared value must stop it (a channel built from an empty credential
-    // is the failure the declaration exists to prevent — a webhook that accepts forged updates, a bot
-    // that cannot reply), while `inspectChannels` — the reporting reader — only collects. A channel
-    // that failed to mount does not gate: its own failure is the report the author needs.
-    const declaredSecrets = new Map();
-    const declaring = modules.flatMap((entry) => {
-        const declaration = readSecretDeclaration(entry.mod.default, entry.label);
-        if (declaration.error !== undefined) {
-            failures.push({ label: entry.label, file: entry.file, message: declaration.error });
-            return [];
+    for (const [name, module] of modules) {
+        const label = `src/channels/${name}`;
+        const ctx = channelContext(agent, stateRoot, name);
+        if (typeof module !== "function") {
+            longConnections.push({ name: module.name, connect: (signal) => module.connect(ctx, signal) });
+            continue;
         }
-        return [{ ...entry, secrets: declaration.secrets }];
-    });
-    for (const { name, label, file, mod, secrets } of declaring) {
-        try {
-            if (longConnectionModule(mod.default)) {
-                validateLongConnectionModule(mod.default, label);
-                const channel = mod.default;
-                longConnections.push({
-                    name: channel.name,
-                    connect: (signal) => channel.connect(ctx, signal),
-                });
-                declaredSecrets.set(name, secrets);
-                continue;
-            }
-            if (typeof mod.default !== "function") {
-                throw new Error(`${label} must default-export (ctx) => Routes or { name, connect(ctx, signal) }`);
-            }
-            const declared = mod.default(ctx);
-            if (declared !== null &&
-                typeof declared === "object" &&
-                typeof declared.then === "function") {
-                declared.catch(() => { });
-                throw new Error(`${label} must return Routes synchronously, not a Promise`);
-            }
-            const declaredRoutes = validateRoutes(declared, label);
-            for (const [route, handler] of declaredRoutes) {
-                const clash = Object.keys(routes).some((key) => routeKeysConflict(key, route));
-                if (clash) {
-                    collisions.push({ route, source: label });
-                    continue;
-                }
-                routes[route] = handler;
-            }
-            routeChannels.push(name);
-            declaredSecrets.set(name, secrets);
+        const declared = module(ctx);
+        if (declared !== null &&
+            typeof declared === "object" &&
+            typeof declared.then === "function") {
+            declared.catch(() => { });
+            throw new Error(`${label} must return Routes synchronously, not a Promise`);
         }
-        catch (error) {
-            failures.push({ label, file, message: error.message });
+        for (const [route, handler] of validateRoutes(declared, label)) {
+            const taken = [...owners.keys()].find((key) => routeKeysConflict(key, route));
+            if (taken !== undefined) {
+                throw new Error(`${label} serves "${route}", which ${owners.get(taken)} already serves as "${taken}"`);
+            }
+            owners.set(route, label);
+            routes[route] = handler;
         }
+        routeChannels.push(name);
     }
-    // Gated LAST, after the loop has said what it found (the gate reports those failures before it
-    // refuses — src/secrets-gate.ts, decision 2). Binding a module ahead of the gate costs nothing: a
-    // route factory builds handlers; nothing listens or dials until the caller mounts what this returns.
-    gateSecrets({ declared: declaredSecrets, failures });
-    return { routes, longConnections, routeChannels, collisions, failures };
+    return { routes, longConnections, routeChannels };
 }

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

@@ -1,4 +1,4 @@
-import type { ImageRef } from "../../agent.ts";
+import type { ImageAttachment as ImageRef } from "../kit/invoke-turn-kit.ts";
 import type { FeishuCloudKind } from "./cloud.ts";
 import type { CallOptions } from "../kit/transport.ts";
 /** Where a reply goes: a chat, optionally quote-replying a message inside a platform thread. */
@@ -35,6 +35,31 @@ export interface FeishuApiOptions {
     appId: string;
     appSecret: string;
 }
+/** One message as `GET /im/v1/messages` lists it — the fields the history read uses. */
+export interface FeishuListedMessage {
+    message_id?: string;
+    chat_id?: string;
+    msg_type?: string;
+    /** Milliseconds since the epoch, as a string. */
+    create_time?: string;
+    parent_id?: string;
+    root_id?: string;
+    thread_id?: string;
+    deleted?: boolean;
+    body?: {
+        content?: string;
+    };
+    mentions?: {
+        key?: string;
+        name?: string;
+        id?: string;
+    }[];
+    sender?: {
+        id?: string;
+        id_type?: string;
+        sender_type?: string;
+    };
+}
 export interface FeishuAppScope {
     name: string;
     grantStatus: number;
@@ -45,6 +70,12 @@ export interface FeishuAppScope {
  * single pipeline (module header). Throws {@link FeishuApiError} on any failure.
  */
 export interface FeishuApi {
+    /**
+     * This client over the same pipeline and token cache, reporting the id of every message it creates (a send, a reply,
+     * each chunk of a long text). The channel sends through one to know which messages in a chat's history are its own
+     * turn output; the send tool shares the plain client, so what the agent sends itself stays part of the discussion.
+     */
+    recordingSends(onSent: (messageId: string) => void): FeishuApi;
     /** Validate appId/appSecret by acquiring the tenant token through this pipeline. Does not require
      *  the bot capability (unlike botInfo), so guided onboarding can fail before persisting a typo. */
     verifyCredentials(): Promise<void>;
@@ -66,6 +97,28 @@ export interface FeishuApi {
     editTextMessage(messageId: string, text: string): Promise<void>;
     /** Recall (delete) a message the bot sent. */
     deleteMessage(messageId: string): Promise<void>;
+    /**
+     * A place's messages, NEWEST first: a chat's (an ordinary group lists a thread's root only; a topic group lists
+     * every message) or a thread's. Cards come back as sent, and senders as open_ids.
+     */
+    listMessages(container: {
+        type: "chat" | "thread";
+        id: string;
+    }, pageSize: number, 
+    /** Seconds since the epoch, inclusive: list nothing created after this second. */
+    endTime?: number, opts?: CallOptions): Promise<{
+        items: FeishuListedMessage[];
+        hasMore: boolean;
+    }>;
+    /**
+     * Names for `wanted` open_ids among a chat's members (needs `im:chat.members:read`). Pages until every wanted id is
+     * named or the member list ends, up to {@link MEMBER_PAGES} pages; `complete` says whether the list was read to its
+     * end, so an id still unnamed is known not to be a member rather than beyond the cap.
+     */
+    chatMemberNames(chatId: string, wanted: ReadonlySet<string>, opts?: CallOptions): Promise<{
+        names: Map<string, string>;
+        complete: boolean;
+    }>;
     /** Fetch one message (the reply-referent path). Undefined when the API returns no item.
      *
      *  `sender` is typed rather than `unknown` because the referent path READS it: an app-sent message
@@ -105,9 +158,6 @@ export interface FeishuApi {
     /** List the app's scopes and grant state. Used by onboarding/runtime to make group visibility
      * explicit instead of silently assuming unmentioned group events are delivered. */
     listAppScopes(): Promise<FeishuAppScope[]>;
-    /** Add tenant scopes to the app draft through application-v7 config. Approval + version publishing
-     * remain console actions; this method only removes the error-prone manual draft edit. */
-    addAppScopes(appId: string, scopeNames: string[]): Promise<void>;
     /** Update the app's own event subscription (application-v7 config PATCH — tenant token can only
      *  operate on itself; the request-URL change takes effect immediately, no version publish). The
      *  platform VERIFIES `requestUrl` with a url_verification challenge during this call, so the server