@fastagent-sh/fastagent 0.21.1 → 0.22.0

package/README.md

@@ -16,12 +16,12 @@
   <sub>— the agent harness &amp; multi-provider LLM API under the hood</sub>
 </p>
 
-A file-defined agent directory can become a live service. FastAgent takes it out of the terminal and serves it in your Next/Astro app, Telegram, GitHub/webhook events, an API endpoint, or your own channel.
+A file-defined agent directory can become a live service. FastAgent takes it out of the terminal and serves it in your Next/Astro app, Telegram, Slack, Feishu, an API endpoint, or your own channel.
 
 Leave the terminal. Become a live service.
 
 - **Add it to your app** — one route, your auth, your database, your host.
-- **Run it as a live service** — Telegram support, GitHub PR review, webhook handler, API endpoint, or custom channel.
+- **Run it as a live service** — Telegram, Slack or Feishu bot, webhook handler, API endpoint, or custom channel.
 
 FastAgent is not a new agent-authoring DSL. You bring the existing definition and project layout; FastAgent provides the serving runtime and adapters around it.
 
@@ -37,8 +37,8 @@ FastAgent is the missing bridge from local agent directory to live service.
 
 ## Features
 
-- **Vibe first — a directory is an agent.** Point FastAgent at the `AGENTS.md` + `skills/` you already vibed in a coding agent. Markdown instructions, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite.
-- **Channels.** Serve the same agent as a GitHub PR reviewer, a Telegram bot, a Feishu or Lark bot, an HTTP/SSE endpoint, or your own adapter: verified webhooks, streaming replies, group-aware.
+- **Vibe first — add a `fastagent/` folder to any project.** The agent is that folder; the project around it is what it works on, and the project's `AGENTS.md` is its context. Markdown instructions, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite.
+- **Channels.** Serve the same agent as a Telegram bot, a Slack app, a Feishu or Lark bot, an HTTP/SSE endpoint, or your own adapter: verified webhooks, streaming replies, group-aware.
 - **Models, tools & skills.** Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from `tools/` (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source [pi](https://github.com/earendil-works/pi) harness.
 - **App embedding — your stack, we plug in.** Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call `invoke` like any function from your own code — your auth, your database, your infra. FastAgent composes with your app, never owns it.
 - **Deploy anywhere.** No application build step — the directory is the deployable unit. `fastagent deploy docker|fly|railway|agentcore` generates the container + target config and a runbook (`--run` drives it to completion). Local Docker gets user-owned Compose + durable state; optional `--tunnel` adds an ephemeral Quick Tunnel service for webhook channels; AWS Bedrock AgentCore gets a one-stack CloudFormation topology (webhooks via a forwarder Lambda, schedules via EventBridge). Durable ingress remains yours.
@@ -102,7 +102,7 @@ For production-style local serving:
 fastagent start
 ```
 
-There is no FastAgent build step: the directory is the agent.
+There is no FastAgent build step: the agent folder is the deployable unit.
 
 ## Embed in an app
 
@@ -150,7 +150,7 @@ const agent = createPiAgent({
 | [Embedding](https://fastagent.sh/docs/embedding/) | Use FastAgent as a library inside your own app |
 | [Channels](https://fastagent.sh/docs/channels/) | Add webhook/bot channels |
 | [Deploy](https://fastagent.sh/docs/deploy/) | Ship the directory to Fly, Railway, or any Docker host |
-| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) / [Slack](https://fastagent.sh/docs/slack/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
+| [Telegram](https://fastagent.sh/docs/telegram/) / [Slack](https://fastagent.sh/docs/slack/) / [Feishu and Lark](https://fastagent.sh/docs/feishu/) | First-party channel guides |
 | [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
 | [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
 | [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
@@ -181,9 +181,9 @@ you register a custom provider.
 | Mounting | `createInvokeHandler`, `Routes`, `ChannelHandler` | Reference implementation, pre-1.0 |
 | Node binding | `nodeListener`, `serveNode` (from `/node`) | The one runtime-specific piece; see below |
 | pi assembly | `createPiAgentFromDir`, `createPiAgentFromDefinition`, `createPiAgent` | Usable now, may tighten before 1.0 |
-| Tool/channel authoring | `defineTool`, `z`, `defineSchedule`, `ChannelModule` | Usable now, may tighten before 1.0 |
+| Tool/channel authoring | `defineTool`, `z`, `defineRoutine`, `ChannelModule` | Usable now, may tighten before 1.0 |
 | Injection ports | `PiSessionRecordStore`, `piSessionRecordStore`, `piInMemorySessionRecordStore`, `Lease`, `Provider` | Public because options reference them |
-| Not exported | The assembly's parts — `router`, `createControlPlane`, `loadTools`/`loadChannels`/`loadSchedules`, `createScheduler` — and prompt/config internals | `createAgentService` does this; no compatibility promise |
+| Not exported | The assembly's parts — `router`, `createControlPlane`, `loadTools`/`loadChannels`/`loadRoutines`, `createScheduler` — and prompt/config internals | `createAgentService` does this; no compatibility promise |
 
 Subpath entry points (`./package.json` is also exported, for tools that read the version):
 
@@ -191,7 +191,6 @@ Subpath entry points (`./package.json` is also exported, for tools that read the
 - `@fastagent-sh/fastagent/node` — the engine-neutral pieces that need a Node runtime: `mountAgentService` (the assembly), `serveNode` / `nodeListener` (the `node:http` ↔ Fetch binding);
 - `@fastagent-sh/fastagent/session` — the engine-neutral session-control contract (types and error codes);
 - `@fastagent-sh/fastagent/pi` — the pi reference implementation;
-- `@fastagent-sh/fastagent/github` — GitHub webhook channel;
 - `@fastagent-sh/fastagent/telegram` — Telegram bot channel;
 - `@fastagent-sh/fastagent/slack` — Slack Events API bot channel;
 - `@fastagent-sh/fastagent/feishu` — canonical Feishu bot channel (飞书, open.feishu.cn);
@@ -205,9 +204,7 @@ test/    vitest suite (faux models by default) + reusable SPEC conformance
 docs/    user docs, SPEC, and maintainer design notes
 ```
 
-Single package, likely long-term; subpath exports (not sibling packages) are the module boundary.
-A `packages/` workspace split is deliberately deferred until a second published artifact with
-independent dependencies/versioning actually exists.
+One package; subpath exports are the module boundary.
 
 ## Status
 

package/dist/agent.d.ts

@@ -1,7 +1,6 @@
 /**
- * Agent Handler protocol v0.1 — the engine-neutral contract (docs/SPEC.md). Pure types, zero
- * dependencies. Importing any engine implementation here is forbidden (`@earendil-works/pi-*` may
- * only appear under engines/).
+ * Agent Handler protocol v0.1 — the engine-neutral contract (docs/SPEC.md). Pure types: importing an engine here is
+ * forbidden (`@earendil-works/pi-*` may only appear under engines/).
  */
 export type Json = null | boolean | number | string | Json[] | {
     [k: string]: Json;
@@ -15,27 +14,25 @@ export interface Prompt {
     text: string;
     images?: ImageRef[];
 }
-/** Invocation scope. Core keeps only the `session` anchor; other fields are extensions (SPEC §8). */
 export interface Scope {
     /** Opaque session anchor: turns of the same logical conversation MUST reuse the same value. */
     session: string;
-    /** EXTENSION (SPEC §8): the session this one branched from — a channel sets it when the place it
-     *  is invoking for was born out of another place (a thread opened in a room). Read ONLY when
-     *  `session` does not exist yet: an engine that understands it seeds the NEW session from the
-     *  parent once, at creation; after that the field is ignored, and an engine that does not
-     *  understand it ignores it entirely (the session starts empty, yesterday's behavior). */
+    /**
+     * EXTENSION (SPEC §8): the session this one branched from — a channel sets it when the place it is invoking for was
+     * born out of another place (a thread opened in a room).
+     */
     parentSession?: string;
-    /** EXTENSION (SPEC §8): opaque markers that MAY locate the branch point inside `parentSession` —
-     *  e.g. platform message ids its transcript embeds. Best-effort by design: the first marker found
-     *  in the parent's transcript wins, and no match falls back to the parent's present. Meaningless
-     *  without `parentSession`. */
+    /**
+     * EXTENSION (SPEC §8): opaque markers that MAY locate the branch point inside `parentSession` — e.g. platform
+     * message ids its transcript embeds.
+     */
     branchHints?: string[];
 }
 export type AgentEvent = {
     type: "text";
     delta: string;
 }
-/** Model reasoning, streamed live. Process, NOT the answer: consumers MUST NOT fold it into the final text. */
+/** Model reasoning, streamed live. */
  | {
     type: "thinking";
     delta: string;
@@ -50,10 +47,10 @@ export type AgentEvent = {
     isError: boolean;
     content: Json;
 }
-/** Advisory, non-terminal (engines MAY emit it): a transient internal failure scheduled a retry
- *  with backoff — the turn is still alive. Explains a quiet gap that would otherwise read as a
- *  hang; deliberately unclosed — the next event is its closure. Terminal consumers ignore it
- *  (SPEC MUST 4). */
+/**
+ * Advisory, non-terminal (engines MAY emit it): a transient internal failure scheduled a retry with backoff — the
+ * turn is still alive.
+ */
  | {
     type: "retrying";
     attempt: number;
@@ -61,14 +58,12 @@ export type AgentEvent = {
     delayMs: number;
     reason: string;
 }
-/** Terminal: success. `data` is attached only when the engine produces a structured result. */
+/** Terminal: success. */
  | {
     type: "completed";
     data?: Json;
 }
-/** Terminal: failure. `retryable` means it is worth re-sending with the same session. `code` is the
- *  optional machine-readable failure subdivision (SPEC §8) — a stable discriminator a consumer can branch
- *  on without parsing `details` (human-facing prose). */
+/** Terminal: failure. */
  | {
     type: "failed";
     details: string;
@@ -76,27 +71,19 @@ export type AgentEvent = {
     code?: string;
 };
 /**
- * The `failed.code` (SPEC §8 failure subdivision) the reference engine sets when a turn is rejected because
- * the session is BUSY — another turn is already in flight, so THIS one never started and is replay-safe.
- * It lives in the contract (a code VALUE, not an engine import) so a neutral consumer — the scheduler,
- * which re-fires a busy wake-up but not one whose turn may have run side effects — branches on it without
- * text-matching `details` or reaching into the engine. An internal fastagent seam (engine ↔ scheduler),
- * not a public cross-engine mandate.
+ * The `failed.code` (SPEC §8 failure subdivision) the reference engine sets when a turn is rejected because the
+ * session is BUSY.
  */
 export declare const SESSION_BUSY_CODE = "session_busy";
 /**
- * The `failed.code` set when a run was DELIBERATELY stopped — a control-plane abort, or any
- * engine-level abort it attributes (`stopReason: "aborted"`) — rather than failing on its
- * own. Channels can render cancellation distinctly from an error, and MUST treat it as a settled
- * outcome — durable turn-intent cleanup included — so a deliberate stop is never replayed as a
- * fresh turn on restart. Exported as a constant for the same reason as {@link SESSION_BUSY_CODE}:
- * a consumer that must branch on it should not string-match.
+ * The `failed.code` set when a run was DELIBERATELY stopped. A channel MAY render cancellation distinctly from an
+ * error, and MUST treat it as a settled outcome — durable turn-intent cleanup included — so a deliberate stop is
+ * never replayed as a fresh turn on restart.
  */
 export declare const ABORTED_CODE = "aborted";
 /**
- * One turn = one invoke, returning a single async event stream. The stream MUST terminate with
- * exactly one of completed / failed, or be cancelled by the caller (no terminal event). Any
- * AsyncIterable producer that implements this conforms (interface, not base class).
+ * One turn = one invoke, returning a single async event stream. The stream MUST terminate with exactly one of
+ * `completed` / `failed`, or be cancelled by the caller (no terminal event).
  */
 export interface Agent {
     invoke(scope: Scope, prompt: Prompt): AsyncIterable<AgentEvent>;

package/dist/agent.js

@@ -1,23 +1,15 @@
 /**
- * Agent Handler protocol v0.1 — the engine-neutral contract (docs/SPEC.md). Pure types, zero
- * dependencies. Importing any engine implementation here is forbidden (`@earendil-works/pi-*` may
- * only appear under engines/).
+ * Agent Handler protocol v0.1 — the engine-neutral contract (docs/SPEC.md). Pure types: importing an engine here is
+ * forbidden (`@earendil-works/pi-*` may only appear under engines/).
  */
 /**
- * The `failed.code` (SPEC §8 failure subdivision) the reference engine sets when a turn is rejected because
- * the session is BUSY — another turn is already in flight, so THIS one never started and is replay-safe.
- * It lives in the contract (a code VALUE, not an engine import) so a neutral consumer — the scheduler,
- * which re-fires a busy wake-up but not one whose turn may have run side effects — branches on it without
- * text-matching `details` or reaching into the engine. An internal fastagent seam (engine ↔ scheduler),
- * not a public cross-engine mandate.
+ * The `failed.code` (SPEC §8 failure subdivision) the reference engine sets when a turn is rejected because the
+ * session is BUSY.
  */
 export const SESSION_BUSY_CODE = "session_busy";
 /**
- * The `failed.code` set when a run was DELIBERATELY stopped — a control-plane abort, or any
- * engine-level abort it attributes (`stopReason: "aborted"`) — rather than failing on its
- * own. Channels can render cancellation distinctly from an error, and MUST treat it as a settled
- * outcome — durable turn-intent cleanup included — so a deliberate stop is never replayed as a
- * fresh turn on restart. Exported as a constant for the same reason as {@link SESSION_BUSY_CODE}:
- * a consumer that must branch on it should not string-match.
+ * The `failed.code` set when a run was DELIBERATELY stopped. A channel MAY render cancellation distinctly from an
+ * error, and MUST treat it as a settled outcome — durable turn-intent cleanup included — so a deliberate stop is
+ * never replayed as a fresh turn on restart.
  */
 export const ABORTED_CODE = "aborted";

package/dist/atomic-write.d.ts

@@ -1,23 +1,19 @@
 /**
  * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
  *
- * The temp name is fixed (`<path>.tmp`). It holds wherever one process writes one state root: a
- * deployment runs one container, `dev`'s supervisor respawns its worker only after the old one has
- * EXITED (dev-supervisor.ts), and these writes are synchronous, so an exited process has none in
- * flight. Slack's onboarding state is the one file with two writers — `add slack`, and the
- * config-token rotation inside `--tunnel` webhook registration — so a second terminal running
- * `add slack --replace-config` can overlap a live `dev --tunnel`. Kept fixed anyway: that window is
- * a single write at tunnel startup, its repair is the `add slack --replace-config` the registration
- * failure already prints, and the fixed name is the seam several channel tests use to inject a write
- * failure by occupying that path with a directory. Revisit for a writer that is neither rare nor
- * self-repairing.
+ * The temp name is FIXED (`<path>.tmp`), which rests on one process writing one state root: a deployment runs one
+ * container, `dev`'s supervisor respawns its worker only after the old one has exited, and these writes are
+ * synchronous. Slack's onboarding state is the documented exception (`add slack` plus the config-token rotation at
+ * `--tunnel` startup); it stays fixed because that window is one rare, self-repairing write, and because the fixed
+ * name is the seam channel tests use to inject a write failure. Revisit before adding a writer that is neither.
  *
- * `mode` is applied to the temp first, so the content is never briefly world-readable.
+ * `mode` is applied to the temp first, so the content is never briefly world-readable, and the `chmod` is not
+ * redundant with it: `writeFileSync` honours `mode` only when it CREATES the file, so a temp left behind by a crashed
+ * writer would keep its old, possibly looser permissions.
  *
- * The `chmod` is NOT redundant with the `mode` option: `writeFileSync` applies `mode` only when it
- * CREATES the file, so a temp left behind by a crashed writer keeps its old, possibly loose
- * permissions and the rename publishes them (verified: 0644 survives a `{ mode: 0o600 }` write).
- * It runs on the temp, before the rename — the final path is then never observable with the wrong
- * permissions, which a chmod after the rename cannot promise.
+ * `sharedWriters` is for a file SEVERAL processes may write at once (the merged models file, content-addressed, so
+ * every writer writes the same bytes): each writes its own temp, and the last rename wins. A fixed temp there would
+ * let one writer's rename take the other's file and fail it with ENOENT. No test exercises that race: it needs two
+ * processes renaming within the same moment, which a test cannot arrange without being flaky.
  */
-export declare function writeFileAtomic(path: string, data: string | Buffer, mode?: number): void;
+export declare function writeFileAtomic(path: string, data: string | Buffer, mode?: number, sharedWriters?: boolean): void;

package/dist/atomic-write.js

@@ -1,39 +1,28 @@
-/**
- * One spelling of "a reader sees the whole file or none of it", after five copies of it drifted
- * apart: two identical, three with different temp names and different permission handling.
- *
- * Synchronous, and there is no async sibling: every caller either sits on a path where a KB-sized
- * write must complete BEFORE a transport ACK (channel state — an ACKed delivery is not redelivered)
- * or on a CLI/startup path where the cost is not observable. An async spelling would buy one of them
- * nothing and cost this module a second set of rules to keep true.
- */
+/** One spelling of "a reader sees the whole file or none of it", for every state writer. */
 import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 /**
  * Write a file so a reader sees the whole thing or nothing: same-directory temp, then rename.
  *
- * The temp name is fixed (`<path>.tmp`). It holds wherever one process writes one state root: a
- * deployment runs one container, `dev`'s supervisor respawns its worker only after the old one has
- * EXITED (dev-supervisor.ts), and these writes are synchronous, so an exited process has none in
- * flight. Slack's onboarding state is the one file with two writers — `add slack`, and the
- * config-token rotation inside `--tunnel` webhook registration — so a second terminal running
- * `add slack --replace-config` can overlap a live `dev --tunnel`. Kept fixed anyway: that window is
- * a single write at tunnel startup, its repair is the `add slack --replace-config` the registration
- * failure already prints, and the fixed name is the seam several channel tests use to inject a write
- * failure by occupying that path with a directory. Revisit for a writer that is neither rare nor
- * self-repairing.
+ * The temp name is FIXED (`<path>.tmp`), which rests on one process writing one state root: a deployment runs one
+ * container, `dev`'s supervisor respawns its worker only after the old one has exited, and these writes are
+ * synchronous. Slack's onboarding state is the documented exception (`add slack` plus the config-token rotation at
+ * `--tunnel` startup); it stays fixed because that window is one rare, self-repairing write, and because the fixed
+ * name is the seam channel tests use to inject a write failure. Revisit before adding a writer that is neither.
  *
- * `mode` is applied to the temp first, so the content is never briefly world-readable.
+ * `mode` is applied to the temp first, so the content is never briefly world-readable, and the `chmod` is not
+ * redundant with it: `writeFileSync` honours `mode` only when it CREATES the file, so a temp left behind by a crashed
+ * writer would keep its old, possibly looser permissions.
  *
- * The `chmod` is NOT redundant with the `mode` option: `writeFileSync` applies `mode` only when it
- * CREATES the file, so a temp left behind by a crashed writer keeps its old, possibly loose
- * permissions and the rename publishes them (verified: 0644 survives a `{ mode: 0o600 }` write).
- * It runs on the temp, before the rename — the final path is then never observable with the wrong
- * permissions, which a chmod after the rename cannot promise.
+ * `sharedWriters` is for a file SEVERAL processes may write at once (the merged models file, content-addressed, so
+ * every writer writes the same bytes): each writes its own temp, and the last rename wins. A fixed temp there would
+ * let one writer's rename take the other's file and fail it with ENOENT. No test exercises that race: it needs two
+ * processes renaming within the same moment, which a test cannot arrange without being flaky.
  */
-export function writeFileAtomic(path, data, mode) {
+export function writeFileAtomic(path, data, mode, sharedWriters = false) {
     mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp`;
+    const tmp = sharedWriters ? `${path}.${process.pid}.${randomUUID()}.tmp` : `${path}.tmp`;
     try {
         writeFileSync(tmp, data, mode === undefined ? undefined : { mode });
         if (mode !== undefined)
@@ -45,8 +34,8 @@ export function writeFileAtomic(path, data, mode) {
             rmSync(tmp, { force: true });
         }
         catch {
-            // `force` only forgives ENOENT: if the temp is a directory, rmSync throws its own error and
-            // would replace the write failure that actually explains what went wrong.
+            // `force` only forgives ENOENT: if the temp is a directory, rmSync throws its own error and would replace the
+            // write failure that actually explains what went wrong.
         }
         throw error;
     }

package/dist/bind.d.ts

@@ -1,34 +1,24 @@
-/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". No other DNS name — a
- *  bind address must be an address of THIS machine, and resolving one is not this module's job. */
+/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". */
 export declare function isBindAddress(host: string): boolean;
 /**
- * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is
- * already an address. Applied where a value ENTERS (the flag, `http.host`), so nothing downstream ever
- * holds a name — not deferring the resolution but removing it, which is the module's whole point.
- *
- * Two things go wrong otherwise, and both are silent. `server.listen` hands the name to `dns.lookup`,
- * which picks ONE of 127.0.0.1/::1 by rules we do not control — so what got bound is unknown here. And
- * `clientHost` would then write that NAME into control.json and the copyable curl, where a consumer
- * resolves it again, possibly to the other one.
+ * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is already an address.
  */
 export declare function bindAddress(host: string): string;
 /**
- * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and
- * answers on loopback too; `loopback` is this machine only; `specific` is one interface, reachable
- * only as itself. Loopback covers the whole reserved range (127/8, ::1) — a `127.0.0.2` bind is no
- * more LAN-reachable than `127.0.0.1`.
+ * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and answers on
+ * loopback too; `loopback` is this machine only; `specific` is one interface, reachable only as itself.
  */
 export declare function classifyBind(host: string | undefined): "wildcard" | "loopback" | "specific";
 /**
- * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name
- * resolves to (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that
- * way. cloudflared dials by name, so `--tunnel` needs this question, not `classifyBind`'s reach.
+ * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name resolves to
+ * (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that way. That is why this is not
+ * {@link classifyBind}'s reach question: cloudflared dials by name, so `--tunnel` needs this one.
  */
 export declare function answersLocalhost(host: string | undefined): boolean;
-/** How to NAME a bind in a message: the wildcard is every interface, so calling it one address would
- *  understate it; anything else is dialable as itself. THE renderer — the ready lines, the
- *  already-in-use refusal and the generic bind failure all read a bind through this one, so a reader
- *  never sees the same bind described two ways. */
+/**
+ * How to NAME a bind in a message: the wildcard is every interface, so calling it one address would understate it;
+ * anything else is dialable as itself.
+ */
 export declare function bindLabel(host: string | undefined, port: number): string;
-/** The address a local client should dial for a serve bound to `host` (control.json, the ready log). */
+/** The address a local client should dial for a serve bound to `host` (the ready log's curl). */
 export declare function clientHost(host: string | undefined): string;

package/dist/bind.js

@@ -1,41 +1,32 @@
 /**
- * The ONE reading of a bind address, shared by everything that parses, binds, warns about, or ships
- * one (the CLI flag, `http.host` validation, the Node host, the deploy pre-flight). Engine- and
- * host-neutral on purpose: a bind address is a plain value, and two parsers of it would disagree.
+ * The ONE reading of a bind address, shared by everything that parses, binds, warns about, or ships one (the CLI flag, the
+ * Node host, the startup report).
  */
 import { isIP } from "node:net";
-/** Lowercase, unbracketed, IPv4-mapped IPv6 reduced to its IPv4 form — the form the checks below read.
- *  Brackets come off only as a PAIR: a half-bracketed `[::1` must stay invalid, not become an address. */
+/**
+ * Lowercase, unbracketed, IPv4-mapped IPv6 reduced to its IPv4 form — the form the checks below read. Brackets come
+ * off only as a PAIR: a half-bracketed `[::1` must stay invalid, not become an address.
+ */
 function normalize(host) {
     return host
         .toLowerCase()
         .replace(/^\[(.+)]$/, "$1")
         .replace(/^::ffff:/, "");
 }
-/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". No other DNS name — a
- *  bind address must be an address of THIS machine, and resolving one is not this module's job. */
+/** A bindable host: an IP literal (v4/v6, brackets optional) or "localhost". */
 export function isBindAddress(host) {
     const h = normalize(host);
     return h === "localhost" || isIP(h) !== 0;
 }
 /**
- * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is
- * already an address. Applied where a value ENTERS (the flag, `http.host`), so nothing downstream ever
- * holds a name — not deferring the resolution but removing it, which is the module's whole point.
- *
- * Two things go wrong otherwise, and both are silent. `server.listen` hands the name to `dns.lookup`,
- * which picks ONE of 127.0.0.1/::1 by rules we do not control — so what got bound is unknown here. And
- * `clientHost` would then write that NAME into control.json and the copyable curl, where a consumer
- * resolves it again, possibly to the other one.
+ * The ADDRESS form of an accepted bind value: `localhost` becomes `127.0.0.1`, everything else is already an address.
  */
 export function bindAddress(host) {
     return normalize(host) === "localhost" ? "127.0.0.1" : host;
 }
 /**
- * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and
- * answers on loopback too; `loopback` is this machine only; `specific` is one interface, reachable
- * only as itself. Loopback covers the whole reserved range (127/8, ::1) — a `127.0.0.2` bind is no
- * more LAN-reachable than `127.0.0.1`.
+ * How far a bind address reaches: `wildcard` (unset or all-interfaces) reaches every interface and answers on
+ * loopback too; `loopback` is this machine only; `specific` is one interface, reachable only as itself.
  */
 export function classifyBind(host) {
     if (host === undefined)
@@ -48,9 +39,9 @@ export function classifyBind(host) {
     return "specific";
 }
 /**
- * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name
- * resolves to (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that
- * way. cloudflared dials by name, so `--tunnel` needs this question, not `classifyBind`'s reach.
+ * Does a serve bound to `host` answer a dial of the NAME `localhost`? Only the addresses that name resolves to
+ * (127.0.0.1 / ::1) and a wildcard bind do — `127.0.0.2` is loopback yet unreachable that way. That is why this is not
+ * {@link classifyBind}'s reach question: cloudflared dials by name, so `--tunnel` needs this one.
  */
 export function answersLocalhost(host) {
     if (classifyBind(host) === "wildcard")
@@ -58,14 +49,14 @@ export function answersLocalhost(host) {
     const h = normalize(host);
     return h === "localhost" || h === "127.0.0.1" || h === "::1";
 }
-/** How to NAME a bind in a message: the wildcard is every interface, so calling it one address would
- *  understate it; anything else is dialable as itself. THE renderer — the ready lines, the
- *  already-in-use refusal and the generic bind failure all read a bind through this one, so a reader
- *  never sees the same bind described two ways. */
+/**
+ * How to NAME a bind in a message: the wildcard is every interface, so calling it one address would understate it;
+ * anything else is dialable as itself.
+ */
 export function bindLabel(host, port) {
     return classifyBind(host) === "wildcard" ? `port ${port}` : `${clientHost(host)}:${port}`;
 }
-/** The address a local client should dial for a serve bound to `host` (control.json, the ready log). */
+/** The address a local client should dial for a serve bound to `host` (the ready log's curl). */
 export function clientHost(host) {
     if (classifyBind(host) === "wildcard")
         return "127.0.0.1";

package/dist/channel.d.ts

@@ -1,55 +1,33 @@
 /**
- * The Channel contract — the trigger side of the product boundary (core.md §1), beside `agent.ts`
- * (what an engine implements) and `session.ts` (the serving control plane). Pure types, no runtime
- * dependency; importing a host, a framework, or an engine here is forbidden, as in those two.
- *
- * §7 fixes two module forms: a function is a route channel, an object with `connect` is a long
- * connection. An agent directory ships hand-written `channels/*.ts` against them, which is why they
- * live away from the code that serves them — a WebSocket ingress needs `LongConnection` and has no
- * HTTP in it, and a `ChannelModule` import must not drag `node:http` in behind it.
- *
- * How a route table becomes a running server: `channels/serve.ts`.
+ * The Channel contract — the trigger side of the product boundary (core.md §1), beside `agent.ts` (what an engine
+ * implements) and `session.ts` (the serving control plane). Pure types: importing a host, a framework, or an engine
+ * here is forbidden, as in those two.
  */
 import type { Agent } from "./agent.ts";
 import type { SessionControl } from "./session.ts";
-/** A mounted request handler (a channel's fetch, or a plain route like health). Fetch-shaped by
- *  contract (SPEC §11): the one signature every runtime and embedding app already speaks. */
+/** A mounted request handler (a channel's fetch, or a plain route like health). */
 export type ChannelHandler = (req: Request) => Response | Promise<Response>;
-/**
- * This deployment's HTTP surface: route key → handler.
- *
- * A key is `"/path"` (any method) or `"METHOD /path"`, with a LITERAL path — small on purpose, so
- * that "would these two fight over a request?" is string equality rather than a prediction about a
- * matcher, and no channel silently shadows another. `assertRouteKey` in `channels/serve.ts`
- * enforces it; a handler owning a prefix is a `PrefixMount`, never a key.
- */
+/** This deployment's HTTP surface: route key → handler. */
 export type Routes = Record<string, ChannelHandler>;
 /**
- * What the framework hands a channel at mount time: the assembled agent plus the resolved state ROOT
- * (absolute; `FASTAGENT_STATE_DIR` > `<root>/.state`). Channels derive their OWN durable home from
- * it (`<stateRoot>/channels/<kind>/`) — they never anchor on `process.cwd()`. env is the OPERATOR
- * input plane; this context is how the resolved result reaches code (embedders without the agent
- * opener construct it explicitly).
+ * What the framework hands a channel at mount time: the assembled agent plus the resolved state ROOT (absolute;
+ * `FASTAGENT_STATE_DIR` > `<root>/.state`).
  */
 export interface ChannelContext {
     agent: Agent;
     stateRoot: string;
-    /** The serving session-control hub, when the serve wires one (`config.sessionControl`). Channels
-     *  use it for DISPATCH only (the user-facing stop command); observation stays on the data plane. */
+    /** The serving session-control hub: every serve has it, so a stop command reaches the live run through it.
+     *  `config.sessionControl` decides only whether the SAME hub is also published as `/control/*` (and wires its
+     *  write side). Absent only when an embedder mounts a service without one. */
     control?: SessionControl;
 }
 /** A `channels/<name>.ts` route channel: receives mount context and returns its HTTP routes. */
 export type ChannelModule = (ctx: ChannelContext) => Routes;
-/** One logical long connection's lifecycle. `ready` settles after its first usable connection — and
- * when `signal` aborts before one exists it must still settle: resolution then means cancellation, not
- * readiness (the server skips ready-side effects once the signal is aborted; it must never hang).
- * `closed` resolves after abort-driven shutdown and rejects on a terminal connection failure. */
 export interface LongConnection {
     ready: Promise<void>;
     closed: Promise<void>;
 }
-/** A long-connection channel is an explicit module object rather than an HTTP-route factory.
- * The adapter owns reconnects and treats `signal` as its sole shutdown command. */
+/** A long-connection channel is an explicit module object rather than an HTTP-route factory. */
 export interface LongConnectionChannelModule {
     name: string;
     connect(ctx: ChannelContext, signal: AbortSignal): LongConnection;

package/dist/channels/agentcore-limits.d.ts

@@ -1,16 +1,5 @@
-/**
- * The HOST's body ceilings, and the one place they are computed.
- *
- * Lambda Function URLs cap a request at 6 MB, so the forwarder cannot deliver more than that no
- * matter what the adapter accepts; the body arrives base64-encoded (×4/3) inside a JSON envelope, so
- * the ORIGINAL body ceiling is smaller still. This is a real capability difference from a resident
- * host — the GitHub channel's own contract is 25 MiB — which is why `deploy agentcore` states it at
- * plan time rather than letting an oversized payload surface as an opaque 502.
- */
-/**
- * Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion.
- * Enforced by both the public forwarder and the runtime adapter.
- */
+/** The HOST's body ceilings, and the one place they are computed. */
+/** Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion. */
 export declare const MAX_WEBHOOK_BODY_BYTES: number;
 /** Largest complete AgentCore envelope accepted by the runtime adapter. */
 export declare const MAX_ENVELOPE_BYTES: number;

package/dist/channels/agentcore-limits.js

@@ -1,18 +1,7 @@
-/**
- * The HOST's body ceilings, and the one place they are computed.
- *
- * Lambda Function URLs cap a request at 6 MB, so the forwarder cannot deliver more than that no
- * matter what the adapter accepts; the body arrives base64-encoded (×4/3) inside a JSON envelope, so
- * the ORIGINAL body ceiling is smaller still. This is a real capability difference from a resident
- * host — the GitHub channel's own contract is 25 MiB — which is why `deploy agentcore` states it at
- * plan time rather than letting an oversized payload surface as an opaque 502.
- */
+/** The HOST's body ceilings, and the one place they are computed. */
 /** AWS Lambda Function URLs accept request payloads up to 6 MB. */
 const FUNCTION_URL_REQUEST_LIMIT = 6 * 1000 * 1000;
-/**
- * Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion.
- * Enforced by both the public forwarder and the runtime adapter.
- */
+/** Maximum original webhook body after reserving JSON-envelope overhead and base64 expansion. */
 export const MAX_WEBHOOK_BODY_BYTES = Math.floor((FUNCTION_URL_REQUEST_LIMIT * 3) / 4) - (64 << 10);
 /** Largest complete AgentCore envelope accepted by the runtime adapter. */
 export const MAX_ENVELOPE_BYTES = FUNCTION_URL_REQUEST_LIMIT;