@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/cli/commands/add.js

@@ -1,19 +1,27 @@
 /**
  * `fastagent add <channel>|skill` — scaffold channel glue (`channels/<kind>.ts`) or vendor an Agent
- * Skills skill. feishu/lark additionally CREATE OR RESUME the platform app (cli-add-feishu.ts).
+ * Skills skill. slack/feishu/lark additionally CREATE OR RESUME the platform app.
  */
 import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
-import { onboardFeishuCloudApp } from "../../cli-add-feishu.js";
-import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
+import { isCancel, select } from "@clack/prompts";
+import { onboardFeishuCloudApp } from "../add-feishu.js";
+import { loadDotEnv } from "../../env.js";
+import { loadConfig, resolveAgentDir, resolveStateRoot } from "../../engines/pi/config.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
+import { exists } from "../../scaffold/init.js";
 import { vendorSkill } from "../../scaffold/vendor-skill.js";
 import { loadRootIgnore } from "../../workspace.js";
 import { failStartup, failUsage } from "../fail.js";
 /** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
 export async function runAddChannel(channelKind, dirArg, opts) {
     const target = resolve(dirArg);
+    if (opts.replaceConfig && opts.onboard === false) {
+        failUsage("--replace-config replaces onboarding credentials; it cannot be combined with --no-onboard");
+    }
+    loadDotEnv(target); // onboarding state follows the same FASTAGENT_STATE_DIR as serving/deploy
     // App creation is not a flag — it is what `add feishu` IS (the scan-to-create flow is the default
     // and only path there). The retired --create-app spelling gets a pointer, not silence.
     if (opts.createApp) {
@@ -32,22 +40,30 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     // hygiene stay at the run root, where .env is actually read.
     const { config: addConfig } = await loadConfig(target).catch(failStartup);
     const channelHome = resolveAgentDir(target, addConfig);
-    // Preconditions before the write, so a refusal is side-effect-free. feishu/lark are exceptions:
+    // Preconditions before the write, so a refusal is side-effect-free. slack/feishu/lark are exceptions:
     // their add is scaffold + ONBOARD THE APP, so an existing scaffold skips the write and continues (a
-    // failed or cancelled scan/paste flow must be re-runnable without hand-deleting glue); never touch it.
+    // failed/cancelled app or OAuth flow must be re-runnable without hand-deleting authored glue).
     const file = join(channelHome, "channels", `${channelKind}.ts`);
-    if (await channelExists(channelHome, channelKind).catch(failStartup)) {
-        if (channelKind !== "feishu" && channelKind !== "lark") {
+    const slackToolFile = join(channelHome, "tools", "slack-send.ts");
+    const slackToolExisted = channelKind === "slack" ? await exists(slackToolFile) : false;
+    const existsAlready = await channelExists(channelHome, channelKind).catch(failStartup);
+    const ingress = await resolveIngress(channelKind, file, existsAlready, opts.ingress);
+    const groupBehavior = await resolveGroupBehavior(channelKind, opts.groupBehavior);
+    if (existsAlready) {
+        if (channelKind !== "slack" && channelKind !== "feishu" && channelKind !== "lark") {
             failStartup(new Error(`${relative(target, file)} already exists — edit it, or remove it to re-scaffold`));
         }
         console.error(`[fastagent] ${relative(target, file)} already exists — keeping it`);
     }
     else {
         await assertChannelReady(channelHome).catch(failStartup);
-        await scaffoldChannel(channelHome, channelKind).catch(failStartup);
+        await scaffoldChannel(channelHome, channelKind, { ingress, groupBehavior: groupBehavior.behavior }).catch(failStartup);
         console.error(`[fastagent] created ${relative(target, file)}`);
+        if (channelKind === "slack") {
+            console.error(`[fastagent] ${slackToolExisted ? "kept existing" : "created"} ${relative(target, slackToolFile)}`);
+        }
     }
-    if (await appendChannelEnv(target, channelKind).catch(failStartup)) {
+    if (await appendChannelEnv(target, channelKind, ingress).catch(failStartup)) {
         console.error(`[fastagent] added ${channelKind} env vars to .env.example`);
     }
     // Secret hygiene: a channel's GENERATED secret (a random string the user contributes nothing to) is
@@ -58,20 +74,40 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     if (!envIgnored) {
         console.error(`[fastagent] warn: .env is not gitignored — a deploy that copies the directory would ship a secret placed there; add .env to .gitignore/.fastagentignore, or use a real env var`);
     }
-    // `add feishu`/`add lark` = scaffold + CREATE OR RESUME the app (cli-add-feishu.ts): feishu persists
-    // its irreversible App ID/Secret boundary internally; lark returns guided credentials for the
-    // generic .env write below.
+    // Stateful app onboarding is re-runnable after the scaffold boundary. Slack's internal-app path
+    // persists its manifest/OAuth recovery state separately and writes runtime secrets directly.
     let created;
-    if (channelKind === "feishu" || channelKind === "lark") {
-        created = await onboardFeishuCloudApp(target, channelKind, envIgnored).catch(failStartup);
+    if (channelKind === "slack" && opts.onboard !== false) {
+        const { onboardSlackInternalApp } = await import("../add-slack.js");
+        created = await onboardSlackInternalApp({
+            target,
+            stateRoot: resolveStateRoot(target),
+            envIgnored,
+            groupBehavior,
+            replaceConfig: opts.replaceConfig,
+        })
+            .then(() => undefined)
+            .catch(failStartup);
     }
-    const { env, steps } = channelSetup(channelKind);
+    else if (channelKind === "feishu" || channelKind === "lark") {
+        created = await onboardFeishuCloudApp(target, channelKind, envIgnored, ingress, groupBehavior).catch(failStartup);
+    }
+    const setup = channelSetup(channelKind, ingress, groupBehavior.behavior);
+    const env = setup.env;
+    const steps = channelKind === "slack" && opts.onboard !== false
+        ? [
+            "Slack internal app created/configured/installed through OAuth; runtime credentials are in .env",
+            "run fastagent dev --tunnel to replace the temporary Events API URL automatically",
+            "invite the app to every channel it should read",
+            "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
+        ]
+        : setup.steps;
     const generated = Object.fromEntries(env.filter((e) => e.generate).map((e) => [e.name, randomBytes(24).toString("hex")]));
     // Kind-neutral: every channel's generated secrets get the same treatment (github's webhook secret is
     // the same class of value as telegram's); guided Lark credentials ride the same write as overwrites.
-    // Feishu's irreversible credentials were already staged inside cli-add-feishu.ts before bootstrap.
+    // Feishu's irreversible credentials were already staged inside add-feishu.ts before bootstrap.
     const dotEnv = envIgnored
-        ? await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {})).catch(failStartup)
+        ? await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {}), ingress).catch(failStartup)
         : undefined;
     if (dotEnv && dotEnv.written.length > 0) {
         console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to .env`);
@@ -100,13 +136,109 @@ export async function runAddChannel(channelKind, dirArg, opts) {
     for (const s of steps) {
         console.error(`    ${s.replace("{channel}", relative(target, file)).replace("{tools}", `${kitPrefix}tools`)}`);
     }
-    if (channelKind !== "lark") {
+    if (ingress === "websocket") {
+        console.error(`    fastagent dev            # no public URL or tunnel required`);
+    }
+    else if (channelKind === "slack") {
+        console.error(`    fastagent dev --tunnel   # serve locally; ${opts.onboard === false ? "print the Request URL for manual Slack setup" : "auto-update the onboarded Slack Request URL"}`);
+    }
+    else if (channelKind === "github") {
+        console.error(`    fastagent dev --tunnel   # serve locally + print the URL for manual GitHub webhook setup`);
+    }
+    else if (channelKind !== "lark") {
         console.error(`    fastagent dev --tunnel   # serve locally + a public URL, auto-registering the webhook`);
     }
-    // The app-creation flow leaves keep-alive sockets behind (platform API fetches, the throwaway tunnel's
-    // health probes) that would hold the event loop open for a while — the work is done, exit crisply.
+    // App-creation flows leave platform/tunnel sockets behind that would otherwise hold the one-shot
+    // scaffold command open after all durable boundaries have completed — exit crisply.
     process.exit(0);
 }
+async function resolveIngress(kind, file, existsAlready, raw) {
+    if (raw !== undefined && raw !== "webhook" && raw !== "websocket") {
+        failUsage(`--ingress must be "webhook" or "websocket", got "${raw}"`);
+    }
+    const requested = raw;
+    if (kind !== "feishu" && kind !== "lark")
+        return "webhook";
+    if (existsAlready) {
+        const source = await readFile(file, "utf8").catch(failStartup);
+        const factory = source.match(/\b(?:feishu|lark)(WebSocket)?Channel\s*\(/);
+        const existing = factory
+            ? factory[1] === "WebSocket"
+                ? "websocket"
+                : "webhook"
+            : undefined;
+        if (!existing) {
+            if (!requested) {
+                failUsage(`${file} uses an unrecognized channel factory — re-run with --ingress webhook|websocket to confirm its mode`);
+            }
+            return requested;
+        }
+        if (requested && requested !== existing) {
+            failStartup(new Error(`${file} already selects ${existing} delivery — changing mode is a migration; edit the factory and platform subscription together`));
+        }
+        return existing;
+    }
+    if (requested)
+        return requested;
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        console.error(`[fastagent] no interactive terminal — defaulting ${kind} ingress to webhook (use --ingress websocket)`);
+        return "webhook";
+    }
+    const answer = await select({
+        message: `How should ${kind === "feishu" ? "Feishu" : "Lark"} deliver events?`,
+        options: [
+            {
+                value: "websocket",
+                label: "WebSocket long connection",
+                hint: "no public URL; requires an always-on process",
+            },
+            {
+                value: "webhook",
+                label: "Webhook endpoint",
+                hint: "supports scale-to-zero; requires a public HTTPS URL",
+            },
+        ],
+    });
+    if (isCancel(answer))
+        failStartup(new Error(`${kind} onboarding cancelled`));
+    return answer;
+}
+async function resolveGroupBehavior(kind, raw) {
+    if (raw !== undefined && raw !== "context" && raw !== "mentions") {
+        failUsage(`--group-behavior must be "context" or "mentions", got "${raw}"`);
+    }
+    if (kind !== "feishu" && kind !== "lark" && kind !== "slack")
+        return { behavior: "context", explicit: false };
+    if (raw !== undefined)
+        return { behavior: raw, explicit: true };
+    const defaultBehavior = "context";
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        console.error(`[fastagent] no interactive terminal — assuming ${kind} group behavior ${defaultBehavior}; pass --group-behavior explicitly to override`);
+        return { behavior: defaultBehavior, explicit: false };
+    }
+    const choices = [
+        {
+            value: "context",
+            label: "Context-aware groups (recommended)",
+            hint: kind === "slack"
+                ? "bare managed-thread replies + buffer; requires channel/group/mpim history scopes"
+                : "bare managed-thread replies + buffer; im:message.group_msg delivers all group messages",
+        },
+        {
+            value: "mentions",
+            label: "Mention-only (least privilege)",
+            hint: "only explicit @Agent messages; no group-wide message permission",
+        },
+    ];
+    const answer = await select({
+        message: "Choose group-chat behavior",
+        initialValue: defaultBehavior,
+        options: choices,
+    });
+    if (isCancel(answer))
+        failStartup(new Error(`${kind} onboarding cancelled`));
+    return { behavior: answer, explicit: true };
+}
 /** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
 export async function runAddSkill(source, dirArg, opts) {
     const target = resolve(dirArg);

package/dist/cli/commands/attach.d.ts

@@ -0,0 +1,82 @@
+import type { SessionControl } from "../../session.ts";
+export interface AttachOptions {
+    /** Override the control endpoint (skip control.json discovery) — for a remote serve. */
+    url?: string;
+    token?: string;
+}
+export declare function runAttach(sessionArg: string, dirArg: string | undefined, opts: AttachOptions): Promise<void>;
+/** One round's observed facts, gathered by the loop (IO) and judged by {@link decideRound} (pure). */
+export type RoundOutcome = {
+    type: "progress";
+}
+/** Clean end that delivered nothing — indistinguishable from a half-dead proxy closing every stream. */
+ | {
+    type: "empty";
+} | {
+    type: "error";
+    error: unknown;
+    isAuth: boolean;
+    /** discover(dir) compared against the current endpoint; remote endpoints report "unavailable". */
+    discovery: "unchanged" | "changed" | "unavailable";
+    /** The freshly discovered credentials when {@link discovery} is "changed". */
+    fresh?: {
+        url: string;
+        token: string;
+    };
+};
+export type RoundDecision = {
+    kind: "reset";
+} | {
+    kind: "exit";
+    message: string;
+} | {
+    kind: "try-reattach";
+    fresh: {
+        url: string;
+        token: string;
+    };
+} | {
+    kind: "retry";
+    warn: string;
+};
+/**
+ * The reconnect policy for BOTH phases (`startup` = connectWithGrace, `steady` = the round loop),
+ * pure and testable: every exit diagnosis and budget claim lives here. `downMs` is wall-clock time
+ * since the phase's anchor (first connect attempt / first non-progress round). The phases differ
+ * on priors, not principle: startup has never succeeded (short budget; a remote non-auth error
+ * exits at once), steady-state had a working attach (longer budgets); the local-401-unchanged
+ * diagnosis and reattach-on-changed-credentials apply identically to both.
+ */
+export declare function decideRound(outcome: RoundOutcome, ctx: {
+    discovered: boolean;
+    downMs: number;
+    phase?: "startup" | "steady";
+}): RoundDecision;
+/** What one ROUND prints through (streamed deltas included), so tests can observe every path a
+ *  round writes. Round output only: stdin-side acceptance/rejection lines print directly — they
+ *  are immediate feedback to a user action and may interleave with a replay block. Timing knobs
+ *  travel as their own parameter. */
+export interface AttachIo {
+    println: (line: string) => void;
+    /** Raw chunk, no newline — the streamed message_delta path. */
+    write: (chunk: string) => void;
+    warn: (line: string) => void;
+}
+/**
+ * ONE attach round: subscribe → backfill (render the durable record since `cursor`) → drain live
+ * until the stream drops. Returns the advanced cursor. Subscribing first + the server's eager
+ * registration (subscribed before response headers) covers the cursor→subscription window in the
+ * normal case; `settleMs` is a HEURISTIC — on a very slow link an event can still land between the
+ * backfill and the subscription taking effect, surfacing only at the next round's replay. Live
+ * events carry no entry ids, so the cursor advances only on backfill; a replay may overlap what
+ * was already seen live — labeled, not silently dropped. A 401 (stale token after a serve restart)
+ * is thrown to the caller: unrecoverable here, never retried silently.
+ */
+export declare function attachRound(control: SessionControl, session: string, cursor: string | undefined, io: AttachIo, 
+/** The subscribe→sync settle heuristic (see the round comment). Tests shrink it. */
+settleMs?: number): Promise<{
+    cursor: string | undefined;
+    sawProgress: boolean;
+}>;
+/** The cursor a failed round reached, if it recorded one. */
+export declare function roundCursor(error: unknown): string | undefined;