@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/cli/commands/add.js

@@ -1,19 +1,42 @@
 /**
  * `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 { dotEnvPath, loadDotEnv } from "../../env.js";
+import { resolveStateRoot } from "../../paths.js";
+import { SECRETS_DIRNAME } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
+import { isUnderDir } from "../../engines/pi/definition.js";
+import { displayPath } from "../../paths.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
+import { exists } from "../../paths.js";
 import { vendorSkill } from "../../scaffold/vendor-skill.js";
-import { loadRootIgnore } from "../../workspace.js";
-import { failStartup, failUsage } from "../fail.js";
+import { failStartup, failUsage, placementOrExit } 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);
+    // The channel (glue + companion tool + secrets) is agent surface — everything lands in the
+    // AGENT DIR (`fastagent/`), the same place dev/start discover channels/.
+    // Flag conflicts first: a bad combination is a USAGE error (exit 2), and reporting it must not depend
+    // on the directory being an agent (a runtime/environment failure, exit 1) — the same order start/tool
+    // follow.
+    if (opts.replaceConfig && opts.onboard === false) {
+        failUsage("--replace-config replaces onboarding credentials; it cannot be combined with --no-onboard");
+    }
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
+    loadDotEnv(target); // onboarding state follows the same FASTAGENT_STATE_DIR as serving/deploy
+    // Paths are printed to someone standing in their CWD, usually the workspace, while every file
+    // belongs to the AGENT dir — prefix them, or they point at nothing. `displayPath` owns the
+    // relative-vs-absolute policy (shared with `init`). The `.env` label names the file actually
+    // WRITTEN (FASTAGENT_SECRETS_DIR relocates it, possibly out of the agent), never the default spelling.
+    const agentFromCwd = displayPath(process.cwd(), target);
+    const inAgent = (p) => (agentFromCwd === undefined ? p : join(agentFromCwd, p));
+    const envPath = dotEnvPath(target);
+    const envLabel = isUnderDir(envPath, target) ? inAgent(relative(target, envPath)) : envPath;
     // 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) {
@@ -27,89 +50,199 @@ export async function runAddChannel(channelKind, dirArg, opts) {
             failStartup(new Error("--create-app is retired — app creation is the default behavior of `add feishu`"));
         }
     }
-    // The channel (glue + companion tool) is agent surface — it lands in agentDir (config.agentDir, or
-    // target when flat), the same place dev/start discover channels/. .env(.example) and the secret
-    // 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.
-    const file = join(channelHome, "channels", `${channelKind}.ts`);
-    if (await channelExists(channelHome, channelKind).catch(failStartup)) {
-        if (channelKind !== "feishu" && channelKind !== "lark") {
+    // failed/cancelled app or OAuth flow must be re-runnable without hand-deleting authored glue).
+    const file = join(target, "channels", `${channelKind}.ts`);
+    const slackToolFile = join(target, "tools", "slack-send.ts");
+    const slackToolExisted = channelKind === "slack" ? await exists(slackToolFile) : false;
+    const existsAlready = await channelExists(target, 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 assertChannelReady(target).catch(failStartup);
+        await scaffoldChannel(target, 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)) {
-        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
-    // written into `.env` — but only when `.env` is already gitignored: the CLI must never materialize a
-    // secret into a committable file. Warn, not refuse, when it is exposed — channel glue may read a real
-    // env var instead.
-    const envIgnored = (await loadRootIgnore(target).catch(failStartup))?.ignores(".env") ?? false;
-    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`);
+    if (await appendChannelEnv(target, channelKind, ingress).catch(failStartup)) {
+        console.error(`[fastagent] added ${channelKind} env vars to ${inAgent(join(SECRETS_DIRNAME, ".env.example"))}`);
     }
-    // `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),
+            groupBehavior,
+            replaceConfig: opts.replaceConfig,
+        })
+            .then(() => undefined)
+            .catch(failStartup);
     }
-    const { env, steps } = channelSetup(channelKind);
+    else if (channelKind === "feishu" || channelKind === "lark") {
+        created = await onboardFeishuCloudApp(target, channelKind, 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 ${envLabel}`,
+            "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.
-    const dotEnv = envIgnored
-        ? await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {})).catch(failStartup)
-        : undefined;
-    if (dotEnv && dotEnv.written.length > 0) {
-        console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to .env`);
-    }
-    const install = detectRuntime(channelHome, await readPackageJson(channelHome)).runtime === "bun" ? "bun install" : "npm install";
-    // The kit's manifest lives in channelHome (agentDir when set) — point the install there, not the run root.
-    const installCmd = channelHome === target ? install : `(cd ${relative(target, channelHome)} && ${install})`;
+    // Feishu's irreversible credentials were already staged inside add-feishu.ts before bootstrap.
+    const dotEnv = await appendChannelDotEnv(target, channelKind, { ...generated, ...created }, Object.keys(created ?? {}), ingress).catch(failStartup);
+    if (dotEnv.unprotectedSecretsDir) {
+        console.error(`[fastagent] note: ${dotEnv.unprotectedSecretsDir} (FASTAGENT_SECRETS_DIR) 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.`);
+    }
+    if (dotEnv.written.length > 0) {
+        console.error(`[fastagent] wrote ${dotEnv.written.join(", ")} to ${envLabel}`);
+    }
+    const install = detectRuntime(target, await readPackageJson(target)).runtime === "bun" ? "bun install" : "npm install";
     console.error(`  next steps:`);
-    console.error(`    ${installCmd}                      # if @fastagent-sh/fastagent is not installed yet`);
+    console.error(`    ${agentFromCwd === undefined ? install : `(cd ${agentFromCwd} && ${install})`}                      # if @fastagent-sh/fastagent is not installed yet`);
     for (const e of env) {
-        if (dotEnv?.alreadySet.includes(e.name))
+        if (dotEnv.alreadySet.includes(e.name))
             continue; // the user already has it — nothing to do
-        if (dotEnv?.written.includes(e.name)) {
+        if (dotEnv.written.includes(e.name)) {
             // Written, but its hint may still carry an action (github: paste the same value into the webhook
             // UI) — keep the variable visible instead of silently absorbing it.
-            console.error(`    ${e.name} — ${e.generate ? "generated and " : ""}written to .env   # ${e.hint}`);
+            console.error(`    ${e.name} — ${e.generate ? "generated and " : ""}written to ${envLabel}   # ${e.hint}`);
             continue;
         }
         const value = e.generate ? `=${generated[e.name]}` : "";
         const action = e.required ? "set" : "optionally set";
-        console.error(`    ${action} ${e.name}${value} in .env${envIgnored ? " (gitignored)" : ""}   # ${e.hint}`);
+        console.error(`    ${action} ${e.name}${value} in ${envLabel}   # ${e.hint}`);
     }
     // Steps carry `{channel}`/`{tools}` path placeholders (their filenames are the scaffold's private
-    // knowledge) — resolve them to the real workspace-relative locations (agentDir-aware) here.
-    const kitPrefix = channelHome === target ? "" : `${relative(target, channelHome)}/`;
+    // knowledge) — resolve them to the real agent-dir-relative locations here.
     for (const s of steps) {
-        console.error(`    ${s.replace("{channel}", relative(target, file)).replace("{tools}", `${kitPrefix}tools`)}`);
+        console.error(`    ${s.replace("{channel}", inAgent(relative(target, file))).replace("{tools}", inAgent("tools"))}`);
+    }
+    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`);
     }
-    if (channelKind !== "lark") {
+    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 replies in the Agent's threads + buffer; requires channel/group/mpim history scopes"
+                : "bare replies in the Agent's threads + 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);
+    const { agentDir: target } = placementOrExit(resolve(dirArg));
     if (!source) {
         // A missing source is a usage error (exit 2), but the guide is worth more than a bare
         // missing-argument line — the common path (writing your own skill) needs no command at all.
@@ -122,10 +255,8 @@ export async function runAddSkill(source, dirArg, opts) {
             `             bare name found in your global skill dirs (~/.agents/skills, ~/.pi/agent/skills)\n` +
             `     --update overwrites an existing skill (re-fetch from source); review with git diff`);
     }
-    // Skills are agent surface — vendored into agentDir/skills (config.agentDir, or target when flat).
-    const { config: skillConfig } = await loadConfig(target).catch(failStartup);
-    const skillHome = resolveAgentDir(target, skillConfig);
-    const { name, description, dest, hasScripts, diagnostics, overwritten } = await vendorSkill(skillHome, source, {
+    // Skills are agent surface — vendored into the agent dir's `skills/`.
+    const { name, description, dest, hasScripts, diagnostics, overwritten } = await vendorSkill(target, source, {
         update: opts.update ?? false,
     }).catch(failStartup);
     console.error(`[fastagent] ${overwritten ? "updated" : "vendored"} skill "${name}" → ${dest}/`);

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;