@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/slack.d.ts

@@ -1,4 +1,4 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
-export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
+export { slackChannel, slackSocketChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, type SlackChannelOptions, type SlackSocketChannelOptions, type SlackEventEnvelope, type SlackFile, type SlackMessageEvent, type SlackRendering, type SlackRoute, type SlackFailure, } from "./channels/slack/slack.ts";
 export { slackThreads, slackTransport, type SlackTransport } from "./channels/slack/shared-api.ts";
 export type { SentSlackMessage, SlackTarget, UploadedSlackFile } from "./channels/slack/slack-api.ts";

package/dist/slack.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/slack` — the first-party Slack Events API bot-channel surface. */
-export { slackChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
+export { slackChannel, slackSocketChannel, defaultSlackRoute, slackEnvelope, verifySlackSignature, } from "./channels/slack/slack.js";
 export { slackThreads, slackTransport } from "./channels/slack/shared-api.js";

package/dist/strip-edges.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Text without the characters at its ends that `isEdge` names, found by index. A regex for it (`/^-+|-+$/`, `/\/+$/`)
+ * backtracks quadratically on a long run that is not at the end, and what is trimmed here is often a name or a URL
+ * somebody else wrote.
+ */
+export declare function stripEdges(text: string, isEdge: (char: string) => boolean): string;
+/** `text` without the characters at its end that `isEdge` names. */
+export declare function stripEnd(text: string, isEdge: (char: string) => boolean): string;
+/** A URL or path without the `/` that ends it. */
+export declare function stripTrailingSlashes(text: string): string;

package/dist/strip-edges.js

@@ -0,0 +1,22 @@
+/**
+ * Text without the characters at its ends that `isEdge` names, found by index. A regex for it (`/^-+|-+$/`, `/\/+$/`)
+ * backtracks quadratically on a long run that is not at the end, and what is trimmed here is often a name or a URL
+ * somebody else wrote.
+ */
+export function stripEdges(text, isEdge) {
+    let start = 0;
+    while (start < text.length && isEdge(text[start]))
+        start++;
+    return stripEnd(text.slice(start), isEdge);
+}
+/** `text` without the characters at its end that `isEdge` names. */
+export function stripEnd(text, isEdge) {
+    let end = text.length;
+    while (end > 0 && isEdge(text[end - 1]))
+        end--;
+    return text.slice(0, end);
+}
+/** A URL or path without the `/` that ends it. */
+export function stripTrailingSlashes(text) {
+    return stripEnd(text, (char) => char === "/");
+}

package/dist/telegram.d.ts

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
-export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
+export { telegramChannel, telegramPollingChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, type TelegramChannelOptions, type TelegramPollingChannelOptions, type TelegramUpdate, type TelegramMessage, type TelegramRoute, type TelegramFailure, } from "./channels/telegram/telegram.ts";
 export { telegramTransport, type TelegramSendTarget, type TelegramSent, type TelegramTransport, } from "./channels/telegram/shared-api.ts";

package/dist/telegram.js

@@ -1,3 +1,3 @@
 /** `@fastagent-sh/fastagent/telegram` — the Telegram bot channel subpath export, kept off the root surface. */
-export { telegramChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";
+export { telegramChannel, telegramPollingChannel, defaultTelegramRoute, telegramEnvelope, telegramStop, } from "./channels/telegram/telegram.js";
 export { telegramTransport, } from "./channels/telegram/shared-api.js";

package/dist/tunnel.d.ts

@@ -26,7 +26,6 @@ export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloud
 /** Print the public URL and wire up first-party webhook channels found under `dir` (the agent ROOT). */
 export declare function announceWebhooks(dir: string, baseUrl: string, channels: readonly DeclaredChannel[], opts?: {
     openUrl?: (url: string) => void;
-    stateRoot?: string;
     env?: NodeJS.ProcessEnv;
     /** {@link Registrars.leave}. */
     leave?: (step: string) => void;

package/dist/tunnel.js

@@ -5,13 +5,12 @@
  */
 import { spawn } from "node:child_process";
 import { registerFeishuWebhook } from "./channels/feishu/register-webhook.js";
-import { registerSlackWebhook } from "./channels/slack/register-webhook.js";
 import { registerTelegramWebhook } from "./channels/telegram/register-webhook.js";
-import { pointChannelsAt, webhookKinds } from "./deploy/channel-ingress.js";
+import { pointChannelsAt } from "./deploy/channel-ingress.js";
+import { webhookKinds } from "./channels/webhooks.js";
 import { loadDotEnv } from "./env.js";
 import { dotEnvPath } from "./value-file.js";
 import { installProxyFetch } from "./proxy.js";
-import { AGENT_ENVIRONMENT_ENV, resolveStateRoot } from "./paths.js";
 import { log } from "./log.js";
 // `(?!api\.)`: cloudflared's ERROR lines mention its request endpoint (`https://api.trycloudflare.com/tunnel`, e.g.
 // "failed to request quick Tunnel: Post ... timeout" under a flaky proxy) — without the exclusion a transient error
