@fastagent-sh/fastagent 0.19.0 → 0.21.0

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

@@ -26,11 +26,36 @@ export function agentSessionManager(session, sessionId) {
         },
     };
 }
+/**
+ * The activation bridge over a live pi session — the ONE implementation, for both consumers.
+ *
+ * Serving (`agent-session-factory.ts`) and chat (`session-builder.ts`) had a copy each, identical
+ * but for the persistence line; the neighbouring `definitionResourceLoaderOptions` exists because
+ * that exact duplication drifted once before. The difference is a PARAMETER now: `onActivated` is
+ * what a served session uses to record the delta that carries the discovery into its next turn,
+ * and chat has nowhere to put one (pi's SessionContext has no active-tool set).
+ *
+ * Bind it to the SESSION, never to a tool call: the next call has to see what this one activated.
+ */
+export function sessionToolActivation(session, onActivated) {
+    return {
+        active: () => session.getActiveToolNames(),
+        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+        activate(names) {
+            const current = session.getActiveToolNames();
+            const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
+            if (added.length === 0)
+                return added;
+            session.setActiveToolsByName([...current, ...added]);
+            onActivated?.(added);
+            return added;
+        },
+    };
+}
 export const turnContext = new AsyncLocalStorage();
-/** The additive-activation contract, in ONE place for both bridges (the served session,
- *  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) {
+/** dedupe → keep registered names only (pi's setters THROW on unknown) → exclude already-active →
+ *  the names to actually add (empty = nothing to set). */
+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,4 +1,5 @@
-import type { AgentHarnessTool, ExecutionToolContext, AgentTool } from "@earendil-works/pi-agent-core";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
 import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
