@fastagent-sh/fastagent 0.14.0 → 0.15.0

package/dist/scaffold/add-channel.js

@@ -43,11 +43,39 @@ const CHANNEL_SCAFFOLDS = {
             "the agent can send messages or files back by calling the scaffolded {tools}/telegram-send.ts tool",
         ],
     },
+    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_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",
+            "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",
+        ],
+    },
     // 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.
+    // This table is the webhook setup; continuous mode below selects only App ID/Secret. No `generate`
+    // in either: values come FROM the platform. `add feishu` scan-creates the app; Lark lacks that
+    // control-plane capability, so `add lark` guides console credential collection.
     feishu: {
         env: [
             {
@@ -72,8 +100,8 @@ const CHANNEL_SCAFFOLDS = {
             },
         ],
         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)",
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (the CLI adds it to the app draft when supported); it delivers all group messages so bare managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "PUBLISH the app version in the developer console after permission approval — 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",
@@ -96,7 +124,7 @@ const CHANNEL_SCAFFOLDS = {
         ],
         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",
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (add it manually if Lark's config API fallback was used); it delivers all group messages so bare managed-thread replies can invoke and other unsummoned discussion can buffer",
             "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",
         ],
@@ -104,17 +132,61 @@ const CHANNEL_SCAFFOLDS = {
 };
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
-/** The env vars + next-step lines a scaffolded channel needs (for the CLI to print). */
-export function channelSetup(kind) {
-    const { env, steps } = CHANNEL_SCAFFOLDS[kind];
-    return { env, steps };
+const WEBSOCKET_SETUPS = {
+    feishu: {
+        env: CHANNEL_SCAFFOLDS.feishu.env.filter((entry) => ["FEISHU_APP_ID", "FEISHU_APP_SECRET"].includes(entry.name)),
+        steps: [
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (the CLI adds it to the app draft when supported); it delivers all group messages so bare managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "PUBLISH the app version in the developer console after permission approval — long-connection event subscriptions become active with the published version",
+            "edit {channel} — routing policy (the scaffold is already set to WebSocket ingress)",
+            "run `fastagent dev` without --tunnel; deployments must keep one process running (no scale-to-zero)",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
+        ],
+    },
+    lark: {
+        env: CHANNEL_SCAFFOLDS.lark.env.filter((entry) => ["LARK_APP_ID", "LARK_APP_SECRET"].includes(entry.name)),
+        steps: [
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (add it manually if Lark's config API fallback was used); it delivers all group messages so bare managed-thread replies can invoke and other unsummoned discussion can buffer",
+            "in Events & Callbacks choose long connection, subscribe im.message.receive_v1, then create + publish a version",
+            "edit {channel} — routing policy (the scaffold is already set to WebSocket ingress)",
+            "run `fastagent dev` without --tunnel; deployments must keep one process running (no scale-to-zero)",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
+        ],
+    },
+};
+/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
+export function channelSetup(kind, ingress = "webhook", groupBehavior) {
+    const behavior = groupBehavior ?? "context";
+    const setup = ingress === "websocket" && (kind === "feishu" || kind === "lark")
+        ? WEBSOCKET_SETUPS[kind]
+        : CHANNEL_SCAFFOLDS[kind];
+    if ((kind === "feishu" || kind === "lark") && behavior === "mentions") {
+        return {
+            env: setup.env,
+            steps: setup.steps.map((step) => step.includes("im:message.group_msg")
+                ? "group behavior: mention-only — do not grant im:message.group_msg; bare managed-thread replies and group context buffering remain disabled"
+                : step),
+        };
+    }
+    if (kind === "slack" && behavior === "mentions") {
+        return {
+            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",
+                "group behavior: mention-only — bare managed-thread replies and unsummoned group context remain disabled",
+                ...setup.steps.slice(2),
+            ],
+        };
+    }
+    return { env: setup.env, steps: setup.steps };
 }
 /**
  * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who
  * copies it to `.env` finds the vars already there. No-op when there is no `.env.example` or the block
  * is already present. Placeholders only — no real secret lands in the committable template.
  */
-export async function appendChannelEnv(dir, kind) {
+export async function appendChannelEnv(dir, kind, ingress = "webhook") {
     const file = join(dir, ".env.example");
     let current;
     try {
@@ -131,7 +203,9 @@ export async function appendChannelEnv(dir, kind) {
     // Hint on its OWN line above the placeholder (like the base env.example template) — never inline
     // after `=`: loadEnvFile does not strip trailing comments, so an uncommented `KEY=   # hint` (or a
     // value pasted before the `#`) would carry the hint text into the parsed value.
-    const block = `\n${marker}\n${CHANNEL_SCAFFOLDS[kind].env.map((e) => `# ${e.hint}\n# ${e.name}=`).join("\n")}\n`;
+    const block = `\n${marker}\n${channelSetup(kind, ingress)
+        .env.map((e) => `# ${e.hint}\n# ${e.name}=`)
+        .join("\n")}\n`;
     await appendFile(file, block);
     return true;
 }
@@ -153,7 +227,7 @@ function mentionsEnvName(content, name) {
  * (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, overwrite = []) {
+export async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
     const file = join(dir, ".env");
     let current = "";
     try {
@@ -163,14 +237,15 @@ export async function appendChannelDotEnv(dir, kind, generated, overwrite = [])
         if (e.code !== "ENOENT")
             throw e;
     }
-    const alreadySet = CHANNEL_SCAFFOLDS[kind].env
+    const env = channelSetup(kind, ingress).env;
+    const alreadySet = env
         .filter((e) => !overwrite.includes(e.name) && hasActiveEnvValue(current, e.name))
         .map((e) => e.name);
     const lines = [];
     const written = [];
     const contentLines = current.split("\n");
     let replacedInPlace = false;
-    for (const e of CHANNEL_SCAFFOLDS[kind].env) {
+    for (const e of env) {
         if (alreadySet.includes(e.name))
             continue;
         const value = generated[e.name];
@@ -230,7 +305,7 @@ export async function channelExists(dir, kind) {
  * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
  * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
  */
-export async function scaffoldChannel(dir, kind) {
+export async function scaffoldChannel(dir, kind, options = {}) {
     const channelsDir = join(dir, "channels");
     // Don't write through a channels/ symlink that escapes the workspace; an in-workspace one is fine.
     await assertInsideWorkspace(dir, "channels");
@@ -242,8 +317,42 @@ export async function scaffoldChannel(dir, kind) {
     // `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).
     for (const name of channelBundleFiles(kind)) {
-        const content = channelTemplate(kind, name);
+        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" });
             continue;
         }

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

@@ -2,15 +2,16 @@
 // Your agent's identity lives in persona.md; its capabilities in skills/ + tools/ — never here.
 // An AGENTS.md at the workspace root (yours or the host repo's) is read as project context.
 // Model precedence: `--model` flag > FASTAGENT_MODEL env > this default.
-// No model is preset: `fastagent dev` prompts you to pick one from the providers you're logged into
-// (run `fastagent login` first) and writes your choice below. Or set it by hand to a "provider/modelId"
-// you have access to (`fastagent models` lists them).
+// No model is preset: `fastagent dev` shows the full model catalog (models you already have
+// credentials for come first; picking one that needs auth logs you in inline) and writes your choice
+// below. Or set it by hand to a "provider/modelId" (`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.
+  // sessionControl: true, // serve /control/* for remote observation + steering (fastagent attach / Web panel)
   // deploy: what the agent needs on the box (so `fastagent deploy` doesn't need a hand-written Dockerfile
   // or hand-set host variables). Uncomment as needed:
   // deploy: {

package/dist/schedule/wakeups.d.ts

@@ -26,9 +26,6 @@ export declare const MAX_PENDING_WAKEUPS = 20;
  *  wake into an active conversation fires in the first gap between the user's turns; this generous
  *  ceiling (~1h) only gives up on a pathologically stuck session (then logs, operator-visible). */
 export declare const MAX_WAKE_ATTEMPTS = 120;
-/** The minimum gap between two consecutive fires of a RECURRING wake — stricter than the one-shot floor:
- *  a recurring runs forever, so a tight cron is a permanent token burner, not a one-time mistake. */
-export declare const MIN_RECURRING_GAP_MS: number;
 /** The current pending wake-ups (`fastagent schedule list` uses this). */
 export declare function listWakeups(stateRoot: string): Wakeup[];
 export type AddWakeupResult = {

package/dist/schedule/wakeups.js

@@ -26,7 +26,7 @@ export const MAX_PENDING_WAKEUPS = 20;
 export const MAX_WAKE_ATTEMPTS = 120;
 /** The minimum gap between two consecutive fires of a RECURRING wake — stricter than the one-shot floor:
  *  a recurring runs forever, so a tight cron is a permanent token burner, not a one-time mistake. */
-export const MIN_RECURRING_GAP_MS = 10 * 60_000; // 10 minutes
+const MIN_RECURRING_GAP_MS = 10 * 60_000; // 10 minutes
 /** A stored entry is a real Wakeup: the fields are present and `fireAt` is a parseable date. A malformed
  *  one (bad/missing fireAt) would compare NaN <= now = false forever — never due, never cleared, but still
  *  eating the pending quota. So validate at this IO boundary and drop it (warn), like a corrupt file. */

package/dist/session-remote.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The remote `SessionControl` — the client half of the Phase 3 transport (design §13). Engine- and
+ * server-neutral: speaks only the wire protocol `controlRoutes` serves (HTTP JSON + SSE with the
+ * {sessionId, epoch, seq, event} envelope) and re-exposes the SAME `SessionControl` interface, so
+ * local and remote consumers are isomorphic — client code does not change when the agent moves out
+ * of process.
+ *
+ * Envelope consumption is internal: a seq gap (loss in transit on this connection) — and any
+ * mid-stream transport failure, a server restart included (its connections drop) — THROWS from
+ * the events iterator, so the consumer's failure handling and budget own it; only the consumer's
+ * own detach reads as a clean end. Recovery is the standard reconnect steps (`entries({ since })`
+ * → `state()` → resubscribe), exactly as after any disconnect. The envelope's `epoch` is
+ * informational for consumers that correlate ACROSS connections — within one connection it cannot
+ * change, so this client does not compare it. Nothing here retries silently: a broken stream is
+ * visible as a thrown iteration error, a failed request as a rejected promise.
+ */
+import type { Agent } from "./agent.ts";
+import type { SessionControl } from "./session.ts";
+/** A control request the server answered with a non-2xx status. Carries the STRUCTURED status so a
+ *  consumer distinguishing auth failure (401 — stale token, unrecoverable) from transient transport
+ *  trouble branches on `status`, never on message prose. */
+export declare class ControlRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** Connection parameters shared by BOTH remote planes (`connectSessionControl` and
+ *  `connectAgent`) — plane-neutral on purpose: one endpoint, one token, two contracts. */
+export interface RemoteEndpointOptions {
+    /** Base URL of the serving process (e.g. `http://127.0.0.1:8787`); `/control/*` is appended. */
+    url: string;
+    /** The shared bearer secret (`<stateRoot>/control.json` on the serving machine). */
+    token: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Connect and return a remote `SessionControl`. Async because `capabilities()` is synchronous in
+ * the contract: the static declaration is fetched ONCE here and served from memory — which also
+ * makes a wrong URL/token fail at connect time, not on first use.
+ */
+export declare function connectSessionControl(options: RemoteEndpointOptions): Promise<SessionControl>;
+/**
+ * The remote DATA plane: an `Agent` whose `invoke` drives `POST /control/invoke` on a serving
+ * process — paired with {@link connectSessionControl}, a client holds a full remote fastagent
+ * instance through the same two contracts local code uses. A REAL Agent, failure discipline
+ * included: SPEC MUST 2 forbids iteration throws, so every failure — transport (401/refused/
+ * dropped mid-stream), protocol, and the images precheck — becomes a terminal `failed` event
+ * (`retryable` from the HTTP status where one exists; network trouble is retryable). Breaking out
+ * of iteration disconnects the request, which cancels the run (SPEC cancellation semantics travel
+ * the wire). The invoke wire is text-only for now: a prompt with images fails visibly instead of
+ * silently dropping them (steer/follow_up on the control plane carry full Prompts).
+ */
+export declare function connectAgent(options: RemoteEndpointOptions): Agent;