@@ -157,11 +156,6 @@ export async function announceWebhooks(dir, baseUrl, channels, opts = {}) {
         registrars: {
             ...(opts.leave === undefined ? {} : { leave: opts.leave }),
             telegram: (url) => registerTelegramWebhook(url, { env: opts.env }),
-            slack: (url) => registerSlackWebhook(url, {
-                stateRoot: opts.stateRoot ?? resolveStateRoot(dir),
-                environment: process.env[AGENT_ENVIRONMENT_ENV] === "production" ? "production" : "dev",
-                log: (message) => log.info(message),
-            }),
             feishu: (url, kind) => registerFeishuWebhook(url, kind, feishuOptions),
         },
     });

package/dist/value-file.d.ts

@@ -7,7 +7,9 @@ export declare function parseEnvContent(content: string): Map<string, string>;
  * is no values, which is normal.
  */
 export declare function loadEnvValues(file: string): Map<string, string>;
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+/** Use `path` as the agent's value file from here on, or the default again. */
+export declare function useValueFile(path: string | undefined): void;
+/** The agent's `.env` file: the one `--env-file` named, else `<resolved secrets dir>/.env`. */
 export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
 /** The committable template: `<agentDir>/.secrets/.env.example`. */
 export declare function envExamplePath(agentDir: string): string;
@@ -31,11 +33,14 @@ export interface ValueWriteResult {
     /** Set when the secrets dir is an operator-chosen one (`FASTAGENT_SECRETS_DIR`) carrying no `.gitignore`. */
     unprotectedSecretsDir?: string;
 }
-/** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
-export declare function unprotectedSecretsNote(dir: string): string;
+/**
+ * What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track; `chosenBy`
+ * is what put the secrets there (the operator's `FASTAGENT_SECRETS_DIR`, unless the caller knows better).
+ */
+export declare function unprotectedSecretsNote(dir: string, chosenBy?: string): string;
 export declare function prepareSecretsDirectory(dir: string, secretsDir: string): Promise<string | undefined>;
 /**
- * Write `entries` into the selected environment's value file, under a `# --- <section> ---` line. A name with a
- * non-empty active value is kept unless `overwrite` names it.
+ * Write `entries` into `file` (default: the selected environment's value file), under a `# --- <section> ---` line. A
+ * name with a non-empty active value is kept unless `overwrite` names it.
  */
-export declare function writeValues(dir: string, section: string, entries: readonly ValueEntry[], overwrite?: readonly string[]): Promise<ValueWriteResult>;
+export declare function writeValues(dir: string, section: string, entries: readonly ValueEntry[], overwrite?: readonly string[], file?: string): Promise<ValueWriteResult>;

package/dist/value-file.js

@@ -44,9 +44,19 @@ export function loadEnvValues(file) {
         throw error;
     }
 }
