@fastagent-sh/fastagent 0.20.0 → 0.21.0

package/dist/engines/pi/session-store.js

@@ -1,10 +1,6 @@
 /**
  * Session persistence for the `AgentSession` L0 — open-or-create a durable record by the Caller's
  * opaque session id, on pi-coding-agent's `SessionManager` (the v3 jsonl every pi surface reads).
- *
- * Records written before this store existed (by the pi-agent-core `Session` the serving path used
- * to run on) are the same v3 jsonl and are continued in place — see `legacySessionId`. That is a
- * READ path for existing conversations, not a second engine.
  */
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
@@ -27,10 +23,10 @@ import { copyBranchForInheritance, copyBranchInto, inheritanceCut, } from "./ses
  * produce one output. `_` escapes itself for the same reason. A trailing `.` or `-` is legal
  * mid-name but not at the end, so it escapes too.
  *
- * Injective within this encoding — which is only sufficient because new records live in their own
- * directory. The older spelling draws names from the same character set (it stored a room literally
- * called `s42` as `s42`, which is also this encoding of `42`), so one directory would make some
- * names ambiguous no matter how either side spells them.
+ * Injective within this encoding — which is only sufficient because this store's records live in
+ * their own directory. A name this store did not write draws from the same character set and can
+ * still decode: a file called `s42` is also this encoding of `42`, so one directory would make some
+ * names ambiguous no matter how this side spells them.
  *
  * Readability is deliberate: `-1001234567890` becomes `s-1001234567890`, so an operator can still
  * tell which room a file belongs to.
