@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/engines/pi/search-tools.js

@@ -0,0 +1,138 @@
+/**
+ * The built-in `search_tools` loader — the discovery surface for deferred tools (defineTool
+ * `deferred: true`). A deferred tool's schema is not in the request and the model cannot see it; this
+ * loader is how it finds and activates one. Mounted automatically (withSearchTool) only when a
+ * deferred tool exists; a workspace tool named `search_tools` wins — the author owns the concept then
+ * (same rule as the wake pair).
+ */
+import { z } from "zod";
+import { log } from "../../log.js";
+import { defineTool, isDeferredTool, stripDeferredMarker } from "./tool.js";
+/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
+export function withSearchTool(tools) {
+    if (!tools.some(isDeferredTool))
+        return tools;
+    const authored = tools.find((t) => t.name === "search_tools");
+    if (!authored)
+        return [...tools, makeSearchToolsTool()];
+    let fixed = authored;
+    if (isDeferredTool(fixed)) {
+        // A deferred LOADER is a contradiction — it is the only entry point to the deferred tools, so
+        // nothing could ever activate it (or, through it, them): every deferred tool would be silently
+        // unreachable. Ignore the marker and keep the loader active (fail visibly, keep the capability).
+        log.warn("[fastagent] search_tools is marked deferred — ignoring the marker: the loader must stay active, or no deferred tool could ever be activated");
+        fixed = stripDeferredMarker(fixed);
+    }
+    if (fixed.executionMode !== "sequential") {
+        // A non-sequential loader silently revives the parallel double-attribution (pi's diff around SDK
+        // tools in chat) — enforce the mode rather than hope the author read the docs; warn so they know.
+        log.warn('[fastagent] search_tools lacks executionMode: "sequential" — forcing it: parallel loader calls would misattribute activations');
+        fixed = { ...fixed, executionMode: "sequential" };
+    }
+    return fixed === authored ? tools : tools.map((t) => (t === authored ? fixed : t));
+}
+/** Activation cap per search: activation is additive, session-persisted, and has NO deactivate path —
+ *  without a cap, one broad token ("get", "file") would permanently activate half the catalog and
+ *  silently spend the entire deferral benefit for the rest of the conversation. Over the cap nothing
+ *  activates; the model gets the candidates and narrows the query. */
+const MAX_ACTIVATIONS_PER_SEARCH = 5;
+/** Miss-path listing cap — same rationale as the activation cap: a typo query must not pour the whole
+ *  catalog (the thing deferral keeps OUT of the context) back in as a tool result. */
+const MAX_MISS_LISTING = 10;
+/** Build the `search_tools` loader. Keyword search over the inactive tools' name+description.
+ *
+ * `executionMode: "sequential"` — pi turns any batch containing a sequential tool serial. Required for
+ * correct load-point attribution everywhere an OUTER active-set diff exists: pi wraps SDK customTools
+ * (the chat path) in a before/after diff, and two parallel loader calls would both snapshot the
+ * pre-activation set and get stamped with the same activation. Custom loader authors must set it too. */
+export function makeSearchToolsTool() {
+    return defineTool({
+        name: "search_tools",
+        executionMode: "sequential",
+        description: 
+        // First line short on purpose: the base prompt's tools list truncates at the first newline, and
+        // the discovery guidance below would otherwise flood it (and duplicate its deferred note).
+        "Discover and activate additional tools.\n" +
+            "Part of this agent's toolset is inactive until needed: search by keywords (e.g. what you are " +
+            "trying to do), and matching inactive tools are activated and become callable from that point on " +
+            "(if too many match, you get the candidates back — narrow the query, or query an exact tool " +
+            "name). ALWAYS search here before concluding a capability is missing.",
+        input: z.object({
+            query: z.string().min(1).describe("keywords describing the capability you need (e.g. 'weather forecast')"),
+        }),
+        async execute(input, ctx) {
+            if (!ctx.tools)
+                return "tool activation is unavailable outside a conversation turn.";
+            // Search the WHOLE registered catalog: the loader is the only discovery surface, and in a long
+            // conversation the model does not remember what it activated — a "No tools matched" answer for
+            // an ALREADY-ACTIVE tool would push it toward the exact wrong conclusion (capability missing).
+            // ponytail: naive keyword match (any query token as a case-insensitive substring of
+            // name+description) with a hard per-search activation cap above — the two named ceilings are
+            // relevance and irreversibility; swap in scoring/embeddings if catalogs outgrow this.
+            const tokens = input.query
+                .toLowerCase()
+                .split(/[^a-z0-9]+/)
+                .filter(Boolean);
+            // AND semantics: EVERY token must hit — "adding a word narrows" must actually hold, or the
+            // over-cap "narrow the query" instruction sends the model in circles (OR would widen with each
+            // word, and a shared prefix like "fetch" could make a whole tool family permanently over-cap).
+            const matchesQuery = (t) => {
+                const haystack = `${t.name} ${t.description}`.toLowerCase();
+                return tokens.every((token) => haystack.includes(token));
+            };
+            const describe = (t) => `${t.name} — ${t.description.split("\n")[0]}`;
+            const active = new Set(ctx.tools.active());
+            const registered = ctx.tools.registered();
+            // A query with no searchable tokens (all punctuation/symbols) must not match: `every` over an
+            // empty token list is vacuously true, and a noise query would otherwise activate the catalog.
+            if (tokens.length === 0)
+                return `"${input.query}" contains no searchable keywords — describe the capability you need.`;
+            // Exact-name shortcut: the guaranteed escape hatch from the cap — a query that IS an INACTIVE
+            // registered tool's name addresses that one tool, no keyword scoring in the way. An exact match
+            // on an ACTIVE tool falls through to keyword matching: it must not swallow the discovery of
+            // other, still-inactive keyword matches.
+            const exact = registered.find((t) => t.name.toLowerCase() === input.query.trim().toLowerCase());
+            const activeMatches = registered.filter((t) => active.has(t.name) && (t === exact || matchesQuery(t)));
+            const inactiveMatches = exact && !active.has(exact.name) ? [exact] : registered.filter((t) => !active.has(t.name) && matchesQuery(t));
+            // Same listing cap as every other branch — a wide token can match most of the ACTIVE set too
+            // (in chat that includes pi's default tools), and no answer may pour a catalog into the context.
+            const listedActive = activeMatches.slice(0, MAX_MISS_LISTING);
+            const moreActive = activeMatches.length - listedActive.length;
+            const activeNote = activeMatches.length > 0
+                ? `Already active (call directly): ${listedActive.map(describe).join("; ")}${moreActive > 0 ? ` … and ${moreActive} more` : ""}.`
+                : "";
+            if (inactiveMatches.length === 0) {
+                if (activeNote)
+                    return activeNote;
+                const inactive = registered.filter((t) => !active.has(t.name));
+                if (inactive.length === 0)
+                    return "All tools are already active — nothing to discover.";
+                // Cap the miss listing like the activation cap — both guard the same semantic (don't pour the
+                // catalog back into the context the deferral exists to protect).
+                const listed = inactive.slice(0, MAX_MISS_LISTING);
+                const more = inactive.length - listed.length;
+                return `No tools matched "${input.query}". Inactive tools: ${listed.map(describe).join("; ")}${more > 0 ? ` … and ${more} more — search with different keywords.` : ""}`;
+            }
+            if (inactiveMatches.length > MAX_ACTIVATIONS_PER_SEARCH) {
+                // Same listing cap as the miss path — an over-cap answer must not pour the catalog into the
+                // context either. Names alone suffice: the exact-name escape only needs a name to query.
+                const listed = inactiveMatches.slice(0, MAX_MISS_LISTING);
+                const more = inactiveMatches.length - listed.length;
+                return `${inactiveMatches.length} inactive tools matched "${input.query}" — too many to activate at once (activation is permanent for this conversation). Narrow the query (or query an exact name). Matches: ${listed
+                    .map((t) => t.name)
+                    .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
+            }
+            const activated = await ctx.tools.activate(inactiveMatches.map((t) => t.name));
+            // Report what actually happened, not what was attempted: a parallel sibling call may have
+            // activated the same matches first, leaving nothing new here — an empty "Activated:" would lie.
+            if (activated.length === 0) {
+                return `Matched ${inactiveMatches.map((t) => t.name).join(", ")} — already active (possibly activated by a concurrent call). Call them directly.${activeNote ? ` ${activeNote}` : ""}`;
+            }
+            const raced = inactiveMatches.filter((t) => !activated.includes(t.name));
+            return `Activated: ${inactiveMatches
+                .filter((t) => activated.includes(t.name))
+                .map(describe)
+                .join("; ")}.${raced.length > 0 ? ` Already active: ${raced.map((t) => t.name).join(", ")}.` : ""}${activeNote ? ` ${activeNote}` : ""} These tools are callable now.`;
+        },
+    });
+}

package/dist/engines/pi/tool-context.d.ts

@@ -10,8 +10,36 @@
  * build time (e.g. a stateRoot) do NOT belong here — pass them via the tool's own closure.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * The turn's tool-activation bridge — narrow closures over the CURRENT harness (invoke.ts builds it
+ * per turn), so a loader tool can activate deferred tools mid-turn without tool.ts importing the
+ * harness. pi records the change in the session (`active_tools_change`) and the per-invoke restore
+ * (harness.ts) carries it into later turns; defineTool's wrapper stamps the newly-activated names on
+ * the tool result (`addedToolNames`) — the load point native deferred-loading providers preserve the
+ * prompt-cache prefix with.
+ */
+export interface ToolActivation {
+    /** Names of the currently ACTIVE tools. */
+    active(): string[];
+    /** Every registered tool (active or not) — the discovery corpus for a loader like `search_tools`. */
+    registered(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /** ADDITIVE activation. Unknown names are filtered out before reaching pi (whose `setActiveTools`
+     *  THROWS on them); resolves the names actually newly activated (already-active names don't repeat). */
+    activate(names: string[]): Promise<string[]>;
+}
 export interface TurnContext {
     /** The session id of the current turn. */
     session: string;
+    /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
+     *  serving harness; chat.ts bridges pi's AgentSession (chat emulates deferral — same loader, same
+     *  semantics). Absent only outside any turn (a bare `fastagent tool` run). */
+    tools?: ToolActivation;
 }
 export declare const turnContext: AsyncLocalStorage<TurnContext>;
+/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
+ *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
+ *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
+export declare function additiveActivation(registered: string[], current: string[], names: string[]): string[];

package/dist/engines/pi/tool-context.js

@@ -11,3 +11,11 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 export const turnContext = new AsyncLocalStorage();
+/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
+ *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
+ *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
+export function additiveActivation(registered, current, names) {
+    const known = new Set(registered);
+    const active = new Set(current);
+    return [...new Set(names)].filter((name) => known.has(name) && !active.has(name));
+}

package/dist/engines/pi/tool.d.ts

@@ -1,22 +1,53 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
+import { type ToolActivation } from "./tool-context.ts";
 export interface ToolContext {
     /** Abort signal for the current turn — honor it to cancel in-flight work on cancellation. */
     signal?: AbortSignal;
     /** The session id of the current turn — which conversation this tool is running in. A general tool
      *  capability: partition per-conversation data, tag logs, scope state. Undefined outside a turn (a bare
      *  `fastagent tool` run, or any call with no session). (The built-in `wake` tool is one consumer — it
-     *  fires a later turn back into this same session.) */
+     *  fires a later turn back into this same session.) In a `fastagent chat` turn this is pi's LOCAL
+     *  chat session id, not a served session — serving-coupled consumers like wake are not mounted there. */
     session?: string;
+    /** Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred}
+     *  tools with it — the built-in `search_tools` is one consumer). Provided by both the serving path
+     *  (invoke.ts, over the harness) and chat (over pi's AgentSession); undefined only outside any turn
+     *  (a bare `fastagent tool` run). */
+    tools?: ToolActivation;
 }
 export interface DefineToolOptions<I extends z.ZodType> {
     /** Explicit name. Usually omitted — a `tools/<name>.ts` tool is named from its filename. */
     name?: string;
     description: string;
     input: I;
+    /**
+     * Registered but NOT initially active: the tool's schema stays out of every request (and the model's
+     *  sight) until a loader — the built-in `search_tools`, mounted automatically when any deferred tool
+     *  exists — activates it mid-turn. For tool-heavy agents: fewer schemas per turn, and on providers
+     *  with native deferred loading the activation preserves the prompt-cache prefix. The trade-off:
+     *  discovery rides entirely on this description — write it for the search. Default: false.
+     */
+    deferred?: boolean;
+    /** pi's per-tool execution mode: "sequential" makes pi run any batch containing this tool serially.
+     *  REQUIRED for a tool that activates others (a loader): pi's own diff around SDK tools (chat)
+     *  would attribute one activation to two parallel calls otherwise. */
+    executionMode?: "sequential" | "parallel";
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
+/** An AgentTool with fastagent's deferral marker — the type for raw tools handed to fastagent
+ *  (`config.tools`, L1/L2 `tools`): plain `AgentTool` has no `deferred`, so an object literal with the
+ *  marker would fail excess-property checking against upstream's type. `defineTool` produces it. */
+export type FastagentTool = AgentTool & {
+    deferred?: boolean;
+};
+/** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
+ *  AgentTool object — pi ignores it). */
+export declare function isDeferredTool(tool: AgentTool): boolean;
+/** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
+ *  could never be activated and would strand every deferred tool). */
+export declare function stripDeferredMarker(tool: AgentTool): AgentTool;
 export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): AgentTool;
 /** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
 export interface ToolCollision {

package/dist/engines/pi/tool.js

@@ -14,6 +14,19 @@ import { join } from "node:path";
 import { z } from "zod";
 import { loadModuleDir } from "../../loader.js";
 import { turnContext } from "./tool-context.js";
+/** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
+ *  AgentTool object — pi ignores it). */
+export function isDeferredTool(tool) {
+    return tool.deferred === true;
+}
+/** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
+ *  could never be activated and would strand every deferred tool). */
+export function stripDeferredMarker(tool) {
+    if (!isDeferredTool(tool))
+        return tool;
+    const { deferred: _drop, ...active } = tool;
+    return active;
+}
 /** Wrap a plain return value into pi's tool-result shape; pass a full result through unchanged. */
 function wrapResult(value) {
     if (value && typeof value === "object" && Array.isArray(value.content)) {
@@ -28,6 +41,8 @@ export function defineTool(options) {
         name: options.name ?? "",
         description: options.description,
         parameters,
+        ...(options.deferred ? { deferred: true } : {}),
+        ...(options.executionMode ? { executionMode: options.executionMode } : {}),
         async execute(_toolCallId, rawParams, signal) {
             const parsed = options.input.safeParse(rawParams);
             if (!parsed.success) {
@@ -35,7 +50,33 @@ export function defineTool(options) {
                 const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
                 return { content: [{ type: "text", text: `Invalid arguments: ${detail}` }], details: { error: detail } };
             }
-            return wrapResult(await options.execute(parsed.data, { signal, session: turnContext.getStore()?.session }));
+            const store = turnContext.getStore();
+            // Stamp tools THIS execute activates on its result — the load point that lets native
+            // deferred-loading providers add the definitions at this transcript position without
+            // invalidating the cached prompt prefix. The names come from this execute's OWN activate()
+            // calls (accumulated below), NOT from an active-set before/after diff: pi runs tool calls of a
+            // batch in parallel, and a snapshot diff would stamp a sibling's activation onto the wrong tool
+            // result, drifting the load point.
+            const added = [];
+            const tools = store?.tools
+                ? {
+                    ...store.tools,
+                    activate: async (names) => {
+                        // biome-ignore lint/style/noNonNullAssertion: guarded by the ternary above
+                        const activated = await store.tools.activate(names);
+                        added.push(...activated);
+                        return activated;
+                    },
+                }
+                : undefined;
+            const result = wrapResult(await options.execute(parsed.data, { signal, session: store?.session, tools }));
+            if (added.length > 0) {
+                // A copy, not a mutation: wrapResult passes a full AgentToolResult through by REFERENCE, and an
+                // author may legally return a shared/frozen result object — stamping in place would corrupt it
+                // across calls (or throw on frozen), only on the rare activating path.
+                return { ...result, addedToolNames: [...new Set([...(result.addedToolNames ?? []), ...added])] };
+            }
+            return result;
         },
     };
     return tool;

package/dist/engines/pi/workspace.d.ts

@@ -45,8 +45,11 @@ export declare function createPiAgentFromWorkspace(dir: string, options?: Create
     sessionsDir: string;
     /** Absolute credentials file in use (for the startup report). */
     authPath: string;
-    /** Non-default tool names in effect: config.tools + discovered tools/. */
+    /** Non-default, active-by-default tool names in effect: config.tools + discovered tools/. Each name
+     *  lives in exactly one report slot — deferred names are in {@link deferredToolNames} instead. */
     toolNames: string[];
+    /** Tools registered but not initially active (deferred) — activated via search_tools. */
+    deferredToolNames: string[];
     toolCollisions: ToolCollision[];
     /** `tools/` files that failed to import — skipped, reported by the caller, never fatal. */
     toolFailures: ModuleLoadFailure[];

package/dist/engines/pi/workspace.js

@@ -28,7 +28,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     // The run root is `dir` (cwd — where config lives, whose AGENTS.md is ② context); the agent's own
     // surface (persona/skills/tools/channels) lives in `agentDir` (config.agentDir, or `dir` when flat).
     const agentDir = resolveAgentDir(dir, config);
-    const { tools, toolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
+    const { tools, toolNames, deferredToolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
     // The state root: auth/sessions/channel state all derive from it, so FASTAGENT_STATE_DIR moves the
     // whole machine-state home in one knob (a container mounts one volume); the finer overrides below
     // still win for their specific path.
@@ -47,6 +47,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
     await ensureStateRootSelfIgnored(dir, stateRoot);
     const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
         model: modelSpec,
+        thinkingLevel: config.thinkingLevel,
         cwd: dir,
         tools: mountedTools,
         authPath,
@@ -64,6 +65,7 @@ export async function createPiAgentFromWorkspace(dir, options = {}) {
         sessionsDir,
         authPath,
         toolNames,
+        deferredToolNames,
         toolCollisions,
         toolFailures,
     };

package/dist/feishu.d.ts

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
+export { feishuChannel, defaultFeishuRoute, feishuEnvelope, type FeishuChannelOptions, type FeishuMessageEvent, type FeishuMessage, type FeishuRoute, type FeishuFailure, } from "./channels/feishu/feishu.ts";

package/dist/feishu.js

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/feishu` — the canonical Feishu (open.feishu.cn) bot-channel surface. */
+export { feishuChannel, defaultFeishuRoute, feishuEnvelope, } from "./channels/feishu/feishu.js";

package/dist/lark.d.ts

@@ -0,0 +1,3 @@
+/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
+ *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
+export { larkChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";

package/dist/lark.js

@@ -0,0 +1,3 @@
+/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
+ *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
+export { larkChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";

package/dist/open-url.d.ts

@@ -0,0 +1,2 @@
+/** Best-effort open a URL in the default browser. Callers must also print the URL for headless use. */
+export declare function openExternalUrl(url: string): void;

package/dist/open-url.js

@@ -0,0 +1,6 @@
+import { spawn } from "node:child_process";
+/** Best-effort open a URL in the default browser. Callers must also print the URL for headless use. */
+export function openExternalUrl(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).on("error", () => { });
+}

package/dist/pi.d.ts

@@ -1,5 +1,6 @@
 export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
-export { defineTool, loadTools, type DefineToolOptions, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export { defineTool, loadTools, type DefineToolOptions, type FastagentTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export type { ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
 export type { AgentTool, ExecutionEnv, Session, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
 export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";

package/dist/scaffold/add-channel.d.ts

@@ -1,8 +1,10 @@
-export type ChannelKind = "github" | "telegram";
+export type ChannelKind = "github" | "telegram" | "feishu" | "lark";
 /** An env var a scaffolded channel reads. `generate` = a random-string secret the CLI can pre-fill. */
 export interface ChannelEnv {
     name: string;
     hint: string;
+    /** Required for the channel to run. Optional values are deployed when present but never gate deploy. */
+    required: boolean;
     generate?: boolean;
 }
 /** The channel kinds `fastagent add <kind>` can scaffold. */
@@ -26,11 +28,13 @@ export interface DotEnvWriteResult {
 }
 /**
  * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept. Manual values (e.g.
- * TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is ready to
- * edit while no fake secret is committed to the user's mental model.
+ * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * `overwrite`: those are authoritative (e.g. the credentials of an app `add feishu` JUST minted —
+ * skipping them for a stale value would silently discard a fresh, unrecoverable secret). Manual values
+ * (e.g. TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is
+ * ready to edit while no fake secret is committed to the user's mental model.
  */
-export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>): Promise<DotEnvWriteResult>;
+export declare function appendChannelDotEnv(dir: string, kind: ChannelKind, generated: Record<string, string>, overwrite?: readonly string[]): Promise<DotEnvWriteResult>;
 /** Whether a channel file already exists — checked before any mutation, so a no-clobber re-add is side-effect-free. */
 export declare function channelExists(dir: string, kind: ChannelKind): Promise<boolean>;
 /**

package/dist/scaffold/add-channel.js

@@ -17,6 +17,7 @@ const CHANNEL_SCAFFOLDS = {
             {
                 name: "GITHUB_WEBHOOK_SECRET",
                 hint: "any random string; set the same value in the GitHub webhook",
+                required: true,
                 generate: true,
             },
         ],
@@ -29,14 +30,77 @@ const CHANNEL_SCAFFOLDS = {
     },
     telegram: {
         env: [
-            { name: "TELEGRAM_BOT_TOKEN", hint: "from @BotFather → /newbot" },
-            { name: "TELEGRAM_SECRET_TOKEN", hint: "any random string; verifies inbound updates", generate: true },
+            { name: "TELEGRAM_BOT_TOKEN", hint: "from @BotFather → /newbot", required: true },
+            {
+                name: "TELEGRAM_SECRET_TOKEN",
+                hint: "any random string; verifies inbound updates",
+                required: true,
+                generate: true,
+            },
         ],
         steps: [
             "edit {channel} — customise routing with route() (optional; the defaults already work)",
             "the agent can send messages or files back by calling the scaffolded {tools}/telegram-send.ts tool",
         ],
     },
+    // Feishu is the canonical engine/cloud; Lark international reuses its protocol through a degraded
+    // compatibility profile. Each remains its own channel KIND: route, env, state, console, onboarding.
+    // No `generate` in either: every value comes FROM the platform (a locally generated Encrypt Key
+    // would break inbound events until mirrored in the console). `add feishu` scan-creates the app;
+    // Lark lacks that control-plane capability, so `add lark` guides console credential collection.
+    feishu: {
+        env: [
+            {
+                name: "FEISHU_APP_ID",
+                hint: "created + written automatically by `add feishu` (console → Credentials & Basic Info)",
+                required: true,
+            },
+            {
+                name: "FEISHU_APP_SECRET",
+                hint: "created + written automatically by `add feishu` (console → Credentials & Basic Info)",
+                required: true,
+            },
+            {
+                name: "FEISHU_VERIFICATION_TOKEN",
+                hint: "captured automatically (console → Events & Callbacks)",
+                required: true,
+            },
+            {
+                name: "FEISHU_ENCRYPT_KEY",
+                hint: "optional but recommended — set one in the console and copy it here",
+                required: false,
+            },
+        ],
+        steps: [
+            "optional before publishing: add the sensitive im:message.group_msg permission (tenant-admin approval) to receive unmentioned managed-thread continuations and buffer other group discussion",
+            "PUBLISH the app version on the page the CLI opened — the switch to webhook mode takes effect on publish (one click, once ever; no API for it)",
+            "edit {channel} — routing policy (the header walks through the console setup, for hand-made apps)",
+            "the event Request URL is auto-registered by `dev --tunnel` / `deploy --run`",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
+        ],
+    },
+    lark: {
+        env: [
+            { name: "LARK_APP_ID", hint: "developer console → Credentials & Basic Info", required: true },
+            { name: "LARK_APP_SECRET", hint: "developer console → Credentials & Basic Info", required: true },
+            {
+                name: "LARK_VERIFICATION_TOKEN",
+                hint: "console → Events & Callbacks; authenticates inbound events",
+                required: true,
+            },
+            {
+                name: "LARK_ENCRYPT_KEY",
+                hint: "optional but recommended — set one in the console and copy it here",
+                required: false,
+            },
+        ],
+        steps: [
+            "finish the console setup: enable Bot and add the required permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
+            "optional before publishing: add the sensitive im:message.group_msg permission (tenant-admin approval) to receive unmentioned managed-thread continuations and buffer other group discussion",
+            "run `fastagent dev --tunnel` and keep it running; if auto-registration reports a config-API 404, manually switch Subscription mode to webhook, set its printed https://…/lark Request URL, save, then create + publish a version",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
+        ],
+    },
 };
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
@@ -83,11 +147,13 @@ function mentionsEnvName(content, name) {
 }
 /**
  * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept. Manual values (e.g.
- * TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is ready to
- * edit while no fake secret is committed to the user's mental model.
+ * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * `overwrite`: those are authoritative (e.g. the credentials of an app `add feishu` JUST minted —
+ * skipping them for a stale value would silently discard a fresh, unrecoverable secret). Manual values
+ * (e.g. TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is
+ * ready to edit while no fake secret is committed to the user's mental model.
  */
-export async function appendChannelDotEnv(dir, kind, generated) {
+export async function appendChannelDotEnv(dir, kind, generated, overwrite = []) {
     const file = join(dir, ".env");
     let current = "";
     try {
@@ -97,7 +163,9 @@ export async function appendChannelDotEnv(dir, kind, generated) {
         if (e.code !== "ENOENT")
             throw e;
     }
-    const alreadySet = CHANNEL_SCAFFOLDS[kind].env.filter((e) => hasActiveEnvValue(current, e.name)).map((e) => e.name);
+    const alreadySet = CHANNEL_SCAFFOLDS[kind].env
+        .filter((e) => !overwrite.includes(e.name) && hasActiveEnvValue(current, e.name))
+        .map((e) => e.name);
     const lines = [];
     const written = [];
     const contentLines = current.split("\n");

package/dist/scaffold/templates/fastagent.config.mjs

@@ -7,6 +7,7 @@
 // you have access to (`fastagent models` lists them).
 export default {
   // model: "openai-codex/gpt-5.5",
+  // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max); default "medium" (pi TUI parity)
   http: { port: 8787 },
   // selfSchedule: true, // mount the built-in `wake` tool: the agent schedules its own follow-up turns
   //                     // ("check the deploy in 10 min"). Cron jobs need no opt-in — drop a schedules/<name>.ts.

package/dist/tunnel.d.ts

@@ -1,7 +1,8 @@
 /**
  * `--tunnel`: expose the local dev server on a public HTTPS URL via a Cloudflare quick tunnel, then
- * auto-register the first-party webhook channels against it (telegram setWebhook; github prints the
- * URL to paste into repo settings). This closes the "local dev → public URL" gap webhooks need.
+ * auto-register the first-party webhook channels against it (Telegram setWebhook; Feishu/Lark
+ * application-config PATCH; GitHub prints the URL to paste into repo settings). This closes the
+ * "local dev → public URL" gap webhooks need.
  *
  * Process orchestration, not assembly — lives outside the engine, beside dev-supervisor.ts.
  */
@@ -22,10 +23,12 @@ type SpawnCloudflared = (port: number) => ChildProcess;
  * (Edge warmup AFTER the URL appears is handled downstream: the telegram registrar polls /health before
  * it calls setWebhook, so a not-yet-routable tunnel just delays registration rather than failing it.)
  */
-export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloudflared): Promise<Tunnel | undefined>;
+export declare function startCloudflareTunnel(port: number, spawnFn?: SpawnCloudflared, attemptTimeoutMs?: number): Promise<Tunnel | undefined>;
 /**
- * Print the public URL and wire up the first-party webhook channels found under `dir`: telegram is
- * auto-registered via setWebhook (using .env tokens); github prints the URL to add in repo settings.
+ * Print the public URL and wire up the first-party webhook channels found under `dir`: Telegram and
+ * Feishu/Lark auto-register using credentials from .env; GitHub prints the URL to add in repo settings.
  */
-export declare function announceWebhooks(dir: string, baseUrl: string): Promise<void>;
+export declare function announceWebhooks(dir: string, baseUrl: string, opts?: {
+    openUrl?: (url: string) => void;
+}): Promise<void>;
 export {};