-/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
+/**
+ * The value file this process's command was told to use (`--env-file`). Process state set at the command's entry, not
+ * an environment variable: a variable would be read from a shell, by commands that never took the flag, and by what
+ * the agent runs. A `dev` worker is spawned with its supervisor's arguments and takes the flag itself.
+ */
+let selectedValueFile;
+/** Use `path` as the agent's value file from here on, or the default again. */
+export function useValueFile(path) {
+    selectedValueFile = path;
+}
+/** The agent's `.env` file: the one `--env-file` named, else `<resolved secrets dir>/.env`. */
 export function dotEnvPath(agentDir, env = process.env) {
-    return join(resolveSecretsDir(agentDir, env), ".env");
+    return selectedValueFile ?? join(resolveSecretsDir(agentDir, env), ".env");
 }
 /** The committable template: `<agentDir>/.secrets/.env.example`. */
 export function envExamplePath(agentDir) {
@@ -64,9 +74,12 @@ export function agentValues(agentDir) {
             values[key] = value;
     return values;
 }
-/** What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track. */
-export function unprotectedSecretsNote(dir) {
-    return (`${dir} (FASTAGENT_SECRETS_DIR) now holds a secret and has no .gitignore — that directory is yours, so ` +
+/**
+ * What a command says when it wrote a secret into a secrets directory fastagent does not own and git may track; `chosenBy`
+ * is what put the secrets there (the operator's `FASTAGENT_SECRETS_DIR`, unless the caller knows better).
+ */
+export function unprotectedSecretsNote(dir, chosenBy = "FASTAGENT_SECRETS_DIR") {
+    return (`${dir} (${chosenBy}) now holds a secret and has no .gitignore — that directory is yours, so ` +
         "fastagent will not write one into it. Make sure git does not track what is in there.");
 }
 export async function prepareSecretsDirectory(dir, secretsDir) {
@@ -91,11 +104,10 @@ function mentionsEnvName(content, name) {
     return content.split("\n").some((line) => new RegExp(`^\\s*#?\\s*${name}\\s*=`).test(line));
 }
 /**
- * Write `entries` into the selected environment's value file, under a `# --- <section> ---` line. A name with a
- * non-empty active value is kept unless `overwrite` names it.
+ * Write `entries` into `file` (default: the selected environment's value file), under a `# --- <section> ---` line. A
+ * name with a non-empty active value is kept unless `overwrite` names it.
  */
-export async function writeValues(dir, section, entries, overwrite = []) {
-    const file = dotEnvPath(dir);
+export async function writeValues(dir, section, entries, overwrite = [], file = dotEnvPath(dir)) {
     const unprotectedSecretsDir = await prepareSecretsDirectory(dir, dirname(file));
     let current = "";
     try {

package/dist/version.d.ts

@@ -3,8 +3,14 @@
  * scaffolded dependency range (`^${version}`), so `init` must never fall back and scaffold an uninstallable `^0.0.0`.
  */
 export declare function fastagentVersion(): Promise<string>;
-/** This build's version, and the exact versions of the harness packages it runs, for a new agent to depend on. */
+/** The packages an agent's code imports besides fastagent: the harness its tools and providers are written for. */
+export declare const HARNESS_PACKAGES: string[];
+/**
+ * This build's version, the exact versions of the harness packages it runs, and the TypeScript `fastagent build`
+ * compiles with (FastAgent's own), for a new agent to depend on.
+ */
 export declare function fastagentBuild(): Promise<{
     version: string;
     harness: Record<string, string>;
+    typescript: string;
 }>;

package/dist/version.js

@@ -8,8 +8,11 @@ export async function fastagentVersion() {
     return (await fastagentBuild()).version;
 }
 /** The packages an agent's code imports besides fastagent: the harness its tools and providers are written for. */
-const HARNESS_PACKAGES = ["@earendil-works/pi-durable", "@earendil-works/pi-ai"];
-/** This build's version, and the exact versions of the harness packages it runs, for a new agent to depend on. */
+export const HARNESS_PACKAGES = ["@earendil-works/pi-durable", "@earendil-works/pi-ai", "@earendil-works/pi-schema"];
+/**
+ * This build's version, the exact versions of the harness packages it runs, and the TypeScript `fastagent build`
+ * compiles with (FastAgent's own), for a new agent to depend on.
+ */
 export async function fastagentBuild() {
     const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
     const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
@@ -22,5 +25,8 @@ export async function fastagentBuild() {
             throw new Error(`${pkgPath} does not depend on ${name}`);
         harness[name] = range;
     }
-    return { version: pkg.version, harness };
+    const typescript = pkg.devDependencies?.typescript;
+    if (typescript === undefined)
+        throw new Error(`${pkgPath} does not develop with typescript`);
+    return { version: pkg.version, harness, typescript };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",
@@ -88,9 +88,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/chord": "1.4.0",
-    "@earendil-works/pi-ai": "1.4.0",
-    "@earendil-works/pi-durable": "1.4.0",
+    "@earendil-works/chord": "1.5.0",
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-durable": "1.5.0",
+    "@earendil-works/pi-schema": "1.5.0",
     "@effect/platform-bun": "^4.0.7",
     "@effect/platform-node": "^4.0.7",
     "@larksuiteoapi/node-sdk": "^1.76.0",
@@ -108,7 +109,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.6.4",
-    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
     "@hono/node-server": "^2.1.5",
     "@modelcontextprotocol/server": "2.4.0",
     "@types/express": "^5.0.6",

package/dist/channels/lark/credentials-page.d.ts

@@ -1,25 +0,0 @@
-export interface LarkCredentials {
-    appId: string;
-    appSecret: string;
-}
-export declare class LarkCredentialsRefused extends Error {
-    readonly fix: string | undefined;
-    readonly why: string | undefined;
-    constructor(headline: string, options?: {
-        fix?: string;
-        why?: string;
-    });
-}
-export interface LarkCredentialsPage<T = LarkCredentials> {
-    url: string;
-    credentials: Promise<T>;
-    close(): Promise<void>;
-}
-export declare function startLarkCredentialsPage(input: {
-    consoleUrl: string;
-    check(credentials: LarkCredentials): Promise<void>;
-}): Promise<LarkCredentialsPage>;
-export declare function startLarkVerificationPage(input: {
-    consoleUrl: string;
-    save(token: string): Promise<void>;
-}): Promise<LarkCredentialsPage<string>>;

package/dist/channels/lark/credentials-page.js

@@ -1,206 +0,0 @@
-/** Loopback-only, single-use forms for Lark setup secrets; values never pass through the agent's conversation. */
-import { randomBytes } from "node:crypto";
-import { createServer } from "node:http";
-import { field, formCard, openButton, privacy, prose, refusal, sendPage, setupRequestUrl, statusCard, step, submit, } from "../../setup-page.js";
-export class LarkCredentialsRefused extends Error {
-    fix;
-    why;
-    constructor(headline, options = {}) {
-        super(headline);
-        this.name = "LarkCredentialsRefused";
-        this.fix = options.fix;
-        this.why = options.why;
-    }
-}
-function readBody(request) {
-    return new Promise((resolve) => {
-        let body = "";
-        let tooLarge = false;
-        request.on("data", (chunk) => {
-            if (tooLarge)
-                return;
-            body += String(chunk);
-            if (Buffer.byteLength(body) > 16 * 1024)
-                tooLarge = true;
-        });
-        request.on("end", () => resolve(tooLarge ? undefined : body));
-        request.on("error", () => resolve(undefined));
-    });
-}
-export function startLarkCredentialsPage(input) {
-    return startPage({
-        heading: "Lark credentials verified",
-        form: (pasted, problem) => formCard("Connect Lark", [
-            step(1, "Create the app in Lark", prose("It opens with the permissions and event your agent needs already set.") +
-                openButton("Open Lark", input.consoleUrl)),
-            step(2, "Paste its credentials", (problem
-                ? refusal(problem.message, problem.fix, problem.why)
-                : prose("Find them under <b>Credentials &amp; Basic Info</b>.")) +
-                field({
-                    id: "app_id",
-                    label: "App ID",
-                    placeholder: "cli_…",
-                    value: pasted.get("app_id") ?? "",
-                    invalid: !!problem,
-                }) +
-                field({ id: "app_secret", label: "App Secret", secret: true, invalid: !!problem, autofocus: !!problem }) +
-                submit("Save and check") +
-                privacy()),
-        ].join("")),
-        accept: async (pasted) => {
-            const pair = { appId: (pasted.get("app_id") ?? "").trim(), appSecret: (pasted.get("app_secret") ?? "").trim() };
-            if (!pair.appId || !pair.appSecret) {
-                throw new LarkCredentialsRefused("Both values are needed.", {
-                    fix: "Copy the App ID and the App Secret from Credentials & Basic Info.",
-                });
-            }
-            await input.check(pair);
-            return pair;
-        },
-    });
-}
-export function startLarkVerificationPage(input) {
-    return startPage({
-        heading: "Verification Token saved",
-        form: (_pasted, problem) => formCard("Finish Lark webhook setup", [
-            step(1, "Copy the Verification Token", prose("Find it under <b>Events &amp; Callbacks</b> → Encryption Strategy. Choose webhook mode when setting the Request URL.") + openButton("Open Lark", input.consoleUrl)),
-            step(2, "Paste the token here", (problem ? refusal(problem.message, problem.fix) : "") +
-                field({
-                    id: "verification_token",
-                    label: "Verification Token",
-                    secret: true,
-                    invalid: !!problem,
-                    autofocus: !!problem,
-                }) +
-                submit("Save token") +
-                privacy()),
-        ].join("")),
-        accept: async (pasted) => {
-            const token = (pasted.get("verification_token") ?? "").trim();
-            if (!token)
-                throw new LarkCredentialsRefused("Verification Token is required.");
-            await input.save(token);
-            return token;
-        },
-    });
-}
-// A browser can leave during validation, before either response event can be subscribed to.
-function afterResponse(response, complete) {
-    if (response.destroyed || response.writableFinished)
-        complete();
-    else
-        response.once("close", complete);
-}
-async function startPage(input) {
-    const path = `/lark/credentials/${randomBytes(24).toString("hex")}`;
-    const { promise: credentials, resolve, reject } = Promise.withResolvers();
-    let checking = false;
-    let used = false;
-    let port = 0;
-    const server = createServer(async (request, response) => {
-        const url = setupRequestUrl(request, response);
-        if (url === undefined)
-            return;
-        const host = request.headers.host ?? "";
-        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) {
-            response.writeHead(421).end("misdirected request\n");
-            return;
-        }
-        if (url.pathname !== path || (request.method !== "GET" && request.method !== "POST")) {
-            response.writeHead(404).end("not found\n");
-            return;
-        }
-        const expired = () => sendPage(response, 404, {
-            title: "FastAgent setup",
-            card: statusCard({
-                state: "failed",
-                heading: "This page is no longer in use",
-                next: "Go back to your coding agent.",
-            }),
-        });
-        if (used) {
-            expired();
-            return;
-        }
-        if (request.method === "GET") {
-            sendPage(response, 200, { title: "Connect Lark — FastAgent", card: input.form(new URLSearchParams()) });
-            return;
-        }
-        const site = request.headers["sec-fetch-site"];
-        if (site !== undefined && site !== "same-origin") {
-            response.writeHead(403).end("forbidden\n");
-            return;
-        }
-        const body = await readBody(request);
-        if (body === undefined) {
-            response.writeHead(413).end("payload too large\n");
-            return;
-        }
-        if (used) {
-            expired();
-            return;
-        }
-        if (checking) {
-            response.writeHead(409).end("another submission is being checked\n");
-            return;
-        }
-        checking = true;
-        const pasted = new URLSearchParams(body);
-        let accepted;
-        try {
-            accepted = await input.accept(pasted);
-        }
-        catch (error) {
-            checking = false;
-            // Only explicit input refusals stay on the form. Infrastructure and persistence errors fail the ticket.
-            if (error instanceof LarkCredentialsRefused) {
-                sendPage(response, 200, { title: "Connect Lark — FastAgent", card: input.form(pasted, error) });
-                return;
-            }
-            used = true;
-            afterResponse(response, () => reject(error));
-            sendPage(response, 200, {
-                title: "Setup stopped — FastAgent",
-                card: statusCard({
-                    state: "failed",
-                    heading: "Setup stopped",
-                    lede: error instanceof Error ? error.message : String(error),
-                    next: "Go back to your coding agent.",
-                }),
-            });
-            return;
-        }
-        used = true;
-        afterResponse(response, () => resolve(accepted));
-        sendPage(response, 200, {
-            title: `${input.heading} — FastAgent`,
-            card: statusCard({
-                state: "done",
-                heading: input.heading,
-                lede: "Your coding agent will say if anything is left to do in Lark.",
-                next: "Go back to your coding agent.",
-            }),
-        });
-    });
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", reject);
-            resolve();
-        });
-    });
-    const address = server.address();
-    if (!address || typeof address === "string") {
-        server.close();
-        throw new Error("the Lark credentials page did not receive a local TCP port");
-    }
-    port = address.port;
-    return {
-        url: `http://127.0.0.1:${port}${path}`,
-        credentials,
-        close: () => new Promise((resolve) => {
-            server.close(() => resolve());
-            server.closeAllConnections();
-        }),
-    };
-}

package/dist/channels/lark/onboard.d.ts

@@ -1,52 +0,0 @@
-import { type FeishuSubscriptionMode } from "../feishu/setup-mode.ts";
-/** Guided Lark-international onboarding. */
-/**
- * Lark's one-click launcher, where the person creates the app. The launcher is unbound (the bound confirm page is broken
- * on the international cloud), but it merges the `addons` query parameter onto the app it creates, as Feishu's does: the
- * scopes and the event the channel needs arrive with the app, so nothing is ticked in the console afterwards. A tenant
- * may still withhold a scope; the permission check that follows creation names it.
- */
-export declare function larkConsoleUrl(ingress: FeishuSubscriptionMode): string;
-/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
-export declare function larkEventSecurityUrl(appId: string): string;
-export interface LarkOnboardIO {
-    /** A page for the person, and what they do there. */
-    openUrl(url: string, action: string): void;
-    note(message: string): void;
-    prompt(message: string, opts?: {
-        hidden?: boolean;
-    }): Promise<string | undefined>;
-    verificationToken?(consoleUrl: string): Promise<string>;
-    collect?(input: {
-        /** Lark's launcher, with what the channel needs set on the app it creates. */
-        consoleUrl: string;
-        check(appId: string, appSecret: string): Promise<void>;
-    }): Promise<{
-        appId: string;
-        appSecret: string;
-    }>;
-}
-interface LarkBootstrapResult {
-    /** Challenge-captured token: the PATCH also switched Subscription mode to webhook. */
-    token?: string;
-    /** Present only for a definitive config-route 404; tells the user why the manual path is active. */
-    manualReason?: string;
-}
-export interface LarkOnboardOptions {
-    /** Existing active .env values. */
-    existing?: Readonly<Record<string, string | undefined>>;
-    ingress?: FeishuSubscriptionMode;
-    verifyCredentials(appId: string, appSecret: string): Promise<void>;
-    keep?(appId: string, appSecret: string): Promise<void>;
-    bootstrapWebhook?(appId: string, appSecret: string): Promise<LarkBootstrapResult>;
-    /** The command that continues an interrupted setup: the one that started it (`add lark`, `deploy <host> --run`). */
-    rerun?: string;
-}
-export interface LarkOnboardCredentials {
-    LARK_APP_ID: string;
-    LARK_APP_SECRET: string;
-    LARK_VERIFICATION_TOKEN?: string;
-}
-/** Open the stable app console and collect everything the runtime needs. */
-export declare function onboardLarkApp(io: LarkOnboardIO, opts: LarkOnboardOptions): Promise<LarkOnboardCredentials>;
-export {};

package/dist/channels/lark/onboard.js

@@ -1,86 +0,0 @@
-import { encodeAddons } from "../feishu/register-app.js";
-import { feishuAppAddons } from "../feishu/setup-mode.js";
-/** Guided Lark-international onboarding. */
-/**
- * Lark's one-click launcher, where the person creates the app. The launcher is unbound (the bound confirm page is broken
- * on the international cloud), but it merges the `addons` query parameter onto the app it creates, as Feishu's does: the
- * scopes and the event the channel needs arrive with the app, so nothing is ticked in the console afterwards. A tenant
- * may still withhold a scope; the permission check that follows creation names it.
- */
-export function larkConsoleUrl(ingress) {
-    const url = new URL("https://open.larksuite.com/page/launcher");
-    url.searchParams.set("from", "backend_oneclick");
-    url.searchParams.set("addons", encodeAddons(feishuAppAddons(ingress)));
-    return url.toString();
-}
-/** Directly where the fallback token lives (and where the successful automatic mode change is visible). */
-export function larkEventSecurityUrl(appId) {
-    return `https://open.larksuite.com/app/${encodeURIComponent(appId)}/event?tab=safe`;
-}
-function required(value, name, rerun) {
-    const trimmed = value?.trim();
-    if (!trimmed)
-        throw new Error(`${name} is required — re-run \`${rerun}\` to continue setup`);
-    return trimmed;
-}
-/** Open the stable app console and collect everything the runtime needs. */
-export async function onboardLarkApp(io, opts) {
-    const rerun = opts.rerun ?? "fastagent add lark";
-    const existingId = opts.existing?.LARK_APP_ID?.trim();
-    const existingSecret = opts.existing?.LARK_APP_SECRET?.trim();
-    const reuseExistingApp = Boolean(existingId && existingSecret);
-    // Credentials are one App-scoped set.
-    // No ingress named is the webhook path below (a deploy's production app).
-    const consoleUrl = larkConsoleUrl(opts.ingress ?? "webhook");
-    let appId;
-    let appSecret;
-    const verify = async (appId, appSecret) => {
-        await opts.verifyCredentials(appId, appSecret);
-        if (!reuseExistingApp)
-            await opts.keep?.(appId, appSecret);
-    };
-    if (reuseExistingApp) {
-        io.note(`Reusing Lark app ${existingId}.`);
-        appId = required(existingId, "LARK_APP_ID", rerun);
-        appSecret = required(existingSecret, "LARK_APP_SECRET", rerun);
-        await verify(appId, appSecret);
-    }
-    else if (io.collect) {
-        ({ appId, appSecret } = await io.collect({ consoleUrl, check: verify }));
-    }
-    else {
-        io.openUrl(consoleUrl, "create the app on Lark's one-click launcher; LARK_APP_ID and LARK_APP_SECRET are under Credentials & Basic Info");
-        appId = required(await io.prompt("LARK_APP_ID (Credentials & Basic Info)", { hidden: false }), "LARK_APP_ID", rerun);
-        appSecret = required(await io.prompt("LARK_APP_SECRET (Credentials & Basic Info)", { hidden: true }), "LARK_APP_SECRET", rerun);
-        await verify(appId, appSecret);
-    }
-    const eventSecurityUrl = larkEventSecurityUrl(appId);
-    io.note("App ID / Secret verified.");
-    if (opts.ingress === "websocket") {
-        io.openUrl(eventSecurityUrl, "in Events & Callbacks, choose long connection and subscribe im.message.receive_v1, but do not publish yet: " +
-            "the permission check follows (no Verification Token or Request URL is needed)");
-        return { LARK_APP_ID: appId, LARK_APP_SECRET: appSecret };
-    }
-    io.note("Trying automatic webhook-mode + Verification-Token bootstrap…");
-    if (!opts.bootstrapWebhook)
-        throw new Error("Lark webhook onboarding requires bootstrapWebhook");
-    const bootstrap = await opts.bootstrapWebhook(appId, appSecret);
-    if (bootstrap.token) {
-        io.note("Verification Token captured; Subscription mode changed to webhook in the app draft.");
-    }
-    else {
-        io.note(bootstrap.manualReason ?? "Automatic bootstrap unavailable.");
-        io.openUrl(eventSecurityUrl, "in Events & Callbacks → Encryption Strategy, copy the Verification Token, and switch Subscription mode to " +
-            "webhook when setting the Request URL");
-    }
-    const verificationToken = required(bootstrap.token ||
-        (reuseExistingApp ? opts.existing?.LARK_VERIFICATION_TOKEN?.trim() : undefined) ||
-        (io.verificationToken
-            ? await io.verificationToken(eventSecurityUrl)
-            : await io.prompt("LARK_VERIFICATION_TOKEN (Events & Callbacks → Encryption Strategy)", { hidden: true })), "LARK_VERIFICATION_TOKEN", rerun);
-    return {
-        LARK_APP_ID: appId,
-        LARK_APP_SECRET: appSecret,
-        LARK_VERIFICATION_TOKEN: verificationToken,
-    };
-}