@@ -81,24 +77,19 @@ export function callerSessionId(recordId) {
  * each header and would make a renamed agent directory look like an empty store (see
  * {@link recordFiles}).
  *
- * NEW records live in a subdirectory of their own, because the two engines cannot share a namespace:
- * both spell ids into `[A-Za-z0-9._-]`, so neither can claim a prefix the other cannot produce, and
- * a directory holding both would have names that belong to two conversations at once — in whichever
- * direction it is read. Separate directories make each side's own injectivity sufficient.
- *
- * A PRE-EXISTING record is continued in place: looked up by the older spelling, which is injective
- * on its own terms, and appended to where it lies. Both spellings are the same v3 jsonl, so a
- * conversation started before this store keeps going rather than restarting empty. Nothing on disk
- * is rewritten.
+ * Records live in a subdirectory of their own, because a name this store did not write can still
+ * decode to a Caller id: a file called `s42` beside them is also this encoding of `42`, so a shared
+ * directory would answer `42` with a record it does not own. Only this directory is scanned, which
+ * makes this encoding's own injectivity sufficient — a record written before this store existed
+ * lies outside it and is never read.
  *
  * SCOPE OF "open-or-create": idempotent against a store that is serialized per session, which is what
  * the serving path provides — the single-writer lease is taken before any store call, so no two
  * turns of one conversation reach this at once. What it does NOT do is arbitrate a FIRST open racing
  * across processes: two instances that scan before either writes will both create, and the
- * conversation forks into two records. sessions.ts states the same boundary for the same reason
- * ("the serving path serializes it with the single-writer lease before reaching any store"), and a
- * horizontally-scaled deployment that wants more owes a lease that spans its instances — an
- * in-process one cannot arbitrate between them, and a file lock here would only look like it could.
+ * conversation forks into two records. A horizontally-scaled deployment that wants more owes a lease
+ * that spans its instances — an in-process one cannot arbitrate between them, and a file lock here
+ * would only look like it could.
  */
 export function piSessionRecordStore(options) {
     const cwd = options.cwd ?? process.cwd();
@@ -178,15 +169,11 @@ export function piSessionRecordStore(options) {
     /** The unreadable records the last listing reported, so a polled endpoint states the condition
      *  once rather than once a second. */
     let lastUnreadable = "";
-    /** WHERE a session's record is, under either spelling — the one lookup every caller shares, so a
-     *  fix to it (this store's own directory rather than pi's cwd-filtered listing) cannot reach three
-     *  of the four. */
+    /** WHERE a session's record is — the one lookup every caller shares, so a fix to it (this store's
+     *  own directory rather than pi's cwd-filtered listing) cannot reach three of the four. */
     const locate = (sessionId) => {
         const mine = recordFiles(own).find((f) => f.id === piSessionId(sessionId));
-        if (mine)
-            return { path: mine.path, dir: own };
-        const legacy = recordFiles(root).find((f) => f.id === legacySessionId(sessionId));
-        return legacy ? { path: legacy.path, dir: root } : undefined;
+        return mine ? { path: mine.path, dir: own } : undefined;
     };
     /** Open an existing record, or undefined. A closure rather than a method call, so `fork` cannot be
      *  broken by a caller that spreads this object into another one. */
@@ -217,8 +204,8 @@ export function piSessionRecordStore(options) {
             const rows = [];
             const unreadable = [];
             for (const file of files) {
-                // A record this store did not write (the older spelling) cannot be decoded back to a Caller
-                // id, and a row nobody can dial is worse than a row that is missing. It stays openable BY id.
+                // A name this store did not write cannot be decoded back to a Caller id, and a row nobody
+                // can dial is worse than a row that is missing.
                 const session = callerSessionId(file.id);
                 if (!session)
                     continue;
@@ -544,7 +531,7 @@ function reconcileInterruptedToolCalls(record) {
     }
     return record;
 }
-/** Where this engine's own records live, under the sessions directory both engines are pointed at. */
+/** Where the records live, under the sessions directory the store is pointed at. */
 const OWN_RECORDS_DIR = "agent-session";
 /**
  * Make a NEW record exist on disk before anyone can act on it.
@@ -655,12 +642,3 @@ export function piInMemorySessionRecordStore(options = {}) {
         },
     };
 }
-/** The spelling used before this store existed — read-only, so older records still resolve. */
-function legacySessionId(sessionId) {
-    return sessionId.replace(/[^A-Za-z0-9._-]/g, (c) => {
-        const code = c.charCodeAt(0);
-        return code < 0x100
-            ? `%${code.toString(16).toUpperCase().padStart(2, "0")}`
-            : `%u${code.toString(16).toUpperCase().padStart(4, "0")}`;
-    });
-}

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

@@ -67,9 +67,9 @@ export interface TurnContext {
     cwd?: string;
     /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
     sessionManager?: ReadonlySessionManager;
-    /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
-     *  served session; chat.ts bridges the resident one (chat emulates deferral — same loader, same
-     *  semantics). Absent only outside any turn (a bare `fastagent tool` run). */
+    /** Tool activation for the current turn. Two producers, one consumer surface: agent-session-factory.ts
+     *  bridges the served session; session-builder.ts bridges the resident one (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>;

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 } : {}),

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

@@ -63,6 +63,8 @@ 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 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

package/dist/loader.js

@@ -90,6 +90,11 @@ export async function moduleInventory(subDir) {
     }
     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

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)

package/dist/paths.js

@@ -16,7 +16,7 @@
  * modules depend on it for something the engine has no say in.
  */
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { access, chmod, mkdir, 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";
 /**
@@ -159,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;
 }
@@ -267,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)

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

package/dist/scaffold/add-channel.js

@@ -44,28 +44,12 @@ const CHANNEL_SCAFFOLDS = {
     },
     slack: {
         env: [
-            { name: "SLACK_BOT_TOKEN", hint: "Slack app → rotating Bot User OAuth access token", required: true },
-            {
-                name: "SLACK_BOT_REFRESH_TOKEN",
-                hint: "Slack OAuth bot refresh token (required when token rotation is enabled)",
-                required: false,
-            },
-            {
-                name: "SLACK_BOT_TOKEN_EXPIRES_AT",
-                hint: "Slack rotating bot access-token expiry (epoch milliseconds)",
-                required: false,
-            },
-            { name: "SLACK_CLIENT_ID", hint: "Slack app OAuth client ID (for bot-token rotation)", required: false },
-            {
-                name: "SLACK_CLIENT_SECRET",
-                hint: "Slack app OAuth client secret (for bot-token rotation)",
-                required: false,
-            },
+            { name: "SLACK_BOT_TOKEN", hint: "Slack app → OAuth & Permissions → Bot User OAuth Token", required: true },
             { name: "SLACK_SIGNING_SECRET", hint: "Slack app → Basic Information → App Credentials", required: true },
         ],
         steps: [
             "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write, channels:history, groups:history, mpim:history",
-            "enable Agents (agent_view) and token rotation; subscribe app_home_opened, app_context_changed, app_mention, message.im, message.channels, message.groups, message.mpim; set Request URL to <public-url>/slack",
+            "enable Agents (agent_view) and leave token rotation OFF (it cannot be turned off again); subscribe app_home_opened, app_context_changed, app_mention, message.im, message.channels, message.groups, message.mpim; set Request URL to <public-url>/slack",
             "reinstall the app after changing scopes, then invite it to each channel it should read",
             "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
         ],
@@ -172,7 +156,7 @@ export function channelSetup(kind, ingress = "webhook", groupBehavior) {
             env: setup.env,
             steps: [
                 "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write (no channel/group/mpim history scopes)",
-                "enable Agents (agent_view) and token rotation; subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
+                "enable Agents (agent_view) and leave token rotation OFF (it cannot be turned off again); subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
                 "group behavior: mention-only — bare thread replies and unsummoned group context remain disabled",
                 ...setup.steps.slice(2),
             ],
@@ -340,55 +324,54 @@ export async function scaffoldChannel(dir, kind, options = {}) {
         throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
     }
     await mkdir(channelsDir, { recursive: true });
-    // `channel.ts` is THE adapter (→ channels/<kind>.ts); any other .ts in the bundle is a companion tool
-    // (→ tools/<name>, never clobbering an authored one).
+    let content = channelTemplate(kind, "channel.ts");
+    if ((kind === "feishu" || kind === "lark") && options.ingress === "websocket") {
+        const factory = `${kind}Channel`;
+        const wsFactory = `${kind}WebSocketChannel`;
+        let configured = content
+            .replace(`import { ${factory} }`, `import { ${wsFactory} }`)
+            .replace(`export default ${factory}({`, `export default ${wsFactory}({`);
+        if (configured === content)
+            throw new Error(`${kind} channel template has no factory anchors`);
+        const prefix = kind === "feishu" ? "FEISHU" : "LARK";
+        const exportAt = configured.indexOf("export default");
+        const importEnd = configured.indexOf("\n\n");
+        if (exportAt < 0 || importEnd < 0)
+            throw new Error(`${kind} channel template header anchors are missing`);
+        const brand = kind === "feishu" ? "Feishu" : "Lark";
+        configured =
+            `${configured.slice(0, importEnd)}\n\n` +
+                `// ${brand} WebSocket long connection: the process connects OUT to the platform, so no public URL,\n` +
+                `// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long\n` +
+                `// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process\n` +
+                `// running in production: scale-to-zero/App Sleeping would disconnect ingress.\n` +
+                configured.slice(exportAt);
+        configured = configured
+            .split("\n")
+            .filter((line) => !line.includes(`verificationToken: process.env.${prefix}_VERIFICATION_TOKEN`) &&
+            !line.includes(`encryptKey: process.env.${prefix}_ENCRYPT_KEY`))
+            .join("\n");
+        content = configured;
+    }
+    await writeFile(file, content, { flag: "wx" });
+    return file;
+}
+/**
+ * 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 async function scaffoldCompanionTools(dir, kind) {
+    const written = [];
     for (const name of channelBundleFiles(kind)) {
-        let content = channelTemplate(kind, name);
-        if (name === "channel.ts") {
-            if ((kind === "feishu" || kind === "lark") && options.ingress === "websocket") {
-                const factory = `${kind}Channel`;
-                const wsFactory = `${kind}WebSocketChannel`;
-                let configured = content
-                    .replace(`import { ${factory} }`, `import { ${wsFactory} }`)
-                    .replace(`export default ${factory}({`, `export default ${wsFactory}({`);
-                if (configured === content)
-                    throw new Error(`${kind} channel template has no factory anchors`);
-                const prefix = kind === "feishu" ? "FEISHU" : "LARK";
-                const exportAt = configured.indexOf("export default");
-                const importEnd = configured.indexOf("\n\n");
-                if (exportAt < 0 || importEnd < 0)
-                    throw new Error(`${kind} channel template header anchors are missing`);
-                const brand = kind === "feishu" ? "Feishu" : "Lark";
-                configured =
-                    `${configured.slice(0, importEnd)}\n\n` +
-                        `// ${brand} WebSocket long connection: the process connects OUT to the platform, so no public URL,\n` +
-                        `// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long\n` +
-                        `// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process\n` +
-                        `// running in production: scale-to-zero/App Sleeping would disconnect ingress.\n` +
-                        configured.slice(exportAt);
-                configured = configured
-                    .split("\n")
-                    .filter((line) => !line.includes(`verificationToken: process.env.${prefix}_VERIFICATION_TOKEN`) &&
-                    !line.includes(`encryptKey: process.env.${prefix}_ENCRYPT_KEY`))
-                    .join("\n");
-                content = configured;
-            }
-            if (kind === "slack" && options.groupBehavior === "mentions") {
-                const configured = content.replace('groupBehavior: "context"', 'groupBehavior: "mentions"');
-                if (configured === content)
-                    throw new Error("slack channel template has no groupBehavior anchor");
-                content = configured;
-            }
-            await writeFile(file, content, { flag: "wx" });
+        if (name === "channel.ts")
             continue;
-        }
-        const toolFile = join(dir, "tools", name);
-        if (!(await exists(toolFile))) {
-            await mkdir(join(dir, "tools"), { recursive: true });
-            await writeFile(toolFile, content, { flag: "wx" });
-        }
+        const file = join(dir, "tools", name);
+        await mkdir(dirname(file), { recursive: true });
+        await writeFile(file, channelTemplate(kind, name));
+        written.push(file);
     }
-    return file;
+    return written;
 }
 /**
  * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares

package/dist/schedule/wake-alarm.d.ts

@@ -1,16 +1,5 @@
+import { type WakeAlarm } from "../channels/agentcore-protocol.ts";
 import { type Wakeup } from "./wakeups.ts";
-/** The forwarder's reserved wake-alarm path — never forwarded to channel routes. */
-export declare const WAKE_ALARM_PATH = "/__fastagent/wake-alarm";
-/** One desired alarm: mirror of a pending wake-up (id names the EventBridge schedule; at = fireAt). */
-export interface WakeAlarm {
-    id: string;
-    at: string;
-}
-/** The wire shape the sink POSTs to {@link WAKE_ALARM_PATH} (the forwarder validates `secret`). */
-export interface WakeAlarmRequest {
-    secret: string;
-    alarms: WakeAlarm[];
-}
 /**
  * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on
  * every turn, the file should not churn). Durable under <stateRoot>/schedule/ so a freshly booted

package/dist/schedule/wake-alarm.js

@@ -23,12 +23,11 @@
  * wasted wake-up of the box, traded for never needing list/delete choreography.
  */
 import { readFileSync } from "node:fs";
+import { RESERVED_PATHS } from "../channels/agentcore-protocol.js";
 import { beginWork } from "../channels/busy.js";
 import { log } from "../log.js";
 import { scheduleFile, writeScheduleFile } from "./state.js";
 import { listWakeups } from "./wakeups.js";
-/** The forwarder's reserved wake-alarm path — never forwarded to channel routes. */
-export const WAKE_ALARM_PATH = "/__fastagent/wake-alarm";
 const URL_FILE = "wake-alarm-url";
 /**
  * Persist the forwarder URL the adapter saw in an envelope (write-if-changed — envelopes arrive on
@@ -106,7 +105,7 @@ export function createWakeAlarmSink(options) {
         }
         const body = { secret, alarms };
         try {
-            const res = await fetchImpl(`${url.replace(/\/$/, "")}${WAKE_ALARM_PATH}`, {
+            const res = await fetchImpl(`${url.replace(/\/$/, "")}${RESERVED_PATHS.wakeAlarm}`, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify(body),