@fastagent-sh/fastagent 0.13.0 → 0.14.0

package/dist/channels/feishu/parse.js

@@ -1,175 +1,65 @@
-/** Restore the platform's mention placeholders (`@_user_1`) in a text body to readable `@Name`. */
-function restoreMentions(text, mentions) {
-    let out = text;
-    for (const m of mentions ?? []) {
-        if (!m.key)
-            continue;
-        out = out.split(m.key).join(`@${m.name ?? "user"}`);
-    }
-    return out;
-}
+import { decodeFeishuContent } from "./normalize.js";
 /**
- * Decode a message's `content` by its `message_type` — the single decoder (module header). Unknown or
- * malformed content degrades to a visible marker (`[sticker message]`), never a throw: the payload is
- * external input, and a message the agent cannot read should still say WHAT it couldn't read.
+ * Compatibility decoder for existing helpers/tests and parent-message resolution. The canonical
+ * decoder now emits typed resources; this wrapper projects them onto the historical parallel arrays.
  */
-export function parseContent(m) {
-    let c;
-    try {
-        c = JSON.parse(m.content);
-        if (typeof c !== "object" || c === null)
-            throw new Error("not an object");
-    }
-    catch {
-        return { text: `[unreadable ${m.message_type} message]`, imageKeys: [], fileRefs: [] };
-    }
-    const imageKeys = [];
-    const fileRefs = [];
-    const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
-    switch (m.message_type) {
-        case "text":
-            return { text: restoreMentions(str(c.text) ?? "", m.mentions), imageKeys, fileRefs };
-        case "post": {
-            // A post is paragraphs of typed nodes; renders as text lines with inline markers. Mentions in a
-            // post are `at` NODES (user_name inline), not placeholders — no restore pass needed.
-            const lines = [];
-            const title = str(c.title);
-            if (title)
-                lines.push(title);
-            const paragraphs = Array.isArray(c.content) ? c.content : [];
-            for (const para of paragraphs) {
-                if (!Array.isArray(para))
-                    continue;
-                const parts = [];
-                for (const node of para) {
-                    if (typeof node !== "object" || node === null)
-                        continue;
-                    if (node.tag === "at")
-                        parts.push(`@${str(node.user_name) ?? str(node.user_id) ?? "user"}`);
-                    else if (node.tag === "a")
-                        parts.push(node.href ? `${str(node.text) ?? node.href} (${node.href})` : (str(node.text) ?? ""));
-                    else if (node.tag === "img") {
-                        if (str(node.image_key))
-                            imageKeys.push(node.image_key);
-                        parts.push("[image]");
-                    }
-                    else if (node.tag === "media") {
-                        if (str(node.file_key))
-                            fileRefs.push({ key: node.file_key, name: str(node.file_name) });
-                        parts.push("[video]");
-                    }
-                    else if (node.tag === "code_block")
-                        parts.push(`\n\`\`\`${str(node.language)?.toLowerCase() ?? ""}\n${str(node.text) ?? ""}\n\`\`\`\n`);
-                    else if (str(node.text))
-                        parts.push(node.text);
-                }
-                const line = parts.join("").trim();
-                if (line)
-                    lines.push(line);
-            }
-            return { text: lines.join("\n"), imageKeys, fileRefs };
-        }
-        case "image": {
-            if (str(c.image_key))
-                imageKeys.push(c.image_key);
-            return { text: "[image]", imageKeys, fileRefs };
-        }
-        case "file": {
-            const name = str(c.file_name);
-            if (str(c.file_key))
-                fileRefs.push({ key: c.file_key, name });
-            return { text: `[file: ${name ?? "file"}]`, imageKeys, fileRefs };
-        }
-        case "audio": {
-            if (str(c.file_key))
-                fileRefs.push({ key: c.file_key, name: "voice-message" });
-            return { text: "[voice message]", imageKeys, fileRefs };
-        }
-        case "media": {
-            const name = str(c.file_name);
-            if (str(c.file_key))
-                fileRefs.push({ key: c.file_key, name });
-            return { text: `[video: ${name ?? "video"}]`, imageKeys, fileRefs };
-        }
-        case "location": {
-            const name = str(c.name);
-            return {
-                text: `[location: ${name ? `${name} — ` : ""}${str(c.latitude) ?? "?"},${str(c.longitude) ?? "?"}]`,
-                imageKeys,
-                fileRefs,
-            };
-        }
-        default:
-            // sticker / share_chat / share_user / system / … — name the type so the agent can say what it got.
-            return { text: `[${m.message_type} message]`, imageKeys, fileRefs };
-    }
+export function parseContent(message) {
+    const decoded = decodeFeishuContent(message);
+    return {
+        text: decoded.text,
+        imageKeys: decoded.resources.filter((resource) => resource.kind === "image").map((resource) => resource.key),
+        fileRefs: decoded.resources
+            .filter((resource) => resource.kind === "file" || resource.kind === "audio" || resource.kind === "video")
+            .map((resource) => ({ key: resource.key, name: resource.name })),
+    };
 }
-/** A stable sender label for attribution. The receive event carries only ids (a display name needs a
- *  contacts-API scope), so the label is the open_id — stable across turns, which is what a shared
- *  multi-user session needs to tell participants apart. */
+/** A stable sender label for attribution. Display names require an additional contacts permission. */
 export function senderLabel(sender) {
     const id = sender?.sender_id?.open_id ?? sender?.sender_id?.user_id ?? sender?.sender_id?.union_id;
     return id ? `user ${id}` : undefined;
 }
-/** The place a message lives (chat, or chat:topic in a topic group) — the default session key. */
-export function placeKey(m) {
-    return m.thread_id ? `${m.chat_id}:${m.thread_id}` : m.chat_id;
+/** The place a message lives (chat, or chat:topic in a topic group) — the legacy default session key. */
+export function placeKey(message) {
+    return message.thread_id ? `${message.chat_id}:${message.thread_id}` : message.chat_id;
 }
-/**
- * The default base prompt: a context envelope (chat/thread/sender + a group note + a reply marker),
- * then the message's decoded body. The sender is named on every message and a group chat is flagged —
- * in a shared multi-user session that is how the model tells participants apart and knows it is not a
- * 1:1. A reply carries only `[in reply to msg …]` here: the referent's CONTENT is not in the event, so
- * the channel fetches and appends it in the IO half (invoke-turn.ts), keeping this layer pure. Exported
- * so a custom Feishu `route` can reuse it, e.g. `text: `${feishuEnvelope(event)}\n\n[extra]``. The
- * internal compatibility seam binds the same shape to `[lark: …]`; each kind's send tool reads the
- * chat id from its own branded line.
- */
+/** The canonical Feishu-branded prompt envelope. */
 export function feishuEnvelope(event) {
     return cloudEnvelope(event, "feishu");
 }
 /** Internal compatibility seam: bind the canonical envelope shape to one cloud's branded tag. */
 export function cloudEnvelope(event, tag) {
-    const m = event.message;
-    if (!m)
+    const message = event.message;
+    if (!message)
         return "";
+    const from = senderLabel(event.sender);
     const meta = [
-        `chat ${m.chat_id} (${m.chat_type})`,
-        m.thread_id ? `topic ${m.thread_id}` : undefined,
-        senderLabel(event.sender) ? `from ${senderLabel(event.sender)}` : undefined,
+        `chat ${message.chat_id} (${message.chat_type})`,
+        message.thread_id ? `topic ${message.thread_id}` : undefined,
+        from ? `from ${from}` : undefined,
     ]
         .filter(Boolean)
         .join(", ");
-    const scope = m.chat_type === "group" ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
-    const replyTo = m.parent_id ? `\n[in reply to msg ${m.parent_id}]` : "";
-    return `[${tag}: ${meta}]${scope}${replyTo}\n${parseContent(m).text}`;
+    const scope = message.chat_type === "group" ? "\n[group chat — multiple people; each message is prefixed with its sender]" : "";
+    const replyTo = message.parent_id ? `\n[in reply to msg ${message.parent_id}]` : "";
+    return `[${tag}: ${meta}]${scope}${replyTo}\n${parseContent(message).text}`;
 }
-/**
- * Whether the message @mentions the bot — read from the `mentions` array the platform already parsed
- * (never a regex over the text: a pasted `@bot` in a code block is not a mention entry), matched on the
- * bot's open_id (stable identity; names are mutable). No id → fail closed (false): answering "is this
- * mention me?" with "I don't know who I am, so yes" would mis-summon in every multi-bot group.
- */
-export function mentionsBot(m, botOpenId) {
+/** Whether the parsed mention list contains this bot's app-scoped open_id. */
+export function mentionsBot(message, botOpenId) {
     if (!botOpenId)
         return false;
-    return (m.mentions ?? []).some((x) => x.id?.open_id === botOpenId);
+    return (message.mentions ?? []).some((mention) => mention.id?.open_id === botOpenId);
 }
 /**
- * The default routing policy (used when `route` is omitted; exported so a custom route can reuse it):
- * answer humans only (a non-`user` sender is another bot/app — two bots answering each other loop
- * forever), p2p chats always, a group only on an @mention of THIS bot (matched by open_id, which
- * feishuChannel resolves via bot/v3/info). NOTE the platform side of the same coin: with the default
- * `im:message.group_at_msg` scope, un-mentioned group messages are never even delivered — receiving
- * everything needs the sensitive `im:message.group_msg` scope. Returns `{}` (act; the channel fills
- * session/target/prompt from the message) or `null` (ignore).
+ * Default EXPLICIT-summon policy: ignore non-user senders, always answer p2p, and answer groups only
+ * when THIS bot is structurally mentioned. No bot identity means group routing fails closed. The
+ * stateful channel wiring may additionally admit unmentioned continuations from its managed-root index.
  */
 export function defaultFeishuRoute(event, options) {
-    const m = event.message;
-    if (!m)
+    const message = event.message;
+    if (!message)
         return null;
     if (event.sender?.sender_type !== "user")
         return null;
-    const summoned = m.chat_type === "p2p" || mentionsBot(m, options?.botOpenId);
+    const summoned = message.chat_type === "p2p" || mentionsBot(message, options?.botOpenId);
     return summoned ? {} : null;
 }

package/dist/channels/feishu/preview.js

@@ -88,8 +88,8 @@ async function finalize(api, target, preview, text, seq) {
             // Settle failed (card expired / rejected) — fall through to delete + fresh send below.
         }
         if (settled) {
-            // Topic continuations must keep reply_in_thread; ordinary group continuations intentionally avoid
-            // repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
+            // Threaded continuations must keep reply_in_thread; continuous top-level group replies intentionally
+            // avoid repeating the quote on every chunk. sendText owns the same distinction for its own chunking.
             // A continuation failure propagates: the card is already authoritative, so deleting it and sending
             // the full answer again would deterministically duplicate every continuation that already landed.
             const continuationTarget = target.replyInThread ? target : { chatId: target.chatId };

package/dist/channels/feishu/scaffold/channel.ts

@@ -7,7 +7,9 @@ import { feishuChannel } from "@fastagent-sh/fastagent/feishu";
 //   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
-//      card scope ("Create and update card" — the live preview streams through a card)
+//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
+//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
 //   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
 //      .env; RECOMMENDED: set an Encrypt Key there and mirror it in FEISHU_ENCRYPT_KEY
 //   4. the event Request URL (https://your.host/feishu) is registered AUTOMATICALLY by
@@ -21,14 +23,19 @@ export default feishuChannel({
   appSecret: process.env.FEISHU_APP_SECRET ?? "",
   verificationToken: process.env.FEISHU_VERIFICATION_TOKEN ?? "", // authenticates inbound events
   encryptKey: process.env.FEISHU_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
+  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
+  // directMessageSession: "continuous",
+  // groupMessageSession: "continuous",
   // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
   // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
   // full details always go to the server log regardless.
   onError: (failed) => `⚠️ ${failed.details}`,
   // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
   // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultFeishuRoute:
-  // p2p chats always answer, groups only on an @mention of this bot (matched by open_id, resolved at
-  // startup). Override to customise, reusing the export:
+  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
+  // threads. Other human group/thread discussion buffers until that place's next answered turn;
+  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // Override to customise explicit routing, reusing the export:
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
   //   route: (e) => defaultFeishuRoute(e, { botOpenId: "ou_xxx" }) && { text: `${feishuEnvelope(e)}\n[extra]` },
 });

package/dist/channels/feishu/seen.js

@@ -1,14 +1,14 @@
 /**
- * Accepted-turn dedup: a bounded, persisted ring of message_ids the channel has ACCEPTED. The platform
- * redelivers events it thinks undelivered AND documents duplicate pushes in "special scenarios", keying
- * idempotency on message_id (its own guidance: dedup on message_id, not event_id). The turn-store alone
- * cannot cover the tail: once a completed turn's intent is removed, a late redelivery would re-run it —
- * this ring is what refuses that. Only ACCEPTED (routed) messages enter: ignored events are side-effect-
- * free, so recording them would just churn the ring.
+ * Bounded delivery dedup for message_ids whose webhook handling produced a durable side effect: either
+ * an accepted turn intent or a buffered group-context entry. Feishu/Lark document duplicate pushes even
+ * after a successful 200 and recommend idempotency on message_id (not event_id). The unfinished-turn
+ * store cannot cover a duplicate after completion, and a duplicated background event would otherwise be
+ * folded twice.
  *
- * Best-effort durability (post-decision insurance, not the pre-ACK intent): a failed write logs and
- * moves on — the exposure is a re-run after BOTH a completed turn and a redelivery straddle a crash,
- * the same at-least-once tail the turn-store documents.
+ * Record only AFTER the pre-ACK side effect is durable: recording first could turn a later state-write
+ * failure into silent loss when the platform redelivers. The ring write is best-effort post-persist
+ * insurance. A crash between the two writes, a ring-write failure, or an id older than the bounded cap
+ * retains L1's at-least-once tail; this is dedup, not exactly-once execution.
  */
 import { log } from "../../log.js";
 import { loadStateFile, saveStateFile } from "../state.js";
@@ -17,7 +17,7 @@ export function createSeenRing(path, label = "[feishu]", cap = 2000) {
         const raw = loadStateFile(path);
         if (raw === undefined)
             return [];
-        if (Array.isArray(raw) && raw.every((x) => typeof x === "string"))
+        if (Array.isArray(raw) && raw.every((id) => typeof id === "string"))
             return raw.slice(-cap);
         log.warn(`${label} unexpected shape in ${path} — starting with no seen ids`);
         return [];
@@ -39,8 +39,8 @@ export function createSeenRing(path, label = "[feishu]", cap = 2000) {
             try {
                 saveStateFile(path, order);
             }
-            catch (e) {
-                log.warn(`${label} seen-ring write failed (dedup degrades to the turn-store window): ${String(e)}`);
+            catch (error) {
+                log.warn(`${label} seen-ring write failed (delivery dedup is in-memory until restart): ${String(error)}`);
             }
         },
     };

package/dist/channels/lark/scaffold/channel.ts

@@ -7,7 +7,9 @@ import { larkChannel } from "@fastagent-sh/fastagent/lark";
 //   1. create a custom app → enable the BOT capability → copy App ID / App Secret into .env
 //   2. Permissions: add `im:message.p2p_msg:readonly` (direct messages), `im:message.group_at_msg:readonly`
 //      (group @mentions), `im:message:send_as_bot` (reply), `im:resource` (attachments), and the
-//      card scope ("Create and update card" — the live preview streams through a card)
+//      card scope ("Create and update card" — the live preview streams through a card). To answer bare
+//      messages in Agent-managed threads and buffer other unsummoned group/thread context, also add the
+//      sensitive `im:message.group_msg` scope (tenant-admin approval) and publish a new version.
 //   3. Events & Callbacks → subscribe to `im.message.receive_v1`; copy the Verification Token into
 //      .env; RECOMMENDED: set an Encrypt Key there and mirror it in LARK_ENCRYPT_KEY
 //   4. run `fastagent dev --tunnel`: it attempts to switch Subscription mode to webhook + register
@@ -19,14 +21,19 @@ export default larkChannel({
   appSecret: process.env.LARK_APP_SECRET ?? "",
   verificationToken: process.env.LARK_VERIFICATION_TOKEN ?? "", // authenticates inbound events
   encryptKey: process.env.LARK_ENCRYPT_KEY || undefined, // optional; when set, plaintext events are refused
+  // Direct and group chats default to one Agent session/thread per top-level ask. Opt out independently:
+  // directMessageSession: "continuous",
+  // groupMessageSession: "continuous",
   // Dev/personal bot: surface raw errors to the chat so you (and your AI agent) can act on them. The
   // chat is customer-facing by default — for a public bot, drop this or return a neutral string;
   // full details always go to the server log regardless.
   onError: (failed) => `⚠️ ${failed.details}`,
   // The channel owns transport + format (markdown card) + attachments (image→vision, file→disk) +
   // the live streaming preview. `route` (POLICY) is OPTIONAL — omitted, it uses defaultLarkRoute:
-  // p2p chats always answer, groups only on an @mention of this bot (matched by open_id, resolved at
-  // startup). Override to customise, reusing the export:
+  // p2p chats always answer; groups answer on @this-bot, plus bare continuations in Agent-managed
+  // threads. Other human group/thread discussion buffers until that place's next answered turn;
+  // @other-only messages in managed threads buffer rather than triggering the Agent.
+  // Override to customise explicit routing, reusing the export:
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { session: `user:${e.sender?.sender_id?.open_id}` },
   //   route: (e) => defaultLarkRoute(e, { botOpenId: "ou_xxx" }) && { text: `${larkEnvelope(e)}\n[extra]` },
 });

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

@@ -0,0 +1,9 @@
+import { type ChannelKind } from "../../scaffold/add-channel.ts";
+/** `fastagent add <kind> [dir]`: scaffold `channels/<kind>.ts` — the adapter import plus a starter `on()`. */
+export declare function runAddChannel(channelKind: ChannelKind, dirArg: string, opts: {
+    createApp?: boolean;
+}): Promise<void>;
+/** `fastagent add skill <source> [dir]`: vendor an Agent Skills skill into <dir>/skills/<name>/. */
+export declare function runAddSkill(source: string | undefined, dirArg: string, opts: {
+    update?: boolean;
+}): Promise<void>;

package/dist/cli/commands/add.js

@@ -0,0 +1,142 @@
+/**
+ * `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).
+ */
+import { randomBytes } from "node:crypto";
+import { join, relative, resolve } from "node:path";
+import { onboardFeishuCloudApp } from "../../cli-add-feishu.js";
+import { loadConfig, resolveAgentDir } from "../../engines/pi/config.js";
+import { detectRuntime, readPackageJson } from "../../runtime.js";
+import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.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);
+    // 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) {
+        if (channelKind === "feishu") {
+            console.error(`[fastagent] note: --create-app is retired — \`add feishu\` creates the app by default`);
+        }
+        else if (channelKind === "lark") {
+            failStartup(new Error("--create-app is retired — `add lark` now opens the developer console and guides credential setup by default"));
+        }
+        else {
+            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:
+    // 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") {
+            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);
+        console.error(`[fastagent] created ${relative(target, file)}`);
+    }
+    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`);
+    }
+    // `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.
+    let created;
+    if (channelKind === "feishu" || channelKind === "lark") {
+        created = await onboardFeishuCloudApp(target, channelKind, envIgnored).catch(failStartup);
+    }
+    const { env, steps } = channelSetup(channelKind);
+    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})`;
+    console.error(`  next steps:`);
+    console.error(`    ${installCmd}                      # if @fastagent-sh/fastagent is not installed yet`);
+    for (const e of env) {
+        if (dotEnv?.alreadySet.includes(e.name))
+            continue; // the user already has it — nothing to do
+        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}`);
+            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}`);
+    }
+    // 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)}/`;
+    for (const s of steps) {
+        console.error(`    ${s.replace("{channel}", relative(target, file)).replace("{tools}", `${kitPrefix}tools`)}`);
+    }
+    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.
+    process.exit(0);
+}
+/** `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);
+    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.
+        failUsage(`add a skill — two ways:\n` +
+            `  1. write your own (vibe): create skills/<name>/SKILL.md with name + description\n` +
+            `     frontmatter; it's auto-discovered. No command needed — this is the common path.\n` +
+            `  2. vendor an existing Agent Skills skill (copied in, git-tracked):\n` +
+            `       fastagent add skill <source> [dir]\n` +
+            `     source: a git ref (owner/repo/path, github default), a local path (./x, /abs), or a\n` +
+            `             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, {
+        update: opts.update ?? false,
+    }).catch(failStartup);
+    console.error(`[fastagent] ${overwritten ? "updated" : "vendored"} skill "${name}" → ${dest}/`);
+    if (overwritten)
+        console.error(`  overwrote it — \`git diff ${dest}\` to review, \`git checkout ${dest}\` to revert`);
+    if (description)
+        console.error(`  ${description.length > 100 ? `${description.slice(0, 100)}…` : description}`);
+    for (const d of diagnostics)
+        console.error(`  warn: ${d.message}`);
+    if (hasScripts) {
+        console.error(`  warn: this skill ships scripts/ (executable code that runs in your agent) — review it before deploying`);
+    }
+    console.error(`  next: mention "${name}" in persona.md so the model knows when to use it; then \`fastagent dev\``);
+}

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

@@ -0,0 +1,3 @@
+export declare function runChat(dirArg: string, opts: {
+    model?: string;
+}): Promise<void>;

package/dist/cli/commands/chat.js

@@ -0,0 +1,16 @@
+/** `fastagent chat [dir]`: open the SAME assembled agent in pi's interactive TUI. */
+import { resolve } from "node:path";
+import { loadDotEnv } from "../../env.js";
+import { installProxyFetch } from "../../proxy.js";
+import { failStartup } from "../fail.js";
+export async function runChat(dirArg, opts) {
+    const dir = resolve(dirArg);
+    loadDotEnv(dir);
+    installProxyFetch(); // model calls (and the login dialog) must go through the proxy too
+    // Run the chat process IN the workspace: pi resolves a session's cwd as `header.cwd ?? process.cwd()`,
+    // so aligning process.cwd() with the workspace keeps a cwd-less session on the workspace. `dir` is absolute.
+    process.chdir(dir);
+    // Lazy-import: chat pulls pi's interactive TUI module graph; headless start/dev never need it.
+    const { runPiChat } = await import("../../engines/pi/chat.js");
+    await runPiChat(dir, { model: opts.model }).catch(failStartup);
+}

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

@@ -0,0 +1,13 @@
+export type DeployHost = "docker" | "fly" | "railway";
+export interface DeployOptions {
+    run?: boolean;
+    tunnel?: boolean;
+    force?: boolean;
+    stop?: boolean;
+    /** false ⇔ `--no-scale-to-zero`. */
+    scaleToZero?: boolean;
+    intoLinked?: boolean;
+    model?: string;
+    authPath?: string;
+}
+export declare function runDeploy(host: DeployHost, dirArg: string, opts: DeployOptions): Promise<void>;