@fastagent-sh/fastagent 0.29.0 → 0.30.1

package/dist/scaffold/add-channel.js

@@ -7,46 +7,23 @@ import { dirname, join } from "node:path";
 import { detectRuntime } from "../runtime.js";
 import { assertInsideAgentDir, exists } from "../paths.js";
 import { channelBundleFiles, channelTemplate } from "./templates.js";
-import { writeValues } from "../value-file.js";
 import { envExamplePath } from "../value-file.js";
-import { FEISHU_AGENT_SCOPES } from "../channels/feishu/setup-mode.js";
-import { slackBotScopes } from "../channels/slack/manifest.js";
-const AGENT_SCOPE_LIST = FEISHU_AGENT_SCOPES.map((entry) => entry.request).join(", ");
-const FEISHU_PERMISSION_STEP = `before publishing: the app needs ${AGENT_SCOPE_LIST} — \`add feishu\` requests them with the app and names any ` +
-    "your tenant withheld (approve those, then publish)";
-/** The setting both clouds read, said the same way in `.env.example` and in `add`'s next steps. */
-const ingressEnv = (prefix) => ({
-    name: `${prefix}_INGRESS`,
-    hint: "webhook | websocket — unset, `dev` connects by websocket, and `start` and every deployment receive by webhook",
-    required: false,
-});
-const LARK_PERMISSION_STEP = `before publishing: add ${AGENT_SCOPE_LIST} — \`add lark\` checks them and opens the permission page for any that ` +
-    "are missing";
 const CHANNEL_SCAFFOLDS = {
+    // A channel's app is set up by `channels setup`, which asks for these values; `add` only names them.
     telegram: {
         env: [
             { 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",
+            { name: "TELEGRAM_SECRET_TOKEN", hint: "webhook only: verifies inbound updates", required: true },
         ],
+        steps: ["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 → OAuth & Permissions → Bot User OAuth Token", required: true },
-            { name: "SLACK_SIGNING_SECRET", hint: "Slack app → Basic Information → App Credentials", required: true },
+            { name: "SLACK_BOT_TOKEN", hint: "Install App → Bot User OAuth Token", required: true },
+            { name: "SLACK_APP_TOKEN", hint: "connection only: Basic Information → App-Level Tokens", required: true },
+            { name: "SLACK_SIGNING_SECRET", hint: "webhook only: Basic Information → Signing Secret", required: true },
         ],
         steps: [
-            `Slack Bot Token Scopes: ${slackBotScopes().join(", ")}`,
-            "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",
             "the agent reads the threads of the channel it is asked in via the scaffolded {tools}/slack-threads.ts tool",
         ],
@@ -57,17 +34,17 @@ const CHANNEL_SCAFFOLDS = {
         env: [
             {
                 name: "FEISHU_APP_ID",
-                hint: "created + written automatically by `add feishu` (console → Credentials & Basic Info)",
+                hint: "`channels setup feishu` creates the app (console → Credentials & Basic Info)",
                 required: true,
             },
             {
                 name: "FEISHU_APP_SECRET",
-                hint: "created + written automatically by `add feishu` (console → Credentials & Basic Info)",
+                hint: "`channels setup feishu` keeps it (console → Credentials & Basic Info)",
                 required: true,
             },
             {
                 name: "FEISHU_VERIFICATION_TOKEN",
-                hint: "webhook only (`start`, every deployment) — captured by `deploy --run` (console → Events & Callbacks)",
+                hint: "webhook only: `channels setup feishu` captures it (console → Events & Callbacks)",
                 required: true,
             },
             {
@@ -75,13 +52,8 @@ const CHANNEL_SCAFFOLDS = {
                 hint: "webhook only; optional but recommended — set one in the console and copy it here",
                 required: false,
             },
-            ingressEnv("FEISHU"),
         ],
         steps: [
-            FEISHU_PERMISSION_STEP,
-            "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)",
-            "for webhook ingress, run `{serve} --tunnel` locally or `deploy --run` to register the selected app's event Request URL",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
             "the agent reads the threads of the group it is asked in via the scaffolded {tools}/feishu-threads.ts tool",
         ],
@@ -92,7 +64,7 @@ const CHANNEL_SCAFFOLDS = {
             { name: "LARK_APP_SECRET", hint: "developer console → Credentials & Basic Info", required: true },
             {
                 name: "LARK_VERIFICATION_TOKEN",
-                hint: "webhook only (`start`, every deployment) — console → Events & Callbacks; authenticates inbound events",
+                hint: "webhook only — console → Events & Callbacks; authenticates inbound events",
                 required: true,
             },
             {
@@ -100,12 +72,8 @@ const CHANNEL_SCAFFOLDS = {
                 hint: "webhook only; optional but recommended — set one in the console and copy it here",
                 required: false,
             },
-            ingressEnv("LARK"),
         ],
         steps: [
-            "finish the console setup: enable Bot and add the required permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
-            LARK_PERMISSION_STEP,
-            "for webhook ingress, run `{serve} --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 agent reads the threads of the group it is asked in via the scaffolded {tools}/lark-threads.ts tool",
         ],
@@ -113,35 +81,9 @@ const CHANNEL_SCAFFOLDS = {
 };
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
-/** Local setup never changes the production app or ingress. */
-const deploymentStep = (kind, pinned) => pinned
-    ? `run \`{serve}\` (no tunnel needed: it connects by WebSocket); ${kind.toUpperCase()}_INGRESS=websocket is ` +
-        "set for this environment; production has its own app and ingress setting"
-    : "run `{serve}` (no tunnel needed: it connects by WebSocket); " +
-        "`deploy --run` creates a separate production app for webhook";
-const websocketSetup = (kind, pinned) => {
-    const prefix = kind.toUpperCase();
-    return {
-        env: CHANNEL_SCAFFOLDS[kind].env.filter((entry) => [`${prefix}_APP_ID`, `${prefix}_APP_SECRET`, `${prefix}_INGRESS`].includes(entry.name)),
-        steps: [
-            kind === "feishu" ? FEISHU_PERMISSION_STEP : LARK_PERMISSION_STEP,
-            kind === "feishu"
-                ? "PUBLISH the app version in the developer console after permission approval — long-connection event subscriptions become active with the published version"
-                : "in Events & Callbacks choose long connection, subscribe im.message.receive_v1, then create + publish a version",
-            "edit {channel} — routing policy",
-            deploymentStep(kind, pinned),
-            `the agent can push messages from scheduled turns via the scaffolded {tools}/${kind}-send.ts tool`,
-            `the agent reads the threads of the group it is asked in via the scaffolded {tools}/${kind}-threads.ts tool`,
-        ],
-    };
-};
-/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
-export function channelSetup(kind, ingress = "webhook", 
-/** Whether `<PREFIX>_INGRESS` is explicitly set in this environment. */
-pinned = false) {
-    if (ingress !== "websocket" || (kind !== "feishu" && kind !== "lark"))
-        return CHANNEL_SCAFFOLDS[kind];
-    return websocketSetup(kind, pinned);
+/** The env vars and next-step lines a scaffolded channel has. */
+export function channelSetup(kind) {
+    return CHANNEL_SCAFFOLDS[kind];
 }
 /**
  * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who copies it to
@@ -167,18 +109,6 @@ export async function appendChannelEnv(dir, kind) {
     await appendFile(file, block);
     return true;
 }
-/**
- * Append generated channel secrets to the selected environment's value file, and a placeholder for each the channel
- * reads that nothing generated. Existing non-empty values are kept.
- */
-export function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
-    const entries = channelSetup(kind, ingress).env.map(({ name, hint }) => ({
-        name,
-        hint,
-        ...(generated[name] === undefined ? {} : { value: generated[name] }),
-    }));
-    return writeValues(dir, `${kind} channel`, entries, overwrite);
-}
 /** The path `add <kind>` scaffolds to. */
 function channelPath(dir, kind) {
     return join(dir, "src", "channels", `${kind}.ts`);

package/dist/scaffold/templates/env.example

@@ -9,11 +9,10 @@
 # ANTHROPIC_API_KEY=
 
 # --- Model selection (overrides fastagent.config) ---
-# Precedence: --model flag > FASTAGENT_MODEL > config — one chain, evaluated in whichever environment
-# is running. THIS FILE also declares the environment `fastagent deploy` resolves in, so a value here rides the
-# release manifest into the deployment and a deployment can run a model the committed config does not
-# name. That recorded value outranks the deployed box's own .env, so switching models there means
-# editing this line and redeploying.
+# Precedence: --model flag > FASTAGENT_MODEL > config, evaluated in whichever environment is running. This file is
+# `dev`'s alone: `fastagent start` and `fastagent deploy` read .secrets/production/.env and never this one, and a
+# deployment's values live on its target (`fastagent secrets list <host>`). To fix the model for every instance, set
+# `defaults.model` in fastagent.config.ts.
 # FASTAGENT_MODEL=openai/gpt-5.5
 
 # --- Serving (fastagent start) ---

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

@@ -1,24 +1,30 @@
-// fastagent.config.ts — the agent's configuration: its default model and how it is served. Its prompt lives in
-// SYSTEM.md, its capabilities in skills/ and src/ (tools, extensions, channels, schedules) — never here.
+// fastagent.config.ts — the agent's configuration: what it is, and what each instance of it starts with. Its prompt
+// lives in SYSTEM.md, its capabilities in skills/ and src/ (tools, extensions, channels, schedules) — never here.
 //
-// Model precedence: `--model` flag > FASTAGENT_MODEL env > this default. No model is preset: `fastagent dev` shows
-// the model catalog (models you already have credentials for come first; picking one that needs auth logs you in
-// inline) and runs with your choice; set it below to keep it. `fastagent models` lists every "provider/modelId".
-// A self-hosted model (vLLM, Ollama, …) or your own gateway is a provider in code: `providers: [...]`, built with
-// pi-ai's `createProvider`.
+// Model precedence: `--model` flag > FASTAGENT_MODEL env > an instance's `fastagent.json` > this default. No model is
+// preset: `fastagent dev` shows the model catalog (models you already have credentials for come first; picking one
+// that needs auth logs you in inline) and runs with your choice; set it below to keep it. `fastagent models` lists
+// every "provider/modelId". A self-hosted model (vLLM, Ollama, …) or your own gateway is a provider in code:
+// `providers: [...]`, built with pi-ai's `createProvider`.
 //
 // Every key is optional; the commented lines carry an example. `satisfies` is what makes your editor complete these
 // keys and turns a typo into an error you see while writing. The import is TYPE-only: nothing is loaded at runtime,
-// so the agent opens before `npm install` has run.
+// so the agent opens before `npm install` has run. To let each instance choose values of its own, declare `settings`
+// with `obj({ ... })` from @earendil-works/pi-schema and switch to `defineAgent`.
 import type { AgentConfig } from "@fastagent-sh/fastagent";
 
 export default {
-  // model: "openai/gpt-5.5",
-  // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max)
-  http: {
-    port: 8787, // the port a serve listens on, for its channels' webhooks and its health check
-    // api: false, // serve no Agent API under /v1, whatever key the environment holds; deploy gives none a key
+  // Constants (what this agent is; an instance cannot change them): name, description, providers, extensions.
+
+  // Defaults: what an instance starts with, which its own `fastagent.json` may override.
+  defaults: {
+    // model: "openai/gpt-5.5",
+    // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max)
+    http: {
+      port: 8787, // the port a serve listens on, for its channels' webhooks and its health check
+      // api: false, // serve no Agent API under /v1, whatever key the environment holds; deploy gives none a key
+    },
+    // deploy: { agentcore: { idleTimeoutSeconds: 180 } }, // `deploy agentcore` only: idle microVM tail, 60–1209600s
   },
   // The commands the agent needs (CLIs, runtimes, apt packages) live in context.json: `fastagent env add gh`.
-  // deploy: { agentcore: { idleTimeoutSeconds: 180 } }, // `deploy agentcore` only: idle microVM tail, 60–1209600s
 } satisfies AgentConfig;

package/dist/scaffold/templates/gitignore

@@ -5,17 +5,20 @@
 # DIRECTORY, so a symlinked one (pnpm, a shared store) would show up as untracked.
 node_modules
 
-# generated from src/ every time the agent opens
+# generated: `fastagent build`'s package, and FastAgent's own files, a local instance's state, working directory and
+# clones of the agent's content included (`.fastagent/dev/`, `.fastagent/start/`)
+/dist
 .fastagent
-# machine state: the agent's storage, channel state, schedule state
+# the same, where an instance is placed in the agent's directory (`--state`, `--root`), and on a deployed host, where
+# `content/` is a link to the volume (no trailing slash, since a link is not a directory)
 .state
-# where fastagent clones the agent's content (each clone is its repository's, not this one's). No trailing
-# slash: on a deployed host it is a link itself.
 /content
-# the directories of this machine the agent is bound to: this machine's, never the agent's
-/context.local.json
 .cache
 
+# the development instance's configuration: its app is one person's, so it is personal. What a team shares goes in
+# `defaults` of fastagent.config.ts, or in a deployment's configuration (`deploy --config`).
+fastagent.json
+
 # fastagent reads the agent's env from .secrets/.env (which un-ignores its own .env.example). A bare
 # .env at THIS level is the file habit puts here — `dev` says so when it finds one; this keeps it
 # uncommittable meanwhile.

package/dist/scaffold/templates.d.ts

@@ -5,12 +5,16 @@ export declare const channelTemplate: (kind: string, name: string) => string;
 /** The .ts files in a channel's bundle: `channel.ts` is the channel template; the rest are companion tools. */
 export declare const channelBundleFiles: (kind: string) => string[];
 /**
- * package.json for the complete agent: fastagent at this build's version, and the packages an agent's code is written
- * against (its tools and extensions are pi-durable code, its providers pi-ai's) at the versions this build runs.
+ * package.json for the complete agent: fastagent at this build's version, the packages an agent's code is written
+ * against (its tools and extensions are pi-durable code, its providers pi-ai's, its tool schemas pi-schema's) at the
+ * versions this build runs, and the TypeScript `fastagent build` compiles it with. Its scripts are the framework's
+ * three entries, so `npm run dev` and `npm start` work as in any web project; `start` builds first, since it opens the
+ * built `dist/` and refuses one the project has moved past.
  */
 export declare function packageJson(name: string, build: {
     version: string;
     harness: Record<string, string>;
+    typescript: string;
 }): string;
 /** Sanitize a directory basename into a valid npm package name (lowercase, safe chars). */
 export declare function toPackageName(dir: string): string;

package/dist/scaffold/templates.js

@@ -12,15 +12,20 @@ export const channelTemplate = (kind, name) => readFileSync(new URL(name, channe
 /** The .ts files in a channel's bundle: `channel.ts` is the channel template; the rest are companion tools. */
 export const channelBundleFiles = (kind) => readdirSync(channelScaffoldDir(kind)).filter((f) => f.endsWith(".ts"));
 /**
- * package.json for the complete agent: fastagent at this build's version, and the packages an agent's code is written
- * against (its tools and extensions are pi-durable code, its providers pi-ai's) at the versions this build runs.
+ * package.json for the complete agent: fastagent at this build's version, the packages an agent's code is written
+ * against (its tools and extensions are pi-durable code, its providers pi-ai's, its tool schemas pi-schema's) at the
+ * versions this build runs, and the TypeScript `fastagent build` compiles it with. Its scripts are the framework's
+ * three entries, so `npm run dev` and `npm start` work as in any web project; `start` builds first, since it opens the
+ * built `dist/` and refuses one the project has moved past.
  */
 export function packageJson(name, build) {
     return `${JSON.stringify({
         name,
         private: true,
         type: "module",
+        scripts: { dev: "fastagent dev", build: "fastagent build", start: "fastagent build && fastagent start" },
         dependencies: { "@fastagent-sh/fastagent": `^${build.version}`, ...build.harness },
+        devDependencies: { typescript: build.typescript },
     }, null, 2)}\n`;
 }
 /** Sanitize a directory basename into a valid npm package name (lowercase, safe chars). */

package/dist/scaffold/vendor-skill.js

@@ -8,11 +8,13 @@ import { randomUUID } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { readSkills } from "../harnesses/pi-durable/text.js";
+import { programText } from "../harnesses/pi-durable/text-sources.js";
 import { assertInsideAgentDir } from "../paths.js";
+import { stripTrailingSlashes } from "../strip-edges.js";
 /** Derive the destination skill name from a source ref: the last path segment, sans `#ref`. */
 function skillNameFromSource(source) {
     const noRef = source.split("#")[0] ?? source;
-    return basename(noRef.replace(/\/+$/, ""));
+    return basename(stripTrailingSlashes(noRef));
 }
 /**
  * The skills/ path must be safe to write through: never follow a symlink that escapes the agent dir (mkdir would), and
@@ -135,7 +137,7 @@ export async function vendorSkill(agentDir, source, options = {}) {
     // would prefix-pollute a sibling `<name>-x` and break on Windows path separators). A skill it refuses is said by
     // that loader, and is missing here.
     const rel = join("skills", name);
-    const skill = readSkills(agentDir).find((sk) => relative(agentDir, dirname(sk.filePath)) === rel);
+    const skill = readSkills(programText(agentDir).skills).find((sk) => relative(agentDir, dirname(sk.filePath)) === rel);
     return {
         name: skill?.name ?? name,
         description: skill?.description,

package/dist/service.d.ts

@@ -1,8 +1,10 @@
 import type { Agent } from "./agent-api.ts";
 import type { ChannelHandler, Routes } from "./channel.ts";
 import { type AnyChannelModule, type LoadedLongConnectionChannel } from "./channels/discover.ts";
+import { type WebhookRegistration } from "./channels/webhooks.ts";
 import { type Scheduler } from "./schedule/scheduler.ts";
 import type { Schedule } from "./schedule/schedule.ts";
+export type { WebhookRegistration } from "./channels/webhooks.ts";
 /** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
 export declare const DEFAULT_HTTP_PORT = 8787;
 /** What a serve answers: its channels' routes, and `GET /health` unless a channel serves it. */
@@ -14,8 +16,11 @@ interface ServingSurface {
     /** Flip health between 200 and 503. */
     setReady(value: boolean): void;
 }
-/** Mount the channels and the health check. */
-export declare function routesFor(agent: Agent, stateRoot: string, channels: ReadonlyMap<string, AnyChannelModule>): ServingSurface;
+/**
+ * Mount the channels and the health check: JSON, `{ status, webhooks }`, each webhook channel only by name and outcome
+ * (SPEC.md §9.1), since it is public; a step and its reasons are in the log.
+ */
+export declare function routesFor(agent: Agent, stateRoot: string, channels: ReadonlyMap<string, AnyChannelModule>, webhooks?: () => readonly WebhookRegistration[]): ServingSurface;
 /** Start the clock: the definition's schedules, and the wake-ups the agent sets for itself, on every serve. */
 export declare function startSchedules(agent: Agent, stateRoot: string, schedules: readonly Schedule[], options?: {
     localClock?: boolean;
@@ -24,8 +29,19 @@ export declare function startSchedules(agent: Agent, stateRoot: string, schedule
 export interface Service {
     /** For an app's own server to route to. */
     fetch(request: Request): Promise<Response>;
-    /** Or a server of its own, on this runtime's server: the one way to start one. Answers the port it bound. */
+    /**
+     * Or a server of its own, on this runtime's server: the one way to start one. Answers the port it bound. Once the
+     * serve is ready it registers the webhook channels at `http.publicUrl`, in the background (`webhooks`).
+     */
     listen(port: number, host?: string): Promise<number>;
+    /**
+     * Point each webhook channel's platform at `<baseUrl ?? http.publicUrl>/<its path>`, for an app serving `fetch` on its
+     * own server, once that server answers and the serve is ready: set on every call. Answers every webhook channel's
+     * outcome; rejects only for a `baseUrl` that is not an absolute http(s) URL.
+     */
+    registerWebhooks(baseUrl?: string): Promise<WebhookRegistration[]>;
+    /** Every webhook channel's outcome, `pending` until its registration ends; empty only with no webhook channel. */
+    readonly webhooks: readonly WebhookRegistration[];
     /** Settles when every long connection is up: immediately when there are none. */
     ready: Promise<void>;
     /**
@@ -52,11 +68,21 @@ export interface ServedAgent extends Service {
     /** Whether the Agent API is served, under `/v1`: only with a key (SPEC.md §9.1). */
     api: boolean;
 }
+/** A serve's webhook channels: their outcomes, and the registration that sets them, one at a time. */
+export interface WebhookRegistry {
+    /** The outcomes, as one array kept current. */
+    list(): readonly WebhookRegistration[];
+    register(baseUrl?: string): Promise<WebhookRegistration[]>;
+    /** Stop hearing the platforms reach it. */
+    dispose(): void;
+}
+/** The webhook channels of an opened agent, to be pointed at `http.publicUrl` or at a URL the host names. */
+export declare function webhooksOf(opened: ServableAgent): WebhookRegistry;
 /**
  * A Service over `handler`: answered in process, or served on a server of its own. `endStreams` ends what would hold
  * the server's close open (a Caller watching events), and `shutdown` stops the rest once the server has.
  */
-export declare function serviceOver(handler: ChannelHandler, ready: Promise<void>, shutdown: () => Promise<void>, endStreams?: () => Promise<void>): Service;
+export declare function serviceOver(handler: ChannelHandler, ready: Promise<void>, shutdown: () => Promise<void>, endStreams?: () => Promise<void>, webhooks?: WebhookRegistry): Service;
 /** What {@link serveAgent} needs beyond an opened agent. */
 export interface ServeOptions {
     /** Called when a long connection ends on its own — a dropped socket-mode channel, say. */
@@ -69,7 +95,20 @@ export interface ServeOptions {
 /** What the assembly serves. */
 export interface ServableAgent {
     agent: Agent;
-    /** The definition's directory: the agent's working directory. */
+    /** The instance's secrets: what its webhook channels are pointed with. */
+    secrets: Readonly<Record<string, string>>;
+    /** The configuration's part a serve reads: where the platforms reach it, and the URLs a person set there. */
+    config: {
+        http?: {
+            publicUrl?: string;
+        };
+        channels?: Readonly<Record<string, {
+            app?: {
+                url?: string;
+            };
+        }>>;
+    };
+    /** The project directory the instance's `.secrets/` belong to. */
     agentDir: string;
     /** Where durable state lives (channel state, schedule fires, wake-ups). */
     stateRoot: string;
@@ -78,4 +117,3 @@ export interface ServableAgent {
 }
 /** The assembly itself: channels, schedules and long connections, composed into one handler. */
 export declare function serveAgent(opened: ServableAgent, options?: ServeOptions): Promise<ServedAgent>;
-export {};

package/dist/service.js

@@ -4,16 +4,19 @@ import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Scope from "effect/Scope";
-import { mountChannels } from "./channels/discover.js";
-import { text } from "./channels/respond.js";
+import { channelIngress, mountChannels, } from "./channels/discover.js";
 import { parseRouteKey, router } from "./channels/router.js";
 import { serveHandler, totalFetch } from "./channels/serve.js";
+import { pendingWebhooks, registerOwnWebhooks, webhookKinds, webhookPath, } from "./channels/webhooks.js";
+import { addressedTo, onReached, readReached } from "./channels/webhook-evidence.js";
+import { channelStateDir } from "./channels/context.js";
 import { portCleanup } from "./effect-port.js";
 import { API_PREFIX } from "./http/contract.js";
 import { apiHandler, isApiPath } from "./http/server.js";
 import { log } from "./log.js";
 import { once } from "./once.js";
 import { createScheduler } from "./schedule/scheduler.js";
+import { stripTrailingSlashes } from "./strip-edges.js";
 /** Default wait for a channel's `closed` before reporting it stuck. */
 const CLOSE_DEADLINE_MS = 5_000;
 /** One deadline for all connections; a failed close must not hide a sibling that is still running. */
@@ -41,8 +44,11 @@ function closeWithin(runs, names, deadlineMs) {
 }
 /** The port a serve binds when neither a flag, `PORT` (start only) nor `http.port` names one. */
 export const DEFAULT_HTTP_PORT = 8787;
-/** Mount the channels and the health check. */
-export function routesFor(agent, stateRoot, channels) {
+/**
+ * Mount the channels and the health check: JSON, `{ status, webhooks }`, each webhook channel only by name and outcome
+ * (SPEC.md §9.1), since it is public; a step and its reasons are in the log.
+ */
+export function routesFor(agent, stateRoot, channels, webhooks = () => []) {
     const { routes, longConnections, routeChannels } = mountChannels(channels, agent, stateRoot);
     for (const key of Object.keys(routes)) {
         if (isApiPath(parseRouteKey(key).path)) {
@@ -50,7 +56,10 @@ export function routesFor(agent, stateRoot, channels) {
         }
     }
     let ready = longConnections.length === 0;
-    const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
+    const health = () => Response.json({
+        status: ready ? "ok" : "starting",
+        webhooks: webhooks().map(({ channel, outcome }) => ({ channel, outcome })),
+    }, { status: ready ? 200 : 503 });
     const probed = Object.keys(routes).some((key) => {
         const entry = parseRouteKey(key);
         return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
@@ -78,16 +87,96 @@ export function startSchedules(agent, stateRoot, schedules, options = {}) {
         log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}`);
     return scheduler;
 }
+/** The channels whose platform lets only a person set the URL (SPEC.md §8): Slack, and Lark without its config API. */
+const PERSON_SET = ["slack", "lark"];
+/** Nothing to point: a serve with no webhook channel. */
+const NONE = Object.freeze([]);
+const NO_WEBHOOKS = { list: () => NONE, register: async () => [], dispose: () => { } };
+/**
+ * The webhook channels among `kinds`, registered with `env`, the instance's own secrets, at `publicUrl` unless a call
+ * names another base. Each call waits for the one before it, so two never interleave their platform calls.
+ */
+function webhookRegistry(kinds, env, publicUrl, confirmation, options = {}) {
+    // One array, replaced in place: a Service is spread into the objects that extend it, and each keeps reading this.
+    const current = pendingWebhooks(kinds);
+    const replace = (next) => current.splice(0, current.length, ...next);
+    let previous = Promise.resolve();
+    let base;
+    // A URL only a person sets is confirmed by the platform reaching it: told as it happens, or read from the record.
+    const confirmed = (kind, address, at) => {
+        const path = webhookPath(kind);
+        if (confirmation.appUrl(kind) === `${at}${path}`)
+            return true;
+        if (address === undefined)
+            return false;
+        if (addressedTo(address, at, path))
+            return true;
+        log.warn(`[fastagent] ${kind}: the platform reached this instance at ${address}, not ${at}${path}`);
+        return false;
+    };
+    const confirm = (registrations, at) => registrations.map((entry) => {
+        const kind = entry.channel;
+        if (at === undefined || entry.outcome !== "manual" || !PERSON_SET.includes(kind))
+            return entry;
+        if (!confirmed(kind, readReached(confirmation.stateDir(kind)), at))
+            return entry;
+        return { channel: entry.channel, outcome: "registered", url: `${at}${webhookPath(kind)}` };
+    });
+    const stops = kinds
+        .filter((kind) => PERSON_SET.includes(kind))
+        .map((kind) => onReached(confirmation.stateDir(kind), (address) => {
+        const index = current.findIndex((entry) => entry.channel === kind);
+        const entry = current[index];
+        if (base === undefined || entry?.outcome !== "manual" || !confirmed(kind, address, base))
+            return;
+        current[index] = { channel: kind, outcome: "registered", url: `${base}${webhookPath(kind)}` };
+    }));
+    return {
+        list: () => current,
+        register(baseUrl) {
+            if (baseUrl !== undefined && !/^https?:\/\/[^/?#\s]+/.test(baseUrl)) {
+                return Promise.reject(new Error(`registerWebhooks: ${JSON.stringify(baseUrl)} is not an absolute http(s) URL`));
+            }
+            const target = baseUrl ?? publicUrl;
+            const at = target === undefined ? undefined : stripTrailingSlashes(target);
+            const run = previous.then(async () => {
+                base = at;
+                replace(pendingWebhooks(kinds));
+                if (at === undefined && kinds.length > 0) {
+                    log.info(`[fastagent] webhooks: no http.publicUrl, so nothing points ${kinds.join(", ")} at this instance`);
+                }
+                replace(confirm(await registerOwnWebhooks(at, kinds, env, options), at));
+                return [...current];
+            });
+            previous = run.catch(() => { });
+            return run;
+        },
+        dispose: () => {
+            for (const stop of stops)
+                stop();
+        },
+    };
+}
+/** The webhook channels of an opened agent, to be pointed at `http.publicUrl` or at a URL the host names. */
+export function webhooksOf(opened) {
+    const kinds = webhookKinds([...opened.channels].map(([name, module]) => ({ name, ingress: channelIngress(module) })));
+    return webhookRegistry(kinds, opened.secrets, opened.config.http?.publicUrl, {
+        stateDir: (kind) => channelStateDir(opened.stateRoot, kind),
+        appUrl: (kind) => opened.config.channels?.[kind]?.app?.url,
+    });
+}
 /**
  * A Service over `handler`: answered in process, or served on a server of its own. `endStreams` ends what would hold
  * the server's close open (a Caller watching events), and `shutdown` stops the rest once the server has.
  */
-export function serviceOver(handler, ready, shutdown, endStreams = async () => { }) {
+export function serviceOver(handler, ready, shutdown, endStreams = async () => { }, webhooks = NO_WEBHOOKS) {
     let listener;
     let closing;
     const fetch = totalFetch(handler);
     return {
         fetch,
+        registerWebhooks: (baseUrl) => closing !== undefined ? Promise.reject(new Error("the service is closed")) : webhooks.register(baseUrl),
+        webhooks: webhooks.list(),
         listen(port, host) {
             if (closing !== undefined)
                 return Promise.reject(new Error("the service is closed"));
@@ -95,7 +184,17 @@ export function serviceOver(handler, ready, shutdown, endStreams = async () => {
                 return Promise.reject(new Error("the service is already listening"));
             const current = serveHandler(handler, { port, ...(host === undefined ? {} : { host }) });
             listener = current;
-            return current.listening.catch(async (error) => {
+            return current.listening.then((bound) => {
+                // After ready: a host may route to the instance only once its health check passes, and a platform verifies
+                // the URL as it is set. In the background, so the port is answered without waiting for a platform.
+                // A ready that fails is the failure its awaiter reports: nothing is registered for a serve that never was.
+                void ready.then(() => closing === undefined
+                    ? webhooks
+                        .register()
+                        .catch((error) => log.error(`[fastagent] webhook registration failed: ${String(error)}`))
+                    : undefined, () => { });
+                return bound;
+            }, async (error) => {
                 // A bind that failed holds nothing once its scope is closed, so the service may listen again, elsewhere.
                 if (listener === current)
                     listener = undefined;
@@ -108,7 +207,7 @@ export function serviceOver(handler, ready, shutdown, endStreams = async () => {
             closing ??= (async () => {
                 // The server first, so nothing new reaches what stops after it; each step runs, and every failure is said.
                 const failures = [];
-                for (const step of [endStreams, () => listener?.close(), shutdown]) {
+                for (const step of [endStreams, () => listener?.close(), shutdown, webhooks.dispose]) {
                     await Promise.resolve()
                         .then(step)
                         .catch((error) => failures.push(error));
@@ -125,7 +224,8 @@ export function serviceOver(handler, ready, shutdown, endStreams = async () => {
 export async function serveAgent(opened, options = {}) {
     const { agent, agentDir, stateRoot, schedules } = opened;
     const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
-    const routed = routesFor(agent, stateRoot, opened.channels);
+    const webhooks = webhooksOf(opened);
+    const routed = routesFor(agent, stateRoot, opened.channels, webhooks.list);
     // Composed BEFORE anything starts.
     const channels = router(routed.routes);
     const api = options.apiKeys?.length ? apiHandler(agent, { keys: options.apiKeys }) : undefined;
@@ -200,7 +300,7 @@ export async function serveAgent(opened, options = {}) {
             // The rejection is still delivered to callers that await ready.
             ready.catch(() => { });
             return {
-                ...serviceOver(handler, ready, close, async () => api?.endStreams()),
+                ...serviceOver(handler, ready, close, async () => api?.endStreams(), webhooks),
                 routes: routed.routes,
                 agentDir,
                 channels: { routes: routed.routeChannels, longConnections: names },

package/dist/serving-command.d.ts

@@ -8,3 +8,13 @@ export declare function markDevServe(env?: NodeJS.ProcessEnv): void;
 /** For a command that is never `dev` (`start`, `deploy`), run from a shell or a tool that a `dev` process spawned. */
 export declare function unmarkDevServe(env?: NodeJS.ProcessEnv): void;
 export declare function servedByDev(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Who runs an instance, as an open is told: `dev` serves it, a deployed box (the release manifest's variable) runs it,
+ * on AgentCore. The CLI reads its own process's variables for these (`runsAsIn`); an app's instance is none of them.
+ */
+export interface RunsAs {
+    dev: boolean;
+    deployed: boolean;
+    agentcore: boolean;
+}
+export declare const NOT_HOSTED: RunsAs;

package/dist/serving-command.js

@@ -14,3 +14,4 @@ export function unmarkDevServe(env = process.env) {
 export function servedByDev(env = process.env) {
     return env[DEV_SERVE_ENV] === "1";
 }
+export const NOT_HOSTED = { dev: false, deployed: false, agentcore: false };