@@ -34,14 +35,10 @@ export interface DefineToolOptions<I extends z.ZodType> {
     executionMode?: "sequential" | "parallel";
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
-/**
- * A tool as MOUNTED: what the engine actually runs. Wider than the authored {@link AgentTool} on
- * purpose — a lower-level mounted tool may read an `ExecutionEnv` from the fifth `execute` parameter,
- * while coding-agent's cwd-bound tools ignore it and fastagent's authored tools take four arguments.
- * Naming the wider type is what lets `defineTool` stay context-free for authors while both families
- * live in one array; every helper that only inspects or reorders tools is typed on THIS.
- */
-export type MountedTool = AgentHarnessTool<ExecutionToolContext>;
+/** AgentTool with Pi's optional per-call context; absent for sessionless CLI execution. */
+export type MountedTool = Omit<AgentTool, "execute"> & {
+    execute(...args: [...Parameters<AgentTool["execute"]>, context?: ExtensionContext]): ReturnType<AgentTool["execute"]>;
+};
 /** 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. */

package/dist/engines/pi/tool.js

@@ -40,6 +40,7 @@ export function defineTool(options) {
     const { $schema: _drop, ...parameters } = z.toJSONSchema(options.input);
     const tool = {
         name: options.name ?? "",
+        label: options.name ?? "",
         description: options.description,
         parameters,
         ...(options.deferred ? { deferred: true } : {}),
@@ -62,9 +63,9 @@ export function defineTool(options) {
             const tools = store?.tools
                 ? {
                     ...store.tools,
-                    activate: async (names) => {
+                    activate: (names) => {
                         // biome-ignore lint/style/noNonNullAssertion: guarded by the ternary above
-                        const activated = await store.tools.activate(names);
+                        const activated = store.tools.activate(names);
                         added.push(...activated);
                         return activated;
                     },

package/dist/env.js

@@ -1,6 +1,5 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { existsSync } from "node:fs";
 import { log } from "./log.js";
 import { SECRETS_DIRNAME, resolveSecretsDir } from "./paths.js";
 /**

package/dist/feishu.d.ts

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

package/dist/feishu.js

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

package/dist/lark.d.ts

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

package/dist/lark.js

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

package/dist/loader.d.ts

@@ -1,5 +1,48 @@
-/** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-export declare function isModuleFile(name: string): boolean;
+/** One module file a directory declares. `name` is what the domain knows it by; nothing is imported
+ *  to produce this. */
+export interface InventoryEntry {
+    /** Basename without extension — the authoritative name for tools/channels/schedules. */
+    name: string;
+    /** "tools/foo.ts"-style label for errors and collisions. */
+    label: string;
+    file: string;
+}
+/**
+ * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules",
+ * without importing any of them.
+ *
+ * It exists because four consumers need that answer and only one of them may import: the loader
+ * below, `fastagent info`'s channel listing, `--tunnel`'s webhook registration, and the deploy
+ * pre-flight's schedule probe. When they each read the directory themselves they disagreed — on
+ * what counts as a module file, on how to strip the extension, on which errno means "no such
+ * directory" — and a fix had to be applied in four places, which is why the fourth kept being
+ * missed. There is one reading now; what to DO with a failure stays with the caller, because that
+ * genuinely differs (the loader throws, the tunnel cannot).
+ *
+ * A missing directory is an empty inventory. Everything else throws, ENOTDIR included: `channels`
+ * and `schedules` are named directories, so the path existing as a FILE is a mistake in the agent
+ * rather than an agent without one (`service.test.ts` pins that for `schedules`). `paths.ts` folds
+ * ENOTDIR into its empty scan for the opposite reason — it asks which children HAPPEN to be agent
+ * dirs, where a file simply is not one. `not_found` is a non-Node runtime's ENOENT.
+ *
+ * SYMLINKS ARE SKIPPED, and that is a boundary rather than an oversight: `assertInsideAgentDir`
+ * guards the code-input DIRECTORY against escaping the definition, and nothing guards the entries
+ * inside it, so following a link would import from anywhere on the box past the very check meant to
+ * prevent it. Do not "fix" this by following them — report them, which this does.
+ *
+ * The skip is WARNED HERE, not handed back, because "this file is not loadable" holds for all four
+ * consumers and only one of them imports — a listing that reports the name it cannot load reads as
+ * "I never created it". What to do about a load FAILURE does differ per caller, so that travels as
+ * data. One warning per READ, so a command that both lists and loads the same directory (`deploy
+ * agentcore` does) says it twice — both readings are true, and remembering what was already said
+ * would mean a restart stops mentioning a skip that is still there.
+ *
+ * A skip is therefore a warning ONLY, unlike a {@link ModuleLoadFailure}: it is absent from `info
+ * --json` and `deploy` does not gate on it. That is the deliberate cost of one report for four
+ * consumers, three of which list names and have nowhere to put data. To give a machine consumer the
+ * skips, return them beside the entries — do not reconstruct them from stderr.
+ */
+export declare function moduleInventory(subDir: string): Promise<InventoryEntry[]>;
 export interface DiscoveredModule {
     /** Basename without extension — the authoritative name for tools/channels. */
     name: string;
@@ -20,12 +63,13 @@ export interface ModuleLoadFailure {
     /** The failure message (an import error carries {@link moduleLoadHint}). */
     message: string;
 }
+/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+export declare function reportModuleLoadFailures(failures: readonly ModuleLoadFailure[]): void;
 /**
- * Import every module file in `subDir`, sorted by name. Missing dir returns none. A file that fails to
- * IMPORT is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
- * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures the
- * same way. (A missing DIRECTORY still returns empty; an unreadable directory still throws
- * — that's not a per-file problem.)
+ * Import every module the directory declares ({@link moduleInventory}). A file that fails to IMPORT
+ * is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
+ * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures
+ * the same way. Entries the inventory SKIPPED are already reported by it, for every consumer.
  */
 export declare function loadModuleDir(subDir: string): Promise<{
     modules: DiscoveredModule[];

package/dist/loader.js

@@ -9,40 +9,106 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { log } from "./log.js";
 const MODULE_EXTS = new Set([".ts", ".js", ".mjs"]);
 /** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-export function isModuleFile(name) {
+function isModuleFile(name) {
     return MODULE_EXTS.has(extname(name)) && !name.endsWith(".d.ts");
 }
+/** The name a module is known by: its basename without the extension. */
+function moduleName(fileName) {
+    return basename(fileName, extname(fileName));
+}
 /**
- * Import every module file in `subDir`, sorted by name. Missing dir returns none. A file that fails to
- * IMPORT is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
- * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures the
- * same way. (A missing DIRECTORY still returns empty; an unreadable directory still throws
- * — that's not a per-file problem.)
+ * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules",
+ * without importing any of them.
+ *
+ * It exists because four consumers need that answer and only one of them may import: the loader
+ * below, `fastagent info`'s channel listing, `--tunnel`'s webhook registration, and the deploy
+ * pre-flight's schedule probe. When they each read the directory themselves they disagreed — on
+ * what counts as a module file, on how to strip the extension, on which errno means "no such
+ * directory" — and a fix had to be applied in four places, which is why the fourth kept being
+ * missed. There is one reading now; what to DO with a failure stays with the caller, because that
+ * genuinely differs (the loader throws, the tunnel cannot).
+ *
+ * A missing directory is an empty inventory. Everything else throws, ENOTDIR included: `channels`
+ * and `schedules` are named directories, so the path existing as a FILE is a mistake in the agent
+ * rather than an agent without one (`service.test.ts` pins that for `schedules`). `paths.ts` folds
+ * ENOTDIR into its empty scan for the opposite reason — it asks which children HAPPEN to be agent
+ * dirs, where a file simply is not one. `not_found` is a non-Node runtime's ENOENT.
+ *
+ * SYMLINKS ARE SKIPPED, and that is a boundary rather than an oversight: `assertInsideAgentDir`
+ * guards the code-input DIRECTORY against escaping the definition, and nothing guards the entries
+ * inside it, so following a link would import from anywhere on the box past the very check meant to
+ * prevent it. Do not "fix" this by following them — report them, which this does.
+ *
+ * The skip is WARNED HERE, not handed back, because "this file is not loadable" holds for all four
+ * consumers and only one of them imports — a listing that reports the name it cannot load reads as
+ * "I never created it". What to do about a load FAILURE does differ per caller, so that travels as
+ * data. One warning per READ, so a command that both lists and loads the same directory (`deploy
+ * agentcore` does) says it twice — both readings are true, and remembering what was already said
+ * would mean a restart stops mentioning a skip that is still there.
+ *
+ * A skip is therefore a warning ONLY, unlike a {@link ModuleLoadFailure}: it is absent from `info
+ * --json` and `deploy` does not gate on it. That is the deliberate cost of one report for four
+ * consumers, three of which list names and have nowhere to put data. To give a machine consumer the
+ * skips, return them beside the entries — do not reconstruct them from stderr.
  */
-export async function loadModuleDir(subDir) {
-    let entries;
+export async function moduleInventory(subDir) {
+    let dirents;
     try {
-        entries = await readdir(subDir, { withFileTypes: true });
+        dirents = await readdir(subDir, { withFileTypes: true });
     }
     catch (error) {
-        const e = error;
-        if (e.code === "ENOENT" || e.code === "not_found")
-            return { modules: [], failures: [] };
+        const code = error.code;
+        if (code === "ENOENT" || code === "not_found")
+            return [];
         throw new Error(`cannot read ${subDir}: ${error.message}`);
     }
     const sub = basename(subDir);
+    const entries = [];
+    // Sorted by the NAME a consumer sees, so none of them re-sorts and none can disagree about order.
+    // Filename breaks a tie: `foo.js` and `foo.ts` both read as `foo`, and the domain loaders document
+    // that the FIRST wins — deciding that here keeps it from depending on readdir's order.
+    const byName = (a, b) => moduleName(a.name).localeCompare(moduleName(b.name)) || a.name.localeCompare(b.name);
+    for (const dirent of dirents.sort(byName)) {
+        if (!isModuleFile(dirent.name))
+            continue;
+        const label = `${sub}/${dirent.name}`;
+        if (dirent.isFile()) {
+            entries.push({ name: moduleName(dirent.name), label, file: join(subDir, dirent.name) });
+        }
+        else if (dirent.isSymbolicLink()) {
+            log.warn(`[fastagent] ${label} is a symlink — code inputs must be real files inside the agent dir — not loaded`);
+        }
+        else if (dirent.isDirectory()) {
+            log.warn(`[fastagent] ${label} is a directory, not a file — not loaded`);
+        }
+        else {
+            log.warn(`[fastagent] ${label} is not a regular file — not loaded`);
+        }
+    }
+    return entries;
+}
+/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+export function reportModuleLoadFailures(failures) {
+    for (const f of failures)
+        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
+}
+/**
+ * Import every module the directory declares ({@link moduleInventory}). A file that fails to IMPORT
+ * is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
+ * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures
+ * the same way. Entries the inventory SKIPPED are already reported by it, for every consumer.
+ */
+export async function loadModuleDir(subDir) {
+    const entries = await moduleInventory(subDir);
     const modules = [];
     const failures = [];
-    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-        if (!entry.isFile() || !isModuleFile(entry.name))
-            continue;
-        const file = join(subDir, entry.name);
-        const label = `${sub}/${entry.name}`;
+    for (const { name, label, file } of entries) {
         try {
             const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
-            modules.push({ name: basename(entry.name, extname(entry.name)), label, file, mod });
+            modules.push({ name, label, file, mod });
         }
         catch (error) {
             failures.push({

package/dist/log.d.ts

@@ -8,22 +8,14 @@
  * This is NOT the CLI's user-facing output (help text, command results): that is the program talking to
  * its operator and stays on plain `console`. Everything here is operational logging to stderr.
  */
-export type LogLevel = "debug" | "info" | "warn" | "error";
-export interface Logger {
-    debug(msg: string): void;
-    info(msg: string): void;
-    warn(msg: string): void;
-    error(msg: string): void;
-}
-/** An embedded logger over an explicit sink — used in tests to assert level gating without the singleton. */
-export declare function createLogger(opts: {
-    level: LogLevel;
-    sink?: (line: string) => void;
-}): Logger;
-/** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` override, if present, wins and is not changed. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` wins over it, whenever a line is emitted. */
 export declare function setLogLevel(level: LogLevel): void;
 /** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
-import type { ModuleLoadFailure } from "./loader.ts";
-export declare const log: Logger;
-/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
-export declare function reportModuleLoadFailures(failures: readonly ModuleLoadFailure[]): void;
+export declare const log: {
+    debug: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+export {};

package/dist/log.js

@@ -9,47 +9,42 @@
  * its operator and stays on plain `console`. Everything here is operational logging to stderr.
  */
 const ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
-const isLevel = (s) => s in ORDER;
+const isLevel = (s) => Object.hasOwn(ORDER, s);
 const format = (level, msg) => `${level.toUpperCase().padEnd(5)} ${msg}`;
-/** An embedded logger over an explicit sink — used in tests to assert level gating without the singleton. */
-export function createLogger(opts) {
-    const sink = opts.sink ?? ((line) => console.error(line));
-    const make = (level) => (msg) => {
-        if (ORDER[level] >= ORDER[opts.level])
-            sink(format(level, msg));
-    };
-    return { debug: make("debug"), info: make("info"), warn: make("warn"), error: make("error") };
-}
 /**
- * `FASTAGENT_LOG_LEVEL` parsed to three states: a valid value locks the level (overrides posture); a
- * present-but-invalid value warns and is treated as absent, so a typo (meant to make logs louder) can
- * never silently pin the level to info nor kill the posture default; absent returns undefined. The
- * warning is raw — the singleton below is not built yet — but reuses `format` for the same shape.
+ * `FASTAGENT_LOG_LEVEL` resolved PER EMIT, not at import: this module is imported transitively by every
+ * command module, so an import-time read runs before any command reaches `loadDotEnv` and could never
+ * see the agent's `.secrets/.env` — a key that file could not carry at all.
+ *
+ * Three states: a valid value wins over the posture; an invalid value warns when it differs from the
+ * last warned value and is treated as absent, so a typo (meant to make logs louder) can never silently pin the
+ * level nor kill the posture default; absent leaves the posture. Empty is absent, matching
+ * `resolveOverridePath` — `KEY=` is how a `.env` parks a key it does not want set, not a typo to warn
+ * about. The warning is raw `console.error` because it is the logger reporting on its own gate, but
+ * reuses `format` for the same shape.
  */
-function parseEnvOverride() {
+let posture = "info";
+let warnedFor;
+function effectiveLevel() {
     const raw = process.env.FASTAGENT_LOG_LEVEL;
-    if (raw === undefined)
-        return undefined;
+    if (!raw)
+        return posture;
     const value = raw.toLowerCase();
     if (isLevel(value))
         return value;
-    console.error(format("warn", `[fastagent] unknown FASTAGENT_LOG_LEVEL "${raw}"; using the posture default`));
-    return undefined;
+    if (warnedFor !== raw) {
+        warnedFor = raw;
+        console.error(format("warn", `[fastagent] unknown FASTAGENT_LOG_LEVEL "${raw}"; using the posture default`));
+    }
+    return posture;
 }
-const override = parseEnvOverride();
-let currentLevel = override ?? "info";
-/** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` override, if present, wins and is not changed. */
+/** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` wins over it, whenever a line is emitted. */
 export function setLogLevel(level) {
-    if (override === undefined)
-        currentLevel = level;
+    posture = level;
 }
 const emit = (level) => (msg) => {
-    if (ORDER[level] >= ORDER[currentLevel])
+    if (ORDER[level] >= ORDER[effectiveLevel()])
         console.error(format(level, msg));
 };
+/** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
 export const log = { debug: emit("debug"), info: emit("info"), warn: emit("warn"), error: emit("error") };
-/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
-export function reportModuleLoadFailures(failures) {
-    for (const f of failures)
-        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
-}

package/dist/paths.d.ts

@@ -62,9 +62,9 @@ export declare function agentsAt(dir: string): string[];
  * reader to a refusal whose own advice points back here.
  */
 export declare function workspaceHint({ agentDir, workspace }: ResolvedPlacement, env?: NodeJS.ProcessEnv): string | undefined;
-/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair,
- *  and without the throw. `login` is the caller: it is the one command allowed to run outside an agent,
- *  so it needs the answer as a value rather than as a refusal. */
+/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair
+ *  or the throw. Login and standalone channel senders also operate outside configured agents, so
+ *  they need absence as a value. Filesystem errors still propagate. */
 export declare function findAgentDir(dir: string): string | undefined;
 /**
  * The agent whose DEFINITION contains `dir` — scaffolding there would make the new agent part of the
@@ -104,6 +104,10 @@ export declare function displayPath(cwd: string, dir: string): string | undefine
 /** Does a path exist? Plain fs, no placement in it — it lives here because `paths.ts` is where the
  *  neutral path helpers are, and the scaffolder is not a utility home for the CLI and deploy. */
 export declare function exists(p: string): Promise<boolean>;
+/** The file's text, or undefined when there is no file. ONLY absence reads as absence: a file that
+ *  exists but cannot be read (EACCES, a directory in its place) throws, because a decision made on
+ *  "not there" — regenerate it, skip its gate — is the wrong one for a file that is there. */
+export declare function readTextIfExists(p: string): Promise<string | undefined>;
 /**
  * Resolve a user-supplied path override (a CLI flag or an env var) to an absolute path, expanding a
  * leading `~`/`~/` to the home dir FIRST. Path-valued config from `.env` (or any non-shell source)
@@ -136,6 +140,25 @@ export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv):
  * auth.json but cannot move the file it is read from (env.ts dotEnvPath).
  */
 export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
+/** What a file under {@link resolveSecretsDir} is written with (auth.json, .env). */
+export declare const SECRET_FILE_MODE = 384;
+/**
+ * Create the secrets directory with the mode its contents require — and REPAIR it when it already
+ * exists, which is the case that matters.
+ *
+ * The DIRECTORY is the boundary that actually protects a credential: without its `x` bit nothing
+ * below it is reachable, whatever a file's own mode says. And it is decided ONCE, by whichever
+ * writer gets there first — `mkdir`'s `mode` is ignored for a directory that already exists, so a
+ * later, more careful caller silently inherits the first one's answer. Four callers create this
+ * directory (`init`, `add <channel>`, the credential store, the deploy seed) and the ordinary order
+ * is init → add → login, so the careful one is LAST: the rule has to live where all of them can
+ * reach it, and it has to chmod rather than trust the create.
+ *
+ * A chmod the caller never asked for owes them its reason: the raw `EPERM ... chmod '/shared/creds'`
+ * reads as a bug in whatever they WERE doing (storing a credential), not as fastagent tightening a
+ * directory they pointed it at, and says nothing about the way out.
+ */
+export declare function ensureSecretsDir(dir: string): Promise<void>;
 /**
  * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
  * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.

package/dist/paths.js

@@ -16,8 +16,7 @@
  * modules depend on it for something the engine has no say in.
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { access } from "node:fs/promises";
-import { realpath } from "node:fs/promises";
+import { access, chmod, mkdir, readFile, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 /**
@@ -160,9 +159,9 @@ export function workspaceHint({ agentDir, workspace }, env = process.env) {
         return undefined;
     return `${parent} looks like a project — point fastagent at it (\`..\`) to have the agent work ON it`;
 }
-/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair,
- *  and without the throw. `login` is the caller: it is the one command allowed to run outside an agent,
- *  so it needs the answer as a value rather than as a refusal. */
+/** The agent dir for `dir`, or undefined when there is none — {@link findPlacement} without the pair
+ *  or the throw. Login and standalone channel senders also operate outside configured agents, so
+ *  they need absence as a value. Filesystem errors still propagate. */
 export function findAgentDir(dir) {
     return findPlacement(dir)?.agentDir;
 }
@@ -268,6 +267,19 @@ export function displayPath(cwd, dir) {
 export async function exists(p) {
     return access(p).then(() => true, () => false);
 }
+/** The file's text, or undefined when there is no file. ONLY absence reads as absence: a file that
+ *  exists but cannot be read (EACCES, a directory in its place) throws, because a decision made on
+ *  "not there" — regenerate it, skip its gate — is the wrong one for a file that is there. */
+export async function readTextIfExists(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
 /**
  * Resolve a user-supplied path override (a CLI flag or an env var) to an absolute path, expanding a
  * leading `~`/`~/` to the home dir FIRST. Path-valued config from `.env` (or any non-shell source)
@@ -309,6 +321,32 @@ export function resolveStateRoot(dir, env = process.env) {
 export function resolveSecretsDir(dir, env = process.env) {
     return resolveOverridePath(env.FASTAGENT_SECRETS_DIR) ?? join(resolve(dir), SECRETS_DIRNAME);
 }
+/** What a file under {@link resolveSecretsDir} is written with (auth.json, .env). */
+export const SECRET_FILE_MODE = 0o600;
+/** What the secrets directory itself is created with. */
+const SECRETS_DIR_MODE = 0o700;
+/**
+ * Create the secrets directory with the mode its contents require — and REPAIR it when it already
+ * exists, which is the case that matters.
+ *
+ * The DIRECTORY is the boundary that actually protects a credential: without its `x` bit nothing
+ * below it is reachable, whatever a file's own mode says. And it is decided ONCE, by whichever
+ * writer gets there first — `mkdir`'s `mode` is ignored for a directory that already exists, so a
+ * later, more careful caller silently inherits the first one's answer. Four callers create this
+ * directory (`init`, `add <channel>`, the credential store, the deploy seed) and the ordinary order
+ * is init → add → login, so the careful one is LAST: the rule has to live where all of them can
+ * reach it, and it has to chmod rather than trust the create.
+ *
+ * A chmod the caller never asked for owes them its reason: the raw `EPERM ... chmod '/shared/creds'`
+ * reads as a bug in whatever they WERE doing (storing a credential), not as fastagent tightening a
+ * directory they pointed it at, and says nothing about the way out.
+ */
+export async function ensureSecretsDir(dir) {
+    await mkdir(dir, { recursive: true, mode: SECRETS_DIR_MODE });
+    await chmod(dir, SECRETS_DIR_MODE).catch((e) => {
+        throw new Error(`cannot secure secrets dir ${dir} (fastagent keeps it 0700): ${e.message} — point --auth-path/FASTAGENT_SECRETS_DIR at a directory this process owns`, { cause: e });
+    });
+}
 /**
  * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
  * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.

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

@@ -57,8 +57,13 @@ export declare function channelExists(dir: string, kind: ChannelKind): Promise<b
  */
 export declare function scaffoldChannel(dir: string, kind: ChannelKind, options?: {
     ingress?: FeishuSubscriptionMode;
-    groupBehavior?: GroupBehavior;
 }): Promise<string>;
+/**
+ * The bundle's companion tools (every `.ts` beside `channel.ts` → `tools/<name>`). Unlike the channel
+ * file they are the package's, not authored glue, so they are written on EVERY add: re-running
+ * `add <kind>` is how an upgraded tool reaches an existing agent.
+ */
+export declare function scaffoldCompanionTools(dir: string, kind: ChannelKind): Promise<string[]>;
 /**
  * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares
  * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that